From 133e9d3f0aef9846a10796a52fe81c894240d8dc Mon Sep 17 00:00:00 2001
From: Sean Goodwin <dealappseo@gmail.com>
Date: Sun, 8 Nov 2026 14:55:15 -0800
Subject: [PATCH 1/4] feat(cli): trust-report and a clean-install E2E for
 testing your own agent

Two paths, kept apart. Path 1 compares what an agent said with GitHub's
record of a run and needs no access to the agent. Path 2 covers only
commands started through trustshell run. trust-report joins them into one
readable report with its evidence, and verify proves the folder is whole,
matches that evidence and was sealed by a pinned key.

scripts/release-e2e.mjs packs the release, installs it into an empty folder
with no keys and runs each step in every shell, tracing the network.

run no longer prints started for a command that could not start.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/release-e2e.yml |  43 +++
 CHANGELOG.md                      |   2 +
 README.md                         |   1 +
 dist/cli/guard.d.ts               |   3 +
 dist/cli/guard.js                 |  16 +-
 dist/cli/index.d.ts               |   3 +-
 dist/cli/index.js                 |  16 +
 dist/cli/trust-report.d.ts        | 101 +++++
 dist/cli/trust-report.js          | 542 +++++++++++++++++++++++++++
 dist/lib/guardrails.d.ts          |   3 +-
 dist/lib/guardrails.js            |   2 +-
 examples/own-agent/README.md      | 104 ++++++
 package.json                      |   1 +
 scripts/check-egress.cjs          |   2 +
 scripts/release-e2e-summary.mjs   |  14 +
 scripts/release-e2e.mjs           | 476 ++++++++++++++++++++++++
 src/cli/guard.ts                  |  16 +-
 src/cli/index.ts                  |  18 +
 src/cli/trust-report.ts           | 586 ++++++++++++++++++++++++++++++
 src/lib/guardrails.ts             |   4 +-
 tests/trust-report.test.ts        | 232 ++++++++++++
 21 files changed, 2172 insertions(+), 13 deletions(-)
 create mode 100644 .github/workflows/release-e2e.yml
 create mode 100644 dist/cli/trust-report.d.ts
 create mode 100644 dist/cli/trust-report.js
 create mode 100644 examples/own-agent/README.md
 create mode 100644 scripts/release-e2e-summary.mjs
 create mode 100644 scripts/release-e2e.mjs
 create mode 100644 src/cli/trust-report.ts
 create mode 100644 tests/trust-report.test.ts

diff --git a/.github/workflows/release-e2e.yml b/.github/workflows/release-e2e.yml
new file mode 100644
index 00000000..9f4479be
--- /dev/null
+++ b/.github/workflows/release-e2e.yml
@@ -0,0 +1,43 @@
+# Installs the packed release into an empty folder and drives it as a new developer would: no account, no key,
+# no secret of ours. It runs on each operating system because the commands have to work the same in each shell.
+name: release-e2e
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  e2e:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+      # Exit 2 means NOT_CHECKED: shared runner addresses are often rate-limited by GitHub's anonymous API. That is
+      # reported as a warning and never as a pass; the step summary lists which steps did not run.
+      - name: Clean-install E2E
+        shell: bash
+        run: |
+          set +e
+          node scripts/release-e2e.mjs --out e2e-out
+          code=$?
+          node scripts/release-e2e-summary.mjs e2e-out >> "$GITHUB_STEP_SUMMARY"
+          if [ "$code" = "2" ]; then echo "::warning::some steps were NOT_CHECKED; see the summary"; exit 0; fi
+          exit $code
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: e2e-${{ matrix.os }}
+          path: e2e-out
+          if-no-files-found: ignore
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 26d23098..ecb16a87 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,8 @@ All notable changes to the `@hyperdag/trustshell` package.
 
 `package.json` on main is `1.9.0-dev.0`: main is ahead of the published 1.8.0, and nothing below is in any npm release.
 
