@astrosheep/keiyaku 4.5.20 → 4.5.21

package/build/src/body/region.js

@@ -1,4 +1,3 @@
-import { directChildren, rawSlice } from "../markdown/query.js";
 export class RegionDocumentError extends Error {
     constructor(message) {
         super(message);
@@ -8,9 +7,6 @@ export class RegionDocumentError extends Error {
 function refusal(message) {
     throw new RegionDocumentError(message);
 }
-function nonblank(document, node) {
-    return rawSlice(document, node.span).trim().length > 0;
-}
 function compileSegment(segment, pattern) {
     if (segment === "**")
         return { kind: "deep" };
@@ -113,15 +109,94 @@ function patternsOverlap(left, right) {
     }
     return false;
 }
-export function decodeRegion(document, section) {
-    const blocks = directChildren(section, "code_block");
-    if (blocks.length !== 1 || !blocks[0].closed || (blocks[0].info !== "" && blocks[0].info !== "txt")) {
-        refusal("Region must contain one closed fence with no info string or the exact 'txt' info string");
+const THEMATIC_BREAK = /^ {0,3}(?:(?:-[ \t]*){3,}|(?:\*[ \t]*){3,}|(?:_[ \t]*){3,})$/u;
+const TABLE_DELIMITER = /^ {0,3}\|?[ \t]*:?-+:?[ \t]*(?:\|[ \t]*:?-+:?[ \t]*)*\|?[ \t]*$/u;
+function nonblank(line) {
+    return line.trim().length > 0;
+}
+/** The AST has no table, thematic-break, or HTML block kind, so the Region boundary classifies that prose itself. */
+function foreignProseKind(lines) {
+    for (const line of lines) {
+        if (THEMATIC_BREAK.test(line))
+            return "thematic break";
+        if (/^ {0,3}</u.test(line))
+            return "HTML";
+    }
+    for (let index = 1; index < lines.length; index += 1) {
+        if (lines[index - 1].includes("|") && TABLE_DELIMITER.test(lines[index]))
+            return "table";
+    }
+    return null;
+}
+function nodeKind(node) {
+    return node.type.replaceAll("_", " ");
+}
+function article(kind) {
+    return kind === "HTML" || /^[aeiou]/iu.test(kind) ? "an" : "a";
+}
+function itemLines(item) {
+    const lines = [];
+    for (const child of item.children) {
+        if (child.type === "text")
+            lines.push(...child.lines);
+        else if (child.type === "list")
+            for (const nested of child.items)
+                lines.push(...itemLines(nested));
     }
-    const other = section.children.filter((node) => node !== blocks[0] && nonblank(document, node));
-    if (other.length > 0)
-        refusal("Region may contain only its fenced declaration");
-    const patterns = blocks[0].lines.slice(1, -1).filter((line) => line.trim().length > 0);
+    return lines.filter(nonblank);
+}
+/**
+ * Structural refusals are separate from pattern compilation so a caller may aggregate every independent failure.
+ * The three authoring forms — fenced lines, list items, and bare paragraph lines — union freely. Blank lines never
+ * count, and an info string beyond the exact `txt` still implies executable content that belongs to Verification.
+ */
+export function regionStructure(section) {
+    for (const node of section.children) {
+        if (node.type === "code_block") {
+            if (!node.closed)
+                return "Region fence must be closed";
+            if (node.info !== "" && node.info !== "txt") {
+                return "Region fence may not carry an info string other than the exact 'txt'";
+            }
+            continue;
+        }
+        if (node.type === "list")
+            continue;
+        if (node.type === "text") {
+            const foreign = foreignProseKind(node.lines);
+            if (foreign !== null)
+                return `Region may not contain ${article(foreign)} ${foreign} block`;
+            continue;
+        }
+        const kind = nodeKind(node);
+        return `Region may not contain ${article(kind)} ${kind} block`;
+    }
+    return null;
+}
+function regionPatterns(section) {
+    const patterns = [];
+    for (const node of section.children) {
+        if (node.type === "code_block")
+            patterns.push(...node.lines.slice(1, -1).filter(nonblank));
+        else if (node.type === "list")
+            for (const item of node.items)
+                patterns.push(...itemLines(item));
+        else if (node.type === "text")
+            patterns.push(...node.lines.filter(nonblank));
+    }
+    return patterns;
+}
+/** A whitespace-bearing pattern is almost certainly strayed prose; bind warns and proceeds rather than rejecting. */
+export function regionWarnings(patterns) {
+    return patterns
+        .filter((pattern) => /\s/u.test(pattern))
+        .map((pattern) => `Region pattern '${pattern}' contains whitespace and will never match a path`);
+}
+export function decodeRegion(_document, section) {
+    const structural = regionStructure(section);
+    if (structural !== null)
+        refusal(structural);
+    const patterns = regionPatterns(section);
     if (patterns.length === 0)
         refusal("Region must declare at least one path pattern");
     return patterns.map((pattern) => compileRegionPattern(pattern).source);

package/build/src/body/render.js

@@ -47,7 +47,7 @@ export function renderContractBody(body, currentArc) {
         section(CONTRACT_SECTIONS.context.title, body.context),
         section(CONTRACT_SECTIONS.objective.title, body.objective),
         section(CONTRACT_SECTIONS.design.title, body.design),
-        section(CONTRACT_SECTIONS.region.title, fenced(body.region.join("\n"))),
+        section(CONTRACT_SECTIONS.region.title, body.region.join("\n")),
         section(CONTRACT_SECTIONS.criteria.title, criteria),
         ...(verification.length === 0 ? [] : [section(CONTRACT_SECTIONS.verification.title, verification)]),
         ...body.extensions.map((extension) => section(extension.title, extension.content)),

package/build/src/body/verification.d.ts

@@ -4,4 +4,6 @@ export type { VerificationDeclaration, VerificationExecutor } from "../verificat
 export declare class VerificationDocumentError extends Error {
     constructor(message: string);
 }
-export declare function decodeVerificationDeclarations(document: DocumentNode, section: SectionNode): readonly VerificationDeclaration[];
+export declare function decodeVerificationDeclarations(document: DocumentNode, section: SectionNode, options?: Readonly<{
+    requireTimeout?: boolean;
+}>): readonly VerificationDeclaration[];

package/build/src/body/verification.js

@@ -6,7 +6,7 @@ export class VerificationDocumentError extends Error {
         this.name = "VerificationDocumentError";
     }
 }
-export function decodeVerificationDeclarations(document, section) {
+export function decodeVerificationDeclarations(document, section, options = {}) {
     const blocks = directChildren(section, "code_block");
     if (blocks.length === 0)
         throw new VerificationDocumentError("Verification must contain one or more fenced executor declarations");
@@ -31,6 +31,9 @@ export function decodeVerificationDeclarations(document, section) {
         if (duration?.kind === "parsed" && duration.milliseconds === 0) {
             throw new VerificationDocumentError("Verification timeout must be positive");
         }
+        if (options.requireTimeout === true && duration === undefined) {
+            throw new VerificationDocumentError("Verification declarations must specify timeout=<duration>");
+        }
         return {
             executor: info[1],
             script,

package/build/src/cli/accepted.js

@@ -24,6 +24,20 @@ function acceptedEnvelope(result, coordinate) {
         ...(result.executionStops.length === 0 ? {} : { executionStops: result.executionStops }),
     };
 }
+/**
+ * The completed placement's movement identity — the reference it advanced and the head it advanced from — is part
+ * of the public accepted shape, so a receipt states the movement without rebuilding it from facts or folded state.
+ */
+function acceptedCompletion(completion) {
+    if (completion === undefined)
+        return undefined;
+    return {
+        integration: completion.integration,
+        ...(completion.predecessor === undefined ? {} : { predecessor: completion.predecessor }),
+        ...(completion.target === undefined ? {} : { target: completion.target }),
+        ...(completion.verification === undefined ? {} : { verification: completion.verification }),
+    };
+}
 function acceptedRegion(result) {
     if (result.overlapFailure !== undefined)
         return { overlapFailure: result.overlapFailure };
@@ -42,6 +56,7 @@ export function acceptedBind(result, coordinates) {
         verb: "bind",
         ...(result.workspace === undefined ? {} : { workspace: result.workspace }),
         target: coordinates.target ?? null,
+        ...(result.warnings === undefined ? {} : { warnings: result.warnings }),
         ...acceptedRegion(result),
     };
 }
@@ -56,6 +71,7 @@ export function acceptedAmend(result, coordinate) {
 export function acceptedDeliver(result, coordinate) {
     const value = result.value;
     const attestation = attestationFor(result.facts, "verified", coordinate);
+    const completion = acceptedCompletion(value.completion);
     const verificationVerdict = value.completion?.verification?.verdict ?? attestation?.data.verdict ?? value.verificationReuse?.verdict;
     return {
         ...acceptedEnvelope(result, coordinate),
@@ -63,7 +79,7 @@ export function acceptedDeliver(result, coordinate) {
         tenderSnapshot: value.tenderSnapshot,
         integration: { changeId: value.integration.changeId },
         ...(value.leading === undefined ? {} : { leading: value.leading }),
-        ...(value.completion === undefined ? {} : { completion: value.completion }),
+        ...(completion === undefined ? {} : { completion }),
         ...(verificationVerdict === undefined ? {} : { verificationVerdict }),
         ...(value.verification === undefined ? {} : { verification: value.verification }),
         ...(value.verificationReuse === undefined ? {} : { verificationReuse: value.verificationReuse }),
@@ -78,6 +94,7 @@ export function acceptedReview(result, coordinate) {
     if (reviewAttestation === undefined)
         throw new Error("accepted review is missing its attestation fact");
     const verificationAttestation = attestationFor(result.facts, "verified", coordinate);
+    const completion = acceptedCompletion(value.completion);
     const verificationVerdict = value.completion?.verification?.verdict ??
         verificationAttestation?.data.verdict ??
         value.verificationReuse?.verdict;
@@ -85,7 +102,7 @@ export function acceptedReview(result, coordinate) {
         ...acceptedEnvelope(result, coordinate),
         verb: "review",
         verdict: reviewAttestation.data.verdict,
-        ...(value.completion === undefined ? {} : { completion: value.completion }),
+        ...(completion === undefined ? {} : { completion }),
         ...(verificationVerdict === undefined ? {} : { verificationVerdict }),
         ...(value.verification === undefined ? {} : { verification: value.verification }),
         ...(value.verificationReuse === undefined ? {} : { verificationReuse: value.verificationReuse }),

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

@@ -11,6 +11,7 @@ export type AkumaInvocationResult = Readonly<{
     result: CallResult;
     world: WorldRoot;
     schemaAnswer?: unknown;
+    streamed?: boolean;
 }> | Readonly<{
     kind: "akuma";
     action: "status";
@@ -21,6 +22,7 @@ export type AkumaInvocationResult = Readonly<{
     action: "wait";
     result: AkumaWaitResult;
     alias?: string;
+    streamed?: boolean;
 }> | Readonly<{
     kind: "akuma";
     action: "tell";

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

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

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

@@ -32,6 +32,7 @@ const AKUMA_COMMAND_SPECS = {
             "A nested birth is clipped to its direct parent's frozen actions. status <aku/...|@alias> shows the born effective set.",
             "--schema reads a JSON Schema file for the answer contract; stdin remains the prompt source.",
             "With --contract, Dispatch succeeds first. If @name exists, the alias then moves.",
+            "While it waits, settled timeline rows stream on stderr; the final answer is written to stdout once.",
         ].join("\n"),
     },
     wait: {
@@ -39,7 +40,16 @@ const AKUMA_COMMAND_SPECS = {
         stdin: false,
         flags: { any: "boolean", all: "boolean", timeout: "value", json: "boolean" },
         usage: "wait <akuma-selector>... [--any | --all] [--timeout <duration>]",
-        purpose: "Wait for one Akuma or an explicitly selected Akuma set.",
+        purpose: "Wait for one Akuma or a selected Akuma set.",
+        details: [
+            "Without --any or --all the mode is any: the wait returns when any selected Akuma completes.",
+            "--all waits until every selected Akuma completes.",
+            "An already completed member counts immediately, so repeating a selection can return at once.",
+            "Identity frames, settled rows, and the closing scoreboard stream on stderr.",
+            "A streamed plural wait leaves stdout empty, and so does a single wait with no answer.",
+            "Only a single selected Akuma that answered writes to stdout, exactly its answer.",
+            "With --json nothing streams and stdout carries the result document.",
+        ].join("\n"),
     },
     tell: {
         arity: 1,
@@ -199,9 +209,6 @@ function validateSet(value, fail) {
 function parseWait(rawSelectors, flags, output, fail) {
     if (flags.any === true && flags.all === true)
         fail("wait --any and --all are mutually exclusive");
-    if (rawSelectors.length > 1 && flags.any !== true && flags.all !== true) {
-        fail("wait requires --any or --all when selecting multiple Akuma");
-    }
     const completion = flags.any === true ? "any" : flags.all === true ? "all" : undefined;
     return {
         command: "wait",

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

@@ -15,18 +15,26 @@ export const CONTRACT_COMMAND_SPECS = {
         usage: "bind [--task <task/...>] [--target <ref>] [--after <kei/...> ...] [--gates <name,...>] [--actor <actor>] - | bind --fork-of <kei/...> [--target <ref>] [--actor <actor>]",
         purpose: "Create one Contract from stdin Markdown or a sibling fork.",
         details: [
+            "--gates <name,...> accepts gate words and configured bundle names together.",
+            "A matching bundle expands; otherwise the name is a literal gate. Duplicates",
+            "are removed in first-seen order. Gate words match ^[a-z][a-z0-9-]{0,63}$.",
+            "Omitting --gates selects gates.default, or reviewed when no default exists.",
+            '--gates "" explicitly binds without gates; --gates reviewed needs no bundle.',
+            "",
             "stdin is Contract Markdown:",
             "  # <title>",
             "  ## Context       motivation, authority, baseline, and boundaries",
             "  ## Objective    one observable end state",
             "  ## Design       closed decisions and ordering",
-            "  ## Region       one fenced path-pattern declaration",
+            "  ## Region       intended path patterns as fenced lines, list items, or bare lines",
             "  ## Criteria     one or more ### <criterion> entries",
             "  ## Verification optional fenced executor declarations",
             "",
-            "Region uses one closed fence with no info string or exactly 'txt'; put one",
-            "repository-relative path pattern on each nonblank line. A trailing '/'",
-            "is directory shorthand for 'path/**'.",
+            "Region accepts intended path patterns as fenced lines, list items, or bare",
+            "lines; the three forms union. Put one repository-relative path pattern on",
+            "each nonblank line. A trailing '/' is directory shorthand for 'path/**'.",
+            "A pattern containing whitespace binds with a warning. A fence carries no",
+            "info string or exactly 'txt'.",
             "",
             "Verification uses one or more closed bash, zsh, or pwsh fences. Its fence",
             "may add timeout=<integer><ms|s|m|h>; the section contains no other prose.",
@@ -40,6 +48,11 @@ export const CONTRACT_COMMAND_SPECS = {
         usage: "amend [<contract>|@<contract>] [--after <kei/...> ... | --clear-after] [--gates <name,...>] [--actor <actor>] [-]",
         purpose: "Amend one Contract's document operations or structured terms.",
         details: [
+            "--gates <name,...> replaces gates using gate words and configured bundle names.",
+            "A matching bundle expands; otherwise the name is a literal gate. Duplicates",
+            "are removed in first-seen order. Gate words match ^[a-z][a-z0-9-]{0,63}$.",
+            'Omitting --gates leaves gates unchanged; --gates "" clears them.',
+            "",
             "  ## Context|Objective|Design|Region|Criteria|Verification|<extension>  (replace, or add new extension)",
             "  ## Replace: Context|Objective|Design|Region|Criteria|Verification|<extension>",
             "  ## Append: Context|Objective|Design|Criteria|<extension>",

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

@@ -20,13 +20,15 @@ function optionalFlag(flags, name) {
 function refuse(command, message) {
     throw new CliUsageError(message, commandGuide(command, CONTRACT_COMMAND_SPECS[command].usage));
 }
-function parseGateBundleNames(parts, command) {
+function parseGateNames(parts, command) {
     const value = optionalFlag(parts.flags, "gates");
     if (value === undefined)
         return undefined;
+    if (value === "")
+        return [];
     const names = value.split(",");
     if (names.some((name) => name.length === 0)) {
-        refuse(command, "--gates requires nonempty comma-separated names");
+        refuse(command, '--gates requires comma-separated names or "" to clear gates');
     }
     return names;
 }
@@ -53,7 +55,7 @@ function parseBind(parts) {
     const task = optionalFlag(parts.flags, "task");
     const target = optionalFlag(parts.flags, "target");
     const after = parts.flags.after === undefined ? [] : Array.isArray(parts.flags.after) ? parts.flags.after : [parts.flags.after];
-    const gates = parseGateBundleNames(parts, "bind");
+    const gates = parseGateNames(parts, "bind");
     return {
         command: "bind",
         ...(task === undefined ? {} : { task }),
@@ -69,7 +71,7 @@ function parseAmend(parts) {
     const after = parts.flags.after === undefined ? [] : Array.isArray(parts.flags.after) ? parts.flags.after : [parts.flags.after];
     if (parts.flags["clear-after"] === true && after.length > 0)
         refuse("amend", "--clear-after and --after are mutually exclusive");
-    const gates = parseGateBundleNames(parts, "amend");
+    const gates = parseGateNames(parts, "amend");
     if (!parts.stdin && parts.flags.after === undefined && parts.flags["clear-after"] !== true && gates === undefined) {
         refuse("amend", "amend requires stdin or --after, --clear-after, or --gates");
     }

package/build/src/cli/commands/status-set.js

@@ -13,33 +13,25 @@ async function statusSetAkuma(selector, id, alias, world, repo) {
         ...(result.alias === undefined ? {} : { alias: result.alias }),
     };
 }
-async function statusSetEntry(selector, world, repo, observed) {
-    let resolved = selector;
-    let alias;
+async function statusSetContract(selector, id, world, repo) {
+    if (repo === undefined)
+        throw new CliUsageError("cannot select a contract while the Contract world is absent");
+    const observation = await (await import("../../kanshi/index.js")).observeKanshi({ world, repo, contract: canonicalContractSelector(id) });
+    return { selector, kind: "contract", report: observation.report };
+}
+async function statusSetEntry(selector, world, repo, named) {
     if (selector.startsWith("@")) {
-        if (observed === undefined)
+        if (named === undefined)
             throw new CliUsageError("cannot resolve a named status selector");
         const { resolveNamedAddress } = await import("../../library/address.js");
-        const address = resolveNamedAddress({ selector, report: observed.report, aliases: observed.aliases });
+        const address = resolveNamedAddress({ selector, report: named.report, aliases: named.aliases });
         if (address.kind === "akuma")
             return await statusSetAkuma(selector, address.id, selector, world, repo);
-        resolved = address.id;
-        alias = selector;
+        return await statusSetContract(selector, address.id, world, repo);
     }
-    if (resolved.startsWith("aku/"))
-        return await statusSetAkuma(selector, resolved, alias, world, repo);
-    if (repo === undefined)
-        throw new CliUsageError("cannot select a contract while the Contract world is absent");
-    if (observed === undefined)
-        throw new CliUsageError("cannot observe Contract status without a Kanshi report");
-    return {
-        selector,
-        kind: "contract",
-        report: (await import("../../kanshi/index.js")).selectKanshi({
-            report: observed.report,
-            contract: canonicalContractSelector(resolved),
-        }),
-    };
+    if (selector.startsWith("aku/"))
+        return await statusSetAkuma(selector, selector, undefined, world, repo);
+    return await statusSetContract(selector, selector, world, repo);
 }
 export async function invokeStatusSet(selectors, world, repo) {
     if (selectors.length < 2)
@@ -47,8 +39,7 @@ export async function invokeStatusSet(selectors, world, repo) {
     if (selectors.some((selector) => !selector.startsWith("aku/") && !selector.startsWith("@")) && repo === undefined) {
         throw new CliUsageError("cannot select a contract while the Contract world is absent");
     }
-    const needsKanshi = selectors.some((selector) => !selector.startsWith("aku/"));
-    const observed = needsKanshi
+    const named = selectors.some((selector) => selector.startsWith("@"))
         ? await (await import("../../kanshi/index.js")).observeKanshi({
             world,
             ...(repo === undefined ? {} : { repo }),
@@ -56,6 +47,6 @@ export async function invokeStatusSet(selectors, world, repo) {
         : undefined;
     const entries = [];
     for (const selector of selectors)
-        entries.push(await statusSetEntry(selector, world, repo, observed));
+        entries.push(await statusSetEntry(selector, world, repo, named));
     return { kind: "status-set", entries };
 }

package/build/src/cli/main.js

@@ -1,4 +1,5 @@
 import { CliUsageError, parseArgv, renderHelp } from "./parse.js";
+import { installedPackageVersion } from "./version.js";
 export async function main(argv = process.argv.slice(2)) {
     try {
         const parsed = parseArgv(argv);
@@ -8,6 +9,10 @@ export async function main(argv = process.argv.slice(2)) {
             process.stdout.write(help.endsWith("\n") ? help : `${help}\n`);
             return 0;
         }
+        if ("version" in parsed) {
+            process.stdout.write(`${await installedPackageVersion()}\n`);
+            return 0;
+        }
         return await (await import("./runtime.js")).runCliCommand(parsed);
     }
     catch (error) {