@astrosheep/keiyaku 0.1.0 → 0.1.1

package/README.md

@@ -15,9 +15,11 @@ Instead of messy, unstructured chat, Keiyaku turns every task into a formal "Kei
 
 The workflow is a simple, non-negotiable loop:
 
-1.  **`summon`**: Initiate the keiyaku. Creates a branch, locks the mission in `KEIYAKU.md`, and starts Round 1.
-2.  **`drive`** (N times): Review the work, give feedback, and launch the next round.
-3.  **`seal`**: The final verdict. `DONE` (merge & clean) or `DROP` (nuke the branch).
+1.  **Start**: Initiate the keiyaku. Creates a branch, locks the mission in `KEIYAKU.md`, and starts Round 1.
+2.  **Iterate** (N times): Review the work, give feedback, and launch the next round.
+3.  **Verdict**: The final verdict. `DONE` (merge & clean) or `DROP` (nuke the branch).
+
+> Note: Tool names are preset-dependent. The defaults are shown in the next section.
 
 ## 🛠 Available Tools
 
@@ -26,15 +28,37 @@ The workflow is a simple, non-negotiable loop:
 | **`summon`** | Start | Define the goal, constraints, and criteria. Starts the first round. |
 | **`drive`** | Iterate | Provide feedback based on the previous round's output. |
 | **`ask`** | Reason | Pure read-only analysis session. No code changes, just brain power. |
-| **`seal`** | Finish | Finalize the task. Requires a quality check (the "Oath"). |
+| **`request_verdict`** | Finish | Finalize the task. Requires a quality check (the "Oath"). |
+| **`help`** | Help | Show the current rules + preset usage guide. |
 
 ## 🎨 Flavor Your Workflow
 
-Bored with generic tool names? Keiyaku supports **Term Presets**. Change the vibe via the `KEIYAKU_TERM_PRESET` environment variable.
+Bored with generic tool names? Keiyaku supports **Term Presets**.
+
+### How to set
+
+Set `KEIYAKU_TERM_PRESET` in the MCP server env (recommended), or in your shell before launching the server.
 
-- **`default`**: `summon` → `drive` → `seal` (Professional)
+- **Valid values**: `default`, `pokemon`, `mischief` (case-insensitive). If omitted, defaults to `default`.
+
+- **`default`**: `summon` → `drive` → `request_verdict` (Professional)
 - **`pokemon`**: `choose_you` → `command` → `capture` (Gotta code 'em all)
-- **`faye`**: `oi` → `neh` → `hora` (For those who like a little attitude)
+- **`mischief`**: `oi` → `neh` → `hora` (For those who like a little attitude)
+
+`ask` is also renamed by preset (`ask` / `pokedex` / `eeto`). `help` stays `help` across presets.
+
+### What it changes (and what it doesn't)
+
+- **Changes**: tool names/titles/descriptions, the "identity" label, and the set of allowed profile display names (see next section).
+- **Doesn't change**: core behavior (branching, protocol files, verdict rules).
+
+### Choose a profile name
+
+Each run/round can pick a profile via tool input `name`, or globally via `KEIYAKU_SUBAGENT_NAME_OVERRIDE`.
+
+- `default`: `servant-tier-b`, `servant-tier-a`, `servant-tier-s` (also accepts internal names `agent-a|agent-b|agent-c`)
+- `pokemon`: `caterpie`, `pikachu`, `mewtwo`
+- `mischief`: `imp`, `minion`, `mastermind`
 
 ## 📦 Setup
 
@@ -53,7 +77,7 @@ Add this to your `claude_desktop_config.json`:
       "command": "npx",
       "args": ["-y", "keiyaku"],
       "env": {
-        "KEIYAKU_TERM_PRESET": "faye" 
+        "KEIYAKU_TERM_PRESET": "mischief" 
       }
     }
   }
@@ -66,7 +90,7 @@ When a keiyaku is active, two files are maintained in your repo:
 - `KEIYAKU.md`: The immutable "Constitution" of the task.
 - `KEIYAKU_TRACE.md`: The history of every round, feedback, and result.
 
-*Note: These files are automatically cleaned up (or committed) when you `seal` the keiyaku.*
+*Note: These files are automatically cleaned up (or committed) when you `request_verdict` (or preset equivalent) the keiyaku.*
 
 ---
-"Keep your branches clean and your minions in line." — Faye
+"Keep your branches clean and your minions in line." — Mischief preset

