@north-light/crouter 0.3.263 → 0.3.269

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

@@ -11,7 +11,7 @@
 // the sanctioned place for it.
 import { existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { getNode, listNodes, pruneNodes, pruneToLimit, rebuildIndex, rosterEdges, rosterNodes, subscriptionsOf } from '../../../core/canvas/canvas.js';
+import { listNodes, pruneNodes, pruneToLimit, rebuildIndex, rosterEdges, rosterNodes } from '../../../core/canvas/canvas.js';
 import { activeBackgroundBashJobs } from '../../../core/bash-jobs.js';
 import { contextDir } from '../../../core/canvas/paths.js';
 import { nowIso } from '../../../core/fs-utils.js';
@@ -20,7 +20,7 @@ import { dashboardRowsAllFromSource, enrichRowsFromSource } from '../../../core/
 import { localCanvasSource } from '../../../core/canvas/source.js';
 import { listFocuses } from '../../../core/canvas/focuses.js';
 import { ticketCountsForNodes, ticketsAcrossCanvas } from '../../../core/canvas/attention.js';
-import { buildCorpus, resolveRef, } from '../../../core/canvas/history.js';
+import { buildCorpus, groupCorpus, resolveRef, } from '../../../core/canvas/history.js';
 import { nodeDir, nodesRoot } from '../../../core/canvas/paths.js';
 import { reapEmptyNodes } from '../../../core/runtime/placement.js';
 import { general, notFound, usage } from '../../../core/errors.js';
@@ -130,9 +130,36 @@ function buildCorpusFromQuery(q) {
         statuses: q.statuses,
         sinceMs: q.since_ms,
         untilMs: q.until_ms,
+        origins: q.origins,
+        roles: q.roles,
+        from: q.from,
     };
     return buildCorpus(scope, corpusFilter);
 }
+function parseStatsBody(body) {
+    if (body === undefined || body === null)
+        return {};
+    if (typeof body !== 'object')
+        throw usage('history stats body must be a JSON object');
+    return body;
+}
+const GROUP_KEYS = ['origin', 'node', 'kind', 'day', 'type', 'role'];
+function handleHistoryStats(ctx) {
+    const q = parseStatsBody(ctx.body);
+    const by = (q.group_by ?? 'type');
+    if (!GROUP_KEYS.includes(by)) {
+        throw usage(`--group-by must be one of: ${GROUP_KEYS.join(', ')}; received: ${String(q.group_by)}`);
+    }
+    const arts = buildCorpusFromQuery(q);
+    const groups = groupCorpus(arts, by);
+    const body = {
+        group_by: by,
+        groups,
+        total: groups.reduce((sum, g) => sum + g.count, 0),
+        scanned: arts.length,
+    };
+    return { status: 200, body };
+}
 function handleHistoryGrep(ctx) {
     const q = parseGrepBody(ctx.body);
     const limit = Math.min(100, Math.max(1, q.limit ?? 20));
@@ -254,7 +281,11 @@ function handleHistoryRead(ctx) {
         });
     }
     const source = resolved.source === 'report' && resolved.reportKind ? `report:${resolved.reportKind}` : resolved.source;
