devflow-kit 1.8.2 → 2.0.0

package/dist/core/learning-queue-cleanup.js

@@ -0,0 +1,92 @@
+/**
+ * @file learning-queue-cleanup.ts
+ *
+ * Shared cleanup helpers for `.devflow/learning/`. Imported solely by
+ * `src/cli/commands/learning.ts`:
+ * - `sweepLegacyDreamMarkers` — used by `devflow learning --reset`
+ * - `drainLearningQueue` — used by `devflow learning --clear` / `--disable`
+ */
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { getLearningPendingTurnsPath, getLearningPendingTurnsProcessingPath, } from './project-paths.js';
+// ---------------------------------------------------------------------------
+// Legacy marker-pipeline sweep
+// ---------------------------------------------------------------------------
+/** Fixed-name stamps left by the retired dream marker pipeline. */
+const LEGACY_FIXED_STAMPS = ['.decisions-runs-today', '.curation-last', '.processor-spawned-at'];
+/** Per-session marker variants: (decisions|curation).*.{json,processing,retries,failed} */
+function isLegacyPerSessionMarker(name) {
+    return ((name.startsWith('decisions.') || name.startsWith('curation.')) &&
+        (name.endsWith('.json') || name.endsWith('.processing') || name.endsWith('.retries') || name.endsWith('.failed')));
+}
+/**
+ * Sweep legacy marker-pipeline files from a `.devflow/learning/` directory:
+ * the fixed-name stamps above, plus per-session `decisions.*`/`curation.*`
+ * markers. Never touches `learning.json` or the live
+ * `.pending-turns.jsonl`/`.pending-turns.processing` queue files.
+ *
+ * ENOENT-idempotent (missing learning dir or already-removed files are not
+ * errors). Non-ENOENT errors are rethrown — callers that need best-effort
+ * semantics (e.g. `--reset`, which must still finish releasing its lock)
+ * should wrap the call in their own try/catch.
+ *
+ * @returns number of files removed
+ */
+export async function sweepLegacyDreamMarkers(learningDir) {
+    let removed = 0;
+    for (const name of LEGACY_FIXED_STAMPS) {
+        try {
+            await fs.unlink(path.join(learningDir, name));
+            removed++;
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== 'ENOENT')
+                throw err;
+        }
+    }
+    try {
+        const entries = await fs.readdir(learningDir);
+        for (const entry of entries) {
+            if (isLegacyPerSessionMarker(entry)) {
+                try {
+                    await fs.unlink(path.join(learningDir, entry));
+                    removed++;
+                }
+                catch (err) {
+                    const code = err.code;
+                    if (code !== 'ENOENT')
+                        throw err;
+                }
+            }
+        }
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== 'ENOENT')
+            throw err;
+    }
+    return removed;
+}
+// ---------------------------------------------------------------------------
+// Live queue drain
+// ---------------------------------------------------------------------------
+/**
+ * Drain the learning (decisions-detection) pending-turns queue so stale turns
+ * don't process later — used by both `--clear` and `--disable`. A mid-run
+ * Learning agent whose claimed batch vanishes aborts without changes, which is
+ * the desired outcome in both cases. ENOENT-tolerant; other errors propagate.
+ */
+export async function drainLearningQueue(gitRoot) {
+    await Promise.all([
+        fs.unlink(getLearningPendingTurnsPath(gitRoot)).catch((e) => {
+            if (e.code !== 'ENOENT')
+                throw e;
+        }),
+        fs.unlink(getLearningPendingTurnsProcessingPath(gitRoot)).catch((e) => {
+            if (e.code !== 'ENOENT')
+                throw e;
+        }),
+    ]);
+}
+//# sourceMappingURL=learning-queue-cleanup.js.map

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

