@north-light/crouter 0.3.261 → 0.3.263

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

@@ -41,11 +41,13 @@
 // 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 { realpathOrSelf } from '../fs-utils.js';
+import { ambientMemoryTarget, listAllMemoryDocs, loadMemoryTargetView, } from '../memory-resolver.js';
 import { owningRootOf } from './surface-match.js';
-import { demoteDocumentTranscriptExposure, documentExposedAtOrAbove, emptyContextExposureState, exposureTarget, registerDocumentExposure, } from './injected-store.js';
+import { demoteDocumentTranscriptExposure, documentExposedAtOrAbove, emptyContextExposureState, exposedAtOrAbove, exposureTarget, registerDocumentExposure, registerExposure, } from './injected-store.js';
 import { planDelivery } from './plan.js';
-import { parseSubstrateDoc, previewLine } from './schema.js';
+import { parseSubstrateDoc, previewLine, rungRank } from './schema.js';
+import { dirDedupKey, docListingDirs, docsByName, isDirName, renderDirListing } from './listings.js';
 import { cachedEventCorpusInclusive } from './session-cache.js';
 function attr(s) {
     return s
@@ -88,24 +90,105 @@ function renderDocEnvelope(doc, rung) {
     }
     return `<memory ${attrs} />`;
 }
-/** 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 }));
+    return plan.docs.filter((r) => r.winner).map((r) => ({ doc: r.doc, rung: r.finalRung, source: r.source }));
+}
+/** The listing corpus for one event: every document the plan CONSIDERED, in
+ *  the plan's own precedence order. Winners alone are not enough — a bootless
+ *  sibling never wins anything, and a store discovered by the read walk is
+ *  absent from the ambient corpus entirely, so both would drop out of the
+ *  directory the delivered doc sits in. */
+function planListingCorpus(plan) {
+    return docsByName(plan.docs.map(({ source }) => source));
+}
+function listingBlock(dir, lines) {
+    return `<memory-listing dir="${attr(dir)}">\n${lines.join('\n')}\n</memory-listing>`;
+}
+export function deliveryAccounting() {
+    return { deliveries: new Map() };
+}
+export function accountDelivery(accounting, doc, rung, cause, source) {
+    if (accounting === undefined || rung === 'none')
+        return;
+    const key = realpathOrSelf(doc.path);
+    const held = accounting.deliveries.get(key);
+    if (held !== undefined && rungRank(held.rung) >= rungRank(rung))
+        return;
+    accounting.deliveries.set(key, {
+        rung,
+        ...(cause === undefined ? {} : { cause }),
+        ...(source === undefined ? {} : { source }),
+    });
+}
+/** The attachment semantics of a content delivery. Content is read-equivalent:
+ * it exposes its own/enclosing directory listings and fires memory-read routes.
+ * The exposure ledger makes this finite even when companion routes cycle. */
+export function contentReadAttachments(doc, opts) {
+    const { target, byName } = opts;
+    const dirs = docListingDirs(byName, doc.name);
+    const ownDir = dirs[0] === doc.name;
+    const blocks = [];
+    let listing;
+    for (const [index, dir] of dirs.entries()) {
+        // A directory absent from THIS corpus discloses nothing here, so claiming
+        // its `dir://` identity would tell the ledger a listing rendered that never
+        // did — and silence the channel that would have rendered it.
+        if (!isDirName(byName, dir))
+            continue;
+        const own = ownDir && index === 0;
+        if (!own && exposedAtOrAbove(target.state, dirDedupKey(dir), 'preview'))
+            continue;
+        if (opts.listings === 'tree') {
+            // The caller renders these members and registers the directory only for
+            // the rows it actually emits.
+            opts.dirs?.push(dir);
+            continue;
+        }
+        const explicitOwn = own && opts.explicit === true;
+        const lines = renderDirListing(byName, dir, target, !explicitOwn, (listed) => accountDelivery(opts.accounting, listed, 'preview', 'directory listing attached to content delivery', listed));
+        // An empty listing is not a listing: registering here would claim a render
+        // that produced no line and silence the next channel to reach this dir.
+        if (lines.length === 0)
+            continue;
+        registerExposure(target, dirDedupKey(dir), 'preview');
+        if (explicitOwn)
+            listing = lines;
+        else
+            blocks.push(listingBlock(dir, lines));
+    }
+    blocks.push(...memoryReadDocBlocks(realpathOrSelf(doc.path), doc.name, {
+        ...opts,
+        deliveryCause: 'memory-read companion of content delivery',
+    }));
+    return { blocks, ...(listing === undefined ? {} : { listing }) };
 }
 /** Render the plan's winners that are not already loaded at their matched rung. */
