@sema-agent/server 2.0.0 → 2.0.1

package/dist/boot/leader.js

@@ -0,0 +1,81 @@
+import { createLeaderEndpoint } from "../leader/endpoint.js";
+import { createLeaderRunner } from "../leader/wire.js";
+export function createLeaderFace(ctx) {
+    const { config, logger, brain, pricing, executionEnvFactory, toolResultStore, sessionStore, checkpointStore } = ctx;
+    // v2 leader endpoint (design/50 + design/68): wire when LEADER_ENABLED + an isolated remote-exec backend
+    // (E2B or k8s/Kata — SSH/ADB are single-worker real-system backends, not fan-out targets). Default off →
+    // zero prod impact. 🔴 a real run also needs `git` on the host PATH + a durable remote with write creds.
+    // F2(a) factory mode (preferred) = the service's executionEnvFactory + MinIO self-upload diff-out; the k8s
+    // lane REQUIRES it (no static k8s mode). E2B without MinIO falls back to the static compat mode.
+    const leaderMinio = process.env.MINIO_ENDPOINT && process.env.MINIO_ACCESS_KEY && process.env.MINIO_SECRET_KEY
+        ? {
+            s3: {
+                endpoint: process.env.MINIO_ENDPOINT,
+                bucket: process.env.MINIO_BUCKET ?? "workspaces",
+                accessKey: process.env.MINIO_ACCESS_KEY,
+                secretKey: process.env.MINIO_SECRET_KEY,
+                ...(process.env.MINIO_REGION ? { region: process.env.MINIO_REGION } : {}),
+            },
+        }
+        : {};
+    const leaderProvider = config.remoteExec?.provider;
+    // DUAL-MODE §5: orchestration is an ENGINE capability, not fleet-only — the TOC `host` lane runs leader fan-out
+    // bounded by ONE box (isolation=none, NON-durable: no snapshot, so the durable sub-worker suspend block below is
+    // skipped — host workers run to completion in-process-adjacent). e2b/k8s keep their isolated/suspendable posture.
+    const leaderEndpoint = config.leaderEnabled &&
+        (leaderProvider === "e2b" ||
+            (leaderProvider === "k8s" && "s3" in leaderMinio && executionEnvFactory) ||
+            (leaderProvider === "host" && executionEnvFactory))
+        ? createLeaderEndpoint(createLeaderRunner({
+            brain, models: config.models, roles: config.roles, pricing, logger,
+            fanoutEnabled: config.leaderFanoutEnabled,
+            // Route the single-vs-fanout classification on the cheap model (deepseek-v4-flash): the heavy
+            // reasoning worker model returns empty ~2/3 of the time on the route prompt → silent collapse to
+            // single (observed 2026-06-14). MODEL_ROUTER_ID overrides; else the cheap model; else default.
+            ...((process.env.MODEL_ROUTER_ID || process.env.MODEL_CHEAP_ID)
+                ? { routerModel: (process.env.MODEL_ROUTER_ID || process.env.MODEL_CHEAP_ID) }
+                : {}),
+            ...(leaderProvider === "e2b" ? { e2bApiKey: config.remoteExec.apiKey } : {}),
+            ...(executionEnvFactory ? { envFactory: executionEnvFactory } : {}),
+            ...leaderMinio,
+            // Durable offload store for sub-worker tool results — without it core REFUSES the durable
+            // suspend (InMemory offload would not survive a cross-replica resume) and the gated call is
+            // denied via the unwired onAsk fallback → the worker fails instead of suspending (drill c3).
+            ...(toolResultStore ? { toolResultStore } : {}),
+            // k8s lane: align the wire's workspace with the adapter's durable-snapshot root (/workspace) —
+            // the E2B default (/home/user) is OUTSIDE the k8s suspend tar, so a suspended sub-worker's repo
+            // would silently vanish on resume (drill c3: 105-byte empty snapshots).
+            ...(leaderProvider === "k8s" ? { workspace: "/workspace" } : {}),
+            // Same store as the main runner: a suspended sub-worker's session must be readable on /decide
+            // resume (sub-runner-local in-memory sessions die with "Entry <leafId> not found" on resume).
+            sessionStore,
+            // design/68 C4: sub-workers can durably suspend when the service runs durable approvals.
+            ...(checkpointStore && config.approvalRequire.length > 0
+                ? {
+                    durable: {
+                        checkpointStore,
+                        requireApproval: config.approvalRequire,
+                        deny: config.approvalDeny,
+                        // design/80: the leader's orchestrated sub-agents adopt the SAME supervisor loop as the
+                        // top-level agent — the D-E auto-budget (auto-approve NORMAL asks up to the budget, then
+                        // escalate) + the never-auto safety set. Without these a sub-agent's gated ask always
+                        // suspends-to-human, defeating the budget circuit-breaker for the supervised team.
+                        autoBudget: config.approvalAutoBudget,
+                        neverAuto: config.approvalNeverAuto,
+                        ...(config.approvalTimeoutSec > 0 ? { ttlMs: config.approvalTimeoutSec * 1000 } : {}),
+                    },
+                }
+                : {}),
+        }), {
+            logger,
+            // SDK 全量核查(2026-07-24,黑板 GD 组)撞获:wire.ts:368 的 runLeader 实际要求这五个字段全部
+            // 非空,此前同步门只查 objective,不完整请求会先拿到 202 再在后台必然失败——同步前移,让错误
+            // 尽早暴露而不是靠后续 GET 才发现。
+            requiredFields: ["objective", "durableRemote", "testCmd", "seedCmd", "baseSha"],
+        })
+        : undefined;
+    if (leaderEndpoint)
+        logger.info("leader_endpoint_enabled", { provider: leaderProvider, mode: "s3" in leaderMinio ? "factory" : "static" });
+    return leaderEndpoint;
+}
+//# sourceMappingURL=leader.js.map

