@sema-agent/server 7.5.0 → 7.7.0

package/dist/run-local.d.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-import { type Brain } from "@sema-agent/core";
+import { type Brain, type OnAsk, type TaskSpec } from "@sema-agent/core";
+import { type ApprovalBaselineConfigView, type DeploymentGovernanceConfigView } from "./deployment-governance.js";
 import { type ServiceConfig } from "./config.js";
 import { type Logger } from "./observability/logger.js";
 /** Parsed CLI invocation. */
@@ -33,6 +34,12 @@ export interface RunLocalDeps {
     print?: (line: string) => void;
     /** stderr sink for the "you still need to set …" guidance (defaults to console.error). */
     printErr?: (line: string) => void;
+    /** design/181 件三: override the TTY detection behind the {@link createLocalApprover} seat
+     *  (defaults to `process.stdin.isTTY === true`) — lets a test drive BOTH arms deterministically. */
+    isTty?: boolean;
+    /** design/181 件三: the TTY arm's prompt (defaults to a readline `y/N` on stdin/stderr);
+     *  `signal` = core `OnAsk` 的取消(EOF/abort 决断臂见 {@link promptYesNoOnTty})。 */
+    askYesNo?: (prompt: string, signal?: AbortSignal) => Promise<boolean>;
 }
 /** Parse argv (everything AFTER `node run-local.js`). Throws a clear Error on a missing objective. */
 export declare function parseArgs(argv: string[]): RunLocalArgs;
