@crouton-kit/crouter 0.3.82 → 0.3.84

package/dist/core/canvas/attention.js

@@ -1,13 +1,16 @@
-// attention.ts — pending human-ask counters across the canvas.
+// attention.ts — pending human-ticket counters across the canvas.
 //
-// Human asks are stored per-cwd, not per-node (interactionsRoot is keyed by
-// the cwd the agent ran in, same pattern as humanloop's human list command).
-// A cwd can be shared by multiple nodes, so we de-dup on cwd before summing to
-// avoid counting the same pending ask N times.
+// A "ticket" is any pending humanloop interaction: a deck (ask), a notify deck,
+// or an anchored review. `scanInbox` returns the sealed deck/review summary
+// union (notify is a durable deck), so every count here is "all pending human
+// tickets", not just asks. Tickets are stored per-cwd, not per-node
+// (interactionsRoot is keyed by the cwd the agent ran in), so a cwd shared by
+// multiple nodes is de-duped before summing to avoid counting the same pending
+// ticket N times.
 //
 // All public functions are best-effort: scanInbox failures return 0 / empty.
-// Callers are display code (dashboard, attention queue) that must not blow up
-// on a cold canvas or missing humanloop state.
+// Callers are display code (dashboard, attention queue, attach chrome) that must
+// not blow up on a cold canvas or missing humanloop state.
 import { scanInbox } from '@crouton-kit/humanloop';
 import { interactionsRoot } from '../artifact.js';
 import { getNode, listNodes, view } from './canvas.js';
