@north-light/crouter 0.3.263 → 0.3.270

package/dist/core/runtime/model-swap.js

@@ -19,8 +19,8 @@ import { oneShotControllerRequest } from './broker-request.js';
 /** True when the node's broker engine is reachable: its recorded pid is alive
  *  AND its view.sock exists. Both are required — a dead pid with a stale socket,
  *  or a live pid mid-boot before it binds the socket, is NOT a live broker. */
-export function isBrokerLive(meta) {
-    return isPidAlive(meta.pi_pid) && existsSync(viewSocketPath(meta.node_id));
+export function isBrokerLive(node) {
+    return isPidAlive(node.pi_pid) && existsSync(viewSocketPath(node.node_id));
 }
 /** Swap a LIVE node's model over its view.sock. Connects as a controller,
  *  sends `set_model`, and resolves with the broker-resolved durable spec from its
@@ -49,9 +49,10 @@ export function setModelLive(nodeId, spec, pinned) {
 }
 /** Persist a model choice into a DORMANT node's durable recipe — mirrors exactly
  *  what the broker's persistModelChoice writes on a live switch: `model_override`
- *  (so polymorphs preserve it via buildLaunchSpec) and `launch.model` (the recipe
- *  buildPiArgv replays on revive). `spec` must already be a concrete `provider/id`
- *  (normalizeModel maps tiers/aliases; a bare substring cannot resolve offline).
+ *  (so polymorphs preserve it via buildLaunchSpec), `launch.model`, and its
+ *  exact-consult marker (the recipe buildPiArgv replays on revive). `spec` must
+ *  already be a concrete `provider/id` (normalizeModel maps tiers/aliases; a bare
+ *  substring cannot resolve offline).
  *  `pinned` is the durable-pin decision for this change — decided by the CALLER
  *  from the RAW pre-normalize token, never re-derived here from `spec`'s shape
  *  (a concrete `spec` always reads as "pinned", which would wrongly re-pin a
@@ -66,6 +67,7 @@ export function updateModelRecipe(meta, spec, pinnedOverride, userSelected) {
                 return {
                     ...rest,
                     model: spec,
+                    modelExact: true,
                     ...(pinnedOverride !== undefined ? { modelProviderPinned: pinnedOverride } : {}),
                     env: remainingEnv,
                 };

package/dist/core/runtime/node-read.d.ts

@@ -32,6 +32,8 @@ export interface NodeMessagesPageRead {
     messages: unknown[];
     /** Stable session-entry ids aligned 1:1 with `messages`. */
     messageIds?: string[];
+    /** Presentation visibility aligned 1:1 with `messages`. */
+    messageVisibility: Array<'visible' | 'internal'>;
     nextCursor: string | null;
 }
 export interface NodeMessagesPageOptions {

package/dist/core/runtime/node-read.js

@@ -18,7 +18,7 @@ import { SessionManager } from './broker-sdk.js';
 import { openModelRegistry } from './model-registry.js';
 import { BUILTIN_SLASH_COMMANDS } from './pi-vendored.js';
 import { cycleAwareMessages } from './session-cycles.js';
-import { visibleMessages } from './session-visibility.js';
+import { projectTranscript } from './session-visibility.js';
 import { normalizeToolGroupSummaryRecord } from '../../shared/tool-groups.js';
 /** A session `.jsonl` records only `{ provider, modelId }` — pi never persists a
  *  whole `Model`. Resolve it back through pi's own registry so a dormant
@@ -149,10 +149,10 @@ function readToolGroupSummaries(nodeId) {
         return {};
     }
 }
-/** Reconstruct the visible message history from a stable at-rest session copy.
+/** Reconstruct transcript messages from a stable at-rest session copy.
  * Both snapshot and paged reads use this one path so their histories cannot
  * diverge. */
-async function reconstructVisibleMessages(nodeId) {
+async function reconstructTranscript(nodeId) {
     const node = getNode(nodeId);
     if (node === null) {
         throw new InputError({ error: 'not_found', message: `no node: ${nodeId}`, field: 'id', next: 'List nodes with `crtr node inspect list`.' });
@@ -174,7 +174,10 @@ async function reconstructVisibleMessages(nodeId) {
         }
         const identified = reconstructed === undefined
             ? undefined
-            : visibleMessages(reconstructed, { boundaryReviewId: node.review_binding?.review_id });
+            : projectTranscript(reconstructed, {
+                boundaryReviewId: node.review_binding?.review_id,
+                sessionEntries: manager.getEntries(),
+            });
         const messages = identified?.map(({ message }) => message) ?? context.messages;
         return {
             sessionFile,
@@ -228,10 +231,13 @@ function encodeMessagesCursor(before) {
 /** Reconstruct a persisted session without launching its broker. Backs the
  * machine-readable snapshot endpoint and the human transcript render. */
 export async function readNodeSnapshot(nodeId) {
-    const read = await reconstructVisibleMessages(nodeId);
+    const read = await reconstructTranscript(nodeId);
     const snapshot = {
         messages: read.messages,
         ...(read.identified === undefined ? {} : { messageIds: read.identified.map(({ id }) => id) }),
+        messageVisibility: read.identified?.map(({ visibility }) => visibility)
+            ?? read.messages.map(() => 'visible'),
+        turnVisibility: 'visible',
         stats: statsFromMessages(read.messages, read.sessionId, read.sessionFile),
         // pi's `get_state` shape (RpcSessionState), reconstructed offline: the
         // live-only fields report their at-rest values (nothing is streaming or
@@ -284,15 +290,16 @@ export async function readNodeMessagesPage(nodeId, { cursor, limit = 200 }) {
     // transcript read is how a UI opens a new conversation. Only this paged read
     // can answer honestly — `/snapshot` would have to invent the engine state a
     // never-run node does not have, so it and the raw `/session` export still
-    // reject the same state through `reconstructVisibleMessages`.
+    // reject the same state through `reconstructTranscript`.
     // Same shape a session-file-backed empty read produces: `messageIds` stays
     // aligned 1:1 with `messages` (an absent `message_ids` would claim this read
     // cannot identify entries, which is a different statement than "there are
     // none"), and `nextCursor: null` is the same end-of-history marker an
     // exhausted backward walk returns.
-    if (readableSessionFile(nodeId) === null)
-        return { messages: [], messageIds: [], nextCursor: null };
-    const { messages, identified } = await reconstructVisibleMessages(nodeId);
+    if (readableSessionFile(nodeId) === null) {
+        return { messages: [], messageIds: [], messageVisibility: [], nextCursor: null };
+    }
+    const { messages, identified } = await reconstructTranscript(nodeId);
     const before = cursor === undefined ? messages.length : decodeMessagesCursor(cursor, messages.length);
     let start = Math.max(0, before - limit);
     while (start > 0
@@ -305,6 +312,8 @@ export async function readNodeMessagesPage(nodeId, { cursor, limit = 200 }) {
     return {
         messages: page?.map(({ message }) => message) ?? messages.slice(start, before),
         ...(page === undefined ? {} : { messageIds: page.map(({ id }) => id) }),
+        messageVisibility: page?.map(({ visibility }) => visibility)
+            ?? messages.slice(start, before).map(() => 'visible'),
         nextCursor: start === 0 ? null : encodeMessagesCursor(start),
     };
 }

package/dist/core/runtime/promote.js

@@ -23,6 +23,7 @@ function reshapeInputs(nodeId, opts) {
         node, kind, mode, lifecycle, profileId,
         launchOpts: {
             lifecycle, hasManager: node.parent !== null, model: opts.model ?? node.model_override ?? undefined,
+            modelOverride: opts.model !== undefined,
             modelProviderPinned: opts.model === undefined ? node.launch?.modelProviderPinned : undefined,
             modelIntent: opts.model === undefined ? node.launch?.modelIntent : undefined,
             modelExact: opts.model === undefined ? node.launch?.modelExact : undefined,
@@ -36,7 +37,7 @@ function persistReshape(nodeId, opts, input, launch, beforePersist) {
     return updateNode(nodeId, {
         kind: input.kind, mode: input.mode, lifecycle: input.lifecycle, profile_id: input.profileId, launch,
         ...(carriesDefaultHandle ? { name: input.kind } : {}),
-        ...(opts.model !== undefined ? { model_override: opts.model } : {}),
+        ...(opts.model !== undefined ? { model_override: launch?.model ?? opts.model } : {}),
     });
 }
 /** Synchronous reshape for CLI callers outside the daemon. */

package/dist/core/runtime/reset.js

@@ -85,9 +85,11 @@ export async function relaunchRoot(oldId, deps = {}) {
         lifecycle: 'resident',
         hasManager: false,
         model: old.model_override ?? undefined,
-        // A `/new` relaunch carries no new --model — preserve the old root's pin
-        // verbatim rather than re-deriving it from model_override's shape.
+        // A `/new` relaunch carries no new --model — preserve the old root's routing
+        // contract verbatim rather than re-deriving it from model_override's shape.
         modelProviderPinned: old.launch?.modelProviderPinned,
+        modelIntent: old.launch?.modelIntent,
+        modelExact: old.launch?.modelExact,
         // The OLD root's cwd + profile, not this process's ambient scope — the
         // relaunch is the same seat, so profile-scope kind defaults keep applying.
         cwd: old.cwd,

package/dist/core/runtime/revive-all.d.ts

@@ -54,4 +54,4 @@ export interface ReviveAllResult {
  *  no-op), so this is a thin orchestrator over `listDisconnected`: revive each
  *  with resume:true. One failing node never aborts the sweep — its error is
  *  collected and the rest proceed. */
-export declare function reviveAll(): ReviveAllResult;
+export declare function reviveAll(): Promise<ReviveAllResult>;

package/dist/core/runtime/revive-all.js

@@ -84,7 +84,7 @@ export function listDisconnected() {
  *  no-op), so this is a thin orchestrator over `listDisconnected`: revive each
  *  with resume:true. One failing node never aborts the sweep — its error is
  *  collected and the rest proceed. */
-export function reviveAll() {
+export async function reviveAll() {
     const result = { revived: [], failed: [], frozen: [] };
     for (const meta of listDisconnected()) {
         try {
@@ -93,7 +93,7 @@ export function reviveAll() {
             // whole canvas is the likeliest way to meet the cap, and every node in it
             // is one the daemon wants back: freeze the overflow and let the tick
             // bring them up as slots free.
-            const outcome = reviveNode(meta.node_id, { resume: true, recovery: true, capacity: 'freeze' }).outcome;
+            const outcome = (await reviveNode(meta.node_id, { resume: true, recovery: true, capacity: 'freeze' })).outcome;
             if (outcome === 'frozen')
                 result.frozen.push(meta.node_id);
             else

package/dist/core/runtime/revive.d.ts

@@ -87,10 +87,10 @@ export type ReviveCapacityPolicy = 'freeze' | 'refuse';
  *  Throws if the node does not exist. All other failures propagate as-is —
  *  callers (daemon, command) decide how to handle.
  */
-export declare function reviveNode(nodeId: string, opts: ReviveOptions): ReviveResult;
+export declare function reviveNode(nodeId: string, opts: ReviveOptions): Promise<ReviveResult>;
 /** The attach-specific entry to the revive boundary. A focus viewer may decline
  * to wake an exact parked resident while preserving the ordinary activating
  * attach default. The fleet check and parked decision are synchronous with the
  * launch below, so an already-running broker wins before dormancy is observed. */
-export declare function decideAttachRevive(nodeId: string, opts: ReviveOptions, wakeParked: boolean): AttachReviveDecision;
+export declare function decideAttachRevive(nodeId: string, opts: ReviveOptions, wakeParked: boolean): Promise<AttachReviveDecision>;
 export {};

package/dist/core/runtime/revive.js

@@ -34,6 +34,7 @@ import { buildPiArgv } from './launch.js';
 import { buildReviveKickoff, drainBearings, readGoal, readYieldMessage, RUNTIME_RESTART_CONTINUATION } from './kickoff.js';
 import { readRoadmap } from './roadmap.js';
 import { hasUnseenWakeMail } from '../feed/inbox.js';
+import { encodeKickoffOrigin, KICKOFF_ORIGIN_ENV } from './stamp/protocol.js';
 import { headlessBrokerHost } from './host.js';
 import { boundFleet, brokerCapReached, brokerThresholdsForDaemon } from './fleet.js';
 import { clearFault, beginBootFaultAttempt } from './fault.js';
@@ -42,6 +43,9 @@ import { rootOfSpine } from './nodes.js';
 import { isReviewCompanionBound } from '../review/companion.js';
 import { assertProfileActive } from '../profiles/manifest.js';
 import { isPidAlive } from '../canvas/pid.js';
+import { crtrHome, contextDir, ensureNodeDirs, jobDir, nodeDir, reportsDir } from '../canvas/paths.js';
+import { discoverLifecycleHookRegistry } from '../command-hooks/discovery.js';
+import { invokeLifecycleHooks } from '../command-hooks/transport/exec-lifecycle.js';
 // resumeArgs — which session source a revive resumes from
 /** Pick the `--session` source for a revive. Both resume=true (a true resume)
  *  and resume=false (a refresh-yield) resume by the absolute session-file path
@@ -139,8 +143,8 @@ export function hasFreshGroundState(nodeId) {
  *  Throws if the node does not exist. All other failures propagate as-is —
  *  callers (daemon, command) decide how to handle.
  */
-export function reviveNode(nodeId, opts) {
-    const decision = decideRevive(nodeId, opts, true);
+export async function reviveNode(nodeId, opts) {
+    const decision = await decideRevive(nodeId, opts, true);
     if (decision.parked)
         throw new Error(`reviveNode: internal parked decision for activating revive ${nodeId}`);
     return decision.result;
@@ -149,10 +153,10 @@ export function reviveNode(nodeId, opts) {
  * to wake an exact parked resident while preserving the ordinary activating
  * attach default. The fleet check and parked decision are synchronous with the
  * launch below, so an already-running broker wins before dormancy is observed. */
-export function decideAttachRevive(nodeId, opts, wakeParked) {
+export async function decideAttachRevive(nodeId, opts, wakeParked) {
     return decideRevive(nodeId, opts, wakeParked);
 }
-function decideRevive(nodeId, opts, wakeParked) {
+async function decideRevive(nodeId, opts, wakeParked) {
     let meta = getNode(nodeId);
     if (meta === null) {
         throw new Error(`reviveNode: unknown node ${nodeId}`);
@@ -168,13 +172,10 @@ function decideRevive(nodeId, opts, wakeParked) {
         throw new Error(`reviveNode: refusing to revive ${nodeId} — its finalization latch is set (final_report=${meta.final_report}). A final landed between the caller's reopen-gate check and this revive; re-run with --reopen if this retask is still wanted.`);
     }
     assertProfileActive(meta.profile_id);
-    // Double-launch guard: a fleet entry IS liveness (design D-1). reviveNode
-    // runs fully SYNCHRONOUSLY on the daemon thread — this check, the launch,
-    // and the fleet registration inside `headlessBrokerHost.launch` complete
-    // with no awaited gap, so no second contender can interleave past this
-    // check before the first's registration lands. A node with a live fleet
-    // entry was already revived by another path — re-launching would put a
-    // SECOND broker on the same session file.
+    // Double-launch guard: a fleet entry IS liveness (design D-1). A lifecycle
+    // hook is awaited before the broker can register, so its reservation also
+    // owns the node while launch is in flight; a second contender must not cross
+    // that awaited gap and start a second broker on the same session file.
     const fleet = boundFleet();
     if (fleet.has(nodeId)) {
         // The node is already running, but the ROW may still say terminal: a reopen
@@ -192,6 +193,17 @@ function decideRevive(nodeId, opts, wakeParked) {
             },
         };
     }
+    if (fleet.isClaimed(nodeId)) {
+        return {
+            parked: false,
+            result: {
+                window: null,
+                session: meta.tmux_session ?? null,
+                resumed: false,
+                outcome: 'already-live',
+            },
+        };
+    }
     // Focus may establish a viewport without establishing an engine. This exact
     // row has no final latch and no fleet owner; returning before reservation is
     // what keeps lifecycle, cycle count, pid, inbox cursor, and session untouched.
@@ -235,7 +247,7 @@ function decideRevive(nodeId, opts, wakeParked) {
         };
     }
     try {
-        return { parked: false, result: launchRevive(nodeId, meta, opts) };
+        return { parked: false, result: await launchRevive(nodeId, meta, opts) };
     }
     finally {
         // The slot is either consumed by the fleet registration inside `launch`
@@ -247,7 +259,7 @@ function decideRevive(nodeId, opts, wakeParked) {
 }
 /** The launch itself, from the cwd preflight through `recordPid`. Split out so
  *  the capacity claim above has exactly one release path around it. */
-function launchRevive(nodeId, meta, opts) {
+async function launchRevive(nodeId, meta, opts) {
     // Preflight, before any state mutation below: a recorded cwd that no longer
     // exists (e.g. a closed managed worktree whose tombstone dir was later
     // reaped) can never host a launch. Fail loud with a typed, user-visible
@@ -266,6 +278,10 @@ function launchRevive(nodeId, meta, opts) {
             next,
         });
     }
+    // This is the same durable distinction used to decide between a birth prompt
+    // and a revive kickoff below. Compute it before launch mutations so a stale
+    // session identity cannot make an ordinary fresh revive look like a birth.
+    const isBirth = isUnstartedBirth(nodeId);
     // Lazy host_kind coerce (§C): every launch now uses the broker host. Persist
     // that identity only after this call has passed the no-op liveness guard.
     if (meta.host_kind !== 'broker') {
@@ -367,12 +383,23 @@ function launchRevive(nodeId, meta, opts) {
     // unchanged (empty for true-fresh, both set for cycling) so buildPiArgv emits
     // the right argv either way.
     let inv;
+    // The provenance of whatever kickoff this branch composes, handed to the
+    // broker process through inv.env below. A promptless launch announces
+    // nothing — there is no message to stamp.
+    let kickoffOrigin = null;
+    const birthOrigin = () => ({
+        type: 'runtime',
+        kind: 'kickoff',
+        ...(meta.spawned_by != null && meta.spawned_by !== '' ? { spawnedBy: meta.spawned_by } : {}),
+    });
     if (forkBirthPending) {
         const goal = readGoal(nodeId);
         inv = buildPiArgv(meta, {
             forkFrom: forkSourceFile,
             ...(goal != null && goal !== '' ? { prompt: goal } : {}),
         });
+        if (goal != null && goal !== '')
+            kickoffOrigin = birthOrigin();
         initializeForkContextExposure(nodeId, findNodeBySessionFile(forkSourceFile)?.node_id ?? null);
     }
     else if (resuming) {
@@ -380,6 +407,9 @@ function launchRevive(nodeId, meta, opts) {
             ...resume,
             ...(opts.wakeReason === 'runtime-restart-abort' ? { prompt: RUNTIME_RESTART_CONTINUATION } : {}),
         });
+        if (opts.wakeReason === 'runtime-restart-abort') {
+            kickoffOrigin = { type: 'runtime', kind: 'restart-continuation' };
+        }
     }
     else if (!hasSessionPath &&
         // A clock-driven wake must keep its <crtr-wake> kickoff — the schedule IS
@@ -391,6 +421,8 @@ function launchRevive(nodeId, meta, opts) {
         // interactive node boots promptless and takes no turn at all.
         const goal = readGoal(nodeId)?.trim();
         inv = buildPiArgv(meta, goal !== undefined && goal !== '' ? { prompt: goal } : {});
+        if (goal !== undefined && goal !== '')
+            kickoffOrigin = birthOrigin();
         clearContextExposureState(nodeId);
     }
     else {
@@ -404,11 +436,16 @@ function launchRevive(nodeId, meta, opts) {
             ...resume,
             prompt: buildReviveKickoff(meta, bearings, opts.wakeReason === 'runtime-restart-abort' ? undefined : opts.wakeReason),
         });
+        kickoffOrigin = opts.wakeReason !== undefined && opts.wakeReason !== 'runtime-restart-abort'
+            ? { type: 'runtime', kind: 'wake', wake: opts.wakeReason }
+            : { type: 'runtime', kind: 'revive', cycle: meta.cycles ?? 0 };
         clearContextExposureState(nodeId);
     }
     // Every lifecycle launch emits the authoritative spine root rather than
     // inheriting whichever node happened to invoke reviveNode.
     inv.env = { ...inv.env, CRTR_SUBTREE: rootOfSpine(nodeId) };
+    if (kickoffOrigin !== null)
+        inv.env[KICKOFF_ORIGIN_ENV] = encodeKickoffOrigin(kickoffOrigin);
     // The broker host launches the detached engine. reviveNode keeps
     // transition+clearPid around it (the crash-safety ordering, unchanged). It
     // opens NO viewer — engine-only; existing viewers reconnect, and a viewer-less
@@ -430,6 +467,27 @@ function launchRevive(nodeId, meta, opts) {
     // `crash` transition (a deadline MUST survive instance death).
     if (opts.recovery !== true)
         cancelCronsOnWake(nodeId);
+    ensureNodeDirs(nodeId);
+    const lifecycleHooks = discoverLifecycleHookRegistry(meta.cwd, meta.profile_id).plans.get('node:start') ?? [];
+    await invokeLifecycleHooks(lifecycleHooks, {
+        node: {
+            id: nodeId,
+            name: meta.name,
+            kind: meta.kind,
+            mode: meta.mode,
+            lifecycle: meta.lifecycle,
+            cwd: meta.cwd,
+            nodeDir: nodeDir(nodeId),
+            contextDir: contextDir(nodeId),
+            jobDir: jobDir(nodeId),
+            reportsDir: reportsDir(nodeId),
+        },
+        runtime: {
+            isBirth,
+            canvasHome: crtrHome(),
+            profile: meta.profile_id ?? null,
+        },
+    });
     let launched;
     try {
         launched = headlessBrokerHost.launch(nodeId, inv, {

package/dist/core/runtime/session-visibility.d.ts

@@ -1,30 +1,26 @@
 import type { WireSessionTreeNode } from './broker-protocol.js';
 import type { IdentifiedMessage } from './session-cycles.js';
+import { type MessageVisibility } from './stamp/protocol.js';
 import { REVIEW_BOUNDARY_CUSTOM_TYPE } from '../../shared/generated-context.js';
 export { REVIEW_BOUNDARY_CUSTOM_TYPE };
+export type ProjectedMessage = IdentifiedMessage & {
+    visibility: MessageVisibility;
+};
 /** True when an entry is a durable review boundary, optionally for one review. */
 export declare function isReviewBoundary(entry: unknown, reviewId?: string): boolean;
 /**
- * Project identified snapshot messages to the visible window for a review companion.
+ * Project identified snapshot messages for transcript presentation.
  *
- * A companion passes its binding's review id so the slice starts at ITS OWN
+ * Every retained message carries its durable visibility classification. A
+ * companion then passes its binding's review id so its slice starts at ITS OWN
  * boundary marker: a node forked from another companion inherits that
  * companion's earlier marker, and slicing at the first marker of any review
  * would reveal the origin companion's transcript.
- *
- * Contract (in evaluation order):
- * 1. This binding's marker present (any marker when the node has no binding) →
- *    slice from the **first** occurrence (marker included) to the end.
- *    Everything before the marker is inherited context, hidden from the person.
- * 2. Not a companion (`boundaryReviewId` undefined) → return input unchanged
- *    (same reference). Ordinary nodes are not filtered.
- * 3. Bound but no matching marker → a leading compaction summary is replaced
- *    with a synthetic boundary while its retained tail remains visible. Every
- *    other markerless shape fails closed with the synthetic boundary alone.
  */
-export declare function visibleMessages(messages: IdentifiedMessage[], opts: {
+export declare function projectTranscript(messages: IdentifiedMessage[], opts: {
     boundaryReviewId: string | undefined;
-}): IdentifiedMessage[];
+    sessionEntries?: readonly unknown[];
+}): ProjectedMessage[];
 /**
  * Project a session tree to the review companion's visible transcript boundary.
  *

package/dist/core/runtime/session-visibility.js

@@ -1,14 +1,7 @@
-// session-visibility.ts — transcript boundary projection for review companions.
-//
-// The companion node inherits the origin's full session context but the person
-// must see only the transcript from the moment the review started. A durable
-// marker (the boundary message) is appended to the session before the first
-// human-visible message, and this projection uses it to slice the visible
-// window.
-//
-// Applied at the two BrokerSnapshot.messages producers (live broker and
-// dormant node read) so every presenter — attach, web node viewer, inspect — is
-// boundary-safe by construction with no presenter-side changes.
+// session-visibility.ts — the transcript projection shared by live and dormant
+// reads. Raw session entries remain authoritative; durable stamps and review
+// boundaries select which reconstructed messages a person can see.
+import { readStamps, STAMP_SCHEMA_VERSION, } from './stamp/protocol.js';
 import { REVIEW_BOUNDARY_CUSTOM_TYPE } from '../../shared/generated-context.js';
 export { REVIEW_BOUNDARY_CUSTOM_TYPE };
 /** True when an entry is a durable review boundary, optionally for one review. */
@@ -29,35 +22,55 @@ function syntheticBoundary(timestamp) {
         timestamp: timestamp ?? Date.now(),
     };
 }
+function classifyMessages(messages, sessionEntries) {
+    const internalByTimestamp = new Map();
+    for (const stamp of readStamps(sessionEntries ?? [])) {
+        if (stamp.kind !== 'message' || stamp.v !== STAMP_SCHEMA_VERSION)
+            continue;
+        const payload = stamp.payload;
+        if (typeof payload.msgTs !== 'number')
+            continue;
+        // Last stamp wins, matching every other message-stamp reader.
+        internalByTimestamp.set(payload.msgTs, payload.visibility === 'internal');
+    }
+    let visibility = 'visible';
+    return messages.map((identified) => {
+        const { message } = identified;
+        if (message.role === 'user') {
+            visibility = typeof message.timestamp === 'number'
+                && internalByTimestamp.get(message.timestamp) === true
+                ? 'internal'
+                : 'visible';
+        }
+        return { ...identified, visibility };
+    });
+}
 /**
- * Project identified snapshot messages to the visible window for a review companion.
+ * Project identified snapshot messages for transcript presentation.
  *
- * A companion passes its binding's review id so the slice starts at ITS OWN
+ * Every retained message carries its durable visibility classification. A
+ * companion then passes its binding's review id so its slice starts at ITS OWN
  * boundary marker: a node forked from another companion inherits that
  * companion's earlier marker, and slicing at the first marker of any review
  * would reveal the origin companion's transcript.
- *
- * Contract (in evaluation order):
- * 1. This binding's marker present (any marker when the node has no binding) →
- *    slice from the **first** occurrence (marker included) to the end.
- *    Everything before the marker is inherited context, hidden from the person.
- * 2. Not a companion (`boundaryReviewId` undefined) → return input unchanged
- *    (same reference). Ordinary nodes are not filtered.
- * 3. Bound but no matching marker → a leading compaction summary is replaced
- *    with a synthetic boundary while its retained tail remains visible. Every
- *    other markerless shape fails closed with the synthetic boundary alone.
  */
-export function visibleMessages(messages, opts) {
-    const markerIndex = messages.findIndex(({ message }) => isReviewBoundary(message, opts.boundaryReviewId));
+export function projectTranscript(messages, opts) {
+    const projected = classifyMessages(messages, opts.sessionEntries);
+    const markerIndex = projected.findIndex(({ message }) => isReviewBoundary(message, opts.boundaryReviewId));
     if (markerIndex !== -1)
-        return messages.slice(markerIndex);
+        return projected.slice(markerIndex);
     if (opts.boundaryReviewId === undefined)
-        return messages;
-    const [first, ...retainedTail] = messages;
+        return projected;
+    const [first, ...retainedTail] = projected;
+    const boundary = {
+        id: '~boundary',
+        message: syntheticBoundary(first?.message.timestamp),
+        visibility: 'visible',
+    };
     if (first?.message.role === 'compactionSummary') {
-        return [{ id: '~boundary', message: syntheticBoundary(first.message.timestamp) }, ...retainedTail];
+        return [boundary, ...retainedTail];
     }
-    return [{ id: '~boundary', message: syntheticBoundary(first?.message.timestamp) }];
+    return [boundary];
 }
 /**
  * Project a session tree to the review companion's visible transcript boundary.

package/dist/core/runtime/spawn.d.ts

@@ -44,9 +44,9 @@ export interface SpawnChildOpts {
     /** Pin the node to a model spec — exact `provider/id`, `provider/tier`
      *  (e.g. `openai/ultra`), bare tier (ultra/strong/medium/light), or family
      *  alias (opus/sonnet/haiku) — overriding the persona's declared default.
-     *  The RAW spec is persisted to `meta.model_override` (buildLaunchSpec
-     *  re-normalizes through the current ladders on every revive/polymorph, so
-     *  ladder config edits keep propagating). Omit to use the persona default. */
+     *  The supplied spec resolves once through the target ladders and its concrete
+     *  provider/model is persisted as the exact launch recipe. Omit to use the
+     *  persona default. */
     model?: string;
     /** Select the profile this node runs under — an exact profile id or a unique
      *  manifest name (or the closest match to one), resolved through

package/dist/core/runtime/spawn.js

@@ -21,6 +21,7 @@ import { writeGoal } from './kickoff.js';
 import { appendSituationalContext, formatSituationalProse } from './situational-context.js';
 import { hasRoadmap, seedRoadmap } from './roadmap.js';
 import { buildWakeBearings } from './bearings.js';
+import { encodeKickoffOrigin, KICKOFF_ORIGIN_ENV } from './stamp/protocol.js';
 import { canonicalSessionFile, contextDir, findNodeBySessionFile, getNode, fullName, recordPid, setFrozen } from '../canvas/index.js';
 import { boundFleet, brokerThresholdsForDaemon } from './fleet.js';
 import { emitEvent } from '../events/emit.js';
@@ -238,7 +239,9 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
     if (opts.nodeId !== undefined)
         preflightNodeId(opts.nodeId);
     const profileId = await resolveProfileId(opts.profile, spawner, opts.cwd);
-    const preflightLaunch = (await buildLaunchSpecAsync(opts.kind, mode, { lifecycle, hasManager: !root, model: opts.model, cwd: opts.cwd, profileId })).launch;
+    const preflightLaunch = (await buildLaunchSpecAsync(opts.kind, mode, {
+        lifecycle, hasManager: !root, model: opts.model, modelOverride: opts.model !== undefined, cwd: opts.cwd, profileId,
+    })).launch;
     await assertLaunchModelRegistered(requestFromLaunch(preflightLaunch), { cwd: opts.cwd, profileId });
     const forkFrom = opts.forkFrom !== undefined ? resolveForkSource(opts.forkFrom) : undefined;
     const forkSourceNodeId = forkFrom === undefined
@@ -259,7 +262,9 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
         // this process's ambient scope (a front-door shell has no CRTR_PROFILE_ID,
         // which silently hid every profile-scope kind override).
         const launch = wantsWorktree
-            ? (await buildLaunchSpecAsync(opts.kind, mode, { lifecycle, hasManager: !root, model: opts.model, cwd: spawnCwd, profileId })).launch
+            ? (await buildLaunchSpecAsync(opts.kind, mode, {
+                lifecycle, hasManager: !root, model: opts.model, modelOverride: opts.model !== undefined, cwd: spawnCwd, profileId,
+            })).launch
             : preflightLaunch;
         if (wantsWorktree) {
             await assertLaunchModelRegistered(requestFromLaunch(launch), { cwd: spawnCwd, profileId });
@@ -280,7 +285,7 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
             profile_id: profileId,
             forkFrom: opts.forkFrom,
             forkSourceFile: forkFrom,
-            modelOverride: opts.model,
+            modelOverride: opts.model === undefined ? undefined : launch.model,
             ...(managedWorktree !== undefined ? { managedWorktree } : {}),
             ...(nodeId !== undefined ? { nodeId } : {}),
             launch,
@@ -335,6 +340,18 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
         // CRTR_SUBTREE (the spine root) rides the detached broker's env so it can group
         // the subtree; the host sets CRTR_FRONT_DOOR itself.
         inv.env = { ...inv.env, CRTR_SUBTREE: rootOfSpine(meta.node_id) };
+        // The kickoff's provenance rides the same env: it is composed here but sent
+        // by the broker process, which stamps it against the message pi persists.
+        if (hasKickoff) {
+            const kickoffOrigin = opts.wakeOrigin !== undefined
+                ? { type: 'runtime', kind: 'wake', wake: opts.wakeOrigin }
+                : {
+                    type: 'runtime',
+                    kind: 'kickoff',
+                    ...(meta.spawned_by != null && meta.spawned_by !== '' ? { spawnedBy: meta.spawned_by } : {}),
+                };
+            inv.env[KICKOFF_ORIGIN_ENV] = encodeKickoffOrigin(kickoffOrigin);
+        }
         // Snapshot the boot-fault attempt the instant before launch — see
         // beginBootFaultAttempt — so a later diagnostic read (root+await only, below)
         // can only ever surface a fault THIS launch recorded, never a stale one.

package/dist/core/runtime/stamp/channel.d.ts

@@ -0,0 +1,22 @@
+import type { MessageOrigin, MessageVisibility } from './protocol.js';
+export interface MessageAnnouncement {
+    origin: MessageOrigin;
+    visibility?: MessageVisibility;
+}
+/** The correlation key for one message body. Announcers pass the text they are
+ *  about to send; the writer passes the text pi persisted. */
+export declare function messageSignature(text: string): string;
+/** Announce the origin and visibility of the user message `text` that is about
+ *  to be sent. Every ordinary announcement promotes the run to visible. */
+export declare function announceMessageOrigin(text: string, origin: MessageOrigin, visibility?: MessageVisibility): void;
+/** Take the announced metadata for a persisted message body, or null when no
+ *  seam announced this message. */
+export declare function claimMessageAnnouncement(text: string): MessageAnnouncement | null;
+/** Contribute namespaced fields to the next stamp the writer emits. Unknown
+ *  namespaces pass through untouched; the core writer never interprets them. */
+export declare function contributeStampExt(namespace: string, fields: Record<string, unknown>): void;
+/** Whether any contribution is waiting — an assistant message is stamped only
+ *  when one is, so an ordinary assistant turn costs no line. */
+export declare function hasPendingStampExt(): boolean;
+/** Take every buffered contribution, merged per namespace. */
+export declare function drainStampExt(): Record<string, Record<string, unknown>> | undefined;