@north-light/crouter 0.3.220 → 0.3.222

package/dist/core/runtime/chat-inventory-rows.js

@@ -0,0 +1,105 @@
+import { isDeterministicCommandExpansion } from './command-expansion.js';
+const MEMORY_KINDS = new Set(['knowledge', 'preference']);
+const MEMORY_SCOPES = new Set(['node', 'project', 'profile', 'user', 'builtin']);
+function nonEmptyString(value) {
+    return typeof value === 'string' && value !== '';
+}
+/** Keep the command rows a Gateway can use. Malformed registrations are
+ * discarded individually so one producer cannot take down the inventory. */
+export function gatewayCommandRows(rows) {
+    if (!Array.isArray(rows))
+        return [];
+    const out = [];
+    for (const row of rows) {
+        if (typeof row !== 'object' || row === null)
+            continue;
+        const record = row;
+        if (record['gatewayCapable'] !== true)
+            continue;
+        const source = record['source'];
+        if (source !== 'command' && source !== 'template')
+            continue;
+        if (!nonEmptyString(record['name']) || typeof record['description'] !== 'string')
+            continue;
+        const expansion = record['expansion'];
+        const template = record['template'];
+        const argumentHint = record['argumentHint'];
+        out.push({
+            name: record['name'],
+            description: record['description'],
+            source,
+            ...(nonEmptyString(argumentHint) ? { argument_hint: argumentHint } : {}),
+            ...(isDeterministicCommandExpansion(expansion) ? { expansion } : {}),
+            ...(typeof template === 'string' ? { template } : {}),
+        });
+    }
+    return out;
+}
+export function chatInventoryCommandRows(rows) {
+    if (!Array.isArray(rows))
+        return [];
+    return rows.filter((row) => {
+        if (typeof row !== 'object' || row === null)
+            return false;
+        const record = row;
+        if (!nonEmptyString(record['name']) || typeof record['description'] !== 'string')
+            return false;
+        if (record['source'] !== 'command' && record['source'] !== 'template')
+            return false;
+        if (record['argument_hint'] !== undefined && !nonEmptyString(record['argument_hint']))
+            return false;
+        if (record['template'] !== undefined && typeof record['template'] !== 'string')
+            return false;
+        return record['expansion'] === undefined || isDeterministicCommandExpansion(record['expansion']);
+    });
+}
+export function gatewayCommandRowsFromDetail(detail) {
+    if (detail === undefined)
+        return [];
+    try {
+        return gatewayCommandRows(JSON.parse(detail));
+    }
+    catch {
+        return [];
+    }
+}
+export function chatInventoryMemoryRows(rows) {
+    if (!Array.isArray(rows))
+        return [];
+    return rows.filter((row) => {
+        if (typeof row !== 'object' || row === null)
+            return false;
+        const record = row;
+        return nonEmptyString(record['name'])
+            && typeof record['shortForm'] === 'string'
+            && typeof record['kind'] === 'string'
+            && MEMORY_KINDS.has(record['kind'])
+            && typeof record['scope'] === 'string'
+            && MEMORY_SCOPES.has(record['scope']);
+    });
+}
+export function gatewayMemoryRows(refs) {
+    if (!Array.isArray(refs))
+        return [];
+    const out = [];
+    for (const row of refs) {
+        if (typeof row !== 'object' || row === null)
+            continue;
+        const record = row;
+        if (record['gatewayVisible'] !== true)
+            continue;
+        if (!nonEmptyString(record['name']) || typeof record['shortForm'] !== 'string')
+            continue;
+        if (typeof record['kind'] !== 'string' || !MEMORY_KINDS.has(record['kind']))
+            continue;
+        if (typeof record['scope'] !== 'string' || !MEMORY_SCOPES.has(record['scope']))
+            continue;
+        out.push({
+            name: record['name'],
+            kind: record['kind'],
+            scope: record['scope'],
+            shortForm: record['shortForm'],
+        });
+    }
+    return out;
+}

package/dist/core/runtime/command-surface.d.ts

