@astrosheep/keiyaku 4.5.7 → 4.5.8

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

@@ -6,16 +6,8 @@ description: Use when authoring, binding, auditing, delivering, reviewing, amend
 # Keiyaku Workflow
 
 A Contract turns one bounded delivery into acceptable terms: bind it, work in
-the appointed worktree, audit the Contract, deliver, then review. When every
-declared gate is current, the result lands on the target ref.
-
-## How The Delivery Moves
-
-```text
-contract document -> bind -> work -> audit -> deliver -> review gates
-                                                    -> placement -> claimed
-                                                                \-> abandoned
-```
+the appointed worktree, audit the Contract, deliver, then satisfy its review
+gates. Placement claims it when every prerequisite and gate is current.
 
 The lifecycle is `waiting -> bound -> tendered -> claimed | abandoned`;
 the last two are terminal. Reserve `--after` for true logical ordering: one
@@ -31,11 +23,27 @@ immutable. You never push it through states by hand: `deliver` and satisfied
 reviews request placement, and placement claims when every prerequisite and
 gate allows it.
 
+## The Lightest Workflow That Fits
+
+Nothing here is required ceremony. Small work is done directly. Larger but
+mechanical work can be bound and delivered without review. Tasks and Arcs
+appear when the work calls for them. There are no cadences, no thresholds, and
+nothing the tool core enforces about how you drive the loop — pick the lightest
+shape that keeps acceptance honest.
+
 ## Bind
 
 Use `keiyaku-bind` to decide readiness, author one bounded Contract, choose
 bind inputs, and read the receipt. Continue here from that receipt.
 
+Managed worktree hooks are transient named command arrays. Each command has a
+nonblank `name`, `argv`, and `timeoutMs`; create and destroy arrays execute
+serially in the current caller. There is no durable marker, frozen command
+snapshot, detached runner, or per-command retry index. `--retry-hooks` reruns
+the complete current phase, so hook authors own idempotence. A successful bind
+receipt prints create hook names in order under `hooks create` and never prints
+their argv or timeout.
+
 ## Work In The Contract Worktree
 
 Change and test code in the worktree the bind receipt names. `deliver` accepts
@@ -43,6 +51,32 @@ a clean worktree by default. You may commit first, or explicitly include all
 non-ignored staged, unstaged, and untracked final bytes with
 `deliver --include-dirty`.
 
+### Managed Worktree Hooks
+
+Configure repository hooks in `<repo>/.keiyaku/settings.json` under the
+`worktree` namespace. User defaults live in `~/.keiyaku/settings.json` and may
+provide the same entries:
+
+```json
+{
+  "worktree": {
+    "create": [{ "argv": ["npm", "ci"], "timeoutMs": 300000 }],
+    "destroy": [{ "argv": ["./scripts/teardown.sh"], "timeoutMs": 60000 }]
+  }
+}
+```
+
+`create` runs when the managed worktree is created; `destroy` runs during
+terminal cleanup. `bind` does not print successful hook argv. A failed hook is
+reported as `worktree-hook-failed`; retry it explicitly:
+
+```bash
+keiyaku reconcile <contract> --retry-hooks
+```
+
+The selected commands freeze per worktree and may replay after runner failure,
+so keep them replay-safe.
+
 ## Regain The Picture
 
 Rebuild state from reads, not memory — after a compact, a handoff, or any
@@ -67,6 +101,32 @@ or an `--after` edge; read `--path` before touching a file that may belong to
 another lane. Regions are declarations only, a coarse planning signal: actual
 touched paths and conflicts remain Git's.
 
