@crouton-kit/crouter 0.3.8 → 0.3.12

package/dist/core/runtime/roadmap.js

@@ -0,0 +1,52 @@
+// The roadmap — one document, two temperatures. A small frozen core (goal +
+// exit criteria) and an evolving body (scope, strategy, active context) the
+// owner keeps current. It holds how you intend to reach the goal and where you
+// are right now — not a journal of what you did or a queue of what's next. It
+// is what lets a resident node survive a refresh-yield: revive with no memory,
+// re-read the map, continue.
+//
+// Written at resident-promotion (a born-resident root, or a spawned node's
+// first refresh-with-open-work). Leaf/terminal workers write nothing.
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { contextDir } from '../canvas/index.js';
+export function roadmapPath(nodeId) {
+    return join(contextDir(nodeId), 'roadmap.md');
+}
+export function hasRoadmap(nodeId) {
+    return existsSync(roadmapPath(nodeId));
+}
+export function readRoadmap(nodeId) {
+    const p = roadmapPath(nodeId);
+    return existsSync(p) ? readFileSync(p, 'utf8') : null;
+}
+/** Seed a fresh roadmap SCAFFOLD. No goal is required — promotion lays this
+ *  down so the file exists for a refresh, and the owner authors the goal +
+ *  body as its next act (guided by its kind's roadmap skill). `goal`/
+ *  `exitCriteria` are optional overrides. Idempotent only if you intend it —
+ *  call sites guard on hasRoadmap to avoid clobbering an evolved map. */
+export function seedRoadmap(nodeId, opts = {}) {
+    const dir = contextDir(nodeId);
+    mkdirSync(dir, { recursive: true });
+    const body = `# Roadmap
+
+<!-- frozen core: set once, rarely changes -->
+## Goal
+${opts.goal?.trim() ?? '- (state the high-level goal you now own — write this as your first act)'}
+
+## Exit criteria
+${opts.exitCriteria?.trim() ?? '- (define what "done" looks like)'}
+
+<!-- evolving body: keep this current as you learn scope + intent -->
+## Scope assumptions / non-goals
+- (record what's out of scope and what's settled — e.g. "reuse existing auth", "security isn't a concern here" — so children inherit the framing)
+
+## Strategy / phases
+- (your high-level shape of how you reach the goal; the ordered phases from here to done, the current one carrying a one-line status. Each phase can become a child whose own roadmap is that phase)
+
+## Active context
+- (the context/ files currently relevant to the work, by path; none yet)
+`;
+    writeFileSync(roadmapPath(nodeId), body);
+    return body;
+}

package/dist/core/runtime/spawn.d.ts

@@ -0,0 +1,33 @@
+import { type NodeMeta, type Mode } from '../canvas/index.js';
+/** A root's tmux session name — its home; every descendant is a window in it. */
+export declare function rootSessionName(rootId: string): string;
+export interface BootRootOpts {
+    cwd: string;
+    kind?: string;
+    name?: string;
+    /** Optional starter prompt (bare `crtr` requires none). */
+    prompt?: string;
+    /** 'inline'  — exec pi in the current terminal (bare `crtr`).
+     *  'session' — create a dedicated tmux session and run pi there (`session new`). */
+    placement: 'inline' | 'session';
+}
+/** Create a root node and bring up its pi. Returns the node; for 'inline' this
+ *  only returns after pi exits (it took over the terminal). */
+export declare function bootRoot(opts: BootRootOpts): NodeMeta;
+export interface SpawnChildOpts {
+    kind: string;
+    mode?: Mode;
+    cwd: string;
+    name?: string;
+    prompt: string;
+    /** Override the parent (defaults to the calling node from env). */
+    parent?: string;
+}
+export interface SpawnChildResult {
+    node: NodeMeta;
+    window: string | null;
+    session: string;
+}
+/** Spawn a terminal worker as a background window under the root session.
+ *  The parent auto-subscribes (active) to it via spawnNode. */
+export declare function spawnChild(opts: SpawnChildOpts): SpawnChildResult;

package/dist/core/runtime/spawn.js

