@sema-agent/core 7.49.5 → 7.50.0

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();

package/dist/core/lsp.d.ts

@@ -1,4 +1,8 @@
-import type { AgentTool, ExecutionEnv } from "../internal/harness-types.js";
+import { type RootsSeat } from "../tools/fs/safety.js";
+import { type ReadDenyMatcher } from "../tools/fs/read-deny.js";
+import type { HomeViewsCarrier } from "../tools/fs/read-deny-home.js";
+import type { ContainmentFace } from "../tools/fs/containment-face.js";
+import type { AgentTool, BoundFileObject, ExecutionEnv } from "../internal/harness-types.js";
 /**
  * LSP code-intelligence tool (design/64 §13.1) — the app-dev命门 (go-to-def / find-refs / hover across
  * Dart/Kotlin/TS). A single `lsp` tool with a 9-operation enum, built over a pluggable {@link LspServerManager}.
@@ -147,8 +151,71 @@ export interface LspRequestParams {
 }
 /** An active language-server session for one language, scoped to a workspace. */
 export interface LspSession {
-    request(op: LspOperation, params: LspRequestParams, signal?: AbortSignal): Promise<LspResult>;
+    /** `gate` = the caller's read face at the session's file reads ({@link LspReadGate}); absent ⇒ a caller with none. */
+    request(op: LspOperation, params: LspRequestParams, signal?: AbortSignal, gate?: LspReadGate): Promise<LspResult>;
 }
+/** What a session's read gate answered for one file: the object its judgment named, opened and HELD (the environment's
+ *  `openBound`) under the canonical key it was judged as — the session reads that object, never the name again, and closes
+ *  it — or a refusal with its reason. */
+export type LspReadAdmission = {
+    readonly ok: true;
+    readonly key: string;
+    readonly object: BoundFileObject;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/** May a session read `filePath` (a path {@link resolveLspPath} minted) for this caller, now — and if so, WHAT: the gate
+ *  admits an object, not a name ({@link LspReadAdmission}). A session reads a file only from the object its caller's gate
+ *  admitted, and closes an opened document the gate does not admit. */
+export type LspReadGate = (filePath: string, signal?: AbortSignal) => Promise<LspReadAdmission>;
+/** The read face one LSP mount reads under: the seats the fs read tools take, so the gate and the tool resolve and judge
+ *  a `filePath` alike (see {@link LspToolOptions.readFace}). */
+export interface LspReadFace {
+    /** The canonical task root: the primary containment root, and the base when no working directory is tracked. */
+    readonly rootCanonical: string;
+    /** The extra read roots (write-capable and read-only), read per call. */
+    readonly roots?: RootsSeat;
+    /** The tracked working directory; `current` is read per call as the base of a relative `filePath`. */
+    readonly cwdRef?: {
+        readonly current: string;
+    };
+    /** The read-deny table in force, with its placement's home views. */
+    readonly readDeny?: ReadDenyMatcher & HomeViewsCarrier;
+    /** The read containment face. Absent ⇒ `roots`. */
+    readonly face?: ContainmentFace;
+    /** The file read station's admission: an out-of-root target the gate asked about and let through, read once. */
+    readonly admitted?: (toolCallId: string | undefined, canonicalKey: string) => boolean;
+    /** Settles once the read-deny table and read roots a judgment takes are ready (a Runner compiles them per read of the
+     *  person's rules): a call's own (`toolCallId`), or — with none — the run's newest; at `signal` too; never rejects;
+     *  absent ⇒ ready. The tool waits for it before it takes its call's; the session's own reads before they judge. */
+    readonly ready?: (toolCallId: string | undefined, signal?: AbortSignal) => Promise<void>;
+}
+/** The base a relative `filePath` resolves against: the catalog declaration through the one selector the fences read it
+ *  with; with no read face the env's working directory is the only base there is. */
+export declare function lspBaseOf(readFace: LspReadFace | undefined, env?: ExecutionEnv): string | undefined;
+/** The session gate over a read face — the bound read a user attachment makes, at the session's read: the name is judged
+ *  as `Read` judges its target (a judgment that throws refuses), the object the judgment named is opened and held
+ *  (`openBound`; an environment without it cannot bind and refuses), and the name, judged again, must still land on the
+ *  held key. The admission carries the held object; the session reads only it. `authorizedKey` = the canonical key this
+ *  call's target was authorized as (the station's one-read admission already spent on it): a spelling that still lands
+ *  there passes outside the roots, nothing else does. */
+export declare function lspReadGateOf(env: ExecutionEnv, face: LspReadFace, authorizedKey?: string): LspReadGate;
+/** Why a file the language server named is withheld: a read-deny row reaches one of its views, or its views could not be
+ *  read (`unreadable` — the judgment's absence word). */
+export type LspListedWithholding = {
+    readonly pattern: string;
+} | {
+    readonly unreadable: true;
+};
+/**
+ * The files a language server named (result locations, symbols, drained diagnostics), judged as ONE bounded batch against
+ * the read face's deny table on every view of each file — the spelling, the canonical target, the home view and the link
+ * hops, through the same `resolveKey` a read target meets (containment is not this question: the face is judged open).
+ * Fail-closed: a file whose views cannot be read, and every file when the batch outlives the gate's deadline, is withheld.
+ * Kept files are absent from the result.
+ */
+export declare function lspListedWithheld(env: ExecutionEnv, face: LspReadFace, uris: readonly string[], signal?: AbortSignal): Promise<ReadonlyMap<string, LspListedWithholding>>;
 /**
  * A JSON-RPC transport to ONE language server, POST-`initialize`. The DEPLOYMENT provides the concrete
  * transport; the protocol logic ({@link buildRequest}/`parseResult`, `TransportLspSession`) drives the LSP
@@ -175,7 +242,8 @@ export interface LspTransport {
      *  a test mock stays minimal. */
     readonly closed?: boolean;
 }
