@caupulican/pi-adaptative 0.81.37 → 0.81.39

package/dist/core/util/atomic-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-file.d.ts","sourceRoot":"","sources":["../../../src/core/util/atomic-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAiEH,MAAM,WAAW,qBAAqB;IACrC;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iGAAiG;IACjG,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,sGAAsG;IACtG,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AA2ED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,CAAC,CAcrG;AAED,0GAA0G;AAC1G,wBAAsB,YAAY,CAAC,CAAC,EACnC,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EACxB,OAAO,CAAC,EAAE,qBAAqB,GAC7B,OAAO,CAAC,CAAC,CAAC,CAiBZ;AA6BD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAY3E;AAED,wDAAwD;AACxD,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAYtF","sourcesContent":["/**\n * Shared atomic-file helper: a single lock+tmp+rename implementation reused by every\n * on-disk store that does a read-modify-write against a JSON/text file. Modeled on the pattern\n * already proven in `memory/providers/file-store.ts` (proper-lockfile advisory lock + write-tmp-\n * then-rename); before this helper existed the pattern was copy-pasted per store, and most copies\n * were missing either the lock, the atomic write, or both.\n *\n * Two call shapes:\n *  - `withFileLock(Sync)` — hold an exclusive advisory lock across an arbitrary read-modify-write\n *    callback. The lock spans BOTH the read and the write, closing the classic RMW race where two\n *    writers each read the old content before either writes back.\n *  - `writeFileAtomic(Sync)` — write-tmp-then-rename. Used INSIDE a `withFileLock` callback (or\n *    standalone, for a pure overwrite that has no read step to race).\n *\n * Sync and async variants are both exported. Most existing stores expose a synchronous public API\n * called from hot, non-async paths (e.g. a per-token-stream perf sample), so the sync variant lets\n * them gain locking without forcing an async ripple through their callers; the async variant is for\n * call sites that are already async.\n */\n\nimport { randomUUID } from \"node:crypto\";\nimport { promises as fsPromises, mkdirSync, renameSync, unlinkSync, writeFileSync } from \"node:fs\";\nimport { dirname } from \"node:path\";\nimport lockfile from \"proper-lockfile\";\n\n/**\n * Bounded rename retry budget for the win32-only transient-rename handling below (see\n * {@link isTransientRenameErrorOnWin32}). Backoff doubles each attempt starting at\n * {@link RENAME_RETRY_MIN_TIMEOUT_MS} and capped at {@link RENAME_RETRY_MAX_TIMEOUT_MS}, mirroring\n * the doubling-backoff shape used for lock acquisition above. With {@link RENAME_RETRY_ATTEMPTS}\n * extra attempts (10, 20, 40, 80, ... capped at 200) the worst-case total wait is ~1.03s\n * (10+20+40+80+160+200+200+200+200 ~= 1110ms across 9 gaps), which comfortably covers the\n * millisecond-scale window Defender/the Windows Search indexer hold a freshly-written file open\n * without FILE_SHARE_DELETE before releasing it.\n */\nconst RENAME_RETRY_ATTEMPTS = 9;\nconst RENAME_RETRY_MIN_TIMEOUT_MS = 10;\nconst RENAME_RETRY_MAX_TIMEOUT_MS = 200;\n\n/**\n * On win32, antivirus (e.g. Windows Defender's real-time scanner) and the Windows Search indexer\n * routinely open a freshly-written file for a brief scan without `FILE_SHARE_DELETE`, which makes a\n * rename over/of that file fail transiently with EPERM/EACCES/EBUSY for a few milliseconds. This is\n * a well-documented platform semantic, not a bug in our write path — it's exactly why the\n * `graceful-fs` package ships its own win32 rename-retry wrapper. POSIX platforms never exhibit this\n * transient (a POSIX rename either succeeds or fails for a real, non-transient reason), so retry is\n * gated strictly to win32 to keep POSIX behavior byte-identical to a bare rename.\n */\nfunction isTransientRenameErrorOnWin32(err: unknown): boolean {\n\tif (process.platform !== \"win32\") return false;\n\tif (typeof err !== \"object\" || err === null) return false;\n\tconst code = (err as { code?: string }).code;\n\treturn code === \"EPERM\" || code === \"EACCES\" || code === \"EBUSY\";\n}\n\n/** Sync counterpart of the rename-retry policy; see {@link isTransientRenameErrorOnWin32}. */\nfunction renameSyncWithRetry(tmpPath: string, filePath: string): void {\n\tfor (let attempt = 0; attempt <= RENAME_RETRY_ATTEMPTS; attempt++) {\n\t\ttry {\n\t\t\trenameSync(tmpPath, filePath);\n\t\t\treturn;\n\t\t} catch (err) {\n\t\t\tif (!isTransientRenameErrorOnWin32(err) || attempt === RENAME_RETRY_ATTEMPTS) throw err;\n\t\t\tconst backoffMs = Math.min(RENAME_RETRY_MIN_TIMEOUT_MS * 2 ** attempt, RENAME_RETRY_MAX_TIMEOUT_MS);\n\t\t\tblockingSleepMs(backoffMs);\n\t\t}\n\t}\n}\n\n/** Async counterpart of the rename-retry policy; see {@link isTransientRenameErrorOnWin32}. */\nasync function renameWithRetry(tmpPath: string, filePath: string): Promise<void> {\n\tfor (let attempt = 0; attempt <= RENAME_RETRY_ATTEMPTS; attempt++) {\n\t\ttry {\n\t\t\tawait fsPromises.rename(tmpPath, filePath);\n\t\t\treturn;\n\t\t} catch (err) {\n\t\t\tif (!isTransientRenameErrorOnWin32(err) || attempt === RENAME_RETRY_ATTEMPTS) throw err;\n\t\t\tconst backoffMs = Math.min(RENAME_RETRY_MIN_TIMEOUT_MS * 2 ** attempt, RENAME_RETRY_MAX_TIMEOUT_MS);\n\t\t\tawait new Promise((resolve) => setTimeout(resolve, backoffMs));\n\t\t}\n\t}\n}\n\nexport interface AtomicFileLockOptions {\n\t/**\n\t * Bounded retry attempts while waiting for a lock already held elsewhere. Both variants use a\n\t * SHORT, capped backoff (see {@link RETRY_MIN_TIMEOUT_MS}/{@link RETRY_MAX_TIMEOUT_MS}) — these\n\t * stores' critical sections are sub-millisecond reads+writes of small JSON/text files, so\n\t * contention should clear in milliseconds, not the multi-second-to-31-second worst case\n\t * proper-lockfile's OWN default backoff produces for a bare numeric `retries` (its default\n\t * `minTimeout` is 1000ms with factor 2 — see node_modules/retry/lib/retry.js). Passing a bare\n\t * number straight through would turn brief contention into a multi-second stall on a hot path\n\t * (e.g. a per-token-stream perf sample), so both variants instead build an explicit short-backoff\n\t * `retry` options object.\n\t * - Async (`withFileLock`): forwarded as `{retries, minTimeout, maxTimeout}` to proper-lockfile.\n\t * - Sync (`withFileLockSync`): proper-lockfile's sync API REJECTS `retries > 0` outright (it\n\t *   requires the whole acquire flow to be synchronous — see proper-lockfile/lib/adapter.js\n\t *   `toSyncOptions`, which throws `ESYNC`). So the sync path implements its own bounded retry\n\t *   around single `lockfile.lockSync` attempts, blocking briefly between them (Atomics.wait) —\n\t *   callers are already fully synchronous fs code, so a short blocking wait on contention matches\n\t *   the existing execution model rather than introducing a new one.\n\t */\n\tretries?: number;\n\t/** Resolve symlinks before locking (proper-lockfile `realpath`); false matches file-store.ts. */\n\trealpath?: boolean;\n\t/** Lock staleness window in ms (proper-lockfile `stale`); omitted = proper-lockfile's own default. */\n\tstale?: number;\n}\n\nconst DEFAULT_RETRIES = 10;\nconst DEFAULT_REALPATH = false;\n/**\n * Capped doubling backoff shared by both variants — see {@link AtomicFileLockOptions.retries}.\n * With the current defaults (10 retries, 25ms floor, 500ms cap) the total worst-case contention\n * budget is ~3.3s (25+50+100+200+400+500+500+500+500+500), comfortably over the >= 2s floor this\n * needs to survive a loaded CI runner (e.g. the Windows CI mkdir/rmdir lock-directory churn under\n * two-real-OS-thread contention).\n */\nconst RETRY_MIN_TIMEOUT_MS = 25;\nconst RETRY_MAX_TIMEOUT_MS = 500;\nfunction ensureLockDirSync(filePath: string): void {\n\tmkdirSync(dirname(filePath), { recursive: true });\n}\n\nasync function ensureLockDir(filePath: string): Promise<void> {\n\tawait fsPromises.mkdir(dirname(filePath), { recursive: true });\n}\n\nfunction isLockedError(err: unknown): boolean {\n\tif (typeof err !== \"object\" || err === null) return false;\n\tconst code = (err as { code?: string }).code;\n\tif (code === \"ELOCKED\") return true;\n\t// On win32, mkdir-ing the lock directory can transiently surface EPERM (rather than the\n\t// expected EEXIST) when a previous incarnation of that directory is concurrently being\n\t// rmdir'd by the racing releaser — the mkdir lands mid-teardown and the OS reports \"operation\n\t// not permitted\" instead of \"already exists\". This is contention, not a real permissions\n\t// failure, so treat it identically to ELOCKED: retry with the existing backoff rather than\n\t// letting it escape as fatal. POSIX platforms don't exhibit this transient and keep surfacing\n\t// real EPERM (e.g. an actually unwritable directory) as fatal.\n\tif (code === \"EPERM\" && process.platform === \"win32\") return true;\n\treturn false;\n}\n\n/** Block the calling thread for `ms` without spinning the CPU (Atomics.wait on a private buffer). */\nfunction blockingSleepMs(ms: number): void {\n\tAtomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);\n}\n\n/**\n * Acquire a proper-lockfile sync lock with bounded retry on `ELOCKED` (proper-lockfile's sync API\n * itself forbids `retries > 0`; see {@link AtomicFileLockOptions.retries}).\n *\n * Backoff doubles each attempt (mirroring the `retry` module's own `factor: 2` default that the\n * async path gets for free from proper-lockfile), starting at {@link RETRY_MIN_TIMEOUT_MS} and\n * capped at {@link RETRY_MAX_TIMEOUT_MS}.\n *\n * This is budget PARITY between two implementations of the same lock-acquisition contract, not\n * flake-masking: `options.retries` (a count of RETRIES, i.e. attempts after the first) means the\n * same thing on both paths, so both must make `retries + 1` total acquisition attempts with the\n * same per-gap backoff schedule. The async path gets `retries + 1` attempts for free from the\n * `retry` module (it retries `options.retries` times after its initial attempt); the sync path\n * used to loop exactly `attempts` times total (one fewer gap, and one fewer attempt than the\n * async path for the same `retries` value), which under-budgeted it relative to its async sibling\n * and surfaced as spurious ELOCKED failures under real contention (e.g. two OS threads hammering\n * the same file, or mkdir/rmdir lock-directory churn on a loaded Windows CI runner).\n */\nfunction lockSyncWithRetry(filePath: string, options: AtomicFileLockOptions): () => void {\n\tconst attempts = Math.max(1, options.retries ?? DEFAULT_RETRIES) + 1;\n\tconst lockOptions = { realpath: options.realpath ?? DEFAULT_REALPATH, stale: options.stale };\n\tfor (let attempt = 1; attempt <= attempts; attempt++) {\n\t\ttry {\n\t\t\treturn lockfile.lockSync(filePath, lockOptions);\n\t\t} catch (err) {\n\t\t\tif (!isLockedError(err) || attempt === attempts) throw err;\n\t\t\tconst backoffMs = Math.min(RETRY_MIN_TIMEOUT_MS * 2 ** (attempt - 1), RETRY_MAX_TIMEOUT_MS);\n\t\t\tblockingSleepMs(backoffMs);\n\t\t}\n\t}\n\t// Unreachable (the loop always returns or throws), but keeps the function's return type honest.\n\tthrow new Error(`Failed to acquire lock for ${filePath}`);\n}\n\n/**\n * Hold an exclusive advisory lock on `filePath` for the duration of `fn` (sync). Always releases,\n * including when `fn` throws.\n */\nexport function withFileLockSync<T>(filePath: string, fn: () => T, options?: AtomicFileLockOptions): T {\n\tensureLockDirSync(filePath);\n\tconst release = lockSyncWithRetry(filePath, options ?? {});\n\ttry {\n\t\treturn fn();\n\t} finally {\n\t\t// A lock-cleanup failure must never mask fn()'s result (or replace fn()'s own thrown error) —\n\t\t// by this point fn() has already durably committed or failed on its own terms.\n\t\ttry {\n\t\t\trelease();\n\t\t} catch {\n\t\t\t// best-effort cleanup; a stale lock self-expires via proper-lockfile's `stale` window\n\t\t}\n\t}\n}\n\n/** Async counterpart of {@link withFileLockSync}. Always releases, including when `fn` throws/rejects. */\nexport async function withFileLock<T>(\n\tfilePath: string,\n\tfn: () => Promise<T> | T,\n\toptions?: AtomicFileLockOptions,\n): Promise<T> {\n\tawait ensureLockDir(filePath);\n\tconst release = await lockfile.lock(filePath, {\n\t\trealpath: options?.realpath ?? DEFAULT_REALPATH,\n\t\tretries: {\n\t\t\tretries: options?.retries ?? DEFAULT_RETRIES,\n\t\t\tminTimeout: RETRY_MIN_TIMEOUT_MS,\n\t\t\tmaxTimeout: RETRY_MAX_TIMEOUT_MS,\n\t\t},\n\t\tstale: options?.stale,\n\t});\n\ttry {\n\t\treturn await fn();\n\t} finally {\n\t\t// See {@link withFileLockSync} — cleanup failures must not mask fn()'s outcome.\n\t\tawait release().catch(() => {});\n\t}\n}\n\n/**\n * Write `content` to `filePath` via write-tmp-then-rename (sync); the rename is atomic on the same\n * filesystem, so a concurrent reader never observes a partially-written file. Does NOT itself lock —\n * call from inside {@link withFileLockSync} when the write follows a read that must not race another\n * writer's read+write; call standalone for an unconditional overwrite with no read step.\n */\nfunction temporaryPath(filePath: string): string {\n\treturn `${filePath}.${process.pid}.${randomUUID()}.tmp`;\n}\n\n/** Remove one invocation's temporary path without masking the original write/rename failure. */\nfunction removeTemporaryPathSync(tmpPath: string): void {\n\ttry {\n\t\tunlinkSync(tmpPath);\n\t} catch {\n\t\t// The rename may have consumed the path, or another failure may have prevented its creation.\n\t}\n}\n\nasync function removeTemporaryPath(tmpPath: string): Promise<void> {\n\ttry {\n\t\tawait fsPromises.unlink(tmpPath);\n\t} catch {\n\t\t// The rename may have consumed the path, or another failure may have prevented its creation.\n\t}\n}\n\nexport function writeFileAtomicSync(filePath: string, content: string): void {\n\tmkdirSync(dirname(filePath), { recursive: true });\n\tconst tmpPath = temporaryPath(filePath);\n\tlet renamed = false;\n\ttry {\n\t\t// `wx` makes a nonce collision harmless: never truncate another writer's temporary file.\n\t\twriteFileSync(tmpPath, content, { encoding: \"utf-8\", flag: \"wx\" });\n\t\trenameSyncWithRetry(tmpPath, filePath);\n\t\trenamed = true;\n\t} finally {\n\t\tif (!renamed) removeTemporaryPathSync(tmpPath);\n\t}\n}\n\n/** Async counterpart of {@link writeFileAtomicSync}. */\nexport async function writeFileAtomic(filePath: string, content: string): Promise<void> {\n\tawait fsPromises.mkdir(dirname(filePath), { recursive: true });\n\tconst tmpPath = temporaryPath(filePath);\n\tlet renamed = false;\n\ttry {\n\t\t// `wx` makes a nonce collision harmless: never truncate another writer's temporary file.\n\t\tawait fsPromises.writeFile(tmpPath, content, { encoding: \"utf-8\", flag: \"wx\" });\n\t\tawait renameWithRetry(tmpPath, filePath);\n\t\trenamed = true;\n\t} finally {\n\t\tif (!renamed) await removeTemporaryPath(tmpPath);\n\t}\n}\n"]}

