@sema-agent/server 7.132.0 → 7.134.0

package/dist/approval-gate-currency.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 一张停驻审批卡的「门」此刻还是不是它 —— 应答口判 `approval_stale` 与按问读口 `state` 的**同一只判官**。
+ *
+ * ## 病灶(为什么要有这一只)
+ * 问账行 `PARKED` 是终态(`approval-ask-machine.ts`:`PARKED: []`):赎回腿的单赢者是 **checkpoint 的 CAS**,取消腿动的也是 checkpoint(先 `expire` 门、再驱 run 终局),
+ * 两条腿都不写 ask 行。于是「这张卡的门还在不在」这件事只有 checkpoint 店知道;读口若只看行,就会在卡被答过 / run 被取消之后继续说 `parked` 并指路去决定,
+ * 而应答口对同一张卡早已答 `409 approval_stale`。同一件事两个读法 —— 本模块把它收成一个:读的是同一个问题、同一个来源。
+ *
+ * ## 判官
+ * 问题:**这把 gate token 是不是该会话当前待决的审批门?**(应答口的答法:`resumeCheckpoint` 的 stale 臂 —— 回显的 token ≠ 该会话当前待决的审批门 ⇒ `409 approval_stale`。)
+ *  · {@link currentApprovalGateToken} —— 该会话当前待决的审批门(审批门型优先,没有再退到任一待决行);应答口读它,读口读它,别处不再内联第二份;
+ *  · {@link readGateCurrency} —— 一把 token 对着它的读数:`current` / `absent`(店里没有这一行)/ `settled`(行在,但不再是当前待决门:已结算、已过期、被取代);
+ *  · {@link createParkedGateRead} —— 协调器读口的门读席:把读数译成读口要的四种读法({@link ParkedGateReading}),`state` 闭集不加字。
+ *
+ * ## `settled` 怎么译(读口只说 checkpoint 上有凭据的话;一条规矩)
+ * 落盘的行不受类型面约束(旧版 / 手改 / 坏体 / 更新版本 core 写下的行可带闭集外的词或坏形),所以已结算门只按**一条规矩**读:
+ *  ① 两个闭集词(行的 `status`、结算记录的种类 `settlement.kind`)各查一张穷举表,**同一查法**({@link throughTable}:只认表自己的键,非字符串不进表):
+ *    表明说 `decided` ⇒ 往下读;明说 `void` ⇒ `void`(没有人决过它,答案无处兑现 —— 已过期〔取消 / 收割〕、仍待决却不是当前门〔被取代,应答口答 stale〕、
+ *    结算种类是引擎窗到期 / 宿主 SLA 扫 / 无人可答的失败族);**表外 ⇒ `unknown`**(读不懂的词撑不起「有人决过」,也撑不起「没有人决过它」);
+ *  ② 结算赢家的门记录 `resolvedOutcome.gateOutcome` 先过 core 唯一的门记录筛 `screenGateOutcome`(**档案读法**:读回的耐久行,闭集 = 今日成员 ∪ 已退役词;
+ *    坏形记缺陷、绝不抛;本仓 `trace/project.ts` 投影同一种记录也只经这一只筛),有缺陷 ⇒ `unknown`,过了筛才读它的成员;
+ *  ③ 分类之前记录要**读得全**:有结算记录、时刻(引擎写进赢家的 `settlement.when`)是有限数、赢家绑的是这一行的调用且判词是 allow / deny(与
+ *    `findDecidedApprovalsForBinding` 同一只 {@link approvalDecisionOfWinner})—— 缺一个都是 `unknown`(**不编一个首决**;读口答 404,应答口对已结算的门答 409 `approval_stale`,两口不同判;
+ *    `void` 也要读得全:绑在别的调用上的结算说的不是这张卡);读全了再按**结算种类**表分类:人 / 策略的四个种类 ⇒ `decided`(理由取自赢家的 `reason`),其余十个 ⇒ `void`
+ *    (按种类不按当事方:跨版本稳定的是种类词,变过义的是当事方词 —— 此前版本的策略拒记 `policy_refused` + `who.party:"none"`,此后记 `"policy"`,按当事方查会把那一代合法历史记录读成 `void`);
+ *  ④ 读的只是行的内容、不碰店:内容坏到读的时候抛(行上缺了必填成员)同样是坏行 ⇒ `unknown`,不冒成店故障(读口对店故障退回 `parked`)。
+ * `unknown` 的这一类(`decision_unreadable`)带上读不出的那几处(缺陷句,非空):读口答 404 `tool_approval.not_pending`,并记一行 error(首句 + 计数)。
+ * 行没了 ⇒ `unknown`(`row_absent`;应答口 PARKED 臂的 404 `not_found.approval` 同判)。
+ *
+ * ## 盲区(core 的筛不判的两处,如实写下:一处本判官手判有限数,一处本判官也不核)
+ *  · 结算时刻 `settlement.when`:筛不判,本判官手判「有限数」;而本仓另一个读同一种记录的读者(trace 投影)把 `when` 原样放上 wire —— 同一个坏时刻,两个读者两种答法;
+ *  · 方向与配对:赢家的方向(`resolvedOutcome.decision`)与记录自己的种类 / 处置说的方向是否一致,以及种类 × 当事方的配对 —— 筛不判,本判官也不核:读口以赢家的方向为准、读的是种类。
+ * 只有坏行 / 手改行才走得到这两处。候引擎的筛把时刻、方向与种类 × 当事方配对一并判了,两个读者同时退掉各自的手判(配对今天没有手判可退 —— 它无人判)。
+ */
+import { type Checkpoint, type CheckpointToken, type SettlementKind } from "@sema-agent/core";
+import { type PendingRowBinding } from "./plugins/checkpoint-store-sql.js";
+import { type ParkedGateRead } from "./tool-approval.js";
+/** 判官要的两个店口(三后端同形;窄接口让测试与装配都不必拿整只店)。 */
+export interface GateCurrencyStore {
+    get(token: CheckpointToken): Promise<Checkpoint | null>;
+    findPendingTokenBySession(sessionId: string, scope?: string, binding?: PendingRowBinding): Promise<CheckpointToken | null | undefined>;
+}
+/**
+ * 该会话**当前待决的审批门**的 token:审批门型({@link APPROVAL_GATE_KINDS})优先 —— 同会话 `task_done` 纯 park 与新 run 的审批 park 可以并存(表无 per-session pending 唯一约束),
+ * 无序读会选中别的门型 —— 没有审批门才退到任一待决行(错门型诊断由 `/decide` 的 gate-kind 守卫点名)。应答口的 stale 臂与按问读口读这一只。
+ */
+export declare function currentApprovalGateToken(cs: Pick<GateCurrencyStore, "findPendingTokenBySession">, sessionId: string): Promise<CheckpointToken | null | undefined>;
+/** 一把 gate token 对着判官的读数。 */
+export type GateCurrency = {
+    readonly kind: "current";
+} | {
+    readonly kind: "absent";
+} | {
+    readonly kind: "settled";
+    readonly checkpoint: Checkpoint;
+};
+/** 这把 gate token 是不是它那条会话当前待决的审批门。读不出(店抛错)⇒ 原样上抛,由调用方的故障姿势处置。 */
+export declare function readGateCurrency(cs: GateCurrencyStore, gateToken: string): Promise<GateCurrency>;
+/** 一个闭集词对已结算门的读法类:有人 / 有策略决过(往下读决议),或没有人决过它。 */
+type SettledClass = "decided" | "void";
+/**
+ * 结算种类(core `SETTLEMENT_KINDS`)→ 这次结算算不算「有人 / 有策略决过」。`human_*`(人)与 `policy_*`(部署的策略)四个词是仅有的决议种类;其余十个 ——
+ * 引擎自己的窗到期 · 宿主窗 / 宿主 SLA 扫 · 无人可答的失败族 —— 没有人决过它,不读成「决议:deny」(那会让壳把一次宿主超时清算渲成「被拒绝」)。
+ * 表的键是**种类**不是当事方:种类词跨版本稳定,当事方词变过义(此前版本的策略拒记 `who.party:"none"`),按当事方查会把那一代合法历史记录读错。core 现成的两张种类表
+ * (是不是拒绝 / 有没有人评判过)答的是别的问题:`human_refused` 与 `approval_window_expired` 同是拒绝,这里一个是决议、一个不是,所以不从它们派生。
+ * 表穷举(与上面 `status` 表同形、同一查法):core 给种类闭集加词而不在此表态 ⇒ 编译红。
+ */
+export declare const SETTLEMENT_KIND_READING: Record<SettlementKind, SettledClass>;
+/** 协调器读口的门读席({@link ParkedGateRead}):装配点把 checkpoint 店递进来,协调器本身不认识 checkpoint 的形。 */
+export declare function createParkedGateRead(cs: GateCurrencyStore): ParkedGateRead;
+export {};
+//# sourceMappingURL=approval-gate-currency.d.ts.map

