@sema-agent/server 7.2.0 → 7.4.0

package/dist/boot/reapers.js

@@ -15,9 +15,66 @@
 import { Runner, defaultTaskRegistry } from "@sema-agent/core";
 import { sweepStaleScratchpads } from "../env-facts.js";
 import { CostQuota } from "../observability/cost-quota.js";
+import { createApprovalReconciler } from "../approval-reconciler.js";
+/** #157 / [2762]§五(sema-comms `audits/failopen-governance-176.md` §7 "Z 类 1 条"):default consecutive-failure
+ *  count before a reaper leg's swallowed error gets a `warn` line. The ~15 `.catch(() => undefined)` sites
+ *  below are correct in DIRECTION (a hiccuping periodic sweep must never crash the whole tick loop — one bad
+ *  leg cannot be allowed to starve its ~15 siblings), but were zero-observability: an operator watching only
+ *  `warn`/`error` would never learn a leg had been silently broken for days. `5` (not `1`) is deliberate —
+ *  a transient blip (one DB reconnect, one timeout) is exactly what fail-open exists to absorb without noise;
+ *  only a STREAK crosses into "diagnosable, not transient". Exported so a future per-leg override is a
+ *  constructor-arg change, not a magic-number hunt. */
+export const REAPER_FAILURE_WARN_THRESHOLD = 5;
+/**
+ * Builds a NAMED, stateful throttle for one reaper leg: attach as `.then(() => guard.onSuccess(), guard.onError)`
+ * in place of a bare `.catch(() => undefined)` (the two-arg `.then` form still catches a rejection from any
+ * earlier link in the chain — same coverage as the `.catch()` it replaces — while also observing the FULFILLED
+ * path, which a plain `.catch()` cannot). Behavior this closure owns, unchanged reaper scheduling/cleanup:
+ *  - a successful run resets the consecutive-failure streak to 0 (one hiccup mid-outage doesn't inflate the count);
+ *  - a failure increments the streak; only once the streak reaches `threshold` (default
+ *    {@link REAPER_FAILURE_WARN_THRESHOLD}) does ONE `warn` line fire (reaper name + streak length + the most
+ *    recent error's message) — then the streak resets to 0 so a STILL-broken leg reports again after another
+ *    full `threshold` run, rather than going silent forever after its first report.
+ * One instance must be created ONCE per named leg (outside the tick's `setInterval` callback) so the streak
+ * survives across ticks — a fresh instance per tick would never accumulate past 1.
+ */
+export function createThrottledReaperCatch(name, logger, threshold = REAPER_FAILURE_WARN_THRESHOLD) {
+    let streak = 0;
+    return {
+        onSuccess: () => {
+            streak = 0;
+        },
+        onError: (err) => {
+            streak += 1;
+            if (streak < threshold)
+                return;
+            try {
+                // #157 补痕交叉复审真发现(codex,2026-08-05):`String(err)` on a pathological rejection reason
+                // (a throwing `Symbol.toPrimitive`/`toString`) or a throwing `logger.warn` transport would otherwise
+                // make THIS handler throw — and since onError is wired as a `.then(fulfilled, onError)` REJECTED
+                // branch with no further `.catch` downstream (every reapers.ts call site), that throw becomes a
+                // floating rejected promise (an unhandled rejection under Node's default handling can crash the
+                // process). The ORIGINAL `.catch(() => undefined)` this replaces could never do that — a failure
+                // in the REPORTING of a swallowed leg failure must not be worse than the silence it replaces, so
+                // this whole block is wrapped total/non-throwing.
+                logger.warn("reaper_leg_repeated_failure", {
+                    reaper: name,
+                    consecutiveFailures: streak,
+                    lastError: err instanceof Error ? err.message : String(err),
+                });
+            }
+            catch {
+                // observability must never itself become the outage — see comment above.
+            }
+            finally {
+                streak = 0; // re-open the window — a leg that stays broken reports again every `threshold` failures, not once ever.
+            }
+        },
+    };
+}
 /** 起后台维护 tick,返回定时器 handle(收尾段 clearInterval 用)。 */
 export function startReapers(ctx) {
-    const { config, logger, metrics, localRoot, backend, subRunner, runStore, checkpointStore, rateLimiter, costQuota, toolResultStore, fileSnapshotStore, taskAttachmentStore, imageBakes, worktreeReap, workflowNotifyGate, workflowJournalStore, sqlWorkflowRunStore, workflowNotifyJournal, rosterStore, backgroundAgentStore, mailboxStore, getRunDenySweep, } = ctx;
+    const { config, logger, metrics, localRoot, backend, subRunner, runStore, checkpointStore, rateLimiter, costQuota, toolResultStore, fileSnapshotStore, taskAttachmentStore, imageBakes, worktreeReap, workflowNotifyGate, workflowJournalStore, sqlWorkflowRunStore, workflowNotifyJournal, rosterStore, backgroundAgentStore, mailboxStore, toolApproval, getRunDenySweep, } = ctx;
     // S7 (SILENT-FALLBACK P0-d): the sweeps' return counts were discarded — an instance death that batch-fails
     // N orphans was indistinguishable from organic failures. Count + log ONLY when a sweep flipped rows (>0),
     // so healthy ticks stay silent. Tolerant of void-returning stores (typeof guard).
@@ -31,6 +88,54 @@ export function startReapers(ctx) {
     let attachmentSweepInFlight = false; // 复审 F1:附件孤儿 sweep 的重入守卫(同上)
     let bgAgentReapInFlight = false; // core 1.364: same serialization for the durable bg-agent joint reap (per-scope serial loop)
     let worktreeReapInFlight = false; // A10 留档发现①(2026-07-29):worktreeReap 重入守卫(同上三个邻居——见下方调用点注释)
+    // #157 / [2762]§五 Z 类补痕:one NAMED throttled-catch guard per periodic leg below (created ONCE here, not
+    // per-tick, so each leg's consecutive-failure streak survives across ticks — see createThrottledReaperCatch).
+    const probeClockSkewGuard = createThrottledReaperCatch("probe_clock_skew", logger);
+    const runsReapStaleGuard = createThrottledReaperCatch("runs_reap_stale", logger);
+    const checkpointsReapExpiredGuard = createThrottledReaperCatch("checkpoints_reap_expired", logger);
+    const runsFailSuspendedExpiredCheckpointGuard = createThrottledReaperCatch("runs_fail_suspended_expired_checkpoint", logger);
+    const runDenySweepGuard = createThrottledReaperCatch("run_deny_sweep", logger);
+    const runsReapSuspendedGuard = createThrottledReaperCatch("runs_reap_suspended", logger);
+    const checkpointReapCtxGuard = createThrottledReaperCatch("checkpoint_reap_ctx", logger);
+    const toolResultReapOlderThanGuard = createThrottledReaperCatch("tool_result_reap_older_than", logger);
+    const fileSnapshotSweepOrphanBlobsGuard = createThrottledReaperCatch("file_snapshot_sweep_orphan_blobs", logger);
+    const attachmentReapUnboundGuard = createThrottledReaperCatch("attachment_reap_unbound", logger);
+    const sessionSweepStagingGuard = createThrottledReaperCatch("session_sweep_staging", logger);
+    const imageBakesReapStaleGuard = createThrottledReaperCatch("image_bakes_reap_stale", logger);
+    const worktreeReapGuard = createThrottledReaperCatch("worktree_reap", logger);
+    const workflowNotifyRecoverGuard = createThrottledReaperCatch("workflow_notify_recover", logger);
+    const workflowJournalReapExpiredGuard = createThrottledReaperCatch("workflow_journal_reap_expired", logger);
+    const workflowRunReapAllScopesGuard = createThrottledReaperCatch("workflow_run_reap_all_scopes", logger);
+    const workflowNotifyJournalReapAckedGuard = createThrottledReaperCatch("workflow_notify_journal_reap_acked", logger);
+    const bgAgentsReapGuard = createThrottledReaperCatch("bg_agents_reap", logger);
+    const rosterReapOlderThanGuard = createThrottledReaperCatch("roster_reap_older_than", logger);
+    const scratchpadSweepStaleGuard = createThrottledReaperCatch("scratchpad_sweep_stale", logger);
+    const approvalReconcileGuard = createThrottledReaperCatch("approval_reconcile", logger);
+    let approvalReconcileInFlight = false; // 车5 §8 C-8:重入守卫(邻居四先例同形——本腿时长随 PARKING 行数增长)
+    // #151 车5(design/172 §3.0 对账收敛器 + 崩溃恢复扫描):**总开关默认 OFF ⇒ 本腿根本不注册**
+    // (`STREAM_APPROVAL_ENABLED=false` 的部署一行库都不扫,零新增查询)。开且有 durable backend 时才建。
+    // 判据 1/2 的两个读口按能力面接:checkpoint 店的窄读口只有 SQL twins 有(local 车道的店没有这个面),
+    // 缺席 ⇒ 判据 1 恒不命中(诚实降级,行落 ②③④⑤),不是「假装没 checkpoint 就该 DENY」。
+    const approvalReconciler = (() => {
+        if (!config.streamApproval.enabled || !backend)
+            return undefined;
+        // duck probe(邻居同形:本文件 `sweepStagingSessions` / `reapAllScopes` 都是这个姿势)——
+        // `CheckpointStoreFull` 的 local 成员没有这个窄读口,它是 SQL twins 的扩展面。
+        const cpPort = checkpointStore;
+        return createApprovalReconciler({
+            askStore: backend.approvalAsk(),
+            checkpoints: typeof cpPort?.findCheckpointCandidatesForAsk === "function" ? cpPort : undefined,
+            // RunStore 三形(TiDB/Pg/File)都带 `getRun`,故直接接、无 probe。
+            runs: runStore,
+            logger,
+            metrics,
+            batchLimit: config.streamApproval.reconcileBatch,
+            pendingGraceMs: config.streamApproval.pendingGraceMs,
+            adhocGraceMs: config.streamApproval.adhocGraceMs,
+            orphanTtlMs: config.streamApproval.orphanTtlMs,
+            ...(toolApproval ? { emitRevoke: (frame, target) => void toolApproval.emitRevoke(frame, target) } : {}),
+        });
+    })();
     // core 1.364([1503] 提货单③):retention **只走** reapDurableAgents(联合 reap:条件删赢了才 release
     // 转录 session;裸 store.reap 会 strand 转录)。staleRunning 翻转在 core 编排内先行(store.reap 一步)。
     // scope 枚举:core 1.368 `BackgroundAgentStore.listScopes?()`([1516]② 交付,SQL twins/File 双实现
@@ -87,7 +192,17 @@ export function startReapers(ctx) {
                 }
                 catch (err) {
                     failedScopes++;
-                    logger.warn("bg_agent_reap_scope_failed", { scope, err: err instanceof Error ? err.message : String(err) });
+                    // codex 交叉复审第三轮真发现(2026-08-05):a poison `err` (throwing `Symbol.toPrimitive`/`toString`)
+                    // or a throwing `logger.warn` must not escape THIS catch — the outer `bgAgentsReapGuard` (this
+                    // car's own wiring) already stops it from becoming an unhandled rejection, but an uncaught throw
+                    // HERE would abort the `for` loop early and skip every remaining scope, defeating the per-scope
+                    // isolation this block exists for ("[1522] LOW3" above — one bad scope must not starve the rest).
+                    try {
+                        logger.warn("bg_agent_reap_scope_failed", { scope, err: err instanceof Error ? err.message : String(err) });
+                    }
+                    catch {
+                        // observability must never break the per-scope loop — see comment above.
+                    }
                 }
             }
             if (failedScopes > 0)
@@ -116,8 +231,11 @@ export function startReapers(ctx) {
         }
     };
     const reaper = setInterval(() => {
-        void probeClockSkew().catch(() => undefined); // S10
-        void runStore?.reapStale(config.runStaleSec * 1000).then(reapCount("runs_reaped_total", { kind: "stale" })).catch(() => undefined);
+        void probeClockSkew().then(() => probeClockSkewGuard.onSuccess(), probeClockSkewGuard.onError); // S10
+        void runStore
+            ?.reapStale(config.runStaleSec * 1000)
+            .then(reapCount("runs_reaped_total", { kind: "stale" }))
+            .then(() => runsReapStaleGuard.onSuccess(), runsReapStaleGuard.onError);
         // Durable F4 (design/45) + design/80 §3 inv#3 crash-safe backstop: CAS-expire checkpoints past their
         // deadline OR their absolute terminal_at backstop (≈ deny), then fail the suspended run rows whose
         // checkpoint was thereby expired (release task_active = unlock the session). These run EVERY tick,
@@ -131,32 +249,51 @@ export function startReapers(ctx) {
             // 真 pin 只存在于 in-memory TtlSessionStore;本部署 durable checkpoint 恒配 durable session 后端
             // (pin=no-op),deny-sweep 走 resumeCheckpoint=core 内部 unpin ✓。SESSION_BACKEND=memory+durable
             // checkpoint 的 niche dev 组合下 abort-expire 臂会把被钉会话泄到进程终——显式接受,不为 dev 形加腿。
-            void checkpointStore.reapExpired(Date.now()).then(reapCount("checkpoints_reaped_total", {})).catch(() => undefined);
-            void runStore?.failSuspendedWithExpiredCheckpoint().then(reapCount("runs_reaped_total", { kind: "expired_checkpoint" })).catch(() => undefined);
+            void checkpointStore
+                .reapExpired(Date.now())
+                .then(reapCount("checkpoints_reaped_total", {}))
+                .then(() => checkpointsReapExpiredGuard.onSuccess(), checkpointsReapExpiredGuard.onError);
+            void runStore
+                ?.failSuspendedWithExpiredCheckpoint()
+                .then(reapCount("runs_reaped_total", { kind: "expired_checkpoint" }))
+                .then(() => runsFailSuspendedExpiredCheckpointGuard.onSuccess(), runsFailSuspendedExpiredCheckpointGuard.onError);
             // D-D SLA-timer: resolve-DENY human/irreversible_ask gates past their deadline (graceful — the model
             // continues with the denial), vs the abort reapExpired gives the other kinds. Bounded per tick.
-            void getRunDenySweep()?.(Date.now()).catch(() => undefined); // A10 搬运改写:晚绑取值(原 `runDenySweep?.`)
+            void getRunDenySweep()?.(Date.now())
+                .then(() => runDenySweepGuard.onSuccess(), runDenySweepGuard.onError); // A10 搬运改写:晚绑取值(原 `runDenySweep?.`)
         }
         // The finer, OPT-IN time-based suspended-run reaper (APPROVAL_TIMEOUT_SEC). Stays gated — reapSuspended
         // with a 0 TTL would nuke ALL suspended rows (cutoff = now). The absolute backstop above is the safety
         // floor; this is the operator-chosen deadline. ([2354] A-5:F4 轮询店的 expireStale 腿随车道退役。)
         if (config.approvalTimeoutSec > 0) {
-            void runStore?.reapSuspended(config.approvalTimeoutSec * 1000).then(reapCount("runs_reaped_total", { kind: "suspended" })).catch(() => undefined);
+            void runStore
+                ?.reapSuspended(config.approvalTimeoutSec * 1000)
+                .then(reapCount("runs_reaped_total", { kind: "suspended" }))
+                .then(() => runsReapSuspendedGuard.onSuccess(), runsReapSuspendedGuard.onError);
         }
         // GC checkpoint_ctx rows whose checkpoint is gone (bound to the checkpoint lifecycle).
-        void checkpointStore?.reapCtx(Date.now() - config.runStaleSec * 1000).catch(() => undefined);
+        void checkpointStore
+            ?.reapCtx(Date.now() - config.runStaleSec * 1000)
+            .then(() => checkpointReapCtxGuard.onSuccess(), checkpointReapCtxGuard.onError);
         rateLimiter?.sweep();
         if (costQuota instanceof CostQuota)
             costQuota.reap(); // TiDB variant self-reaps in its flush loop
-        void toolResultStore?.reapOlderThan?.(Date.now() - config.toolResultTtlSec * 1000)?.catch(() => undefined); // optional extra: SQL twins only (the local FileToolResultStore persists like transcripts)
+        void toolResultStore
+            ?.reapOlderThan?.(Date.now() - config.toolResultTtlSec * 1000)
+            ?.then(() => toolResultReapOlderThanGuard.onSuccess(), toolResultReapOlderThanGuard.onError); // optional extra: SQL twins only (the local FileToolResultStore persists like transcripts)
         // 2c session-sync: GLOBALLY GC grace-window orphan blobs (standalone /sync/blobs PUTs that were never
         // imported are otherwise collected only on reap()/deleteBySession(), which never fire for a never-imported scope).
         // Bounds the standalone-PUT orphan-blob exhaustion (review finding) to the grace window. Durable twins only (local
         // omits the seam → optional-chained no-op).
-        void fileSnapshotStore?.sweepOrphanBlobs?.().catch(() => undefined);
+        void fileSnapshotStore
+            ?.sweepOrphanBlobs?.()
+            .then(() => fileSnapshotSweepOrphanBlobsGuard.onSuccess(), fileSnapshotSweepOrphanBlobsGuard.onError);
         // D-1 附件 TTL:上传后从未被任何 task 引用(session_id NULL)且超过 attachmentUnboundTtlMs 的行收割
         // (绑定行不在此收——随会话 E21 级联删)。best-effort,与其余 reaper 腿同姿。
-        void taskAttachmentStore?.reapUnbound(Date.now() - config.attachmentUnboundTtlMs).then(reapCount("attachments_reaped_total", {})).catch(() => undefined);
+        void taskAttachmentStore
+            ?.reapUnbound(Date.now() - config.attachmentUnboundTtlMs)
+            .then(reapCount("attachments_reaped_total", {}))
+            .then(() => attachmentReapUnboundGuard.onSuccess(), attachmentReapUnboundGuard.onError);
         // D-1 孤儿**对象**彻底 GC(clay 拍 2026-07-28):对象存储 × meta 行对账,grace 默认 1h(上传先行窗
         // 保护;`ATTACHMENT_ORPHAN_GRACE_MS=0` 关掉本腿——同 tick 邻居都有旋钮,复审 F10)。
         // 列举失败=本轮 warn 跳过(「列不出来」绝不当「没有孤儿」),下轮再试。
@@ -171,18 +308,35 @@ export function startReapers(ctx) {
                 metrics.inc("attachment_orphan_objects_swept_total", {}, n);
                 logger.info("attachment_orphan_objects_swept", { removed: n });
             } })
