@north-light/cli 0.0.0-stage → 0.3.413

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

@@ -0,0 +1,314 @@
+import { type AttachBindingId } from '../keybindings/index.js';
+import { shellQuote } from '../../shared/shell-quote.js';
+export { shellQuote };
+declare function tmux(args: string[]): {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+};
+export declare function inTmux(): boolean;
+/** Is any tmux SESSION currently up? `tmux list-sessions` exits 0 iff a server
+ *  is running with at least one session, non-zero otherwise (including "no
+ *  server"). This is the boot-time/bash-tooling probe — distinct from
+ *  `tmuxClientsReachable`, which asks whether a server is reachable at all
+ *  regardless of session count and is the human-surface gate. */
+export declare function tmuxSessionsReachable(): boolean;
+/** Is the tmux SERVER reachable at all? `tmux list-clients` exits 0 whenever a
+ *  server is up (even with zero attached clients), non-zero when no server is
+ *  running. This is the human-surface gate (core/spawn.ts's
+ *  `tmuxServerReachable`) — distinct from `tmuxSessionsReachable`, which
+ *  additionally requires a session to exist. */
+export declare function tmuxClientsReachable(): boolean;
+/** The pane currently displaying `nodeId`, found by the authoritative `@crtr_node`
+ *  pane tag — set by EVERY viewer (a bare `surface attach`, a focus split, a
+ *  spawned viewer) on connect. Scans all panes (`list-panes -a`); the reverse of
+ *  `nodeInPane`. Unlike the focus TABLE (which only `registerViewerFocus` writes,
+ *  so it misses attach-viewed nodes), the tag is on any pane showing the node.
+ *  Returns the pane id, or null when no pane shows it. Works headless (no $TMUX). */
+export declare function paneOfNode(nodeId: string): string | null;
+export interface TmuxLocation {
+    session: string;
+    window: string;
+    pane: string;
+}
+/** Where the caller currently is, or null if not inside tmux. */
+export declare function currentTmux(): TmuxLocation | null;
+/** True when a `tmux` binary runs on PATH. */
+export declare function tmuxAvailable(): boolean;
+/** Run tmux attached to THIS terminal (stdio inherited) — for a foreground
+ *  `new-session`/`attach-session` that hands the terminal to tmux — and return
+ *  its exit status. */
+export declare function tmuxInteractive(args: string[]): number;
+export declare function sessionExists(name: string): boolean;
+/** Create a detached session rooted at `cwd` if it doesn't exist. The session
+ *  name is a root's tmux home; every node under that root is a window in it. */
+export declare function ensureSession(name: string, cwd: string): void;
+export interface OpenWindowOpts {
+    session: string;
+    /** Window name (the node's display name). */
+    name: string;
+    cwd: string;
+    env: Record<string, string>;
+    /** The full command to run in the window (already a shell string). */
+    command: string;
+}
+/** Open a background window for a node and run `command` in it. `-d` keeps it
+ *  detached so it doesn't steal focus or become the current window. Returns the
+ *  new window id AND the pane id it created (the durable `%pane_id`, LOCATION's
+ *  anchor) — callers that only need the window destructure `.window`.
+ *
+ *  Target is `${session}:` (trailing colon = the session, no window index) plus
+ *  `-a` (insert after the current window) so tmux allocates the next free index.
+ *  Passing a bare session name resolves to the session's *active window*, which
+ *  makes new-window try to create AT that occupied index and fail with
+ *  "create window failed: index N in use" whenever the active window is not the
+ *  last one (common when base-index is 0 but the live window sits at index 1).
+ *  `-a` also keeps node windows off index 0, which is reserved for the optional
+ *  dashboard. The explicit `-t ${session}:` target is the §2.2 HARD DRIVER
+ *  INVARIANT — never let new-window fall back to tmux's global current session. */
+export declare function openNodeWindow(opts: OpenWindowOpts): {
+    window: string;
+    pane: string;
+} | null;
+export interface SplitWindowOpts {
+    cwd: string;
+    env: Record<string, string>;
+    /** The full command to run in the new pane (already a shell string). */
+    command: string;
+    /** Stack the new pane below instead of beside (default: beside, `-h`). */
+    vertical?: boolean;
+    /** Place the new pane BEFORE the target (left for `-h`, above for `-v`) via
+     *  `-b`, instead of after it (default: after — right/below). */
+    before?: boolean;
+    /** Fixed size of the new pane in the split axis' cells (columns for `-h`, rows
+     *  for `-v`) via `-l`. Omit ⇒ tmux's default even split. */
+    size?: number;
+}
+/** Split `targetPane`'s window, opening a NEW pane beside it running `command`,
+ *  and return the new pane id (the durable `%id`). The ONLY new-pane-beside verb
+ *  (Q3: a focus opened side-by-side). `-d` keeps the caller's pane active; `-h`
+ *  makes the split side-by-side (left/right), the default for a focus viewport.
+ *
+ *  §2.2 HARD DRIVER INVARIANT: `targetPane` is REQUIRED — a bare `split-window`
+ *  would split tmux's global current pane, which can leak a pane into an
+ *  unrelated user session (the exact bug this design kills). The explicit
+ *  `-t <targetPane>` makes the destination structurally un-leakable. Returns
+ *  null if tmux fails. */
+export declare function splitWindow(targetPane: string, opts: SplitWindowOpts): string | null;
+/** Bring a node's window forefront. Switches client across roots when needed. */
+export declare function focusWindow(session: string, window: string): boolean;
+/** Close a node's window (drop it from the UI). */
+export declare function closeWindow(window: string): boolean;
+/** Rename a window (`tmux rename-window -t <window> <name>`). Used by the
+ *  root relaunch to re-title the viewer window when its pane is re-pointed at
+ *  the freshly-minted node. Best-effort; false if tmux fails. */
+export declare function renameWindow(window: string, name: string): boolean;
+/** Break a single PANE out into a BRAND-NEW window of its own (`tmux break-pane
+ *  -d`). `-d` keeps the new window in the background (does not switch the client
+ *  to it); `-s <pane>` names the source pane — the §2.2 HARD DRIVER INVARIANT, so
+ *  the break never falls back to tmux's global current pane. The pane keeps its
+ *  durable `%id` across the move (only its window changes), so callers can keep
+ *  using the same pane handle. Returns the new `{window, pane}` location, or null
+ *  if tmux fails. Used by `surface tmux-spread` to lift the caller's viewer into a
+ *  fresh window before tiling sibling viewers beside it. */
+export declare function breakPane(pane: string): {
+    window: string;
+    pane: string;
+} | null;
+/** Close a single PANE. Its window closes automatically once this was the last
+ *  pane, but sibling panes survive — so co-located nodes (several agents sharing
+ *  one window via swap-pane focus) are torn down one at a time instead of all
+ *  at once by a window kill. Pane ids are the stable vehicle handle; windows
+ *  shift under swap-pane focus, so pane-granular teardown is the correct unit. */
+export declare function closePane(pane: string): boolean;
+/** Open a command in a tmux popup anchored to a pane. The command is a shell
+ * string because tmux executes popup payloads through the user's shell. */
+export declare function displayPopup(pane: string, cwd: string, command: string): boolean;
+/** `displayPopup` without blocking the event loop. tmux holds `display-popup -E`
+ *  open until the popup closes, so an interactive process (the attach viewer)
+ *  that opens one in-process must not wait on it synchronously. */
+export declare function displayPopupAsync(pane: string, cwd: string, command: string): Promise<boolean>;
+/** The active pane id of a window. Node windows are single-pane, so this is the
+ *  node's pane. Returns null if the window is gone or tmux fails. */
+export declare function paneOfWindow(session: string, window: string): string | null;
+/** The window a pane currently lives in. Used after a swap-pane to learn which
+ *  slot the caller's pane occupied — pane ids are stable across swaps, windows
+ *  are not, so the node→window mapping must be re-derived from the pane. Returns
+ *  null if the pane is gone or tmux fails. */
+export declare function windowOfPane(pane: string): string | null;
+/** The session + window a pane currently lives in (`display-message -p -t %id`).
+ *  The §2.4 reconciliation read-back: resolve a node's/focus's CURRENT
+ *  window/session from its durable pane id before any act, so crtr follows a
+ *  manual `move-pane`/`join-pane`/`break-pane` instead of fighting it. Null if
+ *  the pane is gone or tmux fails. */
+export declare function paneLocation(pane: string): {
+    session: string;
+    window: string;
+} | null;
+/** The index tmux shows for a window target (`#{window_index}`) — the number a
+ *  person sees in the status line and presses after the prefix. Null if the
+ *  target is gone or tmux fails. */
+export declare function windowIndex(target: string): number | null;
+/** Does this pane id still exist? A `display-message` probe on the `%id` — the
+ *  v3 PRIMARY liveness probe (§1.2/§2.2), replacing window-existence so a user
+ *  moving a pane to another window/session never reads as "gone". True iff tmux
+ *  knows the pane.
+ *
+ *  NOTE: `display-message -p -t <gone-pane>` EXITS 0 with EMPTY output (it does
+ *  not error on an unresolvable pane target) — so an `.ok` check alone would
+ *  report a dead pane as alive, defeating the whole point of pane-existence
+ *  liveness. We therefore require the echoed `#{pane_id}` to equal the requested
+ *  pane: a live pane echoes its own id, a gone/bogus one yields empty. */
+export declare function paneExists(pane: string): boolean;
+/** Does this pane exist AND have its command still RUNNING (`#{pane_dead}` = 0)?
+ *  Distinguishes a pane genuinely hosting a live process from a remain-on-exit
+ *  corpse frozen after exit (`pane_dead` = 1). Node viewer panes run `crtr surface attach`
+ *  as the pane command, so pane-running ⟹ a live viewer occupies it. */
+export declare function paneRunning(pane: string): boolean;
+/** Every live pane id on the server (`list-panes -a`), as a Set for membership
+ *  probes. Returns null when tmux is unreachable (no server / transient failure)
+ *  so callers can tell "no panes" apart from "can't tell" — a GC pass must skip,
+ *  never mass-delete, on a failed probe. One subprocess call total, so batch
+ *  liveness sweeps (e.g. the daemon's stale-focus GC) don't pay a per-pane
+ *  display-message each. */
+export declare function listLivePanes(): Set<string> | null;
+/** The same probe without blocking the event loop, for callers running inside
+ *  crtrd's detached work. The daemon runs this sweep on every supervision tick,
+ *  and a blocking fork/exec there freezes the API socket — which every CLI
+ *  command and every live broker's inbox poll shares — for its full duration.
+ *  Identical contract to `listLivePanes`: null means the probe failed (no
+ *  server, timeout), which a GC pass must treat as "can't tell" and skip. */
+export declare function listLivePanesAsync(): Promise<Set<string> | null>;
+/** The working directory of a pane (`display-message -p -t <pane>
+ *  '#{pane_current_path}'`). Null if tmux fails. */
+export declare function paneCurrentPath(pane: string): string | null;
+/** The pane's current cell dimensions, or null when tmux cannot describe it. */
+export declare function paneSize(pane: string): {
+    cols: number;
+    rows: number;
+} | null;
+/** Flash a transient status-line toast on the client showing `pane` (or the
+ *  current client when `pane` is omitted). `ms` sets the display duration. Used
+ *  by `crtr canvas issue new` to confirm a capture from inside its popup.
+ *  Best-effort; never throws. */
+/** Show a transient toast in the target client's status line.
+ *
+ *  `-C` is load-bearing, not decoration: without it tmux STOPS painting that
+ *  client's panes for the whole delay, so every crtr toast freezes a live
+ *  viewer mid-turn until the message expires or a keypress dismisses it. The
+ *  flag is newer than the tmux versions crouter still runs on, and a tmux that
+ *  rejects it prints usage and shows nothing — so a rejected call retries in
+ *  the plain form, where the toast is worth more than the paint stall. */
+export declare function displayMessage(message: string, pane?: string, ms?: number): boolean;
+/** Set a PANE-scoped tmux option (`tmux set-option -p -t <pane> <name> <value>`).
+ *  Best-effort; never throws. */
+export declare function setPaneOption(pane: string, name: string, value: string): boolean;
+/** Read a PANE-scoped tmux option value (`tmux show-options -p -t <pane> -q -v
+ *  <name>`): `-v` prints only the value, `-q` suppresses the unknown-option
+ *  error so an unset option yields an empty string. undefined if tmux fails. */
+export declare function getPaneOption(pane: string, name: string): string | undefined;
+/** Pane option recording when an attach viewer was last started or focused.
+ *  `liveViewerPanes` uses it to select the most recently used viewer. */
+export declare const VIEWER_STAMP_OPTION = "@crtr_viewer_at";
+/** Stamp a viewer pane without blocking the input path that observed focus.
+ *  Stamps are monotonically increasing and their tmux writes are serialized, so
+ *  two rapid focus events cannot leave an older pane with the newer stamp. */
+export declare function stampViewerPaneAsync(pane: string): void;
+export interface LiveViewerPane {
+    readonly pane: string;
+    readonly session: string;
+    readonly nodeId: string;
+    readonly stampMs: number;
+}
+/** List viewer panes tagged by a running local attach viewer. Pane tags can
+ *  survive a killed process, so every tag must match a viewer for the same node.
+ *  Shell-hosted viewers are recognized through their live child process. Unstamped
+ *  valid viewers remain eligible at stamp zero while an older viewer rolls forward. */
+export declare function liveViewerPanes(socket?: string): LiveViewerPane[];
+/** Deliver one private attach-control sequence literally into a viewer pane.
+ *  `-l` bypasses tmux key-table lookup, so delivery cannot re-trigger a root
+ *  binding that initiated it. */
+export declare function sendAttachControl(socket: string | undefined, pane: string, actionId: AttachBindingId): boolean;
+/** Show a tmux status-line message on a specific client when one is known.
+ *  `-C` for the same reason as `displayMessage`: the client's panes must keep
+ *  painting while the message sits in its status line. */
+export declare function displayClientMessage(socket: string | undefined, client: string | undefined, text: string): boolean;
+export interface RespawnPaneOpts {
+    /** Target pane id (e.g. `%3`) — the pane to re-exec in place. */
+    pane: string;
+    cwd: string;
+    env: Record<string, string>;
+    /** The full command to run in the pane (already a shell string). */
+    command: string;
+}
+/** Re-exec a command in an EXISTING pane, in place — SYNCHRONOUS. Runs the
+ *  `respawn-pane` to completion and reports the real exit status. Used when the
+ *  caller is NOT the pane being respawned (e.g. the daemon resuming a frozen
+ *  focus pane), so it can confirm the respawn landed. Returns true on success. */
+export declare function respawnPaneSync(opts: RespawnPaneOpts): boolean;
+/** Queue an in-place respawn through the tmux server. A program running IN the
+ * target pane must use this instead of `respawnPaneSync`: `respawn-pane -k`
+ * terminates that program, while this server-owned shell outlives the pane
+ * process long enough to run the respawn. The returned status only confirms
+ * tmux accepted the queued command. */
+export declare function respawnPaneInBackground(opts: RespawnPaneOpts): boolean;
+/** Run a shell command from the tmux server (`run-shell -b`), outside the
+ * caller's process tree, so it outlives the caller's pane or popup. The returned
+ * status only confirms tmux accepted the command. */
+export declare function runShellInBackground(command: string): boolean;
+/** The command line a pane was originally started with (`#{pane_start_command}`)
+ *  — the exact command `respawn-pane` with no argument re-runs. undefined when
+ *  tmux is unreachable or the pane is gone. */
+export declare function paneStartCommand(pane: string): string | undefined;
+/** The pane's root process pid (`#{pane_pid}`) — the process tmux launched in
+ *  the pane (the viewer itself, or the login shell hosting it). undefined when
+ *  tmux is unreachable or the pane is gone. */
+export declare function panePid(pane: string): number | undefined;
+/** Kill a pane's current process and re-run the SAME command line it was
+ *  started with (`respawn-pane -k` with no command reuses the pane's original
+ *  command). Used to hot-reload a viewer pane in place: the fresh process
+ *  re-resolves `crtr` and picks up the currently selected runtime generation,
+ *  while the pane id, geometry, and the node's broker are untouched. */
+export declare function respawnPaneInPlace(pane: string): boolean;
+/** Turn a pi argv array into a single shell command string.
+ *
+ *  The binary defaults to `CRTR_PI_BINARY` when that env var is set, else the
+ *  bundled pi CLI launched with the current Node binary. CRTR_PI_BINARY is a
+ *  TEST-ONLY substitution seam: the integration-test harness points it at a
+ *  deterministic fake-pi vehicle so a real `crtr node new` reaches the fake
+ *  instead of the LLM pi, without depending on tmux/shell PATH inheritance. An
+ *  explicit `binary` arg still overrides the env. The value may be a multi-word
+ *  launcher (e.g. `node --import tsx/esm host.ts`); only argv entries are
+ *  shell-quoted, so a multi-word binary is spliced verbatim ahead of them. */
+export declare function piCommand(argv: string[], binary?: string): string;
+/** List all window ids present in `session`. Returns [] if the session does
+ *  not exist or tmux fails for any reason. Each entry is the raw window id
+ *  string reported by tmux (e.g. `@1`, `@2`, …). */
+export declare function listWindowIds(session: string): string[];
+/** True when both `session` and `window` are present (non-null/undefined) and
+ *  the window currently exists inside the session. False whenever either arg
+ *  is absent, the session is gone, or tmux does not know the window. */
+export declare function windowAlive(session: string | null | undefined, window: string | null | undefined): boolean;
+/** Activate a window within its session (same-session navigation). Equivalent
+ *  to `tmux select-window -t <session>:<window>`. Best-effort; never throws. */
+export declare function selectWindow(session: string, window: string): boolean;
+/** Apply a named tmux layout to a window (`tmux select-layout -t <window>
+ *  <layout>`). `surface tmux-spread` calls it with `tiled` to evenly grid every
+ *  viewer pane in the spread window (and between splits, to redistribute space so
+ *  the next split has room). Best-effort; false if tmux fails. */
+export declare function selectLayout(window: string, layout: string): boolean;
+/** Make a pane the ACTIVE pane in its window (`tmux select-pane -t <pane>`). A
+ *  `split-window -d` keeps the CALLER active, so a freshly-opened viewer pane is
+ *  not focused until this runs — `focus` calls it so picking a node (e.g. from the
+ *  alt+g graph) lands the keyboard on the new viewer. Best-effort; false if tmux
+ *  fails. */
+export declare function selectPane(pane: string): boolean;
+/** Switch the tmux client to a different session (cross-session focus). Runs
+ *  `tmux switch-client -t <session>`. Best-effort; never throws. The caller is
+ *  responsible for following up with selectWindow to land on the right window. */
+export declare function switchClient(session: string): boolean;
+/** Type a literal (e.g. a `/graph` slash command) into a pane and press Enter
+ *  (`tmux send-keys -t <pane> '<text>' Enter`). Requires the pane's editor be
+ *  empty, same limitation as the menu's `/promote` item. Best-effort. */
+export declare function sendKeysEnter(pane: string, text: string): boolean;
+export { tmux as runTmux };

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

