@khoavu882/doflow 2.0.1 → 2.0.2

package/src/adapters/opencode/index.js

@@ -25,6 +25,7 @@ const { MARKER_START, MARKER_END } = require('../../helper/marker-merge.js');
 const { destructiveCommandGlobs } = require('../../helper/guardrails.js');
 const { declaredHarnessPaths, resolveHarnessPaths } = require('../../helper/harness-paths.js');
 const { renderGuidancePointer } = require('../guidance-pointer.js');
+const { isBlank, createdByDoFlow, creationOrigin, removeCreatedFile } = require('../created-file.js');
 
 const HARNESS = 'opencode';
 /**
@@ -141,7 +142,8 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
   }
 
   function managedInstruction(existing     , rendered     ) {
-    if (existing === null) return { ok: true, operation: 'create', content: rendered };
+    // A file holding only whitespace has nothing to protect and counts as absent.
+    if (existing === null || isBlank(existing)) return { ok: true, operation: 'create', content: rendered };
     const start = existing.indexOf(MARKER_START);
     const end = existing.indexOf(MARKER_END);
     if (start === -1 && end === -1) return { ok: false, conflict: `${INSTRUCTION_FILE} exists without a DoFlow managed section` };
@@ -316,7 +318,9 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
       else if (outcome.operation !== 'none' && outcome.content !== null) {
         changes.push({ assetId: guidance.id, target: found.paths.instruction, operation: outcome.operation,
           content: outcome.content, ownershipIdentity: `${HARNESS}:instructions:managed-section`,
-          fingerprint: fingerprint(outcome.content), harness: HARNESS, projection: { renderer: 'opencode-instructions' } });
+          fingerprint: fingerprint(outcome.content), harness: HARNESS, projection: { renderer: 'opencode-instructions' },
+          // A file DoFlow created and a removal that leaves only whitespace: the file goes (remove()).
+          ...(removing && createdByDoFlow(ledger, HARNESS, `${HARNESS}:instructions:managed-section`, found.paths.instruction) ? { deleteWhenBlank: true } : {}) });
       }
     }
 
@@ -336,7 +340,9 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
           // src/adapters/copilot/index.js's analogous mcp-merge change already carries).
           operation: removing ? 'remove' : (found.config.exists ? 'update' : 'create'), content: `${JSON.stringify(next, null, 2)}\n`,
           ownershipIdentity: `${HARNESS}:config:registration`, fingerprint: fingerprint(next),
-          harness: HARNESS, projection: { renderer: 'opencode-config' } });
+          harness: HARNESS, projection: { renderer: 'opencode-config' },
+          // A file DoFlow created that a removal leaves empty goes too (remove()).
+          ...(removing && createdByDoFlow(ledger, HARNESS, `${HARNESS}:config:registration`, found.paths.config) ? { deleteWhenEmpty: true } : {}) });
       }
     } else if (removing) {
       changes.push(...releasedConfigRow({ assets, paths: found.paths, ledger }));
@@ -384,14 +390,29 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
       if (change.operation !== 'remove') continue;
       if (change.kind === 'copy-tree-file' || change.kind === 'mcp-server') continue; // routed below
       if (typeof change.content !== 'string') continue;
+      if (change.deleteWhenBlank && isBlank(change.content) && removeCreatedFile(change.target, fsImpl)) { removed += 1; continue; }
       writeChange(change, fsImpl);
       removed += 1;
     }
     removed += writeMcpEntries(changes, { container: MCP_CONTAINER, fsImpl });
+    // After the entry removals, which edit the same file: what is left of a config DoFlow created.
+    for (const change of changes) {
+      if (change.deleteWhenEmpty && configIsEmpty(change.target, fsImpl) && removeCreatedFile(change.target, fsImpl)) removed += 1;
+    }
     removed += removeCopyTreeAssets(changes, { fsImpl });
     return { removed };
   }
 
+  /** True when the file holds nothing but an empty JSON object (or only whitespace). */
+  function configIsEmpty(file        , fsImpl     ) {
+    try {
+      const text = fsImpl.readFileSync(file, 'utf8');
+      if (isBlank(text)) return true;
+      const value = JSON.parse(text);
+      return value !== null && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === 0;
+    } catch { return false; }
+  }
+
   function verify({ scope, scopeRoot, assets = [], mcp = [], mcpAdoptable = [], discovery, ledger, operation, context = {}, fsImpl = fs }     ) {
     const found = discover({ scope, scopeRoot, mcp, mcpAdoptable, ledger, context, fsImpl });
     const removing = (operation ?? context.operation) === 'remove';
@@ -399,6 +420,10 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
     const resources = [];
     const conflicts = [];
     const instructionsAssetId = assets.find((asset     ) => asset.capability === 'instructions')?.id ?? pseudoAssetId(assets);
+    const originOf = (ownershipIdentity        , target        , before     ) => {
+      const origin = creationOrigin({ ledger, harness: HARNESS, ownershipIdentity, target, before });
+      return origin ? { origin } : {};
+    };
 
     const hasSection = typeof found.instruction === 'string'
       && found.instruction.includes(MARKER_START) && found.instruction.includes(MARKER_END);
@@ -408,7 +433,8 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
     if (hasSection) {
       resources.push({ assetId: instructionsAssetId, target: found.paths.instruction,
         ownershipIdentity: `${HARNESS}:instructions:managed-section`, fingerprint: fingerprint(found.instruction),
-        sourceVersion: context.sourceVersion ?? 'unknown', projection: { renderer: 'opencode-instructions' } });
+        sourceVersion: context.sourceVersion ?? 'unknown', projection: { renderer: 'opencode-instructions' },
+        ...originOf(`${HARNESS}:instructions:managed-section`, found.paths.instruction, discovery ? discovery.instruction : undefined) });
     }
 
     if (!found.mcpSnapshot[found.paths.config].ok) {
@@ -424,7 +450,8 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
       if (registered) {
         resources.push({ assetId: pseudoAssetId(assets), target: found.paths.config,
           ownershipIdentity: `${HARNESS}:config:registration`, fingerprint: fingerprint(value),
-          sourceVersion: context.sourceVersion ?? 'unknown', projection: { renderer: 'opencode-config' } });
+          sourceVersion: context.sourceVersion ?? 'unknown', projection: { renderer: 'opencode-config' },
+          ...originOf(`${HARNESS}:config:registration`, found.paths.config, discovery ? (discovery.config.exists ? {} : null) : undefined) });
       }
       if (context.permissions) {
         const ours = guardrailBashRules(context);

package/src/adapters/pi/index.js

@@ -27,6 +27,7 @@ const { declaredHarnessPaths, resolveHarnessPaths } = require('../../helper/harn
 const { mcpRows, discoverPiMcp, ownedPiMcpIds, planPiMcp, applyPiMcp, verifyPiMcp } = require('./mcp.js');
 const { planPiHooks, verifyPiHooks, removePiHooks } = require('./hooks.js');
 const { renderGuidancePointer } = require('../guidance-pointer.js');
+const { isBlank, createdByDoFlow, creationOrigin, removeCreatedFile } = require('../created-file.js');
 
 const HARNESS = 'pi';
 const AGENT_DIR_MCP_NOTICE = 'PI_CODING_AGENT_DIR is set: Pi reads its whole agent dir from it, but DoFlow moves only mcp.json there; skills and AGENTS.md stay in ~/.pi/agent.';
@@ -73,9 +74,10 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env
 
   /** Replace only the span between DoFlow's markers. An AGENTS.md with no DoFlow section is refused
    * rather than appended to — Pi shares AGENTS.md with every other agent that reads it, so where
-   * DoFlow's content belongs is its owner's decision. Add an empty marker pair to opt in. */
+   * DoFlow's content belongs is its owner's decision. Add an empty marker pair to opt in. A file
+   * holding only whitespace has nothing to protect and counts as absent. */
   function managedInstruction(existing     , rendered     ) {
-    if (existing === null) return { ok: true, operation: 'create', content: rendered };
+    if (existing === null || isBlank(existing)) return { ok: true, operation: 'create', content: rendered };
     const start = existing.indexOf(MARKER_START);
     const end = existing.indexOf(MARKER_END);
     if (start === -1 && end === -1) return { ok: false, conflict: 'AGENTS.md exists without a DoFlow managed section' };
@@ -190,7 +192,9 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env
       else if (outcome.operation !== 'none' && outcome.content !== null) {
         changes.push({ assetId: guidance.id, target: found.paths.instruction, operation: outcome.operation,
           content: outcome.content, ownershipIdentity: `${HARNESS}:instructions:managed-section`,
-          fingerprint: fingerprint(outcome.content), harness: HARNESS, projection: { renderer: 'pi-instructions' } });
+          fingerprint: fingerprint(outcome.content), harness: HARNESS, projection: { renderer: 'pi-instructions' },
+          // A file DoFlow created and a removal that leaves only whitespace: the file goes (remove()).
+          ...(removing && createdByDoFlow(ledger, HARNESS, `${HARNESS}:instructions:managed-section`, found.paths.instruction) ? { deleteWhenBlank: true } : {}) });
       }
     }
 
