@north-light/crouter 0.3.232 → 0.3.234

package/dist/core/__tests__/fixtures/fake-engine.js

@@ -43,9 +43,7 @@ export const FAIL_BEFORE_SESSION_START_ONCE = '__FAIL_BEFORE_SESSION_START_ONCE_
  *  no turn) — the shape a broker whose model resolved but whose provider has
  *  no installed credential produces ("No API key found for <provider>"). */
 export const REJECT_PROMPT_CALL = '__REJECT_PROMPT_CALL__';
-// ---------------------------------------------------------------------------
 // node dir / proof helpers
-// ---------------------------------------------------------------------------
 function nodeDirFromEnv() {
     const home = (process.env['CRTR_HOME'] ?? '').trim();
     const nodeId = (process.env['CRTR_NODE_ID'] ?? '').trim();
@@ -70,12 +68,10 @@ function recordError(dir, msg) {
         /* ignore */
     }
 }
-// ---------------------------------------------------------------------------
 // SessionManager — the broker calls .open(path) (resume) or .create(cwd) (fresh)
 // and hands the result to createAgentSession. sessionId/sessionFile round-trip
 // through it, so a resume (`--session <pi_session_file>`) re-opens the SAME
 // .jsonl the fresh start created — the load-bearing identity for revive.
-// ---------------------------------------------------------------------------
 export class SessionManager {
     sessionId;
     sessionFile;
@@ -138,7 +134,6 @@ export class SessionManager {
         return this.leafId;
     }
 }
-// ---------------------------------------------------------------------------
 // AgentSessionEvent stream synthesis. The fake emits a
 // REALISTIC streaming assistant turn through session.subscribe — the SAME channel
 // the real pi engine feeds the broker's fan-out — so the frames a `crtr surface attach`