+- **`trustshell trust-report`: one report for testing your own agent.** It joins what the agent said about a GitHub Actions run (`check --out` records) with every command that went through `trustshell run`, and keeps the two apart. It says what to do next and what it cannot see. `trust-report verify` proves the folder is whole, matches its evidence and was sealed by a key you pin. See `examples/own-agent`.
+- **Fix: `trustshell run` no longer prints "started" for a command that could not start.** On Windows it also says why a `.cmd` shim such as npm cannot be started directly.
 - **Fix: `guardedX402Payment` decides every refusal before it writes the pre-pay receipt.** The order was receipt, then `buildX402Payment`, so a payment the Guard denied (#665), the cap refused, or a bad address, key or nonce stopped left a receipt for a payment that never happened. Now it is decide (`prepareX402Payment`: amount, cap, address, key, typed data, then the Guard's spend decision), receipt, sign. One Guard decision and one count per payment, as before. **Behaviour change:** if the receipt writer then throws, nothing is signed but the amount stays counted in the Guard ledger (the ledger is append-only and has no release record), so it can read higher than what was signed, never lower; before, a receipt failure counted nothing. `buildX402Payment` is unchanged for direct callers. `prepareX402Payment` (src/lib/x402-prepare.ts) is internal: the package root does not export it, and the `sign()` it returns is single-use (a second call throws), so one Guard decision buys one signature. tests/guard-before-prepay-receipt.test.ts, tests/x402-prepare-internal.test.ts.
 - **Guard + Carry, experimental (#593).** `trustshell guard` and `trustshell run` add a local owner policy enforced only on the paths they mediate. `trustshell bundle` adds a signed (not encrypted) bundle that carries a profile, a policy and selected notes to another host. These are local guardrails for cooperative agents, not a tamper-resistant boundary: anyone who can run the CLI as the owner can change the policy, and OS commands are not mediated (MCP tool calls are, since IS-P0-5 below).
 - **Guard now decides every MCP tool call (IS-P0-5, containment row C3).** `trustshell-mcp` read no policy, so an agent acting through MCP did what the CLI gate refused. Now each tool call is decided by the CLI's own decision and recorded in the same `guard-receipts.jsonl` (origin `Mcp`) before the tool runs, from the policy in the server's `TRUSTSHELL_HOME`, re-read per call (so `guard kill` stops the next call without a restart). Each tool maps to the CLI command it mirrors (`MCP_GUARD_TOOLS` in `src/mcp/index.ts`: `recall` is `tool:recall`, `get_repid` is `tool:repid`, `inspect_run` and `check_claim` are `tool:check`). A policy that does not parse, is killed or expired, or cannot be read refuses; no policy at all changes nothing, as at the CLI. **Behaviour change:** an MCP user with a restrictive policy is now refused where they were not; under the policy `guard init` writes, only the local tools (ground, learn, quarantine, recall, remember) run over MCP. tests/mcp-guard.test.ts.
diff --git a/README.md b/README.md
index d5d0c8bd..f426ef8b 100644
--- a/README.md
+++ b/README.md
@@ -666,6 +666,7 @@ to the HyperDAG backend's classify endpoint and nothing else):
 | `ground` | **none** — reads the `--source` file. Since 1.7.0 | none |
 | `init` | **none** — writes one local file. `--pai` runs `scripts/init-pai.mjs` (live register) | none |
 | `report` | **none** — it has no fetch and no URL parameter | none |
+| `trust-report` | **none** — reads the Guard records and the `check` records you name, and writes one new folder | none |
 | `profile` | **none** — reads and writes `.trustshell/profile.md`. Since 1.8.0 | none |
 | `remember` | **none** — writes the local memory file | none |
 | `recall` | **none** — reads the local memory file | none |
diff --git a/dist/cli/guard.d.ts b/dist/cli/guard.d.ts
index 5cba4d41..bb3280bb 100644
--- a/dist/cli/guard.d.ts
+++ b/dist/cli/guard.d.ts
@@ -52,6 +52,7 @@ export interface Spawner {
     (cmd: string, args: string[]): {
         status: number | null;
         signal: string | null;
+        error?: string;
     };
 }
 export declare const RUN_USAGE = "trustshell run --tool <name> [--class read|other|post|spend] [--amount <n>] [--sandbox [--runtime runc|runsc]] [--json] -- <command> [args...]";
@@ -60,6 +61,8 @@ export declare const RUN_USAGE = "trustshell run --tool <name> [--class read|oth
  * `run --tool git -- git status` arrived as `run --tool git git status` and failed "unexpected git" with no
  * hint (stranger walk, 2026-10-23, PS 5.1). Quoted, or through the `.cmd` shim, the `--` survives.
  */
+/** Windows starts only real executables without a shell, and `run` never uses a shell: that would let arguments start other commands. */
+export declare const RUN_WINDOWS_SHIM = "On Windows a .cmd shim such as npm or npx cannot be started directly. Start the script it wraps instead: pin it, then trustshell run --tool node '--' node <script>.";
 export declare const RUN_POWERSHELL = "In Windows PowerShell write the -- quoted, '--' (trustshell run --tool git '--' git status), or call trustshell.cmd: PowerShell drops a bare -- before trustshell sees it.";
 /** `trustshell run`. The command's own output goes to the terminal; the card goes to stderr (or --json to stdout). */
 export declare function runRun(argv: string[], io: IO, env?: NodeJS.ProcessEnv, spawn?: Spawner, sandboxExec?: Exec): number;
diff --git a/dist/cli/guard.js b/dist/cli/guard.js
index 6b24cc9a..5ad9500f 100644
--- a/dist/cli/guard.js
+++ b/dist/cli/guard.js
@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LEVEL_IS_NOT = exports.GUARD_USAGE = exports.RUN_POWERSHELL = exports.RUN_USAGE = exports.CHECK_SCOPE = exports.POLICY_SCOPE = exports.SANDBOX_RUN_SCOPE = exports.RUN_SCOPE = exports.CLI_SCOPE = exports.NEVER_GUARDED = exports.EXIT_REFUSED = void 0;
+exports.LEVEL_IS_NOT = exports.GUARD_USAGE = exports.RUN_POWERSHELL = exports.RUN_WINDOWS_SHIM = exports.RUN_USAGE = exports.CHECK_SCOPE = exports.POLICY_SCOPE = exports.SANDBOX_RUN_SCOPE = exports.RUN_SCOPE = exports.CLI_SCOPE = exports.NEVER_GUARDED = exports.EXIT_REFUSED = void 0;
 exports.recordPolicyChange = recordPolicyChange;
 exports.plannedAction = plannedAction;
 exports.runGuarded = runGuarded;
@@ -117,7 +117,11 @@ function formatRunCard(decision, outcome, doc = null, own = null) {
     const by = d.authorized.policy_signed_by;
     const signed = by ? (by === own ? 'owner-signed' : `signed by ${by.slice(0, 16)}…, NOT this install's key`) : doc?.signature ? guardrails_1.SIGNATURE_DOES_NOT_VERIFY : 'unsigned';
     const ex = outcome?.executed;
-    const executed = ex && ex !== 'not run' ? `started; exited ${ex.exit_code ?? `on signal ${ex.signal}`} after ${ex.duration_ms} ms` : 'not run';
+    const executed = ex && ex !== 'not run'
+        ? ex.exit_code === null && ex.signal === null
+            ? `could not start (${ex.start_error ?? 'unknown error'})`
+            : `started; exited ${ex.exit_code ?? `on signal ${ex.signal}`} after ${ex.duration_ms} ms`
+        : 'not run';
     const exe = d.requested.executable;
     const pinnedExe = exe !== undefined && (doc?.policy.executables ?? []).some((p) => p.tool === exe);
     const identity = exe === undefined
@@ -141,7 +145,7 @@ function formatRunCard(decision, outcome, doc = null, own = null) {
 const nodeSpawner = (cmd, args) => {
     const { spawnSync } = require('node:child_process');
     const r = spawnSync(cmd, args, { stdio: 'inherit', windowsHide: true });
-    return { status: r.status, signal: r.signal ?? null };
+    return { status: r.status, signal: r.signal ?? null, error: r.error ? (r.error.code ?? r.error.message) : undefined };
 };
 exports.RUN_USAGE = 'trustshell run --tool <name> [--class read|other|post|spend] [--amount <n>] [--sandbox [--runtime runc|runsc]] [--json] -- <command> [args...]';
 /**
@@ -149,6 +153,8 @@ exports.RUN_USAGE = 'trustshell run --tool <name> [--class read|other|post|spend
  * `run --tool git -- git status` arrived as `run --tool git git status` and failed "unexpected git" with no
  * hint (stranger walk, 2026-10-23, PS 5.1). Quoted, or through the `.cmd` shim, the `--` survives.
  */
+/** Windows starts only real executables without a shell, and `run` never uses a shell: that would let arguments start other commands. */
+exports.RUN_WINDOWS_SHIM = "On Windows a .cmd shim such as npm or npx cannot be started directly. Start the script it wraps instead: pin it, then trustshell run --tool node '--' node <script>.";
 exports.RUN_POWERSHELL = "In Windows PowerShell write the -- quoted, '--' (trustshell run --tool git '--' git status), or call trustshell.cmd: PowerShell drops a bare -- before trustshell sees it.";
 const isHelp = (a) => a === '--help' || a === '-h' || a === 'help';
 /** `trustshell run`. The command's own output goes to the terminal; the card goes to stderr (or --json to stdout). */
@@ -260,10 +266,12 @@ function runRun(argv, io, env = process.env, spawn = nodeSpawner, sandboxExec =
         kind: 'outcome',
         requested: g.record.requested,
         authorized: g.record.authorized,
-        executed: { exit_code: r.status, signal: r.signal, duration_ms: Date.now() - t0 },
+        executed: { exit_code: r.status, signal: r.signal, duration_ms: Date.now() - t0, ...(r.error ? { start_error: r.error } : {}) },
         assurance_scope: exports.RUN_SCOPE,
     });
     (json ? io.out : io.err)(json ? JSON.stringify({ decision: g.record, outcome }, null, 2) : formatRunCard(g.record, outcome, g.loaded.state === 'ok' ? g.loaded.doc : null, own));
+    if (r.error === 'ENOENT' && process.platform === 'win32')
+        io.err(exports.RUN_WINDOWS_SHIM);
     return r.status ?? 3;
 }
 /** C2: Guard has ALLOWED the command; it starts only in a mission container, never on this host. */
diff --git a/dist/cli/index.d.ts b/dist/cli/index.d.ts
index 91edda8a..ac792c48 100644
--- a/dist/cli/index.d.ts
+++ b/dist/cli/index.d.ts
@@ -53,7 +53,7 @@ export declare const EXIT: {
     /** The owner policy (~/.trustshell/policy.json) denied the action. Nothing ran. */
     readonly REFUSED: 5;
 };
-export type Command = 'verify' | 'evaluate' | 'repid' | 'proof' | 'badge' | 'check' | 'receipt' | 'verify-receipt' | 'sign-receipt' | 'demo' | 'inspect' | 'init' | 'report' | 'profile' | 'status' | 'remember' | 'recall' | 'redact' | 'quarantine' | 'bind-status' | 'traps' | 'ground' | 'erc8004' | 'learn' | 'bundle' | 'guard' | 'run' | 'sandbox' | 'help' | 'version';
+export type Command = 'verify' | 'evaluate' | 'repid' | 'proof' | 'badge' | 'check' | 'receipt' | 'verify-receipt' | 'sign-receipt' | 'demo' | 'inspect' | 'init' | 'report' | 'profile' | 'status' | 'remember' | 'recall' | 'redact' | 'quarantine' | 'bind-status' | 'traps' | 'ground' | 'erc8004' | 'learn' | 'bundle' | 'guard' | 'run' | 'trust-report' | 'sandbox' | 'help' | 'version';
 /** Result of parsing argv (everything after `node cli.js`). Pure + testable. */
 export interface ParsedArgs {
     command: Command;
@@ -131,6 +131,7 @@ export interface ParsedArgs {
     guardArgv?: string[];
     /** run: everything after `run`, parsed by src/cli/guard.ts (its options, then `--`, then the command). */
     runArgv?: string[];
+    trustReportArgv?: string[];
     /** sandbox: everything after `sandbox`, parsed by src/sandbox/run.ts (promote <mission>). */
     sandboxArgv?: string[];
     /** profile: the parsed subcommand (show / add / set / remove / interview). */
diff --git a/dist/cli/index.js b/dist/cli/index.js
index c2598273..4238d3c0 100644
--- a/dist/cli/index.js
+++ b/dist/cli/index.js
@@ -91,6 +91,7 @@ const guardrails_1 = require("../lib/guardrails");
 const api_url_1 = require("../lib/api-url");
 const install_key_1 = require("../lib/install-key");
 const decode_text_1 = require("../lib/decode-text");
+const trust_report_1 = require("./trust-report");
 const owner_receipt_1 = require("../lib/owner-receipt");
 /** Exit codes — a small, stable contract so CI scripts can branch on them. */
 exports.EXIT = {
@@ -375,6 +376,16 @@ COMMANDS
                              The chain (default base).
       [--payment <txHash>]   The payment to check. Default: the feedbackHash, read as a
                              transaction. The feedback file is never fetched.
+  trust-report --out <new dir> [--record <record.json>]... [--bind "<tool or script>=<claim>"]...
+                             One readable report and its evidence: what the agent said, checked against
+                             GitHub (from check --out records), and every command that went through
+                             trustshell run. It cannot see anything the agent did any other way. No
+                             network. EXIT 0 every claim SUPPORTED, 1 a claim CONTRADICTED or a broken
+                             record, 3 anything NOT_CHECKED. --bind pairs a claim with the command that
+                             decides it.
+  trust-report verify <dir> [--root <key>]
+                             Prove the folder is whole and matches its evidence. EXIT 0 VERIFIED, 1 FAILED,
+                             2 NOT_CHECKED (no --root, so who made it was not checked).
   report                     State what your log and your saved GitHub evidence TOGETHER
                              support, and where they disagree. NO NETWORK — evidence is a
                              file you produced. CONFIRMED (0) / INCONSISTENT (1) /
@@ -462,6 +473,8 @@ function parseArgs(argv) {
         return { command: 'run', runArgv: argv.slice(1), json: false, verify: false };
     if (argv[0] === 'sandbox')
         return { command: 'sandbox', sandboxArgv: argv.slice(1), json: false, verify: false };
+    if (argv[0] === 'trust-report')
+        return { command: 'trust-report', trustReportArgv: argv.slice(1), json: false, verify: false };
     const flags = new Set();
     const positionals = [];
     // Options that consume the NEXT argument. Indexed rather than for-of because a
@@ -1097,6 +1110,9 @@ async function run(args, client, io = realIO) {
         case 'run':
             // Starts the caller's command only after the policy allows it.
             return (0, guard_1.runRun)(args.runArgv ?? [], io);
+        case 'trust-report':
+            // Local files only. Opens no socket.
+            return (0, trust_report_1.runTrustReport)(args.trustReportArgv ?? [], io);
         case 'sandbox':
             // Local files only: the owner step that promotes a `run --sandbox` mission's quarantined outbox.
             return (0, run_1.sandboxCli)(args.sandboxArgv ?? [], io);
diff --git a/dist/cli/trust-report.d.ts b/dist/cli/trust-report.d.ts
new file mode 100644
index 00000000..16ba7b94
--- /dev/null
+++ b/dist/cli/trust-report.d.ts
@@ -0,0 +1,101 @@
+import { type SealableReceipt } from '../lib/owner-receipt';
+export declare const TRUST_REPORT_SCHEMA: "dev.trustshell.trust-report/0.1-draft";
+export declare const TRUST_REPORT_USAGE = "trustshell trust-report --out <new dir> [--record <record.json>]... [--bind \"<tool or script>=<claim>\"]... [--title <text>] [--json]\ntrustshell trust-report verify <dir> [--root <0x key>] [--json]";
+export declare const NOT_MEDIATED_ALWAYS = "Anything the agent did without `trustshell run`: edits it made directly, its own network calls, commands in another terminal. This report cannot see them.";
+export interface Bind {
+    claim: string;
+    decided_by: string;
+    tool: string | null;
+    script_sha256: string | null;
+}
+export interface InspectRow {
+    path: string;
+    run_url: string;
+    repo: string;
+    run_id: number;
+    head_sha: string;
+    conclusion: string | null;
+    verdict: string;
+    fetched_at: string;
+    digest: string;
+    digest_matches: boolean;
+    exit: number;
+    claims: {
+        status: string;
+        claim: string;
+        scope: string;
+    }[];
+}
+export interface CommandRow {
+    seq: number;
+    ts: string;
+    action: string;
+    script_sha256: string | null;
+    command_sha256: string | null;
+    decision: string;
+    reasons: string[];
+    result: string;
+    exit_code: number | null;
+}
+export interface BoundClaim {
+    claim: string;
+    decided_by: string;
+    status: 'SUPPORTED' | 'CONTRADICTED' | 'NOT_CHECKED';
+    why: string;
+    record_seq: number | null;
+}
+export interface TrustReport {
+    schema: typeof TRUST_REPORT_SCHEMA;
+    title: string;
+    generated_at: string;
+    generator: string;
+    inputs: {
+        binds: Bind[];
+        records: string[];
+    };
+    inspect: InspectRow[];
+    guard: {
+        policy: {
+            state: string;
+            sha256: string | null;
+            nonce: string | null;
+            signed: boolean;
+            actions: string[];
+        };
+        ledger: {
+            verdict: string;
+            count: number;
+            breaks: string[];
+        };
+        commands: CommandRow[];
+        mediated: string[];
+        not_mediated: string[];
+    };
+    bound_claims: BoundClaim[];
+    next_actions: string[];
+    exit: number;
+}
+export interface BuildInput {
+    title: string;
+    generatedAt: string;
+    generator: string;
+    binds: Bind[];
+    records: {
+        path: string;
+        text: string;
+    }[];
+    ledgerText: string;
+    policyText: string | null;
+}
+/** PURE. The whole report, from its inputs. `verify` calls this again to prove the report matches its evidence. */
+export declare function buildTrustReport(input: BuildInput): TrustReport;
+export declare function renderTrustReportMarkdown(r: TrustReport): string;
+export declare function renderTrustReportHtml(r: TrustReport): string;
+interface IO {
+    out: (s: string) => void;
+    err: (s: string) => void;
+}
+/** The sealed receipt names the manifest's sha256 in args_hash, so one signature covers every listed file. */
+export declare function sealBody(manifestSha: string, createdAt: string): SealableReceipt;
+export declare function runTrustReport(argv: string[], io: IO, env?: NodeJS.ProcessEnv, cwd?: string): Promise<number>;
+export {};
diff --git a/dist/cli/trust-report.js b/dist/cli/trust-report.js
new file mode 100644
index 00000000..e7fbdfd4
--- /dev/null
+++ b/dist/cli/trust-report.js
@@ -0,0 +1,542 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NOT_MEDIATED_ALWAYS = exports.TRUST_REPORT_USAGE = exports.TRUST_REPORT_SCHEMA = void 0;
+exports.buildTrustReport = buildTrustReport;
+exports.renderTrustReportMarkdown = renderTrustReportMarkdown;
+exports.renderTrustReportHtml = renderTrustReportHtml;
+exports.sealBody = sealBody;
+exports.runTrustReport = runTrustReport;
+/**
+ * `trustshell trust-report`: one readable report and its evidence, built only from what TrustShell already
+ * records. Local files only. Opens no socket.
+ *
+ * It keeps two different capabilities apart on the page, because they prove different things:
+ *   Inspect  what the agent SAID, compared with GitHub's record of a run. Needs no access to the agent.
+ *   Guard    what was ASKED and decided for commands started through `trustshell run`. Nothing else is seen.
+ *
+ * There is no overall score. A report reads as what was checked, what was not, and what to do next.
+ */
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const action_evidence_1 = require("../lib/action-evidence");
+const guardrails_1 = require("../lib/guardrails");
+const jcs_1 = require("../lib/jcs");
+const owner_receipt_1 = require("../lib/owner-receipt");
+const install_key_1 = require("../lib/install-key");
+const decode_text_1 = require("../lib/decode-text");
+const verify_receipt_1 = require("../lib/verify-receipt");
+const version_1 = require("../lib/version");
+exports.TRUST_REPORT_SCHEMA = 'dev.trustshell.trust-report/0.1-draft';
+exports.TRUST_REPORT_USAGE = `trustshell trust-report --out <new dir> [--record <record.json>]... [--bind "<tool or script>=<claim>"]... [--title <text>] [--json]
+trustshell trust-report verify <dir> [--root <0x key>] [--json]`;
+const MAX_INPUT_BYTES = 8 * 1024 * 1024;
+const MANIFEST = 'MANIFEST.sha256';
+const SEAL = 'report-receipt.json';
+exports.NOT_MEDIATED_ALWAYS = 'Anything the agent did without `trustshell run`: edits it made directly, its own network calls, commands in another terminal. This report cannot see them.';
+const clean = (s, max = 400) => (0, action_evidence_1.cleanCodePoints)(String(s ?? '')).slice(0, max);
+const sha256 = (b) => (0, node_crypto_1.createHash)('sha256').update(b).digest('hex');
+function parseLedgerLines(text) {
+    const out = [];
+    for (const line of text.split(/\r?\n/)) {
+        if (!line.trim())
+            continue;
+        try {
+            const r = JSON.parse(line);
+            if (r && typeof r === 'object' && !Array.isArray(r))
+                out.push(r);
+        }
+        catch {
+            /* readLedger reports this as a break */
+        }
+    }
+    return out;
+}
+function resultOf(outcome, kind, decision) {
+    if (kind === 'check')
+        return { result: 'asked only: Guard decided, nothing was started by TrustShell', exit_code: null };
+    if (decision !== 'ALLOWED')
+        return { result: 'never started', exit_code: null };
+    const ex = outcome?.executed;
+    if (!ex || ex === 'not run')
+        return { result: 'no outcome recorded', exit_code: null };
+    if (ex.exit_code !== null)
+        return { result: `exited ${ex.exit_code} after ${ex.duration_ms} ms`, exit_code: ex.exit_code };
+    if (ex.signal)
+        return { result: `stopped by signal ${ex.signal}`, exit_code: null };
+    return { result: 'could not start', exit_code: null };
+}
+/** The commands a reader cares about: everything `run` started or refused, every `guard check`, every other refusal. */
+function commandRows(records) {
+    const rows = [];
+    records.forEach((r, i) => {
+        if (r.kind !== 'decision' && r.kind !== 'check')
+            return;
+        const started = r.requested.executable !== undefined;
+        if (!started && r.kind !== 'check' && r.authorized?.decision === 'ALLOWED')
+            return;
+        const next = records[i + 1];
+        const outcome = next?.kind === 'outcome' && next.requested?.action === r.requested?.action ? next : undefined;
+        const req = r.requested;
+        rows.push({
+            seq: r.seq,
+            ts: r.ts,
+            action: clean(req.action, 140),
+            script_sha256: req.script_sha256 ?? null,
+            command_sha256: req.command_sha256 ?? null,
+            decision: r.authorized?.decision ?? 'UNKNOWN',
+            reasons: (r.authorized?.reasons ?? []).map((x) => clean(x, 300)),
+            ...resultOf(outcome, r.kind, r.authorized?.decision),
+        });
+    });
+    return rows;
+}
+function bindMatches(b, c) {
+    if (b.script_sha256)
+        return c.script_sha256 === b.script_sha256;
+    return c.action === `tool:${b.tool}`;
+}
+/** The last matching command decides a bound claim. Anything but a clean exit code is NOT_CHECKED or worse. */
+function decideBound(b, commands) {
+    const base = { claim: b.claim, decided_by: b.decided_by };
+    const hits = commands.filter((c) => bindMatches(b, c));
+    const last = hits[hits.length - 1];
+    if (!last)
+        return { ...base, status: 'NOT_CHECKED', why: 'that command was never asked for through TrustShell', record_seq: null };
+    const scope = `record ${last.seq}`;
+    if (last.exit_code === 0)
+        return { ...base, status: 'SUPPORTED', why: `the last time it ran through trustshell run it exited 0 (${scope}). That shows this command passed, not that it tests what the claim says.`, record_seq: last.seq };
+    if (last.exit_code !== null)
+        return { ...base, status: 'CONTRADICTED', why: `the last time it ran through trustshell run it exited ${last.exit_code} (${scope})`, record_seq: last.seq };
+    return { ...base, status: 'NOT_CHECKED', why: `it did not finish with an exit code: ${last.result} (${scope})`, record_seq: last.seq };
+}
+function inspectRow(path, text) {
+    const parsed = JSON.parse(text);
+    const record = parsed.record;
+    if (!record || record.schema !== action_evidence_1.ACTION_EVIDENCE_SCHEMA)
+        throw new Error(`${path} is not a check --claims record (${action_evidence_1.ACTION_EVIDENCE_SCHEMA})`);
+    const o = record.observation;
+    const digest = (0, action_evidence_1.digestRecord)(record).value;
+    return {
+        path,
+        run_url: clean(o.url, 300),
+        repo: `${clean(o.owner, 100)}/${clean(o.repo, 100)}`,
+        run_id: o.run_id,
+        head_sha: clean(o.head_sha, 80),
+        conclusion: o.conclusion === null ? null : clean(o.conclusion, 40),
+        verdict: clean(o.check.verdict, 40),
+        fetched_at: clean(o.fetchedAt, 40),
+        digest,
+        digest_matches: parsed.digest?.value === digest,
+        exit: (0, action_evidence_1.claimsExitCode)(record),
+        claims: record.claims.map((c) => ({ status: c.status, claim: clean(c.claim, 300), scope: clean(c.scope, 400) })),
+    };
+}
+function nextActions(r) {
+    const out = [];
+    if (r.guard.ledger.verdict === 'BROKEN')
+        out.push('Do not rely on the command section: the Guard record chain is broken. Read the breaks listed there.');
+    for (const i of r.inspect)
+        if (!i.digest_matches)
+            out.push(`Do not rely on the record for run ${i.run_id}: it changed after it was made.`);
+    for (const i of r.inspect) {
+        for (const c of i.claims)
+            if (c.status === 'CONTRADICTED')
+                out.push(`Do not accept "${c.claim}". GitHub's record disagrees: ${i.run_url}`);
+    }
+    for (const b of r.bound_claims)
+        if (b.status === 'CONTRADICTED')
+            out.push(`Do not accept "${b.claim}". ${b.decided_by} says otherwise. Fix it or ask the agent why, then run it again through trustshell run.`);
+    const notChecked = r.inspect.reduce((n, i) => n + i.claims.filter((c) => c.status === 'NOT_CHECKED').length, 0) + r.bound_claims.filter((b) => b.status === 'NOT_CHECKED').length;
+    if (notChecked)
+        out.push(`${notChecked} claim${notChecked === 1 ? ' was' : 's were'} not checked, which is not a pass. To decide one: say it as one plain sentence that cites the run ("The check workflow succeeded, run 123."), or pair it with a command using --bind.`);
+    const seen = new Set();
+    for (const c of r.guard.commands.filter((x) => x.decision !== 'ALLOWED')) {
+        const why = c.reasons[0] ?? 'no reason was recorded';
+        if (seen.has(why))
+            continue;
+        seen.add(why);
+        const unlisted = why.startsWith('the owner policy does not list');
+        out.push(`The policy refused ${c.action}: ${why}. If that was what you wanted, nothing to do.${unlisted ? ` If the agent needed it, run trustshell guard allow ${c.action}, then repeat the task.` : ''}`);
+    }
+    if (out.length === 0)
+        out.push('Nothing here contradicts the agent. Read the commands above and decide whether they test what you care about.');
+    return out;
+}
+/** PURE. The whole report, from its inputs. `verify` calls this again to prove the report matches its evidence. */
+function buildTrustReport(input) {
+    const inspect = input.records.map((r) => inspectRow(r.path, r.text));
+    const records = parseLedgerLines(input.ledgerText);
+    const ledger = (0, guardrails_1.readLedger)(input.ledgerText);
+    const commands = commandRows(records);
+    const parsedPolicy = input.policyText === null ? null : (0, guardrails_1.parsePolicyDocument)(input.policyText);
+    const doc = parsedPolicy?.ok ? parsedPolicy.doc : null;
+    const lastPolicy = [...records].reverse().find((r) => r.authorized?.policy_sha256);
+    const dedupe = (pick) => [...new Set(records.filter((r) => r.kind === 'decision' || r.kind === 'outcome').filter((r) => r.requested.executable !== undefined).flatMap((r) => pick(r) ?? []))].map((s) => clean(s, 300));
+    const guard = {
+        policy: {
+            state: input.policyText === null ? 'absent' : doc ? 'ok' : 'unreadable',
+            sha256: lastPolicy?.authorized.policy_sha256 ?? null,
+            nonce: doc?.policy.nonce ?? null,
+            signed: Boolean(doc?.signature),
+            actions: (doc?.policy.actions ?? []).map((a) => clean(a, 140)),
+        },
+        ledger: { verdict: ledger.verdict, count: ledger.count, breaks: ledger.breaks.map((b) => clean(b, 200)) },
+        commands,
+        mediated: dedupe((r) => r.assurance_scope?.mediated),
+        not_mediated: [...dedupe((r) => r.assurance_scope?.not_mediated), exports.NOT_MEDIATED_ALWAYS],
+    };
+    const bound_claims = input.binds.map((b) => decideBound(b, commands));
+    const partial = { inspect, guard, bound_claims };
+    const finding = inspect.some((i) => i.exit === 1 || !i.digest_matches) || bound_claims.some((b) => b.status === 'CONTRADICTED') || ledger.verdict === 'BROKEN';
+    const open = inspect.some((i) => i.exit !== 0) || bound_claims.some((b) => b.status !== 'SUPPORTED') || (inspect.length === 0 && bound_claims.length === 0);
+    return {
+        schema: exports.TRUST_REPORT_SCHEMA,
+        title: clean(input.title, 140),
+        generated_at: input.generatedAt,
+        generator: input.generator,
+        inputs: { binds: input.binds, records: input.records.map((r) => r.path) },
+        inspect,
+        guard,
+        bound_claims,
+        next_actions: nextActions(partial),
+        exit: finding ? 1 : open ? 3 : 0,
+    };
+}
+function blocks(r) {
+    const out = [];
+    out.push({ heading: 'What to do next', rows: r.next_actions.map((text) => ({ text })) });
+    if (r.inspect.length) {
+        for (const i of r.inspect) {
+            out.push({
+                heading: `Path 1 · What the agent said about ${i.repo} run ${i.run_id}`,
+                note: `Compared with GitHub's own record, read ${i.fetched_at}: ${i.verdict}, conclusion ${i.conclusion ?? 'none'}, commit ${i.head_sha}. TrustShell needed no access to the agent or its keys. ${i.run_url}`,
+                rows: i.claims.length ? i.claims.map((c) => ({ status: c.status, text: c.claim, detail: c.scope })) : [{ status: 'NOT_CHECKED', text: 'No claims were given for this run.' }],
+            });
+        }
+    }
+    else {
+        out.push({ heading: 'Path 1 · What the agent said about a GitHub Actions run', note: 'Not used in this report.', rows: [] });
+    }
+    if (r.bound_claims.length) {
+        out.push({
+            heading: 'Claims you paired with a command',
+            note: 'You chose which command decides each claim. TrustShell only reads how that command ended.',
+            rows: r.bound_claims.map((b) => ({ status: b.status, text: b.claim, detail: `decided by ${b.decided_by}: ${b.why}` })),
+        });
+    }
+    const g = r.guard;
+    out.push({
+        heading: 'Path 2 · Commands that went through trustshell run',
+        note: g.commands.length
+            ? `Only these. Policy ${g.policy.state}, ${g.policy.signed ? 'signed' : 'not signed'}, nonce ${g.policy.nonce ?? 'none'}. Record chain ${g.ledger.verdict}, ${g.ledger.count} records.`
+            : 'No command went through TrustShell, so this report says nothing about what the agent ran.',
+        rows: g.commands.map((c) => ({ status: c.decision, text: `#${c.seq} ${c.action}: ${c.result}`, detail: c.reasons.join('; ') || undefined })),
+    });
+    if (g.ledger.breaks.length)
+        out.push({ heading: 'The record chain is broken', rows: g.ledger.breaks.map((text) => ({ text })) });
+    out.push({ heading: 'What Guard saw', rows: g.mediated.map((text) => ({ text })) });
+    out.push({ heading: 'What this report cannot see', rows: g.not_mediated.map((text) => ({ text })) });
+    return out;
+}
+const INTRO = 'There is no overall score. Each line says what was checked and what it does not show.';
+const PRIVACY = 'Made on this machine. Nothing was uploaded. evidence/policy.json can hold local file paths: read it before sharing this folder.';
+const mdSafe = (s) => s.replace(/[\r\n]+/g, ' ').replace(/([\\`*_[\]<>|])/g, '\\$1');
+function renderTrustReportMarkdown(r) {
+    const out = [`# ${mdSafe(r.title)}`, '', `${INTRO} Made ${r.generated_at} by ${mdSafe(r.generator)}.`, ''];
+    for (const b of blocks(r)) {
+        out.push(`## ${mdSafe(b.heading)}`, '');
+        if (b.note)
+            out.push(mdSafe(b.note), '');
+        for (const row of b.rows)
+            out.push(`- ${row.status ? `**${row.status}** ` : ''}${mdSafe(row.text)}${row.detail ? `\n  - ${mdSafe(row.detail)}` : ''}`);
+        if (b.rows.length)
+            out.push('');
+    }
+    out.push('---', '', mdSafe(PRIVACY), '');
+    return out.join('\n');
+}
+const esc = (s) => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+const CSS = `:root{--bg:#fff;--fg:#1b1f24;--muted:#57606a;--line:#d0d7de;--ok:#1a7f37;--bad:#cf222e;--nc:#9a6700}
+@media (prefers-color-scheme:dark){:root{--bg:#0d1117;--fg:#e6edf3;--muted:#8d96a0;--line:#30363d;--ok:#3fb950;--bad:#f85149;--nc:#d29922}}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--fg);font:15px/1.5 system-ui,-apple-system,"Segoe UI",sans-serif}
+main{max-width:760px;margin:0 auto;padding:24px 16px}h1{font-size:22px;margin:0 0 8px}h2{font-size:16px;margin:24px 0 8px}p{margin:0 0 8px;overflow-wrap:anywhere}
+ul{padding-left:20px;margin:0}li{margin:6px 0;overflow-wrap:anywhere}.d{color:var(--muted);font-size:14px;display:block}.n{color:var(--muted)}
+.SUPPORTED,.ALLOWED{color:var(--ok)}.CONTRADICTED,.DENIED{color:var(--bad)}.NOT_CHECKED{color:var(--nc)}footer{margin-top:24px;padding-top:12px;border-top:1px solid var(--line);color:var(--muted);font-size:13px}`;
+function renderTrustReportHtml(r) {
+    const out = [
+        '<!doctype html>',
+        '<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">',
+        // No script, no remote anything: a stranger may open this file.
+        `<meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'">`,
+        `<title>${esc(r.title)}</title><style>${CSS}</style></head><body><main>`,
+        `<h1>${esc(r.title)}</h1><p class="n">${esc(INTRO)} Made ${esc(r.generated_at)} by ${esc(r.generator)}.</p>`,
+    ];
+    for (const b of blocks(r)) {
+        out.push(`<h2>${esc(b.heading)}</h2>`);
+        if (b.note)
+            out.push(`<p class="n">${esc(b.note)}</p>`);
+        if (b.rows.length) {
+            out.push('<ul>');
+            for (const row of b.rows)
+                out.push(`<li>${row.status ? `<strong class="${esc(row.status)}">${esc(row.status)}</strong> ` : ''}${esc(row.text)}${row.detail ? `<span class="d">${esc(row.detail)}</span>` : ''}</li>`);
+            out.push('</ul>');
+        }
+    }
+    out.push(`<footer>${esc(PRIVACY)}</footer></main></body></html>`, '');
+    return out.join('\n');
+}
+function walk(root, dir = root) {
+    return (0, node_fs_1.readdirSync)(dir, { withFileTypes: true }).flatMap((e) => {
+        const p = (0, node_path_1.join)(dir, e.name);
+        return e.isDirectory() ? walk(root, p) : [(0, node_path_1.relative)(root, p).split(node_path_1.sep).join('/')];
+    });
+}
+function readLimited(path) {
+    if ((0, node_fs_1.statSync)(path).size > MAX_INPUT_BYTES)
+        throw new Error(`${path} is larger than ${MAX_INPUT_BYTES} bytes`);
+    return (0, decode_text_1.decodeText)((0, node_fs_1.readFileSync)(path));
+}
+function parseBind(raw, cwd) {
+    const at = raw.indexOf('=');
+    if (at < 1 || at === raw.length - 1)
+        return `--bind needs "<tool or script>=<claim>", got: ${clean(raw, 80)}`;
+    const decided_by = clean(raw.slice(0, at), 200).trim();
+    const claim = clean(raw.slice(at + 1), 300).trim();
+    if (!decided_by || !claim)
+        return `--bind needs "<tool or script>=<claim>", got: ${clean(raw, 80)}`;
+    const file = (0, node_path_1.resolve)(cwd, decided_by);
+    if ((0, node_fs_1.existsSync)(file) && (0, node_fs_1.statSync)(file).isFile())
+        return { claim, decided_by, tool: null, script_sha256: sha256((0, node_fs_1.readFileSync)(file)) };
+    if (!/^[A-Za-z0-9_.:-]{1,128}$/.test(decided_by))
+        return `--bind: ${clean(decided_by, 80)} is not a tool name or a file that exists`;
+    return { claim, decided_by, tool: decided_by.replace(/^tool:/, ''), script_sha256: null };
+}
+/** The sealed receipt names the manifest's sha256 in args_hash, so one signature covers every listed file. */
+function sealBody(manifestSha, createdAt) {
+    return {
+        header: { receipt_id: `trust-report-${manifestSha.slice(0, 16)}`, prev_receipt_id: null, prev_hash: null, created_at: createdAt, env: { network: 'none', chain_id: 0, is_simulated: true } },
+        subject: { agent: { agent_id: 'local', agent_name: 'trustshell trust-report' }, owner: { wallet: null, assurance: null, status: 'none' } },
+        request: { tool: { name: 'trust-report', class: 'read' }, origin: 'Cli', args_hash: `0x${manifestSha}`, amount_raw: null, payee: null, asset: null, chain_id: null },
+        decision: {
+            verdict: 'ALLOW',
+            blocking: false,
+            executed: true,
+            reasons: ['sealed the manifest of a trust report'],
+            checks: [{ name: 'manifest', outcome: 'PASS', source: 'owner' }],
+            does_not_attest: ['that the commands in the report test what the claims say', 'anything done outside trustshell run'],
+            policy: { policy_hash: null, signer: null, signature: 'NOT_CHECKED', expires_at: null, revocation: 'NOT_CHECKED' },
+            limits: {},
+            laya: { lane: null, mode: 'shadow', consulted: false },
+        },
+        payment: { status: 'none' },
+        verification: { status: 'none' },
+    };
+}
+async function create(argv, io, env, cwd) {
+    let out;
+    let title = 'TrustShell Trust Report';
+    let json = false;
+    const recordPaths = [];
+    const binds = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i];
+        const value = () => argv[++i];
+        if (a === '--json')
+            json = true;
+        else if (a === '--out' || a === '--title' || a === '--record' || a === '--bind') {
+            const v = value();
+            if (v === undefined)
+                return usage(io, `${a} needs a value`);
+            if (a === '--out')
+                out = v;
+            else if (a === '--title')
+                title = v;
+            else if (a === '--record')
+                recordPaths.push(v);
+            else {
+                const b = parseBind(v, cwd);
+                if (typeof b === 'string')
+                    return usage(io, b);
+                binds.push(b);
+            }
+        }
+        else
+            return usage(io, `unexpected ${clean(a, 60)}`);
+    }
+    if (!out)
+        return usage(io, '--out <new dir> is required');
+    const outDir = (0, node_path_1.resolve)(cwd, out);
+    if ((0, node_fs_1.existsSync)(outDir) && (0, node_fs_1.readdirSync)(outDir).length > 0)
+        return usage(io, `${out} already has files in it. Name a new folder; a report is never written over another.`);
+    const home = (0, guardrails_1.trustshellHome)(env);
+    const ledgerPath = (0, node_path_1.join)(home, guardrails_1.GUARD_RECEIPTS_FILE);
+    const policyPath = (0, node_path_1.join)(home, guardrails_1.POLICY_FILE);
+    const ledgerText = (0, node_fs_1.existsSync)(ledgerPath) ? readLimited(ledgerPath) : '';
+    const policyText = (0, node_fs_1.existsSync)(policyPath) ? readLimited(policyPath) : null;
+    if (recordPaths.length === 0 && binds.length === 0 && ledgerText === '') {
+        io.err(`NOT_CHECKED nothing to report: no --record, no --bind, and no Guard records in ${home}.`);
+        return 2;
+    }
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(outDir, 'evidence'), { recursive: true });
+    const records = [];
+    try {
+        recordPaths.forEach((p, i) => {
+            const from = (0, node_path_1.resolve)(cwd, p);
+            const rel = `evidence/inspect-${i + 1}/record.json`;
+            (0, node_fs_1.mkdirSync)((0, node_path_1.join)(outDir, (0, node_path_1.dirname)(rel)), { recursive: true });
+            (0, node_fs_1.copyFileSync)(from, (0, node_path_1.join)(outDir, rel));
+            for (const card of ['card.md', 'card.html']) {
+                const c = (0, node_path_1.join)((0, node_path_1.dirname)(from), card);
+                if ((0, node_fs_1.existsSync)(c))
+                    (0, node_fs_1.copyFileSync)(c, (0, node_path_1.join)(outDir, (0, node_path_1.dirname)(rel), card));
+            }
+            records.push({ path: rel, text: readLimited(from) });
+        });
+        if (ledgerText !== '')
+            (0, node_fs_1.writeFileSync)((0, node_path_1.join)(outDir, 'evidence', guardrails_1.GUARD_RECEIPTS_FILE), ledgerText);
+        if (policyText !== null)
+            (0, node_fs_1.writeFileSync)((0, node_path_1.join)(outDir, 'evidence', guardrails_1.POLICY_FILE), policyText);
+        const report = buildTrustReport({ title, generatedAt: new Date().toISOString(), generator: `trustshell ${(0, version_1.resolvePackageVersion)(__dirname)}`, binds, records, ledgerText, policyText });
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(outDir, 'report.json'), `${JSON.stringify(report, null, 2)}\n`);
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(outDir, 'trust-report.md'), renderTrustReportMarkdown(report));
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(outDir, 'trust-report.html'), renderTrustReportHtml(report));
+        const manifest = walk(outDir).sort().map((f) => `${sha256((0, node_fs_1.readFileSync)((0, node_path_1.join)(outDir, f)))}  ${f}`).join('\n');
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(outDir, MANIFEST), `${manifest}\n`);
+        const { key } = (0, install_key_1.signingKey)(home);
+        const seal = await (0, owner_receipt_1.signOwnerReceipt)(sealBody(sha256(`${manifest}\n`), report.generated_at), key);
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(outDir, SEAL), `${JSON.stringify(seal, null, 2)}\n`);
+        const root = (0, owner_receipt_1.installKeyRootHex)(key);
+        if (json)
+            io.out(JSON.stringify({ report, out: outDir, root }, null, 2));
+        else {
+            const count = (s) => report.inspect.reduce((n, i) => n + i.claims.filter((c) => c.status === s).length, 0) + report.bound_claims.filter((b) => b.status === s).length;
+            io.out(`Trust Report written to ${outDir}`);
+            io.out(`  claims     ${count('SUPPORTED')} supported, ${count('CONTRADICTED')} contradicted, ${count('NOT_CHECKED')} not checked`);
+            io.out(`  commands   ${report.guard.commands.filter((c) => c.decision === 'ALLOWED').length} allowed, ${report.guard.commands.filter((c) => c.decision !== 'ALLOWED').length} refused, chain ${report.guard.ledger.verdict}`);
+            io.out('  read       trust-report.html or trust-report.md; the evidence is in evidence/');
+            io.out(`  check it   trustshell trust-report verify ${out} --root ${root}`);
+            io.out('  not seen   anything the agent did without trustshell run');
+        }
+        return report.exit;
+    }
+    catch (e) {
+        io.err(`trust-report: could not build the report: ${clean(e.message, 300)}`);
+        return 3;
+    }
+}
+function usage(io, why) {
+    io.err(`trust-report: ${why}\n${exports.TRUST_REPORT_USAGE}`);
+    return 2;
+}
+/** Exit 0 VERIFIED, 1 FAILED, 2 NOT_CHECKED (nothing to check, or no key to check authorship against). */
+async function verify(argv, io, cwd) {
+    let dirArg;
+    let root;
+    let json = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i];
+        if (a === '--json')
+            json = true;
+        else if (a === '--root')
+            root = argv[++i];
+        else if (a.startsWith('--'))
+            return usage(io, `unexpected ${clean(a, 60)}`);
+        else if (dirArg === undefined)
+            dirArg = a;
+        else
+            return usage(io, `unexpected ${clean(a, 60)}`);
+    }
+    if (!dirArg)
+        return usage(io, 'verify needs <dir>');
+    const dir = (0, node_path_1.resolve)(cwd, dirArg);
+    const manifestPath = (0, node_path_1.join)(dir, MANIFEST);
+    if (!(0, node_fs_1.existsSync)(manifestPath)) {
+        io.err(`NOT_CHECKED no ${MANIFEST} in ${dirArg}: this is not a trust report folder, or it is incomplete.`);
+        return 2;
+    }
+    const problems = [];
+    const manifestText = readLimited(manifestPath);
+    const listed = new Map(manifestText.split('\n').filter(Boolean).map((l) => {
+        const at = l.indexOf('  ');
+        return [l.slice(at + 2), l.slice(0, at)];
+    }));
+    for (const [f, want] of listed) {
+        const p = (0, node_path_1.join)(dir, f);
+        if (f.includes('..') || !(0, node_fs_1.existsSync)(p))
+            problems.push(`${f} is listed but missing`);
+        else if (sha256((0, node_fs_1.readFileSync)(p)) !== want)
+            problems.push(`${f} changed after the report was made`);
+    }
+    for (const f of walk(dir))
+        if (f !== MANIFEST && f !== SEAL && !listed.has(f))
+            problems.push(`${f} is not in the manifest`);
+    let authorship = 'NOT_CHECKED';
+    try {
+        const receipt = JSON.parse(readLimited((0, node_path_1.join)(dir, SEAL)));
+        if (receipt?.request?.args_hash !== `0x${sha256(manifestText)}`)
+            problems.push('the seal does not name this manifest');
+        const result = await (0, verify_receipt_1.verifyReceiptOffline)(receipt, root ? { trustedRoots: root.split(',') } : {});
+        const integrity = result.claims?.integrity?.status;
+        if (root) {
+            authorship = integrity === 'VERIFIED' && result.sealer?.trusted ? 'VERIFIED' : 'FAILED';
+            if (authorship === 'FAILED')
+                problems.push('the seal was not made by the key you pinned, or it was altered');
+        }
+        else if (integrity === 'FAILED')
+            problems.push('the seal was altered');
+    }
+    catch (e) {
+        problems.push(`the seal could not be read: ${clean(e.message, 160)}`);
+    }
+    try {
+        const report = JSON.parse(readLimited((0, node_path_1.join)(dir, 'report.json')));
+        const records = report.inputs.records.map((path) => {
+            if (path.includes('..'))
+                throw new Error(`bad evidence path ${clean(path, 80)}`);
+            return { path, text: readLimited((0, node_path_1.join)(dir, path)) };
+        });
+        const ledger = (0, node_path_1.join)(dir, 'evidence', guardrails_1.GUARD_RECEIPTS_FILE);
+        const policy = (0, node_path_1.join)(dir, 'evidence', guardrails_1.POLICY_FILE);
+        const again = buildTrustReport({
+            title: report.title,
+            generatedAt: report.generated_at,
+            generator: report.generator,
+            binds: report.inputs.binds,
+            records,
+            ledgerText: (0, node_fs_1.existsSync)(ledger) ? readLimited(ledger) : '',
+            policyText: (0, node_fs_1.existsSync)(policy) ? readLimited(policy) : null,
+        });
+        if ((0, jcs_1.jcsSha256)(again) !== (0, jcs_1.jcsSha256)(report))
+            problems.push('report.json does not match what its evidence produces');
+        if (renderTrustReportMarkdown(again) !== readLimited((0, node_path_1.join)(dir, 'trust-report.md')))
+            problems.push('trust-report.md does not match what its evidence produces');
+        if (renderTrustReportHtml(again) !== readLimited((0, node_path_1.join)(dir, 'trust-report.html')))
+            problems.push('trust-report.html does not match what its evidence produces');
+        if (again.guard.ledger.verdict === 'BROKEN')
+            problems.push('the Guard record chain is broken');
+        for (const i of again.inspect)
+            if (!i.digest_matches)
+                problems.push(`${i.path}: its digest does not match its contents`);
+    }
+    catch (e) {
+        problems.push(`the report could not be rebuilt: ${clean(e.message, 200)}`);
+    }
+    const verdict = problems.length ? 'FAILED' : authorship === 'VERIFIED' ? 'VERIFIED' : 'NOT_CHECKED';
+    if (json)
+        io.out(JSON.stringify({ verdict, authorship, problems }, null, 2));
+    else {
+        io.out(`${verdict} ${problems.length ? 'this report does not match its evidence' : authorship === 'VERIFIED' ? 'every file is whole, the report matches its evidence, and the pinned key sealed it' : 'every file is whole and the report matches its evidence, but who made it was not checked: pass --root <key from the author>'}`);
+        for (const p of problems)
+            io.out(`  - ${p}`);
+        io.out('  does not show: that the commands test what the claims say, or anything done outside trustshell run');
+    }
+    return problems.length ? 1 : authorship === 'VERIFIED' ? 0 : 2;
+}
+async function runTrustReport(argv, io, env = process.env, cwd = process.cwd()) {
+    if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+        io.out(exports.TRUST_REPORT_USAGE);
+        return argv.length === 0 ? 2 : 0;
+    }
+    return argv[0] === 'verify' ? verify(argv.slice(1), io, cwd) : create(argv, io, env, cwd);
+}
diff --git a/dist/lib/guardrails.d.ts b/dist/lib/guardrails.d.ts
index 7a8b3d7b..001f07f9 100644
--- a/dist/lib/guardrails.d.ts
+++ b/dist/lib/guardrails.d.ts
@@ -102,7 +102,7 @@ export interface PolicyDocument {
     signature: PolicySignature | null;
 }
 /** The commands that only read or write local files: what `guard init` allows. `learn` is listed, but its `check run` and `probe run` run a stored shell command and the CLI denies them while a policy is in force. */