package/build/agents/codex-exec.js

@@ -0,0 +1,33 @@
+import { runSubagentProcess, resolvePositiveIntFromEnv, resolvePrefixedCommand } from "./process-runner.js";
+const DEFAULT_CODEX_EXEC_TIMEOUT_MS = 20 * 60 * 1000;
+const DEFAULT_CODEX_EXEC_MAX_CAPTURE_CHARS = 200_000;
+export async function runCodexExec(prompt, cwd, options = {}) {
+    const timeoutMs = resolvePositiveIntFromEnv("KEIYAKU_CODEX_EXEC_TIMEOUT_MS", DEFAULT_CODEX_EXEC_TIMEOUT_MS);
+    const maxCaptureChars = resolvePositiveIntFromEnv("KEIYAKU_CODEX_EXEC_MAX_CAPTURE_CHARS", DEFAULT_CODEX_EXEC_MAX_CAPTURE_CHARS);
+    const codexArgs = ["exec", "--full-auto", "-C", cwd];
+    if (options.model) {
+        codexArgs.push("-m", options.model);
+    }
+    if (options.effort) {
+        codexArgs.push("-c", `model_reasoning_effort=${options.effort}`);
+    }
+    codexArgs.push("-");
+    const { command, args } = resolvePrefixedCommand("codex", codexArgs, process.env.KEIYAKU_CODEX_EXEC_PREFIX);
+    const { stdout, stderr } = await runSubagentProcess({
+        runnerName: "runCodexExec",
+        provider: "codex",
+        command,
+        args,
+        cwd,
+        prompt,
+        timeoutMs,
+        maxCaptureChars,
+        signal: options.signal,
+        startDetails: `model=${options.model ?? "default"} effort=${options.effort ?? "default"}`,
+    });
+    return {
+        finalMessage: stdout.trim(),
+        stdout,
+        stderr,
+    };
+}

package/build/agents/gemini-exec.js

@@ -0,0 +1,37 @@
+import { runSubagentProcess, resolvePositiveIntFromEnv, resolvePrefixedCommand } from "./process-runner.js";
+const DEFAULT_GEMINI_EXEC_TIMEOUT_MS = 20 * 60 * 1000;
+const DEFAULT_GEMINI_EXEC_MAX_CAPTURE_CHARS = 200_000;
+export async function runGeminiExec(prompt, cwd, options = {}) {
+    const timeoutMs = resolvePositiveIntFromEnv("KEIYAKU_GEMINI_EXEC_TIMEOUT_MS", DEFAULT_GEMINI_EXEC_TIMEOUT_MS);
+    const maxCaptureChars = resolvePositiveIntFromEnv("KEIYAKU_GEMINI_EXEC_MAX_CAPTURE_CHARS", DEFAULT_GEMINI_EXEC_MAX_CAPTURE_CHARS);
+    const geminiArgs = ["--approval-mode", "yolo", "--output-format", "json"];
+    if (options.model) {
+        geminiArgs.push("-m", options.model);
+    }
+    // Prompt is passed via stdin to avoid command-line length limits.
+    geminiArgs.push("--prompt", "-");
+    const { command, args } = resolvePrefixedCommand("gemini", geminiArgs, process.env.KEIYAKU_GEMINI_EXEC_PREFIX);
+    const { stdout, stderr } = await runSubagentProcess({
+        runnerName: "runGeminiExec",
+        provider: "gemini",
+        command,
+        args,
+        cwd,
+        prompt,
+        timeoutMs,
+        maxCaptureChars,
+        signal: options.signal,
+        startDetails: `model=${options.model ?? "default"}`,
+    });
+    let finalMessage = stdout.trim();
+    try {
+        const parsed = JSON.parse(stdout);
+        if (parsed.response && typeof parsed.response === "string") {
+            finalMessage = parsed.response;
+        }
+    }
+    catch {
+        // Fall back to raw stdout when Gemini output is not valid JSON.
+    }
+    return { finalMessage, stdout, stderr };
+}

package/build/agents/index.js

