@north-light/crouter 0.3.249 → 0.3.251

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;

package/dist/core/runtime/broker/engine-drive.js

@@ -1,9 +1,10 @@
 import { emitEvent } from '../../events/emit.js';
 import { operationIdContext } from '../../events/operation-id.js';
 import { promptWithAdvertisedCommandInvocation } from '../advertised-command-invocation.js';
+import { heldDeferredInboxPromptJoin } from './held-deferred-inbox.js';
 import { chooseGuidanceDeliveryMode, promptWithNextTurnGuidance, resolveEngineRoute, resolveSteerCall, } from './engine-routing.js';
 export function createEngineDriver(deps) {
-    const { registry, replies, session, dispatches, memoryRefs, authReloadGate, rebind, projection, toolGroups, } = deps;
+    const { registry, replies, session, dispatches, memoryRefs, authReloadGate, rebind, projection, toolGroups, turnAdmission, } = deps;
     const { ackTo, engineErrorTo } = replies;
     const errorRelay = (client) => {
         let failure;
@@ -39,18 +40,32 @@ export function createEngineDriver(deps) {
         // before the caught promise resolves, so reading it after the chain is
         // the call's verdict.
         const settle = (p) => p.then(() => errors.failure());
-        const dispatch = () => {
+        const dispatch = () => turnAdmission.admit((release) => {
+            // A prior prompt can be in asynchronous preflight while isStreaming is
+            // false. Admission waits for that preflight, then routes against the
+            // state it actually established instead of its stale snapshot.
             const route = resolveEngineRoute(frame, session().isStreaming);
+            const promptOptions = route.call === 'prompt' ? route.options : undefined;
             const guidance = memoryRefs.guidanceFor(frame.text);
+            const prompt = async () => {
+                // Both human surfaces converge at this admitted boundary. The watcher
+                // claims held deferred mail before the prompt body, but its cursor stays
+                // uncommitted until the resulting turn's agent_settled event.
+                if (route.call === 'prompt' && !session().isStreaming) {
+                    await heldDeferredInboxPromptJoin()?.(session());
+                }
+                await session().prompt(frame.text, { ...promptOptions, preflightResult: release });
+            };
             if (guidance === null) {
                 if (route.call === 'prompt') {
                     // A routed prompt STARTS a turn — including an idle follow_up
                     // escalated by m-C — so it gets a fresh operation id. A true
                     // (mid-stream) followUp rides the current turn's operation, like
                     // steer.
-                    return settle(dispatches.track(operationIdContext.fresh(() => promptWithAdvertisedCommandInvocation(session(), frame.text, () => session().prompt(frame.text, route.options)).catch(relayError))));
+                    return settle(dispatches.track(operationIdContext.fresh(() => promptWithAdvertisedCommandInvocation(session(), frame.text, prompt).catch(relayError))));
                 }
                 // C1: pi's followUp() takes images as a POSITIONAL 2nd arg (`followUp(text, images?)`).
+                release();
                 return settle(session().followUp(frame.text, frame.images).catch(relayError));
             }
             const deliverAs = chooseGuidanceDeliveryMode(frame.type, route.call, session().isStreaming);
@@ -63,19 +78,20 @@ export function createEngineDriver(deps) {
                     // ATOMICALLY clears its own pending entry if prompt() settles
                     // without ever reaching that drain (an early throw/return leaves
                     // nothing stranded to leak into a later, unrelated turn).
-                    return settle(dispatches.track(promptWithNextTurnGuidance(session(), guidance, () => operationIdContext.fresh(() => promptWithAdvertisedCommandInvocation(session(), frame.text, () => session().prompt(frame.text, route.options)))).catch(relayError)));
+                    return settle(dispatches.track(promptWithNextTurnGuidance(session(), guidance, () => operationIdContext.fresh(() => promptWithAdvertisedCommandInvocation(session(), frame.text, prompt))).catch(relayError)));
                 }
-                return settle(dispatches.track(operationIdContext.fresh(() => promptWithAdvertisedCommandInvocation(session(), frame.text, () => session().prompt(frame.text, route.options))
+                return settle(dispatches.track(operationIdContext.fresh(() => promptWithAdvertisedCommandInvocation(session(), frame.text, prompt)
                     .catch(relayError)
                     .then(() => sendGuidance(guidance, deliverAs)))));
             }
             // deliverAs is always 'followUp' here per chooseGuidanceDeliveryMode's
             // contract (a followUp routeCall never yields 'nextTurn').
+            release();
             return settle(session()
                 .followUp(frame.text, frame.images)
                 .catch(relayError)
                 .then(() => sendGuidance(guidance, deliverAs)));
-        };
+        });
         // /login acknowledges before its asynchronous local refresh completes.
         // An idle turn must not overtake that refresh and launch on the stale
         // route; true mid-stream follow-ups keep their immediate queue behavior.
@@ -130,23 +146,23 @@ export function createEngineDriver(deps) {
      */
     const driveSteer = (frame, errors) => {
         const relayError = errors.relay;
-        if (resolveSteerCall(frame.text, session()) === 'prompt') {
-            void promptWithAdvertisedCommandInvocation(session(), frame.text, () => session().prompt(frame.text, {
-                images: frame.images,
-                streamingBehavior: 'steer',
-            })).catch(relayError);
-            return;
-        }
-        const guidance = memoryRefs.guidanceFor(frame.text);
-        // C1: pi's steer() takes images as a POSITIONAL 2nd arg (`steer(text, images?)`).
-        if (guidance === null) {
-            void session().steer(frame.text, frame.images).catch(relayError);
-            return;
-        }
-        void session()
-            .steer(frame.text, frame.images)
-            .catch(relayError)
-            .then(() => sendGuidance(guidance, 'steer'));
+        void turnAdmission.admit((release) => {
+            if (resolveSteerCall(frame.text, session()) === 'prompt') {
+                return promptWithAdvertisedCommandInvocation(session(), frame.text, () => session().prompt(frame.text, {
+                    images: frame.images,
+                    streamingBehavior: 'steer',
+                    preflightResult: release,
+                }));
+            }
+            release();
+            const guidance = memoryRefs.guidanceFor(frame.text);
+            // C1: pi's steer() takes images as a POSITIONAL 2nd arg (`steer(text, images?)`).
+            if (guidance === null)
+                return session().steer(frame.text, frame.images);
+            return session()
+                .steer(frame.text, frame.images)
+                .then(() => sendGuidance(guidance, 'steer'));
+        }).catch(relayError);
     };
     /**
      * esc/abort cancels whatever is live: a running `!` command (abortBash)

package/dist/core/runtime/broker/event-projection.d.ts

@@ -21,6 +21,7 @@ export declare class EventProjection {
     private pendingUpdateTimer;
     private workingActivity;
     private readonly streamWatchdog;
+    private readonly toolExecutionWatchdog;
     private readonly streamWatchdogMs;
     private pendingBroadcast;
     private broadcastGeneration;
@@ -30,8 +31,11 @@ export declare class EventProjection {
     flush(): void;
     reset(): void;
     dispose(): void;
+    /** Arms the applicable watchdog floor after a streaming event or rebind. */
+    rearmIfStreaming(generation: SubscriptionGeneration): void;
     knownStreamWait(deadlineMs: number): () => void;
     relayEvent(event: BrokerToClient, generation: SubscriptionGeneration): void;
+    private abortStalledStream;
     private clearPendingUpdate;
     private flushPendingUpdate;
     private invalidatePendingBroadcasts;

package/dist/core/runtime/broker/event-projection.js

@@ -6,6 +6,9 @@ import { withoutYieldAbort } from '../session-cycles.js';
 import { DEFAULT_WORKING_ACTIVITY, randomWorkingActivity } from '../../../shared/working-activity.js';
 import { hydrateLiveAdvertisedCommandMessage, prepareAdvertisedCommandPersistence, } from '../advertised-command-invocation.js';
 const MESSAGE_UPDATE_COALESCE_MS = 75;
+// Match the daemon's wedge grace: a tool may legitimately be silent longer than
+// a provider stream, but it cannot leave the broker unguarded indefinitely.
+const TOOL_EXECUTION_WATCHDOG_MS = 20 * 60_000;
 /** Projects one live engine event stream to broker viewers and owns its relay timers. */
 export class EventProjection {
     deps;
@@ -13,25 +16,18 @@ export class EventProjection {
     pendingUpdateTimer = null;
     workingActivity = DEFAULT_WORKING_ACTIVITY;
     streamWatchdog;
+    toolExecutionWatchdog;
     streamWatchdogMs = envStreamWatchdogMs();
     pendingBroadcast = null;
     broadcastGeneration = 0;
     constructor(deps) {
         this.deps = deps;
         this.streamWatchdog = new StreamWatchdog((armedGeneration) => {
-            const generation = this.deps.installedGeneration();
-            if (generation === undefined || armedGeneration !== generation.id)
-                return;
-            emitEvent({
-                level: 'debug',
-                event: 'broker.runtime.diagnostic',
-                fields: { message: `stream watchdog: no engine event for ${this.streamWatchdogMs}ms while streaming — aborting stalled provider stream` },
-            });
-            generation.stagedWatchdogAbort = true;
-            void generation.session.abort().catch((err) => {
-                emitEvent({ level: 'debug', event: 'broker.runtime.diagnostic', fields: { message: `stream watchdog abort failed: ${String(err)}` } });
-            });
+            this.abortStalledStream(armedGeneration, this.streamWatchdogMs, 'while streaming — aborting stalled provider stream');
         }, this.streamWatchdogMs);
+        this.toolExecutionWatchdog = new StreamWatchdog((armedGeneration) => {
+            this.abortStalledStream(armedGeneration, TOOL_EXECUTION_WATCHDOG_MS, 'while a tool is executing — aborting stalled tool execution');
+        }, TOOL_EXECUTION_WATCHDOG_MS);
     }
     currentWorkingActivity() {
         return this.workingActivity;
@@ -46,11 +42,25 @@ export class EventProjection {
         this.clearPendingUpdate();
         this.invalidatePendingBroadcasts();
         this.streamWatchdog.reset();
+        this.toolExecutionWatchdog.reset();
     }
     dispose() {
         this.clearPendingUpdate();
         this.invalidatePendingBroadcasts();
         this.streamWatchdog.reset();
+        this.toolExecutionWatchdog.reset();
+    }
+    /** Arms the applicable watchdog floor after a streaming event or rebind. */
+    rearmIfStreaming(generation) {
+        if (!generation.session.isStreaming)
+            return;
+        if (generation.executingTools.size > 0) {
+            this.streamWatchdog.clear();
+            this.toolExecutionWatchdog.poke(generation.id);
+            return;
+        }
+        this.toolExecutionWatchdog.clear();
+        this.streamWatchdog.poke(generation.id);
     }
     knownStreamWait(deadlineMs) {
         if (!Number.isFinite(deadlineMs) || deadlineMs <= Date.now())
@@ -99,18 +109,14 @@ export class EventProjection {
         if (type === 'agent_end') {
             generation.executingTools.clear();
             this.streamWatchdog.reset();
+            this.toolExecutionWatchdog.reset();
         }
-        else if (type === 'tool_execution_start') {
-            generation.executingTools.add(event.toolCallId ?? '');
-            this.streamWatchdog.clear();
-        }
-        else if (type === 'tool_execution_end') {
-            generation.executingTools.delete(event.toolCallId ?? '');
-            if (generation.executingTools.size === 0 && generation.session.isStreaming)
-                this.streamWatchdog.poke(generation.id);
-        }
-        else if (generation.session.isStreaming && generation.executingTools.size === 0) {
-            this.streamWatchdog.poke(generation.id);
+        else {
+            if (type === 'tool_execution_start')
+                generation.executingTools.add(event.toolCallId ?? '');
+            else if (type === 'tool_execution_end')
+                generation.executingTools.delete(event.toolCallId ?? '');
+            this.rearmIfStreaming(generation);
         }
         if (type === 'message_update') {
             this.pendingUpdate = event;
@@ -128,6 +134,20 @@ export class EventProjection {
         }
         this.broadcast(event);
     }
+    abortStalledStream(armedGeneration, timeoutMs, context) {
+        const generation = this.deps.installedGeneration();
+        if (generation === undefined || armedGeneration !== generation.id)
+            return;
+        emitEvent({
+            level: 'debug',
+            event: 'broker.runtime.diagnostic',
+            fields: { message: `stream watchdog: no engine event for ${timeoutMs}ms ${context}` },
+        });
+        generation.stagedWatchdogAbort = true;
+        void generation.session.abort().catch((err) => {
+            emitEvent({ level: 'debug', event: 'broker.runtime.diagnostic', fields: { message: `stream watchdog abort failed: ${String(err)}` } });
+        });
+    }
     clearPendingUpdate() {
         if (this.pendingUpdateTimer !== null) {
             clearTimeout(this.pendingUpdateTimer);