@crouton-kit/crouter 0.3.40 → 0.3.42

package/dist/core/runtime/session-cycles.js

@@ -0,0 +1,77 @@
+// Cycle-aware session history — one node, one `.jsonl`, many cycles.
+//
+// A refresh-yield does not start a new session file: reviveNode reuses the
+// node's existing `.jsonl` (buildPiArgv's `--crtr-new-cycle`), and the broker
+// resets the session-tree leaf, appending a `crtr-cycle` custom entry as the
+// new cycle's ROOT. Custom entries never participate in LLM context, so the
+// refreshed window is exactly as clean as a brand-new session — but every
+// cycle lives in the same tree as a sibling root branch, so the /tree
+// navigator shows previous cycles natively.
+//
+// `cycleAwareMessages()` is the display-side counterpart: it rebuilds the FULL
+// node history — each prior cycle's messages (via pi's own `buildSessionContext`,
+// so a compacted prior cycle renders correctly), a synthetic divider message per
+// boundary, then the live cycle's context — so the broker welcome snapshot
+// (broker.ts) and the dormant snapshot (node-snapshot.ts) both render one
+// continuous conversation.
+import { buildSessionContext } from '@earendil-works/pi-coding-agent';
+/** customType of the persisted tree entry that ROOTS each post-yield cycle.
+ *  Data payload: `{ cycle, fromLeaf }` — `cycle` is the node's cycle counter at
+ *  relaunch, `fromLeaf` the previous cycle's leaf entry id. */
+export const CRTR_CYCLE_CUSTOM_TYPE = 'crtr-cycle';
+/** customType of the SYNTHETIC divider message spliced between cycles in
+ *  snapshot rendering. Never persisted to the session file. */
+export const CRTR_CYCLE_DIVIDER_CUSTOM_TYPE = 'crtr-cycle-divider';
+function cycleDivider(cycle, timestamp) {
+    const label = cycle !== undefined ? `cycle ${cycle}` : 'new cycle';
+    return {
+        role: 'custom',
+        customType: CRTR_CYCLE_DIVIDER_CUSTOM_TYPE,
+        content: `yielded — ${label} begins with a fresh context window`,
+        display: true,
+        timestamp: new Date(timestamp).getTime(),
+    };
+}
+/** The full multi-cycle message history for display: prior cycles (oldest
+ *  first, each closed by a divider), then the live cycle's context. Falls back
+ *  to plain `buildSessionContext()` when the session has no cycle markers, when
+ *  the manager lacks tree accessors (fake engine), or when the current leaf was
+ *  tree-navigated back into a pre-yield branch (pi's active-branch semantics
+ *  then apply unchanged). */
+export function cycleAwareMessages(sm) {
+    const current = sm.buildSessionContext().messages;
+    if (typeof sm.getEntries !== 'function' || typeof sm.getBranch !== 'function')
+        return current;
+    // File order = append order = chronological cycle order.
+    const entries = sm.getEntries();
+    const markers = entries.filter((e) => e.type === 'custom' && e.customType === CRTR_CYCLE_CUSTOM_TYPE);
+    if (markers.length === 0)
+        return current;
+    // The current cycle's root: first entry on the leaf→root path. When it is
+    // not a cycle marker, the leaf sits in the ORIGINAL (pre-yield) branch —
+    // render just that branch. Otherwise replay every cycle up to and including
+    // the one the marker closes.
+    const currentRootId = sm.getBranch()[0]?.id;
+    const rootMarkerIndex = markers.findIndex((m) => m.id === currentRootId);
+    if (rootMarkerIndex === -1)
+        return current;
+    // Shared byId map — buildSessionContext would otherwise rebuild one from
+    // `entries` on every call; one pass here amortizes it across every replayed
+    // marker.
+    const byId = new Map(entries.map((e) => [e.id, e]));
+    const out = [];
+    for (let i = 0; i <= rootMarkerIndex; i++) {
+        const marker = markers[i];
+        const fromLeaf = marker.data?.fromLeaf;
+        if (typeof fromLeaf === 'string' && fromLeaf !== '') {
+            // Replay this prior cycle's own branch through pi's canonical context
+            // builder — preserving compaction semantics (one compactionSummary +
+            // kept + post-compaction messages only) exactly like the live cycle
+            // below.
+            out.push(...buildSessionContext(entries, fromLeaf, byId).messages);
+        }
+        out.push(cycleDivider(marker.data?.cycle, marker.timestamp));
+    }
+    out.push(...current);
+    return out;
+}

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

