@astrosheep/keiyaku 4.6.1 → 4.6.3

package/README.md

@@ -52,7 +52,7 @@ The CLI parses a predicate; the evaluator never sees a raw shell string.
 Query reads only Task facts. No Contract. No Akuma.
 
 ## Verification
-```bash
+```bash timeout=2m
 npm test
 ```
 ```
@@ -60,60 +60,60 @@ npm test
 ## What a deal looks like
 
 ```bash
-keiyaku bind - < keiyaku.md     # terms written; an isolated worktree appears
-keiyaku call worker -           # a worker goes in
-keiyaku deliver                 # tendered; Verification runs; gates judge
-keiyaku review --satisfied      # attested; main moves with a commit receipt
+keiyaku bind - < contract.md                        # terms written; an isolated worktree appears
+keiyaku call worker -                               # a worker goes in
+keiyaku deliver <contract>                          # delivered; Verification runs; gates judge
+keiyaku review <contract> --satisfied --summary -   # attested; main moves with a commit receipt
 ```
 
 ## What the journal records
 
-One real deal, pulled from this repo's own journal:
+One real deal, read back with `keiyaku history`:
 
 ```text
-$ keiyaku audit kei/add-acp-provider-and-grok-build-profile
-
-accepted audit kei/add-acp-provider-and-grok-build-profile head=0508f7eb9cb738bcab06060b13ff1a96d36e3754
-report {"reworks":1,"reviews":2,"timeline":[
-  {"kind":"bind","at":"2026-08-14T08:18:36.224Z"},
-  {"kind":"deliver","at":"2026-08-14T13:02:08.339Z"},
-  {"kind":"attestation","gate":"reviewed","verdict":"unsatisfied","summary":
-   "Implementation review found no blocking code issues; authenticated official
-    Grok smoke remains unavailable because this host has no grok binary."},
-  {"kind":"attestation","gate":"verified","verdict":"satisfied","summary":"[1 bash exit 0] …"}]}
+history  kei/ship-typed-task-query-b186 · accepted · 9 entries
+
+2026-10-04
+
+16:53 bound to targetless @ 3c5d8c0 · gate review
+16:53 delivered 210eeed · ✓ verification · 10 lines
+16:53 × review · 6 lines
+16:53 delivered aebef87 · ✓ verification · 10 lines
+16:53 ✓ review · 6 lines
+16:53 accepted
 ```
 
-The review said no — with a reason, in bytes, on the journal. The deal
-did not land until the gates had current evidence.
+The review said no, and the deal did not land. The verdict and its reason
+stay on the journal as bytes — `keiyaku history --json` reads them:
+
+```json
+{
+  "kind": "attestation",
+  "contract": "kei/ship-typed-task-query-b186",
+  "data": {
+    "gate": "reviewed",
+    "verdict": "unsatisfied",
+    "summary": "Query evaluator still reaches for Contract facts; reads are not Task-owned."
+  }
+}
+```
 
 ## The board
 
-`keiyaku status` is the one screen. A slice of this repository, right now:
+`keiyaku status` is the one screen. Two Contracts and two Tasks in flight:
 
 ```text
-kanshi ─ 7 keiyaku · 18 akuma · 286 task ─ /Users/astrosheep/Developer/keiyaku-v4 main 9cfdca6017633e51827b9b2eba3c76a7fe08e05f
-
-keiyaku 7
-! kei/add-acp-provider-and-grok-build-profile tendered
-  worktree · integration c5cafef6 · -> refs/heads/main
-  × reviewed
-⧗ kei/align-task-cli-truth-promises waiting
-  ! reviewed
-  held by task/align-task-cli-truth-promises-for-ready-compose
-
-akuma 18
-● aku/expert-akuma/a7aafc9e running
-  alias @process-custody-lead
-  keiyaku kei/make-process-custody-capability-honest (active)
-○ aku/design-akuma/cc53ef08 asleep
-  alias @timeline-design
-! aku/grok/95d90b7d stranded
-  alias @acp-provider-impl
-
-task 8 · 5 ready · 2 held
-● task/align-task-cli-truth-promises-for-ready-compose in_progress
-  Align Task CLI truth promises for ready compose and world absence
-  P0 · keiyaku kei/align-task-cli-truth-promises (active)
+CONTRACTS // recent
+
+⧗ kei/ship-typed-task-query-c898 · 1s · Ship typed Task query
+  [✓] delivery  [ ] review
+⧗ kei/tighten-receipt-vocabulary-4a70 · 18s · Tighten receipt vocabulary
+  [ ] delivery  [ ] review
+
+TASKS // recent
+
+○ task/regenerate-readme-from-real-010b · ready · P1 · Regenerate README from real output
+○ task/align-task-cli-truth-promises-3af5 · ready · P0 · Align Task CLI truth promises
 ```
 
 Marks accelerate scanning; the words carry the state.
