agents-handoff 2.0.3 → 2.0.5

package/CHANGELOG.md

@@ -15,6 +15,77 @@ version, and it is the version published to npm: the repository root is the
 
 Add entries under the matching heading as changes land.
 
+## [2.0.5] - 2026-10-09
+
+### Fixed
+
+- **Real Claude Code and Codex exports parse.** The engine read text only from a top-level
+  `text`/`content`/`parts[]`, so a genuine Claude Code transcript (`message.content[]`) or a Codex
+  CLI rollout (`payload`) produced **zero turns** while `--harness claude-code` merely labelled the
+  result. Nested blocks, `message.content[]`, `parts[]`, `item.content[]`, `output` and the Codex
+  `payload` wrapper are read now, and a record whose every typed block is a reasoning block
+  classifies as `THOUGHT`.
+- **A malformed transcript line is no longer dropped in silence.** It stops the build with
+  `exit 5`, naming the line number and reason. Dropping it produced a handoff that looked complete
+  and was missing part of the session; this restores the fail-closed rule the rest of the tool
+  already followed. `--allow-bad-lines` skips such lines deliberately and prints how many were
+  skipped.
+- **`promote` enforces the evidence gate.** It ran the gate, printed the verdict and promoted
+  regardless (`void gateRun`), so a `REJECTED` handoff was stamped as promoted. It now refuses with
+  `exit 6`, names the failed checks, leaves the manifest unstamped, and records `promoted_gate`.
+  `--force` is the deliberate override, recorded as `FORCED` rather than `VERIFIED`.
+- **A rebuild no longer destroys the evidence contract.** `HANDOFF.md` is regenerated on every
+  build, which erased the hand-authored `RESULT:`/`EVIDENCE:` block the gate reads — so growing a
+  session deleted the gate's own input. The block is carried across verbatim under its own heading
+  and hashed into `evidence_contract_sha256` on the manifest.
+- `verify-gate` reports a rejection in its exit code (`6`), not only in its JSON.
+
+### Added
+
+- Regression tests for all four defects above, driving the real CLI: a Claude Code transcript, a
+  Codex rollout, a mixed valid/corrupt source, a rebuild after a hand-authored contract, and the
+  promote / gate / `--force` path (39 tests, up from 34).
+
+### Fixed
+
+- `skill.json` carried the previous release version (2.0.4) while `SKILL.md`, `package.json` and
+  the installer said 2.0.5 — a published contradiction with no runtime consumer to catch it,
+  even though this changelog tells readers the two manifests carry one release version. They now
+  agree, and the suite fails if they ever diverge again.
+- `install/CHANGELOG.md` described the installer as a separate package whose first release was
+  published to npm; there is no separate installer package on the registry. It now states how
+  the installer actually ships (inside the root `agents-handoff` package), keeping the 1.x
+  entries as development history.
+
+## [2.0.4] - 2026-10-09
+
+### Added
+
+- A demo animation on the README and the documentation home page: one run installing into every
+  harness, a session captured and verified, and an installation proved against the published
+  tarball (`assets/handoff-demo.gif`).
+- **[Compatibility](https://github.com/Alot1z/agent-handoff/blob/main/docs/COMPATIBILITY.md)**
+  (`docs/COMPATIBILITY.md`) now records what was measured rather than what
+  is assumed: Node 26 verified, and Bun verified as an alternative runtime — the engine's
+  verbs run unchanged there, and the suite passes 34/34 with `bun test --timeout 30000` (Bun's
+  default 5-second per-test timeout is shorter than the suite's child-process tests). It also
+  states why the artifacts are JavaScript rather than TypeScript: the contracts are the
+  versioned JSON Schemas the runtime validates against, and a build step would put a compiler
+  between a user and a working tool.
+
+### Fixed
+
+- `--update` and `--verify` reported "no installations found" on a machine whose copies predate
+  the 2.0.3 rename, because they only looked for `agents-handoff/`. Both now recognise the
+  `agent-handoff/` directory every earlier release installed and act on it in place.
+- The global-root search missed `~/.config`, which is where a desktop client keeps its
+  account-skill store on Windows too — so that store's installation was invisible to `--list`,
+  `--update`, `--verify` and `doctor` even though the client kept reading it.
+
+### Changed
+
+- `remove` states what it keeps before asking, so its confirmation matches what it does.
+
 ## [2.0.3] - 2026-10-09
 
 ### Added
@@ -187,6 +258,10 @@ documentation site.
   [docs/PROVENANCE.md](https://github.com/Alot1z/agent-handoff/blob/main/docs/PROVENANCE.md),
   not implied.
 
-[Unreleased]: https://github.com/Alot1z/agent-handoff/compare/v2.0.1...main
+[Unreleased]: https://github.com/Alot1z/agent-handoff/compare/v2.0.5...main
+[2.0.5]: https://github.com/Alot1z/agent-handoff/compare/v2.0.1...v2.0.5
+[2.0.4]: https://www.npmjs.com/package/agents-handoff/v/2.0.4
+[2.0.3]: https://www.npmjs.com/package/agents-handoff/v/2.0.3
+[2.0.2]: https://www.npmjs.com/package/agents-handoff/v/2.0.2
 [2.0.1]: https://github.com/Alot1z/agent-handoff/compare/v2.0.0...v2.0.1
 [2.0.0]: https://github.com/Alot1z/agent-handoff/tree/v2.0.0

package/README.md

@@ -11,6 +11,13 @@ reasoning, and the provenance to prove where each byte came from — is captured
 that a fresh agent can continue from with zero shared memory. Zero runtime dependencies,
 Node.js 18 or newer, nothing read from the network at run time.
 
+![agents-handoff: one install into every harness, a verified handoff, and an installation
+proved against the published npm tarball](assets/handoff-demo.gif)
+
+*An abbreviated run of 2.0.3: `--all` installs into every harness found, a session is captured
+and verified, and `--verify-package` proves the installed copy is the published one. The sample
+session is illustrative; the command and output shapes are the real ones.*
+
 ## Install
 
 ```bash

package/SKILL.md

@@ -6,7 +6,7 @@ description: >-
   session as a portable, sha256-proven handoff folder a fresh agent can continue
   from with zero shared memory, with versioned contracts, an evidence gate, and
   backup/verify/rollback on every write. Zero runtime dependencies, no network.
-version: 2.0.3
+version: 2.0.5
 domain: orchestration
 tokens: 900
 allowed-tools: Bash(node:*), Read, Edit, Write
@@ -143,5 +143,5 @@ Dispatch re-runs the evidence gate first; carries manifest sha256; dry-run by de
 | Handoff format + schema | `docs/FORMAT.md`, `templates/` |
 | Installation | `docs/INSTALL.md` |
 
-**Version**: 2.0.0
-**Last Updated**: 2026-10-08
+**Version**: 2.0.5
+**Last Updated**: 2026-10-09

package/docs/ARCHITECTURE.md

@@ -140,10 +140,11 @@ that produced it. A probe kind with no implementation returns `unknown` rather t
 `healthy`. `check` exits non-zero when a required capability is `unknown`, because an
 unanswered question is not a pass.
 
-The same rule applies to the evidence gate. `verify-gate` returns `REJECTED` in its JSON
-when a check fails, and exits 0 either way, so the verdict has to be read rather than
-inferred from a status code. `promote` prints the gate result without enforcing it, which is
-stated in the command reference rather than left for a caller to discover.
+The same rule applies to the evidence gate. `verify-gate` returns `REJECTED` in its JSON when a
+check fails **and exits 6**, so a caller that reads only the status code still fails closed
+instead of reading a rejection as success. `promote` runs the same gate and refuses with
+`exit 6` unless `--force` is passed; a forced promotion is recorded as `promoted_gate: "FORCED"`
+so it stays distinguishable from a verified one.
 
 ## Boundaries
 

package/docs/CHANGELOG.md

@@ -19,6 +19,66 @@ version, and it is the version published to npm: the repository root is the
 
 Add entries under the matching heading as changes land.
 
+## [2.0.5] - 2026-10-09
+
+### Fixed
+
+- **Real Claude Code and Codex exports parse.** The engine read text only from a top-level
+  `text`/`content`/`parts[]`, so a genuine Claude Code transcript (`message.content[]`) or a Codex
+  CLI rollout (`payload`) produced **zero turns** while `--harness claude-code` merely labelled the
+  result. Nested blocks, `message.content[]`, `parts[]`, `item.content[]`, `output` and the Codex
+  `payload` wrapper are read now, and a record whose every typed block is a reasoning block
+  classifies as `THOUGHT`.
+- **A malformed transcript line is no longer dropped in silence.** It stops the build with
+  `exit 5`, naming the line number and reason. Dropping it produced a handoff that looked complete
+  and was missing part of the session; this restores the fail-closed rule the rest of the tool
+  already followed. `--allow-bad-lines` skips such lines deliberately and prints how many were
+  skipped.
+- **`promote` enforces the evidence gate.** It ran the gate, printed the verdict and promoted
+  regardless (`void gateRun`), so a `REJECTED` handoff was stamped as promoted. It now refuses with
+  `exit 6`, names the failed checks, leaves the manifest unstamped, and records `promoted_gate`.
+  `--force` is the deliberate override, recorded as `FORCED` rather than `VERIFIED`.
+- **A rebuild no longer destroys the evidence contract.** `HANDOFF.md` is regenerated on every
+  build, which erased the hand-authored `RESULT:`/`EVIDENCE:` block the gate reads — so growing a
+  session deleted the gate's own input. The block is carried across verbatim under its own heading
+  and hashed into `evidence_contract_sha256` on the manifest.
+- `verify-gate` reports a rejection in its exit code (`6`), not only in its JSON.
+
+### Added
+
+- Regression tests for all four defects above, driving the real CLI: a Claude Code transcript, a
+  Codex rollout, a mixed valid/corrupt source, a rebuild after a hand-authored contract, and the
+  promote / gate / `--force` path (39 tests, up from 34).
+
+## [2.0.4] - 2026-10-09
+
+### Added
+
+- A demo animation on the README and the documentation home page: one run installing into every
+  harness, a session captured and verified, and an installation proved against the published
+  tarball (`assets/handoff-demo.gif`).
+- **[Compatibility](https://github.com/Alot1z/agent-handoff/blob/main/docs/COMPATIBILITY.md)**
+  (`docs/COMPATIBILITY.md`) now records what was measured rather than what
+  is assumed: Node 26 verified, and Bun verified as an alternative runtime — the engine's
+  verbs run unchanged there, and the suite passes 34/34 with `bun test --timeout 30000` (Bun's
+  default 5-second per-test timeout is shorter than the suite's child-process tests). It also
+  states why the artifacts are JavaScript rather than TypeScript: the contracts are the
+  versioned JSON Schemas the runtime validates against, and a build step would put a compiler
+  between a user and a working tool.
+
+### Fixed
+
+- `--update` and `--verify` reported "no installations found" on a machine whose copies predate
+  the 2.0.3 rename, because they only looked for `agents-handoff/`. Both now recognise the
+  `agent-handoff/` directory every earlier release installed and act on it in place.
+- The global-root search missed `~/.config`, which is where a desktop client keeps its
+  account-skill store on Windows too — so that store's installation was invisible to `--list`,
+  `--update`, `--verify` and `doctor` even though the client kept reading it.
+
+### Changed
+
+- `remove` states what it keeps before asking, so its confirmation matches what it does.
+
 ## [2.0.3] - 2026-10-09
 
 ### Added

package/docs/CLI.md

@@ -60,6 +60,7 @@ source hash writes nothing and prints `handoff: up-to-date`.
 | 2 | Usage error, for example `build` without `--source`. |
 | 3 | The id prefix matched more than one session, or none. |
 | 4 | No match for `show`/`verify`/`rename`/`retitle`; also `build` when no turn could be parsed from the source. |
+| 5 | `build` found unparseable JSONL line(s) it would otherwise skip silently. The message names the line number and reason; pass `--allow-bad-lines` to accept the damaged source deliberately. |
 
 ## `tools/agents-handoff.mjs` — runtime layer
 
@@ -71,7 +72,7 @@ once. Behaviour per command is described in [LEVEL4.md](LEVEL4.md).
 |---|---|
 | `auto --source <file>` | Build only when the source is newer than the stored manifest; skip within `--min-fresh-ms` (default 60000). |
 | `verify-gate <id-prefix>` | Five checks: `sha`, `counts`, `payload`, `contract`, `evidence`. |
-| `promote <id-prefix>` | Stamp `promoted_at` and `promoted_by` on the manifest. |
+| `promote <id-prefix>` | Run the evidence gate and, only if it passes, stamp `promoted_at`, `promoted_by` and `promoted_gate` on the manifest. `--force` overrides a rejected gate on purpose and records `promoted_gate: "FORCED"`. |
 | `merge <a> <b>` | Compose two sessions of one project into `<a>+merge+<b>`. |
 | `dispatch <id-prefix> --task <objective>` | Hand the continuation to a worker. See [LEVEL5.md](LEVEL5.md). |
 | `federated-merge --from <root> [--from <root> …] [--dry-run]` | Import sessions from another store root. |
@@ -87,9 +88,11 @@ old one exists only so a command that already names it does not break.
 `dispatch` flags: `--task` (required), `--role` (default `implementation-agent`), `--parent`
 (default `handoff:<id>`), `--broker <root>`, `--live`.
 
-`verify-gate` exits 0 for both `VERIFIED` and `REJECTED`. Read `ok` or `verdict` from the
-JSON; the exit code alone does not report a rejection. `promote` prints the gate result but
-does not enforce it — run `verify-gate` and branch on the verdict first.
+`verify-gate` reports a rejection twice: `ok: false` and `verdict: "REJECTED"` in the JSON, and
+`exit 6`. A gate that failed is not a success, so a caller that only reads the exit code still
+fails closed. `promote` runs the same gate and **refuses** (`exit 6`) when it is rejected — pass
+`--force` to override deliberately, which is recorded in the manifest as `promoted_gate:
+"FORCED"` rather than `"VERIFIED"`.
 
 ### Exit codes
 
@@ -98,6 +101,9 @@ does not enforce it — run `verify-gate` and branch on the verdict first.
 | 0 | Success. |
 | 1 | A mutating command failed; the lock was released. |
 | 2 | Usage or configuration error, including an unresolvable store root. |
+| 3 | A lock is held, an id prefix is ambiguous, or a referenced path is missing. |
+| 4 | No session matches the prefix. |
+| 6 | An evidence gate rejected the handoff (`verify-gate` and `promote`). |
 | 3 | A lock is held, an id prefix is ambiguous or missing, or a referenced path is missing. |
 | 4 | No session matches the prefix. |
 

package/docs/COMPATIBILITY.md

@@ -37,19 +37,64 @@ dependencies.
 | 18.x | SUPPORTED (minimum) |
 | 20.x | SUPPORTED |
 | 22.x | SUPPORTED |
+| 26.x | VERIFIED (developed and released on it) |
 | < 18 | UNSUPPORTED |
 
+## Other runtimes: Bun, Deno, TypeScript
+
+The tools are plain ESM with `node:` built-ins and no dependencies, so another runtime that
+implements those APIs runs them unchanged. Bun was tested against this release:
+
+```bash
+bun tools/handoff.mjs config
+bun tools/handoff.mjs build --source transcript.jsonl --project my-project
+bun tools/handoff.mjs verify my-project          # PASS, same hashes as Node
+bun tools/agents-handoff.mjs index
+bun test --timeout 30000 tools/handoff.test.mjs  # 34 pass, 0 fail
+```
+
+One caveat, and it is a property of the runner rather than of the tools: the suite spawns child
+Node processes, and Bun's default per-test timeout is 5 seconds, so raising it
+(`--timeout 30000`) is what makes all 34 tests pass — at the default, one test times out.
+
+The published artifact is JavaScript, not TypeScript, and there is no build step to add one.
+What TypeScript would have declared — the shape of a handoff, a manifest and the LLM payload —
+is declared by the versioned JSON Schemas the runtime validates against
+(`schemas/handoff.schema.json`, `templates/HANDOFF.llm.schema.json`,
+`handoff.config.schema.json`), and `docs/CLI.md` is the interface of record for the commands.
+
 ## Input formats the engine parses
 
 | Format | How it is detected | Fields read |
 |---|---|---|
-| JSONL | `.jsonl` extension | `seq`, `ts`/`timestamp`, `role`, `kind`, and the text from `text`, `content`, or `parts[].text` |
+| JSONL | `.jsonl` extension | `seq`, `ts`/`timestamp`, `role`, `kind`/`type`, and the text from the top level (`text`, `content`, `output`), from a nested message (`message.content[]`, `message.text`), from an item array (`parts[]`, `item.content[]`), or from a Codex rollout wrapper (`payload.text`, `payload.content[]`, `payload.output`) |
 | Plain text | Any other extension | A line opening with `user:`, `human:`, `assistant:`, `ai:`, `system:` or `tool:` (or `>` instead of `:`); following lines are appended to that turn |
 
-Turn classification, in this order: `kind` containing `tool`, or `role: "tool"`, becomes `TOOL`;
-`kind` containing `reason` or `think` becomes `THOUGHT`; `role: "user"` (or `kind: "human"`) becomes
-`USER`; `role: "assistant"` (or `kind: "ai"`) becomes `AGENT`; everything else becomes `OTHER`.
-Malformed JSONL lines and turns with empty text are skipped.
+This reads the shapes harnesses actually write, not just the canonical one. Claude Code nests the
+turn under `message.content[]` (`{type:"text"}`, `{type:"thinking"}`,
+`{type:"tool_use"}`, `{type:"tool_result"}`); the Codex CLI rollout wraps each event in
+`payload` (`response_item` → `message` / `function_call` / `function_call_output`). Reading only
+top-level fields parses those exports to zero turns, which is why `--harness` is a label and not
+a parser: nothing here branches on the harness name.
+
+Turn classification, in this order: a `kind`/`type` containing `tool`, or `role: "tool"`, or
+`function_call`, becomes `TOOL`; `kind`/`type` containing `reason` or `think`, or a record whose
+every typed content block is a reasoning block, becomes `THOUGHT`; `role: "user"` (or
+`kind: "human"`) becomes `USER`; `role: "assistant"` (or `kind: "ai"`) becomes `AGENT`; everything
+else becomes `OTHER`.
+
+## Malformed and empty input
+
+The two cases are different and are not treated the same way.
+
+| Case | Behaviour |
+|---|---|
+| A JSONL line that is not valid JSON | **The build stops** with `exit 5` and names the line number and reason. Pass `--allow-bad-lines` to skip them on purpose, which prints a warning and keeps going. |
+| A line that parses but carries no user/assistant text | Counted as `skipped` — this is normal harness metadata (usage, summaries, system events), not corruption. |
+| A source where *no* turn parses at all | `exit 4`, whether or not bad lines were found. |
+
+Failing closed is deliberate. Silently dropping an unparseable line produces a handoff that looks
+complete while missing part of the session, and nothing downstream can tell the difference.
 
 ## Session sources
 
@@ -98,6 +143,9 @@ Root resolution order, first match wins: `HANDOFFS_ROOT`, then a config-declared
 | 0 | Success |
 | 1 | Integrity failure (manifest mismatch, corrupted manifest) or an unexpected error |
 | 2 | Usage error, missing source file, or an invalid config |
+| 3 | An id prefix is ambiguous, or a lock is held |
+| 4 | No usable turns were parsed, or no session matches the prefix |
+| 5 | Unparseable JSONL line(s) with `--allow-bad-lines` absent |
 | 3 | Ambiguous session-id prefix |
 | 4 | No parsable turns, no handoffs, or no match for the prefix |
 

package/docs/FORMAT.md

@@ -105,6 +105,9 @@ checks everything else, and treats the absence as neither a pass nor a failure.
 | `turn_count` | Number of turns in `timeline.jsonl` after the build. |
 | `counts` | Turn counts by class: `USER`, `AGENT`, `THOUGHT`, `TOOL`. |
 | `manifest_sha256` | Self-hash: SHA-256 of the manifest JSON with this field removed. |
+| `evidence_contract_sha256` | SHA-256 of the hand-authored evidence block carried into `HANDOFF.md`. Present only when such a block exists. This is what makes "the contract survived the rebuild" checkable rather than asserted. |
+| `promoted_at`, `promoted_by` | Set by the L4 `promote` command after its evidence gate passes. |
+| `promoted_gate` | `VERIFIED` when the gate passed, `FORCED` when `promote --force` overrode a rejection. |
 | `prev_project` | Set when `rename` moves the session to another project. |
 | `titled_from` | Previous directory names, set by `retitle`. |
 
@@ -124,16 +127,22 @@ Turn text is taken from `text`, then `content`, then `parts[].text`.
 
 ## Accepted input
 
-A source file ending in `.jsonl` is read line by line. Each line is parsed
-independently; a line that does not parse, or whose text is blank, is skipped. `seq` is used
-when it is a finite number, and the line index otherwise.
+A source file ending in `.jsonl` is read line by line. Each line is parsed independently. Text is
+taken from the top level (`text`, `content`, `output`), from a nested message
+(`message.content[]`), from an item array (`parts[]`, `item.content[]`), or from a Codex rollout
+`payload` — so a real Claude Code or Codex export parses without preprocessing. `seq` is used when
+it is a finite number, and the line index otherwise.
+
+A line that parses but whose text is blank is counted as skipped: that is normal harness metadata,
+not damage. A line that does **not** parse is treated as corruption and stops the build with
+`exit 5`, naming the line, unless `--allow-bad-lines` is passed.
 
 Any other extension is parsed as text: a line matching `user:`, `human:`, `assistant:`,
 `ai:`, `system:` or `tool:` (optionally prefixed with `#`) starts a turn, and following
 lines are appended to it. The role marker decides the class. Adapters that produce either
 shape are listed in [ADAPTERS.md](https://github.com/Alot1z/agent-handoff/blob/main/refs/ADAPTERS.md).
 
-If no turn parses, the build fails with exit 4.
+If no turn parses, the build fails with exit 4 — whether or not unparseable lines were found.
 
 ## Session id and directory name
 
@@ -156,6 +165,12 @@ Each build appends only the turns with `seq > watermark`, then sets `watermark`
 highest `seq` seen and increments `revisions`. A rebuild with no new turns and an unchanged
 `raw_sha256` prints `handoff: up-to-date` and writes nothing.
 
+A rebuild regenerates `HANDOFF.md`, so the **evidence contract is carried across verbatim**:
+the `RESULT`/`WHAT_CHANGED`/`VALIDATION`/`EVIDENCE`/`BLOCKERS`/`RISKS`/`FOLLOW_UP` block a human or
+agent authored is read from the existing `HANDOFF.md`, re-emitted under
+`## Evidence contract (hand-authored — preserved across rebuilds)`, and hashed into
+`evidence_contract_sha256`. Without that, growing a session would destroy the gate's own input.
+
 ## Provenance and verification
 
 | Value | Definition |

package/docs/INTEGRATION.md

@@ -58,7 +58,9 @@ The marker is `user|human|assistant|ai|system|tool`, optionally prefixed by `#`
 by `:` or `>`. Lines after a marker are appended to that turn until the next marker. A
 `system:` line becomes OTHER, so it stays in the record without appearing as dialogue.
 
-If no usable turn is parsed, the build fails with exit 4 rather than writing an empty handoff.
+If no usable turn is parsed, the build fails with exit 4 rather than writing an empty handoff. A
+JSONL line that does not parse fails the build with exit 5 instead of being skipped silently;
+`--allow-bad-lines` accepts a damaged source on purpose and warns about how many lines it skipped.
 
 ## Build a handoff
 
@@ -162,6 +164,7 @@ and does not detect.
 | 2 | Usage or configuration error: missing `--source`, missing argument, invalid config. |
 | 3 | Ambiguous id prefix — more than one session matched. |
 | 4 | No usable turns, no handoffs, or no session matching the prefix. |
+| 5 | Unparseable JSONL line(s), unless `--allow-bad-lines` was passed. |
 
 ## CI recipe
 

package/docs/LEVEL4.md

@@ -20,7 +20,7 @@ node tools/agents-handoff.mjs <command> [args]
 |---|---|
 | `auto --source <file>` | Build only when the source is newer than the stored manifest. |
 | `verify-gate <id-prefix>` | Five checks: sha, counts, payload, contract, evidence. |
-| `promote <id-prefix>` | Stamp promotion metadata on a handoff's manifest. |
+| `promote <id-prefix>` | Run the evidence gate, then stamp promotion metadata on a handoff's manifest if it passed. |
 | `merge <a> <b>` | Compose two sessions of one project into one handoff. |
 | `dispatch <id-prefix> --task <objective>` | Hand the continuation to a worker (Level 5). |
 | `federated-merge --from <root>` | Import sessions from another store root. |
@@ -74,16 +74,26 @@ manifest is visible as a nonzero status.
 node tools/agents-handoff.mjs promote <id-prefix>
 ```
 
-The manifest is backed up to `manifest.json.bak`, the gate above is run and its verdict is
-printed, and the manifest is then stamped with `promoted_at` and `promoted_by` and re-hashed.
+The manifest is backed up to `manifest.json.bak`, the gate above runs, and the manifest is then
+stamped with `promoted_at`, `promoted_by` and `promoted_gate` and re-hashed.
 
-Two honest caveats:
+The gate is **enforced**, not printed and discarded. A `REJECTED` verdict stops the command with
+`exit 6`, names the checks that failed, and leaves the manifest unstamped — so an unverified
+handoff cannot become a promoted one by accident:
 
-- The gate result is **printed, not enforced**. The stamp is written even when the verdict is
-  `REJECTED`; a caller that wants a gate must run `verify-gate` and branch on `verdict`
-  before calling `promote`.
-- Promotion is local. It writes one flag pair into one manifest file; it contacts no external
-  system and publishes nothing.
+```bash
+node tools/agents-handoff.mjs promote <id-prefix>
+# agents-handoff: promote refused: evidence gate REJECTED (failed: contract) — add the evidence
+# contract to HANDOFF.md, or pass --force to override deliberately
+```
+
+`--force` is the deliberate override for the cases where the gate's input genuinely does not
+apply. It still records what happened: `promoted_gate` is `VERIFIED` after a passing gate and
+`FORCED` after an override, so a forced promotion is distinguishable afterwards from a verified
+one rather than looking identical in the manifest.
+
+One honest caveat: promotion is local. It writes flag fields into one manifest file; it contacts
+no external system and publishes nothing.
 
 ## `merge` — composing two sessions
 
@@ -200,3 +210,4 @@ The state directory is `<repo>/.agents-handoff`, or `AGENT_HANDOFF_STATE_DIR` wh
 | 2 | Usage or configuration error, including an unresolvable store root. |
 | 3 | A lock is held, an id prefix is ambiguous, or a referenced path is missing. |
 | 4 | No session matches the prefix. |
+| 6 | The evidence gate rejected the handoff (`verify-gate`, and `promote` unless `--force`). |

package/docs/SECURITY.md

@@ -51,7 +51,8 @@ or as a request. Concretely:
 
 - A tool call recorded in a transcript is copied verbatim as text into `TOOLS.md`. The engine does not run it.
 - A transcript cannot change the engine's arguments, the store root, or the exit code beyond a parse failure.
-- A transcript with no parsable turns stops the run (`exit 4`). Individual malformed JSONL lines are skipped.
+- A transcript with no parsable turns stops the run (`exit 4`).
+- A malformed JSONL line stops the run (`exit 5`) and is named by line number, because a silent skip would produce a handoff that looks complete and is not. `--allow-bad-lines` is the explicit, warning-printing way to accept a damaged source.
 
 The realistic risk is not code execution but content. A handoff is a readable document that a later
 human or agent may treat as instructions, and it inherits whatever instructions the transcript

package/docs/TROUBLESHOOTING.md

@@ -94,20 +94,32 @@ for the merged session. `index` reports the same sessions as stale.
 seven contract fields — `RESULT`, `WHAT_CHANGED`, `VALIDATION`, `EVIDENCE`, `BLOCKERS`,
 `RISKS`, `FOLLOW_UP` — each starting a line.
 
-## `verify-gate` exits 0 but the verdict says REJECTED
+## `verify-gate` exits 6 and the verdict says REJECTED
 
-**Cause:** not a bug. `verify-gate` exits 0 for both verdicts so that "the gate ran" and
-"the gate passed" stay distinguishable. Read `ok` or `verdict` from the JSON.
+**Cause:** at least one of the five checks (`sha`, `counts`, `payload`, `contract`, `evidence`)
+failed. The JSON names which, and the message on stderr names them too.
 
-**Fix:** branch on the verdict in any script that calls it. The same applies to `promote`,
-which prints the gate result but stamps the manifest either way.
+**Fix:** fix the named check. The usual one is `contract`, which requires `RESULT`,
+`WHAT_CHANGED`, `VALIDATION`, `EVIDENCE`, `BLOCKERS`, `RISKS` and `FOLLOW_UP` — each starting a
+line — in `HANDOFF.md`. That block is hand-authored; a rebuild preserves it and records its
+sha256 as `evidence_contract_sha256` on the manifest.
 
-## `promote` stamped a session that is not verified
+## `promote` refused: evidence gate REJECTED
 
-**Cause:** expected behaviour, and stated in the command reference. Promotion is a local
-stamp, not an enforcement.
+**Cause:** the gate failed and promotion is gated on it, so the manifest was left unstamped.
 
-**Fix:** run `verify-gate` first and only call `promote` when the verdict is `VERIFIED`.
+**Fix:** add the evidence contract to `HANDOFF.md` (see above) and re-run. If the gate genuinely
+cannot apply — an imported session with no hand-authored contract, say — `--force` is the
+recorded override: the manifest then carries `promoted_gate: "FORCED"` instead of `"VERIFIED"`.
+
+## `build` failed with `unparseable JSONL line(s)` (exit 5)
+
+**Cause:** a line in the source is not valid JSON. It used to be dropped in silence, which
+produced a handoff that looked complete and was not.
+
+**Fix:** repair the export, or pass `--allow-bad-lines` to skip those lines on purpose. The
+warning names how many lines were skipped, so the omission is visible in the build output rather
+than buried in the result.
 
 ## `capability-registry check` fails with `unknown`
 

package/docs/index.md

@@ -10,6 +10,8 @@ or a colleague can read and continue from without the original chat. It builds f
 transcript or an adapter export, keeps a hash chain so a handoff can be re-verified, and
 merges later turns into the same session instead of duplicating it.
 
+![agents-handoff demo](https://raw.githubusercontent.com/Alot1z/agent-handoff/main/assets/handoff-demo.gif)
+
 ## Quick start
 
 ```bash

package/install/CHANGELOG.md

@@ -1,11 +1,19 @@
 # Changelog — agents-handoff
 
-The installer is a separate package from the skill. It follows the same
+The installer ships inside the root
+[`agents-handoff`](https://www.npmjs.com/package/agents-handoff) package: its
+`install/package.json` is `private` and tracks the release version, and the published
+`agents-handoff` bin points at `install/install.mjs`. There is no separate installer
+package on the npm registry (verified 2026-10-09: `agents-handoff` serves
+`0.0.0-stage`, `2.0.2`, `2.0.3`, `2.0.4`), so installer changes are recorded in the
+[root changelog](https://github.com/Alot1z/agent-handoff/blob/main/CHANGELOG.md) under
+the release version. The 1.x entries below are retained as the installer's own
+development history — they are not npm releases. Both changelogs follow the same
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format and Semantic Versioning.
 
 ## [1.1.0] — 2026-10-09
 
-First release published to npm. `npx agents-handoff` now installs the skill on a
+The installer gained a download path: `npx agents-handoff` now installs the skill on a
 machine that has neither a checkout nor an unpacked archive.
 
 ### Added

package/install/install.mjs

@@ -38,7 +38,7 @@ const API_LATEST = `https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/rele
 // `list` read back out of an installed copy. The literal below is only the fallback for the
 // run that has no tree beside it — the published package fetching an archive — and the suite
 // asserts it against SKILL.md, so a release that bumps one cannot leave the other behind.
-const FALLBACK_SKILL_VERSION = '2.0.3';
+const FALLBACK_SKILL_VERSION = '2.0.5';
 function skillVersion() {
   try {
     const md = fs.readFileSync(path.join(SOURCE_DIR, 'SKILL.md'), 'utf8');
@@ -433,6 +433,23 @@ function resolveTargets() {
   return targets;
 }
 
+// `--path X` names ONE installation exactly, and must not be widened into a machine-wide search.
+// Discovery is the answer to the BARE verb — "everything on this machine" — so `verify --path
+// ./my-copy` failing because some unrelated copy elsewhere is stale was the search leaking into
+// an explicit request. `--path` is documented as bypassing the search; this makes it true.
+function explicitTarget() {
+  if (!CUSTOM_PATH) return null;
+  const p = resolveInstallPath(LOCATION, CUSTOM_PATH);
+  return { label: 'explicit --path', dir: path.dirname(p), path: p };
+}
+// The targets a verb acts on: named harnesses/custom dirs if any were given, else the explicit
+// `--path` if one was given, else every installation found on this machine.
+function targetList() {
+  if (MULTI_TARGET) return resolveTargets();
+  const one = explicitTarget();
+  return one ? [one] : discoverInstalls();
+}
+
 // EVERY installation this machine has, not just the resolved one. `update` and `verify` with no
 // harness flag act on this list, because "keep my install current" is about the copies that
 // exist, not about the one target the resolver happens to pick: a machine can hold the same
@@ -923,9 +940,7 @@ function doRemove(installPath, force) {  log(`\nRemoving from ${installPath}...`
 // installation found on the machine is verified — the same list `update` acts on, so
 // "update everything" and "verify everything" cannot disagree about what exists.
 function verify(location, customPath) {
-  const targets = MULTI_TARGET
-    ? resolveTargets()
-    : discoverInstalls().map((t) => ({ label: t.label, dir: t.dir, path: t.path }));
+  const targets = targetList();
   if (!targets.length) {
     error('Nothing to verify: no agents-handoff installation found.\n' +
       '  Install one with: npx agents-handoff --all');
@@ -1097,9 +1112,7 @@ async function verifyPackageOne(target) {
 }
 
 async function verifyPackage() {
-  const targets = MULTI_TARGET
-    ? resolveTargets()
-    : discoverInstalls().map((t) => ({ label: t.label, dir: t.dir, path: t.path }));
+  const targets = targetList();
   if (!targets.length) {
     error('Nothing to verify: no agents-handoff installation found.\n' +
       '  Install one with: npx agents-handoff --all');

package/install/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-handoff",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "description": "Internal manifest for the in-tree installer. The published package is the repository root (agents-handoff), whose bin `agents-handoff` points here.",
   "private": true,
   "type": "module",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-handoff",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "description": "Write, verify, and hand off complete AI working sessions across any harness (Claude Code, Codex, DeepSeek Harness, plain JSONL or text logs). Cross-harness session capture with sha256 provenance and verified continuation.",
   "type": "module",
   "main": "tools/handoff.mjs",

package/skill.json

@@ -1,12 +1,12 @@
 {
   "name": "agents-handoff",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "description": "Write, verify, and hand off complete AI working sessions across any harness (Claude Code, Codex, DeepSeek Harness, plain JSONL or text logs). Cross-harness session capture + verified continuation.",
   "domain": "orchestration",
   "installer": {
     "type": "npx",
     "package": "agents-handoff",
-    "packageVersion": "2.0.3",
+    "packageVersion": "2.0.5",
     "repository": "https://github.com/Alot1z/agent-handoff",
     "installCommand": "npx agents-handoff"
   },

package/tools/agents-handoff.mjs

@@ -96,8 +96,7 @@ function cmdAuto() {
 // ---------------------------------------------------------------- verify-gate
 const CONTRACT_FIELDS = ['RESULT', 'WHAT_CHANGED', 'VALIDATION', 'EVIDENCE', 'BLOCKERS', 'RISKS', 'FOLLOW_UP'];
 
-function cmdVerifyGate() {
-  const pre = process.argv[3];
+function runVerifyGate(pre) {
   if (!pre) die(2, 'usage: verify-gate <id-prefix>');
   const { hit, man } = readManifest(pre);
   const checks = {};
@@ -130,7 +129,14 @@ function cmdVerifyGate() {
   checks.evidence = resultLine === 'DONE' && !hasEvidence ? 'FAIL' : 'PASS';
 
   const ok = Object.values(checks).every((v) => v === 'PASS');
-  console.log(JSON.stringify({ ok, verdict: ok ? 'VERIFIED' : 'REJECTED', session: hit.id, checks }, null, 2));
+  const failed = Object.keys(checks).filter((k) => checks[k] !== 'PASS');
+  return { ok, verdict: ok ? 'VERIFIED' : 'REJECTED', session: hit.id, checks, failed, hit, man };
+}
+// A REJECTED gate is not a success: the exit code carries the verdict (fail closed).
+function cmdVerifyGate() {
+  const r = runVerifyGate(process.argv[3]);
+  console.log(JSON.stringify({ ok: r.ok, verdict: r.verdict, session: r.session, checks: r.checks }, null, 2));
+  if (!r.ok) process.exit(6);
 }
 
 // ---------------------------------------------------------------- promote
@@ -144,20 +150,22 @@ function cmdPromote() {
     // Backup manifest before touching it (backup -> apply -> verify).
     const mp = path.join(hit.dir, 'manifest.json');
     fs.copyFileSync(mp, mp + '.bak');
-    // Evidence-gated: never promote a handoff whose gate failed.
-    const gateRun = (() => {
-      const saved = process.argv;
-      process.argv = ['node', 'agents-handoff.mjs', 'verify-gate', hit.id.slice(0, 16)];
-      try { cmdVerifyGate(); } catch (e) { /* capture below */ }
-      process.argv = saved;
-    })();
-    void gateRun;
-    // The verify-gate printed the verdict; a promoted handoff is marked in the manifest.
+    // Evidence-gated: never promote a handoff whose gate failed. The verdict is USED here;
+    // the previous version printed it and threw it away (`void gateRun`), so a REJECTED
+    // handoff was promoted anyway — the gate was decorative.
+    const gate = runVerifyGate(hit.id.slice(0, 16));
+    if (!gate.ok && !process.argv.includes('--force')) {
+      lock.release();
+      die(6, 'promote refused: evidence gate ' + gate.verdict +
+        (gate.failed.length ? ' (failed: ' + gate.failed.join(', ') + ')' : '') +
+        ' — add the evidence contract to HANDOFF.md, or pass --force to override deliberately');
+    }
     man.promoted_at = now();
     man.promoted_by = 'agents-handoff L4 promote';
+    man.promoted_gate = gate.ok ? 'VERIFIED' : 'FORCED';
     man.manifest_sha256 = sha(JSON.stringify((o => { delete o.manifest_sha256; return o; })(Object.assign({}, man))));
     fs.writeFileSync(mp, JSON.stringify(man, null, 2));
-    console.log(JSON.stringify({ ok: true, action: 'promoted', session: hit.id, promoted_at: man.promoted_at }));
+    console.log(JSON.stringify({ ok: true, action: 'promoted', session: hit.id, gate: man.promoted_gate, promoted_at: man.promoted_at }));
   } catch (e) {
     die(1, 'promote failed: ' + (e && e.message));
   } finally {

package/tools/handoff.mjs

@@ -29,30 +29,91 @@ const argOf = (n, f) => { const i = process.argv.indexOf(n); return i >= 0 && i
 const hasFlag = n => process.argv.includes(n);
 const fence = String.fromCharCode(96).repeat(3);
 
+// The `type` of each nested content block, if the record has a content array at all. The
+// documented rule is "kind containing reason/think becomes THOUGHT", and in a real export the
+// kind lives on the BLOCK, not on the record.
+function blockTypes(r) {
+  const pl = (r && r.payload) || {};
+  const arr = [r && r.content, r && r.parts, r && r.message && r.message.content,
+    pl.content, r && r.item && r.item.content].find(Array.isArray);
+  return (arr || []).map((p) => String((p && p.type) || '').toLowerCase()).filter(Boolean);
+}
+
 function classify(r) {
-  const k = String(r.kind || '').toLowerCase(), role = String(r.role || '').toLowerCase();
-  if (k.includes('tool') || role === 'tool') return 'TOOL';
-  if (k.includes('reason') || k.includes('think')) return 'THOUGHT';
-  if (role === 'user' || k === 'human') return 'USER';
-  if (role === 'assistant' || k === 'ai') return 'AGENT';
+  // `payload` is the Codex CLI rollout wrapper: the event type and the role live one level
+  // down, so reading only the top level mislabels (or drops) every Codex turn.
+  const pl = (r && r.payload) || {};
+  const mrole = String((r.message && r.message.role) || pl.role || '');
+  const k = String(r.kind || r.type || '').toLowerCase();
+  const kp = String(pl.kind || pl.type || '').toLowerCase();
+  const role = String(r.role || mrole || '').toLowerCase();
+  const ks = k + ' ' + kp;
+  if (ks.includes('tool') || role === 'tool' || ks.includes('function_call')) return 'TOOL';
+  if (ks.includes('reason') || ks.includes('think')) return 'THOUGHT';
+  // A record whose every typed block is reasoning is a THOUGHT turn. A record that MIXES
+  // reasoning with text/tool blocks is not — it keeps its AGENT class and keeps the text.
+  const bt = blockTypes(r);
+  if (bt.length && bt.every((t) => t.includes('think') || t.includes('reason'))) return 'THOUGHT';
+  if (role === 'user' || k === 'human' || k === 'user') return 'USER';
+  if (role === 'assistant' || k === 'ai' || k === 'assistant') return 'AGENT';
   return 'OTHER';
 }
+// One element of a nested content array: an Anthropic block, an OpenAI part, a Codex item.
+function partText(p) {
+  if (typeof p === 'string') return p;
+  if (!p || typeof p !== 'object') return '';
+  if (typeof p.text === 'string') return p.text;
+  if (typeof p.thinking === 'string') return p.thinking;
+  if (typeof p.content === 'string') return p.content;
+  if (Array.isArray(p.content)) return p.content.map(partText).filter(Boolean).join('\n');
+  if (p.type === 'tool_use') return 'tool_use ' + (p.name || '') + ' ' + JSON.stringify(p.input === undefined ? {} : p.input);
+  if (p.type === 'tool_result') return 'tool_result ' + (typeof p.content === 'string' ? p.content : JSON.stringify(p.content === undefined ? {} : p.content));
+  if (p.type === 'function_call') return 'function_call ' + (p.name || '') + ' ' + String(p.arguments || '');
+  if (p.type === 'function_call_output') return 'function_call_output ' + String(p.output || '');
+  return '';
+}
+// Real harness exports NEST the text: Claude Code keeps it under message.content[],
+// Codex/OpenAI under content[] or output[]. Reading only top-level fields is exactly
+// why --harness was a label instead of a parser; every shipped shape is read here.
 function textOf(r) {
-  if (typeof r.text === 'string') return r.text;
-  if (typeof r.content === 'string') return r.content;
-  if (Array.isArray(r.parts)) return r.parts.map(p => p && p.text ? p.text : '').join(' ');
+  if (!r || typeof r !== 'object') return '';
+  const pl = r.payload || {};
+  if (typeof r.text === 'string' && r.text.trim()) return r.text;
+  for (const v of [r.content, r.output, r.message && r.message.content, r.message && r.message.text,
+    pl.content, pl.output, pl.text, pl.message && pl.message.content]) {
+    if (typeof v === 'string' && v.trim()) return v;
+  }
+  for (const v of [r.parts, r.content, r.output, r.message && r.message.content, r.item && r.item.content,
+    pl.parts, pl.content, pl.output, pl.items]) {
+    if (Array.isArray(v)) {
+      const s = v.map(partText).filter(Boolean).join('\n').trim();
+      if (s) return s;
+    }
+  }
+  // A bare Codex function call/output carries no `content` at all — only name/arguments/output.
+  if (pl.type === 'function_call' || pl.type === 'function_call_output') return partText(pl);
   return '';
 }
+// Lines that are not valid JSON are CORRUPTION and are reported, never dropped in
+// silence (doctrine #1: fail closed on ambiguity). Lines that parse but carry no
+// user/assistant text are normal harness metadata (summaries, usage, system events)
+// and are counted as `skipped`, not as corruption.
+const fmtLines = (bs) => bs.slice(0, 5).map(b => b.line + ' (' + b.reason + ')').join(', ') + (bs.length > 5 ? ' +' + (bs.length - 5) + ' more' : '');
 function loadTurns(src) {
   const raw = fs.readFileSync(src, 'utf8');
+  const badLines = [];
+  let skipped = 0;
   if (/\.jsonl$/i.test(src)) {
-    return raw.split(/\r?\n/).filter(Boolean).map((l, i) => {
+    const turns = [];
+    raw.split(/\r?\n/).forEach((l, i) => {
+      if (!l.trim()) return;
       let r = null;
-      try { r = JSON.parse(l); } catch (e) { return null; }
+      try { r = JSON.parse(l); } catch (e) { badLines.push({ line: i + 1, reason: 'invalid JSON', sample: l.trim().slice(0, 80) }); return; }
       const t = textOf(r);
-      if (!t.trim()) return null;
-      return { seq: Number.isFinite(+r.seq) ? +r.seq : i, ts: String(r.ts || r.timestamp || ''), cls: classify(r), text: t };
-    }).filter(Boolean);
+      if (!t.trim()) { skipped++; return; }
+      return turns.push({ seq: Number.isFinite(+r.seq) ? +r.seq : i, ts: String(r.ts || r.timestamp || (r.message && r.message.created_at) || ''), cls: classify(r), text: t });
+    });
+    return { turns, badLines, skipped };
   }
   const turns = []; let cur = null;
   raw.split(/\r?\n/).forEach(l => {
@@ -60,7 +121,22 @@ function loadTurns(src) {
     if (m) { cur = { seq: turns.length, ts: '', cls: /^u|^h/i.test(m[1]) ? 'USER' : (/^a/i.test(m[1]) ? 'AGENT' : (/^tool/i.test(m[1]) ? 'TOOL' : 'OTHER')), text: m[2] }; turns.push(cur); }
     else if (cur) cur.text += '\n' + l;
   });
-  return turns.filter(t => t.text.trim());
+  return { turns: turns.filter(t => t.text.trim()), badLines, skipped };
+}
+// A hand-authored evidence contract (RESULT:/EVIDENCE:/... at line start) is the gate's
+// INPUT. Rebuilding regenerates HANDOFF.md, which used to erase it — silently destroying
+// the very input the gate requires. It is now carried across every rebuild verbatim.
+function preservedEvidence(mdPath) {
+  if (!fs.existsSync(mdPath)) return null;
+  const lines = fs.readFileSync(mdPath, 'utf8').split(/\r?\n/);
+  const isField = (l) => /^(RESULT|WHAT_CHANGED|VALIDATION|EVIDENCE|BLOCKERS|RISKS|FOLLOW_UP)\s*:/.test(l);
+  let first = -1, last = -1;
+  lines.forEach((l, i) => { if (isField(l)) { if (first < 0) first = i; last = i; } });
+  if (first < 0) return null;
+  let end = last;
+  for (let i = last + 1; i < lines.length; i++) { if (/^#{1,6}\s/.test(lines[i])) break; end = i; }
+  const block = lines.slice(first, end + 1).join('\n').replace(/\s+$/, '');
+  return block.trim() ? block : null;
 }
 const NOTICE_RE = /^(the )?(approval policy|approval|policy changed|system[: ]|notice\b|context low|<\w)/i;
 function pickObjective(turns, override) {
@@ -160,8 +236,15 @@ function build() {
   let src = argOf('--source', () => { const i = process.argv.indexOf('build'); return i >= 0 ? process.argv[i + 1] : null; });
   if (src && !fs.existsSync(src)) die(2, 'source not found: ' + src);
   if (!src) die(2, 'usage: build --source <file> [--session id] [--harness n] [--model m] [--project name] [--objective text]');
-  const turnsAll = loadTurns(src);
-  if (!turnsAll.length) die(4, 'no usable turns parsed from ' + src);
+  const parsed = loadTurns(src);
+  const turnsAll = parsed.turns;
+  if (!turnsAll.length) die(4, 'no usable turns parsed from ' + src +
+    (parsed.badLines.length ? ' — ' + parsed.badLines.length + ' unparseable line(s) at ' + fmtLines(parsed.badLines) : ''));
+  if (parsed.badLines.length && !hasFlag('--allow-bad-lines')) {
+    die(5, 'refusing to continue: ' + parsed.badLines.length + ' unparseable JSONL line(s) at ' + fmtLines(parsed.badLines) +
+      ' — fixing the input is the default (doctrine #1); pass --allow-bad-lines to skip them explicitly');
+  }
+  if (parsed.badLines.length) console.error('handoff: WARNING — skipped ' + parsed.badLines.length + ' unparseable line(s) because --allow-bad-lines was given');
   let firstRaw = null;
   try { firstRaw = JSON.parse(fs.readFileSync(src, 'utf8').split(/\r?\n/)[0]); } catch (e) {}
   const mArg = argOf('--model', () => null);
@@ -202,6 +285,9 @@ function build() {
   const stateNow = ((agents.at(-1) || users.at(-1) || { text: '(none)' }).text || '').slice(-1200);
   const openLoops = [...new Set(turns.flatMap(t => String(t.text).split(/\r?\n/)).filter(l => /(next step|todo|blocked|open loop|remaining work)/i.test(l)).map(l => l.trim()))].slice(0, 20);
   const toolCalls = turns.filter(t => t.cls === 'TOOL');
+  const evidenceBlock = preservedEvidence(path.join(dir, 'HANDOFF.md'));
+  if (evidenceBlock) man.evidence_contract_sha256 = sha(evidenceBlock);
+  else delete man.evidence_contract_sha256;
   man.watermark = Math.max(...turnsAll.map(t => t.seq));
   man.raw_sha256 = rsha;
   man.revisions++;
@@ -232,7 +318,13 @@ function build() {
     '- sources: ' + man.source_paths.join(', '),
     '- raw sha256: ' + rsha,
     '- manifest sha256: ' + man.manifest_sha256,
-    '- incremental: revisions=' + man.revisions + ' (update-not-recreate)', '');
+    '- incremental: revisions=' + man.revisions + ' (update-not-recreate)', '',
+    '## Evidence contract (hand-authored — preserved across rebuilds)', '',
+    ...(evidenceBlock
+      ? [evidenceBlock, '', '- contract sha256: ' + man.evidence_contract_sha256 +
+         ' (carried forward verbatim; the L4 gate reads this section)']
+      : ['(none yet) — add RESULT/WHAT_CHANGED/VALIDATION/EVIDENCE/BLOCKERS/RISKS/FOLLOW_UP and the next rebuild keeps it;',
+         '`agents-handoff.mjs verify-gate <id>` reads this section.']));
   fs.writeFileSync(path.join(dir, 'HANDOFF.md'), md.join('\n'));
   // TOOLS.md carries EVERY tool call verbatim (full text, never truncated) —
   // this is the lossless fidelity tier that answers "does the handoff contain all calls/bits".

package/tools/handoff.test.mjs

@@ -421,6 +421,13 @@ test('runtime: an approved workspace wins over a broad personal-data root it liv
 // out — so this test is about the tree that has one, and an installed copy skips it by name
 // rather than failing the suite that proves the installed copy works.
 const INSTALLER_SRC = path.join(REPO, 'install', 'install.mjs');
+// This file travels to the published repository, and it also runs from the authoring skill
+// tree. `package.json` is NOT one of those two trees' shared files: sync-upstream publishes an
+// allowlist of skill files, and the root package.json is authored in repo-upstream only. A
+// publish-tree assertion therefore cannot be satisfied in the authoring tree, and is named as
+// such rather than failed there. The published tree — and CI, which runs at the repo root —
+// still runs it.
+const IS_PUBLISH_TREE = fs.existsSync(path.join(REPO, 'package.json'));
 test('installer: every manifest source resolves here, and the fallback version matches SKILL.md', (t) => {
   if (!fs.existsSync(INSTALLER_SRC)) {
     return t.skip('no install/ in this tree — an installed copy omits the installer by design');
@@ -447,6 +454,16 @@ test('installer: every manifest source resolves here, and the fallback version m
   assert.ok(version, 'SKILL.md must declare a version');
   assert.equal(fallback[1], version[1],
     'installer fallback version must equal SKILL.md version');
+
+  // skill.json is PUBLISHED metadata: the changelog tells readers that package.json and
+  // skill.json carry the release version, and the installer copies it into every install.
+  // It lagged at 2.0.4 while SKILL.md and package.json said 2.0.5 — a published
+  // contradiction with no runtime consumer to catch it, so the test is the catcher.
+  const skillJson = JSON.parse(fs.readFileSync(path.join(REPO, 'skill.json'), 'utf8'));
+  assert.equal(skillJson.version, version[1],
+    'skill.json version must equal SKILL.md version');
+  assert.equal(skillJson.installer && skillJson.installer.packageVersion, version[1],
+    'skill.json installer.packageVersion must equal SKILL.md version');
 });
 
 // The published identity is one name in one manifest, and every page a user reads has to agree
@@ -457,6 +474,9 @@ test('package: the published name, the packed file list and the docs agree', (t)
   if (!fs.existsSync(INSTALLER_SRC)) {
     return t.skip('no install/ in this tree — an installed copy omits the installer by design');
   }
+  if (!IS_PUBLISH_TREE) {
+    return t.skip('authoring skill tree — the root package.json is authored in repo-upstream');
+  }
   const pkg = JSON.parse(fs.readFileSync(path.join(REPO, 'package.json'), 'utf8'));
   assert.equal(pkg.name, 'agents-handoff', 'the published package name');
   const skillMd = fs.readFileSync(path.join(REPO, 'SKILL.md'), 'utf8');
@@ -648,6 +668,33 @@ for (const t of [
       assert.ok(/not on the npm registry|unreachable/.test(r.stdout + r.stderr), 'reason: ' + r.stdout + r.stderr);
     } finally { fs.rmSync(home, { recursive: true, force: true }); }
   }],
+
+  // `--path X` names ONE installation. It used to fall through to machine-wide discovery, so
+  // `verify --path ./my-copy` reported on (and failed because of) every OTHER copy on the
+  // machine — an explicit request silently widened into a different question.
+  ['installer: verify --path checks exactly that copy, not every copy on the machine', (t) => {
+    if (noInstaller(t)) return;
+    const home = scratchHome();
+    try {
+      // A decoy the search SHOULD find and fail, so the assertion below cannot pass vacuously.
+      assert.equal(runInstaller(['--agents'], home).status, 0, 'setup: decoy install');
+      const decoy = installAt(home, '.agents');
+      fs.writeFileSync(path.join(decoy, 'SKILL.md'), 'tampered\n');
+
+      // A clean copy somewhere the search does not look.
+      const copy = path.join(home, 'elsewhere', 'agents-handoff');
+      assert.equal(runInstaller(['--path', copy], home).status, 0, 'setup: clean copy');
+
+      const scoped = runInstaller(['verify', '--path', copy], home);
+      assert.equal(scoped.status, 0, 'verify --path must ignore an unrelated stale copy: ' + scoped.stdout + scoped.stderr);
+      assert.ok(!scoped.stdout.includes(decoy), 'the out-of-scope copy is not even reported: ' + scoped.stdout);
+
+      // Discovery still works — this is what makes the assertion above meaningful.
+      const bare = runInstaller(['verify'], home);
+      assert.notEqual(bare.status, 0, 'a bare verify must still find (and fail) the tampered copy: ' + bare.stdout);
+      assert.ok(bare.stdout.includes(decoy), 'the bare verify names the copy it found: ' + bare.stdout);
+    } finally { fs.rmSync(home, { recursive: true, force: true }); }
+  }],
 ]) {
   test(t[0], t[1]);
 }
@@ -666,3 +713,186 @@ test('rebuild of identical source is idempotent (up-to-date, revision stable)',
     assert.equal(rev2, rev1, 'revision must not bump on identical rebuild');
   } finally { fs.rmSync(root, { recursive: true, force: true }); }
 });
+
+// ===========================================================================
+// REGRESSION BLOCK — the four verified defects from the 2026-10-09 audit.
+// Each of these FAILS against 2.0.4 as published; each passes here.
+// ===========================================================================
+
+// Every manifest under a scratch store root. The session directory name is derived from
+// the source basename, so tests that build from a differently-named file must not hard-code
+// 'minimal-transcript' the way sessionDir() does.
+function findManifests(root) {
+  const out = [];
+  const walk = (d) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) walk(p); else if (e.name === 'manifest.json') out.push(p);
+    }
+  };
+  const proj = path.join(root, 'projects');
+  if (fs.existsSync(proj)) walk(proj);
+  return out;
+}
+function timelineOf(manifestPath) {
+  return fs.readFileSync(path.join(path.dirname(manifestPath), 'timeline.jsonl'), 'utf8')
+    .split(/\r?\n/).filter(Boolean).map((l) => JSON.parse(l));
+}
+// The L4 runtime is a SEPARATE executable that acts on a STORE, not on a transcript.
+function runL4(args, root) {
+  return spawnSync(process.execPath, [path.join(REPO, 'tools', 'agents-handoff.mjs'), ...args], {
+    cwd: REPO,
+    env: Object.assign({}, process.env, { HANDOFFS_ROOT: root, AGENT_HANDOFF_STATE_DIR: STATE_DIR }),
+    encoding: 'utf8',
+  });
+}
+
+// Fix A — the parser read only TOP-LEVEL text/content/parts, so a real Claude Code or Codex
+// export (which NESTS the text) parsed to zero usable turns, while `--harness claude-code`
+// merely labelled the result. These are the shapes the harnesses actually write.
+test('A: a real Claude Code transcript (nested message.content[]) parses into turns', () => {
+  const root = scratch();
+  try {
+    const src = path.join(root, 'claude-code-session.jsonl');
+    fs.writeFileSync(src, [
+      JSON.stringify({ type: 'user', message: { role: 'user', content: 'Create src/sum.js exporting add(a,b).' }, timestamp: '2026-10-09T10:00:00.000Z' }),
+      JSON.stringify({ type: 'assistant', message: { role: 'assistant', content: [{ type: 'thinking', thinking: 'plan the module and its test' }] }, timestamp: '2026-10-09T10:00:01.000Z' }),
+      JSON.stringify({ type: 'assistant', message: { role: 'assistant', content: [{ type: 'text', text: 'Added src/sum.js and exported add().' }] }, timestamp: '2026-10-09T10:00:02.000Z' }),
+      JSON.stringify({ type: 'assistant', message: { role: 'assistant', content: [{ type: 'tool_use', id: 't1', name: 'Write', input: { file_path: 'src/sum.js' } }] }, timestamp: '2026-10-09T10:00:03.000Z' }),
+    ].join('\n') + '\n');
+    const r = run(['build', '--source', src, '--project', 'cc-proj', '--harness', 'claude-code'], root);
+    assert.equal(r.status, 0, 'the real Claude Code shape must build: ' + r.stderr);
+    const mans = findManifests(root);
+    assert.equal(mans.length, 1, 'exactly one session built, got ' + mans.length);
+    const tl = timelineOf(mans[0]);
+    assert.equal(tl.length, 4, 'all four Claude Code records become turns, got ' + tl.length);
+    assert.deepEqual(tl.map((t) => t.class), ['USER', 'THOUGHT', 'AGENT', 'AGENT']);
+    assert.ok(tl[0].text.includes('Create src/sum.js'), 'the nested user text is kept');
+    assert.ok(tl[2].text.includes('Added src/sum.js'), 'the nested text block is kept: ' + tl[2].text);
+    assert.ok(tl[3].text.includes('tool_use Write'), 'the nested tool_use call is kept: ' + tl[3].text);
+  } finally { fs.rmSync(root, { recursive: true, force: true }); }
+});
+
+// The Codex CLI rollout wraps every event in `payload`. Reading only the top level loses the
+// type AND the role, so a Codex session recorded nothing at all.
+test('A: a Codex CLI rollout (payload-nested) parses, and its calls classify as TOOL', () => {
+  const root = scratch();
+  try {
+    const src = path.join(root, 'rollout-codex.jsonl');
+    fs.writeFileSync(src, [
+      JSON.stringify({ timestamp: '2026-10-09T11:00:00.000Z', type: 'response_item', payload: { type: 'message', role: 'user', content: [{ type: 'input_text', text: 'Run the full test suite.' }] } }),
+      JSON.stringify({ timestamp: '2026-10-09T11:00:01.000Z', type: 'response_item', payload: { type: 'function_call', name: 'shell', arguments: '{"command":["node","tools/handoff.test.mjs"]}' } }),
+      JSON.stringify({ timestamp: '2026-10-09T11:00:02.000Z', type: 'response_item', payload: { type: 'function_call_output', output: 'tests 34 pass 34' } }),
+      JSON.stringify({ timestamp: '2026-10-09T11:00:03.000Z', type: 'response_item', payload: { type: 'message', role: 'assistant', content: [{ type: 'output_text', text: 'All 34 tests pass.' }] } }),
+    ].join('\n') + '\n');
+    const r = run(['build', '--source', src, '--project', 'codex-proj', '--harness', 'codex'], root);
+    assert.equal(r.status, 0, 'the Codex rollout shape must build: ' + r.stderr);
+    const tl = timelineOf(findManifests(root)[0]);
+    assert.equal(tl.length, 4, 'all four Codex records become turns, got ' + tl.length);
+    assert.deepEqual(tl.map((t) => t.class), ['USER', 'TOOL', 'TOOL', 'AGENT']);
+    assert.ok(tl[1].text.includes('function_call shell'), 'the call and its arguments are kept: ' + tl[1].text);
+    assert.ok(tl[2].text.includes('34 pass 34'), 'the call output is kept: ' + tl[2].text);
+  } finally { fs.rmSync(root, { recursive: true, force: true }); }
+});
+
+// Fix B — a malformed JSONL line used to be dropped in SILENCE (`return null`), which turns
+// corruption into a quietly incomplete handoff. Doctrine #1 is fail-closed on ambiguity.
+test('B: unparseable JSONL lines fail closed (exit 5) and name the line; --allow-bad-lines is explicit', () => {
+  const root = scratch();
+  try {
+    const src = path.join(root, 'mixed.jsonl');
+    fs.writeFileSync(src, [
+      JSON.stringify({ role: 'user', text: 'Do the thing.' }),
+      '{"role": "assistant", "text": ',
+      JSON.stringify({ role: 'assistant', text: 'Done.' }),
+    ].join('\n') + '\n');
+    const strict = run(['build', '--source', src, '--project', 'mixed'], root);
+    assert.equal(strict.status, 5, 'a mixed file must fail closed, got ' + strict.status + ' ' + strict.stderr);
+    assert.ok(/unparseable JSONL line\(s\) at 2 \(invalid JSON\)/.test(strict.stderr), 'the bad LINE is named: ' + strict.stderr);
+    const lax = run(['build', '--source', src, '--project', 'mixed', '--allow-bad-lines'], root);
+    assert.equal(lax.status, 0, '--allow-bad-lines proceeds: ' + lax.stderr);
+    assert.ok(/WARNING — skipped 1 unparseable line/.test(lax.stderr), 'the skip is announced, never silent: ' + lax.stderr);
+    assert.equal(timelineOf(findManifests(root)[0]).length, 2, 'the two good turns are the handoff');
+  } finally { fs.rmSync(root, { recursive: true, force: true }); }
+});
+
+// Fix D — HANDOFF.md is the gate's INPUT (the gate reads RESULT:/EVIDENCE: out of it), but a
+// rebuild regenerated the file and erased the hand-authored contract, destroying the very
+// input the next gate run needs.
+test('D: a hand-authored evidence contract survives a rebuild and is hashed into the manifest', () => {
+  const root = scratch();
+  try {
+    const src = path.join(root, 'growing.jsonl');
+    fs.copyFileSync(FIXTURE, src);
+    assert.equal(run(['build', '--source', src, '--project', 'ev-proj'], root).status, 0, 'setup build');
+    const manP = findManifests(root)[0];
+    const mdP = path.join(path.dirname(manP), 'HANDOFF.md');
+    assert.ok(/\(none yet\)/.test(fs.readFileSync(mdP, 'utf8')), 'a fresh handoff still has no contract');
+    const contract = [
+      'RESULT: PARTIAL',
+      'WHAT_CHANGED: src/sum.js added',
+      'VALIDATION: node --test tools/handoff.test.mjs',
+      'EVIDENCE: dist/sum.js sha256=abc123',
+      'BLOCKERS: none',
+      'RISKS: none',
+      'FOLLOW_UP: wire sum() into the CLI', ''].join('\n');
+    fs.appendFileSync(mdP, '\n' + contract);
+    // Grow the source so the rebuild is a REAL rewrite, not the up-to-date short circuit.
+    fs.appendFileSync(src, JSON.stringify({ seq: 9, ts: '2026-10-09T12:00:00Z', role: 'assistant', text: 'Wired sum() into the CLI.' }) + '\n');
+    const b2 = run(['build', '--source', src, '--project', 'ev-proj'], root);
+    assert.equal(b2.status, 0, 'rebuild: ' + b2.stderr);
+    assert.ok(!b2.stdout.includes('up-to-date'), 'the rebuild must actually rewrite HANDOFF.md: ' + b2.stdout);
+    const md2 = fs.readFileSync(mdP, 'utf8');
+    for (const field of ['RESULT:', 'WHAT_CHANGED:', 'VALIDATION:', 'EVIDENCE:', 'BLOCKERS:', 'RISKS:', 'FOLLOW_UP:']) {
+      assert.ok(md2.includes(field), field + ' was destroyed by the rebuild');
+    }
+    assert.ok(md2.includes('dist/sum.js sha256=abc123'), 'the evidence VALUE survived verbatim');
+    const man = JSON.parse(fs.readFileSync(manP, 'utf8'));
+    assert.ok(/^[0-9a-f]{64}$/.test(man.evidence_contract_sha256 || ''), 'the contract is hashed into the manifest: ' + man.evidence_contract_sha256);
+  } finally { fs.rmSync(root, { recursive: true, force: true }); }
+});
+
+// Fix C — `promote` called the gate, printed its verdict and threw it away (`void gateRun`),
+// so a REJECTED handoff was promoted anyway: the gate was decorative.
+test('C: promote refuses a handoff whose evidence gate FAILED; --force is the auditable override', () => {
+  const root = scratch();
+  try {
+    assert.equal(run(['build', '--source', FIXTURE, '--project', 'gate-proj'], root).status, 0, 'setup build');
+    const manP = findManifests(root)[0];
+    const id = JSON.parse(fs.readFileSync(manP, 'utf8')).session;
+    const pre = id.slice(0, 16);
+
+    // (1) no contract at all → the gate FAILS and the EXIT CODE carries that verdict.
+    const g1 = runL4(['verify-gate', pre], root);
+    assert.equal(g1.status, 6, 'a REJECTED gate must not exit 0: ' + g1.stdout + g1.stderr);
+    assert.equal(JSON.parse(g1.stdout).verdict, 'REJECTED', 'verdict: ' + g1.stdout);
+
+    // (2) promote must REFUSE. This is the defect: it used to print REJECTED and promote.
+    const p1 = runL4(['promote', pre], root);
+    assert.equal(p1.status, 6, 'promote must refuse a failed gate, got ' + p1.status + ' ' + p1.stdout + p1.stderr);
+    assert.ok(/promote refused: evidence gate REJECTED/.test(p1.stderr), 'the refusal names the gate: ' + p1.stderr);
+    assert.equal(JSON.parse(fs.readFileSync(manP, 'utf8')).promoted_at, undefined, 'a refused promote must not mark the manifest');
+
+    // (3) --force is deliberate and RECORDED as forced, never as verified.
+    const p2 = runL4(['promote', pre, '--force'], root);
+    assert.equal(p2.status, 0, 'the override proceeds: ' + p2.stdout + p2.stderr);
+    assert.equal(JSON.parse(p2.stdout).gate, 'FORCED', 'an override is recorded as FORCED: ' + p2.stdout);
+
+    // (4) the positive control: with a real contract the gate PASSES and promote carries VERIFIED.
+    const mdP = path.join(path.dirname(manP), 'HANDOFF.md');
+    fs.appendFileSync(mdP, '\n' + [
+      'RESULT: PARTIAL',
+      'WHAT_CHANGED: src/sum.js added',
+      'VALIDATION: node --test tools/handoff.test.mjs',
+      'EVIDENCE: dist/sum.js sha256=abc123',
+      'BLOCKERS: none',
+      'RISKS: none',
+      'FOLLOW_UP: wire sum() into the CLI', ''].join('\n'));
+    const g2 = runL4(['verify-gate', pre], root);
+    assert.equal(g2.status, 0, 'a complete contract must pass the gate: ' + g2.stdout + g2.stderr);
+    assert.equal(JSON.parse(g2.stdout).verdict, 'VERIFIED');
+    const p3 = runL4(['promote', pre], root);
+    assert.equal(p3.status, 0, 'a verified handoff promotes without --force: ' + p3.stdout + p3.stderr);
+    assert.equal(JSON.parse(p3.stdout).gate, 'VERIFIED', 'a clean gate records VERIFIED: ' + p3.stdout);
+  } finally { fs.rmSync(root, { recursive: true, force: true }); }
+});