@crouton-kit/crouter 0.3.33 → 0.3.35

package/dist/core/hearth/providers/blaxel-home.js

@@ -1,126 +1,136 @@
-import { readFileSync } from 'node:fs';
 import { general } from '../../errors.js';
 import { nowIso } from '../../fs-utils.js';
-import { getHome, updateHome } from '../registry.js';
 import { guestEnv } from '../guest-env.js';
 import { buildBootstrapScript } from './blaxel-bootstrap.js';
 import { BlaxelMachineProvider } from './blaxel.js';
-function readCrtrVersion() {
-    const file = new URL('../../../../package.json', import.meta.url);
-    const pkg = JSON.parse(readFileSync(file, 'utf8'));
-    if (typeof pkg.version !== 'string' || pkg.version.trim() === '') {
-        throw general('missing crtr package version', { packageJson: file.pathname });
-    }
-    return pkg.version;
-}
 function stableRouteName(home) {
-    return home.webRoute?.routeId ?? `${home.machineId}-web`;
-}
-function homeStorage(home, config) {
-    return {
-        kind: 'volume',
-        durability: 'durable-volume',
-        longTermContract: true,
-        ownerMachineId: home.machineId,
-        guestHome: config.guestHome,
-        volumeId: home.homeStorage.volumeId,
-        mountPath: config.guestHome,
-    };
+    return `${home.providerSandboxId}-web`;
 }