@@ -122,9 +122,8 @@ Marks accelerate scanning; the words carry the state.
 
 ```markdown
 ---
-provider: claude-agent-sdk
-model: claude-sonnet-4-5
-access: write
+provider: pi
+model: kimi-coding/k3-256k
 description: Repository implementation agent
 ---
 Make scoped changes and run relevant tests.
@@ -132,6 +131,55 @@ Make scoped changes and run relevant tests.
 
 One Markdown file, one worker. `keiyaku call worker` summons it.
 
+## Configuration
+
+Settings are JSON at two addresses: `~/.keiyaku/settings.json` for the user,
+`.keiyaku/settings.json` in the project. A project record
+wholly shadows the same-name user record. There is no write command; edit the
+files directly and inspect the merged, provenance-annotated view with
+`keiyaku settings`.
+
+Named gate groups provide reusable gate sets. Bind and amend select them with
+`--gates`; the `default` group applies when binding with `--gates` omitted.
+Amending without `--gates` keeps the existing gates:
+
+```json
+{
+  "gates": {
+    "default": { "kind": "bundle", "gates": ["reviewed"] },
+    "strict": { "kind": "bundle", "gates": ["reviewed", "verified"] }
+  }
+}
+```
+
+Selections accept the built-in names `reviewed` and `verified`, or configured
+group names. Unknown names are rejected with the known names listed. Custom gates
+must be declared inside a configured group; they stay unsatisfied until a producer
+attests them.
+
+Worktree hooks run commands when a Contract's managed worktree is created or
+destroyed — dependency installs are the usual suspect:
+
+```json
+{
+  "worktree": {
+    "create": [
+      { "name": "install", "argv": ["npm", "ci", "--ignore-scripts", "--prefer-offline"], "timeoutMs": 300000 }
+    ],
+    "destroy": [
+      { "name": "teardown", "argv": ["docker", "compose", "down", "-v"], "timeoutMs": 60000 }
+    ]
+  }
+}
+```
+
+Hooks run as one ordered phase inside the worktree and must be replay-safe: a
+retry reruns the phase from its beginning. Create hooks prepare the worktree;
+destroy hooks release external resources the worktree deletion alone cannot.
+A failing hook retains the worktree
+and reports lag; it never abandons the Contract. `keiyaku settings --help`
+lists every recognized namespace.
+
 ## Install
 
 ```bash

package/build/integrations/marketplace/plugins/keiyaku/skills/keiyaku-bind/SKILL.md

