@north-light/crouter 0.3.154

package/dist/commands/view.js

@@ -0,0 +1,31 @@
+// `crtr surface view` — the TUI view library.
+//
+// Views are switchable surfaces with two targets from one portable core.mjs:
+// the tmux TUI (`run`) and a React+Tailwind web page. This branch assembles the
+// TUI-side leaves: `list` enumerates what's available, `run` hosts the TUI
+// target (interactive in tmux, static dump when piped), `new` scaffolds a fresh
+// view directory, and the hidden `pick` backs the /view popup. Each leaf owns
+// its own help one level down. The web target is no longer served per-view here:
+// it is hosted by the unified surface web server (the shell's /view/<id> route).
+import { defineBranch } from '../core/command.js';
+import { viewListLeaf } from './view-list.js';
+import { viewRunLeaf } from './view-run.js';
+import { viewCycleLeaf } from './view-cycle.js';
+import { viewNewLeaf } from './view-new.js';
+import { viewPickLeaf } from './view-pick.js';
+export function registerView() {
+    return defineBranch({
+        name: 'view',
+        rootEntry: {
+            concept: 'switchable raw-ANSI terminal views — full-screen surfaces hosted in a pane, each a self-contained module',
+            desc: 'list, run, and author TUI views',
+            useWhen: 'you want a live full-screen surface (a monitor, an inbox, a dashboard) rather than one-shot command output — run a view by name, list what exists, or scaffold a new one. Views have no pi session; they render + take keystrokes until you quit.',
+        },
+        help: {
+            name: 'view',
+            summary: 'host and author switchable raw-ANSI terminal views',
+            model: 'The branch divides into listing, hosting, cycling, authoring, and the hidden picker. `list` is the roster; `run` hosts a named view in the current pane or a monitor pane; `cycle` advances a monitor in place; `new` scaffolds a view directory; `pick` backs the popup. The browser target is part of the web surface, not this branch.',
+        },
+        children: [viewListLeaf, viewRunLeaf, viewCycleLeaf, viewNewLeaf, viewPickLeaf],
+    });
+}

package/dist/commands/workspace.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../core/command.js';
+export declare function registerWorkspace(): BranchDef;

package/dist/commands/workspace.js

