@north-light/crouter 0.3.251 → 0.3.252

package/dist/core/runtime/broker.js

@@ -47,6 +47,7 @@ import { ToolGroupTracker } from './broker/tool-groups.js';
 import { onNodeNamed } from './broker/node-named.js';
 import { FaultRetry } from './broker/fault-retry.js';
 import { createTurnAdmissionGate } from './broker/turn-admission.js';
+import { BROKER_IDLE_TURN_START } from './broker/held-deferred-inbox.js';
 import { EventProjection } from './broker/event-projection.js';
 import { createFrameDispatchContext, handleFrame, } from './broker/frame-dispatch.js';
 import { hydratePersistedAdvertisedCommandMessages, installAdvertisedCommandInvocationContract, } from './advertised-command-invocation.js';
@@ -327,6 +328,24 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
         registry.broadcast({ type: 'model_changed', model: isUnknownModel(liveSession.model) ? undefined : liveSession.model, spec });
     };
     const turnAdmission = createTurnAdmissionGate();
+    // The inbox watcher is Jiti-loaded and cannot import this native module's
+    // gate. Its idle delivery therefore calls this narrow process-global bridge:
+    // acquire admission first, then re-read the live session before prompt() so
+    // a viewer turn that won the race is joined rather than double-started.
+    const startIdleInboxTurn = (text) => {
+        void turnAdmission.admit((release) => {
+            const liveSession = rebind.session();
+            return liveSession
+                .prompt(text, {
+                preflightResult: release,
+                ...(liveSession.isStreaming ? { streamingBehavior: 'steer' } : {}),
+            })
+                .catch((error) => {
+                emitEvent({ level: 'error', event: 'broker.inbox.idle_prompt_failed', error });
+            });
+        });
+    };
+    globalThis[BROKER_IDLE_TURN_START] = startIdleInboxTurn;
     faultRetry = new FaultRetry({
         nodeId,
         cfg,

package/dist/core/runtime/close.js

@@ -49,12 +49,12 @@ export function fanDoctrineWake(fromId, subscribers, label, data, tier = 'normal
         try {
             const notice = { from: fromId, tier, kind: 'message', label, data };
             if (sub.active) {
-                appendInbox(sub.node_id, notice);
+                const entry = appendInbox(sub.node_id, notice);
                 // A wake-capable notice consumes the subscriber's cancel-on-wake
                 // deadline: the thing it was waiting for arrived. `deferred` is the
                 // exception — it never wakes a node, riding the next natural cycle
                 // instead, so the deadline it was racing must survive.
-                if (tier !== 'deferred')
+                if (entry.tier !== 'deferred')
                     cancelCronsOnWake(sub.node_id);
             }
             else

package/dist/core/runtime/fault.js

@@ -229,11 +229,14 @@ export function clearFault(nodeId, opts) {
         if (opts?.link !== undefined && current.link !== opts.link)
             return false;
         rmSync(faultPath(nodeId));
-        if (opts?.preserveProviderRetryEpisode !== true) {
-            const episode = currentProviderRetryEpisode(nodeId);
-            if (episode?.fault.since === current.since)
-                rmSync(providerRetryPath(nodeId), { force: true });
-        }
+        const episode = currentProviderRetryEpisode(nodeId);
+        // turn_end precedes agent_settled. An admitted retry keeps its durable
+        // coordinate while the broker classifies an error settlement; an invalidated
+        // coordinate also remains durable so replacement startup cannot replay it.
+        if (opts?.preserveProviderRetryEpisode !== true &&
+            episode?.fault.since === current.since &&
+            episode.state === 'pending')
+            rmSync(providerRetryPath(nodeId), { force: true });
         const operationId = resolveOperationId();
         emitEvent({
             level: 'info',

package/dist/core/runtime/recycle.js

@@ -5,8 +5,8 @@
 //
 //   1. Finalize — push the agent's last surfaced message as a `final` report so
 //      every subscriber/manager waiting on it is unblocked, and mark it done.
-//   2. Close    — tear the agent's broker engine down (the pane is only a viewer).
-//   3. Recycle  — boot a fresh resident broker root the pane re-attaches to.
+//   2. Recycle  — boot a fresh resident broker root and prove it accepts viewers.
+//   3. Close    — tear the finalized broker down, then re-attach the pane to the replacement.
 //
 // NOT to be confused with `node lifecycle demote` (flip-to-terminal IN PLACE, which keeps
 // the agent focused and running): recycle ENDS this agent and boots a brand-new
@@ -17,7 +17,7 @@
 // message) — falling back to a short note when it never reported.
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
-import { getNode, setPresence, setFocusOccupant, fullName } from '../canvas/index.js';
+import { getNode, setPresence, setFocusOccupant, fullName, recordLaunch, recordPid } from '../canvas/index.js';
 import { reportsDir } from '../canvas/paths.js';
 import { pushFinal } from '../feed/feed.js';
 import { spawnNode, rootOfSpine } from './nodes.js';
@@ -25,6 +25,7 @@ import { buildLaunchSpecAsync, buildPiArgv } from './launch.js';
 import { focusOf, respawnPaneSync, setPaneOption } from './placement.js';
 import { waitForBrokerViewSocket, viewerSplitEnv } from './placement-tmux.js';
 import { headlessBrokerHost } from './host.js';
+import { transition } from './lifecycle.js';
 import { ensureDaemon } from '../../daemon/manage.js';
 /** The agent's most recent surfaced message: the newest reports/*.md body with
  *  its YAML frontmatter stripped. Empty string when the node never reported. */
@@ -74,23 +75,11 @@ export async function recycleNode(nodeId, callerPane) {
         finalized = true;
     }
     catch { /* recycle the pane even if the report failed */ }
-    // The node's pane is a VIEWER (`crtr surface attach`), not its engine: the engine is
-    // the detached broker process, so respawn-pane -k below would only kill the
-    // viewer, never the engine. Tear the broker PROCESS down so it exits and
-    // releases the sole .jsonl writer. Status is already flipped done by pushFinal
-    // above (crash-safe order: the daemon won't revive a done node).
-    try {
-        headlessBrokerHost.teardown(nodeId);
-    }
-    catch { /* best-effort */ }
-    // Capture M's focus viewport (if any) BEFORE nulling — the fresh root inherits
-    // it (the SAME focus row + pane). The demoted node no longer holds a pane: it is
-    // being reclaimed.
+    // Capture M's focus viewport (if any) before booting its replacement. The
+    // old broker remains live until the new broker proves it can accept a viewer;
+    // a failed replacement must not strand this finished conversation without an
+    // engine.
     const f = focusOf(nodeId);
-    try {
-        setPresence(nodeId, { pane: null, window: null, tmux_session: null });
-    }
-    catch { /* best-effort */ }
     // 2 + 3. Recycle — boot a fresh resident BROKER root for the SAME pane: the
     // viewer pane re-attaches to the fresh broker (broker-is-the-host — the viewer
     // pane stays a viewer, never becomes an engine pane).
@@ -113,36 +102,69 @@ export async function recycleNode(nodeId, callerPane) {
         profile_id: meta.profile_id,
         launch,
     });
-    // Hand the viewport to the fresh root: reuse M's focus row over the SAME pane
-    // (respawn-pane -k below keeps the %id), so the user keeps watching this slot.
+    const fresh = getNode(root.node_id);
+    const inv = buildPiArgv(fresh);
+    // CRTR_SUBTREE groups the fresh root's subtree; FRONT_DOOR is set by the broker
+    // host itself, so it is not added here.
+    inv.env = { ...inv.env, CRTR_SUBTREE: rootOfSpine(root.node_id) };
+    if (!(await launchRecycledBroker(fresh, inv))) {
+        return { recycled: false, finalized, newRoot: root.node_id, delivered };
+    }
+    // COMMIT after replacement readiness: the node's pane is a VIEWER, so tear
+    // down the old detached broker only now that the fresh broker can serve it.
+    try {
+        headlessBrokerHost.teardown(nodeId);
+    }
+    catch { /* best-effort */ }
+    try {
+        setPresence(nodeId, { pane: null, window: null, tmux_session: null });
+    }
+    catch { /* best-effort */ }
     if (f !== null) {
         try {
             setFocusOccupant(f.focus_id, root.node_id);
         }
         catch { /* best-effort */ }
     }
-    const fresh = getNode(root.node_id);
-    const inv = buildPiArgv(fresh);
-    // CRTR_SUBTREE groups the fresh root's subtree; FRONT_DOOR is set by the broker
-    // host itself, so it is not added here.
-    inv.env = { ...inv.env, CRTR_SUBTREE: rootOfSpine(root.node_id) };
-    const ok = await recycleBrokerViewer(fresh, pane, inv);
+    const ok = respawnRecycledViewer(fresh, pane);
     return { recycled: ok, finalized, newRoot: root.node_id, delivered };
 }
-/** Recycle a BROKER root into `pane`: the fresh root is broker-hosted, so its
- *  engine runs in a DETACHED broker, not the pane. Birth-launch that broker via
- *  the Host seam (mirrors spawnChild's birth path — the host records its pid),
- *  wait for its view.sock to accept, then respawn the pane in place to the VIEWER
- *  `crtr surface attach to <root>`. The pane stays a viewer (attach self-tags it
- *  `@crtr_node`); it never hosts the engine. Returns false (recycle reports the
- *  pane was not respawned) when the broker never serves — the fresh root row
- *  still exists, broker-hosted, for the daemon to revive. */
-async function recycleBrokerViewer(fresh, pane, inv) {
-    const placed = headlessBrokerHost.launch(fresh.node_id, inv, { cwd: fresh.cwd, name: fullName(fresh), resuming: false });
-    if (placed.pid === null)
-        return false;
-    if (!(await waitForBrokerViewSocket(fresh.node_id, placed.exited)))
-        return false;
+/** Launch a recycled root and prove its viewer socket before recycling the old
+ *  broker. This direct birth path writes the same launch/pid coordinates as
+ *  reviveNode, and a failed readiness probe terminalizes and tears it down. */
+async function launchRecycledBroker(fresh, inv) {
+    let placed;
+    try {
+        placed = headlessBrokerHost.launch(fresh.node_id, inv, { cwd: fresh.cwd, name: fullName(fresh), resuming: false });
+        if (placed.pid === null)
+            throw new Error('broker host returned no pid');
+        recordLaunch(fresh.node_id, new Date().toISOString());
+        recordPid(fresh.node_id, placed.pid);
+        if (await waitForBrokerViewSocket(fresh.node_id, placed.exited))
+            return true;
+    }
+    catch {
+        // The replacement never became usable; the finished root's broker remains
+        // intact and this half-born row cannot remain active without a fleet handle.
+    }
+    try {
+        transitionReplacementToDead(fresh.node_id);
+    }
+    catch { /* best-effort */ }
+    try {
+        headlessBrokerHost.teardown(fresh.node_id);
+    }
+    catch { /* best-effort */ }
+    return false;
+}
+function transitionReplacementToDead(nodeId) {
+    // spawnNode births active rows, so crash is the authoritative failed-launch
+    // outcome whether the host returned no pid or exited before readiness.
+    const replacement = getNode(nodeId);
+    if (replacement?.status === 'active' || replacement?.status === 'idle')
+        transition(nodeId, 'crash');
+}
+function respawnRecycledViewer(fresh, pane) {
     // Clear the finalized node's stale `@crtr_node` tag before respawn so the tag
     // never names a done node during the gap before the new `crtr surface attach` re-tags
     // on connect. Node ids are shell-safe identifiers; no quoting needed.

package/dist/core/runtime/reset.d.ts

@@ -25,7 +25,7 @@ export interface RelaunchDeps {
     }>) => boolean | Promise<boolean>;
     /** Re-exec the viewer pane onto the new node. Default: respawnPaneSync. */
     respawnViewer?: typeof respawnPaneSync;
-    /** Tear the old broker down. Default: headlessBrokerHost.teardown. */
+    /** Tear down a broker after a failed replacement or a committed old-root replacement. */
     teardownBroker?: typeof headlessBrokerHost.teardown;
 }
 export interface RelaunchRootResult {

package/dist/core/runtime/reset.js

@@ -20,7 +20,7 @@
 // reserved for finish).
 //
 // Best-effort throughout: a tmux/fs failure on one node never aborts the reap.
-import { getNode, updateNode, fullName, closeFocusRow, view, } from '../canvas/index.js';
+import { getNode, updateNode, recordLaunch, recordPid, fullName, closeFocusRow, view, } from '../canvas/index.js';
 import { transition } from './lifecycle.js';
 import { headlessBrokerHost, requestBrokerTeardown } from './host.js';
 import { tearDownNode, focusOf, registerViewerFocus, respawnPaneSync, windowOfPane, renameWindow, } from './placement.js';
@@ -129,7 +129,30 @@ export async function relaunchRoot(oldId, deps = {}) {
         transition(newMeta.node_id, 'crash');
         return null;
     }
-    await waitForViewSocket(newMeta.node_id, placed.exited); // best-effort; attach auto-redials on miss
+    // A replacement is a managed broker just like a revive: the fleet owns its
+    // real exit, while the row gets the matching launch and pid coordinates before
+    // readiness can observe an early exit.
+    recordLaunch(newMeta.node_id, new Date().toISOString());
+    recordPid(newMeta.node_id, placed.pid);
+    let ready = false;
+    try {
+        ready = await waitForViewSocket(newMeta.node_id, placed.exited);
+    }
+    catch {
+        // A readiness probe error means the replacement is not proven usable.
+    }
+    if (!ready) {
+        // Do not let a broker that can still bind later sit behind a dead row, and
+        // do not commit any old-root teardown without a usable replacement.
+        const replacement = getNode(newMeta.node_id);
+        if (replacement?.status === 'active' || replacement?.status === 'idle')
+            transition(newMeta.node_id, 'crash');
+        try {
+            teardownBroker(newMeta.node_id);
+        }
+        catch { /* best-effort */ }
+        return null;
+    }
     // --- COMMIT: park + reap the old root, re-point the viewer, kill the old
     //     broker. Past this point the new node is the live root. ---
     reapDescendants(oldId); // old workers → canceled + torn down

package/dist/daemon/__tests__/helpers/source-daemon.js

@@ -57,6 +57,7 @@ export function startSourceDaemon(fixture) {
     };
     for (const key of [
         'CRTR_NODE_ID',
+        'CRTR_SUBTREE',
         'CRTR_KIND',
         'CRTR_MODE',
         'CRTR_LIFECYCLE',

package/dist/daemon/api/handlers/messages.js

@@ -327,7 +327,7 @@ async function handleMessage(ctx) {
     const entry = deliver();
     // Deferred mail normally waits for a natural cycle, but a frozen row already
     // owes a thaw; consume its deadline when that durable future wake arrives.
-    if (tier !== 'deferred' || meta.frozen_at !== null)
+    if (entry.tier !== 'deferred' || meta.frozen_at !== null)
         cancelCronsOnWake(id);
     // A wake-capable tier revives a dormant target so its inbox-watcher delivers
     // this; deferred never wakes — it rides the target's next natural cycle. The

package/dist/daemon/api/handlers/reports.js

@@ -33,7 +33,7 @@ function parsePushBody(body) {
     if (deliveryTier !== undefined && deliveryTier !== 'deferred' && deliveryTier !== 'normal' && deliveryTier !== 'urgent') {
         throw usage(`invalid delivery_tier: ${String(deliveryTier)} (expected deferred|normal|urgent)`);
     }
-    if (tier === 'final' && deliveryTier !== undefined) {
+    if (tier !== 'update' && deliveryTier !== undefined) {
         throw usage('delivery_tier is only valid for update reports');
     }
     if (typeof text !== 'string' || text.trim() === '') {

package/dist/daemon/cron/sinks.js

@@ -31,7 +31,7 @@ function deliverNodeSink(c, target, stdout) {
         label: `⏰ cron ${c.name}`,
         data: { body: stdout },
     });
-    if (c.tier !== 'deferred' || meta.frozen_at !== null)
+    if (entry.tier !== 'deferred' || meta.frozen_at !== null)
         cancelCronsOnWake(target);
     // The APPENDED tier decides the wake, not the cron's requested one: a deferred
     // cron aimed at a terminal node was raised out of `deferred` by the append.

package/dist/daemon/messaging/node-message.js

@@ -59,7 +59,7 @@ export async function deliverNodeMessage(args) {
         label: args.label,
         data: { ...args.data, body: args.body },
     }));
-    if (args.mode !== 'quiet' || target.frozen_at !== null)
+    if (entry.tier !== 'deferred' || target.frozen_at !== null)
         cancelCronsOnWake(args.node_id);
     // The APPENDED entry's tier decides the wake: a quiet send to a terminal
     // target was raised out of `deferred` by the append, and must be delivered.

package/dist/pi-extensions/canvas-inbox-watcher.js

@@ -23,7 +23,7 @@ import { errorClassFromError } from '../core/events/errors.js';
 import { operationIdContext } from '../core/events/operation-id.js';
 import { situationalContextEnvelope, SITUATIONAL_CONTEXT_CUSTOM_TYPE } from '../core/runtime/situational-context.js';
 import { isProfilePaused } from '../core/profiles/manifest.js';
-import { HELD_DEFERRED_INBOX_PROMPT_JOIN, } from '../core/runtime/broker/held-deferred-inbox.js';
+import { brokerIdleTurnStart, HELD_DEFERRED_INBOX_PROMPT_JOIN, } from '../core/runtime/broker/held-deferred-inbox.js';
 const MAX_PENDING_HANDOFFS = 64;
 const MAX_SOURCE_OPERATION_IDS = 16;
 let currentWatcher;
@@ -738,7 +738,10 @@ class CanvasInboxWatcher {
                 this.pi.sendMessage({ customType: SITUATIONAL_CONTEXT_CUSTOM_TYPE, content: card, display: true }, route === 'idle' ? {} : { deliverAs: route });
             }
             if (route === 'idle') {
-                this.pi.sendUserMessage(content);
+                const start = brokerIdleTurnStart();
+                if (start === undefined)
+                    throw new Error('broker idle-turn admission is unavailable');
+                start(content);
             }
             else {
                 this.pi.sendUserMessage(content, { deliverAs: route });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.251",
+  "version": "0.3.252",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.251",
+  "version": "0.3.252",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.251",
+      "version": "0.3.252",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {