@bendyline/gezel-inference 0.0.0-stage → 1.0.0

package/dist/engines/signature.d.ts

@@ -0,0 +1,85 @@
+/**
+ * How strictly a downloaded engine binary's code signature is enforced.
+ *
+ *   - `off`     — skip the check entirely (escape hatch).
+ *   - `prefer`  — verify if signed; an unsigned binary is allowed (with a
+ *                 warning), but a *tampered* signature (`invalid`) is
+ *                 rejected. Reserved for explicitly allowlisted upstream
+ *                 binaries that their publisher ships unsigned.
+ *   - `require` — accept only `valid` signatures. (`unsupported` platforms
+ *                 — Linux, which has no signing standard we use — are
+ *                 accepted because sha256 is the integrity gate there.)
+ *                 Missing verification tools on Windows/macOS fail closed.
+ */
+export type SignaturePolicy = 'require' | 'prefer' | 'off';
+export type SignatureStatus = 'valid' | 'invalid' | 'unsigned' | 'unsupported';
+/**
+ * Our signing identity, as it actually appears in each platform's certificate.
+ *
+ * The two platforms disagree on punctuation for the same legal entity, which
+ * is why the name is matched punctuation-insensitively and the Apple team id
+ * is matched exactly:
+ *
+ *   macOS   `Developer ID Application: Bendyline, LLC (JXA5M4VK3V)`   ← comma
+ *   Windows `CN=Bendyline LLC,O=Bendyline LLC,L=Sammamish,ST=…,C=US`  ← none
+ *
+ * A literal `includes('… Application: Bendyline LLC')` therefore never matched
+ * a real macOS binary, and every native engine download failed closed once the
+ * default policy became `require`. The team id is the durable anchor — it is
+ * bound to the certificate and cannot drift with a display-name reissue.
+ */
+export declare const BENDYLINE_PUBLISHER = "Bendyline LLC";
+export declare const BENDYLINE_APPLE_TEAM_ID = "JXA5M4VK3V";
+export interface SignatureResult {
+    status: SignatureStatus;
+    detail?: string;
+}
+export interface VerifyOutcome {
+    result: SignatureResult;
+    /** Whether {@link VerifyOptions.policy} accepts this result. */
+    accepted: boolean;
+}
+/** (code, stdout, stderr) of a finished command; never rejects. */
+type RunResult = {
+    code: number | string;
+    stdout: string;
+    stderr: string;
+};
+type Runner = (cmd: string, args: string[], options?: {
+    env: NodeJS.ProcessEnv;
+}) => Promise<RunResult>;
+export interface VerifyOptions {
+    policy: SignaturePolicy;
+    /** Test seam — defaults to `process.platform`. */
+    platform?: NodeJS.Platform;
+    /** Expected organization in the Authenticode/Developer ID identity. */
+    expectedPublisher?: string;
+    /**
+     * Expected Apple Developer team id (macOS only). Matched exactly against the
+     * `(TEAMID)` suffix of the leaf `Developer ID Application` authority.
+     */
+    expectedAppleTeamId?: string;
+    /**
+     * Require Gatekeeper to identify a parent `.app` bundle as Notarized
+     * Developer ID. Never use this for a bare command-line binary: Apple
+     * notarizes its submitted archive, but `spctl` does not assess it as an app.
+     */
+    requireNotarizedApp?: boolean;
+    /** Test seam — defaults to a real `execFile` runner. */
+    run?: Runner;
+}
+/**
+ * Verify a binary's code signature and decide whether `policy` accepts it.
+ * Pure-ish: all process interaction goes through the injectable `run`.
+ */
+export declare function verifyCodeSignature(binPath: string, opts: VerifyOptions): Promise<VerifyOutcome>;
+/**
+ * Best-effort: clear the macOS `com.apple.quarantine` xattr so a
+ * freshly-downloaded binary isn't blocked by Gatekeeper on first exec.
+ * No-op (and never throws) off macOS or when the attr isn't present.
+ */
+export declare function stripQuarantine(binPath: string, opts?: {
+    platform?: NodeJS.Platform;
+    run?: Runner;
+}): Promise<void>;
+export {};

package/dist/engines/signature.js

