fleetproof 0.3.0__tar.gz → 0.3.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fleetproof
-Version: 0.3.0
+Version: 0.3.1
 Summary: Independent, out-of-band verification for agent fleets.
 Author: Gathrazio
 License: MIT
@@ -161,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
@@ -179,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
@@ -194,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.
@@ -267,7 +277,11 @@ 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.
+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.3.0 → fleetproof-0.3.1}/README.md

@@ -140,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
@@ -158,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
@@ -173,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.
@@ -246,7 +256,11 @@ 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.
+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.3.0 → fleetproof-0.3.1}/pyproject.toml

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

{fleetproof-0.3.0 → 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.3.0 → fleetproof-0.3.1}/src/fleetproof/cli.py

@@ -13,7 +13,8 @@ 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)
@@ -61,6 +62,7 @@ from .ledger import (
     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
@@ -333,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")
@@ -613,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.")

{fleetproof-0.3.0 → fleetproof-0.3.1}/src/fleetproof/hookgate.py

@@ -26,8 +26,10 @@ everything here is designed to fail open around the gaps):
 - SubagentStart carries ``{session_id, transcript_path, cwd, hook_event_name,
   agent_id, agent_type}`` and cannot block.
 - SubagentStop adds ``last_assistant_message`` and can block, same contract as Stop.
-- The spawn *prompt* is in neither payload. So a captured dispatch records a
-  placeholder prompt and says so, rather than inventing the prompt it did not see.
+- The spawn *prompt* is in neither payload. A captured dispatch records a
+  placeholder prompt and says so, rather than inventing the prompt it did not
+  see — unless the dispatcher declared it up front via an intent sidecar
+  (``.fleetproof/intents/<agent_type>.json``), which the start capture consumes.
 - There is no correlation field between the Task-tool call that spawned an agent
   and that agent's stop, so ``agent_id`` + ``session_id`` is the only join key.
 """
@@ -50,6 +52,7 @@ from .checker import (
 )
 from .checks import (
     SPEC_DRIFT_NOTE,
+    Check,
     CheckSpecError,
     load_checks,
     short_spec_hash,
@@ -64,6 +67,7 @@ from .ledger import (
     TIER_BRIDGE,
     LedgerError,
     close_dispatch,
+    consume_intent,
     create_dispatch,
     find_dispatch_by_agent,
     list_dispatches,
@@ -367,7 +371,8 @@ def _suppress_on_retry(payload: dict[str, Any], decision: dict[str, Any]) -> boo
 
 # The harness does not put the spawn prompt in either subagent payload, so a
 # captured dispatch says exactly that instead of pretending to quote a prompt it
-# never saw. Phase C's pilot measures how much this costs us.
+# never saw. The intent sidecar is the dispatcher's way around the gap; this
+# placeholder is what every dispatch without one records.
 UNCAPTURED_PROMPT = "[uncaptured] subagent {agent_type} spawn — prompt not in harness payload"
 
 # Policy v0.2: any subagent captured inside a session is lane tier. Real nesting
@@ -392,11 +397,30 @@ def _placeholder_prompt(agent_type: str | None) -> str:
 
 
 def capture_subagent_start(payload: dict[str, Any]) -> str:
-    """Put a spawning subagent on the ledger before it does any work."""
+    """Put a spawning subagent on the ledger before it does any work.
+
+    When the dispatcher left an intent sidecar for this agent type
+    (``.fleetproof/intents/<agent_type>.json``, written via ``fleetproof
+    dispatch intent``), the dispatch is created with the intent's real prompt,
+    manifest, and tier — the harness still does not carry the spawn prompt, so
+    the sidecar is the only route it has onto the record. The intent is
+    consumed on match: one intent, one spawn, and a second spawn of the same
+    agent type gets exactly the placeholder capture a repo without sidecars
+    always got. Degradations (malformed intent, malformed manifest, bad tier)
+    are surfaced on stderr and in the manifest notes, never fatal — this runs
+    inside a hook that must not break the spawn.
+    """
     agent_id, agent_type = _agent_fields(payload)
+    intent, notes = consume_intent(agent_type)
+    for note in notes:
+        sys.stderr.write(f"[fleetproof] {note}\n")
+    prompt = intent["prompt"] if intent else _placeholder_prompt(agent_type)
+    manifest = intent["manifest"] if intent else None
+    tier = (intent["tier"] if intent else None) or CAPTURED_SUBAGENT_TIER
     return create_dispatch(
-        _placeholder_prompt(agent_type),
-        tier=CAPTURED_SUBAGENT_TIER,
+        prompt,
+        tier=tier,
+        manifest=manifest,
         agent={"agent_id": agent_id, "agent_type": agent_type, "capture": CAPTURE_START},
         by="hook",
     )
@@ -468,6 +492,49 @@ def _try_build_telemetry(run_id: str, check_report=None, checks=None) -> None:
         sys.stderr.write(f"[fleetproof] telemetry build failed for {run_id}: {e}\n")
 
 
+def _manifest_checks(dispatch) -> list[Check]:
+    """Runnable blocking checks declared on the dispatch's own manifest.
+
+    A manifest check is an ``{"id", "cmd"}`` entry: always blocking, always
+    expect-exit0. The richer expectation kinds stay a ``checks.json`` feature —
+    the manifest is a per-dispatch contract, and its checks exist so a
+    manifest-bearing dispatch can grade without pre-registering into the
+    spec-hash-pinned repo file.
+
+    An entry that is not that shape is skipped with a stderr note rather than
+    run half-parsed. A skipped check is never a passing check: its id never
+    reaches the executed set, so the deliverable it vouched for reads as
+    uncovered — the error lands on the self-critical side of the metric.
+    """
+    entries = (dispatch.manifest or {}).get("checks")
+    if not isinstance(entries, list):
+        return []
+    out: list[Check] = []
+    seen: set[str] = set()
+    for i, entry in enumerate(entries):
+        where = f"manifest check [{i}] on dispatch {dispatch.run_id}"
+        if not isinstance(entry, dict):
+            sys.stderr.write(f"[fleetproof] {where} is not an object; skipped\n")
+            continue
+        cid, cmd = entry.get("id"), entry.get("cmd")
+        if not isinstance(cid, str) or not cid or not isinstance(cmd, str) or not cmd.strip():
+            sys.stderr.write(
+                f"[fleetproof] {where} needs a string 'id' and 'cmd'; skipped\n")
+            continue
+        if "\n" in cmd or "\r" in cmd:
+            # Same rule the spec loader enforces (finding H5): cmd.exe executes
+            # only the first line, and a check that half-runs is worse than one
+            # that never runs.
+            sys.stderr.write(f"[fleetproof] {where}: 'cmd' must be a single line; skipped\n")
+            continue
+        if cid in seen:
+            continue
+        seen.add(cid)
+        out.append(Check(id=cid, run=cmd, expect={"kind": "exit0"}, block=True,
+                         description="dispatch-manifest check"))
+    return out
+
+
 def subagent_stop(payload: dict[str, Any]) -> tuple[dict[str, Any] | None, int]:
     """The per-subagent gate. Returns ``(decision_or_None, exit_code)``.
 
