devflow-kit 2.4.0 → 3.0.0

package/dist/core/feature-config.js

@@ -1,125 +1,260 @@
 import * as path from 'path';
 import { promises as fs } from 'fs';
 import { getFeatureConfigPath } from './project-paths.js';
+import { parseTrackerId } from './tracker.js';
+import { loadProjectConfigLib } from './evidence-policy.js';
+/**
+ * Keys devflow itself once wrote and has retired. A managed write drops them
+ * rather than carrying them; no reader consults them.
+ *
+ * D-FEATURES-NARROW-ONLY: `memory`, `learning` and `knowledge` were top-level
+ * per-repo feature switches from the per-repo-install era. A repository now
+ * narrows a feature only through the `features` namespace, so a stale top-level
+ * value must neither decide anything nor linger to be mistaken for a switch:
+ * carrying it would leave a `learning: false` in the file that no longer does
+ * what it says. `decisions` is the pre-rename spelling of `learning`;
+ * `autoCommit` is inert. `features` is deliberately NOT here — it is a live key,
+ * carried like any other unmanaged key (avoids PF-071).
+ */
+const RETIRED_CONFIG_KEYS = new Set([
+    'memory', 'learning', 'knowledge', 'decisions', 'autoCommit',
+]);
 export const DEFAULT_CONFIG = {
-    memory: true,
-    learning: true,
-    knowledge: true,
     reviewPublication: 'auto',
 };
 export function getConfigPath(projectRoot) {
     return getFeatureConfigPath(projectRoot);
 }
