@north-light/crouter 0.3.219 → 0.3.221

package/dist/core/runtime/broker-protocol.d.ts

@@ -82,6 +82,10 @@ export interface HelloFrame {
     type: 'hello';
     role: ClientRole;
     client_id: string;
+    /** Whether this socket represents a person attending the conversation. Defaults
+     * true for backward compatibility; system observers set false without changing
+     * their read-only `role`. */
+    attends?: boolean;
     /** Per-attach welcome transcript bound; absent or invalid keeps the full history. */
     snapshot_tail?: number;
     /** Terminal geometry of a tmux-pane viewer; absent for a headless client. */
@@ -404,6 +408,11 @@ export interface ModelChangedFrame {
      *  frames still parse. */
     spec?: string | null;
 }
+/** Broadcast to attached observers after a successful reload has cleared the
+ *  command and memory inventories. */
+export interface ResourcesReloadedFrame {
+    type: 'resources_reloaded';
+}
 /** The `error` control frame. SOURCED from the shared `@north-light/crouter-api`
  *  contract (`src/api/dto/broker.ts`, the same zero-runtime-dep `/v1` module
  *  Northlight Core imports) so the wire shape here and the shape Core consumes
@@ -504,12 +513,14 @@ export interface WireSettings extends SettingsConfig {
  *  `'taste/foo'`) and what `crtr memory read <name>` expects; `scope` is the
  *  WINNING scope after first-wins-by-name precedence dedup (display only —
  *  resolution is by `name` alone). No body/source path: this is a metadata-only
- *  inventory, never the document content. */
+ *  inventory, never the document content. `gatewayVisible` is broker-computed
+ *  chat-surface eligibility; terminal viewers retain every row. */
 export interface RefMeta {
     name: string;
     kind: 'knowledge' | 'preference';
     scope: 'node' | 'project' | 'profile' | 'user' | 'builtin';
     shortForm: string;
+    gatewayVisible: boolean;
 }
 export interface ListModelsData {
     type: 'data';
@@ -626,7 +637,7 @@ export interface ToolGroupSummaryFrame {
 /** Everything the broker can send. Live `AgentSessionEvent`s are relayed
  *  verbatim (the broker adds nothing); the broker's own control frames carry
  *  non-colliding `type` discriminants. */
-export type BrokerToClient = WelcomeFrame | WorkingActivityFrame | ModelChangedFrame | ErrorFrame | NodeNamedFrame | AckFrame | BrokerDataFrame | BashStartFrame | BashOutputFrame | BashEndFrame | ExtensionUIRequestFrame | ExtensionUIDismissFrame | ToolGroupSummaryFrame | AgentSessionEvent;
+export type BrokerToClient = WelcomeFrame | WorkingActivityFrame | ModelChangedFrame | ResourcesReloadedFrame | ErrorFrame | NodeNamedFrame | AckFrame | BrokerDataFrame | BashStartFrame | BashOutputFrame | BashEndFrame | ExtensionUIRequestFrame | ExtensionUIDismissFrame | ToolGroupSummaryFrame | AgentSessionEvent;
 /** Encode one frame as a single newline-terminated JSON line. */
 export declare function encodeFrame(frame: ClientToBroker | BrokerToClient): string;
 /** Byte bounds for a {@link FrameDecoder} (C5). */

package/dist/core/runtime/broker.js

@@ -31,6 +31,7 @@ import { FRONT_DOOR_ENV } from './front-door.js';
 import { CANVAS_EXTENSIONS, piInvocationToSdkConfig, } from './launch.js';
 import { assertEngineVersion, loadBrokerEngine } from './broker-sdk.js';
 import { resolveBundledPiPackageDir } from './pi-cli.js';
+import { captureSessionPromptTemplateChatSurfaces } from './command-surface.js';
 import { PoolCredentialStore } from '../pool-credential-store.js';
 import { clearCleanAbort, markBusy, markCleanAbort } from './busy.js';
 import { recordFaultForCurrentNode } from './fault.js';
@@ -45,7 +46,8 @@ import { ToolGroupTracker } from './broker/tool-groups.js';
 import { onNodeNamed } from './broker/node-named.js';
 import { FaultRetry } from './broker/fault-retry.js';
 import { EventProjection } from './broker/event-projection.js';
-import { createFrameDispatchContext, handleFrame } from './broker/frame-dispatch.js';
+import { createFrameDispatchContext, handleFrame, } from './broker/frame-dispatch.js';
+import { hydratePersistedAdvertisedCommandMessages, installAdvertisedCommandInvocationContract, } from './advertised-command-invocation.js';
 import { RebindDriver } from './broker/rebind.js';
 import { brokerExtensionState, commitBrokerModel } from './broker/daemon-ops.js';
 import { FrameOverflowError, normalizeSnapshotTail, } from './broker-protocol.js';
@@ -715,6 +717,9 @@ export function snapshotMessages(session, boundaryReviewId) {
     // `crtr-cycle` marker's `{cycle, fromLeaf}` shape — the fields we read off it
     // are ones ONLY this module's own `appendCustomEntry` call (above) ever writes.
     const messages = cycleAwareMessages(session.sessionManager);
+    if (messages !== undefined) {
+        hydratePersistedAdvertisedCommandMessages(messages.map(({ message }) => message));
+    }
     return messages === undefined ? undefined : visibleMessages(messages, { boundaryReviewId });
 }
 // ---------------------------------------------------------------------------
@@ -893,6 +898,10 @@ export async function buildBrokerSession(engine, cfg) {
             tools: cfg.tools,
             sessionStartEvent: o.sessionStartEvent,
         });
+        installAdvertisedCommandInvocationContract(created.session);
+        // The resource loader has completed its initial template load. Capture
+        // crouter-only template metadata before command disclosure can observe it.
+        captureSessionPromptTemplateChatSurfaces(created.session);
         // CONSTRUCTION-ONLY MASK — see modelLessRegistry: reveal now that model
         // selection (construction-time only) is done, so a later /login re-drive's
         // list_models/cycle_model/provider-rotation see the real registry.

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

@@ -0,0 +1,33 @@
+/** 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 every prompt template a session currently exposes. A broken getter
+ *  leaves its templates uncaptured and therefore fail-closed. */
+export declare function captureSessionPromptTemplateChatSurfaces(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,81 @@
+// 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 };
+// 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;
+    if (record['gateway'] !== true)
+        return NOT_CAPABLE;
+    return { gatewayCapable: true, ...hintOf(record['argumentHint']) };
+}
+/** 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 every prompt template a session currently exposes. A broken getter
+ *  leaves its templates uncaptured and therefore fail-closed. */
+export function captureSessionPromptTemplateChatSurfaces(session) {
+    try {
+        if (typeof session !== 'object' || session === null)
+            return;
+        capturePromptTemplateChatSurfaces(session.promptTemplates);
+    }
+    catch {
+        // Fail closed when an engine cannot expose its prompt templates.
+    }
+}
+/** 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/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/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;

package/dist/core/scope.js

@@ -6,6 +6,9 @@ import { assetRoot } from './asset-root.js';
 import { usage } from './errors.js';
 import { loadProfileManifest } from './profiles/manifest.js';
 import { realpathOrSelf } from './fs-utils.js';
+/** The ceiling a project root carries when no profile relationship contributes
+ *  it — the top rung, i.e. no cap at all. */
+export const NEUTRAL_PROJECT_MEMORY = 'content';
 // Cache of resolved project-scope-root STACKS, keyed by (resolved cwd, profile
 // id). A profile widens the pointer set beyond the bare cwd (see
 // findProjectScopeRoots below), so the cache key must carry both — the same
@@ -13,7 +16,8 @@ import { realpathOrSelf } from './fs-utils.js';
 // `resetScopeCache()` (called by every profile mutation in
 // src/core/profiles/manifest.ts) clears the whole cache; there is no
 // per-entry invalidation because a profile edit can change which pointer set
-// any cached cwd belongs to.
+// any cached cwd belongs to. Path-only callers read `roots`, which is the same
+// array in the same order as `annotated`.
 const scopeRootsCache = new Map();
 function scopeRootsCacheKey(resolvedStartDir, profileId) {
     return `${resolvedStartDir}\u0000${profileId ?? ''}`;
@@ -94,19 +98,40 @@ function collectAncestorScopeRoots(startDir, userRoot) {
  *  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 function findProjectScopeRoots(startDir = process.cwd(), profileId = process.env['CRTR_PROFILE_ID'] || null) {
+    return resolveProjectScopeRoots(startDir, profileId).roots;
+}
+/** `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 function findProjectScopeRootsWithMemory(startDir = process.cwd(), profileId = process.env['CRTR_PROFILE_ID'] || null) {
+    return resolveProjectScopeRoots(startDir, profileId).annotated;
+}
+function resolveProjectScopeRoots(startDir, profileId) {
     const resolvedStart = resolve(startDir);
     const key = scopeRootsCacheKey(resolvedStart, profileId);
     const cached = scopeRootsCache.get(key);
     if (cached !== undefined)
         return cached;
     const userRoot = userScopeRoot();
-    const pointers = [resolvedStart];
+    // A null `memory` marks the cwd pointer: it decides precedence like any
+    // other pointer but contributes no ceiling.
+    const pointers = [
+        { dir: resolvedStart, memory: null },
+    ];
     if (profileId !== null && profileId !== '') {
         try {
             const { manifest } = loadProfileManifest(profileId);
-            pointers.push(...manifest.projects);
+            for (const project of manifest.projects)
+                pointers.push({ dir: project.path, memory: project.memory });
         }
         catch {
             // Missing/deleted/invalid profile: this is a hot path every memory and
@@ -116,16 +141,23 @@ export function findProjectScopeRoots(startDir = process.cwd(), profileId = proc
     }
     const seen = new Set();
     const roots = [];
+    const caps = new Map();
     for (const pointer of pointers) {
-        for (const root of collectAncestorScopeRoots(pointer, userRoot)) {
-            if (seen.has(root))
-                continue;
-            seen.add(root);
-            roots.push(root);
+        for (const root of collectAncestorScopeRoots(pointer.dir, userRoot)) {
+            if (!seen.has(root)) {
+                seen.add(root);
+                roots.push(root);
+            }
+            // Independent of the order dedupe above: a root already discovered from
+            // cwd still takes the first profile entry's ceiling.
+            if (pointer.memory !== null && !caps.has(root))
+                caps.set(root, pointer.memory);
         }
     }
-    scopeRootsCache.set(key, roots);
-    return roots;
+    const annotated = roots.map((root) => ({ root, memory: caps.get(root) ?? NEUTRAL_PROJECT_MEMORY }));
+    const entry = { roots, annotated };
+    scopeRootsCache.set(key, entry);
+    return entry;
 }
 export function projectScopeRoot(startDir) {
     return findProjectScopeRoot(startDir);
@@ -133,6 +165,9 @@ export function projectScopeRoot(startDir) {
 export function projectScopeRoots(startDir, profileId) {
     return findProjectScopeRoots(startDir, profileId);
 }
+export function projectScopeRootsWithMemory(startDir, profileId) {
+    return findProjectScopeRootsWithMemory(startDir, profileId);
+}
 export function scopeRoot(scope) {
     // The builtin scope has no scope-root dir; its content lives in dedicated
     // package directories such as builtinMemoryRoot().
@@ -160,7 +195,12 @@ export function ensureProjectScopeRoot(startDir = process.cwd()) {
     const resolvedStart = resolve(startDir);
     const root = join(resolvedStart, CRTR_DIR_NAME);
     const profileId = process.env['CRTR_PROFILE_ID'] || null;
-    scopeRootsCache.set(scopeRootsCacheKey(resolvedStart, profileId), [root]);
+    // Neutral ceiling: the empty cached stack proves no profile entry's ancestor
+    // walk reached this root, since it did not exist to be walked into.
+    scopeRootsCache.set(scopeRootsCacheKey(resolvedStart, profileId), {
+        roots: [root],
+        annotated: [{ root, memory: NEUTRAL_PROJECT_MEMORY }],
+    });
     return root;
 }
 export function pluginsDir(scope) {

package/dist/core/substrate/on-read.d.ts

@@ -15,7 +15,13 @@ export declare function renderOnReadDocsForSubject(subject: NodeConfigSubject, r
 /** Workspace boot docs using the snapshot's cwd/profile instead of a canvas
  * lookup. `seen` is the transcript-scoped dedup set shared with the on-read
  * hook, so a front door delivered here never re-delivers on a later read
- * beneath its store. */
+ * beneath its store.
+ *
+ * Each candidate's authored rung is clamped to its project's profile
+ * relationship cap BEFORE the `none` filter, the ordering, the render, and the
+ * seen-map recording — so a capped doc never renders above its cap, a `none`
+ * project contributes nothing, and a later explicit `crtr memory read` can
+ * still upgrade what workspace-open disclosed at a lower rung. */
 export declare function renderWorkspaceOpenDocsForSubject(subject: NodeConfigSubject, cwd: string, profileId: string | null, seen?: InjectedDocs): string;
 /** Inner `<memory>` blocks for the memory-read event: docs whose
  * `memory-read` entries match the doc a `crtr memory read` just resolved

package/dist/core/substrate/on-read.js

@@ -33,11 +33,11 @@ import { CRTR_DIR_NAME } from '../../types.js';
 import { pathExists, readText, walkFiles } from '../fs-utils.js';
 import { parseFrontmatterGeneric } from '../frontmatter.js';
 import { listAllMemoryDocs, listProjectMemoryDocs } from '../memory-resolver.js';
-import { userScopeRoot } from '../scope.js';
+import { NEUTRAL_PROJECT_MEMORY, userScopeRoot } from '../scope.js';
 import { gatePasses } from './gate.js';
 import { commandDeliveryRung, memoryReadDeliveryRung, owningRootOf, readDeliveryRung, workspaceOpenRung } from './surface-match.js';
 import { deliveredAtOrAbove, recordDelivery } from './injected-store.js';
-import { normalizeDocName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, resolveDocName } from './schema.js';
+import { minRung, normalizeDocName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, resolveDocName } from './schema.js';
 import { cachedSubstrateDocsInclusive } from './session-cache.js';
 import { realpathOrSelf } from '../fs-utils.js';
 const JUNK_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.cache', '.yalc']);
@@ -91,6 +91,9 @@ function loadProjectDoc(file, memoryDir) {
             scope: 'project',
             path: file,
             body,
+            // The read event is uncapped by design: this walk is reached only by an
+            // explicit file read, never by automatic boot/workspace-open delivery.
+            projectMemory: NEUTRAL_PROJECT_MEMORY,
         };
     }
     catch {
@@ -244,7 +247,13 @@ export function renderOnReadDocsForSubject(subject, readFilePath, seen = new Map
 /** Workspace boot docs using the snapshot's cwd/profile instead of a canvas
  * lookup. `seen` is the transcript-scoped dedup set shared with the on-read
  * hook, so a front door delivered here never re-delivers on a later read
- * beneath its store. */
+ * beneath its store.
+ *
+ * Each candidate's authored rung is clamped to its project's profile
+ * relationship cap BEFORE the `none` filter, the ordering, the render, and the
+ * seen-map recording — so a capped doc never renders above its cap, a `none`
+ * project contributes nothing, and a later explicit `crtr memory read` can
+ * still upgrade what workspace-open disclosed at a lower rung. */
 export function renderWorkspaceOpenDocsForSubject(subject, cwd, profileId, seen = new Map()) {
     let docs;
     try {
@@ -256,7 +265,7 @@ export function renderWorkspaceOpenDocsForSubject(subject, cwd, profileId, seen
         return '';
     }
     const candidates = dedupeByPhysicalPath(docs)
-        .map((doc) => ({ doc, rung: workspaceOpenRung(doc) }))
+        .map((doc) => ({ doc, rung: minRung(workspaceOpenRung(doc), doc.projectMemory) }))
         .filter(({ rung }) => rung !== 'none')
         .sort((a, b) => {
         const aRoot = owningRootOf(a.doc) ?? '';

package/dist/core/substrate/render.js

@@ -57,14 +57,14 @@ import { subKindsAvailableTo } from '../config.js';
 import { parseFrontmatterGeneric } from '../frontmatter.js';
 import { pathExists, readText, realpathOrSelf, walkFiles } from '../fs-utils.js';
 import { memoryDir } from '../runtime/memory.js';
-import { projectScopeRoots } from '../scope.js';
+import { NEUTRAL_PROJECT_MEMORY, projectScopeRoots } from '../scope.js';
 import { gatePasses } from './gate.js';
 // De-barreled to LEAF modules on purpose: importing from './index.js' would
 // pull subject.js (canvas-db) transitively, re-tainting every CLI consumer of
 // the pure render fns. The canvas-db wrappers (renderPreferencesSection /
 // renderKnowledgeBlock) live in render-node.js instead.
 import { recordDelivery } from './injected-store.js';
-import { bootRung, normalizeDocName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, resolveDocName, rungRank, } from './schema.js';
+import { bootRung, minRung, normalizeDocName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, resolveDocName, rungRank, } from './schema.js';
 import { cachedSubstrateDocs } from './session-cache.js';
 /** First-wins dedup by (already-normalized) name, preserving the input's
  *  precedence order. The array's ORDER is the precedence signal — callers must
@@ -89,7 +89,13 @@ function dedupeFirstWins(docs) {
  *  selection ONLY; display ordering is a separate, later step (see
  *  renderGrouped) so a builtin doc can never mask a project/user override by
  *  virtue of sorting first. Uses the per-session cache so the full corpus is
- *  scanned + parsed at most once per session across the boot-render calls. */
+ *  scanned + parsed at most once per session across the boot-render calls.
+ *
+ *  The profile relationship's cap applies HERE, before dedup: a `none` project
+ *  leaves the corpus entirely (it contributes nothing, not even a `[+N more]`
+ *  count, and so cannot shadow a wider-scope automatic winner), and every
+ *  surviving doc's authored boot rung is clamped to its cap before dedup, the
+ *  session cache, and delivery seeding see it. */
 function selectWinners(subject, kind) {
     let docs;
     try {
@@ -100,8 +106,9 @@ function selectWinners(subject, kind) {
     }
     const eligible = docs
         .filter((d) => d.kind === kind)
+        .filter((d) => d.projectMemory !== 'none')
         .filter((d) => gatePasses(d, subject))
-        .map((d) => ({ ...d, bootRung: bootRung(d) }));
+        .map((d) => ({ ...d, bootRung: minRung(bootRung(d), d.projectMemory) }));
     return dedupeFirstWins(eligible);
 }
 // ---------------------------------------------------------------------------
@@ -238,7 +245,9 @@ function nodeLocalDocs(nodeId, subject) {
             // node-local is NOT a resolver scope; `scope` is a placeholder never read
             // by gate eval (keyed off the NODE subject, not the doc) nor by the
             // renderers (keyed off name / body / rung).
-            out.push({ ...schema, name, scope: 'user', path: file, body });
+            // Node-local is not a project store: no profile relationship names it,
+            // so it carries the neutral ceiling.
+            out.push({ ...schema, name, scope: 'user', path: file, body, projectMemory: NEUTRAL_PROJECT_MEMORY });
         }
         catch {
             // A single malformed file is skipped, never fatal to the render.

package/dist/core/substrate/schema.d.ts

@@ -1,14 +1,18 @@
+import { type ProfileProjectMemory } from '../../api/dto/profiles.js';
 import type { MemoryDoc, MemoryScope } from '../memory-resolver.js';
 export declare const KINDS: readonly ["knowledge", "preference"];
 export type DocKind = (typeof KINDS)[number];
 /** Is `v` one of the two valid document kinds? */
 export declare function isDocKind(v: unknown): v is DocKind;
 export declare const RUNGS: readonly ["none", "name", "preview", "content"];
-export type Rung = (typeof RUNGS)[number];
+export type Rung = ProfileProjectMemory;
 /** Ordinal of a rung on the ladder (none=0 … content=3). */
 export declare function rungRank(r: Rung): number;
 /** Does rung `r` disclose at least as much as `min`? */
 export declare function rungAtLeast(r: Rung, min: Rung): boolean;
+/** The lower of two rungs — the clamp automatic delivery applies to an
+ *  authored rung against its project relationship's cap. */
+export declare function minRung(a: Rung, b: Rung): Rung;
 /** Strip an optional `NN-` ordering prefix from ONE path segment (file or
  *  directory display name). `00-runtime-base` -> `runtime-base`; `spine` (no
  *  prefix) is unchanged. */
@@ -111,6 +115,12 @@ export interface SubstrateDoc extends SubstrateSchema {
     path: string;
     /** Document body, frontmatter stripped. */
     body: string;
+    /** The selected profile relationship's cap on the project store this doc
+     *  resolved from — the maximum rung automatic boot and workspace-open
+     *  delivery may disclose it at. `content` is the neutral ceiling every
+     *  non-project doc and every uncapped project root carries. Targeted reads,
+     *  command routing, and directory listings ignore it. */
+    projectMemory: ProfileProjectMemory;
 }
 /** Parse a raw frontmatter record (from `parseFrontmatterGeneric`, via the
  *  resolver) into a typed schema with defaults applied. Returns `null` when the

package/dist/core/substrate/schema.js

@@ -7,6 +7,7 @@
 // The runtime parser is tolerant by contract (it maps over many docs and must
 // never throw): invalid `surfaces` entries are dropped rather than crashing a
 // render, and `crtr memory lint` owns strict authoring-time enforcement.
+import { PROFILE_PROJECT_MEMORY_VALUES } from '../../api/dto/profiles.js';
 // ---------------------------------------------------------------------------
 // Kinds — the two semantic kinds (design §3): `knowledge` (consult — procedural
 // playbooks + factual references merged) vs `preference` (behave — standing
@@ -22,7 +23,10 @@ export function isDocKind(v) {
 // each rung is a superset of disclosure over the one before:
 //   none < name < preview < content
 // ---------------------------------------------------------------------------
-export const RUNGS = ['none', 'name', 'preview', 'content'];
+// The ladder is ONE union, owned by the public API DTO (`ProfileProjectMemory`)
+// so a profile relationship's cap and a doc's authored rung are the same values
+// and clamp against each other without a conversion.
+export const RUNGS = PROFILE_PROJECT_MEMORY_VALUES;
 /** Ordinal of a rung on the ladder (none=0 … content=3). */
 export function rungRank(r) {
     return RUNGS.indexOf(r);
@@ -31,6 +35,11 @@ export function rungRank(r) {
 export function rungAtLeast(r, min) {
     return rungRank(r) >= rungRank(min);
 }
+/** The lower of two rungs — the clamp automatic delivery applies to an
+ *  authored rung against its project relationship's cap. */
+export function minRung(a, b) {
+    return rungRank(a) <= rungRank(b) ? a : b;
+}
 // ---------------------------------------------------------------------------
 // Display-name normalization — the optional `NN-` ordering pin. A doc's
 // physical path may carry a two-digit numeric prefix on a file or directory
@@ -133,7 +142,7 @@ export function parseSubstrateDoc(doc) {
     const schema = parseSubstrateFrontmatter(doc.frontmatter);
     if (schema === null)
         return null;
-    return { ...schema, name: doc.name, scope: doc.scope, path: doc.path, body: doc.body };
+    return { ...schema, name: doc.name, scope: doc.scope, path: doc.path, body: doc.body, projectMemory: doc.projectMemory };
 }
 /** The kind a doc resolves to for `--kind` filtering/matching: the substrate
  *  kind when the frontmatter parses as a valid substrate doc, else the raw

package/dist/daemon/api/__tests__/profile-launch-gates.test.js

@@ -42,7 +42,7 @@ after(() => {
     resetScopeCache();
 });
 test('create rejects a paused profile before a node exists', async () => {
-    const profile = createProfile('paused profile', [cwd]);
+    const profile = createProfile('paused profile', [{ path: cwd, memory: 'content' }]);
     pauseProfile(profile.profileId);
     const ctx = {
         method: 'POST',
@@ -62,7 +62,7 @@ test('create rejects a paused profile before a node exists', async () => {
     assert.equal(listNodes().length, beforeRows);
 });
 test('revive refuses a paused profile before launching a broker', () => {
-    const profile = createProfile('paused revive', [cwd]);
+    const profile = createProfile('paused revive', [{ path: cwd, memory: 'content' }]);
     pauseProfile(profile.profileId);
     const nodeId = 'paused-revive-node';
     createNode({
@@ -90,7 +90,7 @@ test('revive refuses a paused profile before launching a broker', () => {
 // because they all reach the canvas through spawnNode and none of them call
 // handleCreate.
 test('the birth gate refuses a paused profile for a daemon-side spawn', () => {
-    const profile = createProfile('paused spawn', [cwd]);
+    const profile = createProfile('paused spawn', [{ path: cwd, memory: 'content' }]);
     pauseProfile(profile.profileId);
     const beforeRows = listNodes().length;
     assert.throws(() => spawnNode({ kind: 'general', cwd, parent: null, profile_id: profile.profileId }), (error) => {
@@ -102,7 +102,7 @@ test('the birth gate refuses a paused profile for a daemon-side spawn', () => {
     assert.equal(listNodes().length, beforeRows);
 });
 test('create kind resolves from the profile default when omitted', () => {
-    const profile = createProfile('default kind', [cwd]);
+    const profile = createProfile('default kind', [{ path: cwd, memory: 'content' }]);
     setProfileDefaultKind(profile.profileId, 'developer');
     const entry = loadProfileManifest(profile.profileId);
     assert.equal(resolveCreateKind(undefined, entry), 'developer');

package/dist/daemon/api/handlers/chat-inventory.d.ts

@@ -0,0 +1,2 @@
+import type { RouteTable } from '../router.js';
+export declare const chatInventoryRoutes: RouteTable;

package/dist/daemon/api/handlers/chat-inventory.js

@@ -0,0 +1,25 @@
+// Chat-inventory handler. `GET /v1/nodes/{id}/chat-inventory` answers what a
+// non-terminal chat surface may offer for one node: the slash commands its live
+// engine registered that opted into chat disclosure, and the memory documents an
+// inline `/name` token resolves to.
+//
+// Read-only in both directions — it takes one observer round trip against a
+// broker that is already running and writes no canvas state. A node whose broker
+// is not live answers 200 with `broker_live: false` and empty arrays rather than
+// 404 or a revival: "this node has nothing to offer right now" is a normal
+// answer, not an error.
+import { getNode } from '../../../core/canvas/canvas.js';
+import { isSafeNodeId } from '../../../core/canvas/paths.js';
+import { notFound, usage } from '../../../core/errors.js';
+import { readChatInventory } from '../../../core/runtime/broker-inventory.js';
+async function handleGet(ctx) {
+    const id = ctx.params['id'];
+    if (!isSafeNodeId(id))
+        throw usage(`invalid node id: ${id}`, { received: id });
+    if (getNode(id) === null)
+        throw notFound(`unknown node: ${id}`, { received: id });
+    return { status: 200, body: await readChatInventory(id) };
+}
+export const chatInventoryRoutes = [
+    { method: 'GET', pattern: '/v1/nodes/:id/chat-inventory', handler: handleGet },
+];