@@ -0,0 +1,165 @@
+// workspace.ts — `crtr workspace enter`: the agent-centric editor layout.
+//
+// Turns the current tmux window into an editor view for attached headless nodes:
+// a narrow LEFT rail (the `workspace-sidebar` view — this graph + other live
+// agents in this cwd, with ⚑ inbox flags) beside a CHAT pane (surface attach).
+// Selecting a node in the rail swaps it into the chat pane.
+//
+// Layout build (the only two driver acts, both through placement's seam):
+//   1. splitWindow(here, before+size) → the rail pane, left of here, runs
+//      the workspace-sidebar view host.
+//   2. `crtr surface node focus <node> --pane <here>` → swaps the chat node's attach
+//      viewer into here's slot (here's old content relocates to the backstage).
+// The rail finds the chat pane by DISCOVERY (the `@crtr_node` tag attach sets),
+// so it is robust to that swap — no launch-time pane id is threaded into it.
+//
+// Command shape: under `crtr surface workspace`, this is a BRANCH wrapping one
+// leaf: `enter`.
+import { execFile } from 'node:child_process';
+import { defineBranch, defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { cliCanvasSource } from './api-client.js';
+// NB: node resolution (getNode/listNodes) now reads via the daemon API
+// (cliCanvasSource). The tmux/editor placement helpers below are pure tmux
+// verbs sourced from the canvas-free placement-tmux seam, so this leaf reaches
+// ZERO canvas.db/canvas.js code.
+import { inTmux, currentTmux, splitWindow, piCommand } from '../core/runtime/placement-tmux.js';
+const RAIL_WIDTH = 32;
+/** Newest LIVE (active|idle) forest root started in `cwd` — the default node the
+ *  chat pane attaches to when `--node` is omitted. A root has no parent inside
+ *  the cwd-scoped set. Returns null when this cwd has no live root. */
+async function defaultChatNode(cwd) {
+    const rows = (await cliCanvasSource().listNodes({ status: ['active', 'idle'] })).filter((r) => r.cwd === cwd);
+    if (rows.length === 0)
+        return null;
+    const ids = new Set(rows.map((r) => r.node_id));
+    const roots = rows.filter((r) => r.parent === null || !ids.has(r.parent));
+    const pool = roots.length > 0 ? roots : rows;
+    pool.sort((a, b) => (a.created < b.created ? 1 : -1)); // newest first
+    return pool[0].node_id;
+}
+const workspaceEnterLeaf = defineLeaf({
+    name: 'enter',
+    description: 'enter the editor view — a node rail beside a chat pane, in this window',
+    whenToUse: 'you want to work in the agent-centric editor layout: a left rail listing this graph plus the other live agents in this working directory (with ⚑ inbox flags) beside a chat pane attached to a node. Selecting a node in the rail swaps it into the chat pane. Opens in the current tmux window. tmux-only.',
+    help: {
+        name: 'workspace enter',
+        summary: 'split the current window into a left node-rail (the workspace-sidebar view) + a chat pane (surface attach); ↵ in the rail swaps a node into the chat. tmux-only.',
+        params: [
+            {
+                kind: 'flag',
+                name: 'node',
+                type: 'string',
+                required: false,
+                constraint: 'Node to attach in the chat pane. Default: the newest live root in this cwd (rail-only, empty chat, if none).',
+            },
+            {
+                kind: 'flag',
+                name: 'width',
+                type: 'int',
+                required: false,
+                default: RAIL_WIDTH,
+                constraint: `Rail width in columns (default ${RAIL_WIDTH}).`,
+            },
+        ],
+        output: [
+            { name: 'rail', type: 'string', required: false, constraint: 'tmux pane id of the rail.' },
+            { name: 'chat', type: 'string', required: false, constraint: 'node id attached in the chat pane (absent if none).' },
+            { name: 'note', type: 'string', required: false, constraint: 'Set only on the non-TTY/piped path.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Splits a narrow LEFT pane in the current window running the workspace-sidebar view.',
+            'Swaps the chosen (or default) node into the current pane as a chat (`crtr surface node focus`), relocating the current pane to the backstage.',
+            'Outside a TTY/tmux: prints a notice and exits 0 (no layout change).',
+        ],
+    },
+    run: async (input) => {
+        const node = input['node'];
+        const width = input['width'] ?? RAIL_WIDTH;
+        if (!process.stdout.isTTY) {
+            return { note: 'surface workspace enter builds a tmux layout — run it in a tmux pane (a TTY), not a pipe.' };
+        }
+        if (!inTmux()) {
+            throw new InputError({
+                error: 'not_in_tmux',
+                message: 'surface workspace is tmux-only — run it inside the crtr tmux session',
+                next: 'Open it from inside tmux.',
+            });
+        }
+        const here = currentTmux();
+        if (here === null) {
+            throw new InputError({
+                error: 'no_tmux_location',
+                message: 'could not resolve the current tmux pane',
+                next: 'Run this inside a tmux pane.',
+            });
+        }
+        // Resolve the chat node (explicit --node, else newest live root here).
+        let chatNode = null;
+        if (node !== undefined && node !== '') {
+            if ((await cliCanvasSource().getNode(node)) === null) {
+                throw new InputError({
+                    error: 'not_found',
+                    message: `no node: ${node}`,
+                    received: node,
+                    next: 'List nodes with `crtr node inspect list`.',
+                });
+            }
+            chatNode = node;
+        }
+        else {
+            chatNode = await defaultChatNode(process.cwd());
+        }
+        // 1. The rail — a narrow split to the LEFT of here. It discovers the chat
+        //    pane itself (the @crtr_node tag), so no pane id is threaded in.
+        const railCmd = piCommand(['surface', 'view', 'run', 'workspace-sidebar', '--target', here.pane], 'crtr');
+        const rail = splitWindow(here.pane, {
+            cwd: process.cwd(),
+            env: {},
+            command: railCmd,
+            before: true,
+            size: Math.max(16, width),
+        });
+        if (rail === null) {
+            throw new InputError({
+                error: 'split_failed',
+                message: 'tmux could not split the rail pane',
+                next: 'Check the tmux server is reachable, then retry.',
+            });
+        }
+        // 2. The chat — swap the node's attach viewer into here's slot. Best-effort:
+        //    the rail is already up, so a focus failure degrades to a rail-only view
+        //    the user can drive (↵ a node) rather than aborting the whole layout.
+        if (chatNode !== null) {
+            await new Promise((resolve) => {
+                execFile('crtr', ['surface', 'node', 'focus', chatNode, '--pane', here.pane], () => resolve());
+            });
+        }
+        return chatNode !== null ? { rail, chat: chatNode } : { rail };
+    },
+    render: (result) => {
+        if (result['note'] !== undefined)
+            return String(result['note']);
+        const chat = result['chat'];
+        return chat !== undefined
+            ? `Workspace ready — rail ${result['rail']}, chat attached to ${chat}.`
+            : `Workspace ready — rail ${result['rail']}. No live agent here yet; press ↵ on a node in the rail to open one.`;
+    },
+});
+export function registerWorkspace() {
+    return defineBranch({
+        name: 'workspace',
+        rootEntry: {
+            concept: 'the agent-centric editor view — a node rail beside a chat pane, in one tmux window',
+            desc: 'enter the editor layout for attached headless nodes',
+            useWhen: 'you want an editor-style workspace in tmux: a left rail of this graph + other live agents in this cwd (with ⚑ inbox flags) next to a chat pane attached to a node, where selecting a node in the rail swaps it into the chat. tmux-only.',
+        },
+        help: {
+            name: 'workspace',
+            summary: 'enter the agent-centric editor view (node rail + chat pane) in the current tmux window',
+            model: 'The branch is a two-pane editor layout: a narrow left rail and a chat pane. The rail shows this graph plus the other live agents in the working directory, and selecting a node swaps it into chat. tmux-only; piped input prints a notice and exits 0.',
+        },
+        children: [workspaceEnterLeaf],
+    });
+}

package/dist/core/__tests__/base-worker-prompt.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/base-worker-prompt.test.js

@@ -0,0 +1,60 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { renderPreferencesForSubject } from '../substrate/render.js';
+function subject(mode, kind = 'plan/reviewers/security') {
+    return {
+        kind,
+        mode,
+        lifecycle: 'terminal',
+        hasManager: true,
+        cwd: process.cwd(),
+        scope: 'project',
+        orchestration: { depth: 1 },
+        profile: null,
+    };
+}
+test('base sub-personas receive hands-on guidance instead of universal delegation pressure', () => {
+    const base = renderPreferencesForSubject(subject('base')).block;
+    assert.match(base, /You are a hands-on worker/);
+    assert.match(base, /Each child gets a bounded outcome distinct from your whole assignment/);
+    assert.doesNotMatch(base, /Hand any self-contained unit of work to a child/);
+    const orchestrator = renderPreferencesForSubject(subject('orchestrator')).block;
+    assert.doesNotMatch(orchestrator, /You are a hands-on worker/);
+    assert.match(orchestrator, /You are an orchestrator/);
+});
+test('developer orchestrators gate only fact-dependent decisions on explore synthesis', () => {
+    const prompt = renderPreferencesForSubject(subject('orchestrator', 'developer')).block;
+    assert.match(prompt, /When a downstream decision depends on unknown source facts.*?Wait for every scout in that evidence wave's final completion result \(`crtr push final`\), not merely an update.*?synthesize the findings into one factual artifact.*?specialist who owns the decision/s);
+    assert.match(prompt, /The scout artifact ends at evidence/);
+    assert.match(prompt, /Independent work that does not depend on the pending facts may proceed in parallel/);
+    assert.match(prompt, /absolute artifact path plus every relevant report or context path/);
+    assert.doesNotMatch(prompt, /first wave explore-only|before launching downstream advisor, spec, design, plan, developer, and review children|Wait for every explore report/);
+});
+test('review guidance bounds one critique pass and closes through evidence', () => {
+    const developer = renderPreferencesForSubject(subject('orchestrator', 'developer')).block;
+    assert.match(developer, /one independent review assignment/);
+    assert.match(developer, /Validation means executing acceptance criteria.*?evidence, not review/s);
+    assert.doesNotMatch(developer, /Hand each lens to its own reviewer|idle capacity is a wasted wake|When in doubt, more rigor/);
+    const reviewOrchestrator = renderPreferencesForSubject(subject('orchestrator', 'review')).block;
+    assert.match(reviewOrchestrator, /Choose the one decomposition axis/);
+    assert.match(reviewOrchestrator, /at most five base review children.*?in one wave/s);
+    assert.match(reviewOrchestrator, /Never delegate synthesis, adjudication, or validation of the synthesis/);
+    assert.doesNotMatch(reviewOrchestrator, /Decompose the surface two ways/);
+    const reviewWorker = renderPreferencesForSubject(subject('base', 'review')).block;
+    assert.match(reviewWorker, /A slice delegated by another reviewer remains base/);
+    const planner = renderPreferencesForSubject(subject('orchestrator', 'plan')).block;
+    assert.match(planner, /one independent review pass/);
+    assert.doesNotMatch(planner, /Fan out your plan-reviewer sub-kinds|loops review.*?re-review/s);
+});
+test('explore personas keep current-state evidence separate from target-state decisions', () => {
+    const base = renderPreferencesForSubject(subject('base', 'explore')).block;
+    assert.match(base, /fast current-state codebase scout/);
+    assert.match(base, /Root cause and recommendations belong to `advisor`, target architecture to `design`, required behavior and acceptance criteria to `spec`, and implementation decomposition to `plan`/);
+    assert.match(base, /A task cannot expand your role: even when it explicitly asks, \*\*never\*\* produce those decisions/);
+    assert.match(base, /leave any requested diagnosis, recommendation, target design, acceptance criteria, or implementation breakdown unperformed/);
+    assert.doesNotMatch(base, /answer architecture questions|suggest changes beyond what was asked/);
+    const orchestrator = renderPreferencesForSubject(subject('orchestrator', 'explore')).block;
+    assert.match(orchestrator, /current-state research question/);
+    assert.match(orchestrator, /even when it explicitly asks for diagnosis or a target-state decision, gather only the facts.*?return the unperformed handoff to the matching specialist/);
+    assert.match(orchestrator, /factual synthesis.*not a pile of transcripts or a proposed solution/);
+});

package/dist/core/__tests__/boot-fault-attempt.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/boot-fault-attempt.test.js

@@ -0,0 +1,83 @@
+// beginBootFaultAttempt: the launch/revive paths' one mechanism for scoping a
+// boot-failure diagnostic to the attempt that is actually failing, never a
+// stale marker left by an earlier one.
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { beginBootFaultAttempt, recordFault } from '../runtime/fault.js';
+let home;
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-boot-fault-attempt-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    rmSync(home, { recursive: true, force: true });
+});
+test('a fatal crtr→pi fault recorded after the snapshot is surfaced', { timeout: 1_000 }, () => {
+    const attempt = beginBootFaultAttempt('node-a');
+    recordFault('node-a', {
+        link: 'crtr→pi',
+        op: 'model resolution at launch',
+        kind: 'model-not-found',
+        retry: { disposition: 'fatal' },
+        message: "model 'bogus' has no 'provider/id' form and cannot be resolved",
+    });
+    assert.equal(attempt.explanation(), "model resolution at launch: model 'bogus' has no 'provider/id' form and cannot be resolved");
+});
+test('a stale fault already present at snapshot time is never surfaced, even if a matching-shape fault is written afterward (fail closed)', { timeout: 1_000 }, () => {
+    // A prior attempt's fault survives clearFault's best-effort removal (its own
+    // errors are swallowed and unchecked by callers) — the exact failure mode
+    // the diagnostic must not be fooled by.
+    recordFault('node-b', {
+        link: 'crtr→pi',
+        op: 'model resolution at launch',
+        kind: 'model-not-found',
+        retry: { disposition: 'fatal' },
+        message: 'stale cause from an earlier boot',
+    });
+    const attempt = beginBootFaultAttempt('node-b');
+    // This attempt's OWN broker also fatal-crashes with the SAME link+kind —
+    // recordFault's since-preserving merge for a repeated link+kind marker means
+    // the on-disk `since` can still read as the STALE incident's start, so a
+    // naive timestamp check would misattribute this. The snapshot taken above
+    // (before this write) is what actually gates it.
+    recordFault('node-b', {
+        link: 'crtr→pi',
+        op: 'model resolution at launch',
+        kind: 'model-not-found',
+        retry: { disposition: 'fatal' },
+        message: 'a fresh cause from this attempt',
+    });
+    assert.equal(attempt.explanation(), null, 'a fault present before this attempt began must fail closed, not surface any cause');
+});
+test('no fault recorded at all yields no explanation', { timeout: 1_000 }, () => {
+    const attempt = beginBootFaultAttempt('node-c');
+    assert.equal(attempt.explanation(), null);
+});
+test('an unrelated fault (wrong link, or non-fatal) is never surfaced as a boot cause', { timeout: 1_000 }, () => {
+    const attempt = beginBootFaultAttempt('node-d');
+    recordFault('node-d', {
+        link: 'viewer↔broker',
+        op: 'connect',
+        kind: 'connection',
+        retry: { disposition: 'manual' },
+        message: 'a viewer failed to connect, unrelated to launch',
+    });
+    assert.equal(attempt.explanation(), null);
+});
+test('a fault with an empty operation or message falls back to null rather than an empty diagnosis', { timeout: 1_000 }, () => {
+    const attempt = beginBootFaultAttempt('node-e');
+    recordFault('node-e', {
+        link: 'crtr→pi',
+        op: '',
+        kind: 'model-not-found',
+        retry: { disposition: 'fatal' },
+        message: '',
+    });
+    assert.equal(attempt.explanation(), null);
+});

package/dist/core/__tests__/boot.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,275 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/boot.test.ts
+//
+// BUG LOCKED (a sandbox/VM destroy+recreate, or a host
+// reboot, leaves stale `pi_pid` values in the durable canvas.db; a pid-reuse
+// collision on the fresh boot can fool `isPidAlive` into reading a dead
+// broker as alive, wedging the node forever). reconcileBootLiveness is the
+// fix: detect the boot change and clear every stale pid BEFORE any liveness
+// check trusts it.
+//
+// Exercises the pure decision core (bootChanged) and the impure, single-writer
+// sweep (reconcileBootLiveness) against a real isolated CRTR_HOME + canvas.db —
+// no real reboot, no real uptime: both take an injected BootIdentity (kernel
+// boot_id + wall-clock epoch) so a boot change is simulated by handing a
+// different identity between calls.
+import { test, before, after, beforeEach } from 'node:test';
+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, 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,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'developer',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        ...over,
+    };
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-boot-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+// ---------------------------------------------------------------------------
+// bootChanged — pure core
+// ---------------------------------------------------------------------------
+test('bootChanged: no persisted history is never a change (never clears a genuinely live pid)', () => {
+    assert.equal(bootChanged(ident('boot-A', 1_000_000), null), false);
+});
+test('bootChanged: same kernel boot_id is the SAME boot (daemon restart, no reboot)', () => {
+    assert.equal(bootChanged(ident('boot-A', 1_000_000 + 5_000), ident('boot-A', 1_000_000)), false, 'identical boot_id — same boot regardless of epoch');
+});
+test('bootChanged: a DIFFERENT boot_id under 60s wall-delta is still detected', () => {
+    // A genuinely fast reboot/recreate: boot B starts only 42s after boot A
+    // (a measured real-world recreate window), well inside the 60s wall tolerance.
+    // The exact kernel boot_id catches it with NO reliance on the wall-clock
+    // window — boot_id is the primary signal, not wall time.
+    assert.equal(bootChanged(ident('boot-B', 1_000_000 + 42_000), ident('boot-A', 1_000_000)), true, 'distinct boot_id 42s apart — a real quick recreate, detected');
+});
+test('bootChanged: same boot_id with a huge epoch jump is NOT a boot change (NTP step within a boot)', () => {
+    assert.equal(bootChanged(ident('boot-A', 1_000_000 + 10 * 60_000), ident('boot-A', 1_000_000)), false, 'boot_id trumps the wall clock — an NTP correction mid-boot never false-positives');
+});
+test('bootChanged: wall-clock fallback (no boot_id) — epochs within tolerance are the SAME boot', () => {
+    assert.equal(bootChanged(ident(null, 1_000_000 + 5_000), ident(null, 1_000_000)), false, '5s drift — same boot');
+});
+test('bootChanged: wall-clock fallback (no boot_id) — epochs far apart are a DIFFERENT boot', () => {
+    assert.equal(bootChanged(ident(null, 1_000_000 + 10 * 60_000), ident(null, 1_000_000)), true, '10min apart — different boot');
+});
+// ---------------------------------------------------------------------------
+// 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: [], 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', () => {
+    const m = node('n1');
+    createNode(m);
+    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: [], 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', () => {
+    const active = node('active-1', { status: 'active' });
+    const idle = node('idle-1', { status: 'idle' });
+    const dead = node('dead-1', { status: 'dead' }); // the guard reads pi_pid unconditionally
+    const noPid = node('no-pid-1', { status: 'active' });
+    for (const m of [active, idle, dead, noPid])
+        createNode(m);
+    recordPid('active-1', 111);
+    recordPid('idle-1', 222);
+    recordPid('dead-1', 333);
+    // no-pid-1 deliberately left without a recorded pid.
+    reconcileBootLiveness(ident('boot-A', 1_000_000)); // seed boot A
+    const result = reconcileBootLiveness(ident('boot-B', 1_000_000 + 60 * 60_000)); // boot B
+    assert.equal(result.changed, true);
+    assert.deepEqual(result.cleared.sort(), ['active-1', 'dead-1', 'idle-1']);
+    assert.equal(getRow('active-1')?.pi_pid, null);
+    assert.equal(getRow('idle-1')?.pi_pid, null);
+    assert.equal(getRow('dead-1')?.pi_pid, null, 'cleared even though status is dead — the double-launch guard reads pi_pid unconditionally');
+    assert.equal(getRow('no-pid-1')?.pi_pid, null, 'already null — no-op, not an error');
+});
+test('reconcileBootLiveness: a fast recreate (distinct boot_id, 42s wall) still sweeps (Major-2 regression)', () => {
+    const m = node('n1');
+    createNode(m);
+    recordPid('n1', 111);
+    reconcileBootLiveness(ident('boot-A', 1_000_000)); // seed boot A
+    const result = reconcileBootLiveness(ident('boot-B', 1_000_000 + 42_000)); // 42s later — inside the wall window, but new boot_id
+    assert.equal(result.changed, true, 'distinct boot_id detected even 42s apart');
+    assert.deepEqual(result.cleared, ['n1']);
+    assert.equal(getRow('n1')?.pi_pid, null);
+});
+test('reconcileBootLiveness: after reconciling, the SAME boot no longer re-triggers (idempotent)', () => {
+    const m = node('n1');
+    createNode(m);
+    recordPid('n1', 111);
+    reconcileBootLiveness(ident('boot-A', 1_000_000)); // seed boot A
+    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: [], 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__/branded-host-concurrency.test.d.ts

@@ -0,0 +1 @@
+export {};