devflow-kit 3.1.0 → 3.3.0

package/dist/core/agent-models.js

@@ -7,7 +7,7 @@
  *
  * Mapping file: ~/.devflow/agent-models.json
  *   { version: 1, agents: { [name]: { model?, effort? } } }
- *   Deviations-only: omit an agent to inherit its shipped default.
+ *   Deviations-only: omit an agent to inherit its shipped default (model AND effort).
  *   Unknown agent names are tolerated and preserved on save (plugin may not be installed).
  *   Invalid effort values are dropped with a warning.
  *
@@ -25,8 +25,8 @@
 import { promises as fs } from 'fs';
 import * as path from 'path';
 import { writeFileAtomicExclusive } from './fs-atomic.js';
-import { isDormantExternalModel } from './external-models.js';
-import { rewriteAgentFrontmatter, readFrontmatterModel, isValidModelName } from './agent-frontmatter.js';
+import { isDormantExternalModel, CLAUDE_MODEL_ALIASES } from './external-models.js';
+import { rewriteAgentFrontmatter, readFrontmatterModel, readFrontmatterEffort, isValidModelName, } from './agent-frontmatter.js';
 import { agentSourceDirs } from './assets.js';
 import { getAllAgentNames } from './plugins.js';
 import { mdEntryName, mdFileName } from './orphan-sweep.js';
@@ -51,6 +51,93 @@ export const EFFORT_LEVELS = ['low', 'medium', 'high', 'xhigh', 'max'];
  * EFFORT_LEVELS[number] is a literal union, not string.
  */
 const EFFORT_LEVELS_SET = new Set(EFFORT_LEVELS);
+/** True when `value` is one of EFFORT_LEVELS (narrows string to EffortLevel). */
+export function isEffortLevel(value) {
+    return EFFORT_LEVELS_SET.has(value);
+}
+/**
+ * D-SHIPPED-EFFORT: the stored effort value that drops an agent's effort line
+ * altogether. A mapping `inherit` yields no `effort:` line and does NOT fall
+ * back to the shipped effort, so the agent follows the session's effort. It is
+ * a stored value, unlike `default` (which deletes the key so the shipped
+ * effort applies again), and it is effort-only: model-side inherit semantics
+ * are a separate decision.
+ */
+export const EFFORT_INHERIT = 'inherit';
+// ---------------------------------------------------------------------------
+// Workers
+// ---------------------------------------------------------------------------
+/**
+ * D-WORKER-AGENTS: background workers whose model and effort are settable in
+ * `devflow agents` although they are not agents. A worker runs as its own
+ * `claude -p` process outside any session and has no installed agent file, so
+ * there is nothing for a reapply to rewrite.
+ *
+ * Worker entries are stored under `agents.<name>` in agent-models.json, in the
+ * same map as agent entries; an absent entry means the default declared here.
+ * Because the map is shared, every agent-only path (the reapply walk, the init
+ * reapply gate, countExternalMappedAgents, the list and TUI agent sets) goes
+ * through agentOnlyMapping, the one definition of the agent-only subset.
+ *
+ * A worker is not a DEVFLOW_PLUGINS agent: getAllAgentNames() and the roster
+ * count are unaffected.
+ *
+ * Shipped value of `memory`: `claude-sonnet-5-5` at `high` effort. User decision
+ * 2026-10-08: memory quality is worth more than the cost saving of Haiku.
+ *
+ * D-MEMORY-WORKER-LEAN: background-memory-update reads `agents.memory` from
+ * `~/.devflow/agent-models.json` at run time, validating `model` and `effort`
+ * field by field against the domain below, and passes `--effort` when the CLI
+ * version probe puts it at or above the lean-argv floor. A field it cannot use
+ * falls back to this row. The hook spells that fallback out for bash
+ * (`MEMORY_MODEL_DEFAULT`, `MEMORY_EFFORT_DEFAULT`, the alias and effort lists and
+ * the model-name rules), and tests/agent-models-worker.test.ts holds every one
+ * equal to this row and to the domain, so the two cannot drift apart.
+ */
+export const WORKER_AGENTS = {
+    memory: { model: 'claude-sonnet-5-5', effort: 'high' },
+};
+/**
+ * True when `name` is a worker key. Own-property check, so a hostile key such as
+ * `constructor` or `__proto__` is never answered from the prototype chain.
+ */
+export function isWorkerAgent(name) {
+    return Object.hasOwn(WORKER_AGENTS, name);
+}
+/** A full Claude model identifier: the `claude-` prefix and at least one more character. */
+const CLAUDE_FULL_ID_RE = /^claude-.+$/;
+/**
+ * D-WORKER-AGENTS: the worker value domain, owned here once and shared by
+ * `validateSetArgs` (the write boundary) and `readAgentMapping` (the read
+ * boundary), so a hand-edited file and a CLI argument are held to one rule.
+ *
+ *  - model:  `default`, a CLAUDE_MODEL_ALIASES alias, or a full identifier
+ *            starting `claude-`. Anything else is rejected, `inherit` included
+ *            (a worker has no session model to inherit). External models are
+ *            rejected too: the worker runs `claude -p` outside a session and
+ *            nothing here verifies it routes through the proxy, so allowing
+ *            them later is a deliberate change to this function.
+ *  - effort: `default` or an EFFORT_LEVELS level. `inherit` is rejected because
+ *            a worker has no session effort to inherit.
+ *
+ * Pure function — no catalog lookup, no I/O.
+ */
+export function validateWorkerValue(field, value) {
+    if (field === 'effort') {
+        if (value === 'default' || isEffortLevel(value))
+            return Ok(undefined);
+        return Err(`Invalid effort "${value}" for a worker. Valid: default, ${EFFORT_LEVELS.join(', ')} ` +
+            `(a worker has no session effort to inherit)`);
+    }
+    const inDomain = isValidModelName(value) &&
+        (value === 'default' ||
+            CLAUDE_MODEL_ALIASES.includes(value) ||
+            CLAUDE_FULL_ID_RE.test(value));
+    if (inDomain)
+        return Ok(undefined);
+    return Err(`Invalid model "${value}" for a worker. Valid: default, ${CLAUDE_MODEL_ALIASES.join(', ')}, ` +
+        `or a full claude- identifier (external models are not supported for workers)`);
+}
 // ---------------------------------------------------------------------------
 // Key migration
 // ---------------------------------------------------------------------------
