@crouton-kit/crouter 0.3.28 → 0.3.30

package/dist/core/runtime/revive.js

@@ -1,27 +1,25 @@
-// The revive primitive — restores a node to active status under a fresh tmux
-// window. Used by both the supervisor daemon (on crash/refresh detection) and
-// the explicit `crtr canvas revive` command.
+// The revive primitive — restores a node to active status by relaunching its
+// broker engine. Used by both the supervisor daemon (on crash/refresh
+// detection) and the explicit `crtr canvas revive` command.
 //
 // A revive replays the node's persisted LaunchSpec + cwd (the canonical recipe)
-// and routes PLACEMENT through reviveIntoPlacement (§1.4): a non-focused node
-// opens a fresh background window in its home_session (the backstage `crtr` for
-// a child — NEVER a user session); a node that occupies a LIVE focus resumes IN
-// PLACE in that focus pane (respawn-pane -k, no new window). reviveNode never
-// targets meta.tmux_session, so a background revive can no longer open an
-// unbidden window in the user's session.
+// and launches the headless broker host (the only host after the
+// broker-is-the-host cut). It opens NO viewer — it relaunches the engine only;
+// existing viewer panes reconnect to the fresh broker on their own (attach
+// auto-reconnect), and a node with no viewer is brought on screen by the next
+// `focus`.
 //
 //   resume=true  → `pi --session <path|id>` — wakes the saved conversation,
 //                  preferring the absolute session-file path (cwd-immune) over
 //                  the bare session id.
 //   resume=false → fresh pi invocation — the node re-reads its roadmap/context dir.
-import { getNode, updateNode, setPresence, clearPid, fullName, cancelDeadlinesFor, } from '../canvas/index.js';
+//
+// reviveNode remains the ONLY sanctioned launcher of the node engine.
+import { getNode, updateNode, clearPid, fullName, cancelDeadlinesFor, } from '../canvas/index.js';
 import { transition } from './lifecycle.js';
 import { buildPiArgv } from './launch.js';
 import { buildReviveKickoff, drainBearings } from './kickoff.js';
-import { FRONT_DOOR_ENV } from './front-door.js';
-import { reconcile, piCommand, respawnPane, } from './placement.js';
-import { hostFor } from './host.js';
-import { nodeSession, childBackstageOf, rootOfSpine } from './nodes.js';
+import { headlessBrokerHost } from './host.js';
 import { isPidAlive } from '../canvas/pid.js';
 import { clearInjectedDocs } from '../substrate/injected-store.js';
 // ---------------------------------------------------------------------------
