@crouton-kit/crouter 0.3.8 → 0.3.12

package/dist/core/spawn.js

@@ -1,18 +1,11 @@
-// Tmux pane spawning machinery for crtr job subtree.
+// Tmux pane detach helpers.
 //
-// Kept: spawnAgent (fire-and-forget new pane), spawnAndDetach (detach + kill originating pane),
-//       shellQuote, isInTmux, countPanesInCurrentWindow, findWindowWithSpace.
-//
-// Removed: createSession, submitToSession, awaitSession, waitForResult,
-//          sessionDirForId, writeSessionMeta, readSessionMeta — all superseded
-//          by the jobs.ts sidecar model (result.json + log.jsonl).
-//
-// Crash detection: the wrapper shell command is:
-//   `claude --dangerously-skip-permissions <prompt>; crtr job _fail <job_id>`
-// If the worker calls `crtr job submit` before claude exits, result.json is
-// written and `_fail` is a no-op (writeResult is idempotent for done status).
-// If claude dies without a submit, `_fail` writes status 'failed'. Either way
-// `job read result` sees a terminal result.json.
+// A small set of tmux primitives used by the `human` command tree to put the
+// humanloop TUI in a detached pane: spawnAndDetach (open a pane running a given
+// command), countPanesInCurrentWindow (placement decision), plus shellQuote and
+// isInTmux. The canvas runtime has its own one-window-per-node machinery in
+// core/runtime/tmux.ts; this module is only the pane-split path the human TUI
+// needs.
 import { spawnSync } from 'node:child_process';
 export function isInTmux() {
     return Boolean(process.env.TMUX);
@@ -20,6 +13,7 @@ export function isInTmux() {
 export function shellQuote(s) {
     return `'${s.replace(/'/g, "'\\''")}'`;
 }
+/** Count panes in the current tmux window (0 outside tmux / on error). */
 export function countPanesInCurrentWindow() {
     const result = spawnSync('tmux', ['list-panes', '-F', '#{pane_id}'], {
         encoding: 'utf8',
@@ -28,126 +22,10 @@ export function countPanesInCurrentWindow() {
         return 0;
     return result.stdout.split('\n').filter((line) => line.trim() !== '').length;
 }
-function listWindowsInCurrentSession() {
-    const result = spawnSync('tmux', ['list-windows', '-F', '#{window_id} #{window_panes} #{window_active}'], { encoding: 'utf8' });
-    if (result.status !== 0)
-        return [];
-    return result.stdout
-        .split('\n')
-        .filter((line) => line.trim() !== '')
-        .map((line) => {
-        const [id, count, active] = line.split(' ');
-        return {
-            windowId: id,
-            paneCount: Number.parseInt(count, 10),
-            isActive: active === '1',
-        };
-    });
-}
-/**
- * Map of window_id → list of pane TTYs (basename, e.g. `ttys008`) for every
- * pane in the current tmux session. Used as the bridge between tmux's pane
- * model and the system process table for foreground-command lookup.
- *
- * tmux's `#{pane_current_command}` is unreliable on macOS because the Claude
- * Code CLI sets `process.title` to its version (e.g. `2.1.143`), which is what
- * tmux then reports. Going through the TTY + `ps` gives us the real binary
- * name (`claude`) from the kernel.
- */
-function paneTtysByWindow() {
-    const result = spawnSync('tmux', ['list-panes', '-s', '-F', '#{window_id} #{pane_tty}'], { encoding: 'utf8' });
-    const out = new Map();
-    if (result.status !== 0)
-        return out;
-    for (const line of result.stdout.split('\n')) {
-        if (line.trim() === '')
-            continue;
-        const idx = line.indexOf(' ');
-        if (idx === -1)
-            continue;
-        const windowId = line.slice(0, idx);
-        const tty = line.slice(idx + 1);
-        const ttyBase = tty.startsWith('/dev/') ? tty.slice(5) : tty;
-        const existing = out.get(windowId);
-        if (existing === undefined) {
-            out.set(windowId, [ttyBase]);
-        }
-        else {
-            existing.push(ttyBase);
-        }
-    }
-    return out;
-}
-/**
- * Map of tty basename → set of foreground process `comm` names on that tty.
- * A process is "foreground" if its STAT field includes `+` (member of the
- * terminal's foreground process group). Built from one `ps -axo ...` call.
- */
-function foregroundCommsByTty() {
-    const result = spawnSync('ps', ['-axo', 'stat=,comm=,tty='], { encoding: 'utf8' });
-    const out = new Map();
-    if (result.status !== 0)
-        return out;
-    for (const line of result.stdout.split('\n')) {
-        if (line.trim() === '')
-            continue;
-        const m = line.match(/^(\S+)\s+(.+?)\s+(\S+)\s*$/);
-        if (m === null)
-            continue;
-        const [, stat, comm, tty] = m;
-        if (!stat.includes('+'))
-            continue;
-        if (tty === '??' || tty === '?')
-            continue;
-        const existing = out.get(tty);
-        if (existing === undefined) {
-            out.set(tty, new Set([comm.trim()]));
-        }
-        else {
-            existing.add(comm.trim());
-        }
-    }
-    return out;
-}
-/**
- * Find a window in the current tmux session with fewer than `maxPanesPerWindow`
- * panes AND where every existing pane has `claude` as a foreground process.
- * Prefers the active window so the spawned pane is visible to the user;
- * otherwise falls back to the first other eligible window. Returns the tmux
- * window id (e.g. `@5`) to pass via `-t`, or null if no window qualifies.
- *
- * Windows holding non-agent panes (dashboards, log tails, idle shells, editors,
- * REPLs, etc.) are skipped so spawning never disrupts those workflows. A pane
- * qualifies as long as `claude` is among its foreground commands — co-resident
- * helpers like `caffeinate` don't disqualify it.
- */
-export function findWindowWithSpace(maxPanesPerWindow) {
-    const windows = listWindowsInCurrentSession();
-    const ttysByWindow = paneTtysByWindow();
-    const fgByTty = foregroundCommsByTty();
-    const isClaudeOnly = (windowId) => {
-        const ttys = ttysByWindow.get(windowId);
-        if (ttys === undefined || ttys.length === 0)
-            return false;
-        return ttys.every((tty) => fgByTty.get(tty)?.has('claude') === true);
-    };
-    const eligible = windows.filter((w) => w.paneCount < maxPanesPerWindow && isClaudeOnly(w.windowId));
-    const active = eligible.find((w) => w.isActive);
-    if (active !== undefined)
-        return active.windowId;
-    const first = eligible[0];
-    if (first === undefined)
-        return null;
-    return first.windowId;
-}
 /**
  * Schedule a kill-pane on the *current* tmux pane after `delaySeconds`, detached
- * so the caller can return normally before the pane dies. No-op outside tmux
- * or when TMUX_PANE is unset.
- *
- * Used by `crtr job submit` (kill_pane=true) so a reviewer agent can self-close
- * its pane after delivering its verdict, and by `spawnAndDetach` for handoff
- * self-kill.
+ * so the caller can return normally before the pane dies. No-op outside tmux,
+ * when TMUX_PANE is unset, or when delaySeconds <= 0.
  */
 export function scheduleKillCurrentPane(delaySeconds) {
     const currentPane = process.env.TMUX_PANE;
@@ -161,24 +39,9 @@ export function scheduleKillCurrentPane(delaySeconds) {
     return true;
 }
 /**
- * Build the wrapper shell command passed to the tmux pane.
- *
- * Pattern: `claude <args>; crtr job _fail <job_id>`
- *
- * If the worker submits via `crtr job submit` before claude exits,
- * result.json is already written (`done`); `_fail` sees it and is a no-op.
- * If claude crashes/exits without submitting, `_fail` writes status `failed`
- * so `job read result` can distinguish completion from crash.
- */
-function wrapperCmd(claudeCmd, jobId) {
-    return `${claudeCmd}; crtr job _fail ${shellQuote(jobId)}`;
-}
-/**
- * Fire-and-forget: launch an interactive `claude` in a new pane (or window),
- * then schedule the originating pane to be killed after `killAfterSeconds`.
- *
- * No custom system prompt — the task is delivered as the first user message.
- * Returns as soon as the new pane is up; does NOT wait for claude to finish.
+ * Fire-and-forget: launch `opts.command` in a new pane (or window), then
+ * schedule the originating pane to be killed after `killAfterSeconds`. Returns
+ * as soon as the new pane is up; does NOT wait for the command to finish.
  */
 export function spawnAndDetach(opts) {
     if (!isInTmux()) {
@@ -187,17 +50,6 @@ export function spawnAndDetach(opts) {
             message: 'handoff requires tmux (TMUX env var not set)',
         };
     }
-    const buildClaudeInner = () => {
-        const parts = ['claude'];
-        if (opts.name !== undefined && opts.name !== '') {
-            parts.push('-n', shellQuote(opts.name));
-        }
-        parts.push('--dangerously-skip-permissions', shellQuote(opts.prompt));
-        return parts.join(' ');
-    };
-    const inner = opts.command !== undefined ? opts.command : buildClaudeInner();
-    const useFailGuard = opts.failGuard !== false;
-    const fullCmd = useFailGuard ? wrapperCmd(inner, opts.jobId) : inner;
     const splitArgs = [];
     if (opts.placement === 'new-window') {
         splitArgs.push('new-window');
@@ -218,7 +70,7 @@ export function spawnAndDetach(opts) {
     if (opts.jobId !== undefined) {
         splitArgs.push('-e', `CRTR_JOB_ID=${opts.jobId}`);
     }
-    splitArgs.push(fullCmd);
+    splitArgs.push(opts.command);
     const split = spawnSync('tmux', splitArgs, { encoding: 'utf8' });
     if (split.status !== 0) {
         const stderrText = split.stderr.trim();
@@ -231,62 +83,6 @@ export function spawnAndDetach(opts) {
     return {
         status: 'spawned',
         paneId,
-        message: `handed off to pane ${paneId}; this pane will close in ${opts.killAfterSeconds}s`,
-    };
-}
-/**
- * Async sibling spawn. Launches a claude session in a tmux pane, progressively
- * filling existing windows up to `maxPanesPerWindow` before creating a new
- * window. Returns immediately with the pane id; the parent stays alive.
- *
- * Placement order:
- *   1. Current window, if it has space.
- *   2. Any other window in the session with space.
- *   3. New window (every existing window at capacity).
- *
- * If `fork` is set, uses `claude --resume <id> --fork-session`.
- */
-export function spawnAgent(opts) {
-    if (!isInTmux()) {
-        return {
-            status: 'not-in-tmux',
-            message: 'crtr job requires tmux (TMUX env var not set)',
-        };
-    }
-    const claudeParts = ['claude'];
-    if (opts.name !== undefined && opts.name !== '') {
-        claudeParts.push('-n', shellQuote(opts.name));
-    }
-    if (opts.fork !== undefined) {
-        claudeParts.push('--resume', opts.fork.sessionId, '--fork-session');
-    }
-    claudeParts.push('--dangerously-skip-permissions', shellQuote(opts.prompt));
-    const claudeCmd = claudeParts.join(' ');
-    const fullCmd = wrapperCmd(claudeCmd, opts.jobId);
-    const targetWindow = findWindowWithSpace(opts.maxPanesPerWindow);
-    const placement = targetWindow === null ? 'new-window' : 'split-window';
-    const tmuxArgs = [placement];
-    if (placement === 'split-window') {
-        tmuxArgs.push('-h', '-t', targetWindow);
-    }
-    tmuxArgs.push('-P', '-F', '#{pane_id}', '-c', opts.cwd, '-e', `CRTR_JOB_ID=${opts.jobId}`, fullCmd);
-    const split = spawnSync('tmux', tmuxArgs, { encoding: 'utf8' });
-    if (split.status !== 0) {
-        const stderrText = split.stderr.trim();
-        const msg = stderrText === '' ? `tmux ${placement} failed` : stderrText;
-        return { status: 'spawn-failed', message: msg };
-    }
-    const paneId = split.stdout.trim();
-    // Re-balance the target window's panes evenly so the new pane doesn't end up
-    // half the size of its siblings. -t <pane_id> resolves to the window it lives
-    // in for both placements (split + new-window).
-    spawnSync('tmux', ['select-layout', '-t', paneId, 'even-horizontal'], {
-        encoding: 'utf8',
-    });
-    return {
-        status: 'spawned',
-        paneId,
-        placement,
-        message: `agent spawned in pane ${paneId} (${placement})`,
+        message: `handed off to pane ${paneId}`,
     };
 }

package/dist/daemon/crtrd-cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/daemon/crtrd-cli.js

@@ -0,0 +1,4 @@
+// crtrd entry point — spawned detached by `crtr canvas daemon start` and by bin/crtrd.
+// Calls runDaemon() and never returns (the loop drives via setTimeout).
+import { runDaemon } from './crtrd.js';
+runDaemon();

package/dist/daemon/crtrd.d.ts

@@ -0,0 +1,20 @@
+/** Read the pid stored in the pidfile, or null if absent / malformed. */
+export declare function readPidfile(): number | null;
+/** True if a process with `pid` is currently alive (signal-0 probe). */
+export declare function isPidAlive(pid: number): boolean;
+/** True when a crtrd process is already running (pidfile exists + pid alive). */
+export declare function isDaemonRunning(): boolean;
+export interface DaemonOpts {
+    /** Milliseconds between supervision polls. Default 2000. */
+    intervalMs?: number;
+}
+/** Start the supervisor loop.
+ *
+ *  If a live crtrd is already running (pidfile + pid alive), exits immediately
+ *  (exit 0 — idempotent, not an error). Otherwise, writes the pidfile, sets up
+ *  signal handlers, and enters the poll loop.
+ *
+ *  Returns a teardown callback that stops the loop and removes the pidfile.
+ *  (Mainly useful for tests; in production the daemon runs until signaled.) */
+export declare function runDaemon(opts?: DaemonOpts): () => void;
+export default runDaemon;

package/dist/daemon/crtrd.js

@@ -0,0 +1,200 @@
+// crtrd — the thin supervisor daemon. One instance per canvas.
+//
+// Sole responsibility: supervise tmux window exit and revive nodes. No
+// orchestration logic lives here. The daemon is a process-lifecycle watcher.
+//
+// Model
+//   • Poll every intervalMs (default 2000ms).
+//   • For each active|idle node: check whether its tmux window is still alive.
+//   • Window alive → healthy, skip.
+//   • Window gone + intent==='refresh' → fresh respawn (node asked to yield).
+//   • Window gone + intent==='idle-release' → node freed its own pane while
+//     dormant; clear the stale window ref and revive (resume) when its inbox
+//     gains an unseen entry.
+//   • Window gone + any other intent → crash: mark 'dead'.
+//   • Nodes with no tmux placement (inline roots) are skipped.
+//
+// Single-instance guarantee
+//   A PID file at crtrHome()/crtrd.pid prevents double-runs. On start, if the
+//   file exists and the recorded pid is alive, we refuse to start (exit 0).
+//   On stop (SIGINT/SIGTERM/exit) we remove the file.
+import { writeFileSync, readFileSync, rmSync, existsSync, mkdirSync, } from 'node:fs';
+import { join } from 'node:path';
+import { crtrHome } from '../core/canvas/paths.js';
+import { listNodes, setStatus, getNode, updateNode, } from '../core/canvas/index.js';
+import { windowAlive } from '../core/runtime/tmux.js';
+import { reviveNode } from '../core/runtime/revive.js';
+import { readInboxSince, readCursor } from '../core/feed/inbox.js';
+const DEFAULT_INTERVAL_MS = 2000;
+// ---------------------------------------------------------------------------
+// Pidfile
+// ---------------------------------------------------------------------------
+function pidfilePath() {
+    return join(crtrHome(), 'crtrd.pid');
+}
+function writePidfile() {
+    // Ensure the canvas home exists before writing.
+    mkdirSync(crtrHome(), { recursive: true });
+    writeFileSync(pidfilePath(), String(process.pid), 'utf8');
+}
+function removePidfile() {
+    try {
+        rmSync(pidfilePath());
+    }
+    catch {
+        // Already gone — nothing to do.
+    }
+}
+/** Read the pid stored in the pidfile, or null if absent / malformed. */
+export function readPidfile() {
+    const p = pidfilePath();
+    if (!existsSync(p))
+        return null;
+    const raw = readFileSync(p, 'utf8').trim();
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : null;
+}
+/** True if a process with `pid` is currently alive (signal-0 probe). */
+export function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** True when a crtrd process is already running (pidfile exists + pid alive). */
+export function isDaemonRunning() {
+    const pid = readPidfile();
+    return pid !== null && isPidAlive(pid);
+}
+// ---------------------------------------------------------------------------
+// Supervisor tick
+// ---------------------------------------------------------------------------
+async function superviseTick() {
+    let rows;
+    try {
+        rows = listNodes({ status: ['active', 'idle'] });
+    }
+    catch (err) {
+        process.stderr.write(`[crtrd] listNodes error: ${err.message}\n`);
+        return;
+    }
+    for (const row of rows) {
+        try {
+            // listNodes returns the lightweight NodeRow; we need the full NodeMeta
+            // for tmux_session, window, intent, and pi_session_id.
+            const meta = getNode(row.node_id);
+            if (meta === null)
+                continue; // vanished between list and get
+            // Nodes without tmux placement are inline roots — not daemon-managed.
+            if (meta.tmux_session == null || meta.window == null)
+                continue;
+            if (windowAlive(meta.tmux_session, meta.window))
+                continue; // healthy
+            // Window is gone. Branch on why.
+            if (meta.intent === 'refresh') {
+                // The node set intent=refresh before stopping — a clean yield. Respawn
+                // fresh so it re-reads its roadmap/context dir.
+                process.stderr.write(`[crtrd] revive ${row.node_id} (refresh-yield)\n`);
+                reviveNode(row.node_id, { resume: false });
+            }
+            else if (meta.intent === 'idle-release') {
+                // The node freed its own window on purpose while dormant. Drop the stale
+                // window ref and keep it 'idle'; the inbox-poll pass below revives it
+                // (resume) the moment a subscribed worker delivers.
+                updateNode(row.node_id, { window: null });
+            }
+            else {
+                // Window vanished without the node completing or refreshing — a crash.
+                process.stderr.write(`[crtrd] dead ${row.node_id} (window gone, intent=${String(meta.intent)})\n`);
+                setStatus(row.node_id, 'dead');
+            }
+        }
+        catch (err) {
+            // One bad node must never kill the loop.
+            process.stderr.write(`[crtrd] error supervising ${row.node_id}: ${err.message}\n`);
+        }
+    }
+    // Second pass: revive idle-released nodes whose inbox has unseen entries.
+    // The in-process inbox-watcher dies with pi, so the daemon owns wake-on-message
+    // for dormant nodes. readCursor is the cursor the watcher persisted before
+    // exit; any entry past it is undelivered work — resume the node to handle it.
+    for (const row of rows) {
+        try {
+            const meta = getNode(row.node_id);
+            if (meta === null)
+                continue;
+            if (meta.status !== 'idle' || meta.intent !== 'idle-release')
+                continue;
+            // If a window is somehow alive, the in-process watcher owns delivery.
+            if (meta.window != null && windowAlive(meta.tmux_session ?? '', meta.window)) {
+                continue;
+            }
+            const entries = readInboxSince(row.node_id, readCursor(row.node_id));
+            if (entries.length > 0) {
+                process.stderr.write(`[crtrd] revive ${row.node_id} (idle-release, inbox)\n`);
+                reviveNode(row.node_id, { resume: true });
+            }
+        }
+        catch (err) {
+            process.stderr.write(`[crtrd] error polling inbox ${row.node_id}: ${err.message}\n`);
+        }
+    }
+}
+/** Start the supervisor loop.
+ *
+ *  If a live crtrd is already running (pidfile + pid alive), exits immediately
+ *  (exit 0 — idempotent, not an error). Otherwise, writes the pidfile, sets up
+ *  signal handlers, and enters the poll loop.
+ *
+ *  Returns a teardown callback that stops the loop and removes the pidfile.
+ *  (Mainly useful for tests; in production the daemon runs until signaled.) */
+export function runDaemon(opts = {}) {
+    if (isDaemonRunning()) {
+        const pid = readPidfile();
+        process.stderr.write(`[crtrd] already running (pid ${pid ?? '?'})\n`);
+        process.exit(0);
+    }
+    const interval = opts.intervalMs ?? DEFAULT_INTERVAL_MS;
+    writePidfile();
+    process.stderr.write(`[crtrd] started (pid ${process.pid}, interval ${interval}ms)\n`);
+    let running = true;
+    // Cleanup — idempotent.
+    const cleanup = () => {
+        removePidfile();
+    };
+    process.on('SIGINT', () => {
+        cleanup();
+        process.exit(0);
+    });
+    process.on('SIGTERM', () => {
+        cleanup();
+        process.exit(0);
+    });
+    process.on('exit', () => {
+        cleanup();
+    });
+    // Recursive setTimeout keeps ticks sequential and avoids overlap on slow
+    // canvases (a timer that fires while a prior tick is awaiting is dropped).
+    const scheduleTick = () => {
+        if (!running)
+            return;
+        superviseTick()
+            .catch((err) => {
+            process.stderr.write(`[crtrd] tick error: ${err.message}\n`);
+        })
+            .finally(() => {
+            if (running)
+                setTimeout(scheduleTick, interval);
+        });
+    };
+    const initialTimer = setTimeout(scheduleTick, interval);
+    return () => {
+        running = false;
+        clearTimeout(initialTimer);
+        cleanup();
+    };
+}
+export default runDaemon;

package/dist/daemon/manage.d.ts

@@ -0,0 +1,17 @@
+export interface SpawnDaemonResult {
+    /** True when a new daemon process was spawned. */
+    started: boolean;
+    /** PID of the newly spawned process, if started. */
+    pid?: number;
+    /** PID of the already-running daemon, if it was already up. */
+    existing_pid?: number;
+}
+/** Spawn crtrd detached. Returns immediately; the child outlives this process.
+ *
+ *  If the daemon is already running, returns {started:false, existing_pid}.
+ *  If spawning fails (e.g. missing dist — run `npm run build` first), throws. */
+export declare function spawnDaemon(): SpawnDaemonResult;
+/** Start the daemon if it is not already running. No-op if already up.
+ *  Silently swallows spawn errors (the canvas still works without the daemon;
+ *  nodes just won't be auto-revived). */
+export declare function ensureDaemon(): void;

package/dist/daemon/manage.js

@@ -0,0 +1,57 @@
+// Daemon management helpers — importable without the full command tree.
+//
+// spawnDaemon() is the low-level spawn call shared by `crtr canvas daemon start` and
+// ensureDaemon(). ensureDaemon() is the silent "start if not running" front-
+// door helper called by the canvas runtime before spawning child nodes.
+import { spawn } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mkdirSync } from 'node:fs';
+import { crtrHome } from '../core/canvas/paths.js';
+import { isDaemonRunning, readPidfile } from './crtrd.js';
+// ---------------------------------------------------------------------------
+// Entry point resolution
+// ---------------------------------------------------------------------------
+/** Resolve the absolute path to the crtrd-cli entry point.
+ *
+ *  At runtime this file is dist/daemon/manage.js; the entry lives at
+ *  dist/daemon/crtrd-cli.js (sibling in the same directory). */
+function resolveCrtrdEntry() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return join(here, 'crtrd-cli.js');
+}
+/** Spawn crtrd detached. Returns immediately; the child outlives this process.
+ *
+ *  If the daemon is already running, returns {started:false, existing_pid}.
+ *  If spawning fails (e.g. missing dist — run `npm run build` first), throws. */
+export function spawnDaemon() {
+    if (isDaemonRunning()) {
+        return { started: false, existing_pid: readPidfile() ?? undefined };
+    }
+    // Ensure the canvas home directory exists so the daemon can write its pidfile.
+    mkdirSync(crtrHome(), { recursive: true });
+    const entry = resolveCrtrdEntry();
+    const child = spawn(process.execPath, [entry], {
+        detached: true,
+        stdio: 'ignore',
+    });
+    const pid = child.pid;
+    child.unref();
+    return { started: true, pid };
+}
+// ---------------------------------------------------------------------------
+// ensureDaemon — fire-and-forget front-door helper
+// ---------------------------------------------------------------------------
+/** Start the daemon if it is not already running. No-op if already up.
+ *  Silently swallows spawn errors (the canvas still works without the daemon;
+ *  nodes just won't be auto-revived). */
+export function ensureDaemon() {
+    try {
+        if (!isDaemonRunning())
+            spawnDaemon();
+    }
+    catch {
+        // Intentionally silent — a missing dist/daemon/crtrd-cli.js (dev mode,
+        // pre-build) must not break the calling command.
+    }
+}

package/dist/pi-extensions/canvas-inbox-watcher.d.ts

@@ -0,0 +1,16 @@
+type PiEvents = 'session_start' | 'turn_end' | 'agent_start' | 'agent_end' | 'session_shutdown';
+interface PiLike {
+    on: (event: PiEvents, handler: (event: any, ctx: any) => void | Promise<void>) => void;
+    sendUserMessage: (content: string, options?: {
+        deliverAs?: 'steer' | 'followUp';
+    }) => void;
+}
+/**
+ * Register the canvas inbox watcher on `pi`.
+ *
+ * CRTR_NODE_ID is re-read each tick so late-injected env (edge case) is
+ * handled gracefully. Returns a disposer for testability; pi ignores it —
+ * the module-level liveTimer guard is the actual stacking prevention.
+ */
+export declare function registerCanvasInboxWatcher(pi: PiLike): () => void;
+export default registerCanvasInboxWatcher;