-                .catch((err) => logger.warn("attachment_orphan_sweep_failed", { err: String(err) }))
+                .catch((err) => {
+                // codex 交叉复审第二轮真发现(2026-08-05):`String(err)` on a pathological rejection reason or a
+                // throwing `logger.warn` transport must not escape THIS handler — this `.catch` sits ahead of a
+                // `.finally()` with no further `.catch` downstream, so an uncaught throw here becomes a floating
+                // rejected promise (unhandled rejection under Node's default handling). Same invariant as
+                // createThrottledReaperCatch.onError above: a reaper leg's failure REPORTING must never itself
+                // crash the tick loop.
+                try {
+                    logger.warn("attachment_orphan_sweep_failed", { err: err instanceof Error ? err.message : String(err) });
+                }
+                catch {
+                    // observability must never crash the tick — see comment above.
+                }
+            })
                 .finally(() => { attachmentSweepInFlight = false; });
         }
         // P1d-β 2c session-sync: GC ABANDONED staged imports — staging-id session_event rows (`%#stg-%`) with NO
         // session_meta whose oldest row is older than the grace window (an in-flight stream stays fresh → never reaped).
         // Bounds the orphan-staging-row growth (a Phase B that opened a staging then never committed). Durable session
         // stores only (the local backend stages in memory → no durable rows; the seam is absent → optional-chained no-op).