@@ -0,0 +1,118 @@
+// The spawn orchestration — the one place that turns "I want a node here" into
+// a running pi process on the canvas. Composes canvas (birth + spine), persona
+// (resolve), launch (pi argv), and tmux (placement).
+//
+//   bootRoot   — a user-opened entry point (bare `crtr`).
+//                Resident. Runs pi in the foreground (inline) or its own session.
+//   spawnChild — a background worker spawned by a live node (`crtr node new`).
+//                Terminal. Opens a non-focus-stealing window under the root.
+import { spawnSync } from 'node:child_process';
+import { FRONT_DOOR_ENV } from './front-door.js';
+import { spawnNode, currentNodeContext } from './nodes.js';
+import { buildLaunchSpec, buildPiArgv } from './launch.js';
+import { writeGoal } from './kickoff.js';
+import { ensureSession, openNodeWindow, piCommand, currentTmux, inTmux, } from './tmux.js';
+import { updateNode, getNode } from '../canvas/index.js';
+import { ensureDaemon } from '../../daemon/manage.js';
+/** A root's tmux session name — its home; every descendant is a window in it. */
+export function rootSessionName(rootId) {
+    return `crtr-${rootId.replace(/[^a-zA-Z0-9]/g, '').slice(0, 12)}`;
+}
+/** Create a root node and bring up its pi. Returns the node; for 'inline' this
+ *  only returns after pi exits (it took over the terminal). */
+export function bootRoot(opts) {
+    // The thin supervisor must be up before any node exists, so a refresh-yield
+    // or crash can be reaped/revived. Idempotent.
+    try {
+        ensureDaemon();
+    }
+    catch { /* daemon is best-effort */ }
+    const kind = opts.kind ?? 'general';
+    // A born-resident root starts in base mode; it earns the orchestrator persona
+    // the first time it delegates (or on promotion). Resident lifecycle either way.
+    const { launch } = buildLaunchSpec(kind, 'base');
+    const meta = spawnNode({
+        kind,
+        mode: 'base',
+        lifecycle: 'resident',
+        cwd: opts.cwd,
+        name: opts.name ?? kind,
+        parent: null,
+        launch,
+    });
+    // Persist the spawning prompt as the goal so a fresh revive can re-read its
+    // mandate (bare `crtr` has none — writeGoal no-ops on empty).
+    if (opts.prompt !== undefined)
+        writeGoal(meta.node_id, opts.prompt);
+    const session = rootSessionName(meta.node_id);
+    if (opts.placement === 'session') {
+        ensureSession(session, opts.cwd);
+        updateNode(meta.node_id, { tmux_session: session });
+        const withSession = getNode(meta.node_id);
+        const inv = buildPiArgv(withSession, { prompt: opts.prompt });
+        const env = { ...inv.env, CRTR_ROOT_SESSION: session, [FRONT_DOOR_ENV]: '1' };
+        const win = openNodeWindow({
+            session,
+            name: meta.name,
+            cwd: opts.cwd,
+            env,
+            command: piCommand(inv.argv),
+        });
+        updateNode(meta.node_id, { window: win });
+        return getNode(meta.node_id);
+    }
+    // inline: the root adopts the current tmux session (if any) as its home, so
+    // children spawn as windows alongside it. Then exec pi in this terminal.
+    const here = currentTmux();
+    const adopted = here?.session ?? session;
+    updateNode(meta.node_id, { tmux_session: adopted, window: here?.window ?? null });
+    const withSession = getNode(meta.node_id);
+    const inv = buildPiArgv(withSession, { prompt: opts.prompt });
+    const env = { ...process.env, ...inv.env, CRTR_ROOT_SESSION: adopted, [FRONT_DOOR_ENV]: '1' };
+    const r = spawnSync('pi', inv.argv, { stdio: 'inherit', env });
+    process.exit(r.status ?? 0);
+}
+/** Spawn a terminal worker as a background window under the root session.
+ *  The parent auto-subscribes (active) to it via spawnNode. */
+export function spawnChild(opts) {
+    try {
+        ensureDaemon();
+    }
+    catch { /* daemon is best-effort */ }
+    const ctx = currentNodeContext();
+    const parent = opts.parent ?? ctx.nodeId;
+    if (parent === null || parent === undefined) {
+        throw new Error('spawnChild requires a calling node (CRTR_NODE_ID) or an explicit parent');
+    }
+    const mode = opts.mode ?? 'base';
+    const { launch } = buildLaunchSpec(opts.kind, mode);
+    const meta = spawnNode({
+        kind: opts.kind,
+        mode,
+        lifecycle: 'terminal',
+        cwd: opts.cwd,
+        name: opts.name ?? opts.kind,
+        parent,
+        launch,
+    });
+    // Persist the task as the child's goal for a fresh revive to re-read.
+    writeGoal(meta.node_id, opts.prompt);
+    // Resolve the root session: inherited from env, else derive + create one.
+    let session = process.env['CRTR_ROOT_SESSION'];
+    if (session === undefined || session === '') {
+        const here = inTmux() ? currentTmux() : null;
+        session = here?.session ?? rootSessionName(parent);
+        ensureSession(session, opts.cwd);
+    }
+    const inv = buildPiArgv(meta, { prompt: opts.prompt });
+    const env = { ...inv.env, CRTR_ROOT_SESSION: session };
+    const window = openNodeWindow({
+        session,
+        name: meta.name,
+        cwd: opts.cwd,
+        env,
+        command: piCommand(inv.argv),
+    });
+    const saved = updateNode(meta.node_id, { tmux_session: session, window });
+    return { node: saved, window, session };
+}

