@sema-agent/server 7.145.0 → 7.147.0

package/dist/rules-consent.js

@@ -5,7 +5,7 @@ import { createLogger } from "./observability/logger.js";
 import { ABSOLUTE_HOST_PATH_MAX, hasControlOrBidi } from "@sema-agent/settings-schema";
 import { isDirectWritableRuleBehavior } from "./permission-rule-vocab.js";
 import { hasBidiControls } from "./text-bidi.js";
-import { confirmRuleApproval, RULE_BEHAVIORS, parseRuleText, ruleReachesProgramRun, precheckEditedRuleText, prepareCardApproval, prepareCcImport, redeemRuleBatch, redeemRuleTicket, addPersistedRule, removePersistedRule, isValidDurableScope, effectiveOrThrow, readRowBehavior, readRuleOwner, } from "@sema-agent/core";
+import { confirmRuleApproval, RULE_BEHAVIORS, RULE_REFUSAL_CODES, parseRuleText, ruleReachesProgramRun, precheckEditedRuleText, prepareCardApproval, prepareCcImport, redeemRuleBatch, redeemRuleTicket, addPersistedRule, removePersistedRule, isValidDurableScope, effectiveOrThrow, readRowBehavior, readRuleOwner, } from "@sema-agent/core";
 import { buildRulePayloadHash } from "./plugins/permission-rule-store-sql.js";
 export const RULE_IMPORT_TICKET_TTL_MS = 10 * 60_000;
 export const RULE_IMPORT_RETRY_AFTER_SEC = 2;
@@ -21,7 +21,7 @@ const ImportOutcomeSchema = z
         .object({
         key: z.object({ behavior: z.preprocess((v) => readRowBehavior(v) ?? v, z.enum(RULE_BEHAVIORS)), rule: z.string().min(1), scope: z.string().min(1) }).strict(),
         outcome: z.enum(["persisted", "no-op", "refused", "indeterminate"]),
-        reason: z.literal("store_refused").optional(),
+        reason: z.enum(RULE_REFUSAL_CODES).optional(),
         detail: z.string().optional(),
     })
         .strict()),
@@ -114,8 +114,12 @@ function isCommandRuleMatch(match) {
     }
 }
 const unknownReasonLogger = createLogger();