-export declare const LOCAL_TOOLS: readonly ["bundle", "ground", "init", "inspect", "learn", "profile", "quarantine", "recall", "redact", "remember", "report", "traps"];
+export declare const LOCAL_TOOLS: readonly ["bundle", "ground", "init", "inspect", "learn", "profile", "quarantine", "recall", "redact", "remember", "report", "traps", "trust-report"];
 /** PURE. Is `a` an entry a policy's `actions` may hold (spend, post, tool or tool:<name>)? */
 export declare const isPolicyAction: (a: string) => boolean;
 /** The policy `guard init` writes: local commands only, every limit 0, expires in `days` days. */
@@ -231,6 +231,7 @@ export interface GuardRecord {
         exit_code: number | null;
         signal: string | null;
         duration_ms: number;
+        start_error?: string;
     } | 'not run' | null;
     assurance_scope: AssuranceScope;
     /** policy-change only: what changed it, and the policy hash before (null: there was none) and after. */
diff --git a/dist/lib/guardrails.js b/dist/lib/guardrails.js
index 6b50a60a..94f5811d 100644
--- a/dist/lib/guardrails.js
+++ b/dist/lib/guardrails.js
@@ -214,7 +214,7 @@ function interpreterCheck(executable, args, env, cwd = process.cwd()) {
     return r.ok ? { script: { path: r.path, sha256: r.sha256 }, reasons } : { reasons: [...reasons, `${r.why}; ${exports.INTERPRETER_RULE}`] };
 }
 /** The commands that only read or write local files: what `guard init` allows. `learn` is listed, but its `check run` and `probe run` run a stored shell command and the CLI denies them while a policy is in force. */
-exports.LOCAL_TOOLS = ['bundle', 'ground', 'init', 'inspect', 'learn', 'profile', 'quarantine', 'recall', 'redact', 'remember', 'report', 'traps'];
+exports.LOCAL_TOOLS = ['bundle', 'ground', 'init', 'inspect', 'learn', 'profile', 'quarantine', 'recall', 'redact', 'remember', 'report', 'traps', 'trust-report'];
 const ACTION = /^(spend|post|tool|tool:[A-Za-z0-9_.:-]{1,128})$/;
 /** PURE. Is `a` an entry a policy's `actions` may hold (spend, post, tool or tool:<name>)? */
 const isPolicyAction = (a) => ACTION.test(a);
diff --git a/examples/own-agent/README.md b/examples/own-agent/README.md
new file mode 100644
index 00000000..819dcf4b
--- /dev/null
+++ b/examples/own-agent/README.md
@@ -0,0 +1,104 @@
+# Test your own agent
+
+Two ways to check an agent. They are different things and prove different things.
+
+| | Path 1: check what it said | Path 2: run a task through TrustShell |
+|---|---|---|
+| **What you need** | A public GitHub Actions run and what the agent said about it | Your agent starts commands with `trustshell run` |
+| **Access to the agent** | None. No API key, no change to it | You opt in, one command at a time |
+| **What you learn** | Whether GitHub's record matches the claim | What was asked, what the policy decided, how each command ended |
+| **What you cannot learn** | Whether the code is right | Anything the agent did without `trustshell run`: direct edits, its own network calls, other terminals |
+
+Every command below is the same in bash, zsh and Windows PowerShell. The quotes around `'--'` matter: PowerShell drops a bare `--`.
+
+`trust-report` is not in a published release yet, so install from a clone:
+
+```bash
+git clone https://github.com/DealAppSeo/trustshell
+```
+
+```bash
+cd trustshell
+```
+
+```bash
+npm ci --ignore-scripts
+```
+
+Then use `node dist/cli/index.js` wherever `trustshell` appears below.
+
+## Path 1: check what it said
+
+Put your agent's words in a file, one claim per paragraph, each citing the run:
+
+```text
+The check workflow succeeded, run 42502305639.
+```
+
+```bash
+trustshell check https://github.com/DealAppSeo/trustshell/actions/runs/42502305639 --claims-file said.txt --out evidence
+```
+
+That run really failed, so the claim is **CONTRADICTED** and the exit code is 1. Only `api.github.com` is contacted, and your claim text is never sent. A claim the run cannot decide is **NOT_CHECKED**, which is not a pass.
+
+## Path 2: run a task through TrustShell
+
+Use a fresh folder for each test, so the report holds only this task.
+
+In bash:
+
+```bash
+export TRUSTSHELL_HOME="$PWD/.trust-run"
+```
+
+In PowerShell:
+
+```powershell
+$env:TRUSTSHELL_HOME = "$PWD\.trust-run"
+```
+
+Write the policy. Anything not listed is refused:
+
+```bash
+trustshell guard init
+```
+
+```bash
+trustshell guard allow tool:node --script test.js
+```
+
+Tell your agent to start its commands this way, and to expect exit code 5 when one is refused:
+
+```bash
+trustshell run --tool node '--' node test.js
+```
+
+A refused command never starts. On Windows, `.cmd` shims such as `npm` cannot be started directly: start the script they wrap, pinned the same way.
+
+## Get the report
+
+Pair each claim with the command that decides it, and add any Path 1 evidence:
+
+```bash
+trustshell trust-report --out report --record evidence/record.json --bind "test.js=All tests pass"
+```
+
+Open `report/trust-report.html`. It has what to do next, each claim and how it was decided, every command with the policy's decision and its exit code, and what the report cannot see. The evidence files are beside it in `report/evidence/`.
+
+Exit codes: `0` every claim supported, `1` a claim contradicted or a record broken, `3` anything not checked.
+
+Anyone you send the folder to can check it, using the key printed when the report was made:
+
+```bash
+trustshell trust-report verify report --root 0x<key>
+```
+
+Exit `0` verified, `1` changed or sealed by another key, `2` not checked (no key given). `MANIFEST.sha256` also works with plain `sha256sum -c`. The key shows who sealed the report. It does not show that the commands test what the claims say.
+
+## Try the whole thing
+
+This packs the release, installs it into an empty folder with no keys, and runs every step above, including a refused command, a test that really fails, and altered reports:
+
+```bash
+npm run test:release-e2e
+```
diff --git a/package.json b/package.json
index e9338ab7..dd5d3cbc 100644
--- a/package.json
+++ b/package.json
@@ -104,6 +104,7 @@
     "test:sdk-import": "npm run sdk:build && node tests/sdk-import-contract.mjs",
     "test:verify-import": "npm run sdk:build && node tests/verify-subpath-import.mjs",
     "test:trustlattice": "npm run sdk:build && node tests/trustlattice-conformance.mjs",
