@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/hearth/wake-proxy/state.js

@@ -0,0 +1,342 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { general } from '../../core/errors.js';
+import { getHome, putHome, updateHome } from '../../core/hearth/registry.js';
+import { nowIso } from '../../core/fs-utils.js';
+const LOCK_STALE_MS = 2 * 60_000;
+const DEFAULT_VERSION = 1;
+const tenantLocks = new Map();
+const tenantRuntimes = new Map();
+function ensureParentDir(path) {
+    mkdirSync(dirname(path), { recursive: true });
+}
+function atomicWriteJson(path, value) {
+    ensureParentDir(path);
+    const tmp = `${path}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
+    writeFileSync(tmp, JSON.stringify(value, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 });
+    try {
+        renameSync(tmp, path);
+    }
+    catch (error) {
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch {
+            /* ignore */
+        }
+        throw error;
+    }
+}
+function readJsonFile(path) {
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+function normalizeProxyState(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw general('invalid hearth proxy state file', { valueType: value === null ? 'null' : typeof value });
+    }
+    const obj = value;
+    const owner = obj.owner;
+    if (owner === null || typeof owner !== 'object' || Array.isArray(owner)) {
+        throw general('invalid hearth proxy state owner', { valueType: typeof owner });
+    }
+    const ownerObj = owner;
+    if (typeof ownerObj.ownerUserId !== 'string' || typeof ownerObj.defaultTenantId !== 'string' || typeof ownerObj.tokenHash !== 'string') {
+        throw general('invalid hearth proxy state owner fields', { owner });
+    }
+    const tenantsRaw = obj.tenants;
+    const tenants = {};
+    if (tenantsRaw !== undefined) {
+        if (tenantsRaw === null || typeof tenantsRaw !== 'object' || Array.isArray(tenantsRaw)) {
+            throw general('invalid hearth proxy tenants map', { tenantsRaw });
+        }
+        for (const [tenantId, tenant] of Object.entries(tenantsRaw)) {
+            if (tenant === null || typeof tenant !== 'object' || Array.isArray(tenant))
+                continue;
+            const draft = tenant;
+            if (typeof draft.tenantId !== 'string' || typeof draft.ownerUserId !== 'string' || typeof draft.m0RegistryPath !== 'string' || typeof draft.idleAfterMs !== 'number' || typeof draft.updatedAt !== 'string') {
+                continue;
+            }
+            tenants[tenantId] = {
+                tenantId: draft.tenantId,
+                ownerUserId: draft.ownerUserId,
+                m0RegistryPath: draft.m0RegistryPath,
+                idleAfterMs: draft.idleAfterMs,
+                lastActivityAt: typeof draft.lastActivityAt === 'string' ? draft.lastActivityAt : null,
+                lastWakeAt: typeof draft.lastWakeAt === 'string' ? draft.lastWakeAt : null,
+                lastPauseAt: typeof draft.lastPauseAt === 'string' ? draft.lastPauseAt : null,
+                updatedAt: draft.updatedAt,
+            };
+        }
+    }
+    return {
+        version: DEFAULT_VERSION,
+        owner: {
+            ownerUserId: ownerObj.ownerUserId,
+            defaultTenantId: ownerObj.defaultTenantId,
+            tokenHash: ownerObj.tokenHash,
+            createdAt: typeof ownerObj.createdAt === 'string' ? ownerObj.createdAt : nowIso(),
+        },
+        tenants,
+    };
+}
+export function loadProxyState(statePath) {
+    if (!existsSync(statePath))
+        return null;
+    return normalizeProxyState(readJsonFile(statePath));
+}
+export function saveProxyState(statePath, state) {
+    atomicWriteJson(statePath, state);
+    return state;
+}
+export function ensureProxyState(config) {
+    const existing = loadProxyState(config.statePath);
+    const now = nowIso();
+    const base = existing ?? {
+        version: DEFAULT_VERSION,
+        owner: {
+            ownerUserId: config.ownerUserId,
+            defaultTenantId: config.defaultTenantId,
+            tokenHash: config.ownerTokenHash,
+            createdAt: now,
+        },
+        tenants: {},
+    };
+    base.owner.ownerUserId = config.ownerUserId;
+    base.owner.defaultTenantId = config.defaultTenantId;
+    base.owner.tokenHash = config.ownerTokenHash;
+    if (base.owner.createdAt.trim() === '')
+        base.owner.createdAt = now;
+    base.tenants[config.defaultTenantId] = ensureTenantState(base.tenants[config.defaultTenantId], config, now);
+    return saveProxyState(config.statePath, base);
+}
+export function getTenantState(state, tenantId) {
+    return state.tenants[tenantId] ?? null;
+}
+function ensureTenantState(existing, config, now = nowIso()) {
+    return {
+        tenantId: existing?.tenantId ?? config.defaultTenantId,
+        ownerUserId: existing?.ownerUserId ?? config.ownerUserId,
+        m0RegistryPath: existing?.m0RegistryPath ?? config.m0RegistryPath,
+        idleAfterMs: existing?.idleAfterMs ?? config.idlePauseMs,
+        lastActivityAt: existing?.lastActivityAt ?? null,
+        lastWakeAt: existing?.lastWakeAt ?? null,
+        lastPauseAt: existing?.lastPauseAt ?? null,
+        updatedAt: now,
+    };
+}
+export function updateTenantState(config, tenantId, mutate) {
+    const state = ensureProxyState(config);
+    const current = state.tenants[tenantId] ?? ensureTenantState(undefined, config);
+    const draft = { ...current, tenantId, ownerUserId: config.ownerUserId, m0RegistryPath: config.m0RegistryPath, idleAfterMs: config.idlePauseMs };
+    const next = mutate(draft) ?? draft;
+    next.updatedAt = nowIso();
+    state.tenants[tenantId] = next;
+    return saveProxyState(config.statePath, state).tenants[tenantId];
+}
+export function touchTenantActivity(config, tenantId) {
+    return updateTenantState(config, tenantId, (tenant) => {
+        tenant.lastActivityAt = nowIso();
+    });
+}
+export function touchTenantWake(config, tenantId) {
+    return updateTenantState(config, tenantId, (tenant) => {
+        tenant.lastWakeAt = nowIso();
+    });
+}
+export function touchTenantPause(config, tenantId) {
+    return updateTenantState(config, tenantId, (tenant) => {
+        tenant.lastPauseAt = nowIso();
+    });
+}
+export function withTenantLock(tenantId, fn) {
+    const previous = tenantLocks.get(tenantId) ?? Promise.resolve();
+    let release;
+    const current = new Promise((resolve) => {
+        release = resolve;
+    });
+    const tail = previous.then(() => current, () => current);
+    tenantLocks.set(tenantId, tail);
+    return previous
+        .catch(() => undefined)
+        .then(() => Promise.resolve(fn()))
+        .finally(() => {
+        release();
+        if (tenantLocks.get(tenantId) === tail) {
+            tenantLocks.delete(tenantId);
+        }
+    });
+}
+function runtimeFor(tenantId) {
+    const existing = tenantRuntimes.get(tenantId);
+    if (existing !== undefined)
+        return existing;
+    const created = {
+        counts: { http: 0, ws: 0, wake: 0 },
+        idleDeadlineAt: null,
+        timer: null,
+    };
+    tenantRuntimes.set(tenantId, created);
+    return created;
+}
+function clearTimer(runtime) {
+    if (runtime.timer !== null) {
+        clearTimeout(runtime.timer);
+        runtime.timer = null;
+    }
+    runtime.idleDeadlineAt = null;
+}
+export function beginActivity(config, tenantId, kind) {
+    const runtime = runtimeFor(tenantId);
+    runtime.counts[kind] += 1;
+    clearTimer(runtime);
+    touchTenantActivity(config, tenantId);
+    return {
+        tenantId,
+        kind,
+        acquiredAt: nowIso(),
+        closed: false,
+    };
+}
+export function endActivity(handle) {
+    const runtime = runtimeFor(handle.tenantId);
+    if (!handle.closed) {
+        handle.closed = true;
+        runtime.counts[handle.kind] = Math.max(0, runtime.counts[handle.kind] - 1);
+    }
+    const total = runtime.counts.http + runtime.counts.ws + runtime.counts.wake;
+    return {
+        tenantId: handle.tenantId,
+        counts: { ...runtime.counts },
+        total,
+        idleDeadlineAt: runtime.idleDeadlineAt,
+    };
+}
+export function getTenantActivitySnapshot(tenantId) {
+    const runtime = runtimeFor(tenantId);
+    return {
+        tenantId,
+        counts: { ...runtime.counts },
+        total: runtime.counts.http + runtime.counts.ws + runtime.counts.wake,
+        idleDeadlineAt: runtime.idleDeadlineAt,
+    };
+}
+export function setTenantIdleTimer(tenantId, deadlineAt, timer) {
+    const runtime = runtimeFor(tenantId);
+    clearTimer(runtime);
+    runtime.idleDeadlineAt = deadlineAt;
+    runtime.timer = timer;
+}
+export function clearTenantIdleTimer(tenantId) {
+    clearTimer(runtimeFor(tenantId));
+}
+export function readTenantHome(config, tenantId) {
+    return getHome(config.m0RegistryPath, tenantId);
+}
+function mergeHomeStorage(home, m0Config, volumeId) {
+    const next = { ...home };
+    next.providerName = m0Config.providerName;
+    next.homeStorage = {
+        kind: 'volume',
+        durability: 'durable-volume',
+        longTermContract: true,
+        ownerMachineId: home.machineId,
+        guestHome: m0Config.guestHome,
+        volumeId,
+        mountPath: m0Config.guestHome,
+    };
+    return next;
+}
+export function ensureSeededM0Registry(config, m0Config) {
+    const existing = getHome(config.m0RegistryPath, config.defaultTenantId);
+    if (existing !== null) {
+        if (typeof existing.machineId !== 'string' || existing.machineId.trim() === '') {
+            throw general('hearth m0 registry is missing machineId — run the existing M0 provision/bootstrap flow before starting the wake proxy', {
+                tenantId: config.defaultTenantId,
+                registryPath: config.m0RegistryPath,
+            });
+        }
+        const updated = updateHome(config.m0RegistryPath, config.defaultTenantId, (home) => {
+            if (home.providerName !== m0Config.providerName)
+                home.providerName = m0Config.providerName;
+            if (!home.homeStorage || home.homeStorage.volumeId.trim() === '') {
+                if (config.seedHome === null) {
+                    throw general('hearth m0 registry is missing homeStorage.volumeId and no seed home was provided', {
+                        tenantId: config.defaultTenantId,
+                        registryPath: config.m0RegistryPath,
+                    });
+                }
+                home.homeStorage = mergeHomeStorage(home, m0Config, config.seedHome.volumeId).homeStorage;
+            }
+            else {
+                home.homeStorage = {
+                    ...home.homeStorage,
+                    ownerMachineId: home.machineId,
+                    guestHome: m0Config.guestHome,
+                    mountPath: m0Config.guestHome,
+                };
+            }
+            if ((typeof home.nodeId !== 'string' || home.nodeId.trim() === '') && config.seedHome?.nodeId) {
+                home.nodeId = config.seedHome.nodeId;
+            }
+            if ((typeof home.relayToken !== 'string' || home.relayToken.trim() === '') && config.seedHome?.relayToken) {
+                home.relayToken = config.seedHome.relayToken;
+            }
+            if (home.state === undefined || home.state === null || home.state === '') {
+                home.state = config.seedHome?.state ?? 'running';
+            }
+            if ((home.webRoute === undefined || home.webRoute === null) && config.seedHome?.webRouteUrl) {
+                home.webRoute = {
+                    routeId: config.seedHome.webRouteUrl,
+                    machineId: home.machineId,
+                    targetPort: m0Config.webPort,
+                    url: config.seedHome.webRouteUrl,
+                    concreteUrl: config.seedHome.webRouteUrl,
+                    concreteUrlSource: 'config',
+                    createdAt: nowIso(),
+                    raw: null,
+                };
+            }
+            home.updatedAt = nowIso();
+        });
+        return updated;
+    }
+    if (config.seedHome === null) {
+        throw general('hearth m0 registry is empty and no HEARTH_SEED_* values were provided — run the existing M0 provision/bootstrap flow before starting the wake proxy', {
+            registryPath: config.m0RegistryPath,
+            tenantId: config.defaultTenantId,
+        });
+    }
+    const now = nowIso();
+    const home = {
+        tenantId: config.seedHome.tenantId,
+        providerName: m0Config.providerName,
+        machineId: config.seedHome.machineId,
+        homeStorage: {
+            kind: 'volume',
+            durability: 'durable-volume',
+            longTermContract: true,
+            ownerMachineId: config.seedHome.machineId,
+            guestHome: m0Config.guestHome,
+            volumeId: config.seedHome.volumeId,
+            mountPath: m0Config.guestHome,
+        },
+        state: config.seedHome.state ?? 'running',
+        nodeId: config.seedHome.nodeId,
+        relayToken: config.seedHome.relayToken,
+        webRoute: config.seedHome.webRouteUrl
+            ? {
+                routeId: config.seedHome.webRouteUrl,
+                machineId: config.seedHome.machineId,
+                targetPort: m0Config.webPort,
+                url: config.seedHome.webRouteUrl,
+                concreteUrl: config.seedHome.webRouteUrl,
+                concreteUrlSource: 'config',
+                createdAt: now,
+                raw: null,
+            }
+            : null,
+        createdAt: now,
+        updatedAt: now,
+    };
+    return putHome(config.m0RegistryPath, home);
+}

package/dist/hearth/wake-proxy/types.d.ts

@@ -0,0 +1,76 @@
+import type { GuestNodeId, MachineId, MachineState, M0Config, RelayToken, TenantId } from '../../core/hearth/types.js';
+export interface HearthProxyOwnerState {
+    ownerUserId: string;
+    defaultTenantId: TenantId;
+    tokenHash: string;
+    createdAt: string;
+}
+export interface HearthProxyTenantState {
+    tenantId: TenantId;
+    ownerUserId: string;
+    m0RegistryPath: string;
+    idleAfterMs: number;
+    lastActivityAt: string | null;
+    lastWakeAt: string | null;
+    lastPauseAt: string | null;
+    updatedAt: string;
+}
+export interface HearthProxyState {
+    version: 1;
+    owner: HearthProxyOwnerState;
+    tenants: Record<TenantId, HearthProxyTenantState>;
+}
+export interface HearthProxySeedHome {
+    tenantId: TenantId;
+    machineId: MachineId;
+    nodeId: GuestNodeId;
+    relayToken: RelayToken;
+    volumeId: string;
+    state?: MachineState | null;
+    webRouteUrl?: string | null;
+}
+export interface HearthProxyConfig {
+    host: string;
+    port: number;
+    publicOrigin: string;
+    statePath: string;
+    m0RegistryPath: string;
+    ownerUserId: string;
+    defaultTenantId: TenantId;
+    ownerTokenHash: string;
+    idlePauseMs: number;
+    wakeTimeoutMs: number;
+    readyTimeoutMs: number;
+    cookieSecure: boolean;
+    seedHome: HearthProxySeedHome | null;
+}
+export interface HearthWakeProxyRuntime {
+    proxy: HearthProxyConfig;
+    m0: M0Config;
+}
+export type ActivityKind = 'http' | 'ws' | 'wake';
+export interface TenantActivitySnapshot {
+    tenantId: TenantId;
+    counts: Record<ActivityKind, number>;
+    total: number;
+    idleDeadlineAt: string | null;
+}
+export interface ActivityHandle {
+    tenantId: TenantId;
+    kind: ActivityKind;
+    acquiredAt: string;
+    closed: boolean;
+}
+export interface AwakenedHome {
+    tenantId: TenantId;
+    nodeId: GuestNodeId;
+    routeUrl: string;
+    relayToken: RelayToken;
+    machineId: MachineId;
+    webPort: number;
+}
+export interface WakeProxyLogger {
+    info(message: string, details?: Record<string, unknown>): void;
+    warn(message: string, details?: Record<string, unknown>): void;
+    error(message: string, details?: Record<string, unknown>): void;
+}

package/dist/hearth/wake-proxy/types.js

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

package/dist/index.js

@@ -1,8 +1,9 @@
 // @crouton-kit/crouter — the sanctioned library surface (design D1).
 //
 // This barrel is the ONLY supported way to import crouter as a library; the
-// `exports` map gates off deep subpath imports, so consumers (notably
-// @crouton-kit/crouter-web) depend on exactly the symbols re-exported here.
+// `exports` map gates off deep subpath imports, so consumers depend on exactly
+// the symbols re-exported here — notably the in-tree web client, which reaches
+// the runtime through the `@crouton-kit/crouter/web` seam.
 // Everything below is a stable, server-facing surface: runtime control that
 // keeps the canvas-row ⇄ pi-session lockstep guarantees, read-only canvas/
 // telemetry queries, and the broker socket client + wire protocol. Nothing

package/dist/pi-extensions/__tests__/canvas-context-intro.test.js

@@ -85,7 +85,7 @@ after(() => {
 test('boot intro asserts the node\'s OWN identity up front (regression: forked node impersonated source)', () => {
     createNode(node('alpha', { name: 'fix-auth', kind: 'developer' }));
     const intro = buildContextIntro('alpha');
-    assert.match(intro, /<crtr-identity>/, 'opens with an explicit identity block');
+    assert.match(intro, /<crtr-bearings>/, 'opens with the bearings section');
     assert.match(intro, /You are node alpha/, 'names the node by its own id');
     assert.match(intro, /kind developer/, 'states the node kind');
     // Gated (Option A): a fresh (non-fork) node's bearings are its FIRST entry, so
@@ -93,9 +93,10 @@ test('boot intro asserts the node\'s OWN identity up front (regression: forked n
     // naming the copied history "inherited reference material") is fork-only and must
     // NOT appear here.
     assert.ok(!/inherited reference material/.test(intro), 'a non-fork node carries no disown-the-earlier-narrative line');
-    // The identity block must come BEFORE the <crtr-context> bearings, so it is the
-    // first thing the model reads — the orienting frame, not a trailing note.
-    assert.ok(intro.indexOf('<crtr-identity>') < intro.indexOf('<crtr-context'), 'identity assertion precedes the context bearings');
+    // Identity LEADS the bearings block (no wrapper of its own), so it is the first
+    // prose the model reads — the orienting frame, not a trailing note.
+    assert.match(intro, /<crtr-bearings>\nYou are node alpha/, 'identity leads the bearings block');
+    assert.ok(intro.indexOf('<crtr-bearings>') < intro.indexOf('<project_context>'), 'bearings precede project context');
 });
 test('a FORK\'s intro names the source and disowns it (regression: fork acted AS the source)', () => {
     // The source node whose conversation pi copied into the fork.
@@ -124,7 +125,7 @@ test('session_start INJECTS the fork\'s own bearings despite the inherited sourc
     createNode(node('srcA'));
     createNode(node('forkB', { fork_from: 'srcA' }));
     // A fork boots with the SOURCE's whole conversation copied in — including the
-    // source's <crtr-context> intro entry (which names srcA, not forkB).
+    // source's bearings intro entry (which names srcA, not forkB).
     const inheritedSourceBlock = introEntry(buildContextIntro('srcA'));
     process.env['CRTR_NODE_ID'] = 'forkB';
     const pi = makeFakePi();

package/dist/pi-extensions/canvas-context-intro.js

@@ -15,11 +15,11 @@
 //
 // The block carries: the path to the node's own context dir and the framing for
 // what belongs there (a shared document store for the other nodes). EVERY node
-// also gets a `<knowledge>` block rendered from the document substrate —
-// eligible `knowledge` docs at their system-prompt visibility rung, plus the
-// node's own node-local substrate docs — so the bearings name what to read on
-// demand. (Preferences surface as their own `<preferences>` block of the
-// system prompt, not in this block.) An
+// also gets a `<memory kind="knowledge">` block rendered from the document
+// substrate — eligible `knowledge` docs at their system-prompt visibility rung,
+// plus the node's own node-local substrate docs — so the bearings name what to
+// read on demand. (Preferences surface as their own `<memory kind="preference">`
+// block of the system prompt, not in this block.) An
 // orchestrator additionally gets the across-refresh-cycles framing (the one
 // thing a terminal worker's bearings drop). The prose lives in
 // core/runtime/bearings.ts (shared with the promotion guidance dump).
@@ -31,8 +31,8 @@
 // (whose bearings name the SOURCE's node id), so the handler must NOT treat that
 // inherited block as ours; it only skips when a bearings block belonging to OUR
 // node is already present (exact `details.nodeId` stamp, content-match
-// fallback), otherwise it injects ours — whose <crtr-identity> block reasserts
-// the fork's identity over the inherited persona. This is ONE of two reinforcing
+// fallback), otherwise it injects ours — whose identity assertion (leading the
+// <crtr-bearings> block) reasserts the fork's identity over the inherited persona. This is ONE of two reinforcing
 // channels: spawn.ts ALSO prepends the same identity assertion to a fork's
 // kickoff prompt (the turn-triggering message), so the override does not rest on
 // a single trailing custom_message.

package/dist/pi-extensions/canvas-doc-substrate.js

@@ -9,13 +9,13 @@
 // It owns the substrate's two new pi hooks:
 //
 //   1. before_agent_start — the BOOT system-prompt half. Splices the rendered
-//      `<preferences>` + `<memory-guidance>` blocks into `event.systemPrompt`,
-//      right after pi's native "Available tools" list (before the
-//      `\n\nGuidelines:` anchor), so the substrate's standing directives sit in
-//      the tool-selection frame the agent reads while choosing a capability —
-//      mirroring the personal crouter-help.ts anchor logic. Falls back to
-//      appending when the anchor is absent. (Knowledge rides the `<crtr-context>`
-//      bearings message instead — see core/substrate/render.ts.)
+//      `<memory kind="preference">` block (memory-usage guidance + preferences)
+//      into `event.systemPrompt`, right after pi's native "Available tools" list
+//      (before the `\n\nGuidelines:` anchor), so the substrate's standing
+//      directives sit in the tool-selection frame the agent reads while choosing
+//      a capability — mirroring the personal crouter-help.ts anchor logic. Falls
+//      back to appending when the anchor is absent. (The `<memory kind="knowledge">`
+//      catalog rides the bearings message instead — see core/substrate/render.ts.)
 //
 //   2. tool_result (gated on `read`) — the ON-READ half. For each non-error
 //      `read`, surfaces the substrate docs that should appear alongside the file
@@ -34,7 +34,7 @@
 // with no dep on the pi packages. Mirrors canvas-context-intro.ts.
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
-import { renderMemoryGuidance, renderOnReadDocs, renderPreferencesSection, } from '../core/substrate/index.js';
+import { renderOnReadDocs, renderPreferencesSection, } from '../core/substrate/index.js';
 import { clearSessionCache } from '../core/substrate/session-cache.js';
 import { loadInjectedDocs, saveInjectedDocs } from '../core/substrate/injected-store.js';
 // ---------------------------------------------------------------------------
@@ -42,9 +42,34 @@ import { loadInjectedDocs, saveInjectedDocs } from '../core/substrate/injected-s
 // ---------------------------------------------------------------------------
 /** The stable seam that closes pi's native "Available tools" list. We splice the
  *  substrate's boot sections right before it — the agent decides which capability
- *  to reach for while reading the tools, so skills/preferences must sit there,
- *  not far below. Mirrors crouter-help.ts. Falls back to appending if absent. */
+ *  to reach for while reading the tools, so memory docs/preferences must sit
+ *  there, not far below. Mirrors crouter-help.ts. Falls back to appending if absent. */
 const TOOLS_ANCHOR = '\n\nGuidelines:';
+const AUTO_CONTEXT_RE = /<auto-loaded-context(?:\s[^>]*)?>\n([\s\S]*?)\n<\/auto-loaded-context>/;
+function mergeAutoLoadedContext(injected, content) {
+    const match = injected.match(AUTO_CONTEXT_RE);
+    const inner = match?.[1]?.trim();
+    if (!inner)
+        return content;
+    const existingText = content.map((block) => block.text ?? '').join('\n');
+    if (existingText.includes(inner))
+        return content;
+    const existingIdx = content.findIndex((block) => typeof block.text === 'string' && AUTO_CONTEXT_RE.test(block.text));
+    if (existingIdx !== -1) {
+        return content.map((block, idx) => {
+            if (idx !== existingIdx || typeof block.text !== 'string')
+                return block;
+            return {
+                ...block,
+                text: block.text.replace(AUTO_CONTEXT_RE, (_whole, current) => {
+                    const trimmed = String(current).trim();
+                    return `<auto-loaded-context>\n${inner}${trimmed === '' ? '' : `\n${trimmed}`}\n</auto-loaded-context>`;
+                }),
+            };
+        });
+    }
+    return [{ type: 'text', text: `<auto-loaded-context>\n${inner}\n</auto-loaded-context>` }, ...content];
+}
 /**
  * Register the document substrate's two render hooks on `pi`.
  *
@@ -67,24 +92,21 @@ export function registerCanvasDocSubstrate(pi) {
     const injectedDocs = loadInjectedDocs(nodeId);
     pi.on('session_start', () => {
         // Only the per-session substrate PARSE cache resets each session (so the
-        // corpus is re-scanned, picking up skill/memory writes). injectedDocs is
+        // corpus is re-scanned, picking up memory writes). injectedDocs is
         // transcript-scoped, not session-scoped — deliberately NOT cleared here.
         clearSessionCache();
     });
-    // 1. BOOT system-prompt half — splice `<preferences>` + `<memory-guidance>`.
-    //    The guidance block is always present for a canvas node (the memory system
-    //    always exists), so the splice is never empty even when the preferences
-    //    tree is. (Knowledge no longer enters the system prompt — it rides the
-    //    `<crtr-context>` bearings message via renderKnowledgeBlock.)
+    // 1. BOOT system-prompt half — splice the `<memory kind="preference">` block
+    //    (memory-usage guidance + preferences). The guidance frame is always
+    //    present for a canvas node (the memory system always exists), so the block
+    //    is never empty even when no preference is eligible. (The knowledge catalog
+    //    no longer enters the system prompt — it rides the bearings message via
+    //    renderKnowledgeBlock.)
     pi.on('before_agent_start', (event) => {
         try {
-            const sections = [
-                renderPreferencesSection(nodeId),
-                renderMemoryGuidance(),
-            ].filter((s) => s !== '');
-            if (sections.length === 0)
+            const block = renderPreferencesSection(nodeId);
+            if (block === '')
                 return; // nothing eligible — leave the prompt untouched
-            const block = sections.join('\n\n');
             const idx = event.systemPrompt.indexOf(TOOLS_ANCHOR);
             if (idx === -1) {
                 return { systemPrompt: `${event.systemPrompt}\n\n${block}` };
@@ -118,8 +140,9 @@ export function registerCanvasDocSubstrate(pi) {
             // A doc surfaced → renderOnReadDocs grew injectedDocs; persist the set so
             // the dedup survives a later dormancy → revive(resume).
             saveInjectedDocs(nodeId, injectedDocs);
-            // Prepend the surfacing docs ahead of the file contents.
-            return { content: [{ type: 'text', text: injected }, ...event.content] };
+            // Fold into any existing auto-loaded-context block from sibling read hooks;
+            // otherwise prepend one quiet block ahead of the file contents.
+            return { content: mergeAutoLoadedContext(injected, event.content) };
         }
         catch {
             return; // inert on error — a bug must degrade a read, never break it