@crouton-kit/crouter 0.3.14 → 0.3.15

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

@@ -1,9 +1,34 @@
 import { type NodeMeta, type Mode, type Lifecycle, type LaunchSpec } from '../canvas/index.js';
 /** Generate a node id in the same shape as job ids (time-sortable + random). */
 export declare function newNodeId(): string;
+/** 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 declare function resolveBirthSession(opts: {
+    /** True for an independent root or the inline front door (both adopt the
+     *  caller's session); false for a managed background child. */
+    adoptCaller: boolean;
+    /** The caller's current tmux location, or null when not inside tmux. */
+    here: {
+        session: string;
+    } | null;
+    /** The inherited CRTR_ROOT_SESSION (the backstage the subtree flows into). */
+    rootSession?: string | null;
+}): string;
+/** 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 declare function homeSessionOf(nodeId: string): string;
 export interface NodeContext {
     nodeId: string | null;
-    parentNodeId: string | null;
     kind: string | null;
     mode: Mode | null;
 }
@@ -21,8 +46,14 @@ export interface SpawnNodeOpts {
     lifecycle?: Lifecycle;
     cwd: string;
     name?: string;
+    /** Editor-label handle (2-4 word kebab-case) for the node's first prompt. */
+    description?: string;
     /** Parent node id. Omit for a user-opened root. */
     parent?: string | null;
+    /** Who spawned me (the `spawned_by` provenance edge), when it differs from
+     *  `parent` — e.g. an independent root (parent=null) still records its
+     *  spawner. Defaults to `parent`. */
+    spawnedBy?: string | null;
     /** New subscriptions this node opens default to passive when true. */
     passiveDefault?: boolean;
     /** Resolved pi launch recipe (from resolve(kind,mode)). */

package/dist/core/runtime/nodes.js

@@ -14,10 +14,42 @@
 //             is also recorded.
 import { randomBytes } from 'node:crypto';
 import { createNode, getNode, subscribe, recordSpawn, } from '../canvas/index.js';
+import { nodeSession } from './tmux.js';
 /** Generate a node id in the same shape as job ids (time-sortable + random). */
 export function newNodeId() {
     return `${Date.now().toString(36)}-${randomBytes(4).toString('hex')}`;
 }
+// ---------------------------------------------------------------------------
+// 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();
+}
 /** 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. */