+    "test:release-e2e": "node scripts/release-e2e.mjs",
     "test:trust-cycle": "npm run sdk:build && node tests/e2e/trust-cycle-walk.mjs",
     "docs:honest-types": "node scripts/gen-honest-return-docs.mjs",
     "test:pack-x402": "node tests/pack-x402-guards.mjs",
diff --git a/scripts/check-egress.cjs b/scripts/check-egress.cjs
index fc31f4c7..adad0625 100644
--- a/scripts/check-egress.cjs
+++ b/scripts/check-egress.cjs
@@ -65,6 +65,8 @@ const NONE_RUNS = {
     exit: 0,
   },
   recall: { args: ['recall'], env: {}, stdout: 'do_not_send COUNT 0', exit: 0 },
+  // The empty temp cwd has no report folder, so this reads nothing and says so.
+  'trust-report': { args: ['trust-report', 'verify', 'no-such-report'], env: {}, stdout: '', exit: 2 },
   redact: { args: ['redact', 'egress-check-absent-key'], env: {}, stdout: 'NOT_CHECKED', exit: 0 },
   // traps prints a plain list (its --json is an array, not a verdict object), so it is pinned on
   // stdout here. Run in an empty cwd, every fixture row has no receipt and reads NOT_CHECKED.
diff --git a/scripts/release-e2e-summary.mjs b/scripts/release-e2e-summary.mjs
new file mode 100644
index 00000000..833ac845
--- /dev/null
+++ b/scripts/release-e2e-summary.mjs
@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// Prints a release-e2e result as Markdown, listing every step that did not pass.
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+const dir = process.argv[2] ?? 'e2e-out';
+const name = readdirSync(dir).find((f) => f.startsWith('e2e-') && f.endsWith('.json'));
+if (!name) {
+  console.log('### NOT_CHECKED: the E2E wrote no result file');
+  process.exit(0);
+}
+const s = JSON.parse(readFileSync(join(dir, name), 'utf8'));
+console.log(`### ${s.platform}: ${s.pass} passed, ${s.fail} failed, ${s.not_checked} not checked (shells: ${s.shells.join(', ')})\n`);
+for (const r of s.results.filter((x) => x.status !== 'PASS')) console.log(`- **${r.status}** ${r.id}: ${r.what}`);
diff --git a/scripts/release-e2e.mjs b/scripts/release-e2e.mjs
new file mode 100644
index 00000000..e3ad354a
--- /dev/null
+++ b/scripts/release-e2e.mjs
@@ -0,0 +1,476 @@
+#!/usr/bin/env node
+/**
+ * RELEASE E2E: what a new developer actually gets, tested on the real package in an empty folder.
+ *
+ * Packs this checkout (or takes --tarball), installs it into a temp directory with no key in the environment,
+ * and drives the installed CLI the way a person would, through real shells. Every step records its evidence.
+ * Needs only Node, npm, git and a network that reaches api.github.com. No account, no key, no secret of ours.
+ *
+ *   node scripts/release-e2e.mjs [--tarball <file.tgz>] [--out <dir>] [--only release|own-agent] [--keep]
+ *
+ * EXIT 0 every step passed. 1 a step failed. 2 no failure, but something was NOT_CHECKED (a shell that is not
+ * installed, GitHub rate-limiting this address). A skipped step is reported as NOT_CHECKED and never as a pass.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import { createServer } from 'node:http';
+import { createHash } from 'node:crypto';
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const WIN = process.platform === 'win32';
+const PKG_DIR = ['node_modules', '@hyperdag', 'trustshell'];
+
+// Real public runs. GREEN is trustshell's own check workflow; RED is a real failure on PR #684, kept for this.
+const GREEN = { url: 'https://github.com/DealAppSeo/trustshell/actions/runs/39619591025', id: '39619591025', sha: '392797a69b6a' };
+const RED = { url: 'https://github.com/DealAppSeo/trustshell/actions/runs/42502305639', id: '42502305639' };
+const GONE = 'https://github.com/DealAppSeo/trustshell/actions/runs/1';
+const GITHUB = 'https://api.github.com';
+
+function parseArgs(argv) {
+  const o = { tarball: undefined, out: undefined, only: undefined, keep: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--tarball') o.tarball = resolve(argv[++i]);
+    else if (a === '--out') o.out = resolve(argv[++i]);
+    else if (a === '--only') o.only = argv[++i];
+    else if (a === '--keep') o.keep = true;
+    else throw new Error(`unexpected ${a}`);
+  }
+  return o;
+}
+
+// Passive: records every outbound request and connection the CLI makes, and changes none of them.
+const TRACER = `const fs=require('fs');const dc=require('diagnostics_channel');const OUT=process.env.TS_E2E_TRACE;
+const log=(o)=>{try{fs.appendFileSync(OUT,JSON.stringify(o)+'\\n')}catch{}};
+dc.subscribe('undici:request:create',({request:r})=>{const h=Array.isArray(r.headers)?r.headers.join('\\n'):String(r.headers||'');log({via:'fetch',origin:r.origin,method:r.method,path:r.path,auth:/authorization/i.test(h)})});
+dc.subscribe('http.client.request.start',({request:r})=>log({via:'http',origin:r.host,method:r.method,path:r.path}));
+dc.subscribe('net.client.socket',({socket:s})=>s.once('connect',()=>log({via:'tcp',addr:s.remoteAddress,port:s.remotePort})));`;
+
+const results = [];
+function record(id, status, what, evidence = '') {
+  results.push({ id, status, what, evidence: String(evidence).slice(0, 1200) });
+  console.log(`${status.padEnd(11)} ${id}  ${what}${status === 'PASS' || !evidence ? '' : `\n            ${String(evidence).slice(0, 600)}`}`);
+}
+const expectStep = (id, what, ok, evidence) => record(id, ok ? 'PASS' : 'FAIL', what, evidence);
+
+function shells() {
+  if (!WIN) return [{ name: 'bash', cmd: 'bash', args: (c) => ['-c', c] }, { name: 'sh', cmd: 'sh', args: (c) => ['-c', c] }];
+  const list = [{ name: 'powershell-5.1', cmd: 'powershell.exe', args: (c) => ['-NoProfile', '-NonInteractive', '-Command', `${c}; exit $LASTEXITCODE`] }];
+  const git = ['C:\\Program Files\\Git\\bin\\bash.exe', 'C:\\Program Files (x86)\\Git\\bin\\bash.exe'].find(existsSync);
+  if (git) list.push({ name: 'git-bash', cmd: git, args: (c) => ['-c', c] });
+  return list;
+}
+
+function baseEnv(install, home, trace) {
+  const keep = ['SystemRoot', 'windir', 'ComSpec', 'PATHEXT', 'SystemDrive', 'PSModulePath', 'ProgramFiles', 'ProgramFiles(x86)', 'ProgramW6432'];
+  const env = {};
+  for (const k of keep) if (process.env[k] !== undefined) env[k] = process.env[k];
+  // One PATH key only. On Windows process.env answers to both spellings, and a child given both can read the old one.
+  env.PATH = `${join(install, 'node_modules', '.bin')}${WIN ? ';' : ':'}${process.env.PATH ?? ''}`;
+  mkdirSync(home, { recursive: true });
+  return {
+    ...env,
+    HOME: home,
+    USERPROFILE: home,
+    APPDATA: join(home, 'appdata'),
+    LOCALAPPDATA: join(home, 'localappdata'),
+    TEMP: tmpdir(),
+    TMP: tmpdir(),
+    TRUSTSHELL_HOME: home,
+    NO_COLOR: '1',
+    NODE_OPTIONS: `--require=${join(install, 'e2e-tracer.cjs').replace(/\\/g, '/')}`,
+    TS_E2E_TRACE: trace,
+  };
+}
+
+function sh(shell, command, { cwd, env, timeoutMs = 120_000 }) {
+  return new Promise((done) => {
+    const child = spawn(shell.cmd, shell.args(command), { cwd, env, windowsHide: true });
+    let stdout = '';
+    let stderr = '';
+    const t = setTimeout(() => child.kill(), timeoutMs);
+    child.stdout.on('data', (d) => (stdout += d));
+    child.stderr.on('data', (d) => (stderr += d));
+    child.on('error', (e) => {
+      clearTimeout(t);
+      done({ code: null, stdout, stderr: String(e) });
+    });
+    child.on('close', (code) => {
+      clearTimeout(t);
+      done({ code, stdout, stderr });
+    });
+  });
+}
+
+const readTrace = (file) => (existsSync(file) ? readFileSync(file, 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l)) : []);
+const origins = (trace) => [...new Set(trace.filter((t) => t.via !== 'tcp').map((t) => t.origin))];
+
+/** Runs one CLI command and returns it with its own network trace. */
+function makeRunner(ctx) {
+  let n = 0;
+  return async (shell, command, opts = {}) => {
+    const trace = join(ctx.work, `trace-${(n += 1)}.jsonl`);
+    const env = { ...baseEnv(ctx.install, opts.home ?? ctx.home, trace), ...(opts.env ?? {}) };
+    // Guard rightly refuses to start node while NODE_OPTIONS is set, so `run` steps go without the tracer.
+    if (opts.notrace) delete env.NODE_OPTIONS;
+    const r = await sh(shell, command, { cwd: opts.cwd ?? ctx.work, env, timeoutMs: opts.timeoutMs });
+    return { ...r, trace: readTrace(trace), hosts: origins(readTrace(trace)) };
+  };
+}
+
+const limited = (r) => /rate limit|GitHub 403|GitHub 429/i.test(`${r.stdout}${r.stderr}`);
+
+/** Decides a step that needed GitHub. Rate limiting is NOT_CHECKED, because the tool was never tested. */
+function githubStep(id, what, r, want, extra = true) {
+  if (limited(r)) return record(id, 'NOT_CHECKED', what, 'GitHub rate-limited this address');
+  const onlyGitHub = r.hosts.length > 0 && r.hosts.every((h) => h === GITHUB);
+  const noAuth = r.trace.every((t) => !t.auth);
+  const ok = r.code === want && onlyGitHub && noAuth && extra;
+  expectStep(id, what, ok, `exit ${r.code} (want ${want}); hosts ${r.hosts.join(',') || 'none'}; auth header ${noAuth ? 'absent' : 'PRESENT'}; ${r.stderr.slice(0, 200)}`);
+}
+
+async function tracerControl(ctx, run, shell) {
+  const server = createServer((_, res) => res.end('ok'));
+  await new Promise((d) => server.listen(0, '127.0.0.1', d));
+  const port = server.address().port;
+  const script = join(ctx.work, 'control.cjs');
+  writeFileSync(script, `fetch('http://127.0.0.1:${port}/').then(r=>r.text()).then(()=>process.exit(0))`);
+  const r = await run(shell, `node "${script.replace(/\\/g, '/')}"`);
+  server.close();
+  expectStep('tracer.control', 'the network tracer sees a request when one is made', r.hosts.includes(`http://127.0.0.1:${port}`), JSON.stringify(r.trace).slice(0, 300));
+}
+
+async function release(ctx, run) {
+  const [primary, ...others] = ctx.shells;
+  await tracerControl(ctx, run, primary);
+
+  const env = baseEnv(ctx.install, ctx.home, join(ctx.work, 'x'));
+  const leaked = Object.keys(env).filter((k) => /KEY|TOKEN|SECRET|PASSWORD|SUPABASE|DATABASE|REPID_/i.test(k));
+  expectStep('first-use.no-keys', 'the install runs with no key, token or secret name in its environment', leaked.length === 0, leaked.join(','));
+
+  const version = await run(primary, 'trustshell --version');
+  const packaged = JSON.parse(readFileSync(join(ctx.install, ...PKG_DIR, 'package.json'), 'utf8')).version;
+  expectStep('first-use.version', 'trustshell on the PATH is the package under test', version.code === 0 && version.stdout.includes(packaged) && version.hosts.length === 0, `want ${packaged}; got ${version.stdout}${version.stderr}`);
+
+  const demo = await run(primary, 'trustshell demo');
+  expectStep('first-use.offline-demo', 'demo seals and verifies a receipt, offline, with no account or key', demo.code === 0 && /VERIFIED/.test(demo.stdout) && demo.hosts.length === 0, `exit ${demo.code}; hosts ${demo.hosts}; ${demo.stderr.slice(0, 300)}`);
+
+  const dj = await run(primary, 'trustshell demo --json');
+  const sample = JSON.parse(dj.stdout);
+  const pin = sample.root;
+  const receipt = sample.receipt;
+  writeFileSync(join(ctx.work, 'r.json'), JSON.stringify(receipt));
+  writeFileSync(join(ctx.work, 'body.json'), JSON.stringify(receipt));
+
+  const good = await run(primary, `trustshell verify-receipt r.json --root ${pin}`);
+  expectStep('receipt.valid', 'a sealed receipt verifies locally (exit 0, no network)', good.code === 0 && good.hosts.length === 0, `exit ${good.code}; ${good.stdout.slice(0, 200)}`);
+
+  const tampered = structuredClone(receipt);
+  tampered.decision.reasons = ['changed after sealing'];
+  writeFileSync(join(ctx.work, 'tampered.json'), JSON.stringify(tampered));
+  const t = await run(primary, `trustshell verify-receipt tampered.json --root ${pin}`);
+  expectStep('receipt.tampered', 'an altered receipt fails (exit 1)', t.code === 1, `exit ${t.code}`);
+
+  const wrong = await run(primary, `trustshell verify-receipt r.json --root 0x${'ab'.repeat(32)}`);
+  expectStep('receipt.wrong-key', 'the wrong key fails (exit 1)', wrong.code === 1, `exit ${wrong.code}`);
+
+  writeFileSync(join(ctx.work, 'broken.json'), '{not json');
+  const bad = await run(primary, 'trustshell verify-receipt broken.json');
+  expectStep('receipt.malformed-json', 'a file that is not JSON is refused, not passed (exit 2)', bad.code === 2, `exit ${bad.code}`);
+
+  writeFileSync(join(ctx.work, 'shape.json'), '{"a":1}');
+  const shape = await run(primary, 'trustshell verify-receipt shape.json');
+  expectStep('receipt.malformed-shape', 'JSON that is not a receipt fails (exit 1)', shape.code === 1 && /MALFORMED/.test(`${shape.stdout}${shape.stderr}`), `exit ${shape.code}; ${shape.stdout.slice(0, 160)}${shape.stderr.slice(0, 160)}`);
+
+  const supported = await run(primary, `trustshell check ${GREEN.url} --claims "The check workflow succeeded, run ${GREEN.id}."`);
+  githubStep('inspect.supported', 'a true claim about a real public run is SUPPORTED (exit 0)', supported, 0, /SUPPORTED/.test(supported.stdout));
+
+  const contra = await run(primary, `trustshell check ${RED.url} --claims "The check workflow succeeded, run ${RED.id}."`);
+  githubStep('inspect.contradicted', 'a false claim about a real failed run is CONTRADICTED (exit 1)', contra, 1, /CONTRADICTED/.test(contra.stdout));
+
+  const nc = await run(primary, `trustshell check ${GREEN.url} --claims "All tests pass."`);
+  githubStep('inspect.not-checked', 'a claim the run cannot decide is NOT_CHECKED (exit 3)', nc, 3, /NOT_CHECKED|not checked/i.test(nc.stdout));
+
+  const marker = 'ZQXPRIVATEWORD';
+  const priv = await run(primary, `trustshell check ${GREEN.url} --claims "${marker} is what my agent said."`);
+  const sent = JSON.stringify(priv.trace);
+  githubStep('privacy.claim-text-stays-local', 'claim text is never sent: only GET requests to api.github.com, none carrying it', priv, 3, !sent.includes(marker) && priv.trace.filter((x) => x.method).every((x) => x.method === 'GET'));
+
+  const gone = await run(primary, `trustshell check ${GONE}`);
+  githubStep('inspect.missing-run', 'a run that does not exist is an error, not a verdict (exit 3)', gone, 3, /404/.test(`${gone.stdout}${gone.stderr}`));
+
+  const url = await run(primary, 'trustshell check https://github.com/a/b/actions/runs/xyz');
+  expectStep('inspect.bad-url', 'a malformed run URL is refused (exit 2, no network)', url.code === 2 && url.hosts.length === 0, `exit ${url.code}; hosts ${url.hosts}`);
+
+  const offline = await run(primary, `trustshell check ${GREEN.url}`, { env: { OFFLINE: '1' } });
+  expectStep('privacy.offline-switch', 'OFFLINE=1 sends nothing and says NOT_CHECKED (exit 2)', offline.code === 2 && offline.hosts.length === 0 && /NOT_CHECKED/.test(`${offline.stdout}${offline.stderr}`), `exit ${offline.code}; hosts ${offline.hosts}`);
+
+  await mcpStep(ctx);
+
+  const scratchHome = join(ctx.work, 'parity-home');
+  const parity = [
+    ['trustshell demo', 0],
+    [`trustshell verify-receipt tampered.json --root ${pin}`, 1],
+    ['trustshell sign-receipt body.json > resealed.json', 0],
+    ['trustshell guard init', 0],
+    ['trustshell guard allow tool:git', 0],
+    ["trustshell run --tool git '--' git --version", 0],
+    ["trustshell run --tool curl '--' curl https://example.com", 5],
+  ];
+  for (const shell of ctx.shells) {
+    const home = join(scratchHome, shell.name);
+    const codes = [];
+    let ok = true;
+    for (const [c, want] of parity) {
+      const r = await run(shell, c, { home });
+      codes.push(`${r.code}`);
+      if (r.code !== want) ok = false;
+    }
+    expectStep(`shells.${shell.name}`, `the same commands give the same exit codes in ${shell.name}`, ok, `got ${codes.join(' ')}, want ${parity.map((p) => p[1]).join(' ')}`);
+    // Read the key straight from the receipt: Guard is on by now, and the receipt is what a person would have.
+    const raw = readFileSync(join(ctx.work, 'resealed.json'));
+    const text = raw[0] === 0xff ? raw.toString('utf16le').replace(/^/, '') : raw.toString('utf8').replace(/^/, '');
+    const key = JSON.parse(text).header.signer.public_key;
+    await run(shell, 'trustshell guard allow tool:verify-receipt', { home });
+    const v = await run(shell, `trustshell verify-receipt resealed.json --root ${key}`, { home });
+    expectStep(`shells.${shell.name}.redirect`, `a receipt saved with > in ${shell.name} verifies`, v.code === 0, `exit ${v.code}; ${v.stdout.slice(0, 160)}${v.stderr.slice(0, 200)}`);
+  }
+  if (others.length === 0) record('shells.second', 'NOT_CHECKED', 'a second shell on this machine', 'only one shell was found');
+}
+
+function mcpStep(ctx) {
+  const server = join(ctx.install, ...PKG_DIR, 'dist', 'mcp', 'index.js');
+  const trace = join(ctx.work, 'trace-mcp.jsonl');
+  const env = baseEnv(ctx.install, join(ctx.work, 'mcp-home'), trace);
+  return new Promise((done) => {
+    const child = spawn(process.execPath, [server], { cwd: ctx.work, env, windowsHide: true });
+    let buf = '';
+    const finish = (status, ev) => {
+      clearTimeout(timer);
+      child.kill();
+      record('mcp.inspect-run', status, 'an agent can ask inspect_run over MCP from the clean install, with no key', ev);
+      done();
+    };
+    const timer = setTimeout(() => finish('FAIL', 'no answer in 90 s'), 90_000);
+    const send = (m) => child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', ...m })}\n`);
+    child.stdout.on('data', (d) => {
+      buf += d;
+      let nl;
+      while ((nl = buf.indexOf('\n')) >= 0) {
+        const line = buf.slice(0, nl).trim();
+        buf = buf.slice(nl + 1);
+        if (!line) continue;
+        const msg = JSON.parse(line);
+        if (msg.id === 1) {
+          send({ method: 'notifications/initialized' });
+          send({ id: 2, method: 'tools/call', params: { name: 'inspect_run', arguments: { run_url: GREEN.url, claims: `The check workflow succeeded, run ${GREEN.id}.` } } });
+        } else if (msg.id === 2) {
+          const text = JSON.stringify(msg.result ?? msg.error);
+          const hosts = origins(readTrace(trace));
+          if (/rate limit/i.test(text)) return finish('NOT_CHECKED', 'GitHub rate-limited this address');
+          const ok = /all_supported/.test(text) && hosts.every((h) => h === GITHUB);
+          finish(ok ? 'PASS' : 'FAIL', `hosts ${hosts}; ${text.slice(0, 400)}`);
+        }
+      }
+    });
+    send({ id: 1, method: 'initialize', params: { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'release-e2e', version: '0' } } });
+  });
+}
+
+/** A small real project. The bug is real and its test really fails until it is fixed. */
+function makeProject(dir, buggy) {
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'sum.js'), `module.exports = (a, b) => a ${buggy ? '-' : '+'} b;\n`);
+  writeFileSync(join(dir, 'test.js'), "const sum = require('./sum.js');\nif (sum(2, 2) !== 4) { console.error('FAIL sum(2,2) =', sum(2, 2)); process.exit(1); }\nconsole.log('ok');\n");
+  writeFileSync(join(dir, 'exfil.js'), "require('fs').writeFileSync('EXFIL_RAN', 'yes');\n");
+}
+
+function walk(dir) {
+  return readdirSync(dir, { withFileTypes: true }).flatMap((e) => (e.isDirectory() ? walk(join(dir, e.name)) : [join(dir, e.name)]));
+}
+
+async function ownAgent(ctx, run) {
+  const [primary] = ctx.shells;
+  const second = ctx.shells[1] ?? primary;
+
+  // ── Path 1: the agent's claims about a real run. No access to the agent is needed. ──
+  const claimsDir = join(ctx.work, 'path1');
+  mkdirSync(claimsDir, { recursive: true });
+  writeFileSync(join(claimsDir, 'said.txt'), `The check workflow succeeded, run ${RED.id}.\n`);
+  const p1 = await run(primary, `trustshell check ${RED.url} --claims-file path1/said.txt --out path1/evidence`, { home: join(ctx.work, 'p1-home') });
+  githubStep('path1.check', "Path 1 finds a false claim in an agent's report of a real run", p1, 1);
+  const p1Record = join('path1', 'evidence', 'record.json');
+  const haveRecord = existsSync(join(ctx.work, p1Record));
+
+  // ── Path 2, example A: an opted-in task that succeeds, with a refused action along the way. ──
+  const homeA = join(ctx.work, 'home-a');
+  const repoA = join(ctx.work, 'repo-a');
+  makeProject(repoA, true);
+  const inA = { home: homeA, cwd: repoA };
+  const plainA = { ...inA, notrace: true };
+  const guardInit = await run(primary, 'trustshell guard init', inA);
+  await run(primary, 'trustshell guard allow tool:node --script test.js', inA);
+  expectStep('path2.opt-in', 'opting in needs one local policy file and no account', guardInit.code === 0 && guardInit.hosts.length === 0, `exit ${guardInit.code}`);
+
+  const before = await run(primary, "trustshell run --tool node '--' node test.js", plainA);
+  expectStep('path2.a.bug-is-real', 'the test really fails before the fix, through trustshell run (exit 1)', before.code === 1, `exit ${before.code}`);
+
+  const refused = await run(primary, "trustshell run --tool node '--' node exfil.js", plainA);
+  expectStep('path2.a.denied-never-starts', 'a command the policy does not allow never starts (exit 5, its side effect absent)', refused.code === 5 && !existsSync(join(repoA, 'EXFIL_RAN')), `exit ${refused.code}`);
+  // The control: run outside TrustShell, the same script does leave its mark, so "absent" above means something.
+  spawnSync(process.execPath, ['exfil.js'], { cwd: repoA, windowsHide: true });
+  expectStep('path2.a.denied-control', 'the same script, started without trustshell run, does its side effect', existsSync(join(repoA, 'EXFIL_RAN')), '');
+  rmSync(join(repoA, 'EXFIL_RAN'), { force: true });
+
+  const argMarker = 'ZQXSECRETARG';
+  const curl = await run(primary, `trustshell run --tool curl '--' curl ${argMarker}`, inA);
+  expectStep('path2.a.unlisted-tool', 'a tool the policy does not list is refused (exit 5)', curl.code === 5, `exit ${curl.code}`);
+
+  writeFileSync(join(repoA, 'sum.js'), 'module.exports = (a, b) => a + b;\n'); // the agent's edit, made directly
+  writeFileSync(join(repoA, 'OUTSIDE'), 'done without trustshell');
+
+  const after = await run(primary, "trustshell run --tool node '--' node test.js", plainA);
+  expectStep('path2.a.fixed', 'the test passes after the fix (exit 0)', after.code === 0, `exit ${after.code}`);
+
+  const reportA = await run(primary, `trustshell trust-report --out ../out-a --bind "test.js=All tests pass" --title "Fixed the sum bug"`, inA);
+  expectStep('path2.a.report', 'the report supports the claim and lists the refusals (exit 0, no network)', reportA.code === 0 && reportA.hosts.length === 0, `exit ${reportA.code}; ${reportA.stderr.slice(0, 300)}`);
+  const outA = join(ctx.work, 'out-a');
+  const report = JSON.parse(readFileSync(join(outA, 'report.json'), 'utf8'));
+  expectStep('path2.a.denials-shown', 'both refusals are in the report', report.guard.commands.filter((c) => c.decision === 'DENIED').length === 2, JSON.stringify(report.guard.commands.map((c) => c.decision)));
+  const refusalRow = report.guard.commands.find((c) => c.decision === 'DENIED');
+  expectStep('path2.a.failure-shown', 'the failing run before the fix is not hidden', report.guard.commands.some((c) => c.exit_code === 1), JSON.stringify(report.guard.commands.map((c) => c.exit_code)));
+  expectStep('path2.a.refusal-reason', 'each refusal says why', refusalRow?.reasons?.length > 0, JSON.stringify(refusalRow));
+
+  const allText = walk(outA).map((f) => readFileSync(f, 'utf8')).join('\n');
+  expectStep('path2.privacy.command-text', 'the command line itself is not stored, only its hash', !allText.includes(argMarker), 'marker searched in every evidence file');
+  const md = readFileSync(join(outA, 'trust-report.md'), 'utf8');
+  expectStep('path2.boundary.stated', 'the report says what it cannot see', /This report cannot see them/.test(md) && /commands run without/.test(md), '');
+  expectStep('path2.boundary.outside-edit-invisible', 'a file written outside trustshell run leaves no record in the report', !allText.includes('OUTSIDE') && report.guard.commands.length === 4, `${report.guard.commands.length} commands listed`);
+
+  const key = JSON.parse(readFileSync(join(outA, 'report-receipt.json'), 'utf8')).header.signer.public_key;
+  const v0 = await run(primary, `trustshell trust-report verify ../out-a --root ${key}`, inA);
+  expectStep('report.verify', 'the folder verifies against the key that sealed it (exit 0, no network)', v0.code === 0 && v0.hosts.length === 0, `exit ${v0.code}; ${v0.stdout.slice(0, 200)}`);
+  const v1 = await run(primary, 'trustshell trust-report verify ../out-a', inA);
+  expectStep('report.no-key-is-not-a-pass', 'with no key to compare, authorship is NOT_CHECKED (exit 2)', v1.code === 2, `exit ${v1.code}`);
+  const v2 = await run(primary, `trustshell trust-report verify ../out-a --root 0x${'cd'.repeat(32)}`, inA);
+  expectStep('report.wrong-key', 'the wrong key fails (exit 1)', v2.code === 1, `exit ${v2.code}`);
+
+  const manifest = readFileSync(join(outA, 'MANIFEST.sha256'), 'utf8').split('\n').filter(Boolean);
+  const independentlyWhole = manifest.every((l) => {
+    const [hash, file] = [l.slice(0, 64), l.slice(66)];
+    return createHash('sha256').update(readFileSync(join(outA, file))).digest('hex') === hash;
+  });
+  expectStep('report.manifest-standalone', 'the manifest checks with plain sha256, no TrustShell code', independentlyWhole, `${manifest.length} files`);
+
+  const tamperCases = [
+    ['report.json', (s) => s.replace('"SUPPORTED"', '"CONTRADICTED"'), 'report.tamper-report'],
+    ['trust-report.md', (s) => `${s}\nAll good.\n`, 'report.tamper-readable'],
+    [join('evidence', 'guard-receipts.jsonl'), (s) => s.replace('"DENIED"', '"ALLOWED"'), 'report.tamper-ledger'],
+  ];
+  for (const [file, edit, id] of tamperCases) {
+    const copy = join(ctx.work, `tamper-${id}`);
+    cpSync(outA, copy, { recursive: true });
+    writeFileSync(join(copy, file), edit(readFileSync(join(copy, file), 'utf8')));
+    const r = await run(primary, `trustshell trust-report verify ../${`tamper-${id}`} --root ${key}`, inA);
+    expectStep(id, `changing ${file} fails verification (exit 1)`, r.code === 1, `exit ${r.code}`);
+  }
+  const extra = join(ctx.work, 'tamper-extra');
+  cpSync(outA, extra, { recursive: true });
+  writeFileSync(join(extra, 'evidence', 'added.txt'), 'x');
+  const added = await run(primary, `trustshell trust-report verify ../tamper-extra --root ${key}`, inA);
+  expectStep('report.tamper-added-file', 'adding a file fails verification (exit 1)', added.code === 1, `exit ${added.code}`);
+
+  // Same keys and a rewritten manifest: an attacker with the key is out of scope, and one without it must fail.
+  const forged = join(ctx.work, 'tamper-forged');
+  cpSync(outA, forged, { recursive: true });
+  const rewritten = readFileSync(join(forged, 'trust-report.md'), 'utf8').replace('Fixed the sum bug', 'Forged title');
+  writeFileSync(join(forged, 'trust-report.md'), rewritten);
+  writeFileSync(join(forged, 'MANIFEST.sha256'), manifest.map((l) => (l.endsWith('trust-report.md') ? `${createHash('sha256').update(rewritten).digest('hex')}  trust-report.md` : l)).join('\n') + '\n');
+  const fg = await run(primary, `trustshell trust-report verify ../tamper-forged --root ${key}`, inA);
+  expectStep('report.tamper-rewritten-manifest', 'a rewritten manifest without the key fails (exit 1)', fg.code === 1, `exit ${fg.code}`);
+
+  // ── Path 2, example B: a separate task, shell and home. The agent reports success; the test says otherwise. ──
+  const homeB = join(ctx.work, 'home-b');
+  const repoB = join(ctx.work, 'repo-b');
+  makeProject(repoB, true);
+  const inB = { home: homeB, cwd: repoB };
+  await run(second, 'trustshell guard init', inB);
+  await run(second, 'trustshell guard allow tool:node --script test.js', inB);
+  const failing = await run(second, "trustshell run --tool node '--' node test.js", { ...inB, notrace: true });
+  expectStep('path2.b.failure-recorded', `a failing test is recorded with its real exit code (${second.name}, exit 1)`, failing.code === 1, `exit ${failing.code}`);
+  const record1 = haveRecord ? `--record ../${p1Record.replace(/\\/g, '/')} ` : '';
+  const reportB = await run(second, `trustshell trust-report --out ../out-b ${record1}--bind "test.js=All tests pass" --bind "lint=Lint is clean" --title "Agent said it was finished"`, inB);
+  expectStep('path2.b.claim-contradicted', 'the false claim is CONTRADICTED and the report exits 1', reportB.code === 1, `exit ${reportB.code}; ${reportB.stderr.slice(0, 300)}`);
+  const b = JSON.parse(readFileSync(join(ctx.work, 'out-b', 'report.json'), 'utf8'));
+  expectStep('path2.b.statuses', 'one claim is contradicted and a claim with no command is NOT_CHECKED', b.bound_claims[0].status === 'CONTRADICTED' && b.bound_claims[1].status === 'NOT_CHECKED', JSON.stringify(b.bound_claims.map((x) => x.status)));
+  if (haveRecord) expectStep('path2.b.two-paths-apart', 'Path 1 and Path 2 appear as separate sections', /Path 1 ·/.test(readFileSync(join(ctx.work, 'out-b', 'trust-report.md'), 'utf8')) && /Path 2 ·/.test(readFileSync(join(ctx.work, 'out-b', 'trust-report.md'), 'utf8')), '');
+  else record('path2.b.two-paths-apart', 'NOT_CHECKED', 'Path 1 and Path 2 appear as separate sections', 'no Path 1 record: GitHub did not answer');
+  const nextB = b.next_actions.join(' ');
+  expectStep('path2.b.next-action', 'the report says what to do next', /Do not accept "All tests pass"/.test(nextB), nextB.slice(0, 300));
+
+  // The sandbox path: refused without a runtime, and not claimed either way when one exists.
+  const runtimeFound = ['docker', 'runc', 'runsc'].some((b) => spawnSync(b, ['--version'], { stdio: 'ignore', windowsHide: true }).status === 0);
+  if (runtimeFound) record('path2.sandbox', 'NOT_CHECKED', 'run --sandbox on this machine', 'a container runtime is present; this E2E does not start containers');
+  else {
+    await run(primary, 'trustshell guard allow tool:git', inA);
+    const sb = await run(primary, "trustshell run --sandbox --tool git '--' git --version", inA);
+    expectStep('path2.sandbox', 'with no container runtime, run --sandbox refuses instead of running on the host (exit 3)', sb.code === 3, `exit ${sb.code}`);
+  }
+
+  if (ctx.out) {
+    for (const [name, dir] of [['example-a-report', outA], ['example-b-report', join(ctx.work, 'out-b')]]) cpSync(dir, join(ctx.out, name), { recursive: true });
+  }
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const work = mkdtempSync(join(tmpdir(), 'ts-release-e2e-'));
+  const install = join(work, 'install');
+  mkdirSync(install);
+  const started = new Date().toISOString();
+  let tarball = opts.tarball;
+  const npm = (args, cwd) => spawnSync(WIN ? 'npm.cmd' : 'npm', args, { cwd, encoding: 'utf8', shell: WIN, windowsHide: true, timeout: 15 * 60_000 });
+  if (!tarball) {
+    const p = npm(['pack', '--ignore-scripts', '--pack-destination', `"${work}"`.replace(/"/g, WIN ? '"' : ''), '--silent'], ROOT);
+    tarball = join(work, p.stdout.trim().split('\n').pop().trim());
+  }
+  if (!existsSync(tarball)) {
+    console.error(`NOT_CHECKED no tarball at ${tarball}`);
+    process.exit(2);
+  }
+  const digest = createHash('sha256').update(readFileSync(tarball)).digest('hex');
+  writeFileSync(join(install, 'package.json'), '{ "name": "ts-release-e2e", "private": true }\n');
+  const installed = npm(['install', WIN ? `"${tarball}"` : tarball, '--ignore-scripts', '--no-audit', '--no-fund', '--silent'], install);
+  if (installed.status !== 0) {
+    console.error(`FAIL install: ${installed.stderr}`);
+    process.exit(1);
+  }
+  writeFileSync(join(install, 'e2e-tracer.cjs'), TRACER);
+  const ctx = { work, install, home: join(work, 'home'), shells: shells().filter((s) => spawnSync(s.cmd, s.args('exit 0'), { windowsHide: true }).status === 0), out: opts.out };
+  const run = makeRunner(ctx);
+  console.log(`tarball sha256 ${digest}\nnode ${process.version} · ${process.platform} · shells ${ctx.shells.map((s) => s.name).join(', ')}\n`);
+  try {
+    if (opts.only !== 'own-agent') await release(ctx, run);
+    if (opts.only !== 'release') await ownAgent(ctx, run);
+  } catch (e) {
+    record('harness', 'FAIL', 'the test run itself crashed', e?.stack ?? e);
+  }
+  const count = (s) => results.filter((r) => r.status === s).length;
+  const summary = { started, finished: new Date().toISOString(), node: process.version, platform: process.platform, shells: ctx.shells.map((s) => s.name), tarball_sha256: digest, pass: count('PASS'), fail: count('FAIL'), not_checked: count('NOT_CHECKED'), results };
+  console.log(`\n${summary.pass} passed · ${summary.fail} failed · ${summary.not_checked} not checked`);
+  if (opts.out) {
+    mkdirSync(opts.out, { recursive: true });
+    writeFileSync(join(opts.out, `e2e-${process.platform}.json`), `${JSON.stringify(summary, null, 2)}\n`);
+  }
+  if (!opts.keep) rmSync(work, { recursive: true, force: true });
+  else console.log(`kept ${work}`);
+  process.exit(summary.fail ? 1 : summary.not_checked ? 2 : 0);
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});
diff --git a/src/cli/guard.ts b/src/cli/guard.ts
index 4203f5a8..14325804 100644
--- a/src/cli/guard.ts
+++ b/src/cli/guard.ts
@@ -179,7 +179,11 @@ export function formatRunCard(decision: GuardRecord, outcome: GuardRecord | null
   const signed = by ? (by === own ? 'owner-signed' : `signed by ${by.slice(0, 16)}…, NOT this install's key`) : doc?.signature ? SIGNATURE_DOES_NOT_VERIFY : 'unsigned';
   const ex = outcome?.executed;
   const executed =
-    ex && ex !== 'not run' ? `started; exited ${ex.exit_code ?? `on signal ${ex.signal}`} after ${ex.duration_ms} ms` : 'not run';
+    ex && ex !== 'not run'
+      ? ex.exit_code === null && ex.signal === null
+        ? `could not start (${ex.start_error ?? 'unknown error'})`
+        : `started; exited ${ex.exit_code ?? `on signal ${ex.signal}`} after ${ex.duration_ms} ms`
+      : 'not run';
   const exe = d.requested.executable;
   const pinnedExe = exe !== undefined && (doc?.policy.executables ?? []).some((p) => p.tool === exe);
   const identity =
@@ -203,13 +207,13 @@ export function formatRunCard(decision: GuardRecord, outcome: GuardRecord | null
 }
 
 export interface Spawner {
-  (cmd: string, args: string[]): { status: number | null; signal: string | null };
+  (cmd: string, args: string[]): { status: number | null; signal: string | null; error?: string };
 }
 
 const nodeSpawner: Spawner = (cmd, args) => {
   const { spawnSync } = require('node:child_process') as typeof import('node:child_process');
   const r = spawnSync(cmd, args, { stdio: 'inherit', windowsHide: true });
-  return { status: r.status, signal: r.signal ?? null };
+  return { status: r.status, signal: r.signal ?? null, error: r.error ? ((r.error as NodeJS.ErrnoException).code ?? r.error.message) : undefined };
 };
 
 export const RUN_USAGE =
@@ -220,6 +224,9 @@ export const RUN_USAGE =
  * `run --tool git -- git status` arrived as `run --tool git git status` and failed "unexpected git" with no
  * hint (stranger walk, 2026-10-23, PS 5.1). Quoted, or through the `.cmd` shim, the `--` survives.
  */
+/** Windows starts only real executables without a shell, and `run` never uses a shell: that would let arguments start other commands. */
+export const RUN_WINDOWS_SHIM = "On Windows a .cmd shim such as npm or npx cannot be started directly. Start the script it wraps instead: pin it, then trustshell run --tool node '--' node <script>.";
+
 export const RUN_POWERSHELL = "In Windows PowerShell write the -- quoted, '--' (trustshell run --tool git '--' git status), or call trustshell.cmd: PowerShell drops a bare -- before trustshell sees it.";
 
 const isHelp = (a: string | undefined) => a === '--help' || a === '-h' || a === 'help';
@@ -318,10 +325,11 @@ export function runRun(argv: string[], io: IO, env: NodeJS.ProcessEnv = process.
     kind: 'outcome',
     requested: g.record.requested,
     authorized: g.record.authorized,
-    executed: { exit_code: r.status, signal: r.signal, duration_ms: Date.now() - t0 },
+    executed: { exit_code: r.status, signal: r.signal, duration_ms: Date.now() - t0, ...(r.error ? { start_error: r.error } : {}) },
     assurance_scope: RUN_SCOPE,
   });
   (json ? io.out : io.err)(json ? JSON.stringify({ decision: g.record, outcome }, null, 2) : formatRunCard(g.record, outcome, g.loaded.state === 'ok' ? g.loaded.doc : null, own));
+  if (r.error === 'ENOENT' && process.platform === 'win32') io.err(RUN_WINDOWS_SHIM);
   return r.status ?? 3;
 }
 
diff --git a/src/cli/index.ts b/src/cli/index.ts
index 7560d94d..e1ded252 100644
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -79,6 +79,7 @@ import { GUARD_RECORD_SCHEMA, trustshellHome } from '../lib/guardrails';
 import { ApiUrlError } from '../lib/api-url';
 import { signingKey } from '../lib/install-key';
 import { decodeText } from '../lib/decode-text';
+import { runTrustReport } from './trust-report';
 import { signOwnerReceipt, installKeyRootHex, type SealableReceipt } from '../lib/owner-receipt';
 
 /** Exit codes — a small, stable contract so CI scripts can branch on them. */
@@ -131,6 +132,7 @@ export type Command =
   | 'bundle'
   | 'guard'
   | 'run'
+  | 'trust-report'
   | 'sandbox'
   | 'help'
   | 'version';
@@ -212,6 +214,7 @@ export interface ParsedArgs {
   guardArgv?: string[];
   /** run: everything after `run`, parsed by src/cli/guard.ts (its options, then `--`, then the command). */
   runArgv?: string[];
+  trustReportArgv?: string[];
   /** sandbox: everything after `sandbox`, parsed by src/sandbox/run.ts (promote <mission>). */
   sandboxArgv?: string[];
   /** profile: the parsed subcommand (show / add / set / remove / interview). */
@@ -491,6 +494,16 @@ COMMANDS
                              The chain (default base).
       [--payment <txHash>]   The payment to check. Default: the feedbackHash, read as a
                              transaction. The feedback file is never fetched.
+  trust-report --out <new dir> [--record <record.json>]... [--bind "<tool or script>=<claim>"]...
+                             One readable report and its evidence: what the agent said, checked against
+                             GitHub (from check --out records), and every command that went through
+                             trustshell run. It cannot see anything the agent did any other way. No
+                             network. EXIT 0 every claim SUPPORTED, 1 a claim CONTRADICTED or a broken
+                             record, 3 anything NOT_CHECKED. --bind pairs a claim with the command that
+                             decides it.
+  trust-report verify <dir> [--root <key>]
+                             Prove the folder is whole and matches its evidence. EXIT 0 VERIFIED, 1 FAILED,
+                             2 NOT_CHECKED (no --root, so who made it was not checked).
   report                     State what your log and your saved GitHub evidence TOGETHER
                              support, and where they disagree. NO NETWORK — evidence is a
                              file you produced. CONFIRMED (0) / INCONSISTENT (1) /
@@ -575,6 +588,7 @@ export function parseArgs(argv: string[]): ParsedArgs {
   if (argv[0] === 'guard') return { command: 'guard', guardArgv: argv.slice(1), json: false, verify: false };
   if (argv[0] === 'run') return { command: 'run', runArgv: argv.slice(1), json: false, verify: false };
   if (argv[0] === 'sandbox') return { command: 'sandbox', sandboxArgv: argv.slice(1), json: false, verify: false };
+  if (argv[0] === 'trust-report') return { command: 'trust-report', trustReportArgv: argv.slice(1), json: false, verify: false };
   const flags = new Set<string>();
   const positionals: string[] = [];
   // Options that consume the NEXT argument. Indexed rather than for-of because a
@@ -1193,6 +1207,10 @@ export async function run(
       // Starts the caller's command only after the policy allows it.
       return runRun(args.runArgv ?? [], io);
 
+    case 'trust-report':
+      // Local files only. Opens no socket.
+      return runTrustReport(args.trustReportArgv ?? [], io);
+
     case 'sandbox':
       // Local files only: the owner step that promotes a `run --sandbox` mission's quarantined outbox.
       return sandboxCli(args.sandboxArgv ?? [], io);
diff --git a/src/cli/trust-report.ts b/src/cli/trust-report.ts
new file mode 100644
index 00000000..a8c75d7b
--- /dev/null
+++ b/src/cli/trust-report.ts
@@ -0,0 +1,586 @@
+/**
+ * `trustshell trust-report`: one readable report and its evidence, built only from what TrustShell already
+ * records. Local files only. Opens no socket.
+ *
+ * It keeps two different capabilities apart on the page, because they prove different things:
+ *   Inspect  what the agent SAID, compared with GitHub's record of a run. Needs no access to the agent.
+ *   Guard    what was ASKED and decided for commands started through `trustshell run`. Nothing else is seen.
+ *
+ * There is no overall score. A report reads as what was checked, what was not, and what to do next.
+ */
+import { createHash } from 'node:crypto';
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import {
+  ACTION_EVIDENCE_SCHEMA,
+  claimsExitCode,
+  cleanCodePoints,
+  digestRecord,
+  type ActionEvidenceRecord,
+  type RecordDigest,
+} from '../lib/action-evidence';
+import { GUARD_RECEIPTS_FILE, POLICY_FILE, parsePolicyDocument, readLedger, trustshellHome, type GuardRecord } from '../lib/guardrails';
+import { jcsSha256 } from '../lib/jcs';
+import { installKeyRootHex, signOwnerReceipt, type SealableReceipt } from '../lib/owner-receipt';
+import { signingKey } from '../lib/install-key';
+import { decodeText } from '../lib/decode-text';
+import { verifyReceiptOffline } from '../lib/verify-receipt';
+import { resolvePackageVersion } from '../lib/version';
+
+export const TRUST_REPORT_SCHEMA = 'dev.trustshell.trust-report/0.1-draft' as const;
+export const TRUST_REPORT_USAGE = `trustshell trust-report --out <new dir> [--record <record.json>]... [--bind "<tool or script>=<claim>"]... [--title <text>] [--json]
+trustshell trust-report verify <dir> [--root <0x key>] [--json]`;
+const MAX_INPUT_BYTES = 8 * 1024 * 1024;
+const MANIFEST = 'MANIFEST.sha256';
+const SEAL = 'report-receipt.json';
+
+export const NOT_MEDIATED_ALWAYS =
+  'Anything the agent did without `trustshell run`: edits it made directly, its own network calls, commands in another terminal. This report cannot see them.';
+
+export interface Bind {
+  claim: string;
+  decided_by: string;
+  tool: string | null;
+  script_sha256: string | null;
+}
+
+export interface InspectRow {
+  path: string;
+  run_url: string;
+  repo: string;
+  run_id: number;
+  head_sha: string;
+  conclusion: string | null;
+  verdict: string;
+  fetched_at: string;
+  digest: string;
+  digest_matches: boolean;
+  exit: number;
+  claims: { status: string; claim: string; scope: string }[];
+}
+
+export interface CommandRow {
+  seq: number;
+  ts: string;
+  action: string;
+  script_sha256: string | null;
+  command_sha256: string | null;
+  decision: string;
+  reasons: string[];
+  result: string;
+  exit_code: number | null;
+}
+
+export interface BoundClaim {
+  claim: string;
+  decided_by: string;
+  status: 'SUPPORTED' | 'CONTRADICTED' | 'NOT_CHECKED';
+  why: string;
+  record_seq: number | null;
+}
+
+export interface TrustReport {
+  schema: typeof TRUST_REPORT_SCHEMA;
+  title: string;
+  generated_at: string;
+  generator: string;
+  inputs: { binds: Bind[]; records: string[] };
+  inspect: InspectRow[];
+  guard: {
+    policy: { state: string; sha256: string | null; nonce: string | null; signed: boolean; actions: string[] };
+    ledger: { verdict: string; count: number; breaks: string[] };
+    commands: CommandRow[];
+    mediated: string[];
+    not_mediated: string[];
+  };
+  bound_claims: BoundClaim[];
+  next_actions: string[];
+  exit: number;
+}
+
+export interface BuildInput {
+  title: string;
+  generatedAt: string;
+  generator: string;
+  binds: Bind[];
+  records: { path: string; text: string }[];
+  ledgerText: string;
+  policyText: string | null;
+}
+
+const clean = (s: unknown, max = 400): string => cleanCodePoints(String(s ?? '')).slice(0, max);
+const sha256 = (b: Buffer | string): string => createHash('sha256').update(b).digest('hex');
+
+function parseLedgerLines(text: string): GuardRecord[] {
+  const out: GuardRecord[] = [];
+  for (const line of text.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    try {
+      const r = JSON.parse(line);
+      if (r && typeof r === 'object' && !Array.isArray(r)) out.push(r as GuardRecord);
+    } catch {
+      /* readLedger reports this as a break */
+    }
+  }
+  return out;
+}
+
+function resultOf(outcome: GuardRecord | undefined, kind: string, decision: string): { result: string; exit_code: number | null } {
+  if (kind === 'check') return { result: 'asked only: Guard decided, nothing was started by TrustShell', exit_code: null };
+  if (decision !== 'ALLOWED') return { result: 'never started', exit_code: null };
+  const ex = outcome?.executed;
+  if (!ex || ex === 'not run') return { result: 'no outcome recorded', exit_code: null };
+  if (ex.exit_code !== null) return { result: `exited ${ex.exit_code} after ${ex.duration_ms} ms`, exit_code: ex.exit_code };
+  if (ex.signal) return { result: `stopped by signal ${ex.signal}`, exit_code: null };
+  return { result: 'could not start', exit_code: null };
+}
+
+/** The commands a reader cares about: everything `run` started or refused, every `guard check`, every other refusal. */
+function commandRows(records: GuardRecord[]): CommandRow[] {
+  const rows: CommandRow[] = [];
+  records.forEach((r, i) => {
+    if (r.kind !== 'decision' && r.kind !== 'check') return;
+    const started = (r.requested as { executable?: string }).executable !== undefined;
+    if (!started && r.kind !== 'check' && r.authorized?.decision === 'ALLOWED') return;
+    const next = records[i + 1];
+    const outcome = next?.kind === 'outcome' && next.requested?.action === r.requested?.action ? next : undefined;
+    const req = r.requested as { action: string; script_sha256?: string; command_sha256?: string };
+    rows.push({
+      seq: r.seq,
+      ts: r.ts,
+      action: clean(req.action, 140),
+      script_sha256: req.script_sha256 ?? null,
+      command_sha256: req.command_sha256 ?? null,
+      decision: r.authorized?.decision ?? 'UNKNOWN',
+      reasons: (r.authorized?.reasons ?? []).map((x) => clean(x, 300)),
+      ...resultOf(outcome, r.kind, r.authorized?.decision),
+    });
+  });
+  return rows;
+}
+
+function bindMatches(b: Bind, c: CommandRow): boolean {
+  if (b.script_sha256) return c.script_sha256 === b.script_sha256;
+  return c.action === `tool:${b.tool}`;
+}
+
+/** The last matching command decides a bound claim. Anything but a clean exit code is NOT_CHECKED or worse. */
+function decideBound(b: Bind, commands: CommandRow[]): BoundClaim {
+  const base = { claim: b.claim, decided_by: b.decided_by };
+  const hits = commands.filter((c) => bindMatches(b, c));
+  const last = hits[hits.length - 1];
+  if (!last) return { ...base, status: 'NOT_CHECKED', why: 'that command was never asked for through TrustShell', record_seq: null };
+  const scope = `record ${last.seq}`;
+  if (last.exit_code === 0) return { ...base, status: 'SUPPORTED', why: `the last time it ran through trustshell run it exited 0 (${scope}). That shows this command passed, not that it tests what the claim says.`, record_seq: last.seq };
+  if (last.exit_code !== null) return { ...base, status: 'CONTRADICTED', why: `the last time it ran through trustshell run it exited ${last.exit_code} (${scope})`, record_seq: last.seq };
+  return { ...base, status: 'NOT_CHECKED', why: `it did not finish with an exit code: ${last.result} (${scope})`, record_seq: last.seq };
+}
+
+function inspectRow(path: string, text: string): InspectRow {
+  const parsed = JSON.parse(text) as { record?: ActionEvidenceRecord; digest?: RecordDigest };
+  const record = parsed.record;
+  if (!record || record.schema !== ACTION_EVIDENCE_SCHEMA) throw new Error(`${path} is not a check --claims record (${ACTION_EVIDENCE_SCHEMA})`);
+  const o = record.observation;
+  const digest = digestRecord(record).value;
+  return {
+    path,
+    run_url: clean(o.url, 300),
+    repo: `${clean(o.owner, 100)}/${clean(o.repo, 100)}`,
+    run_id: o.run_id,
+    head_sha: clean(o.head_sha, 80),
+    conclusion: o.conclusion === null ? null : clean(o.conclusion, 40),
+    verdict: clean(o.check.verdict, 40),
+    fetched_at: clean(o.fetchedAt, 40),
+    digest,
+    digest_matches: parsed.digest?.value === digest,
+    exit: claimsExitCode(record),
+    claims: record.claims.map((c) => ({ status: c.status, claim: clean(c.claim, 300), scope: clean(c.scope, 400) })),
+  };
+}
+
+function nextActions(r: Pick<TrustReport, 'inspect' | 'guard' | 'bound_claims'>): string[] {
+  const out: string[] = [];
+  if (r.guard.ledger.verdict === 'BROKEN') out.push('Do not rely on the command section: the Guard record chain is broken. Read the breaks listed there.');
+  for (const i of r.inspect) if (!i.digest_matches) out.push(`Do not rely on the record for run ${i.run_id}: it changed after it was made.`);
+  for (const i of r.inspect) {
+    for (const c of i.claims) if (c.status === 'CONTRADICTED') out.push(`Do not accept "${c.claim}". GitHub's record disagrees: ${i.run_url}`);
+  }
+  for (const b of r.bound_claims) if (b.status === 'CONTRADICTED') out.push(`Do not accept "${b.claim}". ${b.decided_by} says otherwise. Fix it or ask the agent why, then run it again through trustshell run.`);
+  const notChecked = r.inspect.reduce((n, i) => n + i.claims.filter((c) => c.status === 'NOT_CHECKED').length, 0) + r.bound_claims.filter((b) => b.status === 'NOT_CHECKED').length;
+  if (notChecked) out.push(`${notChecked} claim${notChecked === 1 ? ' was' : 's were'} not checked, which is not a pass. To decide one: say it as one plain sentence that cites the run ("The check workflow succeeded, run 123."), or pair it with a command using --bind.`);
+  const seen = new Set<string>();
+  for (const c of r.guard.commands.filter((x) => x.decision !== 'ALLOWED')) {
+    const why = c.reasons[0] ?? 'no reason was recorded';
+    if (seen.has(why)) continue;
+    seen.add(why);
+    const unlisted = why.startsWith('the owner policy does not list');
+    out.push(`The policy refused ${c.action}: ${why}. If that was what you wanted, nothing to do.${unlisted ? ` If the agent needed it, run trustshell guard allow ${c.action}, then repeat the task.` : ''}`);
+  }
+  if (out.length === 0) out.push('Nothing here contradicts the agent. Read the commands above and decide whether they test what you care about.');
+  return out;
+}
+
+/** PURE. The whole report, from its inputs. `verify` calls this again to prove the report matches its evidence. */
+export function buildTrustReport(input: BuildInput): TrustReport {
+  const inspect = input.records.map((r) => inspectRow(r.path, r.text));
+  const records = parseLedgerLines(input.ledgerText);
+  const ledger = readLedger(input.ledgerText);
+  const commands = commandRows(records);
+  const parsedPolicy = input.policyText === null ? null : parsePolicyDocument(input.policyText);
+  const doc = parsedPolicy?.ok ? parsedPolicy.doc : null;
+  const lastPolicy = [...records].reverse().find((r) => r.authorized?.policy_sha256);
+  const dedupe = (pick: (r: GuardRecord) => string[] | undefined): string[] =>
+    [...new Set(records.filter((r) => r.kind === 'decision' || r.kind === 'outcome').filter((r) => (r.requested as { executable?: string }).executable !== undefined).flatMap((r) => pick(r) ?? []))].map((s) => clean(s, 300));
+  const guard: TrustReport['guard'] = {
+    policy: {
+      state: input.policyText === null ? 'absent' : doc ? 'ok' : 'unreadable',
+      sha256: lastPolicy?.authorized.policy_sha256 ?? null,
+      nonce: doc?.policy.nonce ?? null,
+      signed: Boolean(doc?.signature),
+      actions: (doc?.policy.actions ?? []).map((a) => clean(a, 140)),
+    },
+    ledger: { verdict: ledger.verdict, count: ledger.count, breaks: ledger.breaks.map((b) => clean(b, 200)) },
+    commands,
+    mediated: dedupe((r) => r.assurance_scope?.mediated),
+    not_mediated: [...dedupe((r) => r.assurance_scope?.not_mediated), NOT_MEDIATED_ALWAYS],
+  };
+  const bound_claims = input.binds.map((b) => decideBound(b, commands));
+  const partial = { inspect, guard, bound_claims };
+  const finding = inspect.some((i) => i.exit === 1 || !i.digest_matches) || bound_claims.some((b) => b.status === 'CONTRADICTED') || ledger.verdict === 'BROKEN';
+  const open = inspect.some((i) => i.exit !== 0) || bound_claims.some((b) => b.status !== 'SUPPORTED') || (inspect.length === 0 && bound_claims.length === 0);
+  return {
+    schema: TRUST_REPORT_SCHEMA,
+    title: clean(input.title, 140),
+    generated_at: input.generatedAt,
+    generator: input.generator,
+    inputs: { binds: input.binds, records: input.records.map((r) => r.path) },
+    inspect,
+    guard,
+    bound_claims,
+    next_actions: nextActions(partial),
+    exit: finding ? 1 : open ? 3 : 0,
+  };
+}
+
+// ── one model, two renderings ──────────────────────────────────────────────
+
+type Row = { status?: string; text: string; detail?: string };
+interface Block {
+  heading: string;
+  note?: string;
+  rows: Row[];
+}
+
+function blocks(r: TrustReport): Block[] {
+  const out: Block[] = [];
+  out.push({ heading: 'What to do next', rows: r.next_actions.map((text) => ({ text })) });
+  if (r.inspect.length) {
+    for (const i of r.inspect) {
+      out.push({
+        heading: `Path 1 · What the agent said about ${i.repo} run ${i.run_id}`,
+        note: `Compared with GitHub's own record, read ${i.fetched_at}: ${i.verdict}, conclusion ${i.conclusion ?? 'none'}, commit ${i.head_sha}. TrustShell needed no access to the agent or its keys. ${i.run_url}`,
+        rows: i.claims.length ? i.claims.map((c) => ({ status: c.status, text: c.claim, detail: c.scope })) : [{ status: 'NOT_CHECKED', text: 'No claims were given for this run.' }],
+      });
+    }
+  } else {
+    out.push({ heading: 'Path 1 · What the agent said about a GitHub Actions run', note: 'Not used in this report.', rows: [] });
+  }
+  if (r.bound_claims.length) {
+    out.push({
+      heading: 'Claims you paired with a command',
+      note: 'You chose which command decides each claim. TrustShell only reads how that command ended.',
+      rows: r.bound_claims.map((b) => ({ status: b.status, text: b.claim, detail: `decided by ${b.decided_by}: ${b.why}` })),
+    });
+  }
+  const g = r.guard;
+  out.push({
+    heading: 'Path 2 · Commands that went through trustshell run',
+    note: g.commands.length
+      ? `Only these. Policy ${g.policy.state}, ${g.policy.signed ? 'signed' : 'not signed'}, nonce ${g.policy.nonce ?? 'none'}. Record chain ${g.ledger.verdict}, ${g.ledger.count} records.`
+      : 'No command went through TrustShell, so this report says nothing about what the agent ran.',
+    rows: g.commands.map((c) => ({ status: c.decision, text: `#${c.seq} ${c.action}: ${c.result}`, detail: c.reasons.join('; ') || undefined })),
+  });
+  if (g.ledger.breaks.length) out.push({ heading: 'The record chain is broken', rows: g.ledger.breaks.map((text) => ({ text })) });
+  out.push({ heading: 'What Guard saw', rows: g.mediated.map((text) => ({ text })) });
+  out.push({ heading: 'What this report cannot see', rows: g.not_mediated.map((text) => ({ text })) });
+  return out;
+}
+
+const INTRO = 'There is no overall score. Each line says what was checked and what it does not show.';
+const PRIVACY = 'Made on this machine. Nothing was uploaded. evidence/policy.json can hold local file paths: read it before sharing this folder.';
+
+const mdSafe = (s: string): string => s.replace(/[\r\n]+/g, ' ').replace(/([\\`*_[\]<>|])/g, '\\$1');
+
+export function renderTrustReportMarkdown(r: TrustReport): string {
+  const out = [`# ${mdSafe(r.title)}`, '', `${INTRO} Made ${r.generated_at} by ${mdSafe(r.generator)}.`, ''];
+  for (const b of blocks(r)) {
+    out.push(`## ${mdSafe(b.heading)}`, '');
+    if (b.note) out.push(mdSafe(b.note), '');
+    for (const row of b.rows) out.push(`- ${row.status ? `**${row.status}** ` : ''}${mdSafe(row.text)}${row.detail ? `\n  - ${mdSafe(row.detail)}` : ''}`);
+    if (b.rows.length) out.push('');
+  }
+  out.push('---', '', mdSafe(PRIVACY), '');
+  return out.join('\n');
+}
+
+const esc = (s: string): string => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c] as string);
+
+const CSS = `:root{--bg:#fff;--fg:#1b1f24;--muted:#57606a;--line:#d0d7de;--ok:#1a7f37;--bad:#cf222e;--nc:#9a6700}
+@media (prefers-color-scheme:dark){:root{--bg:#0d1117;--fg:#e6edf3;--muted:#8d96a0;--line:#30363d;--ok:#3fb950;--bad:#f85149;--nc:#d29922}}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--fg);font:15px/1.5 system-ui,-apple-system,"Segoe UI",sans-serif}
+main{max-width:760px;margin:0 auto;padding:24px 16px}h1{font-size:22px;margin:0 0 8px}h2{font-size:16px;margin:24px 0 8px}p{margin:0 0 8px;overflow-wrap:anywhere}
+ul{padding-left:20px;margin:0}li{margin:6px 0;overflow-wrap:anywhere}.d{color:var(--muted);font-size:14px;display:block}.n{color:var(--muted)}
+.SUPPORTED,.ALLOWED{color:var(--ok)}.CONTRADICTED,.DENIED{color:var(--bad)}.NOT_CHECKED{color:var(--nc)}footer{margin-top:24px;padding-top:12px;border-top:1px solid var(--line);color:var(--muted);font-size:13px}`;
+
+export function renderTrustReportHtml(r: TrustReport): string {
+  const out = [
+    '<!doctype html>',
+    '<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">',
+    // No script, no remote anything: a stranger may open this file.
+    `<meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'">`,
+    `<title>${esc(r.title)}</title><style>${CSS}</style></head><body><main>`,
+    `<h1>${esc(r.title)}</h1><p class="n">${esc(INTRO)} Made ${esc(r.generated_at)} by ${esc(r.generator)}.</p>`,
+  ];
+  for (const b of blocks(r)) {
+    out.push(`<h2>${esc(b.heading)}</h2>`);
+    if (b.note) out.push(`<p class="n">${esc(b.note)}</p>`);
+    if (b.rows.length) {
+      out.push('<ul>');
+      for (const row of b.rows) out.push(`<li>${row.status ? `<strong class="${esc(row.status)}">${esc(row.status)}</strong> ` : ''}${esc(row.text)}${row.detail ? `<span class="d">${esc(row.detail)}</span>` : ''}</li>`);
+      out.push('</ul>');
+    }
+  }
+  out.push(`<footer>${esc(PRIVACY)}</footer></main></body></html>`, '');
+  return out.join('\n');
+}
+
+// ── writing and verifying a report folder ──────────────────────────────────
+
+interface IO {
+  out: (s: string) => void;
+  err: (s: string) => void;
+}
+
+function walk(root: string, dir = root): string[] {
+  return readdirSync(dir, { withFileTypes: true }).flatMap((e) => {
+    const p = join(dir, e.name);
+    return e.isDirectory() ? walk(root, p) : [relative(root, p).split(sep).join('/')];
+  });
+}
+
+function readLimited(path: string): string {
+  if (statSync(path).size > MAX_INPUT_BYTES) throw new Error(`${path} is larger than ${MAX_INPUT_BYTES} bytes`);
+  return decodeText(readFileSync(path));
+}
+
+function parseBind(raw: string, cwd: string): Bind | string {
+  const at = raw.indexOf('=');
+  if (at < 1 || at === raw.length - 1) return `--bind needs "<tool or script>=<claim>", got: ${clean(raw, 80)}`;
+  const decided_by = clean(raw.slice(0, at), 200).trim();
+  const claim = clean(raw.slice(at + 1), 300).trim();
+  if (!decided_by || !claim) return `--bind needs "<tool or script>=<claim>", got: ${clean(raw, 80)}`;
+  const file = resolve(cwd, decided_by);
+  if (existsSync(file) && statSync(file).isFile()) return { claim, decided_by, tool: null, script_sha256: sha256(readFileSync(file)) };
+  if (!/^[A-Za-z0-9_.:-]{1,128}$/.test(decided_by)) return `--bind: ${clean(decided_by, 80)} is not a tool name or a file that exists`;
+  return { claim, decided_by, tool: decided_by.replace(/^tool:/, ''), script_sha256: null };
+}
+
+/** The sealed receipt names the manifest's sha256 in args_hash, so one signature covers every listed file. */
+export function sealBody(manifestSha: string, createdAt: string): SealableReceipt {
+  return {
+    header: { receipt_id: `trust-report-${manifestSha.slice(0, 16)}`, prev_receipt_id: null, prev_hash: null, created_at: createdAt, env: { network: 'none', chain_id: 0, is_simulated: true } },
+    subject: { agent: { agent_id: 'local', agent_name: 'trustshell trust-report' }, owner: { wallet: null, assurance: null, status: 'none' } },
+    request: { tool: { name: 'trust-report', class: 'read' }, origin: 'Cli', args_hash: `0x${manifestSha}`, amount_raw: null, payee: null, asset: null, chain_id: null },
+    decision: {
+      verdict: 'ALLOW',
+      blocking: false,
+      executed: true,
+      reasons: ['sealed the manifest of a trust report'],
+      checks: [{ name: 'manifest', outcome: 'PASS', source: 'owner' }],
+      does_not_attest: ['that the commands in the report test what the claims say', 'anything done outside trustshell run'],
+      policy: { policy_hash: null, signer: null, signature: 'NOT_CHECKED', expires_at: null, revocation: 'NOT_CHECKED' },
+      limits: {},
+      laya: { lane: null, mode: 'shadow', consulted: false },
+    },
+    payment: { status: 'none' },
+    verification: { status: 'none' },
+  };
+}
+
+async function create(argv: string[], io: IO, env: NodeJS.ProcessEnv, cwd: string): Promise<number> {
+  let out: string | undefined;
+  let title = 'TrustShell Trust Report';
+  let json = false;
+  const recordPaths: string[] = [];
+  const binds: Bind[] = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i] as string;
+    const value = (): string | undefined => argv[++i];
+    if (a === '--json') json = true;
+    else if (a === '--out' || a === '--title' || a === '--record' || a === '--bind') {
+      const v = value();
+      if (v === undefined) return usage(io, `${a} needs a value`);
+      if (a === '--out') out = v;
+      else if (a === '--title') title = v;
+      else if (a === '--record') recordPaths.push(v);
+      else {
+        const b = parseBind(v, cwd);
+        if (typeof b === 'string') return usage(io, b);
+        binds.push(b);
+      }
+    } else return usage(io, `unexpected ${clean(a, 60)}`);
+  }
+  if (!out) return usage(io, '--out <new dir> is required');
+  const outDir = resolve(cwd, out);
+  if (existsSync(outDir) && readdirSync(outDir).length > 0) return usage(io, `${out} already has files in it. Name a new folder; a report is never written over another.`);
+
+  const home = trustshellHome(env);
+  const ledgerPath = join(home, GUARD_RECEIPTS_FILE);
+  const policyPath = join(home, POLICY_FILE);
+  const ledgerText = existsSync(ledgerPath) ? readLimited(ledgerPath) : '';
+  const policyText = existsSync(policyPath) ? readLimited(policyPath) : null;
+  if (recordPaths.length === 0 && binds.length === 0 && ledgerText === '') {
+    io.err(`NOT_CHECKED nothing to report: no --record, no --bind, and no Guard records in ${home}.`);
+    return 2;
+  }
+
+  mkdirSync(join(outDir, 'evidence'), { recursive: true });
+  const records: BuildInput['records'] = [];
+  try {
+    recordPaths.forEach((p, i) => {
+      const from = resolve(cwd, p);
+      const rel = `evidence/inspect-${i + 1}/record.json`;
+      mkdirSync(join(outDir, dirname(rel)), { recursive: true });
+      copyFileSync(from, join(outDir, rel));
+      for (const card of ['card.md', 'card.html']) {
+        const c = join(dirname(from), card);
+        if (existsSync(c)) copyFileSync(c, join(outDir, dirname(rel), card));
+      }
+      records.push({ path: rel, text: readLimited(from) });
+    });
+    if (ledgerText !== '') writeFileSync(join(outDir, 'evidence', GUARD_RECEIPTS_FILE), ledgerText);
+    if (policyText !== null) writeFileSync(join(outDir, 'evidence', POLICY_FILE), policyText);
+    const report = buildTrustReport({ title, generatedAt: new Date().toISOString(), generator: `trustshell ${resolvePackageVersion(__dirname)}`, binds, records, ledgerText, policyText });
+    writeFileSync(join(outDir, 'report.json'), `${JSON.stringify(report, null, 2)}\n`);
+    writeFileSync(join(outDir, 'trust-report.md'), renderTrustReportMarkdown(report));
+    writeFileSync(join(outDir, 'trust-report.html'), renderTrustReportHtml(report));
+    const manifest = walk(outDir).sort().map((f) => `${sha256(readFileSync(join(outDir, f)))}  ${f}`).join('\n');
+    writeFileSync(join(outDir, MANIFEST), `${manifest}\n`);
+    const { key } = signingKey(home);
+    const seal = await signOwnerReceipt(sealBody(sha256(`${manifest}\n`), report.generated_at), key);
+    writeFileSync(join(outDir, SEAL), `${JSON.stringify(seal, null, 2)}\n`);
+    const root = installKeyRootHex(key);
+    if (json) io.out(JSON.stringify({ report, out: outDir, root }, null, 2));
+    else {
+      const count = (s: string) => report.inspect.reduce((n, i) => n + i.claims.filter((c) => c.status === s).length, 0) + report.bound_claims.filter((b) => b.status === s).length;
+      io.out(`Trust Report written to ${outDir}`);
+      io.out(`  claims     ${count('SUPPORTED')} supported, ${count('CONTRADICTED')} contradicted, ${count('NOT_CHECKED')} not checked`);
+      io.out(`  commands   ${report.guard.commands.filter((c) => c.decision === 'ALLOWED').length} allowed, ${report.guard.commands.filter((c) => c.decision !== 'ALLOWED').length} refused, chain ${report.guard.ledger.verdict}`);
+      io.out('  read       trust-report.html or trust-report.md; the evidence is in evidence/');
+      io.out(`  check it   trustshell trust-report verify ${out} --root ${root}`);
+      io.out('  not seen   anything the agent did without trustshell run');
+    }
+    return report.exit;
+  } catch (e) {
+    io.err(`trust-report: could not build the report: ${clean((e as Error).message, 300)}`);
+    return 3;
+  }
+}
+
+function usage(io: IO, why: string): number {
+  io.err(`trust-report: ${why}\n${TRUST_REPORT_USAGE}`);
+  return 2;
+}
+
+/** Exit 0 VERIFIED, 1 FAILED, 2 NOT_CHECKED (nothing to check, or no key to check authorship against). */
+async function verify(argv: string[], io: IO, cwd: string): Promise<number> {
+  let dirArg: string | undefined;
+  let root: string | undefined;
+  let json = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i] as string;
+    if (a === '--json') json = true;
+    else if (a === '--root') root = argv[++i];
+    else if (a.startsWith('--')) return usage(io, `unexpected ${clean(a, 60)}`);
+    else if (dirArg === undefined) dirArg = a;
+    else return usage(io, `unexpected ${clean(a, 60)}`);
+  }
+  if (!dirArg) return usage(io, 'verify needs <dir>');
+  const dir = resolve(cwd, dirArg);
+  const manifestPath = join(dir, MANIFEST);
+  if (!existsSync(manifestPath)) {
+    io.err(`NOT_CHECKED no ${MANIFEST} in ${dirArg}: this is not a trust report folder, or it is incomplete.`);
+    return 2;
+  }
+  const problems: string[] = [];
+  const manifestText = readLimited(manifestPath);
+  const listed = new Map(
+    manifestText.split('\n').filter(Boolean).map((l) => {
+      const at = l.indexOf('  ');
+      return [l.slice(at + 2), l.slice(0, at)] as const;
+    }),
+  );
+  for (const [f, want] of listed) {
+    const p = join(dir, f);
+    if (f.includes('..') || !existsSync(p)) problems.push(`${f} is listed but missing`);
+    else if (sha256(readFileSync(p)) !== want) problems.push(`${f} changed after the report was made`);
+  }
+  for (const f of walk(dir)) if (f !== MANIFEST && f !== SEAL && !listed.has(f)) problems.push(`${f} is not in the manifest`);
+
+  let authorship: 'VERIFIED' | 'FAILED' | 'NOT_CHECKED' = 'NOT_CHECKED';
+  try {
+    const receipt = JSON.parse(readLimited(join(dir, SEAL)));
+    if (receipt?.request?.args_hash !== `0x${sha256(manifestText)}`) problems.push('the seal does not name this manifest');
+    const result = await verifyReceiptOffline(receipt, root ? { trustedRoots: root.split(',') } : {});
+    const integrity = result.claims?.integrity?.status;
+    if (root) {
+      authorship = integrity === 'VERIFIED' && result.sealer?.trusted ? 'VERIFIED' : 'FAILED';
+      if (authorship === 'FAILED') problems.push('the seal was not made by the key you pinned, or it was altered');
+    } else if (integrity === 'FAILED') problems.push('the seal was altered');
+  } catch (e) {
+    problems.push(`the seal could not be read: ${clean((e as Error).message, 160)}`);
+  }
+
+  try {
+    const report = JSON.parse(readLimited(join(dir, 'report.json'))) as TrustReport;
+    const records = report.inputs.records.map((path) => {
+      if (path.includes('..')) throw new Error(`bad evidence path ${clean(path, 80)}`);
+      return { path, text: readLimited(join(dir, path)) };
+    });
+    const ledger = join(dir, 'evidence', GUARD_RECEIPTS_FILE);
+    const policy = join(dir, 'evidence', POLICY_FILE);
+    const again = buildTrustReport({
+      title: report.title,
+      generatedAt: report.generated_at,
+      generator: report.generator,
+      binds: report.inputs.binds,
+      records,
+      ledgerText: existsSync(ledger) ? readLimited(ledger) : '',
+      policyText: existsSync(policy) ? readLimited(policy) : null,
+    });
+    if (jcsSha256(again) !== jcsSha256(report)) problems.push('report.json does not match what its evidence produces');
+    if (renderTrustReportMarkdown(again) !== readLimited(join(dir, 'trust-report.md'))) problems.push('trust-report.md does not match what its evidence produces');
+    if (renderTrustReportHtml(again) !== readLimited(join(dir, 'trust-report.html'))) problems.push('trust-report.html does not match what its evidence produces');
+    if (again.guard.ledger.verdict === 'BROKEN') problems.push('the Guard record chain is broken');
+    for (const i of again.inspect) if (!i.digest_matches) problems.push(`${i.path}: its digest does not match its contents`);
+  } catch (e) {
+    problems.push(`the report could not be rebuilt: ${clean((e as Error).message, 200)}`);
+  }
+
+  const verdict = problems.length ? 'FAILED' : authorship === 'VERIFIED' ? 'VERIFIED' : 'NOT_CHECKED';
+  if (json) io.out(JSON.stringify({ verdict, authorship, problems }, null, 2));
+  else {
+    io.out(`${verdict} ${problems.length ? 'this report does not match its evidence' : authorship === 'VERIFIED' ? 'every file is whole, the report matches its evidence, and the pinned key sealed it' : 'every file is whole and the report matches its evidence, but who made it was not checked: pass --root <key from the author>'}`);
+    for (const p of problems) io.out(`  - ${p}`);
+    io.out('  does not show: that the commands test what the claims say, or anything done outside trustshell run');
+  }
+  return problems.length ? 1 : authorship === 'VERIFIED' ? 0 : 2;
+}
+
+export async function runTrustReport(argv: string[], io: IO, env: NodeJS.ProcessEnv = process.env, cwd: string = process.cwd()): Promise<number> {
+  if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+    io.out(TRUST_REPORT_USAGE);
+    return argv.length === 0 ? 2 : 0;
+  }
+  return argv[0] === 'verify' ? verify(argv.slice(1), io, cwd) : create(argv, io, env, cwd);
+}
diff --git a/src/lib/guardrails.ts b/src/lib/guardrails.ts
index d32d9604..6b6e9f2f 100644
--- a/src/lib/guardrails.ts
+++ b/src/lib/guardrails.ts
@@ -240,7 +240,7 @@ export interface PolicyDocument {
 }
 
 /** The commands that only read or write local files: what `guard init` allows. `learn` is listed, but its `check run` and `probe run` run a stored shell command and the CLI denies them while a policy is in force. */
