@crouton-kit/crouter 0.3.14 → 0.3.15

package/dist/core/runtime/reset.js

@@ -1,67 +1,91 @@
-// Root reset — the `/new` equivalent.
+// Root reset + relaunch — the `/new` equivalents, plus clean-exit termination.
 //
 // A live pi process is bound to one node via CRTR_NODE_ID (set at launch, not
-// rebindable mid-process). When the user runs `/new`, the conversation is reset
-// but the process — and thus the node id — stays the same. To make `/new`
-// behave like re-running `crtr` (a brand-new graph on the canvas) we reset the
-// root in place: reap its entire descendant sub-DAG, detach its subscriptions,
-// and wipe its working state, then re-point it at a fresh base persona and the
-// new pi session id. The node keeps its id; from the dashboard/nav it is a
-// pristine root with an empty graph.
+// rebindable mid-process). When the user runs `/new`, the conversation resets
+// but the OS process — and thus the node id — stays the same. To make `/new`
+// behave like re-running `crtr` we have two strategies:
+//
+//   • relaunchRoot (option C) — for a ROOT in a tmux pane: PARK the old root
+//     (mark done, keep its id/edges/pi_session_id intact as history), mint a
+//     FRESH node id, and re-exec pi in the current pane bound to the new id.
+//     The old id never changes meaning; external refs stay valid.
+//   • resetRoot (fallback) — for a non-root child (session-id refresh only) or
+//     a root with no pane (no tmux): the legacy in-place reset of the SAME id.
+//
+// Termination semantics: a pi that ends cleanly resolves its node to `done`
+// (markCleanExitDone); only a true crash leaves it `dead`. A force-kill
+// (closeWindow / respawn-pane -k) fires NO clean session_shutdown, so reaped
+// descendants are marked `done` explicitly here.
 //
 // Best-effort throughout: a tmux/fs failure on one node never aborts the reset.
 import { existsSync, rmSync } from 'node:fs';
-import { getNode, updateNode, setStatus, subscriptionsOf, unsubscribe, view, reportsDir, inboxPath, } from '../canvas/index.js';
-import { closeWindow, windowAlive } from './tmux.js';
+import { getNode, updateNode, setPresence, clearPid, subscriptionsOf, unsubscribe, view, reportsDir, inboxPath, nodeDir, openDb, } from '../canvas/index.js';
+import { transition } from './lifecycle.js';
+import { paneLocation, nodeSession } from './tmux.js';
+import { tearDownNode } from './placement.js';
 import { buildLaunchSpec } from './launch.js';
 import { roadmapPath } from './roadmap.js';
