@khoavu882/doflow 2.0.0-beta.5 → 2.0.0

package/src/runtime/state-root.js

@@ -0,0 +1,217 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { acquireLock } = require('./task-state.js');
+const { loadStorageRegistry } = require('./storage/registry.js');
+const { REPO_ROOT } = require('../helper/repo-root.js');
+
+// Where a task's records live (115 IC-004) and how records a linked worktree wrote before that rule
+// reach the main checkout (IC-006): one locked sweep per redirected call.
+//
+// A linked, non-sandbox worktree reads and writes every per-task record under the main checkout's
+// `.doflow/state`, whatever folders the worktree holds: a conditional rule flipped mid-run when
+// do-brainstorm created the feature folder in the worktree and split one task's records across two
+// stores. A DoFlow sandbox (`.doflow-worktree-base`) keeps its own store, and `--global` is $HOME.
+
+/** This module's path as `core/registry/storage.json` names it in a store's `writers`. */
+const ADOPTER = 'src/runtime/state-root.js';
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/**
+ * IC-004: the root a task-store verb or `orchestrate` reads and writes its records in.
+ * @param {Object} o parsed CLI options (`global`, `positional`)
+ * @param {Object|null} checkouts a `listCheckouts` result, or null when none was listed
+ * @returns {{root: string, redirected: boolean}}
+ */
+function taskStateRoot(o     , checkouts     )                                        {
+  if (!o.global && checkouts?.ok && checkouts.isLinked && !checkouts.sandbox && checkouts.main) {
+    return { root: checkouts.main, redirected: true };
+  }
+  return { root: o.global ? os.homedir() : path.resolve(o.positional?.[0] || '.'), redirected: false };
+}
+
+/**
+ * The project-state stores a worktree's records are adopted from: the ones that declare this module
+ * among their `writers` in `core/registry/storage.json`, so the list is the registry's, not a copy.
+ * @param {Object} [registry] a loaded storage registry (default: the shipped one)
+ * @returns {Array<{id: string, path: string, match: RegExp}>}
+ */
+function adoptedStores(registry      = loadStorageRegistry({ repoRoot: REPO_ROOT }))                                                     {
+  return registry.stores
+    .filter((store     ) => store.root === 'project-state' && Array.isArray(store.writers) && store.writers.includes(ADOPTER))
+    .map((store     ) => ({ id: store.id, path: store.path, match: new RegExp(store.match) }));
+}
+
+/** Whether `name` is a namespace directory of a store (a feature slug), not a `<file>.lock` directory. */
+function isNamespaceDir(name        )          {
+  return SAFE_ID.test(name) && !name.includes('..') && !name.endsWith('.lock');
+}
+
+/** The record files of one store directory of the worktree, by the store's exact `match`: flat files
+ * and the files of each `<slug>/` directory, as paths relative to the store. */
+function storeFiles(dir        , match        , fsImpl     )           {
+  const out           = [];
+  let entries       ;
+  try { entries = fsImpl.readdirSync(dir, { withFileTypes: true }); } catch { return out; }
+  for (const entry of entries) {
+    // A link is listed as it stands, file or directory, so the sweep refuses it instead of skipping it.
+    if (entry.isSymbolicLink() && (match.test(entry.name) || isNamespaceDir(entry.name))) out.push(entry.name);
+    else if (entry.isFile() && match.test(entry.name)) out.push(entry.name);
+    else if (entry.isDirectory() && isNamespaceDir(entry.name)) {
+      let inner       ;
+      try { inner = fsImpl.readdirSync(path.join(dir, entry.name), { withFileTypes: true }); } catch { continue; }
+      for (const file of inner) if ((file.isFile() || file.isSymbolicLink()) && match.test(file.name)) out.push(path.join(entry.name, file.name));
+    }
+  }
+  return out.sort();
+}
+
+/** The first link among `root`'s own path components down to `file` (the root itself is the
+ * checkout and is not owned here), or null. A component that does not exist yet is not a link. */
+function linkOnTheWay(root        , file        , fsImpl     )                {
+  let at = root;
+  for (const part of path.relative(root, file).split(path.sep)) {
+    at = path.join(at, part);
+    let stat     ;
+    try { stat = fsImpl.lstatSync(at); } catch { return null; }
+    if (stat.isSymbolicLink()) return at;
+  }
+  return null;
+}
+
+/** The task id a flat record file names: `<taskId>.json` or the claims file `<taskId>_claims.json`. */
+function taskIdOf(name        )         {
+  const base = name.slice(0, -'.json'.length);
+  return base.endsWith('_claims') ? base.slice(0, -'_claims'.length) : base;
+}
+
+/** The feature a flat record names (`featureSlug` on a run, `slug` on a readiness record), or null. */
+function ownSlugOf(bytes        )                {
+  try {
+    const data = JSON.parse(bytes.toString('utf8'));
+    const named = [data?.featureSlug, data?.slug].find((v) => typeof v === 'string' && SAFE_ID.test(v) && !v.includes('..'));
+    return named || null;
+  } catch { return null; }
+}
+
+/** Writes `bytes` to `to` through a temporary file beside it and a rename, so a reader never sees a
+ * partial record. The one write path for a record copied between stores or checkouts. */
+function placeRecord(to        , bytes        , fsImpl      = fs)       {
+  const tmp = `${to}.${process.pid}.tmp`;
+  fsImpl.writeFileSync(tmp, bytes);
+  fsImpl.renameSync(tmp, to);
+}
+
+function realOrNull(p        , fsImpl     )                {
+  try { return fsImpl.realpathSync(p); } catch { return null; }
+}
+
+/**
+ * IC-006 (115 C-3, D-1, D-4): moves every record a linked worktree holds in its own `.doflow/state`
+ * to the main checkout's, before the verb reads any of them. One sweep per redirected call, over
+ * every adopted store, whatever task the call names.
+ *
+ * Nothing is swept when the two state directories are one directory (a worktree whose
+ * `.doflow/state` links to the main checkout's). Per file: a link on either side's own path, or a
+ * source and target that are one file (`dev:ino`), refuses that file; otherwise the target's lock and
+ * then the source's are taken, the source is re-read under them (gone means another sweep moved it),
+ * and it goes to the same relative path, except that a flat record of a task id other than its
+ * feature's slug goes under `<store>/<slug>/` (the slug it names, else the call's `recordSlug`, so it
+ * lands where every reader looks). Equal bytes at the target delete the source; no target means a
+ * copy to a temporary file, a rename into place, a re-read compared with the source, and only then
+ * the source's deletion; other bytes leave both and are reported. Files already moved stay moved.
+ * @param {Object} options
+ * @param {string} options.mainRoot the main checkout
+ * @param {string} options.worktreeRoot the linked worktree the verb runs in
+ * @param {string|null|(() => string|null)} [options.recordSlug] the call's feature slug, asked for only
+ *   when a flat record names no feature of its own
+ * @param {Object} [options.registry] storage registry (default: the shipped one)
+ * @param {Object} [options.fsImpl]
+ * @returns {{ok: boolean, adopted: string[], removed: string[], error?: 'store-conflict',
+ *   conflicts?: Array<{worktree: string, main: string, reason: 'differs'|'link'|'same-file'}>}}
+ */
+function sweepWorktreeRecords({ mainRoot, worktreeRoot, recordSlug = null, registry, fsImpl = fs }     )      {
+  const done = { ok: true, adopted: []            , removed: []             };
+  const conflicts                                                            = [];
+  const fromState = path.join(worktreeRoot, '.doflow', 'state');
+  const toState = path.join(mainRoot, '.doflow', 'state');
+  const fromReal = realOrNull(fromState, fsImpl);
+  if (fromReal === null || fromReal === realOrNull(toState, fsImpl)) return done;
+  let callSlug                           ;
+  const slugOfCall = ()                => {
+    if (callSlug === undefined) {
+      let value      = null;
+      try { value = typeof recordSlug === 'function' ? recordSlug() : recordSlug; } catch { /* no feature */ }
+      callSlug = typeof value === 'string' && SAFE_ID.test(value) && !value.includes('..') ? value : null;
+    }
+    return callSlug;
+  };
+
+  for (const store of adoptedStores(registry)) {
+    const fromDir = path.join(fromState, store.path);
+    let dirStat     ;
+    try { dirStat = fsImpl.lstatSync(fromDir); } catch { continue; }
+    if (dirStat.isSymbolicLink()) {
+      conflicts.push({ worktree: fromDir, main: path.join(toState, store.path), reason: 'link' });
+      continue;
+    }
+    if (!dirStat.isDirectory()) continue;
+    for (const rel of storeFiles(fromDir, store.match, fsImpl)) {
+      const from = path.join(fromDir, rel);
+      if (linkOnTheWay(worktreeRoot, from, fsImpl)) {
+        conflicts.push({ worktree: from, main: path.join(toState, store.path, rel), reason: 'link' });
+        continue;
+      }
+      let toRel = rel;
+      if (!rel.includes(path.sep)) {
+        let bytes                = null;
+        try { bytes = fsImpl.readFileSync(from); } catch { continue; }
+        const slug = ownSlugOf(bytes          ) || slugOfCall();
+        if (slug && slug !== taskIdOf(rel)) toRel = path.join(slug, rel);
+      }
+      const to = path.join(toState, store.path, toRel);
+      if (linkOnTheWay(mainRoot, to, fsImpl)) { conflicts.push({ worktree: from, main: to, reason: 'link' }); continue; }
+      try {
+        const a = fsImpl.lstatSync(from);
+        const b = fsImpl.lstatSync(to);
+        if (a.dev === b.dev && a.ino === b.ino) { conflicts.push({ worktree: from, main: to, reason: 'same-file' }); continue; }
+      } catch { /* one side is absent: not one file */ }
+
+      fsImpl.mkdirSync(path.dirname(to), { recursive: true });
+      const releaseTarget = acquireLock(fsImpl, to);
+      try {
+        const releaseSource = acquireLock(fsImpl, from);
+        try {
+          let bytes        ;
+          try { bytes = fsImpl.readFileSync(from); } catch (error     ) {
+            if (error.code === 'ENOENT') continue; // another sweep moved it
+            throw error;
+          }
+          let there                = null;
+          try { there = fsImpl.readFileSync(to); } catch (error     ) { if (error.code !== 'ENOENT') throw error; }
+          if (there !== null) {
+            if (!bytes.equals(there)) { conflicts.push({ worktree: from, main: to, reason: 'differs' }); continue; }
+            fsImpl.unlinkSync(from);
+            done.removed.push(from);
+            continue;
+          }
+          placeRecord(to, bytes, fsImpl);
+          if (!bytes.equals(fsImpl.readFileSync(to))) { conflicts.push({ worktree: from, main: to, reason: 'differs' }); continue; }
+          fsImpl.unlinkSync(from);
+          done.adopted.push(to);
+        } finally {
+          releaseSource();
+        }
+      } finally {
+        releaseTarget();
+      }
+    }
+  }
+  return conflicts.length ? { ...done, ok: false, error: 'store-conflict', conflicts } : done;
+}
+
+module.exports = { taskStateRoot, sweepWorktreeRecords, placeRecord, adoptedStores, ADOPTER };

