@north-light/crouter 0.3.154

package/dist/core/runtime/recap.js

@@ -0,0 +1,136 @@
+// Inactivity recap — turn a dormant node's conversation into one concise
+// returning-developer briefing for the recap widget.
+//
+// One entry point: generateRecap — async (execFile, non-blocking), mirroring
+// naming.ts's headless-`pi -p` pattern exactly. It runs the live conversation's
+// working model over the literal back-and-forth (the caller concatenates user and
+// assistant text, plus the node's roadmap when one exists) 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';
+import { bundledPiSubprocessEnv, resolveBundledPiCliPath } from './pi-cli.js';
+/** Wall-clock budget for the headless pi call before we give up (no recap). */
+const RECAP_TIMEOUT_MS = 25_000;
+/** Fallback model when the live session has not resolved one yet. Ordinarily the
+ *  caller passes the provider/model that just completed the conversation's last
+ *  turn, avoiding a dead hard-pinned provider. CRTR_RECAP_MODEL overrides both. */
+const DEFAULT_RECAP_MODEL = 'anthropic/claude-haiku-4-5';
+const RECAP_SYSTEM_PROMPT = 'You brief a developer returning to a paused coding-agent conversation. They run ' +
+    'many agent sessions in parallel and have lost this one\'s thread: they no longer ' +
+    'know what this conversation is about or what they originally asked for. The ' +
+    'brief exists to solve exactly that — pinned above their input box, it must tell ' +
+    'them at a glance what this conversation is FOR and where it actually stands. ' +
+    'You are given the first and most recent messages of the literal user/agent ' +
+    'back-and-forth (tool output omitted), and the agent\'s roadmap file when one ' +
+    'exists.\n' +
+    '\n' +
+    'Output EXACTLY two plain-text lines, nothing else:\n' +
+    'Goal: <what was requested — the original ask / what this conversation is for>\n' +
+    'State: <catch-them-up: what is ACTUALLY going on right now>\n' +
+    '\n' +
+    'Both lines are extremely short — telegraphic fragments, roughly 8-15 words, no ' +
+    'filler. The State line must NOT restate the most recent message — the last ' +
+    'message is often mid-progress, a question, or noise; instead synthesize the ' +
+    'real position: what has landed, what is in flight, and the live blocker or ' +
+    'needed answer. If the agent is waiting on the developer, say exactly what for. ' +
+    'Be concrete (real file names, branches, SHAs, error messages — one specific ' +
+    'anchor beats abstractions). Never narrate turn by turn, hedge, or pad. If the ' +
+    'conversation has barely started, still emit your best two lines.\n' +
+    '\n' +
+    'Examples of the shape (from other conversations):\n' +
+    'Goal: Validate + commit the Unit 3 attach-keybinding migration in this worktree.\n' +
+    'State: Done — 17/17 tests green, committed and rebased onto main.\n' +
+    '\n' +
+    'Goal: Build the trimmed-v1 command-plugin seam (orchestrating phases).\n' +
+    'State: Phase 1 landed; waiting on the core-seam worker\'s final.\n' +
+    '\n' +
+    'Goal: Standing personal assistant — iMessage wakes, Reddit scans, small tasks.\n' +
+    'State: Idle — waiting on you: hook pick, map export, Omi timing.';
+/** Put the content FIRST in delimited blocks (roadmap, then conversation), then
+ *  the instruction, so the model reads the content before being told what to do. */
+function recapUserPrompt(conversation, roadmap) {
+    const rm = roadmap !== undefined && roadmap.trim() !== ''
+        ? `<roadmap>\n${roadmap.trim()}\n</roadmap>\n\n`
+        : '';
+    return `${rm}<conversation>\n${conversation}\n</conversation>\n\nWrite the two-line Goal:/State: briefing for the conversation above. Output JUST the two 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. Thinking stays off; model precedence is explicit env
+ *  override → the conversation's live working model → the small fallback. */
+function recapArgs(conversation, liveModel, roadmap) {
+    const override = process.env['CRTR_RECAP_MODEL'];
+    // An explicit operator override wins. Otherwise prefer the live conversation's
+    // current model: it just completed a successful turn, while a hard-pinned
+    // provider (the old Haiku-only path) may be rate-limited and silently produce
+    // no brief. The small default remains for sessions with no resolved model yet.
+    const model = override !== undefined && override.trim() !== ''
+        ? override.trim()
+        : liveModel !== undefined && liveModel.trim() !== ''
+            ? liveModel.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, roadmap),
+    ];
+    return argv;
+}
+/** Normalize model stdout to the two-line `Goal:`/`State:` briefing. Collapses
+ *  intra-line whitespace and drops blank lines; the viewer paints each line
+ *  (wrapping to its width). A garbled shape still returns whatever lines came
+ *  back — the widget is best-effort chrome, not a contract. */
+function parseRecap(stdout) {
+    return stdout
+        .split('\n')
+        .map((l) => l.replace(/\s+/g, ' ').trim())
+        .filter((l) => l !== '')
+        .join('\n');
+}
+/** Ask pi headlessly for a concise briefing of `conversation`, async. Invokes
+ *  `onRecap` with the parsed string 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, liveModel, roadmap) {
+    const body = (conversation ?? '').trim();
+    if (body === '')
+        return;
+    try {
+        const child = execFile(process.execPath, [resolveBundledPiCliPath(), ...recapArgs(body, liveModel, roadmap)], { encoding: 'utf8', timeout: RECAP_TIMEOUT_MS, env: bundledPiSubprocessEnv() }, (err, stdout) => {
+            if (err || typeof stdout !== 'string')
+                return; // silent — no recap
+            const briefing = parseRecap(stdout);
+            if (briefing === '')
+                return;
+            try {
+                onRecap(briefing);
+            }
+            catch { /* best-effort */ }
+        });
+        child.stdin?.end(); // immediate EOF — see the doc above
+    }
+    catch {
+        // best-effort: no recap
+    }
+}

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

@@ -0,0 +1,14 @@
+export interface RecycleResult {
+    /** True when the pane was recycled (a fresh root respawned in it). */
+    recycled: boolean;
+    /** True when a `final` report was pushed for the recycled node. */
+    finalized: boolean;
+    /** The fresh root node booted into the pane, or null on failure. */
+    newRoot: string | null;
+    /** Subscriber node ids that received the final report. */
+    delivered: string[];
+}
+/** Finish `nodeId` and recycle its pane into a fresh root. `callerPane` is the
+ *  tmux pane the agent occupies (the Alt+C menu passes it as `#{pane_id}`).
+ *  Best-effort; `recycled:false` when there is no pane to act on. */
+export declare function recycleNode(nodeId: string, callerPane?: string): Promise<RecycleResult>;

package/dist/core/runtime/recycle.js

@@ -0,0 +1,158 @@
+// recycle.ts — the "finalize + reboot this pane" action behind `crtr node lifecycle recycle`.
+//
+// Recycle FINALIZES the agent occupying a tmux pane and recycles that pane for
+// fresh work, in three steps:
+//
+//   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    — 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 lifecycle demote` (flip-to-terminal IN PLACE, which keeps
+// the agent focused and running): recycle ENDS this agent and boots a brand-new
+// resident root here.
+//
+// The agent's real conversation lives inside pi (not on disk), so the final
+// body is its newest report (which, on a natural stop, IS its last assistant
+// 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, setFocusOccupant, fullName } from '../canvas/index.js';
+import { reportsDir } from '../canvas/paths.js';
+import { pushFinal } from '../feed/feed.js';
+import { spawnNode, rootOfSpine } from './nodes.js';
+import { buildLaunchSpec, buildPiArgv } from './launch.js';
+import { focusOf, respawnPaneSync, setPaneOption } from './placement.js';
+import { waitForBrokerViewSocket, viewerSplitEnv } from './placement-tmux.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. */
+function lastReportBody(nodeId) {
+    try {
+        const dir = reportsDir(nodeId);
+        const files = readdirSync(dir).filter((f) => f.endsWith('.md'));
+        if (files.length === 0)
+            return '';
+        let newest = '';
+        let newestMs = -1;
+        for (const f of files) {
+            const ms = statSync(join(dir, f)).mtimeMs;
+            if (ms > newestMs) {
+                newestMs = ms;
+                newest = f;
+            }
+        }
+        const raw = readFileSync(join(dir, newest), 'utf8');
+        // Strip leading YAML frontmatter: ---\n …\n---\n<body>
+        const m = /^---\n[\s\S]*?\n---\n/.exec(raw);
+        return (m !== null ? raw.slice(m[0].length) : raw).trim();
+    }
+    catch {
+        return '';
+    }
+}
+/** Finish `nodeId` and recycle its pane into a fresh root. `callerPane` is the
+ *  tmux pane the agent occupies (the Alt+C menu passes it as `#{pane_id}`).
+ *  Best-effort; `recycled:false` when there is no pane to act on. */
+export async function recycleNode(nodeId, callerPane) {
+    const meta = getNode(nodeId);
+    if (meta === null)
+        return { recycled: false, finalized: false, newRoot: null, delivered: [] };
+    const pane = callerPane ?? process.env['TMUX_PANE'];
+    if (pane === undefined || pane === '') {
+        return { recycled: false, finalized: false, newRoot: null, delivered: [] };
+    }
+    // 1. Finalize — fan the agent's last message out as a `final`, mark it done.
+    const body = lastReportBody(nodeId) ||
+        `Closed via recycle — no final summary was authored by ${meta.name}.`;
+    let delivered = [];
+    let finalized = false;
+    try {
+        const res = await pushFinal(nodeId, body);
+        delivered = res.deliveredTo;
+        finalized = true;
+    }
+    catch { /* recycle the pane even if the report failed */ }
+    // The node's pane is a VIEWER (`crtr surface 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.
+    const f = focusOf(nodeId);
+    try {
+        setPresence(nodeId, { pane: null, window: null, tmux_session: null });
+    }
+    catch { /* best-effort */ }
+    // 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 */ }
+    // Resolve against the RECYCLED node's cwd + profile (not this process's
+    // ambient scope) and carry the profile onto the fresh root — it is the same
+    // person's seat, so profile-scope defaults (e.g. a persisted /model default)
+    // must keep applying.
+    const { launch } = buildLaunchSpec('general', 'base', { lifecycle: 'resident', hasManager: false, cwd: meta.cwd, profileId: meta.profile_id });
+    const root = spawnNode({
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'resident',
+        cwd: meta.cwd,
+        name: 'general',
+        parent: null,
+        profile_id: meta.profile_id,
+        launch,
+    });
+    // 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) {
+        try {
+            setFocusOccupant(f.focus_id, root.node_id);
+        }
+        catch { /* best-effort */ }
+    }
+    const fresh = getNode(root.node_id);
+    const inv = buildPiArgv(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 = await recycleBrokerViewer(fresh, pane, inv);
+    return { recycled: ok, finalized, newRoot: root.node_id, delivered };
+}
+/** 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),
+ *  wait for its view.sock to accept, then respawn the pane in place to the VIEWER
+ *  `crtr surface attach to <root>`. The pane stays a viewer (attach self-tags it
+ *  `@crtr_node`); it never hosts the engine. Returns false (recycle reports the
+ *  pane was not respawned) when the broker never serves — the fresh root row
+ *  still exists, broker-hosted, for the daemon to revive. */
+async function recycleBrokerViewer(fresh, pane, inv) {
+    const placed = headlessBrokerHost.launch(fresh.node_id, inv, { cwd: fresh.cwd, name: fullName(fresh), resuming: false });
+    if (placed.pid === null)
+        return false;
+    if (!(await waitForBrokerViewSocket(fresh.node_id, placed.exited)))
+        return false;
+    // 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 surface attach` re-tags
+    // on connect. Node ids are shell-safe identifiers; no quoting needed.
+    try {
+        setPaneOption(pane, '@crtr_node', '');
+    }
+    catch { /* best-effort */ }
+    // SYNC respawn: the recycle command runs as a SEPARATE CLI process (the viewer
+    // runs `crtr surface attach`, a TUI — it never execs recycle), so we are NOT respawning
+    // our own pane and can confirm the respawn actually landed (the honest exit
+    // status), unlike the tmux path which often recycles the caller's own pane.
+    return respawnPaneSync({ pane, cwd: fresh.cwd, env: viewerSplitEnv(), command: `crtr surface attach to ${fresh.node_id}` });
+}

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

@@ -0,0 +1,32 @@
+/** Validate a target is NOT latched (the ordinary, non-reopen doorway). Reads
+ *  `final_report` fresh — never a caller-supplied snapshot. Throws
+ *  `node_finalized` when latched; otherwise a no-op (the common case). No
+ *  side effect either way. */
+export declare function assertNotFinalized(nodeId: string): void;
+/** Validate a target IS latched (the `--reopen` doorway) and return the exact
+ *  `final_report` value observed, so the caller can CAS-clear it later via
+ *  `commitReopen` — once every OTHER fallible precondition the requested
+ *  operation needs has already passed (e.g. `--fresh`'s recoverable-state
+ *  check). Throws `not_finalized` when the target has nothing to clear. Pure
+ *  read — never mutates. */
+export declare function assertFinalizedForReopen(nodeId: string): string;
+/** Clear `nodeId`'s finalization latch — retract-pointer-only (only
+ *  `final_report`/`finalized_at`; the report file and every delivered feed
+ *  event are untouched). CAS'd against `expectedFinalReport` (the value the
+ *  caller observed via `assertFinalizedForReopen`): if the row no longer
+ *  matches — a concurrent `--reopen` already cleared it, or (impossible
+ *  without a reopen in between, but defended anyway) a fresh final landed —
+ *  this throws `reopen_latch_changed` instead of silently clobbering a newer
+ *  canonical result. Callers MUST NOT proceed to revive/deliver when this
+ *  throws. */
+export declare function commitReopen(nodeId: string, expectedFinalReport: string): void;
+/** Convenience wrapper for a doorway with NO intervening fallible step between
+ *  the gate check and the reopen clear (`node lifecycle revive` has nothing
+ *  fallible between the gate and `reviveNode`). Validates and, when `reopen`,
+ *  clears in one call.
+ *
+ *  - `reopen` false + latched → throws `node_finalized`.
+ *  - `reopen` true + latched → CAS-clears the latch (side effect) and returns.
+ *  - `reopen` true + not latched → throws `not_finalized`.
+ *  - `reopen` false + not latched → no-op (the common case). */
+export declare function assertReopenGate(nodeId: string, reopen: boolean): void;

package/dist/core/runtime/reopen.js

@@ -0,0 +1,119 @@
+// The re-task/reopen gate (#339) — enforced at every doorway that can revive a
+// node: `node message send` immediate delivery, `node wait deadline`, and
+// `node lifecycle revive`.
+//
+// `final_report` is a write-once latch (`feed.ts`'s `commitCanonicalFinal`);
+// nothing else ever clears it. Reviving a latched node without reconciling
+// that latch hands it a mandate whose only completion verb — `push final` —
+// is guaranteed to error against the still-set column. So every doorway
+// refuses instead of silently reviving; the refusal names the one remedy,
+// `--reopen`, which clears ONLY the live pointer (retract-pointer-only — the
+// report file on disk and every already-delivered feed event are untouched)
+// so the node's next real `push final` re-latches through the normal
+// `WHERE final_report IS NULL` guard.
+//
+// Concurrency (#340 review): every check here reads `final_report` FRESH from
+// the DB — never a caller-cached snapshot from an earlier point in the
+// command — and the actual clear is a compare-and-swap (`UPDATE ... WHERE
+// final_report = <the exact value just observed>`), mirroring the CAS
+// `commitCanonicalFinal` already uses in feed.ts and the `BEGIN
+// IMMEDIATE`-guarded critical section `reviveNode` already uses in revive.ts.
+// This closes two races a stale-snapshot + unconditional clear left open:
+//   1. Two concurrent `--reopen` calls both observe final A. The first clears
+//      and revives; the node produces a NEW final B. The second (delayed)
+//      call's clear, if unconditional, would erase B. CAS-conditioning the
+//      UPDATE on the specific value each caller observed makes the second
+//      call's compare fail (0 rows) instead of clobbering B — it throws
+//      `reopen_latch_changed` and must NOT proceed to revive/deliver.
+//   2. A target finalizes AFTER a NO-reopen caller's gate check but BEFORE its
+//      delivery/revive actually runs — reviveNode's own belt-and-suspenders
+//      check (revive.ts, same `BEGIN IMMEDIATE` section as the double-launch
+//      guard) refuses to revive a node whose `final_report` is set, closing
+//      the remaining window as close to the true side effect as the codebase
+//      already gets for the double-launch race this pattern was modeled on.
+//
+// `assertFinalizedForReopen`/`commitReopen` are deliberately split (not one
+// check-and-clear call) so a caller with an intervening fallible precondition
+// (such as fresh-revive's recoverable-state check) can validate BEFORE
+// mutating the live pointer — the explicit operation must not retract a
+// canonical final unless it can actually enact the requested re-task.
+import { join } from 'node:path';
+import { openDb, reportsDir } from '../canvas/index.js';
+import { InputError } from '../io.js';
+function currentFinalReport(nodeId) {
+    const row = openDb().prepare('SELECT final_report FROM nodes WHERE node_id = ?').get(nodeId);
+    return row?.final_report ?? null;
+}
+function throwNodeFinalized(nodeId, finalReport) {
+    const reportPath = join(reportsDir(nodeId), finalReport);
+    throw new InputError({
+        error: 'node_finalized',
+        message: `${nodeId} already submitted its canonical final result (${reportPath}) — reviving it now would hand it a mandate it can never finish, since a second \`push final\` always errors against an already-latched node.`,
+        next: `Re-run this exact command with --reopen to clear ${nodeId}'s spent latch and re-task it in place.`,
+    });
+}
+function throwNotFinalized(nodeId) {
+    throw new InputError({
+        error: 'not_finalized',
+        message: `${nodeId} is not finalized — --reopen has nothing to clear.`,
+        next: 'Drop --reopen.',
+    });
+}
+/** Validate a target is NOT latched (the ordinary, non-reopen doorway). Reads
+ *  `final_report` fresh — never a caller-supplied snapshot. Throws
+ *  `node_finalized` when latched; otherwise a no-op (the common case). No
+ *  side effect either way. */
+export function assertNotFinalized(nodeId) {
+    const finalReport = currentFinalReport(nodeId);
+    if (finalReport !== null)
+        throwNodeFinalized(nodeId, finalReport);
+}
+/** Validate a target IS latched (the `--reopen` doorway) and return the exact
+ *  `final_report` value observed, so the caller can CAS-clear it later via
+ *  `commitReopen` — once every OTHER fallible precondition the requested
+ *  operation needs has already passed (e.g. `--fresh`'s recoverable-state
+ *  check). Throws `not_finalized` when the target has nothing to clear. Pure
+ *  read — never mutates. */
+export function assertFinalizedForReopen(nodeId) {
+    const finalReport = currentFinalReport(nodeId);
+    if (finalReport === null)
+        throwNotFinalized(nodeId);
+    return finalReport;
+}
+/** Clear `nodeId`'s finalization latch — retract-pointer-only (only
+ *  `final_report`/`finalized_at`; the report file and every delivered feed
+ *  event are untouched). CAS'd against `expectedFinalReport` (the value the
+ *  caller observed via `assertFinalizedForReopen`): if the row no longer
+ *  matches — a concurrent `--reopen` already cleared it, or (impossible
+ *  without a reopen in between, but defended anyway) a fresh final landed —
+ *  this throws `reopen_latch_changed` instead of silently clobbering a newer
+ *  canonical result. Callers MUST NOT proceed to revive/deliver when this
+ *  throws. */
+export function commitReopen(nodeId, expectedFinalReport) {
+    const result = openDb()
+        .prepare('UPDATE nodes SET final_report = NULL, finalized_at = NULL WHERE node_id = ? AND final_report = ?')
+        .run(nodeId, expectedFinalReport);
+    if (result.changes === 0) {
+        throw new InputError({
+            error: 'reopen_latch_changed',
+            message: `${nodeId}'s finalization latch changed since it was last inspected — a concurrent --reopen (or a fresh push final) already moved it, so clearing it now would risk erasing a newer canonical result.`,
+            next: 'Re-run this exact command — it will re-inspect the current state before acting.',
+        });
+    }
+}
+/** Convenience wrapper for a doorway with NO intervening fallible step between
+ *  the gate check and the reopen clear (`node lifecycle revive` has nothing
+ *  fallible between the gate and `reviveNode`). Validates and, when `reopen`,
+ *  clears in one call.
+ *
+ *  - `reopen` false + latched → throws `node_finalized`.
+ *  - `reopen` true + latched → CAS-clears the latch (side effect) and returns.
+ *  - `reopen` true + not latched → throws `not_finalized`.
+ *  - `reopen` false + not latched → no-op (the common case). */
+export function assertReopenGate(nodeId, reopen) {
+    if (reopen) {
+        commitReopen(nodeId, assertFinalizedForReopen(nodeId));
+        return;
+    }
+    assertNotFinalized(nodeId);
+}

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

@@ -0,0 +1,68 @@
+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 lifecycle close` OR a root reset — did not finish its OWN work, so it
+ *  unifies on `canceled`; `done` is reserved for finish. 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, exited?: Promise<{
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    }>) => boolean | Promise<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): Promise<RelaunchRootResult | null>;
+export interface ResetRootResult {
+    /** Descendant node ids torn down. Always empty — a child `/new` reaps nothing. */
+    reaped: string[];
+    /** Direct subscriptions dropped. Always empty — a child `/new` detaches nothing. */
+    detached: string[];
+    /** Always false — a child `/new` is not a graph reset (roots route to relaunchRoot). */
+    reset: boolean;
+}
+/** 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;
+export type HandleNewSessionPath = 'reset-child' | 'noop';
+export interface HandleNewSessionResult {
+    path: HandleNewSessionPath;
+}
+/** 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
+ *  (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;