@astrosheep/keiyaku 4.6.15 → 4.6.17

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

@@ -13,7 +13,7 @@ export const CONTRACT_COMMAND_SPECS = {
             "fork-of": "value",
             json: "boolean",
         },
-        usage: "bind [--debt <debt/...>] [--target <ref> | --no-target] [--after <kei/...> ...] [--gates <name,...>] [--actor <actor>] - | bind --fork-of <kei/...> [--target <ref> | --no-target] [--actor <actor>]",
+        usage: "bind [--debt <debt/...>] [--target <ref> | --no-target] [--after <kei/...>]... [--gates <name,...>] [--actor <actor>] [--repo <path>] -\nbind --fork-of <kei/...> [--target <ref> | --no-target] [--actor <actor>] [--repo <path>]",
         purpose: "Create a Contract from stdin Markdown or copy an existing Contract as a starting point.",
         details: [
             "--target names one existing local branch literally; it is never created and never",
@@ -64,7 +64,7 @@ export const CONTRACT_COMMAND_SPECS = {
         positional: "optional",
         stdin: "optional",
         flags: { actor: "value", after: "repeat", "clear-after": "boolean", gates: "raw-value", json: "boolean" },
-        usage: "amend [<contract>|@<contract>] [--after <kei/...> ... | --clear-after] [--gates <name,...>] [--actor <actor>] [-]",
+        usage: "amend [<contract>|@<contract>] [--after <kei/...> [--after <kei/...>]... | --clear-after] [--gates <name,...>] [--actor <actor>] [--repo <path>] [-]",
         purpose: "Change a Contract's document, prerequisites, or acceptance gates.",
         details: [
             "Gates are acceptance obligations checked at placement: reviewed awaits a",
@@ -97,7 +97,7 @@ export const CONTRACT_COMMAND_SPECS = {
             overwrite: "boolean",
             json: "boolean",
         },
-        usage: "deliver [<contract>|@<contract>] [--message <text>] [--include-dirty] [--materialize-conflict] [--overwrite] | deliver [<contract>|@<contract>] --dry-run [--include-dirty] [--show-diff]",
+        usage: "deliver [<contract>|@<contract>] [--message <text>] [--include-dirty] [--materialize-conflict] [--overwrite] [--repo <path>]\ndeliver [<contract>|@<contract>] --dry-run [--include-dirty] [--show-diff] [--repo <path>]",
         purpose: "Submit work for a Contract and integrate it when its requirements are met.",
         details: [
             "The Contract, not the current Arc, sets what delivery must satisfy. An Arc records progress; it does not narrow acceptance.",
@@ -122,7 +122,7 @@ export const CONTRACT_COMMAND_SPECS = {
         positional: "optional",
         stdin: "optional",
         flags: { actor: "value", satisfied: "boolean", unsatisfied: "boolean", summary: "value", json: "boolean" },
-        usage: "review [<contract>|@<contract>] (--satisfied | --unsatisfied) (--summary <text> | -) [--actor <actor>]",
+        usage: "review [<contract>|@<contract>] (--satisfied | --unsatisfied) (--summary <text> | -) [--actor <actor>] [--repo <path>]",
         purpose: "Record whether a Contract meets its acceptance criteria.",
         details: [
             "A review checks the whole Contract, not just one Arc. After delivery it checks the candidate; before delivery it checks the current Contract and worktree, but cannot integrate.",
@@ -136,7 +136,7 @@ export const CONTRACT_COMMAND_SPECS = {
         positional: "optional",
         stdin: "required",
         flags: { actor: "value", json: "boolean" },
-        usage: "arc [<contract>|@<contract>] [--actor <actor>] -",
+        usage: "arc [<contract>|@<contract>] [--actor <actor>] [--repo <path>] -",
         purpose: "Name the current chapter of a Contract's story (a story arc).",
         details: [
             "stdin is one nonblank H1 chapter name followed by any Markdown body, including none:",
@@ -149,14 +149,14 @@ export const CONTRACT_COMMAND_SPECS = {
         positional: "optional",
         stdin: "none",
         flags: { actor: "value", note: "value", json: "boolean" },
-        usage: "abandon [<contract>|@<contract>] [--note <text>] [--actor <actor>]",
-        purpose: "End work on a Contract without delivering it; optionally record why.",
+        usage: "abandon [<contract>|@<contract>] [--note <text>] [--actor <actor>] [--repo <path>]",
+        purpose: "End work on a Contract without accepting it; optionally record why.",
     },
     show: {
         positional: "optional",
         stdin: "none",
         flags: { json: "boolean" },
-        usage: "show [<contract>|@<contract>]",
+        usage: "show [<contract>|@<contract>] [--repo <path>]",
         purpose: "Read one Contract's guidance.",
         details: [
             "Accepts a complete Contract identity or exact @<contract> short selector.",
@@ -183,12 +183,12 @@ export const CONTRACT_COMMAND_SPECS = {
         positional: "optional",
         stdin: "none",
         flags: { limit: "value", json: "boolean", mine: "boolean", caller: "value" },
-        usage: 'ls debt[/] [--limit <count>]\nls kei[/] [--limit <count>]\nls aku[/] [--limit <count>]\nls aku/<name>[/] [--limit <count>]\nls "aku/<name>/*" [--limit <count>]\nls "aku/*/*" [--limit <count>]\nls ["aku/*/*"] --mine\nls ["aku/*/*"] --caller <integration>:<id> | aku/<name>/<suffix>',
+        usage: 'ls debt[/] [--limit <count>]\nls debt/<namespace>/ [--limit <count>]\nls kei[/] [--limit <count>]\nls aku[/] [--limit <count>]\nls aku/<name>[/] [--limit <count>]\nls "aku/<name>/*" [--limit <count>]\nls "aku/*/*" [--limit <count>]\nls [aku/<name>[/] | "aku/<name>/*" | "aku/*/*"] (--mine | --caller (<integration>:<id> | aku/<name>/<suffix>)) [--limit <count>]',
         purpose: "List debts (ls debt), contracts (ls kei), or akumas (ls aku).",
         details: [
             "ls kei lists active Contracts; accepted and abandoned ones leave the list, and their record stays in history and Git.",
-            "ls aku/ lists the callable Akuma-name catalog; ls aku/<name> lists the living Akumas under one name.",
-            'ls "aku/<name>/*" is the same living set in glob form; ls "aku/*/*" lists every living Akuma.',
+            "ls aku/ lists the callable Akuma-name catalog; ls aku/<name> lists recent retained Akuma instances under one name.",
+            'ls "aku/<name>/*" is the same roster in glob form; ls "aku/*/*" lists recent retained Akuma instances across names.',
             "--mine selects the caller identity of this process and lists that caller's direct and transitive descendants in this World.",
             "--caller selects an explicit caller instead; both selectors are World-local and refuse for Contract, Debt, or Akuma-name catalogues.",
             "Descendant rows name their immediate calling Akuma beside the row.",
@@ -198,7 +198,7 @@ export const CONTRACT_COMMAND_SPECS = {
         positional: "optional",
         stdin: "none",
         flags: { "retry-hooks": "boolean", json: "boolean" },
-        usage: "reconcile [<contract>|@<contract>] [--retry-hooks]",
+        usage: "reconcile [<contract>|@<contract>] [--retry-hooks] [--repo <path>]",
         purpose: "Restore a Contract's Git workspace from its recorded state, or all of this World's.",
         details: "--retry-hooks reruns configured setup commands even when a Contract workspace already exists; otherwise they run when reconciliation creates it.",
     },
@@ -221,7 +221,7 @@ export const CONTRACT_COMMAND_SPECS = {
         positional: "optional",
         stdin: "none",
         flags: { path: "repeat", json: "boolean" },
-        usage: "region [<contract>]\nregion --path <pattern> [--path <pattern> ...]",
+        usage: "region [<contract>] [--repo <path>]\nregion --path <pattern> [--path <pattern>]... [--repo <path>]",
         purpose: "Show declared Contract write patterns — all, one Contract's, or those overlapping given paths.",
         details: "Check overlap before starting parallel work.",
     },
@@ -248,8 +248,8 @@ export function renderContractHelp(command) {
             "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",
+            "  user      ~/.keiyaku/akumas/<name>.md",
+            "  project   <WorldRoot>/.keiyaku/akumas/<name>.md",
             "A project file wholly shadows the same-name user file. YAML",
             "frontmatter selects the provider and may declare base, model,",
             "effort, network, allowed, systemPromptMode, and description; the body is",
@@ -261,7 +261,7 @@ export function renderContractHelp(command) {
             '    "config": { "url": "ws://127.0.0.1:6767/ws", "provider": "claude" }',
             "  } } }",
             "The native provider id is bare (claude, codex, pi), not provider/model.",
-            "Example .keiyaku/akuma/paseo-worker.md frontmatter:",
+            "Example .keiyaku/akumas/paseo-worker.md frontmatter:",
             "  ---",
             "  provider: paseo",
             "  model: <native-model-id>",

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

@@ -1,5 +1,6 @@
 import type { CliCoordinates } from "../coordinates.js";
 import type { CliRuntime } from "../runtime.js";
+import { type CliOutcome } from "../streams.js";
 import type { ParsedContractCommand } from "./contract-grammar.js";
 /**
  * The one bind-document admission that runs before coordinate resolution, so a malformed document
@@ -16,6 +17,6 @@ type ParsedContractHistory = Readonly<{
     full: boolean;
     output: "text" | "json";
 }>;
-export declare function runContractHistoryCommand(command: ParsedContractHistory, coordinates: CliCoordinates): Promise<number>;
-export declare function runContractCommand(command: ParsedContractCommand, coordinates: CliCoordinates, runtime: CliRuntime): Promise<number>;
+export declare function runContractHistoryCommand(command: ParsedContractHistory, coordinates: CliCoordinates): Promise<CliOutcome>;
+export declare function runContractCommand(command: ParsedContractCommand, coordinates: CliCoordinates, runtime: CliRuntime): Promise<CliOutcome>;
 export {};

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

@@ -15,7 +15,7 @@ import { snapshotText } from "../render/akuma-activity.js";
 import { renderAkumaCatalogue, renderArchetypeCatalogue, renderContractCatalogue, renderDebtCatalogue, } from "../render/catalog.js";
 import { renderAccepted, renderContractHistory, renderRetry } from "../render/contract.js";
 import { renderKanshiCategoryText, renderKanshiText } from "../render/kanshi.js";
-import { nukeExitCode, renderNukeText } from "../render/nuke.js";
+import { nukeOutcome, renderNukeText } from "../render/nuke.js";
 import { reconcileHasFailure, renderReconcile } from "../render/reconcile.js";
 import { renderConflictMaterialized, renderRefusal } from "../render/refusal.js";
 import { renderRegionText } from "../render/region.js";
@@ -92,9 +92,6 @@ function deliverRefusalProjection(refusal) {
     const submodules = "submodules" in refusal && Array.isArray(refusal.submodules) ? refusal.submodules : [];
     return { ...refusal, option: { flag: "--include-dirty", available: submodules.length === 0 } };
 }
-function contractExitCode(answer) {
-    return answer.kind === "refused" ? 1 : answer.kind === "retry" ? 2 : 0;
-}
 function renderContractAnswer(answer, project, context) {
     switch (answer.kind) {
         case "handoff":
@@ -108,8 +105,8 @@ function renderContractAnswer(answer, project, context) {
     }
 }
 async function finishContractAnswer(answer, output, project) {
-    const text = () => renderContractAnswer(answer, project, displayContext());
-    return emit(output, answer, text, contractExitCode(answer));
+    const outcome = answer.kind === "refused" ? "refused" : answer.kind === "retry" ? "retryable" : "accepted";
+    return emit(output, answer, () => renderContractAnswer(answer, project, displayContext()), outcome);
 }
 async function selectedContract(repo, selector, scope) {
     const id = await resolveContractId(repo, selector, scope);
@@ -125,16 +122,6 @@ async function existingSeat(command, coordinates, runtime, library) {
         ...(actor === undefined ? {} : { actor }),
     };
 }
-/** One composition for every mutation leaf; gates, hooks, and freshness derive lazily inside it. */
-async function contractLibrary(command, execution, configuration, runtime) {
-    const actor = executionChannel(execution).kind === "local" && ["deliver", "review"].includes(command.command)
-        ? actorFromEdge(undefined, runtime.environment)
-        : undefined;
-    return composeContractLibrary(execution, createKeiyakuHandle, {
-        ...(configuration === undefined ? {} : { settings: configuration }),
-        ...(actor === undefined ? {} : { actor }),
-    });
-}
 async function runBind(command, input, library) {
     const { coordinates, runtime } = input;
     const repo = requiredRepo(coordinates);
@@ -164,7 +151,7 @@ async function runBind(command, input, library) {
             return await finishContractAnswer(answer, command.output);
         const draft = await bindDraftReceipt(coordinates.establishWorld, markdown);
         const text = () => renderRefusal(refusedInvocation(answer), draft, displayContext());
-        return emit(command.output, answer, text, 1);
+        return emit(command.output, answer, text, "refused");
     }
     catch (error) {
         if (error instanceof Error && "executionReceipt" in error)
@@ -193,18 +180,20 @@ async function runAmend(command, input, seat) {
     return await finishContractAnswer(answer, command.output);
 }
 async function runDeliver(command, runtime, seat) {
-    if (command.dryRun)
-        return await runDeliveryPreview(command, runtime, seat);
     const driver = command.output === "text" ? await runtime.progress() : undefined;
     let answer;
     try {
-        answer = await seat.contract.deliver({
-            ...(command.message === undefined ? {} : { message: command.message }),
-            includeDirty: command.includeDirty,
-            materializeConflict: command.materializeConflict,
-            overwrite: command.overwrite,
-            ...(runtime.signal === undefined ? {} : { signal: runtime.signal }),
-        }, { ...(driver === undefined ? {} : { observe: driver.observe }) });
+        const progress = { ...(driver === undefined ? {} : { observe: driver.observe }) };
+        const signal = { ...(runtime.signal === undefined ? {} : { signal: runtime.signal }) };
+        answer = command.dryRun
+            ? await seat.contract.previewDelivery({ includeDirty: command.includeDirty, showDiff: command.showDiff, ...signal }, progress)
+            : await seat.contract.deliver({
+                ...(command.message === undefined ? {} : { message: command.message }),
+                includeDirty: command.includeDirty,
+                materializeConflict: command.materializeConflict,
+                overwrite: command.overwrite,
+                ...signal,
+            }, progress);
     }
     finally {
         if (driver !== undefined)
@@ -242,7 +231,7 @@ async function runArc(command, runtime, seat) {
             throw error;
         const refusal = { kind: "invalid-document", diagnostic: error.message };
         const refused = { kind: "refused", operation: "arc", contract: seat.id, refusal };
-        return emit(command.output, refused, () => renderRefusal(refused, undefined, displayContext()), 1);
+        return emit(command.output, refused, () => renderRefusal(refused, undefined, displayContext()), "refused");
     }
     const answer = await seat.contract.arc({
         markdown,
@@ -257,24 +246,15 @@ async function runAbandon(command, seat) {
     });
     return await finishContractAnswer(answer, command.output);
 }
-async function runDeliveryPreview(command, runtime, seat) {
-    const driver = command.output === "text" ? await runtime.progress() : undefined;
-    let answer;
-    try {
-        answer = await seat.contract.previewDelivery({
-            includeDirty: command.includeDirty,
-            showDiff: command.showDiff,
-            ...(runtime.signal === undefined ? {} : { signal: runtime.signal }),
-        }, { ...(driver === undefined ? {} : { observe: driver.observe }) });
-    }
-    finally {
-        if (driver !== undefined)
-            await driver.finish().catch(() => undefined);
-    }
-    return await finishContractAnswer(answer, command.output, deliverRefusalProjection);
-}
 async function runContractMutation(command, input) {
-    const library = await contractLibrary(command, input.execution, input.configuration, input.runtime);
+    const { execution, configuration, runtime } = input;
+    const actor = executionChannel(execution).kind === "local" && ["deliver", "review"].includes(command.command)
+        ? actorFromEdge(undefined, runtime.environment)
+        : undefined;
+    const library = composeContractLibrary(execution, createKeiyakuHandle, {
+        ...(configuration === undefined ? {} : { settings: configuration }),
+        ...(actor === undefined ? {} : { actor }),
+    });
     if (command.command === "bind")
         return await runBind(command, input, library);
     const seat = await existingSeat(command, input.coordinates, input.runtime, library);
@@ -296,7 +276,7 @@ function statusRefusal(operation, contract) {
 }
 async function runSettings(coordinates, home, output) {
     const value = await settingsAt(coordinates.world ?? undefined, home);
-    return emit(output, settingsJsonValue(value), () => renderSettingsText(value, displayContext().columns), 0);
+    return emit(output, settingsJsonValue(value), () => renderSettingsText(value, displayContext().columns), "accepted");
 }
 async function runNuke(command, coordinates) {
     if (coordinates.world === null)
@@ -305,7 +285,7 @@ async function runNuke(command, coordinates) {
         world: coordinates.world,
         ...(command.confirm === undefined ? {} : { confirm: command.confirm }),
     });
-    return emit(command.output, result, () => renderNukeText(result), nukeExitCode(result));
+    return emit(command.output, result, () => renderNukeText(result), nukeOutcome(result));
 }
 async function runLs(command, coordinates, home, runtime) {
     const query = command.query;
@@ -314,7 +294,7 @@ async function runLs(command, coordinates, home, runtime) {
             repo: requiredRepo(coordinates),
             ...(query.limit === undefined ? {} : { limit: query.limit }),
         });
-        return emit(command.output, list, () => renderContractCatalogue(list), 0);
+        return emit(command.output, list, () => renderContractCatalogue(list), "accepted");
     }
     if (query.kind === "archetypes") {
         const list = await listArchetypeDefinitions({
@@ -322,7 +302,7 @@ async function runLs(command, coordinates, home, runtime) {
             ...(query.limit === undefined ? {} : { limit: query.limit }),
             ...(home === undefined ? {} : { home }),
         });
-        return emit(command.output, list, () => renderArchetypeCatalogue(list), 0);
+        return emit(command.output, list, () => renderArchetypeCatalogue(list), "accepted");
     }
     if (coordinates.world === null)
         throw new CliUsageError("no Keiyaku world contains the invocation cwd");
@@ -334,7 +314,7 @@ async function runLs(command, coordinates, home, runtime) {
         });
         if (listed.kind !== "accepted")
             throw new Error("Debt list did not return an accepted observation");
-        return emit(command.output, listed, () => renderDebtCatalogue(listed.value, query.namespace ?? []), 0);
+        return emit(command.output, listed, () => renderDebtCatalogue(listed.value, query.namespace ?? []), "accepted");
     }
     const caller = await lsCaller(query.caller, coordinates, runtime);
     const listed = await Akumas.of(coordinates.world).list({
@@ -342,7 +322,7 @@ async function runLs(command, coordinates, home, runtime) {
         ...(query.limit === undefined ? {} : { limit: query.limit }),
         ...(caller === undefined ? {} : { caller }),
     });
-    return emit(command.output, listed, () => renderAkumaCatalogue(listed, query.archetype ?? null, caller), 0);
+    return emit(command.output, listed, () => renderAkumaCatalogue(listed, query.archetype ?? null, caller), "accepted");
 }
 /** `--mine` is the process caller identity; `--caller` names the same coordinate explicitly. */
 async function lsCaller(selection, coordinates, runtime) {
@@ -400,9 +380,9 @@ async function runShow(command, coordinates) {
     const guidance = await selected.contract.guidance();
     if (guidance === null) {
         const refusal = statusRefusal(command.command, selected.id);
-        return emit(command.output, null, () => renderRefusal(refusal, undefined, displayContext()), 1);
+        return emit(command.output, null, () => renderRefusal(refusal, undefined, displayContext()), "refused");
     }
-    return emit(command.output, guidance, () => guidance, 0);
+    return emit(command.output, guidance, () => guidance, "accepted");
 }
 async function runStatusSelection(command, coordinates) {
     const selectors = command.selectors;
@@ -426,7 +406,7 @@ async function runStatusSelection(command, coordinates) {
         if (command.output === "text")
             blocks.push(resolved.project());
     }
-    return emit(command.output, values, () => blocks.join("\n\n"), 0);
+    return emit(command.output, values, () => blocks.join("\n\n"), "accepted");
 }
 async function runStatusCategory(command, coordinates) {
     if (command.category === "contract")
@@ -437,7 +417,7 @@ async function runStatusCategory(command, coordinates) {
         category: command.category,
         ...(command.limit === undefined ? {} : { limit: command.limit }),
     });
-    return emit(command.output, report, () => renderKanshiCategoryText(report, displayContext()), 0);
+    return emit(command.output, report, () => renderKanshiCategoryText(report, displayContext()), "accepted");
 }
 async function runStatusIdentity(command, coordinates) {
     if (command.contract === undefined) {
@@ -445,11 +425,11 @@ async function runStatusIdentity(command, coordinates) {
             world: coordinates.world,
             ...(coordinates.repo === undefined ? {} : { repo: coordinates.repo }),
         });
-        return emit(command.output, report, () => renderKanshiText(report, displayContext(), "world"), 0);
+        return emit(command.output, report, () => renderKanshiText(report, displayContext(), "world"), "accepted");
     }
     if (command.contract.startsWith("@")) {
         const resolved = await namedStatus(command.contract, coordinates, await observeNamedAddress({ world: coordinates.world, repo: coordinates.repo ?? null }));
-        return emit(command.output, resolved.value, () => resolved.project(), 0);
+        return emit(command.output, resolved.value, () => resolved.project(), "accepted");
     }
     if (command.contract.startsWith("kei/")) {
         const repo = requiredRepo(coordinates);
@@ -457,9 +437,9 @@ async function runStatusIdentity(command, coordinates) {
         const report = await kanshi({ world: coordinates.world, repo, contract });
         if (report.contracts.kind === "present" && report.contracts.value.rows.length === 0) {
             const refusal = statusRefusal("status", contract);
-            return emit(command.output, refusal.refusal, () => renderRefusal(refusal, undefined, displayContext()), 1);
+            return emit(command.output, refusal.refusal, () => renderRefusal(refusal, undefined, displayContext()), "refused");
         }
-        return emit(command.output, report, () => renderKanshiText(report, displayContext(), "contract"), 0);
+        return emit(command.output, report, () => renderKanshiText(report, displayContext(), "contract"), "accepted");
     }
     throw new CliUsageError(`contract selector must use kei/: ${command.contract}`);
 }
@@ -470,13 +450,13 @@ async function runStatus(command, coordinates) {
         return await runStatusSelection({ ...command, selectors: command.selectors }, coordinates);
     if (command.akuma === true && command.contract !== undefined) {
         const resolved = await readAkumaStatus(command.contract, undefined, coordinates);
-        return emit(command.output, resolved.value, () => resolved.project(), 0);
+        return emit(command.output, resolved.value, () => resolved.project(), "accepted");
     }
     return await runStatusIdentity(command, coordinates);
 }
 async function runRegion(command, coordinates) {
     const repo = requiredRepo(coordinates);
-    const emitSection = (section) => emit(command.output, section, () => renderRegionText(section), 0);
+    const emitSection = (section) => emit(command.output, section, () => renderRegionText(section), "accepted");
     if (command.paths !== undefined) {
         const report = await kanshi({ world: coordinates.world, repo, region: { kind: "path", patterns: command.paths } });
         return emitSection(report.region ?? { kind: "absent" });
@@ -495,7 +475,7 @@ async function runRegion(command, coordinates) {
             writeJson(refusal);
         else
             writeStdout(renderRefusal({ operation: "region", contract, refusal }, undefined, displayContext()));
-        return 1;
+        return "refused";
     }
     if (report.region?.kind !== "present" || report.region.value.kind !== "declarations")
         return emitSection(report.region ?? { kind: "absent" });
@@ -517,9 +497,9 @@ export async function runContractHistoryCommand(command, coordinates) {
             writeJson(refusal);
         else
             writeStdout(renderRefusal({ operation: "history", contract: selected.id, refusal }, undefined, displayContext()));
-        return 1;
+        return "refused";
     }
-    return emit(command.output, history, () => renderContractHistory(history, { full: command.full }), 0);
+    return emit(command.output, history, () => renderContractHistory(history, { full: command.full }), "accepted");
 }
 async function runReconcile(command, coordinates, execution, home) {
     const repo = requiredRepo(coordinates);
@@ -539,7 +519,7 @@ async function runReconcile(command, coordinates, execution, home) {
                 writeJson(statusRefusal("reconcile", selected.id).refusal);
             else
                 writeStdout(renderRefusal(statusRefusal("reconcile", selected.id), undefined, displayContext()));
-            return 1;
+            return "refused";
         }
         report = await library.reconcile({ repo, contract: selected.id, retryHooks: command.retryHooks });
     }
@@ -547,7 +527,7 @@ async function runReconcile(command, coordinates, execution, home) {
         writeJson(report);
     else
         writeStdout(renderReconcile(report, displayContext()));
-    return reconcileHasFailure(report) ? 1 : 0;
+    return reconcileHasFailure(report) ? "failed" : "accepted";
 }
 export async function runContractCommand(command, coordinates, runtime) {
     const execution = runtime.execution;

package/build/src/cli/commands/debt-grammar.js

@@ -1,4 +1,4 @@
-import { CliUsageError, DEBT_FAMILY_USAGE_GUIDE, unknownCommandGuide } from "../usage.js";
+import { CliUsageError, commonInvocationOptions, DEBT_FAMILY_USAGE_GUIDE, unknownCommandGuide, } from "../usage.js";
 import { scanArgs } from "../scan.js";
 import { parseDebtNamespaceSelector } from "../../debt/catalog.js";
 import { parseDebtId } from "../../debt/identity.js";
@@ -165,26 +165,19 @@ export function renderDebtHelp(action) {
     ].join("\n");
 }
 function renderDebtUsage(action) {
-    return DEBT_COMMAND_SPECS[action].usage
+    return debtUsage(action)
         .split("\n")
-        .map((line, index) => {
-        if (index === 0 || line.trimStart().startsWith("debt ")) {
-            const command = line.trimStart().startsWith("debt ") ? `keiyaku ${line.trim()}` : `keiyaku ${line}`;
-            return `${index === 0 ? "usage  " : "      "}${command}`;
-        }
-        return `      ${line.trim()}`;
-    })
+        .map((line, index) => `${index === 0 ? "usage  " : "      "}${line.trimStart()}`)
         .join("\n");
 }
 function debtUsage(action) {
-    const lines = DEBT_COMMAND_SPECS[action].usage.split("\n");
-    return lines
-        .map((line, index) => {
+    const usage = DEBT_COMMAND_SPECS[action].usage;
+    const lines = usage.split("\n").map((line, index) => {
         if (index === 0 || line.trimStart().startsWith("debt "))
             return `keiyaku ${line.trim()}`;
-        return `           ${line.trim()}`;
-    })
-        .join("\n");
+        return line.trim();
+    });
+    return [...lines, commonInvocationOptions(usage)].join("\n");
 }
 export function debtUsageGuide(action) {
     return {

package/build/src/cli/commands/debt.d.ts

@@ -1,4 +1,5 @@
 import type { ParsedDebtCommand } from "./debt-grammar.js";
+import { type CliOutcome } from "../streams.js";
 import type { CliRuntime } from "../runtime.js";
 import type { CliCoordinates } from "../coordinates.js";
-export declare function runDebtCommand(command: ParsedDebtCommand, coordinates: CliCoordinates, runtime: CliRuntime): Promise<number>;
+export declare function runDebtCommand(command: ParsedDebtCommand, coordinates: CliCoordinates, runtime: CliRuntime): Promise<CliOutcome>;

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

@@ -3,7 +3,7 @@ import { parseDebtNamespaceSelector } from "../../debt/catalog.js";
 import { debtsWithExecution, debtRowViewLimit, } from "../../debt/index.js";
 import { installNamespaceContext, resolveDebtNamespaceContext } from "../../debt/context.js";
 import { displayContext, emit, writeJson } from "../streams.js";
-import { renderDoctor, renderDebtContext, renderDebtLifecycle, renderDebtList, renderDebtMutation, renderDebtShow, renderDebtTree, renderDebtUpdate, debtExitCode, } from "../render/debt.js";
+import { renderDoctor, renderDebtContext, renderDebtLifecycle, renderDebtList, renderDebtMutation, renderDebtShow, renderDebtTree, renderDebtUpdate, debtOutcome, } from "../render/debt.js";
 import { actorFromEdge } from "../actor.js";
 import { debtQuerySelection } from "../../debt/query.js";
 function value(command, name) {
@@ -121,15 +121,15 @@ async function runShow(command, debts) {
     for (const id of handles)
         details.push(await debts.debt({ id }).read());
     const missing = details.findIndex((detail) => detail === null);
-    const code = missing >= 0 ? 1 : 0;
+    const outcome = missing >= 0 ? "refused" : "accepted";
     const projected = handles.length === 1 ? details[0] : details;
     if (missing >= 0) {
         const refusal = { kind: "refused", refusal: { kind: "debt-missing", debtId: handles[missing] } };
-        return emit(command.output, projected, () => renderDebtShow(refusal, displayContext()), code);
+        return emit(command.output, projected, () => renderDebtShow(refusal, displayContext()), outcome);
     }
     const found = details.filter((detail) => detail !== null);
     const result = found.length === 1 ? found[0] : found;
-    return emit(command.output, projected, () => renderDebtShow(result, displayContext()), code);
+    return emit(command.output, projected, () => renderDebtShow(result, displayContext()), outcome);
 }
 /** Presentation-only list scope the leaf acquired, never part of the native answer. */
 function listPresentation(command) {
@@ -151,7 +151,7 @@ async function runRead(input) {
                     : { namespace: explicitListNamespace(command) }),
                 ...(limit(command) === undefined ? {} : { limit: limit(command) }),
             });
-            return emit(command.output, result, () => renderDebtList("ls", scope, result, displayContext()), debtExitCode(result));
+            return emit(command.output, result, () => renderDebtList("ls", scope, result, displayContext()), debtOutcome(result));
         }
         case "ready":
         case "blocked": {
@@ -161,7 +161,7 @@ async function runRead(input) {
                 ...(value(command, "parent") === undefined ? {} : { parent: value(command, "parent") }),
                 ...(limit(command) === undefined ? {} : { limit: limit(command) }),
             });
-            return emit(command.output, result, () => renderDebtList(action, scope, result, displayContext()), debtExitCode(result));
+            return emit(command.output, result, () => renderDebtList(action, scope, result, displayContext()), debtOutcome(result));
         }
         case "query": {
             const result = await debts.query({
@@ -170,15 +170,15 @@ async function runRead(input) {
                 ...(value(command, "sort") === undefined ? {} : { sort: value(command, "sort") }),
                 ...(limit(command) === undefined ? {} : { limit: limit(command) }),
             });
-            return emit(command.output, result, () => renderDebtList("query", scope, result, displayContext()), debtExitCode(result));
+            return emit(command.output, result, () => renderDebtList("query", scope, result, displayContext()), debtOutcome(result));
         }
         case "tree": {
             const result = await debts.debt({ id }).tree();
-            return emit(command.output, result, () => renderDebtTree(result, displayContext()), debtExitCode(result));
+            return emit(command.output, result, () => renderDebtTree(result, displayContext()), debtOutcome(result));
         }
         case "doctor": {
             const result = await debts.doctor();
-            return emit(command.output, result, () => renderDoctor(result), debtExitCode(result));
+            return emit(command.output, result, () => renderDoctor(result), debtOutcome(result));
         }
         default:
             throw new Error(`debt action is not a read: ${command.action}`);
@@ -204,32 +204,32 @@ function missingWorld(command) {
         // An addressed missing read keeps its native null in JSON; text refuses without partial output.
         if (output === "json") {
             writeJson(command.positionals.length === 1 ? null : command.positionals.map(() => null));
-            return 1;
+            return "refused";
         }
         const refusal = missingDebt(command.positionals[0]);
-        return emit(output, refusal, () => renderDebtShow(refusal, displayContext()), 1);
+        return emit(output, refusal, () => renderDebtShow(refusal, displayContext()), "refused");
     }
     if (isWorldObservationAction(command)) {
-        return emit(output, { kind: "absent" }, () => "debt world absent", 1);
+        return emit(output, { kind: "absent" }, () => "debt world absent", "refused");
     }
     if (command.action === "context") {
         const result = { kind: "accepted", value: { namespace: [], source: "default-root" } };
-        return emit(output, result, () => renderDebtContext(result, displayContext()), debtExitCode(result));
+        return emit(output, result, () => renderDebtContext(result, displayContext()), debtOutcome(result));
     }
     if (command.action === "tree") {
         const result = missingDebt(command.positionals[0]);
-        return emit(output, result, () => renderDebtTree(result, displayContext()), debtExitCode(result));
+        return emit(output, result, () => renderDebtTree(result, displayContext()), debtOutcome(result));
     }
     if (command.action === "update") {
         const result = missingDebt(command.positionals[0]);
-        return emit(output, result, () => renderDebtUpdate(result, displayContext()), debtExitCode(result));
+        return emit(output, result, () => renderDebtUpdate(result, displayContext()), debtOutcome(result));
     }
     if (command.action !== "done" && command.action !== "drop")
         throw new Error(`debt action has no missing-world answer: ${command.action}`);
     const result = {
         items: command.positionals.map((id) => ({ id: id, outcome: missingDebt(id) })),
     };
-    return emit(output, result, () => renderDebtLifecycle(command.action, result, displayContext()), debtExitCode(result));
+    return emit(output, result, () => renderDebtLifecycle(command.action, result, displayContext()), debtOutcome(result));
 }
 /** One plural Debt lifecycle answer: every verb shares the same batch shape and renderer. */
 async function runBatchLifecycle(debts, command, verb) {
@@ -239,7 +239,7 @@ async function runBatchLifecycle(debts, command, verb) {
         ids: command.positionals,
         ...(note === undefined ? {} : { note }),
     });
-    return emit(command.output, result, () => renderDebtLifecycle(verb, result, displayContext()), debtExitCode(result));
+    return emit(command.output, result, () => renderDebtLifecycle(verb, result, displayContext()), debtOutcome(result));
 }
 async function runMutation(input) {
     const { debts, command } = input;
@@ -248,11 +248,11 @@ async function runMutation(input) {
     switch (command.action) {
         case "add": {
             const result = await invokeAdd(input);
-            return emit(command.output, result, () => renderDebtMutation("add", result, displayContext()), debtExitCode(result));
+            return emit(command.output, result, () => renderDebtMutation("add", result, displayContext()), debtOutcome(result));
         }
         case "update": {
             const result = await invokeUpdate(input);
-            return emit(command.output, result, () => renderDebtUpdate(result, displayContext()), debtExitCode(result));
+            return emit(command.output, result, () => renderDebtUpdate(result, displayContext()), debtOutcome(result));
         }
         case "done":
         case "drop":
@@ -276,10 +276,10 @@ function refuseNamespace(command, refusal) {
         case "blocked":
         case "query": {
             const action = command.action;
-            return emit(command.output, result, () => renderDebtList(action, listPresentation(command), result, displayContext()), debtExitCode(result));
+            return emit(command.output, result, () => renderDebtList(action, listPresentation(command), result, displayContext()), debtOutcome(result));
         }
         case "add":
-            return emit(command.output, result, () => renderDebtMutation("add", result, displayContext()), debtExitCode(result));
+            return emit(command.output, result, () => renderDebtMutation("add", result, displayContext()), debtOutcome(result));
         default:
             throw new Error(`debt action has no namespace refusal: ${command.action}`);
     }
@@ -307,7 +307,7 @@ async function runContext(command, context) {
     const result = typeof resolved === "object" && "kind" in resolved
         ? { kind: "refused", refusal: resolved }
         : { kind: "accepted", value: resolved };
-    return emit(command.output, result, () => renderDebtContext(result, displayContext()), debtExitCode(result));
+    return emit(command.output, result, () => renderDebtContext(result, displayContext()), debtOutcome(result));
 }
 // eslint-disable-next-line complexity -- this is the single CLI edge ordering world, context, forwarding, and local execution.
 export async function runDebtCommand(command, coordinates, runtime) {

package/build/src/cli/commands/install.d.ts

@@ -1,3 +1,4 @@
+import { type CliOutcome } from "../streams.js";
 import type { ProcessInput, ProcessOutcome } from "../../runtime/proc/run.js";
 declare const HARNESS_NAMES: readonly ["codex", "claude", "opencode", "pi"];
 type HarnessName = (typeof HARNESS_NAMES)[number];
@@ -22,5 +23,5 @@ export declare function parseInstallCommand(argv: readonly string[]): ParsedInst
 export declare function renderInstallHelp(): string;
 export declare function installHarnesses(harnesses: readonly HarnessName[], environment: NodeJS.ProcessEnv, runner?: InstallRunner): Promise<InstallInvocationResult>;
 export declare function renderInstallText(result: InstallInvocationResult): string;
-export declare function installExitCode(result: InstallInvocationResult): number;
+export declare function installOutcome(result: InstallInvocationResult): CliOutcome;
 export {};