@khoavu882/doflow 2.0.0 → 2.0.2

package/src/adapters/codex/config.js

@@ -202,8 +202,11 @@ function planCodexConfig({ file, scope, managedResources = [], desiredResources
     if (nextLines.length && nextLines.at(-1) !== '') nextLines.push('');
     nextLines.push(`[${table}]`, ...lines);
   }
-  let content = nextLines.join('\n');
-  if (content && !content.endsWith('\n')) content += '\n';
+  // The file keeps its own line ending (the first one it uses) and its own final-newline state; only a file
+  // that was empty or ended in a newline gets one, so a remove can hand back the user's exact bytes.
+  const eol = /\r?\n/.exec(original)?.[0] ?? '\n';
+  let content = nextLines.join(eol);
+  if (content && !content.endsWith('\n') && (original === '' || original.endsWith('\n'))) content += eol;
   const invalid = newViolation({ file, original, content, identities: changes.map((change     ) => change.identity) });
   if (invalid) return { ok: false, status: 'conflict', file, original, changes: [], conflicts: [invalid], managedResources };
   const nextManagedResources = managedResources.filter((resource     ) => !isOwnedRecord(resource, scope) || desired.has(resource.identity));

package/src/adapters/codex/hooks.js

@@ -17,6 +17,41 @@ const SUPPORTED_EVENTS = new Set([
   'UserPromptSubmit', 'SubagentStop', 'Stop', 'SessionStart', 'SubagentStart', 'SessionEnd',
 ]);
 
+// An earlier DoFlow wired a pre-bash-guard front door into hooks.json and deployed its script. Both
+// are gone from the shipped source; a merge drops the entry from the live file so an updated install
+// does not keep a hook that runs a script nothing refreshes, and the script goes with it. Only the
+// exact command DoFlow shipped is dropped: a user's own hook that happens to name a script of the same
+// file name stays.
+const RETIRED_HOOK_SCRIPT = 'pre-bash-guard.sh';
+const RETIRED_HOOK_COMMAND = 'bash "$(root=$(git rev-parse --show-toplevel 2>/dev/null) && [ -f "$root/.codex/hooks/pre-bash-guard.sh" ] && printf \'%s/.codex/hooks/pre-bash-guard.sh\' "$root" || printf \'%s/hooks/pre-bash-guard.sh\' "${CODEX_HOME:-$HOME/.codex}")"';
+
+function withoutRetiredHooks(hooks     )      {
+  const result                      = {};
+  for (const [event, groups] of Object.entries     (hooks || {})) {
+    if (!Array.isArray(groups)) { result[event] = groups; continue; }
+    const kept = groups.map((group     ) => (Array.isArray(group?.hooks)
+      ? { ...group, hooks: group.hooks.filter((handler     ) => handler?.command !== RETIRED_HOOK_COMMAND) }
+      : group)).filter((group     ) => !Array.isArray(group?.hooks) || group.hooks.length > 0);
+    if (kept.length) result[event] = kept;
+  }
+  return result;
+}
+
+/** Whether the retired front door is still on disk as DoFlow's own (it names the bridge call it was written with). */
+function ownsRetiredHookScript(destinationHooksDir        , fsImpl      = fs)          {
+  const target = path.join(destinationHooksDir, RETIRED_HOOK_SCRIPT);
+  try {
+    return fsImpl.lstatSync(target).isFile() && fsImpl.readFileSync(target, 'utf8').includes('doflow_bridge codex PreToolUse pre-bash-guard');
+  } catch { return false; }
+}
+
+/** Delete the retired front door when it is still DoFlow's own. */
+function removeRetiredHookScript(destinationHooksDir        , fsImpl      = fs, dryRun = false)         {
+  if (!ownsRetiredHookScript(destinationHooksDir, fsImpl)) return 0;
+  if (!dryRun) { try { fsImpl.unlinkSync(path.join(destinationHooksDir, RETIRED_HOOK_SCRIPT)); } catch { return 0; } }
+  return 1;
+}
+
 function validationError(errors          , message        )       { errors.push(message); }
 
 function validateHooksConfig(config     )                                                      {
@@ -148,7 +183,7 @@ function planCodexHooks({ config, sourceFile, sourceHooksDir, destinationContext
     try {
       const existing = JSON.parse(original);
       if (existing?.hooks && desired?.hooks) {
-        mergedDesired = { ...existing, ...desired, hooks: mergeHooks(existing.hooks, desired.hooks) };
+        mergedDesired = { ...existing, ...desired, hooks: mergeHooks(withoutRetiredHooks(existing.hooks), desired.hooks) };
       }
     } catch {
       // malformed existing will be flagged or left for schema validation
@@ -167,7 +202,7 @@ function planCodexHooks({ config, sourceFile, sourceHooksDir, destinationContext
     return { ok: false, status: 'conflict', destination, original, changes: [], commands,
       errors: scripts.edited.map((name        ) => `Codex hook script '${name}' was modified outside DoFlow`) };
   }
-  const scriptsOnly = !configChanged && scripts.stale.length > 0;
+  const scriptsOnly = !configChanged && (scripts.stale.length > 0 || ownsRetiredHookScript(destinationHooksDir, fsImpl));
   const changed = configChanged || scriptsOnly;
   // The scripts deployCodexHooks copies beside hooks.json, so a backup of this change holds them too.
   const companionTargets = [...new Set([
@@ -204,6 +239,7 @@ function deployCodexHooks(plan     , { dryRun = false, fsImpl = fs }
     fsImpl.copyFileSync(source, target);
     fsImpl.chmodSync(target, fsImpl.statSync(source).mode & 0o777);
   }
+  removeRetiredHookScript(plan.destinationHooksDir, fsImpl);
   return { ...plan, applied: true };
 }
 
@@ -220,7 +256,7 @@ function shippedHookScripts(scriptsDir     , fsImpl      = fs)           {
  * user edited or added stays. The directory goes only once it is empty. */
 function removeCodexHookScripts({ scriptsDir, destinationHooksDir }                                                        = {}, { dryRun = false, fsImpl = fs }                                     = {})                      {
   if (!destinationHooksDir || !fsImpl.existsSync(destinationHooksDir)) return { removed: 0 };
-  let removed = 0;
+  let removed = removeRetiredHookScript(destinationHooksDir, fsImpl, dryRun);
   for (const name of shippedHookScripts(scriptsDir, fsImpl)) {
     const target = path.join(destinationHooksDir, name);
     // lstat, not stat: a symlink (even to a file with the shipped bytes) is not DoFlow's copy.

package/src/adapters/codex/index.js

@@ -503,9 +503,22 @@ function createCodexAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
         hooks = { ...hooks, ok: false, status: 'conflict', changes: [], errors: ['Codex hooks.json was modified outside DoFlow'] };
       }
     }
+    if (hooks.ok) hooks = withStaleScriptReleases(hooks, scriptRows(neutralResources, context));
     return hooks;
   }
 
+  /** A script row for a name the source no longer ships (a retired front door) is released with the
+   * plan, so the ledger does not keep a row for a file the update deletes. The script itself goes by
+   * its bytes (deployCodexHooks), so this only drops the row. */
+  function withStaleScriptReleases(hooks     , rows       ) {
+    const shipped = new Set(hooks.scriptNames);
+    const releases = rows.filter((row     ) => !shipped.has(row.identity)).map((row     ) => ({ type: 'remove', assetId: row.assetId, identity: row.identity,
+      target: row.target, ownershipIdentity: row.ownershipIdentity, kind: row.kind, release: true }));
+    if (!releases.length) return hooks;
+    return { ...hooks, changes: [...hooks.changes, ...releases],
+      ...(hooks.status === 'unchanged' ? { status: 'change', scriptsOnly: true } : {}) };
+  }
+
   /** Agents/hooks share one removing-vs-planning fork: removal always owns both via the neutral
    * ledger's own records, regardless of what native input the caller provided this run. */
   /** A removal drops the rows of the hook scripts too. The scripts themselves go by their bytes

package/src/adapters/copilot/index.js

@@ -36,6 +36,7 @@ const path = require('node:path');
 const { MARKER_START, MARKER_END } = require('../../helper/marker-merge.js');
 const { planTree, applyTree, removeTree, verifyTree, copyTreeDestDir, ledgerFileResources, ledgerSiblingFingerprints, siblingReplacedNotices, fingerprint, sourceDirFor, resolveTransform } = require('../copy-tree.js');
 const { renderGuidancePointer } = require('../guidance-pointer.js');
+const { isBlank, createdByDoFlow, creationOrigin, removeCreatedFile } = require('../created-file.js');
 const { readMcpFiles, planMcpEntries, verifyMcpEntries, ownedMcpIds, writeMcpEntries } = require('../mcp-entries.js');
 const { declaredHarnessPaths, resolveHarnessPaths } = require('../../helper/harness-paths.js');
 
@@ -108,7 +109,8 @@ function createCopilotAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS],
    * file it doesn't fully own is a decision for the file's owner, not a guess for the installer. Add
    * an empty marker pair to opt in. */
   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` };
@@ -132,7 +134,7 @@ function createCopilotAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS],
   /** Plan the single instructions change (or none). Global scope always yields no change and no
    * conflict — the user-level ~/.copilot/copilot-instructions.md is not projected, so there is no
    * global target, the same way other adapters skip a capability they do not project at a scope. */
-  function planInstructionsChange({ assets, found, scope, scopeRoot, context, removing, fsImpl }     ) {
+  function planInstructionsChange({ assets, found, scope, scopeRoot, context, removing, ledger, fsImpl }     ) {
     if (!found.paths.instruction) return { changes: [], conflicts: [] };
     // The marker-managed instruction file is one specific asset: exclude tree-projected rule
     // assets (copilot-rule-instructions), whose `source` is a directory, not a file.
@@ -148,6 +150,8 @@ function createCopilotAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS],
         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: 'copilot-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 } : {}),
       }],
       conflicts: [],
     };
@@ -305,7 +309,7 @@ function createCopilotAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS],
     const conflicts = [];
     const removing = context.operation === 'remove';
 
-    const instructions = planInstructionsChange({ assets, found, scope, scopeRoot, context, removing, fsImpl });
+    const instructions = planInstructionsChange({ assets, found, scope, scopeRoot, context, removing, ledger, fsImpl });
     changes.push(...instructions.changes);
     conflicts.push(...instructions.conflicts);
 
@@ -365,6 +369,7 @@ function createCopilotAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS],
       if (change.operation !== 'remove') continue;
       if (change.projection?.renderer === 'copy-tree' || change.kind === 'mcp-server') continue;
       if (typeof change.content !== 'string') continue;
+      if (change.deleteWhenBlank && isBlank(change.content) && removeCreatedFile(change.target, fsImpl)) { removed += 1; continue; }
       writeChange(change, fsImpl);
       removed += 1;
     }
@@ -389,9 +394,11 @@ function createCopilotAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS],
         status: hasSection ? 'managed' : 'absent', target: found.paths.instruction,
         ownershipIdentity: `${HARNESS}:instructions:managed-section` });
       if (hasSection) {
+        const origin = creationOrigin({ ledger, harness: HARNESS, ownershipIdentity: `${HARNESS}:instructions:managed-section`, target: found.paths.instruction, before: discovery?.instruction });
         resources.push({ assetId, target: found.paths.instruction,
           ownershipIdentity: `${HARNESS}:instructions:managed-section`, fingerprint: fingerprint(found.instruction),
-          sourceVersion: context.sourceVersion ?? 'unknown', projection: { renderer: 'copilot-instructions' } });
+          sourceVersion: context.sourceVersion ?? 'unknown', projection: { renderer: 'copilot-instructions' },
+          ...(origin ? { origin } : {}) });
       }
     }
 

package/src/adapters/copy-tree.js

@@ -371,14 +371,13 @@ function kiroHook({ name, trigger, matcher, script, timeout }
   };
 }
 
-/** The three preToolUse hooks every DoFlow-rendered Kiro agent carries. The MCP guard uses the
+/** The two preToolUse hooks every DoFlow-rendered Kiro agent carries. The MCP guard uses the
  * "*" matcher: Kiro documents "@<server>" (every tool of one server) and "*" but no all-MCP
  * matcher, and mcp-tool-guard.sh exits 0 immediately for any non-MCP tool name, so "*" costs one
  * fast no-op for built-in tools and still covers every MCP server. */
 function kiroPreToolUseHooks()        {
   return [
     kiroHook({ name: 'doflow-pre-implementation-gate', trigger: 'preToolUse', matcher: 'write', script: 'pre-implement-gate.sh', timeout: 10 }),
-    kiroHook({ name: 'doflow-pre-bash-guard', trigger: 'preToolUse', matcher: 'shell', script: 'pre-bash-guard.sh', timeout: 10 }),
     kiroHook({ name: 'doflow-mcp-tool-guard', trigger: 'preToolUse', matcher: '*', script: 'mcp-tool-guard.sh', timeout: 10 }),
   ];
 }
@@ -662,6 +661,13 @@ function applyTree({ changes = [], fsImpl = fs, transform }     )
     if (change.operation === 'remove') continue;
     fsImpl.mkdirSync(path.dirname(change.target), { recursive: true });
     const sourceStat = fsImpl.statSync(change.source);
+    // A destination symlink (`install -f` plans over one) is replaced by the regular file, never written through:
+    // its target, which may be a file outside the install, keeps its bytes and mode.
+    try {
+      if (fsImpl.lstatSync(change.target).isSymbolicLink()) fsImpl.unlinkSync(change.target);
+    } catch (error     ) {
+      if (error.code !== 'ENOENT') throw error;
+    }
     if (mapContent) {
       // Re-derive the bytes from the source at write time instead of copying it: the transform,
       // not the source file, is what the recorded fingerprint describes. Keeps recovery retries

package/src/adapters/created-file.js

@@ -0,0 +1,41 @@
+'use strict';
+
+// Shared by the adapters whose instruction file (and opencode.json) is a file DoFlow may have
+// created: the ledger row records `origin: { created: 'file' }` when the file was absent before the
+// install, so a removal that leaves nothing but whitespace can delete exactly the files DoFlow made
+// and keep every file that existed beforehand. Same record Pi's mcp.json rows carry (pi/mcp.ts).
+const fs = require('node:fs');
+
+/** Whitespace is not content: a file holding only whitespace carries none of the user's text. */
+function isBlank(text     )          { return typeof text === 'string' && text.trim() === ''; }
+
+function ownedRow(ledger     , harness        , ownershipIdentity        , target        )      {
+  return (ledger?.resources || []).find((row     ) => row.harness === harness
+    && row.ownershipIdentity === ownershipIdentity && row.target === target);
+}
+
+/** Whether the ledger row for `ownershipIdentity` at `target` says DoFlow created that file. */
+function createdByDoFlow(ledger     , harness        , ownershipIdentity        , target        )          {
+  return ownedRow(ledger, harness, ownershipIdentity, target)?.origin?.created === 'file';
+}
+
+/** The origin to record on the row verify emits. A row already in the ledger passes its origin on
+ * (absent for rows an older version wrote, which are never guessed at). With no row, `before` is
+ * the file as plan read it: `null` means absent, so this install creates it. `undefined` means the
+ * caller has no pre-apply read (a status verify), and nothing is recorded. */
+function creationOrigin({ ledger, harness, ownershipIdentity, target, before }     )                                  {
+  const row = ownedRow(ledger, harness, ownershipIdentity, target);
+  if (row) return row.origin;
+  return before === null ? { created: 'file' } : undefined;
+}
+
+/** Delete `target` unless it is a symlink (the link is the user's, not DoFlow's). */
+function removeCreatedFile(target        , fsImpl      = fs)          {
+  try {
+    if (fsImpl.lstatSync(target).isSymbolicLink()) return false;
+    fsImpl.rmSync(target);
+    return true;
+  } catch { return false; }
+}
+
+module.exports = { isBlank, createdByDoFlow, creationOrigin, removeCreatedFile };

package/src/adapters/mcp-entries.js

@@ -281,15 +281,25 @@ function writePath(file        , fsImpl     )         {
   try { return fsImpl.realpathSync(file); } catch { return path.resolve(path.dirname(file), fsImpl.readlinkSync(file)); }
 }
 
+/** The indent the file already uses (its first indented line, tabs included), else two spaces. */
+function indentOf(file        , fsImpl     )         {
+  try {
+    const found = /^\s*[{[][ \t]*\r?\n([ \t]+)\S/.exec(fsImpl.readFileSync(file, 'utf8'));
+    if (found) return found[1].slice(0, 10);
+  } catch { /* absent or unreadable: the default */ }
+  return '  ';
+}
+
 /** Write a JSON document atomically, keeping the existing file's permission bits: an MCP file kept
  * private for its tokens stays so. Creates missing directories; never deletes a file. */
 function writeMcpJson(file        , doc     , { fsImpl = fs }                   = {})         {
   const dest = writePath(file, fsImpl);
   fsImpl.mkdirSync(path.dirname(dest), { recursive: true });
   const mode = fsImpl.existsSync(dest) ? fsImpl.statSync(dest).mode & 0o7777 : null;
+  const indent = indentOf(dest, fsImpl);
   const temp = path.join(path.dirname(dest), `.${path.basename(dest)}.${process.pid}.${Date.now()}.tmp`);
   try {
-    fsImpl.writeFileSync(temp, `${JSON.stringify(doc, null, 2)}\n`, { encoding: 'utf8', flag: 'wx', ...(mode === null ? {} : { mode }) });
+    fsImpl.writeFileSync(temp, `${JSON.stringify(doc, null, indent)}\n`, { encoding: 'utf8', flag: 'wx', ...(mode === null ? {} : { mode }) });
     if (mode !== null) fsImpl.chmodSync(temp, mode);
     fsImpl.renameSync(temp, dest);
   } finally {

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/status.js

@@ -136,7 +136,7 @@ function cmdStatus(o     )       {
     if (line) console.log(line);
     if (status.errors.length) console.log(`  ${`${label} issues:`.padEnd(24)}${status.errors.join('; ')}`);
     if (harness === 'codex') {
-      console.log('  Codex capability gaps: no Claude-only event emulation is installed; review docs/capability-map.md#codex-capability-detail');
+      console.log('  Codex capability gaps: no Claude-only event emulation is installed');
     }
   }
   if (ctx.registry) {

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,