+/**
+ * Parse the per-repo tracker override from the raw config value.
+ *
+ * Pure. Delegates membership to `parseTrackerId` rather than re-spelling a
+ * closed-domain ternary the way `reviewPublication` does: `reviewPublication`
+ * self-heals any invalid value to `'auto'`, which is correct for a publication
+ * mode and wrong for a provider — a repaired provider is the laundering path
+ * GAP-10 names, and §14.2 gives the invalid case its own DEGRADED reason, which
+ * only exists if the parse REFUSES instead of healing.
+ *
+ * An empty string reads as absent: `"tracker": ""` is an unset key with a
+ * character in it, not an attempt to name a provider.
+ *
+ * A non-string JSON value (`42`, `true`, `null`, an array, an object) is
+ * `invalid`, not `absent` — a present-but-wrong-typed value means the file was
+ * edited, and reporting it as absent would make the whole class silent.
+ */
+export function parseTrackerOverride(raw) {
+    if (raw === undefined || raw === '')
+        return { kind: 'absent' };
+    // `unknown` all the way from the field: this is a boundary parse over
+    // hand-edited JSON, and a signature that promised a string would make the
+    // wrong-type arm unreachable to the compiler while it stays entirely reachable
+    // to a user with a text editor.
+    if (typeof raw !== 'string') {
+        return { kind: 'invalid', raw: JSON.stringify(raw) ?? String(raw) };
+    }
+    const parsed = parseTrackerId(raw);
+    return parsed.ok ? { kind: 'valid', provider: parsed.value } : { kind: 'invalid', raw };
+}
+/**
+ * Whether a parsed JSON value is an object a config can be read from — the one
+ * test for "the file holds a config", shared by the reader and the managed
+ * write so the two never disagree about which files count as empty.
+ */
+function isJsonObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 /**
  * Parse and narrow an unknown JSON value into a FeatureConfig, merging onto
  * DEFAULT_CONFIG. Pure function — no I/O, no side effects.
  *
- * Coalesces legacy `decisions` key into `learning` when both are present:
- * `decisions` wins (legacy-decisions-wins semantics; intentionally opposite to
- * manifest.ts's new-key-wins self-heal — migration-compat requires the old key
- * to take precedence so old configs with `decisions: false` are not silently
- * re-enabled by a newer `learning: true` key).
- * Silently ignores `autoCommit` — old configs may still contain it.
+ * The retired keys ({@link RETIRED_CONFIG_KEYS}) are ignored: an old config may
+ * still hold them, and none of them decides anything (D-FEATURES-NARROW-ONLY).
  *
  * Returns null when `parsed` is not a plain object (caller falls through to
  * the next candidate path).
  */
 function coerceConfig(parsed) {
-    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+    if (!isJsonObject(parsed))
         return null;
     const p = parsed;
-    // Coalesce decisions (legacy key) → learning. decisions wins when both present.
-    let learning = DEFAULT_CONFIG.learning;
-    if (typeof p.learning === 'boolean')
-        learning = p.learning;
-    if (typeof p.decisions === 'boolean')
-        learning = p.decisions; // decisions wins
     // Coerce reviewPublication: any invalid or absent value → 'auto' (self-heal, ADR-014 idiom).
     const rp = p.reviewPublication;
     const reviewPublication = rp === 'auto' || rp === 'full' || rp === 'off' ? rp : 'auto';
+    // The per-repo tracker override is carried through VERBATIM — never coerced,
+    // never type-filtered. Two reasons, and the second is the one a reader is
+    // likely to miss:
+    //   (a) repair is forbidden for a provider value (§14.9-6), so there is no
+    //       healed value to fall back to the way reviewPublication has 'auto';
+    //   (b) a non-string is a state parseTrackerOverride CLASSIFIES (`invalid`),
+    //       not a state this function repairs. Filtering by type here would leave
+    //       that arm reachable from a direct call to the parser and unreachable
+    //       from the file, which is the only place it can actually be written.
+    // Key PRESENCE is the whole rule: a present key is carried as written, and an
+    // absent one stays absent. `hasOwnProperty` rather than `in` because the
+    // object comes from JSON.parse at a trust boundary. Retention on disk is not
+    // decided here: the writers carry every unmanaged key from the file itself
+    // (D-CONFIG-PRESERVE-UNMANAGED).
+    const hasTracker = Object.prototype.hasOwnProperty.call(p, 'tracker');
     return {
-        memory: typeof p.memory === 'boolean' ? p.memory : DEFAULT_CONFIG.memory,
-        learning,
-        knowledge: typeof p.knowledge === 'boolean' ? p.knowledge : DEFAULT_CONFIG.knowledge,
         reviewPublication,
+        ...(hasTracker ? { tracker: p.tracker } : {}),
     };
 }
 /**
- * Read the feature config for a project root.
- * Returns DEFAULT_CONFIG when the file is missing or unreadable.
- * Applies ADR-001: .devflow/config.json is the sole source of truth;
- * `devflow init` writes it directly on first install. An absent file falls
- * through to DEFAULT_CONFIG (all features enabled by default).
+ * Read the per-repo config for a project root.
+ * Returns DEFAULT_CONFIG when the file is missing or unusable.
  */
 export async function readConfig(projectRoot) {
-    const configPath = getFeatureConfigPath(projectRoot);
+    return coerceConfig(objectOf(await readConfigBody(projectRoot))) ?? { ...DEFAULT_CONFIG };
+}
+/**
+ * Classify a config file's bytes (`null` is no file). Pure.
+ *
+ * D-CONFIG-STRICT-PARSE: `.devflow/config.json` is judged by the one parser the
+ * resolvers use (lib/project-config.cjs, D-PROJECT-STRICT-KEYS), never by a bare
+ * `JSON.parse`. The two disagreed where it mattered: `JSON.parse` keeps the
+ * LAST of two duplicate keys silently, while the resolvers read the file as
+ * saying two things and fail its keys closed — so devflow could rewrite a file
+ * into a meaning it never had. A file the parser rejects is `malformed`.
+ */
+export function classifyConfigBytes(buf, lib) {
+    const decoded = lib.decodeConfigBytes(buf);
+    if (decoded.kind === 'absent')
+        return { kind: 'absent' };
+    if (decoded.kind === 'invalid')
+        return { kind: 'malformed' };
+    let parsed;
     try {
-        const config = coerceConfig(JSON.parse(await fs.readFile(configPath, 'utf-8')));
-        if (config !== null)
-            return config;
-        return { ...DEFAULT_CONFIG };
+        parsed = JSON.parse(decoded.text);
     }
     catch {
-        return { ...DEFAULT_CONFIG };
+        return { kind: 'malformed' };
     }
+    if (!isJsonObject(parsed))
+        return { kind: 'malformed' };
+    const duplicates = lib.collectDuplicateKeyPaths(decoded.text);
+    if (duplicates === null || duplicates.size > 0)
+        return { kind: 'malformed' };
+    return { kind: 'object', value: parsed };
+}
+/** The object a config body holds, or undefined for any other body. */
+function objectOf(body) {
+    return body.kind === 'object' ? body.value : undefined;
 }
 /**
- * Write the feature config for a project root.
+ * Read and classify a project's config file. Every read of the file goes
+ * through here, so readConfig, readConfigIfPresent and writeManagedConfig agree
+ * on what an unusable file means. Never throws.
+ *
+ * D-CONFIG-NO-FOLLOW: the bytes come from the resolvers' own bounded read
+ * (lib/project-config.cjs readBoundedRegularFile, `followSymlinks` false — the
+ * read resolve-settings' readConfigFile makes), so devflow and the settings line
+ * never disagree about which file configures the repository. A symlink —
+ * dangling or not — a directory, a FIFO or a file over MAX_CONFIG_BYTES is
+ * refused unopened and reads as `unreadable`: readers configure nothing from it,
+ * and writeManagedConfig leaves it in place (D-CONFIG-NO-REPAIR) rather than
+ * writing through the link or renaming a regular file over it.
+ */
+async function readConfigBody(projectRoot, lib = loadProjectConfigLib()) {
+    if (!lib.ok)
+        return { kind: 'unreadable', detail: `config parser unavailable: ${lib.error.path}` };
+    const read = lib.value.readBoundedRegularFile(getFeatureConfigPath(projectRoot), lib.value.MAX_CONFIG_BYTES, false);
+    if (read.kind === 'absent')
+        return { kind: 'absent' };
+    if (read.kind === 'refused') {
+        return {
+            kind: 'unreadable',
+            detail: `not a regular file of at most ${lib.value.MAX_CONFIG_BYTES} bytes; a symlink is never followed`,
+        };
+    }
+    return classifyConfigBytes(read.bytes, lib.value);
+}
+/**
+ * Serialise a config body to a project's config file.
  * Creates the .devflow/ directory if missing.
  * Uses an atomic temp+rename pattern to prevent partial reads under concurrent writes.
  */
