@astrosheep/keiyaku 2.8.5 → 2.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/keiyaku",
-  "version": "2.8.5",
+  "version": "2.9.1",
   "description": "CLI for running iterative keiyaku workflows with Codex subagents.",
   "license": "MIT",
   "type": "module",
@@ -51,8 +51,9 @@
     "@earendil-works/pi-coding-agent": "^0.80.10",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@openai/codex-sdk": "^0.113.0",
-    "@opencode-ai/sdk": "1.17.20",
+    "@opencode-ai/sdk": "1.18.3",
     "simple-git": "^3.21.0",
+    "yaml": "^2.9.0",
     "zod": "4.3.6"
   },
   "devDependencies": {

package/skills/keiyaku/SKILL.md

@@ -1,28 +1,45 @@
 ---
 name: keiyaku
-description: Use when you need Keiyaku tools to coordinate Akuma work, organize parallel operations, review diffs, and create or manage worktrees.
+description: Use when working in a Keiyaku repository — contract-style coding where changes run on isolated branches and nothing lands without your sign-off.
 allowed-tools: Bash(keiyaku *)
 ---
 
 # Keiyaku
 
-Keiyaku is a local CLI for contract-style coding work in git repositories.
+CLI for contract-style coding in git repos. The mind model, Chainsaw Man rules: you make a **contract** to get work done, you can **call a devil** (akuma) to do it, and words mean nothing — only the commits left behind count. Nothing merges to main without your sign-off.
 
-Prefer the CLI as the source of truth:
+## Mind model
 
-```bash
-keiyaku guide
-keiyaku <command> --help
-```
+Three kinds of objects:
 
-Akuma call/tell/wait/revive lifecycle is owned by the `keiyaku-akuma` skill. Load that skill for helper execution.
+- **task** — a planning note in the repo. No branch, no execution. → `keiyaku-task` skill
+- **contract** — a unit of work with its own branch + worktree. Born by `bind`, dies by `claim` (merged) or `forfeit` (abandoned). Who works inside it — you, an akuma, anyone — is not keiyaku's business; only the result is. → `keiyaku-workflow` skill
+- **akuma / projection** — a callable worker and its live run. `call` starts one, `wait` watches it, `tell` sends more instructions. → `keiyaku-akuma` skill
 
-## Basic Flow
+## Quick start
 
-For committed delivery work, bind the contract, open an arc before implementation, commit delivery work, amend when the governing contract changes, renew when the base drifts, and petition only after the delivery is ready for settlement. Opening another arc seals the current one; petition also seals an open arc, so no extra closing arc is needed.
+```bash
+keiyaku task add "fix the flaky pump test"   # write the idea down          → k-3f9a21c4b0d2
+keiyaku bind --task k-3f9a21c4b0d2           # start it: branch + worktree
+cd .keiyaku/wt/<place>                       # work and commit here — yourself,
+                                             #   or: keiyaku call <akuma> "fix it"
+keiyaku status                               # is anything stuck? what's next?
+keiyaku petition <<'EOF'                     # done: seal + settle; the oath is required
+## Oath
+I fixed the flaky test; suite is green.
+EOF
+# passes → merged to main; a gate fails → keep working, petition again
+```
 
-Use `status` to inspect the Kanshi board and `forfeit` to archive abandoned work. Consult command help for their syntax and flags.
+That's the whole loop. Skip the task when the work needs no planning:
+`keiyaku bind --place NAME --objective TEXT --scope GLOB --checks CHECK` (or the same as Markdown on stdin — `bind --help` shows the shape).
 
-## Help
+## Getting oriented
+
+```bash
+keiyaku status             # the whole board: contracts, running work, ready tasks
+keiyaku guide              # long-form mechanics
+keiyaku <command> --help   # exact syntax — never guess flags or stdin formats
+```
 
-Use `keiyaku <command> --help` for command syntax and flags, and `keiyaku guide` for long-form mechanics. Do not guess Markdown input sections or option defaults.
+`status` is where you go when you lose track of anything: projection ids, contract state, what's ready.

package/skills/keiyaku-akuma/SKILL.md

@@ -1,75 +1,48 @@
 ---
 name: keiyaku-akuma
-description: Use when you need to dispatch an Akuma to do work for you — call a demon, check on it, yell more instructions, or continue from a prior turn.
+description: Use when you need an Akuma to work for you — call a devil, watch it, send more instructions, kill it, or revive it from its record.
 allowed-tools: Bash(keiyaku *)
 ---
 
 # Keiyaku Akuma
 
-```bash
-keiyaku akuma list
-keiyaku <command> --help
-```
+Running devils. Contract lifecycle = `keiyaku-workflow` skill.
 
-Contract work = `keiyaku` skill. This skill = helpers only.
+## Mind model
 
-## Two ids
+- **profile** — a devil you can call (`keiyaku akuma ls`). Markdown file: frontmatter = provider/model config, body = its instructions. Project `.keiyaku/akuma/` > user `~/.keiyaku/akuma/` > builtin.
+- **projection** (`name/8hex`) — one live run of a devil. This is the id for `wait` / `tell` / `kill`.
+- **artifact** (`rsp_…`) — what a finished run left behind. This is the id for `revive`.
 
-| Id | Means | Use with |
-| --- | --- | --- |
-| projection id | live who | `wait`, `tell`, `status` |
-| artifact id | saved answer | `revive` |
+Rule of thumb: alive → projection id; want to continue a finished/dead one → artifact id.
 
-## Daily path
+## Common usage
 
 ```bash
-keiyaku call NAME "task..."                   # launch + foreground join (no CLI --timeout)
-keiyaku call NAME --detach "task..."          # return after launch; keep projection id
-keiyaku wait <projection-id>                  # join until terminal; prints activity list
-keiyaku wait <projection-id> --timeout 5m     # bounded join; timeout keeps projection alive
-keiyaku tell <projection-id> "more..."        # mailbox only; does not wait
-keiyaku wait <projection-id> --timeout 10m    # after tell, rejoin to see progress/outcome
-keiyaku status                                # board + compact activity summary; rediscover ids
-keiyaku revive ARTIFACT_ID                    # new life from saved answer
+keiyaku akuma ls                              # who's callable
+keiyaku call NAME "do the thing"              # run in foreground until it finishes
+keiyaku call NAME --wait 10m "do the thing"   # bounded: after 10m you get a snapshot, it keeps running
+keiyaku call NAME --detach "do the thing"     # fire and forget; note the projection id
+keiyaku call NAME - < prompt.md               # long prompt: literal `-` reads stdin
+keiyaku wait <proj-id>                        # join a running one; prints its activity
+keiyaku wait <proj-id> --timeout 5m           # peek for 5m; timeout = snapshot, not death
+keiyaku tell <proj-id> "also do X"            # drop instructions in its mailbox
+keiyaku tell <proj-id> --wait 5m "also do X"  # tell, then watch the response
+keiyaku revive rsp_XXXX "continue..."         # new run continuing from a record
+keiyaku kill <proj-id>                        # stop it; record survives, revive still works
+keiyaku status                                # forgot an id? it's on the board
 ```
 
-Long prompt: `keiyaku call NAME - < prompt.md`
-
-## Timeouts (do not confuse)
-
-| Surface | Behavior |
-| --- | --- |
-| `call` / `revive` | **No** CLI `--timeout`. Foreground call joins until terminal or signal. |
-| `call --detach` | Returns after launch. Bounded watching is done with `wait --timeout`. |
-| `wait --timeout DURATION` | Only wait command. Forms: `45s`, `5m`, `2h` (max `24h`). Omit = wait until terminal. Timeout exit is a snapshot, not death. |
-| Worker kill (env) | `KEIYAKU_SUBAGENT_EXEC_TIMEOUT_MS` (default 2700000), `KEIYAKU_SUBAGENT_EXEC_IDLE_TIMEOUT_MS` (default 600000). Not CLI flags. |
-| Startup stall | Adoption timeout → wait/status can show `startup timed out` (launch never adopted). |
-
-## Tell vs wait
-
-- `tell` writes mailbox intent and may wake when eligible. It does **not** join.
-- After tell: run `wait` (optionally `--timeout`) for outcome and activity.
-- While pending tells exist, wait header can show `N tells waiting`.
-
-## Activity list
-
-No separate `activity` command.
-
-- **`wait`**: full activity timeline (tools/turns) under the projection header.
-- **`status`**: under `akuma` section, compact per-projection activity summary + tell counts.
-
-Lost the outer handle → `status` to find projection id → `wait` for the list.
-
-## Infrastructure
-
-- `-C` / `--cwd DIR` — effective command directory (all akuma commands)
+## Expectations
 
-## Other flags
+- `tell` is silent on success: exit 0, zero output. Silence **is** the receipt — do not re-send. Effects show up in `wait`/`status`.
+- Body is required for `call`/`tell`. Piping stdin without a literal `-` does nothing.
+- A `--wait`/`--timeout` expiry prints a live snapshot and exits 0 — the run continues; rejoin with `wait` anytime.
+- `wait` is repeatable: on a finished run it shows the final transcript again.
+- `--contract ADDR` attaches a call to a contract (by place, slug, or full id); `--bare` skips attachment explicitly. `call` only — `revive` takes neither.
 
-- `--akuma NAME` — start a session with the named agent (call only)
-- `--incognito` — no response artifact, no later revive (call only)
-- `@addr` / `--contract` — attach commission/arc context when present (call, wait, tell)
-- `--bare` — skip contract attachment only (call only)
-- `--effort LEVEL` — override opaque provider-native effort value (call, revive, tell); must match profile allowlist when set
+## Occasional flags
 
-Profiles: `keiyaku akuma list|show`; user `<KEIYAKU_HOME>/akuma/`, project `.keiyaku/akuma/`.
+- `--incognito` — no artifact written, no revive possible (call)
+- `--effort LEVEL` — provider effort override; needs a model set (call, revive, tell)
+- `-C DIR` — run relative to another directory (all akuma commands)

package/skills/keiyaku-task/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: keiyaku-task
+description: Use when planning work in a Keiyaku repo — add tasks, wire dependencies, track what's ready, promote a task into a contract.
+allowed-tools: Bash(keiyaku *)
+---
+
+# Keiyaku Task
+
+Planning notes that live in the repo. Executing them is `keiyaku-workflow` (`bind --task`).
+
+## Mind model
+
+A task is a Markdown file in `.keiyaku/tasks/` — id `k-<12hex>`, priority 0–3 (0 highest, default 2), optional body. It has no branch and runs nothing; it's the queue you pull from. States:
+
+```
+open ⇄ in_progress → done | drop
+```
+
+**Ready** = open + every `needs` dependency done. Ready is computed for you — `status` and `task ls` surface it.
+
+## Common usage
+
+```bash
+keiyaku task add "fix the flaky pump test"      # body: pipe stdin for details
+keiyaku task add "title" --pri 1 --needs k-aaa  # priority + dependency at birth
+keiyaku task ls                                 # all open, priority order
+keiyaku task view k-xxxx                        # full detail incl. needs/blocks
+keiyaku task start k-xxxx                       # mark in_progress (start ≠ execute)
+keiyaku task stop k-xxxx                        # back to open
+keiyaku task done k-xxxx
+keiyaku task drop k-xxxx                        # won't do; kept in history, not deleted
+keiyaku task update k-xxxx --pri 0              # also --title, --body TEXT|-, --needs,
+                                                #   --drop-needs — see --help
+keiyaku task doctor                             # check board integrity
+```
+
+## Dependencies
+
+`--needs` stores the forward edge; `blocks` on the other task is derived automatically. Cycles are rejected at write time. Use needs to express "don't start B before A lands" — nothing more.
+
+## Promoting to a contract
+
+```bash
+keiyaku bind --task k-xxxx
+```
+
+Only a **ready** task binds. in_progress → `task stop` first; blocked → finish its needs first. Binding links the task to the contract; the contract's intent you still write yourself — the title doesn't auto-expand into a spec.
+
+## Gotcha
+
+Task files are ordinary tracked files: checking out another branch shows *that branch's* board. Don't panic when states differ across branches — you're reading a different branch's truth, and the old one is still in git.

package/skills/keiyaku-workflow/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: keiyaku-workflow
+description: Use when driving a Keiyaku contract — bind to start isolated work, arc/renew mid-flight, petition for review, claim or forfeit to finish.
+allowed-tools: Bash(keiyaku *)
+---
+
+# Keiyaku Workflow
+
+How a contract lives. Running akuma is the `keiyaku-akuma` skill; task planning is `keiyaku-task`.
+
+## Mind model
+
+A contract = one branch + one worktree + a ledger (its record file in the repo). You work inside the worktree however you like; keiyaku only judges the result at petition. States:
+
+```
+bound → active → petitioned → claimed | forfeited
+```
+
+## The default flow
+
+```bash
+keiyaku bind --place fix-pump --objective "make the pump test pass" \
+             --scope "src/pump/**" --checks "pump tests green"
+# or the same four fields as Markdown: keiyaku bind < contract.md
+#   (# <name> / ## Objective / ## Scope / ## Checks)
+# or promote a ready task:            keiyaku bind --task k-xxxx
+
+cd .keiyaku/wt/fix-pump          # worktree lives at .keiyaku/wt/<place>; commit normally
+
+keiyaku petition <<'EOF'
+## Oath
+I made the pump test pass; ran the suite, all green.
+EOF
+# petition seals your work and runs the settlement pipeline itself —
+# passes → claimed (merged to main); a gate fails → fix, petition again.
+# The oath is required (OATH_MISSING otherwise) and checked for presence, not content.
+```
+
+That's the whole small case: bind → commit → petition.
+
+## Mid-flight commands (use when needed, skip otherwise)
+
+```bash
+keiyaku arc < arc.md         # optional iteration boundary: seals the current intent, opens
+                             #   the next. Markdown: # <title> / ## Objective / ## Brief.
+                             #   Only needed when one contract has multiple distinct pushes.
+keiyaku renew                # main moved under you → rebase onto it. Refuses on conflict
+                             #   instead of guessing; resolve, then renew again.
+keiyaku amend < amendment.md # scope/checks changed → update the paper before the code
+keiyaku log                  # this contract's history
+```
+
+Gotchas:
+- Base drift blocks petition — if main moved, `renew` first; petition tells you.
+- After an explicit `arc` seals, new loose commits need another `arc` before `renew`/`petition` accept them.
+- Not in the worktree? Address a contract with `--contract ADDR` (place, slug, or full id) or the `keiyaku @addr <verb>` prefix.
+
+## Ending it
+
+```bash
+keiyaku forfeit --reason "superseded by fix-pump-v2"
+# abandon: worktree destroyed, history kept. Manual only — nothing auto-forfeits.
+```
+
+There is no `claim` command: claiming is the tail of a passing petition.
+
+## Reading status
+
+```bash
+keiyaku status               # every contract row: state, place, what to do next
+```

package/build/agents/harness/pump.js

@@ -1,158 +0,0 @@
-import { claimAllInbox, claimFencedTells, listTellIds, markTellSubmitted, markTellConsumed, readTellSubmitted, readTellOriginal, isTellCausallyConsumed, appendGenerationEvent, } from "../../core/projection-core.js";
-import { prepareAgentEventForPersistence, } from "./execution-handle.js";
-const OPERATOR_PROMPT_MARKER = "[Operator prompt]\n";
-function frameTellBodies(projectionDirectory, tellIds) {
-    const originals = tellIds.map((tellId) => readTellOriginal(projectionDirectory, "inflight", tellId));
-    const frames = originals
-        .map((original, index) => `--- tell ${tellIds[index]} ---\n${original.text}`)
-        .join("\n\n");
-    const effort = originals.reduce((value, original) => original.effort ?? value, undefined);
-    return { frames, ...(effort ? { effort } : {}) };
-}
-function operatorBodyForContinuation(prompt, tellFrames, sessionContinuation) {
-    if (!sessionContinuation)
-        return `${prompt}\n\n${tellFrames}`;
-    const markerAt = prompt.indexOf(OPERATOR_PROMPT_MARKER);
-    if (markerAt >= 0) {
-        return `${prompt.slice(0, markerAt + OPERATOR_PROMPT_MARKER.length)}${tellFrames}`;
-    }
-    return tellFrames;
-}
-/** Tier-2 boundary snapshot. No tells leaves prompt byte-identical. */
-export function snapshotReplayPrompt(projectionDirectory, prompt, tellFence, executionId, options = {}) {
-    const tellIds = claimFencedTells(projectionDirectory, tellFence, executionId);
-    if (tellIds.length === 0)
-        return { prompt, tellIds };
-    const { frames, effort } = frameTellBodies(projectionDirectory, tellIds);
-    const nextPrompt = operatorBodyForContinuation(prompt, frames, options.sessionContinuation === true);
-    return { prompt: nextPrompt, tellIds, ...(effort ? { effort } : {}) };
-}
-/** Tier-2 has no steer acknowledgement: actual driver start is its ordinal-zero submission point. */
-export function markReplayStarted(projectionDirectory, executionId, tellIds) {
-    for (const tellId of tellIds) {
-        if (listTellIds(projectionDirectory, "inflight").includes(tellId)) {
-            markTellSubmitted(projectionDirectory, tellId, { executionId, fence: { kind: "ordinal", ordinal: 0 } });
-        }
-    }
-}
-/** A successful replay terminal is checkpoint ordinal one; failures intentionally do not consume. */
-export function markReplayCompleted(projectionDirectory, executionId) {
-    for (const tellId of listTellIds(projectionDirectory, "submitted")) {
-        const submitted = readTellSubmitted(projectionDirectory, tellId);
-        if (submitted.executionId === executionId && submitted.fence && isTellCausallyConsumed(submitted.fence, { kind: "ordinal", ordinal: 1 })) {
-            markTellConsumed(projectionDirectory, tellId);
-        }
-    }
-}
-/**
- * Tier-2's only submission acknowledgement. A created driver is deliberately
- * insufficient: observe the first provider event, or a successful completion
- * from a provider that emitted no events.
- */
-export function createReplayRunStartGate(projectionDirectory, executionId, tellIds) {
-    let started = false;
-    const start = () => {
-        if (started)
-            return;
-        markReplayStarted(projectionDirectory, executionId, tellIds);
-        started = true;
-    };
-    return { observeProviderEvent: start, observeSuccessfulCompletion: start };
-}
-/**
- * Supervisor pump: iterates handle.events, forwards to publicChannel,
- * persists public events and checks the tell ledger at checkpoints.
- */
-export async function pumpSupervisor(handle, projectionDirectory, executionId, publicChannel, callbacks = {}, dependencies = {}) {
-    let persistenceEnabled = true;
-    let persistenceDiagnosticQueued = false;
-    const pendingDiagnostics = [];
-    const appendEvent = dependencies.appendGenerationEvent ?? appendGenerationEvent;
-    const dispatch = (event, persist = true) => {
-        if (persist && persistenceEnabled) {
-            try {
-                appendEvent(projectionDirectory, executionId, prepareAgentEventForPersistence(event));
-            }
-            catch (error) {
-                persistenceEnabled = false;
-                if (!persistenceDiagnosticQueued) {
-                    persistenceDiagnosticQueued = true;
-                    pendingDiagnostics.push({
-                        text: `event persistence degraded: ${String(error)}`,
-                        persist: false,
-                    });
-                }
-            }
-        }
-        publicChannel.push(event);
-        callbacks.onEvent?.(event);
-    };
-    try {
-        for await (const event of handle.events) {
-            dispatch(event);
-        }
-    }
-    catch (error) {
-        if (error instanceof Error && error.code === "PROJECTION_STATE_ERROR") {
-            const event = handle.mintEvent({
-                type: "fail",
-                code: "PROJECTION_STATE_ERROR",
-                message: error.message,
-            });
-            if (event)
-                dispatch(event);
-        }
-        else {
-            const event = handle.mintEvent({
-                type: "diagnostic",
-                text: `pump error: ${String(error)}`,
-            });
-            if (event)
-                dispatch(event);
-        }
-    }
-    for (const pending of pendingDiagnostics) {
-        const event = handle.mintEvent({ type: "diagnostic", text: pending.text });
-        if (event)
-            dispatch(event, pending.persist);
-    }
-}
-/**
- * Build an onSyncCheckpoint callback that claims all inbox tells
- * and delivers them via the given SteerControl.
- * Intended for use inside adapter start() calls as the onSyncCheckpoint callback.
- */
-export function buildSyncCheckpointCallback(projectionDirectory, executionId) {
-    const submitting = new Set();
-    return (control, checkpoint) => {
-        claimAllInbox(projectionDirectory);
-        for (const tellId of listTellIds(projectionDirectory, "inflight")) {
-            if (submitting.has(tellId))
-                continue;
-            submitting.add(tellId);
-            const original = readTellOriginal(projectionDirectory, "inflight", tellId);
-            const originalText = original.text;
-            const tell = {
-                id: tellId,
-                text: `--- tell ${tellId} ---\n${originalText}`,
-                ...(original.effort ? { effort: original.effort } : {}),
-            };
-            void control.enqueue(tell)
-                .then((ack) => {
-                if (!ack)
-                    throw new Error("provider enqueue resolved without TellSubmitAck");
-                markTellSubmitted(projectionDirectory, tellId, { executionId, fence: ack.fence });
-            })
-                .catch(() => {
-                // Leave in inflight for the next checkpoint.
-            })
-                .finally(() => submitting.delete(tellId));
-        }
-        for (const tellId of listTellIds(projectionDirectory, "submitted")) {
-            const submitted = readTellSubmitted(projectionDirectory, tellId);
-            if (submitted.executionId === executionId && submitted.fence && isTellCausallyConsumed(submitted.fence, checkpoint.fence)) {
-                markTellConsumed(projectionDirectory, tellId);
-            }
-        }
-    };
-}