-function buildHomeRecord(home, config, route, timestamps) {
-    return {
-        ...home,
-        providerName: 'blaxel',
-        homeStorage: homeStorage(home, config),
-        webRoute: route,
-        state: 'running',
-        createdAt: timestamps.createdAt ?? home.createdAt,
-        updatedAt: timestamps.updatedAt,
-    };
-}
-function ensureReadyHome(home, tenantId) {
-    if (home === null) {
-        throw general(`no home for tenant ${tenantId} — run the existing provision/bootstrap flow`, { tenantId });
+function ensureReadyHome(input) {
+    if (input.providerName !== 'blaxel') {
+        throw general(`unsupported Hearth home provider ${input.providerName}`, { providerName: input.providerName });
     }
-    if (typeof home.machineId !== 'string' || home.machineId === '') {
-        throw general(`home ${tenantId} is missing machineId — run the existing provision/bootstrap flow`, { tenantId });
+    if (typeof input.providerSandboxId !== 'string' || input.providerSandboxId === '') {
+        throw general(`home ${input.homeId} is missing providerSandboxId`, { homeId: input.homeId });
     }
-    if (typeof home.homeStorage?.volumeId !== 'string' || home.homeStorage.volumeId === '') {
-        throw general(`home ${tenantId} is missing homeStorage.volumeId — run the existing provision/bootstrap flow`, { tenantId });
+    if (typeof input.providerVolumeId !== 'string' || input.providerVolumeId === '') {
+        throw general(`home ${input.homeId} is missing providerVolumeId`, { homeId: input.homeId });
     }
-    if (typeof home.nodeId !== 'string' || home.nodeId === '') {
-        throw general(`home ${tenantId} is missing nodeId — run the existing provision/bootstrap flow`, { tenantId });
+    if (typeof input.homeAgentTarget !== 'string' || input.homeAgentTarget === '') {
+        throw general(`home ${input.homeId} is missing homeAgentTarget`, { homeId: input.homeId });
     }
-    if (typeof home.relayToken !== 'string' || home.relayToken === '') {
-        throw general(`home ${tenantId} is missing relayToken — run the existing provision/bootstrap flow`, { tenantId });
+    if (typeof input.relayToken !== 'string' || input.relayToken === '') {
+        throw general(`home ${input.homeId} is missing resolved relayToken`, { homeId: input.homeId });
     }
-    return home;
+    return input;
 }
 function isRunningMachine(machine) {
     return machine !== null && machine.state !== 'terminated';
 }
+function previewEndpoint(route, fallback) {
+    return route.concreteUrl ?? route.url ?? fallback ?? null;
+}
+function refreshedPointers(home, provider, route, status, machine) {
+    return {
+        providerName: 'blaxel',
+        providerSandboxId: home.providerSandboxId,
+        providerVolumeId: home.providerVolumeId,
+        previewEndpoint: route === null ? (home.previewEndpoint ?? null) : previewEndpoint(route, home.previewEndpoint),
+        route,
+        homeAgentTarget: home.homeAgentTarget,
+        relayAuthRef: home.relayAuthRef ?? null,
+        templateVersion: provider.templateVersion,
+        status,
+        machine,
+        updatedAt: nowIso(),
+    };
+}
 export class BlaxelHomeBackend {
     config;
     provider;
-    crtrVersion;
     constructor(config, provider) {
         this.config = config;
-        this.provider = provider ?? new BlaxelMachineProvider();
-        this.crtrVersion = readCrtrVersion();
+        this.provider = provider ?? new BlaxelMachineProvider({ image: config.imageRef, templateVersion: config.templateVersion, volumeSizeGb: config.volumeSizeGb });
     }
-    async wake(tenantId) {
-        const current = ensureReadyHome(getHome(this.config.registryPath, tenantId), tenantId);
-        const machine = await this.getMachine(current.machineId);
-        const relayToken = current.relayToken ?? '';
-        if (relayToken === '') {
-            throw general(`home ${tenantId} is missing relayToken — run the existing provision/bootstrap flow`, { tenantId });
-        }
+    async wake(homeInput) {
+        const current = ensureReadyHome(homeInput);
+        const machine = await this.getMachine(current.providerSandboxId);
         const bootstrapScript = buildBootstrapScript({
             guestHome: this.config.guestHome,
-            crtrVersion: this.crtrVersion,
-            relayToken,
+            crtrVersion: this.provider.templateVersion,
+            relayToken: current.relayToken,
             webPort: this.config.webPort,
-            nodeId: current.nodeId ?? undefined,
+            nodeId: current.homeAgentTarget,
             piAuthJson: this.config.piAuthJson,
+            piPackages: this.config.piPackages,
             isFirstProvision: false,
         });
         if (isRunningMachine(machine)) {
+            // Standby resume (R-SUSP-2/R-WAKE-3): the sandbox already exists — never call
+            // createMachine() here. Probing the port is enough to make Blaxel transparently restore
+            // a snapshot-paused sandbox; the broker pid inside the guest is untouched either way, and
+            // nothing on this host-side path invokes reviveNode() (that launcher is for crtr's own
+            // node engine, not a guest process — the provider layer never imports it). The exec
+            // fallback below only re-runs the idempotent in-guest bootstrap when the port still isn't
+            // answering after a snapshot-resume window; it is not a recreate.
             try {
-                await this.provider.waitForPort(current.machineId, this.config.webPort, { maxWaitMs: 30_000 });
+                await this.provider.waitForPort(current.providerSandboxId, this.config.webPort, { maxWaitMs: 30_000 });
             }
             catch {
-                await this.provider.exec(current.machineId, { command: bootstrapScript, background: true, cwd: this.config.guestHome });
-                await this.provider.waitForPort(current.machineId, this.config.webPort, { maxWaitMs: 30_000 });
+                await this.provider.exec(current.providerSandboxId, { command: bootstrapScript, background: true, cwd: this.config.guestHome });
+                await this.provider.waitForPort(current.providerSandboxId, this.config.webPort, { maxWaitMs: 30_000 });
             }
         }
         else {
             await this.provider.createMachine({
-                tenantId,
-                name: current.machineId,
+                tenantId: current.tenantId,
+                name: current.providerSandboxId,
                 envs: guestEnv(this.config),
-                volumeMount: { volumeName: current.homeStorage.volumeId, path: this.config.guestHome },
+                volumeMount: { volumeName: current.providerVolumeId, path: this.config.guestHome },
                 ports: [{ target: this.config.webPort, protocol: 'HTTP' }],
             });
-            await this.provider.exec(current.machineId, { command: bootstrapScript, background: true, cwd: this.config.guestHome });
-            await this.provider.waitForPort(current.machineId, this.config.webPort, { maxWaitMs: 60_000 });
+            await this.provider.exec(current.providerSandboxId, { command: bootstrapScript, background: true, cwd: this.config.guestHome });
+            await this.provider.waitForPort(current.providerSandboxId, this.config.webPort, { maxWaitMs: 60_000 });
         }
-        const route = await this.provider.publishHttpPort(current.machineId, {
-            machineId: current.machineId,
+        const route = await this.provider.publishHttpPort(current.providerSandboxId, {
+            machineId: current.providerSandboxId,
             targetPort: this.config.webPort,
             routeName: stableRouteName(current),
             routeId: stableRouteName(current),
         });
-        const updatedAt = nowIso();
-        updateHome(this.config.registryPath, tenantId, () => buildHomeRecord({ ...current, webRoute: route, relayToken }, this.config, route, { createdAt: current.createdAt, updatedAt }));
+        return refreshedPointers(current, this.provider, route, 'running', await this.getMachine(current.providerSandboxId));
     }
-    async suspend(tenantId) {
-        updateHome(this.config.registryPath, tenantId, (draft) => {
-            draft.updatedAt = nowIso();
-            return draft;
-        });
+    async suspend(homeInput) {
+        const current = ensureReadyHome(homeInput);
+        const machine = await this.getMachine(current.providerSandboxId);
+        // Snapshot-never-kill (P3.4): this method must never call `provider.destroy()` or
+        // `provider.createMachine()` — those are the only ways the underlying sandbox is torn down
+        // or relaunched, and neither belongs on the suspend path. Blaxel (@blaxel/core 0.2.94) has
+        // no imperative pause/standby call to invoke here; `snapshotEnabled` (set at create time in
+        // blaxel.ts) is the only discoverable seam, and it makes idle snapshot-pause a platform-
+        // managed background behavior rather than something this method triggers. So suspend() does
+        // not fabricate a 'suspended' status the way a real pause API's response would justify —
+        // doing so would tell the CP registry a snapshot happened when nothing was asked of the
+        // provider. It fails closed instead: assert the sandbox still exists (a missing/terminated
+        // sandbox cannot be "suspended", it must be re-provisioned through wake()), and return the
+        // provider's own observed status untouched so the CP can tell "confirmed paused" from
+        // "still running, waiting on Blaxel's own idle timer" rather than trusting an invented one.
+        if (machine === null) {
+            throw general(`cannot suspend home ${current.homeId}: backing sandbox ${current.providerSandboxId} is not present`, {
+                homeId: current.homeId,
+                providerSandboxId: current.providerSandboxId,
+            });
+        }
+        return refreshedPointers(current, this.provider, null, machine.state, machine);
     }
     async getMachine(machineId) {
         const machine = await this.provider.getMachine(machineId);
         return machine.state === 'terminated' ? null : machine;
     }
+    /** P2.6 stdin-capable exec seam, passed through verbatim — the `HomeBackend` interface is the
+     *  only door CP code uses to reach it (see `provider.ts`), so callers never import
+     *  `BlaxelMachineProvider` directly. */
+    async exec(machineId, input) {
+        return this.provider.exec(machineId, input);
+    }
 }

package/dist/core/hearth/providers/blaxel.d.ts

@@ -4,9 +4,14 @@ interface BlaxelMachineProviderOptions {
     region?: string;
     memory?: number;
     image?: string;
+    templateVersion?: string;
+    volumeSizeGb?: number;
 }
 export declare class BlaxelMachineProvider implements MachineProvider {
     readonly providerName: "blaxel";
+    readonly imageRef: string;
+    readonly templateVersion: string;
+    readonly volumeSizeGb: number;
     private readonly config;
     constructor(options?: BlaxelMachineProviderOptions);
     createVolume(input: {

package/dist/core/hearth/providers/blaxel.js

@@ -1,7 +1,23 @@
+import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
 import { SandboxInstance, VolumeInstance } from '@blaxel/core';
 import { general } from '../../errors.js';
 const TERMINATED_STATES = new Set(['TERMINATED', 'DELETING', 'DEACTIVATED', 'DEACTIVATING', 'FAILED']);
 const PROVISIONING_STATES = new Set(['UPLOADING', 'BUILDING', 'DEPLOYING', 'BUILT']);
+function readCrtrVersion() {
+    const file = new URL('../../../../package.json', import.meta.url);
+    const pkg = JSON.parse(readFileSync(file, 'utf8'));
+    if (typeof pkg.version !== 'string' || pkg.version.trim() === '') {
+        throw general('missing crtr package version', { packageJson: file.pathname });
+    }
+    return pkg.version;
+}
+function defaultImageRef(templateVersion) {
+    return `crouter-hearth-home-${templateVersion.replace(/\./g, '-')}`;
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
 function shStatus(status) {
     if (status === undefined || status === null || status === '')
         return 'unknown';
@@ -44,6 +60,27 @@ function toEnvVars(envs) {
         .sort(([a], [b]) => a.localeCompare(b))
         .map(([name, value]) => ({ name, value }));
 }
+function resolveExecCommand(input) {
+    const hasCommand = typeof input.command === 'string';
+    const hasArgv = input.argv !== undefined;
+    if (hasCommand === hasArgv) {
+        throw general('provider exec requires exactly one of command or argv', { hasCommand, hasArgv });
+    }
+    if (hasCommand) {
+        const command = input.command?.trim() ?? '';
+        if (command === '')
+            throw general('provider exec command must not be empty');
+        return command;
+    }
+    const argv = input.argv ?? [];
+    if (argv.length === 0)
+        throw general('provider exec argv must not be empty');
+    for (const arg of argv) {
+        if (typeof arg !== 'string' || arg === '')
+            throw general('provider exec argv contains an empty argument');
+    }
+    return argv.map(shellQuote).join(' ');
+}
 function isMissingResourceError(error) {
     const message = error instanceof Error ? error.message : String(error);
     return /\b(not found|404|does not exist|missing)\b/i.test(message);
@@ -73,19 +110,29 @@ function toRouteRef(machineId, targetPort, preview, raw) {
 }
 export class BlaxelMachineProvider {
     providerName = 'blaxel';
+    imageRef;
+    templateVersion;
+    volumeSizeGb;
     config;
     constructor(options = {}) {
+        const templateVersion = options.templateVersion ?? readCrtrVersion();
+        const volumeSizeGb = options.volumeSizeGb ?? 4;
+        if (!Number.isInteger(volumeSizeGb) || volumeSizeGb < 4) {
+            throw general('Blaxel Hearth home volume must be at least 4 GB', { volumeSizeGb });
+        }
+        this.imageRef = options.image ?? defaultImageRef(templateVersion);
+        this.templateVersion = templateVersion;
+        this.volumeSizeGb = volumeSizeGb;
         this.config = {
             region: options.region ?? 'us-west-2',
             memory: options.memory ?? 2048,
-            // blaxel/prod-base:latest is NOT a supported Blaxel sandbox image (400 INVALID_IMAGE,
-            // confirmed live 2026-06-29). blaxel/node:latest ships node+npm on Alpine/musl, which the
-            // in-guest `npm i -g @crouton-kit/crouter` needs.
-            image: options.image ?? 'blaxel/node:latest',
+            image: this.imageRef,
+            templateVersion: this.templateVersion,
+            volumeSizeGb: this.volumeSizeGb,
         };
     }
     async createVolume(input) {
-        const volume = await VolumeInstance.createIfNotExists({ name: input.name, size: 1024, region: this.config.region });
+        const volume = await VolumeInstance.createIfNotExists({ name: input.name, size: this.config.volumeSizeGb * 1024, region: this.config.region });
         return {
             volumeId: volume.metadata.name ?? input.name,
             name: input.name,
@@ -101,6 +148,12 @@ export class BlaxelMachineProvider {
             volumes: input.volumeMount === undefined || input.volumeMount === null ? undefined : [{ name: input.volumeMount.volumeName, mountPath: input.volumeMount.path, readOnly: false }],
             envs: toEnvVars(input.envs),
             ports: input.ports?.map((port) => ({ target: port.target, protocol: port.protocol })),
+            // Snapshot-never-kill (P3.4): this is the only discoverable Blaxel suspend/standby
+            // primitive (@blaxel/core 0.2.94) — there is no imperative pause()/standby() call, only
+            // this create-time runtime flag. Once set, Blaxel's platform idle timer snapshots and
+            // transparently restores the sandbox on the next request instead of tearing it down.
+            // Every Hearth home is created with this on; it is never optional per-home.
+            snapshotEnabled: true,
         });
         await sandbox.wait({ maxWait: 90_000, interval: 500 }).catch(() => sandbox);
         return toMachineRef(sandbox);
@@ -122,14 +175,35 @@ export class BlaxelMachineProvider {
         }
     }
     async exec(machineId, input) {
+        if (input.stdin !== undefined && input.background === true) {
+            throw general('provider exec stdin is not supported for background commands', { machineId });
+        }
         const sandbox = await SandboxInstance.get(machineId);
-        const response = await sandbox.process.exec({
-            command: input.command,
-            env: input.env,
-            timeout: Math.ceil((input.timeoutMs ?? 55_000) / 1000),
-            workingDir: input.cwd,
-            ...(input.background === true ? { waitForCompletion: false } : { waitForCompletion: true }),
-        });
+        const stdinBody = input.stdin;
+        const stdinPath = stdinBody === undefined ? null : `/tmp/crtr-hearth-exec-${randomUUID()}.stdin`;
+        if (stdinPath !== null && stdinBody !== undefined) {
+            if (stdinBody instanceof Uint8Array) {
+                await sandbox.fs.writeBinary(stdinPath, stdinBody);
+            }
+            else {
+                await sandbox.fs.write(stdinPath, stdinBody);
+            }
+        }
+        const command = stdinPath === null ? resolveExecCommand(input) : `${resolveExecCommand(input)} < ${shellQuote(stdinPath)}`;
+        let response;
+        try {
+            response = await sandbox.process.exec({
+                command,
+                env: input.env,
+                timeout: Math.ceil((input.timeoutMs ?? 55_000) / 1000),
+                workingDir: input.cwd,
+                ...(input.background === true ? { waitForCompletion: false } : { waitForCompletion: true }),
+            });
+        }
+        finally {
+            if (stdinPath !== null)
+                await sandbox.fs.rm(stdinPath).catch(() => undefined);
+        }
         const result = record(response) ?? {};
         return {
             exitCode: typeof result.exitCode === 'number' ? result.exitCode : null,

package/dist/core/hearth/providers/types.d.ts

@@ -7,7 +7,9 @@ export interface ExecResult {
     raw?: Record<string, unknown> | null;
 }
 export interface ExecInput {
-    command: string;
+    command?: string;
+    argv?: readonly string[];
+    stdin?: string | Uint8Array;
     timeoutMs?: number;
     background?: boolean;
     env?: Record<string, string>;
@@ -55,6 +57,9 @@ export type DestroyOutcome = {
 };
 export interface MachineProvider {
     readonly providerName: 'blaxel';
+    readonly imageRef: string;
+    readonly templateVersion: string;
+    readonly volumeSizeGb: number;
     createVolume(input: {
         name: string;
     }): Promise<VolumeRef>;

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

@@ -4,6 +4,9 @@ export type SnapshotId = string;
 export type RouteId = string;
 export type RelayToken = string;
 export type GuestNodeId = string;
+export type HomeId = string;
+export type UserId = string;
+export type RelayAuthRef = string;
 export type MachineState = 'provisioning' | 'running' | 'paused' | 'stopped' | 'suspended' | 'restoring' | 'terminating' | 'terminated' | 'unknown' | string;
 export type RouteUrlSource = 'provider' | 'config' | 'derived' | 'unknown';
 export interface HomeStorageRef {
@@ -88,6 +91,34 @@ export interface VerifyResult {
     recreateLatencyMs?: number | null;
     baseline?: VerifyBaseline | null;
 }
+export interface HomeProviderDescriptor {
+    homeId: HomeId;
+    tenantId: TenantId;
+    userId?: UserId | null;
+    providerName: 'blaxel';
+    providerSandboxId: MachineId;
+    providerVolumeId: string;
+    previewEndpoint?: string | null;
+    homeAgentTarget: GuestNodeId;
+    relayAuthRef?: RelayAuthRef | null;
+    relayToken: RelayToken;
+    status?: MachineState | null;
+    templateVersion?: string | null;
+    raw?: Record<string, unknown> | null;
+}
+export interface HomeProviderRefresh {
+    providerName: 'blaxel';
+    providerSandboxId: MachineId;
+    providerVolumeId: string;
+    previewEndpoint?: string | null;
+    route?: RouteRef | null;
+    homeAgentTarget: GuestNodeId;
+    relayAuthRef?: RelayAuthRef | null;
+    templateVersion: string;
+    status: MachineState;
+    machine?: MachineRef | null;
+    updatedAt: string;
+}
 export interface HomeRecord {
     tenantId: TenantId;
     providerName: string;
@@ -100,6 +131,7 @@ export interface HomeRecord {
     verifyBaseline?: VerifyBaseline | null;
     bootstrapMarker?: BootstrapMarker | null;
     relayToken?: RelayToken | null;
+    templateVersion?: string | null;
     warmResume?: boolean | null;
     restoreLatencyMs?: number | null;
     recreateLatencyMs?: number | null;
@@ -109,7 +141,6 @@ export interface HomeRecord {
 }
 export interface M0Config {
     providerName: string;
-    registryPath: string;
     guestUser: string;
     guestHome: string;
     guestCodePath: string;
@@ -118,4 +149,7 @@ export interface M0Config {
     nodeKind: string;
     piAuthJson?: string | null;
     relayToken?: RelayToken | null;
+    imageRef?: string;
+    templateVersion?: string;
+    volumeSizeGb?: number;
 }

package/dist/core/help.d.ts

@@ -152,6 +152,19 @@ export interface BranchHelp {
      *  renderBranch reads this; never author it by hand. */
     listing?: ListingChild[];
 }
+/** Viewer-only hint about how a leaf's result should preview in the attach
+ *  viewer's chat — never part of `-h` output and never reaches agent-facing
+ *  stdout (see renderLeafArgv / renderResult, neither of which read this
+ *  field). Declared on the leaf that owns the behavior, so the attach viewer
+ *  asks the command tree instead of guessing from rendered text. */
+export interface PreviewMeta {
+    /** When true, the attach viewer collapses this leaf's successful result to
+     *  a one-line status by default (still expandable with Ctrl+O). For a
+     *  command whose result is a machine-readable dump meant for a browser/tool
+     *  rather than a human glance (e.g. a snapshot leaf). Never suppresses a
+     *  failed run — errors always show in full. */
+    suppressOutput?: boolean;
+}
 export interface LeafHelp {
     name: string;
     summary: string;
@@ -172,6 +185,9 @@ export interface LeafHelp {
      *  the schema. Renderer soft-fails to omission if it returns null or throws.
      *  Mirrors BranchHelp.dynamicState. */
     dynamicState?: () => string | null;
+    /** Attach-viewer preview hint (see PreviewMeta). Optional; omit for the
+     *  default preview behaviour. */
+    preview?: PreviewMeta;
 }
 /** Build a self-named runtime-state element: `<tag attr="v">body</tag>`. The
  *  subtree that owns the state authors it through this, so the tag name and any

package/dist/core/help.js

@@ -160,6 +160,8 @@ export function renderBranch(h) {
         // expansive with examples for judgment-heavy commands, concise for
         // single-purpose ones. It does not restate "read my -h"; the
         // capability-discovery rule in the root footer already teaches that.
+        if (lines.length > 1)
+            lines.push('');
         lines.push(`<subcommand name="${c.name}" description="${attr(c.description)}" whenToUse="${attr(c.whenToUse)}"${subs}/>`);
     }
     lines.push('</command>');

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

@@ -6,6 +6,8 @@ import type { InstalledPlugin, Scope } from '../types.js';
  * project > user > builtin. It returns the raw parsed
  * frontmatter + body; it does NOT interpret the schema, kind, gate, or rungs —
  * that is the schema/gate layer's job (callers filter by `frontmatter.kind`).
+ * Project resolution is a nearest-first stack of every ancestor `.crouter/`,
+ * while user and builtin remain singleton scopes.
  */
 export interface MemoryDoc {
     /** Path-derived identity: the doc's path under the scope's memory/ root, no
@@ -26,20 +28,18 @@ export interface MemoryResolutionOpts {
 }
 /** Canonical, unambiguous identifier for a memory document: `<scope>/<name>`. */
 export declare function memoryDocId(doc: MemoryDoc): string;
-/** All memory docs in one scope's memory/ dir, scanned recursively for *.md
- *  (topical subdirs supported), sorted by path-derived name. SKILL.md bundles
- *  are legacy Agent Skills and are ignored; crouter memory docs are plain .md
- *  files under memory/. */
+/** All native memory docs for a scope. Project scope is a nearest-first stack of
+ *  every ancestor `.crouter/memory/`; user and builtin are singleton stores. */
 export declare function listMemoryDocs(scope: Scope): MemoryDoc[];
 /** All of one plugin's substrate docs, mounted under the virtual `<pluginName>/`
  *  namespace. Walks `pluginMemoryDir(plugin)` recursively for *.md, deriving each
  *  doc's name exactly as `listMemoryDocs` does (path-relative, no extension,
  *  slash-separated) then prefixing the plugin name. Builtin has no plugins. */
 export declare function listPluginMemoryDocs(plugin: InstalledPlugin, scope: Scope): MemoryDoc[];
-/** All memory docs across the resolved scopes, in precedence order
- *  (project, then user, then builtin). Within each scope, native docs are
- *  emitted FIRST, then that scope's enabled-plugin docs — so native wins on the
- *  caller's first-wins (scope,name) dedup. Each group is name-sorted within. */
+/** All memory docs across the resolved sources, in precedence order: each
+ *  ancestor project `.crouter/` from nearest to farthest, then user, then
+ *  builtin. Within each source, native docs are emitted before enabled-plugin
+ *  docs, so native wins on the caller's first-wins dedup. */
 export declare function listAllMemoryDocs(scope?: Scope): MemoryDoc[];
 /**
  * Resolve a path-derived name to a single memory document.