@sema-agent/core 7.49.4 → 7.50.0

package/dist/core/gate-lanes.js

@@ -26,6 +26,8 @@ const QUESTION_TOOL_NAMES = new Set([ASK_USER_QUESTION_TOOL_NAME]);
 function parkWith(suspendAsk, parkArgs, carry) {
     return suspendAsk(...parkArgs, carry);
 }
+const ruleCallUnreadableOf = (lane) => lane?.unreadable === true && lane.reason !== undefined;
+const ruleStoreUnreadableOf = (lane) => lane?.unreadable === true && lane.reason === undefined;
 export async function runGateLanes(pass) {
     const { input, toolName, toolCallId, callSignal, ledger, notifier, screening, adjudicate, resolveAsk, suspendAsk } = pass;
     const boundedAwaitDeadlineMs = createGateDeadline(input, notifier);
@@ -42,11 +44,12 @@ export async function runGateLanes(pass) {
         targetUnresolved: pass.targetUnresolved === true,
     });
     const readFaceNow = input.readFace?.();
-    const askOriginFacts = (org, ruleCallUnreadable) => ({
+    const askOriginFacts = (org, lane) => ({
         contentQuestion: heldBy("lanes.contentQuestionClass", QUESTION_TOOL_NAMES, pass.req),
         markedUnresolvable: markedUnresolvable(),
         org,
-        ...(ruleCallUnreadable ? { ruleCallUnreadable } : {}),
+        ...(ruleCallUnreadableOf(lane) ? { ruleCallUnreadable: true } : {}),
+        ...(ruleStoreUnreadableOf(lane) ? { ruleStoreUnreadable: true } : {}),
         tightened: pass.tightenedBy,
         mandateMarks: mandateMarksNow(),
         ...(input.toolMarkSources !== undefined ? { toolMarkSources: input.toolMarkSources } : {}),
@@ -118,13 +121,12 @@ export async function runGateLanes(pass) {
     };
     const orgAnswer = await applyOrgLayer(pass.decision, pass.policyRewrite !== undefined ? pass.policyRewrite : pass.currentInput);
     pass.decision = orgAnswer.decision;
-    const ruleCallUnreadableOf = (lane) => lane?.unreadable === true && lane.reason !== undefined;
     const readPersistedRules = (req) => readPersistedRuleLane(input.persistedRules, req, input.abortSignal);
     const reread = pass.policyRewrite !== undefined ? withArgsReading(pass.req, pass.policyRewrite, pass.callSignal ?? input.abortSignal) : undefined;
     const laneReq = reread !== undefined ? await reread : { ...pass.req, ...(pass.policyRewrite !== undefined ? { args: pass.policyRewrite } : {}) };
     const laneAnswer = input.persistedRules !== undefined && wireOf("lanes.persistedLaneSkip", pass.req) !== ASK_USER_QUESTION_TOOL_NAME ? await readPersistedRules(laneReq) : undefined;
     {
-        const tightened = applyPersistedTightening(pass.decision, laneAnswer);
+        const tightened = applyPersistedTightening(pass.decision, laneAnswer, laneReq);
         pass.decision = tightened.decision;
         if (tightened.tightened === "deny")
             pass.deniedBy = "persisted_rule";
@@ -146,7 +148,7 @@ export async function runGateLanes(pass) {
                 pass.req.targetReading = laneReq.targetReading;
         }
         const ruleMayClear = () => ruleClearanceOf(pass.decision.action === "ask" ? pass.decision : undefined, mandateMarksNow()).ruleMayClear;
-        const classMayClear = () => pass.decision.action === "ask" && classifyAsk(pass.decision, askOriginFacts(orgAnswer.org, ruleCallUnreadableOf(laneAnswer))).row.ruleMayClear;
+        const classMayClear = () => pass.decision.action === "ask" && classifyAsk(pass.decision, askOriginFacts(orgAnswer.org, laneAnswer)).row.ruleMayClear;
         let personalEvidence = { dotsAbsent: input.persistedRules === undefined ? "not_wired" : "not_adjudicated" };
         if (laneAnswer?.unreadable === true)
             personalEvidence = { dotsAbsent: "unavailable" };
@@ -234,7 +236,7 @@ export async function runGateLanes(pass) {
             const { allowRuleShadowed: _claimed, ...standing } = pass.decision;
             pass.decision = shadows.length > 0 ? { ...standing, allowRuleShadowed: shadows } : standing;
         }
-        const originFacts = askOriginFacts(orgAnswer.org, ruleCallUnreadableOf(laneAnswer));
+        const originFacts = askOriginFacts(orgAnswer.org, laneAnswer);
         let noRulingMinted = false;
         const fallbackAskOf = (standingAsk, fallback, latestBlockedAction) => {
             const { classifierNoRuling: _why, ...standing } = standingAsk;
@@ -582,13 +584,12 @@ export async function runGateLanes(pass) {
                         editDenied = recheck;
                         break;
                     }
-                    let editRuleCallUnreadable = false;
+                    let editLane;
                     const editReread = withArgsReading(pass.req, editArgs, callSignal ?? input.abortSignal);
                     const editLaneReq = editReread !== undefined ? await editReread : { toolName, args: editArgs, toolCallId, ...(pass.req.face !== undefined ? { face: pass.req.face } : {}) };
                     if (input.persistedRules !== undefined && wireOf("lanes.persistedEditSkip", pass.req) !== ASK_USER_QUESTION_TOOL_NAME) {
-                        const editLane = await readPersistedRules(editLaneReq);
-                        editRuleCallUnreadable = ruleCallUnreadableOf(editLane);
-                        const editTightened = applyPersistedTightening(recheck, editLane);
+                        editLane = await readPersistedRules(editLaneReq);
+                        const editTightened = applyPersistedTightening(recheck, editLane, editLaneReq);
                         recheck = editTightened.decision;
                         if (editTightened.tightened === "deny")
                             pass.deniedBy = "persisted_rule";
@@ -619,7 +620,7 @@ export async function runGateLanes(pass) {
                     }
                     const editAskSnapshot = { ...recheck, ruleEvidence: mintRuleEvidence({ dotsAbsent: "not_adjudicated" }) };
                     markedThisRound = undefined;
-                    const editFacts = askOriginFacts(editOrg.org, editRuleCallUnreadable);
+                    const editFacts = askOriginFacts(editOrg.org, editLane);
                     const editAskDecision = stampAskOrigin(editAskSnapshot, editFacts, classifyStanding(editAskSnapshot, editFacts));
                     if (input.permissionMode !== undefined && pass.askClassification !== undefined) {
                         const editVerdict = arbitrateByMode(input.permissionMode(), pass.askClassification, { ...(editAskDecision.origin !== undefined ? { origin: editAskDecision.origin } : {}), ...(editAskDecision.mandate !== undefined ? { mandate: editAskDecision.mandate } : {}) });

package/dist/core/gate-outcome.d.ts

@@ -360,8 +360,8 @@ export type GateDisposition = {
  * to anyone: the mode, the disclosed class word (`askClass`, the first member of the folded set in `ASK_CLASSES`
  * order — one of {@link releasableAskClassesFor} on the call's face), the whole set, and the origin / mandate words the card would
  * have shown. `reason` is a member of {@link import("./ask-origin.js").MODE_RELEASE_REASONS} (`isModeReleaseReason`):
- * `"rule_unreadable"` marks a release over a rule the call could not be read against, `"target_unresolved"` a release (the
- * shell face) over a write target whose reading could not say where it leads; absent, the release names none. The record carries no face, so the
+ * `"target_unresolved"` marks a release (the shell face) over a write target whose reading could not say where it leads;
+ * absent, the release names none. The record carries no face, so the
  * screen asks that SOME face releases the class.
  */
 export interface ModeRelease {

package/dist/core/governance-codes.js

@@ -47,6 +47,8 @@ export const NON_GOVERNANCE_MEMORY_CODES = new Set([
     "memory.consolidation_lease_unavailable",
     "memory.consolidation_backend_failed",
     "memory.consolidation_gate_failed",
+    "memory.consolidation_write_refused",
+    "memory.landing_unstable",
     "memory.active_set_collapse",
     "memory.challenge_ledger_oversize",
     "memory.control_plane_rebuilt",

package/dist/core/hooks.d.ts

@@ -939,6 +939,14 @@ export interface UserPromptSubmitContext {
      * {@link source}, and absence means "anonymous caller", exactly as on the event face.
      */
     actor?: ActorAssertion;
+    /**
+     * The files declared on this objective (`TaskSpec.userAttachments`), in order — present only on `source:"objective"`
+     * when the objective declares any. A path entry shows its path; a host entry its name and byte count, never its
+     * bytes. Blocking the objective reads and delivers none of them. A hook does not govern the engine's reading of an
+     * allowed attachment (PreToolUse does not run for it either): a deployment that must keep a path from the model
+     * writes a deny rule, which the attachment read honors like the Read tool does.
+     */
+    userAttachments?: readonly import("./user-attachment.js").UserAttachmentDeclaration[];
 }
 /** #281 件A — the context of a {@link Hooks.postToolBatch} invocation (third parameter, additive —
  *  deliberately NOT folded into `meta`, whose presence already means "the engine injected here"). */
@@ -1105,35 +1113,35 @@ export interface PersistedRuleHitRule {
  * deny > ask > allow — already chose it). `rules` is non-empty by contract — an empty set covers nothing
  * and is not a hit (the normalizer reads it as a clean negative).
  *
- * Why dots and not an id: a persisted rule HAS no scalar id — it is a (behavior, text, scope) group whose
- * identity is the set of add dots that redeemed it, and two concurrently approved records for one text
- * each carry their own. The set is the identity; a joined string would not be one.
+ * Why dots and not an id: a persisted rule HAS no scalar id — it is a (behavior, text, scope) group whose identity is
+ * the set of add dots that redeemed it, and two concurrently approved records for one text each carry their own.
  *
- * The pre-375 single-rule object shape (`{ rule, dots? }`) and the pre-behavior `{ rules }` shape are
- * NOT accepted: on this loosening seam an unrecognized answer degrades to a clean negative (more asks),
- * never to a match — the safe failure shape for a lane that missed the same-window upgrade.
+ * The pre-375 single-rule object shape (`{ rule, dots? }`) and the pre-behavior `{ rules }` shape are NOT accepted:
+ * on this loosening seam an unrecognized answer degrades to a clean negative (more asks), never to a match.
  */
 export interface PersistedRuleHit {
     /** What the deciding rule(s) say about the call — the closed set's word. */
     readonly behavior: import("./permission-rule-model.js").RuleBehavior;
     /** The rule set the verdict stands on. Non-empty. */
     readonly rules: readonly PersistedRuleHitRule[];
+    /** A path DENY's coordinates (where the reaching row met the call): the gate's exits mint the refusal's card from it. */
+    readonly denial?: import("../tools/fs/safety.js").PathDenialEvidence;
 }
 /**
- * design/252 G-2 — the answer a lane gives when it could not READ its store (no `reason`; the CALL form is `reason`'s).
+ * design/252 G-2 — the answer a lane gives when it could not READ its store, or a partition of it (no `reason`; the CALL form is `reason`'s).
  *
- * The store form's DECISION meaning is identical to "no rule": the store's rows — allow, ask and deny alike — take
- * no part in this call's decision (skipped, the way a settings file with errors is skipped whole; the lane announces
- * it, and the rows apply again once a read succeeds). What it changes is the RECORD: without it, an unreadable store
- * and a store that holds no matching rule are the same answer (`undefined`), and the ask's evidence would report one
- * as the other — `"no_match"` ("we looked and found nothing") vs `"unavailable"` ("we could not look").
+ * The store form fails CLOSED: a deny or ask row inside what could not be read may forbid this call and an allow beside it
+ * is no yes, so the decision becomes a real-approval ask (origin `rule_store_unavailable`, class `governance_unavailable`:
+ * no automatic lane clears it, `bypassPermissions` keeps it for a person, headless it is refused) until a read succeeds
+ * again; a deny or ask row that WAS read still stands. The RECORD says `"unavailable"`, not `"no_match"`; the lane
+ * announces the skipped partition once per run.
  */
 export interface PersistedRuleUnreadable {
     readonly unreadable: true;
-    /** WHY the lane could not read: absent for a store read failure (its rows take no part); for a CALL the lane could
-     *  not read against the person's standing deny/ask rows (an expansion where a rule reads a word, an unterminated quote,
-     *  a syntax error — `programRunReachOf`'s `unreadable` word), the lexer's reason — the call then fails closed: an allow
-     *  tightens to a real-approval ask of origin `rule_store_unavailable`, the reason in its message. */
+    /** WHY the lane could not read: absent for a store (or partition) read failure — the store form, a real-approval ask of
+     *  class `governance_unavailable`; for a CALL the lane could not read against the person's standing deny/ask rows (an
+     *  expansion where a rule reads a word, an unterminated quote, a syntax error) the lexer's reason — the call form, an allow
+     *  tightens to a real-approval ask of class `rule_unreadable`. Both carry the origin `rule_store_unavailable`. */
     readonly reason?: string;
 }
 /**
@@ -1610,10 +1618,10 @@ export interface ToolGateInput extends PermissionSeatInputs, SkillGateSeats, All
     persistedRules?: {
         /** The lane's verdict for this call — a {@link PersistedRuleHit} naming the behavior that spoke and
          *  the rule set it stands on, a coverage-carrying clean negative, an unreadable report, or
-         *  `undefined` (the store was READ and no rule speaks). Must not throw — and a store that cannot be
-         *  read answers `{ unreadable: true }`, not `undefined`: the DECISION is the same (its rows take no part, as
-         *  for a thrown or timed-out lane) but the evidence records `"unavailable"`, not `"no_match"`; the lane owns
-         *  announcing the skip. A call unreadable against the rows answers `{ unreadable: true, reason }` (fails closed).
+         *  `undefined` (the store was READ and no rule speaks). Must not throw — and a store (or a partition of it) that cannot
+         *  be read answers `{ unreadable: true }`, not `undefined`: it fails closed (a row nobody could read may forbid the call;
+         *  the decision becomes a real-approval ask) and the evidence records `"unavailable"`, not `"no_match"`; the lane owns
+         *  announcing the skip. A call unreadable against the rows answers `{ unreadable: true, reason }` (the call form).
          *
          *  For an ALLOW the set is the COVERAGE SET — each member's canonical text plus its add DOTS. A
          *  single rule admitting the whole command is a one-element set; a compound admitted by the

package/dist/core/human-input-projection.js

@@ -31,6 +31,7 @@ const HANDLED_HUMAN_INPUT_KEYS = {
     delivery: "forwarded",
     principal: "forwarded",
     entryId: "forwarded",
+    attachments: "forwarded",
 };
 export function buildHumanInputEvent(input) {
     void HANDLED_HUMAN_INPUT_KEYS;
@@ -45,6 +46,7 @@ export function buildHumanInputEvent(input) {
         ...(input.actor !== undefined ? { actor: snapshotActorAssertion(input.actor) } : {}),
         ...(input.principal !== undefined ? { principal: input.principal } : {}),
         ...(input.entryId !== undefined ? { entryId: input.entryId } : {}),
+        ...(input.attachments !== undefined && input.attachments.length > 0 ? { attachments: input.attachments.map((a) => ({ ...a })) } : {}),
     };
 }
 export function buildAppliedHumanInputEvent(input) {

package/dist/core/lsp-diagnostics.d.ts

@@ -79,6 +79,9 @@ export declare class LspDiagnosticsRegistry {
      */
     drain(runIdent: string): LspFileDiagnostics[];
 }
+/** A drain with every file the run's read face withholds left out (`withheldOf` answers the batch: a withheld file is in
+ *  the map; a judgment that fails withholds them all). The run's drain already marked them delivered, so they do not come back. */
+export declare function withholdListedDiagnostics(files: LspFileDiagnostics[], withheldOf: (uris: readonly string[]) => Promise<ReadonlyMap<string, unknown>>): Promise<LspFileDiagnostics[]>;
 /**
  * CC 198 `formatDiagnosticsSummary` (198:320480-320499), verbatim shape:
  * ```

package/dist/core/lsp-diagnostics.js

@@ -74,6 +74,12 @@ export class LspDiagnosticsRegistry {
         return out;
     }
 }
+export async function withholdListedDiagnostics(files, withheldOf) {
+    if (files.length === 0)
+        return files;
+    const withheld = await withheldOf(files.map((f) => f.uri)).catch(() => undefined);
+    return withheld === undefined ? [] : files.filter((f) => !withheld.has(f.uri));
+}
 function basenameOfUri(uri) {
     const path = uri.replace(/^file:\/\//, "");
     const idx = path.lastIndexOf("/");

package/dist/core/lsp-session.d.ts

@@ -1,4 +1,4 @@
-import type { LspSession, LspOperation, LspRequestParams, LspResult, LspTransport, LspReadText } from "./lsp.js";
+import type { LspSession, LspOperation, LspRequestParams, LspResult, LspTransport, LspReadText, LspReadGate } from "./lsp.js";
 import type { LspDiagnosticsRegistry } from "./lsp-diagnostics.js";
 export interface SessionWarmup {
     /** Empty results within this window after session creation are retried (a freshly-spawned server answers
@@ -24,9 +24,14 @@ export declare class TransportLspSession implements LspSession {
      *  we ourselves sent removes the round-trip entirely (`uriToPath` stays the fallback for a server that
      *  re-spells the URI). */
     private readonly openedUris;
-    /** In-flight per-file syncs — concurrent ops on the same new file share ONE read/didOpen. Each entry owns a
-     *  {@link SharedAbortScope} so ONE caller's abort no longer cancels the read the others are waiting on
-     *  (HRD-LSP-12). */
+    /** Files carried over from a session that died ({@link warmOpen}): not read yet — the next gated sync opens each one
+     *  its caller's gate admits, before that caller's query, and drops the rest. */
+    private readonly carried;
+    /** Per file, the generation of the newest sync started for it — the only one that may still publish. */
+    private readonly syncGen;
+    /** Per file, the newest sync in flight (dropped when it settles); concurrent by-name syncs share ONE read/didOpen.
+     *  Each entry owns a {@link SharedAbortScope} so ONE caller's abort no longer cancels the read the others are waiting on
+     *  (HRD-LSP-12). `byName` = a read with no gate (the only kind another caller may share). */
     private readonly syncing;
     private readonly createdAt;
     /** HRD-LSP-11: the warm-up barrier as a shared JOB, not a boolean flag set before the await (which let the
@@ -47,7 +52,7 @@ export declare class TransportLspSession implements LspSession {
      *  closing one mid-op turns a healthy answer into `server_terminated` for a caller that did nothing wrong. */
     get inFlight(): number;
     private activeRequests;
-    request(op: LspOperation, params: LspRequestParams, signal?: AbortSignal): Promise<LspResult>;
+    request(op: LspOperation, params: LspRequestParams, signal?: AbortSignal, gate?: LspReadGate): Promise<LspResult>;
     private requestOnce;
     /**
      * HRD-LSP-11: run (or join) this session's ONE warm-up barrier.
@@ -60,13 +65,28 @@ export declare class TransportLspSession implements LspSession {
      * and one caller's abort neither cancels the shared barrier nor makes the others wait for it.
      */
     private warmupBarrierOnce;
-    /** Re-sync every opened file (+ the queried one) with its CURRENT on-disk text, in parallel. Returns the
-     *  QUERIED file's outcome — the one the op's honesty depends on (HRD-LSP-7). */
+    /** Re-sync every opened and carried file (+ the queried one) with its CURRENT on-disk text, in parallel, each through
+     *  the caller's gate. Returns the QUERIED file's outcome — the one the op's honesty depends on (HRD-LSP-7). */
     private syncOpenedFiles;
-    /** didOpen a new file / didChange (full-text replace) an opened one whose disk content moved. Never throws:
-     *  it REPORTS failure instead (`{ok:false}`) — an unreadable file no longer looks like a clean sync to the
-     *  caller. Concurrent callers share one in-flight sync, each keeping its OWN cancellation (HRD-LSP-12). */
-    private syncOne;
+    /**
+     * The session's one read port. Every sync of a document takes the next generation of that document and publishes only if
+     * it is still the newest one started when its read settles — so a sync that publishes after another started after that
+     * publication and opened its object after it: an older object's text never lands after a newer one's. No sync ever waits
+     * for another's read (a read that never settles, abandoned or not, holds up nobody else). A superseded sync publishes nothing: its waiters take the newest sync's outcome, or sync
+     * again when that one is gone or abandoned. With a gate, the file is read only from the object the gate admitted and
+     * holds, never by its name again; a file the newest gate does not admit is closed (not read, not re-sent, its text
+     * dropped from the server's open documents). With none (a caller with no read face), by name through `readText` — and
+     * such a sync shares a by-name read already in flight for the document, each joiner keeping its OWN cancellation
+     * (HRD-LSP-12); a gated read is its caller's admission and is never shared.
+     */
+    private syncGated;
+    private syncInTurn;
+    /** didClose a document the caller's gate refused and forget it (a later caller whose gate admits it opens it afresh). */
+    private closeRefused;
+    /** didOpen a new file / didChange (full-text replace) an opened one whose disk content moved, from the text `read`
+     *  returns — only while `isNewest()` holds when the read settles (else {@link SUPERSEDED}, nothing sent). Never throws: it
+     *  REPORTS failure instead (`{ok:false}`) — an unreadable file no longer looks like a clean sync to the caller. */
+    private publishRead;
     /** Structural fallback classification for errors carrying no {@link lspFailureOf} brand (a
      *  third-party transport, e.g. the TOB WS lane) — abort signal and transport liveness are the only
      *  transport-neutral facts available; everything else is a server fault. Cannot produce
@@ -78,19 +98,21 @@ export declare class TransportLspSession implements LspSession {
      *  project config only "sees" its open files (e.g. tsserver inferred project), so without the carry-over,
      *  cross-file ops (references/calls) silently degrade to single-file after a heal. */
     openedFiles(): string[];
-    /** Re-open carried files on a fresh session (heal). Best-effort per file (a deleted file just skips).
-     *  Returns how many files did NOT make it, so the manager's heal log can say when a carry-over was lost
-     *  instead of leaving a silently single-file server behind (HRD-LSP-1 disclosure half). */
-    warmOpen(filePaths: string[], signal?: AbortSignal): Promise<{
+    /** Carry files over to a fresh session (heal): nothing is read here — no caller's read face is in hand — and the next
+     *  gated sync (an op, a change notice) opens each file its caller's gate admits before that caller's query, so no op
+     *  is answered from a document set missing an admitted carried file (HRD-LSP-1). `deferred` counts the files carried;
+     *  a carried file that later cannot be read is logged by that sync (`lsp_sync_skipped`). */
+    warmOpen(filePaths: string[], _signal?: AbortSignal): Promise<{
         opened: number;
         failed: number;
+        deferred: number;
     }>;
     /**
      * design/121: push the file's CURRENT text to the server WITHOUT an op (didOpen/didChange as
      * appropriate). The agent's edit/write tools call this fire-and-forget so the server re-analyzes
      * and pushes publishDiagnostics — the session's normal lazy sync only runs on the next LSP op,
-     * which may never come. Never throws (same best-effort contract as syncOne).
+     * which may never come. Through the caller's `gate`, as every read. Never throws (same best-effort contract as publishRead).
      */
-    notifyFileChanged(filePath: string, signal?: AbortSignal): Promise<void>;
+    notifyFileChanged(filePath: string, signal?: AbortSignal, gate?: LspReadGate): Promise<void>;
     close(): Promise<void>;
 }

package/dist/core/lsp-session.js

@@ -1,6 +1,14 @@
 import { uriToPath, buildRequest, callHierarchyMethod, parseResult, pathToUri } from "./lsp-protocol.js";
-import { lspFailureOf, SharedAbortScope, settleOnAbort } from "./lsp.js";
+import { lspFailureOf, MAX_LSP_FILE_BYTES, SharedAbortScope, settleOnAbort } from "./lsp.js";
 import { thrownText } from "./thrown-value.js";
+const UTF8 = new TextDecoder("utf-8", { ignoreBOM: true });
+async function readHeldText(held, signal) {
+    const bytes = await held.readBytes(MAX_LSP_FILE_BYTES, signal);
+    if (!bytes.ok)
+        throw bytes.error;
+    return UTF8.decode(bytes.value);
+}
+const SUPERSEDED = Symbol("superseded");
 const WARMUP_MAX_ATTEMPTS = 3;
 export class TransportLspSession {
     transport;
@@ -10,6 +18,8 @@ export class TransportLspSession {
     warmup;
     opened = new Map();
     openedUris = new Map();
+    carried = new Set();
+    syncGen = new Map();
     syncing = new Map();
     createdAt = Date.now();
     warmupBarrier;
@@ -44,20 +54,20 @@ export class TransportLspSession {
         return this.activeRequests;
     }
     activeRequests = 0;
-    async request(op, params, signal) {
+    async request(op, params, signal, gate) {
         this.activeRequests += 1;
         try {
-            return await this.requestOnce(op, params, signal);
+            return await this.requestOnce(op, params, signal, gate);
         }
         finally {
             this.activeRequests -= 1;
         }
     }
-    async requestOnce(op, params, signal) {
+    async requestOnce(op, params, signal, gate) {
         const built = buildRequest(op, params);
         if (!built)
             return { kind: "none", reason: "unsupported_operation" };
-        const sync = await this.syncOpenedFiles(params.filePath, signal);
+        const sync = await this.syncOpenedFiles(params.filePath, signal, gate);
         if (!sync.ok) {
             const reason = signal?.aborted ? "cancelled" : (sync.reason ?? "file_sync_failed");
             this.log("lsp_op_degraded", { op, file: params.filePath, reason, err: sync.error });
@@ -131,64 +141,109 @@ export class TransportLspSession {
         entry.scope.join(signal);
         await settleOnAbort(entry.job, signal, () => undefined);
     }
-    async syncOpenedFiles(queried, signal) {
-        const files = new Set(this.opened.keys());
+    async syncOpenedFiles(queried, signal, gate) {
+        const files = new Set([...this.opened.keys(), ...this.carried]);
         files.add(queried);
-        const outcomes = await Promise.all([...files].map(async (fp) => [fp, await this.syncOne(fp, signal)]));
+        const outcomes = await Promise.all([...files].map(async (fp) => [fp, await this.syncGated(fp, signal, gate)]));
         return outcomes.find(([fp]) => fp === queried)?.[1] ?? { ok: true };
     }
-    syncOne(filePath, signal) {
-        const inflight = this.syncing.get(filePath);
-        if (inflight && !inflight.scope.signal.aborted) {
-            inflight.scope.join(signal);
-            return settleOnAbort(inflight.job, signal, () => ({ ok: false, error: "aborted by the caller" }));
+    async syncGated(filePath, signal, gate) {
+        const outcome = await this.syncInTurn(filePath, signal, gate);
+        if (outcome.ok || signal?.aborted !== true)
+            this.carried.delete(filePath);
+        return outcome;
+    }
+    syncInTurn(filePath, signal, gate) {
+        const aborted = () => ({ ok: false, error: "aborted by the caller" });
+        const newest = this.syncing.get(filePath);
+        if (gate === undefined && newest?.byName === true && !newest.scope.signal.aborted) {
+            newest.scope.join(signal);
+            return settleOnAbort(newest.job, signal, aborted);
         }
+        const gen = (this.syncGen.get(filePath) ?? 0) + 1;
+        this.syncGen.set(filePath, gen);
+        const isNewest = () => this.syncGen.get(filePath) === gen;
         const scope = new SharedAbortScope();
         scope.join(signal);
-        const entry = {
-            scope,
-            job: (async () => {
-                let text;
-                try {
-                    text = await this.readText(filePath, scope.signal);
-                }
-                catch (e) {
-                    const error = thrownText(e);
-                    this.log("lsp_sync_skipped", { file: filePath, error, opened: this.opened.has(filePath) });
-                    return { ok: false, error };
+        const entry = { scope, byName: gate === undefined, job: Promise.resolve({ ok: true }) };
+        entry.job = (async () => {
+            let published;
+            if (gate === undefined)
+                published = await this.publishRead(filePath, () => this.readText(filePath, scope.signal), isNewest);
+            else {
+                const admission = await gate(filePath, scope.signal).catch((e) => ({ ok: false, reason: `the read boundary could not judge this file (${thrownText(e)})` }));
+                if (!admission.ok) {
+                    if (isNewest() && !scope.signal.aborted)
+                        this.closeRefused(filePath);
+                    return { ok: false, error: admission.reason };
                 }
-                const cur = this.opened.get(filePath);
-                const uri = pathToUri(filePath);
-                if (!cur) {
-                    this.transport.notify("textDocument/didOpen", {
-                        textDocument: { uri, languageId: this.languageId, version: 1, text },
-                    });
-                    if (this.transport.closed === true) {
-                        this.log("lsp_sync_notify_dropped", { file: filePath, kind: "didOpen" });
-                        return { ok: false, error: "didOpen was not delivered (transport closed)", reason: "server_terminated" };
-                    }
-                    this.opened.set(filePath, { version: 1, text });
-                    this.openedUris.set(uri, filePath);
-                }
-                else if (cur.text !== text) {
-                    const version = cur.version + 1;
-                    this.transport.notify("textDocument/didChange", { textDocument: { uri, version }, contentChanges: [{ text }] });
-                    if (this.transport.closed === true) {
-                        this.log("lsp_sync_notify_dropped", { file: filePath, kind: "didChange", version });
-                        return { ok: false, error: "didChange was not delivered (transport closed)", reason: "server_terminated" };
-                    }
-                    this.opened.set(filePath, { version, text });
-                    this.log("lsp_file_resync", { file: filePath, version });
-                }
-                return { ok: true };
-            })(),
-        };
+                const held = admission.object;
+                published = await this.publishRead(filePath, () => readHeldText(held, scope.signal).finally(() => held.close().catch(() => undefined)), isNewest);
+            }
+            if (published !== SUPERSEDED)
+                return published;
+            if (scope.signal.aborted)
+                return aborted();
+            const successor = this.syncing.get(filePath);
+            if (successor !== undefined && successor !== entry && !successor.scope.signal.aborted) {
+                successor.scope.join(scope.signal);
+                return successor.job;
+            }
+            return this.syncInTurn(filePath, scope.signal, gate);
+        })();
         this.syncing.set(filePath, entry);
         const settled = entry.job.finally(() => {
             if (this.syncing.get(filePath) === entry)
                 this.syncing.delete(filePath);
         });
-        return settleOnAbort(settled, signal, () => ({ ok: false, error: "aborted by the caller" }));
+        return settleOnAbort(settled, signal, aborted);
+    }
+    closeRefused(filePath) {
+        this.carried.delete(filePath);
+        if (!this.opened.has(filePath))
+            return;
+        const uri = pathToUri(filePath);
+        this.opened.delete(filePath);
+        this.openedUris.delete(uri);
+        this.transport.notify("textDocument/didClose", { textDocument: { uri } });
+        this.log("lsp_doc_closed_refused", { file: filePath });
+    }
+    async publishRead(filePath, read, isNewest) {
+        let text;
+        try {
+            text = await read();
+        }
+        catch (e) {
+            const error = thrownText(e);
+            this.log("lsp_sync_skipped", { file: filePath, error, opened: this.opened.has(filePath) });
+            return { ok: false, error };
+        }
+        if (!isNewest())
+            return SUPERSEDED;
+        const cur = this.opened.get(filePath);
+        const uri = pathToUri(filePath);
+        if (!cur) {
+            this.transport.notify("textDocument/didOpen", {
+                textDocument: { uri, languageId: this.languageId, version: 1, text },
+            });
+            if (this.transport.closed === true) {
+                this.log("lsp_sync_notify_dropped", { file: filePath, kind: "didOpen" });
+                return { ok: false, error: "didOpen was not delivered (transport closed)", reason: "server_terminated" };
+            }
+            this.opened.set(filePath, { version: 1, text });
+            this.openedUris.set(uri, filePath);
+        }
+        else if (cur.text !== text) {
+            const version = cur.version + 1;
+            this.transport.notify("textDocument/didChange", { textDocument: { uri, version }, contentChanges: [{ text }] });
+            if (this.transport.closed === true) {
+                this.log("lsp_sync_notify_dropped", { file: filePath, kind: "didChange", version });
+                return { ok: false, error: "didChange was not delivered (transport closed)", reason: "server_terminated" };
+            }
+            this.opened.set(filePath, { version, text });
+            this.log("lsp_file_resync", { file: filePath, version });
+        }
+        return { ok: true };
     }
     static classifyUnbranded(signal, transport) {
         if (signal?.aborted)
@@ -201,15 +256,20 @@ export class TransportLspSession {
         return this.transport.closed === true;
     }
     openedFiles() {
-        return [...this.opened.keys()];
+        return [...new Set([...this.opened.keys(), ...this.carried])];
     }
-    async warmOpen(filePaths, signal) {
-        const outcomes = await Promise.all(filePaths.map((fp) => this.syncOne(fp, signal)));
-        const failed = outcomes.filter((o) => !o.ok).length;
-        return { opened: outcomes.length - failed, failed };
+    async warmOpen(filePaths, _signal) {
+        let deferred = 0;
+        for (const fp of filePaths) {
+            if (this.opened.has(fp) || this.carried.has(fp))
+                continue;
+            this.carried.add(fp);
+            deferred += 1;
+        }
+        return { opened: 0, failed: 0, deferred };
     }
-    notifyFileChanged(filePath, signal) {
-        return this.syncOne(filePath, signal).then(() => undefined);
+    notifyFileChanged(filePath, signal, gate) {
+        return this.syncGated(filePath, signal, gate).then(() => undefined);
     }
     close() {
         return this.transport.close();