Skip to content

fix(cli): media-use scripts read the host's kept record copy as the CLI does - #8119

Merged
michaelwang11394 merged 1 commit into
mainfrom
sec-low31b-1117
Nov 18, 2026
Merged

michaelwang11394 merged 1 commit into
mainfrom
sec-low31b-1117

Conversation

@michaelwang11394

Copy link
Copy Markdown
Contributor

What

The media-use scripts' copy of the received-files rule now reads the host app's kept copy of a project's record, so it gives the same answer as the CLI. Three follow-ups to the kept-copy check are applied to both the CLI and the copy:

  • A moved project's kept copy whose identity names another folder now counts every file as received. Before, it was ignored.
  • A kept copy that fails its first read is read once more before every file counts as received.
  • A kept copy that the state file names both by path and by dev and ino is read once.

The docs no longer suggest that the app's next read restores a kept entry whose file is gone.

Why

The CLI reads the kept copy, but the media-use copy did not. When a project's record had been emptied outside the app, the audio scripts could treat a received .env as the person's own while the CLI treated it as received. The two must agree.

The follow-ups make the kept-copy check consistent and less fragile:

  • Every other mismatch already counts every file as received. An identity mismatch now does the same.
  • The app can replace a kept copy by renaming a new file over it. A read that overlaps that rename should not count every file as received.
  • Reading the same file twice did no harm, but it was wasted work.

Related work

Follows #8100, which added the kept-copy check to the CLI, and #8086, which added the media-use copy of the rule and its parity test.

How

  • packages/cli/src/media-use/lib/received-env.mjs ports the CLI's kept-copy functions one for one. These are the names per project, the kept-copy read, and the union with kept entries whose path still holds something (checked with lstat, so links are not followed). An unreadable copy adds its own "all received" entry, as it does in the CLI. That includes copies found from nested records.
  • In packages/cli/src/utils/privateProjectFile.ts:
    • keptFilesIn returns "all" on an identity mismatch.
    • hostKeptRecord calls readPlainTail a second time when the first call returns nothing.
    • namings drops a path found by identity when the same path was already found by path.
  • scripts/generate-skill-module-copies.mjs regenerated skills/media-use/scripts/lib/received-env.mjs, and the skills manifest was regenerated with it.

No visible change

Nothing changes on screen or in command output. A host app that keeps record copies now gets the same received-file answers from the media-use audio scripts as from the CLI.

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

The CLI gets tests for a changed identity, a kept copy replaced by rename during its first open, and a copy named by both path and identity being opened once.

The parity test gets these cases with a state file and a kept copy, each checked against both the CLI and the copy:

  • an emptied record whose kept copy lists the file;
  • a kept entry whose file is gone, in two variants: a plain file, and a gone page next to a .env linked outside the project;
  • files: null, a doubted copy, another project's copy and an unparsable copy;
  • a link in place of the kept copy;
  • no kept copy;
  • a moved project whose copy has the folder's identity, and one whose copy has another identity;
  • a nested project's copy;
  • the replace-by-rename retry, and the single read.

A separate test covers the copy's at-or-above mode, which has no CLI equivalent.

fails without the fix: the old received-env.mjs fails 12 of the parity tests. Undoing each CLI follow-up on its own fails its own test. Undoing the same follow-up in the copy fails the matching parity test. Leaving out the nested pass-through fails the nested case.

Runs:

  • privateProjectFile, receivedRender, dotEnv, receivedEnv.parity and terminalText.parity: 185 passed.
  • media-use audio script tests: 267 passed.
  • tsc --noEmit for the CLI, oxlint and oxfmt --check are clean.
  • The comment ratchet, the skill module copy check (check-media-use-copy-parity, 4 passed) and fallow audit all pass.

Not covered:

  • On Linux file systems where Node cannot read a folder's birth time, a moved project's identity never matches its kept copy. Such a project now counts every file as received instead of being judged by its record. Desktop, which writes kept copies, runs on macOS and Windows.
  • Not run: Windows.

…LI does

The media-use copy of the received-files rule now reads the host app's kept
copy of an expected project's record, as the CLI does. It adds back each kept
entry whose path still holds something, checks the folder identity for a
project found only by dev and ino, and counts every file as received when the
copy has no list, is doubted, a link, oversized, unparsable or another
project's.