@@ -252,6 +256,7 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env
       if (change.operation !== 'remove' || change.projection?.renderer === 'copy-tree' || isPiMcp(change)) continue;
       if (change.projection?.renderer === 'pi-guard-extension') continue;
       if (change.content === null) continue;
+      if (change.deleteWhenBlank && isBlank(change.content) && removeCreatedFile(change.target, fsImpl)) { removed += 1; continue; }
       writeChange(change, fsImpl);
       removed += 1;
     }
@@ -260,6 +265,11 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env
     return { removed };
   }
 
+  function originField({ ledger, target, before }     ) {
+    const origin = creationOrigin({ ledger, harness: HARNESS, ownershipIdentity: `${HARNESS}:instructions:managed-section`, target, before });
+    return origin ? { origin } : {};
+  }
+
   function verify({ scope, scopeRoot, assets = [], mcp = [], discovery, ledger, context = {}, fsImpl = fs }     ) {
     const found = discover({ scope, scopeRoot, mcp, ledger, context, fsImpl });
     const statuses = [];
@@ -275,7 +285,8 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env
     if (hasSection) {
       resources.push({ assetId: instructionsAssetId, target: found.paths.instruction,
         ownershipIdentity: `${HARNESS}:instructions:managed-section`, fingerprint: fingerprint(found.instruction),
-        sourceVersion: context.sourceVersion ?? 'unknown', projection: { renderer: 'pi-instructions' } });
+        sourceVersion: context.sourceVersion ?? 'unknown', projection: { renderer: 'pi-instructions' },
+        ...originField({ ledger, target: found.paths.instruction, before: discovery?.instruction }) });
     }
 
     const copyTree = verifyCopyTreeAssets({ assets, scope, scopeRoot, context, fsImpl });

