@crouton-kit/crouter 0.3.61 → 0.3.63

package/dist/core/canvas/render.js

@@ -174,6 +174,73 @@ export function renderForest() {
     }
     return parts.join('\n\n');
 }
+async function nodeLineFromSource(source, nodeId, indent, connector) {
+    const node = await source.getNode(nodeId);
+    if (node === null)
+        return `${indent}${connector}? <missing meta: ${nodeId}>`;
+    const hanging = hangingFor(node);
+    const glyph = resolveNodeVisual(node.status, { hanging }).glyph;
+    const tel = readNodeTelemetry(nodeId);
+    const ctx = fmtCtx(tel.tokens_in);
+    const asks = countAsks(nodeId);
+    const askSuffix = asks > 0 ? ` ⚑${asks}` : '';
+    const faultSuffix = hanging !== null ? ` · ${faultSummary(hanging)}` : '';
+    return `${indent}${connector}${glyph} ${fullName(node)} [${node.kind}/${node.mode}] ctx ${ctx}${askSuffix}${faultSuffix}`;
+}
+async function walkTreeFromSource(source, nodeId, indent, isLast, visited, out) {
+    if (visited.has(nodeId))
+        return;
+    visited.add(nodeId);
+    const connector = isLast ? '└─ ' : '├─ ';
+    out.push(await nodeLineFromSource(source, nodeId, indent, connector));
+    const children = await source.subscriptionsOf(nodeId).catch(() => []);
+    const childIndent = indent + (isLast ? '   ' : '│  ');
+    for (let i = 0; i < children.length; i++) {
+        const child = children[i];
+        const childIsLast = i === children.length - 1;
+        if (visited.has(child.node_id)) {
+            const cycleConnector = childIsLast ? '└─ ' : '├─ ';
+            out.push(`${childIndent}${cycleConnector}↺ <cycle: ${child.node_id}>`);
+            continue;
+        }
+        await walkTreeFromSource(source, child.node_id, childIndent, childIsLast, visited, out);
+    }
+}
+export async function renderTreeFromSource(source, rootId) {
+    const node = await source.getNode(rootId);
+    if (node === null)
+        return `? <missing node: ${rootId}>`;
+    const tel = readNodeTelemetry(rootId);
+    const ctx = fmtCtx(tel.tokens_in);
+    const asks = countAsks(rootId);
+    const askSuffix = asks > 0 ? ` ⚑${asks}` : '';
+    const hanging = hangingFor(node);
+    const glyph = resolveNodeVisual(node.status, { hanging }).glyph;
+    const faultSuffix = hanging !== null ? ` · ${faultSummary(hanging)}` : '';
+    const out = [];
+    out.push(`${glyph} ${fullName(node)} [${node.kind}/${node.mode}] ctx ${ctx}${askSuffix}${faultSuffix}`);
+    const visited = new Set([rootId]);
+    const children = await source.subscriptionsOf(rootId).catch(() => []);
+    for (let i = 0; i < children.length; i++) {
+        const child = children[i];
+        const isLast = i === children.length - 1;
+        await walkTreeFromSource(source, child.node_id, '', isLast, visited, out);
+    }
+    return out.join('\n');
+}
+export async function renderForestFromSource(source) {
+    const all = await source.listNodes();
+    if (all.length === 0)
+        return '(canvas is empty)';
+    const roots = all.filter((n) => n.parent === null && (n.status === 'active' || n.status === 'idle'));
+    if (roots.length === 0)
+        return '(no live roots)';
+    const parts = [];
+    for (const r of roots) {
+        parts.push(await renderTreeFromSource(source, r.node_id));
+    }
+    return parts.join('\n\n');
+}
 /** The spawn prompt, read straight off disk (canvas-home state) and capped so a
  *  giant initial-prompt.md can't bloat the snapshot. Mirrors how telemetry is
  *  read here directly rather than via the runtime layer (which would invert the
@@ -433,26 +500,31 @@ function sessionMtime(nodeId, created) {
  */
 export function dashboardRowsAll() {
     const focusedNodeIds = new Set(listFocuses().map((f) => f.node_id));
-    return listNodes().map((row) => {
-        const live = row.status === 'active' || row.status === 'idle';
-        const hanging = activeFaultForDisplay(row, readFault(row.node_id));
-        return {
-            node_id: row.node_id,
-            name: row.name, // handle only; enrichRow upgrades to fullName (meta.description)
-            status: row.status,
-            kind: row.kind,
-            mode: row.mode,
-            ctx_tokens: 0, // lazy: enrichRow
-            asks: 0, // lazy: enrichRow / enrichRows
-            cwd: row.cwd,
-            created: row.created,
-            lifecycle: row.lifecycle,
-            mtimeMs: sessionMtime(row.node_id, row.created),
-            streaming: hanging === null && live ? isStreaming(row.node_id, row.pi_pid) : false,
-            hanging,
-            viewed: focusedNodeIds.has(row.node_id),
-        };
-    });
+    return listNodes().map((row) => dashboardRowFromNodeRow(row, focusedNodeIds));
+}
+function dashboardRowFromNodeRow(row, focusedNodeIds) {
+    const live = row.status === 'active' || row.status === 'idle';
+    const hanging = activeFaultForDisplay(row, readFault(row.node_id));
+    return {
+        node_id: row.node_id,
+        name: row.name, // handle only; enrichRow upgrades to fullName (meta.description)
+        status: row.status,
+        kind: row.kind,
+        mode: row.mode,
+        ctx_tokens: 0, // lazy: enrichRow
+        asks: 0, // lazy: enrichRow / enrichRows
+        cwd: row.cwd,
+        created: row.created,
+        lifecycle: row.lifecycle,
+        mtimeMs: sessionMtime(row.node_id, row.created),
+        streaming: hanging === null && live ? isStreaming(row.node_id, row.pi_pid) : false,
+        hanging,
+        viewed: focusedNodeIds.has(row.node_id),
+    };
+}
+export async function dashboardRowsAllFromSource(source) {
+    const focusedNodeIds = new Set(listFocuses().map((f) => f.node_id));
+    return (await source.listNodes()).map((row) => dashboardRowFromNodeRow(row, focusedNodeIds));
 }
 // ---------------------------------------------------------------------------
 // Lazy enrichment API — fold the expensive per-node reads into rows on demand,
