@north-light/crouter 0.3.248 → 0.3.250

package/dist/core/canvas/canvas.js

@@ -20,7 +20,7 @@ import { ensureHome, ensureNodeDirs, nodeMetaPath, nodeDir, nodesRoot, jobDir, }
  *  can ever leak onto disk even when a fully-hydrated NodeMeta is handed in. */
 const IDENTITY_KEYS = [
     'node_id', 'name', 'description', 'title', 'icon', 'cycles', 'created', 'cwd', 'host_kind', 'profile_id', 'kind', 'mode',
-    'lifecycle', 'persona_ack', 'parent', 'spawned_by', 'fork_from', 'fork_source_file', 'review_binding', 'passive_default', 'pi_session_id',
+    'lifecycle', 'persona_ack', 'parent', 'spawned_by', 'creator', 'fork_from', 'fork_source_file', 'review_binding', 'passive_default', 'pi_session_id',
     'pi_session_file', 'cycle_pending', 'model_override',
     'launch', 'managed_worktree',
 ];
@@ -208,12 +208,13 @@ export function canonicalSessionFile(sessionFile) {
 /** Resolve the crouter node that owns one exact Pi session file. */
 export function findNodeBySessionFile(sessionFile) {
     const canonical = canonicalSessionFile(sessionFile);
-    const matches = openDb()
-        .prepare('SELECT node_id FROM nodes WHERE pi_session_file = ? ORDER BY created')
-        .all(canonical);
-    if (matches.length > 1)
-        throw new Error(`multiple nodes own pi session file: ${canonical}`);
-    return matches[0] === undefined ? null : getNode(matches[0].node_id);
+    // v36 makes this unique. LIMIT 1 also keeps the lookup total for a canvas
+    // opened during repair of an older duplicate projection: the deterministic
+    // oldest row remains the owner instead of turning a lookup into a crash.
+    const match = openDb()
+        .prepare('SELECT node_id FROM nodes WHERE pi_session_file = ? ORDER BY created, node_id LIMIT 1')
+        .get(canonical);
+    return match === undefined ? null : getNode(match.node_id);
 }
 /** The indexed row (from the db) — cheap for queries that don't need full meta. */
 export function getRow(nodeId) {
@@ -839,6 +840,16 @@ export function rebuildIndex() {
 function hasOpenManagedWorktree(nodeId) {
     return getNode(nodeId)?.managed_worktree?.state === 'open';
 }
+/** Whether a row may be removed by an automatic collection sweep. */
+export function isCollectible(row, opts = {}) {
+    if (!['done', 'dead', 'canceled'].includes(row.status)
+        || row.pi_pid !== null
+        || row.frozen_at !== null
+        || hasOpenManagedWorktree(row.node_id)
+        || row.node_id === envNodeId())
+        return false;
+    return opts.pastTtl === true || !['crashed', 'stranded', null].includes(row.terminal_reason ?? null);
+}
 /** Hard-delete ONE node: drop its row (the edges→nodes FK, ON DELETE CASCADE,
  *  GCs its edges) and remove its on-disk `nodes/<id>/` dir. The single-node
  *  analogue of {@link pruneNodes}, for IMMEDIATE reaping — e.g. an empty node the
@@ -905,14 +916,13 @@ export function pruneNodes(opts) {
     const selfId = envNodeId() ?? '';
     const db = openDb();
     const terminal = db
-        .prepare(`SELECT node_id, status, created FROM nodes
-         WHERE status IN ('dead', 'done', 'canceled') AND created < ?
-         ORDER BY created`)
-        .all(cutoff).map((r) => ({
-        node_id: r['node_id'],
-        status: r['status'],
-        created: r['created'],
-    }));
+        .prepare(`SELECT * FROM nodes
+       WHERE status IN ('dead', 'done', 'canceled') AND created < ?
+       ORDER BY created`)
+        .all(cutoff)
+        .map(rowFrom)
+        .filter((row) => isCollectible(row, { pastTtl: true }))
+        .map((row) => ({ node_id: row.node_id, status: row.status, created: row.created }));
     // Stale non-terminal sweep (opt-in): active | idle past the TTL whose process
     // is provably gone (pi_pid NULL or not alive). Never the caller itself.
     const stale = !includeStale ? [] : db
@@ -930,8 +940,9 @@ export function pruneNodes(opts) {
         node_id: r['node_id'],
         status: r['status'],
         created: r['created'],
-    }));
-    const candidates = [...terminal, ...stale].filter((node) => !hasOpenManagedWorktree(node.node_id));
+    }))
+        .filter((node) => !hasOpenManagedWorktree(node.node_id));
+    const candidates = [...terminal, ...stale];
     if (dryRun || candidates.length === 0)
         return { pruned: candidates, dryRun };
     deletePrunedNodes(candidates);
@@ -1015,50 +1026,33 @@ function recencyMs(nodeId, created) {
     return Number.isNaN(t) ? 0 : t;
 }
 /** Count-based retention sweep: retain the `maxNodes` MOST-RECENTLY-ACTIVE
- *  nodes plus every protected node, so the real retained floor is
- *  `max(maxNodes, protectedCount)`. Bounds the otherwise-unbounded growth the
- *  TTL sweep can't (a canvas that never crosses the TTL still grows without
+ *  nodes plus every row the collection authority retains, so the real retained
+ *  floor is `max(maxNodes, retainedCount)`. Bounds the otherwise-unbounded growth
+ *  the TTL sweep can't (a canvas that never crosses the TTL still grows without
  *  limit).
  *
- *  Protected (never a prune candidate, regardless of recency rank): any
- *  non-terminal node — status active|idle — REGARDLESS of `pi_pid` liveness,
- *  or a node with an open managed worktree. A crashed-but-non-terminal row
- *  (dead pid, status still active/idle) must survive for daemon crash-recovery
- *  to resume, and an open worktree must retain its node ownership until
- *  `node worktree close`; neither is eligible for count-based pruning. The caller
- *  ($CRTR_NODE_ID) is also always protected.
- *
  *  Algorithm: order ALL nodes by recency DESC (telemetry.json mtime, falling back
- *  to `created`); `target = max(maxNodes, protectedCount)`; delete every node
- *  ranked beyond `target` (0-indexed rank >= target) that is NOT protected and
- *  NOT the caller. Retained = all protected + the newest terminal nodes up to
- *  `target`.
+ *  to `created`); `target = max(maxNodes, retainedCount)`; delete every node
+ *  ranked beyond `target` (0-indexed rank >= target) that is collectible.
  *
  *  Mirrors {@link pruneNodes} exactly for the delete (shared `deletePrunedNodes`:
  *  transactioned row sweep + FK edge cascade + best-effort dir removal). `dryRun`
  *  reports the candidate set and deletes NOTHING. */
 export function pruneToLimit(opts) {
     const dryRun = opts.dryRun ?? false;
-    const selfId = envNodeId() ?? '';
     const rows = listNodes();
-    // Rank ALL nodes by recency DESC, tagging protection as we go. Protection is
-    // status-only (active|idle) — NOT gated on pi_pid liveness — so a node whose
-    // broker crashed but whose row is still non-terminal stays protected for
-    // crash-recovery instead of being hard-deleted here.
     const ranked = rows
-        .map((r) => ({
-        node_id: r.node_id,
-        status: r.status,
-        created: r.created,
-        recency: recencyMs(r.node_id, r.created),
-        protected: r.status === 'active' || r.status === 'idle' || hasOpenManagedWorktree(r.node_id),
+        .map((row) => ({
+        row,
+        recency: recencyMs(row.node_id, row.created),
+        retained: !isCollectible(row),
     }))
         .sort((a, b) => b.recency - a.recency);
-    const protectedCount = ranked.filter((r) => r.protected).length;
-    const target = Math.max(opts.maxNodes, protectedCount);
+    const retainedCount = ranked.filter((r) => r.retained).length;
+    const target = Math.max(opts.maxNodes, retainedCount);
     const candidates = ranked
-        .filter((r, rank) => rank >= target && !r.protected && r.node_id !== selfId)
-        .map((r) => ({ node_id: r.node_id, status: r.status, created: r.created }));
+        .filter((r, rank) => rank >= target && !r.retained)
+        .map(({ row }) => ({ node_id: row.node_id, status: row.status, created: row.created }));
     if (dryRun || candidates.length === 0)
         return { pruned: candidates, dryRun };
     deletePrunedNodes(candidates);

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

@@ -185,14 +185,11 @@ export declare function setCronLastOutputHash(cron_id: string, hash: string): vo
  *  terminal node that stopped without finishing. */
 export declare function hasPendingCancelOnWakeCron(anchor_node: string): boolean;
 /** DELETE every cancel-on-wake cron anchored to this node — the deadline rule.
- *  Two seams call it: reviveNode on a WAKE — every revive except a recovery
- *  relaunch, which only replaces a dead broker instance and leaves the wait
- *  open (the wake won the race), and the `finish`/`cancel` lifecycle transitions (the wait ended
- *  with the node, so its deadline must not fire against a finalized or closed
- *  row). Standing declarative crons are untouched — only cancel-on-wake rows.
- *  Kills any in-flight
- *  run process group first (the cancelCron discipline), under one canvas write
- *  boundary. Returns the removed cron ids. */
+ *  A real wake consumes the wait at its delivery boundary or, as a dormant
+ *  fallback, in reviveNode; recovery replacement is not a wake. Terminal
+ *  lifecycle transitions also clear the wait. Standing declarative crons are
+ *  untouched. Kills an in-flight run process group first (the cancelCron
+ *  discipline), under one canvas write boundary. Returns removed cron ids. */
 export declare function cancelCronsOnWake(anchor_node: string): string[];
 /** UPDATE the next fire time — recurrence advancement. The daemon settles a
  *  recurring row to its next slot BEFORE enacting the run (crash-safe). */

package/dist/core/canvas/crons.js

@@ -269,14 +269,11 @@ export function hasPendingCancelOnWakeCron(anchor_node) {
         .get(anchor_node) !== undefined);
 }
 /** DELETE every cancel-on-wake cron anchored to this node — the deadline rule.
- *  Two seams call it: reviveNode on a WAKE — every revive except a recovery
- *  relaunch, which only replaces a dead broker instance and leaves the wait
- *  open (the wake won the race), and the `finish`/`cancel` lifecycle transitions (the wait ended
- *  with the node, so its deadline must not fire against a finalized or closed
- *  row). Standing declarative crons are untouched — only cancel-on-wake rows.
- *  Kills any in-flight
- *  run process group first (the cancelCron discipline), under one canvas write
- *  boundary. Returns the removed cron ids. */
+ *  A real wake consumes the wait at its delivery boundary or, as a dormant
+ *  fallback, in reviveNode; recovery replacement is not a wake. Terminal
+ *  lifecycle transitions also clear the wait. Standing declarative crons are
+ *  untouched. Kills an in-flight run process group first (the cancelCron
+ *  discipline), under one canvas write boundary. Returns removed cron ids. */
 export function cancelCronsOnWake(anchor_node) {
     return withCanvasWrite((db) => {
         const rows = db

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

@@ -53,6 +53,11 @@ export interface CorpusFilter {
  *  CRTR_NODE_ID via the canvas data layer), falling back to the process cwd
  *  when not run as a node. */
 export declare function callerCwd(): string;
+/** The history ref of a node's newest report, or null when it left none.
+ *  Report filenames lead with a compact timestamp, so the lexicographic maximum
+ *  is the latest one. Callers use this to hand a reader something they can
+ *  actually open (`crtr canvas history read <ref>`) instead of a bare node id. */
+export declare function newestReportRef(nodeId: string): string | null;
 /** Build the searchable artifact set for a scope + corpus filter. Node facets
  *  are applied against the db rows first (cheap); only surviving nodes' files
  *  are read. */

package/dist/core/canvas/history.js

@@ -220,7 +220,7 @@ function metaArtifact(row, desc) {
         loadBody: () => body,
     };
 }
-/** List the markdown reports a node left, newest filename first. */
+/** List the markdown reports a node left, in directory order. */
 function listReportFiles(nodeId) {
     const dir = reportsDir(nodeId);
     if (!pathExists(dir))
@@ -232,6 +232,17 @@ function listReportFiles(nodeId) {
         return [];
     }
 }
+/** The history ref of a node's newest report, or null when it left none.
+ *  Report filenames lead with a compact timestamp, so the lexicographic maximum
+ *  is the latest one. Callers use this to hand a reader something they can
+ *  actually open (`crtr canvas history read <ref>`) instead of a bare node id. */
+export function newestReportRef(nodeId) {
+    let newest = null;
+    for (const f of listReportFiles(nodeId))
+        if (newest === null || f > newest)
+            newest = f;
+    return newest === null ? null : `${nodeId}:reports/${newest}`;
+}
 /** Enumerate every context markdown doc a node left (recursive). */
 function listDocFiles(nodeId) {
     const dir = contextDir(nodeId);

package/dist/core/canvas/migrations.js

@@ -21,7 +21,7 @@
 // `db.ts` itself keeps only connection management (`openDb`/`withCanvasWrite`
 // /`closeDb`) and re-exports `migrate`/`MIGRATIONS` from here so external
 // imports are unaffected by this split.
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
 import { crtrHome, isSafeNodeId, nodesRoot, nodeMetaPath } from './paths.js';
 import { STATE_MIGRATIONS } from '../../migrations/registry.js';
@@ -1215,6 +1215,62 @@ function addNodeSessionFileIndex(db) {
     }
     db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_pi_session_file ON nodes(pi_session_file);');
 }
+/** v36 — one Pi transcript may have exactly one node owner. Normalize every
+ * stored path first (including meta), then retain the earliest created row
+ * (node_id breaks equal timestamps) and clear both durable session coordinates
+ * from every later claimant before creating the UNIQUE index. */
+function makeNodeSessionFileUnique(db) {
+    const canonical = (sessionFile) => {
+        const absolute = resolve(sessionFile);
+        return existsSync(absolute) ? realpathSync(absolute) : absolute;
+    };
+    const rows = db.prepare(`
+SELECT node_id, pi_session_file
+FROM nodes
+WHERE pi_session_file IS NOT NULL
+ORDER BY created ASC, node_id ASC
+`).all();
+    const setFile = db.prepare('UPDATE nodes SET pi_session_file = ? WHERE node_id = ?');
+    for (const row of rows) {
+        const sessionFile = canonical(row.pi_session_file);
+        if (sessionFile === row.pi_session_file)
+            continue;
+        // Identity is authoritative, so normalize both stores before grouping.
+        updateJsonFileDurably(nodeMetaPath(row.node_id), (meta) => {
+            meta['pi_session_file'] = sessionFile;
+            return true;
+        });
+        setFile.run(sessionFile, row.node_id);
+    }
+    const duplicates = db.prepare(`
+SELECT pi_session_file
+FROM nodes
+WHERE pi_session_file IS NOT NULL
+GROUP BY pi_session_file
+HAVING COUNT(*) > 1
+`).all();
+    const clearRow = db.prepare('UPDATE nodes SET pi_session_file = NULL WHERE node_id = ?');
+    for (const { pi_session_file } of duplicates) {
+        const owners = db.prepare(`
+SELECT node_id
+FROM nodes
+WHERE pi_session_file = ?
+ORDER BY created ASC, node_id ASC
+`).all(pi_session_file);
+        for (const { node_id } of owners.slice(1)) {
+            // Clear both durable coordinates so a later reindex cannot restore the
+            // duplicate projection.
+            updateJsonFileDurably(nodeMetaPath(node_id), (meta) => {
+                meta['pi_session_id'] = null;
+                meta['pi_session_file'] = null;
+                return true;
+            });
+            clearRow.run(node_id);
+        }
+    }
+    db.exec('DROP INDEX IF EXISTS idx_nodes_pi_session_file;');
+    db.exec('CREATE UNIQUE INDEX IF NOT EXISTS idx_nodes_pi_session_file ON nodes(pi_session_file);');
+}
 /** v35 — durable node lifecycle execution state and terminal cause. */
 function addNodeLifecycleColumns(db) {
     const columns = nodeColumns(db);
@@ -1283,6 +1339,7 @@ export const MIGRATIONS = [
     /* v33 */ addHumanActionDeliveries,
     /* v34 */ addNodeSessionFileIndex,
     /* v35 */ addNodeLifecycleColumns,
+    /* v36 */ makeNodeSessionFileUnique,
     ...JOURNALED_STATE_MIGRATIONS,
 ];
 /** Migration indexes that manage their OWN transaction and therefore must not

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

@@ -252,7 +252,7 @@ export interface TeardownSnapshot {
      *  before this snapshot was taken. Callers must skip ALL signaling when true. */
     reused: boolean;
 }
-export declare function captureTeardownSnapshot(rootPid: number, expectedIdentity: string | null): TeardownSnapshot;
+export declare function captureTeardownSnapshot(rootPid: number, expectedIdentity: string | null, excludePid?: number): TeardownSnapshot;
 /** Best-effort signal against every pid in an ALREADY-CAPTURED tree snapshot
  *  (typically `[rootPid, ...descendantPids(rootPid)]`, taken ONCE by the
  *  caller before sending any signal — see the doc on `isProcessTreeAlive` for

package/dist/core/canvas/pid.js

@@ -500,7 +500,7 @@ export function capturePidCommand(pid) {
         return null;
     }
 }
-export function captureTeardownSnapshot(rootPid, expectedIdentity) {
+export function captureTeardownSnapshot(rootPid, expectedIdentity, excludePid) {
     if (!Number.isInteger(rootPid) || rootPid <= 0)
         return { tree: [], identities: null, reused: false };
     const table = captureLivenessSnapshot();
@@ -512,7 +512,10 @@ export function captureTeardownSnapshot(rootPid, expectedIdentity) {
         !identitiesMatch(currentRootIdentity, expectedIdentity);
     if (reused)
         return { tree: [], identities: null, reused: true };
-    const tree = [rootPid, ...descendantPidsFrom(rootPid, table.childrenOf)];
+    const excluded = excludePid !== undefined && Number.isInteger(excludePid) && excludePid > 0
+        ? new Set([excludePid, ...descendantPidsFrom(excludePid, table.childrenOf)])
+        : undefined;
+    const tree = [rootPid, ...descendantPidsFrom(rootPid, table.childrenOf)].filter((pid) => !excluded?.has(pid));
     const identities = new Map();
     for (const pid of tree) {
         const id = table.processes.get(pid)?.identity;

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

@@ -143,6 +143,10 @@ export interface NodeIdentity {
      *  `parent` so an INDEPENDENT root (parent=null) still records its lineage.
      *  Audit only; null for a user-opened root. Defaults to `parent` for a child. */
     spawned_by?: string | null;
+    /** Actor that created this node; null when an external process did. Unlike
+     *  `parent` (manager) and `spawned_by` (provenance edge), this determines
+     *  whether birth is announced to the manager. */
+    creator?: string | null;
     /** Raw `--fork-from` operand retained for identity framing and audit. */
     fork_from?: string | null;
     /** Resolved absolute source session file used for every pre-bind fork retry. */

package/dist/core/feed/feed.d.ts

@@ -1,7 +1,10 @@
 import type { InboxDisposition } from './inbox.js';
 export type PushKind = 'update' | 'urgent' | 'final';
+export type PushDeliveryTier = 'deferred' | 'normal' | 'urgent';
 export interface PushOpts {
     kind: PushKind;
+    /** Update-only subscriber delivery urgency; report kind remains `kind`. */
+    deliveryTier?: PushDeliveryTier;
     body: string;
     from?: string;
     /** Attribution snapshotted by the human-ticket settlement paths; absent means an ordinary report. */
@@ -25,6 +28,7 @@ export declare class FinalDeliveryError extends Error {
 export declare function push(nodeId: string, opts: PushOpts): Promise<PushResult>;
 export declare function pushUpdate(nodeId: string, body: string, opts?: {
     from?: string;
+    deliveryTier?: PushDeliveryTier;
 }): Promise<PushResult>;
 export declare function pushUrgent(nodeId: string, body: string, opts?: {
     from?: string;

package/dist/core/feed/feed.js

@@ -51,18 +51,21 @@ function firstLine(text, maxLen = 80) {
     const line = text.split('\n')[0] ?? '';
     return line.length > maxLen ? `${line.slice(0, maxLen - 1)}…` : line;
 }
-function tierFor(kind) {
-    return kind === 'urgent' ? 'urgent' : 'normal';
+/** Requested update delivery urgency wins; legacy report-kind mapping is the fallback. */
+function tierFor(kind, requestedTier) {
+    return requestedTier ?? (kind === 'urgent' ? 'urgent' : 'normal');
 }
-function deliver(subscribers, from, fromName, kind, reportRef, body, disposition) {
+function deliver(subscribers, from, fromName, kind, requestedTier, reportRef, body, disposition) {
     const deliveredTo = [];
     const failedTo = [];
     const label = firstLine(body);
     for (const sub of subscribers) {
         try {
-            const entry = { from, ...(fromName === undefined ? {} : { from_name: fromName }), tier: tierFor(kind), kind, ref: reportRef, label, ...(disposition === undefined ? {} : { disposition }) };
-            if (sub.active)
+            const entry = { from, ...(fromName === undefined ? {} : { from_name: fromName }), tier: tierFor(kind, requestedTier), kind, ref: reportRef, label, ...(disposition === undefined ? {} : { disposition }) };
+            if (sub.active) {
                 appendInbox(sub.node_id, entry);
+                cancelCronsOnWake(sub.node_id);
+            }
             else
                 appendPassive(sub.node_id, entry);
             deliveredTo.push(sub.node_id);
@@ -108,6 +111,8 @@ function commitCanonicalFinal(nodeId, staged) {
 async function pushWithContext(nodeId, opts) {
     if (!nodeId)
         throw new Error(`push: empty nodeId (kind=${opts.kind}) — a report must belong to a node`);
+    if (opts.kind === 'final' && opts.deliveryTier !== undefined)
+        throw new Error('push final does not accept a delivery tier');
     const staged = stageReport(nodeId, opts.kind, opts.body);
     const from = opts.from ?? nodeId;
     const fromName = getNode(from)?.name;
@@ -121,14 +126,14 @@ async function pushWithContext(nodeId, opts) {
         // cancel-on-wake rows anchored here go; standing crons survive. Outside
         // commitCanonicalFinal's transaction — it takes its own write boundary.
         cancelCronsOnWake(nodeId);
-        const { deliveredTo, failedTo } = deliver(subscribers, from, fromName, opts.kind, `${nodeId}:reports/${staged.basename}`, opts.body, opts.disposition);
+        const { deliveredTo, failedTo } = deliver(subscribers, from, fromName, opts.kind, undefined, `${nodeId}:reports/${staged.basename}`, opts.body, opts.disposition);
         if (failedTo.length > 0)
             throw new FinalDeliveryError(staged.finalPath, deliveredTo, failedTo);
         return { reportPath: staged.finalPath, deliveredTo };
     }
     try {
         install(staged);
-        const { deliveredTo, failedTo } = deliver(subscribersOf(nodeId), from, fromName, opts.kind, `${nodeId}:reports/${staged.basename}`, opts.body, opts.disposition);
+        const { deliveredTo, failedTo } = deliver(subscribersOf(nodeId), from, fromName, opts.kind, opts.deliveryTier, `${nodeId}:reports/${staged.basename}`, opts.body, opts.disposition);
         if (failedTo.length > 0)
             throw new Error(`report published at ${staged.finalPath}; delivery failed for ${failedTo.join(', ')}`);
         return { reportPath: staged.finalPath, deliveredTo };
@@ -156,7 +161,7 @@ export function redeliverFinalReport(nodeId, originNodeId, reportBasename, body,
     if (reportBasename === '' || reportBasename.includes('/') || reportBasename.includes('\\')) {
         throw new Error(`invalid canonical final report basename: ${reportBasename}`);
     }
-    const { deliveredTo, failedTo } = deliver([{ node_id: originNodeId, active: true, created: '' }], nodeId, getNode(nodeId)?.name, 'final', `${nodeId}:reports/${reportBasename}`, body, opts?.disposition);
+    const { deliveredTo, failedTo } = deliver([{ node_id: originNodeId, active: true, created: '' }], nodeId, getNode(nodeId)?.name, 'final', undefined, `${nodeId}:reports/${reportBasename}`, body, opts?.disposition);
     const reportPath = join(reportsDir(nodeId), reportBasename);
     if (failedTo.length > 0)
         throw new FinalDeliveryError(reportPath, deliveredTo, failedTo);

package/dist/core/feed/inbox.d.ts

@@ -41,7 +41,8 @@ export type InboxEntryInput = Omit<InboxEntry, 'entry_id' | 'ts' | 'operation_id
 };
 /** Complete an entry exactly once before any spill or append work. */
 export declare function finalizeInboxEntry(input: InboxEntryInput): InboxEntry;
-/** Atomically append one finalized inbox entry to `nodes/<nodeId>/inbox.jsonl`. */
+/** Atomically append one finalized inbox entry to `nodes/<nodeId>/inbox.jsonl`,
+ *  at the tier `effectiveTier` resolves for this target. */
 export declare function appendInbox(nodeId: string, entry: InboxEntryInput): InboxEntry;
 /** Deliver the one system notice for a controller that can no longer satisfy a
  * wait. Returns null when another durable operation already settled or re-armed

package/dist/core/feed/inbox.js

@@ -13,12 +13,13 @@
 import { appendFileSync, existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { randomBytes, randomUUID } from 'node:crypto';
-import { deliverAndSettleMessageWait, inboxPath, messagesDir, settleDeadMessageWait } from '../canvas/index.js';
+import { deliverAndSettleMessageWait, getRow, inboxPath, messagesDir, settleDeadMessageWait } from '../canvas/index.js';
 import { resolveRef } from '../canvas/history.js';
 import { emitEvent } from '../events/emit.js';
 import { errorClassFromError } from '../events/errors.js';
 import { generateOperationId, operationIdContext, validateOperationId } from '../events/operation-id.js';
 import { formatInboxCard } from '../../shared/generated-context.js';
+import { renderBirthAnnouncementBody } from '../../shared/birth-announcement.js';
 const INBOX_ENTRY_ID = /^(?!0{32}$)[0-9a-f]{32}$/;
 function validateInboxEntryId(value) {
     if (typeof value !== 'string' || !INBOX_ENTRY_ID.test(value))
@@ -64,9 +65,24 @@ function writeMessageBody(nodeId, ts, body) {
     renameSync(tmpPath, finalPath);
     return finalPath;
 }
-/** Atomically append one finalized inbox entry to `nodes/<nodeId>/inbox.jsonl`. */
+/** The tier a live watcher injects into the turn a node is ALREADY running
+ *  (`visibleRoute`, canvas-inbox-watcher). `normal` and `deferred` both wait
+ *  for a later cycle instead. */
+const STEERING_TIER = 'urgent';
+/** The tier an entry is actually appended at. A terminal node owes one final
+ *  result and reaps on it, so the later cycle `normal` and `deferred` wait for
+ *  is one it may never take — mail handed to such a node is raised to the
+ *  steering tier so the turn it is running now carries it, and so a dormant one
+ *  is woken for it rather than holding it forever. */
+function effectiveTier(nodeId, tier) {
+    if (tier !== 'normal' && tier !== 'deferred')
+        return tier;
+    return getRow(nodeId)?.lifecycle === 'terminal' ? STEERING_TIER : tier;
+}
+/** Atomically append one finalized inbox entry to `nodes/<nodeId>/inbox.jsonl`,
+ *  at the tier `effectiveTier` resolves for this target. */
 export function appendInbox(nodeId, entry) {
-    const full = finalizeInboxEntry(entry);
+    const full = finalizeInboxEntry({ ...entry, tier: effectiveTier(nodeId, entry.tier) });
     try {
         // A push pointer already carries its canonical history `ref` — its body
         // lives in the report file, never inline. A direct message / system notice has no ref yet: when
@@ -353,6 +369,9 @@ function inlineReport(e) {
  * behavior.
  */
 function entryBody(e) {
+    const birth = renderBirthAnnouncementBody(e.data, e.ts);
+    if (birth !== null)
+        return birth;
     const report = inlineReport(e);
     if (report !== null)
         return report.trimEnd();

package/dist/core/git.d.ts

@@ -3,6 +3,9 @@ export interface GitResult {
     stdout: string;
     stderr: string;
     timedOut?: boolean;
+    /** The child did not exit with a numeric status (for example, spawn failure or timeout). */
+    executionFailed?: true;
+    processError?: string;
 }
 export interface GitSyncOptions {
     timeoutMs?: number;

package/dist/core/git.js

@@ -3,10 +3,12 @@ import { network } from './errors.js';
 export function gitSync(args, cwd, input, options = {}) {
     const res = spawnSync('git', args, { cwd, encoding: 'utf8', input, timeout: options.timeoutMs });
     const status = typeof res.status === 'number' ? res.status : 1;
+    const completed = typeof res.status === 'number';
     const stdout = typeof res.stdout === 'string' ? res.stdout : '';
     const stderr = typeof res.stderr === 'string' ? res.stderr : '';
+    const processError = res.error === undefined ? undefined : String(res.error);
     const timedOut = res.error?.code === 'ETIMEDOUT';
-    return { status, stdout, stderr, ...(timedOut ? { timedOut: true } : {}) };
+    return { status, stdout, stderr, ...(completed ? {} : { executionFailed: true }), ...(processError === undefined ? {} : { processError }), ...(timedOut ? { timedOut: true } : {}) };
 }
 export async function gitAsync(args, cwd) {
     return new Promise((resolve) => {

package/dist/core/human/feedback-companion.js

@@ -72,6 +72,7 @@ export async function realizeFeedbackCompanion(args) {
         cwd: origin.cwd,
         profile_id: origin.profile_id ?? null,
         parent: args.senderNodeId,
+        creator: args.senderNodeId,
         subscribe: false,
         forkFrom: branchFile,
         forkSourceFile: branchFile,

package/dist/core/preview-registry.js

@@ -150,7 +150,6 @@ export const LEAF_ICON_CP = {
     'pkg market list': 0xf03a,
     'pkg market browse': 0xf14e,
     'push update': 0xf093,
-    'push urgent': 0xf0e7,
     'push final': 0xf11e,
     'search web': 0xf0ac,
     'search answer': 0xf075,

package/dist/core/review/companion.js

@@ -164,6 +164,7 @@ export function spawnReviewCompanion(spec) {
         cwd: spec.cwd,
         profile_id: spec.profileId,
         parent: spec.originNodeId,
+        creator: spec.originNodeId,
         subscribe: false,
         forkFrom: spec.branchFile,
         forkSourceFile: spec.branchFile,

package/dist/core/review/realize.js

@@ -104,6 +104,7 @@ function realizeBridge(review) {
             kind: 'human',
             lifecycle: 'terminal',
             parent: current.origin_node_id,
+            creator: current.origin_node_id,
             cwd: origin.cwd,
             profile_id: origin.profile_id ?? null,
             name: 'human-review',

package/dist/core/runtime/broker/auth-reload.d.ts

@@ -4,6 +4,7 @@ import type { BrokerClient } from './client-registry.js';
 import type { FrameReplies } from './frame-replies.js';
 import type { RebindDriver } from './rebind.js';
 import type { BrokerSession } from './read-ops.js';
+import type { TurnAdmissionGate } from './turn-admission.js';
 type ResolvedLaunchModel = {
     model: NonNullable<ReturnType<ModelRegistry['find']>>;
     thinkingLevel: string | undefined;
@@ -35,5 +36,6 @@ export declare function createAuthReloadGate(deps: {
     resolveLaunchModel: (services: AgentSessionServices, cfg: BrokerSdkConfig) => Promise<ResolvedLaunchModel>;
     /** A reconcile that finally resolves a model releases the held launch prompt. */
     driveKickoff: () => void;
+    turnAdmission: TurnAdmissionGate;
 }): AuthReloadGate;
 export {};

package/dist/core/runtime/broker/auth-reload.js

@@ -4,7 +4,7 @@ import { emitEvent } from '../../events/emit.js';
 import { clearFault, readFault } from '../fault.js';
 import { isUnknownModel } from '../model-selection.js';
 export function createAuthReloadGate(deps) {
-    const { nodeId, cfg, replies, rebind, session, services, broadcastModelChanged, formatModelSpec, resolveLaunchModel, driveKickoff, } = deps;
+    const { nodeId, cfg, replies, rebind, session, services, broadcastModelChanged, formatModelSpec, resolveLaunchModel, driveKickoff, turnAdmission, } = deps;
     let reloadInFlight = null;
     let faultRedriveInFlight = false;
     /** True once the engine this work started against has been replaced — every
@@ -112,8 +112,14 @@ export function createAuthReloadGate(deps) {
                     fresh.kind !== 'auth' ||
                     fresh.since !== authFault.since)
                     return;
-                clearFault(nodeId, { link: 'pi→provider' });
-                await faultSession.prompt(formatCard('recovery', {}, AUTH_FAULT_RECOVERY_BODY));
+                await turnAdmission.admit((release) => {
+                    if (supersededBy(generation, faultSession) || faultSession.isStreaming) {
+                        release();
+                        return Promise.resolve();
+                    }
+                    clearFault(nodeId, { link: 'pi→provider' });
+                    return faultSession.prompt(formatCard('recovery', {}, AUTH_FAULT_RECOVERY_BODY), { preflightResult: release });
+                });
             }
             catch (err) {
                 emitEvent({

package/dist/core/runtime/broker/engine-drive.d.ts

@@ -8,6 +8,7 @@ import type { BrokerSession } from './read-ops.js';
 import type { RebindDriver } from './rebind.js';
 import type { ToolGroupTracker } from './tool-groups.js';
 import type { PromptDispatchTracker } from './turn-ignition.js';
+import type { TurnAdmissionGate } from './turn-admission.js';
 /** The frames that drive the live engine — the viewer's input vocabulary. */
 export type DriveFrame = Extract<ClientToBroker, {
     type: 'prompt' | 'steer' | 'follow_up' | 'abort' | 'bash';
@@ -23,4 +24,5 @@ export declare function createEngineDriver(deps: {
     rebind: RebindDriver;
     projection: EventProjection;
     toolGroups: ToolGroupTracker;
+    turnAdmission: TurnAdmissionGate;
 }): EngineDriver;