@crouton-kit/crouter 0.3.83 → 0.3.85

package/dist/commands/human/prompts.js

@@ -8,6 +8,7 @@ import { randomBytes } from 'node:crypto';
 import { tmuxServerReachable } from '../../core/spawn.js';
 import { validateDeck, notifyDeck, atomicWriteJson, submitDeck, submitReview, display, } from '@crouton-kit/humanloop';
 import { DECK_SCHEMA_HINT, registerCrouterRoot, resolveMaxPanes } from './shared.js';
+import { inboxOpenInstruction, inboxPopupHint } from '../../core/keybindings/index.js';
 /** The asking node's id, or null when run from a bare shell (no parent to route to). */
 function askingNode() {
     return process.env['CRTR_NODE_ID'] ?? null;
@@ -32,7 +33,12 @@ function buildHumanAskDeck(question) {
         ],
     });
 }
-const QUEUED_FOLLOW_UP = "Queued for the human. Their answer is pushed to your inbox and wakes you when they respond — never poll, verify it opened, or block. Press ⌥I (or run `hl inbox open` at a terminal) to see the queue.";
+/** The non-blocking status peek returned by ask/review. Resolved per call so
+ *  the inbox affordance reflects the human's current keybinding (or the CLI
+ *  fallback when the toggle is disabled). */
+function queuedFollowUp() {
+    return `Queued for the human. Their answer is pushed to your inbox and wakes you when they respond — never poll, verify it opened, or block. To see the queue, ${inboxOpenInstruction()}.`;
+}
 // ---------------------------------------------------------------------------
 // ask
 // ---------------------------------------------------------------------------
