@sema-agent/server 7.5.0 → 7.7.0

package/dist/boot/resolve-spec.js

@@ -18,15 +18,16 @@
  * 描述的代码下移进阶段②。
  */
 import { realpathSync } from "node:fs";
-import { join, posix } from "node:path";
-import { FileError, NodeExecutionEnv, QUESTION_AWAITS_RESUME, StubExecutionEnv, combinePolicies, createAllowDenyPolicy, createDurableQuestionPolicy, createSensitivePathPolicy, err, expandTiers, ok, tightenTaskSpec } from "@sema-agent/core";
-import { createDurableAskPolicy } from "../approval.js";
+import { join } from "node:path";
+import { NodeExecutionEnv, QUESTION_AWAITS_RESUME, expandTiers, tightenTaskSpec } from "@sema-agent/core";
 import { cappedCeiling } from "../budget.js";
 import { centerPromptProvider, centerIdentityAssembled } from "../capabilities/center-prompts.js";
 import { SessionEnvironmentSelection, selectEnvironmentTool } from "../capabilities/select-environment-tool.js";
 import { sendUserFileTool } from "../capabilities/send-user-file-tool.js";
 import { gateScenarioRequest, mergeUserSkills, selectScenario } from "../capabilities/scenarios.js";
+import { toolPolicyForHands } from "../capabilities/hands-lane.js";
 import { applyLongtailDefer } from "../capabilities/tool-defer.js";
+import { assertGuardPatternsUsable, buildOnlySensitiveBaselineWarning, createApprovalBaselinePolicy, createDeploymentGovernanceInputs } from "../deployment-governance.js";
 import { acceptShellScratchpadDir, buildEnvFacts, egressForRemoteExec, ensureScratchpadDir, resumeFactsForLane } from "../env-facts.js";
 import { FleetEventBus } from "../fleet/fleet-bus.js";
 import { composeHooks, createTaskHooks } from "../hooks/hook-runner.js";