@@ -54,6 +54,10 @@ export interface SpawnChildOpts {
      *  choice at fire time (an explicit value re-validates; inheritance re-reads
      *  the spawner's THEN-current profile). */
     profile?: string | null;
+    /** Create a managed worktree for this node and pin its cwd to it. */
+    worktree?: boolean;
+    /** Preallocated node id, used when a managed worktree must be named before birth. */
+    nodeId?: string;
 }
 /** Resolve a `--fork-from` value to an ABSOLUTE `.jsonl` source path for the
  *  broker fork (`SessionManager.forkFrom`, which loads a file — never a bare id).

package/dist/core/runtime/spawn.js

@@ -13,15 +13,18 @@ import { spawnSync } from 'node:child_process';
 import { readdirSync, existsSync } from 'node:fs';
 import { isAbsolute, resolve, join } from 'node:path';
 import { homedir } from 'node:os';
-import { spawnNode, currentNodeContext, rootOfSpine } from './nodes.js';
+import { spawnNode, currentNodeContext, rootOfSpine, newNodeId } from './nodes.js';
 import { loadProfileManifest } from '../profiles/manifest.js';
 import { selectProfileForCwd } from '../profiles/select.js';
 import { buildLaunchSpec, buildPiArgv } from './launch.js';
+import { gitSync } from '../git.js';
+import { createManagedWorktree } from '../worktree.js';
+import { usage } from '../errors.js';
 import { writeGoal } from './kickoff.js';
 import { hasRoadmap, seedRoadmap } from './roadmap.js';
 import { buildIdentityAssertion, buildWakeBearings } from './bearings.js';
 import { installMenuBinding, installNavBindings, installViewNavBindings } from './tmux-chrome.js';
-import { getNode, fullName } from '../canvas/index.js';
+import { getNode, fullName, recordPid } from '../canvas/index.js';
 import { registerViewerFocus, openViewerWindow, waitForBrokerViewSocket, viewerSplitEnv, windowOfPane, currentTmux, inTmux, focusWindow, } from './placement.js';
 import { transition } from './lifecycle.js';
 import { headlessBrokerHost } from './host.js';
@@ -134,6 +137,7 @@ export async function bootRoot(opts) {
         transition(meta.node_id, 'crash');
         throw new Error(`failed to launch the broker engine for the front-door root ${meta.node_id} — nothing to attach to.`);
     }
+    recordPid(meta.node_id, placed.pid);
     // The terminal has nothing to attach to until view.sock accepts. The root is
     // useless without its engine, so a socket timeout IS fatal here (unlike a
     // background child's optional viewer, which is skipped on timeout).
@@ -170,7 +174,9 @@ function piSessionsRoot() {
 function resolveSessionUuid(uuid) {
     const sessionsRoot = piSessionsRoot();
     if (!existsSync(sessionsRoot)) {
-        throw new Error(`--fork-from '${uuid}': no pi sessions store at ${sessionsRoot} to resolve it from — pass a node id or an absolute .jsonl path.`);
+        throw usage(`--fork-from '${uuid}': no pi sessions store at ${sessionsRoot} to resolve it from — pass a node id or an absolute .jsonl path.`, {
+            next: 'Pass a live node id, an absolute .jsonl session path, or drop --fork-from.',
+        });
     }
     const matches = [];
     for (const dir of readdirSync(sessionsRoot, { withFileTypes: true })) {
@@ -187,10 +193,15 @@ function resolveSessionUuid(uuid) {
     }
     const exact = matches.filter((m) => m.id === uuid);
     const hit = exact.length > 0 ? exact : matches.filter((m) => m.id.startsWith(uuid));
-    if (hit.length === 0)
-        throw new Error(`--fork-from '${uuid}': no pi session with that id found.`);
+    if (hit.length === 0) {
+        throw usage(`--fork-from '${uuid}': no pi session with that id found.`, {
+            next: 'Pass a live node id, a real session uuid/prefix, or an absolute .jsonl session path.',
+        });
+    }
     if (hit.length > 1) {
-        throw new Error(`--fork-from '${uuid}': ambiguous — ${hit.length} sessions match that id prefix; pass the full id or the .jsonl path.`);
+        throw usage(`--fork-from '${uuid}': ambiguous — ${hit.length} sessions match that id prefix; pass the full id or the .jsonl path.`, {
+            next: 'Pass the full session uuid or an absolute .jsonl path to disambiguate.',
+        });
     }
     return hit[0].path;
 }
@@ -203,7 +214,7 @@ function resolveSessionUuid(uuid) {
 export function resolveForkSource(value) {
     const v = value.trim();
     if (v === '')
-        throw new Error('--fork-from requires a node id, session file, or session uuid.');
+        throw usage('--fork-from requires a node id, session file, or session uuid.', { next: 'Pass a live node id, an absolute .jsonl session path, or a session uuid/prefix.' });
     // A path (contains `/` or ends `.jsonl`) is a session file — ensure it is
     // ABSOLUTE so the broker, launched in a different cwd, still resolves it.
     if (v.includes('/') || v.endsWith('.jsonl')) {
@@ -215,7 +226,9 @@ export function resolveForkSource(value) {
     if (n !== null) {
         const src = n.pi_session_file;
         if (src === undefined || src === null || src === '') {
-            throw new Error(`node ${v} has no pi session yet — it has not captured a session FILE to fork from (the broker forks a .jsonl path, not a bare id).`);
+            throw usage(`node ${v} has no pi session yet — it has not captured a session FILE to fork from (the broker forks a .jsonl path, not a bare id).`, {
+                next: 'Pick a node that has captured a session, or drop --fork-from.',
+            });
         }
         return src;
     }
@@ -279,102 +292,141 @@ export async function spawnChild(opts) {
     // Born WITHOUT a name — the canvas-goal-capture extension names it async from
     // its first message (the kickoff task) inside its own pi process, so spawn
     // never blocks on the LLM naming round-trip (the 2-3s freeze it used to cost).
+    const wantsWorktree = opts.worktree === true;
+    const nodeId = wantsWorktree ? (opts.nodeId ?? newNodeId()) : opts.nodeId;
+    // Preflight: resolve every fallible input BEFORE creating the worktree or the
+    // node. `--fork-from <bad>` (resolveForkSource) and an invalid `--profile`
+    // (resolveProfileId) must fail HERE, before anything exists to clean up or
+    // strand — catching them later (after the worktree/node are created) is what
+    // let `--worktree --fork-from <bad>` leave an active node pinned to a deleted
+    // cwd with an open managed_worktree.
     const profileId = await resolveProfileId(opts.profile, spawner, opts.cwd);
-    const meta = spawnNode({
-        kind: opts.kind,
-        mode,
-        lifecycle,
-        cwd: opts.cwd,
-        name: opts.name ?? opts.kind,
-        // A root has no spine parent (top-level, nobody subscribes); it still
-        // records spawned_by=spawner when a node (not a human shell) spawned it.
-        // A child's parent IS its manager.
-        parent: root ? null : spawner,
-        spawnedBy: root ? (spawner ?? undefined) : undefined,
-        profile_id: profileId,
-        // Persist the RAW fork reference (not the resolved path) as provenance, so
-        // the boot intro can detect this is a fork and re-assert the node's own
-        // identity over the source's copied-in conversation.
-        forkFrom: opts.forkFrom,
-        modelOverride: opts.model,
-        launch,
-    });
-    // Persist the task as the child's goal for a fresh revive to re-read.
-    writeGoal(meta.node_id, opts.prompt);
-    // A fork copies an existing conversation into this child's first session
-    // (resolved to an absolute file path when forking from a node). Resolved here
-    // — not in buildPiArgv — so a bad reference fails the spawn loudly before any
-    // window opens, rather than after pi is already booting.
     const forkFrom = opts.forkFrom !== undefined ? resolveForkSource(opts.forkFrom) : undefined;
-    // A fork inherits the SOURCE node's entire first-person conversation, so the
-    // identity re-assertion must ride the STRONGEST channel too, not only the
-    // session-start bearings (a trailing custom_message the model weighs only by
-    // recency). Prepend it to the kickoff PROMPT — the message that actually
-    // triggers the fork's first turn, so the model acts on "you are node X, a
-    // FORK of <source>, NOT them" as live instruction. When the daemon births this
-    // node from a scheduled `spawn` wake, the <crtr-wake> provenance block leads
-    // (so "a timer birthed you" precedes the task) — mirroring the fork-identity
-    // prepend. Only the pi argv prompt is reframed; the persisted goal (writeGoal
-    // above) keeps the raw task.
-    const wakeBlock = opts.wakeOrigin !== undefined ? `${buildWakeBearings(opts.wakeOrigin)}\n\n` : '';
-    const idBlock = forkFrom !== undefined ? `${buildIdentityAssertion(meta.node_id)}\n\n` : '';
-    const kickoff = `${wakeBlock}${idBlock}${opts.prompt}`;
-    // A child created DIRECTLY as an orchestrator (mode='orchestrator') boots
-    // with the orchestrator persona but bypasses promote(), which is where a
-    // roadmap scaffold would normally be seeded. Lay one down here (goal
-    // pre-filled from the task) so the orchestrator has its memory artifact from
-    // birth, instead of waking memory-less. Guarded so it never clobbers.
-    if (mode === 'orchestrator' && !hasRoadmap(meta.node_id)) {
-        seedRoadmap(meta.node_id, { goal: opts.prompt.trim() });
-    }
-    // (The three scoped long-term memory stores are seeded for EVERY node at birth
-    // in spawnNode — no orchestrator-gated seeding needed here.)
-    // A --root spawned from inside tmux opens its one viewer in the CALLER'S
-    // CURRENT session (below), so it appears where the spawner is working; a
-    // managed child is a headless broker with NO viewer at all.
-    const here = root ? currentTmux() : null;
-    const inv = buildPiArgv(meta, { prompt: kickoff, forkFrom });
-    // CRTR_SUBTREE (the spine root) rides the detached broker's env so it can group
-    // the subtree; the host sets CRTR_FRONT_DOOR itself.
-    inv.env = { ...inv.env, CRTR_SUBTREE: rootOfSpine(meta.node_id) };
-    // Broker is the only host: launch the detached broker ENGINE. A managed child
-    // gets NO viewer — spawning it returns once the engine is launched and a human
-    // opens a viewer on demand via `crtr node focus` / surface attach. A --root gets
-    // one foreground viewer below.
-    const placed = launchBrokerOrCrash(meta.node_id, inv, {
-        cwd: meta.cwd,
-        name: fullName(meta),
-        resuming: false,
-    });
-    // Definitive failure: no broker pid ⇒ the node has no engine. Crash it (so the
-    // daemon doesn't watch a zombie 'active') and throw so `crtr node new` exits
-    // non-zero. transition('crash') is a legal from-LIVE move (still 'active' from
-    // spawnNode). Mirrors the old window===null crash.
-    if (placed.pid === null) {
-        transition(meta.node_id, 'crash');
-        throw new Error(`failed to launch the broker engine for ${meta.node_id} (${meta.name}) — the node was not started.`);
-    }
-    // A --root is spawned to be DRIVEN directly: when the caller is inside tmux,
-    // open ONE foreground viewer in the caller's CURRENT session and bring it
-    // forefront so whoever asked for it picks up the conversation. Outside tmux a
-    // --root opens no viewer (an agent handing a root off) — never a throw. A
-    // managed child opens nothing. Non-fatal if tmux refuses (openViewerWindow
-    // returns null) or the socket never binds — `focus` opens a viewer later.
-    let window = null;
-    let session = null;
-    if (root && here !== null && await waitForBrokerViewSocket(meta.node_id, placed.exited)) {
-        const viewer = openViewerWindow(meta.node_id, here.session, { name: fullName(meta), cwd: opts.cwd });
-        if (viewer !== null && viewer.pane !== null && viewer.pane !== '') {
-            session = here.session;
-            window = windowOfPane(viewer.pane);
-            if (window !== null) {
-                try {
-                    focusWindow(here.session, window);
+    let managedWorktree;
+    let spawnCwd = opts.cwd;
+    try {
+        if (wantsWorktree) {
+            managedWorktree = createManagedWorktree(opts.cwd, nodeId);
+            spawnCwd = managedWorktree.path;
+        }
+        const meta = spawnNode({
+            kind: opts.kind,
+            mode,
+            lifecycle,
+            cwd: spawnCwd,
+            name: opts.name ?? opts.kind,
+            // A root has no spine parent (top-level, nobody subscribes); it still
+            // records spawned_by=spawner when a node (not a human shell) spawned it.
+            // A child's parent IS its manager.
+            parent: root ? null : spawner,
+            spawnedBy: root ? (spawner ?? undefined) : undefined,
+            profile_id: profileId,
+            // Persist the RAW fork reference (not the resolved path) as provenance, so
+            // the boot intro can detect this is a fork and re-assert the node's own
+            // identity over the source's copied-in conversation.
+            forkFrom: opts.forkFrom,
+            modelOverride: opts.model,
+            ...(managedWorktree !== undefined ? { managedWorktree } : {}),
+            ...(nodeId !== undefined ? { nodeId } : {}),
+            launch,
+        });
+        // Persist the task as the child's goal for a fresh revive to re-read.
+        writeGoal(meta.node_id, opts.prompt);
+        // A fork inherits the SOURCE node's entire first-person conversation, so the
+        // identity re-assertion must ride the STRONGEST channel too, not only the
+        // session-start bearings (a trailing custom_message the model weighs only by
+        // recency). Prepend it to the kickoff PROMPT — the message that actually
+        // triggers the fork's first turn, so the model acts on "you are node X, a
+        // FORK of <source>, NOT them" as live instruction. When the daemon births this
+        // node from a scheduled `spawn` wake, the <crtr-wake> provenance block leads
+        // (so "a timer birthed you" precedes the task) — mirroring the fork-identity
+        // prepend. Only the pi argv prompt is reframed; the persisted goal (writeGoal
+        // above) keeps the raw task.
+        const wakeBlock = opts.wakeOrigin !== undefined ? `${buildWakeBearings(opts.wakeOrigin)}\n\n` : '';
+        const idBlock = forkFrom !== undefined ? `${buildIdentityAssertion(meta.node_id)}\n\n` : '';
+        const kickoff = `${wakeBlock}${idBlock}${opts.prompt}`;
+        // A child created DIRECTLY as an orchestrator (mode='orchestrator') boots
+        // with the orchestrator persona but bypasses promote(), which is where a
+        // roadmap scaffold would normally be seeded. Lay one down here (goal
+        // pre-filled from the task) so the orchestrator has its memory artifact from
+        // birth, instead of waking memory-less. Guarded so it never clobbers.
+        if (mode === 'orchestrator' && !hasRoadmap(meta.node_id)) {
+            seedRoadmap(meta.node_id, { goal: opts.prompt.trim() });
+        }
+        // (The three scoped long-term memory stores are seeded for EVERY node at birth
+        // in spawnNode — no orchestrator-gated seeding needed here.)
+        // A --root spawned from inside tmux opens its one viewer in the CALLER'S
+        // CURRENT session (below), so it appears where the spawner is working; a
+        // managed child is a headless broker with NO viewer at all.
+        const here = root ? currentTmux() : null;
+        const inv = buildPiArgv(meta, { prompt: kickoff, forkFrom });
+        // CRTR_SUBTREE (the spine root) rides the detached broker's env so it can group
+        // the subtree; the host sets CRTR_FRONT_DOOR itself.
+        inv.env = { ...inv.env, CRTR_SUBTREE: rootOfSpine(meta.node_id) };
+        // Broker is the only host: launch the detached broker ENGINE. A managed child
+        // gets NO viewer — spawning it returns once the engine is launched and a human
+        // opens a viewer on demand via `crtr node focus` / surface attach. A --root gets
+        // one foreground viewer below.
+        const placed = launchBrokerOrCrash(meta.node_id, inv, {
+            cwd: meta.cwd,
+            name: fullName(meta),
+            resuming: false,
+        });
+        // Definitive failure: no broker pid ⇒ the node has no engine. Crash it (so the
+        // daemon doesn't watch a zombie 'active') and throw so `crtr node new` exits
+        // non-zero. transition('crash') is a legal from-LIVE move (still 'active' from
+        // spawnNode). Mirrors the old window===null crash.
+        if (placed.pid === null) {
+            transition(meta.node_id, 'crash');
+            throw new Error(`failed to launch the broker engine for ${meta.node_id} (${meta.name}) — the node was not started.`);
+        }
+        recordPid(meta.node_id, placed.pid);
+        // A --root is spawned to be DRIVEN directly: when the caller is inside tmux,
+        // open ONE foreground viewer in the caller's CURRENT session and bring it
+        // forefront so whoever asked for it picks up the conversation. Outside tmux a
+        // --root opens no viewer (an agent handing a root off) — never a throw. A
+        // managed child opens nothing. Non-fatal if tmux refuses (openViewerWindow
+        // returns null) or the socket never binds — `focus` opens a viewer later.
+        let window = null;
+        let session = null;
+        if (root && here !== null && await waitForBrokerViewSocket(meta.node_id, placed.exited)) {
+            const viewer = openViewerWindow(meta.node_id, here.session, { name: fullName(meta), cwd: opts.cwd });
+            if (viewer !== null && viewer.pane !== null && viewer.pane !== '') {
+                session = here.session;
+                window = windowOfPane(viewer.pane);
+                if (window !== null) {
+                    try {
+                        focusWindow(here.session, window);
+                    }
+                    catch { /* best-effort */ }
                 }