package/dist/core/runtime/stop-guard.d.ts

@@ -0,0 +1,18 @@
+export interface StopSignals {
+    /** Did the node call `push --final` (finish) this turn? */
+    pushedFinal: boolean;
+    /** Did the node call `crtr ask` (escalate to the human) this turn? */
+    askedHuman: boolean;
+}
+export type StopAction = {
+    action: 'allow';
+    reason: 'awaiting' | 'finished' | 'escalated' | 'attended';
+} | {
+    action: 'reprompt';
+    reason: 'stalled';
+    message: string;
+};
+export declare const STALL_REPROMPT: string;
+/** Decide what to do when a node stops. Pure given the canvas + this turn's
+ *  signals — the stophook supplies the signals and enacts the action. */
+export declare function evaluateStop(nodeId: string, signals: StopSignals): StopAction;

package/dist/core/runtime/stop-guard.js

@@ -0,0 +1,33 @@
+// The stop-guard — no stalled agents.
+//
+// Every time a node's pi process stops, we ask one question: is this node
+// *legitimately waiting*? A node is legitimately waiting iff it holds an ACTIVE
+// subscription to a node that's still live (active|idle) — something that can
+// actually wake it. (A passive sub won't wake you, so it doesn't count.)
+//
+//   • waiting        → stopping is correct; it's a dormant orchestrator awaiting
+//                      its workers. Let it sleep; a child's push wakes it.
+//   • finished/asked → it pushed --final (done) or called `crtr ask` this turn.
+//                      Also fine.
+//   • otherwise      → it has nothing live to wait for and hasn't resolved.
+//                      Re-prompt it to finish or escalate. Stalls are impossible.
+import { hasActiveLiveSubscription, getNode } from '../canvas/index.js';
+export const STALL_REPROMPT = "You've stopped but you're not waiting on anyone and haven't finished. " +
+    'Run `crtr push final "<result>"` if the work is done, or `crtr human ask` if you are blocked or need the user.';
+/** Decide what to do when a node stops. Pure given the canvas + this turn's
+ *  signals — the stophook supplies the signals and enacts the action. */
+export function evaluateStop(nodeId, signals) {
+    if (signals.pushedFinal)
+        return { action: 'allow', reason: 'finished' };
+    if (signals.askedHuman)
+        return { action: 'allow', reason: 'escalated' };
+    // A user-opened root (no parent) is human-attended: the human is its wake
+    // source, so stopping to await input is always legitimate — never nag it.
+    const node = getNode(nodeId);
+    if (node !== null && (node.parent === null || node.parent === undefined)) {
+        return { action: 'allow', reason: 'attended' };
+    }
+    if (hasActiveLiveSubscription(nodeId))
+        return { action: 'allow', reason: 'awaiting' };
+    return { action: 'reprompt', reason: 'stalled', message: STALL_REPROMPT };
+}

