@litterthanlit/hypher-cli 0.1.8 → 0.2.0

package/vendor/ledgerOps.mjs

@@ -0,0 +1,387 @@
+// Generated from hypher-web/shared/ledgerOps.ts by script/sync-hypher-shared.mjs. Do not edit.
+/**
+ * Ops of the decision ledger (M2 slice 2): the shapes an agent sends, how they are checked, and the
+ * pure helpers around one call. Pure TypeScript with no database, network, Node, Convex, or Next.js,
+ * so the CLI can vendor it later. Nothing calls this yet.
+ *
+ * `type` is a string checked here, never a closed database literal. An op type this code does not
+ * know is kept as unsupported and not applied (the log can replay it once the fold learns it). A
+ * malformed known op refuses the whole call. Text limits match v1: 280 characters.
+ */
+import { findSecretInValue } from "./secretScan.mjs";
+import { canonicalJson, defaultIdempotencyKey, parseRepoSnapshot, sha256Hex } from "./structuredHandoff.mjs";
+/** Decision, reason, constraint, task, blocker, and next action text. `MAX_SHORT` in structuredHandoff. */
+export const LEDGER_MAX_TEXT = 280;
+/** `MAX_GOAL` in structuredHandoff. */
+export const LEDGER_MAX_GOAL = 600;
+/** `MAX_COMMAND` in structuredHandoff. */
+export const LEDGER_MAX_COMMAND = 300;
+export const LEDGER_MAX_OPS_PER_CALL = 50;
+export const LEDGER_MAX_SOURCE_REFS = 8;
+const MAX_KEY = 200;
+const MAX_TYPE = 80;
+/** An op this code does not know is logged as it came, so its size is bounded. */
+const MAX_UNSUPPORTED_JSON = 4_000;
+export const LEDGER_OP_TYPES = [
+    "decision.add",
+    "decision.supersede",
+    "decision.retire",
+    "decision.amend",
+    "decision.approve",
+    "constraint.add",
+    "constraint.retire",
+    "task.upsert",
+    "task.drop",
+    "blocker.add",
+    "blocker.resolve",
+    "evidence.record",
+    "seal",
+];
+function fail(error) {
+    return { ok: false, error };
+}
+function isObject(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function unknownKey(value, allowed) {
+    for (const key of Object.keys(value)) {
+        if (!allowed.includes(key))
+            return key;
+    }
+    return null;
+}
+function shortText(value, field, max = LEDGER_MAX_TEXT) {
+    if (typeof value !== "string")
+        return fail(`${field} must be a string`);
+    const cleaned = value.trim();
+    if (!cleaned)
+        return fail(`${field} is required`);
+    if (cleaned.length > max)
+        return fail(`${field} is too long`);
+    return { ok: true, value: cleaned };
+}
+function optionalRefs(value, field) {
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    if (!Array.isArray(value))
+        return fail(`${field} must be an array`);
+    if (value.length < 1)
+        return fail(`${field} is required`);
+    if (value.length > LEDGER_MAX_SOURCE_REFS)
+        return fail(`${field} has too many items`);
+    const refs = [];
+    for (const item of value) {
+        const parsed = shortText(item, field);
+        if (!parsed.ok)
+            return parsed;
+        if (!refs.includes(parsed.value))
+            refs.push(parsed.value);
+    }
+    return { ok: true, value: refs };
+}
+const ID_PATTERNS = {
+    d: /^d-[1-9]\d{0,8}$/,
+    c: /^c-[1-9]\d{0,8}$/,
+    t: /^t-[1-9]\d{0,8}$/,
+    b: /^b-[1-9]\d{0,8}$/,
+};
+const CALL_REF = /^\$(0|[1-9]\d?)$/;
+const TREE_HASH = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+function idField(value, field, kind, allowCallRef = false) {
+    if (typeof value !== "string")
+        return fail(`${field} must be a string`);
+    const cleaned = value.trim();
+    if (ID_PATTERNS[kind].test(cleaned))
+        return { ok: true, value: cleaned };
+    if (allowCallRef && CALL_REF.test(cleaned))
+        return { ok: true, value: cleaned };
+    return fail(`${field} must look like ${kind}-7`);
+}
+/** The call-local index in `$n`, or null for a display ID. */
+export function callRefIndex(id) {
+    const match = CALL_REF.exec(id);
+    return match ? Number(match[1]) : null;
+}
+const PLACEHOLDER_PREFIX = "FILL:";
+function findPlaceholderIn(value, path) {
+    if (typeof value === "string")
+        return value.trim().startsWith(PLACEHOLDER_PREFIX) ? path : null;
+    if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index += 1) {
+            const found = findPlaceholderIn(value[index], `${path}[${index}]`);
+            if (found)
+                return found;
+        }
+        return null;
+    }
+    if (isObject(value)) {
+        for (const [key, item] of Object.entries(value)) {
+            const found = findPlaceholderIn(item, `${path}.${key}`);
+            if (found)
+                return found;
+        }
+    }
+    return null;
+}
+function parseKnown(type, value, field) {
+    const noExtra = (allowed) => {
+        const extra = unknownKey(value, allowed);
+        return extra ? `${field}.${extra} is not allowed` : null;
+    };
+    switch (type) {
+        case "decision.add": {
+            const extra = noExtra(["type", "text", "reason", "sourceRefs"]);
+            if (extra)
+                return fail(extra);
+            const text = shortText(value.text, `${field}.text`);
+            if (!text.ok)
+                return text;
+            const reason = shortText(value.reason, `${field}.reason`);
+            if (!reason.ok)
+                return reason;
+            const refs = optionalRefs(value.sourceRefs, `${field}.sourceRefs`);
+            if (!refs.ok)
+                return refs;
+            return { ok: true, value: { type, text: text.value, reason: reason.value, ...(refs.value ? { sourceRefs: refs.value } : {}) } };
+        }
+        case "decision.supersede": {
+            const extra = noExtra(["type", "id", "text", "reason", "sourceRefs"]);
+            if (extra)
+                return fail(extra);
+            const id = idField(value.id, `${field}.id`, "d");
+            if (!id.ok)
+                return id;
+            const text = shortText(value.text, `${field}.text`);
+            if (!text.ok)
+                return text;
+            const reason = shortText(value.reason, `${field}.reason`);
+            if (!reason.ok)
+                return reason;
+            const refs = optionalRefs(value.sourceRefs, `${field}.sourceRefs`);
+            if (!refs.ok)
+                return refs;
+            return { ok: true, value: { type, id: id.value, text: text.value, reason: reason.value, ...(refs.value ? { sourceRefs: refs.value } : {}) } };
+        }
+        case "decision.retire":
+        case "constraint.retire": {
+            const extra = noExtra(["type", "id", "reason"]);
+            if (extra)
+                return fail(extra);
+            const id = idField(value.id, `${field}.id`, type === "decision.retire" ? "d" : "c");
+            if (!id.ok)
+                return id;
+            const reason = shortText(value.reason, `${field}.reason`);
+            if (!reason.ok)
+                return reason;
+            return { ok: true, value: { type, id: id.value, reason: reason.value } };
+        }
+        case "decision.amend": {
+            const extra = noExtra(["type", "id", "reason"]);
+            if (extra)
+                return fail(extra);
+            const id = idField(value.id, `${field}.id`, "d");
+            if (!id.ok)
+                return id;
+            const reason = shortText(value.reason, `${field}.reason`);
+            if (!reason.ok)
+                return reason;
+            return { ok: true, value: { type, id: id.value, reason: reason.value } };
+        }
+        case "decision.approve": {
+            const extra = noExtra(["type", "id", "captureRef"]);
+            if (extra)
+                return fail(extra);
+            const id = idField(value.id, `${field}.id`, "d", true);
+            if (!id.ok)
+                return id;
+            const captureRef = shortText(value.captureRef, `${field}.captureRef`);
+            if (!captureRef.ok)
+                return captureRef;
+            return { ok: true, value: { type, id: id.value, captureRef: captureRef.value } };
+        }
+        case "constraint.add": {
+            const extra = noExtra(["type", "text", "sourceRefs"]);
+            if (extra)
+                return fail(extra);
+            const text = shortText(value.text, `${field}.text`);
+            if (!text.ok)
+                return text;
+            const refs = optionalRefs(value.sourceRefs, `${field}.sourceRefs`);
+            if (!refs.ok)
+                return refs;
+            return { ok: true, value: { type, text: text.value, ...(refs.value ? { sourceRefs: refs.value } : {}) } };
+        }
+        case "task.upsert": {
+            const extra = noExtra(["type", "id", "text", "status"]);
+            if (extra)
+                return fail(extra);
+            let id;
+            if (value.id !== undefined) {
+                const parsedId = idField(value.id, `${field}.id`, "t");
+                if (!parsedId.ok)
+                    return parsedId;
+                id = parsedId.value;
+            }
+            const text = shortText(value.text, `${field}.text`);
+            if (!text.ok)
+                return text;
+            if (value.status !== "open" && value.status !== "unverified" && value.status !== "done") {
+                return fail(`${field}.status must be open, unverified, or done`);
+            }
+            return { ok: true, value: { type, ...(id ? { id } : {}), text: text.value, status: value.status } };
+        }
+        case "task.drop":
+        case "blocker.resolve": {
+            const extra = noExtra(["type", "id"]);
+            if (extra)
+                return fail(extra);
+            const id = idField(value.id, `${field}.id`, type === "task.drop" ? "t" : "b");
+            if (!id.ok)
+                return id;
+            return { ok: true, value: { type, id: id.value } };
+        }
+        case "blocker.add": {
+            const extra = noExtra(["type", "text"]);
+            if (extra)
+                return fail(extra);
+            const text = shortText(value.text, `${field}.text`);
+            if (!text.ok)
+                return text;
+            return { ok: true, value: { type, text: text.value } };
+        }
+        case "evidence.record": {
+            const extra = noExtra(["type", "command", "exitCode", "tree", "capturedAt", "capturedBy"]);
+            if (extra)
+                return fail(extra);
+            const command = shortText(value.command, `${field}.command`, LEDGER_MAX_COMMAND);
+            if (!command.ok)
+                return command;
+            if (/[\r\n\u2028\u2029]/.test(command.value))
+                return fail(`${field}.command must be one line`);
+            if (typeof value.exitCode !== "number" || !Number.isInteger(value.exitCode) || value.exitCode < 0 || value.exitCode > 255) {
+                return fail(`${field}.exitCode must be a whole number from 0 to 255`);
+            }
+            if (typeof value.tree !== "string" || !TREE_HASH.test(value.tree)) {
+                return fail(`${field}.tree must be a 40 or 64 character lowercase hex hash`);
+            }
+            if (typeof value.capturedAt !== "number" || !Number.isInteger(value.capturedAt) || value.capturedAt < 1) {
+                return fail(`${field}.capturedAt must be a positive whole number of milliseconds`);
+            }
+            if (value.capturedBy !== undefined && value.capturedBy !== "agent") {
+                return fail(`${field}.capturedBy must be agent`);
+            }
+            return { ok: true, value: { type, command: command.value, exitCode: value.exitCode, tree: value.tree, capturedAt: value.capturedAt } };
+        }
+        case "seal": {
+            const extra = noExtra(["type", "goal", "nextAction"]);
+            if (extra)
+                return fail(extra);
+            let goal;
+            if (value.goal !== undefined) {
+                const parsedGoal = shortText(value.goal, `${field}.goal`, LEDGER_MAX_GOAL);
+                if (!parsedGoal.ok)
+                    return parsedGoal;
+                goal = parsedGoal.value;
+            }
+            const nextAction = shortText(value.nextAction, `${field}.nextAction`);
+            if (!nextAction.ok)
+                return nextAction;
+            return { ok: true, value: { type, ...(goal !== undefined ? { goal } : {}), nextAction: nextAction.value } };
+        }
+        default:
+            return null;
+    }
+}
+/**
+ * Check one op. A known type is checked field by field and rebuilt from its named fields, so a typo
+ * or a smuggled field is refused by name. An unknown type is kept as sent (`unsupported`, bounded in
+ * size). Every op, known or not, goes through the secret scan and the `FILL:` guard.
+ */
+export function parseLedgerOp(value, field = "op") {
+    if (!isObject(value))
+        return fail(`${field} must be an object`);
+    const type = value.type;
+    if (typeof type !== "string" || !type.trim() || type.length > MAX_TYPE)
+        return fail(`${field}.type is required`);
+    const known = parseKnown(type, value, field);
+    let result;
+    if (known) {
+        if (!known.ok)
+            return known;
+        result = { kind: "known", op: known.value };
+    }
+    else {
+        let size;
+        try {
+            size = JSON.stringify(value).length;
+        }
+        catch {
+            return fail(`${field} must be plain JSON`);
+        }
+        if (size > MAX_UNSUPPORTED_JSON)
+            return fail(`${field} is too large`);
+        result = { kind: "unsupported", op: value };
+    }
+    const placeholder = findPlaceholderIn(result.op, field);
+    if (placeholder)
+        return fail(`${placeholder} still contains a FILL: placeholder`);
+    // Saved text reaches every later session, so a secret is refused, never stored.
+    const secret = findSecretInValue(result.op, field);
+    if (secret)
+        return fail(`${secret.field} looks like ${secret.shape}. Remove it; Hypher never stores secrets.`);
+    return { ok: true, value: result };
+}
+/**
+ * Check a whole call. One malformed known op refuses the call; nothing is partly applied. Known ops
+ * come back rebuilt from their named fields, unknown ones as sent.
+ */
+export function parseLedgerCall(value) {
+    if (!isObject(value))
+        return fail("call must be an object");
+    const extra = unknownKey(value, ["baseRevision", "idempotencyKey", "repo", "ops"]);
+    if (extra)
+        return fail(`call.${extra} is not allowed`);
+    const base = value.baseRevision;
+    if (typeof base !== "number" || !Number.isInteger(base) || base < 0 || base > 1_000_000) {
+        return fail("baseRevision must be a non-negative integer");
+    }
+    let idempotencyKey;
+    if (value.idempotencyKey !== undefined) {
+        const key = shortText(value.idempotencyKey, "idempotencyKey", MAX_KEY);
+        if (!key.ok)
+            return key;
+        idempotencyKey = key.value;
+    }
+    const repo = parseRepoSnapshot(value.repo);
+    if (!repo.ok)
+        return repo;
+    const repoSecret = findSecretInValue(repo.value, "repo");
+    if (repoSecret)
+        return fail(`${repoSecret.field} looks like ${repoSecret.shape}. Remove it; Hypher never stores secrets.`);
+    if (!Array.isArray(value.ops))
+        return fail("ops must be an array");
+    if (value.ops.length === 0)
+        return fail("ops is required");
+    if (value.ops.length > LEDGER_MAX_OPS_PER_CALL) {
+        return fail(`A call carries at most ${LEDGER_MAX_OPS_PER_CALL} ops; this one has ${value.ops.length}.`);
+    }
+    const ops = [];
+    for (let index = 0; index < value.ops.length; index += 1) {
+        const parsed = parseLedgerOp(value.ops[index], `ops[${index}]`);
+        if (!parsed.ok)
+            return parsed;
+        ops.push(parsed.value.op);
+    }
+    return { ok: true, value: { baseRevision: base, ...(idempotencyKey ? { idempotencyKey } : {}), repo: repo.value, ops } };
+}
+/**
+ * A hash of the body of a call: the revision it rebases from, the branch, and the ops. The same key
+ * with a different hash is refused; the same key with the same hash is a retry.
+ */
+export function ledgerCallContentHash(call) {
+    return sha256Hex(canonicalJson({ baseRevision: call.baseRevision, branch: call.repo.branch, ops: call.ops }));
+}
+/** The key for a call that did not name one: a hash of the base revision and the ops, as the CLI does for v1. */
+export function ledgerCallKey(call) {
+    return call.idempotencyKey ?? defaultIdempotencyKey(call.baseRevision, { branch: call.repo.branch, ops: call.ops });
+}