@@ -0,0 +1,39 @@
+import { FlowError } from "../common/errors.js";
+import { runCodexExec } from "./codex-exec.js";
+import { runGeminiExec } from "./gemini-exec.js";
+import { isSubagentExecError, SubagentExecError } from "./types.js";
+const CODEX_MODEL = "gpt-5.3-codex";
+const GEMINI_MODEL = "gemini-3-flash-preview";
+const SUBAGENT_PROFILES = {
+    "agent-a": { provider: "codex", model: CODEX_MODEL, effort: "low" },
+    "agent-b": { provider: "codex", model: CODEX_MODEL, effort: "medium" },
+    "agent-c": { provider: "codex", model: CODEX_MODEL, effort: "high" },
+};
+export { SubagentExecError, isSubagentExecError };
+export function getSubagentNames() {
+    return Object.keys(SUBAGENT_PROFILES);
+}
+export function resolveSubagentConfig(name) {
+    const config = SUBAGENT_PROFILES[name];
+    if (!config) {
+        throw new FlowError("UNKNOWN_SUBAGENT", `Unknown subagent '${name}'. Expected one of: ${getSubagentNames().join(", ")}`);
+    }
+    return config;
+}
+export async function runSubagentExec(name, prompt, cwd, options = {}) {
+    const config = resolveSubagentConfig(name);
+    if (config.provider === "codex") {
+        return runCodexExec(prompt, cwd, {
+            model: config.model,
+            effort: config.effort,
+            signal: options.signal,
+        });
+    }
+    if (config.provider === "gemini") {
+        return runGeminiExec(prompt, cwd, {
+            model: config.model,
+            signal: options.signal,
+        });
+    }
+    throw new SubagentExecError("SUBAGENT_EXEC_ERROR", `Unsupported subagent provider '${String(config.provider)}'.`);
+}

package/build/agents/process-runner.js

