@crouton-kit/crouter 0.3.14 → 0.3.15

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

@@ -1,8 +1,12 @@
 import type { NodeMeta } from '../canvas/index.js';
-/** Persist `nodeId` as the currently focused node. Best-effort; never throws. */
+/** Persist `nodeId` as the currently focused node. Best-effort; never throws.
+ *  Also maintains the transitional focus.ptr↔focuses-table dual-write bridge
+ *  (see below) so Step 6 can flip reads to the table with no data gap. */
 export declare function setFocus(nodeId: string): void;
-/** Read the currently focused node id, or null if the pointer is absent or
- *  empty (no active focus). Best-effort; never throws. */
+/** Read the currently focused node id, or null if there is no active focus.
+ *  Reads `focus.ptr` first; FALLS BACK to the canonical focuses row (the bridge,
+ *  below) when the pointer is absent/empty — so a reader sees the same focus
+ *  whichever store a writer reached. Best-effort; never throws. */
 export declare function getFocus(): string | null;
 /** True when the node's tmux window is alive.  A falsy tmux_session/window
  *  always returns false so callers don't need to null-guard. */
@@ -24,15 +28,3 @@ export declare function focusNode(nodeId: string): {
     focused: boolean;
     session: string | null;
 };
-/** Focus a node IN PLACE: bring its pane into the caller's current pane slot
- *  (swap-pane) instead of navigating the client to the node's own window. This
- *  is the default for `crtr node focus` and the nav-chrome spine jump — the
- *  agent appears where you are.
- *
- *  Falls back to window focus when there is no caller pane (not inside tmux) or
- *  the target pane can't be resolved. `inPlace` reports which path ran. */
-export declare function focusNodeInPlace(nodeId: string, callerPane?: string, callerNodeId?: string): {
-    focused: boolean;
-    session: string | null;
-    inPlace: boolean;
-};

package/dist/core/runtime/presence.js

@@ -18,8 +18,8 @@
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { join } from 'node:path';
-import { crtrHome, getNode, updateNode } from '../canvas/index.js';
-import { selectWindow, switchClient, windowAlive, currentTmux, paneOfWindow, swapPaneInPlace, windowOfPane } from './tmux.js';
+import { crtrHome, getNode, getRow, openFocusRow, closeFocusRow, getFocusById, getFocusByNode, } from '../canvas/index.js';
+import { selectWindow, switchClient, windowAlive, currentTmux, inTmux } from './tmux.js';
 // ---------------------------------------------------------------------------
 // Focus pointer
 // ---------------------------------------------------------------------------
