@crouton-kit/crouter 0.3.32 → 0.3.34

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

@@ -1,13 +1,20 @@
 import { type NodeMeta } from '../canvas/index.js';
 import type { WakeOrigin } from './bearings.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
- *  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. */
+import { headlessBrokerHost } from './host.js';
+/** Pick the `--session` source for a revive. resume=true resumes by the
+ *  absolute session-file path (immune to cwd; pi opens it directly) — but ONLY
+ *  when that file actually exists on disk. A node's `pi_session_file` can be
+ *  recorded in meta with nothing ever written there (e.g. its first-boot engine
+ *  died before session_start ever ran), and `headlessBrokerHost.launch`'s
+ *  preflight (host.ts) fatally rejects handing pi a `--session` for a missing
+ *  path OR a bare id — either would crash the revive and strand the node dead
+ *  with nothing to recover it. So when there is no real `.jsonl` to resume,
+ *  this selects NEITHER source: the caller then falls through to a fresh
+ *  (`--fresh`-equivalent) launch, which is always safe. resume=false (a
+ *  refresh-yield) also selects neither — the node re-reads its roadmap fresh.
+ *  Pure so the decision is unit-testable without tmux or a real filesystem
+ *  fixture beyond a temp file. */
 export declare function resumeArgs(meta: NodeMeta, resume: boolean): {
-    resumeSessionId?: string;
     resumeSessionPath?: string;
 };
 export interface ReviveResult {
@@ -17,8 +24,12 @@ export interface ReviveResult {
     /** 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>`). */
+    /** True when pi was instructed to resume its saved conversation by its
+     *  absolute session-file path (`--session <path>`). */
     resumed: boolean;
+    /** Launch handle for the detached broker, so callers can fail fast on its real
+     *  exit before the socket appears. */
+    launch?: ReturnType<typeof headlessBrokerHost.launch>;
 }
 /** Relaunch `nodeId`'s broker engine from its persisted recipe and update canvas
  *  meta. Opens no viewer (engine-only).

package/dist/core/runtime/revive.js

@@ -9,35 +9,47 @@
 // 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=true  → `pi --session <path>` — wakes the saved conversation by its
+//                  absolute session-file path (cwd-immune), but only when that
+//                  file actually exists on disk; otherwise falls through to a
+//                  fresh launch (see resumeArgs).
 //   resume=false → fresh pi invocation — the node re-reads its roadmap/context dir.
 //
 // reviveNode remains the ONLY sanctioned launcher of the node engine.
+import { existsSync } from 'node:fs';
 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 { headlessBrokerHost } from './host.js';
 import { isPidAlive } from '../canvas/pid.js';
+import { reconcileBootLiveness } from '../canvas/boot.js';
+import { clearFault } from './fault.js';
 import { clearInjectedDocs } from '../substrate/injected-store.js';
 // ---------------------------------------------------------------------------
 // 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. */
+/** Pick the `--session` source for a revive. resume=true resumes by the
+ *  absolute session-file path (immune to cwd; pi opens it directly) — but ONLY
+ *  when that file actually exists on disk. A node's `pi_session_file` can be
+ *  recorded in meta with nothing ever written there (e.g. its first-boot engine
+ *  died before session_start ever ran), and `headlessBrokerHost.launch`'s
+ *  preflight (host.ts) fatally rejects handing pi a `--session` for a missing
+ *  path OR a bare id — either would crash the revive and strand the node dead
+ *  with nothing to recover it. So when there is no real `.jsonl` to resume,
+ *  this selects NEITHER source: the caller then falls through to a fresh
+ *  (`--fresh`-equivalent) launch, which is always safe. resume=false (a
+ *  refresh-yield) also selects neither — the node re-reads its roadmap fresh.
+ *  Pure so the decision is unit-testable without tmux or a real filesystem
+ *  fixture beyond a temp file. */
 export function resumeArgs(meta, resume) {
     if (!resume)
         return {};
-    return {
-        resumeSessionId: meta.pi_session_id ?? undefined,
-        resumeSessionPath: meta.pi_session_file ?? undefined,
-    };
+    const path = meta.pi_session_file;
+    if (path != null && path !== '' && existsSync(path)) {
+        return { resumeSessionPath: path };
+    }
+    return {};
 }
 // ---------------------------------------------------------------------------
 // reviveNode
@@ -61,6 +73,15 @@ export function reviveNode(nodeId, opts) {
         updateNode(nodeId, { host_kind: 'broker' });
         meta.host_kind = 'broker';
     }
+    // A durable-row / ephemeral-pid boot change (a sandbox/VM destroy+recreate,
+    // or a host reboot) invalidates every `pi_pid` recorded before it — the OS
+    // process table reset, so a small stale pid can coincidentally collide with
+    // an unrelated process on the new boot and fool the double-launch guard
+    // right below into believing a dead broker is still alive. Idempotent and
+    // cheap once reconciled (a single small file read) except the one time it
+    // actually matters, so it's safe to call on every revive regardless of
+    // entry point (daemon tick, or a direct/manual `canvas revive`).
+    reconcileBootLiveness();
     // 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.
@@ -72,15 +93,31 @@ export function reviveNode(nodeId, opts) {
             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.
+    // Every (re)launch is a new cycle — bump the counter so CRTR_CYCLES and the
+    // footer stay in sync. Mutate the in-memory meta too so buildPiArgv below
+    // launches 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.
+    // Decide whether to wake the saved pi conversation or start fresh. resumeArgs
+    // resumes ONLY by the absolute session-file path (cwd-immune) and ONLY when
+    // that .jsonl actually exists; there is no bare-id fallback (the broker
+    // preflight rejects a bare `--session`). Anything else is a fresh launch.
     const resume = resumeArgs(meta, opts.resume);
-    const resuming = resume.resumeSessionPath !== undefined || resume.resumeSessionId !== undefined;
+    const resuming = resume.resumeSessionPath !== undefined;
+    // A fresh (non-resuming) launch starts a NEW pi session — the old session
+    // identity is dead. Clear it from meta NOW, before launch, so the recorded
+    // state matches what we're about to do. This is load-bearing for boot-failure
+    // classification: if this fresh broker dies BEFORE session_start (recording
+    // no new pid and no new session), the daemon's pid-null branch keys on
+    // pi_session_id — a leftover stale id would be misread as a "stranded
+    // relaunch" and retried forever instead of surfaced via transition('crash') +
+    // surfaceBootFailure. Clearing it makes the failure show as pid=NULL +
+    // session=NULL → boot failure, the correct terminal outcome.
+    if (!resuming && (meta.pi_session_id != null || meta.pi_session_file != null)) {
+        updateNode(nodeId, { pi_session_id: null, pi_session_file: null });
+        meta.pi_session_id = null;
+        meta.pi_session_file = null;
+    }
     // A fresh revive (no resume) gets a kickoff prompt so it re-reads its roadmap
     // and continues; resuming a saved conversation needs none. drainBearings is the
     // one-shot consuming step (yield note + feed cursor + persona ack); the builder
@@ -106,19 +143,36 @@ export function reviveNode(nodeId, opts) {
     // opens NO viewer — engine-only; existing viewers reconnect, and a viewer-less
     // node is brought on screen by the next `focus`.
     transition(nodeId, 'revive');
+    // Clear any active fault the instant this node is (re)launched — don't wait
+    // for the fresh agent_start. A revive (auto or on-demand) is the recovery
+    // this marker advertised.
+    clearFault(nodeId);
     // 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.
     cancelDeadlinesFor(nodeId);
-    headlessBrokerHost.launch(nodeId, inv, {
-        cwd: meta.cwd,
-        name: fullName(meta),
-        resuming,
-    });
+    let launched;
+    try {
+        launched = headlessBrokerHost.launch(nodeId, inv, {
+            cwd: meta.cwd,
+            name: fullName(meta),
+            resuming,
+        });
+    }
+    catch (error) {
+        try {
+            transition(nodeId, 'crash');
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+        clearPid(nodeId);
+        throw new Error(`[broker] refusing to revive ${nodeId}: ${error.message}`);
+    }
     // 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: null, session: meta.tmux_session ?? null, resumed: resuming };
+    return { window: null, session: meta.tmux_session ?? null, resumed: resuming, launch: launched };
 }

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

@@ -4,7 +4,7 @@ export declare function readRoadmap(nodeId: string): string | null;
 /** 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
+ *  roadmap memory doc). `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 declare function seedRoadmap(nodeId: string, opts?: {

package/dist/core/runtime/roadmap.js

@@ -23,7 +23,7 @@ export function readRoadmap(nodeId) {
 /** 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
+ *  roadmap memory doc). `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 = {}) {

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

@@ -7,11 +7,11 @@ export interface BootRootOpts {
     /** Optional starter prompt (bare `crtr` requires none). */
     prompt?: string;
 }
-/** Create the front-door root: launch its broker engine, then exec `crtr attach`
+/** Create the front-door root: launch its broker engine, then exec `crtr surface 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 declare function bootRoot(opts: BootRootOpts): Promise<NodeMeta>;
 export interface SpawnChildOpts {
     kind: string;
     mode?: Mode;
@@ -70,4 +70,4 @@ export declare function resolveSpawner(parent: string | undefined, ctxNodeId: st
  *  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;
+export declare function spawnChild(opts: SpawnChildOpts): Promise<SpawnChildResult>;

package/dist/core/runtime/spawn.js

@@ -3,7 +3,7 @@
 // (resolve), launch (pi argv), and tmux (placement).
 //
 //   bootRoot   — the user-opened front door (bare `crtr`). Resident; launches the
-//                root's broker engine, then execs `crtr attach` inline so THIS
+//                root's broker engine, then execs `crtr surface attach` inline so THIS
 //                terminal becomes the broker's controller-viewer.
 //   spawnChild — a node spawned by a live node (`crtr node new`). A managed,
 //                terminal background worker by default; with `root`, an
@@ -24,12 +24,30 @@ import { registerViewerFocus, openViewerWindow, waitForBrokerViewSocket, viewerS
 import { transition } from './lifecycle.js';
 import { headlessBrokerHost } from './host.js';
 import { ensureDaemon } from '../../daemon/manage.js';
-/** Create the front-door root: launch its broker engine, then exec `crtr attach`
+// ---------------------------------------------------------------------------
+// Shared broker-launch wrapper — catch launch/preflight failures at the call
+// site, mark the node crashed, then rethrow a clear error.
+// ---------------------------------------------------------------------------
+function launchBrokerOrCrash(nodeId, inv, opts) {
+    try {
+        return headlessBrokerHost.launch(nodeId, inv, opts);
+    }
+    catch (error) {
+        try {
+            transition(nodeId, 'crash');
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+        throw new Error(`[broker] refusing to launch ${nodeId}: ${error.message}`);
+    }
+}
+/** Create the front-door root: launch its broker engine, then exec `crtr surface 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 function bootRoot(opts) {
-    // crtr is tmux-only: the front door execs `crtr attach` inline in THIS pane to
+export async function bootRoot(opts) {
+    // crtr is tmux-only: the front door execs `crtr surface attach` inline in THIS pane to
     // become the root's controller-viewer, so there must be a tmux pane to anchor
     // on. Outside tmux there is no viewer surface — throw with a friendly message
     // rather than boot a root nobody can see.
@@ -83,7 +101,7 @@ export function bootRoot(opts) {
     // pane lives in the focuses table (below).
     const here = currentTmux();
     // The FOREGROUND front-door terminal is the root's one viewer: record its pane
-    // as the node's viewer focus row so focus/nav can find it. The `crtr attach`
+    // as the node's viewer focus row so focus/nav can find it. The `crtr surface attach`
     // exec below makes the terminal a controller-viewer of the broker; detaching
     // leaves the resident broker running.
     if (here !== null) {
@@ -95,10 +113,10 @@ export function bootRoot(opts) {
     const inv = buildPiArgv(meta, { prompt: opts.prompt });
     // Broker is the only host: the root runs as a detached broker engine (so its
     // first refresh/revive doesn't strand this terminal — the daemon revives the
-    // broker and the viewer reconnects), and THIS terminal execs `crtr attach`
+    // broker and the viewer reconnects), and THIS terminal execs `crtr surface attach`
     // inline to become its controller-viewer. The host sets CRTR_FRONT_DOOR.
     inv.env = { ...inv.env, CRTR_SUBTREE: rootOfSpine(meta.node_id) };
-    const placed = headlessBrokerHost.launch(meta.node_id, inv, {
+    const placed = launchBrokerOrCrash(meta.node_id, inv, {
         cwd: opts.cwd,
         name: fullName(meta),
         resuming: false,
@@ -112,11 +130,17 @@ export function bootRoot(opts) {
     // The terminal has nothing to attach to until view.sock accepts. The root is
     // useless without its engine, so a socket timeout IS fatal here (unlike a
     // background child's optional viewer, which is skipped on timeout).
-    if (!waitForBrokerViewSocket(meta.node_id)) {
+    if (!(await waitForBrokerViewSocket(meta.node_id, placed.exited))) {
+        try {
+            transition(meta.node_id, 'crash');
+        }
+        catch {
+            /* best-effort cleanup */
+        }
         throw new Error(`the front-door root broker ${meta.node_id} never bound its view socket — cannot attach.`);
     }
     const attachEnv = { ...process.env, ...viewerSplitEnv() };
