oh-my-claudecode 0.2.1 → 0.2.4

package/README.md

@@ -61,7 +61,7 @@ These aren't three plugins you pick and choose. They're one integrated system th
 | **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 |
-| **9 slash commands** | Direct-invoke any mode or flow from the Claude Code chat bar |
+| **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 |
 | **3-level config** | Defaults → user (`~/.claude/oh-my-claudecode.jsonc`) → project (`.claude/...`) with Zod validation and partial parsing |
@@ -140,10 +140,57 @@ Named for the Great Race of Yith from *The Shadow Out of Time* — mind-transfer
 - **Exposed as an MCP server** — during `install`, Yith Archive is registered with Claude Code as a stdio MCP server named `yith-archive`. Sessions get 7 tools: `yith_remember`, `yith_search`, `yith_recall`, `yith_context`, `yith_observe`, `yith_commit_work`, and `yith_trigger` (escape hatch for ~90 advanced memory functions, with a curated top-20 catalog embedded in the tool description).
 - **Rich memory primitives** — `remember`, `search`, `recall`, `context`, `observe`, plus dozens more under the hood: consolidation pipelines, temporal graph retrieval, lesson crystallization, pattern extraction, eviction and retention policies, file-scoped memory index, sliding window compression, query expansion, working memory, session timeline, export/import.
 - **Automatic capture** — notable events during a session can be observed into the archive; a background consolidation pass merges similar memories into distilled lessons.
-- **Zero external runtime** — file-backed JSON storage under `~/.oh-my-claudecode/yith/store.json`. Atomic writes via tmpfile + rename so a crash mid-write can't corrupt the store. No database, no background server, no subprocess, no network, no ports to manage.
+- **Zero external runtime** — file-backed JSON storage at `~/.oh-my-claudecode/yith/necronomicon.json` (legacy installs are auto-migrated from `store.json` on boot). Atomic writes via tmpfile + rename so a crash mid-write can't corrupt the tome. No database, no background server, no subprocess, no network, no ports to manage. The MCP server itself is registered user-level in `~/.claude.json`.
 - **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,6 +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) |