package/vendor/ledgerSeal.mjs

@@ -0,0 +1,283 @@
+// Generated from hypher-web/shared/ledgerSeal.ts by script/sync-hypher-shared.mjs. Do not edit.
+/**
+ * What `seal` means in a project whose decision ledger is on (M2 slice 6): the CLI's `seal` input (a goal,
+ * a next action, decisions with why, constraints, completed, unverified, open, blockers, checks, and raw
+ * ops) turned into one `record_ops` call, and the server's answer turned into the words the agent reads.
+ * Pure TypeScript with no database, network, Node, Convex, or Next.js, vendored into the CLI
+ * (`script/sync-hypher-shared.mjs`) so the hosted tests and the installed copy run the same code.
+ *
+ * Installed CLIs never update themselves, so what this sends is permanent: it sends only ops the
+ * ledger already defines (`ledgerOps.ts`), never an origin, a status, or an approval of its own, and the
+ * call is checked locally by `parseLedgerCall` (secrets, `FILL:`, lengths, 50 ops, 25,000 bytes) before
+ * anything leaves the machine.
+ *
+ * The order of the ops follows `planV1Save` in `ledgerV1.ts`: decisions and constraints first, then the
+ * `seal` (a new goal moves the branch's old tasks, blockers, and checks out of the note), then the tasks,
+ * blockers, and checks this save says stand under it, then any raw ops the agent sent.
+ *
+ * Lists are additive. A ledger holds more than one save's worth, so leaving a line out of `completed`,
+ * `unverified`, `open`, or `blockers` removes nothing. A task is closed by listing it under `completed`,
+ * a decision is replaced by naming its ID, and anything else is a raw op (`ops`), for example
+ * `decision.retire`, `blocker.resolve`, or `task.drop`.
+ */
+import { noteText } from "./handoffNote.mjs";
+import { evidenceFromSeal } from "./handoffSeal.mjs";
+import { LEDGER_MAX_TEXT, parseLedgerCall } from "./ledgerOps.mjs";
+/** A body larger than this does not fit `/api/mcp` (`MAX_BODY_BYTES` in the route). */
+export const LEDGER_CALL_MAX_BYTES = 25_000;
+/** The code of the answer a server gives for a project whose ledger is not on (`ledgerNotOnMessage` in ledgerApi.ts). */
+export const LEDGER_NOT_ON_CODE = "ledger-not-on";
+const lower = (value) => value.toLowerCase();
+function clean(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function cleanList(values) {
+    return Array.isArray(values) ? values.map(clean).filter(Boolean) : [];
+}
+/** The first words of a text, for the line that says what became of it. */
+function short(text, max = 60) {
+    const flat = noteText(text, 400);
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+const DISPLAY_ID = /^d-[1-9]\d{0,8}$/i;
+const WINDOW_NUMBER = /^D\d+$/i;
+/** The numbering of the old note (D1, D2…), which a project with a ledger no longer has. */
+export function windowNumberHint(ref) {
+    return `${ref} is a number from the old note, and decisions in this project have IDs like d-3. Use the ID shown in the note ("d-3: …"), or part of the old decision's words.`;
+}
+/**
+ * The active decision a text names: the exact text, or a unique case-insensitive part of it (three
+ * characters or more). `items` is newest first, as the read route lists them. When the list was cut at
+ * its page size, a miss says so and points at the ID.
+ */
+export function resolveDecisionText(items, reference, complete = true) {
+    const ref = reference.trim();
+    const wanted = lower(ref);
+    const exact = items.find((item) => lower(item.text.trim()) === wanted);
+    if (exact)
+        return { ok: true, id: exact.id };
+    const partial = wanted.length >= 3 ? items.filter((item) => lower(item.text).includes(wanted)) : [];
+    if (partial.length === 1)
+        return { ok: true, id: partial[0].id };
+    const list = (rows) => rows.slice(0, 8).map((item) => `${item.id} "${short(item.text, 50)}"`).join(", ") + (rows.length > 8 ? `, and ${rows.length - 8} more` : "");
+    if (partial.length > 1)
+        return { ok: false, error: `"${short(ref, 50)}" matches ${partial.length} decisions (${list(partial)}); use the decision's ID, for example ${partial[0].id}.` };
+    const cut = complete ? "" : " Only the newest decisions were checked; use the decision's ID (`hypher resume --full` lists them).";
+    return { ok: false, error: `No active decision matches "${short(ref, 50)}".${items.length ? ` Decisions: ${list(items)}.` : " There are no decisions to replace."}${cut}` };
+}
+function fail(error) {
+    return { ok: false, error };
+}
+/**
+ * The ops for one seal. Nothing is sent from here. When a decision is replaced by its words, the active
+ * decisions are needed to find its ID: the first call answers `needsDecisions`, the caller reads them
+ * once and calls again with `decisions`.
+ *
+ * @param input.prior the window this session resumed from (null when none was kept)
+ * @param input.labeled true when the resume was for a branch with no workstream yet: it was shown the most
+ *   recently active one, so its goal is carried onto the new branch when the seal gives none
+ * @param input.sessionRef the label of this session; it is the source of every decision
+ * @param input.now the time of the save; checks are stamped with it rounded down to the minute, so an
+ *   identical retry within the minute is the same call
+ */
+export function planLedgerSeal(input) {
+    const { seal, prior } = input;
+    const nextAction = clean(seal.nextAction);
+    if (!nextAction)
+        return fail("The next action is required: nextAction (in a shell, --next \"…\").");
+    const extra = seal.ops === undefined || seal.ops === null ? [] : seal.ops;
+    if (!Array.isArray(extra))
+        return fail("ops must be a list of ledger ops, each an object with a type, for example { \"type\": \"decision.retire\", \"id\": \"d-3\", \"reason\": \"…\" }.");
+    for (let index = 0; index < extra.length; index += 1) {
+        const op = extra[index];
+        if (!op || typeof op !== "object" || Array.isArray(op) || typeof op.type !== "string") {
+            return fail(`ops[${index}] must be an object with a type, for example { "type": "decision.retire", "id": "d-3", "reason": "…" }.`);
+        }
+    }
+    // First pass: everything that can be refused without reading the ledger.
+    let needsLookup = false;
+    for (const raw of seal.decisions ?? []) {
+        const text = clean(raw?.decision);
+        if (!text)
+            continue;
+        if (!clean(raw.why))
+            return fail(`Say why for "${text}" (--why "…" right after --decision).`);
+        const ref = clean(raw.replaces);
+        if (!ref || DISPLAY_ID.test(ref))
+            continue;
+        if (WINDOW_NUMBER.test(ref))
+            return fail(windowNumberHint(ref));
+        needsLookup = true;
+    }
+    if (needsLookup && !input.decisions)
+        return { ok: false, needsDecisions: true };
+    const ops = [];
+    const labels = [];
+    const push = (op, label) => {
+        ops.push(op);
+        labels.push(label);
+    };
+    // Decisions. A restatement of one the window already holds changes nothing, as in v1. The session's label is the
+    // source of each, cut to the length a source may have (v1 cuts it the same way).
+    const sessionRef = clean(input.sessionRef).slice(0, LEDGER_MAX_TEXT);
+    const known = new Set((prior?.decisions ?? []).map((item) => lower(item.decision.trim())));
+    const replaced = new Set();
+    for (const raw of seal.decisions ?? []) {
+        const text = clean(raw?.decision);
+        if (!text)
+            continue;
+        const reason = clean(raw.why);
+        const ref = clean(raw.replaces);
+        const label = `decision "${short(text)}"`;
+        if (ref) {
+            let id;
+            if (DISPLAY_ID.test(ref)) {
+                id = lower(ref);
+            }
+            else {
+                const found = resolveDecisionText(input.decisions ?? [], ref, input.decisionsComplete ?? true);
+                if (!found.ok)
+                    return found;
+                id = found.id;
+            }
+            if (replaced.has(id))
+                return fail(`${id} is replaced twice.`);
+            replaced.add(id);
+            push({ type: "decision.supersede", id, text, reason, sourceRefs: [sessionRef] }, label);
+        }
+        else {
+            if (known.has(lower(text)))
+                continue;
+            known.add(lower(text));
+            push({ type: "decision.add", text, reason, sourceRefs: [sessionRef] }, label);
+        }
+    }
+    // Constraints are only added. One the window already holds is not sent again.
+    const constraints = new Set((prior?.constraints ?? []).map((item) => lower(item.trim())));
+    for (const text of cleanList(seal.constraints)) {
+        if (constraints.has(lower(text)))
+            continue;
+        constraints.add(lower(text));
+        push({ type: "constraint.add", text }, `constraint "${short(text)}"`);
+    }
+    // The seal. On a branch with no workstream the goal of the one the note showed is carried, so the new
+    // workstream has a goal; a goal the agent gives always wins, and without either none is sent.
+    const given = clean(seal.goal);
+    const goal = given || (input.labeled ? clean(prior?.goal) : "");
+    push({ type: "seal", ...(goal ? { goal } : {}), nextAction }, given ? "goal and next action" : "next action");
+    // Tasks. The fold matches an active task by its words on this branch and sets its status, so a line
+    // under `completed` closes one that was open or unverified. A line in two lists takes the later one.
+    const tasks = new Map();
+    for (const text of cleanList(seal.open))
+        tasks.set(lower(text), { text, status: "open" });
+    for (const text of cleanList(seal.unverified))
+        tasks.set(lower(text), { text, status: "unverified" });
+    for (const text of cleanList(seal.completed))
+        tasks.set(lower(text), { text, status: "done" });
+    for (const task of tasks.values())
+        push({ type: "task.upsert", text: task.text, status: task.status }, `task "${short(task.text)}" (${task.status})`);
+    const blockers = new Set();
+    for (const text of cleanList(seal.blockers)) {
+        if (blockers.has(lower(text)))
+            continue;
+        blockers.add(lower(text));
+        push({ type: "blocker.add", text }, `blocker "${short(text)}"`);
+    }
+    // Checks, bound to the tree at the save and stamped to the minute.
+    const stamped = Math.floor(input.now / 60_000) * 60_000;
+    const reported = evidenceFromSeal(seal.evidence, input.tree, stamped);
+    if (!reported.ok)
+        return fail(reported.error);
+    for (const item of reported.items) {
+        push({ type: "evidence.record", command: item.command, exitCode: item.exitCode, tree: item.tree, capturedAt: item.capturedAt }, `check "${short(item.command)}" (exit ${item.exitCode})`);
+    }
+    // Raw ops last, as the agent wrote them.
+    extra.forEach((op, index) => push(op, `ops[${index}] ${noteText(op.type, 40)}`));
+    return { ok: true, ops, labels };
+}
+/** The words for an error `parseLedgerCall` gave about `ops[n]`, said about the item it came from. */
+export function explainCallError(error, labels) {
+    const limit = /^A call carries at most (\d+) ops; this one has (\d+)\.$/.exec(error);
+    if (limit) {
+        return `Refused: this save would send ${limit[2]} ops, and one call carries at most ${limit[1]}. Nothing was sent. Save in two parts, the most important first.`;
+    }
+    const at = /^ops\[(\d+)\]\.?(.*)$/.exec(error);
+    const rest = (at ? at[2] || "is not valid" : error).replace(/\.$/, "");
+    const subject = at ? labels[Number(at[1])] ?? `ops[${at[1]}]` : "";
+    return `Refused: ${subject ? `${subject}: ` : ""}${rest}. Nothing was sent. Fix it and seal again.`;
+}
+/**
+ * Check the call as the server will: `parseLedgerCall` (secrets, `FILL:`, lengths, at most 50 ops) and the
+ * size of the whole request. A refusal is in plain words and nothing is sent.
+ */
+export function checkLedgerCall(input) {
+    const parsed = parseLedgerCall({ baseRevision: input.baseRevision, repo: input.repo, ops: input.ops });
+    if (!parsed.ok)
+        return fail(explainCallError(parsed.error, input.labels));
+    const args = { source: input.source, projectId: input.projectId, baseRevision: input.baseRevision, repo: parsed.value.repo, ops: parsed.value.ops };
+    // The whole JSON-RPC request counts, not only the arguments.
+    const body = JSON.stringify({ jsonrpc: "2.0", id: 1_000_000, method: "tools/call", params: { name: "record_ops", arguments: args } });
+    const bytes = new TextEncoder().encode(body).length;
+    if (bytes > LEDGER_CALL_MAX_BYTES) {
+        return fail(`Refused: this save is ${bytes.toLocaleString("en-US")} bytes, and one call may carry at most ${LEDGER_CALL_MAX_BYTES.toLocaleString("en-US")}. Nothing was sent. Save in two parts, the most important first.`);
+    }
+    return { ok: true, ops: parsed.value.ops, args };
+}
+/** True for the answer a server gives when it has no such tool: an older Hypher, with no ledger. */
+export function isUnknownToolError(message, code) {
+    return code === -32601 || /\bunknown[-\s]tool\b|\btool not found\b|\bmethod not found\b/i.test(message);
+}
+const KNOWN_STATUSES = ["applied", "merged", "noop", "disputed", "refused", "unsupported"];
+function oneLine(text, max = 240) {
+    return noteText(text ?? "", max);
+}
+function resultLine(result, label) {
+    const note = result.note ? ` (${oneLine(result.note)})` : "";
+    switch (result.status) {
+        case "merged":
+            return `${label}: merged into ${result.id ?? "an existing item"}${note}`;
+        case "noop":
+            return `${label}: no change${note}`;
+        case "disputed":
+            return `${label}: disputed${result.subject ? ` on ${oneLine(result.subject, 40)}` : ""}${result.id ? `; your proposal is ${oneLine(result.id, 40)}` : ""}`;
+        case "refused":
+            return `${label}: refused${result.reason ? `. ${oneLine(result.reason)}` : ""}`;
+        case "unsupported":
+            return `${label}: not applied. This Hypher does not know the op type "${oneLine(result.type ?? "", 60)}"; it is kept in the log.`;
+        default: {
+            // A status this copy does not know: said as it came, with whatever the server attached.
+            const parts = [result.id, result.subject].filter(Boolean).map((item) => oneLine(item, 40));
+            return `${label}: ${oneLine(result.status, 40)}${parts.length ? ` ${parts.join(" ")}` : ""}${result.reason ? `. ${oneLine(result.reason)}` : ""}${note}`;
+        }
+    }
+}
+/**
+ * The answer to a saved `record_ops` call. It starts with the revision and the counts, then has one line
+ * for each op that was not simply applied, then each question for the user, then a line when other
+ * writers landed changes between the revision this session read and this save.
+ */
+export function describeLedgerSave(input) {
+    const { answer } = input;
+    const results = answer.results ?? [];
+    const counts = answer.counts && typeof answer.counts === "object"
+        ? { ...answer.counts }
+        : results.reduce((all, item) => ({ ...all, [item.status]: (all[item.status] ?? 0) + 1 }), {});
+    const order = [...KNOWN_STATUSES, ...Object.keys(counts).filter((status) => !KNOWN_STATUSES.includes(status))];
+    const summary = order.filter((status) => (counts[status] ?? 0) > 0).map((status) => `${counts[status]} ${oneLine(status, 40)}`).join(", ") || "no ops";
+    const where = `for "${oneLine(input.projectName, 80)}" (branch ${oneLine(answer.branch ?? input.branch, 120)})`;
+    const lines = [
+        `Saved ledger revision ${answer.revision} ${where}: ${summary}. Memory did not transfer code.${answer.replay ? " This save was already recorded; nothing was added." : ""}`,
+        ...(input.extraLines ?? []),
+    ];
+    for (const result of results) {
+        if (result.status === "applied")
+            continue;
+        lines.push(`- ${resultLine(result, input.labels[result.index] ?? `ops[${result.index}] ${oneLine(result.type ?? "?", 40)}`)}`);
+    }
+    for (const question of answer.ask ?? [])
+        lines.push(`Ask the user: ${oneLine(question, 600)}`);
+    if (answer.revision > input.base + 1 && !answer.replay) {
+        lines.push(`Other changes landed since this session read the ledger (revision ${input.base}; it is now ${answer.revision}). Run \`hypher resume\` to read them before you save again.`);
+    }
+    return lines.join("\n");
+}