@astrosheep/keiyaku 4.6.6 → 4.6.8

package/build/src/akuma/selection-observation.d.ts

@@ -3,6 +3,30 @@ import { type AkumaStatus } from "./akuma.js";
 declare const akumaObservationSchema: z.ZodObject<{
     status: z.ZodObject<{
         id: z.ZodPipe<z.ZodString, z.ZodTransform<import("./identity.js").AkuId, string>>;
+        birth: z.ZodObject<{
+            origin: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"direct">;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"request">;
+                parent: z.ZodPipe<z.ZodString, z.ZodTransform<import("./identity.js").AkuId, string>>;
+                requestId: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"fork">;
+                parent: z.ZodPipe<z.ZodString, z.ZodTransform<import("./identity.js").AkuId, string>>;
+                at: z.ZodString;
+            }, z.core.$strip>], "kind">;
+            caller: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"akuma">;
+                world: z.ZodCustom<import("../world.js").WorldRoot, import("../world.js").WorldRoot>;
+                akuId: z.ZodPipe<z.ZodString, z.ZodTransform<import("./identity.js").AkuId, string>>;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"external">;
+                integration: z.ZodString;
+                id: z.ZodString;
+            }, z.core.$strict>], "kind">, z.ZodObject<{
+                kind: z.ZodLiteral<"unknown">;
+            }, z.core.$strict>]>;
+        }, z.core.$strict>;
         life: z.ZodEnum<{
             killed: "killed";
             hung: "hung";
@@ -467,6 +491,30 @@ declare const akumaWaitResultSchema: z.ZodObject<{
     observations: z.ZodReadonly<z.ZodArray<z.ZodObject<{
         status: z.ZodObject<{
             id: z.ZodPipe<z.ZodString, z.ZodTransform<import("./identity.js").AkuId, string>>;
+            birth: z.ZodObject<{
+                origin: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    kind: z.ZodLiteral<"direct">;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"request">;
+                    parent: z.ZodPipe<z.ZodString, z.ZodTransform<import("./identity.js").AkuId, string>>;
+                    requestId: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"fork">;
+                    parent: z.ZodPipe<z.ZodString, z.ZodTransform<import("./identity.js").AkuId, string>>;
+                    at: z.ZodString;
+                }, z.core.$strip>], "kind">;
+                caller: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    kind: z.ZodLiteral<"akuma">;
+                    world: z.ZodCustom<import("../world.js").WorldRoot, import("../world.js").WorldRoot>;
+                    akuId: z.ZodPipe<z.ZodString, z.ZodTransform<import("./identity.js").AkuId, string>>;
+                }, z.core.$strict>, z.ZodObject<{
+                    kind: z.ZodLiteral<"external">;
+                    integration: z.ZodString;
+                    id: z.ZodString;
+                }, z.core.$strict>], "kind">, z.ZodObject<{
+                    kind: z.ZodLiteral<"unknown">;
+                }, z.core.$strict>]>;
+            }, z.core.$strict>;
             life: z.ZodEnum<{
                 killed: "killed";
                 hung: "hung";
@@ -1164,8 +1212,6 @@ export type AkumaAskResult<T = unknown> = Omit<z.infer<typeof akumaAskResultSche
 }>;
 /** Compose one native status into the canonical observation its crossing transports. */
 export declare function akumaObservationOf(status: AkumaStatus): AkumaObservation;