-export const LOCAL_TOOLS = ['bundle', 'ground', 'init', 'inspect', 'learn', 'profile', 'quarantine', 'recall', 'redact', 'remember', 'report', 'traps'] as const;
+export const LOCAL_TOOLS = ['bundle', 'ground', 'init', 'inspect', 'learn', 'profile', 'quarantine', 'recall', 'redact', 'remember', 'report', 'traps', 'trust-report'] as const;
 
 const ACTION = /^(spend|post|tool|tool:[A-Za-z0-9_.:-]{1,128})$/;
 /** PURE. Is `a` an entry a policy's `actions` may hold (spend, post, tool or tool:<name>)? */
@@ -592,7 +592,7 @@ export interface GuardRecord {
   requested: Omit<GuardRequest, 'script' | 'executable_file'> & { action: string; script_sha256?: string; executable_sha256?: string };
   authorized: GuardDecision & { policy_sha256: string | null; policy_nonce: string | null; policy_signed_by: string | null };
   /** outcome only: what the started process reported. Never what it did. */
-  executed: { exit_code: number | null; signal: string | null; duration_ms: number } | 'not run' | null;
+  executed: { exit_code: number | null; signal: string | null; duration_ms: number; start_error?: string } | 'not run' | null;
   assurance_scope: AssuranceScope;
   /** policy-change only: what changed it, and the policy hash before (null: there was none) and after. */
   change?: { via: string; before_sha256: string | null; after_sha256: string };
diff --git a/tests/trust-report.test.ts b/tests/trust-report.test.ts
new file mode 100644
index 00000000..42d7a865
--- /dev/null
+++ b/tests/trust-report.test.ts
@@ -0,0 +1,232 @@
+/**
+ * `trustshell trust-report`: the report must say what the evidence says, and must fail when either changes.
+ * Records come from the real `guard` and `run` code; only process start is faked.
+ */
+import { createHash, generateKeyPairSync } from 'node:crypto';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync, cpSync, readdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { runGuard, runRun, type Spawner } from '../src/cli/guard';
+import { signOwnerReceipt } from '../src/lib/owner-receipt';
+import { NOT_MEDIATED_ALWAYS, buildTrustReport, sealBody, renderTrustReportHtml, renderTrustReportMarkdown, runTrustReport, type TrustReport } from '../src/cli/trust-report';
+import { ACTION_EVIDENCE_SCHEMA, digestRecord } from '../src/lib/action-evidence';
+
+const envOf = (v: Record<string, string>) => v as unknown as NodeJS.ProcessEnv;
+const quiet = () => {
+  const lines: string[] = [];
+  return { lines, io: { out: (s: string) => lines.push(s), err: (s: string) => lines.push(s) } };
+};
+
+function record(claims: { status: string; claim: string }[], conclusion = 'success', verdict = 'COMPLETE') {
+  const rec = {
+    schema: ACTION_EVIDENCE_SCHEMA,
+    observation: { url: 'https://github.com/o/r/actions/runs/1', owner: 'o', repo: 'r', run_id: 1, head_sha: 'abc', conclusion, check: { verdict, results: [] }, fetchedAt: '2026-11-08T00:00:00Z' },
+    claims: claims.map((c) => ({ ...c, scope: 'scope text' })),
+  };
+  return { record: rec, digest: digestRecord(rec as never) };
+}
+
+describe('trust-report', () => {
+  let dir = '';
+  let env = envOf({});
+  const started = (status: number | null, error?: string): Spawner => () => ({ status, signal: null, error });
+  const run = (tool: string, spawn: Spawner) => runRun(['--tool', tool, '--', tool], quiet().io, env, spawn);
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'ts-trust-report-'));
+    env = envOf({ TRUSTSHELL_HOME: join(dir, 'home') });
+    expect(runGuard(['init'], quiet().io, env)).toBe(0);
+    expect(runGuard(['allow', 'tool:fake'], quiet().io, env)).toBe(0);
+  });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+  async function make(args: string[]): Promise<{ code: number; out: string; report: TrustReport }> {
+    const q = quiet();
+    const out = join(dir, 'out');
+    const code = await runTrustReport(['--out', out, ...args], q.io, env, dir);
+    return { code, out, report: JSON.parse(readFileSync(join(out, 'report.json'), 'utf8')) };
+  }
+  const key = (out: string): string => JSON.parse(readFileSync(join(out, 'report-receipt.json'), 'utf8')).header.signer.public_key;
+  async function verify(out: string, root?: string): Promise<number> {
+    return runTrustReport(['verify', out, ...(root ? ['--root', root] : [])], quiet().io, env, dir);
+  }
+
+  it('a claim paired with a command that exited 0 is SUPPORTED, and says what that does not show', async () => {
+    expect(run('fake', started(0))).toBe(0);
+    const { code, report } = await make(['--bind', 'fake=All tests pass']);
+    expect(report.bound_claims[0]?.status).toBe('SUPPORTED');
+    expect(report.bound_claims[0]?.why).toContain('not that it tests what the claim says');
+    expect(code).toBe(0);
+  });
+
+  it('the last run decides: a pass followed by a failure is CONTRADICTED', async () => {
+    run('fake', started(0));
+    run('fake', started(1));
+    const { code, report } = await make(['--bind', 'fake=All tests pass']);
+    expect(report.bound_claims[0]?.status).toBe('CONTRADICTED');
+    expect(code).toBe(1);
+    expect(report.next_actions.join(' ')).toContain('Do not accept "All tests pass"');
+  });
+
+  it('a command that never ran, or could not start, is NOT_CHECKED and exits 3', async () => {
+    run('fake', started(null, 'ENOENT'));
+    const { code, report } = await make(['--bind', 'fake=It works', '--bind', 'other=It lints']);
+    expect(report.guard.commands[0]?.result).toBe('could not start');
+    expect(report.bound_claims.map((b) => b.status)).toEqual(['NOT_CHECKED', 'NOT_CHECKED']);
+    expect(code).toBe(3);
+  });
+
+  it('a refused command is shown with its reason, never as run, and is not itself a failure', async () => {
+    run('fake', started(0));
+    expect(run('curl', started(0))).toBe(5);
+    const { code, report } = await make(['--bind', 'fake=All tests pass']);
+    const denied = report.guard.commands.filter((c) => c.decision === 'DENIED');
+    expect(denied).toHaveLength(1);
+    expect(denied[0]?.result).toBe('never started');
+    expect(denied[0]?.reasons[0]).toContain('does not list tool:curl');
+    expect(report.next_actions.join(' ')).toContain('guard allow tool:curl');
+    expect(code).toBe(0);
+  });
+
+  it('every rendering states what it cannot see', async () => {
+    run('fake', started(0));
+    const { out, report } = await make(['--bind', 'fake=x']);
+    expect(report.guard.not_mediated).toContain(NOT_MEDIATED_ALWAYS);
+    expect(readFileSync(join(out, 'trust-report.md'), 'utf8')).toContain('This report cannot see them');
+    expect(readFileSync(join(out, 'trust-report.html'), 'utf8')).toContain('This report cannot see them');
+  });
+
+  it('agent text cannot inject into the HTML or Markdown', () => {
+    const evil = '<img src=x onerror=alert(1)> `code` **bold**';
+    const rec = record([{ status: 'NOT_CHECKED', claim: evil }]);
+    const report = buildTrustReport({ title: 'T', generatedAt: 'now', generator: 'g', binds: [], records: [{ path: 'r', text: JSON.stringify(rec) }], ledgerText: '', policyText: null });
+    const html = renderTrustReportHtml(report);
+    expect(html).not.toContain('<img');
+    expect(html).toContain('&lt;img');
+    expect(html).not.toContain('<script');
+    expect(renderTrustReportMarkdown(report)).toContain('\\`code\\`');
+  });
+
+  it('an Inspect record that changed after it was made is a finding', () => {
+    const rec = record([{ status: 'SUPPORTED', claim: 'x' }]);
+    (rec.digest as { value: string }).value = 'f'.repeat(64);
+    const report = buildTrustReport({ title: 'T', generatedAt: 'now', generator: 'g', binds: [], records: [{ path: 'r', text: JSON.stringify(rec) }], ledgerText: '', policyText: null });
+    expect(report.inspect[0]?.digest_matches).toBe(false);
+    expect(report.exit).toBe(1);
+  });
+
+  it('claims are carried with the run they came from, and a contradicted claim exits 1', async () => {
+    run('fake', started(0));
+    const file = join(dir, 'record.json');
+    writeFileSync(file, JSON.stringify(record([{ status: 'CONTRADICTED', claim: 'it passed' }], 'failure', 'FAILED')));
+    const { code, report } = await make(['--record', file]);
+    expect(report.inspect[0]?.claims[0]?.status).toBe('CONTRADICTED');
+    expect(report.next_actions.join(' ')).toContain('Do not accept "it passed"');
+    expect(code).toBe(1);
+  });
+
+  it('refuses a file that is not an Inspect record, and writes over nothing', async () => {
+    run('fake', started(0));
+    const bad = join(dir, 'bad.json');
+    writeFileSync(bad, '{"record":{"schema":"other"}}');
+    const q = quiet();
+    expect(await runTrustReport(['--out', join(dir, 'o1'), '--record', bad], q.io, env, dir)).toBe(3);
+    const full = join(dir, 'full');
+    cpSync(bad, join(full, 'x.json'), { recursive: true });
+    expect(await runTrustReport(['--out', full], quiet().io, env, dir)).toBe(2);
+    expect(readdirSync(full)).toEqual(['x.json']);
+  });
+
+  it('with nothing recorded there is nothing to report, not an empty pass', async () => {
+    const q = quiet();
+    const fresh = envOf({ TRUSTSHELL_HOME: join(dir, 'empty') });
+    expect(await runTrustReport(['--out', join(dir, 'o2')], q.io, fresh, dir)).toBe(2);
+    expect(q.lines.join(' ')).toContain('NOT_CHECKED');
+  });
+
+  describe('verify', () => {
+    let out = '';
+    let root = '';
+    beforeEach(async () => {
+      run('fake', started(0));
+      run('curl', started(0));
+      ({ out } = await make(['--bind', 'fake=All tests pass']));
+      root = key(out);
+    });
+
+    it('is VERIFIED with the sealing key and NOT_CHECKED without one', async () => {
+      expect(await verify(out, root)).toBe(0);
+      expect(await verify(out)).toBe(2);
+    });
+
+    it('fails with another key', async () => {
+      expect(await verify(out, `0x${'ab'.repeat(32)}`)).toBe(1);
+    });
+
+    it('a folder that is not a report is NOT_CHECKED', async () => {
+      expect(await verify(join(dir, 'home'))).toBe(2);
+    });
+
+    it.each([
+      ['report.json', (s: string) => s.replace('"SUPPORTED"', '"CONTRADICTED"')],
+      ['trust-report.md', (s: string) => `${s}more\n`],
+      ['trust-report.html', (s: string) => `${s}more\n`],
+      ['evidence/guard-receipts.jsonl', (s: string) => s.replace('"DENIED"', '"ALLOWED"')],
+      ['evidence/policy.json', (s: string) => s.replace('"subject"', '"subject" ')],
+      ['report-receipt.json', (s: string) => s.replace('trust-report-', 'other-report-')],
+    ])('fails when %s changes', async (file, edit) => {
+      const p = join(out, file);
+      const before = readFileSync(p, 'utf8');
+      const after = edit(before);
+      expect(after).not.toBe(before);
+      writeFileSync(p, after);
+      expect(await verify(out, root)).toBe(1);
+    });
+
+    it('fails when a file is added', async () => {
+      writeFileSync(join(out, 'evidence', 'added.txt'), 'x');
+      expect(await verify(out, root)).toBe(1);
+    });
+
+    /** Rewrites one line of the manifest so the file on disk matches it. */
+    function rewriteManifestLine(folder: string, file: string, text: string): void {
+      const m = join(folder, 'MANIFEST.sha256');
+      const hash = createHash('sha256').update(text).digest('hex');
+      const lines = readFileSync(m, 'utf8').split('\n').map((l) => (l.endsWith(`  ${file}`) ? `${hash}  ${file}` : l));
+      writeFileSync(m, lines.join('\n'));
+    }
+
+    it('fails when a file outside the report text changes and the manifest is rewritten: the seal names the manifest', async () => {
+      const file = join(dir, 'record.json');
+      writeFileSync(file, JSON.stringify(record([{ status: 'SUPPORTED', claim: 'x' }])));
+      writeFileSync(join(dir, 'card.md'), 'the card');
+      const q = quiet();
+      const second = join(dir, 'second');
+      await runTrustReport(['--out', second, '--record', file], q.io, env, dir);
+      const card = 'evidence/inspect-1/card.md';
+      writeFileSync(join(second, card), 'a different card');
+      rewriteManifestLine(second, card, 'a different card');
+      expect(await verify(second, key(second))).toBe(1);
+    });
+
+    it('fails, even with a new seal from another key, when the report no longer matches its evidence', async () => {
+      const text = readFileSync(join(out, 'report.json'), 'utf8').replace('"SUPPORTED"', '"CONTRADICTED"');
+      writeFileSync(join(out, 'report.json'), text);
+      rewriteManifestLine(out, 'report.json', text);
+      const manifest = readFileSync(join(out, 'MANIFEST.sha256'), 'utf8');
+      const { privateKey } = generateKeyPairSync('ed25519');
+      const body = sealBody(createHash('sha256').update(manifest).digest('hex'), 'now');
+      writeFileSync(join(out, 'report-receipt.json'), JSON.stringify(await signOwnerReceipt(body, privateKey)));
+      expect(await verify(out)).toBe(1);
+    });
+
+    it('fails when a file is rewritten and the manifest is rewritten to match', async () => {
+      const text = `${readFileSync(join(out, 'trust-report.md'), 'utf8')}forged\n`;
+      writeFileSync(join(out, 'trust-report.md'), text);
+      const m = join(out, 'MANIFEST.sha256');
+      const hash = createHash('sha256').update(text).digest('hex');
+      writeFileSync(m, readFileSync(m, 'utf8').replace(/^[0-9a-f]{64} {2}trust-report\.md$/m, `${hash}  trust-report.md`));
+      expect(await verify(out, root)).toBe(1);
+    });
+  });
+});