@@ -44,29 +42,33 @@ export function resumeArgs(meta, resume) {
 // ---------------------------------------------------------------------------
 // reviveNode
 // ---------------------------------------------------------------------------
-/** 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 function reviveNode(nodeId, opts) {
     const meta = getNode(nodeId);
     if (meta === null) {
         throw new Error(`reviveNode: unknown node ${nodeId}`);
     }
-    // Double-revive guard (pane-keyed, §2.4): reconcile FIRST so a user-moved pane
-    // isn't misread as "not yet revived", then probe pane-existence. A node whose
-    // pane is alive AND whose pi is still RUNNING was already revived by another
-    // path; re-launching would put a SECOND pi on the same session file — no-op.
-    // A FROZEN focus pane (remain-on-exit, F3) is pane-alive but pi-DEAD: that is
-    // the resume-into-focus case and MUST proceed (respawn-pane -k back into the
-    // frozen pane), so the guard gates on pi liveness too, not pane-existence alone.
-    reconcile(nodeId);
+    // Lazy host_kind coerce (§C): a pre-cut row carries host_kind null or 'tmux'.
+    // Every launcher now uses the broker host regardless, loading the same
+    // host-agnostic session.jsonl; persist 'broker' so inspect/history read honest
+    // values and the daemon never branches it back. Mutate the in-memory meta too.
+    if (meta.host_kind !== 'broker') {
+        updateNode(nodeId, { host_kind: 'broker' });
+        meta.host_kind = 'broker';
+    }
+    // Double-revive guard: the broker's isAlive IS isPidAlive(pi_pid), so a node
+    // whose broker pid is still running was already revived by another path —
+    // re-launching would put a SECOND broker on the same session file. No-op.
     const live = getNode(nodeId) ?? meta;
-    if (hostFor(live).isAlive(nodeId) && isPidAlive(live.pi_pid)) {
+    if (isPidAlive(live.pi_pid)) {
         return {
-            window: live.window ?? null,
-            session: live.tmux_session ?? nodeSession(),
+            window: null,
+            session: live.tmux_session ?? null,
             resumed: false,
         };
     }
@@ -99,125 +101,24 @@ export function reviveNode(nodeId, opts) {
         // would instead KEEP the persisted set, continuing the same transcript).
         clearInjectedDocs(nodeId);
     }
-    // Placement owns WHERE this revive lands (§1.4): resume into a live focus pane
-    // if the node occupies one, else a fresh window in its home_session (the
-    // backstage `crtr` for a child — NEVER a user session). reviveIntoPlacement
-    // performs the one atomic setPresence; reviveNode keeps transition+clearPid
-    // around it (the crash-safety ordering, unchanged). THIS is the bug-kill: a
-    // non-focused background revive can no longer new-window into a user session.
+    // The broker host launches the detached engine. reviveNode keeps
+    // transition+clearPid around it (the crash-safety ordering, unchanged). It
+    // opens NO viewer — engine-only; existing viewers reconnect, and a viewer-less
+    // node is brought on screen by the next `focus`.
     transition(nodeId, 'revive');
     // Cancel-on-wake (design §6.4, AC-E1): every revive-for-any-reason (an inbox
     // event, a different wake, a manual focus) drops this node's pending deadline,
     // so the deadline always belongs to the dormancy being left. Writes only the
-    // wakeups table, after the atomic transition above. (reviveInPlace's
-    // transition('boot') needs NO hook — a refresh is the same node continuing,
-    // not leaving a dormancy.)
+    // wakeups table, after the atomic transition above.
     cancelDeadlinesFor(nodeId);
-    const placed = hostFor(meta).launch(nodeId, inv, {
+    headlessBrokerHost.launch(nodeId, inv, {
         cwd: meta.cwd,
         name: fullName(meta),
         resuming,
     });
-    // Window-backed launch: clear the stale pid so the daemon won't re-fire on
-    // it during the new pi's boot. The fresh pi re-records its pid on
-    // session_start; if it never boots, this window closes and the window-gone
-    // pass reaps it.
+    // Clear the stale pid so the daemon won't re-fire on it during the new
+    // broker's boot. The fresh broker re-records its pid during extension bind; if
+    // it never boots, the daemon's boot-grace + surfaceBootFailure own that case.
     clearPid(nodeId);
-    return { window: placed.window, session: placed.session, resumed: resuming };
-}
-// ---------------------------------------------------------------------------
-// reviveInPlace — refresh-yield without churning the window
-// ---------------------------------------------------------------------------
-/** 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 function reviveInPlace(nodeId, pane, respawn = respawnPane) {
-    const meta = getNode(nodeId);
-    if (meta === null) {
-        throw new Error(`reviveInPlace: unknown node ${nodeId}`);
-    }
-    // A refresh-yield is a cycle too — advance the label's trailing N.
-    meta.cycles = (meta.cycles ?? 0) + 1;
-    updateNode(nodeId, { cycles: meta.cycles });
-    // Fresh re-exec → new transcript: reset the on-read doc dedup.
-    clearInjectedDocs(nodeId);
-    // The node's LOCATION — the session its pane physically lives in. The re-exec
-    // is IN PLACE (the pane never moves), so this is preserved unchanged below.
-    const session = meta.tmux_session ?? nodeSession();
-    // Fresh re-exec: same recipe as a no-resume reviveNode, with the kickoff so
-    // the node rebuilds its bearings from disk. Drain the one-shot bearings first,
-    // then build purely.
-    const bearings = drainBearings(meta);
-    const inv = buildPiArgv(meta, { prompt: buildReviveKickoff(meta, bearings) });
-    // CRTR_ROOT_SESSION is the backstage this node's CHILDREN spawn into — NOT the
-    // pane's live `session`. A FOCUSED child's pane is in a USER session (focus
-    // taints meta.tmux_session), so sourcing it from `session` would land any
-    // child it spawns in the user's session, re-tainting that child's
-    // home_session (A-MAJOR-1). childBackstageOf is the taint-immune backstage:
-    // home_session for a managed child, but `nodeSession()` for a ROOT (whose
-    // home_session may itself be a user session it adopted via the inline front
-    // door — sourcing children from it would re-point the root's whole subtree
-    // into the user's session on every refresh-yield).
-    const env = { ...inv.env, CRTR_ROOT_SESSION: childBackstageOf(nodeId), CRTR_SUBTREE: rootOfSpine(nodeId) };
-    const ok = respawn({ pane, cwd: meta.cwd, env, command: piCommand(inv.argv) });
-    if (!ok) {
-        throw new Error(`reviveInPlace: respawn-pane dispatch failed for ${nodeId}`);
-    }
-    // Deliberately DO NOT clear intent here, and DO NOT touch pi_pid. The detached
-    // respawn-pane can't confirm it actually replaced the pi (it kills this very
-    // process mid-flight), so clearing intent optimistically is how a failed
-    // refresh became a silent death: the fresh pi never boots, yet meta says the
-    // refresh completed. Instead we leave intent='refresh' (the fresh pi clears it
-    // on boot — the only proof the respawn worked) and leave pi_pid as the OLD
-    // pid. If the respawn succeeds, the old pi dies and the fresh one overwrites
-    // pid+intent within the daemon's grace window; if it fails, the old pid stays
-    // dead and the daemon's pi-liveness pass revives the node.
-    transition(nodeId, 'boot');
-    // tmux_session may have resolved to the shared session; window is unchanged
-    // (we re-execed in place), so preserve it explicitly.
-    setPresence(nodeId, { tmux_session: session, window: meta.window ?? null });
-    // Window is unchanged (we re-execed in place); report the existing one.
-    return { window: meta.window ?? null, session, resumed: false };
-}
-// ---------------------------------------------------------------------------
-// relaunchRootInPane — boot a CLEAN fresh root in the current pane (option C)
-// ---------------------------------------------------------------------------
-/** 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 function relaunchRootInPane(nodeId, pane) {
-    const meta = getNode(nodeId);
-    if (meta === null) {
-        throw new Error(`relaunchRootInPane: unknown node ${nodeId}`);
-    }
-    // No prompt, no resume → a brand-new root conversation at cycle 0.
-    // Brand-new transcript: reset the on-read doc dedup.
-    clearInjectedDocs(nodeId);
-    const inv = buildPiArgv(meta, {});
-    // Source CRTR_ROOT_SESSION from childBackstageOf, the same backstage rule as
-    // reviveInPlace. relaunchRootInPane runs only on a root, whose children must
-    // flow to the shared backstage `nodeSession()` — never the root's own adopted
-    // user session — so both in-pane revive paths stay sourced identically.
-    const env = { ...inv.env, CRTR_ROOT_SESSION: childBackstageOf(nodeId), CRTR_SUBTREE: rootOfSpine(nodeId), [FRONT_DOOR_ENV]: '1' };
-    const ok = respawnPane({ pane, cwd: meta.cwd, env, command: piCommand(inv.argv) });
-    if (!ok) {
-        throw new Error(`relaunchRootInPane: respawn-pane dispatch failed for ${nodeId}`);
-    }
-    // Do NOT clear intent/pi_pid here — the fresh pi clears intent='refresh' on
-    // its session_start boot (the only proof the respawn worked), same dance as
-    // reviveInPlace.
+    return { window: null, session: meta.tmux_session ?? null, resumed: resuming };
 }

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

@@ -6,14 +6,11 @@ export interface BootRootOpts {
     name?: string;
     /** Optional starter prompt (bare `crtr` requires none). */
     prompt?: string;
-    /** Tri-state host selection: `true`/`false` from an explicit
-     *  `--headless`/`--no-headless`, `undefined` to defer to the `headless`
-     *  config default. When it resolves to broker, the front door boots a
-     *  DETACHED broker root and auto-attaches a viewer inline in this pane. */
-    headless?: boolean;
 }