-                catch { /* best-effort */ }
             }
         }
+        const saved = getNode(meta.node_id);
+        return { node: saved, window, session };
+    }
+    catch (err) {
+        // Cleanup scope: a managed worktree is only removed on failure while NO
+        // persisted node identity exists yet. spawnNode() persists the node row
+        // (and its meta files) BEFORE the later fallible steps in this try block
+        // (writeGoal, roadmap seeding, launch, viewer placement) — so a flag set
+        // after spawnNode() merely returns would still read false if one of THOSE
+        // later steps threw, and this catch would then delete the worktree out
+        // from under an already-persisted node whose cwd points at it. Check the
+        // canvas directly instead: once any node row exists for this id, keep the
+        // worktree — the node stays alive (crashed, if the launch itself failed)
+        // with its worktree intact rather than pinned to a deleted path.
+        if (managedWorktree !== undefined && nodeId !== undefined && getNode(nodeId) === null) {
+            const repoRoot = managedWorktree.repo_root;
+            try {
+                gitSync(['worktree', 'remove', managedWorktree.path], repoRoot);
+            }
+            catch { /* best-effort */ }
+            try {
+                gitSync(['branch', '-d', managedWorktree.branch], repoRoot);
+            }
+            catch { /* best-effort */ }
+        }
+        throw err;
     }
