crewly 1.20.198 → 1.20.199

package/dist/backend/backend/src/utils/file-io.utils.d.ts

@@ -13,8 +13,37 @@
  */
 export interface FileIOLogger {
     warn(message: string, meta?: Record<string, unknown>): void;
+    error?(message: string, meta?: Record<string, unknown>): void;
     debug?(message: string, meta?: Record<string, unknown>): void;
 }
+/**
+ * A JSON store file exists but cannot be read or parsed, AND it could not be
+ * copied aside. The caller must not overwrite it: that would destroy the only
+ * copy of whatever it still holds (the 2026-10-03 token-ledger loss).
+ */
+export declare class CorruptJsonFileError extends Error {
+    /** The store file that is bad */
+    readonly filePath: string;
+    /** Why it could not be used (parse or read error) */
+    readonly reason: string;
+    /**
+     * @param filePath - The bad store file
+     * @param reason - Parse / read error text
+     * @param copyError - Why copying it aside failed
+     */
+    constructor(filePath: string, reason: string, copyError: string);
+}
+/** Result of {@link readJsonStore} / {@link readJsonStoreSync}. */
+export type JsonStoreRead<T> = {
+    status: 'missing';
+} | {
+    status: 'ok';
+    data: T;
+} | {
+    status: 'quarantined';
+    quarantinedTo: string;
+    reason: string;
+};
 /**
  * Ensures a directory exists, creating it recursively if necessary.
  *
@@ -62,12 +91,96 @@ export declare function atomicWriteFile(filePath: string, content: string): Prom
  * @param data - Value to serialize (via `JSON.stringify`)
  */
 export declare function atomicWriteJson<T>(filePath: string, data: T): Promise<void>;
+/**
+ * Synchronous {@link atomicWriteFile} for stores that persist synchronously
+ * (temp file in the same directory → fsync → rename).
+ *
+ * A failure (ENOSPC, EACCES) leaves the destination untouched, removes the
+ * temp file and rethrows. No in-process lock: a synchronous call cannot
+ * interleave with another one in the same process.
+ *
+ * **Precondition:** the parent directory must already exist.
+ *
+ * @param filePath - Destination file path
+ * @param content - String content to write
+ */
+export declare function atomicWriteFileSync(filePath: string, content: string): void;
+/**
+ * Where a bad store file is copied: `<file>.corrupt-<ISO timestamp>`
+ * (colons and dots replaced so the name is valid everywhere).
+ *
+ * @param filePath - Store file
+ * @param now - Clock (tests)
+ * @returns Quarantine path
+ */
+export declare function quarantinePathFor(filePath: string, now?: Date): string;
+/**
+ * Copy a store file that cannot be used to `<file>.corrupt-<ts>` and log an
+ * error. After this returns, the caller may start empty and overwrite the
+ * original.
+ *
+ * @param filePath - The bad store file
+ * @param reason - Why it cannot be used
+ * @param logger - Optional logger
+ * @returns The quarantine path
+ * @throws CorruptJsonFileError when the copy fails — the caller must then NOT
+ *   overwrite the original
+ */
+export declare function quarantineCorruptFile(filePath: string, reason: string, logger?: FileIOLogger): Promise<string>;
+/**
+ * Synchronous {@link quarantineCorruptFile}.
+ *
+ * @param filePath - The bad store file
+ * @param reason - Why it cannot be used
+ * @param logger - Optional logger
+ * @returns The quarantine path
+ * @throws CorruptJsonFileError when the copy fails
+ */
+export declare function quarantineCorruptFileSync(filePath: string, reason: string, logger?: FileIOLogger): string;
+/**
+ * Read a JSON store, telling "missing" apart from "bad".
+ *
+ * - missing (`ENOENT`) → `{ status: 'missing' }` — start fresh;
+ * - parses (and passes `validate`) → `{ status: 'ok', data }`;
+ * - invalid JSON, or rejected by `validate` → copied to
+ *   `<file>.corrupt-<ts>`, error logged, `{ status: 'quarantined' }`;
+ * - any other read error (EMFILE, EIO, EACCES…) → rethrown. The file may be
+ *   good; the caller must not start empty and write over it.
+ *
+ * @param filePath - Store file
+ * @param options.validate - Optional shape check; return an error text to reject
+ * @param options.logger - Optional logger
+ * @returns What was found
+ * @throws CorruptJsonFileError when the file is bad and could not be copied aside
+ * @throws The read error itself for anything but ENOENT
+ */
+export declare function readJsonStore<T>(filePath: string, options?: {
+    validate?: (data: unknown) => string | null;
+    logger?: FileIOLogger;
+}): Promise<JsonStoreRead<T>>;
+/**
+ * Synchronous {@link readJsonStore}.
+ *
+ * @param filePath - Store file
+ * @param options.validate - Optional shape check; return an error text to reject
+ * @param options.logger - Optional logger
+ * @returns What was found
+ * @throws CorruptJsonFileError when the file is bad and could not be copied aside
+ * @throws The read error itself for anything but ENOENT
+ */
+export declare function readJsonStoreSync<T>(filePath: string, options?: {
+    validate?: (data: unknown) => string | null;
+    logger?: FileIOLogger;
+}): JsonStoreRead<T>;
 /**
  * Read and parse a JSON file safely.
  *
  * - On `ENOENT` → returns `defaultValue` silently.
- * - On parse error → backs up the corrupt file as `<path>.corrupt.<ts>`
+ * - On parse error → backs up the corrupt file as `<path>.corrupt-<ts>`
  *   and returns `defaultValue`.
+ * - If that backup fails (a full disk, permissions) → throws
+ *   {@link CorruptJsonFileError}. Returning the default would let the caller
+ *   write it over the only copy of the data.
  *
  * @param filePath - Path to the JSON file
  * @param defaultValue - Value to return when the file is missing or corrupt

package/dist/backend/backend/src/utils/file-io.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-io.utils.d.ts","sourceRoot":"","sources":["../../../../../backend/src/utils/file-io.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC/D;AAaD;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9D;AAuCD;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAE9F;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAEnG;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBtF;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAEjF;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,CAAC,CAAC,CAyB1G;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,cAAc,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,EAC9C,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,CAAC,EACf,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EACpC,MAAM,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC,CAAC,CAAC,CAUZ;AAMD;;GAEG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAGrC"}
+{"version":3,"file":"file-io.utils.d.ts","sourceRoot":"","sources":["../../../../../backend/src/utils/file-io.utils.ts"],"names":[],"mappings":"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"}

package/dist/backend/backend/src/utils/file-io.utils.js

@@ -8,6 +8,53 @@
  * @module utils/file-io.utils
  */
 import * as fs from 'fs/promises';