@@ -0,0 +1,231 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { createLogger } from '@bendyline/gezel';
+import { windowsHeadlessSpawnOptions } from '@bendyline/gezel/native';
+const log = createLogger('engine-signature');
+const execFileAsync = promisify(execFile);
+/**
+ * Our signing identity, as it actually appears in each platform's certificate.
+ *
+ * The two platforms disagree on punctuation for the same legal entity, which
+ * is why the name is matched punctuation-insensitively and the Apple team id
+ * is matched exactly:
+ *
+ *   macOS   `Developer ID Application: Bendyline, LLC (JXA5M4VK3V)`   ← comma
+ *   Windows `CN=Bendyline LLC,O=Bendyline LLC,L=Sammamish,ST=…,C=US`  ← none
+ *
+ * A literal `includes('… Application: Bendyline LLC')` therefore never matched
+ * a real macOS binary, and every native engine download failed closed once the
+ * default policy became `require`. The team id is the durable anchor — it is
+ * bound to the certificate and cannot drift with a display-name reissue.
+ */
+export const BENDYLINE_PUBLISHER = 'Bendyline LLC';
+export const BENDYLINE_APPLE_TEAM_ID = 'JXA5M4VK3V';
+const defaultRun = async (cmd, args, options) => {
+    try {
+        const { stdout, stderr } = await execFileAsync(cmd, args, {
+            maxBuffer: 4 * 1024 * 1024,
+            ...options,
+            // Native installation verifies four toolkit executables in sequence.
+            // On Windows, detaching these short-lived PowerShell checks gives each
+            // one a new console window; hide the owned children instead.
+            ...windowsHeadlessSpawnOptions(),
+        });
+        return { code: 0, stdout: String(stdout), stderr: String(stderr) };
+    }
+    catch (err) {
+        const e = err;
+        return {
+            code: e.code ?? 1,
+            stdout: String(e.stdout ?? ''),
+            stderr: String(e.stderr ?? ''),
+        };
+    }
+};
+/** Did the tool fail to launch at all (missing binary)? Then we can't verify. */
+function isSpawnFailure(code) {
+    return typeof code === 'string'; // 'ENOENT', 'EACCES', …
+}
+/**
+ * Verify a binary's code signature and decide whether `policy` accepts it.
+ * Pure-ish: all process interaction goes through the injectable `run`.
+ */
+export async function verifyCodeSignature(binPath, opts) {
+    const platform = opts.platform ?? process.platform;
+    const run = opts.run ?? defaultRun;
+    const result = platform === 'win32'
+        ? await verifyWindows(binPath, run, opts.expectedPublisher)
+        : platform === 'darwin'
+            ? await verifyMac(binPath, run, {
+                expectedPublisher: opts.expectedPublisher,
+                expectedAppleTeamId: opts.expectedAppleTeamId,
+                requireNotarizedApp: opts.requireNotarizedApp === true,
+            })
+            : { status: 'unsupported', detail: 'no signing standard for this platform' };
+    const accepted = policyAccepts(result.status, opts.policy, platform);
+    if (!accepted) {
+        log.warn(`[engine-signature] rejected ${binPath}: status=${result.status} (${result.detail ?? ''})`);
+    }
+    else if (result.status === 'unsigned' && opts.policy === 'prefer') {
+        log.warn(`[engine-signature] ${binPath} is unsigned (allowed under policy=prefer)`);
+    }
+    return { result, accepted };
+}
+function policyAccepts(status, policy, platform) {
+    if (policy === 'off')
+        return true;
+    if (policy === 'prefer')
+        return status !== 'invalid';
+    // require
+    return (status === 'valid' ||
+        (status === 'unsupported' && platform !== 'win32' && platform !== 'darwin'));
+}
+async function verifyWindows(binPath, run, expectedPublisher) {
+    // Get-AuthenticodeSignature.Status: Valid | NotSigned | HashMismatch |
+    // NotTrusted | UnknownError | … . -LiteralPath avoids glob expansion;
+    // single quotes are doubled to escape (paths are from our own cache).
+    const escaped = binPath.replace(/'/g, "''");
+    // Windows PowerShell must build its own module path. Inheriting PowerShell
+    // 7's PSModulePath can prevent Microsoft.PowerShell.Security from loading.
+    const env = { ...process.env };
+    for (const key of Object.keys(env)) {
+        if (key.toLowerCase() === 'psmodulepath')
+            delete env[key];
+    }
+    const res = await run('powershell', [
+        '-NoProfile',
+        '-NonInteractive',
+        '-WindowStyle',
+        'Hidden',
+        '-Command',
+        `$ErrorActionPreference = 'Stop'; $sig = Get-AuthenticodeSignature -LiteralPath '${escaped}'; Write-Output ([string]$sig.Status); Write-Output ([string]$sig.SignerCertificate.Subject)`,
+    ], { env });
+    if (isSpawnFailure(res.code)) {
+        return { status: 'unsupported', detail: `could not run powershell (${res.code})` };
+    }
+    if (res.code !== 0) {
+        return {
+            status: 'invalid',
+            detail: `Authenticode verification failed (exit ${res.code}): ${res.stderr.trim().slice(0, 1000) || 'no diagnostic output'}`,
+        };
+    }
+    const [status = '', ...subjectLines] = res.stdout.trim().split(/\r?\n/);
+    const subject = subjectLines.join(' ').trim();
+    if (status === 'Valid') {
+        // Substring, not equality: this is a full DN
+        // (`CN=Bendyline LLC,O=Bendyline LLC,L=…`), and normalizing both sides
+        // keeps the match working if the CN is ever reissued with the comma form
+        // Apple's certificate already uses.
+        if (expectedPublisher &&
+            !normalizeIdentityName(subject).includes(normalizeIdentityName(expectedPublisher))) {
+            return {
+                status: 'invalid',
+                detail: `unexpected Authenticode publisher: ${subject || 'missing signer subject'}`,
+            };
+        }
+        return { status: 'valid', ...(subject ? { detail: subject } : {}) };
+    }
+    if (status === 'NotSigned')
+        return { status: 'unsigned' };
+    return { status: 'invalid', detail: `Authenticode status: ${status || 'unknown'}` };
+}
+/**
+ * Collapse case, punctuation, and spacing so the same organization compares
+ * equal across certificates that spell it differently — `Bendyline, LLC` on
+ * Apple's leaf vs `Bendyline LLC` on the Authenticode DN.
+ */
+function normalizeIdentityName(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, '');
+}
+/** Leaf `Developer ID Application` authority, split into name and team id. */
+function parseDeveloperIdAuthority(text) {
+    const withTeam = /^Authority=Developer ID Application:\s*(.*?)\s*\(([A-Za-z0-9]+)\)\s*$/im.exec(text);
+    if (withTeam?.[1] && withTeam[2])
+        return { name: withTeam[1], teamId: withTeam[2] };
+    const bare = /^Authority=Developer ID Application:\s*(.+?)\s*$/im.exec(text);
+    return bare?.[1] ? { name: bare[1] } : null;
+}
+async function verifyMac(binPath, run, opts = {}) {
+    const { expectedPublisher, expectedAppleTeamId, requireNotarizedApp = false } = opts;
+    // `codesign --verify` exits 0 for a valid signature, non-zero otherwise.
+    const verify = await run('codesign', ['--verify', '--strict', binPath]);
+    if (isSpawnFailure(verify.code)) {
+        return { status: 'unsupported', detail: `could not run codesign (${verify.code})` };
+    }
+    // `-dvv`, not `-dv`: `Authority=` lines only appear from the second
+    // verbosity level up. At `-dv` the publisher check can never pass, because
+    // the string it looks for is never printed.
+    const info = await run('codesign', ['-dvv', binPath]);
+    const raw = `${info.stdout}\n${info.stderr}`;
+    const blob = raw.toLowerCase();
+    if (verify.code === 0) {
+        if (expectedPublisher || expectedAppleTeamId) {
+            const authority = parseDeveloperIdAuthority(raw);
+            if (!authority) {
+                return {
+                    status: 'invalid',
+                    detail: `no Developer ID Application authority for ${binPath}`,
+                };
+            }
+            if (expectedPublisher &&
+                normalizeIdentityName(authority.name) !== normalizeIdentityName(expectedPublisher)) {
+                return {
+                    status: 'invalid',
+                    detail: `unexpected Developer ID authority for ${binPath}: ${authority.name}`,
+                };
+            }
+            if (expectedAppleTeamId && authority.teamId !== expectedAppleTeamId) {
+                return {
+                    status: 'invalid',
+                    detail: `unexpected Apple team for ${binPath}: ${authority.teamId ?? 'none'}`,
+                };
+            }
+        }
+        if (requireNotarizedApp) {
+            if (!/\.app\/?$/i.test(binPath)) {
+                return {
+                    status: 'invalid',
+                    detail: 'Gatekeeper notarization assessment requires a parent .app bundle',
+                };
+            }
+            const assessment = await run('spctl', [
+                '--assess',
+                '--type',
+                'execute',
+                '--verbose=4',
+                binPath,
+            ]);
+            if (isSpawnFailure(assessment.code)) {
+                return {
+                    status: 'unsupported',
+                    detail: `could not run Gatekeeper assessment (${assessment.code})`,
+                };
+            }
+            const assessmentText = `${assessment.stdout}\n${assessment.stderr}`.toLowerCase();
+            if (assessment.code !== 0 || !assessmentText.includes('source=notarized developer id')) {
+                return {
+                    status: 'invalid',
+                    detail: `Gatekeeper did not confirm notarization: ${assessmentText.trim() || 'assessment failed'}`,
+                };
+            }
+        }
+        return { status: 'valid' };
+    }
+    // Distinguish unsigned from a bad/tampered signature.
+    if (blob.includes('not signed at all') || blob.includes('no signature')) {
+        return { status: 'unsigned' };
+    }
+    return { status: 'invalid', detail: 'codesign --verify failed' };
+}
+/**
+ * Best-effort: clear the macOS `com.apple.quarantine` xattr so a
+ * freshly-downloaded binary isn't blocked by Gatekeeper on first exec.
+ * No-op (and never throws) off macOS or when the attr isn't present.
+ */
+export async function stripQuarantine(binPath, opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    if (platform !== 'darwin')
+        return;
+    const run = opts.run ?? defaultRun;
+    await run('xattr', ['-d', 'com.apple.quarantine', binPath]).catch(() => { });
+}

