@north-light/crouter 0.3.226 → 0.3.228

package/dist/core/runtime/broker-persona-guidance.js

@@ -1,30 +1,21 @@
-// Broker-local persona transition guidance. Canvas state is supplied by crtrd;
-// this module reads only the node's own roadmap and durable memory files.
-import { resolveMemoryDoc } from '../memory-resolver.js';
 import { contextDir } from '../canvas/paths.js';
+import { emitEvent } from '../events/emit.js';
+import { brokerExtensionState, commitBrokerPersonaAck } from './broker/daemon-ops.js';
 import { readRoadmap, roadmapPath } from './roadmap.js';
-function loadMemoryBody(name) {
-    try {
-        return resolveMemoryDoc(name).body.trim();
-    }
-    catch {
-        return '';
-    }
-}
+import { buildSubPersonaMenu, renderConfigChangeDelta } from '../substrate/render.js';
+import { cloneContextExposureState, contextExposureStatesEqual, exposureTarget, loadContextExposureState, mergeContextExposureState, replaceContextExposureState, saveContextExposureState, sharedContextExposureState, } from '../substrate/injected-store.js';
+import { formatCard } from '../../shared/generated-context.js';
 function orchestratorContextNote(nodeId) {
     return `Because you persist across refresh cycles, your context directory (${contextDir(nodeId)}) is also where a future cycle of you resumes the work — keep the working notes and decisions a refreshed you would need there, alongside the docs you share with the nodes you spawn.`;
 }
 function orchestrationGuidance(node) {
-    const kernel = loadMemoryBody('orchestration-kernel');
     const roadmap = readRoadmap(node.node_id) ?? '(no roadmap yet)';
     const rmPath = roadmapPath(node.node_id);
     return [
         `You are now a ${node.kind.toUpperCase()} ORCHESTRATOR. Your scarce resource is your own context window.`,
         'Your job is to manage context and delegate — not to do the goal yourself.',
         '',
-        kernel,
-        '',
-        `Your roadmap scaffold (\`${rmPath}\`) — author it now: state the goal, exit criteria, and the phase skeleton, using the approach above. Current contents:`,
+        `Your roadmap scaffold (\`${rmPath}\`) — author it now: state the goal, exit criteria, and the phase skeleton, using the approach below. Current contents:`,
         '',
         roadmap,
         '',
@@ -38,21 +29,125 @@ function orchestrationGuidance(node) {
 function baseModeGuidance() {
     return 'You are HANDS-ON again — base mode. Do the work yourself in THIS window and finish it here; stop delegating by default. You no longer drive a roadmap, so `crtr node yield` is not your exit. Spawn a child only for a cleanly separable unit, never as your first move.';
 }
-export function transitionGuidanceFromBrokerState(node, from, to) {
+function subPersonaGuidance(from, to) {
+    if (from.kind === to.kind)
+        return '';
+    const before = buildSubPersonaMenu(from.kind);
+    const after = buildSubPersonaMenu(to.kind);
+    if (before === after)
+        return '';
+    return after === ''
+        ? `The ${to.kind} kind has no specialist sub-personas available.`
+        : after;
+}
+function transitionGuidance(state, from, to, contextExposure) {
     const sections = [];
     if (from.mode !== to.mode) {
-        sections.push(to.mode === 'orchestrator' ? orchestrationGuidance(node) : baseModeGuidance());
-    }
-    if (from.lifecycle !== to.lifecycle) {
-        sections.push(loadMemoryBody(to.lifecycle === 'resident' ? 'turn-lifecycle/resident' : 'turn-lifecycle/terminal'));
+        sections.push(to.mode === 'orchestrator' ? orchestrationGuidance(state.node) : baseModeGuidance());
     }
-    return sections.join('\n\n');
+    sections.push(subPersonaGuidance(from, to));
+    sections.push(renderConfigChangeDelta(state.subject, state.node.node_id, exposureTarget(contextExposure, 'transcript')));
+    return sections.filter((section) => section !== '').join('\n\n');
 }
-/** Return an unacknowledged persona transition from crtrd's fixed extension state. */
-export function personaDriftFromBrokerState(node) {
-    const to = { mode: node.mode, lifecycle: node.lifecycle };
-    const from = node.persona_ack ?? to;
-    if (from.mode === to.mode && from.lifecycle === to.lifecycle)
+export function personaDriftFromBrokerState(state) {
+    const node = state.node;
+    const to = { kind: node.kind, mode: node.mode, lifecycle: node.lifecycle };
+    const ack = node.persona_ack;
+    const from = ack === undefined
+        ? to
+        : { kind: ack.kind ?? node.kind, mode: ack.mode, lifecycle: ack.lifecycle };
+    if (from.kind === to.kind && from.mode === to.mode && from.lifecycle === to.lifecycle)
         return null;
-    return { from, to, guidance: transitionGuidanceFromBrokerState(node, from, to) };
+    return { from, to };
+}
+/** A new context's current snapshots make a rank delta unnecessary. */
+export async function acknowledgePersonaBaseline(state) {
+    const drift = personaDriftFromBrokerState(state);
+    if (drift === null)
+        return false;
+    const result = await commitBrokerPersonaAck(state.node.node_id, drift);
+    if (!result.applied)
+        throw new Error(`persona baseline acknowledgment was rejected for ${state.node.node_id}`);
+    return true;
+}
+/** Append pending transitions until the delivered persona matches current canvas state. */
+export async function deliverPendingPersonaTransition(initialState, deliver) {
+    const nodeId = initialState.node.node_id;
+    const live = sharedContextExposureState(nodeId);
+    const persisted = loadContextExposureState(nodeId);
+    mergeContextExposureState(live, persisted);
+    if (live.preferenceSnapshot === null) {
+        throw new Error(`context preference snapshot is missing for ${nodeId}`);
+    }
+    if (!contextExposureStatesEqual(live, persisted))
+        saveContextExposureState(nodeId, live);
+    let state = initialState;
+    let daemonDrift = personaDriftFromBrokerState(state);
+    if (daemonDrift === null)
+        return false;
+    const next = cloneContextExposureState(live);
+    let represented = daemonDrift.from;
+    for (;;) {
+        const current = {
+            kind: state.node.kind,
+            mode: state.node.mode,
+            lifecycle: state.node.lifecycle,
+        };
+        if (represented.kind !== current.kind
+            || represented.mode !== current.mode
+            || represented.lifecycle !== current.lifecycle) {
+            const guidance = transitionGuidance(state, represented, current, next);
+            if (guidance !== '')
+                await deliver(formatCard('persona-transition', {}, guidance));
+            represented = current;
+            replaceContextExposureState(live, next);
+            saveContextExposureState(nodeId, live);
+        }
+        daemonDrift = personaDriftFromBrokerState(state);
+        if (daemonDrift === null)
+            return true;
+        const result = await commitBrokerPersonaAck(nodeId, daemonDrift);
+        if (result.applied)
+            return true;
+        state = await brokerExtensionState(nodeId);
+    }
+}
+/** Gate each provider request on durable delivery of the current persona delta. */
+export function installPersonaTransitionGate(nodeId, session) {
+    const { agent } = session;
+    const previousTransform = agent.transformContext;
+    agent.transformContext = async (messages, signal) => {
+        const transformed = previousTransform === undefined
+            ? messages
+            : await previousTransform(messages, signal);
+        try {
+            const state = await brokerExtensionState(nodeId);
+            await deliverPendingPersonaTransition(state, (content) => {
+                const details = { nodeId };
+                const message = {
+                    role: 'custom',
+                    customType: 'crtr-persona-transition',
+                    content,
+                    display: true,
+                    details,
+                    timestamp: Date.now(),
+                };
+                session.sessionManager.appendCustomMessageEntry('crtr-persona-transition', content, true, details);
+                const active = agent.state.messages;
+                for (const context of new Set([active, messages, transformed]))
+                    context.push(message);
+            });
+            return transformed;
+        }
+        catch (error) {
+            emitEvent({
+                event: 'broker.daemon.operation.failed',
+                level: 'error',
+                node_id: nodeId,
+                error,
+                fields: { operation: 'persona_transition' },
+            });
+            throw error;
+        }
+    };
 }

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

@@ -15,10 +15,22 @@ export interface LiveCustomMessage {
  *  warm claim it is fatal: a node wearing the wrong bearings is worse than a
  *  slow one, so the spare is abandoned and the create goes cold). */
 export declare function deliverCustomMessageLive(nodeId: string, message: LiveCustomMessage): Promise<void>;
-/** Build and deliver `nodeId`'s bearings into its live session. Called by the
- *  warm-pool claim once the row already wears the claimant's kind/mode/name, so
- *  the identity assertion, the knowledge catalog, and the `<project_context>`
- *  environment snapshot are all built for the node being handed out.
+/** Build and deliver `nodeId`'s bearings into its live session, and freeze the
+ *  preference snapshot that goes with them. Called by the warm-pool claim once
+ *  the row already wears the claimant's kind/mode/name, so the identity
+ *  assertion, the knowledge catalog, the `<project_context>` environment
+ *  snapshot, and the preference block are all built for the node being handed
+ *  out.
+ *
+ *  The snapshot is frozen HERE for the same reason bearings are built here: a
+ *  spare boots with no claimant, so `canvas-context-intro` skips warm spares
+ *  and the block would otherwise assert the SPARE's preferences. Claim is the
+ *  first moment the real persona, profile, and cwd exist, and it is the last
+ *  moment before the claimant's first turn — which reaches the provider through
+ *  the persona gate, and which need not be a typed prompt. A slash command
+ *  opens its turn through `sendMessage({ triggerTurn: true })`, and Pi emits
+ *  `before_agent_start` only on the typed-prompt path, so the broker's own
+ *  freeze in `canvas-doc-substrate` never runs for it.
  *
  *  The `details.nodeId` stamp is what the context-intro extension's idempotency
  *  guard matches on, so a LATER revive of this node sees its own bearings

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

@@ -21,7 +21,9 @@ import { getNode } from '../canvas/index.js';
 import { oneShotControllerRequest } from './broker-request.js';
 import { isBrokerLive } from './model-swap.js';
 import { buildContextBearings, CONTEXT_INTRO_CUSTOM_TYPE } from './bearings.js';
-import { loadInjectedDocs, saveInjectedDocs } from '../substrate/injected-store.js';
+import { renderPreferencesForNodeSubject } from './broker-extension-render.js';
+import { assembleNodeSubject } from '../substrate/subject.js';
+import { exposureTarget, freezePreferenceSnapshot, loadContextExposureState, saveContextExposureState, } from '../substrate/injected-store.js';
 import { formatCard } from '../../shared/generated-context.js';
 /** Deliver `message` into `nodeId`'s live session. Resolves without doing
  *  anything when the node has no live broker. Rejects when a live broker cannot
@@ -48,27 +50,39 @@ export async function deliverCustomMessageLive(nodeId, message) {
         result: () => undefined,
     });
 }
-/** Build and deliver `nodeId`'s bearings into its live session. Called by the
- *  warm-pool claim once the row already wears the claimant's kind/mode/name, so
- *  the identity assertion, the knowledge catalog, and the `<project_context>`
- *  environment snapshot are all built for the node being handed out.
+/** Build and deliver `nodeId`'s bearings into its live session, and freeze the
+ *  preference snapshot that goes with them. Called by the warm-pool claim once
+ *  the row already wears the claimant's kind/mode/name, so the identity
+ *  assertion, the knowledge catalog, the `<project_context>` environment
+ *  snapshot, and the preference block are all built for the node being handed
+ *  out.
+ *
+ *  The snapshot is frozen HERE for the same reason bearings are built here: a
+ *  spare boots with no claimant, so `canvas-context-intro` skips warm spares
+ *  and the block would otherwise assert the SPARE's preferences. Claim is the
+ *  first moment the real persona, profile, and cwd exist, and it is the last
+ *  moment before the claimant's first turn — which reaches the provider through
+ *  the persona gate, and which need not be a typed prompt. A slash command
+ *  opens its turn through `sendMessage({ triggerTurn: true })`, and Pi emits
+ *  `before_agent_start` only on the typed-prompt path, so the broker's own
+ *  freeze in `canvas-doc-substrate` never runs for it.
  *
  *  The `details.nodeId` stamp is what the context-intro extension's idempotency
  *  guard matches on, so a LATER revive of this node sees its own bearings
  *  already on the branch and does not inject a second copy. */
 export async function deliverBearingsLive(nodeId) {
-    // This runs in the DAEMON while the spare's pi process is already alive, so
-    // the disk file — not any in-memory set — is the dedup medium: load the
-    // node's persisted set, grow it through the workspace-open render, and
-    // persist it after successful delivery. The pi process's on-read hook merges
-    // the on-disk set before each render, so docs delivered here never
-    // re-deliver on a later read. Plain load/save (not the process-shared
-    // cache): the daemon is long-lived and serves many nodes.
-    const seen = loadInjectedDocs(nodeId);
+    // Claim runs in the daemon while the spare's Pi process is already alive.
+    // Persist transcript registrations after Pi accepts the bearings so the
+    // broker merges the same context state before later event deliveries.
+    const contextExposure = loadContextExposureState(nodeId);
     await deliverCustomMessageLive(nodeId, {
         customType: CONTEXT_INTRO_CUSTOM_TYPE,
-        content: formatCard('bearings', {}, buildContextBearings(nodeId, seen)),
+        content: formatCard('bearings', {}, buildContextBearings(nodeId, exposureTarget(contextExposure, 'transcript'))),
         details: { nodeId },
     });
-    saveInjectedDocs(nodeId, seen);
+    const subject = assembleNodeSubject(nodeId);
+    if (subject === null)
+        throw new Error(`deliverBearingsLive: no document subject for ${nodeId}`);
+    freezePreferenceSnapshot(contextExposure, renderPreferencesForNodeSubject(nodeId, subject, exposureTarget(contextExposure, 'system')));
+    saveContextExposureState(nodeId, contextExposure);
 }

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

@@ -32,12 +32,12 @@ export interface ReviveBearings {
     /** Coalesced digest of unread reports, or null when the feed was empty. The
      *  cursor now records the last physically covered entry. */
     unreadDigest: string | null;
-    /** Persona-transition guidance to surface when the node's role was changed
-     *  while it was away (its ack has already been committed), else null. */
+    /** Persona-transition framing to surface when the node's role changed while
+     *  it was away. The drift remains pending until context-intro completes. */
     driftGuidance: string | null;
 }
 /** Capture revive bearings for `meta`: read the pending yield note, advance the
- *  feed cursor past unread reports, and capture+commit external persona drift.
+ *  feed cursor past unread reports, and capture external persona framing.
  *  Revive paths call it once, then pass the result to the pure kickoff builder. */
 export declare function drainBearings(meta: NodeMeta): ReviveBearings;
 /** Assemble the auto-injected first message for a FRESH revive of `meta` from its

package/dist/core/runtime/kickoff.js

@@ -24,7 +24,7 @@ import { contextDir, reportsDir, getNode, subscriptionsOf, subscribersOf, } from
 import { activeBackgroundBashJobs, bashJobCommandLine, formatBashElapsed } from '../bash-jobs.js';
 import { readRoadmap, roadmapPath } from './roadmap.js';
 import { buildWakeBearings } from './bearings.js';
-import { personaDrift, commitPersonaAck } from './persona.js';
+import { personaDrift } from './persona.js';
 import { readInboxSince, readCursor, writeCursor, coalesce, } from '../feed/inbox.js';
 import { formatCard } from '../../shared/generated-context.js';
 /** The runtime-restart continuation exactly as delivered. `revive.ts` injects
@@ -102,7 +102,7 @@ export function listContextDir(nodeId) {
     return readdirSync(dir).sort();
 }
 /** Capture revive bearings for `meta`: read the pending yield note, advance the
- *  feed cursor past unread reports, and capture+commit external persona drift.
+ *  feed cursor past unread reports, and capture external persona framing.
  *  Revive paths call it once, then pass the result to the pure kickoff builder. */
 export function drainBearings(meta) {
     const nodeId = meta.node_id;
@@ -119,15 +119,10 @@ export function drainBearings(meta) {
         // join back into this block's body; the kickoff is one whole envelope.
         unreadDigest = coalesce(entries).map((delivery) => delivery.text).join('\n\n');
     }
-    // Capture + commit any external persona drift (the second of the two delivery
-    // sites). Committing the ack here is the mutation; the guidance is surfaced by
-    // the pure builder from this captured value.
     const drift = personaDrift(nodeId);
-    let driftGuidance = null;
-    if (drift !== null) {
-        driftGuidance = drift.guidance;
-        commitPersonaAck(nodeId, drift.to);
-    }
+    const driftGuidance = drift?.guidance === undefined || drift.guidance === ''
+        ? null
+        : drift.guidance;
     return { yieldMsg, unreadDigest, driftGuidance };
 }
 // Fresh-revive catch-up bug: on a refresh-yield (resume:false) the old
@@ -309,12 +304,9 @@ export function buildReviveKickoff(meta, bearings, wakeReason) {
         : 'If there is work to do, perform it. Otherwise end your turn — you are working ' +
             'directly with the user, so stay available and continue the conversation when they ' +
             'write back.');
-    // Persona-transition catch-up. If the node's mode/lifecycle was changed
-    // EXTERNALLY while it was dormant (e.g. a human ran `crtr node config --lifecycle` /
-    // `node promote --node` on it), it never saw the turn_end injector. drainBearings
-    // captured the guidance for its new persona and committed the ack (the second
-    // and only other delivery site); we just surface it. A clean fresh revive has
-    // no drift, so this is empty unless a real external change happened.
+    // Non-document framing for a persona change made while the node was away.
+    // The replacement context's current snapshots carry all eligible documents;
+    // context-intro acknowledges the transition after those snapshots persist.
     if (bearings.driftGuidance !== null) {
         parts.push(`<persona-transition>\nYour role was changed while you were away. ${bearings.driftGuidance}\n</persona-transition>`);
     }

package/dist/core/runtime/lifecycle.js

@@ -7,9 +7,8 @@
 // writes both fields in ONE atomic statement (on the WAL'd row setters) so the
 // two can never disagree.
 //
-// This mirrors persona.ts: persona.ts is the single source of transition PROSE;
-// lifecycle.ts is the single source of which status/intent move is LEGAL. Two
-// parallel, legible state machines instead of scattered enactment.
+// Persona modules own context framing; this file owns which status/intent move
+// is legal. The two state machines stay independent.
 //
 // Crash-safety invariant: flip status to a non-supervised value + clear intent
 // BEFORE killing the host (tmux pane or headless broker) — the daemon only ever

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

@@ -65,11 +65,10 @@ export interface SpawnNodeOpts {
      *  `parent` — e.g. an independent root (parent=null) still records its
      *  spawner. Defaults to `parent`. */
     spawnedBy?: string | null;
-    /** Fork provenance — the `--fork-from` reference this node was forked from (a
-     *  node id / session path / pi session uuid). Persisted to `meta.fork_from` so
-     *  the boot intro can re-assert this node's OWN identity over the source's
-     *  copied-in conversation. Omit for a fresh node. */
+    /** Raw `--fork-from` operand retained for identity framing and audit. */
     forkFrom?: string | null;
+    /** Resolved absolute source session file retained for pre-bind retries. */
+    forkSourceFile?: string | null;
     /** Suppress the spawn-time parent→child ACTIVE subscription. Default true
      *  (every existing caller keeps its edge). False gives ordinary canvas
      *  placement with no wake path back to the parent. */

package/dist/core/runtime/nodes.js

@@ -237,14 +237,13 @@ export function spawnNode(opts) {
         kind: opts.kind,
         mode,
         lifecycle,
-        // Born already acked to its initial persona: a fresh node has been "given
-        // guidance" for the state it starts in (its bearings carry it), so the
-        // persona injector sees no drift on its first turn boundary.
-        persona_ack: { mode, lifecycle },
+        // Birth snapshots already represent this persona, so no transition is pending.
+        persona_ack: { kind: opts.kind, mode, lifecycle },
         status: 'active',
         parent,
         spawned_by: spawnedBy,
         fork_from: opts.forkFrom,
+        fork_source_file: opts.forkSourceFile,
         review_binding: opts.reviewBinding,
         model_override: opts.modelOverride ?? null,
         passive_default: opts.passiveDefault ?? false,

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

@@ -1,25 +1,21 @@
 import { type Mode, type Lifecycle } from '../canvas/index.js';
-/** The two-axis persona state the injector keys on. */
+/** The three-axis persona transition key. */
 export interface Persona {
+    kind: string;
     mode: Mode;
     lifecycle: Lifecycle;
 }
 export interface PersonaDriftResult {
     from: Persona;
     to: Persona;
-    /** The built transition guidance to inject for `to`. */
+    /** Fresh-context framing for `to`; its snapshots carry document context. */
     guidance: string;
 }
-/** Build the injected transition prompt for a `from → to` persona change.
- *  Concatenates the relevant section per changed axis (both when both changed).
- *  Pure read of the node's roadmap/memory for the base→orchestrator case. */
+/** Build only the non-document framing for a fresh-context transition. */
 export declare function transitionGuidance(nodeId: string, from: Persona, to: Persona): string;
-/** Compare a node's live {mode,lifecycle} against its `persona_ack` (the last
- *  state it was given guidance for). Returns the transition + built guidance
- *  when they differ, else null. Does NOT mutate — the caller delivers the
- *  guidance, then `commitPersonaAck`s the new state. An unset `persona_ack`
- *  (legacy node) defaults to the current persona, so it reads as no drift and
- *  never fabricates spurious guidance. */
+/** Compare the live persona with the last acknowledged context delivery.
+ * `guidance` contains only fresh-context framing; current snapshots supply its
+ * documents. An absent or pre-kind acknowledgment cannot fabricate drift. */
 export declare function personaDrift(nodeId: string): PersonaDriftResult | null;
-/** Commit the persona state the node has now been given guidance for. */
+/** Commit the persona state whose context delivery is complete. */
 export declare function commitPersonaAck(nodeId: string, to: Persona): void;

package/dist/core/runtime/persona.js

@@ -1,75 +1,25 @@
-// persona.ts — the CENTRALIZED persona-transition injector.
-//
-// A node has two orthogonal, independently switchable axes:
-//   • mode      — base (hands-on; yields mode-preservingly when another window is needed) ↔ orchestrator
-//                 (delegates, holds a roadmap, survives refresh cycles + yields)
-//   • lifecycle — terminal (owes a final up the spine, reaps when done) ↔
-//                 resident (interactable, never forced to submit; unattended
-//                 obligation-free conversations complete after the daemon grace)
-//
-// Whenever EITHER axis changes from the value the node was last GIVEN guidance
-// for, the node must be prompt-injected with guidance for its new state —
-// automatically, here, not by each state-changing command. Commands just call
-// `updateNode({ mode|lifecycle })`; this module is the single source of the
-// transition prose, delivered from exactly two sites:
-//   • the stophook turn_end hook (self-changes this turn + external changes
-//     while the node is active), and
-//   • the revive kickoff (external changes made while the node was dormant).
-//
-// The `persona_ack` meta field records the last {mode,lifecycle} the node was
-// given guidance for (born equal to its initial persona at spawn, so a fresh
-// worker never gets spurious guidance). `personaDrift` compares live meta to it;
-// the caller delivers the guidance, then commits the ack.
+// Persona drift and the non-document framing carried by a fresh-revive kickoff.
+// The new context's system and bearings snapshots supply its memory baseline;
+// canvas-context-intro acknowledges the drift after both snapshots persist.
 import { getNode, updateNode } from '../canvas/index.js';
-import { resolveMemoryDoc } from '../memory-resolver.js';
 import { readRoadmap, roadmapPath } from './roadmap.js';
 import { orchestratorContextNote } from './bearings.js';
 // ---------------------------------------------------------------------------
-// base→orchestrator guidance (the roadmap-shaping dump) — MOVED here from
-// promote.ts so the injector is the one place that builds it.
+// Base → orchestrator guidance
 // ---------------------------------------------------------------------------
-/** Load a builtin/user/project memory doc's body by its normalized name, or ''
- *  if it can't be resolved. The single source for the lifecycle/spine/
- *  orchestration-kernel fragments this injector re-delivers on a transition —
- *  the SAME docs under `src/builtin-memory/`, so static
- *  (system-prompt splice) and transition prose can never drift. */
-function loadMemoryBody(name) {
-    try {
-        return resolveMemoryDoc(name).body.trim();
-    }
-    catch {
-        return '';
-    }
-}
-/** The base→orchestrator guidance dump, specialized to the node's kind: the
- *  shared orchestration-kernel doc + the roadmap scaffold the node must author +
- *  the orchestrator context-dir framing + a short pointer at the substrate
- *  memory flow (promotion re-informs of nothing about the stores, it only adds
- *  the across-cycles relevance). The node is now a delegator whose scarce
- *  resource is its own context window. Roadmap-shaping guidance is just another orchestrator-gated memory
- *  doc the node already gets via the boot-render splice (kinds/<kind>/orchestrator
- *  gated `{kind, mode: orchestrator}`). (Lifecycle is left to its own section —
- *  promotion does not force resident, so this never asserts residency.) */
+/** Fresh-context framing for a base → orchestrator change. */
 function orchestrationGuidance(nodeId, kind) {
-    const kernel = loadMemoryBody('orchestration-kernel');
     const roadmap = readRoadmap(nodeId) ?? '(no roadmap yet)';
     const rmPath = roadmapPath(nodeId);
     const parts = [
         `You are now a ${kind.toUpperCase()} ORCHESTRATOR. Your scarce resource is your own context window.`,
         'Your job is to manage context and delegate — not to do the goal yourself.',
-        '',
-        kernel,
     ];
-    parts.push('', `Your roadmap scaffold (\`${rmPath}\`) — author it now: state the goal, exit criteria, and the phase skeleton, using the approach above. Current contents:`, '', roadmap, '', 
-    // The orchestrator framing for the context dir — the missing guidance a
-    // promoted node never got at spawn (it spawned as a base worker). Same note
-    // a born-orchestrator gets in its <crtr-bearings> block.
-    orchestratorContextNote(nodeId), '', 'Your three long-term memory scopes (user-global, project, node-local) already surface in your bearings at boot. What promotion changes is USE, not access: you now persist across refresh cycles, so node-local carries what THIS goal needs between your refreshes, and durable facts you commit to user-global or project outlive this node. Use `crtr memory write` to save a document; `crtr memory list` to browse; `crtr memory find` to search (see "Your long-term memory" above for the full substrate flow).', '', 'Then delegate each phase with `crtr node new --kind <kind>`. When your context fills, run `crtr node yield` to refresh against this roadmap.');
+    parts.push('', `Your roadmap scaffold (\`${rmPath}\`) — author it now: state the goal, exit criteria, and the phase skeleton, using your orchestration protocol. Current contents:`, '', roadmap, '', orchestratorContextNote(nodeId), '', 'Your three long-term memory scopes (user-global, project, node-local) already surface in your bearings at boot. What promotion changes is USE, not access: you now persist across refresh cycles, so node-local carries what THIS goal needs between your refreshes, and durable facts you commit to user-global or project outlive this node. Use `crtr memory write` to save a document; `crtr memory list` to browse; `crtr memory find` to search (see "Your long-term memory" above for the full substrate flow).', '', 'Then delegate each phase with `crtr node new --kind <kind>`. When your context fills, run `crtr node yield` to refresh against this roadmap.');
     return parts.join('\n');
 }
 // ---------------------------------------------------------------------------
-// The other three transitions — short, prescriptive, audience = the node's
-// agent (decision-first; one well-placed "don't").
+// Orchestrator → base guidance
 // ---------------------------------------------------------------------------
 /** orchestrator → base (demote): hands-on again, finish in-window. */
 function baseModeGuidance() {
@@ -77,57 +27,35 @@ function baseModeGuidance() {
         'stop delegating by default. You no longer drive a roadmap, so `crtr node yield` is not your exit. ' +
         'Spawn a child only for a cleanly separable unit, never as your first move.');
 }
-// The lifecycle transition prose is the SAME contract that's baked into the
-// static system prompt at birth — so both load from the one source
-// (`turn-lifecycle/{terminal,resident}.md`) and can never drift. The flip
-// only re-delivers that fragment as the node's new-state steer.
-/** terminal → resident: interactable, never forced to submit. */
-function residentLifecycleGuidance() {
-    return loadMemoryBody('turn-lifecycle/resident');
-}
-/** resident → terminal: owes a final, reaps when done. */
-function terminalLifecycleGuidance() {
-    return loadMemoryBody('turn-lifecycle/terminal');
-}
-/** Build the injected transition prompt for a `from → to` persona change.
- *  Concatenates the relevant section per changed axis (both when both changed).
- *  Pure read of the node's roadmap/memory for the base→orchestrator case. */
+/** Build only the non-document framing for a fresh-context transition. */
 export function transitionGuidance(nodeId, from, to) {
-    const sections = [];
-    if (from.mode !== to.mode) {
-        if (to.mode === 'orchestrator') {
-            const node = getNode(nodeId);
-            sections.push(orchestrationGuidance(nodeId, node?.kind ?? 'general'));
-        }
-        else {
-            sections.push(baseModeGuidance());
-        }
-    }
-    if (from.lifecycle !== to.lifecycle) {
-        sections.push(to.lifecycle === 'resident' ? residentLifecycleGuidance() : terminalLifecycleGuidance());
-    }
-    return sections.join('\n\n');
+    if (from.mode === to.mode)
+        return '';
+    if (to.mode === 'base')
+        return baseModeGuidance();
+    const node = getNode(nodeId);
+    return orchestrationGuidance(nodeId, node?.kind ?? 'general');
 }
 // ---------------------------------------------------------------------------
 // Detector + ack commit.
 // ---------------------------------------------------------------------------
-/** Compare a node's live {mode,lifecycle} against its `persona_ack` (the last
- *  state it was given guidance for). Returns the transition + built guidance
- *  when they differ, else null. Does NOT mutate — the caller delivers the
- *  guidance, then `commitPersonaAck`s the new state. An unset `persona_ack`
- *  (legacy node) defaults to the current persona, so it reads as no drift and
- *  never fabricates spurious guidance. */
+/** Compare the live persona with the last acknowledged context delivery.
+ * `guidance` contains only fresh-context framing; current snapshots supply its
+ * documents. An absent or pre-kind acknowledgment cannot fabricate drift. */
 export function personaDrift(nodeId) {
     const meta = getNode(nodeId);
     if (meta === null)
         return null;
-    const to = { mode: meta.mode, lifecycle: meta.lifecycle };
-    const from = meta.persona_ack ?? { mode: meta.mode, lifecycle: meta.lifecycle };
-    if (from.mode === to.mode && from.lifecycle === to.lifecycle)
+    const to = { kind: meta.kind, mode: meta.mode, lifecycle: meta.lifecycle };
+    const ack = meta.persona_ack;
+    const from = ack === undefined
+        ? to
+        : { kind: ack.kind ?? meta.kind, mode: ack.mode, lifecycle: ack.lifecycle };
+    if (from.kind === to.kind && from.mode === to.mode && from.lifecycle === to.lifecycle)
         return null;
     return { from, to, guidance: transitionGuidance(nodeId, from, to) };
 }
-/** Commit the persona state the node has now been given guidance for. */
+/** Commit the persona state whose context delivery is complete. */
 export function commitPersonaAck(nodeId, to) {
     updateNode(nodeId, { persona_ack: to });
 }

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

@@ -30,8 +30,8 @@ export declare function reshapeNodeAsync(nodeId: string, opts?: ReshapeOptions,
  *  `developer.orchestrator`) and optionally also making it resident. Idempotent:
  *  re-promoting just rewrites the spec. Seeds a roadmap SCAFFOLD if absent (a
  *  boss with no map is a failure mode) — no goal is forced here; authoring the
- *  goal + roadmap is the node's next act. The transition guidance is injected
- *  centrally by the persona injector at the next turn boundary, not returned. */
+ *  goal + roadmap is the node's next act. Pending context delivery is owned by
+ *  the broker provider gate, not this command. */
 export declare function promote(nodeId: string, opts?: {
     kind?: string;
     resident?: boolean;