-/** Reads a workspace file's CURRENT text for the session's didOpen/didChange re-sync. TOC = local fs; TOB =
+/** Reads a workspace file's CURRENT text for the session's didOpen/didChange re-sync BY NAME — the read of a caller with no
+ *  gate (no read face) only; a gated read is the admitted held object's ({@link LspReadAdmission}). TOC = local fs; TOB =
  *  the sandbox ExecutionEnv. */
 export type LspReadText = (filePath: string, signal?: AbortSignal) => Promise<string>;
 /** CC 2.1.220's LSP file cap (10MB — `File too large for LSP analysis`, (pretty220.js:474745, historical; not relocated in 250 — see cc-250 anchors)). Single-sourced
@@ -216,6 +284,18 @@ export interface LspToolOptions {
     /** The task's ExecutionEnv, passed through to {@link LspServerManager.sessionFor} (the agent's sandbox —
      *  where an in-env language server must run). The Runner wires this from the per-task env. */
     env?: ExecutionEnv;
+    /**
+     * The read face this mount reads under (needs `env`). PRESENT ⇒ every read the tool causes passes it: the `filePath`
+     * target is resolved against the declared base (the tracked working directory, else the root) and fenced as `Read`
+     * fences its own — containment with the station's one-read admission, the read-deny table, blocked devices; the file
+     * preconditions (exists / a regular file / the size cap) are read from the object that judgment named, held at its key
+     * (the environment's `openBound`), never from the spelling again; the session reads an opened file only from the
+     * object the face admitted and held (an environment without `openBound` reads nothing) and closes one it does not
+     * admit; every location or symbol in a file the deny table reaches is withheld, and the result says how many. ABSENT ⇒
+     * no read face judged this mount (a library-direct tool with no gate): a relative `filePath` resolves against
+     * `env.cwd`, the preconditions and the session's reads go by name, nothing is fenced and nothing is withheld.
+     */
+    readFace?: LspReadFace;
 }
 /** Build the `lsp` tool over a {@link LspServerManager}. Mounted only when a manager is wired (opt-in). */
 export declare function createLspTool(manager: LspServerManager, opts?: LspToolOptions): AgentTool;