From 00e4d3545fa25ea0fd8e838840289b045ba77876 Mon Sep 17 00:00:00 2001
From: Sean Goodwin <dealappseo@gmail.com>
Date: Sun, 8 Nov 2026 15:15:05 -0800
Subject: [PATCH 2/4] docs: list trust-report in the egress tables and the
 Guard demo output

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/api-reference.md    | 1 +
 docs/guard-carry-demo.md | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/api-reference.md b/docs/api-reference.md
index 47910e9b..ba9e9561 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -793,6 +793,7 @@ CHECKED; `check <runUrl>`, `inspect` and `report` exit `3`. **Not every command
 | `ground` | **none** — reads the `--source` file. Since 1.7.0 | none |
 | `init` | **none** — writes one local file. `--pai` runs `scripts/init-pai.mjs` (live register) | none |
 | `report` | **none** — it has no fetch and no URL parameter | none |
+| `trust-report` | **none** — reads the Guard records and the `check` records you name, and writes one new folder | none |
 | `profile` | **none** — reads and writes `.trustshell/profile.md`. Since 1.8.0 | none |
 | `remember` | **none** — writes the local memory file | none |
 | `recall` | **none** — reads the local memory file | none |
diff --git a/docs/guard-carry-demo.md b/docs/guard-carry-demo.md
index 2995abb9..f51bef65 100644
--- a/docs/guard-carry-demo.md
+++ b/docs/guard-carry-demo.md
@@ -105,7 +105,7 @@ of the node binary, so the guard can tell them apart by name.
      | Trust settings: autonomy ask_first; confidence gate 0.8; human-in-the-loop gate 70
      |
      | Owner policy (enforced by the harness, not by you; anything not listed is denied):