@@ -0,0 +1,6 @@
+var O=Object.defineProperty;var r=(n,t)=>O(n,"name",{value:t,configurable:!0});import{execFile as w,spawnSync as a}from"node:child_process";import{encodeAttachControlInput as E}from"../keybindings/index.js";import{listProcessTable as $}from"../canvas/pid.js";import{bundledPiCommandForShell as N}from"./pi-cli.js";import{shellQuote as l}from"../../shared/shell-quote.js";import{envPiBinaryOverride as C}from"../../shared/env.js";function o(n){const t=a("tmux",n,{encoding:"utf8"});return{ok:t.status===0,stdout:(t.stdout??"").trim(),stderr:(t.stderr??"").trim()}}r(o,"tmux");function p(n,t){return o(n===void 0||n===""?t:["-S",n,...t])}r(p,"tmuxOnSocket");function M(){return process.env.TMUX!==void 0&&process.env.TMUX!==""}r(M,"inTmux");function Y(){return a("tmux",["list-sessions"],{encoding:"utf8",stdio:"ignore"}).status===0}r(Y,"tmuxSessionsReachable");function Z(){return a("tmux",["list-clients","-F","#{client_name}"],{encoding:"utf8"}).status===0}r(Z,"tmuxClientsReachable");function nn(n){if(n==="")return null;const t=o(["list-panes","-a","-F","#{pane_id}	#{@crtr_node}"]);if(!t.ok)return null;for(const e of t.stdout.split(`
+`)){const s=e.indexOf("	");if(!(s<0)&&e.slice(s+1)===n){const u=e.slice(0,s);if(u!=="")return u}}return null}r(nn,"paneOfNode");function T(){if(!M())return null;const n=o(["display-message","-p","#{session_name}	#{window_id}	#{pane_id}"]);if(!n.ok)return null;const[t,e,s]=n.stdout.split("	");return{session:t,window:e,pane:s}}r(T,"currentTmux");function tn(){const n=a("tmux",["-V"],{stdio:"ignore"});return n.error===void 0&&n.status===0}r(tn,"tmuxAvailable");function en(n){return a("tmux",n,{stdio:"inherit"}).status??1}r(en,"tmuxInteractive");function F(n){return o(["has-session","-t",n]).ok}r(F,"sessionExists");function A(){const n=o(["show-options","-s","terminal-overrides"]).stdout;/Enbp=\\+E/.test(n)||o(["set-option","-sga","terminal-overrides","*:Enbp=\\E[?2004h:Dsbp=\\E[?2004l"])}r(A,"ensureBracketedPaste");function R(){A(),o(["set-option","-s","focus-events","on"])}r(R,"ensureServerOptions");function rn(n,t){F(n)||o(["new-session","-d","-s",n,"-c",t]),R()}r(rn,"ensureSession");function x(n){const t=[];for(const[e,s]of Object.entries(n))t.push("-e",`${e}=${s}`);return t}r(x,"envFlags");function on(n){const t=o(["new-window","-d","-a","-P","-F","#{window_id}	#{pane_id}","-t",`${n.session}:`,"-n",n.name,"-c",n.cwd,...x(n.env),n.command]);if(!t.ok)return null;const[e,s]=t.stdout.split("	");return e===void 0||e===""||s===void 0||s===""?null:{window:e,pane:s}}r(on,"openNodeWindow");function sn(n,t){const e=o(["split-window","-d",...t.vertical===!0?[]:["-h"],...t.before===!0?["-b"]:[],...t.size!==void 0?["-l",String(t.size)]:[],"-P","-F","#{pane_id}","-t",n,"-c",t.cwd,...x(t.env),t.command]);return e.ok&&e.stdout!==""?e.stdout:null}r(sn,"splitWindow");function un(n,t){return!(T()?.session===n)&&!o(["switch-client","-t",n]).ok?!1:o(["select-window","-t",t]).ok}r(un,"focusWindow");function cn(n){return o(["kill-window","-t",n]).ok}r(cn,"closeWindow");function dn(n,t){return o(["rename-window","-t",n,t]).ok}r(dn,"renameWindow");function an(n){const t=o(["break-pane","-d","-P","-F","#{window_id}	#{pane_id}","-s",n]);if(!t.ok)return null;const[e,s]=t.stdout.split("	");return e===void 0||e===""||s===void 0||s===""?null:{window:e,pane:s}}r(an,"breakPane");function pn(n){return o(["kill-pane","-t",n]).ok}r(pn,"closePane");function ln(n,t,e){return o(h(n,t,e)).ok}r(ln,"displayPopup");function fn(n,t,e){return new Promise(s=>{try{w("tmux",h(n,t,e),i=>s(i===null)).stdin?.end()}catch{s(!1)}})}r(fn,"displayPopupAsync");function h(n,t,e){return["display-popup","-E","-t",n,"-d",t,"-w","90%","-h","90%",e]}r(h,"displayPopupArgs");function mn(n,t){const e=o(["display-message","-p","-t",`${n}:${t}`,"#{pane_id}"]);return e.ok&&e.stdout!==""?e.stdout:null}r(mn,"paneOfWindow");function wn(n){const t=o(["display-message","-p","-t",n,"#{window_id}"]);return t.ok&&t.stdout!==""?t.stdout:null}r(wn,"windowOfPane");function xn(n){const t=o(["display-message","-p","-t",n,"#{session_name} #{window_id}"]);if(!t.ok)return null;const e=/^(.*) (@\d+)$/.exec(t.stdout);return e===null||e[1]===""?null:{session:e[1],window:e[2]}}r(xn,"paneLocation");function kn(n){const t=o(["display-message","-p","-t",n,"#{window_index}"]);return!t.ok||!/^\d+$/.test(t.stdout)?null:Number.parseInt(t.stdout,10)}r(kn,"windowIndex");function gn(n){const t=o(["display-message","-p","-t",n,"#{pane_id}"]);return t.ok&&t.stdout===n}r(gn,"paneExists");function hn(n){const t=o(["display-message","-p","-t",n,"#{pane_id}	#{pane_dead}"]);return t.ok&&t.stdout===`${n}	0`}r(hn,"paneRunning");function _n(){const n=o(["list-panes","-a","-F","#{pane_id}"]);return n.ok?new Set(n.stdout.split(`
+`).filter(t=>t!=="")):null}r(_n,"listLivePanes");const V=2e3;async function Pn(){const n=await new Promise(t=>{try{w("tmux",["list-panes","-a","-F","#{pane_id}"],{encoding:"utf8",timeout:V,maxBuffer:4194304},(e,s)=>t(e?null:s))}catch{t(null)}});return n===null?null:new Set(n.trim().split(`
+`).filter(t=>t!==""))}r(Pn,"listLivePanesAsync");function yn(n){const t=o(["display-message","-p","-t",n,"#{pane_current_path}"]);return t.ok&&t.stdout!==""?t.stdout:null}r(yn,"paneCurrentPath");function bn(n){const t=o(["display-message","-p","-t",n,"#{pane_width}	#{pane_height}"]);if(!t.ok)return null;const[e,s]=t.stdout.split("	"),u=Number.parseInt(e,10),i=Number.parseInt(s,10);return Number.isInteger(u)&&u>0&&Number.isInteger(i)&&i>0?{cols:u,rows:i}:null}r(bn,"paneSize");function vn(n,t,e=4e3){const s=r(u=>{const i=["display-message",...u?["-C"]:[],"-d",String(e)];return t!==void 0&&t!==""&&i.push("-t",t),i.push(n),i},"args");return o(s(!0)).ok||o(s(!1)).ok}r(vn,"displayMessage");function Sn(n,t,e){return o(["set-option","-p","-t",n,t,e]).ok}r(Sn,"setPaneOption");function In(n,t){const e=o(["show-options","-p","-t",n,"-q","-v",t]);return e.ok?e.stdout:void 0}r(In,"getPaneOption");const W="@crtr_viewer_at";let _=0,P=Promise.resolve();function On(n){if(n==="")return;const t=Math.max(Date.now(),_+1);_=t,P=P.then(()=>new Promise(e=>{try{w("tmux",["set-option","-p","-t",n,W,String(t)],()=>e())}catch{e()}}))}r(On,"stampViewerPaneAsync");function B(n){return n.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")}r(B,"escapeRegex");function k(n,t){const e=n.replace(/^"|"$/g,"");return new RegExp(`(?:^|\\s)surface\\s+attach\\s+to\\s+${B(t)}(?:\\s|$)`).test(e)}r(k,"looksLikeViewerCommand");function L(){const n=$();if(n===null)return null;const t=new Map,e=new Map;for(const{pid:s,ppid:u,command:i}of n){e.set(s,i);const c=t.get(u)??[];c.push(s),t.set(u,c)}return{childrenOf:t,commandOf:e}}r(L,"readProcessTree");function j(n,t,e){const s=[t];for(;s.length>0;){const u=s.pop();if(k(n.commandOf.get(u)??"",e))return!0;const i=n.childrenOf.get(u);i!==void 0&&s.push(...i)}return!1}r(j,"processTreeHasViewer");function En(n){const t=p(n,["list-panes","-a","-F","#{pane_id}	#{session_name}	#{@crtr_node}	#{@crtr_viewer_at}"]);if(!t.ok||t.stdout==="")return[];const e=[];let s;for(const u of t.stdout.split(`
+`)){const[i,c,d,b]=u.split("	");if(i===void 0||i===""||c===void 0||c===""||d===void 0||d==="")continue;const g=p(n,["display-message","-p","-t",i,"#{pane_current_command}	#{pane_start_command}	#{pane_pid}"]);if(!g.ok)continue;const[v="",S="",I]=g.stdout.split("	");if(!(k(v,d)||k(S,d))){s??=L();const m=Number.parseInt(I,10);if(s===null||!Number.isInteger(m)||m<=0||!j(s,m,d))continue}const f=Number.parseInt(b??"",10);e.push({pane:i,session:c,nodeId:d,stampMs:Number.isSafeInteger(f)&&f>=0?f:0})}return e}r(En,"liveViewerPanes");function $n(n,t,e){return p(n,["send-keys","-l","-t",t,E(e)]).ok}r($n,"sendAttachControl");function Nn(n,t,e){const s=r(u=>{const i=["display-message",...u?["-C"]:[]];return t!==void 0&&t!==""&&i.push("-c",t),i.push(e),i},"args");return p(n,s(!0)).ok||p(n,s(!1)).ok}r(Nn,"displayClientMessage");function y(n){return["respawn-pane","-k","-c",n.cwd,...x(n.env),"-t",n.pane,n.command]}r(y,"respawnPaneArgs");function Cn(n){return o(y(n)).ok}r(Cn,"respawnPaneSync");function Mn(n){return z(`tmux ${y(n).map(l).join(" ")} >/dev/null 2>&1`)}r(Mn,"respawnPaneInBackground");function z(n){return o(["run-shell","-b",n]).ok}r(z,"runShellInBackground");function Tn(n){const t=o(["display-message","-p","-t",n,"#{pane_start_command}"]);return t.ok?t.stdout:void 0}r(Tn,"paneStartCommand");function Fn(n){const t=o(["display-message","-p","-t",n,"#{pane_pid}"]);if(!t.ok)return;const e=Number.parseInt(t.stdout,10);return Number.isInteger(e)&&e>0?e:void 0}r(Fn,"panePid");function An(n){return o(["respawn-pane","-k","-t",n]).ok}r(An,"respawnPaneInPlace");function Rn(n,t=C()??N(l)){return[t,...n.map(l)].join(" ")}r(Rn,"piCommand");function U(n){const t=o(["list-windows","-t",n,"-F","#{window_id}"]);return!t.ok||t.stdout===""?[]:t.stdout.split(`
+`).filter(e=>e!=="")}r(U,"listWindowIds");function Vn(n,t){return n==null||t==null?!1:U(n).includes(t)}r(Vn,"windowAlive");function Wn(n,t){return o(["select-window","-t",`${n}:${t}`]).ok}r(Wn,"selectWindow");function Bn(n,t){return o(["select-layout","-t",n,t]).ok}r(Bn,"selectLayout");function Ln(n){return o(["select-pane","-t",n]).ok}r(Ln,"selectPane");function jn(n){return o(["switch-client","-t",n]).ok}r(jn,"switchClient");function zn(n,t){return o(["send-keys","-t",n,t,"Enter"]).ok}r(zn,"sendKeysEnter");export{W as VIEWER_STAMP_OPTION,an as breakPane,pn as closePane,cn as closeWindow,T as currentTmux,Nn as displayClientMessage,vn as displayMessage,ln as displayPopup,fn as displayPopupAsync,rn as ensureSession,un as focusWindow,In as getPaneOption,M as inTmux,_n as listLivePanes,Pn as listLivePanesAsync,U as listWindowIds,En as liveViewerPanes,on as openNodeWindow,yn as paneCurrentPath,gn as paneExists,xn as paneLocation,nn as paneOfNode,mn as paneOfWindow,Fn as panePid,hn as paneRunning,bn as paneSize,Tn as paneStartCommand,Rn as piCommand,dn as renameWindow,Mn as respawnPaneInBackground,An as respawnPaneInPlace,Cn as respawnPaneSync,z as runShellInBackground,o as runTmux,Bn as selectLayout,Ln as selectPane,Wn as selectWindow,$n as sendAttachControl,zn as sendKeysEnter,F as sessionExists,Sn as setPaneOption,l as shellQuote,sn as splitWindow,On as stampViewerPaneAsync,jn as switchClient,tn as tmuxAvailable,Z as tmuxClientsReachable,en as tmuxInteractive,Y as tmuxSessionsReachable,Vn as windowAlive,kn as windowIndex,wn as windowOfPane};

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

@@ -0,0 +1,36 @@
+/** The tmux session crouter creates (or adds a window to). */
+export declare const HANDOFF_SESSION = "crouter";
+/** Set by the handoff on the inner `crtr`: tmux was started for this person by
+ *  crouter, so the first conversation carries the one-line tmux survival hint,
+ *  and a second handoff is refused rather than looped. */
+export declare const TMUX_STARTED_ENV = "CRTR_TMUX_STARTED";
+/** The invocation to replay inside tmux: the original tokens, with the profile
+ *  the person already chose pinned (so the picker does not run a second time)
+ *  and `--pick-profile` dropped (it has done its job). */
+export declare function handoffArgs(tokens: readonly string[], profileId: string | null): string[];
+/** The environment the inner `crtr` must see. A tmux server that was already
+ *  running has its OWN environment, so anything that exists only in the shell
+ *  that ran `crtr` — a provider key the credential gate just accepted, a custom
+ *  `CRTR_HOME`, PATH additions, proxies, `spawnEnv.allow` names — would be
+ *  missing and the inner replay could fail a check the outer process passed.
+ *  Rather than guess a list of names (the gate and the spawn allowlist both read
+ *  open-ended sets), forward the whole environment minus the terminal/tmux
+ *  identity variables above. Delivered through a private file, never argv and
+ *  never `set-environment -g`: see `writeHandoffEnvFile`. */
+export declare function forwardedEnv(env: NodeJS.ProcessEnv): Array<[string, string]>;
+/** `export NAME='value'` lines for the forwarded environment. */
+export declare function handoffEnvLines(env: NodeJS.ProcessEnv): string;
+/** Write the forwarded environment to a 0600 file in a fresh 0700 directory, so
+ *  secrets never appear in a process listing (tmux's argv is `ps`-visible) or in
+ *  the tmux server's global environment (`tmux show-environment -g`). The
+ *  window's script sources and deletes it. */
+export declare function writeHandoffEnvFile(env: NodeJS.ProcessEnv): string;
+/** The `sh -c` script the tmux window runs: load (and delete) the forwarded
+ *  environment file, run crtr with the replayed arguments, then stay in the
+ *  person's shell. */
+export declare function handoffScript(launcher: readonly string[], args: readonly string[], envFile: string): string;
+/** How to install tmux, for the message shown when it is missing. */
+export declare function tmuxInstallHint(platform: NodeJS.Platform): string;
+/** Start (or join) the `crouter` tmux session running this same invocation, and
+ *  attach this terminal to it. Does not return. */
+export declare function handoffToTmux(tokens: readonly string[], profileId: string | null, cwd: string): never;

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

@@ -0,0 +1,10 @@
+var S=Object.defineProperty;var s=(n,r)=>S(n,"name",{value:r,configurable:!0});import{mkdtempSync as _,rmSync as l,writeFileSync as d}from"node:fs";import{tmpdir as R}from"node:os";import{dirname as a,join as E}from"node:path";import{FRONT_DOOR_ENV as h}from"./front-door-env.js";import{sessionExists as O,tmuxAvailable as I,tmuxInteractive as f}from"./placement-tmux.js";import{shellQuote as i}from"../../shared/shell-quote.js";const c="crouter",T="CRTR_TMUX_STARTED";function A(n,r){const t=[];for(let o=0;o<n.length;o++){const e=n[o];if(e!=="--pick-profile"){if(e==="--profile"){o++;continue}t.push(e)}}return r===null?t:[...t,"--profile",r]}s(A,"handoffArgs");const D=new Set(["TERM","TERMINFO","TMUX","TMUX_PANE","SHLVL","PWD","OLDPWD","_","TERM_SESSION_ID","WINDOWID","STY","UID","EUID","PPID","GROUPS","IFS","BASHOPTS","SHELLOPTS","BASH_VERSINFO",h,T]),N=["TERM_PROGRAM","ITERM_","LC_TERMINAL","KITTY_","WEZTERM_","ALACRITTY_","VTE_","WT_"],w=/^[A-Za-z_][A-Za-z0-9_]*$/;function L(n){const r=[];for(const[t,o]of Object.entries(n))o===void 0||!w.test(t)||D.has(t)||N.some(e=>t.startsWith(e))||r.push([t,o]);return r}s(L,"forwardedEnv");function M(n){return L(n).map(([r,t])=>`export ${r}=${i(t)}`).join(`
+`)+`
+`}s(M,"handoffEnvLines");function $(n){const r=_(E(R(),"crtr-handoff-")),t=E(r,"env.sh");return d(t,M(n),{mode:384}),t}s($,"writeHandoffEnvFile");function v(n,r,t){const o=`. ${i(t)}
+rm -rf ${i(a(t))}`,e=`${T}=1 ${[...n,...r].map(i).join(" ")}`;return[o,e,'exec "${SHELL:-/bin/sh}"'].join(`
+`)}s(v,"handoffScript");function F(n){return n==="darwin"?"brew install tmux":n==="linux"?"sudo apt install tmux   (or your distribution's package manager)":"install tmux with your system package manager"}s(F,"tmuxInstallHint");function j(n,r,t){I()||(process.stderr.write(`
+crouter shows conversations in tmux, and tmux is not installed.
+Install it with:  ${F(process.platform)}
+then run crtr again (\`crtr sys setup\` can also install it for you).
+
+`),process.exit(1));const o=$(process.env),p=["sh","-c",v(["crtr"],A(n,r),o)],x=O(`=${c}`);let u;if(x){const m=f(["new-window","-t",`=${c}:`,"-c",t,"-n","crtr",...p]);m!==0&&(l(a(o),{recursive:!0,force:!0}),process.exit(m)),u=f(["attach-session","-t",`=${c}`])}else u=f(["new-session","-s",c,"-c",t,"-n","crtr",...p]);l(a(o),{recursive:!0,force:!0}),process.exit(u)}s(j,"handoffToTmux");export{c as HANDOFF_SESSION,T as TMUX_STARTED_ENV,L as forwardedEnv,A as handoffArgs,M as handoffEnvLines,v as handoffScript,j as handoffToTmux,F as tmuxInstallHint,$ as writeHandoffEnvFile};

