@north-light/crouter 0.3.227 → 0.3.229

package/dist/core/nested-stores.js

@@ -6,7 +6,7 @@
 // flat ancestor+profile stack (on-read delivery finds nested stores through
 // its own read-file walk instead).
 //
-// Two discovery modes per owner dir, both under one shared 500 ms budget:
+// Two discovery modes per owner dir, each under its own 500 ms budget:
 //   • Git root — `git ls-files` over tracked+untracked (respecting .gitignore),
 //     so junk dirs and ignored trees cost nothing and embedded repos are
 //     auto-excluded (ls-files does not descend into submodules).
@@ -55,12 +55,7 @@ export function descendantStoreRoots(ancestorRoots) {
         ownerSeen.add(real);
         owners.push(owner);
     }
-    const deadline = Date.now() + TIME_BUDGET_MS;
-    let warned = false;
     const tripBudget = (owner) => {
-        if (warned)
-            return;
-        warned = true;
         warn(`memory: nested-store discovery under ${owner} exceeded its ${TIME_BUDGET_MS}ms budget — nested stores may be missing from this listing; register deep stores explicitly (add their dirs to the selected profile's projects)`);
     };
     const found = [];
@@ -72,17 +67,15 @@ export function descendantStoreRoots(ancestorRoots) {
         foundSeen.add(real);
         found.push(storeRoot);
     };
+    // Each owner gets the full budget: owners are independent trees, so one
+    // pathological tree must neither starve the owners after it nor pin the
+    // warning on whichever owner happened to be next when a shared clock ran out.
     for (const owner of owners) {
-        const remaining = deadline - Date.now();
-        if (remaining <= 0) {
-            tripBudget(owner);
-            break;
-        }
         if (pathExists(join(owner, '.git'))) {
-            collectGitStores(owner, add, remaining, () => tripBudget(owner));
+            collectGitStores(owner, add, TIME_BUDGET_MS, () => tripBudget(owner));
         }
         else {
-            collectWalkStores(owner, add, deadline, () => tripBudget(owner));
+            collectWalkStores(owner, add, Date.now() + TIME_BUDGET_MS, () => tripBudget(owner));
         }
     }
     cache.set(key, found);

package/dist/core/profiles/select.d.ts

@@ -1,6 +1,6 @@
 import { type ProfileEntry } from './manifest.js';
 import { type BindingId, type BindingResolution, type RawTerminalInput } from '../keybindings/index.js';
-declare const PROFILE_MENU_ACTIONS: readonly ["crtr.profile.menu.abort", "crtr.profile.menu.up", "crtr.profile.menu.down", "crtr.profile.menu.select", "crtr.profile.menu.accept-default", "crtr.profile.menu.slot.1", "crtr.profile.menu.slot.2", "crtr.profile.menu.slot.3", "crtr.profile.menu.slot.4", "crtr.profile.menu.slot.5", "crtr.profile.menu.slot.6", "crtr.profile.menu.slot.7", "crtr.profile.menu.slot.8", "crtr.profile.menu.slot.9", "crtr.profile.menu.create", "crtr.profile.menu.search-existing", "crtr.profile.menu.use-root", "crtr.profile.menu.set-default", "crtr.profile.menu.add-directory", "crtr.profile.menu.unpin"];
+declare const PROFILE_MENU_ACTIONS: readonly ["crtr.profile.menu.abort", "crtr.profile.menu.up", "crtr.profile.menu.down", "crtr.profile.menu.select", "crtr.profile.menu.accept-default", "crtr.profile.menu.slot.1", "crtr.profile.menu.slot.2", "crtr.profile.menu.slot.3", "crtr.profile.menu.slot.4", "crtr.profile.menu.slot.5", "crtr.profile.menu.slot.6", "crtr.profile.menu.slot.7", "crtr.profile.menu.slot.8", "crtr.profile.menu.slot.9", "crtr.profile.menu.create", "crtr.profile.menu.search-existing", "crtr.profile.menu.use-root", "crtr.profile.menu.set-default", "crtr.profile.menu.add-directory", "crtr.profile.menu.unpin", "crtr.profile.menu.manage"];
 declare const PROFILE_SEARCH_ACTIONS: readonly ["crtr.profile.search.abort", "crtr.profile.search.back", "crtr.profile.search.pick", "crtr.profile.search.up", "crtr.profile.search.down", "crtr.profile.search.delete"];
 export declare function resolveProfileMenuAction(bindings: BindingResolution<BindingId>, raw: RawTerminalInput): (typeof PROFILE_MENU_ACTIONS)[number] | null;
 export declare function resolveProfileSearchAction(bindings: BindingResolution<BindingId>, raw: RawTerminalInput): (typeof PROFILE_SEARCH_ACTIONS)[number] | null;