@@ -216,6 +303,34 @@ export async function parseAgentMappingEnvelope(filePath) {
     }
     return { kind: 'ok', envelope, rawAgents: rawAgents };
 }
+/**
+ * D-WORKER-AGENTS: the agent-only subset of the mapping — every entry whose key
+ * is not a worker. Unknown names stay: the file preserves entries for agents
+ * whose plugin is not installed.
+ *
+ * This is the one definition of "the agents in the mapping". The reapply walk,
+ * the init reapply gate, countExternalMappedAgents and the TUI's orphan rows all
+ * call it, so a worker entry can never be mistaken for an agent with no
+ * installed file.
+ *
+ * Pure function — returns a new record, never mutates the mapping.
+ */
+export function agentOnlyMapping(mapping) {
+    const agents = {};
+    for (const [name, entry] of Object.entries(mapping.agents)) {
+        if (!isWorkerAgent(name))
+            agents[name] = entry;
+    }
+    return agents;
+}
+/**
+ * True when the mapping holds at least one agent entry. The `devflow init`
+ * reapply gate: an agents.memory-only mapping keeps it closed, because there is
+ * no agent file for a reapply to converge.
+ */
+export function hasAgentMappingEntries(mapping) {
+    return Object.keys(agentOnlyMapping(mapping)).length > 0;
+}
 /**
  * Read and tolerantly parse ~/.devflow/agent-models.json.
  * Returns an empty mapping when the file is missing.
@@ -245,24 +360,39 @@ export async function readAgentMapping(devflowDir, opts) {
             continue;
         const raw = entry;
         const mapping = {};
+        // D-WORKER-AGENTS: a worker key is held to the worker value domain on read,
+        // by the same function the CLI write boundary uses.
+        const worker = isWorkerAgent(name);
         if (typeof raw.model === 'string') {
             // Tighten to the same charset used by rewriteAgentFrontmatter.
             // The effort field is enum-validated below; model must be equally strict.
             // An invalid entry is dropped with a warning rather than silently
             // persisting and permanently poisoning that agent on every reapply.
-            if (isValidModelName(raw.model)) {
-                mapping.model = raw.model;
+            if (!isValidModelName(raw.model)) {
+                warn(`agent-models: invalid-model name for agent "${name}" — dropping entry`);
             }
             else {
-                warn(`agent-models: invalid-model name for agent "${name}" — dropping entry`);
+                const workerCheck = worker ? validateWorkerValue('model', raw.model) : undefined;
+                if (workerCheck !== undefined && !workerCheck.ok) {
+                    warn(`agent-models: dropping out-of-domain model "${raw.model}" for worker "${name}" — ${workerCheck.error}`);
+                }
+                else {
+                    mapping.model = raw.model;
+                }
             }
         }
         if (typeof raw.effort === 'string') {
-            if (EFFORT_LEVELS_SET.has(raw.effort)) {
-                // Sound narrowing: has() proved membership; EffortLevel is a literal
-                // subtype of string so the assertion is not a compensating cast.
+            // `inherit` is a stored agent value; a worker has no session effort to
+            // inherit, so for a worker it is out of domain like any other non-level.
+            if (isEffortLevel(raw.effort)) {
                 mapping.effort = raw.effort;
             }
+            else if (raw.effort === EFFORT_INHERIT && !worker) {
+                mapping.effort = raw.effort;
+            }
+            else if (worker) {
+                warn(`agent-models: dropping out-of-domain effort "${raw.effort}" for worker "${name}"`);
+            }
             else {
                 warn(`agent-models: dropping invalid effort "${raw.effort}" for agent "${name}"`);
             }
@@ -330,41 +460,49 @@ export async function saveAgentMapping(devflowDir, mapping) {
  *   isDormantExternalModel) AND proxyEnabled is false → the entry is DORMANT.
  *   The shipped default model is used instead. The entry remains saved.
  *
- * Effort is ALWAYS applied regardless of proxy state.
+ * D-SHIPPED-EFFORT — effort rule, in order:
+ *   1. a mapping effort level wins;
+ *   2. a mapping `inherit` yields no effort line and does NOT fall back to the
+ *      shipped effort;
+ *   3. an absent mapping effort falls back to the shipped effort, which is
+ *      undefined when the agent ships none.
+ *   Effort is ALWAYS applied regardless of proxy state, a dormant external
+ *   model included.
  *
  * Pure function — no I/O.
  *
  * @param agentName - The agent's short name (e.g., 'code').
  * @param mapping - The full mapping file.
- * @param shippedDefaults - Map of agent name → shipped default model.
+ * @param shippedDefaults - Map of agent name → shipped model and effort.
  * @param proxyEnabled - Whether the Devflow proxy is currently active.
  */
 export function resolveEffective(agentName, mapping, shippedDefaults, proxyEnabled) {
     const entry = mapping.agents[agentName];
+    const shipped = shippedDefaults[agentName];
     let model;
     if (entry?.model !== undefined) {
         // Dormant: external model configured but proxy is off → fall back to shipped default.
         model = isDormantExternalModel(entry.model, proxyEnabled)
-            ? shippedDefaults[agentName]
+            ? shipped?.model
             : entry.model;
     }
     else {
         // No mapping entry → use shipped default.
-        model = shippedDefaults[agentName];
+        model = shipped?.model;
     }
-    const effort = entry?.effort;
+    const mapped = entry?.effort;
+    const effort = mapped === EFFORT_INHERIT ? undefined : (mapped ?? shipped?.effort);
     return { model, effort };
 }
