@crouton-kit/crouter 0.3.82 → 0.3.83

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

@@ -12,16 +12,6 @@ export declare function focusByPane(pane: string): FocusRow | null;
 export declare function focusedNodes(): Set<string>;
 /** Every live viewer row (GC'ing any whose pane has gone). */
 export declare function listFocuses(): FocusRow[];
-/** 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 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;
 /** 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
@@ -84,6 +74,7 @@ export declare function openViewerWindow(nodeId: string, session: string, opts?:
 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

package/dist/core/runtime/placement.js

@@ -24,11 +24,11 @@
 //     tmux-chrome.ts import tmux.ts") holds — every other module reaches the
 //     driver verbs through here.
 import { createConnection } from 'node:net';
-import { getNode, deleteNode, listNodes, openFocusRow, closeFocusRow, getFocusByNode, getFocusByPane, getFocusById, listFocuses as listFocusRows, view, } from '../canvas/index.js';
+import { getNode, fullName, deleteNode, listNodes, openFocusRow, closeFocusRow, getFocusByNode, getFocusByPane, getFocusById, listFocuses as listFocusRows, } from '../canvas/index.js';
 import { nodeHasAssistantMessage, isNodeStreaming } from '../canvas/render.js';
 import { headlessBrokerHost } from './host.js';
-import { paneExists, paneLocation, ensureSession, openNodeWindow, splitWindow, closePane, currentTmux, switchClient, selectWindow, selectLayout, selectPane, getPaneOption, } from './tmux.js';
-import { newNodeId, rootOfSpine } from './nodes.js';
+import { paneExists, paneLocation, ensureSession, openNodeWindow, splitWindow, closePane, currentTmux, switchClient, selectWindow, selectLayout, selectPane, getPaneOption, setPaneOption, respawnPaneSync, windowOfPane, renameWindow, } from './tmux.js';
+import { newNodeId } from './nodes.js';
 import { viewSocketPath } from '../canvas/paths.js';
 import { isPidAlive } from '../canvas/pid.js';
 // Placement is the sanctioned model-over-driver (§2.1): non-placement runtime /
@@ -61,8 +61,7 @@ installTmuxBindings as installMenuBinding, setPaneOption, getPaneOption, piComma
 //
 // GC is lazy on read: a row whose viewer pane no longer exists (the user closed
 // the window, the attach client died) is pruned the next time it is read, so the
-// registry self-heals without a sweeper. (graphSurfaceTarget stays pure — no
-// tmux probe — by design; its caller liveness-checks the pane it returns.)
+// registry self-heals without a sweeper.
 // ---------------------------------------------------------------------------
 /** Prune a viewer row whose pane is gone; return it iff its pane is still live. */
 function liveOrPrune(f) {
@@ -100,27 +99,6 @@ export function listFocuses() {
     return live;
 }
 // ---------------------------------------------------------------------------
-// Graph → viewer routing (for surfacing human-in-the-loop prompts)
-// ---------------------------------------------------------------------------
-/** 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 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 function graphSurfaceTarget(nodeId) {
-    const root = rootOfSpine(nodeId);
-    for (const id of [root, ...view(root)]) {
-        const f = getFocusByNode(id);
-        if (f !== null && f.pane !== null)
-            return f;
-    }
-    return null;
-}
-// ---------------------------------------------------------------------------
 // view.sock readiness — the one shared broker-cold-start primitive
 // ---------------------------------------------------------------------------
 const BROKER_FOCUS_SOCKET_WAIT_MS = 30_000;
@@ -311,6 +289,45 @@ export async function focus(nodeId, opts) {
     // split pane's location — the caller's own session.
     const callerSession = paneLocation(callerPane)?.session ?? null;
     const fallbackSession = callerSession ?? '';
+    // (b0) --in-place → the CALLER pane BECOMES this node's viewer, replacing
+    //      whatever it showed (the attach subagent scroll+swap: ↓ into the reports
+    //      roster, Enter dives into that child right here, no new split). This
+    //      re-execs the caller pane via `respawn-pane -k`, so it MUST be driven
+    //      from OUTSIDE that pane's process tree (the viewer shells this through
+    //      `tmux run-shell`, never a direct child) — else the respawn kills its own
+    //      driver mid-call. Move the child's viewer here if it had one elsewhere
+    //      (UNIQUE one-viewer-per-node) and drop the caller pane's prior viewer row
+    //      (that node's broker keeps running headless, reconnectable by a later
+    //      focus). The respawned `crtr surface attach` replays scrollback from the
+    //      welcome snapshot and self-tags the pane `@crtr_node`.
+    if (opts.inPlace === true) {
+        const prior = focusOf(nodeId);
+        if (prior !== null) {
+            if (prior.pane !== null && prior.pane !== callerPane && paneExists(prior.pane))
+                closePane(prior.pane);
+            closeFocusRow(prior.focus_id);
+        }
+        const here = getFocusByPane(callerPane);
+        if (here !== null && here.node_id !== nodeId)
+            closeFocusRow(here.focus_id);
+        // Clear the stale tag before respawn so it never names the wrong node during
+        // the gap before the fresh attach re-tags on connect.
+        try {
+            setPaneOption(callerPane, '@crtr_node', '');
+        }
+        catch { /* best-effort */ }
+        const window = windowOfPane(callerPane);
+        // Continuity: the fresh viewer re-enters the inline roster on the node just
+        // swapped to (self), so the user keeps scrolling from where they were rather
+        // than being dropped back into the text box.
+        const ok = respawnPaneSync({ pane: callerPane, cwd: meta.cwd, env: { ...viewerSplitEnv(), CRTR_ATTACH_ROSTER: '1' }, command: `crtr surface attach to ${nodeId}` });
+        if (ok) {
+            if (window !== null)
+                renameWindow(window, fullName(meta));
+            registerViewerFocus(nodeId, callerPane, callerSession, window);
+        }
+        return { focused: ok, session: callerSession, inPlace: true, revived };
+    }
     // (b) --new-pane → always a fresh viewer beside the caller. Drop any prior
     //     viewer this node holds elsewhere (UNIQUE(node_id): one viewer per node).
     if (opts.newPane === true) {

package/dist/core/runtime/session-list-cache.d.ts

@@ -7,7 +7,13 @@ export declare function compactSessionSearchText(text: string): string;
 export declare class SessionListCache {
     private readonly cacheFile;
     private cache;
-    private loaded;
+    /** In-flight cwd scans keyed by normalized session dir, so an immediate
+     *  /resume that races the background prewarm (or a second identical open)
+     *  shares the one running jsonlFiles/stat/build pass instead of queueing a
+     *  redundant one behind it. */
+    private inflightDir;
+    private loadPromise;
+    private buildChain;
     private persisting;
     private persistAgain;
     private persistTimer;
@@ -18,12 +24,26 @@ export declare class SessionListCache {
      *  broker loop — pre-warming beats worker threads here. Errors are swallowed
      *  by the same paths that guard a normal open. */
     prewarm(sessionDir: string): void;
-    /** Sessions for one cwd's session dir (the picker's default `cwd` scope). */
+    /** Sessions for one cwd's session dir (the picker's default `cwd` scope).
+     *  Single-flight: an identical concurrent cwd open (prewarm ⇄ immediate
+     *  /resume) shares the in-flight promise rather than repeating the scan.
+     *  Incompatible cwd/all builds still serialize through the build chain. */
     listDir(sessionDir: string): Promise<WireSessionInfo[]>;
+    private buildDir;
     /** Sessions across every cwd's dir under the sessions root (`all` scope). */
     listAll(sessionsRoot: string): Promise<WireSessionInfo[]>;
+    /** Serialize builds through a single chain: they mutate the shared cache map
+     *  and, cold, scan the same large corpus. Identical cwd opens are already
+     *  collapsed upstream by `listDir`'s in-flight sharing; chaining serializes
+     *  the remaining incompatible builds (a cwd scan vs an `all` scan) so they
+     *  never race map mutation or launch overlapping cold scans. */
     private build;
+    private buildLocked;
+    /** Load the persisted cache exactly once, single-flight. Returns a shared
+     *  promise so a build that starts while the read is still in flight awaits the
+     *  same load rather than proceeding against a not-yet-populated map. */
     private ensureLoaded;
+    private loadFromDisk;
     /** Coalesce persists onto a single trailing timer so the tens-of-MB
      *  `JSON.stringify` never runs on the reply path and rapid opens write once. */
     private schedulePersist;

package/dist/core/runtime/session-list-cache.js

@@ -19,7 +19,7 @@
 import { createReadStream } from 'node:fs';
 import { readFile, readdir, rename, stat, unlink, writeFile } from 'node:fs/promises';
 import { createInterface } from 'node:readline';
-import { dirname, join } from 'node:path';
+import { dirname, join, normalize } from 'node:path';
 /** Search-text bound: `allMessagesText` is searched on every query edit; pi's
  *  unbounded value retains gigabytes in the viewer and turns key-repeat into GC
  *  jitter. The opening and latest text keep search useful. */
@@ -41,18 +41,41 @@ const CACHE_SCHEMA_VERSION = 1;
  *  are coalesced onto this trailing timer so rapid opens write at most once per
  *  window, off the hot path. */
 const PERSIST_DEBOUNCE_MS = 2000;
+function isFiniteNonNeg(v) {
+    return typeof v === 'number' && Number.isFinite(v) && v >= 0;
+}
+/** An optional field is valid iff absent/undefined or a string. */
+function isOptionalString(v) {
+    return v === undefined || typeof v === 'string';
+}
+/** Validate the full persisted `WireSessionInfo` shape. A same-version file whose
+ *  entry drifts from the current wire schema (any required field missing or
+ *  mistyped, any optional field the wrong type, non-finite/negative metadata)
+ *  must discard the whole cache and rebuild rather than feed a malformed entry to
+ *  the viewer or the sort. */
+function isValidWireInfo(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const i = v;
+    return (typeof i['path'] === 'string' &&
+        typeof i['id'] === 'string' &&
+        typeof i['cwd'] === 'string' &&
+        typeof i['created'] === 'string' &&
+        typeof i['modified'] === 'string' &&
+        isFiniteNonNeg(i['messageCount']) &&
+        typeof i['firstMessage'] === 'string' &&
+        typeof i['allMessagesText'] === 'string' &&
+        isOptionalString(i['name']) &&
+        isOptionalString(i['parentSessionPath']));
+}
 /** Shape-check a loaded entry — a well-formed-JSON file with the right version
- *  but a stale entry shape (e.g. missing `info`) would otherwise push undefined
- *  into the sort and throw. Any failure discards the whole file (rebuild). */
+ *  but a stale entry shape would otherwise feed a malformed `WireSessionInfo` to
+ *  the viewer/sort. Any failure discards the whole file (rebuild). */
 function isValidEntry(e) {
     if (typeof e !== 'object' || e === null)
         return false;
     const c = e;
-    return (typeof c['mtimeMs'] === 'number' &&
-        typeof c['size'] === 'number' &&
-        typeof c['info'] === 'object' &&
-        c['info'] !== null &&
-        typeof c['info']['modified'] === 'string');
+    return isFiniteNonNeg(c['mtimeMs']) && isFiniteNonNeg(c['size']) && isValidWireInfo(c['info']);
 }
 // ---- faithful mirror of pi's private buildSessionInfo -----------------------
 function parseLine(line) {
@@ -172,7 +195,13 @@ async function buildWireSessionInfo(filePath) {
 export class SessionListCache {
     cacheFile;
     cache = new Map();
-    loaded = false;
+    /** In-flight cwd scans keyed by normalized session dir, so an immediate
+     *  /resume that races the background prewarm (or a second identical open)
+     *  shares the one running jsonlFiles/stat/build pass instead of queueing a
+     *  redundant one behind it. */
+    inflightDir = new Map();
+    loadPromise = null;
+    buildChain = Promise.resolve();
     persisting = false;
     persistAgain = false;
     persistTimer = null;
@@ -187,9 +216,32 @@ export class SessionListCache {
     prewarm(sessionDir) {
         void this.listDir(sessionDir);
     }
-    /** Sessions for one cwd's session dir (the picker's default `cwd` scope). */
-    async listDir(sessionDir) {
-        return this.build(await jsonlFiles(sessionDir), new Set([sessionDir]));
+    /** Sessions for one cwd's session dir (the picker's default `cwd` scope).
+     *  Single-flight: an identical concurrent cwd open (prewarm ⇄ immediate
+     *  /resume) shares the in-flight promise rather than repeating the scan.
+     *  Incompatible cwd/all builds still serialize through the build chain. */
+    listDir(sessionDir) {
+        const key = normalize(sessionDir);
+        const existing = this.inflightDir.get(key);
+        if (existing)
+            return existing;
+        const op = this.buildDir(key);
+        this.inflightDir.set(key, op);
+        // Attach both settlement handlers so the slot is cleared on success OR
+        // rejection, a rejected scan can never poison the next open, and a
+        // discarded prewarm rejection never becomes unhandled.
+        const clear = () => {
+            if (this.inflightDir.get(key) === op)
+                this.inflightDir.delete(key);
+        };
+        op.then(clear, clear);
+        return op;
+    }
+    buildDir(sessionDir) {
+        // Prune only keys directly in this cwd's dir. A cwd-scope open must not evict
+        // other cwds' cached entries: they weren't rescanned, so their absence from
+        // `files` says nothing about whether they still exist on disk.
+        return jsonlFiles(sessionDir).then((files) => this.build(files, (key) => dirname(key) === sessionDir));
     }
     /** Sessions across every cwd's dir under the sessions root (`all` scope). */
     async listAll(sessionsRoot) {
@@ -205,19 +257,30 @@ export class SessionListCache {
         const files = [];
         for (const dir of dirEntries)
             files.push(...(await jsonlFiles(dir)));
-        return this.build(files, new Set(dirEntries));
+        // Prune every cached key that is a direct grandchild of the sessions root
+        // (`<root>/<cwd-dir>/<file>.jsonl`). Using the path boundary rather than the
+        // set of dirs that still exist means a wholly-deleted cwd dir — absent from
+        // this scan — also has its stale entries evicted, so the persisted file never
+        // accumulates bloat from removed cwds.
+        return this.build(files, (key) => dirname(dirname(key)) === sessionsRoot);
+    }
+    /** Serialize builds through a single chain: they mutate the shared cache map
+     *  and, cold, scan the same large corpus. Identical cwd opens are already
+     *  collapsed upstream by `listDir`'s in-flight sharing; chaining serializes
+     *  the remaining incompatible builds (a cwd scan vs an `all` scan) so they
+     *  never race map mutation or launch overlapping cold scans. */
+    build(files, shouldPrune) {
+        const run = this.buildChain.then(() => this.buildLocked(files, shouldPrune));
+        // Keep the chain alive past a rejected build without leaking the rejection.
+        this.buildChain = run.then(() => { }, () => { });
+        return run;
     }
-    async build(files, scannedDirs) {
+    async buildLocked(files, shouldPrune) {
         await this.ensureLoaded();
         const present = new Set(files);
         let changed = false;
-        // Prune ONLY keys under the dirs we actually scanned. A cwd-scope open must
-        // not evict other cwds' cached entries: they weren't rescanned, so their
-        // absence from `files` says nothing about whether they still exist on disk.
-        // (Pruning the whole map here would self-destruct the global/`all` cache on
-        // every cwd open.)
         for (const key of this.cache.keys()) {
-            if (!present.has(key) && scannedDirs.has(dirname(key))) {
+            if (!present.has(key) && shouldPrune(key)) {
                 this.cache.delete(key);
                 changed = true;
             }
@@ -262,10 +325,15 @@ export class SessionListCache {
         result.sort((a, b) => new Date(b.modified).getTime() - new Date(a.modified).getTime());
         return result;
     }
-    async ensureLoaded() {
-        if (this.loaded)
-            return;
-        this.loaded = true;
+    /** Load the persisted cache exactly once, single-flight. Returns a shared
+     *  promise so a build that starts while the read is still in flight awaits the
+     *  same load rather than proceeding against a not-yet-populated map. */
+    ensureLoaded() {
+        if (!this.loadPromise)
+            this.loadPromise = this.loadFromDisk();
+        return this.loadPromise;
+    }
+    async loadFromDisk() {
         try {
             const raw = JSON.parse(await readFile(this.cacheFile, 'utf8'));
             // Version mismatch or shape drift → discard and rebuild. No lenient

package/dist/core/runtime/spawn.js

@@ -24,6 +24,7 @@ import { appendSituationalContext } from './situational-context.js';
 import { hasRoadmap, seedRoadmap } from './roadmap.js';
 import { buildIdentityAssertion, buildWakeBearings } from './bearings.js';
 import { installTmuxBindings } from './tmux-chrome.js';
+import { installInboxBinding } from '@crouton-kit/humanloop';
 import { getNode, fullName, recordPid } from '../canvas/index.js';
 import { registerViewerFocus, openViewerWindow, waitForBrokerViewSocket, viewerSplitEnv, windowOfPane, currentTmux, inTmux, focusWindow, } from './placement.js';
 import { transition } from './lifecycle.js';
@@ -102,6 +103,14 @@ export async function bootRoot(opts) {
         installTmuxBindings();
     }
     catch { /* best-effort */ }
+    // Reconcile humanloop's collision-safe M-i inbox popup binding on the same
+    // server so the inbox is reachable from any window. Crouter calls humanloop's
+    // installer — it never authors or parses its own tmux command; the installer
+    // is idempotent and leaves any pre-existing M-i binding untouched.
+    try {
+        installInboxBinding();
+    }
+    catch { /* best-effort */ }
     // This terminal becomes the root's attach VIEWER in the user's CURRENT session,
     // so its window stays where the user already is. The node row carries NO
     // presence — a broker node's pane/window/tmux_session stay NULL; the viewer

package/dist/core/spawn.d.ts

@@ -14,62 +14,3 @@ export declare function isInTmux(): boolean;
  *  degrade to the inbox-drain follow-up. */
 export declare function tmuxServerReachable(): boolean;
 export declare function shellQuote(s: string): string;
-/** Count panes in a tmux window (0 outside tmux / on error). With `targetPane`,
- *  counts the window THAT pane lives in (the placement decision must reflect the
- *  window the new pane will actually open into, not the caller's backstage one);
- *  without it, the caller's current window. */
-export declare function countPanesInWindow(targetPane?: string): number;
-/** Back-compat alias: panes in the caller's current window. */
-export declare function countPanesInCurrentWindow(): number;
-/** Does this tmux pane id still exist? `display-message` EXITS 0 with EMPTY
- *  output on an unresolvable pane, so test for non-empty stdout, not just `.ok`.
- *  False outside tmux / on error. */
-export declare function paneAlive(pane: string): boolean;
-/** Resolve a tmux pane id to its `session:window_index` — the target form
- *  `new-window -t` accepts. tmux REJECTS a pane id for new-window ("can't
- *  specify pane here"); only split-window -t takes a pane. null outside tmux /
- *  on a bad pane id / on error / empty. */
-export declare function paneWindowTarget(pane: string): string | null;
-/** The active pane of the user's attached tmux client — where they are looking
- *  right now. `list-clients` first attached client, then its current pane. Used
- *  to surface a human prompt in the user's view when nothing in the asking
- *  node's graph is focused. null outside tmux / no client / on error. */
-export declare function attachedClientPane(): string | null;
-/**
- * Schedule a kill-pane on the *current* tmux pane after `delaySeconds`, detached
- * so the caller can return normally before the pane dies. No-op outside tmux,
- * when TMUX_PANE is unset, or when delaySeconds <= 0.
- */
-export declare function scheduleKillCurrentPane(delaySeconds: number): boolean;
-export interface DetachOptions {
-    /** Inner command to run in the new pane. */
-    command: string;
-    cwd: string;
-    /** Optional id injected as the CRTR_JOB_ID env var in the pane. */
-    jobId?: string;
-    /** Where to open the new pane. */
-    placement: 'split-h' | 'split-v' | 'new-window';
-    /** Seconds before killing the originating pane so the caller can finish. */
-    killAfterSeconds: number;
-    /** Pin the new pane to this tmux pane: split-window splits it; new-window is
-     *  inserted immediately after its window (-a -t <pane>). Without this, tmux
-     *  uses the attached client's currently-focused pane — which drifts if the
-     *  user switches windows between kickoff and spawn. */
-    targetPane?: string;
-    /** Pass tmux `-d` to new-window so CREATING the window never switches the
-     *  attached client to it (split-window already leaves the client's view put).
-     *  The prompt lands in the target session/window without jumping the user out
-     *  of what they are looking at. No effect on split-h/split-v. */
-    detached?: boolean;
-}
-export interface DetachResult {
-    status: 'spawned' | 'spawn-failed' | 'not-in-tmux';
-    paneId?: string;
-    message: string;
-}
-/**
- * Fire-and-forget: launch `opts.command` in a new pane (or window), then
- * schedule the originating pane to be killed after `killAfterSeconds`. Returns
- * as soon as the new pane is up; does NOT wait for the command to finish.
- */
-export declare function spawnAndDetach(opts: DetachOptions): DetachResult;

package/dist/core/spawn.js

@@ -1,11 +1,9 @@
-// Tmux pane detach helpers.
+// Tmux reachability + quoting helpers for the `human` command tree.
 //
-// A small set of tmux primitives used by the `human` command tree to put the
-// humanloop TUI in a detached pane: spawnAndDetach (open a pane running a given
-// command), countPanesInCurrentWindow (placement decision), plus shellQuote and
-// tmuxServerReachable. The canvas runtime has its own one-window-per-node
-// machinery in core/runtime/tmux.ts; this module is only the pane-split path the
-// human TUI needs.
+// The human surface gates on whether the canvas tmux server is reachable
+// (tmuxServerReachable) so it can decide whether to surface a prompt or degrade
+// to the inbox-drain follow-up. The canvas runtime has its own
+// one-window-per-node machinery in core/runtime/tmux.ts.
 import { spawnSync } from 'node:child_process';
 /** Does THIS process sit inside a tmux client (its own $TMUX is set)? NOT the
  *  gate for the human surface — see tmuxServerReachable. A headless-broker child
@@ -30,159 +28,3 @@ export function tmuxServerReachable() {
 export function shellQuote(s) {
     return `'${s.replace(/'/g, "'\\''")}'`;
 }
-/** Count panes in a tmux window (0 outside tmux / on error). With `targetPane`,
- *  counts the window THAT pane lives in (the placement decision must reflect the
- *  window the new pane will actually open into, not the caller's backstage one);
- *  without it, the caller's current window. */
-export function countPanesInWindow(targetPane) {
-    const args = targetPane !== undefined && targetPane !== ''
-        ? ['list-panes', '-t', targetPane, '-F', '#{pane_id}']
-        : ['list-panes', '-F', '#{pane_id}'];
-    const result = spawnSync('tmux', args, { encoding: 'utf8' });
-    if (result.status !== 0)
-        return 0;
-    return result.stdout.split('\n').filter((line) => line.trim() !== '').length;
-}
-/** Back-compat alias: panes in the caller's current window. */
-export function countPanesInCurrentWindow() {
-    return countPanesInWindow();
-}
-/** Does this tmux pane id still exist? `display-message` EXITS 0 with EMPTY
- *  output on an unresolvable pane, so test for non-empty stdout, not just `.ok`.
- *  False outside tmux / on error. */
-export function paneAlive(pane) {
-    if (!/^%\d+$/.test(pane))
-        return false;
-    const r = spawnSync('tmux', ['display-message', '-p', '-t', pane, '#{pane_id}'], {
-        encoding: 'utf8',
-    });
-    return r.status === 0 && r.stdout.trim() !== '';
-}
-/** Resolve a tmux pane id to its `session:window_index` — the target form
- *  `new-window -t` accepts. tmux REJECTS a pane id for new-window ("can't
- *  specify pane here"); only split-window -t takes a pane. null outside tmux /
- *  on a bad pane id / on error / empty. */
-export function paneWindowTarget(pane) {
-    if (!/^%\d+$/.test(pane))
-        return null;
-    const r = spawnSync('tmux', ['display-message', '-p', '-t', pane, '#{session_name}:#{window_index}'], { encoding: 'utf8' });
-    if (r.status !== 0)
-        return null;
-    const t = r.stdout.trim();
-    return t !== '' ? t : null;
-}
-/** The active pane of the user's attached tmux client — where they are looking
- *  right now. `list-clients` first attached client, then its current pane. Used
- *  to surface a human prompt in the user's view when nothing in the asking
- *  node's graph is focused. null outside tmux / no client / on error. */
-export function attachedClientPane() {
-    const clients = spawnSync('tmux', ['list-clients', '-F', '#{client_name}'], {
-        encoding: 'utf8',
-    });
-    if (clients.status !== 0)
-        return null;
-    const name = clients.stdout
-        .split('\n')
-        .map((l) => l.trim())
-        .find((l) => l !== '');
-    if (name === undefined)
-        return null;
-    const pane = spawnSync('tmux', ['display-message', '-p', '-c', name, '#{pane_id}'], {
-        encoding: 'utf8',
-    });
-    if (pane.status !== 0)
-        return null;
-    const id = pane.stdout.trim();
-    return id !== '' ? id : null;
-}
-/**
- * Schedule a kill-pane on the *current* tmux pane after `delaySeconds`, detached
- * so the caller can return normally before the pane dies. No-op outside tmux,
- * when TMUX_PANE is unset, or when delaySeconds <= 0.
- */
-export function scheduleKillCurrentPane(delaySeconds) {
-    const currentPane = process.env.TMUX_PANE;
-    if (currentPane === undefined || currentPane === '' || delaySeconds <= 0) {
-        return false;
-    }
-    const killCmd = `sleep ${delaySeconds}; tmux kill-pane -t ${currentPane}`;
-    spawnSync('sh', ['-c', `nohup sh -c ${shellQuote(killCmd)} </dev/null >/dev/null 2>&1 &`], {
-        stdio: 'ignore',
-    });
-    return true;
-}
-/**
- * Fire-and-forget: launch `opts.command` in a new pane (or window), then
- * schedule the originating pane to be killed after `killAfterSeconds`. Returns
- * as soon as the new pane is up; does NOT wait for the command to finish.
- */
-export function spawnAndDetach(opts) {
-    // Gate on the CANVAS tmux server's reachability, NOT the caller's $TMUX. A
-    // headless-broker child strips its own $TMUX (broker.ts) but the canvas server
-    // is on the default socket, so `split-window -t <pane>` against a resolved
-    // target pane (resolveHumanTarget) works fine from it. Only a genuine
-    // no-server case degrades to the inbox-drain follow-up.
-    if (!tmuxServerReachable()) {
-        return {
-            status: 'not-in-tmux',
-            message: 'handoff requires a reachable tmux server',
-        };
-    }
-    const splitArgs = [];
-    if (opts.placement === 'new-window') {
-        splitArgs.push('new-window');
-        if (opts.detached === true)
-            splitArgs.push('-d'); // don't switch the client to it
-        if (opts.targetPane !== undefined && opts.targetPane !== '') {
-            // new-window -t REJECTS a pane id (tmux exits 1: "can't specify pane
-            // here") — only split-window -t accepts a pane. Resolve the target pane to
-            // its session:window first; -a then inserts the new window right after it.
-            // If the pane can't be resolved, fall back to no -t (tmux uses current).
-            const winTarget = paneWindowTarget(opts.targetPane);
-            if (winTarget !== null)
-                splitArgs.push('-a', '-t', winTarget);
-        }
-    }
-    else {
-        splitArgs.push('split-window');
-        splitArgs.push(opts.placement === 'split-h' ? '-h' : '-v');
-        if (opts.targetPane !== undefined && opts.targetPane !== '') {
-            splitArgs.push('-t', opts.targetPane);
-        }
-    }
-    splitArgs.push('-P', '-F', '#{pane_id}');
-    splitArgs.push('-c', opts.cwd);
-    if (opts.jobId !== undefined) {
-        splitArgs.push('-e', `CRTR_JOB_ID=${opts.jobId}`);
-    }
-    splitArgs.push(opts.command);
-    const split = spawnSync('tmux', splitArgs, { encoding: 'utf8' });
-    if (split.status !== 0) {
-        const stderrText = split.stderr.trim();
-        const msg = stderrText === '' ? 'tmux split-window/new-window failed' : stderrText;
-        return { status: 'spawn-failed', message: msg };
-    }
-    const paneId = split.stdout.trim();
-    // Force `remain-on-exit off` at PANE scope on the new pane. remain-on-exit is
-    // a pane option (tmux 3.x) inherited from the window-scoped value, and the
-    // canvas runtime arms `remain-on-exit on` on a node's vehicle/focus WINDOW
-    // (F3 freeze, see runtime/tmux.ts setRemainOnExit). A split-window pane opened
-    // into that window inherits the `on`, so the humanloop TUI pane would linger
-    // as a dead pane ("pane is dead (status 0, …)") when `crtr human _run` exits 0
-    // instead of closing. Overriding at pane scope destroys this pane on clean
-    // exit WITHOUT touching the window's value (focus freeze still works) or the
-    // user's global config. Best-effort: harmless no-op on tmux where the option
-    // is window-only.
-    if (paneId !== '') {
-        spawnSync('tmux', ['set-option', '-p', '-t', paneId, 'remain-on-exit', 'off'], {
-            stdio: 'ignore',
-        });
-    }
-    // Schedule self-kill of the originating pane.
-    scheduleKillCurrentPane(opts.killAfterSeconds);
-    return {
-        status: 'spawned',
-        paneId,
-        message: `handed off to pane ${paneId}`,
-    };
-}

package/dist/daemon/crtrd.js

@@ -1205,8 +1205,8 @@ function reapDeadResidue(now) {
  *  row when its pane dies outside the sanctioned teardown paths (a user
  *  kill-pane, a tmux server restart, a crashed swap), so dead-pane rows
  *  accumulate forever — the audit found 15 of 21 rows pointing at gone panes,
- *  and a stale row both lies to graphSurfaceTarget and blocks its node from
- *  being adopted into a fresh viewport (UNIQUE node_id). Sweep them here: one
+ *  and a stale row both misreports the node's on-screen viewer and blocks its
+ *  node from being adopted into a fresh viewport (UNIQUE node_id). Sweep them here: one
  *  batched `list-panes -a` probe (never a per-row display-message), deleting
  *  rows whose recorded pane no longer exists. A pane-less row (a bridge/unplaced
  *  viewport) has nothing to verify and is left alone. On a FAILED probe (tmux
@@ -1294,10 +1294,11 @@ export async function superviseTick(now = Date.now()) {
         return;
     }
     // kind:'human' rows are NOT broker-hosted agent nodes — they are bookkeeping
-    // rows for the `crtr human` bridge. The decision/review TUI runs in a detached
-    // `crtr human _run` pane (NOT a pi engine), and the row's lifecycle is driven
-    // entirely by that worker's `pushFinal` (or `human cancel`). They never record
-    // a `pi_pid` or `pi_session_id`, so the universal broker-liveness path would
+    // rows for the `crtr human` bridge. Their lifecycle is driven entirely by
+    // humanloop's registered `_deliver` handler — which pushFinals the answer when
+    // the human responds from the humanloop inbox — or by `human cancel`. They
+    // never record a `pi_pid` or `pi_session_id`, so the universal broker-liveness
+    // path would
     // (after the boot grace) read every one as a never-booted broker and crash it
     // with surfaceBootFailure — exactly the regression where a headless
     // orchestrator's `human ask` nodes all died at boot. The daemon must never

package/dist/index.d.ts

@@ -10,8 +10,8 @@ export { appendSituationalContext } from './core/runtime/situational-context.js'
 export { getNode, listNodes } from './core/canvas/canvas.js';
 export { nodeDir } from './core/canvas/paths.js';
 export type { NodeMeta, NodeRow, NodeStatus, Lifecycle, Mode, } from './core/canvas/types.js';
-export { asksForNodes, asksAcrossCanvas } from './core/canvas/attention.js';
-export type { AskEntry } from './core/canvas/attention.js';
+export { ticketCountsForNodes, ticketsAcrossCanvas } from './core/canvas/attention.js';
+export type { TicketEntry } from './core/canvas/attention.js';
 export { readTelemetry, readContextTokens } from './core/canvas/telemetry.js';
 export type { Telemetry } from './core/canvas/telemetry.js';
 export { ViewSocketClient, BrokerUnavailableError } from './clients/attach/view-socket.js';

package/dist/index.js

@@ -23,7 +23,7 @@ export { appendSituationalContext } from './core/runtime/situational-context.js'
 // ── Canvas reads ─────────────────────────────────────────────────────────
 export { getNode, listNodes } from './core/canvas/canvas.js';
 export { nodeDir } from './core/canvas/paths.js';
-export { asksForNodes, asksAcrossCanvas } from './core/canvas/attention.js';
+export { ticketCountsForNodes, ticketsAcrossCanvas } from './core/canvas/attention.js';
 export { readTelemetry, readContextTokens } from './core/canvas/telemetry.js';
 // ── Broker client ────────────────────────────────────────────────────────
 export { ViewSocketClient, BrokerUnavailableError } from './clients/attach/view-socket.js';