package/dist/core/runtime/tool-group-summary.d.ts

@@ -0,0 +1,19 @@
+import { type ToolGroupSummary } from '../../shared/tool-groups.js';
+export type ToolGroupPiece = {
+    type: 'tool';
+    name: string;
+    args: unknown;
+} | {
+    type: 'result';
+    name: string;
+    result: unknown;
+    isError: boolean;
+} | {
+    type: 'text';
+    text: string;
+};
+/** Serialize only the causal material around one group, with fixed per-piece
+ * and total budgets so a verbose tool result cannot dominate the light-model call. */
+export declare function serializeToolGroup(previousBoundaryProse: string, pieces: readonly ToolGroupPiece[]): string;
+/** Generate a structured summary object, or null on every failure. */
+export declare function headlessToolGroupSummary(segment: string): Promise<ToolGroupSummary | null>;

package/dist/core/runtime/tool-group-summary.js

@@ -0,0 +1,6 @@
+var l=Object.defineProperty;var r=(e,t)=>l(e,"name",{value:t,configurable:!0});import{Type as i}from"@earendil-works/pi-ai";import{headlessToolCall as m}from"./headless-pi.js";import{defaultProvider as u,modelLadders as c}from"./model-selection.js";import{lightModel as d}from"./naming.js";import{normalizeToolGroupSummary as p}from"../../shared/tool-groups.js";const h=600,f=300,g=400,y=1e3,b=1e4,v=45e3;function n(e,t){const o=e.replace(/\s+/g," ").trim();return o.length<=t?o:`${o.slice(0,Math.max(0,t-1)).trimEnd()}\u2026`}r(n,"capped");function a(e,t){try{return n(typeof e=="string"?e:JSON.stringify(e),t)}catch{return n(String(e),t)}}r(a,"printable");function E(e,t){const o=[`Previous visible message: ${n(e,h)||"(none)"}`,"Between-message activity:"];for(const s of t)s.type==="tool"?o.push(`- tool ${s.name}(${a(s.args,f)})`):s.type==="result"?o.push(`- ${s.isError?"error":"result"} ${s.name}: ${a(s.result,g)}`):o.push(`- context: ${n(s.text,y)}`);return n(o.join(`
+`),b)}r(E,"serializeToolGroup");const w='Create a structured recap of this coding-agent tool activity. Prefer 1\u20133 bullets and use at most 5 only for distinct meaningful outcomes. Each bullet must be an extremely readable plain-English outcome of 3\u201310 words, without markdown markers. Describe what changed or was accomplished, not the tools, commands, or investigation steps; for code work, say what capability was added to a one- or two-phrase plain-English part of the system, such as "Added scheduling controls to the worker service." Never include IDs, hashes, paths, filenames, command names, tool names, raw values, or report text. Omit inbox receipt, delivery, and queueing; node-response and report bookkeeping; help lookups; status checks; and summary-generation activity. A node response may support a substantive outcome, but its arrival or resummarization is never itself an outcome. If no meaningful outcome remains after those omissions, submit the single bullet "No meaningful changes." Count distinct files removed from disk only when the supplied tool arguments or results evidence them; otherwise use zero, even when the corresponding mechanics are omitted from bullets. A deleted file is one that no longer exists after the segment, never a file that was merely edited or overwritten, and a recursive or wildcard removal of an unknown number of files counts as one. Do not invent success when a result shows failure. Call submit_summary exactly once with bullets and filesDeleted, then stop.',S=i.Object({bullets:i.Array(i.String({minLength:1,maxLength:120,description:"A very short, plain-English outcome without bullet markers, identifiers, or operational bookkeeping."}),{minItems:1,maxItems:5}),filesDeleted:i.Integer({minimum:0,description:"Count of distinct files removed from disk during the supplied segment, or zero when none are evidenced."})},{additionalProperties:!1});async function P(e){const t=c(),o=`${u(t)}/light`;return p(await m({systemPrompt:w,userPrompt:`<tool-group>
+${e}
+</tool-group>
+
+Summarize the activity above.`,modelSpec:d(),modelIntent:o,timeoutMs:v,tool:{name:"submit_summary",label:"Submit summary",description:"Submit the structured tool-group activity recap exactly once, then stop.",parameters:S,constrainedSampling:!1}}))}r(P,"headlessToolGroupSummary");export{P as headlessToolGroupSummary,E as serializeToolGroup};