@@ -0,0 +1,38 @@
+/** The optional fields a shipped extension registration may add so its command
+ *  is disclosed to chat surfaces. Registrations cast their options through
+ *  `ChatCapableRegistration` rather than widening pi's own types. */
+export interface ChatCommandMetadata {
+    /** Present and exactly `true` to opt this command into chat disclosure. */
+    gateway?: true;
+    /** Argument shape shown beside the name, e.g. `'[args]'`. */
+    argumentHint?: string;
+}
+/** Registration options plus the preserved custom fields crouter reads back off
+ *  the resolved command. `T` is `Parameters<ExtensionAPI['registerCommand']>[1]`
+ *  at the call site. */
+export type ChatCapableRegistration<T> = T & ChatCommandMetadata;
+/** What the command disclosure needs to know about one command's chat surface. */
+export interface ChatCommandSurface {
+    gatewayCapable: boolean;
+    argumentHint?: string;
+}
+/** Read the chat surface off a resolved extension command. `command` is an
+ *  arbitrary runtime object from another package, so every field is probed
+ *  rather than trusted. */
+export declare function registrationChatSurface(command: unknown): ChatCommandSurface;
+/** Capture prompt-template chat metadata immediately after pi loads or reloads
+ *  its templates. The opt-in is the template file's own frontmatter; the hint
+ *  is pi's already-parsed `argument-hint`. A missing file, unreadable path, or
+ *  invalid YAML is not chat-capable. */
+export declare function capturePromptTemplateChatSurfaces(templates: unknown): void;
+/** Capture the Gateway capabilities declared by one completed resource load. */
+export declare function captureChatCapabilities(input: {
+    commands: unknown;
+    templates: unknown;
+}): void;
+/** Capture every startup-declared command and prompt template a session
+ *  currently exposes. A broken getter leaves that surface fail-closed. */
+export declare function captureSessionChatCapabilities(session: unknown): void;
+/** Read the chat surface captured for this loaded template. An uncaptured
+ *  template is not disclosed to chat surfaces. */
+export declare function templateChatSurface(template: unknown): ChatCommandSurface;

package/dist/core/runtime/command-surface.js