package/dist/approval-gate-currency.js

@@ -0,0 +1,94 @@
+import { screenGateOutcome } from "@sema-agent/core";
+import { approvalDecisionOfWinner } from "./plugins/checkpoint-store-sql.js";
+import { APPROVAL_GATE_KINDS } from "./tool-approval.js";
+export async function currentApprovalGateToken(cs, sessionId) {
+    return (await cs.findPendingTokenBySession(sessionId, undefined, { gateKinds: APPROVAL_GATE_KINDS })) ?? (await cs.findPendingTokenBySession(sessionId));
+}
+export async function readGateCurrency(cs, gateToken) {
+    const first = await cs.get(gateToken);
+    if (first === null)
+        return { kind: "absent" };
+    if (first.status !== "pending")
+        return { kind: "settled", checkpoint: first };
+    const current = await currentApprovalGateToken(cs, first.sessionId);
+    if (current === gateToken)
+        return { kind: "current" };
+    const fresh = await cs.get(gateToken);
+    return fresh === null ? { kind: "absent" } : { kind: "settled", checkpoint: fresh };
+}
+const SETTLED_GATE_READING = { resolved: "decided", expired: "void", pending: "void" };
+export const SETTLEMENT_KIND_READING = {
+    human_allowed: "decided",
+    human_refused: "decided",
+    policy_allowed: "decided",
+    policy_refused: "decided",
+    approval_window_expired: "void",
+    denial_limit_window_expired: "void",
+    park_sla_expired: "void",
+    no_approver: "void",
+    approver_unavailable: "void",
+    approver_error: "void",
+    approver_contract: "void",
+    presentation_failed: "void",
+    blanket_allow_refused: "void",
+    task_aborted: "void",
+};
+function unreadable(defects) {
+    return { kind: "unknown", why: "decision_unreadable", defects };
+}
+function throughTable(table, word, field) {
+    if (typeof word !== "string" || !Object.hasOwn(table, word))
+        return unreadable([`${field} has no reading in this server's table of its closed set`]);
+    return table[word] === "decided" ? "decided" : { kind: "void" };
+}
+function settledReading(checkpoint, gateBoundCallId) {
+    try {
+        return readSettledRow(checkpoint, gateBoundCallId);
+    }
+    catch (e) {
+        return unreadable([`the settled row could not be read (${e instanceof Error ? e.name : "non-Error throw"})`]);
+    }
+}
+function readSettledRow(checkpoint, gateBoundCallId) {
+    const byStatus = throughTable(SETTLED_GATE_READING, checkpoint.status, "checkpoint status");
+    if (byStatus !== "decided")
+        return byStatus;
+    const winner = checkpoint.resolvedOutcome;
+    const recorded = winner?.gateOutcome;
+    const [defect, ...more] = screenGateOutcome(recorded, { reading: "archive" });
+    if (defect !== undefined)
+        return unreadable([defect, ...more]);
+    const settlement = recorded?.settlement;
+    if (settlement === undefined)
+        return unreadable(["the gate record carries no settlement: no decider and no time"]);
+    if (!Number.isFinite(settlement.when))
+        return unreadable(["settlement.when is not a finite epoch-ms time"]);
+    const boundCallId = gateBoundCallId ?? (checkpoint.pendingAction.kind === "tool_approval" ? checkpoint.pendingAction.toolCallId : "");
+    const direction = approvalDecisionOfWinner(winner, boundCallId);
+    if (direction === null)
+        return unreadable([`the resolved winner is not an allow / deny bound to call "${boundCallId}"`]);
+    const byKind = throughTable(SETTLEMENT_KIND_READING, settlement.kind, "settlement.kind");
+    if (byKind !== "decided")
+        return byKind;
+    const note = typeof winner?.reason === "string" && winner.reason !== "" ? winner.reason : undefined;
+    return { kind: "decided", decision: direction === "approve" ? "allow" : "deny", decidedAtMs: settlement.when, ...(note !== undefined ? { decisionNote: note } : {}) };
+}
+export function createParkedGateRead(cs) {
+    return async ({ gateToken, gateBoundCallId }) => {
+        const currency = await readGateCurrency(cs, gateToken);
+        switch (currency.kind) {
+            case "current":
+                return { kind: "open" };
+            case "absent":
+                return { kind: "unknown", why: "row_absent" };
+            case "settled":
+                return settledReading(currency.checkpoint, gateBoundCallId);
+            default: {
+                const unhandled = currency;
+                void unhandled;
+                return { kind: "unknown", why: "row_absent" };
+            }
+        }
+    };
+}
+//# sourceMappingURL=approval-gate-currency.js.map

