@sema-agent/server 7.110.0 → 7.111.0

package/dist/plugins/file-outcome-sink.js

@@ -1,14 +1,20 @@
-import { mkdirSync, appendFileSync } from "node:fs";
 import { join } from "node:path";
+import { AppendLog, ensureDir } from "@sema-agent/core";
 export class FileOutcomeSink {
     path;
+    log;
     constructor(root) {
         const dir = join(root, "outcomes");
-        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        ensureDir(dir);
         this.path = join(dir, "outcomes.jsonl");
     }
     async recordCore(o) {
-        appendFileSync(this.path, `${JSON.stringify({ at: Date.now(), ...o })}\n`, { mode: 0o600 });
+        this.log ??= new AppendLog(this.path);
+        this.log.append({ at: Date.now(), ...o }, false);
+    }
+    dispose() {
+        this.log?.close();
+        this.log = undefined;
     }
 }
 //# sourceMappingURL=file-outcome-sink.js.map

package/dist/plugins/file-run-store.js

@@ -7,7 +7,7 @@ import { randomBytes } from "node:crypto";
 import { AppendLog, atomicWriteFile, ensureDir, isProcessLive, processFingerprint, sanitizePathComponent, writeThenLink } from "@sema-agent/core";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { replayJsonlSkipping } from "../observability/corrupt-read-seat.js";
-import { RUN_STALLED_ERROR, StoreBootRefusalError } from "./store-contracts.js";
+import { RUN_ORPHANED_ERROR, RUN_STALLED_ERROR, StoreBootRefusalError, buildRunOrphanedError } from "./store-contracts.js";
 import { notifyRunTerminal } from "../observability/run-terminal.js";
 import { migrateRetiredAskOrigin } from "./one-time-migrations.js";
 const ownerEq = (a, b) => (a ?? null) === (b ?? null);
@@ -603,7 +603,7 @@ export class FileRunStore {
         for (const r of orphans) {
             r.status = "failed";
             r.result = null;
-            r.error = "run orphaned by engine restart";
+            r.error = RUN_ORPHANED_ERROR;
             r.updatedAt = new Date();
             this.persist(r);
         }
@@ -808,7 +808,7 @@ export class FileRunStore {
             pidStillRunning: owner !== undefined && isProcessLive({ pid: owner.pid }),
             note: "the claim's owner process is provably not the one that wrote it (fingerprint falsified, or the pid is gone) and the row has nothing left to resume — taking the claim over",
         });