@@ -183,9 +183,10 @@ keiyaku -C <repo> bind --gates "" - < CONTRACT.md
 keiyaku -C <repo> bind --gates reviewed - < CONTRACT.md
 ```
 
-Omitting `--gates` uses `gates.default`, or `reviewed` when no default bundle
+Omitting `--gates` uses `gates.default`, or `reviewed` when no default group
 exists. `--gates ""` selects no gates. Gates are named acceptance obligations,
-not work assignments.
+not work assignments. Named gate groups and worktree hooks live in Settings;
+see the README Configuration section or `keiyaku settings --help`.
 
 ## 3. After Binding
 

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

@@ -164,10 +164,11 @@ function translateMessage(event, state) {
         state.assistantSeen = true;
         state.answer = text;
     }
-    // Gemini emits an empty text block alongside every tool-use message. It is
+    // Some providers emit a blank text block alongside every tool-use message:
+    // empty from Gemini, whitespace from openai-responses-style proxies. It is
     // transport scaffolding, not narration; an ordinary terminal empty answer
     // remains public evidence.
-    if (hasTextContent(message.content) && !(message.stopReason === "toolUse" && text.length === 0)) {
+    if (hasTextContent(message.content) && !(message.stopReason === "toolUse" && text.trim().length === 0)) {
         translated.push({ type: "assistant", text });
     }
     return translated;

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

@@ -1,12 +1,11 @@
-import type { createAgentSession, createBashToolDefinition, DefaultResourceLoader, getAgentDir, ModelRuntime, SessionManager, CreateAgentSessionOptions } from "@earendil-works/pi-coding-agent";
+import type { createAgentSessionFromServices, createAgentSessionServices, createBashToolDefinition, getAgentDir, SessionManager } from "@earendil-works/pi-coding-agent";
 import type { ProviderExecution } from "../../provider-recipe.js";
 import { type ProviderAdapter } from "../../provider.js";
 export type PiSdk = Readonly<{
-    createAgentSession(options?: CreateAgentSessionOptions): ReturnType<typeof createAgentSession>;
+    createAgentSessionFromServices: typeof createAgentSessionFromServices;
+    createAgentSessionServices: typeof createAgentSessionServices;
     createBashToolDefinition: typeof createBashToolDefinition;
-    DefaultResourceLoader: typeof DefaultResourceLoader;
     getAgentDir: typeof getAgentDir;
-    ModelRuntime: typeof ModelRuntime;
     SessionManager: typeof SessionManager;
 }>;
 export declare function createPiProvider(execution?: ProviderExecution, load?: () => Promise<PiSdk>): ProviderAdapter;

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

@@ -21,26 +21,14 @@ function admitPiOptions(options) {
         options: Object.freeze({ ...options }),
     };
 }
-async function piCreateOptions(sdk, input) {
+function piCreateOptions(sdk, input, services) {
     let model;
-    let modelRuntime;
     if (input.options.model !== undefined) {
         const slash = input.options.model.indexOf("/");
-        modelRuntime = await sdk.ModelRuntime.create();
-        model = modelRuntime.getModel(input.options.model.slice(0, slash), input.options.model.slice(slash + 1));
+        model = services.modelRuntime.getModel(input.options.model.slice(0, slash), input.options.model.slice(slash + 1));
         if (model === undefined)
             throw new Error(`Pi model '${input.options.model}' is unavailable`);
     }
-    const resourceLoader = input.options.systemPrompt === undefined
-        ? undefined
-        : new sdk.DefaultResourceLoader({
-            cwd: input.cwd,
-            agentDir: sdk.getAgentDir(),
-            ...(input.options.systemPromptMode === "append"
-                ? { appendSystemPromptOverride: (base) => [...base, input.options.systemPrompt] }
-                : { systemPromptOverride: () => input.options.systemPrompt }),
-        });
-    await resourceLoader?.reload();
     const sessionManager = input.session.kind === "fresh"
         ? sdk.SessionManager.create(input.cwd)
         : "sessionFile" in input.session.coordinate
@@ -59,22 +47,39 @@ async function piCreateOptions(sdk, input) {
             }),
         ];
     return {
-        cwd: input.cwd,
+        services,
         sessionManager,
-        ...(model === undefined || modelRuntime === undefined ? {} : { model, modelRuntime }),
-        ...(resourceLoader === undefined ? {} : { resourceLoader }),
+        ...(model === undefined ? {} : { model }),
         ...(input.options.effort === undefined ? {} : { thinkingLevel: input.options.effort }),
         ...(customTools === undefined ? {} : { customTools }),
     };
 }
 async function createPiSession(sdk, execution, input) {
-    const setup = piCreateOptions(sdk, input).then(async (options) => {
-        if (execution.config !== undefined) {
-            throw new TypeError("Pi provider config cannot be consumed by native CreateAgentSessionOptions");
-        }
-        return await sdk.createAgentSession(options);
+    if (execution.config !== undefined) {
+        throw new TypeError("Pi provider config cannot be consumed by native CreateAgentSessionOptions");
+    }
+    const services = await sdk.createAgentSessionServices({
+        cwd: input.cwd,
+        agentDir: sdk.getAgentDir(),
+        modelRuntimeSignal: input.signal,
+        ...(input.options.systemPrompt === undefined
+            ? {}
+            : {
+                resourceLoaderOptions: input.options.systemPromptMode === "append"
+                    ? { appendSystemPromptOverride: (base) => [...base, input.options.systemPrompt] }
+                    : { systemPromptOverride: () => input.options.systemPrompt },
+            }),
     });
-    return await setup;
+    try {
+        input.signal?.throwIfAborted();
+        return await sdk.createAgentSessionFromServices(piCreateOptions(sdk, input, services));
+    }
+    catch (error) {
+        // Before a session owns the extension runtime, failed selection/setup must
+        // retire registrations and event-bus subscriptions loaded by the services.
+        services.resourceLoader.getExtensions().runtime.invalidate();
+        throw error;
+    }
 }
 async function runPiPrompt(native, input, events, state, settle) {
     try {
@@ -273,11 +278,10 @@ async function forkPi(sdk, input) {
 async function loadPiSdk() {
     const sdk = await import("@earendil-works/pi-coding-agent");
     return {
-        createAgentSession: sdk.createAgentSession,
+        createAgentSessionFromServices: sdk.createAgentSessionFromServices,
+        createAgentSessionServices: sdk.createAgentSessionServices,
         createBashToolDefinition: sdk.createBashToolDefinition,
-        DefaultResourceLoader: sdk.DefaultResourceLoader,
         getAgentDir: sdk.getAgentDir,
-        ModelRuntime: sdk.ModelRuntime,
         SessionManager: sdk.SessionManager,
     };
 }

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

@@ -1,4 +1,12 @@
 import type { ArcData } from "../core/facts/types.js";
-import type { ContractBody } from "./types.js";
+import type { ContractBody, DecodedContractDocument } from "./types.js";
 export declare function renderContractBody(body: ContractBody, currentArc?: ArcData): string;
+/**
+ * Binding persists the canonical rendering of decoded terms, never the caller's
+ * literal byte stream: layout-only authorship is normalized at admission so it
+ * never reappears as phantom changes in later amendment diffs.
+ */
+export declare function decodeCanonicalContractDocument(source: string, options?: Readonly<{
+    requireTimeout?: boolean;
+}>): DecodedContractDocument;
 export declare function renderAmendedContractBody(currentSource: string, body: ContractBody, changedSections: ReadonlySet<string>): string;

package/build/src/body/render.js

@@ -1,4 +1,5 @@
 import { formatDuration } from "../duration.js";
+import { decodeContractDocument } from "./decode.js";
 import { parseToAST } from "../markdown/parse.js";
 import { indexDocument, indexedHeadings, normalizeTitle, rawSlice } from "../markdown/query.js";
 import { CONTRACT_SECTIONS } from "./shape.js";
@@ -54,6 +55,16 @@ export function renderContractBody(body, currentArc) {
         .join("\n\n")
         .concat("\n");
 }
+/**
+ * Binding persists the canonical rendering of decoded terms, never the caller's
+ * literal byte stream: layout-only authorship is normalized at admission so it
+ * never reappears as phantom changes in later amendment diffs.
+ */
+export function decodeCanonicalContractDocument(source, options = {}) {
+    const decoded = decodeContractDocument(source, options);
+    const rendered = renderContractBody(decoded);
+    return rendered === decoded.document.bytes ? decoded : decodeContractDocument(rendered, options);
+}
 function sections(document) {
     return indexedHeadings(indexDocument(document), { level: 2 }).filter((node) => node.type === "section");
 }

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

@@ -304,8 +304,10 @@ function parseAddressed(action, rawSelectors, flags, output, fail) {
     return { command: action, akuma, at, output };
 }
 function parsePrompted(action, positionals, stdin, fail) {
-    if (positionals.length < 1 || positionals.length > 2)
-        fail(`${action} has invalid positional arguments`);
+    if (positionals.length === 0)
+        fail(action === "call" ? "call requires an Akuma name" : `${action} requires an Akuma selector`);
+    if (positionals.length > 2)
+        fail(`${action} accepts at most ${action === "call" ? "a name" : "a selector"} and one prompt`);
     const argument = positionals[1];
     if (stdin && argument !== undefined)
         fail(`${action} accepts either a prompt argument or stdin, not both`);
@@ -406,7 +408,14 @@ export function parseAkumaCommand(argv) {
                 : parseAsk(flags, parsed.subject, parsed.prompt, output, fail);
     }
     if (spec.arity === "one-or-more" ? positionals.length === 0 : positionals.length !== spec.arity) {
-        fail(`${action} has invalid positional arguments`);
+        if (positionals.length === 0)
+            fail(spec.arity === "one-or-more"
+                ? `${action} requires at least one Akuma selector`
+                : `${action} requires an Akuma selector`);
+        else
+            fail(spec.arity === 1
+                ? `${action} accepts one Akuma selector`
+                : `${action} accepts exactly ${spec.arity} Akuma selectors`);
     }
     if (stdin)
         fail(`${action} reads no stdin`);

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

@@ -9,6 +9,7 @@ import { executionChannel } from "../../akuma/requests.js";
 import { settings } from "../../settings.js";
 import { AkumaWorldScopeError } from "../../index.js";
 import { akumasWithExecution } from "../../library/akumas.js";
+import { World } from "../../world.js";
 import { contractFromInput } from "../selectors.js";
 import { ActivityDriver } from "../activity.js";
 import { displayContext, resultContext, writeJson, writeStderr, writeStdout } from "../streams.js";
@@ -67,6 +68,11 @@ async function inputInitiator(input) {
     catch { }
     if (initiator === undefined)
         return {};
+    // Plugins coordinate within an established World; a `call` may run where the
+    // marker does not exist yet, and activating there would only fail noisily.
+    // The initiator still travels with the request either way.
+    if (!(await World.established(input.path)))
+        return { initiator };
     try {
         await emitInitiatingPluginSignal({
             world: input.path,

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

@@ -22,6 +22,9 @@ function optionalFlag(flags, name) {
 function refuse(command, message) {
     throw new CliUsageError(message, commandGuide(command, CONTRACT_COMMAND_SPECS[command].usage));
 }
+// The CLI restates the literal gate-word grammar its help prints; the corpus
+// pin in cli-parse.test.ts keeps this shape honest against the owner's gateWord.
+const GATE_NAME_PATTERN = /^[a-z][a-z0-9-]{0,63}$/u;
 function parseGateNames(parts, command) {
     const value = optionalFlag(parts.flags, "gates");
     if (value === undefined)
@@ -32,6 +35,10 @@ function parseGateNames(parts, command) {
     if (names.some((name) => name.length === 0)) {
         refuse(command, '--gates requires comma-separated names or "" to clear gates');
     }
+    const invalid = names.find((name) => !GATE_NAME_PATTERN.test(name));
+    if (invalid !== undefined) {
+        refuse(command, `--gates name must match ^[a-z][a-z0-9-]{0,63}$: ${invalid}`);
+    }
     return names;
 }
 function parseBind(parts) {

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

@@ -106,7 +106,7 @@ export declare const CONTRACT_COMMAND_SPECS: {
             readonly json: "boolean";
         };
         readonly usage: "ls task[/] [--limit <count>]\nls kei[/] [--limit <count>]\nls aku[/] [--limit <count>]\nls aku/<name>[/] [--limit <count>]\nls \"aku/<name>/*\" [--limit <count>]\nls \"aku/*/*\" [--limit <count>]";
-        readonly purpose: "List Tasks, Contracts, or Akumas.";
+        readonly purpose: "List tasks (ls task), contracts (ls kei), or akumas (ls aku).";
         readonly details: string;
     };
     readonly audit: {

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

@@ -15,11 +15,15 @@ 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 a Contract from stdin Markdown or copy an existing Contract as a starting point.",
         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}$.",
+            "Gates are acceptance obligations checked at placement: reviewed awaits a",
+            "satisfied review, verified awaits a passing Verification run.",
+            "",
+            "--gates <name,...> selects reviewed, verified, or named gate groups from Settings",
+            "(keiyaku settings). A group expands into its gates; unknown names are rejected",
+            "with the known names listed. Custom gates must be declared in a configured group.",
+            "Duplicates are removed in first-seen order. Names 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.',
+            '--gates "" explicitly binds without gates; --gates reviewed needs no configuration.',
             "",
             "Binding appoints one managed worktree for the Contract and the receipt",
             "reports its path; the holder and delegates work there. When appointment",
@@ -55,9 +59,14 @@ export const CONTRACT_COMMAND_SPECS = {
         usage: "amend [<contract>|@<contract>] [--after <kei/...> ... | --clear-after] [--gates <name,...>] [--actor <actor>] [-]",
         purpose: "Change a Contract's document, prerequisites, or acceptance gates.",
         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}$.",
+            "Gates are acceptance obligations checked at placement: reviewed awaits a",
+            "satisfied review, verified awaits a passing Verification run.",
+            "",
+            "--gates <name,...> replaces gates using reviewed, verified, or named gate groups",
+            "from Settings (keiyaku settings). A group expands into its gates; unknown names",
+            "are rejected with the known names listed. Custom gates must be declared in a",
+            "configured group. Duplicates are removed in first-seen order.",
+            "Names 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)",
@@ -88,6 +97,7 @@ export const CONTRACT_COMMAND_SPECS = {
             "Delivery requests integration. If prerequisites and gates pass, it integrates now and accepts the Contract; otherwise the candidate remains waiting.",
             "Only changed candidate work invalidates earlier review. If Verification did not finish, repeating delivery resumes that candidate; --overwrite replaces it.",
             "Delivery never counts as an independent review verdict.",
+            "Content identity names the change's content hash, never a commit; it survives rebase and Git cannot look it up.",
             "",
             "  --materialize-conflict  Write the observed integration conflict into the worktree as an uncommitted merge.",
             "                          With --include-dirty, current non-ignored changes are preserved first.",
@@ -147,8 +157,9 @@ export const CONTRACT_COMMAND_SPECS = {
         stdin: "none",
         flags: { limit: "value", json: "boolean" },
         usage: 'ls task[/] [--limit <count>]\nls kei[/] [--limit <count>]\nls aku[/] [--limit <count>]\nls aku/<name>[/] [--limit <count>]\nls "aku/<name>/*" [--limit <count>]\nls "aku/*/*" [--limit <count>]',
-        purpose: "List Tasks, Contracts, or Akumas.",
+        purpose: "List tasks (ls task), contracts (ls kei), or akumas (ls aku).",
         details: [
+            "ls kei lists active Contracts; accepted and abandoned ones leave the list, and their record stays in history and Git.",
             "ls aku/ lists the callable Akuma-name catalog; ls aku/<name> lists the living Akumas under one name.",
             'ls "aku/<name>/*" is the same living set in glob form; ls "aku/*/*" lists every living Akuma.',
         ].join("\n"),
@@ -162,6 +173,7 @@ export const CONTRACT_COMMAND_SPECS = {
         details: [
             "--include-dirty checks all non-ignored worktree changes, staged or not.",
             "--show-diff includes the proposed candidate diff when one can be prepared.",
+            "Content identity names the change's content hash, never a commit; it survives rebase and Git cannot look it up.",
             "Progress appears on stderr; stdout contains one final result.",
         ].join("\n"),
     },
@@ -210,7 +222,7 @@ export function renderContractHelp(command) {
             "command; edit the files directly.",
             "",
             "Recognized settings:",
-            "  gates                            gate bundles selected by bind and amend",
+            "  gates                            named gate groups selected by bind and amend",
             "  worktree                         commands run when worktrees are created or destroyed",
             "  git.requireBranchesToBeUpToDate  whether deliver and audit require up-to-date target branches",
             "  providers                        the available Akuma and how each is run",

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

@@ -148,7 +148,9 @@ async function contractLibrary(command, execution, configuration, runtime) {
     return composeContractLibrary(execution, createKeiyakuHandle, {
         ...(configuration === undefined ? {} : { settings: configuration }),
         ...(actor === undefined ? {} : { actor }),
-    });
+    }, 
+    // The CLI owns this default: an omitted Markdown --target names the invocation branch.
+    { kind: "current-branch" });
 }
 async function runBind(command, input, library) {
     const { coordinates, runtime } = input;

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

@@ -204,14 +204,12 @@ export function renderTaskHelp(action) {
         const spec = TASK_COMMAND_SPECS[action];
         return `${spec.purpose}\n\n${renderTaskUsage(action)}${spec.details === undefined ? "" : `\n\n${spec.details}`}`;
     }
+    const nameWidth = Math.max(...Object.keys(TASK_COMMAND_SPECS).map((name) => name.length));
     return [
         "usage  keiyaku task <command> ...",
+        "      keiyaku task <command> --help   shows that command's complete usage",
         "",
-        "commands:",
-        ...Object.values(TASK_COMMAND_SPECS).flatMap((spec) => spec.usage
-            .split("\n")
-            .map((line) => `  ${line}`)
-            .concat(`    ${spec.purpose}`)),
+        ...Object.entries(TASK_COMMAND_SPECS).map(([name, spec]) => `  ${name.padEnd(nameWidth)}  ${spec.purpose}`),
     ].join("\n");
 }
 function renderTaskUsage(action) {
@@ -387,8 +385,12 @@ function validateListSelector(selector, fail) {
 }
 function validateTaskScan(action, scanned, fail) {
     const spec = TASK_COMMAND_SPECS[action], { positionals, flags, stdin } = scanned;
-    if (positionals.length < spec.arity[0] || positionals.length > spec.arity[1])
-        fail(`task ${action} has invalid positional arguments`);
+    if (positionals.length < spec.arity[0])
+        fail(spec.arity[1] === 1 ? `task ${action} requires a TaskId` : `task ${action} requires at least one TaskId`);
+    if (positionals.length > spec.arity[1])
+        fail(spec.arity[1] === 0
+            ? `task ${action} accepts no positional arguments`
+            : `task ${action} accepts at most ${spec.arity[1]} positional argument${spec.arity[1] === 1 ? "" : "s"}`);
     if (action === "add" && (stdin === "document") === (positionals.length === 1))
         fail("task add requires either TITLE or '-' input");
     if (action === "add" &&

package/build/src/cli/parse.js

@@ -294,6 +294,11 @@ export function parseArgv(argv) {
     const help = helpCoordinate(invocation.commandArgv);
     if (help !== null)
         return { help };
+    // A bare invocation asks for orientation: the root help index, not a refusal.
+    if (invocation.commandArgv.length === 0)
+        return { help: { kind: "root" } };
+    if (invocation.commandArgv.length === 1 && invocation.commandArgv[0] === "task")
+        return { help: { kind: "task" } };
     if (invocation.commandArgv.length === 1 && invocation.commandArgv[0] === "--version")
         return { version: true };
     const task = invocation.commandArgv[0] === "task" ? parseTaskCommand(invocation.commandArgv.slice(1)) : undefined;

package/build/src/cli/render/akuma-activity.d.ts

@@ -14,6 +14,10 @@ export declare const DEFAULT_CONTEXT: TextRenderContext;
  */
 export declare function frameRule(headLines: readonly string[]): string;
 type StatusTimeline = AkumaObservation["status"]["timeline"];
+type StatusTimelineEntry = StatusTimeline["entries"][number];
+type RenderRow = ActivityRow | Extract<StatusTimelineEntry, {
+    kind: "row";
+}>["row"];
 type RenderedSnapshot = StatusTimeline;
 type RenderedActivity = Readonly<{
     snapshot: RenderedSnapshot;
@@ -56,15 +60,31 @@ export type ActivityStream = ((activity: RenderedActivity) => readonly string[])
     seed: (activity: RenderedActivity, alreadyRenderedSequence?: number) => readonly string[];
     /** Current live rows for the redrawable frame; never part of append-only output. */
     frame: () => readonly string[];
-    /** Emit the deferred tail exactly once before the command's conclusion. */
+    /** Emit the pending omission count and unsettled rows once before the command's conclusion. */
     flush: () => readonly string[];
+    /** The same decisions undrawn, so concurrent streams can merge before rendering. */
+    emissions: Readonly<{
+        observe: (activity: RenderedActivity) => readonly StreamEmission[];
+        seed: (activity: RenderedActivity, alreadyRenderedSequence?: number) => readonly StreamEmission[];
+        flush: () => readonly StreamEmission[];
+    }>;
+    render: (emissions: readonly StreamEmission[]) => readonly string[];
+}>;
+/** One decided piece of append-only output: a settled row, or an untimed omission count. */
+export type StreamEmission = Readonly<{
+    kind: "gap";
+    count: number;
+}> | Readonly<{
+    kind: "row";
+    row: RenderRow;
+    inFlightSay?: boolean;
+    unsettled?: boolean;
 }>;
 /**
- * Append-only live view over one command's successive settled snapshots. The
- * first three tools stream immediately; later tools wait in a two-row tail.
- * A say omits the earlier tail, so only the last two extra tools after the
- * final say can print at closing. Newer tools displace older tail candidates
- * in place. Other narrative rows wait behind undecided tail tools.
+ * Append-only live view over one command's successive settled snapshots.
+ * After each say or Tell, the first three tools print as they settle; later
+ * tools until the next checkpoint fold into one omission marker. Failed tools
+ * always print.
  */
 export declare function activityStream(context: TextRenderContext, layout?: RowLayout): ActivityStream;
 /** What a wait conclusion renders over: its observed and unobserved members. */