-/** Reset a root node to a pristine, empty graph (the `/new` semantics).
+import { spawnNode, newNodeId } from './nodes.js';
+import { setFocus } from './presence.js';
+import { relaunchRootInPane } from './revive.js';
+// ---------------------------------------------------------------------------
+// reapDescendants — tear down a root's descendant sub-DAG (shared helper)
+// ---------------------------------------------------------------------------
+/** Reap the descendant sub-DAG of `rootId`: mark each **done** (the user moved
+ *  on — a clean teardown, NOT a fault) + clear intent FIRST, then kill its
+ *  window (closes the daemon revive race). Edges are LEFT INTACT — descendants
+ *  keep parent=rootId. No wipe. Returns the reaped ids.
+ *
+ *  Why `done`, and why marking is STILL explicit: a `closeWindow`/`respawn-pane
+ *  -k` kill is abrupt and fires NO clean `session_shutdown`, so the general
+ *  quit→done rule does NOT auto-resolve a force-killed descendant — we mark it
+ *  `done` here. Shared by relaunchRoot (option C) and resetRoot's in-place
+ *  fallback, so both leave their descendants `done`. */
+export function reapDescendants(rootId) {
+    const reaped = [];
+    for (const id of view(rootId)) {
+        try {
+            // Reap BEFORE tearing down the placement (the crash-safety invariant the
+            // `reap` event encodes): a non-supervised status + cleared intent first, so
+            // the daemon can't revive a descendant mid-teardown. tearDownNode then
+            // closes any focus row it held, kills its pane (pane-keyed), and nulls its
+            // LOCATION.
+            transition(id, 'reap');
+            tearDownNode(id);
+            reaped.push(id);
+        }
+        catch {
+            /* one bad node never aborts the reap */
+        }
+    }
+    return reaped;
+}
+/** Reset a root node to a pristine, empty graph (the legacy `/new` semantics —
+ *  now used as the no-pane fallback and the non-root session-id refresh).
  *
  *  For a non-root (spawned child), a `/new` is not a graph reset — we only
- *  refresh its session id so a later `--resume` wakes the right conversation. */
-export function resetRoot(nodeId, newSessionId) {
+ *  refresh its session id so a later `--session <id>` wakes the right conversation. */
+export function resetRoot(nodeId, newSessionId, newSessionFile) {
     const meta = getNode(nodeId);
     if (meta === null)
         return { reaped: [], detached: [], reset: false };
     // Only roots own a graph in the "ran crtr again" sense.
     if (meta.parent != null) {
         if (newSessionId !== undefined) {
-            try {
-                updateNode(nodeId, { pi_session_id: newSessionId });
-            }
-            catch { /* */ }
+            updateNode(nodeId, {
+                pi_session_id: newSessionId,
+                ...(newSessionFile !== undefined ? { pi_session_file: newSessionFile } : {}),
+            });
         }
         return { reaped: [], detached: [], reset: false };
     }
-    // 1) Reap the descendant sub-DAG. Mark dead + clear intent FIRST, then kill
-    //    the window: the daemon revives on a window-gone + intent==='refresh'
-    //    (or 'idle-release'), so flipping to dead before the window dies closes
-    //    the race where a descendant mid-yield gets revived as we tear it down.
-    const reaped = [];
-    for (const id of view(nodeId)) {
-        try {
-            const dmeta = getNode(id);
-            setStatus(id, 'dead');
-            updateNode(id, { intent: null });
-            if (dmeta !== null && windowAlive(dmeta.tmux_session, dmeta.window)) {
-                closeWindow(dmeta.window);
-            }
-            reaped.push(id);
-        }
-        catch {
-            /* one bad node never aborts the reset */
-        }
-    }
+    // 1) Reap the descendant sub-DAG (mark done + kill windows; shared helper).
+    const reaped = reapDescendants(nodeId);
     // 2) Detach the root's own subscriptions so its view is empty.
     const detached = [];
     for (const sub of subscriptionsOf(nodeId)) {
-        try {
-            unsubscribe(nodeId, sub.node_id);
-            detached.push(sub.node_id);
-        }
-        catch {
-            /* */
-        }
+        unsubscribe(nodeId, sub.node_id);
+        detached.push(sub.node_id);
     }
     // 3) Wipe the root's working state (reports / inbox / roadmap).
     for (const p of [
@@ -78,20 +102,167 @@ export function resetRoot(nodeId, newSessionId) {
             /* */
         }
     }
-    // 4) Re-point the root at a fresh base persona + the new pi session id.
+    // 4) Re-point the root at a fresh base persona + the new pi session id. A
+    //    root is resident by definition (this only runs on roots — see the early
+    //    return above), so resetting to base/resident is the model, not a bypass.
+    //    Re-seed persona_ack to the fresh persona so the pristine `/new`
+    //    conversation never gets a spurious mode/lifecycle transition steer (the
+    //    persona injector compares against this ack).
+    const { launch } = buildLaunchSpec(meta.kind, 'base', { lifecycle: 'resident', hasManager: false });
+    updateNode(nodeId, {
+        mode: 'base',
+        lifecycle: 'resident',
+        persona_ack: { mode: 'base', lifecycle: 'resident' },
+        launch,
+        ...(newSessionId !== undefined ? { pi_session_id: newSessionId } : {}),
+        ...(newSessionFile !== undefined ? { pi_session_file: newSessionFile } : {}),
+    });
+    transition(nodeId, 'revive');
+    return { reaped, detached, reset: true };
+}
+/** The single entry the stophook calls on a detected `/new` (session id change).
+ *  Policy lives here so the stophook stays thin and this stays unit-testable:
+ *    - non-root child          → resetRoot(nodeId, newSessionId)  (session-id refresh only)
+ *    - root + pane present      → relaunchRoot(nodeId, pane)        (option C)
+ *    - root + no pane (no tmux) → resetRoot(nodeId, newSessionId)  (in-place fallback)
+ *  On a respawn-dispatch failure the live pi never died, so we degrade to the
+ *  legacy in-place reset. */
+export function handleNewSession(nodeId, newSessionId, pane, deps = {}, newSessionFile) {
+    const meta = getNode(nodeId);
+    if (meta === null)
+        return { path: 'noop' };
+    // Non-root child: a `/new` only refreshes its session id (unchanged).
+    if (meta.parent != null) {
+        resetRoot(nodeId, newSessionId, newSessionFile);
+        return { path: 'reset-child' };
+    }
+    // Root with no pane (not inside tmux): in-place reset fallback. Option C needs
+    // a pane to respawn into; resetRoot needs the new session id (available here
+    // because the trigger is session_start).
+    if (pane === undefined || pane.trim() === '') {
+        resetRoot(nodeId, newSessionId, newSessionFile);
+        return { path: 'reset-root' };
+    }
+    // Root with a pane: option C relaunch. relaunchRoot self-rolls-back its DB
+    // writes on a respawn-dispatch failure and rethrows; we then degrade to the
+    // legacy in-place reset (the live pi is still alive, never killed).
+    try {
+        const result = relaunchRoot(nodeId, pane, deps);
+        if (result === null)
+            return { path: 'noop' }; // defensive guard hit (e.g. rapid double /new)
+        return { path: 'relaunch', newNodeId: result.newNodeId };
+    }
+    catch {
+        setFocus(nodeId);
+        resetRoot(nodeId, newSessionId, newSessionFile);
+        return { path: 'reset-root' };
+    }
+}
+/** Park the old root + create+launch a fresh root in `pane` (option C). All DB
+ *  writes are synchronous and happen BEFORE the respawn (the respawn kills the
+ *  caller). Returns the new node id, or null on a defensive guard (not a root /
+ *  already parked). Throws only if the respawn dispatch fails — and self-rolls-
+ *  back its writes first so the caller can degrade to resetRoot. */
+export function relaunchRoot(oldId, pane, deps = {}) {
+    const oldMeta = getNode(oldId);
+    if (oldMeta === null || oldMeta.parent != null)
+        return null; // defensive: not a root
+    if (oldMeta.status === 'done')
+        return null; // defensive: already parked (rapid double /new)
+    const respawn = deps.relaunchRootInPane ?? relaunchRootInPane;
+    // Resolve where the new pi will live (pane authoritative; fall back to old
+    // meta when paneLocation can't resolve, e.g. outside a live tmux server).
+    const loc = paneLocation(pane) ?? {
+        session: oldMeta.tmux_session ?? null,
+        window: oldMeta.window ?? null,
+    };
+    const newId = newNodeId();
+    const { launch } = buildLaunchSpec(oldMeta.kind, 'base', { lifecycle: 'resident', hasManager: false });
+    // Park-old + mint-new is the single most fragile spot in the runtime, so it is
+    // ONE atomic unit: every ROW write below runs inside a sqlite transaction. A
+    // failure anywhere — including the respawn DISPATCH — rolls the whole thing
+    // back, leaving the old root EXACTLY as it was (no hand-rolled compensation).
+    // Only the *detached* respawn (the async pane kill) lands outside the txn — it
+    // must, since it kills this caller, and by then COMMIT has made the new state
+    // durable. setFocus is a file write, not in the txn; the catch restores it.
+    const db = openDb();
+    db.exec('BEGIN');
     try {
-        const { launch } = buildLaunchSpec(meta.kind, 'base');
-        updateNode(nodeId, {
+        // 1) Reap descendants (mark done + kill windows, keep edges, no wipe).
+        reapDescendants(oldId);
+        // 2) Create the fresh root node (new id, empty context dir via
+        //    ensureNodeDirs) seeded active; `yield` adds the refresh safety net so
+        //    that if the pane dies before boot the daemon revives it in a new window.
+        spawnNode({
+            kind: oldMeta.kind,
             mode: 'base',
             lifecycle: 'resident',
-            intent: null,
-            status: 'active',
+            cwd: oldMeta.cwd,
+            name: oldMeta.kind,
+            parent: null,
+            spawnedBy: oldId, // audit-only successor link; does NOT touch the spine
+            nodeId: newId,
             launch,
-            ...(newSessionId !== undefined ? { pi_session_id: newSessionId } : {}),
         });
+        transition(newId, 'yield'); // active (from spawn) + intent=refresh safety net
+        setPresence(newId, { tmux_session: loc.session, window: loc.window });
+        // REVIVE-HOME: the relaunched root's durable revive target is the session
+        // of the pane it is respawned into (same pane-recycle rule as demote).
+        updateNode(newId, { home_session: loc.session ?? nodeSession() });
+        clearPid(newId); // no pi yet → daemon 'leave' until boot records the pid
+        // 3) Park the old root: reap (done + intent cleared) and detach its window so
+        //    it never claims the pane, but KEEP pi_session_id (resumable),
+        //    parent=null, and all edges.
+        transition(oldId, 'reap');
+        setPresence(oldId, { window: null, tmux_session: null });
+        // 4) Focus follows content (file write — restored by the catch on rollback).
+        setFocus(newId);
+        // 5) Re-exec pi in this pane bound to newId; the dispatch is the LAST thing
+        //    inside the txn. If it throws the txn rolls back (old root untouched); on
+        //    success we COMMIT and the async detached kill of this pane lands after.
+        respawn(newId, pane);
+        db.exec('COMMIT');
     }
-    catch {
-        /* */
+    catch (err) {
+        // Dispatch failed (or a write threw) — the live pi never died. Roll the whole
+        // transaction back so the old root is FULLY restored, then degrade.
+        try {
+            db.exec('ROLLBACK');
+        }
+        catch { /* */ }
+        // The rolled-back new node's row is gone, but spawnNode already scaffolded its
+        // on-disk dir (ensureNodeDirs). With no row, prune never sees it — so remove
+        // the orphan dir here, otherwise it is permanent disk litter on this rare path.
+        try {
+            rmSync(nodeDir(newId), { recursive: true, force: true });
+        }
+        catch { /* */ }
+        try {
+            setFocus(oldId);
+        }
+        catch { /* */ } // focus is a file op, outside the txn
+        throw err instanceof Error ? err : new Error(String(err));
     }
-    return { reaped, detached, reset: true };
+    return { newNodeId: newId };
+}
+// ---------------------------------------------------------------------------
+// markCleanExitDone — the clean-exit→done termination guard
+// ---------------------------------------------------------------------------
+/** Resolve a cleanly-exiting node to `done`. Returns true iff it transitioned.
+ *  Guard: only a real quit, and only a node still active|idle with no pending
+ *  intent — so it never clobbers a node already routed by agent_end to done
+ *  (push final), refresh (yield), or idle-release. Pure/DB-only (no pi/tmux) so
+ *  the guard is unit-testable without a live pi. */
+export function markCleanExitDone(nodeId, reason) {
+    if (reason !== 'quit')
+        return false; // new/reload/resume/fork → no-op
+    const meta = getNode(nodeId);
+    if (meta === null)
+        return false;
+    if (meta.status !== 'active' && meta.status !== 'idle')
+        return false; // already done/dead/canceled
+    if (meta.intent != null)
+        return false; // refresh / idle-release in flight
+    transition(nodeId, 'finalize');
+    return true;
 }

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

@@ -1,9 +1,21 @@
+import { type NodeMeta } from '../canvas/index.js';
+import { type RespawnPaneOpts } from './tmux.js';
+/** Pick the `--session` source for a revive. resume=true prefers the absolute
+ *  session-file path (immune to cwd; pi opens it directly) and keeps the bare
+ *  session id as the fallback for older nodes booted before pi_session_file was
+ *  captured. buildPiArgv prefers the path when both are present. resume=false (a
+ *  refresh-yield) selects neither — the node re-reads its roadmap fresh. Pure so
+ *  the path-vs-id selection is unit-testable without tmux. */
+export declare function resumeArgs(meta: NodeMeta, resume: boolean): {
+    resumeSessionId?: string;
+    resumeSessionPath?: string;
+};
 export interface ReviveResult {
     /** The new tmux window id, or null if openNodeWindow failed. */
     window: string | null;
     /** The tmux session the node was placed in. */
     session: string;
-    /** True when pi was instructed to resume its saved conversation (`--resume`). */
+    /** True when pi was instructed to resume its saved conversation (`--session <id>`). */
     resumed: boolean;
 }
 /** Open a fresh background tmux window for `nodeId` and update canvas meta.
@@ -23,4 +35,16 @@ export declare function reviveNode(nodeId: string, opts: {
  *  `pane` is the target pane id (the yielding node reads it from $TMUX_PANE).
  *  Throws on unknown node or when the respawn could not be dispatched, so the
  *  caller can fall back to a plain shutdown (daemon revives in a new window). */
-export declare function reviveInPlace(nodeId: string, pane: string): ReviveResult;
+export declare function reviveInPlace(nodeId: string, pane: string, respawn?: (opts: RespawnPaneOpts) => boolean): ReviveResult;
+/** Re-exec a FRESH pi for `nodeId` in EXISTING `pane` (respawn-pane -k), with
+ *  NO prompt and NO resume — a clean root conversation (goal-capture /
+ *  context-intro handle the first message + bearings, exactly like bare
+ *  `crtr`). Unlike reviveInPlace: no buildReviveKickoff prompt, no cycles bump,
+ *  and it sets CRTR_FRONT_DOOR=1 (REQUIRED — src/core/runtime/CLAUDE.md: any
+ *  path that boots a pi must guard against a removed/renamed subcommand
+ *  fork-bombing). Throws if the respawn could not be dispatched.
+ *
+ *  Used by relaunchRoot (reset.ts) for the `/new`-in-a-root relaunch. Kept
+ *  SEPARATE from reviveInPlace so the refresh-yield path's exact semantics
+ *  (kickoff + cycle bump) are untouched. */
+export declare function relaunchRootInPane(nodeId: string, pane: string): void;

package/dist/core/runtime/revive.js

@@ -2,16 +2,55 @@
 // window. Used by both the supervisor daemon (on crash/refresh detection) and
 // the explicit `crtr canvas revive` command.
 //
-// A revive always opens a NEW window: the old one is gone (crashed, or the
-// node exited with intent=refresh). The node's persisted LaunchSpec and cwd
-// are the canonical recipe; reviveNode replays them faithfully.
+// A revive replays the node's persisted LaunchSpec + cwd (the canonical recipe)
+// and routes PLACEMENT through reviveIntoPlacement (§1.4): a non-focused node
+// opens a fresh background window in its home_session (the backstage `crtr` for
+// a child — NEVER a user session); a node that occupies a LIVE focus resumes IN
+// PLACE in that focus pane (respawn-pane -k, no new window). reviveNode never
+// targets meta.tmux_session, so a background revive can no longer open an
+// unbidden window in the user's session.
 //
-//   resume=true  → `pi --resume <pi_session_id>` — wakes the saved conversation.
+//   resume=true  → `pi --session <path|id>` — wakes the saved conversation,
+//                  preferring the absolute session-file path (cwd-immune) over
+//                  the bare session id.
 //   resume=false → fresh pi invocation — the node re-reads its roadmap/context dir.
-import { getNode, updateNode, } from '../canvas/index.js';
+import { getNode, updateNode, setPresence, clearPid, fullName, } from '../canvas/index.js';
+import { transition } from './lifecycle.js';
 import { buildPiArgv } from './launch.js';
-import { buildReviveKickoff } from './kickoff.js';
-import { ensureSession, openNodeWindow, piCommand, respawnPane, nodeSession, } from './tmux.js';
+import { buildReviveKickoff, drainBearings } from './kickoff.js';
+import { FRONT_DOOR_ENV } from './front-door.js';
+import { piCommand, respawnPane, nodeSession } from './tmux.js';
+import { reviveIntoPlacement, reconcile, isNodePaneAlive, homeSessionOf } from './placement.js';
+/** signal-0 liveness probe for a pi pid (mirrors the daemon's isPidAlive). A
+ *  null pid (legacy / never-booted) reads dead. */
+function pidAlive(pid) {
+    if (pid == null)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
+// ---------------------------------------------------------------------------
+// resumeArgs — which session source a revive resumes from
+// ---------------------------------------------------------------------------
+/** Pick the `--session` source for a revive. resume=true prefers the absolute
+ *  session-file path (immune to cwd; pi opens it directly) and keeps the bare
+ *  session id as the fallback for older nodes booted before pi_session_file was
+ *  captured. buildPiArgv prefers the path when both are present. resume=false (a
+ *  refresh-yield) selects neither — the node re-reads its roadmap fresh. Pure so
+ *  the path-vs-id selection is unit-testable without tmux. */
+export function resumeArgs(meta, resume) {
+    if (!resume)
+        return {};
+    return {
+        resumeSessionId: meta.pi_session_id ?? undefined,
+        resumeSessionPath: meta.pi_session_file ?? undefined,
+    };
+}
 // ---------------------------------------------------------------------------
 // reviveNode
 // ---------------------------------------------------------------------------
@@ -25,35 +64,63 @@ export function reviveNode(nodeId, opts) {
     if (meta === null) {
         throw new Error(`reviveNode: unknown node ${nodeId}`);
     }
-    // The node lives in the shared global session. Prefer its stored session
-    // (an inline root tracks its own real terminal session); fall back to the
-    // shared node session.
-    const session = meta.tmux_session ?? nodeSession();
-    ensureSession(session, meta.cwd);
-    // Decide whether to wake the saved pi conversation or start fresh.
-    const resumeId = opts.resume && meta.pi_session_id != null
-        ? meta.pi_session_id
-        : undefined;
+    // Double-revive guard (pane-keyed, §2.4): reconcile FIRST so a user-moved pane
+    // isn't misread as "not yet revived", then probe pane-existence. A node whose
+    // pane is alive AND whose pi is still RUNNING was already revived by another
+    // path; re-launching would put a SECOND pi on the same session file — no-op.
+    // A FROZEN focus pane (remain-on-exit, F3) is pane-alive but pi-DEAD: that is
+    // the resume-into-focus case and MUST proceed (respawn-pane -k back into the
+    // frozen pane), so the guard gates on pi liveness too, not pane-existence alone.
+    reconcile(nodeId);
+    const live = getNode(nodeId) ?? meta;
+    if (isNodePaneAlive(nodeId) && pidAlive(live.pi_pid)) {
+        return {
+            window: live.window ?? null,
+            session: live.tmux_session ?? nodeSession(),
+            resumed: false,
+        };
+    }
+    // Every (re)launch is a new cycle — bump the counter so the editor label's
+    // trailing N advances. Mutate the in-memory meta too so buildPiArgv below
+    // builds the label with the incremented count.
+    meta.cycles = (meta.cycles ?? 0) + 1;
+    updateNode(nodeId, { cycles: meta.cycles });
+    // Decide whether to wake the saved pi conversation or start fresh. Prefer the
+    // absolute session-file path (cwd-immune); fall back to the bare id.
+    const resume = resumeArgs(meta, opts.resume);
+    const resuming = resume.resumeSessionPath !== undefined || resume.resumeSessionId !== undefined;
     // A fresh revive (no resume) gets a kickoff prompt so it re-reads its roadmap
-    // and continues; resuming a saved conversation needs none.
-    const inv = resumeId !== undefined
-        ? buildPiArgv(meta, { resumeSessionId: resumeId })
-        : buildPiArgv(meta, { prompt: buildReviveKickoff(meta) });
-    const env = { ...inv.env, CRTR_ROOT_SESSION: session };
-    const window = openNodeWindow({
-        session,
-        name: meta.name,
-        cwd: meta.cwd,
-        env,
+    // and continues; resuming a saved conversation needs none. drainBearings is the
+    // one-shot consuming step (yield note + feed cursor + persona ack); the builder
+    // is then pure.
+    let inv;
+    if (resuming) {
+        inv = buildPiArgv(meta, resume);
+    }
+    else {
+        const bearings = drainBearings(meta);
+        inv = buildPiArgv(meta, { prompt: buildReviveKickoff(meta, bearings) });
+    }
+    // Placement owns WHERE this revive lands (§1.4): resume into a live focus pane
+    // if the node occupies one, else a fresh window in its home_session (the
+    // backstage `crtr` for a child — NEVER a user session). reviveIntoPlacement
+    // performs the one atomic setPresence; reviveNode keeps transition+clearPid
+    // around it (the crash-safety ordering, unchanged). THIS is the bug-kill: a
+    // non-focused background revive can no longer new-window into a user session.
+    transition(nodeId, 'revive');
+    const placed = reviveIntoPlacement(nodeId, {
         command: piCommand(inv.argv),
+        env: inv.env,
+        cwd: meta.cwd,
+        name: fullName(meta),
+        resuming,
     });
-    updateNode(nodeId, {
-        status: 'active',
-        intent: null,
-        window,
-        tmux_session: session,
-    });
-    return { window, session, resumed: resumeId !== undefined };
+    // Window-backed launch: clear the stale pid so the daemon won't re-fire on
+    // it during the new pi's boot. The fresh pi re-records its pid on
+    // session_start; if it never boots, this window closes and the window-gone
+    // pass reaps it.
+    clearPid(nodeId);
+    return { window: placed.window, session: placed.session, resumed: resuming };
 }
 // ---------------------------------------------------------------------------
 // reviveInPlace — refresh-yield without churning the window
@@ -67,21 +134,81 @@ export function reviveNode(nodeId, opts) {
  *  `pane` is the target pane id (the yielding node reads it from $TMUX_PANE).
  *  Throws on unknown node or when the respawn could not be dispatched, so the
  *  caller can fall back to a plain shutdown (daemon revives in a new window). */
-export function reviveInPlace(nodeId, pane) {
+export function reviveInPlace(nodeId, pane, respawn = respawnPane) {
     const meta = getNode(nodeId);
     if (meta === null) {
         throw new Error(`reviveInPlace: unknown node ${nodeId}`);
     }
+    // A refresh-yield is a cycle too — advance the label's trailing N.
+    meta.cycles = (meta.cycles ?? 0) + 1;
+    updateNode(nodeId, { cycles: meta.cycles });
+    // The node's LOCATION — the session its pane physically lives in. The re-exec
+    // is IN PLACE (the pane never moves), so this is preserved unchanged below.
     const session = meta.tmux_session ?? nodeSession();
     // Fresh re-exec: same recipe as a no-resume reviveNode, with the kickoff so
-    // the node rebuilds its bearings from disk.
-    const inv = buildPiArgv(meta, { prompt: buildReviveKickoff(meta) });
-    const env = { ...inv.env, CRTR_ROOT_SESSION: session };
-    const ok = respawnPane({ pane, cwd: meta.cwd, env, command: piCommand(inv.argv) });
+    // the node rebuilds its bearings from disk. Drain the one-shot bearings first,
+    // then build purely.
+    const bearings = drainBearings(meta);
+    const inv = buildPiArgv(meta, { prompt: buildReviveKickoff(meta, bearings) });
+    // CRTR_ROOT_SESSION is the backstage this node's CHILDREN spawn into — it must
+    // be the durable REVIVE-HOME (home_session), NOT the pane's live `session`. A
+    // FOCUSED child's pane is in a USER session (focus taints meta.tmux_session),
+    // so sourcing it from `session` would land any child it spawns in the user's
+    // session, re-tainting that child's home_session (A-MAJOR-1). home_session is
+    // the taint-immune backstage `crtr` for a child; for a root it equals its own
+    // session, so this is behavior-preserving there.
+    const env = { ...inv.env, CRTR_ROOT_SESSION: homeSessionOf(nodeId) };
+    const ok = respawn({ pane, cwd: meta.cwd, env, command: piCommand(inv.argv) });
     if (!ok) {
         throw new Error(`reviveInPlace: respawn-pane dispatch failed for ${nodeId}`);
     }
-    updateNode(nodeId, { status: 'active', intent: null, tmux_session: session });
+    // Deliberately DO NOT clear intent here, and DO NOT touch pi_pid. The detached
+    // respawn-pane can't confirm it actually replaced the pi (it kills this very
+    // process mid-flight), so clearing intent optimistically is how a failed
+    // refresh became a silent death: the fresh pi never boots, yet meta says the
+    // refresh completed. Instead we leave intent='refresh' (the fresh pi clears it
+    // on boot — the only proof the respawn worked) and leave pi_pid as the OLD
+    // pid. If the respawn succeeds, the old pi dies and the fresh one overwrites
+    // pid+intent within the daemon's grace window; if it fails, the old pid stays
+    // dead and the daemon's pi-liveness pass revives the node.
+    transition(nodeId, 'boot');
+    // tmux_session may have resolved to the shared session; window is unchanged
+    // (we re-execed in place), so preserve it explicitly.
+    setPresence(nodeId, { tmux_session: session, window: meta.window ?? null });
     // Window is unchanged (we re-execed in place); report the existing one.
     return { window: meta.window ?? null, session, resumed: false };
 }
+// ---------------------------------------------------------------------------
+// relaunchRootInPane — boot a CLEAN fresh root in the current pane (option C)
+// ---------------------------------------------------------------------------
+/** Re-exec a FRESH pi for `nodeId` in EXISTING `pane` (respawn-pane -k), with
+ *  NO prompt and NO resume — a clean root conversation (goal-capture /
+ *  context-intro handle the first message + bearings, exactly like bare
+ *  `crtr`). Unlike reviveInPlace: no buildReviveKickoff prompt, no cycles bump,
+ *  and it sets CRTR_FRONT_DOOR=1 (REQUIRED — src/core/runtime/CLAUDE.md: any
+ *  path that boots a pi must guard against a removed/renamed subcommand
+ *  fork-bombing). Throws if the respawn could not be dispatched.
+ *
+ *  Used by relaunchRoot (reset.ts) for the `/new`-in-a-root relaunch. Kept
+ *  SEPARATE from reviveInPlace so the refresh-yield path's exact semantics
+ *  (kickoff + cycle bump) are untouched. */
+export function relaunchRootInPane(nodeId, pane) {
+    const meta = getNode(nodeId);
+    if (meta === null) {
+        throw new Error(`relaunchRootInPane: unknown node ${nodeId}`);
+    }
+    // No prompt, no resume → a brand-new root conversation at cycle 0.
+    const inv = buildPiArgv(meta, {});
+    // Source CRTR_ROOT_SESSION from the durable REVIVE-HOME (home_session), the
+    // same taint-immunity rule as reviveInPlace. relaunchRootInPane runs only on a
+    // root, whose home_session IS its own session, so this is behavior-preserving
+    // — it keeps both in-pane revive paths sourced identically.
+    const env = { ...inv.env, CRTR_ROOT_SESSION: homeSessionOf(nodeId), [FRONT_DOOR_ENV]: '1' };
+    const ok = respawnPane({ pane, cwd: meta.cwd, env, command: piCommand(inv.argv) });
+    if (!ok) {
+        throw new Error(`relaunchRootInPane: respawn-pane dispatch failed for ${nodeId}`);
+    }
+    // Do NOT clear intent/pi_pid here — the fresh pi clears intent='refresh' on
+    // its session_start boot (the only proof the respawn worked), same dance as
+    // reviveInPlace.
+}

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

@@ -5,9 +5,6 @@ export interface BootRootOpts {
     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). */
@@ -20,12 +17,30 @@ export interface SpawnChildOpts {
     prompt: string;
     /** Override the parent (defaults to the calling node from env). */
     parent?: string;
+    /** Spawn an INDEPENDENT root instead of a managed child: parent=null, no
+     *  subscription back to the spawner, resident lifecycle, spawned_by=spawner.
+     *  Brought forefront on spawn so a human can drive it directly. */
+    root?: boolean;
+    /** Fork the new node from an existing pi conversation instead of starting it
+     *  fresh: a node id (resolved to that node's session file), an absolute
+     *  `.jsonl` path, or a partial pi session uuid. pi COPIES that history into a
+     *  new session for the child — the source is untouched — then `prompt` is the
+     *  next message. A one-shot at birth; the child resumes its own session after. */
+    forkFrom?: string;
 }
+/** Resolve a `--fork-from` value to the source pi gets as `--fork <path|id>`.
+ *  A live node id resolves to its captured session FILE (absolute, cwd-immune),
+ *  falling back to its bare session id; a path or partial uuid passes straight
+ *  through to pi. Throws when a known node has no session to fork yet. */
+export declare function resolveForkSource(value: string): 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. */
+/** Spawn a node from a live node. By default a managed terminal worker in a
+ *  background window, with the spawner auto-subscribed (active) via spawnNode.
+ *  With `root`: an independent resident root — parent=null, NO subscription back
+ *  to the spawner (it carries spawned_by=spawner for provenance only), brought
+ *  forefront so a human can pick up the conversation directly. */
 export declare function spawnChild(opts: SpawnChildOpts): SpawnChildResult;