@astrosheep/keiyaku 2.9.3 → 2.9.5

package/build/git/streaming-batch.js

@@ -0,0 +1,301 @@
+import { spawn } from "node:child_process";
+import { normalizeFilesystemCoordinate } from "../fs/path-coordinate.js";
+import { gitProcessEnv, resolveGitTimeoutMs, } from "./core.js";
+/** Default long-lived batch argv. One-shot calls must not use this gate. */
+export const GIT_STREAMING_BATCH_DEFAULT_ARGS = ["cat-file", "--batch"];
+/** Safety cap for a single response header line before the body frame. */
+export const GIT_STREAMING_BATCH_MAX_HEADER_BYTES = 64 * 1024;
+/** Wire/framing failure while reading batch stdout. */
+export class GitStreamingBatchFramingError extends Error {
+    name = "GitStreamingBatchFramingError";
+}
+/** Stdout ended before a complete frame arrived. */
+export class GitStreamingBatchResponseEndedError extends Error {
+    name = "GitStreamingBatchResponseEndedError";
+}
+class BufferedReader {
+    #iterator;
+    #buffer = Buffer.alloc(0);
+    #ended = false;
+    constructor(stream) {
+        this.#iterator = stream[Symbol.asyncIterator]();
+    }
+    async #fill() {
+        if (this.#ended) {
+            throw new GitStreamingBatchResponseEndedError("git streaming batch response ended unexpectedly");
+        }
+        const next = await this.#iterator.next();
+        if (next.done) {
+            this.#ended = true;
+            throw new GitStreamingBatchResponseEndedError("git streaming batch response ended unexpectedly");
+        }
+        const chunk = Buffer.isBuffer(next.value) ? next.value : Buffer.from(next.value);
+        this.#buffer = this.#buffer.length === 0 ? chunk : Buffer.concat([this.#buffer, chunk]);
+    }
+    async readLine(maxBytes) {
+        for (;;) {
+            const newline = this.#buffer.indexOf(0x0a);
+            if (newline >= 0) {
+                if (newline > maxBytes) {
+                    throw new GitStreamingBatchFramingError(`git streaming batch header exceeds ${maxBytes} bytes`);
+                }
+                const line = this.#buffer.subarray(0, newline).toString("ascii");
+                this.#buffer = this.#buffer.subarray(newline + 1);
+                return line;
+            }
+            if (this.#buffer.length > maxBytes) {
+                throw new GitStreamingBatchFramingError(`git streaming batch header exceeds ${maxBytes} bytes without a newline`);
+            }
+            try {
+                await this.#fill();
+            }
+            catch (error) {
+                if (error instanceof GitStreamingBatchResponseEndedError) {
+                    throw new GitStreamingBatchFramingError("git streaming batch response ended before a header newline");
+                }
+                throw error;
+            }
+        }
+    }
+    async readExactly(length) {
+        while (this.#buffer.length < length)
+            await this.#fill();
+        const value = this.#buffer.subarray(0, length);
+        this.#buffer = this.#buffer.subarray(length);
+        return value;
+    }
+    async discardExactly(length) {
+        let remaining = length;
+        while (remaining > 0) {
+            if (this.#buffer.length === 0)
+                await this.#fill();
+            const consumed = Math.min(remaining, this.#buffer.length);
+            this.#buffer = this.#buffer.subarray(consumed);
+            remaining -= consumed;
+        }
+    }
+}
+/**
+ * Long-lived Git batch subprocess: raw request lines, framed response records,
+ * and exit/timeout/close facts only. No domain vocabulary or FlowError decisions.
+ */
+export class GitStreamingBatchSession {
+    cwd;
+    #child;
+    #reader;
+    #stderr = [];
+    #timeout;
+    #closed;
+    #maxHeaderBytes;
+    #state = { kind: "open" };
+    #timedOut = false;
+    #aborted = false;
+    #inputError = null;
+    #requestInFlight = false;
+    #closePromise = null;
+    constructor(cwd, child, timeoutMs, maxHeaderBytes) {
+        this.cwd = cwd;
+        this.#child = child;
+        this.#reader = new BufferedReader(this.#child.stdout);
+        this.#maxHeaderBytes = maxHeaderBytes;
+        this.#child.stderr.on("data", (chunk) => this.#stderr.push(chunk));
+        this.#child.stdin.on("error", (error) => {
+            this.#inputError = error;
+        });
+        this.#closed = new Promise((resolve) => {
+            this.#child.once("error", (error) => {
+                resolve({ code: null, signal: null, processError: error });
+            });
+            this.#child.once("close", (code, signal) => {
+                resolve({ code, signal });
+            });
+        });
+        this.#timeout = setTimeout(() => {
+            this.#timedOut = true;
+            this.#child.kill("SIGKILL");
+        }, timeoutMs);
+    }
+    /**
+     * Open the sole long-lived Git batch process for `cwd`.
+     * Default argv is `cat-file --batch`; callers supply compatible batch modes only.
+     */
+    static open(cwd, options) {
+        const args = options?.args ?? GIT_STREAMING_BATCH_DEFAULT_ARGS;
+        const timeoutMs = options?.timeoutMs ?? resolveGitTimeoutMs();
+        const maxHeaderBytes = options?.maxHeaderBytes ?? GIT_STREAMING_BATCH_MAX_HEADER_BYTES;
+        const child = spawn("git", [...args], {
+            cwd: normalizeFilesystemCoordinate(cwd),
+            env: gitProcessEnv(),
+            shell: false,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        return new GitStreamingBatchSession(cwd, child, timeoutMs, maxHeaderBytes);
+    }
+    /**
+     * Write one request line and read one framed response record.
+     * Honors stdin backpressure. Concurrent requests are rejected.
+     */
+    async request(expression, options) {
+        if (this.#state.kind !== "open") {
+            throw new Error("git streaming batch session is not open");
+        }
+        if (this.#requestInFlight) {
+            throw new Error("git streaming batch rejects concurrent requests");
+        }
+        this.#requestInFlight = true;
+        try {
+            if (this.#inputError)
+                throw this.#inputError;
+            const line = `${expression}\n`;
+            if (!this.#child.stdin.write(line)) {
+                await new Promise((resolve, reject) => {
+                    const onDrain = () => {
+                        this.#child.stdin.off("error", onError);
+                        resolve();
+                    };
+                    const onError = (error) => {
+                        this.#child.stdin.off("drain", onDrain);
+                        reject(error);
+                    };
+                    this.#child.stdin.once("drain", onDrain);
+                    this.#child.stdin.once("error", onError);
+                });
+            }
+            let header;
+            try {
+                header = await this.#reader.readLine(this.#maxHeaderBytes);
+            }
+            catch (error) {
+                if (error instanceof GitStreamingBatchFramingError
+                    || error instanceof GitStreamingBatchResponseEndedError) {
+                    this.abort();
+                }
+                throw error;
+            }
+            if (header === `${expression} missing`) {
+                return { kind: "missing", expression };
+            }
+            if (header === `${expression} ambiguous`) {
+                return { kind: "ambiguous", expression };
+            }
+            const parts = header.split(" ");
+            const [oid, type, sizeText, ...unexpected] = parts;
+            const size = Number(sizeText);
+            if (unexpected.length > 0
+                || !oid
+                || !/^[0-9a-f]{40,64}$/.test(oid)
+                || !type
+                || !Number.isSafeInteger(size)
+                || size < 0) {
+                this.abort();
+                throw new GitStreamingBatchFramingError(`git streaming batch returned invalid object header: ${header}`);
+            }
+            if (options?.maxContentBytes !== undefined && size > options.maxContentBytes) {
+                try {
+                    await this.#reader.discardExactly(size + 1);
+                }
+                catch (error) {
+                    this.abort();
+                    throw error;
+                }
+                // Stream stays aligned after discard; oversized is a record limit, not a framing break.
+                throw new Error(`git streaming batch object ${oid} exceeds ${options.maxContentBytes} bytes`);
+            }
+            let content;
+            let terminator;
+            try {
+                content = await this.#reader.readExactly(size);
+                terminator = await this.#reader.readExactly(1);
+            }
+            catch (error) {
+                this.abort();
+                throw error;
+            }
+            if (terminator[0] !== 0x0a) {
+                this.abort();
+                throw new GitStreamingBatchFramingError(`git streaming batch object ${oid} has an invalid frame terminator`);
+            }
+            return {
+                kind: "object",
+                record: { oid, type, size, content },
+            };
+        }
+        finally {
+            this.#requestInFlight = false;
+        }
+    }
+    /**
+     * Idempotent kill of the child after a framing or stream-end failure.
+     * Immediately leaves `open` so no later request can write/read the destroyed child.
+     */
+    abort() {
+        if (this.#aborted)
+            return;
+        this.#aborted = true;
+        if (this.#state.kind === "open") {
+            this.#state = { kind: "closing" };
+        }
+        this.#child.stdin.destroy();
+        this.#child.kill("SIGKILL");
+    }
+    /**
+     * End stdin, await process exit, and return structured close facts.
+     * First close may reject on process spawn error after storing the closed fact;
+     * a later close returns that stored fact. Successful and aborted close stay idempotent.
+     */
+    close() {
+        if (this.#state.kind === "closed")
+            return Promise.resolve(this.#state.fact);
+        if (this.#closePromise)
+            return this.#closePromise;
+        this.#state = { kind: "closing" };
+        // Clear the in-flight promise after settlement so a later close() returns the
+        // stored fact instead of replaying a rejected process-error promise. The
+        // returned chain is what callers await; bookkeeping must not create a second
+        // unhandled rejection.
+        this.#closePromise = this.#closeOnce().then((fact) => {
+            this.#closePromise = null;
+            return fact;
+        }, (error) => {
+            this.#closePromise = null;
+            throw error;
+        });
+        return this.#closePromise;
+    }
+    async #closeOnce() {
+        if (!this.#aborted && this.#child.stdin?.writable) {
+            this.#child.stdin.end();
+        }
+        let exit;
+        try {
+            exit = await this.#closed;
+        }
+        finally {
+            clearTimeout(this.#timeout);
+        }
+        if (exit.processError && !this.#aborted) {
+            const fact = {
+                code: null,
+                signal: null,
+                timedOut: this.#timedOut,
+                aborted: this.#aborted,
+                stderr: Buffer.concat(this.#stderr),
+            };
+            this.#state = { kind: "closed", fact };
+            throw exit.processError;
+        }
+        const fact = {
+            code: exit.code,
+            signal: exit.signal,
+            timedOut: this.#timedOut,
+            aborted: this.#aborted,
+            stderr: Buffer.concat(this.#stderr),
+        };
+        this.#state = { kind: "closed", fact };
+        return fact;
+    }
+}
+/** Open the sole long-lived Git batch subprocess primitive. */
+export function openGitStreamingBatch(cwd, options) {
+    return GitStreamingBatchSession.open(cwd, options);
+}

package/build/git/worktree.js

@@ -1,3 +1,6 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { FlowError } from "../flow-error.js";
 import { createGit, wrapGitError } from "./core.js";
 export const DIRTY_FILE_CATEGORY = {
     modified: "modified",
@@ -8,6 +11,8 @@ export const DIRTY_FILE_CATEGORY = {
     copied: "copied",
     untracked: "untracked",
 };
+const DIRTY_WORKTREE_LIST_LIMIT = 10;
+const KEIYAKU_ARTIFACT_DIR_PREFIX = ".keiyaku/";
 function normalizeGitPath(filePath) {
     return filePath.trim().replace(/^\.\/+/, "");
 }
@@ -67,6 +72,28 @@ export async function getDirtyFiles(cwd) {
         category: deriveDirtyFileCategory(file, statusPathSets),
     }));
 }
+function normalizePathForDirtyMatch(cwd, filePath) {
+    const normalizedPath = filePath.trim();
+    if (!normalizedPath)
+        return "";
+    const repoRelativePath = path.isAbsolute(normalizedPath) ? path.relative(cwd, normalizedPath) : normalizedPath;
+    const platformNormalizedPath = path.normalize(repoRelativePath.replace(/[\\/]+/g, path.sep));
+    return platformNormalizedPath.split(path.sep).join("/").replace(/^\.\/+/, "").replace(/^\/+/, "");
+}
+/** Refuse mutations that can overwrite tracked changes in this worktree. */
+export async function assertCleanTrackedWorkingTree(cwd) {
+    const dirtyFiles = (await getDirtyFiles(cwd)).filter((file) => file.category !== DIRTY_FILE_CATEGORY.untracked);
+    if (dirtyFiles.length === 0)
+        return;
+    const shown = dirtyFiles.slice(0, DIRTY_WORKTREE_LIST_LIMIT);
+    const list = shown.map((file) => `  ${renderDirtyFileStatusLine(file)}`).join("\n");
+    const overflowCount = dirtyFiles.length - shown.length;
+    const overflowLine = overflowCount > 0 ? `\n  ... (+${overflowCount} more)` : "";
+    const hasDirtyKeiyakuArtifacts = dirtyFiles.some((file) => normalizePathForDirtyMatch(cwd, file.path).startsWith(KEIYAKU_ARTIFACT_DIR_PREFIX));
+    throw new FlowError("DIRTY_WORKTREE", `Uncommitted changes detected in working tree:\n${list}${overflowLine}\n\nBlocking changes must be committed or stashed before proceeding.`, hasDirtyKeiyakuArtifacts
+        ? { facts: { kind: "dirty_worktree", hasKeiyakuArtifacts: true } }
+        : undefined);
+}
 export async function getUntrackedFiles(cwd) {
     const git = createGit(cwd);
     let output;
@@ -82,6 +109,44 @@ export async function getUntrackedFiles(cwd) {
         .filter((line) => line.length > 0);
     return Array.from(new Set(files));
 }
+/** Capture conflicted paths while the index still contains unmerged entries. */
+export async function getUnmergedPaths(cwd) {
+    const git = createGit(cwd);
+    let output;
+    try {
+        output = await git.raw(["diff", "--name-only", "--diff-filter=U", "-z"]);
+    }
+    catch (err) {
+        throw wrapGitError("diff --name-only --diff-filter=U", err, cwd);
+    }
+    return Array.from(new Set(output.split("\0").filter((filePath) => filePath.length > 0)));
+}
+async function directoryExists(directory) {
+    try {
+        return (await fs.stat(directory)).isDirectory();
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+/** Git owns these paths; a lingering REBASE_HEAD alone is not active-rebase evidence. */
+export async function hasActiveRebase(cwd) {
+    const git = createGit(cwd);
+    let paths;
+    try {
+        paths = await Promise.all([
+            git.raw(["rev-parse", "--git-path", "rebase-merge"]),
+            git.raw(["rev-parse", "--git-path", "rebase-apply"]),
+        ]);
+    }
+    catch (error) {
+        throw wrapGitError("rev-parse --git-path rebase state", error, cwd);
+    }
+    const directories = paths.map((candidate) => path.resolve(cwd, candidate.trim()));
+    return (await Promise.all(directories.map(directoryExists))).some(Boolean);
+}
 export async function isPathTracked(cwd, filePath) {
     const git = createGit(cwd);
     let output;

package/build/index.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
-import { VERSION } from "./generated/version.js";
+import { VERSION, GIT_HASH } from "./generated/version.js";
 import * as fs from "node:fs/promises";
 import { getConfig, initializeConfig } from "./config/env.js";
 import { ENV_KEYS } from "./config/env-keys.js";
-import { logErrorWithCause } from "./telemetry/logger.js";
-import { runProjectionGenerationRuntime } from "./core/projection-generation-runtime.js";
+import { formatErrorWithCause } from "./telemetry/logger.js";
+import { runProjectionGenerationRuntime } from "./core/projection/index.js";
 import { renderCliHelp, runCliCommand } from "./cli/index.js";
-import { installCliOutputStreamErrorPolicy } from "./cli/output-stream-error-policy.js";
+import { installCliOutputStreamErrorPolicy, writeCliOutput } from "./cli/output-stream-error-policy.js";
 import { assertSubagentCliCommandAllowed } from "./cli/subagent-guard.js";
 installCliOutputStreamErrorPolicy(process.stdout, process.stderr);
 const packageVersion = VERSION;
@@ -45,16 +45,16 @@ async function main() {
         args: cliArgs,
     });
     if (cliArgs.length === 1 && cliArgs[0] === "--version") {
-        console.log(packageVersion);
+        await writeCliOutput(process.stdout, `${GIT_HASH ? `${packageVersion} (${GIT_HASH})` : packageVersion}\n`);
         return;
     }
     if (cliArgs.length === 0 || (cliArgs.length === 1 && (cliArgs[0] === "--help" || cliArgs[0] === "-h"))) {
-        console.log(renderCliHelp(packageVersion));
+        await writeCliOutput(process.stdout, `${renderCliHelp(packageVersion)}\n`);
         return;
     }
     process.exitCode = await runCliCommand(cliArgs);
 }
-main().catch((err) => {
-    logErrorWithCause("Fatal error:", err, { mirrorToDebugLog: false });
-    process.exit(1);
+await main().catch(async (err) => {
+    await writeCliOutput(process.stderr, `${formatErrorWithCause("Fatal error:", err)}\n`);
+    process.exitCode = 1;
 });

package/build/keiyaku.js

@@ -1,10 +1,8 @@
 import * as path from "path";
 import { ACTOR_IDENTITY, SETTINGS_PATH_SEGMENTS } from "./keiyaku-constants.js";
 export { ACTOR_IDENTITY } from "./keiyaku-constants.js";
+export { DRAFT_ARTIFACT_NOTICE, formatArtifactDirectories, KEIYAKU_ARTIFACT_DIRS, KEIYAKU_DRAFT_DIR, RESPONSE_ARTIFACT_NOTICE, RESPONSE_HISTORY_DIR, } from "./artifact-directories.js";
 export const KEIYAKU_FILE = path.join(".keiyaku", "KEIYAKU.md");
-export const KEIYAKU_DRAFT_DIR = path.join(".keiyaku", "draft");
-export const RESPONSE_HISTORY_DIR = path.join(".keiyaku", "response");
-export const KEIYAKU_ARTIFACT_DIRS = [KEIYAKU_DRAFT_DIR, RESPONSE_HISTORY_DIR];
 export const TOOL_NAMES = {
     bind: "bind",
     arc: "arc",
@@ -16,44 +14,12 @@ export const TOOL_NAMES = {
     help: "help",
 };
 export const ACTOR_IDENTITY_PLURAL = `${ACTOR_IDENTITY}s`;
-function formatArtifactDirectory(directory) {
-    return `\`${directory}/\``;
-}
-export function formatArtifactDirectories(directories) {
-    const formatted = directories.map(formatArtifactDirectory);
-    if (formatted.length === 0)
-        return "";
-    if (formatted.length === 1)
-        return formatted[0];
-    if (formatted.length === 2)
-        return `${formatted[0]} and ${formatted[1]}`;
-    return `${formatted.slice(0, -1).join(", ")}, and ${formatted[formatted.length - 1]}`;
-}
-function buildArtifactNotice(directory) {
-    return `Auto-generated artifact. Add ${formatArtifactDirectory(directory)} to \`.gitignore\` if you do not want it tracked.`;
-}
-export const DRAFT_ARTIFACT_NOTICE = buildArtifactNotice(KEIYAKU_ARTIFACT_DIRS[0]);
-export const RESPONSE_ARTIFACT_NOTICE = buildArtifactNotice(KEIYAKU_ARTIFACT_DIRS[1]);
 export const KEIYAKU_BRANCH_PREFIX = "keiyaku/";
 export const BASE_RULES_FILE = path.join(".keiyaku", "base-rules.md");
 export const SETTINGS_FILE = path.join(...SETTINGS_PATH_SEGMENTS);
-export const SUBAGENT_PROVIDERS = [
-    "codex-sdk",
-    "codex-app-server",
-    "claude-agent-sdk",
-    "opencode-sdk",
-    "pi",
-];
-export function isSubagentProvider(value) {
-    return SUBAGENT_PROVIDERS.includes(value);
-}
+export { SUBAGENT_PROVIDERS, isSubagentProvider, BUILTIN_AGENT_PROFILES, BUILTIN_AGENT_NAMES, } from "./agents/providers/registry.js";
 export const CODEX_MODEL_REASONING_EFFORT_CONFIG_KEY = "model_reasoning_effort";
-export const BUILTIN_AGENT_NAMES = ["akuma-codex", "akuma-claude"];
 export const DEFAULT_AGENT_NAME = "akuma-codex";
-export const BUILTIN_AGENT_PROFILES = {
-    "akuma-codex": { provider: "codex-sdk", description: "Deprecated Codex SDK Akuma; use codex-app-server." },
-    "akuma-claude": { provider: "claude-agent-sdk", description: "Default Claude Agent SDK Akuma." },
-};
 export const CLAUDE_PERMISSION_MODES = ["default", "acceptEdits", "bypassPermissions", "plan", "dontAsk", "auto"];
 export const CLAUDE_SETTING_SOURCES = ["project", "user", "local"];
 export const CLAUDE_DEFAULT_SETTING_SOURCES = ["project"];

package/build/telemetry/logger.js

@@ -31,6 +31,9 @@ function stringifyUnknown(error) {
         return String(error);
     }
 }
+export function formatErrorWithCause(message, error) {
+    return `${message} ${stringifyUnknown(error)}`;
+}
 export function logInfo(message, options = {}) {
     log("info", message, options);
 }
@@ -41,6 +44,5 @@ export function logError(message, options = {}) {
     log("error", message, options);
 }
 export function logErrorWithCause(message, error, options = {}) {
-    const details = stringifyUnknown(error);
-    logError(`${message} ${details}`, options);
+    logError(formatErrorWithCause(message, error), options);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/keiyaku",
-  "version": "2.9.3",
+  "version": "2.9.5",
   "description": "CLI for running iterative keiyaku workflows with Codex subagents.",
   "license": "MIT",
   "type": "module",
@@ -24,12 +24,6 @@
   },
   "scripts": {
     "sync:version": "node scripts/generate-version.mjs",
-    "predev": "npm run sync:version --silent",
-    "prebuild": "npm run sync:version --silent",
-    "pretest:unit": "npm run sync:version --silent",
-    "pretest:typecheck": "npm run sync:version --silent",
-    "pretest:integration": "npm run sync:version --silent",
-    "prestart": "npm run sync:version --silent",
     "preversion": "npm test --silent",
     "version": "npm run sync:version --silent && git add src/generated/version.ts",
     "dev": "npx tsx src/index.ts",
@@ -37,12 +31,13 @@
     "test:typecheck": "npx tsc --project tsconfig.tests.json",
     "prepublishOnly": "npm run build",
     "start": "node build/index.js",
-    "test:unit": "node --import ./tests/support/real-provider-path-sentinel.mjs --import tsx --test --test-concurrency=8 tests/unit/*.test.ts",
+    "test:unit": "node scripts/run-unit-tests.mjs",
+    "test:boundaries": "node scripts/check-import-boundaries.mjs",
     "test:integration": "node --import ./tests/support/real-provider-path-sentinel.mjs --import tsx --test tests/integration/integration.test.ts",
     "pretest:cli-expect": "npm run build",
     "test:cli-expect": "node --import ./tests/support/real-provider-path-sentinel.mjs --test --test-concurrency=8 tests/cli-expect/suite/*.test.mjs",
     "test:real-providers": "KEIYAKU_REAL_PROVIDERS=1 node --import tsx --test --test-concurrency=1 tests/real-provider/matrix.test.ts",
-    "test": "npm run test:unit && npm run test:typecheck && npm run test:integration && npm run test:cli-expect",
+    "test": "npm run test:unit && npm run test:typecheck && npm run test:boundaries && npm run test:integration && npm run test:cli-expect",
     "release": "npm version patch && npm publish"
   },
   "dependencies": {
@@ -50,7 +45,6 @@
     "@anthropic-ai/sdk": "^0.110.0",
     "@earendil-works/pi-coding-agent": "^0.80.10",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@openai/codex-sdk": "^0.113.0",
     "@opencode-ai/sdk": "1.18.3",
     "simple-git": "^3.21.0",
     "yaml": "^2.9.0",

package/skills/keiyaku/SKILL.md

@@ -21,10 +21,11 @@ Three kinds of objects:
 ```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"
+cd .keiyaku/wt/<place>                       # work here yourself, or call an Akuma
+keiyaku call <akuma> "fix it"                # worker leaves reviewed source as a dirty tree
+# host coordinator reviews, then git -C <worktree> add/commit accepted paths
 keiyaku status                               # is anything stuck? what's next?
-keiyaku petition <<'EOF'                     # done: seal + settle; the oath is required
+keiyaku petition - <<'EOF'                   # done: seal + settle; the oath is required
 ## Oath
 I fixed the flaky test; suite is green.
 EOF
@@ -32,7 +33,7 @@ EOF
 ```
 
 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).
+`keiyaku bind --place NAME --objective TEXT --scope GLOB --checks CHECK` (or the same as Markdown through `keiyaku bind -` — `bind --help` shows the shape).
 
 ## Getting oriented
 

package/skills/keiyaku-akuma/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: keiyaku-akuma
-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.
+description: Use whenever a request mentions an Akuma, akuma, devil, demon, or 恶魔 and the work may involve calling, watching, telling, killing, or reviving one; covers Keiyaku Akuma profiles, projections, artifacts, lifecycle control, and rejoin operations.
 allowed-tools: Bash(keiyaku *)
 ---
 
@@ -8,42 +8,56 @@ allowed-tools: Bash(keiyaku *)
 
 Running devils. Contract lifecycle = `keiyaku-workflow` skill.
 
-## Mind model
+## Core ideas
 
-- **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.
+- **profile** — callable configuration: frontmatter selects provider/model;
+  Markdown body gives instructions. Project overrides user, which overrides 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`.
 
-Rule of thumb: alive → projection id; want to continue a finished/dead one → artifact id.
+Rule of thumb: continue the same conversation with its projection id. Use an
+artifact id with `revive` only when deliberately starting a new projection;
+failed/dead state alone is not a reason to revive.
 
 ## Common usage
 
 ```bash
 keiyaku akuma ls                              # who's callable
+keiyaku akuma view NAME                       # resolved profile + live projections
 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 tell <proj-id> [--wait DURATION] <BODY|-> # optionally tell, then bounded-join
 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
 ```
 
+## Configuration
+
+```text
+<repo>/.keiyaku/akuma/<name>.md          project profile
+<KEIYAKU_HOME>/akuma/<name>.md           user profile (normally ~/.keiyaku)
+```
+
+Use `keiyaku akuma view NAME` to inspect the resolved source and configuration.
+
 ## Expectations
 
-- `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.
+- Omit tell's bracketed `--wait DURATION` option for silent success: exit 0,
+  zero output. Supply it to perform the ordinary bounded join after acceptance.
+  Silence **is** the receipt — do not re-send. Effects show up in `wait`/`status`.
+- Body is required for `call`/`tell`. Literal `-` selects stdin; unselected
+  piped bytes are ignored and cannot change an argv body.
 - 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.
 
 ## Occasional flags
 
 - `--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)
-- `--repo DIR` — you almost never need this: the repo is inferred from where you stand (`-C` included). Only for the rare case where the contract ledger lives in a *different* repo. Never pass it the same value as `-C`.
+- `--repo DIR` — override repository inference only when the contract ledger
+  lives in a different repository.