In both the CLI and the copy:
- a kept copy whose identity names another folder counts every file as
  received instead of being ignored;
- a kept copy that fails its first read, for example because the app replaced
  it mid-read, is read once more before every file counts as received;
- a kept copy named both by path and by dev and ino is read once.

The docs no longer suggest that the app's next read restores a kept entry
whose file is gone.
@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, 10:53 PM

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

@github-actions

Copy link
Copy Markdown
Contributor

Edit accuracy: accurate 271 (base branch 271), smooth 68 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 (0)

Unstable (1)

  • seqplainkeys-none-center-r0-nested-z100: tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo true, teleport true / tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo true, teleport true / tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo true, teleport true

@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 0df23d2.

Verdict: approved, good to ship.

Summary. The media-use scripts' copy of the "received project" rule did not read the desktop host's kept copy of a project's record, so it could treat a received project .env as the person's own where the CLI treated it as received. The PR ports the CLI's kept-copy functions into the copy; the functions that decide the answer match the CLI line for line and the two shipped copies of the module are byte-identical. In both the CLI and the copy, a kept copy whose identity does not match the folder now counts every file as received (it was ignored before), the kept-copy read is retried once, and a copy named by both path and identity is read once. Every changed branch fails towards "received"; I found no input where the copy says "not received" and the CLI says "received".

I read the core myself. The media-use scripts' copy of the rule now reads the host's kept record copy the same way the CLI does, and the two shipped copies of that module are byte-identical. Every changed branch fails towards "received": a kept copy for another project path, a kept copy whose identity does not match the folder, a doubted or malformed copy and an unreadable one all count every file as received. I found no input where the scripts say "not received" while the CLI says "received".

The non-blockers are about usability and test strength, not safety.

Blockers

None.

Non-blockers

  1. packages/cli/src/utils/privateProjectFile.ts:198: A moved project whose kept copy carries no identity now loses its own keys (fail-closed usability change). The check is kept.identity !== identity, so a missing or null identity is a mismatch. A project the state file finds only by dev and ino (the folder was renamed) whose kept copy was written without an identity, or on a file system where the folder's birth time is not what the host recorded, now has every file counted as received; before this PR that copy was ignored and the project's record decided. The person's own .env keys in that project then give way to other credentials. Same line in the copy: packages/cli/src/media-use/lib/received-env.mjs:164. This is the safe direction and the PR body states the Linux birth-time case. To resolve: Owner confirms the desktop host always writes an identity into kept copies, in the same dev:ino:birth-ns form the CLI computes; no code change needed if so.
  2. packages/cli/src/media-use/receivedEnv.parity.test.ts:257: Parity fixture for a matching identity passes even if the copy never reads the kept copy. The moved-project fixture keeps only index.html and probes .env, expecting null. A wrong identity string in the copy would be caught (it would return received), but a copy that skipped the kept copy for identity-found projects would also return null and pass. To resolve: Keep .env in that fixture's kept list and expect "received" for the matching-identity case.
  3. packages/cli/src/media-use/lib/received-env.mjs:187: The single retry covers only a failed open or changed file, not a partial in-place rewrite. The second read happens only when the first returns null. If the host ever rewrote a kept copy in place, a read of half-written JSON succeeds, parsing fails and every file counts as received for that run with no retry. Fails closed; harmless if the host always replaces by rename, as the PR says. Same at packages/cli/src/utils/privateProjectFile.ts:224. To resolve: None required if the host replaces kept copies by rename; otherwise retry on a parse failure too.