@@ -0,0 +1,117 @@
+// command-surface.ts — crouter's own metadata about the commands the engine
+// registers, and the one place that decides whether a command can complete its
+// outcome from a non-terminal chat surface.
+//
+// Eligibility is OPT-IN and fail-closed. An extension registration declares
+// `gateway: true`; a prompt template declares `gateway: true` in frontmatter.
+// Anything else — a missing flag, a malformed value, an unreadable file — is
+// not chat-capable. Capability is NEVER inferred from a command's name, its
+// source, or a hard-coded list, because the command set is whatever the active
+// VM registered, not a catalog crouter ships.
+//
+// pi keeps unknown registration fields on the resolved command object, so
+// `gateway`/`argumentHint` ride along beside `expansion` without touching pi's
+// global registration types. pi's prompt-template loader is the opposite: it
+// parses `argument-hint` into `argumentHint` and DROPS every other frontmatter
+// key. Capture `gateway` from the template file when the loader finishes, so
+// the eligibility and loaded template content share the same reload boundary.
+import { readFileSync } from 'node:fs';
+import { parseFrontmatterGeneric } from '../frontmatter.js';
+const NOT_CAPABLE = { gatewayCapable: false };
+// One resource load declares Gateway capability by extension identity and pi's
+// collision-resolved invocation name. Later registrations from that extension
+// retain only names the load declared.
+let startupGatewayNames = new WeakMap();
+// Pi drops unknown prompt frontmatter keys. This cache restores crouter's
+// metadata without re-reading a template during command disclosure.
+const templateChatSurfaces = new WeakMap();
+function hintOf(value) {
+    return typeof value === 'string' && value.trim() !== '' ? { argumentHint: value } : {};
+}
+/** Read the chat surface off a resolved extension command. `command` is an
+ *  arbitrary runtime object from another package, so every field is probed
+ *  rather than trusted. */
+export function registrationChatSurface(command) {
+    if (typeof command !== 'object' || command === null)
+        return NOT_CAPABLE;
+    const record = command;
+    const { sourceInfo, invocationName } = record;
+    if (typeof sourceInfo !== 'object' ||
+        sourceInfo === null ||
+        typeof invocationName !== 'string' ||
+        !startupGatewayNames.get(sourceInfo)?.has(invocationName))
+        return NOT_CAPABLE;
+    return { gatewayCapable: true, ...hintOf(record['argumentHint']) };
+}
+function captureExtensionCommandSurfaces(commands) {
+    startupGatewayNames = new WeakMap();
+    if (!Array.isArray(commands))
+        return;
+    for (const command of commands) {
+        if (typeof command !== 'object' || command === null)
+            continue;
+        const record = command;
+        const { sourceInfo, invocationName } = record;
+        if (record['gateway'] !== true ||
+            typeof sourceInfo !== 'object' ||
+            sourceInfo === null ||
+            typeof invocationName !== 'string')
+            continue;
+        const names = startupGatewayNames.get(sourceInfo) ?? new Set();
+        names.add(invocationName);
+        startupGatewayNames.set(sourceInfo, names);
+    }
+}
+/** Capture prompt-template chat metadata immediately after pi loads or reloads
+ *  its templates. The opt-in is the template file's own frontmatter; the hint
+ *  is pi's already-parsed `argument-hint`. A missing file, unreadable path, or
+ *  invalid YAML is not chat-capable. */
+export function capturePromptTemplateChatSurfaces(templates) {
+    if (!Array.isArray(templates))
+        return;
+    for (const template of templates) {
+        if (typeof template !== 'object' || template === null)
+            continue;
+        const { filePath, argumentHint } = template;
+        let surface = NOT_CAPABLE;
+        if (typeof filePath === 'string' && filePath !== '') {
+            try {
+                const frontmatter = parseFrontmatterGeneric(readFileSync(filePath, 'utf8')).data;
+                if (frontmatter?.['gateway'] === true)
+                    surface = { gatewayCapable: true, ...hintOf(argumentHint) };
+            }
+            catch {
+                // Fail closed for malformed or unreadable template metadata.
+            }
+        }
+        templateChatSurfaces.set(template, surface);
+    }
+}
+/** Capture the Gateway capabilities declared by one completed resource load. */
+export function captureChatCapabilities(input) {
+    captureExtensionCommandSurfaces(input.commands);
+    capturePromptTemplateChatSurfaces(input.templates);
+}
+/** Capture every startup-declared command and prompt template a session
+ *  currently exposes. A broken getter leaves that surface fail-closed. */
+export function captureSessionChatCapabilities(session) {
+    try {
+        if (typeof session !== 'object' || session === null)
+            return;
+        const value = session;
+        captureChatCapabilities({
+            commands: value.extensionRunner?.getRegisteredCommands?.(),
+            templates: value.promptTemplates,
+        });
+    }
+    catch {
+        // Fail closed when an engine cannot expose its loaded resources.
+    }
+}
+/** Read the chat surface captured for this loaded template. An uncaptured
+ *  template is not disclosed to chat surfaces. */
+export function templateChatSurface(template) {
+    if (typeof template !== 'object' || template === null)
+        return NOT_CAPABLE;
+    return templateChatSurfaces.get(template) ?? NOT_CAPABLE;
+}

package/dist/core/runtime/launch-target.d.ts

@@ -0,0 +1,25 @@
+import type { CreateNodeRequest } from '../../api/dto/nodes.js';
+import type { Mode } from '../canvas/types.js';
+import { type ProfileEntry } from '../profiles/manifest.js';
+import { buildLaunchSpecAsync } from './launch.js';
+export interface ResolvedLaunchTarget {
+    profileId: string | null;
+    profile: ProfileEntry | null;
+    kind: string;
+    mode: Mode;
+    cwd: string;
+    launch: Awaited<ReturnType<typeof buildLaunchSpecAsync>>['launch'];
+}
+export declare function resolveCreateKind(kind: string | undefined, profile: ProfileEntry | null): string;
+/** Validate a kind against the same cwd/profile configuration used to build its launch.
+ *  Resolution is subprocess-isolated: crtrd is single-threaded and a config read can
+ *  block indefinitely on a network filesystem. */
+export declare function assertLaunchKind(kind: string, cwd?: string, profileId?: string | null): Promise<void>;
+/** Resolve the exact profile, kind, cwd, mode and launch recipe a create will use. */
+export declare function resolveLaunchTarget(req: CreateNodeRequest, options?: {
+    readOnlyProfileSelection?: boolean;
+    /** Preserve an existing caller's validation boundary before target resolution. */
+    validateKind?: (kind: string) => void | Promise<void>;
+}): Promise<ResolvedLaunchTarget>;
+/** The directory a new node is pinned to. */
+export declare function resolveNodeCwd(req: CreateNodeRequest, parent: string | undefined, profileId: string | null, contextCwd: string): string;