package/dist/core/runtime/turn-visibility.d.ts

@@ -0,0 +1,10 @@
+import type { MessageVisibility } from './stamp/protocol.js';
+export type TurnVisibility = MessageVisibility;
+/** The presentation classification of the current agent run. */
+export declare function currentTurnVisibility(): TurnVisibility;
+/** Whether the current agent run is structurally internal to crouter. */
+export declare function isTurnInternal(): boolean;
+/** Set visibility before handing an admitted input to pi. */
+export declare function setTurnVisibility(visibility: TurnVisibility): void;
+/** Return to the fail-open state after the complete agent run settles. */
+export declare function clearTurnVisibility(): void;

package/dist/core/runtime/turn-visibility.js

@@ -0,0 +1 @@
+var o=Object.defineProperty;var i=(t,n)=>o(t,"name",{value:n,configurable:!0});const u=Symbol.for("@crouton-kit/crtr:turn-visibility");function r(){const t=globalThis,n=t[u];if(n!==void 0)return n;const e={value:"visible"};return t[u]=e,e}i(r,"state");function l(){return r().value}i(l,"currentTurnVisibility");function c(){return l()==="internal"}i(c,"isTurnInternal");function a(t){r().value=t}i(a,"setTurnVisibility");function b(){r().value="visible"}i(b,"clearTurnVisibility");export{b as clearTurnVisibility,l as currentTurnVisibility,c as isTurnInternal,a as setTurnVisibility};