-     | - allowed actions: tool:bundle, tool:ground, tool:init, tool:inspect, tool:learn, tool:profile, tool:quarantine, tool:recall, tool:redact, tool:remember, tool:report, tool:traps, tool:reader
+     | - allowed actions: tool:bundle, tool:ground, tool:init, tool:inspect, tool:learn, tool:profile, tool:quarantine, tool:recall, tool:redact, tool:remember, tool:report, tool:traps, tool:trust-report, tool:reader
      | - limits: per action 0, per day 0, in total 0 (smallest units)
      | - expires: 2026-11-21T18:38:47.000Z
      |

From 927f659f71902e69fda752d2ba48b539aa0830ec Mon Sep 17 00:00:00 2001
From: Sean Goodwin <dealappseo@gmail.com>
Date: Sun, 8 Nov 2026 15:27:42 -0800
Subject: [PATCH 3/4] fix(report): a failure cannot be replaced by an easier
 run

In a real run, a last invocation that selected no tests exited 0 and
counted as support. A claim paired with a command that ran with more
than one command line is now NOT_CHECKED.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 dist/cli/trust-report.js   |  5 +++++
 docs/api-reference.md      | 12 ++++++++++++
 src/cli/trust-report.ts    |  4 ++++
 tests/trust-report.test.ts |  9 +++++++++
 4 files changed, 30 insertions(+)

