@cotal-ai/runtime 0.57.0 → 0.59.0

package/dist/resolve-checkpoint.js

@@ -27,8 +27,13 @@
  * "the checkpoint named `approve` in this run". The journal is what maps one to the other, and it is
  * also what says whether that step is still open — which is the question a resolver most needs
  * answered before it collects a human's decision.
+ *
+ * **A settled step is never re-answered, but it can be AMENDED.** The pause stays settled and the run
+ * keeps the answer it acted on; {@link amendAcceptedAnswer} files a later position beside that
+ * answer, naming it, so a participant who changes their mind records it on the step that holds the
+ * original rather than somewhere else.
  */
-import { replayRunJournal, newTakeoverId, recordCheckpointAnswer, checkpointAnswerId, readCheckpointSpec, resumeCheckpoint, } from "@cotal-ai/core";
+import { replayRunJournal, newTakeoverId, recordCheckpointAnswer, checkpointAnswerId, newAmendmentId, readCheckpointAnswer, readCheckpointSpec, readCheckpointStatus, resumeCheckpoint, } from "@cotal-ai/core";
 import { journalEntryKeyString } from "@cotal-ai/lang";
 /** No open checkpoint (or ask) answers to this address in this run. */
 export class CheckpointNotOpen extends Error {
@@ -48,6 +53,24 @@ export class CheckpointNotOpen extends Error {
         this.name = "CheckpointNotOpen";
     }
 }
