@crouton-kit/crouter 0.3.27 → 0.3.29

package/dist/core/runtime/nodes.js

@@ -38,71 +38,6 @@ export function rootOfSpine(nodeId) {
         cur = row.parent;
     }
 }
-/** The single, shared tmux session that ALL canvas node windows live in.
- *  Overridable with CRTR_NODE_SESSION (default `crtr`). Every root and every
- *  child opens a window here rather than cluttering the user's own working
- *  session — switch to it to browse the whole live graph, ignore it otherwise.
- *  Pure policy (env only, no tmux call), so it lives in the node layer, not the
- *  driver; the tmux driver imports it from here for installMenuBinding's use. */
-export function nodeSession() {
-    const v = process.env['CRTR_NODE_SESSION'];
-    return v !== undefined && v !== '' ? v : 'crtr';
-}
-// ---------------------------------------------------------------------------
-// REVIVE-HOME (home_session) — the durable session a node is (re)opened into
-// ---------------------------------------------------------------------------
-/** Resolve the tmux session a freshly-born node's window/pane opens into — and
- *  thus its durable REVIVE-HOME (`home_session`). Pure so the birth decision is
- *  unit-testable without a live tmux:
- *    - managed background child  (`adoptCaller=false`) → the shared backstage:
- *      the inherited `CRTR_ROOT_SESSION`, else `nodeSession()` (`crtr`).
- *    - independent `--root` / inline front door (`adoptCaller=true`) → the
- *      caller's CURRENT session when inside tmux (`here`), else the backstage.
- *  This is exactly the session each birth site already places the node into;
- *  centralizing it keeps `home_session` and the actual placement in lockstep. */
-export function resolveBirthSession(opts) {
-    const backstage = opts.rootSession !== undefined && opts.rootSession !== null && opts.rootSession !== ''
-        ? opts.rootSession
-        : nodeSession();
-    if (opts.adoptCaller && opts.here !== null)
-        return opts.here.session;
-    return backstage;
-}
-/** A node's durable REVIVE-HOME, with the legacy back-compat default. Nodes born
- *  before `home_session` existed have no such field in meta — they fall back to
- *  their last live LOCATION (`tmux_session`), then to the shared backstage
- *  (`nodeSession()`). The defaulted read for the placement layer; a present
- *  `home_session` is always returned verbatim. */
-export function homeSessionOf(nodeId) {
-    const meta = getNode(nodeId);
-    if (meta === null)
-        return nodeSession();
-    return meta.home_session ?? meta.tmux_session ?? nodeSession();
-}
-/** The session a node's CHILDREN spawn into — the value its pi process exports
- *  as CRTR_ROOT_SESSION (the subtree's backstage). NOT the same as where the
- *  node's OWN pane lives.
- *
- *  For a managed CHILD this is its `home_session`: a child's home_session is
- *  ALWAYS the backstage it was born into (focus may move its live pane into a
- *  user session, but home_session stays the taint-immune backstage), so its
- *  descendants correctly inherit that backstage.
- *
- *  For a ROOT (`parent === null`) `home_session` may be a USER session it
- *  ADOPTED — the inline front door keeps the root's own pane where the user is
- *  working (`home_session = cli`). Sourcing children's CRTR_ROOT_SESSION from
- *  that would exile the root's entire subtree into the user's session. A root's
- *  children must instead flow to the shared backstage `nodeSession()`, NEVER the
- *  user's session — mirroring spawnRoot's birth-time split (root pane → user
- *  session; children → nodeSession() via CRTR_ROOT_SESSION). The revive paths
- *  MUST honor the same split, or a refreshed front-door root re-points its whole
- *  subtree into the user's session on every yield (the bug this fixes). */
-export function childBackstageOf(nodeId) {
-    const meta = getNode(nodeId);
-    if (meta !== null && meta.parent === null)
-        return nodeSession();
-    return homeSessionOf(nodeId);
-}
 /** Read the current node's identity from the environment. A spawned pi process
  *  runs with CRTR_NODE_ID set; its own `crtr` invocations spawn children under
  *  it by reading CRTR_NODE_ID as the parent. */