@@ -25,7 +57,6 @@ export function currentNodeContext() {
     const env = process.env;
     return {
         nodeId: env['CRTR_NODE_ID'] ?? null,
-        parentNodeId: env['CRTR_NODE_ID'] ?? null, // a child's parent is the live node
         kind: env['CRTR_KIND'] ?? null,
         mode: env['CRTR_MODE'] ?? null,
     };
@@ -63,33 +94,52 @@ export function nodeEnv(meta) {
 export function spawnNode(opts) {
     const parent = opts.parent ?? null;
     const isRoot = parent === null;
+    // Provenance is independent of the spine: a root has no parent but still
+    // records who spawned it. A child's spawner is its parent unless overridden.
+    const spawnedBy = opts.spawnedBy ?? parent;
+    const mode = opts.mode ?? 'base';
+    // A user-opened root is resident (a conversation you live in); a spawned node
+    // is terminal until it must persist (promotion handles that later).
+    const lifecycle = opts.lifecycle ?? (isRoot ? 'resident' : 'terminal');
     const meta = {
         node_id: opts.nodeId ?? newNodeId(),
         name: opts.name ?? opts.kind,
+        description: opts.description,
+        cycles: 0,
         created: new Date().toISOString(),
         cwd: opts.cwd,
         kind: opts.kind,
-        mode: opts.mode ?? 'base',
-        // A user-opened root is resident (a conversation you live in); a spawned
-        // node is terminal until it must persist (promotion handles that later).
-        lifecycle: opts.lifecycle ?? (isRoot ? 'resident' : 'terminal'),
+        mode,
+        lifecycle,
+        // Born already acked to its initial persona: a fresh node has been "given
+        // guidance" for the state it starts in (its bearings carry it), so the
+        // persona injector sees no drift on its first turn boundary.
+        persona_ack: { mode, lifecycle },
         status: 'active',
         parent,
+        spawned_by: spawnedBy,
         passive_default: opts.passiveDefault ?? false,
         intent: null,
         pi_session_id: null,
+        pi_session_file: null,
         launch: opts.launch,
     };
+    // Validate BEFORE minting: a bad parent must leave no half-born orphan row or
+    // dirs behind, so the parent's existence is checked before createNode
+    // scaffolds anything on disk or in the db.
+    if (parent !== null && getNode(parent) === null) {
+        throw new Error(`cannot spawn under unknown parent node: ${parent}`);
+    }
     createNode(meta);
     if (parent !== null) {
-        if (getNode(parent) === null) {
-            throw new Error(`cannot spawn under unknown parent node: ${parent}`);
-        }
         // The load-bearing seed: parent subscribes (active) to child so it learns
         // when the work finishes. This mirrors spawn structure into the spine.
+        // A root (parent=null) gets NO subscription — nobody is woken by it.
         subscribe(parent, meta.node_id, true);
-        // Audit-only provenance.
-        recordSpawn(meta.node_id, parent);
+    }
+    // Audit-only provenance edge — recorded for a root too (from its spawner).
+    if (spawnedBy !== null && spawnedBy !== undefined && getNode(spawnedBy) !== null) {
+        recordSpawn(meta.node_id, spawnedBy);
     }
     return meta;
 }

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

@@ -0,0 +1,25 @@
+import { type Mode, type Lifecycle } from '../canvas/index.js';
+/** The two-axis persona state the injector keys on. */
+export interface Persona {
+    mode: Mode;
+    lifecycle: Lifecycle;
+}
+export interface PersonaDriftResult {
+    from: Persona;
+    to: Persona;
+    /** The built transition guidance to inject for `to`. */
+    guidance: string;
+}
+/** 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 declare function transitionGuidance(nodeId: string, from: Persona, to: Persona): string;
+/** 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 declare function personaDrift(nodeId: string): PersonaDriftResult | null;
+/** Commit the persona state the node has now been given guidance for. */
+export declare function commitPersonaAck(nodeId: string, to: Persona): void;

package/dist/core/runtime/persona.js

@@ -0,0 +1,139 @@
+// persona.ts — the CENTRALIZED persona-transition injector.
+//
+// A node has two orthogonal, independently switchable axes:
+//   • mode      — base (hands-on, finishes in one window) ↔ 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 { loadKernel, loadPersona, loadLifecycleFragment } from '../personas/index.js';
+import { resolveSkill } from '../resolver.js';
+import { readText } from '../fs-utils.js';
+import { parseFrontmatter } from '../frontmatter.js';
+import { readRoadmap, roadmapPath } from './roadmap.js';
+import { orchestratorContextNote } from './bearings.js';
+import { memoryPath, memoryDir, userMemoryPath, userMemoryDir, projectMemoryPath, projectMemoryDir, } from './memory.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 skill's body text by name, or null if it can't be resolved. Used to
+ *  inline a kind's roadmap-shaping skill into the orchestration guidance. */
+function loadSkillBody(name) {
+    try {
+        const skill = resolveSkill(name, {});
+        return parseFrontmatter(readText(skill.path)).body.trim();
+    }
+    catch {
+        return null;
+    }
+}
+/** The base→orchestrator guidance dump, specialized to the node's kind: the
+ *  shared kernel + that kind's roadmap-shaping skill + the roadmap scaffold the
+ *  node must author + the orchestrator context-dir framing + the three memory
+ *  stores. The node is now a delegator whose scarce resource is its own context
+ *  window. (Lifecycle is left to its own section — promotion no longer forces
+ *  resident, so this never asserts residency.) */
+function orchestrationGuidance(nodeId, kind, cwd) {
+    const kernel = loadKernel();
+    const orch = loadPersona(kind, 'orchestrator');
+    const roadmapSkill = typeof orch?.frontmatter?.['roadmapSkill'] === 'string'
+        ? orch.frontmatter['roadmapSkill']
+        : undefined;
+    const skillBody = roadmapSkill ? loadSkillBody(roadmapSkill) : null;
+    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,
+    ];
+    if (skillBody) {
+        parts.push('', `--- How to shape a ${kind} roadmap (skill: ${roadmapSkill}) ---`, '', skillBody);
+    }
+    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-context> bearings block.
+    orchestratorContextNote(nodeId), '', 'Your long-term memory now exists across three seeded stores (write to them directly), each a different scope per "Your long-term memory" above:', `  • user-global \`${userMemoryDir()}\` (index \`${userMemoryPath()}\`) — who the human is, how they like to work; loaded into every orchestrator everywhere.`, `  • project \`${projectMemoryDir(cwd)}\` (index \`${projectMemoryPath(cwd)}\`) — facts bound to this repo; loaded into every orchestrator working here.`, `  • node-local \`${memoryDir(nodeId)}\` (index \`${memoryPath(nodeId)}\`) — facts specific to this goal; they die with this node.`, 'A memory\'s `type` decides which store it lands in (see "Your long-term memory"). These same paths ride into every future wake in your `<crtr-context>` block.', '', '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 loadLifecycleFragment('resident');
+}
+/** resident → terminal: owes a final, reaps when done. */
+function terminalLifecycleGuidance() {
+    return loadLifecycleFragment('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', node?.cwd ?? process.cwd()));
+        }
+        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/placement.d.ts