package/dist/boot/reapers.d.ts

@@ -0,0 +1,53 @@
+/**
+ * design/158 A10:composition root 分段 —— 后台 reaper / 维护 tick。
+ *
+ * 纯搬运:函数体逐字来自 `main.ts`(原 2387-2599 行),缩进不变;新增的只有 import 与
+ * `startReapers(ctx)` 包壳。
+ *
+ * ⚠️ **位置即契约**:
+ *  1. 本段必须在 `createHttpServer` **之前**调用 —— D-D SLA-timer 的 deny-sweep 是 server 造出来的,
+ *     故经 `getRunDenySweep()` 晚绑(`let runDenySweep` 仍留在 main.ts,赋值点仍在 server 之后)。
+ *     这是本次搬运里**唯一**一行改写(`runDenySweep?.(…)` → `getRunDenySweep()?.(…)`)。
+ *  2. `reaper.unref?.()` 必须紧跟 `setInterval`(定时器绝不可持住进程),故一并搬进本函数、
+ *     返回值只交出 handle 给收尾段 `clearInterval`。
+ *  3. tick 内各腿的**相对次序**逐字保留:probeClockSkew(时钟指纹)先于任何按本地时钟分桶的清算。
+ */
+import { Runner, type RunnerDeps, type WorkflowRunStore } from "@sema-agent/core";
+import type { ServiceConfig } from "../config.js";
+import { CostQuota } from "../observability/cost-quota.js";
+import type { RateLimiter } from "../observability/rate-limit.js";
+import type { Logger } from "../observability/logger.js";
+import type { Metrics } from "../observability/metrics.js";
+import type { WorkflowNotifyGate, WorkflowNotifyJournalStore } from "../orchestration/workflow-notify-journal.js";
+import type { TaskAttachmentStore } from "../plugins/task-attachment-store.js";
+import type { ApprovalStore, CheckpointStoreFull, CostQuotaStore, ImageBake, RateLimiterStore, ServiceWorkflowJournalStore, StoreBackend, ToolResultStoreFull } from "../plugins/store-backend.js";
+export interface ReapersCtx {
+    config: ServiceConfig;
+    logger: Logger;
+    metrics: Metrics;
+    localRoot: string;
+    backend: StoreBackend | undefined;
+    subRunner: Runner;
+    runStore: ReturnType<StoreBackend["run"]> | undefined;
+    checkpointStore: CheckpointStoreFull | undefined;
+    approvalStore: ApprovalStore | undefined;
+    rateLimiter: RateLimiter | RateLimiterStore | undefined;
+    costQuota: CostQuota | CostQuotaStore | undefined;
+    toolResultStore: ToolResultStoreFull | undefined;
+    fileSnapshotStore: ReturnType<StoreBackend["fileSnapshot"]> | undefined;
+    taskAttachmentStore: TaskAttachmentStore | undefined;
+    imageBakes: ImageBake | undefined;
+    worktreeReap: (() => Promise<void>) | undefined;
+    workflowNotifyGate: WorkflowNotifyGate | undefined;
+    workflowJournalStore: ServiceWorkflowJournalStore | undefined;
+    sqlWorkflowRunStore: WorkflowRunStore | undefined;
+    workflowNotifyJournal: WorkflowNotifyJournalStore | undefined;
+    rosterStore: RunnerDeps["rosterStore"];
+    backgroundAgentStore: RunnerDeps["backgroundAgentStore"];
+    mailboxStore: RunnerDeps["mailboxStore"];
+    /** 晚绑(server 造出来才有)——见文件头「位置即契约」①。 */
+    getRunDenySweep: () => ((now: number) => Promise<void>) | undefined;
+}
+/** 起后台维护 tick,返回定时器 handle(收尾段 clearInterval 用)。 */
+export declare function startReapers(ctx: ReapersCtx): NodeJS.Timeout;
+//# sourceMappingURL=reapers.d.ts.map