-function renderWinnerBlocks(winners, target) {
+function renderWinnerBlocks(winners, opts) {
+    const { target } = opts;
     const rendered = [];
-    for (const { doc, rung } of winners) {
+    for (const { doc, rung, source } of winners) {
         if (documentExposedAtOrAbove(target.state, doc.path, doc.body, rung))
             continue;
         const block = renderDocEnvelope(doc, rung);
         if (block === null)
             continue;
         registerDocumentExposure(target, doc.path, doc.body, rung);
+        accountDelivery(opts.accounting, doc, rung, opts.deliveryCause, source);
+        if (rung === 'content') {
+            rendered.push(...contentReadAttachments(doc, {
+                ...opts,
+                deliveryCause: 'memory-read companion of content delivery',
+            }).blocks);
+        }
         rendered.push(block);
     }
     return rendered;
 }
+/** The attachment options for one event render: listings inline as blocks,
+ *  answered from the event corpus ∪ this plan's own winners. */
+function eventAttachmentOptions(subject, target, plan, accounting) {
+    return { subject, target, byName: planListingCorpus(plan), listings: 'blocks', accounting };
+}
 function transientTranscriptTarget() {
     return exposureTarget(emptyContextExposureState(), 'transcript');
 }
@@ -114,14 +197,19 @@ function wrapAutoLoaded(blocks) {
 }
 /** 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());
+function eventPlan(subject, event, payload, memoryTarget) {
+    // An explicit memory target names a workspace other than this process's, so
+    // its corpus is resolved for that target rather than taken from the ambient
+    // session cache.
+    return memoryTarget === undefined
+        ? planDelivery(subject, ambientMemoryTarget(), event, payload, resolvedDocs())
+        : planDelivery(subject, memoryTarget, event, payload);
 }
 /** Surface docs whose `read` entries match a successfully read file, using
  * the caller-supplied daemon snapshot subject. */
-export function renderOnReadDocsForSubject(subject, readFilePath, target = transientTranscriptTarget()) {
+export function renderOnReadDocsForSubject(subject, readFilePath, target = transientTranscriptTarget(), accounting) {
     const plan = eventPlan(subject, 'read', { absoluteFile: readFilePath });
-    return wrapAutoLoaded(renderWinnerBlocks(planWinners(plan), target));
+    return wrapAutoLoaded(renderWinnerBlocks(planWinners(plan), eventAttachmentOptions(plan.subject, target, plan, accounting)));
 }
 /** 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
@@ -131,11 +219,18 @@ export function renderOnReadDocsForSubject(subject, readFilePath, target = trans
  * relationship cap BEFORE filtering, ordering, rendering, and exposure
  * 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()) {
+export function renderWorkspaceOpenDocsForSubject(subject, cwd, profileId, target = transientTranscriptTarget(), accounting) {
     const workspaceTarget = { cwd, profileId, nodeId: null };
     let winners;
+    let byName;
     try {
         winners = planWinners(planDelivery(subject, workspaceTarget, 'workspace-open'));
+        // Listings and companion routes answer from the workspace this event
+        // opened — the ambient cwd/profile of the process rendering it is a
+        // different corpus and would disclose another workspace's neighbourhood.
+        // The workspace-open plan considers project stores only, so the listing
+        // corpus is the target's full view rather than the plan's.
+        byName = docsByName(loadMemoryTargetView(workspaceTarget, { quiet: true }).docs);
     }
     catch {
         return '';
@@ -149,7 +244,14 @@ export function renderWorkspaceOpenDocsForSubject(subject, cwd, profileId, targe
         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 wrapAutoLoaded(renderWinnerBlocks(winners, target));
+    return wrapAutoLoaded(renderWinnerBlocks(winners, {
+        subject,
+        target,
+        byName,
+        memoryTarget: workspaceTarget,
+        listings: 'blocks',
+        accounting,
+    }));
 }
 /** Inner `<memory>` blocks for the memory-read event: docs whose
  * `memory-read` entries match the doc a `crtr memory read` just resolved
@@ -157,26 +259,31 @@ export function renderWorkspaceOpenDocsForSubject(subject, cwd, profileId, targe
  * `excludeRealpath` keeps the resolved doc from delivering itself). Returns
  * 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 plan = eventPlan(subject, 'memory-read', {
-        resolvedCanonicalName: name,
-        resolvedDocPath: excludeRealpath,
+export function memoryReadDocBlocks(excludeRealpath, name, opts) {
+    const plan = eventPlan(opts.subject, 'memory-read', { resolvedCanonicalName: name, resolvedDocPath: excludeRealpath }, opts.memoryTarget);
+    // A caller with no corpus of its own (the `sys context resolve` simulation)
+    // gets this plan's; every nested companion arrives with its parent's corpus
+    // already resolved.
+    return renderWinnerBlocks(planWinners(plan), {
+        ...opts,
+        byName: opts.byName ?? planListingCorpus(plan),
     });
-    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()) {
-    return wrapAutoLoaded(renderWinnerBlocks(planWinners(eventPlan(subject, 'command', { command })), target));
+export function renderOnCommandDocsForSubject(subject, command, target = transientTranscriptTarget(), accounting) {
+    const plan = eventPlan(subject, 'command', { command });
+    return wrapAutoLoaded(renderWinnerBlocks(planWinners(plan), eventAttachmentOptions(subject, target, plan, accounting)));
 }
 /** 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
  * string is load-bearing: `''` means every matching doc is already exposed at
  * its matching rung or above, which is the release — the caller lets the
  * command through. */
-export function renderPreCommandDocsForSubject(subject, command, target = transientTranscriptTarget()) {
-    return wrapAutoLoaded(renderWinnerBlocks(planWinners(eventPlan(subject, 'pre-command', { command })), target));
+export function renderPreCommandDocsForSubject(subject, command, target = transientTranscriptTarget(), accounting) {
+    const plan = eventPlan(subject, 'pre-command', { command });
+    return wrapAutoLoaded(renderWinnerBlocks(planWinners(plan), eventAttachmentOptions(subject, target, plan, accounting)));
 }
 function carriesPreCommandEntry(doc) {
     return doc.surfaces.some((entry) => entry.on === 'pre-command');

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

@@ -1,6 +1,7 @@
 import { type ExposureTarget } from './injected-store.js';
 import { type SubstrateDoc } from './schema.js';
 import type { NodeConfigSubject } from './subject-fields.js';
+import { type DeliveryAccounting } from './on-read.js';
 /** The computed "sub-personas you may spawn" menu for a subject's kind — the
  *  live restoration of the old `personas/resolve.ts` static menu, now derived
  *  at render time from the merged kind registry (`subKindsAvailableTo`) so it
@@ -9,7 +10,7 @@ import type { NodeConfigSubject } from './subject-fields.js';
  *  header). Emitted for BOTH base and orchestrator modes per the CTO's ruling —
  *  mode is irrelevant to which sub-kinds are spawnable. */
 export declare function buildSubPersonaMenu(kind: string): string;
-export declare function renderPreferencesForSubject(subject: NodeConfigSubject | null, target?: ExposureTarget): {
+export declare function renderPreferencesForSubject(subject: NodeConfigSubject | null, target?: ExposureTarget, accounting?: DeliveryAccounting): {
     block: string;
     contentDocs: SubstrateDoc[];
     tree: string;
@@ -26,7 +27,7 @@ export declare function renderPreferencesForSubject(subject: NodeConfigSubject |
  *  renders: floored docs never reach the `content` rung). Procedural guidance and factual
  *  references both live here as `knowledge`. Returns '' when nothing is
  *  eligible. */
-export declare function renderKnowledgeForSubject(subject: NodeConfigSubject, nodeId: string, target?: ExposureTarget): string;
+export declare function renderKnowledgeForSubject(subject: NodeConfigSubject, nodeId: string, target?: ExposureTarget, accounting?: DeliveryAccounting): string;
 /** What a node's configuration change newly exposes, rendered as up to three
  *  blocks in one string: the shipped protocol prose, a `<memory kind="preference">`
  *  block, and a `<memory kind="knowledge">` block — each dropped when empty, ''

package/dist/core/substrate/render.js

@@ -69,9 +69,11 @@ import { projectScopeRoots } from '../scope.js';
 // pull subject.js (canvas-db) transitively, re-tainting every CLI consumer of
 // the pure render fns. The canvas-db wrappers (renderPreferencesSection /
 // renderKnowledgeBlock) live in render-node.js instead.
-import { documentExposedAtOrAbove, registerDocumentExposure, } from './injected-store.js';
+import { documentExposedAtOrAbove, emptyContextExposureState, exposureTarget, registerDocumentExposure, registerExposure, } from './injected-store.js';
 import { bootPartitionOf, planDelivery } from './plan.js';
-import { parseSubstrateDoc, previewLine, rungRank, } from './schema.js';
+import { parseSubstrateDoc, previewLine, rungAtLeast, rungRank, } from './schema.js';
+import { accountDelivery, contentReadAttachments, } from './on-read.js';
+import { dirDedupKey, docsByName } from './listings.js';
 import { cachedEventCorpusInclusive } from './session-cache.js';
 /** The node's own store (`nodes/<id>/context/memory/`), loaded through the
  *  resolver's descriptor loader like every other store. Returned across ALL
@@ -134,16 +136,6 @@ function bootWinners(plan, partition) {
 function rendersAtBoot(doc) {
     return isVisible(doc.bootRung) && (doc.bootRung !== 'content' || doc.body.trim() !== '');
 }
-/** Register every visibly rendered winner at its displayed rung. */
-function recordRendered(target, docs) {
-    if (target === undefined)
-        return;
-    for (const d of docs) {
-        if (!rendersAtBoot(d))
-            continue;
-        registerDocumentExposure(target, d.path, d.body, d.bootRung);
-    }
-}
 // Step 2 — display ordering + grouped render.
 /** Content-prose ordering rank: general → specific. builtin=0, user=1,
  *  profile=2, project ranks start at 3 and climb by root nearness — the
@@ -204,12 +196,74 @@ function compareTreePosition(a, b) {
 function isAgentEditable(doc) {
     return doc.scope !== 'builtin' && doc.plugin === undefined;
 }
+/** The members of every directory this render's content deliveries disclosed,
+ *  raised to `preview` so the catalog tree carries the routing lines a
+ *  `<memory-listing>` would have carried on an explicit read. A member is
+ *  raised only when the raise is honest: it renders as a row (content bodies
+ *  render as prose instead), it does not already disclose its line, it is not
+ *  `unlisted`, its project's profile cap permits preview, and this context does
+ *  not already hold it at preview or above.
+ *
+ *  The corpus is `listingDocs` — the partition's own winners. A directory
+ *  holding both knowledge and preference docs therefore discloses only the
+ *  current partition's members here, and the other partition skips the
+ *  directory's `dir://` key: under-disclosure, never a false ledger claim.
+ *
+ *  A directory registers its `dir://` identity here and ONLY here — when it
+ *  actually contributed a row. A directory whose every member was rejected
+ *  rendered no listing, so the next channel to reach it must still be free to
+ *  render one. */
+function exposedDirEntries(listingDocs, dirs, target) {
+    if (dirs.length === 0)
+        return [];
+    const byPath = new Map(listingDocs.map((doc) => [doc.path, doc]));
+    const tree = buildMemoryTree(listingDocs.map((doc) => doc.source));
+    const raised = new Map();
+    for (const dir of dirs) {
+        const node = tree.node(dir);
+        if (node === null)
+            continue;
+        let rendered = false;
+        const members = [
+            ...node.childDocuments.map((member) => member.document),
+            ...node.childDirectories.flatMap((child) => (child.document === null ? [] : [child.document])),
+        ];
+        for (const member of members) {
+            const doc = byPath.get(member.path);
+            if (doc === undefined || raised.has(doc.path))
+                continue;
+            if (doc.bootRung === 'content' || rungAtLeast(doc.bootRung, 'preview'))
+                continue;
+            if (doc.unlisted)
+                continue;
+            if (!rungAtLeast(doc.projectMemory, 'preview'))
+                continue;
+            if (documentExposedAtOrAbove(target.state, doc.path, doc.body, 'preview'))
+                continue;
+            raised.set(doc.path, { ...doc, bootRung: 'preview' });
+            rendered = true;
+        }
+        if (rendered)
+            registerExposure(target, dirDedupKey(dir), 'preview');
+    }
+    return [...raised.values()];
+}
 /** STEP 2 — split deduped `winners` by rung and render each group in its
  *  display order: `content` docs first, as clean prose (general→specific,
  *  then tree position, then filename — no tree chrome); every
- *  other winner (preview/name/hidden-bootless) folds into ONE catalog tree
- *  exactly as before. */
-function renderGrouped(winners, rootLabel) {
+ *  other winner (preview/name/hidden-bootless) folds into ONE catalog tree,
+ *  which additionally carries the members that the content deliveries'
+ *  directory listings disclosed.
+ *
+ *  This function owns exposure registration for the boot renders: every doc
+ *  registers at the rung it ACTUALLY rendered at, here, rather than being
+ *  registered wholesale by the caller beforehand — which would have let a body
+ *  already delivered as a companion in another partition render again as
+ *  prose. A caller that passes no `target` renders against a throwaway ledger
+ *  (the `sys context` diagnostics), so its output matches live boot without
+ *  recording anything. */
+function renderGrouped(winners, rootLabel, subject, target, listingDocs = winners, accounting) {
+    const ledger = target ?? exposureTarget(emptyContextExposureState(), 'transcript');
     const content = [];
     const rest = [];
     for (const d of winners) {
@@ -221,11 +275,52 @@ function renderGrouped(winners, rootLabel) {
     content.sort((a, b) => scopeGeneralityRank(a) - scopeGeneralityRank(b) ||
         compareTreePosition(a, b) ||
         a.name.localeCompare(b.name));
-    const contentProse = content
+    // A body this context already holds at content does not render twice, even
+    // when the other delivery was a companion in the other boot partition.
+    const fresh = content.filter((d) => !documentExposedAtOrAbove(ledger.state, d.path, d.body, 'content'));
+    const contentProse = fresh
         .map((d) => d.body.trim())
         .filter((b) => b !== '')
         .join('\n\n');
-    return { contentProse, tree: buildTree(rest, rootLabel), contentDocs: content };
+    // Register the prose BEFORE its attachments run, so the listings and
+    // companion routes dedupe against the bodies this render just delivered.
+    for (const d of fresh) {
+        if (!rendersAtBoot(d))
+            continue;
+        registerDocumentExposure(ledger, d.path, d.body, d.bootRung);
+        accountDelivery(accounting, d, d.bootRung, undefined, d.source);
+    }
+    // ONE options object for the whole pass: `dirs` accumulates across every
+    // content doc AND every companion it routes, and the shared corpus keeps the
+    // listing tree built once.
+    const attachments = {
+        subject: subject ?? null,
+        target: ledger,
+        byName: docsByName(listingDocs.map((d) => d.source)),
+        listings: 'tree',
+        dirs: [],
+        accounting,
+    };
+    const attachmentBlocks = fresh.flatMap((doc) => contentReadAttachments(doc, attachments).blocks);
+    const raised = exposedDirEntries(listingDocs, attachments.dirs ?? [], ledger);
+    const raisedByPath = new Map(raised.map((d) => [d.path, d]));
+    const restPaths = new Set(rest.map((d) => d.path));
+    const treeDocs = [
+        ...rest.map((d) => raisedByPath.get(d.path) ?? d),
+        ...raised.filter((d) => !restPaths.has(d.path)),
+    ];
+    for (const d of treeDocs) {
+        if (!rendersAtBoot(d))
+            continue;
+        registerDocumentExposure(ledger, d.path, d.body, d.bootRung);
+        accountDelivery(accounting, d, d.bootRung, raisedByPath.has(d.path) ? 'directory listing attached to content delivery' : undefined, d.source);
+    }
+    return {
+        contentProse,
+        tree: buildTree(treeDocs, rootLabel),
+        contentDocs: fresh,
+        attachmentBlocks,
+    };
 }
 function leafSegment(name) {
     const i = name.lastIndexOf('/');
@@ -456,7 +551,7 @@ export function buildSubPersonaMenu(kind) {
  *  across nodes is preserved. ALWAYS returns a non-empty splice — the guidance
  *  frame is unconditional, so it is never empty even when no preference is
  *  eligible. */
-function buildPreferencesBlock(subject, target) {
+function buildPreferencesBlock(subject, target, accounting) {
     let contentDocs = [];
     let tree = '';
     let protocol = '';
@@ -465,8 +560,7 @@ function buildPreferencesBlock(subject, target) {
         // No nodeId: a node-local doc rides the knowledge partition whatever its
         // kind, so it never reaches the preference block.
         const winners = bootWinners(bootPlan(subject, null), 'preference');
-        recordRendered(target, winners);
-        const grouped = renderGrouped(winners, 'preferences');
+        const grouped = renderGrouped(winners, 'preferences', subject, target, winners, accounting);
         contentDocs = grouped.contentDocs;
         tree = grouped.tree;
         const shipped = contentDocs
@@ -481,7 +575,7 @@ function buildPreferencesBlock(subject, target) {
         })
             .filter((b) => b !== '');
         const subPersonaMenu = buildSubPersonaMenu(subject.kind);
-        protocol = [...shipped, ...(subPersonaMenu === '' ? [] : [subPersonaMenu])].join('\n\n');
+        protocol = [...shipped, ...grouped.attachmentBlocks, ...(subPersonaMenu === '' ? [] : [subPersonaMenu])].join('\n\n');
         if (editable.length > 0 || tree !== '') {
             memBody += `\n\n${PREFERENCES_INTRO}`;
             if (editable.length > 0)
@@ -494,8 +588,8 @@ function buildPreferencesBlock(subject, target) {
     const memoryBlock = `<memory kind="preference">\n${memBody}\n</memory>`;
     return { block: protocol === '' ? memoryBlock : `${protocol}\n\n${memoryBlock}`, contentDocs, tree };
 }
-export function renderPreferencesForSubject(subject, target) {
-    return buildPreferencesBlock(subject, target);
+export function renderPreferencesForSubject(subject, target, accounting) {
+    return buildPreferencesBlock(subject, target, accounting);
 }
 // 2. Knowledge — `<memory kind="knowledge">` (the first-message bearings).
 /** The `<memory kind="knowledge">` block embedded in the session_start bearings
@@ -510,15 +604,15 @@ export function renderPreferencesForSubject(subject, target) {
  *  renders: floored docs never reach the `content` rung). Procedural guidance and factual
  *  references both live here as `knowledge`. Returns '' when nothing is
  *  eligible. */
-export function renderKnowledgeForSubject(subject, nodeId, target) {
+export function renderKnowledgeForSubject(subject, nodeId, target, accounting) {
     const winners = bootWinners(bootPlan(subject, nodeId), 'knowledge');
-    recordRendered(target, winners);
-    const { contentProse, tree } = renderGrouped(winners, 'knowledge');
-    if (contentProse === '' && tree === '')
+    const { contentProse, tree, attachmentBlocks } = renderGrouped(winners, 'knowledge', subject, target, winners, accounting);
+    const deliveredContent = [contentProse, ...attachmentBlocks].filter((block) => block !== '').join('\n\n');
+    if (deliveredContent === '' && tree === '')
         return '';
     let out = KNOWLEDGE_INTRO;
-    if (contentProse !== '')
-        out += `\n\n${contentProse}`;
+    if (deliveredContent !== '')
+        out += `\n\n${deliveredContent}`;
     if (tree !== '')
         out += `\n\n${tree}`;
     out += `\n\n${KNOWLEDGE_OUTRO}`;
@@ -549,9 +643,7 @@ function undelivered(target, docs) {
 export function renderConfigChangeDelta(subject, nodeId, target) {
     const plan = bootPlan(subject, nodeId);
     const prefs = undelivered(target, bootWinners(plan, 'preference'));
-    const knowledgeDelta = undelivered(target, bootWinners(plan, 'knowledge'));
-    recordRendered(target, [...prefs, ...knowledgeDelta]);
-    const { contentDocs, tree } = renderGrouped(prefs, 'preferences');
+    const { contentDocs, tree, attachmentBlocks: preferenceAttachments } = renderGrouped(prefs, 'preferences', subject, target, bootWinners(plan, 'preference'));
     // Same split as the boot preference render: shipped bodies are protocol prose
     // (the rules of the node's world), agent-editable bodies are memory the node
     // can revise, and every non-content preference winner rides the one catalog.
@@ -567,8 +659,8 @@ export function renderConfigChangeDelta(subject, nodeId, target) {
     })
         .filter((b) => b !== '');
     const blocks = [];
-    if (shipped.length > 0)
-        blocks.push(`${DELTA_PROTOCOL_INTRO}\n\n${shipped.join('\n\n')}`);
+    if (shipped.length > 0 || preferenceAttachments.length > 0)
+        blocks.push(`${DELTA_PROTOCOL_INTRO}\n\n${[...shipped, ...preferenceAttachments].join('\n\n')}`);
     if (editable.length > 0 || tree !== '') {
         let body = DELTA_PREFERENCES_INTRO;
         if (editable.length > 0)
@@ -578,11 +670,14 @@ export function renderConfigChangeDelta(subject, nodeId, target) {
         body += `\n\n${PREFERENCES_OUTRO}`;
         blocks.push(`<memory kind="preference">\n${body}\n</memory>`);
     }
-    const knowledge = renderGrouped(knowledgeDelta, 'knowledge');
-    if (knowledge.contentProse !== '' || knowledge.tree !== '') {
+    // Computed AFTER the preference render: that pass may have delivered a
+    // knowledge body as a companion, and this delta must not repeat it.
+    const knowledge = renderGrouped(undelivered(target, bootWinners(plan, 'knowledge')), 'knowledge', subject, target, bootWinners(plan, 'knowledge'));
+    const knowledgeContent = [knowledge.contentProse, ...knowledge.attachmentBlocks].filter((block) => block !== '').join('\n\n');
+    if (knowledgeContent !== '' || knowledge.tree !== '') {
         let body = DELTA_KNOWLEDGE_INTRO;
-        if (knowledge.contentProse !== '')
-            body += `\n\n${knowledge.contentProse}`;
+        if (knowledgeContent !== '')
+            body += `\n\n${knowledgeContent}`;
         if (knowledge.tree !== '')
             body += `\n\n${knowledge.tree}`;
         body += `\n\n${KNOWLEDGE_OUTRO}`;

package/dist/daemon/api/__tests__/seam/api-server.test.js

@@ -25,6 +25,7 @@
 //    auth.json FILE WRITE only — the plan's sanctioned substitution.
 import { test, before, after } from 'node:test';
 import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
 import { statSync, existsSync, readFileSync, mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, dirname } from 'node:path';
@@ -33,8 +34,10 @@ import { createHeadlessHarness } from '../../../../core/__tests__/helpers/harnes
 import { createAttachKit } from '../../../../core/__tests__/helpers/broker-clients.js';
 import { ApiError, CrtrClient } from '../../../../api/index.js';
 import { createApiServer } from '../../server.js';
+import { createNode } from '../../../../core/canvas/canvas.js';
 import { apiSocketPath, inboxPath } from '../../../../core/canvas/paths.js';
 import { isPidAlive } from '../../../../core/canvas/pid.js';
+import { clearBusy, markBusy } from '../../../../core/runtime/busy.js';
 let h;
 let server;
 let client;
@@ -79,6 +82,37 @@ test('A1: /healthz is ok and the unix socket is bound mode 0600', async () => {
     const mode = statSync(sockPath).mode & 0o777;
     assert.equal(mode, 0o600, `socket mode is 0600 (fs-perms-as-auth), got 0o${mode.toString(8)}`);
 });
+test('status counts only live, busy non-human engine rows', async () => {
+    const agent = h.fabricateBrokerNode({ pi_pid: process.pid });
+    const deadPid = spawnSync(process.execPath, ['-e', '']).pid;
+    assert.ok(deadPid !== undefined, 'dead-pid fixture process started');
+    const deadAgent = h.fabricateBrokerNode({ pi_pid: deadPid });
+    const bridge = `human-status-${process.pid}`;
+    createNode({
+        node_id: bridge,
+        name: bridge,
+        created: new Date().toISOString(),
+        cwd: process.cwd(),
+        kind: 'human',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        host_kind: 'broker',
+        pi_pid: process.pid,
+    });
+    const baseline = (await client.status()).busy_node_count;
+    markBusy(agent);
+    markBusy(deadAgent);
+    markBusy(bridge);
+    try {
+        assert.equal((await client.status()).busy_node_count, baseline + 1);
+    }
+    finally {
+        clearBusy(agent);
+        clearBusy(deadAgent);
+        clearBusy(bridge);
+    }
+});
 test('attention counts reads only the requested node slice', async () => {
     const root = h.spawnRoot('attention root');
     const result = await client.attentionCounts([root, 'unknown-node']);

package/dist/daemon/api/handlers/canvas.js

@@ -266,9 +266,25 @@ function handleHistoryRead(ctx) {
 }
 // snapshot \u2014 the enriched browser canvas roster + subscribes_to adjacency.
 // Lifted from `commands/canvas-snapshot.ts` run() (dashboardRowsAll + enrichRows).
-async function handleSnapshot() {
+// `?live=true` selects active/idle rows before the row builder's disk reads.
+function snapshotLiveOnly(ctx) {
+    for (const [name] of ctx.query) {
+        if (name !== 'live')
+            throw usage(`unknown snapshot query parameter: ${name}`);
+    }
+    const values = ctx.query.getAll('live');
+    if (values.length > 1)
+        throw usage('live must appear at most once');
+    const value = values[0];
+    if (value === undefined || value === 'false' || value === '0')
+        return false;
+    if (value === 'true' || value === '1')
+        return true;
+    throw usage('live must be true or false');
+}
+async function handleSnapshot(ctx) {
     const focusedNodeIds = new Set(listFocuses().map((f) => f.node_id));
-    const rows = await dashboardRowsAllFromSource(localCanvasSource, focusedNodeIds);
+    const rows = await dashboardRowsAllFromSource(localCanvasSource, focusedNodeIds, snapshotLiveOnly(ctx));
     const asks = ticketCountsForNodes(rows.map((r) => r.node_id));
     await enrichRowsFromSource(localCanvasSource, rows, asks);
     const nodes = rows.map((row) => {