@north-light/crouter 0.3.235 → 0.3.237

package/dist/core/runtime/revive.js

@@ -24,7 +24,8 @@
 // reviveNode remains the ONLY sanctioned launcher of the node engine.
 import { existsSync } from 'node:fs';
 import { isAbsolute } from 'node:path';
-import { findNodeBySessionFile, getNode, updateNode, clearPid, recordPid, fullName, subscribersOf, } from '../canvas/index.js';
+import { findNodeBySessionFile, getNode, updateNode, clearPid, recordPid, setFrozen, clearFrozen, fullName, subscribersOf, } from '../canvas/index.js';
+import { emitEvent } from '../events/emit.js';
 import { cancelCronsOnWake } from '../canvas/crons.js';
 import { isParked, transition } from './lifecycle.js';
 import { fanDoctrineWake } from './close.js';
@@ -34,7 +35,7 @@ import { buildReviveKickoff, drainBearings, readGoal, readYieldMessage, RUNTIME_
 import { readRoadmap } from './roadmap.js';
 import { hasUnseenWakeMail } from '../feed/inbox.js';
 import { headlessBrokerHost } from './host.js';
-import { boundFleet } from './fleet.js';
+import { boundFleet, brokerCapReached, brokerThresholdsForDaemon } from './fleet.js';
 import { clearFault, beginBootFaultAttempt } from './fault.js';
 import { clearContextExposureState, initializeForkContextExposure, } from '../substrate/injected-store.js';
 import { rootOfSpine } from './nodes.js';
@@ -126,13 +127,67 @@ export function reviveNode(nodeId, opts) {
     // check before the first's registration lands. A node with a live fleet
     // entry was already revived by another path — re-launching would put a
     // SECOND broker on the same session file.
-    if (boundFleet().has(nodeId)) {
+    const fleet = boundFleet();
+    if (fleet.has(nodeId)) {
+        // The node is already running, but the ROW may still say terminal: a reopen
+        // or a retask lands on a live broker, and only this transition puts the row
+        // back where its liveness already is. Both specs accept any prior status,
+        // so this is a no-op for a row that is already active.
+        transition(nodeId, meta.intent === 'refresh' ? 'refresh-launch' : 'revive');
         return {
             window: null,
             session: meta.tmux_session ?? null,
             resumed: false,
+            outcome: 'already-live',
         };
     }
+    // The cap, consulted BEFORE any mutation below: a node that cannot get a
+    // broker must not have its cycle counter bumped, its session identity
+    // cleared, or its bearings drained on the way to being turned away.
+    if (!fleet.reserveSlot(nodeId)) {
+        if (opts.capacity === 'refuse') {
+            throw brokerCapReached(brokerThresholdsForDaemon().automaticReviveCap, fleet.size());
+        }
+        // Freezing is durable and once-per-episode: the mark stays until a launch
+        // clears it, so a node frozen across many saturated ticks announces itself
+        // exactly once and keeps its original wait timestamp (the thaw order reads
+        // it).
+        if (meta.frozen_at == null) {
+            setFrozen(nodeId, new Date().toISOString());
+            // The row holds no engine and is not getting one this pass, so a pid left
+            // over from the instance that just died would read as stale-active on
+            // every status surface. Clearing it is what makes `isFrozenRow` true and
+            // what tells the tick this row has never launched OR has already been
+            // written off, so the freeze lane owes it a launch rather than a verdict.
+            clearPid(nodeId);
+            emitEvent({
+                level: 'info',
+                event: 'broker.frozen',
+                node_id: nodeId,
+                fields: { live_count: fleet.size(), hard_cap: brokerThresholdsForDaemon().automaticReviveCap },
+            });
+        }
+        return {
+            window: null,
+            session: meta.tmux_session ?? null,
+            resumed: false,
+            outcome: 'frozen',
+        };
+    }
+    try {
+        return launchRevive(nodeId, meta, opts);
+    }
+    finally {
+        // The slot is either consumed by the fleet registration inside `launch`
+        // (making this a no-op) or given back here — the one release path covering
+        // every preflight refusal and launch failure between the claim and the
+        // registration.
+        fleet.releaseReservation(nodeId);
+    }
+}
+/** The launch itself, from the cwd preflight through `recordPid`. Split out so
+ *  the capacity claim above has exactly one release path around it. */
+function launchRevive(nodeId, meta, opts) {
     // Preflight, before any state mutation below: a recorded cwd that no longer
     // exists (e.g. a closed managed worktree whose tombstone dir was later
     // reaped) can never host a launch. Fail loud with a typed, user-visible
@@ -345,11 +400,15 @@ export function reviveNode(nodeId, opts) {
     // and status surfaces (canvas views, the daemon's identity rechecks at
     // signal boundaries) still read it.
     recordPid(nodeId, launched.pid);
+    // A launch is the definition of not-frozen, and every launcher passes
+    // through here — so this is the one place the wait mark is retired.
+    clearFrozen(nodeId);
     return {
         window: null,
         session: meta.tmux_session ?? null,
         resumed: resuming,
         launch: launched,
         faultExplanation: bootFault.explanation,
+        outcome: 'launched',
     };
 }

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

@@ -15,19 +15,11 @@ export interface SpawnChildOpts {
      *  subscription back to the spawner, spawned_by=spawner. Resident and brought
      *  forefront by default — see `rootLifecycle` for the unattended variant. */
     root?: boolean;
-    /** Only meaningful with `root`. The independent node's lifecycle.
-     *
-     *  `'resident'` (default) is the ATTENDED root: a standing conversation a
-     *  human picks up, so it owes no final, never reaps on its own, and is
-     *  brought forefront in tmux on spawn.
-     *
-     *  `'terminal'` is the UNATTENDED root: still parentless (nobody subscribes,
-     *  so nothing receives its push) but it still owes a final, so it reaps when
-     *  its work is done — and it is NEVER brought forefront. This is what
-     *  machinery firing with no human present must birth: the cron executor
-     *  spawns one when its cron's creating node is gone. A resident root there
-     *  would accrete one permanently-live node per fire (the count-based prune
-     *  never deletes live nodes) and steal the human's tmux focus every time. */
+    /** Lifecycle for the new node. Roots default to resident and managed
+     *  children default to terminal. A resident child remains an interactable,
+     *  wakeable conversation without owing a final; a terminal child remains a
+     *  bounded worker that must finalize. For roots, terminal keeps the
+     *  unattended no-viewer behavior. */
     rootLifecycle?: Lifecycle;
     /** Direct root creation waits until the broker accepts viewers before it
      *  returns. Cron-launched births use `launch`: the daemon must never wait in
@@ -103,6 +95,10 @@ export declare function assertLaunchModelRegistered(request: ModelRequest | unde
 }, registry?: ModelRegistryLike): Promise<void>;
 export interface SpawnChildResult {
     node: NodeMeta;
+    /** The birth found the broker cap full: the row exists and is marked frozen,
+     *  but no engine was launched. The node-lifecycle tick starts it when a slot
+     *  frees. */
+    frozen: boolean;
     /** The viewer window opened for a --root in tmux; null otherwise (a managed
      *  child opens no viewer, and a --root spawned outside tmux opens none). */
     window: string | null;

package/dist/core/runtime/spawn.js

@@ -21,7 +21,9 @@ import { writeGoal } from './kickoff.js';
 import { appendSituationalContext, formatSituationalProse } from './situational-context.js';
 import { hasRoadmap, seedRoadmap } from './roadmap.js';
 import { buildWakeBearings } from './bearings.js';
-import { canonicalSessionFile, contextDir, findNodeBySessionFile, getNode, fullName, recordPid } from '../canvas/index.js';
+import { canonicalSessionFile, contextDir, findNodeBySessionFile, getNode, fullName, recordPid, setFrozen } from '../canvas/index.js';
+import { boundFleet, brokerThresholdsForDaemon } from './fleet.js';
+import { emitEvent } from '../events/emit.js';
 import { jobDir } from '../canvas/paths.js';
 import { openViewerWindow, focusOf, windowOfPane, } from './placement.js';
 import { waitForBrokerViewSocket } from './placement-tmux.js';
@@ -209,16 +211,10 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
     const root = opts.root === true;
     const spawner = resolveSpawner(opts.parent, ctx.nodeId ?? null, root);
     const mode = opts.mode ?? 'base';
-    // Lifecycle keys on ROOT-ness only, independent of mode: an independent root
-    // (or `--root`) is resident by default (a conversation that persists, woken by
-    // inbox/human); every spawned child is terminal — it owes a final up the spine
-    // and reaps when done. A child born as an orchestrator is terminal/orchestrator
-    // (delegates + holds a roadmap, but still reports up), NOT resident.
-    //
-    // `rootLifecycle: 'terminal'` is the one deliberate exception: a parentless
-    // node that STILL owes a final (see the option's docblock). It is unattended
-    // by construction, so `attendedRoot` below also suppresses viewer placement.
-    const lifecycle = root ? (opts.rootLifecycle ?? 'resident') : 'terminal';
+    // Roots are resident by default; managed children are terminal workers by
+    // default. The one lifecycle option deliberately applies to both shapes so a
+    // child can be born as a standing, wakeable conversation too.
+    const lifecycle = opts.rootLifecycle ?? (root ? 'resident' : 'terminal');
     const attendedRoot = root && lifecycle === 'resident';
     // Born WITHOUT a name — the canvas-goal-capture extension names it async from
     // its first message (the kickoff task) inside its own pi process, so spawn
@@ -341,16 +337,43 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
         // Snapshot the boot-fault attempt the instant before launch — see
         // beginBootFaultAttempt — so a later diagnostic read (root+await only, below)
         // can only ever surface a fault THIS launch recorded, never a stale one.
+        // Claim the slot BEFORE the launch: `launchBrokerOrCrash` turns any launch
+        // failure — including the ledger's refusal — into a crashed row, and a birth
+        // that merely has to wait for capacity must not be crashed. Consulting the
+        // ledger here keeps the freeze decision ahead of that conversion. The
+        // reservation is consumed by the fleet's own `register` on a successful
+        // launch, so the release below is a no-op then and a give-back on any path
+        // that never registered a handle.
+        const fleet = boundFleet();
+        if (!fleet.reserveSlot(meta.node_id)) {
+            // Freezing is durable and once-per-episode; a birth is by definition the
+            // first, so the mark and its announcement always land here.
+            setFrozen(meta.node_id, new Date().toISOString());
+            emitEvent({
+                level: 'info',
+                event: 'broker.frozen',
+                node_id: meta.node_id,
+                fields: { live_count: fleet.size(), hard_cap: brokerThresholdsForDaemon().automaticReviveCap },
+            });
+            // No engine, so no readiness to wait for and no viewer to place.
+            return { node: getNode(meta.node_id), frozen: true, window: null, session: null };
+        }
         const bootFault = beginBootFaultAttempt(meta.node_id);
         // Broker is the only host: launch the detached broker ENGINE. A managed child
         // gets NO viewer — spawning it returns once the engine is launched and a human
         // opens a viewer on demand via `crtr surface node focus` / surface attach. A --root gets
         // a foreground viewer below.
-        const placed = launchBrokerOrCrash(meta.node_id, inv, {
-            cwd: meta.cwd,
-            name: fullName(meta),
-            resuming: false,
-        });
+        let placed;
+        try {
+            placed = launchBrokerOrCrash(meta.node_id, inv, {
+                cwd: meta.cwd,
+                name: fullName(meta),
+                resuming: false,
+            });
+        }
+        finally {
+            fleet.releaseReservation(meta.node_id);
+        }
         // Definitive failure: no broker pid ⇒ the node has no engine. Crash it (so the
         // daemon doesn't watch a zombie 'active') and throw so `crtr node new` exits
         // non-zero. transition('crash') is a legal from-LIVE move (still 'active' from
@@ -418,7 +441,7 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
             catch { /* best-effort — a headless spawn must never fail on viewer placement */ }
         }
         const saved = getNode(meta.node_id);
-        return { node: saved, window, session };
+        return { node: saved, frozen: false, window, session };
     }
     catch (err) {
         // Cleanup scope: a managed worktree is only removed on failure while NO

package/dist/core/substrate/frontmatter-validation.js

@@ -1,7 +1,7 @@
 import { isDocKind, parseSubstrateFrontmatter, SURFACE_EVENTS, SURFACE_RUNGS } from './schema.js';
 const RETIRED_FIELDS = ['system-prompt-visibility', 'file-read-visibility', 'applies-to', 'read-when'];
 const SURFACE_ENTRY_KEYS = ['on', 'match', 'match-frontmatter', 'gate', 'at'];
-export const SUPPRESSIBLE_RULES = ['length', 'broad-memory-read'];
+export const SUPPRESSIBLE_RULES = ['length', 'broad-memory-read', 'orphan'];
 /** Strict validation of one raw routing entry. Runtime parsing deliberately
  * tolerates malformed docs; this authoring/preflight contract does not. */
 export function lintSubstrateSurfaces(value) {

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

@@ -1,7 +1,10 @@
-export { KINDS, isDocKind, RUNGS, rungRank, rungAtLeast, SURFACE_EVENTS, SURFACE_RUNGS, bootRung, parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, normalizeNameSegment, normalizeDocName, resolveDocName, } from './schema.js';
+export { KINDS, isDocKind, RUNGS, rungRank, rungAtLeast, SURFACE_EVENTS, SURFACE_RUNGS, parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, normalizeNameSegment, normalizeDocName, resolveDocName, } from './schema.js';
 export type { DocKind, Rung, GatePredicate, SubstrateSchema, SubstrateDoc, SurfaceEntry, SurfaceEvent, SurfaceRung } from './schema.js';
 export { lintSubstrateFrontmatter, lintSubstrateSchema, lintSubstrateSurfaces, parsedSubstrateSurfaces } from './frontmatter-validation.js';
-export { matchesReadEntry, matchesMemoryReadEntry, matchesCommandEntry, readDeliveryRung, workspaceOpenRung, memoryReadDeliveryRung, commandDeliveryRung, owningRootOf, underOwningRoot } from './surface-match.js';
+export { matchesReadEntry, matchesMemoryReadEntry, matchesCommandEntry, readDeliveryRung, workspaceOpenRung, memoryReadDeliveryRung, commandDeliveryRung, matchingSurfaceEntry, surfaceEntryParticipates, owningRootOf, underOwningRoot } from './surface-match.js';
+export type { SurfaceMatchPayload } from './surface-match.js';
+export { planDelivery, bootPartitionOf } from './plan.js';
+export type { DeliveryPlan, DeliveryRecord, DeliveryPayload, EntryDecision, GateOutcome } from './plan.js';
 export { dirDedupKey, docsByName, isDirName, ancestorDirsOf, renderDirListing } from './listings.js';
 export { clearContextExposureState, cloneContextExposureState, cloneTranscriptExposureState, contentExposureIdentity, contextExposureStatesEqual, documentExposedAtOrAbove, emptyContextExposureState, exposedAtOrAbove, exposureTarget, freezePreferenceSnapshot, hasTranscriptExposure, initializeForkContextExposure, loadContextExposureState, mergeContextExposureState, registerDocumentExposure, registerExposure, replaceContextExposureState, saveContextExposureState, sharedContextExposureState, } from './injected-store.js';
 export type { ContextExposureState, ExposureSource, ExposureTarget } from './injected-store.js';
@@ -11,5 +14,5 @@ export { spineDepth, assembleNodeSubject } from './subject.js';
 export { gatePasses } from './gate.js';
 export { renderPreferencesForSubject, renderKnowledgeForSubject } from './render.js';
 export { renderPreferencesSection, renderKnowledgeBlock } from './render-node.js';
-export { renderOnReadDocsForSubject, renderWorkspaceOpenDocsForSubject, renderOnCommandDocsForSubject, renderCandidateBlocks, memoryReadDocBlocks } from './on-read.js';
+export { renderOnReadDocsForSubject, renderWorkspaceOpenDocsForSubject, renderOnCommandDocsForSubject, memoryReadDocBlocks } from './on-read.js';
 export { renderOnReadDocs, renderWorkspaceOpenDocs } from './on-read-node.js';

package/dist/core/substrate/index.js

@@ -9,7 +9,7 @@ KINDS, isDocKind,
 // ladder
 RUNGS, rungRank, rungAtLeast, 
 // surfaces (event routing)
-SURFACE_EVENTS, SURFACE_RUNGS, bootRung, 
+SURFACE_EVENTS, SURFACE_RUNGS, 
 // parse + render-shared helpers
 parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, 
 // display-name normalization
@@ -17,7 +17,8 @@ normalizeNameSegment, normalizeDocName,
 // substrate identity (explicit-name-then-path-fallback)
 resolveDocName, } from './schema.js';
 export { lintSubstrateFrontmatter, lintSubstrateSchema, lintSubstrateSurfaces, parsedSubstrateSurfaces } from './frontmatter-validation.js';
-export { matchesReadEntry, matchesMemoryReadEntry, matchesCommandEntry, readDeliveryRung, workspaceOpenRung, memoryReadDeliveryRung, commandDeliveryRung, owningRootOf, underOwningRoot } from './surface-match.js';
+export { matchesReadEntry, matchesMemoryReadEntry, matchesCommandEntry, readDeliveryRung, workspaceOpenRung, memoryReadDeliveryRung, commandDeliveryRung, matchingSurfaceEntry, surfaceEntryParticipates, owningRootOf, underOwningRoot } from './surface-match.js';
+export { planDelivery, bootPartitionOf } from './plan.js';
 export { dirDedupKey, docsByName, isDirName, ancestorDirsOf, renderDirListing } from './listings.js';
 export { clearContextExposureState, cloneContextExposureState, cloneTranscriptExposureState, contentExposureIdentity, contextExposureStatesEqual, documentExposedAtOrAbove, emptyContextExposureState, exposedAtOrAbove, exposureTarget, freezePreferenceSnapshot, hasTranscriptExposure, initializeForkContextExposure, loadContextExposureState, mergeContextExposureState, registerDocumentExposure, registerExposure, replaceContextExposureState, saveContextExposureState, sharedContextExposureState, } from './injected-store.js';
 export { scopeForCwd, profileNameFor } from './subject-fields.js';
@@ -25,5 +26,5 @@ export { spineDepth, assembleNodeSubject } from './subject.js';
 export { gatePasses } from './gate.js';
 export { renderPreferencesForSubject, renderKnowledgeForSubject } from './render.js';
 export { renderPreferencesSection, renderKnowledgeBlock } from './render-node.js';
-export { renderOnReadDocsForSubject, renderWorkspaceOpenDocsForSubject, renderOnCommandDocsForSubject, renderCandidateBlocks, memoryReadDocBlocks } from './on-read.js';
+export { renderOnReadDocsForSubject, renderWorkspaceOpenDocsForSubject, renderOnCommandDocsForSubject, memoryReadDocBlocks } from './on-read.js';
 export { renderOnReadDocs, renderWorkspaceOpenDocs } from './on-read-node.js';

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

@@ -1,12 +1,5 @@
 import { type ContextExposureState, type ExposureTarget } from './injected-store.js';
-import { type Rung, type SubstrateDoc } from './schema.js';
 import type { NodeConfigSubject } from './subject-fields.js';
-interface EventCandidate {
-    doc: SubstrateDoc;
-    rung: Rung;
-}
-/** Render the selected candidates not already loaded at their matched rung. */
-export declare function renderCandidateBlocks(subject: NodeConfigSubject | null, candidates: EventCandidate[], target: ExposureTarget): string[];
 /** Surface docs whose `read` entries match a successfully read file, using
  * the caller-supplied daemon snapshot subject. */
 export declare function renderOnReadDocsForSubject(subject: NodeConfigSubject, readFilePath: string, target?: ExposureTarget): string;
@@ -46,4 +39,3 @@ export declare function corpusHasPreCommandSurfaces(): boolean;
  * held once and then silently absent for the rest of the session. Lives here
  * rather than in the extension because the corpus accessor is private. */
 export declare function demotePreCommandExposures(state: ContextExposureState): void;
-export {};

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

@@ -33,20 +33,20 @@
 // renders at the highest rung matched by that event.
 //
 // Equal-canonical candidates (the same identity in two physical stores) do not
-// each deliver: `selectEventCandidates` collapses them to the first one
-// ELIGIBLE for that event, in source order.
-import { homedir } from 'node:os';
-import { dirname, parse, sep } from 'node:path';
-import { readText, realpathOrSelf } from '../fs-utils.js';
-import { parseFrontmatterGeneric } from '../frontmatter.js';
-import { listAllMemoryDocs, listProjectMemoryDocs, loadStoreMemoryDocs, openProjectMemoryStore } from '../memory-resolver.js';
-import { userScopeRoot } from '../scope.js';
-import { gatePasses } from './gate.js';
-import { commandDeliveryRung, memoryReadDeliveryRung, owningRootOf, preCommandDeliveryRung, readDeliveryRung, workspaceOpenRung } from './surface-match.js';
+// each deliver: the plan collapses them to the first one ELIGIBLE for that
+// event, in corpus order.
+//
+// Every selection decision — discovery, gates, the profile cap, the rung fold,
+// the first-wins collapse — belongs to planDelivery (plan.ts). This module is
+// the plan→text adapter: it owns the `<memory>` envelope, the
+// `<auto-loaded-context>` wrapper, and the exposure ledger.
+import { sep } from 'node:path';
+import { ambientMemoryTarget, listAllMemoryDocs } from '../memory-resolver.js';
+import { owningRootOf } from './surface-match.js';
 import { demoteDocumentTranscriptExposure, documentExposedAtOrAbove, emptyContextExposureState, exposureTarget, registerDocumentExposure, } from './injected-store.js';
-import { minRung, parseSubstrateDoc, previewLine } from './schema.js';
+import { planDelivery } from './plan.js';
+import { parseSubstrateDoc, previewLine } from './schema.js';
 import { cachedEventCorpusInclusive } from './session-cache.js';
-const JUNK_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.cache', '.yalc']);
 function attr(s) {
     return s
         .replace(/&/g, '&amp;')
@@ -54,48 +54,11 @@ function attr(s) {
         .replace(/</g, '&lt;')
         .replace(/>/g, '&gt;');
 }
-function isJunkAncestor(dir) {
-    return dir.split(sep).some((segment) => JUNK_DIRS.has(segment));
-}
-/** Project docs from every workspace store enclosing the read file, nearest
- * first. This is a discovery walk only: each returned doc must still match an
- * explicit trigger. A store that declares no namespace does not mount here
- * either — an unmounted store has no canonical identities to deliver under.
- * The stores carry the neutral ceiling: the read event is uncapped by design,
- * reached only by an explicit file read. */
-function enclosingProjectDocs(absReadFile) {
-    const out = [];
-    const seen = new Set();
-    const home = realpathOrSelf(homedir());
-    const userRoot = realpathOrSelf(userScopeRoot());
-    const fsRoot = parse(absReadFile).root;
-    let dir = dirname(absReadFile);
-    while (true) {
-        if (dir !== home && dir !== userRoot && !isJunkAncestor(dir)) {
-            const store = openProjectMemoryStore(dir);
-            if (store.mountStatus === 'ready' && !seen.has(store.storeRoot)) {
-                seen.add(store.storeRoot);
-                for (const source of loadStoreMemoryDocs(store, true)) {
-                    const doc = parseSubstrateDoc(source);
-                    if (doc !== null)
-                        out.push({ doc, source });
-                }
-            }
-        }
-        if (dir === home || dir === fsRoot)
-            break;
-        const parent = dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    return out;
-}
 // The event corpus INCLUDES node-scope docs: surfaces entries are explicit
 // authored routing, so a node-local doc's read/memory-read/command entry
-// fires like any other store's. Only boot excludes node scope (render.ts's
-// nodeLocalDocs owns node-local boot rendering); the active exposure state
-// prevents a lower-rung repeat here.
+// fires like any other store's. Only boot excludes node scope (render.ts owns
+// node-local boot rendering); the active exposure state prevents a lower-rung
+// repeat here.
 function resolvedDocs() {
     try {
         return cachedEventCorpusInclusive(listAllMemoryDocs, parseSubstrateDoc);
@@ -104,16 +67,6 @@ function resolvedDocs() {
         return [];
     }
 }
-function readFileFrontmatter(absReadFile) {
-    if (!/\.(md|mdx|markdown)$/i.test(absReadFile))
-        return {};
-    try {
-        return parseFrontmatterGeneric(readText(absReadFile)).data ?? {};
-    }
-    catch {
-        return {};
-    }
-}
 // Two shapes: element-with-body means the content is here; self-closing means
 // it is not — a preview carries its routing line as `readWhen` metadata so the
 // one-liner can never be mistaken for the document's content. No disk path:
@@ -135,37 +88,14 @@ function renderDocEnvelope(doc, rung) {
     }
     return `<memory ${attrs} />`;
 }
-/** The eligible candidate per canonical identity, in the caller's SOURCE order.
- * Kind and mount are settled by the loader and the profile cap by the caller's
- * rung fold, so what remains is the document gate over candidates the event
- * already gave a delivering rung. A nearer candidate that is gated off or does
- * not deliver never suppresses a farther one — the filter runs before the
- * first-wins collapse, not after it.
- *
- * A `null` subject skips gated documents and still delivers ungated ones. */
-function selectEventCandidates(subject, candidates) {
-    const selected = [];
-    const seen = new Set();
-    for (const candidate of candidates) {
-        const { doc, rung } = candidate;
-        if (rung === 'none' || seen.has(doc.name))
-            continue;
-        try {
-            if (subject === null ? doc.gate !== undefined : !gatePasses(doc, subject))
-                continue;
-        }
-        catch {
-            continue;
-        }
-        seen.add(doc.name);
-        selected.push(candidate);
-    }
-    return selected;
+/** One winner per doc, in plan (precedence) order. */
+function planWinners(plan) {
+    return plan.docs.filter((r) => r.winner).map((r) => ({ doc: r.doc, rung: r.finalRung }));
 }
-/** Render the selected candidates not already loaded at their matched rung. */
-export function renderCandidateBlocks(subject, candidates, target) {
+/** Render the plan's winners that are not already loaded at their matched rung. */
+function renderWinnerBlocks(winners, target) {
     const rendered = [];
-    for (const { doc, rung } of selectEventCandidates(subject, candidates)) {
+    for (const { doc, rung } of winners) {
         if (documentExposedAtOrAbove(target.state, doc.path, doc.body, rung))
             continue;
         const block = renderDocEnvelope(doc, rung);
@@ -179,23 +109,19 @@ export function renderCandidateBlocks(subject, candidates, target) {
 function transientTranscriptTarget() {
     return exposureTarget(emptyContextExposureState(), 'transcript');
 }
-function renderCandidates(subject, candidates, target) {
-    const rendered = renderCandidateBlocks(subject, candidates, target);
-    return rendered.length === 0
-        ? ''
-        : `<auto-loaded-context>\n${rendered.join('\n')}\n</auto-loaded-context>`;
+function wrapAutoLoaded(blocks) {
+    return blocks.length === 0 ? '' : `<auto-loaded-context>\n${blocks.join('\n')}\n</auto-loaded-context>`;
+}
+/** The corpus-carrying plan for one event. Every renderer here passes the
+ *  session-cached corpus so a hook never re-walks the filesystem. */
+function eventPlan(subject, event, payload) {
+    return planDelivery(subject, ambientMemoryTarget(), event, payload, resolvedDocs());
 }
 /** Surface docs whose `read` entries match a successfully read file, using
  * the caller-supplied daemon snapshot subject. */
 export function renderOnReadDocsForSubject(subject, readFilePath, target = transientTranscriptTarget()) {
-    const absReadFile = realpathOrSelf(readFilePath);
-    const readFrontmatter = readFileFrontmatter(absReadFile);
-    // Enclosing stores lead: a store discovered from the read file is the nearest
-    // source of an identity the mounted corpus may also carry.
-    const candidates = [...enclosingProjectDocs(absReadFile), ...resolvedDocs()]
-        .filter(({ doc }) => realpathOrSelf(doc.path) !== absReadFile)
-        .map(({ doc }) => ({ doc, rung: readDeliveryRung(doc, subject, absReadFile, readFrontmatter) }));
-    return renderCandidates(subject, candidates, target);
+    const plan = eventPlan(subject, 'read', { absoluteFile: readFilePath });
+    return wrapAutoLoaded(renderWinnerBlocks(planWinners(plan), target));
 }
 /** Workspace boot docs using the snapshot's cwd/profile instead of a canvas
  * lookup. The shared exposure target prevents a later read from repeating a
@@ -206,25 +132,24 @@ export function renderOnReadDocsForSubject(subject, readFilePath, target = trans
  * registration. A later explicit `crtr memory read` can still raise a document
  * that workspace-open disclosed at a lower rung. */
 export function renderWorkspaceOpenDocsForSubject(subject, cwd, profileId, target = transientTranscriptTarget()) {
-    let docs;
+    const workspaceTarget = { cwd, profileId, nodeId: null };
+    let winners;
     try {
-        docs = listProjectMemoryDocs(cwd, profileId)
-            .map(parseSubstrateDoc)
-            .filter((doc) => doc !== null);
+        winners = planWinners(planDelivery(subject, workspaceTarget, 'workspace-open'));
     }
     catch {
         return '';
     }
-    // Selection runs on the corpus's SOURCE order, so the nearest store wins an
-    // equal-canonical tie; the sort below is display order only — outermost
-    // workspace first, so context arrives general before specific.
-    const ordered = selectEventCandidates(subject, docs.map((doc) => ({ doc, rung: minRung(workspaceOpenRung(doc, subject), doc.projectMemory) }))).sort((a, b) => {
+    // Selection ran on the corpus's PRECEDENCE order, so the nearest store won an
+    // equal-canonical tie; this sort is display order only — outermost workspace
+    // first, so context arrives general before specific.
+    winners.sort((a, b) => {
         const aRoot = owningRootOf(a.doc) ?? '';
         const bRoot = owningRootOf(b.doc) ?? '';
         const depth = aRoot.split(sep).filter(Boolean).length - bRoot.split(sep).filter(Boolean).length;
         return depth || aRoot.localeCompare(bRoot) || a.doc.path.localeCompare(b.doc.path);
     });
-    return renderCandidates(subject, ordered, target);
+    return wrapAutoLoaded(renderWinnerBlocks(winners, target));
 }
 /** Inner `<memory>` blocks for the memory-read event: docs whose
  * `memory-read` entries match the doc a `crtr memory read` just resolved
@@ -233,20 +158,17 @@ export function renderWorkspaceOpenDocsForSubject(subject, cwd, profileId, targe
  * unwrapped blocks — the read leaf composes one `<auto-loaded-context>`
  * envelope from these plus the directory listings. */
 export function memoryReadDocBlocks(subject, excludeRealpath, name, target) {
-    const candidates = resolvedDocs()
-        .filter(({ doc }) => realpathOrSelf(doc.path) !== excludeRealpath)
-        .map(({ doc, source }) => ({
-        doc,
-        rung: memoryReadDeliveryRung(doc, source.routingAnchor, subject, name),
-    }));
-    return renderCandidateBlocks(subject, candidates, target);
+    const plan = eventPlan(subject, 'memory-read', {
+        resolvedCanonicalName: name,
+        resolvedDocPath: excludeRealpath,
+    });
+    return renderWinnerBlocks(planWinners(plan), target);
 }
 /** Surface docs whose `command` entries match an executed bash command.
  * The corpus is the resolved cwd/profile set; a command has no file from which
  * to discover enclosing project stores. */
 export function renderOnCommandDocsForSubject(subject, command, target = transientTranscriptTarget()) {
-    const candidates = resolvedDocs().map(({ doc }) => ({ doc, rung: commandDeliveryRung(doc, subject, command) }));
-    return renderCandidates(subject, candidates, target);
+    return wrapAutoLoaded(renderWinnerBlocks(planWinners(eventPlan(subject, 'command', { command })), target));
 }
 /** Surface docs whose `pre-command` entries match a bash command that has NOT
  * run yet. The exact twin of the post-execution renderer above, and its empty
@@ -254,8 +176,7 @@ export function renderOnCommandDocsForSubject(subject, command, target = transie
  * its matching rung or above, which is the release — the caller lets the
  * command through. */
 export function renderPreCommandDocsForSubject(subject, command, target = transientTranscriptTarget()) {
-    const candidates = resolvedDocs().map(({ doc }) => ({ doc, rung: preCommandDeliveryRung(doc, subject, command) }));
-    return renderCandidates(subject, candidates, target);
+    return wrapAutoLoaded(renderWinnerBlocks(planWinners(eventPlan(subject, 'pre-command', { command })), target));
 }
 function carriesPreCommandEntry(doc) {
     return doc.surfaces.some((entry) => entry.on === 'pre-command');