-        void backend?.session()?.sweepStagingSessions?.().catch(() => undefined);
+        void backend?.session()?.sweepStagingSessions?.()
+            .then(() => sessionSweepStagingGuard.onSuccess(), sessionSweepStagingGuard.onError);
         // Bake-runner backstop (§P2.7): fail any `running` bake whose lease went stale (the runner crashed mid-build),
         // append a synthetic terminal `done{failed}` so SSE readers settle, and force-release the single-flight lease.
         // staleMs (≈3× the 30s heartbeat) bounds a healthy slow build so it is never wrongly reaped.
-        void imageBakes?.reapStaleBakes(config.imageBakes.staleMs).then(reapCount("bakes_reaped_total", {})).catch(() => undefined);
+        void imageBakes
+            ?.reapStaleBakes(config.imageBakes.staleMs)
+            .then(reapCount("bakes_reaped_total", {}))
+            .then(() => imageBakesReapStaleGuard.onSuccess(), imageBakesReapStaleGuard.onError);
         // SVC-3 worktree isolation: deregister worktrees orphaned by a process crash (the Runner never reached
         // destroy → `git worktree remove` never ran). `git worktree prune` cleans registrations whose dirs are
         // already gone. Best-effort, userland (core ships no post-kill Runner hook); never throws. Unset = no-op.