+/** No accepted answer at this address that an amendment could be filed beside. */
+export class CheckpointNotAmendable extends Error {
+    runId;
+    stepKey;
+    why;
+    constructor(runId, stepKey, why) {
+        super(`run ${runId} has no accepted answer to amend at ${stepKey}: ${{
+            unknown: "no step is recorded under that key",
+            open: "that step is still open, so answer it instead",
+            "not-a-checkpoint": "that step is neither a checkpoint nor an ask",
+            unanswered: "that step settled without accepting an answer",
+        }[why]}`);
+        this.runId = runId;
+        this.stepKey = stepKey;
+        this.why = why;
+        this.name = "CheckpointNotAmendable";
+    }
+}
 /**
  * Answer a run's open checkpoint over ONE set of planes: {@link locateOpenCheckpoint} then
  * {@link answerOpenCheckpoint}. A caller whose credential must be pinned to the pause before it may
@@ -78,13 +101,46 @@ export async function resolveCheckpoint(deps, req) {
 export async function locateOpenCheckpoint(deps, req) {
     const entries = await replayRunEntries(deps, req.runId, req.takeoverId);
     const token = openCheckpointToken(entries, req.runId, req.stepKey);
-    const spec = await readCheckpointSpec(deps.kv, { endpoint: deps.endpoint, token });
+    const spec = await readSpecPastTheMintWindow(deps, token);
     if (spec === undefined) {
-        throw new Error(`checkpoint "${token}" has a journal entry but no record on endpoint ${deps.endpoint}; `
+        throw new Error(`checkpoint "${token}" has a journal entry but no record on endpoint ${deps.endpoint} `
+            + `after ${MINT_WINDOW_ATTEMPTS} reads over ${(MINT_WINDOW_ATTEMPTS - 1) * MINT_WINDOW_STEP_MS}ms; `
             + `refusing to guess a presenter — reconcile the store before answering`);
     }
     return { token, holder: spec.holder };
 }
+/** Reads long enough to tell a mint in flight from a torn store, and no longer.
+ *
+ *  `checkpoint` in the mesh handler appends the step's PENDING journal entry before it mints the
+ *  pause's record, deliberately: its own comment calls that the harmless direction, because a crash
+ *  between the two leaves an entry saying what it was going to ask rather than a pause nothing
+ *  records. The cost is a window in which the two halves this resolver needs are not both readable
+ *  yet, and one read cannot tell that window from the store being torn — the SAME observation means
+ *  either. What separates them is time: the window closes in a couple of round trips, and a torn
+ *  store never closes.
+ *
+ *  Bounded on purpose, both ways. Refusing on the first read turns a checkpoint that is about to be
+ *  answerable into "reconcile the store", which is the wrong instruction and, at the operator
+ *  surface, an answer a human has to give twice. Waiting without a bound would hang that human on a
+ *  pause that will never be answerable. The window is a KV create plus its status write on a loaded
+ *  host, so a low single-digit number of seconds covers it with room to spare.
+ *
+ *  Only the record is re-read. The token is a fact about the journal at the moment it was replayed,
+ *  and a replay binds its own consumer, so re-reading the journal per attempt would contend with
+ *  the driver for a staleness this call already carries either way. */
+const MINT_WINDOW_ATTEMPTS = 10;
+const MINT_WINDOW_STEP_MS = 200;
+async function readSpecPastTheMintWindow(deps, token) {
+    const ref = { endpoint: deps.endpoint, token };
+    for (let i = 0; i < MINT_WINDOW_ATTEMPTS; i += 1) {
+        const spec = await readCheckpointSpec(deps.kv, ref);
+        if (spec !== undefined)
+            return spec;
+        if (i + 1 < MINT_WINDOW_ATTEMPTS)
+            await new Promise((r) => setTimeout(r, MINT_WINDOW_STEP_MS));
+    }
+    return undefined;
+}
 /**
  * The WRITE half of an answer: file the answer record for the located pause, then present its
  * token as the arming holder. Every write is keyed by `open.token`, so a credential minted for this
@@ -115,6 +171,68 @@ export async function answerOpenCheckpoint(deps, req) {
     });
     return { token, answerId, settle };
 }
+/**
+ * The READ half of an amendment: replay the run's journal to the settled pause at `stepKey`, then
+ * read which answer its settlement accepted off the checkpoint's status record. Nothing is written.
+ * The status names the id for an `ask` as well as a checkpoint, where the journal's frozen result
+ * names it for a checkpoint only.
+ */
+export async function locateAcceptedAnswer(deps, req) {
+    const entries = await replayRunEntries(deps, req.runId, req.takeoverId);
+    const token = settledPauseToken(entries, req.runId, req.stepKey);
+    if (token === undefined)
+        throw new CheckpointNotAmendable(req.runId, req.stepKey, "unanswered");
+    const status = await readCheckpointStatus(deps.kv, { endpoint: deps.endpoint, token });
+    const answerId = status?.value.state === "resumed" ? status.value.settledAnswerId : undefined;
+    if (answerId === undefined)
+        throw new CheckpointNotAmendable(req.runId, req.stepKey, "unanswered");
+    const accepted = await readCheckpointAnswer(deps.kv, deps.endpoint, token, answerId);
+    if (accepted === undefined)
+        throw new Error(`checkpoint "${token}" settled naming the answer ${answerId}, which is not on record; reconcile the store before amending`);
+    return { token, answerId, by: accepted.by };
+}
+/**
+ * The WRITE half of an amendment: file a create-only answer record under the accepted answer's
+ * token that names it as `supersedes`, under a fresh id, so every call is its own filing. No token
+ * is presented, so the pause stays settled and the run never reads this record; the journal lists
+ * it under the step.
+ */
+export async function amendAcceptedAnswer(deps, req) {
+    const { token, answerId: supersedes } = req.accepted;
+    const answerId = newAmendmentId();
+    await recordCheckpointAnswer(deps.kv, deps.endpoint, {
+        v: 1,
+        token,
+        answerId,
+        ...(req.value !== undefined ? { value: req.value } : {}),
+        ...(req.artifact !== undefined ? { artifact: req.artifact } : {}),
+        by: req.by,
+        at: req.now,
+        supersedes,
+    });
+    return { token, answerId, supersedes };
+}
+/** The token a settled checkpoint (or ask) settled under, or a loud refusal naming why the step has
+ *  none to amend. A checkpoint settles under its request id; an `ask` under its LAST attempt's
+ *  token, which rides the step's pending entries as `askToken` (attempt 1 is the request id). */
+export function settledPauseToken(entries, runId, stepKey) {
+    let entry;
+    let askToken;
+    for (const e of entries) {
+        if (journalEntryKeyString(e) !== stepKey)
+            continue;
+        entry = e;
+        if (typeof e.external?.askToken === "string")
+            askToken = e.external.askToken;
+    }
+    if (entry === undefined)
+        throw new CheckpointNotAmendable(runId, stepKey, "unknown");
+    if (entry.kind !== "checkpoint" && entry.kind !== "ask")
+        throw new CheckpointNotAmendable(runId, stepKey, "not-a-checkpoint");
+    if (entry.state === "pending")
+        throw new CheckpointNotAmendable(runId, stepKey, "open");
+    return entry.kind === "ask" ? askToken ?? entry.requestId : entry.requestId;
+}
 /** The token of the open checkpoint (or ask attempt) at this address, or a loud refusal naming
  *  which it is not. An `ask` parks on the checkpoint plane too — one pause per attempt — and the
  *  CURRENT attempt's token rides the entry's external state as `askToken` (attempt 1 is the

package/dist/resolve-checkpoint.js.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-checkpoint.js","sourceRoot":"","sources":["../src/resolve-checkpoint.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"resolve-checkpoint.js","sourceRoot":"","sources":["../src/resolve-checkpoint.ts"],"names":[],"mappings":"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"}

package/dist/run-command.d.ts

@@ -20,7 +20,7 @@ import { EpEnvelopeError, type ParsedArgs } from "@cotal-ai/core";
  * fixture with no manager at all, and an operator there would have been sent to check a version.
  */
 export declare function unansweredManagerRefusal(e: EpEnvelopeError): string;
