@crouton-kit/crouter 0.3.14 → 0.3.16

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

@@ -1,21 +1,28 @@
 import { type NodeMeta } from '../canvas/index.js';
 export interface PromoteResult {
     meta: NodeMeta;
-    /** Orchestration guidance to surface into the node's current context now. */
-    guidance: string;
     roadmapWritten: boolean;
     /** Absolute path to the node's roadmap doc (context/roadmap.md). */
     roadmapPath: string;
     /** Absolute path to the node's goal doc (context/initial-prompt.md). */
     goalPath: string;
+    /** Absolute path to the node-local memory index (context/memory/MEMORY.md). */
+    memoryPath: string;
+    /** Absolute path to the user-global memory index (<crtrHome>/memory/MEMORY.md). */
+    userMemoryPath: string;
+    /** Absolute path to the project memory index (<crtrHome>/projects/<key>/memory/MEMORY.md). */
+    projectMemoryPath: string;
 }
-/** Promote a node to resident orchestrator, optionally specializing its kind
- *  (e.g. a `general` worker becoming a `developer.orchestrator`). Idempotent:
- *  re-promoting just rewrites the spec + returns fresh guidance. Seeds a
- *  roadmap SCAFFOLD if absent (a boss with no map is a failure mode) — no goal
- *  is forced here; authoring the goal + roadmap is the node's next act. */
+/** Promote a node to an orchestrator (mode→orchestrator), optionally
+ *  specializing its kind (e.g. a `general` worker becoming a
+ *  `developer.orchestrator`) and optionally also making it resident. Idempotent:
+ *  re-promoting just rewrites the spec. Seeds a roadmap SCAFFOLD if absent (a
+ *  boss with no map is a failure mode) — no goal is forced here; authoring the
+ *  goal + roadmap is the node's next act. The transition guidance is injected
+ *  centrally by the persona injector at the next turn boundary, not returned. */
 export declare function promote(nodeId: string, opts?: {
     kind?: string;
+    resident?: boolean;
 }): PromoteResult;
 export interface YieldResult {
     meta: NodeMeta;

package/dist/core/runtime/promote.js

@@ -1,71 +1,36 @@
-// Promotion — terminal → resident, and the worker→orchestrator polymorph.
+// Promotion — the worker→orchestrator polymorph (mode→orchestrator).
 //
 // Two stages (the pi-mode-switch pattern):
-//   1. Promotion → guidance dump (mid-turn, ephemeral). This call flips the
-//      node's mode/lifecycle and (optionally) its KIND, REWRITES its launch
-//      spec to that kind's orchestrator persona (so the next revive comes back
-//      as that orchestrator), seeds a roadmap scaffold, and RETURNS kind-
-//      specific orchestration + roadmap-shaping guidance — which enters the
-//      current context so the node can author its roadmap before any refresh.
+//   1. Promotion → mode flips to orchestrator (mid-turn). This call flips the
+//      node's mode and (optionally) its KIND, REWRITES its launch spec to that
+//      kind's orchestrator persona (so the next revive comes back as that
+//      orchestrator), and seeds a roadmap scaffold + the three memory stores.
+//      The transition guidance the node needs is injected CENTRALLY by the
+//      persona injector (runtime/persona.ts) at the turn boundary — promote()
+//      itself no longer returns or hand-emits guidance.
 //   2. Refresh → persona swap (permanent). On the next fresh revive the node
 //      starts with the orchestrator system prompt baked in (because the launch
-//      spec now says orchestrator). The guidance dump bridges until then.
+//      spec now says orchestrator). The injected guidance bridges until then.
+//
+// Mode and lifecycle are ORTHOGONAL: promotion flips mode only. Lifecycle stays
+// whatever it was (a promoted child is terminal/orchestrator — still reports up
+// + reaps) unless the caller passes `resident:true` to also make it resident.
 //
 // Trigger is persistence-need (deliberate, or a refresh-yield with open work),
 // never the mere act of spawning a child.
-import { getNode, updateNode, hasActiveLiveSubscription } from '../canvas/index.js';
+import { getNode, updateNode } from '../canvas/index.js';
+import { transition } from './lifecycle.js';
 import { buildLaunchSpec } from './launch.js';
-import { loadKernel, loadPersona } from '../personas/index.js';
-import { resolveSkill } from '../resolver.js';
-import { readText } from '../fs-utils.js';
-import { parseFrontmatter } from '../frontmatter.js';
-import { hasRoadmap, seedRoadmap, readRoadmap, roadmapPath } from './roadmap.js';
+import { hasRoadmap, seedRoadmap, roadmapPath } from './roadmap.js';
+import { seedMemory, memoryPath, seedUserMemory, userMemoryPath, seedProjectMemory, projectMemoryPath, } from './memory.js';
 import { readGoal, goalPath } from './kickoff.js';
-/** Load a skill's body text by name, or null if it can't be resolved. Used to
- *  inline a kind's roadmap-shaping skill into the promotion guidance dump. */
-function loadSkillBody(name) {
-    try {
-        const skill = resolveSkill(name, {});
-        return parseFrontmatter(readText(skill.path)).body.trim();
-    }
-    catch {
-        return null;
-    }
-}
-/** Build the mid-turn guidance dump, specialized to the node's (possibly
- *  just-chosen) kind: the shared kernel + that kind's roadmap-shaping skill
- *  (auto-loaded now, before the persona swap bakes in on revive) + the roadmap
- *  scaffold the node must author. No goal is assumed — writing it is step one. */
-function orchestrationGuidance(nodeId, kind) {
-    const kernel = loadKernel();
-    const orch = loadPersona(kind, 'orchestrator');
-    const roadmapSkill = typeof orch?.frontmatter?.['roadmapSkill'] === 'string'
-        ? orch.frontmatter['roadmapSkill']
-        : undefined;
-    const skillBody = roadmapSkill ? loadSkillBody(roadmapSkill) : null;
-    const roadmap = readRoadmap(nodeId) ?? '(no roadmap yet)';
-    const rmPath = roadmapPath(nodeId);
-    const goal = readGoal(nodeId);
-    const parts = [
-        `You are now a RESIDENT ${kind.toUpperCase()} ORCHESTRATOR. Your scarce resource is your own context window.`,
-        'Your job is to manage context and delegate — not to do the goal yourself.',
-        '',
-        kernel,
-    ];
-    if (goal !== null && goal.trim() !== '') {
-        parts.push('', `--- Your goal (${goalPath(nodeId)}) ---`, '', goal.trim());
-    }
-    if (skillBody) {
-        parts.push('', `--- How to shape a ${kind} roadmap (skill: ${roadmapSkill}) ---`, '', skillBody);
-    }
-    parts.push('', `Your roadmap scaffold (\`${rmPath}\`) — author it now: state the goal, exit criteria, and the phase skeleton, using the approach above. Current contents:`, '', roadmap, '', 'Then delegate each phase with `crtr node new --kind <kind>`. When your context fills, run `crtr node yield` to refresh against this roadmap.');
-    return parts.join('\n');
-}
-/** Promote a node to resident orchestrator, optionally specializing its kind
- *  (e.g. a `general` worker becoming a `developer.orchestrator`). Idempotent:
- *  re-promoting just rewrites the spec + returns fresh guidance. Seeds a
- *  roadmap SCAFFOLD if absent (a boss with no map is a failure mode) — no goal
- *  is forced here; authoring the goal + roadmap is the node's next act. */
+/** Promote a node to an orchestrator (mode→orchestrator), optionally
+ *  specializing its kind (e.g. a `general` worker becoming a
+ *  `developer.orchestrator`) and optionally also making it resident. Idempotent:
+ *  re-promoting just rewrites the spec. Seeds a roadmap SCAFFOLD if absent (a
+ *  boss with no map is a failure mode) — no goal is forced here; authoring the
+ *  goal + roadmap is the node's next act. The transition guidance is injected
+ *  centrally by the persona injector at the next turn boundary, not returned. */
 export function promote(nodeId, opts = {}) {
     const node = getNode(nodeId);
     if (node === null)
@@ -76,7 +41,13 @@ export function promote(nodeId, opts = {}) {
     // *next* revive comes back orchestrating in that kind (polymorph stage 2).
     // nodeEnv reads meta.{kind,mode}, so CRTR_KIND/CRTR_MODE flip immediately for
     // the live process's children too.
-    const { launch } = buildLaunchSpec(targetKind, 'orchestrator');
+    // Bake the node's post-promote lifecycle + spine into the rebuilt prompt:
+    // lifecycle becomes resident only when the caller asked (else it keeps its
+    // current value); spine is fixed by parent-ness (immutable).
+    const { launch } = buildLaunchSpec(targetKind, 'orchestrator', {
+        lifecycle: opts.resident === true ? 'resident' : node.lifecycle,
+        hasManager: node.parent !== null,
+    });
     // Seed a barebones roadmap scaffold if absent so the file exists for a
     // refresh. Pre-fill its Goal from the node's goal doc when present (set at
     // spawn, or captured from the first user message); the node fleshes out the
@@ -87,13 +58,30 @@ export function promote(nodeId, opts = {}) {
         seedRoadmap(nodeId, goal !== null && goal.trim() !== '' ? { goal: goal.trim() } : {});
         roadmapWritten = true;
     }
-    const meta = updateNode(nodeId, { kind: targetKind, lifecycle: 'resident', mode: 'orchestrator', launch });
+    // Seed all three scoped memory stores alongside the roadmap — user-global,
+    // project (keyed off this node's cwd), and node-local. Each is a durable,
+    // refresh-surviving artifact; each guarded so a re-seed never clobbers an
+    // evolved memory.
+    seedUserMemory();
+    seedProjectMemory(node.cwd);
+    seedMemory(nodeId);
+    // Flip mode→orchestrator + kind + launch spec. Lifecycle is independent:
+    // only set resident when the caller asked for it (the common self-promotion
+    // stays terminal/orchestrator — it still reports up + reaps).
+    const meta = updateNode(nodeId, {
+        kind: targetKind,
+        mode: 'orchestrator',
+        launch,
+        ...(opts.resident === true ? { lifecycle: 'resident' } : {}),
+    });
     return {
         meta,
-        guidance: orchestrationGuidance(nodeId, targetKind),
         roadmapWritten,
         roadmapPath: roadmapPath(nodeId),
         goalPath: goalPath(nodeId),
+        memoryPath: memoryPath(nodeId),
+        userMemoryPath: userMemoryPath(),
+        projectMemoryPath: projectMemoryPath(node.cwd),
     };
 }
 /** Request a refresh-yield: discard in-memory context and revive fresh against
@@ -107,14 +95,16 @@ export function requestYield(nodeId, opts = {}) {
     if (node === null)
         throw new Error(`unknown node: ${nodeId}`);
     let promoted = false;
-    if (node.lifecycle === 'terminal') {
-        // Yielding with open work ⇒ must survive a context reset ⇒ promote
-        // (optionally specializing the kind).
+    if (node.mode !== 'orchestrator') {
+        // A yield needs a ROADMAP to refresh against — i.e. orchestrator mode, not
+        // resident lifecycle. Ensure orchestrator (which seeds the roadmap + memory)
+        // WITHOUT forcing resident: a terminal/orchestrator yields fine, since the
+        // daemon's refresh-revive keys on intent='refresh', not lifecycle.
         promote(nodeId, opts.kind !== undefined ? { kind: opts.kind } : {});
         promoted = true;
     }
     // Mark the intent; the stophook enacts the shutdown, the daemon the revive.
-    const meta = updateNode(nodeId, { intent: 'refresh' });
-    void hasActiveLiveSubscription; // (open-work signal, reserved for future gating)
+    transition(nodeId, 'yield');
+    const meta = getNode(nodeId);
     return { meta, promoted, willRefresh: true };
 }

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

@@ -1,13 +1,56 @@
+/** 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 declare function reapDescendants(rootId: string): string[];
 export interface ResetRootResult {
-    /** Descendant node ids torn down (window killed + marked dead). */
+    /** Descendant node ids torn down (window killed + marked done). */
     reaped: string[];
     /** Direct subscriptions dropped off the root. */
     detached: string[];
     /** True when the node was a root and a full reset ran. */
     reset: boolean;
 }
-/** Reset a root node to a pristine, empty graph (the `/new` semantics).
+/** 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 declare function resetRoot(nodeId: string, newSessionId?: string): ResetRootResult;
+ *  refresh its session id so a later `--session <id>` wakes the right conversation. */
+export declare function resetRoot(nodeId: string, newSessionId?: string, newSessionFile?: string | null): ResetRootResult;
+/** Injectable respawn seam — tests pass a double since tmux isn't available. */
+export interface RelaunchDeps {
+    relaunchRootInPane?: (nodeId: string, pane: string) => void;
+}
+export type HandleNewSessionPath = 'relaunch' | 'reset-root' | 'reset-child' | 'noop';
+export interface HandleNewSessionResult {
+    path: HandleNewSessionPath;
+    newNodeId?: string;
+}
+/** 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 declare function handleNewSession(nodeId: string, newSessionId: string, pane: string | undefined, deps?: RelaunchDeps, newSessionFile?: string | null): HandleNewSessionResult;
+/** 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 declare function relaunchRoot(oldId: string, pane: string, deps?: RelaunchDeps): {
+    newNodeId: string;
+} | null;
+/** 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 declare function markCleanExitDone(nodeId: string, reason: unknown): boolean;

package/dist/core/runtime/reset.js

@@ -1,67 +1,89 @@
-// 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, setFocusOccupant, subscriptionsOf, unsubscribe, view, reportsDir, inboxPath, nodeDir, openDb, } from '../canvas/index.js';
+import { transition } from './lifecycle.js';
+import { paneLocation, tearDownNode, focusOf } 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, nodeSession } from './nodes.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 +100,169 @@ 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 {
+        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. The focus repoint (step 4) is INSIDE the txn, so a ROLLBACK undoes
+    // it automatically — there is no file to restore.
+    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: repoint the old root's focus row to the new root
+        //    (same pane — respawn-pane -k below keeps the %id). Inside the txn → the
+        //    ROLLBACK path restores the old occupant automatically (no file to restore).
+        const oldFocus = focusOf(oldId);
+        if (oldFocus !== null)
+            setFocusOccupant(oldFocus.focus_id, 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 { /* */ }
+        // The focus repoint was inside the txn; ROLLBACK already restored the old
+        // occupant — nothing to undo here.
+        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 './placement.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;