-/** Create a root node and bring up its pi. Returns the node; for 'inline' this
- *  only returns after pi exits (it took over the terminal). */
+/** Create the front-door root: launch its broker engine, then exec `crtr attach`
+ *  inline so THIS terminal becomes the broker's controller-viewer. Does not
+ *  return — it process.exit()s when the inline attach exits (detach leaves the
+ *  resident broker running, to be reconnected later). */
 export declare function bootRoot(opts: BootRootOpts): NodeMeta;
 export interface SpawnChildOpts {
     kind: string;
@@ -40,24 +37,26 @@ export interface SpawnChildOpts {
      *  a <crtr-wake> block is prepended to the kickoff so the newborn knows a clock
      *  birthed it. */
     wakeOrigin?: WakeOrigin;
-    /** Which HOST launches + supervises this node: a tmux pane (default) or the
-     *  headless broker. Persisted as `host_kind` at birth (resolved from
-     *  `--headless` / the `headless` config default by the caller). */
-    hostKind?: 'tmux' | 'broker';
     /** Pin the node to a model TIER (ultra/strong/medium/light), overriding the
      *  persona's declared default. Persisted to `meta.model_override` so it
      *  survives polymorphs. Omit to use the persona default. */
     model?: string;
 }
-/** Resolve a `--fork-from` value to the source pi gets as `--fork <path|id>`.
- *  A live node id resolves to its captured session FILE (absolute, cwd-immune),
- *  falling back to its bare session id; a path or partial uuid passes straight
- *  through to pi. Throws when a known node has no session to fork yet. */
+/** Resolve a `--fork-from` value to an ABSOLUTE `.jsonl` source path for the
+ *  broker fork (`SessionManager.forkFrom`, which loads a file — never a bare id).
+ *  A live node id resolves to its captured session FILE (absolute, cwd-immune); a
+ *  relative path is made absolute; a bare/partial uuid is resolved against pi's
+ *  sessions store. Throws when a known node has no captured session file, or when
+ *  a uuid resolves to zero or multiple sessions. */
 export declare function resolveForkSource(value: string): string;
 export interface SpawnChildResult {
     node: NodeMeta;
+    /** The viewer window opened for a --root in tmux; null otherwise (a managed
+     *  child opens no viewer, and a --root spawned outside tmux opens none). */
     window: string | null;
-    session: string;
+    /** The session the --root's viewer opened into (the caller's current session);
+     *  null when no viewer was opened. */
+    session: string | null;
 }
 /** Resolve who a spawn is attributed to. A managed child needs a spine parent
  *  (explicit `--parent` or the calling node's CRTR_NODE_ID). A --root spawn