@north-light/crouter 0.3.231 → 0.3.233

package/dist/daemon/park-pending.js

@@ -0,0 +1,42 @@
+// park-pending.ts — the in-flight parking turns, one map keyed by node id.
+//
+// When the unattended clock expires on a live resident, the daemon does not
+// terminalize it: it asks the still-live engine for one summary turn and hands
+// the terminal decision to broker settlement. This module is the only record
+// that a given node's next settlement means "park", read by exactly two
+// collaborators inside crtrd — the supervision reconciler (which armed it, and
+// which enforces its abort conditions and grace) and the broker-settle handler
+// (which consumes it).
+//
+// The pending park is PROCESS-LOCAL on purpose. The park clock and the pending
+// park are the same authority and must die together: if crtrd is replaced
+// mid-turn, the successor has no clock reading and no pending park, the node
+// simply stays live, and its 15-minute clock restarts. Nothing is inconsistent
+// and nothing needs repair. A durable in-flight flag would instead need its own
+// reconciliation on every daemon start to avoid stranding a node that never got
+// its prompt.
+/** node id → the timestamp its parking turn was requested at. */
+const pending = new Map();
+/** Arm a pending park for `nodeId`. The caller delivers the parking prompt. */
+export function beginPendingPark(nodeId, now) {
+    pending.set(nodeId, now);
+}
+export function isPendingPark(nodeId) {
+    return pending.has(nodeId);
+}
+/** When the pending park was armed, or undefined when none is armed. */
+export function pendingParkStartedAt(nodeId) {
+    return pending.get(nodeId);
+}
+/** Delete-and-report: true only for the caller that actually took the pending
+ *  park. Both the supervision tick and the settle handler run on the daemon
+ *  thread with no await between their check and this call, so exactly one of
+ *  them ever enacts a given park. */
+export function consumePendingPark(nodeId) {
+    return pending.delete(nodeId);
+}
+/** Every node with a parking turn in flight — the reconciler's sweep drops the
+ *  ones whose broker has left the fleet. */
+export function pendingParkIds() {
+    return Array.from(pending.keys());
+}

package/dist/daemon/reconcilers/broker-supervision.d.ts

@@ -16,6 +16,7 @@ export declare const YIELD_STALL_GRACE_MS: number;
 export declare const WEDGE_QUIET_MS: number;
 export declare const WEDGE_CPU_MAX_PERCENT = 2;
 export declare function unattendedParkMsForDaemon(): number;
