@sema-agent/server 6.8.0 → 7.1.0

package/dist/memory-scope.d.ts

@@ -58,9 +58,18 @@ export declare function memoryEngineBackendFor(config: ServiceConfig, fallbackRo
  * (memory feature off for this run). Pure (testable in isolation) — main.ts's resolveSpec composes it with the
  * engine-backend presence guard.
  */
-export declare function memorySpecForRequest(scope: string | undefined, memoryWrite: boolean | undefined, defaultScopes?: string[]): {
+export declare function memorySpecForRequest(scope: string | undefined, memoryWrite: boolean | undefined, defaultScopes?: string[], 
+/** design/170 件A(#148 件3④):origin 盖章的部署形态维(N2)。`multiTenant=true`(requirePrincipal)
+ *  ⇒ 登记簿 defaultScopes 的 org 键按 **request** 盖章(条目由调用方 projectId 选定=caller 可影响的
+ *  选择器,core 准入门据此过目录判决);单用户 ⇒ 一律 deployment(operator 登记簿条目归 deployment,
+ *  否则单用户部署被自家规则整拒——v4 §0 伤害①的成立前提)。缺参=旧调用形,不盖章(整键缺席=
+ *  core legacy 语义,零迁移)。 */
+originPolicy?: {
+    multiTenant: boolean;
+}): {
     scopes: string[];
     writeScope?: string | null;
     scopeContract?: "v2";
+    scopeOrigins?: Record<string, "deployment" | "request">;
 } | undefined;
 //# sourceMappingURL=memory-scope.d.ts.map

package/dist/memory-scope.js

@@ -98,7 +98,13 @@ export function memoryEngineBackendFor(config, fallbackRoot) {
  * (memory feature off for this run). Pure (testable in isolation) — main.ts's resolveSpec composes it with the
  * engine-backend presence guard.
  */
-export function memorySpecForRequest(scope, memoryWrite, defaultScopes) {
+export function memorySpecForRequest(scope, memoryWrite, defaultScopes, 
+/** design/170 件A(#148 件3④):origin 盖章的部署形态维(N2)。`multiTenant=true`(requirePrincipal)
+ *  ⇒ 登记簿 defaultScopes 的 org 键按 **request** 盖章(条目由调用方 projectId 选定=caller 可影响的
+ *  选择器,core 准入门据此过目录判决);单用户 ⇒ 一律 deployment(operator 登记簿条目归 deployment,
+ *  否则单用户部署被自家规则整拒——v4 §0 伤害①的成立前提)。缺参=旧调用形,不盖章(整键缺席=
+ *  core legacy 语义,零迁移)。 */
+originPolicy) {
     if (!scope)
         return undefined;
     // 142-S1.5: a scope carrying a v2 typed prefix rides WITH the explicit contract marker — core validates
@@ -119,7 +125,21 @@ export function memorySpecForRequest(scope, memoryWrite, defaultScopes) {
     // 最后一层就是派生 scope=正确,不钉保持最小形)。
     const layered = extras.length > 0 ? { scopes: [scope, ...extras], writeScope: scope } : { scopes: [scope] };
     const v2 = isV2(scope) || extras.some(isV2) ? { scopeContract: "v2" } : {};
+    // 件A origin 盖章(core 5.13.0 `memory.scopeOrigins` 两格语义):只盖 org 键(非 org 不入准入判决,
+    // v4 §1);派生/env 位的 `scope` org 形只可能来自 operator 显式 MEMORY_SCOPE(memoryScopeFor 多租户
+    // 恒铸 user: 形)⇒ deployment;登记簿种子按部署形态维分格(见参数注)。零 org 键 ⇒ 整键缺席
+    // (core legacy 零迁移;非 org 部署形状逐字节不变=additive 锁)。
+    const stamped = {};
+    if (originPolicy !== undefined) {
+        if (scope.startsWith("org:"))
+            stamped[scope] = "deployment";
+        for (const extra of extras) {
+            if (extra.startsWith("org:"))
+                stamped[extra] = originPolicy.multiTenant ? "request" : "deployment";
+        }
+    }
+    const origins = Object.keys(stamped).length > 0 ? { scopeOrigins: stamped } : {};
     // memoryWrite === false(MF-30 pause)wins over the layered writeScope pin — 只读语义在有种子时同样成立。
-    return memoryWrite === false ? { ...layered, writeScope: null, ...v2 } : { ...layered, ...v2 };
+    return memoryWrite === false ? { ...layered, writeScope: null, ...v2, ...origins } : { ...layered, ...v2, ...origins };
 }
 //# sourceMappingURL=memory-scope.js.map

package/dist/org-memory-admission.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Org 记忆准入 resolver — server 侧对接 @sema-agent/core@5.13.0 `RunnerDeps.memoryScopeAdmission` seam。
+ * 授权事实来自「目录」抽象:远程腿 = config-center per-principal caps 响应里的 `orgMemory` 段(形状
+ * 同源锚 = registry-core `PrincipalOrgMemoryWire`,zod schema 直接 safeParse);单机腿 = env JSON 静态表
+ * (`MEMORY_ORG_DIRECTORY_JSON`,{@link parseOrgDirectoryStatic} 装载,启动期 fail-loud)。
+ *
+ * 判别联合 {@link OrgDirectoryLookup} 是本模块的核心裁定(设计 N3/C5):取数成功(granted,含零授权空表
+ * = 负结果)与瞬时不可用(unavailable)绝不塌成一格——granted 空表是 resolver 可以终局判决的「事实」
+ * (「这个 principal 没有这个 scope」),unavailable 必须让 core 铸瞬时码 memory.admission_required 重试,
+ * 而不是被误判成「没这个 scope」而永久拒绝。
+ *
+ * core 侧契约(RunnerDeps.memoryScopeAdmission,core types.d.ts):resolver 返回 {ok:false} ⇒ core 铸终局码
+ * memory.admission_denied;resolver throw 一个带 `retryAfterMs`(ms)属性的 Error ⇒ core 铸瞬时码
+ * memory.admission_required 并透传 retryAfterMs;{ok:true}.scopes 只能 ⊆ requested(多给 = resolver fault
+ * 会被 core 整拒)。core 只在「存在 request-origin org scope 且 principal 缺席」时自己先拒——本模块仍防御
+ * `principal === undefined` 这一支(不能信任「core 一定先拒过」这件事)。
+ */
+import type { MemoryScopeAdmission } from "@sema-agent/core";
+/**
+ * 单机腿:装载 `MEMORY_ORG_DIRECTORY_JSON`(`Record<principal, Record<orgScope, {write?}>>`)。启动期调用,
+ * **fail-loud**——任何非法直接 throw 且消息点名坏在哪个键(响亮拒是正确方向:一张半坏的授权表比拒绝
+ * 启动更危险)。principal 键复用 {@link assertPrincipalShape}(拒保留哨兵/超长租户名,与所有其它
+ * principal 入口同一道闸);scope 键必须是 `org:` 前缀、值必须是仅含可选 `write: boolean` 的 plain object。
+ */
+export declare function parseOrgDirectoryStatic(json: string): Map<string, Record<string, {
+    write?: boolean;
+}>>;
+/**
+ * 目录条目的判别联合(设计裁定 N3/C5):`granted` 是取数成功——包括零授权空表(负结果,由 resolver
+ * 判终局拒);`unavailable` 是瞬时臂(取数本身失败/形状不可信/LB 陈旧副本),只在这一支才该让 core 重试。
+ */
+export type OrgDirectoryLookup = {
+    kind: "granted";
+    scopes: Readonly<Record<string, {
+        write?: boolean;
+    }>>;
+} | {
+    kind: "unavailable";
+    reason: OrgDirectoryUnavailableReason;
+    retryAfterMs: number;
+};
+/** {@link createOrgMemoryDirectory} 的产物 —— 单一 per-principal 查表口。 */
+export interface OrgMemoryDirectory {
+    lookup(principal: string): Promise<OrgDirectoryLookup>;
+}
+export interface OrgMemoryDirectoryOptions {
+    /** 远程腿:返回 caps 响应的 `orgMemory` 段原值(unknown,本模块用 `PrincipalOrgMemoryWire.safeParse` 校验)。
+     *  返回 undefined = 响应里键整体缺席(旧 center 能力握手)⇒ unavailable("section_absent")。
+     *  throw = fetch 失败 ⇒ unavailable("fetch_failed")。
+     *  与 `staticTable` 互斥:二者恰好给一个(装配点保证;都给或都缺 = 构造期 throw,fail-loud)。 */
+    fetchSection?: (principal: string) => Promise<unknown>;
+    /** 单机腿:{@link parseOrgDirectoryStatic} 的产物。查表恒「取数成功」:缺 principal ⇒ granted 空表。 */
+    staticTable?: Map<string, Record<string, {
+        write?: boolean;
+    }>>;
+    /** granted(含负结果)缓存 TTL——ms。负结果与正授权同 TTL:未授权 principal 不该比授权 principal 打出
+     *  更多流量。默认值不在本模块(接线点决定,设计定 60_000)。 */
+    grantTtlMs: number;
+    /** 一次 unavailable 之后,同 principal 在这个窗口内的 lookup 直接返回 unavailable(不重新 fetch)——
+     *  防止对一个持续故障/未授权目标反复打 center。默认值不在本模块(接线点决定,设计定 10_000)。 */
+    unavailableBackoffMs: number;
+    /** 时间注入(测试用);默认 `Date.now`。 */
+    now?: () => number;
+}
+type OrgDirectoryUnavailableReason = "fetch_failed" | "section_absent" | "malformed" | "stale_generation";
+/**
+ * 建目录:远程腿(fetchSection,per-principal TTL 缓存 + in-flight 去重 + 退避窗 + gen 高水位)或单机腿
+ * (staticTable,恒同步成功、无 TTL/退避语义——operator 自证配置面)。两腿互斥,装配点必须恰好给一个。
+ */
+export declare function createOrgMemoryDirectory(opts: OrgMemoryDirectoryOptions): OrgMemoryDirectory;
+export interface MemoryScopeAdmissionOptions {
+    /** "audit": 判决照算但从不真拒——会拒的结果（终局 ok:false 或瞬时 throw）一律换成全额放行 + 观测记录
+     *  would-deny；真通过的判决（含 write 收窄为 null）照常返回。"enforce": 判决即结果。 */
+    mode: "audit" | "enforce";
+    /** 观测 hook。outcome ∈ "ok" | "denied" | "principal_missing" | "directory_absent" | "directory_stale" |
+     *  "directory_malformed"。audit 模式下的 would-deny 也走这里，`details.audited === true`。hook 本身绝不
+     *  允许打断准入判决——一律吞掉它可能抛出的异常。 */
+    onOutcome?: (outcome: string, details?: Record<string, unknown>) => void;
+}
+/** core 侧「瞬时不可用，重试」契约的载体：一个带 `retryAfterMs`（ms）属性的真 Error 子类，core 据此铸
+ *  memory.admission_required 终局码并透传该值。子类而非事后挂属性——避免任何宽松断言就能拿到正确类型。 */
+export declare class OrgMemoryAdmissionRetryError extends Error {
+    readonly retryAfterMs: number;
+    constructor(message: string, retryAfterMs: number);
+}
+/**
+ * `RunnerDeps.memoryScopeAdmission` 的 server 实装。deployment-origin 的 requested 项一律放行（operator
+ * 自证——v1 不做中央收窄部署声明）；request-origin 项查 `directory.lookup(principal)`：granted 时逐项核
+ * 对是否在授权集里（任何一项缺席 = 整体终局拒绝，不做部分放行——reason 只点名调用方自己请求过的 scope
+ * 串，不逐 scope 展开「为什么」，避免变成成员探针）；unavailable 时 throw 一个带 `retryAfterMs` 的
+ * {@link OrgMemoryAdmissionRetryError}。write 面独立收窄：deployment-origin 恒授，request-origin 仅当目录
+ * 条目 `write === true` 才授，否则收窄为 null（即使读侧整体放行）。
+ */
+export declare function createMemoryScopeAdmission(directory: OrgMemoryDirectory, opts: MemoryScopeAdmissionOptions): MemoryScopeAdmission;
+export {};
+//# sourceMappingURL=org-memory-admission.d.ts.map

package/dist/org-memory-admission.js

@@ -0,0 +1,224 @@
+import { PrincipalOrgMemoryWire } from "@sema-agent/registry-core";
+import { assertPrincipalShape } from "./security.js";
+const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const ORG_SCOPE_RE = /^org:\S+$/;
+/**
+ * 单机腿:装载 `MEMORY_ORG_DIRECTORY_JSON`(`Record<principal, Record<orgScope, {write?}>>`)。启动期调用,
+ * **fail-loud**——任何非法直接 throw 且消息点名坏在哪个键(响亮拒是正确方向:一张半坏的授权表比拒绝
+ * 启动更危险)。principal 键复用 {@link assertPrincipalShape}(拒保留哨兵/超长租户名,与所有其它
+ * principal 入口同一道闸);scope 键必须是 `org:` 前缀、值必须是仅含可选 `write: boolean` 的 plain object。
+ */
+export function parseOrgDirectoryStatic(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (e) {
+        throw new Error(`MEMORY_ORG_DIRECTORY_JSON is not valid JSON: ${e.message}`);
+    }
+    if (!isPlainObject(parsed)) {
+        throw new Error("MEMORY_ORG_DIRECTORY_JSON must be a JSON object: Record<principal, Record<orgScope, {write?: boolean}>>");
+    }
+    const table = new Map();
+    for (const [principal, scopesRaw] of Object.entries(parsed)) {
+        assertPrincipalShape(principal); // reserved sentinel / oversized tenant name → throws (same gate as every other principal entry point)
+        if (!isPlainObject(scopesRaw)) {
+            throw new Error(`MEMORY_ORG_DIRECTORY_JSON[${JSON.stringify(principal)}] must be an object of org scopes`);
+        }
+        const scopes = {};
+        for (const [scope, entryRaw] of Object.entries(scopesRaw)) {
+            if (!ORG_SCOPE_RE.test(scope)) {
+                throw new Error(`MEMORY_ORG_DIRECTORY_JSON[${JSON.stringify(principal)}] has an invalid org scope key ${JSON.stringify(scope)} (must match /^org:\\S+$/)`);
+            }
+            if (!isPlainObject(entryRaw)) {
+                throw new Error(`MEMORY_ORG_DIRECTORY_JSON[${JSON.stringify(principal)}][${JSON.stringify(scope)}] must be an object`);
+            }
+            for (const key of Object.keys(entryRaw)) {
+                if (key !== "write") {
+                    throw new Error(`MEMORY_ORG_DIRECTORY_JSON[${JSON.stringify(principal)}][${JSON.stringify(scope)}] has an unexpected key ${JSON.stringify(key)} (only "write" is allowed)`);
+                }
+            }
+            if (entryRaw.write !== undefined && typeof entryRaw.write !== "boolean") {
+                throw new Error(`MEMORY_ORG_DIRECTORY_JSON[${JSON.stringify(principal)}][${JSON.stringify(scope)}].write must be a boolean`);
+            }
+            scopes[scope] = entryRaw.write !== undefined ? { write: entryRaw.write } : {};
+        }
+        table.set(principal, scopes);
+    }
+    return table;
+}
+/**
+ * 建目录:远程腿(fetchSection,per-principal TTL 缓存 + in-flight 去重 + 退避窗 + gen 高水位)或单机腿
+ * (staticTable,恒同步成功、无 TTL/退避语义——operator 自证配置面)。两腿互斥,装配点必须恰好给一个。
+ */
+export function createOrgMemoryDirectory(opts) {
+    if ((opts.fetchSection !== undefined) === (opts.staticTable !== undefined)) {
+        throw new Error("createOrgMemoryDirectory requires exactly one of fetchSection or staticTable (both given or both missing)");
+    }
+    if (opts.staticTable !== undefined) {
+        const table = opts.staticTable;
+        return {
+            async lookup(principal) {
+                return { kind: "granted", scopes: table.get(principal) ?? {} };
+            },
+        };
+    }
+    if (opts.fetchSection === undefined) {
+        // Unreachable given the xor guard above (staticTable was undefined, so fetchSection must not be) — this
+        // check exists ONLY so the type checker narrows fetchSection to a function without a cast.
+        throw new Error("createOrgMemoryDirectory: fetchSection missing (invariant violated)");
+    }
+    const fetchSection = opts.fetchSection;
+    const grantTtlMs = opts.grantTtlMs;
+    const backoffMs = opts.unavailableBackoffMs;
+    const now = opts.now ?? (() => Date.now());
+    const states = new Map();
+    const inflight = new Map();
+    function markUnavailable(state, reason) {
+        state.unavailable = { until: now() + backoffMs, reason };
+        // C6: retryAfterMs never 0/negative — the window just opened, so its remaining time IS backoffMs.
+        return { kind: "unavailable", reason, retryAfterMs: Math.max(backoffMs, 1000) };
+    }
+    async function doFetch(principal, state) {
+        let raw;
+        try {
+            raw = await fetchSection(principal);
+        }
+        catch {
+            return markUnavailable(state, "fetch_failed");
+        }
+        if (raw === undefined)
+            return markUnavailable(state, "section_absent");
+        const parsed = PrincipalOrgMemoryWire.safeParse(raw);
+        if (!parsed.success) {
+            // malformed: does NOT touch state.grant — a bad shape must not refresh (or clear) an existing granted entry's
+            // timestamp; a still-fresh old grant keeps serving from cache on the NEXT lookup (checked before we ever get here).
+            return markUnavailable(state, "malformed");
+        }
+        if (state.highWaterGen !== undefined && parsed.data.gen < state.highWaterGen) {
+            // LB stale-replica defense: an older generation than one we've already seen is NEVER adopted.
+            return markUnavailable(state, "stale_generation");
+        }
+        state.highWaterGen = parsed.data.gen;
+        state.grant = { scopes: parsed.data.scopes, at: now() };
+        delete state.unavailable; // a real success clears any prior backoff window
+        return { kind: "granted", scopes: parsed.data.scopes };
+    }
+    return {
+        async lookup(principal) {
+            let state = states.get(principal);
+            if (!state) {
+                state = {};
+                states.set(principal, state);
+            }
+            const t = now();
+            // 1. Fresh grant (positive OR negative/empty result) always wins — no fetch, no backoff check.
+            if (state.grant && state.grant.at + grantTtlMs > t) {
+                return { kind: "granted", scopes: state.grant.scopes };
+            }
+            // 2. Inside an open backoff window → answer from the window WITHOUT re-fetching.
+            if (state.unavailable && state.unavailable.until > t) {
+                return { kind: "unavailable", reason: state.unavailable.reason, retryAfterMs: Math.max(state.unavailable.until - t, 1000) };
+            }
+            // 3. Grant expired (or never existed) and no active backoff → fetch, deduping concurrent callers.
+            const dup = inflight.get(principal);
+            if (dup)
+                return dup;
+            const p = doFetch(principal, state).finally(() => inflight.delete(principal));
+            inflight.set(principal, p);
+            return p;
+        },
+    };
+}
+/** core 侧「瞬时不可用，重试」契约的载体：一个带 `retryAfterMs`（ms）属性的真 Error 子类，core 据此铸
+ *  memory.admission_required 终局码并透传该值。子类而非事后挂属性——避免任何宽松断言就能拿到正确类型。 */
+export class OrgMemoryAdmissionRetryError extends Error {
+    retryAfterMs;
+    constructor(message, retryAfterMs) {
+        super(message);
+        this.retryAfterMs = retryAfterMs;
+        this.name = "OrgMemoryAdmissionRetryError";
+    }
+}
+/**
+ * `RunnerDeps.memoryScopeAdmission` 的 server 实装。deployment-origin 的 requested 项一律放行（operator
+ * 自证——v1 不做中央收窄部署声明）；request-origin 项查 `directory.lookup(principal)`：granted 时逐项核
+ * 对是否在授权集里（任何一项缺席 = 整体终局拒绝，不做部分放行——reason 只点名调用方自己请求过的 scope
+ * 串，不逐 scope 展开「为什么」，避免变成成员探针）；unavailable 时 throw 一个带 `retryAfterMs` 的
+ * {@link OrgMemoryAdmissionRetryError}。write 面独立收窄：deployment-origin 恒授，request-origin 仅当目录
+ * 条目 `write === true` 才授，否则收窄为 null（即使读侧整体放行）。
+ */
+export function createMemoryScopeAdmission(directory, opts) {
+    const emit = (outcome, details) => {
+        try {
+            opts.onOutcome?.(outcome, details);
+        }
+        catch {
+            /* an observability hook must never break admission */
+        }
+    };
+    return async ({ principal, requested, requestedWriteScope }) => {
+        const requestOriginRequested = requested.filter((r) => r.origin === "request");
+        const writeIsRequestOrigin = requestedWriteScope?.origin === "request";
+        const hasRequestOrigin = requestOriginRequested.length > 0 || writeIsRequestOrigin;
+        const fullScopes = requested.map((r) => r.scope);
+        const fullWriteScope = requestedWriteScope?.scope ?? null;
+        const admitFull = () => ({ ok: true, scopes: fullScopes, writeScope: fullWriteScope });
+        async function decide() {
+            // deployment-only requests (no request-origin item anywhere, including the write slot): nothing to
+            // look up — v1 does not centrally narrow operator-declared deployment scopes.
+            if (!hasRequestOrigin)
+                return { kind: "admit", verdict: admitFull() };
+            if (principal === undefined) {
+                // Defensive arm: core already refuses this shape itself when a request-origin org scope is present
+                // with no principal, but the resolver must not assume that guard always ran first.
+                return { kind: "deny", reason: "principal absent", outcome: "principal_missing" };
+            }
+            const lookup = await directory.lookup(principal);
+            if (lookup.kind === "unavailable") {
+                const outcome = lookup.reason === "stale_generation" ? "directory_stale" : lookup.reason === "malformed" ? "directory_malformed" : "directory_absent"; // fetch_failed | section_absent
+                return { kind: "unavailable", retryAfterMs: lookup.retryAfterMs, outcome, lookupReason: lookup.reason, details: { reason: lookup.reason } };
+            }
+            const deniedScopes = requestOriginRequested.filter((r) => !(r.scope in lookup.scopes)).map((r) => r.scope);
+            if (deniedScopes.length > 0) {
+                return {
+                    kind: "deny",
+                    reason: `org scope(s) not admitted for this principal: ${deniedScopes.join(", ")}`,
+                    outcome: "denied",
+                    details: { deniedScopes },
+                };
+            }
+            const writeScope = requestedWriteScope === null
+                ? null
+                : requestedWriteScope.origin === "deployment"
+                    ? requestedWriteScope.scope
+                    : lookup.scopes[requestedWriteScope.scope]?.write === true
+                        ? requestedWriteScope.scope
+                        : null;
+            return { kind: "admit", verdict: { ok: true, scopes: fullScopes, writeScope } };
+        }
+        const decision = await decide();
+        if (decision.kind === "admit") {
+            // C10(audit=纯观察**零**行为变化):write 收窄也是行为变化(enforce 下 harvest 静默零提交)——
+            // audit 模式对「读面通过但 write 未显式授」的判决只记 would-narrow,返回未收窄的全额;
+            // enforce 照常收窄。ok:true 分支的 writeScope 恒为 fullWriteScope 或 null(decide 只做这两值)。
+            if (opts.mode === "audit" && decision.verdict.ok && decision.verdict.writeScope !== fullWriteScope) {
+                emit("ok", { audited: true, wouldNarrowWriteScope: true });
+                return admitFull();
+            }
+            emit("ok");
+            return decision.verdict;
+        }
+        if (opts.mode === "audit") {
+            // Zero behavior change: a would-deny (terminal or transient) is overridden to a full, UNNARROWED admit —
+            // the real decision is only ever recorded via onOutcome, never enforced.
+            emit(decision.outcome, { ...decision.details, audited: true, wouldDeny: true, ...(decision.kind === "unavailable" ? { retryAfterMs: decision.retryAfterMs } : { reason: decision.reason }) });
+            return admitFull();
+        }
+        emit(decision.outcome, decision.details);
+        if (decision.kind === "deny")
+            return { ok: false, reason: decision.reason };
+        throw new OrgMemoryAdmissionRetryError(`org memory directory unavailable (${decision.lookupReason})`, decision.retryAfterMs);
+    };
+}
+//# sourceMappingURL=org-memory-admission.js.map

package/dist/question.d.ts

@@ -67,6 +67,11 @@ export declare class QuestionCoordinator {
     };
     /** Test/observability hook: number of currently-parked questions. */
     pendingCount(): number;
+    /** #152 ([2703] 案二):durable 部署上的 AskUserQuestion 判决探针——本调用点是否处在某条活流腿的
+     *  per-run 上下文里(runWithContext 包裹的 bg/SSE 腿=true;sync /v1/tasks、verify/cascade=false)。
+     *  resolve-spec 的 durable question policy 用它在**判决时**分腿:有活流 ⇒ allow(问活人),无 ⇒
+     *  ask(durable park)。ALS 让这个判断天然 per-leg,policy 组装期不必预知腿别。 */
+    hasLiveContext(): boolean;
     private countersFor;
 }
 //# sourceMappingURL=question.d.ts.map

package/dist/question.js

@@ -192,6 +192,13 @@ export class QuestionCoordinator {
     pendingCount() {
         return this.pending.size;
     }
+    /** #152 ([2703] 案二):durable 部署上的 AskUserQuestion 判决探针——本调用点是否处在某条活流腿的
+     *  per-run 上下文里(runWithContext 包裹的 bg/SSE 腿=true;sync /v1/tasks、verify/cascade=false)。
+     *  resolve-spec 的 durable question policy 用它在**判决时**分腿:有活流 ⇒ allow(问活人),无 ⇒
+     *  ask(durable park)。ALS 让这个判断天然 per-leg,policy 组装期不必预知腿别。 */
+    hasLiveContext() {
+        return this.als.getStore() !== undefined;
+    }
     countersFor(taskId) {
         let rc = this.counters.get(taskId);
         if (!rc) {

package/dist/runs.d.ts

@@ -106,6 +106,13 @@ export declare function isSessionConflictResult(result: {
  * UNCHANGED for the shell). `rewind_snapshot.unresolvable` (rewindFiles + "before": no snapshot at/above the branch
  * point) is core's third rejection with a DIFFERENT prefix — same caller-mistake shape (prepare-throw, nothing
  * billed), map it to 422 explicitly so it doesn't fall through to a 200-with-failed body.
+ *
+ * design/170 件A(#148 件4): core 5.13.0's org-memory admission rides the SAME prepare-throw pipe
+ * (GOVERNANCE_CODES). `memory.admission_denied` is TERMINAL — the principal has no grant on that tenant
+ * plane → 403 (a retry cannot change the verdict). `memory.admission_required` is TRANSIENT fail-closed —
+ * the directory is unreachable / no resolver is wired → 503 (retry later; the sync leg forwards the
+ * result's `retryAfterMs` as body `retryAfterSec`, same family shape as usage.window_exhausted). Exact
+ * codes only, no memory.* family grab — an unknown sibling stays a 200-with-failed-body until cataloged.
  */
 export declare function resumeAtHttpStatus(result: {
     status: string;

package/dist/runs.js

@@ -3,7 +3,7 @@ import { withPrincipal } from "./observability/principal-context.js";
 import { redactSecrets } from "./trace/redact.js";
 import { taskNotificationEventData, appendModelUsageDelta, appendPromptManifest, attachModelUsage } from "./trace/project.js";
 import { createLedgerSink } from "./trace/ledger-sink.js";
-import { fleetRunResiduals } from "./fleet/fleet-bus.js";
+import { fleetRunResiduals, isFleetAgentTerminalNotification } from "./fleet/fleet-bus.js";
 import { defaultSubagentTailBus, projectTailFrame } from "./fleet/subagent-tail-bus.js";
 import { emitPendingWorkflowCompletions, taskNotificationInboxEntry, taskNotificationStreamKey, NotifiedKeys } from "./orchestration/workflow-completion-inbox.js";
 /**
@@ -148,6 +148,13 @@ export function isSessionConflictResult(result) {
  * UNCHANGED for the shell). `rewind_snapshot.unresolvable` (rewindFiles + "before": no snapshot at/above the branch
  * point) is core's third rejection with a DIFFERENT prefix — same caller-mistake shape (prepare-throw, nothing
  * billed), map it to 422 explicitly so it doesn't fall through to a 200-with-failed body.
+ *
+ * design/170 件A(#148 件4): core 5.13.0's org-memory admission rides the SAME prepare-throw pipe
+ * (GOVERNANCE_CODES). `memory.admission_denied` is TERMINAL — the principal has no grant on that tenant
+ * plane → 403 (a retry cannot change the verdict). `memory.admission_required` is TRANSIENT fail-closed —
+ * the directory is unreachable / no resolver is wired → 503 (retry later; the sync leg forwards the
+ * result's `retryAfterMs` as body `retryAfterSec`, same family shape as usage.window_exhausted). Exact
+ * codes only, no memory.* family grab — an unknown sibling stays a 200-with-failed-body until cataloged.
  */
 export function resumeAtHttpStatus(result) {
     if (result.status !== "failed")
@@ -156,6 +163,10 @@ export function resumeAtHttpStatus(result) {
         return 404;
     if (result.errorCode === "rewind_snapshot.unresolvable")
         return 422;
+    if (result.errorCode === "memory.admission_denied")
+        return 403;
+    if (result.errorCode === "memory.admission_required")
+        return 503;
     if (!(result.errorCode?.startsWith("resume_at.") ?? false))
         return undefined;
     return result.errorCode === "resume_at.not_found" ? 404 : 422;
@@ -575,8 +586,11 @@ promptManifests) {
                     }
                     // id-domain alias (core): fleet child rows key by the TICK's taskId = the child's sessionId
                     // (uuid domain); the notification's task_id is the a* domain — payload.sessionId IS the tick-domain
-                    // alias, so flip by it (fallback task_id for pre-1.238 payloads / bash lane).
-                    const hadRow = fleetPublisher?.onChildTerminal(n.sessionId ?? n.task_id, n.status, n.task_id, n.toolUseId) ?? false;
+                    // alias, so flip by it (fallback task_id for pre-1.238 payloads).
+                    // [2687-cli] 幽灵行案:onChildTerminal 只对 **agent 族终态**调用(isFleetAgentTerminalNotification
+                    // 单源判别,理由与病灶链见其 doc 注)。通知帧/park 面照走,只掐 fleet 铸行。三消费点孪生同形
+                    // (http/server.ts resume 腿、routes/tasks.ts sync 腿)。
+                    const hadRow = isFleetAgentTerminalNotification(n) ? (fleetPublisher?.onChildTerminal(n.sessionId ?? n.task_id, n.status, n.task_id, n.toolUseId) ?? false) : false;
                     const parked = !legLive && Boolean(workflowCompletionInbox && spec.sessionId);
                     // diagnosability: one line per observed bg completion. hadFleetRow=false = the terminal frame was
                     // FLIP-THROUGH synthesized (the row was gone — parent settle removed it, or a bg BASH never ticked).

package/dist/runtime-governance.d.ts

@@ -86,15 +86,23 @@ export declare function compileCommandPolicy(rules: CommandRule[] | undefined):
  */
 export declare function autonomyOverrides(autonomy: Autonomy | undefined): Partial<TaskSpec>;
 /**
- * Apply the operator's runtime governance (autonomy + commandPolicy) onto a base `TaskSpec`, TIGHTEN-ONLY, in a
- * SINGLE {@link tightenTaskSpec} call: commandPolicy compiles to a `toolPolicy` override (combined onto the
- * baseline by `tightenTaskSpec` — TRAP #1), and autonomy expands to `handsReadOnly` / `shellGate` overrides
- * (TRAP #2). `tightenTaskSpec` THROWS `TaskSpecTightenError` if any override would LOOSEN a stricter base safety
- * field — surfacing a misconfiguration loudly instead of silently weakening the gate. Returns `base` untouched
- * when there is nothing to apply (no autonomy override and no commandPolicy).
+ * Apply the operator's runtime governance (autonomy + commandPolicy + manualModeShellGate) onto a base
+ * `TaskSpec`, TIGHTEN-ONLY, in a SINGLE {@link tightenTaskSpec} call: commandPolicy compiles to a `toolPolicy`
+ * override (combined onto the baseline by `tightenTaskSpec` — TRAP #1), and autonomy expands to
+ * `handsReadOnly` / `shellGate` overrides (TRAP #2). `tightenTaskSpec` THROWS `TaskSpecTightenError` if any
+ * override would LOOSEN a stricter base safety field — surfacing a misconfiguration loudly instead of silently
+ * weakening the gate. Returns `base` untouched when there is nothing to apply.
+ *
+ * #153([2713] server 分单②):`MANUAL_MODE_SHELL_GATE` 从 settings 折叠搬到这里**无条件施加**。旧家
+ * (task-settings deriveSettingsPolicy 的 default/auto/acceptEdits 三臂)让一个**部署级 tighten-only 旋钮
+ * 的生死由客户端表态在场性决定**:body 无 settings/permissionMode(cli print/headless 腿按设计不 stamp)
+ * ⇒ 旋钮静默失效(clay 实机 Monitor 案「门根本没铸」);bypassPermissions 一句话掀掉部署闸;非 host lane
+ * fsWriteGate wiring 不建 ⇒ 沙箱 lane 全失效。governance 层与 autonomy 同拍施加后三者全闭。rank 合成:
+ * autonomy 派生值与旋钮取大(ask→"always" 压过 "classify"),再对 base 只升不降(防 tightenTaskSpec throw)。
  */
 export declare function applyRuntimeGovernance(base: TaskSpec, governance: {
     autonomy?: Autonomy;
     commandPolicy?: CommandRule[];
+    manualModeShellGate?: "always" | "classify";
 }): TaskSpec;
 //# sourceMappingURL=runtime-governance.d.ts.map

package/dist/runtime-governance.js

@@ -204,19 +204,40 @@ export function autonomyOverrides(autonomy) {
             return {};
     }
 }
+/** core `tighten-task-spec` 的 SHELL_GATE_RANK 镜像(单一属主:#153 搬家后本文件是 server 侧唯一副本;
+ *  task-settings 的旧副本随 settings 折叠臂一并拆除)。tightenTaskSpec 的契约是「override 自身必须收紧」
+ *  而非「取两者较严」——低于 base 的 override 直接 throw,所以施加前要按 rank 只升不降。 */
+const SHELL_GATE_RANK = { off: 0, classify: 1, always: 2 };
 /**
- * Apply the operator's runtime governance (autonomy + commandPolicy) onto a base `TaskSpec`, TIGHTEN-ONLY, in a
- * SINGLE {@link tightenTaskSpec} call: commandPolicy compiles to a `toolPolicy` override (combined onto the
- * baseline by `tightenTaskSpec` — TRAP #1), and autonomy expands to `handsReadOnly` / `shellGate` overrides
- * (TRAP #2). `tightenTaskSpec` THROWS `TaskSpecTightenError` if any override would LOOSEN a stricter base safety
- * field — surfacing a misconfiguration loudly instead of silently weakening the gate. Returns `base` untouched
- * when there is nothing to apply (no autonomy override and no commandPolicy).
+ * Apply the operator's runtime governance (autonomy + commandPolicy + manualModeShellGate) onto a base
+ * `TaskSpec`, TIGHTEN-ONLY, in a SINGLE {@link tightenTaskSpec} call: commandPolicy compiles to a `toolPolicy`
+ * override (combined onto the baseline by `tightenTaskSpec` — TRAP #1), and autonomy expands to
+ * `handsReadOnly` / `shellGate` overrides (TRAP #2). `tightenTaskSpec` THROWS `TaskSpecTightenError` if any
+ * override would LOOSEN a stricter base safety field — surfacing a misconfiguration loudly instead of silently
+ * weakening the gate. Returns `base` untouched when there is nothing to apply.
+ *
+ * #153([2713] server 分单②):`MANUAL_MODE_SHELL_GATE` 从 settings 折叠搬到这里**无条件施加**。旧家
+ * (task-settings deriveSettingsPolicy 的 default/auto/acceptEdits 三臂)让一个**部署级 tighten-only 旋钮
+ * 的生死由客户端表态在场性决定**:body 无 settings/permissionMode(cli print/headless 腿按设计不 stamp)
+ * ⇒ 旋钮静默失效(clay 实机 Monitor 案「门根本没铸」);bypassPermissions 一句话掀掉部署闸;非 host lane
+ * fsWriteGate wiring 不建 ⇒ 沙箱 lane 全失效。governance 层与 autonomy 同拍施加后三者全闭。rank 合成:
+ * autonomy 派生值与旋钮取大(ask→"always" 压过 "classify"),再对 base 只升不降(防 tightenTaskSpec throw)。
  */
 export function applyRuntimeGovernance(base, governance) {
     const overrides = { ...autonomyOverrides(governance.autonomy) };
     const coarse = compileCommandPolicy(governance.commandPolicy);
     if (coarse)
         overrides.toolPolicy = coarse;
+    if (governance.manualModeShellGate !== undefined) {
+        const candidate = overrides.shellGate !== undefined && SHELL_GATE_RANK[overrides.shellGate] >= SHELL_GATE_RANK[governance.manualModeShellGate]
+            ? overrides.shellGate
+            : governance.manualModeShellGate;
+        // base 已更严(如 resume 重放时 base 带 always)⇒ 省略,让 base 原样保留(省略=行为等价,不 throw)。
+        if (SHELL_GATE_RANK[candidate] >= SHELL_GATE_RANK[base.shellGate ?? "off"])
+            overrides.shellGate = candidate;
+        else
+            delete overrides.shellGate;
+    }
     if (overrides.toolPolicy === undefined && overrides.handsReadOnly === undefined && overrides.shellGate === undefined) {
         return base; // nothing to govern → avoid a needless tightenTaskSpec pass
     }

package/dist/task-settings.d.ts

@@ -181,19 +181,21 @@ export interface FsWriteGateWiring {
      *  now closed). Source = config `SENSITIVE_WRITE_PATTERNS` (unset ⇒ core RECOMMENDED_SENSITIVE_PATTERNS; the
      *  set curation is core's — the server passes through). Absent/empty ⇒ no sensitive policy (pre-1.295 shape). */
     sensitivePatterns?: string[];
-    /** [1557]§四 opt-in(cli[1555]②「echo -n … > file 绕写门」缺口的部署侧补丁,core[1556] 建议):
-     *  CC manual 系模式(default/auto/acceptEdits — 见 {@link deriveSettingsPolicy})額外把
-     *  `TaskSpec.shellGate` 收紧到这个值,让 Bash 走同一 fs-write 审批链(core `bashReversibilityProbe`
-     *  在 `"classify"` 下只拦构造性不可逆命令——含 shell 重定向 `>`/`>>` 等,纯读命令白名单自动放行)。
-     *  **Absent(缺省)= 零行为变化**(config `MANUAL_MODE_SHELL_GATE` 未设置时不传本字段,pre-此批行为
-     *  byte-for-byte;这是个 tighten-only opt-in,不是默认开启——运营方需要显式选择开启)。 */
-    shellGate?: "always" | "classify";
 }
 export declare function deriveSettingsPolicy(settings: ParsedTaskSettings, gate?: FsWriteGateWiring, workflowGate?: WorkflowGateWiring): {
     toolPolicy?: ToolPolicy;
     handsReadOnly?: boolean;
     enablePlanMode?: boolean;
-    shellGate?: "always" | "classify";
 };
+/**
+ * Apply a client's parsed per-request settings onto a base `TaskSpec`, TIGHTEN-ONLY, in a SINGLE {@link
+ * tightenTaskSpec} pass (so the permission override composes deny-wins onto the baseline — TRAP #1 — and
+ * `handsReadOnly`/`onAsk` can only narrow). `tightenTaskSpec` THROWS `TaskSpecTightenError` if any override would
+ * LOOSEN a stricter base — surfaced by the caller as a 4xx (a client settings stamp that tries to widen is a
+ * client error, never a silent weakening). `model`/`outputStyle` are applied directly (model is the caller's
+ * choice WITHIN the catalog — the caller gates it before calling; outputStyle appends to the system prompt).
+ *
+ * Returns `base` untouched when the parsed settings project nothing onto the spec.
+ */
 export declare function applyTaskSettings(base: TaskSpec, settings: ParsedTaskSettings, gate?: FsWriteGateWiring, workflowGate?: WorkflowGateWiring): TaskSpec;
 //# sourceMappingURL=task-settings.d.ts.map