-    const content = includeFrontmatter && resolved.raw !== null ? resolved.raw : resolved.body;
+    // `raw` is the verbatim record; `--frontmatter` is the narrower legacy ask
+    // for the same bytes on a markdown artifact. Either one yields the raw form
+    // when the artifact has one.
+    const wantRaw = ctx.query.get('format') === 'raw' || includeFrontmatter;
+    const content = wantRaw && resolved.raw !== null ? resolved.raw : resolved.body;
     const body = {
         ref,
         node: `${resolved.nodeName} (${resolved.nodeId})`,
@@ -288,39 +319,53 @@ async function handleSnapshot(ctx) {
     const asks = ticketCountsForNodes(rows.map((r) => r.node_id));
     await enrichRowsFromSource(localCanvasSource, rows, asks);
     const nodes = rows.map((row) => {
-        const meta = getNode(row.node_id);
-        const hostKind = meta?.host_kind ?? 'tmux';
+        // Every field here comes from the NodeRow listNodes already fetched (stashed
+        // on the row as srcRow) — this handler opens no meta.json at all.
+        const src = row.srcRow;
+        const hostKind = src?.host_kind ?? 'tmux';
         return {
             node_id: row.node_id,
             name: row.name,
-            title: meta?.name ?? row.name,
-            description: meta?.description ?? null,
+            title: row.handle ?? row.name,
+            description: row.description ?? null,
             kind: row.kind,
             mode: row.mode,
-            lifecycle: row.lifecycle ?? meta?.lifecycle,
+            lifecycle: row.lifecycle ?? src?.lifecycle,
             status: row.status,
             cwd: row.cwd,
-            profile_id: meta?.profile_id ?? null,
-            parent: meta?.parent ?? null,
+            profile_id: row.profile_id ?? null,
+            parent: src?.parent ?? null,
             created: row.created,
             host_kind: hostKind,
             enterable: hostKind === 'broker',
             attention_count: row.asks,
-            ...(meta?.cycles !== undefined ? { cycles: meta.cycles } : {}),
+            ...(src?.cycles != null ? { cycles: src.cycles } : {}),
             ...(row.mtimeMs !== undefined ? { last_activity: new Date(row.mtimeMs).toISOString() } : {}),
             ctx_tokens: row.ctx_tokens,
             streaming: row.streaming ?? false,
-            jobs_active: meta !== null && isBrokerLive(meta)
+            jobs_active: src !== undefined && isBrokerLive(src)
                 ? activeBackgroundBashJobs(contextDir(row.node_id)).length
                 : 0,
-            waiting_for: meta?.waiting_for ?? null,
+            waiting_for: src?.waiting_for ?? null,
             hanging: (row.hanging ?? null),
             viewed: row.viewed ?? false,
-            final_report: meta?.final_report ?? null,
-            finalized_at: meta?.finalized_at ?? null,
+            final_report: src?.final_report ?? null,
+            finalized_at: src?.finalized_at ?? null,
         };
     });
-    const subscriptions = Object.fromEntries(rows.map((row) => [row.node_id, subscriptionsOf(row.node_id).map((ref) => ref.node_id)]));
+    // Opt 3: one rosterEdges() pass grouped by subscriber, replacing the per-node
+    // subscriptionsOf query. Both are `subscribes_to` edges (active + inactive)
+    // ORDER BY created, so grouping preserves the exact per-node ordering. Rows
+    // with no outgoing edge still get an empty array (iterate rows, not the map).
+    const edgesByFrom = new Map();
+    for (const e of rosterEdges()) {
+        const list = edgesByFrom.get(e.from_id);
+        if (list === undefined)
+            edgesByFrom.set(e.from_id, [e.to_id]);
+        else
+            list.push(e.to_id);
+    }
+    const subscriptions = Object.fromEntries(rows.map((row) => [row.node_id, edgesByFrom.get(row.node_id) ?? []]));
     const body = { generated_at: nowIso(), nodes, subscriptions };
     return { status: 200, body };
 }
@@ -479,6 +524,7 @@ export const canvasRoutes = [
     { method: 'POST', pattern: '/v1/canvas/history/search', handler: handleHistorySearch },
     { method: 'POST', pattern: '/v1/canvas/history/grep', handler: handleHistoryGrep },
     { method: 'GET', pattern: '/v1/canvas/history/read', handler: handleHistoryRead },
+    { method: 'POST', pattern: '/v1/canvas/history/stats', handler: handleHistoryStats },
     { method: 'GET', pattern: '/v1/canvas/snapshot', handler: handleSnapshot },
     { method: 'GET', pattern: '/v1/canvas/roster', handler: handleRoster },
     { method: 'POST', pattern: '/v1/canvas/prune', handler: handlePrune },

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

@@ -249,7 +249,18 @@ async function handleMessage(ctx) {
         try {
             if (hasSidecar)
                 appendSituationalContext(id, sidecar);
-            await deliverLive(id, req.body, [...(hasSidecar ? [sidecar] : []), ...oneShotCards]);
+            await deliverLive(id, req.body, {
+                cards: [...(hasSidecar ? [sidecar] : []), ...oneShotCards],
+                // Same authorship the durable route would record for this send, so a
+                // reader cannot tell live from inbox delivery by the stamp.
+                origin: from === 'human'
+                    ? { type: 'human' }
+                    : {
+                        type: 'runtime',
+                        kind: 'inbox',
+                        entries: [{ ...(from === null ? {} : { from }), kind: 'message', tier }],
+                    },
+            });
             cancelCronsOnWake(id);
             const body = {
                 node_id: id,

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

@@ -156,9 +156,10 @@ function buildRecipe(req, parent, cwd) {
 /** The warm-pool request this create is asking for, or null when it carries
  *  something a pre-booted spare cannot honor. A spare is a bare root with no
  *  kickoff, so anything that shapes the node AT BIRTH — a prompt to run, a
- *  forked conversation, a managed worktree, a caller-pinned node id, a spine
- *  parent — disqualifies it. `kind`, `mode`, `model`, `name`, `situational_context`
- *  and `output_schema` are all applied at claim time and so do not. A terminal
+ *  forked conversation, a managed worktree, a model override, a caller-pinned
+ *  node id, a spine parent — disqualifies it. `kind`, `mode`, `name`,
+ *  `situational_context` and `output_schema` are all applied at claim time and
+ *  so do not. A terminal
  *  root is not warm-compatible: every spare is resident. */
 function warmRequestFor(req, cwd, profileId) {
     if (!warmPoolEnabled())
@@ -171,6 +172,11 @@ function warmRequestFor(req, cwd, profileId) {
         return null;
     if ((req.prompt ?? '') !== '')
         return null;
+    // An explicit override freezes the requested model before the first turn;
+    // applying it to a live spare would switch models after its broker already
+    // launched its default route.
+    if (req.model !== undefined)
+        return null;
     if (req.fork_from !== undefined || req.worktree !== undefined || req.node_id !== undefined)
         return null;
     return {
@@ -196,6 +202,7 @@ async function assertNodeModelChangeRegistered(meta, target, registry) {
         lifecycle: target.lifecycle,
         hasManager: meta.parent !== null,
         model: target.model,
+        modelOverride: true,
         cwd: meta.cwd,
         profileId: meta.profile_id ?? null,
     })).launch;

package/dist/daemon/api/map.js

@@ -28,6 +28,8 @@ export function toNodeSummaryDTO(row) {
     return {
         node_id: row.node_id,
         name: row.name,
+        description: row.description,
+        cycles: row.cycles,
         kind: row.kind,
         mode: row.mode,
         lifecycle: row.lifecycle,

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

@@ -39,7 +39,21 @@ export async function deliverNodeMessage(args) {
             // card; only live delivery needs this message's own envelope.
             await deliverLive(args.node_id, args.runtime === undefined
                 ? args.body
-                : formatCard(args.runtime.kind, args.runtime.facts, args.body));
+                : formatCard(args.runtime.kind, args.runtime.facts, args.body), {
+                // The authorship the durable fallback below would record for this
+                // same send, so the two routes stamp identically.
+                origin: args.from === 'human'
+                    ? { type: 'human' }
+                    : {
+                        type: 'runtime',
+                        kind: 'inbox',
+                        entries: [{
+                                ...(args.from == null ? {} : { from: args.from }),
+                                kind: 'message',
+                                tier: 'normal',
+                            }],
+                    },
+            });
             // The broker acknowledgement is asynchronous to the SQLite guard. Recheck
             // before reporting an engine receipt so a final that committed during the
             // request is not represented as a routable delivery.

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

@@ -24,23 +24,30 @@ import { deliverLive } from '../../core/runtime/interactive-deliver.js';
 import { BrokerUnreachableError } from '../../core/runtime/broker-request.js';
 import { formatCard, PARK_SUMMARY_PROMPT } from '../../shared/generated-context.js';
 import { brokerThresholdsForDaemon } from '../../core/runtime/fleet.js';
+import { readConfig } from '../../core/config.js';
 import { beginPendingPark, consumePendingPark, pendingParkIds, pendingParkStartedAt } from '../park-pending.js';
 import { applyParkEvent, parkEvent } from './live-obligation.js';
-import { envNoDaemonAutostart, envTestParkSummaryGraceMs, envTestUnattendedParkMs, } from '../../shared/env.js';
+import { envNoDaemonAutostart, envTestParkSummaryGraceMs, envTestUnattendedParkMs, envUnattendedParkMs, } from '../../shared/env.js';
 const execFileAsync = promisify(execFile);
 export const YIELD_STALL_GRACE_MS = 3 * 60_000;
 const KILL_ESCALATE_MS = 20_000;
 export const WEDGE_QUIET_MS = 20 * 60_000;
 export const WEDGE_CPU_MAX_PERCENT = 2;
 const OVER_CAP_WARN_THROTTLE_MS = 5 * 60_000;
-const DEFAULT_UNATTENDED_PARK_MS = 15 * 60_000;
 // Longer than a summary turn and shorter than the unattended clock itself, so a
 // stuck parking turn cannot hold a broker for a whole extra clock period.
 const DEFAULT_PARK_SUMMARY_GRACE_MS = 5 * 60_000;
 export function unattendedParkMsForDaemon() {
+    // The `CRTR_UNATTENDED_PARK_MS` override wins whenever set, autostart or not.
+    const envOverride = envUnattendedParkMs();
+    if (envOverride !== undefined)
+        return envOverride;
+    // Otherwise the user-scope config value is the base (default 15 min), with the
+    // test-only override winning only when autostart is disabled.
+    const configured = readConfig('user').lifecycle.unattendedParkMs;
     if (!envNoDaemonAutostart())
-        return DEFAULT_UNATTENDED_PARK_MS;
-    return envTestUnattendedParkMs() ?? DEFAULT_UNATTENDED_PARK_MS;
+        return configured;
+    return envTestUnattendedParkMs() ?? configured;
 }
 export function parkSummaryGraceMsForDaemon() {
     return envTestParkSummaryGraceMs() ?? DEFAULT_PARK_SUMMARY_GRACE_MS;
@@ -149,6 +156,11 @@ export class BrokerSupervisionReconciler {
         ctx.lifecycle.registerDetached(warning);
     }
     async run(now, ctx) {
+        // Resolve the unattended-park interval once per tick — it reads user
+        // config.json, so a per-broker read would add one file read per eligible
+        // broker and could apply different values within one tick after a config
+        // write (mirrors how `runFleetPreamble` snapshots the broker thresholds).
+        const unattendedParkMs = unattendedParkMsForDaemon();
         for (const row of ctx.rows) {
             const id = row.node_id;
             const entry = ctx.fleet.get(id);
@@ -161,7 +173,7 @@ export class BrokerSupervisionReconciler {
                     this.handleYieldStall(row, entry.pid, now);
                     await this.handleWedgeDetection(id, entry.pid, row.pi_pid_identity, now);
                     this.handleFatalFault(id);
-                    this.handleUnattendedParking(id, getNode(id), entry.pid, now, ctx);
+                    this.handleUnattendedParking(id, getNode(id), entry.pid, now, ctx, unattendedParkMs);
                 }
                 catch (err) {
                     this.unattendedSince.delete(id);
@@ -211,7 +223,7 @@ export class BrokerSupervisionReconciler {
             return true;
         return hasUnseenWakeMail(id);
     }
-    handleUnattendedParking(id, row, livePid, now, ctx) {
+    handleUnattendedParking(id, row, livePid, now, ctx, unattendedParkMs) {
         // An unclaimed warm-pool spare is not a conversation: the booted broker it
         // holds IS its whole value, and nobody is meant to be attending it. Its
         // lifetime belongs to `reapStaleSpares` (warm-pool.ts) and its own TTL, so
@@ -269,7 +281,7 @@ export class BrokerSupervisionReconciler {
             this.unattendedSince.set(id, now);
             return;
         }
-        if (now - since < unattendedParkMsForDaemon())
+        if (now - since < unattendedParkMs)
             return;
         this.unattendedSince.delete(id);
         const event = parkEvent(id, row.lifecycle);
@@ -302,7 +314,9 @@ export class BrokerSupervisionReconciler {
      *  the node is working again and its clock simply restarts. */
     async requestParkSummary(id) {
         try {
-            const route = await deliverLive(id, formatCard('park', {}, PARK_SUMMARY_PROMPT));
+            const route = await deliverLive(id, formatCard('park', {}, PARK_SUMMARY_PROMPT), {
+                origin: { type: 'runtime', kind: 'park' },
+            });
             if (route === 'steer' && consumePendingPark(id))
                 return;
             emitEvent({
@@ -361,7 +375,10 @@ export class BrokerSupervisionReconciler {
                 if (client === '')
                     return;
                 try {
-                    await execFileAsync('tmux', ['display-message', '-d', '10000', '-c', client, msg], {
+                    // `-C` keeps the client's panes painting while the warning sits in
+                    // its status line; without it every attached viewer freezes for the
+                    // full 10s. The plain retry below covers a tmux without the flag.
+                    await execFileAsync('tmux', ['display-message', '-C', '-d', '10000', '-c', client, msg], {
                         encoding: 'utf8',
                         timeout: 2000,
                     });

package/dist/daemon/reconcilers/live-obligation.d.ts

@@ -11,10 +11,17 @@ export declare function hasLiveObligation(nodeId: string): boolean;
  *  Deferred mail deliberately does not count: it rides the node's next natural
  *  cycle rather than causing one. */
 export declare function hasPendingWake(nodeId: string): boolean;
+/** Whether a person is looking at this node right now: a focused viewer pane,
+ *  or a broker client that declared itself attending. A client that hellos with
+ *  `attends: false` is a system observer and deliberately does not count, which
+ *  is how Northlight Core identifies itself — so an open product page is
+ *  invisible here, while crouter's own local and remote viewers are not. */
+export declare function hasHumanViewer(nodeId: string): boolean;
 /** What parking an unattended node actually amounts to — the one rule both the
  *  live-broker park clock and the lifecycle tick apply.
  *
- *  `release` — something can still wake it, so parking is a pause.
+ *  `release` — something can still wake it, or a person is watching it, so
+ *              parking is a pause.
  *  `park`    — a resident with nothing left to wake it has completed its
  *              conversation, and the row becomes prunable history. The live
  *              clock asks it for a summary turn first; this verdict is what

package/dist/daemon/reconcilers/live-obligation.js

@@ -28,9 +28,26 @@ export function hasPendingWake(nodeId) {
         return true;
     if (hasUnseenWakeMail(nodeId))
         return true;
+    return hasHumanViewer(nodeId);
+}
+/** Whether a person is looking at this node right now: a focused viewer pane,
+ *  or a broker client that declared itself attending. A client that hellos with
+ *  `attends: false` is a system observer and deliberately does not count, which
+ *  is how Northlight Core identifies itself — so an open product page is
+ *  invisible here, while crouter's own local and remote viewers are not. */
+export function hasHumanViewer(nodeId) {
     return focusOf(nodeId) !== null || hasAttachedBrokerViewers(nodeId);
 }
 export function parkEvent(nodeId, lifecycle) {
+    // Attendance defeats unattended parking outright: the grace exists to settle
+    // a conversation nobody is in, and terminalizing a node somebody is watching
+    // is the one outcome the grace must never reach. The live clock resets its
+    // own timer on the same test, so this covers the paths that reach a verdict
+    // without it — the settlement re-check after a parking turn, and the tick's
+    // sweep over already-idle rows. The live clock discards its timer on that
+    // same reset, so parking resumes a full grace after the last viewer detaches.
+    if (hasHumanViewer(nodeId))
+        return 'release';
     if (hasLiveObligation(nodeId))
         return 'release';
     if (lifecycle === 'resident')

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

@@ -17,6 +17,7 @@
 import { envNodeId, envProfileId, envWatcherDebounceMs, envWatcherTickMs } from '../shared/env.js';
 import { coalesceBrokerInbox, entryCards, readBrokerCanceledEntryIds, readBrokerCursor, readBrokerInboxSince, reportRefNodeId, } from '../core/runtime/broker/inbox.js';
 import { advanceBrokerInboxCursor, brokerExtensionState } from '../core/runtime/broker/daemon-ops.js';
+import { announceMessageOrigin } from '../core/runtime/stamp/channel.js';
 import { captureGoalIfAbsent, generateAndCommitInitialName } from './broker-local.js';
 import { emitEvent } from '../core/events/emit.js';
 import { errorClassFromError } from '../core/events/errors.js';
@@ -97,6 +98,26 @@ function emitStoredBestEffort(operationId, input) {
         // Delivery state remains authoritative when its observational record cannot append.
     }
 }
+/** The authorship stamped onto a delivered message. A person's words arrive
+ *  verbatim and are stamped as theirs — no channel, because the durable inbox
+ *  is not a transport a reader can attribute. Every other delivery is the
+ *  runtime's inbox card, carrying each entry's attribution as the coalescer
+ *  received it. */
+function deliveryOrigin(delivery) {
+    if (delivery.kind === 'human')
+        return { type: 'human' };
+    return {
+        type: 'runtime',
+        kind: 'inbox',
+        entries: delivery.entries.map((entry) => ({
+            ...(entry.from === null ? {} : { from: entry.from }),
+            ...(entry.from_name === undefined ? {} : { fromName: entry.from_name }),
+            kind: entry.kind,
+            tier: entry.tier,
+            ...(entry.ref === undefined ? {} : { ref: entry.ref }),
+        })),
+    };
+}
 function deliveryFacts(entries, channel) {
     if (entries.length === 0)
         throw new Error(`cannot create an empty ${channel} delivery`);
@@ -729,7 +750,7 @@ class CanvasInboxWatcher {
      *  unit: a throw anywhere requeues the whole entry, so a retry may repeat a
      *  card already handed off (context is restatable; the human's body is not,
      *  and it is sent last). */
-    sendVisible(entries, cards, content, route, stage) {
+    sendVisible(entries, cards, content, origin, route, stage) {
         return this.sendDelivery('visible', entries, () => {
             if (route !== 'idle' && route !== 'steer' && route !== 'followUp') {
                 throw new Error(`visible send requested for non-send route ${route}`);
@@ -737,6 +758,10 @@ class CanvasInboxWatcher {
             for (const card of cards) {
                 this.pi.sendMessage({ customType: SITUATIONAL_CONTEXT_CUSTOM_TYPE, content: card, display: true }, route === 'idle' ? {} : { deliverAs: route });
             }
+            // Claimed by the stamp writer against the message pi persists, so a send
+            // that throws here leaves an announcement nobody claims rather than one
+            // that mislabels a later message.
+            announceMessageOrigin(content, origin);
             if (route === 'idle') {
                 const start = brokerIdleTurnStart();
                 if (start === undefined)
@@ -803,7 +828,7 @@ class CanvasInboxWatcher {
         if (!this.canMutate())
             return { inactive: true, requeueEntryIds };
         if (delivery !== undefined) {
-            const result = this.sendVisible(delivery.entries, delivery.cards, delivery.text, route, stage);
+            const result = this.sendVisible(delivery.entries, delivery.cards, delivery.text, deliveryOrigin(delivery), route, stage);
             if (result === 'inactive')
                 return { inactive: true, requeueEntryIds };
             if (result === 'failed') {

package/dist/pi-extensions/canvas-recap.js

@@ -41,6 +41,7 @@
 import { envNodeId, envRecapIdleMs } from '../shared/env.js';
 import { brokerExtensionState } from '../core/runtime/broker/daemon-ops.js';
 import { generateRecap } from '../core/runtime/recap.js';
+import { writeNodeRecap } from '../core/canvas/node-recap.js';
 import { isReviewBoundary } from '../core/runtime/session-visibility.js';
 import { editorLabelForBrokerNode } from '../core/runtime/broker-extension-render.js';
 import { generateAndCommitRecapName, readRoadmap } from './broker-local.js';
@@ -315,6 +316,9 @@ export function registerCanvasRecap(pi, recapGenerator = generateRecap, nameRege
             // Automatic work paints only while its idle snapshot remains current.
             if ((!manual && activityVersion !== snapshotVersion) || !canPaint())
                 return;
+            // Persist what we are about to paint. The widget dies with the broker; the
+            // file is what `crtr canvas browse` shows for a dormant node.
+            writeNodeRecap(nodeId, briefing);
             recapShown = true;
             recapStale = activityVersion !== snapshotVersion;
             showRecap(briefing);

package/dist/pi-extensions/canvas-stamp.d.ts

@@ -0,0 +1,14 @@
+interface StampCtxLike {
+    sessionManager: {
+        /** Whole file, not the active branch: a session stamp on an abandoned
+         *  branch still describes this file's owner. */
+        getEntries: () => unknown[];
+    };
+}
+interface PiLike {
+    on: (event: 'session_start' | 'message_end', handler: (event: unknown, ctx: StampCtxLike) => void | Promise<void>) => void;
+    appendEntry: (customType: string, data?: unknown) => void;
+}
+/** Register the stamp writer. */
+export declare function registerCanvasStamp(pi: PiLike): void;
+export default registerCanvasStamp;

package/dist/pi-extensions/canvas-stamp.js

@@ -0,0 +1,77 @@
+// canvas-stamp.ts — the sole writer of `crtr-stamp` entries.
+//
+// Two records land in the session jsonl. A SESSION stamp names the node and the
+// crtr release that own the file, appended at session start only when the
+// latest one on disk disagrees — which covers a fresh session, a fork (whose
+// copied history still carries the source node's stamp), a new cycle, and a
+// runtime upgrade mid-node, without a rule per case. A MESSAGE stamp records
+// where one user message came from, joined to it by the message's own
+// timestamp.
+//
+// Every user message is stamped; an origin appears only when a delivery seam
+// announced one (absence means unknown, never a guess). An assistant message is
+// stamped only when an `ext` contribution is pending, so an ordinary turn costs
+// no line.
+//
+// Ordering note: pi runs message_end handlers BEFORE it persists the finalized
+// message, so the stamp is written as that message's structural parent. The
+// join is by `msgTs`, so tree position carries no meaning here.
+import { envNodeId } from '../shared/env.js';
+import { crtrVersion } from '../shared/crtr-version.js';
+import { claimMessageOrigin, drainStampExt, hasPendingStampExt, } from '../core/runtime/stamp/channel.js';
+import { CRTR_STAMP_CUSTOM_TYPE, latestSessionStamp, STAMP_SCHEMA_VERSION, } from '../core/runtime/stamp/protocol.js';
+/** Plain text of a message's content (string or content blocks). */
+function messageText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .filter((block) => typeof block === 'object' && block !== null && typeof block.text === 'string')
+            .map((block) => block.text)
+            .join('\n');
+    }
+    return '';
+}
+function envelope(kind, payload) {
+    const ext = drainStampExt();
+    return {
+        v: STAMP_SCHEMA_VERSION,
+        kind,
+        payload,
+        ...(ext === undefined ? {} : { ext }),
+    };
+}
+/** Register the stamp writer. */
+export function registerCanvasStamp(pi) {
+    pi.on('session_start', (_event, ctx) => {
+        const node = envNodeId();
+        if (node === undefined || node.trim() === '')
+            return;
+        const crtr = crtrVersion();
+        const latest = latestSessionStamp(ctx.sessionManager.getEntries());
+        if (latest !== null && latest.payload.node === node && latest.payload.crtr === crtr)
+            return;
+        pi.appendEntry(CRTR_STAMP_CUSTOM_TYPE, envelope('session', { node, crtr }));
+    });
+    pi.on('message_end', (event) => {
+        const message = event?.message;
+        if (message === undefined || message === null)
+            return;
+        if (typeof message.timestamp !== 'number')
+            return;
+        const msgTs = message.timestamp;
+        if (message.role === 'user') {
+            const origin = claimMessageOrigin(messageText(message.content));
+            pi.appendEntry(CRTR_STAMP_CUSTOM_TYPE, envelope('message', {
+                msgTs,
+                ...(origin === null ? {} : { origin }),
+            }));
+            return;
+        }
+        // Any other message earns a line only for a pending contribution.
+        if (!hasPendingStampExt())
+            return;
+        pi.appendEntry(CRTR_STAMP_CUSTOM_TYPE, envelope('message', { msgTs }));
+    });
+}
+export default registerCanvasStamp;

package/dist/pi-extensions/canvas-stophook.js

@@ -33,6 +33,7 @@ import { activeBackgroundBashJobs } from '../core/bash-jobs.js';
 import { CONTEXT_NUDGE_CUSTOM_TYPE, formatCard } from '../shared/generated-context.js';
 import { isReviewBoundary } from '../core/runtime/session-visibility.js';
 import { runRefreshAbort } from '../core/runtime/broker/extension-abort.js';
+import { announceMessageOrigin } from '../core/runtime/stamp/channel.js';
 /** Condense a tool call into one short line for the activity cue. Picks the most
  *  identifying arg (command / path / pattern / description), collapses whitespace,
  *  and hard-caps the length so a giant bash command can't bloat telemetry.json. */
@@ -271,6 +272,7 @@ export function registerCanvasStophook(pi) {
     };
     const enactSettleDirective = (directive, ctx) => {
         if (directive.action === 'reprompt') {
+            announceMessageOrigin(directive.prompt, { type: 'runtime', kind: 'stop-guard' });
             pi.sendUserMessage(directive.prompt, { deliverAs: 'followUp' });
             return;
         }
@@ -566,6 +568,7 @@ export function registerCanvasStophook(pi) {
                 firedBands.add(at);
                 const note = formatCard('context-nudge', {}, steerNote(at, node.lifecycle, node.mode));
                 if (runContinues) {
+                    announceMessageOrigin(note, { type: 'runtime', kind: 'context-nudge' });
                     pi.sendUserMessage(note, { deliverAs: 'steer' });
                 }
                 else {

package/dist/shared/__tests__/env-boundary.test.js

@@ -17,6 +17,7 @@ const MIGRATED_VARS = [
     'CRTR_PROFILE_ID',
     'CRTR_NODE_CWD',
     'CRTR_MODEL_INTENT',
+    'CRTR_MODEL_EXACT',
     'CRTR_HOME',
     'CRTR_STREAM_WATCHDOG_MS',
     'CRTR_WATCHER_TICK_MS',
@@ -35,6 +36,7 @@ const MIGRATED_VARS = [
     'CRTR_WARN_LIVE_BROKERS',
     'CRTR_TEST_UNATTENDED_PARK_MS',
     'CRTR_TEST_PARK_SUMMARY_GRACE_MS',
+    'CRTR_UNATTENDED_PARK_MS',
 ];
 // Matches `process.env['VAR']`, `process.env.VAR`, or `process.env[\`VAR\`]`
 // for exactly one of MIGRATED_VARS — not a longer name that merely starts
@@ -53,8 +55,8 @@ const EXEMPTIONS = new Map([
     ],
     [
         'core/runtime/broker.ts',
-        "clears CRTR_MODEL_INTENT via `delete process.env[...]` — a mutation, " +
-            'not a read, so it stays here per shared/env.ts\'s header comment.',
+        "clears CRTR_MODEL_INTENT and sets CRTR_MODEL_EXACT via process.env — mutations, " +
+            'not reads, so they stay here per shared/env.ts\'s header comment.',
     ],
 ]);
 function tsFilesUnder(dir) {

package/dist/shared/crtr-version.d.ts

@@ -0,0 +1,2 @@
+/** The running crouter package version (`package.json` `version`). */
+export declare function crtrVersion(): string;

package/dist/shared/crtr-version.js

@@ -0,0 +1,18 @@
+// The installed crtr release string, read once per process from the package
+// manifest. Callers that record a version into durable state (the session
+// stamp) and callers that compare against npm (self-update) read this one
+// implementation.
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+let cached = null;
+/** The running crouter package version (`package.json` `version`). */
+export function crtrVersion() {
+    if (cached !== null)
+        return cached;
+    // src|dist/shared/crtr-version.ts → up to src|dist/ → up to pkg root
+    const root = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+    const parsed = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+    cached = parsed.version;
+    return cached;
+}