@north-light/crouter 0.3.180 → 0.3.182

package/dist/core/runtime/broker/message-ledger.js

@@ -0,0 +1,143 @@
+// message-ledger.ts — broker-owned message identity across pi's id-less queues.
+//
+// pi's steering/follow-up queues and user messages carry TEXT only: `steer()`
+// pushes bare strings, `queue_update` relays bare string arrays, and retirement
+// (on user `message_start`) is a first-index-of-text splice. Every downstream
+// consumer was therefore forced into order/text heuristics to match its own
+// optimistic send to the wake that echoed it — wrong under duplicates,
+// cross-surface sends, and reconnect replay.
+//
+// The broker is the ONLY writer to the engine (every prompt/steer/follow_up/
+// deliver funnels through driveEngine) and observes pi's event stream
+// synchronously in-process, so it can own identity at the wire boundary: mint
+// (or adopt the sender's) id per accepted frame, mirror pi's queue state by
+// reconciling pi's own `queue_update` events, and attach the retired entry's id
+// to the relayed user `message_start`. Same deterministic algorithm over the
+// same data in the same process as pi's own bookkeeping — it cannot drift.
+//
+// pi ordering facts this relies on (verified at pi 0.83.0, agent-session.js):
+//  - `_queueSteer`/`_queueFollowUp` push the text and emit `queue_update`
+//    synchronously inside the steer/followUp call.
+//  - On a queued message's user `message_start`, `_handleAgentEvent` splices
+//    the queue and emits `queue_update` BEFORE emitting the `message_start`,
+//    so a retirement's queue_update always precedes its message and two
+//    removals never interleave.
+//  - An idle `prompt()` never touches a queue — its user message matches a
+//    pending dispatch intent by text instead.
+import { randomUUID } from 'node:crypto';
+/** Dispatch intents not yet observed anywhere: bounded FIFO so an intent whose
+ *  text pi transformed (and so never matches) cannot accumulate forever. */
+const MAX_PENDING_INTENTS = 32;
+/** Recent id-bearing user-message dispatches carried in `welcome` so a
+ *  reattaching follower can key its snapshot's trailing user wakes. */
+const MAX_RECENT = 8;
+export class MessageIdLedger {
+    steering = [];
+    followUp = [];
+    pendingIntents = [];
+    stagedRetirementId = null;
+    recent = [];
+    /** Record an accepted client frame's identity before its engine call runs.
+     *  `id` is the sender's `message_id` when it minted one, else broker-minted. */
+    noteDispatch(id, text) {
+        this.pendingIntents.push({ id, text });
+        if (this.pendingIntents.length > MAX_PENDING_INTENTS)
+            this.pendingIntents.shift();
+    }
+    /** Remove a noted intent whose engine call rejected — the message will never
+     *  appear in a queue or as a user message. No-op if already adopted. */
+    dropIntent(id) {
+        const idx = this.pendingIntents.findIndex((e) => e.id === id);
+        if (idx !== -1)
+            this.pendingIntents.splice(idx, 1);
+    }
+    /**
+     * Fold one pi `queue_update` into the ledger and return the id arrays
+     * parallel to its text arrays (total: every position gets an id).
+     *
+     * Per-queue positional diff against the mirrored entries: a text matching an
+     * old entry at-or-after the cursor keeps its id (everything skipped is
+     * removed); an unmatched text ADOPTS the first pending intent with equal
+     * text, else mints a fresh id. Exactly ONE removal across both queues is
+     * pi's per-message retirement (its queue_update precedes the user
+     * `message_start` it belongs to) and is staged for `takeUserMessageId`;
+     * 0 or >1 removals (an enqueue, clearQueue/dequeue, abort) stage nothing.
+     */
+    reconcileQueueUpdate(steering, followUp) {
+        const removed = [];
+        const next = (old, texts) => {
+            const out = [];
+            let cursor = 0;
+            for (const text of texts) {
+                let match = -1;
+                for (let j = cursor; j < old.length; j++) {
+                    if (old[j].text === text) {
+                        match = j;
+                        break;
+                    }
+                }
+                if (match !== -1) {
+                    for (let j = cursor; j < match; j++)
+                        removed.push(old[j].id);
+                    out.push(old[match]);
+                    cursor = match + 1;
+                    continue;
+                }
+                const intentIdx = this.pendingIntents.findIndex((e) => e.text === text);
+                const id = intentIdx !== -1 ? this.pendingIntents.splice(intentIdx, 1)[0].id : randomUUID();
+                out.push({ id, text });
+            }
+            for (let j = cursor; j < old.length; j++)
+                removed.push(old[j].id);
+            return out;
+        };
+        this.steering = next(this.steering, steering);
+        this.followUp = next(this.followUp, followUp);
+        this.stagedRetirementId = removed.length === 1 ? removed[0] : null;
+        return {
+            steeringIds: this.steering.map((e) => e.id),
+            followUpIds: this.followUp.map((e) => e.id),
+        };
+    }
+    /**
+     * The id for a relayed user `message_start`, or undefined when this message
+     * carries none (an engine-command expansion, a text pi transformed, or a
+     * pre-ledger replay). A staged retirement wins — pi emitted its queue_update
+     * synchronously right before this message; otherwise the first pending
+     * intent with equal text (the idle-prompt case, which never touches a
+     * queue). Id-bearing results are remembered for `recentUserMessages`.
+     */
+    takeUserMessageId(messageText) {
+        const staged = this.stagedRetirementId;
+        if (staged !== null) {
+            this.stagedRetirementId = null;
+            this.remember(staged, messageText);
+            return staged;
+        }
+        const idx = this.pendingIntents.findIndex((e) => e.text === messageText);
+        if (idx === -1)
+            return undefined;
+        const intent = this.pendingIntents.splice(idx, 1)[0];
+        this.remember(intent.id, messageText);
+        return intent.id;
+    }
+    /** The last {@link MAX_RECENT} id-bearing user-message dispatches, oldest
+     *  first — the `welcome.recentUserMessages` payload. */
+    recentUserMessages() {
+        return this.recent.map((e) => ({ ...e }));
+    }
+    /** Session rebind/replacement: the mirrored queues, staged retirement, and
+     *  recent list all described the OLD session — drop everything. */
+    reset() {
+        this.steering = [];
+        this.followUp = [];
+        this.pendingIntents = [];
+        this.stagedRetirementId = null;
+        this.recent = [];
+    }
+    remember(id, text) {
+        this.recent.push({ id, text });
+        if (this.recent.length > MAX_RECENT)
+            this.recent.shift();
+    }
+}