-function confirmRefusalWord(reason) {
+function confirmRefusalWord(confirmed) {
+    const { reason } = confirmed;
     switch (reason) {
+        case "store_read":
+        case "store_write":
+            throw new RuleStoreFaultError({ code: reason, reason: confirmed.detail?.message ?? reason });
         case "edit_disabled":
         case "edit_binding_mismatch":
             return "edit-unsupported";
@@ -137,6 +141,75 @@ function confirmRefusalWord(reason) {
         }
     }
 }
+export function isRuleStoreFault(code) {
+    switch (code) {
+        case "store_read":
+        case "store_write":
+            return true;
+        case "unsupported.layer_root":
+        case "ticket_invalid":
+        case "record_missing":
+        case "wrong_principal":
+        case "record_schema_stale":
+        case "not_confirmed":
+        case "record_malformed":
+        case "not_chosen":
+        case "parse_rejected":
+        case "store_unavailable":
+        case "record_changed":
+        case "withheld":
+        case "session_ended":
+        case "occ":
+        case "dot_removed":
+            return false;
+        default: {
+            const unknown = code;
+            unknownReasonLogger.warn("isRuleStoreFault: unknown RuleRefusalCode from core (dist/core version skew?) — read as not a store failure", { code: String(unknown) });
+            return false;
+        }
+    }
+}
+class RuleStoreFaultError extends Error {
+    code;
+    constructor(refusal) {
+        super(refusal.reason);
+        this.name = "RuleStoreFaultError";
+        this.code = refusal.code;
+    }
+}
+const retriableSkewLogger = createLogger();
+function throwIfRetriable(refusal) {
+    if (!refusal.retriable)
+        return;
+    const { code } = refusal;
+    if (isRuleStoreFault(code))
+        throw new RuleStoreFaultError({ code, reason: refusal.reason });
+    retriableSkewLogger.warn("an engine refusal says retriable but its code is not a store failure (core/dist skew?) — not retried", { code });
+}
+export function confirmRefusalRetries(reason) {
+    switch (reason) {
+        case "conflict":
+        case "store_read":
+        case "store_write":
+            return true;
+        case "record_not_found":
+        case "record_schema_stale":
+        case "record_malformed":
+        case "selection_missing":
+        case "selection_invalid":
+        case "selection_mismatch":
+        case "not_pending":
+        case "edit_disabled":
+        case "edit_binding_mismatch":
+        case "edit_rejected":
+            return false;
+        default: {
+            const unknown = reason;
+            unknownReasonLogger.warn("confirmRefusalRetries: unknown ConfirmRefusalReason from core (dist/core version skew?) — read as not retriable", { reason: String(unknown) });
+            return false;
+        }
+    }
+}
 function refusedMembersOf(members) {
     const refused = [];
     for (const m of members) {
@@ -241,22 +314,50 @@ function buildLocalImportLayers(candidates) {
         return root === "" ? { layer: "userSettings", path: LOCAL_IMPORT_LAYER_PATH, readFile } : { layer: "projectSettings", path: `${LOCAL_IMPORT_LAYER_PATH}:${root}`, root, readFile };
     });
 }
-function buildImportOutcomeMembers(members) {
-    return members.map((m) => {
+function settleImportWalk(members) {
+    const settled = [];
+    for (const m of members) {
         const key = { behavior: m.behavior, rule: m.rule, scope: serializeRuleScope(m.scope) };
         switch (m.status) {
             case "persisted":
-                return { key, outcome: "persisted" };
+                settled.push({ key, outcome: "persisted" });
+                break;
             case "deduped":
-                return { key, outcome: "no-op" };
-            case "refused":
-                return { key, outcome: "indeterminate", reason: "store_refused", detail: m.reason };
+                settled.push({ key, outcome: "no-op" });
+                break;
+            case "refused": {
+                const open = openRefusalOf(m);
+                if (open !== undefined)
+                    return { open: `the outcome of ${m.rule} is not settled (${m.code}, ${open}): ${m.reason}` };
+                settled.push({ key, outcome: "refused", reason: m.code, detail: m.reason });
+                break;
+            }
             default: {
                 const unknown = m;
                 throw new Error(`unknown redeemed-batch member status: ${JSON.stringify(unknown)}`);
             }
         }
-    });
+    }
+    return { settled };
+}
+function openRefusalOf(refusal) {
+    if (refusal.retriable)
+        return "retriable";
+    switch (refusal.committed) {
+        case "no":
+            return undefined;
+        case "unknown":
+            return "committed unknown";
+        default: {
+            const unknown = refusal.committed;
+            throw new Error(`unknown redeemed-batch member committed word: ${JSON.stringify(unknown)}`);
+        }
+    }
+}
+function importRecordRefusal(refusal) {
+    if (!refusal.retriable)
+        throw new Error(`the engine refused to prepare this import and says repeating will not help (${refusal.code}): ${refusal.reason}`);
+    return { ok: false, reason: "record-store-refused", committed: refusal.committed, detail: refusal.reason };
 }
 export function createRuleConsentLane(stores, opts) {
     const deps = { provider: stores.provider, approvals: stores.approvals, cardEdits: true };
@@ -289,6 +390,10 @@ export function createRuleConsentLane(stores, opts) {
             if (prepared === undefined) {
                 return { ok: false, reason: "no-candidates", detail: "the rule lane cannot speak for this command (compound / redirection / unsupported tool)" };
             }
+            if ("status" in prepared) {
+                throwIfRetriable(prepared);
+                return { ok: false, reason: "redeem-refused", detail: prepared.reason };
+            }
             const redemption = input.redemption;
             if (redemption.kind === "batch") {
                 const wanted = new Set(redemption.offer.rules.map((r) => r.rule));
@@ -298,12 +403,17 @@ export function createRuleConsentLane(stores, opts) {
                 }
                 const confirmed = await confirmRuleApproval({ approvalId: prepared.approvalId, principal: input.principal, selectedOffer: offerIndex, deps });
                 if (!confirmed.ok)
-                    return { ok: false, reason: "confirm-refused", detail: confirmed.reason };
+                    return { ok: false, reason: confirmRefusalWord(confirmed), detail: confirmed.detail?.message ?? confirmed.reason };
                 const result = await redeemRuleBatch({ approvalId: prepared.approvalId, principal: input.principal, deps });
-                if ("status" in result)
+                if ("status" in result) {
+                    throwIfRetriable(result);
                     return { ok: false, reason: "redeem-refused", detail: result.reason };
+                }
                 const refused = refusedMembersOf(result.members);
                 if (refused.length > 0) {
+                    const first = refused[0];
+                    if (first !== undefined && refused.length === result.members.length && refused.every((m) => m.retriable))
+                        throwIfRetriable(first);
                     return { ok: false, reason: "redeem-refused", detail: `partial batch: ${refused.length} member(s) refused (${refused.map((x) => x.reason).join("; ")})` };
                 }
                 return { ok: true, ...anchorBatchMembers(result.members, redemption.offer), rev: result.rev };
@@ -318,7 +428,7 @@ export function createRuleConsentLane(stores, opts) {
                 }
                 const confirmed = await confirmRuleApproval({ approvalId: prepared.approvalId, principal: input.principal, selectedOffer: offerIndex, deps });
                 if (!confirmed.ok)
-                    return { ok: false, reason: "confirm-refused", detail: confirmed.reason };
+                    return { ok: false, reason: confirmRefusalWord(confirmed), detail: confirmed.detail?.message ?? confirmed.reason };
                 ticket = offered;
             }
             else {
@@ -336,7 +446,7 @@ export function createRuleConsentLane(stores, opts) {
                     deps,
                 });
                 if (!confirmed.ok)
-                    return { ok: false, reason: confirmRefusalWord(confirmed.reason), detail: confirmed.detail?.message ?? confirmed.reason };
+                    return { ok: false, reason: confirmRefusalWord(confirmed), detail: confirmed.detail?.message ?? confirmed.reason };
                 const minted = confirmed.mintedCandidate;
                 if (minted === undefined) {
                     return { ok: false, reason: "confirm-refused", detail: "the edited confirmation landed without a minted candidate — nothing to redeem" };
@@ -351,8 +461,10 @@ export function createRuleConsentLane(stores, opts) {
                 ticket = minted.ticket;
             }
             const redeemed = await redeemRuleTicket({ ticket, principal: input.principal, deps });
-            if (redeemed.status !== "redeemed")
+            if (redeemed.status !== "redeemed") {
+                throwIfRetriable(redeemed);
                 return { ok: false, reason: "redeem-refused", detail: redeemed.reason };
+            }
             return { ok: true, kind: "single", rule: redeemed.rule, rev: redeemed.rev, alreadyRedeemed: redeemed.alreadyRedeemed };
         },
         async prepareImport(principal, layers) {
@@ -360,7 +472,10 @@ export function createRuleConsentLane(stores, opts) {
                 const readFile = async () => l.content;
                 return l.layer === "userSettings" ? { layer: l.layer, path: l.path, readFile } : { layer: l.layer, path: l.path, root: l.root, readFile };
             });
-            const { preview, approvalId } = await prepareCcImport({ layers: ccLayers, principal, deps });
+            const prepared = await prepareCcImport({ layers: ccLayers, principal, deps });
+            if ("status" in prepared)
+                return importRecordRefusal(prepared);
+            const { preview, approvalId } = prepared;
             if (approvalId === undefined) {
                 return { ok: true, preview };
             }
@@ -440,8 +555,8 @@ export function createRuleConsentLane(stores, opts) {
                 if (record.state === "pending") {
                     const confirmed = await confirmRuleApproval({ approvalId: consumed.approvalId, principal, deps });
                     if (!confirmed.ok) {
-                        if (confirmed.reason === "conflict")
-                            return await indeterminate(confirmed.reason);
+                        if (confirmRefusalRetries(confirmed.reason))
+                            return await indeterminate(confirmed.detail?.message ?? confirmed.reason);
                         return { ok: false, reason: "record-unusable", detail: confirmed.reason };
                     }
                 }
@@ -449,7 +564,10 @@ export function createRuleConsentLane(stores, opts) {
                 if ("status" in result) {
                     return await indeterminate(result.reason);
                 }
-                return { ok: true, outcome: { members: buildImportOutcomeMembers(result.members), rev: result.rev } };
+                const walk = settleImportWalk(result.members);
+                if ("open" in walk)
+                    return await indeterminate(walk.open);
+                return { ok: true, outcome: { members: walk.settled, rev: result.rev } };
             }
             catch (err) {
                 return await indeterminate(err instanceof Error ? err.message : String(err));
@@ -507,7 +625,10 @@ export function createRuleConsentLane(stores, opts) {
             }
             if (allows.length === 0)
                 return { ok: true, preview: { members } };
-            const { preview, approvalId } = await prepareCcImport({ layers: buildLocalImportLayers(allows), principal, deps });
+            const prepared = await prepareCcImport({ layers: buildLocalImportLayers(allows), principal, deps });
+            if ("status" in prepared)
+                return importRecordRefusal(prepared);
+            const { preview, approvalId } = prepared;
             const engineKeys = new Set(preview.candidates.map((c) => `${c.behavior}${LOCAL_IMPORT_KEY_SEP}${serializeRuleScope(c.scope)}${LOCAL_IMPORT_KEY_SEP}${c.rule}`));
             for (let i = 0; i < members.length; i++) {
                 const m = members[i];
@@ -596,8 +717,8 @@ export function createRuleConsentLane(stores, opts) {
                     if (record.state === "pending") {
                         const confirmed = await confirmRuleApproval({ approvalId, principal, deps });
                         if (!confirmed.ok) {
-                            if (confirmed.reason === "conflict")
-                                return await transient(confirmed.reason);
+                            if (confirmRefusalRetries(confirmed.reason))
+                                return await transient(confirmed.detail?.message ?? confirmed.reason);
                             return await verdict("record-unusable", confirmed.reason);
                         }
                     }
@@ -605,7 +726,10 @@ export function createRuleConsentLane(stores, opts) {
                     if ("status" in result) {
                         return await transient(result.reason);
                     }
-                    members = buildImportOutcomeMembers(result.members);
+                    const walk = settleImportWalk(result.members);
+                    if ("open" in walk)
+                        return await transient(walk.open);
+                    members = walk.settled;
                     rev = result.rev;
                 }
                 catch (err) {

package/dist/run-cancel-context.d.ts

@@ -136,6 +136,9 @@ export declare function buildCancelledLedgerRow(c: PersistedTaskResult): {
  * `signal.reason`:那会改掉引擎与 provider 层收到的拒绝值,是在下游改上游接缝的输入(立宪禁区)。
  */
 export interface RunAbort {
+    /** 这条腿的**属主**(run 行的 `owner` 列;无主体 = `null`)—— 在飞集(`inflightRuns`)里「谁占着几条」的唯一读处:并发帽按主体数在飞腿时读它
+     *  (`http/run-concurrency-cap.ts`),不另起一张按 taskId 键控的旁表。句柄与腿同寿,换腿就是换句柄。 */
+    readonly owner: string | null;
     /** 交给引擎的那只信号(`spec.signal` / 审批 / 提问 ALS 的 `abortSignal` / 子代 stoppedBy 归因都用它)。 */
     readonly signal: AbortSignal;
     /** 以 `cause` 中止本腿。已中止 ⇒ no-op(成因不改写)。 */
@@ -143,6 +146,6 @@ export interface RunAbort {
     /** 让本腿停下来的那次中止的成因;未中止 ⇒ `undefined`。 */
     cause(): AbortCause | undefined;
 }
-export declare function createRunAbort(): RunAbort;
+export declare function createRunAbort(owner: string | null): RunAbort;
 export {};
 //# sourceMappingURL=run-cancel-context.d.ts.map

package/dist/run-cancel-context.js

@@ -51,10 +51,11 @@ export function buildCancelledLedgerRow(c) {
         ...(c.abortCause !== undefined ? { abortCause: c.abortCause } : {}),
     };
 }
-export function createRunAbort() {
+export function createRunAbort(owner) {
     const ctrl = new AbortController();
     let landed;
     return {
+        owner,
         signal: ctrl.signal,
         abort(cause) {
             if (ctrl.signal.aborted)

package/dist/run-local.js

@@ -23,7 +23,7 @@ import { buildUnpricedCeilingNotice, isRosterGateArmed, loadConfig, logConfigDia
 import { buildStoreOpenRefusalTail } from "./plugins/store-open-refusal.js";
 import { acquireLocalBackendWithWait } from "./plugins/store-lock-wait.js";
 import { configLocalRoot, createConfigProvider } from "./config-provider.js";
-import { CONFIG_DOMAIN_INVALID_NOTE, buildCandidateRejectedFields, judgeConfigCandidate } from "./web-admin-client/candidate-gate.js";
+import { CONFIG_DOMAIN_INVALID_NOTE, buildCandidateRejectedFields, buildCandidateRejectionNotes, judgeConfigCandidate } from "./web-admin-client/candidate-gate.js";
 import { buildUnreadConfigFileFields, buildUnreadConfigKeyFields } from "./web-admin-client/read-warnings.js";
 import { composeExecutionLane, settleHostLaneShell, warnReadDenyFloorUnkept } from "./boot/execution-lane.js";
 import { judgeConsolidationValve } from "./boot/memory-consolidation.js";
@@ -316,6 +316,7 @@ function buildUnfinishedStopFooter(stop, sessionId) {
         }
     }
 }
+const RUN_LOCAL_LANE_ENTRY = { name: "run-local", runs: ["host", "none"], declares: "host" };
 export const RUN_LOCAL_CONFIG_SOURCE_REFUSAL = "CONFIG_PROVIDER=remote: run-local reads its configuration from the local config directory only — it does not pull a web-admin center " +
     "(center credential renewal, sealed model keys and the roster gate are assembled by the HTTP service). Unset CONFIG_PROVIDER or set " +
     "CONFIG_PROVIDER=local for this command, or run the HTTP service to use the center.";
@@ -345,30 +346,31 @@ export async function runLocal(argv, deps = {}) {
     if (args.root)
         process.env.CONFIG_LOCAL_DIR = args.root;
     declareServerWithheldEnv();
-    const config = loadConfig();
-    bindOwnCredentialsConfig(config);
-    const root = configLocalRoot(config);
-    const logger = deps.logger ?? createLogger(config.logLevel);
+    const loaded = loadConfig();
+    bindOwnCredentialsConfig(loaded);
+    const root = configLocalRoot(loaded);
+    const logger = deps.logger ?? createLogger(loaded.logLevel);
     const metrics = createMetrics();
     const memoryEngineIncident = createMemoryEngineIncidentSink({ logger, metrics });
     installSecretEnvScrubRecorder({ logger, metrics });
     installDefaultEngineNoticeSeat(logger, metrics);
     logConfigDiagnostics(logger);
-    provisionSemaConfigDir(config, logger);
+    provisionSemaConfigDir(loaded, logger);
     installOutboundDispatcher(logger);
-    const providerInput = { provider: "local", localDir: root, localOwnerUid: config.configLocalOwnerUid };
+    const providerInput = { provider: "local", localDir: root, localOwnerUid: loaded.configLocalOwnerUid };
     try {
-        await assertLocalConfigDirTrusted({ root, declaredOwnerUid: config.configLocalOwnerUid });
+        await assertLocalConfigDirTrusted({ root, declaredOwnerUid: loaded.configLocalOwnerUid });
     }
     catch (err) {
         printErr(err instanceof Error ? err.message : String(err));
         return 2;
     }
-    const envModelsMigration = { root, env: process.env, envTableIsPlaceholder: isRosterGateArmed(config.webAdmin) };
+    const envModelsMigration = { root, env: process.env, envTableIsPlaceholder: isRosterGateArmed(loaded.webAdmin) };
     logEnvModelsMigration(logger, envModelsMigration, await runEnvModelsMigration(envModelsMigration));
     logConfigDirMigration(logger, await migrateLocalConfigDirectory(root));
+    let config;
     try {
-        await composeExecutionLane(config, { configSource: "local", localRoot: root, logger, drivesFromFile: ["host"] });
+        config = await composeExecutionLane(loaded, { configSource: "local", localRoot: root, logger, entry: RUN_LOCAL_LANE_ENTRY });
     }
     catch (err) {
         printErr(err instanceof Error ? err.message : String(err));
@@ -379,12 +381,14 @@ export async function runLocal(argv, deps = {}) {
     const rosterLease = peerDesk.lease("roster");
     let effective;
     let candidatePrompts;
+    let candidateRejectionNotes;
     let applying = false;
     try {
         const r = await configProvider.fetchEffective(undefined);
         if (r) {
             const verdict = judgeConfigCandidate(r);
             if (verdict.verdict === "rejected") {
+                candidateRejectionNotes = buildCandidateRejectionNotes({ errors: verdict.errors, ...(configProvider.kind === "local" ? { dir: root } : {}) });
                 for (const de of r.domainErrors ?? [])
                     logger.warn("config_domain_invalid", { domain: de.domain, error: de.error, note: CONFIG_DOMAIN_INVALID_NOTE });
                 logger.warn("config_candidate_rejected", buildCandidateRejectedFields(r, verdict, "run-local", { lkgVersion: "(env)", ...(configProvider.kind === "local" ? { dir: root } : {}) }));
@@ -419,7 +423,7 @@ export async function runLocal(argv, deps = {}) {
         else
             logger.warn("config_source_unreachable_using_env", { source: configProvider.kind, err: String(err) });
     }
-    const noDefaultModel = defaultModelRefusal(config, servedModelTableLeg(config));
+    const noDefaultModel = defaultModelRefusal({ models: config.models, modelRefusals: config.modelRefusals, candidateRejectionNotes }, servedModelTableLeg(config));
     if (noDefaultModel !== undefined)
         throw new Error(noDefaultModel);
     const routeVerdict = judgeServedModelRoute(config, { envTableIsPlaceholder: false });
@@ -474,7 +478,7 @@ export async function runLocal(argv, deps = {}) {
     }
     const sessionStore = fileBackend.sessionStore;
     const keyResolver = createKeyResolver(config.modelApiKeyEnv, process.env, config.modelApiKeys);
-    const hostRx = config.remoteExec?.provider === "host" ? config.remoteExec : undefined;
+    const hostRx = config.remoteExec.provider === "host" ? config.remoteExec : undefined;
     const workspaceDir = args.workspace ?? hostRx?.workspaceBase ?? process.cwd();
     await settleHostLaneShell(config, logger);
     warnReadDenyFloorUnkept(config, logger);
@@ -720,7 +724,7 @@ export async function runLocal(argv, deps = {}) {
         ...(a2a ? { a2a } : {}),
         ...(Object.keys(limits).length > 0 ? { limits } : {}),
     }, config, workspaceDir), onAsk);
-    logger.info("run_local_start", { scenario: scenarioName, model: spec.model, sessionId, exec: executionLaneOf(config.remoteExec?.provider) });
+    logger.info("run_local_start", { scenario: scenarioName, model: spec.model, sessionId, exec: config.remoteExec.provider });
     const settleSessionBackground = async () => {
         const reaped = defaultTaskRegistry.reapSessionBackground(sessionId, scope);
         if (reaped === 0)

package/dist/runs.d.ts

@@ -151,33 +151,40 @@ export declare function releaseKeyIfZeroWorkRefusal(runStore: {
  * observable instead of a silent feature outage.
  */
 /**
- * 「这一次用户消息提交是不是一句**提问**」的唯一读法 —— 三处用户回退锚(后台腿与续跑腿的 {@link TurnAnchorCapture}、`/v1/tasks/stream`
- * 腿的 `userMsgEntryId`)同调这一只。
+ * 「这一次用户消息提交是不是这个 run 的**开场提示**」的唯一读法 —— 三处用户回退锚(后台腿与续跑腿的 {@link TurnAnchorCapture}、`/v1/tasks/stream`
+ * 腿的 `userMsgEntryId`)同调这一只;调用点零各自判、零按正文判,且都是「最后一次交出的赢」。
  *
- * 目标声明了附件时,引擎把每只附件铸成**一条自己的用户消息**,紧跟在目标后面提交(core `human_input.attachments` 顶注:
- * 「each attachment is delivered as its own message after the objective; its `message_committed` is the delivery」)。
- * 所以一次带 N 只附件的提交会出 1 + N 次 `message_committed{role:"user"}`,而「回到这条提问」的锚要的是**人的那条**
- * (core 的 `resumeAt` 认它:「a `resumeAt` that keeps the message keeps its group」;以附件帧作 `resumeAt` 引擎拒 `resume_at.not_a_message`),
- * 不是排在最后的附件帧。目标**之前**还可能有引擎排队的注入消息同批提交(亲读 core `engine/harness/agent-harness.js` 的 `takePrompts`:
- * 排队消息 ⇒ 目标 ⇒ 附件帧;真案 = 工作区是 git 仓且带图时,git 状态帧单独排在目标前面),所以「窗口里第一次用户提交」不是判据。
+ * **回退锚 = 该轮开场提示,一个 run 一个(开场窗 + 闩)**:run 一开始就开着一个**开场窗**,收集第一次模型输出之前的 user 提交;窗关上之后(闩上),同 run 的 user-role 提交 ——
+ * 用户打断时引擎收尾追加的「[Request interrupted by user]」、第一次模型调用前后排进来的 steer 正文、答完之后再来的 steer —— 一律不交。这是 CC「rewind to the message that started this turn」的
+ * 同义,与 core `resumeAt` 的 `before` 语义(叶 = 目标的 parent)配对:锚在开场提示上,切到它的 parent = 这一轮整个撤回;锚若漂到打断标记行上,
+ * parent 就是被撤回的那句提示本身,模型仍见它。同根:core 的文件历史边界按「本 run 第一条 user 提交」的 entry 键入(`rewindFilesTo` / `POST /v1/sessions/:id/rewind-files`
+ * 凭锚找边界),锚漂到没有自己边界的打断标记行上就解不到。打断标记行永远不是锚。
+ * 「一个 run」= 锚的键(`taskId`)的边界:读法实例每个 run 新建一只;续既有 run 的续跑腿不写用户锚(见 `resume-legs.ts`)。
  *
- * **为什么是「窗口 + 严格吻合」而不是读标记**:`message_committed` 上只有 `entryId / role / toolCallId?`,附件帧与用户真提交在事件上**不可辨认**;
- * 落盘的行上有标记(`attachment` 键;引擎收尾的中断标记带 `provenance: "engine-note"`),但事件到手的那一刻本仓读不到那一行
- * (会话店面没有按条目读的口,只有整日志导出),所以只能数。数的前提是「目标之后紧接恰好 N 只帧、其后才是别的」—— 前提成立才落锚,
- * **不成立就不猜**:猜错的锚会落在附件帧上(引擎拒)或引擎的中断标记上(回到的不是用户那句)。
+ * **窗里怎么认**。`message_committed` 上只有 `entryId / role / toolCallId?`:引擎排队在目标之前同批提交的消息(带图且工作区是 git 仓时单独排的 git 状态帧;会话空闲期间到的后台任务通知)、
+ * 目标、目标声明的附件帧、引擎收尾的中断标记,在事件上**不可辨认**(落盘的行上有标记 —— `attachment` 键、`provenance: "engine-note"` —— 但事件到手那一刻本仓读不到那一行:
+ * 会话店面没有按条目读的口,只有整日志导出),所以只能数。引擎的提交序(亲读 core `engine/harness/agent-harness.js` 的 `takePrompts`):排队消息 ⇒ 目标 ⇒ 附件帧;
+ * 中断标记只在打断收尾时追加(此时第一次模型输出没有出来,窗是被 `turn_end` 切断,不是被输出关上)。
+ *  · **临时锚**:不带附件的提交,窗里**第一条** user 提交到手那一刻就交出 —— 打断 / 取消 / 断连常发生在第一次模型输出之前,那时窗还没关,锚必须已经在;
+ *    它也是 core 文件历史边界的键(本 run 第一条 user 提交)。
+ *  · **校正**:窗被**非用户提交**(第一次助手消息 / 工具结果)关上 ⇒ 窗内共 k 条 user 提交、声明了 N 只附件帧:k ≥ N+1 时开场提示 = 倒数第 N+1 条(严格吻合)。
+ *    不带附件而 k > 1(目标之前有引擎排队的消息)⇒ 交出这一条,**盖过**临时锚(调用方「最后一次赢」,与修前同读:修前的读法就是『开场批里最后一条 user 提交』);k = 1 ⇒ 临时锚已是它,不再交。
+ *    带附件的提交没有临时锚(此刻还不知道哪几条是帧),只在关窗这一刻交一次;k < N+1(帧数不符)⇒ 不猜。
+ *  · 窗被 `turn_end` 先切断 ⇒ 第一次模型调用没出任何输出就收了(halt / interrupt / cancel / 空失败):窗里可能夹着引擎收尾的中断标记,数 N 会落在帧或标记上 ⇒ **不校正**,
+ *    临时锚(不带附件)原样留着,带附件的提交不猜、不落锚。切断即闩上。
+ *  · 带附件的提交,窗内又应用了一条别的输入(`human_input{applied}`,如第一次模型调用前排进来的 steer;事件先于它的正文提交到手)⇒ 窗里多了一条别人的消息,数 N 会落在帧后面的 steer 上 ⇒ 不猜。
+ *    不带附件的提交不看输入条数:多条 applied 输入可以合成一条提交(续跑把停驻的 steer 与 wake 文本并成一条续跑消息),按修前同读校正到窗内最后一条。排队未应用(`delivery: "queued"`)的输入不动窗。窗还开着时继续攒,直到被关上。
+ *  · 「不猜」= 这个 run 不落(带附件)或不校正(不带附件),且窗关上之后闩上 —— 其后的 user 提交(steer 正文、打断标记)不是开场提示,不顶上来;拿这次 run 的 taskId 去 `resumeAt`
+ *    得 404 `resume_at.unknown_event`(文案点名带附件这一类成因)。
+ * 窗关上之前一个 user 提交都没有就关了(续跑腿里先到的是工具结果 / 助手消息)⇒ 窗照开着,不闩:那一条之后第一条 user 提交才是这个 run 里的第一条。
  *
- * 读法:
- *  · `human_input{delivery:"applied"}` 带 N 只附件 ⇒ 开窗;窗内的用户提交只攒、不落锚(此刻还不知道它们是不是『目标 + N 只帧』)。
- *  · 窗被**非用户提交**(第一次助手消息 / 工具结果)关上 ⇒ 窗内共 k 次用户提交,k ≥ N+1 时提问 = 倒数第 N+1 次(严格吻合);k < N+1(帧数不符)⇒ 不猜。
- *  · 窗被 `turn_end` 先切断 ⇒ 第一次模型调用没出任何提交就收了(halt / interrupt / 空失败):窗里可能夹着引擎收尾的中断标记,数 N 会落在帧或标记上 ⇒ 不猜。
- *  · 窗内又应用了一条别的输入(`human_input{applied}`,如第一次模型调用前排进来的 steer;事件先于它的正文提交到手)⇒ 窗里多了一条别人的消息,数 N 会落在帧上 ⇒ 窗作废、不猜,
- *    之后的用户提交(含那条 steer 正文)是窗口之外的提交,最后一次赢。排队未应用(`delivery: "queued"`)的输入不动窗。
- *  · 「不猜」= 返回 `undefined`、这次提交不落锚;拿这次 run 的 taskId 去 `resumeAt` 得 404 `resume_at.unknown_event`(文案点名这一类成因)。
- *    窗口之外的用户提交(如 interrupt 带话的 steer 正文,在 `turn_end` 之后提交)照修前读法(是提问,最后一次赢)。
- * 返回这次提交之后的提问 `entryId`(调用方照旧「最后一次赢」地落锚),不是提问相关的提交返回 `undefined`。
+ * 已知边界(引擎在 `message_committed` 上带来源标 / 输入标之日见下):
+ *  · 被 `turn_end` 切断(第一次模型输出之前打断 / 取消)、不带附件、且由引擎排队的消息领头的 run —— 窗来不及校正,锚落在领头的那一条上(修前:取消 = 目标,halt / interrupt = 打断标记)。
+ *    它与 core 文件历史边界的键是同一条消息,`resumeAtMode:"before"` 的叶仍是整轮之前;含目标的 `resumeAt` 只留下领头那条。
+ *  · 不带附件、第一次模型输出之前就应用了一条 steer:校正到窗内最后一条 = steer 正文(与修前同读)。
  *
- * 退役条件:引擎在落盘的帧上(`message_committed`)带上附件标记之日,本读法整体换成「按标记判一次」(零计数、无窗口、无拒臂),
- * 窗口 / 严格吻合 / 不猜三臂与 `resume_at.unknown_event` 文案里对应的那一句一并删除。
+ * 退役条件:引擎在落盘的帧上(`message_committed`)带上来源标(附件标记 / 引擎消息标)之日,本读法整体换成「第一条非引擎消息」(零计数、无窗口、无校正、无拒臂),
+ * 窗口 / 严格吻合 / 不猜三臂与 `resume_at.unknown_event` 文案里对应的那一句一并删除,领头排队消息的边界随之消失。
  */
 export declare function createPromptCommitReader(): (ev: {
     readonly type: string;
@@ -206,12 +213,17 @@ export declare class TurnAnchorCapture {
      *  assistant). This is the CC rewind target ("rewind to the prompt" = the code-restore parity path — a code
      *  change happens in a tool turn WITHIN a prompt's run, so rewinding to the prompt + rewindFiles undoes it).
      *  Keyed by the run's taskId (the handle the shell already holds from the POST response — no eventId→entryId
-     *  side map / no leaf-read inference needed). The assistant-turn capture above stays as an additive bonus. */
+     *  side map / no leaf-read inference needed). The assistant-turn capture above stays as an additive bonus.
+     *  The anchor is the run's OPENING prompt (the reader's opening window: provisional on the first user commit, corrected
+     *  when the first model output closes the window, latched after); a later
+     *  user-role commit in the same run — the interruption marker, a steer — never moves it. The capture instance is per
+     *  run: a leg that CONTINUES an existing run (same taskId) wires no `captureUser` (its opening prompt was anchored
+     *  by the first leg). */
     private readonly captureUser?;
     /** The turn's FIRST text_delta eventId = the message's stable resume handle (also stamped on the durable text event). */
     firstTextEventId: string | undefined;
     private turnHadTool;
-    /** 用户提交是不是提问的唯一读法({@link createPromptCommitReader};附件帧不是提问)。 */
+    /** 用户提交是不是开场提示的唯一读法({@link createPromptCommitReader};开场窗 + 闩 —— 开场提示之后打断标记 / steer 不改锚;附件帧不是提问)。 */
     private readonly promptCommit;
     constructor(capture: ((eventId: string) => Promise<void>) | undefined, 
     /** 这只捕获器在哪条腿上(写失败的 fail-open 探针行带它)。 */
@@ -222,16 +234,22 @@ export declare class TurnAnchorCapture {
      *  assistant). This is the CC rewind target ("rewind to the prompt" = the code-restore parity path — a code
      *  change happens in a tool turn WITHIN a prompt's run, so rewinding to the prompt + rewindFiles undoes it).
      *  Keyed by the run's taskId (the handle the shell already holds from the POST response — no eventId→entryId
-     *  side map / no leaf-read inference needed). The assistant-turn capture above stays as an additive bonus. */
+     *  side map / no leaf-read inference needed). The assistant-turn capture above stays as an additive bonus.
+     *  The anchor is the run's OPENING prompt (the reader's opening window: provisional on the first user commit, corrected
+     *  when the first model output closes the window, latched after); a later
+     *  user-role commit in the same run — the interruption marker, a steer — never moves it. The capture instance is per
+     *  run: a leg that CONTINUES an existing run (same taskId) wires no `captureUser` (its opening prompt was anchored
+     *  by the first leg). */
     captureUser?: ((entryId: string) => Promise<void>) | undefined);
-    /** A `human_input` arrived — the objective's declared attachments open the frame window of {@link createPromptCommitReader}. */
+    /** A `human_input` arrived — the objective's declared attachments open the frame window of {@link createPromptCommitReader} (another applied input inside the window voids it). */
     onHumanInput(ev: {
         readonly type: string;
     }): void;
     /** A `message_committed` arrived — capture a USER-message rewind anchor (CC parity). Best-effort (a failure only
-     *  makes that one prompt non-rewindable). Only a user commit that is a PROMPT (not an attachment frame trailing the
-     *  objective — {@link createPromptCommitReader}; an attachment window is decided when a non-user commit closes it, so
-     *  the anchor of an attachment-carrying prompt lands on THAT call); assistant/toolResult committed entries are handled by
+     *  makes that one prompt non-rewindable). Only the run's OPENING prompt anchors (the opening window's user commit — not an
+     *  attachment frame trailing the objective, not the interruption marker / a steer that follows it —
+     *  {@link createPromptCommitReader}; an attachment window is decided when a non-user commit closes it, so the anchor of an
+     *  attachment-carrying prompt lands on THAT call); assistant/toolResult committed entries are handled by
      *  the turn-text path (assistant) or deliberately not anchored (toolResult — `resumeAt` rejects them). */
     onMessageCommitted(role: string | undefined, entryId: string | undefined): Promise<void>;
     /** A text_delta arrived — latch the first DEFINED eventId as the message handle (eventId is optional on the stream). */