@sema-agent/server 7.93.2 → 7.93.4

package/dist/plugins/approval-ask-store-sql.js

@@ -12,6 +12,18 @@ export function assertIdempotencyKeyShape(key) {
         throw new Error(`invalid idempotency key: must be 1-255 chars with no leading/trailing whitespace (got ${JSON.stringify(key.slice(0, 32))}${key.length > 32 ? "…" : ""}, length ${key.length})`);
     }
 }
+export const MAX_SETTLED_BY_CHARS = 16;
+export function assertDecideSettledBy(decision) {
+    const v = decision.settledBy;
+    if (v === undefined)
+        return;
+    if (v.length === 0 || v.length > MAX_SETTLED_BY_CHARS) {
+        throw new Error(`invalid settledBy: the settlement source is one word from the engine's closed set and lands in a VARCHAR(${MAX_SETTLED_BY_CHARS}) column — must be 1-${MAX_SETTLED_BY_CHARS} chars (got ${JSON.stringify(v.slice(0, 32))}${v.length > 32 ? "…" : ""}, length ${v.length})`);
+    }
+    if (decision.decision !== "deny") {
+        throw new Error(`invalid settledBy: a settlement source is only representable on a deny row (got decision="${decision.decision}") — only a person approves an action that EXECUTES, so an approve row carrying a non-human settlement source is a row no replay could honestly hand back to the engine`);
+    }
+}
 export class ApprovalAskReadAbortedError extends Error {
     constructor(where) {
         super(`approval-ask read ${where} aborted by caller`);
@@ -47,6 +59,7 @@ export function projectAskTerminalClaimTruth(row) {
         rev: row.rev,
         decision: row.decision,
         ...(row.updatedInput !== undefined ? { updatedInput: row.updatedInput } : {}),
+        settledBy: row.settledBy,
     };
 }
 export const APPROVAL_ASK_TABLE = "approval_ask";
@@ -87,6 +100,12 @@ export const TIDB_APPROVAL_ASK_STATEMENTS = [
     decision VARCHAR(16) NULL,
     decision_actor TEXT NULL,
     decision_note TEXT NULL,
+    -- settled_by(S-558 / #1016 持久半场):这条决议的结算来源词(NULL = 人答的)。语义、两态读法与
+    -- 「为什么是自己一列而不是塞进 decision_actor」的全文见 AskRow.settledBy 顶注。
+    -- VARCHAR(16):词表属主是 core(AskOutcome.settledBy,今天最长 7 字符 "timeout"),宽度与同表
+    -- decision 同尺同理由 —— 闭集词列,不是自由文本。截断面由入店形门堵死(assertDecideSettledBy),
+    -- 不靠「列够宽就不会截」这种运气(MySQL 非严格模式静默截、PG 直接报错 = 两方言不同答)。
+    settled_by VARCHAR(16) NULL,
     -- updated_input(S-26 / #304,A-054.15 收口):人批准时带的 ctrl+g 编辑实参,JSON 文本,与决议同一条
     -- UPDATE 原子落列;NULL = 没带编辑(与 JSON "null" = 编辑成 null 分家)。LONGTEXT 照 card_json 先例:
     -- 编辑实参是整只工具入参,VARCHAR/TEXT 会造静默截断面。语义三态与读法见 AskRow.updatedInput 顶注。
@@ -166,6 +185,8 @@ export async function ensurePgApprovalAskSchema(q) {
     decision VARCHAR(16) COLLATE "C",
     decision_actor TEXT COLLATE "C",
     decision_note TEXT COLLATE "C",
+    -- settled_by(S-558)—— MySQL 孪生逐字同形(宽度/语义/形门的理由写在那侧的行内注)。
+    settled_by VARCHAR(16) COLLATE "C",
     -- updated_input(S-26 / #304)—— MySQL 孪生逐字同形(语义/类型理由见那侧行内注;PG TEXT 无长度上限)。
     updated_input TEXT COLLATE "C",
     decided_at_ms BIGINT,
@@ -211,7 +232,7 @@ export async function assertApprovalAskRuleMaterialSchema(query, dialect) {
     }
 }
 const ASK_COLS = "ask_id, task_id, source_task_id, session_id, owner, batch_id, tool_call_id, leg_key, parent_tool_call_id, bound_input_hash, state, " +
-    "provisional, rev, decision, decision_actor, decision_note, updated_input, decided_at_ms, denied_reason, gate_token, " +
+    "provisional, rev, decision, decision_actor, decision_note, settled_by, updated_input, decided_at_ms, denied_reason, gate_token, " +
     "gate_bound_call_id, gate_bound_input_hash, idempotency_key, card_json, rule_command, rule_scope_root, schema_version, expires_at_ms, " +
     "created_at_ms, updated_at_ms";
 const BATCH_COLS = "batch_id, task_id, state, bound_ask_id, rev, created_at_ms, updated_at_ms";
@@ -245,6 +266,7 @@ function mapAskRow(r) {
         decision: strOrNull(r.decision) ?? null,
         decisionActor: r.decision_actor == null ? null : parseJsonColumn(r.decision_actor),
         decisionNote: strOrNull(r.decision_note),
+        settledBy: strOrNull(r.settled_by),
         ...(r.updated_input == null ? {} : { updatedInput: parseJsonColumn(r.updated_input) }),
         decidedAtMs: numOrNull(r.decided_at_ms),
         deniedReason: strOrNull(r.denied_reason),
@@ -331,9 +353,9 @@ export class SqlApprovalAskStore {
         try {
             await conn.begin();
             await conn.query(this.q(`INSERT IGNORE INTO ${APPROVAL_BATCH_TABLE} (batch_id, task_id, state, rev, created_at_ms, updated_at_ms) VALUES (?, ?, 'OPEN', 0, ?, ?)`, `INSERT INTO ${APPROVAL_BATCH_TABLE} (batch_id, task_id, state, rev, created_at_ms, updated_at_ms) VALUES ($1, $2, 'OPEN', 0, $3, $4) ON CONFLICT (batch_id) DO NOTHING`), [row.batchId, row.taskId, now, now]);
-            const askInsert = await conn.query(this.q(`INSERT IGNORE INTO ${APPROVAL_ASK_TABLE} (ask_id, task_id, source_task_id, session_id, owner, batch_id, tool_call_id, leg_key, parent_tool_call_id, bound_input_hash, state, provisional, rev, decision, decision_actor, decision_note, decided_at_ms, denied_reason, gate_token, gate_bound_call_id, gate_bound_input_hash, idempotency_key, card_json, rule_command, rule_scope_root, schema_version, expires_at_ms, created_at_ms, updated_at_ms) ` +
-                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'STREAM_PENDING', 0, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, ?, ?, ?, ?, ?, ?, ?)", `INSERT INTO ${APPROVAL_ASK_TABLE} (ask_id, task_id, source_task_id, session_id, owner, batch_id, tool_call_id, leg_key, parent_tool_call_id, bound_input_hash, state, provisional, rev, decision, decision_actor, decision_note, decided_at_ms, denied_reason, gate_token, gate_bound_call_id, gate_bound_input_hash, idempotency_key, card_json, rule_command, rule_scope_root, schema_version, expires_at_ms, created_at_ms, updated_at_ms) ` +
-                "VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, 'STREAM_PENDING', 0, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, $11, $12, $13, $14, $15, $16, $17) ON CONFLICT (ask_id) DO NOTHING"), [
+            const askInsert = await conn.query(this.q(`INSERT IGNORE INTO ${APPROVAL_ASK_TABLE} (ask_id, task_id, source_task_id, session_id, owner, batch_id, tool_call_id, leg_key, parent_tool_call_id, bound_input_hash, state, provisional, rev, decision, decision_actor, decision_note, settled_by, decided_at_ms, denied_reason, gate_token, gate_bound_call_id, gate_bound_input_hash, idempotency_key, card_json, rule_command, rule_scope_root, schema_version, expires_at_ms, created_at_ms, updated_at_ms) ` +
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'STREAM_PENDING', 0, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, ?, ?, ?, ?, ?, ?, ?)", `INSERT INTO ${APPROVAL_ASK_TABLE} (ask_id, task_id, source_task_id, session_id, owner, batch_id, tool_call_id, leg_key, parent_tool_call_id, bound_input_hash, state, provisional, rev, decision, decision_actor, decision_note, settled_by, decided_at_ms, denied_reason, gate_token, gate_bound_call_id, gate_bound_input_hash, idempotency_key, card_json, rule_command, rule_scope_root, schema_version, expires_at_ms, created_at_ms, updated_at_ms) ` +
+                "VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, 'STREAM_PENDING', 0, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, $11, $12, $13, $14, $15, $16, $17) ON CONFLICT (ask_id) DO NOTHING"), [
                 row.askId,
                 row.taskId,
                 row.sourceTaskId,
@@ -389,6 +411,7 @@ export class SqlApprovalAskStore {
     async decideAsk(askId, batchId, decision) {
         if (decision.idempotencyKey != null)
             assertIdempotencyKeyShape(decision.idempotencyKey);
+        assertDecideSettledBy(decision);
         const now = Date.now();
         const dialect = this.db.dialect;
         const conn = await this.db.connect();
@@ -401,10 +424,11 @@ export class SqlApprovalAskStore {
             }
             let askRes;
             try {
-                askRes = await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='DECIDED', decision=${ph(dialect, 1)}, decision_actor=${ph(dialect, 2)}, decision_note=${ph(dialect, 3)}, updated_input=${ph(dialect, 4)}, decided_at_ms=${ph(dialect, 5)}, idempotency_key=${ph(dialect, 6)}, rev=rev+1, updated_at_ms=${ph(dialect, 7)} WHERE ${pendingClaimWhere(dialect, 8)}`, [
+                askRes = await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='DECIDED', decision=${ph(dialect, 1)}, decision_actor=${ph(dialect, 2)}, decision_note=${ph(dialect, 3)}, settled_by=${ph(dialect, 4)}, updated_input=${ph(dialect, 5)}, decided_at_ms=${ph(dialect, 6)}, idempotency_key=${ph(dialect, 7)}, rev=rev+1, updated_at_ms=${ph(dialect, 8)} WHERE ${pendingClaimWhere(dialect, 9)}`, [
                     decision.decision,
                     decision.decisionActor == null ? null : this.json(decision.decisionActor),
                     decision.decisionNote ?? null,
+                    decision.settledBy ?? null,
                     decision.updatedInput === undefined ? null : this.json(decision.updatedInput),
                     now,
                     decision.idempotencyKey ?? null,

package/dist/plugins/host-platform.d.ts

@@ -58,7 +58,11 @@ export declare function trackHostForegroundChild(pid: number): ForegroundChildTi
 /** 注销(`exit` / settle / 领养移交)。按回执身份删 ⇒ 幂等,且**绝不**碰同号的其它登记。 */
 export declare function untrackHostForegroundChild(ticket: ForegroundChildTicket): void;
 /** 一次前台收割的读数。三格分开是**刻意**的:`alreadyDead` 是想要的结果(不是失败),`failed` 是**真的**
- *  没收上来 —— 两者混成一个数就等于把后者静默掉([ref]:这条腿上不许有安静的兜底)。 */
+ *  没收上来 —— 两者混成一个数就等于把后者静默掉([ref]:这条腿上不许有安静的兜底)。
+ *
+ *  🔴 **三格只描述调用的那一拍**(S-557):`failed: []` 读作「这一拍发出去的信号没有被拒」,**不是**
+ *  「机器上一个都没落下」—— 簿在这一拍之后照样可以再登记(受控退的窗里在飞 turn 还在 spawn)。
+ *  「一个都没落下」这句话的承重点是退出边界那只钩,不是任何一次读数。 */
 export interface ForegroundReapReading {
     /** 真发出了杀伤信号的组数。 */
     readonly signalled: number;
@@ -71,9 +75,19 @@ export interface ForegroundReapReading {
  * 收割簿上全部前台子进程组。返回**发出**信号的读数,不是确认死亡数 —— 确认要等,而本函数的调用点之一
  * 是 uncaught 出口。
  *
- * **同步形、一次到位、不等宽限**:两个调用点(`hardShutdown` / uncaught 双钩)都紧挨着 `process.exit`,
- * `await` 一个宽限梯就是把收割赌在一个永远等不到的续段上。上界 = 簿上条数 × 一次 `kill(-pid)` syscall
- * (簿条数被 host lane 的在飞 turn 数界住),没有定时器、没有 promise。
+ * **同步形、一次到位、不等宽限**(S-557 起自述与实现同一句):承重的调用点是收尾链的
+ * `process.once("exit")` 钩 —— `exit` 之后**没有续段**,`await` 一个宽限梯就是把收割赌在一个永远等不到的
+ * 时刻上(`hardShutdown` 终点那次早按只是优化,见 `boot/shutdown.ts` 的两处注)。上界 = 簿上条数 ×
+ * 一次 `kill(-pid)` syscall(簿条数被 host lane 的在飞 turn 数界住),没有定时器、没有 promise。
+ *
+ * 🔴 **「没有定时器」只对 POSIX 成立**(codex 对抗复审 [high],亲读 core dist 验真后如实标注,**不在本仓绕**):
+ * win32 的 `killTreeHard` 落到 core 的 `signalProcessTree`,而它在**装了 Git Bash** 的机器上先 spawn 一只
+ * MSYS 组杀脚本(detached ⇒ 本进程退了它照跑),随后把 `taskkill /F /T` 的**兜底**排在一只 1200ms
+ * `setTimeout` 上 —— 那只定时器在退出边界这一拍跑不到。射程:MSYS 组杀抓不到的**原生**后代可能幸存;
+ * 没装 Git Bash 的机器走的是同步 spawn 的 `taskkill /F /T`,不吃这条。**属主在上游**(本仓只是调用方),
+ * 正解 = core 给一条**无定时器的同步硬收**面(与后台腿那条已登记的上游诉求同一族),下游自铸第二把
+ * win32 杀伤 = 同一语义面两个写者,禁。修前对照:崩溃双钩那两次收割紧挨 `exit(1)`,同样跑不到那只
+ * 定时器 ⇒ 这是**既有**暴露面,不是退出边界新开的洞;而受控退的早收割仍有十秒量级的窗,定时器跑得完。
  *
  * 🔴 **为什么是 `killTreeHard` 而不是 SIGTERM**(codex 对抗复审 [high],亲跑复现后改):软鞍的语义是
  * 「给它一个收尾窗,到点我再升级」,而这两个调用点之后**没有任何人在场**去升级 —— 一个
@@ -85,8 +99,9 @@ export interface ForegroundReapReading {
  * 真的成立。后台腿的宽限梯不受影响(那条腿有自己的属主,且不在本簿里)。
  */
 export declare function reapHostForegroundChildren(): ForegroundReapReading;
-/** 测试面:簿上现存条数(产品面没有消费者 —— 收割腿只读它自己那只 Set)。 */
-export declare function liveHostForegroundChildCountForTest(): number;
+/** 簿上现存条数。S-557 起**产品面也读它**(退出边界钩的「exit 时簿上还剩几条」哨兵),与第二本同形簿的
+ *  {@link liveEphemeralHostWorkspaceCount} 同名同形 —— 所以名字里不再带 `ForTest`(零别名,旧名直接消失)。 */
+export declare function liveHostForegroundChildCount(): number;
 /**
  * win32 env-key case collapse (design D1). Windows env keys are case-insensitive; Node hands the
  * object to CreateProcess as-is, so a case-sensitive merge that produced BOTH `Path` (inherited) and `PATH`

package/dist/plugins/host-platform.js

@@ -83,7 +83,7 @@ export function reapHostForegroundChildren() {
     liveHostForegroundGroups.clear();
     return { signalled, alreadyDead, failed };
 }
-export function liveHostForegroundChildCountForTest() {
+export function liveHostForegroundChildCount() {
     return liveHostForegroundGroups.size;
 }
 export function collapseWin32EnvKeys(env) {

package/dist/plugins/store-backend.js

@@ -8,6 +8,7 @@ import { FileOutcomeSink } from "./file-outcome-sink.js";
 import { TiDBWorkflowRunStore, TiDBWorkflowCompletionInbox, TiDBWorkflowNotifyJournalStore, TiDBWorkflowAgentSessionIndex, PgWorkflowRunStore, PgWorkflowCompletionInbox, PgWorkflowNotifyJournalStore, PgWorkflowAgentSessionIndex } from "./workflow-run-store-sql.js";
 import { FileRunStore } from "./file-run-store.js";
 import { StoreBootRefusalError } from "./store-contracts.js";
+import { buildStoreOpenRefusalTail } from "./store-open-refusal.js";
 import { acquireLocalBackendWithWait } from "./store-lock-wait.js";
 import { NO_SQL_MIGRATIONS, runSqlOneTimeMigrations } from "./one-time-migrations.js";
 import { LocalSessionStore } from "./local-session-store.js";
@@ -234,8 +235,9 @@ class LocalBackend {
         catch (e) {
             if (e instanceof AdoptionError)
                 throw e;
-            throw new Error(`DB_BACKEND=local cannot open data dir ${root}: ${e instanceof Error ? e.message : String(e)} ` +
-                "(another HTTP service / run-local instance may own it; stop it first or set LOCAL_DATA_ROOT to a free dir)");
+            const tail = buildStoreOpenRefusalTail(e, "http");
+            throw new Error(`DB_BACKEND=local cannot open data dir ${root}: ${e instanceof Error ? e.message : String(e)}` +
+                (tail === undefined ? "" : ` ${tail}`));
         }
         this.sessionStore = new LocalSessionStore(new FileSessionRepo(this.fileBackend.root), this.fileBackend.root);
         this.runStore = new FileRunStore(this.fileBackend.root, {

package/dist/plugins/store-open-refusal.d.ts

@@ -0,0 +1,11 @@
+/** 取数据根的两条路。语义上只是「换根的通道叫什么」,不是两套出路。 */
+export type StoreOpenLane = "http" | "run-local";
+/**
+ * 数据根拒启句的**尾巴**:锁类失败 ⇒ 该码的出路;其余一切 ⇒ `undefined`(不加话)。
+ *
+ * @param err  构造 `FileStorageBackend` 时抛出来的东西(未经重铸 —— `store-lock-wait.ts` 的等待腿到窗
+ *             重抛时刻意保留 `code` 与类型身份,正是为了让这里分派得成)。
+ * @param lane 哪条路在问。只影响「换根」半句的措辞。
+ */
+export declare function buildStoreOpenRefusalTail(err: unknown, lane: StoreOpenLane): string | undefined;
+//# sourceMappingURL=store-open-refusal.d.ts.map

package/dist/plugins/store-open-refusal.js

@@ -0,0 +1,23 @@
+import { FileStoreLockError } from "@sema-agent/core";
+const FREE_ROOT_KNOB = {
+    http: "set LOCAL_DATA_ROOT to a free dir",
+    "run-local": "use a different --root",
+};
+export function buildStoreOpenRefusalTail(err, lane) {
+    if (!(err instanceof FileStoreLockError))
+        return undefined;
+    const code = err.code;
+    switch (code) {
+        case "store.dir_in_use":
+            return `(a LIVE process — possibly this one — owns this data dir; stop that process first, or ${FREE_ROOT_KNOB[lane]})`;
+        case "store.dir_claiming":
+            return "(transient: another process is taking over a crashed owner's lock — it either finishes or is itself reclaimed, so just retry in a moment)";
+        case "store.lock_unreadable":
+            return '(only a human can resolve this: do what the line above says, and nothing more — "unreadable" is NOT proof the owner is gone: a lock this process merely lacks permission to read looks identical, so confirm the holder is really stale (or fix the permission) before removing anything)';
+        default: {
+            const unhandled = code;
+            return `(unrecognized file-store lock code ${String(unhandled)}: this server build has no verified way out for it — treat the line above as the whole story)`;
+        }
+    }
+}
+//# sourceMappingURL=store-open-refusal.js.map

package/dist/run-local.js

@@ -7,7 +7,7 @@ import { realpathSync } from "node:fs";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { loadRemoteExec } from "@sema-agent/settings-schema/node";
-import { Runner, uuidv7, parseModelMention, AdoptionError, FileStorageBackend, NodeExecutionEnv, NodeLspManager, TtlSessionStore, CenterPromptSource, FilePromptArtifactStore, FilePromptSourceStateStore, MemoryPromptArtifactStore, MemoryPromptSourceStateStore, defaultTaskRegistry } from "@sema-agent/core";
+import { Runner, uuidv7, parseModelMention, FileStorageBackend, NodeExecutionEnv, NodeLspManager, TtlSessionStore, CenterPromptSource, FilePromptArtifactStore, FilePromptSourceStateStore, MemoryPromptArtifactStore, MemoryPromptSourceStateStore, defaultTaskRegistry } from "@sema-agent/core";
 import { hasOperatorGateIntent } from "./approval.js";
 import { createBrain } from "./brain.js";
 import { assertGuardPatternsUsable, buildOnlySensitiveBaselineWarning, createApprovalBaselinePolicy, createDeploymentGovernanceInputs, } from "./deployment-governance.js";
@@ -17,6 +17,7 @@ import { taskWallClockSec } from "./task-workflow.js";
 import { applyCatalogToSource } from "./capabilities/center-prompts.js";
 import { validatePromptsDomain, CORE_ENGINE_VERSION } from "./prompts-domain-validate.js";
 import { buildUnpricedCeilingNotice, loadConfig, logConfigDiagnostics, parseNumOrFailNonNegative } from "./config.js";
+import { buildStoreOpenRefusalTail } from "./plugins/store-open-refusal.js";
 import { acquireLocalBackendWithWait } from "./plugins/store-lock-wait.js";
 import { createConfigProvider } from "./config-provider.js";
 import { applyEffective, applyCenterReadFace, resolveMcpServers, mcpForScenario, resolveA2aPeers, a2aForScenario } from "./config-center/facade.js";
@@ -272,9 +273,9 @@ export async function runLocal(argv, deps = {}) {
     }
     catch (e) {
         printErr(`cannot open local data dir ${root}: ${e instanceof Error ? e.message : String(e)}`);
-        if (!(e instanceof AdoptionError)) {
-            printErr("(another run-local/engine instance may own it; finish it first, or use a different --root)");
-        }
+        const tail = buildStoreOpenRefusalTail(e, "run-local");
+        if (tail !== undefined)
+            printErr(tail);
         return 2;
     }
     const sessionStore = fileBackend.sessionStore;

package/dist/tool-approval.d.ts

@@ -1,8 +1,9 @@
+import type { HostDecidedBy, HostSettledBy } from "./host-decision.js";
 import type { IncomingMessage } from "node:http";
 import { type AskRequest, type AskOutcome, type ReadRootGrantCandidate, type RuleOffer } from "@sema-agent/core";
 import { type CardRulePersisted, type RuleConsentLane } from "./rules-consent.js";
 import { type DenialLimitFallback, type RuleOffersAbsence, type ApprovalRequestFrame, type ApprovalRevokeFrame, type RuleEvidenceProjection } from "./approval-card.js";
-import { type ApprovalAskStore } from "./plugins/approval-ask-store-sql.js";
+import { type ApprovalAskStore, type AskRow } from "./plugins/approval-ask-store-sql.js";
 import type { ApprovalAskAuditSink } from "./approval-ask-audit-store.js";
 import { type GovernanceAskMarks } from "./governance-ask-marks.js";
 /** [ref]:审批 gate kind 闭集(core gateMatch 的 `human`/`irreversible_ask` ↔ outcome.gate "policy_ask")。
@@ -53,6 +54,13 @@ export interface ParkedAskRedeemRequest {
     decision: "approve" | "deny";
     /** [ref] 同源的人写理由(deny 时 core 把它交给模型;allow 只进审计面)。 */
     note?: string;
+    /** #1016:回决体自报的**结算来源**,原样过境到耐久腿的 `hostDecision.decidedBy`(缺席 ⇒ `"person"`)。
+     *  live 命中臂与本 PARKED 臂读**同一格** —— 同一份体落在哪条臂上只取决于副本与时序。
+     *  型 = `string`(本层证得出的全部);判词的是耐久座的属主 core,cast 在 `hostDecisionFacts` 那一处。
+     *  ⚠️ 两座的**词表并不相同**(live = `human`/`timeout`/`policy`,耐久 = `person`/`sla_timeout`/`policy`,
+     *  只在 `policy` 上相交)—— 这正是这条 wire 键只开 `"policy"` 一个词的原因,也是它不能声明成其中任何
+     *  一只闭集的原因:同一个串要落到两个不同词表的座上。 */
+    settledBy?: string;
     /** [ref] ctrl+g 编辑放行的实参整体替换(approve 才有意义)。 */
     updatedInput?: unknown;
     /** 发起本次 respond 的**已验证**调用方(live 腿 `gatedPrincipal` 的那一把)。席在赎回之前拿它与
@@ -575,6 +583,23 @@ export declare const PERSIST_RULE_BATCH_EXCLUSIVE_ERROR = "persistRule.batchOffe
  * 指定 scope = 让一次「在项目 A 里点的同意」写成一条覆盖项目 B(或全局)的常驻放行 —— 那是这条轴上
  * 最贵的一次扩权。静默忽略同样不行:客户端会以为自己设上了。响亮拒,一句话说清谁拥有这一格。
  */
+/**
+ * #1016 —— `settledBy` 与 allow 族**互斥**的那一句(两条回决腿共用一份文本:同一个体在两条口上必须
+ * 拿到同一句话)。判的是**键在不在**,不是它是什么词。
+ */
+/**
+ * #1016 —— `settledBy` 的**形**拒句(两条回决腿共用一份文本,与 {@link SETTLED_BY_DENY_ONLY} 同姿势)。
+ *
+ * 🔴 **判形 ≠ 判词**:本层证得出的只有「它是个串」;「它是不是词表里的那个串」由**引擎**判(两条腿各有
+ * 一处响亮拒,读数在收车档)。加这道形门的理由是**类型必须说真话**(wire 边界强类型宪法):
+ * 一个非串值往下会落进 `AskOutcome.settledBy`(core 的串闭集)与本仓审计账本的 `settledBy?: string` 席 ——
+ * 两处都声明成串,而运行期塞进去一个数字。引擎对它照样响亮拒(实测三形一致:`"bogus"` / `1` / `null`
+ * 都是 `approver_contract` 的 fail-closed deny),所以这不是在补一个 fail-open,而是**不让本层的类型撒谎**;
+ * 顺带把「一个非串永远不可能是闭集成员」这件必然的事拒在最早的地方,与同一只 parser 里 `note` /
+ * `persistRule.rule` / `persistRule.edited` 三道既有形门**同族**(那三道在,只有本格没有 = 本格才是特例)。
+ */
+export declare const SETTLED_BY_MUST_BE_STRING = "settledBy must be a string \u2014 the settlement source is one word from the engine's closed set, and this layer judges only the SHAPE (which word it is, the engine decides)";
+export declare const SETTLED_BY_DENY_ONLY = "settledBy is only meaningful with decision \"deny\" \u2014 only a person approves an action that EXECUTES, so a self-reported settlement source on an allow is a contradiction the engine refuses; the refusal would arrive too late to undo this door's own side effects (a session allow-all grant, a persisted rule, a DECIDED row that replays as a plain approval), so it is refused here, before the decision";
 export declare const PERSIST_RULE_SCOPE_REFUSED = "this endpoint does not accept a rule scope \u2014 the server mints it from where the approval happened (send neither `scope` nor `persistRule.scope`)";
 /** Validate the respond body — the closed three-choice enum (rationale in the module header). */
 export declare function parseToolApprovalResponse(body: unknown): {
@@ -583,10 +608,21 @@ export declare function parseToolApprovalResponse(body: unknown): {
     updatedInput?: unknown;
     persistRule?: ParsedPersistRule;
     note?: string;
+    settledBy?: string;
 } | {
     ok: false;
     error: string;
 };
+/**
+ * #1016 —— wire 上**开给调用方**的那一个词,从 core 的两只闭集里取**交集**。
+ *
+ * 🔴 它是一条**文档钉**,不是过境值的型(过境值是 `string`,理由在 `parseToolApprovalResponse` 那处注):
+ * `"human"` 与缺席同义、`"timeout"` 是本仓自己观察到的窗(客户端说出来就是替服务端伪证一件只有服务端
+ * 看得见的事),而耐久座那边的 `"person"` / `"sla_timeout"` 同理。两只词表**只在 `"policy"` 上相交** ——
+ * 这条 wire 键因此恰好只开那一个词。core 哪天退役它,这里**编译期先红**,而不是在 wire 上静默留一个
+ * 两个座都已经不收的词;`test/tool-approval.test.ts` 的 #1016 那组按它写判据。
+ */
+export type RespondSettledBy = Extract<HostSettledBy, HostDecidedBy>;
 /**
  * [ref] R-13 C —— `UNATTENDED_APPROVAL_POLICY` 的**闭集**词表([ref]Q1「裁2:A+C」/[ref] 裁②)。
  *
@@ -745,6 +781,33 @@ export declare function resolveApprovalLeg(input: {
      *  「窗偏短」(安全侧,§7.3 的误差方向论证)。 */
     nowMonotonicMs: number;
 }): ApprovalLegAssembly;
+/** 一条 **DECIDED 行**能交还给引擎的全部形(`AskOutcome` 减掉 park 路由那一臂 —— 一条有决议的行
+ *  从定义上不是「投递面拿走了它」)。{@link ToolApprovalCoordinator.notifyExternalDecision} 收的就是它。 */
+export type DecidedAskOutcome = Exclude<AskOutcome, "unavailable">;
+/** 铸点的入参形 = 行上与**这条决议本身**有关的三格。整行(`AskRow`)与 claim 败方读数都满足。 */
+type DecidedRowFacts = Pick<AskRow, "decision" | "settledBy"> & {
+    updatedInput?: unknown;
+};
+/**
+ * 🔴 **一条 DECIDED 行 → 交还给引擎的那个 outcome:全仓唯一铸点**(S-558)。
+ *
+ * 存在理由 = 这条投影此前被**手抄**在每个消费点上(`row.decision === "approve"` + `row.updatedInput`,
+ * 六处),于是给行加一格新事实就得记得改六处 —— `settledBy` 正是那个没人改到的格:一次**策略拒**在
+ * 重放 / 兄弟广播 / 歧义提交恢复三条路上全都退化成裸 `false`,而裸 `false` 在 core 那边逐字是
+ * 「**一个人**拒绝了」。手抄投影全面下线([ref]):消费点交行,形由这里铸。
+ *
+ * 三条读法,每条的属主注在别处,这里只落笔:
+ *  · **方向** —— `decision !== "approve"` 即拒(列的二值由店的 CAS 保证);
+ *  · **编辑载荷**([ref])—— `updatedInput` 键缺席 = 没带编辑 ⇒ 裸 `true`;在场(**含 `null`**)= 编辑的
+ *    字面值 ⇒ 对象臂(语义三态的唯一属主 = `AskRow.updatedInput` 顶注);
+ *  · **结算来源**(S-558)—— 行上非 null 即宿主自报的那个词(`null` = 人决,与「不铸这个键」同义;
+ *    语义属主 = `AskRow.settledBy` 顶注)。
+ *
+ * 🔴 approve 臂**不读**来源位,而且那不是「静默丢」:store 的入店形门(`assertDecideSettledBy`)让
+ * 「approve 行带来源位」在**写面不可表示** —— core 对 `{allow:true, settledBy}` 是 fail-closed 拒,
+ * 一条那样的行没有任何读回路径能诚实地交还给引擎,所以它在落库那一刻就被拒掉了,而不是在这里被吞掉。
+ */
+export declare function outcomeOfDecidedRow(row: DecidedRowFacts): DecidedAskOutcome;
 /**
  * Coordinates the live tool-approval HITL for the singleton runner. Process-local + same-replica (the pending map is
  * in memory, like QuestionCoordinator): a respond that lands on another replica finds nothing → 404. Present (passed
@@ -1137,7 +1200,7 @@ export declare class ToolApprovalCoordinator {
      * 真决议」,重复注册必须拿到**同一个**决议(approve 就是 approve)——合并会把外部批准的重复条目错
      * 结算成拒绝。已被结算过的条目再调 settle 天然无操作(幂等),所以本口对「赢家自己已 settle」安全。
      */
-    notifyExternalDecision(askId: string, allowed: boolean, updatedInput?: unknown): {
+    notifyExternalDecision(askId: string, outcome: DecidedAskOutcome): {
         settled: number;
     };
     /**
@@ -1436,4 +1499,5 @@ export declare class ToolApprovalCoordinator {
     /** [ref]:当前在场的 park 墓碑数(有界性的可观测面 —— 判据据它证「帽是硬的、过期会被清」)。 */
     parkTombstoneCount(): number;
 }
+export {};
 //# sourceMappingURL=tool-approval.d.ts.map

package/dist/tool-approval.js

@@ -83,6 +83,11 @@ export const PERSIST_RULE_TEXT_ERROR = `persistRule.rule must be a non-empty str
 export const PERSIST_RULE_EDITED_FLAG_ERROR = "persistRule.edited must be a boolean when present";
 export const PERSIST_RULE_BATCH_INDEX_ERROR = "persistRule.batchOfferIndex must be a non-negative integer when present";
 export const PERSIST_RULE_BATCH_EXCLUSIVE_ERROR = "persistRule.batchOfferIndex is mutually exclusive with persistRule.rule / persistRule.edited — send exactly one arm";
+export const SETTLED_BY_MUST_BE_STRING = "settledBy must be a string — the settlement source is one word from the engine's closed set, and this layer judges only the SHAPE (which word it is, the engine decides)";
+function respondSettledBy(parsed) {
+    return parsed.settledBy;
+}
+export const SETTLED_BY_DENY_ONLY = 'settledBy is only meaningful with decision "deny" — only a person approves an action that EXECUTES, so a self-reported settlement source on an allow is a contradiction the engine refuses; the refusal would arrive too late to undo this door\'s own side effects (a session allow-all grant, a persisted rule, a DECIDED row that replays as a plain approval), so it is refused here, before the decision';
 export const PERSIST_RULE_SCOPE_REFUSED = "this endpoint does not accept a rule scope — the server mints it from where the approval happened (send neither `scope` nor `persistRule.scope`)";
 export function parseToolApprovalResponse(body) {
     if (body === null || typeof body !== "object" || Array.isArray(body))
@@ -127,12 +132,19 @@ export function parseToolApprovalResponse(body) {
             }
             note = rawNote;
         }
+        const rawSettledBy = body.settledBy;
+        if (rawSettledBy !== undefined && d !== "deny")
+            return { ok: false, error: SETTLED_BY_DENY_ONLY };
+        if (rawSettledBy !== undefined && typeof rawSettledBy !== "string")
+            return { ok: false, error: SETTLED_BY_MUST_BE_STRING };
+        const settledBy = rawSettledBy;
         return {
             ok: true,
             value: d,
             ...(d !== "deny" && u !== undefined ? { updatedInput: u } : {}),
             ...(persistRule !== undefined ? { persistRule } : {}),
             ...(note !== undefined ? { note } : {}),
+            ...(rawSettledBy !== undefined ? { settledBy } : {}),
         };
     }
     return { ok: false, error: 'decision must be one of "allow" | "allow_session" | "deny"' };
@@ -213,21 +225,28 @@ function effectiveAskWindowMs(ttlMs, windowMarginMs, legDeadlineMonotonic, nowMo
     return Math.min(ttlMs, Math.max(0, legRemainingMs - windowMarginMs));
 }
 function replayTerminalAskRow(row) {
-    if (row.state === "DECIDED") {
-        if (row.decision !== "approve")
-            return false;
-        return row.updatedInput !== undefined ? { allow: true, updatedInput: row.updatedInput } : true;
-    }
+    if (row.state === "DECIDED")
+        return outcomeOfDecidedRow(row);
     if (row.state === "PARKING" || row.state === "PARKED")
         return "unavailable";
     return false;
 }
-function settleArgsOf(outcome) {
-    if (outcome === "unavailable")
-        return "unavailable";
+export function outcomeOfDecidedRow(row) {
+    if (row.decision !== "approve")
+        return row.settledBy !== null ? { allow: false, settledBy: row.settledBy } : false;
+    return row.updatedInput !== undefined ? { allow: true, updatedInput: row.updatedInput } : true;
+}
+function settleArgsOfDecided(outcome) {
     if (typeof outcome === "boolean")
         return { allowed: outcome };
-    return { allowed: outcome.allow, ...(outcome.updatedInput !== undefined ? { updatedInput: outcome.updatedInput } : {}) };
+    return {
+        allowed: outcome.allow,
+        ...(outcome.updatedInput !== undefined ? { updatedInput: outcome.updatedInput } : {}),
+        ...(outcome.settledBy !== undefined ? { settledBy: outcome.settledBy } : {}),
+    };
+}
+function settleArgsOf(outcome) {
+    return outcome === "unavailable" ? "unavailable" : settleArgsOfDecided(outcome);
 }
 export class ToolApprovalCoordinator {
     als = new AsyncLocalStorage();
@@ -607,16 +626,17 @@ export class ToolApprovalCoordinator {
     classifyClaimLoss(askId, current, _where) {
         if (current.state === "absent")
             return { kind: "absent" };
-        const replayed = settleArgsOf(replayTerminalAskRow(current));
-        if (replayed === "unavailable")
+        const replayedOutcome = replayTerminalAskRow(current);
+        if (replayedOutcome === "unavailable")
             return { kind: "parked" };
+        const replayed = settleArgsOfDecided(replayedOutcome);
         if (!replayed.allowed)
-            return { kind: "denied" };
+            return { kind: "decided", outcome: replayedOutcome };
         if (replayed.updatedInput !== undefined)
-            return { kind: "approved", updatedInput: replayed.updatedInput };
+            return { kind: "decided", outcome: replayedOutcome };
         if (this.editedDecisionInFlight(askId))
             return { kind: "edit-in-flight" };
-        return { kind: "approved" };
+        return { kind: "decided", outcome: replayedOutcome };
     }
     hasOtherSuspendedOwner(askId, self) {
         if (askId === undefined)
@@ -704,13 +724,14 @@ export class ToolApprovalCoordinator {
         }
         return tomb;
     }
-    notifyExternalDecision(askId, allowed, updatedInput) {
+    notifyExternalDecision(askId, outcome) {
         const entries = this.pendingByAskId.get(askId);
         if (!entries)
             return { settled: 0 };
+        const args = settleArgsOfDecided(outcome);
         let settled = 0;
         for (const entry of [...entries]) {
-            entry.settle(allowed, allowed ? "allowed" : "denied", updatedInput);
+            entry.settle(args.allowed, args.allowed ? "allowed" : "denied", args.updatedInput, args.settledBy);
             settled += 1;
         }
         return { settled };
@@ -1082,11 +1103,8 @@ export class ToolApprovalCoordinator {
             if (askId === undefined)
                 return;
             switch (read.kind) {
-                case "approved":
-                    this.notifyExternalDecision(askId, true, read.updatedInput);
-                    return;
-                case "denied":
-                    this.notifyExternalDecision(askId, false);
+                case "decided":
+                    this.notifyExternalDecision(askId, read.outcome);
                     return;
                 case "parked":
                     this.settleSameAskIdParkRoute(askId);
@@ -1102,14 +1120,12 @@ export class ToolApprovalCoordinator {
         };
         const settleFromClaimLoss = (read) => {
             switch (read.kind) {
-                case "approved":
-                    settle(true, "allowed", read.updatedInput);
-                    broadcastClaimTruth(read);
-                    return true;
-                case "denied":
-                    settle(false, "denied");
+                case "decided": {
+                    const args = settleArgsOfDecided(read.outcome);
+                    settle(args.allowed, args.allowed ? "allowed" : "denied", args.updatedInput, args.settledBy);
                     broadcastClaimTruth(read);
                     return true;
+                }
                 case "parked":
                     windowRouteUnavailable = true;
                     settle(false, "expired");
@@ -1613,7 +1629,7 @@ export class ToolApprovalCoordinator {
             });
             return this.notPending();
         }
-        this.notifyExternalDecision(row.askId, row.decision === "approve", row.updatedInput);
+        this.notifyExternalDecision(row.askId, outcomeOfDecidedRow(row));
         return {
             status: 200,
             body: {
@@ -1656,6 +1672,7 @@ export class ToolApprovalCoordinator {
                     gateBoundInputHash: row.gateBoundInputHash,
                     decision,
                     ...(parsed.note !== undefined ? { note: parsed.note } : {}),
+                    ...(parsed.settledBy !== undefined ? { settledBy: parsed.settledBy } : {}),
                     ...(parsed.updatedInput !== undefined && parsed.value !== "deny" ? { updatedInput: parsed.updatedInput } : {}),
                     ...(principal !== undefined ? { principal } : {}),
                     ...(httpReq !== undefined ? { httpReq } : {}),
@@ -1885,21 +1902,23 @@ export class ToolApprovalCoordinator {
         }
     }
     async respondWithCas(askStore, askId, batchId, id, entry, parsed, ruleEligibility) {
-        let decidedWon = false;
-        let confirmedRowPayload;
+        let winnerRow;
+        let ambiguousConfirmedRow;
         let noteLanded = false;
         try {
             const decided = await this.withStoreDeadline(askStore.decideAsk(askId, batchId, {
                 decision: parsed.value === "deny" ? "deny" : "approve",
                 ...(parsed.note !== undefined ? { decisionNote: parsed.note } : {}),
                 ...(parsed.value !== "deny" && parsed.updatedInput !== undefined ? { updatedInput: parsed.updatedInput } : {}),
+                ...(parsed.settledBy !== undefined ? { settledBy: respondSettledBy(parsed) } : {}),
             }), "decideAsk", DURABLE_CALL_TIMEOUT_MS, (late) => {
                 if (late.ok)
-                    this.notifyExternalDecision(askId, parsed.value !== "deny", parsed.updatedInput);
+                    this.notifyExternalDecision(askId, outcomeOfDecidedRow(late.row));
             });
-            decidedWon = decided.ok;
-            if (decided.ok)
+            if (decided.ok) {
+                winnerRow = decided.row;
                 noteLanded = true;
+            }
             if (!decided.ok) {
                 return this.notPending();
             }
@@ -1910,8 +1929,8 @@ export class ToolApprovalCoordinator {
             try {
                 const row = await this.withStoreDeadline(askStore.getAsk(askId), "getAsk(decideAsk-confirm)", DURABLE_CONVERGE_READ_TIMEOUT_MS);
                 if (row?.state === "DECIDED" && row.decision === (parsed.value === "deny" ? "deny" : "approve")) {
-                    decidedWon = true;
-                    confirmedRowPayload = { updatedInput: row.updatedInput };
+                    winnerRow = row;
+                    ambiguousConfirmedRow = row;
                     noteLanded = parsed.note === undefined || row.decisionNote === parsed.note;
                 }
             }
@@ -1920,22 +1939,25 @@ export class ToolApprovalCoordinator {
             }
         }
         const wantAllowed = parsed.value !== "deny";
+        const decidedWon = winnerRow !== undefined;
         if (this.pending.get(id) !== entry) {
-            if (decidedWon)
-                this.notifyExternalDecision(askId, wantAllowed, confirmedRowPayload !== undefined ? confirmedRowPayload.updatedInput : parsed.updatedInput);
+            if (winnerRow !== undefined)
+                this.notifyExternalDecision(askId, outcomeOfDecidedRow(winnerRow));
             const converged = decidedWon && entry.settledOutcome === (wantAllowed ? "allowed" : "denied");
             if (!converged) {
                 return this.notPending();
             }
             return this.finishRespond(id, entry, parsed, { updatedInputDelivered: false, noteRecorded: noteLanded });
         }
-        const payloadIsMine = confirmedRowPayload === undefined ||
-            approvalPayloadFingerprint({ updatedInput: confirmedRowPayload.updatedInput }) === approvalPayloadFingerprint({ updatedInput: parsed.updatedInput });
+        const payloadIsMine = ambiguousConfirmedRow === undefined ||
+            approvalPayloadFingerprint({ updatedInput: ambiguousConfirmedRow.updatedInput }) === approvalPayloadFingerprint({ updatedInput: parsed.updatedInput });
         const result = this.finishRespond(id, entry, parsed, {
             noteRecorded: noteLanded,
-            ...(confirmedRowPayload !== undefined ? { settlePayload: confirmedRowPayload, updatedInputDelivered: payloadIsMine } : {}),
+            ...(winnerRow !== undefined ? { settleOutcome: outcomeOfDecidedRow(winnerRow) } : {}),
+            ...(ambiguousConfirmedRow !== undefined ? { updatedInputDelivered: payloadIsMine } : {}),
         });
-        this.notifyExternalDecision(askId, wantAllowed, confirmedRowPayload !== undefined ? confirmedRowPayload.updatedInput : parsed.updatedInput);
+        if (winnerRow !== undefined)
+            this.notifyExternalDecision(askId, outcomeOfDecidedRow(winnerRow));
         return result;
     }
     finishRespond(id, entry, parsed, opts) {
@@ -1952,7 +1974,8 @@ export class ToolApprovalCoordinator {
             this.allowAllSessions.add(sessionAllowKey(entry.owner, entry.sessionId, sessionAllowCategory(entry.toolName)));
         }
         const allowed = parsed.value !== "deny";
-        entry.settle(allowed, allowed ? "allowed" : "denied", opts?.settlePayload !== undefined ? opts.settlePayload.updatedInput : parsed.updatedInput, undefined, allowed ? undefined : parsed.note);
+        const settleArgs = opts?.settleOutcome !== undefined ? settleArgsOfDecided(opts.settleOutcome) : { allowed, updatedInput: parsed.updatedInput, settledBy: respondSettledBy(parsed) };
+        entry.settle(settleArgs.allowed, settleArgs.allowed ? "allowed" : "denied", settleArgs.updatedInput, settleArgs.settledBy, settleArgs.allowed ? undefined : parsed.note);
         const updatedInputDelivered = opts?.updatedInputDelivered ?? true;
         const noteRecorded = opts?.noteRecorded ?? false;
         return {
@@ -2025,14 +2048,14 @@ export class ToolApprovalCoordinator {
                 continue;
             if (this.editedDecisionInFlight(askId))
                 continue;
-            const outcome = settleArgsOf(replayTerminalAskRow(row));
+            const outcome = replayTerminalAskRow(row);
             if (outcome === "unavailable") {
                 const before = this.pendingByAskId.get(askId)?.size ?? 0;
                 this.settleSameAskIdParkRoute(askId);
                 settled += before;
                 continue;
             }
-            const delivered = this.notifyExternalDecision(askId, outcome.allowed, outcome.updatedInput).settled;
+            const delivered = this.notifyExternalDecision(askId, outcome).settled;
             settled += delivered;
         }
         const backlog = Math.max(0, candidates.length - polled);