+| `/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 |

package/commands/cthulhu.md

@@ -7,6 +7,15 @@ Activate Cthulhu orchestrator mode.
 
 **First**: ensure `.elder-gods/` exists at the project root. If it does not, create it now (empty is fine — `mkdir .elder-gods`). This marker makes every future Claude Code session in this project auto-activate Cthulhu via the `cthulhu-auto` SessionStart hook, so the user will not need to run `/cthulhu` again here. If the directory already exists, proceed silently.
 
+**Second — Necronomicon preflight**: before accepting the user's request, verify that the Yith Archive memory system is bound on this machine. Run ONE lightweight check:
+
+- Try calling `yith_context({ project: "." })` (the Yith MCP tool).
+- If the tool **is not available at all** (no `yith_context` in your tool list), or if the call errors with "MCP server not connected" / similar, the Necronomicon has not been bound yet.
+- In that case, tell the user exactly: "I notice the Necronomicon hasn't been bound on this machine yet. Run `/bind-necronomicon` first — it's a one-time setup ritual that verifies the MCP server, warms up the embedding model, and optionally backfills past sessions. After that, every Cthulhu session will have persistent memory across projects. Run `/bind-necronomicon` now, or proceed without memory for this session?" Wait for the user's decision before doing anything else.
+- If the tool call succeeds (even with empty context), proceed silently — the Necronomicon is ready.
+
+Do this preflight exactly once per session, not before every user message.
+
 You are now operating as Cthulhu, the Great Dreamer — primary orchestrator of the oh-my-claudecode system.
 
 Your operating principles:

package/commands/necronomicon-bind.md

@@ -0,0 +1,106 @@
+---
+name: bind-necronomicon
+description: First-run setup ritual for Yith Archive. Verifies the MCP server is reachable, warms up the embedding model, and offers to backfill past Claude Code sessions into the Necronomicon. Safe to run multiple times — it detects what's already done.
+---
+
+You are performing the binding ritual for the **Necronomicon** — the on-disk grimoire that the Great Race of Yith maintains for this machine. The Necronomicon is the physical JSON file at `~/.oh-my-claudecode/yith/necronomicon.json`; Yith Archive is the archival practice that writes to and reads from it. Both names refer to the same system, viewed through different lenses.
+
+Run the ritual in phases. For each phase, print a header line, run the check, and report the outcome with a status glyph (`✓`, `⚠`, `✗`, or `…`) and a short explanation. Do NOT proceed to the next phase until the current one is resolved.
+
+## Phase I — The Tome Exists
+
+Check whether the Necronomicon has been bound on this machine.
+
+1. Use the `yith_context` MCP tool with a placeholder project like `{ project: "." }`. This is a lightweight call that exercises the MCP server without writing anything.
+2. If the tool returns successfully (even with empty context), the server is reachable → `✓ Necronomicon is bound and the Great Race answers.`
+3. If the MCP tool is not available at all (the `yith_trigger`/`yith_context` tools don't appear in your tool list), the MCP server is not registered. Tell the user to run `oh-my-claudecode install` in their terminal, then start a NEW Claude Code session and re-run `/bind-necronomicon`. Stop here.
+4. If the tool is available but errors out, report the error verbatim and stop.
+
+## Phase II — The Embedding Sigil
+
+If this is a fresh install, the local nomic embedding model (~137 MB) has not been downloaded yet. The first memory write or search triggers the download. We'll warm it up explicitly now so the first real use is fast.
+
+1. Call `yith_remember` with a harmless sentinel memory:
+   ```
+   yith_remember({
+     content: "Necronomicon binding sentinel — written during /bind-necronomicon ritual",
+     type: "reference",
+     concepts: ["bind-necronomicon", "sentinel"]
+   })
+   ```
+2. The response may take 30-90 seconds on first call because the nomic model downloads in the background. While you wait, print a progress indicator to the user:
+   ```
+   ▓▓▓▓▓▓▓▓▓░░░░░░░░ warming up the embedding sigil...
+   ```
+   (Only one frame — you cannot actually animate in a Claude Code session. The single bar communicates "work is happening, this is the expected delay.")
+3. If the call succeeds → `✓ The embedding sigil pulses. Model is cached under ~/.cache/huggingface/.`
+4. If the call fails with a network error, tell the user the nomic download needs internet and offer to skip this phase (BM25-only mode still works). Continue.
+5. If the call fails with a parse or validation error, report it and stop.
+
+## Phase III — Searching the Tome
+
+Verify hybrid search actually returns the sentinel memory we just wrote.
+
+1. Call `yith_search({ query: "Necronomicon binding sentinel", limit: 5 })`.
+2. If the result contains at least one hit referencing the sentinel → `✓ Hybrid search is operational (BM25 + vector index in sync).`
+3. If zero hits but the sentinel is definitely in KV (you can verify with `yith_trigger({ name: "mem::diagnose", args: {} })`), the index is out of sync. Call `yith_trigger({ name: "mem::rebuild-index", args: {} })` if such a function exists, or tell the user to restart their Claude Code session (the MCP server rebuilds the index on boot). Continue.
+
+## Phase IV — Past Sessions (Optional)
+
+The user may have Claude Code transcripts from past sessions on this machine, in `~/.claude/projects/<sanitized-cwd>/*.jsonl`. Offer to backfill them into the Necronomicon so the archive has history from before it existed.
+
+1. Ask the user: "Would you like to backfill past Claude Code sessions into the Necronomicon? This reads your historical `~/.claude/projects/` transcripts and converts user prompts + assistant responses + tool calls into observations that get compressed and made searchable. (yes / skip / specific-project-path)"
+2. If the user says `skip`, note it and move on.
+3. If they say `yes` or provide a path, run:
+   ```
+   yith_trigger({
+     name: "mem::backfill-sessions",
+     args: {
+       projectCwd: <path or "." for cwd>,
+       dryRun: false,
+       maxObservations: 500
+     }
+   })
+   ```
+4. The backfill runs through the work-packet loop. Each compression round will return a `needs_llm_work` envelope with one or more packets. For each round:
+   - Run the packets' prompts through your own reasoning (inline — the systemPrompt + userPrompt describe a compression task, you act as the LLM for Yith).
+   - Commit the completions via `yith_commit_work({ continuation, packetResults: [...] })`.
+   - Loop until the response is terminal.
+5. Between rounds, render a progress bar using monospace ASCII:
+   ```
+   [▓▓▓▓▓▓░░░░░░░░░░░░] 34% — 171/500 observations compressed
+   ```
+   Update the numbers in each round's status message. Users can't get an animated bar, but a re-printed bar in each tool call shows forward motion.
+6. Report the final counts from the backfill terminal result.
+
+## Phase V — Sealing the Ritual
+
+1. Print a summary of what was done:
+   ```
+   ═════════════════════════════════════════════════════
+     The Necronomicon is bound.
+   ═════════════════════════════════════════════════════
+     Tome:             ~/.oh-my-claudecode/yith/necronomicon.json
+     MCP server:       yith-archive (reachable)
+     Embedding model:  local:nomic-embed-text-v1.5 (768 dims)
+     Memories:         <count from yith_trigger mem::diagnose>
+     Observations:     <count from yith_trigger mem::diagnose>
+     Backfill:         <yes/skipped + counts>
+   ═════════════════════════════════════════════════════
+     The Great Race of Yith now remembers this machine.
+     Every new Claude Code session will have access to
+     the Necronomicon through yith_search, yith_remember,
+     yith_context, and the other MCP tools.
+   ```
+2. If any phase reported a warning, restate the warnings at the end so the user doesn't miss them.
+
+## Re-entry
+
+This command is idempotent. Running it twice in a row:
+- Phase I passes immediately (MCP reachable)
+- Phase II is a no-op if the embedding model is already cached (the call returns fast)
+- Phase III passes immediately
+- Phase IV offers to backfill again (the user can skip if they already did it)
+- Phase V prints the final summary
+
+Run it any time you want to verify the Necronomicon is still bound.

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,78 @@
+/**
+ * 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;
+}
+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[];
+}
+/**
+ * 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;CACf;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;CACpB;AAwBD;;;;;;GAMG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,CAAC,CAqHtE;AA4DD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,IAAI,WAAW,EAAE,CA+TnD"}