@khoavu882/doflow 2.0.1 → 2.0.2

package/src/runtime/context-pack.js

@@ -10,7 +10,7 @@ const { ClaimsManager } = require('./claims.js');
 const { ResearchRequestStore } = require('./research-request.js');
 const { finishRuntime, usageError, EXIT } = require('./cli-result.js');
 const nativeConsoleLog = console.log;
-const { resolveFeature } = require('./task-scope.js');
+const { resolveFeature, isSafeSlug } = require('./task-scope.js');
 const { readRegister } = require('./decision-register.js');
 const compose = require('./context/compose.js');
 const {
@@ -122,6 +122,13 @@ function classifyStoreFailure(error     )         {
   return 'store-unwritable';
 }
 
+/** A store-locked failure's additive diagnostics for `delivery`: the lock folder (relative to the
+ * state root) and the stray entries blocking it. Empty for any other failure. */
+function lockDiagnostics(error     , root        )                                                 {
+  if (classifyStoreFailure(error) !== 'store-locked' || typeof error?.lockPath !== 'string') return {};
+  return { lockPath: path.relative(root, error.lockPath), strayEntries: Array.isArray(error.strayEntries) ? error.strayEntries : [] };
+}
+
 function profileRetention(harnessId               , profiles              )      {
   if (!harnessId) return null;
   const harnesses = profiles || getRegisteredHarnesses();
@@ -949,7 +956,9 @@ function handleContextPackCommand({
 
   const budget = resolveBudget({ taskClass: effectiveTaskClass, maxBytes: parsedMaxBytes, harnessFlag: harness, profiles });
 
-  const feature = resolveFeature({ projectRoot: source, slug: slug || null });
+  const resolved = resolvePackFeature({ source, stateRoot: root, taskId, slug, typed: explicitSlug });
+  slug = resolved.slug;
+  const feature = resolved.feature;
 
   let deltaExpansions        = [];
   if (parsedMaxBytes !== undefined) {
@@ -1008,6 +1017,7 @@ function handleContextPackCommand({
         recordReason = null;
       } catch (error     ) {
         recordReason = error?.code === 'entry-evicted' ? 'entry-evicted' : classifyStoreFailure(error);
+        Object.assign(pack.delivery, lockDiagnostics(error, root));
       }
     }
     pack.delivery.recorded = expansionRecorded;
@@ -1115,6 +1125,7 @@ function deliverPack({
   const form = json ? 'json' : 'markdown';
   let deliveryRecorded = !noRecord;
   let deliveryReason                = noRecord ? 'no-record' : null;
+  let deliveryLock                                                 = {};
   pack.delivery.recorded = deliveryRecorded;
   pack.delivery.reason = deliveryReason;
   pack.delivery.key = noRecord ? null : `${pack.delivery.packDigest}.${form}.${budget.harness?.id || 'unstated'}`;
@@ -1175,6 +1186,7 @@ function deliverPack({
         pack = trimmed;
         pack.delivery.recorded = deliveryRecorded;
         pack.delivery.reason = deliveryReason;
+        Object.assign(pack.delivery, deliveryLock);
         pack.delivery.key = deliveryRecorded ? `${pack.delivery.packDigest}.${form}.${budget.harness?.id || 'unstated'}` : null;
         pack.accounting.tokens = makeTokenRecord(json ? jsonBytes : mdBytes);
         pack.omissions = pack.mode === 'bare' ? pack.omissions : compose.groupOmissions(pack.deliveryOmissions, !noRecord);
@@ -1224,6 +1236,8 @@ function deliverPack({
     } catch (error     ) {
       deliveryRecorded = false;
       deliveryReason = classifyStoreFailure(error);
+      deliveryLock = lockDiagnostics(error, root);
+      Object.assign(pack.delivery, deliveryLock);
       pack.delivery.key = null;
       pack.delivery.recorded = deliveryRecorded;
       pack.delivery.reason = deliveryReason;
@@ -1274,10 +1288,13 @@ function resolveDeltaBasis({ root, source = root, taskId, slug, since, budget, p
 function gatherMandatory({ root, taskId, feature }     ) {
   let reqText                = null;
   let reqPath = 'requirement.md';
+  // The folder lives in `featureRoot`, the checkout that holds it: the main checkout when the
+  // checkout the verb runs in has none of its own.
+  const folder = feature.featureFolder || feature.featureDir;
   if (!feature.error && feature.featureDir) {
     reqPath = feature.paths?.requirement
-      ? path.resolve(feature.repoRoot || root, feature.paths.requirement)
-      : path.join(feature.featureDir, 'intention', 'requirement.md');
+      ? path.resolve(feature.featureRoot || feature.repoRoot || root, feature.paths.requirement)
+      : path.join(folder, 'intention', 'requirement.md');
     try {
       if (fs.existsSync(reqPath)) {
         reqText = fs.readFileSync(reqPath, 'utf8');
@@ -1291,10 +1308,10 @@ function gatherMandatory({ root, taskId, feature }     ) {
   if (!feature.error && feature.featureDir && taskId) {
     let planPath                = null;
     if (feature.paths?.plan) {
-      planPath = path.resolve(feature.repoRoot || root, feature.paths.plan);
+      planPath = path.resolve(feature.featureRoot || feature.repoRoot || root, feature.paths.plan);
     } else {
-      const nestedPlan = path.join(feature.featureDir, 'plan', 'plan.md');
-      const flatPlan = path.join(feature.featureDir, 'plan.md');
+      const nestedPlan = path.join(folder, 'plan', 'plan.md');
+      const flatPlan = path.join(folder, 'plan.md');
       if (fs.existsSync(nestedPlan)) planPath = nestedPlan;
       else if (fs.existsSync(flatPlan)) planPath = flatPlan;
     }
@@ -1323,6 +1340,27 @@ function gatherMandatory({ root, taskId, feature }     ) {
   });
 }
 
+/**
+ * The feature a pack is compiled for, as `{slug, feature}`. A `--slug` the caller typed wins; without
+ * one, a task id that names an existing feature folder (in this checkout, the state root's, or the
+ * checkout the branch's feature was found in) is that feature's own task, ahead of the branch's feature, so the
+ * objective, artifacts and records all select the same feature (a pack for feature B's task id run
+ * on feature A's branch). The common case, a task id that names no feature, resolves nothing extra.
+ * @param {{source: string, taskId: string, slug?: string|null, typed?: string|null}} options
+ *   `typed`: the `--slug` the caller typed, when it is known; absent means `slug` was given on purpose.
+ */
+function resolvePackFeature({ source, stateRoot = source, taskId, slug, typed }     ) {
+  const feature = resolveFeature({ projectRoot: source, slug: slug || null });
+  if (typed || (typed === undefined && slug) || !isSafeSlug(taskId) || (!feature.error && feature.paths?.feature_slug === taskId)) return { slug, feature };
+  const roots = new Set        ([source, stateRoot, feature.repoRoot, feature.paths?.repo_root].filter((root) => typeof root === 'string' && root !== ''));
+  if (![...roots].some((root) => fs.existsSync(path.join(root, 'agent-docs', 'doflow', taskId)))) return { slug, feature };
+  try {
+    const own = resolveFeature({ projectRoot: source, slug: taskId });
+    if (!own.error && fs.existsSync(own.featureFolder || own.featureDir || '')) return { slug: taskId, feature: own };
+  } catch { /* a failed lookup keeps the branch's feature */ }
+  return { slug, feature };
+}
+
 /**
  * 078 IC-001: the context pack `emitContext()` delivers on `launch` and `delta`, compiled by
  * compileContextPack() through the verb's own steps, with `maxBytes` as the budget and `since` the
@@ -1331,7 +1369,9 @@ function gatherMandatory({ root, taskId, feature }     ) {
  */
 function packForEmission({ root, stateRoot = root, taskId = 'default', taskClass = 'feature', slug = null, harness = null, maxBytes, since = null, noRecord = false, env = process.env }     )                                {
   const budget = resolveBudget({ taskClass, maxBytes, harnessFlag: harness, env });
-  const feature = resolveFeature({ projectRoot: root, slug: slug || null });
+  const resolved = resolvePackFeature({ source: root, stateRoot, taskId, slug, typed: slug || null });
+  slug = resolved.slug;
+  const feature = resolved.feature;
   // 115 C-2: the delivery record goes where `context-pack` puts it, under the state root; the feature
   // folder, the plan and the hashed source files are read in `root`, the checkout emitting.
   const basis = resolveDeltaBasis({ root: stateRoot, source: root, taskId, slug, since, budget, profiles: null });

package/src/runtime/dispatch/integrate.js

@@ -17,8 +17,10 @@
 // Integration (IC-018). One dispatch per call, under the store's lease: `cherry-pick --no-commit`
 // of `C` on the integration HEAD, `write-tree`, `commit-tree` on the pre-integration head, then
 // `update-ref` naming that head as the expected old value, so a concurrent move of the branch fails
-// the update instead of being overwritten (DEC-050). Verification follows on the integrated HEAD
-// (IC-019), then B.3's end rule finishes or releases the 080 attempt inside the dispatch lock.
+// the update instead of being overwritten (DEC-050). The new commit is recorded as the lease's
+// `pickedHead` before `update-ref` runs (RT-10), so a stop between the two is recoverable (IC-032). Verification follows on the integrated HEAD
+// (IC-019), then B.3's end rule finishes or releases the 080 attempt inside the dispatch lock, once
+// the integration worktree is found on its branch, at this integration's head and clean again.
 // Undo is `reset --hard` to the pre-integration head, run only while the integration branch is
 // checked out there and points at a head this integration made (IC-020).
 //
@@ -310,7 +312,7 @@ function endStale(store     , dispatch     , reason        , ctx     , now
  * `ctx` is B.3's 080 context (`ledgerFile`, `roots`, `slug`, `env`, `cwd`, `fsImpl`, `now`); `env`
  * is the environment git and the verification inherit, less the repository variables. `holder` is
  * the lease holder `{ pid, start }` (this process by default). `beforeUpdateRef` is a test seam
- * called between `commit-tree` and `update-ref`, and `afterLease` one called between steps 1 and 2;
+ * called after the lease records the commit and before `update-ref`, and `afterLease` one called between steps 1 and 2;
  * the loop passes neither.
  *
  * Resolves `{ outcome, dispatchId, task, token, ... }`, `outcome` one of `none`, `not-running`,
@@ -446,15 +448,19 @@ async function integrateOnce({
         const made = runGit(integration.worktree, ['commit-tree', tree.stdout.trim(), '-p', preHead, '-m', `${task}: dispatch ${dispatchId} token ${token}`], { env: identityEnv, timeout: WRITE_TIMEOUT_MS });
         const commit = made.stdout.trim();
         if (!made.ok || !SHA.test(commit)) return releaseWithError('commit-tree-failed', made.status, null);
+        // RT-10: the commit is recorded in this dispatch's lease BEFORE the ref moves, so a stop between
+        // the two leaves a head the lease rule (IC-032) knows as this integration's. Not recorded (the lease
+        // is no longer this dispatch's), no ref move.
+        const recorded = mutateDispatch(file, (store     ) => {
+          if (!store.lease || store.lease.dispatchId !== dispatchId) return { write: false, result: false };
+          store.lease.pickedHead = commit;
+          return { write: true, result: true };
+        });
+        if (!recorded) return releaseWithError('picked-head-unrecorded', null, null);
         if (beforeUpdateRef) await beforeUpdateRef({ worktree: integration.worktree, branch: integration.branch, preHead, commit });
         const moved = runGit(integration.worktree, ['update-ref', `refs/heads/${integration.branch}`, commit, preHead], { env: identityEnv, timeout: WRITE_TIMEOUT_MS });
         if (!moved.ok) return releaseWithError('update-ref-failed', moved.status, null);
         pickedHead = commit;
-        mutateDispatch(file, (store     ) => {
-          if (!store.lease || store.lease.dispatchId !== dispatchId) return { write: false, result: null };
-          store.lease.pickedHead = commit;
-          return { write: true, result: null };
-        });
       }
     }
 
@@ -487,6 +493,19 @@ async function integrateOnce({
       }, record);
     }
 
+    // A passing verification must also have left the integration worktree as it found it: on its branch,
+    // at this integration's head, listing nothing. Anything else is not this integration's to reset, so
+    // nothing is undone and the work stays for recovery; the run blocks instead of completing.
+    const post = integrationClean({ ...where, preHead: pickedHead ?? preHead });
+    if (!post.clean) {
+      return settle((store, d) => {
+        record(store);
+        retryLater(store, d);
+        blockRun(store, { task, kind: 'integration-dirty', reason: `after-verification:${post.reason}`, paths: post.paths });
+        return { ...base, outcome: 'integration-dirty', reason: `after-verification:${post.reason}`, paths: post.paths, verification };
+      }, record);
+    }
+
     const after = readLedger(ctx);
     const finished = mutateDispatch(file, (store     ) => {
       const d = store.dispatches[dispatchId];

package/src/runtime/dispatch/loop.js

@@ -951,6 +951,13 @@ async function launchChildren(p     ) {
     const started = Date.now();
     const granter = current.dispatches[req.granterDispatchId];
     const who = { dispatchId: req.granterDispatchId, task: granter ? granter.task : null, token: granter ? granter.token : null };
+    // RR-7: a launch whose record write was refused keeps its worktree and child run on the request
+    // (RR-5); launching it again would reuse the tree and overwrite that child run id.
+    if (req.childRunId != null) {
+      refuse(req.requestId, 'child-run-recorded');
+      p.act('launch-child', who, 'refused', `${req.requestId} child-run-recorded`, Date.now() - started);
+      continue;
+    }
     if (!granter || granter.phase !== 'launched' || !granter.workerRunId) {
       refuse(req.requestId, 'granter-not-running');
       p.act('launch-child', who, 'refused', `${req.requestId} granter-not-running`, Date.now() - started);

package/src/runtime/dispatch/verify-run.js

@@ -24,9 +24,15 @@ const processTree = require('../worker/process-tree.js');
 const { EvidenceLedger } = require('../evidence-ledger.js');
 const { emitVerifyTelemetry } = require('../verification/telemetry-emit.js');
 
-/** The same names as 081's `REPO_ENV` (`src/runtime/worker/worktree-check.js:30`), which that
- * module does not export: inherited variables that would point git at another repository. */
-const REPO_ENV = Object.freeze(['GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_COMMON_DIR', 'GIT_OBJECT_DIRECTORY']);
+/** The repository-local variables of `git rev-parse --local-env-vars` (git 2.50): inherited, they would point git at
+ * another repository. Hardcoded so no git process is spawned to compute it. Fetch (`packages/fetch.ts`) strips these
+ * and also `GIT_ALLOW_PROTOCOL`; the integration step and the review checks inherit this list. `GIT_CONFIG*` is left
+ * out on purpose: CI injects authentication through it. */
+const REPO_ENV = Object.freeze([
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES', 'GIT_OBJECT_DIRECTORY', 'GIT_DIR', 'GIT_WORK_TREE', 'GIT_IMPLICIT_WORK_TREE',
+  'GIT_GRAFT_FILE', 'GIT_INDEX_FILE', 'GIT_NO_REPLACE_OBJECTS', 'GIT_REPLACE_REF_BASE', 'GIT_PREFIX',
+  'GIT_SHALLOW_FILE', 'GIT_COMMON_DIR',
+]);
 /** How long the streams may stay open after the leader's exit (a grandchild may hold them). */
 const DRAIN_MS = 500;
 /** Bound on the `git rev-parse HEAD` read of the verified head. */

package/src/runtime/feature-pointer.js

@@ -24,6 +24,8 @@ const { resolveActiveFeature } = require('./feature-resolve.js');
 const SCHEMA = 1;
 const POINTER_DIR = path.join('.doflow', 'state', 'feature');
 const POINTER_NAME = /^[0-9a-f]{16}\.json$/;
+/** The single-file pointer written before row 135 (one per store, not per checkout). It is never migrated or deleted. */
+const LEGACY_FILE = path.join('.doflow', 'state', 'feature.json');
 
                                                                                                                                                                       
 
@@ -145,7 +147,14 @@ function describeActive({ storeRoot, cwd }                                    )
   const file = pointerFile(storeRoot, here.key);
   const read = readEntry(file);
   if (read.status === 'unreadable') return { ...base, state: 'unreadable', reason: read.reason, file: path.relative(storeRoot, file) };
-  if (read.status === 'none') return { ...base, state: 'none' };
+  if (read.status === 'none') {
+    // A pre-135 feature.json is not read as an answer, but it is not silence either: say it is there and how to retire it.
+    const legacy = path.join(storeRoot, LEGACY_FILE);
+    if (fs.existsSync(legacy)) {
+      return { ...base, state: 'unreadable', file: LEGACY_FILE, reason: 'a pre-row-135 single-file pointer that is not migrated to the per-checkout pointer' };
+    }
+    return { ...base, state: 'none' };
+  }
   const entry = read.data ;
   const mismatch = entry.branch !== current.branch || (derived !== null && derived !== entry.slug);
   if (mismatch) return { ...base, state: 'mismatch', pointer: entry };

package/src/runtime/health.js

@@ -31,6 +31,9 @@ const { readGrants, detectedProjectRoot } = require('./packages/grants.js');
 const { readState, grantRevoked } = require('./packages/state.js');
 const { transcriptsDoctorView } = require('./transcripts/registry.js');
 const { readLedger, stateRoot } = require('../state/index.js');
+const { readRegularFileText } = require('./task-scope.js');
+const { migrationPending } = require('./lifecycle/store-upkeep.js');
+const { isRunNamespaceDir, isSupersededFlatRun } = require('./storage/work-status.js');
 
 /** Answered a probe. */
 const HEALTHY = 'HEALTHY';
@@ -612,22 +615,21 @@ function mcpConsultationsView({ projectRoot, fsImpl }     ) {
   const listed                                                                    = [];
   const readRunFile = (rel        , name        , namespace        )       => {
     let run;
-    try { run = JSON.parse(fsImpl.readFileSync(path.join(dir, rel), 'utf8')); } catch { run = null; }
+    try { run = JSON.parse(readRegularFileText(path.join(dir, rel), fsImpl) ?? 'null'); } catch { run = null; }
     listed.push({ rel, name, namespace, run });
   };
   let entries        = [];
   try { entries = fsImpl.readdirSync(dir, { withFileTypes: true }); } catch { entries = []; }
   for (const entry of entries) if (entry.name.endsWith('.json') && !entry.isDirectory()) readRunFile(entry.name, entry.name, '');
   for (const entry of entries) {
-    if (!entry.isDirectory() || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(entry.name) || entry.name.endsWith('.lock')) continue;
+    if (!entry.isDirectory() || !isRunNamespaceDir(entry.name)) continue;
     let inner        = [];
     try { inner = fsImpl.readdirSync(path.join(dir, entry.name), { withFileTypes: true }); } catch { inner = []; }
     for (const file of inner) if (file.name.endsWith('.json') && !file.isDirectory()) readRunFile(`${entry.name}/${file.name}`, file.name, entry.name);
   }
   listed.sort((a, b) => byText(a.rel, b.rel));
   // A flat run whose namespaced copy exists is that copy's seed, not a second run.
-  const files = listed.filter((one) => one.namespace !== '' || !listed.some((other) => other.namespace !== '' && other.name === one.name
-    && (typeof one.run?.featureSlug !== 'string' || one.run.featureSlug === other.namespace)));
+  const files = listed.filter((one) => one.namespace !== '' || !isSupersededFlatRun(one.name, one.run, listed.filter((other) => other.namespace !== '')));
   let unreadableRuns = 0;
   const bySkill = new Map();
   for (const { name, run } of files) {
@@ -935,6 +937,9 @@ function buildHealthReport({ repoRoot, projectRoot = process.cwd(), router, exec
   const warnings = [
     ...(nodeWarning ? [nodeWarning] : []),
     ...claudePermissionWarnings({ repoRoot: root, projectRoot, homeDir: home, fsImpl }),
+    ...(migrationPending(path.resolve(projectRoot), { fsImpl })
+      ? [{ kind: 'lifecycle-migration-pending', subject: 'lifecycle store', detail: 'the lifecycle store has not been copied yet from agent-docs/lifecycle; run any followup, lifecycle or goal command once without DOFLOW_UPKEEP=off. doctor wrote nothing.' }]
+      : []),
     ...freshness
       .filter((item) => item.state === 'STALE')
       .map((item) => ({ kind: 'index-stale', subject: item.providerId, detail: `${item.label} is behind the working tree; refresh with: ${item.refresh}` })),

package/src/runtime/implementation-gate.js

@@ -401,15 +401,22 @@ function findNamespacedRun({ stateRoot, taskId, exec }     ) {
   const name = `${taskId}.json`;
   const missing = { status: 'missing', file: null, root: null, origin: null, candidates: [] };
   const inRoot = (root        ) => runFilesAt(root).filter((entry) => entry.namespace !== null && path.basename(entry.file) === name);
+  // A flat run in another checkout that names no feature is any feature's, so `list` shows it and
+  // `status` opens it; read through the same safe read as every other run (a link, FIFO or device
+  // is never opened, and is not a match).
+  const flatInRoot = (root        ) => runFilesAt(root).filter((entry) => {
+    if (entry.namespace !== null || path.basename(entry.file) !== name) return false;
+    try { return namesNoFeature(JSON.parse(readRunText(fs, entry.file, runStoreDir(root))          )); } catch { return false; }
+  });
   const settle = (entries                                                 , root        , origin                   ) => (
     entries.length === 1
-      ? { status: 'found', file: entries[0].file, root, origin, candidates: [], slug: entries[0].namespace           }
+      ? { status: 'found', file: entries[0].file, root, origin, candidates: [], ...(entries[0].namespace !== null ? { slug: entries[0].namespace } : {}) }
       : { ...missing, status: 'ambiguous', byFeature: true, candidates: entries.map((entry) => entry.file) });
   const here = inRoot(stateRoot);
   if (here.length > 0) return settle(here, stateRoot, 'current');
   const checkouts = listCheckouts({ cwd: stateRoot, ...(exec ? { exec } : {}) });
   if (!checkouts.ok || checkouts.sandbox) return missing;
-  const matches = checkouts.others.flatMap((root        ) => inRoot(root).map((entry) => ({ ...entry, root })));
+  const matches = checkouts.others.flatMap((root        ) => [...inRoot(root), ...flatInRoot(root)].map((entry) => ({ ...entry, root })));
   if (matches.length === 0) return missing;
   return settle(matches, matches[0].root, 'other');
 }
@@ -568,6 +575,7 @@ module.exports = {
   featureSlugFor,
   runSlugOf,
   orchestrationRuns,
+  runEntriesAt,
   selectRunEntries,
   findRunFile,
   RUN_STORE_REL,

package/src/runtime/intake/engine.js

@@ -210,10 +210,12 @@ function directClaim(categories       , name        )      {
 
 /**
  * Plans a sort of the loose files (IC-002). Pure with respect to the folder: it reads, hashes and decides, and
- * writes nothing. A companion rule sends a file beside a same-stem file that is itself moving in this plan, or
+ * writes nothing. The manifest is read, and so validated, once before anything is planned (a caller that already
+ * holds a snapshot passes it as `manifest`), so a malformed manifest or a linked `.intake` fails the same way
+ * whether or not a loose render has a partner. A companion rule sends a file beside a same-stem file that is itself moving in this plan, or
  * that already sits in the category folder or is recorded `done` in the manifest.
  */
-function planSort({ contextDir, taxonomy, now, fsImpl = nodeFs, withHashes = true }     )      {
+function planSort({ contextDir, taxonomy, now, fsImpl = nodeFs, withHashes = true, manifest = readManifest(contextDir, fsImpl) }     )      {
   const { files, dirs, unsupported } = rootEntries(contextDir, fsImpl);
   const windowMs = taxonomy.recentWindowSeconds * 1000;
   const recent = new Set        ();
@@ -236,7 +238,7 @@ function planSort({ contextDir, taxonomy, now, fsImpl = nodeFs, withHashes = tru
 
   // A partner that no longer is loose: already in the category folder, or recorded `done` by an earlier run. This
   // settles a render stranded by a crash or by a recent-window skip while its source moved.
-  let doneMoves               = null;
+  const doneMoves        = manifest.runs.flatMap((run     ) => run.moves.filter((move     ) => move.state === 'done'));
   const settledPartnerPlace = (category     , rule     , name        )                                             => {
     const stem = stemOf(name);
     for (const sourceRule of category.rules) {
@@ -251,8 +253,7 @@ function planSort({ contextDir, taxonomy, now, fsImpl = nodeFs, withHashes = tru
         if (!isUnreadable(error)) throw error; // a folder this user may not read holds no partner we can see: the render stays loose
       }
       if (inFolder) return place;
-      const done        = doneMoves ??= readManifest(contextDir, fsImpl).runs.flatMap((run     ) => run.moves.filter((move     ) => move.state === 'done'));
-      if (done.some((move     ) => path.posix.dirname(move.to) === place.dir && isPartner(path.posix.basename(move.to)))) return place;
+      if (doneMoves.some((move     ) => path.posix.dirname(move.to) === place.dir && isPartner(path.posix.basename(move.to)))) return place;
     }
     return null;
   };
@@ -376,7 +377,7 @@ const hasPlanned = (manifest     )          => manifest.runs.some((run     ) =>
 const absent = (action        , extra      = {})      => ({ action, state: 'absent', ...extra });
 const absentSort = (action        )      => absent(action, { runId: null, moves: [], skipped: [], unmatched: [], createdDirs: [] });
 
-/** IC-002 preview: the plan, with `runId: null`; no lock, no manifest, no write. */
+/** IC-002 preview: the plan, with `runId: null`; reads the manifest once, takes no lock and writes nothing. */
 function previewSort({ contextDir, taxonomy, now = new Date(), fsImpl = nodeFs }     )      {
   if (contextState(contextDir, fsImpl) === 'absent') return absentSort('preview');
   return { action: 'preview', state: 'sorted', runId: null, ...planSort({ contextDir, taxonomy, now, fsImpl }) };
@@ -387,13 +388,14 @@ function sortFolder({ contextDir, taxonomy, now = new Date(), fsImpl = nodeFs }
   if (contextState(contextDir, fsImpl) === 'absent') return absentSort('sort');
   const empty = (plan     )      => ({ action: 'sort', state: 'sorted', runId: null, moves: [], skipped: plan.skipped, unmatched: plan.unmatched, createdDirs: [] });
   // Nothing to move and nothing to settle: report without a lock or a single write.
-  const first = planSort({ contextDir, taxonomy, now, fsImpl, withHashes: false });
-  if (first.moves.length === 0 && !hasPlanned(readManifest(contextDir, fsImpl))) return empty(first);
+  const snapshot = readManifest(contextDir, fsImpl);
+  const first = planSort({ contextDir, taxonomy, now, fsImpl, withHashes: false, manifest: snapshot });
+  if (first.moves.length === 0 && !hasPlanned(snapshot)) return empty(first);
 
   return withManifestLock(contextDir, (assertHeld            ) => {
     const manifest = readManifest(contextDir, fsImpl);
     if (reconcile(manifest, contextDir, now, fsImpl, assertHeld)) writeManifest(contextDir, manifest, fsImpl, assertHeld);
-    const plan = planSort({ contextDir, taxonomy, now, fsImpl });
+    const plan = planSort({ contextDir, taxonomy, now, fsImpl, manifest });
     if (plan.moves.length === 0) return empty(plan);
 
     const run      = { id: newRunId(now), action: 'sort', startedAt: now.toISOString(), finishedAt: null, source: null, stage: null, createdDirs: [], moves: [] };

package/src/runtime/knowledge/code-retrieval.js

@@ -45,12 +45,14 @@ function lexicalOutcome(result     ) {
 
 function validFreshness(value     ) { return INDEX_STATES.has(value) ? value : 'UNKNOWN'; }
 
-function appendOutcome({ binding, projectRoot, taskId, slug, intent, need, router, provider, capability, id, candidates, indexState, failure, bound = null, complete }     ) {
+function appendOutcome({ binding, projectRoot, taskId, slug, intent, need, router, provider, capability, id, candidates, indexState, failure, bound = null, complete, answered = complete }     ) {
+  // `answered`: the provider finished its own search. `complete` additionally needs a complete corpus. An
+  // empty answer is classified on `answered`, so an incomplete corpus never turns it into a timeout.
   let stored = null;
   if (binding) {
     let status; let reason;
     if (failure) { status = 'UNREACHED'; reason = failureReason(failure, indexState); }
-    else if (!candidates.length && complete) {
+    else if (!candidates.length && answered) {
       if (indexState === 'STALE') { status = 'EMPTY'; reason = 'index-stale'; }
       else if (indexState === 'UNKNOWN') { status = 'UNVERIFIED'; reason = 'index-unverifiable'; }
       else { status = 'EMPTY'; reason = 'empty-answer'; }
@@ -233,10 +235,14 @@ async function executeCodeRetrieval(options      = {}) {
     rankedLists.push({ provider: 'native.rg', capability, queryRef, retrievalAttemptRef: lexicalId, candidates: lexCandidates });
     const lexOutcome = lexicalOutcome(lexResult);
     attempts.push(appendOutcome({ binding, projectRoot, taskId, slug, intent, need, router, provider: 'native.rg', capability,
-      id: lexicalId, candidates: lexCandidates, indexState: 'NOT_APPLICABLE', ...lexOutcome, complete: Boolean(lexResult.complete && inventory.complete) }));
+      id: lexicalId, candidates: lexCandidates, indexState: 'NOT_APPLICABLE', ...lexOutcome, complete: Boolean(lexResult.complete && inventory.complete), answered: Boolean(lexResult.complete) }));
     if (lexOutcome.failure || lexOutcome.bound) gaps.push({ provider: 'native.rg', reason: lexOutcome.failure || lexOutcome.bound, source: 'lexical' });
 
-    if (profile === 'hybrid' && classification.queryClass === 'conceptual') {
+    // Semantic search needs a complete corpus (index build and refresh refuse one too): an incomplete inventory skips
+    // it as a coverage gap, never as a provider attempt or failure. The admission gaps above already say why.
+    if (profile === 'hybrid' && classification.queryClass === 'conceptual' && !inventory.complete) {
+      gaps.push({ source: 'semantic', reason: 'incomplete-corpus-skipped' });
+    } else if (profile === 'hybrid' && classification.queryClass === 'conceptual') {
       const semanticId = makeId();
       let semResult;
       const modelPath = options.modelPath || process.env.SEMBLE_MODEL_PATH || null;
@@ -269,7 +275,7 @@ async function executeCodeRetrieval(options      = {}) {
         rankedLists.push({ provider: 'native.rg', capability, queryRef, retrievalAttemptRef: fallbackId, candidates: fallbackCandidates });
         const fallbackOutcome = lexicalOutcome(fallback);
         attempts.push(appendOutcome({ binding, projectRoot, taskId, slug, intent, need, router, provider: 'native.rg', capability,
-          id: fallbackId, candidates: fallbackCandidates, indexState: 'NOT_APPLICABLE', ...fallbackOutcome, complete: Boolean(fallback.complete && inventory.complete) }));
+          id: fallbackId, candidates: fallbackCandidates, indexState: 'NOT_APPLICABLE', ...fallbackOutcome, complete: Boolean(fallback.complete && inventory.complete), answered: Boolean(fallback.complete) }));
         if (fallbackOutcome.failure || fallbackOutcome.bound) gaps.push({ provider: 'native.rg', reason: fallbackOutcome.failure || fallbackOutcome.bound, source: 'fallback' });
       }
     }

package/src/runtime/knowledge/semble-provider.js

@@ -234,6 +234,9 @@ function inspectArtifacts(index        , inventory     , paths     , model     ,
 // rule: process.kill(pid, 0)) is reclaimed under a claim file named for its token, created `wx`: the claim winner re-reads
 // the lock and removes it only while it still carries the judged token, so a live or newer lock is never removed. A lock
 // from another host, from this process, or without a readable record is never reclaimed.
+// The Python bridge child is what writes the cache, so executeBridge records its pid in the lock as `childPid`; a lock
+// is stale only when the owner and that child are both gone. Ceiling: a Node process killed between spawn and the
+// record leaves a lock without `childPid` (the child is then unprotected for that instant).
 // Ceiling: a reclaimer killed between creating and removing its claim leaves `operation.lock.claim.<token>`, and that
 // lock then waits for a manual removal, which the contention cause names.
 const LOCK_TOKEN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
@@ -243,6 +246,12 @@ function readLockOwner(lock        )      {
     return owner && Number.isInteger(owner.pid) && typeof owner.hostname === 'string' && LOCK_TOKEN.test(owner.token) ? owner : null;
   } catch { return null; }
 }
+function recordLockChild(lock        , childPid        )       {
+  const owner = readLockOwner(lock); if (!owner || owner.pid !== process.pid || !Number.isInteger(childPid)) return;
+  const next = `${lock}.child.${process.pid}`;
+  try { fs.writeFileSync(next, `${JSON.stringify({ ...owner, childPid })}\n`, { flag: 'w', mode: 0o600 }); fs.renameSync(next, lock); }
+  catch { try { fs.unlinkSync(next); } catch {} }
+}
 function reclaimStaleLock(lock        , owner     , hostname        )          {
   const claim = `${lock}.claim.${owner.token}`;
   try { fs.writeFileSync(claim, `${JSON.stringify({ pid: process.pid, hostname })}\n`, { flag: 'wx', mode: 0o600 }); }
@@ -262,7 +271,7 @@ async function acquireSemanticLock(paths     , { isAlive = defaultIsAlive, hostn
       return () => { fs.closeSync(fd); if (readLockOwner(paths.lock)?.token === token) fs.unlinkSync(paths.lock); };
     } catch (error     ) { if (error.code !== 'EEXIST') throw error; }
     const owner = readLockOwner(paths.lock);
-    if (owner && owner.hostname === hostname && owner.pid !== process.pid && !isAlive(owner.pid) && reclaimStaleLock(paths.lock, owner, hostname)) continue;
+    if (owner && owner.hostname === hostname && owner.pid !== process.pid && !isAlive(owner.pid) && !(Number.isInteger(owner.childPid) && isAlive(owner.childPid)) && reclaimStaleLock(paths.lock, owner, hostname)) continue;
     if (Date.now() >= deadline) {
       throw fault('lock-contention', 'UNKNOWN', `another semantic index operation holds ${paths.lock}${owner ? ` (pid ${owner.pid} on ${owner.hostname})` : ''}; `
         + 'run the command again when it finishes. A lock whose process has exited on this host is reclaimed automatically; '
@@ -300,6 +309,7 @@ function executeBridge(request     , options     , paths     , sandbox        )
       TRANSFORMERS_CACHE: library, XDG_CACHE_HOME: library, SEMBLE_GRAMMARS_CACHE_DIR: path.join(library, 'grammars'), TORCH_HOME: library,
       TMPDIR: library, TEMP: library, TMP: library, TOKENIZERS_PARALLELISM: 'false', SEMBLE_INDEX_WORKERS: '0' };
     const child = spawn(options.python, [options.bridgePath || path.join(__dirname, 'semble-bridge.py')], { cwd: paths.state, env, stdio: ['pipe', 'pipe', 'pipe'], shell: false });
+    if (child.pid) recordLockChild(paths.lock, child.pid);
     let stdout = ''; let outputBytes = 0; let failure                = null; let done = false;
     const stop = (reason        ) => { if (!failure) failure = reason; child.kill('SIGKILL'); };
     const timer = setTimeout(() => stop('provider-timeout'), deadline);
@@ -362,4 +372,4 @@ async function runSembleQuery(options     )               {
   finally { try { if (temp) fs.rmSync(temp, { recursive: true, force: true }); } catch {} try { if (release) release(); } catch {} }
 }
 module.exports = { SEMBLE_VERSION, SEMBLE_LIMITS, runSembleQuery, resolveSembleInterpreter, checkSembleVersion, semanticStatePaths, digest, fault, inside, safeDirectories,
-  regularBytes, scanTree, inspectModel, inspectBm25, validateInventory, readSource, checkSources, inspectArtifacts, acquireSemanticLock, cleanupTemporary, executeBridge, readCompleted, modelLinkRoots };
+  regularBytes, scanTree, inspectModel, inspectBm25, validateInventory, readSource, checkSources, inspectArtifacts, acquireSemanticLock, recordLockChild, cleanupTemporary, executeBridge, readCompleted, modelLinkRoots };

package/src/runtime/lifecycle/cli.js

@@ -15,7 +15,7 @@ const followup = require('./followup.js');
 const { StoreUnsafeError, StoreLockedError } = require('./event-store.js');
 const { prepareStore } = require('./store-upkeep.js');
 const { printSafe } = require('../mask.js');
-const { buildOverview, initFeature, featureStatus, activeFeature } = require('./overview.js');
+const { buildOverview, capOverviewBrief, initFeature, featureStatus, activeFeature } = require('./overview.js');
 const { recordFeature, clearSlug } = require('../feature-pointer.js');
 const { releaseFeatures, recordMerged } = require('./release.js');
 const goal = require('./goal.js');
@@ -44,7 +44,7 @@ const OVERVIEW_BRIEF = Object.freeze({
     '$.followups.items[].id', '$.followups.items[].statement', '$.followups.items[].source', '$.followups.items[].pending',
     '$.intents', '$.goals[].goal', '$.goals[].outcome', '$.goals[].items', '$.goals[].proposeDone', '$.goals[].nudges',
     '$.goals[].conflicts', '$.conflicts', '$.unreadable', '$.unreadableReasons', '$.failures', '$.reason', '$.note',
-    '$.integrationBehind', '$.pending', '$.next',
+    '$.integrationBehind', '$.pending', '$.omitted', '$.next',
   ]),
 });
 /** A brief list answers one page of this many items unless `--limit` says otherwise. */
@@ -195,7 +195,7 @@ function emitList(result     , view     , flags     , json     ) {
   const paged = result.shown !== undefined;
   const carried = { state: flags.state, ids: flags.ids, limit: flags.limit };
   const lines = !paged ? [] : [
-    ...viewLines('page', { spec: FOLLOWUP_LIST_BRIEF, carried, nextCursor: result.nextCursor, view }),
+    ...viewLines('page', { spec: FOLLOWUP_LIST_BRIEF, carried, nextCursor: result.nextCursor, view, json: Boolean(json) }),
     ...(view === 'brief' ? viewLines('page-full', { spec: FOLLOWUP_LIST_BRIEF, carried, cursor: flags.cursor, shown: result.shown, json: Boolean(json) }) : []),
   ];
   if (!json) return emit({ ...result, next: result.shown < result.count ? lines : [] }, false, followupLines);
@@ -301,8 +301,10 @@ function handleLifecycleCommand({ action, cwd, global = false, slug = null, json
       // keeps its 50: that loop settles every pending item. The next lines name the paged list and carry no full-view line.
       if (view === 'brief' && json) {
         const items = flags.maintain ? result.followups.items : result.followups.items.slice(0, BRIEF_PAGE);
-        const brief = { ...result, followups: { ...result.followups, shown: items.length, items } };
-        return emit(withEnvelope(projectBrief(brief, OVERVIEW_BRIEF.keep), { view }), true, lifecycleLines);
+        const brief      = capOverviewBrief({ ...result, followups: { ...result.followups, shown: items.length, items } });
+        // Something cut from a list: the next lines also say how to get everything.
+        const next = brief.omitted ? [...result.next, ...viewLines('full', { spec: OVERVIEW_BRIEF, carried: { maintain: flags.maintain, since: flags.since }, json: true })] : undefined;
+        return emit(withEnvelope(projectBrief(brief, OVERVIEW_BRIEF.keep), { view, ...(next ? { next } : {}) }), true, lifecycleLines);
       }
     } else if (act === 'init') {
       result = initFeature({ root, slug, take: flags.take, intent: flags.intent, goal: flags.goal });

package/src/runtime/lifecycle/overview.js

@@ -28,6 +28,8 @@ const DISCOVERY_SHOWN = 15;
 const MAINTAIN_SHOWN = 50;
 /** Slugs shown per finished or awaiting-release bucket: those lists only grow, and the overview runs on every brainstorm. */
 const FEATURES_SHOWN = 10;
+/** Entries per list in the JSON brief overview: intents, the ids of one intent, the nudges of one goal (137 FU-2jtkch). */
+const BRIEF_LIST_SHOWN = 10;
 
 const refusal = (action     , finding     , message     ) => ({ ok: false, action, finding, message });
 
@@ -116,7 +118,10 @@ function goalView(goal     , features     , statuses     , conflicts      = [])
   const met = goal.items.filter((i     ) => i.met).length;
   const nudges = [];
   if (buckets.finished.length) {
-    const who = buckets.finished.length === 1 ? `linked feature ${buckets.finished[0]} is finished` : `linked features ${buckets.finished.join(', ')} are finished`;
+    // The nudge names the most recent finished features only; `features.finished` still lists every one.
+    const finished = shownBucket(buckets.finished);
+    const who = buckets.finished.length === 1 ? `linked feature ${buckets.finished[0]} is finished`
+      : `linked features ${finished.shown.join(', ')}${finished.more ? ` (+${finished.more} more)` : ''} are finished`;
     for (const item of goal.items.filter((i     ) => !i.met)) nudges.push(`${item.id} is unchecked and ${who}`);
   }
   return {
@@ -160,6 +165,31 @@ function nextLines({ shown, open, items, intents, goals, maintain, pendingItems,
   return next;
 }
 
+/**
+ * The JSON brief form of an overview answer: at most BRIEF_LIST_SHOWN intents, ids per intent and nudges per goal. What
+ * was cut is counted in `omitted` (absent when nothing was cut): `intents`, and `intentItems`, `nudges` and
+ * `finished` (the finished features a goal's nudges leave out of their text) per intent or goal that exceeds the
+ * bound. The full view lists everything.
+ */
+function capOverviewBrief(result     ) {
+  const omitted      = {};
+  const intents = result.intents.slice(0, BRIEF_LIST_SHOWN).map((intent     ) => {
+    if (intent.items.length > BRIEF_LIST_SHOWN) {
+      (omitted.intentItems ??= []).push({ path: intent.path, total: intent.items.length, more: intent.items.length - BRIEF_LIST_SHOWN });
+    }
+    return { ...intent, items: intent.items.slice(0, BRIEF_LIST_SHOWN) };
+  });
+  if (result.intents.length > BRIEF_LIST_SHOWN) omitted.intents = { total: result.intents.length, more: result.intents.length - BRIEF_LIST_SHOWN };
+  const goals = result.goals.map((goal     ) => {
+    const finished = goal.features.finished.length;
+    if (finished > FEATURES_SHOWN) (omitted.finished ??= []).push({ goal: goal.goal, total: finished, more: finished - FEATURES_SHOWN });
+    if (goal.nudges.length <= BRIEF_LIST_SHOWN) return goal;
+    (omitted.nudges ??= []).push({ goal: goal.goal, total: goal.nudges.length, more: goal.nudges.length - BRIEF_LIST_SHOWN });
+    return { ...goal, nudges: goal.nudges.slice(0, BRIEF_LIST_SHOWN) };
+  });
+  return { ...result, intents, goals, ...(Object.keys(omitted).length ? { omitted } : {}) };
+}
+
 /**
  * IC-007.
  * @param {Object} options
@@ -313,4 +343,4 @@ function activeFeature({ root, cwd, now = new Date(), fsImpl = nodeFs }     ) {
   return derived.ok ? { ...derived, active } : { ...result, slug: active.slug, message: `${active.slug} is tracked by its run only; \`lifecycle --action init\` to track it.` };
 }
 
-module.exports = { buildOverview, initFeature, featureStatus, activeFeature, goalView, goalConflicts, goalConflictNext, DISCOVERY_SHOWN, MAINTAIN_SHOWN, FEATURES_SHOWN };
+module.exports = { buildOverview, capOverviewBrief, initFeature, featureStatus, activeFeature, goalView, goalConflicts, goalConflictNext, DISCOVERY_SHOWN, MAINTAIN_SHOWN, FEATURES_SHOWN };