@@ -49,105 +50,25 @@ import { MAX_SETTINGS_OUTPUT_STYLE_CHARS, acceptAppendSystemPrompt, applyTaskSet
 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——工具执行落到
- *  RunnerDeps.onQuestion 的 coordinator,问正在 tail 流的活人;无活流腿(sync /v1/tasks、verify/cascade、
- *  durable resume 驱动、断连后的 detach 腿)ask——durable park 原语义逐字保留(#166 后无活流腿放行执行
- *  也不会产出空答:coordinator 无 ALS ctx ⇒ 冻结 `{kind:"unavailable"}`(src/question.ts),永不悬挂;
- *  park 仍是把问题送到人面前的唯一那条腿,正当性不变、只是反事实前提换了)。
- *  工具名字面量与 server.ts 的 pre-CAS 守卫同源("AskUserQuestion",core 未根导出常量)。
- *  ⚠️ **单一属主**(复审 A2):AskUserQuestion 的 durable 判决只有这一处。任何需要「同参重建」这条判决的
- *  地方(main.ts 的 parkedReviveInheritedGate 父约束链)必须调本工厂,不得自折 core 原形——两份拷贝里
- *  只改一份正是本条 finding 的成因。**登记豁免一处**:leader worker 腿(src/leader/wire.ts provisionWorker)
- *  自折 core 原形——该腿无活体问答面可装且 leader 不 import boot 层(分层),core 原形+sentinel 即其完整
- *  语义;豁免注在彼处互指,接活体面之日必须并回本工厂。 */
-export function createDurableQuestionGate(live) {
-    if (live === undefined)
-        return createDurableQuestionPolicy();
-    return {
-        check(req) {
-            if (req.toolName !== "AskUserQuestion")
-                return { action: "allow" };
-            return live.hasLiveContext()
-                ? { action: "allow" }
-                : { action: "ask", message: "AskUserQuestion: awaiting a human answer (durable)" };
-        },
-    };
-}
-/**
- * 沙箱 lane 上**相对形**写目标的守卫补层用 env(codex 对抗复审 round1 finding 1,红先复现)。
- *
- * 缺口:沙箱 lane 的守卫策略拿不到 `rootPath`(沙箱 cwd 不是 server 能猜的,#165 裁定 1),而
- * `DeferredSandboxPathEnv.absolutePath` 对相对形一律报错。core 的 `canonicalizeTarget` 在
- * **absolutePath 失败**这一支不置 `unresolvedSymlink`,于是 `createSensitivePathPolicy` 走的是
- * 「判不了就弃权」的 `allow`(dist 亲读)。写门在场时这条腿被门的 `ask` 兜住;而
- * `bypassPermissions` / settings 缺席这几形**根本没有门**,于是 `Write(file_path: ".env")` 一路放行——
- * 而 core 的结构化写工具会把相对形按 engine 跟踪的 cwd 解析后真写下去(fs-write.js `resolveKey`)。
- *
- * 补法:**同一只** `createSensitivePathPolicy` 再铸一个实例,只把「路径→canonical key」这一步换成
- * 纯词法基准(本 env)。判定与提取(哪个参数是写目标、NotebookEdit 的 notebook_path 优先、段匹配)
- * 全部仍是 core 的,server 侧零复刻——复刻 core 的裁决逻辑正是「同源谎」那一类错误。
- *
- * 三条不可动的边界:
- *  · **绝对形一律弃权**(absolutePath 报错 ⇒ canon 失败且非 unresolvedSymlink ⇒ core 判 allow):
- *    绝对形归真身裁决那一层,#165「真身胜过名字」的裁定(域内良性软链名叫 `.ssh` 只 ask)不受影响。
- *  · **只会 deny,不会放行**:相对形自身拼写里出现的段,解析成绝对路径后仍在,所以词法命中即真命中;
- *    反过来一条名叫 `.env` 而真身良性的相对软链会被误 deny —— 方向是 fail-closed,与守卫集语义同向。
- *  · 🔴 **覆盖面到此为止:cwd 里的守卫段看不见**(codex 对抗复审 round2,验真)。本层把相对形挂在 `/`
- *    上,而工具是挂在 engine **活** cwd 上的:`cd .git` 后 `Write("config")` 真写 `<root>/.git/config`
- *    (命中缺省模式 `.git/config`),本层只看得到 `/config` ⇒ 不命中 ⇒ 弃权。同形的还有 cwd 落在
- *    `.ssh`/`.aws` 里再写叶名。**这一格今天无人裁决**(沙箱 lane ∧ 守卫集开 ∧ 写门不在场的
- *    bypass/settings 缺席两形)。收口只有两条路,都超出本件自裁范围,已上交:①(正解)一条「按当前
- *    工具调用的活 cwd/env 裁决」的引擎缝——与子代继承那条残余面同一条缝;②(代价形)守卫集开启时把
- *    沙箱 lane 的相对写目标一律 deny——那是拿「相对写从 ask 变 deny」换覆盖,有真受损方且无对应旋钮,
- *    须部署方拍板。特征化钉见 test/task-settings.test.ts(「cwd 里的守卫段」那条),别把它读成已保护。
- */
-class RelativeTargetLexicalEnv extends StubExecutionEnv {
-    /** 相对形 → `/<词法归一>`;绝对形 / 空串 / 含 NUL 一律报错(= 弃权,见类注)。 */
-    absolutePath(path) {
-        if (path.length === 0 || path.startsWith("/") || path.includes("\u0000")) {
-            return Promise.resolve(err(new FileError("not_supported", "this guard layer only adjudicates RELATIVE write targets (absolute forms are adjudicated against the real sandbox filesystem)", path)));
-        }
-        return Promise.resolve(ok(posix.normalize(`/${path}`)));
-    }
-    /** 恒「不存在」⇒ core 的 `canonicalizeNewPath` 逐级回退,最终把词法归一形当 canonical key 交给段匹配。
-     *  这里绝不能报错:报错会被 core 读成 `unresolvedSymlink` 而对**每一个**相对目标 deny(含普通文件)。 */
-    exists(_path, _abortSignal) {
-        return Promise.resolve(ok(false));
-    }
-}
 export function createResolveSpec(ctx) {
-    const { config, logger, metrics, localRoot, scenarios, principalCaps, centerRuntimeCapsResolver, getCenterPrompts, getKeyResolver, taskAttachmentStore, perSessionCwd, setSessionCwd, setSessionShellEnv, hookLlm, hookAgent, fleetBus, hookWakeBus, resumeAnchorStore, ownerAware, taskLimitCaps, taskTimeoutSec, selectEnvTool, sendUserFileToolSpec, memoryEngine, durableEnabled, approvalExemptionStore, singleUserAutoAcceptBaseline, checkpointStore, deploymentHooks, imageIndex, perTaskImage, sessionEnvSelection, liveQuestionFace, } = ctx;
+    const { config, logger, metrics, localRoot, scenarios, principalCaps, centerRuntimeCapsResolver, handsLanes, getCenterPrompts, getKeyResolver, taskAttachmentStore, perSessionCwd, setSessionCwd, setSessionShellEnv, hookLlm, hookAgent, fleetBus, hookWakeBus, resumeAnchorStore, ownerAware, taskLimitCaps, taskTimeoutSec, selectEnvTool, sendUserFileToolSpec, memoryEngine, durableEnabled, approvalExemptionStore, singleUserAutoAcceptBaseline, checkpointStore, deploymentHooks, imageIndex, perTaskImage, sessionEnvSelection, liveQuestionFace, } = ctx;
     // ── #177 的两件 boot 期收口(把守卫集搬到 governance 拍之后才成立的两条)────────────────────────
     //
     // ① 守卫集的**编译**从此每个请求都发生(旧家只在 default/auto/acceptEdits 三个模式臂里发生)。
-    //    core 的 `compilePatterns` 对「一个路径段都没有」的模式(`"/"`、`"//"`)THROW,那条 throw 在旧家
-    //    还会被 `applyTaskSettings` 的 catch 误标成「settings 不能放松部署策略」的 422;搬家后它会变成
-    //    **每一个任务一条 500**,且运维从错误里看不出是自己的 env 写错了。这里在 boot 期先编译一次:
-    //    非法旋钮值当场炸在启动上(与 config.ts 的 env fail-loud 同族),指名键与 core 的原因。
-    //    env 只是编译期的占位(compilePatterns 不碰它),真裁决用的是每请求按 lane 铸的那一个。
-    if (config.sensitiveWritePatterns.length > 0) {
-        try {
-            createSensitivePathPolicy({ env: new StubExecutionEnv(), patterns: config.sensitiveWritePatterns });
-        }
-        catch (e) {
-            throw new Error(`SENSITIVE_WRITE_PATTERNS is not a usable guard set: ${e instanceof Error ? e.message : String(e)}`);
-        }
-    }
+    //    非法旋钮值必须当场炸在启动上而不是每任务一条 500 —— 判据与文案随 design/181 件一搬进构造口
+    //    (`assertGuardPatternsUsable`),赎回腿/run-local 装配时调同一只,三腿同得。
+    assertGuardPatternsUsable(config);
     // ② governance 拍的 DENY 基线让 `spec.toolPolicy` 在**任何**客户端表态下都在场,于是 core 的
     //    「write-capable hand tools are present but UNGATED」那条 onError 不再触发(core 判据是
     //    `policyLayers.length > 0`,prepare-task dist 亲读)。它此前是「部署一个门都没接」这个 misconfig
     //    的唯一信号,而守卫集只挡那二十来个路径段、其余写目标照旧无裁决 —— 信号不能因为本件静默消失。
     //    条件 = 两条产 toolPolicy 的腿都不在场(durable 门关 ∧ 单用户 auto-accept 基线不适用),即修前
     //    `spec.toolPolicy` 恒缺席的那一形;三个量都是 boot 常量,所以这里说一次而不是每任务说一次。
-    if (config.sensitiveWritePatterns.length > 0 && !durableEnabled && !singleUserAutoAcceptBaseline) {
-        logger.warn("tool_policy_only_sensitive_baseline", {
-            detail: "the sensitive-path DENY baseline (SENSITIVE_WRITE_PATTERNS) is this deployment's ONLY tool policy — writes outside the guarded segments are unadjudicated, and core's own UNGATED warning no longer fires because a policy is now always present",
-            remedy: "wire an approval face (DURABLE_APPROVAL / APPROVAL_REQUIRE with a store) or accept the single-user auto-accept baseline",
-            guardedPatterns: config.sensitiveWritePatterns.length,
-        });
-    }
+    //    判据与文案随 design/181 件三搬进构造口(`buildOnlySensitiveBaselineWarning`),run-local 腿调同
+    //    一只 —— 本处零行为变化(条件与字段逐字同前)。
+    const onlySensitiveBaseline = buildOnlySensitiveBaselineWarning(config, { durableEnabled, singleUserAutoAcceptBaseline });
+    if (onlySensitiveBaseline)
+        logger.warn(onlySensitiveBaseline.event, onlySensitiveBaseline.fields);
     // Deployment-owned mapping. Tools/prompt/skills come from the selected scenario (assembled once,
     // bound per request); identity/session/policy stay server-side. Never taken from the request body.
     // design/158 A8:从 createHttpServer 实参里提出来(原地占该字面量 1,093 行中的 967 行)——
@@ -160,11 +81,15 @@ export function createResolveSpec(ctx) {
         const anchors = await resolveHistoryAnchors(body, auth);
         const spec = assembleSpecLiteral(body, auth, opts, { ...gated, ...lane, ...anchors });
         const folded = await foldGovernanceAndSettings(body, auth, spec, gated);
-        return applyImageFactsAndRouting(body, auth, folded.governed, {
+        const final = await applyImageFactsAndRouting(body, auth, folded.governed, {
             scenarioName: gated.scenarioName,
             scratchpadDir: folded.scratchpadDir,
             hostSemanticsLane: folded.hostSemanticsLane,
         });
+        // #196:登记本请求的 hands lane。**必须是最终对象**(阶段⑤/⑥ 会换新对象 —— 登记中间态 = 执行点
+        // 查不到、静默落回 full)。resume 腿也走同一条 resolveSpec,故续跑与首跑选同一只 Runner。
+        handsLanes.stamp(final, gated.hands);
+        return final;
     };
     /** 阶段①(场景/append 门):吃 请求体 + auth + `opts.leg`,吐 本请求的场景绑定(scenarioName/cap)、center-pack
      *  的**单次**快照与 append 门结论(centerDecls/appendLessPack/acceptedAppend)、objective、解析后的 settings 戳,
@@ -274,7 +199,7 @@ export function createResolveSpec(ctx) {
                 }
             }
         }
-        return { scenarioName, cap, centerDecls, appendLessPack, acceptedAppend, objective, parsedSettings, attachmentNotice };
+        return { scenarioName, cap, hands: cap.hands, centerDecls, appendLessPack, acceptedAppend, objective, parsedSettings, attachmentNotice };
     };
     /** 阶段②(settings·cwd·env):吃 请求体 + auth + 阶段①的 objective/parsedSettings,吐 taskHooks、
      *  additionalDirectories、档位展开后的 wireCatalog 与选中的 picked;副作用=per-session cwd/shellEnv 注册与
@@ -485,7 +410,7 @@ export function createResolveSpec(ctx) {
     /** 阶段④(spec 字面量):吃 请求体 + auth + `opts.leg` + 前三阶段的全部产出,吐**尚未过治理层**的 TaskSpec
      *  字面量 —— 部署方拥有的 body→TaskSpec 映射本体(compactionModel 的 fresh 腿 400 也在这一段)。 */
     const assembleSpecLiteral = (body, auth, opts, parts) => {
-        const { scenarioName, cap, centerDecls, acceptedAppend, parsedSettings, attachmentNotice, taskHooks, additionalDirectories, additionalReadDirectories, wireCatalog, picked, resumeAtEntryId, rewindFilesToEntryId, s4DefaultScopes, } = parts;
+        const { scenarioName, cap, hands, centerDecls, acceptedAppend, parsedSettings, attachmentNotice, taskHooks, additionalDirectories, additionalReadDirectories, wireCatalog, picked, resumeAtEntryId, rewindFilesToEntryId, s4DefaultScopes, } = parts;
         const spec = {
             // D-1:附件告知随 objective 进 durable 流(只有名字/mime/尺寸——**内容永不进流**,这正是
             // 「拼进 objective 是伪方案」的账要划清的线;文件名已消毒为安全字符集,无注入面)。
@@ -823,9 +748,15 @@ export function createResolveSpec(ctx) {
             // the QuestionAnswer (server.ts `body.answer` → onQuestion closure). #152([2703] 案二): the question
             // policy is LIVE-AWARE when the QuestionCoordinator is wired — a live-stream leg adjudicates `allow`
             // (the live human answers over the stream) instead of unconditionally parking; see durableQuestionPolicy.
-            toolPolicy: durableEnabled
-                ? combinePolicies(createDurableQuestionGate(liveQuestionFace), createDurableAskPolicy({
-                    requireApproval: config.approvalRequire, deny: config.approvalDeny, autoBudget: config.approvalAutoBudget, neverAuto: config.approvalNeverAuto,
+            // design/181 件一:基线的**构造**归 `createApprovalBaselinePolicy`(三腿单一属主);本处只做部署形
+            // 判断——哪一形该有 durable 轴、哪一形铺 allow-all、哪一形留 `undefined`(见下两条注)。
+            // #196 纵深(设计小票 §2b):hands=none 的场景在 spec 上叠一份 band 名单 deny —— **不是**主保证
+            // (主保证=这类任务跑在不挂 executionEnvFactory 的 Runner 上,band 根本不 mount),而是「将来
+            // 有人把它误接回有手 Runner」时的第二层。合成走 tighten-only 的 combinePolicies(TRAP #1:
+            // 直接赋值会静默丢掉下方那条 durable 审批基线 / auto-accept 座),见 capabilities/hands-lane.ts。
+            toolPolicy: toolPolicyForHands(hands, durableEnabled
+                ? createApprovalBaselinePolicy(config, {
+                    question: liveQuestionFace,
                     // The probe key is the CONTINUED session (auth.sessionId — the same id that keys the
                     // durable checkpoint /decide route). A fresh session (no body.sessionId) has no exemptions by
                     // construction; fail-closed inside the policy on a store error.
@@ -835,21 +766,22 @@ export function createResolveSpec(ctx) {
                             onExempted: (toolName, rawToolName) => logger.info("approval_exempted", { sessionId: auth.sessionId, toolName, rawToolName }),
                         }
                         : {}),
-                }))
+                })
                 : singleUserAutoAcceptBaseline
                     // 🔴 (live finding: single-user host-lane Bash ran UNGATED, no adjudication): a
                     // single-user turnkey worker with NO expressed gate intent previously left `toolPolicy` UNDEFINED →
                     // core's write-capable hand tools mount UNADJUDICATED (core error-logs it every task; host lane has NO
                     // sandbox to fall back on). CC's trust model is auto-accept, but the GATE MECHANISM must be PRESENT
                     // (core 原则: "机制留、默认可更宽 auto-accept"). So wire an adjudicated auto-accept BASELINE
-                    // (`createAllowDenyPolicy({})` = a present, effect-aware policy that allows all): satisfies core's
-                    // `hasEffectAwareGate`, restores observability + a hook/tighten point, and the operator STILL tightens
-                    // irreversible ops via `AUTONOMY` / `commandPolicy` (layered TIGHTEN-ONLY by applyRuntimeGovernance).
+                    // (the durable-less arm of `createApprovalBaselinePolicy` = a present, effect-aware policy that allows
+                    // all): satisfies core's `hasEffectAwareGate`, restores observability + a hook/tighten point, and the
+                    // operator STILL tightens irreversible ops via `AUTONOMY` / `commandPolicy` (layered TIGHTEN-ONLY by
+                    // applyRuntimeGovernance).
                     // Interactive approval routed to the shell HITL = follow-on. 🔴 `singleUserAutoAcceptBaseline` requires
                     // ZERO gate intent — a single-user op who SET approval flags but wired no store falls to `undefined`
                     // (core warns = real misconfig, not masked); multi-tenant likewise stays `undefined` (approval required).
-                    ? createAllowDenyPolicy({})
-                    : undefined,
+                    ? createApprovalBaselinePolicy(config)
+                    : undefined),
             // Durable suspend needs both the store (here, per-task) and the opt-in scope key (multi-tenant =
             // principal; "_" when auth is off). core suspends on a policy `ask` only when these are present.
             ...(durableEnabled
@@ -925,27 +857,10 @@ export function createResolveSpec(ctx) {
                     logger: { warn: (event, fields) => logger.warn(event, { ...(fields ?? {}), lane: config.remoteExec?.provider }) },
                 }),
             };
-        const sensitivePathPolicy = config.sensitiveWritePatterns.length > 0
-            ? (() => {
-                const realTarget = createSensitivePathPolicy({
-                    env: pathAdjudication.env,
-                    patterns: config.sensitiveWritePatterns,
-                    ...(pathAdjudication.cwd !== undefined ? { rootPath: pathAdjudication.cwd } : {}),
-                });
-                // cwd 在场(host 形)⇒ 相对形已被 core 按 rootPath 解析进真身裁决,一层就够。
-                // cwd 缺席(沙箱形)⇒ 相对形在真身那一层是「判不了 ⇒ 弃权 allow」,而写门恰恰在
-                // bypass/settings 缺席这几形不在场 ⇒ 补一层纯词法的相对形守卫(见 RelativeTargetLexicalEnv)。
-                if (pathAdjudication.cwd !== undefined)
-                    return realTarget;
-                return combinePolicies(realTarget, createSensitivePathPolicy({ env: new RelativeTargetLexicalEnv(), patterns: config.sensitiveWritePatterns }));
-            })()
-            : undefined;
-        const governedBase = applyRuntimeGovernance(spec, {
-            autonomy: config.autonomy,
-            commandPolicy: config.commandPolicy,
-            ...(config.manualModeShellGate ? { manualModeShellGate: config.manualModeShellGate } : {}),
-            ...(sensitivePathPolicy ? { sensitivePathPolicy } : {}),
-        });
+        // design/181 件一:governance 实参(含守卫集预铸)归 `createDeploymentGovernanceInputs`(三腿单一
+        // 属主),**折叠属主不变**——仍是这一句 `applyRuntimeGovernance` → core `tightenTaskSpec`。每请求现调,
+        // 读的是活 config(autonomy/commandPolicy 热改;resume 腿按当前值重折,与上方审批基线同姿势)。
+        const governedBase = applyRuntimeGovernance(spec, createDeploymentGovernanceInputs(config, pathAdjudication));
         // Fold the client's per-request settings stamp onto the governed spec, TIGHTEN-ONLY (deny-wins) — AFTER
         // the approval baseline + operator governance, so the order is deployment ⊇ operator ⊇ client (each can only
         // narrow). tightenTaskSpec THROWS if the client settings would LOOSEN a stricter baseline → a 422 client error

package/dist/budget.d.ts

@@ -1,5 +1,5 @@
 /**
- * Cost / budget / trace wiring for the Runner (core 1.37) — pure, testable helpers kept out of the
+ * Cost / budget / trace wiring for the Runner (core 5.x) — pure, testable helpers kept out of the
  * auto-running main.ts:
  *   ③ buildPricing   — Model.cost catalog → injected ModelPricing (authoritative costMicroUsd).
  *   ④ createTracer    — core's content-free TraceEvents → /metrics (spend, first-token, tool calls).

package/dist/budget.js

@@ -1,5 +1,5 @@
 /**
- * Cost / budget / trace wiring for the Runner (core 1.37) — pure, testable helpers kept out of the
+ * Cost / budget / trace wiring for the Runner (core 5.x) — pure, testable helpers kept out of the
  * auto-running main.ts:
  *   ③ buildPricing   — Model.cost catalog → injected ModelPricing (authoritative costMicroUsd).
  *   ④ createTracer    — core's content-free TraceEvents → /metrics (spend, first-token, tool calls).

package/dist/capabilities/hands-lane.d.ts

@@ -0,0 +1,91 @@
+/**
+ * #196 场景 hands lane —— 「要手的场景」与「无手的场景」在装配层分家。
+ *
+ * 病根(设计小票 §1,案源 [3208]/[3209]/[3212]):core 的手带工具面是 **per-Runner 表态**
+ * (`prepare-task`:`handsEnabled = ownedEnv || deps.executionEnv`,ownedEnv 只要挂了
+ * `executionEnvFactory` 就每任务必铸)。server 此前全场景共享一只 runner + 一只 subRunner,
+ * 于是任何 REMOTE_EXEC 部署里,声明 clone-free 的 `scan`、只有 `run_council` 的评审团、
+ * 零工具人格的 team 成员,最终 roster 都被并集进全量可写手带(Bash/Edit/Write/…)。
+ *
+ * 本模块提供三件:
+ *  ① {@link ScenarioHands} 判别位 + {@link pickHandsRunner} 的**穷举** switch —— 新场景不表态 = 编译红,
+ *     不是静默继承 full(词表闭集纪律)。
+ *  ② {@link HANDS_EXCLUSIVE_TOOL_NAMES} + {@link handsDenyPolicy} —— 纵深:hands=none 的任务即便被误接到
+ *     有手 Runner 上,手独占名单逐一 deny。**不是**主保证(主保证是根本不挂 factory ⇒ 工具面不可见)。
+ *  ③ {@link createHandsLaneRegistry} —— resolveSpec 产出 spec 与执行点选 Runner 之间的 lane 传递。
+ */
+import { type Runner, type TaskSpec, type ToolPolicy } from "@sema-agent/core";
+/** 场景对手带工具面的表态(闭集)。`full` = core 手带 band 照常 mount;`none` = 不挂 executionEnvFactory 的 Runner。 */
+export type ScenarioHands = "full" | "none";
+/**
+ * 无手孪生 Runner 的 deps 构造:把 `executionEnvFactory` **摘键**(不是置 undefined)。
+ * 摘键让「这只 Runner 没有手」在 deps 字面量上自证;置 undefined 留下一个值为 undefined 的键,
+ * 与 core 现在的 `deps.executionEnvFactory ||` 判读结果相同,但把正确性寄托在真值判断上。
+ */
+export declare function withoutExecutionEnv<T extends {
+    executionEnvFactory?: unknown;
+}>(deps: T): Omit<T, "executionEnvFactory">;
+/** 一对 Runner:同 deps,唯一差别是 `handsless` 不挂 `executionEnvFactory`。 */
+export interface HandsRunnerPair {
+    full: Runner;
+    handsless: Runner;
+}
+/** 按场景表态取 Runner。**穷举 switch**:`ScenarioHands` 加词而此处不改 = 编译错(无 default 臂)。 */
+export declare function pickHandsRunner(hands: ScenarioHands, pair: HandsRunnerPair): Runner;
+/**
+ * core 手带 band 的工具名**全集** —— 「挂 executionEnvFactory 才出现、不挂就消失」的那一批。
+ *
+ * 两段来源,都不是拍脑袋:
+ *  · `HAND_TOOL_EFFECTS`(core 导出面,`tools/fs`)—— band 的 effect 表,11 名。
+ *  · 下方钉死补集 —— `createHandsToolkit` / 手带块还会铸但**不在** effect 表里的 5 名(实测差集,见
+ *    test/scenario-hands-lane.test.ts 的对表格:它用真 Runner 跑「有手 roster ∖ 无手 roster」,与本常量逐名对账,
+ *    core 加/改 band 成员时红,防漂移)。
+ *
+ * ⚠️ 本全集是**观测口径**(用于防漂移对账),**不是** deny 名单 —— deny 用下面的
+ * {@link HANDS_EXCLUSIVE_TOOL_NAMES},理由见那里。
+ */
+export declare const HANDS_BAND_TOOL_NAMES: readonly string[];
+/**
+ * band 里**只有手才可能出现**的那批(= deny 名单)。
+ *
+ * 🔴 codex 复审(2026-08-09 finding-3,亲验 core prepare-task):band 全集里有四件是**两用**的 ——
+ * `prepare-task` 的挂载条件是 `if (backgroundTaskToolsActive || workflowToolsActive)`,而
+ * `workflowToolsActive` 只要 `spec.selfOrchestration`(caller 可设,与场景正交)+ 部署的 workflow deps
+ * 就成立,**与手无关**。拿全集去 deny,会让「hands=none 场景 + selfOrchestration:true」的请求挂上
+ * `Workflow` 却读不到它的轮询/停止/消息/转录 —— 一个半瘫的工作流面,比不给还糟。
+ * 故 deny 名单 = 全集 ∖ 两用四件。Monitor 不在两用之列(core 的挂载条件是纯
+ * `if (backgroundTaskToolsActive)`,而它 = handsIncludeShell ∧ …,无手不成立)。
+ */
+export declare const HANDS_DUAL_USE_TOOL_NAMES: readonly string[];
+export declare const HANDS_EXCLUSIVE_TOOL_NAMES: readonly string[];
+/** 手独占名单的 deny 策略(纵深层)。名单是常量 ⇒ 每次调用产出等价策略,构造成本可忽略。 */
+export declare function handsDenyPolicy(): ToolPolicy;
+/**
+ * 把 band deny 叠到既有基线上 —— **tighten-only**。
+ *
+ * 🪤 TRAP #1(runtime-governance.ts 头注逐字):`TaskSpec.toolPolicy` 是**覆盖**而非合并
+ * (`spec.toolPolicy ?? deps.toolPolicy`),直接赋值会静默丢掉部署的 durable 审批基线 /
+ * 单用户 auto-accept 座。走 `combinePolicies(base, deny)`(deny 胜、ask 不被 allow 冲掉),
+ * 只会加 deny,永不放松。base 缺席时单挂 deny —— 该形下 band 本就不 mount,core 的
+ * "write-capable hand tools are present but UNGATED" 信号不受影响(它以 Write 在场为条件)。
+ */
+export declare function tightenWithHandsDeny(base: ToolPolicy | undefined): ToolPolicy;
+/** 装配点的取用形:`full` 原样放行基线,`none` 叠 deny。**穷举 switch**,无缺省臂。 */
+export declare function toolPolicyForHands(hands: ScenarioHands, base: ToolPolicy | undefined): ToolPolicy | undefined;
+/**
+ * 请求级 lane 登记簿 —— resolveSpec 在产出 TaskSpec 时登记本请求的场景表态,执行点凭 spec 取回选 Runner。
+ *
+ * 为什么不把 lane 写进 TaskSpec:那是 core 的类型,server 无自有位;而 `resolveSpec` 的返回形是
+ * ServiceDeps 的公开签名,80+ 测试文件在桩它 —— 改返回形的射程远大于本件。登记簿以 spec **对象身份**
+ * 为键(每请求一只新对象,并发无串台;WeakMap 弱引用,零清理欠账),由同一只 boot 装配同时交给
+ * resolveSpec 与 HTTP 执行点,配对是结构性的。
+ *
+ * 未登记 ⇒ `full`:唯一可达形是「这只 spec 不是本 resolver 产的」(测试桩)。生产链上 stamp 与 laneOf
+ * 同一实例,不存在半接;真误配时纵深 deny 仍在(见 {@link tightenWithHandsDeny})。
+ */
+export interface HandsLaneRegistry {
+    stamp(spec: TaskSpec, hands: ScenarioHands): void;
+    laneOf(spec: TaskSpec): ScenarioHands;
+}
+export declare function createHandsLaneRegistry(): HandsLaneRegistry;
+//# sourceMappingURL=hands-lane.d.ts.map

package/dist/capabilities/hands-lane.js

@@ -0,0 +1,104 @@
+/**
+ * #196 场景 hands lane —— 「要手的场景」与「无手的场景」在装配层分家。
+ *
+ * 病根(设计小票 §1,案源 [3208]/[3209]/[3212]):core 的手带工具面是 **per-Runner 表态**
+ * (`prepare-task`:`handsEnabled = ownedEnv || deps.executionEnv`,ownedEnv 只要挂了
+ * `executionEnvFactory` 就每任务必铸)。server 此前全场景共享一只 runner + 一只 subRunner,
+ * 于是任何 REMOTE_EXEC 部署里,声明 clone-free 的 `scan`、只有 `run_council` 的评审团、
+ * 零工具人格的 team 成员,最终 roster 都被并集进全量可写手带(Bash/Edit/Write/…)。
+ *
+ * 本模块提供三件:
+ *  ① {@link ScenarioHands} 判别位 + {@link pickHandsRunner} 的**穷举** switch —— 新场景不表态 = 编译红,
+ *     不是静默继承 full(词表闭集纪律)。
+ *  ② {@link HANDS_EXCLUSIVE_TOOL_NAMES} + {@link handsDenyPolicy} —— 纵深:hands=none 的任务即便被误接到
+ *     有手 Runner 上,手独占名单逐一 deny。**不是**主保证(主保证是根本不挂 factory ⇒ 工具面不可见)。
+ *  ③ {@link createHandsLaneRegistry} —— resolveSpec 产出 spec 与执行点选 Runner 之间的 lane 传递。
+ */
+import { HAND_TOOL_EFFECTS, combinePolicies, createAllowDenyPolicy } from "@sema-agent/core";
+/**
+ * 无手孪生 Runner 的 deps 构造:把 `executionEnvFactory` **摘键**(不是置 undefined)。
+ * 摘键让「这只 Runner 没有手」在 deps 字面量上自证;置 undefined 留下一个值为 undefined 的键,
+ * 与 core 现在的 `deps.executionEnvFactory ||` 判读结果相同,但把正确性寄托在真值判断上。
+ */
+export function withoutExecutionEnv(deps) {
+    const { executionEnvFactory: _handsDropped, ...rest } = deps;
+    return rest;
+}
+/** 按场景表态取 Runner。**穷举 switch**:`ScenarioHands` 加词而此处不改 = 编译错(无 default 臂)。 */
+export function pickHandsRunner(hands, pair) {
+    switch (hands) {
+        case "full":
+            return pair.full;
+        case "none":
+            return pair.handsless;
+    }
+}
+/**
+ * core 手带 band 的工具名**全集** —— 「挂 executionEnvFactory 才出现、不挂就消失」的那一批。
+ *
+ * 两段来源,都不是拍脑袋:
+ *  · `HAND_TOOL_EFFECTS`(core 导出面,`tools/fs`)—— band 的 effect 表,11 名。
+ *  · 下方钉死补集 —— `createHandsToolkit` / 手带块还会铸但**不在** effect 表里的 5 名(实测差集,见
+ *    test/scenario-hands-lane.test.ts 的对表格:它用真 Runner 跑「有手 roster ∖ 无手 roster」,与本常量逐名对账,
+ *    core 加/改 band 成员时红,防漂移)。
+ *
+ * ⚠️ 本全集是**观测口径**(用于防漂移对账),**不是** deny 名单 —— deny 用下面的
+ * {@link HANDS_EXCLUSIVE_TOOL_NAMES},理由见那里。
+ */
+export const HANDS_BAND_TOOL_NAMES = Object.freeze([
+    ...Object.keys(HAND_TOOL_EFFECTS),
+    "SendMessage",
+    "AgentTranscript",
+    "Monitor",
+    "EnterWorktree",
+    "ExitWorktree",
+]);
+/**
+ * band 里**只有手才可能出现**的那批(= deny 名单)。
+ *
+ * 🔴 codex 复审(2026-08-09 finding-3,亲验 core prepare-task):band 全集里有四件是**两用**的 ——
+ * `prepare-task` 的挂载条件是 `if (backgroundTaskToolsActive || workflowToolsActive)`,而
+ * `workflowToolsActive` 只要 `spec.selfOrchestration`(caller 可设,与场景正交)+ 部署的 workflow deps
+ * 就成立,**与手无关**。拿全集去 deny,会让「hands=none 场景 + selfOrchestration:true」的请求挂上
+ * `Workflow` 却读不到它的轮询/停止/消息/转录 —— 一个半瘫的工作流面,比不给还糟。
+ * 故 deny 名单 = 全集 ∖ 两用四件。Monitor 不在两用之列(core 的挂载条件是纯
+ * `if (backgroundTaskToolsActive)`,而它 = handsIncludeShell ∧ …,无手不成立)。
+ */
+export const HANDS_DUAL_USE_TOOL_NAMES = Object.freeze(["TaskOutput", "TaskStop", "SendMessage", "AgentTranscript"]);
+export const HANDS_EXCLUSIVE_TOOL_NAMES = Object.freeze(HANDS_BAND_TOOL_NAMES.filter((n) => !HANDS_DUAL_USE_TOOL_NAMES.includes(n)));
+/** 手独占名单的 deny 策略(纵深层)。名单是常量 ⇒ 每次调用产出等价策略,构造成本可忽略。 */
+export function handsDenyPolicy() {
+    return createAllowDenyPolicy({ deny: [...HANDS_EXCLUSIVE_TOOL_NAMES] });
+}
+/**
+ * 把 band deny 叠到既有基线上 —— **tighten-only**。
+ *
+ * 🪤 TRAP #1(runtime-governance.ts 头注逐字):`TaskSpec.toolPolicy` 是**覆盖**而非合并
+ * (`spec.toolPolicy ?? deps.toolPolicy`),直接赋值会静默丢掉部署的 durable 审批基线 /
+ * 单用户 auto-accept 座。走 `combinePolicies(base, deny)`(deny 胜、ask 不被 allow 冲掉),
+ * 只会加 deny,永不放松。base 缺席时单挂 deny —— 该形下 band 本就不 mount,core 的
+ * "write-capable hand tools are present but UNGATED" 信号不受影响(它以 Write 在场为条件)。
+ */
+export function tightenWithHandsDeny(base) {
+    const deny = handsDenyPolicy();
+    return base ? combinePolicies(base, deny) : deny;
+}
+/** 装配点的取用形:`full` 原样放行基线,`none` 叠 deny。**穷举 switch**,无缺省臂。 */
+export function toolPolicyForHands(hands, base) {
+    switch (hands) {
+        case "full":
+            return base;
+        case "none":
+            return tightenWithHandsDeny(base);
+    }
+}
+export function createHandsLaneRegistry() {
+    const lanes = new WeakMap();
+    return {
+        stamp: (spec, hands) => {
+            lanes.set(spec, hands);
+        },
+        laneOf: (spec) => lanes.get(spec) ?? "full",
+    };
+}
+//# sourceMappingURL=hands-lane.js.map

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

@@ -11,7 +11,7 @@ export interface RepoCoords {
     owner: string;
     repo: string;
 }
-/** Parse `owner/name` or a repo URL (e.g. http://host:9999/AI-Only/sema-server.git). */
+/** Parse `owner/name` or a repo URL (e.g. https://git.example.com/some-org/some-repo.git). */
 export declare function parseRepo(input: string): RepoCoords;
 /** Thin read-only Gitea API client. Built once at startup; bound to a repo per task. */
 export declare class GiteaClient {

package/dist/capabilities/repo-tools.js

@@ -1,5 +1,5 @@
 import { Type } from "typebox";
-/** Parse `owner/name` or a repo URL (e.g. http://host:9999/AI-Only/sema-server.git). */
+/** Parse `owner/name` or a repo URL (e.g. https://git.example.com/some-org/some-repo.git). */
 export function parseRepo(input) {
     const s = input.trim().replace(/\.git$/, "");
     const m = /^[a-z]+:\/\/[^/]+\/(.+)$/i.exec(s);
@@ -42,7 +42,13 @@ export class GiteaClient {
     async tree(coords, ref) {
         const { owner, repo } = coords;
         const body = (await (await this.api(`/repos/${owner}/${repo}/git/trees/${encodeURIComponent(ref)}?recursive=true&per_page=${MAX_TREE_ENTRIES}`)).json());
-        return (body.tree ?? []).filter((e) => e.type === "blob").map((e) => e.path);
+        const paths = (body.tree ?? []).filter((e) => e.type === "blob").map((e) => e.path);
+        // The upstream API caps the listing at `per_page` and reports the overflow via `truncated` — it does
+        // not report how many entries were left out. Surface that (same disclosure-marker family as
+        // `readFile`/`pullDiff` below) so a review lens never mistakes a capped tree for the whole repo.
+        return body.truncated
+            ? [...paths, `…[truncated, tree has more than ${MAX_TREE_ENTRIES} entries]`]
+            : paths;
     }
     async readFile(coords, path, ref) {
         const { owner, repo } = coords;

package/dist/capabilities/scenarios.d.ts

@@ -3,6 +3,7 @@ import type { Metrics } from "../observability/metrics.js";
 import type { Logger } from "../observability/logger.js";
 import { GiteaClient } from "./repo-tools.js";
 import { type LoadedSkill } from "./skills.js";
+import { type ScenarioHands } from "./hands-lane.js";
 /**
  * Scenario routing — a deployment serves many scenarios from one image. Each request's `scenario`
  * selects a pre-wired capability bundle: tools (incl. subagent roster) + a whole-harness prompt +
@@ -17,6 +18,14 @@ export interface ScenarioRequest {
 export interface ScenarioBundle {
     tools: ToolSpec[];
     skills: SkillSpec[];
+    /**
+     * #196:本场景对 core 手带工具面(Bash/Edit/Write/Read/Grep/…)的表态 —— **必填闭集**。
+     * `full` = 任务跑在挂了 `executionEnvFactory` 的 Runner 上(core 把 band 并集进 roster);
+     * `none` = 跑在不挂 factory 的 Runner 上(band 根本不 mount,工具 schema 对模型不可见)。
+     * 必填是设计的一半:新场景不表态 = 编译红,而不是静默继承 full(那正是 [3208] 的病灶——
+     * `scan` 声明 clone-free 四件、实际拿到全量可写手)。
+     */
+    hands: ScenarioHands;
     promptProvider?: PromptProvider;
     /** [849] 场景解释层定死的终验开关(core TaskSpec.finalVerification):bench 实测产品默认请求与
      *  bench 态差距三件之一。[2400] 起无场景定死(autonomous 退役)——纯 caller 显式旋钮;spec 组装处 OR 折入(场景只会
@@ -28,6 +37,13 @@ export interface ScenarioDeps {
     runner: Runner;
     /** In-memory runner for ephemeral sub-tasks (council lenses/arbiter) — keeps them out of TiDB. */
     subRunner: Runner;
+    /**
+     * #196:`subRunner` 的无手孪生 —— 同 deps,唯独不挂 `executionEnvFactory`。hands=none 的场景把它交给
+     * 自己造的子任务工具(council 的 lens/arbiter、team 的成员/synthesizer):那些子任务只该读仓库/讨论,
+     * 拿全量可写手是 [3208] 病灶里最意外的一支(零工具人格照拿 Bash)。取用一律走 {@link pickHandsRunner},
+     * 不在场景体内手挑 —— 判别位是唯一开关。
+     */
+    handslessSubRunner: Runner;
     model: string;
     skills: LoadedSkill[];
     repoClient?: GiteaClient;
@@ -144,21 +160,52 @@ export interface ScenarioDetail {
     tools: string[];
     /** 内建=概览(不外泄提示词资产全文);center 条目=prompt 原文(本就 ≤4KB 明文在配置域)。 */
     promptSummary: string;
+    /** **已声明**(内建恒 true;center 条目 `enabled !== false`)。⚠️ 不是「跑得动」——那是 {@link available}。 */
     enabled: boolean;
+    /**
+     * [C132] **本部署现在真跑得动吗**:后端依赖(如 repo 型场景的 `GIT_API_BASEURL`)是否就位。
+     * 与请求面的 501 拒绝臂**单一属主**({@link scenarioAvailability});false ⟺ 良性请求真吃 501。
+     */
+    available: boolean;
+    /** 机读原因键;仅 `available:false` 时在场(缺席=没有理由)。消费方按键分支,禁匹配英文文案。 */
+    unavailableReason?: ScenarioUnavailableReason;
 }
 /** 内建五场景详情。default/code/team 工厂对良性请求无副作用可真调(拿真实工具名单);code-review/scan 是
  *  fail-loud 语义(缺 GIT_API 配置/principal 即 throw)→ 探针失败落静态表兜底(表↔工厂一致性由测试锁:
  *  测试喂 fake deps 真调工厂对账工具名)。enabled 对内建恒 true(约定②)。 */
-export declare function builtinScenarioDetails(scenarios: Record<string, Scenario>, deps: Pick<ScenarioDeps, "brandIdentity">): Record<string, ScenarioDetail>;
+export declare function builtinScenarioDetails(scenarios: Record<string, Scenario>, deps: Pick<ScenarioDeps, "brandIdentity" | "repoClient">): Record<string, ScenarioDetail>;
 /** center 条目详情(有效性判定与 centerScenarios 完全同款:无效条目既不进 overlay 也不进详情——
  *  保证约定①「详情显示的来源=运行实际用的定义」永不错位)。 */
-export declare function centerScenarioDetails(specs: CenterScenarioSpec[] | undefined, builtinNames: string[]): Record<string, ScenarioDetail>;
+export declare function centerScenarioDetails(specs: CenterScenarioSpec[] | undefined, builtinNames: string[], deps: Pick<ScenarioDeps, "repoClient">): Record<string, ScenarioDetail>;
 export interface CenterScenarioSpec {
     name: string;
     toolset: string;
     prompt?: string;
     enabled?: boolean;
 }
+/** 场景不可用的**机读原因**(闭集)。新增成员必须在 {@link scenarioUnavailableMessage} 的穷举 switch
+ *  里表态——漏表态是编译错误,不是运行期 miss 臂。消费方按这个键分支,禁去正则匹配英文文案。 */
+export type ScenarioUnavailableReason = "git_client_unconfigured";
+/** 判别式:可用臂**不带**原因键(缺席=没有理由),不可用臂必带。 */
+export type ScenarioAvailability = {
+    readonly available: true;
+} | {
+    readonly available: false;
+    readonly reason: ScenarioUnavailableReason;
+};
+/**
+ * 🔴 场景可用性的**唯一属主**。列举面(`ScenarioDetail.available` / `unavailableReason`)与请求面
+ * ({@link requireRepoClient} 的 501 拒绝臂,三处调用点)都只从这里取值——两处各写一份就是本仓反复
+ * 吃过的「同一语义两个属主」病:判据一漂,列举面开始说谎而没人先红。一致性由 capabilities.test 的
+ * **对表格**逐名钉住(`available:false` ⟺ 良性请求真吃 501),而不是靠这段注释。
+ *
+ * 判据键 = **toolset**:内建详情与 center 条目都带这个字段,故两条产线天然共用同一份判据。
+ * `requiresRepo` 的 toolset 需要部署配好 git 后端(`GIT_API_BASEURL` ⇒ `deps.repoClient`)。
+ * 词表外的 toolset(内建的 `full-body`/`team`)不依赖后端 ⇒ 恒可用。
+ */
+export declare function scenarioAvailability(deps: Pick<ScenarioDeps, "repoClient">, toolset: string): ScenarioAvailability;
+/** 拒绝文案的唯一属主:闭集穷举 switch(新增原因词不在这里表态即编译红)。 */
+export declare function scenarioUnavailableMessage(reason: ScenarioUnavailableReason, scenarioLabel: string): string;
 export declare const SCENARIO_NAME_RE: RegExp;
 /**
  * Build the center-declared scenario overlay. Invalid specs are SKIPPED with a warning (never fail