@crouton-kit/crouter 0.3.13 → 0.3.15

package/dist/core/runtime/roadmap.js

@@ -20,32 +20,25 @@ export function readRoadmap(nodeId) {
     const p = roadmapPath(nodeId);
     return existsSync(p) ? readFileSync(p, 'utf8') : null;
 }
-/** Seed a fresh roadmap SCAFFOLD. No goal is required — promotion lays this
- *  down so the file exists for a refresh, and the owner authors the goal +
- *  body as its next act (guided by its kind's roadmap skill). `goal`/
- *  `exitCriteria` are optional overrides. Idempotent only if you intend it —
+/** Seed a fresh, EXTREMELY BAREBONES roadmap scaffold — just the section
+ *  skeleton with one-line prompts. Promotion lays this down so the file exists
+ *  for a refresh; the owner fleshes it out as its next act (guided by its
+ *  kind's roadmap skill). `goal`/`exitCriteria` pre-fill those sections when
+ *  known (e.g. from the node's goal doc). Idempotent only if you intend it —
  *  call sites guard on hasRoadmap to avoid clobbering an evolved map. */
 export function seedRoadmap(nodeId, opts = {}) {
     const dir = contextDir(nodeId);
     mkdirSync(dir, { recursive: true });
     const body = `# Roadmap
 
-<!-- frozen core: set once, rarely changes -->
 ## Goal
-${opts.goal?.trim() ?? '- (state the high-level goal you now own — write this as your first act)'}
+${opts.goal?.trim() ?? '(the goal you now own)'}
 
 ## Exit criteria
-${opts.exitCriteria?.trim() ?? '- (define what "done" looks like)'}
+${opts.exitCriteria?.trim() ?? '(what "done" looks like)'}
 
-<!-- evolving body: keep this current as you learn scope + intent -->
-## Scope assumptions / non-goals
-- (record what's out of scope and what's settled — e.g. "reuse existing auth", "security isn't a concern here" — so children inherit the framing)
-
-## Strategy / phases
-- (your high-level shape of how you reach the goal; the ordered phases from here to done, the current one carrying a one-line status. Each phase can become a child whose own roadmap is that phase)
-
-## Active context
-- (the context/ files currently relevant to the work, by path; none yet)
+## Phases
+(ordered phases from here to done; the current one carries a one-line status)
 `;
     writeFileSync(roadmapPath(nodeId), body);
     return body;

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 } from './nodes.js';
 import { buildLaunchSpec, buildPiArgv } from './launch.js';
 import { writeGoal } from './kickoff.js';
-import { ensureSession, openNodeWindow, piCommand, currentTmux, inTmux, nodeSession, installMenuBinding, } 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 { ensureSession, openNodeWindow, piCommand, currentTmux, inTmux, nodeSession, focusWindow, installMenuBinding, installNavBindings, } from './tmux.js';
+import { setPresence, updateNode, getNode, fullName } from '../canvas/index.js';
+import { registerRootFocus } 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,
     });
@@ -43,81 +57,192 @@ export function bootRoot(opts) {
     // Every node window — root or child — lives in the one shared session.
     const session = nodeSession();
     ensureSession(session, opts.cwd);
-    // Make the Alt+C action menu live on this server (idempotent, in-tmux only).
+    // Make the Alt+C action menu + Alt+] / Alt+[ nav keys live on this server
+    // (idempotent, in-tmux only).
     if (inTmux()) {
         try {
             installMenuBinding();
         }
         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);
+        try {
+            installNavBindings();
+        }
+        catch { /* best-effort */ }
     }
     // 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.d.ts

