cowork-harness 2.0.1 → 2.2.0

package/README.md

@@ -115,7 +115,7 @@ node dist/cli.js replay examples/replays/example-pdf-skill.cassette.json
 
 > **Installed globally instead?** Once linked/installed, the same command is `cowork-harness replay
 > <cassette>` — but the relative path above only resolves from a source checkout's `examples/replays/`.
-> From a global install (`npm i -g "cowork-harness@^2.0.1"`), point at the package root instead:
+> From a global install (`npm i -g "cowork-harness@^2.2.0"`), point at the package root instead:
 > `cowork-harness replay "$(npm root -g)/cowork-harness/examples/replays/example-pdf-skill.cassette.json"`
 > (or copy the cassette into your own project and pass that path).
 
@@ -125,7 +125,7 @@ Live `run`/`skill` need the prerequisites in the next section — note the `prot
 > - **Replay only (zero setup):** `cowork-harness replay <cassette>` — no token, no Docker, no agent. The command above.
 > - **`protocol` (real model, no Docker):** needs only the auth token (item 3 below).
 > - **Live `container` / `microvm` / `hostloop` / `cowork`:** needs Docker (or Lima for `microvm`), a staged agent, and the token — run `cowork-harness doctor` first.
-> - **Invocation:** from a source checkout, `node dist/cli.js <cmd>` (or `npm link` to get the `cowork-harness` command); from a global install, `cowork-harness <cmd>`; the companion skill falls back to `npx "cowork-harness@^2.0.1"`.
+> - **Invocation:** from a source checkout, `node dist/cli.js <cmd>` (or `npm link` to get the `cowork-harness` command); from a global install, `cowork-harness <cmd>`; the companion skill falls back to `npx "cowork-harness@^2.2.0"`.
 
 Two more worked examples worth knowing about: `examples/scenarios/protocol-smoke.yaml` (zero-Docker smoke
 test) and `examples/scenarios/skill-loads.yaml` (container-tier acceptance check) — see
@@ -150,7 +150,7 @@ claude plugin marketplace add yaniv-golan/cowork-harness
 claude plugin install cowork-harness@cowork-harness
 ```
 