@@ -0,0 +1,287 @@
+import { type NodeRow, type FocusRow } from '../canvas/index.js';
+import { homeSessionOf } from './nodes.js';
+export { homeSessionOf };
+export type { FocusRow };
+/** The focus a node occupies, or null. UNIQUE(node_id) ⇒ at most one. */
+export declare function focusOf(nodeId: string): FocusRow | null;
+/** Is this node on a viewport? */
+export declare function isFocused(nodeId: string): boolean;
+/** The focus 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. */
+export declare function focusedNodes(): Set<string>;
+/** Every focus row (every live viewport). */
+export declare function listFocuses(): FocusRow[];
+/** 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 `homeSession` in BOTH branches so the node's
+ *  children always flow to the backstage, never into the focus session. */
+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. */
+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. */
+export type Reviver = (nodeId: string) => void;
+/** Result of a focus/retarget op. */
+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): a still-generating node moves to backstage (F2); a holder pane or a
+ *  done/dormant node has its (now-backstage) pane reaped (Invariant P: a
+ *  not-focused + not-generating node has NO pane). Unit-testable in isolation. */
+export type OutgoingAction = {
+    kind: 'backstage';
+} | {
+    kind: 'kill';
+};
+export declare function outgoingDisposition(o: {
+    exists: 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;
+}): 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. Mirrors focus.ptr via setFocus (the transitional bridge). */
+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 still generating → backstage (F2); else reap its now-backstage
+ *      pane (Invariant P). A holder occupant (no node row) is always reaped.
+ *  Arms remain-on-exit on the viewport (F3) and mirrors focus.ptr (setFocus). */
+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: mirror focus.ptr, report
+ *      not-in-place. */
+export declare function focus(nodeId: string, opts: {
+    pane?: string;
+    newPane?: boolean;
+    callerNode?: string;
+    revive: Reviver;
+}): FocusResult;
+/** 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.
+ *  Mirrors focus.ptr when this node was the current focus. 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). */
+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): 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. (UNCHANGED — the canonical takeover.)
+ *    - 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) — when there is no manager,
+ *  the manager IS this node, or the manager already occupies another viewport
+ *  (UNIQUE node_id: do NOT move it, §1.6 edge).
+ *
+ *  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;
+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;