@@ -481,13 +548,17 @@ def subagent_stop(payload: dict[str, Any]) -> tuple[dict[str, Any] | None, int]:
     3. If the spec changed since this dispatch was pinned, block. At lane tier and
        deeper the pinned spec is the contract; grading against a spec the agent
        could have edited mid-flight is not verification.
-    4. Grade the agent's own tier of the spec. Blocking failure -> ``contradicted``
-       and block (the agent gets its turn back, and the retry re-reports onto this
-       same dispatch). Otherwise -> ``verified`` and terminate.
-
-    When the agent's tier selects no checks, no verdict is recorded at all: the
-    dispatch is terminated still-ungraded, because an absent grade must never read
-    as a passing grade.
+    4. Grade the agent's own tier of the spec, unioned with the checks declared
+       on this dispatch's own manifest (blocking, expect-exit0). Blocking
+       failure -> ``contradicted`` and block (the agent gets its turn back, and
+       the retry re-reports onto this same dispatch). Otherwise -> ``verified``
+       and terminate.
+
+    When nothing is runnable — the tier selects no repo checks *and* the
+    manifest declares none — no verdict is recorded at all: the dispatch is
+    terminated still-ungraded, because an absent grade must never read as a
+    passing grade. A manifest-bearing dispatch can therefore always grade,
+    which is the L21 fix: its checks no longer need to live in ``checks.json``.
     """
     session_id = os.environ.get(SESSION_ID_ENV)
     agent_id, agent_type = _agent_fields(payload)
@@ -552,7 +623,14 @@ def subagent_stop(payload: dict[str, Any]) -> tuple[dict[str, Any] | None, int]:
         # not manufacture a verdict out of the absence of checks.
         checks = []
     selected = select_checks(checks, dispatch.tier) if checks else []
-    if not selected:
+    # Union with the dispatch's own manifest checks, repo spec first. A manifest
+    # check whose id collides with a selected repo check is dropped: the repo
+    # spec is the more attested source, and two commands under one id would make
+    # the executed-id set (which coverage joins on) ambiguous.
+    selected_ids = {c.id for c in selected}
+    runnable = selected + [c for c in _manifest_checks(dispatch)
+                           if c.id not in selected_ids]
+    if not runnable:
         _try_close(dispatch.run_id)
         # The grading *happened* and selected nothing — recorded as an empty
         # CheckReport so the telemetry layer can tell "checked nothing on
@@ -564,7 +642,7 @@ def subagent_stop(payload: dict[str, Any]) -> tuple[dict[str, Any] | None, int]:
         )
         return None, 0
 
-    report = run_checks(selected, record_to_log=True, tier=dispatch.tier)
+    report = run_checks(runnable, record_to_log=True, tier=dispatch.tier)
     if report.blocking_failures:
         record_verdict(
             dispatch.run_id,
@@ -572,7 +650,7 @@ def subagent_stop(payload: dict[str, Any]) -> tuple[dict[str, Any] | None, int]:
             detail="; ".join(r.id for r in report.blocking_failures),
             by=VERDICT_BY,
         )
-        _try_build_telemetry(dispatch.run_id, check_report=report, checks=selected)
+        _try_build_telemetry(dispatch.run_id, check_report=report, checks=runnable)
         return _subagent_block(_failure_reason(report), _evidence_context(report)), 0
 
     record_verdict(
@@ -584,7 +662,7 @@ def subagent_stop(payload: dict[str, Any]) -> tuple[dict[str, Any] | None, int]:
     _try_close(dispatch.run_id)
     # Built after the close, so the outcome class derives from a finished
     # lifecycle rather than a snapshot mid-transition.
-    _try_build_telemetry(dispatch.run_id, check_report=report, checks=selected)
+    _try_build_telemetry(dispatch.run_id, check_report=report, checks=runnable)
     return None, 0
 
 

{fleetproof-0.3.0 → fleetproof-0.3.1}/src/fleetproof/ledger.py

@@ -52,6 +52,8 @@ Public API:
     list_dispatches(*, session_id, open_only, non_terminal_only) -> list[DispatchRecord]
     find_dispatch_by_agent(session_id, agent_id) -> DispatchRecord | None
     derive_manifest(prompt) -> dict
+    write_intent(agent_type, prompt, *, manifest, tier) -> Path
+    consume_intent(agent_type) -> (fields_or_None, notes)
 """
 
 from __future__ import annotations
