@litterthanlit/hypher-cli 0.1.6 → 0.1.8

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.8",
   "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.8";
 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

@@ -17,13 +17,18 @@ import {
   renderNoHandoffNote,
   renderUnlinkedLine,
 } from "../vendor/handoffNote.mjs";
-import { buildSealProposal } from "../vendor/handoffSeal.mjs";
-import { parseHandoffProposal } from "../vendor/structuredHandoff.mjs";
+import { buildSealProposal, CLI_UPDATE_COMMAND, readOnlyHandoffMessage } from "../vendor/handoffSeal.mjs";
+import { parseHandoffProposalLenient } from "../vendor/structuredHandoff.mjs";
 
 // The MCP tool first: in an agent's shell `hypher` may be off PATH or inside Codex's sandbox.
 export const ACK_HINT = "call the `acknowledge` tool of the `hypher` MCP server, or run `hypher ack`";
 const NOT_CONNECTED_LINE = "Hypher is not connected on this computer; starting without it. Run `hypher init` in a terminal.";
 
+/** Said at the top of the note when the handoff is newer than this copy of Hypher can save over. */
+export function readOnlyNotice(version) {
+  return `Hypher: this handoff is read-only here. It is format version ${version}, newer than this copy of Hypher can save over, so a save would be refused and nothing would be sent. Use the note as it is. To save again, run \`${CLI_UPDATE_COMMAND}\` in a terminal.`;
+}
+
 /** The agent running this command, from its environment. */
 export function detectAgent(env, fallback) {
   if (env.HYPHER_AGENT) return String(env.HYPHER_AGENT).slice(0, 40);
@@ -104,8 +109,9 @@ export async function resumeHere({ env, cwd, destination, sessionId, now = Date.
     return { status: "rejected", note: `Hypher: ${prepared?.error ?? "could not load the handoff"}. Run \`hypher doctor\`.`, snapshot };
   }
 
-  const parsed = parseHandoffProposal(prepared.proposal, { allowPlaceholders: true });
-  if (!parsed.ok) return { status: "rejected", note: "Hypher returned a handoff this CLI cannot read. Update with `hypher init`.", snapshot };
+  // Read leniently: a field, a longer list, or a newer version written by a newer Hypher is not a reason to refuse the note.
+  const parsed = parseHandoffProposalLenient(prepared.proposal);
+  if (!parsed.ok) return { status: "rejected", note: `Hypher returned a handoff this CLI cannot read. Update with \`${CLI_UPDATE_COMMAND}\`.`, snapshot };
   const proposal = parsed.value;
   const verdict = truthCheck(snapshot.root, proposal.repo);
   const savedAt = typeof prepared.savedAt === "number" ? prepared.savedAt : undefined;
@@ -117,8 +123,11 @@ 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,
+    notice: parsed.readOnly ? readOnlyNotice(proposal.schemaVersion) : null,
   });
   updateWorktreeState(env, snapshot.root, (state) => withBranchState({
     ...state,
@@ -141,9 +150,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() }) {
@@ -162,13 +181,25 @@ export async function sealHere({ env, cwd, seal, agent, now = Date.now() }) {
   if (!state || state.projectId !== link.projectId || typeof state.baseRevision !== "number") {
     return { ok: false, code: "no-base", message: "Run `hypher resume` first, so this save is based on the handoff you read." };
   }
-  const prior = state.proposal ? parseHandoffProposal(state.proposal, { allowPlaceholders: true }) : null;
+  const prior = state.proposal ? parseHandoffProposalLenient(state.proposal) : null;
+  // A newer format than this copy can write: refused before anything is built or sent.
+  if (prior?.ok && prior.readOnly) return { ok: false, code: "read-only", message: readOnlyHandoffMessage(prior.value.schemaVersion) };
   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 +209,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 +255,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 +263,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;
@@ -114,6 +135,7 @@ function sections(input, max, listLimit) {
         header,
         NOTE_FIRST_REPLY,
         NOTE_PREAMBLE,
+        ...(input.notice ? [noteText(input.notice, 500)] : []),
         input.verdict ? describeVerdict(input.verdict)
             : "Tree: not checked here. Compare the repository, branch, commit, and uncommitted files yourself before continuing.",
         `Constraints: ${joinItems(limit(proposal.constraints), "none recorded.", max)}${more(proposal.constraints)}`,
@@ -122,6 +144,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

@@ -6,8 +6,17 @@
  * adds a source for this session, and maps short decision references ("D2",
  * or a unique part of the text) to the exact prior text for `supersedes`.
  */
-import { HANDOFF_PROPOSAL_SCHEMA_VERSION, parseHandoffProposal, } from "./structuredHandoff.mjs";
+import { HANDOFF_PROPOSAL_SCHEMA_VERSION, knownFieldsV1, parseHandoffProposal, reattachUnknownFields, } from "./structuredHandoff.mjs";
 export const MAX_HANDOFF_ITEMS = 8;
+/**
+ * What an installed copy runs to update itself. `hypher init` from an installed copy finds itself
+ * already at its own path and keeps the same version; the `@latest` fetch is what updates.
+ */
+export const CLI_UPDATE_COMMAND = "npx @litterthanlit/hypher-cli@latest init";
+/** Why a save on top of a newer-format handoff is refused. One line; nothing was sent. */
+export function readOnlyHandoffMessage(version) {
+    return `This handoff is format version ${version}, newer than this copy of Hypher can save over, so nothing was sent. Update with \`${CLI_UPDATE_COMMAND}\` in a terminal, then save again.`;
+}
 function clean(value) {
     return typeof value === "string" ? value.trim() : "";
 }
@@ -59,15 +68,67 @@ 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}`;
 }
 /**
+ * Carry rule: a save sends what it knows plus what it was handed, unchanged. Fields of the prior
+ * handoff that this code does not know are re-attached as they were: the top-level ones always,
+ * and those on a decision, source, or evidence item for as long as that item is carried forward.
+ * They leave with the item when it is replaced or dropped, because its owner was removed on
+ * purpose. Nothing this code did not read is invented or edited, and `repo` is replaced. The
+ * known fields are built only from the seal input and checked by the strict parser; the carried
+ * ones are not checked here, and the server refuses by name what it does not accept. A prior
+ * newer than version 1 is read-only: the save is refused.
+ *
  * @param prior the proposal this session resumed from (null for the first handoff)
  * @param sessionRef a unique label for this session, used as its source
  */
 export function buildSealProposal(input) {
     const { prior, seal } = input;
+    if (prior && prior.schemaVersion !== HANDOFF_PROPOSAL_SCHEMA_VERSION) {
+        return { ok: false, error: readOnlyHandoffMessage(prior.schemaVersion) };
+    }
     const nextAction = clean(seal.nextAction);
     if (!nextAction)
         return { ok: false, error: "The next action is required: nextAction (in a shell, --next \"…\")." };
@@ -130,6 +191,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,14 +214,19 @@ 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) {
             return { ok: false, error: tooMany(field, proposal[field].length, "Keep the ones the next agent needs.") };
         }
     }
-    const parsed = parseHandoffProposal(proposal);
+    // The strict parser sees only the fields this code knows; the carried ones go back afterwards.
+    const sendable = knownFieldsV1(proposal);
+    if (!sendable)
+        return { ok: false, error: readOnlyHandoffMessage(proposal.schemaVersion) };
+    const parsed = parseHandoffProposal(sendable);
     if (!parsed.ok)
         return parsed;
-    return { ok: true, proposal: parsed.value };
+    return { ok: true, proposal: reattachUnknownFields(parsed.value, { ...prior, ...proposal }) };
 }

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);
@@ -345,6 +409,248 @@ export function parseHandoffProposal(value, options = {}) {
     }
     return { ok: true, value: proposal };
 }
+const DECISION_KEYS = new Set(["decision", "reason", "status", "sourceRefs", "supersedes"]);
+const SOURCE_KEYS = new Set(["ref", "label", "kind", "sourceId"]);
+const REPO_KEYS = new Set(["repository", "branch", "commit", "dirty", "worktreePath", "dirtyFingerprint"]);
+/** Required text, trimmed, with no length cap. */
+function readText(value, field) {
+    return shortText(value, field, Number.POSITIVE_INFINITY);
+}
+function readTextList(value, field) {
+    if (!Array.isArray(value))
+        return { ok: false, error: `${field} must be an array` };
+    const items = [];
+    for (const item of value) {
+        const parsed = readText(item, field);
+        if (!parsed.ok)
+            return parsed;
+        items.push(parsed.value);
+    }
+    return { ok: true, value: items };
+}
+/** The own fields of `value` that are not in `known`, in their original order. */
+function unknownFieldsOf(value, known) {
+    return Object.fromEntries(Object.entries(value).filter(([key]) => !known.has(key)));
+}
+function knownFieldsOnly(value, known) {
+    return Object.fromEntries(Object.entries(value).filter(([key]) => known.has(key)));
+}
+function readRepo(value) {
+    if (!isObject(value))
+        return { ok: false, error: "repo must be an object" };
+    const branch = readText(value.branch, "repo.branch");
+    if (!branch.ok)
+        return branch;
+    const commit = readText(value.commit, "repo.commit");
+    if (!commit.ok)
+        return commit;
+    if (typeof value.dirty !== "boolean")
+        return { ok: false, error: "repo.dirty must be a boolean" };
+    const result = { branch: branch.value, commit: commit.value, dirty: value.dirty };
+    for (const field of ["repository", "worktreePath", "dirtyFingerprint"]) {
+        if (value[field] === undefined)
+            continue;
+        const parsed = readText(value[field], `repo.${field}`);
+        if (!parsed.ok)
+            return parsed;
+        result[field] = parsed.value;
+    }
+    return { ok: true, value: result };
+}
+function readEvidence(value) {
+    if (!Array.isArray(value))
+        return { ok: false, error: "evidence must be an array" };
+    const items = [];
+    for (const item of value) {
+        if (!isObject(item))
+            return { ok: false, error: "evidence must be objects" };
+        const command = readText(item.command, "evidence.command");
+        if (!command.ok)
+            return command;
+        if (typeof item.exitCode !== "number" || !Number.isFinite(item.exitCode)) {
+            return { ok: false, error: "evidence.exitCode must be a number" };
+        }
+        const tree = readText(item.tree, "evidence.tree");
+        if (!tree.ok)
+            return tree;
+        if (item.capturedBy !== "agent" && item.capturedBy !== "hook") {
+            return { ok: false, error: "evidence.capturedBy must be agent or hook" };
+        }
+        if (typeof item.capturedAt !== "number" || !Number.isFinite(item.capturedAt)) {
+            return { ok: false, error: "evidence.capturedAt must be a number" };
+        }
+        items.push({
+            command: command.value,
+            exitCode: item.exitCode,
+            tree: tree.value,
+            capturedBy: item.capturedBy,
+            capturedAt: item.capturedAt,
+            ...unknownFieldsOf(item, EVIDENCE_KEYS),
+        });
+    }
+    return { ok: true, value: items };
+}
+/**
+ * Read a handoff leniently: the reader of a stored handoff, which must not refuse a note because
+ * a newer Hypher wrote a field, a longer list, or a longer line than this code would. For any
+ * input `parseHandoffProposal` accepts, the known fields come out equal. A `schemaVersion` above 1
+ * parses but is flagged `readOnly`: the meaning may have changed, so a writer must not save over
+ * it. A missing, non-integer, or below-1 `schemaVersion` is an error.
+ */
+export function parseHandoffProposalLenient(value) {
+    if (!isObject(value))
+        return { ok: false, error: "proposal must be an object" };
+    const schemaVersion = value.schemaVersion;
+    if (typeof schemaVersion !== "number" || !Number.isInteger(schemaVersion) || schemaVersion < 1) {
+        return { ok: false, error: "proposal.schemaVersion must be a whole number, 1 or higher" };
+    }
+    const goal = readText(value.goal, "goal");
+    if (!goal.ok)
+        return goal;
+    const constraints = readTextList(value.constraints, "constraints");
+    if (!constraints.ok)
+        return constraints;
+    const completed = readTextList(value.completed, "completed");
+    if (!completed.ok)
+        return completed;
+    const unverified = readTextList(value.unverified, "unverified");
+    if (!unverified.ok)
+        return unverified;
+    const blockers = readTextList(value.blockers, "blockers");
+    if (!blockers.ok)
+        return blockers;
+    const nextAction = readText(value.nextAction, "nextAction");
+    if (!nextAction.ok)
+        return nextAction;
+    if (!Array.isArray(value.decisions))
+        return { ok: false, error: "decisions must be an array" };
+    const decisions = [];
+    for (const item of value.decisions) {
+        if (!isObject(item))
+            return { ok: false, error: "decisions must be objects" };
+        const decision = readText(item.decision, "decisions.decision");
+        if (!decision.ok)
+            return decision;
+        const reason = readText(item.reason, "decisions.reason");
+        if (!reason.ok)
+            return reason;
+        const entry = { decision: decision.value, reason: reason.value };
+        if (item.status !== undefined) {
+            if (item.status !== "reported" && item.status !== "approved")
+                return { ok: false, error: "decisions.status is invalid" };
+            entry.status = item.status;
+        }
+        if (item.sourceRefs !== undefined) {
+            const sourceRefs = readTextList(item.sourceRefs, "decisions.sourceRefs");
+            if (!sourceRefs.ok)
+                return sourceRefs;
+            entry.sourceRefs = sourceRefs.value;
+        }
+        if (item.supersedes !== undefined) {
+            const supersedes = readText(item.supersedes, "decisions.supersedes");
+            if (!supersedes.ok)
+                return supersedes;
+            entry.supersedes = supersedes.value;
+        }
+        decisions.push({ ...entry, ...unknownFieldsOf(item, DECISION_KEYS) });
+    }
+    if (!Array.isArray(value.sources))
+        return { ok: false, error: "sources must be an array" };
+    const sources = [];
+    for (const item of value.sources) {
+        if (!isObject(item))
+            return { ok: false, error: "sources must be objects" };
+        const ref = readText(item.ref, "sources.ref");
+        if (!ref.ok)
+            return ref;
+        const source = { ref: ref.value };
+        if (item.label !== undefined) {
+            const label = readText(item.label, "sources.label");
+            if (!label.ok)
+                return label;
+            source.label = label.value;
+        }
+        if (item.kind !== undefined) {
+            if (item.kind !== "agent_report" && item.kind !== "capture" && item.kind !== "agent_event") {
+                return { ok: false, error: "sources.kind is invalid" };
+            }
+            source.kind = item.kind;
+        }
+        if (item.sourceId !== undefined) {
+            const sourceId = readText(item.sourceId, "sources.sourceId");
+            if (!sourceId.ok)
+                return sourceId;
+            source.sourceId = sourceId.value;
+        }
+        sources.push({ ...source, ...unknownFieldsOf(item, SOURCE_KEYS) });
+    }
+    const repo = readRepo(value.repo);
+    if (!repo.ok)
+        return repo;
+    let evidence;
+    if (value.evidence !== undefined) {
+        const read = readEvidence(value.evidence);
+        if (!read.ok)
+            return read;
+        evidence = read.value;
+    }
+    const proposal = {
+        schemaVersion,
+        goal: goal.value,
+        constraints: constraints.value,
+        decisions,
+        completed: completed.value,
+        unverified: unverified.value,
+        blockers: blockers.value,
+        nextAction: nextAction.value,
+        sources,
+        repo: repo.value,
+        ...(evidence !== undefined ? { evidence } : {}),
+        ...unknownFieldsOf(value, PROPOSAL_KEYS),
+    };
+    return { ok: true, value: proposal, readOnly: schemaVersion > HANDOFF_PROPOSAL_SCHEMA_VERSION };
+}
+/**
+ * A read handoff as version 1 with only the fields this code knows: unknown fields are dropped at
+ * the top level and on each decision, source, and evidence item. Null above version 1, whose known
+ * fields may no longer mean what they meant. What a writer sends to be checked by the strict parser.
+ */
+export function knownFieldsV1(read) {
+    if (read.schemaVersion !== HANDOFF_PROPOSAL_SCHEMA_VERSION)
+        return null;
+    return {
+        schemaVersion: HANDOFF_PROPOSAL_SCHEMA_VERSION,
+        goal: read.goal,
+        constraints: read.constraints,
+        decisions: read.decisions.map((item) => knownFieldsOnly(item, DECISION_KEYS)),
+        completed: read.completed,
+        unverified: read.unverified,
+        blockers: read.blockers,
+        nextAction: read.nextAction,
+        sources: read.sources.map((item) => knownFieldsOnly(item, SOURCE_KEYS)),
+        repo: knownFieldsOnly(read.repo, REPO_KEYS),
+        ...(read.evidence ? { evidence: read.evidence.map((item) => knownFieldsOnly(item, EVIDENCE_KEYS)) } : {}),
+    };
+}
+/**
+ * Put back, unchanged, the unknown fields `carrier` held: the top-level ones, and those of each
+ * decision, source, and evidence item. `known` must be what a parse of `knownFieldsV1(carrier)`
+ * returns, or any list built from it, with the same items in the same order: the fields go back
+ * by position. Nothing is invented or edited.
+ */
+export function reattachUnknownFields(known, carrier) {
+    const back = (items, from, keys) => items.map((item, index) => {
+        const owner = from?.[index];
+        return isObject(owner) ? { ...item, ...unknownFieldsOf(owner, keys) } : item;
+    });
+    return {
+        ...known,
+        ...unknownFieldsOf(carrier, PROPOSAL_KEYS),
+        decisions: back(known.decisions, carrier.decisions, DECISION_KEYS),
+        sources: back(known.sources, carrier.sources, SOURCE_KEYS),
+        ...(known.evidence ? { evidence: back(known.evidence, carrier.evidence, EVIDENCE_KEYS) } : {}),
+    };
+}
 export function renderHandoffPacket(proposal) {
     const lines = [
         `Goal: ${proposal.goal}`,
@@ -354,6 +660,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}`),
@@ -546,6 +855,30 @@ export function planHandoffDelivery(input) {
         receipt,
     };
 }
+export function headFromRow(projectId, row) {
+    if (!row || typeof row.revision !== "number")
+        return { kind: "none" };
+    const unreadable = (error) => ({ kind: "unreadable", revision: row.revision, error });
+    if (!row.proposal || !row.idempotencyKey || !row.sourceAgent)
+        return unreadable("the stored row is incomplete");
+    const parsed = parseHandoffProposalLenient(row.proposal);
+    if (!parsed.ok)
+        return unreadable(parsed.error);
+    const proposal = knownFieldsV1(parsed.value);
+    if (!proposal)
+        return unreadable(`it is format version ${parsed.value.schemaVersion}, newer than this server reads`);
+    return {
+        kind: "head",
+        head: {
+            projectId,
+            revision: row.revision,
+            idempotencyKey: row.idempotencyKey,
+            proposal,
+            source: row.sourceAgent,
+            savedAt: row.generatedAt,
+        },
+    };
+}
 export function readHandoffCommand(value) {
     if (!isObject(value))
         return { ok: true, command: null };