Skip to content

fix(cli): keep files received that a host's kept record still lists - #8100

Merged
michaelwang11394 merged 3 commits into
mainfrom
sec-low31a-1117
Nov 17, 2026
Merged

michaelwang11394 merged 3 commits into
mainfrom
sec-low31a-1117

Conversation

@michaelwang11394

Copy link
Copy Markdown
Contributor

What

The CLI keeps a file received when the host app's kept copy of the project's received-files record still lists it, even if .hyperframes/received-files.json no longer does.

  • When HYPERFRAMES_RECEIVED_STATE_FILE names a project as "expected" and the app keeps a copy of that project's record in received-records/ beside the state file, every received-file check reads the record together with each kept entry whose path still holds something.
  • The checks covered are the render rule, publish, add, .env keys, and Studio's rename and history tracking. Only the CLI's own record writes still read the record as written.
  • A kept copy with no list, a doubted one, a link, an oversized one, one that can't be parsed, or one for another project counts every file as received. A copy found only by folder identity counts only when its identity matches the folder.
  • With no state file, no kept copy, or a project the state file doesn't name, nothing changes.

Why

When the app runs an agent in a project, the agent can write inside that project. Text in a received project could steer it to rewrite the record to a shorter or empty list. The app repairs this at its next read of the record, from its kept copy. Until then, the CLI trusted the edited record, so received files read as the person's own for the render rule, publish and the rest.

How

privateProjectFile.ts reads the kept copy at received-records/<sha256 of the state file's path>.json. It caps the read and refuses a link at that path. It adds back each listed entry whose path holds something, checked with lstat, so nothing is followed. Entries are matched with the same normalization the record uses. projectRecords.ts passes the merged lines to Studio's tracking. The format and the identity string (dev:ino:birth time in ns) match what the app writes.

No visible change

Your own projects and projects the app doesn't track behave as before. The CLI removes record entries only for files that are gone, and the app updates its kept copy whenever it changes the record itself, so normal edits, renames and deletes read the same.

Test plan

  • Unit tests added/updated

  • Manual testing performed

  • Documentation updated (if applicable)

  • Comments follow CONTRIBUTING.md "Comments": they say why, not what, and a bug fix says what the code must do and how to reproduce the bug

  • fails without the fix: the 7 new attack tests in privateProjectFile.test.ts and receivedRender.test.ts fail on main's privateProjectFile.ts. They cover:

    • an emptied record while the kept copy lists two files that still exist;
    • one of those files deleted, so only the other stays received;
    • a kept copy with no list;
    • a kept copy that is a link;
    • an unreadable kept copy;
    • a copy matched by identity;
    • the render rule refusing outside files after the record is emptied.
  • Two more tests show no change: no state file, and a project with no kept copy.

  • The received-project, privateProjectFile, render rule, Studio received-record and dotEnv suites pass (109 tests in the two touched files, 498 across the 16 related suites). tsc --noEmit for cli, oxlint, oxfmt --check, the comment ratchet, the citations check and fallow pass.

  • A separate review checked the kept-copy format and identity against the app's writer, and looked for bypasses and regressions.

Not covered here

  • The media-use audio scripts keep their own copy of the received rule. Its replacement, fix(media-use): audio scripts judge a received .env by the CLI's rule #8086, is not merged yet; the same kept-copy check goes into that copy as soon as it lands.
  • A received file renamed after its entry is removed from the record is judged by the record alone until the app's next read. Adding back a kept entry whose file is gone would also flag every normal rename and delete, so the docs state this limit.
  • received-content.json has no kept copy.
  • A process the agent launches can change its own environment, including the state-file variable.
  • Not run: Windows.

When the received-state file names a project as expected and the host
keeps its own copy of that project's record beside the state file, the
received-file checks read the record together with each entry that copy
lists whose path still holds something. A record shortened or emptied
outside the host no longer makes those files read as the person's own.
A kept copy with no list, a doubted one, a link or one that cannot be
read counts every file as received; with no kept copy, nothing changes.
…be read

A kept copy with no list, or one that cannot be read, now counts every
file as received through its own entry, named by the kept copy's path,
instead of hiding the record's lines from Studio's rename and move
tracking. A copy found only by folder identity counts only when its
identity matches the folder, and a copy that disappears mid-read counts
as no copy.
@mintlify

mintlify Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
hyperframes 🟢 Ready View Preview Nov 17, 2026, 6:39 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

@github-actions

Copy link
Copy Markdown
Contributor

Edit accuracy: accurate 267 (base branch 267), smooth 65 of those

The gate passes.
Smoothness is reported in the artifact, not gated. A case fails only if it fails 2 of 3 runs.

Quarantined, measured but not gated (8)