@@ -15,21 +18,21 @@ import { getNode, listNodes, view } from './canvas.js';
 // Helpers
 // ---------------------------------------------------------------------------
 /**
- * Count pending asks for a single cwd root. Never throws.
+ * Count pending tickets for a single cwd root. Never throws.
  *
- * When `nodeId` is given, count only asks raised by THAT node — humanloop
- * stamps `deck.source.nodeId` with the originating CRTR_NODE_ID, so two nodes
- * sharing a cwd no longer pollute each other's count. Asks with no stamp
- * (legacy, or raised outside a canvas node) are not attributable to any node
- * and are excluded from the per-node count. Read via a cast so this doesn't
- * hard-depend on a humanloop type bump.
+ * When `nodeId` is given, count only tickets raised by THAT node — humanloop
+ * stamps `source.nodeId` (deck AND review submissions alike) with the
+ * originating CRTR_NODE_ID, so two nodes sharing a cwd no longer pollute each
+ * other's count. Tickets with no stamp (raised from a bare shell, or outside a
+ * canvas node) are not attributable to any node and are excluded from the
+ * per-node count.
  */
 function countForCwd(cwd, nodeId) {
     try {
         const items = scanInbox([interactionsRoot(cwd)]);
         if (nodeId === undefined)
             return items.length;
-        return items.filter((i) => i.source?.nodeId === nodeId).length;
+        return items.filter((i) => i.source.nodeId === nodeId).length;
     }
     catch {
         // humanloop not installed, or interactions dir doesn't exist — both fine.
@@ -40,23 +43,23 @@ function countForCwd(cwd, nodeId) {
 // Public API
 // ---------------------------------------------------------------------------
 /**
- * Count pending asks for the cwd of a single node.
+ * Count pending tickets for the cwd of a single node.
  * Returns 0 when the node is unknown or humanloop is unavailable.
  */
-export function countAsks(nodeId) {
+export function countTickets(nodeId) {
     const node = getNode(nodeId);
     if (node === null)
         return 0;
     return countForCwd(node.cwd, nodeId);
 }
 /**
- * Pending asks for all nodes reachable in the subscription sub-DAG from
+ * Pending tickets for all nodes reachable in the subscription sub-DAG from
  * `rootId` (including root itself). De-duped by cwd: when multiple nodes
  * share a cwd the first one encountered claims the entry.
  *
  * Returns only entries with count > 0.
  */
-export function pendingAsksForView(rootId) {
+export function pendingTicketsForView(rootId) {
     // view() returns children only (excludes root), so prepend root.
     const ids = [rootId, ...view(rootId)];
     const seen = new Map(); // cwd → entry
@@ -78,15 +81,17 @@ export function pendingAsksForView(rootId) {
     return Array.from(seen.values()).filter((e) => e.count > 0);
 }
 /**
- * Per-node pending ask counts for an explicit set of node ids — the batched
- * counterpart to `countAsks`, used by the nav chrome to label every visible
+ * Per-node pending ticket counts for an explicit set of node ids — the batched
+ * counterpart to `countTickets`, used by the nav chrome to label every visible
  * node in ONE pass. Groups ids by their cwd so each distinct interactions dir
- * is scanned exactly once, then buckets the decks by the `source.nodeId` stamp
- * (same attribution as `countForCwd(cwd, nodeId)`). Asks with no node stamp are
- * not attributable to any node and are excluded. Every requested id appears in
- * the result (0 when it has none). Never throws.
+ * is scanned exactly once, de-duplicates by canonical ticket dir (scanInbox
+ * already returns one summary per dir), then buckets the tickets by the
+ * `source.nodeId` stamp (same attribution as `countForCwd(cwd, nodeId)`).
+ * Tickets with no node stamp (bare-shell / unattributed) belong to no node and
+ * are excluded from the map. Every requested id appears in the result (0 when
+ * it has none). Never throws.
  */
-export function asksForNodes(ids) {
+export function ticketCountsForNodes(ids) {
     const counts = {};
     for (const id of ids)
         counts[id] = 0;
@@ -110,7 +115,7 @@ export function asksForNodes(ids) {
         }
         const want = new Set(cwdIds);
         for (const i of items) {
-            const nid = i.source?.nodeId;
+            const nid = i.source.nodeId;
             if (nid !== undefined && want.has(nid))
                 counts[nid] = (counts[nid] ?? 0) + 1;
         }
@@ -118,10 +123,10 @@ export function asksForNodes(ids) {
     return counts;
 }
 /**
- * Pending asks across the entire canvas — every distinct cwd among all known
+ * Pending tickets across the entire canvas — every distinct cwd among all known
  * nodes. Returns only entries with count > 0.
  */
-export function asksAcrossCanvas() {
+export function ticketsAcrossCanvas() {
     const rows = listNodes();
     const seen = new Map(); // cwd → entry
     for (const row of rows) {

package/dist/core/canvas/boot.d.ts

@@ -7,6 +7,7 @@ export interface BootIdentity {
      *  discriminator only, used when `bootId` is null on either side. */
     bootEpochMs: number;
 }
+export declare function readKernelBootId(): string | null;
 /** Identity of the CURRENT OS boot. `now` is injectable for tests. */
 export declare function currentBootIdentity(now?: number): BootIdentity;
 /** Pure decision core: does `current` belong to a DIFFERENT boot than the
@@ -21,11 +22,29 @@ export declare function currentBootIdentity(now?: number): BootIdentity;
  *  on either side (non-Linux dev) does it fall back to the epoch-drift window.
  *  Unit-testable without real uptime/fs. */
 export declare function bootChanged(current: BootIdentity, known: BootIdentity | null): boolean;
+/** POSITIVE proof that `current` is the SAME boot the persisted `known` marker
+ *  recorded — as distinct from `!bootChanged(...)`, which is merely "no change
+ *  detected" and is also true when there is no history, a malformed marker, or
+ *  only the coarse wall-clock fallback to go on. Proof requires an exact kernel
+ *  `boot_id` present and equal on BOTH sides. This gates the one-time legacy
+ *  identity migration: that sweep rewrites a legacy row's baseline as
+ *  `<currentBootId>#<ticks>`, permanently blessing the recorded pid as a
+ *  current-boot process, so it must run ONLY when we can prove the recorded pid
+ *  really is from this boot — never on a mere ticks match under an unproven
+ *  boot (the epoch fallback or an absent/malformed marker could otherwise bless
+ *  an unrelated stranger process that happens to collide on pid+ticks). */
+export declare function bootProvenSame(current: BootIdentity, known: BootIdentity | null): boolean;
 export interface BootReconcileResult {
     /** True when a boot change was detected (and, therefore, pids were cleared). */
     changed: boolean;
     /** node_ids whose stale `pi_pid` was cleared. */
     cleared: string[];
+    /** True ONLY when this run positively proved same-boot provenance against the
+     *  persisted marker (exact `boot_id` present and equal on both sides). Gates
+     *  the legacy identity migration — see `bootProvenSame`. False on a boot
+     *  change, a first-ever/absent/malformed marker, or a wall-clock-fallback
+     *  match. */
+    sameBootProven: boolean;
 }
 /** Idempotent and safe to call from every revive entry point (daemon startup,
  *  reviveNode): compares the current boot's identity against the last one
@@ -46,3 +65,29 @@ export interface BootReconcileResult {
  *  `current` defaults to the real identity; tests inject a synthetic one against
  *  an isolated CRTR_HOME to simulate a boot change without a real reboot. */
 export declare function reconcileBootLiveness(current?: BootIdentity): BootReconcileResult;
+/** The one-time legacy pid-identity migration, injected into the startup
+ *  composition. In production this is `migrateLegacyPidIdentities` from
+ *  canvas.ts; it is a parameter (not a direct import) because canvas.ts already
+ *  depends on pid.ts which depends on this module — injecting it keeps the
+ *  dependency one-directional and lets tests exercise this exact composition. */
+export type MigrateLegacyPidIdentities = (captureIdentity?: (pid: number) => string | undefined) => {
+    migrated: string[];
+};
+export interface BootStartupResult {
+    /** The pid-liveness reconciliation result (boot-change sweep + provenance). */
+    reconcile: BootReconcileResult;
+    /** node_ids whose legacy identity baseline was migrated — empty when the
+     *  provenance gate skipped the sweep. */
+    migrated: string[];
+}
+/** The daemon's one-time startup boot composition, the single source of truth
+ *  for its ORDERING and GATE: reconcile pid liveness FIRST (clearing any pids
+ *  recorded before this boot), then run the legacy identity migration ONLY when
+ *  reconciliation positively PROVED same-boot provenance (`sameBootProven`).
+ *  Both `runDaemon` and the migration-gate regression tests call this, so a
+ *  revert that inverts the gate, drops it, or reorders migration ahead of
+ *  reconciliation is caught here rather than only in a test-side duplicate.
+ *
+ *  `migrate` is injected (see `MigrateLegacyPidIdentities`); `current` and
+ *  `captureIdentity` pass through to the two steps for test injection. */
+export declare function reconcileAndMigrateBoot(migrate: MigrateLegacyPidIdentities, current?: BootIdentity, captureIdentity?: (pid: number) => string | undefined): BootStartupResult;

package/dist/core/canvas/boot.js

@@ -47,7 +47,7 @@ import { openDb } from './db.js';
  *  dangerous direction. The production target (Linux microVM guests) never
  *  reaches this branch; there `boot_id` is exact. */
 const BOOT_EPOCH_TOLERANCE_MS = 60_000;
-function readKernelBootId() {
+export function readKernelBootId() {
     try {
         const id = readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim();
         return id.length > 0 ? id : null;
@@ -79,6 +79,23 @@ export function bootChanged(current, known) {
     }
     return Math.abs(current.bootEpochMs - known.bootEpochMs) > BOOT_EPOCH_TOLERANCE_MS;
 }
+/** POSITIVE proof that `current` is the SAME boot the persisted `known` marker
+ *  recorded — as distinct from `!bootChanged(...)`, which is merely "no change
+ *  detected" and is also true when there is no history, a malformed marker, or
+ *  only the coarse wall-clock fallback to go on. Proof requires an exact kernel
+ *  `boot_id` present and equal on BOTH sides. This gates the one-time legacy
+ *  identity migration: that sweep rewrites a legacy row's baseline as
+ *  `<currentBootId>#<ticks>`, permanently blessing the recorded pid as a
+ *  current-boot process, so it must run ONLY when we can prove the recorded pid
+ *  really is from this boot — never on a mere ticks match under an unproven
+ *  boot (the epoch fallback or an absent/malformed marker could otherwise bless
+ *  an unrelated stranger process that happens to collide on pid+ticks). */
+export function bootProvenSame(current, known) {
+    return (known !== null &&
+        current.bootId !== null &&
+        known.bootId !== null &&
+        current.bootId === known.bootId);
+}
 const BOOT_MARKER_KEY = 'boot_identity';
 function readBootMarker(db) {
     const row = db
@@ -129,8 +146,9 @@ export function reconcileBootLiveness(current = currentBootIdentity()) {
         if (!bootChanged(current, known)) {
             if (known === null)
                 writeBootMarker(db, current); // seed first-ever marker
+            const sameBootProven = bootProvenSame(current, known);
             db.exec('COMMIT');
-            return { changed: false, cleared: [] };
+            return { changed: false, cleared: [], sameBootProven };
         }
         const rows = db
             .prepare('SELECT node_id FROM nodes WHERE pi_pid IS NOT NULL')
@@ -148,7 +166,7 @@ export function reconcileBootLiveness(current = currentBootIdentity()) {
         }
         writeBootMarker(db, current);
         db.exec('COMMIT');
-        return { changed: true, cleared };
+        return { changed: true, cleared, sameBootProven: false };
     }
     catch (err) {
         try {
@@ -160,3 +178,18 @@ export function reconcileBootLiveness(current = currentBootIdentity()) {
         throw err;
     }
 }
+/** The daemon's one-time startup boot composition, the single source of truth
+ *  for its ORDERING and GATE: reconcile pid liveness FIRST (clearing any pids
+ *  recorded before this boot), then run the legacy identity migration ONLY when
+ *  reconciliation positively PROVED same-boot provenance (`sameBootProven`).
+ *  Both `runDaemon` and the migration-gate regression tests call this, so a
+ *  revert that inverts the gate, drops it, or reorders migration ahead of
+ *  reconciliation is caught here rather than only in a test-side duplicate.
+ *
+ *  `migrate` is injected (see `MigrateLegacyPidIdentities`); `current` and
+ *  `captureIdentity` pass through to the two steps for test injection. */
+export function reconcileAndMigrateBoot(migrate, current, captureIdentity) {
+    const reconcile = reconcileBootLiveness(current);
+    const migrated = reconcile.sameBootProven ? migrate(captureIdentity).migrated : [];
+    return { reconcile, migrated };
+}

package/dist/core/canvas/browse/app.js

@@ -84,8 +84,8 @@ export async function runBrowse(opts = {}) {
     let childIds;
     let tree;
     let totalNodes;
-    // Remote-only: pending-ask counts per node, merged from one
-    // `askCountsForView` call per forest root (RemoteCanvasSource.askCountsForView
+    // Remote-only: pending human-ticket counts per node, merged from one
+    // `ticketCountsForView` call per forest root (RemoteCanvasSource.ticketCountsForView
     // already shells a single `canvas attention map --view <root>` per root, same
     // cost class as the per-node `subscriptionsOf` fan-out this snapshot already
     // does below) — fetched once per snapshot rebuild, not per flush/keystroke, so
@@ -105,7 +105,7 @@ export async function runBrowse(opts = {}) {
         tree = buildTree(rows, rootIds, (id) => childIds.get(id) ?? []);
         totalNodes = tree.nodes.size;
         if (isRemote) {
-            const maps = await Promise.all(rootIds.map((root) => source.askCountsForView(root).catch(() => ({}))));
+            const maps = await Promise.all(rootIds.map((root) => source.ticketCountsForView(root).catch(() => ({}))));
             remoteAskCounts = Object.assign({}, ...maps);
         }
     };

package/dist/core/canvas/canvas.d.ts

@@ -50,6 +50,46 @@ export declare function recordPid(nodeId: string, pid: number): void;
  *  reuses the pid namespace could compare its own fresh pid against a STALE
  *  identity left over from the pid this row held before. */
 export declare function clearPid(nodeId: string): void;
+/** ONE-TIME completion of the boot-scoped-identity format migration, run once
+ *  at daemon startup (the natural boot-reconciliation chokepoint, right after
+ *  `reconcileBootLiveness`). It closes the gap the `identitiesMatch` legacy
+ *  lane only TOLERATES: a broker that survives an in-place crouter upgrade
+ *  keeps its old `lstart#ticks` row indefinitely (`recordPid` only fires on
+ *  launch/revive/session_start), so the cross-boot ticks-collision exposure the
+ *  boot-scoped base was added to close never provably shuts for those rows.
+ *
+ *  For every row whose RECORDED identity is legacy-format while this platform
+ *  now composes new-format (a readable kernel boot_id):
+ *   - if the recorded pid's CURRENT live identity matches the recorded one via
+ *     the migration lane (same live process, `identitiesMatch` true) AND that
+ *     current identity is itself boot-scoped — re-record it with the new
+ *     composer, completing the migration in place;
+ *   - otherwise (pid gone, probe failed, reused — no match, or no readable
+ *     boot_id for it) — leave the row untouched for the normal liveness
+ *     handling that already runs each tick.
+ *
+ *  After this runs once, the legacy compare lane only ever engages for
+ *  genuinely no-boot_id platforms. NOT a per-caller reconciliation layer — a
+ *  single startup sweep. `captureIdentity` is injectable for unit tests.
+ *
+ *  GATED on proven same-boot provenance by its caller (daemon startup runs it
+ *  only when `reconcileBootLiveness` returned `sameBootProven` — see
+ *  `bootProvenSame`). This is what makes a bare ticks match safe to bless as a
+ *  current-boot identity: without that proof an equal-ticks collision with an
+ *  unrelated process from a DIFFERENT boot could be rewritten as
+ *  `<currentBootId>#<ticks>`, permanently baptizing a stranger.
+ *
+ *  Not transactional by design: it never HOLDS the write lock across the (slow,
+ *  per-row) `ps` probe. Each re-record is a compare-and-swap single-row UPDATE
+ *  constrained by ALL three snapshotted values (`node_id`, `pi_pid`,
+ *  `pi_pid_identity`), counted only when a row actually changed. So if the old
+ *  broker exits and a concurrent revive atomically records a fresh
+ *  `(pi_pid, pi_pid_identity)` between this sweep's probe and its update, the
+ *  CAS matches zero rows and the migration is skipped rather than clobbering
+ *  the newer identity with the stale one. */
+export declare function migrateLegacyPidIdentities(captureIdentity?: (pid: number) => string | undefined): {
+    migrated: string[];
+};
 /** All rows, optionally filtered by status. */
 export declare function listNodes(filter?: {
     status?: NodeStatus | NodeStatus[];

package/dist/core/canvas/canvas.js

@@ -7,7 +7,7 @@
 import { existsSync, readFileSync, renameSync, readdirSync, rmSync, openSync, writeSync, fsyncSync, closeSync, statSync, } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { openDb } from './db.js';
-import { isPidAlive, capturePidIdentities } from './pid.js';
+import { isPidAlive, capturePidIdentities, identitiesMatch, isLegacyTicksIdentity, isBootScopedIdentity, } from './pid.js';
 import { cancelTriggersFor } from './triggers.js';
 import { ensureHome, ensureNodeDirs, nodeMetaPath, nodeDir, nodesRoot, jobDir, } from './paths.js';
 // ---------------------------------------------------------------------------
@@ -272,6 +272,70 @@ export function recordPid(nodeId, pid) {
 export function clearPid(nodeId) {
     openDb().prepare('UPDATE nodes SET pi_pid = NULL, pi_pid_identity = NULL WHERE node_id = ?').run(nodeId);
 }
+/** ONE-TIME completion of the boot-scoped-identity format migration, run once
+ *  at daemon startup (the natural boot-reconciliation chokepoint, right after
+ *  `reconcileBootLiveness`). It closes the gap the `identitiesMatch` legacy
+ *  lane only TOLERATES: a broker that survives an in-place crouter upgrade
+ *  keeps its old `lstart#ticks` row indefinitely (`recordPid` only fires on
+ *  launch/revive/session_start), so the cross-boot ticks-collision exposure the
+ *  boot-scoped base was added to close never provably shuts for those rows.
+ *
+ *  For every row whose RECORDED identity is legacy-format while this platform
+ *  now composes new-format (a readable kernel boot_id):
+ *   - if the recorded pid's CURRENT live identity matches the recorded one via
+ *     the migration lane (same live process, `identitiesMatch` true) AND that
+ *     current identity is itself boot-scoped — re-record it with the new
+ *     composer, completing the migration in place;
+ *   - otherwise (pid gone, probe failed, reused — no match, or no readable
+ *     boot_id for it) — leave the row untouched for the normal liveness
+ *     handling that already runs each tick.
+ *
+ *  After this runs once, the legacy compare lane only ever engages for
+ *  genuinely no-boot_id platforms. NOT a per-caller reconciliation layer — a
+ *  single startup sweep. `captureIdentity` is injectable for unit tests.
+ *
+ *  GATED on proven same-boot provenance by its caller (daemon startup runs it
+ *  only when `reconcileBootLiveness` returned `sameBootProven` — see
+ *  `bootProvenSame`). This is what makes a bare ticks match safe to bless as a
+ *  current-boot identity: without that proof an equal-ticks collision with an
+ *  unrelated process from a DIFFERENT boot could be rewritten as
+ *  `<currentBootId>#<ticks>`, permanently baptizing a stranger.
+ *
+ *  Not transactional by design: it never HOLDS the write lock across the (slow,
+ *  per-row) `ps` probe. Each re-record is a compare-and-swap single-row UPDATE
+ *  constrained by ALL three snapshotted values (`node_id`, `pi_pid`,
+ *  `pi_pid_identity`), counted only when a row actually changed. So if the old
+ *  broker exits and a concurrent revive atomically records a fresh
+ *  `(pi_pid, pi_pid_identity)` between this sweep's probe and its update, the
+ *  CAS matches zero rows and the migration is skipped rather than clobbering
+ *  the newer identity with the stale one. */
+export function migrateLegacyPidIdentities(captureIdentity = (pid) => capturePidIdentities([pid])?.get(pid)) {
+    const db = openDb();
+    const rows = db
+        .prepare('SELECT node_id, pi_pid, pi_pid_identity FROM nodes WHERE pi_pid IS NOT NULL AND pi_pid_identity IS NOT NULL')
+        .all();
+    // Compare-and-swap: rewrite only if the row STILL carries the exact pid +
+    // legacy identity we probed. A concurrent revive between probe and update
+    // records a new (pi_pid, pi_pid_identity) pair, so this WHERE fails to match
+    // and we skip rather than clobber the fresh baseline.
+    const upd = db.prepare('UPDATE nodes SET pi_pid_identity = ? WHERE node_id = ? AND pi_pid = ? AND pi_pid_identity = ?');
+    const migrated = [];
+    for (const row of rows) {
+        if (!isLegacyTicksIdentity(row.pi_pid_identity))
+            continue;
+        const current = captureIdentity(row.pi_pid);
+        if (current === undefined)
+            continue; // pid gone / probe failed → normal liveness handling
+        if (!isBootScopedIdentity(current))
+            continue; // no readable boot_id for it → nothing to upgrade
+        if (!identitiesMatch(current, row.pi_pid_identity))
+            continue; // reused → leave to liveness
+        const res = upd.run(current, row.node_id, row.pi_pid, row.pi_pid_identity);
+        if (res.changes > 0)
+            migrated.push(row.node_id); // skipped if a concurrent revive re-recorded
+    }
+    return { migrated };
+}
 /** All rows, optionally filtered by status. */
 export function listNodes(filter) {
     const db = openDb();

package/dist/core/canvas/pid.d.ts

@@ -20,24 +20,50 @@ export declare function isPidAlive(pid: number | null | undefined): boolean;
  *  drift from this rule (review Major #1, Round 2 of the pid-reuse-liveness
  *  fix).
  *
- *  The hazard this closes: `composeIdentity` appends the `#<ticks>` Linux
- *  discriminator only when `/proc/<pid>/stat` happens to be readable at
- *  capture time — so the SAME live process can be recorded plain `lstart` on
- *  one capture and `lstart#ticks` on another (a transient `/proc` read
- *  failure, or capturing on a platform/container without procfs). A naive
- *  `===` then reads that as a reuse (different string) and reports `dead` for
- *  a broker that never actually died — the false-DEAD direction, which can
- *  make `reviveNode`'s double-launch guard wrongly relaunch a SECOND broker
- *  onto a still-live session.
+ *  Two hazards this closes, both in the false-DEAD direction (the dangerous
+ *  one — a false DEAD lets `reviveNode`'s double-launch guard relaunch a
+ *  SECOND broker onto a still-live session):
  *
- *  Rule: split both on `#`. Bases (`lstart`) differ → definitely NOT a match
- *  (different process, or the same pid reused in a different second). Bases
- *  match and BOTH carry a `#ticks` suffix → match iff the suffixes are equal
- *  (this still catches genuine same-second reuse, the case `procStartTicks`
- *  exists for). Bases match and EITHER lacks the suffix → coarse-vs-fine,
- *  can't distinguish → MATCH (fail-open to same-process, matching this
- *  module's universal discipline: only a POSITIVE mismatch counts as reuse,
- *  never an absence of evidence). */
+ *  1. `composeIdentity` appends the `#<ticks>` Linux discriminator only when
+ *     `/proc/<pid>/stat` happens to be readable at capture time — so the SAME
+ *     live process can be recorded plain `lstart` on one capture and
+ *     `lstart#ticks` on another (a transient `/proc` read failure, or
+ *     capturing on a platform/container without procfs). A naive `===` reads
+ *     that as a reuse (different string) and reports `dead` for a broker that
+ *     never died.
+ *  2. `lstart` is NOT stable for a live process on every host. It is derived
+ *     from `/proc/stat` btime (wall-clock boot epoch) + starttime jiffies, so
+ *     a clock correction / suspend-resume shifts btime and re-anchors the
+ *     SAME live process's `lstart` by seconds between two captures. Observed
+ *     on Blaxel unikraft guests: pid+ticks identical across probes, `lstart`
+ *     drifting +81s — a base-first compare then reads the live home-node
+ *     broker as reused/dead every cycle, driving an uncapped revive loop.
+ *
+ *  A third hazard the base itself once carried: `ticks` (jiffies-since-boot)
+ *  RESET on every boot and can repeat across boots, so ticks-alone is only
+ *  safe WITHIN one boot. `composeIdentity` therefore boot-SCOPES the base on
+ *  Linux-with-procfs — the base IS the kernel `boot_id` UUID — so a
+ *  new-format identity is `<bootId>#<ticks>` and equality means same boot AND
+ *  same process. This closes the cross-boot false match at the root, without
+ *  plumbing boot reconciliation ahead of every caller.
+ *
+ *  Rule: split both on `#`.
+ *   - BOTH sides carry `#ticks` AND both bases are `boot_id` UUIDs
+ *     (new-format vs new-format): match iff base AND ticks are equal. A
+ *     different boot_id with equal ticks is NOT a match (the cross-boot
+ *     collision).
+ *   - BOTH sides carry `#ticks` but a base is NOT a boot_id UUID on EITHER
+ *     side — a LEGACY `lstart#ticks` row recorded before this repo boot-scoped
+ *     the base, or a Linux host that has procfs ticks but no readable boot_id:
+ *     ticks DECIDE it alone (the prior landed semantics). This is a NARROW
+ *     format-migration path so an in-place upgrade never false-kills a live
+ *     broker whose row still holds `lstart#ticks`; it is NOT a general
+ *     fallback — new-format vs new-format always demands base+ticks above.
+ *   - EITHER side lacks a valid `#ticks` suffix (macOS / no procfs / transient
+ *     `/proc` miss / malformed suffix): fall back to the coarse base —
+ *     matching iff the bases agree (fail-open to same-process, matching this
+ *     module's universal discipline: only a POSITIVE mismatch counts as reuse,
+ *     never an absence of evidence). */
 export declare function identitiesMatch(a: string, b: string): boolean;
 /** Three-valued liveness verdict for a RECORDED node pid, identity-guarded
  *  against PID REUSE using the launch-time baseline (`pi_pid_identity`,
@@ -97,6 +123,49 @@ export declare function isRecordedPidAlive(pid: number | null | undefined, expec
  *  Guards `pid` before signaling (review nit, crouter#98): never hit pid 0
  *  (which means "my own group") or a negative/non-integer value. */
 export declare function killProcessGroup(pid: number, signal?: NodeJS.Signals): void;
+/** The kernel `boot_id` (`/proc/sys/kernel/random/boot_id`) is stable for the
+ *  whole lifetime of this process — it only changes on a kernel boot, which
+ *  necessarily kills this process — so once a real value is read it is cached
+ *  for good, rather than re-read for every row of a whole-process-table `ps`
+ *  scan. Only SUCCESSFUL reads are cached forever: a `null` read is negative
+ *  for `BOOT_ID_NEGATIVE_TTL_MS`, after which the next call retries — so a
+ *  transient `/proc` miss on a boot_id-capable host still recovers (never
+ *  permanently downgraded to legacy `lstart#ticks`), while a genuinely
+ *  no-boot_id host is not hammered with a synchronous throwing read on every
+ *  identity composition. `now` is injectable for tests. */
+export declare function makeBootIdCache(read: () => string | null, now?: () => number, negativeTtlMs?: number): () => string | null;
+/** Is `identity` a LEGACY (pre-boot-scoped) baseline — a `<lstart>#<ticks>` row
+ *  whose base is NOT a boot_id UUID but which DOES carry ticks? These are the
+ *  rows the one-time startup migration re-records once this platform can
+ *  compose boot-scoped identities (see `migrateLegacyPidIdentities`). */
+export declare function isLegacyTicksIdentity(identity: string): boolean;
+/** Is `identity` a NEW-format boot-scoped baseline — `<bootId>#<ticks>` with a
+ *  real boot_id UUID base AND ticks? The startup migration only re-records a
+ *  legacy row when the pid's CURRENT identity comes out in this shape (i.e. the
+ *  platform now composes new-format), never otherwise. */
+export declare function isBootScopedIdentity(identity: string): boolean;
+/** Compose the stable, BOOT-SCOPED process-identity fingerprint used
+ *  everywhere in this module. ALWAYS used to build an identity string, never a
+ *  raw field directly, so every identity captured anywhere (launch-time
+ *  `recordPid`, the teardown snapshot, and the escalation-window re-check) is
+ *  comparable apples-to-apples.
+ *
+ *  Platform capability, not layered fallbacks — the base is the finest STABLE
+ *  per-boot anchor available:
+ *   - Linux-with-procfs (the production guest shape): `<bootId>#<ticks>` — the
+ *     per-boot `boot_id` UUID plus the per-process jiffies-since-boot. Ticks
+ *     reset per boot and can repeat, so scoping the base to the boot is what
+ *     makes an equal-ticks compare safe ACROSS boots (see `identitiesMatch`).
+ *   - Linux-with-procfs but no readable `boot_id` (if that combination
+ *     exists): `<lstart>#<ticks>` — the prior landed behavior.
+ *   - No procfs ticks (macOS / containers without procfs): `<lstart>` alone —
+ *     unchanged coarse behavior. The base is only ever a `boot_id` when a
+ *     `ticks` discriminator is ALSO present; a bare `boot_id` (shared by every
+ *     process on the boot) would be a useless per-process identity. */
+export declare function composeIdentity(pid: number, lstart: string, deps?: {
+    ticks?: string | null;
+    bootId?: string | null;
+}): string;
 /** Every transitive descendant of `rootPid`, discovered by walking `ps`'s
  *  pid/ppid table (BFS) — NOT process-GROUP membership. This is the fix for
  *  crouton-labs/crouter#98: the pi SDK's bash tool spawns its shell child with