@@ -27,7 +27,9 @@ import { selectWindow, switchClient, windowAlive, currentTmux, paneOfWindow, swa
 function focusPtrPath() {
     return join(crtrHome(), 'focus.ptr');
 }
-/** Persist `nodeId` as the currently focused node. Best-effort; never throws. */
+/** Persist `nodeId` as the currently focused node. Best-effort; never throws.
+ *  Also maintains the transitional focus.ptr↔focuses-table dual-write bridge
+ *  (see below) so Step 6 can flip reads to the table with no data gap. */
 export function setFocus(nodeId) {
     try {
         const p = focusPtrPath();
@@ -37,19 +39,101 @@ export function setFocus(nodeId) {
     catch {
         /* focus pointer is best-effort; never surface */
     }
+    syncBridgeFocusRow(nodeId); // Step-4 dual-write bridge (REMOVED in Step 8)
 }
-/** Read the currently focused node id, or null if the pointer is absent or
- *  empty (no active focus). Best-effort; never throws. */
+/** Read the currently focused node id, or null if there is no active focus.
+ *  Reads `focus.ptr` first; FALLS BACK to the canonical focuses row (the bridge,
+ *  below) when the pointer is absent/empty — so a reader sees the same focus
+ *  whichever store a writer reached. Best-effort; never throws. */
 export function getFocus() {
     try {
         const raw = readFileSync(focusPtrPath(), 'utf8').trim();
-        return raw !== '' ? raw : null;
+        if (raw !== '')
+            return raw;
+    }
+    catch {
+        /* pointer absent — fall through to the table */
+    }
+    // Bridge fallback: the canonical focus row's occupant (Step-8 removal).
+    try {
+        return getFocusById(BRIDGE_FOCUS_ID)?.node_id ?? null;
     }
     catch {
         return null;
     }
 }
 // ---------------------------------------------------------------------------
+// Transitional focus.ptr ↔ focuses-table dual-write bridge.
+//
+// THROWAWAY — DELETED IN STEP 8. Today `focus.ptr` owns the single "current"
+// focus. Step 4 stands up the plural `focuses` table but nothing reads it as
+// authority yet (that switch is Step 6). To populate it in lockstep WITHOUT a
+// behavior change, every `setFocus` ALSO writes one canonical focus row that
+// mirrors `focus.ptr`, and `getFocus` falls back to it. Step 6 replaces
+// focusNodeInPlace with retargetFocus/openFocus, which write pane-correct focus
+// rows directly — then this bridge (and focus.ptr) is removed.
+// ---------------------------------------------------------------------------
+/** The fixed focus_id of the one canonical row that mirrors `focus.ptr`. */
+const BRIDGE_FOCUS_ID = '__focus_ptr__';
+/** Best-effort pane/session for the canonical focus row. A bare `setFocus(id)`
+ *  only carries a node id, but a focus row wants pane+session. Resolve them
+ *  READ-ONLY from the node's already-stored LOCATION (`row.pane`/`tmux_session`),
+ *  else from the caller's current tmux pane (`currentTmux`).
+ *
+ *  DELIBERATE DEVIATION from the design's "run reconcile(nodeId) first": reconcile
+ *  WRITES node presence via setPresence, and `setFocus` has many non-focus callers
+ *  (reset/close/demote/tmux-spread). Reconciling on every setFocus would mutate
+ *  their nodes' LOCATION as an invisible side-effect of a dual-write that is
+ *  supposed to change NOTHING this step. So the bridge reads, never reconciles;
+ *  best-effort is fine THIS step (nothing reads the row as authority until Step 6,
+ *  which replaces these writers with pane-correct retargetFocus/openFocus). */
+function resolveBridgePaneSession(nodeId) {
+    try {
+        const row = getRow(nodeId);
+        if (row?.pane != null && row.pane !== '') {
+            return { pane: row.pane, session: row.tmux_session ?? null };
+        }
+        if (inTmux()) {
+            const cur = currentTmux();
+            if (cur)
+                return { pane: cur.pane, session: cur.session };
+        }
+    }
+    catch {
+        /* best-effort */
+    }
+    return { pane: null, session: null };
+}
+/** Mirror the current focus into the single canonical focuses row. `''` closes
+ *  it (focus cleared). Otherwise re-point the row at `nodeId`: drop the prior
+ *  canonical row and any row already holding `nodeId` (UNIQUE(node_id) safety)
+ *  before re-inserting. All best-effort — a failure here must never break a
+ *  setFocus caller or the build. */
+function syncBridgeFocusRow(nodeId) {
+    try {
+        if (nodeId === '') {
+            closeFocusRow(BRIDGE_FOCUS_ID);
+            return;
+        }
+        // Step 6: retargetFocus/openFocus now write REAL (pane-correct) focus rows.
+        // If one already shows this node, the table is already authoritative —
+        // focus.ptr (the file, written above) names the node and getFocus's fallback
+        // reads the real row. Drop any stale bridge row and PIGGYBACK on the real
+        // one; never duplicate-insert (UNIQUE node_id) or clobber it.
+        const real = getFocusByNode(nodeId);
+        if (real !== null && real.focus_id !== BRIDGE_FOCUS_ID) {
+            closeFocusRow(BRIDGE_FOCUS_ID);
+            return;
+        }
+        const { pane, session } = resolveBridgePaneSession(nodeId);
+        closeFocusRow(BRIDGE_FOCUS_ID);
+        openFocusRow(BRIDGE_FOCUS_ID, pane, session, nodeId);
+    }
+    catch {
+        /* dual-write is best-effort; never surface */
+    }
+}
+// ---------------------------------------------------------------------------
 // Liveness
 // ---------------------------------------------------------------------------
 /** True when the node's tmux window is alive.  A falsy tmux_session/window
@@ -92,63 +176,3 @@ export function focusNode(nodeId) {
     const windowOk = selectWindow(session, window);
     return { focused: clientOk && windowOk, session };
 }
-/** Focus a node IN PLACE: bring its pane into the caller's current pane slot
- *  (swap-pane) instead of navigating the client to the node's own window. This
- *  is the default for `crtr node focus` and the nav-chrome spine jump — the
- *  agent appears where you are.
- *
- *  Falls back to window focus when there is no caller pane (not inside tmux) or
- *  the target pane can't be resolved. `inPlace` reports which path ran. */
-export function focusNodeInPlace(nodeId, callerPane, callerNodeId) {
-    const meta = getNode(nodeId);
-    // Always write the pointer so the dashboard reflects intent even on failure.
-    setFocus(nodeId);
-    if (meta === null || !nodeLive(meta)) {
-        return { focused: false, session: meta?.tmux_session ?? null, inPlace: false };
-    }
-    const session = meta.tmux_session;
-    const window = meta.window;
-    const pane = callerPane ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane;
-    // No caller pane (not in tmux) — best we can do is bring the window forefront.
-    if (pane === undefined || pane === '') {
-        const ok = switchClient(session) && selectWindow(session, window);
-        return { focused: ok, session, inPlace: false };
-    }
-    const targetPane = paneOfWindow(session, window);
-    if (targetPane === null) {
-        const ok = switchClient(session) && selectWindow(session, window);
-        return { focused: ok, session, inPlace: false };
-    }
-    if (targetPane === pane)
-        return { focused: true, session, inPlace: true }; // already here
-    // The window the caller's pane currently sits in — the slot the target's pane
-    // is about to be swapped INTO.
-    const callerWindow = windowOfPane(pane);
-    const ok = swapPaneInPlace(targetPane, pane);
-    // Keep the canvas window mapping in sync with the physical swap. swap-pane
-    // exchanges the two PANES between their windows (pane ids are stable, windows
-    // are slots): after the swap the target's pane occupies the caller's window
-    // and the caller's pane occupies the target's old window. Without this update
-    // meta.window goes stale, and a later paneOfWindow(session, meta.window)
-    // resolves the WRONG pane — the bug that made focusing back to a manager a
-    // no-op (it kept resolving the pane already in view) and made a focused node's
-    // exit collapse the visible window instead of its background one.
-    if (ok && callerWindow !== null && callerWindow !== window) {
-        try {
-            updateNode(nodeId, { window: callerWindow });
-        }
-        catch { /* best-effort */ }
-        // The caller is the node running this focus (its pi process owns callerPane).
-        // Its pane moved to the target's old window, so re-point its window there.
-        // Prefer an explicit id (the `node cycle` tmux binding runs outside any pi,
-        // so CRTR_NODE_ID is unset there) and fall back to the env for `node focus`.
-        const cnid = callerNodeId ?? process.env['CRTR_NODE_ID'];
-        if (cnid !== undefined && cnid.trim() !== '' && cnid !== nodeId) {
-            try {
-                updateNode(cnid, { window });
-            }
-            catch { /* best-effort */ }
-        }
-    }
-    return { focused: ok, session, inPlace: true };
-}

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;