@@ -192,16 +346,22 @@ export function startReapers(ctx) {
         // 照抄 bgAgentReap 的 in-flight + finally 释放形。
         if (worktreeReap && !worktreeReapInFlight) {
             worktreeReapInFlight = true;
-            void worktreeReap().catch(() => undefined).finally(() => (worktreeReapInFlight = false));
+            void worktreeReap()
+                .then(() => worktreeReapGuard.onSuccess(), worktreeReapGuard.onError)
+                .finally(() => (worktreeReapInFlight = false));
         }
         // SVC-1 (adversarial-review HIGH): PERIODIC notify-recovery sweep (not just at boot) — re-delivers a terminal
         // run whose in-process notify was lost, AND finalizes-as-abandoned a `running` run orphaned past the grace
         // window (core never resumes/reaps a prior `running` row, so nothing else would). Idempotent; best-effort.
-        void workflowNotifyGate?.recover({ orphanGraceMs: config.workflowOrphanGraceMs }).catch(() => undefined);
+        void workflowNotifyGate
+            ?.recover({ orphanGraceMs: config.workflowOrphanGraceMs })
+            .then(() => workflowNotifyRecoverGuard.onSuccess(), workflowNotifyRecoverGuard.onError);
         // SVC-2 (adversarial-review HIGH): time-based GC of the workflow_journal table (the heaviest, TaskResult-bearing
         // one) — the per-run deleteByRun has no run-store reap hook, so this bounded sweep is what stops unbounded
         // growth. A resume of a journal older than the retention window re-runs live (resume is an optimization).
-        void workflowJournalStore?.reapExpired?.(Date.now(), config.workflowJournalRetentionMs).catch(() => undefined);
+        void workflowJournalStore
+            ?.reapExpired?.(Date.now(), config.workflowJournalRetentionMs)
+            .then(() => workflowJournalReapExpiredGuard.onSuccess(), workflowJournalReapExpiredGuard.onError);
         // Retention (WorkflowRunStore never auto-purges, reap is explicit):
         // age out TERMINAL workflow_run rows across ALL scopes. SQL twins only (reapAllScopes is their DISTINCT-scope
         // extension; the contract itself has no cross-scope enumeration, and the File store keeps the transcripts-like
@@ -212,37 +372,52 @@ export function startReapers(ctx) {
             const sweep = sqlWorkflowRunStore?.reapAllScopes?.(Date.now(), { maxAgeMs: config.workflowRunRetentionMs });
             if (sweep) {
                 wfRunReapInFlight = true;
-                void sweep.catch(() => undefined).finally(() => (wfRunReapInFlight = false));
+                void sweep
+                    .then(() => workflowRunReapAllScopesGuard.onSuccess(), workflowRunReapAllScopesGuard.onError)
+                    .finally(() => (wfRunReapInFlight = false));
             }
             // 1.108: SQL notify-journal retention rides the same knob — ACKED rows are pure history (pending rows are
             // the recovery backlog and are NEVER reaped; the orphan-grace sweep retires a stuck pending run).
             void workflowNotifyJournal
                 ?.reapAcked?.(Date.now() - config.workflowRunRetentionMs)
-                .catch(() => undefined);
+                .then(() => workflowNotifyJournalReapAckedGuard.onSuccess(), workflowNotifyJournalReapAckedGuard.onError);
         }
         // core 1.364 durable bg-agent joint reap(定义在 interval 上方,契约注释在彼)。in-flight 守卫同
         // wfRun sweep(per-scope 串行循环,短 tick + 多 scope 下不叠罗汉)。
         if (reapBgAgents && !bgAgentReapInFlight) {
             bgAgentReapInFlight = true;
-            void reapBgAgents().catch(() => undefined).finally(() => (bgAgentReapInFlight = false));
+            void reapBgAgents()
+                .then(() => bgAgentsReapGuard.onSuccess(), bgAgentsReapGuard.onError)
+                .finally(() => (bgAgentReapInFlight = false));
         }
         // [1522] MED2:agent_roster TTL 清理(core RB-23②③ 派给部署的半场)——SQL twins 扩展面
         // (reapOlderThan,duck probe;File/Memory 店 core 自带 maxAgeMs,无此面=no-op)。
         void rosterStore
             ?.reapOlderThan?.(Date.now() - config.rosterRetentionMs)
             .then(reapCount("roster_rows_reaped_total", {}))
-            .catch(() => undefined);
+            .then(() => rosterReapOlderThanGuard.onSuccess(), rosterReapOlderThanGuard.onError);
         // 修8(三路复审 absorb-2,接线 (b)):periodic scratchpad sweep — 无 E21 purge 兜到的孤儿目录(session 从未
         // DELETE、purge 当次失败、local 后端无 purge coordinator)按 mtime 过期回收。SCRATCHPAD_SWEEP_TTL_MS
         // (default 7d,0=禁用)。activeSessionIds 不传:活跃判据的诚实边界在 env-facts.ts 的 sweep 文档——TTL 7d
         // 远大于任何在飞任务;一个 7 天零写入的 scratchpad 被回收是可接受的(它本就是临时区,fact 文案即如此宣示)。
+        // #151 车5:流内审批的对账收敛器 + 崩溃恢复扫描(两段都在 `runOnce` 内,见 approval-reconciler.ts
+        // 判据表 v2)。**不新起独立定时器**——复用本 tick(收敛延迟上界 = 一个 reaper tick;壳侧的体感由
+        // 车4 的 425 `Retry-After` 覆盖)。in-flight 守卫同邻居四腿:本腿时长随 PARKING 行数与两个读口的
+        // 库延迟增长,短 REAP_INTERVAL_SEC 下无守卫会逐 tick 叠罗汉压同一批行。
+        if (approvalReconciler && !approvalReconcileInFlight) {
+            approvalReconcileInFlight = true;
+            void approvalReconciler
+                .runOnce(Date.now())
+                .then(() => approvalReconcileGuard.onSuccess(), approvalReconcileGuard.onError)
+                .finally(() => (approvalReconcileInFlight = false));
+        }
         if (config.scratchpadSweepTtlMs > 0) {
             void sweepStaleScratchpads(config.localDataRoot ?? localRoot, { olderThanMs: config.scratchpadSweepTtlMs })
                 .then((removed) => {
                 if (removed > 0)
                     logger.info("scratchpads_swept", { removed });
             })
-                .catch(() => undefined);
+                .then(() => scratchpadSweepStaleGuard.onSuccess(), scratchpadSweepStaleGuard.onError);
         }
     }, config.reapIntervalSec * 1000);
     reaper.unref?.();