@@ -56,7 +62,7 @@ export const humanAsk = defineLeaf({
         outputKind: 'object',
         effects: [
             'Creates a kind:"human" node under you and enqueues a decision deck in the humanloop inbox.',
-            'Returns immediately; nothing opens on screen. The human answers from the inbox popup (⌥I) on their own time.',
+            `Returns immediately; nothing opens on screen. The human answers from the inbox popup (${inboxPopupHint()}) on their own time.`,
         ],
     },
     run: async (input) => {
@@ -100,7 +106,7 @@ export const humanAsk = defineLeaf({
         atomicWriteJson(join(idir, 'run.json'), rc);
         const root = registerCrouterRoot(cwd);
         const { dir } = submitDeck({ root, id: jobId, deck });
-        return { job_id: jobId, dir, follow_up: QUEUED_FOLLOW_UP };
+        return { job_id: jobId, dir, follow_up: queuedFollowUp() };
     },
 });
 // ---------------------------------------------------------------------------
@@ -113,7 +119,7 @@ export const humanReview = defineLeaf({
     help: {
         name: 'human review',
         summary: "queue a .md for anchored, line-by-line human comments; returns a job handle instantly (a non-blocking kickoff, like ask). The human opens it from the inbox popup, which previews the live doc and re-reads it on every save, so edit in place rather than re-presenting.",
-        guide: "A kickoff, not a blocking call: it returns at once and the human reviews on their own time from the inbox (⌥I). When they submit, the FeedbackResult (anchored comments, plus any line edits they made) is pushed to your inbox — waking you — and autosaved to `output`; you never poll, verify it opened, or background it. The inbox preview is a LIVE view of the file: keep editing the .md in place and it updates, so do not cancel and re-present to show a change. The .md is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one.",
+        guide: `A kickoff, not a blocking call: it returns at once and the human reviews on their own time from the inbox (${inboxPopupHint()}). When they submit, the FeedbackResult (anchored comments, plus any line edits they made) is pushed to your inbox — waking you — and autosaved to \`output\`; you never poll, verify it opened, or background it. The inbox preview is a LIVE view of the file: keep editing the .md in place and it updates, so do not cancel and re-present to show a change. The .md is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see \`termrender doc -h\` for the directive set before authoring one.`,
         params: [
             { kind: 'positional', name: 'file', type: 'path', required: true, constraint: 'Absolute path to an existing .md file.' },
             { kind: 'flag', name: 'output', type: 'path', required: false, constraint: 'Where the FeedbackResult JSON is written. Default: <dir>/feedback.json.' },
@@ -127,7 +133,7 @@ export const humanReview = defineLeaf({
         outputKind: 'object',
         effects: [
             'Creates a kind:"human" node under you and enqueues an anchored review in the humanloop inbox.',
-            'Returns immediately; nothing opens on screen. The human reviews from the inbox popup (⌥I); comments fan into your inbox when they submit.',
+            `Returns immediately; nothing opens on screen. The human reviews from the inbox popup (${inboxPopupHint()}); comments fan into your inbox when they submit.`,
         ],
     },
     run: async (input) => {
@@ -168,7 +174,7 @@ export const humanReview = defineLeaf({
             },
         });
         const output = outputArg !== undefined ? resolve(outputArg) : join(dir, 'feedback.json');
-        return { job_id: jobId, dir, output, follow_up: QUEUED_FOLLOW_UP };
+        return { job_id: jobId, dir, output, follow_up: queuedFollowUp() };
     },
 });
 // ---------------------------------------------------------------------------

package/dist/commands/human.js

@@ -4,13 +4,15 @@
 // the asking node, register the per-cwd interaction root with humanloop (owner
 // 'crouter', `_deliver` handler), submit the deck/review, and return at once —
 // nothing opens on screen. When the human answers from humanloop's inbox popup
-// (⌥I), humanloop invokes the registered `_deliver` handler, which pushFinals
+// (the inbox-toggle keybinding, or `hl inbox open`), humanloop invokes the
+// registered `_deliver` handler, which pushFinals
 // the answer as the bridge node's final report, fanning it into the asking
 // node's inbox. notify enqueues a durable deck with no node; show is passive
 // display. Humanloop owns the queue UI, claims, and atomic finalization.
 import { defineBranch } from '../core/command.js';
 import { humanAsk, humanReview, humanNotify, humanShow } from './human/prompts.js';
 import { humanList, humanDeck, humanResolve, humanCancel, humanDeliver } from './human/queue.js';
+import { inboxOpenInstruction } from '../core/keybindings/index.js';
 export function registerHuman() {
     return defineBranch({
         name: 'human',
@@ -22,7 +24,7 @@ export function registerHuman() {
         help: {
             name: 'human',
             summary: 'human-in-the-loop decisions, document review, and live display',
-            model: "Every body and displayed file is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one. ask and review are kickoffs: they create a kind:'human' bridge node under you and return instantly, never blocking. Nothing opens on screen — the ticket is queued in the humanloop inbox; the human opens it with ⌥I (or `hl inbox open`) on their own time, and their response is pushed to your inbox when they answer, so keep working (or just end your turn) and you'll be woken with it. ask covers everything from a yes/no sign-off gate (two options) to an open-ended judgment call; review queues a .md for anchored comments and the inbox previews the live file, so edit in place rather than canceling and re-presenting. notify enqueues a durable acknowledgement with no node; show is passive live display.",
+            model: `Every body and displayed file is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see \`termrender doc -h\` for the directive set before authoring one. ask and review are kickoffs: they create a kind:'human' bridge node under you and return instantly, never blocking. Nothing opens on screen — the ticket is queued in the humanloop inbox; the human opens it — ${inboxOpenInstruction()} — on their own time, and their response is pushed to your inbox when they answer, so keep working (or just end your turn) and you'll be woken with it. ask covers everything from a yes/no sign-off gate (two options) to an open-ended judgment call; review queues a .md for anchored comments and the inbox previews the live file, so edit in place rather than canceling and re-presenting. notify enqueues a durable acknowledgement with no node; show is passive live display.`,
         },
         children: [
             humanAsk,

package/dist/commands/node.js

@@ -15,6 +15,7 @@ import { writeYieldMessage, readGoal } from '../core/runtime/kickoff.js';
 import { reviveNode } from '../core/runtime/revive.js';
 import { parseOutputSchemaValue, writeOutputSchema } from '../core/runtime/structured-output.js';
 import { newNodeId } from '../core/runtime/nodes.js';
+import { inboxPopupHint } from '../core/keybindings/index.js';
 import { readRoadmap, hasRoadmap, seedRoadmap } from '../core/runtime/roadmap.js';
 import { parseWhen, parseCadence, cadenceDisplay } from '../core/wake.js';
 import { nodeSnapshotLeaf } from './node-snapshot.js';
@@ -642,7 +643,7 @@ const nodeFocus = defineLeaf({
             throw new InputError({
                 error: 'not_focusable',
                 message: `node ${id} is a human-ask (kind:human), not a conversation — it has no pi session to focus.`,
-                next: `The pending question is queued for the human (⌥I opens the inbox popup); see it with \`crtr human list\`, or retract it with \`crtr human cancel ${id}\`.`,
+                next: `The pending question is queued for the human (${inboxPopupHint()} opens the inbox popup); see it with \`crtr human list\`, or retract it with \`crtr human cancel ${id}\`.`,
             });
         }
         // Placement owns the whole act: ensure the target's broker engine is alive

package/dist/commands/sys/__tests__/setup-front-door.test.js

@@ -1,11 +1,11 @@
 // Run with: node --import tsx/esm --test src/commands/sys/__tests__/setup-front-door.test.ts
 //
-// M1 — `crtr sys setup` front-door reconciliation. Setup installs the
-// collision-safe ⌥I inbox popup binding and registers known nodes' interaction
-// roots to owner 'crouter' so a resolved humanloop ticket can call back into the
-// asking node. Both are best-effort. The humanloop registry is isolated with a
-// temp XDG_STATE_HOME (see human-deliver.test.ts); the canvas is isolated with a
-// temp CRTR_HOME + HOME.
+// M1 — `crtr sys setup` front-door reconciliation. Setup registers known nodes'
+// interaction roots to owner 'crouter' so a resolved humanloop ticket can call
+// back into the asking node (best-effort). The inbox-toggle tmux key is a
+// crouter keybinding installed by `installTmuxBindings()`, not reconciled here.
+// The humanloop registry is isolated with a temp XDG_STATE_HOME (see
+// human-deliver.test.ts); the canvas is isolated with a temp CRTR_HOME + HOME.
 import { test, before, beforeEach, after } from 'node:test';
 import assert from 'node:assert/strict';
 import { mkdtempSync, realpathSync } from 'node:fs';
@@ -14,7 +14,7 @@ import { join } from 'node:path';
 import { listInboxRoots } from '@crouton-kit/humanloop';
 import { spawnNode } from '../../../core/runtime/nodes.js';
 import { closeDb } from '../../../core/canvas/index.js';
-import { reconcileInboxFrontDoor, formatInboxBindingLine } from '../setup-core.js';
+import { reconcileInboxFrontDoor } from '../setup-core.js';
 import { sysSetupLeaf } from '../setup.js';
 let home;
 let stateHome;
@@ -46,14 +46,11 @@ test('reconcile registers each known node cwd as an owner-crouter interaction ro
     spawnNode({ kind: 'general', parent: null, cwd: home, name: 'a' });
     spawnNode({ kind: 'general', parent: null, cwd: home, name: 'b' });
     spawnNode({ kind: 'general', parent: null, cwd: otherCwd, name: 'c' });
-    const { binding, interactionRootsRegistered } = reconcileInboxFrontDoor();
+    const { interactionRootsRegistered } = reconcileInboxFrontDoor();
     // Deduped by cwd: two cwds → two registrations.
     assert.equal(interactionRootsRegistered, 2, 'one registration per distinct node cwd');
     const crouterRoots = listInboxRoots().filter((r) => r.owner === 'crouter');
     assert.ok(crouterRoots.length >= 2, 'both interaction roots landed in the humanloop registry as owner crouter');
-    // The binding is best-effort: with or without a tmux server the state is one
-    // of the known values and never throws.
-    assert.ok(['installed', 'collision', 'unbound', 'unavailable'].includes(binding.state), `unexpected binding state: ${binding.state}`);
 });
 test('invoking `crtr sys setup` (non-TTY leaf run) reconciles the front door', async () => {
     // Exercise the real control flow — sysSetupLeaf.run() → runSetup() →
@@ -86,13 +83,3 @@ test('reconcile is idempotent for owner crouter — re-running does not error an
     assert.equal(interactionRootsRegistered, 1);
     assert.ok(listInboxRoots().some((r) => r.owner === 'crouter'));
 });
-test('the summary binding line surfaces the collision remedy', () => {
-    const collision = { state: 'collision', key: 'M-i', isDefault: true };
-    const line = formatInboxBindingLine(collision);
-    assert.match(line, /NOT installed/);
-    assert.match(line, /hl inbox bind --key/);
-    const installed = { state: 'installed', key: 'M-i', isDefault: true };
-    assert.match(formatInboxBindingLine(installed), /\u2325I \(M-i\).*installed/);
-    const unavailable = { state: 'unavailable', key: '', isDefault: false };
-    assert.match(formatInboxBindingLine(unavailable), /unavailable/);
-});

package/dist/commands/sys/setup-core.d.ts

@@ -44,13 +44,6 @@ export interface SetupSubmission {
     composioKey: string;
     composioKeyPath: string;
 }
-/** Outcome of reconciling humanloop's collision-safe ⌥I inbox popup binding
- *  during setup. `unavailable` means the installer threw (no tmux server, etc). */
-export interface SetupInboxBindingResult {
-    state: 'installed' | 'collision' | 'unbound' | 'unavailable';
-    key: string;
-    isDefault: boolean;
-}
 export interface SetupExecutionSummary {
     installed: string[];
     skipped: string[];
@@ -58,7 +51,6 @@ export interface SetupExecutionSummary {
     exaKeyPath: string;
     composioKeyWritten: boolean;
     composioKeyPath: string;
-    inboxBinding: SetupInboxBindingResult;
     interactionRootsRegistered: number;
 }
 export interface SetupInitialState {
@@ -131,14 +123,12 @@ export declare function buildSetupStaticInstructions(opts: {
 export declare function renderSetupStaticInstructions(state: Pick<SetupInitialState, 'manifest' | 'installedPackageIds' | 'systemTools' | 'exaKeyPath' | 'composioKeyPath'>): string;
 export declare function writeExaKey(exaKeyPath: string, exaKey: string): Promise<void>;
 export declare function writeComposioKey(composioKeyPath: string, composioKey: string): Promise<void>;
-/** Reconcile humanloop's collision-safe ⌥I inbox popup binding on the current
- *  tmux server, and register each known node's interaction root to owner
- *  `crouter` so a resolved ticket can call back into `human _deliver`. Both are
- *  best-effort: setup must never fail because tmux is absent or the canvas is
- *  unreadable. Crouter calls humanloop's installer — it never authors its own
- *  tmux command. */
+/** Register each known node's interaction root to owner `crouter` so a resolved
+ *  ticket can call back into `human _deliver`. Best-effort: setup must never
+ *  fail because the canvas is unreadable. The inbox-toggle tmux key is NOT
+ *  reconciled here — it is a crouter keybinding installed by `installTmuxBindings()`
+ *  alongside every other binding. */
 export declare function reconcileInboxFrontDoor(): {
-    binding: SetupInboxBindingResult;
     interactionRootsRegistered: number;
 };
 export declare function summarizeSetupExecution(result: {
@@ -150,9 +140,7 @@ export declare function summarizeSetupExecution(result: {
     exaKeyPath: string;
     composioKeyWritten: boolean;
     composioKeyPath: string;
-    inboxBinding: SetupInboxBindingResult;
     interactionRootsRegistered: number;
 }): SetupExecutionSummary;
-export declare function formatInboxBindingLine(binding: SetupInboxBindingResult): string;
 export declare function formatSetupExecutionSummary(summary: SetupExecutionSummary): string;
 export declare function executeSetupSubmission(submission: SetupSubmission): Promise<SetupExecutionSummary>;

package/dist/commands/sys/setup-core.js

@@ -4,11 +4,10 @@ import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, dirname, join, resolve } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
-import { BINDING_CATALOG, normalizeGesture, resolveKeybindings, } from '../../core/keybindings/index.js';
+import { BINDING_CATALOG, normalizeGesture, inboxShortcut, resolveKeybindings, } from '../../core/keybindings/index.js';
 import { builtinPiPackageDir } from '../../core/scope.js';
 import { readJsonIfExists } from '../../core/fs-utils.js';
 import { resolveBundledPiCliPath } from '../../core/runtime/pi-cli.js';
-import { installInboxBinding } from '@crouton-kit/humanloop';
 import { listNodes } from '../../core/canvas/index.js';
 import { registerCrouterRoot } from '../human/shared.js';
 function isKeybindingsObject(value) {
@@ -426,7 +425,7 @@ export function renderSetupStaticInstructions(state) {
         instructions.exaLine,
         instructions.composioLine,
         '',
-        'Inbox popup: running `crtr sys setup` installs the collision-safe ⌥I humanloop inbox popup binding and registers known nodes\' interaction roots (best-effort; the binding needs a running tmux server). On a key collision, re-bind with `hl inbox bind --key <tmux-key>`.',
+        `Inbox popup: the inbox-toggle key (${inboxShortcut() ?? 'disabled'}) is a crouter keybinding — view or rebind it in the \`crtr sys setup\` keybindings tab; it is installed on the same tmux server as every other crouter binding. \`crtr sys setup\` also registers known nodes' interaction roots (best-effort).`,
         instructions.footer,
     ].join('\n') + '\n';
 }
@@ -452,21 +451,12 @@ export async function writeComposioKey(composioKeyPath, composioKey) {
     await writeFile(composioKeyPath, `${composioKey}\n`, 'utf8');
     await chmod(composioKeyPath, 0o600).catch(() => undefined);
 }
-/** Reconcile humanloop's collision-safe ⌥I inbox popup binding on the current
- *  tmux server, and register each known node's interaction root to owner
- *  `crouter` so a resolved ticket can call back into `human _deliver`. Both are
- *  best-effort: setup must never fail because tmux is absent or the canvas is
- *  unreadable. Crouter calls humanloop's installer — it never authors its own
- *  tmux command. */
+/** Register each known node's interaction root to owner `crouter` so a resolved
+ *  ticket can call back into `human _deliver`. Best-effort: setup must never
+ *  fail because the canvas is unreadable. The inbox-toggle tmux key is NOT
+ *  reconciled here — it is a crouter keybinding installed by `installTmuxBindings()`
+ *  alongside every other binding. */
 export function reconcileInboxFrontDoor() {
-    let binding = { state: 'unavailable', key: '', isDefault: false };
-    try {
-        const state = installInboxBinding();
-        binding = { state: state.state, key: state.key, isDefault: state.isDefault };
-    }
-    catch {
-        /* best-effort: no tmux server / installer unavailable */
-    }
     let interactionRootsRegistered = 0;
     try {
         const seen = new Set();
@@ -486,7 +476,7 @@ export function reconcileInboxFrontDoor() {
     catch {
         /* best-effort: canvas unavailable */
     }
-    return { binding, interactionRootsRegistered };
+    return { interactionRootsRegistered };
 }
 export function summarizeSetupExecution(result) {
     return {
@@ -496,22 +486,9 @@ export function summarizeSetupExecution(result) {
         exaKeyPath: result.exaKeyPath,
         composioKeyWritten: result.composioKeyWritten,
         composioKeyPath: result.composioKeyPath,
-        inboxBinding: result.inboxBinding,
         interactionRootsRegistered: result.interactionRootsRegistered,
     };
 }
-export function formatInboxBindingLine(binding) {
-    switch (binding.state) {
-        case 'installed':
-            return `inbox popup binding: ⌥I (${binding.key})${binding.isDefault ? '' : ' — custom key'} installed`;
-        case 'collision':
-            return `inbox popup binding: NOT installed — ${binding.key} is already bound by another action. Re-bind explicitly with \`hl inbox bind --key <tmux-key>\`.`;
-        case 'unbound':
-            return 'inbox popup binding: not bound';
-        default:
-            return 'inbox popup binding: unavailable (no tmux server)';
-    }
-}
 export function formatSetupExecutionSummary(summary) {
     return [
         'crtr sys setup complete',
@@ -519,7 +496,6 @@ export function formatSetupExecutionSummary(summary) {
         summary.skipped.length > 0 ? `skipped: ${summary.skipped.join(', ')}` : 'skipped: none',
         summary.exaKeyWritten ? `exa key written: ${summary.exaKeyPath}` : 'exa key written: no',
         summary.composioKeyWritten ? `composio key written: ${summary.composioKeyPath}` : 'composio key written: no',
-        formatInboxBindingLine(summary.inboxBinding),
         `interaction roots registered: ${summary.interactionRootsRegistered}`,
     ].join('\n') + '\n';
 }
@@ -556,9 +532,10 @@ export async function executeSetupSubmission(submission) {
     if (composioKeyWritten) {
         await writeComposioKey(submission.composioKeyPath, submission.composioKey);
     }
-    // Front-door reconciliation: install the ⌥I inbox popup binding and register
-    // known nodes' interaction roots for `human _deliver` callback. Best-effort.
-    const { binding, interactionRootsRegistered } = reconcileInboxFrontDoor();
+    // Front-door reconciliation: register known nodes' interaction roots for
+    // `human _deliver` callback. Best-effort. The inbox-toggle key is a crouter
+    // keybinding installed by `installTmuxBindings()`, not reconciled here.
+    const { interactionRootsRegistered } = reconcileInboxFrontDoor();
     return summarizeSetupExecution({
         installedPackages,
         skippedPackages,
@@ -568,7 +545,6 @@ export async function executeSetupSubmission(submission) {
         exaKeyPath: submission.exaKeyPath,
         composioKeyWritten,
         composioKeyPath: submission.composioKeyPath,
-        inboxBinding: binding,
         interactionRootsRegistered,
     });
 }

package/dist/commands/sys/setup.js

@@ -1300,10 +1300,12 @@ export class SetupWizard {
 async function runSetup() {
     const state = buildSetupInitialState();
     // Front-door reconciliation: invoking `crtr sys setup` — TTY or not —
-    // installs the collision-safe ⌥I inbox popup binding and registers known
-    // nodes' interaction roots. Best-effort + idempotent, so it is safe to run on
+    // registers known nodes' interaction roots so resolved tickets can call back
+    // into the asking node. Best-effort + idempotent, so it is safe to run on
     // every invocation regardless of whether the wizard is opened, canceled, or
-    // submitted (the post-submission call re-runs it harmlessly).
+    // submitted (the post-submission call re-runs it harmlessly). The inbox-toggle
+    // tmux key is a crouter keybinding, installed by the catalog/save path through
+    // installTmuxBindings() like every other binding — not reconciled here.
     reconcileInboxFrontDoor();
     if (!process.stdout.isTTY) {
         process.stdout.write(renderSetupStaticInstructions(state));
@@ -1403,7 +1405,7 @@ export const sysSetupLeaf = defineLeaf({
             'Collects companion package installs, system dependency installs, API keys, and sparse user overrides for crouter-owned keybindings across the remaining tabs.',
             'Saves validated keybinding changes atomically in the user config and refreshes crouter-owned tmux bindings without overwriting occupied user keys.',
             'Runs the bundled pi CLI to install the selected companion packages, writes EXA_API_KEY to ~/.crouter/exa.key and COMPOSIO_API_KEY to ~/.crouter/composio.key when provided, and prints a summary.',
-            'On every invocation (best-effort, idempotent), installs the collision-safe ⌥I humanloop inbox popup binding on the current tmux server (leaving any pre-existing binding untouched and reporting the collision remedy) and registers known nodes\' interaction roots so resolved tickets can call back into the asking node.',
+            'On every invocation (best-effort, idempotent), registers known nodes\' interaction roots so resolved tickets can call back into the asking node. The inbox popup toggle is a crouter-owned keybinding, edited on the keybindings tab and installed through the catalog/save path alongside every other tmux binding.',
         ],
     },
     run: async () => {

package/dist/core/__tests__/boot.test.js

@@ -17,15 +17,22 @@ import assert from 'node:assert/strict';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { createNode, getRow, recordPid } from '../canvas/canvas.js';
-import { closeDb } from '../canvas/db.js';
-import { bootChanged, reconcileBootLiveness } from '../canvas/boot.js';
+import { createNode, getRow, recordPid, migrateLegacyPidIdentities } from '../canvas/canvas.js';
+import { closeDb, openDb } from '../canvas/db.js';
+import { bootChanged, bootProvenSame, reconcileBootLiveness, reconcileAndMigrateBoot, } from '../canvas/boot.js';
 let home;
 /** Build a BootIdentity for injection. `bootId` null models the non-Linux
  *  fallback (wall-clock window); a string models the exact kernel boot_id. */
 function ident(bootId, bootEpochMs) {
     return { bootId, bootEpochMs };
 }
+const BOOT_A = '4b0c1d2e-3f40-4152-8637-a1b2c3d4e5f6';
+/** Force a row's recorded pid + identity baseline directly (recordPid derives
+ *  the identity from the real `ps`, which can't produce a controlled legacy
+ *  `lstart#ticks` value on a non-Linux test host). */
+function setPidIdentity(id, pid, identity) {
+    openDb().prepare('UPDATE nodes SET pi_pid = ?, pi_pid_identity = ? WHERE node_id = ?').run(pid, identity, id);
+}
 function node(id, over = {}) {
     return {
         node_id: id,
@@ -80,12 +87,60 @@ test('bootChanged: wall-clock fallback (no boot_id) — epochs far apart are a D
 // ---------------------------------------------------------------------------
 // reconcileBootLiveness — the impure sweep against a real canvas.db
 // ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// migrateLegacyPidIdentities — one-time in-place format migration at startup
+// ---------------------------------------------------------------------------
+test('migrateLegacyPidIdentities: a live legacy lstart#ticks broker is re-recorded to <bootId>#<ticks>', () => {
+    createNode(node('n1'));
+    setPidIdentity('n1', 111, 'Sat Jul 11 17:51:45 2026#53459'); // legacy baseline
+    // The pid still names the same live process; its CURRENT identity on this
+    // (now boot_id-capable) platform reads bootId#ticks with the SAME ticks.
+    const result = migrateLegacyPidIdentities((pid) => (pid === 111 ? `${BOOT_A}#53459` : undefined));
+    assert.deepEqual(result.migrated, ['n1']);
+    assert.equal(getRow('n1')?.pi_pid_identity, `${BOOT_A}#53459`, 'legacy row completed to boot-scoped format');
+    assert.equal(getRow('n1')?.pi_pid, 111, 'the pid itself is untouched');
+});
+test('migrateLegacyPidIdentities: a legacy row whose pid is GONE is left to normal liveness handling', () => {
+    createNode(node('n1'));
+    setPidIdentity('n1', 111, 'Sat Jul 11 17:51:45 2026#53459');
+    const result = migrateLegacyPidIdentities(() => undefined); // pid gone / probe failed
+    assert.deepEqual(result.migrated, []);
+    assert.equal(getRow('n1')?.pi_pid_identity, 'Sat Jul 11 17:51:45 2026#53459', 'untouched — liveness handles it');
+});
+test('migrateLegacyPidIdentities: a REUSED pid (different ticks) is NOT re-recorded', () => {
+    createNode(node('n1'));
+    setPidIdentity('n1', 111, 'Sat Jul 11 17:51:45 2026#53459');
+    // The pid now names a DIFFERENT process (different jiffies) — no match.
+    const result = migrateLegacyPidIdentities(() => `${BOOT_A}#99999`);
+    assert.deepEqual(result.migrated, []);
+    assert.equal(getRow('n1')?.pi_pid_identity, 'Sat Jul 11 17:51:45 2026#53459', 'reused pid left for liveness to clear');
+});
+test('migrateLegacyPidIdentities: an already boot-scoped row is skipped (not legacy)', () => {
+    createNode(node('n1'));
+    setPidIdentity('n1', 111, `${BOOT_A}#53459`); // already new-format
+    let captured = false;
+    const result = migrateLegacyPidIdentities(() => {
+        captured = true;
+        return `${BOOT_A}#53459`;
+    });
+    assert.deepEqual(result.migrated, []);
+    assert.equal(captured, false, 'a non-legacy row is filtered out before any ps probe');
+});
+test('migrateLegacyPidIdentities: no readable boot_id (current identity still legacy) leaves the row untouched', () => {
+    createNode(node('n1'));
+    setPidIdentity('n1', 111, 'Sat Jul 11 17:51:45 2026#53459');
+    // Platform still composes legacy-shaped identities (no boot_id) — nothing to
+    // upgrade to; the legacy compare lane legitimately stays in play.
+    const result = migrateLegacyPidIdentities(() => 'Sun Jul 12 09:00:00 2026#53459');
+    assert.deepEqual(result.migrated, []);
+    assert.equal(getRow('n1')?.pi_pid_identity, 'Sat Jul 11 17:51:45 2026#53459', 'no boot_id → not migrated');
+});
 test('reconcileBootLiveness: first-ever call seeds the marker and clears nothing', () => {
     const m = node('n1');
     createNode(m);
     recordPid('n1', 12345);
     const result = reconcileBootLiveness(ident('boot-A', 1_000_000));
-    assert.deepEqual(result, { changed: false, cleared: [] });
+    assert.deepEqual(result, { changed: false, cleared: [], sameBootProven: false });
     assert.equal(getRow('n1')?.pi_pid, 12345, 'a first-ever run never clears an existing pid');
 });
 test('reconcileBootLiveness: same boot (same boot_id) leaves pids untouched — MUST NOT weaken the normal daemon-restart case', () => {
@@ -94,7 +149,7 @@ test('reconcileBootLiveness: same boot (same boot_id) leaves pids untouched —
     recordPid('n1', 12345);
     reconcileBootLiveness(ident('boot-A', 1_000_000)); // seed
     const result = reconcileBootLiveness(ident('boot-A', 1_000_000 + 3_000)); // 3s later, same boot
-    assert.deepEqual(result, { changed: false, cleared: [] });
+    assert.deepEqual(result, { changed: false, cleared: [], sameBootProven: true });
     assert.equal(getRow('n1')?.pi_pid, 12345, 'a live pid on the same boot is never cleared');
 });
 test('reconcileBootLiveness: a boot change clears every recorded pid, regardless of status', () => {
@@ -135,6 +190,86 @@ test('reconcileBootLiveness: after reconciling, the SAME boot no longer re-trigg
     reconcileBootLiveness(ident('boot-B', 1_000_000 + 60 * 60_000)); // boot change → clears + persists boot B
     recordPid('n1', 999); // a fresh broker re-records its pid post-revive
     const result = reconcileBootLiveness(ident('boot-B', 1_000_000 + 60 * 60_000 + 2_000)); // still boot B, 2s later
-    assert.deepEqual(result, { changed: false, cleared: [] });
+    assert.deepEqual(result, { changed: false, cleared: [], sameBootProven: true });
     assert.equal(getRow('n1')?.pi_pid, 999, 'a pid recorded AFTER reconciliation, within the same boot, is never touched');
 });
+// ---------------------------------------------------------------------------
+// bootProvenSame + the daemon migration gate (Major-1 regression)
+//
+// The legacy identity migration blesses a recorded pid as a current-boot
+// process on a bare ticks match, so it may run ONLY when same-boot provenance
+// is POSITIVELY proven (exact boot_id equal on both sides). `!bootChanged` is
+// NOT that proof — it is also true with no/malformed marker or the wall-clock
+// epoch fallback, where an unrelated cross-boot process can collide on
+// pid+ticks and be permanently baptized.
+// ---------------------------------------------------------------------------
+test('bootProvenSame: exact equal boot_id on both sides is proof', () => {
+    assert.equal(bootProvenSame(ident('boot-A', 2_000), ident('boot-A', 1_000)), true);
+});
+test('bootProvenSame: no history is NOT proof (absent/malformed marker)', () => {
+    assert.equal(bootProvenSame(ident('boot-A', 1_000), null), false);
+});
+test('bootProvenSame: a missing boot_id on EITHER side is NOT proof (epoch fallback)', () => {
+    assert.equal(bootProvenSame(ident(null, 1_000), ident('boot-A', 1_000)), false, 'current lacks boot_id');
+    assert.equal(bootProvenSame(ident('boot-A', 1_000), ident(null, 1_000)), false, 'known lacks boot_id');
+    assert.equal(bootProvenSame(ident(null, 1_000), ident(null, 1_000)), false, 'both lack boot_id');
+});
+test('bootProvenSame: a different boot_id is not proof (it is a change)', () => {
+    assert.equal(bootProvenSame(ident('boot-B', 1_000), ident('boot-A', 1_000)), false);
+});
+// Drive the ACTUAL production startup composition (reconcile, then gate the
+// migration on proven same-boot provenance) rather than a test-side copy, so a
+// revert that inverts/drops the gate or reorders migration ahead of
+// reconciliation is caught here. `runDaemon` calls this same helper.
+function daemonBootStartup(current, captureIdentity) {
+    return reconcileAndMigrateBoot(migrateLegacyPidIdentities, current, captureIdentity);
+}
+const LEGACY = 'Sat Jul 11 17:51:45 2026#53459';
+test('migration gate: a cross-boot equal-ticks legacy row is NOT migrated when the marker is ABSENT (first-ever startup)', () => {
+    createNode(node('n1'));
+    setPidIdentity('n1', 111, LEGACY);
+    // No marker yet. A current-boot stranger process happens to hold pid 111 with
+    // the same ticks — an equal-ticks collision that would falsely migrate if the
+    // sweep ran. It must NOT: provenance is unproven.
+    const result = daemonBootStartup(ident(BOOT_A, 1_000_000), () => `${BOOT_A}#53459`);
+    assert.deepEqual(result.migrated, [], 'no marker → unproven → migration skipped');
+    assert.equal(getRow('n1')?.pi_pid_identity, LEGACY, 'the stranger is NOT baptized as the recorded process');
+});
+test('migration gate: a cross-boot equal-ticks legacy row is NOT migrated under the epoch fallback (no boot_id)', () => {
+    createNode(node('n1'));
+    setPidIdentity('n1', 111, LEGACY);
+    reconcileBootLiveness(ident(null, 1_000_000)); // seed a no-boot_id marker
+    // A transient current boot_id read failure: reconcile sees null on both sides,
+    // the epochs are within tolerance so no change is DETECTED, but same-boot is
+    // NOT PROVEN. A cross-boot pid+ticks collision must not be migrated.
+    const result = daemonBootStartup(ident(null, 1_000_000 + 5_000), () => `${BOOT_A}#53459`);
+    assert.deepEqual(result.migrated, [], 'epoch fallback → unproven → migration skipped');
+    assert.equal(getRow('n1')?.pi_pid_identity, LEGACY, 'not migrated on an unproven boot');
+});
+test('migration gate: a legacy row IS migrated when same-boot provenance is PROVEN (exact boot_id match)', () => {
+    createNode(node('n1'));
+    setPidIdentity('n1', 111, LEGACY);
+    reconcileBootLiveness(ident(BOOT_A, 1_000_000)); // seed an exact-boot_id marker
+    // Same boot proven (boot_id equal on both sides); pid 111 still names the same
+    // live process (matching ticks) — the in-place upgrade completes.
+    const result = daemonBootStartup(ident(BOOT_A, 1_000_000 + 3_000), (pid) => pid === 111 ? `${BOOT_A}#53459` : undefined);
+    assert.deepEqual(result.migrated, ['n1']);
+    assert.equal(getRow('n1')?.pi_pid_identity, `${BOOT_A}#53459`, 'proven same boot → migrated in place');
+});
+test('migrateLegacyPidIdentities CAS: a concurrent re-record between probe and update is not clobbered', () => {
+    createNode(node('n1'));
+    setPidIdentity('n1', 111, LEGACY);
+    // The capture models the old broker still probing as its live legacy self,
+    // but a concurrent revive atomically re-records a FRESH (pid, identity) pair
+    // before the sweep's compare-and-swap update lands.
+    const result = migrateLegacyPidIdentities((pid) => {
+        if (pid === 111) {
+            setPidIdentity('n1', 222, `${BOOT_A}#77777`); // concurrent revive wins the row
+            return `${BOOT_A}#53459`; // stale probe result for the OLD pid
+        }
+        return undefined;
+    });
+    assert.deepEqual(result.migrated, [], 'CAS matched zero rows — no migration counted');
+    assert.equal(getRow('n1')?.pi_pid, 222, 'the concurrent revive pid stands');
+    assert.equal(getRow('n1')?.pi_pid_identity, `${BOOT_A}#77777`, 'the fresh identity is NOT overwritten by the stale one');
+});

package/dist/core/__tests__/pid-identity-match.test.js

@@ -24,7 +24,7 @@
 // when a base is NOT a boot_id UUID on either side, ticks decide alone.
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { identitiesMatch } from '../canvas/pid.js';
+import { identitiesMatch, composeIdentity, makeBootIdCache } from '../canvas/pid.js';
 test('equal ticks with DIFFERENT lstart bases compare EQUAL (the btime-drift bug)', () => {
     // Same live process, same jiffies-since-boot; only the wall-clock-anchored
     // lstart drifted because btime shifted. Must NOT read as reuse.
@@ -71,6 +71,68 @@ test('migration: legacy lstart#ticks vs new bootId#ticks with equal ticks → ma
     assert.equal(identitiesMatch(`${BOOT_A}#53459`, 'Sat Jul 11 17:51:45 2026#53459'), true, 'order-independent');
     assert.equal(identitiesMatch('Sat Jul 11 17:51:45 2026#60536', `${BOOT_A}#53459`), false, 'legacy migration still discriminates on ticks');
 });
+// --- composeIdentity composition (guards against a regression that emits the
+//     old wall-clock `lstart#ticks` on a boot_id-capable host) ---
+test('composeIdentity: procfs + boot_id host emits <bootId>#<ticks> with the base equal to the kernel boot_id', () => {
+    // The exact production-guest shape. The `deps` seam injects the boot_id and
+    // ticks so the composition is provable off-Linux (real /proc reads return
+    // null there). If composeIdentity regressed to emitting lstart#ticks, the
+    // base here would be the lstart string, not BOOT_A — this asserts it is not.
+    const id = composeIdentity(1234, 'Sat Jul 11 17:51:45 2026', { bootId: BOOT_A, ticks: '53459' });
+    assert.equal(id, `${BOOT_A}#53459`, 'base must be the kernel boot_id, not the wall-clock lstart');
+    assert.equal(splitBase(id), BOOT_A);
+});
+test('composeIdentity: procfs but NO readable boot_id falls back to <lstart>#<ticks>', () => {
+    const id = composeIdentity(1234, 'Sat Jul 11 17:51:45 2026', { bootId: null, ticks: '53459' });
+    assert.equal(id, 'Sat Jul 11 17:51:45 2026#53459', 'no boot_id → prior lstart#ticks behavior');
+});
+test('composeIdentity: no procfs ticks emits the bare <lstart> (coarse, unchanged)', () => {
+    const id = composeIdentity(1234, 'Sat Jul 11 17:51:45 2026', { bootId: BOOT_A, ticks: null });
+    assert.equal(id, 'Sat Jul 11 17:51:45 2026', 'no ticks → bare lstart regardless of boot_id');
+});
+function splitBase(identity) {
+    const i = identity.indexOf('#');
+    return i === -1 ? identity : identity.slice(0, i);
+}
+// --- boot_id cache: a TRANSIENT read failure must be retried, never cached as
+//     permanent absence (would permanently downgrade a boot_id host to legacy
+//     lstart#ticks identities). This exercises the exact memoize used by
+//     bootIdBase. ---
+test('makeBootIdCache: a null read is negative-cached, RETRIED only after the window, then a success is cached forever', () => {
+    let calls = 0;
+    const reads = [null, BOOT_A, BOOT_B];
+    let clock = 1_000;
+    const cache = makeBootIdCache(() => {
+        const v = calls < reads.length ? reads[calls] : BOOT_B;
+        calls += 1;
+        return v;
+    }, () => clock, 100);
+    assert.equal(cache(), null, 'first read failed → null (not cached)');
+    assert.equal(calls, 1);
+    assert.equal(cache(), null, 'within the negative window → NOT re-read');
+    assert.equal(calls, 1, 'the throwing read is rate-limited, not repeated every call');
+    clock += 100; // advance past the negative-cache deadline
+    assert.equal(cache(), BOOT_A, 'after the window the failure is retried → succeeds');
+    assert.equal(calls, 2);
+    clock += 10_000;
+    assert.equal(cache(), BOOT_A, 'success is now cached → reader NOT called again');
+    assert.equal(calls, 2, 'no further reads after a successful one');
+});
+test('makeBootIdCache: a permanent no-boot_id host reads null only once per negative window (bounded, not per-call)', () => {
+    let calls = 0;
+    let clock = 1_000;
+    const cache = makeBootIdCache(() => {
+        calls += 1;
+        return null;
+    }, () => clock, 100);
+    assert.equal(cache(), null);
+    assert.equal(cache(), null);
+    assert.equal(cache(), null);
+    assert.equal(calls, 1, 'repeated calls within one window do a SINGLE read — no synchronous read storm');
+    clock += 100;
+    assert.equal(cache(), null);
+    assert.equal(calls, 2, 'one read per window — still retryable for a transient miss, but bounded');
+});
 test('malformed/empty ticks suffix is treated as ABSENT (base compare applies)', () => {
     // A garbage suffix must never be trusted as a fine discriminator; it falls
     // back to the base compare.