@astrosheep/keiyaku 2.9.10 → 2.9.12

package/build/agents/providers/claude-agent-sdk/adapter.js

@@ -3,7 +3,7 @@ import { SUBAGENT_SESSION_VERSION } from "../../session.js";
 import { createProjectionDriver } from "../../harness/execution-handle.js";
 import { exactLaunchInputReceipts } from "../../harness/control-types.js";
 import { createProviderFailure } from "../../harness/provider-adapter.js";
-import { buildSubagentEnv, createAbortError, emitProviderEvidence, linkAbortSignal, sha256Utf8 } from "../../harness/runtime.js";
+import { awaitProviderAbortSettlement, buildSubagentEnv, createAbortError, emitProviderEvidence, linkAbortSignal, sha256Utf8 } from "../../harness/runtime.js";
 import { claudeIngressDisposition, emitClaudeThoughts, emitClaudeToolResults, emitClaudeToolStarts, emitClaudeUsage, extractAssistantMessage, extractAssistantMessageId, extractAssistantMessageModel, extractOverloadFallbackWarning, extractResultText, extractResumeToken, isClaudeApiRetryEvent, isClaudeModelRefusalFallbackEvent, isClaudeModelRefusalNoFallbackEvent, mapClaudeApiRetryWarning, } from "./events.js";
 import { CLAUDE_AGENT_SDK_PROVIDER, createPushableUserMessageStream, toClaudeUserMessage, } from "./session.js";
 function toClaudeSdkEffort(effort) {
@@ -19,6 +19,10 @@ async function loadClaudeAgentSdk(loader) {
 export async function startClaudeAgentSdk(prompt, cwd, options) {
     const sessionId = options.sessionId?.trim();
     let liveQuery;
+    let queryAbortController;
+    let runStarted = false;
+    let settleRun;
+    const runSettled = new Promise((resolve) => { settleRun = resolve; });
     let pendingEvidenceDiagnostics = 0;
     let builderDiagnostic = () => {
         pendingEvidenceDiagnostics += 1;
@@ -117,9 +121,13 @@ export async function startClaudeAgentSdk(prompt, cwd, options) {
             queryActive = false;
             const abortError = createAbortError(`${CLAUDE_AGENT_SDK_PROVIDER} exec cancelled by client`);
             if (mode === "force") {
+                queryAbortController?.abort(abortError);
                 inputStream?.end(abortError);
                 rejectPendingEnqueueWaiters(abortError);
                 liveQuery?.close();
+                if (runStarted) {
+                    await awaitProviderAbortSettlement(CLAUDE_AGENT_SDK_PROVIDER, runSettled, "forced query teardown did not settle");
+                }
                 return;
             }
             try {
@@ -131,8 +139,12 @@ export async function startClaudeAgentSdk(prompt, cwd, options) {
             liveQuery?.close();
             inputStream?.end(abortError);
             rejectPendingEnqueueWaiters(abortError);
+            if (runStarted) {
+                await awaitProviderAbortSettlement(CLAUDE_AGENT_SDK_PROVIDER, runSettled, "graceful query teardown did not settle");
+            }
         },
         async run(builder) {
+            runStarted = true;
             builderDiagnostic = (text) => builder.emit({ type: "diagnostic", text });
             emitTurnStarted = () => builder.emit({ type: "turn", phase: "started" });
             while (pendingEvidenceDiagnostics > 0) {
@@ -140,7 +152,7 @@ export async function startClaudeAgentSdk(prompt, cwd, options) {
                 builderDiagnostic("provider evidence callback failed");
             }
             const sdk = await loadClaudeAgentSdk(options.loader);
-            const queryAbortController = new AbortController();
+            queryAbortController = new AbortController();
             const unlinkBuilderAbort = linkAbortSignal(builder.signal, queryAbortController, () => undefined);
             const unlinkOuterAbort = linkAbortSignal(options.signal, queryAbortController, () => undefined);
             try {
@@ -375,6 +387,7 @@ export async function startClaudeAgentSdk(prompt, cwd, options) {
                     inputStream.end(endError);
                 }
                 rejectPendingEnqueueWaiters(endError);
+                settleRun();
             }
         },
     });

package/build/cli/commands/contract/bind/meta.js

@@ -5,7 +5,7 @@ export const meta = {
         "keiyaku @<full-contract-id> bind [-C|--cwd DIR] [--repo DIR]",
         "keiyaku bind --contract <full-contract-id> [-C|--cwd DIR] [--repo DIR]",
         "keiyaku bind [-C|--cwd DIR] [--repo DIR] [--task ID]... [- < contract.md]",
-        "keiyaku bind [-C|--cwd DIR] [--repo DIR] [--task ID]... --title TEXT --context TEXT --objective TEXT --design TEXT --scope GLOB --criteria CRITERION [--verification DECLARATION] [--dry-run]",
+        "keiyaku bind [-C|--cwd DIR] [--repo DIR] [--task ID]... --title TEXT --context TEXT --objective TEXT --design TEXT --scope GLOB [--scope GLOB]... --criteria CRITERION [--verification DECLARATION] [--dry-run]",
     ],
     stdin: { mode: "document", selector: { kind: "positional", index: 0, required: false, rejectBlank: false } },
     flags: ["cwd", "repo", "contract", "after", "exclusive", "draft-only", "title", "context", "objective", "design", "scope", "criteria", "verification", "task", "dry-run"],
@@ -21,7 +21,7 @@ export const meta = {
         "## Objective",
         "<what the commission should accomplish>",
         "",
-        "## Design",
+        "## Design & Approach",
         "<settled blueprint>",
         "",
         "## Scope",
@@ -54,7 +54,7 @@ export const meta = {
             "## Objective",
             "<what the commission should accomplish>",
             "",
-            "## Design",
+            "## Design & Approach",
             "<settled blueprint>",
             "",
             "## Scope",
@@ -75,7 +75,7 @@ export const meta = {
             "## Context",
             "<established facts and constraints>",
             "",
-            "## Design",
+            "## Design & Approach",
             "<settled blueprint>",
             "",
             "## Scope",

package/build/cli/commands/metadata.js

@@ -22,6 +22,7 @@ import { meta as statusMeta } from "./projection/status/meta.js";
 import { meta as historyMeta } from "./projection/history/meta.js";
 import { meta as taskMeta } from "./task/task/meta.js";
 import { meta as taskAddMeta } from "./task/add/meta.js";
+import { meta as taskComposeMeta } from "./task/compose/meta.js";
 import { meta as taskShowMeta } from "./task/show/meta.js";
 import { meta as taskLsMeta } from "./task/ls/meta.js";
 import { meta as taskLogMeta } from "./task/log/meta.js";
@@ -38,14 +39,14 @@ export const COMMAND_METADATA_ORDER = [
     "bind", "arc", "call", "revive", "wait", "tell", "kill", "log",
     "akuma", "akuma ls", "akuma show", "skills", "skills install", "amend", "audit",
     "renew", "petition", "forfeit", "guide", "completion", "status", "history", "task",
-    "task add", "task show", "task ls", "task log", "task start", "task stop", "task hold", "task resume", "task done",
+    "task add", "task compose", "task show", "task ls", "task log", "task start", "task stop", "task hold", "task resume", "task done",
     "task drop", "task update", "task doctor", "dump-env",
 ];
 const COMMAND_METADATA = [
     bindMeta, arcMeta, callMeta, reviveMeta, waitMeta, tellMeta, killMeta, logMeta,
     akumaMeta, akumaLsMeta, akumaShowMeta, skillsMeta, skillsInstallMeta, amendMeta, auditMeta,
     renewMeta, petitionMeta, forfeitMeta, guideMeta, completionMeta, statusMeta, historyMeta,
-    taskMeta, taskAddMeta, taskShowMeta, taskLsMeta, taskLogMeta, taskStartMeta, taskStopMeta,
+    taskMeta, taskAddMeta, taskComposeMeta, taskShowMeta, taskLsMeta, taskLogMeta, taskStartMeta, taskStopMeta,
     taskHoldMeta, taskResumeMeta,
     taskDoneMeta, taskDropMeta, taskUpdateMeta, taskDoctorMeta, dumpEnvMeta,
 ];

package/build/cli/commands/projection/kill/handler.js

@@ -10,12 +10,11 @@ export const handler = async (_stdin, flags, signal, positional) => runProjectio
         throw new FlowError("EMPTY_PARAM", "kill requires a projection address");
     const projection = await resolveProjectionCommandTarget(ctx, projectionAddress, "kill");
     const result = killProjectionGeneration(projection.directory);
-    if (result.status === "already-closed") {
-        return buildKillAlreadyClosedResponse(projection.id);
-    }
     if (flags.timeoutMs === undefined) {
-        return buildKillAcceptedResponse(projection.id);
+        return result.status === "already-closed"
+            ? buildKillAlreadyClosedResponse(projection.id)
+            : buildKillAcceptedResponse(projection.id);
     }
-    // Accepted with --wait: no acceptance receipt or address preamble.
+    // --wait always replays ordinary wait, including already-terminal generations.
     return buildWaitResponse(projection.id, await waitForProjection({ projectionDirectory: projection.directory, timeoutMs: flags.timeoutMs, signal }), { alias: projection.alias });
 });

package/build/cli/commands/shared.js

@@ -54,7 +54,7 @@ export async function repositoryDirectory(flags, operation) {
             const asTyped = flags.contractAddressSource === "at-address"
                 ? `@${flags.contractId}`
                 : `--contract ${flags.contractId}`;
-            throw new AddressResolutionError("EMPTY_PARAM", `${asTyped} is a commission address, but ${candidate} has no repository ledger; contract addressing requires a ledger`, buildResolutionAttempt({
+            throw new AddressResolutionError("UNKNOWN_ADDRESS", `${asTyped} is a commission address, but ${candidate} has no repository ledger; contract addressing requires a ledger`, buildResolutionAttempt({
                 repo: { kind: "user" },
                 workdir: effectiveDirectory(flags),
                 spelling: {

package/build/cli/commands/task/catalog.js

@@ -1,5 +1,6 @@
 import { meta as taskMeta } from "./task/meta.js";
 import { meta as addMeta } from "./add/meta.js";
+import { meta as composeMeta } from "./compose/meta.js";
 import { meta as showMeta } from "./show/meta.js";
 import { meta as lsMeta } from "./ls/meta.js";
 import { meta as logMeta } from "./log/meta.js";
@@ -14,6 +15,7 @@ import { meta as doctorMeta } from "./doctor/meta.js";
 export const taskCatalog = [
     { meta: taskMeta, load: () => import("./task/handler.js") },
     { meta: addMeta, load: () => import("./add/handler.js") },
+    { meta: composeMeta, load: () => import("./compose/handler.js") },
     { meta: showMeta, load: () => import("./show/handler.js") },
     { meta: lsMeta, load: () => import("./ls/handler.js") },
     { meta: logMeta, load: () => import("./log/handler.js") },

package/build/cli/commands/task/compose/handler.js

@@ -0,0 +1,18 @@
+import { composeTasks, openTaskMutationContext, planTaskComposition, resolveTaskCreator, } from "../../../../core/task/index.js";
+import { renderTaskComposition, renderTaskCompositionJson } from "../../../render/task.js";
+import { textResponse } from "../../../render/shared.js";
+import { effectiveDirectory } from "../../shared.js";
+export const handler = async (stdin, flags, signal) => {
+    const cwd = effectiveDirectory(flags);
+    const context = await openTaskMutationContext(cwd, signal);
+    const input = {
+        sketch: stdin,
+        creator: await resolveTaskCreator(cwd),
+        namespace: context.namespace,
+        now: () => new Date(),
+    };
+    const plan = flags.check
+        ? planTaskComposition(await context.repository.read(), input)
+        : await composeTasks(context.repository, input);
+    return textResponse(flags.json ? renderTaskCompositionJson(plan, Boolean(flags.check)) : renderTaskComposition(plan, Boolean(flags.check)));
+};

package/build/cli/commands/task/compose/meta.js

@@ -0,0 +1,10 @@
+export const meta = {
+    command: "task compose",
+    summary: "Atomically compose tasks from a tree sketch",
+    usage: ["keiyaku task compose [-C|--cwd DIR] [--check] - < sketch.md"],
+    stdin: { mode: "document", selector: { kind: "positional", index: 0, required: true, rejectBlank: true } },
+    flags: ["cwd", "check", "json"],
+    purpose: "Atomically create and rewire tasks from one validated tree sketch.",
+    input: ["Each task line is two-space indented + title or @COORDINATE, followed by whitespace-separated parent=, needs=@a,@b, supersedes=@c, or relates=@d declarations. Bare prose is allowed only in a nested + task body."],
+    notes: ["Nesting assigns parent. Top-level references preserve their parent; parent= clears it. Omitted relation declarations preserve their current complete set, while an explicit empty declaration clears that set."],
+};

package/build/cli/flags.js

@@ -103,7 +103,7 @@ export const FLAG_SPECS = {
     scope: {
         kind: "value",
         placeholder: "GLOB",
-        description: "Set the single scope pattern for flag-generated bind Markdown.",
+        description: "Add an ordered scope pattern to flag-generated bind Markdown. May be repeated.",
     },
     criteria: {
         kind: "value",
@@ -138,6 +138,10 @@ export const FLAG_SPECS = {
         kind: "boolean",
         description: "Preview bind input or petition preflight without mutation.",
     },
+    check: {
+        kind: "boolean",
+        description: "Derive and render the task composition without changing the board or Git state.",
+    },
     "append-scope": {
         kind: "value",
         placeholder: "PATTERN",

package/build/cli/index.js

@@ -37,10 +37,10 @@ function prepareBindInput(stdin, flags, selectsStdin) {
     const nonblankStdin = stdin.trim().length > 0;
     const domainFlags = hasBindDomainFlags(flags);
     if (flags.dryRun && flags.draftOnly) {
-        throw new FlowError("EMPTY_PARAM", "--dry-run cannot be combined with --draft-only");
+        throw new FlowError("INVALID_USAGE", "--dry-run cannot be combined with --draft-only");
     }
     if (selectsStdin && domainFlags) {
-        throw new FlowError("EMPTY_PARAM", "bind accepts either stdin Markdown or domain flags, not both");
+        throw new FlowError("INVALID_USAGE", "bind accepts either stdin Markdown or domain flags, not both");
     }
     if (domainFlags) {
         const missing = [];
@@ -74,7 +74,10 @@ function prepareBindInput(stdin, flags, selectsStdin) {
         if (flags.bindTaskIds !== undefined && flags.bindTaskIds.length > 0) {
             return "";
         }
-        throw new FlowError("EMPTY_PARAM", `No Markdown input received on stdin.\n\nExample:\n  ${usageExample("bind")}`);
+        const message = selectsStdin
+            ? `No Markdown input received on stdin.\n\nExample:\n  ${usageExample("bind")}`
+            : "bind requires literal '-' for Markdown input or the required domain flags";
+        throw new FlowError(selectsStdin ? "STDIN_EMPTY" : "EMPTY_PARAM", message);
     }
     return stdin;
 }
@@ -218,7 +221,7 @@ async function resolveCliInput(parsed) {
     const token = selected?.token;
     const selectsStdin = token === "-";
     if (selectsStdin && process.stdin.isTTY) {
-        throw new FlowError("EMPTY_PARAM", `${parsed.command} literal '-' requires piped stdin`);
+        throw new FlowError("INVALID_USAGE", `${parsed.command} literal '-' requires piped stdin`);
     }
     const piped = selectsStdin ? await readStdin() : "";
     const input = selectsStdin ? piped : token ?? "";
@@ -231,8 +234,10 @@ async function resolveCliInput(parsed) {
     if (token !== undefined && stdinMeta.selector?.rejectBlank && !input.trim()) {
         const message = stdinMeta.mode === "document"
             ? `No Markdown input received on stdin.\n\nExample:\n  ${usageExample(parsed.command)}`
-            : `${parsed.command} body cannot be empty`;
-        throw new FlowError("EMPTY_PARAM", message);
+            : selectsStdin
+                ? `${parsed.command} received no body on stdin`
+                : `${parsed.command} body cannot be empty`;
+        throw new FlowError(selectsStdin ? "STDIN_EMPTY" : "EMPTY_PARAM", message);
     }
     return { stdin: input, flags: selected?.replace(input) ?? parsed.flags, selectsStdin };
 }

package/build/cli/parse-flags.js

@@ -11,7 +11,7 @@ export function parseFlagName(raw) {
 }
 export function assertAllowedFlag(command, name) {
     if (!allowedFlagsForParse(command).includes(name)) {
-        throw new FlowError("EMPTY_PARAM", `option --${name} is not valid for ${command}`);
+        throw new FlowError("UNKNOWN_OPTION", `option --${name} is not valid for ${command}`);
     }
 }
 export function assignFlag(flags, name, value) {
@@ -65,43 +65,40 @@ export function assignFlag(flags, name, value) {
             return;
         case "place":
             if (flags.bindPlace !== undefined) {
-                throw new FlowError("EMPTY_PARAM", "option --place may only be specified once");
+                throw new FlowError("INVALID_USAGE", "option --place may only be specified once");
             }
             flags.bindPlace = String(value);
             return;
         case "objective":
             if (flags.bindObjective !== undefined) {
-                throw new FlowError("EMPTY_PARAM", "option --objective may only be specified once");
+                throw new FlowError("INVALID_USAGE", "option --objective may only be specified once");
             }
             flags.bindObjective = String(value);
             return;
         case "context":
             if (flags.bindContext !== undefined) {
-                throw new FlowError("EMPTY_PARAM", "option --context may only be specified once");
+                throw new FlowError("INVALID_USAGE", "option --context may only be specified once");
             }
             flags.bindContext = String(value);
             return;
         case "design":
             if (flags.bindDesign !== undefined) {
-                throw new FlowError("EMPTY_PARAM", "option --design may only be specified once");
+                throw new FlowError("INVALID_USAGE", "option --design may only be specified once");
             }
             flags.bindDesign = String(value);
             return;
         case "scope":
-            if (flags.bindScope !== undefined) {
-                throw new FlowError("EMPTY_PARAM", "option --scope may only be specified once");
-            }
-            flags.bindScope = String(value);
+            flags.bindScope = [...(flags.bindScope ?? []), String(value)];
             return;
         case "criteria":
             if (flags.bindCriteria !== undefined) {
-                throw new FlowError("EMPTY_PARAM", "option --criteria may only be specified once");
+                throw new FlowError("INVALID_USAGE", "option --criteria may only be specified once");
             }
             flags.bindCriteria = String(value);
             return;
         case "verification":
             if (flags.bindVerification !== undefined) {
-                throw new FlowError("EMPTY_PARAM", "option --verification may only be specified once");
+                throw new FlowError("INVALID_USAGE", "option --verification may only be specified once");
             }
             flags.bindVerification = String(value);
             return;
@@ -120,6 +117,9 @@ export function assignFlag(flags, name, value) {
         case "dry-run":
             flags.dryRun = Boolean(value);
             return;
+        case "check":
+            flags.check = Boolean(value);
+            return;
         case "append-scope":
             flags.appendScope = [...(flags.appendScope ?? []), String(value)];
             return;
@@ -152,7 +152,7 @@ export function assignFlag(flags, name, value) {
             return;
         case "target":
             if (flags.target !== undefined) {
-                throw new FlowError("EMPTY_PARAM", "option --target may only be specified once");
+                throw new FlowError("INVALID_USAGE", "option --target may only be specified once");
             }
             flags.target = String(value);
             return;
@@ -162,7 +162,7 @@ export function assignFlag(flags, name, value) {
         case "diff-budget": {
             const parsed = Number(String(value));
             if (!Number.isSafeInteger(parsed) || parsed < 0) {
-                throw new FlowError("EMPTY_PARAM", "option --diff-budget requires a non-negative safe integer byte count");
+                throw new FlowError("INVALID_USAGE", "option --diff-budget requires a non-negative safe integer byte count");
             }
             flags.auditDiffBudgetBytes = parsed;
             return;
@@ -175,17 +175,17 @@ export function assignFlag(flags, name, value) {
             return;
         case "sort":
             if (flags.taskSort !== undefined) {
-                throw new FlowError("EMPTY_PARAM", "option --sort may only be specified once");
+                throw new FlowError("INVALID_USAGE", "option --sort may only be specified once");
             }
             flags.taskSort = String(value);
             return;
         case "pri": {
             const raw = String(value);
             if (!/^[0-3]$/.test(raw)) {
-                throw new FlowError("EMPTY_PARAM", "task priority must be an integer from 0 through 3");
+                throw new FlowError("INVALID_USAGE", "task priority must be an integer from 0 through 3");
             }
             if (flags.taskPri !== undefined) {
-                throw new FlowError("EMPTY_PARAM", "option --pri may only be specified once");
+                throw new FlowError("INVALID_USAGE", "option --pri may only be specified once");
             }
             flags.taskPri = Number(raw);
             return;
@@ -213,7 +213,7 @@ export function assignFlag(flags, name, value) {
             return;
         case "parent":
             if (flags.taskParent !== undefined) {
-                throw new FlowError("EMPTY_PARAM", "option --parent may only be specified once");
+                throw new FlowError("INVALID_USAGE", "option --parent may only be specified once");
             }
             flags.taskParent = String(value);
             return;
@@ -222,24 +222,24 @@ export function assignFlag(flags, name, value) {
             return;
         case "title":
             if (flags.taskTitle !== undefined) {
-                throw new FlowError("EMPTY_PARAM", "option --title may only be specified once");
+                throw new FlowError("INVALID_USAGE", "option --title may only be specified once");
             }
             flags.taskTitle = String(value);
             return;
         case "body":
             if (flags.taskBody !== undefined) {
-                throw new FlowError("EMPTY_PARAM", "option --body may only be specified once");
+                throw new FlowError("INVALID_USAGE", "option --body may only be specified once");
             }
             flags.taskBody = String(value);
             return;
         case "append":
             if (flags.taskAppend !== undefined) {
-                throw new FlowError("EMPTY_PARAM", "option --append may only be specified once");
+                throw new FlowError("INVALID_USAGE", "option --append may only be specified once");
             }
             flags.taskAppend = String(value);
             return;
         default:
-            throw new FlowError("EMPTY_PARAM", `unknown option: --${name}`);
+            throw new FlowError("UNKNOWN_OPTION", `unknown option: --${name}`);
     }
 }
 export function readValueFlag(name, token, eq, tokens, index) {

package/build/cli/parse-metadata.js

@@ -45,13 +45,13 @@ export function isPetitionDryRunInvocation(tokens) {
 export function parseWaitTimeout(value) {
     const matched = /^(?<amount>[1-9][0-9]*)(?<unit>[smh])$/.exec(value);
     if (!matched?.groups) {
-        throw new FlowError("EMPTY_PARAM", "wait timeout must use <positive integer><s|m|h>, for example 45s, 5m, or 2h (maximum 24h)");
+        throw new FlowError("INVALID_USAGE", "wait timeout must use <positive integer><s|m|h>, for example 45s, 5m, or 2h (maximum 24h)");
     }
     const amount = Number(matched.groups.amount);
     const multiplier = matched.groups.unit === "s" ? 1_000 : matched.groups.unit === "m" ? 60_000 : 3_600_000;
     const timeoutMs = amount * multiplier;
     if (!Number.isSafeInteger(timeoutMs) || timeoutMs > 24 * 3_600_000) {
-        throw new FlowError("EMPTY_PARAM", "wait timeout must use <positive integer><s|m|h>, for example 45s, 5m, or 2h (maximum 24h)");
+        throw new FlowError("INVALID_USAGE", "wait timeout must use <positive integer><s|m|h>, for example 45s, 5m, or 2h (maximum 24h)");
     }
     return timeoutMs;
 }
@@ -86,6 +86,9 @@ export function commandPositionalRange(command) {
     if (command === "task add") {
         return { min: 1, max: 1, label: "<BODY|->" };
     }
+    if (command === "task compose") {
+        return { min: 0, max: 0 };
+    }
     if (command === "task show" || command === "task log" || command === "task start" || command === "task hold" || command === "task resume" || command === "task drop") {
         return { min: 1, max: 1, label: "<ID>" };
     }

package/build/cli/parse-selectors.js

@@ -26,13 +26,13 @@ function formatSelectorList(items) {
 }
 export function applyCommissionSelector(command, flags, atTokens, contractFlagRaws) {
     if (atTokens.length > 0 && contractFlagRaws.length > 0) {
-        throw new FlowError("EMPTY_PARAM", `commission address supplied twice: ${atTokens[0]} and --contract ${contractFlagRaws[0]}; use exactly one form`);
+        throw new FlowError("INVALID_USAGE", `commission address supplied twice: ${atTokens[0]} and --contract ${contractFlagRaws[0]}; use exactly one form`);
     }
     if (atTokens.length > 1) {
-        throw new FlowError("EMPTY_PARAM", `${command} accepts one commission address; got ${formatSelectorList(atTokens)}`);
+        throw new FlowError("INVALID_USAGE", `${command} accepts one commission address; got ${formatSelectorList(atTokens)}`);
     }
     if (contractFlagRaws.length > 1) {
-        throw new FlowError("EMPTY_PARAM", `${command} accepts one commission address; got ${formatSelectorList(contractFlagRaws.map((raw) => `--contract ${raw}`))}`);
+        throw new FlowError("INVALID_USAGE", `${command} accepts one commission address; got ${formatSelectorList(contractFlagRaws.map((raw) => `--contract ${raw}`))}`);
     }
     if (atTokens.length === 1) {
         flags.contractId = normalizeContractAddress(atTokens[0]);
@@ -46,7 +46,7 @@ export function assertCommissionSelectorAllowed(command, flags) {
     if (flags.contractId === undefined || COMMISSION_SELECTOR_COMMANDS.has(command)) {
         return;
     }
-    throw new FlowError("EMPTY_PARAM", `contract address @${flags.contractId} is not valid for ${command}`);
+    throw new FlowError("INVALID_USAGE", `contract address @${flags.contractId} is not valid for ${command}`);
 }
 export function assertProjectionSelectorPresent(command, flags, atTokens, contractFlagRaws, restLength, payloadLength) {
     if ((command !== "wait" && command !== "tell") || flags.contractId === undefined) {

package/build/cli/parse.js

@@ -31,7 +31,7 @@ export function parseCliArgs(tokens) {
             const short = token.slice(1);
             const name = SHORT_FLAG_ALIASES[short];
             if (!name) {
-                throw new FlowError("EMPTY_PARAM", `unknown option: ${token}`);
+                throw new FlowError("UNKNOWN_OPTION", `unknown option: ${token}`);
             }
             seenFlagNames.add(name);
             if (VALUE_FLAGS.has(name)) {
@@ -52,7 +52,7 @@ export function parseCliArgs(tokens) {
                 assignFlag(flags, name, true);
                 continue;
             }
-            throw new FlowError("EMPTY_PARAM", `unknown option: ${token}`);
+            throw new FlowError("UNKNOWN_OPTION", `unknown option: ${token}`);
         }
         if (!token.startsWith("--")) {
             free.push(token);
@@ -61,7 +61,7 @@ export function parseCliArgs(tokens) {
         const eq = token.indexOf("=");
         const name = parseFlagName(eq === -1 ? token : token.slice(0, eq));
         if (!CONTROL_FLAGS.has(name)) {
-            throw new FlowError("EMPTY_PARAM", `unknown option: --${name}`);
+            throw new FlowError("UNKNOWN_OPTION", `unknown option: --${name}`);
         }
         seenFlagNames.add(name);
         if (VALUE_FLAGS.has(name)) {
@@ -77,7 +77,7 @@ export function parseCliArgs(tokens) {
         }
         if (BOOLEAN_FLAGS.has(name)) {
             if (eq !== -1) {
-                throw new FlowError("EMPTY_PARAM", `option --${name} does not accept a value`);
+                throw new FlowError("INVALID_USAGE", `option --${name} does not accept a value`);
             }
             assignFlag(flags, name, true);
         }
@@ -113,9 +113,9 @@ export function parseCliArgs(tokens) {
     }
     if (seenFlagNames.has("place")) {
         if (command === "bind") {
-            throw new FlowError("EMPTY_PARAM", "bind no longer accepts --place; use --title <text>");
+            throw new FlowError("UNKNOWN_OPTION", "bind no longer accepts --place; use --title <text>");
         }
-        throw new FlowError("EMPTY_PARAM", "unknown option --place; use @addr or --contract <addr>");
+        throw new FlowError("UNKNOWN_OPTION", "unknown option --place; use @addr or --contract <addr>");
     }
     for (const name of seenFlagNames) {
         assertAllowedFlag(command, name);
@@ -125,19 +125,19 @@ export function parseCliArgs(tokens) {
         delete flags.taskTitle;
     }
     if (command === "call" && flags.detach && flags.timeoutMs !== undefined) {
-        throw new FlowError("EMPTY_PARAM", "call cannot combine --detach and --wait");
+        throw new FlowError("INVALID_USAGE", "call cannot combine --detach and --wait");
     }
     if (command === "task ls" && flags.all && flags.done) {
-        throw new FlowError("EMPTY_PARAM", "task ls cannot combine --all and --done");
+        throw new FlowError("INVALID_USAGE", "task ls cannot combine --all and --done");
     }
     if (command === "wait" && flags.any && flags.all) {
-        throw new FlowError("EMPTY_PARAM", WAIT_SET_SELECTION_ERROR);
+        throw new FlowError("INVALID_USAGE", WAIT_SET_SELECTION_ERROR);
     }
     if (command === "task update" && flags.taskParent !== undefined && flags.taskNoParent) {
-        throw new FlowError("EMPTY_PARAM", "task update cannot combine --parent and --no-parent");
+        throw new FlowError("INVALID_USAGE", "task update cannot combine --parent and --no-parent");
     }
     if (command === "task update" && flags.taskBody !== undefined && flags.taskAppend !== undefined) {
-        throw new FlowError("EMPTY_PARAM", "task update cannot combine --body and --append");
+        throw new FlowError("INVALID_USAGE", "task update cannot combine --body and --append");
     }
     if (command === "task update" && flags.taskTitle === undefined && flags.taskBody === undefined && flags.taskAppend === undefined
         && flags.taskPri === undefined && flags.taskNeeds === undefined && flags.taskDropNeeds === undefined
@@ -147,18 +147,18 @@ export function parseCliArgs(tokens) {
         throw new FlowError("EMPTY_PARAM", "task update requires at least one change");
     }
     if (command === "petition" && flags.json && !flags.dryRun) {
-        throw new FlowError("EMPTY_PARAM", "petition --json requires --dry-run");
+        throw new FlowError("INVALID_USAGE", "petition --json requires --dry-run");
     }
     if (command === "petition" && flags.dryRun && (flags.appendScope?.length ?? 0) > 0) {
-        throw new FlowError("EMPTY_PARAM", "petition --dry-run does not accept --append-scope");
+        throw new FlowError("INVALID_USAGE", "petition --dry-run does not accept --append-scope");
     }
     if (command === "renew") {
         const recoveryModes = [flags.renewContinue, flags.renewAbort].filter(Boolean).length;
         if (recoveryModes > 1) {
-            throw new FlowError("EMPTY_PARAM", "renew accepts only one of --continue or --abort");
+            throw new FlowError("INVALID_USAGE", "renew accepts only one of --continue or --abort");
         }
         if (flags.renewAbort && (flags.appendScope?.length ?? 0) > 0) {
-            throw new FlowError("EMPTY_PARAM", "renew --abort does not accept --append-scope");
+            throw new FlowError("INVALID_USAGE", "renew --abort does not accept --append-scope");
         }
     }
     assertCommissionSelectorAllowed(command, flags);
@@ -166,7 +166,7 @@ export function parseCliArgs(tokens) {
     const positional = [...rest, ...payload];
     if (command === "bind" && flags.contractId !== undefined) {
         if (!isCommissionId(flags.contractId)) {
-            throw new FlowError("EMPTY_PARAM", `bind replay requires a full canonical contract id; got ${flags.contractId}`);
+            throw new FlowError("UNKNOWN_ADDRESS", `bind replay requires a full canonical contract id; got ${flags.contractId}`);
         }
         const hasReplayInput = positional.length > 0
             || flags.bindTaskIds !== undefined
@@ -182,7 +182,7 @@ export function parseCliArgs(tokens) {
             || flags.bindCriteria !== undefined
             || flags.bindVerification !== undefined;
         if (hasReplayInput) {
-            throw new FlowError("EMPTY_PARAM", "addressed bind is replay-only and accepts no draft or creation input");
+            throw new FlowError("INVALID_USAGE", "addressed bind is replay-only and accepts no draft or creation input");
         }
     }
     if (command === "wait") {
@@ -190,13 +190,13 @@ export function parseCliArgs(tokens) {
             throw new FlowError("EMPTY_PARAM", "wait requires <projection-address>");
         }
         if (positional.length > 1 && !flags.any && !flags.all) {
-            throw new FlowError("EMPTY_PARAM", WAIT_SET_SELECTION_ERROR);
+            throw new FlowError("INVALID_USAGE", WAIT_SET_SELECTION_ERROR);
         }
     }
     if (isCallCommand(command)) {
         if (flags.akuma) {
             if (positional.length > 1) {
-                throw new FlowError("EMPTY_PARAM", `${command} accepts at most one <BODY|-> when --akuma is used`);
+                throw new FlowError("INVALID_USAGE", `${command} accepts at most one <BODY|-> when --akuma is used`);
             }
         }
         else {
@@ -205,16 +205,16 @@ export function parseCliArgs(tokens) {
                 throw new FlowError("EMPTY_PARAM", `${command} requires an agent name; use \`keiyaku ${command} NAME <BODY|->\``);
             }
             if (isResponseArtifactId(name)) {
-                throw new FlowError("EMPTY_PARAM", `artifact ${name} is a response artifact; call expects an Akuma profile name`);
+                throw new FlowError("UNKNOWN_ADDRESS", `artifact ${name} is a response artifact; call expects an Akuma profile name`);
             }
             const parsedName = agentNameSchema.safeParse(name);
             if (!parsedName.success) {
-                throw new FlowError("EMPTY_PARAM", `${command} requires a valid agent name before <BODY|->`);
+                throw new FlowError("UNKNOWN_ADDRESS", `${command} requires a valid agent name before <BODY|->`);
             }
             flags.akuma = parsedName.data;
             positional.shift();
             if (positional.length > 1) {
-                throw new FlowError("EMPTY_PARAM", `${command} accepts at most one <BODY|-> after the agent name`);
+                throw new FlowError("INVALID_USAGE", `${command} accepts at most one <BODY|-> after the agent name`);
             }
         }
     }
@@ -231,7 +231,7 @@ export function parseCliArgs(tokens) {
         const message = stdin.mode === "document"
             ? `${command} reads Markdown only through literal '-'; file path arguments are not supported`
             : `${command} does not accept positional arguments`;
-        throw new FlowError("EMPTY_PARAM", message);
+        throw new FlowError("INVALID_USAGE", message);
     }
     return { command, flags, positional };
 }