-    const r = spawnSync('crtr', ['attach', 'to', meta.node_id], { stdio: 'inherit', env: attachEnv });
+    const r = spawnSync('crtr', ['surface', 'attach', 'to', meta.node_id], { stdio: 'inherit', env: attachEnv });
     process.exit(r.status ?? 0);
 }
 /** pi's sessions root, VENDORED from pi `config.getSessionsDir()` (= `<agentDir>/
@@ -210,7 +234,7 @@ export function resolveSpawner(parent, ctxNodeId, root) {
  *  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) {
+export async function spawnChild(opts) {
     try {
         ensureDaemon();
     }
@@ -290,9 +314,9 @@ export function spawnChild(opts) {
     inv.env = { ...inv.env, CRTR_SUBTREE: rootOfSpine(meta.node_id) };
     // Broker is the only host: launch the detached broker ENGINE. A managed child
     // gets NO viewer — spawning it returns once the engine is launched and a human
-    // opens a viewer on demand via `crtr node focus` / `crtr attach`. A --root gets
+    // opens a viewer on demand via `crtr node focus` / surface attach. A --root gets
     // one foreground viewer below.
-    const placed = headlessBrokerHost.launch(meta.node_id, inv, {
+    const placed = launchBrokerOrCrash(meta.node_id, inv, {
         cwd: meta.cwd,
         name: fullName(meta),
         resuming: false,
@@ -313,7 +337,7 @@ export function spawnChild(opts) {
     // returns null) or the socket never binds — `focus` opens a viewer later.
     let window = null;
     let session = null;
-    if (root && here !== null && waitForBrokerViewSocket(meta.node_id)) {
+    if (root && here !== null && await waitForBrokerViewSocket(meta.node_id, placed.exited)) {
         const viewer = openViewerWindow(meta.node_id, here.session, { name: fullName(meta), cwd: opts.cwd });
         if (viewer !== null && viewer.pane !== null && viewer.pane !== '') {
             session = here.session;

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

@@ -16,7 +16,7 @@
 //                      Also fine.
 //   • otherwise      → a TERMINAL node with nothing live to wait for and no
 //                      final pushed. Re-prompt it to finish or escalate.
-import { hasActiveLiveSubscription, hasPendingSelfWake, getNode } from '../canvas/index.js';
+import { hasActiveLiveSubscription, hasPendingSelfTrigger, 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.';
 /** Decide what to do when a node stops. Pure given the canvas + this turn's
@@ -26,19 +26,24 @@ export function evaluateStop(nodeId, signals) {
         return { action: 'allow', reason: 'finished' };
     if (signals.askedHuman)
         return { action: 'allow', reason: 'escalated' };
+    // Already-terminal stored state wins before any stall logic: a node that is
+    // done/dead/canceled is not waiting to be re-prompted.
+    const node = getNode(nodeId);
+    if (node !== null && (node.status === 'done' || node.status === 'dead' || node.status === 'canceled')) {
+        return { action: 'allow', reason: 'finished' };
+    }
     // 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.lifecycle === 'resident') {
         return { action: 'allow', reason: 'dormant' };
     }
-    // A terminal node with a pending self-scheduled wakeup is legitimately
-    // waiting on the clock: the daemon's wakeup sweep resumes it when the wake
-    // fires, so it should idle-release rather than busy-wait holding pi/window.
-    if (hasPendingSelfWake(nodeId))
+    // A terminal node with a pending self-scheduled trigger is legitimately
+    // waiting on the clock: the daemon's trigger sweep resumes it when the
+    // trigger fires, so it should idle-release rather than busy-wait holding pi/window.
+    if (hasPendingSelfTrigger(nodeId))
         return { action: 'allow', reason: 'scheduled' };
     // A terminal node holding something live to wake it is legitimately awaiting.
     if (hasActiveLiveSubscription(nodeId))

package/dist/core/runtime/surface-bg.js

@@ -17,7 +17,7 @@
 // door (which never otherwise loads pi). We only READ the process-global symbol;
 // any process that needs styling (the attach viewer, a node's broker) has already
 // called `initTheme()` and populated it. Where the symbol is absent (the front
-// door, before it execs into the themed `crtr attach`), the tmux helpers return
+// door, before it execs into the themed `crtr surface attach`), the tmux helpers return
 // no style args and the chrome stays at its default — the viewer re-themes it.
 const THEME_SYMBOL = Symbol.for('@earendil-works/pi-coding-agent:theme');
 /** The live pi Theme if a process has already run `initTheme()`, else undefined.

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

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

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

@@ -1,4 +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, installViewNavBindings, sendKeysEnter } from './tmux.js';
+export { installMenuBinding, installNavBindings, installViewNavBindings, sendKeysEnter, displayMessage, paneCurrentPath } from './tmux.js';

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

@@ -72,6 +72,18 @@ export declare function closeWindow(window: string): boolean;
  *  root relaunch to re-title the viewer window when its pane is re-pointed at
  *  the freshly-minted node. Best-effort; false if tmux fails. */
 export declare function renameWindow(window: string, name: string): boolean;