@@ -0,0 +1,207 @@
+import { spawn } from "node:child_process";
+import { appendDebugLog } from "../utils/debug-log.js";
+import { StringTailBuffer } from "./string-tail-buffer.js";
+import { SubagentExecError } from "./types.js";
+function shellEscape(arg) {
+    return `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+function createAbortError(message) {
+    const error = new Error(message);
+    error.name = "AbortError";
+    return error;
+}
+function createStderrStreamId() {
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+function renderTruncationSuffix(truncatedChars) {
+    if (truncatedChars <= 0)
+        return "";
+    return `\n...[truncated ${truncatedChars} chars from start]...`;
+}
+function terminateChildTree(pid, detached, signal) {
+    if (!pid)
+        return;
+    if (detached && process.platform !== "win32") {
+        try {
+            process.kill(-pid, signal);
+            return;
+        }
+        catch {
+            // Fall through to direct child kill when process group kill fails.
+        }
+    }
+    try {
+        process.kill(pid, signal);
+    }
+    catch {
+        // Best effort shutdown.
+    }
+}
+function getCapturedOutput(stdoutBuffer, stderrBuffer) {
+    const stdoutSnapshot = stdoutBuffer.snapshot();
+    const stderrSnapshot = stderrBuffer.snapshot();
+    return {
+        stdout: `${stdoutSnapshot.text}${renderTruncationSuffix(stdoutSnapshot.truncatedChars)}`,
+        stderr: `${stderrSnapshot.text}${renderTruncationSuffix(stderrSnapshot.truncatedChars)}`,
+        stdoutSnapshot,
+        stderrSnapshot,
+    };
+}
+export function resolvePositiveIntFromEnv(envName, fallback) {
+    const value = process.env[envName]?.trim();
+    if (!value)
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return fallback;
+    return Math.floor(parsed);
+}
+export function resolvePrefixedCommand(binary, binaryArgs, commandPrefix) {
+    const prefix = commandPrefix?.trim();
+    if (!prefix) {
+        return { command: binary, args: binaryArgs };
+    }
+    return {
+        command: "sh",
+        args: ["-lc", `${prefix} ${binary} ${binaryArgs.map(shellEscape).join(" ")}`],
+    };
+}
+export async function runSubagentProcess(options) {
+    const stderrStreamId = createStderrStreamId();
+    let stderrStreamed = false;
+    const stderrSection = `${options.provider}-stderr`;
+    const prefixStderrChunk = (chunk) => {
+        const normalized = chunk.replace(/\r/g, "");
+        const lines = normalized.split("\n");
+        return lines.map((line) => `[stderr:${stderrStreamId}] ${line}`).join("\n");
+    };
+    try {
+        const detailsSuffix = options.startDetails ? ` ${options.startDetails}` : "";
+        appendDebugLog(`${options.runnerName} start: command=${options.command} args=${JSON.stringify(options.args)} timeoutMs=${options.timeoutMs} maxCaptureChars=${options.maxCaptureChars}${detailsSuffix}`, { cwd: options.cwd, section: options.provider });
+        const { stdout, stderr } = await new Promise((resolve, reject) => {
+            const detached = process.platform !== "win32";
+            const child = spawn(options.command, options.args, { cwd: options.cwd, detached });
+            const stdoutBuffer = new StringTailBuffer(options.maxCaptureChars);
+            const stderrBuffer = new StringTailBuffer(options.maxCaptureChars);
+            let stdoutTotalBytes = 0;
+            let stderrTotalBytes = 0;
+            let finished = false;
+            let forceKillTimer;
+            const finishWithError = (error) => {
+                if (finished)
+                    return;
+                finished = true;
+                clearTimeout(timeout);
+                if (forceKillTimer)
+                    clearTimeout(forceKillTimer);
+                if (options.signal && abortHandler) {
+                    options.signal.removeEventListener("abort", abortHandler);
+                }
+                reject(error);
+            };
+            const requestStop = (error) => {
+                if (finished)
+                    return;
+                appendDebugLog(`${options.runnerName} stop requested: ${error.message}`, { cwd: options.cwd, section: options.provider });
+                terminateChildTree(child.pid, detached, "SIGTERM");
+                forceKillTimer = setTimeout(() => {
+                    terminateChildTree(child.pid, detached, "SIGKILL");
+                }, 5000);
+                finishWithError(error);
+            };
+            const timeout = setTimeout(() => {
+                requestStop((() => {
+                    const captured = getCapturedOutput(stdoutBuffer, stderrBuffer);
+                    return new SubagentExecError("SUBAGENT_TIMEOUT", `${options.provider} exec timed out`, {
+                        timeoutMs: options.timeoutMs,
+                        stdout: captured.stdout,
+                        stderr: captured.stderr,
+                    });
+                })());
+            }, options.timeoutMs);
+            const abortHandler = () => {
+                requestStop(createAbortError(`${options.provider} exec cancelled by client`));
+            };
+            if (options.signal) {
+                if (options.signal.aborted) {
+                    requestStop(createAbortError(`${options.provider} exec cancelled by client`));
+                    return;
+                }
+                options.signal.addEventListener("abort", abortHandler, { once: true });
+            }
+            child.stdout.on("data", (chunk) => {
+                const text = String(chunk);
+                stdoutTotalBytes += Buffer.byteLength(text);
+                stdoutBuffer.append(text);
+            });
+            child.stderr.on("data", (chunk) => {
+                const text = String(chunk);
+                stderrTotalBytes += Buffer.byteLength(text);
+                stderrBuffer.append(text);
+                stderrStreamed = true;
+                appendDebugLog(prefixStderrChunk(text), { cwd: options.cwd, section: stderrSection });
+            });
+            child.on("error", (err) => {
+                appendDebugLog(`${options.runnerName} spawn error: ${err.message}`, { cwd: options.cwd, section: options.provider });
+                finishWithError((() => {
+                    const captured = getCapturedOutput(stdoutBuffer, stderrBuffer);
+                    return new SubagentExecError("SUBAGENT_SPAWN_ERROR", `${options.provider} exec spawn error: ${err.message}`, {
+                        timeoutMs: options.timeoutMs,
+                        stdout: captured.stdout,
+                        stderr: captured.stderr,
+                        cause: err,
+                    });
+                })());
+            });
+            child.on("close", (code) => {
+                clearTimeout(timeout);
+                if (forceKillTimer)
+                    clearTimeout(forceKillTimer);
+                if (options.signal) {
+                    options.signal.removeEventListener("abort", abortHandler);
+                }
+                if (finished)
+                    return;
+                finished = true;
+                const captured = getCapturedOutput(stdoutBuffer, stderrBuffer);
+                appendDebugLog(`${options.runnerName} close: code=${code} stdoutBytes=${stdoutTotalBytes} stderrBytes=${stderrTotalBytes} stdoutTruncatedChars=${captured.stdoutSnapshot.truncatedChars} stderrTruncatedChars=${captured.stderrSnapshot.truncatedChars}`, { cwd: options.cwd, section: options.provider });
+                if (code === 0) {
+                    resolve({ stdout: captured.stdout, stderr: captured.stderr });
+                    return;
+                }
+                const errorText = captured.stderr || captured.stdout || `${options.provider} exec exited with code ${code}`;
+                reject(new SubagentExecError("SUBAGENT_NON_ZERO_EXIT", errorText, {
+                    timeoutMs: options.timeoutMs,
+                    stdout: captured.stdout,
+                    stderr: captured.stderr,
+                    exitCode: code,
+                }));
+            });
+            child.stdin.end(options.prompt);
+        });
+        if (!stderrStreamed && stderr.trim()) {
+            appendDebugLog(`[stderr:${stderrStreamId}] ${stderr.trim()}`, { cwd: options.cwd, section: stderrSection });
+        }
+        return { stdout, stderr };
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            appendDebugLog(`${options.runnerName} error: ${error.name}: ${error.message}`, { cwd: options.cwd, section: options.provider });
+            if (error instanceof SubagentExecError) {
+                if (!stderrStreamed && error.stderr.trim()) {
+                    appendDebugLog(`[stderr:${stderrStreamId}] ${error.stderr.trim()}`, { cwd: options.cwd, section: stderrSection });
+                }
+            }
+        }
+        if (error instanceof Error && error.name === "AbortError") {
+            throw error;
+        }
+        if (error instanceof SubagentExecError) {
+            throw error;
+        }
+        const message = error instanceof Error ? error.message : `Unknown ${options.provider} exec error`;
+        throw new SubagentExecError("SUBAGENT_EXEC_ERROR", `${options.provider} exec failed: ${message}`, {
+            timeoutMs: options.timeoutMs,
+        });
+    }
+}

package/build/agents/round-runner.js

@@ -0,0 +1,53 @@
+import { appendDebugBlock, appendDebugLog } from "../utils/debug-log.js";
+import { asMessage } from "../common/errors.js";
+import { resolveTermPreset } from "../config/term-presets.js";
+import { isSubagentExecError, runSubagentExec } from "./index.js";
+function toSnippet(raw, maxChars = 4000) {
+    const text = raw.trim();
+    if (!text)
+        return undefined;
+    if (text.length <= maxChars)
+        return text;
+    const marker = `\n...[truncated ${text.length - maxChars} chars]...\n`;
+    const side = Math.floor((maxChars - marker.length) / 2);
+    const head = text.slice(0, side);
+    const tail = text.slice(text.length - side);
+    return `${head}${marker}${tail}`;
+}
+export function describeSubagentFailure(error, name, round) {
+    const message = asMessage(error);
+    if (isSubagentExecError(error)) {
+        return {
+            errorCode: error.code,
+            message: error.message,
+            name,
+            round,
+            timeoutMs: error.timeoutMs,
+            exitCode: error.exitCode,
+            stderrSnippet: toSnippet(error.stderr),
+        };
+    }
+    return {
+        errorCode: "SUBAGENT_EXEC_ERROR",
+        message,
+        name,
+        round,
+        timeoutMs: null,
+        exitCode: null,
+    };
+}
+export async function runSubagent(subagent, prompt, cwd, round, signal) {
+    const { identity } = resolveTermPreset();
+    if (process.env.KEIYAKU_FAKE_SUBAGENT === "1") {
+        return `Mock ${identity} '${subagent.displayName}' completed round ${round}.`;
+    }
+    const startLog = `[${identity}] Running execution for '${subagent.displayName}' in ${cwd}`;
+    console.error(startLog);
+    appendDebugLog(startLog, { cwd, section: "script" });
+    const result = await runSubagentExec(subagent.profileName, prompt, cwd, { signal });
+    const summary = result.finalMessage || `${identity} completed successfully.`;
+    if (result.stderr.trim()) {
+        appendDebugBlock("subagent stderr", result.stderr, { cwd, section: "codex-stderr" });
+    }
+    return summary;
+}

package/build/agents/selector.js

@@ -0,0 +1,25 @@
+import { FlowError } from "../common/errors.js";
+import { getAvailableNamesForPreset, getDefaultNameForPreset, resolveSubagentProfileName, resolveTermPreset, } from "../config/term-presets.js";
+import { resolveSubagentConfig } from "./index.js";
+function resolveKnownSubagent(name, preset) {
+    const profileName = resolveSubagentProfileName(name, preset);
+    if (!profileName) {
+        throw new FlowError("UNKNOWN_SUBAGENT", `Unknown subagent '${name}'. Expected one of: ${getAvailableNamesForPreset(preset).join(", ")}`);
+    }
+    resolveSubagentConfig(profileName);
+    return { displayName: name, profileName };
+}
+function resolveConfiguredSubagent(preset) {
+    const fromEnv = process.env.KEIYAKU_SUBAGENT_NAME_OVERRIDE?.trim();
+    if (!fromEnv)
+        return undefined;
+    return resolveKnownSubagent(fromEnv, preset);
+}
+export function selectSubagent(name) {
+    const preset = resolveTermPreset();
+    const configured = resolveConfiguredSubagent(preset);
+    if (configured)
+        return configured;
+    const selected = name?.trim() || getDefaultNameForPreset(preset);
+    return resolveKnownSubagent(selected, preset);
+}

package/build/agents/string-tail-buffer.js

@@ -0,0 +1,44 @@
+export class StringTailBuffer {
+    maxChars;
+    chunks = [];
+    keptChars = 0;
+    totalChars = 0;
+    constructor(maxChars) {
+        if (!Number.isFinite(maxChars) || maxChars <= 0) {
+            throw new Error(`invalid maxChars: ${maxChars}`);
+        }
+        this.maxChars = Math.floor(maxChars);
+    }
+    append(chunk) {
+        if (!chunk)
+            return;
+        this.totalChars += chunk.length;
+        if (chunk.length >= this.maxChars) {
+            this.chunks.length = 0;
+            this.chunks.push(chunk.slice(-this.maxChars));
+            this.keptChars = this.maxChars;
+            return;
+        }
+        this.chunks.push(chunk);
+        this.keptChars += chunk.length;
+        this.trimOverflow();
+    }
+    snapshot() {
+        const text = this.chunks.join("");
+        const truncatedChars = Math.max(0, this.totalChars - text.length);
+        return { text, totalChars: this.totalChars, truncatedChars };
+    }
+    trimOverflow() {
+        while (this.keptChars > this.maxChars && this.chunks.length > 0) {
+            const overflow = this.keptChars - this.maxChars;
+            const first = this.chunks[0];
+            if (first.length <= overflow) {
+                this.chunks.shift();
+                this.keptChars -= first.length;
+                continue;
+            }
+            this.chunks[0] = first.slice(overflow);
+            this.keptChars -= overflow;
+        }
+    }
+}

package/build/agents/types.js

@@ -0,0 +1,19 @@
+export class SubagentExecError extends Error {
+    code;
+    timeoutMs;
+    exitCode;
+    stdout;
+    stderr;
+    constructor(code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "SubagentExecError";
+        this.code = code;
+        this.timeoutMs = options.timeoutMs ?? null;
+        this.exitCode = options.exitCode ?? null;
+        this.stdout = options.stdout ?? "";
+        this.stderr = options.stderr ?? "";
+    }
+}
+export function isSubagentExecError(error) {
+    return error instanceof SubagentExecError;
+}

package/build/common/constants.js

@@ -0,0 +1,3 @@
+export const KEIYAKU_FILE = "KEIYAKU.md";
+export const TRACE_FILE = "KEIYAKU_TRACE.md";
+export const ROUND_SUBAGENTS = ["agent-a", "agent-b", "agent-c"];

package/build/common/errors.js

@@ -0,0 +1,119 @@
+import { getAvailableNamesForPreset, resolveTermPreset } from "../config/term-presets.js";
+function unknownSubagentHint() {
+    const preset = resolveTermPreset();
+    const names = getAvailableNamesForPreset(preset).join(", ");
+    const { identity } = preset;
+    return `Unknown ${identity.toLowerCase()} name. Configured ${identity.toLowerCase()}s: ${names}. Choose one via tool input 'name' or env 'KEIYAKU_SUBAGENT_NAME_OVERRIDE'.`;
+}
+export class FlowError extends Error {
+    code;
+    constructor(code, message, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = "FlowError";
+        this.code = code;
+    }
+}
+export function isFlowError(err) {
+    return err instanceof FlowError;
+}
+export function asMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+export function wrapFlowError(action, err) {
+    if (err instanceof Error && err.name === "AbortError") {
+        return err;
+    }
+    if (isFlowError(err)) {
+        return new FlowError(err.code, `${action} failed: ${err.message}`, err);
+    }
+    return new Error(`${action} failed: ${asMessage(err)}`);
+}
+export function pickHintFromError(err, message) {
+    if (isFlowError(err)) {
+        switch (err.code) {
+            case "NOT_GIT_REPO":
+                return "The provided `cwd` is not a git repository.";
+            case "ACTIVE_KEIYAKU_EXISTS":
+                return "An active keiyaku branch already exists in this repository.";
+            case "EXISTING_KEIYAKU_BRANCH_FOUND":
+                return "At least one local `keiyaku/*` branch already exists in this repository.";
+            case "EMPTY_PARAM":
+                return "One or more required parameters are empty.";
+            case "DIRTY_WORKTREE":
+                return "The working tree has uncommitted changes.";
+            case "NOT_ACTIVE_KEIYAKU_BRANCH":
+                return message;
+            case "MISSING_KEIYAKU_BASE":
+                return "Current keiyaku branch is missing `keiyakuBase` metadata.";
+            case "MISSING_PROTOCOL_FILES":
+                return "Required protocol files are missing (`KEIYAKU.md` or `KEIYAKU_TRACE.md`).";
+            case "DONE_MERGE_CONFLICT":
+                return "DONE encountered a git merge conflict.";
+            case "CLOSE_QUALITY_GATE_FAILED":
+                return "DONE requires metPrecise/metMinimal/metIsolated/metIdiomatic/metCohesive all set to true.";
+            case "OATH_MISMATCH":
+                return err.message;
+            case "SUBAGENT_DID_NOT_ADVANCE_ROUND":
+                return "Subagent run did not append the expected new round in `KEIYAKU_TRACE.md`.";
+            case "ROUND_SUBAGENT_FAILED":
+                return "Subagent execution failed. Review KEIYAKU_TRACE.md for details, then continue with a narrower directive.";
+            case "INVALID_BRANCH_TITLE":
+                return "Title cannot be converted to a valid branch token for `keiyaku/<title>`.";
+            case "UNKNOWN_SUBAGENT":
+                return unknownSubagentHint();
+            default:
+                return "Review the error details, fix the issue, and retry.";
+        }
+    }
+    // Fallback for untyped runtime errors.
+    if (message.includes("is not a git repository")) {
+        return "The provided `cwd` is not a git repository.";
+    }
+    if (message.includes("active keiyaku already exists")) {
+        return "An active keiyaku branch already exists in this repository.";
+    }
+    if (message.includes("existing keiyaku branch found")) {
+        return "At least one local `keiyaku/*` branch already exists in this repository.";
+    }
+    if (message.includes("parameter") && message.includes("cannot be empty")) {
+        return "One or more required parameters are empty.";
+    }
+    if (message.includes("working tree has uncommitted changes")) {
+        return "The working tree has uncommitted changes.";
+    }
+    if (message.includes("current branch is not an active keiyaku branch")) {
+        return "No active keiyaku branch (`keiyaku/*`). If this task is not using keiyaku workflow, skip this tool call.";
+    }
+    if (message.includes("is missing base metadata")) {
+        return "Current keiyaku branch is missing `keiyakuBase` metadata.";
+    }
+    if (message.includes("missing protocol files")) {
+        return "Required protocol files are missing (`KEIYAKU.md` or `KEIYAKU_TRACE.md`).";
+    }
+    if (message.includes("DONE merge conflict")) {
+        return "DONE encountered a git merge conflict.";
+    }
+    if (message.includes("requires metPrecise/metMinimal/metIsolated/metIdiomatic/metCohesive all set to true")) {
+        return "DONE requires metPrecise/metMinimal/metIsolated/metIdiomatic/metCohesive all set to true.";
+    }
+    if (message.includes("requires the sacred oath to exactly equal") ||
+        message.includes("requires oath to exactly match configured value") ||
+        message.includes("requires oath to match configured value. If template contains") ||
+        message.includes("To declare DONE, you must solemnly swear the sacred oath.") ||
+        message.includes("To declare DONE, oath mismatch.")) {
+        return message;
+    }
+    if (message.includes("subagent did not advance round") || message.includes("did not append KEIYAKU_TRACE")) {
+        return "Subagent run did not append the expected new round in `KEIYAKU_TRACE.md`.";
+    }
+    if (message.includes("failed during subagent execution")) {
+        return "Subagent execution failed. Review KEIYAKU_TRACE.md for details, then continue with a narrower directive.";
+    }
+    if (message.includes("cannot be converted to a valid branch name")) {
+        return "Title cannot be converted to a valid branch token for `keiyaku/<title>`.";
+    }
+    if (message.includes("Unknown subagent")) {
+        return unknownSubagentHint();
+    }
+    return "Review the error details, fix the issue, and retry.";
+}