@sema-agent/server 7.10.0 → 7.12.0

package/dist/rules-consent.js

@@ -0,0 +1,240 @@
+/**
+ * #154 车二 —— **同意车道的 server 半场**(core 5.18.0 design/179 `permission-rule-consent.ts` 的宿主侧)。
+ *
+ * core 把一条规则进店的路钉成三步:`durable approval record (pending)` → `authenticated confirmation
+ * transfer (approved)` → `principal-bound redemption (redeemed)`,而且**只有第三步**够得着写面。core 明写
+ * 「The confirmation transfer is an in-process call. **A deployment must reach it only from its
+ * authenticated approval channel**」—— 那句话是把一段责任**交给宿主**,不是一段已经完成的检查。本文件就是
+ * 那段责任的落点:
+ *
+ *  · 卡道(兑付口):一次 ask 决议携「不再询问」时,由**这里**去 prepare→confirm→redeem。人是谁 =
+ *    回决端点已验明的 principal(不是请求体里的任何字段);规则文本 = **引擎**从被裁决的命令铸的候选
+ *    (`prepareCardApproval` 不收调用方候选,core 在那条入口上已经把「写自己的规则」这件事变成不可拼写),
+ *    客户端只能说「我选第几个」。
+ *
+ *  · 导入道(CC settings):`prepare` 读用户交上来的 settings 层、铸 pending 记录 + **server 自铸的票**;
+ *    `redeem` 原子消费票、confirm、`redeemRuleBatch`。
+ *
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * 🔴 票的信任边界四条,**全部是 server 附加的**(不是 core 的语义)
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * 亲读 core 的 `mintRuleTicket`(dist,5.22.0):`return \`rt.${candidateIndex}.${recordId}\`` —— 它**没有**
+ * TTL、没有签名、没有消费位、没有载荷绑定。core 的票在**进程内**是够的(它的相邻语义是「重放同一次兑付是
+ * 幂等的」),但一条跨网络、由客户端保管、可被复制的票需要另外四样:
+ *   ① **principal 绑定** —— redeem 的已验明 principal 必须 = prepare 铸票的那一位。跨 principal redeem 与
+ *      unknown ticket **同形 404**:两者返回不同的码就是一台存在性 oracle(拿别人的票撞库能探到「它存在」)。
+ *   ② **过期** —— `RULE_IMPORT_TICKET_TTL_MS`;过期 redeem 拒。
+ *   ③ **一次性原子消费** —— 同票二次 redeem 拒,并发双 redeem **恰一成功**。判据由 SQL 的单条条件
+ *      `UPDATE … WHERE consumed_at_ms IS NULL` 回答,**禁 read-then-write**(见 store 那侧的 🔴 注)。
+ *   ④ **载荷绑定** —— redeem 应用的规则集 = prepare 时刻的快照。core 已经结构上保证了「规则文本来自记录」,
+ *      本层再加一道:票上钉着 prepare 时刻候选集的摘要,redeem 时与记录上的候选集重算比对,不符即拒 ——
+ *      于是「篡改记录再拿旧票兑付」这条路上多一道等式,而不是只靠「记录只有我们能写」这一条信念。
+ *
+ * 命名(CLAUDE.md 工厂律):`build*` = 纯数据;`create*` = 活对象。本文件的 {@link createRuleConsentLane}
+ * 返回一个带方法的束 ⇒ `create*`。
+ */
+import { randomUUID } from "node:crypto";
+import { recordFailOpen } from "./observability/fail-open.js";
+import { confirmRuleApproval, prepareCardApproval, prepareCcImport, redeemRuleBatch, redeemRuleTicket, removePersistedRule, } from "@sema-agent/core";
+import { buildRulePayloadHash } from "./plugins/permission-rule-store-sql.js";
+/** 导入票的存活窗。人从「看到预览」到「按下确认」是一次交互,不是一段会话——十分钟宽到不会误伤,
+ *  窄到一张泄漏的票不会常驻。运维旋钮暂不开(没有部署形要求它可调;要开时走 config.ts 的既有姿势)。 */
+export const RULE_IMPORT_TICKET_TTL_MS = 10 * 60_000;
+/** 可重试那一支通告给客户端的等待秒数(`state.rule_import_retry` 的 `retryAfterSec` / `Retry-After`)。
+ *  短 —— 它对应的是一次瞬时 store 抖动,不是排队。**单一真源在本文件**:放回认领时要用它判「这张票
+ *  还能不能撑过这段窗」,HTTP 层要用它填响应,两处用同一个数才谈得上「承诺兑得出来」。 */
+export const RULE_IMPORT_RETRY_AFTER_SEC = 2;
+/**
+ * **全部层合计**的候选上限(codex 交叉复审 round7 [high] 二,验真后修)。
+ *
+ * 单层 16 KiB 只管住了**请求体**,管不住**下游工作量**:紧凑的合法规则(`Bash(ls)` 十个字符)能让三层
+ * 塞进上千条候选,而 core 的 `redeemRuleBatch` 是**逐候选**跑一遍「读店 + CAS 写」的串行循环 —— 一个
+ * 已鉴权的请求就能把连接池占满、把响应撑到兆字节。全局限流器默认是关的,拦不住它(一次准入就够了)。
+ *
+ * 帽数的是 **core 已经解析好的候选**(不是我们自己再数一遍 JSON):零重复解析,而且数的正好是那条串行
+ * 循环的**真实**长度。位置在**铸票之前** —— 超限就没有票,那条昂贵的循环一次都跑不起来(代价只剩一条
+ * 已铸的 pending 记录,与任何一次没去兑付的 prepare 留下的残余同形)。
+ * 200 的取值:一份人手写的 CC settings 极少超过几十条;200 给了一个数量级的余量,又把最坏工作量钉在
+ * 「几百次 SQL」而不是「几万次」。
+ */
+export const MAX_IMPORT_CANDIDATES = 200;
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+// #203 §2 —— 撤销面(`GET /v1/rules` + `DELETE /v1/rules`)的车道半场
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+/**
+ * scope 的 **wire 形**:`global` | `project:<root>` 的判别式串(design/203 v2 §6 F5「显式成文」)。
+ *
+ * 🔴 为什么是一个串而不是把 core 的 `{kind, root}` 对象直接上 wire:这一份表示要同时当**列举结果里的
+ * 一列**、**查询参数**、**删除请求体的一个字段**和**分页游标的一部分**。四处若各用各的形,「删掉我刚才
+ * 列出来的那一行」就变成一次跨形状翻译 —— 而那正是最容易漂的地方。判别式串在四处逐字相同,而且
+ * `project:` 前缀让「这条规则是项目内的」在一眼扫日志时就成立。
+ *
+ * `root` 里可以含冒号(路径合法),所以只切**第一个**冒号 —— 用 `split(":")` 取 [1] 会把
+ * `project:/a:b` 悄悄截成 `/a`,那是一条**放宽面**上的静默改写(更短的 root 覆盖更多 cwd)。
+ */
+export function serializeRuleScope(scope) {
+    return scope.kind === "global" ? "global" : `project:${scope.root}`;
+}
+/** {@link serializeRuleScope} 的逆。读不出形 ⇒ `undefined`(调用方 400,绝不猜一个 global 出来 ——
+ *  猜 global 会把一次「删项目内规则」的请求变成一次删不掉任何东西的 no-op,或者更糟)。 */
+export function parseRuleScope(text) {
+    if (text === "global")
+        return { kind: "global" };
+    if (!text.startsWith("project:"))
+        return undefined;
+    const root = text.slice("project:".length);
+    // 空 root 硬拒:`{kind:"project", root:""}` 在 core 的 `pathWithinRoot` 下**包含每一个 cwd**
+    // (空前缀包含一切)——一条项目内规则就此悄悄升成全局规则(cc-import 那侧同判据,同一条 codex 发现)。
+    return root === "" ? undefined : { kind: "project", root };
+}
+export function createRuleConsentLane(stores, opts) {
+    const deps = { provider: stores.provider, approvals: stores.approvals };
+    const ticketTtlMs = opts?.ticketTtlMs ?? RULE_IMPORT_TICKET_TTL_MS;
+    const newTicketId = opts?.newTicketId ?? (() => randomUUID());
+    return {
+        async persistCardRule(input) {
+            // 🔴 候选**由引擎铸**(core `prepareCardApproval` 不收调用方候选;那条入口上「写自己的规则」
+            // 结构上不可拼写)。本层只把「人选了哪一个」翻译成下标。
+            const prepared = await prepareCardApproval({
+                principal: input.principal,
+                toolName: input.toolName,
+                command: input.command,
+                ...(input.toolCallId !== undefined ? { toolCallId: input.toolCallId } : {}),
+                ...(input.boundInputHash !== undefined ? { boundInputHash: input.boundInputHash } : {}),
+                ...(input.scope !== undefined ? { scope: input.scope } : {}),
+                deps,
+            });
+            if (prepared === undefined) {
+                return { ok: false, reason: "no-candidates", detail: "the rule lane cannot speak for this command (compound / redirection / unsupported tool)" };
+            }
+            const index = prepared.candidates.findIndex((c) => c.rule === input.ruleText);
+            const ticket = index < 0 ? undefined : prepared.tickets[index];
+            if (index < 0 || ticket === undefined) {
+                return { ok: false, reason: "unknown-candidate", detail: "the chosen rule text is not one the engine minted for this command" };
+            }
+            const confirmed = await confirmRuleApproval({ approvalId: prepared.approvalId, principal: input.principal, selectedCandidate: index, deps });
+            if (!confirmed.ok)
+                return { ok: false, reason: "confirm-refused", detail: confirmed.reason };
+            const redeemed = await redeemRuleTicket({ ticket, principal: input.principal, deps });
+            if (redeemed.status !== "redeemed")
+                return { ok: false, reason: "redeem-refused", detail: redeemed.reason };
+            return { ok: true, rule: redeemed.rule, rev: redeemed.rev, alreadyRedeemed: redeemed.alreadyRedeemed };
+        },
+        async prepareImport(principal, layers) {
+            // core 的 `CcImportLayer.readFile` 是一条**注入的**读口 —— 云端部署没有用户的文件系统,内容由
+            // 调用方交上来(这是本仓的部署形,不是绕过:读的仍然只是 allow 桶,拒/问桶是收紧方向、另有通道)。
+            const ccLayers = layers.map((l) => ({
+                layer: l.layer,
+                path: l.path,
+                root: l.root,
+                readFile: async () => l.content,
+            }));
+            const { preview, approvalId } = await prepareCcImport({ layers: ccLayers, principal, deps });
+            // 帽在**铸票之前**(见 {@link MAX_IMPORT_CANDIDATES}):没有票 ⇒ 那条逐候选的串行 SQL 循环跑不起来。
+            if (preview.candidates.length > MAX_IMPORT_CANDIDATES) {
+                // core 在**返回预览之前**就把 pending 记录落了盘 ⇒ 这次不做的导入会留一条永远没人要的行。
+                // 收掉它(codex round8 [medium]:被拒的 prepare 不该在共享库里长东西)。best-effort:收不掉
+                // 也只是留一条 pending 孤儿,不影响任何判决 —— 但**绝不**因此把 413 变成 500。
+                try {
+                    await stores.approvals.discardPendingRecord?.(approvalId);
+                }
+                catch (err) {
+                    recordFailOpen("server.rules.rejected-prepare-row-left", err instanceof Error ? err.message : String(err));
+                }
+                return { ok: false, reason: "too-many-candidates", candidates: preview.candidates.length };
+            }
+            const minted = await stores.tickets.mint({ ticketId: newTicketId(), principal, approvalId, candidates: preview.candidates, ttlMs: ticketTtlMs });
+            return { ok: true, preview, ticket: minted.ticketId, expiresAtMs: minted.expiresAtMs };
+        },
+        async redeemImport(principal, ticket) {
+            // ①②③ 一次原子**认领**同时回答(principal 绑定 / 未过期 / 未认领);四类拒绝在 wire 面同形。
+            const consumed = await stores.tickets.consume(ticket, principal);
+            if (!consumed.ok)
+                return { ok: false, reason: "ticket-unusable", detail: consumed.reason };
+            // 🔴 codex round1 [high] 一(验真后修):认领**之后**的每一步都可能失败,而旧形把认领当终局 ⇒
+            // 一次 store 抖动就永久烧掉这张票,客户端拿到与「票不存在」同形的 404,重试无门。
+            // 处置:裁定性拒绝(载荷被篡改 / 记录不存在)**留着**认领(重试不改判);不确定/瞬时失败**放回**
+            // 认领并标 `retryable`。放回不打开双兑付的门(认领仍是单持有者),兑付腿本身按 core 的设计幂等。
+            // 🔴 codex 交叉复审 round3 [high] 一(验真后修):返回值是**「认领确实放回去了吗」**,不是 void。
+            // 旧形无条件回 `retryable: true`,而释放本身也可能失败(同一场 store 故障往往两跳一起挂)——
+            // 那就变成对客户端**撒谎**:它拿着一张其实已经烧掉的票去重试,只会收到 404,人的确认永久丢失。
+            // 判据必须是「释放**确认**成功」;没确认就不许承诺重试(如实按不可重试报,四类同形 404)。
+            const releaseClaim = async () => {
+                try {
+                    return await stores.tickets.release(ticket, principal, RULE_IMPORT_RETRY_AFTER_SEC * 1000);
+                }
+                catch (err) {
+                    // 放不回去 = 回到「认领即烧票」的旧形(属主这一轮不能重试,票随 TTL 消失)。**不**把一次
+                    // 已经失败的请求再变成一次抛错;但也**不**静默 —— 登记的 F 类兜底,理由逐字见 tag 词表。
+                    recordFailOpen("server.rules.ticket-claim-release-failed", err instanceof Error ? err.message : String(err));
+                    return false;
+                }
+            };
+            /** 「不确定」那一支的统一收口:**释放确认成功**才承诺可重试。 */
+            const indeterminate = async (detail) => {
+                // 放回之后这张票至少要能撑过我们通告的等待窗 —— 撑不过就不承诺重试(见 store 侧 `release` 头注)。
+                const released = await releaseClaim();
+                return { ok: false, reason: "record-unusable", detail, ...(released ? { retryable: true } : {}) };
+            };
+            try {
+                // ④ 载荷绑定:记录上的候选集必须与铸票时刻的快照同摘要。
+                const record = await stores.approvals.get(consumed.approvalId);
+                if (record === undefined)
+                    return { ok: false, reason: "record-unusable", detail: "the approval record behind this ticket is gone" };
+                if (buildRulePayloadHash(record.candidates) !== consumed.payloadHash) {
+                    return { ok: false, reason: "payload-mismatch", detail: "the approval record's candidates changed after the ticket was minted" };
+                }
+                // 🔴 确认是**一次性状态跃迁**,不是每次兑付都要过的门:重试一张**放回过认领**的票时,记录
+                // 早已不是 `pending` 了(core 的崩溃序:`redeemRuleTicket` 在调用写面**之前**就把记录推到
+                // `redeemed`,所以哪怕一个候选都没落地,状态也已经变了)。对已确认的记录再调一次
+                // `confirmRuleApproval` 会拿到 `not_pending` —— 把它当拒绝就等于「放回了认领却永远兑不动」,
+                // round1/round3/round5 那一串修复到此全部白做。判据用记录**自己的状态**,不是猜错误串。
+                if (record.state === "pending") {
+                    const confirmed = await confirmRuleApproval({ approvalId: consumed.approvalId, principal, deps });
+                    if (!confirmed.ok) {
+                        // `conflict` = CAS 输给了一个并发写者(瞬时);其余是裁定(记录不存在/状态不对)。
+                        if (confirmed.reason === "conflict")
+                            return await indeterminate(confirmed.reason);
+                        return { ok: false, reason: "record-unusable", detail: confirmed.reason };
+                    }
+                }
+                const result = await redeemRuleBatch({ approvalId: consumed.approvalId, principal, deps });
+                if ("status" in result) {
+                    // core 的 refused 里既有裁定也有瞬时(OCC 用尽 / 店读不出来)——分不清就按**可重试**放回:
+                    // 兑付是幂等的,多放一次认领最坏是多跑一遍同样的重放;烧掉一张真票是不可逆的。
+                    return await indeterminate(result.reason);
+                }
+                // 🔴 codex 交叉复审 round5 [high] 二(验真后修):core 的 `redeemRuleBatch` 把**逐候选**的失败
+                // 记在 `skippedAtRedeem` 里,顶层照样返回一个 ImportResult —— 只判顶层 `status` 会把「一半没落地」
+                // 当成功回 200,而认领已经烧掉,那一半再也补不回来。
+                // 为什么这条车道可以把「非空 skippedAtRedeem」一律当**不确定**:候选在 `prepareCcImport` 那一步
+                // 就已经全过了同一个验证器(过不了的进 `preview.skipped`,压根不进记录),所以兑付期的逐候选拒绝
+                // 实际只剩「店读不出/写不进 / OCC 用尽 / 隔离栅栏」这类**瞬时或异常**成因。重放是幂等的
+                // (记录里存着每个候选已铸的 dot),所以放回认领让人重试,代价上界只是再跑一遍同样的重放。
+                // 残留(如实登记):真出现一条**永久**被拒的候选时,客户端会一直拿到 503 直到票到期(10 分钟)——
+                // 有界、且不破坏任何已落地的规则;要更好得让 core 把逐候选拒绝分成瞬时/裁定两类,已列后续件。
+                if (result.skippedAtRedeem.length > 0) {
+                    return await indeterminate(`partial import: ${result.skippedAtRedeem.length} candidate(s) did not land (${result.skippedAtRedeem.map((x) => x.reason).join("; ")})`);
+                }
+                return { ok: true, result };
+            }
+            catch (err) {
+                return await indeterminate(err instanceof Error ? err.message : String(err));
+            }
+        },
+        async listRules(principal) {
+            // `list()` 已经把墓碑折算掉(`applyTombstones`)⇒ 这里拿到的就是**活着**的规则,治理面看到的
+            // 与引擎放行时看到的是同一份。空桶 = 空表 + rev 0,不是错误(「这个人没有规则」是合法状态)。
+            const stored = await stores.provider.forPrincipal(principal).list();
+            const rows = stored.rules.map((r) => ({ rule: r.rule, scope: serializeRuleScope(r.scope), tool: r.tool, match: r.match, command: r.command, adds: r.adds }));
+            rows.sort((a, b) => (a.scope < b.scope ? -1 : a.scope > b.scope ? 1 : a.rule < b.rule ? -1 : a.rule > b.rule ? 1 : 0));
+            return { rows, rev: stored.rev };
+        },
+        async removeRule(input) {
+            // 🔴 一行也不自己写:OCC 重试、墓碑铸造、`stillLive` 的读回全在 core 那条原语里,而它的语义
+            // (add-wins、observed-remove、失败必须由读回确认「什么都没写」)是 core 的单一属主。
+            return await removePersistedRule({ rule: input.rule, scope: input.scope, principal: input.principal, provider: stores.provider });
+        },
+    };
+}
+//# sourceMappingURL=rules-consent.js.map