@@ -0,0 +1,78 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { getDevFlowDirectory } from '../targets/claude-code/claude-paths.js';
+import { getLearningTuningConfigPath } from './project-paths.js';
+const VALID_MODELS = new Set(['opus', 'sonnet', 'haiku']);
+function isValidModel(value) {
+    return typeof value === 'string' && VALID_MODELS.has(value);
+}
+const DEFAULTS = {
+    model: 'opus',
+    debug: false,
+};
+/**
+ * Apply a single JSON config layer onto a LearningTuningConfig, returning a new object.
+ * Skips fields with wrong types. Swallows parse errors — callers see defaults.
+ * Unknown fields (e.g. an old config still on disk with extra knobs) are
+ * silently ignored, not an error.
+ */
+export function applyLearningTuningConfigLayer(config, json) {
+    try {
+        const parsed = JSON.parse(json);
+        // Object-shape guard mirrors coerceConfig in feature-config.ts: a JSON
+        // array, null, or primitive can't be treated as a config record.
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            return { ...config };
+        }
+        const raw = parsed;
+        return {
+            // Only accept a model value that belongs to the closed LearningModelAlias domain.
+            model: isValidModel(raw.model) ? raw.model : config.model,
+            debug: typeof raw.debug === 'boolean' ? raw.debug : config.debug,
+        };
+    }
+    catch {
+        return { ...config };
+    }
+}
+/**
+ * Read a JSON config file and return its contents as a string, or null if absent.
+ * Returns null (not throws) on ENOENT or any other read error.
+ */
+function readConfigFile(filePath) {
+    try {
+        return fs.readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            // Warn but don't crash — callers fall back to defaults.
+            console.warn(`[learning-tuning-config] warning: could not read ${filePath}: ${err.message}`);
+        }
+        return null;
+    }
+}
+/**
+ * Load and merge learning agent tuning configuration.
+ *
+ * Priority (highest wins): project config → global config → defaults.
+ *
+ * - Global:  `~/.devflow/learning.json`
+ * - Project: `<cwd>/.devflow/learning/learning.json`
+ *
+ * Invalid JSON in either file is silently ignored and treated as absent.
+ */
+export function loadLearningTuningConfig(cwd) {
+    const globalConfigPath = path.join(getDevFlowDirectory(), 'learning.json');
+    const projectConfigPath = getLearningTuningConfigPath(cwd);
+    let config = { ...DEFAULTS };
+    const globalJson = readConfigFile(globalConfigPath);
+    if (globalJson !== null) {
+        config = applyLearningTuningConfigLayer(config, globalJson);
+    }
+    const projectJson = readConfigFile(projectConfigPath);
+    if (projectJson !== null) {
+        config = applyLearningTuningConfigLayer(config, projectJson);
+    }
+    return config;
+}
+//# sourceMappingURL=learning-tuning-config.js.map

package/dist/core/manifest.js

