oh-my-claudecode 0.2.3 → 0.2.5

package/README.md

@@ -60,7 +60,7 @@ These aren't three plugins you pick and choose. They're one integrated system th
 | **Yith Archive** | Persistent cross-session memory with retrieval-based injection. Dozens of memory primitives: remember, search, consolidate, evict, crystallize, reflect, temporal graph, pattern extraction, and more. Exposed to Claude Code as a stdio MCP server with 7 tools. |
 | **Work-packet protocol** | LLM-requiring memory ops (consolidate, summarize, reflect, etc.) run in sessions with no API key — each function has a state-machine variant that emits prompts for the parent agent to execute with its own subscription auth. |
 | **Block Summarizer** | In-session delegation summarization with on-disk block archive |
-| **8 lifecycle hooks** | Auto-activation, memory redirect, todo enforcement, completion loops, code-quality checks, rule injection, write guards |
+| **8 lifecycle hooks** | Auto-activation, memory redirect, continuous Yith capture, todo enforcement, completion loops, code-quality checks, rule injection, write guards |
 | **10 slash commands** | Direct-invoke any mode or flow from the Claude Code chat bar |
 | **Intent gate** | Every user message is classified and routed before Cthulhu acts |
 | **Work plan system** | Multi-step planning flow with interview → scope → plan → review before execution |
@@ -144,6 +144,53 @@ Named for the Great Race of Yith from *The Shadow Out of Time* — mind-transfer
 - **Crash-safe work-packet flows** — pending continuations for LLM-requiring operations persist to the same store and survive server restarts; resuming with the same continuation token picks up where the flow left off.
 - **Replaces Claude Code's built-in auto-memory** via the `memory-override` SessionStart hook, which tells the session not to write to the built-in memory files. Disable the override with `disabled_hooks: ["memory-override"]` if you prefer to keep the built-in system active.
 
+### The binding ritual (`oh-my-claudecode bind`)
+
+Fresh installs start with an empty `necronomicon.json`. To populate it
+with history, run one command in your terminal:
+
+```bash
+oh-my-claudecode bind
+```
+
+This kicks off a six-phase ritual with a real ANSI TUI (progress bars,
+section headers, per-phase status):
+
+1. **Embedding sigil** — downloads the local nomic embedding model
+   (~137 MB) with a live byte-counter progress bar.
+2. **Claude Code transcripts** — scans every subdirectory under
+   `~/.claude/projects/` (every project you've ever opened a session
+   in), parses the `.jsonl` transcripts, and writes one raw
+   observation per user prompt / assistant text / tool call.
+3. **Opencode grimoire** — if you're migrating from oh-my-opencode, the
+   ritual auto-detects `~/.local/share/opencode/opencode.db` and
+   imports every project / session / message / part it finds.
+4. **Sisyphus migration** — walks your home looking for legacy
+   `.sisyphus/` directories (the oh-my-opencode equivalent of
+   `.elder-gods/`) and copies plans, handoffs, and evidence into the
+   new layout without touching the source.
+5. **Project code scan** — for each project the CLI has seen, walks
+   the code tree (gitignore-aware) and seeds preliminary memories:
+   language stats, package metadata, README sections, directory tree.
+6. **Sealing** — reports how many raw observations are queued for
+   compression and points you at the next step.
+
+The ritual is **resumable**: if any phase errors or you interrupt it,
+re-running `oh-my-claudecode bind` picks up from the failed phase via
+the `KV.bindState` cursor — no manual intervention required.
+
+Phase 2 (LLM-dependent compression of raw observations into
+searchable memories) runs **inside a Claude Code session** via the
+work-packet loop. Either:
+
+- Open Claude Code and run `/necronomicon-bind` — uses your
+  subscription auth via the MCP work-packet protocol.
+- Or install a cron entry that spawns `claude -p` on an interval:
+  ```bash
+  oh-my-claudecode bind --install-cron --interval 1h
+  ```
+  The cron tick drives compression unattended. No API key needed.
+
 ### Work-packet protocol — LLM ops without an API key
 
 13 of Yith's memory operations need an LLM to do their work (`crystallize`, `consolidate`, `consolidate-pipeline`, `compress`, `summarize`, `flow-compress`, `graph-extract`, `temporal-graph-extract`, `expand-query`, `skill-extract`, `reflect`, `enrich-window`, `enrich-session`). If Yith has its own `ANTHROPIC_API_KEY` in `~/.oh-my-claudecode/yith/.env`, these run directly in-process.
