@crouton-kit/crouter 0.3.14 → 0.3.16

package/dist/core/runtime/revive.js

@@ -2,16 +2,55 @@
 // window. Used by both the supervisor daemon (on crash/refresh detection) and
 // the explicit `crtr canvas revive` command.
 //
-// A revive always opens a NEW window: the old one is gone (crashed, or the
-// node exited with intent=refresh). The node's persisted LaunchSpec and cwd
-// are the canonical recipe; reviveNode replays them faithfully.
+// 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.
 //
-//   resume=true  → `pi --resume <pi_session_id>` — wakes the saved conversation.
+//   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, } from '../canvas/index.js';
+import { getNode, updateNode, setPresence, clearPid, fullName, } from '../canvas/index.js';
+import { transition } from './lifecycle.js';
 import { buildPiArgv } from './launch.js';
-import { buildReviveKickoff } from './kickoff.js';
-import { ensureSession, openNodeWindow, piCommand, respawnPane, nodeSession, } from './tmux.js';
+import { buildReviveKickoff, drainBearings } from './kickoff.js';
+import { FRONT_DOOR_ENV } from './front-door.js';
+import { reviveIntoPlacement, reconcile, isNodePaneAlive, homeSessionOf, piCommand, respawnPane, } from './placement.js';
+import { nodeSession } from './nodes.js';
+/** signal-0 liveness probe for a pi pid (mirrors the daemon's isPidAlive). A
+ *  null pid (legacy / never-booted) reads dead. */
+function pidAlive(pid) {
+    if (pid == null)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
+// ---------------------------------------------------------------------------
+// resumeArgs — which session source a revive resumes from
+// ---------------------------------------------------------------------------
+/** 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
+ *  captured. buildPiArgv prefers the path when both are present. resume=false (a
+ *  refresh-yield) selects neither — the node re-reads its roadmap fresh. Pure so
+ *  the path-vs-id selection is unit-testable without tmux. */
+export function resumeArgs(meta, resume) {
+    if (!resume)
+        return {};
+    return {
+        resumeSessionId: meta.pi_session_id ?? undefined,
+        resumeSessionPath: meta.pi_session_file ?? undefined,
+    };
+}
 // ---------------------------------------------------------------------------
 // reviveNode
 // ---------------------------------------------------------------------------
@@ -25,35 +64,63 @@ export function reviveNode(nodeId, opts) {
     if (meta === null) {
         throw new Error(`reviveNode: unknown node ${nodeId}`);
     }
-    // The node lives in the shared global session. Prefer its stored session
-    // (an inline root tracks its own real terminal session); fall back to the
-    // shared node session.
-    const session = meta.tmux_session ?? nodeSession();
-    ensureSession(session, meta.cwd);
-    // Decide whether to wake the saved pi conversation or start fresh.
-    const resumeId = opts.resume && meta.pi_session_id != null
-        ? meta.pi_session_id
-        : undefined;
+    // 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);
+    const live = getNode(nodeId) ?? meta;
+    if (isNodePaneAlive(nodeId) && pidAlive(live.pi_pid)) {
+        return {
+            window: live.window ?? null,
+            session: live.tmux_session ?? nodeSession(),
+            resumed: false,
+        };
+    }
+    // Every (re)launch is a new cycle — bump the counter so the editor label's
+    // trailing N advances. Mutate the in-memory meta too so buildPiArgv below
+    // builds the label with the incremented count.
+    meta.cycles = (meta.cycles ?? 0) + 1;
+    updateNode(nodeId, { cycles: meta.cycles });
+    // Decide whether to wake the saved pi conversation or start fresh. Prefer the
+    // absolute session-file path (cwd-immune); fall back to the bare id.
+    const resume = resumeArgs(meta, opts.resume);
+    const resuming = resume.resumeSessionPath !== undefined || resume.resumeSessionId !== undefined;
     // A fresh revive (no resume) gets a kickoff prompt so it re-reads its roadmap
-    // and continues; resuming a saved conversation needs none.
-    const inv = resumeId !== undefined
-        ? buildPiArgv(meta, { resumeSessionId: resumeId })
-        : buildPiArgv(meta, { prompt: buildReviveKickoff(meta) });
-    const env = { ...inv.env, CRTR_ROOT_SESSION: session };
-    const window = openNodeWindow({
-        session,
-        name: meta.name,
-        cwd: meta.cwd,
-        env,
+    // and continues; resuming a saved conversation needs none. drainBearings is the
+    // one-shot consuming step (yield note + feed cursor + persona ack); the builder
+    // is then pure.
+    let inv;
+    if (resuming) {
+        inv = buildPiArgv(meta, resume);
+    }
+    else {
+        const bearings = drainBearings(meta);
+        inv = buildPiArgv(meta, { prompt: buildReviveKickoff(meta, bearings) });
+    }
+    // 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.
+    transition(nodeId, 'revive');
+    const placed = reviveIntoPlacement(nodeId, {
         command: piCommand(inv.argv),
+        env: inv.env,
+        cwd: meta.cwd,
+        name: fullName(meta),
+        resuming,
     });
-    updateNode(nodeId, {
-        status: 'active',
-        intent: null,
-        window,
-        tmux_session: session,
-    });
-    return { window, session, resumed: resumeId !== undefined };
+    // 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.
+    clearPid(nodeId);
+    return { window: placed.window, session: placed.session, resumed: resuming };
 }
 // ---------------------------------------------------------------------------
 // reviveInPlace — refresh-yield without churning the window
@@ -67,21 +134,81 @@ export function reviveNode(nodeId, opts) {
  *  `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) {
+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 });
+    // 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.
-    const inv = buildPiArgv(meta, { prompt: buildReviveKickoff(meta) });
-    const env = { ...inv.env, CRTR_ROOT_SESSION: session };
-    const ok = respawnPane({ pane, cwd: meta.cwd, env, command: piCommand(inv.argv) });
+    // 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 — it must
+    // be the durable REVIVE-HOME (home_session), 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). home_session is
+    // the taint-immune backstage `crtr` for a child; for a root it equals its own
+    // session, so this is behavior-preserving there.
+    const env = { ...inv.env, CRTR_ROOT_SESSION: homeSessionOf(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}`);
     }
-    updateNode(nodeId, { status: 'active', intent: null, tmux_session: session });
+    // 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.
+    const inv = buildPiArgv(meta, {});
+    // Source CRTR_ROOT_SESSION from the durable REVIVE-HOME (home_session), the
+    // same taint-immunity rule as reviveInPlace. relaunchRootInPane runs only on a
+    // root, whose home_session IS its own session, so this is behavior-preserving
+    // — it keeps both in-pane revive paths sourced identically.
+    const env = { ...inv.env, CRTR_ROOT_SESSION: homeSessionOf(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.
+}

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

@@ -5,9 +5,6 @@ export interface BootRootOpts {
     name?: string;
     /** Optional starter prompt (bare `crtr` requires none). */
     prompt?: string;
-    /** 'inline'  — exec pi in the current terminal (bare `crtr`).
-     *  'session' — create a dedicated tmux session and run pi there (`session new`). */
-    placement: 'inline' | 'session';
 }
 /** 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). */
@@ -20,12 +17,30 @@ export interface SpawnChildOpts {
     prompt: string;
     /** Override the parent (defaults to the calling node from env). */
     parent?: string;
+    /** Spawn an INDEPENDENT root instead of a managed child: parent=null, no
+     *  subscription back to the spawner, resident lifecycle, spawned_by=spawner.
+     *  Brought forefront on spawn so a human can drive it directly. */
+    root?: boolean;
+    /** Fork the new node from an existing pi conversation instead of starting it
+     *  fresh: a node id (resolved to that node's session file), an absolute
+     *  `.jsonl` path, or a partial pi session uuid. pi COPIES that history into a
+     *  new session for the child — the source is untouched — then `prompt` is the
+     *  next message. A one-shot at birth; the child resumes its own session after. */
+    forkFrom?: 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. */
+export declare function resolveForkSource(value: string): string;
 export interface SpawnChildResult {
     node: NodeMeta;
     window: string | null;
     session: string;
 }
-/** Spawn a terminal worker as a background window under the root session.
- *  The parent auto-subscribes (active) to it via spawnNode. */
+/** Spawn a node from a live node. By default a managed terminal worker in a
+ *  background window, with the spawner auto-subscribed (active) via spawnNode.
+ *  With `root`: an independent resident root — parent=null, NO subscription back
+ *  to the spawner (it carries spawned_by=spawner for provenance only), brought
+ *  forefront so a human can pick up the conversation directly. */
 export declare function spawnChild(opts: SpawnChildOpts): SpawnChildResult;

package/dist/core/runtime/spawn.js

@@ -2,17 +2,24 @@
 // a running pi process on the canvas. Composes canvas (birth + spine), persona
 // (resolve), launch (pi argv), and tmux (placement).
 //
-//   bootRoot   — a user-opened entry point (bare `crtr`).
-//                Resident. Runs pi in the foreground (inline) or its own session.
-//   spawnChild — a background worker spawned by a live node (`crtr node new`).
-//                Terminal. Opens a non-focus-stealing window under the root.
+//   bootRoot   — the user-opened front door (bare `crtr`). Resident; runs pi
+//                inline, taking over the current terminal.
+//   spawnChild — a node spawned by a live node (`crtr node new`). A managed,
+//                terminal background worker by default; with `root`, an
+//                INDEPENDENT resident root (no subscription back to the spawner,
+//                provenance via spawned_by) brought forefront for direct driving.
 import { spawnSync } from 'node:child_process';
 import { FRONT_DOOR_ENV } from './front-door.js';
-import { spawnNode, currentNodeContext } from './nodes.js';
+import { spawnNode, currentNodeContext, resolveBirthSession, nodeSession } from './nodes.js';
 import { buildLaunchSpec, buildPiArgv } from './launch.js';
 import { writeGoal } from './kickoff.js';
-import { ensureSession, openNodeWindow, piCommand, currentTmux, inTmux, nodeSession, installMenuBinding, installNavBindings, } from './tmux.js';
-import { updateNode, getNode } from '../canvas/index.js';
+import { hasRoadmap, seedRoadmap } from './roadmap.js';
+import { seedMemory, seedUserMemory, seedProjectMemory } from './memory.js';
+import { generateSessionName } from './naming.js';
+import { installMenuBinding, installNavBindings } from './tmux-chrome.js';
+import { setPresence, updateNode, getNode, fullName } from '../canvas/index.js';
+import { registerRootFocus, ensureSession, openNodeWindow, piCommand, currentTmux, inTmux, focusWindow, } from './placement.js';
+import { transition } from './lifecycle.js';
 import { ensureDaemon } from '../../daemon/manage.js';
 /** 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). */
@@ -26,13 +33,20 @@ export function bootRoot(opts) {
     const kind = opts.kind ?? 'general';
     // A born-resident root starts in base mode; it earns the orchestrator persona
     // the first time it delegates (or on promotion). Resident lifecycle either way.
-    const { launch } = buildLaunchSpec(kind, 'base');
+    const { launch } = buildLaunchSpec(kind, 'base', { lifecycle: 'resident', hasManager: false });
+    // A root opened WITH a prompt gets its editor name now (so the first pi
+    // session already carries it). A bare root has no prompt yet — the
+    // goal-capture extension names it from the first message (async, next cycle).
+    const description = opts.prompt !== undefined && opts.prompt.trim() !== ''
+        ? generateSessionName(opts.prompt)
+        : undefined;
     const meta = spawnNode({
         kind,
         mode: 'base',
         lifecycle: 'resident',
         cwd: opts.cwd,
         name: opts.name ?? kind,
+        description,
         parent: null,
         launch,
     });
@@ -55,74 +69,180 @@ export function bootRoot(opts) {
         }
         catch { /* best-effort */ }
     }
-    if (opts.placement === 'session') {
-        updateNode(meta.node_id, { tmux_session: session });
-        const withSession = getNode(meta.node_id);
-        const inv = buildPiArgv(withSession, { prompt: opts.prompt });
-        const env = { ...inv.env, CRTR_ROOT_SESSION: session, [FRONT_DOOR_ENV]: '1' };
-        const win = openNodeWindow({
-            session,
-            name: meta.name,
-            cwd: opts.cwd,
-            env,
-            command: piCommand(inv.argv),
-        });
-        updateNode(meta.node_id, { window: win });
-        return getNode(meta.node_id);
-    }
     // inline: the root's pi takes over THIS terminal, so its own window stays
     // where the user is (its tmux_session tracks that real pane so supervision
     // sees it alive). But its children spawn into the shared global session via
     // CRTR_ROOT_SESSION — they never clutter the user's working session.
     const here = currentTmux();
-    const adopted = here?.session ?? session;
-    updateNode(meta.node_id, { tmux_session: adopted, window: here?.window ?? null });
+    const adopted = resolveBirthSession({ adoptCaller: true, here, rootSession: undefined });
+    setPresence(meta.node_id, { tmux_session: adopted, window: here?.window ?? null, pane: here?.pane ?? null });
+    // REVIVE-HOME: the inline root's durable revive target is the session it
+    // adopts (the caller's when inside tmux, else the shared backstage). Set once
+    // at birth, alongside the live LOCATION above.
+    updateNode(meta.node_id, { home_session: adopted });
+    // Root boot registers focus #1 (§2.6): the FOREGROUND inline root owns the
+    // user's viewport, so its OWN pane becomes a durable focus (remain-on-exit so
+    // a clean exit freezes rather than detaching the terminal). A background
+    // `--root` (spawnChild) does NOT — it stays a plain window until the user
+    // focuses it (§6). Only possible inside tmux (a pane to anchor on).
+    if (here) {
+        try {
+            registerRootFocus(meta.node_id, here.pane, adopted, here.window);
+        }
+        catch { /* best-effort */ }
+    }
     const withSession = getNode(meta.node_id);
     const inv = buildPiArgv(withSession, { prompt: opts.prompt });
     const env = { ...process.env, ...inv.env, CRTR_ROOT_SESSION: session, [FRONT_DOOR_ENV]: '1' };
     const r = spawnSync('pi', inv.argv, { stdio: 'inherit', env });
     process.exit(r.status ?? 0);
 }
-/** Spawn a terminal worker as a background window under the root session.
- *  The parent auto-subscribes (active) to it via spawnNode. */
+/** 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. */
+export function resolveForkSource(value) {
+    const v = value.trim();
+    if (v === '')
+        throw new Error('--fork-from requires a node id, session file, or session uuid.');
+    // A path (contains `/` or ends `.jsonl`) is a session file — hand it to pi as-is.
+    if (v.includes('/') || v.endsWith('.jsonl'))
+        return v;
+    // A live node id — fork from the conversation it has accumulated.
+    const n = getNode(v);
+    if (n !== null) {
+        const src = n.pi_session_file ?? n.pi_session_id;
+        if (src === undefined || src === null || src === '') {
+            throw new Error(`node ${v} has no pi session yet — it has not started a conversation to fork from.`);
+        }
+        return src;
+    }
+    // Not a known node — treat as a bare/partial pi session id for pi to resolve.
+    return v;
+}
+/** Spawn a node from a live node. By default a managed terminal worker in a
+ *  background window, with the spawner auto-subscribed (active) via spawnNode.
+ *  With `root`: an independent resident root — parent=null, NO subscription back
+ *  to the spawner (it carries spawned_by=spawner for provenance only), brought
+ *  forefront so a human can pick up the conversation directly. */
 export function spawnChild(opts) {
     try {
         ensureDaemon();
     }
     catch { /* daemon is best-effort */ }
     const ctx = currentNodeContext();
-    const parent = opts.parent ?? ctx.nodeId;
-    if (parent === null || parent === undefined) {
+    const spawner = opts.parent ?? ctx.nodeId;
+    if (spawner === null || spawner === undefined) {
         throw new Error('spawnChild requires a calling node (CRTR_NODE_ID) or an explicit parent');
     }
+    const root = opts.root === true;
     const mode = opts.mode ?? 'base';
-    const { launch } = buildLaunchSpec(opts.kind, mode);
+    // Lifecycle keys on ROOT-ness only, independent of mode: an independent root
+    // (or `--root`) is resident (a conversation that persists, woken by inbox/
+    // human); every spawned child is terminal — it owes a final up the spine and
+    // reaps when done. A child born as an orchestrator is terminal/orchestrator
+    // (delegates + holds a roadmap, but still reports up), NOT resident.
+    const lifecycle = root ? 'resident' : 'terminal';
+    // Spine: a managed child reports up to its spawner (has a manager); an
+    // independent root sits top-of-spine with nobody to push to. Mirrors the
+    // `parent` set below (root ? null : spawner), so hasManager === parent!==null.
+    const { launch } = buildLaunchSpec(opts.kind, mode, { lifecycle, hasManager: !root });
+    // Name the worker from its task now, so its first editor label carries it.
     const meta = spawnNode({
         kind: opts.kind,
         mode,
-        lifecycle: 'terminal',
+        lifecycle,
         cwd: opts.cwd,
         name: opts.name ?? opts.kind,
-        parent,
+        description: generateSessionName(opts.prompt),
+        // A root has no spine parent (top-level, nobody subscribes); it still
+        // records spawned_by=spawner. A child's parent IS its manager.
+        parent: root ? null : spawner,
+        spawnedBy: root ? spawner : undefined,
         launch,
     });
     // Persist the task as the child's goal for a fresh revive to re-read.
     writeGoal(meta.node_id, opts.prompt);
-    // Children always land in the shared global session: inherited from the
-    // parent's CRTR_ROOT_SESSION, else the default node session.
-    let session = process.env['CRTR_ROOT_SESSION'];
-    if (session === undefined || session === '')
-        session = nodeSession();
+    // A fork copies an existing conversation into this child's first session
+    // (resolved to an absolute file path when forking from a node). Resolved here
+    // — not in buildPiArgv — so a bad reference fails the spawn loudly before any
+    // window opens, rather than after pi is already booting.
+    const forkFrom = opts.forkFrom !== undefined ? resolveForkSource(opts.forkFrom) : undefined;
+    // A child created DIRECTLY as an orchestrator (mode='orchestrator') boots
+    // with the orchestrator persona but bypasses promote(), which is where a
+    // roadmap scaffold would normally be seeded. Lay one down here (goal
+    // pre-filled from the task) so the orchestrator has its memory artifact from
+    // birth, instead of waking memory-less. Guarded so it never clobbers.
+    if (mode === 'orchestrator' && !hasRoadmap(meta.node_id)) {
+        seedRoadmap(meta.node_id, { goal: opts.prompt.trim() });
+    }
+    // Born an orchestrator ⇒ also lay down its three scoped long-term memory
+    // stores, the companions to the roadmap: user-global (key-less), project
+    // (keyed off the child's cwd), and node-local. Each guarded against clobber.
+    if (mode === 'orchestrator') {
+        seedUserMemory();
+        seedProjectMemory(opts.cwd);
+        seedMemory(meta.node_id);
+    }
+    // A managed CHILD lands in the shared global session: inherited from the
+    // parent's CRTR_ROOT_SESSION, else the default node session. A --root spawned
+    // from inside tmux instead opens its window in the CALLER'S CURRENT session,
+    // so it appears where the spawner is working rather than exiled to a separate
+    // crtr session. Either way the root's OWN descendants still flow to the shared
+    // session (childSession) via CRTR_ROOT_SESSION, to keep the subtree from
+    // cluttering the user's session.
+    const rootSessionEnv = process.env['CRTR_ROOT_SESSION'];
+    const here = root ? currentTmux() : null;
+    // The shared backstage the whole subtree flows into (this child's own
+    // CRTR_ROOT_SESSION): the inherited root session, else the default `crtr`.
+    const childSession = resolveBirthSession({ adoptCaller: false, here, rootSession: rootSessionEnv });
+    // Where THIS node's window opens — and its durable REVIVE-HOME. A managed
+    // child lands in the backstage; a --root adopts the caller's current session
+    // when inside tmux, so it appears where the spawner is working.
+    const session = resolveBirthSession({ adoptCaller: root, here, rootSession: rootSessionEnv });
     ensureSession(session, opts.cwd);
-    const inv = buildPiArgv(meta, { prompt: opts.prompt });
-    const env = { ...inv.env, CRTR_ROOT_SESSION: session };
-    const window = openNodeWindow({
+    // REVIVE-HOME set once at birth: a managed child's revive target is the
+    // backstage, never a user session — this is what keeps a background revive
+    // off the user's screen (the focus taint cannot reach it).
+    updateNode(meta.node_id, { home_session: session });
+    const inv = buildPiArgv(meta, { prompt: opts.prompt, forkFrom });
+    const env = { ...inv.env, CRTR_ROOT_SESSION: childSession, [FRONT_DOOR_ENV]: '1' };
+    const command = piCommand(inv.argv);
+    // openNodeWindow now returns {window, pane}; pane is unused until the
+    // placement layer lands, so destructure the window and proceed unchanged.
+    const opened = openNodeWindow({
         session,
-        name: meta.name,
+        name: fullName(meta),
         cwd: opts.cwd,
         env,
-        command: piCommand(inv.argv),
+        command,
     });
-    const saved = updateNode(meta.node_id, { tmux_session: session, window });
+    const window = opened?.window ?? null;
+    // Two-stage failure model. Opening the window is instant and definitive, so a
+    // failure here is reported SYNCHRONOUSLY: crash the node (so it isn't a zombie
+    // 'active' the daemon can't reap — it has no window to watch) and throw so
+    // `crtr node new` exits non-zero with a clear message for the caller. The node
+    // is still 'active' from spawnNode, so transition('crash') is a legal from-LIVE
+    // move — the last scattered node-status write, now through the lifecycle machine.
+    //
+    // pi BOOTING inside the window, by contrast, is inherently slow (and slower
+    // under load), so we stay optimistic and return status='active' the instant
+    // the window exists. A vehicle that then dies before its first session_start
+    // is caught by the daemon — it surfaces the boot failure up the spine rather
+    // than letting the node die silently (see crtrd.ts surfaceBootFailure).
+    if (window === null) {
+        transition(meta.node_id, 'crash');
+        throw new Error(`failed to open a tmux window for ${meta.node_id} (${meta.name}) in session '${session}' — the node was not started.`);
+    }
+    setPresence(meta.node_id, { tmux_session: session, window });
+    const saved = getNode(meta.node_id);
+    // A root is spawned to be driven directly — bring it forefront so whoever
+    // asked for it picks up the conversation. A child stays a background window.
+    if (root) {
+        try {
+            focusWindow(session, window);
+        }
+        catch { /* best-effort */ }
+    }
     return { node: saved, window, session };
 }

package/dist/core/runtime/stop-guard.d.ts

@@ -6,7 +6,7 @@ export interface StopSignals {
 }
 export type StopAction = {
     action: 'allow';
-    reason: 'awaiting' | 'finished' | 'escalated' | 'attended';
+    reason: 'awaiting' | 'finished' | 'escalated' | 'dormant';
 } | {
     action: 'reprompt';
     reason: 'stalled';

package/dist/core/runtime/stop-guard.js

@@ -5,12 +5,17 @@
 // subscription to a node that's still live (active|idle) — something that can
 // actually wake it. (A passive sub won't wake you, so it doesn't count.)
 //
-//   • waiting        → stopping is correct; it's a dormant orchestrator awaiting
-//                      its workers. Let it sleep; a child's push wakes it.
+//   • resident       → an interactable / human-driven node is NEVER forced to
+//                      submit a final: stopping to go dormant is always
+//                      legitimate (woken by inbox/human). Keyed on the LIFECYCLE
+//                      value, not on parent/mode — what matters is residency.
+//   • waiting        → a TERMINAL node holding an active live subscription is a
+//                      dormant orchestrator awaiting its workers. Let it sleep;
+//                      a child's push wakes it (and idle-releases its window).
 //   • finished/asked → it pushed --final (done) or called `crtr ask` this turn.
 //                      Also fine.
-//   • otherwise      → it has nothing live to wait for and hasn't resolved.
-//                      Re-prompt it to finish or escalate. Stalls are impossible.
+//   • otherwise      → a TERMINAL node with nothing live to wait for and no
+//                      final pushed. Re-prompt it to finish or escalate.
 import { hasActiveLiveSubscription, getNode } from '../canvas/index.js';
 export const STALL_REPROMPT = "You've stopped but you're not waiting on anyone and haven't finished. " +
     'Run `crtr push final "<result>"` if the work is done, or `crtr human ask` if you are blocked or need the user.';
@@ -21,13 +26,18 @@ export function evaluateStop(nodeId, signals) {
         return { action: 'allow', reason: 'finished' };
     if (signals.askedHuman)
         return { action: 'allow', reason: 'escalated' };
-    // A user-opened root (no parent) is human-attended: the human is its wake
-    // source, so stopping to await input is always legitimate — never nag it.
+    // A RESIDENT node is interactable / human-driven and is never forced to submit
+    // a final: stopping to go dormant is always legitimate (the inbox or the human
+    // wakes it). Keyed on lifecycle, not parent — whether it has a parent doesn't
+    // matter, only whether it's resident. Roots are resident by birth default, so
+    // this still covers "don't nag the human's root" while generalizing it.
     const node = getNode(nodeId);
-    if (node !== null && (node.parent === null || node.parent === undefined)) {
-        return { action: 'allow', reason: 'attended' };
+    if (node !== null && node.lifecycle === 'resident') {
+        return { action: 'allow', reason: 'dormant' };
     }
+    // A terminal node holding something live to wake it is legitimately awaiting.
     if (hasActiveLiveSubscription(nodeId))
         return { action: 'allow', reason: 'awaiting' };
+    // A terminal node with nothing live and no final pushed has stalled.
     return { action: 'reprompt', reason: 'stalled', message: STALL_REPROMPT };
 }

package/dist/core/runtime/tmux-chrome.d.ts

@@ -0,0 +1 @@
+export { installMenuBinding, installNavBindings, sendKeysEnter } from './tmux.js';

package/dist/core/runtime/tmux-chrome.js

@@ -0,0 +1,4 @@
+// tmux-chrome.ts — chrome seam (§2.1): stateless keybind/input verbs.
+// The ONLY non-placement module allowed to import the tmux driver, per the
+// §5.1 lint. Re-exports the menu/nav/send-keys verbs callers (spawn, chord) need.
+export { installMenuBinding, installNavBindings, sendKeysEnter } from './tmux.js';