@crouton-kit/crouter 0.3.27 → 0.3.29

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

@@ -17,6 +17,7 @@ export interface PromoteResult {
 export declare function promote(nodeId: string, opts?: {
     kind?: string;
     resident?: boolean;
+    model?: string;
 }): PromoteResult;
 export interface YieldResult {
     meta: NodeMeta;
@@ -32,4 +33,5 @@ export interface YieldResult {
  *  the daemon revives it fresh. */
 export declare function requestYield(nodeId: string, opts?: {
     kind?: string;
+    model?: string;
 }): YieldResult;

package/dist/core/runtime/promote.js

@@ -36,6 +36,9 @@ export function promote(nodeId, opts = {}) {
         throw new Error(`unknown node: ${nodeId}`);
     // The node may specialize as it promotes; default to its current kind.
     const targetKind = opts.kind ?? node.kind;
+    // ...and may raise/change its model tier; default to its current pin (so a
+    // promote with no --model preserves whatever it was running on).
+    const targetModel = opts.model ?? node.model_override ?? undefined;
     // Rewrite the launch spec to the target kind's orchestrator persona so the
     // *next* revive comes back orchestrating in that kind (polymorph stage 2).
     // nodeEnv reads meta.{kind,mode}, so CRTR_KIND/CRTR_MODE flip immediately for
@@ -46,9 +49,11 @@ export function promote(nodeId, opts = {}) {
     const { launch } = buildLaunchSpec(targetKind, 'orchestrator', {
         lifecycle: opts.resident === true ? 'resident' : node.lifecycle,
         hasManager: node.parent !== null,
-        // Preserve a caller-pinned model tier across the polymorph (the persona
-        // default is recomputed fresh for targetKind).
-        model: node.model_override ?? undefined,
+        // A model tier chosen on this call (opts.model) overrides the persona
+        // default and is persisted below; absent one, the existing pin carries
+        // across the polymorph (the persona default is recomputed fresh for
+        // targetKind).
+        model: targetModel,
     });
     // 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
@@ -67,6 +72,9 @@ export function promote(nodeId, opts = {}) {
         kind: targetKind,
         mode: 'orchestrator',
         launch,
+        // Persist a newly-chosen tier so it is durable across future revives; omit
+        // when unchanged so the existing pin (or persona default) stands.
+        ...(opts.model !== undefined ? { model_override: opts.model } : {}),
         ...(opts.resident === true ? { lifecycle: 'resident' } : {}),
     });
     return {
@@ -86,14 +94,24 @@ export function requestYield(nodeId, opts = {}) {
     const node = getNode(nodeId);
     if (node === null)
         throw new Error(`unknown node: ${nodeId}`);
+    // A yield may also RESHAPE the node as it refreshes — change kind and/or raise
+    // model tier. promote() is idempotent (on an already-orchestrator node it just
+    // rewrites the launch spec), so it doubles as the apply-path for that reshape.
+    const reshaping = opts.kind !== undefined || opts.model !== undefined;
+    const wasBase = node.mode !== 'orchestrator';
     let promoted = false;
-    if (node.mode !== 'orchestrator') {
+    if (wasBase || reshaping) {
         // 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;
+        promote(nodeId, {
+            ...(opts.kind !== undefined ? { kind: opts.kind } : {}),
+            ...(opts.model !== undefined ? { model: opts.model } : {}),
+        });
+        // "promoted" means a base node became an orchestrator — not a mere reshape
+        // of an already-orchestrator node.
+        promoted = wasBase;
     }
     // Mark the intent; the stophook enacts the shutdown, the daemon the revive.
     transition(nodeId, 'yield');

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

@@ -0,0 +1,8 @@
+/** Ask pi headlessly for a three-fragment recap of `conversation`, async. Invokes
+ *  `onRecap` with the parsed fragment lines on success, or never (silent) on any
+ *  failure — non-zero exit, timeout, empty/garbled output. Owns the subprocess
+ *  mechanics — crucially it hands pi an immediate stdin EOF: `pi -p` reads stdin,
+ *  and execFile's default stdin is an OPEN pipe that never closes, so without
+ *  this pi blocks waiting for EOF and the call exits non-zero (the same gotcha
+ *  naming.ts documents). */
+export declare function generateRecap(conversation: string, onRecap: (lines: string[]) => void): void;

package/dist/core/runtime/recap.js

@@ -0,0 +1,107 @@
+// Inactivity recap — turn a dormant node's conversation into a three-fragment
+// "where it left off" card (goal / doing-now / next) for the recap widget.
+//
+// One entry point: generateRecap — async (execFile, non-blocking), mirroring
+// naming.ts's headless-`pi -p` pattern exactly. It runs Haiku over the literal
+// back-and-forth (the caller concatenates user+assistant text) with a stripped-
+// down pi invocation (no tools/session/context/extensions/skills), so it's fast
+// and side-effect free and can never recurse into another spawn.
+//
+// Best-effort and silent on failure: a non-zero exit, timeout, empty or garbled
+// output resolves to NO recap (the caller shows nothing). The recap is throwaway
+// idle chrome — there is no local fallback, unlike naming, because a wrong or
+// stale recap is worse than none.
+//
+// Plain TS-with-types — no imports from @earendil-works/* so it compiles inside
+// crouter's own tsc build without a dep on the pi packages.
+import { execFile } from 'node:child_process';
+/** Wall-clock budget for the headless pi call before we give up (no recap). */
+const RECAP_TIMEOUT_MS = 25_000;
+/** Default recap model — Haiku. A recap is a one-shot summarization, so we pin
+ *  the small/fast model rather than the node's heavyweight default. Override
+ *  with CRTR_RECAP_MODEL (mirrors CRTR_NAME_MODEL). */
+const DEFAULT_RECAP_MODEL = 'anthropic/claude-haiku-4-5';
+const RECAP_SYSTEM_PROMPT = 'You write a terse "where we left off" recap of a coding-agent work session, ' +
+    'read at a glance by someone returning to a paused conversation. You are given ' +
+    'the literal back-and-forth between the user and the agent. Output EXACTLY three ' +
+    'lines, nothing else — no labels, no numbering, no bullets, no punctuation at the ' +
+    'end of a line, no prose:\n' +
+    '  Line 1: the GOAL — what this session is ultimately trying to achieve.\n' +
+    '  Line 2: DOING NOW — what was just happening / the active piece of work.\n' +
+    '  Line 3: NEXT — the immediate next step.\n' +
+    'Each line is a short FRAGMENT, not a sentence (e.g. `wire up recap widget above editor`, ' +
+    'not `We are wiring up the recap widget.`). Keep each under ~60 characters. ' +
+    'If the session has barely started or you cannot tell, still give your best three ' +
+    'fragments from whatever text exists. Output JUST the three lines.';
+/** Put the conversation FIRST in a delimited block, then the instruction, so the
+ *  model reads the content before being told what to do. */
+function recapUserPrompt(conversation) {
+    return `<conversation>\n${conversation}\n</conversation>\n\nWrite the three-line recap of the session above (goal / doing-now / next). Output JUST the three lines.`;
+}
+/** The pi argv for a headless recap request. Stripped down (no tools, session,
+ *  context files, extensions, skills, templates, themes) so it's fast and
+ *  side-effect free. Pinned to Haiku with thinking off. Override the model with
+ *  CRTR_RECAP_MODEL. */
+function recapArgs(conversation) {
+    const override = process.env['CRTR_RECAP_MODEL'];
+    const model = override !== undefined && override.trim() !== '' ? override.trim() : DEFAULT_RECAP_MODEL;
+    const argv = [
+        '-p',
+        '--no-session',
+        '--no-context-files',
+        '--no-extensions',
+        '--no-skills',
+        '--no-prompt-templates',
+        '--no-themes',
+        '--no-tools',
+        '--mode', 'text',
+        '--thinking', 'off',
+        '--model', model,
+        '--system-prompt', RECAP_SYSTEM_PROMPT,
+        recapUserPrompt(conversation),
+    ];
+    return argv;
+}
+/** Parse the model's raw stdout into up to three short fragment lines. Strips any
+ *  stray leading labels/bullets the model may have added despite instructions,
+ *  drops empties, and hard-caps line length so a runaway line can't blow up the
+ *  widget. Returns [] when nothing usable survives (→ no recap). */
+function parseRecap(stdout) {
+    const LINE_CAP = 72;
+    const lines = stdout
+        .split('\n')
+        .map((l) => l.trim())
+        // Strip a leading `goal:` / `now:` / `next:` / `- ` / `1.` style prefix.
+        .map((l) => l.replace(/^(?:[-*•]\s*)?(?:\d+[.)]\s*)?(?:goal|now|doing(?:[\s-]now)?|next)\s*[:\-]\s*/i, '').trim())
+        .filter((l) => l !== '');
+    return lines.slice(0, 3).map((l) => (l.length > LINE_CAP ? l.slice(0, LINE_CAP) : l));
+}
+/** Ask pi headlessly for a three-fragment recap of `conversation`, async. Invokes
+ *  `onRecap` with the parsed fragment lines on success, or never (silent) on any
+ *  failure — non-zero exit, timeout, empty/garbled output. Owns the subprocess
+ *  mechanics — crucially it hands pi an immediate stdin EOF: `pi -p` reads stdin,
+ *  and execFile's default stdin is an OPEN pipe that never closes, so without
+ *  this pi blocks waiting for EOF and the call exits non-zero (the same gotcha
+ *  naming.ts documents). */
+export function generateRecap(conversation, onRecap) {
+    const body = (conversation ?? '').trim();
+    if (body === '')
+        return;
+    try {
+        const child = execFile('pi', recapArgs(body), { encoding: 'utf8', timeout: RECAP_TIMEOUT_MS }, (err, stdout) => {
+            if (err || typeof stdout !== 'string')
+                return; // silent — no recap
+            const lines = parseRecap(stdout);
+            if (lines.length === 0)
+                return;
+            try {
+                onRecap(lines);
+            }
+            catch { /* best-effort */ }
+        });
+        child.stdin?.end(); // immediate EOF — see the doc above
+    }
+    catch {
+        // best-effort: no recap
+    }
+}

package/dist/core/runtime/recycle.js

@@ -5,8 +5,8 @@
 //
 //   1. Finalize — push the agent's last surfaced message as a `final` report so
 //      every subscriber/manager waiting on it is unblocked, and mark it done.
-//   2. Close    — kill the agent's pi (respawn-pane -k tears it down in place).
-//   3. Recycle  — boot a fresh resident root in that same pane (a new `crtr`).
+//   2. Close    — tear the agent's broker engine down (the pane is only a viewer).
+//   3. Recycle  — boot a fresh resident broker root the pane re-attaches to.
 //
 // NOT to be confused with `node demote` (flip-to-terminal IN PLACE, which keeps
 // the agent focused and running): recycle ENDS this agent and boots a brand-new
@@ -17,14 +17,13 @@
 // message) — falling back to a short note when it never reported.
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
-import { getNode, setPresence, updateNode, setFocusOccupant, fullName } from '../canvas/index.js';
+import { getNode, setPresence, setFocusOccupant, fullName } from '../canvas/index.js';
 import { reportsDir } from '../canvas/paths.js';
 import { pushFinal } from '../feed/feed.js';
-import { spawnNode, nodeSession, rootOfSpine } from './nodes.js';
+import { spawnNode, rootOfSpine } from './nodes.js';
 import { buildLaunchSpec, buildPiArgv } from './launch.js';
-import { FRONT_DOOR_ENV } from './front-door.js';
-import { focusOf, recycleFocusPane, piCommand, paneLocation, respawnPaneSync, setPaneOption, waitForBrokerViewSocket, viewerSplitEnv } from './placement.js';
-import { hostFor } from './host.js';
+import { focusOf, respawnPaneSync, setPaneOption, waitForBrokerViewSocket, viewerSplitEnv } from './placement.js';
+import { headlessBrokerHost } from './host.js';
 import { ensureDaemon } from '../../daemon/manage.js';
 /** The agent's most recent surfaced message: the newest reports/*.md body with
  *  its YAML frontmatter stripped. Empty string when the node never reported. */
@@ -74,19 +73,15 @@ export async function recycleNode(nodeId, callerPane) {
         finalized = true;
     }
     catch { /* recycle the pane even if the report failed */ }
-    // A broker node's pane is a VIEWER (`crtr attach`), not its engine: the engine
-    // is the detached broker process, so respawn-pane -k below would only kill the
-    // viewer, never the engine. Route teardown through the Host seam so the broker
-    // PROCESS exits and releases the sole .jsonl writer (mirrors the T12
-    // close.ts/reset.ts fix; review reuse MINOR-3). Status is already flipped done
-    // by pushFinal above (crash-safe order: the daemon won't revive a done node).
-    const isBroker = meta.host_kind === 'broker';
-    if (isBroker) {
-        try {
-            hostFor(meta).teardown(nodeId);
-        }
-        catch { /* best-effort */ }
+    // The node's pane is a VIEWER (`crtr attach`), not its engine: the engine is
+    // the detached broker process, so respawn-pane -k below would only kill the
+    // viewer, never the engine. Tear the broker PROCESS down so it exits and
+    // releases the sole .jsonl writer. Status is already flipped done by pushFinal
+    // above (crash-safe order: the daemon won't revive a done node).
+    try {
+        headlessBrokerHost.teardown(nodeId);
     }
+    catch { /* best-effort */ }
     // Capture M's focus viewport (if any) BEFORE nulling — the fresh root inherits
     // it (the SAME focus row + pane). The demoted node no longer holds a pane: it is
     // being reclaimed.
@@ -95,17 +90,13 @@ export async function recycleNode(nodeId, callerPane) {
         setPresence(nodeId, { pane: null, window: null, tmux_session: null });
     }
     catch { /* best-effort */ }
-    // 2 + 3. Recycle — boot a fresh resident root for the SAME pane, PRESERVING
-    // the recycled node's host model: a tmux node recycles into a tmux root in the
-    // pane; a broker node recycles into a fresh BROKER root the pane re-attaches to
-    // (broker-is-the-host — the viewer pane stays a viewer, never becomes an engine
-    // pane). Without preserving host_kind, recycling a broker node from its viewer
-    // would silently respawn the viewer into a tmux pi root.
+    // 2 + 3. Recycle — boot a fresh resident BROKER root for the SAME pane: the
+    // viewer pane re-attaches to the fresh broker (broker-is-the-host — the viewer
+    // pane stays a viewer, never becomes an engine pane).
     try {
         ensureDaemon();
     }
     catch { /* daemon is best-effort */ }
-    const loc = paneLocation(pane);
     const { launch } = buildLaunchSpec('general', 'base', { lifecycle: 'resident', hasManager: false });
     const root = spawnNode({
         kind: 'general',
@@ -115,12 +106,7 @@ export async function recycleNode(nodeId, callerPane) {
         name: 'general',
         parent: null,
         launch,
-        hostKind: isBroker ? 'broker' : 'tmux',
     });
-    // REVIVE-HOME: a recycled root's durable revive target is the session
-    // of the pane it was recycled into (the one place home_session is rewritten
-    // after birth). Falls back to the backstage when the pane can't be located.
-    updateNode(root.node_id, { home_session: loc?.session ?? nodeSession() });
     // Hand the viewport to the fresh root: reuse M's focus row over the SAME pane
     // (respawn-pane -k below keeps the %id), so the user keeps watching this slot.
     if (f !== null) {
@@ -131,33 +117,12 @@ export async function recycleNode(nodeId, callerPane) {
     }
     const fresh = getNode(root.node_id);
     const inv = buildPiArgv(fresh);
-    // CRTR_ROOT_SESSION/CRTR_SUBTREE route the fresh root's children to the
-    // backstage (both consumers below read this one authoritative env). FRONT_DOOR
-    // is added per-consumer: the tmux command const adds it; the broker host sets
-    // it itself, so the broker branch omits it.
-    inv.env = { ...inv.env, CRTR_ROOT_SESSION: nodeSession(), CRTR_SUBTREE: rootOfSpine(root.node_id) };
-    const ok = isBroker
-        ? recycleBrokerViewer(fresh, pane, inv)
-        : recycleTmuxRoot(root.node_id, pane, {
-            command: piCommand(inv.argv),
-            env: { ...inv.env, [FRONT_DOOR_ENV]: '1' },
-            cwd: meta.cwd,
-            name: fullName(fresh),
-        });
+    // CRTR_SUBTREE groups the fresh root's subtree; FRONT_DOOR is set by the broker
+    // host itself, so it is not added here.
+    inv.env = { ...inv.env, CRTR_SUBTREE: rootOfSpine(root.node_id) };
+    const ok = recycleBrokerViewer(fresh, pane, inv);
     return { recycled: ok, finalized, newRoot: root.node_id, delivered };
 }
-/** Recycle a TMUX root into `pane`: respawn-pane -k boots the fresh pi engine in
- *  place. Clears any stale `@crtr_node` viewer tag first — a prior `crtr attach`
- *  in this pane may have left one (tmux pane options survive respawn-pane), and
- *  since nodeInPane checks the tag BEFORE the window, a stale tag would shadow
- *  the real window→node lookup for the fresh tmux engine now in the pane. */
-function recycleTmuxRoot(nodeId, pane, launch) {
-    try {
-        setPaneOption(pane, '@crtr_node', '');
-    }
-    catch { /* best-effort */ }
-    return recycleFocusPane(nodeId, pane, { ...launch, resuming: false });
-}
 /** Recycle a BROKER root into `pane`: the fresh root is broker-hosted, so its
  *  engine runs in a DETACHED broker, not the pane. Birth-launch that broker via
  *  the Host seam (mirrors spawnChild's birth path — the host records its pid),
@@ -167,13 +132,12 @@ function recycleTmuxRoot(nodeId, pane, launch) {
  *  pane was not respawned) when the broker never serves — the fresh root row
  *  still exists, broker-hosted, for the daemon to revive. */
 function recycleBrokerViewer(fresh, pane, inv) {
-    hostFor(fresh).launch(fresh.node_id, inv, { cwd: fresh.cwd, name: fullName(fresh), resuming: false });
+    headlessBrokerHost.launch(fresh.node_id, inv, { cwd: fresh.cwd, name: fullName(fresh), resuming: false });
     if (!waitForBrokerViewSocket(fresh.node_id))
         return false;
-    // Clear the finalized node's stale `@crtr_node` tag before respawn (symmetry
-    // with recycleTmuxRoot) so the tag never names a done node during the gap
-    // before the new `crtr attach` re-tags on connect. Node ids are shell-safe
-    // identifiers; no quoting needed.
+    // Clear the finalized node's stale `@crtr_node` tag before respawn so the tag
+    // never names a done node during the gap before the new `crtr attach` re-tags
+    // on connect. Node ids are shell-safe identifiers; no quoting needed.
     try {
         setPaneOption(pane, '@crtr_node', '');
     }

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

@@ -1,56 +1,62 @@
+import { headlessBrokerHost } from './host.js';
+import { respawnPaneSync } from './placement.js';
 /** Reap the descendant sub-DAG of `rootId`: mark each **canceled** (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 `canceled` (A5, human-confirmed 2026-06-06): an externally-reaped node —
- *  whether via `node close` OR a root reset/relaunch — did not finish its OWN
- *  work, so it unifies on `canceled`; `done` is reserved for finalize. 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 `canceled` here via the
- *  same `cancel` event the close cascade uses. Shared by relaunchRoot (option C)
- *  and resetRoot's in-place fallback, so both leave their descendants `canceled`. */
+ *  whether via `node close` OR a root reset — did not finish its OWN work, so it
+ *  unifies on `canceled`; `done` is reserved for finalize. Why marking is STILL
+ *  explicit: an abrupt broker teardown fires NO clean `session_shutdown`, so the
+ *  general quit→done rule does NOT auto-resolve a force-killed descendant — we
+ *  mark it `canceled` here via the same `cancel` event the close cascade uses. */
 export declare function reapDescendants(rootId: string): string[];
+/** Injectable host/viewer seam, so the fast-tier test drives relaunchRoot's pure
+ *  DB transitions without a real broker or tmux. Each field defaults to its
+ *  production verb. */
+export interface RelaunchDeps {
+    /** Boot the new node's detached broker engine. Default: headlessBrokerHost.launch. */
+    launchBroker?: typeof headlessBrokerHost.launch;
+    /** Wait for the new broker's view.sock to accept. Default: waitForBrokerViewSocket. */
+    waitForViewSocket?: (nodeId: string) => boolean;
+    /** Re-exec the viewer pane onto the new node. Default: respawnPaneSync. */
+    respawnViewer?: typeof respawnPaneSync;
+    /** Tear the old broker down. Default: headlessBrokerHost.teardown. */
+    teardownBroker?: typeof headlessBrokerHost.teardown;
+}
+export interface RelaunchRootResult {
+    /** The freshly-minted node now driving this pane. */
+    newNodeId: string;
+}
+/** Relaunch a ROOT on `/new`: park the old root `done` (kept as history) and
+ *  mint a fresh node id + broker in the same pane/cwd, re-pointing the viewer at
+ *  it. The new broker is booted FIRST and its pid confirmed BEFORE the old root
+ *  is touched, so any pre-commit failure leaves the old root fully intact and
+ *  live. Returns null when `oldId` is not a relaunchable root (unknown, a child,
+ *  or already parked), or when the new broker failed to launch. */
+export declare function relaunchRoot(oldId: string, deps?: RelaunchDeps): RelaunchRootResult | null;
 export interface ResetRootResult {
-    /** Descendant node ids torn down (window killed + marked canceled). */
+    /** Descendant node ids torn down. Always empty — a child `/new` reaps nothing. */
     reaped: string[];
-    /** Direct subscriptions dropped off the root. */
+    /** Direct subscriptions dropped. Always empty — a child `/new` detaches nothing. */
     detached: string[];
-    /** True when the node was a root and a full reset ran. */
+    /** Always false — a child `/new` is not a graph reset (roots route to relaunchRoot). */
     reset: boolean;
 }
-/** 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 `--session <id>` wakes the right conversation. */
+/** Refresh a non-root child's pi session id on `/new`, so a later
+ *  `--session <id>` wakes the right conversation. A `/new` on a child is NOT a
+ *  graph reset — a root's `/new` is handled by relaunchRoot, never here; a root
+ *  that reaches this is a no-op. */
 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 type HandleNewSessionPath = '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;
+/** The child-side `/new` entry the stophook calls (the root side goes to
+ *  relaunchRoot directly). The broker already drove the engine-side new_session;
+ *  this only refreshes the child's session id on the SAME node id. */
+export declare function handleNewSession(nodeId: string, newSessionId: string, newSessionFile?: string | null): HandleNewSessionResult;
 /** 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