devflow-kit 3.3.0 → 3.5.0

package/dist/core/claude-md-audit.js

@@ -0,0 +1,190 @@
+/**
+ * The CLI's view of the CLAUDE.md import audit — a typed seam onto the package's
+ * own `claude-md-audit.cjs`, never a second implementation of it.
+ *
+ * D-CLAUDE-MD-IMPORT-AUDIT: the logic (import grammar, bounds, thresholds, display
+ * text, stamp format) lives once, in src/assets/scripts/claude-md-audit.cjs, because
+ * the SessionStart hook reaches only `~/.devflow/scripts/`, which `composeScripts`
+ * fills by copying `src/assets/scripts/` verbatim. This module is the typed facade
+ * `devflow init` calls, loaded with the evidence-policy seam's `loadScript` against
+ * an explicit surface map (D-POLICY-CJS-SEAM). The interfaces below are TRANSCRIBED
+ * from the script's JSDoc and are this side's only shape authority; the module is
+ * required from `scriptsDir()` (the package's own copy), never from the installed
+ * `~/.devflow/scripts`, which may be older than this CLI.
+ *
+ * Nothing here throws: a load failure, a script that throws and a stamp that cannot
+ * be written are `Result` errors, and init prints at most one degraded line for them
+ * and keeps its exit code.
+ *
+ * D-AUDIT-STAMP (the caller's half): the audit writes nothing; this module writes the
+ * stamp after the install, only under an existing machine root (a command never
+ * creates `~/.devflow` for it), only through a sibling temp file renamed into place
+ * ({@link writeFileAtomicExclusive}), and never through a link. Because
+ * `writeFileAtomicExclusive` does not refuse a symlink at the target, the write does
+ * its own `lstat` regular-file check first (AC-437): a stamp path that is a symbolic
+ * link or any other non-regular file is refused and nothing is written.
+ */
+import { promises as fs } from 'fs';
+import { join } from 'path';
+import { scriptsDir } from './assets.js';
+import { writeFileAtomicExclusive } from './fs-atomic.js';
+import { loadScript, } from './evidence-policy.js';
+/** The script, relative to src/assets/scripts/ (and ~/.devflow/scripts/). */
+export const CLAUDE_MD_AUDIT_SCRIPT_NAME = 'claude-md-audit.cjs';
+/** The stamp's basename under the machine root (`~/.devflow`). */
+export const CLAUDE_MD_AUDIT_STAMP_FILE = '.claude-md-audit';
+/**
+ * The prefix of the stamp's sibling temp file, `<stamp>.tmp.<pid>`: the one name
+ * the hook and {@link writeFileAtomicExclusive} both create, so a crash between the
+ * write and the rename leaves a name uninstall can sweep.
+ */
+export const CLAUDE_MD_AUDIT_STAMP_TMP_PREFIX = `${CLAUDE_MD_AUDIT_STAMP_FILE}.tmp.`;
+/** The stamp is created owner-only, the mode the hook's `umask 077` write gives it. */
+const STAMP_CREATE_MODE = 0o600;
+/** Every key of ClaudeMdAuditModule and the runtime kind the loader requires of it. */
+export const CLAUDE_MD_AUDIT_MODULE_SURFACE = Object.freeze({
+    FILE_THRESHOLD_BYTES: 'number',
+    CHAIN_THRESHOLD_BYTES: 'number',
+    MAX_HOPS: 'number',
+    MAX_PATHS_PER_ROOT: 'number',
+    SCAN_BYTES: 'number',
+    MAX_BYTES_READ: 'number',
+    MAX_STAMP_BYTES: 'number',
+    MAX_KEYS: 'number',
+    SKIP_FILE_BYTES: 'number',
+    NOT_SHOWN: 'string',
+    HOOK_MAGIC: 'string',
+    HOOK_END: 'string',
+    extractImports: 'function',
+    isDisplayable: 'function',
+    isRecordable: 'function',
+    formatFinding: 'function',
+    findingKey: 'function',
+    parseStamp: 'function',
+    renderStamp: 'function',
+    readStampFile: 'function',
+    audit: 'function',
+    main: 'function',
+});
+/**
+ * Load the audit script from `dir` (default: the package's own scripts directory)
+ * and shape-check its surface. Never throws.
+ */
+export function loadClaudeMdAuditModule(dir = scriptsDir()) {
+    return loadScript(join(dir, CLAUDE_MD_AUDIT_SCRIPT_NAME), CLAUDE_MD_AUDIT_MODULE_SURFACE);
+}
+// ── Roots ──────────────────────────────────────────────────────────────────────
+/**
+ * The gated root set, in the order the hook passes it: `CLAUDE.md` in the Claude
+ * config directory, then (only for a git project that is not HOME — the caller
+ * passes `null` otherwise) the project's `CLAUDE.md`, `.claude/CLAUDE.md` and
+ * `CLAUDE.local.md` at its toplevel. Ancestor directories, lazily loaded
+ * subdirectory files and `rules/*.md` are not roots.
+ */
+export function claudeMdAuditRoots(claudeDir, projectRoot) {
+    const roots = [join(claudeDir, 'CLAUDE.md')];
+    if (projectRoot !== null) {
+        roots.push(join(projectRoot, 'CLAUDE.md'), join(projectRoot, '.claude', 'CLAUDE.md'), join(projectRoot, 'CLAUDE.local.md'));
+    }
+    return roots;
+}
+/** The stamp's text when it is a regular file of at most MAX_STAMP_BYTES, else null (read as absent). */
+export async function readClaudeMdAuditStamp(devflowDir, maxBytes) {
+    const stampPath = join(devflowDir, CLAUDE_MD_AUDIT_STAMP_FILE);
+    try {
+        const st = await fs.lstat(stampPath);
+        if (!st.isFile() || st.size > maxBytes)
+            return null;
+        return await fs.readFile(stampPath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Run the audit over the gated roots. Reads only; the stamp is written by
+ * {@link writeClaudeMdAuditStamp}. Never throws.
+ */
+export async function runClaudeMdAudit(opts) {
+    const loaded = loadClaudeMdAuditModule(opts.scriptsDir);
+    if (!loaded.ok)
+        return { ok: false, error: { kind: 'load', detail: loaded.error } };
+    const audit = loaded.value;
+    try {
+        const stampText = await readClaudeMdAuditStamp(opts.devflowDir, audit.MAX_STAMP_BYTES);
+        const prior = stampText === null ? [] : audit.parseStamp(stampText).keys;
+        const roots = claudeMdAuditRoots(opts.claudeDir, opts.projectRoot);
+        if (opts.showAll !== true)
+            return { ok: true, value: audit.audit({ roots, home: opts.home, keys: prior }) };
+        const result = audit.audit({ roots, home: opts.home, keys: [] });
+        const keys = [...prior.filter(key => !result.shown.includes(key)), ...result.shown].slice(-audit.MAX_KEYS);
+        return { ok: true, value: { ...result, stamp: audit.renderStamp({ roots, examined: result.examined, keys }) } };
+    }
+    catch (err) {
+        return { ok: false, error: { kind: 'failed', detail: err instanceof Error ? err.message : String(err) } };
+    }
+}
+/**
+ * Run the audit and record its stamp (D-AUDIT-STAMP): what `devflow init` does after the
+ * install. Every finding over a threshold is displayed (`showAll`), as init is a deliberate
+ * command. The stamp carries the examined paths and every key the audit displayed, so the
+ * first SessionStart afterwards repeats nothing it was just shown. A stamp that cannot be
+ * written (no machine root, a link in the way, a full disk) costs a repeated message at
+ * most, never the audit's result, so that failure is not reported. Never throws.
+ */
+export async function auditAndRecordClaudeMd(opts) {
+    const run = await runClaudeMdAudit({ ...opts, showAll: true });
+    if (run.ok)
+        await writeClaudeMdAuditStamp(opts.devflowDir, run.value.stamp);
+    return run;
+}
+/**
+ * The display lines of an audit result, as ONE note body, or null when nothing is
+ * flagged. The single formatter both init paths (Recommended and Advanced) use; the
+ * lines themselves are produced by the script's own formatter, the one the hook
+ * shows in its systemMessage.
+ */
+export function formatClaudeMdAuditNote(result) {
+    return result.lines.length === 0 ? null : result.lines.join('\n');
+}
+/** The one degraded line printed when the audit could not run. */
+export function formatClaudeMdAuditUnavailable(error) {
+    if (error.kind === 'load') {
+        return error.detail.kind === 'not-found'
+            ? 'CLAUDE.md import audit unavailable: audit script not found — reinstall devflow-kit'
+            : 'CLAUDE.md import audit unavailable: audit script failed to load — reinstall devflow-kit';
+    }
+    return 'CLAUDE.md import audit unavailable: the audit failed';
+}
+/**
+ * Write the stamp text to `<devflowDir>/.claude-md-audit` (AC-437, D-AUDIT-STAMP).
+ *
+ * Refuses, writing nothing: a machine root that does not exist; a stamp path that is
+ * a symbolic link, a directory, a FIFO or any other non-regular file (an `lstat`
+ * check made here, because the atomic writer renames over the target without
+ * looking at what it is). Otherwise the text lands in a sibling temp file renamed
+ * into place. Never throws.
+ */
+export async function writeClaudeMdAuditStamp(devflowDir, text) {
+    try {
+        const root = await fs.stat(devflowDir).catch(() => null);
+        if (root === null || !root.isDirectory())
+            return { ok: false, error: { kind: 'no-machine-root' } };
+        const stampPath = join(devflowDir, CLAUDE_MD_AUDIT_STAMP_FILE);
+        const existing = await fs.lstat(stampPath).catch((err) => {
+            if (err.code === 'ENOENT')
+                return null;
+            throw err;
+        });
+        if (existing !== null && !existing.isFile()) {
+            return { ok: false, error: { kind: 'refused', detail: existing.isSymbolicLink() ? 'the stamp path is a symbolic link' : 'the stamp path is not a regular file' } };
+        }
+        // Owner-only, as the hook writes it: the stamp names the user's project paths.
+        await writeFileAtomicExclusive(stampPath, text, STAMP_CREATE_MODE);
+        return { ok: true, value: undefined };
+    }
+    catch (err) {
+        return { ok: false, error: { kind: 'write-failed', detail: err instanceof Error ? err.message : String(err) } };
+    }
+}
+//# sourceMappingURL=claude-md-audit.js.map

package/dist/core/compliance-compose.js

@@ -172,13 +172,15 @@ function collectMissingFragmentWarnings(fnName, activeFrameworks, fragments, omi
  *
  * Every framework reference is installed on every machine
  * (D-COMPLIANCE-INSTALL-ALWAYS), so file presence no longer says which
- * frameworks apply. The caller hands the agent `COMPLIANCE_FRAMEWORKS` — the
- * `COMPLIANCE` field of the settings line, which folds this machine's selection
- * with the repository's `.devflow/project.json` — and those ids alone are in force.
+ * frameworks apply. The command names the ids in the agent's prompt
+ * (D-COMPLIANCE-INJECT: the compliance directive) — the `COMPLIANCE` field of the
+ * settings line, which folds this machine's selection with the repository's
+ * `.devflow/project.json` — and those ids alone are in force. No agent takes a
+ * named lens input, so the stamp names the prompt, not a variable.
  */
 const RUNTIME_SELECTION_LINES = [
     'Every `references/{id}.md` is installed, so presence decides nothing: the ids you were given',
-    "(`COMPLIANCE_FRAMEWORKS`, this machine's plus the repository's) are the frameworks in force.",
+    "(named in your prompt; this machine's plus the repository's) are the frameworks in force.",
     'Load `references/{id}.md` for each given id and no other; `none` means generic controls only.',
     'Apply generic controls always.',
     '',

package/dist/core/feature-switch.js

@@ -80,6 +80,16 @@ export function setMachineFeature(rawManifest, feature, enabled, now) {
         updatedAt: now,
     };
 }
+/**
+ * Whether a RAW parsed manifest already records `feature` as exactly `enabled`:
+ * `features.<feature>` is that boolean. Pure. Stricter than
+ * {@link isMachineFeatureOn} on purpose — an absent key, a non-boolean value and
+ * a legacy key all read as a state without being recorded as it, so writing the
+ * explicit boolean is still a change.
+ */
+function isMachineFeatureRecorded(rawManifest, feature, enabled) {
+    return isJsonObject(rawManifest) && isJsonObject(rawManifest.features) && rawManifest.features[feature] === enabled;
+}
 async function readRawManifest(devflowDir) {
     try {
         return JSON.parse(await fs.readFile(path.join(devflowDir, 'manifest.json'), 'utf-8'));
@@ -96,14 +106,44 @@ async function readRawManifest(devflowDir) {
 export async function readMachineFeature(devflowDir, feature) {
     return isMachineFeatureOn(await readRawManifest(devflowDir), feature);
 }
+/**
+ * Whether a RAW parsed manifest has an opt-in `feature` switched on. Pure.
+ *
+ * D-BEHAVIOR-OPT-IN: only an explicit boolean `true` is on. A missing key, a
+ * non-boolean value, a manifest without a `features` record and anything that is not an
+ * object all read as OFF — fail-closed, the mirror of {@link isMachineFeatureOn}. Like
+ * that reader it is deliberately not built on readManifest(): a read-only status must
+ * not heal-write, and a manifest missing a required field is still a manifest here.
+ */
+export function isOptInFeatureOn(rawManifest, feature) {
+    if (!isJsonObject(rawManifest) || !isJsonObject(rawManifest.features))
+        return false;
+    return rawManifest.features[feature] === true;
+}
+/**
+ * Read an opt-in machine switch from `<devflowDir>/manifest.json`. Read-only (no heal
+ * write); an absent, unreadable or malformed manifest reads as OFF.
+ */
+export async function readOptInFeature(devflowDir, feature) {
+    return isOptInFeatureOn(await readRawManifest(devflowDir), feature);
+}
 /**
  * Write the machine-wide switch to `<devflowDir>/manifest.json` (atomic
  * temp + rename). Refuses with `not-installed` when there is no manifest to
  * write into — a manifest is created by `devflow init`, never by a toggle,
  * because a bare `{features: {...}}` file is not a manifest any reader accepts.
+ *
+ * D-NOOP-TOGGLE: a toggle to the value the manifest already records writes
+ * nothing. The only bytes such a write could change are `updatedAt`, and that
+ * field means "the manifest's content last changed", so a no-op must not move
+ * it. This is the one write point of `devflow memory|learning|knowledge|behavior
+ * --enable/--disable`, so the rule holds for all four at once.
  */
 export async function writeMachineFeature(devflowDir, feature, enabled) {
-    const next = setMachineFeature(await readRawManifest(devflowDir), feature, enabled, new Date().toISOString());
+    const raw = await readRawManifest(devflowDir);
+    if (isMachineFeatureRecorded(raw, feature, enabled))
+        return { ok: true, value: undefined };
+    const next = setMachineFeature(raw, feature, enabled, new Date().toISOString());
     if (next === null)
         return { ok: false, error: 'not-installed' };
     await writeFileAtomicExclusive(path.join(devflowDir, 'manifest.json'), JSON.stringify(next, null, 2) + '\n');

package/dist/core/flags.js

@@ -88,6 +88,45 @@ export const FLAG_REGISTRY = [
         recommended: true,
         defaultValue: true,
     },
+    {
+        // D-SUBAGENT-CACHE-5M: subagents write their prompt cache with the 5-minute TTL
+        // while the main session keeps the 1-hour TTL of `prompt-caching-1h` (untouched).
+        //
+        // Why: the wave-4 token audit (2026-10-10) found 99.998% of subagent cache writes
+        // are 1-hour writes, yet fewer than 0.1% of subagent requests idle longer than
+        // 5 minutes - a subagent finishes or is resumed long before a 5-minute entry
+        // lapses, so the 1-hour premium buys nothing. Modelled effect of 5m: -8.9% on
+        // subagent cache-equivalent cost, -7.7% on total.
+        //
+        // Mechanism (VENDOR BEHAVIOUR, probed 2026-10-11 on Claude Code 2.1.296 in a
+        // sandboxed session): with ENABLE_PROMPT_CACHING_1H=true and this setting at
+        // "5m", subagent requests wrote only ephemeral_5m cache (36,387 tokens, none at
+        // 1h) while the main session wrote 100% 1h (35,209). Precedence of the subagent
+        // TTL in the binary, highest first: an env var that forces 5m, env
+        // CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL, this setting, a per-agent frontmatter
+        // `experimental.cacheTtl`, ENABLE_PROMPT_CACHING_1H. The 1-hour TTL is ignored
+        // while a subscription is in overage. A Claude Code that predates the setting
+        // ignores the key, so subagents then follow ENABLE_PROMPT_CACHING_1H as before.
+        // Re-probe when the precedence matters again; this is an observation, not a spec.
+        //
+        // Rejected: per-agent `experimental.cacheTtl` - it would spread one policy over
+        // every agent file; one devflow-managed flag keeps the policy in one place.
+        //
+        // Delete guard: only "5m" is deleted on disable or uninstall, so a user's own
+        // "1h" stays (D-GUARD-SCALAR). Adoption: init seeds this flag OFF when a value
+        // that is not "5m" is already on disk (D-ADOPT-RESPECTS-USER, respectUserOwnedSettings).
+        id: 'subagent-cache-5m',
+        label: 'Subagent 5-min cache',
+        description: 'Write subagent prompt-cache entries with the 5-minute TTL; the main session keeps 1 hour',
+        hint: 'Subagents rarely idle past 5 min, so 5-min cache writes cost less',
+        blurb: '5-min cache TTL for subagents',
+        kind: 'boolean',
+        target: { type: 'setting', key: 'subagentPromptCacheTtl' },
+        onPayload: '5m',
+        settingDeleteGuard: '5m',
+        recommended: true,
+        defaultValue: true,
+    },
     {
         id: 'show-turn-duration',
         label: 'Show turn duration',
@@ -423,6 +462,34 @@ export const FLAG_REGISTRY = [
         integer: true,
         upstreamDefault: 600000,
     },
+    {
+        // D-AUTO-COMPACT-WINDOW-OPT-IN: opt-in and unset by default (undefined → manifest null →
+        // key never written). devflow writes CLAUDE_CODE_AUTO_COMPACT_WINDOW only when the user sets
+        // this flag. Init applies a seeded record without asking, which is why the default is neutral
+        // and `recommended` stays false: a smaller window compacts sooner, and a compaction
+        // mid-command is exactly what the SessionStart resume directive (D-COMPACT-RESUME-DIRECTIVE)
+        // recovers from, so the flag is not recommended until a forced mid-/implement /compact has
+        // been seen to resume at the phase after the last finished one (plan §9, a follow-up gate).
+        // The percent-based auto-compact override is a different variable that devflow deliberately
+        // never writes or names; tests/guards/no-autocompact-pct-override.test.ts keeps it out of src/.
+        // The env name was confirmed present in Claude Code 2.1.296, where it takes precedence over
+        // the in-app setting, and an in-app message names `auto` or 100k–1M (docs/reference/
+        // claude-code-flags-probe.md). No upstreamDefault: the default window and the grammar of the
+        // variable's own value were not observed, so the description states only devflow's own
+        // accepted range, 100000–1000000.
+        id: 'auto-compact-window',
+        label: 'Auto-compact window',
+        description: 'Context window size in tokens at which Claude Code auto-compacts',
+        hint: 'Sets the auto-compact window (100000-1000000); unset keeps the default',
+        blurb: 'auto-compact window size',
+        kind: 'number',
+        target: { type: 'env', key: 'CLAUDE_CODE_AUTO_COMPACT_WINDOW' },
+        recommended: false,
+        defaultValue: undefined,
+        min: 100000, // devflow sanity bound
+        max: 1000000, // devflow sanity bound
+        integer: true,
+    },
     {
         // Writes as { command: value } per Claude Code spellcheck setting shape.
         id: 'spellcheck',
@@ -941,6 +1008,78 @@ export function settingHoldsManagedShape(settingsJson, flagId) {
         return false;
     }
 }
+/**
+ * D-ADOPT-RESPECTS-USER predicate: the mirror of `settingHoldsManagedShape`.
+ *
+ * Returns true when the settings.json string carries a value at the guarded flag's
+ * target key that is NOT the flag's managed shape - a value the user (or another
+ * tool) owns, which enabling the flag would overwrite. Presence is decided with
+ * `hasOwnProperty`, so an explicit `null` counts as a value; the shape decision is
+ * delegated to `settingValueHoldsManagedShape`, never compared here.
+ *
+ * Returns false when:
+ *   - settingsJson is malformed
+ *   - root is not a plain object
+ *   - flagId is not in the registry
+ *   - the flag has no settingDeleteGuard, or is not a setting-target boolean
+ *   - the key is absent
+ *   - the on-disk value holds the managed shape
+ */
+export function settingHoldsUserValue(settingsJson, flagId) {
+    try {
+        const parsed = JSON.parse(settingsJson);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+            return false;
+        const flag = FLAG_REGISTRY_MAP.get(flagId);
+        if (!flag || flag.kind !== 'boolean' || flag.target.type !== 'setting')
+            return false;
+        if (flag.settingDeleteGuard === undefined)
+            return false;
+        const root = parsed;
+        if (!Object.prototype.hasOwnProperty.call(root, flag.target.key))
+            return false;
+        return !settingValueHoldsManagedShape(flag, root[flag.target.key]);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * D-ADOPT-RESPECTS-USER: seed a guarded setting flag OFF when adopting it ON would
+ * overwrite a value the user already owns.
+ *
+ * A flag the manifest does not record is adopted at its `defaultValue`. For a flag whose
+ * target is a settings.json key with a `settingDeleteGuard`, adopting ON writes its
+ * managed payload over whatever is on disk (the guard protects deletion, not writes).
+ * When the key already holds a value that is not the managed shape - a user's own `"1h"`
+ * under `subagentPromptCacheTtl` - that write would silently replace a deliberate choice.
+ * Such a flag is set `false` instead; with the record then claiming `false`, the converge
+ * pipeline neither writes nor deletes the user's value.
+ *
+ * Scope: only flags ABSENT from `manifestFlags` (or all of them on a fresh install, when
+ * it is null). A flag the manifest records keeps its value in `flags`, so an explicit
+ * enable still wins. `devflow init --reset` hands this an empty settings snapshot
+ * (resolveResetGatedInputs), so nothing is detected and the factory default stands. The rule is generic over guarded
+ * setting flags: no flag id is special-cased, and `settingHoldsUserValue` is the one place
+ * that decides "the disk holds something that is not ours". For a flag whose default is
+ * already OFF (suppress-attribution) it changes nothing.
+ *
+ * Two callers apply the same rule: the init seed, and the flags TUI's starting rows (an
+ * upgrade that has not run init yet would otherwise offer a Save that overwrites the value).
+ *
+ * Pure function - the settings snapshot is read by the caller and passed in.
+ */
+export function respectUserOwnedSettings(flags, manifestFlags, settingsSnapshot) {
+    const result = { ...flags };
+    for (const flag of FLAG_REGISTRY) {
+        const adoptedAtDefault = manifestFlags === null || !(flag.id in manifestFlags);
+        if (!adoptedAtDefault)
+            continue;
+        if (settingHoldsUserValue(settingsSnapshot, flag.id))
+            result[flag.id] = false;
+    }
+    return result;
+}
 /**
  * D-ATTR-GUARD: returns true when it is safe to delete a flag's target key from
  * settings. For flags with a settingDeleteGuard the key is only deleted when the

package/dist/core/fs-atomic.js

@@ -28,15 +28,20 @@ import { promises as fs } from 'fs';
  *
  * @param filePath - Absolute path to the target file.
  * @param data - UTF-8 encoded content to write.
+ * @param createMode - Permission bits the temp file is CREATED with (masked by the
+ *   umask), so a file that must be owner-only is never readable by others, not even
+ *   between the write and the rename. Omitted, the umask default applies. Either way
+ *   an existing target's mode wins (below).
  */
-export async function writeFileAtomicExclusive(filePath, data) {
+export async function writeFileAtomicExclusive(filePath, data, createMode) {
     // PID-scope the tmp name so concurrent writers from different processes
     // (e.g., two Claude Code sessions) never collide on the same .tmp path.
     // mirrors proxy-log.ts rotation at src/core/proxy-log.ts which PID-scopes
     // for the same reason.
     const tmp = `${filePath}.tmp.${process.pid}`;
+    const options = { encoding: 'utf-8', flag: 'wx', ...(createMode === undefined ? {} : { mode: createMode }) };
     try {
-        await fs.writeFile(tmp, data, { encoding: 'utf-8', flag: 'wx' });
+        await fs.writeFile(tmp, data, options);
     }
     catch (err) {
         if (err.code !== 'EEXIST')
@@ -48,7 +53,7 @@ export async function writeFileAtomicExclusive(filePath, data) {
             await fs.unlink(tmp);
         }
         catch { /* race — already removed */ }
-        await fs.writeFile(tmp, data, { encoding: 'utf-8', flag: 'wx' });
+        await fs.writeFile(tmp, data, options);
     }
     // Preserve the target's permission mode across the atomic replace.
     // A user who hardened the target (e.g. settings.json → 0600 to protect