package/dist/core/runtime/launch-target.js

@@ -0,0 +1,54 @@
+import { resolve } from 'node:path';
+import { getNode } from '../canvas/canvas.js';
+import { usage } from '../errors.js';
+import { assertProfileActive, profileHome } from '../profiles/manifest.js';
+import { buildLaunchSpecAsync, readMergedLaunchConfigAsync } from './launch.js';
+import { resolveProfileId } from './spawn.js';
+export function resolveCreateKind(kind, profile) {
+    return kind ?? profile?.manifest.default_kind ?? 'general';
+}
+/** Validate a kind against the same cwd/profile configuration used to build its launch.
+ *  Resolution is subprocess-isolated: crtrd is single-threaded and a config read can
+ *  block indefinitely on a network filesystem. */
+export async function assertLaunchKind(kind, cwd = process.cwd(), profileId = process.env['CRTR_PROFILE_ID'] || null) {
+    const kinds = Object.keys((await readMergedLaunchConfigAsync(cwd, profileId)).kinds);
+    if (!kinds.includes(kind)) {
+        throw usage(`unknown kind: ${kind}`, { received: kind, next: `Valid kinds: ${kinds.sort().join(', ')}.` });
+    }
+}
+/** Resolve the exact profile, kind, cwd, mode and launch recipe a create will use. */
+export async function resolveLaunchTarget(req, options = {}) {
+    const parent = req.parent ?? undefined;
+    const contextCwd = req.cwd ?? process.cwd();
+    const profileId = await resolveProfileId(req.profile, parent ?? null, contextCwd, {
+        readOnlySelection: options.readOnlyProfileSelection,
+    });
+    const profile = assertProfileActive(profileId);
+    const kind = resolveCreateKind(req.kind, profile);
+    await options.validateKind?.(kind);
+    const cwd = resolveNodeCwd({ ...req, kind }, parent, profileId, contextCwd);
+    if (options.validateKind === undefined)
+        await assertLaunchKind(kind, cwd, profileId);
+    const mode = (req.mode ?? 'base');
+    const launch = (await buildLaunchSpecAsync(kind, mode, {
+        lifecycle: req.root === true ? (req.root_lifecycle ?? 'resident') : 'terminal',
+        hasManager: req.root !== true,
+        ...(req.model !== undefined ? { model: req.model } : {}),
+        cwd,
+        profileId,
+    })).launch;
+    return { profileId, profile, kind, mode, cwd, launch };
+}
+/** The directory a new node is pinned to. */
+export function resolveNodeCwd(req, parent, profileId, contextCwd) {
+    if (req.pin_cwd !== undefined && req.pin_cwd !== '')
+        return resolve(req.pin_cwd);
+    if (parent != null) {
+        const spawner = getNode(parent);
+        if (spawner !== null)
+            return spawner.cwd;
+    }
+    if (req.cwd !== undefined && req.cwd !== '')
+        return resolve(req.cwd);
+    return profileHome(profileId) ?? contextCwd;
+}

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

@@ -13,6 +13,7 @@ import { basename, join } from 'node:path';
 import { InputError } from '../io.js';
 import { fullName, getNode } from '../canvas/index.js';
 import { jobDir, nodeDir, sessionPtrPath } from '../canvas/paths.js';
+import { hydratePersistedAdvertisedCommandMessages } from './advertised-command-invocation.js';
 import { SessionManager } from './broker-sdk.js';
 import { openModelRegistry } from './model-registry.js';
 import { BUILTIN_SLASH_COMMANDS } from './pi-vendored.js';