package/dist/core/runtime/view-socket.d.ts

@@ -0,0 +1,21 @@
+import { Socket } from 'node:net';
+/** The shared cold-start deadline (ms) a freshly-opened viewer waits for its
+ * broker's view.sock — one source of truth for CRTR_ATTACH_WAIT_MS. */
+export declare const BROKER_VIEW_SOCKET_WAIT_MS = 30000;
+/** Connect to `nodeId`'s view.sock without following a symlink the node's app
+ *  planted in its run folder. A refusal or a missing socket surfaces as the
+ *  socket's 'error' event, as a failed connect does. */
+export declare function connectViewSocket(nodeId: string): Socket;
+/** Resolve true exactly when `nodeId`'s view.sock accepts a connection within
+ *  `timeoutMs`. A view.sock that is a symlink rejects with the refusal, so no
+ *  wait reads a planted link as a broker that is still starting. */
+export declare function probeViewSocket(nodeId: string, timeoutMs: number): Promise<boolean>;
+/** Bounded retry for the revive leaf, which has no launch handle to observe. */
+export declare function waitForViewSocketReady(nodeId: string): Promise<boolean>;
+/** Wait for a launched broker's view.sock, failing fast when its launch handle
+ * exits. `exited` remains optional for existing callers that only need the same
+ * bounded readiness deadline without a handle. */
+export declare function waitForBrokerViewSocket(nodeId: string, exited?: Promise<{
+    code: number | null;
+    signal: NodeJS.Signals | null;
+}>): Promise<boolean>;