@@ -11,6 +11,9 @@ export declare function resolveProfileSearchAction(bindings: BindingResolution<B
 export declare function profileCoversCwd(entry: ProfileEntry, cwd: string): boolean;
 /** Resolve the headless selector against existing state without changing it. */
 export declare function selectProfileForCwdReadOnly(cwd: string): string;
+/** Collapse the home prefix to `~` so project paths read short. Exported so the
+ *  Profiles settings panel prints a project dir exactly as this menu does. */
+export declare function tildify(p: string): string;
 /** Select the profile a node about to boot at `cwd` should run under.
  *
  *  1. `explicitProfile` present → resolve id/name via `loadProfileManifest`. If

package/dist/core/profiles/select.js

@@ -7,6 +7,7 @@
 // root decision when nothing covers. This is the ONLY place that decision
 // runs; front-door.ts/
 // spawn.ts call it, never re-derive it.
+import { spawnSync } from 'node:child_process';
 import { existsSync, realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, resolve as resolvePath, sep } from 'node:path';
@@ -15,6 +16,8 @@ import { emitKeypressEvents } from 'node:readline';
 import { listProfiles, loadProfileManifest, updateProfileLastUsed, createProfile, addProfileProject, ensureRootProfile, ROOT_PROFILE_ID, } from './manifest.js';
 import { getDefaultProfileId, setDefaultProfileId, clearDefaultProfile, } from './default-binding.js';
 import { stdoutColor } from '../output.js';
+import { inTmux } from '../runtime/placement-tmux.js';
+import { surfaceTmuxStyleArgs } from '../runtime/surface-bg.js';
 import { formatBinding, matchesTerminalInput, resolveUserKeybindings, } from '../keybindings/index.js';
 const PROFILE_MENU_ACTIONS = [
     'crtr.profile.menu.abort', 'crtr.profile.menu.up', 'crtr.profile.menu.down',
@@ -24,6 +27,7 @@ const PROFILE_MENU_ACTIONS = [
     'crtr.profile.menu.slot.7', 'crtr.profile.menu.slot.8', 'crtr.profile.menu.slot.9',
     'crtr.profile.menu.create', 'crtr.profile.menu.search-existing', 'crtr.profile.menu.use-root',
     'crtr.profile.menu.set-default', 'crtr.profile.menu.add-directory', 'crtr.profile.menu.unpin',
+    'crtr.profile.menu.manage',
 ];
 const PROFILE_SEARCH_ACTIONS = [
     'crtr.profile.search.abort', 'crtr.profile.search.back', 'crtr.profile.search.pick',
@@ -133,8 +137,9 @@ const accent = stdoutColor.cyan;
 function key(k) {
     return accent(bold(k));
 }
-/** Collapse the home prefix to `~` so project paths read short. */
-function tildify(p) {
+/** Collapse the home prefix to `~` so project paths read short. Exported so the
+ *  Profiles settings panel prints a project dir exactly as this menu does. */
+export function tildify(p) {
     const home = homedir();
     if (p === home)
         return '~';
@@ -305,6 +310,34 @@ function runMenu(bindings, title, subtitle, rows, opts = {}) {
         draw();
     });
 }
+// ---------------------------------------------------------------------------
+// The profile manager. `v` on either selection gate opens the Profiles page of
+// `crtr sys settings` in a tmux popup: this menu is a CHOOSER filtered to cwd,
+// while that page is the whole map — every profile, every directory each one
+// owns, every pin. The popup runs to completion with the raw-mode menu already
+// torn down (runMenu cleans up before resolving an action), and the caller then
+// re-runs the whole selector, so a directory just adopted or a default just
+// pinned decides the menu you come back to.
+// ---------------------------------------------------------------------------
+/** Open the profiles page in a tmux popup and block until it closes. False when
+ *  there is no tmux to host it — possible only on the `crtr node new` path, as
+ *  the front door requires tmux before it ever selects — after printing the
+ *  pointer, so the caller can simply redraw its menu. */
+function openProfileManager(cwd) {
+    if (!inTmux()) {
+        process.stdout.write(`  ${dim('the profile manager needs tmux \u2014 run `crtr sys settings` instead')}\n`);
+        return false;
+    }
+    spawnSync('tmux', [
+        'display-popup', '-E', '-T', ' profiles ', '-w', '90%', '-h', '85%', '-d', cwd,
+        ...surfaceTmuxStyleArgs(),
+        'crtr sys settings --page profiles',
+    ], { stdio: 'inherit' });
+    return true;
+}
+/** The gate answering "the user managed their profiles" — every prior reading of
+ *  this directory is stale, so `selectProfileForCwd` decides again from the top. */
+const MANAGED = Symbol('profile-manager-ran');
 /** The trailing readline prompt: `  › <dim hint> `. */
 function caret(hint) {
     return `  ${accent('\u203a')} ${dim(hint)} `;
@@ -484,7 +517,17 @@ async function promptCreateOrRoot(cwd, bindings) {
     for (;;) {
         const res = await runMenu(bindings, 'No profile covers this directory', undefined, rows, {
             initialIndex: 2,
+            actionBindingIds: ['crtr.profile.menu.manage'],
+            hint: `${formatBinding(bindings, 'crtr.profile.menu.manage')}=manage profiles`,
         });
+        // Managing may have given this directory an owner — re-decide from the top
+        // rather than re-showing a menu the manager just made wrong. With no tmux to
+        // host the manager nothing changed, so fall through to a redraw.
+        if (res.action === 'crtr.profile.menu.manage') {
+            if (openProfileManager(cwd))
+                return MANAGED;
+            continue;
+        }
         if (res.index === 0) {
             const rl = createInterface({ input: process.stdin, output: process.stdout });
             try {
@@ -559,7 +602,7 @@ async function promptPickProfileOrCreate(candidates, cwd, exact, pinnedId, bindi
     rows.push({ label: dim('create a new profile here'), detail: '', bindingId: 'crtr.profile.menu.create' });
     // Row-scoped actions pin the highlighted profile, widen its purview (hidden
     // when candidates already claim cwd exactly), or clear an existing pin.
-    const actionBindingIds = ['crtr.profile.menu.set-default'];
+    const actionBindingIds = ['crtr.profile.menu.set-default', 'crtr.profile.menu.manage'];
     if (!exact)
         actionBindingIds.push('crtr.profile.menu.add-directory');
     if (pinned !== null)
@@ -569,9 +612,18 @@ async function promptPickProfileOrCreate(candidates, cwd, exact, pinnedId, bindi
         hintParts.push(`${formatBinding(bindings, 'crtr.profile.menu.add-directory')}=add dir here`);
     if (pinned !== null)
         hintParts.push(`${formatBinding(bindings, 'crtr.profile.menu.unpin')}=unpin`);
+    hintParts.push(`${formatBinding(bindings, 'crtr.profile.menu.manage')}=manage profiles`);
     const res = await runMenu(bindings, exact ? 'Choose a profile' : 'Select a profile', exact
         ? 'Several profiles claim this directory as their project'
         : 'This directory falls under existing profile(s)', rows, { actionBindingIds, hint: hintParts.join('  ') });
+    // The manager can adopt dirs, pin a default, create or delete profiles — every
+    // row here may be stale, so the caller re-resolves from the top. Without tmux
+    // nothing changed: re-show this same menu.
+    if (res.action === 'crtr.profile.menu.manage') {
+        return openProfileManager(cwd)
+            ? MANAGED
+            : await promptPickProfileOrCreate(candidates, cwd, exact, pinnedId, bindings);
+    }
     // The create row is last; selecting it (Enter on it, or `c`) creates here.
     if (res.index >= ordered.length) {
         const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -640,51 +692,59 @@ export async function selectProfileForCwd(cwd, explicitProfile, forcePicker = fa
         updateProfileLastUsed(entry.profileId);
         return entry.profileId;
     }
-    const { covering, exact, pinnedId, pinned } = profileSelectionState(resolvedCwd);
-    // A per-cwd pinned default (set from the menu with `d`) is the user's
-    // explicit "default to THIS profile HERE". It outranks both the exact-single
-    // auto-pick and global-MRU, so long as it still covers cwd; a stale pin
-    // (profile deleted, or its dir removed from purview) is self-healed away.
-    if (pinnedId !== null && pinned === null)
-        clearDefaultProfile(resolvedCwd);
-    // A valid pin decides it outright and STOPS ASKING — the whole point of
-    // setting a default. Auto-pick it silently: the crouton banner the viewer
-    // paints a beat later shows the active profile and the `crtr --pick-profile`
-    // hint, so a boot-time breadcrumb here would just be redundant.
-    // `crtr --pick-profile` (forcePicker) re-opens the menu to re-pin/unpin.
-    if (pinned !== null && !forcePicker) {
-        updateProfileLastUsed(pinned.profileId);
-        return pinned.profileId;
-    }
-    // Exactly one profile's project dir IS cwd — unambiguous project root, use it
-    // silently, never a prompt. (Several exact claims fall through to the menu.)
-    // Suppressed under forcePicker so `--pick-profile` can pin even a lone owner.
-    if (!forcePicker && pinned === null && exact.length === 1) {
-        updateProfileLastUsed(exact[0].profileId);
-        return exact[0].profileId;
-    }
-    // Non-interactive: cannot prompt. Prefer an exact claimant, else any covering
-    // profile (both MRU), else root.
-    if (!isInteractive()) {
-        const pool = exact.length > 0 ? exact : covering;
-        if (pool.length > 0) {
-            const winner = pickMostRecent(pool);
-            updateProfileLastUsed(winner.profileId);
-            return winner.profileId;
+    // Looped for the one gate that changes the world before it answers: `v` opens
+    // the profile manager, which can adopt this directory, pin a default, or
+    // create a profile — so the decision is taken again from the top rather than
+    // resumed inside a menu the manager just invalidated.
+    for (;;) {
+        const { covering, exact, pinnedId, pinned } = profileSelectionState(resolvedCwd);
+        // A per-cwd pinned default (set from the menu with `d`) is the user's
+        // explicit "default to THIS profile HERE". It outranks both the exact-single
+        // auto-pick and global-MRU, so long as it still covers cwd; a stale pin
+        // (profile deleted, or its dir removed from purview) is self-healed away.
+        if (pinnedId !== null && pinned === null)
+            clearDefaultProfile(resolvedCwd);
+        // A valid pin decides it outright and STOPS ASKING — the whole point of
+        // setting a default. Auto-pick it silently: the crouton banner the viewer
+        // paints a beat later shows the active profile and the `crtr --pick-profile`
+        // hint, so a boot-time breadcrumb here would just be redundant.
+        // `crtr --pick-profile` (forcePicker) re-opens the menu to re-pin/unpin.
+        if (pinned !== null && !forcePicker) {
+            updateProfileLastUsed(pinned.profileId);
+            return pinned.profileId;
+        }
+        // Exactly one profile's project dir IS cwd — unambiguous project root, use it
+        // silently, never a prompt. (Several exact claims fall through to the menu.)
+        // Suppressed under forcePicker so `--pick-profile` can pin even a lone owner.
+        if (!forcePicker && pinned === null && exact.length === 1) {
+            updateProfileLastUsed(exact[0].profileId);
+            return exact[0].profileId;
+        }
+        // Non-interactive: cannot prompt. Prefer an exact claimant, else any covering
+        // profile (both MRU), else root.
+        if (!isInteractive()) {
+            const pool = exact.length > 0 ? exact : covering;
+            if (pool.length > 0) {
+                const winner = pickMostRecent(pool);
+                updateProfileLastUsed(winner.profileId);
+                return winner.profileId;
+            }
+            const root = ensureRootProfile();
+            process.stderr.write(rootProfileMessage(resolvedCwd));
+            return root.profileId;
         }
-        const root = ensureRootProfile();
-        process.stderr.write(rootProfileMessage(resolvedCwd));
-        return root.profileId;
+        // Interactive. Several exact claimants → choose among them. Else covered from
+        // a parent/workspace dir → menu of covering profiles. Else nothing covers →
+        // the create-or-root prompt (root is only ever offered there).
+        const validPinnedId = pinned !== null ? pinned.profileId : null;
+        const chosen = exact.length > 1
+            ? await promptPickProfileOrCreate(exact, resolvedCwd, true, validPinnedId, bindings)
+            : covering.length > 0
+                ? await promptPickProfileOrCreate(covering, resolvedCwd, false, validPinnedId, bindings)
+                : await promptCreateOrRoot(resolvedCwd, bindings);
+        if (chosen === MANAGED)
+            continue;
+        updateProfileLastUsed(chosen);
+        return chosen;
     }
-    // Interactive. Several exact claimants → choose among them. Else covered from
-    // a parent/workspace dir → menu of covering profiles. Else nothing covers →
-    // the create-or-root prompt (root is only ever offered there).
-    const validPinnedId = pinned !== null ? pinned.profileId : null;
-    const chosen = exact.length > 1
-        ? await promptPickProfileOrCreate(exact, resolvedCwd, true, validPinnedId, bindings)
-        : covering.length > 0
-            ? await promptPickProfileOrCreate(covering, resolvedCwd, false, validPinnedId, bindings)
-            : await promptCreateOrRoot(resolvedCwd, bindings);
-    updateProfileLastUsed(chosen);
-    return chosen;
 }

package/dist/core/review/__tests__/capture-origin.test.js

@@ -1,5 +1,5 @@
 import assert from 'node:assert/strict';
-import { existsSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdtempSync, readdirSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { afterEach, test } from 'node:test';
@@ -92,7 +92,7 @@ test('detached capture takes provider/id and explicit thinking from the launch r
     const { session, sourceFile } = seededOrigin({ launchModel: 'p/m:high', thinking: 'low' });
     const captured = await capture({ launchModel: 'p/m:high', thinking: 'low' });
     assert.deepEqual(captured, {
-        sourceFile,
+        sourceFile: realpathSync(sourceFile),
         sourceSessionId: session.getSessionId(),
         leafId: session.getLeafId(),
         modelSpec: 'p/m:high',

package/dist/core/review/__tests__/stage-identity.test.js

@@ -1,5 +1,5 @@
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { afterEach, test } from 'node:test';
@@ -63,7 +63,7 @@ function setup() {
     const original = SessionManager.create(sessions);
     original.appendThinkingLevelChange('low');
     original.appendMessage(assistant('m'));
-    const sourceFile = original.getSessionFile();
+    const sourceFile = realpathSync(original.getSessionFile());
     createNode({
         node_id: 'origin',
         name: 'origin',

package/dist/core/review/companion.js

@@ -2,7 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { basename, isAbsolute, resolve } from 'node:path';
 import { BrokerClient } from '../broker-client/index.js';
-import { getNode } from '../canvas/index.js';
+import { deleteNode, getNode } from '../canvas/index.js';
 import { ensureReviewDir, reviewBranchPath } from '../canvas/paths.js';
 import { expandModelCandidates, selectInitialModelRoute } from '../model-routes.js';
 import { buildLaunchSpec } from '../runtime/launch.js';
@@ -12,6 +12,7 @@ import { spawnNode } from '../runtime/nodes.js';
 import { SessionManager } from '../runtime/broker-sdk.js';
 import { materializeSessionBranchAt } from '../runtime/session-branch.js';
 import { isReviewBoundary } from '../runtime/session-visibility.js';
+import { initializeForkContextExposure } from '../substrate/injected-store.js';
 import { ReviewOperationError } from './types.js';
 const EXACT_MODEL_SPEC = /^[^/\s:]+\/[^/\s:]+:(?:off|minimal|low|medium|high|xhigh|max)$/;
 const BIND_POLL_MS = 100;
@@ -155,7 +156,7 @@ export function spawnReviewCompanion(spec) {
         cwd: spec.cwd,
         profileId: spec.profileId,
     });
-    spawnNode({
+    const node = spawnNode({
         nodeId: spec.nodeId,
         kind: 'review/companion',
         mode: 'base',
@@ -165,6 +166,7 @@ export function spawnReviewCompanion(spec) {
         parent: spec.originNodeId,
         subscribe: false,
         forkFrom: spec.branchFile,
+        forkSourceFile: spec.branchFile,
         modelOverride: spec.modelSpec,
         reviewBinding: {
             review_id: spec.reviewId,
@@ -175,6 +177,13 @@ export function spawnReviewCompanion(spec) {
         name: `review ${basename(spec.targetFile)}`,
         launch,
     });
+    try {
+        initializeForkContextExposure(node.node_id, spec.originNodeId);
+    }
+    catch (error) {
+        deleteNode(node.node_id);
+        throw error;
+    }
 }
 /** A companion is bound only when its session coordinates and visible boundary are durable. */
 export function isReviewCompanionBound(nodeId) {

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

@@ -1,5 +1,5 @@
 import { type Cron } from '../canvas/index.js';
-import type { InjectedDocs } from '../substrate/injected-store.js';
+import type { ExposureTarget } from '../substrate/injected-store.js';
 /** The bearings custom type is shared with every attached renderer. */
 export { CONTEXT_INTRO_CUSTOM_TYPE } from '../../shared/generated-context.js';
 /** The `<project_context>` block — the `<environment>` snapshot only: a
@@ -78,4 +78,4 @@ export declare function buildWakeBearings(origin: WakeOrigin): string;
  *      AGENTS.md/CLAUDE.md injection stays suppressed (`noContextFiles` in
  *      broker.ts); `crtr sys sync project-guidance` imports that guidance into
  *      the directory's `.crouter/memory/INDEX.md` front door. */
-export declare function buildContextBearings(nodeId: string, seen?: InjectedDocs): string;
+export declare function buildContextBearings(nodeId: string, target?: ExposureTarget): string;

package/dist/core/runtime/bearings.js

@@ -346,7 +346,7 @@ function managedWorktreeNote(node) {
  *      AGENTS.md/CLAUDE.md injection stays suppressed (`noContextFiles` in
  *      broker.ts); `crtr sys sync project-guidance` imports that guidance into
  *      the directory's `.crouter/memory/INDEX.md` front door. */
-export function buildContextBearings(nodeId, seen) {
+export function buildContextBearings(nodeId, target) {
     const node = getNode(nodeId);
     const bearings = ['<crtr-bearings>', buildIdentityAssertion(nodeId)];
     const map = buildGraphMap(nodeId);
@@ -365,9 +365,9 @@ export function buildContextBearings(nodeId, seen) {
         bearings.push('', orchestratorContextNote(nodeId));
     bearings.push('</crtr-bearings>');
     // The consultable catalog rides BESIDE the bearings, not inside them.
-    const knowledge = renderKnowledgeBlock(nodeId, seen);
+    const knowledge = renderKnowledgeBlock(nodeId, target);
     // A workspace mount is the initial read of its root (`on: workspace-open`).
-    const workspaceContext = renderWorkspaceOpenDocs(nodeId, seen);
+    const workspaceContext = renderWorkspaceOpenDocs(nodeId, target);
     // Hidden applet/situation-origin ambient context (see situational-context.ts)
     // — the stored `situational` card, placed in the bearings BODY, so it is a
     // nested card inside the outer envelope. Never routed through the visible

package/dist/core/runtime/broker/daemon-ops.d.ts

@@ -1,4 +1,4 @@
-import type { BrokerExtensionStateDTO, BrokerGeneratedNameRequest, BrokerGeneratedNameResultDTO, BrokerInboxCursorDirective, BrokerInboxCursorRequest, BrokerModelCommitRequest, BrokerModelCommitResultDTO, BrokerPersonaAckRequest, BrokerSessionBoundRequest, BrokerSessionBoundResultDTO, BrokerSettleDirective, BrokerSettleRequest } from '../../../api/dto/broker-ops.js';
+import type { BrokerExtensionStateDTO, BrokerGeneratedNameRequest, BrokerGeneratedNameResultDTO, BrokerInboxCursorDirective, BrokerInboxCursorRequest, BrokerModelCommitRequest, BrokerModelCommitResultDTO, BrokerPersonaAckRequest, BrokerPersonaAckResultDTO, BrokerSessionBoundRequest, BrokerSessionBoundResultDTO, BrokerSettleDirective, BrokerSettleRequest } from '../../../api/dto/broker-ops.js';
 import type { RelaunchRootResultDTO } from '../../../api/dto/lifecycle.js';
 import type { PushReportRequest } from '../../../api/dto/reports.js';
 export declare function bindBrokerSession(nodeId: string, request: BrokerSessionBoundRequest): Promise<BrokerSessionBoundResultDTO>;
@@ -9,7 +9,7 @@ export declare function advanceBrokerInboxCursor(nodeId: string, request: Broker
 export declare function commitBrokerModel(nodeId: string, request: BrokerModelCommitRequest): Promise<BrokerModelCommitResultDTO>;
 export declare function brokerExtensionState(nodeId: string): Promise<BrokerExtensionStateDTO>;
 export declare function commitBrokerGeneratedName(nodeId: string, request: BrokerGeneratedNameRequest): Promise<BrokerGeneratedNameResultDTO>;
-export declare function commitBrokerPersonaAck(nodeId: string, request: BrokerPersonaAckRequest): Promise<void>;
+export declare function commitBrokerPersonaAck(nodeId: string, request: BrokerPersonaAckRequest): Promise<BrokerPersonaAckResultDTO>;
 /** Reports still use the canonical daemon report handler; this broker adapter
  * only preserves terminal structured output's idempotent finalization result. */
 export declare function publishBrokerReport(nodeId: string, request: PushReportRequest): Promise<void>;

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

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { jobDir } from '../../canvas/paths.js';
 import { emitEvent } from '../../events/emit.js';
 import { operationIdContext } from '../../events/operation-id.js';
+import { installPersonaTransitionGate } from '../broker-persona-guidance.js';
 import { abortSessionFromExtension } from './extension-abort.js';
 const MAX_ADMITTED_REPLACEMENTS = 2;
 const REPLACEMENT_DEADLINE_MS = 30_000;
@@ -79,6 +80,10 @@ export class RebindDriver {
             // fake-engine fixture has no `.agent`.
             const agent = candidateSession.agent;
             if (agent) {
+                installPersonaTransitionGate(this.deps.nodeId, {
+                    agent,
+                    sessionManager: candidateSession.sessionManager,
+                });
                 agent.steeringMode = 'all';
                 agent.followUpMode = 'all';
             }

package/dist/core/runtime/broker-extension-render.d.ts

@@ -1,4 +1,5 @@
-import type { InjectedDocs } from '../substrate/injected-store.js';
+import type { NodeConfigSubject } from '../substrate/subject-fields.js';
+import type { ExposureTarget } from '../substrate/injected-store.js';
 import type { BrokerExtensionNodeDTO, BrokerExtensionStateDTO } from '../../api/dto/broker-ops.js';
 export declare function editorLabelForBrokerNode(node: BrokerExtensionNodeDTO): string;
 /** Same environment-only project context rendered at normal boot, without a
@@ -7,9 +8,12 @@ export declare function buildProjectContextBlockForBroker(cwd: string): string;
 /** `situational` is the node's stored situational card, placed in the bearings
  *  BODY — the one place in the system where a runtime card nests inside
  *  another (see situational-context.ts). '' when none is set. */
-export declare function buildContextBearingsFromState(state: BrokerExtensionStateDTO, projectContext: string, situational?: string, seen?: InjectedDocs): string;
+export declare function buildContextBearingsFromState(state: BrokerExtensionStateDTO, projectContext: string, situational?: string, target?: ExposureTarget): string;
 export declare function buildForkBearingsFromState(state: BrokerExtensionStateDTO, situational?: string): string;
-export declare function renderPreferencesFromState(state: BrokerExtensionStateDTO, seen?: InjectedDocs): string;
+export declare function renderPreferencesFromState(state: BrokerExtensionStateDTO, target?: ExposureTarget): string;
+/** The same preference block without the extension-state DTO, for the daemon-side
+ * claim path that holds a node's subject directly. */
+export declare function renderPreferencesForNodeSubject(nodeId: string, subject: NodeConfigSubject | null, target?: ExposureTarget): string;
 /** A canonical report ref has already been validated by crtrd in state. The
  * broker reads only its local filesystem content; no canvas accessor is needed. */
 export declare function reportPathFromRef(ref: string, reportNodes: ReadonlyMap<string, unknown>): string | null;

package/dist/core/runtime/broker-extension-render.js

@@ -142,7 +142,7 @@ function reviewNote(node) {
 /** `situational` is the node's stored situational card, placed in the bearings
  *  BODY — the one place in the system where a runtime card nests inside
  *  another (see situational-context.ts). '' when none is set. */
-export function buildContextBearingsFromState(state, projectContext, situational = '', seen) {
+export function buildContextBearingsFromState(state, projectContext, situational = '', target) {
     const { node } = state;
     const bearings = ['<crtr-bearings>', identity(state)];
     const map = graphMap(state);
@@ -158,8 +158,8 @@ export function buildContextBearingsFromState(state, projectContext, situational
     if (node.mode === 'orchestrator')
         bearings.push('', `Because you persist across refresh cycles, your context directory (${contextDir(node.node_id)}) 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.`);
     bearings.push('</crtr-bearings>');
-    const knowledge = renderKnowledgeForSubject(state.subject, node.node_id, seen);
-    const workspace = renderWorkspaceOpenDocsForSubject(state.subject, node.cwd, node.profile_id, seen);
+    const knowledge = renderKnowledgeForSubject(state.subject, node.node_id, target);
+    const workspace = renderWorkspaceOpenDocsForSubject(state.subject, node.cwd, node.profile_id, target);
     return [bearings.join('\n'), knowledge, workspace, situational, projectContext].filter((part) => part !== '').join('\n');
 }
 export function buildForkBearingsFromState(state, situational = '') {
@@ -186,8 +186,13 @@ export function buildForkBearingsFromState(state, situational = '') {
     bearings.push('', 'The first real user message after these bearings is your mandate.', '</crtr-bearings>');
     return [bearings.join('\n'), situational].filter((part) => part !== '').join('\n');
 }
-export function renderPreferencesFromState(state, seen) {
-    return interpolateNodePaths(renderPreferencesForSubject(state.subject, seen).block, state.node.node_id);
+export function renderPreferencesFromState(state, target) {
+    return renderPreferencesForNodeSubject(state.node.node_id, state.subject, target);
+}
+/** The same preference block without the extension-state DTO, for the daemon-side
+ * claim path that holds a node's subject directly. */
+export function renderPreferencesForNodeSubject(nodeId, subject, target) {
+    return interpolateNodePaths(renderPreferencesForSubject(subject, target).block, nodeId);
 }
 /** A canonical report ref has already been validated by crtrd in state. The
  * broker reads only its local filesystem content; no canvas accessor is needed. */

package/dist/core/runtime/broker-persona-guidance.d.ts

@@ -1,13 +1,27 @@
-import type { BrokerExtensionNodeDTO } from '../../api/dto/broker-ops.js';
+import type { Agent } from '@earendil-works/pi-agent-core';
+import type { BrokerExtensionStateDTO } from '../../api/dto/broker-ops.js';
 export interface BrokerPersona {
+    kind: string;
     mode: 'base' | 'orchestrator';
     lifecycle: 'terminal' | 'resident';
 }
 export interface BrokerPersonaDrift {
     from: BrokerPersona;
     to: BrokerPersona;
-    guidance: string;
 }
-export declare function transitionGuidanceFromBrokerState(node: BrokerExtensionNodeDTO, from: BrokerPersona, to: BrokerPersona): string;
-/** Return an unacknowledged persona transition from crtrd's fixed extension state. */
-export declare function personaDriftFromBrokerState(node: BrokerExtensionNodeDTO): BrokerPersonaDrift | null;
+export declare function personaDriftFromBrokerState(state: BrokerExtensionStateDTO): BrokerPersonaDrift | null;
+/** A new context's current snapshots make a rank delta unnecessary. */
+export declare function acknowledgePersonaBaseline(state: BrokerExtensionStateDTO): Promise<boolean>;
+/** Append pending transitions until the delivered persona matches current canvas state. */
+export declare function deliverPendingPersonaTransition(initialState: BrokerExtensionStateDTO, deliver: (content: string) => void | Promise<void>): Promise<boolean>;
+interface PersonaTransitionSession {
+    agent: Pick<Agent, 'state' | 'transformContext'>;
+    sessionManager: {
+        appendCustomMessageEntry: (customType: string, content: string, display: boolean, details?: {
+            nodeId: string;
+        }) => unknown;
+    };
+}
+/** Gate each provider request on durable delivery of the current persona delta. */
+export declare function installPersonaTransitionGate(nodeId: string, session: PersonaTransitionSession): void;
+export {};