@@ -163,6 +165,23 @@ EMPTY_MANIFEST_KEYS = ("deliverables", "allowed_paths", "checks")
 DERIVED_V1_NO_MANIFEST = "derived-v1: no structured manifest in prompt"
 DERIVED_V1_MALFORMED = "derived-v1: embedded manifest was malformed and ignored"
 
+# Where dispatch-intent sidecars live, next to the runs directory. An intent is
+# the dispatcher's declaration of what it is about to spawn — the harness does
+# not put the spawn prompt in the SubagentStart payload, so the sidecar is the
+# only way a real prompt (and manifest, and tier) reaches the captured dispatch.
+INTENTS_DIRNAME = "intents"
+
+INTENT_MANIFEST_MALFORMED = (
+    "intent-sidecar: declared manifest was malformed and ignored; "
+    "derived from the intent prompt instead"
+)
+
+# What may name an intent file. The agent_type on the consume side comes out of
+# the harness payload; building a path from a payload-controlled string is how
+# a hook gets walked out of its own directory, so anything that is not a plain
+# name gets no sidecar lookup at all.
+_INTENT_NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
+
 
 class LedgerError(Exception):
     """Raised on an illegal state transition or an unusable dispatch/report."""
@@ -544,6 +563,128 @@ def derive_manifest(prompt: str) -> dict[str, Any]:
     return empty_manifest(DERIVED_V1_MALFORMED if saw_malformed else DERIVED_V1_NO_MANIFEST)
 
 