+/** Break a single PANE out into a BRAND-NEW window of its own (`tmux break-pane
+ *  -d`). `-d` keeps the new window in the background (does not switch the client
+ *  to it); `-s <pane>` names the source pane — the §2.2 HARD DRIVER INVARIANT, so
+ *  the break never falls back to tmux's global current pane. The pane keeps its
+ *  durable `%id` across the move (only its window changes), so callers can keep
+ *  using the same pane handle. Returns the new `{window, pane}` location, or null
+ *  if tmux fails. Used by `canvas tmux-spread` to lift the caller's viewer into a
+ *  fresh window before tiling sibling viewers beside it. */
+export declare function breakPane(pane: string): {
+    window: string;
+    pane: string;
+} | null;
 /** 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
@@ -108,7 +120,7 @@ export declare function paneLocation(pane: string): {
 export declare function paneExists(pane: string): boolean;
 /** Does this pane exist AND have its command still RUNNING (`#{pane_dead}` = 0)?
  *  Distinguishes a pane genuinely hosting a live process from a remain-on-exit
- *  corpse frozen after exit (`pane_dead` = 1). Node viewer panes run `crtr attach`
+ *  corpse frozen after exit (`pane_dead` = 1). Node viewer panes run `crtr surface attach`
  *  as the pane command, so pane-running ⟹ a live viewer occupies it. */
 export declare function paneRunning(pane: string): boolean;
 /** Every live pane id on the server (`list-panes -a`), as a Set for membership
@@ -122,6 +134,11 @@ export declare function listLivePanes(): Set<string> | null;
  *  '#{pane_current_path}'`). Used to preserve a view monitor's cwd across a
  *  view-cycle respawn so project-scoped views still resolve. Null if tmux fails. */
 export declare function paneCurrentPath(pane: string): string | null;