@@ -233,7 +280,7 @@ After installation these are available in Claude Code sessions:
 | Command | Description |
 |---------|-------------|
 | `/cthulhu` | Activate Cthulhu orchestrator mode (also creates `.elder-gods/` on first use) |
-| `/bind-necronomicon` | First-time Yith Archive setup ritual — tome check, embedding warmup, search verify, optional session backfill |
+| `/necronomicon-bind` | Necronomicon binding ritual — shells out to `oh-my-claudecode bind` (real TUI, all-projects ingestion, opencode import, sisyphus migration, preliminary code scan) then drains pending compression via the work-packet loop using this session's LLM |
 | `/shoggoth` | Fast parallel codebase search |
 | `/yog-sothoth` | Consult the architecture/debug advisor |
 | `/elder-loop` | Start the self-referential completion loop |
@@ -251,6 +298,7 @@ After installation these are available in Claude Code sessions:
 |------|-------|-------------|
 | `cthulhu-auto` | SessionStart | Auto-activate Cthulhu orchestrator mode when `.elder-gods/` is present in the project |
 | `memory-override` | SessionStart | Redirect persistent memory writes from Claude Code's built-in auto-memory to Yith Archive |
+| `yith-capture` | Stop | Continuous Yith ingestion — after every assistant turn, spawns a background `bind --resume --claude-only` to pull new transcript lines into the archive, and occasionally spawns `claude -p` to drain pending compression when the queue grows past threshold. Debounced; non-blocking; fail-safe. |
 | `todo-continuation` | Stop | Inject a reminder to continue if incomplete todos exist when stopping |
 | `elder-loop` | Stop | Self-referential completion loop — keeps running until the promise is met |
 | `comment-checker` | PostToolUse | Warn when AI-slop comments are introduced (comments that explain obvious code) |

package/commands/necronomicon-bind.md