-/** `cotal run <start|resume|ps|journal|answer>` — dispatch. The manager hosts by default;
+/** `cotal run <start|resume|ps|journal|answer|amend>` — dispatch. The manager hosts by default;
  *  `--local` drives in this process over one connection per invocation. */
 export declare function runWorkflow(args: ParsedArgs): Promise<void>;
 //# sourceMappingURL=run-command.d.ts.map

package/dist/run-command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-command.d.ts","sourceRoot":"","sources":["../src/run-command.ts"],"names":[],"mappings":"AAuBA,OAAO,EAEL,eAAe,EAiCf,KAAK,UAAU,EAOhB,MAAM,gBAAgB,CAAC;AAmiBxB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,eAAe,GAAG,MAAM,CAMnE;AAoND;2EAC2E;AAC3E,wBAAsB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAsCjE"}
+{"version":3,"file":"run-command.d.ts","sourceRoot":"","sources":["../src/run-command.ts"],"names":[],"mappings":"AAuBA,OAAO,EAEL,eAAe,EA8Bf,KAAK,UAAU,EAOhB,MAAM,gBAAgB,CAAC;AAsfxB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,eAAe,GAAG,MAAM,CAMnE;AA2PD;2EAC2E;AAC3E,wBAAsB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CA2CjE"}

package/dist/run-command.js

@@ -20,17 +20,17 @@ import { randomBytes, randomUUID } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { jetstream, jetstreamManager } from "@nats-io/jetstream";
 import { Kvm } from "@nats-io/kv";
-import { BASELINE_LIFECYCLE_ENDPOINT, EpEnvelopeError, LANG_PROBLEM_DETAIL_KIND, dialerFor, invokeCommand, newTakeoverId, newIdentity, mintCreds, readAcceptedRow, openRecordsBucket, admissionBucket, createRunAdmission, readRunAdmission, readRunRevocation, revokeRunAdmission, chatSubject, DEV_OWNER, readRunProgram, readRunRecord, renderLifecycleBlocked, replayRunJournal, resolveService, runDriverCaller, RUN_LAUNCH_DEADLINE_MS, standaloneConnectOpts, unansweredRail, unansweredRequest, walkKvEntries, } from "@cotal-ai/core";
+import { BASELINE_LIFECYCLE_ENDPOINT, EpEnvelopeError, LANG_PROBLEM_DETAIL_KIND, dialerFor, invokeCommand, newTakeoverId, newIdentity, mintCreds, readAcceptedRow, openRecordsBucket, admissionBucket, createRunAdmission, readRunAdmission, revokeRunAdmission, chatSubject, DEV_OWNER, readRunProgram, readRunRecord, renderLifecycleBlocked, replayRunJournal, resolveService, runDriverCaller, RUN_LAUNCH_DEADLINE_MS, standaloneConnectOpts, unansweredRail, unansweredRequest, } from "@cotal-ai/core";
 import {} from "@cotal-ai/lang";
 import { agentLifecycleSecretFilePaths, connectOrExit, controlCaller, endpointAuth, resolveControlTarget, resolveMeshTarget } from "@cotal-ai/workspace";
 import { startRun, driveRun } from "./run-driver.js";
 import { migrateRun } from "./migrate.js";