package/dist/core/runtime/view-socket.js

@@ -0,0 +1 @@
+var m=Object.defineProperty;var a=(t,e)=>m(t,"name",{value:e,configurable:!0});import{createConnection as p,Socket as S}from"node:net";import{nodeRunDir as d,viewSocketPath as h}from"../canvas/paths.js";import{isBeneathRefusal as x,socketBeneath as _}from"../spaces/open-beneath.js";const u=3e4,l=100,T=u;function f(t){return new Promise(e=>{setTimeout(e,t)})}a(f,"sleep");function E(t){let e;try{e=_(d(t),h(t))}catch(i){const c=new S;return process.nextTick(()=>c.destroy(i)),c}const r=p(e.path);return r.once("connect",e.release),r.once("close",e.release),r}a(E,"connectViewSocket");function w(t,e){return new Promise((r,i)=>{let c=!1,n=null;const s=a(o=>{c||(c=!0,n!==null&&n.destroy(),o instanceof Error?i(o):r(o))},"finish");n=E(t),n.once("connect",()=>s(!0)),n.once("error",o=>s(x(o)?o:!1)),n.setTimeout(e,()=>s(!1))})}a(w,"probeViewSocket");async function B(t){const e=Date.now()+u;for(;Date.now()<=e;){if(await w(t,l))return!0;await f(l)}return!1}a(B,"waitForViewSocketReady");async function C(t,e){const r=Date.now()+u,i=e?.then(()=>"exit");for(;Date.now()<=r;){const c=Math.max(0,r-Date.now()),n=w(t,Math.min(l,c)).then(o=>o?"ready":"retry"),s=i===void 0?await n:await Promise.race([n,i]);if(s==="ready")return!0;if(s==="exit")return!1;if(i!==void 0){if(await Promise.race([f(l).then(()=>"sleep"),i])==="exit")return!1}else await f(l)}return!1}a(C,"waitForBrokerViewSocket");export{T as BROKER_VIEW_SOCKET_WAIT_MS,E as connectViewSocket,w as probeViewSocket,C as waitForBrokerViewSocket,B as waitForViewSocketReady};

package/dist/core/runtime/warm-pool.d.ts