+import * as fsSync from 'fs';
+/**
+ * A JSON store file exists but cannot be read or parsed, AND it could not be
+ * copied aside. The caller must not overwrite it: that would destroy the only
+ * copy of whatever it still holds (the 2026-10-03 token-ledger loss).
+ */
+export class CorruptJsonFileError extends Error {
+    /** The store file that is bad */
+    filePath;
+    /** Why it could not be used (parse or read error) */
+    reason;
+    /**
+     * @param filePath - The bad store file
+     * @param reason - Parse / read error text
+     * @param copyError - Why copying it aside failed
+     */
+    constructor(filePath, reason, copyError) {
+        super(`Store file ${filePath} is unreadable (${reason}) and could not be set aside (${copyError}); refusing to overwrite it`);
+        this.name = 'CorruptJsonFileError';
+        this.filePath = filePath;
+        this.reason = reason;
+    }
+}
+/**
+ * Error text of an unknown thrown value.
+ *
+ * @param err - Thrown value
+ * @returns Message
+ */
+function errText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Log at error level when the logger has one, else warn.
+ *
+ * @param logger - Optional logger
+ * @param message - Message
+ * @param meta - Metadata
+ */
+function logError(logger, message, meta) {
+    if (!logger)
+        return;
+    if (logger.error)
+        logger.error(message, meta);
+    else
+        logger.warn(message, meta);
+}
 // ──────────────────────────────────────────────────────────────────────
 //  Module-level lock maps (singleton per process — no class needed)
 // ──────────────────────────────────────────────────────────────────────