package/src/adapters/pi/mcp.js

@@ -104,7 +104,8 @@ function twinOf(doc     , key        )      {
   return doc.servers?.members.find((member     ) => member.key !== key && piServerKey(member.key) === piServerKey(key)) ?? null;
 }
 
-function sameValue(a     , b     )          { return JSON.stringify(a) === JSON.stringify(b); }
+/** Equal as JSON values, whatever order an object's keys sit in (an owned entry the user reordered is still ours). */
+function sameValue(a     , b     )          { return fingerprint(a) === fingerprint(b); }
 
 function baseChange({ target, operation, id, snapshot }     )      {
   return {
@@ -271,26 +272,51 @@ function applyPiMcp(changes       , { fsImpl = fs }                   = {})
   for (const [target, all] of groups) {
     const group = all.filter((change     ) => !change.release);
     if (!group.length) continue;
-    const exists = fsImpl.existsSync(target);
-    const bytes = exists ? fsImpl.readFileSync(target) : Buffer.alloc(0);
-    if (sha256(bytes) !== group[0].baseHash) throw new Error(`Pi MCP: ${target} changed after planning; nothing was written, re-run the command`);
-    const text = bytes.toString('utf8');
-    const creates = group.filter((change     ) => change.operation === 'create');
-    const origin = group.find((change     ) => change.origin)?.origin;
-    let next = exists ? editedText(text, group) : renderNewDocument(creates.map((change     ) => [change.identity, change.entry]));
-    // Only a file DoFlow created is deleted, and never through a symlink; a user's own file that
-    // happens to equal the skeleton stays.
-    if (exists && origin?.created === 'file' && next === SKELETON) {
-      if (!isSymlink(target, fsImpl)) { fsImpl.rmSync(target); applied += 1; continue; }
-    } else if (exists && origin && !creates.length) next = restoredText(next, origin);
-    if (next !== text) {
-      atomicWrite(target, next, fsImpl);
-      applied += 1;
-    }
+    // The hash check and the write are one critical section across the installers of this machine,
+    // keyed by the file a write lands in, so two links to one mcp.json share a lock.
+    const release = lockTarget(target, fsImpl);
+    try { applied += applyGroup(target, group, fsImpl); } finally { release(); }
   }
   return { applied };
 }
 
+/** The file a write to `target` lands in, as one name for every path that reaches it. */
+function canonicalTarget(target        , fsImpl     )         {
+  const dest = writePath(target, fsImpl);
+  try { return fsImpl.realpathSync(dest); } catch { /* not there yet: its directory names it */ }
+  try { return path.join(fsImpl.realpathSync(path.dirname(dest)), path.basename(dest)); } catch { return path.resolve(dest); }
+}
+
+/** Waits for another installer's lock on the same mcp.json (`<file>.lock`, task-state's protocol: a
+ * crashed holder's lock is reclaimed once stale) and refuses with that lock named when it stays held. */
+function lockTarget(target        , fsImpl     )             {
+  const { acquireLock } = require('../../runtime/task-state.js');
+  const canonical = canonicalTarget(target, fsImpl);
+  fsImpl.mkdirSync(path.dirname(canonical), { recursive: true });
+  try { return acquireLock(fsImpl, canonical); } catch (error     ) {
+    throw new Error(`Pi MCP: ${target} is being changed by another DoFlow run; nothing was written, re-run the command (${error.message})`);
+  }
+}
+
+/** One file's changes, applied against the bytes read now. Returns 1 when the file changed. */
+function applyGroup(target        , group       , fsImpl     )         {
+  const exists = fsImpl.existsSync(target);
+  const bytes = exists ? fsImpl.readFileSync(target) : Buffer.alloc(0);
+  if (sha256(bytes) !== group[0].baseHash) throw new Error(`Pi MCP: ${target} changed after planning; nothing was written, re-run the command`);
+  const text = bytes.toString('utf8');
+  const creates = group.filter((change     ) => change.operation === 'create');
+  const origin = group.find((change     ) => change.origin)?.origin;
+  let next = exists ? editedText(text, group) : renderNewDocument(creates.map((change     ) => [change.identity, change.entry]));
+  // Only a file DoFlow created is deleted, and never through a symlink; a user's own file that
+  // happens to equal the skeleton stays.
+  if (exists && origin?.created === 'file' && next === SKELETON) {
+    if (!isSymlink(target, fsImpl)) { fsImpl.rmSync(target); return 1; }
+  } else if (exists && origin && !creates.length) next = restoredText(next, origin);
+  if (next === text) return 0;
+  atomicWrite(target, next, fsImpl);
+  return 1;
+}
+
 function statusFor({ id, target, status }                                                )      {
   return { harness: HARNESS, assetId: ASSET_ID, capability: 'mcp', identity: id, target,
     ownershipIdentity: `doflow:${HARNESS}:mcp-server:${id}`, status };
@@ -370,4 +396,4 @@ function verifyPiMcp({ selected = [], rows = [], file, snapshot = {}, removing =
   return { statuses, resources, conflicts };
 }
 
-module.exports = { NOTICES, renderPiEntry, piServerKey, mcpRows, discoverPiMcp, ownedPiMcpIds, planPiMcp, applyPiMcp, verifyPiMcp };
+module.exports = { NOTICES, renderPiEntry, piServerKey, mcpRows, discoverPiMcp, ownedPiMcpIds, planPiMcp, applyPiMcp, verifyPiMcp, canonicalTarget };

package/src/cli/commands/remove.js

@@ -10,7 +10,7 @@ const { loadRegistry } = require('../../registry/index.js');
 const { storageForgetScope } = require('../../runtime/storage/upkeep.js');
 const { removeLifecycle, retentionSummary } = require('../../lifecycle/index.js');
 const {
-  codexScope, registryLifecycleView, printRegistryLifecycle, LIFECYCLE_HARNESSES,
+  codexScope, registryLifecycleView, printRegistryLifecycle, printPlanNotices, LIFECYCLE_HARNESSES,
   assertSafeRegistryPlan, lockDocument, recordLock,
 } = require('../../lifecycle/view.js');
 const { recordedMcpSelections } = require('../../install/mcp.js');
@@ -63,6 +63,8 @@ function cmdRemove(o     )       {
     // antigravity/copilot) mean a removal can legitimately leave files standing. Saying only "removed"
     // would be half the truth, so what was kept and who still claims it is printed, not implied.
     for (const line of retentionSummary(result.retained)) console.log(`[INFO] ${line}`);
+    // The plan's notices (a file left untouched, a kept edit) read the same on a real run as under --dry-run.
+    printPlanNotices(view);
     console.log(`[OK] Removed ${result.ledger.resources.length === 0 ? 'all' : 'eligible'} native resource(s) for ${lifecycleTargets.join(', ')}; ${result.ledger.resources.length} owned record(s) remain.`);
 
     // Re-pin what still stands: every harness the ledger still holds keeps its pin and its recorded

package/src/cli/commands/update.js

@@ -4,7 +4,7 @@
 // TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
 const os = require('node:os');
 const path = require('node:path');
-const { resolveTargets, toolDirs } = require('../../install/targets.js');
+const { resolveTargets, installedTargets, toolDirs } = require('../../install/targets.js');
 const { resolveContext, printContext } = require('../../install/context.js');
 const { DEFAULT_BACKUP_RETENTION, createFileBackup, applyRetention, retentionNote } = require('../../install/backup.js');
 const { backupSetFromPlan } = require('../../install/backup-set.js');
@@ -29,12 +29,17 @@ const {
 
 function cmdUpdate(o     )       {
   refuseHomeRootedProject(o, 'update');
-  const targets = resolveTargets(o.targets);
+  const requested = resolveTargets(o.targets); // validates an explicit -t before anything is read
   const scope = scopeOf(o);
   const hold = holdRunLock(o, scope, 'update');
   try {
     const dirs = toolDirs(scope);
     const lifecyclePaths = installPaths(scope);
+    const existingManifest = readInstallManifest({ scopeRoot: lifecyclePaths.scopeRoot });
+    // No -t: act on the harnesses this scope's manifest lists as installed, not on the install default.
+    // With no manifest (or none listed) the default stays, as before.
+    const listed = installedTargets(existingManifest);
+    const targets = o.targets?.length || !listed.length ? requested : listed;
     const backupRoot = lifecyclePaths.backupRoot;
     const commit = sourceCommit(SCRIPT_DIR);
     printContext(resolveContext({ repoRoot: REPO_ROOT, targets, dirs, sourceCommit: commit, ...scope }));
@@ -42,7 +47,6 @@ function cmdUpdate(o     )       {
     // Never interactive: update reuses each harness's recorded selection, or applies an explicit --mcp
     // override, without re-prompting.
     const registry = loadRegistry({ repoRoot: REPO_ROOT });
-    const existingManifest = readInstallManifest({ scopeRoot: lifecyclePaths.scopeRoot });
     const { lock, ledger } = scopeSelectionState(scope);
     const selection = resolveMcpSelections({
       cmd: 'update', requested: o.mcp, targets, registry, lock, ledger, manifestServers: existingManifest?.mcpServers ?? null,

package/src/cli/index.js

@@ -53,6 +53,16 @@ function assertNoBackupRequiresForce(o     )       {
   }
 }
 
+/**
+ * Reports an argument error and exits. `review` answers in its own JSON usage shape when `--json` is anywhere in the
+ * arguments (before or after the bad one); every other verb prints the plain line on stderr.
+ */
+function argError(o     , argv          , message        , code        )        {
+  if (o.cmd === 'review' && argv.includes('--json')) console.log(JSON.stringify({ ok: false, error: 'usage', message }));
+  else console.error(`doflow: ${message}`);
+  process.exit(code);
+}
+
 function parseArgs(argv          )      {
   const o      = { cmd: null, positional: [], targets: [], mcp: null, dryRun: false, force: false, adopt: false,
     otlpHttp: false,
@@ -68,7 +78,7 @@ function parseArgs(argv          )      {
     if (a.startsWith('-')) o.flagsGiven.push(a);
     // `--commit` is the roadmap verb's own flag: anywhere else it must reach the default branch and get
     // that verb's unknown-flag answer, as it did before it was added. '' matches no case.
-    switch (a === '--commit' && o.cmd !== 'roadmap' ? '' : a) {
+    switch (a === '--commit' && o.cmd !== 'roadmap' ? '' : a.startsWith('--action=') ? '--action' : a) {
       case '-h': case '--help': o.help = true; break;
       case '-v': o.version = true; break;
       case '--version':
@@ -92,7 +102,7 @@ function parseArgs(argv          )      {
       case '--':
         if (o.cmd === 'slot') { o.slotCommand = argv.slice(i + 1); i = argv.length; break; }
         if (o.cmd === 'plan-check') break;
-        console.error(unknownFlagMessage(a)); process.exit(unknownFlagExit(o.cmd));
+        argError(o, argv, unknownFlagMessage(a), unknownFlagExit(o.cmd));
         break;
       // worker --action run|describe|select: the isolated-edit recipe and baseline (082 IC-014).
       case '--edit': o.edit = true; break;
@@ -148,10 +158,12 @@ function parseArgs(argv          )      {
         o.tools = val.split(',').map((s) => s.trim()).filter(Boolean); i++; break;
       }
       case '--action': {
-        const val = argv[i + 1];
+        // `--action <value>` or `--action=<value>`.
+        const inline = a.startsWith('--action=');
+        const val = inline ? a.slice('--action='.length) : argv[i + 1];
         // `review`, `protocol`, `config`, `primary` and `package` answer a missing value as usage, exit 2; other verbs keep exit 1.
-        if (val === undefined || val.startsWith('-')) { console.error(`doflow: ${a} requires a value`); process.exit(o.cmd === 'review' || o.cmd === 'protocol' || o.cmd === 'config' || o.cmd === 'primary' || o.cmd === 'fleet' || o.cmd === 'transcript' || o.cmd === 'package' || o.cmd === 'worktree' ? 2 : 1); }
-        o.action = val; o.actionGiven = true; i++; break;
+        if (val === undefined || val === '' || val.startsWith('-')) argError(o, argv, '--action requires a value', o.cmd === 'review' || o.cmd === 'protocol' || o.cmd === 'config' || o.cmd === 'primary' || o.cmd === 'fleet' || o.cmd === 'transcript' || o.cmd === 'package' || o.cmd === 'worktree' ? 2 : 1);
+        o.action = val; o.actionGiven = true; if (!inline) i++; break;
       }
       case '--task-class': {
         const val = argv[i + 1];
@@ -236,7 +248,7 @@ function parseArgs(argv          )      {
         if (runtime !== null) { i = runtime; break; }
         // slot, primary, fleet and transcript report an unknown flag as their own usage error (exit 2, 115 IC-008, 120 IC-008).
         if (a.startsWith('-') && (o.cmd === 'slot' || o.cmd === 'primary' || o.cmd === 'fleet' || o.cmd === 'transcript')) (o.extraFlags = o.extraFlags || []).push(a);
-        else if (a.startsWith('-') && o.cmd !== 'plan-check') { console.error(unknownFlagMessage(a)); process.exit(unknownFlagExit(o.cmd)); }
+        else if (a.startsWith('-') && o.cmd !== 'plan-check') argError(o, argv, unknownFlagMessage(a), unknownFlagExit(o.cmd));
         else if (!o.cmd) o.cmd = a;
         else o.positional.push(a);
       }
@@ -254,12 +266,12 @@ function unknownFlagExit(cmd               )         {
 /** Longest part of an unrecognised argument echoed back; the rest is cut and marked. */
 const UNKNOWN_FLAG_ECHO_CHARS = 80;
 
-/** The unknown-flag error: the argument is untrusted text, so it is made print-safe (no control
+/** The unknown-flag message (without the `doflow: ` prefix): the argument is untrusted text, so it is made print-safe (no control
  * characters, one line) and cut to a bounded length (FU-8eqytg). */
 function unknownFlagMessage(arg        )         {
   const safe = printSafe(String(arg));
   const shown = safe.length > UNKNOWN_FLAG_ECHO_CHARS ? `${safe.slice(0, UNKNOWN_FLAG_ECHO_CHARS)}...` : safe;
-  return `doflow: unknown flag '${shown}'`;
+  return `unknown flag '${shown}'`;
 }
 
 /** Single-value arguments of the runtime verbs → the option key each one writes. */
@@ -498,14 +510,14 @@ function parseRuntimeFlag(arg        , argv          , i        , o     )
     // `--batch <file|->`. Rejecting it made the documented spelling exit 2 while only `--batch=-`
     // worked — a help text endorsing a form the parser refuses.
     const isStdin = value === '-';
-    if (value === undefined || (value.startsWith('-') && !isStdin)) { console.error(`doflow: ${name} requires a value`); process.exit(2); }
+    if (value === undefined || (value.startsWith('-') && !isStdin)) argError(o, argv, `${name} requires a value`, 2);
     next = i + 1;
   }
-  if (value === '') { console.error(`doflow: ${name} requires a value`); process.exit(2); }
+  if (value === '') argError(o, argv, `${name} requires a value`, 2);
 
   if (RUNTIME_INT_FLAGS.has(name)) {
     const parsed = parseInt(value, 10);
-    if (!Number.isFinite(parsed) || parsed < 0) { console.error(`doflow: ${name} expects a non-negative integer, got '${value}'`); process.exit(2); }
+    if (!Number.isFinite(parsed) || parsed < 0) argError(o, argv, `${name} expects a non-negative integer, got '${value}'`, 2);
     o[key] = parsed;
   } else if (RUNTIME_LIST_FLAGS.has(name)) {
     // --exclude and --exclude-family both accept comma lists or repeated flags. Keep --exclude's
@@ -710,7 +722,7 @@ Runtime verb arguments (accept --flag value or --flag=value):
       --request <text>, --request-file <file>  classify (mutually exclusive; optional second opinion)
       --view brief|full                     followup --action list (default brief), lifecycle --action overview, classify (default full); brief drops detail, full is the whole answer
       --cursor <c>, --limit <n>             followup --action list (the cursor is opaque: pass back a page's nextCursor); also transcript --action read
-      --intent, --query, --check            route
+      --intent, --query, --check, --harness  route
       --statement, --claim-id,
       --evidence-id, --relation             claim
       --kind, --provenance, --provider,

package/src/cli/runtime-commands.js

@@ -415,7 +415,7 @@ function dispatchRuntimeCommandInner(o     , moment     )      {
     case 'brief-tools': return handleBriefToolsCommand({ owner: o.owner, tier: o.tier, harness: o.harness, slug: o.slug, headingLevel: o.headingLevel, tasks: o.tasks, json: o.json, repoRoot: REPO_ROOT, projectRoot: storeRoot, buildAdapters: buildAdapterRegistry });
     case 'advise': return handleAdviseCommand({ action: o.action, actionGiven: o.actionGiven, kind: o.kind, server: o.server, state: o.state, stateFile: o.stateFile, staticAnswer: o.staticAnswer, questionsFile: o.questionsFile, taskId: o.taskId, pickId: o.pickId, actual: o.actual, model: o.model, endpoint: o.endpoint, off: o.off, project: o.project, force: o.force, global: o.global, json: o.json, projectRoot: evidenceRoot(o) });
     case 'model-role': return handleModelRoleCommand({ role: o.role, exclude: o.exclude, excludeFamilies: o.excludeFamily, json: o.json, repoRoot: REPO_ROOT });
-    case 'route': return handleRouteCommand({ intent: o.intent, query: o.query, check: o.check, json: o.json, projectRoot: evidenceRoot(o) });
+    case 'route': return handleRouteCommand({ intent: o.intent, query: o.query, harness: o.harness, check: o.check, json: o.json, projectRoot: evidenceRoot(o) });
     case 'claim': return handleClaimCommand({ slug: storeSlug, taskId: requireTaskId(o), action: o.action, statement: o.statement, claimId: o.claimId, evidenceId: o.evidenceId, replacedBy: o.replacedBy, relation: o.relation, role: o.role, json: o.json, stateRoot: storeRoot });
     case 'context-pack': return handleContextPackCommand({ taskId: requireTaskId(o), taskClass: o.taskClass, objective: o.objective, json: o.json, stateRoot: storeRoot, sourceRoot: evidenceRoot(o), slug: storeSlug, explicitSlug: o.slug || null, mandatoryFile: o.mandatoryFile, harness: o.harness, maxBytes: o.maxBytes, bare: o.bare, noRecord: o.noRecord, reason: o.reason, since: o.since, expand: o.expand });
     // 078 IC-005 and IC-013: identity is the process environment's alone, never a flag.

package/src/cli/shared.js

@@ -10,7 +10,7 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const { REPO_ROOT } = require('../helper/repo-root.js');
-const { doflowPaths } = require('../install/paths.js');
+const { doflowPaths, canonicalPath, canonicalLedger } = require('../install/paths.js');
 const { readInstallManifest } = require('../install/manifest.js');
 const { DEFAULT_BACKUP_RETENTION, formatBytes } = require('../install/backup.js');
 const { stateRoot, readLedger } = require('../state/index.js');
@@ -64,7 +64,9 @@ function buildAdapterRegistry()      {
 
 /** Resolve {global, projectRoot} scope options for src/install/targets.js#toolDirs from parsed args. */
 function scopeOf(o     )                                           {
-  return { global: o.global, projectRoot: o.positional[0] || '.' };
+  // The single place a project path enters the verbs: canonical, so an aliased spelling (macOS
+  // /var -> /private/var) and the real one name the same scope, ledger rows and lock.
+  return { global: o.global, projectRoot: o.global ? (o.positional[0] || '.') : canonicalPath(o.positional[0] || '.') };
 }
 
 function installPaths(scope     )      {
@@ -141,7 +143,7 @@ function scopeSelectionState(scope     )      {
   const scopeRoot = scope.global ? os.homedir() : path.resolve(scope.projectRoot);
   return {
     lock: readLock(scope.global ? { scope: 'global', homeDir: scopeRoot } : { scope: 'project', projectRoot: scopeRoot }),
-    ledger: readLedger(stateRoot({ scope: scope.global ? 'global' : 'project', projectRoot: scopeRoot, homeDir: scopeRoot })),
+    ledger: canonicalLedger(readLedger(stateRoot({ scope: scope.global ? 'global' : 'project', projectRoot: scopeRoot, homeDir: scopeRoot })), scopeRoot),
     manifestServers: readInstallManifest({ scopeRoot })?.mcpServers ?? null,
   };
 }

package/src/helper/marker-merge.js

@@ -70,8 +70,7 @@ function mergeMarkedSection(srcAbs        , dstAbs        , { dryRun = false, co
       // original file's matching trailing "\n" (if present) must be consumed here —
       // otherwise a replace with no real change grows the file by one newline
       // every time it runs (breaks idempotency).
-      let afterEnd = endIdx + MARKER_END.length;
-      if (existing[afterEnd] === '\n') afterEnd += 1;
+      const afterEnd = afterEndMarker(existing, endIdx + MARKER_END.length);
       newContent = existing.slice(0, startIdx) + section + existing.slice(afterEnd);
     }
   }
@@ -84,10 +83,16 @@ function mergeMarkedSection(srcAbs        , dstAbs        , { dryRun = false, co
   return { changed: true };
 }
 
+/** `at` moved past the one line break (LF or CRLF) that follows an end marker, if there is one. */
+function afterEndMarker(text        , at        )         {
+  if (text[at] === '\n') return at + 1;
+  return text[at] === '\r' && text[at + 1] === '\n' ? at + 2 : at;
+}
+
 /**
  * Where `text`'s doflow span is: the first of `startMarkers`, the first MARKER_END after it, and no
  * start marker after that end (a second span is `malformed`). `after` is past the end marker and the
- * one '\n' that follows it.
+ * one line break (LF or CRLF) that follows it.
  */
 function markedSpan(text        , startMarkers           = [MARKER_START])                                                                                             {
   const found = startMarkers.map((marker) => ({ at: text.indexOf(marker), length: marker.length })).filter((item) => item.at !== -1);
@@ -95,10 +100,9 @@ function markedSpan(text        , startMarkers           = [MARKER_START])
   const first = found.reduce((a, b) => (b.at < a.at ? b : a));
   const end = text.indexOf(MARKER_END, first.at + first.length);
   if (end === -1) return { state: 'malformed' };
-  let after = end + MARKER_END.length;
-  if (startMarkers.some((marker) => text.indexOf(marker, after) !== -1)) return { state: 'malformed' };
-  if (text[after] === '\n') after += 1;
-  return { state: 'ok', start: first.at, after };
+  const closed = end + MARKER_END.length;
+  if (startMarkers.some((marker) => text.indexOf(marker, closed) !== -1)) return { state: 'malformed' };
+  return { state: 'ok', start: first.at, after: afterEndMarker(text, closed) };
 }
 
 /**

package/src/install/backup-set.js

@@ -89,8 +89,9 @@ function addCandidate(candidates                  , file        , harness
  * lock); an entry at or under one of them is reported in `excluded`, not backed up.
  * `records` lists DoFlow record files backed up beside those files although an `exclude` root holds
  * them (the ownership ledger), with no harness; a rollback restores only the ledger rows of the files
- * it writes back (backup.ts mergeRestoredLedger). They join only a set that holds some file already,
- * so a run that backs up nothing still backs up nothing.
+ * it writes back (backup.ts mergeRestoredLedger). They join a set that holds some file already, or one whose
+ * plan gives up a retired harness's ledger row (only the ledger is then snapshotted); a run that changes
+ * neither backs up nothing.
  */
 function backupSetFromPlan({ plan, scope, scopeRoot, exclude = [], records = [], fsImpl = fs }     )      {
   const candidates = new Map();
@@ -131,7 +132,10 @@ function backupSetFromPlan({ plan, scope, scopeRoot, exclude = [], records = [],
   const excluded = [...mcpOnly]
     .filter(([target, onlyMcp]) => onlyMcp && !candidates.has(target))
     .map(([target]) => ({ path: target, reason: 'mcp-entries-only' }));
-  if (candidates.size) for (const file of records) addCandidate(candidates, file, null, 'record');
+  // A retired harness's row given up (every sweep action but `defer`) is a ledger change even when no file
+  // changes: the ledger alone is snapshotted then, so a rollback restores the row. Deferred rows stay.
+  const givesUpRow = plan.changes.some((change     ) => change.retired === true && change.action !== 'defer');
+  if (candidates.size || givesUpRow) for (const file of records) addCandidate(candidates, file, null, 'record');
   return toBackupSet(candidates, { scope, scopeRoot, exclude, excluded, records, fsImpl });
 }
 

package/src/install/backup.js

@@ -591,11 +591,12 @@ function planRestore({ bid, backupRoot, scope, scopeRoot, targets, explicitTarge
  * staler than the current one; a current row of it the backup lacks stays. A restored row whose file
  * a live harness now claims is released by the next sweep (claim rule 2), file untouched.
  */
-function mergeRestoredLedger(backup     , current     , restored             , retired              = new Set())      {
+function mergeRestoredLedger(backup     , current     , restored             , retired              = new Set(), lost              = new Set())      {
   if (!current) return backup;
   const at = (target     ) => typeof target === 'string' && restored.has(path.resolve(target));
   const whole = (row     ) => retired.has(row?.harness);
-  const back = backup.resources.filter((r     ) => at(r.target) || whole(r));
+  // A retired row whose file this restore tried and could not write back stays out: it would name a file the next sweep drops as absent.
+  const back = backup.resources.filter((r     ) => at(r.target) || (whole(r) && !(typeof r.target === 'string' && lost.has(path.resolve(r.target)))));
   const backKeys = new Set(back.filter(whole).map(ownershipKey));
   const targets = Object.entries(backup.targets ?? {}).filter(([id]) => retired.has(id));
   return {
@@ -610,20 +611,23 @@ function mergeRestoredLedger(backup     , current     , restored             , r
 }
 
 /** Ids the registry retires (row 127 IC-001): `registry` when a caller passes one, else the shipped
- * registry. One that cannot be read retires nothing, which leaves the merge per restored file. */
+ * registry. One that cannot be read throws, so a restore stops before it writes anything rather than
+ * silently skipping the retired rows and targets. */
 function retiredIds(registry     )              {
   if (registry === undefined) {
     const { REPO_ROOT } = require('../helper/repo-root.js');
-    try { registry = require('../registry/index.js').loadRegistry({ repoRoot: REPO_ROOT }); } catch { registry = null; }
+    try { registry = require('../registry/index.js').loadRegistry({ repoRoot: REPO_ROOT }); } catch (err     ) {
+      throw new BackupError(`cannot read the registry to find retired harnesses: ${err?.message ?? err}`);
+    }
   }
   return new Set((Array.isArray(registry?.retired) ? registry.retired : []).map((entry     ) => entry?.id).filter((id     ) => typeof id === 'string'));
 }
 
 /** The bytes a ledger restore item writes: the backup's ledger merged onto the current one. */
-function restoredLedgerBytes(item     , restored             , retired             , fsImpl     )         {
+function restoredLedgerBytes(item     , restored             , retired             , lost             , fsImpl     )         {
   const backup = validateLedger(JSON.parse(fsImpl.readFileSync(item.stored, 'utf8')));
   const current = fsImpl.existsSync(item.path) ? validateLedger(JSON.parse(fsImpl.readFileSync(item.path, 'utf8'))) : null;
-  return Buffer.from(`${JSON.stringify(validateLedger(mergeRestoredLedger(backup, current, restored, retired)), null, 2)}\n`);
+  return Buffer.from(`${JSON.stringify(validateLedger(mergeRestoredLedger(backup, current, restored, retired, lost)), null, 2)}\n`);
 }
 
 /**
@@ -641,6 +645,8 @@ function executeRestore(plan     , { backupRoot, dryRun = false, registry, fsImp
     return { restored: plan.v1.tools.map((t     ) => t.tool), failed: [], absent: [], refused: [], untargeted: 0, legacy: true };
   }
 
+  // Read before the first write: an unreadable registry stops the restore with nothing changed.
+  const retired = dryRun || plan.narrowed || !plan.restore.some((item     ) => item.ledger) ? new Set        () : retiredIds(registry);
   const restored = [];
   const failed = [];
   const files = new Set        ();
@@ -654,7 +660,7 @@ function executeRestore(plan     , { backupRoot, dryRun = false, registry, fsImp
     try {
       const dir = path.dirname(item.path);
       fsImpl.mkdirSync(dir, { recursive: true });
-      const bytes = item.ledger ? restoredLedgerBytes(item, files, plan.narrowed ? new Set() : retiredIds(registry), fsImpl) : fsImpl.readFileSync(item.stored);
+      const bytes = item.ledger ? restoredLedgerBytes(item, files, retired, new Set([...failed.map((f     ) => f.path), ...plan.refused.map((f     ) => f.path)].filter((p     ) => typeof p === 'string').map((p        ) => path.resolve(p))), fsImpl) : fsImpl.readFileSync(item.stored);
       let isLink = false;
       try {
         isLink = fsImpl.lstatSync(item.path).isSymbolicLink();

package/src/install/context.js

@@ -7,6 +7,7 @@
 // native type-stripping — no build step, no runtime dependency. Body stays CommonJS so a `.js`
 // caller's `require('../install/context.js')` keeps working while the tree is still `.js`.
 const path = require('node:path');
+const { canonicalPath } = require('./paths.js');
 const { sourceCommit: gitSourceCommit } = require('../helper/git.js');
 
                                
@@ -27,7 +28,7 @@ const { sourceCommit: gitSourceCommit } = require('../helper/git.js');
 function resolveContext({ repoRoot, global, projectRoot, targets, dirs, sourceCommit, managedResources }                     )      {
   const context      = {
     scope: global ? 'global' : 'project',
-    scopeRoot: global ? path.dirname(dirs.claude) : path.resolve(projectRoot),
+    scopeRoot: global ? path.dirname(dirs.claude) : canonicalPath(projectRoot),
     targets,
     dirs: Object.fromEntries(targets.map((t) => [t, dirs[t]])),
     repoRoot,