-        return { kind: "stale", reason: `run orphaned by engine restart (claim held by ${who}, which is gone)`, snapshot };
+        return { kind: "stale", reason: buildRunOrphanedError(who), snapshot };
     }
     takeOverClaim(sessionId, reason, snapshot) {
         const nowClaim = readClaimRecord(singleRecordOf(this.readRecords(this.activePath(sessionId), CLAIM_RECORD_SHAPE)), sessionId);

package/dist/plugins/retention-store-sql.d.ts

@@ -8,7 +8,7 @@
  * core 把破坏性级联整个下沉成 store 方法(`expireCheckpoints` / `deleteExpiredSessions` /
  * `deleteOrphanToolResults`),并点名 server 的 session-purge 顺序契约(E21,`boot/session-faces.ts` 的
  * `purgeSession` 协调器)为参考实现。那条顺序契约横跨**十余张表**(run 账本 / checkpoint / tool_result /
- * anchor / exemption / policy / attachment / snapshot / workflow inbox / session_meta+event),而设计稿
+ * anchor / exemption / policy / attachment / 用户输入受理账本 / snapshot / workflow inbox / session_meta+event),而设计稿
  * §6 的 F5 又要求「审计行与删除同一个 DB 事务」—— 一个事务 ⇒ 一条连接 ⇒ **一个属主**。
  *
  * ⇒ 布局裁定:本能力**不能**挂在 session / checkpoint / tool-result 任何一只店上(每只店只拥有自己的表,

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

@@ -1,5 +1,6 @@
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { TASK_LIST_ITEM_TABLE, TASK_LIST_META_TABLE, taskListKeyFor } from "./task-list-store-sql.js";
+import { USER_INPUT_ACCEPTANCE_TABLE } from "./user-input-ledger-sql.js";
 import { ensureIndexes } from "./ensure-index.js";
 export const MANAGED_RETENTION = "managed";
 export const UNMANAGED_RETENTION = "none";
@@ -382,6 +383,7 @@ export class SqlRetentionStore {
             ["session_policy", "session_id"],
             ["session_policy_rev_mark", "session_id"],
             ...(this.opts.taskAttachmentTable ? [["task_attachment", "session_id"]] : []),
+            [USER_INPUT_ACCEPTANCE_TABLE, "session_id"],
             ["file_history_tracked", "scope"],
             ["file_history_version", "scope"],
             ["file_history_boundary", "scope"],

package/dist/plugins/store-backend.js

@@ -277,6 +277,7 @@ class LocalBackend {
         this.approvalAskStore.dispose();
         this.sendFileLedgerStore.dispose();
         this.userInputLedgerStore.dispose();
+        this.outcomeSinkInst.dispose();
         this.workflowJournalStore.dispose();
         this.checkpointStoreInst?.close();
         this.permissionRuleStoresInst?.dispose();

package/dist/plugins/store-contracts.d.ts

@@ -106,11 +106,28 @@ export type PersistedTaskResult = TaskResult & {
 };
 /**
  * 🔴 run 店「持有它的实例丢了」那一判的**行上落款**(S-928 codex r1-F1 提为常量):三只 run 店的 `reapStale` 把心跳过期的 running 行翻成
- * `failed` 并写下这一句。它是 run 店死亡判决留在行上的唯一证据 —— 用户输入受理账本的 SQL 收敛臂据它在 reap **之后**仍能判出「写者死了」
- * (`user-input-ledger.ts` 的判词)。改这一句 = 改那条判据;所以三个写者与那一个读者都只引用本常量。读时折叠成同一句话的 wire 展示站点
+ * `failed` 并写下这一句。它是 run 店死亡判决留在行上的证据之一(另一只 = {@link RUN_ORPHANED_ERROR})—— 用户输入受理账本的收敛判词
+ * (S-969 L8 起两车道同一只)据 {@link isHolderDeathVerdict} 在 reap **之后**仍能判出「写者死了」。改这一句 = 改那条判据;所以三个写者与那一个读者都只引用本常量。读时折叠成同一句话的 wire 展示站点
  * (`routes/runs.ts` 的 stale 折叠、`routes/trace-usage.ts` 的 WORKER_DOWN 帧)刻意留字面量:它们由文案冻结门逐字钉着,且不参与任何判据。
  */
 export declare const RUN_STALLED_ERROR = "run stalled (instance lost?)";
+/**
+ * 🔴 File 车道「持有它的进程随重启没了」那一判的行上落款(S-969 L8 提为常量):boot 孤儿回收(`FileRunStore.reclaimOrphanedAtBoot`,
+ * 数据根 LOCK 作证前世进程已死 ⇒ 仍 running 的行无条件判孤儿)与运行期 claim 接管的 running 臂(`judgeClaim`,外来 + owner 已死 + 无可续)
+ * 都写这一句;接管臂在括号里附上前任持有者的进程指纹(取证用,形 = {@link buildRunOrphanedError})。与 {@link RUN_STALLED_ERROR} 同一种身份:
+ * run 店写在行上的**死亡判决**,读者 = {@link isHolderDeathVerdict}。
+ */
+export declare const RUN_ORPHANED_ERROR = "run orphaned by engine restart";
+/** File 车道两个孤儿落款写口共用的那一句(`heldBy` = 接管臂的前任持有者描述;boot 回收臂不带)。 */
+export declare function buildRunOrphanedError(heldBy?: string): string;
+/**
+ * run 行上是不是一份**持有者死亡判决**:`failed`,且 `error` 是 run 店的两只死亡落款之一 —— {@link RUN_STALLED_ERROR}(三只 run 店的
+ * `reapStale`:心跳过期 ⇒ 实例丢了)或 {@link RUN_ORPHANED_ERROR}(File 车道:前世进程随重启没了;接管臂带括注)。判决只说「持有它的那个进程
+ * 死在这条腿收场之前」,不说是谁 —— 持有者是谁读行上的 `instanceId`(两只落款都不改它)。唯一读者 = 用户输入受理账本的收敛判词
+ * (`src/user-input-ledger.ts` `judgeOpen`);改任一句落款 = 改那条判据,所以写者与读者都只引用本模块的常量。
+ * 正常失败(别的 error)/ park 过期收割(`approval expired before decision`:腿 park 过)都**不是**死亡判决。
+ */
+export declare function isHolderDeathVerdict(run: Pick<RunRecord, "status" | "error">): boolean;
 export interface RunRecord {
     taskId: string;
     sessionId: string;

package/dist/plugins/store-contracts.js

@@ -1,6 +1,15 @@
 export class StoreBootRefusalError extends Error {
 }
 export const RUN_STALLED_ERROR = "run stalled (instance lost?)";
+export const RUN_ORPHANED_ERROR = "run orphaned by engine restart";
+export function buildRunOrphanedError(heldBy) {
+    return heldBy === undefined ? RUN_ORPHANED_ERROR : `${RUN_ORPHANED_ERROR} (claim held by ${heldBy}, which is gone)`;
+}
+export function isHolderDeathVerdict(run) {
+    if (run.status !== "failed" || run.error === null)
+        return false;
+    return run.error === RUN_STALLED_ERROR || run.error === RUN_ORPHANED_ERROR || run.error.startsWith(`${RUN_ORPHANED_ERROR} (`);
+}
 export const RUN_STATUS_CLASS = {
     running: "live",
     completed: "succeeded",

package/dist/plugins/user-input-ledger-file.d.ts

@@ -1,5 +1,5 @@
 import type { Logger } from "../observability/logger.js";
-import { UserInputLedgerFold, type NewUserInputAcceptance, type OpenScanCursor, type SettleHow, type UserInputAcceptance, type UserInputLedgerRecord, type UserInputLedgerStore } from "../user-input-ledger.js";
+import { UserInputLedgerFold, type NewUserInputAcceptance, type OpenScanCursor, type OpenScanPage, type SettleHow, type UserInputAcceptance, type UserInputLedgerRecord, type UserInputLedgerStore } from "../user-input-ledger.js";
 /** 账本文件名(取证按文件字节对账 —— 崩溃语义的真源是文件)。 */
 export declare const USER_INPUT_LEDGER_FILE = "ledger.jsonl";
 /** 纯内存孪生(测试 / 夹具)。 */
@@ -13,9 +13,11 @@ export declare class MemoryUserInputLedgerStore implements UserInputLedgerStore
     settle(acceptId: string, how: SettleHow, atMs: number): Promise<boolean>;
     converge(acceptId: string, atMs: number): Promise<boolean>;
     announce(acceptId: string, taskId: string, atMs: number): Promise<boolean>;
-    listOpen(after?: OpenScanCursor, limit?: number): Promise<UserInputAcceptance[]>;
+    listOpen(after?: OpenScanCursor, limit?: number): Promise<OpenScanPage>;
     listCrashed(sessionId: string): Promise<UserInputAcceptance[]>;
     listUnannounced(sessionId: string, limit: number): Promise<UserInputAcceptance[]>;
+    /** S-965:会话树删除 = 一行会话级墓碑(守卫:该会话此刻有行 ⇒ 落;否则零写、回 0)。写抛 ⇒ 原样抛(协调器据此不删会话本体)。 */
+    deleteBySession(sessionId: string): Promise<number>;
 }
 /** local 车道(File)孪生。 */
 export declare class FileUserInputLedgerStore extends MemoryUserInputLedgerStore {

package/dist/plugins/user-input-ledger-file.js

@@ -39,6 +39,10 @@ export class MemoryUserInputLedgerStore {
     async listUnannounced(sessionId, limit) {
         return this.fold.listUnannounced(sessionId, limit);
     }
+    async deleteBySession(sessionId) {
+        const n = this.fold.sessionSize(sessionId);
+        return (await this.write({ kind: "erased", sessionId, at: Date.now() })) ? n : 0;
+    }
 }
 const RECORD_SHAPE = {
     what: "user-input ledger record of an unknown kind or with a missing / out-of-vocabulary member",
@@ -46,8 +50,14 @@ const RECORD_SHAPE = {
         const o = record;
         const str = (k) => (typeof o[k] === "string" && o[k].length > 0 ? o[k] : undefined);
         const at = typeof o.at === "number" && Number.isFinite(o.at) ? o.at : undefined;
+        if (at === undefined)
+            return undefined;
+        if (o.kind === "erased") {
+            const sessionId = str("sessionId");
+            return sessionId === undefined ? undefined : { kind: "erased", sessionId, at };
+        }
         const acceptId = str("acceptId");
-        if (acceptId === undefined || at === undefined)
+        if (acceptId === undefined)
             return undefined;
         switch (o.kind) {
             case "accepted": {

package/dist/plugins/user-input-ledger-sql.d.ts

@@ -13,13 +13,22 @@
  * 无 owner / principal / scope 列(行随它挂靠的会话走 —— 收编形Ⅲ);`writer` 是受理进程的 `instanceId`(随进程消亡,不是租户轴)。
  * 行里不存输入正文(只有身份与时刻)。
  *
- * ## 不在本表上的东西
- * 会话删除 / 托管留存的级联**未接**(行至多是几条身份 + 时刻;S-928 收车档登记的欠账)。
+ * ## 会话树删除(S-965)
+ * `deleteBySession` = `DELETE … WHERE session_id = ?`(真删行;File 孪生是一行会话级墓碑,同义)。两条删会话树的级联各有一臂:在线删除协调器
+ * 经本动词;托管留存的事务化孪生(`retention-store-sql.ts` `purgeSessionTrees` ④)在**自己的事务**里对本表发同一只谓词(`session_id` 单键,
+ * 多值集合按方言)—— 它不调店,理由见该文件顶注的布局裁定(一个事务 ⇒ 一条连接 ⇒ 一个属主)。谓词走 `(session_id, state, accepted_at_ms)` 索引的前缀。
+ *
+ * ## 读不出的行(S-969 L6):逐行跳过,游标按原始行推进
+ * 三只读口都按 `state` 列取行(`= 'open'` / `= 'converged'`),所以 `state` 词表外的行任何读口都取不到;被取到的行上读不出的列 —— `input_kind`
+ * 词表外(新版本写的输入族:滚动发布 / 回滚的混版窗)、收敛行缺 `state_at_ms` —— 由 {@link readRows} 逐行跳过 + 计 F 类 tag
+ * `server.user-input-ledger.corrupt-record-skipped`(File 孪生重放坏行的同一只登记座),其余行照交。修前一行读不出 ⇒ 整页抛:收敛断点不前进
+ * (其后的 open 行永不收敛)、同会话的通告与读面一并失效。`listOpen` 的续翻游标取**原始**末行的键(`accept_id` / `accepted_at_ms` 是 NOT NULL
+ * 键列,坏行也读得出),跳过的行照样推进;页里少了几行不等于扫到底(那由原始行数判)。SQL 文本 / DDL 不变。
  */
 import type { Pool as MysqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type SqlDriver } from "./sql-driver.js";
-import { type NewUserInputAcceptance, type OpenScanCursor, type SettleHow, type UserInputAcceptance, type UserInputLedgerStore } from "../user-input-ledger.js";
+import { type NewUserInputAcceptance, type OpenScanCursor, type OpenScanPage, type SettleHow, type UserInputAcceptance, type UserInputLedgerStore } from "../user-input-ledger.js";
 export declare const USER_INPUT_ACCEPTANCE_TABLE = "user_input_acceptance";
 export declare class SqlUserInputLedgerStore implements UserInputLedgerStore {
     private readonly db;
@@ -29,9 +38,10 @@ export declare class SqlUserInputLedgerStore implements UserInputLedgerStore {
     settle(acceptId: string, how: SettleHow, atMs: number): Promise<boolean>;
     converge(acceptId: string, atMs: number): Promise<boolean>;
     announce(acceptId: string, taskId: string, atMs: number): Promise<boolean>;
-    listOpen(after?: OpenScanCursor, limit?: number): Promise<UserInputAcceptance[]>;
+    listOpen(after?: OpenScanCursor, limit?: number): Promise<OpenScanPage>;
     listCrashed(sessionId: string): Promise<UserInputAcceptance[]>;
     listUnannounced(sessionId: string, limit: number): Promise<UserInputAcceptance[]>;
+    deleteBySession(sessionId: string): Promise<number>;
 }
 /** MySQL 协议腿的构造绑定。 */
 export declare class TiDBUserInputLedgerStore extends SqlUserInputLedgerStore {

package/dist/plugins/user-input-ledger-sql.js

@@ -1,3 +1,4 @@
+import { recordFailOpen } from "../observability/fail-open.js";
 import { isDupKeyError } from "./sql-errors.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { assertPageLimit, CRASHED_CAUSE, SETTLE_HOW_WORDS, USER_INPUT_KIND_WORDS, USER_INPUT_OPEN_SCAN_MAX, USER_INPUT_SESSION_READ_MAX, } from "../user-input-ledger.js";
@@ -12,35 +13,57 @@ function rowState(r) {
         case "settled": {
             const how = String(r["settle_how"]);
             if (!Object.hasOwn(SETTLE_HOW_WORDS, how) || !Number.isFinite(at))
-                break;
+                return undefined;
             return { kind: "settled", how: how, atMs: at };
         }
         case "converged":
             if (!Number.isFinite(at))
-                break;
+                return undefined;
             return { kind: "converged", cause: CRASHED_CAUSE, atMs: at };
         default:
-            break;
+            return undefined;
     }
-    throw new Error(`${USER_INPUT_ACCEPTANCE_TABLE} row ${String(r["accept_id"])}: unreadable state (${String(r["state"])} / ${String(r["settle_how"])} / ${String(r["state_at_ms"])})`);
 }
-function rowToAcceptance(r) {
+function readRow(r) {
     const input = String(r["input_kind"]);
     if (!Object.hasOwn(USER_INPUT_KIND_WORDS, input))
-        throw new Error(`${USER_INPUT_ACCEPTANCE_TABLE} row ${String(r["accept_id"])}: input_kind ${input} is not a ledger word`);
+        return { ok: false, reason: `input_kind ${input} is not a ledger word` };
+    const state = rowState(r);
+    if (state === undefined)
+        return { ok: false, reason: `unreadable state (${String(r["state"])} / ${String(r["settle_how"])} / ${String(r["state_at_ms"])})` };
     const announcedAt = r["announced_at_ms"] == null ? undefined : Number(r["announced_at_ms"]);
     return {
-        acceptId: String(r["accept_id"]),
-        input: input,
-        messageId: String(r["message_id"]),
-        sessionId: String(r["session_id"]),
-        taskId: String(r["task_id"]),
-        writer: String(r["writer"]),
-        acceptedAtMs: Number(r["accepted_at_ms"]),
-        state: rowState(r),
-        ...(announcedAt !== undefined ? { announced: { atMs: announcedAt, taskId: String(r["announced_task_id"]) } } : {}),
+        ok: true,
+        acceptance: {
+            acceptId: String(r["accept_id"]),
+            input: input,
+            messageId: String(r["message_id"]),
+            sessionId: String(r["session_id"]),
+            taskId: String(r["task_id"]),
+            writer: String(r["writer"]),
+            acceptedAtMs: Number(r["accepted_at_ms"]),
+            state,
+            ...(announcedAt !== undefined ? { announced: { atMs: announcedAt, taskId: String(r["announced_task_id"]) } } : {}),
+        },
     };
 }
+function readRows(rows, op) {
+    const out = [];
+    for (const r of rows) {
+        const read = readRow(r);
+        if (read.ok)
+            out.push(read.acceptance);
+        else
+            recordFailOpen("server.user-input-ledger.corrupt-record-skipped", `table=${USER_INPUT_ACCEPTANCE_TABLE} op=${op} accept_id=${String(r["accept_id"])} ${read.reason}`);
+    }
+    return out;
+}
+function rawCursor(r) {
+    const acceptedAtMs = Number(r["accepted_at_ms"]);
+    if (!Number.isFinite(acceptedAtMs))
+        throw new Error(`${USER_INPUT_ACCEPTANCE_TABLE} row ${String(r["accept_id"])}: accepted_at_ms ${String(r["accepted_at_ms"])} is not a number — cannot page past it`);
+    return { acceptedAtMs, acceptId: String(r["accept_id"]) };
+}
 export class SqlUserInputLedgerStore {
     db;
     constructor(db) {
@@ -76,16 +99,21 @@ export class SqlUserInputLedgerStore {
         const { rows } = after === undefined
             ? await this.db.query(this.q(`SELECT ${COLUMNS} FROM ${USER_INPUT_ACCEPTANCE_TABLE} WHERE state = 'open' ORDER BY accepted_at_ms, accept_id LIMIT ${limit}`, `SELECT ${COLUMNS} FROM ${USER_INPUT_ACCEPTANCE_TABLE} WHERE state = 'open' ORDER BY accepted_at_ms, accept_id LIMIT ${limit}`), [])
             : await this.db.query(this.q(`SELECT ${COLUMNS} FROM ${USER_INPUT_ACCEPTANCE_TABLE} WHERE state = 'open' AND (accepted_at_ms > ? OR (accepted_at_ms = ? AND accept_id > ?)) ORDER BY accepted_at_ms, accept_id LIMIT ${limit}`, `SELECT ${COLUMNS} FROM ${USER_INPUT_ACCEPTANCE_TABLE} WHERE state = 'open' AND (accepted_at_ms > $1 OR (accepted_at_ms = $2 AND accept_id > $3)) ORDER BY accepted_at_ms, accept_id LIMIT ${limit}`), [after.acceptedAtMs, after.acceptedAtMs, after.acceptId]);
-        return rows.map(rowToAcceptance);
+        const open = readRows(rows, "listOpen");
+        return rows.length === limit ? { open, next: rawCursor(rows[rows.length - 1]) } : { open };
     }
     async listCrashed(sessionId) {
         const { rows } = await this.db.query(this.q(`SELECT ${COLUMNS} FROM ${USER_INPUT_ACCEPTANCE_TABLE} WHERE session_id = ? AND state = 'converged' ORDER BY accepted_at_ms DESC, accept_id DESC LIMIT ${USER_INPUT_SESSION_READ_MAX}`, `SELECT ${COLUMNS} FROM ${USER_INPUT_ACCEPTANCE_TABLE} WHERE session_id = $1 AND state = 'converged' ORDER BY accepted_at_ms DESC, accept_id DESC LIMIT ${USER_INPUT_SESSION_READ_MAX}`), [sessionId]);
-        return rows.map(rowToAcceptance).reverse();
+        return readRows(rows, "listCrashed").reverse();
     }
     async listUnannounced(sessionId, limit) {
         const n = assertPageLimit("listUnannounced", limit);
         const { rows } = await this.db.query(this.q(`SELECT ${COLUMNS} FROM ${USER_INPUT_ACCEPTANCE_TABLE} WHERE session_id = ? AND state = 'converged' AND announced_at_ms IS NULL ORDER BY accepted_at_ms, accept_id LIMIT ${n}`, `SELECT ${COLUMNS} FROM ${USER_INPUT_ACCEPTANCE_TABLE} WHERE session_id = $1 AND state = 'converged' AND announced_at_ms IS NULL ORDER BY accepted_at_ms, accept_id LIMIT ${n}`), [sessionId]);
-        return rows.map(rowToAcceptance);
+        return readRows(rows, "listUnannounced");
+    }
+    async deleteBySession(sessionId) {
+        const res = await this.db.query(this.q(`DELETE FROM ${USER_INPUT_ACCEPTANCE_TABLE} WHERE session_id = ?`, `DELETE FROM ${USER_INPUT_ACCEPTANCE_TABLE} WHERE session_id = $1`), [sessionId]);
+        return res.affected;
     }
 }
 export class TiDBUserInputLedgerStore extends SqlUserInputLedgerStore {

package/dist/project-memory.d.ts

@@ -25,7 +25,8 @@ interface ProjectMemoryCtx {
  *  every CLAUDE file it finds, per directory level up the ancestor chain, whereas this loader reads one root and
  *  takes the single first hit. */
 declare const INSTRUCTION_FILE_CHAIN: readonly ["CLAUDE.md", ".claude/CLAUDE.md", "AGENTS.md", ".claude/AGENTS.md"];
-type ChainMember = (typeof INSTRUCTION_FILE_CHAIN)[number];
+/** 一个链成员(相对项目根的拼写)。导出给 S-961 的 wire 段与它的值闭集登记(`trace/self-minted-wire.ts`)—— 链长一员,两处 tsc 跟着红。 */
+export type InstructionChainMember = (typeof INSTRUCTION_FILE_CHAIN)[number];
 /** Recover (root, rel) for a path the LOADER declared — every declared path is `root + one chain member`.
  *  The probe needs this to re-run the loader's parent-directory symlink gate each round (self-review: the probe
  *  checked only the final component, so swapping `.claude` for a symlink out of the repo MID-RUN made the probe
@@ -33,7 +34,7 @@ type ChainMember = (typeof INSTRUCTION_FILE_CHAIN)[number];
  *  calls it with the host `node:path`. */
 export declare function instructionChainCoordinates(absPath: string, p?: PlatformPath): {
     root: string;
-    rel: ChainMember;
+    rel: InstructionChainMember;
 } | null;
 /**
  * Build a `loadProjectMemory` for the host lane. Returns null (skip) unless hands are enabled AND cwd is a local
@@ -54,6 +55,13 @@ export declare function instructionChainCoordinates(absPath: string, p?: Platfor
  * an absolute local directory) is "not applicable", not "none" — it never reaches the mint (O6, see `LoadOutcome`). The member is the one the snapshot carries — a cache hit answers the cached pick, so
  * the notice follows what the model actually reads, not the disk (a same-process edit changes nothing until the
  * snapshot is re-read: restart, post-compact, or a new session).
+ *
+ * S-961 — the same statement (same predicate, same member) also settles the calling LEG's `wiring_manifest.instructions`
+ * segment through {@link settleLegInstructionStatement} (`instruction-selection.ts`): the leg scope is the run identity
+ * the ctx does not carry, and the first call inside a leg's scope whose `ctx.sessionId` equals the leg's session is that
+ * leg's own prepare (a session-less adhoc leg falls back to plain first-call; [ref] X1). The segment projects
+ * `instructionFile`, not `instructionSources`: an empty selected file with no git narrative returns no answer and so no
+ * `instructionSources`, yet it IS the pick (it shadows every member below it) — and the notice reads the same value.
  */
 export declare function makeLoadProjectMemory(opts: {
     logger?: {

package/dist/project-memory.js

@@ -3,6 +3,7 @@ import { execFile } from "node:child_process";
 import { createHmac, randomBytes } from "node:crypto";
 import hostPath, { isAbsolute, join } from "node:path";
 import { announceInstructionSource } from "./instruction-source-notice.js";
+import { settleLegInstructionStatement } from "./instruction-selection.js";
 import { gitSubprocessEnv } from "./server-secret-env.js";
 import { redactSecrets } from "./trace/redact.js";
 const INSTRUCTION_FILE_CHAIN = ["CLAUDE.md", ".claude/CLAUDE.md", "AGENTS.md", ".claude/AGENTS.md"];
@@ -92,8 +93,10 @@ export function makeLoadProjectMemory(opts) {
     const seat = opts.instructionSource;
     return async (ctx) => {
         const outcome = await loadOutcome(ctx);
-        if (seat && ctx.sessionId && !ctx.isSubagent && outcome.walked)
-            await announceInstructionSource(seat, ctx.sessionId, outcome.instructionFile);
+        const statement = outcome.walked && !ctx.isSubagent ? { stated: true, file: outcome.instructionFile } : { stated: false };
+        settleLegInstructionStatement(statement, ctx.sessionId);
+        if (seat && ctx.sessionId && statement.stated)
+            await announceInstructionSource(seat, ctx.sessionId, statement.file);
         return outcome.answer;
     };
     async function loadOutcome(ctx) {

package/dist/runs.js

@@ -6,6 +6,7 @@ import { isSessionErrorCode, sessionErrorHttp } from "./session-error-wire.js";
 import { redactErrorMessage } from "./observability/run-terminal.js";
 import { withPrincipal } from "./observability/principal-context.js";
 import { withModelReachScope } from "./model-reach-scope.js";
+import { createInstructionSelectionLeg } from "./instruction-selection.js";
 import { redactSecrets } from "./trace/redact.js";
 import { taskNotificationEventData, appendModelUsageDelta, appendPromptManifest, attachModelUsage } from "./trace/project.js";
 import { createLedgerSink } from "./trace/ledger-sink.js";
@@ -247,7 +248,8 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
         metrics?.addGauge("runs_active", -1);
         metrics?.inc("tasks_total", { status: "needs_review" });
     };
-    const sink = createLedgerSink({ appendEvent: (seq, type, data) => runStore.appendEvent(taskId, seq, type, data), persistThinking, notifiedKeys, onActivity: (kind, statusData) => recordTurnActivity(taskId, kind, statusData) });
+    const instructionLeg = createInstructionSelectionLeg();
+    const sink = createLedgerSink({ appendEvent: (seq, type, data) => runStore.appendEvent(taskId, seq, type, data), persistThinking, notifiedKeys, onActivity: (kind, statusData) => recordTurnActivity(taskId, kind, statusData), instructionsSegment: instructionLeg.segment });
     const append = (type, data) => sink.append(type, data);
     const flush = () => sink.flush();
     const flushModelUsage = () => appendModelUsageDelta(append, modelUsage, taskId);
@@ -422,7 +424,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 await append("suggestions", { suggestions: suggestions.map((s) => redactSecrets(s)) });
             }
         };
-        await withModelReachScope(spec.sessionId, () => withPrincipal(principal, () => {
+        await instructionLeg.run(spec.sessionId, () => withModelReachScope(spec.sessionId, () => withPrincipal(principal, () => {
             const withElicit = elicitation
                 ? () => elicitation.runWithContext({ taskId, owner: elicitOwner ?? owner, emit: elicitEmit, abortSignal: cancelCtrl.signal }, runBody)
                 : runBody;
@@ -445,7 +447,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
             return sendUserFile
                 ? sendUserFile.runWithContext({ taskId, emit: (frame) => { const { type, ...rest } = frame; return append(type, rest); } }, withApproval)
                 : withApproval();
-        }));
+        })));
         if (!reached && cancelCtrl.signal.aborted) {
             try {
                 await flush();

package/dist/trace/ledger-sink.d.ts

@@ -2,6 +2,7 @@ import { type TerminalCause } from "@sema-agent/core";
 import { brainStatusEventData } from "./project.js";
 import { NotifiedKeys } from "../orchestration/workflow-completion-inbox.js";
 import { type LedgerEventType, type ParkLedgerEventType } from "./ledger-events.js";
+import type { InstructionsSegment } from "../instruction-selection.js";
 /**
  * LedgerSink — the SINGLE "stream event → durable runs-ledger" projection, shared by the background leg
  * (runs.ts `runInBackground`) and the sync `/v1/tasks/stream` detach lane (server.ts, `x-detach-on-disconnect`).
@@ -115,5 +116,8 @@ export declare function createLedgerSink(opts: {
      *  各传自己看得见的那个词(位①=流事件 `ev.type`,位②=账本行 `type`);拿不到类型的打点方
      *  (core 的 onActivity 第五席、resume 腿手动打点)省参,`kind` 诚实缺席(见 turn-activity.ts)。 */
     onActivity?: (kind?: string, statusData?: Record<string, unknown>) => void;
+    /** S-961:这条腿的 `wiring_manifest.instructions` 段(腿的 `InstructionSelectionLeg.segment`)。**必填**:账本行与 live 帧是
+     *  同一条腿的两个载体,段必须来自同一只腿;在投帧那一刻读(core 推帧之前已 await 过 loader)。返回 `undefined` ⇒ 段缺席。 */
+    instructionsSegment: () => InstructionsSegment | undefined;
 }): LedgerSink;
 //# sourceMappingURL=ledger-sink.d.ts.map

package/dist/trace/ledger-sink.js

@@ -97,7 +97,7 @@ export function createLedgerSink(opts) {
                 await append("workspace_changed", workspaceChangedEventData(ev));
                 break;
             case "wiring_manifest":
-                await append("wiring_manifest", wiringManifestEventData(ev));
+                await append("wiring_manifest", wiringManifestEventData(ev, opts.instructionsSegment()));
                 break;
             case "tool_roster_delta": {
                 const rosterDelta = toolRosterDeltaEventData(ev);

package/dist/trace/project.d.ts

@@ -28,6 +28,7 @@ import type { RunEvent, RunRecord } from "../plugins/store-contracts.js";
 import type { ModelUsageDelta, ModelUsageTracker, PromptManifestRecord } from "../budget.js";
 import { type SemaProvenanceInput } from "./sema-provenance.js";
 import type { LedgerEventType } from "./ledger-events.js";
+import type { InstructionsSegment } from "../instruction-selection.js";
 /** 账本写口的统一签名 —— `type` 是**闭集**(`ledger-events.ts`):新型必须先登记,否则调用点编译红
  *  (codex 交叉复审 F2:别名门 `ap("x")` 与动态首参让纯词法门结构性抓不全)。 */
 type AppendFn = (type: LedgerEventType, data: unknown) => Promise<void>;
@@ -719,11 +720,18 @@ export declare function toolRosterDeltaEventData(ev: {
     eventId?: unknown;
     parentToolCallId?: unknown;
 }): Record<string, unknown> | undefined;
+/**
+ * 🔴 S-961(7.111.0)**第二参 `instructions` 必传**(值可以是 `undefined`):`wiring_manifest` 上唯一一段**本仓自铸**的段
+ * —— 这条腿的 project-memory loader 选中的指令文件链成员,`{ selected: string[] }`。它不在 core 的 manifest 里(core 不持有
+ * 选择规则),所以不从 `ev` 读:每条投帧的腿把**自己那只** `InstructionSelectionLeg.segment()` 递进来。必传而不是可选 ——
+ * 漏递的腿当场 tsc 红,而不是静默投出一个「缺席」(缺席在 wire 上是一句话:「这条腿没有关于指令文件的陈述」)。
+ * `undefined` ⇒ 段缺席;`{ selected: [] }` ⇒ 显式空(走了链、没选中)。登记:`wire-projection-faces.ts` 租户行 `minted`。
+ */
 export declare function wiringManifestEventData(ev: {
     manifest?: unknown;
     eventId?: unknown;
     parentToolCallId?: unknown;
-}): Record<string, unknown>;
+}, instructions: InstructionsSegment | undefined): Record<string, unknown>;
 /**
  * `wiring_manifest` 的 **operator 投影**([ref] 件一)—— {@link wiringManifestEventData} 的租户形加上
  * `governance` 段与 core 的真 `configFingerprint`。
@@ -759,7 +767,7 @@ export declare function wiringManifestOperatorEventData(ev: {
     manifest?: unknown;
     eventId?: unknown;
     parentToolCallId?: unknown;
-}): Record<string, unknown>;
+}, instructions: InstructionsSegment | undefined): Record<string, unknown>;
 /**
  * `wiring_manifest` 的**唯一分叉点**(S-528)—— 两条知道调用方身份的 live 消费腿共用它:
  * `/v1/tasks/stream` 的 SSE 帧,与 `POST /v1/tasks`(非流式)200 体里的 `wiringManifest` 起手回执。
@@ -780,7 +788,7 @@ export declare function wiringManifestFaceEventData(ev: {
     manifest?: unknown;
     eventId?: unknown;
     parentToolCallId?: unknown;
-}, operatorFace: boolean): Record<string, unknown>;
+}, operatorFace: boolean, instructions: InstructionsSegment | undefined): Record<string, unknown>;
 /**
  * `human_input`(core 5.14.0 [ref] 新 `TaskEvent` 臂)—— 「谁把什么喂进了这条 run」的生命周期账本
  * 帧(objective / 实时 steer / nextTurn / parked-steer 续跑 / wake 五个载体共用一个投影点)。

package/dist/trace/project.js

@@ -464,7 +464,7 @@ export function toolRosterDeltaEventData(ev) {
     }
     return { delta: ev.delta, ...identityFields(ev) };
 }
-export function wiringManifestEventData(ev) {
+export function wiringManifestEventData(ev, instructions) {
     const str = (v) => (typeof v === "string" && v.length > 0 ? v : undefined);
     const bool = (v) => (typeof v === "boolean" ? v : undefined);
     const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : undefined);
@@ -630,11 +630,12 @@ export function wiringManifestEventData(ev) {
         ...(lsp !== undefined ? { lsp } : {}),
         ...(hands !== undefined ? { hands } : {}),
         ...(writeProtection !== undefined ? { writeProtection } : {}),
+        ...(instructions !== undefined ? { instructions: { selected: [...instructions.selected] } } : {}),
         ...identityFields(ev),
     };
 }
-export function wiringManifestOperatorEventData(ev) {
-    const tenant = wiringManifestEventData(ev);
+export function wiringManifestOperatorEventData(ev, instructions) {
+    const tenant = wiringManifestEventData(ev, instructions);
     const str = (v) => (typeof v === "string" && v.length > 0 ? v : undefined);
     const bool = (v) => (typeof v === "boolean" ? v : undefined);
     const sec = (v) => (typeof v === "object" && v !== null && !Array.isArray(v) ? { ...v } : undefined);
@@ -678,8 +679,8 @@ export function wiringManifestOperatorEventData(ev) {
         ...(str(m.configFingerprint) !== undefined ? { configFingerprint: m.configFingerprint } : {}),
     };
 }
-export function wiringManifestFaceEventData(ev, operatorFace) {
-    return operatorFace ? wiringManifestOperatorEventData(ev) : wiringManifestEventData(ev);
+export function wiringManifestFaceEventData(ev, operatorFace, instructions) {
+    return operatorFace ? wiringManifestOperatorEventData(ev, instructions) : wiringManifestEventData(ev, instructions);
 }
 export function humanInputEventData(ev) {
     const str = (v) => (typeof v === "string" && v.length > 0 ? v : undefined);

package/dist/trace/self-minted-wire.d.ts

@@ -32,6 +32,32 @@ export declare const SELF_MINTED_WIRE: {
             };
         };
     };
+    /**
+     * S-961(7.111.0):`wiring_manifest.instructions.selected[]` 的成员值 = 指令文件链的成员(相对 cwd 的拼写)。属主是 `project-memory.ts`
+     * 的 `INSTRUCTION_FILE_CHAIN`([ref] 序:CLAUDE 族先、AGENTS 族后,首中即选)—— 链加 / 删一员 ⇒ 本行 `satisfies` 编译红,登记跟着动。
+     * 段本身(键)登记在 `wire-projection-faces.ts` 的 `wiring_manifest_tenant.minted`。
+     */
+    readonly wiringInstructionsSelected: {
+        readonly at: "wiring_manifest instructions.selected[](本腿 loader 选中的链成员;段缺席 = 本腿无陈述)";
+        readonly members: {
+            "CLAUDE.md": {
+                attr: string;
+                since: string;
+            };
+            ".claude/CLAUDE.md": {
+                attr: string;
+                since: string;
+            };
+            "AGENTS.md": {
+                attr: string;
+                since: string;
+            };
+            ".claude/AGENTS.md": {
+                attr: string;
+                since: string;
+            };
+        };
+    };
     /**
      * 会话所有者自助抹除面的**已分类拒** → HTTP 状态(S-930 起与 operator 面 `POST /v1/memory/erase` 同一只映射;`since` 记的是**本面**
      * 自哪一版起这样答 —— 7.107.0 及以前本面只认前两只,其余落 500 `internal.error`)。

package/dist/trace/self-minted-wire.js

@@ -12,6 +12,15 @@ export const SELF_MINTED_WIRE = {
             crashed: { attr: "-", since: "7.110.0" },
         },
     },
+    wiringInstructionsSelected: {
+        at: "wiring_manifest instructions.selected[](本腿 loader 选中的链成员;段缺席 = 本腿无陈述)",
+        members: {
+            "CLAUDE.md": { attr: "-", since: "7.111.0" },
+            ".claude/CLAUDE.md": { attr: "-", since: "7.111.0" },
+            "AGENTS.md": { attr: "-", since: "7.111.0" },
+            ".claude/AGENTS.md": { attr: "-", since: "7.111.0" },
+        },
+    },
     sessionMemoryEraseStatus: {
         at: "POST /v1/sessions/:id/memory/erase(已分类拒 errorCode → HTTP 状态)",
         members: {

package/dist/trace/wire-projection-faces.d.ts

@@ -16,7 +16,7 @@
  * `NotificationExcluded` 直接读成本表这一行的 `excluded`,于是「哪几个键有意不上 wire」全仓**只有一个写者**。
  * 旧形是两个:守卫文件一簿、`test/wire-whitelist-exhaustiveness.test.ts` 的 `KnownExcluded` 一簿,那份门注
  * 自己写着「两处必须同时改」—— 而「必须同时改」正是 [ref] 要下线的东西(对账门不算替代,单写者才算)。
- * 本表是纯数据、无行为(唯一的派生是 `wiring_manifest_operator` 行的 `excluded` 取值器 = 租户行减具名常量,S-724),
+ * 本表是纯数据、无行为(唯一的派生是 `wiring_manifest_operator` 行的两只取值器:`excluded` = 租户行减具名常量,S-724;`minted` = 租户行,S-961),
  * 被守卫文件以 `typeof import(...)` 的**类型查询**读取(编译期擦除,零运行期边)。
  *
  * ## 门在哪里
@@ -170,14 +170,14 @@ export declare const WIRE_PROJECTION_FACES: {
         readonly coreType: `WiringManifest & ${string}`;
         readonly excluded: readonly ["governance", "configFingerprint", "autoConsolidation", "readDeny", "peerPresence", "permissionMode"];
         readonly unwrapped: readonly ["manifest"];
-        readonly minted: readonly [];
+        readonly minted: readonly ["instructions"];
     };
     readonly wiring_manifest_operator: {
         readonly projector: "wiringManifestOperatorEventData";
         readonly coreType: `WiringManifest & ${string}`;
         readonly excluded: readonly string[];
         readonly unwrapped: readonly ["manifest"];
-        readonly minted: readonly [];
+        readonly minted: readonly string[];
     };
     readonly engine_notice: {
         readonly projector: "engineNoticeEventData";