+# === Dispatch-intent sidecar ===
+
+def intents_dir() -> Path:
+    """The ``.fleetproof/intents/`` directory, resolved beside the runs dir."""
+    return runs_dir().parent / INTENTS_DIRNAME
+
+
+def intent_path(agent_type: str | None) -> Path | None:
+    """The sidecar path for ``agent_type``, or None when it cannot name a file."""
+    if not agent_type or not _INTENT_NAME_RE.match(agent_type):
+        return None
+    return intents_dir() / f"{agent_type}.json"
+
+
+def write_intent(
+    agent_type: str,
+    prompt: str,
+    *,
+    manifest: dict[str, Any] | None = None,
+    tier: str | None = None,
+) -> Path:
+    """Write the dispatch-intent sidecar for the next spawn of ``agent_type``.
+
+    The dispatcher calls this (via ``fleetproof dispatch intent``) *before*
+    spawning, so the SubagentStart capture finds the real prompt waiting instead
+    of recording a placeholder. Overwrites an existing intent for the same agent
+    type — the newest declaration wins, matching how a re-issued dispatch prompt
+    supersedes the one it replaces. Validation is strict here, on the write
+    side, where an error still has someone to land on; the consume side (a hook
+    that must not crash a spawn) degrades instead.
+    """
+    path = intent_path(agent_type)
+    if path is None:
+        raise LedgerError(
+            f"Agent type {agent_type!r} cannot name an intent file; use a plain "
+            "name (letters, digits, dot, dash, underscore)."
+        )
+    if not isinstance(prompt, str) or not prompt.strip():
+        raise LedgerError("An intent needs a prompt; refusing to record an empty one.")
+    intent: dict[str, Any] = {
+        "agent_type": agent_type,
+        "prompt": prompt,
+        "created_at": _now_iso(),
+    }
+    if manifest is not None:
+        try:
+            intent["manifest"] = _coerce_manifest(manifest)
+        except ValueError as e:
+            raise LedgerError(f"Unusable manifest: {e}") from e
+    if tier is not None:
+        intent["tier"] = _validate_tier(tier)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    _write_json(path, intent)
+    return path
+
+
+def consume_intent(agent_type: str | None) -> tuple[dict[str, Any] | None, list[str]]:
+    """Read, validate, and DELETE the intent sidecar for one spawning agent.
+
+    Returns ``(fields, notes)``. ``fields`` is ``{"prompt", "manifest", "tier"}``
+    — manifest coerced (or None), tier validated (or None) — or None when no
+    usable intent exists. ``notes`` are human-readable degradation notes for the
+    caller to surface; an intent that half-worked must be visible, not silent.
+
+    Consumption is unconditional once a matching file is found: one intent, one
+    spawn, even when the intent turns out malformed. A malformed sidecar left in
+    place would attach itself to the *next* spawn of the same agent type, which
+    misattributes a prompt — worse than losing it, and the note says what was
+    lost. The one exception is a file that cannot be deleted: an undeletable
+    sidecar would replay onto every later spawn, so it is not trusted either.
+    """
+    notes: list[str] = []
+    path = intent_path(agent_type)
+    if path is None or not path.exists():
+        return None, notes
+    raw = _read_json(path)
+    try:
+        path.unlink()
+    except OSError as e:
+        notes.append(f"could not delete intent file {path}: {e}; ignoring it")
+        return None, notes
+    if raw is None:
+        notes.append(
+            f"intent file {path.name} was unreadable or not a JSON object; "
+            "capturing with the placeholder prompt instead"
+        )
+        return None, notes
+    prompt = raw.get("prompt")
+    if not isinstance(prompt, str) or not prompt.strip():
+        notes.append(
+            f"intent file {path.name} has no usable prompt; "
+            "capturing with the placeholder prompt instead"
+        )
+        return None, notes
+    fields: dict[str, Any] = {"prompt": prompt, "manifest": None, "tier": None}
+    raw_manifest = raw.get("manifest")
+    if raw_manifest is not None:
+        try:
+            fields["manifest"] = _coerce_manifest(raw_manifest)
+        except ValueError as e:
+            # Degrade to derive-from-prompt, with the failure written into the
+            # manifest notes so it survives on the dispatch record itself.
+            notes.append(
+                f"intent manifest for {agent_type!r} was malformed ({e}); "
+                "deriving from the intent prompt instead"
+            )
+            derived = derive_manifest(prompt)
+            base = derived.get("notes") or ""
+            derived["notes"] = (f"{base}; " if base else "") + INTENT_MANIFEST_MALFORMED
+            fields["manifest"] = derived
+    raw_tier = raw.get("tier")
+    if raw_tier is not None:
+        if isinstance(raw_tier, str) and raw_tier in VALID_TIERS:
+            fields["tier"] = raw_tier
+        else:
+            notes.append(
+                f"intent tier {raw_tier!r} is not one of {sorted(VALID_TIERS)}; "
+                "using the captured-subagent default"
+            )
+    return fields, notes
+
+
 # === Creating a dispatch ===
 
 def _now_iso() -> str:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fleetproof