package/dist/boot/reapers.js

@@ -0,0 +1,252 @@
+/**
+ * design/158 A10:composition root 分段 —— 后台 reaper / 维护 tick。
+ *
+ * 纯搬运:函数体逐字来自 `main.ts`(原 2387-2599 行),缩进不变;新增的只有 import 与
+ * `startReapers(ctx)` 包壳。
+ *
+ * ⚠️ **位置即契约**:
+ *  1. 本段必须在 `createHttpServer` **之前**调用 —— D-D SLA-timer 的 deny-sweep 是 server 造出来的,
+ *     故经 `getRunDenySweep()` 晚绑(`let runDenySweep` 仍留在 main.ts,赋值点仍在 server 之后)。
+ *     这是本次搬运里**唯一**一行改写(`runDenySweep?.(…)` → `getRunDenySweep()?.(…)`)。
+ *  2. `reaper.unref?.()` 必须紧跟 `setInterval`(定时器绝不可持住进程),故一并搬进本函数、
+ *     返回值只交出 handle 给收尾段 `clearInterval`。
+ *  3. tick 内各腿的**相对次序**逐字保留:probeClockSkew(时钟指纹)先于任何按本地时钟分桶的清算。
+ */
+import { Runner, defaultTaskRegistry } from "@sema-agent/core";
+import { sweepStaleScratchpads } from "../env-facts.js";
+import { CostQuota } from "../observability/cost-quota.js";
+/** 起后台维护 tick,返回定时器 handle(收尾段 clearInterval 用)。 */
+export function startReapers(ctx) {
+    const { config, logger, metrics, localRoot, backend, subRunner, runStore, checkpointStore, approvalStore, rateLimiter, costQuota, toolResultStore, fileSnapshotStore, taskAttachmentStore, imageBakes, worktreeReap, workflowNotifyGate, workflowJournalStore, sqlWorkflowRunStore, workflowNotifyJournal, rosterStore, backgroundAgentStore, mailboxStore, 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).
+    const reapCount = (metric, labels) => (n) => {
+        if (typeof n === "number" && n > 0) {
+            metrics.inc(metric, labels, n);
+            logger.info("reaper_swept", { metric, ...labels, count: n });
+        }
+    };
+    let wfRunReapInFlight = false; // 1.108 review (lens③): serialize the all-scopes retention sweep across ticks
+    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 重入守卫(同上三个邻居——见下方调用点注释)
+    // 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 双实现
+    // 都带)——1.248 拍的「file 腿只扫 default」假设已撤;无该方法的第三方 store 仍回落 "default"(可选
+    // 接口成员,诚实回落)。
+    // sessions=subRunner.sessions —— [1522] 裁定件(③ 显式裁定形,双店真相考据后拍):bg 子代转录会话
+    // 是**双店**(ForkRoutingSessionStore):①非 fork 子代铸在 transient 店(TtlSessionStore,进程内
+    // 1h TTL)——release=内存删=**真正终结可寻址性**(转录本就不 durable;跨实例读面读的是行内
+    // finalOutput,非转录);②fork 子代铸在 host durable 店——release=lease 释放,durable 转录行**有意
+    // 保留**,留存归 session 留存策略/E21 purge 生命周期管(行先删可接受:行是执行记录,转录是会话资产,
+    // 两者生命周期本就不同)。core [1522] 复审只见 durable 腿判 HIGH——按其契约句「做不到终结可寻址性
+    // 宁可不传」,transient 类做得到、fork 类是显式裁定,维持传入。sessionsReleased 计数=「store 侧
+    // release 被调次数」(transient=真删,durable=lease 释放),非「durable 转录处置数」——如实注。
+    // 复审 F4 如实注:条件删的赢者若非写者副本,fork-routing 对未知 id 回落 transient=本地 no-op,写者
+    // 进程内 pinned 转录滞留到自身 TTL/进程退出——sessionsReleased 计数偏低是诚实读数,非缺陷。
+    const reapBgAgents = backgroundAgentStore
+        ? async () => {
+            const store = backgroundAgentStore;
+            const scopes = await (store.listScopes?.() ?? Promise.resolve(["default"]));
+            let rows = 0, sessions = 0, skipped = 0, failedScopes = 0;
+            for (const scope of scopes) {
+                // [1522] LOW3:per-scope 错误隔离——一个 scope 抛(坏 record_json/权限)不饿死后续 scope;
+                // 失败响亮(warn+计数),下 tick 重试。
+                try {
+                    // core 1.382([1561] 提货单④,design/153 parked 状态机对账):先对账 parked 行(checkpoint
+                    // expired/missing → 行诚实翻 failed;stale claim → 回滚 parked),再让下面既有的
+                    // reapDurableAgents 按自然节奏处置(刚翻 failed 的行本 tick 不会立刻被 maxAge 删——它是
+                    // "刚失败"的新行,不是"失败很久"的老行)。**走 registry 面**(裂脑 fence 内建于
+                    // TaskRegistry.reconcileParkedAgents 内部,不裸调 store 面——那是无活实例场景专用,core
+                    // [1561]④ 措辞)。仅在 checkpointStore 真在场时跑(同 [1561]①②「同车必接」判据——没有
+                    // checkpointStore 就不可能有真正 parked 的行,调用本身没有意义)。
+                    // 🔴 [1575] F1 修(cli 复查,红先行确认):`opts.staleClaimMaxAgeMs` 必须显式传——core 把
+                    // 整个 stale-claim 清算块(claimer 崩死回滚 + resolved-未-finalize 诚实翻 failed)门在
+                    // `staleMs !== undefined` 上,缺席不是"跳过 stale-claim 这一小步",是**整块永不运行**
+                    // (此前漏传,`bg_agents_park_reconciled_rolledback_total` 恒 0,人已做出的审批决定会被
+                    // 静默丢弃——见 config.ts backgroundAgentParkClaimStaleMs 顶注)。
+                    if (checkpointStore) {
+                        const pr = await defaultTaskRegistry.reconcileParkedAgents({ agentStore: store, checkpointStore }, scope, Date.now(), { staleClaimMaxAgeMs: config.backgroundAgentParkClaimStaleMs });
+                        if (pr.failed > 0 || pr.rolledBack > 0) {
+                            metrics.inc("bg_agents_park_reconciled_failed_total", {}, pr.failed);
+                            metrics.inc("bg_agents_park_reconciled_rolledback_total", {}, pr.rolledBack);
+                            logger.info("reaper_swept", { metric: "bg_agents_park_reconciled", scope, failed: pr.failed, rolledBack: pr.rolledBack });
+                        }
+                    }
+                    // deps.mailbox(core 1.374,[1533]②):行删联动 F-13——agent 行 reap 时同 drop 其信箱
+                    // (盒生命周期随行终结;不挂=信箱行无 retention 无界涨)。
+                    const r = await defaultTaskRegistry.reapDurableAgents(scope, { store, sessions: subRunner.sessions, ...(mailboxStore ? { mailbox: mailboxStore } : {}) }, {
+                        maxAgeMs: config.backgroundAgentRetentionMs,
+                        staleRunningMaxAgeMs: config.backgroundAgentStaleRunningMs,
+                    });
+                    rows += r.rowsReaped;
+                    sessions += r.sessionsReleased;
+                    skipped += r.skippedNoSessions;
+                }
+                catch (err) {
+                    failedScopes++;
+                    logger.warn("bg_agent_reap_scope_failed", { scope, err: err instanceof Error ? err.message : String(err) });
+                }
+            }
+            if (failedScopes > 0)
+                metrics.inc("bg_agent_reap_scope_failures_total", {}, failedScopes);
+            if (rows > 0 || sessions > 0) {
+                metrics.inc("bg_agents_reaped_total", {}, rows);
+                logger.info("reaper_swept", { metric: "bg_agents_reaped_total", count: rows, sessionsReleased: sessions, skippedNoSessions: skipped });
+            }
+        }
+        : undefined;
+    // S10 (SILENT-FALLBACK P1): the write-behind counters bucket on LOCAL floor(now/windowMs) — replica clock
+    // skew vs the DB splits a fleet window into disjoint buckets (soft-limit leak) with zero visibility. Probe
+    // the DB clock each reaper tick; the gauge is the fleet-wide skew fingerprint (can be negative).
+    const probeClockSkew = async () => {
+        // Probe-ok gauge: a failing probe froze the skew gauge at its last value with zero signal —
+        // "probe ran, skew=N" vs "probe failing for 30 min" were indistinguishable.
+        try {
+            const dbMs = await backend?.dbNowMs?.();
+            if (typeof dbMs === "number" && Number.isFinite(dbMs)) {
+                metrics.setGauge("fleet_counter_bucket_skew_ms", dbMs - Date.now());
+                metrics.setGauge("fleet_clock_probe_ok", 1);
+            }
+        }
+        catch {
+            metrics.setGauge("fleet_clock_probe_ok", 0);
+        }
+    };
+    const reaper = setInterval(() => {
+        void probeClockSkew().catch(() => undefined); // S10
+        void runStore?.reapStale(config.runStaleSec * 1000).then(reapCount("runs_reaped_total", { kind: "stale" })).catch(() => undefined);
+        // 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,
+        // REGARDLESS of APPROVAL_TIMEOUT_SEC — terminal_at (stamped at put, never before an explicit deadline)
+        // bounds even a NULL-deadline pending checkpoint, so the backstop is the always-on safety net (it was
+        // inert when nested under the approvalTimeoutSec>0 guard — adversarial finding). The run-row half is
+        // checkpoint-STATE-driven (not a uniform timer) so it aligns with the per-row terminal_at. Global +
+        // idempotent across replicas, no election.
+        if (checkpointStore) {
+            // 轴A #5 注释落档(1.254):core CheckpointStore.reap 契约把弃置臂的 unpin 义务派给部署 reaper——
+            // 真 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);
+            // 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?.`)
+        }
+        // The finer, OPT-IN per-approval TTL sweeps (APPROVAL_TIMEOUT_SEC): the F4 poll-gate store + the
+        // time-based suspended-run reaper. Stay 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.
+        if (config.approvalTimeoutSec > 0) {
+            void approvalStore?.expireStale(config.approvalTimeoutSec * 1000).catch(() => undefined);
+            void runStore?.reapSuspended(config.approvalTimeoutSec * 1000).then(reapCount("runs_reaped_total", { kind: "suspended" })).catch(() => undefined);
+        }
+        // GC checkpoint_ctx rows whose checkpoint is gone (bound to the checkpoint lifecycle).
+        void checkpointStore?.reapCtx(Date.now() - config.runStaleSec * 1000).catch(() => undefined);
+        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)
+        // 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);
+        // 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);
+        // D-1 孤儿**对象**彻底 GC(clay 拍 2026-07-28):对象存储 × meta 行对账,grace 默认 1h(上传先行窗
+        // 保护;`ATTACHMENT_ORPHAN_GRACE_MS=0` 关掉本腿——同 tick 邻居都有旋钮,复审 F10)。
+        // 列举失败=本轮 warn 跳过(「列不出来」绝不当「没有孤儿」),下轮再试。
+        // 🔴 复审 F1:必须 in-flight 守卫——本腿时长随对象总数增长(20 万对象实测秒级、百万级可达 30s),
+        // 无守卫时超过 tick 间隔即逐 tick 叠加(实测叠 6 层),同时压 LIST/SQL/DELETE 三面。邻居
+        // wfRunReap/bgAgentReap 都有同款守卫。
+        if (config.attachmentOrphanGraceMs > 0 && !attachmentSweepInFlight && taskAttachmentStore?.sweepOrphanObjects) {
+            attachmentSweepInFlight = true;
+            void taskAttachmentStore
+                .sweepOrphanObjects(config.attachmentOrphanGraceMs)
+                .then((n) => { if (n > 0) {
+                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) }))
+                .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);
+        // 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);
+        // 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.
+        // 🔴 A10 留档发现①(review 2026-07-29):必须 in-flight 守卫——`git worktree prune` 随仓内 worktree
+        // 总数/子代并发度增长可变慢,无守卫时超过 tick 间隔即在下一 tick 被重入叠跑(邻居
+        // attachmentSweep/wfRunReap/bgAgentReap 三个 sweep 都已有同款守卫,此腿此前是唯一漏配的)。
+        // 照抄 bgAgentReap 的 in-flight + finally 释放形。
+        if (worktreeReap && !worktreeReapInFlight) {
+            worktreeReapInFlight = true;
+            void worktreeReap().catch(() => undefined).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);
+        // 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);
+        // 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
+        // keep-everything posture). Running rows are untouched — the orphan-grace sweep above owns those.
+        // In-flight guard (1.108 review, lens③): the sweep enumerates EVERY scope serially — under a short
+        // REAP_INTERVAL_SEC + many scopes, overlapping sweeps would pile up on the pool. One at a time.
+        if (!wfRunReapInFlight) {
+            const sweep = sqlWorkflowRunStore?.reapAllScopes?.(Date.now(), { maxAgeMs: config.workflowRunRetentionMs });
+            if (sweep) {
+                wfRunReapInFlight = true;
+                void sweep.catch(() => undefined).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);
+        }
+        // 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));
+        }
+        // [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);
+        // 修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 文案即如此宣示)。
+        if (config.scratchpadSweepTtlMs > 0) {
+            void sweepStaleScratchpads(config.localDataRoot ?? localRoot, { olderThanMs: config.scratchpadSweepTtlMs })
+                .then((removed) => {
+                if (removed > 0)
+                    logger.info("scratchpads_swept", { removed });
+            })
+                .catch(() => undefined);
+        }
+    }, config.reapIntervalSec * 1000);
+    reaper.unref?.();
+    return reaper;
+}
+//# sourceMappingURL=reapers.js.map