+## Hold the Fulfillment Loop
+
+Every Contract in flight has exactly one holder of its fulfillment loop:
+whoever currently turns intent into commissions and returns into decisions. By
+default that is the flagship caller. Holding the loop means four things.
+
+Decompose before delegating — delegation spends a decision already made; it is
+not where the decision happens. Give every requirement in a commission or tell
+a source — user intent, journaled terms, or standing authority; a hypothesis
+formed mid-loop goes down as a question to investigate, or is settled first —
+a real decision, a journaled amend — before it may be required. Treat returns
+as input to judgment, never as the next instruction — see Review Gates. Keep
+the work converging on the Objective — when successive rounds move the candidate
+away from what the Contract set out to make true, judge the premise instead of
+commissioning another round.
+
+The whole loop can be handed to one Aku in a single commission. Keep the
+Contract association but give that delegate the repository cwd explicitly;
+automatic Contract-worktree cwd resolution is for Deliverer and Reviewer seat
+commissions. The duties travel with it; the delegate decides for itself when
+to cut Arcs and Tasks and when to call, tell, and review. It needs no title,
+seat, or identity beyond the commission itself. After handing over, the
+flagship steers only through the holder — a tell to the holder, a journaled
+amend, escalation, or withdrawing the commission — and never reaches past it
+to its subordinates.
+
 ## Commission A Contract
 
 When another agent will fulfill or review the Contract, the commissioning
@@ -95,11 +155,18 @@ frontmatter names `Contract`, then reads the listed owner documents and source
 files before acting. Do not substitute a generic repository tour for the files
 that actually govern the assignment.
 
+The commission owns the question: what to work on or examine, how deep, which
+risks to watch, what evidence to produce. It genuinely directs the round — a
+Deliverer's brief commands the work; a Reviewer's commission frames the
+examination. What it can never do is manufacture acceptance: a requirement
+meant to outlive the round goes through bind or amend, and an expectation stated
+in a prompt is never evidence for a finding.
+
 Contract association, available forwarded actions, and the brief are
-independent inputs. When a Reviewer should record its own verdict, include
-`--allowed contract.review` and say in the brief to record `--satisfied` on
-pass or `--unsatisfied` on failure. When a Deliverer should tender its completed
-candidate, include `--allowed contract.deliver` and say so in the brief.
+independent inputs. Give a Reviewer `--allowed contract.review` only when it
+must record its own verdict, and require it to choose `--satisfied` or
+`--unsatisfied` from its independent judgment. Give a Deliverer `--allowed
+contract.deliver` when it must tender its candidate.
 
 A `Deliverer` implements and verifies the terms in `Worktree`. Commission a
 `Reviewer` after delivery. The reviewer inspects the complete current Contract
@@ -107,8 +174,7 @@ worktree snapshot, not a worker report or named candidate commit, and does not
 modify it. Missing or contradictory seat, worktree, or reading list means stop
 and ask.
 
-Observe commissioned workers through their Contract association instead of
-collecting Aku ids by hand:
+Observe commissioned workers through their Contract association:
 
 ```bash
 keiyaku wait kei/<contract> --all --timeout 5m
@@ -131,7 +197,11 @@ intended work is unsafe to run concurrently.
 When a complex Keiyaku cannot be split without breaking one acceptance
 boundary, organize its fulfillment into arcs. Do not hand the whole
 undifferentiated Contract to one Deliverer and trust one pass to finish it.
-Record and work one current chapter at a time.
+Handing over a whole Contract is legitimate in exactly one form: as a transfer
+of its fulfillment loop, not as one oversized Deliverer assignment. Commission
+one Aku to hold the loop and let it decide when to cut Arcs and Tasks and when
+to call, tell, and review. A Deliverer owes a candidate; a loop holder owes
+decisions.
 
 An arc is a chapter as in a work of literature: one named part of the
 delivery's story, not a task list, progress slice, or claim that the work is
@@ -158,17 +228,17 @@ boundary. The document grammar authority is `docs/document.md`.
 
 ## Amend Or Start Over
 
-Use `amend` when a discovery during the same delivery changes terms but the
-original Objective, Design, and acceptance boundary still truthfully describe
-the result:
+Terms change through the journal or not at all. When delivery or review reveals
+the standing terms are wrong — ambiguous, contradictory, or aimed at the wrong
+outcome — the holder amends, staling old evidence, or abandons and rebinds.
+Remediation that works around a wrong term is the expensive way to keep a
+mistake.
 
 ```bash
 keiyaku amend <contract> -
 ```
 
-See `amend --help` for the operation grammar. If the objective or boundary
-itself changed, `abandon` with a note and bind a new Contract; do not steer an
-old Contract onto a different delivery.
+See `amend --help` for the operation grammar.
 
 ## Audit Before Delivery
 
@@ -178,14 +248,10 @@ Audit is an evidence window for a prospective delivery:
 keiyaku audit <contract> --diff
 ```
 
