@crouton-kit/crouter 0.3.82 → 0.3.84

package/dist/core/keybindings/index.d.ts

@@ -1,5 +1,6 @@
 export { BINDING_CATALOG, BINDING_IDS, SAFETY_REQUIREMENTS, type BindingId, } from './catalog.js';
 export { GestureSyntaxError, KeybindingValidationError, normalizeGesture, normalizeSparseOverrides, normalizeStroke, resolveKeybindings, resolveUserKeybindings, } from './resolve.js';
 export { canonicalTerminalStroke, formatBinding, formatGesture, formatStroke, matchesPiTuiInput, matchesTerminalInput, type PiTuiMatcher, type RawTerminalInput, } from './match.js';
+export { inboxOpenHint, inboxOpenInstruction, inboxPopupHint, inboxShortcut, } from './inbox.js';
 export { KeybindingConcurrentEditError, persistUserKeybindings, type PersistedKeybindings, type PersistKeybindingsOptions, } from './persistence.js';
 export type { BindingDefinition, BindingInputKind, BindingResolution, BindingSafetyCapability, EffectiveBinding, KeybindingDiagnostic, KeybindingDiagnosticCode, SafetyRequirement, SparseKeybindingOverrides, } from './types.js';

package/dist/core/keybindings/index.js

@@ -1,4 +1,5 @@
 export { BINDING_CATALOG, BINDING_IDS, SAFETY_REQUIREMENTS, } from './catalog.js';
 export { GestureSyntaxError, KeybindingValidationError, normalizeGesture, normalizeSparseOverrides, normalizeStroke, resolveKeybindings, resolveUserKeybindings, } from './resolve.js';
 export { canonicalTerminalStroke, formatBinding, formatGesture, formatStroke, matchesPiTuiInput, matchesTerminalInput, } from './match.js';
+export { inboxOpenHint, inboxOpenInstruction, inboxPopupHint, inboxShortcut, } from './inbox.js';
 export { KeybindingConcurrentEditError, persistUserKeybindings, } from './persistence.js';

package/dist/core/preview-registry.js