@@ -125,6 +172,185 @@ export async function atomicWriteFile(filePath, content) {
 export async function atomicWriteJson(filePath, data) {
     await atomicWriteFile(filePath, JSON.stringify(data, null, 2));
 }
+/**
+ * Synchronous {@link atomicWriteFile} for stores that persist synchronously
+ * (temp file in the same directory → fsync → rename).
+ *
+ * A failure (ENOSPC, EACCES) leaves the destination untouched, removes the
+ * temp file and rethrows. No in-process lock: a synchronous call cannot
+ * interleave with another one in the same process.
+ *
+ * **Precondition:** the parent directory must already exist.
+ *
+ * @param filePath - Destination file path
+ * @param content - String content to write
+ */
+export function atomicWriteFileSync(filePath, content) {
+    const tempPath = `${filePath}.tmp.${Date.now()}.${Math.random().toString(36).substring(2)}`;
+    let fd = null;
+    try {
+        fd = fsSync.openSync(tempPath, 'w');
+        fsSync.writeFileSync(fd, content, 'utf8');
+        fsSync.fsyncSync(fd);
+        fsSync.closeSync(fd);
+        fd = null;
+        fsSync.renameSync(tempPath, filePath);
+    }
+    catch (error) {
+        if (fd !== null) {
+            try {
+                fsSync.closeSync(fd);
+            }
+            catch { /* ignore */ }
+        }
+        try {
+            fsSync.unlinkSync(tempPath);
+        }
+        catch { /* ignore */ }
+        throw error;
+    }
+}
+// ──────────────────────────────────────────────────────────────────────
+//  Corrupt-store quarantine
+// ──────────────────────────────────────────────────────────────────────
+/**
+ * Where a bad store file is copied: `<file>.corrupt-<ISO timestamp>`
+ * (colons and dots replaced so the name is valid everywhere).
+ *
+ * @param filePath - Store file
+ * @param now - Clock (tests)
+ * @returns Quarantine path
+ */
+export function quarantinePathFor(filePath, now = new Date()) {
+    return `${filePath}.corrupt-${now.toISOString().replace(/[:.]/g, '-')}`;
+}
+/**
+ * Copy a store file that cannot be used to `<file>.corrupt-<ts>` and log an
+ * error. After this returns, the caller may start empty and overwrite the
+ * original.
+ *
+ * @param filePath - The bad store file
+ * @param reason - Why it cannot be used
+ * @param logger - Optional logger
+ * @returns The quarantine path
+ * @throws CorruptJsonFileError when the copy fails — the caller must then NOT
+ *   overwrite the original
+ */
+export async function quarantineCorruptFile(filePath, reason, logger) {
+    const target = quarantinePathFor(filePath);
+    try {
+        await fs.copyFile(filePath, target);
+    }
+    catch (copyErr) {
+        logError(logger, 'Store file is unreadable and could not be set aside; it will not be overwritten', {
+            filePath, reason, copyError: errText(copyErr),
+        });
+        throw new CorruptJsonFileError(filePath, reason, errText(copyErr));
+    }
+    logError(logger, 'Store file was unreadable; copied aside and starting empty', { filePath, quarantinedTo: target, reason });
+    return target;
+}
+/**
+ * Synchronous {@link quarantineCorruptFile}.
+ *
+ * @param filePath - The bad store file
+ * @param reason - Why it cannot be used
+ * @param logger - Optional logger
+ * @returns The quarantine path
+ * @throws CorruptJsonFileError when the copy fails
+ */
+export function quarantineCorruptFileSync(filePath, reason, logger) {
+    const target = quarantinePathFor(filePath);
+    try {
+        fsSync.copyFileSync(filePath, target);
+    }
+    catch (copyErr) {
+        logError(logger, 'Store file is unreadable and could not be set aside; it will not be overwritten', {
+            filePath, reason, copyError: errText(copyErr),
+        });
+        throw new CorruptJsonFileError(filePath, reason, errText(copyErr));
+    }
+    logError(logger, 'Store file was unreadable; copied aside and starting empty', { filePath, quarantinedTo: target, reason });
+    return target;
+}
+/**
+ * Read a JSON store, telling "missing" apart from "bad".
+ *
+ * - missing (`ENOENT`) → `{ status: 'missing' }` — start fresh;
+ * - parses (and passes `validate`) → `{ status: 'ok', data }`;
+ * - invalid JSON, or rejected by `validate` → copied to
+ *   `<file>.corrupt-<ts>`, error logged, `{ status: 'quarantined' }`;
+ * - any other read error (EMFILE, EIO, EACCES…) → rethrown. The file may be
+ *   good; the caller must not start empty and write over it.
+ *
+ * @param filePath - Store file
+ * @param options.validate - Optional shape check; return an error text to reject
+ * @param options.logger - Optional logger
+ * @returns What was found
+ * @throws CorruptJsonFileError when the file is bad and could not be copied aside
+ * @throws The read error itself for anything but ENOENT
+ */
+export async function readJsonStore(filePath, options = {}) {
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, 'utf-8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { status: 'missing' };
+        // EMFILE, EIO, EACCES…: the file may be perfectly good. Never set it
+        // aside (the store would start empty and overwrite it); let the caller
+        // refuse to write until a read succeeds.
+        throw err;
+    }
+    const parsed = parseStore(raw, options.validate);
+    if (parsed.ok)
+        return { status: 'ok', data: parsed.data };
+    return { status: 'quarantined', quarantinedTo: await quarantineCorruptFile(filePath, parsed.reason, options.logger), reason: parsed.reason };
+}
+/**
+ * Synchronous {@link readJsonStore}.
+ *
+ * @param filePath - Store file
+ * @param options.validate - Optional shape check; return an error text to reject
+ * @param options.logger - Optional logger
+ * @returns What was found
+ * @throws CorruptJsonFileError when the file is bad and could not be copied aside
+ * @throws The read error itself for anything but ENOENT
+ */
+export function readJsonStoreSync(filePath, options = {}) {
+    let raw;
+    try {
+        raw = fsSync.readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { status: 'missing' };
+        throw err; // see readJsonStore: a read error is not corruption
+    }
+    const parsed = parseStore(raw, options.validate);
+    if (parsed.ok)
+        return { status: 'ok', data: parsed.data };
+    return { status: 'quarantined', quarantinedTo: quarantineCorruptFileSync(filePath, parsed.reason, options.logger), reason: parsed.reason };
+}
+/**
+ * Parse store text and run the optional shape check.
+ *
+ * @param raw - File text
+ * @param validate - Optional shape check
+ * @returns Parsed data, or why it was rejected
+ */
+function parseStore(raw, validate) {
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch (err) {
+        return { ok: false, reason: `invalid JSON (${raw.length} bytes): ${errText(err)}` };
+    }
+    const rejected = validate?.(data) ?? null;
+    return rejected ? { ok: false, reason: rejected } : { ok: true, data };
+}
 // ──────────────────────────────────────────────────────────────────────
 //  Safe read
 // ──────────────────────────────────────────────────────────────────────