@@ -493,6 +565,20 @@ export function enrichRows(rows) {
         row.enriched = true;
     }
 }
+export async function enrichRowsFromSource(source, rows) {
+    const todo = rows.filter((r) => r.enriched !== true);
+    if (todo.length === 0)
+        return;
+    const asks = asksForNodes(todo.map((r) => r.node_id));
+    await Promise.all(todo.map(async (row) => {
+        const meta = await source.getNode(row.node_id);
+        if (meta !== null)
+            row.name = fullName(meta);
+        row.ctx_tokens = readNodeTelemetry(row.node_id).tokens_in ?? 0;
+        row.asks = asks[row.node_id] ?? 0;
+        row.enriched = true;
+    }));
+}
 /** Load the SELECTED row's preview text: the spawn `goal` (initial-prompt.md) plus
  *  the whole-conversation `prompts` and the `lastAssistant` reply — the latter two
  *  folded into ONE session-file read (see {@link readSessionParts}). Mutates the row
@@ -509,3 +595,14 @@ export function loadPreview(row) {
     row.previewLoaded = true;
     return row;
 }
+export async function loadPreviewFromSource(source, row) {
+    if (row.previewLoaded === true)
+        return row;
+    row.goal = readGoalText(row.node_id);
+    const meta = await source.getNode(row.node_id);
+    const { prompts, lastAssistant } = readSessionParts(meta?.pi_session_file);
+    row.prompts = prompts;
+    row.lastAssistant = lastAssistant;
+    row.previewLoaded = true;
+    return row;
+}

package/dist/core/canvas/source.d.ts

@@ -0,0 +1,26 @@
+import type { NodeMeta, NodeRow, NodeStatus, SubscriptionRef } from './types.js';
+export interface CanvasSource {
+    getNode(nodeId: string): Promise<NodeMeta | null>;
+    getRow(nodeId: string): Promise<NodeRow | null>;
+    listNodes(filter?: {
+        status?: NodeStatus | NodeStatus[];
+    }): Promise<NodeRow[]>;
+    subscriptionsOf(subscriber: string): Promise<SubscriptionRef[]>;
+    subscribersOf(publisher: string): Promise<SubscriptionRef[]>;
+    view(root: string): Promise<string[]>;
+    askCountsForView(root: string): Promise<Record<string, number>>;
+    hasActiveLiveSubscription(nodeId: string): Promise<boolean>;
+}
+export declare class LocalCanvasSource implements CanvasSource {
+    getNode(nodeId: string): Promise<NodeMeta | null>;
+    getRow(nodeId: string): Promise<NodeRow | null>;
+    listNodes(filter?: {
+        status?: NodeStatus | NodeStatus[];
+    }): Promise<NodeRow[]>;
+    subscriptionsOf(subscriber: string): Promise<SubscriptionRef[]>;
+    subscribersOf(publisher: string): Promise<SubscriptionRef[]>;
+    view(root: string): Promise<string[]>;
+    askCountsForView(root: string): Promise<Record<string, number>>;
+    hasActiveLiveSubscription(nodeId: string): Promise<boolean>;
+}
+export declare const localCanvasSource: CanvasSource;

package/dist/core/canvas/source.js

@@ -0,0 +1,29 @@
+import { getNode, getRow, listNodes, subscriptionsOf, subscribersOf, view, hasActiveLiveSubscription, } from './canvas.js';
+import { asksForNodes } from './attention.js';
+export class LocalCanvasSource {
+    async getNode(nodeId) {
+        return getNode(nodeId);
+    }
+    async getRow(nodeId) {
+        return getRow(nodeId);
+    }
+    async listNodes(filter) {
+        return listNodes(filter);
+    }
+    async subscriptionsOf(subscriber) {
+        return subscriptionsOf(subscriber);
+    }
+    async subscribersOf(publisher) {
+        return subscribersOf(publisher);
+    }
+    async view(root) {
+        return view(root);
+    }
+    async askCountsForView(root) {
+        return asksForNodes([root, ...view(root)]);
+    }
+    async hasActiveLiveSubscription(nodeId) {
+        return hasActiveLiveSubscription(nodeId);
+    }
+}
+export const localCanvasSource = new LocalCanvasSource();

package/dist/core/canvas/status-glyph.js

@@ -45,6 +45,7 @@ export function hangingLabel(kind) {
         case 'auth': return 'auth';
         case 'protocol': return 'protocol';
         case 'wedged': return 'wedged';
+        case 'model-not-found': return 'model-not-found';
         default: return 'other';
     }
 }

package/dist/core/canvas/types.d.ts

@@ -73,7 +73,8 @@ export interface NodeIdentity {
      *  to the row (like `cwd`/`host_kind`), NOT re-derived by `rebuildIndex()` —
      *  it is chosen once at spawn (inherited from the spawner, or `--profile`) and
      *  is the runtime→resolver seam (`CRTR_PROFILE_ID`) the memory/gate substrate
-     *  reads. NULL for a root/no-profile node — never invent a literal root id. */
+     *  reads. NULL only for historical root/no-profile rows; new root conversations
+     *  use the stable root profile id. */
     profile_id?: string | null;
     /** Role the node was born as: explore | developer | plan | review | general… */
     kind: string;