-It aggregates facts from the same candidate preparation used by `deliver`:
-the prospective candidate and integration identities, the requested diff, the
-declared Verification commands and their observed results, and the target
-placement observation. A terminal run may record subject-bound `verified`
-testimony for those observed commands; it does not deliver, request placement,
-satisfy a review gate, or decide whether the candidate should land. The
-coordinator judges the returned facts; a worker's completion report is not a
-substitute for them.
+Audit is prospective evidence for candidate preparation, Verification, and
+target placement. A terminal run may record subject-bound `verified` testimony,
+but audit never delivers, requests placement, or satisfies a gate; judge its
+facts rather than a worker's completion report.
 
 ## Deliver
 
@@ -200,50 +266,47 @@ Deliver when the worktree content is the candidate you intend to land:
 keiyaku deliver <contract> --include-dirty
 ```
 
-This example includes all non-ignored staged, unstaged, and untracked bytes in
-the candidate. Use `--include-dirty` only when the complete current workspace
-is the intended delivery; otherwise commit the intended bytes and run
-`keiyaku deliver <contract>`.
-
-`deliver` freshly tenders the candidate, records it, and requests placement.
-When a current audit attestation names the identical integration
-snapshot and Verification segment, deliver reuses it; otherwise it runs the
-declarations. Worktree, target, policy, document, Verification, or
-snapshot-producing option changes prevent reuse. If the workspace is dirty, the refusal
-lists staged, unstaged, and untracked paths, a short statistic, and the
-`--include-dirty` option. Use that option only when the complete current
-workspace is the intended delivery; dirty submodule internals cannot be
-included. Read the receipt:
-
-- When every gate is current, the receipt shows placement and `claimed`; the
-  delivery is done.
-- When a gate is not current, the receipt shows the recorded candidate and the
-  placement stop. This is not a failed delivery. The Contract stays
-  `tendered` while you complete the gates.
-- A lag row reports an accepted physical effect that has not finished. The
-  delivery stands; `reconcile` completes the effect later. It never changes
-  the verdict.
+Use `--include-dirty` only when the complete current workspace is the intended
+candidate; otherwise commit the intended bytes first. Read the receipt for the
+candidate, gate/placement stop, and any physical-effect lag. A not-complete
+delivery is still a recorded `tendered` candidate.
+
+`deliver` freshly tenders the candidate and requests placement. A current audit
+attestation is reused only when its integration snapshot and Verification
+segment still match; changes to the worktree, target, policy, document,
+Verification, or snapshot-producing options make it stale.
 
 ## Review Gates
 
-A `reviewed` gate wants a recorded judgment of the current patch:
+The Reviewer owns the answer. A gate review compares the full current candidate
+against every journaled Criterion — the floor that cannot be reduced — and
+testifies satisfied or unsatisfied over the current document identity and
+worktree; satisfied requests placement. A current defect, missing, failed, or
+stale required evidence, or terms too ambiguous or contradictory to judge all
+yield unsatisfied, with the summary naming what blocks. Advice beyond the terms
+belongs in the summary and never changes the verdict by itself.
 
 ```bash
 keiyaku review <contract> --satisfied --summary "<conclusion>"
 keiyaku review <contract> --unsatisfied --summary "<finding>"
 ```
 
-Have an independent reviewer inspect the delivered Contract worktree snapshot.
-If it should record the verdict itself, dispatch it with `--allowed
-contract.review` and state both verdicts in the brief. Otherwise its answer is
-review input for the coordinator to record.
-The `review` command records the verdict. `--satisfied` requests placement; if
-the other gates are current, the receipt shows `claimed`.
-
-Fixing findings changes the patch and makes earlier evidence stale (`?` in
-`status`). Audit the rework, deliver it, then review again. Record
-`--unsatisfied` only when the negative judgment should remain in Contract
-history.
+One Contract, one continuing Reviewer by default: reuse the same identity
+across rounds, replace it with a recorded reason when its judgment frame is
+contaminated, and never carry a Reviewer across Contracts — a new Contract
+always gets a new call. If it should record the verdict itself, dispatch it
+with `--allowed contract.review` and require it to choose the verdict from its
+independent judgment. Otherwise its answer is review input for the coordinator
+to record. The `review` command records the verdict and `--satisfied` requests
+placement.
+
+A review return is input to the loop holder's judgment, never a work order in
+itself. Classify before anything moves: a current defect against the terms is
+fixed and re-reviewed; advice worth keeping but not owed becomes a Task or is
+consciously declined; a problem with the terms goes up — journaled amend or
+escalation — before any remediation is commissioned; work outside the Contract
+stays outside it. Remediation that drifts the candidate away from the Objective
+is evidence against the premise, not a reason for another round.
 
 ## When Multiple Contracts Overlap On One Target
 
@@ -251,16 +314,17 @@ When active Contracts write a shared surface, landing order is a coordinator
 judgment, not Contract state. Keep the decision in the workflow skill; do not
 persist a train or add a second placement authority.
 
-- `audit` and a reviewer's report are preliminary. `review --satisfied` is
-  authoritative gate testimony: it requests placement and claims when
-  delivery, prerequisites, and all gates are current. Record it only when the
-  reviewed bytes are intended to land now.
+- `audit` and a reviewer's report are preliminary; the satisfied review is the
+  gate-visible judgment for placement.
 - Before recording a satisfied review, or delivering a Contract with no
   declared gates, ask whether the exact patch will survive until placement. A
   pure rebase whose `ChangeId` is unchanged keeps the existing review current;
   do not re-review content addressing kept alive. Conflict resolution that
   changes the `ChangeId` makes earlier testimony stale and requires a fresh
-  review against the resolved candidate.
+  review: re-inspect the resolved candidate and record new testimony. Fresh
+  review follows the reviewer-reuse rule above; prefer the existing independent
+  reviewer when its judgment frame remains sound, especially so earlier findings
+  can be checked within the complete fresh judgment.
 - For Contracts known to overlap, resolve the current-target integration before
   the authoritative review. Preliminary feedback may happen earlier, but it
   is not a satisfied gate until its reviewed patch is the candidate intended
@@ -273,19 +337,15 @@ persist a train or add a second placement authority.
 
 ## Target Placement
 
-Placement follows the Git mental model you already have:
+Managed target checkouts follow Git merge semantics: unrelated staged,
+unstaged, and untracked paths are preserved. Staged changes refuse only when
+Git cannot carry the predecessor-to-candidate merge; overlapping worktree
+changes and colliding untracked files also refuse.
 
-- Delivering from a managed worktree to a checked-out target behaves like a
-  merge. Non-overlapping staged, unstaged, and untracked files in that checkout
-  are preserved. A staged path refuses only when Git cannot carry it through
-  the predecessor-to-candidate merge; overlapping worktree changes and
-  colliding untracked files also refuse. The receipt lists the exact paths.
-  The deliver or review you just ran still counts: the recorded candidate and
-  any `✓ reviewed` verdict are kept, but nothing claims and nothing moves.
-  The target ref, its checkout, and your bytes stay exactly where they were,
-  and the Contract stays `tendered`.
-After a refusal, handle the listed paths, then `deliver` again or record a
-satisfied review; either command requests placement again.
+Placement refusal is nonpublishing: the receipt names the reason and paths,
+while the target, checkout bytes, candidate, and current review evidence remain
+unchanged. Handle the listed paths, then run `deliver` again or record a
+satisfied review to request placement again.
 
 ## Recover Or End
 
@@ -295,12 +355,11 @@ keiyaku abandon <contract> --note "<why>"     # terminal; target untouched
 ```
 
 `reconcile` completes physical effects of already accepted placements; it does
