@sema-agent/server 7.70.0 → 7.72.0

package/dist/observability/tool-trace.js

@@ -1,4 +1,4 @@
-import { isAutoModeUnavailableCause, isDeniedBy } from "@sema-agent/core";
+import { isClassifierDenyCause, isDeniedBy } from "@sema-agent/core";
 import { redactSecrets } from "../trace/redact.js";
 function deniedByLabel(gate) {
     const d = gate.disposition;
@@ -8,9 +8,10 @@ export function createPermissionDeniedMeter(metrics) {
     return {
         permissionDenied(payload) {
             metrics.inc("permission_denied_total", { deniedBy: deniedByLabel(payload.gate) });
-            const cause = payload.classifierUnavailable?.cause;
+            const disposition = payload.gate?.disposition;
+            const cause = disposition?.kind === "denied" ? disposition.cause : undefined;
             if (cause !== undefined) {
-                metrics.inc("auto_mode_classifier_unavailable_total", { cause: isAutoModeUnavailableCause(cause) ? cause : "other" });
+                metrics.inc("auto_mode_classifier_deny_cause_total", { cause: isClassifierDenyCause(cause) ? cause : "other" });
             }
         },
     };

package/dist/orchestration/workflow-agent-session-index.d.ts

@@ -19,10 +19,93 @@ export interface WorkflowAgentSessionIndex {
     syncRun(runId: string, rows: readonly WorkflowAgentSessionRow[]): Promise<void>;
     findByAgentSession(sessionId: string): Promise<WorkflowAgentSessionRow | null>;
 }
+/** 一条 wa* 行在**恢复面**上的读形(本模块两个派生点共用的最小入参 —— 只声明恢复判据用得到的位)。 */
+export interface ParkedAgentReadFace {
+    label?: unknown;
+    status?: unknown;
+    sessionId?: unknown;
+    callKey?: unknown;
+    queuedAt?: unknown;
+    startedAt?: unknown;
+    parkedCheckpointToken?: unknown;
+}
+/**
+ * 🔴 **「这一行是不是一条可赎回的 park」的唯一判据**(S-192 提取;此前只内联在
+ * {@link buildParkedAgentSessionRows} 里,而店层的瘦身腿需要**同一条**判据 —— 两处各写一遍就是两份会漂的
+ * 定义,而它们的消费面是同一件事:park 的赎回路由)。
+ *
+ * 三位缺任何一个都不算:缺 `sessionId` 的 park 行 join 不到(checkpoint 那侧的键就是它),缺
+ * `parkedCheckpointToken` 的行不是一条可赎回的 park(core 契约:在场 ⟺ `status:"parked"`)。
+ */
+export declare function isRecoverableParkedAgent<T extends ParkedAgentReadFace>(a: T): a is T & {
+    sessionId: string;
+    parkedCheckpointToken: string;
+};
+/** LLM 撰写的 `label` 在**恢复身份行**上的字符上界。core 的铸点对它零钳零脱(脚本经 `opts.label` 供,
+ *  缺席才落 auto 名;`parked-decide.ts` 拒把它内插进可信帧时亲核过这一点),而这条行存在的理由是**装得下**
+ *  —— 把一段无界展示文本原样带进来会让「留身份」这件事本身把行撑爆。 */
+export declare const PARKED_IDENTITY_LABEL_MAX = 200;
+/**
+ * 🔴 **一条 parked 行的「恢复身份」形**(S-192)—— 店层瘦身时**最后才放弃**的那一份。
+ *
+ * 它是一条**合法的** `WorkflowAgentRun`(core 的必填四位 `label`/`callKey`/`status`/`queuedAt` 齐全),
+ * 加上赎回路由要的两位(`sessionId` = checkpoint 的 `sourceTaskId`,`parkedCheckpointToken` = 赎回键)。
+ * 展示载荷(`prompt`/`output`/`activity`/`errorMessage`/`phase`/`model`…)一律不带 —— 那正是被裁掉的东西。
+ *
+ * 返回的是**普通数据**(build*),消费方是 `plugins/workflow-run-store-sql.ts` 的 `slimOversizeRun`。
+ */
+export declare function buildParkedRecoveryIdentity(a: ParkedAgentReadFace & {
+    sessionId: string;
+    parkedCheckpointToken: string;
+}, // 准入判据 {@link isRecoverableParkedAgent} 的守卫输出:类型上绕不开
+labelMax?: number): Record<string, unknown>;
+/**
+ * 一只 run 的 parked 行的恢复身份集(顺序 = 原行序;非 park / 无身份的行不产出)。
+ *
+ * `labelMax` 是**展示名的预算**,不是第二种形:身份四位(`callKey` / `sessionId` /
+ * `parkedCheckpointToken` / `status`)恒在,`label` 是这条行上唯一可弃的展示物。店的瘦身阶梯据此把
+ * 「放弃展示名」排在「放弃身份」**之前** —— 传 0 即得只剩身份的最小行(`redactHead(x, 0)` 恒得空串)。
+ */
+export declare function buildParkedRecoveryIdentities(agents: ReadonlyArray<ParkedAgentReadFace> | undefined, labelMax?: number): Array<Record<string, unknown>>;
+/**
+ * 🔴 **park 恢复身份「保不住」的显式标记**(S-192)。
+ *
+ * ## 为什么它住在 run 的 blob 上、而且键名带 `server` 前缀
+ * core 的 `WorkflowRun`(`orchestration/workflow-types.d.ts`)**没有合法座** —— 亲读全部可选成员
+ * (`agentFailures` / `budgetOvershoot` / `timeoutInterruption` / `resume` / `journalSkips` …)全是 core 自己的
+ * 观测席,没有一个说得了「本仓的店把这条 run 的 park 身份裁掉了」。而这条事实的**唯一知情点**是
+ * `plugins/workflow-run-store-sql.ts` 的瘦身腿(店内),它的**唯一消费点**是 `/decide` 的 workflow 车道
+ * (读 `WorkflowRunStore.get`)—— 两点之间已经有的、且只有的那条通路就是 run 的 blob。
+ * (本仓的 park join 索引 {@link WorkflowAgentSessionIndex} 承载不了它:索引的**单写者**是
+ * `JournalingWorkflowRunStore` 的 put/update 观察点,它拿到的是**内存里的整只 run**,结构上看不见店内那次
+ * 瘦身;把这条事实塞过去要么加第二个写者、要么把店的字节上界漏进装饰器,两者都比现在这条更坏。)
+ * 键名前缀 `server` 是**诚实标注**:它是本仓铸的位,不是 core 契约的一部分,也因此永远不会与 core 后来加的
+ * 成员撞名。
+ *
+ * ## 闭集
+ * `reason` 只有一个词(单一成因:店的字节上界)。`parks` 是被丢掉的 parked 行数 —— **只有计数,不带任何
+ * 身份位**(带了就等于没裁)。
+ */
+export declare const PARK_IDENTITY_LOSS_KEY = "serverParkIdentityLoss";
+export interface ParkIdentityLoss {
+    /** 闭集单值:行被店的字节上界裁掉。 */
+    reason: "oversize_slim";
+    /** 被裁掉的 parked 行数(诊断口径,不含身份位)。 */
+    parks: number;
+}
+/** 铸点(普通数据)。 */
+export declare function buildParkIdentityLoss(parks: number): ParkIdentityLoss;
+/**
+ * 盘上 run blob → {@link ParkIdentityLoss} 的**唯一读者**(宪法 [ref] §2:进程外字节禁裸 `as` 铸形;
+ * 与本文件 {@link readAgentSessionLedgerLine} 同一条姿态)。
+ *
+ * 形不合(缺键 / 词出闭集 / 计数不是有限数)⇒ **缺席**,而不是「铸一个默认标记出来」:标记在场的后果是
+ * `/decide` 响亮拒,一个凭空铸出来的标记会把一条**可赎回**的 park 拒死。
+ */
+export declare function readParkIdentityLoss(run: unknown): ParkIdentityLoss | undefined;
 /** 派生的**唯一属主**:一只 `WorkflowRun` 当前的 parked 索引行。
  *
- *  三个键缺任何一个都不入索引 —— 缺 `sessionId` 的 park 行 join 不到(checkpoint 那侧的键就是它),
- *  缺 `parkedCheckpointToken` 的行不是一条可赎回的 park(core 契约:在场 ⟺ `status:"parked"`)。
+ *  行的准入判据 = {@link isRecoverableParkedAgent}(与店层瘦身腿**同一条**)。
  *  ⚠️ token **不进索引行**:它是赎回能力,家在 run 的 blob 里(与 bg 行同判),索引只回答「去哪条 run 找」。 */
 export declare function buildParkedAgentSessionRows(runId: string, run: {
     scope: string;

package/dist/orchestration/workflow-agent-session-index.js

@@ -1,13 +1,46 @@
 import { existsSync, fsyncSync, mkdirSync, openSync, readFileSync, truncateSync, writeSync } from "node:fs";
 import { join } from "node:path";
+import { redactHead } from "../observability/run-terminal-log.js";
+const nonEmptyString = (v) => typeof v === "string" && v !== "";
+export function isRecoverableParkedAgent(a) {
+    return a.status === "parked" && nonEmptyString(a.sessionId) && nonEmptyString(a.parkedCheckpointToken);
+}
+export const PARKED_IDENTITY_LABEL_MAX = 200;
+export function buildParkedRecoveryIdentity(a, labelMax = PARKED_IDENTITY_LABEL_MAX) {
+    return {
+        label: typeof a.label === "string" ? redactHead(a.label, labelMax) : "",
+        callKey: typeof a.callKey === "string" ? a.callKey : "",
+        status: "parked",
+        queuedAt: typeof a.queuedAt === "number" && Number.isFinite(a.queuedAt) ? a.queuedAt : 0,
+        ...(typeof a.startedAt === "number" && Number.isFinite(a.startedAt) ? { startedAt: a.startedAt } : {}),
+        sessionId: a.sessionId,
+        parkedCheckpointToken: a.parkedCheckpointToken,
+    };
+}
+export function buildParkedRecoveryIdentities(agents, labelMax = PARKED_IDENTITY_LABEL_MAX) {
+    return (agents ?? []).filter(isRecoverableParkedAgent).map((a) => buildParkedRecoveryIdentity(a, labelMax));
+}
+export const PARK_IDENTITY_LOSS_KEY = "serverParkIdentityLoss";
+export function buildParkIdentityLoss(parks) {
+    return { reason: "oversize_slim", parks };
+}
+export function readParkIdentityLoss(run) {
+    if (typeof run !== "object" || run === null)
+        return undefined;
+    const v = run[PARK_IDENTITY_LOSS_KEY];
+    if (typeof v !== "object" || v === null || Array.isArray(v))
+        return undefined;
+    const { reason, parks } = v;
+    if (reason !== "oversize_slim")
+        return undefined;
+    if (typeof parks !== "number" || !Number.isFinite(parks) || parks <= 0)
+        return undefined;
+    return { reason, parks };
+}
 export function buildParkedAgentSessionRows(runId, run) {
     const rows = [];
     for (const a of run.agents ?? []) {
-        if (a.status !== "parked")
-            continue;
-        if (typeof a.sessionId !== "string" || a.sessionId === "")
-            continue;
-        if (typeof a.parkedCheckpointToken !== "string" || a.parkedCheckpointToken === "")
+        if (!isRecoverableParkedAgent(a))
             continue;
         rows.push({ sessionId: a.sessionId, runId, agentKey: typeof a.callKey === "string" ? a.callKey : "", scope: run.scope });
     }

package/dist/parked-decide.d.ts

@@ -10,7 +10,7 @@
  */
 import type { HostDecision } from "./host-decision.js";
 import type { BackgroundAgentRecord, BackgroundAgentStore, CheckpointStore, QuestionAnswer, ResumeOutcome, TaskRegistry, ToolSpec, WorkflowAgentRun, WorkflowRun, WorkflowRunStore } from "@sema-agent/core";
-import type { WorkflowAgentSessionIndex } from "./orchestration/workflow-agent-session-index.js";
+import { type ParkIdentityLoss, type WorkflowAgentSessionIndex } from "./orchestration/workflow-agent-session-index.js";
 export interface ParkedAgentMatch {
     handle: string;
     row: BackgroundAgentRecord;
@@ -47,6 +47,23 @@ export type ParkOrigin = {
     runId: string;
     run: WorkflowRun;
     agent: WorkflowAgentRun;
+}
+/**
+ * S-192 —— **恢复身份被店的字节上界裁掉**的那条 park(第四种出身,不是第四条车道)。
+ *
+ * 索引行还在(它由**内存里的整只 run** 派生,店内的瘦身它看不见),run 行也还在,但 blob 里已经没有
+ * 那一行 —— 而 blob 里的 `parkedCheckpointToken` 是 server 侧**复核**「这条 park 仍在此 token 下」的唯一
+ * 依据(引擎自己的那份赎回键住在 resume journal 的 parked 条目里,resume 时从那里取,见
+ * {@link denyWorkflowParkIdentityLost} 顶注亲读的 core 坐标)。此前这一格与「索引落后一拍 / 行已在新
+ * token 下 re-park」两种**正常** miss 完全同形,于是落 legacy 腿拿一个错因 409。
+ * 现在店在裁掉它的同时落一个闭集标记({@link readParkIdentityLoss}),判别式据它把这一格分出来,
+ * 三个消费点各自响亮处置(decide 拒 + 不驱动宿主续跑;SLA sweep 照旧静默跳过——它同样复核不了)。
+ */
+ | {
+    kind: "workflow_identity_lost";
+    runId: string;
+    run: WorkflowRun;
+    loss: ParkIdentityLoss;
 };
 /** 判别式的两个源。各自可缺席(部署没接就是没接)—— 缺席 ⇒ 那条臂不判,不是失败。 */
 export interface ParkOriginSources {
@@ -208,6 +225,28 @@ export type WorkflowParkedDecidePlan = {
     ok: false;
     deny: ParkedDecideResult;
 };
+/**
+ * S-192 —— **恢复身份已被裁掉的 workflow park 的响亮拒**(与上面那族拒臂同一种返回形)。
+ *
+ * 为什么是拒而不是「尽力而为地投递一次」(机理按 core 7.13.0 `dist/orchestration/workflow.js` 亲读,合并复审
+ * R9/R23 推翻本注此前「引擎手上没有赎回键 ⇒ 重跑」的推断):
+ *  · 投递用的 token 是调用方 checkpoint 的 `cp.token`(路由拿到的那枚),**不是** blob 里那一行;blob 行在本
+ *    车道的用途只有一个 —— 复核「这条 park 此刻仍在此 token 下」(`agent.parkedCheckpointToken === cp.token`,
+ *    行已在新 token 下 re-park ⇒ miss 不错配)。行被裁掉 = 这道复核**失明**,200「决定已交给宿主的下一跑」
+ *    就证不出它兑付的是哪一条 park。
+ *  · 引擎 resume 时的赎回键取自 **resume journal** 的 parked 条目(`parkedResumeFor(cached.parked.terminal.token)`,
+ *    :1327/:1727),不取自 run blob;不带决定的 resume 用同一 token **重新 park**(`parkAgentLeg(reparkRec, …)`,
+ *    :1345/:1738),不是重跑。blob 的 parked 行在引擎侧唯一的读点是 `prior.agents` 那道「journal 缺条目」防线
+ *    (:2118-2130)—— 身份被裁掉后失明的正是它:**只有 journal 也缺该条目时**,resume 才会把那次调用活跑。
+ *  ⇒ 拒,并把真话与真恢复路径说出来:先不带决定 resume(引擎按 journal re-park 进一只新的、小的 run 行),
+ *    再对同一 checkpoint decide;re-park 后能否再赎回取决于新 blob 是否装得下身份行(不下 ⇒ 再落本臂)。
+ *    码是新的,与既有 `decide.workflow_*` 同族。
+ *
+ * 体上带 `runId` 与被裁掉的 park 数(`parks`)—— 后者是店给的计数,**不含任何身份位**(带了就等于没裁)。
+ */
+export declare function denyWorkflowParkIdentityLost(origin: Extract<ParkOrigin, {
+    kind: "workflow_identity_lost";
+}>): ParkedDecideResult;
 export declare function planWorkflowParkedDecide(origin: Extract<ParkOrigin, {
     kind: "workflow";
 }>, req: ParkedDecideRequest): WorkflowParkedDecidePlan;

package/dist/parked-decide.js

@@ -1,5 +1,7 @@
+import { readParkIdentityLoss } from "./orchestration/workflow-agent-session-index.js";
 import { defaultSubagentTailBus } from "./fleet/subagent-tail-bus.js";
 import { backgroundScopesForCheckpointScope, decodeCheckpointScope } from "./security.js";
+import { ASK_USER_QUESTION_TOOL_NAME } from "./approval-content-kind.js";
 export async function findParkOrigin(sources, cp) {
     if (sources.agentStore !== undefined) {
         let match;
@@ -24,7 +26,11 @@ export async function findParkOrigin(sources, cp) {
         if (run === null)
             return undefined;
         const agent = (run.agents ?? []).find((a) => a.sessionId === cp.sessionId && a.status === "parked");
-        if (agent === undefined || agent.parkedCheckpointToken !== cp.token)
+        if (agent === undefined) {
+            const loss = readParkIdentityLoss(run);
+            return loss === undefined ? undefined : { kind: "workflow_identity_lost", runId: row.runId, run, loss };
+        }
+        if (agent.parkedCheckpointToken !== cp.token)
             return undefined;
         return { kind: "workflow", runId: row.runId, run, agent };
     }
@@ -80,6 +86,17 @@ export function buildParkedResumeOutcome(req) {
         hostDecision: req.hostDecision,
     };
 }
+export function denyWorkflowParkIdentityLost(origin) {
+    return {
+        status: 409,
+        body: {
+            error: "this parked workflow agent's recovery identity was dropped when the run store slimmed an oversize run blob — the server can no longer verify that the row is still parked under this checkpoint token, so the decision is not delivered. The park itself is kept by the engine's resume journal, not by this blob: resume the run without a decision (the engine re-parks the child under the same token into a fresh run row), then decide again; only if that journal entry is also missing would a resume run the call live",
+            errorCode: "decide.workflow_park_identity_lost",
+            runId: origin.runId,
+            parksDropped: origin.loss.parks,
+        },
+    };
+}
 export function planWorkflowParkedDecide(origin, req) {
     if (req.grantRemember !== undefined) {
         return {
@@ -115,8 +132,9 @@ export function planWorkflowParkedDecide(origin, req) {
         runId: origin.runId,
         outcome: buildParkedResumeOutcome(req),
         message: `The human approval that workflow run "${origin.runId}" parked on (agent callKey "${origin.agent.callKey}") has been ${verdict}. ` +
-            `Resume that run now by calling Workflow with resumeFromRunId: "${origin.runId}" — the decision is already held by the deployment ` +
-            `and will be applied to the parked agent; completed steps replay from the journal. Do not re-issue the original call.`,
+            `Resume that run now: re-invoke Workflow with the SAME script source you launched it from (script / name / scriptPath) ` +
+            `AND resumeFromRunId: "${origin.runId}" — the decision is already held by the deployment and will be applied to the parked ` +
+            `agent; completed steps replay from the journal. Do not re-issue the original call.`,
     };
 }
 export async function decideParkedAgent(deps, req, match) {
@@ -126,7 +144,7 @@ export async function decideParkedAgent(deps, req, match) {
         return { status: 400, body: { error: "remember cannot be applied: this parked agent row carries no root/parent session anchor for the exemption", errorCode: "decide.parked_remember_unsupported", taskId: match.handle } };
     }
     const pendingTool = req.pendingAction?.toolName;
-    if (pendingTool === "AskUserQuestion" && req.decision === "approve" && req.answer === undefined) {
+    if (pendingTool === ASK_USER_QUESTION_TOOL_NAME && req.decision === "approve" && req.answer === undefined) {
         return { status: 400, body: { error: "pending action is AskUserQuestion — approve requires body.answer (the operator's answers[]); deny needs none", errorCode: "decide.parked_answer_required", taskId: match.handle } };
     }
     if (row.name === undefined) {

package/dist/plugins/checkpoint-store-sql.js

@@ -1,4 +1,4 @@
-import { contentKindOf } from "../approval-content-kind.js";
+import { ASK_USER_QUESTION_SQL_LITERAL, contentKindOf } from "../approval-content-kind.js";
 import { createHash } from "node:crypto";
 import { APPROVAL_GATE_KINDS_SQL_IN } from "../tool-approval.js";
 import { CheckpointError, MAX_RULE_TEXT_CHARS, validatePendingSteer, appendPendingSteer, checkpointVersionOf, winnerFromOutcome, summarizeCheckpoint, MAX_SUPPORTED_CHECKPOINT_VERSION, ExecutionOutcomeConflictError, executionRecordDisposition, executionVerdict, } from "@sema-agent/core";
@@ -487,14 +487,14 @@ export class SqlCheckpointStore {
     }
     async reapExpired(cutoff) {
         const res = await this.db.query(this.q("UPDATE checkpoint SET status = 'expired', decided_at_ms = ? " +
-            `WHERE status = 'pending' AND ((deadline IS NOT NULL AND deadline <= ? AND (gate_kind IS NULL OR gate_kind NOT IN ${APPROVAL_GATE_KINDS_SQL_IN} OR COALESCE(tool_name,'') = 'AskUserQuestion')) OR (terminal_at_ms IS NOT NULL AND terminal_at_ms <= ?))`, "UPDATE checkpoint SET status = 'expired', decided_at_ms = $1 " +
-            `WHERE status = 'pending' AND ((deadline IS NOT NULL AND deadline <= $2 AND (gate_kind IS NULL OR gate_kind NOT IN ${APPROVAL_GATE_KINDS_SQL_IN} OR COALESCE(tool_name,'') = 'AskUserQuestion')) OR (terminal_at_ms IS NOT NULL AND terminal_at_ms <= $3))`), [Date.now(), cutoff, cutoff]);
+            `WHERE status = 'pending' AND ((deadline IS NOT NULL AND deadline <= ? AND (gate_kind IS NULL OR gate_kind NOT IN ${APPROVAL_GATE_KINDS_SQL_IN} OR COALESCE(tool_name,'') = ${ASK_USER_QUESTION_SQL_LITERAL})) OR (terminal_at_ms IS NOT NULL AND terminal_at_ms <= ?))`, "UPDATE checkpoint SET status = 'expired', decided_at_ms = $1 " +
+            `WHERE status = 'pending' AND ((deadline IS NOT NULL AND deadline <= $2 AND (gate_kind IS NULL OR gate_kind NOT IN ${APPROVAL_GATE_KINDS_SQL_IN} OR COALESCE(tool_name,'') = ${ASK_USER_QUESTION_SQL_LITERAL})) OR (terminal_at_ms IS NOT NULL AND terminal_at_ms <= $3))`), [Date.now(), cutoff, cutoff]);
         return res.affected;
     }
     async listExpiredApprovalGates(cutoff, limit = 100) {
         const { rows } = await this.db.query(this.q(`SELECT session_id, scope FROM checkpoint WHERE status = 'pending' AND gate_kind IN ${APPROVAL_GATE_KINDS_SQL_IN} ` +
-            "AND COALESCE(tool_name,'') <> 'AskUserQuestion' AND deadline IS NOT NULL AND deadline <= ? ORDER BY deadline ASC LIMIT ?", `SELECT session_id, scope FROM checkpoint WHERE status = 'pending' AND gate_kind IN ${APPROVAL_GATE_KINDS_SQL_IN} ` +
-            "AND COALESCE(tool_name,'') <> 'AskUserQuestion' AND deadline IS NOT NULL AND deadline <= $1 ORDER BY deadline ASC LIMIT $2"), [cutoff, limit]);
+            `AND COALESCE(tool_name,'') <> ${ASK_USER_QUESTION_SQL_LITERAL} AND deadline IS NOT NULL AND deadline <= ? ORDER BY deadline ASC LIMIT ?`, `SELECT session_id, scope FROM checkpoint WHERE status = 'pending' AND gate_kind IN ${APPROVAL_GATE_KINDS_SQL_IN} ` +
+            `AND COALESCE(tool_name,'') <> ${ASK_USER_QUESTION_SQL_LITERAL} AND deadline IS NOT NULL AND deadline <= $1 ORDER BY deadline ASC LIMIT $2`), [cutoff, limit]);
         return rows.map((r) => ({ sessionId: String(r.session_id), scope: String(r.scope) }));
     }
     async listPending(scope) {

package/dist/plugins/e2b-orphan-reclaim.d.ts

@@ -10,10 +10,10 @@
  * memory `capability-probe-fail-direction`;误杀的代价是杀死一个活任务的手,漏杀的代价只是钱):
  *   a. `metadata.semaManaged !== "1"`         → 非我方铸造,provider 侧 query 过滤已排除;防御性重验。
  *   b. `metadata.taskId` 缺席                 → 病态形(factory 恒打标),不杀 + failOpen 留痕。
- *   c. run 行在场:
- *        LIVE 词(running/suspended/needs_review)→ 活,跳过;
- *        TERMINAL 词                           → 孤儿,kill;
- *        两表皆不中的词                        → 词表纪律([ref]):不杀 + failOpen(新词先安全后收编)。
+ *   c. run 行在场(词 → 类问 `RUN_STATUS_CLASS` 属主,S-221):
+ *        类 live / parked(行还能再动)        → 活,跳过;
+ *        类 succeeded / unsuccessful(终局)   → 孤儿,kill;
+ *        属主表外的词(类 undefined)          → 词表纪律([ref]):不杀 + failOpen(新词先安全后收编)。
  *   d. 行不存在:
  *        startedAt 距今 < GRACE                → create→行落库窗口,跳过(防误杀新沙盒);
  *        ≥ GRACE                              → 真孤儿,kill(单库 fleet 方向下行跨副本可见)。

package/dist/plugins/e2b-orphan-reclaim.js

@@ -1,10 +1,13 @@
 import { recordFailOpen } from "../observability/fail-open.js";
+import { runStatusClassOf } from "./store-contracts.js";
 export const E2B_ORPHAN_GRACE_MS = 10 * 60 * 1000;
 export const SEMA_MANAGED_METADATA_KEY = "semaManaged";
-const LIVE_STATUSES = new Set(["running", "suspended", "needs_review"]);
-const TERMINAL_STATUSES = new Set(["completed", "blocked", "failed"]);
-const _statusesCovered = true;
-void _statusesCovered;
+const CLASS_VERDICT = {
+    live: "live",
+    parked: "live",
+    succeeded: "kill",
+    unsuccessful: "kill",
+};
 export async function reclaimOrphanE2bSandboxes(deps) {
     const now = deps.now ?? Date.now;
     const graceMs = deps.graceMs ?? E2B_ORPHAN_GRACE_MS;
@@ -29,28 +32,15 @@ export async function reclaimOrphanE2bSandboxes(deps) {
             if (run === undefined) {
                 verdict = now() - sbx.startedAt.getTime() < graceMs ? "grace" : "kill";
             }
-            else if (LIVE_STATUSES.has(run.status)) {
-                verdict = "live";
-            }
-            else if (TERMINAL_STATUSES.has(run.status)) {
-                verdict = "kill";
-            }
             else {
-                verdict = "unknown";
+                const cls = runStatusClassOf(run.status);
+                verdict = cls === undefined ? "unknown" : CLASS_VERDICT[cls];
             }
         }
         catch {
             verdict = "unknown";
         }
-        if (verdict === "live")
-            summary.skippedLive++;
-        else if (verdict === "grace")
-            summary.skippedGrace++;
-        else if (verdict === "unknown") {
-            summary.skippedUnknown++;
-            recordFailOpen("server.e2b.orphan-skip-unknown");
-        }
-        else {
+        if (verdict === "kill") {
             try {
                 await deps.provider.kill(sbx.sandboxId);
                 summary.reclaimed++;
@@ -61,6 +51,14 @@ export async function reclaimOrphanE2bSandboxes(deps) {
                 deps.logger?.warn("e2b_orphan_kill_failed", { sandboxId: sbx.sandboxId, taskId, error: e instanceof Error ? e.message : String(e) });
             }
         }
+        else if (verdict === "live")
+            summary.skippedLive++;
+        else if (verdict === "grace")
+            summary.skippedGrace++;
+        else {
+            summary.skippedUnknown++;
+            recordFailOpen("server.e2b.orphan-skip-unknown");
+        }
     }
     if (summary.reclaimed > 0 || summary.killFailed > 0) {
         deps.logger?.info("e2b_orphan_reclaim_round", { ...summary });

package/dist/plugins/local-checkpoint-store.js

@@ -1,4 +1,4 @@
-import { contentKindOf } from "../approval-content-kind.js";
+import { ASK_USER_QUESTION_TOOL_NAME, contentKindOf } from "../approval-content-kind.js";
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, readdirSync, renameSync, unlinkSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
@@ -249,7 +249,7 @@ export class LocalCheckpointStore {
             const toolName = cp.pendingAction?.toolName ?? "";
             const deadlineBranch = cp.deadline !== undefined &&
                 cp.deadline <= cutoff &&
-                (gateKind === undefined || !isApprovalGateKind(gateKind) || toolName === "AskUserQuestion");
+                (gateKind === undefined || !isApprovalGateKind(gateKind) || toolName === ASK_USER_QUESTION_TOOL_NAME);
             const terminalBranch = terminalAtOf(cp) <= cutoff;
             if ((deadlineBranch || terminalBranch) && (await this.inner.expire(token, cp.scope)))
                 n++;
@@ -263,7 +263,7 @@ export class LocalCheckpointStore {
             const toolName = cp.pendingAction?.toolName ?? "";
             if (gateKind !== undefined &&
                 isApprovalGateKind(gateKind) &&
-                toolName !== "AskUserQuestion" &&
+                toolName !== ASK_USER_QUESTION_TOOL_NAME &&
                 cp.deadline !== undefined &&
                 cp.deadline <= cutoff)
                 hits.push({ sessionId: cp.sessionId, scope: cp.scope, deadline: cp.deadline });

package/dist/plugins/remote-env-adb.d.ts

@@ -6,6 +6,15 @@ export interface AdbEnvConfig {
     serial: string;
     /** Path to the adb binary. Default "adb" (must be on PATH in the runner image). */
     adbPath?: string;
+    /**
+     * S-213④ / core [ref] —— 本执行环境的 **home 目录**(`ExecutionEnv.homeDir` 座,绝对路径,本环境自己的
+     * 命名空间里)。`~/…` 形权限规则(`Edit(~/.ssh/**)`)对**跑在本 env 里的调用**就以它为基。
+     * 缺席 ⇒ 本 env 声明「我没有 home」,core 对 `~/` 规则判 `unreadable`(fail-closed 的 ask),
+     * 绝不回落引擎进程自己的 home(那在远端腿上是另一个用户的另一个目录 —— 静默守错目录正是 [ref] 的病)。
+     * 值由 `boot/execution-env.ts` 从**唯一属主** `execution-lane-caps.ts` 的 `executionLaneHomeDir` 递进来;
+     * adapter 不自算(两处各算一份 = 422 门与引擎对同一条规则给相反答案)。
+     */
+    homeDir?: string;
     /** On-device workspace root; relative paths resolve against it. Default "/data/local/tmp". */
     mountPath?: string;
     commandTimeoutMs?: number;
@@ -48,6 +57,8 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
      *  同姿态的 ssh 腿早有先例(`remote-env-ssh.ts`「destroy 后一律不复活,显式 connect/reconnect 同禁」),
      *  五条兄弟腿全部 fail-closed,只有 adb 例外 —— 补齐它。 */
     private destroyed;
+    /** core `ExecutionEnv.homeDir`([ref]):本沙箱/目标机上执行用户的 home。见配置同名字段。 */
+    readonly homeDir?: string | undefined;
     private readonly cfg;
     private readonly spawnFn;
     private readonly injectedConnectOnce?;

package/dist/plugins/remote-env-adb.js

@@ -22,6 +22,7 @@ export class RemoteAdbExecutionEnv {
     cwd;
     connected = false;
     destroyed = false;
+    homeDir;
     cfg;
     spawnFn;
     injectedConnectOnce;
@@ -35,6 +36,7 @@ export class RemoteAdbExecutionEnv {
             retry: { maxAttempts: config.retry?.maxAttempts ?? 3, backoffMs: config.retry?.backoffMs ?? 800 },
         };
         this.cwd = this.cfg.mountPath;
+        this.homeDir = config.homeDir;
         this.spawnFn = deps?.spawn ?? spawn;
         this.injectedConnectOnce = deps?.connectOnce;
     }

package/dist/plugins/remote-env-device.d.ts

@@ -54,6 +54,9 @@ export interface DeviceEnvLogger {
     info?(msg: string, fields?: Record<string, unknown>): void;
 }
 export interface DeviceEnvFactoryDeps {
+    /** S-213④ / core [ref]:设备上执行用户的 home(`ExecutionEnv.homeDir` 座)。由 `boot/execution-env.ts`
+     *  从唯一属主 `executionLaneHomeDir` 递进;缺席 ⇒ 本 env 声明「没有 home」,`~/` 规则判 unreadable。 */
+    homeDir?: string;
     hub: DeviceWsHub;
     store: DeviceStore;
     enrollment: DeviceEnrollment;
@@ -71,6 +74,10 @@ interface DeviceEnvConfig {
     deviceId: string;
     owner: DeviceOwner;
     cwd: string;
+    /** S-213④ / core [ref] —— 员工设备上执行用户的 home(`ExecutionEnv.homeDir` 座)。缺席 ⇒ 本 env 声明
+     *  「我没有 home」,`~/` 形权限规则对本腿判 unreadable(fail-closed)。值经 `boot/execution-env.ts`
+     *  从唯一属主 `executionLaneHomeDir` 递进;设备是运行期连进来的,boot 期只有运维显式声明才有值。 */
+    homeDir?: string;
     shellEnv?: Record<string, string>;
     execTimeoutMs: number;
     /** 设备当前连接声明的指令面(`undefined` = 铸 env 时设备不在线 ⇒ 可选面一律缺席)。 */
@@ -79,6 +86,8 @@ interface DeviceEnvConfig {
 }
 export declare class RemoteDeviceExecutionEnv implements RemoteExecutionEnv {
     private readonly cfg;
+    /** core `ExecutionEnv.homeDir`([ref]):设备上执行用户的 home。见 `DeviceEnvConfig.homeDir`。 */
+    readonly homeDir?: string | undefined;
     /**
      * 🔴 `suspendable: false` 在 core 契约里**同时断言**「工作区在目标上外部持久」(remote-env.ts 的
      * load-bearing 不变量)—— 设备工作区 = 员工机磁盘,真持久 ✅,park-only 降级腿因此合法可用。

package/dist/plugins/remote-env-device.js

@@ -109,6 +109,7 @@ function assertPosixDevicePlatform(os, deviceId) {
 }
 export class RemoteDeviceExecutionEnv {
     cfg;
+    homeDir;
     capabilities = { isolation: false, suspendable: false };
     externalContentTarget = true;
     hostLocalPaths = false;
@@ -121,6 +122,7 @@ export class RemoteDeviceExecutionEnv {
     constructor(cfg) {
         this.cfg = cfg;
         this.cwd = cfg.cwd;
+        this.homeDir = cfg.homeDir;
         if (cfg.supports?.has("readLink") === true)
             this.readLink = (p, s) => this.doReadLink(p, s);
         if (cfg.supports?.has("writeFileExclusive") === true)
@@ -724,6 +726,7 @@ export function deviceExecutionEnvFactory(deps) {
             deviceId: binding.deviceId,
             owner: binding.owner,
             cwd: effectiveDeviceCwd(deps.perSessionCwd?.get(ctx.sessionId), ctx.parentCwd, view.row),
+            ...(deps.homeDir === undefined ? {} : { homeDir: deps.homeDir }),
             ...(deps.perSessionShellEnv?.get(ctx.sessionId) === undefined ? {} : { shellEnv: deps.perSessionShellEnv.get(ctx.sessionId) }),
             execTimeoutMs,
             supports: deps.hub.declaredSupports(binding.deviceId),

package/dist/plugins/remote-env-e2b.d.ts

@@ -41,6 +41,15 @@ export interface RemoteContainerEnvConfig extends RemoteEnvObservers {
     template?: string;
     /** Sandbox lifetime in ms (E2B billing window). Default {@link DEFAULT_TIMEOUT_MS}. */
     timeoutMs?: number;
+    /**
+     * S-213④ / core [ref] —— 本执行环境的 **home 目录**(`ExecutionEnv.homeDir` 座,绝对路径,本环境自己的
+     * 命名空间里)。`~/…` 形权限规则(`Edit(~/.ssh/**)`)对**跑在本 env 里的调用**就以它为基。
+     * 缺席 ⇒ 本 env 声明「我没有 home」,core 对 `~/` 规则判 `unreadable`(fail-closed 的 ask),
+     * 绝不回落引擎进程自己的 home(那在远端腿上是另一个用户的另一个目录 —— 静默守错目录正是 [ref] 的病)。
+     * 值由 `boot/execution-env.ts` 从**唯一属主** `execution-lane-caps.ts` 的 `executionLaneHomeDir` 递进来;
+     * adapter 不自算(两处各算一份 = 422 门与引擎对同一条规则给相反答案)。
+     */
+    homeDir?: string;
     /** Workspace root inside the VM; remote paths normalize against it. Default {@link DEFAULT_MOUNT_PATH}. */
     mountPath?: string;
     /** Outbound network for the sandbox (clay: service needs external-network capability). Default `true`. */
@@ -89,6 +98,8 @@ export interface RemoteContainerEnvDeps {
 export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv, BackgroundShellCapability {
     /** Current working directory for relative paths (FileSystem contract; mutable, core may reassign). */
     cwd: string;
+    /** core `ExecutionEnv.homeDir`([ref]):本沙箱/目标机上执行用户的 home。见配置同名字段。 */
+    readonly homeDir?: string | undefined;
     private readonly cfg;
     private readonly sandboxApi;
     private sbx?;

package/dist/plugins/remote-env-e2b.js

@@ -18,6 +18,7 @@ const E2B_BG_PROVIDER_BACKSTOP_PAD_SEC = 30;
 const ok = (value) => ({ ok: true, value });
 export class RemoteContainerExecutionEnv {
     cwd;
+    homeDir;
     cfg;
     sandboxApi;
     sbx;
@@ -38,6 +39,7 @@ export class RemoteContainerExecutionEnv {
             dataTimeoutMs: config.dataTimeoutMs ?? DEFAULT_DATA_TIMEOUT_MS,
         };
         this.cwd = this.cfg.mountPath;
+        this.homeDir = config.homeDir;
         this.sandboxApi = deps.sandboxApi ?? Sandbox;
     }
     capabilities = { isolation: true, suspendable: true };

package/dist/plugins/remote-env-host.d.ts

@@ -20,6 +20,15 @@ export interface HostEnvConfig {
      * own `process.env` is the default base (a local coding agent inherits the user's environment).
      */
     env?: Record<string, string>;
+    /**
+     * S-213④ / core [ref] —— 本执行环境的 **home 目录**(`ExecutionEnv.homeDir` 座,绝对路径,本环境自己的
+     * 命名空间里)。`~/…` 形权限规则(`Edit(~/.ssh/**)`)对**跑在本 env 里的调用**就以它为基。
+     * 缺席 ⇒ 本 env 声明「我没有 home」,core 对 `~/` 规则判 `unreadable`(fail-closed 的 ask),
+     * 绝不回落引擎进程自己的 home(那在远端腿上是另一个用户的另一个目录 —— 静默守错目录正是 [ref] 的病)。
+     * 值由 `boot/execution-env.ts` 从**唯一属主** `execution-lane-caps.ts` 的 `executionLaneHomeDir` 递进来;
+     * adapter 不自算(两处各算一份 = 422 门与引擎对同一条规则给相反答案)。
+     */
+    homeDir?: string;
     /** Per-command wall-clock bound (ms) when the caller gives none. Default {@link DEFAULT_COMMAND_TIMEOUT_MS}. */
     commandTimeoutMs?: number;
     /** Shell-child env policy (D1; mirrors core's `NodeExecutionEnv`). Default `"scrub"`: inherit the worker's
@@ -64,6 +73,8 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     list(ctx: SchedulerContext): Promise<Result<ScheduledTaskSummary[], SchedulerError>>;
     /** Working directory; relative paths resolve against it (ExecutionEnv contract). Starts at the workspace root. */
     cwd: string;
+    /** core `ExecutionEnv.homeDir`([ref]):本沙箱/目标机上执行用户的 home。见配置同名字段。 */
+    readonly homeDir?: string | undefined;
     private readonly workspaceDir;
     private readonly cfg;
     /** Workspace created on disk (lazily, on first use). */

package/dist/plugins/remote-env-host.js

@@ -53,6 +53,7 @@ export class RemoteHostExecutionEnv {
             : Promise.resolve({ ok: false, error: new SchedulerError("unsupported", "scheduler not enabled on this worker") });
     }
     cwd;
+    homeDir;
     workspaceDir;
     cfg;
     prepared = false;
@@ -84,6 +85,7 @@ export class RemoteHostExecutionEnv {
             commandTimeoutMs: config.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS,
         };
         this.cwd = this.workspaceDir;
+        this.homeDir = config.homeDir;
         this.handle = { sandboxId: this.workspaceDir, provider: PROVIDER, mountPath: this.workspaceDir };
     }
     workspaceHandle() {

package/dist/plugins/remote-env-k8s.d.ts

@@ -16,6 +16,15 @@ export interface K8sEnvConfig {
     image: string;
     /** RuntimeClass for the VM boundary. Default "kata-qemu" (set "" to run plain runc — tests/dev only). */
     runtimeClass?: string;
+    /**
+     * S-213④ / core [ref] —— 本执行环境的 **home 目录**(`ExecutionEnv.homeDir` 座,绝对路径,本环境自己的
+     * 命名空间里)。`~/…` 形权限规则(`Edit(~/.ssh/**)`)对**跑在本 env 里的调用**就以它为基。
+     * 缺席 ⇒ 本 env 声明「我没有 home」,core 对 `~/` 规则判 `unreadable`(fail-closed 的 ask),
+     * 绝不回落引擎进程自己的 home(那在远端腿上是另一个用户的另一个目录 —— 静默守错目录正是 [ref] 的病)。
+     * 值由 `boot/execution-env.ts` 从**唯一属主** `execution-lane-caps.ts` 的 `executionLaneHomeDir` 递进来;
+     * adapter 不自算(两处各算一份 = 422 门与引擎对同一条规则给相反答案)。
+     */
+    homeDir?: string;
     /** Workspace root inside the pod; created on connect. Default "/workspace". */
     mountPath?: string;
     /** Pod lifetime (activeDeadlineSeconds) — the leak guard. Default 30min. */
@@ -126,6 +135,8 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     private inFlightExecs;
     /** Memoized in-flight connect (lazy-connect; prevents concurrent double pod-create — the E2B race lesson). */
     private connectPromise?;
+    /** core `ExecutionEnv.homeDir`([ref]):本沙箱/目标机上执行用户的 home。见配置同名字段。 */
+    readonly homeDir?: string | undefined;
     private readonly cfg;
     private readonly deps;
     constructor(config: K8sEnvConfig, deps?: K8sEnvDeps);