package/dist/run-local.js

@@ -26,6 +26,16 @@
  * 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.
  *
+ * 🔴 **design/201 的 permissionMode → shellGate 翻译表 SCOPED-OUT 本腿**(设计稿 §5,显式裁定而非欠账)。
+ * 这条腿的 operator 就是亲手起这个进程的用户,它**没有 permission mode 这个概念**(一次性 CLI 收不到
+ * 客户端表态),今昔都落 core 的缺省 `shellGate: off`。给它硬塞一个 classify 档,在没有 HITL 面的形态下
+ * 等于把每一次 shell 调用送进 auto-deny —— 那不是加固,是废掉 run-local。部署治理段(上一段)照旧全接:
+ * `MANUAL_MODE_SHELL_GATE` 想要门,operator 在自己的 `.env` 里说一句就有。同族的另一条 scoped-out 是
+ * parked-revive 赎回腿(body 全盲,core 的 `InheritedGate` 以 `max(seed, live)` 兜底,自洽)。
+ * 「三腿不共享翻译点」是设计,不是漏接:名册对账钉在
+ * `test/operator-knob-client-posture-matrix.test.ts`(`shellGateForMode` 已并入构造点名册,第四条腿哪天
+ * 接上它必须同时挂矩阵腿)。
+ *
  *   Usage:  run-local "<objective>"  [--root <dir>] [--json] [--scenario <name>]
  *
  * `main()` is a thin wrapper over the testable {@link runLocal}, which takes argv + injectable