@@ -0,0 +1,65 @@
+import type { Mode, OutcomeDeliveryBinding } from '../canvas/index.js';
+/** Kill switch. `CRTR_WARM_POOL=0` makes every create cold again: claims stop,
+ *  refills stop, and daemon-start pre-warm no-ops. Read live (not cached at
+ *  module load) so flipping it takes effect on the next `crtr sys daemon
+ *  restart` without a rebuild. Env rather than config because the operators who
+ *  need it are guest containers — a Blaxel sandbox spec and the local-docker
+ *  compose both already carry per-home env, and neither has a config file the
+ *  host controls.
+ *
+ *  Turn it off when a spare's ~150-300 MB resident broker is the scarce
+ *  resource (a memory-capped guest), or to isolate the pool while debugging a
+ *  node that came back wearing the wrong persona. */
+export declare function warmPoolEnabled(): boolean;
+/** What a `prefer_warm` create is asking for. Only a subset of this is frozen
+ *  into the pool key (see `warmRecipeKey`); the rest is applied at claim time. */
+export interface WarmRequest {
+    kind: string;
+    mode: Mode;
+    /** Where the node runs — already resolved by the create handler (pin >
+     *  spawner > launch cwd > profile home). */
+    cwd: string;
+    /** The RESOLVED profile id, or null for explicitly no profile. */
+    profileId: string | null;
+    model: string | null;
+    situationalContext: string | null;
+    name: string | null;
+    /** Node that asked for this create, or null for an external process. Claim-time
+     *  identity like `name` — a spare is minted creator-less and adopts the
+     *  claimant's, so provenance survives the warm path. */
+    creator: string | null;
+}
+/** Claim a spare for `request`, reshaped onto its persona — or null when the
+ *  pool cannot serve it. The caller falls back to a cold spawn; a refused
+ *  create hook leaves the spare untouched and rejects the create. `beforeClaimDelivery`
+ *  persists birth state before the claimant's first session message can arrive. */
+export declare function claimWarmNode(request: WarmRequest, birth?: {
+    deadlineAt?: string;
+    outcomeDelivery?: OutcomeDeliveryBinding;
+    requestKey?: string;
+}, beforeClaimDelivery?: (nodeId: string) => void): Promise<string | null>;
+/** Finish a warm claim that was durably assigned to an idempotency key before a
+ *  daemon handover. The marker is already gone, so this only restores the
+ *  claimant's node shape and live-session deliveries. */
+export declare function resumeWarmClaim(request: WarmRequest, nodeId: string, beforeClaimDelivery?: (nodeId: string) => void): Promise<string | null>;
+/** Return every spare that is no longer worth its broker: one whose engine is
+ *  confirmed GONE (the common case — a daemon handover tears down every broker
+ *  of its epoch and nothing resumes a spare), one whose row left `active`/`idle`,
+ *  and one nobody claimed inside `SPARE_TTL_MS`.
+ *
+ *  Order matters: the marker is deleted FIRST, atomically, which is the same
+ *  move a claim makes — so a spare handed out a microsecond earlier is left
+ *  alone (`unregisterWarmSpare` returns false) and never torn down under its
+ *  new owner. Only after winning the marker is the broker killed and the row +
+ *  dir deleted. Never throws: a failed reap is retried on the next sweep. */
+export declare function reapStaleSpares(): string[];
+/** Bring the pool for `request` back to depth 1, in the background. Never
+ *  throws and never blocks a caller: a failed mint just means the next create
+ *  for this key is cold again. */
+export declare function refillWarmPool(request: WarmRequest): void;
+/** Mint a spare for the most recently used profiles so the FIRST create after
+ *  crtrd boots is warm too, not only the second. The profile is the whole
+ *  recipe: it supplies the cwd, and everything else a claim reshapes live.
+ *  Fire-and-forget — returns as soon as the mints are scheduled, never blocking
+ *  the daemon's work lane. */
+export declare function prewarmRecentRecipes(): void;

package/dist/core/runtime/warm-pool.js

@@ -0,0 +1 @@
+var S=Object.defineProperty;var a=(e,r)=>S(e,"name",{value:r,configurable:!0});import{createHash as _}from"node:crypto";import{claimWarmSpare as x,deleteNode as N,getNode as u,listNodes as $,listWarmSpares as C,registerWarmSpare as R,unregisterWarmSpare as W,updateNode as b,warmSpareCount as w}from"../canvas/index.js";import{recordedPidLiveness as P}from"../canvas/pid.js";import{nowIso as h}from"../fs-utils.js";import{admitNodeCreate as L}from"../command-hooks/lifecycle-create.js";import{spawnChildPrepared as M}from"./spawn.js";import{buildLaunchSpecAsync as A}from"./launch.js";import{setModelLive as E}from"./model-swap.js";import{setSituationalContextLive as O}from"./situational-live.js";import{deliverBearingsLive as I}from"./deliver-live.js";import{closeNode as y}from"./close.js";function g(){return process.env.CRTR_WARM_POOL!=="0"}a(g,"warmPoolEnabled");function T(e,r,o){const t=Object.entries(o.env??{}).sort(([s],[i])=>s<i?-1:s>i?1:0),n=JSON.stringify([e,r,o.tools??[],o.extensions??[],o.systemPrompt??null,t]);return _("sha256").update(n).digest("hex").slice(0,32)}a(T,"warmRecipeKey");async function d(e){const{launch:r}=await A(e.kind,e.mode,{lifecycle:"resident",hasManager:!1,...e.model!==null?{model:e.model}:{},cwd:e.cwd,profileId:e.profileId});return{key:T(e.cwd,e.profileId,r),launch:r,request:e}}a(d,"resolveRecipe");async function Z(e,r={},o){const t=await d(e);if(w(t.key)===0)return null;const n=h(),s=await L({kind:e.kind,mode:e.mode,cwd:e.cwd,profile:e.profileId,root:!0,parentId:null,requestingNodeId:e.creator,lifecycle:"resident",replaces:null},e.creator===null?"app:terminal":(()=>{const l=u(e.creator);if(!l?.grantee)throw new Error("warm node creator has no app");return l.grantee})());let i;try{i=x(t.key,n,r)}finally{s()}return i===null?null:v(i,t,n,o)}a(Z,"claimWarmNode");async function q(e,r,o){return v(r,await d(e),h(),o)}a(q,"resumeWarmClaim");async function v(e,r,o,t){const{request:n}=r,i=u(e)?.launch?.model;b(e,{created:o,kind:n.kind,mode:n.mode,name:n.name??n.kind,creator:n.creator,launch:r.launch,persona_ack:{kind:n.kind,mode:n.mode,lifecycle:"resident"},...n.model!==null?{model_override:n.model}:{}});try{t?.(e)}catch(c){return m(e,"birth preparation",c)}try{await I(e)}catch(c){return m(e,"bearings delivery",c)}const l=r.launch.model;if(l!==void 0&&l!==i)try{await E(e,l,r.launch.modelIntent)}catch(c){return m(e,"model swap",c)}if(n.situationalContext!==null)try{await O(e,n.situationalContext)}catch(c){return m(e,"situational-context delivery",c)}return e}a(v,"completeWarmClaim");function m(e,r,o){console.error(`[warm-pool] ${r} failed on claim; closing the spare: ${o.message}`);try{y(e)}catch{}return null}a(m,"abandonSpare");const D=3600*1e3;function ee(){const e=[];let r;try{r=C()}catch(t){return console.error(`[warm-pool] spare scan failed: ${t.message}`),e}const o=Date.now()-D;for(const t of r){if(f.has(t.node_id))continue;const n=Date.parse(t.created),s=Number.isNaN(n)||n<o,i=P(t.pi_pid,t.pi_pid_identity),l=(t.status==="active"||t.status==="idle")&&i==="alive";if(!(l&&!s)&&!(i==="indeterminate"&&!s))try{if(!W(t.node_id))continue;if(l)try{y(t.node_id)}catch{}N(t.node_id),e.push(t.node_id)}catch(c){console.error(`[warm-pool] reap failed for ${t.node_id}: ${c.message}`)}}return e}a(ee,"reapStaleSpares");const p=new Set,f=new Set;function re(e){if(g())try{d({...e,model:null,situationalContext:null}).then(k).catch(r=>console.error(`[warm-pool] recipe resolution failed: ${r.message}`))}catch(r){console.error(`[warm-pool] recipe resolution failed: ${r.message}`)}}a(re,"refillWarmPool");function k(e){const{key:r,request:o}=e;p.has(r)||w(r)>0||(p.add(r),(async()=>{let t=null;try{await M({kind:o.kind,mode:o.mode,cwd:o.cwd,prompt:"",root:!0,readiness:"await",profile:o.profileId},n=>{t=n,f.add(n),R(n,r)})}catch(n){console.error(`[warm-pool] mint failed for ${o.kind}: ${n.message}`)}finally{t!==null&&f.delete(t),p.delete(r)}})())}a(k,"mint");const j=2;function oe(){if(!g())return;let e;try{const r=new Set;e=[];for(const o of $({status:["active","idle"]}).reverse()){if(o.parent!==null||o.kind==="human")continue;const t=o.profile_id??null;if(!r.has(t??"")&&(r.add(t??""),e.push({cwd:o.cwd,profileId:t}),e.length>=j))break}}catch(r){console.error(`[warm-pool] prewarm scan failed: ${r.message}`);return}for(const r of e)try{d({kind:"general",mode:"base",cwd:r.cwd,profileId:r.profileId,model:null,situationalContext:null,name:null,creator:null}).then(k).catch(o=>console.error(`[warm-pool] prewarm failed for ${r.cwd}: ${o.message}`))}catch(o){console.error(`[warm-pool] prewarm failed for ${r.cwd}: ${o.message}`)}}a(oe,"prewarmRecentRecipes");export{Z as claimWarmNode,oe as prewarmRecentRecipes,ee as reapStaleSpares,re as refillWarmPool,q as resumeWarmClaim,g as warmPoolEnabled};