+export declare function parkSummaryGraceMsForDaemon(): number;
 export type WedgeVerdict = 'leave' | 'pending' | 'wedged';
 export declare function yieldStallVerdict(piPidAlive: boolean | null, intent: NodeRow['intent'], busy: boolean, stalledFor: number | null): 'leave' | 'pending' | 'kill';
 export declare function wedgeVerdict(input: {
@@ -38,7 +39,19 @@ export declare class BrokerSupervisionReconciler {
         warning: number;
         automaticReviveCap: number;
     }>;
+    /** Every condition that resets the unattended clock EXCEPT `isBusy` — the
+     *  node is unavailable to park, attended, or has work waiting. Short-circuits
+     *  in cost order so the common tick does no file reads it can avoid.
+     *  Evaluated for a pending park too, where a busy engine is precisely what is
+     *  expected (it is writing the summary) and every other hit aborts. */
+    private parkResetCondition;
     private handleUnattendedParking;
+    /** Deliver the parking prompt over the live broker's serialized frame loop.
+     *  Two outcomes cancel the park immediately: an unreachable broker (nothing
+     *  live to summarize with) falls through to the degraded enactment, and a
+     *  `steer` route means a turn started between the idle gate and the frame, so
+     *  the node is working again and its clock simply restarts. */
+    private requestParkSummary;
     private warnOverCapInTmux;
     private handleYieldStall;
     private readTreeSample;

package/dist/daemon/reconcilers/broker-supervision.js

@@ -21,6 +21,10 @@ import { readCursor, readInboxSince } from '../../core/feed/inbox.js';
 import { activeBackgroundBashJobs } from '../../core/bash-jobs.js';
 import { focusOf } from '../../core/runtime/placement.js';
 import { hasAttachedBrokerViewers } from '../../core/runtime/broker/client-registry.js';
+import { deliverLive } from '../../core/runtime/interactive-deliver.js';
+import { BrokerUnreachableError } from '../../core/runtime/broker-request.js';
+import { formatCard, PARK_SUMMARY_PROMPT } from '../../shared/generated-context.js';
+import { beginPendingPark, consumePendingPark, pendingParkIds, pendingParkStartedAt } from '../park-pending.js';
 import { applyParkEvent, parkEvent } from './live-obligation.js';
 const execFileAsync = promisify(execFile);
 function configuredPositiveInteger(name, fallback) {
@@ -43,6 +47,9 @@ export const WEDGE_CPU_MAX_PERCENT = 2;
 const OVER_CAP_WARN_THROTTLE_MS = 5 * 60_000;
 const CAPACITY_LOG_THROTTLE_MS = 30_000;
 const DEFAULT_UNATTENDED_PARK_MS = 15 * 60_000;
+// Longer than a summary turn and shorter than the unattended clock itself, so a
+// stuck parking turn cannot hold a broker for a whole extra clock period.
+const DEFAULT_PARK_SUMMARY_GRACE_MS = 5 * 60_000;
 export function unattendedParkMsForDaemon() {
     const raw = process.env['CRTR_TEST_UNATTENDED_PARK_MS'];
     if (raw === undefined)
@@ -50,6 +57,13 @@ export function unattendedParkMsForDaemon() {
     const parsed = Number(raw);
     return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_UNATTENDED_PARK_MS;
 }
+export function parkSummaryGraceMsForDaemon() {
+    const raw = process.env['CRTR_TEST_PARK_SUMMARY_GRACE_MS'];
+    if (raw === undefined)
+        return DEFAULT_PARK_SUMMARY_GRACE_MS;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_PARK_SUMMARY_GRACE_MS;
+}
 export function yieldStallVerdict(piPidAlive, intent, busy, stalledFor) {
     if (piPidAlive !== true)
         return 'leave';
@@ -155,7 +169,7 @@ export class BrokerSupervisionReconciler {
                     this.handleYieldStall(row, entry.pid, now);
                     await this.handleWedgeDetection(id, entry.pid, row.pi_pid_identity, now);
                     this.handleFatalFault(id);
-                    this.handleUnattendedParking(id, getNode(id), entry.pid, now);
+                    this.handleUnattendedParking(id, getNode(id), entry.pid, now, ctx);
                 }
                 catch (err) {
                     this.unattendedSince.delete(id);
@@ -172,39 +186,90 @@ export class BrokerSupervisionReconciler {
             if (!ctx.fleet.has(id))
                 this.unattendedSince.delete(id);
         }
+        // A broker that died mid-summary leaves no pending park behind: its parking
+        // turn can never settle, and the node's next clock starts from scratch.
+        for (const id of pendingParkIds()) {
+            if (!ctx.fleet.has(id))
+                consumePendingPark(id);
+        }
         return thresholds;
     }
-    handleUnattendedParking(id, row, livePid, now) {
-        // An unclaimed warm-pool spare is not a conversation: the booted broker it
-        // holds IS its whole value, and nobody is meant to be attending it. Its
-        // lifetime belongs to `reapStaleSpares` (warm-pool.ts) and its own TTL, so
-        // parking one here would empty the pool every 15 minutes.
-        if (isWarmSpare(id)) {
-            this.unattendedSince.delete(id);
-            return;
-        }
-        if (row === null
-            || row.pi_session_id == null
+    /** Every condition that resets the unattended clock EXCEPT `isBusy` — the
+     *  node is unavailable to park, attended, or has work waiting. Short-circuits
+     *  in cost order so the common tick does no file reads it can avoid.
+     *  Evaluated for a pending park too, where a busy engine is precisely what is
+     *  expected (it is writing the summary) and every other hit aborts. */
+    parkResetCondition(id, row, livePid, now) {
+        if (row.pi_session_id == null
             || row.pi_pid !== livePid
             || row.status === 'done'
             || row.status === 'canceled'
             || row.status === 'dead'
             || row.intent !== null
-            || isBusy(id)
             || activeBackgroundBashJobs(contextDir(id)).length > 0
             || focusOf(id) !== null
-            || hasAttachedBrokerViewers(id)) {
-            this.unattendedSince.delete(id);
-            return;
-        }
+            || hasAttachedBrokerViewers(id))
+            return true;
         const fault = readFault(id);
         const activeAutoProviderRetry = fault !== null
             && fault.retry.disposition === 'auto'
             && fault.retry.by === 'daemon'
             && (fault.kind === 'connection' || fault.kind === 'rate-limit' || fault.kind === 'overloaded')
             && (fault.retry.nextAt !== undefined || nextFaultRetry(fault, now) !== null);
-        if (activeAutoProviderRetry
-            || readInboxSince(id, readCursor(id)).some((entry) => entry.tier !== 'deferred')) {
+        if (activeAutoProviderRetry)
+            return true;
+        return readInboxSince(id, readCursor(id)).some((entry) => entry.tier !== 'deferred');
+    }
+    handleUnattendedParking(id, row, livePid, now, ctx) {
+        // An unclaimed warm-pool spare is not a conversation: the booted broker it
+        // holds IS its whole value, and nobody is meant to be attending it. Its
+        // lifetime belongs to `reapStaleSpares` (warm-pool.ts) and its own TTL, so
+        // parking one here would empty the pool every 15 minutes.
+        if (isWarmSpare(id)) {
+            this.unattendedSince.delete(id);
+            consumePendingPark(id);
+            return;
+        }
+        if (row === null) {
+            this.unattendedSince.delete(id);
+            consumePendingPark(id);
+            return;
+        }
+        const reset = this.parkResetCondition(id, row, livePid, now);
+        // A parking turn is in flight for this node: it owns the decision until it
+        // settles, aborts, or runs out of grace.
+        const parkingSince = pendingParkStartedAt(id);
+        if (parkingSince !== undefined) {
+            if (reset) {
+                // Something worth attending to arrived (or the node became unavailable)
+                // during the summary turn. The node stays live and the park consequence
+                // is discarded; its clock restarts from scratch.
+                consumePendingPark(id);
+                this.unattendedSince.delete(id);
+                return;
+            }
+            if (now - parkingSince < parkSummaryGraceMsForDaemon())
+                return;
+            // The degraded path: park anyway, with the marker but no report, exactly
+            // as this clock behaved before the summary turn existed. Status flips
+            // BEFORE the host dies (the crash-safety invariant).
+            if (!consumePendingPark(id))
+                return;
+            this.unattendedSince.delete(id);
+            emitEvent({
+                level: 'warn',
+                event: 'broker.park.summary_expired',
+                ...(isSafeNodeId(id) ? { node_id: id } : {}),
+                fields: {
+                    ...(isSafeNodeId(id) ? {} : { affected_node_id: id }),
+                    grace_ms: parkSummaryGraceMsForDaemon(),
+                },
+            });
+            applyParkEvent(id, 'park');
+            headlessBrokerHost.teardown(id);
+            return;
+        }
+        if (reset || isBusy(id)) {
             this.unattendedSince.delete(id);
             return;
         }
@@ -216,8 +281,61 @@ export class BrokerSupervisionReconciler {
         if (now - since < unattendedParkMsForDaemon())
             return;
         this.unattendedSince.delete(id);
-        applyParkEvent(id, parkEvent(id, row.lifecycle));
-        headlessBrokerHost.teardown(id);
+        const event = parkEvent(id, row.lifecycle);
+        if (event === 'release') {
+            // A pause, not a terminal write: something can still wake this node, so
+            // its row stays wakeable while the idle broker is released. Skipping the
+            // teardown here would hold the broker process for as long as the
+            // obligation lasts — the exact leak this clock exists to close.
+            applyParkEvent(id, event);
+            headlessBrokerHost.teardown(id);
+            return;
+        }
+        if (event === 'cancel') {
+            applyParkEvent(id, event);
+            headlessBrokerHost.teardown(id);
+            return;
+        }
+        // A resident ends its conversation the way a worker ends a task: it gets one
+        // last turn to leave a roadmap and a report behind. Terminalization moves to
+        // broker settlement, which re-evaluates this verdict once that turn ends.
+        if (!ctx.lifecycle.acceptsDetachedWork())
+            return;
+        beginPendingPark(id, now);
+        ctx.lifecycle.registerDetached(this.requestParkSummary(id));
+    }
+    /** Deliver the parking prompt over the live broker's serialized frame loop.
+     *  Two outcomes cancel the park immediately: an unreachable broker (nothing
+     *  live to summarize with) falls through to the degraded enactment, and a
+     *  `steer` route means a turn started between the idle gate and the frame, so
+     *  the node is working again and its clock simply restarts. */
+    async requestParkSummary(id) {
+        try {
+            const route = await deliverLive(id, formatCard('park', {}, PARK_SUMMARY_PROMPT));
+            if (route === 'steer' && consumePendingPark(id))
+                return;
+            emitEvent({
+                level: 'info',
+                event: 'broker.park.summary_requested',
+                ...(isSafeNodeId(id) ? { node_id: id } : {}),
+                fields: { ...(isSafeNodeId(id) ? {} : { affected_node_id: id }), route },
+            });
+        }
+        catch (err) {
+            if (!consumePendingPark(id))
+                return;
+            if (err instanceof BrokerUnreachableError) {
+                applyParkEvent(id, 'park');
+                headlessBrokerHost.teardown(id);
+                return;
+            }
+            emitEvent({
+                level: 'error',
+                event: 'broker.park.summary_failed',
+                ...(isSafeNodeId(id) ? { node_id: id } : { fields: { affected_node_id: id } }),
+                error: err,
+            });
+        }
     }
     async warnOverCapInTmux(count, warning, max) {
         const now = Date.now();

package/dist/daemon/reconcilers/live-obligation.d.ts

@@ -16,8 +16,10 @@ export declare function hasPendingWake(nodeId: string): boolean;
  *  reconciliation (dormant-inbox) apply.
  *
  *  `release` — something can still wake it, so parking is a pause.
- *  `finish`  — a resident with nothing left to wake it has completed its
- *              conversation, and the row becomes prunable history.
+ *  `park`    — a resident with nothing left to wake it has completed its
+ *              conversation, and the row becomes prunable history. The live
+ *              clock asks it for a summary turn first; this verdict is what
+ *              that turn's settlement re-evaluates before enacting.
  *  `cancel`  — a terminal node that never pushed a final was torn down before
  *              finishing, which is what `canceled` records; it stays revivable
  *              and becomes prunable. A live subscriber still awaiting its
@@ -29,7 +31,11 @@ export declare function hasPendingWake(nodeId: string): boolean;
  *  terminalized row no longer takes that cycle, so writing one off would drop
  *  content the sender already handed over.
  */
-export type ParkEvent = Extract<LifecycleEvent, 'release' | 'finish' | 'cancel'>;
+export type ParkEvent = Extract<LifecycleEvent, 'release' | 'park' | 'cancel'>;
 export declare function parkEvent(nodeId: string, lifecycle: Lifecycle): ParkEvent;
-/** Apply an unattended decision and notify subscribers of automatic completion. */
+/** Apply an unattended decision and notify subscribers of automatic completion.
+ *  This is the DEGRADED enactment: no summary turn ran, so subscribers get the
+ *  doctrine wake instead of the node's own report. The live clock's good path
+ *  (broker settlement after a parking turn) enacts `park` directly and fans
+ *  nothing — the node's report is the notice. */
 export declare function applyParkEvent(nodeId: string, event: ParkEvent): void;

package/dist/daemon/reconcilers/live-obligation.js

@@ -36,13 +36,17 @@ export function parkEvent(nodeId, lifecycle) {
     if (readInboxSince(nodeId, readCursor(nodeId)).length > 0)
         return 'release';
     if (lifecycle === 'resident')
-        return 'finish';
+        return 'park';
     return hasLiveSubscriber(nodeId) ? 'release' : 'cancel';
 }
-/** Apply an unattended decision and notify subscribers of automatic completion. */
+/** Apply an unattended decision and notify subscribers of automatic completion.
+ *  This is the DEGRADED enactment: no summary turn ran, so subscribers get the
+ *  doctrine wake instead of the node's own report. The live clock's good path
+ *  (broker settlement after a parking turn) enacts `park` directly and fans
+ *  nothing — the node's report is the notice. */
 export function applyParkEvent(nodeId, event) {
     const node = transition(nodeId, event);
-    if (event !== 'finish')
+    if (event !== 'park')
         return;
     fanDoctrineWake(nodeId, subscribersOf(nodeId), `Child done — ${fullName(node)} (${nodeId}) was automatically marked done after its unattended grace with nothing left to wake it. It sent no final report.`, { reason: 'child-auto-done', child: nodeId });
 }

package/dist/daemon/reconcilers/storage-maintenance.d.ts

@@ -2,7 +2,6 @@ export declare const DEAD_REAP_GRACE_MS: number;
 /** Recurring storage cleanup. The in-memory throttle clocks intentionally reset
  * on daemon boot, so the first tick runs both full sweeps. */
 export declare class StorageMaintenanceReconciler {
-    private lastPruneAt;
     private lastSpareSweepAt;
     private lastGhostSweepAt;
     run(now: number): void;
@@ -19,9 +18,6 @@ export declare class StorageMaintenanceReconciler {
     /** Delete focus rows whose recorded tmux pane no longer exists. A failed tmux
      * probe is "can't tell" and never authorizes deleting every viewport. */
     private gcStaleFocuses;
-    /** Count-based full-canvas prune, throttled to once per hour. Live rows are
-     * never deleted by pruneToLimit, so the true floor can exceed AUTO_PRUNE_MAX. */
-    private autoPrune;
     /** Collect dead or expired hidden warm-pool spares. */
     private gcWarmPool;
 }

package/dist/daemon/reconcilers/storage-maintenance.js

@@ -1,6 +1,6 @@
 import { statSync } from 'node:fs';
 import { join } from 'node:path';
-import { closeFocusRow, listFocuses, listNodes, pruneToLimit, reapGhostRows, } from '../../core/canvas/index.js';
+import { closeFocusRow, listFocuses, listNodes, reapGhostRows, } from '../../core/canvas/index.js';
 import { isSafeNodeId, jobDir, nodeDir } from '../../core/canvas/paths.js';
 import { emitEvent } from '../../core/events/emit.js';
 import { operationIdContext } from '../../core/events/operation-id.js';
@@ -9,14 +9,11 @@ import { reapStaleSpares } from '../../core/runtime/warm-pool.js';
 // How long a dead node's on-disk record must be quiet before its leftover
 // placement is reaped. A fresh crash keeps its pane for inspection.
 export const DEAD_REAP_GRACE_MS = 10 * 60_000;
-const AUTO_PRUNE_MAX = 2000;
-const PRUNE_INTERVAL_MS = 60 * 60 * 1000;
 const SPARE_SWEEP_INTERVAL_MS = 60 * 1000;
 const GHOST_SWEEP_INTERVAL_MS = 60 * 1000;
 /** Recurring storage cleanup. The in-memory throttle clocks intentionally reset
  * on daemon boot, so the first tick runs both full sweeps. */
 export class StorageMaintenanceReconciler {
-    lastPruneAt = Number.NEGATIVE_INFINITY;
     lastSpareSweepAt = Number.NEGATIVE_INFINITY;
     lastGhostSweepAt = Number.NEGATIVE_INFINITY;
     run(now) {
@@ -26,7 +23,6 @@ export class StorageMaintenanceReconciler {
         this.reapDeadResidue(now);
         this.gcStaleFocuses();
         this.reapGhostRows(now);
-        this.autoPrune(now);
         this.gcWarmPool(now);
     }
     /** Drop rows whose on-disk node dir is gone. Such a row can never be revived,
@@ -192,34 +188,6 @@ export class StorageMaintenanceReconciler {
                 return;
         }
     }
-    /** Count-based full-canvas prune, throttled to once per hour. Live rows are
-     * never deleted by pruneToLimit, so the true floor can exceed AUTO_PRUNE_MAX. */
-    autoPrune(now) {
-        if (now - this.lastPruneAt < PRUNE_INTERVAL_MS)
-            return;
-        this.lastPruneAt = now;
-        operationIdContext.fresh(() => {
-            try {
-                const before = listNodes().length;
-                const { pruned } = pruneToLimit({ maxNodes: AUTO_PRUNE_MAX });
-                if (pruned.length > 0) {
-                    emitEvent({
-                        level: 'info',
-                        event: 'canvas.auto_prune.completed',
-                        outcome: 'succeeded',
-                        fields: {
-                            before_count: before,
-                            kept_count: before - pruned.length,
-                            pruned_count: pruned.length,
-                        },
-                    });
-                }
-            }
-            catch (err) {
-                emitEvent({ level: 'error', event: 'canvas.auto_prune.failed', error: err });
-            }
-        });
-    }
     /** Collect dead or expired hidden warm-pool spares. */
     gcWarmPool(now) {
         if (now - this.lastSpareSweepAt < SPARE_SWEEP_INTERVAL_MS)

package/dist/pi-extensions/__tests__/pre-command-gate.test.d.ts

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

package/dist/pi-extensions/__tests__/pre-command-gate.test.js

@@ -0,0 +1,220 @@
+// Regression: the `pre-command` gate holds a bash command BEFORE it runs and
+// releases it once its memory is in the transcript. The release is not a stored
+// decision — it is the exposure ledger, and that is exactly what makes it
+// fragile:
+//
+//   • Compaction drops the delivered guidance out of the transcript while the
+//     ledger still claims it was delivered. Without the demotion pass the doc is
+//     held once and then silently absent for the rest of the session. Worse, a
+//     demotion that left a rankless entry behind would crash the node's whole
+//     substrate on its next load — so the ledger is reloaded FROM DISK here.
+//   • pi preflights the siblings of one assistant message sequentially and then
+//     executes them concurrently, so without a per-turn flag the second sibling
+//     would find the doc already exposed and slip past the hold its sibling just
+//     raised.
+//   • A session whose corpus carries no `pre-command` doc at all is the common
+//     case and must never pay a daemon round-trip. Proven by closing the daemon:
+//     if the short-circuit stopped working the call would fail loud.
+//
+// The gate runs against the real canvas api server, so the subject the matcher
+// gates on is the one crtrd actually serves.
+//
+// Run: node --conditions=crtr-src --import tsx/esm --test src/pi-extensions/__tests__/pre-command-gate.test.ts
+import { test, before, beforeEach, afterEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { registerCanvasDocSubstrate } from '../canvas-doc-substrate.js';
+import { createNode } from '../../core/canvas/canvas.js';
+import { closeDb } from '../../core/canvas/db.js';
+import { apiSocketPath } from '../../core/canvas/paths.js';
+import { resetScopeCache } from '../../core/scope.js';
+import { loadContextExposureState } from '../../core/substrate/injected-store.js';
+import { clearSessionCache } from '../../core/substrate/session-cache.js';
+import { createApiServer } from '../../daemon/api/server.js';
+const DOCTRINE_BODY = 'PRE-COMMAND-DOCTRINE-BODY';
+let home;
+let cwd;
+let server = null;
+let origCwd;
+let origHome;
+let origNode;
+let origProfile;
+async function waitForSocket(path) {
+    for (let i = 0; i < 200; i++) {
+        if (existsSync(path))
+            return;
+        await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+    throw new Error(`api socket never bound at ${path}`);
+}
+async function closeServer() {
+    const running = server;
+    server = null;
+    if (running !== null)
+        await running.close();
+}
+/** A user-scope doc that holds every `deploy …` invocation until it is read. */
+function writeDoctrineDoc(event) {
+    const store = join(home, 'user', '.crouter', 'memory');
+    mkdirSync(store, { recursive: true });
+    const path = join(store, 'deploy-doctrine.md');
+    writeFileSync(path, '---\nkind: knowledge\n' +
+        'when-and-why-to-read: When deploying, this knowledge should be read because it carries the approval boundary.\n' +
+        `surfaces:\n  - {on: ${event}, at: content, match: "deploy*"}\n---\n` +
+        `${DOCTRINE_BODY}\n`);
+    clearSessionCache();
+    return realpathSync(path);
+}
+/** A canvas node the api server can assemble a subject for, selected as the
+ *  session's node. Each test uses its own id: the extension's exposure state is
+ *  a per-node process singleton. */
+function seedNode(id) {
+    createNode({
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd,
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+    });
+    mkdirSync(join(home, 'nodes', id), { recursive: true });
+    process.env['CRTR_NODE_ID'] = id;
+}
+/** The registered extension, driven through the pi events it actually binds. */
+function registerSubstrate() {
+    const handlers = new Map();
+    registerCanvasDocSubstrate({
+        on(event, handler) {
+            const bound = handlers.get(event) ?? [];
+            bound.push(handler);
+            handlers.set(event, bound);
+        },
+    });
+    async function fire(event, payload) {
+        const bound = handlers.get(event) ?? [];
+        assert.equal(bound.length, 1, `the substrate binds exactly one ${event} handler`);
+        return await bound[0](payload, {});
+    }
+    return {
+        toolCall: (toolName, input) => fire('tool_call', { toolName, input }),
+        bash: (command) => fire('tool_call', { toolName: 'bash', input: { command } }),
+        endTurn: async () => void (await fire('turn_end', {})),
+        compact: async () => void (await fire('session_compact', {})),
+    };
+}
+function assertHeld(result, what) {
+    assert.ok(result !== undefined, `${what} is held`);
+    assert.equal(result.block, true);
+    assert.ok(result.reason.startsWith('HELD — nothing ran.'), `the held result opens with the notice; got: ${result.reason}`);
+    return result;
+}
+before(() => {
+    origCwd = process.cwd();
+    origHome = process.env['HOME'];
+    origNode = process.env['CRTR_NODE_ID'];
+    origProfile = process.env['CRTR_PROFILE_ID'];
+});
+beforeEach(async () => {
+    closeDb();
+    if (home)
+        rmSync(home, { recursive: true, force: true });
+    home = mkdtempSync(join(tmpdir(), 'crtr-pre-command-'));
+    cwd = join(home, 'user', 'work');
+    mkdirSync(cwd, { recursive: true });
+    process.chdir(cwd);
+    process.env['HOME'] = join(home, 'user');
+    process.env['CRTR_HOME'] = home;
+    delete process.env['CRTR_NODE_ID'];
+    delete process.env['CRTR_PROFILE_ID'];
+    resetScopeCache();
+    clearSessionCache();
+    server = createApiServer();
+    await waitForSocket(apiSocketPath());
+});
+afterEach(async () => {
+    try {
+        await closeServer();
+    }
+    finally {
+        process.chdir(origCwd);
+    }
+});
+after(() => {
+    process.chdir(origCwd);
+    closeDb();
+    if (home)
+        rmSync(home, { recursive: true, force: true });
+    resetScopeCache();
+    clearSessionCache();
+    delete process.env['CRTR_HOME'];
+    if (origHome === undefined)
+        delete process.env['HOME'];
+    else
+        process.env['HOME'] = origHome;
+    if (origNode === undefined)
+        delete process.env['CRTR_NODE_ID'];
+    else
+        process.env['CRTR_NODE_ID'] = origNode;
+    if (origProfile === undefined)
+        delete process.env['CRTR_PROFILE_ID'];
+    else
+        process.env['CRTR_PROFILE_ID'] = origProfile;
+});
+test('a matching command is held with its doc, every sibling in the message with it, and the re-issue runs', async () => {
+    const docPath = writeDoctrineDoc('pre-command');
+    seedNode('gate-hold');
+    const pi = registerSubstrate();
+    const held = assertHeld(await pi.bash('deploy prod'), 'the first matching command');
+    assert.ok(held.reason.includes(DOCTRINE_BODY), `the doc rides back as the blocked call's result; got: ${held.reason}`);
+    assert.match(held.reason, /re-issue your WHOLE command/, 'the copy steers a whole-command re-issue, never one clause');
+    // Exposure is registered AT BLOCK TIME — physical identity and content alias
+    // both — and that single fact is what releases the re-issue below.
+    const afterBlock = loadContextExposureState('gate-hold');
+    assert.deepEqual(afterBlock.exposures.get(docPath), { transcript: 3 }, 'the held doc is recorded as delivered');
+    assert.equal(afterBlock.exposures.size, 2, 'the content alias is recorded alongside the path');
+    // Siblings of the same assistant message. The doc is already exposed, so
+    // without the per-turn flag the render would come back empty and let them
+    // through. The flag covers the whole message, matching or not: every command
+    // in it was authored under the worldview this doc just corrected.
+    const sibling = assertHeld(await pi.bash('deploy staging'), 'a matching sibling');
+    assert.match(sibling.reason, /Another command in this same message/);
+    assertHeld(await pi.bash('ls -la'), 'a non-matching sibling of a held command');
+    await pi.endTurn();
+    // The release: the doc is in the transcript, so there is nothing left to
+    // deliver and nothing left to hold.
+    assert.equal(await pi.bash('deploy prod'), undefined, 'the identical command re-issued in a later turn runs');
+    assert.equal(await pi.bash('ls -la'), undefined, 'a command matching nothing is untouched');
+});
+test('compaction re-arms the hold and leaves an exposure ledger that reloads', async () => {
+    const docPath = writeDoctrineDoc('pre-command');
+    seedNode('gate-compact');
+    const pi = registerSubstrate();
+    assertHeld(await pi.bash('deploy prod'), 'the first matching command');
+    await pi.endTurn();
+    assert.equal(await pi.bash('deploy prod'), undefined, 'the doc is in the transcript, so the command runs');
+    await pi.endTurn();
+    await pi.compact();
+    // Reloaded from disk: the demotion must DELETE the rankless entry rather than
+    // leave `{}` behind, which the v3 loader rejects outright — this call is the
+    // proof it did.
+    const afterCompact = loadContextExposureState('gate-compact');
+    assert.equal(afterCompact.exposures.has(docPath), false, 'compaction forgets the delivery that compaction dropped');
+    assert.equal(afterCompact.exposures.size, 0, 'the content alias is forgotten too, and no rankless entry survives');
+    const reheld = assertHeld(await pi.bash('deploy prod'), 'the same command after compaction');
+    assert.ok(reheld.reason.includes(DOCTRINE_BODY), 'guidance the transcript no longer carries is delivered again');
+});
+test('a corpus with no pre-command doc never reaches the daemon', async () => {
+    writeDoctrineDoc('command');
+    seedNode('gate-quiet');
+    const pi = registerSubstrate();
+    // No daemon. Every path below must return before the subject lookup; one that
+    // does not fails loud with `daemon_unavailable` instead of passing quietly.
+    await closeServer();
+    assert.equal(await pi.toolCall('read', { file: '/tmp/x' }), undefined, 'a non-bash call is not the gate’s business');
+    assert.equal(await pi.toolCall('bash', { command: '   ' }), undefined, 'a bash call carrying no command is not held');
+    assert.equal(await pi.bash('deploy prod'), undefined, 'a post-execution `command` doc never holds anything');
+});