@sema-agent/core 7.40.1 → 7.41.1

package/dist/stores/file/session-policy-store.js

@@ -1,6 +1,6 @@
 import { readFileSync, readdirSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
-import { loosenReasons, normalizeRules, stripRev, SessionPolicyError, } from "../../core/session-policy-store.js";
+import { assertSessionRuleNamesCurrent, loosenReasons, normalizeRules, readMountedToolNames, stripRev, SessionPolicyError, } from "../../core/session-policy-store.js";
 import { atomicWriteFile, ensureDir, sanitizeScope } from "./fs-atomic.js";
 import { guardCorruptSink } from "./corrupt-read-sink.js";
 import { assertAdoptionBootGate, readRootAdoptionFile } from "./adoption/marker.js";
@@ -13,27 +13,25 @@ export function readSessionPolicyMark(path) {
     }
     catch (err) {
         if (err.code === "ENOENT")
-            return null;
+            return { mark: null };
         throw err;
     }
-    const refuse = (fault) => {
-        throw new SessionPolicyError("corrupt", `session rules high-water mark ${fault}: ${path} — refusing rather than restart this key's rev from zero. Deleting that file is the repair, and it gives up the number it was holding.`);
-    };
+    const corrupt = (reason) => ({ corrupt: { reason } });
     let parsed;
     try {
         parsed = JSON.parse(raw);
     }
     catch {
-        return refuse("is unparseable");
+        return corrupt("is unparseable");
     }
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
-        return refuse("is not a JSON object");
+        return corrupt("is not a JSON object");
     const mark = parsed;
     if (typeof mark.__hwm !== "number" || !Number.isFinite(mark.__hwm))
-        return refuse("carries no numeric value");
+        return corrupt("carries no numeric value");
     if (mark.__gen !== undefined && (typeof mark.__gen !== "number" || !Number.isInteger(mark.__gen) || mark.__gen < 0))
-        return refuse("carries a lineage that is not a whole number");
-    return mark;
+        return corrupt("carries a lineage that is not a whole number");
+    return { mark };
 }
 export function judgeSessionPolicyRowObject(raw) {
     let parsed;
@@ -63,12 +61,22 @@ export function judgeSessionPolicyRowShape(row) {
     void _principal;
     return { rules: clean };
 }
+export function attributeSessionPolicyRow(dir, file, row) {
+    const spell = (p) => (typeof p === "string" || p === null ? p : undefined);
+    if (row !== undefined && typeof row.__sid === "string")
+        return { owner: { sessionId: row.__sid, principal: spell(row.__principal) } };
+    const markRead = readSessionPolicyMark(join(dir, `${file.slice(0, -".json".length)}${MARK_SUFFIX}`));
+    const mark = "corrupt" in markRead ? null : markRead.mark;
+    return { owner: mark !== null && typeof mark.__sid === "string" ? { sessionId: mark.__sid, principal: spell(mark.__principal) } : undefined, markRead };
+}
 export class FileSessionPolicyStore {
     dir;
     onCorruptRead;
+    mountedToolNames;
     anonymousAlias;
     constructor(root, opts) {
         assertAdoptionBootGate(root, "FileSessionPolicyStore");
+        this.mountedToolNames = readMountedToolNames(opts?.mountedToolNames);
         this.dir = join(root, "session-policy");
         ensureDir(this.dir);
         this.onCorruptRead = guardCorruptSink(opts?.onCorruptRead);
@@ -79,11 +87,57 @@ export class FileSessionPolicyStore {
     disclose(info) {
         this.onCorruptRead?.({ kind: "file", ...info });
     }
-    refuseDamaged(sessionId, principal, grade, reason) {
-        const path = this.pathFor(sessionId, principal);
+    refuseDamaged(sessionId, principal, path, grade, reason) {
         this.disclose({ sessionId, ...(principal !== undefined ? { principal } : {}), path, reason });
         throw new SessionPolicyError("corrupt", `session rules file for ${JSON.stringify(sessionId)} is ${grade} (${reason}) — refusing rather than read the rules it held as none (session rules only tighten). Repair it: fix the file, or delete it (deleting it = explicitly no rules, and gives up the rules it held). The file's location is reported to the store's corrupt-read disclosure (onCorruptRead), not in this message.`);
     }
+    refuseDamagedMark(sessionId, principal, reason) {
+        this.disclose({ sessionId, ...(principal !== undefined ? { principal } : {}), path: this.markPathFor(sessionId, principal), reason: `high-water mark ${reason}` });
+        throw new SessionPolicyError("corrupt", `session rules high-water mark for ${JSON.stringify(sessionId)} ${reason} — refusing rather than restart this key's rev from zero. Repair it: fix the mark file, or delete it (deleting it gives up the number it was holding). The file's location is reported to the store's corrupt-read disclosure (onCorruptRead), not in this message.`);
+    }
+    refuseUnreadable(sessionId, path, what, err) {
+        const reason = `${what} could not be read (${err.code ?? err.name})`;
+        this.disclose({ sessionId, path, reason });
+        throw new SessionPolicyError("corrupt", `session rules for ${JSON.stringify(sessionId)}: ${reason} — refusing rather than guess whose rules it holds. Retry; if it persists, repair access to the file. The file's location is reported to the store's corrupt-read disclosure (onCorruptRead), not in this message.`);
+    }
+    ownerOf(sessionId, file, row) {
+        try {
+            return attributeSessionPolicyRow(this.dir, file, row);
+        }
+        catch (err) {
+            return this.refuseUnreadable(sessionId, join(this.dir, `${file.slice(0, -".json".length)}${MARK_SUFFIX}`), "a rules row's high-water mark", err);
+        }
+    }
+    sweepMark(sessionId, markPath) {
+        try {
+            return readSessionPolicyMark(markPath);
+        }
+        catch (err) {
+            return this.refuseUnreadable(sessionId, markPath, "a rules row's high-water mark", err);
+        }
+    }
+    sweepEntries(sessionId) {
+        try {
+            return readdirSync(this.dir);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return [];
+            return this.refuseUnreadable(sessionId, this.dir, "the session rules directory", err);
+        }
+    }
+    readMark(sessionId, principal) {
+        let judged;
+        try {
+            judged = readSessionPolicyMark(this.markPathFor(sessionId, principal));
+        }
+        catch (err) {
+            return this.refuseDamagedMark(sessionId, principal, `could not be read (${err.code ?? err.name})`);
+        }
+        if ("corrupt" in judged)
+            return this.refuseDamagedMark(sessionId, principal, judged.corrupt.reason);
+        return judged.mark;
+    }
     pathFor(sessionId, principal) {
         return join(this.dir, `${this.basenameFor(sessionId, principal)}.json`);
     }
@@ -102,22 +156,28 @@ export class FileSessionPolicyStore {
         atomicWriteFile(join(this.dir, "tmp"), path, JSON.stringify(mark));
     }
     read(sessionId, principal) {
+        const path = this.pathFor(sessionId, principal);
+        const judged = this.readRowFile(path);
+        if (judged === null)
+            return null;
+        if ("corrupt" in judged)
+            return this.refuseDamaged(sessionId, principal, path, judged.corrupt.grade, judged.corrupt.reason);
+        const shaped = judgeSessionPolicyRowShape(judged.row);
+        if ("corrupt" in shaped)
+            return this.refuseDamaged(sessionId, principal, path, shaped.corrupt.grade, shaped.corrupt.reason);
+        return shaped.rules;
+    }
+    readRowFile(path) {
         let raw;
         try {
-            raw = readFileSync(this.pathFor(sessionId, principal), "utf8");
+            raw = readFileSync(path, "utf8");
         }
         catch (err) {
             if (err.code === "ENOENT")
                 return null;
-            return this.refuseDamaged(sessionId, principal, "unreadable", `read failed (${err.code ?? err.name})`);
+            return { corrupt: { grade: "unreadable", reason: `read failed (${err.code ?? err.name})` } };
         }
-        const judged = judgeSessionPolicyRowObject(raw);
-        if ("corrupt" in judged)
-            return this.refuseDamaged(sessionId, principal, judged.corrupt.grade, judged.corrupt.reason);
-        const shaped = judgeSessionPolicyRowShape(judged.row);
-        if ("corrupt" in shaped)
-            return this.refuseDamaged(sessionId, principal, shaped.corrupt.grade, shaped.corrupt.reason);
-        return shaped.rules;
+        return judgeSessionPolicyRowObject(raw);
     }
     async getRules(sessionId, principal) {
         return this.read(sessionId, principal);
@@ -128,13 +188,14 @@ export class FileSessionPolicyStore {
             throw new SessionPolicyError("conflict", `session rules rev mismatch (expected ${opts.expectedRev}, have ${prior?.rev ?? 0})`);
         }
         const clean = normalizeRules(stripRev(rules));
+        assertSessionRuleNamesCurrent(clean, this.mountedToolNames);
         if (prior && opts?.operator !== true) {
-            const loosens = loosenReasons(prior, clean);
+            const loosens = loosenReasons(prior, clean, this.mountedToolNames);
             if (loosens.length > 0) {
                 throw new SessionPolicyError("loosen_forbidden", `a non-operator session-rule write may only tighten; refused: ${loosens.join("; ")}`);
             }
         }
-        const mark = readSessionPolicyMark(this.markPathFor(sessionId, principal));
+        const mark = this.readMark(sessionId, principal);
         if (mark?.__lineage === "lost") {
             throw new SessionPolicyError("corrupt", `session rules for ${JSON.stringify(sessionId)} have no lineage evidence (the erase left a lost-lineage mark) — refusing to restart the key's lineage by guessing; delete the mark to restart it`);
         }
@@ -147,15 +208,7 @@ export class FileSessionPolicyStore {
         return next;
     }
     async listBySession(sessionId) {
-        let files;
-        try {
-            files = readdirSync(this.dir);
-        }
-        catch (err) {
-            if (err.code === "ENOENT")
-                return [];
-            throw err;
-        }
+        const files = this.sweepEntries(sessionId);
         const out = [];
         for (const file of files) {
             if (file.endsWith(MARK_SUFFIX))
@@ -163,116 +216,80 @@ export class FileSessionPolicyStore {
             if (!file.endsWith(".json"))
                 continue;
             const full = join(this.dir, file);
-            let raw;
-            try {
-                raw = readFileSync(full, "utf8");
-            }
-            catch (err) {
-                if (err.code !== "ENOENT") {
-                    this.disclose({ sessionId, path: full, reason: `read failed (non-ENOENT): ${err.message}` });
-                }
+            const judged = this.readRowFile(full);
+            if (judged === null)
                 continue;
-            }
-            const judged = judgeSessionPolicyRowObject(raw);
-            if ("corrupt" in judged) {
-                this.disclose({ sessionId, path: full, reason: judged.corrupt.reason });
+            const { owner } = this.ownerOf(sessionId, file, "row" in judged ? judged.row : undefined);
+            if (owner === undefined) {
+                this.disclose({ sessionId, path: full, reason: "corrupt" in judged ? judged.corrupt.reason : "session metadata is not a string" });
                 continue;
             }
-            if (typeof judged.row.__sid !== "string") {
-                this.disclose({ sessionId, path: full, reason: "session metadata is not a string" });
-                continue;
-            }
-            if (judged.row.__sid !== sessionId)
+            if (owner.sessionId !== sessionId)
                 continue;
+            if ("corrupt" in judged)
+                this.refuseDamaged(sessionId, undefined, full, judged.corrupt.grade, judged.corrupt.reason);
+            if (typeof judged.row.__sid !== "string")
+                this.refuseDamaged(sessionId, undefined, full, "malformed", "session metadata is not a string");
             const shaped = judgeSessionPolicyRowShape(judged.row);
-            if ("corrupt" in shaped) {
-                this.disclose({ sessionId, path: full, reason: shaped.corrupt.reason });
-                continue;
-            }
+            if ("corrupt" in shaped)
+                this.refuseDamaged(sessionId, undefined, full, shaped.corrupt.grade, shaped.corrupt.reason);
             const attributed = judged.row.__principal;
             if (attributed !== undefined && attributed !== null && typeof attributed !== "string") {
-                this.disclose({ sessionId, path: full, reason: "principal metadata is not a string" });
-                continue;
+                this.refuseDamaged(sessionId, undefined, full, "malformed", "principal metadata is not a string");
             }
             out.push({ principal: attributed ?? undefined, rules: shaped.rules });
         }
         return out;
     }
     async deleteBySession(sessionId) {
-        let files;
-        try {
-            files = readdirSync(this.dir);
-        }
-        catch (err) {
-            if (err.code === "ENOENT")
-                return;
-            throw err;
-        }
-        for (const file of files) {
+        for (const file of this.sweepEntries(sessionId)) {
             if (file.endsWith(MARK_SUFFIX))
                 continue;
             if (!file.endsWith(".json"))
                 continue;
-            let raw;
-            try {
-                raw = readFileSync(join(this.dir, file), "utf8");
-            }
-            catch {
+            const full = join(this.dir, file);
+            const judged = this.readRowFile(full);
+            if (judged === null)
                 continue;
-            }
-            const judged = judgeSessionPolicyRowObject(raw);
-            if ("corrupt" in judged) {
-                if (judged.corrupt.grade !== "unparseable")
-                    continue;
-                const tornMarkPath = join(this.dir, `${file.slice(0, -".json".length)}${MARK_SUFFIX}`);
-                try {
-                    const tornMark = readSessionPolicyMark(tornMarkPath);
-                    if (tornMark === null) {
-                        this.writeMark(tornMarkPath, { __hwm: 0, __gen: 0, __lineage: "lost" });
-                        this.disclose({ sessionId, path: join(this.dir, file), reason: "erase purged a torn row that had no high-water mark: the key's lineage is lost, writes are refused until the mark is deleted" });
-                    }
-                    else {
-                        this.writeMark(tornMarkPath, { ...tornMark, __gen: (tornMark.__gen ?? 0) + 1 });
-                    }
-                }
-                catch (err) {
-                    if (!(err instanceof SessionPolicyError))
-                        throw err;
-                    this.disclose({ sessionId, path: join(this.dir, file), reason: `erase purged a torn row whose high-water mark is corrupt (${err.message}); the mark is left for the operator` });
-                }
-                try {
-                    unlinkSync(join(this.dir, file));
-                }
-                catch (err) {
-                    if (err.code !== "ENOENT")
-                        throw err;
-                }
+            const row = "row" in judged ? judged.row : undefined;
+            const markPath = join(this.dir, `${file.slice(0, -".json".length)}${MARK_SUFFIX}`);
+            const { owner, markRead } = this.ownerOf(sessionId, file, row);
+            if (owner !== undefined) {
+                if (owner.sessionId === sessionId)
+                    this.eraseRow(full, markPath, sessionId, owner.principal ?? null, row, markRead);
                 continue;
             }
-            const row = judged.row;
-            if (row.__sid !== sessionId)
+            if (!("corrupt" in judged) || judged.corrupt.grade !== "unparseable")
                 continue;
-            const markPath = join(this.dir, `${file.slice(0, -".json".length)}${MARK_SUFFIX}`);
-            let mark;
-            try {
-                mark = readSessionPolicyMark(markPath);
-            }
-            catch (err) {
-                if (!(err instanceof SessionPolicyError))
-                    throw err;
-                mark = undefined;
+            const tornRead = markRead ?? this.sweepMark(sessionId, markPath);
+            if ("corrupt" in tornRead) {
+                this.disclose({ sessionId, path: markPath, reason: `erase purged a torn row whose high-water mark is corrupt (it ${tornRead.corrupt.reason}); the mark is left for the operator` });
             }
-            if (mark !== undefined) {
-                const rowRev = typeof row.rev === "number" && Number.isFinite(row.rev) ? row.rev : 0;
-                this.writeMarkFile(markPath, Math.max(mark?.__hwm ?? 0, rowRev), sessionId, row.__principal ?? null, (mark?.__gen ?? 0) + 1);
+            else if (tornRead.mark === null) {
+                this.writeMark(markPath, { __hwm: 0, __gen: 0, __lineage: "lost" });
+                this.disclose({ sessionId, path: full, reason: "erase purged a torn row that had no high-water mark: the key's lineage is lost, writes are refused until the mark is deleted" });
             }
-            try {
-                unlinkSync(join(this.dir, file));
-            }
-            catch (err) {
-                if (err.code !== "ENOENT")
-                    throw err;
+            else {
+                this.writeMark(markPath, { ...tornRead.mark, __gen: (tornRead.mark.__gen ?? 0) + 1 });
             }
+            unlinkIfPresent(full);
+        }
+    }
+    eraseRow(full, markPath, sessionId, principal, row, observed) {
+        const markRead = observed ?? this.sweepMark(sessionId, markPath);
+        if (!("corrupt" in markRead)) {
+            const rowRev = typeof row?.rev === "number" && Number.isFinite(row.rev) ? row.rev : 0;
+            this.writeMarkFile(markPath, Math.max(markRead.mark?.__hwm ?? 0, rowRev), sessionId, principal, (markRead.mark?.__gen ?? 0) + 1);
         }
+        unlinkIfPresent(full);
+    }
+}
+function unlinkIfPresent(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
     }
 }

package/dist/stores/file/task-list-store.d.ts

@@ -1,4 +1,5 @@
 import type { TaskListStore } from "../../tools/task-list.js";
+import { type CorruptReadInfo } from "./corrupt-read-sink.js";
 export declare function createFileTaskListStore(root: string, opts?: {
     /**
      * The DATA ROOT whose adoption marker gates construction (design/183 I6). Most of the file family
@@ -13,4 +14,8 @@ export declare function createFileTaskListStore(root: string, opts?: {
      * on `adoptLocalDataRoot` lists that default among the seams it does not cover.
      */
     dataRoot?: string;
+    /** Disclosure sink for a task-list document that is present but cannot be read as one: it fires WITH the
+     *  refusal and is the only carrier of the file's location (the refusal's message names none). Never fires on
+     *  plain absence. Swallow-guarded: a throwing sink cannot change the refusal. */
+    onCorruptRead?: (info: CorruptReadInfo) => void;
 }): TaskListStore;

package/dist/stores/file/task-list-store.js

@@ -3,6 +3,7 @@ import { readFileSync } from "node:fs";
 import { assertJsonMetadata, normalizeTaskShape } from "../../tools/task-list.js";
 import { canonicalStoreKey, atomicWriteFile, ensureDir } from "./fs-atomic.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
+import { guardCorruptSink } from "./corrupt-read-sink.js";
 const dirLocks = new Map();
 export function createFileTaskListStore(root, opts) {
     const dir = resolve(root);
@@ -12,6 +13,11 @@ export function createFileTaskListStore(root, opts) {
     ensureDir(dir);
     const lockKey = canonicalStoreKey(dir);
     ensureDir(tmpDir);
+    const disclose = guardCorruptSink(opts?.onCorruptRead);
+    const refuseDamaged = (fault) => {
+        disclose?.({ kind: "file", path, reason: fault });
+        throw new Error(`file task-list store: the task list document ${fault} — refusing rather than start an empty list, which would hand out again the task ids it reserved. Repair it: fix the file, or delete it (deleting it = an empty task list whose ids restart at 1). The file's location is reported to the store's corrupt-read disclosure (onCorruptRead), not in this message.`);
+    };
     const load = () => {
         let raw;
         try {
@@ -20,14 +26,22 @@ export function createFileTaskListStore(root, opts) {
         catch (err) {
             if (err.code === "ENOENT")
                 return { version: 1, nextId: 1, tasks: {} };
-            throw err;
+            return refuseDamaged(`could not be read (${err.code ?? err.name})`);
         }
         if (raw === "")
             return { version: 1, nextId: 1, tasks: {} };
-        const doc = JSON.parse(raw);
-        if (typeof doc.nextId !== "number" || typeof doc.tasks !== "object" || doc.tasks === null) {
-            throw new Error(`file task-list store: corrupt document at ${path}`);
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return refuseDamaged("is not valid JSON (torn write?)");
         }
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+            return refuseDamaged("is not a JSON object");
+        const doc = parsed;
+        if (typeof doc.nextId !== "number" || typeof doc.tasks !== "object" || doc.tasks === null)
+            return refuseDamaged("carries no numeric nextId or no tasks map");
         return doc;
     };
     const save = (doc) => {

package/dist/stores/file/usage-window-store.d.ts

@@ -1,4 +1,11 @@
 import { type UsageWindow, type UsageWindowReading, type UsageWindowStore } from "../../core/usage-window-store.js";
+import { type CorruptReadInfo } from "./corrupt-read-sink.js";
+export interface FileUsageWindowStoreOptions {
+    /** Disclosure sink for a ledger that is present but cannot be read as one: it fires WITH the refusal and is the
+     *  only carrier of the file's location (the refusal's message, which reaches a run's failure text, names none).
+     *  Never fires on plain absence. Swallow-guarded: a throwing sink cannot change the refusal. */
+    onCorruptRead?: (info: CorruptReadInfo) => void;
+}
 /**
  * design/164 件五 — file-backed {@link UsageWindowStore}: ONE JSON record per governed key, semantics
  * identical to `InMemoryUsageWindowStore` BY CONSTRUCTION (both are shells around the same pure
@@ -17,7 +24,8 @@ import { type UsageWindow, type UsageWindowReading, type UsageWindowStore } from
  */
 export declare class FileUsageWindowStore implements UsageWindowStore {
     private readonly dir;
-    constructor(root: string);
+    private readonly onCorruptRead;
+    constructor(root: string, opts?: FileUsageWindowStoreOptions);
     /** key → a safe, INJECTIVE filename (`sanitizeScope` appends the full sha256 of the raw key, so two
      *  distinct principals can never share a ledger file). */
     private pathFor;

package/dist/stores/file/usage-window-store.js

@@ -3,40 +3,30 @@ import { join } from "node:path";
 import { chargeUsageRecord, readUsageRecord, EMPTY_USAGE_WINDOW_RECORD, } from "../../core/usage-window-store.js";
 import { atomicWriteFile, ensureDir, sanitizeScope } from "./fs-atomic.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
+import { guardCorruptSink } from "./corrupt-read-sink.js";
 export class FileUsageWindowStore {
     dir;
-    constructor(root) {
+    onCorruptRead;
+    constructor(root, opts) {
         assertAdoptionBootGate(root, "FileUsageWindowStore");
         this.dir = join(root, "usage-windows");
         ensureDir(this.dir);
+        this.onCorruptRead = guardCorruptSink(opts?.onCorruptRead);
     }
     pathFor(key) {
         return join(this.dir, `${sanitizeScope(key)}.json`);
     }
     loadRecord(key) {
         const path = this.pathFor(key);
-        let raw;
         try {
-            raw = readFileSync(path, "utf8");
+            return judgeRecord(path);
         }
         catch (err) {
-            if (err.code === "ENOENT")
-                return EMPTY_USAGE_WINDOW_RECORD;
-            throw err;
+            if (!(err instanceof LedgerFault))
+                throw err;
+            this.onCorruptRead?.({ kind: "file", path, reason: err.message });
+            throw corrupt(key, err.message);
         }
-        let parsed;
-        try {
-            parsed = JSON.parse(raw);
-        }
-        catch {
-            throw corrupt(path, "unparseable JSON (torn/zero-byte write?)");
-        }
-        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
-            throw corrupt(path, "not a JSON object");
-        const rec = parsed;
-        const slots = validateSlots(rec.slots, path);
-        const buckets = validateBuckets(rec.buckets, path);
-        return { slots, buckets };
     }
     async charge(key, tokens, at, windows, costMicroUsd) {
         const next = chargeUsageRecord(this.loadRecord(key), tokens, at, windows, costMicroUsd);
@@ -46,28 +36,52 @@ export class FileUsageWindowStore {
         return readUsageRecord(this.loadRecord(key), windows, now);
     }
 }
-function corrupt(path, reason) {
-    const e = new Error(`usage-window ledger at ${path} is unreadable (${reason}). Refused rather than treated as empty: an unreadable ceiling would grant the key an unlimited, silent allowance.`);
+class LedgerFault extends Error {
+}
+function judgeRecord(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return EMPTY_USAGE_WINDOW_RECORD;
+        throw new LedgerFault(`read failed (${err.code ?? err.name})`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new LedgerFault("unparseable JSON (torn/zero-byte write?)");
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new LedgerFault("not a JSON object");
+    const rec = parsed;
+    return { slots: validateSlots(rec.slots), buckets: validateBuckets(rec.buckets) };
+}
+function corrupt(key, reason) {
+    const e = new Error(`usage-window ledger for key ${JSON.stringify(key)} is unreadable (${reason}). Refused rather than treated as empty: an unreadable ceiling would grant the key an unlimited, silent allowance. Repair it: fix the file, or delete it (deleting it = no usage recorded for the key). The file's location is reported to the store's corrupt-read disclosure (onCorruptRead), not in this message.`);
     e.code = "usage_window.store_corrupt";
     return e;
 }
-function validateSlots(value, path) {
+function validateSlots(value) {
     if (value === undefined)
         return [];
     if (!Array.isArray(value))
-        throw corrupt(path, "`slots` is not an array");
+        throw new LedgerFault("`slots` is not an array");
     return value.map((s) => {
         if (s === null || typeof s !== "object")
-            throw corrupt(path, "`slots` entry is not an object");
+            throw new LedgerFault("`slots` entry is not an object");
         const { at, tokens, costMicroUsd, costUnknown } = s;
         if (typeof at !== "number" || !Number.isFinite(at) || typeof tokens !== "number" || !Number.isFinite(tokens)) {
-            throw corrupt(path, "`slots` entry has a non-numeric `at`/`tokens`");
+            throw new LedgerFault("`slots` entry has a non-numeric `at`/`tokens`");
         }
         if (costMicroUsd !== undefined && (typeof costMicroUsd !== "number" || !Number.isFinite(costMicroUsd))) {
-            throw corrupt(path, "`slots` entry has a non-numeric `costMicroUsd`");
+            throw new LedgerFault("`slots` entry has a non-numeric `costMicroUsd`");
         }
         if (costUnknown !== undefined && costUnknown !== true)
-            throw corrupt(path, "`slots` entry has a `costUnknown` that is not `true`");
+            throw new LedgerFault("`slots` entry has a `costUnknown` that is not `true`");
         return {
             at,
             tokens,
@@ -76,14 +90,14 @@ function validateSlots(value, path) {
         };
     });
 }
-function validateBuckets(value, path) {
+function validateBuckets(value) {
     if (value === undefined)
         return [];
     if (!Array.isArray(value))
-        throw corrupt(path, "`buckets` is not an array");
+        throw new LedgerFault("`buckets` is not an array");
     return value.map((b) => {
         if (b === null || typeof b !== "object")
-            throw corrupt(path, "`buckets` entry is not an object");
+            throw new LedgerFault("`buckets` entry is not an object");
         const { windowMs, openedAt, tokens, costMicroUsd, costUnknown } = b;
         if (typeof windowMs !== "number" ||
             !Number.isFinite(windowMs) ||
@@ -91,13 +105,13 @@ function validateBuckets(value, path) {
             !Number.isFinite(openedAt) ||
             typeof tokens !== "number" ||
             !Number.isFinite(tokens)) {
-            throw corrupt(path, "`buckets` entry has a non-numeric `windowMs`/`openedAt`/`tokens`");
+            throw new LedgerFault("`buckets` entry has a non-numeric `windowMs`/`openedAt`/`tokens`");
         }
         if (costMicroUsd !== undefined && (typeof costMicroUsd !== "number" || !Number.isFinite(costMicroUsd))) {
-            throw corrupt(path, "`buckets` entry has a non-numeric `costMicroUsd`");
+            throw new LedgerFault("`buckets` entry has a non-numeric `costMicroUsd`");
         }
         if (costUnknown !== undefined && costUnknown !== true)
-            throw corrupt(path, "`buckets` entry has a `costUnknown` that is not `true`");
+            throw new LedgerFault("`buckets` entry has a `costUnknown` that is not `true`");
         return {
             windowMs,
             openedAt,

package/dist/tools/fs/safety.d.ts

@@ -5,7 +5,7 @@ import { protectivePathTargetOf, type ToolCallLike } from "../../core/tool-regis
 /**
  * CC parity: Read/Edit/Write take the file path as `file_path`. Read the target the same way
  * EVERYWHERE the path is consumed from a tool-call's args — not just the tool body but ALSO every gate that
- * extracts the write target to confine it (sensitive-path, skill allowPaths, session allowDirs). A gate that only
+ * extracts the write target to confine it (sensitive-path, session allowDirs, the fs-write gate). A gate that only
  * read `args.path` would see `undefined` for a `file_path` call and either fail-OPEN (circumvent the guard — a real
  * hole) or fail-closed (deny a legitimate write). Single source.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.40.1",
+  "version": "7.41.1",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",