@@ -200,8 +201,8 @@ export interface NodeRow {
     cwd: string;
     /** Which HOST launches + supervises this node; see NodeIdentity.host_kind. */
     host_kind: 'tmux' | 'broker' | null;
-    /** The profile this node runs under; see NodeIdentity.profile_id. NULL for a
-     *  root/no-profile node. */
+    /** The profile this node runs under; see NodeIdentity.profile_id. NULL only
+     *  for historical root/no-profile rows. */
     profile_id: string | null;
     parent: string | null;
     created: string;

package/dist/core/config.d.ts

@@ -9,6 +9,13 @@ export declare function ensureScopeInitialized(scope: Scope, root: string): void
 export interface MergedLaunchConfig {
     kinds: Record<string, KindConfig>;
     modelLadders: ModelLaddersConfig;
+    /** The merged `spawnEnv.allow` set (project stack > profile > user >
+     *  builtin, additive) — read by `buildOperationalEnvBase`
+     *  (`core/runtime/spawn-env.ts`) as source C of the broker spawn-env
+     *  boundary. */
+    spawnEnv: {
+        allow: string[];
+    };
 }
 /** Merge launch knobs (`kinds`, `modelLadders`) across scopes in
  *  project stack > profile > user > builtin precedence — the same precedence
@@ -29,8 +36,17 @@ export interface MergedLaunchConfig {
  *  Callers (launch, kind registry) go through this function rather than
  *  `readConfig` directly, so `ScopeConfig.kinds`/`modelLadders`/tools/
  *  extensions/`availableTo` all honor the same profile + multi-project
- *  precedence. */
-export declare function readMergedLaunchConfig(): MergedLaunchConfig;
+ *  precedence.
+ *
+ *  `targetCwd`/`targetProfileId` default to this PROCESS's own ambient cwd
+ *  and `CRTR_PROFILE_ID` — correct for a caller resolving config for itself
+ *  (front-door commands, kind listing). A caller resolving config on behalf
+ *  of a DIFFERENT node (the broker spawn-env boundary, predicate-eval — both
+ *  run inside the daemon, whose ambient cwd/profile is the daemon's own, not
+ *  the target node's) MUST pass the target's own cwd/profile explicitly, or
+ *  `spawnEnv.allow` resolves from the wrong scope entirely (the C-1
+ *  follow-up fix this parameterization exists for). */
+export declare function readMergedLaunchConfig(targetCwd?: string, targetProfileId?: string | null): MergedLaunchConfig;
 /** The effective `KindConfig` for one full kind string (top-level, e.g.
  *  `developer`, or sub-kind, e.g. `plan/reviewers/security`), across
  *  project > user > builtin precedence. Returns `undefined` for a kind no

package/dist/core/config.js

@@ -1,5 +1,5 @@
 import { join } from 'node:path';
-import { CONFIG_FILE, STATE_FILE, defaultScopeConfig, defaultScopeState, defaultCanvasNavConfig, defaultModelLaddersConfig, defaultKindsConfig } from '../types.js';
+import { CONFIG_FILE, STATE_FILE, defaultScopeConfig, defaultScopeState, defaultCanvasNavConfig, defaultModelLaddersConfig, defaultKindsConfig, defaultRemoteCanvasConfig } from '../types.js';
 import { readJsonIfExists, writeJson, ensureDir } from './fs-utils.js';
 import { scopeRoot, requireScopeRoot, findProjectScopeRoots } from './scope.js';
 import { profileRoot } from './profiles/manifest.js';
@@ -176,6 +176,33 @@ function mergeModelLadders(raw, base = defaultModelLaddersConfig()) {
     }
     return out;
 }
+/** True when `pattern` (a `spawnEnv.allow` entry) matches EVERY possible env
+ *  var name — a bare `*`, or any run of nothing but `*` characters (`**`,
+ *  `***`, …). This is the one glob shape that reopens the inherit-all hole
+ *  the whole spawn-env boundary exists to close, so it is rejected loud
+ *  rather than silently treated as literal or silently dropped (per
+ *  `cto-rejects-fallback-hedges`: fix the config, don't hedge around it). */
+function isInheritAllGlob(pattern) {
+    return pattern !== '' && pattern.replace(/\*/g, '') === '';
+}
+/** Merge a raw `spawnEnv.allow` list over `base` (defaulting to empty):
+ *  additive/union, not override — each scope only ADDS a name/glob it
+ *  explicitly admits across the broker spawn-env boundary (`buildBrokerEnv`),
+ *  never removes a lower-precedence scope's entry. Non-string entries are
+ *  dropped, never thrown, mirroring `mergeKinds`/`mergeModelLadders` — but an
+ *  inherit-all glob (`isInheritAllGlob`) throws immediately at config read: it
+ *  is not a shape any legitimate entry can mean, and silently accepting or
+ *  dropping it would either reopen the leak or hide a config mistake. */
+function mergeSpawnEnv(raw, base = []) {
+    const r = raw;
+    const extra = Array.isArray(r?.allow) ? r.allow.filter((v) => typeof v === 'string') : [];
+    for (const pattern of extra) {
+        if (isInheritAllGlob(pattern)) {
+            throw new Error(`spawnEnv.allow: "${pattern}" matches every env var name (inherit-all) — this is exactly the leak the spawn-env boundary closes. Name the specific vars/prefixes you actually need instead (e.g. "AWS_*", "GIT_ASKPASS").`);
+        }
+    }
+    return { allow: [...new Set([...base, ...extra])] };
+}
 /** Validate one raw `kinds.<name>` entry into a `KindConfig`, or drop it
  *  (return null) rather than throwing — an invalid kind entry in config.json
  *  must not break config parsing for every other kind. `whenToUse` is the
@@ -216,6 +243,41 @@ function mergeKinds(raw, base = defaultKindsConfig()) {
     }
     return out;
 }
+/** Validate one raw `remoteCanvas.targets.<name>` entry, or drop it (return
+ *  null) rather than throwing — same rule `normalizeKindEntry` follows. A
+ *  valid entry needs a non-empty `previewEndpoint` and `relayTokenEnv`; the
+ *  token itself is never stored here (see `RemoteCanvasTarget`). */
+function normalizeRemoteCanvasTarget(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    if (typeof r.previewEndpoint !== 'string' || r.previewEndpoint.trim() === '')
+        return null;
+    if (typeof r.relayTokenEnv !== 'string' || r.relayTokenEnv.trim() === '')
+        return null;
+    const out = { previewEndpoint: r.previewEndpoint, relayTokenEnv: r.relayTokenEnv };
+    if (typeof r.cpOrigin === 'string' && r.cpOrigin.trim() !== '')
+        out.cpOrigin = r.cpOrigin;
+    return out;
+}
+/** Merge a raw `remoteCanvas` block over the built-in defaults (no targets):
+ *  each valid `targets.<name>` entry adds or shadows a target by name;
+ *  invalid entries are dropped, never thrown. Mirrors `mergeKinds`'s
+ *  layer-over-defaults shape. */
+function mergeRemoteCanvas(raw, base = defaultRemoteCanvasConfig()) {
+    const out = { ...base.targets };
+    if (raw !== null && typeof raw === 'object') {
+        const r = raw;
+        if (r.targets !== null && typeof r.targets === 'object') {
+            for (const [name, value] of Object.entries(r.targets)) {
+                const normalized = normalizeRemoteCanvasTarget(value);
+                if (normalized !== null)
+                    out[name] = normalized;
+            }
+        }
+    }
+    return { targets: out };
+}
 function normalizeMode(value, fallback) {
     if (value === true)
         return 'notify';
@@ -247,7 +309,9 @@ function mergeConfig(partial) {
     const canvasNav = mergeCanvasNav(partial.canvasNav);
     const modelLadders = mergeModelLadders(partial.modelLadders);
     const kinds = mergeKinds(partial.kinds);
-    return { schema_version, marketplaces, plugins, auto_update, max_panes_per_window, canvasNav, modelLadders, kinds };
+    const remoteCanvas = mergeRemoteCanvas(partial.remoteCanvas);
+    const spawnEnv = mergeSpawnEnv(partial.spawnEnv, defaults.spawnEnv?.allow);
+    return { schema_version, marketplaces, plugins, auto_update, max_panes_per_window, canvasNav, modelLadders, kinds, remoteCanvas, spawnEnv };
 }
 /** Raw (un-defaulted) partial config for one scope, or null if the scope has
  *  no root or no config.json. Used by `readMergedLaunchConfig` to layer
@@ -281,9 +345,11 @@ function readRawProfileConfig(profileId) {
  *  — every ancestor `.crouter/`, widened by a selected profile's `projects`),
  *  ordered FARTHEST-first so `readMergedLaunchConfig` can layer them on last
  *  and have the NEAREST root win — mirroring the resolver's nearest-project-
- *  strongest replacement precedence. */
-function readRawProjectScopeConfigs() {
-    const nearestFirst = findProjectScopeRoots();
+ *  strongest replacement precedence. Walks from `targetCwd`/`targetProfileId`
+ *  — the SCOPE THE CONFIG IS FOR, not necessarily the calling process's own
+ *  ambient cwd/profile (see `readMergedLaunchConfig`). */
+function readRawProjectScopeConfigs(targetCwd, targetProfileId) {
+    const nearestFirst = findProjectScopeRoots(targetCwd, targetProfileId);
     const farthestFirst = [...nearestFirst].reverse();
     const out = [];
     for (const root of farthestFirst) {
@@ -312,23 +378,35 @@ function readRawProjectScopeConfigs() {
  *  Callers (launch, kind registry) go through this function rather than
  *  `readConfig` directly, so `ScopeConfig.kinds`/`modelLadders`/tools/
  *  extensions/`availableTo` all honor the same profile + multi-project
- *  precedence. */
-export function readMergedLaunchConfig() {
+ *  precedence.
+ *
+ *  `targetCwd`/`targetProfileId` default to this PROCESS's own ambient cwd
+ *  and `CRTR_PROFILE_ID` — correct for a caller resolving config for itself
+ *  (front-door commands, kind listing). A caller resolving config on behalf
+ *  of a DIFFERENT node (the broker spawn-env boundary, predicate-eval — both
+ *  run inside the daemon, whose ambient cwd/profile is the daemon's own, not
+ *  the target node's) MUST pass the target's own cwd/profile explicitly, or
+ *  `spawnEnv.allow` resolves from the wrong scope entirely (the C-1
+ *  follow-up fix this parameterization exists for). */
+export function readMergedLaunchConfig(targetCwd = process.cwd(), targetProfileId = process.env['CRTR_PROFILE_ID'] || null) {
     const defaults = defaultScopeConfig();
     const userRaw = readRawScopeConfig('user');
-    const profileRaw = readRawProfileConfig(process.env['CRTR_PROFILE_ID'] || null);
-    const projectRawsFarthestFirst = readRawProjectScopeConfigs();
+    const profileRaw = readRawProfileConfig(targetProfileId);
+    const projectRawsFarthestFirst = readRawProjectScopeConfigs(targetCwd, targetProfileId);
     let kinds = mergeKinds(userRaw?.kinds, defaults.kinds);
     let modelLadders = mergeModelLadders(userRaw?.modelLadders, defaults.modelLadders);
+    let spawnEnv = mergeSpawnEnv(userRaw?.spawnEnv, defaults.spawnEnv?.allow);
     if (profileRaw !== null) {
         kinds = mergeKinds(profileRaw.kinds, kinds);
         modelLadders = mergeModelLadders(profileRaw.modelLadders, modelLadders);
+        spawnEnv = mergeSpawnEnv(profileRaw.spawnEnv, spawnEnv.allow);
     }
     for (const raw of projectRawsFarthestFirst) {
         kinds = mergeKinds(raw.kinds, kinds);
         modelLadders = mergeModelLadders(raw.modelLadders, modelLadders);
+        spawnEnv = mergeSpawnEnv(raw.spawnEnv, spawnEnv.allow);
     }
-    return { kinds, modelLadders };
+    return { kinds, modelLadders, spawnEnv };
 }
 /** The effective `KindConfig` for one full kind string (top-level, e.g.
  *  `developer`, or sub-kind, e.g. `plan/reviewers/security`), across

package/dist/core/fault-classifier.d.ts

@@ -1,5 +1,5 @@
-export type FaultLink = 'pi→provider' | 'viewer↔broker' | 'relay↔broker' | 'browser↔relay' | 'cli→exa' | 'daemon→node';
-export type FaultKind = 'rate-limit' | 'overloaded' | 'connection' | 'auth' | 'protocol' | 'other' | 'wedged';
+export type FaultLink = 'pi→provider' | 'viewer↔broker' | 'relay↔broker' | 'browser↔relay' | 'cli→exa' | 'daemon→node' | 'crtr→pi';
+export type FaultKind = 'rate-limit' | 'overloaded' | 'connection' | 'auth' | 'protocol' | 'other' | 'wedged' | 'model-not-found';
 export type FaultRetryDisposition = 'auto' | 'manual' | 'fatal';
 export type FaultRetryOwner = 'sdk' | 'daemon' | 'client';
 export interface FaultRetry {

package/dist/core/memory-resolver.d.ts

@@ -2,7 +2,7 @@ import type { InstalledPlugin, Scope } from '../types.js';
 /**
  * Thin memory-document resolver for the document substrate. Precedence is the
  * OUTER loop, not a global scan: scopes/sources are tried NEAREST-FIRST
- * (project stack nearest > ... > profile > user > builtin), and WITHIN each
+ * (node > project stack nearest > ... > profile > user > builtin), and WITHIN each
  * source, in order: (1) exact substrate-identity match (`doc.name === query`
  * — the explicit frontmatter `name`, or its path-derived fallback), (2) direct
  * `memory/<name>.md` physical-path lookup (plus the bare-dir/bare-plugin-name
@@ -38,11 +38,14 @@ export interface MemoryDoc {
     plugin?: string;
 }
 /** The memory-only scope union: the global `Scope` (`user|project|builtin`)
- *  plus `profile`. Confined to the memory resolver/list/read/write/render
- *  paths — deliberately NOT folded into the global `Scope` union, because that
- *  would leak `profile` into config, plugin, marketplace, view, and doctor/
- *  sys-config surfaces the spec does not extend. */
-export type MemoryScope = Scope | 'profile';
+ *  plus `profile` and `node`. Confined to the memory resolver/list/read/write/
+ *  render paths — deliberately NOT folded into the global `Scope` union, because
+ *  that would leak these into config, plugin, marketplace, view, and doctor/
+ *  sys-config surfaces the spec does not extend. `node` is the this-node store
+ *  (`nodes/<id>/context/memory/`), available only inside a running node
+ *  (`CRTR_NODE_ID`), and it is the NEAREST scope — a node doc overrides a
+ *  same-named doc at any wider scope. */
+export type MemoryScope = Scope | 'profile' | 'node';
 export interface MemoryResolutionOpts {
     /** Restrict resolution to a single scope. Conflicts with a scope prefix on
      *  the identifier (e.g. `user/foo` with scope=project) throw. */

package/dist/core/memory-resolver.js

@@ -8,6 +8,7 @@ import { warn } from './output.js';
 import { pluginMemoryDir, projectScopeRoot, projectScopeRoots, scopeMemoryDir } from './scope.js';
 import { normalizeDocName, normalizeNameSegment, resolveDocName } from './substrate/schema.js';
 import { loadProfileManifest, profileMemoryDir } from './profiles/manifest.js';
+import { memoryDir as nodeMemoryDir } from './runtime/memory.js';
 /** Canonical, unambiguous identifier for a memory document: `<scope>/<name>`. */
 export function memoryDocId(doc) {
     return `${doc.scope}/${doc.name}`;
@@ -18,14 +19,24 @@ export function memoryDocId(doc) {
 function selectedProfileId() {
     return process.env['CRTR_PROFILE_ID'] || '';
 }
-/** The memory scopes in resolution precedence: project stack > profile > user >
- *  builtin. Project is included only when a project scope exists for the cwd
- *  (or the selected profile's project stack); profile is included only when a
- *  profile is selected. A single `scope` narrows to just that scope. */
+/** The current node id from the process env, or '' when not running inside a
+ *  node. The seam the `node` scope resolves through — its memory dir is
+ *  `nodeMemoryDir(id)` (`nodes/<id>/context/memory/`). */
+function selectedNodeId() {
+    return process.env['CRTR_NODE_ID'] || '';
+}
+/** The memory scopes in resolution precedence: node > project stack > profile >
+ *  user > builtin. Node is included only inside a running node (`CRTR_NODE_ID`)
+ *  and ranks NEAREST — a node doc overrides any wider scope. Project is included
+ *  only when a project scope exists for the cwd (or the selected profile's
+ *  project stack); profile is included only when a profile is selected. A single
+ *  `scope` narrows to just that scope. */
 function scopesInPrecedence(scope) {
     if (scope)
         return [scope];
     const out = [];
+    if (selectedNodeId() !== '')
+        out.push('node');
     if (projectScopeRoot())
         out.push('project');
     if (selectedProfileId() !== '')
@@ -65,6 +76,13 @@ function memorySourcesInPrecedence(scope) {
                 }
             }
         }
+        else if (s === 'node') {
+            // The this-node store — a singleton dir in the node's context, no plugins.
+            // Silently absent when not running inside a node (CRTR_NODE_ID unset).
+            const nodeId = selectedNodeId();
+            if (nodeId !== '')
+                out.push({ scope: 'node', memoryDir: nodeMemoryDir(nodeId), plugins: [] });
+        }
         else {
             out.push({
                 scope: s,
@@ -147,6 +165,12 @@ export function listMemoryDocs(scope, quiet = false) {
             return [];
         }
     }
+    if (scope === 'node') {
+        const nodeId = selectedNodeId();
+        if (nodeId === '')
+            return [];
+        return listMemoryDocsInDir('node', nodeMemoryDir(nodeId), quiet);
+    }
     return listMemoryDocsInDir(scope, scopeMemoryDir(scope), quiet);
 }
 /** All of one plugin's substrate docs, mounted under the virtual `<pluginName>/`

package/dist/core/profiles/__tests__/root-profile.test.d.ts

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

package/dist/core/profiles/__tests__/root-profile.test.js

@@ -0,0 +1,69 @@
+import { test, before, after, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { ensureRootProfile, listProfiles, loadProfileManifest, profileManifestPath, profileMemoryDir, profileRoot, ROOT_PROFILE_ID, } from '../manifest.js';
+import { selectProfileForCwd } from '../select.js';
+import { resetScopeCache } from '../../scope.js';
+let home;
+let cwd;
+let previousHome;
+let previousCwd;
+function forceNonInteractive() {
+    Object.defineProperty(process.stdin, 'isTTY', { value: false, configurable: true, writable: true });
+    Object.defineProperty(process.stdout, 'isTTY', { value: false, configurable: true, writable: true });
+}
+function restoreInteractiveFlags() {
+    Reflect.deleteProperty(process.stdin, 'isTTY');
+    Reflect.deleteProperty(process.stdout, 'isTTY');
+}
+before(() => {
+    previousHome = process.env.HOME;
+    previousCwd = process.cwd();
+});
+beforeEach(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-root-profile-home-'));
+    cwd = mkdtempSync(join(tmpdir(), 'crtr-root-profile-cwd-'));
+    process.env.HOME = home;
+    process.chdir(cwd);
+    forceNonInteractive();
+    resetScopeCache();
+});
+afterEach(() => {
+    restoreInteractiveFlags();
+    process.chdir(previousCwd);
+    rmSync(home, { recursive: true, force: true });
+    rmSync(cwd, { recursive: true, force: true });
+    resetScopeCache();
+});
+after(() => {
+    process.chdir(previousCwd);
+    if (previousHome === undefined)
+        delete process.env.HOME;
+    else
+        process.env.HOME = previousHome;
+    resetScopeCache();
+});
+test('ensureRootProfile creates the stable root profile and is idempotent', () => {
+    const first = ensureRootProfile();
+    const second = ensureRootProfile();
+    assert.equal(first.profileId, ROOT_PROFILE_ID);
+    assert.equal(second.profileId, ROOT_PROFILE_ID);
+    assert.deepEqual(second, first);
+    assert.equal(first.manifest.name, 'root');
+    assert.deepEqual(first.manifest.projects, []);
+    assert.equal(existsSync(profileRoot(ROOT_PROFILE_ID)), true);
+    assert.equal(existsSync(profileManifestPath(ROOT_PROFILE_ID)), true);
+    assert.equal(existsSync(profileMemoryDir(ROOT_PROFILE_ID)), true);
+    assert.deepEqual(listProfiles().map(({ profileId }) => profileId), [ROOT_PROFILE_ID]);
+});
+test('selectProfileForCwd falls back to the stable root profile when nothing covers cwd', async () => {
+    const profileId = await selectProfileForCwd(cwd);
+    assert.equal(profileId, ROOT_PROFILE_ID);
+    const entry = loadProfileManifest(ROOT_PROFILE_ID);
+    assert.equal(entry.profileId, ROOT_PROFILE_ID);
+    assert.equal(entry.manifest.name, 'root');
+    assert.equal(entry.manifest.last_used_at !== null, true);
+    assert.equal(existsSync(profileRoot(ROOT_PROFILE_ID)), true);
+});

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

@@ -1,4 +1,5 @@
 import type { ProfileManifest } from '../../types.js';
+export declare const ROOT_PROFILE_ID = "root-00000000";
 export declare function profilesRoot(): string;
 export declare function profileRoot(profileId: string): string;
 export declare function profileManifestPath(profileId: string): string;
@@ -25,6 +26,7 @@ export declare function loadProfileManifest(profileIdOrName: string): ProfileEnt
  *  mutations (create/rename/add-project/remove-project/delete/last-used)
  *  below run inside this. */
 export declare function withProfileManifestLock<T>(profileId: string, fn: () => T): T;
+export declare function ensureRootProfile(): ProfileEntry;
 export declare function createProfile(name: string, projects?: string[]): ProfileEntry;
 export declare function updateProfileLastUsed(profileId: string): ProfileEntry;
 export declare function renameProfile(profileId: string, name: string): ProfileEntry;