@@ -49,6 +56,71 @@ export declare class UsageError extends Error {
  * this check in that case — the check is about a REAL run, not the assembly.
  */
 export declare function missingGatewayRequirements(config: ServiceConfig): string[];
+/** 本腿读的部署配置切面(`ServiceConfig` 结构满足;两个构造口各自的切面之和)。 */
+export interface LocalGovernanceConfigView extends DeploymentGovernanceConfigView, ApprovalBaselineConfigView {
+}
+/**
+ * design/181 件三:run-local 腿的**部署治理链装配**(#180)。
+ *
+ * 与另外两条腿(HTTP 的 `resolveSpec`、durable park 的赎回腿)装的是**同一条**链,经**同一个**构造口:
+ * 审批基线作 base 的 `toolPolicy` 座,再经**折叠属主** `applyRuntimeGovernance`(→ core `tightenTaskSpec`)
+ * 叠上部署治理段(autonomy / commandPolicy / MANUAL_MODE_SHELL_GATE / 守卫集)。本函数一条 policy 都不
+ * 自己合成。
+ *
+ * · **审批基线 = adjudicated allow-all**:一次性 CLI 没有 durable 审批设施(没有 `/decide` 腿可赎回),
+ *   所以 `createApprovalBaselinePolicy` 走 durable 缺席那一臂。它是一条**在场的** effect-aware 策略
+ *   (满足 core 的 `hasEffectAwareGate`),运维照旧用 `AUTONOMY` / `commandPolicy` / 守卫集在其上收紧。
+ * · **裁决 env 恒 host 形,锚 `workspaceDir`**:run-local 的手就跑在这台机器的这个目录上
+ *   (`--workspace` / config.d workdir / cwd 三选一,调用方已解析好),所以 `cwd` 恒在场 —— 相对形写目标
+ *   由 core 按 `rootPath` 解析进真身裁决,构造口的词法补层(沙箱腿那条)在这里自动不铺。
+ *   ✅ **旧残余面已收口(core 5.19.0 #108,2026-08-08 校正)**:`rootPath` 是装配期的**静态**值,而 core
+ *   的写工具解析相对形用的是被 Bash `cd` 就地改写的活 cwd —— 于是 `cd .git/hooks` 之后
+ *   `Write("pre-commit")` 落进守卫段却判不出来(两条 host 腿同形,本腿与 resolve-spec)。5.19.0 起守卫
+ *   按 `ToolCallRequest.cwd`(引擎每次调用从同一只 tracked cwd 盖戳)解析写目标,本腿零改动即得保护;
+ *   **不对称是 core 故意的**:目标跟活 cwd 走,守卫自己配置的目录仍锚静态根,`cd` 搬不动栅栏。全文与
+ *   证据见 `deployment-governance.ts` 的 `RelativeTargetLexicalEnv` 顶注,端到端正控钉见
+ *   test/run-local.test.ts(该钉已由 🟡 特征化翻成 🔴 正控)。
+ * · **禁 memoize**:四个旋钮都是热改字段,每次装配现读活 config(与另两条腿同一姿势)。
+ */
+export declare function applyLocalGovernance(base: TaskSpec, config: LocalGovernanceConfigView, workspaceDir: string): TaskSpec;
+/** {@link createLocalApprover} 的 io 面(全部可注入,所以两条臂都测得动)。 */
+export interface LocalApproverIo {
+    /** 这次调用是不是接在一个人面前(生产里 = `process.stdin.isTTY`)。 */
+    readonly isTty: boolean;
+    /** TTY 臂的问人器(默认 {@link promptYesNoOnTty} 的 readline y/N;`signal`=core 取消透传)。 */
+    readonly askYesNo: (prompt: string, signal?: AbortSignal) => Promise<boolean>;
+    /** 非 TTY 臂的告知面(stderr)。 */
+    readonly printErr: (line: string) => void;
+}
+/**
+ * design/181 件三:**onAsk 座**(§0 潜雷 / §5 锁 6)。
+ *
+ * 🔴 为什么这个座位是接治理链的**同窗必做项**:run-local 有 checkpointStore(file backend),所以
+ * `AUTONOMY=ask` ⇒ `shellGate:"always"` ⇒ Bash 进 `irreversibleTools` ⇒ park lane effective ⇒ **每一次
+ * shell 调用都 durable park 成一张永远没人 resume 的 checkpoint**,任务挂起、CLI 退 1。一次性 CLI 里
+ * 没有任何赎回腿,那不是「等人来批」,是卡死。core 的 `isLiveApproverSeat(onAsk)` 为真时 `suspendAsk`
+ * 早退(prepare-task dist 亲读),ask 于是落回本回调 —— 把 park 换成「问人 / 当场拒」的唯一正当接法。
+ *
+ * ⛔ **不在 toolPolicy 层做 ask→deny 映射**:core 自己就有 headless auto-deny 的语义与文案,在策略层
+ * 复刻一份 = 同源谎(两处判据日后各改各的)。裁决归 core,座位归这里。
+ *
+ * 🔴 非 TTY 臂答 `false`(真 deny),**绝不答 `"unavailable"`**:后者被 core 读成「席位够不到」并**改道
+ * `suspendAsk`**(dist `core/hooks.js:296` 的 `approverUnavailable` 重投),上面那颗雷会原样回来。
+ */
+export declare function createLocalApprover(io: LocalApproverIo): OnAsk;
+/** 默认的 TTY 问人器:一问一答,回答写 **stderr**(stdout 是任务结果的专用管道,别污染它)。
+ *  streams 可注入=EOF/abort 两臂测得动(默认 process.stdin/stderr)。
+ *
+ *  🔴 决断三臂(codex 验收轮 high,红先修):`readline/promises` 的 `question` 在输入流 EOF/close 时
+ *  **不决**(promise 悬挂)——Ctrl-D、关闭的 stdin、任务取消都会把 runLocal 永久挂住,文件后端的锁
+ *  跟着被拖住,下一次同 root 调用直接卡死。三臂全部 fail-closed 决 false:
+ *   · `signal` abort(core `OnAsk` 递进来的取消,含预先 aborted);
+ *   · readline `close`(输入流 end/close 时 readline 自关);
+ *   · `question` 自身 reject(abort throw / 流错误)。 */
+export declare function promptYesNoOnTty(prompt: string, signal?: AbortSignal, streams?: {
+    input: NodeJS.ReadableStream;
+    output: NodeJS.WritableStream;
+}): Promise<boolean>;
 /**
  * Boot the engine in LOCAL mode, run ONE task to completion, print the result. Returns the process exit
  * code (0 = completed, 1 = the task did not complete / a fatal error, 2 = bad usage / unmet env). Pure of

package/dist/run-local.js

@@ -13,7 +13,18 @@
  * applyEffective (config.d/.env drives models/roles/mcp), and the `host` exec lane (run on THIS machine,
  * no container) — identical building blocks to the server path so behavior matches (no drift). It reuses
  * main.ts's helpers verbatim; the only thing it skips is the server-only surface (createHttpServer, listen,
- * auth/rateLimit/quota/run-store/leader/durable-checkpoint/reapers).
+ * auth/rateLimit/quota/run-store/leader/durable-approval-decide/reapers).
+ *
+ * 🔴 **DEPLOYMENT GOVERNANCE IS NOT IN THAT SKIP LIST** (design/181 件三 / #180). Until 7.4.x this file
+ * assembled its `TaskSpec` with the governance chain entirely ABSENT — `loadConfig` + `applyEffective` had
+ * already parsed `autonomy` / `commandPolicy` / `sensitiveWritePatterns` into the config, and the spec
+ * literal simply never read them (compute-then-discard), so the same operator knob was live on the HTTP leg
+ * and structurally non-existent here. It now goes through the SAME single construction port as the other two
+ * legs ({@link applyLocalGovernance} → `src/deployment-governance.ts` → `applyRuntimeGovernance` → core's
+ * `tightenTaskSpec`). What this leg genuinely does NOT have is the **durable approval** face (a one-shot CLI
+ * has no `/v1/approvals/:id/decide` leg to resume from), so the approval baseline is the adjudicated
+ * allow-all arm and a gated `ask` is answered by {@link createLocalApprover} — the TTY human, or a
+ * fail-closed deny — instead of parking a checkpoint nobody will ever redeem.
  *
  *   Usage:  run-local "<objective>"  [--root <dir>] [--json] [--scenario <name>]
  *
@@ -24,10 +35,14 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { realpathSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { loadRemoteExec } from "@sema-agent/registry-core/node";
-import { Runner, uuidv7, parseModelMention, FileStorageBackend, NodeLspManager, TtlSessionStore, CenterPromptSource, FilePromptArtifactStore, FilePromptSourceStateStore, MemoryPromptArtifactStore, MemoryPromptSourceStateStore } from "@sema-agent/core";
+import { Runner, uuidv7, parseModelMention, FileStorageBackend, NodeExecutionEnv, NodeLspManager, TtlSessionStore, CenterPromptSource, FilePromptArtifactStore, FilePromptSourceStateStore, MemoryPromptArtifactStore, MemoryPromptSourceStateStore } from "@sema-agent/core";
+import { hasOperatorGateIntent } from "./approval.js";
 import { createBrain } from "./brain.js";
+import { assertGuardPatternsUsable, buildOnlySensitiveBaselineWarning, createApprovalBaselinePolicy, createDeploymentGovernanceInputs, } from "./deployment-governance.js";
+import { applyRuntimeGovernance } from "./runtime-governance.js";
 import { ForkRoutingSessionStore } from "./plugins/fork-routing-session-store.js";
 import { taskWallClockSec } from "./task-workflow.js";
 import { applyCatalogToSource } from "./capabilities/center-prompts.js";
@@ -41,6 +56,7 @@ import { loadSkills } from "./capabilities/skills.js";
 import { GiteaClient } from "./capabilities/repo-tools.js";
 import { webSearchConfigFromEnv, createWebSearchBackend } from "./plugins/web-search.js";
 import { buildScenarios, selectScenario, centerScenarios } from "./capabilities/scenarios.js";
+import { pickHandsRunner, withoutExecutionEnv } from "./capabilities/hands-lane.js";
 import { HttpError } from "./security.js";
 import { memoryEngineBackendFor, memorySpecForRequest } from "./memory-scope.js";
 import { createMemorySyncRunner, createMemorySyncTransport } from "./memory-sync-client.js";
@@ -147,6 +163,89 @@ export function missingGatewayRequirements(config) {
     }
     return missing;
 }
+/**
+ * design/181 件三:run-local 腿的**部署治理链装配**(#180)。
+ *
+ * 与另外两条腿(HTTP 的 `resolveSpec`、durable park 的赎回腿)装的是**同一条**链,经**同一个**构造口:
+ * 审批基线作 base 的 `toolPolicy` 座,再经**折叠属主** `applyRuntimeGovernance`(→ core `tightenTaskSpec`)
+ * 叠上部署治理段(autonomy / commandPolicy / MANUAL_MODE_SHELL_GATE / 守卫集)。本函数一条 policy 都不
+ * 自己合成。
+ *
+ * · **审批基线 = adjudicated allow-all**:一次性 CLI 没有 durable 审批设施(没有 `/decide` 腿可赎回),
+ *   所以 `createApprovalBaselinePolicy` 走 durable 缺席那一臂。它是一条**在场的** effect-aware 策略
+ *   (满足 core 的 `hasEffectAwareGate`),运维照旧用 `AUTONOMY` / `commandPolicy` / 守卫集在其上收紧。
+ * · **裁决 env 恒 host 形,锚 `workspaceDir`**:run-local 的手就跑在这台机器的这个目录上
+ *   (`--workspace` / config.d workdir / cwd 三选一,调用方已解析好),所以 `cwd` 恒在场 —— 相对形写目标
+ *   由 core 按 `rootPath` 解析进真身裁决,构造口的词法补层(沙箱腿那条)在这里自动不铺。
+ *   ✅ **旧残余面已收口(core 5.19.0 #108,2026-08-08 校正)**:`rootPath` 是装配期的**静态**值,而 core
+ *   的写工具解析相对形用的是被 Bash `cd` 就地改写的活 cwd —— 于是 `cd .git/hooks` 之后
+ *   `Write("pre-commit")` 落进守卫段却判不出来(两条 host 腿同形,本腿与 resolve-spec)。5.19.0 起守卫
+ *   按 `ToolCallRequest.cwd`(引擎每次调用从同一只 tracked cwd 盖戳)解析写目标,本腿零改动即得保护;
+ *   **不对称是 core 故意的**:目标跟活 cwd 走,守卫自己配置的目录仍锚静态根,`cd` 搬不动栅栏。全文与
+ *   证据见 `deployment-governance.ts` 的 `RelativeTargetLexicalEnv` 顶注,端到端正控钉见
+ *   test/run-local.test.ts(该钉已由 🟡 特征化翻成 🔴 正控)。
+ * · **禁 memoize**:四个旋钮都是热改字段,每次装配现读活 config(与另两条腿同一姿势)。
+ */
+export function applyLocalGovernance(base, config, workspaceDir) {
+    return applyRuntimeGovernance({ ...base, toolPolicy: createApprovalBaselinePolicy(config) }, createDeploymentGovernanceInputs(config, { env: new NodeExecutionEnv({ cwd: workspaceDir }), cwd: workspaceDir }));
+}
+/**
+ * design/181 件三:**onAsk 座**(§0 潜雷 / §5 锁 6)。
+ *
+ * 🔴 为什么这个座位是接治理链的**同窗必做项**:run-local 有 checkpointStore(file backend),所以
+ * `AUTONOMY=ask` ⇒ `shellGate:"always"` ⇒ Bash 进 `irreversibleTools` ⇒ park lane effective ⇒ **每一次
+ * shell 调用都 durable park 成一张永远没人 resume 的 checkpoint**,任务挂起、CLI 退 1。一次性 CLI 里
+ * 没有任何赎回腿,那不是「等人来批」,是卡死。core 的 `isLiveApproverSeat(onAsk)` 为真时 `suspendAsk`
+ * 早退(prepare-task dist 亲读),ask 于是落回本回调 —— 把 park 换成「问人 / 当场拒」的唯一正当接法。
+ *
+ * ⛔ **不在 toolPolicy 层做 ask→deny 映射**:core 自己就有 headless auto-deny 的语义与文案,在策略层
+ * 复刻一份 = 同源谎(两处判据日后各改各的)。裁决归 core,座位归这里。
+ *
+ * 🔴 非 TTY 臂答 `false`(真 deny),**绝不答 `"unavailable"`**:后者被 core 读成「席位够不到」并**改道
+ * `suspendAsk`**(dist `core/hooks.js:296` 的 `approverUnavailable` 重投),上面那颗雷会原样回来。
+ */
+export function createLocalApprover(io) {
+    return async (req, signal) => {
+        if (!io.isTty) {
+            io.printErr(`denied "${req.toolName}" (${req.message}) — this run-local invocation has no TTY, so there is nobody to ask. ` +
+                `The gate comes from this deployment's governance knobs: AUTONOMY, MANUAL_MODE_SHELL_GATE, ` +
+                `runtime.commandPolicy (config.d/governance.json). Run it in a terminal to answer interactively, or relax the knob.`);
+            return false;
+        }
+        return io.askYesNo(`approve "${req.toolName}"? ${req.message} [y/N] `, signal);
+    };
+}
+/** 默认的 TTY 问人器:一问一答,回答写 **stderr**(stdout 是任务结果的专用管道,别污染它)。
+ *  streams 可注入=EOF/abort 两臂测得动(默认 process.stdin/stderr)。
+ *
+ *  🔴 决断三臂(codex 验收轮 high,红先修):`readline/promises` 的 `question` 在输入流 EOF/close 时
+ *  **不决**(promise 悬挂)——Ctrl-D、关闭的 stdin、任务取消都会把 runLocal 永久挂住,文件后端的锁
+ *  跟着被拖住,下一次同 root 调用直接卡死。三臂全部 fail-closed 决 false:
+ *   · `signal` abort(core `OnAsk` 递进来的取消,含预先 aborted);
+ *   · readline `close`(输入流 end/close 时 readline 自关);
+ *   · `question` 自身 reject(abort throw / 流错误)。 */
+export async function promptYesNoOnTty(prompt, signal, streams = { input: process.stdin, output: process.stderr }) {
+    if (signal?.aborted)
+        return false;
+    const rl = createInterface({ input: streams.input, output: streams.output });
+    try {
+        return await new Promise((resolve) => {
+            const settle = (v) => {
+                rl.off("close", onClosed);
+                signal?.removeEventListener("abort", onAborted);
+                resolve(v);
+            };
+            const onClosed = () => settle(false);
+            const onAborted = () => settle(false);
+            rl.on("close", onClosed);
+            signal?.addEventListener("abort", onAborted, { once: true });
+            rl.question(prompt).then((answer) => settle(/^y(es)?$/i.test(answer.trim())), () => settle(false));
+        });
+    }
+    finally {
+        rl.close();
+    }
+}
 /**
  * Boot the engine in LOCAL mode, run ONE task to completion, print the result. Returns the process exit
  * code (0 = completed, 1 = the task did not complete / a fatal error, 2 = bad usage / unmet env). Pure of
@@ -248,6 +347,28 @@ export async function runLocal(argv, deps = {}) {
         printErr(`config.d/remote-exec.json is invalid: ${String(err)}`);
         return 2;
     }
+    // ── design/181 件三 boot 期两件(与 HTTP 腿同一只判据)────────────────────────────────────────
+    // ① 守卫集的**可编译性**门:编译发生在每一次装配上,一条「一个路径段都没有」的模式(`"/"`)会 THROW,
+    //    运维从那条错误里看不出是自己的 env 写错了。共享 .env 的坏值必须炸在启动上——这条腿按 run-local 的
+    //    既定 UX 落地(doctor 文案 + 退 2),而不是把栈抛给用户。
+    try {
+        assertGuardPatternsUsable(config);
+    }
+    catch (e) {
+        printErr(e instanceof Error ? e.message : String(e));
+        printErr(`(local config root: ${root} — fix it in ${join(root, ".env")} or your shell env; \`SENSITIVE_WRITE_PATTERNS=off\` disables the guard set)`);
+        return 2;
+    }
+    // ② UNGATED 补偿:接上审批基线后 core 的 `hasEffectAwareGate` 恒真 ⇒ 它那条 "write-capable hand tools
+    //    are present but UNGATED" 的信号在这条腿上结构性消失。判据与文案是**同一只**构造口的
+    //    (buildOnlySensitiveBaselineWarning),两个座位量按本腿的真形取:durable 门恒不在场(一次性 CLI
+    //    没有 /decide 赎回腿),单用户 auto-accept 基线的适用性判据与 main.ts 逐字同源。
+    const ungatedCompensation = buildOnlySensitiveBaselineWarning(config, {
+        durableEnabled: false,
+        singleUserAutoAcceptBaseline: config.requirePrincipal !== true && !hasOperatorGateIntent(config),
+    });
+    if (ungatedCompensation)
+        logger.warn(ungatedCompensation.event, ungatedCompensation.fields);
     // ── Pre-flight: with a REAL brain, validate the gateway + key and print the doctor-style guidance instead
     //    of crashing on the first brain call. With an injected mock brain, no real call happens → skip. ──
     if (!deps.brain) {
@@ -361,7 +482,21 @@ export async function runLocal(argv, deps = {}) {
     catch (e) {
         logger.warn("center_prompts_catalog_restore_failed", { err: String(e), note: "catalog candidate absent — built-ins serve" });
     }
-    const runner = new Runner({
+    // design/181 件三:**onAsk 座**(全文理由见 {@link createLocalApprover})。两只 Runner 同装 —— 委派出去
+    // 的子任务也在同一台机器上动手,少装一只就是「主任务问人、子任务 park 卡死」。
+    const onAsk = createLocalApprover({
+        isTty: deps.isTty ?? process.stdin.isTTY === true,
+        askYesNo: deps.askYesNo ?? promptYesNoOnTty,
+        printErr,
+    });
+    /** core 的 `RunnerDeps.onError` 座(两只 Runner 共用一只闭包 —— 两处各写一份正是漂移的成因)。 */
+    const engineOnError = (err, ctx) => logger.warn("engine_error", {
+        phase: ctx.phase,
+        sessionId: ctx.sessionId,
+        ...(ctx.classification !== undefined ? { classification: ctx.classification } : {}),
+        err: String(err),
+    });
+    const runnerDeps = {
         brain,
         models: config.models,
         roles: config.roles,
@@ -372,6 +507,11 @@ export async function runLocal(argv, deps = {}) {
         sessionStore,
         ...(memoryEngine ? { memoryBackend: memoryEngine.backend, memoryEngineDir: memoryEngine.root } : {}),
         checkpointStore: fileBackend.checkpointStore,
+        // design/181 件三:core 的降级/配置类告警此前被 `deps.onError?.()` 的可选链整条吞掉(这条腿从不接这
+        // 个座),包括那条 "write-capable hand tools are present but UNGATED"。接上 stderr(logger.warn 走
+        // stderr)后其余告警——compaction / prompt-cache / mcp / memory / hook 的降级——也不再无声。
+        onError: engineOnError,
+        onAsk,
         // core 1.219 (dogfood: "ReadToolResult(ref) 恒空"): durable tool-result refs on the TOC CLI
         // lane too — offloaded full text survives a process restart (one file per ref under the data root).
         toolResultStore: fileBackend.toolResultStore,
@@ -382,14 +522,21 @@ export async function runLocal(argv, deps = {}) {
         ...(config.projectMemoryEnabled
             ? { loadProjectMemory: makeLoadProjectMemory({ logger }), probeInstructionSources: makeProbeInstructionSources() }
             : {}),
-    });
+    };
+    const runner = new Runner(runnerDeps);
     // Sub-task runner (council lenses/team) — mirrors main.ts's subRunner, INCLUDING executionEnvFactory so a delegated
     // child gets hands (Bash/Read/Edit) on the host lane. Without it the child's handsEnabled is false — the exact
     // "subagent couldn't run pwd" defect fixed at main.ts:799; this is its run-local twin, caught by the systematic audit.
     // [1367]① fork server half(main.ts subRunner 同款):ForkRoutingSessionStore——fork/resume 形
     // (requireExisting)→ host 文件店优先(core 1.350 hostSessionFork 在宿主店 fork,拆店=响亮
     // resume.session_not_found),普通子任务 → 私有 TTL 店(throwaway 姿势保留)。
-    const subRunner = new Runner({ brain, models: config.models, roles: config.roles, pricing, promptSource, sessionStore: new ForkRoutingSessionStore(sessionStore, new TtlSessionStore({ defaultTtlDays: 1 / 24 })), ...(executionEnvFactory ? { executionEnvFactory } : {}), ...(lspManager ? { lspManager } : {}) });
+    const subRunnerDeps = { brain, models: config.models, roles: config.roles, pricing, promptSource, sessionStore: new ForkRoutingSessionStore(sessionStore, new TtlSessionStore({ defaultTtlDays: 1 / 24 })), onError: engineOnError, onAsk, ...(executionEnvFactory ? { executionEnvFactory } : {}), ...(lspManager ? { lspManager } : {}) };
+    const subRunner = new Runner(subRunnerDeps);
+    // #196:无手孪生一对 —— **mirrors main.ts**(那边是 `handslessRunner` / `handslessSubRunner` 两只,同 deps
+    // 摘掉 executionEnvFactory)。run-local 是同形装配点,漏这一对 = 本地 lane 上 scan/council/team 的最终
+    // roster 仍被并集进全量可写手(server 修了、CLI 静默留病 —— 这条腿的 subRunner 当年就是这么漏配的)。
+    const handslessRunner = new Runner(withoutExecutionEnv(runnerDeps));
+    const handslessSubRunner = new Runner(withoutExecutionEnv(subRunnerDeps));
     // Capability layer (loadSkills + buildScenarios + selectScenario) — assembled exactly like main.ts.
     const skills = loadSkills(config.skillsDir);
     const repoClient = config.gitApiBaseUrl ? new GiteaClient(config.gitApiBaseUrl, config.gitApiToken) : undefined;
@@ -398,7 +545,7 @@ export async function runLocal(argv, deps = {}) {
     const webSearchCfg = webSearchConfigFromEnv();
     const webSearch = webSearchCfg ? createWebSearchBackend(webSearchCfg) : undefined;
     const scenarioDeps = {
-        runner, subRunner, model: "default", skills, repoClient, metrics, logger,
+        runner, subRunner, handslessSubRunner, model: "default", skills, repoClient, metrics, logger,
         ...(webSearch ? { webSearch } : {}),
         brandIdentity: true, // run-local is always a local/TOC deployment → brand the default scenario as Sema.
     };
@@ -451,7 +598,9 @@ export async function runLocal(argv, deps = {}) {
     const taskTimeoutSec = Math.max(0, Math.floor(numEnv("TASK_TIMEOUT_SEC", "0")));
     const timeoutSec = taskWallClockSec(taskTimeoutSec, false, scenarioName === "team");
     const mcp = mcpForScenario(config.mcpServers, scenarioName);
-    const spec = {
+    // design/181 件三:自建的 spec 字面量经**同一条**部署治理链(见 {@link applyLocalGovernance})——
+    // 审批基线 + autonomy/commandPolicy/MANUAL_MODE_SHELL_GATE/守卫集,tighten-only,折叠属主仍是 core。
+    const spec = applyLocalGovernance({
         objective: mention.cleanedText || args.objective,
         sessionId,
         // design/129: run-local IS the pure TOC lane → session-scoped background children
@@ -471,13 +620,15 @@ export async function runLocal(argv, deps = {}) {
         ...(mcp ? { mcp } : {}),
         // core 5.8.0:timeoutSec 键退役 → maxWalltimeMs(毫秒);taskWallClockSec 仍产秒,此处换算一次。
         ...(timeoutSec !== undefined ? { limits: { maxWalltimeMs: timeoutSec * 1000 } } : {}),
-    };
+    }, config, workspaceDir);
     logger.info("run_local_start", { scenario: scenarioName, model: spec.model, sessionId, exec: config.remoteExec?.provider ?? "in-process" });
     // ── Run ONE task to completion (the sync /v1/tasks path: plain runTask, no verify/cascade). ──
     let result;
     let exitCode = 0;
+    // #196:与 HTTP 腿同一条选路 —— 场景声明 hands:"none" 时任务跑无手 Runner(band 不 mount)。
+    const taskRunner = pickHandsRunner(cap.hands, { full: runner, handsless: handslessRunner });
     try {
-        result = await runner.runTask(spec);
+        result = await taskRunner.runTask(spec);
     }
     catch (err) {
         printErr(`task crashed: ${err instanceof Error ? err.message : String(err)}`);

package/dist/runs.d.ts

@@ -184,7 +184,9 @@ export declare class TurnAnchorCapture {
  * Strip the durable-resume capability token from a result before it is persisted to the replayable event
  * log / run row or returned to the submitter. The token IS the resume credential (token-as-auth, search
  * [18] Q1b) and must never leave the service. Safe on any result (no-op when absent) — notably core maps a
- * NESTED suspend under verify/cascade to status:"failed" + errorCode "suspended.awaiting_approval"(core 5.9.0 W1 改名)while still
+ * NESTED suspend under verify/cascade to status:"failed" + errorCode "unexpected.suspended"(inner status
+ * "needs_review" ⇒ "unexpected.needs_review";core `agents/suspend-guard.js` `mapNestedSuspend`,由 verify.js
+ * 191/201/208 与 cascade.js:125 调用)while still
  * spreading `checkpointToken`, so that "failed" path (unlike the stream path's explicit suspend handling)
  * would otherwise leak it into task_event / task_run.result / the sync 200 response. `checkpointGate` is
  * non-secret and intentionally kept.

package/dist/runs.js

@@ -262,7 +262,9 @@ export class TurnAnchorCapture {
  * Strip the durable-resume capability token from a result before it is persisted to the replayable event
  * log / run row or returned to the submitter. The token IS the resume credential (token-as-auth, search
  * [18] Q1b) and must never leave the service. Safe on any result (no-op when absent) — notably core maps a
- * NESTED suspend under verify/cascade to status:"failed" + errorCode "suspended.awaiting_approval"(core 5.9.0 W1 改名)while still
+ * NESTED suspend under verify/cascade to status:"failed" + errorCode "unexpected.suspended"(inner status
+ * "needs_review" ⇒ "unexpected.needs_review";core `agents/suspend-guard.js` `mapNestedSuspend`,由 verify.js
+ * 191/201/208 与 cascade.js:125 调用)while still
  * spreading `checkpointToken`, so that "failed" path (unlike the stream path's explicit suspend handling)
  * would otherwise leak it into task_event / task_run.result / the sync 200 response. `checkpointGate` is
  * non-secret and intentionally kept.

package/dist/security.d.ts

@@ -208,6 +208,18 @@ export declare function principalFrom(req: IncomingMessage, config: ServiceConfi
 /** Header carrying the crypto-verified principal JWT on a direct-door worker (the issuer signs it; the worker only
  *  verifies). The trusted twin of `config.principalHeader` (the latter is client-spoofable on a direct door). */
 export declare const PRINCIPAL_TOKEN_HEADER = "x-approval-principal-token";
+/**
+ * direct-door 决策证明三件套的另外两个头名(JWT 在上面那个常量里)。
+ *
+ * 为什么也具名(2026-08-08,#176 二轮扫描 finding):这三个头名此前在
+ * `http/routes/approvals-assistant.ts` 的两个 `verifyDirectDoorProof` 调用点、以及 `http/server.ts` 的
+ * CORS `access-control-allow-headers` 串里**各手抄一份**——而 CORS 那一行同一句里已经在用
+ * `${principalHeader}` 插值另一个头名,证明具名写法在该处本就可用。改任一头名时漏改 CORS 串的后果
+ * 是**静默的**:浏览器预检把该头挡下,请求到不了 handler ⇒ 表现成「direct-door 上审批面莫名失效」,
+ * 而不是任何一处报错。低危(改头名本身即 wire BREAKING、不太可能单边发生),但零成本可消。
+ */
+export declare const APPROVAL_MAC_HEADER = "x-approval-mac";
+export declare const APPROVAL_MAC_KID_HEADER = "x-approval-mac-kid";
 export declare function setSsoPrincipal(req: IncomingMessage, principal: string): void;
 export declare function ssoVerifiedPrincipal(req: IncomingMessage): string | undefined;
 export declare function setSsoScope(req: IncomingMessage, scope: string): void;

package/dist/security.js

@@ -279,6 +279,18 @@ export function principalFrom(req, config) {
 /** Header carrying the crypto-verified principal JWT on a direct-door worker (the issuer signs it; the worker only
  *  verifies). The trusted twin of `config.principalHeader` (the latter is client-spoofable on a direct door). */
 export const PRINCIPAL_TOKEN_HEADER = "x-approval-principal-token";
+/**
+ * direct-door 决策证明三件套的另外两个头名(JWT 在上面那个常量里)。
+ *
+ * 为什么也具名(2026-08-08,#176 二轮扫描 finding):这三个头名此前在
+ * `http/routes/approvals-assistant.ts` 的两个 `verifyDirectDoorProof` 调用点、以及 `http/server.ts` 的
+ * CORS `access-control-allow-headers` 串里**各手抄一份**——而 CORS 那一行同一句里已经在用
+ * `${principalHeader}` 插值另一个头名,证明具名写法在该处本就可用。改任一头名时漏改 CORS 串的后果
+ * 是**静默的**:浏览器预检把该头挡下,请求到不了 handler ⇒ 表现成「direct-door 上审批面莫名失效」,
+ * 而不是任何一处报错。低危(改头名本身即 wire BREAKING、不太可能单边发生),但零成本可消。
+ */
+export const APPROVAL_MAC_HEADER = "x-approval-mac";
+export const APPROVAL_MAC_KID_HEADER = "x-approval-mac-kid";
 /** The DIRECT-DOOR-SAFE principal — the VERIFIED identity for governance + cost + isolation. On a BFF/gated deployment
  *  the header is already verified upstream (return it); on a direct-door worker the `principalHeader` is client-
  *  spoofable, so identity comes from the crypto-verified `x-approval-principal-token` JWT (the issuer's private key

package/dist/session-sync-kernel.d.ts

@@ -66,6 +66,19 @@ export declare function stagingIdFor(realSessionId: string, token: string): stri
 export declare const STAGING_ID_MARKER = "#stg-";
 /** Recover the real session id from a staging id (everything before the `#stg-` marker), or null if not a staging id. */
 export declare function realIdOfStaging(stagingId: string): string | null;
+/**
+ * Staging-row reaper grace window — a staging session's rows are GC'able only if it has NO `session_meta` (never
+ * committed) AND its OLDEST row is older than this (an in-flight stream keeps appending fresh rows → safe).
+ * Mirrors the file-snapshot store's `BLOB_GC_GRACE_MS` discipline (an in-flight import must never be reaped
+ * mid-stream).
+ *
+ * 🔴 住在 kernel 里而不是任一个店里(2026-08-08,#176 二轮扫描 finding):TiDB 与 PG 两个孪生店原先**各
+ * 抄一份**同值常量,PG 那份的注释甚至自称「twin of the TiDB store's STAGING_GC_GRACE_MS」——明知孪生却
+ * 不共享。单边改值的后果是两个后端对「同一个中断的导入还能不能收」判定分家,而两边都按自己的常量静默
+ * 正确工作。这里是两个店**本就都 import** 的那个叶子模块(店契约纪律:适配器不许 import 自己的孪生,
+ * 共享常量必须落在中立处),同族先例见 `checkpoint-store-sql.ts` 的 `export const TERMINAL_GRACE_MS`。
+ */
+export declare const STAGING_GC_GRACE_MS = 3600000;
 /**
  * §7 — the relationship between a SOURCE bundle's entry log and the DESTINATION's CURRENT entry log, the gate that
  * decides whether an import is a safe sync or a data-losing overwrite. Five exhaustive cases:

package/dist/session-sync-kernel.js

@@ -10,6 +10,19 @@ export function realIdOfStaging(stagingId) {
     const i = stagingId.indexOf(STAGING_ID_MARKER);
     return i < 0 ? null : stagingId.slice(0, i);
 }
+/**
+ * Staging-row reaper grace window — a staging session's rows are GC'able only if it has NO `session_meta` (never
+ * committed) AND its OLDEST row is older than this (an in-flight stream keeps appending fresh rows → safe).
+ * Mirrors the file-snapshot store's `BLOB_GC_GRACE_MS` discipline (an in-flight import must never be reaped
+ * mid-stream).
+ *
+ * 🔴 住在 kernel 里而不是任一个店里(2026-08-08,#176 二轮扫描 finding):TiDB 与 PG 两个孪生店原先**各
+ * 抄一份**同值常量,PG 那份的注释甚至自称「twin of the TiDB store's STAGING_GC_GRACE_MS」——明知孪生却
+ * 不共享。单边改值的后果是两个后端对「同一个中断的导入还能不能收」判定分家,而两边都按自己的常量静默
+ * 正确工作。这里是两个店**本就都 import** 的那个叶子模块(店契约纪律:适配器不许 import 自己的孪生,
+ * 共享常量必须落在中立处),同族先例见 `checkpoint-store-sql.ts` 的 `export const TERMINAL_GRACE_MS`。
+ */
+export const STAGING_GC_GRACE_MS = 3_600_000;
 /**
  * §7 — classify how importing `srcEntries` into a destination holding `dstEntries` would relate the two logs. PURE
  * (no I/O); the §7 fork detector. The comparison is over the ENTRY-ID SETS, not leaf_id:

package/dist/trace/core-keyset-guard.d.ts

@@ -27,7 +27,7 @@ type _GuardBgNotif = AssertAllKeysHandled<Exclude<keyof BackgroundChildEvent, Bg
 type RosterProjected = "name" | "agentId" | "sessionId" | "toolUseId" | "owner" | "scope" | "sessionScoped" | "rootSessionId" | "model" | "modelFallback" | "createdAt";
 type _GuardRoster = AssertAllKeysHandled<Exclude<keyof RosterEntry, RosterProjected>>;
 type AskProjected = "toolName" | "toolCallId" | "args" | "message" | "sourceTaskId" | "fromSubagent" | "sourceAgentName" | "delegation";
-type AskExcluded = "preview" | "principal" | "requiresRealApproval" | "riskAxes" | "boundInputHash";
+type AskExcluded = "preview" | "principal" | "requiresRealApproval" | "riskAxes" | "boundInputHash" | "ruleSuggestions";
 type _GuardAsk = AssertAllKeysHandled<Exclude<keyof AskRequest, AskProjected | AskExcluded>>;
 type TaskEventHandled = "text_delta" | "reasoning_delta" | "tool_start" | "tool_end" | "turn_end" | "compacted" | "diagnostics" | "message_committed" | "status" | "task_notification" | "task_progress" | "steering_injected" | "workspace_changed" | "done" | "context_usage" | "compaction_outcome" | "human_input" | "wiring_manifest";
 type _GuardTaskEvent = AssertAllKeysHandled<Exclude<TaskEvent["type"], TaskEventHandled>>;

package/dist/trace/project.d.ts

@@ -12,7 +12,7 @@
  * old session-join `toolOutput` hook is gone, there's a real source now); `eventId`/`parentToolCallId` (§E2) ride
  * each content event, additive / tolerate-absent.
  */
-import type { TaskResult } from "@sema-agent/core";
+import type { ApprovalSettledBy, TaskResult } from "@sema-agent/core";
 import type { RunEvent, RunRecord } from "../plugins/store-contracts.js";
 import type { ModelUsageDelta, ModelUsageTracker, PromptManifestRecord } from "../budget.js";
 type AppendFn = (type: string, data: unknown) => Promise<void>;
@@ -90,6 +90,7 @@ export type TraceBlock = {
     totalChars?: number;
     structured?: unknown;
     errorCode?: string;
+    settledBy?: ApprovalSettledBy;
     eventId?: string;
     parentToolCallId?: string;
 } | {
@@ -131,6 +132,7 @@ export declare function toolEndEventData(ev: {
     totalChars?: number;
     structured?: unknown;
     errorCode?: string;
+    settledBy?: ApprovalSettledBy;
     eventId?: string;
     parentToolCallId?: string;
 }): Record<string, unknown>;
@@ -284,6 +286,13 @@ export declare function workspaceChangedEventData(ev: {
  *  · `interaction.posture`(三值:interactive / headless / absent)—— **裁:租户可见**。它是部署形的
  *    自述(这条腿有没有人能答问题),消费端据此决定渲不渲交互面;不是治理秘密,也不构成任何治理位的
  *    侧信道(它不参与 governance 那 4 个布尔的还原)。
+ *  · `permissionRules.storeWired`(布尔;core 5.18.0 design/179 新段)—— **裁:租户可见**。同族判据:
+ *    它与 `parkLane.capable` / `elicit.seamWired` / `fleet.backgroundAgentStore` 是同一类「这条腿接没接
+ *    某个可选设施」的部署形自述,而那三个早已租户可见。消费端的真需求也在租户侧:审批卡要不要渲染
+ *    「不再询问」这一格,取决于这台 worker 有没有规则店 —— 剥掉它,客户端只能靠试(提交后被拒)才知道。
+ *    它**不在** `governance` 段里(core 自己把它放在段外),也不构成那 4 个治理布尔的侧信道。
+ *    ⚠️ 恒在段(core 侧 `permissionRules` 无 `?`):本仓未接规则店 ⇒ `storeWired: false`,这是**真值**
+ *    不是缺席 —— 消费端读到 false 就是「这台 worker 没有这条车道」,不许当成「这版引擎还没这个概念」。
  * 未来 core 加一段而它没有 audience 标签时,**先在这里补一条裁定再决定挑不挑键** —— 段级完备性钉
  * (test/wiring-manifest-projection.test.ts)会在那一刻先把人拦下来。
  */

package/dist/trace/project.js

@@ -1,3 +1,6 @@
+// 值导入(非 `import type`):`settledBy` 的闭集判据必须**复用 core 的谓词**——本仓抄一份三元词表
+// 就是值拷贝漂移源(上游加员时两处静默不同步)。core 5.18.1 #187 导出的单一属主。
+import { isApprovalSettledBy } from "@sema-agent/core";
 import { redactSecrets, redactDeep } from "./redact.js";
 /** E8 (shell-host): drain the per-task model-usage accumulator into an append-only `model_usage` DELTA event.
  *  Shared by BOTH durable-write legs (runInBackground + the resume leg) so the persisted shape never drifts; the
@@ -163,6 +166,16 @@ export function toolEndEventData(ev) {
         // 带 default 臂,禁按两值穷举。verbatim 依据:码是机器短串标识符、非用户内容(不脱敏),边界靠
         // 显式上限而非词表 —— >128 字符=非法形,整键丢弃(不截断:截断会铸出 core 从未发过的码)。
         ...(typeof ev.errorCode === "string" && ev.errorCode.length <= 128 ? { errorCode: ev.errorCode } : {}),
+        // core 5.18.1 #187([3110] 提货批):`settledBy` = 这一次调用的**结算来源**("human"/"timeout"/
+        // "aborted"),只挂在经审批结算的那个 tool_end 上。与上面的 errorCode **不同族**,两条差别都承重:
+        //  ① 它是**闭集**,判据走 core 导出的 `isApprovalSettledBy`(单一属主)—— 不在本仓抄词表,也不拿
+        //     长度上限当边界(那是开集的兜底姿势,对闭集等于没门:出格词照样上 wire,下游按闭集写的
+        //     switch 会撞 default 或更坏地把它当成一次真结算)。上游加员时判据自动跟随。
+        //  ② **缺席不是语义**:core 契约逐字写「Absence = an older caller — consumers must not infer
+        //     semantics from a missing key」;姿态臂(headless auto-deny / 整体放行)本就不填。所以缺席
+        //     一律不铸键 —— 既不折 "human" 也不折 null,把「不知道」如实表达成「没有这个键」。
+        // 值是引擎铸的枚举短串、非用户内容 ⇒ 不脱敏。
+        ...(isApprovalSettledBy(ev.settledBy) ? { settledBy: ev.settledBy } : {}),
         ...identityFields(ev),
     };
 }
@@ -363,6 +376,13 @@ export function workspaceChangedEventData(ev) {
  *  · `interaction.posture`(三值:interactive / headless / absent)—— **裁:租户可见**。它是部署形的
  *    自述(这条腿有没有人能答问题),消费端据此决定渲不渲交互面;不是治理秘密,也不构成任何治理位的
  *    侧信道(它不参与 governance 那 4 个布尔的还原)。
+ *  · `permissionRules.storeWired`(布尔;core 5.18.0 design/179 新段)—— **裁:租户可见**。同族判据:
+ *    它与 `parkLane.capable` / `elicit.seamWired` / `fleet.backgroundAgentStore` 是同一类「这条腿接没接
+ *    某个可选设施」的部署形自述,而那三个早已租户可见。消费端的真需求也在租户侧:审批卡要不要渲染
+ *    「不再询问」这一格,取决于这台 worker 有没有规则店 —— 剥掉它,客户端只能靠试(提交后被拒)才知道。
+ *    它**不在** `governance` 段里(core 自己把它放在段外),也不构成那 4 个治理布尔的侧信道。
+ *    ⚠️ 恒在段(core 侧 `permissionRules` 无 `?`):本仓未接规则店 ⇒ `storeWired: false`,这是**真值**
+ *    不是缺席 —— 消费端读到 false 就是「这台 worker 没有这条车道」,不许当成「这版引擎还没这个概念」。
  * 未来 core 加一段而它没有 audience 标签时,**先在这里补一条裁定再决定挑不挑键** —— 段级完备性钉
  * (test/wiring-manifest-projection.test.ts)会在那一刻先把人拦下来。
  */
@@ -386,6 +406,7 @@ export function wiringManifestEventData(ev) {
     const fleetIn = sec(m.fleet) ?? {};
     const legIn = sec(m.leg) ?? {};
     const interactionIn = sec(m.interaction) ?? {};
+    const rulesIn = sec(m.permissionRules) ?? {};
     const ask = nonEmpty({
         ...(str(askIn.form) !== undefined ? { form: askIn.form } : {}),
         ...(str(askIn.provenance) !== undefined ? { provenance: askIn.provenance } : {}),
@@ -413,6 +434,11 @@ export function wiringManifestEventData(ev) {
         ...(bool(fleetIn.backgroundAgentStore) !== undefined ? { backgroundAgentStore: fleetIn.backgroundAgentStore } : {}),
         ...(bool(fleetIn.hostChildEventSink) !== undefined ? { hostChildEventSink: fleetIn.hostChildEventSink } : {}),
     });
+    // core 5.18.0 design/179 段(裁定见头注:租户可见)。逐键挑,与其余段同规:非布尔按缺席处理
+    // (不铸假值——一个编出来的 `false` 会被读成「确实没接规则店」,而真相是这段读不出来)。
+    const permissionRules = nonEmpty({
+        ...(bool(rulesIn.storeWired) !== undefined ? { storeWired: rulesIn.storeWired } : {}),
+    });
     return {
         ...(num(m.schemaVersion) !== undefined ? { schemaVersion: m.schemaVersion } : {}),
         ...(str(legIn.kind) !== undefined ? { leg: { kind: legIn.kind } } : {}),
@@ -423,6 +449,7 @@ export function wiringManifestEventData(ev) {
         ...(parkLane !== undefined ? { parkLane } : {}),
         ...(str(sessionIn.store) !== undefined ? { session: { store: sessionIn.store } } : {}),
         ...(fleet !== undefined ? { fleet } : {}),
+        ...(permissionRules !== undefined ? { permissionRules } : {}),
         // governance —— **刻意不在此**(见头注:受众标 operator,无投影不披露)。
         // configFingerprint —— **也刻意不在此**(codex 复审 2026-08-06 F1,验真后采纳)。剥掉一个段却把
         // **对它取的哈希**发出去,等于没剥:core 的算法是
@@ -685,6 +712,10 @@ export function toolResultFieldsOf(d) {
         // core 5.9.0 W3([2535]):机器可判别的 park/死投影码(`gate.parked`/`tool.not_found`)——写侧
         // toolEndEventData 已带,读腿必须同键 verbatim(absent⇒absent),否则冷回放退回锚 abort 文案字面。
         ...(typeof d.errorCode === "string" ? { errorCode: d.errorCode } : {}),
+        // core 5.18.1 #187:结算来源(闭集)——写侧 toolEndEventData 已带,读腿同键 verbatim(absent⇒absent)。
+        // 🔴 读腿的闭集门是**独立的一道**,不是写侧那道的复述:账本行可以来自任何引擎世代、任何第三方
+        // producer,写侧的门管不到它们;这里放行 = 把一个 core 从未发过的词直接送上 wire。
+        ...(isApprovalSettledBy(d.settledBy) ? { settledBy: d.settledBy } : {}),
         ...identityFields(d),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.5.0",
+  "version": "7.7.0",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",
@@ -54,7 +54,7 @@
     "build:binary:run-local:darwin-arm64": "bun build --compile --target=bun-darwin-arm64 src/run-local.ts --outfile dist/run-local-darwin-arm64"
   },
   "dependencies": {
-    "@sema-agent/core": "^5.17.0",
+    "@sema-agent/core": "^5.21.0",
     "@sema-agent/registry-core": "^0.16.0",
     "e2b": "^2.28.0",
     "libsodium-wrappers": "^0.8.4",
@@ -69,7 +69,7 @@
     "sharp": "^0.35.3"
   },
   "devDependencies": {
-    "@sema-agent/sdk": "^6.8.0",
+    "@sema-agent/sdk": "^6.9.0",
     "@types/libsodium-wrappers": "^0.7.14",
     "@types/node": "22.10.2",
     "@types/pg": "^8.20.0",