-export declare function isTellResult(value: unknown): value is AkumaTellResult;
-export declare function isAskResult(value: unknown): value is AkumaAskResult;
 export declare const selectionResultSchemas: {
     wait: z.ZodObject<{
         mode: z.ZodEnum<{
@@ -1179,6 +1225,30 @@ export declare const selectionResultSchemas: {
         observations: z.ZodReadonly<z.ZodArray<z.ZodObject<{
             status: z.ZodObject<{
                 id: z.ZodPipe<z.ZodString, z.ZodTransform<import("./identity.js").AkuId, string>>;
+                birth: z.ZodObject<{
+                    origin: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                        kind: z.ZodLiteral<"direct">;
+                    }, z.core.$strip>, z.ZodObject<{
+                        kind: z.ZodLiteral<"request">;
+                        parent: z.ZodPipe<z.ZodString, z.ZodTransform<import("./identity.js").AkuId, string>>;
+                        requestId: z.ZodString;
+                    }, z.core.$strip>, z.ZodObject<{
+                        kind: z.ZodLiteral<"fork">;
+                        parent: z.ZodPipe<z.ZodString, z.ZodTransform<import("./identity.js").AkuId, string>>;
+                        at: z.ZodString;
+                    }, z.core.$strip>], "kind">;
+                    caller: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject<{
+                        kind: z.ZodLiteral<"akuma">;
+                        world: z.ZodCustom<import("../world.js").WorldRoot, import("../world.js").WorldRoot>;
+                        akuId: z.ZodPipe<z.ZodString, z.ZodTransform<import("./identity.js").AkuId, string>>;
+                    }, z.core.$strict>, z.ZodObject<{
+                        kind: z.ZodLiteral<"external">;
+                        integration: z.ZodString;
+                        id: z.ZodString;
+                    }, z.core.$strict>], "kind">, z.ZodObject<{
+                        kind: z.ZodLiteral<"unknown">;
+                    }, z.core.$strict>]>;
+                }, z.core.$strict>;
                 life: z.ZodEnum<{
                     killed: "killed";
                     hung: "hung";

package/build/src/akuma/selection-observation.js

@@ -50,12 +50,6 @@ const akumaAskResultSchema = z
 export function akumaObservationOf(status) {
     return { status, contract: NO_DISPATCH_ASSOCIATION, createdTasks: EMPTY_CREATED_TASK_OBSERVATION };
 }
-export function isTellResult(value) {
-    return akumaTellResultSchema.safeParse(value).success;
-}
-export function isAskResult(value) {
-    return akumaAskResultSchema.safeParse(value).success;
-}
 export const selectionResultSchemas = {
     wait: akumaWaitResultSchema,
     tell: akumaTellResultSchema,

package/build/src/akuma/selection-owner-port.d.ts

@@ -9,4 +9,4 @@ import type { SelectionRequestPort } from "./selection-request.js";
  * unaddressable member never starts; the executor's own access to the target is
  * then the product act, never a second addressing probe.
  */
-export declare function selectionRequestPort(world: WorldRoot): SelectionRequestPort;
+export declare function selectionRequestPort(world: WorldRoot, reportDiagnostic: (message: string) => void): SelectionRequestPort;

package/build/src/akuma/selection-owner-port.js

@@ -1,3 +1,4 @@
+import { outcomePluginObserver } from "../plugin/akuma-signals.js";
 import { requireBornAkuma } from "./akuma-probe.js";
 import { executeAskAkuma, executeKillAkuma, executeTellAkuma } from "./akuma-selection-execution.js";
 import { executeWaitAkuma } from "./akuma-wait.js";
@@ -11,26 +12,36 @@ import { akumaObservationOf } from "./selection-observation.js";
  * unaddressable member never starts; the executor's own access to the target is
  * then the product act, never a second addressing probe.
  */
-export function selectionRequestPort(world) {
+export function selectionRequestPort(world, reportDiagnostic) {
     const prove = async (targets) => {
         for (const id of targets)
             await requireBornAkuma(world, id);
     };
     return {
-        wait: async ({ targets, ...request }) => {
+        wait: async ({ targets, observer, ...request }) => {
             await prove(targets);
             // The lower wait owner returns association-free native evidence; the
             // actual request crossing composes its canonical transport shape.
-            const native = await executeWaitAkuma({ path: world, ids: targets, ...request });
+            const native = await executeWaitAkuma({
+                path: world,
+                ids: targets,
+                ...request,
+                outcomeObserved: outcomePluginObserver({ world, reportDiagnostic }, observer),
+            });
             return { ...native, observations: native.observations.map(akumaObservationOf) };
         },
         tell: async ({ target, ...request }) => {
             await prove([target]);
             return await executeTellAkuma({ path: world, id: target, ...request });
         },
-        ask: async ({ target, ...request }) => {
+        ask: async ({ target, observer, ...request }) => {
             await prove([target]);
-            return await executeAskAkuma({ path: world, id: target, ...request });
+            return await executeAskAkuma({
+                path: world,
+                id: target,
+                ...request,
+                outcomeObserved: outcomePluginObserver({ world, reportDiagnostic }, observer),
+            });
         },
         kill: async ({ targets, ...request }) => {
             await prove(targets);

package/build/src/akuma/selection-request.d.ts

@@ -106,6 +106,7 @@ export type SelectionRequestPort = Readonly<{
         targets: readonly AkumaStatus["id"][];
         completion: "any" | "all";
         timeoutMs?: number;
+        observer: string;
         signal: AbortSignal;
     }>): Promise<AkumaWaitResult>;
     tell(input: Readonly<{
@@ -126,6 +127,7 @@ export type SelectionRequestPort = Readonly<{
         schemaJson?: string;
         initiator?: string;
         interrupt?: boolean;
+        observer: string;
         signal: AbortSignal;
     }>): Promise<AkumaAskResult>;
     kill(input: Readonly<{

package/build/src/akuma/selection-request.js

@@ -167,7 +167,7 @@ export function selectionRequestCommand(action, port) {
             if (request.action === "akuma.wait") {
                 return {
                     kind: "served",
-                    result: await port.wait({ ...request, signal: facts.signal }),
+                    result: await port.wait({ ...request, observer: facts.requester, signal: facts.signal }),
                     service: { action: request.action },
                 };
             }
@@ -196,6 +196,7 @@ export function selectionRequestCommand(action, port) {
                         body: request.body,
                         tellId: facts.id,
                         recordedAt: facts.admittedAt,
+                        observer: facts.requester,
                         ...(request.timeoutMs === undefined ? {} : { timeoutMs: request.timeoutMs }),
                         ...(request.schemaJson === undefined ? {} : { schemaJson: request.schemaJson }),
                         ...(request.initiator === undefined ? {} : { initiator: request.initiator }),

package/build/src/akuma/turn-drive.js

@@ -115,7 +115,7 @@ async function startTurnDrive(input) {
         cwd,
         options,
         signal: driveController.signal,
-        requests: { dir: requests.directory },
+        requests: { dir: requests.directory, entry: requests.entry },
         ...(schemaJson === undefined ? {} : { schemaJson }),
     };
     const attempt = session === undefined
@@ -232,9 +232,6 @@ function pumpReceipts(writers) {
 function observeFailure(settlement) {
     return settlement.then(() => new Promise(() => { }), (error) => Promise.reject(error));
 }
-function observeReceiptFailure(receiptPump) {
-    return observeFailure(receiptPump);
-}
 function observeCompletionFailure(drive) {
     return drive.completion.then(() => new Promise(() => { }), (error) => ({ kind: "completion-failed", error }));
 }
@@ -354,7 +351,7 @@ async function consumeTurnDrive(input, active) {
     let writesOpen = true;
     const mayWrite = () => writesOpen && !input.supervisor.signal.aborted;
     const writers = { input, turnSequence, drive, writeWitness, mayWrite };
-    const receiptFailure = observeReceiptFailure(pumpReceipts(writers));
+    const receiptFailure = observeFailure(pumpReceipts(writers));
     const completionFailure = observeCompletionFailure(drive);
     const iterator = drive.events[Symbol.asyncIterator]();
     let liveTells = true;

package/build/src/akuma-body.js

@@ -1,6 +1,6 @@
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { bodyLaunchSchema, LEASH_HELD_EXIT, runAkumaBody } from "./akuma/body.js";
+import { bodyLaunchSchema, LEASH_HELD_EXIT, runAkumaBody, recordPluginDiagnostic, } from "./akuma/body.js";
 import { worldRootForAkumaPaths } from "./akuma/identity.js";
 import { composeRequestCommands } from "./akuma/request-wire.js";
 import { localExecutionContext } from "./akuma/requests.js";
@@ -108,7 +108,9 @@ export async function externalRequestCommandsFor(launch, processConfiguration) {
     const world = await World.prove(worldRootForAkumaPaths(launch.paths));
     return {
         world,
-        commands: composeRequestCommands(selectionRequestCommands(selectionRequestPort(world)), contractRequestCommands(contractUpstream(processConfiguration)), taskMutationRequestCommands(taskMutationRequestPort())),
+        commands: composeRequestCommands(selectionRequestCommands(selectionRequestPort(world, (message) => {
+            void recordPluginDiagnostic(launch.paths, "outcome observation", message);
+        })), contractRequestCommands(contractUpstream(processConfiguration)), taskMutationRequestCommands(taskMutationRequestPort())),
     };
 }
 function bodyProcessConfiguration() {

package/build/src/cli/akuma-caller.d.ts

@@ -0,0 +1,3 @@
+import { type AkumaCaller } from "../akuma/caller.js";
+/** Environment attribution belongs to the process edge, never SDK admission. */
+export declare function akumaCallerFromEnvironment(environment: NodeJS.ProcessEnv): Promise<AkumaCaller | undefined>;

package/build/src/cli/akuma-caller.js

@@ -0,0 +1,21 @@
+import { decodeAkumaCaller } from "../akuma/caller.js";
+import { World } from "../world.js";
+/** Environment attribution belongs to the process edge, never SDK admission. */
+export async function akumaCallerFromEnvironment(environment) {
+    const id = environment.KEIYAKU_ACTOR_ID;
+    const world = environment.KEIYAKU_ACTOR_WORLD;
+    if ((id === undefined) !== (world === undefined)) {
+        throw new TypeError("Akuma caller requires both KEIYAKU_ACTOR_ID and KEIYAKU_ACTOR_WORLD");
+    }
+    if (id !== undefined && world !== undefined) {
+        const resolved = await World.resolve({ cwd: world, repositoryRoot: world });
+        return decodeAkumaCaller({ kind: "akuma", akuId: id, world: resolved.candidate });
+    }
+    const external = environment.KEIYAKU_EXTERNAL_CALLER;
+    if (external === undefined)
+        return undefined;
+    const colon = external.indexOf(":");
+    if (colon < 0)
+        throw new TypeError("KEIYAKU_EXTERNAL_CALLER must be <integration>:<id>");
+    return decodeAkumaCaller({ kind: "external", integration: external.slice(0, colon), id: external.slice(colon + 1) });
+}

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

@@ -175,11 +175,6 @@ function positiveIndex(raw, option, fail) {
         fail(`${option} exceeds the safe integer range`);
     return value;
 }
-function validateDirect(value, _fail) {
-    // Address validation belongs to the operation boundary so callers receive
-    // the compact Akuma refusal instead of a generic usage page.
-    return value;
-}
 function validateSet(value, fail) {
     if (value.startsWith("kei/"))
         return value;
@@ -192,7 +187,7 @@ function validateSet(value, fail) {
         }
         return value;
     }
-    return validateDirect(value, fail);
+    return value;
 }
 function parseWait(rawSelectors, flags, output, fail) {
     if (flags.any === true && flags.all === true)
@@ -236,7 +231,7 @@ function parseAkumaHistory(selector, flags, output, fail) {
         fail("history --id requires turn/<positive safe integer>");
     return {
         command: "history",
-        akuma: validateDirect(selector, fail),
+        akuma: selector,
         ...(id === undefined ? {} : { id }),
         last: flags.last === true,
         ...(flags.before === undefined ? {} : { before: positiveIndex(flags.before, "--before", fail) }),
@@ -256,7 +251,7 @@ function parseAddressed(action, rawSelectors, flags, output, fail) {
             fail("history accepts one complete aku/..., @alias, or kei/... selector");
         return parseHistory(selector, flags, output, fail);
     }
-    const akuma = validateDirect(rawSelectors[0], fail);
+    const akuma = rawSelectors[0];
     const at = stringFlag(flags.at, "fork requires --at <historyId>", fail);
     return { command: action, akuma, at, output };
 }
@@ -279,10 +274,10 @@ function parsePrompted(action, positionals, stdin, fail) {
                 : { prompt: { kind: "argument", value: argument } }),
     };
 }
-function parseTell(flags, subject, prompt, output, fail) {
+function parseTell(flags, subject, prompt, output) {
     return {
         command: "tell",
-        akuma: validateDirect(subject, fail),
+        akuma: subject,
         interrupt: flags.interrupt === true,
         prompt,
         output,
@@ -292,7 +287,7 @@ function parseAsk(flags, subject, prompt, output, fail) {
     const schema = flags.schema === undefined ? undefined : stringFlag(flags.schema, "ask --schema requires a file", fail);
     return {
         command: "ask",
-        akuma: validateDirect(subject, fail),
+        akuma: subject,
         interrupt: flags.interrupt === true,
         ...(schema === undefined ? {} : { schema }),
         ...(flags.wait === undefined ? {} : { timeoutMs: parseDuration(flags.wait, "--wait", fail) }),
@@ -361,7 +356,7 @@ export function parseAkumaCommand(argv) {
         return action === "call"
             ? parseCall(flags, parsed.subject, parsed.prompt, output, fail)
             : action === "tell"
-                ? parseTell(flags, parsed.subject, parsed.prompt, output, fail)
+                ? parseTell(flags, parsed.subject, parsed.prompt, output)
                 : parseAsk(flags, parsed.subject, parsed.prompt, output, fail);
     }
     if (spec.arity === "one-or-more" ? positionals.length === 0 : positionals.length !== spec.arity) {

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

@@ -1,8 +1,9 @@
+import { akumaCallerFromEnvironment } from "../akuma-caller.js";
 import { CliUsageError, isBlankInput } from "../usage.js";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { squareAssignedParticipantName } from "@astrosheep/square";
-import { emitInitiatingPluginSignal } from "../../plugin/akuma-signals.js";
+import { emitPluginSignal } from "../../plugin/akuma-signals.js";
 import { canonicalBirthCwd } from "../../akuma/call-input.js";
 import { Schema } from "../../akuma/index.js";
 import { executionChannel } from "../../akuma/requests.js";
@@ -27,7 +28,7 @@ async function settingsAt(root, home) {
     });
 }
 function akumas(input) {
-    return akumasWithExecution(input.path, input.execution);
+    return akumasWithExecution(input.path, input.execution, { reportDiagnostic: writeStderr });
 }
 async function schemaFromFile(path) {
     try {
@@ -68,22 +69,14 @@ 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.
+    // Identity preparation needs established plugin custody, not just a candidate.
     if (!(await World.established(input.path)))
         return { initiator };
-    try {
-        await emitInitiatingPluginSignal({
-            world: input.path,
-            ...(input.settings === undefined ? {} : { settings: input.settings }),
-            initiator,
-            reportDiagnostic: (message) => writeStderr(message),
-        });
-    }
-    catch (error) {
-        writeStderr(`! plugin initiation: ${error instanceof Error ? error.message : String(error)}`);
-    }
+    await emitPluginSignal({
+        world: input.path,
+        ...(input.settings === undefined ? {} : { settings: input.settings }),
+        reportDiagnostic: (message) => writeStderr(message),
+    }, { kind: "akuma.initiating", initiator });
     return { initiator };
 }
 function emitAnswer(body, exact) {
@@ -96,9 +89,15 @@ function emitAnswer(body, exact) {
 async function runCall(command, input) {
     const body = command.prompt === undefined ? undefined : await promptBody("call", { prompt: command.prompt }, input);
     const schema = command.schema === undefined ? undefined : await schemaFromFile(command.schema);
+    const declaredCaller = executionChannel(input.execution).kind === "body-request"
+        ? undefined
+        : await akumaCallerFromEnvironment(input.environment);
+    // Establish the selected World before preparing the submitting Square route.
+    await World.at(input.path);
     const caller = akumas(input);
     const request = {
         ...(await inputInitiator(input)),
+        ...(declaredCaller === undefined ? {} : { caller: declaredCaller }),
         archetype: command.archetype,
         ...(body === undefined ? {} : { body }),
         ...(input.home === undefined ? {} : { home: input.home }),
@@ -293,7 +292,10 @@ async function runHistory(command, input) {
     return historyExitCode(result, command.id);
 }
 async function runFork(command, input) {
+    const caller = await akumaCallerFromEnvironment(input.environment);
     const receipt = await akumas(input).fork({
+        ...(await inputInitiator(input)),
+        ...(caller === undefined ? {} : { caller }),
         akuma: command.akuma,
         at: command.at,
         ...(input.repo === undefined ? {} : { repo: input.repo }),

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

@@ -24,7 +24,8 @@ export type ParsedBind = Output & Actor & Readonly<{
     command: "bind";
     forkOf?: string;
     task?: string;
-    target?: string;
+    /** A literal target branch, or `null` for a deliberately targetless bind. */
+    target?: string | null;
     after?: readonly string[];
     gates?: readonly string[];
 }>;

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

@@ -1,4 +1,4 @@
-import { archetypeName } from "../../akuma/identity.js";
+import { validateAkumaName } from "../../identity/normalize.js";
 import { parseTaskNamespaceSelector } from "../../task/catalog.js";
 import { CliUsageError, commandGuide } from "../usage.js";
 import { CONTRACT_COMMAND_SPECS } from "./contract-help.js";
@@ -9,11 +9,11 @@ function parseAkumaCatalogPath(value) {
         return { kind: "akuma" };
     const scopedGlob = /^aku\/([^/]+)\/\*$/u.exec(value);
     if (scopedGlob !== null)
-        return { kind: "akuma", archetype: archetypeName(scopedGlob[1]) };
+        return { kind: "akuma", archetype: validateAkumaName(scopedGlob[1]) };
     const match = /^aku\/([^/]+)\/?$/u.exec(value);
     if (match === null)
         return null;
-    return { kind: "akuma", archetype: archetypeName(match[1]) };
+    return { kind: "akuma", archetype: validateAkumaName(match[1]) };
 }
 function optionalFlag(flags, name) {
     const value = flags[name];
@@ -41,6 +41,13 @@ function parseGateNames(parts, command) {
     }
     return names;
 }
+function parseBindTarget(parts) {
+    const target = optionalFlag(parts.flags, "target");
+    const noTarget = parts.flags["no-target"] === true;
+    if (target !== undefined && noTarget)
+        refuse("bind", "--target and --no-target are mutually exclusive");
+    return noTarget ? null : target;
+}
 function parseBind(parts) {
     const forkOf = optionalFlag(parts.flags, "fork-of");
     if (forkOf !== undefined) {
@@ -50,7 +57,7 @@ function parseBind(parts) {
             if (parts.flags[option] !== undefined)
                 refuse("bind", `--${option} is not valid with --fork-of`);
         }
-        const target = optionalFlag(parts.flags, "target");
+        const target = parseBindTarget(parts);
         return {
             command: "bind",
             forkOf,
@@ -62,7 +69,7 @@ function parseBind(parts) {
     if (!parts.stdin)
         refuse("bind", "bind requires stdin");
     const task = optionalFlag(parts.flags, "task");
-    const target = optionalFlag(parts.flags, "target");
+    const target = parseBindTarget(parts);
     const after = parts.flags.after === undefined ? [] : Array.isArray(parts.flags.after) ? parts.flags.after : [parts.flags.after];
     const gates = parseGateNames(parts, "bind");
     return {
@@ -196,15 +203,6 @@ function parseRegion(parts) {
         output: parts.output,
     };
 }
-function akumaCatalogQuery(query, parts) {
-    const limit = optionalFlag(parts.flags, "limit");
-    if (limit !== undefined && (!/^[1-9][0-9]*$/u.test(limit) || !Number.isSafeInteger(Number(limit))))
-        refuse("ls", "--limit requires a positive safe integer");
-    return {
-        ...query,
-        ...(limit === undefined ? {} : { limit: Number(limit) }),
-    };
-}
 function listLimit(parts, command = "ls") {
     const limit = optionalFlag(parts.flags, "limit");
     if (limit !== undefined && (!/^[1-9][0-9]*$/u.test(limit) || !Number.isSafeInteger(Number(limit))))
@@ -249,7 +247,7 @@ function parseLs(parts) {
         const query = parseAkumaCatalogPath(path);
         if (query === null)
             refuse("ls", "ls requires a supported identity directory selector");
-        return { command: "ls", query: akumaCatalogQuery(query, parts), output: parts.output };
+        return { command: "ls", query: { ...query, ...(limit === undefined ? {} : { limit }) }, output: parts.output };
     }
     catch (error) {
         if (error instanceof CliUsageError)

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

@@ -15,12 +15,13 @@ export declare const CONTRACT_COMMAND_SPECS: {
             readonly actor: "value";
             readonly task: "value";
             readonly target: "value";
+            readonly "no-target": "boolean";
             readonly after: "repeat";
             readonly gates: "raw-value";
             readonly "fork-of": "value";
             readonly json: "boolean";
         };
-        readonly usage: "bind [--task <task/...>] [--target <ref>] [--after <kei/...> ...] [--gates <name,...>] [--actor <actor>] - | bind --fork-of <kei/...> [--target <ref>] [--actor <actor>]";
+        readonly usage: "bind [--task <task/...>] [--target <ref> | --no-target] [--after <kei/...> ...] [--gates <name,...>] [--actor <actor>] - | bind --fork-of <kei/...> [--target <ref> | --no-target] [--actor <actor>]";
         readonly purpose: "Create a Contract from stdin Markdown or copy an existing Contract as a starting point.";
         readonly details: string;
     };

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

@@ -7,14 +7,21 @@ export const CONTRACT_COMMAND_SPECS = {
             actor: "value",
             task: "value",
             target: "value",
+            "no-target": "boolean",
             after: "repeat",
             gates: "raw-value",
             "fork-of": "value",
             json: "boolean",
         },
-        usage: "bind [--task <task/...>] [--target <ref>] [--after <kei/...> ...] [--gates <name,...>] [--actor <actor>] - | bind --fork-of <kei/...> [--target <ref>] [--actor <actor>]",
+        usage: "bind [--task <task/...>] [--target <ref> | --no-target] [--after <kei/...> ...] [--gates <name,...>] [--actor <actor>] - | bind --fork-of <kei/...> [--target <ref> | --no-target] [--actor <actor>]",
         purpose: "Create a Contract from stdin Markdown or copy an existing Contract as a starting point.",
         details: [
+            "--target names one existing local branch literally; it is never created and never",
+            "guessed. Omitting it binds to the current branch of the invocation worktree",
+            "coordinate, or binds without a target on a detached committed HEAD. --no-target",
+            "binds without a target on purpose, and is refused together with --target.",
+            "A fork copies its source target when neither flag is given.",
+            "",
             "Gates are acceptance obligations checked at placement: reviewed awaits a",
             "satisfied review, verified awaits a passing Verification run.",
             "",
@@ -245,6 +252,29 @@ export function renderContractHelp(command) {
             "effort, network, allowed, systemPromptMode, and description; the body is",
             "an optional system prompt.",
             "",
+            "Local Paseo provider in settings.json:",
+            '  { "providers": { "paseo": {',
+            '    "kind": "paseo",',
+            '    "config": { "url": "ws://127.0.0.1:6767/ws", "provider": "claude" }',
+            "  } } }",
+            "The native provider id is bare (claude, codex, pi), not provider/model.",
+            "Example .keiyaku/akuma/paseo-worker.md frontmatter:",
+            "  ---",
+            "  provider: paseo",
+            "  model: <native-model-id>",
+            "  effort: high",
+            "  ---",
+            "Model and effort must be offered by the selected native provider;",
+            "effort names its native thinking option id.",
+            'PASEO_PASSWORD=<password> keiyaku call paseo-worker "<prompt>"',
+            "Paseo must already be running locally. Resume keeps its live native",
+            "runtime; after Paseo native reload/restart create a fresh Akuma.",
+            "Observed busy agents refuse; native steer still has a check/send race.",
+            "Explicit control cancels native current execution session-wide and may",
+            "affect concurrent human work. Normal completion only retires the client",
+            "and its sockets; it never cancels later work or closes the native runtime.",
+            "Socket closure does not prove native cancellation succeeded.",
+            "",
             usageLine(spec.usage),
         ].join("\n");
     }