@eddy-heygen eddy-heygen left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(Eddy's agent) Reviewed by Eddy's Claude agent at commit dc009b9.

Verdict: approved, good to ship.

Summary. The CLI used to trust a project's received-files record as written, so a record shortened or emptied from inside the project made received files read as the person's own until the desktop app repaired it. This PR makes every CLI read path (render rule, publish, add, .env, Studio tracking) merge in the entries of the app's kept copy, which lives outside the project, for each entry whose path still holds something, and treats a kept copy that is doubted, list-less, a link, oversized, unparsable or for another project as "every file received". With no state file, an unnamed project or no kept copy, behaviour is unchanged. The stated remainders (file renamed as well as de-listed, agent-launched CLI with the variable unset, the second copy of the rule in the media scripts) are real and are the same gaps the default branch has.

Approved as a partial fix. Every CLI read of the received-files record now also counts the entries of the app's kept copy, which lives outside the project, and a kept copy that cannot be trusted or read makes every file count as received. I read the merge logic myself. Stated remainders, the same gaps the default branch has: a received file that is renamed as well as taken off the list, a CLI started by an agent with the state variable unset, and the second copy of the rule in the media scripts.

Blockers

None.

Non-blockers

  1. packages/cli/src/utils/privateProjectFile.ts:239: A received file that is renamed as well as de-listed is still judged by the edited record. A kept entry is added back only when something is at its exact path (onDisk(join(dir, entry))). If the same writer that shortens the record also moves the file to a new name, the kept entry is skipped, no 'gone' signal is raised (goneFile only looks at merged entries), and the file under its new name reads as the person's own for per-file checks such as publish. The render rule is harder to escape: it refuses while any kept non-media path still holds something, so every kept code path, including the entry page, would have to be vacated. The default branch has the same gap, the desktop app's own repair uses the same 'path still holds something' rule (so the app's next read does not restore such an entry either, contrary to what the docs wording suggests), and the fix criteria allow removal for a file that is really gone or renamed. Remainder, not a regression. To resolve: Follow-up: record removals the CLI itself makes somewhere outside the project (or have the app keep content hashes outside the project) so a kept entry whose file is gone without a known CLI/app removal makes code files read as received. Tighten the docs sentence at docs/packages/cli.mdx:2910-2912 so it does not imply the app's next read repairs this case.
  2. packages/cli/src/utils/privateProjectFile.ts:196: Identity mismatch on a moved project ignores the kept copy instead of failing closed. For a project matched only by device and inode (moved from the path the state file names), a kept copy whose identity string differs from the folder's dev:ino:birth-time returns null and is treated as no copy, so the record as written is trusted. Every other mismatch in the same function returns 'all'. The birth time of a folder can be changed by its owner on some file systems, so a moved project plus a changed birth time plus a shortened record reads as the person's own. This is no stronger than copying the project to a new, unnamed folder, which the default branch already trusts, so it does not reopen the path for a project at its named location (the by-path naming has no identity check, line 181). To resolve: Return 'all' when the state file matched the folder by dev:ino but the kept copy's identity differs, or justify in a comment why inode reuse makes ignoring the right call and add a test for the birth-time-changed case.
  3. packages/cli/src/utils/privateProjectFile.ts:223: Transient read of the kept copy while the app replaces it reads as every file received; no retry and no cache. The app replaces the kept copy by rename. If that lands between the open and the lstat inside readPlainTail (projectRecords.ts:42-47), the read returns null, onDisk is true, and the project reads as all received for that one CLI call: a render at that instant refuses outside files with a message naming the kept copy. The window is very small and the direction is safe. Related cost: the copy (cap 16 MB) is read and parsed on every readRecord call, twice when the state entry carries dev and ino (namings at 180-187 returns the same path twice), with one lstat per kept entry missing from the record. To resolve: Retry the read once before returning 'all'; de-duplicate namings by path; optionally cache the parsed copy by stat key as hostStates does.

What the change needed to do

  • finding-1: When a read finds the project's record missing entries the app's kept copy holds, and those files still exist, the entries count as received again (or the whole project reads as received).: met (packages/cli/src/utils/privateProjectFile.ts:228-242 withEntriesHostKept adds back each kept entry not in the record whose path passes an lstat; readRecord (274-277) applies it to every array-valued record. Test at privateProjectFile.test.ts 'counts entries an emptied record lost' and receivedRender.test.ts:242.)
  • finding-1: The project must never read as the person's own to the CLI between the edit and the app's repair, for a record emptied without touching the listed files.: partly met (Met for CLI processes that carry the state-file variable (privateProjectFile.ts:229-230). Not met for a CLI process started with the variable unset or changed (hostStates returns null at line 141), which the PR states as not covered; that gap exists on main too.)
  • finding-1: The CLI learns the project's state through the state file, and a kept copy that cannot be trusted fails closed.: met (privateProjectFile.ts:194-200 (other project, doubted, no list, non-string entries -> all), 202-208 (unparsable -> all), 217-225 (lstat error other than ENOTDIR, link, device, oversized -> all); 498 turns that into an every-file-received record. Unreadable state file -> all (153-155, 160), unchanged.)
  • finding-1: The CLI's own record writes, under the shared lock, may still remove an entry for a file that is really gone, renamed or replaced.: met (privateProjectFile.ts:320-321 applyRecordChange reads readRecordAsWritten, so kept entries are never written into the project's record by the CLI and legitimate removals stand.)
  • finding-1: Kept-copy format, file name and identity string match what the desktop app writes.: met (Compared by reading the app's ledger writer on its default branch: file name is sha256 of the project path as the state file names it, fields project/identity/files/doubted, identity is dev:ino:birthtimeNs; matches privateProjectFile.ts:185, 194-199, 215-216.)

CI: all checks pass at this commit (the rest are skipped by path).

How this was reviewed: a code-review pass and a security-review pass, by a reviewer agent in an isolated checkout of this commit; I then read the core of the fix and the cited lines myself. Nothing was built or run.

@michaelwang11394
michaelwang11394 added this pull request to the merge queue Nov 17, 2026
Merged via the queue into main with commit 183bf2a Nov 17, 2026
85 checks passed
@michaelwang11394
michaelwang11394 deleted the sec-low31a-1117 branch November 17, 2026 19:22

This branch was successfully deployed

1 active deployment
staging - docs — dc009b9c Deployed Nov 17, 2026 by mintlify[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants