@astrosheep/keiyaku 4.0.6 → 4.1.0

package/build/src/akuma/archetype.js

@@ -96,7 +96,11 @@ function decodeArchetype(name, path, markdown) {
     const network = archetypeEnum(values, "network", ["disabled", "enabled"]);
     const description = archetypeField(values, "description");
     const allowed = effectiveAllowedActions(values.allowed);
+    const systemPromptMode = archetypeEnum(values, "systemPromptMode", ["append", "replace"]);
     const systemPrompt = lines.slice(closing + 1).join("\n");
+    if (systemPromptMode !== undefined && systemPrompt.length === 0) {
+        throw new TypeError("Akuma systemPromptMode requires a nonempty Markdown body");
+    }
     return Object.freeze({
         name,
         path,
@@ -106,7 +110,10 @@ function decodeArchetype(name, path, markdown) {
             ...(model === undefined ? {} : { model }),
             ...(effort === undefined ? {} : { effort }),
             ...(network === undefined ? {} : { network }),
-            ...(systemPrompt.length === 0 ? {} : { systemPrompt }),
+            ...(systemPrompt.length === 0 ? {} : {
+                systemPrompt,
+                systemPromptMode: systemPromptMode ?? "append",
+            }),
         }),
         ...(readonly === undefined ? {} : { readonly }),
         allowed,

package/build/src/akuma/provider-recipe.d.ts

@@ -1,9 +1,11 @@
+export type SystemPromptMode = "append" | "replace";
 export type ProviderOptions = Readonly<{
     model?: string;
     effort?: string;
     readonly?: true;
     network?: "disabled" | "enabled";
     systemPrompt?: string;
+    systemPromptMode?: SystemPromptMode;
 }>;
 export type ReadonlyRestraint = Readonly<{
     enforcement: "native";

package/build/src/akuma/provider-recipe.js

@@ -34,12 +34,22 @@ export function decodeProviderOptions(value) {
         throw new TypeError("provider option network must be disabled, enabled");
     }
     const systemPrompt = optionText(options, "systemPrompt", "allow");
+    const systemPromptMode = options.systemPromptMode;
+    if (systemPromptMode !== undefined) {
+        if (systemPromptMode !== "append" && systemPromptMode !== "replace") {
+            throw new TypeError("provider option systemPromptMode must be append, replace");
+        }
+        if (systemPrompt === undefined) {
+            throw new TypeError("provider option systemPromptMode requires systemPrompt");
+        }
+    }
     return Object.freeze({
         ...(model === undefined ? {} : { model }),
         ...(effort === undefined ? {} : { effort }),
         ...(options.readonly === undefined ? {} : { readonly: true }),
         ...(network === undefined ? {} : { network }),
         ...(systemPrompt === undefined ? {} : { systemPrompt }),
+        ...(systemPromptMode === undefined ? {} : { systemPromptMode }),
     });
 }
 export function decodeReadonlyRestraint(value) {

package/build/src/akuma/providers/acp/config.d.ts

@@ -1,8 +1,10 @@
+import type { SystemPromptMode } from "../../provider-recipe.js";
 export type AcpExecutionConfig = Readonly<{
     argvBefore: readonly string[];
     argvAfter: readonly string[];
     modelArg?: string;
     effortArg?: string;
     systemPromptArg?: string;
+    systemPromptMode?: SystemPromptMode;
 }>;
 export declare function decodeAcpConfig(value: unknown): AcpExecutionConfig;

package/build/src/akuma/providers/acp/config.js

@@ -13,7 +13,7 @@ export function decodeAcpConfig(value) {
     }
     const config = value;
     const unknown = Object.keys(config)
-        .find((key) => !["argvBefore", "argvAfter", "effortArg", "modelArg", "systemPromptArg"].includes(key));
+        .find((key) => !["argvBefore", "argvAfter", "effortArg", "modelArg", "systemPromptArg", "systemPromptMode"].includes(key));
     if (unknown !== undefined)
         throw new TypeError(`ACP provider config has unknown field ${unknown}`);
     if (!Array.isArray(config.argvBefore)
@@ -27,11 +27,19 @@ export function decodeAcpConfig(value) {
     const modelArg = argumentName(config, "modelArg");
     const effortArg = argumentName(config, "effortArg");
     const systemPromptArg = argumentName(config, "systemPromptArg");
+    const systemPromptMode = config.systemPromptMode;
+    if (systemPromptMode !== undefined && systemPromptMode !== "append" && systemPromptMode !== "replace") {
+        throw new TypeError("ACP provider config systemPromptMode must be append, replace");
+    }
+    if (systemPromptMode !== undefined && systemPromptArg === undefined) {
+        throw new TypeError("ACP provider config systemPromptMode requires systemPromptArg");
+    }
     return Object.freeze({
         argvBefore: Object.freeze([...config.argvBefore]),
         argvAfter: Object.freeze([...config.argvAfter]),
         ...(modelArg === undefined ? {} : { modelArg }),
         ...(effortArg === undefined ? {} : { effortArg }),
         ...(systemPromptArg === undefined ? {} : { systemPromptArg }),
+        ...(systemPromptMode === undefined ? {} : { systemPromptMode }),
     });
 }

package/build/src/akuma/providers/acp/core.d.ts

@@ -1,16 +1,19 @@
-import * as acp from "@agentclientprotocol/sdk";
+import type * as AcpSdk from "@agentclientprotocol/sdk";
 import { spawnStdioProcess } from "../../../runtime/proc/stdio.js";
 import { type ProviderAdapter, type Session } from "../../provider.js";
 import { type AcpToolInterpreter, type AcpToolUpdate } from "./events.js";
 export type { AcpToolInterpreter, AcpToolUpdate };
 export type AcpStartInput = Parameters<ProviderAdapter["start"]>[0] | Parameters<NonNullable<ProviderAdapter["resume"]>>[0];
+export type AcpSessionMeta = Readonly<Record<string, unknown>>;
 export type AcpDependencies = Readonly<{
     spawnProcess?: typeof spawnStdioProcess;
     interpretTool?: AcpToolInterpreter;
+    freshSessionMeta?: AcpSessionMeta;
+    loadSessionMeta?: AcpSessionMeta;
 }>;
 export type AcpLiveSession = Readonly<{
     session: Session;
-    agent: acp.ClientContext;
+    agent: AcpSdk.ClientContext;
     sessionId: string;
     open(): boolean;
 }>;

package/build/src/akuma/providers/acp/core.js

@@ -1,10 +1,9 @@
-import * as acp from "@agentclientprotocol/sdk";
 import { Readable, Writable } from "node:stream";
 import { spawnStdioProcess } from "../../../runtime/proc/stdio.js";
 import { abortable } from "../../abort.js";
 import { AKUMA_REQUESTS_ENV, AgentEventChannel, } from "../../provider.js";
 import { EMPTY_ACP_EVENT_STATE, flushAcpEvents, mapAcpUpdate, } from "./events.js";
-function diagnostic(error) {
+function diagnostic(acp, error) {
     if (!(error instanceof Error))
         return String(error);
     if (!(error instanceof acp.RequestError) || error.data === undefined)
@@ -18,7 +17,7 @@ function diagnostic(error) {
     }
     return data.length === 0 ? `${error.message} [${error.code}]` : `${error.message} [${error.code}]: ${data}`;
 }
-function createAcpClient(onUpdate) {
+function createAcpClient(acp, onUpdate) {
     return acp.client({ name: "keiyaku" })
         .onNotification(acp.methods.client.session.update, ({ params }) => onUpdate(params));
 }
@@ -29,7 +28,10 @@ function promptResult(response) {
     }
     return { kind: "failed", diagnostic: `ACP prompt ended ${response.stopReason}` };
 }
-async function establishSession(agent, input) {
+function requestMeta(meta) {
+    return meta === undefined || Object.keys(meta).length === 0 ? {} : { _meta: meta };
+}
+async function establishSession(acp, agent, input, dependencies) {
     const initialized = await agent.request(acp.methods.agent.initialize, {
         protocolVersion: acp.PROTOCOL_VERSION,
         clientInfo: { name: "keiyaku", version: "4" },
@@ -38,15 +40,24 @@ async function establishSession(agent, input) {
         throw new Error("ACP agent does not advertise session/load");
     }
     if (input.session.kind === "fresh") {
-        return (await agent.request(acp.methods.agent.session.new, { cwd: input.cwd, mcpServers: [] })).sessionId;
+        return (await agent.request(acp.methods.agent.session.new, {
+            cwd: input.cwd,
+            mcpServers: [],
+            ...requestMeta(dependencies.freshSessionMeta),
+        })).sessionId;
     }
     const sessionId = input.session.coordinate.sessionId;
     if (sessionId === undefined)
         throw new Error("ACP resume coordinate has no session id");
-    await agent.request(acp.methods.agent.session.load, { cwd: input.cwd, mcpServers: [], sessionId });
+    await agent.request(acp.methods.agent.session.load, {
+        cwd: input.cwd,
+        mcpServers: [],
+        sessionId,
+        ...requestMeta(dependencies.loadSessionMeta),
+    });
     return sessionId;
 }
-function createAcpTurn(connection, interpret) {
+function createAcpTurn(acp, connection, interpret) {
     const events = new AgentEventChannel();
     let state = EMPTY_ACP_EVENT_STATE;
     let terminal = false;
@@ -66,7 +77,7 @@ function createAcpTurn(connection, interpret) {
         terminal = true;
         let completionResult = result;
         const failCleanup = (error) => {
-            completionResult = { kind: "failed", diagnostic: `ACP cleanup failed: ${diagnostic(error)}` };
+            completionResult = { kind: "failed", diagnostic: `ACP cleanup failed: ${diagnostic(acp, error)}` };
         };
         try {
             await cleanup();
@@ -96,11 +107,12 @@ function createAcpTurn(connection, interpret) {
         open: () => !terminal,
     };
 }
-function beginAcpPrompt(agent, child, turn, sessionId, input) {
+function beginAcpPrompt(context, child, turn, sessionId, input) {
+    const { acp, agent } = context;
     void agent.request(acp.methods.agent.session.prompt, {
         sessionId,
         prompt: [{ type: "text", text: input.body }, ...input.launchTells.map(({ text }) => ({ type: "text", text }))],
-    }).then((response) => turn.finish(promptResult(response), () => child.endInputAndDrain()), (error) => turn.finish({ kind: "failed", diagnostic: diagnostic(error) }, () => child.endInputAndDrain()));
+    }).then((response) => turn.finish(promptResult(response), () => child.endInputAndDrain()), (error) => turn.finish({ kind: "failed", diagnostic: diagnostic(acp, error) }, () => child.endInputAndDrain()));
     void child.exited.then((exit) => turn.finish({
         kind: "failed",
         diagnostic: exit.stderr || `ACP process exited${exit.code === null ? "" : ` with code ${exit.code}`}`,
@@ -115,7 +127,7 @@ function beginAcpPrompt(agent, child, turn, sessionId, input) {
                 await agent.notify(acp.methods.agent.session.cancel, { sessionId });
             }
             catch (error) {
-                result = { kind: "failed", diagnostic: diagnostic(error) };
+                result = { kind: "failed", diagnostic: diagnostic(acp, error) };
             }
             if (!turn.open())
                 await child.close(true);
@@ -131,6 +143,7 @@ function beginAcpPrompt(agent, child, turn, sessionId, input) {
     };
 }
 export async function startAcpSession(launch, input, dependencies = {}) {
+    const acp = await import("@agentclientprotocol/sdk");
     const signal = input.signal ?? new AbortController().signal;
     signal.throwIfAborted();
     const child = (dependencies.spawnProcess ?? spawnStdioProcess)({
@@ -144,15 +157,15 @@ export async function startAcpSession(launch, input, dependencies = {}) {
     });
     let sessionId;
     let turn;
-    const connection = createAcpClient((notification) => {
+    const connection = createAcpClient(acp, (notification) => {
         if (notification.sessionId === sessionId)
             turn.update(notification.update);
     }).connect(acp.ndJsonStream(Writable.toWeb(child.input), Readable.toWeb(child.output)));
-    turn = createAcpTurn(connection, dependencies.interpretTool);
+    turn = createAcpTurn(acp, connection, dependencies.interpretTool);
     try {
-        sessionId = await abortable(establishSession(connection.agent, input), signal);
+        sessionId = await abortable(establishSession(acp, connection.agent, input, dependencies), signal);
         turn.events.emit({ type: "session", coordinate: { sessionId } });
-        const session = beginAcpPrompt(connection.agent, child, turn, sessionId, input);
+        const session = beginAcpPrompt({ acp, agent: connection.agent }, child, turn, sessionId, input);
         return { session, agent: connection.agent, sessionId, open: turn.open };
     }
     catch (error) {
@@ -161,7 +174,7 @@ export async function startAcpSession(launch, input, dependencies = {}) {
             await child.close(true);
         }
         catch (cleanup) {
-            throw new Error(`${diagnostic(error)}; ACP cleanup failed: ${diagnostic(cleanup)}`, { cause: error });
+            throw new Error(`${diagnostic(acp, error)}; ACP cleanup failed: ${diagnostic(acp, cleanup)}`, { cause: error });
         }
         turn.events.end();
         throw error;

package/build/src/akuma/providers/acp/index.js

@@ -11,8 +11,14 @@ function optionAdmission(options, config) {
     if (options.effort !== undefined && config.effortArg === undefined) {
         return { kind: "refused", diagnostic: "ACP provider has no effort argument mapping" };
     }
-    if (options.systemPrompt !== undefined && options.systemPrompt.length > 0 && config.systemPromptArg === undefined) {
-        return { kind: "refused", diagnostic: "ACP provider has no systemPrompt argument mapping" };
+    if (options.systemPrompt !== undefined && options.systemPrompt.length > 0) {
+        if (config.systemPromptArg === undefined) {
+            return { kind: "refused", diagnostic: "ACP provider has no systemPrompt argument mapping" };
+        }
+        if (options.systemPromptMode !== undefined
+            && options.systemPromptMode !== (config.systemPromptMode ?? "replace")) {
+            return { kind: "refused", diagnostic: "ACP provider systemPromptMode does not match the configured argument mode" };
+        }
     }
     return {
         kind: "admitted",

package/build/src/akuma/providers/claude/index.d.ts

@@ -19,7 +19,7 @@ export type ClaudeSdk = Readonly<{
         sessionId: string;
     }>>;
 }>;
-export declare function createClaudeProvider(load: () => Promise<ClaudeSdk>, execution?: ClaudeExecution): ProviderAdapter;
+export declare function createClaudeProvider(loadOrExecution?: (() => Promise<ClaudeSdk>) | ClaudeExecution, execution?: ClaudeExecution): ProviderAdapter;
 export declare const claudeProvider: Readonly<{
     admitOptions(options: ProviderOptions): import("../../provider.js").ProviderOptionAdmission;
     fork?(input: Readonly<{

package/build/src/akuma/providers/claude/index.js

@@ -74,7 +74,9 @@ function claudeQueryOptions(input, execution, abortController) {
         ...(input.options.model === undefined ? {} : { model: input.options.model }),
         ...(input.options.effort === undefined ? {} : { effort: input.options.effort }),
         ...(input.options.systemPrompt === undefined || input.options.systemPrompt.length === 0 ? {} : {
-            systemPrompt: { type: "preset", preset: "claude_code", append: input.options.systemPrompt },
+            systemPrompt: input.options.systemPromptMode === "replace"
+                ? input.options.systemPrompt
+                : { type: "preset", preset: "claude_code", append: input.options.systemPrompt },
         }),
         ...(input.session.kind === "fresh" ? {} : { resume: claudeSessionId(input.session.coordinate) }),
     };
@@ -277,12 +279,14 @@ async function driveClaude(load, execution, drive) {
         },
     };
 }
-export function createClaudeProvider(load, execution = {}) {
+export function createClaudeProvider(loadOrExecution = async () => await import("@anthropic-ai/claude-agent-sdk"), execution = {}) {
+    const load = typeof loadOrExecution === "function" ? loadOrExecution : async () => await import("@anthropic-ai/claude-agent-sdk");
+    const selectedExecution = typeof loadOrExecution === "function" ? execution : loadOrExecution;
     return {
         admitOptions: admitClaudeOptions,
-        fork: (input) => forkClaude(load, execution, input),
-        start: (input) => driveClaude(load, execution, input),
-        resume: (input) => driveClaude(load, execution, input),
+        fork: (input) => forkClaude(load, selectedExecution, input),
+        start: (input) => driveClaude(load, selectedExecution, input),
+        resume: (input) => driveClaude(load, selectedExecution, input),
     };
 }
 export const claudeProvider = createClaudeProvider(async () => await import("@anthropic-ai/claude-agent-sdk"));

package/build/src/akuma/providers/codex-app-server/index.js

@@ -66,7 +66,10 @@ async function admitTurn(server, input, state, events, config) {
         ...(config === undefined ? {} : { config }),
         ...(input.options.model === undefined ? {} : { model: input.options.model }),
         ...(input.options.systemPrompt === undefined || input.options.systemPrompt.length === 0
-            ? {} : { developerInstructions: input.options.systemPrompt }),
+            ? {}
+            : input.options.systemPromptMode === "replace"
+                ? { baseInstructions: input.options.systemPrompt }
+                : { developerInstructions: input.options.systemPrompt }),
     };
     if (input.session.kind === "fresh") {
         state.threadId = threadId(await server.request("thread/start", threadParams));

package/build/src/akuma/providers/grok-build/index.js

@@ -71,7 +71,9 @@ function optionAdmission(options) {
     if (options.network !== undefined) {
         return { kind: "refused", diagnostic: "Grok Build does not support the network option" };
     }
-    if (options.systemPrompt !== undefined && options.systemPrompt.length > 0) {
+    if (options.systemPrompt !== undefined
+        && options.systemPrompt.length > 0
+        && options.systemPromptMode === undefined) {
         return { kind: "refused", diagnostic: "Grok Build does not support the systemPrompt option" };
     }
     return {
@@ -85,6 +87,17 @@ function optionAdmission(options) {
         }),
     };
 }
+function grokSessionMeta(options) {
+    if (options.systemPrompt === undefined || options.systemPrompt.length === 0)
+        return {};
+    if (options.systemPromptMode === "append")
+        return { freshSessionMeta: { rules: options.systemPrompt } };
+    if (options.systemPromptMode === "replace") {
+        const meta = { systemPromptOverride: options.systemPrompt };
+        return { freshSessionMeta: meta, loadSessionMeta: meta };
+    }
+    return {};
+}
 function argv(execution, options) {
     if (execution.executable === undefined)
         throw new Error("Grok Build provider execution requires executable");
@@ -129,6 +142,7 @@ export function createGrokBuildProvider(execution, dependencies = {}) {
         return withInterject(await startAcpSession(launch, input, {
             ...dependencies,
             interpretTool: interpretGrokTool,
+            ...grokSessionMeta(input.options),
         }));
     };
     return {

package/build/src/akuma/providers/index.js

@@ -32,7 +32,7 @@ async function adapterFor(execution) {
         const { claudeProvider, createClaudeProvider } = await import("./claude/index.js");
         return execution.executable === undefined && execution.env === undefined
             ? claudeProvider
-            : createClaudeProvider(async () => await import("@anthropic-ai/claude-agent-sdk"), execution);
+            : createClaudeProvider(execution);
     }
     if (execution.kind === "codex-app-server")
         return (await import("./codex-app-server/index.js")).createCodexAppServerProvider(execution);

package/build/src/akuma/providers/opencode-sdk/index.js

@@ -24,6 +24,9 @@ function opencodeSessionId(coordinateValue) {
 function admit(options) {
     if (options.network !== undefined)
         throw new Error("OpenCode does not support explicit network");
+    if (options.systemPromptMode === "replace") {
+        throw new Error("OpenCode V1 does not support replacing the native system prompt");
+    }
     if (options.model !== undefined)
         parseModel(options.model);
 }

package/build/src/akuma/providers/pi/index.js

@@ -32,7 +32,9 @@ async function piCreateOptions(sdk, input) {
     const resourceLoader = input.options.systemPrompt === undefined ? undefined : new sdk.DefaultResourceLoader({
         cwd: input.cwd,
         agentDir: sdk.getAgentDir(),
-        systemPromptOverride: () => input.options.systemPrompt,
+        ...(input.options.systemPromptMode === "append"
+            ? { appendSystemPromptOverride: (base) => [...base, input.options.systemPrompt] }
+            : { systemPromptOverride: () => input.options.systemPrompt }),
     });
     await resourceLoader?.reload();
     const sessionManager = input.session.kind === "fresh"

package/build/src/body/amend.js

@@ -151,15 +151,6 @@ function applyRemove(body, operation, document) {
     body.extensionIndexes.delete(normalizeTitle(operation.target));
 }
 function applyUpdate(body, operation, document) {
-    if (operation.target.startsWith("Criterion ")) {
-        const title = operation.target.slice("Criterion ".length);
-        const index = criterionIndex(body, title);
-        if (index < 0)
-            refusal(`unknown criterion '${title}'`);
-        const criterion = body.criteria[index];
-        body.criteria[index] = { ...criterion, body: prose(document, operation.section, "criterion") };
-        return;
-    }
     const index = extensionIndex(body, operation.target);
     if (index < 0)
         refusal(`unknown extension '${operation.target}'`);

package/build/src/body/region.js

@@ -175,8 +175,8 @@ function patternsOverlap(left, right) {
 }
 export function decodeRegion(document, section) {
     const blocks = directChildren(section, "code_block");
-    if (blocks.length !== 1 || !blocks[0].closed || blocks[0].info.length > 0) {
-        refusal("Region must contain one closed fence without an info string");
+    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 other = section.children.filter((node) => node !== blocks[0] && nonblank(document, node));
     if (other.length > 0)

package/build/src/cli/accepted.js

@@ -57,6 +57,7 @@ export function acceptedDeliver(result, coordinate) {
         ...(value.verificationReuse === undefined ? {} : { verificationReuse: value.verificationReuse }),
         ...(value.verificationSummary === undefined ? {} : { verificationSummary: value.verificationSummary }),
         ...(value.placement === undefined ? {} : { placement: value.placement }),
+        ...(value.continuation === undefined ? {} : { continuation: value.continuation }),
         ...(value.cleanup === undefined ? {} : { cleanup: value.cleanup }),
         ...(value.leak === undefined ? {} : { leak: value.leak }),
     };
@@ -78,6 +79,7 @@ export function acceptedReview(result, coordinate) {
         ...(value.verificationReuse === undefined ? {} : { verificationReuse: value.verificationReuse }),
         ...(value.verificationSummary === undefined ? {} : { verificationSummary: value.verificationSummary }),
         ...(value.placement === undefined ? {} : { placement: value.placement }),
+        ...(value.continuation === undefined ? {} : { continuation: value.continuation }),
         ...(value.workspace === undefined ? {} : { workspace: value.workspace }),
         ...(value.cleanup === undefined ? {} : { cleanup: value.cleanup }),
         ...(value.leak === undefined ? {} : { leak: value.leak }),

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

@@ -5,8 +5,8 @@ export type ContractCommandSpec = Readonly<{
     flags: Readonly<Record<string, ContractFlagKind>>;
     usage: string;
     purpose: string;
+    help?: string;
 }>;
-export declare const AMEND_OPERATIONS_HELP: string;
 export declare const CONTRACT_COMMAND_SPECS: {
     readonly bind: {
         readonly positional: "none";
@@ -35,6 +35,7 @@ export declare const CONTRACT_COMMAND_SPECS: {
         };
         readonly usage: "amend [<contract>|@<contract>] [--after <kei/...> ... | --clear-after] [--gates <name,...>] [--actor <actor>] [-]";
         readonly purpose: "Amend one Contract's document operations or structured terms.";
+        readonly help: string;
     };
     readonly deliver: {
         readonly positional: "optional";
@@ -47,7 +48,8 @@ export declare const CONTRACT_COMMAND_SPECS: {
             readonly json: "boolean";
         };
         readonly usage: "deliver [<contract>|@<contract>] [--message <text>] [--include-dirty] [--materialize-conflict] [--actor <actor>]";
-        readonly purpose: "Deliver one Contract candidate.";
+        readonly purpose: "Deliver one Contract candidate from the appointed worktree.";
+        readonly help: string;
     };
     readonly review: {
         readonly positional: "optional";
@@ -139,7 +141,7 @@ export declare const CONTRACT_COMMAND_SPECS: {
             readonly confirm: "value";
             readonly json: "boolean";
         };
-        readonly usage: "nuke [--confirm <WorldRoot>]";
+        readonly usage: "nuke [--confirm <WorldRoot>] [--json]";
         readonly purpose: "Remove Keiyaku-owned data from one confirmed World.";
     };
     readonly settings: {

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

@@ -1,17 +1,27 @@
-export const AMEND_OPERATIONS_HELP = [
-    "stdin operations (H2 sections only, no H1):",
-    "  ## Replace: Context|Objective|Design|Region|Criteria|Verification|<extension>",
-    "  ## Append: Context|Objective|Design|Criteria|<extension>",
-    "  ## Add: Criteria|<new-extension-title>",
-    "  ## Update: Criterion <existing-title>|<existing-extension-title>",
-    "  ## Remove: Criterion <existing-title>|<existing-extension-title>",
-    "",
-    "full operation grammar: docs/document.md, Amend Operations",
-].join("\n");
 export const CONTRACT_COMMAND_SPECS = {
     bind: { positional: "none", stdin: "required", flags: { actor: "value", task: "value", target: "value", here: "boolean", after: "repeat-value", gates: "raw-value", json: "boolean" }, usage: "bind [--task <task/...>] [--target <ref>] [--here] [--after <kei/...> ...] [--gates <name,...>] [--actor <actor>] -", purpose: "Create one Contract from stdin Markdown." },
-    amend: { positional: "optional", stdin: "optional", flags: { actor: "value", after: "repeat-value", "clear-after": "boolean", gates: "raw-value", json: "boolean" }, usage: "amend [<contract>|@<contract>] [--after <kei/...> ... | --clear-after] [--gates <name,...>] [--actor <actor>] [-]", purpose: "Amend one Contract's document operations or structured terms." },
-    deliver: { positional: "optional", stdin: "none", flags: { actor: "value", message: "value", "include-dirty": "boolean", "materialize-conflict": "boolean", json: "boolean" }, usage: "deliver [<contract>|@<contract>] [--message <text>] [--include-dirty] [--materialize-conflict] [--actor <actor>]", purpose: "Deliver one Contract candidate." },
+    amend: {
+        positional: "optional", stdin: "optional", flags: { actor: "value", after: "repeat-value", "clear-after": "boolean", gates: "raw-value", json: "boolean" }, usage: "amend [<contract>|@<contract>] [--after <kei/...> ... | --clear-after] [--gates <name,...>] [--actor <actor>] [-]", purpose: "Amend one Contract's document operations or structured terms.",
+        help: [
+            "  ## Replace: Context|Objective|Design|Region|Criteria|Verification|<extension>",
+            "  ## Append: Context|Objective|Design|Criteria|<extension>",
+            "  ## Add: Criteria|<new-extension-title>",
+            "  ## Update: <existing-extension-title>",
+            "  ## Remove: Criterion <existing-title>",
+            "  ## Remove: <existing-extension-title>",
+        ].join("\n"),
+    },
+    deliver: {
+        positional: "optional", stdin: "none", flags: { actor: "value", message: "value", "include-dirty": "boolean", "materialize-conflict": "boolean", json: "boolean" }, usage: "deliver [<contract>|@<contract>] [--message <text>] [--include-dirty] [--materialize-conflict] [--actor <actor>]", purpose: "Deliver one Contract candidate from the appointed worktree.",
+        help: [
+            "  --include-dirty         Capture the complete non-ignored worktree tree as the",
+            "                          candidate; stages nothing, commits nothing. Refused",
+            "                          while unmerged paths exist.",
+            "  --materialize-conflict  After a conflict result, project the judged targetHead",
+            "                          into the worktree as an uncommitted merge. Not a",
+            "                          delivery: resolve, stage, deliver again.",
+        ].join("\n"),
+    },
     review: { positional: "optional", stdin: "optional", flags: { actor: "value", satisfied: "boolean", unsatisfied: "boolean", summary: "value", json: "boolean" }, usage: "review [<contract>|@<contract>] (--satisfied | --unsatisfied) (--summary <text> | -) [--actor <actor>]", purpose: "Record one review verdict." },
     arc: { positional: "optional", stdin: "required", flags: { actor: "value", json: "boolean" }, usage: "arc [<contract>|@<contract>] [--actor <actor>] -", purpose: "Record stdin arc Markdown for one Contract." },
     abandon: { positional: "optional", stdin: "none", flags: { actor: "value", note: "value", json: "boolean" }, usage: "abandon [<contract>|@<contract>] [--note <text>] [--actor <actor>]", purpose: "Abandon one Contract with an optional note." },
@@ -20,7 +30,7 @@ export const CONTRACT_COMMAND_SPECS = {
     ls: { positional: "optional", stdin: "none", flags: { json: "boolean" }, usage: "ls task[/]\n       keiyaku ls kei[/]\n       keiyaku ls aku[/]\n       keiyaku ls aku/<akuma>[/]\n       keiyaku ls \"aku/*/*\"", purpose: "List one identity directory." },
     audit: { positional: "optional", stdin: "none", flags: { "include-dirty": "boolean", diff: "boolean", actor: "value", json: "boolean" }, usage: "audit [<contract>|@<contract>] [--include-dirty] [--diff] [--actor <actor>]", purpose: "Ask what candidate preparation, Verification, and target placement would do." },
     reconcile: { positional: "optional", stdin: "none", flags: { "retry-hooks": "boolean", json: "boolean" }, usage: "reconcile [<contract>|@<contract>] [--retry-hooks]", purpose: "Reconcile one Contract or the invocation world." },
-    nuke: { positional: "none", stdin: "none", flags: { confirm: "value", json: "boolean" }, usage: "nuke [--confirm <WorldRoot>]", purpose: "Remove Keiyaku-owned data from one confirmed World." },
+    nuke: { positional: "none", stdin: "none", flags: { confirm: "value", json: "boolean" }, usage: "nuke [--confirm <WorldRoot>] [--json]", purpose: "Remove Keiyaku-owned data from one confirmed World." },
     settings: { positional: "none", stdin: "none", flags: { json: "boolean" }, usage: "settings", purpose: "Read user and project Settings resources." },
     region: { positional: "optional", stdin: "none", flags: { overlap: "boolean", path: "value", json: "boolean" }, usage: "region [<contract>] [--overlap]\n       region --path <repo-relative-path>", purpose: "Read active declared Contract Regions." },
 };

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

@@ -1,7 +1,10 @@
 import { type BlockedTaskList, type TaskBatchResult, type TaskCompositionResult, type TaskDecompositionTree, type TaskDetail, type TaskDoctorReport, type TaskList, type TaskMutationResult, type TaskNamespaceResult, type TaskQueryResult, type TaskUpdateResult } from "../../task/index.js";
 import type { ParsedTaskCommand } from "./task.js";
 import type { WorldRoot } from "../../world.js";
-export type TaskInvocationResult = TaskMutationResult | TaskUpdateResult | TaskBatchResult | TaskCompositionResult | TaskDetail | TaskList | BlockedTaskList | TaskQueryResult | TaskDecompositionTree | TaskDoctorReport | TaskNamespaceResult | TaskWorldObservation;
+export type TaskShowResult = TaskDetail | readonly TaskDetail[] | Extract<TaskMutationResult, {
+    kind: "refused";
+}>;
+export type TaskInvocationResult = TaskMutationResult | TaskUpdateResult | TaskBatchResult | TaskCompositionResult | TaskShowResult | TaskList | BlockedTaskList | TaskQueryResult | TaskDecompositionTree | TaskDoctorReport | TaskNamespaceResult | TaskWorldObservation;
 type TaskWorldRead = TaskList | BlockedTaskList | TaskQueryResult | TaskDoctorReport;
 export type TaskWorldObservation = Readonly<{
     kind: "present";

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

@@ -1,4 +1,4 @@
-import { Tasks, } from "../../task/index.js";
+import { Tasks, observeTaskDetails, } from "../../task/index.js";
 import { injectedBodyRequests, requestBodyTask } from "../../akuma/requests.js";
 import { decodeTaskMutationRequest } from "../../task/mutation.js";
 import { resolveTaskNamespaceContext, writeTaskNamespaceContext } from "../../task/context.js";
@@ -157,8 +157,11 @@ async function invokeRead(tasks, command, current) {
     const id = command.positionals[0];
     switch (command.action) {
         case "show": {
-            const detail = await tasks.task({ id }).read();
-            return detail ?? { kind: "refused", refusal: { kind: "task-missing", taskId: id } };
+            const ids = command.positionals.map((taskId) => tasks.task({ id: taskId }).id);
+            const observed = await observeTaskDetails(tasks.root, ids);
+            if (observed.kind !== "accepted")
+                return observed;
+            return command.output === "json" || observed.value.length > 1 ? observed.value : observed.value[0];
         }
         case "ls": return tasks.list({ selection: command.flags.all === true ? "all" : command.flags.closed === true ? "closed" : "active", ...readScope(command, current), ...(limit(command) === undefined ? {} : { limit: limit(command) }) });
         case "ready": return tasks.ready({ ...readScope(command, current), ...(value(command, "parent") === undefined ? {} : { parent: value(command, "parent") }), ...(limit(command) === undefined ? {} : { limit: limit(command) }) });

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

@@ -13,7 +13,7 @@ const TASK_COMMAND_SPECS = {
 task add [--namespace <ns>] [--actor <actor>] -`,
         purpose: "Create one Task from flags or a canonical stdin document.",
     },
-    show: { arity: [1, 1], flags: COMMON, usage: "task show <TaskId>", purpose: "Read one Task and its relationships." },
+    show: { arity: [1, Number.POSITIVE_INFINITY], flags: COMMON, usage: "task show <TaskId>...", purpose: "Read one or more Tasks and their relationships." },
     ls: { arity: [0, 0], flags: { ...COMMON, closed: "boolean", all: "boolean", world: "boolean", limit: "value" }, usage: "task ls [--closed | --all] [--world] [--limit <n>]", purpose: "List Tasks in the selected scope." },
     ready: { arity: [0, 0], flags: { ...COMMON, world: "boolean", parent: "value", limit: "value" }, usage: "task ready [--world] [--parent <TaskId>] [--limit <n>]", purpose: "List open Tasks whose every need is terminal." },
     blocked: { arity: [0, 0], flags: { ...COMMON, world: "boolean", parent: "value", limit: "value" }, usage: "task blocked [--world] [--parent <TaskId>] [--limit <n>]", purpose: "List Tasks blocked by dependencies." },
@@ -46,7 +46,15 @@ export function isTaskAction(value) {
 export function renderTaskHelp(action) {
     if (action !== undefined) {
         const spec = TASK_COMMAND_SPECS[action];
-        return `${spec.purpose}\n\n${usageLine(spec.usage)}`;
+        const queryGuide = action === "query" ? [
+            "",
+            "fields: state priority title id parent under needs blocks ready blocked created updated",
+            "operators: = != < > <= >= ~ and or not ( )",
+            "examples:",
+            "  keiyaku task query --where 'priority <= 1 and ready' --world",
+            "  keiyaku task query --where 'updated < 2026-08-06T00:00:00.000Z' --world",
+        ].join("\n") : "";
+        return `${spec.purpose}\n\n${usageLine(spec.usage)}${queryGuide}`;
     }
     return [
         "usage: keiyaku task <command> ...",

package/build/src/cli/parse.js

@@ -1,7 +1,7 @@
 import { isTaskAction, parseTaskCommand, renderTaskHelp, renderTaskUsage, } from "./commands/task.js";
 import { isAkumaAction, parseAkumaCatalogPath, parseAkumaCommand, renderAkumaHelp, renderAkumaRootRows, renderAkumaUsage, } from "./commands/akuma.js";
 import { INSTALL_USAGE, parseInstallCommand, renderInstallHelp } from "./commands/install.js";
-import { AMEND_OPERATIONS_HELP, CONTRACT_COMMAND_SPECS, } from "./commands/contract.js";
+import { CONTRACT_COMMAND_SPECS, } from "./commands/contract.js";
 import { CliUsageError, isBlankInput, usageLine } from "./usage.js";
 export { CliUsageError } from "./usage.js";
 const ROOT_USAGE = "usage: keiyaku [-C <path>] [--repo <path>] <command> [<contract>|@<contract>] [--flag ...] [-]";
@@ -25,7 +25,7 @@ export function renderRootHelp() {
 export function renderContractHelp(command) {
     const spec = CONTRACT_COMMAND_SPECS[command];
     const help = `${spec.purpose}\n\n${usageLine(spec.usage)}`;
-    return command === "amend" ? `${help}\n\n${AMEND_OPERATIONS_HELP}` : help;
+    return spec.help === undefined ? help : `${help}\n\n${spec.help}`;
 }
 function contractUsage(command) {
     return usageLine(CONTRACT_COMMAND_SPECS[command].usage);