@khoavu882/doflow 2.0.0-beta.5 → 2.0.1

package/src/runtime/lifecycle/followup.js

@@ -22,6 +22,7 @@ const { STAGES: CHAIN_STAGES } = require('../decision-register.js');
 const { isSafeSlug, invalidSlugRefusal } = require('../task-scope.js');
 const { resolveActiveFeature } = require('../feature-resolve.js');
 const { SETTLE_AS, withDerivedDone } = require('./fold.js');
+const { pageItems } = require('../verb-view.js');
 const { appendEvents, readFold, byFromChannel, randomChars } = require('./event-store.js');
 const { deriveStatuses } = require('./status.js');
 const { writeIntent, kebabTitle } = require('./intent-writer.js');
@@ -73,7 +74,7 @@ function newFollowupId(taken     ) {
 
 function channelBy(channel     ) {
   const by = byFromChannel(channel || 'default');
-  if (!by) throw new FollowupUsageError(`unknown --channel '${channel}'. Valid: question, gate, prompt, default`);
+  if (!by) throw new FollowupUsageError(`unknown --channel '${channel}'. Valid: question, gate, prompt, resolution, default`);
   return by;
 }
 
@@ -334,12 +335,37 @@ function reportFollowup({ root, statement, input, release, feature, channel, now
 
 // ── list ───────────────────────────────────────────────────────────────────────────────────────
 
-/** IC-006 `list`: `state` is open (default), taken, done, dismissed or all. */
-function listFollowups({ root, state = 'open', hasBody, fsImpl = nodeFs, statuses, now = new Date() }     ) {
-  if (state !== 'all' && !STATES.includes(state)) throw new FollowupUsageError(`--state must be one of ${[...STATES, 'all'].join(', ')} (got '${state}')`);
+/** The most items one list answer holds, however large a `--limit` asks for (IC-004). */
+const LIST_MAX_LIMIT = 100;
+
+/** The key the fold orders on and a list cursor names: the creating event's time in ms, then its event id (IC-008). */
+function followupOrderKey(item     ) {
+  const created = item.history[0];
+  return { atMs: Date.parse(created.at), event: created.event };
+}
+
+/**
+ * IC-006 `list`: `state` is open (default), taken, done, dismissed or all. `ids` keeps the named items (and, with no
+ * `state`, looks in every state); an id that is no item at all is the `unknown-id` refusal. With `cursor`, `limit` or
+ * `defaultLimit` the answer holds one page of `items` plus `shown` and `nextCursor`; with none it is the whole list.
+ */
+function listFollowups({ root, state, ids, cursor, limit, defaultLimit = null, hasBody, fsImpl = nodeFs, statuses, now = new Date() }     ) {
+  const wanted = ids === undefined ? null : parseIds(ids);
+  const wantedState = state === undefined ? (wanted ? 'all' : 'open') : state;
+  if (wantedState !== 'all' && !STATES.includes(wantedState)) throw new FollowupUsageError(`--state must be one of ${[...STATES, 'all'].join(', ')} (got '${wantedState}')`);
   const { fold, followups } = loadFollowups(root, { hasBody, fsImpl, statuses, now });
-  const items = state === 'all' ? followups : followups.filter((item     ) => item.state === state);
-  return { ok: true, action: 'list', state, count: items.length, items, conflicts: fold.conflicts, unreadable: fold.unreadable, unreadableReasons: fold.unreadableReasons, next: [] };
+  let matched = followups;
+  if (wanted) {
+    const known = new Set(followups.map((item     ) => item.id));
+    const unknown = wanted.filter((id) => !known.has(id));
+    if (unknown.length) return refusal('list', 'unknown-id', `${unknown.join(', ')} ${unknown.length === 1 ? 'is' : 'are'} not a follow-up in this store. Nothing was listed.`);
+    matched = followups.filter((item     ) => wanted.includes(item.id));
+  }
+  if (wantedState !== 'all') matched = matched.filter((item     ) => item.state === wantedState);
+  const answer      = { ok: true, action: 'list', state: wantedState, count: matched.length, items: matched, conflicts: fold.conflicts, unreadable: fold.unreadable, unreadableReasons: fold.unreadableReasons, next: [] };
+  if (cursor === undefined && limit === undefined && defaultLimit === null) return answer;
+  const page = pageItems(matched, { cursor, limit, defaultLimit, maxLimit: LIST_MAX_LIMIT, key: followupOrderKey });
+  return { ...answer, items: page.items, shown: page.shown, nextCursor: page.nextCursor };
 }
 
 // ── take, settle, promote ──────────────────────────────────────────────────────────────────────
@@ -350,6 +376,11 @@ function takeFollowups({ root, ids, slug, channel, now = new Date(), fsImpl = no
   if (!slug) throw new FollowupUsageError('--slug is required for --action take');
   const bad = invalidSlugRefusal(slug);
   if (bad) throw new FollowupUsageError(bad.message);
+  // `list` shows a taken item whose feature finished as `done`, but the fold still holds it `taken`: say what the user was shown.
+  const shown = loadFollowups(root, { fsImpl, now }).followups.find((item     ) => item.derived && list.includes(item.id));
+  if (shown) {
+    return refusal('take', 'illegal-transition', `${shown.id} is done because feature ${shown.takenBy} finished (derived from git and the release records, not recorded on the item); only an open item can be taken. Nothing was written.`);
+  }
   const out = appendEvents(root, [{ type: 'followup.taken', by: channelBy(channel), data: { ids: list, feature: slug } }], { now, fsImpl });
   if (!out.ok) return refusalFrom('take', out);
   return { ok: true, action: 'take', ids: list, feature: slug, events: out.written.map((w     ) => w.file), next: [] };
@@ -426,7 +457,7 @@ function promoteFollowups({ root, ids, title, channel, now = new Date(), fsImpl
 }
 
 module.exports = {
-  addFollowups, reportFollowup, listFollowups, takeFollowups, settleFollowups, promoteFollowups,
+  addFollowups, reportFollowup, listFollowups, followupOrderKey, takeFollowups, settleFollowups, promoteFollowups,
   loadFollowups, readBatchFile, resolveFeatureSlug, parseIds, oneLine, channelBy,
   FollowupUsageError, STAGES, STATES, SOURCE_KINDS, STATEMENT_MAX,
 };

package/src/runtime/lifecycle/overview.js

@@ -16,6 +16,8 @@ const { withDerivedDone } = require('./fold.js');
 const { appendEvents, readFold, readEvents } = require('./event-store.js');
 const { deriveStatuses, bucketize, behindNote } = require('./status.js');
 const { FollowupUsageError, parseIds } = require('./followup.js');
+const { describeActive } = require('../feature-pointer.js');
+const { commandLine } = require('../verb-view.js');
 
 /** The failure store, or null when its module cannot be loaded: the overview then reports no failures. */
 function failureStoreOrNull() {
@@ -129,7 +131,7 @@ function goalView(goal     , features     , statuses     , conflicts      = [])
 
 function nextLines({ shown, open, items, intents, goals, maintain, pendingItems, failures }     ) {
   const next = [];
-  if (shown < open) next.push('List the rest: doflow-run followup --action list');
+  if (shown < open) next.push(`Page through all ${open} open follow-ups: ${commandLine('followup', 'list', {})}`);
   if (items.length) next.push(`Take items into the new feature when its folder exists: doflow-run lifecycle --action init --slug <slug> --take ${items[0].id}`);
   if (intents.length) {
     next.push(`Start from a promoted intent: /do-brainstorm --intent ${intents[0].path}, then doflow-run lifecycle --action init --slug <slug> --intent ${intents[0].path}`);
@@ -289,4 +291,26 @@ function featureStatus({ root, slug, now = new Date(), fsImpl = nodeFs }     ) {
   return result;
 }
 
-module.exports = { buildOverview, initFeature, featureStatus, goalView, goalConflicts, goalConflictNext, DISCOVERY_SHOWN, MAINTAIN_SHOWN, FEATURES_SHOWN };
+/**
+ * `status` with no `--slug` (row 135): the feature the runtime recorded for this checkout, against the
+ * branch's. A mismatch or an unreadable pointer is a refusal (exit 1) that names both sides and picks
+ * neither; an agreeing pointer also carries the tracked feature's derived status, as `--slug` does.
+ */
+function activeFeature({ root, cwd, now = new Date(), fsImpl = nodeFs }     ) {
+  const active = describeActive({ storeRoot: root, cwd });
+  const here = `branch ${active.current.branch || 'unknown'}${active.current.slug ? `, branch feature ${active.current.slug}` : ''}`;
+  if (active.state === 'unreadable') {
+    return { ok: false, action: 'status', finding: 'feature-pointer-unreadable', message: `${active.file} cannot be read (${active.reason}); delete it to let the next feature start write it again.`, active };
+  }
+  if (active.state === 'mismatch') {
+    const p = active.pointer;
+    return { ok: false, action: 'status', finding: 'feature-mismatch', message: `the pointer names ${p.slug} on branch ${p.branch || 'unknown'}, but this checkout is on ${here}; neither is trusted, so check which feature you are on.`, active };
+  }
+  const result      = { ok: true, action: 'status', active };
+  if (active.state === 'none') return { ...result, message: `no active feature is recorded for this checkout (${here}); pass --slug <slug> to ask about one.` };
+  // An untracked feature is refused by featureStatus; the pointer answer stands, named, without status fields.
+  const derived = featureStatus({ root, slug: active.slug, now, fsImpl });
+  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 };

package/src/runtime/lifecycle/report-store.js

@@ -6,7 +6,7 @@
  * The machine-local report body (IC-005, DEC-014). A report's text can hold a crash trace, a log or
  * pasted output, so it never enters the repository: the body is masked with the body profile (IC-012),
  * cut to at most 1 MiB and written once under the same per-machine home the failure store uses,
- * `<XDG_CONFIG_HOME or $HOME/.config>/doflow/reports/<projectKey>/<FU-id>.txt`, folder 0700 and file
+ * `<config home>/doflow/reports/<projectKey>/<FU-id>.txt`, folder 0700 and file
  * 0600. The project event carries only a reference, the size and a masked 2 KB excerpt.
  *
  * `projectKey` is the first 12 hex characters of the SHA-256 of the IC-001 root's real path, so two
@@ -20,6 +20,7 @@ const nodeFs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
 const mask = require('../mask.js');
+const { configHome } = require('../config-home.js');
 
 /** A `--file` or `--stdin` source is read for at most this many bytes; the rest could not be kept anyway. */
 const MAX_READ_BYTES = 16 * 1024 * 1024;
@@ -38,17 +39,14 @@ const EXCERPT_BYTES = 2048;
 class ReportInputError extends Error {}
 
 /**
- * The folder holding every project's report bodies, or null when no home resolves. It resolves the
- * base the way IC-011 resolves the failure home (`XDG_CONFIG_HOME` when set, non-empty and absolute,
- * else `$HOME/.config` when `HOME` is absolute) and sits beside it, `doflow/reports`. The rule is
- * repeated here rather than required from the failure module, so the follow-up service still loads in
- * a build or an install where the failure modules cannot be loaded (IC-016).
+ * The folder holding every project's report bodies, or null when no config home resolves. It sits in
+ * the same config home as the failure home (`../config-home.js`), `doflow/reports`, and takes that
+ * leaf helper rather than the failure module, so the follow-up service still loads in a build or an
+ * install where the failure modules cannot be loaded (IC-016).
  */
 function reportsHome(env                                     = process.env)                {
-  const xdg = env.XDG_CONFIG_HOME;
-  if (typeof xdg === 'string' && xdg !== '') return path.isAbsolute(xdg) ? path.join(xdg, 'doflow', 'reports') : null;
-  const home = env.HOME;
-  return typeof home === 'string' && path.isAbsolute(home) ? path.join(home, '.config', 'doflow', 'reports') : null;
+  const { dir } = configHome(env);
+  return dir === null ? null : path.join(dir, 'reports');
 }
 
 function realProjectRoot(root        , fsImpl      = nodeFs)         {

package/src/runtime/lifecycle/retention.js

@@ -9,18 +9,17 @@
  * joined by any event that names more than one, and a unit goes only as a whole: when every item in
  * it is settled in the fold (a follow-up done or dismissed, a goal done) and its newest event is
  * older than the window. A unit whose removal would change anything else the fold shows (another
- * item, a feature, a release, a conflict) is kept.
+ * item, a feature, a release, a conflict) is kept, and so is a unit that an event of a type this
+ * version does not know (written by a newer DoFlow) names by id.
  *
- * `parseWindow` remains pure. `retentionWindow` composes its unset case with the declared storage
- * default and the project's prune setting; explicit environment values retain their existing meaning.
+ * `parseWindow` remains pure. `retentionWindow` composes the resolver-owned default with the project's
+ * prune setting; explicit values retain their existing meaning while pruning is off.
  */
 
 const nodeFs = require('node:fs');
 const { isDeepStrictEqual } = require('node:util');
-const { REPO_ROOT } = require('../../helper/repo-root.js');
-const { loadStorageRegistry } = require('../storage/registry.js');
-const { resolveRoots, readPruneSetting } = require('../storage/roots.js');
-const { foldInto, finalize } = require('./fold.js');
+const { loadSettings } = require('../settings/resolve.js');
+const { foldInto, finalize, EVENT_TYPES } = require('./fold.js');
 
 const HOUR_MS = 3600000;
 
@@ -35,23 +34,46 @@ function parseWindow(env                                     = process.env)
   return { state: 'invalid', raw: String(raw) };
 }
 
-/** Composes IC-013's explicit environment override with the declared lifecycle default. */
-function retentionWindow({ env = process.env, projectRoot, registry, fsImpl = nodeFs }      = {})      {
+function invalidRaw(resolved     , env                                    )         {
+  for (let i = resolved.candidates.length - 1; i >= 0; i -= 1) {
+    const candidate = resolved.candidates[i];
+    if (candidate.status !== 'invalid') continue;
+    if (candidate.layer === 'env') return String(env.DOFLOW_RETENTION_HOURS ?? '');
+    try {
+      const raw = JSON.parse(candidate.display);
+      if (typeof raw === 'string' || typeof raw === 'number') return String(raw);
+    } catch { /* a malformed whole-file candidate has no display value */ }
+    return candidate.display || candidate.reason || candidate.code || '';
+  }
+  return '';
+}
+
+/** Composes the retention setting and prune gate through the shared settings resolver. */
+function retentionWindow({ env = process.env, projectRoot, fsImpl = nodeFs }      = {})      {
   const parsed = parseWindow(env);
   if (parsed.state === 'invalid') return parsed;
-  if (parsed.state === 'on') return { ...parsed, source: 'env' };
-  let activeRegistry     ;
   try {
-    activeRegistry = registry || loadStorageRegistry({ repoRoot: REPO_ROOT, fsImpl });
+    let settingsRegistry;
+    if (fsImpl !== nodeFs) {
+      const { loadSettingsRegistry } = require('../settings/registry.js');
+      const loaded = loadSettingsRegistry({ fsImpl });
+      if (!loaded.ok) throw new Error(loaded.detail);
+      settingsRegistry = loaded.registry;
+    }
+    const view = loadSettings({ projectRoot, env, fsImpl, ...(settingsRegistry ? { registry: settingsRegistry } : {}) });
+    const retention = view.get('storage.retentionHours', 'project');
+    if (retention.state === 'invalid') return { state: 'invalid', raw: invalidRaw(retention, env) };
+    if (retention.explicit) {
+      const hours = retention.value;
+      return { state: 'on', hours, ms: hours * HOUR_MS, source: retention.origin.layer };
+    }
+    if (view.get('storage.prune', 'project').value !== 'on') return { state: 'off' };
+    const hours = retention.value;
+    return { state: 'on', hours, ms: hours * HOUR_MS, source: 'default' };
   } catch {
-    return { state: 'off' };
+    // Preserve an explicit environment window when the resolver registry is unavailable.
+    return parsed.state === 'on' ? { ...parsed, source: 'env' } : { state: 'off' };
   }
-  const roots = resolveRoots({ registry: activeRegistry, projectRoot, env });
-  if (readPruneSetting({ registry: activeRegistry, roots, rootId: 'project-state', fsImpl }).setting !== 'on') return { state: 'off' };
-  const lifecycleStore = activeRegistry.stores.find((store     ) => store.id === 'lifecycle-events');
-  if (!lifecycleStore) throw new Error('Storage registry has no lifecycle-events store');
-  const hours = lifecycleStore.bound.defaultHours;
-  return { state: 'on', hours, ms: hours * HOUR_MS, source: 'default' };
 }
 
 function isText(value     )          { return typeof value === 'string' && value.trim() !== ''; }
@@ -113,6 +135,34 @@ function unitsOf(events       , shouldStop                )               {
   return [...units.values()];
 }
 
+/**
+ * Every string value and every object key in the data of the events whose type this version's fold
+ * does not know (a newer DoFlow wrote them). The fold ignores them, so retention cannot tell what they change; a unit that
+ * one of them names by id is kept whole rather than deleted from under it. Exact matches only:
+ * keeping too little is a lost record, keeping too much only a file that stays.
+ * @returns {Set<string>|null} null when `shouldStop` fired
+ */
+function unknownTypeStrings(events       , shouldStop                )                     {
+  const known = new Set        (EVENT_TYPES);
+  const found = new Set        ();
+  for (const event of events) {
+    if (shouldStop?.()) return null;
+    if (known.has(event.type)) continue;
+    const pending        = [event.data];
+    while (pending.length > 0) {
+      if (shouldStop?.()) return null;
+      const value = pending.pop();
+      if (typeof value === 'string') found.add(value);
+      else if (Array.isArray(value)) pending.push(...value);
+      else if (value && typeof value === 'object') {
+        for (const key of Object.keys(value)) found.add(key);
+        pending.push(...Object.values(value));
+      }
+    }
+  }
+  return found;
+}
+
 function isSettled(state     , key        )          {
   const [kind, id] = [key.slice(0, key.indexOf(':')), key.slice(key.indexOf(':') + 1)];
   if (kind === 'followup') {
@@ -173,6 +223,12 @@ function selectExpired(events       , { now, windowMs, shouldStop }      = {})
   }
   const named = unitsOf(events, shouldStop);
   if (!named || shouldStop?.()) return incomplete();
+  const mentioned = unknownTypeStrings(events, shouldStop);
+  if (!mentioned || shouldStop?.()) return incomplete();
+  // Selected exactly as 5bc9407b did (every settled, expired, unserved unit is a candidate), and only
+  // then are the units an unknown-type event names dropped. Protection removes units from that
+  // selection; it never changes which of the others are picked, so what is deleted is always a subset
+  // of what base would delete on the same events.
   const candidates        = [];
   for (const unit of named) {
     if (shouldStop?.()) return incomplete();
@@ -186,20 +242,28 @@ function selectExpired(events       , { now, windowMs, shouldStop }      = {})
     if (eligible) candidates.push({ ...unit, newestAt: newest });
   }
   const full = finalize(state);
-  let selected = candidates;
-  const allSafe = refoldEqual(events, full, candidates, now, shouldStop);
-  if (allSafe === null || shouldStop?.()) return incomplete();
-  if (!allSafe) {
-    selected = [];
-    const ordered = [...candidates].sort((a     , b     ) => Date.parse(a.newestAt) - Date.parse(b.newestAt));
-    if (shouldStop?.()) return incomplete();
+  /** The refold-safe subset of `list`: all of it when that holds, else the oldest-first greedy pass. */
+  const safeSubset = (list       )               => {
+    const allSafe = refoldEqual(events, full, list, now, shouldStop);
+    if (allSafe === null || shouldStop?.()) return null;
+    if (allSafe) return list;
+    const chosen        = [];
+    const ordered = [...list].sort((a     , b     ) => Date.parse(a.newestAt) - Date.parse(b.newestAt));
+    if (shouldStop?.()) return null;
     for (const unit of ordered) {
-      if (shouldStop?.()) return incomplete();
-      const safe = refoldEqual(events, full, [...selected, unit], now, shouldStop);
-      if (safe === null) return incomplete();
-      if (safe) selected.push(unit);
+      if (shouldStop?.()) return null;
+      const safe = refoldEqual(events, full, [...chosen, unit], now, shouldStop);
+      if (safe === null) return null;
+      if (safe) chosen.push(unit);
     }
-  }
+    return chosen;
+  };
+  const baseSelected = safeSubset(candidates);
+  if (!baseSelected) return incomplete();
+  const unprotected = baseSelected.filter((unit     ) => ![...unit.items].some((key        ) => mentioned.has(key.slice(key.indexOf(':') + 1))));
+  // Dropping units can leave a set the refold no longer accepts; check it again, inside the subset.
+  const selected = unprotected.length === baseSelected.length ? baseSelected : safeSubset(unprotected);
+  if (!selected) return incomplete();
   const units        = [];
   for (const unit of selected) {
     if (shouldStop?.()) return incomplete();

package/src/runtime/lifecycle/root.js

@@ -10,6 +10,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { execFileSync } = require('node:child_process');
+const { memoGit } = require('../git-memo.js');
 
                                                                           
 
@@ -61,11 +62,18 @@ function showToplevel(cwd        )                {
  * @returns {string} an absolute, real path
  */
 function projectRoot(cwd         = process.cwd())         {
+  // Inside a call scope (git-memo.ts) the answer git gave for this path is kept for the call. The
+  // fallback `real(cwd)` is not git's answer, so it is never kept: the path may become a repository.
+  return memoGit(`projectRoot:${path.resolve(cwd)}`, () => gitProjectRoot(cwd)) ?? real(cwd);
+}
+
+/** The root git names for `cwd`, or undefined when git names none (outside a repository). */
+function gitProjectRoot(cwd        )                     {
   let entries                  = [];
   try { entries = worktreeEntries(git(cwd, ['worktree', 'list', '--porcelain'])); } catch { /* not a repository */ }
   const first = entries[0];
   if (first && !first.bare && isRealWorkTree(first)) return real(first.path);
-  return showToplevel(cwd) || real(cwd);
+  return showToplevel(cwd) || undefined;
 }
 
 module.exports = { projectRoot, worktreeEntries };

package/src/runtime/lifecycle/status.js

@@ -11,19 +11,20 @@
  * the release tags and the base tag) come from `do-git-state.sh --lifecycle`, so bash and Node never
  * derive them twice. The rest is a fixed number of plain `git` calls, however many features are
  * tracked: one `rev-parse` pins the ref, one `for-each-ref` lists the branches, one
- * `git log --first-parent --merges` lists the merges, one `git tag --list` (tagged mode) gives the
- * release tags' commits, and one `git rev-list --parents` reads the commit graph of the pinned ref
- * and those tags. Every ancestry question (which merge brought a branch tip in, which tag contains a
- * merge) is then answered from that graph in memory, not by a git call per feature.
+ * `git log --first-parent --merges` lists the merges and their `DoFlow-Row` trailers, one
+ * `git tag --list` (tagged mode) gives the release tags' commits, and one `git rev-list --parents`
+ * reads the commit graph of the pinned ref and those tags. Every ancestry question (which merge
+ * brought a branch tip in, which tag contains a merge) is then answered from that graph in memory,
+ * not by a git call per feature.
  *
  * Nothing here writes, fetches or reaches a network.
  *
  * Accepted ceilings, stated rather than hidden: a feature's merge evidence is only as good as the
- * merge commit's subject and the branch name (a squash, a rebase and a fast-forward leave none,
- * so they reach the user through `notDetected` and `lifecycle --action merged`); the merge log and
- * the graph are read in full, without `--since` or a lower cut (a skewed clock must not hide a
- * merge), so their cost grows with the history of the integration ref, once per call; git dates
- * have one-second resolution, so the lower bound is floored to the second.
+ * merge commit's `DoFlow-Row` trailer or subject and the branch name (a squash, a rebase and a
+ * fast-forward leave none, so they reach the user through `notDetected` and `lifecycle --action
+ * merged`); the merge log and the graph are read in full, without `--since` or a lower cut (a skewed
+ * clock must not hide a merge), so their cost grows with the history of the integration ref, once
+ * per call; git dates have one-second resolution, so the lower bound is floored to the second.
  */
 
 const fs = require('node:fs');
@@ -69,13 +70,18 @@ function subjectNames(subject        , slug        )          {
   return new RegExp(`(?:^|[^a-z0-9-])${escapeRegExp(slug)}(?:$|[^a-z0-9-])`).test(subject);
 }
 
-/** First-parent merges of `ref`, oldest first. */
-function readMerges(root        , ref        )                                                                         {
-  const out = git(root, ['log', '--first-parent', '--merges', '--format=%H%x09%P%x09%ct%x09%s', ref]);
-  return out.split('\n').filter(Boolean).map((line) => {
-    const [sha, parents, ct, ...subject] = line.split('\t');
-    return { sha, parents: parents.split(' ').filter(Boolean), ct: Number(ct), subject: subject.join('\t') };
-  }).reverse();
+/** First-parent merges of `ref`, oldest first, with any `DoFlow-Row` trailer. */
+function readMerges(root        , ref        )                                                                                             {
+  const out = git(root, ['log', '--first-parent', '--merges', '--format=%H%x00%P%x00%ct%x00%s%x00%(trailers:key=DoFlow-Row,separator=%x1f)%x00', ref]);
+  const fields = out.split('\0');
+  const merges                                                                                             = [];
+  for (let i = 0; i + 4 < fields.length; i += 5) {
+    const [rawSha, parents, ct, subject, rowTrailer] = fields.slice(i, i + 5);
+    const sha = rawSha.trim();
+    if (!sha) continue;
+    merges.push({ sha, parents: parents.split(' ').filter(Boolean), ct: Number(ct), subject, rowTrailer: rowTrailer.trim() });
+  }
+  return merges.reverse();
 }
 
 /** Branch refs by short name (`feat/x`, `origin/feat/x`) with their tips; local branches first. */
@@ -221,7 +227,18 @@ function findEvidence({ slug, lowerBound, merges, mergeBySha, newestCt, history,
     if (merge) return { kind: 'branch', ref: tip.short, commit: merge.sha };
   }
   for (let i = merges.length - 1; i >= 0; i -= 1) {
-    if (merges[i].ct >= lowerBound && subjectNames(merges[i].subject, slug)) return { kind: 'merge-subject', ref: merges[i].sha.slice(0, 7), commit: merges[i].sha };
+    const merge = merges[i];
+    if (merge.ct < lowerBound) continue;
+    if (merge.rowTrailer) {
+      // A present DoFlow-Row is authoritative: it can match only on an exact two-parent merge,
+      // and a mismatch must not fall through to a subject that names a different row.
+      const match = /^DoFlow-Row:\s*(.*?)\s*$/i.exec(merge.rowTrailer);
+      if (merge.parents.length === 2 && match && match[1] === slug) {
+        return { kind: 'trailer', ref: merge.sha.slice(0, 7), commit: merge.sha };
+      }
+      continue;
+    }
+    if (subjectNames(merge.subject, slug)) return { kind: 'merge-subject', ref: merge.sha.slice(0, 7), commit: merge.sha };
   }
   if (confirmed) return { kind: 'confirmed', ref: null, commit: null };
   return null;

package/src/runtime/lifecycle/store-upkeep.js

@@ -36,8 +36,18 @@ const LEGACY_EVENTS_REL = path.join(LEGACY_LIFECYCLE_REL, 'events');
 const MARKER_REL = path.join(LIFECYCLE_REL, 'migrated.json');
 const MIGRATING_PREFIX = 'events.migrating-';
 const NOTICE = 'note: the lifecycle store is now .doflow/state/lifecycle/events; agent-docs/lifecycle/ is no longer read and can be deleted';
-const removedLine = (count     , hours     ) => `retention: removed ${count} event files older than ${hours} h`;
-const invalidLine = (raw     ) => `warning: DOFLOW_RETENTION_HOURS='${raw}' is not a positive whole number of hours; ignored, nothing removed`;
+const removedLine = (count     , hours     ) => `retention: removed ${count} event ${count === 1 ? 'file' : 'files'} older than ${hours} h`;
+// A leading zero is rejected on purpose (`024` could be read as octal); the warning names it.
+const invalidLine = (raw     ) => `warning: DOFLOW_RETENTION_HOURS='${raw}' is not a positive whole number of hours${/^0[0-9]+$/.test(String(raw)) ? ' (no leading zeros)' : ''}; ignored, nothing removed`;
+/**
+ * What `writeAtomic` leaves behind when a verb dies between creating its temp file and renaming it:
+ * `.retention-<pid>-<chars>.tmp` (the journal) and `.migrated-<pid>-<chars>.tmp` (the marker), in the
+ * lifecycle folder. The storage engine's work-store sweep matches `<name>.json.<pid>.tmp` inside
+ * record stores only, so nothing else ever removes them.
+ */
+const WRITE_TMP = /^\.(?:retention|migrated)-[0-9]+-[A-Za-z0-9]+\.tmp$/;
+/** The age past which such a file is abandoned; the storage engine passes `settings.staleTmpHours`, and a test pins this to it. */
+const STALE_TMP_MS = 24 * 3600000;
 /** Bounds one pass, so its journal stays far below the reader's cap and its lock is held briefly. */
 const MAX_PASS_FILES = 20000;
 /** Unlinks between two refreshes of the lock's age. */
@@ -100,7 +110,8 @@ function fsyncCopy(fsImpl     , file     ) {
 function fsyncFolder(fsImpl     , dir     ) {
   let fd;
   try { fd = fsImpl.openSync(dir, 'r'); } catch { return; }
-  try { fsImpl.fsyncSync(fd); } finally { fsImpl.closeSync(fd); }
+  // Windows opens a folder but refuses to flush it (EPERM); there is nothing to flush there.
+  try { fsImpl.fsyncSync(fd); } catch (error     ) { if (!['EPERM', 'EINVAL', 'EISDIR', 'ENOTSUP'].includes(error?.code)) throw error; } finally { fsImpl.closeSync(fd); }
 }
 
 const migrationFailed = (code     ) => ({
@@ -208,6 +219,30 @@ function refreshLock(fsImpl     , root     ) {
   try { fsImpl.utimesSync(`${lockTarget(root)}.lock`, now, now); } catch { /* the lock folder is ours; a failed touch only shortens its life */ }
 }
 
+/**
+ * Removes temp files a crashed writer left in the lifecycle folder, once they are older than
+ * `staleMs`. Runs under the store lock, which every writer of these files holds, so none of them
+ * belongs to a live pass unless its lock was taken over as stale. Best effort: a file that cannot
+ * be removed is left for the next pass. `shouldStop` is checked before each unlink and each unlink
+ * counts against `maxFiles`, so a bounded caller's budget and stop hold here too.
+ * @returns {{removed: number, partial: boolean}} partial: stopped or out of budget with files left
+ */
+function sweepStaleTmp(fsImpl     , root     , now     , staleMs         = STALE_TMP_MS, { maxFiles = Infinity, shouldStop }      = {}) {
+  const dir = path.join(root, LIFECYCLE_REL);
+  let list          ;
+  try { list = namesIn(fsImpl, dir); } catch { return { removed: 0, partial: false }; }
+  let removed = 0;
+  for (const name of list) {
+    if (!WRITE_TMP.test(name)) continue;
+    const file = path.join(dir, name);
+    const st = lstatOrNull(fsImpl, file);
+    if (!st || !st.isFile() || now.getTime() - st.mtimeMs <= staleMs) continue;
+    if (shouldStop?.() || removed >= maxFiles) return { removed, partial: true };
+    try { fsImpl.unlinkSync(file); removed += 1; } catch { /* left for the next pass */ }
+  }
+  return { removed, partial: false };
+}
+
 /** Unlinks pending event files without clearing the journal until every hidden name is finished. */
 function removePending(fsImpl     , root     , names     , onRemoved = () => {}, { maxFiles = Infinity, shouldStop }      = {}) {
   const dir = path.join(root, EVENTS_REL);
@@ -294,7 +329,7 @@ function retain(fsImpl     , root     , window     , now     , { maxFiles = MAX_
 
 /** Runs a bounded lifecycle retention pass under a non-waiting store lock for the storage engine. */
 function retainLocked(root     , options      = {}) {
-  const { window, now = new Date(), fsImpl = nodeFs, maxFiles = MAX_PASS_FILES, shouldStop } = options;
+  const { window, now = new Date(), fsImpl = nodeFs, maxFiles = MAX_PASS_FILES, shouldStop, staleTmpMs = STALE_TMP_MS } = options;
   const bounded = Object.hasOwn(options, 'maxFiles') || Object.hasOwn(options, 'shouldStop');
   const outcome = (removed     , warning     , partial = false, selected      = [], code      ) => bounded
     ? { removed, warning, partial, selected, ...(code ? { code } : {}) }
@@ -306,7 +341,9 @@ function retainLocked(root     , options      = {}) {
   const release = tryAcquireLock(fsImpl, lockTarget(root));
   if (!release) return outcome(0, [], true);
   try {
-    const result = retain(fsImpl, root, window, now, { maxFiles, shouldStop });
+    const swept = sweepStaleTmp(fsImpl, root, now, staleTmpMs, { maxFiles, shouldStop });
+    if (swept.partial) return outcome(0, [], true);
+    const result = retain(fsImpl, root, window, now, { maxFiles: Math.max(0, maxFiles - swept.removed), shouldStop });
     return outcome(result.removedCount, result.warning, result.partial, result.selected, result.code);
   } finally {
     release();
@@ -326,7 +363,7 @@ function needsPrune(fsImpl     , root     , window     , now     ) {
  * @param {string} root projectRoot() result
  * @param {{env?: Object, now?: Date, fsImpl?: Object}} [options] defaults process.env, new Date(), node:fs
  * @returns {{ok: true, lines: string[]}
- *   | {ok: false, finding: 'store-migration-failed'|'store-locked', message: string, lines: string[]}}
+ *   | {ok: false, finding: 'store-migration-pending'|'store-migration-failed'|'store-locked', message: string, lines: string[]}}
  *   `lines` are for stderr, without the verb prefix.
  * @throws {StoreUnsafeError} a symlinked new store folder, or a symlinked old folder when a copy must read it
  */
@@ -345,6 +382,17 @@ function prepareStore(root        , { env = process.env, now = new Date(), fsImp
       try { migrate = legacyEventFiles(fsImpl, root).length > 0; } catch (error     ) { return legacyUnreadable(error.code || error.message); }
     }
   }
+  if (env.DOFLOW_UPKEEP === 'off') {
+    if (migrate) {
+      return {
+        ok: false,
+        finding: 'store-migration-pending',
+        message: 'the lifecycle store has not been copied yet; run any followup, lifecycle or goal command once without DOFLOW_UPKEEP=off. Nothing was written.',
+        lines: [],
+      };
+    }
+    return { ok: true, lines: [...notice, ...invalid] };
+  }
   const retentionDue = readJournal(root, fsImpl).pending.length > 0 || needsPrune(fsImpl, root, window, now);
   if (!migrate && !markerDue && !retentionDue) return { ok: true, lines: [...notice, ...invalid] };
   if (migrate) refuseLinks(fsImpl, root, [LEGACY_LIFECYCLE_REL, LEGACY_EVENTS_REL]);
@@ -367,6 +415,7 @@ function prepareStore(root        , { env = process.env, now = new Date(), fsImp
     throw error;
   }
   try {
+    sweepStaleTmp(fsImpl, root, now);
     // Decided again under the lock: another verb may have finished the copy while this one waited.
     let marked = hasMarker(fsImpl, root);
     if (!marked && storeHasEvents(fsImpl, root)) {
@@ -390,4 +439,4 @@ function prepareStore(root        , { env = process.env, now = new Date(), fsImp
   }
 }
 
-module.exports = { prepareStore, retainLocked, LEGACY_LIFECYCLE_REL, LEGACY_EVENTS_REL, MARKER_REL };
+module.exports = { prepareStore, retainLocked, removedLine, STALE_TMP_MS, LEGACY_LIFECYCLE_REL, LEGACY_EVENTS_REL, MARKER_REL };