package/dist/core/util/atomic-file.js

@@ -0,0 +1,255 @@
+/**
+ * Shared atomic-file helper: a single lock+tmp+rename implementation reused by every
+ * on-disk store that does a read-modify-write against a JSON/text file. Modeled on the pattern
+ * already proven in `memory/providers/file-store.ts` (proper-lockfile advisory lock + write-tmp-
+ * then-rename); before this helper existed the pattern was copy-pasted per store, and most copies
+ * were missing either the lock, the atomic write, or both.
+ *
+ * Two call shapes:
+ *  - `withFileLock(Sync)` — hold an exclusive advisory lock across an arbitrary read-modify-write
+ *    callback. The lock spans BOTH the read and the write, closing the classic RMW race where two
+ *    writers each read the old content before either writes back.
+ *  - `writeFileAtomic(Sync)` — write-tmp-then-rename. Used INSIDE a `withFileLock` callback (or
+ *    standalone, for a pure overwrite that has no read step to race).
+ *
+ * Sync and async variants are both exported. Most existing stores expose a synchronous public API
+ * called from hot, non-async paths (e.g. a per-token-stream perf sample), so the sync variant lets
+ * them gain locking without forcing an async ripple through their callers; the async variant is for
+ * call sites that are already async.
+ */
+import { randomUUID } from "node:crypto";
+import { promises as fsPromises, mkdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import lockfile from "proper-lockfile";
+/**
+ * Bounded rename retry budget for the win32-only transient-rename handling below (see
+ * {@link isTransientRenameErrorOnWin32}). Backoff doubles each attempt starting at
+ * {@link RENAME_RETRY_MIN_TIMEOUT_MS} and capped at {@link RENAME_RETRY_MAX_TIMEOUT_MS}, mirroring
+ * the doubling-backoff shape used for lock acquisition above. With {@link RENAME_RETRY_ATTEMPTS}
+ * extra attempts (10, 20, 40, 80, ... capped at 200) the worst-case total wait is ~1.03s
+ * (10+20+40+80+160+200+200+200+200 ~= 1110ms across 9 gaps), which comfortably covers the
+ * millisecond-scale window Defender/the Windows Search indexer hold a freshly-written file open
+ * without FILE_SHARE_DELETE before releasing it.
+ */
+const RENAME_RETRY_ATTEMPTS = 9;
+const RENAME_RETRY_MIN_TIMEOUT_MS = 10;
+const RENAME_RETRY_MAX_TIMEOUT_MS = 200;
+/**
+ * On win32, antivirus (e.g. Windows Defender's real-time scanner) and the Windows Search indexer
+ * routinely open a freshly-written file for a brief scan without `FILE_SHARE_DELETE`, which makes a
+ * rename over/of that file fail transiently with EPERM/EACCES/EBUSY for a few milliseconds. This is
+ * a well-documented platform semantic, not a bug in our write path — it's exactly why the
+ * `graceful-fs` package ships its own win32 rename-retry wrapper. POSIX platforms never exhibit this
+ * transient (a POSIX rename either succeeds or fails for a real, non-transient reason), so retry is
+ * gated strictly to win32 to keep POSIX behavior byte-identical to a bare rename.
+ */
+function isTransientRenameErrorOnWin32(err) {
+    if (process.platform !== "win32")
+        return false;
+    if (typeof err !== "object" || err === null)
+        return false;
+    const code = err.code;
+    return code === "EPERM" || code === "EACCES" || code === "EBUSY";
+}
+/** Sync counterpart of the rename-retry policy; see {@link isTransientRenameErrorOnWin32}. */
+function renameSyncWithRetry(tmpPath, filePath) {
+    for (let attempt = 0; attempt <= RENAME_RETRY_ATTEMPTS; attempt++) {
+        try {
+            renameSync(tmpPath, filePath);
+            return;
+        }
+        catch (err) {
+            if (!isTransientRenameErrorOnWin32(err) || attempt === RENAME_RETRY_ATTEMPTS)
+                throw err;
+            const backoffMs = Math.min(RENAME_RETRY_MIN_TIMEOUT_MS * 2 ** attempt, RENAME_RETRY_MAX_TIMEOUT_MS);
+            blockingSleepMs(backoffMs);
+        }
+    }
+}
+/** Async counterpart of the rename-retry policy; see {@link isTransientRenameErrorOnWin32}. */
+async function renameWithRetry(tmpPath, filePath) {
+    for (let attempt = 0; attempt <= RENAME_RETRY_ATTEMPTS; attempt++) {
+        try {
+            await fsPromises.rename(tmpPath, filePath);
+            return;
+        }
+        catch (err) {
+            if (!isTransientRenameErrorOnWin32(err) || attempt === RENAME_RETRY_ATTEMPTS)
+                throw err;
+            const backoffMs = Math.min(RENAME_RETRY_MIN_TIMEOUT_MS * 2 ** attempt, RENAME_RETRY_MAX_TIMEOUT_MS);
+            await new Promise((resolve) => setTimeout(resolve, backoffMs));
+        }
+    }
+}
+const DEFAULT_RETRIES = 10;
+const DEFAULT_REALPATH = false;
+/**
+ * Capped doubling backoff shared by both variants — see {@link AtomicFileLockOptions.retries}.
+ * With the current defaults (10 retries, 25ms floor, 500ms cap) the total worst-case contention
+ * budget is ~3.3s (25+50+100+200+400+500+500+500+500+500), comfortably over the >= 2s floor this
+ * needs to survive a loaded CI runner (e.g. the Windows CI mkdir/rmdir lock-directory churn under
+ * two-real-OS-thread contention).
+ */
+const RETRY_MIN_TIMEOUT_MS = 25;
+const RETRY_MAX_TIMEOUT_MS = 500;
+function ensureLockDirSync(filePath) {
+    mkdirSync(dirname(filePath), { recursive: true });
+}
+async function ensureLockDir(filePath) {
+    await fsPromises.mkdir(dirname(filePath), { recursive: true });
+}
+function isLockedError(err) {
+    if (typeof err !== "object" || err === null)
+        return false;
+    const code = err.code;
+    if (code === "ELOCKED")
+        return true;
+    // On win32, mkdir-ing the lock directory can transiently surface EPERM (rather than the
+    // expected EEXIST) when a previous incarnation of that directory is concurrently being
+    // rmdir'd by the racing releaser — the mkdir lands mid-teardown and the OS reports "operation
+    // not permitted" instead of "already exists". This is contention, not a real permissions
+    // failure, so treat it identically to ELOCKED: retry with the existing backoff rather than
+    // letting it escape as fatal. POSIX platforms don't exhibit this transient and keep surfacing
+    // real EPERM (e.g. an actually unwritable directory) as fatal.
+    if (code === "EPERM" && process.platform === "win32")
+        return true;
+    return false;
+}
+/** Block the calling thread for `ms` without spinning the CPU (Atomics.wait on a private buffer). */
+function blockingSleepMs(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * Acquire a proper-lockfile sync lock with bounded retry on `ELOCKED` (proper-lockfile's sync API
+ * itself forbids `retries > 0`; see {@link AtomicFileLockOptions.retries}).
+ *
+ * Backoff doubles each attempt (mirroring the `retry` module's own `factor: 2` default that the
+ * async path gets for free from proper-lockfile), starting at {@link RETRY_MIN_TIMEOUT_MS} and
+ * capped at {@link RETRY_MAX_TIMEOUT_MS}.
+ *
+ * This is budget PARITY between two implementations of the same lock-acquisition contract, not
+ * flake-masking: `options.retries` (a count of RETRIES, i.e. attempts after the first) means the
+ * same thing on both paths, so both must make `retries + 1` total acquisition attempts with the
+ * same per-gap backoff schedule. The async path gets `retries + 1` attempts for free from the
+ * `retry` module (it retries `options.retries` times after its initial attempt); the sync path
+ * used to loop exactly `attempts` times total (one fewer gap, and one fewer attempt than the
+ * async path for the same `retries` value), which under-budgeted it relative to its async sibling
+ * and surfaced as spurious ELOCKED failures under real contention (e.g. two OS threads hammering
+ * the same file, or mkdir/rmdir lock-directory churn on a loaded Windows CI runner).
+ */
+function lockSyncWithRetry(filePath, options) {
+    const attempts = Math.max(1, options.retries ?? DEFAULT_RETRIES) + 1;
+    const lockOptions = { realpath: options.realpath ?? DEFAULT_REALPATH, stale: options.stale };
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        try {
+            return lockfile.lockSync(filePath, lockOptions);
+        }
+        catch (err) {
+            if (!isLockedError(err) || attempt === attempts)
+                throw err;
+            const backoffMs = Math.min(RETRY_MIN_TIMEOUT_MS * 2 ** (attempt - 1), RETRY_MAX_TIMEOUT_MS);
+            blockingSleepMs(backoffMs);
+        }
+    }
+    // Unreachable (the loop always returns or throws), but keeps the function's return type honest.
+    throw new Error(`Failed to acquire lock for ${filePath}`);
+}
+/**
+ * Hold an exclusive advisory lock on `filePath` for the duration of `fn` (sync). Always releases,
+ * including when `fn` throws.
+ */
+export function withFileLockSync(filePath, fn, options) {
+    ensureLockDirSync(filePath);
+    const release = lockSyncWithRetry(filePath, options ?? {});
+    try {
+        return fn();
+    }
+    finally {
+        // A lock-cleanup failure must never mask fn()'s result (or replace fn()'s own thrown error) —
+        // by this point fn() has already durably committed or failed on its own terms.
+        try {
+            release();
+        }
+        catch {
+            // best-effort cleanup; a stale lock self-expires via proper-lockfile's `stale` window
+        }
+    }
+}
+/** Async counterpart of {@link withFileLockSync}. Always releases, including when `fn` throws/rejects. */
+export async function withFileLock(filePath, fn, options) {
+    await ensureLockDir(filePath);
+    const release = await lockfile.lock(filePath, {
+        realpath: options?.realpath ?? DEFAULT_REALPATH,
+        retries: {
+            retries: options?.retries ?? DEFAULT_RETRIES,
+            minTimeout: RETRY_MIN_TIMEOUT_MS,
+            maxTimeout: RETRY_MAX_TIMEOUT_MS,
+        },
+        stale: options?.stale,
+    });
+    try {
+        return await fn();
+    }
+    finally {
+        // See {@link withFileLockSync} — cleanup failures must not mask fn()'s outcome.
+        await release().catch(() => { });
+    }
+}
+/**
+ * Write `content` to `filePath` via write-tmp-then-rename (sync); the rename is atomic on the same
+ * filesystem, so a concurrent reader never observes a partially-written file. Does NOT itself lock —
+ * call from inside {@link withFileLockSync} when the write follows a read that must not race another
+ * writer's read+write; call standalone for an unconditional overwrite with no read step.
+ */
+function temporaryPath(filePath) {
+    return `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+}
+/** Remove one invocation's temporary path without masking the original write/rename failure. */
+function removeTemporaryPathSync(tmpPath) {
+    try {
+        unlinkSync(tmpPath);
+    }
+    catch {
+        // The rename may have consumed the path, or another failure may have prevented its creation.
+    }
+}
+async function removeTemporaryPath(tmpPath) {
+    try {
+        await fsPromises.unlink(tmpPath);
+    }
+    catch {
+        // The rename may have consumed the path, or another failure may have prevented its creation.
+    }
+}
+export function writeFileAtomicSync(filePath, content) {
+    mkdirSync(dirname(filePath), { recursive: true });
+    const tmpPath = temporaryPath(filePath);
+    let renamed = false;
+    try {
+        // `wx` makes a nonce collision harmless: never truncate another writer's temporary file.
+        writeFileSync(tmpPath, content, { encoding: "utf-8", flag: "wx" });
+        renameSyncWithRetry(tmpPath, filePath);
+        renamed = true;
+    }
+    finally {
+        if (!renamed)
+            removeTemporaryPathSync(tmpPath);
+    }
+}
+/** Async counterpart of {@link writeFileAtomicSync}. */
+export async function writeFileAtomic(filePath, content) {
+    await fsPromises.mkdir(dirname(filePath), { recursive: true });
+    const tmpPath = temporaryPath(filePath);
+    let renamed = false;
+    try {
+        // `wx` makes a nonce collision harmless: never truncate another writer's temporary file.
+        await fsPromises.writeFile(tmpPath, content, { encoding: "utf-8", flag: "wx" });
+        await renameWithRetry(tmpPath, filePath);
+        renamed = true;
+    }
+    finally {
+        if (!renamed)
+            await removeTemporaryPath(tmpPath);
+    }
+}
+//# sourceMappingURL=atomic-file.js.map

package/dist/core/util/atomic-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-file.js","sourceRoot":"","sources":["../../../src/core/util/atomic-file.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shared atomic-file helper: a single lock+tmp+rename implementation reused by every\n * on-disk store that does a read-modify-write against a JSON/text file. Modeled on the pattern\n * already proven in `memory/providers/file-store.ts` (proper-lockfile advisory lock + write-tmp-\n * then-rename); before this helper existed the pattern was copy-pasted per store, and most copies\n * were missing either the lock, the atomic write, or both.\n *\n * Two call shapes:\n *  - `withFileLock(Sync)` — hold an exclusive advisory lock across an arbitrary read-modify-write\n *    callback. The lock spans BOTH the read and the write, closing the classic RMW race where two\n *    writers each read the old content before either writes back.\n *  - `writeFileAtomic(Sync)` — write-tmp-then-rename. Used INSIDE a `withFileLock` callback (or\n *    standalone, for a pure overwrite that has no read step to race).\n *\n * Sync and async variants are both exported. Most existing stores expose a synchronous public API\n * called from hot, non-async paths (e.g. a per-token-stream perf sample), so the sync variant lets\n * them gain locking without forcing an async ripple through their callers; the async variant is for\n * call sites that are already async.\n */\n\nimport { randomUUID } from \"node:crypto\";\nimport { promises as fsPromises, mkdirSync, renameSync, unlinkSync, writeFileSync } from \"node:fs\";\nimport { dirname } from \"node:path\";\nimport lockfile from \"proper-lockfile\";\n\n/**\n * Bounded rename retry budget for the win32-only transient-rename handling below (see\n * {@link isTransientRenameErrorOnWin32}). Backoff doubles each attempt starting at\n * {@link RENAME_RETRY_MIN_TIMEOUT_MS} and capped at {@link RENAME_RETRY_MAX_TIMEOUT_MS}, mirroring\n * the doubling-backoff shape used for lock acquisition above. With {@link RENAME_RETRY_ATTEMPTS}\n * extra attempts (10, 20, 40, 80, ... capped at 200) the worst-case total wait is ~1.03s\n * (10+20+40+80+160+200+200+200+200 ~= 1110ms across 9 gaps), which comfortably covers the\n * millisecond-scale window Defender/the Windows Search indexer hold a freshly-written file open\n * without FILE_SHARE_DELETE before releasing it.\n */\nconst RENAME_RETRY_ATTEMPTS = 9;\nconst RENAME_RETRY_MIN_TIMEOUT_MS = 10;\nconst RENAME_RETRY_MAX_TIMEOUT_MS = 200;\n\n/**\n * On win32, antivirus (e.g. Windows Defender's real-time scanner) and the Windows Search indexer\n * routinely open a freshly-written file for a brief scan without `FILE_SHARE_DELETE`, which makes a\n * rename over/of that file fail transiently with EPERM/EACCES/EBUSY for a few milliseconds. This is\n * a well-documented platform semantic, not a bug in our write path — it's exactly why the\n * `graceful-fs` package ships its own win32 rename-retry wrapper. POSIX platforms never exhibit this\n * transient (a POSIX rename either succeeds or fails for a real, non-transient reason), so retry is\n * gated strictly to win32 to keep POSIX behavior byte-identical to a bare rename.\n */\nfunction isTransientRenameErrorOnWin32(err: unknown): boolean {\n\tif (process.platform !== \"win32\") return false;\n\tif (typeof err !== \"object\" || err === null) return false;\n\tconst code = (err as { code?: string }).code;\n\treturn code === \"EPERM\" || code === \"EACCES\" || code === \"EBUSY\";\n}\n\n/** Sync counterpart of the rename-retry policy; see {@link isTransientRenameErrorOnWin32}. */\nfunction renameSyncWithRetry(tmpPath: string, filePath: string): void {\n\tfor (let attempt = 0; attempt <= RENAME_RETRY_ATTEMPTS; attempt++) {\n\t\ttry {\n\t\t\trenameSync(tmpPath, filePath);\n\t\t\treturn;\n\t\t} catch (err) {\n\t\t\tif (!isTransientRenameErrorOnWin32(err) || attempt === RENAME_RETRY_ATTEMPTS) throw err;\n\t\t\tconst backoffMs = Math.min(RENAME_RETRY_MIN_TIMEOUT_MS * 2 ** attempt, RENAME_RETRY_MAX_TIMEOUT_MS);\n\t\t\tblockingSleepMs(backoffMs);\n\t\t}\n\t}\n}\n\n/** Async counterpart of the rename-retry policy; see {@link isTransientRenameErrorOnWin32}. */\nasync function renameWithRetry(tmpPath: string, filePath: string): Promise<void> {\n\tfor (let attempt = 0; attempt <= RENAME_RETRY_ATTEMPTS; attempt++) {\n\t\ttry {\n\t\t\tawait fsPromises.rename(tmpPath, filePath);\n\t\t\treturn;\n\t\t} catch (err) {\n\t\t\tif (!isTransientRenameErrorOnWin32(err) || attempt === RENAME_RETRY_ATTEMPTS) throw err;\n\t\t\tconst backoffMs = Math.min(RENAME_RETRY_MIN_TIMEOUT_MS * 2 ** attempt, RENAME_RETRY_MAX_TIMEOUT_MS);\n\t\t\tawait new Promise((resolve) => setTimeout(resolve, backoffMs));\n\t\t}\n\t}\n}\n\nexport interface AtomicFileLockOptions {\n\t/**\n\t * Bounded retry attempts while waiting for a lock already held elsewhere. Both variants use a\n\t * SHORT, capped backoff (see {@link RETRY_MIN_TIMEOUT_MS}/{@link RETRY_MAX_TIMEOUT_MS}) — these\n\t * stores' critical sections are sub-millisecond reads+writes of small JSON/text files, so\n\t * contention should clear in milliseconds, not the multi-second-to-31-second worst case\n\t * proper-lockfile's OWN default backoff produces for a bare numeric `retries` (its default\n\t * `minTimeout` is 1000ms with factor 2 — see node_modules/retry/lib/retry.js). Passing a bare\n\t * number straight through would turn brief contention into a multi-second stall on a hot path\n\t * (e.g. a per-token-stream perf sample), so both variants instead build an explicit short-backoff\n\t * `retry` options object.\n\t * - Async (`withFileLock`): forwarded as `{retries, minTimeout, maxTimeout}` to proper-lockfile.\n\t * - Sync (`withFileLockSync`): proper-lockfile's sync API REJECTS `retries > 0` outright (it\n\t *   requires the whole acquire flow to be synchronous — see proper-lockfile/lib/adapter.js\n\t *   `toSyncOptions`, which throws `ESYNC`). So the sync path implements its own bounded retry\n\t *   around single `lockfile.lockSync` attempts, blocking briefly between them (Atomics.wait) —\n\t *   callers are already fully synchronous fs code, so a short blocking wait on contention matches\n\t *   the existing execution model rather than introducing a new one.\n\t */\n\tretries?: number;\n\t/** Resolve symlinks before locking (proper-lockfile `realpath`); false matches file-store.ts. */\n\trealpath?: boolean;\n\t/** Lock staleness window in ms (proper-lockfile `stale`); omitted = proper-lockfile's own default. */\n\tstale?: number;\n}\n\nconst DEFAULT_RETRIES = 10;\nconst DEFAULT_REALPATH = false;\n/**\n * Capped doubling backoff shared by both variants — see {@link AtomicFileLockOptions.retries}.\n * With the current defaults (10 retries, 25ms floor, 500ms cap) the total worst-case contention\n * budget is ~3.3s (25+50+100+200+400+500+500+500+500+500), comfortably over the >= 2s floor this\n * needs to survive a loaded CI runner (e.g. the Windows CI mkdir/rmdir lock-directory churn under\n * two-real-OS-thread contention).\n */\nconst RETRY_MIN_TIMEOUT_MS = 25;\nconst RETRY_MAX_TIMEOUT_MS = 500;\nfunction ensureLockDirSync(filePath: string): void {\n\tmkdirSync(dirname(filePath), { recursive: true });\n}\n\nasync function ensureLockDir(filePath: string): Promise<void> {\n\tawait fsPromises.mkdir(dirname(filePath), { recursive: true });\n}\n\nfunction isLockedError(err: unknown): boolean {\n\tif (typeof err !== \"object\" || err === null) return false;\n\tconst code = (err as { code?: string }).code;\n\tif (code === \"ELOCKED\") return true;\n\t// On win32, mkdir-ing the lock directory can transiently surface EPERM (rather than the\n\t// expected EEXIST) when a previous incarnation of that directory is concurrently being\n\t// rmdir'd by the racing releaser — the mkdir lands mid-teardown and the OS reports \"operation\n\t// not permitted\" instead of \"already exists\". This is contention, not a real permissions\n\t// failure, so treat it identically to ELOCKED: retry with the existing backoff rather than\n\t// letting it escape as fatal. POSIX platforms don't exhibit this transient and keep surfacing\n\t// real EPERM (e.g. an actually unwritable directory) as fatal.\n\tif (code === \"EPERM\" && process.platform === \"win32\") return true;\n\treturn false;\n}\n\n/** Block the calling thread for `ms` without spinning the CPU (Atomics.wait on a private buffer). */\nfunction blockingSleepMs(ms: number): void {\n\tAtomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);\n}\n\n/**\n * Acquire a proper-lockfile sync lock with bounded retry on `ELOCKED` (proper-lockfile's sync API\n * itself forbids `retries > 0`; see {@link AtomicFileLockOptions.retries}).\n *\n * Backoff doubles each attempt (mirroring the `retry` module's own `factor: 2` default that the\n * async path gets for free from proper-lockfile), starting at {@link RETRY_MIN_TIMEOUT_MS} and\n * capped at {@link RETRY_MAX_TIMEOUT_MS}.\n *\n * This is budget PARITY between two implementations of the same lock-acquisition contract, not\n * flake-masking: `options.retries` (a count of RETRIES, i.e. attempts after the first) means the\n * same thing on both paths, so both must make `retries + 1` total acquisition attempts with the\n * same per-gap backoff schedule. The async path gets `retries + 1` attempts for free from the\n * `retry` module (it retries `options.retries` times after its initial attempt); the sync path\n * used to loop exactly `attempts` times total (one fewer gap, and one fewer attempt than the\n * async path for the same `retries` value), which under-budgeted it relative to its async sibling\n * and surfaced as spurious ELOCKED failures under real contention (e.g. two OS threads hammering\n * the same file, or mkdir/rmdir lock-directory churn on a loaded Windows CI runner).\n */\nfunction lockSyncWithRetry(filePath: string, options: AtomicFileLockOptions): () => void {\n\tconst attempts = Math.max(1, options.retries ?? DEFAULT_RETRIES) + 1;\n\tconst lockOptions = { realpath: options.realpath ?? DEFAULT_REALPATH, stale: options.stale };\n\tfor (let attempt = 1; attempt <= attempts; attempt++) {\n\t\ttry {\n\t\t\treturn lockfile.lockSync(filePath, lockOptions);\n\t\t} catch (err) {\n\t\t\tif (!isLockedError(err) || attempt === attempts) throw err;\n\t\t\tconst backoffMs = Math.min(RETRY_MIN_TIMEOUT_MS * 2 ** (attempt - 1), RETRY_MAX_TIMEOUT_MS);\n\t\t\tblockingSleepMs(backoffMs);\n\t\t}\n\t}\n\t// Unreachable (the loop always returns or throws), but keeps the function's return type honest.\n\tthrow new Error(`Failed to acquire lock for ${filePath}`);\n}\n\n/**\n * Hold an exclusive advisory lock on `filePath` for the duration of `fn` (sync). Always releases,\n * including when `fn` throws.\n */\nexport function withFileLockSync<T>(filePath: string, fn: () => T, options?: AtomicFileLockOptions): T {\n\tensureLockDirSync(filePath);\n\tconst release = lockSyncWithRetry(filePath, options ?? {});\n\ttry {\n\t\treturn fn();\n\t} finally {\n\t\t// A lock-cleanup failure must never mask fn()'s result (or replace fn()'s own thrown error) —\n\t\t// by this point fn() has already durably committed or failed on its own terms.\n\t\ttry {\n\t\t\trelease();\n\t\t} catch {\n\t\t\t// best-effort cleanup; a stale lock self-expires via proper-lockfile's `stale` window\n\t\t}\n\t}\n}\n\n/** Async counterpart of {@link withFileLockSync}. Always releases, including when `fn` throws/rejects. */\nexport async function withFileLock<T>(\n\tfilePath: string,\n\tfn: () => Promise<T> | T,\n\toptions?: AtomicFileLockOptions,\n): Promise<T> {\n\tawait ensureLockDir(filePath);\n\tconst release = await lockfile.lock(filePath, {\n\t\trealpath: options?.realpath ?? DEFAULT_REALPATH,\n\t\tretries: {\n\t\t\tretries: options?.retries ?? DEFAULT_RETRIES,\n\t\t\tminTimeout: RETRY_MIN_TIMEOUT_MS,\n\t\t\tmaxTimeout: RETRY_MAX_TIMEOUT_MS,\n\t\t},\n\t\tstale: options?.stale,\n\t});\n\ttry {\n\t\treturn await fn();\n\t} finally {\n\t\t// See {@link withFileLockSync} — cleanup failures must not mask fn()'s outcome.\n\t\tawait release().catch(() => {});\n\t}\n}\n\n/**\n * Write `content` to `filePath` via write-tmp-then-rename (sync); the rename is atomic on the same\n * filesystem, so a concurrent reader never observes a partially-written file. Does NOT itself lock —\n * call from inside {@link withFileLockSync} when the write follows a read that must not race another\n * writer's read+write; call standalone for an unconditional overwrite with no read step.\n */\nfunction temporaryPath(filePath: string): string {\n\treturn `${filePath}.${process.pid}.${randomUUID()}.tmp`;\n}\n\n/** Remove one invocation's temporary path without masking the original write/rename failure. */\nfunction removeTemporaryPathSync(tmpPath: string): void {\n\ttry {\n\t\tunlinkSync(tmpPath);\n\t} catch {\n\t\t// The rename may have consumed the path, or another failure may have prevented its creation.\n\t}\n}\n\nasync function removeTemporaryPath(tmpPath: string): Promise<void> {\n\ttry {\n\t\tawait fsPromises.unlink(tmpPath);\n\t} catch {\n\t\t// The rename may have consumed the path, or another failure may have prevented its creation.\n\t}\n}\n\nexport function writeFileAtomicSync(filePath: string, content: string): void {\n\tmkdirSync(dirname(filePath), { recursive: true });\n\tconst tmpPath = temporaryPath(filePath);\n\tlet renamed = false;\n\ttry {\n\t\t// `wx` makes a nonce collision harmless: never truncate another writer's temporary file.\n\t\twriteFileSync(tmpPath, content, { encoding: \"utf-8\", flag: \"wx\" });\n\t\trenameSyncWithRetry(tmpPath, filePath);\n\t\trenamed = true;\n\t} finally {\n\t\tif (!renamed) removeTemporaryPathSync(tmpPath);\n\t}\n}\n\n/** Async counterpart of {@link writeFileAtomicSync}. */\nexport async function writeFileAtomic(filePath: string, content: string): Promise<void> {\n\tawait fsPromises.mkdir(dirname(filePath), { recursive: true });\n\tconst tmpPath = temporaryPath(filePath);\n\tlet renamed = false;\n\ttry {\n\t\t// `wx` makes a nonce collision harmless: never truncate another writer's temporary file.\n\t\tawait fsPromises.writeFile(tmpPath, content, { encoding: \"utf-8\", flag: \"wx\" });\n\t\tawait renameWithRetry(tmpPath, filePath);\n\t\trenamed = true;\n\t} finally {\n\t\tif (!renamed) await removeTemporaryPath(tmpPath);\n\t}\n}\n"]}

package/dist/core/util/minimatch-cache.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared compiled-pattern cache (C2): `matchesAnyPattern` in `package-manager.ts` and
+ * `matchesResourceProfilePattern` in `settings-manager.ts` each test up to 6 candidate strings
+ * (relative path, basename, absolute path, and the same 3 for the parent directory) against every
+ * configured glob pattern, per file, on every reload/profile switch. The functional `minimatch(p,
+ * pattern, options)` re-parses `pattern` into a `Minimatch` instance on EVERY call — so the same
+ * pattern was being compiled up to 6x per file per call site.
+ *
+ * `new Minimatch(pattern, options).match(p)` is exactly what the functional form does internally
+ * (see `minimatch`'s own implementation: `assertValidPattern(pattern)` then
+ * `new Minimatch(pattern, options).match(p)`, with comment/empty-pattern short-circuits handled
+ * inside the class itself), so precompiling and reusing the `Minimatch` instance is behaviorally
+ * identical to calling the functional form each time — only the redundant re-parsing is removed.
+ *
+ * Both call sites invoke `minimatch(candidate, pattern)` with NO options argument (always the
+ * library default `{}`), so the cache key is the pattern string alone. If a future caller needs
+ * non-default options, extend the key to include a serialized options object rather than reusing
+ * this cache blind — a `Minimatch` compiled under different options is not interchangeable.
+ *
+ * The cache is a plain, unbounded module-level `Map`. That is safe here because patterns are not
+ * arbitrary/untrusted input: they come from a small, operator-controlled set (package resource
+ * patterns in settings, `.gitignore`-style profile overrides) that is bounded by how much a human
+ * hand-authors into settings/profile files, not by file count or request volume. It never grows
+ * per-file or per-scan.
+ */
+import { type MinimatchOptions } from "minimatch";
+/**
+ * Drop-in replacement for `minimatch(candidate, pattern, options)` that compiles each unique
+ * `(pattern, options)` pair once and reuses it. Match results are identical to the functional
+ * form; only the redundant glob-compilation work is eliminated.
+ */
+export declare function matchesCompiledPattern(candidate: string, pattern: string, options?: MinimatchOptions): boolean;
+//# sourceMappingURL=minimatch-cache.d.ts.map

package/dist/core/util/minimatch-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"minimatch-cache.d.ts","sourceRoot":"","sources":["../../../src/core/util/minimatch-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAa,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAgB7D;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAE9G","sourcesContent":["/**\n * Shared compiled-pattern cache (C2): `matchesAnyPattern` in `package-manager.ts` and\n * `matchesResourceProfilePattern` in `settings-manager.ts` each test up to 6 candidate strings\n * (relative path, basename, absolute path, and the same 3 for the parent directory) against every\n * configured glob pattern, per file, on every reload/profile switch. The functional `minimatch(p,\n * pattern, options)` re-parses `pattern` into a `Minimatch` instance on EVERY call — so the same\n * pattern was being compiled up to 6x per file per call site.\n *\n * `new Minimatch(pattern, options).match(p)` is exactly what the functional form does internally\n * (see `minimatch`'s own implementation: `assertValidPattern(pattern)` then\n * `new Minimatch(pattern, options).match(p)`, with comment/empty-pattern short-circuits handled\n * inside the class itself), so precompiling and reusing the `Minimatch` instance is behaviorally\n * identical to calling the functional form each time — only the redundant re-parsing is removed.\n *\n * Both call sites invoke `minimatch(candidate, pattern)` with NO options argument (always the\n * library default `{}`), so the cache key is the pattern string alone. If a future caller needs\n * non-default options, extend the key to include a serialized options object rather than reusing\n * this cache blind — a `Minimatch` compiled under different options is not interchangeable.\n *\n * The cache is a plain, unbounded module-level `Map`. That is safe here because patterns are not\n * arbitrary/untrusted input: they come from a small, operator-controlled set (package resource\n * patterns in settings, `.gitignore`-style profile overrides) that is bounded by how much a human\n * hand-authors into settings/profile files, not by file count or request volume. It never grows\n * per-file or per-scan.\n */\n\nimport { Minimatch, type MinimatchOptions } from \"minimatch\";\n\nconst compiledPatternCache = new Map<string, Minimatch>();\n\nfunction getCompiledPattern(pattern: string, options?: MinimatchOptions): Minimatch {\n\t// Both current call sites omit `options`, so this collapses to a single default-options\n\t// instance per unique pattern string in practice.\n\tconst key = options ? `${JSON.stringify(options)}\u0000${pattern}` : pattern;\n\tlet compiled = compiledPatternCache.get(key);\n\tif (!compiled) {\n\t\tcompiled = new Minimatch(pattern, options);\n\t\tcompiledPatternCache.set(key, compiled);\n\t}\n\treturn compiled;\n}\n\n/**\n * Drop-in replacement for `minimatch(candidate, pattern, options)` that compiles each unique\n * `(pattern, options)` pair once and reuses it. Match results are identical to the functional\n * form; only the redundant glob-compilation work is eliminated.\n */\nexport function matchesCompiledPattern(candidate: string, pattern: string, options?: MinimatchOptions): boolean {\n\treturn getCompiledPattern(pattern, options).match(candidate);\n}\n"]}

package/dist/core/util/minimatch-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"minimatch-cache.js","sourceRoot":"","sources":["../../../src/core/util/minimatch-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,SAAS,EAAyB,MAAM,WAAW,CAAC;AAE7D,MAAM,oBAAoB,GAAG,IAAI,GAAG,EAAqB,CAAC;AAE1D,SAAS,kBAAkB,CAAC,OAAe,EAAE,OAA0B,EAAa;IACnF,wFAAwF;IACxF,kDAAkD;IAClD,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,OAAO,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;IACxE,IAAI,QAAQ,GAAG,oBAAoB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7C,IAAI,CAAC,QAAQ,EAAE,CAAC;QACf,QAAQ,GAAG,IAAI,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAC3C,oBAAoB,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,QAAQ,CAAC;AAAA,CAChB;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,SAAiB,EAAE,OAAe,EAAE,OAA0B,EAAW;IAC/G,OAAO,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;AAAA,CAC7D","sourcesContent":["/**\n * Shared compiled-pattern cache (C2): `matchesAnyPattern` in `package-manager.ts` and\n * `matchesResourceProfilePattern` in `settings-manager.ts` each test up to 6 candidate strings\n * (relative path, basename, absolute path, and the same 3 for the parent directory) against every\n * configured glob pattern, per file, on every reload/profile switch. The functional `minimatch(p,\n * pattern, options)` re-parses `pattern` into a `Minimatch` instance on EVERY call — so the same\n * pattern was being compiled up to 6x per file per call site.\n *\n * `new Minimatch(pattern, options).match(p)` is exactly what the functional form does internally\n * (see `minimatch`'s own implementation: `assertValidPattern(pattern)` then\n * `new Minimatch(pattern, options).match(p)`, with comment/empty-pattern short-circuits handled\n * inside the class itself), so precompiling and reusing the `Minimatch` instance is behaviorally\n * identical to calling the functional form each time — only the redundant re-parsing is removed.\n *\n * Both call sites invoke `minimatch(candidate, pattern)` with NO options argument (always the\n * library default `{}`), so the cache key is the pattern string alone. If a future caller needs\n * non-default options, extend the key to include a serialized options object rather than reusing\n * this cache blind — a `Minimatch` compiled under different options is not interchangeable.\n *\n * The cache is a plain, unbounded module-level `Map`. That is safe here because patterns are not\n * arbitrary/untrusted input: they come from a small, operator-controlled set (package resource\n * patterns in settings, `.gitignore`-style profile overrides) that is bounded by how much a human\n * hand-authors into settings/profile files, not by file count or request volume. It never grows\n * per-file or per-scan.\n */\n\nimport { Minimatch, type MinimatchOptions } from \"minimatch\";\n\nconst compiledPatternCache = new Map<string, Minimatch>();\n\nfunction getCompiledPattern(pattern: string, options?: MinimatchOptions): Minimatch {\n\t// Both current call sites omit `options`, so this collapses to a single default-options\n\t// instance per unique pattern string in practice.\n\tconst key = options ? `${JSON.stringify(options)}\u0000${pattern}` : pattern;\n\tlet compiled = compiledPatternCache.get(key);\n\tif (!compiled) {\n\t\tcompiled = new Minimatch(pattern, options);\n\t\tcompiledPatternCache.set(key, compiled);\n\t}\n\treturn compiled;\n}\n\n/**\n * Drop-in replacement for `minimatch(candidate, pattern, options)` that compiles each unique\n * `(pattern, options)` pair once and reuses it. Match results are identical to the functional\n * form; only the redundant glob-compilation work is eliminated.\n */\nexport function matchesCompiledPattern(candidate: string, pattern: string, options?: MinimatchOptions): boolean {\n\treturn getCompiledPattern(pattern, options).match(candidate);\n}\n"]}

package/dist/core/worktree-sync/codes.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Worktree-sync SSOT for tagged result codes and shared record types.
+ *
+ * Every worktree-sync operation reports its outcome through one of these string-literal codes in
+ * a typed result -- callers branch on `code`, NEVER on message/stderr substrings (the
+ * `classifyDispatchError` substring compromise is deliberately not repeated here). Git stderr is
+ * carried alongside as evidence for humans, not as a branch condition.
+ */
+/** Cap on `WorktreeSyncEpoch.changedPaths`; beyond it the list is truncated and overlap checks
+ * treat the land as conservatively overlapping EVERYTHING (deterministic, never optimistic). */
+export declare const EPOCH_CHANGED_PATHS_CAP = 500;
+/** Branch namespace for lane branches: `pi/wt/<laneKey>`. */
+export declare const LANE_BRANCH_PREFIX = "pi/wt/";
+export type WorktreeSyncCode = "ok" | "disabled" | "not_a_git_repo" | "default_branch_unresolved" | "hub_missing" | "invalid_lane_key" | "lane_exists" | "lane_not_found" | "max_lanes_reached" | "lane_dirty" | "hub_dirty" | "stale_lane" | "sync_required" | "sync_clean" | "sync_conflicts" | "rebase_in_progress" | "no_rebase_in_progress" | "conflict_markers_present" | "gate_command_unset" | "gate_failed" | "lane_changed_during_gate" | "ff_failed" | "lock_busy" | "lock_takeover" | "nothing_to_land" | "main_mutation_refused" | "lane_unlanded_work" | "worktree_missing" | "released" | "reconciled" | "git_error" | "role_forbidden" | "path_outside_lane" | "lane_owner_conflict";
+/**
+ * A refusal/failure outcome. `message` is deterministic text assembled from facts (safe to show a
+ * model verbatim); `gitStderr` is bounded raw evidence; `paths` names offending files where the
+ * refusal is about specific files (dirty files, conflict markers); `holder` identifies the
+ * integration-lock holder on `lock_busy`.
+ */
+export interface WorktreeSyncRefusal<C extends WorktreeSyncCode = WorktreeSyncCode> {
+    code: C;
+    message: string;
+    gitStderr?: string;
+    paths?: string[];
+    holder?: IntegrationLockOwner;
+}
+/** Staleness-propagation policy (D9). `on_land_mandatory` is the default: every land marks every
+ * other active lane sync_required. `overlap_mandatory` requires it only on changed-file overlap.
+ * `land_time_only` keeps staleness advisory until the land gate (G3 always enforces). */
+export type WorktreeSyncPolicy = "on_land_mandatory" | "overlap_mandatory" | "land_time_only";
+/** One lane registration record (`lanes/<laneKey>.json`). Identity/binding fields ONLY -- git
+ * truths (freshness, dirtiness, ahead/behind) are always re-derived live, never stored here. */
+export interface LaneRegistration {
+    laneKey: string;
+    branch: string;
+    worktreePath: string;
+    status: "active" | "released" | "orphaned";
+    createdAt: string;
+    updatedAt: string;
+    goalId?: string;
+    requirementId?: string;
+    /** Host `LaneRecord.laneId` after dispatch correlation (tmux/in-process worker binding). */
+    boundLaneId?: string;
+    ownerPid?: number;
+    ownerSessionId?: string;
+}
+/** `epoch.json` -- the integration epoch. `epoch` is monotonic messaging/audit sugar; correctness
+ * always derives from git shas (`merge-base --is-ancestor`), never from this counter. */
+export interface WorktreeSyncEpoch {
+    epoch: number;
+    mainSha: string;
+    previousMainSha?: string;
+    landedLaneKey?: string;
+    landedAt?: string;
+    changedPaths: string[];
+    changedPathsTruncated: boolean;
+}
+/** Live, git-derived facts about one lane. Computed fresh per call -- there is no cached copy to
+ * go stale, which is the point. */
+export interface LaneFacts {
+    laneKey: string;
+    branch: string;
+    worktreePath: string;
+    registrationStatus: LaneRegistration["status"];
+    /** Lane branch tip sha; undefined when the branch no longer exists. */
+    branchSha?: string;
+    /** True iff current main is an ancestor of the lane tip (`merge-base --is-ancestor`). */
+    fresh: boolean;
+    /** True when `status --porcelain` in the lane worktree is non-empty. */
+    dirty: boolean;
+    rebaseInProgress: boolean;
+    aheadOfMain: number;
+    behindMain: number;
+    worktreePresent: boolean;
+    /** Undefined when the lane has no recorded owner pid. */
+    ownerAlive?: boolean;
+}
+export interface IntegrationLockOwner {
+    pid: number;
+    hostname: string;
+    /** Random acquisition identity; PID/session are diagnostic only and never authorize release. */
+    token: string;
+    sessionId?: string;
+    laneKey?: string;
+    acquiredAt: string;
+}
+export type IntegrationLockAcquisition = {
+    acquired: true;
+    takeover: boolean;
+    token: string;
+} | {
+    acquired: false;
+    holder?: IntegrationLockOwner;
+    holderAlive: boolean;
+};
+/** One conflicted file in a sync stopped on conflicts. */
+export interface ConflictWorklistFile {
+    path: string;
+    /** Both-modified is the common case; add/add and modify/delete surface as their index states. */
+    kind: "both_modified" | "both_added" | "deleted_by_us" | "deleted_by_them" | "unknown";
+    /** True when git rerere already replayed a recorded resolution for this file -- review, not re-resolve. */
+    resolvedByRerere: boolean;
+}
+/** Structured conflict worklist returned when a sync/continue stops on conflicts. */
+export interface ConflictWorklist {
+    /** e.g. "2/5" -- rebase progress (stopped step / total steps). */
+    step: string;
+    stoppedAtCommit?: {
+        sha: string;
+        subject: string;
+    };
+    files: ConflictWorklistFile[];
+}
+export type BindLaneWorkerResult = {
+    code: "bound";
+    laneKey: string;
+    laneId: string;
+} | {
+    code: "already_bound";
+    laneKey: string;
+    laneId: string;
+} | {
+    code: "binding_conflict";
+    laneKey: string;
+    boundLaneId: string;
+} | {
+    code: "lane_not_found";
+    message: string;
+} | {
+    code: "lane_not_active";
+    message: string;
+} | {
+    code: "store_error";
+    message: string;
+};
+export type CreateLaneResult = {
+    code: "ok";
+    lane: LaneRegistration;
+} | WorktreeSyncRefusal<"not_a_git_repo" | "default_branch_unresolved" | "invalid_lane_key" | "lane_exists" | "max_lanes_reached" | "git_error">;
+export type ReleaseLaneResult = {
+    code: "released";
+    laneKey: string;
+} | WorktreeSyncRefusal<"not_a_git_repo" | "default_branch_unresolved" | "lane_not_found" | "lane_unlanded_work" | "lane_owner_conflict" | "git_error">;
+export interface LandingTransaction {
+    laneKey: string;
+    priorMainSha: string;
+    testedTipSha: string;
+    changedPaths: string[];
+    changedPathsTruncated: boolean;
+    lockToken: string;
+    gate: "passed" | "off";
+    stage: "ready_to_merge" | "main_moved" | "epoch_written" | "audit_logged";
+}
+export interface ReconcileSummary {
+    code: "reconciled";
+    orphanedLaneKeys: string[];
+    reRegisteredLaneKeys: string[];
+    ownerClearedLaneKeys: string[];
+    staleLockReleased: boolean;
+}
+export type ReconcileResult = ReconcileSummary | WorktreeSyncRefusal<"not_a_git_repo" | "default_branch_unresolved" | "git_error">;
+export type SyncLaneResult = {
+    code: "sync_clean";
+    laneKey: string;
+    alreadyFresh: boolean;
+    autoContinued: number;
+} | {
+    code: "sync_conflicts";
+    laneKey: string;
+    worklist: ConflictWorklist;
+} | WorktreeSyncRefusal<"not_a_git_repo" | "default_branch_unresolved" | "lane_not_found" | "worktree_missing" | "lane_dirty" | "rebase_in_progress" | "git_error">;
+export type ContinueSyncResult = {
+    code: "sync_clean";
+    laneKey: string;
+    autoContinued: number;
+} | {
+    code: "sync_conflicts";
+    laneKey: string;
+    worklist: ConflictWorklist;
+} | WorktreeSyncRefusal<"not_a_git_repo" | "default_branch_unresolved" | "lane_not_found" | "worktree_missing" | "no_rebase_in_progress" | "conflict_markers_present" | "git_error">;
+export type AbortSyncResult = {
+    code: "ok";
+    laneKey: string;
+} | WorktreeSyncRefusal<"not_a_git_repo" | "default_branch_unresolved" | "lane_not_found" | "no_rebase_in_progress" | "git_error">;
+export type LandResult = {
+    code: "ok";
+    laneKey: string;
+    epoch: number;
+    mainSha: string;
+    gate: "passed" | "off";
+} | WorktreeSyncRefusal<"not_a_git_repo" | "default_branch_unresolved" | "lane_not_found" | "worktree_missing" | "rebase_in_progress" | "lane_dirty" | "stale_lane" | "hub_missing" | "hub_dirty" | "gate_command_unset" | "gate_failed" | "lane_changed_during_gate" | "ff_failed" | "lock_busy" | "nothing_to_land" | "lane_owner_conflict" | "git_error">;
+/** One lane's full status entry: live git facts plus registry identity plus policy derivation. */
+export interface LaneStatusEntry extends LaneFacts {
+    goalId?: string;
+    requirementId?: string;
+    boundLaneId?: string;
+    /** Not fresh: main moved past this lane's base. Derived, never stored. */
+    stale: boolean;
+    /** Stale AND the active policy makes syncing mandatory NOW (G8 gates on this). */
+    syncRequired: boolean;
+    /** Lane-changed files intersecting the last land's changed files (conservatively the whole
+     * lane-changed list when the epoch's changedPaths were truncated). */
+    overlapWithLastLand: string[];
+}
+/** The deterministic full picture (`status` action): everything an agent would otherwise infer
+ * probabilistically from porcelain output, computed mechanically. */
+export interface SyncStatus {
+    code: "ok";
+    mainBranch: string;
+    mainSha: string;
+    epoch: number;
+    hub?: {
+        path: string;
+        clean: boolean;
+    };
+    lock: {
+        held: boolean;
+        holder?: IntegrationLockOwner;
+        holderAlive?: boolean;
+    };
+    lanes: LaneStatusEntry[];
+    /** One deterministic advisory sentence assembled from the codes above; never model-generated. */
+    advice?: string;
+}
+export type SyncStatusResult = SyncStatus | WorktreeSyncRefusal<"not_a_git_repo" | "default_branch_unresolved" | "git_error">;
+//# sourceMappingURL=codes.d.ts.map