-export async function writeConfig(projectRoot, config) {
+async function writeConfigBody(projectRoot, body) {
     const configPath = getFeatureConfigPath(projectRoot);
     await fs.mkdir(path.join(projectRoot, '.devflow'), { recursive: true });
     const tmpPath = configPath + '.tmp.' + process.pid;
-    await fs.writeFile(tmpPath, JSON.stringify(config, null, 2) + '\n', { encoding: 'utf-8', mode: 0o600 });
+    await fs.writeFile(tmpPath, JSON.stringify(body, null, 2) + '\n', { encoding: 'utf-8', mode: 0o600 });
     await fs.rename(tmpPath, configPath);
 }
 /**
- * Toggle a single feature in the feature config.
- * Reads current config, applies the change, and writes back.
+ * Merge devflow's managed keys over the config body the file already holds.
+ * Pure — returns a new object and never mutates `existing`.
  *
- * D1: Non-atomic read-modify-write. Concurrent invocations of `updateFeature`
- * could lose each other's writes. Acceptable here because: (a) devflow CLI
- * commands are single-threaded user-initiated actions, and (b) the window is
- * milliseconds on a local filesystem with no concurrent writers in normal use.
- * If concurrent safety is ever required, replace with an atomic file-swap or
- * a lock file.
+ * D-CONFIG-PRESERVE-UNMANAGED (avoids PF-071): `.devflow/config.json` is a
+ * user-editable file that devflow only PARTLY owns. The managed keys come from
+ * `managed`; every other key comes from the file, verbatim and by key presence
+ * — the hand-written per-repo `tracker` override (whose invalid values must
+ * survive so their DEGRADED report can name them) and any key devflow does not
+ * know. The alternative, writing the declared shape, is a silent delete of all
+ * of them on every `devflow init`. Every writer of the file goes through here
+ * (writeManagedConfig, called by init). Only the managed key is copied from
+ * `managed`, by name, so a caller holding a whole FeatureConfig still cannot
+ * overwrite the file's override with its in-memory copy. The retired keys in
+ * RETIRED_CONFIG_KEYS are dropped, not carried. A body that is
+ * not a JSON object reads as empty, exactly as readConfigIfPresent treats it;
+ * writeManagedConfig never reaches here with a malformed file.
+ *
+ * This holds under `devflow init --reset` too: a factory reset returns
+ * devflow's own settings to their defaults through `managed`, and leaves the
+ * keys devflow never wrote alone.
  */
-export async function updateFeature(projectRoot, feature, enabled) {
-    const config = await readConfig(projectRoot);
-    await writeConfig(projectRoot, { ...config, [feature]: enabled });
+export function mergeManagedConfig(existing, managed) {
+    const fileKeys = isJsonObject(existing)
+        ? Object.fromEntries(Object.entries(existing).filter(([key]) => !RETIRED_CONFIG_KEYS.has(key)))
+        : {};
+    return {
+        ...fileKeys,
+        reviewPublication: managed.reviewPublication,
+    };
 }
 /**
- * Check whether a specific feature is enabled for the given project root.
+ * Write devflow's managed keys to a project's config, keeping every key it
+ * does not manage (D-CONFIG-PRESERVE-UNMANAGED). Never throws.
+ *
+ * D-CONFIG-NO-REPAIR: a file that exists but is malformed or unreadable
+ * (D-CONFIG-STRICT-PARSE) is left byte-for-byte as it is, and the Result says
+ * why. The file is the user's: a syntax error in it still holds their
+ * hand-written keys — the `tracker` override first among them — and a rewrite
+ * from an empty merge would delete them silently. The resolvers fail its keys
+ * closed meanwhile, so leaving it costs nothing but the managed key.
+ *
+ * D1: Non-atomic read-modify-write. A concurrent writer could lose the other's
+ * change. Acceptable because init is a single-threaded, user-initiated command
+ * and the window is milliseconds on a local filesystem; the file swap itself is
+ * atomic (temp + rename), so a reader never sees a partial file.
  */
-export async function isFeatureEnabled(projectRoot, feature) {
-    const config = await readConfig(projectRoot);
-    return config[feature];
+export async function writeManagedConfig(projectRoot, managed, lib = loadProjectConfigLib()) {
+    const configPath = getFeatureConfigPath(projectRoot);
+    const existing = await readConfigBody(projectRoot, lib);
+    if (existing.kind === 'malformed')
+        return { ok: false, error: { kind: 'malformed', path: configPath } };
+    if (existing.kind === 'unreadable') {
+        return { ok: false, error: { kind: 'unreadable', path: configPath, detail: existing.detail } };
+    }
+    try {
+        await writeConfigBody(projectRoot, mergeManagedConfig(objectOf(existing), managed));
+    }
+    catch (err) {
+        return { ok: false, error: { kind: 'write-failed', path: configPath, detail: err instanceof Error ? err.message : String(err) } };
+    }
+    return { ok: true };
 }
 /**
- * Read the feature config for a project root, returning null when the file
+ * Read the per-repo config for a project root, returning null when the file
  * is absent or malformed.
  *
  * Unlike readConfig (which falls back to DEFAULT_CONFIG on any error),
  * readConfigIfPresent distinguishes "not configured yet" (null) from
- * "configured with specific values" (FeatureConfig).  The distinction
- * matters for init-seed resolution: a present config overrides the
- * manifest for memory/learning/knowledge even when the manifest is absent.
- *
- * Applies ADR-001: .devflow/config.json is the source of truth; null means
- * the config file does not exist or is unreadable — not that all features
- * are disabled.
+ * "configured with specific values" (FeatureConfig). init relies on the
+ * distinction to carry a repo's own reviewPublication across a re-init.
  */
 export async function readConfigIfPresent(projectRoot) {
-    const configPath = getFeatureConfigPath(projectRoot);
-    try {
-        const text = await fs.readFile(configPath, 'utf-8');
-        return coerceConfig(JSON.parse(text)); // null when JSON is not a plain object
-    }
-    catch {
-        // ENOENT (absent) or SyntaxError (malformed) — treat as not present
-        return null;
-    }
+    // null when the file is absent, malformed or unreadable
+    return coerceConfig(objectOf(await readConfigBody(projectRoot)));
 }
 //# sourceMappingURL=feature-config.js.map

package/dist/core/feature-switch.js

@@ -0,0 +1,112 @@
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { writeFileAtomicExclusive } from './fs-atomic.js';
+function isJsonObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * The pre-rename key each machine feature was stored under, where one exists:
+ * `learning` was `decisions` (ADR-011) and `knowledge` was `kb`. A manifest no
+ * command has rewritten since the rename can still hold only the legacy key.
+ * `memory` was never renamed.
+ */
+const LEGACY_KEYS = {
+    learning: 'decisions',
+    knowledge: 'kb',
+};
+/**
+ * Whether a RAW parsed manifest leaves `feature` switched on. Pure.
+ *
+ * Only an explicit boolean `false` switches a feature off. A missing key, a
+ * non-boolean value, or anything that is not a manifest-shaped object reads as
+ * ON — fail-open (ADR-028), and the exact rule `queue_read_gates` applies in the
+ * shell hooks, so the CLI's status and the runtime never disagree about the
+ * same file.
+ *
+ * D-LEARNING-LEGACY-DECISIONS (a sub-decision of D-FEATURES-NARROW-ONLY):
+ * `learning` is read as `features.learning` when that is a boolean, else the
+ * legacy `features.decisions` when THAT is a boolean, else ON — readManifest's
+ * migration precedence exactly. The legacy key is otherwise honoured only once
+ * some command happens to run readManifest and heal it, so a `decisions: false`
+ * would keep learning running until then. queue_read_gates applies the same
+ * precedence.
+ *
+ * D-KNOWLEDGE-LEGACY-KB (the same sub-decision for the other renamed key):
+ * `knowledge` is read as `features.knowledge` when that is a boolean, else the
+ * legacy `features.kb` when THAT is a boolean, else ON — again readManifest's
+ * precedence exactly, so `devflow knowledge --status` reports a `kb: false`
+ * as disabled. queue_read_gates never reads knowledge, so there is no shell
+ * mirror. The knowledge write-back prose gate deliberately does not learn the
+ * legacy key (ADR-028: no prompt text for a state only an un-upgraded install
+ * can hold); readManifest rewrites `kb` to `knowledge` on the next CLI run
+ * that loads the manifest, after which that gate reads the healed key.
+ *
+ * Deliberately NOT built on readManifest(): it returns null for a manifest
+ * missing any of its required fields — reported as "on" here, as the hooks read
+ * it — and it writes its heals back to disk, which a read-only status must not.
+ */
+export function isMachineFeatureOn(rawManifest, feature) {
+    if (!isJsonObject(rawManifest))
+        return true;
+    const features = rawManifest.features;
+    if (!isJsonObject(features))
+        return true;
+    const legacyKey = LEGACY_KEYS[feature];
+    const value = legacyKey !== undefined && typeof features[feature] !== 'boolean'
+        ? features[legacyKey]
+        : features[feature];
+    return value !== false;
+}
+/**
+ * Set `feature` in a RAW parsed manifest. Pure — returns a new object and never
+ * mutates its input. Null when the value is not a manifest-shaped object (there
+ * is no `features` record to write into).
+ *
+ * Only `features.<feature>` and `updatedAt` change; every other key is carried
+ * verbatim. Writing `learning` leaves a legacy `decisions` key in place, and
+ * writing `knowledge` a legacy `kb` key, inert: the boolean just written wins
+ * over it (D-LEARNING-LEGACY-DECISIONS, D-KNOWLEDGE-LEGACY-KB). Going through
+ * readManifest()/writeManifest() instead would refuse a manifest that reader
+ * rejects, drop every key ManifestData does not model (one a newer devflow
+ * wrote, say), and persist that reader's unrelated heals as a side effect of a
+ * one-key toggle.
+ */
+export function setMachineFeature(rawManifest, feature, enabled, now) {
+    if (!isJsonObject(rawManifest) || !isJsonObject(rawManifest.features))
+        return null;
+    return {
+        ...rawManifest,
+        features: { ...rawManifest.features, [feature]: enabled },
+        updatedAt: now,
+    };
+}
+async function readRawManifest(devflowDir) {
+    try {
+        return JSON.parse(await fs.readFile(path.join(devflowDir, 'manifest.json'), 'utf-8'));
+    }
+    catch {
+        // ENOENT, EACCES or SyntaxError — no usable manifest.
+        return undefined;
+    }
+}
+/**
+ * Read the machine-wide switch from `<devflowDir>/manifest.json`. Read-only (no
+ * heal write); an absent, unreadable or malformed manifest reads as ON.
+ */
+export async function readMachineFeature(devflowDir, feature) {
+    return isMachineFeatureOn(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.
+ */
+export async function writeMachineFeature(devflowDir, feature, enabled) {
+    const next = setMachineFeature(await readRawManifest(devflowDir), 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');
+    return { ok: true, value: undefined };
+}
+//# sourceMappingURL=feature-switch.js.map

package/dist/core/flags.js

@@ -121,8 +121,8 @@ export const FLAG_REGISTRY = [
         kind: 'boolean',
         target: { type: 'setting', key: 'disableBundledSkills' },
         onPayload: true,
-        recommended: true,
-        defaultValue: true,
+        recommended: false,
+        defaultValue: false,
     },
     {
         id: 'pin-sonnet-4-6',
@@ -133,8 +133,8 @@ export const FLAG_REGISTRY = [
         kind: 'boolean',
         target: { type: 'env', key: 'ANTHROPIC_DEFAULT_SONNET_MODEL' },
         onPayload: 'claude-sonnet-4-6',
-        recommended: true,
-        defaultValue: true,
+        recommended: false,
+        defaultValue: false,
     },
     {
         // Devflow fan-outs routinely exceed the upstream default of 20.
@@ -1259,7 +1259,35 @@ export function convergeFlagsIntoSettings(settingsJson, record, opts) {
     }
     // ── Step 3: strip all managed keys, then apply the folded record ──────────
     const stripped = stripFlags(settingsJson);
-    const settings = applyFlags(stripped, folded);
-    return { settings, record: folded };
+    const applied = JSON.parse(applyFlags(stripped, folded));
+    // ── Step 4: restore the pre-strip key order (D-KEY-ORDER) ────────────────
+    const ordered = orderKeysLike(parsed, applied);
+    const beforeEnv = asPlainObject(parsed.env);
+    const afterEnv = asPlainObject(ordered.env);
+    const settings = beforeEnv && afterEnv
+        ? { ...ordered, env: orderKeysLike(beforeEnv, afterEnv) }
+        : ordered;
+    return { settings: JSON.stringify(settings, null, 2) + '\n', record: folded };
+}
+/**
+ * Return `after`'s entries ordered as `before` had them: every key `before` held,
+ * in `before`'s order, then the keys only `after` holds, in `after`'s order.
+ *
+ * D-KEY-ORDER: strip-then-apply deletes every managed key and re-adds it, so each
+ * one lands after whatever key followed it on disk. init merges the security deny
+ * list AFTER the flags, which appends `permissions` behind them; a second init then
+ * moved the flags behind `permissions` and re-init stopped being a no-op on disk
+ * (#388 AC-3). Keeping the pre-converge order makes the first run's order the stable
+ * one: a key that stays keeps its place, a key the record newly sets is appended, a
+ * key it drops is simply absent. Values are `after`'s — only the order is borrowed.
+ *
+ * `Object.fromEntries` defines each key as an own data property, so a `__proto__`
+ * key parsed from settings.json stays a key rather than becoming the prototype.
+ */
+function orderKeysLike(before, after) {
+    const has = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+    const kept = Object.keys(before).filter(k => has(after, k));
+    const added = Object.keys(after).filter(k => !has(before, k));
+    return Object.fromEntries([...kept, ...added].map(k => [k, after[k]]));
 }
 //# sourceMappingURL=flags.js.map

package/dist/core/fs-atomic.js

@@ -71,4 +71,31 @@ export async function writeFileAtomicExclusive(filePath, data) {
     }
     await fs.rename(tmp, filePath);
 }
+/**
+ * Write a Claude Code settings file (`settings.json`) atomically.
+ *
+ * D-SETTINGS-ATOMIC: every write of a Claude settings file goes through this one
+ * helper, so no command can leave a half-written file for Claude Code — or a
+ * concurrent devflow command — to read: the bytes land in a sibling temp file
+ * and one rename swaps them in ({@link writeFileAtomicExclusive}).
+ *
+ * A settings file that is a symbolic link (a dotfiles-managed `settings.json`)
+ * stays one: the temp file and the rename target the link's resolved file, so
+ * the link keeps pointing where the user pointed it. A dangling link has no file
+ * to resolve and is replaced like a missing file.
+ */
+export async function writeSettingsFileAtomic(filePath, data) {
+    await writeFileAtomicExclusive(await resolveLinkedFile(filePath), data);
+}
+/** `filePath`, or the file it resolves to when it is a symbolic link that resolves. */
+async function resolveLinkedFile(filePath) {
+    try {
+        if (!(await fs.lstat(filePath)).isSymbolicLink())
+            return filePath;
+        return await fs.realpath(filePath);
+    }
+    catch {
+        return filePath;
+    }
+}
 //# sourceMappingURL=fs-atomic.js.map

package/dist/core/hook-log-dirs.js

@@ -0,0 +1,104 @@
+import { promises as fs } from 'fs';
+import * as path from 'path';
+/**
+ * @file hook-log-dirs.ts
+ *
+ * The cap on the hooks' per-directory log folders.
+ *
+ * D-LOG-DIR-CAP: every hook logs under `~/.devflow/logs/<slug>/`, one directory
+ * per working directory a session ran in (`log-paths`' devflow_log_dir). Left
+ * uncapped they pile up — a machine was found holding 31k of them, most left by
+ * test runs in throwaway temp directories — so `devflow init` keeps the
+ * {@link MAX_HOOK_LOG_DIRS} most recently written and removes the rest, oldest
+ * first. A folder's recency is the newest mtime among the folder and the log
+ * files in it: a log that is only ever appended to leaves the folder's own mtime
+ * where the file's creation put it, so the folder mtime alone would rank the
+ * busiest project as the oldest.
+ *
+ * Every pass is bounded — at most {@link MAX_LOG_DIRS_SCANNED} folders read and
+ * {@link MAX_LOG_DIRS_PRUNED_PER_RUN} removed. The two bounds are equal, so one
+ * init clears every folder it scanned beyond the cap: a 31k backlog costs that
+ * init about seven seconds (roughly 2.2 s per 10,000 removals), and only a
+ * backlog larger than the scan bound is finished by the next init. The pass is
+ * the one-time cleanup of an existing backlog and the standing cap alike.
+ * Only directories are touched: files at the logs root (`proxy.log`) and symbolic
+ * links are left alone.
+ */
+/** How many hook log folders survive a prune — the most recently written ones. */
+export const MAX_HOOK_LOG_DIRS = 200;
+/** The most folders one prune reads; beyond it the rest wait for a later run. */
+export const MAX_LOG_DIRS_SCANNED = 100_000;
+/** The most folders one prune removes — every scanned folder, so one run clears what it read. */
+export const MAX_LOG_DIRS_PRUNED_PER_RUN = MAX_LOG_DIRS_SCANNED;
+/** The most entries read inside one folder to find its newest log. */
+const MAX_FILES_READ_PER_DIR = 64;
+/** Folders stat'ed or removed at once. */
+const IO_CHUNK = 64;
+/** The newest mtime among `dir` and the entries in it; -Infinity when unreadable. */
+async function recencyOf(dir) {
+    let newest;
+    try {
+        newest = (await fs.lstat(dir)).mtimeMs;
+    }
+    catch {
+        return -Infinity;
+    }
+    let names;
+    try {
+        names = (await fs.readdir(dir)).slice(0, MAX_FILES_READ_PER_DIR);
+    }
+    catch {
+        return newest;
+    }
+    const times = await Promise.all(names.map(name => fs.lstat(path.join(dir, name)).then(st => st.mtimeMs, () => -Infinity)));
+    return Math.max(newest, ...times);
+}
+/** Apply `fn` to every item, `IO_CHUNK` at a time. Bounded by `items.length`. */
+async function inChunks(items, fn) {
+    const out = [];
+    for (let i = 0; i < items.length; i += IO_CHUNK) {
+        out.push(...await Promise.all(items.slice(i, i + IO_CHUNK).map(fn)));
+    }
+    return out;
+}
+/**
+ * Remove the oldest hook log folders under `logsDir` beyond the cap
+ * (D-LOG-DIR-CAP). Never throws: a missing logs directory is nothing to do, and
+ * a folder that cannot be removed is counted as still over the cap.
+ */
+export async function pruneHookLogDirs(logsDir, opts = {}) {
+    const keep = opts.keep ?? MAX_HOOK_LOG_DIRS;
+    const maxRemovals = opts.maxRemovals ?? MAX_LOG_DIRS_PRUNED_PER_RUN;
+    const maxScanned = opts.maxScanned ?? MAX_LOG_DIRS_SCANNED;
+    if (!path.isAbsolute(logsDir) || path.basename(logsDir) !== 'logs') {
+        return { ok: false, error: `not a devflow logs directory: ${logsDir}` };
+    }
+    if (keep < 0 || maxRemovals < 0 || maxScanned < 0) {
+        return { ok: false, error: 'prune bounds must be non-negative' };
+    }
+    let entries;
+    try {
+        entries = await fs.readdir(logsDir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { ok: true, value: { removed: 0, overCap: 0 } };
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+    const dirs = entries
+        .filter(e => e.isDirectory())
+        .slice(0, maxScanned)
+        .map(e => path.join(logsDir, e.name));
+    if (dirs.length <= keep)
+        return { ok: true, value: { removed: 0, overCap: 0 } };
+    const recencies = await inChunks(dirs, recencyOf);
+    const oldestFirst = dirs
+        .map((dir, i) => ({ dir, recency: recencies[i] }))
+        .sort((a, b) => a.recency - b.recency);
+    const overCap = oldestFirst.slice(0, oldestFirst.length - keep);
+    const batch = overCap.slice(0, maxRemovals);
+    const outcomes = await inChunks(batch, ({ dir }) => fs.rm(dir, { recursive: true, force: true }).then(() => true, () => false));
+    const removed = outcomes.filter(Boolean).length;
+    return { ok: true, value: { removed, overCap: overCap.length - removed } };
+}
+//# sourceMappingURL=hook-log-dirs.js.map

package/dist/core/learning-tuning-config.js

@@ -57,13 +57,15 @@ function readConfigFile(filePath) {
  * Priority (highest wins): project config → global config → defaults.
  *
  * - Global:  `~/.devflow/learning.json`
- * - Project: `<cwd>/.devflow/learning/learning.json`
+ * - Project: `<ledgerRoot>/.devflow/learning/learning.json` — pass the ledger root
+ *   (getLedgerRoot), where session-start-context reads it and `devflow learning
+ *   --configure` writes it (D-LEDGER-MAIN-WORKTREE).
  *
  * Invalid JSON in either file is silently ignored and treated as absent.
  */
-export function loadLearningTuningConfig(cwd) {
+export function loadLearningTuningConfig(ledgerRoot) {
     const globalConfigPath = path.join(getDevFlowDirectory(), 'learning.json');
-    const projectConfigPath = getLearningTuningConfigPath(cwd);
+    const projectConfigPath = getLearningTuningConfigPath(ledgerRoot);
     let config = { ...DEFAULTS };
     const globalJson = readConfigFile(globalConfigPath);
     if (globalJson !== null) {