@astrosheep/keiyaku 4.5.17 → 4.5.19

package/build/integrations/marketplace/plugins/keiyaku/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "keiyaku",
-  "version": "0.1.2+codex.20260826070830",
+  "version": "0.1.2+codex.20260905023250",
   "description": "Use the Keiyaku contract, task, and Akuma CLI.",
   "author": {
     "name": "Keiyaku"

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

@@ -1,6 +1,9 @@
 ---
 name: keiyaku
-description: Use the Keiyaku v4 CLI for contract delivery, task coordination, and Akuma work.
+description: >-
+  Keiyaku is a CLI that records plans, writes handoff terms for deliveries,
+  and calls delegates. Use this skill when you need to figure out which
+  Keiyaku skill or command to reach for.
 ---
 
 # Keiyaku
@@ -33,7 +36,7 @@ keiyaku -C <repo> review [<contract>|@<contract>] --satisfied
 ```
 
 ```bash
-keiyaku -C <cwd> call <akuma-name> [--contract <kei/...>] [--alias @name] [--readonly] [--allowed <product.action>]... [--schema <file>] [--wait <duration> | -d | --detach] [--json] (<prompt> | -)
+keiyaku -C <cwd> call <akuma-name> [--contract <kei/...>] [--alias @name] [--allowed <product.action>]... [--schema <file>] [--wait <duration> | -d | --detach] [--json] (<prompt> | -)
 keiyaku -C <repo> wait <akuma-selector>... [--any | --all]
 keiyaku -C <repo> tell <aku/...|@alias> (<prompt> | -)
 ```

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

@@ -1,6 +1,8 @@
 ---
 name: keiyaku-akuma
-description: Use when delegating work to, supervising, steering, inspecting, forking, or stopping a Keiyaku v4 Akuma.
+description: >-
+  Calling an Akuma: delegating scouting, mechanical chores, or fanned-out
+  parallel work instead of doing it inline.
 ---
 
 # Keiyaku Akuma
@@ -13,7 +15,7 @@ is accepted; the identity underneath never changes.
 ## Start One
 
 ```bash
-keiyaku -C <cwd> call <akuma-name> [--alias @name] [--readonly] [--allowed <product.action>]... [--schema <file>] [--wait <duration> | -d | --detach] [--json] (<prompt> | -)
+keiyaku -C <cwd> call <akuma-name> [--alias @name] [--allowed <product.action>]... [--schema <file>] [--wait <duration> | -d | --detach] [--json] (<prompt> | -)
 ```
 
 Give the worker's initial prompt as one argument (quote it when it contains

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

@@ -1,6 +1,8 @@
 ---
 name: keiyaku-babysit
-description: Babysit a long-running multi-lane goal — a room of lanes that advance on their own, call for you on their schedule, and hold each other up while you are busy being productive.
+description: >-
+  Entering babysit mode: supervising parallel work across multiple Akuma and
+  Contracts as they advance, instead of doing the work yourself.
 ---
 
 # Keiyaku Babysit

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

@@ -1,6 +1,8 @@
 ---
 name: keiyaku-bind
-description: Author and bind one Keiyaku delivery Contract. Use when deciding whether a bounded delivery is ready for Contract terms, writing those terms for an implementer, binding an existing Task with `bind --task`, choosing bind inputs, or interpreting the bind receipt and worktree handoff.
+description: >-
+  Binding a Keiyaku: writing down what a bounded piece of work must deliver and
+  how it will be judged, so it can be handed off.
 ---
 
 # Keiyaku Bind

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

@@ -1,8 +1,9 @@
 ---
 name: keiyaku-task
 description: >-
-  Use when recording, decomposing, or tracking a complex task, typically
-  involving three or more steps.
+  Organizing, tracking progress and status, or binding work of three or more
+  steps as a Keiyaku Task: what to do, in what order, what depends on what,
+  what is done and what is blocked.
 ---
 
 # Keiyaku Task

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

@@ -1,6 +1,9 @@
 ---
 name: keiyaku-workflow
-description: Hold a Contract's fulfillment loop — the loop-holder's five decisions across the whole active loop, from a waiting or bound Contract to claimed or abandoned. Hold or delegate; shape the work into Contracts, Arcs, and Tasks; commission Deliverer and Reviewer seats; adjudicate deliver, review, and audit returns, amend or abandon; schedule landing. For the flagship or the single delegate holding a whole loop.
+description: >-
+  The Keiyaku workflow: how work moves through Keiyaku from planning through
+  binding, commissioning, delivery, review, and landing, and what you decide
+  at each stage.
 ---
 
 # Holding a fulfillment loop
@@ -111,6 +114,15 @@ immutable commit without moving the branch or the real index — a
 prior git commit is optional shaping, never a prerequisite. Deliver
 never satisfies a review gate.
 
+Conflict materialization projects an uncommitted merge; it does not resolve
+its contents or record a delivery. After editing the final worktree bytes,
+`deliver --include-dirty` can capture them even while the real index still
+reports `UU`. No `git add` or commit is required, and capture preserves the
+real index. The candidate includes the complete non-ignored worktree, not
+just the Contract's Region or the conflict paths. Candidate capture and target
+placement are separate: this authorization does not permit overwriting
+blocking changes in the target checkout.
+
 Audit observes: prospective candidate, integration, Verification,
 diff, target. It records no candidate and satisfies no gate.
 

package/build/src/akuma/akuma-handle.d.ts

@@ -1,10 +1,15 @@
-import { type TellResult } from "./body.js";
-import { type KillEvidence } from "./heart/index.js";
-import { type AkuId } from "./identity.js";
+import { type TellResult, type TellWakeRuntime } from "./body.js";
+import { HeldAkumaLeash, type KillEvidence } from "./heart/index.js";
+import { type AkuId, type AkumaPaths } from "./identity.js";
 import { type ActivityHistory, type ExactHistory } from "./projection.js";
 import type { AkumaCallExecution, AkumaStatus, ForkReceipt, InterruptReceipt } from "./akuma.js";
 import type { WorldRoot } from "../world.js";
 declare const CALL_EXECUTION: unique symbol;
+export declare function settleAkumaKill(paths: AkumaPaths, signal?: AbortSignal, retainLeash?: boolean): Promise<Readonly<{
+    evidence: KillEvidence;
+    leash?: HeldAkumaLeash;
+}>>;
+export declare function killAkumaWithRecovery(paths: AkumaPaths, recover?: (paths: AkumaPaths) => Promise<void>, signal?: AbortSignal): Promise<KillEvidence>;
 export declare class AkumaHandle {
     readonly id: AkuId;
     private readonly worldPath;
@@ -23,13 +28,19 @@ export declare class AkumaHandle {
     wait(predicate?: (status: AkumaStatus) => boolean, options?: Readonly<{
         timeoutMs?: number;
     }>): Promise<AkumaStatus>;
-    tell(body: string): Promise<TellResult>;
-    interrupt(body: string): Promise<InterruptReceipt>;
-    interruptSchema(body: string, schemaJson: string): Promise<TellResult>;
+    tell(body: string, tellId?: string, recordedAt?: string, runtime?: TellWakeRuntime, schemaJson?: string): Promise<TellResult>;
+    interrupt(body: string, options?: Readonly<{
+        tellId?: string;
+        schemaJson?: string;
+        signal?: AbortSignal;
+        runtime?: TellWakeRuntime;
+    }>): Promise<InterruptReceipt>;
     fork(input: Readonly<{
         at: string;
     }>): Promise<ForkReceipt>;
-    kill(): Promise<KillEvidence>;
+    kill(options?: Readonly<{
+        signal?: AbortSignal;
+    }>): Promise<KillEvidence>;
     lastAnswer(): Promise<LastAnswer>;
 }
 /** Package-internal provenance retained only by the handle returned from call. */

package/build/src/akuma/akuma-handle.js

@@ -1,73 +1,81 @@
 import { randomUUID } from "node:crypto";
-import { CONTROL_RESPONSE_MS, wakeRecordedTell } from "./body.js";
+import { handoffPendingTells, wakeRecordedTell } from "./body.js";
 import { HeldAkumaLeash, activitySlice, readForkPoint, readHeart, readKill, readLastAnsweredTurn, readSoul, recordTell, requestPause, requestStop, } from "./heart/index.js";
+import { acquireLeash } from "./control.js";
 import { parsePublicHistoryId, pathsForAkuId } from "./identity.js";
 import { projectTurns, selectHistory, selectExactHistory, } from "./projection.js";
 import { resolveProviderExecution } from "./providers/index.js";
 import { publishAkuma } from "./publication.js";
 import { spawnAkumaBody } from "./body.js";
 import { AkumaNotBornError } from "./akuma-errors.js";
-import { bornStatus } from "./akuma-observe.js";
+import { bornStatus, defaultWaitComplete, readWaitComplete } from "./akuma-observe.js";
 const CALL_EXECUTION = Symbol("akuma-call-execution");
 const POLL_MS = 100;
 const wait = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
 function diagnostic(error) {
     return error instanceof Error ? error.message : String(error);
 }
-function defaultWaitComplete(status) {
-    return (status.life !== "running" &&
-        !status.timeline.entries.some((entry) => entry.kind === "row" && entry.row.kind === "tell" && entry.row.state === "pending"));
+async function takeLeashUntilSignal(paths, bodySequence, signal, unbounded = false) {
+    const leash = await acquireLeash(paths, {
+        bodySequence,
+        ...(signal === undefined && unbounded ? { deadline: Number.POSITIVE_INFINITY } : {}),
+        ...(signal === undefined ? {} : { signal }),
+    });
+    if (leash !== null)
+        return leash;
+    const latestBody = (await readHeart(paths)).latestBody;
+    if (latestBody?.sequence === bodySequence && latestBody.hung !== undefined)
+        return { kind: "unavailable", evidence: "hung" };
+    if (latestBody?.sequence === bodySequence && latestBody.end !== undefined)
+        return { kind: "unavailable", evidence: "untidy" };
+    return { kind: "unavailable", evidence: "unavailable" };
 }
-async function takeLeashUntil(paths, deadline) {
-    for (;;) {
-        const leash = await HeldAkumaLeash.try(paths);
-        if (leash !== null)
-            return leash;
-        if (performance.now() >= deadline)
-            return null;
-        await wait(Math.min(POLL_MS, Math.max(0, deadline - performance.now())));
+export async function settleAkumaKill(paths, signal, retainLeash = false) {
+    const request = await requestStop(paths, new Date().toISOString(), signal);
+    if (request.kind !== "requested") {
+        if (!retainLeash)
+            return { evidence: request.kind };
+        const leash = await acquireLeash(paths, signal === undefined ? {} : { signal });
+        return leash === null ? { evidence: "unavailable" } : { evidence: request.kind, leash };
     }
-}
-async function recordTellBody(paths, akuma, body, id = randomUUID(), recordedAt = new Date().toISOString()) {
-    const admitted = await recordTell(paths, { kind: "tell", id, body, recordedAt });
-    if (admitted.kind === "not-born")
-        throw new AkumaNotBornError(akuma);
-    return { kind: "recorded", tellId: admitted.tell.id };
-}
-async function killAkumaWithRecovery(paths, recover = async () => { }) {
+    const target = request.body;
+    const waited = await takeLeashUntilSignal(paths, target.sequence, signal);
+    if ("kind" in waited) {
+        if ((await readKill(paths, target.sequence)) !== null)
+            return { evidence: "killed" };
+        return { evidence: waited.evidence };
+    }
+    const leash = waited;
+    let retain = false;
     try {
-        const request = await requestStop(paths, new Date().toISOString());
-        if (request.kind !== "requested")
-            return request.kind;
-        const target = request.body;
-        const leash = await takeLeashUntil(paths, performance.now() + CONTROL_RESPONSE_MS);
-        if ((await readKill(paths, target.sequence)) !== null) {
-            leash?.release();
-            return "killed";
+        if ((await readKill(paths, target.sequence)) !== null)
+            return { evidence: "killed" };
+        const settledBody = (await readHeart(paths)).latestBody;
+        if (settledBody?.sequence !== target.sequence) {
+            return { evidence: (await readKill(paths, target.sequence)) === null ? "unavailable" : "killed" };
         }
-        if (leash === null) {
-            if ((await readKill(paths, target.sequence)) !== null)
-                return "killed";
-            const body = (await readHeart(paths)).latestBody;
-            return body?.sequence === target.sequence && body.hung !== undefined ? "hung" : "unavailable";
-        }
-        try {
-            const settledBody = (await readHeart(paths)).latestBody;
-            if (settledBody?.sequence !== target.sequence)
-                return (await readKill(paths, target.sequence)) === null ? "unavailable" : "killed";
-            if (settledBody.end !== "put-down") {
-                await leash.clearStop(paths);
-                return "untidy";
-            }
-            const settled = await leash.settleStop(paths, target.sequence);
-            return settled === null ? "unavailable" : "killed";
+        if (settledBody.end !== "put-down") {
+            await leash.clearStop(paths);
+            return { evidence: "untidy" };
         }
-        finally {
+        const settled = await leash.settleStop(paths, target.sequence);
+        if (settled === null)
+            return { evidence: "unavailable" };
+        retain = retainLeash;
+        return retainLeash ? { evidence: "killed", leash } : { evidence: "killed" };
+    }
+    finally {
+        if (!retain)
             leash.release();
-        }
+    }
+}
+export async function killAkumaWithRecovery(paths, recover, signal) {
+    try {
+        return (await settleAkumaKill(paths, signal)).evidence;
     }
     finally {
-        void recover(paths).catch(() => undefined);
+        if (recover !== undefined)
+            void recover(paths).catch(() => undefined);
     }
 }
 export class AkumaHandle {
@@ -129,108 +137,77 @@ export class AkumaHandle {
         }
         const deadline = options.timeoutMs === undefined ? undefined : performance.now() + options.timeoutMs;
         for (;;) {
-            const status = await this.status();
-            if (predicate(status) || (deadline !== undefined && performance.now() >= deadline))
-                return status;
+            if (predicate !== defaultWaitComplete ||
+                (deadline !== undefined && performance.now() >= deadline) ||
+                (await readWaitComplete(this.worldPath, this.id))) {
+                const status = await this.status();
+                if (predicate(status) || (deadline !== undefined && performance.now() >= deadline))
+                    return status;
+            }
             await wait(deadline === undefined ? POLL_MS : Math.min(POLL_MS, Math.max(0, deadline - performance.now())));
         }
     }
-    async tell(body) {
-        const recorded = await recordTellBody(this.paths, this.id, body);
-        return await wakeRecordedTell(this.paths, recorded.tellId);
+    async tell(body, tellId = randomUUID(), recordedAt = new Date().toISOString(), runtime, schemaJson) {
+        const admitted = await recordTell(this.paths, {
+            kind: "tell",
+            id: tellId,
+            body,
+            recordedAt,
+            ...(schemaJson === undefined ? {} : { schemaJson }),
+        });
+        if (admitted.kind === "not-born")
+            throw new AkumaNotBornError(this.id);
+        return await wakeRecordedTell(this.paths, admitted.tell.id, runtime);
     }
-    async interrupt(body) {
-        const request = await requestPause(this.paths, new Date().toISOString());
+    async interrupt(body, options = {}) {
+        const request = await requestPause(this.paths, new Date().toISOString(), options.signal);
         if (request.kind === "not-born") {
             throw new AkumaNotBornError(this.id);
         }
         let putDown = "was-idle";
         let leash = await HeldAkumaLeash.try(this.paths);
         if (leash === null) {
-            leash = await takeLeashUntil(this.paths, performance.now() + CONTROL_RESPONSE_MS);
+            const waited = await takeLeashUntilSignal(this.paths, request.body.sequence, options.signal, true);
+            if ("kind" in waited)
+                return waited;
+            leash = waited;
             putDown = "self-aborted";
         }
-        if (leash === null) {
-            const body = (await readHeart(this.paths)).latestBody;
-            return {
-                kind: "unavailable",
-                evidence: body?.sequence === request.body.sequence && body.hung !== undefined ? "hung" : "unavailable",
-            };
-        }
-        const settledBody = (await readHeart(this.paths)).latestBody;
-        if (settledBody?.sequence === request.body.sequence && settledBody.hung !== undefined) {
-            try {
-                await leash.clearPause(this.paths);
-            }
-            finally {
-                leash.release();
-            }
-            return { kind: "unavailable", evidence: "hung" };
-        }
-        if (settledBody?.sequence !== request.body.sequence || settledBody.end === undefined) {
-            try {
-                await leash.clearPause(this.paths);
-            }
-            finally {
-                leash.release();
-            }
-            return { kind: "unavailable", evidence: "untidy" };
-        }
-        if (request.body.end !== undefined || settledBody.end !== "put-down")
-            putDown = "was-idle";
         let recorded;
         try {
-            const id = randomUUID();
-            const admitted = await leash.recordInterruptTell(this.paths, {
-                kind: "tell",
-                id,
-                body,
-                recordedAt: new Date().toISOString(),
-            });
-            if (admitted.kind === "not-born")
-                throw new AkumaNotBornError(this.id);
-            recorded = { kind: "recorded", tellId: admitted.tell.id };
-        }
-        finally {
-            leash.release();
-        }
-        return { kind: "interrupted", putDown, tell: await wakeRecordedTell(this.paths, recorded.tellId) };
-    }
-    async interruptSchema(body, schemaJson) {
-        const request = await requestPause(this.paths, new Date().toISOString());
-        if (request.kind === "not-born")
-            throw new AkumaNotBornError(this.id);
-        let tellId;
-        let leash = await HeldAkumaLeash.try(this.paths);
-        if (leash === null)
-            leash = await takeLeashUntil(this.paths, performance.now() + CONTROL_RESPONSE_MS);
-        if (leash === null)
-            throw new Error("schema interrupt could not acquire Body leash");
-        try {
+            options.signal?.throwIfAborted();
             const settledBody = (await readHeart(this.paths)).latestBody;
             if (settledBody?.sequence === request.body.sequence && settledBody.hung !== undefined) {
                 await leash.clearPause(this.paths);
-                throw new Error("schema interrupt found a hung Body");
+                return { kind: "unavailable", evidence: "hung" };
             }
             if (settledBody?.sequence !== request.body.sequence || settledBody.end === undefined) {
                 await leash.clearPause(this.paths);
-                throw new Error("schema interrupt could not prove Body settlement");
+                return { kind: "unavailable", evidence: "untidy" };
             }
+            if (request.body.end !== undefined || settledBody.end !== "put-down")
+                putDown = "was-idle";
+            options.signal?.throwIfAborted();
+            const id = randomUUID();
             const admitted = await leash.recordInterruptTell(this.paths, {
                 kind: "tell",
-                id: randomUUID(),
+                id: options.tellId ?? id,
                 body,
                 recordedAt: new Date().toISOString(),
-                schemaJson,
+                ...(options.schemaJson === undefined ? {} : { schemaJson: options.schemaJson }),
             });
             if (admitted.kind === "not-born")
                 throw new AkumaNotBornError(this.id);
-            tellId = admitted.tell.id;
+            recorded = { kind: "recorded", tellId: admitted.tell.id };
         }
         finally {
             leash.release();
         }
-        return await wakeRecordedTell(this.paths, tellId);
+        return {
+            kind: "interrupted",
+            putDown,
+            tell: await wakeRecordedTell(this.paths, recorded.tellId, options.runtime),
+        };
     }
     async fork(input) {
         const source = await readSoul(this.paths);
@@ -296,8 +273,8 @@ export class AkumaHandle {
             };
         }
     }
-    async kill() {
-        return await killAkumaWithRecovery(this.paths);
+    async kill(options = {}) {
+        return await killAkumaWithRecovery(this.paths, handoffPendingTells, options.signal);
     }
     async lastAnswer() {
         const turn = await readLastAnsweredTurn(this.paths);

package/build/src/akuma/akuma-instance.d.ts

@@ -1,9 +1,22 @@
 import type { AllowedAction } from "./allowed.js";
+import type { AkumaStatus } from "./akuma.js";
+import type { InterruptReceipt, KillEvidence } from "./akuma.js";
 import { type AkuId } from "./identity.js";
 import { type ActivityHistory } from "./projection.js";
 import type { Settings } from "../settings.js";
 import type { WorldRoot } from "../world.js";
-import type { Schema } from "./schema.js";
+import { type Schema } from "./schema.js";
+export type AkumaIdleOptions = Readonly<{
+    timeoutMs?: number;
+}>;
+export type AkumaHistoryOptions = Readonly<{
+    before?: number;
+    since?: number;
+    limit?: number;
+}>;
+export type AkumaSignalOptions = Readonly<{
+    signal?: AbortSignal;
+}>;
 export type AkumaBirthInput = Readonly<{
     root: WorldRoot;
     cwd?: string;
@@ -25,7 +38,9 @@ export declare class Akuma {
     static select(root: WorldRoot, selector: string): Akuma;
     tell(text: string): Promise<string>;
     tell<T>(text: string, options: AkumaTellOptions<T>): Promise<T>;
-    idle(): Promise<void>;
-    history(): Promise<ActivityHistory>;
-    kill(): Promise<void>;
+    status(): Promise<AkumaStatus>;
+    interrupt(text: string, options?: AkumaSignalOptions): Promise<InterruptReceipt>;
+    idle(options?: AkumaIdleOptions): Promise<void>;
+    history(options?: AkumaHistoryOptions): Promise<ActivityHistory>;
+    kill(options?: AkumaSignalOptions): Promise<KillEvidence>;
 }