package/dist/boot/resolve-spec.d.ts

@@ -0,0 +1,70 @@
+import { type MemoryBackend, type RunnerDeps } from "@sema-agent/core";
+import { type PromptsDomainFaces } from "../capabilities/center-prompts.js";
+import { SessionEnvironmentSelection, selectEnvironmentTool } from "../capabilities/select-environment-tool.js";
+import { sendUserFileTool } from "../capabilities/send-user-file-tool.js";
+import { selectScenario } from "../capabilities/scenarios.js";
+import type { ServiceConfig } from "../config.js";
+import { FleetEventBus } from "../fleet/fleet-bus.js";
+import { type HookLlmCall } from "../hooks/hook-runner.js";
+import type { createHookLlm } from "../hooks/hook-llm.js";
+import { type ServiceDeps } from "../http/server.js";
+import type { createKeyResolver } from "../key-resolver.js";
+import type { Logger } from "../observability/logger.js";
+import type { Metrics } from "../observability/metrics.js";
+import { PerTaskImageRegistry } from "../per-task-image.js";
+import type { StoreBackend } from "../plugins/store-backend.js";
+import { type TaskAttachmentStore } from "../plugins/task-attachment-store.js";
+import { type createPrincipalEntitlementsClient } from "../runtime-caps-resolver.js";
+import { type OwnerAwareSessionStore } from "../security.js";
+type PrincipalCaps = ReturnType<typeof createPrincipalEntitlementsClient>;
+/** `resolveSpec` 原先从 `main()` 闭包里拿到的全部 boot 局部量。 */
+export interface ResolveSpecCtx {
+    config: ServiceConfig;
+    logger: Logger;
+    metrics: Metrics;
+    localRoot: string;
+    scenarios: Record<string, ReturnType<typeof selectScenario>>;
+    principalCaps: PrincipalCaps | undefined;
+    centerRuntimeCapsResolver: PrincipalCaps["resolveRuntimeCaps"] | undefined;
+    /** 活引用(adoptCenterPrompts 每次采用换引用)—— 见文件头「位置即契约」。 */
+    getCenterPrompts: () => PromptsDomainFaces | undefined;
+    /** 活引用(registry 热应用换引用)—— 见文件头「位置即契约」。 */
+    getKeyResolver: () => ReturnType<typeof createKeyResolver>;
+    taskAttachmentStore: TaskAttachmentStore | undefined;
+    perSessionCwd: Map<string, string>;
+    setSessionCwd: (sid: string, cwd: string) => void;
+    setSessionShellEnv: (sid: string, env: Record<string, string>) => void;
+    hookLlm: ReturnType<typeof createHookLlm>["hookLlm"];
+    hookAgent: HookLlmCall;
+    fleetBus: FleetEventBus;
+    hookWakeBus: {
+        deliver?: (sessionId: string, text: string) => Promise<boolean>;
+    };
+    resumeAnchorStore: ReturnType<StoreBackend["resumeAnchor"]> | undefined;
+    ownerAware: OwnerAwareSessionStore;
+    taskLimitCaps: {
+        timeoutSec: number | undefined;
+        maxOutputTokens: number | undefined;
+        maxTurns: number | undefined;
+    };
+    taskTimeoutSec: number;
+    selectEnvTool: ReturnType<typeof selectEnvironmentTool> | undefined;
+    sendUserFileToolSpec: ReturnType<typeof sendUserFileTool> | undefined;
+    memoryEngine: {
+        backend: MemoryBackend;
+        root: string;
+    } | undefined;
+    durableEnabled: boolean;
+    approvalExemptionStore: ReturnType<StoreBackend["approvalExemption"]> | undefined;
+    approvalEnabled: boolean | undefined;
+    approvalStore: ReturnType<NonNullable<StoreBackend["approval"]>> | undefined;
+    singleUserAutoAcceptBaseline: boolean;
+    checkpointStore: ReturnType<NonNullable<StoreBackend["checkpoint"]>> | undefined;
+    deploymentHooks: NonNullable<RunnerDeps["hooks"]>;
+    imageIndex: ReturnType<NonNullable<StoreBackend["imageIndex"]>> | undefined;
+    perTaskImage: PerTaskImageRegistry;
+    sessionEnvSelection: SessionEnvironmentSelection;
+}
+export declare function createResolveSpec(ctx: ResolveSpecCtx): ServiceDeps["resolveSpec"];
+export {};
+//# sourceMappingURL=resolve-spec.d.ts.map