@@ -153,7 +154,11 @@ async function reconstructVisibleMessages(nodeId) {
         copyFileSync(sessionFile, copy);
         const manager = SessionManager.open(copy);
         const context = manager.buildSessionContext();
+        hydratePersistedAdvertisedCommandMessages(context.messages);
         const reconstructed = cycleAwareMessages(manager);
+        if (reconstructed !== undefined) {
+            hydratePersistedAdvertisedCommandMessages(reconstructed.map(({ message }) => message));
+        }
         const identified = reconstructed === undefined
             ? undefined
             : visibleMessages(reconstructed, { boundaryReviewId: node.review_binding?.review_id });

package/dist/core/runtime/persona.js

@@ -79,15 +79,15 @@ function baseModeGuidance() {
 }
 // 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
-// (`personas/lifecycle/{terminal,resident}.md`) and can never drift. The flip
+// (`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('lifecycle/resident');
+    return loadMemoryBody('turn-lifecycle/resident');
 }
 /** resident → terminal: owes a final, reaps when done. */
 function terminalLifecycleGuidance() {
-    return loadMemoryBody('lifecycle/terminal');
+    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).

package/dist/core/runtime/prospective-inventory-cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/runtime/prospective-inventory-cli.js

@@ -0,0 +1,61 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { DefaultResourceLoader, ExtensionRunner, getAgentDir, } from '@earendil-works/pi-coding-agent';
+import { buildRefInventory } from '../memory/inline-ref-inventory.js';
+import { gatewayCommandRows, gatewayMemoryRows } from './chat-inventory-rows.js';
+import { captureChatCapabilities, registrationChatSurface, templateChatSurface, } from './command-surface.js';
+function parseInput() {
+    const parsed = JSON.parse(readFileSync(0, 'utf8'));
+    if (typeof parsed !== 'object' || parsed === null)
+        throw new Error('preflight input must be an object');
+    const extensions = parsed.extensions;
+    if (!Array.isArray(extensions) || !extensions.every((value) => typeof value === 'string')) {
+        throw new Error('preflight input extensions must be strings');
+    }
+    return { extensions };
+}
+async function main() {
+    const { extensions } = parseInput();
+    const cwd = process.cwd();
+    const loader = new DefaultResourceLoader({
+        cwd,
+        agentDir: getAgentDir(),
+        additionalExtensionPaths: extensions,
+        noContextFiles: true,
+    });
+    await loader.reload();
+    const loaded = loader.getExtensions();
+    const templates = loader.getPrompts().prompts;
+    // getRegisteredCommands only reads extension maps and applies pi's collision
+    // naming. The unbound placeholders make every action path unavailable.
+    const runner = new ExtensionRunner(loaded.extensions, loaded.runtime, cwd, undefined, undefined);
+    const commands = runner.getRegisteredCommands();
+    captureChatCapabilities({ commands, templates });
+    const disclosures = [
+        ...commands.map((command) => {
+            const expansion = command.expansion;
+            return {
+                name: command.invocationName,
+                description: command.description ?? '',
+                source: 'command',
+                ...(expansion !== undefined ? { expansion } : {}),
+                ...registrationChatSurface(command),
+            };
+        }),
+        ...templates.map((template) => ({
+            name: template.name,
+            description: template.description,
+            source: 'template',
+            template: template.content,
+            ...templateChatSurface(template),
+        })),
+    ];
+    const memory = buildRefInventory();
+    writeFileSync(3, `${JSON.stringify({
+        commands: gatewayCommandRows(disclosures),
+        memory_refs: gatewayMemoryRows(memory.refs),
+    })}\n`);
+}
+main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});

package/dist/core/runtime/prospective-inventory.d.ts

@@ -0,0 +1,10 @@
+import type { ChatInventoryCommandDTO, ChatInventoryMemoryRefDTO } from '../../api/dto/chat-inventory.js';
+export interface ProspectiveInventoryRows {
+    commands: ChatInventoryCommandDTO[];
+    memory_refs: ChatInventoryMemoryRefDTO[];
+}
+export declare function runProspectiveInventory(input: {
+    cwd: string;
+    profileId: string | null;
+    extensions: string[];
+}): Promise<ProspectiveInventoryRows>;