package/src/runtime/storage/cli.js

@@ -5,7 +5,7 @@
 const path = require('node:path');
 const fs = require('node:fs');
 const { loadStorageRegistry } = require('./registry.js');
-const { resolveRoots, readPruneSetting } = require('./roots.js');
+const { resolveRoots, createPruneSettingsResolver } = require('./roots.js');
 const { runPass } = require('./engine.js');
 const { upkeepAfterVerb } = require('./upkeep.js');
 const { REPO_ROOT } = require('../../helper/repo-root.js');
@@ -29,10 +29,15 @@ function handleStorageCommand({ action = 'report', json = false, global = false,
     return;
   }
   const roots = resolveRoots({ registry, projectRoot: global ? null : path.resolve(projectRoot), global, env });
-  const projectSetting = readPruneSetting({ registry, roots, rootId: 'project-state', fsImpl });
-  const userSetting = readPruneSetting({ registry, roots, rootId: 'user-state', fsImpl });
-  const setting = Object.fromEntries(Object.keys(roots).map(rootId => [rootId,
-    readPruneSetting({ registry, roots, rootId, fsImpl })]));
+  let settingsView      = null;
+  const resolvePruneSetting = createPruneSettingsResolver({ roots, fsImpl, onView: (view     ) => { settingsView = view; } });
+  const projectSetting = resolvePruneSetting('project-state');
+  const userSetting = resolvePruneSetting('user-state');
+  let deprecationNotes        = [];
+  try {
+    if (settingsView) deprecationNotes = settingsView.notes.filter((note     ) => note.code === 'deprecated' && note.key === 'storage.prune');
+  } catch { /* a settings fault does not change storage's fail-closed report */ }
+  const setting = Object.fromEntries(Object.keys(roots).map(rootId => [rootId, resolvePruneSetting(rootId)]));
   const mode = action === 'prune' ? 'prune' : 'report';
   const result = runPass({ registry, roots, mode, setting, now: Date.now(), env, fsImpl });
   const removed = result.stores.reduce((sum     , row     ) => sum + row.removed, 0);
@@ -42,6 +47,7 @@ function handleStorageCommand({ action = 'report', json = false, global = false,
     // IC-013: an explicitly set DOFLOW_RETENTION_HOURS still removes settled lifecycle events.
     console.log(removed === 0 ? `storage: pruning is off (${decision}); nothing removed`
       : `storage: pruning is off (${decision}); DOFLOW_RETENTION_HOURS still applied to lifecycle events: removed ${removed} ${entries}`);
+    for (const note of deprecationNotes) console.log(`note: ${note.text}`);
     return;
   }
   if (json) {
@@ -53,6 +59,7 @@ function handleStorageCommand({ action = 'report', json = false, global = false,
     return;
   }
   console.log(`Settings: project ${projectSetting.setting}${projectSetting.decidedBy ? ` (${projectSetting.decidedBy})` : ' (default)'}; user ${userSetting.setting}${userSetting.decidedBy ? ` (${userSetting.decidedBy})` : ' (default)'}`);
+  for (const note of deprecationNotes) console.log(`note: ${note.text}`);
   for (const row of result.stores) {
     const names = row.selected.slice(0, 20).map((entry     ) => entry.name);
     const more = row.selected.length > 20 ? `\n    ... and ${row.selected.length - 20} more` : '';

package/src/runtime/storage/engine.js

@@ -7,7 +7,7 @@ const path = require('node:path');
 const { randomBytes } = require('node:crypto');
 const { formatBound } = require('./registry.js');
 const { resolveStorePath } = require('./roots.js');
-const { selectCandidates, recordStillCandidate, protectedLogs, removableRules, ruleOrder, projectRoot } = require('./rules.js');
+const { selectCandidates, recordStillCandidate, protectedLogs, unfinishedRuns, removableRules, ruleOrder, projectRoot } = require('./rules.js');
 const { retainLocked } = require('../lifecycle/store-upkeep.js');
 const { parseWindow, selectExpired } = require('../lifecycle/retention.js');
 const { readEvents } = require('../lifecycle/event-store.js');
@@ -192,7 +192,7 @@ function runPass({registry,roots,stores,mode,setting={},now=Date.now(),budgetMs,
           row.selected=selection.files.map((name     )=>({name,reason:'settled',bytes:stat(fsImpl,path.join(location,name))?.size || 0}));
         } else {
           let output;
-          try { output=retainLocked(project,{fsImpl,now:new Date(now),window,maxFiles:Math.max(0,cap-removals),shouldStop}); }
+          try { output=retainLocked(project,{fsImpl,now:new Date(now),window,maxFiles:Math.max(0,cap-removals),shouldStop,staleTmpMs:registry.settings.staleTmpHours*3600000}); }
           catch(error     ) { row.failed.push({name:store.id,code:error.code || 'EIO'}); continue; }
           row.selected=output.selected.map(({name,bytes}     )=>({name,reason:'settled',bytes}));
           row.removed=output.removed; removals+=row.removed;
@@ -222,6 +222,13 @@ function runPass({registry,roots,stores,mode,setting={},now=Date.now(),budgetMs,
       row.protected=candidates.filter((c     )=>protectedSet.has(c.name)).length;
       candidates=candidates.filter((c     )=>!protectedSet.has(c.name));
     }
+    if (store.protect==='unfinished-run' && candidates.length) {
+      // Fails closed: a file whose run cannot be shown terminal is kept, never reported as a failure.
+      const kept=unfinishedRuns({roots,fsImpl,names:candidates.map((c     )=>c.name),shouldStop});
+      if (kept.incomplete) { result.partial=true; break; }
+      row.protected=candidates.filter((c     )=>kept.names.has(c.name)).length;
+      candidates=candidates.filter((c     )=>!kept.names.has(c.name));
+    }
     const orderedCandidates=store.entry==='record' ? removalOrder(candidates)
       : [...candidates].sort((a,b)=>a.mtimeMs-b.mtimeMs || a.name.localeCompare(b.name));
     if (shouldStop()) { result.partial=true; break; }

package/src/runtime/storage/registry.js

@@ -18,6 +18,9 @@ const RULES                        = new Map([
   ['existing', []],
   ['control', []],
 ]);
+// open-work keeps logs an unfinished task's record names; unfinished-run keeps a worker-model file
+// while its worker run or dispatch is not terminal or cannot be resolved (row 120 IC-005).
+const PROTECTS = new Set(['open-work', 'unfinished-run']);
 const MOMENTS = new Set(['verb', 'session', 'verify', 'install', 'lifecycle-verb', 'uninstall']);
 const STORE_ID = /^[a-z][a-z0-9-]*$/;
 
@@ -70,8 +73,18 @@ function validateStorageRegistry(registry     )
         for (const field of RULES.get(store.rule) || []) if (!positiveInteger(store.bound[field])) error(errors, `${where}.bound.${field}`, 'must be a positive integer');
         if (['existing', 'control'].includes(store.rule) && (typeof store.bound.text !== 'string' || !store.bound.text)) error(errors, `${where}.bound.text`, 'must be a non-empty string');
         if (store.rule === 'existing' && store.bound.value !== undefined && !positiveInteger(store.bound.value)) error(errors, `${where}.bound.value`, 'must be a positive integer when present');
+        if (store.rule === 'count-and-age' && store.bound.either !== undefined && typeof store.bound.either !== 'boolean') error(errors, `${where}.bound.either`, 'must be a boolean when present');
+        const allowed = new Set([
+          ...(RULES.get(store.rule) || []),
+          ...(['existing', 'control'].includes(store.rule) ? ['text'] : []),
+          ...(store.rule === 'existing' ? ['value'] : []),
+          ...(store.rule === 'count-and-age' ? ['either'] : []),
+        ]);
+        for (const key of Object.keys(store.bound)) {
+          if (!allowed.has(key)) error(errors, `${where}.bound`, `unknown key '${key}'`);
+        }
       }
-      if (store.protect !== null && store.protect !== 'open-work') error(errors, `${where}.protect`, 'must be open-work or null');
+      if (store.protect !== null && !PROTECTS.has(store.protect)) error(errors, `${where}.protect`, 'must be open-work, unfinished-run or null');
       if (!Array.isArray(store.moments) || store.moments.some((moment     ) => !MOMENTS.has(moment)) || new Set(store.moments).size !== store.moments.length) error(errors, `${where}.moments`, 'must be a unique subset of known moments');
       if (store.rule === 'existing' && store.moments?.length) error(errors, `${where}.moments`, 'must be empty for existing stores');
       if (!Array.isArray(store.writers) || store.writers.some((writer     ) => typeof writer !== 'string' || !writer)) error(errors, `${where}.writers`, 'must be an array of repository-relative paths');

package/src/runtime/storage/roots.js

@@ -3,16 +3,16 @@
 // TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
 
 const fs = require('node:fs');
-const os = require('node:os');
 const path = require('node:path');
+const { configHome } = require('../config-home.js');
 
 function absolute(value     )                { return typeof value === 'string' && path.isAbsolute(value) ? value : null; }
 
 /** Resolves IC-001's five physical roots; -g/global deliberately omits project roots. */
 function resolveRoots({ registry, projectRoot, global = false, env = process.env }      = {})                                {
-  const home = absolute(env.HOME) || os.homedir();
-  const xdgBase = env.XDG_CONFIG_HOME === undefined || env.XDG_CONFIG_HOME === ''
-    ? path.join(home, '.config') : absolute(env.XDG_CONFIG_HOME);
+  // No home variable means no home base and no config home: nothing falls back to the account home (DD-7).
+  const home = absolute(env.HOME);
+  const xdgBase = configHome(env).base;
   const project = global ? null : absolute(projectRoot);
   const bases                                = { project, home, 'xdg-config': xdgBase };
   return Object.fromEntries(Object.entries(registry.roots).map(([id, root]               ) => {
@@ -21,21 +21,71 @@ function resolveRoots({ registry, projectRoot, global = false, env = process.env
   }));
 }
 
-function readSetting(file        , fsImpl     )         {
-  try {
-    const first = fsImpl.readFileSync(file, 'utf8').split(/\r?\n/, 1)[0].trim().toLowerCase();
-    return first === 'on' || first === 'off' ? first : 'off';
-  } catch { return 'off'; }
+/** Creates one IC-014 resolver for all roots in a command; a project view can also read global scope. */
+function createPruneSettingsResolver({ roots, fsImpl = fs, onView }      = {})                                                                    {
+  const resolverEnv                         = {};
+  if (roots['config-home']) resolverEnv.XDG_CONFIG_HOME = path.dirname(roots['config-home']);
+  let view      = null;
+  let loadedView = false;
+  return (rootId        ) => {
+    if (!loadedView) {
+      loadedView = true;
+      try {
+        let settingsRegistry;
+        if (fsImpl !== fs) {
+          const { loadSettingsRegistry } = require('../settings/registry.js');
+          const loaded = loadSettingsRegistry({ fsImpl });
+          if (!loaded.ok) throw new Error(loaded.detail);
+          settingsRegistry = loaded.registry;
+        }
+        const { loadSettings } = require('../settings/resolve.js');
+        const projectRoot = roots['project-doflow'] ? path.dirname(roots['project-doflow']) : null;
+        view = loadSettings({ projectRoot, env: resolverEnv, fsImpl, ...(settingsRegistry ? { registry: settingsRegistry } : {}) });
+      } catch {
+        // A settings registry fault fails closed for every root, as it did for each old call.
+        view = null;
+      }
+      if (typeof onView === 'function') onView(view);
+    }
+    if (!view) return { setting: 'off', decidedBy: null };
+    try {
+      const usesProject = rootId === 'project-doflow' || rootId === 'project-state';
+      const resolved = view.get('storage.prune', usesProject ? 'project' : 'global');
+      return {
+        setting: resolved.value === 'on' ? 'on' : 'off',
+        decidedBy: resolved.origin.layer === 'default' ? null : resolved.origin.source,
+      };
+    } catch {
+      return { setting: 'off', decidedBy: null };
+    }
+  };
 }
 
 /** Reads IC-014 and reports exactly which present file made the decision, if any. */
-function readPruneSetting({ registry, roots, rootId, fsImpl = fs }      = {})                                                {
-  const projectFile = roots['project-doflow'] ? path.join(roots['project-doflow'], registry.settings.optOutFile) : null;
-  const userFile = roots['config-home'] ? path.join(roots['config-home'], registry.settings.optOutFile) : null;
+function readPruneSetting({ roots, rootId, fsImpl = fs }      = {})                                                {
   const usesProject = rootId === 'project-doflow' || rootId === 'project-state';
-  if (usesProject && projectFile && fsImpl.existsSync(projectFile)) return { setting: readSetting(projectFile, fsImpl), decidedBy: projectFile };
-  if (userFile && fsImpl.existsSync(userFile)) return { setting: readSetting(userFile, fsImpl), decidedBy: userFile };
-  return { setting: 'on', decidedBy: null };
+  const global = !usesProject;
+  const projectRoot = !global && roots['project-doflow'] ? path.dirname(roots['project-doflow']) : null;
+  const resolverEnv                         = {};
+  if (roots['config-home']) resolverEnv.XDG_CONFIG_HOME = path.dirname(roots['config-home']);
+  try {
+    let settingsRegistry;
+    if (fsImpl !== fs) {
+      const { loadSettingsRegistry } = require('../settings/registry.js');
+      const loaded = loadSettingsRegistry({ fsImpl });
+      if (!loaded.ok) throw new Error(loaded.detail);
+      settingsRegistry = loaded.registry;
+    }
+    const { loadSettings } = require('../settings/resolve.js');
+    const view = loadSettings({ projectRoot, global, env: resolverEnv, fsImpl, ...(settingsRegistry ? { registry: settingsRegistry } : {}) });
+    const resolved = view.get('storage.prune', global ? 'global' : 'project');
+    return {
+      setting: resolved.value === 'on' ? 'on' : 'off',
+      decidedBy: resolved.origin.layer === 'default' ? null : resolved.origin.source,
+    };
+  } catch {
+    return { setting: 'off', decidedBy: null };
+  }
 }
 
 function linked(file        , fsImpl     )          {
@@ -60,4 +110,4 @@ function resolveStorePath({ store, roots, fsImpl = fs }      = {})
   return current;
 }
 
-module.exports = { resolveRoots, readPruneSetting, resolveStorePath };
+module.exports = { resolveRoots, readPruneSetting, createPruneSettingsResolver, resolveStorePath };

package/src/runtime/storage/rules.js

@@ -4,7 +4,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { workStatus, createWorkCache, refreshedWorkCache } = require('./work-status.js');
+const { workStatus, recordExtension, createWorkCache, refreshedWorkCache } = require('./work-status.js');
 const { projectKey } = require('../lifecycle/report-store.js');
 const { readEvents } = require('../lifecycle/event-store.js');
 
@@ -50,7 +50,7 @@ function workCandidates(store     , entries     , context     ) {
   const project = projectRoot(roots);
   if (!project) return [];
   const cache = context.cache || createWorkCache({ projectRoot: project, fsImpl });
-  const recordMatch = new RegExp(store.match), selected        = [];
+  const recordMatch = new RegExp(store.match), extensionLength = recordExtension(store.match).length, selected        = [];
   const visit = (dir     , namespace      = null) => {
     let children;
     try { children = names(fsImpl, dir); } catch { return true; }
@@ -61,7 +61,7 @@ function workCandidates(store     , entries     , context     ) {
       if (TMP.test(name) && now - stat.mtimeMs > settings.staleTmpHours * HOUR) {
         selected.push({ name: namespace ? `${namespace}/${name}` : name, reason: 'stale-tmp', bytes: stat.size, mtimeMs: stat.mtimeMs, recordStat: stat });
       } else if (recordMatch.test(name)) {
-        const result = workStatus({ projectRoot: project, store: store.id, taskId: name.slice(0, -5), namespace, mtimeMs: stat.mtimeMs, cache, fsImpl, shouldStop });
+        const result = workStatus({ projectRoot: project, store: store.id, taskId: name.slice(0, -extensionLength), namespace, mtimeMs: stat.mtimeMs, cache, fsImpl, shouldStop });
         if (result.incomplete || shouldStop?.()) return false;
         if (result.state === 'finished' && now - result.since > store.bound.finishedDays * DAY)
           selected.push({ name: namespace ? `${namespace}/${name}` : name, reason: 'finished-work', bytes: stat.size, mtimeMs: result.since, recordStat: stat });
@@ -92,7 +92,7 @@ function recordStillCandidate(store     , candidate     , info     , context
     if (!snapshot?.ok || JSON.stringify(current) !== JSON.stringify(snapshot.value)) return false;
   }
   const fresh = cache ? refreshedWorkCache(cache) : undefined;
-  const status = workStatus({ projectRoot: projectRoot(roots), store: store.id, taskId: name.slice(0, -5), namespace, mtimeMs: info.mtimeMs, cache: fresh, fsImpl, shouldStop });
+  const status = workStatus({ projectRoot: projectRoot(roots), store: store.id, taskId: name.slice(0, -recordExtension(store.match).length), namespace, mtimeMs: info.mtimeMs, cache: fresh, fsImpl, shouldStop });
   return !status.incomplete && !shouldStop?.() && status.state === 'finished'
     && status.since === candidate.mtimeMs && now - status.since > store.bound.finishedDays * DAY;
 }
@@ -138,7 +138,7 @@ function protectedLogs({ registry, roots, fsImpl, cache, shouldStop }     ) {
           continue;
         }
         if (!stat.isFile() || !recordMatch.test(name)) continue;
-        const status = workStatus({ projectRoot: project, store: store.id, taskId: name.slice(0, -5), namespace, mtimeMs: stat.mtimeMs, cache: workCache, fsImpl, shouldStop });
+        const status = workStatus({ projectRoot: project, store: store.id, taskId: name.slice(0, -recordExtension(store.match).length), namespace, mtimeMs: stat.mtimeMs, cache: workCache, fsImpl, shouldStop });
         if (status.incomplete || shouldStop?.()) return false;
         if (status.state === 'finished') continue;
         try {
@@ -158,6 +158,73 @@ function protectedLogs({ registry, roots, fsImpl, cache, shouldStop }     ) {
   }
   return { names: protectedNames, incomplete: false };
 }
+const WORKER_UNIT = /^L\.([A-Za-z0-9][A-Za-z0-9_-]{0,55})\.([A-Za-z0-9][A-Za-z0-9_-]{0,55})\.([1-9][0-9]{0,3})\.json$/;
+/** Every `<slug>.json` store file of `.doflow/state/<dir>` read by `read`; [] when the folder is
+ * absent, null when a link sits on the path or any file cannot be read (the caller fails closed). */
+function stateStores(project        , dir        , read                                    , fsImpl     , shouldStop     )               {
+  let current = project;
+  for (const segment of ['.doflow', 'state', dir]) {
+    current = path.join(current, segment);
+    let info;
+    try { info = fsImpl.lstatSync(current); }
+    catch (error     ) { if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return []; return null; }
+    if (info.isSymbolicLink() || !info.isDirectory()) return null;
+  }
+  const stores        = [];
+  let list;
+  try { list = names(fsImpl, current); } catch { return null; }
+  for (const name of list) {
+    if (shouldStop?.()) return null;
+    if (!name.endsWith('.json')) continue;
+    const info = safeStat(fsImpl, path.join(current, name));
+    if (!info || info.isSymbolicLink() || !info.isFile()) return null;
+    try { stores.push(read(path.join(current, name), fsImpl)); } catch { return null; }
+  }
+  return stores;
+}
+/**
+ * Protect kind `unfinished-run` (row 120 IC-005): of the candidate names `L.<run>.<lineage>.<attempt>.json`,
+ * the ones to keep. A name is released only when this project's worker run store holds at least one
+ * run whose `identity` is that unit and every such run is terminal, and no dispatch naming one of
+ * those runs (`workerRunId`) is still open. Terminal is the one end phase each store has: a worker
+ * run's `phase: 'ended'` (run-store.ts PHASES, which `transition` never leaves) and a dispatch's
+ * `phase: 'ended'` (dispatch/store.ts NEXT_PHASES, add-only once reached). Everything else is kept
+ * (fail closed): an unparsable name, no project, an unknown unit (another project's file, or a run
+ * record pruned first), a link on a store path or any store file that cannot be read.
+ */
+function unfinishedRuns({ roots, fsImpl, names: candidates, shouldStop }     )                                              {
+  const all = new Set        (candidates);
+  const project = projectRoot(roots);
+  if (!project) return { names: all, incomplete: false };
+  const { readRuns } = require('../worker/run-store.js');
+  const { readDispatch } = require('../dispatch/store.js');
+  const runStores = stateStores(project, 'worker-runs', (file, impl) => ({ runs: readRuns(file, impl) }), fsImpl, shouldStop);
+  if (shouldStop?.()) return { names: all, incomplete: true };
+  const dispatchStores = runStores && stateStores(project, 'dispatch', readDispatch, fsImpl, shouldStop);
+  if (shouldStop?.()) return { names: all, incomplete: true };
+  if (!runStores || !dispatchStores) return { names: all, incomplete: false };
+  const units = new Map                                              ();
+  for (const store of runStores) for (const [runId, run] of Object.entries(store.runs)                   ) {
+    const id = run?.identity;
+    if (!id || typeof id.run !== 'string' || typeof id.lineage !== 'string' || typeof id.attempt !== 'string') continue;
+    const key = `${id.run}.${id.lineage}.${id.attempt}`;
+    const unit = units.get(key) || { ended: true, runIds: [] };
+    unit.ended = unit.ended && run.phase === 'ended';
+    unit.runIds.push(runId);
+    units.set(key, unit);
+  }
+  const openRuns = new Set        ();
+  for (const store of dispatchStores) for (const dispatch of Object.values(store.dispatches)         ) {
+    if (dispatch.phase !== 'ended' && typeof dispatch.workerRunId === 'string') openRuns.add(dispatch.workerRunId);
+  }
+  const kept = new Set        ();
+  for (const name of candidates) {
+    const match = WORKER_UNIT.exec(name);
+    const unit = match && units.get(`${match[1]}.${match[2]}.${match[3]}`);
+    if (!unit || !unit.ended || unit.runIds.some((runId) => openRuns.has(runId))) kept.add(name);
+  }
+  return { names: kept, incomplete: false };
+}
 function lifecyclePathsSafe(project     , fsImpl     ) {
   for (const rel of [path.join('.doflow'), path.join('.doflow', 'state'), path.join('.doflow', 'state', 'lifecycle'), path.join('.doflow', 'state', 'lifecycle', 'events')]) {
     try { if (fsImpl.lstatSync(path.join(project, rel)).isSymbolicLink()) return false; }
@@ -236,14 +303,19 @@ function selectCandidates(store     , entries     , context     ) {
   const { now, fsImpl, storeDir, roots, shouldStop } = context;
   switch (store.rule) {
     case 'count-and-age': {
-      const ordered = [...entries].sort((a, b) => Number(b.name.slice(0, 13)) - Number(a.name.slice(0, 13)) || a.name.localeCompare(b.name));
+      const hasTimestamp = (entry     ) => /^[0-9]{13}/.test(entry.name);
+      const entryTime = (entry     ) => hasTimestamp(entry) ? Number(entry.name.slice(0, 13)) : entry.stat.mtimeMs;
+      const ordered = [...entries].sort((a, b) => entryTime(b) - entryTime(a) || a.name.localeCompare(b.name));
       if (stopped(context)) return null;
       const selected = [];
       for (let index = 0; index < ordered.length; index += 1) {
         if (shouldStop?.()) return null;
-        const entry = ordered[index], time = Number(entry.name.slice(0, 13));
-        if (index >= store.bound.keepNewest || now - time > store.bound.maxAgeDays * DAY)
-          selected.push({ name: entry.name, reason: index >= store.bound.keepNewest ? 'count' : 'age', bytes: entry.stat.size, mtimeMs: time });
+        const entry = ordered[index], time = entryTime(entry);
+        const beyondCount = index >= store.bound.keepNewest, beyondAge = now - time > store.bound.maxAgeDays * DAY;
+        // Preserve timestamped stores' count-or-age policy; mtime entries must exceed both bounds unless bound.either is set.
+        const eitherBound = hasTimestamp(entry) || store.bound?.either === true;
+        if (eitherBound ? beyondCount || beyondAge : beyondCount && beyondAge)
+          selected.push({ name: entry.name, reason: beyondCount ? 'count' : 'age', bytes: entry.stat.size, mtimeMs: time });
       }
       return selected;
     }
@@ -279,4 +351,4 @@ function selectCandidates(store     , entries     , context     ) {
     default: throw new Error(`Unknown storage rule '${store.rule}'`);
   }
 }
-module.exports={selectCandidates,recordStillCandidate,protectedLogs,removableRules,ruleOrder,projectRoot,BODY};
+module.exports={selectCandidates,recordStillCandidate,protectedLogs,unfinishedRuns,removableRules,ruleOrder,projectRoot,BODY};

package/src/runtime/storage/upkeep.js

@@ -9,7 +9,7 @@ const { REPO_ROOT } = require('../../helper/repo-root.js');
 const { loadStorageRegistry } = require('./registry.js');
 const { resolveRoots, readPruneSetting } = require('./roots.js');
 const engine = require('./engine.js');
-const { RunLedger } = require('../trace/ledger.js');
+const { RunLedger, outerProjectRoot } = require('../trace/ledger.js');
 
 // Load once: a not-due moment only reads the three small markers, never the catalogue again.
 let registry     ;
@@ -147,7 +147,10 @@ function passForRoot({ roots, rootId, stores, now, env, fsImpl, throttled = fals
 
 /** IC-009: silent throttled upkeep after a verb, using that verb's resolved store root. */
 function upkeepAfterVerb({ projectRoot, now = Date.now(), env = process.env, fsImpl = fs }      = {}) {
+  // IC-004: the read switch, exact `off` like DOFLOW_TELEMETRY; nothing at all is written.
+  if (env.DOFLOW_UPKEEP === 'off') return;
   return silently(() => {
+    projectRoot = projectRoot && outerProjectRoot(projectRoot);
     const roots = resolveRoots({ registry, projectRoot, env });
     for (const rootId of ['project-state', 'user-state']) {
       try { ensureIgnore({ roots, rootId, projectRoot, fsImpl }); } catch { /* continue other roots */ }
@@ -165,14 +168,19 @@ function upkeepAfterVerb({ projectRoot, now = Date.now(), env = process.env, fsI
 
 /** IC-010: the verify moment is project-only and unthrottled. Wiring belongs to D.3. */
 function upkeepAfterVerify({ projectRoot, now = Date.now(), env = process.env, fsImpl = fs }      = {}) {
+  // IC-004: the switch covers every upkeep moment, so `off` prunes, locks and writes nothing here either.
+  if (env.DOFLOW_UPKEEP === 'off') return;
   return silently(() => {
+    projectRoot = projectRoot && outerProjectRoot(projectRoot);
     const roots = resolveRoots({ registry, projectRoot, env });
-    return passForRoot({ roots, rootId: 'project-state', stores: ['verification-logs'], now, env, fsImpl });
+    return passForRoot({ roots, rootId: 'project-state', stores: ['verification-logs', 'verification-reuse'], now, env, fsImpl });
   });
 }
 
 /** IC-011: only this scope's recovery store; install/update call sites belong to D.4. */
 function storageAfterInstall({ scope, scopeRoot, now = Date.now(), env = process.env, fsImpl = fs }      = {}) {
+  // IC-004: no ignore file, prune pass or lock at install time under the switch either.
+  if (env.DOFLOW_UPKEEP === 'off') return;
   return silently(() => {
     if (!['project', 'global'].includes(scope)) return;
     const global = scope === 'global';