package/dist/core/runtime/tmux.d.ts

@@ -0,0 +1,88 @@
+/** POSIX single-quote escaping for one shell word. */
+export declare function shellQuote(s: string): string;
+export declare function inTmux(): boolean;
+export interface TmuxLocation {
+    session: string;
+    window: string;
+    pane: string;
+}
+/** Where the caller currently is, or null if not inside tmux. */
+export declare function currentTmux(): TmuxLocation | null;
+export declare function sessionExists(name: string): boolean;
+/** Create a detached session rooted at `cwd` if it doesn't exist. The session
+ *  name is a root's tmux home; every node under that root is a window in it. */
+export declare function ensureSession(name: string, cwd: string): void;
+export interface OpenWindowOpts {
+    session: string;
+    /** Window name (the node's display name). */
+    name: string;
+    cwd: string;
+    env: Record<string, string>;
+    /** The full command to run in the window (already a shell string). */
+    command: string;
+}
+/** Open a background window for a node and run `command` in it. `-d` keeps it
+ *  detached so it doesn't steal focus or become the current window. Returns the
+ *  new window id.
+ *
+ *  Target is `${session}:` (trailing colon = the session, no window index) plus
+ *  `-a` (insert after the current window) so tmux allocates the next free index.
+ *  Passing a bare session name resolves to the session's *active window*, which
+ *  makes new-window try to create AT that occupied index and fail with
+ *  "create window failed: index N in use" whenever the active window is not the
+ *  last one (common when base-index is 0 but the live window sits at index 1).
+ *  `-a` also keeps node windows off index 0, which is reserved for the optional
+ *  dashboard. */
+export declare function openNodeWindow(opts: OpenWindowOpts): string | null;
+/** Bring a node's window forefront. Switches client across roots when needed. */
+export declare function focusWindow(session: string, window: string): boolean;
+/** Close a node's window (drop it from the UI). */
+export declare function closeWindow(window: string): boolean;
+/** The active pane id of a window. Node windows are single-pane, so this is the
+ *  node's pane. Returns null if the window is gone or tmux fails. */
+export declare function paneOfWindow(session: string, window: string): string | null;
+/** The window a pane currently lives in. Used after a swap-pane to learn which
+ *  slot the caller's pane occupied — pane ids are stable across swaps, windows
+ *  are not, so the node→window mapping must be re-derived from the pane. Returns
+ *  null if the pane is gone or tmux fails. */
+export declare function windowOfPane(pane: string): string | null;
+/** Swap `targetPane` into `callerPane`'s layout slot, IN PLACE. `-d` keeps the
+ *  caller's window active, so the target's pane appears where the caller is
+ *  rather than navigating the client off to the target's window. The caller's
+ *  old pane lives on in the target's former window — the move is reversible
+ *  (focusing back swaps it in again). Best-effort; never throws. */
+export declare function swapPaneInPlace(targetPane: string, callerPane: string): boolean;
+export interface RespawnPaneOpts {
+    /** Target pane id (e.g. `%3`) — the pane to re-exec in place. */
+    pane: string;
+    cwd: string;
+    env: Record<string, string>;
+    /** The full command to run in the pane (already a shell string). */
+    command: string;
+}
+/** Re-exec a command in an EXISTING pane, in place. `-k` kills the pane's
+ *  current process (e.g. a yielding pi) and starts `command` in the same pane
+ *  — the window/pane survives, so an interactive session is never dropped to a
+ *  shell and no window churns. Used by refresh-yield.
+ *
+ *  Spawned DETACHED (own process group, unref'd) so the request reaches the
+ *  tmux server even though killing the pane tears down the caller's own pi.
+ *  Returns true once the request was dispatched. */
+export declare function respawnPane(opts: RespawnPaneOpts): boolean;
+/** Turn a pi argv array into a single shell command string. */
+export declare function piCommand(argv: string[], binary?: string): string;
+/** List all window ids present in `session`. Returns [] if the session does
+ *  not exist or tmux fails for any reason. Each entry is the raw window id
+ *  string reported by tmux (e.g. `@1`, `@2`, …). */
+export declare function listWindowIds(session: string): string[];
+/** True when both `session` and `window` are present (non-null/undefined) and
+ *  the window currently exists inside the session. False whenever either arg
+ *  is absent, the session is gone, or tmux does not know the window. */
+export declare function windowAlive(session: string | null | undefined, window: string | null | undefined): boolean;
+/** Activate a window within its session (same-session navigation). Equivalent
+ *  to `tmux select-window -t <session>:<window>`. Best-effort; never throws. */
+export declare function selectWindow(session: string, window: string): boolean;
+/** Switch the tmux client to a different session (cross-session focus). Runs
+ *  `tmux switch-client -t <session>`. Best-effort; never throws. The caller is
+ *  responsible for following up with selectWindow to land on the right window. */
+export declare function switchClient(session: string): boolean;