-// ---------------------------------------------------------------------------
-// loadShippedDefaults
-// ---------------------------------------------------------------------------
 /**
- * Parse the shipped model default out of every {name}.md in one directory.
+ * Parse the shipped model and effort out of every {name}.md in one directory.
  *
  * A missing or unreadable directory yields an empty map — dist/agents/ does not
  * exist until a generator host does, and a source tree that produced no agents
  * is caught by the registry-completeness guard rather than by a throw here.
- * Unknown or malformed files are skipped individually.
+ * Unknown or malformed files are skipped individually. The effort is returned as
+ * written: only the directory that wins the merge has its effort validated, so a
+ * typo in a losing file is never reported.
  */
 async function readDirDefaults(dir) {
     let entries;
@@ -380,9 +518,10 @@ async function readDirDefaults(dir) {
             return null;
         try {
             const content = await fs.readFile(path.join(dir, file), 'utf-8');
-            const result = readFrontmatterModel(content);
-            if (result.ok && result.value) {
-                return [agentName, result.value];
+            const model = readFrontmatterModel(content);
+            const effort = readFrontmatterEffort(content);
+            if (model.ok && model.value && effort.ok) {
+                return [agentName, { model: model.value, effort: effort.value }];
             }
         }
         catch {
@@ -399,11 +538,22 @@ async function readDirDefaults(dir) {
     return defaults;
 }
 /**
- * Load shipped default models from the agent files.
+ * Load the shipped default model and effort of every agent from the agent files.
+ *
+ * D-SHIPPED-EFFORT: this is the only production reader of shipped model and
+ * effort values. An agent's effort is part of its shipped default, so a reapply
+ * that did not see it would strip it (the mapping has no entry to say
+ * otherwise).
  *
  * Directories are MOST-PREFERRED FIRST — the convention owned by
  * agentSourceDirs() — and the first directory to supply a name wins, so once an
  * agent is generated into dist/agents/ its frontmatter is the shipped default.
+ * First-hit-wins applies to the whole record: an agent's effort is never read
+ * from a different file than its model.
+ *
+ * A shipped `effort:` outside EFFORT_LEVELS (`inherit` included — it is a
+ * mapping value, not a shipped one) is dropped with a warning naming the agent;
+ * its model survives.
  *
  * A registry agent that no directory supplies is reported through `onWarning`
  * as ONE aggregate message naming every missing agent and the build step. The
@@ -417,17 +567,31 @@ async function readDirDefaults(dir) {
  *   prove the precedence against a temp tree; all real callers use the default.
  * @param opts - Optional warning channel; the gap is silent without one.
  */
-export async function loadShippedDefaults(dirs = agentSourceDirs(), opts) {
+export async function loadShippedAgentDefaults(dirs = agentSourceDirs(), opts) {
     const perDir = await Promise.all(dirs.map(readDirDefaults));
-    const defaults = {};
+    const winners = {};
     for (const dirDefaults of perDir) {
-        for (const [agentName, model] of Object.entries(dirDefaults)) {
-            if (!(agentName in defaults)) {
-                defaults[agentName] = model;
+        for (const [agentName, raw] of Object.entries(dirDefaults)) {
+            if (!Object.hasOwn(winners, agentName)) {
+                winners[agentName] = raw;
             }
         }
     }
-    const missing = getAllAgentNames().filter(name => !(name in defaults));
+    const defaults = {};
+    for (const [agentName, raw] of Object.entries(winners)) {
+        if (raw.effort === '') {
+            defaults[agentName] = { model: raw.model };
+        }
+        else if (isEffortLevel(raw.effort)) {
+            defaults[agentName] = { model: raw.model, effort: raw.effort };
+        }
+        else {
+            defaults[agentName] = { model: raw.model };
+            opts?.onWarning?.(`Shipped agent "${agentName}" declares effort "${raw.effort}", which is not one of ` +
+                `${EFFORT_LEVELS.join(', ')} — ignoring it.`);
+        }
+    }
+    const missing = getAllAgentNames().filter(name => !Object.hasOwn(defaults, name));
     if (missing.length > 0) {
         opts?.onWarning?.(`No shipped default found for declared agent(s): ${missing.join(', ')}. ` +
             `Run \`npm run build:mds\` if they are compiled from .mds generator hosts, otherwise ` +
@@ -439,10 +603,11 @@ export async function loadShippedDefaults(dirs = agentSourceDirs(), opts) {
  * Idempotent convergence function: walk every installed agent file and
  * rewrite frontmatter model/effort to match the effective mapping.
  *
- * - Reads shipped defaults LIVE from the agent sources — agentSourceDirs(),
- *   dist/agents/ preferred over src/assets/agents/. An agent no source supplies
- *   is reported through the warning channel rather than passing as 'unchanged'
- *   with no explanation.
+ * - Reads shipped defaults (model AND effort) LIVE from the agent sources —
+ *   agentSourceDirs(), dist/agents/ preferred over src/assets/agents/. An agent
+ *   no source supplies is reported through the warning channel rather than
+ *   passing as 'unchanged' with no explanation. D-SHIPPED-EFFORT: an agent that
+ *   ships an effort keeps it across a reapply unless its mapping says otherwise.
  * - Gets the agent name list from the registry (getAllAgentNames()) plus
  *   any mapping entries for agents not in the registry.
  * - Missing installed files → skip silently (recorded in skippedMissing).
@@ -461,11 +626,11 @@ export async function reapplyAgentMapping(opts) {
         return { updated: [], unchanged: [], skippedMissing: [], invalidMapping: [], warnings };
     }
     const mapping = mappingResult.value;
-    const shippedDefaults = await loadShippedDefaults(opts.agentSourceDirs, { onWarning: warn });
+    const shippedDefaults = await loadShippedAgentDefaults(opts.agentSourceDirs, { onWarning: warn });
     // Build the union of: all registered agent names + all names in the mapping
     // (so agents not yet in the registry but configured are also processed).
     const registryNames = new Set(getAllAgentNames());
-    const mappingNames = new Set(Object.keys(mapping.agents));
+    const mappingNames = new Set(Object.keys(agentOnlyMapping(mapping)));
     const allNames = new Set([...registryNames, ...mappingNames]);
     // Stable iteration order — Set preserves insertion order, array fixes it for the map.
     const allNamesList = [...allNames];
@@ -589,7 +754,7 @@ export async function revertExternalAgents(opts) {
  */
 export function countExternalMappedAgents(mapping) {
     let count = 0;
-    for (const entry of Object.values(mapping.agents)) {
+    for (const entry of Object.values(agentOnlyMapping(mapping))) {
         if (isDormantExternalModel(entry.model, false)) {
             count++;
         }

package/dist/core/agent-state.js

@@ -1,9 +1,9 @@
 /**
- * Agent installation-state classification.
+ * Agent row vocabulary shared by `devflow agents --list` and the TUI.
  *
- * Single source of truth for the STATE column shared by `--list` and the TUI.
- * Centralised here (core layer) so neither cli/commands nor
- * cli/agents-view owns the vocabulary.
+ * Single source of truth for the STATE column and the EFFORT cell, so neither
+ * surface can drift from the other. Centralised here (core layer) so neither
+ * cli/commands nor cli/agents-view owns the vocabulary.
  *
  * Pure core-layer module, no CLI-adapter concerns.
  */
@@ -22,13 +22,35 @@ export const AGENT_STATE_LABELS = {
     'saved-inactive': 'saved-inactive',
     'not-installed': 'not installed',
     'unknown': 'unknown',
+    'worker': 'worker',
 };
+// ---------------------------------------------------------------------------
+// formatEffortDisplay
+// ---------------------------------------------------------------------------
+/**
+ * The text of an EFFORT cell, shared by `--list` and the TUI.
+ *
+ * D-SHIPPED-EFFORT: a configured level or `inherit` is shown as is. An
+ * unconfigured row shows `default (<shipped effort>)` when the shipped source
+ * carries an effort — the same `default (shippedDefault)` convention the MODEL
+ * cell uses — and plain `default` when it carries none.
+ *
+ * Pure function, no I/O.
+ *
+ * @param configured - The row's effort: a level, `inherit`, or `default` when unset.
+ * @param shippedEffort - The effort the shipped source carries, if any.
+ */
+export function formatEffortDisplay(configured, shippedEffort) {
+    if (configured !== 'default')
+        return configured;
+    return shippedEffort === undefined ? 'default' : `default (${shippedEffort})`;
+}
 /**
  * Classify an agent row's install state.
  *
  * Single source of truth shared by `--list` and the TUI so the two surfaces
  * cannot drift. The four-way result drives the STATE column in render.ts and
- * the STATE column in --list output.
+ * the STATE column in --list output. Worker rows never come through here.
  *
  * Pure function, no I/O.
  */

package/dist/core/assets.js

@@ -75,7 +75,7 @@ export function compiledSkillRefsDir(root = getPackageRoot()) {
  * The single owner of the dist-first agent-resolution policy: a generator
  * host's compiled artifact in dist/agents/ supersedes a hand-authored file of
  * the same name in src/assets/agents/. Every consumer reads the order from
- * here — the installer's first-hit-wins resolve, loadShippedDefaults's
+ * here — the installer's first-hit-wins resolve, loadShippedAgentDefaults's
  * first-wins merge, and the test harness's resolveAgentSource — so the
  * convention is stated once and cannot drift apart between call sites.
  *

package/dist/core/feature-config.js

@@ -1,5 +1,6 @@
 import * as path from 'path';
 import { promises as fs } from 'fs';
+import { firstSymbolicLink } from './linked-path.js';
 import { getFeatureConfigPath } from './project-paths.js';
 import { parseTrackerId } from './tracker.js';
 import { loadProjectConfigLib } from './evidence-policy.js';
@@ -169,17 +170,64 @@ async function readConfigBody(projectRoot, lib = loadProjectConfigLib()) {
     }
     return classifyConfigBytes(read.bytes, lib.value);
 }
+/** A thrown value's message, or the value itself when it is not an Error. */
+function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}
 /**
- * Serialise a config body to a project's config file.
+ * Serialise a config body to a project's config file. Never throws.
  * Creates the .devflow/ directory if missing.
  * Uses an atomic temp+rename pattern to prevent partial reads under concurrent writes.
+ * The copy is created only where nothing stands ('wx'), so an entry a repository
+ * planted at its name — a symbolic link among them — is never written through
+ * (D-CLI-NO-SYMLINK) and, not being this run's, is left where it is; the write then
+ * fails and the Result says so. Once this run has created the copy, a write, close or
+ * rename that fails removes it again, so a failed write leaves nothing beside the
+ * config; the Result names the failure, and the copy too when it could not be removed.
  */
 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(body, null, 2) + '\n', { encoding: 'utf-8', mode: 0o600 });
-    await fs.rename(tmpPath, configPath);
+    let text;
+    let copy;
+    try {
+        text = JSON.stringify(body, null, 2) + '\n';
+        await fs.mkdir(path.join(projectRoot, '.devflow'), { recursive: true });
+        copy = await fs.open(tmpPath, 'wx', 0o600);
+    }
+    catch (err) {
+        return { ok: false, detail: messageOf(err) };
+    }
+    try {
+        try {
+            // The open handle is fs.writeFile's destination and the text its data: the same
+            // write as copy.writeFile(text), in the form a path-traversal scan reads right,
+            // since it takes a writeFile's first argument for a path.
+            await fs.writeFile(copy, text, 'utf-8');
+        }
+        finally {
+            await copy.close();
+        }
+        await fs.rename(tmpPath, configPath);
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, detail: await removeCopy(tmpPath, messageOf(err)) };
+    }
+}
+/**
+ * Remove the copy a failed config write created, and say why the write failed:
+ * `detail`, followed by the removal's own failure when the copy stays. A copy that
+ * is already gone counts as removed (`force`).
+ */
+async function removeCopy(tmpPath, detail) {
+    try {
+        await fs.rm(tmpPath, { force: true });
+        return detail;
+    }
+    catch (err) {
+        return `${detail}; its copy ${tmpPath} could not be removed: ${messageOf(err)}`;
+    }
 }
 /**
  * Merge devflow's managed keys over the config body the file already holds.
@@ -227,21 +275,31 @@ export function mergeManagedConfig(existing, managed) {
  * 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.
+ *
+ * D-CLI-NO-SYMLINK (firstSymbolicLink): a `.devflow` that is a symbolic link is
+ * left alone, and the Result says so; the file is neither read nor written there.
  */
 export async function writeManagedConfig(projectRoot, managed, lib = loadProjectConfigLib()) {
     const configPath = getFeatureConfigPath(projectRoot);
+    let linked;
+    try {
+        linked = await firstSymbolicLink([path.dirname(configPath)]);
+    }
+    catch (err) {
+        return { ok: false, error: { kind: 'unreadable', path: configPath, detail: messageOf(err) } };
+    }
+    if (linked !== null) {
+        return { ok: false, error: { kind: 'unreadable', path: configPath, detail: `${linked} is a symbolic link, and devflow writes nothing through one` } };
+    }
     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) } };
-    }
+    const written = await writeConfigBody(projectRoot, mergeManagedConfig(objectOf(existing), managed));
+    if (!written.ok)
+        return { ok: false, error: { kind: 'write-failed', path: configPath, detail: written.detail } };
     return { ok: true };
 }
 /**

package/dist/core/flags.js

@@ -399,6 +399,30 @@ export const FLAG_REGISTRY = [
         integer: true,
         upstreamDefault: 30,
     },
+    {
+        // D-FOREGROUND-RUN: every agent runs builds and tests in the foreground under an explicit
+        // Bash `timeout` whose ceiling is Claude Code's 600000 ms, or this variable when set. A
+        // suite that cannot be split under that ceiling is reported BLOCKED with the remedy
+        // `devflow flags --set bash-max-timeout-ms=<ms>`, so this flag is that remedy.
+        // The env name was confirmed against Claude Code 2.1.294 (docs/reference/claude-code-flags-probe.md):
+        // the binary reads BASH_MAX_TIMEOUT_MS, ignores a non-positive or NaN value, and takes the
+        // larger of it and the default timeout. Neutral by default (undefined → manifest null →
+        // key deleted). min 600000 = upstream default, so the flag only ever raises the ceiling;
+        // max 7200000 (2 h) is the devflow sanity bound.
+        id: 'bash-max-timeout-ms',
+        label: 'Bash max timeout',
+        description: 'Ceiling in milliseconds for a foreground Bash command timeout',
+        hint: 'Raises the Bash timeout ceiling past 600000 ms for long-running suites',
+        blurb: 'Bash timeout ceiling',
+        kind: 'number',
+        target: { type: 'env', key: 'BASH_MAX_TIMEOUT_MS' },
+        recommended: false,
+        defaultValue: undefined,
+        min: 600000, // upstream default ceiling: lower values would only shrink it
+        max: 7200000, // devflow sanity bound: 2 hours
+        integer: true,
+        upstreamDefault: 600000,
+    },
     {
         // Writes as { command: value } per Claude Code spellcheck setting shape.
         id: 'spellcheck',

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

@@ -5,24 +5,23 @@
  * --clear` and `--disable` (src/cli/commands/learning.ts) and by the drain
  * `devflow init` runs when learning is switched off (src/cli/commands/init.ts).
  */
-import { promises as fs } from 'fs';
-import { getLearningClaimOwnerPath, getLearningPendingTurnsPath, getLearningPendingTurnsProcessingPath, } from './project-paths.js';
+import * as path from 'path';
+import { getLearningClaimOwnerPath, getLearningDir, getLearningPendingTurnsPath, getLearningPendingTurnsProcessingPath, } from './project-paths.js';
+import { drainQueueFiles } from './queue-drain.js';
 /**
  * Drain the learning (decisions-detection) pending-turns queue, its claimed
  * batch and the claim's owner file 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.
+ * Refused, deleting nothing, when `.devflow` or `.devflow/learning` under `gitRoot`
+ * is a symbolic link (D-CLI-NO-SYMLINK). ENOENT-tolerant; other errors propagate.
  */
 export async function drainLearningQueue(gitRoot) {
-    const unlinkIfPresent = (file) => fs.unlink(file).catch((e) => {
-        if (e.code !== 'ENOENT')
-            throw e;
-    });
-    await Promise.all([
-        unlinkIfPresent(getLearningPendingTurnsPath(gitRoot)),
-        unlinkIfPresent(getLearningPendingTurnsProcessingPath(gitRoot)),
-        unlinkIfPresent(getLearningClaimOwnerPath(gitRoot)),
+    const learningDir = getLearningDir(gitRoot);
+    return drainQueueFiles([path.dirname(learningDir), learningDir], [
+        getLearningPendingTurnsPath(gitRoot),
+        getLearningPendingTurnsProcessingPath(gitRoot),
+        getLearningClaimOwnerPath(gitRoot),
     ]);
 }
 //# sourceMappingURL=learning-queue-cleanup.js.map

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

@@ -6,6 +6,14 @@ const VALID_MODELS = new Set(['opus', 'sonnet', 'haiku']);
 function isValidModel(value) {
     return typeof value === 'string' && VALID_MODELS.has(value);
 }
+/**
+ * D-LEARNING-SHIPPED-ROW: the default model is the model the Learning agent ships
+ * with, the `model:` line of src/assets/agents/learning.md. With no layer
+ * configuring a model, the spawn directive names none and that line decides, so a
+ * different default here would describe a run that never happens.
+ * tests/decisions/config.test.ts holds this value equal to the Learning row of the
+ * agent-config table, which a change of the shipped tier edits with the frontmatter.
+ */
 const DEFAULTS = {
     model: 'opus',
     debug: false,