@@ -150,7 +145,6 @@ export class SessionManager {
 // union, so a drift in the shape of any variant emitTurn() constructs (the
 // streaming subset: the message_*, tool_execution_*, agent/turn start+end events)
 // fails the build, not a test.
-// ---------------------------------------------------------------------------
 /** A minimal but fully-typed AssistantMessage. `pad` bytes of filler text let a
  *  test size a single frame to multiple MiB (G8 backpressure flood). */
 function assistantMessage(text, pad = 0) {
@@ -403,7 +397,7 @@ class FakeSession {
         this.recordModel();
         return Promise.resolve();
     }
-    // --- list_models / cycle_model read surface (real-SDK parity) ----------------
+    // list_models / cycle_model read surface (real-SDK parity)
     /** The broker's read-op picker data (buildListModelsData → registryOf(session))
      *  reads this. For a model-less boot it is the self-healing mask proxy — see
      *  modelRt. */
@@ -448,11 +442,11 @@ class FakeSession {
             /* best effort */
         }
     }
-    // --- naming is cosmetic (broker calls it in a try/catch) ---------------------
+    // naming is cosmetic (broker calls it in a try/catch)
     setSessionName(_name) {
         /* no-op recording stub */
     }
-    // --- controller-drive stubs (no controller connects in these tests) ----------
+    // controller-drive stubs (no controller connects in these tests)
     prompt(text, _options) {
         // Rejection seam: the engine refuses the call itself (pi's no-provider-
         // credential shape) — the promise rejects and NO lifecycle event fires.
@@ -865,7 +859,7 @@ class FakeSession {
             /* best effort */
         }
     }
-    // --- the ctx passed to fired handlers (union across both focus extensions) ---
+    // the ctx passed to fired handlers (union across both focus extensions)
     buildCtx() {
         return {
             sessionManager: {
@@ -1250,16 +1244,12 @@ export async function createAgentSessionRuntime(createRuntime, options) {
     const initial = await createRuntime(options);
     return new FakeAgentSessionRuntime(createRuntime, options.cwd, options.agentDir, initial.session, initial.services);
 }
-// ---------------------------------------------------------------------------
 // VERSION — set to the SDK's published version so assertEngineVersion (which
 // only logs, never throws) emits no spurious mismatch warning.
-// ---------------------------------------------------------------------------
 export const VERSION = '0.78.1';
-// ---------------------------------------------------------------------------
 // Parse the broker-launch.json recipe the host serialized (the PiInvocation
 // buildPiArgv produced) for the proof shape — the same `-e`/`-n`/positional
 // vocabulary fake-pi-host parses off its argv.
-// ---------------------------------------------------------------------------
 function readLaunch(dir) {
     let argv = [];
     try {

package/dist/core/__tests__/fixtures/fake-pi-host.js

@@ -61,7 +61,7 @@ if (home === '')
     fail('CRTR_HOME missing in env');
 const nodeDir = join(home, 'nodes', nodeId);
 mkdirSync(nodeDir, { recursive: true });
-// --- parse the argv the runtime built (buildPiArgv → piCommand) ------------
+// parse the argv the runtime built (buildPiArgv → piCommand)
 const extPaths = [];
 let sessionArg;
 let label;
@@ -167,7 +167,7 @@ const ctx = {
         /* spike: no-op */
     },
 };
-// --- load the REAL extension modules from the -e paths ----------------------
+// load the REAL extension modules from the -e paths
 const loaded = [];
 const failedExt = [];
 for (const p of extPaths) {
@@ -187,9 +187,9 @@ for (const p of extPaths) {
         recordError(`import ${p} failed: ${String(e)}`);
     }
 }
-// --- session_start: the real boot-confirm hook captures session id + pid -----
+// session_start: the real boot-confirm hook captures session id + pid
 await fire('session_start', { reason: resuming ? 'resume' : 'startup' }, ctx);
-// --- the boot proof the harness asserts on ----------------------------------
+// the boot proof the harness asserts on
 const boot = {
     pid: process.pid,
     nodeId,
@@ -226,7 +226,7 @@ try {
 catch {
     /* best effort */
 }
-// --- control loop: poll for one harness command at a time -------------------
+// control loop: poll for one harness command at a time
 const cmdFile = join(nodeDir, 'fake-pi.cmd');
 const ackFile = join(nodeDir, 'fake-pi.ack');
 function ack(id, body) {

package/dist/core/__tests__/focuses.test.js

@@ -38,17 +38,13 @@ after(() => {
     rmSync(home, { recursive: true, force: true });
     delete process.env['CRTR_HOME'];
 });
-// ---------------------------------------------------------------------------
 // Migration v6 — the additive `focuses` table.
-// ---------------------------------------------------------------------------
 test('a fresh db migrates to the latest version and has the focuses table', () => {
     const db = openDb();
     assert.equal(userVersion(db), MIGRATIONS.length);
     assert.ok(tableNames(db).includes('focuses'), 'focuses table exists on a fresh db');
 });
-// ---------------------------------------------------------------------------
 // Canvas setters / reads — open / setOccupant / setPane / close round-trip.
-// ---------------------------------------------------------------------------
 test('open / setOccupant / close round-trip with the reads', () => {
     openDb();
     openFocusRow('f1', '%a', 'Sa', 'A');
@@ -85,7 +81,6 @@ test('independent focus rows do not contend', () => {
     assert.deepEqual(getFocusByNode('B'), { focus_id: 'f2', pane: '%b', session: 'Sb', node_id: 'B' });
     assert.deepEqual(listFocuses().map((f) => f.focus_id), ['f2']);
 });
-// ---------------------------------------------------------------------------
 // Placement reads — focusOf / isFocused / focusByPane / focusedNodes /
 // listFocuses GC dead-pane viewer rows on read (broker-host cut: liveOrPrune).
 // A row whose viewer pane no longer exists is pruned the next time it is read,
@@ -93,7 +88,6 @@ test('independent focus rows do not contend', () => {
 // registered-but-not-yet-realized viewer) is passed through. A live tmux pane
 // can't be fabricated in the ordinary suite, so we cover the prune + null-pane paths
 // here; the live-pane read is covered in the compiled-seam broker lifecycle suite.
-// ---------------------------------------------------------------------------
 test('placement reads GC dead-pane viewer rows and keep null-pane rows', () => {
     openDb();
     openFocusRow('f1', '%a', 'Sa', 'A'); // %a is not a live tmux pane → pruned on read

package/dist/core/__tests__/fs-utils.test.d.ts

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

package/dist/core/__tests__/fs-utils.test.js

@@ -0,0 +1,50 @@
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { atomicWriteJson, atomicWriteText, readJson } from '../fs-utils.js';
+let dir;
+before(() => {
+    dir = mkdtempSync(join(tmpdir(), 'crtr-fs-utils-'));
+});
+after(() => {
+    rmSync(dir, { recursive: true, force: true });
+});
+test('atomicWriteText defaults a new file to 0o600', () => {
+    const path = join(dir, 'new-file.txt');
+    atomicWriteText(path, 'hello');
+    const mode = statSync(path).mode & 0o777;
+    assert.equal(mode, 0o600);
+});
+test('atomicWriteText preserves an existing file\'s mode on rewrite', () => {
+    const path = join(dir, 'existing-file.txt');
+    writeFileSync(path, 'first', { mode: 0o640 });
+    atomicWriteText(path, 'second');
+    const mode = statSync(path).mode & 0o777;
+    assert.equal(mode, 0o640);
+});
+test('atomicWriteText opts.mode forces a mode regardless of the existing file', () => {
+    const path = join(dir, 'forced-mode.txt');
+    writeFileSync(path, 'first', { mode: 0o640 });
+    atomicWriteText(path, 'second', { mode: 0o600 });
+    const mode = statSync(path).mode & 0o777;
+    assert.equal(mode, 0o600);
+});
+test('atomicWriteJson round-trips data and leaves no temp file after success', () => {
+    const path = join(dir, 'data.json');
+    atomicWriteJson(path, { hello: 'world' });
+    assert.deepEqual(readJson(path), { hello: 'world' });
+    const leftovers = readdirSync(dir).filter((name) => name.includes('.tmp'));
+    assert.deepEqual(leftovers, []);
+});
+test('atomicWriteText leaves no temp file behind after a forced rename failure', () => {
+    // Target an existing directory as the write path so ensureDir succeeds, the
+    // temp file is actually created, and only the rename step fails (EISDIR),
+    // exercising the finally-block cleanup path.
+    const path = join(dir, 'a-directory');
+    mkdirSync(path);
+    assert.throws(() => atomicWriteText(path, 'nope'));
+    const leftovers = readdirSync(dir).filter((name) => name.includes('.tmp'));
+    assert.deepEqual(leftovers, []);
+});

package/dist/core/__tests__/helpers/harness.js

@@ -36,7 +36,7 @@ import { bindDaemonEventSource, resetEventSourceForTests } from '../../events/so
 import { bindFleet, resetFleetForTests } from '../../runtime/fleet.js';
 import { readInboxSince } from '../../feed/inbox.js';
 import { capturePidCommand, recordedPidLiveness } from '../../canvas/pid.js';
-// --- locations --------------------------------------------------------------
+// locations
 const HERE = dirname(fileURLToPath(import.meta.url));
 const TREE_ROOT = join(HERE, '..', '..', '..'); // src/ or dist/
 const CROUTER = join(TREE_ROOT, '..'); // package root

package/dist/core/__tests__/inline-memory-refs.test.js

@@ -15,14 +15,12 @@ import { clearSessionCache } from '../substrate/session-cache.js';
 import { memoryDir as nodeMemoryDir } from '../runtime/memory.js';
 import { buildRefInventory } from '../memory/inline-ref-inventory.js';
 import { gatewayMemoryRows } from '../runtime/chat-inventory-rows.js';
-// ---------------------------------------------------------------------------
 // Wave C4 — buildRefInventory: the authoritative corpus builder. Fixture-
 // backed (node/project/user scope docs on disk), since precedence dedup,
 // referenceability-ignores-gate/slash, and directory browse names are all corpus-shape
 // facts that a pure in-memory test can't exercise. Fixture names are prefixed
 // to avoid any collision with the real shipped builtin/user corpus that
 // listAllMemoryDocs() also picks up in this environment.
-// ---------------------------------------------------------------------------
 describe('buildRefInventory (fixture-backed corpus)', () => {
     const NODE_ID = 'crtr-inline-ref-fixture-node';
     const PROJECT_NAMESPACE = 'crtr-inline-ref-fixture-project';

package/dist/core/__tests__/integration/broker-fork-seam.test.js

@@ -118,11 +118,9 @@ test('D2 broker fork branch: buildBrokerSession(cfg.forkFrom) yields a NEW id +
         session.dispose();
     }
 });
-// ---------------------------------------------------------------------------
 // resolveForkSource — a reference that resolves to no forkable session file
 // must fail loudly BEFORE launch, rather than hand the broker a source it
 // cannot fork.
-// ---------------------------------------------------------------------------
 function nodeRow(id, over = {}) {
     return {
         node_id: id,

package/dist/core/__tests__/integration/broker-sdk-wiring.test.js

@@ -27,9 +27,10 @@ import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createAgentSessionServices, createAgentSessionFromServices, SessionManager, VERSION, } from '../../runtime/broker-sdk.js';
 import { buildBrokerSession, makeBrokerUiContext, snapshotMessages } from '../../runtime/broker.js';
-import { isLeadingEngineCommand, resolveSteerCall, chooseGuidanceDeliveryMode, promptWithNextTurnGuidance, promptWithAdvertisedCommandInvocation, isHiddenJsonlBranchEntry, stripHiddenEntriesFromJsonlExport, engineLeadingCommandTokens, } from '../../runtime/broker/frame-dispatch.js';
+import { isLeadingEngineCommand, resolveSteerCall, chooseGuidanceDeliveryMode, promptWithNextTurnGuidance, engineLeadingCommandTokens, } from '../../runtime/broker/engine-routing.js';
+import { isHiddenJsonlBranchEntry, stripHiddenEntriesFromJsonlExport, } from '../../runtime/broker/frame-session.js';
 import { CANVAS_EXTENSIONS } from '../../runtime/launch.js';
-import { prepareAdvertisedCommandPersistence } from '../../runtime/advertised-command-invocation.js';
+import { prepareAdvertisedCommandPersistence, promptWithAdvertisedCommandInvocation, } from '../../runtime/advertised-command-invocation.js';
 // The REAL engine, assembled from broker-sdk's static SDK re-exports — bypasses
 // the CRTR_BROKER_ENGINE seam entirely so these tests can never accidentally hit
 // the fake (the whole point: prove the wiring the mock hid).
@@ -74,11 +75,9 @@ function brokerExts() {
 function cfg(cwd, extra = {}) {
     return { cwd, extensionPaths: brokerExts(), ...extra };
 }
-// ===========================================================================
 // C3 — the SERVICES path registers an extension's custom model provider, so the
 // broker resolves a model that plain createAgentSession (no registerProvider)
 // would never see.
-// ===========================================================================
 test('C3 — services path registers an extension model provider; the broker session gets it', async () => {
     const cwd = mkdtempSync(join(tmpdir(), 'crtr-c3-'));
     try {
@@ -283,12 +282,10 @@ test('C3h — a cooling managed launch target boots model-less rather than falli
 // `noContextFiles: true` in buildBrokerSession, and buildContextIntro's
 // `<project_context>` block is environment-only. Covered by
 // context-intro.test.ts's environment-only regression.)
-// ===========================================================================
 // C2 — zero-writable dialogs resolve to deny/cancel IMMEDIATELY (noOp), never
 // hanging the turn and never waiting on a per-dialog timeout. Drives the REAL
 // makeBrokerUiContext (the exact ExtensionUIContext the SDK hands extensions),
 // with a writable() snapshot that reports zero writable viewers.
-// ===========================================================================
 test('C2 — zero-writable UI context resolves dialogs to deny/cancel immediately (noOp, no hang)', async () => {
     const ctx = makeBrokerUiContext({
         writable: () => [], // ZERO writable viewers attached
@@ -315,14 +312,12 @@ test('C2 — zero-writable UI context resolves dialogs to deny/cancel immediatel
     assert.equal(await ctx.input('name'), undefined, 'C2: input() cancels (undefined)');
     assert.equal(await ctx.editor('edit'), undefined, 'C2: editor() cancels (undefined)');
 });
-// ===========================================================================
 // M2 (review mq5wkqep / T4) — REPLACES the Wave-0 M-1 cancel-on-detach. A dialog
 // forwarded to a writable viewer that then DETACHES must NOT be cancelled: it
 // stays pending so a brief detach/reattach (or another writable viewer joining)
 // does not lose an answerable dialog. The broker-side default timeout is the ONLY
 // non-answer resolution (proven here with a short per-dialog timeout standing in
 // for the 120s default). Guards against regressing to the over-eager cancel.
-// ===========================================================================
 test('M2 — a forwarded dialog stays pending when its writable viewer detaches, resolving only on the broker-side timeout', async () => {
     const pending = new Map();
     let attached = true;
@@ -355,7 +350,6 @@ test('M2 — a forwarded dialog stays pending when its writable viewer detaches,
     assert.equal(resolved, false, 'M2: resolves to deny on the broker-side timeout, never hangs');
     assert.equal(pending.size, 0, 'M2: the pending registry is drained after the timeout');
 });
-// ===========================================================================
 // C5 — exact leading engine-command suppression and hidden display:false
 // guidance delivery ordering.
 //
@@ -374,7 +368,6 @@ test('M2 — a forwarded dialog stays pending when its writable viewer detaches,
 // verbatim sibling of the compiled-seam-covered `list_models` dispatch whose only
 // non-trivial input, `engineLeadingCommandTokens(session)`, is proven below
 // against a real session.
-// ===========================================================================
 test('a streaming extension command uses prompt preflight instead of the rejecting steer queue', () => {
     const session = { extensionRunner: { getCommand: (name) => (name === 'recap' ? { name: 'recap' } : undefined) } };
     assert.equal(resolveSteerCall('/recap', session), 'prompt');
@@ -555,14 +548,12 @@ test('C5 — fake-engine sendCustomMessage records the call in order without cra
         rmSync(cwd, { recursive: true, force: true });
     }
 });
-// ===========================================================================
 // Review fix (Major 1) — promptWithNextTurnGuidance atomically clears its own
 // pending nextTurn guidance if the prompt it rode alongside never reaches pi's
 // internal drain point (agent-session.js `prompt()` step 8) — an extension-
 // command interception (step 1, `_tryExecuteExtensionCommand`) is a genuine,
 // fully offline SDK early-return that proves the exact leak window the review
 // flagged, without touching model/auth/network.
-// ===========================================================================
 test('Major 1 fix — promptWithNextTurnGuidance clears its own pending guidance when the human prompt is intercepted by an extension command (never reaches pi\'s drain)', async () => {
     const cwd = mkdtempSync(join(tmpdir(), 'crtr-m1-atomic-'));
     try {
@@ -628,13 +619,11 @@ test('Major 1 fix — promptWithNextTurnGuidance leaves the queue drained (not d
         rmSync(cwd, { recursive: true, force: true });
     }
 });
-// ===========================================================================
 // Review fix (Major 2) — JSONL export (`session.exportToJsonl` via the broker
 // `case 'export'` handler) must honor the general `display:false` boundary,
 // not just `crtr-memory-refs` guidance. `stripHiddenEntriesFromJsonlExport`
 // rewrites the exported file in place; covers ACTUAL exported JSONL bytes,
 // not `transcriptMarkdown`.
-// ===========================================================================
 test('Major 2 fix — isHiddenJsonlBranchEntry recognizes both persisted display:false shapes', () => {
     assert.equal(isHiddenJsonlBranchEntry({ type: 'custom_message', display: false }), true, 'a hidden custom_message entry matches');
     assert.equal(isHiddenJsonlBranchEntry({ type: 'custom_message', display: true }), false, 'a visible custom_message entry does not match');
@@ -684,12 +673,10 @@ test('Major 2 fix — exportToJsonl (via the broker export path) strips display:
         rmSync(cwd, { recursive: true, force: true });
     }
 });
-// ===========================================================================
 // Review fix (Major 6, broker/protocol half) — the `list_memory_refs` read-op
 // publishes `engineLeadingCommandNames` as metadata SEPARATE from `refs`
 // (RefMeta rows), exactly matching `isLeadingEngineCommand`'s three sources,
 // so viewers can combine it with their own locally-consumed commands.
-// ===========================================================================
 test('Major 6 (broker half) — engineLeadingCommandTokens degrades to empty per-source without throwing, and never touches refs/RefMeta shape', () => {
     assert.deepEqual(engineLeadingCommandTokens({}), [], 'a bare session with no accessors at all degrades to an empty enumeration');
     const throwingExtButRealTemplate = {

package/dist/core/__tests__/integration/command-plugins.test.js

@@ -45,10 +45,8 @@ import { pluginDisable, pluginEnable, pluginInstall } from '../../../commands/pk
 // import the real SUBTREE_NAMES (build-root.ts pulls the whole tree); a small
 // explicit set is enough for the collision contract and keeps the test cheap.
 const RESERVED = new Set(['push', 'node', 'canvas', 'sys', 'memory']);
-// ---------------------------------------------------------------------------
 // Fixture executable: reads one JSON request on stdin, writes one envelope.
 // Behavior is selected by req.input.mode so one binary drives the whole table.
-// ---------------------------------------------------------------------------
 const FIXTURE_EXEC = `#!/usr/bin/env node
 const fs = require('fs');
 let data = '';
@@ -163,9 +161,7 @@ function installPlugin(scopeRoot, name, opts = {}) {
     }
     return root;
 }
-// ---------------------------------------------------------------------------
 // Isolated home + workspace
-// ---------------------------------------------------------------------------
 let home; // becomes HOME → user scope root = $HOME/.crouter
 let userRoot;
 let projectDir; // a workspace with its own .crouter (project scope)
@@ -219,9 +215,7 @@ function leafOf(branch, name) {
     assert.ok(c !== undefined && c.kind === 'leaf', `expected leaf ${name}`);
     return c;
 }
-// ---------------------------------------------------------------------------
 // 1. Registry composition
-// ---------------------------------------------------------------------------
 describe('registry composition', () => {
     test('a fixture top-level branch composes with plugin-owned help, schema, effects, stable order', () => {
         installPlugin(userRoot, 'deploy-tools');
@@ -258,9 +252,7 @@ describe('registry composition', () => {
         assert.match(leafOut, /None\. Read-only\./);
     });
 });
-// ---------------------------------------------------------------------------
 // 2. Core collision
-// ---------------------------------------------------------------------------
 describe('core collision', () => {
     test('a fixture claiming a core top-level name is skipped + recorded', () => {
         installPlugin(userRoot, 'rogue', { manifest: commandsJson('push') });
@@ -274,9 +266,7 @@ describe('core collision', () => {
         assert.equal(collision.contributor.name, 'rogue');
     });
 });
-// ---------------------------------------------------------------------------
 // 3. Scope / shadowing
-// ---------------------------------------------------------------------------
 describe('scope shadowing', () => {
     test('a project copy shadows a user copy of the same plugin name', () => {
         installPlugin(userRoot, 'deploy-tools');
@@ -298,9 +288,7 @@ describe('scope shadowing', () => {
         assert.equal(effective.length, 0, 'the disabled higher-precedence copy must suppress the user copy');
     });
 });
-// ---------------------------------------------------------------------------
 // 4. Protocol integration (table-driven)
-// ---------------------------------------------------------------------------
 describe('protocol integration', () => {
     function showLeaf() {
         installPlugin(userRoot, 'deploy-tools');
@@ -368,9 +356,7 @@ describe('protocol integration', () => {
         });
     }
 });
-// ---------------------------------------------------------------------------
 // 4b. True end-to-end CLI invocation (argv → parseArgv → adapter → renderer)
-// ---------------------------------------------------------------------------
 describe('end-to-end CLI invocation', () => {
     // dist/cli.js is up 4 from src/core/__tests__/integration/. Requires a prior
     // `npm run build` (the harness/CI builds before tests). Drives the WHOLE seam: the
@@ -398,9 +384,7 @@ describe('end-to-end CLI invocation', () => {
         assert.equal(obj.status, 'running');
     });
 });
-// ---------------------------------------------------------------------------
 // 5. Lifecycle without restart (per-invocation discovery)
-// ---------------------------------------------------------------------------
 describe('lifecycle without restart', () => {
     test('install → appears; disable → gone; edit → visible; remove → gone', () => {
         const discover = () => {
@@ -425,9 +409,7 @@ describe('lifecycle without restart', () => {
         assert.equal(discover().length, 0);
     });
 });
-// ---------------------------------------------------------------------------
 // 6/7. Typed issues without executing the binary
-// ---------------------------------------------------------------------------
 describe('typed validation issues', () => {
     function validate(manifest, extra = {}) {
         installPlugin(userRoot, 'p', { manifest, ...extra });
@@ -513,7 +495,6 @@ describe('typed validation issues', () => {
         assert.equal(v.contributions[0].node.name, 'app');
     });
 });
-// ---------------------------------------------------------------------------
 // Plugin help addenda — the append-only product-guidance seam. An addendum
 // that quietly stops rendering is exactly the silent-absence class: pin that a
 // valid entry survives validation and is collected attributed, and that the
@@ -522,7 +503,6 @@ describe('typed validation issues', () => {
 // plugin's tree. The help-render lookup receives the gate's exact inputs, so a
 // map rejected at ingress renders nothing — render never disagrees with the
 // install report.
-// ---------------------------------------------------------------------------
 describe('plugin help addenda', () => {
     const gate = (paths) => ({
         reservedCoreNames: RESERVED,
@@ -599,11 +579,9 @@ describe('plugin help addenda', () => {
         assert.ok(out.includes('ADDENDUM RENDERED THROUGH THE REAL HELP PATH'), out.slice(-400));
     });
 });
-// ---------------------------------------------------------------------------
 // Lifecycle surfaces — the validator's verdict must reach the caller WITHOUT
 // executing the plugin binary, and a cross-plugin top-level collision must
 // preserve every claimant under its origin-qualified command name.
-// ---------------------------------------------------------------------------
 describe('lifecycle surfaces report validation without executing the plugin', () => {
     // Records the fact it ran. No validation surface may ever spawn it.
     const SENTINEL_EXEC = `#!/usr/bin/env node
@@ -664,14 +642,12 @@ process.stdout.write(JSON.stringify({ protocolVersion: 1, ok: true, result: { ap
         assertNotExecuted();
     });
 });
-// ---------------------------------------------------------------------------
 // Memory-corpus gate across the plugin lifecycle — install, and enable of a
 // package installed while disabled, both converge the candidate's memory store
 // onto exact canonical identity BEFORE it can mount. A local-path install stays
 // a live link, so the caller's own directory is the corpus that gets rewritten;
 // a corpus that cannot converge writes nothing and changes no config. Update
 // runs the same gate through the same helper, so it needs no cases of its own.
-// ---------------------------------------------------------------------------
 describe('memory corpus gate across the plugin lifecycle', () => {
     let realCwd;
     beforeEach(() => {

package/dist/core/__tests__/integration/deferred-no-wake.test.js

@@ -145,9 +145,7 @@ after(() => {
         process.env['CRTR_NODE_ID'] = prevNodeId;
     resetFleetForTests();
 });
-// ---------------------------------------------------------------------------
 // Command layer — the immediate-delivery wake block in node.ts
-// ---------------------------------------------------------------------------
 test('node message send --tier deferred to an ordinary dormant (idle-released) target does not revive it — appended and held for the next natural cycle', { timeout: 30_000 }, async () => {
     const id = 'idleReleaseTarget';
     createNode(node(id, { status: 'idle', intent: 'idle-release' }));
@@ -286,12 +284,10 @@ test('#343 (immediate path): `node message send --tier deferred --reopen` agains
     assert.equal(readInboxSince(id, undefined).length, inboxBefore, 'a rejected reopen+deferred retask must not append an inbox entry');
     assert.equal(getNode(id)?.final_report, firstFinal, 'the canonical final must survive untouched — assertFinalizedForReopen/commitReopen never ran on the rejected path');
 });
-// ---------------------------------------------------------------------------
 // The shared `withFreshTerminalGuard` primitive itself (Major, gh #341/#343
 // review). Every caller that needs a fresh terminal-status check and a
 // dependent write to share one transaction — the immediate deferred path
 // above, and any future arm/schedule doorway — rides this one function.
-// ---------------------------------------------------------------------------
 // #343 review, Major 1: the fresh terminal-status check and a guarded write
 // that depends on it must share ONE transaction, or a concurrent finish/
 // cancel/finalization can land in the gap and silently strand the write. This
@@ -366,9 +362,7 @@ test("withFreshTerminalGuard reports 'missing' — never runs the guarded body
     assert.deepEqual(outcome, { kind: 'missing' }, "the guard reports a distinct 'missing' outcome, not 'terminal' (nothing to report) and not a fabricated 'ran'");
     assert.equal(existsSync(nodeDir(targetId)), false, 'the guarded appendInbox never ran, so no orphan node dir was recreated for the deleted target');
 });
-// ---------------------------------------------------------------------------
 // Daemon second pass — crtrd.ts's idle-release inbox loop
-// ---------------------------------------------------------------------------
 // Deterministic: `headlessBrokerHost.launch` is fully STUBBED (never delegates
 // to the real launcher) so `reviveNode` cannot spawn a real detached broker/pi
 // process as a side effect of this decision test — the stubbed HostHandle's