@astrosheep/keiyaku 2.9.12 → 2.9.13

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

@@ -1,11 +1,12 @@
+export const TASK_UPDATE_EXPLICIT_CHANGE_ERROR = "task update requires an explicit change: --title, --body TEXT or --body -, --append TEXT|-, --pri, --needs/--drop-needs, --parent/--no-parent, --from, --supersedes/--drop-supersedes, or --relates-to/--drop-relates-to";
 export const meta = {
     command: "task update",
     summary: "Update task facts",
-    usage: ["keiyaku task update [-C|--cwd DIR] COORDINATE [--title TEXT] [--body TEXT|-|--append TEXT|-] [--pri 0-3] [--needs COORDINATE] [--drop-needs COORDINATE] [--parent COORDINATE|--no-parent] [--from COORDINATE] [--supersedes COORDINATE] [--drop-supersedes COORDINATE] [--relates-to COORDINATE] [--drop-relates-to COORDINATE] [--json]"],
+    usage: ["keiyaku task update [-C|--cwd DIR] [--contract ADDR] COORDINATE [--title TEXT] [--body TEXT|-|--append TEXT|-] [--pri 0-3] [--needs COORDINATE] [--drop-needs COORDINATE] [--parent COORDINATE|--no-parent] [--from COORDINATE] [--supersedes COORDINATE] [--drop-supersedes COORDINATE] [--relates-to COORDINATE] [--drop-relates-to COORDINATE] [--json]"],
     stdin: {
         mode: "argument",
         selector: { kind: "flag", names: ["taskBody", "taskAppend"], required: false, rejectBlank: false },
     },
-    flags: ["cwd", "title", "body", "append", "pri", "needs", "drop-needs", "parent", "no-parent", "from", "supersedes", "drop-supersedes", "relates-to", "drop-relates-to", "json"],
+    flags: ["cwd", "contract", "title", "body", "append", "pri", "needs", "drop-needs", "parent", "no-parent", "from", "supersedes", "drop-supersedes", "relates-to", "drop-relates-to", "json"],
     purpose: "Change mutable task facts.",
 };

package/build/cli/commands/verification/handler.js

@@ -0,0 +1,43 @@
+import { readVerificationRun, requestVerificationRunCancellation, VerificationRunUnknownError, VerificationRunWaitTimeoutError, waitForVerificationRun, } from "../../../core/settlement/verification.js";
+import { FlowError } from "../../../flow-error.js";
+import { renderVerificationCli, verificationCancelModel, verificationStatusModel, verificationWaitModel, verificationWaitTimeoutModel, } from "../../render/verification.js";
+import { projectDirectory } from "../shared.js";
+export const handler = async (_stdin, flags, signal, positional) => {
+    const [operation, runId, ...extra] = positional;
+    if (!operation || !runId || extra.length > 0) {
+        throw new FlowError("EMPTY_PARAM", "verification requires wait, status, or cancel followed by one VerificationRun id");
+    }
+    // Honor --repo through the shared repository-resolution primitive.
+    const root = await projectDirectory(flags, "verification");
+    const json = flags.json === true;
+    if (operation === "wait") {
+        try {
+            // Observation only: timeout/abort end wait without requesting cancellation.
+            const terminal = await waitForVerificationRun({ root, runId, timeoutMs: flags.timeoutMs, signal });
+            return renderVerificationCli(verificationWaitModel(runId, terminal), json);
+        }
+        catch (error) {
+            if (error instanceof VerificationRunUnknownError) {
+                throw new FlowError("UNKNOWN_ADDRESS", error.message);
+            }
+            if (!(error instanceof VerificationRunWaitTimeoutError))
+                throw error;
+            return renderVerificationCli(verificationWaitTimeoutModel(runId), json);
+        }
+    }
+    if (operation === "status") {
+        const run = readVerificationRun(root, runId);
+        if (!run)
+            throw new FlowError("UNKNOWN_ADDRESS", `verification run '${runId}' does not exist`);
+        return renderVerificationCli(verificationStatusModel(run), json);
+    }
+    if (operation === "cancel") {
+        // Explicit cancel is the only mutating verification CLI path.
+        if (!readVerificationRun(root, runId)) {
+            throw new FlowError("UNKNOWN_ADDRESS", `verification run '${runId}' does not exist`);
+        }
+        const accepted = requestVerificationRunCancellation(root, runId);
+        return renderVerificationCli(verificationCancelModel(runId, accepted), json);
+    }
+    throw new FlowError("INVALID_USAGE", "verification operation must be wait, status, or cancel");
+};

package/build/cli/commands/verification/meta.js

@@ -0,0 +1,13 @@
+export const meta = {
+    command: "verification",
+    summary: "Observe or cancel one durable VerificationRun",
+    usage: [
+        "keiyaku verification wait RUN_ID [-C|--cwd DIR] [--repo DIR] [--timeout DURATION] [--json]",
+        "keiyaku verification cancel RUN_ID [-C|--cwd DIR] [--repo DIR] [--json]",
+        "keiyaku verification status RUN_ID [-C|--cwd DIR] [--repo DIR] [--json]",
+    ],
+    stdin: { mode: "argument" },
+    flags: ["cwd", "repo", "timeout", "json"],
+    purpose: "Rejoin, inspect, or request cancellation of an addressable VerificationRun without inspecting runtime SQLite directly.",
+    completionRank: 11,
+};

package/build/cli/completion.js

@@ -19,8 +19,8 @@ function topLevelCommands() {
 function subcommandsFor(parent) {
     return [...(getCommandMetadata(parent).subcommands ?? [])];
 }
-function topLevelOptionsFor(command) {
-    const metadata = allCommandMetadata().find((meta) => meta.command === command && !command.includes(" "));
+function optionsForCommandContext(context) {
+    const metadata = allCommandMetadata().find((meta) => meta.command === context);
     return metadata ? metadata.flags.map((flag) => `--${flag}`) : [];
 }
 function filterPrefix(items, word) {
@@ -40,22 +40,24 @@ export async function renderCompletionCandidates(input) {
     if (word.startsWith("@")) {
         return (await contractAddressCandidates(input.cwd, word)).join("\n");
     }
-    if (input.previous === "call") {
+    const previous = input.previous ?? "";
+    const previousWord = previous.split(/\s+/).at(-1) ?? "";
+    if (previous === "call") {
         return filterPrefix([...(await akumaCandidates(input.cwd, word)), "--alias"], word).join("\n");
     }
-    if (input.previous === "akuma") {
+    if (previous === "akuma") {
         return filterPrefix(subcommandsFor("akuma"), word).join("\n");
     }
-    if (input.previous === "skills") {
+    if (previous === "skills") {
         return filterPrefix(subcommandsFor("skills"), word).join("\n");
     }
-    if (input.previous === "task") {
+    if (previous === "task") {
         return filterPrefix(subcommandsFor("task"), word).join("\n");
     }
-    if (input.previous === "--filter") {
+    if (previousWord === "--filter") {
         return filterPrefix([TASK_FILTER_COMPLETION], word).join("\n");
     }
-    const options = input.previous ? topLevelOptionsFor(input.previous) : [];
+    const options = previous ? optionsForCommandContext(previous) : [];
     if (options.length > 0) {
         return filterPrefix(options, word).join("\n");
     }
@@ -66,8 +68,9 @@ export function renderCompletionScript(shell = "bash") {
         return [
             "#compdef keiyaku",
             "_keiyaku() {",
-            "  local -a candidates",
-            "  candidates=(${(f)\"$(keiyaku completion --complete --word=\"${words[CURRENT]}\" --previous=\"${words[CURRENT-1]}\" 2>/dev/null)\"})",
+            "  local -a candidates context",
+            "  context=\"${(j: :)words[2,CURRENT-1]}\"",
+            "  candidates=(${(f)\"$(keiyaku completion --complete --word=\"${words[CURRENT]}\" --previous=\"${context}\" 2>/dev/null)\"})",
             "  compadd -- $candidates",
             "}",
             "_keiyaku \"$@\"",
@@ -75,13 +78,13 @@ export function renderCompletionScript(shell = "bash") {
     }
     return [
         "_keiyaku_completion() {",
-        "  local cur prev",
+        "  local cur context",
         "  cur=\"${COMP_WORDS[COMP_CWORD]}\"",
-        "  prev=\"${COMP_WORDS[COMP_CWORD-1]}\"",
+        "  context=\"${COMP_WORDS[*]:1:$((COMP_CWORD - 1))}\"",
         "  COMPREPLY=()",
         "  while IFS= read -r candidate; do",
         "    COMPREPLY+=(\"$candidate\")",
-        "  done < <(keiyaku completion --complete --word=\"$cur\" --previous=\"$prev\" 2>/dev/null)",
+        "  done < <(keiyaku completion --complete --word=\"$cur\" --previous=\"$context\" 2>/dev/null)",
         "}",
         "complete -F _keiyaku_completion keiyaku",
     ].join("\n");

package/build/cli/flags.js

@@ -47,6 +47,11 @@ export const FLAG_SPECS = {
         placeholder: "DURATION",
         description: "Wait at most a positive duration such as 45s, 5m, or 2h (maximum 24h).",
     },
+    entry: {
+        kind: "value",
+        placeholder: "N",
+        description: "Select one zero-based retained history entry from an addressed projection.",
+    },
     any: {
         kind: "boolean",
         description: "For a projection set, return when the first observed member reaches a terminal state.",
@@ -58,7 +63,7 @@ export const FLAG_SPECS = {
     },
     incognito: {
         kind: "boolean",
-        description: "Do not persist response history and do not allow revive.",
+        description: "Do not persist response history and do not allow fork.",
     },
     bare: {
         kind: "boolean",
@@ -151,6 +156,10 @@ export const FLAG_SPECS = {
         kind: "boolean",
         description: "Renew onto the current target before petitioning.",
     },
+    audit: {
+        kind: "boolean",
+        description: "Run the ordinary read-only audit after a completed renew.",
+    },
     continue: {
         kind: "boolean",
         description: "Continue from the derived renew conflict scratch.",
@@ -191,11 +200,29 @@ export const FLAG_SPECS = {
         kind: "boolean",
         description: "Render structured data as JSON.",
     },
+    limit: {
+        kind: "value",
+        placeholder: "COUNT",
+        description: "Limit terminal rows in the Akuma roster.",
+    },
+    offset: {
+        kind: "value",
+        placeholder: "COUNT",
+        description: "Skip terminal rows in the Akuma roster.",
+    },
+    raw: {
+        kind: "boolean",
+        description: "Include retained raw event bodies when inspecting one history entry.",
+    },
     "diff-budget": {
         kind: "value",
         placeholder: "BYTES",
         description: "Set the audit raw-diff presentation budget in bytes.",
     },
+    "skip-diff-body": {
+        kind: "boolean",
+        description: "Suppress raw diff hunk bodies from the human audit presentation without changing audit evidence or checks.",
+    },
     done: {
         kind: "boolean",
         description: "Show terminal tasks.",
@@ -213,51 +240,51 @@ export const FLAG_SPECS = {
     pri: {
         kind: "value",
         placeholder: "0-3",
-        description: "Set task priority from 0 through 3.",
+        description: "Set task priority: 0 (highest) through 3 (lowest).",
     },
     needs: {
         kind: "value",
         placeholder: "ID",
-        description: "Add a task dependency. May be repeated.",
+        description: "Order execution: this task needs another task first. May be repeated.",
     },
     "drop-needs": {
         kind: "value",
         placeholder: "ID",
-        description: "Remove a task dependency. May be repeated.",
+        description: "Remove an execution-ordering dependency. May be repeated.",
     },
     parent: {
         kind: "value",
         placeholder: "ID",
-        description: "Set the parent task.",
+        description: "Organize task hierarchy under a parent task.",
     },
     "no-parent": {
         kind: "boolean",
-        description: "Clear the parent task.",
+        description: "Clear the hierarchy parent task.",
     },
     from: {
         kind: "value",
         placeholder: "ID",
-        description: "Add a discovery-lineage task. May be repeated.",
+        description: "Record work discovered while doing another task. May be repeated.",
     },
     supersedes: {
         kind: "value",
         placeholder: "ID",
-        description: "Record that this task supersedes another task. May be repeated.",
+        description: "Record that this task replaces another task. May be repeated.",
     },
     "drop-supersedes": {
         kind: "value",
         placeholder: "ID",
-        description: "Remove a supersedes relation. May be repeated.",
+        description: "Remove a replacement relation. May be repeated.",
     },
     "relates-to": {
         kind: "value",
         placeholder: "ID",
-        description: "Record related work. May be repeated.",
+        description: "Record a thematic relation without ordering or replacement. May be repeated.",
     },
     "drop-relates-to": {
         kind: "value",
         placeholder: "ID",
-        description: "Remove a related-work relation. May be repeated.",
+        description: "Remove a thematic relation. May be repeated.",
     },
     title: {
         kind: "value",
@@ -274,6 +301,11 @@ export const FLAG_SPECS = {
         placeholder: "TEXT|-",
         description: "Append a Markdown paragraph to the task body; literal - reads stdin.",
     },
+    note: {
+        kind: "value",
+        placeholder: "TEXT|-",
+        description: "Append an immutable task note; literal - reads stdin.",
+    },
 };
 export const CONTROL_FLAGS = new Set(Object.keys(FLAG_SPECS));
 export const VALUE_FLAGS = new Set(Object.entries(FLAG_SPECS)

package/build/cli/help.js

@@ -25,7 +25,7 @@ export function renderCliCommandHelp(_command, spec, flagSpecs) {
     section(lines, "Purpose:", [spec.purpose]);
     section(lines, "Subcommands:", spec.subcommands);
     section(lines, "Input:", spec.input);
-    section(lines, "Options:", spec.flags.map((name) => `${flagUsage(name, flagSpecs)}  ${spec.flagDescriptions?.[name] ?? flagSpecs[name]?.description ?? ""}`));
+    section(lines, "Options:", spec.flags.map((name) => `${spec.flagUsages?.[name] ?? flagUsage(name, flagSpecs)}  ${spec.flagDescriptions?.[name] ?? flagSpecs[name]?.description ?? ""}`));
     section(lines, "Notes:", spec.notes);
     section(lines, "Examples:", spec.examples);
     return lines.join("\n").trimEnd();
@@ -39,27 +39,27 @@ export function renderCliHelp(version) {
         "  keiyaku @<commission> <command> [flags]",
         "",
         "Flow:",
-        "  bind -> delivery work -> petition",
-        "  optional: arc -> delivery work -> arc; renew on base drift",
+        "  bind -> make and commit changes -> petition",
+        "  optional: arc -> make and commit changes -> arc; renew when the target moves",
         "",
         "Commands:",
-        "  bind       Create a contract ledger and workspace files.",
-        "  arc        Optional iteration; seals current intent first.",
-        "  renew      Rewrite delivery onto the current base and seal it.",
-        "  call       Start an Akuma helper session.",
-        "  wait       Wait for an akuma projection.",
-        "  revive     Revive an Akuma helper session.",
-        "  tell       Send intent to an Akuma projection.",
-        "  kill       Stop the current Akuma generation.",
-        "  log        Render a contract ledger.",
-        "  akuma      Inspect helper profiles.",
+        "  bind       Create a contract and its workspace.",
+        "  arc        Seal the current stage and begin another.",
+        "  renew      Refresh committed changes onto the contract target.",
+        "  call       Start an Akuma projection.",
+        "  wait       Wait for a projection.",
+        "  fork       Start a projection from a response artifact.",
+        "  tell       Send a message to a projection.",
+        "  kill       Stop a projection's active run.",
+        "  log        Show a contract history.",
+        "  akuma      Inspect available Akuma definitions.",
         "  skills     Install bundled official skills.",
         "  amend      Record an amendment.",
-        "  petition   Run settlement processing.",
-        "  forfeit    Forfeit an addressed contract.",
+        "  petition   Ask Keiyaku to settle a contract.",
+        "  forfeit    End a contract without claiming it.",
         "  guide      Print workflow guidance.",
         "  completion Print shell completion.",
-        "  status     Render the Kanshi board.",
+        "  status     Show contracts, tasks, and projections that need attention.",
         "  task       Manage lightweight repository tasks.",
         "  dump-env   Print the environment template.",
         "",
@@ -67,12 +67,12 @@ export function renderCliHelp(version) {
         "  <> means required; [] means optional.",
         "  bind, arc, amend, and petition read document stdin only when literal `-` selects it.",
         "  call and tell require literal BODY or `-`; literal `-` selects stdin.",
-        "  revive accepts an artifact plus optional BODY or `-`; unselected stdin is ignored.",
+        "  fork accepts an artifact plus optional BODY or `-`; unselected stdin is ignored.",
         "",
         "Configuration:",
-        "  Akuma profiles  <KEIYAKU_HOME>/akuma/*.md or .keiyaku/akuma/*.md",
+        "  Akuma definitions  <KEIYAKU_HOME>/akuma/*.md or .keiyaku/akuma/*.md",
         "  Settings        <KEIYAKU_HOME>/settings.json or .keiyaku/settings.json",
-        "  Inspect         keiyaku akuma ls | keiyaku akuma show NAME",
+        "  Inspect         keiyaku akuma list | keiyaku akuma show NAME",
         "  Environment     keiyaku dump-env",
         "  Full format     README Configuration",
     ].join("\n");
@@ -81,18 +81,17 @@ export function buildKeiyakuGuide(version) {
     return [
         `# Keiyaku Guide (v${version})`,
         "",
-        "## Workflow",
-        "`bind -> delivery work -> petition`",
-        "optional: `arc -> delivery work -> arc`; renew on base drift",
+        "A task is a planning item: it does not create a workspace or start work.",
+        "A contract is one bounded delivery with its own workspace. It begins bound and ends claimed when settlement lands it, or forfeited when it is ended without a claim.",
+        "An Akuma is a callable worker definition. A projection is one run of an Akuma.",
         "",
-        "- `bind` supplies derived default intent a0.",
-        "- `arc` is an optional iteration boundary, not admission; the first explicit arc seals a0, and later arcs seal the previous open explicit arc.",
-        "- `renew` seals the current a0 or open explicit arc after a successful refresh onto the default branch.",
-        "- `petition` seals the current a0 or open explicit arc and starts settlement.",
-        "- After an explicit arc closes, loose commits require another arc before renew or petition.",
-        "- `call` and `revive` provide helper execution without changing the ledger lifecycle.",
-        "- `skills install` installs the bundled official Keiyaku skills into supported agent skill directories; force permits replacement of foreign collisions.",
-        "- `status` is read-only and reports next actions, drift, queue state, and projections.",
+        "`bind -> make and commit changes -> petition`",
+        "",
+        "Binding a contract establishes its first delivery stage. A `seal` records that stage's committed changes and scope at a lifecycle boundary.",
+        "`arc` is an optional boundary: it seals the current stage and opens the next. Use arcs only for successive stages of one contract and one final settlement; they do not create separately claimable work.",
+        "When the contract target moves, `renew` refreshes the committed changes onto it and seals the refreshed current stage.",
+        "`petition` seals the current stage, runs the contract's settlement checks, and claims the contract only when they pass. If a settlement gate fails, the contract is not claimed; address the reported problem and petition again.",
+        "Use separate tasks and contracts for work with separate acceptance, ownership, or waiting needs. `status` shows the work that needs attention.",
     ].join("\n");
 }
 export function commandMetadata(command) {

package/build/cli/index.js

@@ -220,9 +220,6 @@ async function resolveCliInput(parsed) {
     const selected = selectedArgument(parsed);
     const token = selected?.token;
     const selectsStdin = token === "-";
-    if (selectsStdin && process.stdin.isTTY) {
-        throw new FlowError("INVALID_USAGE", `${parsed.command} literal '-' requires piped stdin`);
-    }
     const piped = selectsStdin ? await readStdin() : "";
     const input = selectsStdin ? piped : token ?? "";
     if (stdinMeta.selector?.required && token === undefined) {
@@ -235,8 +232,12 @@ async function resolveCliInput(parsed) {
         const message = stdinMeta.mode === "document"
             ? `No Markdown input received on stdin.\n\nExample:\n  ${usageExample(parsed.command)}`
             : selectsStdin
-                ? `${parsed.command} received no body on stdin`
-                : `${parsed.command} body cannot be empty`;
+                ? parsed.command === "task add"
+                    ? "task add received no task document on stdin"
+                    : `${parsed.command} received no body on stdin`
+                : parsed.command === "task add"
+                    ? "task add title cannot be empty"
+                    : `${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

@@ -126,6 +126,9 @@ export function assignFlag(flags, name, value) {
         case "renew":
             flags.renewBeforePetition = Boolean(value);
             return;
+        case "audit":
+            flags.renewAudit = Boolean(value);
+            return;
         case "continue":
             flags.renewContinue = Boolean(value);
             return;
@@ -167,6 +170,9 @@ export function assignFlag(flags, name, value) {
             flags.auditDiffBudgetBytes = parsed;
             return;
         }
+        case "skip-diff-body":
+            flags.auditSkipDiffBody = Boolean(value);
+            return;
         case "done":
             flags.done = Boolean(value);
             return;
@@ -179,6 +185,33 @@ export function assignFlag(flags, name, value) {
             }
             flags.taskSort = String(value);
             return;
+        case "limit": {
+            const parsed = Number(String(value));
+            if (!Number.isSafeInteger(parsed) || parsed < 1) {
+                throw new FlowError("INVALID_USAGE", "option --limit requires a positive safe integer entry count");
+            }
+            flags.historyLimit = parsed;
+            return;
+        }
+        case "offset": {
+            const parsed = Number(String(value));
+            if (!Number.isSafeInteger(parsed) || parsed < 0) {
+                throw new FlowError("INVALID_USAGE", "option --offset requires a non-negative safe integer entry count");
+            }
+            flags.historyOffset = parsed;
+            return;
+        }
+        case "entry": {
+            const parsed = Number(String(value));
+            if (!Number.isSafeInteger(parsed) || parsed < 0) {
+                throw new FlowError("INVALID_USAGE", "option --entry requires a non-negative safe integer retained entry index");
+            }
+            flags.historyEntry = parsed;
+            return;
+        }
+        case "raw":
+            flags.historyRaw = Boolean(value);
+            return;
         case "pri": {
             const raw = String(value);
             if (!/^[0-3]$/.test(raw)) {
@@ -238,6 +271,12 @@ export function assignFlag(flags, name, value) {
             }
             flags.taskAppend = String(value);
             return;
+        case "note":
+            if (flags.taskNote !== undefined) {
+                throw new FlowError("INVALID_USAGE", "option --note may only be specified once");
+            }
+            flags.taskNote = String(value);
+            return;
         default:
             throw new FlowError("UNKNOWN_OPTION", `unknown option: --${name}`);
     }

package/build/cli/parse-metadata.js

@@ -68,7 +68,7 @@ export function commandPositionalRange(command) {
     if (command === "tell") {
         return { min: 2, max: 2, label: "<PROJECTION> <BODY|->" };
     }
-    if (command === "revive") {
+    if (command === "fork") {
         return { min: 1, max: 2, label: "<ARTIFACT> [BODY|-]" };
     }
     if (command === "wait") {
@@ -84,7 +84,7 @@ export function commandPositionalRange(command) {
         return { min: 0, max: 1, label: "[projection|alias|rsp]" };
     }
     if (command === "task add") {
-        return { min: 1, max: 1, label: "<BODY|->" };
+        return { min: 1, max: 1, label: "<TITLE|->" };
     }
     if (command === "task compose") {
         return { min: 0, max: 0 };
@@ -92,6 +92,9 @@ export function commandPositionalRange(command) {
     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>" };
     }
+    if (command === "task note") {
+        return { min: 2, max: 2, label: "<ID> <TEXT|->" };
+    }
     if (command === "task update") {
         return { min: 1, max: 1, label: "<ID>" };
     }

package/build/cli/parse-selectors.js

@@ -14,6 +14,21 @@ const COMMISSION_SELECTOR_COMMANDS = new Set([
     "petition",
     "forfeit",
     "audit",
+    "status",
+    "task add",
+    "task compose",
+    "task show",
+    "task ls",
+    "task log",
+    "task start",
+    "task stop",
+    "task hold",
+    "task resume",
+    "task done",
+    "task note",
+    "task drop",
+    "task update",
+    "task doctor",
 ]);
 function formatSelectorList(items) {
     if (items.length <= 1) {
@@ -49,6 +64,9 @@ export function assertCommissionSelectorAllowed(command, flags) {
     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 === "status" && flags.contractId !== undefined && restLength + payloadLength > 0) {
+        throw new FlowError("INVALID_USAGE", `status accepts either one projection id or one commission selector; ${flags.contractAddressSource === "at-address" ? atTokens[0] ?? `@${flags.contractId}` : `--contract ${contractFlagRaws[0] ?? flags.contractId}`} cannot be combined with a projection id`);
+    }
     if ((command !== "wait" && command !== "tell") || flags.contractId === undefined) {
         return;
     }

package/build/cli/parse.js

@@ -4,10 +4,13 @@ import { isResponseArtifactId } from "../core/response-artifact-id.js";
 import { isCommissionId } from "../core/ids.js";
 import { HELP_FLAGS } from "./flags.js";
 import { getCommandMetadata } from "./commands/metadata.js";
+import { AKUMA_SUBCOMMANDS } from "./types.js";
 import { assertAllowedFlag, assignFlag, BOOLEAN_FLAGS, CONTROL_FLAGS, parseFlagName, readValueFlag, SHORT_FLAG_ALIASES, VALUE_FLAGS, } from "./parse-flags.js";
 import { commandPositionalRange, isCallCommand, resolveCommand, splitAtLiteralBoundary, TASK_SUBCOMMANDS, } from "./parse-metadata.js";
 import { applyCommissionSelector, assertCommissionSelectorAllowed, assertProjectionSelectorPresent, } from "./parse-selectors.js";
 import { WAIT_SET_SELECTION_ERROR } from "./commands/projection/wait/meta.js";
+import { TASK_ADD_INPUT_SHAPE_ERROR } from "./commands/task/add/meta.js";
+import { TASK_UPDATE_EXPLICIT_CHANGE_ERROR } from "./commands/task/update/meta.js";
 export { commandPositionalRange, isCallCommand, isPetitionDryRunInvocation, normalizeContractAddress, parseWaitTimeout, } from "./parse-metadata.js";
 export function parseCliArgs(tokens) {
     const { head, payload } = splitAtLiteralBoundary(tokens);
@@ -64,6 +67,14 @@ export function parseCliArgs(tokens) {
             throw new FlowError("UNKNOWN_OPTION", `unknown option: --${name}`);
         }
         seenFlagNames.add(name);
+        // `--akuma` is a status-only collection selector. Elsewhere it remains
+        // the existing value-taking launch option.
+        if (name === "akuma" && head.includes("status")) {
+            if (eq !== -1)
+                throw new FlowError("INVALID_USAGE", "option --akuma does not accept a value for status");
+            flags.akumaRoster = true;
+            continue;
+        }
         if (VALUE_FLAGS.has(name)) {
             const { value, nextIndex } = readValueFlag(name, token, eq, head, index);
             index = nextIndex;
@@ -103,7 +114,7 @@ export function parseCliArgs(tokens) {
         };
     }
     if (command === "akuma") {
-        throw new FlowError("EMPTY_PARAM", "akuma requires subcommand: ls or show");
+        throw new FlowError("EMPTY_PARAM", `akuma requires subcommand: ${AKUMA_SUBCOMMANDS.slice(0, -1).join(", ")} or ${AKUMA_SUBCOMMANDS.at(-1)}`);
     }
     if (command === "skills") {
         throw new FlowError("EMPTY_PARAM", "skills requires subcommand: install");
@@ -144,14 +155,11 @@ export function parseCliArgs(tokens) {
         && flags.taskParent === undefined && !flags.taskNoParent && flags.taskFrom === undefined
         && flags.taskSupersedes === undefined && flags.taskDropSupersedes === undefined
         && flags.taskRelatesTo === undefined && flags.taskDropRelatesTo === undefined) {
-        throw new FlowError("EMPTY_PARAM", "task update requires at least one change");
+        throw new FlowError("INVALID_USAGE", TASK_UPDATE_EXPLICIT_CHANGE_ERROR);
     }
     if (command === "petition" && flags.json && !flags.dryRun) {
         throw new FlowError("INVALID_USAGE", "petition --json requires --dry-run");
     }
-    if (command === "petition" && flags.dryRun && (flags.appendScope?.length ?? 0) > 0) {
-        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) {
@@ -164,6 +172,9 @@ export function parseCliArgs(tokens) {
     assertCommissionSelectorAllowed(command, flags);
     assertProjectionSelectorPresent(command, flags, atTokens, contractFlagRaws, rest.length, payload.length);
     const positional = [...rest, ...payload];
+    if (command === "amend" && flags.appendScope && positional.length > 0 && positional[0] !== "-") {
+        throw new FlowError("INVALID_USAGE", "amend accepts Markdown only through literal '-' and --append-scope never reads unselected stdin");
+    }
     if (command === "bind" && flags.contractId !== undefined) {
         if (!isCommissionId(flags.contractId)) {
             throw new FlowError("UNKNOWN_ADDRESS", `bind replay requires a full canonical contract id; got ${flags.contractId}`);
@@ -228,9 +239,11 @@ export function parseCliArgs(tokens) {
         && positional.length === stdin.selector.index + 1
         && positional[stdin.selector.index] === "-";
     if (positional.length > positionalRange.max && !documentStdinSelector) {
-        const message = stdin.mode === "document"
-            ? `${command} reads Markdown only through literal '-'; file path arguments are not supported`
-            : `${command} does not accept positional arguments`;
+        const message = command === "task add"
+            ? TASK_ADD_INPUT_SHAPE_ERROR
+            : stdin.mode === "document"
+                ? `${command} reads Markdown only through literal '-'; file path arguments are not supported`
+                : `${command} does not accept positional arguments`;
         throw new FlowError("INVALID_USAGE", message);
     }
     return { command, flags, positional };