devflow-kit 3.7.0 → 3.8.0

package/dist/core/manifest-lock.js

@@ -0,0 +1,238 @@
+/**
+ * @file manifest-lock.ts
+ *
+ * A mkdir lock for `<devflowDir>/manifest.json`. It covers two writers, which read the
+ * manifest, decide and write it back: the toggle write of the `memory`, `curation`,
+ * `knowledge` and `behavior` switches (`writeMachineFeature`) and the read heal
+ * (`readManifest`). Without a lock, a heal that parsed the file
+ * before a `--disable` landed writes its stale snapshot over the disable, after the
+ * toggle reported success. Both writers take this lock around their read and their write.
+ *
+ * Every other writer of the manifest takes no lock: `syncManifestFeature` (the `hud`,
+ * `security`, `proxy` and `tracker` toggles), the `flags` and `rules` writes, the gate
+ * level writer and init. Such a write can still overwrite a toggle that lands between its
+ * read and its write. That gap is older than this lock and is tracked in issue #587.
+ *
+ * The lock is a directory beside the manifest. `mkdir` is atomic, so one caller makes
+ * it and every other caller sees EEXIST. A holder that died leaves the directory
+ * behind; a directory older than {@link MANIFEST_LOCK_STALE_MS} counts as left over
+ * and a waiter breaks it.
+ *
+ * Breaking is where the shared hook lock (`hooks/lib/mkdir-lock.cjs`) is weak: two
+ * waiters that both saw the same stale lock can both remove it, and the second
+ * removal can hit the lock that the first waiter took in between. This module breaks
+ * a lock in two steps. The waiter renames the directory to a unique name, so only one
+ * waiter can move it, and then checks that the directory it moved really was stale.
+ * A waiter that moved a fresh lock gives it back and counts the lock as busy.
+ *
+ * The give-back leaves a short time in which the live holder's directory is not at the
+ * path, and a third caller can make a directory there. So a holder writes a random
+ * token into a file inside the directory it made, and `stillHeld()` tells it whether the
+ * directory at the path still holds that token. A holder calls it just before its write.
+ * When it answers false, the holder does not write: the heal skips, and the toggle takes
+ * the lock again. A release removes the directory only while it still holds the holder's
+ * own token. A token tells two directories apart on every file system. The device and
+ * inode numbers of a directory do not: Linux file systems often give the freed inode
+ * number of a removed directory to the next one made. The check narrows the window to
+ * the time between the check and the write itself; a directory lock cannot close it.
+ */
+import { promises as fs } from 'fs';
+import { randomBytes } from 'crypto';
+import * as path from 'path';
+/** The lock directory's name, in the machine directory beside `manifest.json`. */
+export const MANIFEST_LOCK_NAME = 'manifest.json.lock';
+/**
+ * What a stale break adds to the lock's name for the directory it moves aside:
+ * `manifest.json.lock.stale-<pid>-<12 lowercase hex>`. A break whose removal failed leaves one.
+ */
+export const MANIFEST_LOCK_STALE_MARK = '.stale-';
+/**
+ * Age after which a lock directory counts as left behind by a dead holder. The
+ * critical sections are one read and one atomic write, so a live holder is done in
+ * milliseconds.
+ */
+export const MANIFEST_LOCK_STALE_MS = 5_000;
+/** The file inside the lock directory that holds the holder's token. */
+export const MANIFEST_LOCK_TOKEN_NAME = 'holder';
+/**
+ * The longest a toggle waits for the lock. It is longer than the stale age, so a lock
+ * left by a dead holder is always broken inside the wait.
+ */
+export const MANIFEST_LOCK_WAIT_MS = 7_000;
+const POLL_MS = 25;
+/** The lock directory for `devflowDir`. */
+export function getManifestLockPath(devflowDir) {
+    return path.join(devflowDir, MANIFEST_LOCK_NAME);
+}
+function errorCode(err) {
+    return err?.code;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** `made`: this call made the directory, with its token. `exists`: another caller has it, or it was taken away at once. `unusable`: the folder cannot hold it. */
+async function makeLockDir(lockDir) {
+    try {
+        await fs.mkdir(lockDir, { recursive: false });
+    }
+    catch (err) {
+        return errorCode(err) === 'EEXIST' ? 'exists' : 'unusable';
+    }
+    const token = randomBytes(16).toString('hex');
+    try {
+        await fs.writeFile(path.join(lockDir, MANIFEST_LOCK_TOKEN_NAME), token, { flag: 'wx', mode: 0o600 });
+    }
+    catch (err) {
+        // ENOENT: the directory was taken away at once. Another failure: the directory is
+        // empty or another's, so `rmdir` removes only an empty one of ours.
+        if (errorCode(err) === 'ENOENT')
+            return 'exists';
+        await fs.rmdir(lockDir).catch(() => undefined);
+        return 'unusable';
+    }
+    return { made: token };
+}
+/** True when the directory at `lockDir` is a real directory (not a link) that holds `token`. */
+async function holdsToken(lockDir, token) {
+    try {
+        if (!(await fs.lstat(lockDir)).isDirectory())
+            return false;
+        return (await fs.readFile(path.join(lockDir, MANIFEST_LOCK_TOKEN_NAME), 'utf-8')) === token;
+    }
+    catch {
+        return false;
+    }
+}
+async function removeQuietly(dir) {
+    try {
+        await fs.rm(dir, { recursive: true, force: true });
+    }
+    catch {
+        // Best effort: a leftover renamed directory holds no lock.
+    }
+}
+/**
+ * Break a stale lock. True when the lock path is free to take again (this call removed
+ * a stale lock, or it was already gone); false when it is held by a live holder or
+ * could not be moved.
+ *
+ * The directory is renamed to a unique name before anything is removed, so of any
+ * number of waiters that judged the same lock stale, one rename succeeds and the rest
+ * get ENOENT. The rename is also where a late waiter can hit a lock that a new holder
+ * has taken since it judged: the age of the moved directory tells the two apart, and
+ * a fresh one is put back.
+ */
+async function breakStaleLock(lockDir, staleMs) {
+    try {
+        const seen = await fs.stat(lockDir);
+        if (Date.now() - seen.mtimeMs <= staleMs)
+            return false;
+    }
+    catch (err) {
+        return errorCode(err) === 'ENOENT';
+    }
+    const moved = `${lockDir}${MANIFEST_LOCK_STALE_MARK}${process.pid}-${randomBytes(6).toString('hex')}`;
+    try {
+        await fs.rename(lockDir, moved);
+    }
+    catch (err) {
+        // ENOENT: another waiter broke it, or the holder released it, since the age check.
+        return errorCode(err) === 'ENOENT';
+    }
+    let movedAge;
+    try {
+        movedAge = Date.now() - (await fs.stat(moved)).mtimeMs;
+    }
+    catch {
+        return false;
+    }
+    if (movedAge > staleMs) {
+        await removeQuietly(moved);
+        return true;
+    }
+    // A live holder took the lock between the age check and the rename. Give it back,
+    // unless the path was taken again meanwhile; then the moved copy is removed, and its
+    // holder finds out through `stillHeld` that its directory is not at the path any more.
+    try {
+        await fs.lstat(lockDir);
+        await removeQuietly(moved);
+    }
+    catch {
+        try {
+            await fs.rename(moved, lockDir);
+        }
+        catch {
+            await removeQuietly(moved);
+        }
+    }
+    return false;
+}
+/** One try: make the lock, or break a stale one and make it once more. */
+async function tryOnce(lockDir, staleMs) {
+    const first = await makeLockDir(lockDir);
+    if (typeof first === 'object')
+        return first.made;
+    if (first === 'unusable')
+        return 'unusable';
+    if (!(await breakStaleLock(lockDir, staleMs)))
+        return 'busy';
+    const second = await makeLockDir(lockDir);
+    if (typeof second === 'object')
+        return second.made;
+    return second === 'exists' ? 'busy' : 'unusable';
+}
+/**
+ * Take the manifest lock. Waits at most `timeoutMs` (polling every 25 ms), then gives
+ * up with `not-acquired`; with `timeoutMs: 0` it tries once. The number of tries is
+ * fixed by the timeout, so no wait is unbounded. A folder that cannot hold a lock (it
+ * does not exist, or it is read-only) also answers `not-acquired`, at once, and this
+ * call never creates the folder.
+ */
+export async function acquireManifestLock(devflowDir, options = {}) {
+    const timeoutMs = Math.max(0, options.timeoutMs ?? MANIFEST_LOCK_WAIT_MS);
+    const staleMs = options.staleMs ?? MANIFEST_LOCK_STALE_MS;
+    const lockDir = getManifestLockPath(devflowDir);
+    const tries = Math.floor(timeoutMs / POLL_MS) + 1;
+    for (let attempt = 0; attempt < tries; attempt++) {
+        const outcome = await tryOnce(lockDir, staleMs);
+        if (outcome !== 'busy' && outcome !== 'unusable') {
+            return {
+                ok: true,
+                value: {
+                    stillHeld: () => holdsToken(lockDir, outcome),
+                    release: async () => {
+                        if (!(await holdsToken(lockDir, outcome)))
+                            return;
+                        try {
+                            await fs.rm(path.join(lockDir, MANIFEST_LOCK_TOKEN_NAME), { force: true });
+                            await fs.rmdir(lockDir);
+                        }
+                        catch { /* already released */ }
+                    },
+                },
+            };
+        }
+        if (outcome === 'unusable')
+            break;
+        if (attempt < tries - 1)
+            await sleep(POLL_MS);
+    }
+    return { ok: false, error: 'not-acquired' };
+}
+/**
+ * Run `work` while holding the manifest lock, and release it after, whether `work`
+ * returns or throws (a throw goes on to the caller). `work` does not run when the lock
+ * is not acquired. `work` gets the holder's `stillHeld` check, to call just before it writes.
+ */
+export async function withManifestLock(devflowDir, options, work) {
+    const lock = await acquireManifestLock(devflowDir, options);
+    if (!lock.ok)
+        return lock;
+    try {
+        return { ok: true, value: await work({ stillHeld: lock.value.stillHeld }) };
+    }
+    finally {
+        await lock.value.release();
+    }
+}
+//# sourceMappingURL=manifest-lock.js.map

package/dist/core/manifest.js

@@ -5,6 +5,8 @@ import { VIEW_MODES, migrateLegacyFlagsToRecord, sanitizeFlagsRecord, } from './
 import { normalizeComplianceFeature } from './compliance.js';
 import { normalizeTrackerFeature } from './tracker.js';
 import { writeFileAtomicExclusive } from './fs-atomic.js';
+import { isMachineFeatureOn } from './feature-switch.js';
+import { withManifestLock } from './manifest-lock.js';
 /**
  * Parse features.flags across the three on-disk shapes; reports whether a heal is owed.
  *
@@ -77,7 +79,11 @@ export function hasRequiredManifestFields(data) {
  *
  * Self-heals the following on-disk inconsistencies:
  * - features.kb → features.knowledge rename (both absent → true, D-FEATURES-ABSENT-ON)
- * - features.decisions → features.learning rename (both absent → true, D-FEATURES-ABSENT-ON)
+ * - the curation switch (features.curation beside its pre-rename copy features.learning,
+ *   and the oldest features.decisions) resolves by the machine rule — false in either
+ *   current key wins, both absent → true (D-FEATURES-ABSENT-ON) — and the heal writes
+ *   both current keys to the resolved value and drops `decisions`; a second read writes
+ *   nothing
  * - features.flags as string[] → FlagsRecord (via migrateLegacyFlagsToRecord)
  * - features.viewMode folded into flags['view-mode'] and stripped from result
  * - features.knownFlags stripped from result (folded into FlagsRecord key-presence)
@@ -90,6 +96,12 @@ export function hasRequiredManifestFields(data) {
  *
  * D39: heal-write failure returns the migrated in-memory manifest (not null).
  * The on-disk format remains unhealed; next read triggers another attempt.
+ *
+ * The heal is a read-modify-write and takes the manifest lock (manifest-lock.ts) like
+ * the toggle write does. It never waits for it: when the lock is held, it skips the
+ * write, because the next read heals. Under the lock it reads the file again and
+ * writes only when those bytes are the bytes it parsed, so a toggle that landed after
+ * the parse is never written over with the older snapshot.
  */
 export async function readManifest(devflowDir, opts) {
     const manifestPath = path.join(devflowDir, 'manifest.json');
@@ -100,7 +112,7 @@ export async function readManifest(devflowDir, opts) {
             return null;
         const features = data.features;
         // D-FEATURES-ABSENT-ON (a sub-decision of D-FEATURES-NARROW-ONLY,
-        // src/core/feature-switch.ts): knowledge and learning are machine-wide
+        // src/core/feature-switch.ts): knowledge and curation are machine-wide
         // switches, and every runtime gate — queue_read_gates in the hooks,
         // isMachineFeatureOn in the CLI, the knowledge write-back prose gate — reads
         // an ABSENT key as ON. This reader must agree: init seeds from it and every
@@ -119,13 +131,15 @@ export async function readManifest(devflowDir, opts) {
         const knowledge = typeof features.knowledge === 'boolean' ? features.knowledge
             : typeof features.kb === 'boolean' ? features.kb
                 : true;
-        // Self-heal: rename features.decisions → features.learning on disk.
-        // Coalesce: features.learning wins; fall back to features.decisions; default ON.
-        // D-LEARNING-LEGACY-DECISIONS: isMachineFeatureOn and queue_read_gates apply
-        // this exact precedence, so the legacy key is honoured before the heal lands.
-        const learning = typeof features.learning === 'boolean' ? features.learning
-            : typeof features.decisions === 'boolean' ? features.decisions
-                : true;
+        // Self-heal: the curation switch is stored under two current keys, `curation`
+        // and its pre-rename copy `learning` (#529). A boolean false in either is off, a
+        // boolean true in either is on when neither is false, and the pre-rename
+        // features.decisions decides only when neither current key is a boolean;
+        // default ON. isMachineFeatureOn IS that rule (D-LEARNING-LEGACY-DECISIONS),
+        // and queue_read_gates and resolve-settings.cjs mirror it, so the legacy key
+        // is honoured before the heal lands and a disagreeing pair reads off. The heal
+        // (needsHeal below) writes the resolved value to both current keys once.
+        const curation = isMachineFeatureOn(data, 'curation');
         // 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
@@ -140,9 +154,14 @@ export async function readManifest(devflowDir, opts) {
         const { flags: parsedFlags, legacy: flagsWereLegacy } = parseManifestFlags(features, knownFlags);
         // D39: sanitize all values; block prototype pollution keys.
         const sanitizedFlags = sanitizeFlagsRecord(parsedFlags);
-        // needsHeal when any legacy artifact is present on disk
+        // needsHeal when any legacy artifact is present on disk. The curation pair is a
+        // defect unless BOTH current keys are present and equal to the resolved value
+        // (a disagreeing pair, one key alone and neither key all heal); once healed,
+        // the pair holds and a second read writes nothing.
         const needsHeal = features.kb !== undefined ||
             features.decisions !== undefined ||
+            features.curation !== curation ||
+            features.learning !== curation ||
             flagsWereLegacy ||
             features.knownFlags !== undefined ||
             features.viewMode !== undefined ||
@@ -161,7 +180,7 @@ export async function readManifest(devflowDir, opts) {
                 memory: features.memory,
                 hud: typeof features.hud === 'boolean' ? features.hud : false,
                 knowledge,
-                learning,
+                curation,
                 rules: typeof features.rules === 'boolean' ? features.rules : true,
                 flags: sanitizedFlags,
                 // knownFlags and viewMode are NOT carried into the result.
@@ -177,7 +196,7 @@ export async function readManifest(devflowDir, opts) {
                 proxy: typeof features.proxy === 'boolean' ? features.proxy : false,
                 // Self-heal: absent/malformed compliance → {enabled:false, frameworks:[]}
                 compliance: normalizeComplianceFeature(features.compliance),
-                // D-BEHAVIOR-OPT-IN: absent/malformed → false (opt-in; the inverse of knowledge/learning).
+                // D-BEHAVIOR-OPT-IN: absent/malformed → false (opt-in; the inverse of knowledge/curation).
                 behavior: features.behavior === true,
                 // Self-heal: absent/malformed/unknown tracker → {provider:'github'} (AC-3.21).
                 // Deliberately NOT in the hard-null set above — see the field's doc comment.
@@ -197,7 +216,15 @@ export async function readManifest(devflowDir, opts) {
             // propagate to the caller. The migrated in-memory manifest is returned even
             // when the on-disk heal fails. The next read will retry the heal.
             try {
-                await writeManifest(devflowDir, manifest);
+                // No wait: a held lock means a toggle is writing, and the next read heals.
+                // Under the lock the write goes ahead only while the file still holds the
+                // bytes parsed above and the lock directory is still this heal's own; any
+                // other writer's result stands, and a skipped heal is made by the next read.
+                await withManifestLock(devflowDir, { timeoutMs: 0 }, async (lock) => {
+                    if ((await fs.readFile(manifestPath, 'utf-8')) === content && (await lock.stillHeld())) {
+                        await writeManifest(devflowDir, manifest);
+                    }
+                });
             }
             catch {
                 // heal-write failed — return migrated in-memory manifest unchanged
@@ -219,9 +246,26 @@ export async function writeManifest(devflowDir, data) {
     await fs.mkdir(devflowDir, { recursive: true });
     const manifestPath = path.join(devflowDir, 'manifest.json');
     // D-MANIFEST-SCOPE-PINNED: every write records 'user', whatever the caller holds.
-    const pinned = { ...data, scope: 'user' };
+    // The manifest mirror (#529): the pre-rename key `learning` is written equal to
+    // `curation`, right after it, so every typed writer keeps the copy a 3.7.0 CLI reads.
+    const pinned = { ...data, scope: 'user', features: withCurationMirror(data.features) };
     await writeFileAtomicExclusive(manifestPath, JSON.stringify(pinned, null, 2) + '\n');
 }
+/**
+ * `features` with the pre-rename key `learning` set equal to `curation`, placed right
+ * after it. Pure. Any `learning` the input carried is replaced, never kept.
+ */
+function withCurationMirror(features) {
+    const mirrored = {};
+    for (const [key, value] of Object.entries(features)) {
+        if (key === 'learning')
+            continue;
+        mirrored[key] = value;
+        if (key === 'curation')
+            mirrored.learning = value;
+    }
+    return mirrored;
+}
 /**
  * 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.

package/dist/core/migrations.js

@@ -11,6 +11,7 @@
 import { promises as fs } from 'fs';
 import * as path from 'path';
 import { writeFileAtomicExclusive } from './fs-atomic.js';
+import { pooled } from './pool.js';
 import { getMemoryDir } from './project-paths.js';
 import { LEGACY_AGENT_KEYS, canonicaliseAgentKeys, parseAgentMappingEnvelope } from './agent-models.js';
 import { migrateLegacyTrackerConventions } from './tracker.js';
@@ -215,19 +216,6 @@ export function reportMigrationResult(result, logger, verbose) {
             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 }.
  *

package/dist/core/observations.js

@@ -10,8 +10,8 @@
  * INACTIVE_DECISIONS_STATUSES stay in the ledger and leave the rendered files and
  * the HUD counts; an absent or unknown status counts as active. These lists
  * mirror ACTIVE_STATUSES / INACTIVE_STATUSES in
- * src/assets/scripts/hooks/lib/learning-store.cjs, which the hooks and the
- * renderer use, and the parity test in tests/decisions/learning-store.test.ts
+ * src/assets/scripts/hooks/lib/curation-store.cjs, which the hooks and the
+ * renderer use, and the parity test in tests/decisions/curation-store.test.ts
  * pins the two equal. Reason: the renderer, the HUD and this module each kept a
  * list of their own, so a status added to one counted as active in the others.
  */

package/dist/core/plugins.js

@@ -481,36 +481,36 @@ export const FEATURE_OWNED_SKILLS = ['compliance'];
  */
 export const FEATURE_OWNED_RULES = ['compliance', 'behavior'];
 /**
- * Skills a learning-off machine does not install.
+ * Skills a curation-off machine does not install.
  *
- * D-LEARNING-VARIANT-INSTALL: the learning-off variants of the commands and
+ * D-LEARNING-VARIANT-INSTALL: the curation-off variants of the commands and
  * agents (D-LEARNING-VARIANTS) carry no decisions text and preload no
- * apply-decisions, so the skill has no reader on a machine with learning off. It
+ * apply-decisions, so the skill has no reader on a machine with curation off. It
  * stays OWNED and REQUIRED by its plugins in the registry — the closure guard
- * reasons over the learning-on variant, the superset — and the install drops it
- * on top of the selection: `installViaFileCopy` skips it when `learning` is false
- * and `convergeLearningVariants` installs or removes it when the switch flips.
+ * reasons over the curation-on variant, the superset — and the install drops it
+ * on top of the selection: `installViaFileCopy` skips it when `curation` is false
+ * and `convergeCurationVariants` installs or removes it when the switch flips.
  *
  * This is a machine-switch condition, not a deselection: the plan
- * ({@link resolveSkillInstallPlan}) is untouched, so a learning-off machine never
+ * ({@link resolveSkillInstallPlan}) is untouched, so a curation-off machine never
  * reports the skill as "removed because no selected plugin requires it" nor its
  * shadow as inactive for a plugin that is not selected.
  *
  * Used by:
- *   - installer.ts installViaFileCopy: omits these from the install loop when learning is off
- *   - learning-install.ts convergeLearningVariants: installs or removes the directory
+ *   - installer.ts installViaFileCopy: omits these from the install loop when curation is off
+ *   - curation-install.ts convergeCurationVariants: installs or removes the directory
  *   - tests: independent literal ['apply-decisions'] (avoids the EXCLUDED-as-oracle trap)
  */
-export const LEARNING_GATED_SKILLS = ['apply-decisions'];
+export const CURATION_GATED_SKILLS = ['apply-decisions'];
 /**
- * A skills map with the learning-gated skills left out when learning is off.
+ * A skills map with the curation-gated skills left out when curation is off.
  *
- * Pure: the same map instance comes back when learning is on, a copy otherwise.
+ * Pure: the same map instance comes back when curation is on, a copy otherwise.
  */
-export function omitLearningGatedSkills(skillsMap, learning) {
-    if (learning)
+export function omitCurationGatedSkills(skillsMap, curation) {
+    if (curation)
         return skillsMap;
-    const gated = LEARNING_GATED_SKILLS;
+    const gated = CURATION_GATED_SKILLS;
     return new Map([...skillsMap].filter(([skill]) => !gated.includes(skill)));
 }
 // ── Skill-closure boundaries ──────────────────────────────────────────────────

package/dist/core/pool.js

@@ -0,0 +1,26 @@
+/**
+ * @file pool.ts
+ *
+ * Bounded concurrency over an array. Shared by the migration runner and the
+ * curation move step, so neither imports the other for a general helper.
+ */
+/**
+ * Process an array of items with at most `limit` concurrent Promises.
+ * Returns PromiseSettledResult for every item in the original order.
+ *
+ * Precondition: `limit` is a positive integer. A limit below 1 (or NaN) would never
+ * advance the chunk loop, so the call rejects with a RangeError before `fn` runs.
+ */
+export async function pooled(items, limit, fn) {
+    if (!Number.isInteger(limit) || limit < 1) {
+        throw new RangeError(`pooled: limit must be a positive integer, got ${String(limit)}`);
+    }
+    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;
+}
+//# sourceMappingURL=pool.js.map