@north-light/crouter 0.3.154

package/dist/core/runtime/persona.js

@@ -0,0 +1,132 @@
+// persona.ts — the CENTRALIZED persona-transition injector.
+//
+// A node has two orthogonal, independently switchable axes:
+//   • mode      — base (hands-on; yields mode-preservingly when another window is needed) ↔ orchestrator
+//                 (delegates, holds a roadmap, survives refresh cycles + yields)
+//   • lifecycle — terminal (owes a final up the spine, reaps when done) ↔
+//                 resident (interactable, stays dormant, never forced to submit)
+//
+// Whenever EITHER axis changes from the value the node was last GIVEN guidance
+// for, the node must be prompt-injected with guidance for its new state —
+// automatically, here, not by each state-changing command. Commands just call
+// `updateNode({ mode|lifecycle })`; this module is the single source of the
+// transition prose, delivered from exactly two sites:
+//   • the stophook turn_end hook (self-changes this turn + external changes
+//     while the node is active), and
+//   • the revive kickoff (external changes made while the node was dormant).
+//
+// The `persona_ack` meta field records the last {mode,lifecycle} the node was
+// given guidance for (born equal to its initial persona at spawn, so a fresh
+// worker never gets spurious guidance). `personaDrift` compares live meta to it;
+// the caller delivers the guidance, then commits the ack.
+import { getNode, updateNode } from '../canvas/index.js';
+import { resolveMemoryDoc } from '../memory-resolver.js';
+import { readRoadmap, roadmapPath } from './roadmap.js';
+import { orchestratorContextNote } from './bearings.js';
+// ---------------------------------------------------------------------------
+// base→orchestrator guidance (the roadmap-shaping dump) — MOVED here from
+// promote.ts so the injector is the one place that builds it.
+// ---------------------------------------------------------------------------
+/** Load a builtin/user/project memory doc's body by its normalized name, or ''
+ *  if it can't be resolved. The single source for the lifecycle/spine/
+ *  orchestration-kernel fragments this injector re-delivers on a transition —
+ *  the SAME docs Phase 2 authored under `src/builtin-memory/`, so static
+ *  (system-prompt splice) and transition prose can never drift. */
+function loadMemoryBody(name) {
+    try {
+        return resolveMemoryDoc(name).body.trim();
+    }
+    catch {
+        return '';
+    }
+}
+/** The base→orchestrator guidance dump, specialized to the node's kind: the
+ *  shared orchestration-kernel doc + the roadmap scaffold the node must author +
+ *  the orchestrator context-dir framing + a short pointer at the substrate
+ *  memory flow (promotion re-informs of nothing about the stores, it only adds
+ *  the across-cycles relevance). The node is now a delegator whose scarce
+ *  resource is its own context window. Roadmap-shaping guidance is just another orchestrator-gated memory
+ *  doc the node already gets via the boot-render splice (kinds/<kind>/orchestrator
+ *  gated `{kind, mode: orchestrator}`). (Lifecycle is left to its own section —
+ *  promotion no longer forces resident, so this never asserts residency.) */
+function orchestrationGuidance(nodeId, kind) {
+    const kernel = loadMemoryBody('orchestration-kernel');
+    const roadmap = readRoadmap(nodeId) ?? '(no roadmap yet)';
+    const rmPath = roadmapPath(nodeId);
+    const parts = [
+        `You are now a ${kind.toUpperCase()} ORCHESTRATOR. Your scarce resource is your own context window.`,
+        'Your job is to manage context and delegate — not to do the goal yourself.',
+        '',
+        kernel,
+    ];
+    parts.push('', `Your roadmap scaffold (\`${rmPath}\`) — author it now: state the goal, exit criteria, and the phase skeleton, using the approach above. Current contents:`, '', roadmap, '', 
+    // The orchestrator framing for the context dir — the missing guidance a
+    // promoted node never got at spawn (it spawned as a base worker). Same note
+    // a born-orchestrator gets in its <crtr-bearings> block.
+    orchestratorContextNote(nodeId), '', 'Your three long-term memory scopes (user-global, project, node-local) already surface in your bearings at boot. What promotion changes is USE, not access: you now persist across refresh cycles, so node-local carries what THIS goal needs between your refreshes, and durable facts you commit to user-global or project outlive this node. Use `crtr memory write` to save a document; `crtr memory list` to browse; `crtr memory find` to search (see "Your long-term memory" above for the full substrate flow).', '', 'Then delegate each phase with `crtr node new --kind <kind>`. When your context fills, run `crtr node yield` to refresh against this roadmap.');
+    return parts.join('\n');
+}
+// ---------------------------------------------------------------------------
+// The other three transitions — short, prescriptive, audience = the node's
+// agent (decision-first; one well-placed "don't").
+// ---------------------------------------------------------------------------
+/** orchestrator → base (demote): hands-on again, finish in-window. */
+function baseModeGuidance() {
+    return ('You are HANDS-ON again — base mode. Do the work yourself in THIS window and finish it here; ' +
+        'stop delegating by default. You no longer drive a roadmap, so `crtr node yield` is not your exit. ' +
+        'Spawn a child only for a cleanly separable unit, never as your first move.');
+}
+// The lifecycle transition prose is the SAME contract that's baked into the
+// static system prompt at birth — so both load from the one source
+// (`personas/lifecycle/{terminal,resident}.md`) and can never drift. The flip
+// only re-delivers that fragment as the node's new-state steer.
+/** terminal → resident: interactable, never forced to submit. */
+function residentLifecycleGuidance() {
+    return loadMemoryBody('lifecycle/resident');
+}
+/** resident → terminal: owes a final, reaps when done. */
+function terminalLifecycleGuidance() {
+    return loadMemoryBody('lifecycle/terminal');
+}
+/** Build the injected transition prompt for a `from → to` persona change.
+ *  Concatenates the relevant section per changed axis (both when both changed).
+ *  Pure read of the node's roadmap/memory for the base→orchestrator case. */
+export function transitionGuidance(nodeId, from, to) {
+    const sections = [];
+    if (from.mode !== to.mode) {
+        if (to.mode === 'orchestrator') {
+            const node = getNode(nodeId);
+            sections.push(orchestrationGuidance(nodeId, node?.kind ?? 'general'));
+        }
+        else {
+            sections.push(baseModeGuidance());
+        }
+    }
+    if (from.lifecycle !== to.lifecycle) {
+        sections.push(to.lifecycle === 'resident' ? residentLifecycleGuidance() : terminalLifecycleGuidance());
+    }
+    return sections.join('\n\n');
+}
+// ---------------------------------------------------------------------------
+// Detector + ack commit.
+// ---------------------------------------------------------------------------
+/** Compare a node's live {mode,lifecycle} against its `persona_ack` (the last
+ *  state it was given guidance for). Returns the transition + built guidance
+ *  when they differ, else null. Does NOT mutate — the caller delivers the
+ *  guidance, then `commitPersonaAck`s the new state. An unset `persona_ack`
+ *  (legacy node) defaults to the current persona, so it reads as no drift and
+ *  never fabricates spurious guidance. */
+export function personaDrift(nodeId) {
+    const meta = getNode(nodeId);
+    if (meta === null)
+        return null;
+    const to = { mode: meta.mode, lifecycle: meta.lifecycle };
+    const from = meta.persona_ack ?? { mode: meta.mode, lifecycle: meta.lifecycle };
+    if (from.mode === to.mode && from.lifecycle === to.lifecycle)
+        return null;
+    return { from, to, guidance: transitionGuidance(nodeId, from, to) };
+}
+/** Commit the persona state the node has now been given guidance for. */
+export function commitPersonaAck(nodeId, to) {
+    updateNode(nodeId, { persona_ack: to });
+}

