@litterthanlit/hypher-cli 0.1.8 → 0.2.1

package/src/hooks/index.mjs

@@ -5,11 +5,17 @@
  * once for a seal when the tree changed. Hooks never acknowledge, never block
  * twice in a row, and never block on Hypher being down. In a repository no
  * human linked they record and upload nothing.
+ *
+ * Claude Code alone (Codex parity is M4) also records a checkpoint after the note is read at SessionStart, and
+ * after a tool ran (PostToolUse: a file edit at most every 10 seconds, a command at most every 60), so a session
+ * killed in the middle of a turn still leaves one. PostToolUse reads only `cwd` and `tool_name` from its payload:
+ * the rest is the tool's input, which can be file contents, and is never looked at.
  */
 import { createClient } from "../api.mjs";
 import { linkFor } from "../config.mjs";
 import { enqueue, flushOutbox, shouldFlush } from "../outbox.mjs";
 import { resumeHere } from "../session.mjs";
+import { claimCheckpoint, toolKind } from "../throttle.mjs";
 import { takeSnapshot } from "../snapshot.mjs";
 import { branchState, readWorktreeState, updateWorktreeState, withBranchState } from "../state.mjs";
 import { findSecret } from "../secrets.mjs";
@@ -48,18 +54,38 @@ export function recordCheckpoint(env, snapshot, event, now = Date.now(), agent =
   }, { env, now });
 }
 