package/dist/approval.d.ts

@@ -184,5 +184,20 @@ export declare function createDeploymentListExemption(store: Pick<ApprovalExempt
     info(event: string, fields?: Record<string, unknown>): void;
     warn(event: string, fields?: Record<string, unknown>): void;
 }, leg?: "parked_revive"): DeploymentListExemption;
+/**
+ * **每腿自动批额度的审批人名**(本仓闭词;core `AskOutcome.approver` 契约逐字「a closed word the host owns, never a person」)。
+ * 结算记录读 `policy_allowed` / `who.party: "policy"` / `who.approver` = 本词 —— 审计读者按它认出「这一次放行是部署的自动批额度答的」,
+ * 与无人值守腿的 `unattended_class_answer`(`unattended-permission-mode.ts`)同族。
+ */
+export declare const AUTO_APPROVE_BUDGET_APPROVER = "auto_approve_budget";
+/**
+ * **请求叶策略:`settings.permissions.neverAuto`**(S-1351)—— 命中名单的工具恒问真人;名单外「本层没有意见」(裸 allow)。叶只管请求自己写的那张表,部署的 `APPROVAL_NEVER_AUTO`
+ * 在基线里({@link createDurableAskPolicy}),两者经 `tightenGoverned` 的 deny-wins 折叠取并:请求叶只会**多**问,删不掉基线里的任何一行。
+ *
+ * 名字读法与部署名单是**同一只**({@link createApprovalListVerdict} → 精确 ∪ covering,收紧臂读调用答得上的全部名字):一条规则只有一种读法。问的铸点是
+ * {@link requestAlwaysHumanAsk}(要真人位 + 请求出处),不是部署的 {@link operatorAlwaysHumanAsk}(那一个盖部署出身,请求里的声明冒不得)。
+ * `source` = 这张表在请求体里的坐标(出处进 `matchedAskRule`,审计 / 卡面据它说清是哪张表问的)。
+ */
+export declare function createRequestNeverAutoPolicy(names: readonly string[], source: string): ToolPolicy;
 export declare function createDurableAskPolicy(opts: DurableAskOptions): ToolPolicy;
 //# sourceMappingURL=approval.d.ts.map

package/dist/approval.js

@@ -1,5 +1,5 @@
-import { isNamespacedCoveringRuleName, namespacedRuleNameCovers } from "@sema-agent/core";
-import { operatorAlwaysHumanAsk, operatorAsk } from "./operator-ask.js";
+import { createApprovalPolicy, isNamespacedCoveringRuleName, namespacedRuleNameCovers } from "@sema-agent/core";
+import { operatorAlwaysHumanAsk, operatorAsk, requestAlwaysHumanAsk } from "./operator-ask.js";
 import { ASK_USER_QUESTION_TOOL_NAME } from "./approval-content-kind.js";
 import { isExplicitPosture } from "./posture-source.js";
 import { handsOnWorkerFilePlane } from "./execution-lane-caps.js";
@@ -37,7 +37,7 @@ export function buildNoResponderBootWarns(input) {
         out.push({
             event: "fs_write_gate_no_responder",
             fields: {
-                hint: "host-semantics lane with no approval face: permissionMode default/auto Write/Edit asks will auto-deny (fail-closed); wire TOOL_APPROVAL_ENABLED=true or DURABLE_APPROVAL=true to answer them",
+                hint: "host-semantics lane with no approval face: the engine's write-gate asks (permissionMode default/auto, absent reads as default; acceptEdits outside the write roots) will auto-deny (fail-closed); wire TOOL_APPROVAL_ENABLED=true or DURABLE_APPROVAL=true to answer them",
             },
         });
     }
