@north-light/crouter 0.3.251 → 0.3.253

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

@@ -1,4 +1,5 @@
 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;
@@ -7,3 +8,6 @@ export type HeldDeferredInboxPromptJoin = (session: {
     }) => 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

@@ -1,8 +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. This process-global
-// symbol names the watcher-owned join function across that loader boundary.
+// 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/core/runtime/revive.js

@@ -230,10 +230,15 @@ function launchRevive(nodeId, meta, opts) {
     // fail deep inside the crash/doctrine-wake catch below, where it would
     // surface as an opaque `internal error` (toErrorBody masks every 5xx).
     if (!existsSync(meta.cwd)) {
+        const next = meta.fork_from != null
+            ? `Restore ${meta.cwd}, then revive the fork normally with \`crtr node lifecycle revive ${nodeId}\`.`
+            : meta.managed_worktree?.state === 'open'
+                ? 'Restore or reconcile the recorded checkout, then use the managed-worktree close or abandon recovery.'
+                : `Recreate ${meta.cwd}, or repair it with \`crtr node config --cwd <path> --node ${nodeId}\`; durable node work resumes in a fresh conversation. Then retry \`crtr node lifecycle revive ${nodeId}\`.`;
         throw new InputError({
             error: 'cwd_missing',
             message: `${nodeId} cannot be revived — its recorded cwd no longer exists: ${meta.cwd}`,
-            next: `Recreate ${meta.cwd}, or update the node's cwd, then retry \`crtr node lifecycle revive ${nodeId}\`.`,
+            next,
         });
     }
     // Lazy host_kind coerce (§C): every launch now uses the broker host. Persist

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/nodes.js

@@ -7,8 +7,8 @@
 //
 // `{id}` is the target node.
 import { envProfileId } from '../../../shared/env.js';
-import { readdirSync } from 'node:fs';
-import { basename } from 'node:path';
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { basename, isAbsolute, resolve } from 'node:path';
 import { appendSituationalContext, formatSituationalProse } from '../../../core/runtime/situational-context.js';
 import { closeNode } from '../../../core/runtime/close.js';
 import { reviveNode } from '../../../core/runtime/revive.js';
@@ -35,6 +35,7 @@ import { BrokerUnreachableError } from '../../../core/runtime/broker-request.js'
 import { readFault } from '../../../core/runtime/fault.js';
 import { activeFaultForDisplay } from '../../../core/canvas/render-source.js';
 import { isBrokerLive, persistDormantModel, setModelLive } from '../../../core/runtime/model-swap.js';
+import { boundFleet } from '../../../core/runtime/fleet.js';
 import { writeOutputSchema } from '../../../core/runtime/structured-output.js';
 import { claimWarmNode, refillWarmPool, warmPoolEnabled } from '../../../core/runtime/warm-pool.js';
 import { resolveLaunchTarget } from '../../../core/runtime/launch-target.js';
@@ -45,6 +46,7 @@ import { cronWakeOrigin } from '../../../core/runtime/bearings.js';
 import { notFound, usage } from '../../../core/errors.js';
 import { toCloseResultDTO, toNodeDetailDTO, toNodeSummaryDTO, toReviveResultDTO } from '../map.js';
 import { ApiError } from '../../../api/index.js';
+import { InputError } from '../../../core/io.js';
 // Shared helpers
 function requireMeta(id) {
     const meta = getNode(id);
@@ -622,11 +624,129 @@ function handleReviveAll() {
     };
     return { status: 200, body };
 }
-// PATCH /v1/nodes/{id}/config — model / situational-context (spec §6.2)
+// PATCH /v1/nodes/{id}/config — durable config and repair-only cwd (spec §6.2)
 export async function handleConfig(ctx, deps = {}) {
     const id = ctx.params['id'];
+    const body = ctx.body;
+    let patch;
+    if (body === undefined) {
+        patch = {};
+    }
+    else if (typeof body === 'object' && body !== null && !Array.isArray(body)) {
+        patch = body;
+    }
+    else {
+        throw new InputError({
+            error: 'cwd_invalid',
+            message: 'cwd repair requires a non-null object with a non-empty cwd string',
+            received: body,
+            field: 'cwd',
+            next: 'Send a config patch with a non-empty absolute cwd string.',
+        });
+    }
+    if (Object.prototype.hasOwnProperty.call(patch, 'cwd')) {
+        const cwd = patch.cwd;
+        if (typeof cwd !== 'string' || cwd === '') {
+            throw new InputError({
+                error: 'cwd_invalid',
+                message: 'cwd must be a non-empty string',
+                received: cwd,
+                field: 'cwd',
+                next: 'Send a non-empty absolute cwd string.',
+            });
+        }
+        if (Object.keys(patch).some((key) => key !== 'cwd' && patch[key] !== undefined)) {
+            throw new InputError({
+                error: 'cwd_not_exclusive',
+                message: 'cwd repair cannot be combined with another config field',
+                received: patch,
+                field: 'cwd',
+                next: 'Send cwd as the only config field.',
+            });
+        }
+        const meta = requireMeta(id);
+        if (boundFleet().has(id)) {
+            const message = `${id} cannot repair its cwd while its broker is live`;
+            throw new ApiError(409, 'cwd_node_live', message, {
+                error: 'cwd_node_live',
+                message,
+                received: cwd,
+                field: 'cwd',
+                next: 'Let the node become dormant, then retry the cwd repair.',
+            });
+        }
+        if (meta.fork_from != null) {
+            throw new InputError({
+                error: 'cwd_node_forked',
+                message: `${id} is a fork and cannot repair its cwd; recorded cwd: ${meta.cwd}`,
+                received: cwd,
+                field: 'cwd',
+                next: `Restore ${meta.cwd}, then revive the fork normally.`,
+            });
+        }
+        if (meta.managed_worktree?.state === 'open') {
+            throw new InputError({
+                error: 'cwd_node_managed_worktree_open',
+                message: `${id} owns an open managed worktree and cannot repair its cwd`,
+                received: cwd,
+                field: 'cwd',
+                next: 'Restore or reconcile the recorded checkout, then use the managed-worktree close or abandon flow.',
+            });
+        }
+        if (existsSync(meta.cwd)) {
+            throw new InputError({
+                error: 'cwd_still_present',
+                message: `${id} recorded cwd still exists: ${meta.cwd}; cwd repair is not a relocation command`,
+                received: cwd,
+                field: 'cwd',
+                next: 'This command only repairs a node whose recorded cwd is gone.',
+            });
+        }
+        if (!isAbsolute(cwd)) {
+            throw new InputError({
+                error: 'cwd_not_absolute',
+                message: `cwd must be an absolute path: ${cwd}`,
+                received: cwd,
+                field: 'cwd',
+                next: 'Send an absolute path.',
+            });
+        }
+        const resolved = resolve(cwd);
+        if (!existsSync(resolved)) {
+            throw new InputError({
+                error: 'cwd_missing',
+                message: `cwd does not exist: ${resolved}`,
+                received: cwd,
+                field: 'cwd',
+                next: 'Create the replacement directory or send an existing absolute directory.',
+            });
+        }
+        try {
+            if (!statSync(resolved).isDirectory()) {
+                throw new InputError({
+                    error: 'cwd_not_a_directory',
+                    message: `cwd is not a directory: ${resolved}`,
+                    received: cwd,
+                    field: 'cwd',
+                    next: 'Send an existing absolute directory.',
+                });
+            }
+        }
+        catch (error) {
+            if (error instanceof InputError)
+                throw error;
+            throw new InputError({
+                error: 'cwd_missing',
+                message: `cwd does not exist: ${resolved}`,
+                received: cwd,
+                field: 'cwd',
+                next: 'Create the replacement directory or send an existing absolute directory.',
+            });
+        }
+        updateNode(id, { cwd: resolved, pi_session_id: null, pi_session_file: null });
+        return { status: 200, body: detailOf(id) };
+    }
     let meta = requireMeta(id);
-    const patch = ctx.body ?? {};
     if (patch.situational_context !== undefined) {
         appendSituationalContext(id, formatSituationalProse(patch.situational_context));
     }

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/api/map.d.ts

@@ -112,7 +112,7 @@ export declare function errorToStatus(thrown: unknown): {
 };
 /** Build the uniform JSON error body (spec §8) for a thrown value, using
  *  `errorToStatus` for the status/code. Structured `details` are surfaced for a
- *  CrtrError (they let the client reconstruct the error verbatim). A 500 still
+ *  CrtrError or ApiError (they let the client reconstruct the error verbatim). A 500 still
  *  omits `details` for hygiene, but NO LONGER strips the message to a bare
  *  `internal error`: it surfaces the bounded cause (`boundedCause`) so a caller
  *  is never left with a causeless internal, while the router logs the full

package/dist/daemon/api/map.js

@@ -17,6 +17,7 @@ import { NodeIdConflictError } from '../../core/runtime/nodes.js';
 import { readContextTokens } from '../../core/canvas/telemetry.js';
 import { CrtrError } from '../../core/errors.js';
 import { WorktreeError } from '../../core/worktree.js';
+import { ApiError } from '../../api/errors.js';
 import { ExitCode } from '../../types.js';
 import { sinkDisplay } from '../cron-sink.js';
 import { responsePath } from '../../core/human/convention.js';
@@ -563,7 +564,7 @@ function boundedCause(err) {
 }
 /** Build the uniform JSON error body (spec §8) for a thrown value, using
  *  `errorToStatus` for the status/code. Structured `details` are surfaced for a
- *  CrtrError (they let the client reconstruct the error verbatim). A 500 still
+ *  CrtrError or ApiError (they let the client reconstruct the error verbatim). A 500 still
  *  omits `details` for hygiene, but NO LONGER strips the message to a bare
  *  `internal error`: it surfaces the bounded cause (`boundedCause`) so a caller
  *  is never left with a causeless internal, while the router logs the full
@@ -577,7 +578,7 @@ export function toErrorBody(thrown) {
     const message = err instanceof Error ? err.message : String(err);
     const details = err instanceof ReviewOperationErrorClass
         ? reviewErrorDetails(err)
-        : err instanceof CrtrError && err.details !== undefined
+        : (err instanceof CrtrError || err instanceof ApiError) && err.details !== undefined
             ? err.details
             : undefined;
     const body = { error: { code, message } };

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.