@crouton-kit/crouter 0.3.82 → 0.3.84

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

@@ -56,7 +56,7 @@ import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { crtrHome, nodeDir, jobDir } from '../core/canvas/paths.js';
-import { listNodes, getRow, getNode, dueClockTriggers, consumeTrigger, advanceTrigger, listFocuses, closeFocusRow, pruneToLimit, subscribersOf, } from '../core/canvas/index.js';
+import { listNodes, getRow, getNode, migrateLegacyPidIdentities, dueClockTriggers, consumeTrigger, advanceTrigger, listFocuses, closeFocusRow, pruneToLimit, subscribersOf, } from '../core/canvas/index.js';
 import { fullName } from '../core/canvas/labels.js';
 import { transition } from '../core/runtime/lifecycle.js';
 import { isBusy, busySince } from '../core/runtime/busy.js';
@@ -65,7 +65,7 @@ import { fanDoctrineWake } from '../core/runtime/close.js';
 import { logger } from '../core/log.js';
 export { FAULT_QUIET_MS };
 import { isPidAlive, isRecordedPidAlive, recordedPidLiveness } from '../core/canvas/pid.js';
-import { reconcileBootLiveness } from '../core/canvas/boot.js';
+import { reconcileAndMigrateBoot } from '../core/canvas/boot.js';
 import { listLivePanes, tearDownNode } from '../core/runtime/placement.js';
 import { reviveNode } from '../core/runtime/revive.js';
 import { isBrokerLive } from '../core/runtime/model-swap.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
@@ -1613,9 +1614,33 @@ export function runDaemon(opts = {}) {
     // "leave it, nothing to revive" and never calls reviveNode at all — a
     // pid-reuse collision on the first post-boot tick would silently no-op
     // forever with no revive attempt to even hit reviveNode's own reconcile call.
-    const { changed, cleared } = reconcileBootLiveness();
-    if (changed) {
-        process.stderr.write(`[crtrd] boot change detected — cleared ${cleared.length} stale pi_pid(s) recorded before this boot\n`);
+    //
+    // Ordering + gate live in reconcileAndMigrateBoot (canvas/boot.ts) so the
+    // migration-gate regression tests exercise the real composition rather than a
+    // test-side copy of these lines.
+    const { reconcile, migrated } = reconcileAndMigrateBoot(migrateLegacyPidIdentities);
+    if (reconcile.changed) {
+        process.stderr.write(`[crtrd] boot change detected — cleared ${reconcile.cleared.length} stale pi_pid(s) recorded before this boot\n`);
+    }
+    // Then, once, complete the boot-scoped-identity format migration for any
+    // broker that survived an in-place crouter upgrade and still carries a legacy
+    // `lstart#ticks` baseline: re-record it as `<bootId>#<ticks>` if its pid still
+    // names the same live process. `identitiesMatch` only TOLERATES legacy rows;
+    // this is what actually closes the cross-boot ticks-collision exposure for
+    // them, so the legacy compare lane then only engages for genuinely no-boot_id
+    // hosts.
+    //
+    // GATED on PROVEN same-boot provenance: the sweep blesses a legacy row's pid
+    // as a current-boot process (`<currentBootId>#<ticks>`) on a ticks match, so
+    // it is correct ONLY when the recorded pid provably belongs to THIS boot. We
+    // run it solely when reconciliation matched an exact kernel `boot_id` on both
+    // sides (`sameBootProven`) — never on a first-ever/absent/malformed marker or
+    // the wall-clock epoch fallback, where an equal-ticks collision with an
+    // unrelated cross-boot process could otherwise baptize a stranger. (On a
+    // detected boot change the prior-boot pids were just cleared, so there is
+    // nothing left to migrate either.)
+    if (migrated.length > 0) {
+        process.stderr.write(`[crtrd] migrated ${migrated.length} legacy pi_pid identity baseline(s) to boot-scoped format\n`);
     }
     writePidfile();
     log.info(`started (pid ${process.pid}, interval ${interval}ms)`);

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';