@@ -38,7 +48,7 @@ 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, NodeExecutionEnv, NodeLspManager, TtlSessionStore, CenterPromptSource, FilePromptArtifactStore, FilePromptSourceStateStore, MemoryPromptArtifactStore, MemoryPromptSourceStateStore } from "@sema-agent/core";
+import { Runner, uuidv7, parseModelMention, AdoptionError, 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";
@@ -60,7 +70,10 @@ import { pickHandsRunner, withoutExecutionEnv } from "./capabilities/hands-lane.
 import { HttpError } from "./security.js";
 import { memoryEngineBackendFor, memorySpecForRequest } from "./memory-scope.js";
 import { createMemorySyncRunner, createMemorySyncTransport } from "./memory-sync-client.js";
-import { buildPricing, cappedCeiling } from "./budget.js";
+import { buildPricing, cappedCeiling, createTracer } from "./budget.js";
+import { createSharedRunnerDeps } from "./boot/runner-deps.js";
+import { createOrgMemoryAdmissionWiring } from "./boot/org-memory.js";
+import { createPermissionDeniedMeter } from "./observability/tool-trace.js";
 import { createKeyResolver } from "./key-resolver.js";
 import { createLogger } from "./observability/logger.js";
 import { createMetrics } from "./observability/metrics.js";
@@ -389,11 +402,35 @@ export async function runLocal(argv, deps = {}) {
     // concurrent instance throws in the constructor — surface a clear message instead of a stack.
     let fileBackend;
     try {
-        fileBackend = new FileStorageBackend({ root });
+        fileBackend = new FileStorageBackend({
+            // 🔴 腐读披露座(codex 复审 R1-medium,#205 件3 连带):本批把 `sessionPolicyStore` 接进了两只
+            // Runner,而 core 对**坏掉的**策略文件是 documented fail-open —— 读不出来按「没有规则」处理。
+            // 这条 fail-open 本身是 core 的裁定(抛会让整条任务死、也会自锁修复写),但它**不许无声**
+            // (#157 安全轴纪律)。一个座覆盖 core 今天转发的三张脸,后果**各不相同**,所以文案只陈述共同事实
+            // (「一次持久读被当成缺席」)并把后果按脸分列,不下统一结论(codex R2-medium:原文案把「少了
+            // 会话规则这一层」写成「整个任务无约束」——那会误导事故定级,而且对另外两张脸根本不成立)。
+            // ENOENT 不触发(那是真缺席)。
+            root,
+            onCorruptRead: (info) => logger.warn("file_store_corrupt_read", {
+                path: info.path,
+                reason: info.reason,
+                ...(info.sessionId !== undefined ? { sessionId: info.sessionId } : {}),
+                ...(info.principal !== undefined ? { principal: info.principal } : {}),
+                note: "a durable read was treated as ABSENT because the bytes were unreadable (never a plain ENOENT). " +
+                    "Consequence depends on which store read it: session-policy = this run lost its SUBTRACTIVE session-rule " +
+                    "layer (deployment policy / hooks / shell gate still applied); session repo = a listing silently omitted " +
+                    "rows; file-snapshot = a snapshot or scope read as missing. Inspect the named path before deciding.",
+            }),
+        });
     }
     catch (e) {
         printErr(`cannot open local data dir ${root}: ${e instanceof Error ? e.message : String(e)}`);
-        printErr("(another run-local/engine instance may own it; finish it first, or use a different --root)");
+        // 🔴 core 5.23.0([3372] 件④):这个构造器的第二个拒绝面是 design/183 的 I6 adoption boot 门。
+        // 那一类失败**不能**再补「换一个 --root」这句 —— 换根 = 丢下一个迁移到一半的数据根(与
+        // `plugins/store-backend.ts` 的 local 臂同案同判)。core 的拒绝句已自带出路,上面那行已如实打印。
+        if (!(e instanceof AdoptionError)) {
+            printErr("(another run-local/engine instance may own it; finish it first, or use a different --root)");
+        }
         return 2;
     }
     const sessionStore = fileBackend.sessionStore;
@@ -496,12 +533,74 @@ export async function runLocal(argv, deps = {}) {
         ...(ctx.classification !== undefined ? { classification: ctx.classification } : {}),
         err: String(err),
     });
-    const runnerDeps = {
+    // ⚠️ `createOrgMemoryAdmissionWiring` 有一条 **throw** 路径:`MEMORY_ORG_DIRECTORY_JSON` 形坏时
+    // `parseOrgDirectoryStatic` 启动期炸(config 层按 A4 分层刻意不校验它)。server 那边炸=进程拒启,
+    // 正确;但本腿的既定 UX 是「doctor 文案 + 退 2」(同 assertGuardPatternsUsable / remote-exec-file-invalid
+    // 两处),把栈抛给在终端里敲命令的人是回归。另一条 throw(多租户 org 键 + 无目录源)在本腿**结构上
+    // 不可达**——上面已把 `REQUIRE_PRINCIPAL` 强制成 false。
+    let orgMemoryAdmission;
+    try {
+        orgMemoryAdmission = createOrgMemoryAdmissionWiring({ config, logger, metrics });
+    }
+    catch (e) {
+        printErr(`MEMORY_ORG_DIRECTORY_JSON is invalid: ${e instanceof Error ? e.message : String(e)}`);
+        printErr(`(local config root: ${root} — fix it in ${join(root, ".env")} or your shell env, or unset it)`);
+        await fileBackend.dispose();
+        return 2;
+    }
+    /**
+     * [3397]①②③ / #205 件3 —— run-local 的两份 Runner deps 走 **server 同一只共享基座**
+     * (`createSharedRunnerDeps`,main.ts:432 的同款展开)。
+     *
+     * 为什么必须收编:这两份 deps 此前各自手写同源键,而漏配**没有任何编译期或运行期信号** —— 复扫亲验
+     * 到三处真漂移:`toolResultStore` 只在主 runner(委派子代的 `ReadToolResult(ref)` 恒空,正是 core
+     * 1.219 修过的那个病在 sub 腿复发)、`config.tiers` **全文件零接线**(而上面的 `applyEffective` 真在
+     * 填它 ⇒ tier 词 / CC 别名在这条腿上解不出来)、`hooks` / `tracer` / `sessionPolicyStore` 两处都没有。
+     * 基座是一份,新增共享键不可能只挂一半。
+     *
+     * ── 逐参裁定(local 车道**真差异**保留,不为收编硬造 stub)───────────────────────────────────
+     *  · `brain` / `pricing` / `promptSource` / `executionEnvFactory` / `lspManager`:本腿真有,直供。
+     *  · `config`(基座据以取 models / roles / **tiers** / usageWindows):本腿真有 —— tiers 正是本件修的漏。
+     *  · `tracer`:`createTracer(metrics)` 真形。配额/舰队/prompt-manifest 四个可选跟踪器是 server 面的
+     *    设施,本腿没有 ⇒ 不传(不是 stub:那几个参数本就可选,缺席即该轴不记账)。
+     *  · `deploymentHooks`:`createPermissionDeniedMeter(metrics)` —— main.ts 在**没有** toolTracer 时的
+     *    同一只值(tool-trace 落库面是 server 侧设施,一次性 CLI 无处落)。
+     *  · `sessionPolicyStore`:`fileBackend.sessionPolicyStore`(core 的 File 形,其文档原话就是「本地部署
+     *    要让会话规则跨重启存活就接这里」)。E6 规则是 subtract-only ⇒ 方向只会更紧;同一个数据根上的
+     *    本地 HTTP 服务写下的规则,这条腿本就该认。
+     *  · `usageWindowStore`:与 `config.usageWindows` **成对**(main.ts 同规:两键同真同假)—— 配了窗才接
+     *    File 账本,没配窗时接一个空账本只会让 core 以为这条腿有治理窗。
+     *  · `toolResultStore`:`fileBackend.toolResultStore`(本件的主修点:现在主/子同源)。
+     *  · `orgMemoryAdmission`:`createOrgMemoryAdmissionWiring(...)` 真形。本腿 `REQUIRE_PRINCIPAL` 被强制
+     *    false(见上),所以那条多租户拒启探测结构上不可达;产物在无 center / 无 `MEMORY_ORG_DIRECTORY_JSON`
+     *    时是「resolver 缺席 + deployment 自证集」——即 `MEMORY_SCOPE=org:x` 的本地用户从此走得通自证通道。
+     *  · `backgroundAgentStore` / `mailboxStore` / `rosterStore`:**undefined** —— core 的 `FileStorageBackend`
+     *    根本不供这三个店(durable 后台子代 / tier-3 懒复活 / 持久名册都是 server+SQL 面的设施)。造个内存
+     *    冒牌货等于让 core 以为「具名子代能跨进程复活」,而一次性 CLI 的进程下一秒就没了。
+     *  · `sharedMemoryStores`:**undefined** —— 供给面只有 SQL 形(`store-backend.ts` 明写:单机造 file 形
+     *    等于给一个人的部署做「团队共享」,能力面会因此说谎)。
+     */
+    const sharedRunnerDeps = createSharedRunnerDeps({
+        config,
         brain,
-        models: config.models,
-        roles: config.roles,
         pricing,
+        tracer: createTracer(metrics),
         promptSource,
+        executionEnvFactory,
+        lspManager,
+        backgroundAgentStore: undefined,
+        mailboxStore: undefined,
+        rosterStore: undefined,
+        deploymentHooks: createPermissionDeniedMeter(metrics),
+        toolResultStore: fileBackend.toolResultStore,
+        sessionPolicyStore: fileBackend.sessionPolicyStore,
+        usageWindowStore: config.usageWindows ? fileBackend.usageWindowStore : undefined,
+        orgMemoryAdmission,
+        sharedMemoryStores: undefined,
+    });
+    const runnerDeps = {
+        ...sharedRunnerDeps,
+        // ── 以下为主 runner 的差异键(不在共享基座;逐个有因)──────────────────────────────────────
         // [931]① clay 拍:run-local=Sema 品牌本地形态,commit 尾注接 Sema 署名(core 1.300 缺省已翻转不署)。
         hands: { commitCoAuthor: "Sema <noreply@vivi-ai.com>" },
         sessionStore,
@@ -512,11 +611,6 @@ export async function runLocal(argv, deps = {}) {
         // 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,
-        ...(executionEnvFactory ? { executionEnvFactory } : {}),
-        ...(lspManager ? { lspManager } : {}),
         // design/113 C4: run-local IS the single-user host lane (cwd = --workspace ?? process.cwd()) — the CLI path where
         // CLAUDE.md project-awareness most belongs. Wire it unless explicitly disabled.
         ...(config.projectMemoryEnabled
@@ -530,7 +624,12 @@ export async function runLocal(argv, deps = {}) {
     // [1367]① fork server half(main.ts subRunner 同款):ForkRoutingSessionStore——fork/resume 形
     // (requireExisting)→ host 文件店优先(core 1.350 hostSessionFork 在宿主店 fork,拆店=响亮
     // resume.session_not_found),普通子任务 → 私有 TTL 店(throwaway 姿势保留)。
-    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 } : {}) };
+    // #205 件3:与主 runner **同一只**共享基座展开(上面那份 `sharedRunnerDeps`)——此前这里是一行手写
+    // 字面量,`toolResultStore`/`tiers`/`hooks`/`tracer`/`sessionPolicyStore` 全漏,子代 lane 静默降级。
+    // 差异键只剩会话店与两个座位;**checkpointStore 有意不给**(main.ts 的 sub 腿给它是为了子代 durable
+    // park,而本腿的 park 设施结构上不存在:一次性 CLI 没有 `/decide` 赎回腿,gated ask 由 TTY 真人当场答
+    // ——上面 `buildOnlySensitiveBaselineWarning` 传 `durableEnabled: false` 记的就是同一件事实)。
+    const subRunnerDeps = { ...sharedRunnerDeps, sessionStore: new ForkRoutingSessionStore(sessionStore, new TtlSessionStore({ defaultTtlDays: 1 / 24 })), onError: engineOnError, onAsk };
     const subRunner = new Runner(subRunnerDeps);
     // #196:无手孪生一对 —— **mirrors main.ts**(那边是 `handslessRunner` / `handslessSubRunner` 两只,同 deps
     // 摘掉 executionEnvFactory)。run-local 是同形装配点,漏这一对 = 本地 lane 上 scan/council/team 的最终
@@ -619,6 +718,14 @@ export async function runLocal(argv, deps = {}) {
         // design/129: run-local IS the pure TOC lane → session-scoped background children
         // (CC Backgrounded semantics; parity with the server's single-user posture).
         backgroundScope: "session",
+        // [1909]⑧(core 5.23.0 `TaskSpec.oneShot`,#205 件1 的**本腿**半场,codex R2-high 抓获):这条腿
+        // 是**定义上**的一次性提交 —— 本文件头注第一句就是「跑完一条任务、打印 TaskResult、退出」,
+        // `runLocal` 返回后 Runner 全被 dispose、进程即散。缺席这个键时,core 会照默认(交互态)给后台
+        // 委派 / run_workflow 发「结束回合,你会被通知」的回执,而这里**没有下一个回合**能接住那条通知 ——
+        // 那正是本键被造出来要消灭的丢结果病族(BGB drilldown case 2)。
+        // 与 HTTP 腿的差别在**来源**而不在语义:那边是调用方表态(缺席不写键),这边是**进程形态的事实**,
+        // 所以无条件为真,不看任何 body/表态(本腿根本收不到客户端表态,同 permissionMode 的 scoped-out 理由)。
+        oneShot: true,
         principal: scope, // stable local memory/identity scope (single-user TOC; --user overrides)
         // design/138 S1: enable the memory engine for this run (spec.memory is core's per-task activation half of
         // the deps.memoryBackend switch). Scope = the --user identity (default "local", the single TOC user).

package/dist/runtime-governance.js

@@ -319,9 +319,15 @@ export function applyRuntimeGovernance(base, governance) {
         const candidate = overrides.shellGate !== undefined && SHELL_GATE_RANK[overrides.shellGate] >= SHELL_GATE_RANK[governance.manualModeShellGate]
             ? overrides.shellGate
             : governance.manualModeShellGate;
-        // base 已更严 ⇒ 省略,让 base 原样保留(省略=行为等价,不 throw)。当前**装配上不可达、纯防御**:
-        // resolveSpec 的 spec 字面量从不写 shellGate,governance 是本进程里第一个产它的人(SUP 路由姿态在其**后**
-        // 才叠),所以每次真实调用的 base.shellGate 都是缺席。若将来有人给 base 种上更严的值,这里省略而不是让
+        // base 已更严 ⇒ 省略,让 base 原样保留(省略=行为等价,不 throw)。**仍然装配上不可达、纯防御**
+        // ——但论证已随 design/201 换了一条:
+        //  · 前提(改):resolveSpec 的 spec 字面量**现在会写 shellGate** —— 显式 permissionMode 的翻译档
+        //    (`shellGateForMode`,阶段④,governance 之前),所以 base.shellGate 不再恒缺席。
+        //  · 结论(不变):这一支照旧不可达。翻译表的**上限是 classify**(rank 1),而能走到这里的 candidate
+        //    下限也是 classify(旋钮词表只有 classify/always,且 candidate 已取过与 autonomy 派生值的较大者)
+        //    ⇒ candidate ≥ base 恒成立。SUP 路由姿态(resolve-spec 的 supPostureOverrides)是 governance 之
+        //    **后**才叠的,够不到这里的 base。
+        // 若将来有人给 base 种上更严的值(例:翻译表新增一个 ⇒ always 的模式词),这里省略而不是让
         // tightenTaskSpec 因「override 更松」throw——candidate 已是 autonomy 派生值与旋钮的较大者,省略它不会
         // 丢掉 autonomy 那一半(autonomy 只产 "always",即最高 rank,永远不会落进这一支)。
         if (SHELL_GATE_RANK[candidate] >= SHELL_GATE_RANK[base.shellGate ?? "off"])

package/dist/shared-memory-scope-authorizer.d.ts

@@ -0,0 +1,29 @@
+/**
+ * design/177 v2/F4 —— shared-memory 读面的**授权折叠**:principal → 可读 org scope 集。
+ *
+ * 为什么复用 {@link OrgMemoryDirectory} 而不是另立一张表:「谁属于 org:acme」在一个进程里必须只有一个
+ * 答案。core 的记忆准入 seam、`/v1/memory/*` 的属主门、以及这里的共享库读面读的是**同一个目录实例**
+ * (`createOrgMemoryAdmissionWiring` 的产物),因此共享同一份 TTL 缓存 / 退避窗 / gen 高水位——吊销窗内
+ * 三面不会公开分歧。各建各的目录 = 三个答案,那正是 design/170 §7 收编要消灭的东西。
+ *
+ * 🔴 判别联合原样透传(N3/C5 裁定的下游一致性):目录说 `unavailable` 时**绝不**折成「你不属于任何
+ * org」。前者在模型面渲染成「连接不可用,恢复前拒读」(可重试),后者渲染成「本会话没有连接任何记忆库」
+ * (终局,模型就此放弃)。两句话是相反的指令,把前者塌进后者是一次静默的 fail-open。
+ *
+ * 🔴 deployment-origin scope 的多租户切断:operator 在配置里自证的 org scope(`MEMORY_SCOPE=org:x`、
+ * 单用户部署的 projects 登记簿)只在**无租户边界**的部署里授予。多租户部署(`requirePrincipal`)下,
+ * 一条部署级声明会同时授予每一个 principal —— 那是跨租户读,不是配置便利。装配点因此按部署形态把这个
+ * 集合择净后再传进来(见 main.ts 的构造行),本模块只忠实使用它:哪些 scope 算「部署自证」是装配点的
+ * 判断,不是这里的。
+ */
+import type { SharedMemoryScopeAuthorizer } from "./plugins/shared-memory-store-sql.js";
+import type { OrgMemoryDirectory } from "./org-memory-admission.js";
+export interface SharedMemoryScopeAuthorizerOptions {
+    /** 目录实例。**必须**与 core 准入 seam / memory-policy 面同一只(见头注)。 */
+    directory: OrgMemoryDirectory;
+    /** 部署自证的 org scope(装配点已按部署形态择净;多租户下应为空)。 */
+    deploymentScopes?: readonly string[];
+}
+/** 活对象(闭包持有目录与集合)⇒ `create*`(CLAUDE.md 工厂命名律)。 */
+export declare function createSharedMemoryScopeAuthorizer(opts: SharedMemoryScopeAuthorizerOptions): SharedMemoryScopeAuthorizer;
+//# sourceMappingURL=shared-memory-scope-authorizer.d.ts.map

package/dist/shared-memory-scope-authorizer.js

@@ -0,0 +1,17 @@
+/** 活对象(闭包持有目录与集合)⇒ `create*`(CLAUDE.md 工厂命名律)。 */
+export function createSharedMemoryScopeAuthorizer(opts) {
+    const deploymentScopes = [...new Set(opts.deploymentScopes ?? [])];
+    return {
+        async resolve(principal) {
+            // principal 缺席 = 单用户部署(多租户下 core 与 HTTP 门都先要求身份)。此时唯一的授权事实就是
+            // operator 自证的那一组;目录无从查起,但这不是「不可用」——它是一个**已知的**答案。
+            if (principal === undefined)
+                return { kind: "granted", scopes: deploymentScopes };
+            const lookup = await opts.directory.lookup(principal);
+            if (lookup.kind === "unavailable")
+                return { kind: "unavailable", reason: lookup.reason };
+            return { kind: "granted", scopes: [...new Set([...deploymentScopes, ...Object.keys(lookup.scopes)])] };
+        },
+    };
+}
+//# sourceMappingURL=shared-memory-scope-authorizer.js.map

package/dist/task-settings.d.ts

@@ -70,6 +70,50 @@ export declare function effectiveThinking(reasoningEffort: unknown, ultracode: b
  *  field is the explicit per-turn intent → it WINS over a bundle defaultMode). Creates a minimal settings object when
  *  no `body.settings` bundle was sent. The result flows through {@link applyTaskSettings} (tighten-only). */
 export declare function withPermissionMode(settings: ParsedTaskSettings | undefined, mode: SettingsPermissionMode): ParsedTaskSettings;
+/**
+ * design/201 §6-1 —— 本请求的**生效** permission mode,单点。优先序逐字同 {@link withPermissionMode}:
+ * 顶层 `body.permissionMode`(本轮显式表态)赢过 bundle 的 `settings.permissions.defaultMode`;两处
+ * 都没有 ⇒ `undefined` = **无表态**(调用点据此不写键,而不是替调用方选一个默认值)。
+ *
+ * 🔴 为什么必须是一只函数:同一个「生效模式」此前在 resolve-spec 里被算了两次(hooks 腿的
+ * `permission_mode` 载荷、settings 折叠腿的 `withPermissionMode`),三审同点判定翻译表**不得**成为
+ * 第三个算点 —— 三处各算各的,任何一次优先序修订都会让三面分家,而分家在这条轴上的形态是
+ * 「壳发的 bundle bypass 在 A 面生效、在 B 面没生效」这种最难被外部发现的静默偏差。
+ */
+export declare function effectivePermissionMode(body: {
+    permissionMode?: unknown;
+}, settings: ParsedTaskSettings | undefined): SettingsPermissionMode | undefined;
+/**
+ * design/201 §2 —— 显式 permission mode → `TaskSpec.shellGate` 档位的**翻译表(单一真源)**。
+ *
+ *  · `bypassPermissions` ⇒ `"off"` —— CC `--dangerously-skip-permissions` 的对位裁定
+ *    (与 fs-write 面的 bypass 臂两面归一,见 {@link deriveSettingsPolicy})。
+ *  · `auto` ⇒ `"classify"` —— **design/201 §8 开口按施工期新披露亲裁改译**(原裁定字面是 off,
+ *    §8 保留「core auto 分类器覆盖面有新披露时可独立再裁,表驱动一行」——新披露见下段):
+ *
+ *    ⚠️ **`auto` 这一行有一条待裁的开口(design/201 §8 明列「core auto 分类器覆盖面有新披露时可独立再裁,
+ *    表驱动一行」)。施工期对抗复审给出了那条新披露,已亲读安装包核实**:
+ *      · core 只在**已经产生 `ask`** 之后才咨询分类器(`dist/core/hooks.js`:`if (input.autoMode &&
+ *        decision.action === "ask" …)`);
+ *      · 而 `shellGate:"off"` 下 core **不铸任何 shell 面的门**(`dist/core/runner/prepare-task.js` 的
+ *        `shellGate === "off"` 臂反而发一条 `classification:"shell-gate-off"` 的 onError:「真可写 Bash 挂着
+ *        却没有 shell 安全轴折叠」)。
+ *    两条合起来:`auto` × off ⇒ Bash 既不产 ask、分类器也就永不被咨询 —— off 档下「筛选权交给分类器」
+ *    不成立。故 auto 归 classify 组:分类器坐在 classify 产的 ask 之上,语义才真是「交给分类器」
+ *    (良性只读命令由分类器自动放行,其余 ask;这正是 auto 模式的本义)。发车帖向 [3378] 裁定链披露此
+ *    一行偏离;core auto 分类器若来日在 off 档下也有咨询点,可再裁回(表驱动一行)。
+ *  · `default` / `acceptEdits` / `plan` ⇒ `"classify"` —— 这一档原先由壳无条件注入 `MANUAL_MODE_SHELL_GATE`
+ *    供给(车道缺省走了 operator 通道),现在归位到表态轴。`plan` 本身 handsReadOnly(core 明写此档下
+ *    shellGate 无效),给它 classify 纯为一致性。
+ *
+ * 🔴 **入参非可选**:缺席(无表态)不是这张表的一行 —— 它的语义是「不写这个键」,只能在调用点判。
+ * 把它折进来会逼出一个 `undefined` 返回值,而那正是「写 off」与「不写」被混同的入口(core 的
+ * 缺席默认是 off,但**写**一个 off 会成为 governance 的 base,与缺席不是同一件事)。
+ *
+ * 🔴 **闭集 exhaustive switch,无 default 臂**:五个模式词是封闭词表,新增一个模式而不更新本表
+ * 是**编译错误**(#157 的安全轴纪律:词表的未知项不许有静默兜底臂)。
+ */
+export declare function shellGateForMode(effMode: SettingsPermissionMode): "off" | "classify";
 /** The validated, service-trusted subset of `SemaSettings` we project onto the spec. `env` is parsed only to REPORT
  *  it as received-but-deferred when off the host lane (never silently dropped); a MALFORMED `hooks` likewise reports
  *  deferred (submit 路径另有 400 fail-loud),valid `hooks` 进 applied shape(hook-runner 阶段一)。 */