package/dist/boot/resolve-spec.js

@@ -42,12 +42,13 @@ import { applyRuntimeGovernance, stripDelegationTools } from "../runtime-governa
 import { HttpError, encodeCheckpointScope } from "../security.js";
 import { memorySpecForRequest } from "../memory-scope.js";
 import { mcpForScenario } from "../config-center/facade.js";
-import { normalizeAttachments, normalizeResilience, normalizeResumeAtMode, normalizeSuggestNextPrompts, promptProfileFromBody, resolveTaskLimits, retainBackgroundProcessesFromBody, taskAgentsSpecFragment, toolNameListFromBody } from "../spec-fields.js";
+import { normalizeAttachments, normalizeResilience, normalizeResumeAtMode, normalizeSuggestNextPrompts, promptProfileFromBody, resolveTaskLimits, retainBackgroundProcessesFromBody, taskAgentsSpecFragment, toolMaterializeStrategyFromBody, toolNameListFromBody } from "../spec-fields.js";
 import { cwdHonored, effectiveHostWorkspace, inProcessSingleUserLane, isValidCwd, parseAdditionalDirectories, satisfiedByProcessCwd, shellEnvMismatchCount } from "../task-cwd.js";
 import { resolveRequestMcp } from "../task-mcp.js";
 import { MAX_SETTINGS_OUTPUT_STYLE_CHARS, acceptAppendSystemPrompt, applyTaskSettings, coercePermissionMode, effectiveThinking, hasConstitutionAnchors, parseTaskSettings, providerDropsAppend, withPermissionMode } from "../task-settings.js";
 import { enableForkFromBody, normalizeRetainSubagentSessions, selfOrchestrationFromBody } from "../task-workflow.js";
 import { redactSecrets } from "../trace/redact.js";