@@ -93,7 +93,6 @@ const LEAF_ICON_CP = {
     'human notify': 0xf0f3,
     'human show': 0xf108,
     'human cancel': 0xf00d,
-    'human inbox': 0xf01c,
     'human list': 0xf03a,
     'human deck': 0xf0db,
     'human resolve': 0xf00c,
@@ -1083,29 +1082,28 @@ function truncateLine(line, max) {
     return line.length > max ? `${line.slice(0, max).trimEnd()}…` : line;
 }
 const ASK_TEASER_CHARS = 160;
-/** `crtr human ask` (humanAsk.run, src/commands/human/prompts.ts:97) returns
+/** `crtr human ask` (humanAsk.run, src/commands/human/prompts.ts) returns
  *  `{job_id, dir, follow_up}` — `job_id` is always short (a node id) so it
  *  always bullets; `dir`/`follow_up` cross the prose threshold depending on
- *  path length, so the shape is recognized by `job_id` plus one of the two
- *  FIXED follow_up sentences (followUpResult/followUpDrain, shared.ts) being
- *  present anywhere in the text — never by assuming dir/follow_up's bullet
- *  vs. prose form. The question text isn't in the output at all (only the
- *  bare-question invocation echoes it), so it's recovered from argv: the
- *  first non-flag token after `human ask`, skipping `--context-file`'s value
- *  — absent for a `--context-file` deck invocation, which still gets the
- *  road-sign line with no question teaser. Returns null when neither
- *  follow_up sentence is present (an error/unrecognized shape). */
+ *  path length, so the shape is recognized by `job_id` plus the stable road-sign
+ *  prefix `Queued for the human` (queuedFollowUp, prompts.ts — its inbox-
+ *  affordance tail resolves per call, the prefix never varies) appearing
+ *  anywhere in the text — never by assuming dir/follow_up's bullet vs. prose
+ *  form. Arrival is always just durable queue state, so the card collapses to
+ *  one posted line. The
+ *  question text isn't in the output at all (only the bare-question invocation
+ *  echoes it), so it's recovered from argv: the first non-flag token after
+ *  `human ask`, skipping `--context-file`'s value — absent for a
+ *  `--context-file` deck invocation, which still gets the road-sign line with
+ *  no question teaser. Returns null when the road-sign is absent (an
+ *  error/unrecognized shape). */
 function summarizeHumanAsk(text, tokens) {
     const jobId = /^- job_id:\s*(\S+)\s*$/m.exec(text)?.[1];
     if (jobId === undefined)
         return null;
-    const drained = text.includes('Not in tmux: a human must drain it');
-    const delivered = text.includes('no need to poll');
-    if (!drained && !delivered)
+    if (!text.includes('Queued for the human'))
         return null;
-    const lines = drained
-        ? [{ text: 'ask posted — drain via `human inbox`', tone: 'warning' }]
-        : [{ text: 'ask posted → waiting on human', tone: 'accent' }];
+    const lines = [{ text: 'ask posted → waiting on human', tone: 'accent' }];
     const question = firstPositionalArg(tokens, 2, new Set(['--context-file']));
     if (question !== undefined) {
         const firstLine = truncateLine(question.split('\n')[0].trim(), ASK_TEASER_CHARS);
@@ -1114,26 +1112,22 @@ function summarizeHumanAsk(text, tokens) {
     }
     return lines;
 }
-/** `crtr human review` (humanReview.run, src/commands/human/prompts.ts:169)
+/** `crtr human review` (humanReview.run, src/commands/human/prompts.ts)
  *  returns `{job_id, dir, output, follow_up}` — same recognition strategy as
- *  summarizeHumanAsk (job_id bullet + one of the two fixed follow_up
- *  sentences, this time followUpReview/followUpDrain). The reviewed file
- *  isn't in the output either, so its basename is recovered from argv (the
- *  file positional, skipping `--output`'s value). Returns null when neither
- *  follow_up sentence is present. */
+ *  summarizeHumanAsk (job_id bullet + the stable `Queued for the human`
+ *  road-sign prefix, which review shares with ask). The
+ *  reviewed file isn't in the output either, so its basename is recovered
+ *  from argv (the file positional, skipping `--output`'s value). Returns null
+ *  when the road-sign is absent. */
 function summarizeHumanReview(text, tokens) {
     const jobId = /^- job_id:\s*(\S+)\s*$/m.exec(text)?.[1];
     if (jobId === undefined)
         return null;
-    const drained = text.includes('Not in tmux: a human must drain it');
-    const live = text.includes("live on the human's screen for anchored, line-by-line review");
-    if (!drained && !live)
+    if (!text.includes('Queued for the human'))
         return null;
     const file = firstPositionalArg(tokens, 2, new Set(['--output']));
     const label = file !== undefined ? `review posted: ${basename(file)}` : 'review posted';
-    return drained
-        ? [{ text: `${label} — drain via \`human inbox\``, tone: 'warning' }]
-        : [{ text: `${label} → waiting on human`, tone: 'accent' }];
+    return [{ text: `${label} → waiting on human`, tone: 'accent' }];
 }
 /** `crtr human list` (humanList.run, src/commands/human/queue.ts:283) has no
  *  custom `render`; the generic renderer bullets `- total: N` then an

package/dist/core/profiles/select.js

@@ -297,10 +297,10 @@ function rootProfileMessage(cwd) {
  *  the session IS interactive. Ask on the controlling terminal — create a
  *  profile pointing at cwd, or proceed as root — and block until answered.
  *  Deliberately a minimal `readline` prompt, not `crtr human ask`: that bridge
- *  is asynchronous (writes a deck, waits for a separate process to answer it)
- *  and cannot gate pi's boot; the codebase's other humanloop entry points
- *  (`launchReview`, the `human _run` bridge) are built for reviewing an
- *  artifact or a queued interaction, not a two-choice gate on the same TTY pi
+ *  is asynchronous (registers an interaction with humanloop, then waits for the
+ *  human to answer it from a separate inbox) and cannot gate pi's boot; the
+ *  humanloop entry points (`human ask`/`review`) are built for a queued,
+ *  asynchronously-answered interaction, not a two-choice gate on the same TTY pi
  *  is about to take over — a raw `readline` question is the actual minimal
  *  fit here. */
 /** Explicit `--profile` names a profile whose manifest does NOT cover cwd.

package/dist/core/runtime/pi-vendored.js

@@ -21,9 +21,23 @@ import { join } from 'node:path';
  *  the sessions dir — same vendoring rationale as the slash-command list below. */
 export function piSessionsRoot() {
     const env = process.env['PI_CODING_AGENT_DIR'];
-    const agentDir = env !== undefined && env !== '' ? env : join(homedir(), '.pi', 'agent');
+    const agentDir = env !== undefined && env !== '' ? expandTilde(env) : join(homedir(), '.pi', 'agent');
     return join(agentDir, 'sessions');
 }
+/** Mirror pi's `expandTildePath` (= `normalizePath` with the default expandTilde
+ *  on): a bare `~` is the home dir, and a leading `~/` (or `~\` on win32) joins
+ *  the remainder under home. pi's `getAgentDir()` runs `PI_CODING_AGENT_DIR`
+ *  through this, so the vendored root must too or `~/custom-pi` yields a broken
+ *  relative path. Other forms (absolute, relative, `~user`) pass through as pi
+ *  leaves them. */
+function expandTilde(p) {
+    if (p === '~')
+        return homedir();
+    if (p.startsWith('~/') || (process.platform === 'win32' && p.startsWith('~\\'))) {
+        return join(homedir(), p.slice(2));
+    }
+    return p;
+}
 /**
  * pi's builtin slash commands — vendored verbatim from pi `core/slash-commands.js`
  * `BUILTIN_SLASH_COMMANDS` (review C1). **21 entries at 0.78.1** (review n1 — NOT 23).

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

@@ -97,7 +97,8 @@ export async function bootRoot(opts) {
     // mandate (bare `crtr` has none — writeGoal no-ops on empty).
     if (opts.prompt !== undefined)
         writeGoal(meta.node_id, opts.prompt);
-    // Reconcile the crouter-owned tmux bindings on this server.
+    // Reconcile the crouter-owned tmux bindings on this server, including the
+    // inbox-toggle key (crtr.tmux.inbox.toggle) folded into the same manifest sweep.
     try {
         installTmuxBindings();
     }

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

@@ -1 +1 @@
-export { installTmuxBindings, sendKeysEnter, displayMessage, paneCurrentPath, type TmuxInstalledPair, type TmuxInstallDiagnostic, type TmuxInstallResult, } from './tmux.js';
+export { installTmuxBindings, legacyInboxKeyFile, sendKeysEnter, displayMessage, paneCurrentPath, type TmuxInstalledPair, type TmuxInstallDiagnostic, type TmuxInstallResult, } from './tmux.js';

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

@@ -1,4 +1,4 @@
 // tmux-chrome.ts — chrome seam (§2.1): stateless keybind/input verbs.
 // The ONLY non-placement module allowed to import the tmux driver, per the
 // §5.1 lint. Re-exports the server chrome callers need.
-export { installTmuxBindings, sendKeysEnter, displayMessage, paneCurrentPath, } from './tmux.js';
+export { installTmuxBindings, legacyInboxKeyFile, sendKeysEnter, displayMessage, paneCurrentPath, } from './tmux.js';

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

@@ -218,5 +218,6 @@ export interface TmuxInstallResult {
     readonly installed: readonly TmuxInstalledPair[];
     readonly diagnostics: readonly TmuxInstallDiagnostic[];
 }
+export declare function legacyInboxKeyFile(): string;
 /** Reconcile the tmux server with one immutable crouter binding snapshot. */
 export declare function installTmuxBindings(bindings?: BindingResolution<BindingId>): TmuxInstallResult;

package/dist/core/runtime/tmux.js

@@ -8,9 +8,13 @@
 // root) or switch-client + select-window (across roots). done/dead nodes close
 // their window; reviving opens a fresh one.
 import { spawnSync } from 'node:child_process';
+import { readFileSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
 import { resolveUserKeybindings, } from '../keybindings/index.js';
 import { bundledPiCommandForShell } from './pi-cli.js';
 import { surfaceTmuxStyleArgs } from './surface-bg.js';
+import { inboxToggleTmuxCommand } from '@crouton-kit/humanloop';
 // ---------------------------------------------------------------------------
 // Shell quoting + tmux invocation
 // ---------------------------------------------------------------------------
@@ -428,6 +432,7 @@ const MENU_ACTIONS = {
     'crtr.tmux.menu.issue.bug': undefined,
     'crtr.tmux.node.next': undefined,
     'crtr.tmux.node.previous': undefined,
+    'crtr.tmux.inbox.toggle': undefined,
     'crtr.tmux.view.next': undefined,
     'crtr.tmux.view.previous': undefined,
 };
@@ -546,12 +551,28 @@ function readManifest() {
         return null;
     }
 }
+// Crouter's own pre-manifest root bindings. When a machine had these installed
+// before the ownership manifest existed, the first reconciliation adopts them
+// into the manifest (unbinding the stale copy so it reinstalls cleanly) instead
+// of reporting them foreign. Gated on a fresh manifest — once one exists these
+// keys are already crouter-owned through it.
 const LEGACY_ROOT_BINDINGS = [
     { key: 'M-c', markers: ['display-menu', 'promote to orchestrator', 'crtr canvas chord', 'new issue / todo'] },
     { key: 'M-]', markers: ['run-shell', 'crtr node cycle --dir next', "--pane '#{pane_id}'"] },
     { key: 'M-[', markers: ['run-shell', 'crtr node cycle --dir prev', "--pane '#{pane_id}'"] },
     { key: 'M-v', markers: ['switch-client', '-T crtr-view'] },
 ];
+// The inbox toggle is a crouter-owned root binding, resolved from keybindings.json
+// and installed through the manifest sweep like every sibling. Root bindings
+// matching these markers that are NOT tracked in the manifest are hl-owned
+// strays; reconciliation removes them (and the state file naming their key) so
+// the manifest stays the sole owner of the inbox command.
+const LEGACY_INBOX_MARKERS = ['run-shell', 'hl inbox toggle'];
+const LEGACY_INBOX_DEFAULT_KEY = 'M-i';
+export function legacyInboxKeyFile() {
+    const stateHome = process.env['XDG_STATE_HOME'] || join(homedir(), '.local', 'state');
+    return join(stateHome, 'humanloop', 'inbox-key');
+}
 function adoptLegacyBindings() {
     for (const legacy of LEGACY_ROOT_BINDINGS) {
         const existing = bindingAt(ROOT_TABLE, legacy.key);
@@ -560,10 +581,42 @@ function adoptLegacyBindings() {
         }
     }
 }
+// Enforce the manifest's sole ownership of the inbox command: any hl-owned
+// inbox binding not tracked in the manifest is unbound, and the humanloop
+// state file is discarded. Runs on every reconciliation regardless of whether
+// a manifest already exists. Checks the default key plus the key the state
+// file records (the file's value only locates a stray binding — it is never
+// imported into crouter config). A key tracked in the manifest is crouter's
+// own and left alone; a foreign non-hl binding never matches the markers and
+// is preserved. Idempotent: with no file and no untracked hl binding, a no-op.
+function removeLegacyInboxBindings(manifestPairs) {
+    const owned = new Set(manifestPairs.filter((pair) => pair.table === ROOT_TABLE).map((pair) => pair.key));
+    const keys = new Set([LEGACY_INBOX_DEFAULT_KEY]);
+    const file = legacyInboxKeyFile();
+    try {
+        const configured = readFileSync(file, 'utf8').trim();
+        if (configured !== '')
+            keys.add(configured);
+    }
+    catch { /* no state file: only the default key can hold a stale binding */ }
+    for (const key of keys) {
+        if (owned.has(key))
+            continue;
+        const existing = bindingAt(ROOT_TABLE, key);
+        if (existing !== null && LEGACY_INBOX_MARKERS.every((marker) => existing.includes(marker))) {
+            tmux(['unbind-key', '-T', ROOT_TABLE, key]);
+        }
+    }
+    try {
+        rmSync(file, { force: true });
+    }
+    catch { /* best-effort */ }
+}
 function actionCommand(id) {
     switch (id) {
         case 'crtr.tmux.node.next': return ['run-shell', `crtr node cycle --dir next --pane '#{pane_id}' >/dev/null 2>&1`];
         case 'crtr.tmux.node.previous': return ['run-shell', `crtr node cycle --dir prev --pane '#{pane_id}' >/dev/null 2>&1`];
+        case 'crtr.tmux.inbox.toggle': return inboxToggleTmuxCommand();
         case 'crtr.tmux.view.next': return ['run-shell', `crtr surface view cycle --dir next --pane '#{pane_id}' >/dev/null 2>&1`];
         case 'crtr.tmux.view.previous': return ['run-shell', `crtr surface view cycle --dir prev --pane '#{pane_id}' >/dev/null 2>&1`];
         default: throw new Error(`no tmux command for ${id}`);
@@ -580,6 +633,7 @@ export function installTmuxBindings(bindings = resolveUserKeybindings()) {
     }
     if (!manifest.existed)
         adoptLegacyBindings();
+    removeLegacyInboxBindings(manifest.pairs);
     for (const pair of manifest.pairs) {
         const result = tmux(['unbind-key', '-T', pair.table, pair.key]);
         if (!result.ok && bindingAt(pair.table, pair.key) !== null) {
@@ -606,7 +660,7 @@ export function installTmuxBindings(bindings = resolveUserKeybindings()) {
     for (const gesture of bindings.gestures('crtr.tmux.menu.open')) {
         install(ROOT_TABLE, tmuxKey(gesture), menuCommand, 'crtr.tmux.menu.open', gesture);
     }
-    for (const id of ['crtr.tmux.node.next', 'crtr.tmux.node.previous']) {
+    for (const id of ['crtr.tmux.node.next', 'crtr.tmux.node.previous', 'crtr.tmux.inbox.toggle']) {
         for (const gesture of bindings.gestures(id))
             install(ROOT_TABLE, tmuxKey(gesture), actionCommand(id), id, gesture);
     }