-    const saved = getNode(meta.node_id);
-    return { node: saved, window, session };
 }

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

@@ -164,16 +164,13 @@ export declare function respawnPaneSync(opts: RespawnPaneOpts): boolean;
 /** Turn a pi argv array into a single shell command string.
  *
  *  The binary defaults to `CRTR_PI_BINARY` when that env var is set, else the
- *  literal `pi`. This is a TEST-ONLY substitution seam: when CRTR_PI_BINARY is
- *  unset (every production path) the behavior is byte-identical to exec'ing
- *  `pi`. The integration-test harness points it at a deterministic fake-pi
- *  vehicle so a real `crtr node new` reaches the fake instead of the LLM `pi`,
- *  without any dependence on tmux/shell PATH inheritance — the substitution is
- *  baked into the command string at build time, in the process that calls
- *  piCommand. An explicit `binary` arg still overrides the env (no caller passes
- *  one today). The value may be a multi-word launcher (e.g. `node --import
- *  tsx/esm host.ts`); only the argv entries are shell-quoted, so a multi-word
- *  binary is spliced verbatim ahead of them. */
+ *  bundled pi CLI launched with the current Node binary. CRTR_PI_BINARY is a
+ *  TEST-ONLY substitution seam: the integration-test harness points it at a
+ *  deterministic fake-pi vehicle so a real `crtr node new` reaches the fake
+ *  instead of the LLM pi, without depending on tmux/shell PATH inheritance. An
+ *  explicit `binary` arg still overrides the env. The value may be a multi-word
+ *  launcher (e.g. `node --import tsx/esm host.ts`); only argv entries are
+ *  shell-quoted, so a multi-word binary is spliced verbatim ahead of them. */
 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

