@north-light/crouter 0.3.308 → 0.3.309

package/dist/daemon/reconcilers/broker-supervision.d.ts

@@ -11,6 +11,14 @@ export interface BrokerSupervisionContext {
     fleet: FleetRegistry;
     lifecycle: DetachedWorkLifecycle;
 }
+type TreeSample = {
+    cpuPercent: number;
+    hasDescendants: boolean;
+} | null;
+export interface BrokerSupervisionOptions {
+    readTreeSample?: (pid: number) => Promise<TreeSample>;
+    signal?: (pid: number, signal: NodeJS.Signals) => void;
+}
 export interface SaturationContext {
     fleet: FleetRegistry;
     lifecycle: DetachedWorkLifecycle;
@@ -41,13 +49,15 @@ export declare function wedgeVerdict(input: {
 export declare function sumTreeCpu(psOutput: string, rootPid: number): number | null;
 export declare function treeHasDescendants(psOutput: string, rootPid: number): boolean | null;
 export declare class BrokerSupervisionReconciler {
-    private readonly yieldStallSince;
-    private readonly yieldTermAt;
+    private readonly yieldStalls;
     private readonly wedgeNotifiedAt;
     private readonly fatalFaultNotifiedAt;
     private readonly unattendedSince;
+    private readonly sampleTree;
+    private readonly signal;
     private knownAuthMtimeMs;
     private lastOverCapWarnAt;
+    constructor(options?: BrokerSupervisionOptions);
     /** The fleet-wide preamble, run BEFORE the tick's row-list guard: an auth
      *  reload does not depend on a successful canvas scan, and the thresholds it
      *  returns are read once for the whole tick. */
@@ -70,8 +80,10 @@ export declare class BrokerSupervisionReconciler {
     private requestParkSummary;
     private warnOverCapInTmux;
     private handleYieldStall;
+    private signalYieldStall;
     private readTreeSample;
     private handleWedgeDetection;
     private handleFatalFault;
     private handleAuthReload;
 }
+export {};

package/dist/daemon/reconcilers/broker-supervision.js

@@ -30,6 +30,16 @@ import { shouldParkAfterSummary } from '../park-activity.js';
 import { applyParkEvent, parkEvent } from './live-obligation.js';
 import { envNoDaemonAutostart, envTestUnattendedParkMs, parkSummaryGraceMs, envUnattendedParkMs, } from '../../shared/env.js';
 const execFileAsync = promisify(execFile);
+function incarnationOf(pid, identity) {
+    return identity === null ? null : `${pid}:${identity}`;
+}
+function busySinceForIncarnation(row) {
+    const since = busySince(row.node_id);
+    const launchedAt = row.launched_at === null || row.launched_at === undefined ? Number.NaN : Date.parse(row.launched_at);
+    if (since === null || !Number.isFinite(launchedAt) || since < launchedAt)
+        return null;
+    return since;
+}
 export const YIELD_STALL_GRACE_MS = 3 * 60_000;
 const KILL_ESCALATE_MS = 20_000;
 export const WEDGE_QUIET_MS = 20 * 60_000;
@@ -131,13 +141,18 @@ function piCredentialPaths() {
     ];
 }
 export class BrokerSupervisionReconciler {
-    yieldStallSince = new Map();
-    yieldTermAt = new Map();
+    yieldStalls = new Map();
     wedgeNotifiedAt = new Map();
     fatalFaultNotifiedAt = new Map();
     unattendedSince = new Map();
+    sampleTree;
+    signal;
     knownAuthMtimeMs = null;
     lastOverCapWarnAt = Number.NEGATIVE_INFINITY;
+    constructor(options = {}) {
+        this.sampleTree = options.readTreeSample ?? ((pid) => this.readTreeSample(pid));
+        this.signal = options.signal ?? ((pid, signal) => process.kill(pid, signal));
+    }
     /** The fleet-wide preamble, run BEFORE the tick's row-list guard: an auth
      *  reload does not depend on a successful canvas scan, and the thresholds it
      *  returns are read once for the whole tick. */
@@ -168,8 +183,8 @@ export class BrokerSupervisionReconciler {
             }
             await operationIdContext.fresh(async () => {
                 try {
-                    this.handleYieldStall(row, entry.pid, now);
-                    await this.handleWedgeDetection(id, entry.pid, row.pi_pid_identity, now);
+                    this.handleYieldStall(row, entry, ctx.fleet, now);
+                    await this.handleWedgeDetection(row, entry, ctx.fleet, now);
                     this.handleFatalFault(id);
                     this.handleUnattendedParking(id, getNode(id), entry.pid, now, ctx, unattendedParkMs);
                 }
@@ -391,62 +406,74 @@ export class BrokerSupervisionReconciler {
             emitEvent({ level: 'error', event: 'broker.capacity.tmux_list_clients_failed', error: err });
         }
     }
-    handleYieldStall(row, pid, now) {
+    handleYieldStall(row, entry, fleet, now) {
         const id = row.node_id;
-        if (row.intent !== 'refresh' || isBusy(id)) {
-            this.yieldStallSince.delete(id);
-            this.yieldTermAt.delete(id);
+        const incarnation = incarnationOf(entry.pid, row.pi_pid_identity);
+        if (row.intent !== 'refresh' || busySinceForIncarnation(row) !== null || incarnation === null) {
+            if (incarnation !== null)
+                this.yieldStalls.delete(incarnation);
             return;
         }
-        const since = this.yieldStallSince.get(id);
-        if (since === undefined) {
-            this.yieldStallSince.set(id, now);
+        let state = this.yieldStalls.get(incarnation);
+        if (state === undefined) {
+            state = { since: now };
+            this.yieldStalls.set(incarnation, state);
             return;
         }
-        if (yieldStallVerdict(true, row.intent, false, now - since) !== 'kill')
+        if (yieldStallVerdict(true, row.intent, false, now - state.since) !== 'kill')
             return;
-        if (row.pi_pid_identity == null || recordedPidLiveness(pid, row.pi_pid_identity) !== 'alive')
+        const current = getNode(id);
+        if (fleet.get(id) !== entry || current?.pi_pid !== entry.pid || current.pi_pid_identity !== row.pi_pid_identity || recordedPidLiveness(entry.pid, row.pi_pid_identity) !== 'alive')
             return;
-        const termed = this.yieldTermAt.get(id);
-        if (termed === undefined) {
+        if (state.termedAt === undefined) {
+            if (!this.signalYieldStall(id, entry.pid, 'SIGTERM'))
+                return;
+            state.termedAt = now;
             emitEvent({
                 level: 'warn',
                 event: 'broker.yield_stall.sigterm',
                 ...(isSafeNodeId(id) ? { node_id: id } : {}),
                 fields: {
                     ...(isSafeNodeId(id) ? {} : { affected_node_id: id }),
-                    pid,
-                    elapsed_ms: now - since,
+                    pid: entry.pid,
+                    elapsed_ms: now - state.since,
                     grace_ms: YIELD_STALL_GRACE_MS,
                 },
             });
-            try {
-                process.kill(pid, 'SIGTERM');
-            }
-            catch {
-                /* already gone */
-            }
-            this.yieldTermAt.set(id, now);
         }
-        else if (now - termed >= KILL_ESCALATE_MS) {
+        else if (now - state.termedAt >= KILL_ESCALATE_MS && this.signalYieldStall(id, entry.pid, 'SIGKILL')) {
             emitEvent({
                 level: 'warn',
                 event: 'broker.yield_stall.sigkill',
                 ...(isSafeNodeId(id) ? { node_id: id } : {}),
                 fields: {
                     ...(isSafeNodeId(id) ? {} : { affected_node_id: id }),
-                    pid,
-                    elapsed_ms: now - termed,
+                    pid: entry.pid,
+                    elapsed_ms: now - state.termedAt,
                     grace_ms: KILL_ESCALATE_MS,
-                    stall_elapsed_ms: now - since,
+                    stall_elapsed_ms: now - state.since,
                 },
             });
-            try {
-                process.kill(pid, 'SIGKILL');
-            }
-            catch {
-                /* already gone */
-            }
+        }
+    }
+    signalYieldStall(id, pid, signal) {
+        try {
+            this.signal(pid, signal);
+            return true;
+        }
+        catch (err) {
+            emitEvent({
+                level: 'error',
+                event: 'broker.yield_stall.signal_failed',
+                ...(isSafeNodeId(id) ? { node_id: id } : {}),
+                error: err,
+                fields: {
+                    ...(isSafeNodeId(id) ? {} : { affected_node_id: id }),
+                    pid,
+                    signal,
+                },
+            });
+            return false;
         }
     }
     async readTreeSample(pid) {
@@ -467,29 +494,36 @@ export class BrokerSupervisionReconciler {
             return null;
         }
     }
-    async handleWedgeDetection(id, pid, expectedIdentity, now) {
-        if (!isBusy(id)) {
-            this.wedgeNotifiedAt.delete(id);
+    async handleWedgeDetection(row, entry, fleet, now) {
+        const id = row.node_id;
+        const incarnation = incarnationOf(entry.pid, row.pi_pid_identity);
+        const since = busySinceForIncarnation(row);
+        if (since === null || incarnation === null) {
+            if (incarnation !== null)
+                this.wedgeNotifiedAt.delete(incarnation);
             return;
         }
-        const since = busySince(id);
-        const quietForMs = since === null ? null : now - since;
-        const sample = quietForMs !== null && quietForMs >= WEDGE_QUIET_MS ? await this.readTreeSample(pid) : null;
+        const quietForMs = now - since;
+        const sample = quietForMs >= WEDGE_QUIET_MS ? await this.sampleTree(entry.pid) : null;
+        const current = getNode(id);
+        const currentSince = current === null ? null : busySinceForIncarnation(current);
+        if (fleet.get(id) !== entry || current === null || current.pi_pid !== entry.pid || current.pi_pid_identity !== row.pi_pid_identity || currentSince !== since)
+            return;
         const cpuPercent = sample?.cpuPercent ?? null;
         const sampleHasDescendants = sample?.hasDescendants ?? null;
         if (wedgeVerdict({ busy: true, quietForMs, cpuPercent, hasDescendants: sampleHasDescendants }) !== 'wedged')
             return;
-        if (since !== null && this.wedgeNotifiedAt.get(id) === since)
+        if (this.wedgeNotifiedAt.get(incarnation) === since)
             return;
-        if (since !== null)
-            this.wedgeNotifiedAt.set(id, since);
-        const meta = getNode(id);
-        const name = meta !== null ? fullName(meta) : id;
+        this.wedgeNotifiedAt.set(incarnation, since);
+        const name = fullName(current);
         const minutes = Math.round((quietForMs ?? WEDGE_QUIET_MS) / 60_000);
         const hasDescendants = sampleHasDescendants ?? true;
-        const kickSuppressionReason = !hasDescendants && (expectedIdentity == null || recordedPidLiveness(pid, expectedIdentity) !== 'alive')
+        const kickSuppressionReason = !hasDescendants && recordedPidLiveness(entry.pid, row.pi_pid_identity) !== 'alive'
             ? 'pid_identity_unproven'
             : null;
+        let kickAttempted = false;
+        let kicked = false;
         let label;
         if (hasDescendants) {
             label =
@@ -506,16 +540,32 @@ export class BrokerSupervisionReconciler {
                     `confirmed alive.`;
         }
         else {
-            label =
-                `Child wedged — ${name} (${id}) is alive and mid-turn but has shown NO engine progress for ` +
-                    `${minutes}+ minutes and it has no subprocess to kill (the engine itself stalled). Kicking it ` +
-                    `now: SIGTERM to the broker — the daemon will resume a cleanly ` +
-                    `aborted session with a continuation, or start a recovery cycle if the abort cannot settle.`;
+            kickAttempted = true;
             try {
-                process.kill(pid, 'SIGTERM');
+                this.signal(entry.pid, 'SIGTERM');
+                kicked = true;
+                label =
+                    `Child wedged — ${name} (${id}) is alive and mid-turn but has shown NO engine progress for ` +
+                        `${minutes}+ minutes and it has no subprocess to kill (the engine itself stalled). The daemon sent ` +
+                        `SIGTERM to the broker and will resume a cleanly aborted session with a continuation, or start a ` +
+                        `recovery cycle if the abort cannot settle.`;
             }
-            catch {
-                /* already gone — its ChildProcess exit event still owns recovery */
+            catch (err) {
+                emitEvent({
+                    level: 'error',
+                    event: 'broker.wedge.signal_failed',
+                    ...(isSafeNodeId(id) ? { node_id: id } : {}),
+                    error: err,
+                    fields: {
+                        ...(isSafeNodeId(id) ? {} : { affected_node_id: id }),
+                        pid: entry.pid,
+                        signal: 'SIGTERM',
+                    },
+                });
+                label =
+                    `Child wedged — ${name} (${id}) is alive and mid-turn but has shown NO engine progress for ` +
+                        `${minutes}+ minutes and it has no subprocess to kill (the engine itself stalled). The daemon ` +
+                        `attempted SIGTERM to the broker, but the signal call failed.`;
             }
         }
         emitEvent({
@@ -524,11 +574,12 @@ export class BrokerSupervisionReconciler {
             ...(isSafeNodeId(id) ? { node_id: id } : {}),
             fields: {
                 ...(isSafeNodeId(id) ? {} : { affected_node_id: id }),
-                pid,
+                pid: entry.pid,
                 quiet_ms: quietForMs,
                 cpu_percent: cpuPercent,
                 has_descendants: hasDescendants,
-                kicked: !hasDescendants && kickSuppressionReason === null,
+                kick_attempted: kickAttempted,
+                kicked,
                 ...(kickSuppressionReason === null ? {} : { kick_suppression_reason: kickSuppressionReason }),
             },
         });
@@ -554,7 +605,8 @@ export class BrokerSupervisionReconciler {
             child: id,
             quiet_ms: quietForMs,
             cpu_percent: cpuPercent,
-            kicked: !hasDescendants && kickSuppressionReason === null,
+            kick_attempted: kickAttempted,
+            kicked,
             ...(kickSuppressionReason === null ? {} : { kick_suppression_reason: kickSuppressionReason }),
         });
     }

package/dist/daemon/reconcilers/storage-maintenance.d.ts

@@ -13,6 +13,7 @@ export interface StorageMaintenanceContext {
 export declare class StorageMaintenanceReconciler {
     private lastSpareSweepAt;
     private lastGhostSweepAt;
+    private focusGcInFlight;
     private readonly worktreeSweep;
     run(now: number, ctx: StorageMaintenanceContext): void;
     /** Drop rows whose on-disk node dir is gone. Such a row can never be revived,
@@ -25,6 +26,10 @@ export declare class StorageMaintenanceReconciler {
     /** Reap only physical placement residue of terminal nodes. The durable row,
      * graph, and on-disk state remain available for a later manual revive. */
     private reapDeadResidue;
+    /** Register one detached focus-GC pass, never overlapping another. The pane
+     * probe is a subprocess, and running it on the tick blocks the API socket for
+     * its full duration on every beat. */
+    private scheduleFocusGc;
     /** Delete focus rows whose recorded tmux pane no longer exists. A failed tmux
      * probe is "can't tell" and never authorizes deleting every viewport. */
     private gcStaleFocuses;

package/dist/daemon/reconcilers/storage-maintenance.js

@@ -1,10 +1,10 @@
 import { statSync } from 'node:fs';
 import { join } from 'node:path';
-import { closeFocusRow, listFocuses, listNodes, reapGhostRows, } from '../../core/canvas/index.js';
+import { closeFocusRow, getFocusById, listFocuses, listNodes, reapGhostRows, } from '../../core/canvas/index.js';
 import { isSafeNodeId, jobDir, nodeDir } from '../../core/canvas/paths.js';
 import { emitEvent } from '../../core/events/emit.js';
 import { operationIdContext } from '../../core/events/operation-id.js';
-import { listLivePanes, tearDownNode } from '../../core/runtime/placement.js';
+import { listLivePanesAsync, tearDownNode } from '../../core/runtime/placement.js';
 import { reapStaleSpares } from '../../core/runtime/warm-pool.js';
 import { ManagedWorktreeSweepReconciler } from './managed-worktree-sweep.js';
 // How long a dead node's on-disk record must be quiet before its leftover
@@ -18,13 +18,16 @@ const GHOST_SWEEP_INTERVAL_MS = 60 * 1000;
 export class StorageMaintenanceReconciler {
     lastSpareSweepAt = Number.NEGATIVE_INFINITY;
     lastGhostSweepAt = Number.NEGATIVE_INFINITY;
+    focusGcInFlight = false;
     worktreeSweep = new ManagedWorktreeSweepReconciler();
     run(now, ctx) {
         // Placement reap MUST precede focus GC, so GC catches a focus row the reap
         // strands. Both run after the lifecycle tick, so a same-tick revive has
-        // already had the chance to re-anchor its focus.
+        // already had the chance to re-anchor its focus. The GC is detached, but it
+        // reads the focus table synchronously before its first await, so it still
+        // observes the post-reap state this ordering exists to give it.
         this.reapDeadResidue(now);
-        this.gcStaleFocuses();
+        this.scheduleFocusGc(ctx);
         this.reapGhostRows(now);
         this.gcWarmPool(now);
         // Registers detached async Git work and returns immediately: this lane is
@@ -140,9 +143,23 @@ export class StorageMaintenanceReconciler {
             });
         }
     }
+    /** Register one detached focus-GC pass, never overlapping another. The pane
+     * probe is a subprocess, and running it on the tick blocks the API socket for
+     * its full duration on every beat. */
+    scheduleFocusGc(ctx) {
+        if (this.focusGcInFlight)
+            return;
+        if (!ctx.lifecycle.acceptsDetachedWork())
+            return;
+        this.focusGcInFlight = true;
+        const pass = this.gcStaleFocuses().finally(() => {
+            this.focusGcInFlight = false;
+        });
+        ctx.lifecycle.registerDetached(pass);
+    }
     /** Delete focus rows whose recorded tmux pane no longer exists. A failed tmux
      * probe is "can't tell" and never authorizes deleting every viewport. */
-    gcStaleFocuses() {
+    async gcStaleFocuses() {
         let rows;
         try {
             rows = listFocuses();
@@ -157,7 +174,7 @@ export class StorageMaintenanceReconciler {
             return;
         let live;
         try {
-            live = listLivePanes();
+            live = await listLivePanesAsync();
         }
         catch (err) {
             operationIdContext.fresh(() => {
@@ -170,8 +187,14 @@ export class StorageMaintenanceReconciler {
         for (const focus of rows) {
             if (focus.pane === null || live.has(focus.pane))
                 continue;
-            const removed = operationIdContext.fresh(() => {
+            const proceed = operationIdContext.fresh(() => {
                 try {
+                    // The probe awaited above let other event-loop work run, so a viewer
+                    // may have re-pointed this row at a pane the probe never saw. Re-read
+                    // and match the pane before deleting; the read and the delete are both
+                    // synchronous, so nothing can interleave between them.
+                    if (getFocusById(focus.focus_id)?.pane !== focus.pane)
+                        return true;
                     emitEvent({
                         level: 'info',
                         event: 'focus.gc.removed',
@@ -190,7 +213,7 @@ export class StorageMaintenanceReconciler {
                     return false;
                 }
             });
-            if (!removed)
+            if (!proceed)
                 return;
         }
     }

package/dist/pi-extensions/__tests__/pre-command-gate.test.js

@@ -12,9 +12,9 @@
 //     executes them concurrently, so without a per-turn flag the second sibling
 //     would find the doc already exposed and slip past the hold its sibling just
 //     raised.
-//   • A session whose corpus carries no `pre-command` doc at all is the common
-//     case and must never pay a daemon round-trip. Proven by closing the daemon:
-//     if the short-circuit stopped working the call would fail loud.
+//   • A command that matches no `pre-command` doc must never pay a daemon
+//     round-trip, even when another document gates a different command. Proven
+//     against an unavailable test API socket: a lookup fails loudly.
 //
 // The gate runs against the real canvas api server, so the subject the matcher
 // gates on is the one crtrd actually serves.
@@ -104,6 +104,7 @@ function registerSubstrate() {
         bash: (command) => fire('tool_call', { toolName: 'bash', input: { command } }),
         endTurn: async () => void (await fire('turn_end', {})),
         compact: async () => void (await fire('session_compact', {})),
+        toolResult: (toolName, input) => fire('tool_result', { toolName, input, content: [] }),
     };
 }
 function assertHeld(result, what) {
@@ -207,14 +208,13 @@ test('compaction re-arms the hold and leaves an exposure ledger that reloads', a
     const reheld = assertHeld(await pi.bash('deploy prod'), 'the same command after compaction');
     assert.ok(reheld.reason.includes(DOCTRINE_BODY), 'guidance the transcript no longer carries is delivered again');
 });
-test('a corpus with no pre-command doc never reaches the daemon', async () => {
-    writeDoctrineDoc('command');
+test('a command that matches no gate never reaches the daemon', async () => {
+    writeDoctrineDoc('pre-command');
     seedNode('gate-quiet');
     const pi = registerSubstrate();
-    // No daemon. Every path below must return before the subject lookup; one that
-    // does not fails loud with `daemon_unavailable` instead of passing quietly.
+    // The test API socket is unavailable. Both hooks must return before their
+    // subject lookup; one that does not fails loud with `daemon_unavailable`.
     await closeServer();
-    assert.equal(await pi.toolCall('read', { file: '/tmp/x' }), undefined, 'a non-bash call is not the gate’s business');
-    assert.equal(await pi.toolCall('bash', { command: '   ' }), undefined, 'a bash call carrying no command is not held');
-    assert.equal(await pi.bash('deploy prod'), undefined, 'a post-execution `command` doc never holds anything');
+    assert.equal(await pi.bash('git status'), undefined, 'the pre-call hook ignores an unrelated pre-command document');
+    assert.equal(await pi.toolResult('bash', { command: 'git status' }), undefined, 'the post-result hook ignores an unrelated pre-command document');
 });

package/dist/pi-extensions/canvas-doc-substrate.js

@@ -19,7 +19,7 @@ import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { brokerExtensionState } from '../core/runtime/broker/daemon-ops.js';
 import { renderPreferencesFromState } from '../core/runtime/broker-extension-render.js';
-import { corpusHasPreCommandSurfaces, demotePreCommandExposures, renderOnCommandDocsForSubject, renderOnReadDocsForSubject, renderPreCommandDocsForSubject, } from '../core/substrate/on-read.js';
+import { corpusHasCommandSurfaceForCommand, corpusHasPreCommandSurfaceForCommand, demotePreCommandExposures, renderOnCommandDocsForSubject, renderOnReadDocsForSubject, renderPreCommandDocsForSubject, } from '../core/substrate/on-read.js';
 import { clearSessionCache } from '../core/substrate/session-cache.js';
 import { cloneContextExposureState, exposureTarget, freezePreferenceSnapshot, loadContextExposureState, mergeContextExposureState, replaceContextExposureState, saveContextExposureState, sharedContextExposureState, } from '../core/substrate/injected-store.js';
 import { autoLoadedContextInner, mergeAutoLoadedContext } from './envelope-merge.js';
@@ -110,12 +110,13 @@ export function registerCanvasDocSubstrate(pi) {
         const command = bashCommandOf(event.input);
         if (command === null)
             return;
-        // The common case is a corpus with no pre-command doc at all, and it must
-        // cost nothing — short-circuit before the daemon round-trip below.
-        if (!corpusHasPreCommandSurfaces())
-            return;
         if (blockedThisTurn)
             return { block: true, reason: HELD_SIBLING_REASON };
+        // Match the parsed command before resolving daemon-owned node config. Gates
+        // remain intentionally conservative here: a matching gated entry still
+        // resolves its subject and cannot fail open.
+        if (!corpusHasPreCommandSurfaceForCommand(command))
+            return;
         const state = await brokerExtensionState(nodeId);
         mergeContextExposureState(contextExposure, loadContextExposureState(nodeId));
         const next = cloneContextExposureState(contextExposure);
@@ -152,6 +153,11 @@ export function registerCanvasDocSubstrate(pi) {
         else {
             return;
         }
+        // A successful bash call only needs daemon-owned node config when its
+        // parsed command could match a post-command surface. Gates are deliberately
+        // ignored by this prefilter so a matching safety gate cannot fail open.
+        if (command !== null && !corpusHasCommandSurfaceForCommand(command))
+            return;
         const state = await brokerExtensionState(nodeId);
         mergeContextExposureState(contextExposure, loadContextExposureState(nodeId));
         const next = cloneContextExposureState(contextExposure);

package/dist/shared/generated-context.d.ts

@@ -69,5 +69,7 @@ export declare function formatCard(kind: string, facts: Record<string, string |
 export declare function formatDataCard(kind: string, facts: Record<string, string | number | boolean | undefined>, body: string): string;
 /** Parse a runtime envelope, with pre-envelope customType compatibility. */
 export declare function parseCard(message: GeneratedContextMessageLike): GeneratedCard | null;
+/** Explain how an inbox entry's ref is read without guessing its filesystem location. */
+export declare function formatInboxRefInstruction(ref: string): string;
 /** Format a complete inbox card from report bodies resolved by the caller. */
 export declare function formatInboxCard(sections: readonly InboxCardSection[]): string;

package/dist/shared/generated-context.js

@@ -205,6 +205,12 @@ export function parseCard(message) {
         senders: [],
     };
 }
+/** Explain how an inbox entry's ref is read without guessing its filesystem location. */
+export function formatInboxRefInstruction(ref) {
+    return ref.startsWith('/')
+        ? `Preview only. Read the full body from file \`${ref}\`.`
+        : `Read this report with \`crtr canvas history read ${ref}\`.`;
+}
 /** Format a complete inbox card from report bodies resolved by the caller. */
 export function formatInboxCard(sections) {
     const body = sections.map((section) => {

package/package.json

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

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.308",
+  "version": "0.3.309",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.308",
+      "version": "0.3.309",
       "hasInstallScript": true,
       "license": "MIT",
       "workspaces": [
@@ -5206,17 +5206,17 @@
     },
     "packages/crouter-api": {
       "name": "@north-light/crouter-api",
-      "version": "0.3.308",
+      "version": "0.3.309",
       "license": "UNLICENSED"
     },
     "packages/crouter-env-docker": {
       "name": "@north-light/crouter-env-docker",
-      "version": "0.3.308",
+      "version": "0.3.309",
       "license": "UNLICENSED"
     },
     "packages/crouter-sdk": {
       "name": "@north-light/crouter-sdk",
-      "version": "0.3.308",
+      "version": "0.3.309",
       "license": "UNLICENSED",
       "dependencies": {
         "@north-light/crouter-api": "^0.3.295"