fleetproof 0.2.1__tar.gz → 0.3.1__tar.gz

{fleetproof-0.2.1/src/fleetproof.egg-info → fleetproof-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fleetproof
-Version: 0.2.1
+Version: 0.3.1
 Summary: Independent, out-of-band verification for agent fleets.
 Author: Gathrazio
 License: MIT
@@ -74,6 +74,7 @@ No language model sits in the grading path. Grading is comparison.
 | SubagentStop hook | The per-subagent gate: records what the agent claimed, grades it at that agent's tier, blocks a false "done". |
 | `fleetproof fleet` | The dispatch board: every dispatch, its state, its tier, and whether anything graded it. |
 | `fleetproof report` | One self-contained HTML file: per run, claimed-done vs. independently-verified. |
+| `fleetproof telemetry` | v0.3: per-dispatch outcome records, a local reliability summary, and a strict-allowlist export. |
 
 Runtime dependencies: none (Python standard library only). A tool whose job is
 being trustworthy should add as little dependency and supply-chain surface as it can.
@@ -160,10 +161,12 @@ SubagentStop is the gate. Each step is its own reason to refuse the stop:
 2. Pin drift. Every dispatch pins the SHA-256 of the check spec that was in force
    when the work was ordered. If the spec changed mid-flight, the stop is blocked
    rather than graded against a spec the agent could have edited itself.
-3. That agent's tier of the spec. A blocking failure records `contradicted` and
-   blocks; a pass records `verified` and closes the dispatch. If the tier selects
-   no checks at all, no verdict is recorded — an absent grade must never read as a
-   passing one.
+3. That agent's tier of the spec, unioned with any checks declared on the
+   dispatch's own manifest (`{"id", "cmd"}` entries — blocking, expect-exit0).
+   A blocking failure records `contradicted` and blocks; a pass records
+   `verified` and closes the dispatch. If nothing is runnable — the tier selects
+   no repo checks and the manifest declares none — no verdict is recorded: an
+   absent grade must never read as a passing one.
 
 The Stop hook keeps its v0.1 job and adds a ledger sweep. A dispatch that reported
 and then never terminated blocks the bridge from stopping: something started
@@ -178,6 +181,10 @@ fleetproof dispatch new --prompt "..."        # --prompt-file for a real, long o
 fleetproof dispatch report <run-id> --report report.json
 fleetproof dispatch close <run-id>
 
+fleetproof dispatch intent --agent recon --prompt-file p.md \
+    [--manifest m.json] [--tier lane]         # declare the NEXT spawn of an agent
+                                              # type; the start capture consumes it
+
 fleetproof fleet                              # the board, newest first
 fleetproof fleet --open                       # only what has not terminated
 fleetproof fleet --format json                # full records, for an agent to read
@@ -193,12 +200,16 @@ transition trail, and which process wrote each transition.
 
 ### What the ledger does not do yet
 
-- The spawn prompt is in neither subagent hook payload. A captured dispatch records
-  a placeholder saying so, rather than inventing a prompt it never saw. To get the
-  real prompt on the record, dispatch through `fleetproof dispatch new`.
-- Captured subagents are recorded as `lane` tier. Real nesting depth is not visible
-  from the payload — there is no parent-agent field — so declaring one beats
-  inferring it wrongly. What that costs in practice is a pilot question.
+- The spawn prompt is in neither subagent hook payload, so an undeclared spawn
+  still records a placeholder saying so, rather than inventing a prompt it never
+  saw. To get the real prompt (and manifest, and tier) onto a captured dispatch,
+  write an intent sidecar first: `fleetproof dispatch intent --agent <type>
+  --prompt-file <file>` writes `.fleetproof/intents/<agent_type>.json`, and the
+  next SubagentStart of that agent type consumes it — one intent, one spawn.
+- Captured subagents without a declared intent tier are recorded as `lane` tier.
+  Real nesting depth is not visible from the payload — there is no parent-agent
+  field — so declaring one beats inferring it wrongly. What that costs in
+  practice is a pilot question.
 - An agent killed mid-turn can reach SubagentStop with an empty final message,
   which report-before-idle blocks. Blocking the stop of an agent that is already
   gone is not useful; how often it happens is under observation.
@@ -207,6 +218,71 @@ transition trail, and which process wrote each transition.
   is also why the lookup is scoped to non-terminal dispatches: an agent id can be
   reused once a dispatch is closed out.
 
+## Verification telemetry (v0.3)
+
+The ledger records what happened to each dispatch. v0.3 turns those records into
+reliability data an operator can actually read — and, when they choose to, share.
+
+Enable it per repo with `.fleetproof/config.json`:
+
+```json
+{ "telemetry_era": "2026-08-21" }
+```
+
+From that date, every dispatch gains a `telemetry.json`, written on the checker/hook
+side at verdict or close time — never by the agent being measured. Runs from before
+the date read back as pre-telemetry and are never back-filled or guessed.
+
+Each finished dispatch derives one of nine **outcome classes** from its transition
+history — bookkeeping, not judgment:
+
+- `verified` — the claim survived the checks.
+- `near_miss` — a gate-blocked retry whose work product *changed* before passing:
+  a real failure, caught before acceptance.
+- `verifier_flake` — the retry passed with the work product *unchanged*: the
+  contradiction was wrong, not the work. Counted separately so flaky checks can't
+  inflate the near-miss number.
+- `contradicted` — the claim did not survive.
+- `ungraded` — checks existed but no verdict ever landed. This is a control
+  failure and every summary says so; it is never folded into a benign class.
+- `unverifiable` — reported, but nothing in the claim was checkable. Never counts
+  as success.
+- `silent_idle` / `terminated_unreported` / `terminated_unclassified` — died
+  without reporting, split by the recorded terminate reason.
+
+The commands:
+
+```
+fleetproof telemetry summary                  # local-only reliability read
+fleetproof telemetry loss <run-id>            # one question per failure: hours or dollars
+fleetproof telemetry export --recipient X     # allowlist extract for sharing
+fleetproof telemetry anchor                   # record the current chain head
+```
+
+`summary` prints outcome and severity distributions with their numerators and
+denominators spelled out, override rates, and the corpus's own integrity rates
+(stop-only captures, missing telemetry files) — a dataset that can't measure its
+own holes isn't worth reading.
+
+`export` is built the opposite way from most exports: a strict per-field
+**allowlist** — closed enums, counts, bands, versions, and salted identifiers.
+Free text, prompts, paths, and every name you chose yourself never leave the
+machine; timestamps coarsen to dates. Each export carries a completeness manifest
+(runs per day per class, gaps visible) and a methodology note that says plainly
+what `verified` means here: conformance to *your own declared checks* at a
+measured coverage — not a judgment of work quality.
+
+The honest trust model, stated rather than implied: local records are
+operator-attested. The checker writes verdicts from a separate process, and v0.3
+chains a rolling hash over the records as they're written (`anchor` gives you a
+head you can sign or store elsewhere) — but a local ledger on a shared filesystem
+is not tamper-proof against everything that can write to it, and FleetProof will
+not pretend otherwise. The dispatch-intent sidecar (0.3.1) sits in the same
+trust class as `checks.json` itself: operator-attested, exactly as forgeable as
+the rest of `.fleetproof/`, no worse — anything that can write the repo can
+write an intent, and the manifest checks it carries run as shell commands at
+the stop gate the same way repo checks do.
+
 ## Install (each line is one command in Claude Code)
 
 ```

{fleetproof-0.2.1 → fleetproof-0.3.1}/README.md

@@ -53,6 +53,7 @@ No language model sits in the grading path. Grading is comparison.
 | SubagentStop hook | The per-subagent gate: records what the agent claimed, grades it at that agent's tier, blocks a false "done". |
 | `fleetproof fleet` | The dispatch board: every dispatch, its state, its tier, and whether anything graded it. |
 | `fleetproof report` | One self-contained HTML file: per run, claimed-done vs. independently-verified. |
+| `fleetproof telemetry` | v0.3: per-dispatch outcome records, a local reliability summary, and a strict-allowlist export. |
 
 Runtime dependencies: none (Python standard library only). A tool whose job is
 being trustworthy should add as little dependency and supply-chain surface as it can.
@@ -139,10 +140,12 @@ SubagentStop is the gate. Each step is its own reason to refuse the stop:
 2. Pin drift. Every dispatch pins the SHA-256 of the check spec that was in force
    when the work was ordered. If the spec changed mid-flight, the stop is blocked
    rather than graded against a spec the agent could have edited itself.
-3. That agent's tier of the spec. A blocking failure records `contradicted` and
-   blocks; a pass records `verified` and closes the dispatch. If the tier selects
-   no checks at all, no verdict is recorded — an absent grade must never read as a
-   passing one.
+3. That agent's tier of the spec, unioned with any checks declared on the
+   dispatch's own manifest (`{"id", "cmd"}` entries — blocking, expect-exit0).
+   A blocking failure records `contradicted` and blocks; a pass records
+   `verified` and closes the dispatch. If nothing is runnable — the tier selects
+   no repo checks and the manifest declares none — no verdict is recorded: an
+   absent grade must never read as a passing one.
 
 The Stop hook keeps its v0.1 job and adds a ledger sweep. A dispatch that reported
 and then never terminated blocks the bridge from stopping: something started
@@ -157,6 +160,10 @@ fleetproof dispatch new --prompt "..."        # --prompt-file for a real, long o
 fleetproof dispatch report <run-id> --report report.json
 fleetproof dispatch close <run-id>
 
+fleetproof dispatch intent --agent recon --prompt-file p.md \
+    [--manifest m.json] [--tier lane]         # declare the NEXT spawn of an agent
+                                              # type; the start capture consumes it
+
 fleetproof fleet                              # the board, newest first
 fleetproof fleet --open                       # only what has not terminated
 fleetproof fleet --format json                # full records, for an agent to read
@@ -172,12 +179,16 @@ transition trail, and which process wrote each transition.
 
 ### What the ledger does not do yet
 
-- The spawn prompt is in neither subagent hook payload. A captured dispatch records
-  a placeholder saying so, rather than inventing a prompt it never saw. To get the
-  real prompt on the record, dispatch through `fleetproof dispatch new`.
-- Captured subagents are recorded as `lane` tier. Real nesting depth is not visible
-  from the payload — there is no parent-agent field — so declaring one beats
-  inferring it wrongly. What that costs in practice is a pilot question.
+- The spawn prompt is in neither subagent hook payload, so an undeclared spawn
+  still records a placeholder saying so, rather than inventing a prompt it never
+  saw. To get the real prompt (and manifest, and tier) onto a captured dispatch,
+  write an intent sidecar first: `fleetproof dispatch intent --agent <type>
+  --prompt-file <file>` writes `.fleetproof/intents/<agent_type>.json`, and the
+  next SubagentStart of that agent type consumes it — one intent, one spawn.
+- Captured subagents without a declared intent tier are recorded as `lane` tier.
+  Real nesting depth is not visible from the payload — there is no parent-agent
+  field — so declaring one beats inferring it wrongly. What that costs in
+  practice is a pilot question.
 - An agent killed mid-turn can reach SubagentStop with an empty final message,
   which report-before-idle blocks. Blocking the stop of an agent that is already
   gone is not useful; how often it happens is under observation.
@@ -186,6 +197,71 @@ transition trail, and which process wrote each transition.
   is also why the lookup is scoped to non-terminal dispatches: an agent id can be
   reused once a dispatch is closed out.
 
+## Verification telemetry (v0.3)
+
+The ledger records what happened to each dispatch. v0.3 turns those records into
+reliability data an operator can actually read — and, when they choose to, share.
+
+Enable it per repo with `.fleetproof/config.json`:
+
+```json
+{ "telemetry_era": "2026-08-21" }
+```
+
+From that date, every dispatch gains a `telemetry.json`, written on the checker/hook
+side at verdict or close time — never by the agent being measured. Runs from before
+the date read back as pre-telemetry and are never back-filled or guessed.
+
+Each finished dispatch derives one of nine **outcome classes** from its transition
+history — bookkeeping, not judgment:
+
+- `verified` — the claim survived the checks.
+- `near_miss` — a gate-blocked retry whose work product *changed* before passing:
+  a real failure, caught before acceptance.
+- `verifier_flake` — the retry passed with the work product *unchanged*: the
+  contradiction was wrong, not the work. Counted separately so flaky checks can't
+  inflate the near-miss number.
+- `contradicted` — the claim did not survive.
+- `ungraded` — checks existed but no verdict ever landed. This is a control
+  failure and every summary says so; it is never folded into a benign class.
+- `unverifiable` — reported, but nothing in the claim was checkable. Never counts
+  as success.
+- `silent_idle` / `terminated_unreported` / `terminated_unclassified` — died
+  without reporting, split by the recorded terminate reason.
+
+The commands:
+
+```
+fleetproof telemetry summary                  # local-only reliability read
+fleetproof telemetry loss <run-id>            # one question per failure: hours or dollars
+fleetproof telemetry export --recipient X     # allowlist extract for sharing
+fleetproof telemetry anchor                   # record the current chain head
+```
+
+`summary` prints outcome and severity distributions with their numerators and
+denominators spelled out, override rates, and the corpus's own integrity rates
+(stop-only captures, missing telemetry files) — a dataset that can't measure its
+own holes isn't worth reading.
+
+`export` is built the opposite way from most exports: a strict per-field
+**allowlist** — closed enums, counts, bands, versions, and salted identifiers.
+Free text, prompts, paths, and every name you chose yourself never leave the
+machine; timestamps coarsen to dates. Each export carries a completeness manifest
+(runs per day per class, gaps visible) and a methodology note that says plainly
+what `verified` means here: conformance to *your own declared checks* at a
+measured coverage — not a judgment of work quality.
+
+The honest trust model, stated rather than implied: local records are
+operator-attested. The checker writes verdicts from a separate process, and v0.3
+chains a rolling hash over the records as they're written (`anchor` gives you a
+head you can sign or store elsewhere) — but a local ledger on a shared filesystem
+is not tamper-proof against everything that can write to it, and FleetProof will
+not pretend otherwise. The dispatch-intent sidecar (0.3.1) sits in the same
+trust class as `checks.json` itself: operator-attested, exactly as forgeable as
+the rest of `.fleetproof/`, no worse — anything that can write the repo can
+write an intent, and the manifest checks it carries run as shell commands at
+the stop gate the same way repo checks do.
+
 ## Install (each line is one command in Claude Code)
 
 ```