package/dist/core/runtime/tmux.js

@@ -10,6 +10,7 @@
 import { spawnSync } from 'node:child_process';
 import { readConfig } from '../config.js';
 import { defaultCanvasNavConfig } from '../../types.js';
+import { bundledPiCommandForShell } from './pi-cli.js';
 import { surfaceTmuxStyleArgs } from './surface-bg.js';
 // ---------------------------------------------------------------------------
 // Shell quoting + tmux invocation
@@ -327,17 +328,14 @@ export function respawnPaneSync(opts) {
 /** Turn a pi argv array into a single shell command string.
  *
  *  The binary defaults to `CRTR_PI_BINARY` when that env var is set, else the
- *  literal `pi`. This is a TEST-ONLY substitution seam: when CRTR_PI_BINARY is
- *  unset (every production path) the behavior is byte-identical to exec'ing
- *  `pi`. The integration-test harness points it at a deterministic fake-pi
- *  vehicle so a real `crtr node new` reaches the fake instead of the LLM `pi`,
- *  without any dependence on tmux/shell PATH inheritance — the substitution is
- *  baked into the command string at build time, in the process that calls
- *  piCommand. An explicit `binary` arg still overrides the env (no caller passes
- *  one today). The value may be a multi-word launcher (e.g. `node --import
- *  tsx/esm host.ts`); only the argv entries are shell-quoted, so a multi-word
- *  binary is spliced verbatim ahead of them. */
-export function piCommand(argv, binary = process.env['CRTR_PI_BINARY'] ?? 'pi') {
+ *  bundled pi CLI launched with the current Node binary. CRTR_PI_BINARY is a
+ *  TEST-ONLY substitution seam: the integration-test harness points it at a
+ *  deterministic fake-pi vehicle so a real `crtr node new` reaches the fake
+ *  instead of the LLM pi, without depending on tmux/shell PATH inheritance. An
+ *  explicit `binary` arg still overrides the env. The value may be a multi-word
+ *  launcher (e.g. `node --import tsx/esm host.ts`); only argv entries are
+ *  shell-quoted, so a multi-word binary is spliced verbatim ahead of them. */
+export function piCommand(argv, binary = process.env['CRTR_PI_BINARY'] ?? bundledPiCommandForShell(shellQuote)) {
     return [binary, ...argv.map(shellQuote)].join(' ');
 }
 // ---------------------------------------------------------------------------

package/dist/core/worktree.d.ts

@@ -0,0 +1,35 @@
+import { type NodeMeta, type ManagedWorktree } from './canvas/index.js';
+export interface WorktreeCommandResult {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+}
+export declare class WorktreeError extends Error {
+    code: string;
+    next: string;
+    detail?: string;
+    constructor(code: string, message: string, next: string, detail?: string);
+}
+export declare function managedWorktreesRoot(): string;
+export declare function managedWorktreePath(nodeId: string): string;
+export declare function hasOpenManagedWorktree(node: NodeMeta | null | undefined): boolean;
+export declare function openManagedWorktreeForNode(nodeId: string): ManagedWorktree | null;
+export declare function createManagedWorktree(cwd: string, nodeId: string): ManagedWorktree;
+export declare function isRebaseInProgress(cwd: string): boolean;
+export interface CloseManagedWorktreeResult {
+    node_id: string;
+    branch: string;
+    worktree_path: string;
+    pushed_sha: string;
+    /** False when the push landed but the worktree checkout could not be removed
+     *  automatically afterward — the close still counts as done (state is
+     *  closed, push-final is unblocked); `worktree_remove_error` carries the
+     *  manual cleanup note. */
+    worktree_removed: boolean;
+    worktree_remove_error?: string;
+    /** False when the push landed but the local branch could not be deleted
+     *  afterward — same non-fatal treatment as worktree_removed. */
+    branch_deleted: boolean;
+    branch_delete_error?: string;
+}
+export declare function closeManagedWorktree(nodeId: string): CloseManagedWorktreeResult;