-Version: 0.3.0
+Version: 0.3.1
 Summary: Independent, out-of-band verification for agent fleets.
 Author: Gathrazio
 License: MIT
@@ -161,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
@@ -179,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
@@ -194,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.
@@ -267,7 +277,11 @@ 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.
+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.3.0 → fleetproof-0.3.1}/tests/test_cli.py

@@ -131,6 +131,61 @@ def test_dispatch_new_bad_manifest_file(cli_runs, tmp_path, capsys):
                  str(tmp_path / "absent.json")]) == 2
 
 
+def test_dispatch_intent_writes_sidecar_and_prints_path(cli_runs, tmp_path, capsys):
+    pf = tmp_path / "prompt.md"
+    pf.write_text("do the real work\nwith a real prompt", encoding="utf-8")
+    mf = tmp_path / "manifest.json"
+    mf.write_text(json.dumps({"manifest": {
+        "deliverables": ["a"],
+        "checks": [{"id": "c1", "cmd": "true"}],
+        "check_map": {"a": ["c1"]},
+    }}), encoding="utf-8")
+
+    assert main(["dispatch", "intent", "--agent", "recon", "--prompt-file", str(pf),
+                 "--manifest", str(mf), "--tier", "lane"]) == 0
+    path = Path(capsys.readouterr().out.strip())
+    assert path.exists()
+    assert path.name == "recon.json"
+
+    intent = json.loads(path.read_text(encoding="utf-8"))
+    assert intent["agent_type"] == "recon"
+    assert intent["prompt"] == "do the real work\nwith a real prompt"
+    assert intent["manifest"]["check_map"] == {"a": ["c1"]}
+    assert intent["tier"] == "lane"
+    assert intent["created_at"]
+
+
+def test_dispatch_intent_json_format(cli_runs, tmp_path, capsys):
+    pf = tmp_path / "prompt.md"
+    pf.write_text("work", encoding="utf-8")
+    assert main(["dispatch", "intent", "--agent", "recon", "--prompt-file", str(pf),
+                 "--format", "json"]) == 0
+    out = json.loads(capsys.readouterr().out)
+    assert out["ok"] is True
+    assert Path(out["intent_path"]).exists()
+
+
+def test_dispatch_intent_rejects_bad_inputs(cli_runs, tmp_path, capsys):
+    pf = tmp_path / "prompt.md"
+    pf.write_text("work", encoding="utf-8")
+    # Missing prompt file: an intent with no prompt is the placeholder problem
+    # the sidecar exists to fix, so it fails at write time.
+    assert main(["dispatch", "intent", "--agent", "recon",
+                 "--prompt-file", str(tmp_path / "absent.md")]) == 2
+    # Unparseable manifest file vs. parseable-but-unusable manifest shape.
+    bad = tmp_path / "bad.json"
+    bad.write_text("{not json", encoding="utf-8")
+    assert main(["dispatch", "intent", "--agent", "recon", "--prompt-file", str(pf),
+                 "--manifest", str(bad)]) == 2
+    unusable = tmp_path / "unusable.json"
+    unusable.write_text(json.dumps({"deliverables": "not-an-array"}), encoding="utf-8")
+    assert main(["dispatch", "intent", "--agent", "recon", "--prompt-file", str(pf),
+                 "--manifest", str(unusable)]) == 1
+    # A path-shaped agent type must never become a path.
+    assert main(["dispatch", "intent", "--agent", "../evil",
+                 "--prompt-file", str(pf)]) == 1
+
+
 def test_dispatch_report_and_close(cli_runs, tmp_path, capsys):
     run_id = _dispatch_new(capsys)
     rf = tmp_path / "report.json"

