@cotal-ai/runtime 0.100.2 → 0.101.0

package/dist/run-command.js

@@ -19,26 +19,27 @@
 import { randomBytes, randomUUID } from "node:crypto";
 import { jetstream, jetstreamManager } from "@nats-io/jetstream";
 import { Kvm } from "@nats-io/kv";
-import { BASELINE_LIFECYCLE_ENDPOINT, EpEnvelopeError, assertLifecycleToken, LANG_PROBLEM_DETAIL_KIND, dialerFor, freezeExpectedSet, invokeRepairingSplit, noLiveInstances, newTakeoverId, newIdentity, mintCreds, issuedUserCaller, 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 { RunHeld } from "@cotal-ai/lang";
-import { CommandFailure, presentationOf, recordOperationSpace, connectOrExit, controlCaller, endpointAuth, resolveControlTarget, resolveSeatControlTarget } from "@cotal-ai/workspace";
+import { assertValidChannel, BASELINE_LIFECYCLE_ENDPOINT, chatStream, EpEnvelopeError, isStreamNotFound, hasDuplicateNames, assertIdToken, assertLifecycleToken, LANG_PROBLEM_DETAIL_KIND, dialerFor, freezeExpectedSet, invokeRepairingSplit, noLiveInstances, newTakeoverId, newIdentity, mintCreds, issuedUserCaller, openRecordsBucket, admissionBucket, admissionKey, createRunAdmission, readRunAdmission, revokeRunAdmission, chatSubject, DEV_OWNER, readRunProgram, readRunRecord, renderLifecycleBlocked, replayRunJournal, resolveService, runDriverCaller, RUN_LAUNCH_DEADLINE_MS, standaloneConnectOpts, oneLine, unansweredRail, unansweredRequest, } from "@cotal-ai/core";
+import { CATALOG, CheckpointNotAmendable, CheckpointNotOpen, DurationError, isDuration, LangErrors, parseDuration, RunHeld } from "@cotal-ai/lang";
+import { boundedValue, CommandFailure, commandFailureReport, failureEnvelope, presentationOf, recordOperationSpace, renderReport, terminalWidth, writeEnvelope, connectOrExit, controlCaller, endpointAuth, resolveControlTarget, resolveSeatControlTarget, localStackRoot, spaceStreamsAbsent, spaceStreamsExpected, connectOrThrow, isConnectRefusal, SHOWN_VALUE_MAX, } from "@cotal-ai/workspace";
 import { offlineWorkflow, sourceOf } from "./offline-command.js";
 import { seatTurnCommand } from "./seat-turn-command.js";
-import { printRunDetail, printRunList, runReceipt } from "./workflow-views.js";
+import { openRequestKeys, printRunDetail, printRunList, runReceipt } from "./workflow-views.js";
 import { startRun, driveRun } from "./run-driver.js";
 import { migrateRun } from "./migrate.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, 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] [--page [--limit <n>] [--cursor <cursor>]] | 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>]] [--on <instance>] [--space <s>] [--server <url>] [--creds <path>]';
+import { logLineText } from "./log-line.js";
+import { locateOpenCheckpoint, answerOpenCheckpoint, locateAcceptedAnswer, amendAcceptedAnswer, RunAnswerBlocked } from "./resolve-checkpoint.js";
+const USAGE = 'usage: cotal run [--endpoint <ep>] [--json] [--page [--limit <n>] [--cursor <cursor>]] | cotal run <start --file <program> [--timeout <dur>] | resume <runId> [--local --file <program>] | show <runId> [--endpoint <ep>] [--limit <n>] [--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>] | check <runId> <program> [--endpoint <ep>]> [--local [--admit-read <channels> --admit-publish <channels>]] [--on <instance>] [--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
  *  open mesh connects bare either way. */
 async function openPlanes(values, role, mint) {
-    const conn = await connectOrExit(values, role, { mint });
+    const conn = await connectOrThrow(values, role, { mint });
     const nc = await dialerFor(conn.server)({
         servers: conn.server,
         ...standaloneConnectOpts({ ...endpointAuth(conn), tls: conn.tls }),
@@ -221,7 +222,7 @@ async function revoke(values, runId) {
         process.exit(1);
     }
     const endpoint = values.endpoint ?? "manager";
-    const conn = await connectOrExit(values, "run-admitter", { mint: { runAdmitter: { endpoint, runId } } });
+    const conn = await connectOrThrow(values, "run-admitter", { mint: { runAdmitter: { endpoint, runId } } });
     refuseSingleCredential(conn);
     if (conn.auth === undefined) {
         console.error("run revoke: an open mesh keeps no admission store, so there is nothing to revoke there");
@@ -230,13 +231,19 @@ async function revoke(values, runId) {
     const nc = await dialerFor(conn.server)({ servers: conn.server, ...standaloneConnectOpts({ ...endpointAuth(conn), tls: conn.tls }), maxReconnectAttempts: 0 });
     try {
         const kv = await new Kvm(nc).open(admissionBucket(conn.space));
+        // The marker sits beside the run's admission. With no admission there is no run here to revoke,
+        // so refuse before anything is written.
+        if (await kv.get(admissionKey(endpoint, runId)) === null)
+            throw new CommandFailure("refused", "TARGET_NOT_FOUND", `run ${runId} has no admission on endpoint ${endpoint}, so there is nothing to revoke; nothing was written`, { target: { space: conn.space, endpoint, run: runId }, remedy: "list the recorded runs with cotal run" });
         await revokeRunAdmission(kv, endpoint, { version: 1, runId, reason: values.reason, by: values.by, revokedAt: Date.now() });
         const view = await readRunAdmission(await jetstreamManager(nc), conn.space, endpoint, runId);
         console.log(`run ${runId} on ${endpoint}: revoked by ${view.revoked.by} (${view.revoked.reason}); its hosts refuse the next channel effect, and it is not resumed or taken back`);
         // What the operator will see NEXT, because the two surfaces disagreed for as long as one of
         // them never read the marker. Saying it here means the acknowledgement and the table cannot
         // drift apart without somebody noticing at the moment of the revoke.
-        console.log(`run ps now lists ${runId} as revoked; the status record is left as its driver last wrote it`);
+        console.log(`cotal run now lists ${runId} as revoked; the status record is left as its driver last wrote it`);
+        // The marker is read only at a channel effect, so a run that makes none keeps computing.
+        console.log("a revoke does not cancel the run: work that touches no channel, such as sleep or log, keeps running until the host driving it stops");
     }
     finally {
         await nc.drain().catch(() => nc.close());
@@ -308,22 +315,43 @@ async function drive(values, planes, a) {
             handler,
             ...(values.file !== undefined ? { file: values.file } : {}),
             ...(planes.resultBytes !== undefined ? { resultBytes: planes.resultBytes } : {}),
+            onLog: (line) => console.log(`run ${runId}: log ${logLineText(line)}`),
         };
         if (a.mode === "new")
             console.log(`starting run ${runId} on endpoint ${endpoint} in space ${planes.space}`);
-        const out = a.mode === "new" ? await startRun(planes.js, planes.jsm, req) : await driveRun(planes.js, planes.jsm, req);
+        let out;
+        try {
+            out = a.mode === "new" ? await startRun(planes.js, planes.jsm, req) : await driveRun(planes.js, planes.jsm, req);
+        }
+        catch (e) {
+            // The driver records a program that failed on the run's status under this drive's lease, then
+            // rethrows its error. Only that record makes the outcome failed; any other throw stays unknown.
+            const status = (await readRunRecord(req.kv, endpoint, runId).catch(() => undefined))?.status?.value;
+            if (status?.state !== "failed" || status.holder !== who.id || status.epoch !== epoch || status.fencingToken !== fencingToken)
+                throw e;
+            // A language code is named by its catalog title. Other recorded text is untrusted, so only its
+            // first line is shown, and the report escapes its control characters.
+            const code = status.failure?.code;
+            const why = code !== undefined && Object.hasOwn(CATALOG, code) ? `: ${code} ${CATALOG[code]}` : `${code !== undefined ? ` (${code})` : ""}: ${(status.failure?.message ?? e.message).split("\n")[0]}`;
+            const show = `cotal run show ${runId} --local${endpoint === "manager" ? "" : ` --endpoint ${endpoint}`}`;
+            throw new CommandFailure("failed", "OPERATION_FAILED", `run ${runId} failed${why}`, { target: { space: planes.space, endpoint, run: runId }, remedy: `read its recorded failure with ${show}` });
+        }
         reportOutcome(runId, out);
     }
     finally {
         await mediator.nc.drain().catch(() => mediator.nc.close());
     }
 }
+/** The endpoints a listing's runs are recorded under, each once. */
+const recordedUnder = (rows) => [...new Set(rows.map((row) => row.endpoint))].sort();
 async function ps(values, planes) {
     // 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 } : {});
-    printRunList(planes.space, rows, values);
+    // An endpoint no run lives under is named, with the endpoints that hold runs.
+    const unmatched = values.endpoint !== undefined && !rows.length ? { endpoint: values.endpoint, recordedUnder: recordedUnder(await runHost.list(planes, {})) } : undefined;
+    printRunList(planes.space, rows, values, unmatched);
 }
 async function journal(values, planes, endpoint, runId, takeoverId) {
     if (runId === undefined) {
@@ -346,7 +374,12 @@ async function answer(values, reader, runId, stepKey, takeoverId) {
     }
     const endpoint = values.endpoint ?? "manager";
     const parsedValue = parseAnswerValue(values);
-    const open = await locateOpenCheckpoint({ kv: reader.kv, js: reader.js, jsm: reader.jsm, space: reader.space, endpoint }, { runId, stepKey, takeoverId });
+    const open = await locateOpenCheckpoint({ kv: reader.kv, js: reader.js, jsm: reader.jsm, space: reader.space, endpoint }, { runId, stepKey, takeoverId }).catch((e) => {
+        // Locating writes nothing, so a pause it does not find is refused as the hosted answer refuses it.
+        if (e instanceof CheckpointNotOpen)
+            throw new CommandFailure("refused", "TARGET_NOT_FOUND", e.message, { target: { space: reader.space, endpoint, run: runId }, remedy: `read the run's open requests with cotal run show ${runId} --local` });
+        throw e;
+    });
     // Resume is holder-bound (SPEC 13.10) and the CLI is not the driver: the resolver presents as
     // the ARMING holder it read off the checkpoint's own record, so a fresh invocation answers
     // exactly as the minter would have. The answerer's name rides `by`, never the presenter.
@@ -358,8 +391,12 @@ async function answer(values, reader, runId, stepKey, takeoverId) {
             ...(values.value !== undefined ? { value: parsedValue } : {}),
             ...(values.artifact !== undefined ? { artifact: values.artifact } : {}),
             now: Date.now(),
+        }).catch((e) => {
+            if (e instanceof RunAnswerBlocked)
+                throw new CommandFailure("refused", "LIFECYCLE_BLOCKED", e.message, { target: { space: writer.space, endpoint, run: runId }, native: { code: e.code } });
+            throw e;
         });
-        console.log(JSON.stringify(result, null, 2));
+        runReceipt("answer", reader.space, result, values, runId, { step: stepKey, ...(values.value !== undefined ? { value: parsedValue } : {}), ...(values.artifact !== undefined ? { artifact: values.artifact } : {}) });
     }
     finally {
         await writer.close();
@@ -376,7 +413,12 @@ async function amend(values, reader, runId, stepKey, takeoverId) {
     }
     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 accepted = await locateAcceptedAnswer({ kv: reader.kv, js: reader.js, jsm: reader.jsm, space: reader.space, endpoint }, { runId, stepKey, takeoverId }).catch((e) => {
+        // Locating writes nothing, so an answer it does not find is refused as the hosted amend refuses it.
+        if (e instanceof CheckpointNotAmendable)
+            throw new CommandFailure("refused", "TARGET_NOT_FOUND", e.message, { target: { space: reader.space, endpoint, run: runId }, remedy: `read the run's answers with cotal run show ${runId} --local` });
+        throw e;
+    });
     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 }, {
@@ -386,7 +428,7 @@ async function amend(values, reader, runId, stepKey, takeoverId) {
             ...(values.artifact !== undefined ? { artifact: values.artifact } : {}),
             now: Date.now(),
         });
-        console.log(JSON.stringify(result, null, 2));
+        runReceipt("amend", reader.space, result, values, runId, { step: stepKey, ...(values.value !== undefined ? { value: parsedValue } : {}), ...(values.artifact !== undefined ? { artifact: values.artifact } : {}) });
     }
     finally {
         await writer.close();
@@ -412,7 +454,7 @@ function parseAnswerValue(values) {
 async function migrate(values, planes, runId, takeoverId) {
     if (runId === undefined || values.file === undefined) {
         console.error(USAGE);
-        console.error("run migrate: <runId> and --file <program> are required");
+        console.error("run check: <runId> and <program> are required");
         process.exit(1);
     }
     // Commit-side overrides, refused by name: each one records a person's decision on a report the
@@ -423,29 +465,40 @@ async function migrate(values, planes, runId, takeoverId) {
         ["discard-approvals", "--discard-approvals"],
     ]) {
         if (values[flag] !== undefined) {
-            console.error(`run migrate: ${what} decides what a COMMIT does with an orphan, and this verb only checks; nothing was written`);
+            console.error(`run check: ${what} decides what a COMMIT does with an orphan, and this verb only checks; nothing was written`);
             process.exit(1);
         }
     }
     const endpoint = values.endpoint ?? "manager";
     const record = await readRunRecord(planes.kv, endpoint, runId);
-    if (record === undefined) {
-        console.error(`run ${runId}: no record on endpoint ${endpoint}; a run that was never started cannot be migrated`);
-        process.exit(1);
-    }
+    // A run ID nothing records is refused as `run show` refuses it; the check writes nothing either way.
+    if (record === undefined)
+        throw new CommandFailure("refused", "TARGET_NOT_FOUND", `run ${runId}: no record on endpoint ${endpoint}; a run that was never started cannot be checked`, { target: { space: planes.space, endpoint, run: runId }, remedy: "list the recorded runs with cotal run" });
     const replay = await replayRunJournal(planes.js, planes.jsm, planes.space, runId, takeoverId);
     const source = sourceOf(values.file);
-    const report = await migrateRun({
-        endpoint,
-        runId,
-        source,
-        file: values.file,
-        entries: replay.records.flatMap((r) => (r.record.kind === "step" ? [r.record.entry] : [])),
-        pins: record.spec.value.pins,
-        kv: planes.kv,
-        actor: "cotal run migrate",
-        now: () => Date.now(),
-    });
+    let report;
+    try {
+        report = await migrateRun({
+            endpoint,
+            runId,
+            source,
+            file: values.file,
+            entries: replay.records.flatMap((r) => (r.record.kind === "step" ? [r.record.entry] : [])),
+            pins: record.spec.value.pins,
+            kv: planes.kv,
+            actor: "cotal run migrate",
+            now: () => Date.now(),
+        });
+    }
+    catch (e) {
+        if (!(e instanceof LangErrors))
+            throw e;
+        // Every problem with its position, cause and fix, as `run validate` lists them.
+        console.error(`run check: ${values.file} is not valid cotal-lang (${e.errors.length} problem${e.errors.length === 1 ? "" : "s"}), so it was not checked against the journal`);
+        for (const item of e.errors)
+            console.error(`  ${item.code} ${item.title} (${item.span.file}:${item.span.line}:${item.span.column})\n    ${item.cause}\n    fix: ${item.fix}`);
+        process.exit(1);
+    }
     printMigrateReport(report);
     if (!report.admissible)
         process.exitCode = 1;
@@ -492,27 +545,67 @@ export function unansweredManagerRefusal(e) {
     const detail = `${e.code}: ${e.message}`;
     const rail = unansweredRail(e);
     if (rail === undefined || rail === "ep")
-        return `no manager answered on the endpoint rails (${detail}); is a manager running for this mesh? A run can still be driven from this terminal with --local`;
-    return `no manager answered on the ${rail} rail (${detail}). The ${rail} and legacy ep rails are disjoint at the broker (SPEC 13.15) and an endpoint must serve both, so this does not tell no manager running apart from one older than ${rail}, which serves ep only and cannot answer here. Check whether a manager is running, and if it is, restart it on a build that serves ${rail}`;
+        return `the manager registered for this space did not answer on the endpoint rails (${detail}); is a manager running for this mesh? A run can still be driven from this terminal with --local`;
+    return `the manager registered for this space did not answer on the ${rail} rail (${detail}). The ${rail} and legacy ep rails are disjoint at the broker (SPEC 13.15) and an endpoint must serve both, so this does not tell no manager running apart from one older than ${rail}, which serves ep only and cannot answer here. Check whether a manager is running, and if it is, restart it on a build that serves ${rail}`;
 }
 /** The manager's refusal codes that say it acted on nothing. */
 const REFUSED_BEFORE_EFFECT = {
     "permission-denied": "PERMISSION_DENIED", "not-found": "TARGET_NOT_FOUND", "failed-precondition": "LIFECYCLE_BLOCKED",
     "bad-request": "USAGE_INVALID", "unimplemented": "UNSUPPORTED", "conflict": "CONFLICT",
 };
+/** The local journal read a refused hosted read names. */
+const localJournal = (args) => `cotal run show ${typeof args?.runId === "string" ? args.runId : "<run-id>"} --local`;
 /** A manager refusal under the CLI's outcome table, with the manager's own sentence. Any other code
  *  leaves a read failed and a start, resume or answer unconfirmed, because the manager may have
- *  recorded it. */
-function managerRefusal(command, space, args, err) {
+ *  recorded it. `on` is the caller's explicit manager pin, which a suggested command keeps. */
+export function managerRefusal(command, space, args, err, on) {
     const message = renderLifecycleBlocked(err?.message ?? err?.code ?? "the manager refused", err);
     const options = { target: { space }, native: { code: err?.code ?? "unreported" } };
-    const code = err?.code === undefined ? undefined : REFUSED_BEFORE_EFFECT[err.code];
-    const remedy = err?.code !== "not-found" ? {} : { remedy: command === "run-answer" && typeof args?.runId === "string" ? `read the run's open requests with cotal run show ${args.runId}` : "list the recorded runs with cotal run ps" };
+    // A manager at its launch limit refuses `resource-exhausted` before writing anything, and says
+    // so with `not-executed`.
+    const busy = err?.code === "resource-exhausted" && err.outcome === "not-executed";
+    const code = err?.code === undefined ? undefined : busy ? "LIFECYCLE_BLOCKED" : REFUSED_BEFORE_EFFECT[err.code];
+    // A resume refused as a precondition, such as of a completed or failed run, appended nothing, so
+    // the run's recorded state is what to read next.
+    const resumeBlocked = command === "run-resume" && err?.code === "failed-precondition" && typeof args?.runId === "string";
+    const remedy = busy ? { remedy: `wait until one of them has activated, then run ${command === "run-resume" ? "the resume" : "the start"} again; cotal run lists a run once it has` }
+        : resumeBlocked ? { remedy: `read the run's recorded state with cotal run show ${args.runId}${on ? ` --on ${on}` : ""}` }
+            : err?.code !== "not-found" ? {} : { remedy: command === "run-answer" && typeof args?.runId === "string" ? `read the run's open requests with cotal run show ${args.runId}` : "list the recorded runs with cotal run" };
     if (code)
         return new CommandFailure("refused", err.details?.some((d) => d.kind === LANG_PROBLEM_DETAIL_KIND) ? "SCHEMA_INVALID" : code, message, { ...options, ...remedy });
+    // A reply too large for the broker changed nothing; the local read takes no reply.
+    if (command === "run-status" && err?.code === "resource-exhausted")
+        return new CommandFailure("refused", "UNSUPPORTED", message, { ...options, remedy: `read the run from its project folder with ${localJournal(args)}` });
     if (command === "run-status" || command === "run-ps")
         return new CommandFailure("failed", "OPERATION_FAILED", message, options);
-    return new CommandFailure("unknown", "OPERATION_UNKNOWN", message, { ...options, remedy: "read the run with cotal run show or cotal run ps before trying again; it was not retried" });
+    return new CommandFailure("unknown", "OPERATION_UNKNOWN", message, { ...options, remedy: "read the run with cotal run show, or list the runs with cotal run, before trying again; it was not retried" });
+}
+/** nats.js refuses a frame over the broker's `max_payload` before writing any of it. */
+function payloadRefused(error) {
+    for (let e = error; e instanceof Error; e = e.cause)
+        if (e.name === "InvalidArgumentError" && e.message.includes("max_payload"))
+            return true;
+    return false;
+}
+/** While a hosted start's request may be with the manager, a SIGINT or SIGTERM reports that the run
+ *  may already be recorded and exits as the signal would. The manager does not stop on the caller's
+ *  signal, so the process used to die silently with the run started, and a retry started a second
+ *  one. Returns the release. */
+function reportInterruptedStart(values, space) {
+    const exit = (signal) => {
+        const failure = new CommandFailure("unknown", "OPERATION_UNKNOWN", "interrupted after the start request was sent, so the manager may already have recorded the run", {
+            target: { space }, remedy: "list the recorded runs with cotal run before starting it again",
+        });
+        if (values.json)
+            writeEnvelope(failureEnvelope("run", failure));
+        process.stderr.write(`${renderReport(commandFailureReport(failure), values.plain ? "plain" : "rich", terminalWidth(process.stderr))}\n`);
+        process.exit(signal === "SIGINT" ? 130 : 143);
+    };
+    const onInterrupt = () => exit("SIGINT");
+    const onTerminate = () => exit("SIGTERM");
+    process.once("SIGINT", onInterrupt);
+    process.once("SIGTERM", onTerminate);
+    return () => { process.off("SIGINT", onInterrupt); process.off("SIGTERM", onTerminate); };
 }
 /** One command to the mesh's manager over the endpoint rails: a fresh resolve (describe, store
  *  fetch, digest-verified recompile), then the invoke, re-issued after a bind split
@@ -522,18 +615,21 @@ async function askHost(values, command, args, resolved) {
     const { target: t, seat } = await resolveRunControlTarget(values);
     resolved?.(t.space);
     const who = controlCaller(t.auth);
-    if ("refusal" in who) {
-        console.error(who.refusal);
-        process.exit(1);
-    }
+    // A raw --creds file carries no endpoint-caller triple, and this route cannot mint one. Without
+    // --creds the CLI mints the one-shot caller from the space's trust or the signed-in login.
+    if ("refusal" in who)
+        throw new CommandFailure("refused", "UNSUPPORTED", "a hosted run command cannot use a raw --creds file: it carries no endpoint-caller triple (owner, actor, lifecycle uid), and this route cannot mint one; nothing was sent", {
+            target: { space: t.space },
+            remedy: "run it again without --creds: in the mesh's project folder, or with --space naming its registry entry, the CLI mints the one-shot caller itself",
+        });
     const auth = t.auth;
     const connectOpts = standaloneConnectOpts(auth.creds ? { creds: auth.creds, tls: auth.tls === true } : auth.bearer ? { bearer: auth.bearer, sentinelCreds: auth.sentinelCreds, tls: auth.tls === true } : { tls: auth.tls === true });
     const nc = await dialerFor(t.server)({ servers: t.server, ...connectOpts, maxReconnectAttempts: 0 });
     try {
         // Only the operator's own unpinned instrument holds the registry rows `ps` scatters on; a seat's
         // credential and a user's manager view hold none.
-        if (!seat && auth.bearer === undefined && auth.managerInstanceId === undefined)
-            await refuseWithoutLiveManager(nc, t.space);
+        if (!seat && auth.bearer === undefined && (auth.managerInstanceId === undefined || values.on !== undefined))
+            await refuseWithoutLiveManager(nc, t.space, values.on);
         // A logged-in user's manager view is issued at the callout (SPEC 13.15): its generation is read
         // back from this connection's accepted row, and every request rides `ep.v1` under it.
         const caller = auth.bearer !== undefined && auth.managerInstanceId !== undefined
@@ -546,10 +642,26 @@ async function askHost(values, command, args, resolved) {
         // A start or resume is answered only once the drive has activated, which the manager waits on
         // for a bounded time; the deadline here outlives that wait, so the manager's own "still
         // launching" refusal is what a slow activation reads as, never a manager that did not answer.
-        const r = await invokeRepairingSplit(nc, t.space, service, command, args, {
-            deadlineMs: RUN_LAUNCH_DEADLINE_MS,
-            ...(command === "run-answer" ? { target: { mode: "self" } } : {}),
-        });
+        const interrupt = command === "run-start" ? reportInterruptedStart(values, t.space) : undefined;
+        let r;
+        try {
+            r = await invokeRepairingSplit(nc, t.space, service, command, args, {
+                deadlineMs: RUN_LAUNCH_DEADLINE_MS,
+                ...(command === "run-answer" ? { target: { mode: "self" } } : {}),
+            });
+        }
+        catch (e) {
+            if (!payloadRefused(e))
+                throw e;
+            const source = command === "run-start" && typeof args?.source === "string" ? args.source : undefined;
+            const limit = `this broker's ${nc.info?.max_payload ?? "unreported"}-byte message limit`;
+            throw new CommandFailure("refused", "UNSUPPORTED", source !== undefined
+                ? `the program is ${Buffer.byteLength(source)} bytes, and the start request that carries it exceeds ${limit}; nothing was sent`
+                : `the ${command} request exceeds ${limit}; nothing was sent`, { target: { space: t.space }, ...(source !== undefined ? { remedy: "shorten the program; a hosted start sends it to the manager in one message" } : {}) });
+        }
+        finally {
+            interrupt?.();
+        }
         if (r.reply.ok !== true) {
             const err = r.reply.error;
             // A validation refusal carries every problem as the language's own records; print them the
@@ -557,13 +669,25 @@ async function askHost(values, command, args, resolved) {
             for (const d of err?.details ?? [])
                 if (d.kind === LANG_PROBLEM_DETAIL_KIND)
                     console.error(renderLangProblem(d));
-            throw managerRefusal(command, t.space, args, err);
+            throw managerRefusal(command, t.space, args, err, values.on);
         }
         return r.reply.data;
     }
     catch (e) {
+        // A space whose streams were removed has no registry or contract store to read, so name that
+        // instead of the read that failed. `cotal status` says whether its stack still runs.
+        if (!(e instanceof CommandFailure) && spaceStreamsExpected(t.space, t.mode) && await chatStreamGone(nc, t.space))
+            throw spaceStreamsAbsent(t.space, localStackRoot(t.space));
+        // The contract of a manager from release 0.99.3 or earlier takes no journal page, so the request
+        // is refused here, against that contract, before it is sent.
+        if (e instanceof EpEnvelopeError && command === "run-status" && e.code === "bad-request" && /additional properties: "journal"/.test(e.message))
+            throw new CommandFailure("refused", "UNSUPPORTED", "this manager is from release 0.99.3 or earlier and reads no journal page, so this command cannot read the run through it", { target: { space: t.space }, remedy: `upgrade that manager, or read the run from its project folder with ${localJournal(args)}` });
+        // No answer is an unavailable target, not a usage error. Only this machine's records can name a
+        // manager that runs and does not answer, and `cotal status` reads them.
+        if (e instanceof EpEnvelopeError && unansweredRequest(e))
+            throw new CommandFailure("refused", "TARGET_UNAVAILABLE", unansweredManagerRefusal(e), { target: { space: t.space }, native: { code: e.code }, remedy: "cotal status shows whether this space's manager answers; a stack manager that runs but does not answer is named there with its pid and the way to end it" });
         if (e instanceof EpEnvelopeError) {
-            console.error(unansweredRequest(e) ? unansweredManagerRefusal(e) : `${e.code}: ${e.message}`);
+            console.error(`${e.code}: ${e.message}`);
             process.exit(1);
         }
         throw e;
@@ -572,13 +696,25 @@ async function askHost(values, command, args, resolved) {
         await nc.drain().catch(() => nc.close());
     }
 }
+/** Whether the chat stream of `space` is gone from the broker `nc` is connected to. Any other
+ *  failure to read it answers no. */
+async function chatStreamGone(nc, space) {
+    try {
+        await (await jetstreamManager(nc, { checkAPI: false })).streams.info(chatStream(space));
+        return false;
+    }
+    catch (e) {
+        return isStreamNotFound(e);
+    }
+}
 /** A hosted verb on a space whose registry lists no live manager is refused here, as `ps` refuses
  *  it, rather than after the describe has waited out its whole deadline for an answer no manager
- *  can send. Any other registry outcome, an unreadable registry included, leaves the describe to
- *  decide. */
-async function refuseWithoutLiveManager(nc, space) {
+ *  can send. So is an `on` pin that names none of the live managers, with the ones that run. Any
+ *  other registry outcome, an unreadable registry included, leaves the describe to decide. */
+async function refuseWithoutLiveManager(nc, space, on) {
+    let live;
     try {
-        await freezeExpectedSet(await jetstreamManager(nc, { checkAPI: false }), space, BASELINE_LIFECYCLE_ENDPOINT);
+        live = await freezeExpectedSet(await jetstreamManager(nc, { checkAPI: false }), space, BASELINE_LIFECYCLE_ENDPOINT);
     }
     catch (e) {
         if (!(e instanceof EpEnvelopeError) || !noLiveInstances(e))
@@ -589,6 +725,15 @@ async function refuseWithoutLiveManager(nc, space) {
             remedy: "start the stack's manager with bare cotal up; a stack started with --no-manager has none",
         });
     }
+    // A pin that names none of the running managers can only wait out its describe, so it is refused
+    // here, with the managers that do run.
+    if (on === undefined || live.some((instance) => instance.instanceId === on))
+        return;
+    const ids = live.map((instance) => instance.instanceId);
+    throw new CommandFailure("refused", "TARGET_NOT_FOUND", `--on ${on} names no manager running for space ${space}; ${ids.length === 1 ? `the one running is ${ids[0]}` : `the ones running are ${ids.join(", ")}`}. Nothing was sent`, {
+        target: { space, requestedManagerInstance: on },
+        remedy: ids.length === 1 ? `run it again with --on ${ids[0]}, or without --on` : "run it again with --on naming one of them",
+    });
 }
 /** A spawned static seat that shells out to the rendered `cotal run answer …` command must answer as
  *  THAT seat ({@link resolveSeatControlTarget}). An open mesh keeps the operator caller here, which
@@ -599,7 +744,7 @@ async function refuseWithoutLiveManager(nc, space) {
 async function resolveRunControlTarget(values) {
     const on = values.on;
     const seat = values.creds === undefined ? await resolveSeatControlTarget(values, on) : undefined;
-    const target = seat?.mode === "auth" ? seat : await resolveControlTarget(values, "control-caller-privileged", on);
+    const target = seat?.mode === "auth" ? seat : await resolveControlTarget(values, "control-caller-privileged", on, { onRefusal: "throw" });
     recordOperationSpace(target.space);
     const resolved = { target, seat: target === seat };
     if (on === undefined)
@@ -608,10 +753,13 @@ async function resolveRunControlTarget(values) {
         throw new CommandFailure("refused", "CONFLICT", "the requested manager instance differs from this credential's instance authority; no other manager was selected");
     return { ...resolved, target: { ...target, auth: { ...target.auth, managerInstanceId: on } } };
 }
-function renderLangProblem(d) {
+/** A validation problem the manager returned, as `run validate` prints one. Each value can quote the
+ *  program, such as a step name, so its control characters are escaped before the terminal sees them. */
+export function renderLangProblem(d) {
     const where = d.where;
     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 ?? "")}`;
+    const text = (value) => oneLine(String(value ?? ""));
+    return `  ${text(d.code ?? "L????")} ${text(d.title)} (${text(at)})\n    ${text(d.cause)}\n    fix: ${text(d.fix)}`;
 }
 async function hosted(values, verb, a, b) {
     let space;
@@ -630,7 +778,7 @@ async function hosted(values, verb, a, b) {
     // The manager serves no `run-migrate` command, so there is nothing to route to: the check reads
     // the run's record, journal and program itself, which is what `--local` does.
     if (verb === "migrate") {
-        console.error("run migrate: the manager serves no run-migrate command; the check reads the run from this terminal. Run `cotal run migrate <runId> --local --file <program>`");
+        console.error("run check: the manager serves no run-migrate command; the check reads the run from this terminal. Run `cotal run check <runId> <program>`");
         process.exit(1);
     }
     if (verb === "start") {
@@ -672,7 +820,8 @@ async function hosted(values, verb, a, b) {
             return;
         }
         const rows = await ask("run-ps", Object.keys(endpoint).length ? endpoint : undefined);
-        printRunList(space, rows, values);
+        const unmatched = values.endpoint !== undefined && !rows.length ? { endpoint: values.endpoint, recordedUnder: recordedUnder(await ask("run-ps", undefined)) } : undefined;
+        printRunList(space, rows, values, unmatched);
         return;
     }
     if (verb === "journal") {
@@ -680,10 +829,22 @@ async function hosted(values, verb, a, b) {
             console.error(USAGE);
             process.exit(1);
         }
-        const view = await ask("run-status", { runId: a, ...endpoint });
+        // The journal is read in pages, each one reply, so one larger than the broker's payload limit
+        // stays readable.
+        const rows = [];
+        let view;
+        do {
+            view = await ask("run-status", { runId: a, ...endpoint, journal: { offset: rows.length } });
+            if (view.journalTotal === undefined)
+                throw new CommandFailure("failed", "OPERATION_FAILED", "the manager answered the journal read without a page; the journal was not read", { target: { space: space ?? null, run: a } });
+            if (view.journal.length === 0 && rows.length < view.journalTotal)
+                throw new CommandFailure("failed", "OPERATION_FAILED", `the manager returned no journal rows at row ${rows.length} of ${view.journalTotal}; the journal was not read completely`, { target: { space: space ?? null, run: a } });
+            rows.push(...view.journal);
+        } while (rows.length < view.journalTotal);
         if (space === undefined)
             throw new Error("the native run target was not reported");
-        printRunDetail(space, view, values);
+        const { journalTotal: _total, ...record } = view;
+        printRunDetail(space, { ...record, journal: rows }, values);
         return;
     }
     // answer and amend: the manager records the caller as the answerer (SPEC 14.5), so no `--by`
@@ -701,12 +862,48 @@ async function hosted(values, verb, a, b) {
         ...(values.value !== undefined ? { value } : {}),
         ...(values.artifact !== undefined ? { artifact: values.artifact } : {}),
         ...(verb === "amend" ? { amend: true } : {}),
+    }).catch(async (error) => {
+        throw verb === "answer" ? await withMatchingKeys(error, a, b, values, () => ask("run-status", { runId: a, ...endpoint })) : error;
     });
-    runReceipt(verb, space, result, values, a);
+    runReceipt(verb, space, result, values, a, { step: b, ...(values.value !== undefined ? { value } : {}), ...(values.artifact !== undefined ? { artifact: values.artifact } : {}) });
+}
+/** A step key the run has no open request at, answered with the open keys whose step name it matches,
+ *  as `frage` matches `/checkpoint:frage#0`. A run that cannot be read leaves the refusal as it was. */
+export async function withMatchingKeys(error, runId, stepKey, values, read) {
+    if (!(error instanceof CommandFailure) || error.code !== "TARGET_NOT_FOUND")
+        return error;
+    let open;
+    try {
+        open = openRequestKeys(await read());
+    }
+    catch {
+        return error;
+    }
+    const stepName = (key) => /:([^:/#]*)#\d+$/.exec(key)?.[1] ?? key;
+    const word = stepName(stepKey);
+    const matches = open.filter((key) => key !== stepKey && (stepName(key) === word || (word !== "" && (stepName(key).includes(word) || word.includes(stepName(key))))));
+    if (!matches.length)
+        return error;
+    // A step name comes from the program, so it is escaped and quoted before the terminal shows it.
+    const quoted = (key) => `'${oneLine(key).replaceAll("'", `'\\''`)}'`;
+    const remedy = matches.length === 1
+        ? `the open request ${quoted(matches[0])} matches; answer it with \`cotal run answer ${runId} ${quoted(matches[0])} --value '<json>'${values.on ? ` --on ${values.on}` : ""}\``
+        : `the open requests that match are ${matches.map(quoted).join(", ")}; pass one of them as the step`;
+    return new CommandFailure(error.outcome, error.code, error.message, { remedy, target: error.target, ...(error.native ? { native: error.native } : {}) });
 }
 /** `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) {
+    // A mesh the verb cannot resolve or connect to is refused under the refusal's own code, before
+    // any request.
+    try {
+        await workflow(args);
+    }
+    catch (e) {
+        throw isConnectRefusal(e) ? e.failure() : e;
+    }
+}
+async function workflow(args) {
     const { values, verb, a, b } = workflowArguments(args);
     if (verb === "validate" || verb === "plan" || verb === "simulate")
         return offlineWorkflow(verb, a, values);
@@ -753,15 +950,58 @@ export async function runWorkflow(args) {
         await planes.close();
     }
 }
+/** How deep an answer value may nest. Serializing it recurses, and a host runs out of stack a few
+ *  thousand levels down, at a depth that depends on the host, so the bound sits well below that. */
+const ANSWER_VALUE_DEPTH = 1000;
+/** `--value` as the answer record carries it, refused before anything is sent when the record
+ *  would differ from what was typed: JSON keeps only the last of two equal names, writes a number
+ *  past the double range as null, and cannot send a value nested past the serializer's stack. */
+function checkAnswerValue(text, usage) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        usage("--value must be valid JSON");
+    }
+    const refuse = (message) => { throw new CommandFailure("refused", "SCHEMA_INVALID", `${message}; nothing was sent`); };
+    const duplicate = hasDuplicateNames(text);
+    if (duplicate.duplicate)
+        refuse(`--value names "${duplicate.name}" twice in one object, and JSON keeps only the last`);
+    // Iterative, because the value can nest deeper than the stack a recursive walk has.
+    const pending = [{ v: value, depth: 1 }];
+    while (pending.length > 0) {
+        const { v, depth } = pending.pop();
+        if (typeof v === "number" && !Number.isFinite(v))
+            refuse("--value holds a number outside the range JSON carries, which would be recorded as null");
+        if (v === null || typeof v !== "object")
+            continue;
+        if (depth > ANSWER_VALUE_DEPTH)
+            refuse(`--value nests more than ${ANSWER_VALUE_DEPTH} levels deep, deeper than an answer can be sent`);
+        for (const child of Object.values(v))
+            pending.push({ v: child, depth: depth + 1 });
+    }
+}
 /** Public workflow grammar, before catalog preparation or native requests. */
 export function workflowArguments(args) {
     const values = { ...args.values };
     presentationOf(values);
     const [raw = "list", first, second, ...extra] = args.positionals;
     const verb = { list: "ps", show: "journal", check: "migrate" }[raw] ?? raw;
-    const usage = (message) => { throw new CommandFailure("refused", "USAGE_INVALID", message); };
+    // A refusal that names its own fix prints that fix and no help; any other prints the help.
+    const usage = (message, remedy) => { throw new CommandFailure("refused", "USAGE_INVALID", message, remedy === undefined ? {} : { remedy, selfContained: true }); };
     if (extra.length || !["start", "resume", "ps", "journal", "answer", "amend", "revoke", "migrate", "validate", "plan", "simulate", "turns", "yield"].includes(verb))
         usage("choose a declared run command; run it bare to list workflows");
+    // A run id is an id token, so a malformed one is refused here, before any contact, rather than
+    // by whichever plane reads it first.
+    if (["journal", "resume", "revoke", "answer", "amend", "migrate"].includes(verb) && first !== undefined) {
+        try {
+            assertIdToken(first, "run id");
+        }
+        catch {
+            usage(`run ${raw}: ${JSON.stringify(boundedValue(first, SHOWN_VALUE_MAX))} is not a run id, which is 1 to 64 letters, digits, "_" or "-"; cotal run lists them`);
+        }
+    }
     let a = first;
     let b = second;
     if (verb === "start") {
@@ -796,7 +1036,7 @@ export function workflowArguments(args) {
             usage(`run ${verb} requires a run id and step key`);
     }
     else if (!first || second !== undefined)
-        usage(`run ${raw} takes one identifier`);
+        usage(`run ${raw} takes one identifier`, verb === "yield" ? "cotal run turns lists your turns; run cotal run yield <turn-id>" : `cotal run lists the runs; run cotal run ${raw} <run-id>`);
     const scopes = {
         timeout: ["start", "resume"], by: ["answer", "amend", "revoke"], reason: ["revoke"], value: ["answer", "amend"], artifact: ["answer", "amend"],
         "admit-read": ["start"], "admit-publish": ["start"], adopt: ["migrate"], release: ["migrate"], "discard-approvals": ["migrate"],
@@ -804,7 +1044,16 @@ export function workflowArguments(args) {
     for (const [flag, modes] of Object.entries(scopes))
         if (args.values[flag] !== undefined && !modes.includes(verb))
             usage(`--${flag} is not taken by this run command`);
-    if (values.page !== undefined || values.limit !== undefined || values.cursor !== undefined) {
+    // The limit of every checkpoint, ask and turn that sets none of its own, so a zero expires each at once.
+    if (values.timeout !== undefined && !(isDuration(values.timeout) && parseDuration(values.timeout) > 0))
+        usage(isDuration(values.timeout) ? "--timeout must be longer than zero, or every checkpoint, ask and turn that sets no limit of its own expires at once" : `--timeout ${new DurationError(values.timeout).message}`);
+    if (verb === "journal" && values.limit !== undefined) {
+        if (!/^[1-9][0-9]*$/.test(values.limit) || Number(values.limit) > 1000)
+            usage(`run ${raw}: --limit must be between 1 and 1000`);
+        if (values.json)
+            usage(`run ${raw}: --limit bounds the text view, and --json returns the whole journal`);
+    }
+    else if (values.page !== undefined || values.limit !== undefined || values.cursor !== undefined) {
         if (verb !== "ps" || values.local === true || values.page !== true || values.on === undefined)
             usage("diagnostic paging requires run --page --on <instance> without --local");
         if (values.limit !== undefined && (!/^[1-9][0-9]*$/.test(values.limit) || Number(values.limit) > 16))
@@ -816,20 +1065,41 @@ export function workflowArguments(args) {
     }
     if ((values["admit-read"] !== undefined || values["admit-publish"] !== undefined) && values.local !== true)
         usage("admission ceilings belong to the explicit local start");
+    // A ceiling entry is a channel or a channel pattern. One the wire layer would rewrite, such as
+    // `a b`, would admit a channel nobody named.
+    for (const flag of ["admit-read", "admit-publish"]) {
+        const entries = (values[flag] ?? "").split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+        if (entries.length === 1 && entries[0] === "none")
+            continue;
+        for (const entry of entries) {
+            try {
+                assertValidChannel(entry);
+            }
+            catch (error) {
+                usage(`--${flag}: ${oneLine(error.message)}`);
+            }
+        }
+    }
+    // Revoke is local only and needs --by, so its own requirement is named before the hosted --by refusal.
+    // An empty --by or --reason on an otherwise whole revoke names that flag and prints no help.
+    if (verb === "revoke" && values.local === true) {
+        for (const [flag, what] of [["by", "who revokes the run"], ["reason", "why it is revoked"]]) {
+            if (values[flag] !== undefined && !values[flag].trim())
+                throw new CommandFailure("refused", "USAGE_INVALID", `--${flag} is empty; nothing was written`, { remedy: `name ${what}: cotal run revoke ${a} --local --by <who> --reason <text>`, selfContained: true });
+        }
+    }
+    if (verb === "revoke" && (values.local !== true || !values.by?.trim() || !values.reason?.trim()))
+        usage("run revoke requires --local --by <actor> --reason <text> under the existing trust checks");
+    if ((verb === "answer" || verb === "amend") && values.local === true && !values.by)
+        usage(`run ${verb} --local requires --by <who>; nothing was written`, "add --by <who> to name the local answerer");
     if (values.by !== undefined && values.local !== true)
         usage("the hosted manager records the authenticated caller; --by is only for the local path");
     if ((verb === "start" || verb === "resume") && values.endpoint !== undefined && values.local !== true)
         usage("a hosted run uses the manager's endpoint; --endpoint is only for the local path");
-    if (verb === "revoke" && (values.local !== true || !values.by?.trim() || !values.reason?.trim()))
-        usage("run revoke requires --local --by <actor> --reason <text> under the existing trust checks");
-    if (values.value !== undefined) {
-        try {
-            JSON.parse(values.value);
-        }
-        catch {
-            usage("--value must be valid JSON");
-        }
-    }
+    if (values.value !== undefined)
+        checkAnswerValue(values.value, usage);
+    if (values.artifact !== undefined && !values.artifact.trim())
+        usage("--artifact names the artifact the answer cites, so it cannot be empty");
     if (values.handler !== undefined && verb !== "simulate")
         usage("--handler belongs to run simulate");
     if ((values.status !== undefined || values.to !== undefined || values.note !== undefined) && verb !== "yield")
@@ -856,8 +1126,14 @@ export function workflowArguments(args) {
             usage("--on requires the full manager instance id as cotal ps prints it");
         }
     }
-    if ((values.json || values.plain) && values.local && !["ps", "journal"].includes(verb))
-        usage("the local drive does not implement structured or plain receipts; use the hosted form");
+    // A local drive, a revoke and a check print text only. Name the manager's form where one takes the
+    // flag, and the same command without it where none does.
+    if ((values.json || values.plain) && values.local && !["ps", "journal", "answer", "amend"].includes(verb)) {
+        const flag = values.json ? "--json" : "--plain";
+        if (verb === "start" || verb === "resume")
+            usage(`run ${raw} --local prints no ${flag} output`, `drop --local to ${raw} it on the manager, which takes ${flag}: cotal run ${verb === "start" ? "start <file>" : `resume ${a}`} ${flag}`);
+        usage(`run ${raw} prints no ${flag} output`, `run it without ${flag}: ${verb === "revoke" ? `cotal run revoke ${a} --local --by <who> --reason <text>` : `cotal run check ${a} <program>`}`);
+    }
     return { values, verb, ...(a === undefined ? {} : { a }), ...(b === undefined ? {} : { b }) };
 }
 //# sourceMappingURL=run-command.js.map