@crouton-kit/crouter 0.3.39 → 0.3.41

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;

package/dist/core/worktree.js

@@ -0,0 +1,158 @@
+import { existsSync, mkdirSync, rmdirSync } from 'node:fs';
+import { gitSync } from './git.js';
+import { crtrHome } from './canvas/paths.js';
+import { getNode, updateNode } from './canvas/index.js';
+export class WorktreeError extends Error {
+    code;
+    next;
+    detail;
+    constructor(code, message, next, detail) {
+        super(message);
+        this.name = 'WorktreeError';
+        this.code = code;
+        this.next = next;
+        this.detail = detail;
+    }
+}
+function runGit(cwd, args, code, next) {
+    const res = gitSync(args, cwd);
+    if (res.status !== 0) {
+        const detail = (res.stderr.trim() || res.stdout.trim()).trim();
+        throw new WorktreeError(code, `git ${args.join(' ')} failed`, next, detail);
+    }
+    return res.stdout.trim();
+}
+export function managedWorktreesRoot() {
+    return `${crtrHome()}/worktrees`;
+}
+export function managedWorktreePath(nodeId) {
+    return `${managedWorktreesRoot()}/${nodeId}`;
+}
+export function hasOpenManagedWorktree(node) {
+    return node?.managed_worktree?.state === 'open';
+}
+export function openManagedWorktreeForNode(nodeId) {
+    const node = getNode(nodeId);
+    const wt = node?.managed_worktree;
+    return wt?.state === 'open' ? wt : null;
+}
+function repoRootFor(cwd) {
+    return runGit(cwd, ['rev-parse', '--show-toplevel'], 'not_git_repo', 'Pass --cwd pointing inside a git repository.');
+}
+function requireOriginMain(repoRoot) {
+    return runGit(repoRoot, ['rev-parse', 'origin/main'], 'missing_origin_main', 'Managed worktrees land by rebasing onto origin/main. Fetch/create origin/main, then retry.');
+}
+export function createManagedWorktree(cwd, nodeId) {
+    const repoRoot = repoRootFor(cwd);
+    const baseSha = requireOriginMain(repoRoot);
+    const path = managedWorktreePath(nodeId);
+    if (existsSync(path)) {
+        throw new WorktreeError('worktree_path_exists', `managed worktree path already exists: ${path}`, 'Remove the stale path or choose a fresh node id.');
+    }
+    const branch = `crtr/${nodeId}`;
+    runGit(repoRoot, ['worktree', 'add', '-b', branch, path, 'origin/main'], 'worktree_add_failed', 'Inspect the git error, fix the repository/worktree state, then retry spawning with --worktree.');
+    return {
+        state: 'open',
+        path,
+        branch,
+        repo_root: repoRoot,
+        base_ref: 'origin/main',
+        base_sha: baseSha,
+        created: new Date().toISOString(),
+    };
+}
+function statusPorcelain(cwd) {
+    return runGit(cwd, ['status', '--porcelain'], 'status_failed', 'Inspect the worktree manually, then retry.');
+}
+function currentBranch(cwd) {
+    return runGit(cwd, ['rev-parse', '--abbrev-ref', 'HEAD'], 'branch_check_failed', 'Inspect the worktree manually, then retry.');
+}
+function gitPath(cwd, logicalPath) {
+    return runGit(cwd, ['rev-parse', '--git-path', logicalPath], 'git_path_failed', 'Inspect the worktree manually, then retry.');
+}
+export function isRebaseInProgress(cwd) {
+    return existsSync(gitPath(cwd, 'rebase-merge')) || existsSync(gitPath(cwd, 'rebase-apply'));
+}
+export function closeManagedWorktree(nodeId) {
+    const node = getNode(nodeId);
+    if (node === null) {
+        throw new WorktreeError('unknown_node', `unknown node: ${nodeId}`, 'Run this from a live node, or pass a real node id once that command supports it.');
+    }
+    const wt = openManagedWorktreeForNode(nodeId);
+    if (wt === null) {
+        throw new WorktreeError('no_managed_worktree', `node ${nodeId} has no open managed worktree`, 'Nothing to close for this node.');
+    }
+    if (!existsSync(wt.path)) {
+        throw new WorktreeError('worktree_missing', `managed worktree path is missing: ${wt.path}`, 'Ask the human with `crtr human ask` before changing node state; the checkout disappeared outside crouter.');
+    }
+    if (isRebaseInProgress(wt.path)) {
+        throw new WorktreeError('rebase_in_progress', 'this managed worktree is mid-rebase', `Resolve conflicts in ${wt.path}, run \`git rebase --continue\` there, then rerun \`crtr worktree close\`.`);
+    }
+    const dirty = statusPorcelain(wt.path);
+    if (dirty !== '') {
+        throw new WorktreeError('dirty_worktree', 'managed worktree has uncommitted changes', `Commit the work in ${wt.path} (or ask the human with \`crtr human ask\` if you do not know whether to keep it), then rerun \`crtr worktree close\`.`);
+    }
+    const branch = currentBranch(wt.path);
+    if (branch !== wt.branch) {
+        const found = branch === 'HEAD' ? 'detached HEAD' : branch;
+        throw new WorktreeError('wrong_branch', `managed worktree is not on its recorded branch (expected ${wt.branch}, found ${found})`, `Check out ${wt.branch} in ${wt.path} before closing, or ask the human with \`crtr human ask\` if you are unsure why it changed, then rerun \`crtr worktree close\`.`);
+    }
+    runGit(wt.path, ['fetch', 'origin', 'main'], 'fetch_failed', 'Network/remote state blocked landing. Ask the human with `crtr human ask` if this is not a transient git/network issue.');
+    const rebase = gitSync(['rebase', 'origin/main'], wt.path);
+    if (rebase.status !== 0) {
+        const detail = (rebase.stderr.trim() || rebase.stdout.trim()).trim();
+        throw new WorktreeError('rebase_failed', 'rebase onto origin/main did not complete', `Resolve conflicts in ${wt.path}, run \`git rebase --continue\` there, then rerun \`crtr worktree close\`. If the blocker is not mechanical, ask the human with \`crtr human ask\`.`, detail);
+    }
+    const push = gitSync(['push', 'origin', 'HEAD:main'], wt.path);
+    if (push.status !== 0) {
+        const detail = (push.stderr.trim() || push.stdout.trim()).trim();
+        throw new WorktreeError('push_main_failed', 'could not fast-forward/push origin/main from this worktree', 'Do not force-push main. Ask the human with `crtr human ask` how to land this managed worktree.', detail);
+    }
+    // The push landing IS the point of no return: persist `state: 'closed'`
+    // IMMEDIATELY, before reading the landed sha or attempting any cleanup below.
+    // Worktree removal and branch deletion are best-effort from here on — their
+    // failure is cosmetic (a stray checkout / local ref) and must never re-strand
+    // `state: 'open'` behind a dead end that permanently blocks push-final.
+    updateNode(nodeId, { managed_worktree: { ...wt, state: 'closed', closed: new Date().toISOString() } });
+    const pushedSha = runGit(wt.path, ['rev-parse', 'HEAD'], 'pushed_sha_failed', 'The branch landed and the node is already marked closed, but crouter could not read the landed commit SHA. Inspect the checkout manually to confirm the landed commit; no further close action is needed.');
+    const remove = gitSync(['worktree', 'remove', wt.path], wt.repo_root);
+    const worktreeRemoved = remove.status === 0;
+    if (worktreeRemoved && existsSync(wt.path)) {
+        // `git worktree remove` can leave the (now empty) mount dir behind; tidy it best-effort.
+        try {
+            rmdirSync(wt.path);
+        }
+        catch { /* non-empty or busy — leave it */ }
+    }
+    // wt.path IS the calling node's own pi-process cwd — a process can never chdir
+    // itself out of a directory that vanishes out from under it, so once removal
+    // deletes it every subsequent bash/chdir in this node fails permanently and the
+    // mandated post-close `crtr push final` can never run. Recreate it as an empty
+    // tombstone directory so the path still resolves; the branch is already landed
+    // and `state: 'closed'` already persisted above, so this is purely about keeping
+    // the node's cwd alive, not about worktree bookkeeping.
+    if (!existsSync(wt.path)) {
+        try {
+            mkdirSync(wt.path, { recursive: true });
+        }
+        catch { /* best-effort; leaves cwd broken only if this also fails */ }
+    }
+    const worktreeRemoveError = worktreeRemoved
+        ? undefined
+        : `local worktree checkout at ${wt.path} landed but could not be removed automatically (${(remove.stderr.trim() || remove.stdout.trim()).trim()}); run \`git -C ${wt.repo_root} worktree remove ${wt.path}\` after confirming it is safe to delete.`;
+    const branchDelete = gitSync(['branch', '-d', wt.branch], wt.repo_root);
+    const branchDeleted = branchDelete.status === 0;
+    const branchDeleteError = branchDeleted
+        ? undefined
+        : `local branch ${wt.branch} landed but could not be deleted automatically; run \`git -C ${wt.repo_root} branch -d ${wt.branch}\` after confirming it is merged.`;
+    return {
+        node_id: nodeId,
+        branch: wt.branch,
+        worktree_path: wt.path,
+        pushed_sha: pushedSha,
+        worktree_removed: worktreeRemoved,
+        ...(worktreeRemoveError !== undefined ? { worktree_remove_error: worktreeRemoveError } : {}),
+        branch_deleted: branchDeleted,
+        ...(branchDeleteError !== undefined ? { branch_delete_error: branchDeleteError } : {}),
+    };
+}