+import { DeferredSandboxPathEnv, isSandboxPathAdjudicationLane, sandboxPathEnvSlots } from "./deferred-sandbox-path-env.js";
 /** #152([2703] 案二):durable 部署上的 AskUserQuestion 门。活体面(QuestionCoordinator)缺席 ⇒ 原形
  *  `createDurableQuestionPolicy()`(恒 ask ⇒ 恒 durable park)。在场 ⇒ **判决时**按活流上下文分腿:
  *  活流腿(bg/SSE,coordinator.runWithContext 包裹且投递面此刻可达,ALS 判)allow——工具执行落到
@@ -108,7 +109,11 @@ export function createResolveSpec(ctx) {
         // allowedLanes ⇒ typed 403 `execution_lane_not_allowed`. Same caps car as the scenario ruling (zero extra
         // RTT); fail-open + audit on blip. "in-process" = fleet's REMOTE_EXEC-unset core stub lane
         // (named distinctly from the explicit `host` lane — same machine, different posture).
-        gateExecutionLane(await principalCaps?.executionRuling(auth?.principal), config.remoteExec?.provider ?? "in-process");
+        // #157 补痕交叉复审真发现(codex,2026-08-05):第三参不传就落 runtime-caps-resolver.ts 自己的私有
+        // `defaultLogger`(createLogger() 默认 minLevel="info")——与本部署真正按 config.logLevel 建的 `logger`
+        // 是两个独立实例,即便运维把 LOG_LEVEL 调到 debug 也打不到这条新增的一次性默认落痕行(补痕功能形同虚设)。
+        // 显式传本装配的真 logger,让该痕迹真的受部署日志级别管辖。
+        gateExecutionLane(await principalCaps?.executionRuling(auth?.principal), config.remoteExec?.provider ?? "in-process", logger);
         // Resolve an unknown name to "default" so the WHOLE bundle stays coherent — tools/prompt AND
         // skills/mcp fall back together. (selectScenario already falls back for tools/prompt; without
         // resolving here, skills/mcp would still be filtered by the raw unknown name → any skill/MCP tagged
@@ -559,6 +564,10 @@ export function createResolveSpec(ctx) {
             // [1144]/[1146] (core 1.328 R2): promptProfile 双形轴直通——纯呈现轴无租户门(deferTools 姿势);
             // 缺省不挂键(引擎缺省 simple);非法值由 HTTP 门 400,resume 重放 defensive DROP。
             ...(() => { const v = promptProfileFromBody(body.promptProfile); return v ? { promptProfile: v } : {}; })(),
+            // [2856]②(core 5.14.0):deferred 工具激活后的 schema 供给策略,per-task 位。core 侧读法是
+            // `spec.toolMaterializeStrategy ?? env ?? "static"` ⇒ **缺省不挂键**才能让进程级 env 继续说话;
+            // 挂一个「缺省值」上去会把 env 车道悄悄夺权。非法值由 HTTP 门 400,resume 重放 defensive DROP。
+            ...(() => { const v = toolMaterializeStrategyFromBody(body.toolMaterializeStrategy); return v ? { toolMaterializeStrategy: v } : {}; })(),
             // [922]①/[915]② (core 1.296): interactiveTools 三态旋钮直通——boolean 上 spec(壳 -p 恒 stamp false=
             // A3 类「headless 提问 park」根治腿;plan 显式 true 恒赢),undefined=core 自动判据(送达面探测)。
             // per-run 工具面选择无跨租户面 ⇒ 无租户门;非 boolean 由 HTTP 门 400,resume 重放 typeof 检查天然 DROP。
@@ -857,7 +866,8 @@ export function createResolveSpec(ctx) {
         // [820]③ scratchpadDir, hoisted from the envFacts block below so the SAME per-session dir feeds BOTH the
         // `# Environment` fact and the fs-write gate's exemptDirs (single-source path via scratchpadDirFor inside
         // ensureScratchpadDir). HOST-semantics lanes only + session required — rationale at the envFacts consumer.
-        const hostSemanticsLane = config.remoteExec === undefined || config.remoteExec.provider === "host";
+        // 判别式单一真源:补集(沙箱裁决 lane)是写门代理与工厂装饰器的挂载条件,两处各写一份正是漂移的成因。
+        const hostSemanticsLane = !isSandboxPathAdjudicationLane(config.remoteExec?.provider);
         // G3([816]③/[820]③,[1840]§四):壳供 body.scratchpadDir 优先——壳(CC 形)有自己的 per-session
         // scratchpad 约定路径,接受后事实/豁免/根围栏三处同源指向壳的目录(壳侧提示词与 server 写门不再
         // 两个 scratchpad)。验收门 fail-closed(多租户/远程 lane/浅路径全拒收,warn 后回落自算)——
@@ -870,12 +880,20 @@ export function createResolveSpec(ctx) {
         const scratchpadDir = shellScratchpad ??
             (hostSemanticsLane && auth?.sessionId ? await ensureScratchpadDir(config.localDataRoot ?? localRoot, auth.sessionId) : undefined);
         if (effectiveSettings) {
-            // [816]/[820]① fs-write gate wiring — HOST-semantics lanes only: core's createFsWriteGatePolicy
-            // canonicalizes每一个 target/dir 走给定 env 的真实 fs(exists/canonicalPath/readLink,dist 亲读),所以
-            // env 必须就是 hand 工具真正写的那块盘。e2b/k8s/ssh/adb/local-docker 的沙箱 env 由 core 在 spec 之后
-            // 才铸(executionEnvFactory),这里给 worker 本机 env 会拿错误的 fs 裁决(symlink/exists 全答错)——
-            // 沙箱 lane 诚实不挂(gate=undefined ⇒ derive 回落 base 规则,pre-[816] 行为)。
-            // NodeExecutionEnv 构造是纯字段赋值(不 spawn)。
+            // [816]/[820]① fs-write gate wiring —— 两形,按 lane 分:
+            //
+            // ① HOST-semantics lane(REMOTE_EXEC 未设或 "host"):core 的 createFsWriteGatePolicy 把每一个
+            //    target/dir 交给给定 env 的**真实 fs**(exists/canonicalPath/readLink,dist 亲读),所以 env 必须
+            //    就是 hand 工具真正写的那块盘 —— 这里给 worker 本机的 NodeExecutionEnv(构造是纯字段赋值,不 spawn)。
+            //
+            // ② 沙箱 lane(e2b/k8s/ssh/adb/local-docker,#165):沙箱 env 由 core 在 spec **之后**才铸
+            //    (executionEnvFactory),spec 期把 worker 本机 env 递进去会拿**别人机器上的 fs 事实**裁决
+            //    (symlink/exists 全答错),而错误的 allow 比没有门更糟。解法是把「取 env」推迟到裁决时刻:
+            //    `DeferredSandboxPathEnv` 是个代理,per-session slot 由工厂装饰器在铸 env 时填(boot/execution-env.ts
+            //    链尾),写门每次 canonicalize 都转发那台**真沙箱**的 exists/canonicalPath/fileInfo/readLink。
+            //    唯一不转发的是 `absolutePath`(相对路径基准之争,理由在下面那条臂与代理模块的文件头)。
+            //    cwd 仍不铸 ⇒ 无 acceptDirs、相对路径恒 ask;scratchpad 豁免按 host 同形补回(真 canonicalize
+            //    在场,软链逃逸形会落回真身裁决)。sensitivePatterns 的 deny 腿与 isExempt 会话豁免探针照常施加。
             //
             // 修5(三路复审 W4,cwd 基准漂移):gate 的 cwd 基准=与 hands 真跑处同源,分三形:
             //  · session 注册过 cwd(cwdHonored 已在注册处把关)⇒ 用它——与 host factory 的 effectiveHostWorkspace
@@ -887,6 +905,32 @@ export function createResolveSpec(ctx) {
             //    (hand 工具的书面契约形)与 scratchpad exempt 均不受影响。
             //  · provider 未设(in-process host / run-local)⇒ hands 就在本进程 cwd 跑(无 factory),process.cwd()
             //    正是真工作目录,保留。
+            // 两形**共有**的两件(都与 env/cwd 无关,故不随 lane 分叉——单一属主,两臂各抄一份正是漂移的成因):
+            const gateCommon = {
+                // ③ (core 1.295) sensitive-path write deny set:组合进 gate 腿的同一 combinePolicies 折叠
+                // (deny 恒赢 —— 豁免/acceptDirs 越不过;集合取舍 core 成文,server 只透传 config 旋钮:
+                // 缺省 = core RECOMMENDED_SENSITIVE_PATTERNS,SENSITIVE_WRITE_PATTERNS 显式替换/off 关闭)。
+                // 沙箱 lane 上它按**词法** key 的路径段匹配(#156)——glob 本就只看段名,不需要真 fs。
+                ...(config.sensitiveWritePatterns.length > 0 ? { sensitivePatterns: config.sensitiveWritePatterns } : {}),
+                // [1557]§四 的 shellGate 旧家已随 #153 搬到 applyRuntimeGovernance(governance 层无条件施加,
+                // 见上方 governedBase)——wiring 不再承运该旋钮,FsWriteGateWiring.shellGate 字段一并拆除。
+                // [841]① / core 1.294 exemption seam:gate 产 ask 前查同一只 approval_exemption 店(与 decide
+                // remember="session" 的授予、ask 政策层探针同店同 canonical toolName 键空间)——「本会话不再询问」
+                // 对 fs-write 门同 turn 即时生效(父+继承子任务,ask 路径不再重入)。has() reject ⇒ core 按
+                // 未豁免处理(fail-closed 照 ask),与店契约的调用方纪律一致;命中打 info 审计(对齐
+                // approval_exempted 的短路留痕,不记路径,路径留在 core 的 allow message 里)。探针是 name-keyed
+                // 的(不做任何 fs 裁决),所以沙箱 lane 照接不误。
+                ...(approvalExemptionStore && auth?.sessionId
+                    ? {
+                        isExempt: async (toolName) => {
+                            const hit = await approvalExemptionStore.has(auth.sessionId, toolName);
+                            if (hit)
+                                logger.info("fs_write_gate_exempted", { toolName, sessionId: auth.sessionId });
+                            return hit;
+                        },
+                    }
+                    : {}),
+            };
             const fsWriteGate = hostSemanticsLane
                 ? (() => {
                     const sessionCwd = auth?.sessionId ? effectiveHostWorkspace(perSessionCwd.get(auth.sessionId), {}) : undefined;
@@ -898,32 +942,52 @@ export function createResolveSpec(ctx) {
                         env: new NodeExecutionEnv({ cwd: gateCwd }),
                         cwd: gateCwd,
                         ...(scratchpadDir ? { scratchpadDir } : {}),
-                        // ③ (core 1.295) sensitive-path write deny set:组合进 gate 腿的同一 combinePolicies 折叠
-                        // (deny 恒赢 —— 豁免/acceptDirs 越不过;集合取舍 core 成文,server 只透传 config 旋钮:
-                        // 缺省 = core RECOMMENDED_SENSITIVE_PATTERNS,SENSITIVE_WRITE_PATTERNS 显式替换/off 关闭)。
-                        ...(config.sensitiveWritePatterns.length > 0 ? { sensitivePatterns: config.sensitiveWritePatterns } : {}),
-                        // [1557]§四 的 shellGate 旧家已随 #153 搬到 applyRuntimeGovernance(governance 层无条件施加,
-                        // 见上方 governedBase)——wiring 不再承运该旋钮,FsWriteGateWiring.shellGate 字段一并拆除。
-                        // [841]① / core 1.294 exemption seam:gate 产 ask 前查同一只 approval_exemption 店(与 decide
-                        // remember="session" 的授予、ask 政策层探针同店同 canonical toolName 键空间)——「本会话不再询问」
-                        // 对 fs-write 门同 turn 即时生效(父+继承子任务,ask 路径不再重入)。has() reject ⇒ core 按
-                        // 未豁免处理(fail-closed 照 ask),与店契约的调用方纪律一致;命中打 info 审计(对齐
-                        // approval_exempted 的短路留痕,不记路径,路径留在 core 的 allow message 里)。
-                        ...(approvalExemptionStore && auth?.sessionId
-                            ? {
-                                isExempt: async (toolName) => {
-                                    const hit = await approvalExemptionStore.has(auth.sessionId, toolName);
-                                    if (hit)
-                                        logger.info("fs_write_gate_exempted", { toolName, sessionId: auth.sessionId });
-                                    return hit;
-                                },
-                            }
-                            : {}),
+                        ...gateCommon,
                     };
                 })()
-                : undefined;
-            // [1248]②/codex F2 — the workflow ask leg's session-exemption probe, on EVERY lane (unlike fsWriteGate:
-            // the workflow gate is name-keyed, not fs-adjudicated). Same store + canonical toolName key space as the
+                : // 沙箱 lane(#165):裁决 env = `DeferredSandboxPathEnv` 代理 —— 裁决时刻(必在 prepare 之后)
+                    // 去 per-session slot 里取本 task 的**真沙箱 env**,转发 exists/canonicalPath/fileInfo/readLink。
+                    // 于是绝对路径的 symlink 真身、存在性都是真沙箱 fs 的事实,域内软链指向守卫段照样 deny;
+                    // slot 空/歧义 ⇒ 转发面报错 ⇒ core 判 `unresolvedSymlink` ⇒ 写门 ask + sensitive deny(fail-closed)。
+                    //
+                    // **`cwd` 仍不给**(显式裁定,非过渡欠款):`cwd` 同时是 core 的 `rootPath`(相对路径基准)与
+                    // acceptEdits 的 accept 域。沙箱里那个基准是 engine 跟踪的 cwd,不是 env 自己的 cwd,server 侧要
+                    // 铸它得先建一个 per-task 跟踪面——那是独立一件(与 host 臂哨兵同族的漂移风险)。后果:相对路径
+                    // 恒 ask,acceptEdits 在沙箱 lane 与 default 同形(全 ask),fail-safe 方向。
+                    //
+                    // **scratchpad 豁免按 host 同形补回**:`/tmp/scratchpad/<sessionId>`(remote-scratchpad.ts 单一
+                    // 真源,e2b/k8s/local-docker/ssh 四 lane;adb 无此约定故无豁免)。#156 当年不豁免是因为词法版
+                    // 看不见软链——域内一个指向域外的软链会被判成域内;现在 exemptDirs 与写目标两侧都过真
+                    // canonicalize,逃逸形会解出域外真身而落回真身裁决,host lane 的同一保证在这里成立了。
+                    // 注:远程 lane 的**根围栏**admit 走的是 core 对 `spec.envFacts.scratchpadDir` 的自建根(prepare 期
+                    // canonicalize/实体化),而那条事实在 `SANDBOX_ENV_FACTS=false` 下不发——那种配置里根围栏先拒,
+                    // 本豁免够不着(方向更严,不是放行面);host 臂的 additionalDirectories 折叠不受影响。
+                    (() => {
+                        const sandboxScratchpadDir = isRemoteScratchpadLane(config.remoteExec?.provider) ? remoteScratchpadDirFor(auth?.sessionId) : undefined;
+                        return {
+                            env: new DeferredSandboxPathEnv({
+                                sessionId: auth?.sessionId,
+                                slots: sandboxPathEnvSlots,
+                                logger: { warn: (event, fields) => logger.warn(event, { ...(fields ?? {}), lane: config.remoteExec?.provider }) },
+                            }),
+                            ...gateCommon,
+                            ...(sandboxScratchpadDir ? { scratchpadDir: sandboxScratchpadDir } : {}),
+                            // codex 复审 B(2026-08-05,dist 亲读+实测):core 的 canonicalizeTarget 把反斜杠 UNC 形在**入口**
+                            // 短路成 ok:true/key=原样——不经本 env,canon 便「成功」,gate 随后就咨询豁免探针;name-keyed
+                            // 命中即 allow,「非 POSIX 绝对形一律 ask」就被豁免会话越过(相对形/盘符形没这个洞:它们的
+                            // canon 失败先于豁免咨询)。沙箱臂因此给探针加 canonical-key 守门:只有 `/` 开头(=真经过本
+                            // 代理的路径面)的 key 才享豁免,其余落回 defaultWrite 的 ask。host 臂不加
+                            // (真 fs canonicalize 的 key 可信,[841]① 原契约不动)。
+                            ...(gateCommon.isExempt
+                                ? {
+                                    isExempt: (toolName, canonicalPath) => canonicalPath.startsWith("/") ? gateCommon.isExempt(toolName) : false,
+                                }
+                                : {}),
+                        };
+                    })();
+            // [1248]②/codex F2 — the workflow ask leg's session-exemption probe. Name-keyed and never fs-adjudicated,
+            // so it was on EVERY lane from day one (the fs gate has been too since #156, by a different route: a
+            // lane-specific adjudication env rather than no gate). Same store + canonical toolName key space as the
             // fs-gate probe — one remember="session" grant serves both; without it the durable lane re-parks every
             // later run_workflow call after an operator already granted "don't ask again this session".
             const workflowGate = approvalExemptionStore && auth?.sessionId

package/dist/capabilities/center-prompts.js

@@ -22,6 +22,7 @@
 import { verifyPromptArtifact } from "@sema-agent/core";
 import { CORE_ENGINE_VERSION } from "../prompts-domain-validate.js";
 import { SHA256_HEX_RE } from "../digest-form.js";
+import { recordFailOpen } from "../observability/fail-open.js";
 /** 判形半场(validateCenterPrompts/validatePromptsDomain/CORE_ENGINE_VERSION 及两 interface)已下沉到
  *  中立叶子 `src/prompts-domain-validate.ts`(design/158 S6);消费者直引真源([2354] 兼容面全清,
  *  此处兼容 re-export 已删)。 */