{fleetproof-0.2.1 → fleetproof-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fleetproof"
-version = "0.2.1"
+version = "0.3.1"
 description = "Independent, out-of-band verification for agent fleets."
 readme = "README.md"
 requires-python = ">=3.10"

{fleetproof-0.2.1 → fleetproof-0.3.1}/src/fleetproof/__init__.py

@@ -5,7 +5,7 @@ The agent may author the checks; it never executes and grades its own work.
 
 from __future__ import annotations
 
-__version__ = "0.2.1"
+__version__ = "0.3.1"
 
 from .runlog import (
     RunRecord,

{fleetproof-0.2.1 → fleetproof-0.3.1}/src/fleetproof/cli.py

@@ -13,8 +13,11 @@ surface as it can. Subcommands:
     record    PostToolUse-hook entry: append an evidence record from hook stdin
     subagent-start SubagentStart-hook entry: put a spawning subagent on the ledger
     subagent-stop  SubagentStop-hook entry: the per-subagent report-and-verify gate
-    dispatch  ledger verbs: new / report / close a dispatch
+    dispatch  ledger verbs: new / report / close a dispatch; intent writes the
+              sidecar the SubagentStart capture consumes
     fleet     the dispatch board — every dispatch, its state, and whether it reported
+    telemetry summary (local-only aggregates) / export (allowlisted bundle) /
+              anchor (chain head) / loss (the one raw-loss question per failure)
 
 Output is plain ASCII on purpose: these commands get read in cp1252 consoles on
 Windows, where a stray unicode glyph is a UnicodeEncodeError, not a nicer table.
@@ -27,7 +30,7 @@ import json
 import os
 import shutil
 import sys
-from datetime import datetime, timedelta, timezone
+from datetime import date, datetime, timedelta, timezone
 from pathlib import Path
 
 # The CLI must not record its own invocations.
@@ -51,12 +54,15 @@ from .hookgate import (
     subagent_stop_main,
 )
 from .ledger import (
+    REASON_OPERATOR_CLOSE,
+    VALID_TERMINATE_REASONS,
     LedgerError,
     close_dispatch,
     create_dispatch,
     list_dispatches,
     load_dispatch,
     record_report,
+    write_intent,
 )
 # The board and the HTML report describe a dispatch with the same words, defined
 # once in report.py. Two surfaces disagreeing about what a state is called is how
@@ -76,6 +82,7 @@ from .runlog import (
     project_root,
     runs_dir,
 )
+from .telemetry import TelemetryError, build_telemetry, record_failure_loss
 
 
 def _cmd_init(args: argparse.Namespace) -> int:
@@ -328,6 +335,49 @@ def _cmd_dispatch_new(args: argparse.Namespace) -> int:
     return 0
 
 
+def _cmd_dispatch_intent(args: argparse.Namespace) -> int:
+    """Write the dispatch-intent sidecar the next SubagentStart capture consumes.
+
+    Exists so dispatchers never hand-write the JSON: the prompt comes from a
+    file (same rationale as ``dispatch new --prompt-file`` — shell-quoting a
+    real prompt on Windows is how prompts get mangled), the manifest is
+    validated here where an error still has someone to land on, and the printed
+    path is the audit surface: the file that will vanish when the spawn
+    consumes it.
+    """
+    try:
+        prompt = Path(args.prompt_file).read_text(encoding="utf-8")
+    except OSError as e:
+        _emit_error("bad_prompt",
+                    f"Could not read prompt file {args.prompt_file}: {e}", args.format)
+        return 2
+
+    manifest = None
+    if args.manifest:
+        try:
+            manifest = _load_json_file(args.manifest, "manifest")
+        except ValueError as e:
+            _emit_error("bad_manifest", str(e), args.format)
+            return 2
+        # Same tolerance as dispatch new: a bare manifest object or a wrapper
+        # with a "manifest" key both work.
+        inner = manifest.get("manifest")
+        if isinstance(inner, dict):
+            manifest = inner
+
+    try:
+        path = write_intent(args.agent, prompt, manifest=manifest, tier=args.tier)
+    except LedgerError as e:
+        _emit_error("ledger_error", str(e), args.format)
+        return 1
+    if args.format == "json":
+        print(json.dumps({"ok": True, "agent_type": args.agent,
+                          "intent_path": str(path)}))
+    else:
+        print(str(path))
+    return 0
+
+
 def _cmd_dispatch_report(args: argparse.Namespace) -> int:
     try:
         payload = _load_json_file(args.report, "report")
@@ -348,10 +398,19 @@ def _cmd_dispatch_report(args: argparse.Namespace) -> int:
 
 def _cmd_dispatch_close(args: argparse.Namespace) -> int:
     try:
-        record = close_dispatch(args.run_id)
+        record = close_dispatch(args.run_id, reason=args.reason)
     except LedgerError as e:
         _emit_error("ledger_error", str(e), args.format)
         return 1
+    # The close finalizes the lifecycle, so the telemetry record derives here.
+    # Best-effort: a telemetry failure must not turn a successful close into a
+    # failed command — the summary surfaces the missing record as an integrity
+    # defect instead.
+    try:
+        build_telemetry(record.run_id)
+    except Exception as e:
+        print(f"[fleetproof] telemetry build failed for {record.run_id}: {e}",
+              file=sys.stderr)
     if args.format == "json":
         print(json.dumps(record.to_dict(), indent=2))
     else:
@@ -416,6 +475,105 @@ def _cmd_fleet(args: argparse.Namespace) -> int:
     return 0
 
 
+def _parse_date(value: str | None, label: str) -> "date | None":
+    if value is None:
+        return None
+    try:
+        return date.fromisoformat(value)
+    except ValueError as e:
+        raise ValueError(f"--{label} must be YYYY-MM-DD: {e}") from e
+
+
+def _cmd_telemetry_summary(args: argparse.Namespace) -> int:
+    from .telemetry_export import summarize
+    summary = summarize()
+    if args.format == "json":
+        print(json.dumps(summary, indent=2))
+        return 0
+    print("Telemetry summary (LOCAL-ONLY: clear-text names and exact times;")
+    print("anything shareable goes through `fleetproof telemetry export`).")
+    for name, block in summary["windows"].items():
+        counts = block["counts"]
+        shown = {k: v for k, v in counts.items() if v}
+        print(f"\n[{name}] {block['total_dispatches']} dispatch(es), "
+              f"{block['classifiable_dispatches']} classifiable")
+        print(f"  outcomes: {shown if shown else 'none'}")
+        for metric in ("delivery_failure_rate", "false_claim_rate",
+                       "near_miss_rate", "verifier_flake_rate",
+                       "ungraded_rate", "unverifiable_rate",
+                       "telemetry_missing_rate", "stop_only_fraction"):
+            m = block[metric]
+            rate = f"{m['rate']:.3f}" if m["rate"] is not None else "n/a"
+            print(f"  {metric}: {m['numerator']}/{m['denominator']} = {rate}")
+        sev = block["severity_distribution"]
+        print(f"  severity: {({k: v for k, v in sev.items() if v}) or 'no failures'}")
+        override = block["override_rate_by_source"]
+        for source in ("hook", "operator"):
+            m = override[source]
+            rate = f"{m['rate']:.3f}" if m["rate"] is not None else "n/a"
+            print(f"  override_rate[{source}]: {m['numerator']}/{m['denominator']} = {rate}")
+    timeline = summary["spec_hash_timeline"]
+    if timeline:
+        print("\nspec-hash timeline:")
+        for entry in timeline:
+            print(f"  {entry['first_seen']}  {short_spec_hash(entry['spec_sha256'])}")
+    return 0
+
+
+def _cmd_telemetry_export(args: argparse.Namespace) -> int:
+    from .telemetry_export import export_telemetry
+    try:
+        since = _parse_date(args.since, "since")
+        until = _parse_date(args.until, "until")
+    except ValueError as e:
+        _emit_error("bad_date", str(e), args.format)
+        return 2
+    try:
+        out = export_telemetry(
+            args.recipient,
+            out_dir=Path(args.output) if args.output else None,
+            since=since, until=until)
+    except TelemetryError as e:
+        _emit_error("telemetry_error", str(e), args.format)
+        return 1
+    if args.format == "json":
+        print(json.dumps({"ok": True, "export_dir": str(out)}))
+    else:
+        print(f"Wrote export bundle to {out}")
+        print("Label: identified, minimized (single-party exports are "
+              "identified by construction).")
+    return 0
+
+
+def _cmd_telemetry_anchor(args: argparse.Namespace) -> int:
+    from .telemetry_export import anchor_chain
+    anchor = anchor_chain()
+    if args.format == "json":
+        print(json.dumps(anchor, indent=2))
+    else:
+        print(f"chain head: {anchor['chain_head']}")
+        print(f"entries:    {anchor['chain_entries']}")
+        print(anchor["note"])
+    return 0
+
+
+def _cmd_telemetry_loss(args: argparse.Namespace) -> int:
+    try:
+        telemetry = record_failure_loss(
+            args.run_id, args.value, args.unit,
+            default_accepted=args.default_accepted or None)
+    except TelemetryError as e:
+        _emit_error("telemetry_error", str(e), args.format)
+        return 1
+    if args.format == "json":
+        print(json.dumps(telemetry, indent=2))
+    else:
+        print(f"{args.run_id}: severity {telemetry['failure.severity_band']} "
+              f"(floor {telemetry['failure.severity_floor']}), "
+              f"loss {telemetry['failure.estimated_loss']}")
+    return 0
+
+
 def _emit_error(code: str, message: str, fmt: str) -> None:
     if fmt == "json":
         print(json.dumps({"ok": False, "error_code": code, "message": message}), file=sys.stderr)
@@ -500,6 +658,22 @@ def build_parser() -> argparse.ArgumentParser:
     _add_format(p_dnew)
     p_dnew.set_defaults(func=_cmd_dispatch_new)
 
+    p_dint = dsub.add_parser(
+        "intent",
+        help="Write the dispatch-intent sidecar for the next spawn of one agent type.")
+    p_dint.add_argument("--agent", required=True,
+                        help="The agent_type the harness will report for the spawn.")
+    p_dint.add_argument("--prompt-file", required=True,
+                        help="File holding the dispatch prompt, verbatim.")
+    p_dint.add_argument("--manifest", default=None,
+                        help="JSON file with the dispatch manifest "
+                             "(bare object or a {'manifest': ...} wrapper).")
+    p_dint.add_argument("--tier", choices=sorted(VALID_TIERS), default=None,
+                        help="Declare the tier. Omit to record the captured-subagent "
+                             "default (lane).")
+    _add_format(p_dint)
+    p_dint.set_defaults(func=_cmd_dispatch_intent)
+
     p_drep = dsub.add_parser("report", help="Record what a dispatched agent claimed.")
     p_drep.add_argument("run_id")
     p_drep.add_argument("--report", required=True, help="JSON file holding the report.")
@@ -508,9 +682,54 @@ def build_parser() -> argparse.ArgumentParser:
 
     p_dclose = dsub.add_parser("close", help="Terminate a dispatch.")
     p_dclose.add_argument("run_id")
+    # Defaulted, not required: the CLI is the operator's close path, so the
+    # honest machine-set reason for it is operator-close. Scripted sweepers and
+    # session-teardown callers override it to say what they actually are.
+    p_dclose.add_argument(
+        "--reason", choices=sorted(VALID_TERMINATE_REASONS),
+        default=REASON_OPERATOR_CLOSE,
+        help="Why this dispatch is being terminated (default: operator-close).")
     _add_format(p_dclose)
     p_dclose.set_defaults(func=_cmd_dispatch_close)
 
+    p_tel = sub.add_parser("telemetry", help="Verification-telemetry surfaces.")
+    tsub = p_tel.add_subparsers(dest="telemetry_command", required=True)
+
+    p_tsum = tsub.add_parser(
+        "summary",
+        help="Local-only outcome/severity/integrity summary with trailing windows.")
+    _add_format(p_tsum)
+    p_tsum.set_defaults(func=_cmd_telemetry_summary)
+
+    p_texp = tsub.add_parser(
+        "export",
+        help="Write the allowlisted, date-bucketed export bundle for one recipient.")
+    p_texp.add_argument("--recipient", required=True,
+                        help="Counterparty label; selects (or mints) the export salt.")
+    p_texp.add_argument("-o", "--output", default=None, help="Output directory.")
+    p_texp.add_argument("--since", default=None, help="Window start, YYYY-MM-DD.")
+    p_texp.add_argument("--until", default=None, help="Window end, YYYY-MM-DD.")
+    _add_format(p_texp)
+    p_texp.set_defaults(func=_cmd_telemetry_export)
+
+    p_tanc = tsub.add_parser(
+        "anchor",
+        help="Record the telemetry chain head as an anchorable value.")
+    _add_format(p_tanc)
+    p_tanc.set_defaults(func=_cmd_telemetry_anchor)
+
+    p_tloss = tsub.add_parser(
+        "loss",
+        help="Record the one raw loss quantity for a failed run (hours or usd).")
+    p_tloss.add_argument("run_id")
+    p_tloss.add_argument("--value", type=float, required=True,
+                         help="The raw quantity; the band is derived, never chosen.")
+    p_tloss.add_argument("--unit", choices=["hours", "usd"], required=True)
+    p_tloss.add_argument("--default-accepted", action="store_true",
+                         help="The suggested default was accepted unchanged.")
+    _add_format(p_tloss)
+    p_tloss.set_defaults(func=_cmd_telemetry_loss)
+
     p_fleet = sub.add_parser("fleet", help="The dispatch board, newest first.")
     p_fleet.add_argument("--open", action="store_true",
                          help="Only dispatches that have not terminated.")