diff --git a/dist/cli/trust-report.js b/dist/cli/trust-report.js
index e7fbdfd4..500f7ccc 100644
--- a/dist/cli/trust-report.js
+++ b/dist/cli/trust-report.js
@@ -103,6 +103,11 @@ function decideBound(b, commands) {
     const last = hits[hits.length - 1];
     if (!last)
         return { ...base, status: 'NOT_CHECKED', why: 'that command was never asked for through TrustShell', record_seq: null };
+    // A last run with other arguments could select nothing and exit 0, so "the last run" only means one thing
+    // when every run was the same command. An agent must not be able to replace a failure with an easier run.
+    const variants = new Set(hits.filter((c) => c.decision === 'ALLOWED').map((c) => c.command_sha256));
+    if (variants.size > 1)
+        return { ...base, status: 'NOT_CHECKED', why: `it ran with ${variants.size} different command lines, so no one run decides this. Run the exact command you trust, using a fresh TRUSTSHELL_HOME.`, record_seq: last.seq };
     const scope = `record ${last.seq}`;
     if (last.exit_code === 0)
         return { ...base, status: 'SUPPORTED', why: `the last time it ran through trustshell run it exited 0 (${scope}). That shows this command passed, not that it tests what the claim says.`, record_seq: last.seq };
diff --git a/docs/api-reference.md b/docs/api-reference.md
index ba9e9561..374fd548 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -750,6 +750,18 @@ These are the facts worked out in erc-8004/erc-8004-contracts#99. The tests repl
 
 Print the after-create table, one Honesty A line, and counted first_pass fields. A NOT_CHECKED body or a missing column is NOT_CHECKED, never 0. post-HAL is printed only when post_hal_verdict is in the JSON. can_bind is true only when GET /readiness exact_true.HUMAN_AGENT_BIND_ENABLED is true. can_stake stays shadow — not live unless SAYS_STAKE_LIVE is the exact string 'true'.
 
+### `trustshell trust-report --out <new dir> [--record <record.json>]... [--bind "<tool or script>=<claim>"]...`
+
+One readable report and its evidence, made from what TrustShell already recorded. Local files only, no network. See `examples/own-agent/README.md`.
+
+It keeps two things apart. **Path 1** is what the agent said about a GitHub Actions run, from the `record.json` files `check --out` writes. **Path 2** is every command that went through `trustshell run`. It cannot see anything else the agent did, and says so.
+
+`--bind` pairs a claim with the command that decides it, by a script file or a tool name. The last run decides. If that command ran with more than one command line, the claim is `NOT_CHECKED`, so a failure cannot be replaced by an easier run.
+
+Exit `0` every claim SUPPORTED, `1` a claim CONTRADICTED or a record broken, `2` usage or nothing to report, `3` anything NOT_CHECKED.
+
+`trustshell trust-report verify <dir> [--root <key>]` proves the folder is whole, matches its evidence and was sealed by the key you pin. Exit `0` VERIFIED, `1` FAILED, `2` NOT_CHECKED (no `--root`, so who made it was not checked).
+
 ### `trustshell report [--session <path>] [--evidence <path>]`
 
 State what your session log and your saved GitHub evidence **together** support, and name where
diff --git a/src/cli/trust-report.ts b/src/cli/trust-report.ts
index a8c75d7b..aa56a474 100644
--- a/src/cli/trust-report.ts
+++ b/src/cli/trust-report.ts
@@ -170,6 +170,10 @@ function decideBound(b: Bind, commands: CommandRow[]): BoundClaim {
   const hits = commands.filter((c) => bindMatches(b, c));
   const last = hits[hits.length - 1];
   if (!last) return { ...base, status: 'NOT_CHECKED', why: 'that command was never asked for through TrustShell', record_seq: null };
+  // A last run with other arguments could select nothing and exit 0, so "the last run" only means one thing
+  // when every run was the same command. An agent must not be able to replace a failure with an easier run.
+  const variants = new Set(hits.filter((c) => c.decision === 'ALLOWED').map((c) => c.command_sha256));
+  if (variants.size > 1) return { ...base, status: 'NOT_CHECKED', why: `it ran with ${variants.size} different command lines, so no one run decides this. Run the exact command you trust, using a fresh TRUSTSHELL_HOME.`, record_seq: last.seq };
   const scope = `record ${last.seq}`;
   if (last.exit_code === 0) return { ...base, status: 'SUPPORTED', why: `the last time it ran through trustshell run it exited 0 (${scope}). That shows this command passed, not that it tests what the claim says.`, record_seq: last.seq };
   if (last.exit_code !== null) return { ...base, status: 'CONTRADICTED', why: `the last time it ran through trustshell run it exited ${last.exit_code} (${scope})`, record_seq: last.seq };
diff --git a/tests/trust-report.test.ts b/tests/trust-report.test.ts
index 42d7a865..5d7a901c 100644
--- a/tests/trust-report.test.ts
+++ b/tests/trust-report.test.ts
@@ -68,6 +68,15 @@ describe('trust-report', () => {
     expect(report.next_actions.join(' ')).toContain('Do not accept "All tests pass"');
   });
 
+  it('a failure cannot be replaced by an easier run: different command lines decide nothing', async () => {
+    run('fake', started(1));
+    expect(runRun(['--tool', 'fake', '--', 'fake', '--select-nothing'], quiet().io, env, started(0))).toBe(0);
+    const { code, report } = await make(['--bind', 'fake=All tests pass']);
+    expect(report.bound_claims[0]?.status).toBe('NOT_CHECKED');
+    expect(report.bound_claims[0]?.why).toContain('2 different command lines');
+    expect(code).toBe(3);
+  });
+
   it('a command that never ran, or could not start, is NOT_CHECKED and exits 3', async () => {
     run('fake', started(null, 'ENOENT'));
     const { code, report } = await make(['--bind', 'fake=It works', '--bind', 'other=It lints']);

From a9724a86c33cf6c292771c3071081d5470d2bb80 Mon Sep 17 00:00:00 2001
From: Sean Goodwin <dealappseo@gmail.com>
Date: Sun, 8 Nov 2026 15:29:05 -0800
Subject: [PATCH 4/4] test(stranger): walk trust-report like every other
 command

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 tests/e2e-stranger.test.ts | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/tests/e2e-stranger.test.ts b/tests/e2e-stranger.test.ts
index 4d5984ae..6b795c8d 100644
--- a/tests/e2e-stranger.test.ts
+++ b/tests/e2e-stranger.test.ts
@@ -399,6 +399,10 @@ describe('stranger e2e on current main', () => {
       expect(verified.code).toBe(0);
       expect(verified.out).toContain('trusted as this install');
       // run with no policy authorizes nothing: it starts nothing and says so (exit 2, NOT_CHECKED).
+      // A folder that is not a report is NOT_CHECKED (exit 2), never a pass.
+      const report = await go(['trust-report', 'verify', join(dir, 'no-such-report')]);
+      expect(report.code).toBe(2);
+      expect(report.err).toMatch(/^NOT_CHECKED/);
       const ran = await go(['run', '--tool', 'git', '--', 'node', '-e', '0']);
       expect(ran.code).toBe(2);
       expect(ran.err).toMatch(/^NOT_CHECKED no policy/);