@crouton-kit/crouter 0.3.27 → 0.3.29

package/dist/core/runtime/reset.js

@@ -1,33 +1,31 @@
-// Root reset + relaunch — the `/new` equivalents, plus clean-exit termination.
+// `/new` handling — root relaunch + child session-id refresh — 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 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:
+// A node's engine is a detached broker process bound to one CRTR_NODE_ID, and
+// its on-screen viewer is a SEPARATE `crtr attach` pane. `/new` splits by who
+// ran it:
 //
-//   • relaunchRoot (option C) — for a ROOT in a tmux pane: PARK the old root
-//     (mark canceled, 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.
+//   • relaunchRoot — a `/new` on a ROOT starts a genuinely new node: the old
+//     root is parked `done` (kept as history), a fresh node id + broker is
+//     minted in the same pane/cwd, and the viewer pane is re-pointed at the new
+//     broker. The new broker is booted FIRST, so any failure before the commit
+//     point leaves the old root fully intact.
+//   • resetRoot — a `/new` on a non-root child refreshes its session id only, so
+//     a later `--session <id>` wakes the right conversation.
 //
 // 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 `canceled` explicitly here (A5: an externally-reaped
-// node did not finish its own work — done is reserved for finalize).
+// (markCleanExitDone); only a true crash leaves it `dead`. A force-kill fires NO
+// clean session_shutdown, so reaped descendants are marked `canceled` explicitly
+// here (A5: an externally-reaped node did not finish its own work — done is
+// reserved for finalize).
 //
-// Best-effort throughout: a tmux/fs failure on one node never aborts the reset.
-import { existsSync, rmSync } from 'node:fs';
-import { getNode, updateNode, setPresence, clearPid, setFocusOccupant, subscriptionsOf, unsubscribe, view, reportsDir, inboxPath, nodeDir, openDb, } from '../canvas/index.js';
+// Best-effort throughout: a tmux/fs failure on one node never aborts the reap.
+import { getNode, updateNode, fullName, closeFocusRow, view, } from '../canvas/index.js';
 import { transition } from './lifecycle.js';
-import { hostFor } from './host.js';
-import { paneLocation, focusOf } from './placement.js';
-import { buildLaunchSpec } from './launch.js';
-import { roadmapPath } from './roadmap.js';
-import { spawnNode, newNodeId, nodeSession } from './nodes.js';
-import { relaunchRootInPane } from './revive.js';
+import { headlessBrokerHost } from './host.js';
+import { tearDownNode, focusOf, registerViewerFocus, respawnPaneSync, viewerSplitEnv, windowOfPane, renameWindow, waitForBrokerViewSocket, } from './placement.js';
+import { buildLaunchSpec, buildPiArgv } from './launch.js';
+import { spawnNode, rootOfSpine } from './nodes.js';
 // ---------------------------------------------------------------------------
 // reapDescendants — tear down a root's descendant sub-DAG (shared helper)
 // ---------------------------------------------------------------------------
