@litterthanlit/hypher-cli 0.1.6 → 0.1.7

package/README.md

@@ -5,6 +5,7 @@ Pilot · not yet recorded. The bridge between coding agents and Hypher project m
 - `hypher init` connects this computer (one browser approval), installs a pinned copy under `~/.hypher/`, and adds Claude Code hooks and Codex hooks (Codex asks once to trust them: `/hooks`). It keeps M0a's `hypher` sign-in entry wherever it finds one.
 - `hypher doctor` checks each piece and prints the fix for anything red.
 - `hypher resume` prints the note for this repository; `hypher seal` saves a handoff.
+- `hypher seal --evidence "<command>=<exit code>"` (repeatable, split at the last `=`) reports a check you ran. Hypher binds each to the working tree at the save and labels it an agent report (only agent reports are accepted until hooks capture checks in Baton M3); the next note says whether that tree still matches. It never runs the command. Only the command text, exit code, tree hash, and time leave the machine, never output. Against a server that does not accept evidence yet, the handoff saves without it and says so.
 - `hypher mcp` is the bridge for any MCP client: `resume`, `seal`, and `acknowledge`, with no IDs.
 - `hypher uninstall` removes exactly what `init` added and revokes the key.
 - `init` also puts `~/.hypher/bin` on PATH with one marked block in your shell's startup file (`~/.zshenv` for zsh, `~/.bash_profile` or `~/.bashrc` for bash, a `conf.d` file for fish), so `hypher` runs by name in new terminals and in agents' shells. `--no-path` skips it; hooks and the MCP bridge use the full path either way.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litterthanlit/hypher-cli",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Hypher bridge for coding agents: hooks, a local outbox, and a truth check against the working tree. Pilot, not yet recorded.",
   "type": "module",
   "bin": {

package/src/cli.mjs

@@ -35,6 +35,7 @@ const OPTIONS = {
   completed: { type: "string", multiple: true },
   unverified: { type: "string", multiple: true },
   blocker: { type: "string", multiple: true },
+  evidence: { type: "string", multiple: true },
   source: { type: "string" },
   agent: { type: "string" },
   session: { type: "string" },
@@ -52,7 +53,8 @@ Usage: hypher <command>
   doctor      Check every piece and print the fix for anything red
   status      What is installed; --last shows exactly what was last sent
   resume      Print the handoff note for this repository and its truth check
-  seal        Save a handoff: --next "…" [--decision "…" --why "…" [--replaces "…"]] or JSON on stdin
+  seal        Save a handoff: --next "…" [--decision "…" --why "…" [--replaces "…"]]
+              [--evidence "<command>=<exit code>": a check you ran] or JSON on stdin
   ack         Acknowledge the handoff this session read
   mcp         Run the stdio MCP bridge: resume, seal, acknowledge (for any MCP client)
   uninstall   Remove exactly what init added and revoke the key

package/src/commands/mcp.mjs

@@ -14,6 +14,7 @@ import { createClient, HypherRejected, HypherUnavailable } from "../api.mjs";
 import { CLI_VERSION } from "../env.mjs";
 import { detectAgent, resumeHere, sealHere } from "../session.mjs";
 import { acknowledgeHere } from "./ack.mjs";
+import { evidenceInput } from "./seal.mjs";
 
 const SUPPORTED_PROTOCOLS = ["2024-11-05", "2025-03-26", "2025-06-18", "2025-11-25"];
 
@@ -40,7 +41,7 @@ export const LOCAL_TOOLS = [
   {
     name: "seal",
     title: "Save to Hypher",
-    description: "Call before you finish work that changed files, or when asked to save. Saves a handoff for the next agent from what you know: the decisions that changed and why, and the next action. The bridge adds repository, branch, commit, and tree identity and carries earlier decisions forward. Sends only this text, file names, and commit identity; never code. Needs no IDs. The first save in a repository also needs goal, and so does a save after the work moved on from the note's goal.",
+    description: "Call before you finish work that changed files, or when asked to save. Saves a handoff for the next agent from what you know: the decisions that changed and why, and the next action. The bridge adds repository, branch, commit, and tree identity and carries earlier decisions forward. To report checks, pass evidence: only commands you actually ran, with their exit codes. Hypher records them against the current tree as an agent report; it never runs them. Sends only this text, file names, and commit identity; never code or command output. Needs no IDs. The first save in a repository also needs goal, and so does a save after the work moved on from the note's goal.",
     inputSchema: {
       type: "object",
       properties: {
@@ -63,6 +64,18 @@ export const LOCAL_TOOLS = [
         completed: LIST("Work you finished (reported, not verified)."),
         unverified: LIST("Work that still needs checking."),
         blockers: LIST("What blocks the next action, if anything."),
+        evidence: {
+          type: "array",
+          description: "Checks you ran in this session: report only commands you actually ran, with their exit codes. Hypher records them against the current tree as an agent report and never runs them. The command text only, never its output. A check against an older tree is flagged for the next agent. At most 8.",
+          items: {
+            type: "object",
+            properties: {
+              command: { type: "string", description: "The command as you ran it, on one line." },
+              exitCode: { type: "integer", minimum: 0, maximum: 255, description: "Its exit code." },
+            },
+            required: ["command", "exitCode"],
+          },
+        },
         cwd: CWD_PROPERTY,
       },
       required: ["nextAction"],
@@ -171,6 +184,7 @@ export async function callLocalTool(name, args, session) {
       completed: asList(args?.completed),
       unverified: asList(args?.unverified),
       blockers: asList(args?.blockers),
+      evidence: evidenceInput(args?.evidence),
     };
     const result = await sealHere({ env: session.env, cwd, seal, agent });
     return textResult(result.message, !result.ok);

package/src/commands/seal.mjs

@@ -5,15 +5,37 @@
  *
  *   hypher seal --next "Fix rounding" --decision "Guest checkout only" --why "…" --replaces D1
  *   hypher seal '{"nextAction":"…","decisions":[{"decision":"…","why":"…"}]}'
+ *   hypher seal --next "Fix rounding" --evidence "npm test=0" --evidence "npm run lint=1"
  *   echo '{"nextAction":"…"}' | hypher seal --stdin
  *
  * The JSON fields are the MCP `seal` tool's: nextAction, goal, decisions
- * [{ decision, why, replaces }], constraints, completed, unverified, blockers.
+ * [{ decision, why, replaces }], constraints, completed, unverified, blockers,
+ * evidence [{ command, exitCode }]: the checks the agent ran. Hypher records each
+ * against the current tree as an agent report; it never runs the command.
  */
 import { detectAgent, sealHere } from "../session.mjs";
 import { readWorktreeState } from "../state.mjs";
 import { repoIdentity } from "../../vendor/hypher-git.mjs";
 
+/** `--evidence "<command>=<exit code>"`: split at the last `=`, so a command may hold its own. */
+export function parseEvidenceFlag(value) {
+  const text = String(value ?? "");
+  const at = text.lastIndexOf("=");
+  const command = at < 0 ? "" : text.slice(0, at).trim();
+  const code = at < 0 ? "" : text.slice(at + 1).trim();
+  if (!command) return { error: `--evidence "${text}" needs the form "<command>=<exit code>", for example --evidence "npm test=0".` };
+  if (!/^\d{1,3}$/.test(code) || Number(code) > 255) {
+    return { error: `--evidence "${command}": the exit code "${code}" must be a whole number from 0 to 255.` };
+  }
+  return { evidence: { command, exitCode: Number(code) } };
+}
+
+/** The evidence array from JSON or MCP arguments: only `command` and `exitCode` are read. */
+export function evidenceInput(value) {
+  if (!Array.isArray(value)) return value;
+  return value.map((item) => ({ command: item?.command, exitCode: item?.exitCode }));
+}
+
 /** Pair each --why and --replaces with the --decision before it. */
 export function sealFromTokens(tokens) {
   const seal = { decisions: [] };
@@ -23,7 +45,11 @@ export function sealFromTokens(tokens) {
     const value = token.value ?? "";
     if (token.name === "goal") seal.goal = value;
     else if (token.name === "next") seal.nextAction = value;
-    else if (token.name === "decision") seal.decisions.push({ decision: value, why: "" });
+    else if (token.name === "evidence") {
+      const parsed = parseEvidenceFlag(value);
+      if (parsed.error) return { error: parsed.error };
+      (seal.evidence ??= []).push(parsed.evidence);
+    } else if (token.name === "decision") seal.decisions.push({ decision: value, why: "" });
     else if (token.name === "why" || token.name === "replaces") {
       const last = seal.decisions[seal.decisions.length - 1];
       if (!last) return { error: `--${token.name} must follow a --decision.` };
@@ -55,6 +81,7 @@ export function sealFromJson(parsed) {
       completed: list(parsed.completed),
       unverified: list(parsed.unverified),
       blockers: list(parsed.blockers),
+      evidence: evidenceInput(parsed.evidence),
     },
   };
 }

package/src/env.mjs

@@ -7,7 +7,7 @@ import os from "node:os";
 import path from "node:path";
 
 // Keep equal to package.json; a test checks it.
-export const CLI_VERSION = "0.1.6";
+export const CLI_VERSION = "0.1.7";
 export const DEFAULT_API_BASE = "https://www.hypher.app";
 export const INTEGRATIONS_URL = "https://hypher.app/app/settings/integrations";
 export const API_KEYS_URL = "https://hypher.app/app/settings/api-keys";

package/src/hooks/index.mjs

@@ -52,10 +52,10 @@ function sealRequest(firstHandoff) {
   const goal = firstHandoff ? ' --goal "<the goal>"' : "";
   return [
     "Hypher: the working tree changed since the last handoff, and no one saved why.",
-    "Before you stop, record the decisions that changed and the next action for the next agent:",
+    "Before you stop, record the decisions that changed, the next action for the next agent, and the checks you ran with their exit codes:",
     `call the \`seal\` tool of the hypher MCP server, or, only if that tool is not available, run \`hypher seal${goal} --decision "<a decision that changed>" --why "<why>" --next "<the next action>"\` in the terminal.`,
     firstHandoff ? "This is the first handoff here, so give the goal too." : "If the work moved on from the note's goal, give the new goal too (goal, or --goal \"…\").",
-    "Add one --decision/--why pair per changed decision (--replaces D1 names one it replaces), or none if no decision changed; --next is always needed.",
+    "Add one --decision/--why pair per changed decision (--replaces D1 names one it replaces), or none if no decision changed; --next is always needed. Report only checks you ran (evidence, or --evidence \"<command>=<exit code>\").",
     "It sends only your text, file names, and commit identity. Hypher asks once; if you cannot save now, say so and stop.",
   ].join(" ");
 }

package/src/session.mjs

@@ -117,6 +117,8 @@ export async function resumeHere({ env, cwd, destination, sessionId, now = Date.
     from: prepared.sourceAgent,
     savedAt,
     verdict,
+    // Each reported check says whether its tree is the tree now.
+    currentTree: verdict?.current?.tree ?? snapshot.tree,
     checkpoint: shownCheckpoint,
     acknowledge: ACK_HINT,
   });
@@ -141,9 +143,19 @@ export async function resumeHere({ env, cwd, destination, sessionId, now = Date.
   };
 }
 
+/** Said once when an older server refuses the `evidence` field and the handoff goes without it. */
+export const NO_EVIDENCE_LINE = "This Hypher server does not accept evidence yet; the handoff was saved without it.";
+
+/** True when a refusal is the server rejecting the `evidence` field itself, not a bad entry. */
+export function refusesEvidenceField(text) {
+  const message = String(text ?? "");
+  return /\bevidence\b/i.test(message) && /not allowed|extra field|not in the validator|unknown (?:field|key)|unexpected/i.test(message);
+}
+
 /**
  * Save a handoff from what the agent knows: decisions that changed and why,
- * and the next action. Based on the revision this session was handed.
+ * the next action, and the checks it ran (command and exit code, bound to the
+ * tree at this save). Based on the revision this session was handed.
  * @param {{ env: NodeJS.ProcessEnv, cwd: string, seal: object, agent: string, now?: number }} options
  */
 export async function sealHere({ env, cwd, seal, agent, now = Date.now() }) {
@@ -164,11 +176,21 @@ export async function sealHere({ env, cwd, seal, agent, now = Date.now() }) {
   }
   const prior = state.proposal ? parseHandoffProposal(state.proposal, { allowPlaceholders: true }) : null;
   const iso = new Date(now).toISOString().slice(0, 16).replace("T", " ");
+  // Checks are bound to the working-tree hash at this save. Without one, the handoff still
+  // saves; the checks are left out and the agent is told.
+  const lines = [];
+  let toSeal = seal;
+  if (Array.isArray(seal.evidence) && seal.evidence.length && !snapshot.tree) {
+    toSeal = { ...seal, evidence: undefined };
+    lines.push("The checks were not recorded: Hypher could not read the working tree hash.");
+  }
   const built = buildSealProposal({
     prior: prior?.ok ? prior.value : null,
-    seal,
+    seal: toSeal,
     repo: snapshot.currentRepo,
     sessionRef: `${agent} session on ${snapshot.branch}, ${iso} UTC`,
+    tree: snapshot.tree,
+    now,
   });
   if (!built.ok) return { ok: false, code: "invalid", message: built.error };
 
@@ -178,28 +200,41 @@ export async function sealHere({ env, cwd, seal, agent, now = Date.now() }) {
       ? { ok: false, code: "sandboxed", message: SANDBOX_LINE }
       : { ok: false, code: "not-connected", message: "This computer is not connected. Run `hypher init`." };
   }
-  const request = {
-    kind: "handoff",
-    source: agent,
-    projectId: link.projectId,
-    proposal: built.proposal,
-    expectedBaseRevision: state.baseRevision,
-  };
-  // Same base and same request: same key, so a retry dedupes. A change that
-  // returns to earlier content has a newer base, so it is not a duplicate.
-  const idempotencyKey = `seal-${sha256(`${state.baseRevision}\n${canonicalJson(request)}`).slice(0, 40)}`;
-  let result;
-  try {
-    result = (await client.tool("post_agent_event", { ...request, idempotencyKey })).structured;
-  } catch (error) {
-    if (error instanceof HypherUnavailable) {
-      return inCodexSandbox(env)
-        ? { ok: false, code: "sandboxed", message: SANDBOX_LINE }
-        : { ok: false, code: "unavailable", message: "Hypher unavailable; nothing was saved. Run `hypher doctor`, then seal again." };
+  /** One save request. Returns the server's answer, or the failure to hand back. */
+  async function send(proposal) {
+    const request = {
+      kind: "handoff",
+      source: agent,
+      projectId: link.projectId,
+      proposal,
+      expectedBaseRevision: state.baseRevision,
+    };
+    // Same base and same request: same key, so a retry dedupes. A change that
+    // returns to earlier content has a newer base, so it is not a duplicate.
+    const idempotencyKey = `seal-${sha256(`${state.baseRevision}\n${canonicalJson(request)}`).slice(0, 40)}`;
+    try {
+      return { result: (await client.tool("post_agent_event", { ...request, idempotencyKey })).structured };
+    } catch (error) {
+      if (error instanceof HypherUnavailable) {
+        return { failure: inCodexSandbox(env)
+          ? { ok: false, code: "sandboxed", message: SANDBOX_LINE }
+          : { ok: false, code: "unavailable", message: "Hypher unavailable; nothing was saved. Run `hypher doctor`, then seal again." } };
+      }
+      if (error instanceof HypherRejected) return { failure: { ok: false, code: "rejected", message: error.message } };
+      throw error;
     }
-    if (error instanceof HypherRejected) return { ok: false, code: "rejected", message: error.message };
-    throw error;
   }
+  let saved = built.proposal;
+  let sent = await send(saved);
+  // A server that predates evidence refuses the field itself. Once, without it.
+  if (saved.evidence && (refusesEvidenceField(sent.failure?.message) || (sent.result?.ok === false && refusesEvidenceField(sent.result.error)))) {
+    const { evidence: _evidence, ...withoutEvidence } = saved;
+    saved = withoutEvidence;
+    sent = await send(saved);
+    lines.push(NO_EVIDENCE_LINE);
+  }
+  if (sent.failure) return sent.failure;
+  const result = sent.result;
   if (!result?.ok) {
     if (result?.code === "stale-revision") {
       return { ok: false, code: "stale", message: `Hypher has a newer handoff (revision ${result.headRevision}) than the one this session read (revision ${state.baseRevision}). Run \`hypher resume\`, read it, and seal again.` };
@@ -211,7 +246,7 @@ export async function sealHere({ env, cwd, seal, agent, now = Date.now() }) {
   updateWorktreeState(env, snapshot.root, (current) => withBranchState({
     ...current,
     baseRevision: result.revision,
-    proposal: built.proposal,
+    proposal: saved,
     agent,
   }, snapshot.branch, { sealTree: tree }));
   return {
@@ -219,7 +254,7 @@ export async function sealHere({ env, cwd, seal, agent, now = Date.now() }) {
     code: result.code,
     revision: result.revision,
     projectName: link.projectName,
-    message: `Saved handoff revision ${result.revision} for "${link.projectName}". Memory did not transfer code.`,
+    message: [`Saved handoff revision ${result.revision} for "${link.projectName}". Memory did not transfer code.`, ...lines].join("\n"),
   };
 }
 

package/vendor/handoffNote.mjs

@@ -89,6 +89,27 @@ export function describeCheckpoint(checkpoint, now) {
     const files = checkpoint.changedFiles.length ? `changed: ${fileList(checkpoint.changedFiles)}` : "no uncommitted changes";
     return `Last checkpoint: ${formatAge(now - checkpoint.capturedAt)} ago from ${noteText(checkpoint.source, 40)} (${noteText(checkpoint.event, 40)}), not sealed · branch ${noteText(checkpoint.branch, 200)} · ${files}.`;
 }
+/** A code span that survives backticks inside the text. */
+function codeSpan(text) {
+    const longest = Math.max(0, ...(text.match(/`+/g) ?? []).map((run) => run.length));
+    const fence = "`".repeat(longest + 1);
+    return longest > 0 ? `${fence} ${text} ${fence}` : `${fence}${text}${fence}`;
+}
+/**
+ * One reported check: the command, its exit code, who reported it, how old it is, and
+ * whether the tree it ran against is the tree now. Hypher never runs the command; a check
+ * against an older tree says to run it again.
+ */
+export function describeEvidence(item, now, currentTree, max = 280) {
+    // The validator refuses `hook` until Baton M3; the wording waits for it.
+    const who = item.capturedBy === "hook" ? "captured by a hook" : "agent report";
+    const tree = !currentTree
+        ? "tree not checked here"
+        : currentTree === item.tree
+            ? "same tree as now"
+            : "the tree changed since; run it again before relying on it";
+    return `${codeSpan(noteText(item.command, max))} exit ${item.exitCode}, ${who}, ${formatAge(now - item.capturedAt)} ago, ${tree}.`;
+}
 function joinItems(items, empty, max = 280) {
     const cleaned = items.map((item) => noteText(item, max)).filter(Boolean);
     return cleaned.length ? cleaned.map((item) => (/[.!?…]$/.test(item) ? item : `${item}.`)).join(" ") : empty;
@@ -122,6 +143,9 @@ function sections(input, max, listLimit) {
         `Completed (agent-reported, not verified): ${joinItems(limit(proposal.completed), "none.", max)}${more(proposal.completed)}`,
         `Unverified: ${joinItems(limit(proposal.unverified), "none.", max)}${more(proposal.unverified)}`,
         `Blockers: ${joinItems(limit(proposal.blockers), "none.", max)}${more(proposal.blockers)}`,
+        ...(proposal.evidence?.length
+            ? [`Evidence: ${limit(proposal.evidence).map((item) => describeEvidence(item, input.now, input.currentTree, max)).join(" ")}${more(proposal.evidence)}`]
+            : []),
         ...(input.checkpoint ? [describeCheckpoint(input.checkpoint, input.now)] : []),
         `Sources: ${limit(proposal.sources).map((source) => {
             const kind = source.kind === "capture" ? "project capture" : source.kind === "agent_event" ? "stored agent report" : "agent report";

package/vendor/handoffSeal.mjs

@@ -59,6 +59,46 @@ function mergeUnique(prior, added) {
     }
     return merged;
 }
+const MAX_EVIDENCE_COMMAND = 300;
+const TREE_HASH = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+/**
+ * The checks this save reports, bound to the tree at the save, as agent
+ * reports. The order given is kept; a command listed twice keeps its last entry.
+ */
+function evidenceFromSeal(raw, tree, now) {
+    if (raw === undefined || raw === null)
+        return { ok: true, items: [] };
+    if (!Array.isArray(raw))
+        return { ok: false, error: "evidence must be a list of { command, exitCode }." };
+    const reported = [];
+    for (const item of raw) {
+        const entry = (item ?? {});
+        const command = clean(entry.command);
+        if (!command)
+            return { ok: false, error: "Each evidence entry needs a command (in a shell, --evidence \"<command>=<exit code>\")." };
+        if (/[\r\n\u2028\u2029]/.test(command))
+            return { ok: false, error: `Evidence command "${command.replace(/\s+/g, " ").slice(0, 40)}…" must be one line.` };
+        if (command.length > MAX_EVIDENCE_COMMAND) {
+            return { ok: false, error: `Evidence command "${command.slice(0, 40)}…" is ${command.length} characters; the limit is ${MAX_EVIDENCE_COMMAND}.` };
+        }
+        const exitCode = entry.exitCode;
+        if (typeof exitCode !== "number" || !Number.isInteger(exitCode) || exitCode < 0 || exitCode > 255) {
+            return { ok: false, error: `The exit code for evidence "${command}" must be a whole number from 0 to 255.` };
+        }
+        reported.push({ command, exitCode });
+    }
+    if (reported.length === 0)
+        return { ok: true, items: [] };
+    if (!tree || !TREE_HASH.test(tree)) {
+        return { ok: false, error: "Hypher could not read the working tree, so it cannot record the checks against it." };
+    }
+    const seen = new Set();
+    const latest = [...reported].reverse().filter((item) => !seen.has(item.command) && seen.add(item.command)).reverse();
+    return {
+        ok: true,
+        items: latest.map((item) => ({ command: item.command, exitCode: item.exitCode, tree, capturedBy: "agent", capturedAt: now })),
+    };
+}
 function tooMany(field, count, hint) {
     return `A handoff keeps at most ${MAX_HANDOFF_ITEMS} ${field}; this one would have ${count}. ${hint}`;
 }
@@ -130,6 +170,18 @@ export function buildSealProposal(input) {
     // save kept "finish CONTRIBUTING.md" and its stale lines). Decisions and constraints still carry.
     const goalChanged = Boolean(prior && newGoal && newGoal !== prior.goal);
     const listOrPrior = (value, fallback) => cleanList(value) ?? (goalChanged ? [] : fallback);
+    // Evidence follows the goal rule: kept while the goal holds, dropped when it changes. A newer
+    // entry for a command replaces the older one. This save's entries come first, then the earlier
+    // ones, so the list runs newest first; beyond eight, the oldest go.
+    const reported = evidenceFromSeal(seal.evidence, input.tree, input.now ?? Date.now());
+    if (!reported.ok)
+        return reported;
+    if (reported.items.length > MAX_HANDOFF_ITEMS) {
+        return { ok: false, error: tooMany("evidence entries", reported.items.length, "Report the checks the next agent needs.") };
+    }
+    const reportedCommands = new Set(reported.items.map((item) => item.command));
+    const carried = goalChanged ? [] : (prior?.evidence ?? []).filter((item) => !reportedCommands.has(item.command));
+    const evidence = [...reported.items, ...carried].slice(0, MAX_HANDOFF_ITEMS);
     const proposal = {
         schemaVersion: HANDOFF_PROPOSAL_SCHEMA_VERSION,
         goal,
@@ -141,6 +193,7 @@ export function buildSealProposal(input) {
         nextAction,
         sources,
         repo: input.repo,
+        ...(evidence.length ? { evidence } : {}),
     };
     for (const field of ["completed", "unverified", "blockers"]) {
         if (proposal[field].length > MAX_HANDOFF_ITEMS) {

package/vendor/structuredHandoff.mjs

@@ -13,6 +13,7 @@ const MAX_BRANCH = 200;
 const MAX_COMMIT = 80;
 const MAX_DESTINATION = 80;
 const MAX_REASON = 500;
+const MAX_COMMAND = 300;
 const PROPOSAL_KEYS = new Set([
     "schemaVersion",
     "goal",
@@ -24,7 +25,9 @@ const PROPOSAL_KEYS = new Set([
     "nextAction",
     "sources",
     "repo",
+    "evidence",
 ]);
+const EVIDENCE_KEYS = new Set(["command", "exitCode", "tree", "capturedBy", "capturedAt"]);
 export const HANDOFF_PROPOSAL_JSON_SCHEMA = {
     type: "object",
     additionalProperties: false,
@@ -93,6 +96,23 @@ export const HANDOFF_PROPOSAL_JSON_SCHEMA = {
             },
             description: "Working-tree metadata. This snapshot does not include file contents.",
         },
+        evidence: {
+            type: "array",
+            maxItems: MAX_ITEMS,
+            description: "Optional. Checks you ran, newest first: the command text and its exit code, bound to the working-tree hash at the save. An agent report; Hypher does not run it. Never include output or file contents.",
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: ["command", "exitCode", "tree", "capturedBy", "capturedAt"],
+                properties: {
+                    command: { type: "string", maxLength: MAX_COMMAND, description: "One line." },
+                    exitCode: { type: "integer", minimum: 0, maximum: 255 },
+                    tree: { type: "string", pattern: "^([0-9a-f]{40}|[0-9a-f]{64})$", description: "Working-tree hash at the save: the same hash as repo.dirtyFingerprint, without the tree: prefix, and also when the tree is clean." },
+                    capturedBy: { type: "string", enum: ["agent"] },
+                    capturedAt: { type: "integer", minimum: 1, description: "Milliseconds since the epoch." },
+                },
+            },
+        },
     },
 };
 function isObject(value) {
@@ -156,6 +176,40 @@ export function parseRepoSnapshot(value) {
     }
     return { ok: true, value: result };
 }
+const TREE_HASH = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+export function parseEvidence(value) {
+    if (!Array.isArray(value))
+        return { ok: false, error: "evidence must be an array" };
+    if (value.length > MAX_ITEMS)
+        return { ok: false, error: "evidence has too many items" };
+    const items = [];
+    for (const item of value) {
+        if (!isObject(item))
+            return { ok: false, error: "evidence must be objects" };
+        const extra = unknownKey(item, EVIDENCE_KEYS);
+        if (extra)
+            return { ok: false, error: `evidence.${extra} is not allowed` };
+        const command = shortText(item.command, "evidence.command", MAX_COMMAND);
+        if (!command.ok)
+            return command;
+        if (/[\r\n\u2028\u2029]/.test(command.value))
+            return { ok: false, error: "evidence.command must be one line" };
+        if (typeof item.exitCode !== "number" || !Number.isInteger(item.exitCode) || item.exitCode < 0 || item.exitCode > 255) {
+            return { ok: false, error: "evidence.exitCode must be a whole number from 0 to 255" };
+        }
+        if (typeof item.tree !== "string" || !TREE_HASH.test(item.tree)) {
+            return { ok: false, error: "evidence.tree must be a 40 or 64 character lowercase hex hash" };
+        }
+        if (item.capturedBy !== "agent") {
+            return { ok: false, error: "evidence.capturedBy must be agent" };
+        }
+        if (typeof item.capturedAt !== "number" || !Number.isInteger(item.capturedAt) || item.capturedAt < 1) {
+            return { ok: false, error: "evidence.capturedAt must be a positive whole number of milliseconds" };
+        }
+        items.push({ command: command.value, exitCode: item.exitCode, tree: item.tree, capturedBy: item.capturedBy, capturedAt: item.capturedAt });
+    }
+    return { ok: true, value: items };
+}
 const PLACEHOLDER_PREFIX = "FILL:";
 function isPlaceholder(value) {
     return typeof value === "string" && value.trim().startsWith(PLACEHOLDER_PREFIX);
@@ -192,6 +246,8 @@ export function findHandoffPlaceholder(proposal) {
         if (isPlaceholder(proposal.repo[field]))
             return `repo.${field}`;
     }
+    if (proposal.evidence?.some((item) => isPlaceholder(item.command)))
+        return "evidence.command";
     return null;
 }
 /**
@@ -322,6 +378,13 @@ export function parseHandoffProposal(value, options = {}) {
     const repo = parseRepoSnapshot(value.repo);
     if (!repo.ok)
         return repo;
+    let evidence;
+    if (value.evidence !== undefined) {
+        const parsedEvidence = parseEvidence(value.evidence);
+        if (!parsedEvidence.ok)
+            return parsedEvidence;
+        evidence = parsedEvidence.value;
+    }
     const proposal = {
         schemaVersion: 1,
         goal: goal.value,
@@ -333,6 +396,7 @@ export function parseHandoffProposal(value, options = {}) {
         nextAction: nextAction.value,
         sources,
         repo: repo.value,
+        ...(evidence !== undefined ? { evidence } : {}),
     };
     if (!options.allowPlaceholders) {
         const placeholder = findHandoffPlaceholder(proposal);
@@ -354,6 +418,9 @@ export function renderHandoffPacket(proposal) {
         proposal.completed.length ? `Agent-reported completed work: ${proposal.completed.join("; ")}` : "Agent-reported completed work: none",
         proposal.unverified.length ? `Unverified: ${proposal.unverified.join("; ")}` : "Unverified: none",
         proposal.blockers.length ? `Blockers: ${proposal.blockers.join("; ")}` : "Blockers: none",
+        ...(proposal.evidence?.length
+            ? [`Evidence (agent reports against the tree at the save; Hypher did not run them): ${proposal.evidence.map((item) => `${item.command} exited ${item.exitCode}`).join("; ")}`]
+            : []),
         `Next action: ${proposal.nextAction}`,
         "Sources:",
         ...proposal.sources.map((item) => `- ${item.kind === "capture" ? "Project capture" : item.kind === "agent_event" ? "Stored agent report" : "Agent-reported"}: ${item.label ? `${item.label}: ` : ""}${item.ref}`),