@@ -28,7 +28,8 @@ export interface OpenWindowOpts {
 }
 /** Open a background window for a node and run `command` in it. `-d` keeps it
  *  detached so it doesn't steal focus or become the current window. Returns the
- *  new window id.
+ *  new window id AND the pane id it created (the durable `%pane_id`, LOCATION's
+ *  anchor) — callers that only need the window destructure `.window`.
  *
  *  Target is `${session}:` (trailing colon = the session, no window index) plus
  *  `-a` (insert after the current window) so tmux allocates the next free index.
@@ -37,24 +38,41 @@ export interface OpenWindowOpts {
  *  "create window failed: index N in use" whenever the active window is not the
  *  last one (common when base-index is 0 but the live window sits at index 1).
  *  `-a` also keeps node windows off index 0, which is reserved for the optional
- *  dashboard. */
-export declare function openNodeWindow(opts: OpenWindowOpts): string | null;
-/** Open a background window running a plain login shell (no pi) and return its
- *  window + pane ids. Used by demote: the agent's pi is swapped OUT into this
- *  window's slot and the shell is swapped INTO the caller's pane. `-a` keeps it
- *  off index 0 (reserved for a dashboard), `-d` keeps it from stealing focus. */
-export declare function openShellWindow(opts: {
-    session: string;
-    name: string;
-    cwd: string;
-}): {
+ *  dashboard. The explicit `-t ${session}:` target is the §2.2 HARD DRIVER
+ *  INVARIANT — never let new-window fall back to tmux's global current session. */
+export declare function openNodeWindow(opts: OpenWindowOpts): {
     window: string;
     pane: string;
 } | null;
+export interface SplitWindowOpts {
+    cwd: string;
+    env: Record<string, string>;
+    /** The full command to run in the new pane (already a shell string). */
+    command: string;
+    /** Stack the new pane below instead of beside (default: beside, `-h`). */
+    vertical?: boolean;
+}
+/** Split `targetPane`'s window, opening a NEW pane beside it running `command`,
+ *  and return the new pane id (the durable `%id`). The ONLY new-pane-beside verb
+ *  (Q3: a focus opened side-by-side). `-d` keeps the caller's pane active; `-h`
+ *  makes the split side-by-side (left/right), the default for a focus viewport.
+ *
+ *  §2.2 HARD DRIVER INVARIANT: `targetPane` is REQUIRED — a bare `split-window`
+ *  would split tmux's global current pane, which can leak a pane into an
+ *  unrelated user session (the exact bug this design kills). The explicit
+ *  `-t <targetPane>` makes the destination structurally un-leakable. Returns
+ *  null if tmux fails. */
+export declare function splitWindow(targetPane: string, opts: SplitWindowOpts): string | null;
 /** Bring a node's window forefront. Switches client across roots when needed. */
 export declare function focusWindow(session: string, window: string): boolean;
 /** Close a node's window (drop it from the UI). */
 export declare function closeWindow(window: string): boolean;
+/** Close a single PANE. Its window closes automatically once this was the last
+ *  pane, but sibling panes survive — so co-located nodes (several agents sharing
+ *  one window via swap-pane focus) are torn down one at a time instead of all
+ *  at once by a window kill. Pane ids are the stable vehicle handle; windows
+ *  shift under swap-pane focus, so pane-granular teardown is the correct unit. */
+export declare function closePane(pane: string): boolean;
 /** The active pane id of a window. Node windows are single-pane, so this is the
  *  node's pane. Returns null if the window is gone or tmux fails. */
 export declare function paneOfWindow(session: string, window: string): string | null;
@@ -63,6 +81,35 @@ export declare function paneOfWindow(session: string, window: string): string |
  *  are not, so the node→window mapping must be re-derived from the pane. Returns
  *  null if the pane is gone or tmux fails. */
 export declare function windowOfPane(pane: string): string | null;
+/** The session + window a pane currently lives in (`display-message -p -t %id`).
+ *  The §2.4 reconciliation read-back: resolve a node's/focus's CURRENT
+ *  window/session from its durable pane id before any act, so crtr follows a
+ *  manual `move-pane`/`join-pane`/`break-pane` instead of fighting it. Null if
+ *  the pane is gone or tmux fails. */
+export declare function paneLocation(pane: string): {
+    session: string;
+    window: string;
+} | null;
+/** Does this pane id still exist? A `display-message` probe on the `%id` — the
+ *  v3 PRIMARY liveness probe (§1.2/§2.2), replacing window-existence so a user
+ *  moving a pane to another window/session never reads as "gone". True iff tmux
+ *  knows the pane.
+ *
+ *  NOTE: `display-message -p -t <gone-pane>` EXITS 0 with EMPTY output (it does
+ *  not error on an unresolvable pane target) — so an `.ok` check alone would
+ *  report a dead pane as alive, defeating the whole point of pane-existence
+ *  liveness. We therefore require the echoed `#{pane_id}` to equal the requested
+ *  pane: a live pane echoes its own id, a gone/bogus one yields empty. */
+export declare function paneExists(pane: string): boolean;
+/** Relocate a pane into another session as its own window WITHOUT killing the
+ *  process in it — `break-pane -d` moves the pane out of its current window (the
+ *  pi keeps generating) into a fresh window in `session`; `-d` leaves the caller's
+ *  client where it is rather than following the pane to the background, and `-a`
+ *  allocates the next free window index (same dodge as openNodeWindow). The
+ *  "detach to background" driver behind `node lifecycle --detach`. Best-effort;
+ *  false if tmux refuses (e.g. the pane is gone). The caller reconciles presence
+ *  so the canvas follows the move. */
+export declare function breakPaneToSession(pane: string, session: string): boolean;
 /** Swap `targetPane` into `callerPane`'s layout slot, IN PLACE. `-d` keeps the
  *  caller's window active, so the target's pane appears where the caller is
  *  rather than navigating the client off to the target's window. The caller's
@@ -77,14 +124,20 @@ export interface RespawnPaneOpts {
     /** The full command to run in the pane (already a shell string). */
     command: string;
 }