-function sealRequest(firstHandoff) {
+/**
+ * What the Stop hook asks for. The words are the same for every project, except that when the last resume found
+ * the decision ledger on, IDs are named: a decision is replaced by its ID, and the lists are said to be added to.
+ */
+function sealRequest(firstHandoff, ledgerOn = false) {
   const goal = firstHandoff ? ' --goal "<the goal>"' : "";
+  const pairs = ledgerOn
+    ? "Add one --decision/--why pair per changed decision (--replaces d-3 names the earlier decision it replaces, by the ID in the note), or none if no decision changed; --next is always needed. What you list is added to the ledger, never replaced: close finished work by listing it under completed (--completed \"…\"). Report only checks you ran (evidence, or --evidence \"<command>=<exit code>\")."
+    : "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>\").";
   return [
     "Hypher: the working tree changed since the last handoff, and no one saved why.",
     "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. Report only checks you ran (evidence, or --evidence \"<command>=<exit code>\").",
+    pairs,
     "It sends only your text, file names, and commit identity. Hypher asks once; if you cannot save now, say so and stop.",
   ].join(" ");
 }
 
+/** The resume statuses whose one line is also shown to the person (`systemMessage`), not only given to the model. */
+const PERSON_SEES = new Set(["unavailable", "not-connected", "unlinked"]);
+
+/** The SessionStart checkpoint, from the snapshot the read already took. It never fails a session start. */
+function recordStartCheckpoint(env, snapshot, agent) {
+  try {
+    if (!snapshot?.repository || !snapshot.tree || !linkFor(snapshot.repository, env)) return;
+    recordCheckpoint(env, snapshot, "SessionStart", Date.now(), agent);
+  } catch {
+    // The note is already read; a checkpoint that could not be written is not worth a failed start.
+  }
+}
+
 async function sessionStart(agent, env, input) {
   const result = await resumeHere({
     env,
@@ -69,7 +95,12 @@ async function sessionStart(agent, env, input) {
     timeoutMs: HOOK_TIMEOUT_MS,
   });
   if (result.status === "not-git" || !result.note) return null;
-  return { hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: result.note } };
+  // After the note is read and rendered, so the note never names its own checkpoint. Queued, not uploaded:
+  // the next session on this computer sends it.
+  if (agent === "claude-code") recordStartCheckpoint(env, result.snapshot, agent);
+  const output = { hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: result.note } };
+  // The person sees these three too: the model alone may never mention that Hypher is not there.
+  return PERSON_SEES.has(result.status) ? { systemMessage: result.note, ...output } : output;
 }
 
 async function stop(agent, env, input, now = Date.now()) {
@@ -96,7 +127,23 @@ async function stop(agent, env, input, now = Date.now()) {
   updateWorktreeState(env, snapshot.root, (current) => withBranchState(current, snapshot.branch, {
     askedAt: now, askedTree: snapshot.tree, blockedLast: true,
   }));
-  return { decision: "block", reason: sealRequest(!state.proposal) };
+  return { decision: "block", reason: sealRequest(!state.proposal, state.ledger?.on === true) };
+}
+
+/**
+ * A tool just ran. Only Claude Code has this hook. The payload carries the tool's input, which can be file
+ * contents, so nothing but `cwd` and `tool_name` is read from it. A call inside its window answers from one
+ * small file, with no git call. Queued, not uploaded: a laptop's next session sends it.
+ */
+async function postToolUse(agent, env, input, now = Date.now()) {
+  if (agent !== "claude-code") return null;
+  const kind = toolKind(input.tool_name);
+  if (!kind) return null;
+  const cwd = typeof input.cwd === "string" && input.cwd ? input.cwd : process.cwd();
+  if (!claimCheckpoint(env, cwd, kind, now)) return null;
+  const found = linkedSnapshot(env, cwd);
+  if (found) recordCheckpoint(env, found.snapshot, "PostToolUse", now, agent);
+  return null;
 }
 
 async function checkpointAndUpload(agent, env, input, event, now = Date.now()) {
@@ -122,6 +169,8 @@ export async function handleAgentHook(agent, event, input, env) {
       return await sessionStart(agent, env, input);
     case "Stop":
       return await stop(agent, env, input);
+    case "PostToolUse":
+      return await postToolUse(agent, env, input);
     case "PreCompact":
     case "SessionEnd":
       return await checkpointAndUpload(agent, env, input, event);

package/src/ledger.mjs

@@ -0,0 +1,134 @@
+/**
+ * Reading the decision ledger (M2 slice 6): `GET /api/cli/ledger`, the one route that lists every
+ * item, dispute, and workstream of a project whose ledger is on. `hypher resume --full` prints what it
+ * returns, and `seal` reads the active decisions once when a decision is replaced by its words.
+ * Only a project in mode `on` ever reaches this; for any other the route says the ledger is not on.
+ */
+import { HypherUnavailable } from "./api.mjs";
+import { noteText } from "../vendor/handoffNote.mjs";
+
+export const LEDGER_PAGE_LIMIT = 100;
+/** Pages read for one list before `--full` stops and says so. A page is 100 rows. */
+export const MAX_FULL_PAGES = 20;
+
+/** The route for one page. `projectId` is the one a human linked; `branch` puts the reader's workstream first. */
+export function ledgerRoute({ projectId, branch, section, kind, cursor, limit = LEDGER_PAGE_LIMIT }) {
+  const params = new URLSearchParams();
+  params.set("section", section);
+  if (kind) params.set("kind", kind);
+  params.set("limit", String(limit));
+  if (cursor) params.set("cursor", cursor);
+  params.set("projectId", projectId);
+  if (branch) params.set("branch", branch);
+  return `/api/cli/ledger?${params.toString()}`;
+}
+
+function refusal(answer) {
+  const json = answer.json ?? {};
+  if (answer.status === 401) return "Hypher did not accept this computer's key. Run `hypher init` again.";
+  if (json.ok === true && json.ledgerOn === false) return json.message ?? "This project's decision ledger is not on.";
+  return typeof json.error === "string" ? json.error : `Hypher answered ${answer.status}`;
+}
+
+/**
+ * The active decisions, newest first, for finding the ID of the one a seal replaces by its words. One page of
+ * 100. Throws `HypherUnavailable` when Hypher cannot be reached.
+ * @returns {Promise<{ ok: true, items: Array<{ id: string, text: string }>, complete: boolean } | { ok: false, error: string }>}
+ */
+export async function readActiveDecisions(client, { projectId, branch }) {
+  const answer = await client.send("GET", ledgerRoute({ projectId, branch, section: "items", kind: "decision" }));
+  const page = answer.json?.items;
+  if (!answer.ok || answer.json?.ok !== true || answer.json.ledgerOn !== true || !page || !Array.isArray(page.list)) {
+    return { ok: false, error: refusal(answer) };
+  }
+  return {
+    ok: true,
+    items: page.list.filter((item) => typeof item?.id === "string" && typeof item.text === "string").map((item) => ({ id: item.id, text: item.text })),
+    complete: page.next === null || page.next === undefined,
+  };
+}
+
+/** Every page of one list, newest first, until `next` is null or the cap. */
+async function readList(client, { projectId, branch, section }) {
+  const rows = [];
+  let cursor;
+  let total = 0;
+  for (let page = 0; page < MAX_FULL_PAGES; page += 1) {
+    const answer = await client.send("GET", ledgerRoute({ projectId, branch, section, cursor }));
+    const body = answer.json;
+    const list = body?.[section];
+    if (!answer.ok || body?.ok !== true || body.ledgerOn !== true || !list || !Array.isArray(list.list)) {
+      return { ok: false, error: refusal(answer) };
+    }
+    rows.push(...list.list);
+    total = typeof list.total === "number" ? list.total : rows.length;
+    cursor = list.next ?? undefined;
+    if (!cursor) return { ok: true, rows, total, cut: false, revision: body.revision, branch: body.branch, counts: body.counts };
+  }
+  return { ok: true, rows, total, cut: true };
+}
+
+/**
+ * Everything the ledger holds for a project in mode `on`: the items, disputes, and workstreams, read in
+ * pages of 100 until each list ends (at most 20 pages a list). Never throws for Hypher being down; says so.
+ * @returns {Promise<{ ok: true, revision: number, branch: string, counts: object, items: any[], disputes: any[], workstreams: any[], cut: string[] } | { ok: false, error: string }>}
+ */
+export async function readWholeLedger(client, { projectId, branch }) {
+  try {
+    const out = { ok: true, revision: 0, branch: branch ?? "", counts: {}, items: [], disputes: [], workstreams: [], cut: [] };
+    for (const section of ["items", "disputes", "workstreams"]) {
+      const list = await readList(client, { projectId, branch, section });
+      if (!list.ok) return list;
+      out[section] = list.rows;
+      if (list.cut) out.cut.push(section);
+      if (typeof list.revision === "number") {
+        out.revision = list.revision;
+        out.branch = list.branch ?? out.branch;
+        out.counts = list.counts ?? out.counts;
+      }
+    }
+    return out;
+  } catch (error) {
+    if (error instanceof HypherUnavailable) return { ok: false, error: "Hypher unavailable. Run `hypher doctor`." };
+    throw error;
+  }
+}
+
+const line = (text, max = 400) => noteText(text, max);
+
+function itemLine(item) {
+  const standing = item.status === "approved" ? "approved" : item.origin === "human" ? `${item.status}, human-sourced` : item.status;
+  const reason = item.reason ? `, because ${line(item.reason)}` : "";
+  const replaces = item.supersedes ? ` Replaces ${line(item.supersedes, 20)}.` : "";
+  const disputed = Array.isArray(item.disputedWith) && item.disputedWith.length ? ` Disputed with ${item.disputedWith.map((id) => line(id, 20)).join(", ")}.` : "";
+  return `- ${line(item.id, 20)} [${line(standing, 40)}] ${line(item.text)}${reason}${replaces}${disputed}`;
+}
+
+function workstreamLines(ws) {
+  const goal = ws.goal ?? (Array.isArray(ws.goals) && ws.goals.length ? ws.goals.map((claim) => claim.text).join(" | ") : "none recorded");
+  const next = Array.isArray(ws.nextActions) && ws.nextActions.length ? ws.nextActions.map((claim) => claim.text).join(" | ") : "none recorded";
+  const tasks = Array.isArray(ws.tasks) ? ws.tasks : [];
+  const blockers = Array.isArray(ws.blockers) ? ws.blockers : [];
+  const evidence = Array.isArray(ws.evidence) ? ws.evidence : [];
+  return [
+    `- ${line(ws.branch, 120)}${ws.current ? " (this branch)" : ""}: goal ${line(goal, 300)}; next ${line(next, 300)}; ${tasks.length} task${tasks.length === 1 ? "" : "s"}, ${blockers.length} blocker${blockers.length === 1 ? "" : "s"}, ${evidence.length} check${evidence.length === 1 ? "" : "s"}`,
+    ...tasks.map((task) => `  - ${line(task.id, 20)} [${line(task.status, 20)}] ${line(task.text)}`),
+    ...blockers.map((blocker) => `  - ${line(blocker.id, 20)} [blocker] ${line(blocker.text)}`),
+    ...evidence.map((item) => `  - check ${JSON.stringify(line(item.command, 200))} exit ${item.exitCode}`),
+  ];
+}
+
+/** The lists `hypher resume --full` prints after the note: one line for each item, dispute, and workstream. */
+export function describeWholeLedger(ledger) {
+  const out = [];
+  out.push(`Decisions and constraints (${ledger.items.length}, retired ones left out):`);
+  out.push(...(ledger.items.length ? ledger.items.map(itemLine) : ["- none"]));
+  out.push("", `Disputes (${ledger.disputes.length}):`);
+  out.push(...(ledger.disputes.length ? ledger.disputes.map((dispute) => `- ${line(dispute.subject, 40)}: ${line(dispute.ask, 700)}`) : ["- none"]));
+  out.push("", `Workstreams (${ledger.workstreams.length}):`);
+  out.push(...(ledger.workstreams.length ? ledger.workstreams.flatMap(workstreamLines) : ["- none"]));
+  if (ledger.cut.length) {
+    out.push("", `Hypher: stopped after ${MAX_FULL_PAGES} pages of ${ledger.cut.join(" and ")}. Name an ID, or ask for a list with the \`read_ledger\` tool.`);
+  }
+  return out.join("\n");
+}

package/src/outbox.mjs

@@ -8,7 +8,7 @@ import { mkdirSync, readdirSync } from "node:fs";
 import path from "node:path";
 import { randomBytes } from "node:crypto";
 import { paths } from "./env.mjs";
-import { readJson, removeFile, writeJson } from "./fsutil.mjs";
+import { readJson, removeFile, sha256, writeJson } from "./fsutil.mjs";
 import { HypherUnavailable } from "./api.mjs";
 
 export const FLUSH_AGE_MS = 5 * 60_000;
@@ -51,6 +51,41 @@ export function enqueue(input, { env = process.env, now = Date.now() } = {}) {
   return item;
 }
 
+function uploadedFile(env, key) {
+  return path.join(paths(env).stateDir, "uploaded", `${sha256(String(key)).slice(0, 20)}.json`);
+}
+
+/** The newest checkpoint Hypher accepted for a key, kept so `hypher status` can say it was uploaded. Never throws. */
+function rememberUploaded(env, item, now) {
+  try {
+    const file = uploadedFile(env, item.key);
+    const before = readJson(file, null);
+    if (typeof before?.body?.capturedAt === "number" && before.body.capturedAt > item.body?.capturedAt) return;
+    writeJson(file, { key: item.key, uploadedAt: now, body: item.body }, { mode: 0o600 });
+  } catch {
+    // Only a convenience for `hypher status`.
+  }
+}
+
+/**
+ * The newest checkpoint on this computer for a repository and branch: waiting in the outbox, or the last one
+ * Hypher accepted. `null` when there is none.
+ * @returns {{ state: "queued" | "uploaded", body: any, queuedAt?: number, uploadedAt?: number } | null}
+ */
+export function newestCheckpoint(env, repository, branch) {
+  const key = `${String(repository).toLowerCase()}#${branch}`;
+  const queued = listOutbox(env)
+    .filter((entry) => entry.item.kind === "checkpoint" && entry.item.key === key)
+    .map((entry) => ({ state: "queued", body: entry.item.body, queuedAt: entry.item.queuedAt }))
+    .sort((a, b) => (b.body?.capturedAt ?? 0) - (a.body?.capturedAt ?? 0))[0];
+  const saved = readJson(uploadedFile(env, key), null);
+  const uploaded = typeof saved?.body?.capturedAt === "number"
+    ? { state: "uploaded", body: saved.body, uploadedAt: saved.uploadedAt }
+    : null;
+  if (queued && (!uploaded || (queued.body?.capturedAt ?? 0) >= uploaded.body.capturedAt)) return queued;
+  return uploaded ?? queued ?? null;
+}
+
 export function oldestAgeMs(env = process.env, now = Date.now()) {
   const [oldest] = listOutbox(env);
   return oldest ? now - oldest.item.queuedAt : 0;
@@ -75,6 +110,7 @@ export async function flushOutbox(client, { env = process.env, now = Date.now(),
     try {
       const response = await client.send("POST", "/api/cli/checkpoints", { body: item.body });
       if (response.ok) {
+        rememberUploaded(env, item, now);
         removeFile(file);
         sent += 1;
         continue;

package/src/session.mjs

@@ -3,6 +3,7 @@
  * `hypher seal`, and (later) the MCP tools all come through here.
  */
 import { createClient, HypherRejected, HypherUnavailable } from "./api.mjs";
+import { readActiveDecisions, readWholeLedger } from "./ledger.mjs";
 import { linkFor } from "./config.mjs";
 import { canonicalJson, sha256 } from "./fsutil.mjs";
 import { flushOutbox } from "./outbox.mjs";
@@ -19,9 +20,19 @@ import {
 } from "../vendor/handoffNote.mjs";
 import { buildSealProposal, CLI_UPDATE_COMMAND, readOnlyHandoffMessage } from "../vendor/handoffSeal.mjs";
 import { parseHandoffProposalLenient } from "../vendor/structuredHandoff.mjs";
+import { composeLedgerNote } from "../vendor/ledgerNoteLocal.mjs";
+import {
+  checkLedgerCall,
+  describeLedgerSave,
+  isUnknownToolError,
+  LEDGER_NOT_ON_CODE,
+  planLedgerSeal,
+} from "../vendor/ledgerSeal.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`";
+/** What a cut list in the note says to do: `--full` prints the rest (mismatch 8 of the M2 design). */
+export const MORE_HINT = "run `hypher resume --full`";
 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. */
@@ -54,9 +65,10 @@ function checkpointFrom(body) {
  * Load the handoff for the repository at cwd, check it against the working
  * tree, record a prepared receipt, and render the note. Never throws for a
  * missing link, credential, or network; returns a status and one line instead.
- * @param {{ env: NodeJS.ProcessEnv, cwd: string, destination: string, sessionId?: string, now?: number, timeoutMs?: number }} options
+ * `full` prints every item, uncut; for a project whose decision ledger is on it also reads the ledger's lists.
+ * @param {{ env: NodeJS.ProcessEnv, cwd: string, destination: string, sessionId?: string, now?: number, timeoutMs?: number, full?: boolean }} options
  */
-export async function resumeHere({ env, cwd, destination, sessionId, now = Date.now(), timeoutMs = 2_500 }) {
+export async function resumeHere({ env, cwd, destination, sessionId, now = Date.now(), timeoutMs = 2_500, full = false }) {
   const snapshot = takeSnapshot(cwd);
   if (!snapshot) return { status: "not-git", note: "" };
   if (!snapshot.repository) {
@@ -102,8 +114,12 @@ export async function resumeHere({ env, cwd, destination, sessionId, now = Date.
   if (prepared?.ok !== true) {
     if (prepared?.code === "no-handoff") {
       const shown = checkpoint && checkpoint.branch === snapshot.branch ? checkpoint : null;
-      updateWorktreeState(env, snapshot.root, (state) => withBranchState({ ...state, ...base, baseRevision: 0, proposal: null, receiptId: null, receiptRevision: null },
-        snapshot.branch, { sealTree: snapshot.tree }));
+      updateWorktreeState(env, snapshot.root, (state) => {
+        // A project with no handoff saves its first one the v1 way, in every mode: no ledger flag.
+        const { ledger: _ledger, ...rest } = state;
+        return withBranchState({ ...rest, ...base, baseRevision: 0, proposal: null, receiptId: null, receiptRevision: null },
+          snapshot.branch, { sealTree: snapshot.tree });
+      });
       return { status: "no-handoff", note: renderNoHandoffNote({ repository: snapshot.repository, projectName: link.projectName, now, checkpoint: shown }), snapshot, checkpoint: shown };
     }
     return { status: "rejected", note: `Hypher: ${prepared?.error ?? "could not load the handoff"}. Run \`hypher doctor\`.`, snapshot };
@@ -116,28 +132,49 @@ export async function resumeHere({ env, cwd, destination, sessionId, now = Date.
   const verdict = truthCheck(snapshot.root, proposal.repo);
   const savedAt = typeof prepared.savedAt === "number" ? prepared.savedAt : undefined;
   const shownCheckpoint = checkpoint && (!savedAt || checkpoint.capturedAt > savedAt) ? checkpoint : null;
-  const note = renderHandoffNote({
-    proposal,
-    revision: prepared.revision,
-    now,
-    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,
+  // The server says a project's ledger is on by sending its note as a field. The signal is that field and
+  // never the words of the text: an installed CLI keeps what it was built to read.
+  const ledgerNote = typeof prepared.ledgerNote === "string" && prepared.ledgerNote !== "" ? prepared.ledgerNote : null;
+  const notice = parsed.readOnly ? readOnlyNotice(proposal.schemaVersion) : null;
+  const note = ledgerNote
+    ? composeLedgerNote({ serverNote: ledgerNote, verdict, checkpoint: shownCheckpoint, now, acknowledge: ACK_HINT, notice })
+    : renderHandoffNote({
+      proposal,
+      revision: prepared.revision,
+      now,
+      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,
+      moreHint: MORE_HINT,
+      full,
+    });
+  // A resume of a branch with no workstream yet is shown the most recently active one, labeled by its branch
+  // (the window's `repo.branch`). The seal then carries that goal onto the new branch.
+  const ledger = ledgerNote
+    ? { on: true, labeledBranch: proposal.repo.branch !== snapshot.branch ? proposal.repo.branch : null, branch: snapshot.branch }
+    : null;
+  updateWorktreeState(env, snapshot.root, (state) => {
+    // Every resume decides the mode afresh: a flag from an earlier resume never outlives it.
+    const { ledger: _ledger, ...rest } = state;
+    return withBranchState({
+      ...rest,
+      ...base,
+      baseRevision: prepared.revision,
+      proposal,
+      receiptId: prepared.receiptId ?? null,
+      // A later save moves baseRevision; the receipt stays tied to the revision that was read.
+      receiptRevision: prepared.revision,
+      ...(ledger ? { ledger } : {}),
+    }, snapshot.branch, { sealTree: snapshot.tree });
   });
-  updateWorktreeState(env, snapshot.root, (state) => withBranchState({
-    ...state,
-    ...base,
-    baseRevision: prepared.revision,
-    proposal,
-    receiptId: prepared.receiptId ?? null,
-    // A later save moves baseRevision; the receipt stays tied to the revision that was read.
-    receiptRevision: prepared.revision,
-  }, snapshot.branch, { sealTree: snapshot.tree }));
+  const wholeLedger = full && ledgerNote
+    ? await readWholeLedger(client, { projectId: link.projectId, branch: snapshot.branch })
+    : null;
   return {
     status: "ready",
     note,
@@ -147,6 +184,7 @@ export async function resumeHere({ env, cwd, destination, sessionId, now = Date.
     projectId: link.projectId,
     checkpoint: shownCheckpoint,
     snapshot,
+    ...(wholeLedger ? { ledger: wholeLedger } : {}),
   };
 }
 
@@ -185,6 +223,22 @@ export async function sealHere({ env, cwd, seal, agent, now = Date.now() }) {
   // 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", " ");
+  const sessionRef = `${agent} session on ${snapshot.branch}, ${iso} UTC`;
+
+  // A project whose ledger the last resume found on saves through it. Only a project on the old path ever
+  // reaches the v1 save below, so what it sends and prints is what it was.
+  if (state.ledger?.on === true) {
+    const outcome = await sealWithOps({ env, snapshot, link, state, prior, seal, agent, now, sessionRef });
+    if (outcome.result) return outcome.result;
+    // The server says the ledger is not on (or has no such tool): this seal is a v1 save. It cannot be one
+    // when an ops save already moved this session on, because the window kept here is then out of date.
+    if (state.ledger.windowStale) {
+      return { ok: false, code: "resume-first", message: "Hypher's decision ledger is not on for this project any more, and this session already saved through it, so the handoff kept here is out of date. Nothing was sent. Run `hypher resume`, then seal again." };
+    }
+  }
+  const ledgerOnly = ledgerOnlyInputMessage(seal);
+  if (ledgerOnly) return { ok: false, code: "not-ledger", message: ledgerOnly };
+
   // 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 = [];
@@ -197,7 +251,7 @@ export async function sealHere({ env, cwd, seal, agent, now = Date.now() }) {
     prior: prior?.ok ? prior.value : null,
     seal: toSeal,
     repo: snapshot.currentRepo,
-    sessionRef: `${agent} session on ${snapshot.branch}, ${iso} UTC`,
+    sessionRef,
     tree: snapshot.tree,
     now,
   });
@@ -252,12 +306,16 @@ export async function sealHere({ env, cwd, seal, agent, now = Date.now() }) {
   }
   const tree = snapshot.tree;
   if (tree) keepHandoffTree(snapshot.root, { branch: snapshot.branch, tree, commit: snapshot.commit });
-  updateWorktreeState(env, snapshot.root, (current) => withBranchState({
-    ...current,
-    baseRevision: result.revision,
-    proposal: saved,
-    agent,
-  }, snapshot.branch, { sealTree: tree }));
+  updateWorktreeState(env, snapshot.root, (current) => {
+    // This was a v1 save, so the ledger flag (if the server turned out not to have one) goes.
+    const { ledger: _ledger, ...rest } = current;
+    return withBranchState({
+      ...rest,
+      baseRevision: result.revision,
+      proposal: saved,
+      agent,
+    }, snapshot.branch, { sealTree: tree });
+  });
   return {
     ok: true,
     code: result.code,
@@ -267,4 +325,123 @@ export async function sealHere({ env, cwd, seal, agent, now = Date.now() }) {
   };
 }
 
+/** The refusal for a seal that sends `open` or `ops` to a project the ledger is not on for. Nothing was sent. */
+export function ledgerOnlyInputMessage(seal) {
+  // A client that fills every optional list with [] (or null) has sent nothing.
+  const given = (value) => value !== undefined && value !== null && !(Array.isArray(value) && value.length === 0);
+  const named = [given(seal.ops) ? "ops" : null, given(seal.open) ? "open" : null].filter(Boolean);
+  if (!named.length) return null;
+  const how = [
+    named.includes("open") ? "Put work that is still open under unverified." : null,
+    named.includes("ops") ? "To replace a decision, give the new one with --replaces." : null,
+  ].filter(Boolean).join(" ");
+  return `Refused: ${named.join(" and ")} apply only when the note says "Ledger: on", and this project saves handoffs the old way. Nothing was sent. ${how}`;
+}
+
+/**
+ * A save of a project whose ledger is on: one `record_ops` call built from the seal (the mapping and every check
+ * are `vendor/ledgerSeal.mjs`), based on the revision this session read. Returns `{ result }`, which is final
+ * (saved or refused), or `{ result: null }` when the server says the ledger is not on or has no such tool; the
+ * seal is then a v1 save. Hypher unavailable and a refusal by the ledger are final: nothing was saved, and
+ * Hypher never writes around the ledger.
+ */
+async function sealWithOps({ env, snapshot, link, state, prior, seal, agent, now, sessionRef }) {
+  const refused = (code, message) => ({ result: { ok: false, code, message } });
+  const unavailable = () => (inCodexSandbox(env)
+    ? refused("sandboxed", SANDBOX_LINE)
+    : refused("unavailable", "Hypher unavailable; nothing was saved. Run `hypher doctor`, then seal again."));
+  const notConnected = () => (inCodexSandbox(env)
+    ? refused("sandboxed", SANDBOX_LINE)
+    : refused("not-connected", "This computer is not connected. Run `hypher init`."));
+
+  // Checks are bound to the working-tree hash at this save. Without one, the save still goes; 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.");
+  }
+  // The branch this session resumed on had no workstream, so it was shown another one's; the goal is carried onto it.
+  const labeled = Boolean(state.ledger.labeledBranch) && (state.ledger.branch ?? snapshot.branch) === snapshot.branch;
+  const input = { seal: toSeal, prior: prior?.ok ? prior.value : null, labeled, sessionRef, tree: snapshot.tree, now };
+  const client = createClient({ env, timeoutMs: 10_000 });
+
+  let planned = planLedgerSeal(input);
+  if (!planned.ok && planned.needsDecisions) {
+    // A decision is replaced by its words: its ID is read once from the ledger.
+    if (!client.apiKey) return notConnected();
+    let decisions;
+    try {
+      decisions = await readActiveDecisions(client, { projectId: link.projectId, branch: snapshot.branch });
+    } catch (error) {
+      if (error instanceof HypherUnavailable) return unavailable();
+      throw error;
+    }
+    if (!decisions.ok) {
+      return refused("rejected", `Hypher could not list the decisions to find the one to replace (${decisions.error}). Nothing was sent. Name it by its ID (d-3) and seal again.`);
+    }
+    planned = planLedgerSeal({ ...input, decisions: decisions.items, decisionsComplete: decisions.complete });
+  }
+  if (!planned.ok) return refused("invalid", planned.error);
+  const checked = checkLedgerCall({
+    source: agent,
+    projectId: link.projectId,
+    baseRevision: state.baseRevision,
+    repo: snapshot.currentRepo,
+    ops: planned.ops,
+    labels: planned.labels,
+  });
+  if (!checked.ok) return refused("invalid", checked.error);
+  if (!client.apiKey) return notConnected();
+
+  // No idempotency key: the server makes one from the base, the branch, and the ops, and the checks and the session
+  // label are stamped to the minute, so a retry within the minute is the same call and replays.
+  let answer;
+  try {
+    answer = (await client.tool("record_ops", checked.args)).structured;
+  } catch (error) {
+    if (error instanceof HypherUnavailable) return unavailable();
+    if (error instanceof HypherRejected) {
+      if (isUnknownToolError(error.message, error.body?.rpcCode)) return { result: null };
+      return refused("rejected", error.message);
+    }
+    throw error;
+  }
+  if (answer?.code === LEDGER_NOT_ON_CODE) return { result: null };
+  if (answer?.ok !== true || typeof answer.revision !== "number") {
+    const error = String(answer?.error ?? "unknown error");
+    const behind = typeof answer?.headRevision === "number" && answer.headRevision < state.baseRevision
+      ? " Run `hypher resume`, then seal again."
+      : "";
+    return refused(answer?.code ?? "rejected", `Hypher refused the ledger update: ${error}${/nothing was (?:saved|recorded|written)/i.test(error) ? "" : " Nothing was saved."}${behind}`);
+  }
+
+  const tree = snapshot.tree;
+  if (tree) keepHandoffTree(snapshot.root, { branch: snapshot.branch, tree, commit: snapshot.commit });
+  // The window kept here is the one this session read; this save changed the ledger past it, so it is stale
+  // until the next resume. The branch now has its own workstream, so nothing is carried onto it again.
+  updateWorktreeState(env, snapshot.root, (current) => withBranchState({
+    ...current,
+    baseRevision: answer.revision,
+    agent,
+    ledger: { on: true, labeledBranch: null, branch: snapshot.branch, windowStale: true },
+  }, snapshot.branch, { sealTree: tree }));
+  return {
+    result: {
+      ok: true,
+      code: answer.code,
+      revision: answer.revision,
+      projectName: link.projectName,
+      message: describeLedgerSave({
+        answer,
+        labels: planned.labels,
+        base: state.baseRevision,
+        projectName: link.projectName ?? "this project",
+        branch: snapshot.branch,
+        extraLines: lines,
+      }),
+    },
+  };
+}
+
 export { handoffTreeOf };

package/src/throttle.mjs

@@ -0,0 +1,46 @@
+/**
+ * How often a PostToolUse hook may record a checkpoint (M3 slice 3). One small file per working directory
+ * holds the time of the last checkpoint for each kind of tool, so a call that is too soon answers from that
+ * file alone, with no git call. A file edit may record every 10 seconds, a command every 60, each counted
+ * on its own: a command does not wait for an edit, nor an edit for a command.
+ */
+import path from "node:path";
+import { paths } from "./env.mjs";
+import { readJson, sha256, writeJson } from "./fsutil.mjs";
+
+export const EDIT_WINDOW_MS = 10_000;
+export const BASH_WINDOW_MS = 60_000;
+
+const EDIT_TOOLS = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]);
+
+/** "edit" for a tool that changes files, "bash" for a command, else null (no checkpoint). */
+export function toolKind(toolName) {
+  if (typeof toolName !== "string") return null;
+  if (EDIT_TOOLS.has(toolName)) return "edit";
+  return toolName === "Bash" ? "bash" : null;
+}
+
+const WINDOWS = { edit: EDIT_WINDOW_MS, bash: BASH_WINDOW_MS };
+
+function throttleFile(env, cwd) {
+  return path.join(paths(env).stateDir, "throttle", `${sha256(String(cwd)).slice(0, 20)}.json`);
+}
+
+/**
+ * True, and counted, when a checkpoint of this kind may be recorded now; false when the last one is too
+ * recent. A last time in the future (a clock that moved back) does not block.
+ * @param {NodeJS.ProcessEnv} env
+ * @param {string} cwd
+ * @param {"edit" | "bash"} kind
+ * @param {number} now
+ */
+export function claimCheckpoint(env, cwd, kind, now) {
+  const file = throttleFile(env, cwd);
+  const saved = readJson(file, null);
+  const last = saved && typeof saved === "object" && !Array.isArray(saved) ? saved : {};
+  const at = last[kind];
+  if (typeof at === "number" && now >= at && now - at < WINDOWS[kind]) return false;
+  // Counted before the git work, so two hooks started together do not both record.
+  writeJson(file, { ...last, [kind]: now }, { mode: 0o600 });
+  return true;
+}