package/dist/core/runtime/broker/rebind.js

@@ -58,6 +58,20 @@ export class RebindDriver {
             this.removeInstalledSubscription();
             this.sessionValue = candidateSession;
             this.servicesValue = candidateServices;
+            // Queue modes 'all': at each drain point pi injects EVERY queued steering/
+            // follow-up message in one drain, instead of the default one-at-a-time
+            // (which held a second queued message back a whole assistant response).
+            // Set directly on the public `session.agent` fields — exactly what pi's
+            // own syncQueueModesFromSettings() does minus the shared settings.json
+            // write. Applied here so boot AND every rebind/replacement get it; pi
+            // resets the modes from settings only inside reload(), which re-applies
+            // them at its call site (frame-dispatch). Structurally guarded: the
+            // fake-engine fixture has no `.agent`.
+            const agent = candidateSession.agent;
+            if (agent) {
+                agent.steeringMode = 'all';
+                agent.followUpMode = 'all';
+            }
             if (this.deps.cfg.editorName !== undefined && this.deps.cfg.editorName !== '') {
                 try {
                     candidateSession.setSessionName(this.deps.cfg.editorName);

package/dist/core/runtime/broker-protocol.d.ts

@@ -78,16 +78,27 @@ export interface PromptFrame {
     images?: ImageContent[];
     /** Abort the active turn before starting this prompt. Used by the attach viewer's whip action so its command replaces, rather than joins, in-flight work. */
     interrupt?: true;
+    /** Sender-minted message identity (see MessageIdLedger). The broker mirrors
+     *  it through pi's id-less queues and echoes it back on the relayed user
+     *  `message_start` (`crtrMessageId`) and enriched `queue_update`
+     *  (`steeringIds`/`followUpIds`), so an optimistic sender retires its
+     *  pending entry by exact id instead of text/order guessing. Absent (a
+     *  legacy client, kickoff, inbox): the broker mints one itself. */
+    message_id?: string;
 }
 export interface SteerFrame {
     type: 'steer';
     text: string;
     images?: ImageContent[];
+    /** Sender-minted message identity — see {@link PromptFrame.message_id}. */
+    message_id?: string;
 }
 export interface FollowUpFrame {
     type: 'follow_up';
     text: string;
     images?: ImageContent[];
+    /** Sender-minted message identity — see {@link PromptFrame.message_id}. */
+    message_id?: string;
 }
 export interface AbortFrame {
     type: 'abort';
@@ -111,6 +122,9 @@ export interface DeliverFrame {
     id: string;
     text: string;
     images?: ImageContent[];
+    /** Sender-minted message identity — see {@link PromptFrame.message_id}.
+     *  Distinct from `id`, the one-shot ack-correlation token. */
+    message_id?: string;
 }
 /** Run a `!` bash command — writable clients only. Maps to `session.executeBash()`,
  *  which runs the command, records a `bashExecution` message in context, and
@@ -351,7 +365,38 @@ export interface WelcomeFrame {
      *  can construct an AuthStorage/ModelRegistry pointing at the SAME auth.json.
      *  crtr surface attach is tmux-local only: broker + viewer share a filesystem. */
     agentDir?: string;
-}
+    /** The last few id-bearing user-message dispatches from the broker's message
+     *  ledger, oldest first — so a reattaching follower (Core's snapshot wake
+     *  replay) can key the snapshot's trailing user wakes by id instead of
+     *  discarding them heuristically. Live-process memory only: a broker restart
+     *  loses it (accepted — optimistic pending sends don't survive that either).
+     *  Absent on a broker pinned to an older runtime generation. */
+    recentUserMessages?: Array<{
+        id: string;
+        text: string;
+    }>;
+}
+/** A relayed pi `queue_update`, enriched by the broker with id arrays PARALLEL
+ *  to pi's text arrays (`steeringIds[i]` identifies `steering[i]`). The ids are
+ *  the broker's message ledger mirror of pi's queues — sender-minted when the
+ *  frame carried `message_id`, broker-minted otherwise. Absent on a broker
+ *  pinned to an older runtime generation; consumers fall back to bare texts. */
+export type RelayedQueueUpdate = Extract<AgentSessionEvent, {
+    type: 'queue_update';
+}> & {
+    steeringIds?: string[];
+    followUpIds?: string[];
+};
+/** A relayed user `message_start`, enriched by the broker with the message's
+ *  crouter identity — the id staged by the retirement `queue_update` pi emits
+ *  synchronously before it, or the matching dispatch intent for an idle
+ *  prompt. Absent when the message carries none (an engine-command expansion,
+ *  a pre-ledger replay, an older broker). */
+export type RelayedUserMessageStart = Extract<AgentSessionEvent, {
+    type: 'message_start';
+}> & {
+    crtrMessageId?: string;
+};
 /** Broadcast to EVERY client after a successful `set_model`/`cycle_model`. pi
  *  emits no AgentSessionEvent for a model switch, so without this the new model
  *  reaches no viewer at all (the requester gets only a bare ack) and footers

package/dist/core/runtime/broker.js

@@ -44,6 +44,7 @@ import { BrokerClientRegistry } from './broker/client-registry.js';
 import { ToolGroupTracker } from './broker/tool-groups.js';
 import { FaultRetry } from './broker/fault-retry.js';
 import { EventProjection } from './broker/event-projection.js';
+import { MessageIdLedger } from './broker/message-ledger.js';
 import { createFrameDispatchContext, handleFrame } from './broker/frame-dispatch.js';
 import { RebindDriver } from './broker/rebind.js';
 import { brokerExtensionState, commitBrokerModel } from './broker/daemon-ops.js';
@@ -284,6 +285,9 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
     let projection;
     let notifyTurnAccepted = () => { };
     let resetFrameState = () => { };
+    // Broker-owned message identity (see MessageIdLedger): mirrors pi's id-less
+    // queues so relayed queue_update/user message_start frames carry ids.
+    const messageLedger = new MessageIdLedger();
     rebind = new RebindDriver({
         nodeId, cfg, session, services, runtime, registry, toolGroups,
         uiContext: () => uiContext,
@@ -291,7 +295,10 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
         projection: () => projection,
         setActiveSession: (candidate) => { activeSession = candidate; },
         disposeAndExit: (reason, status) => disposeAndExit(reason, status),
-        onSessionRebind: () => resetFrameState(),
+        onSessionRebind: () => {
+            resetFrameState();
+            messageLedger.reset();
+        },
         reWelcomeAll: () => reWelcomeAll(),
     });
     // Pi's model controls mutate only the live engine. Commit the concrete model
@@ -332,6 +339,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
     projection = new EventProjection({
         registry,
         faultRetry,
+        ledger: messageLedger,
         installedGeneration: () => rebind.installedGeneration(),
         currentSession: () => rebind.session(),
         notifyTurnAccepted: () => notifyTurnAccepted(),
@@ -388,6 +396,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
             role: client.role,
             pending_dialog: first !== undefined ? first.request : null,
             agentDir: getAgentDir(),
+            recentUserMessages: messageLedger.recentUserMessages(),
         }, true);
         // No display_* replay: the retained extension state rides IN the snapshot
         // (`snapshot.display`), so catch-up is one atomic frame. A viewer attaching
@@ -500,7 +509,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
     rebind.setRebindSession();
     await rebind.enqueueRebind(session, services);
     const frameDispatch = createFrameDispatchContext({
-        nodeId, cfg, registry, toolGroups, projection, rebind, reviewCompanion,
+        nodeId, cfg, registry, toolGroups, projection, ledger: messageLedger, rebind, reviewCompanion,
         pendingDialogs, sendWelcome, replayExtraPendingDialogsTo, reWelcomeAll, disposeAndExit,
         persistModelChoice, broadcastModelChanged, registryOf, formatModelSpec,
         formatExactModelSpec, resolveLaunchModel,

package/dist/core/runtime/interactive-deliver.d.ts

@@ -6,8 +6,11 @@ export type LiveDeliverRoute = 'prompt' | 'steer';
 export type LiveInterruptOutcome = 'turn' | 'bash' | 'idle';
 /** Deliver `text` to a LIVE node's engine on its serialized frame loop. The
  *  broker routes it itself (idle → prompt, streaming → steer) and acks once
- *  routed; resolves with the route taken. */
-export declare function deliverLive(nodeId: string, text: string): Promise<LiveDeliverRoute>;
+ *  routed; resolves with the route taken. `messageId` is the sender-minted
+ *  message identity (`SendMessageRequest.message_id`), carried on the deliver
+ *  frame so the broker's ledger echoes it back on the relayed user
+ *  `message_start` — distinct from the one-shot ack-correlation id. */
+export declare function deliverLive(nodeId: string, text: string, messageId?: string): Promise<LiveDeliverRoute>;
 /** Abort whatever a LIVE node's engine is doing (turn or `!` bash). Resolves
  *  once the broker has PROCESSED the abort — which, on the single frame loop,
  *  also implies every earlier-accepted deliver was already routed (so a

package/dist/core/runtime/interactive-deliver.js

@@ -14,14 +14,17 @@
 import { oneShotControllerRequest } from './broker-request.js';
 /** Deliver `text` to a LIVE node's engine on its serialized frame loop. The
  *  broker routes it itself (idle → prompt, streaming → steer) and acks once
- *  routed; resolves with the route taken. */
-export function deliverLive(nodeId, text) {
+ *  routed; resolves with the route taken. `messageId` is the sender-minted
+ *  message identity (`SendMessageRequest.message_id`), carried on the deliver
+ *  frame so the broker's ledger echoes it back on the relayed user
+ *  `message_start` — distinct from the one-shot ack-correlation id. */
+export function deliverLive(nodeId, text, messageId) {
     return oneShotControllerRequest({
         nodeId,
         what: 'the interactive delivery',
         ackFor: 'deliver',
         correlated: true,
-        frame: (id) => ({ type: 'deliver', id, text }),
+        frame: (id) => ({ type: 'deliver', id, text, ...(messageId !== undefined ? { message_id: messageId } : {}) }),
         result: (detail) => (detail === 'steer' ? 'steer' : 'prompt'),
     });
 }

package/dist/core/runtime/shell-expansion.d.ts

@@ -0,0 +1,32 @@
+export declare const DEFAULT_SHELL_TIMEOUT_MS = 120000;
+/** Runs one command and returns the text that replaces it in the body. A runner
+ * never throws: a failure is reported inline so the surrounding document still
+ * reaches the model. */
+export type ShellRunner = (cmd: string) => Promise<string>;
+/** True when `body` carries at least one shell construct. Lets a caller skip an
+ * async execution pass (and its cwd/timeout plumbing) for the common inert
+ * document. */
+export declare function hasShellBlocks(body: string): boolean;
+/** Cap runaway command output before it becomes model context. */
+export declare function truncateShellOutput(content: string): string;
+/** Merge a completed command's streams the way the model should read them. */
+export declare function formatShellResult(result: {
+    code: number | null;
+    killed?: boolean;
+    stdout?: string;
+    stderr?: string;
+    timeoutMs: number;
+}): string;
+/** The runner for processes with no pi engine — every CLI leaf. */
+export declare function makeNodeShellRunner(opts: {
+    cwd: string;
+    timeoutMs?: number;
+}): ShellRunner;
+/** Replace every shell construct in `body` with its output.
+ *
+ * Fenced blocks resolve first behind sentinels so an inline pattern inside a
+ * block's own text is never executed a second time; inline forms resolve
+ * against the masked text; sentinels are then restored. Commands run in
+ * document order, exactly once per call — a document read twice runs its
+ * commands twice, which is the intended "once per invocation" contract. */
+export declare function expandShellBlocks(body: string, run: ShellRunner): Promise<string>;

package/dist/core/runtime/shell-expansion.js

@@ -0,0 +1,102 @@
+import { execFile } from 'node:child_process';
+// ---------------------------------------------------------------------------
+// Shell expansion inside Markdown bodies: `!`cmd`` inline and ```! fenced
+// blocks are replaced by the command's output.
+//
+// The grammar and substitution ORDER live here; the execution STRATEGY is
+// injected. Two callers need different strategies:
+//   • Broker-side extensions run through `pi.exec`, so the engine sees the
+//     subprocess (claude-plugin-commands, memory-slash-commands).
+//   • CLI leaves have no pi engine and must not import one — `crtr memory read`
+//     uses `makeNodeShellRunner` over node:child_process.
+//
+// Node built-ins ONLY. This module is reachable from `src/commands/**`, where a
+// `@earendil-works/pi-coding-agent` import would load the whole pi runtime just
+// to read a document.
+// ---------------------------------------------------------------------------
+// Built fresh per use, never shared. A module-level /g regex carries mutable
+// `lastIndex`, and both `.test()` and `matchAll` (which copies it into its
+// internal clone) would make one call silently skip matches another consumed.
+const SHELL_INLINE_SOURCE = '!`([^`\\n]+)`';
+const SHELL_BLOCK_SOURCE = '```!\\n([\\s\\S]*?)\\n```';
+const inlineRe = () => new RegExp(SHELL_INLINE_SOURCE, 'g');
+const blockRe = () => new RegExp(SHELL_BLOCK_SOURCE, 'g');
+export const DEFAULT_SHELL_TIMEOUT_MS = 120_000;
+const MAX_OUTPUT_LINES = 2000;
+const MAX_OUTPUT_BYTES = 50_000;
+/** True when `body` carries at least one shell construct. Lets a caller skip an
+ * async execution pass (and its cwd/timeout plumbing) for the common inert
+ * document. */
+export function hasShellBlocks(body) {
+    return new RegExp(SHELL_INLINE_SOURCE).test(body) || new RegExp(SHELL_BLOCK_SOURCE).test(body);
+}
+/** Cap runaway command output before it becomes model context. */
+export function truncateShellOutput(content) {
+    const lines = content.split('\n');
+    if (lines.length > MAX_OUTPUT_LINES) {
+        return `${lines.slice(0, MAX_OUTPUT_LINES).join('\n')}\n[truncated: hit ${MAX_OUTPUT_LINES} lines]`;
+    }
+    if (Buffer.byteLength(content, 'utf8') > MAX_OUTPUT_BYTES) {
+        return `${Buffer.from(content, 'utf8').subarray(0, MAX_OUTPUT_BYTES).toString('utf8')}\n[truncated: hit ${MAX_OUTPUT_BYTES} bytes]`;
+    }
+    return content;
+}
+/** Merge a completed command's streams the way the model should read them. */
+export function formatShellResult(result) {
+    if (result.killed === true) {
+        return `[Shell error: timed out after ${Math.max(1, Math.round(result.timeoutMs / 1000))}s]`;
+    }
+    if (result.code !== 0) {
+        return `[Shell error: exit code ${result.code}]\n${truncateShellOutput(result.stderr ?? '')}`;
+    }
+    let combined = result.stdout ?? '';
+    if (result.stderr !== undefined && result.stderr !== '') {
+        const sep = combined.length === 0 || combined.endsWith('\n') ? '' : '\n';
+        combined = `${combined}${sep}[stderr]\n${result.stderr}`;
+    }
+    return truncateShellOutput(combined);
+}
+/** The runner for processes with no pi engine — every CLI leaf. */
+export function makeNodeShellRunner(opts) {
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_SHELL_TIMEOUT_MS;
+    const [sh, flag] = process.platform === 'win32' ? ['powershell.exe', '-Command'] : ['sh', '-c'];
+    return (cmd) => new Promise((resolve) => {
+        execFile(sh, [flag, cmd], { cwd: opts.cwd, timeout: timeoutMs, maxBuffer: MAX_OUTPUT_BYTES * 4, encoding: 'utf8' }, (err, stdout, stderr) => {
+            // On timeout execFile kills the child and reports `killed: true` with
+            // a null `code` and a signal — never a numeric exit status. Check that
+            // first, or a timeout is misreported as a generic failure.
+            const e = err;
+            const killed = e !== null && (e.killed === true || (e.signal !== undefined && e.signal !== null));
+            const code = e === null ? 0 : typeof e.code === 'number' ? e.code : 1;
+            resolve(formatShellResult({ code, killed, stdout, stderr, timeoutMs }));
+        });
+    });
+}
+/** Replace every shell construct in `body` with its output.
+ *
+ * Fenced blocks resolve first behind sentinels so an inline pattern inside a
+ * block's own text is never executed a second time; inline forms resolve
+ * against the masked text; sentinels are then restored. Commands run in
+ * document order, exactly once per call — a document read twice runs its
+ * commands twice, which is the intended "once per invocation" contract. */
+export async function expandShellBlocks(body, run) {
+    const blockOut = [];
+    let masked = '';
+    let last = 0;
+    for (const m of body.matchAll(blockRe())) {
+        const idx = m.index ?? 0;
+        masked += body.slice(last, idx) + `\x00B${blockOut.length}\x00`;
+        blockOut.push(await run(m[1] ?? ''));
+        last = idx + m[0].length;
+    }
+    masked += body.slice(last);
+    let inlined = '';
+    last = 0;
+    for (const m of masked.matchAll(inlineRe())) {
+        const idx = m.index ?? 0;
+        inlined += masked.slice(last, idx) + (await run(m[1] ?? ''));
+        last = idx + m[0].length;
+    }
+    inlined += masked.slice(last);
+    return inlined.replace(/\x00B(\d+)\x00/g, (_, n) => blockOut[parseInt(n, 10)] ?? '');
+}

package/dist/core/session-model/session-state.d.ts

@@ -24,10 +24,15 @@ export interface SessionState {
     /** Live context occupancy in prompt tokens: seeded from the snapshot's
      *  contextUsage, then tracked off each assistant `message_end`. */
     contextTokens: number | undefined;
-    /** Queued steering + follow-up message TEXT, from `queue_update`. A fresh
-     *  broker with an empty queue emits no `queue_update`, so every welcome resets
-     *  this rather than leaving a dead broker's rows on screen. */
-    queued: string[];
+    /** Queued steering + follow-up messages, from `queue_update`. `id` is the
+     *  broker's message-ledger identity for the entry (`steeringIds`/
+     *  `followUpIds`), absent on a broker pinned to an older runtime generation.
+     *  A fresh broker with an empty queue emits no `queue_update`, so every
+     *  welcome resets this rather than leaving a dead broker's rows on screen. */
+    queued: Array<{
+        id?: string;
+        text: string;
+    }>;
     display: DisplayState;
     /** The blocking dialog awaiting an answer, or null. Only a writable client is
      *  ever sent one, and every writable client is sent the SAME one — the first

package/dist/core/session-model/session-state.js

@@ -132,7 +132,11 @@ export function reduce(state, frame) {
         case 'thinking_level_changed':
             return patchEngine(state, { thinkingLevel: frame.level });
         case 'queue_update': {
-            const queued = [...frame.steering, ...frame.followUp];
+            // The broker enriches relayed queue_updates with id arrays parallel to
+            // pi's text arrays; zip them, tolerating their absence (older broker).
+            const { steeringIds, followUpIds } = frame;
+            const zip = (texts, ids) => texts.map((text, i) => (ids?.[i] !== undefined ? { id: ids[i], text } : { text }));
+            const queued = [...zip(frame.steering, steeringIds), ...zip(frame.followUp, followUpIds)];
             const next = patchEngine(state, { pendingMessageCount: queued.length });
             return { ...next, queued };
         }

package/dist/daemon/api/handlers/broker-ops.js

@@ -15,6 +15,7 @@ import { handleNewSession } from '../../../core/runtime/reset.js';
 import { evaluateStop } from '../../../core/runtime/stop-guard.js';
 import { clearFault } from '../../../core/runtime/fault.js';
 import { updateModelRecipe } from '../../../core/runtime/model-swap.js';
+import { completeCompanionRequestedSubmit } from '../../review/finish.js';
 function objectBody(body, operation) {
     if (typeof body !== 'object' || body === null || Array.isArray(body)) {
         throw usage(`${operation} requires a JSON body`);
@@ -289,6 +290,13 @@ function handleSettle(ctx) {
     const nodeId = ctx.params['id'];
     const request = parseSettleBody(ctx.body);
     const directive = withCanvasWrite(() => settleBroker(nodeId, request));
+    // A review companion that just went quiet releases any submit the human left
+    // waiting on it. A reprompt is not going quiet, so it waits for the turn that
+    // reprompt starts. This never blocks the directive: the completion delivers
+    // an approval and retires this very broker, and the broker is owed its answer
+    // first.
+    if (directive.action !== 'reprompt')
+        void completeCompanionRequestedSubmit(nodeId);
     return { status: 200, body: directive };
 }
 /** Commit a watcher cursor only while this broker generation remains current.

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

@@ -6,6 +6,7 @@
 //   POST   /v1/crons/:cronId/pause   stop firing, keep config + history
 //   POST   /v1/crons/:cronId/resume  re-arm a paused cron
 //   POST   /v1/crons/:cronId/run     fire NOW, out of band (synchronous)
+//   POST   /v1/crons/poke            eligibility poke: re-due every held cron
 //   DELETE /v1/crons/:cronId         cancel one cron (idempotent, kills in-flight run)
 //
 // The CLI resolves timing client-side (parseWhen/parseCadence) and sends the
@@ -21,7 +22,7 @@
 // display spec.
 import { randomUUID } from 'node:crypto';
 import { ApiError } from '../../../api/errors.js';
-import { armCron, cancelCron, getCron, listCrons, listCronRuns, setCronState, } from '../../../core/canvas/crons.js';
+import { armCron, cancelCron, getCron, listCrons, listCronRuns, pokeHeldCrons, setCronState, } from '../../../core/canvas/crons.js';
 import { getNode } from '../../../core/canvas/canvas.js';
 import { InputError } from '../../../core/io.js';
 import { nextSlotAfter } from '../../../core/wake.js';
@@ -329,6 +330,17 @@ async function handleRun(ctx) {
     }
     return { status: 200, body: toCronRunDTO(record) };
 }
+/** `POST /v1/crons/poke` — the bare daemon-level eligibility poke: "something
+ *  changed; re-check now". Canvas-wide and label-free by design — the caller
+ *  (a host platform, an operator's curl) asserts only that eligibility
+ *  changed; every held row re-checks its own gate in bash and re-parks if
+ *  still blocked. Paused rows are not unparked (pause is user-owned).
+ *  Idempotent and free when nothing is held. The count is for the caller's
+ *  log line, nothing else. */
+function handlePoke() {
+    const at = new Date().toISOString();
+    return { status: 200, body: { unparked: pokeHeldCrons(at), at } };
+}
 /** `DELETE /v1/crons/:cronId` — cancel one cron. Idempotent: an already-absent
  *  cron is a no-op 204 (`cancelCron` kills any in-flight run process group
  *  before deleting). */
@@ -354,6 +366,7 @@ export const cronRoutes = [
     { method: 'GET', pattern: '/v1/crons/:cronId', handler: handleShow },
     { method: 'POST', pattern: '/v1/crons/:cronId/pause', handler: handlePause },
     { method: 'POST', pattern: '/v1/crons/:cronId/resume', handler: handleResume },
+    { method: 'POST', pattern: '/v1/crons/poke', handler: handlePoke },
     { method: 'POST', pattern: '/v1/crons/:cronId/run', handler: handleRun },
     { method: 'DELETE', pattern: '/v1/crons/:cronId', handler: handleCancel },
 ];

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

@@ -89,6 +89,11 @@ function toDeckSourceDTO(source) {
         dto.askedBy = source.askedBy;
     if (source.blockedSince !== undefined)
         dto.blockedSince = source.blockedSince;
+    // The originating canvas node id — machine attribution a consumer uses to
+    // relate a ticket to the node that raised it. A node id is opaque canvas
+    // identity, not a host path, so it is safe on this wire.
+    if (source.nodeId !== undefined)
+        dto.nodeId = source.nodeId;
     return dto;
 }
 function toOptionDTO(option) {

package/dist/daemon/api/handlers/memory.d.ts

@@ -0,0 +1,2 @@
+import type { RouteTable } from '../router.js';
+export declare const memoryRoutes: RouteTable;

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

@@ -0,0 +1,48 @@
+// Memory-document resolution handler — `GET /v1/memory/resolve?name=&node=`.
+// Turns a `[[canonical/name]]` link written in a node's transcript into the
+// absolute path of the document THAT node would read, so a client can peek it
+// (`GET /v1/files/peek`) and render it.
+//
+// The node is required, not optional: crtrd serves every node from one process,
+// so its own cwd and env name no node, and the same name legitimately resolves
+// to different documents for two nodes (each has its own context store, project
+// stack, and profile). Resolution therefore runs target-addressed —
+// `resolveMemoryDocForTarget` with the node's cwd/profile/id off canvas.
+import { getNode } from '../../../index.js';
+import { notFound, usage } from '../../../core/errors.js';
+import { resolveMemoryDocForTarget } from '../../../core/memory-resolver.js';
+import { isDocLinkName } from '../../../core/memory/doc-link-grammar.js';
+function handleResolve(ctx) {
+    const name = ctx.query.get('name');
+    if (name === null || name === '') {
+        throw usage('a memory resolve requires a `name` query param');
+    }
+    // The link grammar is the same one that produced the link (browser-safe, one
+    // source of truth): anything outside it is not a document name, and rejecting
+    // it here keeps a stray `[[…]]` from reaching the resolver's scope parsing.
+    if (!isDocLinkName(name)) {
+        throw usage('memory document name must be `/`-joined [A-Za-z0-9_-] segments', { received: name });
+    }
+    const nodeId = ctx.query.get('node');
+    if (nodeId === null || nodeId === '') {
+        throw usage('a memory resolve requires a `node` query param — resolution is per-node');
+    }
+    const meta = getNode(nodeId);
+    if (meta === null)
+        throw notFound(`unknown node: ${nodeId}`, { received: nodeId });
+    const doc = resolveMemoryDocForTarget(name, {
+        cwd: meta.cwd,
+        profileId: meta.profile_id ?? null,
+        nodeId: meta.node_id,
+    });
+    const body = {
+        name: doc.name,
+        scope: doc.scope,
+        path: doc.path,
+        ...(doc.plugin === undefined ? {} : { plugin: doc.plugin }),
+    };
+    return { status: 200, body };
+}
+export const memoryRoutes = [
+    { method: 'GET', pattern: '/v1/memory/resolve', handler: handleResolve },
+];