package/dist/core/scope.d.ts

@@ -0,0 +1,32 @@
+import type { InstalledPlugin, Scope } from '../types.js';
+export declare function builtinMemoryRoot(): string;
+export declare function builtinPiPackagesDir(): string;
+export declare function builtinPiPackageDir(name: string): string;
+export declare function userScopeRoot(): string;
+export declare function findProjectScopeRoot(startDir?: string): string | null;
+/** Every project scope root visible from `startDir`, nearest first — now a
+ *  PROFILE-AWARE pointer walk, not a single-pointer ancestor walk. Pointers are
+ *  `[startDir]` plus, when `profileId` resolves to a manifest, each of its
+ *  `projects` in manifest order; each pointer independently walks upward
+ *  collecting every ancestor `.crouter/` dir, the pointers' contributions
+ *  concatenate in pointer order, and the combined list dedupes to first
+ *  occurrence — so a `.crouter/` shared by two pointers contributes once, at
+ *  whichever pointer reached it first. `profileId` defaults to the process's
+ *  selected profile (`CRTR_PROFILE_ID`); a null/unresolvable profile collapses
+ *  to the single `[startDir]` pointer, reproducing today's behavior exactly.
+ *  Outside a Linux node sandbox, roots are discovered on each call so profile
+ *  edits and deleted project directories do not leave a stale pointer. A node
+ *  sandbox has no profile store to read and uses only its cwd pointer. */
+export declare function findProjectScopeRoots(startDir?: string, profileId?: string | null): string[];
+export declare function projectScopeRoot(startDir?: string): string | null;
+export declare function projectScopeRoots(startDir?: string, profileId?: string | null): string[];
+export declare function scopeRoot(scope: Scope): string | null;
+export declare function requireScopeRoot(scope: Scope): string;
+export declare function ensureProjectScopeRoot(startDir?: string): string;
+export declare function pluginsDir(scope: Scope): string | null;
+export declare function marketplacesDir(scope: Scope): string | null;
+/** Where a plugin's substrate memory documents live: `<plugin.root>/memory`.
+ *  The resolver mounts these under the virtual `<pluginName>/` namespace. */
+export declare function pluginMemoryDir(plugin: InstalledPlugin): string;
+export declare function resolveScopeArg(scopeArg: string | undefined): Scope | 'all';
+export declare function listScopes(scopeArg: string | undefined): Scope[];

package/dist/core/scope.js

@@ -0,0 +1 @@
+var D=Object.defineProperty;var r=(o,t)=>D(o,"name",{value:t,configurable:!0});import{envProfileId as $,isSandboxedNode as S}from"../shared/env.js";import{homedir as j}from"node:os";import{existsSync as g,statSync as k}from"node:fs";import{join as n,resolve as m,dirname as M,sep as h}from"node:path";import{CRTR_DIR_NAME as f}from"../types.js";import{assetRoot as b}from"./asset-root.js";import{usage as P}from"./errors.js";import{loadProfileManifest as C}from"./profiles/manifest.js";import{realpathOrSelf as i}from"./fs-utils.js";import{appsRoot as N,layoutRoot as W,runtimeRoot as x}from"./layout.js";function U(){return n(b(),"builtin-memory")}r(U,"builtinMemoryRoot");function _(){return n(b(),"builtin-pi-packages")}r(_,"builtinPiPackagesDir");function V(o){return n(_(),o)}r(V,"builtinPiPackageDir");function d(){return n(x(),"scope")}r(d,"userScopeRoot");function q(o,t){if(!g(o)||i(o)===i(n(j(),f))||i(o).startsWith(`${i(N())}${h}`)&&o.endsWith(`${h}home${h}${f}`)||!S()&&(i(o)===i(t)||i(o)===i(W())))return!1;try{return k(o).isDirectory()}catch{return!1}}r(q,"isProjectScopeDir");function y(o=process.cwd()){return v(o)[0]??null}r(y,"findProjectScopeRoot");function A(o,t){const e=[],l=i(j());let u=m(o);for(;;){const s=n(u,f);if(q(s,t)&&e.push(s),i(u)===l)return e;const c=M(u);if(c===u)return e;u=c}}r(A,"collectAncestorScopeRoots");function v(o=process.cwd(),t=$()||null){return E(o,t)}r(v,"findProjectScopeRoots");function E(o,t){const e=m(o),l=d(),u=[e];if(!S()&&t!==null&&t!=="")try{const{manifest:a}=C(t);for(const p of a.projects)u.push(p.path)}catch{}const s=new Set,c=[];for(const a of u)for(const p of A(a,l))s.has(p)||(s.add(p),c.push(p));return c}r(E,"resolveProjectScopeRoots");function w(o){return y(o)}r(w,"projectScopeRoot");function X(o,t){return v(o,t)}r(X,"projectScopeRoots");function R(o){return o==="builtin"?null:o==="user"?d():w()}r(R,"scopeRoot");function Y(o){const t=R(o);if(!t)throw P(`no ${o} scope available \u2014 run \`crtr init\` here or use --scope user`);return t}r(Y,"requireScopeRoot");function Z(o=process.cwd()){const t=y(o);return t||n(m(o),f)}r(Z,"ensureProjectScopeRoot");function oo(o){const t=o==="user"?x():R(o);return t?n(t,"plugins"):null}r(oo,"pluginsDir");function to(o){const t=o==="user"?x():R(o);return t?n(t,"marketplaces"):null}r(to,"marketplacesDir");function ro(o){return n(o.root,"memory")}r(ro,"pluginMemoryDir");function L(o){if(o===void 0)return"all";const t=o.toLowerCase();if(t==="user"||t==="project"||t==="builtin"||t==="all")return t;throw P(`invalid --scope: ${o} (expected user|project|builtin|all)`)}r(L,"resolveScopeArg");function eo(o){const t=L(o);if(t==="all"){const e=[];return w()&&e.push("project"),e.push("user"),e.push("builtin"),e}return[t]}r(eo,"listScopes");export{U as builtinMemoryRoot,V as builtinPiPackageDir,_ as builtinPiPackagesDir,Z as ensureProjectScopeRoot,y as findProjectScopeRoot,v as findProjectScopeRoots,eo as listScopes,to as marketplacesDir,ro as pluginMemoryDir,oo as pluginsDir,w as projectScopeRoot,X as projectScopeRoots,Y as requireScopeRoot,L as resolveScopeArg,R as scopeRoot,d as userScopeRoot};

package/dist/core/scoped-state/db.d.ts

@@ -0,0 +1,17 @@
+import { DatabaseSync } from 'node:sqlite';
+import { type ScopedStore } from './paths.js';
+export declare const PROFILE_ID_SHAPE: RegExp;
+export declare function writeOwnerRoot(db: DatabaseSync, key: string, root: string): void;
+export declare function assertScopedStoreReady(store: ScopedStore): void;
+export declare function discardIncompleteScopedStore(store: ScopedStore): void;
+export declare function withProjectStateLock<T>(root: string, run: () => T): T;
+export declare function scopedStoreExists(store: ScopedStore): boolean;
+export declare function legacyScopedStorePaths(store: ScopedStore): string[];
+export declare function initializeFreshScopedStore(input: {
+    kind: 'user' | 'project' | 'provider';
+    root: string;
+}): void;
+export declare function openScopedStore(store: ScopedStore): DatabaseSync;
+export declare function createScopedStore(store: ScopedStore, create: (db: DatabaseSync) => void): void;
+export declare function withScopedWrite<T>(store: ScopedStore, run: (db: DatabaseSync) => T): T;
+export declare function closeScopedStores(): void;