-The skill **self-bootstraps the CLI**: if `cowork-harness` isn't on your PATH it falls back to `npx "cowork-harness@^2.0.1"` (a version floor that fails loud rather than silently fetching a too-old CLI; Node ≥ 22). Tiers above `protocol` still need Docker/Lima and a Claude Desktop agent binary — see the prerequisites below.
+The skill **self-bootstraps the CLI**: if `cowork-harness` isn't on your PATH it falls back to `npx "cowork-harness@^2.2.0"` (a version floor that fails loud rather than silently fetching a too-old CLI; Node ≥ 22). Tiers above `protocol` still need Docker/Lima and a Claude Desktop agent binary — see the prerequisites below.
 
 It also follows the open [Agent Skills](https://agentskills.io) spec, so it installs cross-editor (Cursor, Codex, OpenCode, …) via [`npx skills`](https://github.com/vercel-labs/skills) (Vercel Labs' CLI implementation of that spec):
 
@@ -175,7 +175,7 @@ global install puts nothing in your working directory. The matrix, answer-policy
 ones that still need a source checkout. (The marketplace
 skill install itself only pulls `.claude/skills/cowork-harness/` — SKILL.md + `references/` + `scenario.py`/
 assertion keys, per `.claude-plugin/marketplace.json`'s `source` — not the rest of this table; the full set
-above becomes available once the skill's first command self-bootstraps `npx "cowork-harness@^2.0.1"` — see
+above becomes available once the skill's first command self-bootstraps `npx "cowork-harness@^2.2.0"` — see
 [above](#drive-it-from-claude-code-companion-skill) — which pulls the same npm package as the global-install row.)
 
 ### Prerequisites for anything above `protocol` fidelity
@@ -358,7 +358,11 @@ Exceptions worth knowing:
 
 - the `boundary-check` **command**'s own probe failures follow the assertion convention and exit `1` (see SPEC.md §11);
 - `verify-cassettes` reuses exit `3` with a different meaning — "could not verify" (vs. a verified failure's `1`); see the command table;
-- exit `4` is reserved on the `run`/`skill` family (SPEC §11).
+- `rehash` uses **exit `4` for PARTIAL success** — some cassettes migrated, some could not. That and a total
+  failure (`1`, nothing migrated) demand opposite responses, so they are separate codes; `0` means all
+  migrated or nothing needed migrating (SPEC §11);
+- exit `4` is otherwise reserved on the `run`/`skill` family, where it is still unused (SPEC §11) — the code
+  space is per-command, so `rehash`'s `4` above does not touch that reservation.
 
 After a run, the footer **echoes every auto-answered
 question as a copy-pasteable `--answer "<q>=<choice>"` line** — run once exploratorily, then paste them
@@ -719,11 +723,23 @@ cowork-harness run scenarios/            # your repo's scenarios; runs every *.y
 
 The fastest path to CI: a composite action wrapping the token-free lane, with a PR job-summary reporter.
 
+> **The `uses:` ref pins the Action, not the CLI.** `@main`, `@v1` and a commit SHA all select which
+> *Action* runs; which *CLI* it installs is the separate `version:` input below, which defaults to
+> `latest`. The two move independently — so a workflow whose `uses:` ref has not changed in months still
+> picks up a CLI **major** the moment one is promoted to `latest`. That is not hypothetical: `@v1` points
+> at 1.24.0 and has not moved, yet an `@v1` workflow without a `version:` input installs 2.x today.
+> **To hold a major, pin the input** — `version: ^2` (or `^1`) — not the `uses:` ref.
+>
+> Upgrading across the 1.x → 2.x boundary this way means the hash-format epoch: cassettes recorded before
+> format v12 need `cowork-harness rehash <dir/>` (no re-record). See the 2.0.0 entry in
+> [CHANGELOG.md](./CHANGELOG.md).
+
 ```yaml
-- uses: yaniv-golan/cowork-harness@main
+- uses: yaniv-golan/cowork-harness@v2
   with:
     command: replay              # replay | lint | lint-skill | analyze-skill | verify-cassettes | run
     path: cassettes/my-skill.cassette.json
+    version: "^2"                # hold the CLI major; the input defaults to `latest`
 ```
 
 | Lane | Commands | Runner requirements | What you get |
@@ -748,14 +764,15 @@ jobs:
           curl -fSL "https://downloads.claude.ai/claude-code-releases/$V/linux-arm64/claude" -o "$RUNNER_TEMP/claude-$V"
           chmod +x "$RUNNER_TEMP/claude-$V"
           echo "COWORK_AGENT_BINARY=$RUNNER_TEMP/claude-$V" >> "$GITHUB_ENV"
-      - uses: yaniv-golan/cowork-harness@main
+      - uses: yaniv-golan/cowork-harness@v2
         with:
           command: run
           path: scenarios/
+          version: "^2"
           anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
 ```
 
-Every run writes a Markdown verdict table (scenario, pass/fail, signals, cost/turns when available, staleness findings, and the replay-skipped-assertions honesty line) to the job summary. Inputs: `command`, `path` (required), `version` (npm dist-tag/version, default `latest` — intentional so recipes track the current release; pin an exact version for reproducible CI. The companion skill's `cowork-harness@^2.0.1` floor guidance applies to ad-hoc CLI installs, not this input), `strict` (applies to `replay` (staleness findings), `lint`/`lint-skill` (WARN/INFO), and `analyze-skill` (any **`error`**-severity finding — advisory findings are precisely the class that does NOT gate); IGNORED — not forwarded — for `verify-cassettes`/`run`, which don't accept the flag), `fail-on-skill-drift` (**`replay`-only** — never forwarded to the analyzers), `extra-args`, `summary` (default `true`), `anthropic-api-key` (live lane only). Outputs: `ok` (`"true"`/`"false"`, mirrors the exit code), `envelope-path` (path to the raw JSON envelope, for post-processing), `summary-md` (the rendered verdict table, exposed as an output — not just written to `$GITHUB_STEP_SUMMARY` — because that file is scoped to this action's own invocation and a caller's later step gets a fresh, empty one). See [`action.yml`](https://github.com/yaniv-golan/cowork-harness/blob/main/action.yml) for the full input/output reference.
+Every run writes a Markdown verdict table (scenario, pass/fail, signals, cost/turns when available, staleness findings, and the replay-skipped-assertions honesty line) to the job summary. Inputs: `command`, `path` (required), `version` (npm dist-tag/version, default `latest` — the recipes above pin `^2` instead, because leaving it at `latest` takes a CLI major the moment it is promoted even though your `uses:` ref never changed; pin an exact version for byte-reproducible CI. The companion skill's `cowork-harness@^2.2.0` floor guidance applies to ad-hoc CLI installs, not this input), `strict` (applies to `replay` (staleness findings), `lint`/`lint-skill` (WARN/INFO), and `analyze-skill` (any **`error`**-severity finding — advisory findings are precisely the class that does NOT gate); IGNORED — not forwarded — for `verify-cassettes`/`run`, which don't accept the flag), `fail-on-skill-drift` (**`replay`-only** — never forwarded to the analyzers), `extra-args`, `summary` (default `true`), `anthropic-api-key` (live lane only). Outputs: `ok` (`"true"`/`"false"`, mirrors the exit code), `envelope-path` (path to the raw JSON envelope, for post-processing), `summary-md` (the rendered verdict table, exposed as an output — not just written to `$GITHUB_STEP_SUMMARY` — because that file is scoped to this action's own invocation and a caller's later step gets a fresh, empty one). See [`action.yml`](https://github.com/yaniv-golan/cowork-harness/blob/main/action.yml) for the full input/output reference.
 
 The provided [GitHub Actions workflow](https://github.com/yaniv-golan/cowork-harness/blob/main/.github/workflows/ci.yml) runs a **nine-stage pipeline**. The **build** + **test** stages are the token-free gate you can copy into your skill repo; the `floor`, `action-self-test`, `python`, `image-recipe`, `boundary`, `scenarios`, and `parity-drift` stages are this repo's own fidelity self-tests and are not directly portable (they build the harness's Docker image and run harness-specific e2e scenarios — see [`ci-recipe.md`](./.claude/skills/cowork-harness/references/ci-recipe.md) for the skill-repo template):
 

package/RELEASING.md

@@ -223,8 +223,13 @@ tagging `1.0.0`, deliberately review and freeze the surfaces with no machine-rea
       gh run watch $(gh run list --workflow=release.yml --limit 1 --json databaseId --jq '.[0].databaseId')
       ```
 - [ ] **Clean up**: `git push origin --delete release/X.Y.Z && git branch -d release/X.Y.Z`
-- [ ] **Move the major/minor tags** (so `uses: yaniv-golan/cowork-harness@v1` and `@v1.0` resolve to
-      this release — the packaged Action's Marketplace consumers pin those):
+- [x] **Move the major/minor tags** — **AUTOMATED** by `release.yml`'s last step, which points `vX` and
+      `vX.Y` at the release it just published. It skips a prerelease tag entirely, and never moves an alias
+      backwards (re-releasing an older patch on a line moves `vX.Y` but leaves `vX` where it is). Left as a
+      checklist item, it lapsed: `v1` sat at 1.24.0 through two releases. Note what these tags do NOT do:
+      they select the ACTION, never the CLI. A consumer who leaves the `version:` input at its `latest`
+      default already tracks CLI majors regardless of which alias they pin, so moving `vX` neither causes
+      nor prevents a cross-major CLI upgrade for them. Manual fallback, if the step ever needs redoing:
       ```
       git tag -f vX vX.Y.Z && git tag -f vX.Y vX.Y.Z   # e.g. v1 and v1.0 → v1.2.3
       git push -f origin vX vX.Y

package/SPEC.md

@@ -485,9 +485,11 @@ token-free assertion-iteration loop. That path is safe by construction: it **har
 drift (`prompt` / `baseline` / `fidelity` / `answers` / `skills` / `requires_capabilities`) and, when a skill
 fingerprint was recorded, on skill-content staleness (it implies `--fail-on-skill-drift`). `expect_denied` and
 the filesystem/egress keys are sourced from on-disk but remain live-only (sourced ≠ evaluated; replay warns on
-such an edit). The `session` (model / data mounts / discovery) is **not** drift-checked or fingerprinted, so a
-model/mount change between record and re-assert is undetected — the notice states this; re-record if the
-session changed.
+such an edit). The `session` is **not drift-checked on the replay path**, so a session change between record and
+re-assert does not move the replay verdict — the notice states this; re-record if the session changed.
+It *is* fingerprinted, but only `verify-cassettes` checks that hash (§11.1): `sessionFingerprint`
+covers the session's connected `folders`/`plugins`/`skills`/`mcp`/`egress`/`web_fetch`, plus `projects`
+and `agent_env` when set. `model` is covered by neither, so a model swap is undetected everywhere.
 
 **`replay_protocol_fidelity` (O7 guard):** after the run, `replay` re-serializes each decision
 response via `serializeDecision` and compares to the frozen `controlOut` envelope (canonical
@@ -647,7 +649,8 @@ is never truncated by `process.exit` on a pipe.)
 question" outcome (the deferred `on_unanswered: surface` / `needs_input` Track 2). It is currently
 unused — reserving it now keeps a later addition additive rather than a renumbering of the burned
 `0`/`1`/`2`/`3` space. Exit-code space is **per-command**, not global (`status` uses `0`/`1`/`2`/`3`
-with its own meanings); this reservation applies only to the `run`/`skill` family.
+with its own meanings); this reservation applies only to the `run`/`skill` family. `rehash` does use `4`,
+for partial migration success (above) — a different command, so it does not consume this reservation.
 
 **Per-command exceptions:** `critique` **never gates on findings** — it exits `0` for any finding of any classification, and even when the task run it graded ERRORED (that is a finding about the skill, not a broken instrument). It exits `2` only for a usage error or an **instrument failure**: the turn was killed, the reflection protocol broke, or the evaluator was never invoked *or threw* — i.e. no critique was produced. Do not gate CI on `critique`; that inverts its design. `lint` exits `127` when `python3` is missing (spawn error); `replay` exits
 `2` on a **whole-cassette operational failure** — anything `readCassette` rejects (unreadable, invalid
@@ -666,6 +669,14 @@ verification could NOT complete (any `unverifiable-*`-class staleness finding, a
 newer harness than this one understands, or a per-file read error/crash — including a
 malformed/unreadable cassette, which is tallied there rather than as a `1` finding). A real finding
 always outranks a could-not-verify signal within the same run, so exit `1` wins if both occur.
+**`rehash` uses its own four-way split:** `0` all migrated (or nothing needed migrating) · **`4` PARTIAL —
+some migrated, some could not** · `1` nothing migrated and at least one could not · `2` usage. The partial
+code is distinct because the two failing shapes demand opposite responses — commit what migrated and budget
+a re-record for the rest, versus nothing here is salvageable — and while both were `1` a shell consumer
+reading only the exit code could not tell them apart (the JSON envelope always carried the split as
+`migrated`/`skipped`/`errors`). `4` rather than `3`: the code space is per-command, and `3`'s "could not
+verify" meaning is load-bearing on `verify-cassettes` — a migration that partly succeeded is not a failed
+verification.
 **Collision warning:** the `run`/`skill` family's exit `3` means *boundary/integrity* (§11 above);
 `verify-cassettes`' exit `3` means *could not verify*. These are unrelated per-command meanings that
 happen to share a number — a CI script that branches on exit code across commands must not conflate
@@ -839,6 +850,15 @@ Covered-surface changes follow semver as of `1.0.0` — see [RELEASING.md](./REL
   future-stamped cassette without refusing, since neither produces a pass/fail verdict. Post-1.0, raising
   the read floor past a still-readable version is breaking.
 - **Control protocol** — `schema/protocol.v1.json` + the golden control-response vectors (§5).
+  Removing or narrowing a described frame is breaking; **DESCRIBING A FRAME THE HARNESS ALREADY
+  ANSWERS IS NOT** — it can only make a validator that was rejecting real traffic start accepting it,
+  so no working consumer changes behaviour. (The same additive latitude the `verify-cassettes` and
+  `doctor` envelopes above are granted. Stated explicitly because its absence here read as a
+  prohibition: three subtypes the harness had always answered — `request_user_dialog`, `elicitation`
+  and `side_question` — plus the fail-closed `subtype:"error"` envelope went undescribed rather than
+  added. A schema that rejects frames the code sends is worse than one that grows.) The golden vector
+  pack is coupled: every schema definition must be exercised by a vector, so a new frame ships with
+  evidence or not at all.
 - **Environment variables** — the documented `COWORK_HARNESS_*` knobs plus `COWORK_AGENT_BINARY` and
   `COWORK_AGENT_IMAGE`. Renaming a documented var or changing its meaning is breaking.
 - **Packaged GitHub Action** — `action.yml` inputs (`command`, `path`, `version`, `strict`,

package/dist/assert.js

@@ -1141,10 +1141,25 @@ function check(a, ctx) {
             results.push(fail("present_files_called: present_files is not served on `lane: remote` — a local MCP server cannot reach a remote Cowork session, which delivers via the agent-native SendUserFile instead (not modeled; see docs/fidelity-gaps.md) — cannot verify"));
         else if (ctx.effectiveFidelity !== "container" && ctx.effectiveFidelity !== "hostloop")
             results.push(fail(`present_files_called: present_files is served only on the container/hostloop tiers (this run: ${ctx.effectiveFidelity ?? "unknown"}) — cannot verify; use fidelity: container or hostloop for present_files-based delivery`));
-        else if (ctx.presentedFiles === undefined || ctx.presentedFiles.length === 0)
-            results.push(fail(`present_files_called: no file was delivered via present_files (the tool was never called)`));
-        else
+        // PRESENCE comes from the invocation count, not from `presentedFiles`. The two answer different
+        // questions, and only one of them survives redaction: `presentedFiles` entries are dropped when a
+        // path can't be classified, which a host-path policy guarantees at hostloop (a real host path
+        // redacts to `[REDACTED:…]/mnt/outputs/f`, and the classifier requires an absolute path). Reading
+        // delivery off classification made a redacted recording report "the tool was never called" about a
+        // run that called it three times — and, because record's redaction self-check replays both
+        // cassettes and compares verdicts, no such cassette could be written at all.
+        // `presentedFiles.length` stays as the fallback for a run recorded before the count existed.
+        else if ((ctx.presentFilesCalls ?? 0) > 0 || (ctx.presentedFiles?.length ?? 0) > 0)
             results.push(ok());
+        // Called, but every call's `files` was unusable — the tool WAS invoked, so "never called" would be a
+        // factual claim the harness knows to be false. Mirrors no_scratchpad_leak's malformed branch above.
+        // The count is deliberately NOT interpolated: record's self-check normalizes [REDACTED…] tokens out
+        // of failing messages but not digits, so a count that differs between the base and redacted replays
+        // would trip its message compare and refuse a record that is otherwise fine to write.
+        else if (ctx.evidenceErrors?.presentFilesMalformed)
+            results.push(fail(`present_files_called: present_files WAS called, but no call carried a usable file path (malformed input) — cannot verify delivery`));
+        else
+            results.push(fail(`present_files_called: no file was delivered via present_files (the tool was never called)`));
     }
     if (a.no_skill_triggered !== undefined) {
         const c = compileUserRegex(a.no_skill_triggered);

package/dist/baseline.js

@@ -319,25 +319,47 @@ function latestBaselineFile() {
     files.sort(compareBaselineVersions);
     return join(BASELINES_DIR, files[files.length - 1]);
 }
+/** The one segment the harness's staged session tree always adds under the session root. Every stager
+ *  and every argv builder composes guest paths with it (`stage.ts`/`hostloop-stage.ts` create
+ *  `<sessionHost>/mnt`, `dockerRunArgv` nests `:ro` binds at `<sessionRoot>/mnt/<mountPath>`), so a
+ *  guest mnt root that is anything OTHER than `<sessionRoot>/mnt` cannot be produced. */
+export const GUEST_MNT_SEGMENT = "mnt";
 /**
- * Expand the mount layout for a concrete session id.
- * cwd/sessionRoot = the session root (e.g. /sessions/<id>); mounts sit under mntRoot
- * (/sessions/<id>/mnt) and are returned as ABSOLUTE guest paths.
+ * Expand the mount layout for a concrete session id — the layout of the tree THIS HARNESS stages, which
+ * is what every guest path must be built from.
+ *
+ * `mntRoot` is DERIVED as `<sessionRoot>/mnt`, not read from `mountLayout.mntRoot`: the staged tree can
+ * only ever be there (see GUEST_MNT_SEGMENT), so honouring a recorded value that says otherwise emits
+ * guest paths pointing at directories no stager creates. A baseline recording a different mnt root is a
+ * FIDELITY divergence, surfaced by `recordedLayoutDivergence` at spawn, never a path this builds.
+ *
+ * Guest paths anchor on `sessionRoot` (the bind target), never on `cwd`: production's own working dir is
+ * a folder mount or `outputs` rather than the bare session root, so the two are not interchangeable even
+ * though every synced baseline currently records them equal. `cwd` is the agent's working directory and
+ * nothing else.
  */
 export function resolveMounts(baseline, sessionId, projectId = "proj1") {
     const subst = (s) => s.replace("{sessionId}", sessionId).replace("{projectId}", projectId);
     const cwd = subst(baseline.mountLayout.cwd);
     const sessionRoot = subst(baseline.mountLayout.sessionRoot);
-    // TODO: container.ts:31 computes configGuest independently from sessionRoot and is NOT fixed here;
-    // the legacy desktop-1.11847.5 baseline (sessionRoot ending in /mnt, no spawn block) still produces
-    // a double-mnt configGuest path (/sessions/<id>/mnt/mnt/.claude) — that is a separate out-of-scope issue.
-    const rawSessionRoot = baseline.mountLayout.sessionRoot;
-    const mntRoot = subst(baseline.mountLayout.mntRoot ?? (rawSessionRoot.endsWith("/mnt") ? rawSessionRoot : `${rawSessionRoot}/mnt`));
-    return {
-        cwd,
-        sessionRoot,
-        mntRoot,
-        configDir: `${mntRoot}/.claude`,
-        mounts: baseline.mountLayout.mounts.map((m) => ({ ...m, mountPath: `${mntRoot}/${subst(m.mountPath)}` })),
-    };
+    const mntRoot = `${sessionRoot}/${GUEST_MNT_SEGMENT}`;
+    return { cwd, sessionRoot, mntRoot };
+}
+/** Does this baseline RECORD a guest layout the harness cannot stage? Reads the recorded fields only
+ *  (never the derived ones), so it stays a statement about the data: a `mntRoot` that is not
+ *  `<sessionRoot>/mnt`, or a `sessionRoot` that already ends in the mnt segment — the shape that made
+ *  `resolveMounts` return a root one level above the staged tree. Returns the divergence for the caller
+ *  to surface, or undefined when the recording is reproducible. */
+export function recordedLayoutDivergence(baseline) {
+    // Read STRUCTURALLY: a partially-constructed baseline (`{ spawn: {} }`) is normal at the argv seam, and
+    // this check must never be the thing that throws there. No recorded layout ⇒ nothing to diverge from.
+    const { sessionRoot, mntRoot } = baseline.mountLayout ?? {};
+    if (typeof sessionRoot !== "string")
+        return undefined;
+    const staged = `${sessionRoot}/${GUEST_MNT_SEGMENT}`;
+    if (mntRoot !== undefined && mntRoot !== staged)
+        return { recorded: mntRoot, staged };
+    if (sessionRoot.endsWith(`/${GUEST_MNT_SEGMENT}`))
+        return { recorded: sessionRoot, staged };
+    return undefined;
 }

package/dist/cli.js

@@ -490,7 +490,10 @@ const SUBCOMMAND_USAGE = {
         "       match are the algorithm-derived values rewritten. Anything unprovable is refused, never migrated.\n" +
         "       --session <file>: for a MOVED cassette, whose recorded session cannot be resolved from its own\n" +
         "       directory. One cassette at a time — each may have been recorded against a different tree, so a\n" +
-        "       directory batch cannot share one override.",
+        "       directory batch cannot share one override.\n" +
+        "       Exit: 0 = all migrated, or nothing needed migrating. 4 = PARTIAL, some migrated and some could not\n" +
+        "       (commit what migrated, budget a re-record for the rest). 1 = nothing migrated and at least one\n" +
+        "       could not. 2 = usage. The JSON envelope carries the same split as migrated/skipped/errors.",
     prune: "usage: prune [--keep-last <n>] [--pinned-older-than <N>d|h|m] [--dry-run] [<runs-dir>]   (prune accumulated run dirs; default --keep-last 5)",
     "migrate-run-dir": "usage: migrate-run-dir [<runs-dir>] [--scenario <name>] [--write] [--verbose]\n" +
         "       convert pre-layout run dirs (artifacts at the run-dir root) to the per-turn `turns/<N>/` layout, in place.\n" +
@@ -3766,6 +3769,7 @@ async function cmdVerifyRun(args) {
         fileToolAttempts: result.fileToolAttempts,
         pathDenials: result.pathDenials,
         presentedFiles: result.presentedFiles,
+        presentFilesCalls: result.presentFilesCalls,
         evidenceErrors: result.evidenceErrors,
         effectiveFidelity: result.effectiveFidelity,
         // verify-run re-checks a kept run dir on the SAME machine that ran it — grouped with the live

package/dist/prompt.js

@@ -2,6 +2,7 @@ import { warn } from "./io.js";
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { resolveMounts } from "./baseline.js";
 const BASELINES_DIR = join(fileURLToPath(new URL("..", import.meta.url)), "baselines");
 /** The {{placeholder}} names renderPrompts() substitutes. KEEP IN LOCKSTEP with the `tokens` map below. */
 export const MODELED_PLACEHOLDER_NAMES = new Set([
@@ -31,8 +32,10 @@ firstFolderMountPath, opts) {
     const spawn = baseline.spawn;
     if (!spawn)
         return {};
-    const sessionRoot = `/sessions/${sessionId}`;
-    const mntRoot = `${sessionRoot}/mnt`;
+    // Through resolveMounts, NOT a local `/sessions/<id>` literal: the prompt tells the agent where its
+    // files are, so it must name the same tree the runtimes stage and bind. A private derivation here was a
+    // fourth copy of this rule, and a fourth place for it to drift.
+    const { sessionRoot, mntRoot } = resolveMounts(baseline, sessionId);
     const workspaceFolder = firstFolderMountPath ? `${mntRoot}/${firstFolderMountPath}` : `${mntRoot}/outputs`;
     // {{currentDateTime}}/{{currentTimezone}} are deliberately render-time-impure (wall clock, host
     // TZ) — that's what the real Desktop builder substitutes, and the rendered append never enters a

package/dist/redact.js

@@ -31,6 +31,46 @@ function csv(v) {
         .map((s) => s.trim())
         .filter(Boolean);
 }
+/** Pattern ORDER is load-bearing, and nothing used to say so.
+ *
+ *  `redactText` applies patterns sequentially over the ACCUMULATING output, so an earlier pattern can eat
+ *  the very text a later pattern's lookahead exists to preserve. The shipped policy relies on this: the
+ *  `(?=/mnt/)`-anchored rules are ordered ahead of the bare catch-alls precisely so a run-dir path redacts
+ *  to `[REDACTED:…]/mnt/outputs/f.md` and still resolves. Reverse them and the whole path is eaten:
+ *
+ *    as shipped -> [REDACTED:local-path:…]/mnt/outputs/report.md   -> normalizes to `outputs/report.md`
+ *    reordered  -> [REDACTED:local-path:…]                         -> normalizes to `null`
+ *
+ *  i.e. every `computer_links` structural-marker resolution silently stops working — no error, no finding,
+ *  just links that no longer resolve on replay. This detects the one shape that causes it: a bare pattern
+ *  ordered ahead of an otherwise-identical lookahead-anchored one.
+ *
+ *  Deliberately CONSERVATIVE — regex subsumption is undecidable in general, so this fires only when a
+ *  later pattern's source is exactly an earlier one's plus a trailing lookahead (modulo lazy quantifiers).
+ *  A miss is a missed warning; a false positive would train authors to ignore it. */
+export function findShadowedPatterns(sources) {
+    const norm = (r) => r.replace(/\+\?/g, "+").replace(/\*\?/g, "*");
+    const out = [];
+    for (let j = 0; j < sources.length; j++) {
+        const b = norm(sources[j]);
+        for (let i = 0; i < j; i++) {
+            const a = norm(sources[i]);
+            if (!b.startsWith(a))
+                continue;
+            // The remainder must be exactly a trailing lookahead. Checked by SHAPE, never by parsing the
+            // lookahead's body: an earlier version matched `\(\?=[^()]*\)`, and the `[^()]*` silently skipped
+            // every lookahead containing a group — so `(?=/mnt(?:/|$|[\s"'\\)\]]))`, the natural way to write
+            // "slash, end, or delimiter" and arguably more correct than a bare `(?=/mnt/)`, went unflagged while
+            // being just as dangerous. Reported against a real third-party policy. Paren-balancing here would
+            // also have to be escape- and char-class-aware (that same policy carries a `\)` inside a class);
+            // not looking inside sidesteps both problems.
+            const rest = b.slice(a.length);
+            if (rest.length > 3 && rest.startsWith("(?=") && rest.endsWith(")"))
+                out.push({ shadowed: j, by: i, base: a });
+        }
+    }
+    return out;
+}
 /** Assemble a redaction policy from `.cowork-redact.json` (searched in `searchDirs`, e.g. cwd then the
  *  scenario/cassette dir) merged with `COWORK_HARNESS_REDACT_PATTERNS`/`_KEYS`. No config + no env →
  *  an empty policy (the opt-in default; the scanner is the always-on safety net). A malformed regex
@@ -60,6 +100,10 @@ export function loadRedactionPolicy(searchDirs) {
         patterns.push({ re: new RegExp(src, "g"), label: "redacted" });
     for (const k of csv(process.env.COWORK_HARNESS_REDACT_KEYS))
         keyNames.push(k);
+    for (const { shadowed, by, base } of findShadowedPatterns(patterns.map((p) => p.re.source)))
+        process.stderr.write(`cowork-harness: WARNING .cowork-redact.json pattern [${by}] (\`${base}\`) is ordered ahead of the ` +
+            `lookahead-anchored pattern [${shadowed}], so it matches first and eats the text that lookahead ` +
+            `preserves. Move [${shadowed}] before [${by}], or computer:// links will stop resolving on replay.\n`);
     return { patterns, keyNames };
 }
 /** Stable, collision-safe token for a matched span. Depends ONLY on the matched text (context-free), so the

package/dist/run/budget.js

@@ -96,15 +96,21 @@ export function batchBudgetTracker(maxBudgetUsd, enforceRunningTotal, onWarn = l
  *  that to size a 24-scenario re-record. */
 export function estimateBatchCost(scenarios) {
     let known = 0;
+    let pricedRuns = 0;
+    let thinnest;
     const unpriced = [];
     for (const s of scenarios) {
         const worst = worstObservedCost(s);
-        if (worst === undefined)
+        if (worst === undefined) {
             unpriced.push(s);
-        else
-            known += worst;
+            continue;
+        }
+        known += worst;
+        const n = pricedRunCount(s);
+        pricedRuns += n;
+        thinnest = thinnest === undefined ? n : Math.min(thinnest, n);
     }
-    return { known, unpriced };
+    return { known, unpriced, pricedRuns, thinnest };
 }
 /** The one-line estimate, phrased so a partially-unpriced total can never read as authoritative. An
  *  unqualified "$0.00" over a corpus that has never run is worse than no number at all. */
@@ -113,8 +119,17 @@ export function batchCostEstimateLine(scenarios, est) {
     const detail = est.unpriced.length
         ? ` (${est.unpriced.length}/${scenarios.length} scenario(s) have no priced run history and contribute $0: ` +
             `${est.unpriced.slice(0, 5).join(", ")}${est.unpriced.length > 5 ? `, +${est.unpriced.length - 5} more` : ""})`
-        : ` (all ${scenarios.length} scenario(s) priced from prior runs)`;
-    return `estimated batch cost: $${est.known.toFixed(4)}${bound}${detail}`;
+        : // The complete case used to read `(all N scenario(s) priced from prior runs)`, which is an active
+            // claim of authority — and the one case where this line said nothing qualifying. It is still
+            // `sum(max(local history))`: a max over whatever THIS machine ran, so at a new baseline or a new
+            // agent binary the history describes a materially different configuration and can UNDER-predict.
+            // A consumer wrote "that is the ceiling, not the scope" into a plan off this line and had to retract.
+            ` (all ${scenarios.length} scenario(s) priced)`;
+    const basis = est.thinnest === undefined
+        ? ""
+        : ` — basis: ${est.pricedRuns} prior run(s) on THIS machine, thinnest scenario has ${est.thinnest}; ` +
+            `a max over that history, NOT a bound`;
+    return `estimated batch cost: $${est.known.toFixed(4)}${bound}${detail}${basis}`;
 }
 /**
  * Cumulative pre-flight for a `record` BATCH: refuse before spending anything if the summed worst-case

package/dist/run/cassette.js

@@ -908,7 +908,10 @@ export function fingerprintSkillDrift(rec, live) {
  *  undefined ("can't verify", never a false mismatch) for an inline scenario or when the session file
  *  can't be read/parsed from `sessionPath` (resolved against `cassetteDir` exactly like
  *  `skillSourceDirs`). Arrays are sorted before hashing so authoring order can't spuriously move the hash. */
-export function buildSessionFingerprint(sessionPath, cassetteDir, override) {
+export function buildSessionFingerprint(sessionPath, cassetteDir, override, 
+/** `omitProjects` reproduces the PRE-`projects` shape. Only `sessionFingerprintDrift` passes it, to tell
+ *  "this recording predates `projects` coverage" apart from "your session changed" — see there. */
+opts) {
     if (sessionPath === "(inline)")
         return undefined;
     // Same resolver as skillSourceDirs: an override that reached only ONE of them would verify skill
@@ -949,6 +952,15 @@ export function buildSessionFingerprint(sessionPath, cassetteDir, override) {
         // affects only hostloop/protocol replay behavior — see agent_env's doc comment) moves the hash so
         // `verify-cassettes` surfaces the drift instead of a cassette quietly replaying stale env behavior.
         ...(Object.keys(agentEnv).length ? { agent_env: agentEnv } : {}),
+        // Connected PROJECTS, on the same NON-EMPTY-ONLY terms as `agent_env` above: a session with no
+        // `projects:` hashes byte-identically to before, so the overwhelming majority of cassettes do not
+        // move. Unlike `agent_env` (a brand-new field nobody had), `projects` is an EXISTING field, so a
+        // project-bearing session's hash DOES move once — which is why `sessionFingerprintDrift` reports that
+        // case as unverifiable rather than as drift. Omitting it was a false green: swapping which directory
+        // is mounted at `.projects/<uuid>` changed the run's inputs and `verify-cassettes` said nothing.
+        ...(!opts?.omitProjects && cfg.projects.length
+            ? { projects: [...cfg.projects].map((pr) => ({ uuid: pr.uuid, from: pr.from })).sort((a, b) => a.uuid.localeCompare(b.uuid)) }
+            : {}),
     };
     return createHash("sha256")
         .update(Buffer.from(JSON.stringify(shape), "utf8"))
@@ -1729,6 +1741,7 @@ function minimalRec() {
         fileToolAttempts: [],
         pathDenials: [],
         presentedFiles: [],
+        presentFilesCalls: 0,
         webSearches: [],
         infraErrors: [],
         evidenceErrors: { taskTracking: 0, webSearchParse: 0, presentFilesMalformed: 0 },
@@ -3060,6 +3073,9 @@ export async function cmdRecord(args) {
                     refusals,
                     estimatedCostUsd: estimate.known,
                     unpricedScenarios: estimate.unpriced,
+                    // The basis for `estimatedCostUsd`, so automation need not treat it as a bound. It is
+                    // `sum(max(local run history))` — see `batchCostEstimateLine`.
+                    estimateBasis: { source: "local-run-index", pricedRuns: estimate.pricedRuns, thinnestScenarioRuns: estimate.thinnest ?? 0 },
                     token,
                     agent: agentPayload,
                 }));
@@ -3905,6 +3921,7 @@ function replayErrorResult(file) {
         fileToolAttempts: undefined, // no rec to read from on this early-bail lane
         pathDenials: undefined, // no rec to read from on this early-bail lane
         presentedFiles: undefined, // no rec to read from on this early-bail lane
+        presentFilesCalls: undefined, // ditto
         preRunPaths: undefined,
         preRunLinkAware: undefined,
         preRunHashes: undefined,
@@ -4059,6 +4076,23 @@ export function sessionFingerprintDrift(cassette, cassetteDir, sourceVia, sessio
         };
     if (live === cassette.sessionFingerprint)
         return { drifted: false };
+    // A recording made BEFORE `projects` was folded into the shape carries a hash that says nothing about
+    // `projects[]`. Report that honestly as UNVERIFIABLE, not as a migration-with-all-clear: the recorded
+    // value cannot distinguish "the field was simply never covered" from "the project mount changed since",
+    // because there is nothing about `projects` in it to compare against. Claiming "nothing changed" here
+    // would reintroduce, in the remedy, exactly the false green this field's coverage exists to close.
+    //
+    // The test is an EXACT match on the pre-`projects` shape, which is also why it can run ahead of the
+    // name-lookup downgrade below: a byte-equal legacy hash is strong evidence the resolved file really is
+    // this cassette's session (an unrelated same-named sibling matching exactly is not a coincidence worth
+    // hedging), so the more specific and more actionable message wins.
+    const legacy = buildSessionFingerprint(cassette.scenario.session, cassetteDir, sessionOverride, { omitProjects: true });
+    if (legacy !== undefined && legacy === cassette.sessionFingerprint)
+        return {
+            drifted: false,
+            unverifiable: true,
+            note: "session-fingerprint: this cassette was recorded before `projects` was part of the session shape, so its hash covers everything EXCEPT `projects[]` — and everything it does cover matches. A change to a project mount since record time is therefore not detectable here. Re-record to gain that coverage.",
+        };
     // Only "name-lookup" (a scenario WAS found, but not at its persisted/expected offset — the SAME
     // low-confidence signal scenarioContentDrift downgrades on) is grounds to distrust this mismatch.
     // "none" means "nothing to compare the layout against" (mirrors scenarioContentDrift's own `!src.path`
@@ -5009,7 +5043,7 @@ export async function cmdVerifyCassettes(args) {
             const sourceVia = rr.persistedMissing ? "name-lookup" : "none";
             const sfd = sessionFingerprintDrift(rc.cassette, dirname(f), sourceVia, vcSessionOverride);
             if (sfd.drifted)
-                staleness.push("session-shape fingerprint differs from the current session file (connected folders/plugin/skill/mcp/egress config changed since record) — re-record");
+                staleness.push("session-shape fingerprint differs from the current session file (connected folders/plugins/skills/mcp/egress/web_fetch config changed since record; projects and agent_env are hashed only when set) — re-record");
             if (sfd.note)
                 notes.push(sfd.note);
         }
@@ -5452,26 +5486,50 @@ export function cmdRehash(args) {
     const migrated = results.filter((r) => r.action === "migrated").length;
     const skipped = results.filter((r) => r.action === "skipped").length;
     const errors = results.filter((r) => r.action === "error").length;
+    const code = rehashExitCode({ migrated, errors });
     if (asJson) {
         out(jsonPayloadEnvelope("rehash", errors === 0, { dryRun, migrated, skipped, errors, results }));
     }
     else {
-        for (const r of results) {
-            const glyph = r.action === "migrated" ? "✓" : r.action === "error" ? "✗" : "·";
-            log(`${glyph} ${r.file}: ${r.reason}`);
-        }
+        // Summary FIRST. It used to print last, after every per-file line had scrolled past — and these two
+        // counts ARE the decision, so a reader had to scroll back up to find them. The per-file lines below
+        // are the detail behind it, not the thing being reported.
         if (migrated > 0 || errors > 0) {
-            log(errors > 0
-                ? `✗ rehash: ${migrated} migrated, ${skipped} skipped, ${errors} could not migrate${dryRun ? " (dry-run)" : ""}`
-                : // No single target version here — P8 stamps per-scenario (requiredVersionFor), so a batch can
-                    // migrate some cassettes to v10 and others to v11; each row's own reason already says which.
-                    `✓ rehash: ${migrated} cassette(s) migrated${dryRun ? " (dry-run — nothing written)" : ""}`);
+            const glyph = errors > 0 ? (migrated > 0 ? "!" : "✗") : "✓";
+            const verb = dryRun ? "migratable" : "migrated";
+            // No single target version here — P8 stamps per-scenario (requiredVersionFor), so a batch can
+            // migrate some cassettes to v10 and others to v11; each row's own reason already says which.
+            log(`${glyph} rehash: ${migrated} ${verb}` +
+                (errors > 0 ? `, ${errors} require a re-record` : "") +
+                (skipped > 0 ? `, ${skipped} already current` : "") +
+                (dryRun ? " (dry-run — nothing written)" : ""));
         }
         else {
             log("✓ rehash: nothing to migrate");
         }
+        for (const r of results) {
+            const glyph = r.action === "migrated" ? "✓" : r.action === "error" ? "✗" : "·";
+            log(`${glyph} ${r.file}: ${r.reason}`);
+        }
     }
-    return process.exit(errors > 0 ? 1 : 0);
+    return process.exit(code);
+}
+/** `rehash`'s exit code, documented in SPEC §11 and in its `--help`.
+ *
+ *  PARTIAL success gets its own code. `4 migrated, 18 failed` and `0 migrated, 22 failed` demand opposite
+ *  responses — commit the four and budget a re-record for the rest, versus nothing here is salvageable —
+ *  and while both were `1`, a shell consumer reading only the exit code could not tell them apart. The
+ *  JSON envelope always carried the split as `migrated`/`skipped`/`errors`; a bare terminal run did not.
+ *
+ *  `4` rather than `3`: the exit-code space is per-command, and `3`'s "could not verify" meaning is
+ *  load-bearing on `verify-cassettes` — a migration that partly succeeded is not a failed verification.
+ *
+ *  `skipped` is deliberately not an input: an already-current cassette needs no action, so it cannot
+ *  turn a clean run dirty or a total failure partial. */
+export function rehashExitCode(tally) {
+    if (tally.errors === 0)
+        return 0;
+    return tally.migrated > 0 ? 4 : 1;
 }
 /** Record-time connected-folder host-path -> resolved-mount-name map (Finding 24), persisted onto a
  *  v9+ cassette's `folderPrefixMap`. Zips `recordRoots` (minus the leading `outputs`) against
@@ -5564,8 +5622,10 @@ export const ALWAYS_CONTENT_KEYS = [
     "task_status",
     "result",
     // content-class, NOT controlOut-gated: both the present_files tool_use and its own tool_result live
-    // in the ordinary events stream, so the re-drive reproduces `RunResult.presentedFiles` exactly like
-    // the other re-derived signals above (skill_triggered, redundantToolCalls, …).
+    // in the ordinary events stream, so the re-drive reproduces the present_files signals like the other
+    // re-derived ones above (skill_triggered, redundantToolCalls, …). `presentFilesCalls` (what
+    // present_files_called reads) reproduces on every tier; `presentedFiles`' promoted/leaked booleans
+    // reproduce at container, where cwd is the session root — no_scratchpad_leak's only tier.
     "no_scratchpad_leak",
     "present_files_called",
     // content-class, NOT controlOut-gated: fileToolAttempts re-derives from frozen tool_use blocks (the
@@ -6080,6 +6140,7 @@ export async function replayCassette(cassette, hooks = [], opts = {}) {
             // empty [] (nothing presented) vacuous-passes no_scratchpad_leak instead of reading as
             // evidence-unavailable.
             presentedFiles: rec.presentedFiles,
+            presentFilesCalls: rec.presentFilesCalls,
             evidenceErrors: rec.evidenceErrors,
             effectiveFidelity: cassette.effectiveFidelity,
             // Replay has no live filesystem — computer_links_resolve normalizes both link shapes against the
@@ -6437,6 +6498,7 @@ export async function replayCassette(cassette, hooks = [], opts = {}) {
             // NOT reproduce — this one genuinely re-derives. Uncollapsed (an empty [] is the real "nothing
             // presented" signal no_scratchpad_leak's vacuous pass needs, matching live).
             presentedFiles: rec.presentedFiles,
+            presentFilesCalls: rec.presentFilesCalls,
             preRunPaths: undefined,
             // Report the baseline semantics actually used during evaluation above (not undefined) so the returned
             // result doesn't misrepresent them. Same source of truth as the evaluate() ctx.

package/dist/run/chat-result.js

@@ -113,6 +113,7 @@ export function buildChatResult(record, opts) {
         fileToolAttempts: record.fileToolAttempts,
         pathDenials: record.pathDenials,
         presentedFiles: record.presentedFiles,
+        presentFilesCalls: record.presentFilesCalls,
         egress: opts.egress,
         resources,
         stderrLogPath: join(opts.outDir, "agent.stderr.log"),