package/dist/fs/atomic.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Write a file atomically by writing to a sibling tmp path and then
+ * renaming over the target. `rename` is atomic on NTFS, ext4, and
+ * APFS from the application's perspective — readers see either the
+ * previous file or the new one, never an in-between zeroed file.
+ *
+ * The fix this exists for: a plain `fs.writeFile` truncates + extends
+ * the target file's size on disk independently of the data flush. A
+ * power loss or force-kill between the size extension and the actual
+ * data write leaves a file whose on-disk size says N bytes but whose
+ * contents are all-NUL — which `JSON.parse` then chokes on with
+ * `Unexpected token '' is not valid JSON`. Writing to a tmp file
+ * first means the target path is never in that intermediate state.
+ *
+ * Accepts strings (treated as utf8) and binary `Uint8Array` / `Buffer`
+ * payloads. Callers that previously used `writeFile(p, data)` (no
+ * encoding arg, binary data) can swap in `writeFileAtomic(p, data)`
+ * with no other change.
+ *
+ * `durable: true` additionally fsyncs the staged file before rename and,
+ * where the platform supports it, the parent directory afterward. Use it for
+ * recovery journals and ownership markers whose survival across power loss is
+ * required to decide whether later cleanup is safe.
+ *
+ * The tmp name includes pid + a random suffix so concurrent writers
+ * (multiple gezeld processes, or two threads in the same process)
+ * don't collide on the same staging path. On rename failure we try
+ * to unlink the orphaned tmp; that's best-effort because a partial
+ * tmp is harmless — the next write will pick a fresh name.
+ *
+ * NOT used for:
+ *   - append-only logs (HistoryManager's `history.jsonl`, daily
+ *     memory markdown) — those use `appendFile` by design and don't
+ *     suffer the truncate-extend race
+ *   - native binary trees / extracted runtimes (supervisor-owned)
+ *   - sandboxed script outputs and other external working copies
+ *
+ * See CLAUDE.md "Don't bypass the Store" / carve-outs section for
+ * the canonical list of paths that opt out of this contract.
+ */
+export declare function writeFileAtomic(absPath: string, content: string | Uint8Array, opts?: {
+    mode?: number;
+    durable?: boolean;
+    noReplace?: boolean;
+}): Promise<void>;
+/**
+ * Atomically publish an existing file without first loading it into memory.
+ * This is the file-backed twin of {@link writeFileAtomic}: large connector
+ * attachments (release installers, disk images, archives) are streamed to a
+ * private staging file by their adapter, then copied to a sibling temporary
+ * path and renamed into place.
+ */
+export declare function copyFileAtomic(sourcePath: string, absPath: string): Promise<void>;