package/dist/core/runtime/prospective-inventory.js

@@ -0,0 +1,88 @@
+import { spawn } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { chatInventoryCommandRows, chatInventoryMemoryRows } from './chat-inventory-rows.js';
+import { FRONT_DOOR_ENV } from './front-door-env.js';
+const PREFLIGHT_TIMEOUT_MS = 15_000;
+function entryPath() {
+    return join(dirname(fileURLToPath(import.meta.url)), 'prospective-inventory-cli.js');
+}
+function parseDocument(response) {
+    const parsed = JSON.parse(response.trim());
+    if (typeof parsed !== 'object' || parsed === null)
+        throw new Error('preflight output must be an object');
+    const record = parsed;
+    if (!Array.isArray(record['commands']) || !Array.isArray(record['memory_refs'])) {
+        throw new Error('preflight output must contain command and memory-ref arrays');
+    }
+    return {
+        commands: chatInventoryCommandRows(record['commands']),
+        memory_refs: chatInventoryMemoryRows(record['memory_refs']),
+    };
+}
+export function runProspectiveInventory(input) {
+    return new Promise((resolve, reject) => {
+        const env = {
+            ...process.env,
+            CRTR_PROFILE_ID: input.profileId ?? '',
+            [FRONT_DOOR_ENV]: '1',
+        };
+        delete env['CRTR_NODE_ID'];
+        const child = spawn(process.execPath, [entryPath()], {
+            cwd: input.cwd,
+            env,
+            stdio: ['pipe', 'pipe', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        let response = '';
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            child.kill('SIGKILL');
+            reject(new Error('prospective inventory preflight timed out'));
+        }, PREFLIGHT_TIMEOUT_MS);
+        timer.unref?.();
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        const responseStream = child.stdio[3];
+        if (responseStream === null || responseStream === undefined || !('setEncoding' in responseStream)) {
+            clearTimeout(timer);
+            child.kill('SIGKILL');
+            reject(new Error('prospective inventory preflight response channel unavailable'));
+            return;
+        }
+        responseStream.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => { stdout += chunk; });
+        child.stderr.on('data', (chunk) => { stderr += chunk; });
+        responseStream.on('data', (chunk) => { response += chunk; });
+        child.on('error', (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            reject(error);
+        });
+        child.on('close', (code, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            const diagnostics = [stderr.trim(), stdout.trim()].filter(Boolean).join('\n');
+            if (code !== 0) {
+                reject(new Error(`prospective inventory preflight exited ${code ?? signal ?? 'unknown'}${diagnostics === '' ? '' : `: ${diagnostics}`}`));
+                return;
+            }
+            try {
+                resolve(parseDocument(response));
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                reject(new Error(`${message}${diagnostics === '' ? '' : `: ${diagnostics}`}`));
+            }
+        });
+        child.stdin.end(JSON.stringify({ extensions: input.extensions }));
+    });
+}

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

@@ -88,7 +88,9 @@ export declare function resolveForkSource(value: string): string;
  *  shell, not from inside a node — there is no profile to inherit, so this runs
  *  the same startup selector the front door uses (MRU covering `cwd`, else the
  *  root-profile prompt/default). */
-export declare function resolveProfileId(explicit: string | null | undefined, spawner: string | null, cwd: string): Promise<string | null>;
+export declare function resolveProfileId(explicit: string | null | undefined, spawner: string | null, cwd: string, options?: {
+    readOnlySelection?: boolean;
+}): Promise<string | null>;
 /** Reject a permanently invalid launch recipe against the registry that will
  * serve it. Registered-but-unauthenticated/cooling requests intentionally pass
  * this authoring check so broker policy for transient availability is unchanged. */

package/dist/core/runtime/spawn.js

@@ -13,7 +13,7 @@ import { accessSync, constants, cpSync, readdirSync, existsSync, rmSync } from '
 import { isAbsolute, resolve, join } from 'node:path';
 import { spawnNode, currentNodeContext, rootOfSpine, newNodeId, preflightNodeId } from './nodes.js';
 import { loadProfileManifest } from '../profiles/manifest.js';