package/dist/core/runtime/tmux.js

@@ -0,0 +1,198 @@
+// tmux placement — one window per active node.
+//
+//   session = a root        window = a node        window 0 = optional dashboard
+//
+// Background windows run but don't render — only the current window draws. That
+// is the "detached but switchable" model: nothing tiles, you never see a node's
+// UI unless you switch to it. Bring one forefront with select-window (within a
+// root) or switch-client + select-window (across roots). done/dead nodes close
+// their window; reviving opens a fresh one.
+import { spawn, spawnSync } from 'node:child_process';
+// ---------------------------------------------------------------------------
+// Shell quoting + tmux invocation
+// ---------------------------------------------------------------------------
+/** POSIX single-quote escaping for one shell word. */
+export function shellQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+function tmux(args) {
+    const r = spawnSync('tmux', args, { encoding: 'utf8' });
+    return {
+        ok: r.status === 0,
+        stdout: (r.stdout ?? '').trim(),
+        stderr: (r.stderr ?? '').trim(),
+    };
+}
+export function inTmux() {
+    return process.env['TMUX'] !== undefined && process.env['TMUX'] !== '';
+}
+/** Where the caller currently is, or null if not inside tmux. */
+export function currentTmux() {
+    if (!inTmux())
+        return null;
+    const r = tmux([
+        'display-message',
+        '-p',
+        '#{session_name}\t#{window_id}\t#{pane_id}',
+    ]);
+    if (!r.ok)
+        return null;
+    const [session, window, pane] = r.stdout.split('\t');
+    return { session, window, pane };
+}
+// ---------------------------------------------------------------------------
+// Sessions + windows
+// ---------------------------------------------------------------------------
+export function sessionExists(name) {
+    return tmux(['has-session', '-t', name]).ok;
+}
+/** Create a detached session rooted at `cwd` if it doesn't exist. The session
+ *  name is a root's tmux home; every node under that root is a window in it. */
+export function ensureSession(name, cwd) {
+    if (sessionExists(name))
+        return;
+    tmux(['new-session', '-d', '-s', name, '-c', cwd]);
+}
+function envFlags(env) {
+    const out = [];
+    for (const [k, v] of Object.entries(env))
+        out.push('-e', `${k}=${v}`);
+    return out;
+}
+/** Open a background window for a node and run `command` in it. `-d` keeps it
+ *  detached so it doesn't steal focus or become the current window. Returns the
+ *  new window id.
+ *
+ *  Target is `${session}:` (trailing colon = the session, no window index) plus
+ *  `-a` (insert after the current window) so tmux allocates the next free index.
+ *  Passing a bare session name resolves to the session's *active window*, which
+ *  makes new-window try to create AT that occupied index and fail with
+ *  "create window failed: index N in use" whenever the active window is not the
+ *  last one (common when base-index is 0 but the live window sits at index 1).
+ *  `-a` also keeps node windows off index 0, which is reserved for the optional
+ *  dashboard. */
+export function openNodeWindow(opts) {
+    const r = tmux([
+        'new-window',
+        '-d',
+        '-a',
+        '-P',
+        '-F',
+        '#{window_id}',
+        '-t',
+        `${opts.session}:`,
+        '-n',
+        opts.name,
+        '-c',
+        opts.cwd,
+        ...envFlags(opts.env),
+        opts.command,
+    ]);
+    return r.ok ? r.stdout : null;
+}
+/** Bring a node's window forefront. Switches client across roots when needed. */
+export function focusWindow(session, window) {
+    const here = currentTmux();
+    const sameRoot = here?.session === session;
+    if (!sameRoot) {
+        if (!tmux(['switch-client', '-t', session]).ok)
+            return false;
+    }
+    return tmux(['select-window', '-t', window]).ok;
+}
+/** Close a node's window (drop it from the UI). */
+export function closeWindow(window) {
+    return tmux(['kill-window', '-t', window]).ok;
+}
+/** The active pane id of a window. Node windows are single-pane, so this is the
+ *  node's pane. Returns null if the window is gone or tmux fails. */
+export function paneOfWindow(session, window) {
+    const r = tmux(['display-message', '-p', '-t', `${session}:${window}`, '#{pane_id}']);
+    return r.ok && r.stdout !== '' ? r.stdout : null;
+}
+/** The window a pane currently lives in. Used after a swap-pane to learn which
+ *  slot the caller's pane occupied — pane ids are stable across swaps, windows
+ *  are not, so the node→window mapping must be re-derived from the pane. Returns
+ *  null if the pane is gone or tmux fails. */
+export function windowOfPane(pane) {
+    const r = tmux(['display-message', '-p', '-t', pane, '#{window_id}']);
+    return r.ok && r.stdout !== '' ? r.stdout : null;
+}
+/** Swap `targetPane` into `callerPane`'s layout slot, IN PLACE. `-d` keeps the
+ *  caller's window active, so the target's pane appears where the caller is
+ *  rather than navigating the client off to the target's window. The caller's
+ *  old pane lives on in the target's former window — the move is reversible
+ *  (focusing back swaps it in again). Best-effort; never throws. */
+export function swapPaneInPlace(targetPane, callerPane) {
+    if (targetPane === callerPane)
+        return true;
+    return tmux(['swap-pane', '-d', '-s', targetPane, '-t', callerPane]).ok;
+}
+/** Re-exec a command in an EXISTING pane, in place. `-k` kills the pane's
+ *  current process (e.g. a yielding pi) and starts `command` in the same pane
+ *  — the window/pane survives, so an interactive session is never dropped to a
+ *  shell and no window churns. Used by refresh-yield.
+ *
+ *  Spawned DETACHED (own process group, unref'd) so the request reaches the
+ *  tmux server even though killing the pane tears down the caller's own pi.
+ *  Returns true once the request was dispatched. */
+export function respawnPane(opts) {
+    try {
+        const child = spawn('tmux', [
+            'respawn-pane',
+            '-k',
+            '-c',
+            opts.cwd,
+            ...envFlags(opts.env),
+            '-t',
+            opts.pane,
+            opts.command,
+        ], { detached: true, stdio: 'ignore' });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// pi command assembly
+// ---------------------------------------------------------------------------
+/** Turn a pi argv array into a single shell command string. */
+export function piCommand(argv, binary = 'pi') {
+    return [binary, ...argv.map(shellQuote)].join(' ');
+}
+// ---------------------------------------------------------------------------
+// Window liveness helpers (used by the supervisor daemon)
+// ---------------------------------------------------------------------------
+/** List all window ids present in `session`. Returns [] if the session does
+ *  not exist or tmux fails for any reason. Each entry is the raw window id
+ *  string reported by tmux (e.g. `@1`, `@2`, …). */
+export function listWindowIds(session) {
+    const r = tmux(['list-windows', '-t', session, '-F', '#{window_id}']);
+    if (!r.ok || r.stdout === '')
+        return [];
+    return r.stdout.split('\n').filter((s) => s !== '');
+}
+/** True when both `session` and `window` are present (non-null/undefined) and
+ *  the window currently exists inside the session. False whenever either arg
+ *  is absent, the session is gone, or tmux does not know the window. */
+export function windowAlive(session, window) {
+    if (session == null || window == null)
+        return false;
+    return listWindowIds(session).includes(window);
+}
+// ---------------------------------------------------------------------------
+// Focus helpers (used by the presence layer)
+// ---------------------------------------------------------------------------
+/** Activate a window within its session (same-session navigation). Equivalent
+ *  to `tmux select-window -t <session>:<window>`. Best-effort; never throws. */
+export function selectWindow(session, window) {
+    return tmux(['select-window', '-t', `${session}:${window}`]).ok;
+}
+/** Switch the tmux client to a different session (cross-session focus). Runs
+ *  `tmux switch-client -t <session>`. Best-effort; never throws. The caller is
+ *  responsible for following up with selectWindow to land on the right window. */
+export function switchClient(session) {
+    return tmux(['switch-client', '-t', session]).ok;
+}

package/dist/core/spawn.d.ts

@@ -1,100 +1,37 @@
-export interface SpawnAgentOptions {
-    /** First user message for the new claude session. */
-    prompt: string;
-    cwd: string;
-    /** crtr job_id injected as CRTR_JOB_ID env var in the pane. */
-    jobId: string;
-    /** If set, resume this Claude Code session with --fork-session (new session id). */
-    fork?: {
-        sessionId: string;
-    };
-    /** Max panes per tmux window before overflowing to a new window. */
-    maxPanesPerWindow: number;
-    /** Display name passed to `claude -n`; surfaces in pane title and /resume picker. */
-    name?: string;
-}
-export interface SpawnAgentResult {
-    status: 'spawned' | 'spawn-failed' | 'not-in-tmux';
-    /** tmux pane id of the spawned pane. */
-    paneId?: string;
-    /** How the pane was placed. */
-    placement?: 'split-window' | 'new-window';
-    message: string;
-}
+export declare function isInTmux(): boolean;
+export declare function shellQuote(s: string): string;
+/** Count panes in the current tmux window (0 outside tmux / on error). */
+export declare function countPanesInCurrentWindow(): number;
+/**
+ * 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,
+ * when TMUX_PANE is unset, or when delaySeconds <= 0.
+ */
+export declare function scheduleKillCurrentPane(delaySeconds: number): boolean;
 export interface DetachOptions {
-    /** Inner command to run in the pane. If omitted, build `claude … <prompt>`. */
-    command?: string;
-    /** Full first user message for the new claude session (claude mode only;
-     *  ignored when `command` is set). No custom system prompt. */
-    prompt?: string;
+    /** Inner command to run in the new pane. */
+    command: string;
     cwd: string;
-    /** crtr job_id injected as CRTR_JOB_ID env var in the pane and used by the
-     *  `_fail` guard. Optional only when `failGuard` is false. */
+    /** Optional id injected as the CRTR_JOB_ID env var in the pane. */
     jobId?: string;
     /** Where to open the new pane. */
     placement: 'split-h' | 'split-v' | 'new-window';
-    /** Seconds to wait before killing the originating pane so the caller can finish. */
+    /** Seconds before killing the originating pane so the caller can finish. */
     killAfterSeconds: number;
-    /** Append `; crtr job _fail <jobId>` and inject CRTR_JOB_ID. Default true. */
-    failGuard?: boolean;
     /** Pin the new pane to this tmux pane: split-window splits it; new-window is
      *  inserted immediately after its window (-a -t <pane>). Without this, tmux
      *  uses the attached client's currently-focused pane — which drifts if the
      *  user switches windows between kickoff and spawn. */
     targetPane?: string;
-    /** Display name passed to `claude -n`; ignored when `command` is set
-     *  (caller controls the full argv in that mode). */
-    name?: string;
 }
 export interface DetachResult {
     status: 'spawned' | 'spawn-failed' | 'not-in-tmux';
     paneId?: string;
     message: string;
 }
-export declare function isInTmux(): boolean;
-export declare function shellQuote(s: string): string;
-export declare function countPanesInCurrentWindow(): number;
-/**
- * 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 declare function findWindowWithSpace(maxPanesPerWindow: number): string | null;
 /**
- * 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.
- */
-export declare function scheduleKillCurrentPane(delaySeconds: number): boolean;
-/**
- * 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 declare function spawnAndDetach(opts: DetachOptions): DetachResult;
-/**
- * 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 declare function spawnAgent(opts: SpawnAgentOptions): SpawnAgentResult;