@@ -131,14 +66,9 @@ export function nodeEnv(meta) {
     const home = process.env['CRTR_HOME'];
     if (home !== undefined && home !== '')
         env['CRTR_HOME'] = home;
-    // Propagate the root's tmux session so every descendant spawns its windows
-    // into the same root session.
-    const rootSession = process.env['CRTR_ROOT_SESSION'];
-    if (rootSession !== undefined && rootSession !== '')
-        env['CRTR_ROOT_SESSION'] = rootSession;
-    // Propagate the subtree-root node id (additive in Phase 3; tmux still keys on
-    // CRTR_ROOT_SESSION). The broker uses it to group a subtree; each launch site
-    // also emits the authoritative rootOfSpine(nodeId) over this passthrough.
+    // Propagate the subtree-root node id. The broker uses it to group a subtree;
+    // each launch site also emits the authoritative rootOfSpine(nodeId) over this
+    // passthrough.
     const subtree = process.env['CRTR_SUBTREE'];
     if (subtree !== undefined && subtree !== '')
         env['CRTR_SUBTREE'] = subtree;
@@ -167,7 +97,9 @@ export function spawnNode(opts) {
         cycles: 0,
         created: new Date().toISOString(),
         cwd: opts.cwd,
-        host_kind: opts.hostKind ?? 'tmux',
+        // Broker is the only host: every node runs on the headless broker; a tmux
+        // pane is only an attach viewer.
+        host_kind: 'broker',
         kind: opts.kind,
         mode,
         lifecycle,

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

@@ -1,357 +1,114 @@
-import { type NodeRow, type FocusRow } from '../canvas/index.js';
-import { homeSessionOf, childBackstageOf } from './nodes.js';
-export { homeSessionOf, childBackstageOf };
+import { type FocusRow } from '../canvas/index.js';
 export type { FocusRow };
-export { piCommand, paneLocation, currentTmux, inTmux, ensureSession, openNodeWindow, splitWindow, focusWindow, windowAlive, windowOfPane, respawnPane, respawnPaneSync, setPaneOption, getPaneOption, paneCurrentPath, listLivePanes, } from './tmux.js';
+export { splitWindow, focusWindow, selectWindow, switchClient, openNodeWindow, ensureSession, paneLocation, paneExists, paneRunning, paneCurrentPath, currentTmux, inTmux, installMenuBinding, setPaneOption, getPaneOption, piCommand, respawnPaneSync, closePane, windowOfPane, renameWindow, paneOfWindow, windowAlive, listLivePanes, } from './tmux.js';
 export type { RespawnPaneOpts } from './tmux.js';
-export { nodeSession } from './nodes.js';
-/** The focus a node occupies, or null. UNIQUE(node_id) ⇒ at most one. */
+/** The viewer a node has on screen, or null. UNIQUE(node_id) ⇒ at most one. */
 export declare function focusOf(nodeId: string): FocusRow | null;
-/** Is this node on a viewport? */
+/** Does this node have a live viewer on screen? */
 export declare function isFocused(nodeId: string): boolean;
-/** The focus realized by a given pane (`%id`), or null. */
+/** The viewer realized by a given pane (`%id`), or null. */
 export declare function focusByPane(pane: string): FocusRow | null;
-/** The set of node ids currently on some focus. */
+/** The set of node ids that currently have a live viewer. */
 export declare function focusedNodes(): Set<string>;
-/** Every focus row (every live viewport). */
+/** Every live viewer row (GC'ing any whose pane has gone). */
 export declare function listFocuses(): FocusRow[];
-/** The on-screen viewport a human-in-the-loop prompt raised by `nodeId` should
- *  surface into: the HIGHEST FOCUSED node of nodeId's graph — the focused node
- *  closest to the graph root, i.e. the session/window the user is actually
+/** The on-screen viewer a human-in-the-loop prompt raised by `nodeId` should
+ *  surface into: the HIGHEST node of nodeId's graph that has a viewer — the
+ *  viewer closest to the graph root, i.e. the session/window the user is actually
  *  watching this work in. Walks nodeId's spine to its root, enumerates the whole
- *  tree root-first (`view` is BFS ⇒ shallowest first), and returns the focus row
- *  of the first node that occupies a viewport. null when nothing in the graph is
- *  on screen — the caller then surfaces in the user's attached pane rather than
- *  the backstage node session. PURE (db reads only): no tmux probe, so the pane
- *  may be stale; the caller liveness-checks before targeting it. */
+ *  tree root-first (`view` is BFS ⇒ shallowest first), and returns the viewer row
+ *  of the first node that has one. null when nothing in the graph is on screen —
+ *  the caller then surfaces in the user's attached pane. PURE (db reads only): no
+ *  tmux probe, so the pane may be stale; the caller liveness-checks before
+ *  targeting it. */
 export declare function graphSurfaceTarget(nodeId: string): FocusRow | null;
-/** The cached LOCATION as stored on a node row: the authoritative `pane` handle
- *  plus its derived window/session cache. */
-export interface CachedLocation {
-    pane: string | null;
-    tmux_session: string | null;
-    window: string | null;
-}
-/** What `reconcile` resolved from tmux for the cached location. The shell does
- *  the two driver reads; the pure decision interprets them.
- *    - `paneLoc`: `paneLocation(cached.pane)` — the pane's CURRENT session/window,
- *      or null when the pane is gone. Only meaningful when `cached.pane != null`.
- *    - `windowPane`: `paneOfWindow(cached.tmux_session, cached.window)` — the live
- *      window's active pane, for the legacy backfill case (`cached.pane == null`). */
-export interface LiveProbe {
-    paneLoc: {
-        session: string;
-        window: string;
-    } | null;
-    windowPane: string | null;
-}
-/** The presence patch `reconcile` should write, or `{ kind: 'none' }` for a no-op.
- *    - `none`     — the cache already matches reality (or there's nothing to do).
- *    - `gone`     — the durable pane is gone → null the whole LOCATION.
- *    - `follow`   — the pane moved (user move) → re-point the cache at its new
- *                   window/session, keeping the same pane id.
- *    - `backfill` — a legacy row had no pane but a live window → adopt the
- *                   window's active pane as the durable handle (begins populating
- *                   `pane` for pre-existing nodes). */
-export type ReconcileDecision = {
-    kind: 'none';
-} | {
-    kind: 'gone';
-} | {
-    kind: 'follow';
-    pane: string;
-    tmux_session: string;
-    window: string;
-} | {
-    kind: 'backfill';
-    pane: string;
-    tmux_session: string;
-    window: string;
-};
-/** PURE reconciliation decision (§2.4) — unit-testable without a live tmux.
- *  Given the cached row LOCATION and what tmux currently reports, decide the
- *  presence patch. Mirrors the pure-core/impure-shell split (cf. `livenessVerdict`
- *  vs `handleLiveWindow`): this is the decision, `reconcile` wires it to the
- *  driver reads + `setPresence`. */
-export declare function reconcileDecision(cached: CachedLocation, live: LiveProbe): ReconcileDecision;
-/** Reconcile a node's LOCATION against tmux reality (§2.4) — the impure shell.
- *  Reads `row.pane`, resolves its CURRENT session/window via the driver, and
- *  writes the resulting presence patch through `setPresence` (never a raw UPDATE):
- *    - pane moved   → FOLLOW (re-point window/session, keep the pane id)
- *    - pane gone    → null the whole LOCATION
- *    - legacy/no pane + live window → backfill the pane from `paneOfWindow`
- *  A no-op when there's nothing to resolve (genuinely no pane, or the cache is
- *  already current). Call this before any swap/kill/focus/revive so the act lands
- *  on the pane's current window, never a stale one. */
-export declare function reconcile(nodeId: string): void;
-/** Reconcile a FOCUS's derived `session` cache against tmux reality (§2.4, Q4) —
- *  the focus-row analogue of `reconcile`. A focus is anchored on its durable
- *  `%pane_id`; `session` is a derived cache. If the user moved the focus pane to
- *  another session, re-point the cache so a resume-into-focus lands in the pane's
- *  CURRENT session. A no-op when the focus has no pane, the cache is already
- *  current, or the pane is GONE — in the gone case reconcileFocus does NOT null
- *  the row; the caller (reviveIntoPlacement) instead falls to the backstage
- *  branch via `paneExists(pane)` being false. */
-export declare function reconcileFocus(focusId: string): void;
-/** Is this node's pane (its LOCATION) alive? The v3 PRIMARY liveness probe,
- *  PURE / non-mutating so the daemon can gate on it without side effects:
- *    - `pane != null`  → `paneExists(pane)` (display-message on the `%id`), so a
- *      user moving the pane to another window/session never reads as "gone".
- *    - `pane == null`  → window-keyed FALLBACK (`windowAlive`) for legacy/no-pane
- *      rows that haven't been backfilled yet.
- *  Accepts a node id (re-reads the row) or a `NodeRow` already in hand. */
-export declare function isNodePaneAlive(node: string | NodeRow): boolean;
-/** The launch recipe `reviveIntoPlacement` plays into a pane. `command` is the
- *  full shell string (`piCommand(argv)`); `env`/`cwd`/`name` describe the
- *  window/pane; `resuming` is carried through for the caller's ReviveResult. */
-export interface ReviveLaunch {
-    command: string;
-    env: Record<string, string>;
-    cwd: string;
-    name: string;
-    resuming: boolean;
-}
-/** Where a revive physically landed: the new/derived window, the session it ran
- *  in, and the durable pane id. */
-export interface PlacementResult {
-    window: string | null;
-    session: string;
-    pane: string | null;
-}
-/** The PURE revive-target decision (§1.4/§5.1) — THE assertion that the
- *  "unbidden windows" bug is structurally dead. Given a node's focus (or null),
- *  whether that focus's pane is still alive, and the node's durable REVIVE-HOME
- *  (`home_session`), decide WHERE a revive must land:
- *    - occupies a LIVE focus → resume IN PLACE in that focus pane (no new window).
- *    - otherwise             → a new window in `homeSession`, and NOTHING ELSE.
- *
- *  The backstage branch's session is `homeSession` ONLY — never
- *  `meta.tmux_session`, the field focus taints to a user session. For a
- *  post-Step-1 child `homeSession` is the backstage `crtr` (never a user
- *  session), so a non-focused child — INCLUDING a once-focused-now-unfocused
- *  child whose `tmux_session` was tainted — can NEVER revive into a user session.
- *  A root's `homeSession` is its own session, so reviving a root into its own
- *  session is correct, not the bug. */
-export type ReviveTargetDecision = {
-    kind: 'focus-pane';
-    pane: string;
-    session: string;
-} | {
-    kind: 'backstage';
-    session: string;
-};
-export declare function reviveTarget(focus: FocusRow | null, focusPaneAlive: boolean, homeSession: string): ReviveTargetDecision;
-/** Place a reviving node into its CORRECT location (§1.4) — the single decision
- *  that replaces revive.ts's old `session = meta.tmux_session ?? nodeSession()` +
- *  `openNodeWindow`. Reconcile first (§2.4), then dispatch on `reviveTarget`:
- *    - the node occupies a LIVE focus → `reconcileFocus` (resolve the pane's
- *      CURRENT session, Q4) and `respawn-pane -k` the pi INTO that focus pane —
- *      no new window (F3 resume-in-place).
- *    - otherwise → the node is NOT focused (or its focus pane already collapsed,
- *      the Step-5 limitation: remain-on-exit lands in Step 6), so it may ONLY
- *      (re)appear in its durable REVIVE-HOME: a fresh window in `homeSession`.
- *      **There is NO code path here by which a non-focused node's new-window
- *      targets a user session** — `openNodeWindow`'s session is `homeSession` and
- *      nothing else. That is the structural bug-kill.
- *
- *  `setPresence` (the one atomic LOCATION write) records where the node landed.
- *  CRTR_ROOT_SESSION is forced to the node's children-backstage (childBackstageOf)
- *  in BOTH branches so the node's children always flow to the backstage, never
- *  into the focus session — and, for a front-door ROOT, never into the user
- *  session its own pane adopted. */
-export declare function reviveIntoPlacement(nodeId: string, launch: ReviveLaunch): PlacementResult;
-/** Relocate a node's still-running agent to the background `crtr` session,
- *  freeing the foreground pane WITHOUT killing the pi. `break-pane` moves the
- *  pane out of the foreground window into a fresh window in the shared backstage
- *  (the pi keeps generating); the node becomes a background window — switchable
- *  but not rendered, like any other node. Reconcile first (act on the pane's
- *  CURRENT location, §2.4) and again after (presence FOLLOWS the move). No-op
- *  (false) when there is no live pane to relocate or tmux refuses the break.
- *  `pane` is the authoritative node pane the caller acts on (the Alt+C menu's
- *  `#{pane_id}`); falls back to the node's durable handle.
- *
- *  Invariant P gate (Bug 1): the backstage holds ONLY generating-but-unfocused
- *  nodes. A node that is NOT mid-turn (e.g. a resident root parked idle between
- *  turns, detached via Alt+C → D) must never be parked there as a live-idle pi —
- *  nothing would re-enter agent_end to release it and, with no live subscription,
- *  nothing would wake it, so it would hold a backstage pane forever, reaped by
- *  nothing. Such a node is RELEASED to dormant instead (mirrors the parked-viewer
- *  release on focus-away in retargetFocus). */
-export declare function detachToBackground(nodeId: string, pane?: string): boolean;
-/** A reviver: resume a DORMANT node into its backstage placement (a fresh `crtr`
- *  window via reviveIntoPlacement). Injected so placement.ts need not import
- *  revive.ts (which imports placement.ts — a cycle). The node's landed pane is
- *  read back from its row afterwards. */
+/** Synchronously wait until a broker's view.sock accepts a connection. The spawn
+ *  and focus flows are sync (the command layer calls them directly), so the
+ *  readiness probe lives in a short child Node process that can use async net
+ *  events while this process blocks in `spawnSync`. Success proves more than file
+ *  existence: it is robust to a stale leftover socket the launching broker has
+ *  not unlinked yet, because only an accepting listener exits 0. */
+export declare function waitForBrokerViewSocket(nodeId: string): boolean;
+/** A reviver: ensure a node's broker ENGINE is alive (idempotent → reviveNode →
+ *  headlessBrokerHost.launch). Injected so placement.ts need not import revive.ts
+ *  (which imports placement.ts — a cycle). */
 export type Reviver = (nodeId: string) => void;
-/** Result of a focus/retarget op. */
+/** Result of a focus op. `inPlace` = navigated to an existing viewer (no new
+ *  pane); false = a fresh viewer pane was opened/moved. `revived` = this call
+ *  had to (re)launch the broker engine. */
 export interface FocusResult {
     focused: boolean;
     session: string | null;
     inPlace: boolean;
     revived: boolean;
 }
-/** PURE disposition of a focus's outgoing occupant after a retarget swap (§2.5/
- *  §1.3). Four signals decide one of three fates; unit-testable in isolation:
- *    - `kill`     — a holder pane (no row) or a done/dead/canceled node: reap the
- *                   (now-backstage) pane (Invariant P: not-focused + not-live ⇒
- *                   no pane).
- *    - `backstage`— a human-driven RESIDENT node (editor/root/orchestrator — NEVER
- *                   despawned on focus-away), or a terminal worker that is
- *                   genuinely MID-TURN (Invariant F2 — keeps running off-screen).
- *    - `release`  — a PARKED terminal viewer (live but not mid-turn): a node
- *                   revived only for inspection. Despawn it back to dormant
- *                   (transition `release` → idle/idle-release) and reap its pane;
- *                   the daemon revives it on its inbox, or the user re-focuses.
- *                   This is the bug fix: such a node was misclassified as
- *                   generating and left stuck active forever.
- *  Order matters: `resident` is checked BEFORE `generating` so a resident node is
- *  always kept warm regardless of whether it happens to be mid-turn. */
-export type OutgoingAction = {
-    kind: 'backstage';
-} | {
-    kind: 'kill';
-} | {
-    kind: 'release';
-};
-export declare function outgoingDisposition(o: {
-    exists: boolean;
-    live: boolean;
-    resident: boolean;
-    generating: boolean;
-}): OutgoingAction;
-/** Open a NEW viewport (§2.3, F4) — the ONLY path a new pane appears in a user
- *  session. Default: `splitWindow(callerPane)` beside (Q3); `newWindow` opens a
- *  fresh window in the caller pane's session instead. Arms `remain-on-exit` on
- *  the new pane's window (F3) and inserts a focuses row anchored on it, occupied
- *  by a HOLDER until retargetFocus swaps a real node in. A benign long-sleep
- *  holds the pane open until the swap; retargetFocus reaps it. Returns the row,
- *  or null if tmux failed. */
-export declare function openFocus(callerPane: string, opts?: {
-    newWindow?: boolean;
+/** Env for a `crtr attach` VIEWER pane (the focus split, the spawn viewer
+ *  window, AND recycle's re-attach respawn): propagate CRTR_HOME so the viewer
+ *  resolves the SAME canvas home — and thus the right view.sock — under a
+ *  non-default override; otherwise an empty env (the pane inherits the tmux
+ *  server env, like every other crtr chrome pane). One helper so the viewer-pane
+ *  sites can't drift. */
+export declare function viewerSplitEnv(): Record<string, string>;
+/** Register a `crtr attach` VIEWER pane as the node's one viewer focus row.
+ *  UNIQUE(node_id) ⇒ one viewer per node: returns
+ *  the existing row (no insert) when the pane or the node is already registered.
+ *  `window` is accepted for the call contract (spawn passes it) but not stored —
+ *  the focuses table keys on pane + session only. The attach client self-tags the
+ *  pane `@crtr_node` on connect, so `nodeInPane` resolves it either way. */
+export declare function registerViewerFocus(nodeId: string, pane: string, session: string | null, window: string | null): FocusRow | null;
+/** Open a `crtr attach` VIEWER for `nodeId` and register its viewer focus row —
+ *  the shared opener used by `focus` (a split beside the caller) and by a --root
+ *  spawn (a fresh window in the caller's current session). Wraps `ensureSession`
+ *  + `openNodeWindow`/`splitWindow` + `registerViewerFocus`. The attach client
+ *  connects to the node's `view.sock` and renders/drives the live broker engine
+ *  — it NEVER launches the engine (the one-writer invariant; the caller ensures
+ *  the broker is alive first). Returns the registered viewer row, or null if tmux
+ *  refused.
+ *    - default → a fresh WINDOW in `session` (the --root spawn-viewer path).
+ *    - `besidePane` → a SPLIT beside that pane in its own session (the focus
+ *      open-beside-the-caller path); `session` is then only a fallback. */
+export declare function openViewerWindow(nodeId: string, session: string, opts?: {
+    name?: string;
+    cwd?: string;
+    besidePane?: string;
 }): FocusRow | null;
-/** Register the FOREGROUND root's pane as focus #1 at boot (§2.6). The inline
- *  root owns the user's viewport, so its own pane becomes a durable focus — with
- *  `remain-on-exit` so a clean exit FREEZES the pane rather than detaching the
- *  terminal (F1). A background `--root` does NOT call this (§6): it stays a plain
- *  window until the user `node focus`es it. No-op when the pane or this node is
- *  already a focus. The focus row IS the record — no pointer to mirror. */
-export declare function registerRootFocus(nodeId: string, pane: string, session: string | null, window: string | null): FocusRow | null;
-/** retargetFocus — the unified hot-swap (§2.5, Invariant P + Q5). Swap `incoming`
- *  onto focus `focusId`'s viewport, keeping the screen position invariant (no new
- *  window). One sqlite txn updates the focus row + BOTH nodes' presence:
- *    - Q5: if `incoming` already occupies ANOTHER focus, VACATE it first (close
- *      its row + kill its pane — the node MOVES here, no auto-retarget).
- *    - resolve `incoming`'s live pin pane (a backstage pane), else `revive` it
- *      into the backstage and read back its pane.
- *    - `swapPaneInPlace(pin, focusPane)`: incoming → the viewport slot; the
- *      outgoing occupant → incoming's old (backstage) slot, %ids preserved
- *      (cross-session swap confirmed by the spike).
- *    - outgoing resident OR still mid-turn → backstage (kept warm / F2); a parked
- *      terminal viewer → RELEASE (status → idle, pane reaped); a holder or
- *      done/dormant occupant → reap its now-backstage pane (Invariant P).
- *  Arms remain-on-exit on the viewport (F3); the focus row is the record. */
-export declare function retargetFocus(focusId: string, incoming: string, revive: Reviver): FocusResult;
-/** The front door for `node focus` / `node cycle` (§2.3): resolve which focus the
- *  caller's pane acts on, then retarget `nodeId` onto it.
- *    - `newPane` → `openFocus` a fresh viewport beside the caller (F4), then
- *      retarget into it.
- *    - else → retarget the caller pane's focus IN PLACE (`focusByPane`); if the
- *      caller's pane is not yet a viewport, adopt it as one (occupied by whatever
- *      node sits there now — `callerNode`, else resolved by pane).
- *    - no caller pane (not in tmux) → best-effort: reconcile + report status,
- *      not-in-place (no viewport to swap into). */
+/** Bring a node's ONE viewer pane forefront (§A.4). Every node is a detached
+ *  broker, so there is no engine pane to swap into the caller's viewport — focus
+ *  instead ensures the node's single `crtr attach` viewer is on screen beside (or
+ *  navigated to) the caller:
+ *    (a) ensure the broker ENGINE is alive (idempotent injected reviver) and its
+ *        view.sock is ACCEPTING (closes the cold-start race against attach's
+ *        single connect) — without this the freshly-opened viewer would exit
+ *        "no broker".
+ *    (b) `--new-pane` → always a fresh viewer beside the caller (e.g. two
+ *        different nodes side by side); drop any prior viewer first (UNIQUE).
+ *    (c) the node already has a live viewer:
+ *          - in the caller's session ⇒ navigate to it (switchClient+selectWindow),
+ *            no new pane (inPlace).
+ *          - elsewhere (e.g. a --root's viewer in another session) ⇒ MOVE it: close the old
+ *            viewer pane (the broker runs on; the fresh viewer replays full
+ *            scrollback from the broker `welcome` snapshot), drop its row, reopen
+ *            beside the caller.
+ *    (d) no live viewer ⇒ open one beside the caller and register the row.
+ *
+ *  crtr is tmux-only: with no caller pane there is no viewport to open and no
+ *  non-tmux fallback — report not-focused. */
 export declare function focus(nodeId: string, opts: {
     pane?: string;
     newPane?: boolean;
-    callerNode?: string;
     revive: Reviver;
 }): FocusResult;
-/** Synchronously wait until a broker's view.sock accepts a connection. `focus()`
- *  is sync today (the command layer calls it directly), so the readiness probe
- *  lives in a short child Node process that can use async net events while this
- *  process blocks in `spawnSync`. Success proves more than file existence: it is
- *  robust to a stale leftover socket that the launching broker has not unlinked
- *  yet, because only an accepting listener exits 0. */
-export declare function waitForBrokerViewSocket(nodeId: string): boolean;
-/** Env for a `crtr attach` VIEWER pane (the focusBroker split AND recycle's
- *  re-attach respawn): propagate CRTR_HOME so the viewer resolves the SAME canvas
- *  home — and thus the right view.sock — under a non-default override; otherwise
- *  an empty env (the pane inherits the tmux server env, like every other crtr
- *  chrome pane). One helper so the two viewer-pane sites can't drift. */
-export declare function viewerSplitEnv(): Record<string, string>;
-/** Tear a node off its placement (close/reset teardown, §2.3, flow (e)).
- *  Reconcile first (follow a manual move / backfill a legacy pane), close the
- *  focus row it occupies (if any), kill its pane (pane-keyed via the durable
- *  `%id` — the window collapses once its last pane goes), and null its LOCATION.
- *  The focus row close is the record. Best-effort tmux; the
- *  DB writes always land. The pane kill is the sole teardown unit (Q1/§6: a
- *  split-pane focus returns its space to the surviving split; a standalone-window
- *  focus closes the window). */
+/** Tear a node off its viewer (close/reset/cancel teardown). The broker engine
+ *  is killed by its own host teardown over view.sock — this only closes the
+ *  on-screen viewer: kill its pane (the window collapses once its last pane goes)
+ *  and drop its registry row. Best-effort tmux; the DB write always lands. No-op
+ *  when the node has no viewer. */
 export declare function tearDownNode(nodeId: string): void;
-/** Demote's in-pane relaunch (§2.3, flow (e)): respawn `nodeId`'s launch into an
- *  EXISTING `pane`, keeping the durable `%id` (respawn-pane -k), and record its
- *  presence keyed on that pane. The session/window are DERIVED from the pane
- *  itself (paneLocation), so the recycled node's LOCATION follows the pane it was
- *  recycled into. `launch.env` is passed through verbatim — the caller (demote)
- *  already sets CRTR_ROOT_SESSION (children → backstage) + FRONT_DOOR. Detached
- *  respawn, since the pane is often the caller's own. Returns whether the respawn
- *  dispatched. */
-export declare function recycleFocusPane(nodeId: string, pane: string, launch: ReviveLaunch): boolean;
-/** §1.6 lifecycle successor — hand a truly-done focused node's viewport to its
- *  manager. Repoints the focus row `focusId` to `managerId` (a DB swap of the
- *  occupant). Two takeover realizations, split on the manager's liveness:
- *    - DORMANT manager (dead pi) — ONLY when it is idle + idle-release: the row
- *      repoint is all this does; the manager, woken by the finished node's `push
- *      final` landing in its inbox, is revived by the external daemon INTO this
- *      node's now-frozen focus pane (remain-on-exit), where reviveIntoPlacement's
- *      focus-pane branch resumes it in place — no new window, no taint. A dormant
- *      manager that is NOT idle-release (done/dead/canceled, or idle with another
- *      intent) is one the daemon will NEVER revive, so this returns false WITHOUT
- *      repointing — the caller then disarms the freeze (see below).
- *    - LIVE manager (pi alive in the backstage, the normal multi-child state):
- *      the daemon never revives it (it only respawns dead-pi nodes), so we must
- *      bring it into the viewport SYNCHRONOUSLY here — swap its backstage pane
- *      into the focus slot (MAJOR 1). Otherwise the manager runs off-screen
- *      forever while %m sits orphaned in the viewport and the focus row lies
- *      about LOCATION.
- *  Returns false — the caller closes the focus (Q1: closeFocusToShell disarms
- *  remain-on-exit so the pane REAPS on exit) — whenever NO successor will claim
- *  the frozen pane: no manager, the manager IS this node, the manager already
- *  occupies another viewport (UNIQUE node_id: do NOT move it, §1.6 edge), the
- *  manager row is missing, or it is a dormant manager the daemon won't revive
- *  (not idle-release) / a live-but-paneless inline root. It does NOT repoint the
- *  occupant on any false path — repointing while returning false would strand the
- *  pane frozen forever with no reaper (the dead-focus-pane bug).
- *
- *  Why the live swap is NOT the forbidden self-saw: `swap-pane -d` only EXCHANGES
- *  two panes' slot positions; it never respawns or kills the finishing node's own
- *  pi. The forbidden move is a synchronous `respawn-pane -k %m` from inside %m —
- *  we never do that here. After the swap, %m (the dying node's pane) sits in the
- *  manager's old backstage slot; the caller nulls this node's presence so nothing
- *  tracks the corpse. */
-export declare function handFocusToManager(focusId: string, managerId: string | null): boolean;
-/** Q1 close-to-shell for a truly-done focused node with no successor (§1.6 /
- *  flow (b)): close its focus row and DISARM the pane's
- *  freeze (`remain-on-exit` off) so it reaps when the finishing pi exits. The
- *  stophook calls this instead of `tearDownNode` because it runs INSIDE the pane
- *  it is closing: it cannot `closePane` its own pane (self-saw), but it is still
- *  alive to disarm the freeze, so the pane closes on exit (return-to-shell)
- *  rather than freezing into an orphan. (Keeps the stophook off the tmux driver,
- *  §2.1.) */
-export declare function closeFocusToShell(focusId: string, nodeId: string): void;
-export interface SpreadResult {
-    window: string | null;
-    session: string | null;
-    /** Child node ids whose panes were joined into the target window. */
-    joined: string[];
-    focused: boolean;
-}
-/** Join each of `childIds`' live panes into `targetId`'s window, lay them out
- *  (target wide on the left, children stacked right), and focus it. Reconcile
- *  drives both the target resolution and the per-join fix-up (a joined pane keeps
- *  its `%id` but changes window, so its LOCATION must FOLLOW — else the daemon
- *  reads it dormant). Caller revives dormant nodes first so they have live panes.
- *  No-op result when the target has no live pane. */
-export declare function spreadNode(targetId: string, childIds: string[], opts?: {
-    mainPaneWidth?: string;
-}): SpreadResult;
+/** Detach a node from the foreground (the `node lifecycle --detach` / Alt+C → D
+ *  half). Every node is a headless broker — the only thing on screen is its
+ *  `crtr attach` VIEWER pane — so "detach" means STOP FOREGROUNDING it: close the
+ *  viewer pane (and drop its row) and leave the broker engine running untouched,
+ *  reconnectable by a later `focus`. `pane` is the authoritative pane the caller
+ *  acts on (the Alt+C menu's `#{pane_id}`); falls back to the node's registered
+ *  viewer pane. No-op (false) when there is no live viewer pane to close. */
+export declare function detachToBackground(nodeId: string, pane?: string): boolean;