@astrosheep/keiyaku 2.9.0 → 2.9.2

package/build/core/projection-coordinate.js

@@ -1,6 +1,8 @@
 import { spawnSync } from "node:child_process";
 import * as path from "node:path";
 import { ProjectionStateError } from "./atomic-publish.js";
+import { isGitExecutableUnavailable } from "../git/core.js";
+import { gitCommonRootPath, resolveGitCommonRootSync } from "./path-coordinate.js";
 /**
  * Resolve projection storage root and authority from one Git probe.
  *
@@ -19,6 +21,9 @@ export function resolveProjectionCoordinate(cwd) {
         },
         stdio: ["ignore", "pipe", "pipe"],
     });
+    if (result.error && isGitExecutableUnavailable(result.error)) {
+        return { physicalRoot: cwd, authority: { kind: "user" } };
+    }
     if (result.error) {
         throw new ProjectionStateError(`cannot resolve projection repository coordinate: ${result.error.message}`);
     }
@@ -30,10 +35,17 @@ export function resolveProjectionCoordinate(cwd) {
         throw new ProjectionStateError(`cannot resolve projection repository coordinate${detail ? `: ${detail}` : ` (git exited ${String(result.status)})`}`);
     }
     const [bare, commonDir] = result.stdout.trim().split(/\r?\n/);
-    if (bare !== "false" || !commonDir || !path.isAbsolute(commonDir)) {
+    const stableRoot = commonDir === undefined ? undefined : gitCommonRootPath(commonDir);
+    if (bare !== "false" || !commonDir || !stableRoot || !path.isAbsolute(stableRoot)) {
         return { physicalRoot: cwd, authority: { kind: "user" } };
     }
-    const physicalRoot = path.dirname(commonDir);
+    let physicalRoot;
+    try {
+        physicalRoot = resolveGitCommonRootSync(commonDir);
+    }
+    catch (error) {
+        throw new ProjectionStateError(`cannot resolve projection repository root ${stableRoot}`, { cause: error });
+    }
     return {
         physicalRoot,
         authority: { kind: "repository", stableRoot: physicalRoot },

package/build/core/renew.js

@@ -10,7 +10,7 @@ import { captureSeal, findOpenArc, getMaxArc, receiptsAfterFence, sealCurrentArc
 import { deriveContractState, isTerminalState } from "./status/lifecycle.js";
 import { commissionTarget, latestBase } from "./status/drift.js";
 import { findContractWorktreePath } from "./worktree-path.js";
-import { getCurrentBranch, isGitRepo } from "../git/branches.js";
+import { getCurrentBranch, requireGitRepository } from "../git/branches.js";
 import { resolveContractAddress, withResolvedAddress } from "./addressing.js";
 import { ACTOR_IDENTITY } from "../keiyaku.js";
 import { persistResponseHistory } from "./transcripts.js";
@@ -164,9 +164,7 @@ export async function renewContract(input) {
     };
 }
 export async function renewKeiyaku(input) {
-    if (!(await isGitRepo(input.cwd))) {
-        throw new FlowError("NOT_GIT_REPO", `${input.cwd} is not a git repository`);
-    }
+    await requireGitRepository(input.cwd, "renew");
     const address = input.address ?? await resolveContractAddress(input.cwd, input.contractId, input.contractAddressSource);
     return await withResolvedAddress(address, async () => {
         const contractId = address.binding.commissionId;

package/build/core/status/board.js

@@ -1,5 +1,5 @@
 import { loadKeiyakuSettings } from "../../config/settings/loader.js";
-import { isGitRepo } from "../../git/branches.js";
+import { observeGitRepository } from "../../git/branches.js";
 import { listContractIds, readLedger } from "../ledger.js";
 import { readProjectionStatusBoard } from "../projection-status.js";
 import { deriveQueueReadModel, queueMembership, } from "../queue.js";
@@ -142,10 +142,13 @@ export async function readKanshiBoard(cwd, now, opts) {
     const targetFilter = opts?.target ?? null;
     const loadedSettings = await loadKeiyakuSettings(cwd);
     const tasks = await readTaskStatusSummary(cwd);
-    if (!(await isGitRepo(cwd))) {
+    const repository = await observeGitRepository(cwd);
+    if (repository.capability === "unknown")
+        throw repository.error;
+    if (repository.capability !== "available" || repository.coordinate !== "repository") {
         return {
             contracts: [],
-            projections: null,
+            projections: readProjectionStatusBoard(cwd, now, { showAll: opts?.showAllProjections }),
             queueLength: 0,
             diseases: loadedSettings.diseases,
             claimReconciliation: null,

package/build/core/task-contract.js

@@ -1,4 +1,5 @@
 import { FlowError } from "../flow-error.js";
+import { assertGitObservation, requireGitRepository } from "../git/branches.js";
 import { withLockHeldTaskBoard } from "./task-git-store.js";
 import { prepareTaskDocumentReplacements, taskRepositoryFromLockedBoard } from "./task-store-repository.js";
 import { containsCommit, createLandingCommit, createTaskBoardCommit, inspectCurrentBranch, publishForwardTaskBoardCommit, readableRefHead, reconcileTaskIndex, refHead, sameTaskSourceBytes, taskContractAtCommit, taskWritesFromSources, updateBranch, updateTargetRef, } from "./task/settlement-git.js";
@@ -17,8 +18,12 @@ async function replaceTaskDocument(repository, replacement) {
     }));
 }
 export async function settleTaskBoardForBind(input, deps = {}) {
+    await requireGitRepository(input.cwd, "task bind");
     return withLockHeldTaskBoard(input.cwd, async (transaction) => {
         if (transaction.location.mode !== "git") {
+            if (transaction.location.capability === "unavailable") {
+                assertGitObservation({ capability: "unavailable" }, "task bind");
+            }
             throw new FlowError("NOT_GIT_REPO", "task bind requires Git task storage");
         }
         const hubCwd = transaction.location.root;
@@ -103,9 +108,13 @@ export async function settleTaskBoardForBind(input, deps = {}) {
     });
 }
 export async function reconcileTaskForfeit(input) {
+    await requireGitRepository(input.cwd, "task forfeit");
     const hubRoot = await stableRepoRoot(input.cwd);
     return withLockHeldTaskBoard(hubRoot, async (transaction) => {
         if (transaction.location.mode !== "git") {
+            if (transaction.location.capability === "unavailable") {
+                assertGitObservation({ capability: "unavailable" }, "task forfeit");
+            }
             throw new FlowError("NOT_GIT_REPO", "task forfeit requires Git task storage");
         }
         const repository = taskRepositoryFromLockedBoard(transaction);
@@ -126,6 +135,7 @@ export async function reconcileTaskForfeit(input) {
  * one complete snapshot of the common hub board held under its repository lock.
  */
 export async function settleTaskBoardForLanding(input) {
+    await requireGitRepository(input.cwd, "task landing");
     const hubRoot = await stableRepoRoot(input.cwd);
     let lastTargetHead = input.targetHead;
     let lastPublishError;
@@ -133,6 +143,9 @@ export async function settleTaskBoardForLanding(input) {
     for (let attempt = 0; attempt < 4; attempt += 1) {
         const result = await withLockHeldTaskBoard(hubRoot, async (transaction) => {
             if (transaction.location.mode !== "git") {
+                if (transaction.location.capability === "unavailable") {
+                    assertGitObservation({ capability: "unavailable" }, "task landing");
+                }
                 throw new FlowError("NOT_GIT_REPO", "task landing requires Git task storage");
             }
             // Each attempt reads fresh target and board facts while holding the

package/build/core/task-git-runtime.js

@@ -1,4 +1,4 @@
-import { isGitRepo } from "../git/branches.js";
+import { observeGitRepository } from "../git/branches.js";
 import { listContractIds } from "./ledger.js";
 import { contractBoundByEngineWorktree, stableRepoRoot } from "./worktree-path.js";
 import { inspectTaskLock, openTaskStore } from "./task-git-store.js";
@@ -6,7 +6,10 @@ import { taskRepositoryFromStore } from "./task-store-repository.js";
 import { withTaskWorktreePolicy } from "./task-worktree.js";
 import { inspectTaskDoctor } from "./task-doctor.js";
 export async function taskCommandContractId(cwd) {
-    if (!(await isGitRepo(cwd)))
+    const observation = await observeGitRepository(cwd);
+    if (observation.capability === "unknown")
+        throw observation.error;
+    if (observation.capability !== "available" || observation.coordinate !== "repository")
         return undefined;
     return contractBoundByEngineWorktree(cwd);
 }

package/build/core/task-git-store.js

@@ -4,6 +4,8 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { DatabaseSync } from "node:sqlite";
 import { FlowError } from "../flow-error.js";
+import { isGitExecutableUnavailable, NOT_GIT_REPOSITORY_PATTERNS } from "../git/core.js";
+import { gitCommonRootPath, normalizeGitPath } from "./path-coordinate.js";
 const TASK_ID = /^k-[0-9a-f]{12}$/;
 const SQLITE_BUSY = 5;
 const LOCK_FILE = "task-lock.sqlite";
@@ -35,17 +37,6 @@ function defaultRunGit(cwd, args, input) {
         stdio: ["pipe", "pipe", "pipe"],
     });
 }
-function runGit(cwd, args, input) {
-    const result = defaultRunGit(cwd, args, input);
-    if (result.error) {
-        throw new FlowError("INTERNAL_STATE", `git ${args[0]} failed: ${result.error.message}`, { cause: result.error });
-    }
-    if (result.status !== 0) {
-        const detail = result.stderr.trim() || `exit ${String(result.status)}`;
-        throw new FlowError("INTERNAL_STATE", `git ${args[0]} failed: ${detail}`);
-    }
-    return result.stdout;
-}
 function nearestDirectoryBoard(cwd) {
     const original = path.resolve(cwd);
     let candidate = original;
@@ -58,26 +49,45 @@ function nearestDirectoryBoard(cwd) {
         candidate = parent;
     }
 }
-export async function locateTaskBoard(cwd) {
-    const probe = defaultRunGit(cwd, ["rev-parse", "--is-inside-work-tree", "--is-bare-repository"]);
-    if (probe.error) {
+export function taskBoardRootFromGitDir(rawGitDir, platform = process.platform) {
+    return gitCommonRootPath(rawGitDir, platform);
+}
+export async function locateTaskBoard(cwd, runGitProbe = defaultRunGit) {
+    const probe = runGitProbe(cwd, ["rev-parse", "--is-inside-work-tree", "--is-bare-repository"]);
+    if (probe.error && !isGitExecutableUnavailable(probe.error)) {
         throw new FlowError("INTERNAL_STATE", `cannot inspect task repository: ${probe.error.message}`, { cause: probe.error });
     }
+    if (probe.error) {
+        return { mode: "directory", root: nearestDirectoryBoard(cwd), capability: "unavailable" };
+    }
     if (probe.status !== 0) {
-        return { mode: "directory", root: nearestDirectoryBoard(cwd) };
+        if (NOT_GIT_REPOSITORY_PATTERNS.some((pattern) => probe.stderr.includes(pattern))) {
+            return { mode: "directory", root: nearestDirectoryBoard(cwd) };
+        }
+        const detail = probe.stderr.trim() || `exit ${String(probe.status)}`;
+        throw new FlowError("INTERNAL_STATE", `cannot inspect task repository: ${detail}`);
     }
     const [insideWorktree, bare] = probe.stdout.trim().split(/\r?\n/);
     if (bare === "true" || insideWorktree !== "true") {
         throw new FlowError("NOT_GIT_REPO", "bare repositories are not supported for task storage");
     }
-    const facts = runGit(cwd, ["rev-parse", "--path-format=absolute", "--show-toplevel", "--git-common-dir"], undefined);
-    const [checkoutRoot, gitDir] = facts.trimEnd().split(/\r?\n/);
-    if (!checkoutRoot || !gitDir || !path.isAbsolute(checkoutRoot) || !path.isAbsolute(gitDir)) {
+    const facts = runGitProbe(cwd, ["rev-parse", "--path-format=absolute", "--show-toplevel", "--git-common-dir"]);
+    if (facts.error) {
+        throw new FlowError("INTERNAL_STATE", `git rev-parse failed: ${facts.error.message}`, { cause: facts.error });
+    }
+    if (facts.status !== 0) {
+        const detail = facts.stderr.trim() || `exit ${String(facts.status)}`;
+        throw new FlowError("INTERNAL_STATE", `git rev-parse failed: ${detail}`);
+    }
+    const [checkoutRoot, rawGitDir] = facts.stdout.trimEnd().split(/\r?\n/);
+    const gitDir = rawGitDir === undefined ? undefined : normalizeGitPath(rawGitDir);
+    const normalizedCheckoutRoot = checkoutRoot === undefined ? undefined : normalizeGitPath(checkoutRoot);
+    if (!normalizedCheckoutRoot || !gitDir || !path.isAbsolute(normalizedCheckoutRoot) || !path.isAbsolute(gitDir)) {
         throw new FlowError("INTERNAL_STATE", "git returned incomplete task-board location facts");
     }
     return {
         mode: "git",
-        root: path.dirname(gitDir),
+        root: taskBoardRootFromGitDir(gitDir),
         gitDir,
     };
 }
@@ -309,7 +319,7 @@ function assertTaskDirectorySafety(directory) {
     }
 }
 export async function openTaskStore(cwd, deps = {}) {
-    const board = await locateTaskBoard(cwd);
+    const board = await locateTaskBoard(cwd, deps.runGit);
     const directory = taskDirectory(board);
     return {
         mode: board.mode,
@@ -328,7 +338,7 @@ export async function openTaskStore(cwd, deps = {}) {
     };
 }
 export async function withLockHeldTaskBoard(cwd, apply, deps = {}, locatedBoard) {
-    const board = locatedBoard ?? await locateTaskBoard(cwd);
+    const board = locatedBoard ?? await locateTaskBoard(cwd, deps.runGit);
     const directory = taskDirectory(board);
     assertKeiyakuDirectory(board);
     const database = acquireTaskLock(taskLockPath(board));

package/build/core/worktree-path.js

@@ -5,6 +5,7 @@ import { createGit, wrapGitError } from "../git/core.js";
 import { readLedger } from "./ledger.js";
 import { listContractIds } from "./ledger.js";
 import { deriveContractState, isTerminalState } from "./status/lifecycle.js";
+import { gitCommonRootPath, resolveGitCommonRoot } from "./path-coordinate.js";
 export function findBindEntry(entries) {
     return entries.find((entry) => entry.kind === "bind");
 }
@@ -58,10 +59,16 @@ export async function stableRepoRoot(cwd) {
     catch (error) {
         throw wrapGitError("rev-parse --path-format=absolute --git-common-dir", error, cwd);
     }
-    if (!path.isAbsolute(commonDir)) {
+    const stableRoot = gitCommonRootPath(commonDir);
+    if (!path.isAbsolute(stableRoot)) {
         throw new FlowError("INTERNAL_STATE", `git common directory is not absolute: ${commonDir}`);
     }
-    return path.dirname(commonDir);
+    try {
+        return await resolveGitCommonRoot(commonDir);
+    }
+    catch (error) {
+        throw new FlowError("INTERNAL_STATE", `cannot resolve git common directory ${stableRoot}`, { cause: error });
+    }
 }
 export async function contractWorktreePathFromBind(cwd, contractId, bind) {
     return path.join(await stableRepoRoot(cwd), ".keiyaku", "wt", bind?.data.place ?? contractId);

package/build/flow-error.js

@@ -21,6 +21,8 @@ function resolveFlowErrorHint(code, context) {
     switch (code) {
         case "NOT_GIT_REPO":
             return "The provided `cwd` is not a git repository.";
+        case "GIT_UNAVAILABLE":
+            return "Install Git, or use an explicitly bare command that does not require repository authority.";
         case "ACTIVE_KEIYAKU_EXISTS":
             return `Next: open an arc with \`${context.arcToolName}\`, then use \`${context.renewToolName}\` when delivery must follow the current base, or \`${context.closeToolName}\` to settle it.`;
         case "CONTRACT_AMBIGUOUS":

package/build/generated/version.js

@@ -1,2 +1,2 @@
 // Auto-generated by scripts/generate-version.mjs
-export const VERSION = "2.8.5";
+export const VERSION = "2.9.1";

package/build/git/branches.js

@@ -1,17 +1,41 @@
 import { simpleGit } from "simple-git";
 import { FlowError } from "../flow-error.js";
-import { createGit, wrapGitError } from "./core.js";
-export async function isGitRepo(cwd) {
-    const git = simpleGit(cwd);
-    git.env("GIT_TERMINAL_PROMPT", "0");
-    git.env("GCM_INTERACTIVE", "Never");
-    git.env("GIT_MERGE_AUTOEDIT", "no");
-    git.env("LC_ALL", "C");
+import { createGit, errorContainsAnyPattern, isGitExecutableUnavailable, NOT_GIT_REPOSITORY_PATTERNS, wrapGitError, } from "./core.js";
+export async function observeGitRepository(cwd) {
     try {
-        return await git.checkIsRepo();
+        const git = simpleGit(cwd);
+        git.env("GIT_TERMINAL_PROMPT", "0");
+        git.env("GCM_INTERACTIVE", "Never");
+        git.env("GIT_MERGE_AUTOEDIT", "no");
+        git.env("LC_ALL", "C");
+        git.env("PATH", process.env.PATH ?? "");
+        const output = await git.raw(["rev-parse", "--is-inside-work-tree", "--is-bare-repository"]);
+        const [insideWorktree, bare] = output.trim().split(/\r?\n/);
+        return {
+            capability: "available",
+            coordinate: insideWorktree === "true" && bare !== "true" ? "repository" : "non-repository",
+        };
     }
     catch (err) {
-        throw wrapGitError("check-is-repo", err, cwd);
+        if (isGitExecutableUnavailable(err))
+            return { capability: "unavailable" };
+        if (errorContainsAnyPattern(err, NOT_GIT_REPOSITORY_PATTERNS)) {
+            return { capability: "available", coordinate: "non-repository" };
+        }
+        return { capability: "unknown", error: wrapGitError("check-is-repo", err, cwd) };
+    }
+}
+export function assertGitObservation(observation, operation) {
+    if (observation.capability === "unavailable") {
+        throw new FlowError("GIT_UNAVAILABLE", `Git executable is unavailable; ${operation} requires repository authority.`);
+    }
+    if (observation.capability === "unknown")
+        throw observation.error;
+    return observation.coordinate;
+}
+export async function requireGitRepository(cwd, operation) {
+    if (assertGitObservation(await observeGitRepository(cwd), operation) === "non-repository") {
+        throw new FlowError("NOT_GIT_REPO", `${cwd} is not a git repository`);
     }
 }
 export async function getCurrentBranch(cwd) {

package/build/git/core.js

@@ -10,6 +10,14 @@ export const MISSING_HEAD_PATTERNS = [
     "unknown revision or path not in the working tree",
     "bad revision 'HEAD'",
 ];
+/** Git is an optional adapter for directory-local product surfaces. */
+export function isGitExecutableUnavailable(error) {
+    const source = (error ?? {});
+    if (source.code === "ENOENT")
+        return true;
+    const message = typeof source.message === "string" ? source.message : String(error);
+    return /spawn\s+git\s+ENOENT|git(?:\.exe)?["']?\s*:\s*(?:not found|no such file)/i.test(message);
+}
 export function compactText(input, maxChars = GIT_ERROR_COMPACT_MAX_CHARS) {
     const text = input.trim();
     if (!text)
@@ -58,5 +66,6 @@ export function createGit(cwd) {
     git.env("GCM_INTERACTIVE", "Never");
     git.env("GIT_MERGE_AUTOEDIT", "no");
     git.env("LC_ALL", "C");
+    git.env("PATH", process.env.PATH ?? "");
     return git;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/keiyaku",
-  "version": "2.9.0",
+  "version": "2.9.2",
   "description": "CLI for running iterative keiyaku workflows with Codex subagents.",
   "license": "MIT",
   "type": "module",

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
 
-The small/default workflow is bind, commit delivery work, then petition. Bind supplies derived default intent a0. Arc is optional for multiple intent iterations: the first explicit arc seals a0, and a later arc seals the current explicit arc. Renew when the base drifts; renew and petition seal the current a0 or open explicit arc. After an explicit arc closes, loose commits require another arc before renew or petition. Amend when the governing contract changes.
+```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,80 +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 ls
-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..."                   # required literal BODY; launch + foreground join
-keiyaku call NAME --detach "task..."          # return after launch; keep projection id
-keiyaku call NAME - < prompt.md               # only literal `-` opens stdin
-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..."        # required literal BODY; mailbox only
-keiyaku tell <projection-id> - < direction.md # explicit stdin body; `-` is never delivered
-keiyaku tell <projection-id> --wait 5m "more..."  # no mandatory `--` before BODY
-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                    # omit body → default continuation
-keiyaku revive ARTIFACT_ID "continue..."      # literal BODY
-keiyaku revive ARTIFACT_ID - < cont.md        # explicit `-` stdin; blank fails
+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 body: `keiyaku call NAME - < prompt.md` or `keiyaku tell PROJECTION - < direction.md`. Never omit call/tell body and hope for piped stdin.
-
-## 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 ls|view`; 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.