@@ -37,25 +35,25 @@ import { relaunchRootInPane } from './revive.js';
  *  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 function reapDescendants(rootId) {
     const reaped = [];
     for (const id of view(rootId)) {
         try {
-            // Reap BEFORE tearing down the placement (the crash-safety invariant the
-            // `cancel` event encodes): a non-supervised status + cleared intent first, so
-            // the daemon can't revive a descendant mid-teardown. Teardown then routes
-            // through the Host seam (hostFor): a tmux node closes any focus row it held,
-            // kills its pane (pane-keyed), and nulls its LOCATION; a broker node sends
-            // the `shutdown` frame so its PROCESS exits and releases the .jsonl writer.
-            const m = transition(id, 'cancel');
-            hostFor(m).teardown(id);
+            // Reap BEFORE tearing down the engine (the crash-safety invariant the
+            // `cancel` event encodes): a non-supervised status + cleared intent first,
+            // so the daemon can't revive a descendant mid-teardown. Teardown then sends
+            // the broker the `shutdown` frame so its PROCESS exits and releases the
+            // sole .jsonl writer; tearDownNode then proactively closes the on-screen
+            // viewer pane + registry row (attach auto-reconnects, so the viewer must be
+            // closed here or it lingers ~30s in a misleading "reconnecting…" state).
+            transition(id, 'cancel');
+            headlessBrokerHost.teardown(id);
+            tearDownNode(id);
             reaped.push(id);
         }
         catch {
@@ -64,194 +62,109 @@ export function reapDescendants(rootId) {
     }
     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 `--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) {
-            updateNode(nodeId, {
-                pi_session_id: newSessionId,
-                ...(newSessionFile !== undefined ? { pi_session_file: newSessionFile } : {}),
-            });
-        }
-        return { reaped: [], detached: [], reset: false };
-    }
-    // 1) Reap the descendant sub-DAG (mark canceled + 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)) {
-        unsubscribe(nodeId, sub.node_id);
-        detached.push(sub.node_id);
-    }
-    // 3) Wipe the root's working state (reports / inbox / roadmap).
-    for (const p of [
-        reportsDir(nodeId),
-        inboxPath(nodeId),
-        `${inboxPath(nodeId)}.cursor`,
-        roadmapPath(nodeId),
-    ]) {
-        try {
-            if (existsSync(p))
-                rmSync(p, { recursive: true, force: true });
-        }
-        catch {
-            /* */
-        }
-    }
-    // 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, model: meta.model_override ?? undefined });
-    updateNode(nodeId, {
+/** 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 function relaunchRoot(oldId, deps = {}) {
+    const launchBroker = deps.launchBroker ?? headlessBrokerHost.launch;
+    const waitForViewSocket = deps.waitForViewSocket ?? waitForBrokerViewSocket;
+    const respawnViewer = deps.respawnViewer ?? respawnPaneSync;
+    const teardownBroker = deps.teardownBroker ?? headlessBrokerHost.teardown;
+    const old = getNode(oldId);
+    if (old === null || old.parent != null)
+        return null; // roots only
+    if (old.status === 'done')
+        return null; // defensive: a double `/new`
+    const oldFocus = focusOf(oldId); // capture the viewer BEFORE any teardown
+    // --- mint + boot the NEW broker FIRST (a failure here leaves the old root
+    //     untouched) ---
+    // A relaunched root is a fresh resident base, exactly like the front door.
+    const { launch } = buildLaunchSpec(old.kind, 'base', {
+        lifecycle: 'resident',
+        hasManager: false,
+        model: old.model_override ?? undefined,
+    });
+    const newMeta = spawnNode({
+        kind: old.kind,
         mode: 'base',
         lifecycle: 'resident',
-        persona_ack: { mode: 'base', lifecycle: 'resident' },
+        cwd: old.cwd,
+        name: old.kind,
+        parent: null,
         launch,
-        ...(newSessionId !== undefined ? { pi_session_id: newSessionId } : {}),
-        ...(newSessionFile !== undefined ? { pi_session_file: newSessionFile } : {}),
+        modelOverride: old.model_override ?? undefined,
     });
-    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 };
+    const inv = buildPiArgv(newMeta, {});
+    // Mirror bootRoot's subtree routing on inv.env (the broker host merges it; it
+    // sets CRTR_FRONT_DOOR itself).
+    inv.env = {
+        ...inv.env,
+        CRTR_SUBTREE: rootOfSpine(newMeta.node_id),
+    };
+    const placed = launchBroker(newMeta.node_id, inv, {
+        cwd: old.cwd,
+        name: fullName(newMeta),
+        resuming: false,
+    });
+    if (placed.pid == null) {
+        // The new broker never started — crash the half-born node and BAIL. The old
+        // root is still live and untouched (nothing below this point has run).
+        transition(newMeta.node_id, 'crash');
+        return null;
     }
-    catch {
-        resetRoot(nodeId, newSessionId, newSessionFile);
-        return { path: 'reset-root' };
+    waitForViewSocket(newMeta.node_id); // best-effort; attach auto-redials on miss
+    // --- COMMIT: park + reap the old root, re-point the viewer, kill the old
+    //     broker. Past this point the new node is the live root. ---
+    reapDescendants(oldId); // old workers → canceled + torn down
+    // Park the old root DONE (kept as history; NOT canceled — a relaunched root
+    // finished cleanly, the user just started fresh). Its reports/inbox/roadmap
+    // are left on disk as the record of that session.
+    transition(oldId, 'finalize');
+    if (oldFocus?.pane != null) {
+        closeFocusRow(oldFocus.focus_id);
+        respawnViewer({
+            pane: oldFocus.pane,
+            cwd: old.cwd,
+            env: viewerSplitEnv(),
+            command: `crtr attach to ${newMeta.node_id}`,
+        });
+        const window = windowOfPane(oldFocus.pane);
+        if (window !== null)
+            renameWindow(window, fullName(newMeta));
+        registerViewerFocus(newMeta.node_id, oldFocus.pane, oldFocus.session, window);
     }
+    teardownBroker(oldId); // old broker exits cleanly (its /new work is discarded)
+    return { newNodeId: newMeta.node_id };
 }
-/** 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 === 'canceled')
-        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, model: oldMeta.model_override ?? undefined });
-    // 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 {
-        // 1) Reap descendants (mark canceled + 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',
-            cwd: oldMeta.cwd,
-            name: oldMeta.kind,
-            parent: null,
-            spawnedBy: oldId, // audit-only successor link; does NOT touch the spine
-            nodeId: newId,
-            modelOverride: oldMeta.model_override,
-            launch,
+/** 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 function resetRoot(nodeId, newSessionId, newSessionFile) {
+    const meta = getNode(nodeId);
+    const empty = { reaped: [], detached: [], reset: false };
+    if (meta === null || meta.parent == null)
+        return empty; // unknown or a root
+    if (newSessionId !== undefined) {
+        updateNode(nodeId, {
+            pi_session_id: newSessionId,
+            ...(newSessionFile !== undefined ? { pi_session_file: newSessionFile } : {}),
         });
-        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: cancel (canceled + intent cleared) and detach its
-        //    window so it never claims the pane, but KEEP pi_session_id (resumable),
-        //    parent=null, and all edges. A5: a superseded old root did not finish its
-        //    own work — it unifies on `canceled` like every other external reap.
-        transition(oldId, 'cancel');
-        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 (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 { newNodeId: newId };
+    return empty;
+}
+/** 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 function handleNewSession(nodeId, newSessionId, newSessionFile) {
+    const meta = getNode(nodeId);
+    if (meta === null)
+        return { path: 'noop' };
+    resetRoot(nodeId, newSessionId, newSessionFile);
+    return { path: 'reset-child' };
 }
 // ---------------------------------------------------------------------------
 // markCleanExitDone — the clean-exit→done termination guard

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

@@ -1,6 +1,5 @@
 import { type NodeMeta } from '../canvas/index.js';
 import type { WakeOrigin } from './bearings.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
@@ -12,41 +11,22 @@ export declare function resumeArgs(meta: NodeMeta, resume: boolean): {
     resumeSessionPath?: string;
 };
 export interface ReviveResult {
-    /** The new tmux window id, or null if openNodeWindow failed. */
+    /** Always null — the broker engine is never placed in a tmux window. Kept on
+     *  the result for caller back-compat. */
     window: string | null;
-    /** The tmux session the node was placed in. */
-    session: string;
+    /** The node's last live LOCATION session, or null — the broker engine has no
+     *  tmux session of its own (it opens no viewer). Kept for caller back-compat. */
+    session: string | null;
     /** 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.
+/** Relaunch `nodeId`'s broker engine from its persisted recipe and update canvas
+ *  meta. Opens no viewer (engine-only).
  *
- *  Throws if the node does not exist. All other failures (e.g. tmux not
- *  available) propagate as-is — callers (daemon, command) decide how to handle.
+ *  Throws if the node does not exist. All other failures propagate as-is —
+ *  callers (daemon, command) decide how to handle.
  */
 export declare function reviveNode(nodeId: string, opts: {
     resume: boolean;
     wakeReason?: WakeOrigin;
 }): ReviveResult;
-/** Re-exec a node's pi FRESH in its EXISTING tmux pane (the refresh-yield
- *  path). Unlike `reviveNode`, this opens no new window: the pane's current pi
- *  is replaced in place via `respawn-pane -k`, so a foreground/interactive
- *  session keeps its terminal and a background node keeps its window. Always
- *  fresh (no resume) — the node re-reads its roadmap/context dir.
- *
- *  `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, 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;