comisai 1.0.45 → 1.0.46

package/node_modules/@comis/daemon/dist/autonomy/bounded-autonomy.d.ts

@@ -1,34 +1,33 @@
 /**
- * `createBoundedAutonomy` — the single bounded-autonomy chokepoint (Phase 213-06,
- * RESEARCH §Pattern-1).
+ * `createBoundedAutonomy` — the single bounded-autonomy chokepoint.
  *
- * ONE typed daemon-wide service that COMPOSES the five mechanism modules built in
- * Plans 04/05 into one place, keyed on `rootRunId`, so every bound decision is
- * reconstructable from a single seam — the seam the Phase-215 audit reads:
- *   - the per-`rootRunId` spawn semaphore (CEIL-01, {@link createRootRunSemaphore}):
+ * ONE typed daemon-wide service that COMPOSES the five mechanism modules
+ * into one place, keyed on `rootRunId`, so every bound decision is
+ * reconstructable from a single seam:
+ *   - the per-`rootRunId` spawn semaphore ({@link createRootRunSemaphore}):
  *     bounds a `for(;;) spawn()` fork-bomb tree-wide on concurrency/depth/fanout,
- *   - the per-`rootRunId` $/token/wall-clock budget meter (BUDGET-01/02/03,
- *     {@link createPerRootBudget}): aborts a self-spawning loop on cost, with token
+ *   - the per-`rootRunId` $/token/wall-clock budget meter
+ *     ({@link createPerRootBudget}): aborts a self-spawning loop on cost, with token
  *     + wall-clock limbs that bite even a zero-price subscription/Codex model,
- *   - the per-key sliding-window call-rate limiter + connection-churn cap (RATE-01,
- *     {@link createCallRateLimiter}): bounds the RATE of cap-socket calls,
- *   - the outward quota (QUOTA-01/02, {@link createOutwardQuota}): the
+ *   - the per-key sliding-window call-rate limiter + connection-churn cap
+ *     ({@link createCallRateLimiter}): bounds the RATE of cap-socket calls,
+ *   - the outward quota ({@link createOutwardQuota}): the
  *     irreversible-action gate for agent-initiated outward sends.
  *
  * Plus two correlation/accessor seams the composite owns:
  *   - `registerRoot(rootRunId, leaseId, parentLeaseId?)` — anchors the budget's
  *     wall-clock deadline at the tree root AND records the rootRunId↔leaseId
  *     correlation (`leaseIdsForRoot`) for the audit/kill fan-out,
- *   - `cronCount(agentId)` — the NAMED RATE-02 cron-cap count source the
+ *   - `cronCount(agentId)` — the NAMED cron-cap count source the
  *     capability endpoint reaches THROUGH this service (it has no cron store of
- *     its own): delegates to the injected `cronJobCount` provider Plan 07 binds to
- *     the per-agent `CronScheduler.getJobs().length`.
+ *     its own): delegates to the injected `cronJobCount` provider the daemon
+ *     wiring binds to the per-agent `CronScheduler.getJobs().length`.
  *
  * Discipline (the daemon arch gates): EVERY numeric cap is sourced from the
  * resolved {@link ResolvedAutonomy} — no hard-coded limits except the structural
  * sliding-window sizes (1000ms call window / 60_000ms churn window) which are
  * documented. The service NEVER throws (it composes Result/discriminated-union
- * returning modules — the chokepoint converts a deny in Plans 07/08); all time is
+ * returning modules — the message-handler chokepoint converts a deny); all time is
  * the injected {@link ClockPort}/{@link TimerPort} (never the wall-clock global —
  * the globals gate). `destroy()` tears down the rate limiter's timers for clean
  * shutdown.
@@ -41,12 +40,12 @@ import type { LeaseManager } from "@comis/infra";
 import type { SpendGateOutcome } from "@comis/agent";
 import type { Result } from "@comis/shared";
 import { type SpawnDenyReason } from "./root-run-semaphore.js";
-import { type PerRootBudget } from "./per-root-budget.js";
+import { createPerRootBudget, type PerRootBudget } from "./per-root-budget.js";
 import { type OutwardQuota, type QuotaError } from "./outward-quota.js";
-/** The composed bounded-autonomy surface — the single chokepoint (Phase 215 reads it). */
+/** The composed bounded-autonomy surface — the single chokepoint every bound decision flows through. */
 export interface BoundedAutonomy {
     /**
-     * Atomically check + reserve one spawn slot for `rootRunId` (CEIL-01). Denies on
+     * Atomically check + reserve one spawn slot for `rootRunId`. Denies on
      * the depth → fanout → concurrency bounds (all from `config.spawn.*`). Delegates
      * to the per-root semaphore; the reserve is synchronous.
      */
@@ -59,7 +58,7 @@ export interface BoundedAutonomy {
     /** Release one spawn slot for `rootRunId` (paired with a prior `tryAcquireSpawn`). */
     releaseSpawn(rootRunId: string): void;
     /**
-     * KEYING-01: re-anchor an IDLE root's wall-clock + token limbs at a turn
+     * Re-anchor an IDLE root's wall-clock + token limbs at a turn
      * boundary (the bridge calls this once per turn). A no-op when `rootRunId` has a
      * LIVE spawn (`activeCount > 0`) so a runaway-tree backstop is never weakened;
      * preserves the $ accumulator + the leaseId index (unlike `releaseSpawn`). Fixes
@@ -68,10 +67,10 @@ export interface BoundedAutonomy {
      */
     evictRootIfIdle(rootRunId: string): void;
     /**
-     * Record one cap-socket call (RATE-01). Composes the per-root AND per-socket
+     * Record one cap-socket call. Composes the per-root AND per-socket
      * sliding-window limits — denies if EITHER trips: the per-root key on
      * `config.rate.perRootCallsPerSec`, the per-socket key on its OWN
-     * `config.rate.perSocketCallsPerSec` (WR-01 — these are two distinct caps with
+     * `config.rate.perSocketCallsPerSec` (these are two distinct caps with
      * two distinct limiters, not one cap applied twice).
      */
     tryCall(rootRunId: string, socketId: string): {
@@ -80,7 +79,7 @@ export interface BoundedAutonomy {
         ok: false;
         reason: "rate";
     };
-    /** Record one cap-socket (re)connection for `rootRunId` (the churn cap, RATE-01). */
+    /** Record one cap-socket (re)connection for `rootRunId` (the churn cap). */
     tryChurn(rootRunId: string): {
         ok: true;
     } | {
@@ -88,11 +87,11 @@ export interface BoundedAutonomy {
         reason: "churn";
     };
     /**
-     * Reserve budget for one LLM/web call against the tree root (BUDGET-01/02/03).
+     * Reserve budget for one LLM/web call against the tree root.
      * Returns a {@link SpendGateOutcome} — `ok`/`free`/`unpriceable`/`exceeded`.
      */
     reserveBudget(rootRunId: string, provider: string, model: string, estUsd: number, estTokens: number): SpendGateOutcome;
-    /** Gate one outward agent send (QUOTA-01/02). Returns `Result<void, QuotaError>`. */
+    /** Gate one outward agent send. Returns `Result<void, QuotaError>`. */
     tryOutward(agentId: string, channelId: string, isOrigin: boolean, volume: number): Result<void, QuotaError>;
     /**
      * Register a tree root: anchor the budget wall-clock deadline AND record the
@@ -104,12 +103,12 @@ export interface BoundedAutonomy {
     leaseIdsForRoot(rootRunId: string): ReadonlySet<string>;
     /**
      * The composite remaining-state snapshot for one run — the read surface the
-     * `capabilities.introspect`/`whoami` RPC reports (INTRO-01). Composes the two
+     * `capabilities.introspect`/`whoami` RPC reports. Composes the two
      * per-module {@link PerRootBudget.remaining} + {@link OutwardQuota.remaining}
      * accessors (delegating to the sub-modules the composite already holds) plus
      * the rootRunId↔leaseId correlation. A PURE read — no gate mutation, no window
-     * advance, no budget reserve (T-215-05): it surfaces the SAME numbers the gates
-     * enforce against (so the read matches the gate, T-215-06).
+     * advance, no budget reserve: it surfaces the SAME numbers the gates
+     * enforce against (so the read always matches the gate).
      */
     snapshot(rootRunId: string, agentId: string, channelId: string): {
         budget: ReturnType<PerRootBudget["remaining"]>;
@@ -117,7 +116,7 @@ export interface BoundedAutonomy {
         leaseIds: ReadonlyArray<string>;
     };
     /**
-     * The agent's live cron-job count (RATE-02) — the NAMED count source the cap
+     * The agent's live cron-job count — the NAMED count source the cap
      * endpoint consults THROUGH this service. Delegates to the injected
      * `cronJobCount` provider; 0 when no provider is wired (fail-open on this limb).
      */
@@ -136,9 +135,9 @@ export interface BoundedAutonomy {
  *   own the full bound surface in one place).
  * @param deps.config - the resolved {@link ResolvedAutonomy} — the SINGLE source
  *   of every numeric cap (spawn/budget/rate/outward + message.maxPerHour).
- * @param deps.cronJobCount - the per-agent cron-job count provider (the RATE-02
- *   count source). Optional — absent ⇒ `cronCount` returns 0 (Plan 07 binds it to
- *   the per-agent `CronScheduler.getJobs().length`).
+ * @param deps.cronJobCount - the per-agent cron-job count provider (the cron-cap
+ *   count source). Optional — absent ⇒ `cronCount` returns 0 (the daemon wiring
+ *   binds it to the per-agent `CronScheduler.getJobs().length`).
  * @param deps.logger - structured logger threaded into the sub-modules.
  */
 export declare function createBoundedAutonomy(deps: {
@@ -148,4 +147,8 @@ export declare function createBoundedAutonomy(deps: {
     config: ResolvedAutonomy;
     cronJobCount?: (agentId: string) => number;
     logger: ComisLogger;
+    /** Pre-trip budget warning hook, threaded verbatim into the per-root meter
+     *  (fired once per (root, limb) at 80% of a limb's cap). Optional — the boot
+     *  wiring emits `autonomy:budget_warning` from it. */
+    onLimbWarning?: Parameters<typeof createPerRootBudget>[0]["onLimbWarning"];
 }): BoundedAutonomy;

package/node_modules/@comis/daemon/dist/autonomy/bounded-autonomy.js

@@ -23,9 +23,9 @@ const RATE_MAX_ENTRIES = 100_000;
  *   own the full bound surface in one place).
  * @param deps.config - the resolved {@link ResolvedAutonomy} — the SINGLE source
  *   of every numeric cap (spawn/budget/rate/outward + message.maxPerHour).
- * @param deps.cronJobCount - the per-agent cron-job count provider (the RATE-02
- *   count source). Optional — absent ⇒ `cronCount` returns 0 (Plan 07 binds it to
- *   the per-agent `CronScheduler.getJobs().length`).
+ * @param deps.cronJobCount - the per-agent cron-job count provider (the cron-cap
+ *   count source). Optional — absent ⇒ `cronCount` returns 0 (the daemon wiring
+ *   binds it to the per-agent `CronScheduler.getJobs().length`).
  * @param deps.logger - structured logger threaded into the sub-modules.
  */
 export function createBoundedAutonomy(deps) {
@@ -38,6 +38,7 @@ export function createBoundedAutonomy(deps) {
         maxChildrenPerAgent: config.spawn.maxChildrenPerAgent,
     });
     const budget = createPerRootBudget({
+        ...(deps.onLimbWarning !== undefined ? { onLimbWarning: deps.onLimbWarning } : {}),
         clock,
         config: {
             aggregateUsd: config.budget.aggregateUsd,
@@ -58,10 +59,10 @@ export function createBoundedAutonomy(deps) {
         maxChurnPerWindow: config.rate.connectionChurnPerMin,
         maxEntries: RATE_MAX_ENTRIES,
     });
-    // WR-01 (213-REVIEW): a SEPARATE limiter for the per-SOCKET dimension. The
+    // A SEPARATE limiter for the per-SOCKET dimension. The
     // shared sliding-window body enforces ONE `maxPerWindow`, so a single limiter
-    // cannot apply two different per-key caps — pre-fix, both the root AND socket
-    // keys rode the per-root cap, making `perSocketCallsPerSec` (default 10) dead
+    // cannot apply two different per-key caps — if both the root AND socket
+    // keys rode the per-root cap, `perSocketCallsPerSec` (default 10) would be dead
     // config. This second limiter's callWindow uses `perSocketCallsPerSec` so the
     // `socket:<id>` key is bounded by its own configured cap. Its churn limb is
     // unused (churn is per-root, gated by `rate.tryChurn`); a positive placeholder
@@ -96,7 +97,7 @@ export function createBoundedAutonomy(deps) {
         },
         releaseSpawn(rootRunId) {
             semaphore.releaseSpawn(rootRunId);
-            // WR-05: when the tree has no live spawns left, evict ALL per-root state in
+            // When the tree has no live spawns left, evict ALL per-root state in
             // one place — the semaphore already dropped its own entry inside
             // releaseSpawn (active→0), so mirror that here for the budget meter's
             // wall-clock/token maps AND the leaseId correlation index, so a storm of
@@ -108,13 +109,13 @@ export function createBoundedAutonomy(deps) {
             }
         },
         evictRootIfIdle(rootRunId) {
-            // KEYING-01: re-anchor an IDLE root's wall-clock + token limbs at a turn
+            // Re-anchor an IDLE root's wall-clock + token limbs at a turn
             // boundary. An interactive SESSION root (`root-session-*`) acquires NO spawn
             // slot, so `releaseSpawn` never fires for it and its wall-clock/token anchors
             // would accumulate across the WHOLE conversation — a session alive >
-            // wallClockMs then falsely aborts EVERY subsequent turn (live finding
-            // 2026-06-24). The bridge calls this once per turn so each turn re-anchors
-            // from its own start (the next reserveBudget re-anchors via the IN-02
+            // wallClockMs would then falsely abort EVERY subsequent turn.
+            // The bridge calls this once per turn so each turn re-anchors
+            // from its own start (the next reserveBudget re-anchors via the
             // first-reserve write). GUARD: only when `activeCount === 0` — a root with a
             // LIVE spawn is NOT reset, so the genuine runaway-TREE wall-clock backstop
             // holds. Drops ONLY the budget meter's wall-clock + token maps (via
@@ -129,7 +130,7 @@ export function createBoundedAutonomy(deps) {
             // Compose the per-root AND per-socket sliding-window limits — deny if EITHER
             // trips. The per-root key bounds the whole tree's call rate
             // (`perRootCallsPerSec`); the per-socket key bounds a single orchestration
-            // socket via its OWN limiter (`perSocketCallsPerSec`, WR-01). Check the root
+            // socket via its OWN limiter (`perSocketCallsPerSec`). Check the root
             // bound first (the tree-wide cap), then the socket bound.
             const perRoot = rate.tryCall(`root:${rootRunId}`);
             if (!perRoot.ok)
@@ -162,7 +163,7 @@ export function createBoundedAutonomy(deps) {
             return leaseIdsByRoot.get(rootRunId) ?? new Set();
         },
         snapshot(rootRunId, agentId, channelId) {
-            // PURE read (INTRO-01 / T-215-05): delegate to the per-module remaining()
+            // PURE read: delegate to the per-module remaining()
             // accessors (themselves pure) + materialize the lease-correlation set as an
             // array. No gate state is mutated here.
             return {
@@ -172,7 +173,7 @@ export function createBoundedAutonomy(deps) {
             };
         },
         cronCount(agentId) {
-            // Delegate to the injected provider (the RATE-02 count source); the service
+            // Delegate to the injected provider (the cron-cap count source); the service
             // holds NO cron store of its own. Absent provider ⇒ 0 (fail-open on this
             // single limb — the endpoint gates origin/scope first).
             return deps.cronJobCount?.(agentId) ?? 0;

package/node_modules/@comis/daemon/dist/autonomy/call-rate-limiter.d.ts

@@ -1,5 +1,5 @@
 /**
- * Call-rate limiter (RATE-01): bounds the rate of cap-socket calls per root and
+ * Call-rate limiter: bounds the rate of cap-socket calls per root and
  * per socket, plus a connection-churn cap per root, using the sliding-window +
  * TTL-evict + maxEntries pattern from `core/src/security/injection-rate-limiter.ts`.
  *
@@ -14,7 +14,7 @@
  * `?? <wall-clock-global>` hazard the globals.test.ts arch-gate rejects) — the
  * clock is required. Returns discriminated unions, never throws (raw-throw.test.ts).
  *
- * The composite caller (Plan 07) constructs ONE limiter and calls
+ * The composite caller (`createBoundedAutonomy`) constructs ONE limiter and calls
  * `tryCall(\`root:${rootRunId}\`)` + `tryCall(\`socket:${socketId}\`)` per dispatch
  * and `tryChurn(rootRunId)` per new cap-socket connection.
  *

package/node_modules/@comis/daemon/dist/autonomy/call-rate-limiter.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Call-rate limiter (RATE-01): bounds the rate of cap-socket calls per root and
+ * Call-rate limiter: bounds the rate of cap-socket calls per root and
  * per socket, plus a connection-churn cap per root, using the sliding-window +
  * TTL-evict + maxEntries pattern from `core/src/security/injection-rate-limiter.ts`.
  *
@@ -15,7 +15,7 @@
  * `?? <wall-clock-global>` hazard the globals.test.ts arch-gate rejects) — the
  * clock is required. Returns discriminated unions, never throws (raw-throw.test.ts).
  *
- * The composite caller (Plan 07) constructs ONE limiter and calls
+ * The composite caller (`createBoundedAutonomy`) constructs ONE limiter and calls
  * `tryCall(\`root:${rootRunId}\`)` + `tryCall(\`socket:${socketId}\`)` per dispatch
  * and `tryChurn(rootRunId)` per new cap-socket connection.
  *

package/node_modules/@comis/daemon/dist/autonomy/denial-breaker.d.ts

@@ -1,10 +1,10 @@
 /**
  * `createDenialBreaker` — the per-`rootRunId` consecutive-floor-block counter
- * (Phase 217-02, BREAK-01) with trip-once semantics (BREAK-02).
+ * with trip-once semantics.
  *
  * The "never loop" guarantee: after N CONSECUTIVE floor-blocks a self-driving run
- * trips the breaker so the chokepoint (Plan 05) aborts + escalates rather than
- * retry-looping and burning the aggregate budget (T-217-05 DoS-on-self; the §8.7
+ * trips the breaker so the chokepoint aborts + escalates rather than
+ * retry-looping and burning the aggregate budget (a DoS-on-self; the
  * per-root budget stays the independent backstop).
  *
  * This is a daemon-internal sibling of {@link createBoundedAutonomy}, modeled on
@@ -18,15 +18,16 @@
  *     content-free trip log).
  *
  * CONSECUTIVE, not cumulative: {@link DenialBreaker.recordAllow} resets the
- * counter, so a single deny inside a productive loop never accumulates to a trip
- * (T-217-07). The trip fires on the EXACT crossing of `denialBreakerN` (`===`,
- * never `>=`) so a later deny does not re-trip — the tool-retry-breaker.ts:559
- * trip-once discipline (a `>=` verdict would inflate Phase 153's breakerTimeline
- * and re-abort an already-aborting run).
+ * counter, so a single deny inside a productive loop never accumulates to a trip.
+ * The trip fires on the EXACT crossing of `denialBreakerN` (`===`,
+ * never `>=`) so a later deny does not re-trip — the same trip-once
+ * discipline as `tool-retry-breaker.ts` (a `>=` verdict would inflate the
+ * breakerTimeline and re-abort an already-aborting run).
  *
  * Trust boundary: the chokepoint (trusted, in-daemon) is the SOLE driver. It calls
  * recordDenial ONLY on a `CapabilityDeniedError` floor-block (NOT generic
- * RPC/validation errors — the tool-retry-breaker.ts:214-269 lesson), recordAllow
+ * RPC/validation errors, which would trip the breaker on noise — the same
+ * classification discipline as `tool-retry-breaker.ts`), recordAllow
  * on the allow branch of a gated method, and {@link DenialBreaker.evict} at run
  * termination. So the breaker holds no untrusted input (rootRunId is a
  * daemon-minted id) and counts only genuine floor-blocks.

package/node_modules/@comis/daemon/dist/autonomy/denial-breaker.js

@@ -10,8 +10,8 @@ export function createDenialBreaker(deps) {
     const { denialBreakerN } = deps;
     const logger = deps.logger.child({ submodule: "denial-breaker" });
     // rootRunId → consecutive floor-block count. Reset on recordAllow, dropped on
-    // evict (the WR-05 per-root cleanup discipline — prevents a per-cron-fire-root
-    // map leak under a storm of distinct roots, T-217-06).
+    // evict (the per-root cleanup discipline — prevents a per-cron-fire-root
+    // map leak under a storm of distinct roots).
     const consecutiveByRoot = new Map();
     return {
         recordDenial(rootRunId) {
@@ -23,10 +23,10 @@ export function createDenialBreaker(deps) {
             // re-abort an already-aborting run and double-count the breakerTimeline).
             const tripped = consecutive === denialBreakerN;
             if (tripped) {
-                // Content-free trip WARN (T-217-08): errorKind + an operator hint naming
+                // Content-free trip WARN: errorKind + an operator hint naming
                 // the knob + the count + the rootRunId (an id, not a body). NO message
                 // body — the denied action's args/content never leak here. The eventBus
-                // abort + killByRootRun belong to the chokepoint (Plan 05), not here.
+                // abort + killByRootRun belong to the chokepoint, not here.
                 logger.warn({
                     rootRunId,
                     consecutive,
@@ -38,14 +38,14 @@ export function createDenialBreaker(deps) {
             return { tripped, consecutive };
         },
         recordAllow(rootRunId) {
-            // A real allowed step happened → reset. Per the research anti-pattern, ONLY
+            // A real allowed step happened → reset. ONLY
             // an ACTUAL allowed gated call resets; the chokepoint guarantees this is
             // called only on the allow branch of a gated method (never on a deny).
             consecutiveByRoot.delete(rootRunId);
         },
         evict(rootRunId) {
-            // Run-end / evict / kill cleanup (the WR-05 discipline). Idempotent —
-            // deleting an absent key is a no-op.
+            // Run-end / evict / kill cleanup (the per-root cleanup discipline).
+            // Idempotent — deleting an absent key is a no-op.
             consecutiveByRoot.delete(rootRunId);
         },
     };

package/node_modules/@comis/daemon/dist/autonomy/durable-resume-engine.d.ts

@@ -1,32 +1,32 @@
 /**
- * Durable resume engine (Phase 216 — the brain of the phase). On boot (and on
+ * Durable resume engine. On boot (and on
  * each watchdog tick) it turns persisted state back into live runs:
  *
- *   1. RECONCILE crashed-mid-send rows (ONCE-03/ONCE-04). An `unknown_after_send`
+ *   1. RECONCILE crashed-mid-send rows. An `unknown_after_send`
  *      ledger row is NEVER blind-replayed — the owning channel's `reconcileSend?`
  *      resolves it three ways: `sent` → ack once (commit, no replay), `not_sent`
  *      → replay exactly once, `unresolved` (or a channel that cannot reconcile)
  *      → park + escalate. A channel with no `reconcileSend` is treated as
- *      `unresolved` (Pitfall 2 — never a double-send dressed as a reconcile).
- *   2. RESUME-OR-ORPHAN (DUR-02/DUR-03). For each resumable run the engine
+ *      `unresolved` (never a double-send dressed as a reconcile).
+ *   2. RESUME-OR-ORPHAN. For each resumable run the engine
  *      re-mints a lease from the PERSISTED attenuated caps VERBATIM (never
  *      re-attenuating from a live parent — the persisted caps ARE the attenuated
  *      result). A `revoked` re-read, a caps-parse failure (a tampered superset),
  *      or an un-resumable run is ORPHANED + the operator is notified — never
  *      silently re-minted and never silently dropped. A legitimate never-sent run
- *      (stepIndex = -1, the NEW-5 sentinel) PASSES the guard and is resumed.
- *   3. BOUNDED RECOVERY (HB-02). The whole pass is bounded by a wall-clock
+ *      (stepIndex = -1, the never-sent sentinel) PASSES the guard and is resumed.
+ *   3. BOUNDED RECOVERY. The whole pass is bounded by a wall-clock
  *      `recoveryBudgetMs`; a backlog larger than the budget is partially
  *      recovered and the remainder DEFERRED (status stays `running`, so the
  *      watchdog / next boot picks them up) — no thundering herd.
- *   4. ORPHAN NOTIFICATION (HB-03). Every orphan fires the injected NotifyFn + an
+ *   4. ORPHAN NOTIFICATION. Every orphan fires the injected NotifyFn + an
  *      eventBus `durable:orphaned` + an INFO line — an un-resumed run is never
- *      silently vanished (DUR-02).
+ *      silently vanished.
  *
  * The engine is deliberately PURE / I/O-free: every dependency (the stores, the
  * LeaseManager re-mint, the channel lookup, the replay closure, the operator
  * notify, the clock, the event bus) is INJECTED so it is exhaustively
- * unit-testable with a fake clock + stub stores + a stub channel. Plan 07's
+ * unit-testable with a fake clock + stub stores + a stub channel. The
  * wiring binds it to the real stores / LeaseManager / channel adapters and calls
  * `resumeAll()` on boot. No callable-global time/timer reads here (the
  * globals.test.ts arch-gate forbids the wall-clock and interval-scheduler
@@ -36,14 +36,14 @@
  * line (with durationMs) + an eventBus event; every failure branch carries
  * `hint` + `errorKind` (the closed precondition|dependency|platform|internal
  * union). Content-free: rootRunId/stepIndex/state/reconcileOutcome/counts ONLY —
- * never the message body (the reconcile query keys on a contentDigest, T-216-17).
+ * never the message body (the reconcile query keys on a contentDigest).
  *
  * @module
  */
 import { type Result } from "@comis/shared";
 import { type OutwardSendLedgerPort, type OutwardSendRecord, type ChannelPort, type DurableRunPort, type DurableRunRecord, type AgentCapability, type ComisLogger } from "@comis/core";
 /**
- * The content-free operator notification (HB-03). Reuses the background-task
+ * The content-free operator notification. Reuses the background-task
  * NotifyFn shape: ids + a reason + a hint, NEVER a message body. Fired
  * out-of-band for every orphan / unresolved reconcile.
  */
@@ -71,24 +71,51 @@ export interface IssuedLease {
 }
 /**
  * The narrow content-free event emitter the engine calls on each transition.
- * Plan 07's wiring binds a real TypedEventBus adapter; the engine stays I/O-free
+ * The wiring binds a real TypedEventBus adapter; the engine stays I/O-free
  * and the closed EventMap (owned at the wiring layer) is not coupled here.
  */
 export interface DurableEventEmitter {
     emit(event: string, payload: Record<string, unknown>): void;
 }
 /**
- * FLEET-03 (Phase 220-01): map the engine's free-text orphan reason to the
- * CLOSED enum the `durable:orphaned` EVENT carries (events-orchestration.ts).
- * TOTAL over `string` — the `default` arm guarantees every input (including a
- * brand-new unmapped reason) returns a union member and the function NEVER
- * echoes its `freeText` argument. This is the T-220-01 content-free invariant AT
- * THE SOURCE: the free string stays ONLY on the WARN log / notify (the operator's
- * debugging surface); the closed enum is the only thing that crosses onto the
- * event/obs-row. Mirrors the closed-union discriminator pattern of
- * `execution:aborted.reason`.
+ * Map the engine's free-text orphan reason to the CLOSED enum the
+ * `durable:orphaned` EVENT carries (events-orchestration.ts). TOTAL over
+ * `string` — the `default` arm guarantees every input (including a brand-new
+ * unmapped reason) returns a union member and the function NEVER echoes its
+ * `freeText` argument. This is the content-free invariant AT THE SOURCE: the
+ * free string stays ONLY on the WARN log / notify (the operator's debugging
+ * surface); the closed enum is the only thing that crosses onto the event/obs-row.
+ * Mirrors the closed-union discriminator pattern of `execution:aborted.reason`.
  */
 export declare function orphanReasonToEnum(freeText: string): "not_resumable" | "reread_failed" | "invalid_caps" | "resume_failed";
+/**
+ * The injected seams the orphan-reclaim hook composes. Both are best-effort /
+ * result-degrading in production (a missing file is a no-op), so reclaim is
+ * IDEMPOTENT. Injected so the hook is macOS-unit-testable against a real temp
+ * workspace with no daemon boot / no concrete store import.
+ */
+export interface OrchestrateReclaimSeams {
+    /** Resolve the dead run's workspace ROOT (undefined ⇒ nothing to reclaim). */
+    readonly workspaceFor: (record: DurableRunRecord) => string | undefined;
+    /** Delete the run's `results/` dir — reuses result-ref-store.cleanupRun (rmSync recursive). */
+    readonly cleanupResults: (workspacePath: string, runId: string) => Promise<void>;
+    /** Delete the pinned `<scriptRef>` at the workspace root (guarded rmSync — a missing file is a no-op). */
+    readonly removePinnedScript: (workspacePath: string, scriptRef: string) => void;
+}
+/**
+ * Reclaim a dead resumable orchestrate run's artifacts: its surviving `results/`
+ * (the checkpoint blob + any materialized results) + the pinned `<scriptRef>`.
+ *
+ * The RESUME-04 orphan sweep. A run orphaned on boot (its checkpoint gone) or on a
+ * lapsed-heartbeat watchdog tick has NO surviving runner to GC its workspace (the
+ * runner's own run-end cleanup never fired — the process crashed mid-pipeline), so
+ * the orphan path is the OWNER of the reclaim. SCOPED to orchestrate-kind rows
+ * (`scriptRef != null` — a re-runnable orchestrate row); a DAG/flat legacy orphan
+ * carries no `scriptRef` and is a no-op. IDEMPOTENT — a second reclaim finds the
+ * files already gone (the seams degrade, never throw). Composes the EXISTING
+ * `cleanupRun` + a guarded `rmSync` — no new GC primitive (NG4).
+ */
+export declare function reclaimOrphanedOrchestrateRun(record: DurableRunRecord, seams: OrchestrateReclaimSeams): Promise<void>;
 /** Dependencies for {@link reconcileLedgerRow}. */
 export interface ReconcileLedgerDeps {
     readonly ledger: OutwardSendLedgerPort;
@@ -103,16 +130,16 @@ export interface ReconcileLedgerDeps {
     readonly logger: ComisLogger;
 }
 /**
- * Reconcile ONE crashed-mid-send ledger row (ONCE-03/ONCE-04). The exactly-once
+ * Reconcile ONE crashed-mid-send ledger row. The exactly-once
  * core: it asks the channel "was this sent?" and resolves the row accordingly —
  * it NEVER blind-replays.
  *
- *   - `committed` row → no-op (ONCE-02; already terminal-success).
+ *   - `committed` row → no-op (already terminal-success).
  *   - channel has no `reconcileSend` → treated as `unresolved` → park + escalate,
- *     NO replay (Pitfall 2 — an un-queryable channel must never double-send).
+ *     NO replay (an un-queryable channel must never double-send).
  *   - `sent`       → resolveReconcile("sent") + commit(platformMessageId); NO replay.
  *   - `not_sent`   → resolveReconcile("not_sent") + replay ONCE; on ok → commit;
- *                    on a PERMANENT error → markFailed("permanent") (ONCE-04, retry
+ *                    on a PERMANENT error → markFailed("permanent") (retry
  *                    budget skipped); on a TRANSIENT error → leave for the next tick.
  *   - `unresolved` → resolveReconcile("unresolved") + notify escalation; NO replay,
  *                    NO commit.
@@ -138,10 +165,18 @@ export interface DurableResumeEngineDeps {
     }, Error>>;
     readonly notify: NotifyFn;
     readonly nowMs: () => number;
-    /** The wall-clock recovery budget (ms) — the whole pass is bounded by it (HB-02). */
+    /** The wall-clock recovery budget (ms) — the whole pass is bounded by it. */
     readonly recoveryBudgetMs: number;
     readonly logger: ComisLogger;
     readonly eventBus: DurableEventEmitter;
+    /**
+     * Reclaim a dead resumable orchestrate run's artifacts on the orphan path
+     * (RESUME-04). Called for a run whose resume FAILED (e.g. the boot-sweep arm
+     * found a missing checkpoint); scoped + idempotent by the bound
+     * {@link reclaimOrphanedOrchestrateRun} (a non-orchestrate row is a no-op).
+     * Absent ⇒ no reclaim (a flat/legacy-only wiring).
+     */
+    readonly reclaimOrchestrateRun?: (record: DurableRunRecord) => Promise<void>;
 }
 /** The result of one boot/watchdog recovery pass. */
 export interface ResumeAllResult {