-not retry an ordinary placement refusal. `abandon` ends the Contract and never
-touches the target.
+not retry an ordinary placement refusal. Use `--retry-hooks` only for a frozen
+failed hook phase. A lagging effect does not change the accepted verdict.
+`abandon` ends the Contract and never touches the target.
 
 ## Routine Output
 
-Use default text output for normal operation and `--json` only when a script
-needs the public result. Use the complete `kei/...` ID, or `@...` inside a
-managed worktree. When a flag or stdin form is unclear, read that command's
-`--help` instead of guessing.
+Use the complete `kei/...` ID, or `@...` inside a managed worktree. Read a
+command's `--help` when its flags or stdin form are unclear.

package/build/src/akuma/abort.d.ts

@@ -1,2 +1,3 @@
-export declare function abortable<T>(operation: Promise<T>, signal: AbortSignal, disposeLate?: (value: T) => Promise<void> | void): Promise<T>;
+/** Race an awaited operation against cancellation without retaining resource state. */
+export declare function abortable<T>(operation: Promise<T>, signal: AbortSignal): Promise<T>;
 export declare function abortableDelay(milliseconds: number, signal?: AbortSignal): Promise<void>;

package/build/src/akuma/abort.js

@@ -1,32 +1,15 @@
-export function abortable(operation, signal, disposeLate) {
+/** Race an awaited operation against cancellation without retaining resource state. */
+export function abortable(operation, signal) {
     signal.throwIfAborted();
     return new Promise((resolve, reject) => {
-        let aborted = false;
-        let settled = false;
-        const abort = () => {
-            aborted = true;
-            if (!settled) {
-                settled = true;
-                reject(signal.reason);
-            }
-        };
+        const abort = () => reject(signal.reason);
         signal.addEventListener("abort", abort, { once: true });
-        if (signal.aborted)
-            abort();
-        void operation.then(async (value) => {
+        operation.then((value) => {
             signal.removeEventListener("abort", abort);
-            if (!aborted) {
-                settled = true;
-                resolve(value);
-                return;
-            }
-            void Promise.resolve(disposeLate?.(value)).catch(() => undefined);
+            resolve(value);
         }, (error) => {
             signal.removeEventListener("abort", abort);
-            if (settled)
-                return;
-            settled = true;
-            reject(aborted ? signal.reason : error);
+            reject(error);
         });
     });
 }

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

@@ -110,7 +110,7 @@ export class AkumaHandle {
                 throw new TypeError(`Akuma history ${name} must be a positive safe integer`);
             }
         }
-        const limit = input.limit ?? 50;
+        const limit = input.limit ?? 12;
         if (!Number.isSafeInteger(limit) || limit <= 0 || limit > 5_000) {
             throw new TypeError("Akuma history limit must be a positive safe integer no greater than 5000");
         }
@@ -213,7 +213,9 @@ export class AkumaHandle {
             throw new Error(`Akuma fork point ${input.at} has a mismatched provider`);
         let childSession;
         try {
-            childSession = (await adapter.fork({ session: point.session, at: point.historyId, cwd: point.cwd })).session;
+            const attempt = adapter.fork({ session: point.session, at: point.historyId, cwd: point.cwd });
+            childSession = (await attempt.result).session;
+            await attempt.closed;
         }
         catch (error) {
             return { kind: "fork-failed", diagnostic: diagnostic(error) };

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

@@ -10,10 +10,12 @@ export type BudgetedStatusObservation = Readonly<{
 export declare function bornStatus(paths: AkumaPaths, expected: AkuId, input: Readonly<{
     aperture: "monitoring" | "receipt";
     ordinaryBudget?: number;
+    admittedTellId?: string;
 }>): Promise<BudgetedStatusObservation>;
 export declare function readBudgetedStatus(worldPath: WorldRoot, id: AkuId, input: Readonly<{
     aperture: "monitoring" | "receipt";
     ordinaryBudget?: number;
+    admittedTellId?: string;
 }>): Promise<BudgetedStatusObservation>;
 export declare function readAkumaBirthCwd(worldPath: WorldRoot, id: AkuId): Promise<string>;
 export { selectHistory, type ActivityHistory, type ActivitySnapshot };

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

@@ -50,6 +50,7 @@ export async function bornStatus(paths, expected, input) {
     const selected = selectSnapshot(projectTurns(slice.rows), {
         aperture: input.aperture,
         budget: ordinarySnapshotBudget(input.ordinaryBudget),
+        ...(input.admittedTellId === undefined ? {} : { admittedTellId: input.admittedTellId }),
     });
     return {
         status: {

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

@@ -8,7 +8,8 @@ import { akuIdFromDirectoryName, akumaPaths, akumaRunRoot, archetypeName, parseA
 import { loadArchetype, listArchetypes as readArchetypes } from "./archetype.js";
 import { birthAkuma, launchAkuma } from "./publication.js";
 import { spawnAkumaBody } from "./body.js";
-import { injectedBodyRequests, requestBodyCall } from "./requests.js";
+import { requestForwardedAkumaCall } from "./call-request.js";
+import { executionChannel } from "./requests.js";
 import { decodeAllowedActions, unionAllowedActions } from "./allowed.js";
 import { settings as readSettings } from "../settings.js";
 function callReadonly(value) {
@@ -60,7 +61,7 @@ export class Akuma {
         const allowed = input.allowed === undefined
             ? archetype.allowed
             : unionAllowedActions(archetype.allowed, decodeAllowedActions(input.allowed, "Akuma call allowed"));
-        const requests = injectedBodyRequests();
+        const execution = executionChannel(this.configuration.execution);
         const requestRecipe = Object.freeze({
             ...(archetype.description === undefined ? {} : { description: archetype.description }),
             provider: archetype.provider,
@@ -68,14 +69,14 @@ export class Akuma {
             ...(archetype.readonly === undefined ? {} : { readonly: archetype.readonly }),
             allowed,
         });
-        if (requests !== null) {
+        if (execution.kind === "body-request") {
             const cwd = input.cwd === undefined
                 ? undefined
                 : context?.cwdCanonical === true
                     ? input.cwd
                     : await canonicalBirthCwd(input.cwd);
-            const child = await requestBodyCall({
-                directory: requests,
+            const child = await requestForwardedAkumaCall({
+                directory: execution.directory,
                 id: randomUUID(),
                 world: this.path,
                 archetype: name,
@@ -140,6 +141,7 @@ export class Akuma {
         if (unknown !== undefined)
             throw new TypeError(`Akuma list input has unknown field: ${unknown}`);
         const selected = input.archetype === undefined ? undefined : archetypeName(input.archetype);
+        const observedAt = new Date().toISOString();
         const runRoot = akumaRunRoot(this.path);
         let names;
         try {
@@ -150,7 +152,7 @@ export class Akuma {
         }
         catch (error) {
             if (error.code === "ENOENT")
-                return { rows: [], searched: [runRoot] };
+                return { observedAt, rows: [], searched: [runRoot] };
             throw error;
         }
         const rows = [];
@@ -170,7 +172,7 @@ export class Akuma {
             }
             catch { }
         }
-        return { rows, searched: [runRoot] };
+        return { observedAt, rows, searched: [runRoot] };
     }
 }
 export async function callAkumaWithContext(akuma, input, context) {