{fleetproof-0.3.0 → fleetproof-0.3.1}/tests/test_hookgate.py

@@ -622,6 +622,255 @@ def test_subagent_shims_run_via_the_plugin_root_fallback(tmp_path):
     assert "report-before-idle" in decision["reason"]
 
 
+# === dispatch-intent sidecar (SubagentStart) ===
+
+_INTENT_PROMPT = "Refactor the widget module and prove it with the manifest checks."
+
+
+def _intent_manifest(cmd_exit=0):
+    cmd = f'"{sys.executable}" -c "raise SystemExit({cmd_exit})"'
+    return {
+        "deliverables": ["the widget refactor"],
+        "checks": [{"id": "m-widget", "cmd": cmd}],
+        "check_map": {"the widget refactor": ["m-widget"]},
+        "notes": "declared by the dispatcher",
+    }
+
+
+def test_subagent_start_consumes_intent_sidecar(tmp_path, monkeypatch):
+    # The whole point of the sidecar: the real prompt, manifest, and tier land
+    # on the captured dispatch, and the intent file is gone afterwards.
+    from fleetproof.hookgate import subagent_start_main
+    from fleetproof.ledger import intent_path, list_dispatches, write_intent
+    _setup_project(tmp_path, [_LANE_PASS], monkeypatch)
+    path = write_intent("tester", _INTENT_PROMPT,
+                        manifest=_intent_manifest(), tier="leaf")
+    assert path.exists()
+
+    _feed(monkeypatch, _start_payload())
+    assert subagent_start_main() == 0
+
+    d = list_dispatches()[0]
+    assert d.prompt == _INTENT_PROMPT
+    assert d.tier == "leaf"
+    assert d.tier_source == "declared"
+    assert d.manifest["deliverables"] == ["the widget refactor"]
+    assert d.manifest["check_map"] == {"the widget refactor": ["m-widget"]}
+    assert d.agent["capture"] == "start"
+    # Consumed: one intent, one spawn.
+    assert not path.exists()
+    assert intent_path("tester") is not None  # the name itself stays mappable
+
+
+def test_second_spawn_after_consumption_gets_the_placeholder(tmp_path, monkeypatch):
+    from fleetproof.hookgate import subagent_start_main
+    from fleetproof.ledger import list_dispatches, write_intent
+    _setup_project(tmp_path, [_LANE_PASS], monkeypatch)
+    write_intent("tester", _INTENT_PROMPT)
+
+    _feed(monkeypatch, _start_payload(agent_id="agent-1"))
+    subagent_start_main()
+    _feed(monkeypatch, _start_payload(agent_id="agent-2"))
+    subagent_start_main()
+
+    # Two spawns in the same second sort unpredictably; key on the agent id.
+    by_agent = {d.agent_id: d for d in list_dispatches()}
+    assert by_agent["agent-1"].prompt == _INTENT_PROMPT
+    assert "[uncaptured]" in by_agent["agent-2"].prompt
+    assert by_agent["agent-2"].tier == "lane"
+
+
+def test_intent_for_a_different_agent_type_is_left_alone(tmp_path, monkeypatch):
+    from fleetproof.hookgate import subagent_start_main
+    from fleetproof.ledger import intent_path, list_dispatches, write_intent
+    _setup_project(tmp_path, [_LANE_PASS], monkeypatch)
+    write_intent("someone-else", _INTENT_PROMPT)
+
+    _feed(monkeypatch, _start_payload(agent_type="tester"))
+    assert subagent_start_main() == 0
+
+    assert "[uncaptured]" in list_dispatches()[0].prompt
+    assert intent_path("someone-else").exists()  # not consumed by the wrong spawn
+
+
+def test_malformed_intent_json_degrades_to_placeholder(tmp_path, monkeypatch, capsys):
+    # The capture must survive a hand-mangled sidecar: placeholder path, loud
+    # stderr note, and the bad file consumed so it cannot poison the next spawn.
+    from fleetproof.hookgate import subagent_start_main
+    from fleetproof.ledger import intent_path, intents_dir, list_dispatches
+    _setup_project(tmp_path, [_LANE_PASS], monkeypatch)
+    intents_dir().mkdir(parents=True, exist_ok=True)
+    (intents_dir() / "tester.json").write_text("not json at all", encoding="utf-8")
+
+    _feed(monkeypatch, _start_payload())
+    assert subagent_start_main() == 0
+
+    d = list_dispatches()[0]
+    assert "[uncaptured]" in d.prompt
+    assert "intent file tester.json" in capsys.readouterr().err
+    assert not intent_path("tester").exists()
+
+
+def test_malformed_manifest_in_a_valid_intent_degrades_with_a_note(
+        tmp_path, monkeypatch, capsys):
+    # A valid intent whose manifest is unusable keeps its real prompt; the
+    # manifest degrades to derive-from-prompt with the failure written into the
+    # manifest notes, where it survives on the dispatch record itself.
+    from fleetproof.hookgate import subagent_start_main
+    from fleetproof.ledger import INTENT_MANIFEST_MALFORMED, intents_dir, list_dispatches
+    _setup_project(tmp_path, [_LANE_PASS], monkeypatch)
+    intents_dir().mkdir(parents=True, exist_ok=True)
+    (intents_dir() / "tester.json").write_text(json.dumps({
+        "agent_type": "tester",
+        "prompt": _INTENT_PROMPT,
+        "manifest": {"deliverables": "not-an-array"},
+    }), encoding="utf-8")
+
+    _feed(monkeypatch, _start_payload())
+    assert subagent_start_main() == 0
+
+    d = list_dispatches()[0]
+    assert d.prompt == _INTENT_PROMPT
+    assert d.manifest["deliverables"] == []
+    assert INTENT_MANIFEST_MALFORMED in d.manifest["notes"]
+    assert "malformed" in capsys.readouterr().err
+
+
+def test_invalid_intent_tier_falls_back_to_the_captured_default(
+        tmp_path, monkeypatch, capsys):
+    from fleetproof.hookgate import subagent_start_main
+    from fleetproof.ledger import intents_dir, list_dispatches
+    _setup_project(tmp_path, [_LANE_PASS], monkeypatch)
+    intents_dir().mkdir(parents=True, exist_ok=True)
+    (intents_dir() / "tester.json").write_text(json.dumps({
+        "agent_type": "tester", "prompt": _INTENT_PROMPT, "tier": "captain",
+    }), encoding="utf-8")
+
+    _feed(monkeypatch, _start_payload())
+    assert subagent_start_main() == 0
+
+    d = list_dispatches()[0]
+    assert d.prompt == _INTENT_PROMPT
+    assert d.tier == "lane"
+    assert "captain" in capsys.readouterr().err
+
+
+# === manifest checks in the stop gate (SubagentStop) ===
+
+def _era_config(tmp_path: Path) -> None:
+    """Telemetry-era cutover in force, so the gate builds telemetry.json."""
+    (tmp_path / ".fleetproof" / "config.json").write_text(
+        json.dumps({"telemetry_era": "2026-01-01"}), encoding="utf-8")
+
+
+def _spawn_with_intent(tmp_path, monkeypatch, manifest, spec=None):
+    from fleetproof.hookgate import subagent_start_main
+    from fleetproof.ledger import write_intent
+    _setup_project(tmp_path, spec if spec is not None else [_LEAF_ONLY], monkeypatch)
+    _era_config(tmp_path)
+    write_intent("tester", _INTENT_PROMPT, manifest=manifest, tier="lane")
+    _feed(monkeypatch, _start_payload())
+    subagent_start_main()
+
+
+def test_manifest_checks_grade_a_dispatch_the_spec_ignores(tmp_path, monkeypatch, capsys):
+    # The L21 fix, end to end: the repo spec has nothing at lane tier, so before
+    # 0.3.1 this dispatch terminated ungraded. Its own manifest checks now run
+    # as blocking, the verdict lands, and coverage joins through check_map.
+    from fleetproof.hookgate import subagent_stop_main
+    from fleetproof.ledger import list_dispatches
+    from fleetproof.telemetry import load_telemetry
+    _spawn_with_intent(tmp_path, monkeypatch, _intent_manifest(cmd_exit=0))
+
+    _feed(monkeypatch, _stop_payload(message="Refactored and verified."))
+    assert subagent_stop_main() == 0
+    assert capsys.readouterr().out == ""  # allowed to stop
+
+    d = list_dispatches()[0]
+    assert d.verdict == "verified"
+    assert d.state == "terminated"
+    telemetry = load_telemetry(d.run_id)
+    assert telemetry["outcome.class"] == "verified"
+    assert telemetry["outcome.verifier"]["checks_run"] == 1
+    assert telemetry["outcome.coverage"] > 0
+
+
+def test_failing_manifest_check_contradicts_and_blocks(tmp_path, monkeypatch, capsys):
+    from fleetproof.hookgate import subagent_stop_main
+    from fleetproof.ledger import list_dispatches
+    _spawn_with_intent(tmp_path, monkeypatch, _intent_manifest(cmd_exit=1))
+
+    _feed(monkeypatch, _stop_payload(message="Refactored, honest."))
+    assert subagent_stop_main() == 0
+    decision = json.loads(capsys.readouterr().out)
+    assert decision["decision"] == "block"
+    assert "m-widget" in decision["reason"]
+
+    d = list_dispatches()[0]
+    assert d.state == "contradicted"
+    assert d.is_terminal is False  # the retry lands on this same dispatch
+
+
+def test_manifest_checks_union_with_tier_selected_repo_checks(tmp_path, monkeypatch, capsys):
+    # Both sources grade the same stop: the lane-tier repo check and the
+    # dispatch's own manifest check each execute exactly once.
+    from fleetproof.hookgate import subagent_stop_main
+    from fleetproof.ledger import list_dispatches
+    _spawn_with_intent(tmp_path, monkeypatch, _intent_manifest(cmd_exit=0),
+                       spec=[_LANE_PASS])
+
+    _feed(monkeypatch, _stop_payload(message="Done, both ways."))
+    assert subagent_stop_main() == 0
+    assert capsys.readouterr().out == ""
+
+    assert _graded_check_ids() == ["lane-ok", "m-widget"]
+    assert list_dispatches()[0].verdict == "verified"
+
+
+def test_manifest_check_colliding_with_a_repo_check_id_defers_to_the_spec(
+        tmp_path, monkeypatch, capsys):
+    # One id, one command: the repo spec is the more attested source, so a
+    # manifest check reusing a selected repo check's id is dropped rather than
+    # run as a second command under the same name.
+    from fleetproof.hookgate import subagent_stop_main
+    from fleetproof.ledger import list_dispatches
+    manifest = {
+        "checks": [{"id": "lane-ok",
+                    "cmd": f'"{sys.executable}" -c "raise SystemExit(1)"'}],
+    }
+    _spawn_with_intent(tmp_path, monkeypatch, manifest, spec=[_LANE_PASS])
+
+    _feed(monkeypatch, _stop_payload(message="Done."))
+    assert subagent_stop_main() == 0
+    assert capsys.readouterr().out == ""  # the repo's lane-ok passes; no block
+
+    assert _graded_check_ids() == ["lane-ok"]
+    assert list_dispatches()[0].verdict == "verified"
+
+
+def test_malformed_manifest_check_entries_are_skipped_loudly(
+        tmp_path, monkeypatch, capsys):
+    # Junk entries must neither run half-parsed nor take down the gate — and a
+    # skipped check never counts as executed, so it can never read as a pass.
+    from fleetproof.hookgate import subagent_stop_main
+    from fleetproof.ledger import list_dispatches
+    manifest = _intent_manifest(cmd_exit=0)
+    manifest["checks"] = [
+        "not-an-object",
+        {"id": "no-cmd"},
+        {"id": "multi-line", "cmd": "echo a\necho b"},
+    ] + manifest["checks"]
+    _spawn_with_intent(tmp_path, monkeypatch, manifest)
+
+    _feed(monkeypatch, _stop_payload(message="Done."))
+    assert subagent_stop_main() == 0
+    err = capsys.readouterr().err
+    assert "skipped" in err
+
+    assert _graded_check_ids() == ["m-widget"]  # only the well-formed entry ran
+    assert list_dispatches()[0].verdict == "verified"
+
+
 def test_read_hook_input_tolerates_utf8_bom(monkeypatch):
     # Some shells prepend a BOM when piping; losing the payload would silently
     # lose session grouping and drift detection.