@crouton-kit/crouter 0.3.14 → 0.3.16

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

@@ -0,0 +1,299 @@
+import { type NodeRow, type FocusRow } from '../canvas/index.js';
+import { homeSessionOf } from './nodes.js';
+export { homeSessionOf };
+export type { FocusRow };
+export { piCommand, paneLocation, currentTmux, inTmux, ensureSession, openNodeWindow, focusWindow, windowAlive, windowOfPane, respawnPane, } 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. */
+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. 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 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); 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). */
+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.
+ *  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). */
+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;
+/** 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;