-import { journalStepRow } from "./run-host.js";
+import { cotalLangRunHost as runHost, journalRows } from "./run-host.js";
 import { createRunEffectHost } from "./run-effect-host.js";
 import { createRunScopeAuthority } from "./run-scope-authority.js";
 import { createRunRecordHost, runRecordView } from "./run-record-host.js";
-import { locateOpenCheckpoint, answerOpenCheckpoint } from "./resolve-checkpoint.js";
-const USAGE = 'usage: cotal run <start --file <program> [--timeout <dur>] | resume <runId> [--local --file <program>] | ps [--endpoint <ep>] | journal <runId> [--endpoint <ep>] | answer <runId> <stepKey> [--value <json>] [--artifact <ref>] [--endpoint <ep>] [--local --by <who>] | revoke <runId> --local --by <who> --reason <text> [--endpoint <ep>] | migrate <runId> --local --file <program> [--endpoint <ep>]> [--local [--admit-read <channels> --admit-publish <channels>]] [--space <s>] [--server <url>] [--creds <path>]';
+import { locateOpenCheckpoint, answerOpenCheckpoint, locateAcceptedAnswer, amendAcceptedAnswer } from "./resolve-checkpoint.js";
+const USAGE = 'usage: cotal run <start --file <program> [--timeout <dur>] | resume <runId> [--local --file <program>] | ps [--endpoint <ep>] [--json] | journal <runId> [--endpoint <ep>] [--json] | answer <runId> <stepKey> [--value <json>] [--artifact <ref>] [--endpoint <ep>] [--local --by <who>] | amend <runId> <stepKey> [--value <json>] [--artifact <ref>] [--endpoint <ep>] [--local --by <who>] | revoke <runId> --local --by <who> --reason <text> [--endpoint <ep>] | migrate <runId> --local --file <program> [--endpoint <ep>]> [--local [--admit-read <channels> --admit-publish <channels>]] [--space <s>] [--server <url>] [--creds <path>]';
 /** One raw connection to the resolved mesh under the verb's OWN profile, with the planes over it.
  *  A drive rides the run's `run-driver` credential (SPEC 14.6), minted for the one run and attempt
  *  it drives; a read or an answer rides a one-shot `run-operator` credential for that call. An
@@ -61,13 +61,13 @@ async function openPlanes(values, role, mint) {
         },
     };
 }
-/** Mint from the same resolved target as the driver, preserving its broker and TLS intent. */
 /** A local drive mints its mediator and its admitter from the folder's signer; a lone `--creds`
  *  file can supply neither, and is refused by name before any other local check. */
 function refuseSingleCredential(conn) {
     if (conn.creds !== undefined && conn.auth === undefined)
         throw new Error("run --local needs the space signer to mint a separate mediator; a single --creds file cannot supply both roles. From the project with the recorded static-auth mesh and signer, omit --creds and run cotal run start --local --space <space> --file <program>. If you only have caller credentials, ask the mesh operator to host the run.");
 }