package/dist/fs/atomic.js

@@ -0,0 +1,202 @@
+import { randomUUID } from 'node:crypto';
+import { chmod, copyFile, link, lstat, open, rename, rm, writeFile, } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+/**
+ * Write a file atomically by writing to a sibling tmp path and then
+ * renaming over the target. `rename` is atomic on NTFS, ext4, and
+ * APFS from the application's perspective — readers see either the
+ * previous file or the new one, never an in-between zeroed file.
+ *
+ * The fix this exists for: a plain `fs.writeFile` truncates + extends
+ * the target file's size on disk independently of the data flush. A
+ * power loss or force-kill between the size extension and the actual
+ * data write leaves a file whose on-disk size says N bytes but whose
+ * contents are all-NUL — which `JSON.parse` then chokes on with
+ * `Unexpected token '' is not valid JSON`. Writing to a tmp file
+ * first means the target path is never in that intermediate state.
+ *
+ * Accepts strings (treated as utf8) and binary `Uint8Array` / `Buffer`
+ * payloads. Callers that previously used `writeFile(p, data)` (no
+ * encoding arg, binary data) can swap in `writeFileAtomic(p, data)`
+ * with no other change.
+ *
+ * `durable: true` additionally fsyncs the staged file before rename and,
+ * where the platform supports it, the parent directory afterward. Use it for
+ * recovery journals and ownership markers whose survival across power loss is
+ * required to decide whether later cleanup is safe.
+ *
+ * The tmp name includes pid + a random suffix so concurrent writers
+ * (multiple gezeld processes, or two threads in the same process)
+ * don't collide on the same staging path. On rename failure we try
+ * to unlink the orphaned tmp; that's best-effort because a partial
+ * tmp is harmless — the next write will pick a fresh name.
+ *
+ * NOT used for:
+ *   - append-only logs (HistoryManager's `history.jsonl`, daily
+ *     memory markdown) — those use `appendFile` by design and don't
+ *     suffer the truncate-extend race
+ *   - native binary trees / extracted runtimes (supervisor-owned)
+ *   - sandboxed script outputs and other external working copies
+ *
+ * See CLAUDE.md "Don't bypass the Store" / carve-outs section for
+ * the canonical list of paths that opt out of this contract.
+ */
+export async function writeFileAtomic(absPath, content, opts) {
+    const tmp = `${absPath}.tmp-${process.pid}-${randomUUID()}`;
+    // When a mode is given (secret files), create the tmp with it so the
+    // file is never group/world-readable even momentarily — the prior
+    // "write at umask, chmod 0600 afterwards" pattern left a TOCTOU window
+    // in which a local watcher could open the still-0644 file. `rename`
+    // preserves the tmp's mode, so the published target lands at `mode`.
+    let mode = opts?.mode;
+    if (mode === undefined && !opts?.noReplace && process.platform !== 'win32') {
+        try {
+            const existing = await lstat(absPath);
+            // Preserve ordinary permissions, including executable bits. A symlink
+            // is replaced as a link, so its target's permissions do not apply here.
+            if (existing.isFile())
+                mode = existing.mode & 0o777;
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+        }
+    }
+    const modeOpt = mode !== undefined ? { mode } : {};
+    try {
+        if (typeof content === 'string') {
+            await writeFile(tmp, content, { encoding: 'utf8', ...modeOpt });
+        }
+        else {
+            await writeFile(tmp, content, modeOpt);
+        }
+        // Creation applies the process umask. Restore the intended permissions
+        // before publication, even under a more restrictive current umask.
+        if (mode !== undefined && process.platform !== 'win32')
+            await chmod(tmp, mode);
+        if (opts?.durable)
+            await fsyncPath(tmp);
+        if (opts?.noReplace) {
+            // A hard link publishes the fully written sibling inode only when the
+            // destination is absent. This gives backups create-only semantics
+            // without exposing a partially written target or a check/write race.
+            await link(tmp, absPath);
+            await rm(tmp, { force: true }).catch(() => undefined);
+            if (opts.durable)
+                await fsyncDirectoryIfSupported(dirname(absPath));
+            return;
+        }
+        await renameWithWindowsRetry(tmp, absPath);
+        if (opts?.durable)
+            await fsyncDirectoryIfSupported(dirname(absPath));
+    }
+    catch (err) {
+        try {
+            await rm(tmp, { force: true });
+        }
+        catch {
+            // ignore — leftover tmp is harmless
+        }
+        throw err;
+    }
+}
+/**
+ * Atomically publish an existing file without first loading it into memory.
+ * This is the file-backed twin of {@link writeFileAtomic}: large connector
+ * attachments (release installers, disk images, archives) are streamed to a
+ * private staging file by their adapter, then copied to a sibling temporary
+ * path and renamed into place.
+ */
+export async function copyFileAtomic(sourcePath, absPath) {
+    const tmp = `${absPath}.tmp-${process.pid}-${randomUUID()}`;
+    try {
+        await copyFile(sourcePath, tmp);
+        await renameWithWindowsRetry(tmp, absPath);
+    }
+    catch (err) {
+        try {
+            await rm(tmp, { force: true });
+        }
+        catch {
+            // ignore — leftover tmp is harmless
+        }
+        throw err;
+    }
+}
+async function fsyncPath(path) {
+    // Windows requires a handle opened with write access for FlushFileBuffers;
+    // POSIX accepts the same mode for fsync(2).
+    const handle = await open(path, 'r+');
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * POSIX needs the containing directory synced for the rename itself to survive
+ * power loss. Windows does not consistently permit opening directories as
+ * file handles; the file flush above is still honored there and unsupported
+ * directory-sync errors are ignored.
+ */
+async function fsyncDirectoryIfSupported(path) {
+    let handle;
+    try {
+        handle = await open(path, 'r');
+        await handle.sync();
+    }
+    catch (err) {
+        const code = err.code;
+        if (process.platform === 'win32' &&
+            (code === 'EACCES' || code === 'EINVAL' || code === 'ENOTSUP' || code === 'EPERM')) {
+            return;
+        }
+        throw err;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+/**
+ * `rename` retry loop for Windows. On POSIX filesystems rename is
+ * straightforwardly atomic and the first call succeeds; on Windows
+ * (NTFS) it can fail transiently with `EPERM` / `EACCES` / `EBUSY`
+ * when something else briefly holds the target file open — Windows
+ * Defender's real-time scan is the most common culprit, but the
+ * Search indexer, IDE file watchers, or backup utilities can do it
+ * too. The lock window is typically tens of milliseconds.
+ *
+ * Strategy: try the rename, and on a transient error retry up to
+ * `maxAttempts` times with exponential backoff (10ms, 20ms, 40ms,
+ * 80ms, 160ms — total ~310ms worst case before giving up). Any
+ * non-transient error (ENOENT, EROFS, etc.) fails fast on the
+ * first attempt. POSIX never enters the retry path because the
+ * first rename succeeds.
+ *
+ * Without this, `writeFileAtomic` flakes on Windows under typical
+ * developer environments (AV running, IDE watching). The plain
+ * `fs.writeFile` it replaced didn't have this problem because it
+ * doesn't rename — but it ALSO doesn't survive crashes, which is
+ * the whole reason this helper exists. Retry restores that
+ * tradeoff on the platform where it costs the most.
+ */
+async function renameWithWindowsRetry(from, to) {
+    const maxAttempts = 6;
+    let delayMs = 10;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            await rename(from, to);
+            return;
+        }
+        catch (err) {
+            const code = err.code;
+            const transient = code === 'EPERM' || code === 'EACCES' || code === 'EBUSY';
+            if (!transient || attempt === maxAttempts)
+                throw err;
+            await sleep(delayMs);
+            delayMs *= 2;
+        }
+    }
+}

package/dist/fs/config-store.d.ts

@@ -0,0 +1,14 @@
+import { type GezelConfig } from '@bendyline/gezel';
+export declare class ConfigCorruptionError extends Error {
+    readonly code = "CONFIG_CORRUPT";
+    constructor(message: string);
+}
+/** Configuration persistence only: safe to construct in an engine-only home. */
+export declare class ConfigStore {
+    private readonly home;
+    constructor(home: string);
+    get homePath(): string;
+    readConfig(): Promise<GezelConfig>;
+    writeConfig(config: Partial<Record<keyof GezelConfig, unknown>>): Promise<GezelConfig>;
+    private writeConfigPatch;
+}