package/dist/core/runtime/pi-cli.d.ts

@@ -0,0 +1,8 @@
+export declare function resolveBundledPiPackageDir(): string;
+/** Environment for a bundled pi subprocess. pi resolves theme assets relative
+ *  to its package root; pnpm/npm mixed layouts can make its own module URL point
+ *  through `.pnpm` at a package copy without those JSON assets, so explicitly
+ *  pin the real bundled package directory (the same contract attach uses). */
+export declare function bundledPiSubprocessEnv(): NodeJS.ProcessEnv;
+export declare function resolveBundledPiCliPath(): string;
+export declare function bundledPiCommandForShell(quote: (value: string) => string): string;

package/dist/core/runtime/pi-cli.js

@@ -0,0 +1,65 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, parse } from 'node:path';
+import { fileURLToPath } from 'node:url';
+function findPackageRootFromEntry(entryPath, expectedName) {
+    let dir = dirname(entryPath);
+    const root = parse(dir).root;
+    while (true) {
+        const pkgPath = join(dir, 'package.json');
+        if (existsSync(pkgPath)) {
+            try {
+                const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+                if (pkg.name === expectedName)
+                    return dir;
+            }
+            catch {
+                return null;
+            }
+        }
+        if (dir === root)
+            return null;
+        dir = dirname(dir);
+    }
+}
+export function resolveBundledPiPackageDir() {
+    const packageName = '@earendil-works/pi-coding-agent';
+    let entryPath;
+    try {
+        entryPath = fileURLToPath(import.meta.resolve(packageName));
+    }
+    catch (error) {
+        throw new Error(`crouter install is missing bundled ${packageName}; reinstall @north-light/crouter. ${error.message}`);
+    }
+    const packageRoot = findPackageRootFromEntry(entryPath, packageName);
+    if (packageRoot === null) {
+        throw new Error(`could not locate bundled ${packageName} package root from ${entryPath}`);
+    }
+    return packageRoot;
+}
+/** Environment for a bundled pi subprocess. pi resolves theme assets relative
+ *  to its package root; pnpm/npm mixed layouts can make its own module URL point
+ *  through `.pnpm` at a package copy without those JSON assets, so explicitly
+ *  pin the real bundled package directory (the same contract attach uses). */
+export function bundledPiSubprocessEnv() {
+    return {
+        ...process.env,
+        PI_PACKAGE_DIR: resolveBundledPiPackageDir(),
+    };
+}
+export function resolveBundledPiCliPath() {
+    const packageRoot = resolveBundledPiPackageDir();
+    const pkgPath = join(packageRoot, 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    const bin = pkg.bin && typeof pkg.bin === 'object' ? pkg.bin.pi : undefined;
+    if (typeof bin !== 'string' || bin.trim() === '') {
+        throw new Error(`bundled @earendil-works/pi-coding-agent does not declare a pi binary in ${pkgPath}`);
+    }
+    const cliPath = join(packageRoot, bin);
+    if (!existsSync(cliPath)) {
+        throw new Error(`bundled pi binary is missing at ${cliPath}`);
+    }
+    return cliPath;
+}
+export function bundledPiCommandForShell(quote) {
+    return `${quote(process.execPath)} ${quote(resolveBundledPiCliPath())}`;
+}

package/dist/core/runtime/pi-vendored.d.ts

@@ -0,0 +1,26 @@
+/** pi's sessions root, VENDORED from pi `config.getSessionsDir()` (= `<agentDir>/
+ *  sessions`). pi's package `exports` map is `.`-only, so config.js can't be
+ *  deep-imported, and a ROOT import of `getAgentDir` would eager-load the entire
+ *  heavy pi SDK index on crtr's front-door hot path (the reason broker-sdk.ts
+ *  dynamic-imports the engine). Mirrors pi: `PI_CODING_AGENT_DIR` env, else
+ *  `~/.pi/agent` (APP_NAME defaults to 'pi'). Re-sync on a pi SDK bump that moves
+ *  the sessions dir — same vendoring rationale as the slash-command list below. */
+export declare function piSessionsRoot(): string;
+/**
+ * pi's builtin slash commands — vendored verbatim from pi `core/slash-commands.js`
+ * `BUILTIN_SLASH_COMMANDS` (review C1). **21 entries at 0.78.1** (review n1 — NOT 23).
+ *
+ * Builtins are NOT engine-interpreted (`session.prompt('/model')` ships `/model`
+ * to the LLM as literal text), so the broker's `get_commands` op MERGES this list
+ * with the engine's registered commands/templates/skills, and the viewer
+ * autocomplete parses these locally. Both the broker (T3) and the viewer (T6)
+ * import this single copy.
+ *
+ * Upstream interpolates `${APP_NAME}` into the `quit` description; `APP_NAME`
+ * defaults to "pi" (overridable via pi config), so the vendored copy hardcodes
+ * "Quit pi".
+ */
+export declare const BUILTIN_SLASH_COMMANDS: ReadonlyArray<{
+    name: string;
+    description: string;
+}>;

package/dist/core/runtime/pi-vendored.js

@@ -0,0 +1,77 @@
+// pi-vendored.ts — symbols copied verbatim from pi that pi does NOT re-export.
+//
+// VENDORED, not imported, because pi's `exports` map is `.`-only (+`./hooks`):
+// a deep import like `@earendil-works/pi-coding-agent/dist/core/slash-commands`
+// fails with ERR_PACKAGE_PATH_NOT_EXPORTED, and the symbol is absent from the
+// package-root `index.d.ts` at BOTH 0.78.1 and 0.79.0 — so there is no pin at
+// which it becomes importable (review C1). The only safe access is to copy it.
+//
+// MAINTENANCE: re-sync on EVERY pi SDK bump. The source of truth is
+// `node_modules/@earendil-works/pi-coding-agent/dist/core/slash-commands.js`.
+// If the upstream list changes (entries added/removed/reworded), update the copy
+// below to match and adjust the count note.
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** pi's sessions root, VENDORED from pi `config.getSessionsDir()` (= `<agentDir>/
+ *  sessions`). pi's package `exports` map is `.`-only, so config.js can't be
+ *  deep-imported, and a ROOT import of `getAgentDir` would eager-load the entire
+ *  heavy pi SDK index on crtr's front-door hot path (the reason broker-sdk.ts
+ *  dynamic-imports the engine). Mirrors pi: `PI_CODING_AGENT_DIR` env, else
+ *  `~/.pi/agent` (APP_NAME defaults to 'pi'). Re-sync on a pi SDK bump that moves
+ *  the sessions dir — same vendoring rationale as the slash-command list below. */
+export function piSessionsRoot() {
+    const env = process.env['PI_CODING_AGENT_DIR'];
+    const agentDir = env !== undefined && env !== '' ? expandTilde(env) : join(homedir(), '.pi', 'agent');
+    return join(agentDir, 'sessions');
+}
+/** Mirror pi's `expandTildePath` (= `normalizePath` with the default expandTilde
+ *  on): a bare `~` is the home dir, and a leading `~/` (or `~\` on win32) joins
+ *  the remainder under home. pi's `getAgentDir()` runs `PI_CODING_AGENT_DIR`
+ *  through this, so the vendored root must too or `~/custom-pi` yields a broken
+ *  relative path. Other forms (absolute, relative, `~user`) pass through as pi
+ *  leaves them. */
+function expandTilde(p) {
+    if (p === '~')
+        return homedir();
+    if (p.startsWith('~/') || (process.platform === 'win32' && p.startsWith('~\\'))) {
+        return join(homedir(), p.slice(2));
+    }
+    return p;
+}
+/**
+ * pi's builtin slash commands — vendored verbatim from pi `core/slash-commands.js`
+ * `BUILTIN_SLASH_COMMANDS` (review C1). **21 entries at 0.78.1** (review n1 — NOT 23).
+ *
+ * Builtins are NOT engine-interpreted (`session.prompt('/model')` ships `/model`
+ * to the LLM as literal text), so the broker's `get_commands` op MERGES this list
+ * with the engine's registered commands/templates/skills, and the viewer
+ * autocomplete parses these locally. Both the broker (T3) and the viewer (T6)
+ * import this single copy.
+ *
+ * Upstream interpolates `${APP_NAME}` into the `quit` description; `APP_NAME`
+ * defaults to "pi" (overridable via pi config), so the vendored copy hardcodes
+ * "Quit pi".
+ */
+export const BUILTIN_SLASH_COMMANDS = [
+    { name: 'settings', description: 'Open settings menu' },
+    { name: 'model', description: 'Select model (opens selector UI)' },
+    { name: 'scoped-models', description: 'Enable/disable models for Ctrl+P cycling' },
+    { name: 'export', description: 'Export session (HTML default, or specify path: .html/.jsonl)' },
+    { name: 'import', description: 'Import and resume a session from a JSONL file' },
+    { name: 'share', description: 'Share session as a secret GitHub gist' },
+    { name: 'copy', description: 'Copy last agent message to clipboard' },
+    { name: 'name', description: 'Set session display name' },
+    { name: 'session', description: 'Show session info and stats' },
+    { name: 'changelog', description: 'Show changelog entries' },
+    { name: 'hotkeys', description: 'Show all keyboard shortcuts' },
+    { name: 'fork', description: 'Create a new fork from a previous user message' },
+    { name: 'clone', description: 'Duplicate the current session at the current position' },
+    { name: 'tree', description: 'Navigate session tree (switch branches)' },
+    { name: 'login', description: 'Configure provider authentication' },
+    { name: 'logout', description: 'Remove provider authentication' },
+    { name: 'new', description: 'Start a new session' },
+    { name: 'compact', description: 'Manually compact the session context' },
+    { name: 'resume', description: 'Resume a different session' },
+    { name: 'reload', description: 'Reload keybindings, extensions, skills, prompts, and themes' },
+    { name: 'quit', description: 'Quit pi' },
+];

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

@@ -0,0 +1,42 @@
+export { paneExists, paneLocation, paneOfNode, paneCurrentPath, ensureSession, openNodeWindow, splitWindow, closePane, currentTmux, switchClient, selectWindow, selectLayout, selectPane, getPaneOption, setPaneOption, breakPane, inTmux, piCommand, shellQuote, installTmuxBindings, renameWindow, displayPopup, windowOfPane, respawnPaneSync, respawnPaneInPlace, paneStartCommand, panePid, windowAlive, listLivePanes, } from './tmux.js';
+/** The shared cold-start deadline (ms) a freshly-opened viewer waits for its
+ *  broker's view.sock — one source of truth for the CRTR_ATTACH_WAIT_MS a viewer
+ *  pane is handed. */
+export declare const BROKER_VIEW_SOCKET_WAIT_MS = 30000;
+/** Wait until a broker's view.sock accepts a connection. The launching caller
+ *  stays async, so the broker's real exit signal can fail fast the wait instead
+ *  of being masked by a zombie pid. Success proves more than file existence: it
+ *  is robust to a stale leftover socket the broker has not unlinked yet,
+ *  because only an accepting listener yields a `connect`. */
+export declare function waitForBrokerViewSocket(nodeId: string, exited?: Promise<{
+    code: number | null;
+    signal: NodeJS.Signals | null;
+}>): Promise<boolean>;
+/** Env for a `crtr surface 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>;
+/** The opened viewer pane's tmux coordinates. */
+export interface ViewerPane {
+    pane: string;
+    session: string | null;
+    window: string | null;
+}
+/** Open a `crtr surface attach` VIEWER pane for `nodeId` — the PURE tmux half of
+ *  placement's openViewerWindow (no focus-row write). Wraps `ensureSession` +
+ *  `openNodeWindow`/`splitWindow`. 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 opened pane's coordinates, 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 openViewerPane(nodeId: string, session: string, opts?: {
+    name?: string;
+    cwd?: string;
+    besidePane?: string;
+    waitForBroker?: boolean;
+}): ViewerPane | null;

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

@@ -0,0 +1,151 @@
+// placement-tmux.ts — the PURE tmux + broker-socket half of placement.
+//
+// After the broker-is-the-host cut, the on-screen surface for a node is a
+// `crtr surface attach` VIEWER pane. Opening/sizing that pane and waiting for the
+// broker's view.sock are pure tmux + net operations — no canvas-db read. They
+// live here so CLI/viewer consumers (workspace, surface-tmux-spread, sysprompt,
+// viewer.ts) can reach the tmux front door WITHOUT dragging placement.ts's
+// canvas state-store (the focuses table) into their bundle.
+//
+// placement.ts RE-EXPORTS viewerSplitEnv + waitForBrokerViewSocket from here so
+// its existing importers (daemon runtime, handlers) are unchanged, and its
+// openViewerWindow composes openViewerPane (here) + registerViewerFocus (the db
+// write, which stays in placement.ts).
+//
+// §5.1 import-lint: placement-tmux.ts is an ALLOWED direct importer of tmux.ts —
+// it is the sanctioned pure-tmux seam, re-exporting the driver verbs other
+// modules need so they never import tmux.ts directly.
+import { createConnection } from 'node:net';
+import { paneLocation, ensureSession, openNodeWindow, splitWindow, selectLayout, } from './tmux.js';
+import { viewSocketPath } from '../canvas/paths.js';
+// Re-export the pure tmux driver verbs the CLI/viewer consumers need, so the
+// §5.1 lint's "only placement / tmux-chrome import tmux.ts" holds while these
+// modules never reach the canvas focuses table.
+export { paneExists, paneLocation, paneOfNode, paneCurrentPath, ensureSession, openNodeWindow, splitWindow, closePane, currentTmux, switchClient, selectWindow, selectLayout, selectPane, getPaneOption, setPaneOption, breakPane, inTmux, piCommand, shellQuote, installTmuxBindings, renameWindow, displayPopup, windowOfPane, respawnPaneSync, respawnPaneInPlace, paneStartCommand, panePid, windowAlive, listLivePanes, } from './tmux.js';
+// ---------------------------------------------------------------------------
+// view.sock readiness — the one shared broker-cold-start primitive
+// ---------------------------------------------------------------------------
+const BROKER_FOCUS_SOCKET_WAIT_MS = 30_000;
+const BROKER_FOCUS_SOCKET_RETRY_MS = 100;
+/** The shared cold-start deadline (ms) a freshly-opened viewer waits for its
+ *  broker's view.sock — one source of truth for the CRTR_ATTACH_WAIT_MS a viewer
+ *  pane is handed. */
+export const BROKER_VIEW_SOCKET_WAIT_MS = BROKER_FOCUS_SOCKET_WAIT_MS;
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+function probeBrokerViewSocket(sockPath, timeoutMs) {
+    return new Promise((resolve) => {
+        let settled = false;
+        let socket = null;
+        const finish = (ok) => {
+            if (settled)
+                return;
+            settled = true;
+            if (socket !== null)
+                socket.destroy();
+            resolve(ok);
+        };
+        try {
+            socket = createConnection(sockPath);
+        }
+        catch {
+            finish(false);
+            return;
+        }
+        socket.once('connect', () => finish(true));
+        socket.once('error', () => finish(false));
+        socket.setTimeout(timeoutMs, () => finish(false));
+    });
+}
+/** Wait until a broker's view.sock accepts a connection. The launching caller
+ *  stays async, so the broker's real exit signal can fail fast the wait instead
+ *  of being masked by a zombie pid. Success proves more than file existence: it
+ *  is robust to a stale leftover socket the broker has not unlinked yet,
+ *  because only an accepting listener yields a `connect`. */
+export async function waitForBrokerViewSocket(nodeId, exited) {
+    const sockPath = viewSocketPath(nodeId);
+    const deadline = Date.now() + BROKER_FOCUS_SOCKET_WAIT_MS;
+    const exitSeen = exited?.then(() => 'exit');
+    while (Date.now() <= deadline) {
+        const remaining = Math.max(0, deadline - Date.now());
+        const probe = probeBrokerViewSocket(sockPath, Math.min(BROKER_FOCUS_SOCKET_RETRY_MS, remaining)).then((ok) => (ok ? 'ready' : 'retry'));
+        // Race the probe against the broker's real exit ONLY when we have one. With
+        // no exit promise, an `?? Promise.resolve('retry')` would settle instantly
+        // and always beat the probe, so readiness could never observe a `connect`.
+        const outcome = exitSeen === undefined ? await probe : await Promise.race([probe, exitSeen]);
+        if (outcome === 'ready')
+            return true;
+        if (outcome === 'exit')
+            return false;
+        if (exitSeen !== undefined) {
+            const sleptOrExit = await Promise.race([
+                sleep(BROKER_FOCUS_SOCKET_RETRY_MS).then(() => 'sleep'),
+                exitSeen,
+            ]);
+            if (sleptOrExit === 'exit')
+                return false;
+        }
+        else {
+            await sleep(BROKER_FOCUS_SOCKET_RETRY_MS);
+        }
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// Viewer pane opener (tmux half, NO focus-row write)
+// ---------------------------------------------------------------------------
+/** Env for a `crtr surface 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 function viewerSplitEnv() {
+    const crtrHome = process.env['CRTR_HOME'];
+    return crtrHome !== undefined ? { CRTR_HOME: crtrHome } : {};
+}
+/** Open a `crtr surface attach` VIEWER pane for `nodeId` — the PURE tmux half of
+ *  placement's openViewerWindow (no focus-row write). Wraps `ensureSession` +
+ *  `openNodeWindow`/`splitWindow`. 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 opened pane's coordinates, 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 function openViewerPane(nodeId, session, opts = {}) {
+    const command = `crtr surface attach to ${nodeId}`;
+    // When the broker may not have bound view.sock yet (a viewer opened right after
+    // a fresh spawn), hand the attach pane CRTR_ATTACH_WAIT_MS so it POLLS the
+    // socket until it accepts instead of failing fast on a cold socket and closing
+    // the pane instantly — the same self-polling bootRoot/resume rely on. The
+    // deadline is the shared BROKER_VIEW_SOCKET_WAIT_MS (one source of truth), not
+    // a literal duplicated at the call site.
+    const env = opts.waitForBroker === true
+        ? { ...viewerSplitEnv(), CRTR_ATTACH_WAIT_MS: String(BROKER_FOCUS_SOCKET_WAIT_MS) }
+        : viewerSplitEnv();
+    const cwd = opts.cwd ?? process.cwd();
+    if (opts.besidePane !== undefined) {
+        const pane = splitWindow(opts.besidePane, { cwd, env, command });
+        if (pane === null)
+            return null;
+        const loc = paneLocation(pane);
+        const sess = loc?.session ?? session;
+        const window = loc?.window ?? null;
+        // Rebalance the window to even side-by-side widths. Without this each split
+        // halves the pane it split from, so repeated spawns beside the same pane keep
+        // shrinking (¼, ⅛, …); an even-horizontal relayout gives every viewer in the
+        // window equal width instead. Best-effort — sizing never fails the open.
+        if (window !== null)
+            selectLayout(window, 'even-horizontal');
+        return { pane, session: sess, window };
+    }
+    ensureSession(session, cwd);
+    const opened = openNodeWindow({ session, name: opts.name ?? nodeId, cwd, env, command });
+    if (opened === null)
+        return null;
+    return { pane: opened.pane, session, window: opened.window };
+}

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

@@ -0,0 +1,97 @@
+import { type FocusRow } from '../canvas/index.js';
+export type { FocusRow };
+export { splitWindow, breakPane, selectLayout, selectPane, focusWindow, selectWindow, switchClient, openNodeWindow, ensureSession, paneLocation, paneExists, paneRunning, paneCurrentPath, currentTmux, inTmux, paneOfNode, installTmuxBindings, installTmuxBindings as installMenuBinding, setPaneOption, getPaneOption, piCommand, shellQuote, respawnPaneSync, closePane, displayPopup, windowOfPane, renameWindow, paneOfWindow, windowAlive, listLivePanes, } from './tmux.js';
+export type { RespawnPaneOpts, TmuxInstalledPair, TmuxInstallDiagnostic, TmuxInstallResult } from './tmux.js';
+/** The viewer a node has on screen, or null. UNIQUE(node_id) ⇒ at most one. */
+export declare function focusOf(nodeId: string): FocusRow | null;
+/** Does this node have a live viewer on screen? */
+export declare function isFocused(nodeId: string): boolean;
+/** The viewer realized by a given pane (`%id`), or null. */
+export declare function focusByPane(pane: string): FocusRow | null;
+/** The set of node ids that currently have a live viewer. */
+export declare function focusedNodes(): Set<string>;
+/** Every live viewer row (GC'ing any whose pane has gone). */
+export declare function listFocuses(): FocusRow[];
+/** 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) => {
+    launch?: {
+        exited: Promise<{
+            code: number | null;
+            signal: NodeJS.Signals | null;
+        }>;
+    };
+} | void;
+/** 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;
+}
+/** Register a `crtr surface 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 surface-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;
+    waitForBroker?: boolean;
+}): FocusRow | null;
+export declare function focus(nodeId: string, opts: {
+    pane?: string;
+    newPane?: boolean;
+    inPlace?: boolean;
+    revive: Reviver;
+}): Promise<FocusResult>;
+/** 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, keepPane?: string): void;
+/** Detach a node from the foreground (the `node lifecycle demote --detach` / Alt+C → D
+ *  half). Every node is a headless broker — the only thing on screen is its
+ *  surface-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;
+/** Reap `nodeId` IFF it is an empty shell (see {@link isEmptyNode}): tear down its
+ *  broker engine, close any viewer, and hard-delete its row (edges cascade) + dir.
+ *  The user closing or detaching from a node that never said anything wants it
+ *  GONE, not parked as a canceled husk — except an OPEN managed worktree keeps
+ *  its node identity so the worktree remains owned and can later be closed.
+ *  Returns true when it reaped. No-op (false) on a node that produced output,
+ *  is mid-first-turn, owns an open managed worktree, or no longer exists. */
+export declare function reapIfEmpty(nodeId: string, keepPane?: string): boolean;
+/** Sweep the whole canvas for empty shells and reap them — the bulk cleanup
+ *  behind `crtr canvas prune --empty`, for the husks that accumulated before
+ *  close/detach learned to reap. Skips: the caller ($CRTR_NODE_ID), nodes
+ *  mid-first-turn, and any node with a LIVE broker (pi_pid alive) — a running
+ *  engine is the daemon's domain and may have output not yet persisted, so bulk
+ *  GC never kills one (the per-action {@link reapIfEmpty} does, since the user
+ *  explicitly closed/detached that node). `dryRun` reports candidates without
+ *  deleting. Returns the reaped (or, under dryRun, reapable) node ids. */
+export declare function reapEmptyNodes(opts?: {
+    dryRun?: boolean;
+}): string[];