@@ -0,0 +1,69 @@
+---
+name: necronomicon-bind
+description: Start, continue, or resume the Necronomicon binding ritual. Thin wrapper that shells out to `oh-my-claudecode bind` (real progress bars, state-machine resumption, all-projects ingestion) and then offers to drain any pending compression via the work-packet loop using this session's own LLM.
+---
+
+You are invoking the **Necronomicon Binding Ritual**. The ritual has two halves that must work together:
+
+1. **The fast half** (no LLM) — download the embedding model, scan every past Claude Code transcript across every project on this machine, import opencode history, migrate `.sisyphus/` dirs, seed preliminary memories from project code. This runs as a **real Node process** in the user's terminal with an ANSI TUI showing actual download progress bars and per-phase status. It must run OUTSIDE this Claude Code session.
+
+2. **The slow half** (LLM-dependent) — compress the thousands of raw observations the fast half ingested into searchable memories. This runs **inside this session** via the work-packet protocol, using the session's own subscription auth. Each round is one `yith_trigger → yith_commit_work` loop iteration.
+
+## Why not do everything from this slash command?
+
+Previous versions of this ritual were prompt-only — they asked Claude to call `yith_remember` / `yith_trigger` inline from this slash command. That design was unreliable: Claude would skip steps, print cosmetic ✓ marks without actually invoking the tools, and the user would see "bound in 5 seconds" with an empty Necronomicon. **Do not try to recreate that approach.** The fast half MUST run as a real CLI, and this command's job is to drive it and then handle the compression half.
+
+## Phase 1 — Delegate to the CLI
+
+Do this BEFORE anything else:
+
+1. Tell the user: "Running `oh-my-claudecode bind` in your terminal. This downloads the embedding model (~137 MB, one-time), scans every past Claude Code transcript, imports opencode data, migrates sisyphus directories, and seeds preliminary memories from project code. It's resumable — if it errors mid-run, re-running this command picks up where it stopped."
+
+2. Run via `Bash`:
+   ```bash
+   oh-my-claudecode bind
+   ```
+   Stream the output to the user as it arrives. The CLI already produces its own TUI (section headers, progress bars, status glyphs) so you should forward the output verbatim without adding your own commentary.
+
+3. When `oh-my-claudecode bind` exits, inspect its final lines. If the CLI reports "Ritual elapsed: Xs" and a green ✓, the fast half succeeded. If it reports a red ✗ with an error, surface that to the user and stop — re-running this command will retry the failed phase automatically from the state machine cursor.
+
+## Phase 2 — Drain pending compression via the work-packet loop
+
+The CLI's last line tells you how many raw observations are pending compression. That's the input to this half.
+
+1. Call `yith_trigger({ name: "mem::compress-batch-step", args: { limit: 100 } })`. Expect a `needs_llm_work` envelope with one or more `workPackets` and a `continuation` token.
+
+2. For each packet in the envelope: read `systemPrompt` + `userPrompt`, reason about them inline (you ARE the LLM for Yith — just produce the compression XML the system prompt asks for), and collect the results.
+
+3. Call `yith_commit_work({ continuation, packetResults: [{id, completion}, ...] })`. The response is either terminal (`{status: "success"}`) or another `needs_llm_work` for the next batch.
+
+4. Between rounds, render a monospace ASCII progress bar so the user sees forward motion:
+   ```
+   [▓▓▓▓▓▓░░░░░░░░░░░░░░] 34%  —  171/500 raw observations compressed
+   ```
+   Re-print the bar each round with updated numbers. (The Claude Code chat UI won't animate in place, but a re-printed bar per tool call shows clear progress.)
+
+5. Loop until terminal. Each round's `limit` can be 50-100 — adjust based on how large the prompts are. If a round takes more than ~2 minutes, drop the limit for the next one.
+
+## Phase 3 — Seal the ritual
+
+Final output:
+
+```
+═══════════════════════════════════════════════════════
+  The Necronomicon is bound.
+═══════════════════════════════════════════════════════
+  Tome:              ~/.oh-my-claudecode/yith/necronomicon.json
+  MCP server:        yith-archive (via ~/.claude.json)
+  Embedding:         local:nomic-embed-text-v1.5 (768 dims)
+  Observations:      <total from mem::diagnose>
+  Compressed:        <total - pending>
+  Pending:           <remaining count>
+═══════════════════════════════════════════════════════
+```
+
+If there are still pending observations (either because `limit` capped the batch or because the user interrupted), tell them exactly how many and that running `/necronomicon-bind` again resumes from where it stopped.
+
+## Unattended mode
+
+Mention once at the end: if the user wants this to happen in the background without opening a session, they can run `oh-my-claudecode bind --install-cron [--interval 1h]` once, and a cron entry will run `oh-my-claudecode bind --resume` on the interval. That form uses `claude -p` (Claude Code's non-interactive mode) to drive the compression half, so nothing needs to be open.

package/dist/cli/bind-cron.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Cron installer + `claude -p` spawn-command assembly for unattended
+ * Necronomicon bind / compression.
+ *
+ * Everything here is a pure function over strings — no process
+ * spawning, no crontab mutation, no fs writes. The CLI entry point
+ * orchestrates the actual `crontab -l` / `crontab -` dance; this
+ * module only handles the string-level logic so tests can verify
+ * every edge case without side effects.
+ *
+ * The cron entry calls `oh-my-claudecode bind --resume`, which:
+ *   1. Runs any pending Phase 1 work (filesystem ingestion — no LLM).
+ *   2. For Phase 2 (compression), if an ANTHROPIC_API_KEY is
+ *      configured, routes directly through the in-process LLM
+ *      provider. Otherwise spawns `claude -p` with the command
+ *      produced by `buildClaudePSpawnCommand` below, so Claude Code's
+ *      own subscription auth drives the work-packet loop.
+ */
+/** Suffix appended to every bind-installed crontab entry so the
+ *  installer can find + replace its own line without clobbering
+ *  unrelated entries. */
+export declare const BIND_CRON_MARKER = "# oh-my-claudecode bind";
+/**
+ * Convert a short interval spec like `"1h"`, `"30m"`, `"1d"` into a
+ * cron schedule string. Accepts:
+ *
+ *   `Nm`  — every N minutes (N > 0)
+ *   `Nh`  — every N hours   (N > 0)
+ *   `Nd`  — every N days    (currently supports 1d; multi-day uses
+ *           "at midnight every day" since cron doesn't natively
+ *           express "every 2 days" without a workaround)
+ *   `N`   — bare number, interpreted as minutes
+ *
+ * Throws on malformed input or zero/negative intervals so the CLI
+ * can surface a clear error.
+ */
+export declare function parseIntervalSpec(spec: string): string;
+export interface ClaudePSpawnOptions {
+    /** Observations per compress-batch-step call. Default 100. */
+    limit?: number;
+    /** Dollar cap on the claude -p invocation. Default 2.00. */
+    maxBudgetUsd?: number;
+    /** Model alias. Default "sonnet" — fast and cheap for compression. */
+    model?: string;
+    /** Where to write the claude -p log. Default /dev/null. */
+    logPath?: string;
+}
+/**
+ * Assemble the shell command that a cron tick runs to drive Phase 2
+ * compression via `claude -p`. The command is a single string suitable
+ * for a crontab line or a shell -c invocation.
+ *
+ * Security contract: --allowedTools restricts the spawn to the yith
+ * MCP tools only, so a runaway prompt can't shell out / edit files /
+ * read arbitrary code. --max-budget-usd caps the total API spend per
+ * tick. --permission-mode auto skips interactive prompts.
+ *
+ * The embedded prompt tells the spawned Claude to call
+ * mem::compress-batch-step in a loop via the work-packet protocol,
+ * terminating when the response is {status: "success"} or after 20
+ * rounds (safety cap).
+ */
+export declare function buildClaudePSpawnCommand(opts?: ClaudePSpawnOptions): string;
+export interface CrontabLineOptions {
+    /** 5-field cron schedule string, e.g. `0 * * * *`. */
+    schedule: string;
+    /** Command to run on each tick. */
+    command: string;
+}
+/**
+ * Build a full crontab line including the installer marker. The marker
+ * is a trailing comment so the line looks like a normal cron entry to
+ * operators who inspect their crontab.
+ */
+export declare function buildCrontabLine(opts: CrontabLineOptions): string;
+/**
+ * Merge `newLine` into an existing crontab file body, replacing any
+ * previous bind entry (identified by BIND_CRON_MARKER) in place. If
+ * no previous entry exists, appends. Preserves all other lines
+ * unchanged — including comments, whitespace, and unrelated jobs.
+ *
+ * Returns the updated crontab body as a string. Callers pipe this
+ * to `crontab -` to commit.
+ */
+export declare function installCrontabEntry(existing: string, newLine: string): string;
+//# sourceMappingURL=bind-cron.d.ts.map

package/dist/cli/bind-cron.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bind-cron.d.ts","sourceRoot":"","sources":["../../src/cli/bind-cron.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;yBAEyB;AACzB,eAAO,MAAM,gBAAgB,4BAA4B,CAAA;AAMzD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAiCtD;AAMD,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,GAAE,mBAAwB,GAC7B,MAAM,CA0BR;AAYD,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAA;IAChB,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAEjE;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,MAAM,CA8BR"}

package/dist/cli/bind-cron.js

@@ -0,0 +1,161 @@
+/**
+ * Cron installer + `claude -p` spawn-command assembly for unattended
+ * Necronomicon bind / compression.
+ *
+ * Everything here is a pure function over strings — no process
+ * spawning, no crontab mutation, no fs writes. The CLI entry point
+ * orchestrates the actual `crontab -l` / `crontab -` dance; this
+ * module only handles the string-level logic so tests can verify
+ * every edge case without side effects.
+ *
+ * The cron entry calls `oh-my-claudecode bind --resume`, which:
+ *   1. Runs any pending Phase 1 work (filesystem ingestion — no LLM).
+ *   2. For Phase 2 (compression), if an ANTHROPIC_API_KEY is
+ *      configured, routes directly through the in-process LLM
+ *      provider. Otherwise spawns `claude -p` with the command
+ *      produced by `buildClaudePSpawnCommand` below, so Claude Code's
+ *      own subscription auth drives the work-packet loop.
+ */
+/** Suffix appended to every bind-installed crontab entry so the
+ *  installer can find + replace its own line without clobbering
+ *  unrelated entries. */
+export const BIND_CRON_MARKER = "# oh-my-claudecode bind";
+// ============================================================================
+// Interval spec parser
+// ============================================================================
+/**
+ * Convert a short interval spec like `"1h"`, `"30m"`, `"1d"` into a
+ * cron schedule string. Accepts:
+ *
+ *   `Nm`  — every N minutes (N > 0)
+ *   `Nh`  — every N hours   (N > 0)
+ *   `Nd`  — every N days    (currently supports 1d; multi-day uses
+ *           "at midnight every day" since cron doesn't natively
+ *           express "every 2 days" without a workaround)
+ *   `N`   — bare number, interpreted as minutes
+ *
+ * Throws on malformed input or zero/negative intervals so the CLI
+ * can surface a clear error.
+ */
+export function parseIntervalSpec(spec) {
+    if (!spec)
+        throw new Error("parseIntervalSpec: empty interval");
+    const m = spec.match(/^(\d+)([mhd])?$/);
+    if (!m) {
+        throw new Error(`parseIntervalSpec: invalid interval "${spec}" — use Nm / Nh / Nd`);
+    }
+    const n = parseInt(m[1], 10);
+    const unit = m[2] ?? "m";
+    if (!Number.isFinite(n) || n <= 0) {
+        throw new Error(`parseIntervalSpec: interval must be > 0 (got ${n})`);
+    }
+    if (unit === "m") {
+        // Every N minutes. If N divides 60 evenly, use step syntax.
+        if (n >= 60 && n % 60 === 0) {
+            const hours = n / 60;
+            return hours === 1 ? "0 * * * *" : `0 */${hours} * * *`;
+        }
+        return `*/${n} * * * *`;
+    }
+    if (unit === "h") {
+        return n === 1 ? "0 * * * *" : `0 */${n} * * *`;
+    }
+    // Days: run at midnight every N days. Cron doesn't natively support
+    // "every 2 days" so we emit the 1d form only.
+    if (n === 1)
+        return "0 0 * * *";
+    // Fall back to "every N-th day of month" — not perfect but better
+    // than refusing the input.
+    return `0 0 */${n} * *`;
+}
+/**
+ * Assemble the shell command that a cron tick runs to drive Phase 2
+ * compression via `claude -p`. The command is a single string suitable
+ * for a crontab line or a shell -c invocation.
+ *
+ * Security contract: --allowedTools restricts the spawn to the yith
+ * MCP tools only, so a runaway prompt can't shell out / edit files /
+ * read arbitrary code. --max-budget-usd caps the total API spend per
+ * tick. --permission-mode auto skips interactive prompts.
+ *
+ * The embedded prompt tells the spawned Claude to call
+ * mem::compress-batch-step in a loop via the work-packet protocol,
+ * terminating when the response is {status: "success"} or after 20
+ * rounds (safety cap).
+ */
+export function buildClaudePSpawnCommand(opts = {}) {
+    const limit = opts.limit ?? 100;
+    const maxBudgetUsd = opts.maxBudgetUsd ?? 2.0;
+    const model = opts.model ?? "sonnet";
+    const logPath = opts.logPath ?? "/dev/null";
+    const prompt = `Call yith_trigger with name "mem::compress-batch-step" and args {"limit": ${limit}}. ` +
+        `If the response has status "needs_llm_work", execute each packet's prompts ` +
+        `(read the systemPrompt + userPrompt, produce the compression XML the system ` +
+        `prompt asks for), then call yith_commit_work with the continuation token and ` +
+        `an array of {id, completion} results. Repeat this loop until the response is ` +
+        `{status: "success"} or you've processed 20 batches total. Output a single-line ` +
+        `JSON summary {"compressed": N, "failed": N, "errors": []} and exit.`;
+    return [
+        `claude`,
+        `--print`,
+        `--permission-mode auto`,
+        `--max-budget-usd ${maxBudgetUsd}`,
+        `--model ${model}`,
+        `--allowedTools "mcp__yith-archive__yith_trigger,mcp__yith-archive__yith_commit_work"`,
+        `--output-format json`,
+        `${shellEscapeSingle(prompt)}`,
+        `>> ${logPath} 2>&1`,
+    ].join(" ");
+}
+function shellEscapeSingle(s) {
+    // Wrap in single quotes and escape any literal single quote the
+    // shell-safe way: '...''...'...
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Build a full crontab line including the installer marker. The marker
+ * is a trailing comment so the line looks like a normal cron entry to
+ * operators who inspect their crontab.
+ */
+export function buildCrontabLine(opts) {
+    return `${opts.schedule} ${opts.command} ${BIND_CRON_MARKER}`;
+}
+/**
+ * Merge `newLine` into an existing crontab file body, replacing any
+ * previous bind entry (identified by BIND_CRON_MARKER) in place. If
+ * no previous entry exists, appends. Preserves all other lines
+ * unchanged — including comments, whitespace, and unrelated jobs.
+ *
+ * Returns the updated crontab body as a string. Callers pipe this
+ * to `crontab -` to commit.
+ */
+export function installCrontabEntry(existing, newLine) {
+    const lines = existing.split("\n");
+    const out = [];
+    let replaced = false;
+    for (const line of lines) {
+        if (line.includes(BIND_CRON_MARKER)) {
+            if (!replaced) {
+                out.push(newLine);
+                replaced = true;
+            }
+            // Drop duplicate bind entries.
+            continue;
+        }
+        out.push(line);
+    }
+    if (!replaced) {
+        // Make sure we don't leave a trailing empty line + the new entry
+        // mashed together. Trim trailing blank lines before appending.
+        while (out.length > 0 && out[out.length - 1] === "") {
+            out.pop();
+        }
+        out.push(newLine);
+    }
+    // Ensure trailing newline — crontabs want it.
+    let body = out.join("\n");
+    if (!body.endsWith("\n"))
+        body += "\n";
+    return body;
+}
+//# sourceMappingURL=bind-cron.js.map

package/dist/cli/bind-cron.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bind-cron.js","sourceRoot":"","sources":["../../src/cli/bind-cron.ts"],"names":[],"mappings":"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"}

package/dist/cli/bind.d.ts

@@ -0,0 +1,102 @@
+/**
+ * oh-my-claudecode bind — the CLI subcommand that drives the
+ * Necronomicon binding ritual.
+ *
+ * Architecture: a state-machine runner (`runBind`) reads `KV.bindState`,
+ * walks through each phase in `BIND_PHASE_ORDER`, invokes the matching
+ * `PhaseRunner`, and persists progress after every transition. Phases
+ * are injectable — tests pass fakes; production passes the real
+ * runners defined in `defaultPhaseRunners()`.
+ *
+ * Failure semantics: if any phase throws, `runBind` records the error
+ * into bindState, halts (does NOT run subsequent phases), and returns.
+ * The CLI entry point surfaces the error via the TUI and exits with
+ * a non-zero code. A re-run picks up from the failed phase and retries
+ * it — the state machine treats `failed` the same as `pending`.
+ *
+ * Cron-friendly: the same entry point is called from `bind --resume`
+ * which prints to stdout and exits, so a crontab can invoke it on
+ * an interval without an interactive session.
+ */
+import type { YithArchiveHandle } from "../features/yith-archive/index.js";
+import { type BindPhase, type BindState } from "../features/yith-archive/state/bind-state.js";
+import { TuiWriter } from "./tui.js";
+export interface BindContext {
+    archive: YithArchiveHandle;
+    tui: TuiWriter;
+    /**
+     * Absolute project cwd to scope work to, when the caller wants a
+     * narrow run. Set by the Stop-hook capture path so each assistant-
+     * response tick only scans the current session's project's
+     * transcripts rather than every project under `~/.claude/projects/`.
+     * Undefined means "all projects" (the full bind default).
+     */
+    projectCwd?: string;
+}
+export interface PhaseRunner {
+    name: BindPhase;
+    /**
+     * Execute the phase's work. Return a details object to merge into
+     * the phase's `details` field (e.g., per-project counts, cursor
+     * positions). Throw on failure — the runner catches and records
+     * the error into bindState for you.
+     */
+    run(ctx: BindContext): Promise<{
+        details?: Record<string, unknown>;
+    }>;
+}
+export interface RunBindOptions {
+    archive: YithArchiveHandle;
+    tui: TuiWriter;
+    /**
+     * Phase implementations. Defaults to `defaultPhaseRunners()` when
+     * omitted. Tests pass fakes to drive the state machine without
+     * hitting the real embedding / backfill / opencode paths.
+     */
+    phases?: PhaseRunner[];
+    /**
+     * When set, runs only the listed phases (even if they're already
+     * completed). Used by `bind --force <phase>` to re-run a specific
+     * phase without touching the others. Default: respect bindState.
+     */
+    force?: BindPhase[];
+    /**
+     * Narrow the runner to a specific subset of phases. Phases NOT in
+     * this list are neither run nor marked complete — their bindState
+     * stays untouched so the next full `bind` invocation still treats
+     * them as pending. Used by `--claude-only` / `--compress-only`
+     * flags and by the Stop hook to run a fast tick without re-doing
+     * unrelated work.
+     */
+    onlyPhases?: BindPhase[];
+    /**
+     * Absolute project cwd to pass through to phase runners via
+     * `BindContext.projectCwd`. The default `claude_transcripts`
+     * runner uses this to scope transcript ingestion to one project
+     * instead of scanning every `~/.claude/projects/` subdir.
+     */
+    projectCwd?: string;
+}
+/**
+ * State-machine driver. Reads bindState, runs pending phases in order,
+ * persists progress after each, halts on first failure.
+ *
+ * Returns the final BindState so callers (the CLI entry point) can
+ * summarize what happened and exit with the right code.
+ */
+export declare function runBind(opts: RunBindOptions): Promise<BindState>;
+/**
+ * Production phase runners. Tests inject fakes; the CLI entry point
+ * uses these defaults.
+ *
+ * Each runner is a thin wrapper that calls the underlying feature
+ * (provider warmup, backfill function, opencode importer, etc.) and
+ * reports progress via the context's TUI writer.
+ *
+ * Phases B, C, and D (opencode_import, sisyphus_migrate,
+ * preliminary_seed) currently register placeholders that log a
+ * "pending implementation" status and complete without work. They
+ * get real implementations in their respective phase files.
+ */
+export declare function defaultPhaseRunners(): PhaseRunner[];
+//# sourceMappingURL=bind.d.ts.map

package/dist/cli/bind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bind.d.ts","sourceRoot":"","sources":["../../src/cli/bind.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAA;AAO1E,OAAO,EAKL,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,8CAA8C,CAAA;AACrD,OAAO,EACL,SAAS,EAMV,MAAM,UAAU,CAAA;AAMjB,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,iBAAiB,CAAA;IAC1B,GAAG,EAAE,SAAS,CAAA;IACd;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,SAAS,CAAA;IACf;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAA;CACtE;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,iBAAiB,CAAA;IAC1B,GAAG,EAAE,SAAS,CAAA;IACd;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,EAAE,CAAA;IACtB;;;;OAIG;IACH,KAAK,CAAC,EAAE,SAAS,EAAE,CAAA;IACnB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,SAAS,EAAE,CAAA;IACxB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAwBD;;;;;;GAMG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,CAAC,CAiKtE;AA4DD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,IAAI,WAAW,EAAE,CA8VnD"}