+/** Flash a transient status-line toast on the client showing `pane` (or the
+ *  current client when `pane` is omitted). `ms` sets the display duration. Used
+ *  by `crtr canvas issue new` to confirm a capture from inside its popup.
+ *  Best-effort; never throws. */
+export declare function displayMessage(message: string, pane?: string, ms?: number): boolean;
 /** Set a PANE-scoped tmux option (`tmux set-option -p -t <pane> <name> <value>`).
  *  Used to tag a pane with the view id it currently hosts (`@crtr_view`) so the
  *  view-nav cycle can read it back and switch to the next/prev view in place.
@@ -169,6 +186,17 @@ export declare function windowAlive(session: string | null | undefined, window:
 /** Activate a window within its session (same-session navigation). Equivalent
  *  to `tmux select-window -t <session>:<window>`. Best-effort; never throws. */
 export declare function selectWindow(session: string, window: string): boolean;
+/** Apply a named tmux layout to a window (`tmux select-layout -t <window>
+ *  <layout>`). `canvas tmux-spread` calls it with `tiled` to evenly grid every
+ *  viewer pane in the spread window (and between splits, to redistribute space so
+ *  the next split has room). Best-effort; false if tmux fails. */
+export declare function selectLayout(window: string, layout: string): boolean;
+/** Make a pane the ACTIVE pane in its window (`tmux select-pane -t <pane>`). A
+ *  `split-window -d` keeps the CALLER active, so a freshly-opened viewer pane is
+ *  not focused until this runs — `focus` calls it so picking a node (e.g. from the
+ *  alt+g graph) lands the keyboard on the new viewer. Best-effort; false if tmux
+ *  fails. */
+export declare function selectPane(pane: string): boolean;
 /** Switch the tmux client to a different session (cross-session focus). Runs
  *  `tmux switch-client -t <session>`. Best-effort; never throws. The caller is
  *  responsible for following up with selectWindow to land on the right window. */
@@ -177,12 +205,7 @@ export declare function switchClient(session: string): boolean;
  *  (`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/resume/demote/detach/close) are static; the canvas-nav
- *  chords (default g→graph, m→manager + 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. */
+/** Bind Alt+C to the crouter action menu. Best-effort; false if tmux fails. */
 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