@@ -45,7 +45,7 @@ export function buildNoResponderBootWarns(input) {
         out.push({
             event: "workflow_gate_no_responder",
             fields: {
-                hint: "self-orchestration with no approval face: permissionMode default/auto/acceptEdits run_workflow asks will auto-deny (fail-closed); wire TOOL_APPROVAL_ENABLED=true or DURABLE_APPROVAL=true to answer them",
+                hint: "self-orchestration with no approval face: run_workflow asks (every permission mode but bypassPermissions, which releases them, and dontAsk, which refuses them; absent reads as default) will auto-deny (fail-closed); wire TOOL_APPROVAL_ENABLED=true or DURABLE_APPROVAL=true to answer them",
             },
         });
     }
@@ -119,8 +119,38 @@ function createNameSetMatcher(names) {
         return (toolName) => exact.has(toolName);
     return (toolName) => exact.has(toolName) || covering.some((rule) => namespacedRuleNameCovers(rule, toolName));
 }
-function grantedByRule() {
-    return { action: "allow", decisionReason: "rule" };
+export const AUTO_APPROVE_BUDGET_APPROVER = "auto_approve_budget";
+function budgetSeatAnswer(req, requireHit, signal) {
+    let answered = false;
+    const seat = createApprovalPolicy({
+        requireApproval: [requireHit],
+        approve: () => {
+            answered = true;
+            return { allow: true, settledBy: "policy", approver: AUTO_APPROVE_BUDGET_APPROVER };
+        },
+    });
+    return { answered: () => answered, verdict: Promise.resolve(seat.check(req, signal)) };
+}
+export function createRequestNeverAutoPolicy(names, source) {
+    const verdictOf = createApprovalListVerdict({ requireApproval: [], neverAuto: names });
+    return {
+        check: (req) => {
+            const verdict = verdictOf(req);
+            switch (verdict.list) {
+                case "never_auto":
+                    return requestAlwaysHumanAsk(`${source}(${verdict.hit})`, `human approval required to run "${req.toolName}"`);
+                case "none":
+                    return { action: "allow" };
+                case "deny":
+                case "require":
+                    throw new Error(`request never-auto leaf reached a "${verdict.list}" verdict with empty deny / require lists`);
+                default: {
+                    const unreachable = verdict;
+                    throw new Error(`unhandled approval-list verdict: ${JSON.stringify(unreachable)}`);
+                }
+            }
+        },
+    };
 }
 export function createDurableAskPolicy(opts) {
     const verdictOf = createApprovalListVerdict(opts);
@@ -128,7 +158,7 @@ export function createDurableAskPolicy(opts) {
     let autoApproved = 0;
     const isQuestionTool = (name) => name === ASK_USER_QUESTION_TOOL_NAME;
     return {
-        check: (req) => {
+        check: (req, signal) => {
             const verdict = verdictOf(req);
             switch (verdict.list) {
                 case "deny":
@@ -136,7 +166,7 @@ export function createDurableAskPolicy(opts) {
                 case "never_auto":
                     return operatorAlwaysHumanAsk(`APPROVAL_NEVER_AUTO(${verdict.hit})`, `human approval required to run "${req.toolName}"`);
                 case "require":
-                    return decideRequired(req, verdict.hit);
+                    return decideRequired(req, verdict.hit, signal);
                 case "none":
                     return { action: "allow" };
                 default: {
@@ -146,7 +176,7 @@ export function createDurableAskPolicy(opts) {
             }
         },
     };
-    function decideRequired(req, requireHit) {
+    function decideRequired(req, requireHit, signal) {
         const rem = req.budget?.resourceRemainingMicroUsd;
         if (rem !== undefined && rem <= 0) {
             return operatorAlwaysHumanAsk("RESOURCE_SUSPEND budget exhausted", `durable resource budget exhausted — human approval required to run "${req.toolName}"`);
@@ -159,17 +189,25 @@ export function createDurableAskPolicy(opts) {
                     exemption.onExempted(req.toolName);
                     return { action: "allow" };
                 }
-                return budgetOrAsk(req, ask);
+                return budgetOrAsk(req, ask, requireHit, signal);
             })();
         }
-        return budgetOrAsk(req, ask);
+        return budgetOrAsk(req, ask, requireHit, signal);
     }
-    function budgetOrAsk(req, ask) {
-        if (heldRuleName(req, isQuestionTool) === undefined && budget > 0 && autoApproved < budget) {
-            autoApproved++;
-            return grantedByRule();
-        }
-        return ask;
+    function budgetOrAsk(req, ask, requireHit, signal) {
+        if (heldRuleName(req, isQuestionTool) !== undefined || budget <= 0 || autoApproved >= budget)
+            return ask;
+        autoApproved++;
+        const { answered, verdict } = budgetSeatAnswer(req, requireHit, signal);
+        return verdict.then((d) => {
+            if (answered() && d.action === "allow")
+                return d;
+            autoApproved--;
+            return ask;
+        }, (err) => {
+            autoApproved--;
+            throw err;
+        });
     }
 }
 //# sourceMappingURL=approval.js.map

package/dist/audit.d.ts

@@ -1,4 +1,4 @@
-import { type StoredPromptEpoch } from "@sema-agent/core";
+import { type SessionPlacementRecord, type StoredPromptEpoch } from "@sema-agent/core";
 import type { Pool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 /**
@@ -29,12 +29,32 @@ export interface SessionAudit {
      *  the key entirely (undefined). */
     promptEpoch?: StoredPromptEpoch;
 }
+/**
+ * 会话视图体顶层 additive 键 `agent` —— **这只会话是哪只委派子代的转录**(`GET /v1/sessions/:id`;读法:终端侧链投影方按 fleet 帧的 `transcriptId`
+ * 读同一只会话读面,从体上拿到子代身份,不必再回头翻 fleet 行 —— 行一离场就没有了)。
+ *
+ * 只投影**存下来的 placement 元组**(`session_meta` 的 `placement_*` 列,首写不可变;店的 `placementOf` 一行 PK 探针),**不另铸**:
+ *  · `id` = 元组里的 `handle` —— 耐久 agent 行的 `a…` 键,与 fleet 行的 `id`、`GET /v1/agents/roster` 的 `handle` 是同一个串(core 铸元组时 `handle: taskId`);
+ *  · `parentSessionId` / `rootSessionId` = 元组里的同名格(派它的会话 / 委派树的根会话);
+ *  · 元组缺哪一格这里就缺哪一格(present-iff;不铸空串);元组的 `scope`(租户键)/ `placedAt` / `kind` 不上 wire。
+ * 键在场 = 这是一只委派子代的转录(哪怕元组只存了 `kind`,那时 `agent` 是 `{}`);键缺席 = 普通会话,**或这台部署的店不存 placement 元组**
+ * (local 后端:子代转录停驻前住私有短 TTL 店、停驻时拷进来的那一份是普通会话行 —— 事实没存就不报,消费方在 fleet 行 / `GET /v1/agents/roster` 上本就有 `id`)。
+ * 元组由引擎在**后台**委派子代(带耐久 agent 行、店声明了 placements)建会话时铸;同步委派的子代转录不落宿主店,没有元组。
+ */
+export interface SessionAgent {
+    id?: string;
+    parentSessionId?: string;
+    rootSessionId?: string;
+}
+/** {@link SessionAgent} 的唯一投影:店答出的 placement 元组 → 体上的 `agent` 值;`undefined`(普通会话 / 店没有这一面)⇒ 调用方不铸键。 */
+export declare function sessionAgentOf(placement: SessionPlacementRecord | undefined): SessionAgent | undefined;
 /**
  * 用户消息行的**回退手柄**表:用户条目 id → 回退时交给 `resumeAt` 的那个 `event_id`(R8 用户消息锚按 run 的 taskId 键入)。
  * 真源 = `resume_anchor`(锚店 `listBySession` 的读数),本表只是它对**一位读者**的一次投影。
  */
 export type RewindHandles = ReadonlyMap<string, string>;
-/** 会话视图读口(`ServiceDeps.sessionAudit`)的读者参数:`reader` = 读这张视图的**已验身份**(无身份 = `null`)。给了 ⇒ 用户消息行投回退手柄。 */
+/** 会话视图读口(`ServiceDeps.sessionAudit`)的读者参数:`reader` = 读这张视图的**已验身份**(无身份 = `null`)。给了 ⇒ 这是一次**视图读**:用户消息行投回退手柄、体顶层投 `agent`({@link sessionAgentOf});
+ *  不给(只要归属的调用方:memory-status / 自助抹除)⇒ 两样投影的读都不付。 */
 export interface SessionAuditReadOpts {
     readonly reader: string | null;
 }
@@ -53,15 +73,12 @@ export declare function buildRewindHandles(anchors: ReadonlyArray<{
  *  rewind-handle projection ({@link buildRewindHandles}); absent ⇒ no `taskId` keys. */
 export declare function buildSessionAudit(pool: Pool, sessionId: string, handles?: RewindHandles): Promise<SessionAudit | undefined>;
 /** The PG twin — same view over PgSessionStorage.wake. Until this, the
- *  audit face was TiDB-only and a PG/local deployment 404'd the whole web session area. local = follow-on
- *  (its storage seam has no wake-equivalent yet — may turn out to be a core gap). */
+ *  audit face was TiDB-only and a PG/local deployment 404'd the whole web session area. */
 export declare function buildSessionAuditPg(pool: PgPool, sessionId: string, handles?: RewindHandles): Promise<SessionAudit | undefined>;
-/** The LOCAL (File) leg — web session area on DB_BACKEND=local.
- *  repo 取自 `createLocalSessionRepo`(与 `LocalSessionStore` 同一只工厂):坏记录的披露座(F 类 `server.session-repo.corrupt-record-skipped`)
- *  因此在视图口同样在场 —— 视图照常返回、跳过的记录有计数 + 探针行(修前自建一只不带座的 repo,零披露)。
- *  实现姿势:`FileSessionRepo.exportEntries`(纯读、torn-tail 恢复、missing→not_found)→
- *  `boundedTail`(纯函数切 floor)→ InMemorySessionStorage → 同一 auditFromStorage 内核。零写面、
- *  零新 seam;createdAt 从 repo.list() 的 metadata 取(File 形态 meta 与 entries 分储)。 */
+/** The LOCAL (File) leg — web session area on DB_BACKEND=local: the same view over `LocalSessionWindow.wake`
+ *  (`plugins/local-session-window.ts`). All three legs read one way — a bounded window that carries the epoch anchor below its
+ *  floor — and on every backend that is what the run reads: the SQL twins' run wakes the same window; the local run wakes the whole
+ *  tree, and the local window is cut from that tree's branch, with the anchor walking the branch below the floor. */
 export declare function buildSessionAuditLocal(root: string, sessionId: string, handles?: RewindHandles): Promise<SessionAudit | undefined>;
 /**
  * 🔴 **会话视图的读面口 —— `GET /v1/sessions/:id` 的全部取法(整读 / `?tail` / `?before` / `?blobCap` / `?message=N`)共用这一只**。

package/dist/audit.js

@@ -1,11 +1,20 @@
-import { StoredSession, InMemorySessionStorage, boundedTail } from "@sema-agent/core";
+import { StoredSession } from "@sema-agent/core";
 import { TiDBSessionStorage } from "./plugins/tidb-session-storage.js";
 import { PgSessionStorage } from "./plugins/pg-session-storage.js";
-import { createLocalSessionRepo } from "./plugins/local-session-store.js";
+import { LocalSessionWindow } from "./plugins/local-session-window.js";
 import { redactModelText } from "./observability/run-terminal.js";
 import { redactDeepWith } from "./trace/redact.js";
 import { projectToolStructured } from "./trace/tool-output-media.js";
 import { INJECTED_BLOCK_RE, isAttachmentFrame } from "./user-authored-text.js";
+export function sessionAgentOf(placement) {
+    if (placement === undefined)
+        return undefined;
+    return {
+        ...(placement.handle !== undefined ? { id: placement.handle } : {}),
+        ...(placement.parentSessionId !== undefined ? { parentSessionId: placement.parentSessionId } : {}),
+        ...(placement.rootSessionId !== undefined ? { rootSessionId: placement.rootSessionId } : {}),
+    };
+}
 export function buildRewindHandles(anchors, reader) {
     const byEntry = new Map();
     for (const a of anchors) {
@@ -26,20 +35,7 @@ export async function buildSessionAuditPg(pool, sessionId, handles) {
     return auditFromStorage(await PgSessionStorage.wake(pool, sessionId), sessionId, handles);
 }
 export async function buildSessionAuditLocal(root, sessionId, handles) {
-    const repo = createLocalSessionRepo(root);
-    let entries;
-    try {
-        entries = await repo.exportEntries(sessionId);
-    }
-    catch (e) {
-        if (e.code === "not_found")
-            return undefined;
-        throw e;
-    }
-    const meta = (await repo.list()).find((m) => m.id === sessionId);
-    const { tail, floorEntryId } = boundedTail(entries);
-    const storage = new InMemorySessionStorage({ entries: tail, floorEntryId, ...(meta ? { metadata: meta } : {}) });
-    return auditFromStorage(storage, sessionId, handles);
+    return auditFromStorage(await LocalSessionWindow.wake(root, sessionId), sessionId, handles);
 }
 async function auditFromStorage(storage, sessionId, handles) {
     if (!storage)

package/dist/bake-runner/main.js

@@ -5,6 +5,7 @@ import { logConfigDiagnostics, parseEnvNameAllowlist, parseNumOrFailNonNegative
 import { installSecretEnvScrubRecorder } from "../observability/secret-env-scrub.js";
 import { declareServerWithheldEnv, hostSubprocessEnv } from "../server-secret-env.js";
 import { shellQuote as shellSafe } from "../plugins/remote-shell.js";
+import { echoCallerText } from "../caller-text-echo.js";
 import { BakeRunner, } from "./runner.js";
 const BAKE_CLAIM_INGEST_FETCH_TIMEOUT_MS = 30_000;
 const BAKE_HEARTBEAT_FETCH_TIMEOUT_MS = 10_000;
@@ -181,9 +182,9 @@ export async function execGroup(cmd, timeoutMs, envAllow) {
     try {
         const { code, signal } = await child.exited;
         if (timedOut)
-            throw new Error(`host exec timed out after ${timeoutMs}ms (group killed): ${cmd.slice(0, 120)}`);
+            throw new Error(`host exec timed out after ${timeoutMs}ms (group killed): ${echoCallerText(cmd, { maxChars: 120 })}`);
         if (code !== 0)
-            throw new Error(`host exec exited ${code ?? signal}: ${cmd.slice(0, 120)}${stderr.trim() ? ` — ${stderr.trim().slice(-400)}` : ""}`);
+            throw new Error(`host exec exited ${code ?? signal}: ${echoCallerText(cmd, { maxChars: 120 })}${stderr.trim() ? ` — ${stderr.trim().slice(-400)}` : ""}`);
         return { stdout };
     }
     finally {

package/dist/boot/coordinators.d.ts

@@ -14,6 +14,7 @@ import { QuestionCoordinator } from "../question.js";
 import { ToolApprovalCoordinator, type ParkedAskRedeem } from "../tool-approval.js";
 import { FileApprovalAskAuditStore } from "../approval-ask-audit-store.js";
 import type { ParkCommitWatch } from "../plugins/park-commit-watch.js";
+import { type GateCurrencyStore } from "../approval-gate-currency.js";
 import { SendUserFileEmitter } from "../capabilities/send-user-file-tool.js";
 import { TaskEnvRegistry } from "../capabilities/sandbox-file-send.js";
 import type { StoreBackend } from "../plugins/store-backend.js";
@@ -36,13 +37,17 @@ export interface LiveCoordinatorsCtx {
     /** S-929 F1:checkpoint 店的 park 提交观察层(stage-06 与店同一处铸;在场 ⇔ 有 checkpoint 店)。协调器据它判「有序关停下的 park 路由
      *  提交了没有」—— 审计 settle 行等 park 提交落定才写。缺席 = 没有 park 设施(core 在 ask 回调处就收场,没有提交这一步)。 */
     parkCommits?: ParkCommitWatch;
+    /** S-1915:checkpoint 店(stage-06 的**同一只**,与 `parkCommits` 同源;在场 ⇔ 有 park 设施)。协调器的按问读口据它判一张 `PARKED` 卡的门此刻还是不是该会话当前待决的审批门
+     *  (判官 = `approval-gate-currency.ts`,应答口判 `approval_stale` 读的同一只)。缺席 ⇒ 读口只能说行说的话(`parked`)。
+     *  也是流内审批协议上场门的 park 设施位:在场性与实例是一个事实 —— 门的 `active` 臂交出去的就是这一只,缺席 ⇒ 协议不上场(`no_park_facility`)。 */
+    checkpointStore?: GateCurrencyStore;
 }
 export declare function createLiveCoordinators(ctx: LiveCoordinatorsCtx): {
     elicitation: ElicitationCoordinator | undefined;
     question: QuestionCoordinator | undefined;
     toolApproval: ToolApprovalCoordinator | undefined;
     durableEnabled: boolean;
-    streamApprovalGate: import("../tool-approval.js").StreamApprovalGate;
+    streamApprovalGate: import("../tool-approval.js").StreamApprovalGate<GateCurrencyStore>;
     approvalAskAudit: FileApprovalAskAuditStore | undefined;
     approvalExemptionStore: import("../plugins/approval-exemption-store.js").ApprovalExemptionStore | undefined;
     sendUserFileEmitter: SendUserFileEmitter | undefined;

package/dist/boot/coordinators.js

@@ -3,6 +3,7 @@ import { QuestionCoordinator } from "../question.js";
 import { ToolApprovalCoordinator, resolveStreamApprovalGate } from "../tool-approval.js";
 import { deploymentListAsks } from "../approval.js";
 import { FileApprovalAskAuditStore } from "../approval-ask-audit-store.js";
+import { createParkedGateRead } from "../approval-gate-currency.js";
 import { SendUserFileEmitter, SEND_USER_FILE_MAX_BYTES, sendUserFileTool } from "../capabilities/send-user-file-tool.js";
 import { createSandboxFileSend, TaskEnvRegistry } from "../capabilities/sandbox-file-send.js";
 import { createSendUserFileIssuer } from "../plugins/send-user-file.js";
@@ -11,15 +12,16 @@ import { basename, resolve } from "node:path";
 import { toolsRunOnThisHost } from "../task-cwd.js";
 import { stat as fsStat, readFile as fsReadFile } from "node:fs/promises";
 export function createLiveCoordinators(ctx) {
-    const { config, logger, backend, sendUserFileTaskEnvs, ruleConsent, ruleScopeRootFor, getParkedRedeem, parkCommits } = ctx;
+    const { config, logger, backend, sendUserFileTaskEnvs, ruleConsent, ruleScopeRootFor, getParkedRedeem, parkCommits, checkpointStore } = ctx;
     const elicitation = config.mcpElicitation.enabled ? new ElicitationCoordinator(config.mcpElicitation.throttle) : undefined;
     const question = config.askQuestionEnabled ? new QuestionCoordinator(config.questionThrottle) : undefined;
-    const durableEnabled = backend?.checkpoint !== undefined && config.durableApproval === true;
+    const parkStore = checkpointStore;
+    const durableEnabled = parkStore !== undefined;
     const streamApprovalGate = resolveStreamApprovalGate({
         toolApprovalEnabled: config.toolApprovalEnabled === true,
         streamApprovalEnabled: config.streamApproval.enabled,
         backend,
-        parkFacility: durableEnabled,
+        checkpointStore: parkStore,
     });
     if (config.streamApproval.enabled && !streamApprovalGate.active) {
         logger.info("stream_approval_disabled", {
@@ -58,6 +60,7 @@ export function createLiveCoordinators(ctx) {
             ...(ruleScopeRootFor !== undefined ? { ruleScopeRootFor } : {}),
             unattendedPolicy: config.unattendedApprovalPolicy,
             ...(getParkedRedeem !== undefined ? { parkedRedeem: getParkedRedeem } : {}),
+            ...(checkpointStore !== undefined ? { parkedGate: createParkedGateRead(checkpointStore) } : {}),
             ...(approvalAskAudit !== undefined ? { askAudit: approvalAskAudit } : {}),
             ...(approvalExemptionStore !== undefined
                 ? { sessionGrants: approvalExemptionStore, deploymentListAsks: (call) => deploymentListAsks(config, call) }

package/dist/boot/deferred-sandbox-path-env.js

@@ -118,7 +118,7 @@ export class DeferredSandboxPathEnv extends StubExecutionEnv {
                 reason: found.reason,
                 face,
                 sessionId: this.sessionId ?? null,
-                note: "the sandbox fs-write gate has no task environment to adjudicate against — every write target fails closed (ask, and deny under the sensitive-path set) until one is bound",
+                note: "the sandbox path adjudication has no task environment to read — the sensitive-path guard fails closed (deny) on every write target until one is bound",
             });
         }
         return {

package/dist/boot/execution-env.js

@@ -20,13 +20,14 @@ import { FileSchedulerBackend, defaultSchedulerStorePath } from "../plugins/sche
 import * as facts from "../capability-facts.js";
 import { materializeAttachmentsInto } from "../plugins/task-attachment-store.js";
 import { reapOrphanWorktrees, withWorktreeIsolation } from "../plugins/worktree-isolation.js";
-import { customPkgSourceFromEnv, derivePkgSourceEnv } from "../sandbox-pkg-source.js";
+import { derivePkgSourceEnv } from "../sandbox-pkg-source.js";
 import { effectiveHostWorkspace } from "../task-cwd.js";
 import { taskInheritEnvRefusal } from "../hosted-posture.js";
 import { createCacheMissMemory } from "../workspace-cache.js";
 import { workspaceSnapshotTimeoutOf } from "../workspace-space.js";
 import { sayEgressPolicyReading } from "../sandbox-egress-policy.js";
 import { isSandboxPathAdjudicationLane, sandboxPathEnvSlots, withSandboxPathEnvSlot } from "./deferred-sandbox-path-env.js";
+import { LANE_HOME_UNDECLARED_EVENT, createLaneHomeAbsenceReporter } from "../lane-home-probe.js";
 import { REMOTE_EXEC_PROVIDER_WORDS, buildUndeclaredHomeNote, executionLaneHomeDir, executionLaneOf, isSingleMachineDefaultLane, laneBindsReads, laneIsolated } from "../execution-lane-caps.js";
 function boundedSessionSetter(map, maxEntries) {
     return (sid, value) => {
@@ -55,7 +56,7 @@ function forwardedSandboxEnvKeys(remoteExec) {
     }
 }
 function buildSandboxLaneEnv(config, explicit) {
-    const merged = { ...derivePkgSourceEnv(config.sandboxPkgSource, customPkgSourceFromEnv()), ...(explicit ?? {}) };
+    const merged = { ...derivePkgSourceEnv(config.sandboxPkgSource, config.sandboxPkgSourceCustom), ...(explicit ?? {}) };
     return Object.keys(merged).length > 0 ? merged : undefined;
 }
 const MAX_CWD_SESSIONS = 4096;
@@ -197,6 +198,7 @@ export function createExecutionEnv(ctx) {
     const { config, logger, metrics, taskAttachmentStore } = ctx;
     const laneHomeDir = executionLaneHomeDir(config);
     const homeDirSeat = laneHomeDir !== undefined ? { homeDir: laneHomeDir } : {};
+    const homeAbsentNotice = { onHomeAbsent: createLaneHomeAbsenceReporter((event, fields) => logger.warn(event, fields)) };
     const perTaskImage = new PerTaskImageRegistry();
     const sessionEnvSelection = new SessionEnvironmentSelection();
     const sessionScoped = createSessionScopedRegistries();
@@ -223,7 +225,7 @@ export function createExecutionEnv(ctx) {
     else if (config.remoteExec?.provider === "k8s") {
         const k8sCfg = {
             image: config.remoteExec.image,
-            ...homeDirSeat,
+            ...homeDirSeat, ...homeAbsentNotice,
             ...(config.remoteExec.apiUrl ? { apiUrl: config.remoteExec.apiUrl } : {}),
             ...(config.remoteExec.token ? { token: config.remoteExec.token } : {}),
             ...(config.remoteExec.caCert ? { caCert: config.remoteExec.caCert } : {}),
@@ -254,7 +256,7 @@ export function createExecutionEnv(ctx) {
         executionEnvFactory = sshExecutionEnvFactory({
             host: config.remoteExec.host,
             username: config.remoteExec.username,
-            ...homeDirSeat,
+            ...homeDirSeat, ...homeAbsentNotice,
             privateKey: config.remoteExec.privateKey,
             ...(config.remoteExec.port != null ? { port: config.remoteExec.port } : {}),
             ...(config.remoteExec.mountPath ? { mountPath: config.remoteExec.mountPath } : {}),
@@ -278,7 +280,7 @@ export function createExecutionEnv(ctx) {
     else if (config.remoteExec?.provider === "adb") {
         executionEnvFactory = adbExecutionEnvFactory({
             serial: config.remoteExec.serial,
-            ...homeDirSeat,
+            ...homeDirSeat, ...homeAbsentNotice,
             ...(config.remoteExec.adbPath ? { adbPath: config.remoteExec.adbPath } : {}),
             ...(config.remoteExec.mountPath ? { mountPath: config.remoteExec.mountPath } : {}),
         });
@@ -327,7 +329,7 @@ export function createExecutionEnv(ctx) {
         executionEnvFactory = localDockerExecutionEnvFactory({
             image: config.remoteExec.image,
             ...(config.remoteExec.mountPath ? { mountPath: config.remoteExec.mountPath } : {}),
-            ...homeDirSeat,
+            ...homeDirSeat, ...homeAbsentNotice,
             ...(config.remoteExec.dockerPath ? { dockerPath: config.remoteExec.dockerPath } : {}),
             ...(config.remoteExec.dockerHost ? { dockerHost: config.remoteExec.dockerHost } : {}),
             ...(config.remoteExec.memory ? { memory: config.remoteExec.memory } : {}),
@@ -416,7 +418,7 @@ export function createExecutionEnv(ctx) {
             logger.warn("remote_exec_real_system", { provider: config.remoteExec.provider, note: buildRealSystemNote(config.remoteExec) });
         const homeNote = buildUndeclaredHomeNote(config);
         if (homeNote !== undefined)
-            logger.warn("execution_lane_home_undeclared", { provider: config.remoteExec.provider, note: homeNote });
+            logger.warn(LANE_HOME_UNDECLARED_EVENT, { provider: config.remoteExec.provider, note: homeNote });
         if (executionLaneOf(config.remoteExec.provider) === "host")
             logger.info("task_inherit_env_honored", { honored: taskInheritEnvRefusal(config) === undefined });
     }

package/dist/boot/execution-lane.js

@@ -1,13 +1,23 @@
 import { loadRemoteExec } from "@sema-agent/settings-schema/node";
+import { assertLocalConfigDirTrusted } from "../config-dir-trust.js";
 import { crossInvariant } from "../config-invariants.js";
 import { executionLaneOf, laneIsolated } from "../execution-lane-caps.js";
+import { buildReadFacePostureNotice, settleDerivedReadFace } from "../read-face-posture.js";
 import { settleHostShellAtBoot } from "../plugins/host-platform.js";
 export const FILE_SOURCED_LANES = ["host", "local-docker"];
 export async function composeExecutionLane(config, ctx) {
     if (ctx.configSource === "local")
         await applyRemoteExecFile(config, ctx);
+    settleReadFaceForFinalLane(config, ctx.logger);
     assertExecutionLaneInvariants(config);
 }
+function settleReadFaceForFinalLane(config, logger) {
+    if (!settleDerivedReadFace(config, config.requirePrincipal !== true))
+        return;
+    const notice = buildReadFacePostureNotice(config);
+    if (notice !== undefined)
+        logger.info(notice.event, notice.fields);
+}
 export async function settleHostLaneShell(config, logger) {
     if (config.remoteExec?.provider !== "host")
         return;
@@ -34,6 +44,7 @@ export function assertExecutionLaneInvariants(config) {
 }
 async function applyRemoteExecFile(config, ctx) {
     const { localRoot, logger } = ctx;
+    await assertLocalConfigDirTrusted({ root: localRoot, declaredOwnerUid: config.configLocalOwnerUid });
     let fileRx;
     try {
         fileRx = await loadRemoteExec(localRoot);