@khoavu882/doflow 2.0.0 → 2.0.2

package/src/runtime/settings/write.js

@@ -189,10 +189,74 @@ function writeLayer({ file, set = {}, unset = [], scrubKeys = [], force = false,
   }
 }
 
+/**
+ * Where a write to `file` lands. A symlinked settings file (a dotfile manager's link) is written
+ * through to its target so the link survives; a project or local file whose link leads outside the
+ * project, or leads nowhere, is refused rather than read through or copied.
+ */
+function writeTarget(file        , fsImpl     )                                                            {
+  let stat     ;
+  try { stat = fsImpl.lstatSync(file); } catch { return { ok: true, target: file }; }
+  if (!stat.isSymbolicLink()) return { ok: true, target: file };
+  let real        ;
+  try { real = fsImpl.realpathSync(file); } catch {
+    return { ok: false, result: invalid(file, 'is a symbolic link that does not resolve to a file; nothing was written', 'scope') };
+  }
+  const directory = path.dirname(file);
+  if (path.basename(directory) === '.doflow') {
+    try {
+      const rel = path.relative(fsImpl.realpathSync(path.dirname(directory)), real);
+      if (!rel || rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) throw new Error('outside');
+    } catch {
+      return { ok: false, result: invalid(file, 'is a symbolic link to a path outside the project; nothing was written', 'scope') };
+    }
+  }
+  return { ok: true, target: real };
+}
+
+/** The most significant digits a JSON number keeps exactly when it is read as a double and written back. */
+const EXACT_DIGITS = 15;
+const NUMBER_AT = /-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/y;
+
+/**
+ * The first top-level key of `text` (a JSON document) holding a number that `JSON.parse` followed by
+ * `JSON.stringify` would change in value: more than 15 digits and not a safe integer.
+ */
+function inexactNumberKey(text        )                {
+  let depth = 0;
+  let current                = null;
+  for (let i = 0; i < text.length;) {
+    const ch = text[i];
+    if (ch === '"') {
+      let end = i + 1;
+      while (end < text.length && text[end] !== '"') end += text[end] === '\\' ? 2 : 1;
+      if (depth === 1) {
+        let after = end + 1;
+        while (after < text.length && /\s/.test(text[after])) after++;
+        if (text[after] === ':') { try { current = JSON.parse(text.slice(i, end + 1)); } catch { current = null; } }
+      }
+      i = end + 1;
+    } else if (ch === '{' || ch === '[') { depth++; i++; }
+    else if (ch === '}' || ch === ']') { depth--; i++; }
+    else if (ch === '-' || (ch >= '0' && ch <= '9')) {
+      NUMBER_AT.lastIndex = i;
+      const match = NUMBER_AT.exec(text);
+      if (!match) { i++; continue; }
+      const token = match[0];
+      const digits = token.replace(/[eE].*$/, '').replace(/[-.]/g, '').replace(/^0+/, '').replace(/0+$/, '');
+      if (digits.length > EXACT_DIGITS && !(/^-?\d+$/.test(token) && Number.isSafeInteger(Number(token))) && current !== null) return current;
+      i += token.length;
+    } else i++;
+  }
+  return null;
+}
+
 const INVALID = Symbol('invalid layer');
 
 /** The read, merge and rename of `writeLayer`, run while it holds the layer's lock. */
 function replaceLayer({ file, registry, set, unsetKeys, scrubKeys, force, expect, backup, fsImpl }     )      {
+  const landing = writeTarget(file, fsImpl);
+  if (!landing.ok) return landing.result;
   let before                                 = null;
   let existing                          = {};
   let layer     ;
@@ -231,6 +295,13 @@ function replaceLayer({ file, registry, set, unsetKeys, scrubKeys, force, expect
   for (const [key, value] of Object.entries(set)) values[key] = value;
   for (const key of unsetKeys) delete values[key];
 
+  if (layer?.status === 'ok' && typeof layer.source === 'string') {
+    const kept = inexactNumberKey(layer.source);
+    if (kept !== null && Object.hasOwn(values, kept) && !Object.hasOwn(set, kept)) {
+      return invalid(file, `key '${kept}' holds a number with more digits than JSON can rewrite exactly; nothing was written; edit the file by hand`, 'number-precision');
+    }
+  }
+
   const after = layerDocument(registry, values);
   const bytes = serializeLayer(after);
   const tooLarge = oversize(file, bytes);
@@ -244,7 +315,7 @@ function replaceLayer({ file, registry, set, unsetKeys, scrubKeys, force, expect
   const directory = path.dirname(file);
   let temporary                = null;
   try {
-    temporary = path.join(directory, `.${path.basename(file)}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`);
+    temporary = path.join(path.dirname(landing.target), `.${path.basename(landing.target)}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`);
     fsImpl.writeFileSync(temporary, bytes, { flag: 'wx', mode: 0o600 });
     fsImpl.chmodSync(temporary, 0o600);
     if (path.basename(directory) === '.doflow') {
@@ -253,7 +324,7 @@ function replaceLayer({ file, registry, set, unsetKeys, scrubKeys, force, expect
         return invalid(file, '.doflow symlink points outside the project', 'scope');
       }
     }
-    fsImpl.renameSync(temporary, file);
+    fsImpl.renameSync(temporary, landing.target);
     temporary = null;
     clearSettingsCache();
     return { ok: true, file, before, after };

package/src/runtime/slots.js

@@ -185,7 +185,7 @@ const refuse = (why        ) => Object.assign(new Error(why), { code: 'EBUSY' })
  * directory name this lock does not make once the lock is 10 s old, as in task-state. An older
  * runtime's lock (its `owner.json` token) is judged the same way. `reclaimed` records that this acquire
  * judged a lock reclaimable, so it holds only after `quiet` (every reclaim quiets; user ruling, 117
- * decisions: amends 115 C-4's "dead owner reclaimed at once"). See docs/architecture.md, "The slot lock".
+ * decisions: amends 115 C-4's "dead owner reclaimed at once").
  */
 function slotLock(fsImpl     , deps     ) {
   const start = deps.procStart(deps.pid);

package/src/runtime/storage/registry.js

@@ -13,7 +13,7 @@ const RULES                        = new Map([
   ['date-partition', ['maxAgeDays']],
   ['recovery', ['keepNewest']],
   ['lifecycle-settled', ['defaultHours']],
-  ['report-orphan', ['orphanGraceHours', 'foreignMaxAgeDays']],
+  ['report-orphan', ['orphanGraceHours']],
   ['age', ['maxAgeDays']],
   ['existing', []],
   ['control', []],
@@ -132,7 +132,7 @@ function formatBound(store     )         {
     case 'date-partition': return `prune partitions older than ${bound.maxAgeDays} days`;
     case 'recovery': return `keep newest ${bound.keepNewest}, plus the snapshot named by the ledger`;
     case 'lifecycle-settled': return `retain settled events for ${bound.defaultHours} hours`;
-    case 'report-orphan': return `prune orphan bodies after ${bound.orphanGraceHours} hours; foreign folders after ${bound.foreignMaxAgeDays} days`;
+    case 'report-orphan': return `prune orphan bodies after ${bound.orphanGraceHours} hours; foreign folders are kept`;
     case 'age': return `prune inactive directories after ${bound.maxAgeDays} days`;
     case 'existing':
     case 'control': return bound.text;

package/src/runtime/storage/roots.js

@@ -31,16 +31,9 @@ function createPruneSettingsResolver({ roots, fsImpl = fs, onView }      = {})
     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 { loadSettings, registryOn } = require('../settings/resolve.js');
         const projectRoot = roots['project-doflow'] ? path.dirname(roots['project-doflow']) : null;
-        view = loadSettings({ projectRoot, env: resolverEnv, fsImpl, ...(settingsRegistry ? { registry: settingsRegistry } : {}) });
+        view = loadSettings({ projectRoot, env: resolverEnv, fsImpl, ...registryOn(fsImpl) });
       } catch {
         // A settings registry fault fails closed for every root, as it did for each old call.
         view = null;
@@ -69,15 +62,8 @@ function readPruneSetting({ roots, rootId, fsImpl = fs }      = {})
   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 { loadSettings, registryOn } = require('../settings/resolve.js');
+    const view = loadSettings({ projectRoot, global, env: resolverEnv, fsImpl, ...registryOn(fsImpl) });
     const resolved = view.get('storage.prune', global ? 'global' : 'project');
     return {
       setting: resolved.value === 'on' ? 'on' : 'off',

package/src/runtime/storage/rules.js

@@ -232,16 +232,15 @@ function lifecyclePathsSafe(project     , fsImpl     ) {
   }
   return true;
 }
-function definitelyMissing(fsImpl     , target     ) {
-  try { fsImpl.lstatSync(target); return false; }
-  catch (error     ) { return error.code === 'ENOENT' || error.code === 'ENOTDIR'; }
-}
 function reportCandidates(store     , entries     , context     ) {
   const { fsImpl, storeDir, roots, now, settings, shouldStop } = context;
   const project = projectRoot(roots);
   const key = project && projectKey(project, fsImpl), selected = [];
   for (const entry of entries) {
     if (shouldStop?.()) throw budgetError();
+    // A folder under another project's key stays: ENOENT or ENOTDIR on its recorded root never
+    // authorises deleting it, since an unmounted or renamed root looks the same as a gone one.
+    if (entry.name !== key) continue;
     const folder = path.join(storeDir, entry.name);
     let children, bodyNames = [];
     try {
@@ -251,50 +250,27 @@ function reportCandidates(store     , entries     , context     ) {
         if (BODY.test(name) && safeStat(fsImpl, path.join(folder, name))?.isFile()) bodyNames.push(name);
       }
     } catch (error     ) { if (error.partial) throw error; continue; }
-    if (entry.name === key) {
-      const lifecycle = path.join(project, '.doflow/state/lifecycle');
-      if (!safeStat(fsImpl, path.join(lifecycle, 'migrated.json'))?.isFile() || !lifecyclePathsSafe(project, fsImpl)) continue;
-      let snapshot;
-      try { snapshot = readEvents(project, { fsImpl, lockFallback: false, shouldStop }); }
-      catch { continue; }
-      if (snapshot.incomplete) throw budgetError();
-      if (snapshot.unreadable.length) continue;
-      const eventIds = new Set();
-      for (const event of snapshot.events) {
-        if (shouldStop?.()) throw budgetError();
-        const ids = [event.data.id, ...(Array.isArray(event.data.ids) ? event.data.ids : [])];
-        for (const id of ids) {
-          if (shouldStop?.()) throw budgetError();
-          if (typeof id === 'string' && /^FU-[0-9a-hjkmnp-tv-z]{6}$/.test(id)) eventIds.add(id);
-        }
-      }
-      for (const body of bodyNames) {
-        if (shouldStop?.()) throw budgetError();
-        const stat = safeStat(fsImpl, path.join(folder, body));
-        if (stat && !eventIds.has(body.slice(0, -4)) && now - stat.mtimeMs > settings.orphanGraceHours * HOUR)
-          selected.push({ name: `${entry.name}/${body}`, reason: 'orphan-body', bytes: stat.size, mtimeMs: stat.mtimeMs });
-      }
-    } else {
-      const marker = path.join(folder, '.root');
-      if (!safeStat(fsImpl, marker)?.isFile() || !bodyNames.length) continue;
-      let validFolder = true;
-      for (const name of children) {
+    const lifecycle = path.join(project, '.doflow/state/lifecycle');
+    if (!safeStat(fsImpl, path.join(lifecycle, 'migrated.json'))?.isFile() || !lifecyclePathsSafe(project, fsImpl)) continue;
+    let snapshot;
+    try { snapshot = readEvents(project, { fsImpl, lockFallback: false, shouldStop }); }
+    catch { continue; }
+    if (snapshot.incomplete) throw budgetError();
+    if (snapshot.unreadable.length) continue;
+    const eventIds = new Set();
+    for (const event of snapshot.events) {
+      if (shouldStop?.()) throw budgetError();
+      const ids = [event.data.id, ...(Array.isArray(event.data.ids) ? event.data.ids : [])];
+      for (const id of ids) {
         if (shouldStop?.()) throw budgetError();
-        if (name !== '.root' && !bodyNames.includes(name)) { validFolder = false; break; }
+        if (typeof id === 'string' && /^FU-[0-9a-hjkmnp-tv-z]{6}$/.test(id)) eventIds.add(id);
       }
-      if (!validFolder) continue;
-      let root;
-      try { root = fsImpl.readFileSync(marker, 'utf8').trim(); } catch { continue; }
-      if (!path.isAbsolute(root) || !definitelyMissing(fsImpl, root)) continue;
-      let newest = -Infinity;
-      for (const body of bodyNames) {
-        if (shouldStop?.()) throw budgetError();
-        const stat = safeStat(fsImpl, path.join(folder, body));
-        if (!stat) { newest = Infinity; break; }
-        newest = Math.max(newest, stat.mtimeMs);
-      }
-      if (now - newest > store.bound.foreignMaxAgeDays * DAY)
-        selected.push({ name: entry.name, reason: 'foreign-root-gone', bytes: entry.stat.size, mtimeMs: newest });
+    }
+    for (const body of bodyNames) {
+      if (shouldStop?.()) throw budgetError();
+      const stat = safeStat(fsImpl, path.join(folder, body));
+      if (stat && !eventIds.has(body.slice(0, -4)) && now - stat.mtimeMs > settings.orphanGraceHours * HOUR)
+        selected.push({ name: `${entry.name}/${body}`, reason: 'orphan-body', bytes: stat.size, mtimeMs: stat.mtimeMs });
     }
   }
   return selected;

package/src/runtime/storage/work-status.js

@@ -81,6 +81,17 @@ function isRunNamespaceDir(name        )          {
   return safeSegment(name) && !name.endsWith('.lock');
 }
 
+/**
+ * Whether a flat run is superseded by a namespaced copy: it names that copy's namespace as its own
+ * feature (`featureSlug`, else `slug`) and the copy has the same file name. A flat run that names
+ * no feature, or one whose namespace holds no copy, is a run of its own and is never dropped. The
+ * one ownership rule for every reader that walks `orchestration/` (health, trace, work status).
+ */
+function isSupersededFlatRun(name        , value     , copies                                            )          {
+  const own = stringField(value, 'featureSlug') || stringField(value, 'slug');
+  return own !== null && isRunNamespaceDir(own) && copies.some((copy) => copy.namespace === own && copy.name === name);
+}
+
 /**
  * Every run id the orchestration store holds, flat or under a `<slug>/` namespace (115 C-1: a task id
  * other than its feature's slug lives in `orchestration/<slug>/`). `cache.runLocations` maps each id
@@ -136,9 +147,8 @@ function readRunAt(cache     , runId        , where        )      {
   const file = path.join(stateRoot(cache.projectRoot), 'orchestration', ...(where ? [where] : []), `${runId}.json`);
   let result     ;
   try {
-    // A namespaced copy is a file base never read (N-4): a link, a FIFO or a device there reads as
-    // unreadable (the record is kept) and never blocks. The flat copy keeps its plain read (FU-d88kp0).
-    const text = where && typeof cache.fsImpl.lstatSync === 'function' && typeof cache.fsImpl.openSync === 'function'
+    // A link, a FIFO or a device there reads as unreadable (the record is kept) and never blocks.
+    const text = typeof cache.fsImpl.lstatSync === 'function' && typeof cache.fsImpl.openSync === 'function'
       ? require('../task-scope.js').readRegularFileText(file, cache.fsImpl) : cache.fsImpl.readFileSync(file, 'utf8');
     if (text === null) throw new Error('not a regular file');
     const value = JSON.parse(text);
@@ -542,4 +552,4 @@ function workStatus({
   return answer('finished', run ? 'run-finished' : 'no-run', resolvedRun.id, feature, since);
 }
 
-module.exports = { workStatus, recordExtension, createWorkCache, refreshedWorkCache, RUN_OPEN_STATES };
+module.exports = { workStatus, recordExtension, createWorkCache, refreshedWorkCache, RUN_OPEN_STATES, isRunNamespaceDir, isSupersededFlatRun };

package/src/runtime/task-classifier.js

@@ -6,7 +6,8 @@ const path = require('node:path');
 const fs = require('node:fs');
 const { TextDecoder } = require('node:util');
 const { WorkflowEngine, CALLER_ROLES } = require('./workflow-engine.js');
-const { finishRuntime } = require('./cli-result.js');
+const { finishRuntime, usageError } = require('./cli-result.js');
+const { ViewUsageError, resolveView, projectBrief, viewLines, withEnvelope, emitJson } = require('./verb-view.js');
 const { REPO_ROOT } = require('../helper/repo-root.js');
 const { loadAdviceRegistry } = require('./advice/registry.js');
 const { createAdviceClient } = require('./advice/client.js');
@@ -421,6 +422,25 @@ class TaskClassifier {
   }
 }
 
+/**
+ * The brief view of a classify answer (feature 137, IC-005): the fields the skills' classify call sites read.
+ * Everything else is dropped; `--view full` returns the whole object.
+ */
+const CLASSIFY_BRIEF = Object.freeze({
+  verb: 'classify',
+  carry: Object.freeze(['taskClass', 'callingSkill']),
+  keep: Object.freeze([
+    '$.outcome', '$.taskClass', '$.proposedClass', '$.callingSkill', '$.reason', '$.message', '$.validClasses',
+    '$.suggestions', '$.callerSuggestions', '$.fit.state', '$.fit.reason', '$.fit.hostingClasses', '$.secondOpinion',
+    '$.workflow.taskClass', '$.workflow.handoff', '$.workflow.stageIds', '$.workflow.hasImplementationStage',
+    '$.workflow.requiresImplementationReadiness', '$.workflow.stages[].id', '$.workflow.stages[].skill',
+    '$.workflow.stages[].agent', '$.workflow.stages[].kind', '$.workflow.stages[].optional',
+    '$.workflow.stages[].readinessTemplate', '$.workflow.stages[].mutatesSource', '$.workflow.gates[].id',
+    '$.workflow.gates[].afterStage', '$.workflow.gates[].kind', '$.workflow.gates[].trigger',
+    '$.workflow.gates[].prompt',
+  ]),
+});
+
 /**
  * Handles `doflow classify` — validate a proposed task class against the workflow registry.
  *
@@ -437,16 +457,31 @@ class TaskClassifier {
  * @param {string} [options.request] request text for a second opinion
  * @param {string} [options.requestFile] file containing request text for a second opinion
  * @param {boolean} [options.json=false]
+ * @param {string} [options.view] `brief` or `full` (default): the JSON answer's view; text output is the same in both
  * @returns {number|Promise<number>} exit code; advisory calls are asynchronous
  */
-function handleClassifyCommand({ taskClass, rationale, proposedBy, callingSkill, request, requestFile, taskId, projectRoot, env = process.env, json = false }      = {}) {
+function handleClassifyCommand({ taskClass, rationale, proposedBy, callingSkill, request, requestFile, taskId, projectRoot, view, env = process.env, json = false }      = {}) {
+  let resolvedView;
+  try {
+    resolvedView = resolveView(view, 'full');
+  } catch (error     ) {
+    if (error instanceof ViewUsageError) return usageError('classify', error.message, json);
+    throw error;
+  }
+  const printJson = (opinion     ) => {
+    const answer = { ...decision, secondOpinion: opinion };
+    if (resolvedView === 'full') return emitJson(answer);
+    return emitJson(withEnvelope(projectBrief(answer, CLASSIFY_BRIEF.keep), {
+      view: 'brief', next: viewLines('full', { spec: CLASSIFY_BRIEF, carried: { taskClass, callingSkill }, json: true }),
+    }));
+  };
   const classifier = new TaskClassifier({ repoRoot: REPO_ROOT });
   const decision = classifier.classify({ taskClass, rationale, proposedBy, callingSkill });
   const exitCode = decision.outcome === CLASSIFICATION_OUTCOMES.ACCEPTED
     ? 0 : decision.reason === REJECTION_REASONS.MISSING_CLASS ? 2 : 1;
   const hasRequest = request !== undefined || requestFile !== undefined;
   if (!hasRequest) {
-    if (json) console.log(JSON.stringify({ ...decision, secondOpinion: null }, null, 2));
+    if (json) printJson(null);
     else printClassifyDecision(decision, null);
     return finishRuntime(exitCode);
   }
@@ -528,7 +563,7 @@ function handleClassifyCommand({ taskClass, rationale, proposedBy, callingSkill,
         opinion = emptySecondOpinion('unavailable', 'config-invalid');
       }
     }
-    if (json) console.log(JSON.stringify({ ...decision, secondOpinion: opinion }, null, 2));
+    if (json) printJson(opinion);
     else printClassifyDecision(decision, opinion);
     return finishRuntime(exitCode);
   }

package/src/runtime/task-scope.js

@@ -176,9 +176,23 @@ function readRegularFileText(file        , fsImpl      = fs)                {
   }
 }
 
+/** Whether `slug` is a register feature (it has `decisions/register.json`), for a record file under
+ * a checkout's `.doflow/state`. Such a feature never reads another feature's identity-less flat
+ * record (045 isolation). A file whose checkout cannot be told, or a feature that does not resolve,
+ * has no register. */
+function featureHasRegister(file        , slug        )          {
+  const marker = `${path.sep}.doflow${path.sep}state${path.sep}`;
+  const at = file.lastIndexOf(marker);
+  if (at <= 0) return false;
+  try {
+    const found = resolveFeature({ projectRoot: file.slice(0, at), slug });
+    return !found.error && Boolean(found.featureDir) && fs.existsSync(path.join(found.featureDir, 'decisions', 'register.json'));
+  } catch { return false; }
+}
+
 /**
  * Whether a flat record may be read as `slug`'s (D-3): it names that feature (`featureSlug` on a
- * run, `slug` on a readiness record) or names none. A file that does not parse names nobody, so a
+ * run, `slug` on a readiness record), or names none and `slug` has no decision register. A file that does not parse names nobody, so a
  * namespaced read never falls back to it. The probe never blocks and follows no link: a flat file
  * that is not a regular file of at most `MAX_RECORD_FILE_BYTES` is not read; `unsafeIsOurs` is then
  * the answer, so a caller whose reader refuses such a file (the run store's `readRunRecord`) is
@@ -198,7 +212,8 @@ function flatRecordIsOurs(file        , slug               , fsImpl      = fs, u
     data = JSON.parse(text);
   } catch { return false; }
   const named = [data?.featureSlug, data?.slug].find((value) => typeof value === 'string' && value !== '');
-  return named === undefined || named === slug;
+  if (named === undefined) return !slug || !featureHasRegister(file, slug);
+  return named === slug;
 }
 
 /**

package/src/runtime/task-state.js

@@ -103,8 +103,7 @@ function sleep(ms        )       {
 // Runtimes from before this protocol see a directory they did not create: they wait on a fresh one,
 // and on a stale one their rmdir fails (it is not empty), so they fail closed ("Could not lock",
 // `store-locked`) instead of taking it; their release of a lock reclaimed from them fails the same
-// way. Whatever a process leaves when it dies is reclaimed once LOCK_STALE_MS old. The bounds (what
-// this does not cover) are listed once, in docs/architecture.md under "The task-state lock".
+// way. Whatever a process leaves when it dies is reclaimed once LOCK_STALE_MS old.
 const OWNER_PREFIX = 'owner-';
 // The longest a fresh acquire may take from its mkdir to its entry and still trust the directory is
 // its own: half the stale age, so a process that judged it stale cannot have done so before the
@@ -307,7 +306,7 @@ function ownedRelease(fsImpl     , lockDir        , me       )      {
     try { fsImpl.rmdirSync(entry); } catch { return; } // reclaimed: the lock is not ours to remove
     // Removed only if it is still that directory: a release stalled here past LOCK_STALE_MS may find
     // an older runtime's new (empty) lock at the path. What stays is the gap between this stat and the
-    // rmdir (docs/architecture.md, "The task-state lock", bound 3).
+    // rmdir.
     try {
       if (mine && sameDir(mine, fsImpl.statSync(lockDir))) fsImpl.rmdirSync(lockDir);
     } catch { /* a waiting process's entry is in it; that process holds next */ }
@@ -377,10 +376,14 @@ function acquireLock(fsImpl     , file        , options              = {})
     + strayEntries(fsImpl, lockDir));
 }
 
-/** Names a non-directory entry in the lock (no DoFlow runtime makes one; it blocks the lock until removed). */
+/** The non-directory entries in the lock (no DoFlow runtime makes one; each blocks the lock until removed). */
+function strayNames(fsImpl     , lockDir        )           {
+  try { return fsImpl.readdirSync(lockDir, { withFileTypes: true }).filter((d     ) => !d.isDirectory()).map((d     ) => d.name); } catch { return []; }
+}
+
+/** `strayNames` as the sentence the lock timeout carries. */
 function strayEntries(fsImpl     , lockDir        )         {
-  let stray           = [];
-  try { stray = fsImpl.readdirSync(lockDir, { withFileTypes: true }).filter((d     ) => !d.isDirectory()).map((d     ) => d.name); } catch { return ''; }
+  const stray = strayNames(fsImpl, lockDir);
   if (stray.length === 0) return '';
   return ` It holds ${stray.map((name) => `'${name}'`).join(', ')}, which no DoFlow runtime makes and which keeps it locked: `
     + `remove ${stray.length > 1 ? 'them' : 'it'} once no DoFlow process is running.`;
@@ -390,7 +393,8 @@ function strayEntries(fsImpl     , lockDir        )         {
  * Takes the cross-process lock for one state file with a bounded wait.
  * Makes 1 try plus `retries` retries (default 3) separated by `waitMs` (default 5); each try is one
  * tryAcquireLock, which waits at most 40 ms, and only on a process that reached the lock at the same moment.
- * Throws an Error('store-locked') after one try plus retries.
+ * Throws an Error('store-locked') after one try plus retries, carrying `lockPath` (the lock folder) and
+ * `strayEntries` (the names in it that no DoFlow runtime makes) as properties.
  * @param {Object} fsImpl
  * @param {string} file
  * @param {Object} [options]
@@ -421,6 +425,8 @@ function boundedAcquire(
   }
   const error = new Error('store-locked');
   (error       ).code = 'store-locked';
+  (error       ).lockPath = `${file}.lock`;
+  (error       ).strayEntries = strayNames(fsImpl, `${file}.lock`);
   throw error;
 }
 

package/src/runtime/trace/analyze.js

@@ -115,8 +115,10 @@ function latencyHotspots(scopes       , th     , latency       )      {
     const groups = new Map             ();
     for (const s of sc.spans) {
       if (!Number.isInteger(s.durationMs) || !ranItself(s)) continue;
-      const key = `${s.kind}\n${s.name ?? ''}`;
-      if (!groups.has(key)) groups.set(key, { kind: s.kind, name: s.name ?? null, spans: [] });
+      // Every derived `test` span is named 'test'; the command's class tells unrelated shell commands apart.
+      const name = s.kind === 'test' && typeof s.attrs?.test_class === 'string' ? s.attrs.test_class : (s.name ?? null);
+      const key = `${s.kind}\n${name ?? ''}`;
+      if (!groups.has(key)) groups.set(key, { kind: s.kind, name, spans: [] });
       groups.get(key).spans.push(s);
     }
     for (const g of [...groups.values()].sort((a, b) => cmp(a.kind, b.kind) || cmp(a.name ?? '', b.name ?? ''))) {

package/src/runtime/trace/indicators.js

@@ -40,27 +40,33 @@ function parseAt(value     )                {
   return Number.isNaN(ms) ? null : ms;
 }
 
-/** Every record in a directory, plus the names of the ones that did not parse. A file that cannot be
- * read is counted and named rather than skipped: a report that quietly drops what it could not read
- * overstates its own coverage, which is the defect `malformedLines` already guards against for runs. */
-function readRecords(dir        , fsImpl      = fs)      {
-  if (!fsImpl.existsSync(dir)) return { records: [], unreadable: [], exists: false };
-  const records        = [];
+/** Every run the `list` action shows (flat and namespaced, this checkout and the other ones, each
+ * logical run once), plus the ones that could not be read, named with a fixed reason. A file that
+ * cannot be read is counted and named rather than skipped: a report that quietly drops what it could
+ * not read overstates its own coverage, which is the defect `malformedLines` already guards against
+ * for runs. The reason is never the error's own text, which can carry a path or file bytes. */
+function readRecords(root        )      {
+  const { orchestrationRuns, runEntriesAt, selectRunEntries, runStoreDir } = require('../implementation-gate.js');
+  const listed = orchestrationRuns({ stateRoot: root });
   const unreadable        = [];
-  for (const name of fsImpl.readdirSync(dir).sort()) {
-    if (!name.endsWith('.json')) continue;
-    try {
-      const parsed = JSON.parse(fsImpl.readFileSync(path.join(dir, name), 'utf8'));
-      if (!parsed || typeof parsed !== 'object' || !parsed.taskId) {
-        unreadable.push({ file: name, reason: 'not an orchestration record' });
-        continue;
-      }
-      records.push(parsed);
-    } catch (err     ) {
-      unreadable.push({ file: name, reason: err.message });
+  let entries       ;
+  if (listed.ok) entries = selectRunEntries(listed.entries);
+  else {
+    entries = selectRunEntries(runEntriesAt(root, 'current'));
+    unreadable.push({ file: '(other checkouts)', reason: 'could not be listed' });
+  }
+  const records        = [];
+  for (const entry of entries) {
+    const name = entry.origin === 'other' ? entry.file : path.relative(runStoreDir(entry.root), entry.file);
+    if (entry.error) {
+      unreadable.push({ file: name, reason: entry.error === 'io' ? 'not a regular file' : 'not valid JSON' });
+    } else if (!entry.record || typeof entry.record !== 'object' || !entry.record.taskId) {
+      unreadable.push({ file: name, reason: 'not an orchestration record' });
+    } else {
+      records.push(entry.record);
     }
   }
-  return { records, unreadable, exists: true };
+  return { records, unreadable, exists: entries.length > 0 || fs.existsSync(orchestrationDir(root)) };
 }
 
 /** A stage row is "not work done" when the orchestrator backfilled it or imported it rather than
@@ -196,8 +202,7 @@ function printClass(group     )       {
 }
 
 function handleIndicatorsCommand({ json = false, projectRoot = process.cwd() } = {})         {
-  const dir = orchestrationDir(projectRoot);
-  const read = readRecords(dir);
+  const read = readRecords(projectRoot);
   const view = buildIndicators(read);
 
   if (json) {

package/src/runtime/trace/spans.js

@@ -9,6 +9,7 @@ const { resolveRunsLocation, normalizeRunRecord } = require('./ledger.js');
 const { SAFE_TOKEN } = require('./telemetry.js');
 const { finish } = require('./render.js');
 const { REPO_ROOT } = require('../../helper/repo-root.js');
+const { isRunNamespaceDir, isSupersededFlatRun } = require('../storage/work-status.js');
 
 /**
  * `trace spans` (088 IC-011, FR-005, DD-5): spans projected offline from the records that already
@@ -63,7 +64,6 @@ const { REPO_ROOT } = require('../../helper/repo-root.js');
 
 const PARTITION = /^\d{4}-\d{2}-\d{2}\.jsonl$/;
 const STORE_FILE = /^[A-Za-z0-9][A-Za-z0-9._-]*\.json$/;
-const NAMESPACE_DIR = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const HEX16 = /^[0-9a-f]{16}$/;
 const HEX32 = /^[0-9a-f]{32}$/;
 const WORKER_RUN_ID = /^w-[0-9a-f]{12}$/;
@@ -201,15 +201,14 @@ function readStores(fsImpl     , stateDir        , rel        , gaps       , kin
   if (!namespaced) return out.map(({ file, value }) => ({ file, value }));
   let entries        = [];
   try { entries = fsImpl.readdirSync(base, { withFileTypes: true }); } catch { entries = []; }
-  const namespaces = entries.filter((entry     ) => entry.isDirectory() && NAMESPACE_DIR.test(entry.name) && !entry.name.endsWith('.lock'))
+  const namespaces = entries.filter((entry     ) => entry.isDirectory() && isRunNamespaceDir(entry.name))
     .map((entry     ) => entry.name).sort();
   for (const namespace of namespaces) {
     const dir = path.join(base, namespace);
     for (const name of listDir(fsImpl, dir, STORE_FILE)) read(`${rel}/${namespace}/${name}`, name, dir, namespace);
   }
-  const copied = (flat     )          => out.some((other) => other.namespace !== ''
-    && other.name === flat.name && (typeof flat.value.featureSlug !== 'string' || flat.value.featureSlug === other.namespace));
-  return out.filter((entry) => entry.namespace !== '' || !copied(entry)).map(({ file, value }) => ({ file, value }));
+  const copies = out.filter((other) => other.namespace !== '');
+  return out.filter((entry) => entry.namespace !== '' || !isSupersededFlatRun(entry.name, entry.value, copies)).map(({ file, value }) => ({ file, value }));
 }
 
 const objects = (v     )                       => (v && typeof v === 'object' && !Array.isArray(v)