-/** Re-exec a command in an EXISTING pane, in place. `-k` kills the pane's
- *  current process (e.g. a yielding pi) and starts `command` in the same pane
- *  — the window/pane survives, so an interactive session is never dropped to a
- *  shell and no window churns. Used by refresh-yield.
- *
- *  Spawned DETACHED (own process group, unref'd) so the request reaches the
- *  tmux server even though killing the pane tears down the caller's own pi.
- *  Returns true once the request was dispatched. */
+/** Re-exec a command in an EXISTING pane, in place — DETACHED. Spawned in its own
+ *  process group (unref'd) so the request reaches the tmux server even though
+ *  `-k` tears down the caller's own pi mid-flight. Used when a node respawns ITS
+ *  OWN pane (refresh-yield): the dispatch can't be awaited because it kills the
+ *  awaiter. Returns true once the request was dispatched. */
+export declare function respawnPaneDetached(opts: RespawnPaneOpts): boolean;
+/** Re-exec a command in an EXISTING pane, in place — SYNCHRONOUS. Runs the
+ *  `respawn-pane` to completion and reports the real exit status. Used when the
+ *  caller is NOT the pane being respawned (e.g. the daemon resuming a frozen
+ *  focus pane), so it can confirm the respawn landed. Returns true on success. */
+export declare function respawnPaneSync(opts: RespawnPaneOpts): boolean;
+/** @deprecated Use respawnPaneDetached. Retained so existing refresh-yield
+ *  callers stay green while the placement layer migrates onto the explicit
+ *  sync/detached split. */
 export declare function respawnPane(opts: RespawnPaneOpts): boolean;
 /** Turn a pi argv array into a single shell command string. */
 export declare function piCommand(argv: string[], binary?: string): string;
@@ -103,5 +156,37 @@ export declare function selectWindow(session: string, window: string): boolean;
  *  `tmux switch-client -t <session>`. Best-effort; never throws. The caller is
  *  responsible for following up with selectWindow to land on the right window. */
 export declare function switchClient(session: string): boolean;
-/** Bind Alt+C to the crouter action menu. Best-effort; false if tmux fails. */
+/** Move a source pane into a destination window (`tmux join-pane`). The source
+ *  pane's running process (e.g. a child's live pi) is preserved; its now-empty
+ *  source window auto-closes. Best-effort; false if tmux fails. */
+export declare function joinPane(srcPane: string, dstWindow: string): boolean;
+/** Apply a named tmux layout to a window (`tmux select-layout`). Use
+ *  `main-vertical` for one wide pane on the left + the rest stacked right.
+ *  Best-effort; never throws. */
+export declare function selectLayout(window: string, layout: string): boolean;
+/** Set a tmux window option (`tmux set-window-option`). Used to size the main
+ *  pane (`main-pane-width`) before a main-vertical layout. Best-effort. */
+export declare function setWindowOption(window: string, name: string, value: string): boolean;
+/** Toggle `remain-on-exit` on a window (§1.5 F3). `on` keeps a focus pane on
+ *  screen after its pi exits — the viewport survives (F1), the final transcript
+ *  is preserved, and `respawn-pane -k` can resurrect the node into the SAME pane
+ *  id. NOTE (§1.5/§2.5, spike-confirmed): a dead/frozen pane is reaped only by
+ *  `kill-pane`/`respawn-pane`, NEVER by toggling this off — the toggle does not
+ *  reap an already-dead pane. Best-effort; never throws. */
+export declare function setRemainOnExit(window: string, on: boolean): boolean;
+/** Type a literal (e.g. a `/graph` slash command) into a pane and press Enter
+ *  (`tmux send-keys -t <pane> '<text>' Enter`). Requires the pane's editor be
+ *  empty, same limitation as the menu's `/promote` item. Best-effort. */
+export declare function sendKeysEnter(pane: string, text: string): boolean;
+/** Bind Alt+C to the crouter action menu. Best-effort; false if tmux fails.
+ *  The built-in items (promote/demote/detach/close/browse) are static; the canvas-nav
+ *  chords (graph/manager/expand/report-N + any custom prefixBind) are appended
+ *  from `canvasNav.prefixBinds`, each routed through `crtr canvas chord` (or, for
+ *  the `__graph__` sentinel, a `send-keys '/graph'`) so the menu stays static
+ *  while behaviour is config-driven. */
 export declare function installMenuBinding(): boolean;
+/** Bind Alt+] (forward) and Alt+[ (back) to the DFS canvas walk. Best-effort;
+ *  false if either bind fails. NOTE: Alt+[ is only delivered cleanly when the
+ *  terminal/tmux disambiguate it from a raw CSI introducer (`extended-keys on`).
+ */
+export declare function installNavBindings(): boolean;