@north-light/crouter 0.3.250 → 0.3.252

package/dist/core/canvas/migrations.js

@@ -26,14 +26,19 @@ import { basename, join, resolve } from 'node:path';
 import { crtrHome, isSafeNodeId, nodesRoot, nodeMetaPath } from './paths.js';
 import { STATE_MIGRATIONS } from '../../migrations/registry.js';
 import { customExtensionPaths } from './extensions.js';
-import { updateJsonFileDurably } from './meta-file.js';
+import { readMetaObject, updateJsonFileDurably, withMetaLock, writeMetaObjectLocked } from './meta-file.js';
 // Schema as a forward-only migration list
 //
 // The schema is the migration list: one place a schema change is expressed,
 // one gate (`PRAGMA user_version`) that applies it. `migrate()` runs every
 // pending step in order and bumps `user_version` after each, so a fresh db and
 // the live fleet (all at `user_version 0`) converge on the same final shape.
-// Migrations are append-only and forward-only — never edit a shipped step.
+// Migrations are append-only and forward-only — never edit a shipped step. The
+// v36 body below is the sole corrective exception: v0.3.250 shipped a destructive
+// stale-row decision, so v36 is narrowed for databases still below its gate while
+// appended v37 repairs databases that already crossed it. Do not repeat this
+// exception; an appended migration is required unless it would run too late to
+// prevent destruction at an existing version boundary.
 /** v1 — the baseline tables + indexes. `IF NOT EXISTS` makes this a no-op on
  *  any existing db (the live fleet already has these tables). */
 function baselineSchema(db) {
@@ -1215,32 +1220,43 @@ 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) {
+/** Reproject the derived session-file index from authoritative node metadata.
+ * v36 may resolve duplicate authoritative claimants because it runs before the
+ * first UNIQUE index exists. v37 must retain every surviving meta claim: a
+ * conflict at that later boundary is irreconcilable and fails instead. */
+function reconcileNodeSessionFileOwners(db, clearDuplicateMetaClaimants) {
     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)
+    db.exec('DROP INDEX IF EXISTS idx_nodes_pi_session_file;');
+    const rows = db.prepare('SELECT node_id FROM nodes ORDER BY created ASC, node_id ASC').all();
+    for (const { node_id } of rows) {
+        const metaPath = nodeMetaPath(node_id);
+        // Missing or unreadable metadata has no authoritative coordinate. Avoid
+        // taking a file lock there: old rows can outlive a removed node directory.
+        if (readMetaObject(metaPath) === null) {
+            setFile.run(null, node_id);
             continue;
-        // Identity is authoritative, so normalize both stores before grouping.
-        updateJsonFileDurably(nodeMetaPath(row.node_id), (meta) => {
-            meta['pi_session_file'] = sessionFile;
-            return true;
+        }
+        const sessionFile = withMetaLock(metaPath, () => {
+            const meta = readMetaObject(metaPath);
+            if (meta === null)
+                throw new Error(`node ${node_id} session metadata changed during ownership migration`);
+            if (typeof meta['pi_session_file'] !== 'string')
+                return null;
+            const storedSessionFile = meta['pi_session_file'];
+            const normalizedSessionFile = canonical(storedSessionFile);
+            if (normalizedSessionFile !== storedSessionFile) {
+                meta['pi_session_file'] = normalizedSessionFile;
+                writeMetaObjectLocked(metaPath, meta);
+            }
+            return normalizedSessionFile;
         });
-        setFile.run(sessionFile, row.node_id);
+        // meta.json is authoritative: a crash after its write can leave this row
+        // claiming another node's old session coordinate.
+        setFile.run(sessionFile, node_id);
     }
     const duplicates = db.prepare(`
 SELECT pi_session_file
@@ -1249,6 +1265,10 @@ WHERE pi_session_file IS NOT NULL
 GROUP BY pi_session_file
 HAVING COUNT(*) > 1
 `).all();
+    if (!clearDuplicateMetaClaimants && duplicates.length > 0) {
+        const coordinates = duplicates.map(({ pi_session_file }) => pi_session_file).join(', ');
+        throw new Error(`cannot restore unique Pi session ownership: authoritative metadata has concurrent claimants for ${coordinates}`);
+    }
     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(`
@@ -1259,18 +1279,36 @@ 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) => {
+            // duplicate projection. The checked write fails rather than erasing a
+            // concurrent metadata change.
+            const cleared = updateJsonFileDurably(nodeMetaPath(node_id), (meta) => {
+                const currentSessionFile = meta['pi_session_file'];
+                if (typeof currentSessionFile !== 'string' || canonical(currentSessionFile) !== pi_session_file) {
+                    throw new Error(`node ${node_id} session metadata changed during ownership migration`);
+                }
                 meta['pi_session_id'] = null;
                 meta['pi_session_file'] = null;
                 return true;
             });
+            if (!cleared)
+                throw new Error(`node ${node_id} session metadata changed during ownership migration`);
             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);');
 }
+/** v36 — one Pi transcript may have exactly one node owner. This is the narrow
+ * corrective body for clients below v36; it reprojects metadata before choosing
+ * the earliest created duplicate claimant (node_id breaks equal timestamps). */
+function makeNodeSessionFileUnique(db) {
+    reconcileNodeSessionFileOwners(db, true);
+}
+/** v37 — repair v0.3.250's already-applied v36 projection without inventing
+ * coordinates v36 already cleared. Surviving authoritative metadata wins over
+ * stale rows; concurrent surviving claims fail loudly rather than clearing one. */
+function repairNodeSessionFileUniqueIndex(db) {
+    reconcileNodeSessionFileOwners(db, false);
+}
 /** v35 — durable node lifecycle execution state and terminal cause. */
 function addNodeLifecycleColumns(db) {
     const columns = nodeColumns(db);
@@ -1340,6 +1378,7 @@ export const MIGRATIONS = [
     /* v34 */ addNodeSessionFileIndex,
     /* v35 */ addNodeLifecycleColumns,
     /* v36 */ makeNodeSessionFileUnique,
+    /* v37 */ repairNodeSessionFileUniqueIndex,
     ...JOURNALED_STATE_MIGRATIONS,
 ];
 /** Migration indexes that manage their OWN transaction and therefore must not

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

@@ -1,6 +1,7 @@
 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, turnAdmission, } = deps;
@@ -44,14 +45,30 @@ export function createEngineDriver(deps) {
             // 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) {
+                    try {
+                        await heldDeferredInboxPromptJoin()?.(session());
+                    }
+                    catch {
+                        // The watcher emitted the failed durable delivery and retains it for
+                        // replay. A person's live prompt is not replayable, so it must run.
+                    }
+                }
+                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, preflightResult: release })).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();
@@ -67,9 +84,9 @@ 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, preflightResult: release })))).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, preflightResult: release }))
+                return settle(dispatches.track(operationIdContext.fresh(() => promptWithAdvertisedCommandInvocation(session(), frame.text, prompt)
                     .catch(relayError)
                     .then(() => sendGuidance(guidance, deliverAs)))));
             }

package/dist/core/runtime/broker/fault-retry.js

@@ -58,19 +58,26 @@ export class FaultRetry {
         generation.stagedRefreshAbort = false;
         generation.stagedOverflowFailure = null;
         const settledSession = generation.session;
-        // A failed daemon retry settles here with the episode's fault marker still
-        // present (a successful provider round-trip would have cleared it). Carry
-        // the episode forward — original anchor, start time, and attempt count — so
-        // each retry rewinds to the same fork point instead of stacking recovery
-        // prompts, and so backoff/exhaustion actually accumulate.
+        // turn_end clears the ordinary marker before this settlement. A failed
+        // admitted retry therefore carries from its durable episode, while an
+        // initial provider failure still reads from the ordinary marker.
         const prior = readFault(this.deps.nodeId);
-        const episode = this.isActiveAutoFault(prior) && prior.link === 'pi→provider'
-            ? { since: prior.since, anchorEntryId: prior.anchorEntryId, attempt: prior.retry.attempt }
-            : null;
+        const durableEpisode = readProviderRetryEpisode(this.deps.nodeId);
+        const episodeFault = this.isActiveAutoFault(prior) && prior.link === 'pi→provider'
+            ? prior
+            : durableEpisode?.state === 'admitted' &&
+                durableEpisode.sessionFile === this.sessionFile(settledSession) &&
+                this.isActiveAutoFault(durableEpisode.fault)
+                ? durableEpisode.fault
+                : null;
+        const episode = episodeFault === null
+            ? null
+            : { since: episodeFault.since, anchorEntryId: episodeFault.anchorEntryId, attempt: episodeFault.retry.attempt };
         const messages = Array.isArray(agentEnd?.messages) ? agentEnd.messages : [];
         const last = [...messages].reverse().find((message) => typeof message === 'object' && message !== null && message.role === 'assistant');
         if (overflowFailure !== null) {
             clearFault(this.deps.nodeId, { link: 'pi→provider' });
+            clearProviderRetryEpisode(this.deps.nodeId);
             recordFault(this.deps.nodeId, {
                 link: 'pi→provider', op: 'context overflow recovery', kind: 'context-overflow', retry: { disposition: 'fatal' },
                 message: overflowFailure.errorMessage, anchorEntryId: settledSession.sessionManager.getLeafId?.() ?? undefined,
@@ -87,21 +94,30 @@ export class FaultRetry {
             });
             return;
         }
-        if (last?.stopReason !== 'error')
+        if (last?.stopReason !== 'error') {
+            if (last !== undefined)
+                clearProviderRetryEpisode(this.deps.nodeId);
             return;
-        if (refreshAbort)
+        }
+        if (refreshAbort) {
+            clearProviderRetryEpisode(this.deps.nodeId);
             return;
+        }
         const raw = typeof last.errorMessage === 'string' ? last.errorMessage : 'engine error (no errorMessage recorded)';
         // An abort landing between requests reaches pi's catch as a bare AbortError
         // and settles as an error rather than `aborted`. Something asked that turn
         // to stop, so there is no provider fault to record.
-        if (endedByAbort({ stopReason: 'error', errorMessage: raw }))
+        if (endedByAbort({ stopReason: 'error', errorMessage: raw })) {
+            clearProviderRetryEpisode(this.deps.nodeId);
             return;
+        }
         const uncompactedOverflow = isContextOverflow(last, settledSession.model?.contextWindow);
         const classified = classify('pi→provider', last);
         const coolingDeadline = extractCoolingDeadline(last);
-        if (uncompactedOverflow)
+        if (uncompactedOverflow) {
             clearFault(this.deps.nodeId, { link: 'pi→provider' });
+            clearProviderRetryEpisode(this.deps.nodeId);
+        }
         const faultInput = {
             link: 'pi→provider', op: 'generation turn', kind: uncompactedOverflow ? 'context-overflow' : classified.kind,
             retry: uncompactedOverflow
@@ -121,8 +137,10 @@ export class FaultRetry {
         };
         if (faultInput.retry.disposition === 'auto')
             this.recordPendingProviderFault(settledSession, faultInput);
-        else
+        else {
+            clearProviderRetryEpisode(this.deps.nodeId);
             recordFault(this.deps.nodeId, faultInput);
+        }
     }
     /** Startup re-drive reads only a durable pending episode. Revive deliberately
      * clears the ordinary fault marker before this boundary, so the episode is

package/dist/core/runtime/broker/held-deferred-inbox.d.ts

@@ -0,0 +1,13 @@
+export declare const HELD_DEFERRED_INBOX_PROMPT_JOIN: unique symbol;
+export declare const BROKER_IDLE_TURN_START: unique symbol;
+export type HeldDeferredInboxPromptJoin = (session: {
+    sendCustomMessage: (message: {
+        customType: string;
+        content: string;
+        display: boolean;
+    }) => Promise<void>;
+}) => Promise<void>;
+export declare function heldDeferredInboxPromptJoin(): HeldDeferredInboxPromptJoin | undefined;
+/** Starts an inbox-delivered idle turn through the broker's admission gate. */
+export type BrokerIdleTurnStart = (text: string) => void;
+export declare function brokerIdleTurnStart(): BrokerIdleTurnStart | undefined;

package/dist/core/runtime/broker/held-deferred-inbox.js

@@ -0,0 +1,13 @@
+// The inbox watcher is a Pi extension loaded through Jiti, while the broker is
+// native ESM. They therefore cannot share a module singleton. Process-global
+// symbols carry their narrow bridge functions across that loader boundary.
+export const HELD_DEFERRED_INBOX_PROMPT_JOIN = Symbol.for('@crouton-kit/crtr:held-deferred-inbox-prompt-join');
+export const BROKER_IDLE_TURN_START = Symbol.for('@crouton-kit/crtr:broker-idle-turn-start');
+export function heldDeferredInboxPromptJoin() {
+    const join = globalThis[HELD_DEFERRED_INBOX_PROMPT_JOIN];
+    return typeof join === 'function' ? join : undefined;
+}
+export function brokerIdleTurnStart() {
+    const start = globalThis[BROKER_IDLE_TURN_START];
+    return typeof start === 'function' ? start : undefined;
+}

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.