+/** Mint from the same resolved target as the driver, preserving its broker and TLS intent. */
 async function openMediator(driver, pin) {
     const conn = driver.connection;
     refuseSingleCredential(conn);
@@ -313,108 +313,20 @@ async function drive(values, planes, a) {
     }
 }
 async function ps(values, planes) {
-    // Run record keys are `run.<endpoint>.<runId>.<spec|status>` in the records bucket; the scan is
-    // over the spec half, which every run has exactly once. A consumer-free walk: the records bucket
-    // is an authority stream whose consumer surface is an exact audited list (SPEC 13.9).
-    const seen = new Set();
-    const rows = [];
-    /** Why each revoked row reads `revoked`, printed under the table: the marker carries `by` and the
-     *  reason, and the table has no column for either. */
-    const revocations = new Map();
-    /** Rows whose revocation could not be read at all, each with the reason and its record's state,
-     *  printed to stderr after the table. */
-    const unchecked = [];
-    for (const e of await walkKvEntries(planes.kv, "run.*.*.spec")) {
-        const parts = e.key.split(".");
-        if (parts.length !== 4 || parts[3] !== "spec")
-            continue;
-        const endpoint = parts[1];
-        const runId = parts[2];
-        const dedupe = `${endpoint}/${runId}`;
-        if (seen.has(dedupe))
-            continue;
-        seen.add(dedupe);
-        if (values.endpoint !== undefined && endpoint !== values.endpoint)
-            continue;
-        const record = await readRunRecord(planes.kv, endpoint, runId);
-        if (record === undefined)
-            continue;
-        const st = record.status?.value;
-        const lineage = record.spec.value.forkedFrom;
-        // THE ADMISSION STORE, not the status record alone. A revocation is a create-only marker under
-        // its own key and nothing rewrites the record (SPEC 14.8, docs/workflows.md), while the record
-        // is written only by a driver. A driver that dies mid-run therefore leaves `running` behind
-        // with nothing left to write anything else, and this table listed that run as live for as long
-        // as it existed. `resume` already reads the marker and refuses; the table was the one surface
-        // that never learned.
-        //
-        // DISPLAY ONLY. A revoke does not make a run `failed` or `released`: nobody drove it there, the
-        // journal owns the facts, and fabricating a terminal state here would put a fact in front of an
-        // operator that no host ever recorded.
-        let state = st?.state ?? "(no status)";
-        try {
-            const revoked = await readRunRevocation(planes.jsm, planes.space, endpoint, runId);
-            if (revoked !== undefined) {
-                revocations.set(dedupe, revoked);
-                state = "revoked";
-            }
-        }
-        catch (e) {
-            // Absence of EVIDENCE, and the STATE column itself says so. A marker this call could not read
-            // (a store it could not reach, a marker version or shape it does not know) says nothing about
-            // whether the run was revoked. The record's own word is what a revoked run printed before
-            // this table read the marker, so the column says `unchecked` and the record's word goes to
-            // stderr with the reason, where `awk '{print $3}'` and `grep running` over stdout never see it.
-            // The row itself still prints: one unreadable marker does not hide the rest of the listing.
-            state = "unchecked";
-            unchecked.push(`${dedupe}: revocation marker could not be read (${e.message}); its record reads ${st?.state ?? "(no status)"}`);
-        }
-        rows.push([
-            runId,
-            endpoint,
-            state,
-            st?.holder ?? "-",
-            st === undefined ? "-" : String(st.journalHigh),
-            lineage === undefined ? "-" : `${lineage.run}@${lineage.step}`,
-        ]);
-    }
-    if (rows.length === 0) {
-        console.log(`no workflow runs recorded in space ${planes.space}`);
-        return;
-    }
-    const header = ["RUN", "ENDPOINT", "STATE", "HOLDER", "JOURNAL", "FORKED-FROM"];
-    const widths = header.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
-    const line = (r) => r.map((cell, i) => cell.padEnd(widths[i])).join("  ");
-    console.log(line(header));
-    for (const r of rows)
-        console.log(line(r));
-    // WHO revoked it and WHY, under the table rather than in it. The marker carries both and the
-    // columns carry neither, and a state of `revoked` with no attribution anywhere sends the
-    // operator to a second command to learn what they are looking at.
-    for (const [key, r] of revocations)
-        console.log(`${key}: revoked by ${r.by} (${r.reason}); the status record is left as its driver last wrote it`);
-    // A listing with an unchecked row is incomplete, and the exit status says so after every row
-    // has been printed, as `ls` and `find` do when one entry cannot be read: the rows on stdout, the
-    // failed reads on stderr, and a non-zero status a caller can test without parsing the column.
-    for (const u of unchecked)
-        console.error(u);
-    if (unchecked.length > 0)
-        process.exitCode = 1;
+    // The same rows the manager answers `run-ps` with, read under this call's operator credential:
+    // the record's state beside its revocation marker (SPEC 14.8), so `--local` and hosted agree
+    // row for row, `--json` included.
+    const rows = await runHost.list(planes, values.endpoint !== undefined ? { endpoint: values.endpoint } : {});
+    printRuns(planes.space, rows, values.json === true);
 }
-async function journal(planes, runId, takeoverId) {
+async function journal(values, planes, endpoint, runId, takeoverId) {
     if (runId === undefined) {
         console.error(USAGE);
         process.exit(1);
     }
     // The replay durable is named by the takeover id this call's credential was minted for.
     const replay = await replayRunJournal(planes.js, planes.jsm, planes.space, runId, takeoverId);
-    if (replay.records.length === 0) {
-        console.log(`run ${runId}: no journal records (never started, or retired)`);
-        return;
-    }
-    printJournal(runId, replay.records.map(({ record }) => record.kind === "activation"
-        ? { n: record.n, kind: "activation", holder: record.holder, epoch: record.epoch, replayedTo: record.replayedTo }
-        : journalStepRow(record.n, record.entry)));
+    printJournal(runId, await journalRows(planes.kv, endpoint, replay.records), values.json === true);
 }
 /** `answer --local`: the pause is found under the READ credential this call was opened on, then
  *  the answer rides a second, one-shot credential pinned to that pause's token. */
@@ -445,6 +357,33 @@ async function answer(values, reader, runId, stepKey, takeoverId) {
         await writer.close();
     }
 }
+/** `amend --local`: the accepted answer is found under the READ credential this call was opened on,
+ *  then the amendment rides a second, one-shot credential pinned to that pause's token. Nothing is
+ *  presented: the step stays settled and the run keeps the answer it acted on. */
+async function amend(values, reader, runId, stepKey, takeoverId) {
+    if (runId === undefined || stepKey === undefined || values.by === undefined) {
+        console.error(USAGE);
+        console.error("run amend: <runId> <stepKey> and --by <who> are required");
+        process.exit(1);
+    }
+    const endpoint = values.endpoint ?? "manager";
+    const parsedValue = parseAnswerValue(values);
+    const accepted = await locateAcceptedAnswer({ kv: reader.kv, js: reader.js, jsm: reader.jsm, space: reader.space, endpoint }, { runId, stepKey, takeoverId });
+    const writer = await openPlanes(values, "run-operator", { runOperator: { endpoint, takeoverId: newTakeoverId(), answers: { token: accepted.token } } });
+    try {
+        const result = await amendAcceptedAnswer({ kv: writer.kv, js: writer.js, jsm: writer.jsm, space: writer.space, endpoint }, {
+            accepted,
+            by: values.by,
+            ...(values.value !== undefined ? { value: parsedValue } : {}),
+            ...(values.artifact !== undefined ? { artifact: values.artifact } : {}),
+            now: Date.now(),
+        });
+        console.log(JSON.stringify(result, null, 2));
+    }
+    finally {
+        await writer.close();
+    }
+}
 /** Parse `--value` as JSON, with the one hint every first-time user needs. */
 function parseAnswerValue(values) {
     if (values.value === undefined)
@@ -648,7 +587,14 @@ function renderLangProblem(d) {
     const at = where ? `${where.file ?? "<program>"}:${where.line ?? "?"}:${where.column ?? "?"}` : "<program>";
     return `  ${String(d.code ?? "L????")} ${String(d.title ?? "")} (${at})\n    ${String(d.cause ?? "")}\n    fix: ${String(d.fix ?? "")}`;
 }
-function printJournal(runId, rows) {
+/** `--json` prints each row unchanged as one JSON object per line, as `cotal ps --json` does for
+ *  seats: stdout carries rows only, so an empty journal prints nothing there. */
+function printJournal(runId, rows, json) {
+    if (json) {
+        for (const r of rows)
+            console.log(JSON.stringify(r));
+        return;
+    }
     if (rows.length === 0) {
         console.log(`run ${runId}: no journal records (never started, or retired)`);
         return;
@@ -671,17 +617,45 @@ function printJournal(runId, rows) {
             ];
             console.log(`            answered    ${facts.join("  ")}`);
         }
+        for (const m of r.amendments ?? []) {
+            const facts = [
+                ...(Object.hasOwn(m, "value") ? [`value=${JSON.stringify(m.value)}`] : []),
+                `by=${JSON.stringify(m.by)}`,
+                ...(m.artifact !== undefined ? [`artifact=${JSON.stringify(m.artifact)}`] : []),
+                `at=${JSON.stringify(m.at)}`,
+                `supersedes=${JSON.stringify(m.supersedes)}`,
+                `answerId=${JSON.stringify(m.answerId)}`,
+            ];
+            console.log(`            amended     ${facts.join("  ")}`);
+        }
     }
 }
-function printRuns(space, rows) {
+function printRuns(space, rows, json) {
+    // A marker the host could not read fails the listing after every row is printed, under `--json`
+    // as in the table: its reason and the record's word on stderr, and exit 1.
+    const unchecked = rows.filter((r) => r.revocationUnreadable !== undefined);
+    const reportUnchecked = () => {
+        for (const r of unchecked)
+            console.error(`${r.endpoint}/${r.runId}: revocation marker could not be read (${r.revocationUnreadable}); its record reads ${r.state ?? "(no status)"}`);
+        if (unchecked.length > 0)
+            process.exitCode = 1;
+    };
+    if (json) {
+        for (const r of rows)
+            console.log(JSON.stringify(r));
+        reportUnchecked();
+        return;
+    }
     if (rows.length === 0) {
         console.log(`no workflow runs recorded in space ${space}`);
         return;
     }
+    // The same reading as `run ps --local`: a marker wins over the record's state, and a marker the
+    // host could not read prints `unchecked` with the record's word on stderr and exit 1.
     const table = rows.map((r) => [
         r.runId,
         r.endpoint,
-        r.state ?? "(no status)",
+        r.revoked !== undefined ? "revoked" : r.revocationUnreadable !== undefined ? "unchecked" : r.state ?? "(no status)",
         r.holder ?? "-",
         r.journalHigh === undefined ? "-" : String(r.journalHigh),
         r.forkedFrom === undefined ? "-" : `${r.forkedFrom.run}@${r.forkedFrom.step}`,
@@ -692,6 +666,10 @@ function printRuns(space, rows) {
     console.log(line(header));
     for (const r of table)
         console.log(line(r));
+    for (const r of rows)
+        if (r.revoked !== undefined)
+            console.log(`${r.endpoint}/${r.runId}: revoked by ${r.revoked.by} (${r.revoked.reason}); the status record is left as its driver last wrote it`);
+    reportUnchecked();
 }
 async function hosted(values, verb, a, b) {
     const endpoint = values.endpoint !== undefined ? { endpoint: values.endpoint } : {};
@@ -701,8 +679,8 @@ async function hosted(values, verb, a, b) {
         console.error(`run ${verb}: --endpoint is not taken on the hosted path; the manager records the run under its own endpoint. \`--local\` drives under a chosen endpoint from this process`);
         process.exit(1);
     }
-    if (verb === "answer" && values.by !== undefined) {
-        console.error("run answer: --by is not taken on the hosted path; the manager records you as the answerer from your credential. `--local --by <who>` names the answerer when driving from this process");
+    if ((verb === "answer" || verb === "amend") && values.by !== undefined) {
+        console.error(`run ${verb}: --by is not taken on the hosted path; the manager records you as the answerer from your credential. \`--local --by <who>\` names the answerer when driving from this process`);
         process.exit(1);
     }
     // The manager serves no `run-migrate` command, so there is nothing to route to: the check reads
@@ -738,7 +716,7 @@ async function hosted(values, verb, a, b) {
     if (verb === "ps") {
         const rows = await askHost(values, "run-ps", Object.keys(endpoint).length ? endpoint : undefined);
         const t = values.space ?? "(the resolved mesh)";
-        printRuns(t, rows);
+        printRuns(t, rows, values.json === true);
         return;
     }
     if (verb === "journal") {
@@ -748,14 +726,16 @@ async function hosted(values, verb, a, b) {
         }
         const view = await askHost(values, "run-status", { runId: a, ...endpoint });
         const st = view.status;
-        console.log(`run ${view.runId} on ${view.endpoint}: ${st === undefined ? "(no status)" : `${st.state}, holder ${st.holder}, epoch ${st.epoch}`}`);
-        printJournal(view.runId, view.journal);
+        // Under --json the run's header line is structure, not a row: it goes to stderr.
+        (values.json === true ? console.error : console.log)(`run ${view.runId} on ${view.endpoint}: ${st === undefined ? "(no status)" : `${st.state}, holder ${st.holder}, epoch ${st.epoch}`}`);
+        printJournal(view.runId, view.journal, values.json === true);
         return;
     }
-    // answer: the manager records the caller as the answerer (SPEC 14.5), so no `--by` rides.
+    // answer and amend: the manager records the caller as the answerer (SPEC 14.5), so no `--by`
+    // rides. An amend is the same served command with `amend` set.
     if (a === undefined || b === undefined) {
         console.error(USAGE);
-        console.error("run answer: <runId> <stepKey> are required");
+        console.error(`run ${verb}: <runId> <stepKey> are required`);
         process.exit(1);
     }
     const value = parseAnswerValue(values);
@@ -765,18 +745,23 @@ async function hosted(values, verb, a, b) {
         ...endpoint,
         ...(values.value !== undefined ? { value } : {}),
         ...(values.artifact !== undefined ? { artifact: values.artifact } : {}),
+        ...(verb === "amend" ? { amend: true } : {}),
     });
     console.log(JSON.stringify(result, null, 2));
 }
-/** `cotal run <start|resume|ps|journal|answer>` — dispatch. The manager hosts by default;
+/** `cotal run <start|resume|ps|journal|answer|amend>` — dispatch. The manager hosts by default;
  *  `--local` drives in this process over one connection per invocation. */
 export async function runWorkflow(args) {
     const values = args.values;
     const [verb, a, b] = args.positionals;
-    if (verb === undefined || !["start", "resume", "ps", "journal", "answer", "revoke", "migrate"].includes(verb)) {
+    if (verb === undefined || !["start", "resume", "ps", "journal", "answer", "amend", "revoke", "migrate"].includes(verb)) {
         console.error(USAGE);
         process.exit(1);
     }
+    if (values.json === true && verb !== "ps" && verb !== "journal") {
+        console.error(`run ${verb}: --json is taken by \`ps\` and \`journal\` only`);
+        process.exit(1);
+    }
     if (verb === "revoke") {
         // Revocation is an operator act on the admission store, never a served command: the marker is
         // written from the folder's trust material, so it is `--local` only.
@@ -794,9 +779,9 @@ export async function runWorkflow(args) {
         return start(values);
     if (verb === "resume")
         return resume(values, a);
-    // The reads ride a one-shot operator READ credential for that call; a journal or an answer names
-    // the run its replay durable is pinned to. An answer finds its pause on this credential and then
-    // writes on a second one, minted for that pause alone (see `answer`).
+    // The reads ride a one-shot operator READ credential for that call; a journal, an answer or an
+    // amend names the run its replay durable is pinned to. An answer or an amend finds its pause on
+    // this credential and then writes on a second one, minted for that pause alone (see `answer`).
     const endpoint = values.endpoint ?? "manager";
     const takeoverId = newTakeoverId();
     const planes = await openPlanes(values, "run-operator", {
@@ -806,9 +791,11 @@ export async function runWorkflow(args) {
         if (verb === "ps")
             await ps(values, planes);
         else if (verb === "journal")
-            await journal(planes, a, takeoverId);
+            await journal(values, planes, endpoint, a, takeoverId);
         else if (verb === "migrate")
             await migrate(values, planes, a, takeoverId);
+        else if (verb === "amend")
+            await amend(values, planes, a, b, takeoverId);
         else
             await answer(values, planes, a, b, takeoverId);
     }