@astrosheep/keiyaku 4.5.19 → 4.5.21

package/build/src/cli/commands/akuma-invoke.js

@@ -1,11 +1,65 @@
 import { readFile } from "node:fs/promises";
-import { Keiyaku, } from "../../index.js";
+import { squareAssignedParticipantName } from "@astrosheep/square";
+import { emitInitiatingPluginSignal } from "../../plugin/akuma-signals.js";
+import { observeAkumaStatus } from "../../akuma/akuma-observe.js";
+import { AuthorityCorruptionError, Keiyaku, } from "../../index.js";
+import { callObservationStream, waitObservationStream } from "../render/akuma-activity.js";
+import { callObservationHead } from "../render/akuma.js";
 import { killAkuma, tellAkuma, waitAkuma } from "../../library/fleet.js";
 import { localExecutionContext } from "../../akuma/requests.js";
 import { Akuma, Schema } from "../../akuma/index.js";
 import { addressAkuma } from "../../library/address.js";
 import { executionChannel } from "../../akuma/requests.js";
 import { requestForwardedFleetTellAnswer } from "../../akuma/fleet-request.js";
+/** The window a call observes for when the caller gives no `--wait` duration. */
+const CALL_TIMEOUT_MS = 300_000;
+function integrationFailure(error) {
+    return {
+        kind: error instanceof AuthorityCorruptionError ? "authority-corruption" : "infrastructure",
+        diagnostic: error instanceof Error ? error.message : String(error),
+    };
+}
+/** The display context the command result renders with, so live progress rows match the result. */
+function resultContext() {
+    const tty = process.stderr.isTTY === true;
+    return {
+        columns: tty && Number.isInteger(process.stderr.columns) ? process.stderr.columns : 80,
+        color: tty && process.env.NO_COLOR === undefined,
+    };
+}
+function writeProgress(body) {
+    process.stderr.write(body.endsWith("\n") ? body : `${body}\n`);
+}
+/**
+ * The live half of an observe-mode call: the resolved birth opens one identity
+ * frame (never the detached receipt's cwd row), each later observation prints
+ * the settled rows that arrived since the previous one, and the return appends
+ * one conclusion. The stream is append-only, so no final snapshot replays.
+ */
+async function observeCallUntilComplete(command, input, born) {
+    const stream = callObservationStream(resultContext(), callObservationHead(born));
+    try {
+        const status = await observeAkumaStatus(input.path, born.akuma, {
+            timeoutMs: command.timeoutMs ?? CALL_TIMEOUT_MS,
+            observe: (observed) => {
+                const lines = stream.observe(observed);
+                if (lines.length > 0)
+                    writeProgress(lines.join("\n"));
+            },
+        });
+        const conclusion = stream.conclude({ kind: "observed", status });
+        if (conclusion.length > 0)
+            writeProgress(conclusion);
+        return { kind: "observed", status };
+    }
+    catch (error) {
+        const failure = integrationFailure(error);
+        const conclusion = stream.conclude({ kind: "failed", failure });
+        if (conclusion.length > 0)
+            writeProgress(conclusion);
+        return { kind: "failed", failure };
+    }
+}
 async function schemaFromFile(path) {
     try {
         const parsed = JSON.parse(await readFile(path, "utf8"));
@@ -21,21 +75,73 @@ function inputAlias(selector) {
 async function promptBody(command, input) {
     return command.prompt.kind === "stdin" ? await input.readStdin() : command.prompt.value;
 }
+/**
+ * The live half of a local wait: each observation round opens every newly seen
+ * Akuma with its identity frame, then prints only the rows that settled since
+ * the previous round. The first sighting of an Akuma only establishes its
+ * baseline, so an already settled Akuma prints no backlog rows. When the wait
+ * ends, `conclude` prints its closing scoreboard on the same channel.
+ */
+function waitObserver(stream) {
+    return {
+        selected: (selected) => stream.select(selected),
+        observe: (observed) => {
+            const lines = stream.observe(observed);
+            if (lines.length > 0)
+                writeProgress(lines.join("\n"));
+        },
+    };
+}
 async function invokeWait(command, input) {
     const alias = command.akuma.length === 1 ? inputAlias(command.akuma[0]) : undefined;
+    const stream = command.output === "text" ? waitObservationStream(resultContext()) : undefined;
+    const result = await waitAkuma({
+        path: input.path,
+        akuma: command.akuma,
+        ...(input.repo === undefined ? {} : { repo: input.repo }),
+        ...(command.completion === undefined ? {} : { completion: command.completion }),
+        ...(command.timeoutMs === undefined ? {} : { timeoutMs: command.timeoutMs }),
+    }, input.execution ?? localExecutionContext(), stream === undefined ? undefined : waitObserver(stream));
+    if (stream !== undefined && stream.streamed()) {
+        const closing = stream.conclude(result);
+        if (closing.length > 0)
+            writeProgress(closing);
+        return {
+            kind: "akuma",
+            action: "wait",
+            result,
+            streamed: true,
+            ...(alias === undefined ? {} : { alias }),
+        };
+    }
     return {
         kind: "akuma",
         action: "wait",
-        result: await waitAkuma({
-            path: input.path,
-            akuma: command.akuma,
-            ...(input.repo === undefined ? {} : { repo: input.repo }),
-            ...(command.completion === undefined ? {} : { completion: command.completion }),
-            ...(command.timeoutMs === undefined ? {} : { timeoutMs: command.timeoutMs }),
-        }, input.execution ?? localExecutionContext()),
+        result,
         ...(alias === undefined ? {} : { alias }),
     };
 }
+async function inputInitiator(input) {
+    let initiator;
+    try {
+        initiator = squareAssignedParticipantName(input.environment);
+    }
+    catch { }
+    if (initiator === undefined)
+        return {};
+    try {
+        await emitInitiatingPluginSignal({
+            world: input.path,
+            ...(input.settings === undefined ? {} : { settings: input.settings }),
+            initiator,
+            reportDiagnostic: (message) => process.stderr.write(`${message}\n`),
+        });
+    }
+    catch (error) {
+        process.stderr.write(`! plugin initiation: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+    return { initiator };
+}
 async function invokeTell(command, input) {
     const body = await promptBody(command, input);
     if (command.schema !== undefined) {
@@ -45,6 +151,7 @@ async function invokeTell(command, input) {
             akuma: command.akuma,
             ...(input.repo === undefined ? {} : { repo: input.repo }),
         });
+        const initiator = await inputInitiator(input);
         const channel = executionChannel(input.execution);
         const answer = channel.kind === "body-request"
             ? await requestForwardedFleetTellAnswer({
@@ -53,9 +160,11 @@ async function invokeTell(command, input) {
                 body,
                 schema,
                 interrupt: command.interrupt,
+                ...initiator,
             })
             : await Akuma.select(addressed.path, addressed.id).tell(body, {
                 schema,
+                ...initiator,
                 ...(command.interrupt ? { interrupt: true } : {}),
             });
         const alias = inputAlias(command.akuma);
@@ -68,8 +177,10 @@ async function invokeTell(command, input) {
             ...(alias === undefined ? {} : { alias }),
         };
     }
+    const initiator = await inputInitiator(input);
     if (command.interrupt) {
         const result = await Keiyaku.interrupt({
+            ...initiator,
             path: input.path,
             akuma: command.akuma,
             body,
@@ -86,6 +197,7 @@ async function invokeTell(command, input) {
         };
     }
     const result = await tellAkuma({
+        ...initiator,
         path: input.path,
         akuma: command.akuma,
         body,
@@ -151,24 +263,32 @@ export async function invokeAkuma(command, input) {
             const body = await promptBody(command, input);
             const schema = command.schema === undefined ? undefined : await schemaFromFile(command.schema);
             const caller = input.execution === undefined ? Keiyaku : Keiyaku.withExecution({ execution: input.execution });
-            const result = await caller.call({
+            const request = {
+                ...(await inputInitiator(input)),
                 path: input.path,
                 archetype: command.archetype,
                 body,
                 ...(input.home === undefined ? {} : { home: input.home }),
                 ...(input.settings === undefined ? {} : { settings: input.settings }),
-                ...(input.statedCwd === undefined ? {} : { cwd: input.statedCwd }),
-                mode: command.mode,
-                ...(command.timeoutMs === undefined ? {} : { timeoutMs: command.timeoutMs }),
+                ...(input.executionCwd === undefined ? {} : { cwd: input.executionCwd }),
                 ...(input.contract === undefined ? {} : { contract: input.contract }),
                 ...(command.alias === undefined ? {} : { alias: command.alias }),
                 ...(command.allowed === undefined ? {} : { allowed: command.allowed }),
                 ...(schema === undefined ? {} : { schema }),
-            });
+            };
+            const observing = schema === undefined && command.mode === "wait" && command.output === "text";
+            const born = await caller.call(observing
+                ? { ...request, mode: "detach" }
+                : {
+                    ...request,
+                    mode: command.mode,
+                    ...(command.timeoutMs === undefined ? {} : { timeoutMs: command.timeoutMs }),
+                });
+            const result = observing ? { ...born, observation: await observeCallUntilComplete(command, input, born) } : born;
             if (schema !== undefined && command.mode === "wait" && result.schemaAnswer !== undefined) {
                 return { kind: "akuma", action: "call", result, world: input.path, schemaAnswer: result.schemaAnswer };
             }
-            return { kind: "akuma", action: "call", result, world: input.path };
+            return { kind: "akuma", action: "call", result, world: input.path, ...(observing ? { streamed: true } : {}) };
         }
         case "wait":
             return await invokeWait(command, input);

package/build/src/cli/commands/akuma.js

@@ -2,7 +2,7 @@ import { CliUsageError, commandGuide, isBlankInput, usageLine } from "../usage.j
 import { parseAkuId } from "../../akuma/identity.js";
 import { parseDuration as decodeDuration } from "../../duration.js";
 import { parseAkumaAlias, parseAkumaGlob } from "../../identity/selector.js";
-import { decodeAllowedActions } from "../../akuma/allowed.js";
+import { ALLOWED_ACTIONS, decodeAllowedActions } from "../../akuma/allowed.js";
 import { parsePublicHistoryId } from "../../akuma/identity.js";
 const AKUMA_COMMAND_SPECS = {
     call: {
@@ -17,30 +17,45 @@ const AKUMA_COMMAND_SPECS = {
             json: "boolean",
             schema: "value",
         },
-        usage: "call <akuma-name> [--contract <kei/...>] [--alias @name] [--allowed <product.action>]... [--schema <file>] [--wait <duration> | -d | --detach] [--json] (<prompt> | -)",
+        usage: "call <akuma-name> [--contract <kei/...>] [--workdir <path>] [--alias @name] [--allowed <product.action>]... [--schema <file>] [--wait <duration> | -d | --detach] (<prompt> | -)",
         purpose: "Birth an Akuma from <akuma-name> with one prompt.",
         details: [
             "Give <prompt> as one argument, or use - to read stdin.",
             "Default: --wait 5m. An explicit --wait replaces that duration; -d and --detach return after birth.",
             "--contract dispatches the born Akuma to that Contract.",
+            "--workdir selects the execution directory; a relative path is relative to the invocation cwd.",
+            "Without --workdir, a Contract call uses its appointed worktree; an unassociated call uses the invocation cwd.",
             "--alias assigns the world-local @name selector to the born Akuma.",
-            "Repeated --allowed adds actions to the selected Akuma's defaults.",
+            `Legal actions: ${ALLOWED_ACTIONS.join(", ")}.`,
+            "Repeated --allowed adds actions to the selected Akuma's defaults; it never narrows them.",
+            "An omitted Archetype default permits every legal action; an explicit empty default permits none.",
+            "A nested birth is clipped to its direct parent's frozen actions. status <aku/...|@alias> shows the born effective set.",
             "--schema reads a JSON Schema file for the answer contract; stdin remains the prompt source.",
             "With --contract, Dispatch succeeds first. If @name exists, the alias then moves.",
+            "While it waits, settled timeline rows stream on stderr; the final answer is written to stdout once.",
         ].join("\n"),
     },
     wait: {
         arity: "one-or-more",
         stdin: false,
         flags: { any: "boolean", all: "boolean", timeout: "value", json: "boolean" },
-        usage: "wait <akuma-selector>... [--any | --all] [--timeout <duration>] [--json]",
-        purpose: "Wait for one Akuma or an explicitly selected Akuma set.",
+        usage: "wait <akuma-selector>... [--any | --all] [--timeout <duration>]",
+        purpose: "Wait for one Akuma or a selected Akuma set.",
+        details: [
+            "Without --any or --all the mode is any: the wait returns when any selected Akuma completes.",
+            "--all waits until every selected Akuma completes.",
+            "An already completed member counts immediately, so repeating a selection can return at once.",
+            "Identity frames, settled rows, and the closing scoreboard stream on stderr.",
+            "A streamed plural wait leaves stdout empty, and so does a single wait with no answer.",
+            "Only a single selected Akuma that answered writes to stdout, exactly its answer.",
+            "With --json nothing streams and stdout carries the result document.",
+        ].join("\n"),
     },
     tell: {
         arity: 1,
         stdin: true,
         flags: { interrupt: "boolean", schema: "value", json: "boolean" },
-        usage: "tell <aku/...|@alias> [--interrupt] [--schema <file>] [--json] (<prompt> | -)",
+        usage: "tell <aku/...|@alias> [--interrupt] [--schema <file>] (<prompt> | -)",
         purpose: "Send one prompt to an existing Akuma and wake it.",
         details: [
             "Give <prompt> as one argument, or use - to read stdin.",
@@ -52,21 +67,21 @@ const AKUMA_COMMAND_SPECS = {
         arity: 1,
         stdin: false,
         flags: { id: "value", before: "value", since: "value", limit: "value", last: "boolean", json: "boolean" },
-        usage: "history <aku/...|@alias> [--id <historyId> | --before <index> | --since <index>] [--limit <count>] [--last] [--json]\nhistory <kei/...> [--json]",
+        usage: "history <aku/...|@alias> [--id <historyId> | --before <index> | --since <index>] [--limit <count>] [--last]\nhistory <kei/...>",
         purpose: "Read Akuma execution history or one complete Contract journal and Dispatch timeline.",
     },
     fork: {
         arity: 1,
         stdin: false,
         flags: { at: "value", json: "boolean" },
-        usage: "fork <aku/...|@alias> --at <historyId> [--json]",
+        usage: "fork <aku/...|@alias> --at <historyId>",
         purpose: "Fork one Akuma at a retained answered history point.",
     },
     kill: {
         arity: "one-or-more",
         stdin: false,
         flags: { json: "boolean" },
-        usage: "kill <akuma-selector>... [--json]",
+        usage: "kill <akuma-selector>...",
         purpose: "Put down the current Body of an Akuma selector snapshot.",
     },
 };
@@ -194,9 +209,6 @@ function validateSet(value, fail) {
 function parseWait(rawSelectors, flags, output, fail) {
     if (flags.any === true && flags.all === true)
         fail("wait --any and --all are mutually exclusive");
-    if (rawSelectors.length > 1 && flags.any !== true && flags.all !== true) {
-        fail("wait requires --any or --all when selecting multiple Akuma");
-    }
     const completion = flags.any === true ? "any" : flags.all === true ? "all" : undefined;
     return {
         command: "wait",

package/build/src/cli/commands/contract-help.d.ts

@@ -20,7 +20,7 @@ export declare const CONTRACT_COMMAND_SPECS: {
             readonly "fork-of": "value";
             readonly json: "boolean";
         };
-        readonly usage: "bind [--task <task/...>] [--target <ref>] [--after <kei/...> ...] [--gates <name,...>] [--actor <actor>] [--json] - | bind --fork-of <kei/...> [--target <ref>] [--actor <actor>] [--json]";
+        readonly usage: "bind [--task <task/...>] [--target <ref>] [--after <kei/...> ...] [--gates <name,...>] [--actor <actor>] - | bind --fork-of <kei/...> [--target <ref>] [--actor <actor>]";
         readonly purpose: "Create one Contract from stdin Markdown or a sibling fork.";
         readonly details: string;
     };
@@ -34,7 +34,7 @@ export declare const CONTRACT_COMMAND_SPECS: {
             readonly gates: "raw-value";
             readonly json: "boolean";
         };
-        readonly usage: "amend [<contract>|@<contract>] [--after <kei/...> ... | --clear-after] [--gates <name,...>] [--actor <actor>] [--json] [-]";
+        readonly usage: "amend [<contract>|@<contract>] [--after <kei/...> ... | --clear-after] [--gates <name,...>] [--actor <actor>] [-]";
         readonly purpose: "Amend one Contract's document operations or structured terms.";
         readonly details: string;
     };
@@ -48,7 +48,7 @@ export declare const CONTRACT_COMMAND_SPECS: {
             readonly overwrite: "boolean";
             readonly json: "boolean";
         };
-        readonly usage: "deliver [<contract>|@<contract>] [--message <text>] [--include-dirty] [--materialize-conflict] [--overwrite] [--json]";
+        readonly usage: "deliver [<contract>|@<contract>] [--message <text>] [--include-dirty] [--materialize-conflict] [--overwrite]";
         readonly purpose: "Deliver your work as this Contract's candidate.";
         readonly details: string;
     };
@@ -61,7 +61,7 @@ export declare const CONTRACT_COMMAND_SPECS: {
             readonly summary: "value";
             readonly json: "boolean";
         };
-        readonly usage: "review [<contract>|@<contract>] (--satisfied | --unsatisfied) (--summary <text> | -) [--json]";
+        readonly usage: "review [<contract>|@<contract>] (--satisfied | --unsatisfied) (--summary <text> | -)";
         readonly purpose: "Record one review verdict over this Contract's current subject.";
         readonly details: string;
     };
@@ -72,7 +72,7 @@ export declare const CONTRACT_COMMAND_SPECS: {
             readonly actor: "value";
             readonly json: "boolean";
         };
-        readonly usage: "arc [<contract>|@<contract>] [--actor <actor>] [--json] -";
+        readonly usage: "arc [<contract>|@<contract>] [--actor <actor>] -";
         readonly purpose: "Record stdin arc Markdown for one Contract.";
     };
     readonly abandon: {
@@ -83,7 +83,7 @@ export declare const CONTRACT_COMMAND_SPECS: {
             readonly note: "value";
             readonly json: "boolean";
         };
-        readonly usage: "abandon [<contract>|@<contract>] [--note <text>] [--actor <actor>] [--json]";
+        readonly usage: "abandon [<contract>|@<contract>] [--note <text>] [--actor <actor>]";
         readonly purpose: "Abandon one Contract with an optional note.";
     };
     readonly status: {
@@ -92,7 +92,7 @@ export declare const CONTRACT_COMMAND_SPECS: {
         readonly flags: {
             readonly json: "boolean";
         };
-        readonly usage: "status [<contract>|@name|<aku/...>]... [--json]";
+        readonly usage: "status [<contract>|@name|<aku/...>]...";
         readonly purpose: "Read the world status board or one or more Contract and Akuma projections.";
     };
     readonly show: {
@@ -101,7 +101,7 @@ export declare const CONTRACT_COMMAND_SPECS: {
         readonly flags: {
             readonly json: "boolean";
         };
-        readonly usage: "show [<contract>|@<contract>] [--json]";
+        readonly usage: "show [<contract>|@<contract>]";
         readonly purpose: "Read one Contract guidance projection.";
     };
     readonly ls: {
@@ -111,7 +111,7 @@ export declare const CONTRACT_COMMAND_SPECS: {
             readonly limit: "value";
             readonly json: "boolean";
         };
-        readonly usage: "ls task[/] [--limit <count>] [--json]\nls kei[/] [--limit <count>] [--json]\nls aku[/] [--json]\nls aku/<akuma>[/] [--limit <count>] [--json]\nls \"aku/*/*\" [--limit <count>] [--json]";
+        readonly usage: "ls task[/] [--limit <count>]\nls kei[/] [--limit <count>]\nls aku[/]\nls aku/<akuma>[/] [--limit <count>]\nls \"aku/*/*\" [--limit <count>]";
         readonly purpose: "List one identity directory.";
     };
     readonly audit: {
@@ -122,8 +122,8 @@ export declare const CONTRACT_COMMAND_SPECS: {
             readonly diff: "boolean";
             readonly json: "boolean";
         };
-        readonly usage: "audit [<contract>|@<contract>] [--include-dirty] [--diff] [--json]";
-        readonly purpose: "Ask what candidate preparation, Verification, and target placement would do.";
+        readonly usage: "audit [<contract>|@<contract>] [--include-dirty] [--diff]";
+        readonly purpose: "Ask what candidate preparation, Verification, and target placement would do; progress is on stderr.";
     };
     readonly reconcile: {
         readonly positional: "optional";
@@ -132,7 +132,7 @@ export declare const CONTRACT_COMMAND_SPECS: {
             readonly "retry-hooks": "boolean";
             readonly json: "boolean";
         };
-        readonly usage: "reconcile [<contract>|@<contract>] [--retry-hooks] [--json]";
+        readonly usage: "reconcile [<contract>|@<contract>] [--retry-hooks]";
         readonly purpose: "Reconcile one Contract or the invocation world.";
     };
     readonly nuke: {
@@ -142,7 +142,7 @@ export declare const CONTRACT_COMMAND_SPECS: {
             readonly confirm: "value";
             readonly json: "boolean";
         };
-        readonly usage: "nuke [--confirm <WorldRoot>] [--json]";
+        readonly usage: "nuke [--confirm <WorldRoot>]";
         readonly purpose: "Remove Keiyaku-owned data from one confirmed World.";
     };
     readonly settings: {
@@ -151,7 +151,7 @@ export declare const CONTRACT_COMMAND_SPECS: {
         readonly flags: {
             readonly json: "boolean";
         };
-        readonly usage: "settings [--json]";
+        readonly usage: "settings";
         readonly purpose: "Show effective Settings (user + project, read-only)";
     };
     readonly region: {
@@ -161,7 +161,7 @@ export declare const CONTRACT_COMMAND_SPECS: {
             readonly path: "repeat-value";
             readonly json: "boolean";
         };
-        readonly usage: "region [<contract>] [--json]\nregion --path <pattern> [--path <pattern> ...] [--json]";
+        readonly usage: "region [<contract>]\nregion --path <pattern> [--path <pattern> ...]";
         readonly purpose: "Read active declared Contract Regions.";
     };
 };

package/build/src/cli/commands/contract-help.js

@@ -12,21 +12,29 @@ export const CONTRACT_COMMAND_SPECS = {
             "fork-of": "value",
             json: "boolean",
         },
-        usage: "bind [--task <task/...>] [--target <ref>] [--after <kei/...> ...] [--gates <name,...>] [--actor <actor>] [--json] - | bind --fork-of <kei/...> [--target <ref>] [--actor <actor>] [--json]",
+        usage: "bind [--task <task/...>] [--target <ref>] [--after <kei/...> ...] [--gates <name,...>] [--actor <actor>] - | bind --fork-of <kei/...> [--target <ref>] [--actor <actor>]",
         purpose: "Create one Contract from stdin Markdown or a sibling fork.",
         details: [
+            "--gates <name,...> accepts gate words and configured bundle names together.",
+            "A matching bundle expands; otherwise the name is a literal gate. Duplicates",
+            "are removed in first-seen order. Gate words match ^[a-z][a-z0-9-]{0,63}$.",
+            "Omitting --gates selects gates.default, or reviewed when no default exists.",
+            '--gates "" explicitly binds without gates; --gates reviewed needs no bundle.',
+            "",
             "stdin is Contract Markdown:",
             "  # <title>",
             "  ## Context       motivation, authority, baseline, and boundaries",
             "  ## Objective    one observable end state",
             "  ## Design       closed decisions and ordering",
-            "  ## Region       one fenced path-pattern declaration",
+            "  ## Region       intended path patterns as fenced lines, list items, or bare lines",
             "  ## Criteria     one or more ### <criterion> entries",
             "  ## Verification optional fenced executor declarations",
             "",
-            "Region uses one closed fence with no info string or exactly 'txt'; put one",
-            "repository-relative path pattern on each nonblank line. A trailing '/'",
-            "is directory shorthand for 'path/**'.",
+            "Region accepts intended path patterns as fenced lines, list items, or bare",
+            "lines; the three forms union. Put one repository-relative path pattern on",
+            "each nonblank line. A trailing '/' is directory shorthand for 'path/**'.",
+            "A pattern containing whitespace binds with a warning. A fence carries no",
+            "info string or exactly 'txt'.",
             "",
             "Verification uses one or more closed bash, zsh, or pwsh fences. Its fence",
             "may add timeout=<integer><ms|s|m|h>; the section contains no other prose.",
@@ -37,9 +45,14 @@ export const CONTRACT_COMMAND_SPECS = {
         positional: "optional",
         stdin: "optional",
         flags: { actor: "value", after: "repeat-value", "clear-after": "boolean", gates: "raw-value", json: "boolean" },
-        usage: "amend [<contract>|@<contract>] [--after <kei/...> ... | --clear-after] [--gates <name,...>] [--actor <actor>] [--json] [-]",
+        usage: "amend [<contract>|@<contract>] [--after <kei/...> ... | --clear-after] [--gates <name,...>] [--actor <actor>] [-]",
         purpose: "Amend one Contract's document operations or structured terms.",
         details: [
+            "--gates <name,...> replaces gates using gate words and configured bundle names.",
+            "A matching bundle expands; otherwise the name is a literal gate. Duplicates",
+            "are removed in first-seen order. Gate words match ^[a-z][a-z0-9-]{0,63}$.",
+            'Omitting --gates leaves gates unchanged; --gates "" clears them.',
+            "",
             "  ## Context|Objective|Design|Region|Criteria|Verification|<extension>  (replace, or add new extension)",
             "  ## Replace: Context|Objective|Design|Region|Criteria|Verification|<extension>",
             "  ## Append: Context|Objective|Design|Criteria|<extension>",
@@ -58,13 +71,14 @@ export const CONTRACT_COMMAND_SPECS = {
             overwrite: "boolean",
             json: "boolean",
         },
-        usage: "deliver [<contract>|@<contract>] [--message <text>] [--include-dirty] [--materialize-conflict] [--overwrite] [--json]",
+        usage: "deliver [<contract>|@<contract>] [--message <text>] [--include-dirty] [--materialize-conflict] [--overwrite]",
         purpose: "Deliver your work as this Contract's candidate.",
         details: [
             "The subject is the whole Contract. An Arc names the chapter you are in — it",
             "frames the work, it never shrinks what the Contract accepts. Finishing a chapter",
             "is progress; deliver is the different claim that the worktree, as it stands, is",
             "the Contract's candidate.",
+            "Verification, placement, and cleanup progress is printed to stderr; stdout stays one final text or JSON result.",
             "",
             "A clean worktree delivers its HEAD. --include-dirty captures the complete final",
             "non-ignored worktree bytes through a private index, even while the shared index",
@@ -103,7 +117,7 @@ export const CONTRACT_COMMAND_SPECS = {
         positional: "optional",
         stdin: "optional",
         flags: { satisfied: "boolean", unsatisfied: "boolean", summary: "value", json: "boolean" },
-        usage: "review [<contract>|@<contract>] (--satisfied | --unsatisfied) (--summary <text> | -) [--json]",
+        usage: "review [<contract>|@<contract>] (--satisfied | --unsatisfied) (--summary <text> | -)",
         purpose: "Record one review verdict over this Contract's current subject.",
         details: [
             "You are judging the whole Contract, not the current Arc. The subject is whatever",
@@ -126,76 +140,77 @@ export const CONTRACT_COMMAND_SPECS = {
             "--summary is your testimony, not decoration. Satisfied: the conclusion that the",
             "whole Contract is complete, and the evidence it rests on. Unsatisfied: the specific",
             "blocker, missing evidence, or unmet term.",
+            "Confirmed admission and later work are shown on stderr; stdout remains one final result.",
         ].join("\n"),
     },
     arc: {
         positional: "optional",
         stdin: "required",
         flags: { actor: "value", json: "boolean" },
-        usage: "arc [<contract>|@<contract>] [--actor <actor>] [--json] -",
+        usage: "arc [<contract>|@<contract>] [--actor <actor>] -",
         purpose: "Record stdin arc Markdown for one Contract.",
     },
     abandon: {
         positional: "optional",
         stdin: "none",
         flags: { actor: "value", note: "value", json: "boolean" },
-        usage: "abandon [<contract>|@<contract>] [--note <text>] [--actor <actor>] [--json]",
+        usage: "abandon [<contract>|@<contract>] [--note <text>] [--actor <actor>]",
         purpose: "Abandon one Contract with an optional note.",
     },
     status: {
         positional: "optional",
         stdin: "none",
         flags: { json: "boolean" },
-        usage: "status [<contract>|@name|<aku/...>]... [--json]",
+        usage: "status [<contract>|@name|<aku/...>]...",
         purpose: "Read the world status board or one or more Contract and Akuma projections.",
     },
     show: {
         positional: "optional",
         stdin: "none",
         flags: { json: "boolean" },
-        usage: "show [<contract>|@<contract>] [--json]",
+        usage: "show [<contract>|@<contract>]",
         purpose: "Read one Contract guidance projection.",
     },
     ls: {
         positional: "optional",
         stdin: "none",
         flags: { limit: "value", json: "boolean" },
-        usage: 'ls task[/] [--limit <count>] [--json]\nls kei[/] [--limit <count>] [--json]\nls aku[/] [--json]\nls aku/<akuma>[/] [--limit <count>] [--json]\nls "aku/*/*" [--limit <count>] [--json]',
+        usage: 'ls task[/] [--limit <count>]\nls kei[/] [--limit <count>]\nls aku[/]\nls aku/<akuma>[/] [--limit <count>]\nls "aku/*/*" [--limit <count>]',
         purpose: "List one identity directory.",
     },
     audit: {
         positional: "optional",
         stdin: "none",
         flags: { "include-dirty": "boolean", diff: "boolean", json: "boolean" },
-        usage: "audit [<contract>|@<contract>] [--include-dirty] [--diff] [--json]",
-        purpose: "Ask what candidate preparation, Verification, and target placement would do.",
+        usage: "audit [<contract>|@<contract>] [--include-dirty] [--diff]",
+        purpose: "Ask what candidate preparation, Verification, and target placement would do; progress is on stderr.",
     },
     reconcile: {
         positional: "optional",
         stdin: "none",
         flags: { "retry-hooks": "boolean", json: "boolean" },
-        usage: "reconcile [<contract>|@<contract>] [--retry-hooks] [--json]",
+        usage: "reconcile [<contract>|@<contract>] [--retry-hooks]",
         purpose: "Reconcile one Contract or the invocation world.",
     },
     nuke: {
         positional: "none",
         stdin: "none",
         flags: { confirm: "value", json: "boolean" },
-        usage: "nuke [--confirm <WorldRoot>] [--json]",
+        usage: "nuke [--confirm <WorldRoot>]",
         purpose: "Remove Keiyaku-owned data from one confirmed World.",
     },
     settings: {
         positional: "none",
         stdin: "none",
         flags: { json: "boolean" },
-        usage: "settings [--json]",
+        usage: "settings",
         purpose: "Show effective Settings (user + project, read-only)",
     },
     region: {
         positional: "optional",
         stdin: "none",
         flags: { path: "repeat-value", json: "boolean" },
-        usage: "region [<contract>] [--json]\nregion --path <pattern> [--path <pattern> ...] [--json]",
+        usage: "region [<contract>]\nregion --path <pattern> [--path <pattern> ...]",
         purpose: "Read active declared Contract Regions.",
     },
 };
@@ -220,6 +235,17 @@ export function renderContractHelp(command) {
             "Each entry is validated by the feature that reads it. A rejected",
             "value's diagnostic states the expected shape.",
             "",
+            "Akuma definitions are Markdown files, one per name:",
+            "  user      ~/.keiyaku/akuma/<name>.md",
+            "  project   <WorldRoot>/.keiyaku/akuma/<name>.md",
+            "A project file wholly shadows the same-name user file. YAML",
+            "frontmatter selects the provider and may declare base, model,",
+            "effort, readonly, network, sandbox, allowed, systemPromptMode, and",
+            "description; the body is an optional system prompt. sandbox:",
+            "full-access disables a supporting provider's native command",
+            "sandbox for future births; it grants no extra operating-system",
+            "permissions and cannot combine with readonly or network: disabled.",
+            "",
             usageLine(spec.usage),
         ].join("\n");
     }

package/build/src/cli/commands/contract-invoke.d.ts

@@ -1,3 +1,4 @@
+import type { ExecutionEvent } from "../../library/execution.js";
 import type { InvocationResult } from "../result.js";
 import type { ParsedCommand } from "../parse.js";
 import type { WorktreeHooks } from "../../library/configuration.js";
@@ -11,6 +12,8 @@ type ContractMutation = Extract<ParsedCommand, {
 type InvocationEdge = Readonly<{
     environment: NodeJS.ProcessEnv;
     readStdin: () => Promise<string>;
+    signal?: AbortSignal;
+    progress?: (events: AsyncIterable<ExecutionEvent>) => Promise<void>;
 }>;
 export type ContractMutationInput = Readonly<{
     parsed: ContractMutation;