What the change needed to do

  • The media-use copy applies the same kept-copy rule as the CLI in every branch (absent copy, unreadable copy, link, oversized, unparsable, another project's copy, no list, doubted, identity mismatch, nested project): met (packages/cli/src/media-use/lib/received-env.mjs:151-205 matches packages/cli/src/utils/privateProjectFile.ts:180-243 statement for statement (namings, keptFilesIn, keptFilesFor, hostKeptRecord, withEntriesHostKept); nested pass-through at received-env.mjs:265-266 and :422-423 matches privateProjectFile.ts:424-425 and :499.)
  • Failure handling fails closed (treat as received): met (received-env.mjs:185 (lstat error other than ENOTDIR -> all), :188 (two failed reads or oversized while something is on disk -> all), :170-175 (parse error -> all), :163-167 (wrong project, wrong identity, doubted, no list, non-string entry -> all); the second failed read does not loop, it falls to line 188.)
  • A kept copy with a different identity for a moved project counts every file as received, in CLI and copy: met (privateProjectFile.ts:198 and received-env.mjs:164 return "all"; tests at privateProjectFile.test.ts:418-432 and the parity fixture 'another folder's identity'.)
  • A received project cannot plant or redirect the kept copy: met (received-env.mjs:180-181: the kept copy path is the SHA-256 of the state file's own path string for the project, under the directory of the file named by the host's environment variable; nothing read from the project folder feeds that path. skills/media-use/audio/scripts/lib/heygen.mjs:240 only loads allow-listed keys from a project .env (allow-list contents not opened).)
  • Shipped skill copy is the same file as the tested copy: met (diff of packages/cli/src/media-use/lib/received-env.mjs and skills/media-use/scripts/lib/received-env.mjs reports no difference; 'Skills: manifest in sync' check passed.)
  • Regression tests that fail on the old code: partly met (packages/cli/src/media-use/receivedEnv.parity.test.ts:197-273 and :345-412 cover the listed cases against both implementations; the matching-identity fixture at :257-261 is weak (see finding). Tests were read, not run; the CI shards that run them have since passed.)

CI: 76 checks pass at 0df23d2, none failing or pending; 10 skipped. The CLI test shards that run the new tests are among those that passed.

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.

@jrusso1020 jrusso1020 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Reviewed at 0df23d22c35487e8ccbbea64301288c81d048470.

Approve. The media-use copy now applies the CLI's kept-copy rule one for one:

  • addNamed keeps every path the state file names.
  • namings, keptFilesIn, hostKeptRecord and withEntriesHostKept match the CLI's.
  • readRecord wraps readRecordAsWritten, nestedRecord passes unreadKeptCopy on, and receivedRecords adds an "every file" record for each unread copy.

I compared the port with privateProjectFile.ts function by function and found no divergence. skills/media-use/scripts/lib/received-env.mjs is byte-identical to the package copy.

Each of the three CLI follow-ups fails closed:

  • Identity mismatch now gives "all", the same as every other mismatch.
  • The retry only re-reads when readPlainTail returned null. That happens when the lstat and fstat inodes differ, which is the replace-by-rename race. A real link or non-file still fails both reads and stays "all".
  • The dedupe only drops a path the state file already names by path, so no naming is lost.

Need: the media-use scripts disagreed with the CLI on received .env files · Size: right · Reuse: one-for-one port, held by the copy check · Simpler: no · Structure: fine

Risk: low. Each change only makes more files count as received, never fewer.

Tests (cli vitest: privateProjectFile, receivedEnv.parity, receivedRender, dotEnv, terminalText.parity):

  • Head: 184 passed, 1 skipped. check-media-use-copy-parity: 4/4.

Mutants (one at a time, then reverted). All 10 failed at least one test:

Mutant Tests failed
CLI identity mismatch back to "ignore" 2
Same change in the copy 1
CLI without the retry 2
Copy without the retry 1
CLI without the dedupe 2
Copy without the dedupe 1
nestedRecord drops unreadKeptCopy 1
Copy skips withEntriesHostKept 12
Copy adds back a gone kept entry 2
Copy never adds an every-file record for an unread copy 8

CI: 76 pass, 10 skipped, none failing or pending.

Note, non-blocking: the body discloses the Linux birth-time gap. There, a moved project's copy identity never matches, so every file counts as received. That fails closed, and Desktop is the only writer of kept copies, so this needs no action now. If Linux ever writes kept copies, the identity will need another source.

— Rames

@michaelwang11394
michaelwang11394 added this pull request to the merge queue Nov 17, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Nov 17, 2026
@michaelwang11394
michaelwang11394 added this pull request to the merge queue Nov 17, 2026
Merged via the queue into main with commit c27adb3 Nov 18, 2026
86 checks passed
@michaelwang11394
michaelwang11394 deleted the sec-low31b-1117 branch November 18, 2026 00:17

This branch was successfully deployed

1 active deployment
staging - docs — 0df23d22 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.

3 participants