@@ -56,7 +57,9 @@ export function withPromptArtifactBackfill(inner, fetchRaw, log) {
                         log.warn("center_prompts_backfill_rejected", { digest: canonical, ...(v.ok ? { got: v.artifact.artifactDigest, code: "digest_mismatch" } : { code: v.code, reason: v.reason }) });
                         return undefined;
                     }
-                    await inner.put(raw).catch(() => undefined); // cache best-effort
+                    // cache best-effort —— #157:F 类兜底(工件已验签且已返回;失败的代价只是下次再取一次网络),
+                    // 留痕是为了让"缓存其实一直没写成"不必靠回填流量异常来发现。
+                    await inner.put(raw).catch(() => recordFailOpen("server.prompts.artifact-cache-write-failed", `digest=${canonical}`));
                     log.info("center_prompts_backfilled", { digest: canonical });
                     return raw;
                 }

package/dist/capabilities/oa-tools.d.ts

@@ -0,0 +1,15 @@
+import type { ToolSpec } from "@sema-agent/core";
+/**
+ * OA scenario — tools are thin HTTP clients to the OA backend's existing APIs (read = /api/v1/*,
+ * write = /api/assets/*). The shared service token + the request's principal are forwarded so OA
+ * enforces THAT end-user's RBAC + audit (the service never holds per-user creds). Decoupled: the
+ * service knows no OA schema/DB — OA stays the source of truth (its /api/v1/meta is self-describing).
+ */
+export interface OaCtx {
+    baseUrl: string;
+    token: string;
+    principal?: string;
+}
+export declare function oaTools(ctx: OaCtx): ToolSpec[];
+export declare const oaPrompt: import("@sema-agent/core").PromptProvider;
+//# sourceMappingURL=oa-tools.d.ts.map