@@ -0,0 +1,171 @@
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { LEGACY_PLUGIN_NAMES, DELETED_PLUGIN_NAMES } from './plugins.js';
+import { VIEW_MODES } from './flags.js';
+import { normalizeComplianceFeature } from './compliance.js';
+/**
+ * Read and parse the manifest file. Returns null if missing or corrupt.
+ */
+export async function readManifest(devflowDir) {
+    const manifestPath = path.join(devflowDir, 'manifest.json');
+    try {
+        const content = await fs.readFile(manifestPath, 'utf-8');
+        const data = JSON.parse(content);
+        const features = data.features;
+        if (!data.version ||
+            !Array.isArray(data.plugins) ||
+            !data.scope ||
+            typeof features !== 'object' ||
+            features === null ||
+            typeof features.ambient !== 'boolean' ||
+            typeof features.memory !== 'boolean' ||
+            typeof data.installedAt !== 'string' ||
+            typeof data.updatedAt !== 'string') {
+            return null;
+        }
+        // Self-heal: rename features.kb → features.knowledge on disk
+        const knowledge = typeof features.knowledge === 'boolean' ? features.knowledge
+            : typeof features.kb === 'boolean' ? features.kb
+                : false;
+        // Self-heal: rename features.decisions → features.learning on disk
+        // Coalesce: features.learning wins; fall back to features.decisions; default false.
+        const learning = typeof features.learning === 'boolean' ? features.learning
+            : typeof features.decisions === 'boolean' ? features.decisions
+                : false;
+        const needsHeal = features.kb !== undefined || features.decisions !== undefined;
+        const SECURITY_MODES = ['none', 'user', 'managed'];
+        // Self-heal: non-string-array or absent knownFlags/knownPlugins → undefined (never partial/garbage)
+        const asStringArray = (val) => Array.isArray(val) && val.every(e => typeof e === 'string')
+            ? val
+            : undefined;
+        const knownFlags = asStringArray(features.knownFlags);
+        const knownPlugins = asStringArray(data.knownPlugins);
+        const manifest = {
+            version: data.version,
+            plugins: data.plugins,
+            scope: data.scope,
+            knownPlugins,
+            features: {
+                ambient: features.ambient,
+                memory: features.memory,
+                hud: typeof features.hud === 'boolean' ? features.hud : false,
+                knowledge,
+                learning,
+                rules: typeof features.rules === 'boolean' ? features.rules : true,
+                flags: Array.isArray(features.flags) ? features.flags : [],
+                knownFlags,
+                viewMode: typeof features.viewMode === 'string' && VIEW_MODES.includes(features.viewMode)
+                    ? features.viewMode
+                    : undefined,
+                security: typeof features.security === 'string' && SECURITY_MODES.includes(features.security)
+                    ? features.security
+                    : undefined,
+                // Self-heal: absent proxy field defaults to false (applies ADR-014 self-heal idiom)
+                proxy: typeof features.proxy === 'boolean' ? features.proxy : false,
+                // Self-heal: absent/malformed compliance → {enabled:false, frameworks:[]}
+                // (applies ADR-014 self-heal idiom; normalizeComplianceFeature is in TOLERANT section)
+                compliance: normalizeComplianceFeature(features.compliance),
+            },
+            installedAt: data.installedAt,
+            updatedAt: data.updatedAt,
+        };
+        if (needsHeal) {
+            await writeManifest(devflowDir, manifest);
+        }
+        return manifest;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write manifest to disk. Creates parent directory if needed.
+ */
+export async function writeManifest(devflowDir, data) {
+    await fs.mkdir(devflowDir, { recursive: true });
+    const manifestPath = path.join(devflowDir, 'manifest.json');
+    await fs.writeFile(manifestPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Update a single feature field in the manifest. No-op when no manifest exists.
+ * Reads, mutates, and writes atomically. The `updatedAt` timestamp is always refreshed.
+ *
+ * Use this in toggle commands (ambient, hud, memory, decisions, security) instead of
+ * the repeated read → if-exists → mutate → write pattern.
+ */
+export async function syncManifestFeature(devflowDir, key, value) {
+    const manifest = await readManifest(devflowDir);
+    if (!manifest)
+        return;
+    manifest.features[key] = value;
+    manifest.updatedAt = new Date().toISOString();
+    await writeManifest(devflowDir, manifest);
+}
+/**
+ * Merge new plugins into existing plugin list (union, no duplicates).
+ * Preserves order: existing plugins first, then new ones appended.
+ */
+export function mergeManifestPlugins(existing, newPlugins) {
+    const merged = [...existing];
+    for (const plugin of newPlugins) {
+        if (!merged.includes(plugin)) {
+            merged.push(plugin);
+        }
+    }
+    return merged;
+}
+/**
+ * Compare two semver strings. Returns -1, 0, or 1.
+ * Handles simple x.y.z versions; returns null for unparseable input.
+ *
+ * Note: Pre-release suffixes (e.g., `-beta.1`, `-rc.2`) are silently ignored.
+ * `1.0.0-beta.1` and `1.0.0` compare as equal. Build metadata is also ignored.
+ */
+function compareSemver(a, b) {
+    const parse = (v) => {
+        const match = v.match(/^v?(\d+)\.(\d+)\.(\d+)/);
+        return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : [];
+    };
+    const pa = parse(a);
+    const pb = parse(b);
+    if (pa.length === 0 || pb.length === 0)
+        return null;
+    for (let i = 0; i < 3; i++) {
+        if (pa[i] > pb[i])
+            return 1;
+        if (pa[i] < pb[i])
+            return -1;
+    }
+    return 0;
+}
+/**
+ * Resolve the final plugin list for a manifest write.
+ * On partial installs (--plugin flag), merge newly installed plugins into
+ * the existing manifest's plugin list. On full installs, replace entirely.
+ */
+export function resolvePluginList(installedPluginNames, existingManifest, isPartialInstall) {
+    if (existingManifest && isPartialInstall) {
+        const deletedSet = new Set(DELETED_PLUGIN_NAMES);
+        const cleaned = existingManifest.plugins
+            .filter(p => !deletedSet.has(p))
+            .map(p => LEGACY_PLUGIN_NAMES[p] ?? p);
+        return mergeManifestPlugins(cleaned, installedPluginNames);
+    }
+    return installedPluginNames;
+}
+export function detectUpgrade(currentVersion, installedVersion) {
+    if (!installedVersion) {
+        return { isUpgrade: false, isDowngrade: false, isSameVersion: false, previousVersion: null };
+    }
+    const cmp = compareSemver(currentVersion, installedVersion);
+    if (cmp === null) {
+        return { isUpgrade: false, isDowngrade: false, isSameVersion: false, previousVersion: installedVersion };
+    }
+    return {
+        isUpgrade: cmp > 0,
+        isDowngrade: cmp < 0,
+        isSameVersion: cmp === 0,
+        previousVersion: installedVersion,
+    };
+}
+//# sourceMappingURL=manifest.js.map

package/dist/core/migrations.js

@@ -0,0 +1,330 @@
+/**
+ * @file migrations.ts
+ *
+ * Run-once migration registry for devflow init. Migrations execute at most once
+ * per machine (global scope) or once per machine across all discovered projects
+ * (per-project scope). State is persisted at ~/.devflow/migrations.json.
+ *
+ * Registry holds 2.x entries only (first: canonicalise-agent-keys-v1). To add a
+ * migration, append an entry to MIGRATIONS below. No 1.x → 2.0 upgrade path.
+ */
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { writeFileAtomicExclusive } from './fs-atomic.js';
+import { getMemoryDir } from './project-paths.js';
+import { LEGACY_AGENT_KEYS, canonicaliseAgentKeys, parseAgentMappingEnvelope } from './agent-models.js';
+/**
+ * D31: Registry pattern over scattered `if (!applied.includes(...))` conditionals.
+ *
+ * A typed array of Migration entries provides:
+ * - Single authoritative list of all one-time migrations (no hunting across files)
+ * - Explicit scope field that drives the runner's dispatch logic without branching
+ *   on migration IDs
+ * - Append-only growth: adding a migration = adding an entry here, nothing else
+ *
+ * The `scope` field distinguishes global (one run per machine, no project context
+ * needed) from per-project (sweeps every discovered Claude-enabled project root).
+ *
+ * Append new migrations here.
+ *
+ * KNOWN ISSUE (out of scope for this wave): the migration runner retries a
+ * THROWING migration on every `devflow init`, forever, with no cap or backoff.
+ * This was acceptable with an empty MIGRATIONS registry (D37: the vacuous-truth
+ * case); this registry's first real entry is added below. Fix deferred.
+ *
+ * Note how that interacts with `canonicalise-agent-keys-v1`: runGlobalMigration
+ * marks a migration applied for ANY non-throwing return, and that entry never
+ * throws — it catches every I/O and parse failure and returns it as a *warning*.
+ * So it does NOT hit the unbounded-retry path. It hits the opposite one: a
+ * transient EACCES or a failed write records the migration as applied and it
+ * never runs again, leaving legacy keys on disk permanently.
+ *
+ * That is survivable by design rather than by luck: `readAgentMapping` applies
+ * canonicaliseAgentKeys on EVERY read, so a user whose disk migration silently
+ * failed still resolves their overrides correctly, and the next write persists
+ * the canonical keys. The disk file self-heals; only the one-time rewrite is
+ * lost. A future fix should make genuine I/O failure (as distinct from
+ * "malformed file, skip it") throw so the runner retries it.
+ */
+export const MIGRATIONS = [
+    {
+        id: 'canonicalise-agent-keys-v1',
+        description: 'Rename legacy agent keys in ~/.devflow/agent-models.json to their canonical names',
+        scope: 'global',
+        async run(ctx) {
+            const infos = [];
+            const warnings = [];
+            // Fast path: no legacy keys defined — skip without touching the file.
+            if (Object.keys(LEGACY_AGENT_KEYS).length === 0)
+                return { infos, warnings };
+            const filePath = path.join(ctx.devflowDir, 'agent-models.json');
+            // parseAgentMappingEnvelope handles IO, BOM-strip, JSON parse, and shape validation.
+            // Raw read intentionally avoids readAgentMapping (which would drop unknown fields).
+            const envelope = await parseAgentMappingEnvelope(filePath);
+            if (envelope.kind === 'skip')
+                return { infos, warnings };
+            if (envelope.kind === 'warn') {
+                warnings.push(`canonicalise-agent-keys-v1: ${envelope.message}`);
+                return { infos, warnings };
+            }
+            const onWarning = (msg) => warnings.push(msg);
+            const { agents: migrated, didMutate, renamed, dropped, guardDropped } = canonicaliseAgentKeys(envelope.rawAgents, onWarning);
+            if (!didMutate)
+                return { infos, warnings };
+            // Write back with the canonical keys, preserving the rest of the envelope.
+            // Idempotent under concurrent execution (no lock needed; see D31 comment above).
+            const updated = { ...envelope.envelope, agents: migrated };
+            try {
+                await writeFileAtomicExclusive(filePath, JSON.stringify(updated, null, 2) + '\n');
+            }
+            catch (err) {
+                warnings.push(`canonicalise-agent-keys-v1: failed to write ${filePath}: ${err.message}`);
+                return { infos, warnings };
+            }
+            if (renamed.length > 0) {
+                infos.push(`Migrated agent-models.json: renamed ${renamed.map(k => `'${k}' → '${LEGACY_AGENT_KEYS[k]}'`).join(', ')}`);
+            }
+            if (dropped.length > 0) {
+                warnings.push(`canonicalise-agent-keys-v1: dropped legacy key(s) ${dropped.map(k => `'${k}'`).join(', ')} — canonical key already present, existing value kept`);
+            }
+            if (guardDropped.length > 0) {
+                warnings.push(`canonicalise-agent-keys-v1: dropped legacy key(s) ${guardDropped.map(k => `'${k}'`).join(', ')} — skipped due to prototype-pollution guard`);
+            }
+            return { infos, warnings };
+        },
+    },
+];
+const MIGRATIONS_FILE = 'migrations.json';
+/**
+ * D30: State lives at `~/.devflow/migrations.json` (scope-independent) rather
+ * than the install manifest because:
+ *
+ * - The install manifest is scope-specific: user-scope manifests live at
+ *   `~/.devflow/manifest.json` while local-scope manifests live at
+ *   `.devflow/manifest.json` inside the repo. A migration that runs on user-scope
+ *   init wouldn't be recorded in a local-scope manifest, so the migration would
+ *   re-run on the next local-scope init.
+ * - Migration state is machine-wide: once a global migration runs on a machine it
+ *   should never re-run regardless of which project or scope triggered devflow init.
+ * - `~/.devflow/migrations.json` is always writable (home-dir location), whereas
+ *   local-scope devflowDir may be inside a read-only checkout.
+ *
+ * @param devflowDir - absolute path to `~/.devflow` (always the home-dir location)
+ */
+export async function readAppliedMigrations(devflowDir) {
+    const filePath = path.join(devflowDir, MIGRATIONS_FILE);
+    try {
+        const raw = await fs.readFile(filePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed.applied))
+            return [];
+        return parsed.applied;
+    }
+    catch {
+        // File missing or malformed — treat as empty
+        return [];
+    }
+}
+/**
+ * Write applied migration IDs to `~/.devflow/migrations.json` atomically.
+ * Uses exclusive-create tmp + rename so readers never observe a partial file
+ * and a stale tmp from a previous crash does not silently overwrite good data.
+ *
+ * Delegates to `writeFileAtomicExclusive` in fs-atomic.ts (D34/D39: canonical
+ * TS atomic-write helper with race-tolerant unlink before retry).
+ *
+ * @param devflowDir - absolute path to `~/.devflow`
+ * @param ids - full list of applied migration IDs (cumulative, not incremental)
+ */
+export async function writeAppliedMigrations(devflowDir, ids) {
+    await fs.mkdir(devflowDir, { recursive: true });
+    const filePath = path.join(devflowDir, MIGRATIONS_FILE);
+    const data = { applied: ids };
+    const content = JSON.stringify(data, null, 2) + '\n';
+    await writeFileAtomicExclusive(filePath, content);
+}
+/**
+ * Surface migration result infos, warnings, failures, and newly-applied IDs
+ * to the user via the provided logger.
+ *
+ * Extracted from runMigrationsWithFallback (init.ts) so reporting can be
+ * tested independently of the project-list routing logic.
+ */
+export function reportMigrationResult(result, logger, verbose) {
+    for (const f of result.failures) {
+        // D33: Non-fatal — warn but continue; migration will retry on next init
+        const where = f.project ? ` in ${path.basename(f.project)}` : '';
+        logger.warn(`Migration '${f.id}'${where} failed: ${f.error.message}`);
+    }
+    for (const info of result.infos) {
+        logger.info(info);
+    }
+    for (const warn of result.warnings) {
+        logger.warn(warn);
+    }
+    if (result.newlyApplied.length > 0) {
+        logger.success(`Applied ${result.newlyApplied.length} migration(s)`);
+    }
+    if (verbose) {
+        for (const id of result.newlyApplied)
+            logger.info(`  ✓ ${id}`);
+    }
+}
+/**
+ * Process an array of items with at most `limit` concurrent Promises.
+ * Returns PromiseSettledResult for every item in the original order.
+ */
+async function pooled(items, limit, fn) {
+    const results = [];
+    for (let i = 0; i < items.length; i += limit) {
+        const chunk = items.slice(i, i + limit);
+        const chunkResults = await Promise.allSettled(chunk.map(fn));
+        results.push(...chunkResults);
+    }
+    return results;
+}
+/**
+ * Run a single global migration, returning { applied, failure, infos, warnings }.
+ *
+ * D33: Non-fatal semantics — if a global migration fails, we record the failure
+ * and continue. The failing migration is NOT marked as applied so it retries on
+ * the next `devflow init` run (transient errors such as filesystem contention
+ * are eventually resolved without blocking the install).
+ */
+async function runGlobalMigration(migration, ctx) {
+    try {
+        const runResult = await migration.run(ctx);
+        return { applied: true, failure: null, infos: runResult.infos, warnings: runResult.warnings };
+    }
+    catch (error) {
+        return {
+            applied: false,
+            failure: {
+                id: migration.id,
+                scope: migration.scope,
+                error: error instanceof Error ? error : new Error(String(error)),
+            },
+            infos: [],
+            warnings: [],
+        };
+    }
+}
+/**
+ * Run a single per-project migration across all discovered project roots with a
+ * concurrency cap, returning { applied, failures, infos, warnings }.
+ *
+ * D35: Per-project migrations run across all discovered projects with a
+ * concurrency cap of 16 to avoid EMFILE on machines with 50–200 projects.
+ * This matches the pattern used by `installClaudeignore` in init.ts for
+ * multi-project install — each project has its own `.memory/.decisions.lock`
+ * so there is no cross-project contention. Promise.allSettled collects all
+ * outcomes without short-circuiting on partial failures.
+ *
+ * Marking strategy: the migration is considered applied globally only when
+ * ALL projects succeed. Any per-project failure causes the ID to remain
+ * unapplied so the next `devflow init` (which may discover the same or
+ * additional projects) can retry the failed projects.
+ *
+ * D37: runPerProjectMigration is unreachable in production — MIGRATIONS holds
+ * only a global migration (`canonicalise-agent-keys-v1`). The vacuous-truth
+ * analysis is preserved for correctness: if a per-project migration is ever
+ * added, an empty discoveredProjects list marks it applied (empty-discovery-marks-applied
+ * intended); the applied-set write is skipped only when newlyApplied is empty,
+ * which is guaranteed when MIGRATIONS has no per-project entries.
+ */
+async function runPerProjectMigration(migration, ctx, discoveredProjects) {
+    const results = await pooled(discoveredProjects, 16, (projectRoot) => {
+        const memoryDir = getMemoryDir(projectRoot);
+        return migration.run({
+            scope: 'per-project',
+            devflowDir: ctx.devflowDir,
+            memoryDir,
+            projectRoot,
+        });
+    });
+    const failures = [];
+    const infos = [];
+    const warnings = [];
+    for (const [i, result] of results.entries()) {
+        if (result.status === 'rejected') {
+            failures.push({
+                id: migration.id,
+                scope: migration.scope,
+                project: discoveredProjects[i],
+                error: result.reason instanceof Error ? result.reason : new Error(String(result.reason)),
+            });
+        }
+        else {
+            infos.push(...result.value.infos);
+            warnings.push(...result.value.warnings);
+        }
+    }
+    const applied = results.every(r => r.status === 'fulfilled');
+    return { applied, failures, infos, warnings };
+}
+/**
+ * Run all unapplied migrations from MIGRATIONS.
+ *
+ * D32: Always-run-unapplied semantics (no fresh-vs-upgrade branch).
+ * MIGRATIONS currently holds one global migration (`canonicalise-agent-keys-v1`);
+ * on a fresh machine the loop executes once and writes migrations.json. On
+ * subsequent runs the ID is already in the applied set and the loop is a no-op.
+ *
+ * @param ctx - devflowDir (memoryDir and projectRoot filled per-project)
+ * @param discoveredProjects - absolute paths to discovered Claude-enabled project roots
+ * @param registryOverride - override MIGRATIONS for testing (defaults to module-level MIGRATIONS)
+ */
+export async function runMigrations(ctx, discoveredProjects, registryOverride) {
+    const registry = registryOverride ?? MIGRATIONS;
+    // Always read from home-dir devflow location so state is machine-wide
+    const homeDevflowDir = path.join(os.homedir(), '.devflow');
+    const appliedArray = await readAppliedMigrations(homeDevflowDir);
+    // Convert to Set once for O(1) lookups throughout the loop (issue #9)
+    const applied = new Set(appliedArray);
+    const newlyApplied = [];
+    const failures = [];
+    const infos = [];
+    const warnings = [];
+    for (const migration of registry) {
+        if (applied.has(migration.id))
+            continue; // Already done — skip
+        if (migration.scope === 'global') {
+            const globalCtx = {
+                scope: 'global',
+                devflowDir: ctx.devflowDir,
+            };
+            const outcome = await runGlobalMigration(migration, globalCtx);
+            if (outcome.applied) {
+                newlyApplied.push(migration.id);
+                infos.push(...outcome.infos);
+                warnings.push(...outcome.warnings);
+            }
+            else if (outcome.failure) {
+                failures.push(outcome.failure);
+            }
+        }
+        else if (migration.scope === 'per-project') {
+            const outcome = await runPerProjectMigration(migration, ctx, discoveredProjects);
+            failures.push(...outcome.failures);
+            infos.push(...outcome.infos);
+            warnings.push(...outcome.warnings);
+            if (outcome.applied) {
+                newlyApplied.push(migration.id);
+            }
+        }
+        else {
+            // Exhaustiveness check — AnyMigration covers all MigrationScope values;
+            // migration is narrowed to `never` here so this branch is unreachable at runtime.
+            const _exhaustive = migration;
+            void _exhaustive;
+            throw new Error('Unknown migration scope');
+        }
+    }
+    // Write state once at end, accumulating all newly applied IDs (issue #5 — O(N²) → O(1))
+    if (newlyApplied.length > 0) {
+        await writeAppliedMigrations(homeDevflowDir, [...appliedArray, ...newlyApplied]);
+    }
+    return { newlyApplied, failures, infos, warnings };
+}
+//# sourceMappingURL=migrations.js.map