@@ -132,8 +358,11 @@ export async function atomicWriteJson(filePath, data) {
  * Read and parse a JSON file safely.
  *
  * - On `ENOENT` → returns `defaultValue` silently.
- * - On parse error → backs up the corrupt file as `<path>.corrupt.<ts>`
+ * - On parse error → backs up the corrupt file as `<path>.corrupt-<ts>`
  *   and returns `defaultValue`.
+ * - If that backup fails (a full disk, permissions) → throws
+ *   {@link CorruptJsonFileError}. Returning the default would let the caller
+ *   write it over the only copy of the data.
  *
  * @param filePath - Path to the JSON file
  * @param defaultValue - Value to return when the file is missing or corrupt
@@ -155,15 +384,16 @@ export async function safeReadJson(filePath, defaultValue, logger) {
     try {
         return JSON.parse(raw);
     }
-    catch {
-        // Corrupt JSON — back up the file so we can debug later
-        const backupPath = `${filePath}.corrupt.${Date.now()}`;
+    catch (parseErr) {
+        // Corrupt JSON — back up the file before anyone can write over it
+        const backupPath = quarantinePathFor(filePath);
         try {
             await fs.copyFile(filePath, backupPath);
             logger?.warn('Backed up corrupt JSON file', { filePath, backupPath });
         }
-        catch {
-            logger?.warn('Failed to back up corrupt JSON file', { filePath });
+        catch (copyErr) {
+            logError(logger, 'Failed to back up corrupt JSON file; refusing to fall back to the default', { filePath });
+            throw new CorruptJsonFileError(filePath, `invalid JSON: ${errText(parseErr)}`, errText(copyErr));
         }
         return defaultValue;
     }

package/dist/backend/backend/src/utils/file-io.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"file-io.utils.js","sourceRoot":"","sources":["../../../../../backend/src/utils/file-io.utils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"file-io.utils.js","sourceRoot":"","sources":["../../../../../backend/src/utils/file-io.utils.ts"],"names":[],"mappings":"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"}

package/dist/backend/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "5e3c72b5643811738cd50a6c40a9572a57d5f099",
-  "builtAt": "2026-10-03T12:41:47.102Z"
+  "commit": "f843dd39cad10eeda2de8ca81f9ab78985f95af0",
+  "builtAt": "2026-10-03T13:09:32.583Z"
 }

package/dist/cli/backend/src/constants.d.ts

@@ -5696,6 +5696,22 @@ export declare const REPLY_ROUTING_CONSTANTS: {
     /** Decision ids (`D-12`) */
     readonly DECISION_PATTERN: RegExp;
 };
+/**
+ * Usage ledger backfill (`POST /api/system/usage/backfill`, owner only).
+ * specs/2026-10-03-usage-ledger-durability.md §Backfill
+ */
+export declare const USAGE_BACKFILL_CONSTANTS: {
+    /** Longest range one request may rebuild, in days */
+    readonly MAX_DAYS: 120;
+    /** Most ledger backup files one request may read */
+    readonly MAX_LEDGER_FILES: 10;
+    /** Largest ledger backup file read (the live ledger was 2.8 MB) */
+    readonly MAX_LEDGER_FILE_BYTES: number;
+    /** Names a ledger backup may have: `*.json`, `*.corrupt-*`, `*.corrupt.*`, `*.bak-*` */
+    readonly LEDGER_FILE_NAME_PATTERN: RegExp;
+    /** The one error a rejected ledger file gets: never file contents, never "missing" vs "unreadable" */
+    readonly LEDGER_FILE_ERROR: "not a usable ledger file";
+};
 /**
  * Daily token caps with a hard stop, team caps and temporary boosts
  * (specs/2026-10-02-spend-cap.md). The unit is TOKENS, not dollars (owner,