-import { selectProfileForCwd } from '../profiles/select.js';
+import { selectProfileForCwd, selectProfileForCwdReadOnly } from '../profiles/select.js';
 import { buildLaunchSpecAsync, buildPiArgv } from './launch.js';
 import { createManagedWorktree, rollbackManagedWorktree } from '../worktree.js';
 import { usage, brokerLaunchFailed } from '../errors.js';
@@ -153,7 +153,7 @@ export function resolveForkSource(value) {
  *  shell, not from inside a node — there is no profile to inherit, so this runs
  *  the same startup selector the front door uses (MRU covering `cwd`, else the
  *  root-profile prompt/default). */
-export async function resolveProfileId(explicit, spawner, cwd) {
+export async function resolveProfileId(explicit, spawner, cwd, options = {}) {
     if (explicit === null)
         return null;
     if (explicit !== undefined && explicit !== '') {
@@ -161,7 +161,9 @@ export async function resolveProfileId(explicit, spawner, cwd) {
     }
     if (spawner !== null)
         return getNode(spawner)?.profile_id ?? null;
-    return selectProfileForCwd(cwd);
+    return options.readOnlySelection === true
+        ? selectProfileForCwdReadOnly(cwd)
+        : selectProfileForCwd(cwd);
 }
 function requestFromLaunch(launch) {
     const intent = launch.modelIntent === undefined

package/dist/core/scope.d.ts

@@ -1,4 +1,17 @@
 import type { InstalledPlugin, Scope } from '../types.js';
+import type { ProfileProjectMemory } from '../api/dto/profiles.js';
+/** The ceiling a project root carries when no profile relationship contributes
+ *  it — the top rung, i.e. no cap at all. */
+export declare const NEUTRAL_PROJECT_MEMORY: ProfileProjectMemory;
+/** One resolved project scope root plus the selected profile relationship's
+ *  memory ceiling for it. The ceiling is INDEPENDENT of how the root was
+ *  discovered: a root reached by both cwd and a profile entry still takes that
+ *  entry's value (first entry in manifest order wins). */
+export interface ProjectScopeRoot {
+    /** Absolute path of the `.crouter/` dir. */
+    root: string;
+    memory: ProfileProjectMemory;
+}
 export declare function builtinMemoryRoot(): string;
 export declare function builtinPiPackagesDir(): string;
 export declare function builtinPiPackageDir(name: string): string;
@@ -15,10 +28,22 @@ export declare function findProjectScopeRoot(startDir?: string): string | null;
  *  selected profile (`CRTR_PROFILE_ID`); a null/unresolvable profile collapses
  *  to the single `[startDir]` pointer, reproducing today's behavior exactly.
  *  Results are cached per (resolved startDir, profileId) — `resetScopeCache()`
- *  invalidates on any profile mutation that can change project dirs or names. */
+ *  invalidates on any profile mutation that can change project dirs or names.
+ *
+ *  Each root also carries the selected profile relationship's memory ceiling
+ *  (`findProjectScopeRootsWithMemory`), a projection layered onto this order
+ *  rather than part of it: discovery provenance decides precedence, the
+ *  relationship decides the ceiling, and the two never influence each other. */
 export declare function findProjectScopeRoots(startDir?: string, profileId?: string | null): string[];
+/** `findProjectScopeRoots` with each root's profile memory ceiling attached —
+ *  same roots, same order. A root contributed by a profile entry's ancestor
+ *  walk takes that entry's `memory` (first entry in manifest order wins, even
+ *  when cwd also reaches the root); every other root takes the neutral
+ *  `content` ceiling. */
+export declare function findProjectScopeRootsWithMemory(startDir?: string, profileId?: string | null): ProjectScopeRoot[];
 export declare function projectScopeRoot(startDir?: string): string | null;
 export declare function projectScopeRoots(startDir?: string, profileId?: string | null): string[];
+export declare function projectScopeRootsWithMemory(startDir?: string, profileId?: string | null): ProjectScopeRoot[];
 export declare function scopeRoot(scope: Scope): string | null;
 export declare function requireScopeRoot(scope: Scope): string;
 export declare function ensureProjectScopeRoot(startDir?: string): string;