@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.3

package/src/adapters/pi/mcp.ts

@@ -0,0 +1,373 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+// Pi MCP projection: DoFlow's stdio servers merged per server into the mcpServers map of Pi's
+// mcp.json. Ownership is one ledger row per server and file, whose fingerprint is the entry value
+// DoFlow last verified there. A same-named entry DoFlow holds no row for is the user's and is never
+// touched; an owned entry whose value no longer matches its row was edited by the user and is
+// released, not overwritten or removed. The file itself is edited by splicing members into its
+// original text (./json-members.ts), so every byte DoFlow does not own survives.
+//
+// Plan changes carry DoFlow's own entry and a hash of the text plan read, never the file's text:
+// the lifecycle copies every change into the recovery record, and a user's mcp.json may hold secrets.
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const { fingerprint } = require('../copy-tree.ts');
+const { SKELETON, readDocument, insertMember, replaceValue, removeMember, replaceInner, renderNewDocument } = require('./json-members.ts');
+
+const HARNESS = 'pi';
+const ASSET_ID = 'guidance.codex-pointer';
+const RENDERER = 'pi-mcp';
+const SERVER_NAME = /^[A-Za-z0-9_-]+$/;
+const ABSENT_DOCUMENT = Object.freeze({ ok: true, root: null, servers: null });
+
+const NOTICES = Object.freeze({
+  surface: 'MCP: stdio servers are registered in the mcpServers map of Pi\'s mcp.json for its built-in MCP (Pi 0.99.0 or later; a project entry replaces a user entry of the same name).',
+  extension: 'MCP: an installed extension that registers /mcp, such as pi-mcp-adapter, replaces Pi\'s built-in MCP, and Pi then does not read mcp.json.',
+  trust: 'MCP: Pi reads .pi/mcp.json only after this project is trusted (/trust or --approve); DoFlow does not grant trust.',
+});
+
+function sha256(text: any): string { return crypto.createHash('sha256').update(text).digest('hex'); }
+
+function shorten(name: string): string { return name.length > 40 ? `${name.slice(0, 37)}...` : name; }
+
+function collisionNotice(key: string, id: string): string {
+  return `MCP: kept your own entry '${shorten(key)}' and did not register DoFlow's '${shorten(id)}'; rename or remove yours to let DoFlow manage it.`;
+}
+
+function releasedNotice(id: string): string {
+  return `MCP: entry '${shorten(id)}' was changed outside DoFlow; it is yours now and DoFlow no longer updates or removes it.`;
+}
+
+/** Pi treats two server names that differ only in `-` versus `_` as one server. */
+function piServerKey(name: string): string { return name.replace(/_/g, '-'); }
+
+function refusalFor(file: string, reason: string): string { return `Pi MCP: ${file}: ${reason}; DoFlow did not change the file`; }
+
+function untouchedNotice(file: string): string {
+  const shown = file.length > 80 ? `...${file.slice(-77)}` : file;
+  return `MCP: left ${shown} untouched because it cannot be edited safely; DoFlow no longer manages the entries in it.`;
+}
+
+/** DoFlow's entry for one catalog server, or the reason Pi cannot take it. */
+function renderPiEntry(server: any): any {
+  if (server.transport !== 'stdio' || typeof server.command !== 'string' || !server.command) {
+    return { refusal: `Pi MCP: server '${server.id}' is not a stdio server; DoFlow writes only stdio entries for Pi` };
+  }
+  if (typeof server.id !== 'string' || !SERVER_NAME.test(server.id)) {
+    return { refusal: `Pi MCP: server id '${server.id}' is not a valid Pi server name` };
+  }
+  const entry: any = { command: server.command };
+  if (Array.isArray(server.args) && server.args.length) entry.args = [...server.args];
+  if (server.env && typeof server.env === 'object' && Object.keys(server.env).length) entry.env = { ...server.env };
+  return { entry };
+}
+
+function mcpRows(ledger: any): any[] {
+  return (ledger?.resources || []).filter((row: any) => row.harness === HARNESS && row.kind === 'mcp-server');
+}
+
+function readSnapshotFile(file: string, fsImpl: any): any {
+  if (!fsImpl.existsSync(file)) return { exists: false, text: '', hash: sha256(''), doc: ABSENT_DOCUMENT };
+  const bytes = fsImpl.readFileSync(file);
+  const text = bytes.toString('utf8');
+  // A splice writes the decoded text back, so bytes that do not survive a UTF-8 round trip would be
+  // rewritten; such a file is refused like any other one DoFlow cannot edit safely.
+  const doc = Buffer.from(text, 'utf8').equals(bytes) ? readDocument(text) : { ok: false, reason: 'file is not valid UTF-8' };
+  return { exists: true, text, hash: sha256(bytes), doc };
+}
+
+/** Read the selected server file and every file a ledger row names. Nothing is read when there is
+ * neither a selection nor a row, so a run with no Pi MCP work touches no MCP file. */
+function discoverPiMcp({ selected = [], rows = [], file, fsImpl = fs }: any): any {
+  const files = new Set<string>(rows.map((row: any) => row.target));
+  if (selected.length) files.add(file);
+  return Object.fromEntries([...files].map((target) => [target, readSnapshotFile(target, fsImpl)]));
+}
+
+function memberOf(doc: any, key: string): any { return doc.servers?.members.find((member: any) => member.key === key) ?? null; }
+
+/** The servers DoFlow owns in Pi's mcp.json now: rows whose entry still holds the value they record. */
+function ownedPiMcpIds({ rows = [], snapshot = {} }: any): string[] {
+  const owned = rows.filter((row: any) => {
+    const doc = snapshot[row.target]?.doc;
+    const member = doc?.ok ? memberOf(doc, row.identity) : null;
+    return member !== null && fingerprint(member.value) === row.fingerprint;
+  });
+  return [...new Set<string>(owned.map((row: any) => row.identity))];
+}
+
+function twinOf(doc: any, key: string): any {
+  return doc.servers?.members.find((member: any) => member.key !== key && piServerKey(member.key) === piServerKey(key)) ?? null;
+}
+
+function sameValue(a: any, b: any): boolean { return JSON.stringify(a) === JSON.stringify(b); }
+
+function baseChange({ target, operation, id, snapshot }: any): any {
+  return {
+    assetId: ASSET_ID, target, operation,
+    ownershipIdentity: `doflow:${HARNESS}:mcp-server:${id}`,
+    kind: 'mcp-server', identity: id, baseHash: snapshot[target]?.hash ?? sha256(''),
+    sourceVersion: 'registry-v1', projection: { renderer: RENDERER },
+  };
+}
+
+function writeChange({ target, operation, id, entry, snapshot }: any): any {
+  return { ...baseChange({ target, operation, id, snapshot }), entry, fingerprint: fingerprint(entry), afterFingerprint: fingerprint(entry) };
+}
+
+function releaseChange({ row, snapshot }: any): any {
+  const id = row.identity;
+  return { ...baseChange({ target: row.target, operation: 'remove', id, snapshot }), release: true, fingerprint: row.fingerprint };
+}
+
+function planPiMcp({ selected = [], rows = [], file, scope, removing = false, snapshot = {}, assets = [] }: any): any {
+  const changes: any[] = [];
+  const conflicts: string[] = [];
+  const notices: string[] = [];
+  if (!removing && !selected.length && !rows.length) return { changes, conflicts, notices };
+  if (removing && !rows.length) return { changes, conflicts, notices };
+  if (!assets.some((asset: any) => asset.id === ASSET_ID)) {
+    return { changes, conflicts: [`Pi MCP needs the ${ASSET_ID} asset to record ownership`], notices };
+  }
+
+  // An install or update refuses a file it cannot edit; a removal must still uninstall everything
+  // else, so it releases the rows for that file and leaves the file as it is.
+  const refused = new Set<string>();
+  for (const [target, entry] of Object.entries(snapshot) as [string, any][]) {
+    if (entry.doc.ok) continue;
+    refused.add(target);
+    if (removing) notices.push(untouchedNotice(target));
+    else conflicts.push(refusalFor(target, entry.doc.reason));
+  }
+
+  const matched = new Set<any>();
+  if (!removing) {
+    if (selected.length) {
+      notices.push(NOTICES.surface, NOTICES.extension);
+      if (scope === 'project') notices.push(NOTICES.trust);
+    }
+    const doc = snapshot[file]?.doc ?? ABSENT_DOCUMENT;
+    for (const server of selected) {
+      const { entry: desired, refusal } = renderPiEntry(server);
+      if (refusal) { conflicts.push(refusal); continue; }
+      const row = rows.find((item: any) => item.identity === server.id && item.target === file);
+      if (row) matched.add(row);
+      const member = memberOf(doc, server.id);
+      const twin = twinOf(doc, server.id);
+      if (row && member) {
+        if (fingerprint(member.value) !== row.fingerprint) {
+          changes.push(releaseChange({ row, snapshot }));
+          notices.push(releasedNotice(server.id));
+        } else if (!sameValue(member.value, desired)) {
+          changes.push(writeChange({ target: file, operation: 'update', id: server.id, entry: desired, snapshot }));
+        }
+      } else if (member || twin) {
+        // The user's entry holds the name. An owned row whose own entry is gone is released with it,
+        // because re-creating DoFlow's entry beside the user's twin would give Pi two of one server.
+        if (row) changes.push(releaseChange({ row, snapshot }));
+        notices.push(collisionNotice((member ?? twin).key, server.id));
+      } else {
+        changes.push(writeChange({ target: file, operation: 'create', id: server.id, entry: desired, snapshot }));
+      }
+    }
+  }
+
+  for (const row of rows) {
+    if (matched.has(row)) continue;
+    const id = row.identity;
+    const member = memberOf(snapshot[row.target]?.doc ?? ABSENT_DOCUMENT, id);
+    if (member && fingerprint(member.value) === row.fingerprint) {
+      changes.push({ ...baseChange({ target: row.target, operation: 'remove', id, snapshot }), fingerprint: row.fingerprint,
+        ...(row.origin ? { origin: row.origin } : {}) });
+    } else {
+      changes.push(releaseChange({ row, snapshot }));
+      if (member) notices.push(releasedNotice(id));
+    }
+  }
+
+  return { changes: changes.filter((change: any) => !refused.has(change.target) || (removing && change.release)), conflicts, notices };
+}
+
+function isSymlink(file: string, fsImpl: any): boolean {
+  try { return fsImpl.lstatSync(file).isSymbolicLink(); } catch { return false; }
+}
+
+/** Where a write to `file` lands: a symlinked mcp.json is written through to the file it points at,
+ * so the link stays a link and its target receives the entries. */
+function writePath(file: string, fsImpl: any): string {
+  if (!isSymlink(file, fsImpl)) return file;
+  try { return fsImpl.realpathSync(file); } catch { return path.resolve(path.dirname(file), fsImpl.readlinkSync(file)); }
+}
+
+function atomicWrite(file: string, content: string, fsImpl: any): void {
+  const dest = writePath(file, fsImpl);
+  fsImpl.mkdirSync(path.dirname(dest), { recursive: true });
+  // The rename gives the file the temp file's mode; an mcp.json kept private for its tokens stays so.
+  const mode = fsImpl.existsSync(dest) ? fsImpl.statSync(dest).mode & 0o7777 : null;
+  const temp = path.join(path.dirname(dest), `.${path.basename(dest)}.${process.pid}.${Date.now()}.tmp`);
+  try {
+    fsImpl.writeFileSync(temp, content, { encoding: 'utf8', flag: 'wx', ...(mode === null ? {} : { mode }) });
+    if (mode !== null) fsImpl.chmodSync(temp, mode);
+    fsImpl.renameSync(temp, dest);
+  } finally {
+    if (fsImpl.existsSync(temp)) fsImpl.rmSync(temp, { force: true });
+  }
+}
+
+/** Replay one file's edits against the text read now, each against a fresh parse of the last result. */
+function editedText(text: string, group: any[]): string {
+  const parse = (current: string) => {
+    const doc = readDocument(current);
+    if (!doc.ok) throw new Error(`Pi MCP: cannot edit the planned file: ${doc.reason}`);
+    return doc;
+  };
+  let next = text;
+  for (const change of group.filter((item: any) => item.operation === 'remove')) {
+    const doc = parse(next);
+    const member = memberOf(doc, change.identity);
+    if (member) next = removeMember(next, doc.servers, member);
+  }
+  for (const change of group.filter((item: any) => item.operation === 'update')) {
+    const doc = parse(next);
+    const member = memberOf(doc, change.identity);
+    if (member) next = replaceValue(next, member, change.entry, doc);
+  }
+  const creates = group.filter((item: any) => item.operation === 'create');
+  for (const [index, change] of creates.entries()) {
+    const doc = parse(next);
+    if (!doc.servers) {
+      const entries = Object.fromEntries(creates.slice(index).map((item: any) => [item.identity, item.entry]));
+      return insertMember(next, doc.root, 'mcpServers', entries, doc);
+    }
+    next = insertMember(next, doc.servers, change.identity, change.entry, doc);
+  }
+  return next;
+}
+
+/** Undo what DoFlow added around its entries once the last of them is gone: the mcpServers member
+ * it inserted, or the inner whitespace of the container it first wrote into. `origin` is recorded
+ * on the ledger rows (see originFor); without it the emptied container is left as it is. */
+function restoredText(text: string, origin: any): string {
+  const doc = readDocument(text);
+  if (!doc.ok || !doc.servers || doc.servers.members.length) return text;
+  if (origin.created === 'member') return replaceInner(text, doc.servers, origin.inner);
+  const next = removeMember(text, doc.root, doc.root.members.find((member: any) => member.key === 'mcpServers'));
+  if (origin.inner === undefined) return next;
+  const after = readDocument(next);
+  return after.root.members.length ? next : replaceInner(next, after.root, origin.inner);
+}
+
+function applyPiMcp(changes: any[], { fsImpl = fs }: { fsImpl?: any } = {}): { applied: number } {
+  const groups = new Map<string, any[]>();
+  for (const change of changes) {
+    if (!groups.has(change.target)) groups.set(change.target, []);
+    groups.get(change.target)!.push(change);
+  }
+  let applied = 0;
+  for (const [target, all] of groups) {
+    const group = all.filter((change: any) => !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: any) => change.operation === 'create');
+    const origin = group.find((change: any) => change.origin)?.origin;
+    let next = exists ? editedText(text, group) : renderNewDocument(creates.map((change: any) => [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;
+    }
+  }
+  return { applied };
+}
+
+function statusFor({ id, target, status }: { id: string, target: string, status: string }): any {
+  return { harness: HARNESS, assetId: ASSET_ID, capability: 'mcp', identity: id, target,
+    ownershipIdentity: `doflow:${HARNESS}:mcp-server:${id}`, status };
+}
+
+function resourceFor({ id, target, value, origin }: { id: string, target: string, value: any, origin?: any }): any {
+  return { assetId: ASSET_ID, target, ownershipIdentity: `doflow:${HARNESS}:mcp-server:${id}`, kind: 'mcp-server', identity: id,
+    fingerprint: fingerprint(value), sourceVersion: 'registry-v1', projection: { renderer: RENDERER }, ...(origin ? { origin } : {}) };
+}
+
+/** What DoFlow added to `target` besides its entries, so a later removal can take it out again:
+ * the whole file, the mcpServers member, or the first member of an empty mcpServers (with the
+ * container's original inner whitespace). A row already carrying it passes it on; otherwise it is
+ * read from the file as plan saw it. Only whitespace is recorded, never file content. */
+function originFor(target: string, rows: any[], snapshot: any): any {
+  const carried = rows.find((row: any) => row.target === target && row.origin)?.origin;
+  if (carried) return carried;
+  const before = snapshot[target];
+  if (!before) return undefined;
+  if (!before.exists) return { created: 'file' };
+  const { doc, text } = before;
+  if (!doc.ok) return undefined;
+  const inner = (node: any) => text.slice(node.open + 1, node.close);
+  if (!doc.servers) return doc.root.members.length ? { created: 'key' } : { created: 'key', inner: inner(doc.root) };
+  return doc.servers.members.length ? undefined : { created: 'member', inner: inner(doc.servers) };
+}
+
+/** Statuses and ledger resources for the Pi MCP entries. `snapshot` is what plan read before apply:
+ * an entry it held that DoFlow did not own then, or held with a value its row no longer matched, is
+ * the user's, whatever it holds now. */
+function verifyPiMcp({ selected = [], rows = [], file, snapshot = {}, removing = false, fsImpl = fs }: any): any {
+  const statuses: any[] = [];
+  const resources: any[] = [];
+  const conflicts: string[] = [];
+  const current: Record<string, any> = {};
+  for (const target of new Set<string>([...(selected.length ? [file] : []), ...rows.map((row: any) => row.target)])) {
+    current[target] = readSnapshotFile(target, fsImpl).doc;
+    if (!current[target].ok && !removing) conflicts.push(refusalFor(target, current[target].reason));
+  }
+  const memberNow = (target: string, id: string) => (current[target]?.ok ? memberOf(current[target], id) : null);
+  const foreign = (target: string, id: string) => {
+    const before = snapshot[target]?.doc;
+    if (!before?.ok) return false;
+    const row = rows.find((item: any) => item.identity === id && item.target === target);
+    const member = memberOf(before, id);
+    if (!member) return Boolean(twinOf(before, id));
+    return !row || fingerprint(member.value) !== row.fingerprint;
+  };
+
+  const verified = new Set<string>();
+  if (!removing) {
+    for (const server of selected) {
+      const { entry: desired } = renderPiEntry(server);
+      if (!desired) continue;
+      verified.add(`${file}\u0000${server.id}`);
+      const member = memberNow(file, server.id);
+      if (foreign(file, server.id)) statuses.push(statusFor({ id: server.id, target: file, status: 'not-managed' }));
+      else if (member && sameValue(member.value, desired)) {
+        statuses.push(statusFor({ id: server.id, target: file, status: 'managed' }));
+        resources.push(resourceFor({ id: server.id, target: file, value: member.value, origin: originFor(file, rows, snapshot) }));
+      } else statuses.push(statusFor({ id: server.id, target: file, status: 'missing' }));
+    }
+  }
+
+  for (const row of rows) {
+    const id = row.identity;
+    if (verified.has(`${row.target}\u0000${id}`)) continue;
+    const member = memberNow(row.target, id);
+    let status: string;
+    if (!current[row.target].ok) status = 'not-managed';
+    else if (!member) status = 'absent';
+    else if (foreign(row.target, id) || fingerprint(member.value) !== row.fingerprint) status = 'not-managed';
+    else status = 'retained';
+    statuses.push(statusFor({ id, target: row.target, status }));
+    if (status === 'managed') resources.push(resourceFor({ id, target: row.target, value: member.value, origin: originFor(row.target, rows, snapshot) }));
+  }
+  return { statuses, resources, conflicts };
+}
+
+module.exports = { NOTICES, renderPiEntry, piServerKey, mcpRows, discoverPiMcp, ownedPiMcpIds, planPiMcp, applyPiMcp, verifyPiMcp };

package/src/adapters/resolve-source.ts

@@ -0,0 +1,19 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const path = require('node:path');
+
+/** Resolve a registry-declared source path against the repo root, refusing escapes. Shared by the
+ * common projection module and by per-adapter native-projection normalizers, which is why it lives
+ * in its own module rather than in index.js — a normalizer importing index.js would be a cycle. */
+function resolveRegistrySource(registry: any, source: any, label: string): string {
+  if (typeof registry.repoRoot !== 'string' || !registry.repoRoot) throw new Error(`Registry repoRoot is required for ${label}`);
+  if (typeof source !== 'string' || !source) throw new Error(`Registry ${label} source is required`);
+  const root = path.resolve(registry.repoRoot);
+  const resolved = path.resolve(root, source);
+  if (!resolved.startsWith(`${root}${path.sep}`)) throw new Error(`Registry ${label} source escapes repository: ${source}`);
+  return resolved;
+}
+
+module.exports = { resolveRegistrySource };

package/src/cli/commands/install.ts

@@ -0,0 +1,218 @@
+'use strict';
+// `doflow install` — plan the full lifecycle across the requested targets, back up, apply, and
+// pin what was chosen in doflow.lock. Supports --dry-run previews and MCP selection.
+// 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.ts');
+const { resolveContext, printContext } = require('../../install/context.ts');
+const {
+  BackupError, DEFAULT_BACKUP_RETENTION, createFileBackup, applyRetention, formatBytes, retentionNote,
+} = require('../../install/backup.ts');
+const { backupSetFromPlan } = require('../../install/backup-set.ts');
+const { ledgerPath } = require('../../state/index.ts');
+const { writeManifest, readInstallManifest } = require('../../install/manifest.ts');
+const { confirm } = require('../../helper/prompt.ts');
+const { sourceCommit } = require('../../helper/git.ts');
+const { chmodHooksExecutable } = require('../../helper/settings-scope.ts');
+const { promptMcpCheckbox, resolveMcpSelections } = require('../../install/mcp.ts');
+const { loadRegistry } = require('../../registry/index.ts');
+const { storageAfterInstall } = require('../../runtime/storage/upkeep.ts');
+const { applyLifecycle, applyMcpIndex, recordMcpOwnership } = require('../../lifecycle/index.ts');
+const {
+  codexScope, registryLifecycleView, printRegistryLifecycle, printPlanNotices, assertSafeRegistryPlan,
+  lockDocument, recordLock,
+} = require('../../lifecycle/view.ts');
+const {
+  REPO_ROOT, SCRIPT_DIR, pkg, scopeOf, installPaths, reportRetiredMcp, scopeSelectionState, printMcpSelection, plannedMcpSelections,
+  printRecordedMcpOwnership, buildAdapterRegistry, refuseHomeRootedProject, holdRunLock, checkpointRunLock,
+} = require('../shared.ts');
+
+function cmdInstall(o: any): void {
+  refuseHomeRootedProject(o, 'install');
+  const targets = resolveTargets(o.targets);
+  const scope = scopeOf(o);
+  const hold = holdRunLock(o, scope, 'install');
+  try {
+    const dirs = toolDirs(scope);
+    const lifecyclePaths = installPaths(scope);
+    const backupRoot = lifecyclePaths.backupRoot;
+    // Resolved once per invocation and threaded into resolveContext/createFileBackup/writeManifest below
+    // — those three used to each spawn their own `git rev-parse` for the identical value.
+    const commit = sourceCommit(SCRIPT_DIR);
+
+    printContext(resolveContext({ repoRoot: REPO_ROOT, targets, dirs, sourceCommit: commit, ...scope }));
+
+    const registry = loadRegistry({ repoRoot: REPO_ROOT });
+    const existingManifest = readInstallManifest({ scopeRoot: lifecyclePaths.scopeRoot });
+    const { lock, ledger } = scopeSelectionState(scope);
+    // Each MCP-capable target gets its own selection; a real terminal is asked once for all of them.
+    const selection = resolveMcpSelections({
+      cmd: 'install', requested: o.mcp, targets, registry, lock, ledger, manifestServers: existingManifest?.mcpServers ?? null,
+      interactive: !o.dryRun && !o.force && Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY),
+      promptFn: promptMcpCheckbox, onStale: reportRetiredMcp,
+    });
+    // One lifecycle view across every requested target — computed unconditionally (not only under
+    // --dry-run) so its safety gate and its plan are the exact same object the real apply below uses.
+    const lifecycleView = registryLifecycleView({ registry, repoRoot: REPO_ROOT, scope, dirs, targets,
+      mcpSelections: selection.selections, mcpAdoptable: selection.adoptable, retainedMcpIds: selection.retainedMcpIds,
+      force: o.force, adopt: o.adopt === true, permissions: o.permissions === true, statusline: o.statusline === true });
+    if (!lifecycleView.plan.safe) { assertSafeRegistryPlan(lifecycleView); return; }
+
+    printMcpSelection(lifecycleView, selection.sources, { requested: o.mcp, prefix: o.dryRun ? '[DRY]' : '[INFO]' });
+    // Safe-by-default surfaced, not silent: a first-ever non-interactive install selects zero MCP
+    // servers. Anyone scripting installs must opt in explicitly; interactive users never see this
+    // because the checkbox is the discovery path.
+    if (!o.mcp && !o.dryRun && !process.stdin.isTTY && Object.values(selection.sources).includes('default')) {
+      console.log('[INFO] MCP: none selected by default in non-interactive mode — pass --mcp all or --mcp <names> to include servers.');
+    }
+
+    // The files this run's apply can overwrite or delete; DoFlow's own records are never among them.
+    const buildBackupSet = () => backupSetFromPlan({
+      plan: lifecycleView.plan, scope: scope.global ? 'global' : 'project', scopeRoot: lifecyclePaths.scopeRoot,
+      exclude: [backupRoot, lifecycleView.stateRoot, lifecyclePaths.manifestPath, path.join(lifecyclePaths.doflowRoot, 'doflow.lock')],
+      // The ownership ledger, and nothing else from the state root (runs, evidence and recovery
+      // records written after the backup must survive a rollback): a rollback then restores the
+      // rows that describe the files it restores.
+      records: [ledgerPath(lifecycleView.stateRoot)],
+    });
+    const keep = o.prune ?? DEFAULT_BACKUP_RETENTION;
+
+    if (o.dryRun) {
+      console.log(`[INFO] Install targets: ${targets.join(' ')}`);
+      printRegistryLifecycle(lifecycleView, '[DRY]');
+      const set = o.noBackup ? null : backupStep(buildBackupSet);
+      if (set) printBackupDryRun(set, `${backupRoot}/install_<timestamp>`);
+      const retention = applyRetention({ backupRoot, keep, dryRun: true, reserve: set?.count ? 1 : 0 });
+      console.log(`[DRY]  Backups: would keep ${retention.kept}, would remove ${retention.wouldRemove.length} (${retentionNote(o.prune, keep)})`);
+      console.log(`[DRY]  Would write manifest: ${lifecyclePaths.manifestPath}`);
+      console.log('[DRY] Dry run complete — no changes written');
+      return;
+    }
+
+    if (!confirm(`Install configs to: ${targets.join(' ')}?`, o.force)) {
+      // Exit 1, not 0: a declined prompt is a decision, and it must not share an exit code with a
+      // completed run. With no stdin the prompt auto-declines, so `doflow install <path>` in a script
+      // or CI step printed "Aborted.", wrote zero files, and reported success. It also silently
+      // corrupted a set of install-timing measurements during the D.4 sweep, which is how it surfaced.
+      console.error('[INFO]  Aborted.');
+      process.exit(1);
+    }
+    checkpointRunLock(hold);
+
+    let bid = '';
+    if (!o.noBackup) {
+      const backup = backupStep(() => createFileBackup({ operation: 'install', set: buildBackupSet(), backupRoot, repoRoot: SCRIPT_DIR,
+        sourceCommit: commit, version: pkg.version, date: new Date() }));
+      bid = reportBackup(backup);
+    } else {
+      console.error('[WARN]  Skipping backup (--no-backup)');
+    }
+
+    // The ledger the lock is pinned against: the one this run leaves.
+    let ledgerAfter = lifecycleView.ledger;
+    if (lifecycleView.plan.changes.length) {
+      const result = applyLifecycle({ plan: lifecycleView.plan, registry: lifecycleView.registry,
+        adapters: buildAdapterRegistry(),
+        stateRoot: lifecycleView.stateRoot, ledger: lifecycleView.ledger });
+      for (const target of lifecycleView.plan.targets) {
+        if (target.skipped || !target.changes.length) continue;
+        const owned = result.ledger.resources.filter((resource: any) => resource.harness === target.harness).length;
+        console.log(`[INFO] ${target.harness}: lifecycle verified (${owned} owned resource(s))`);
+      }
+      ledgerAfter = result.ledger;
+    } else {
+      // MCP_INDEX.md is generated, not a tracked resource, so it never appears in plan.changes and
+      // applyLifecycle — which owns the only call that writes it — is skipped entirely when nothing
+      // else changed. Without this branch the index is rewritten only as a side effect of some
+      // unrelated asset changing, so a change to the renderer, to a server's `doc`/`shortFlag`, or
+      // to the resolved selection silently does nothing whenever the rest of the tree is current.
+      applyMcpIndex({ scopeRoot: lifecycleView.plan.scopeRoot, selectedMcp: lifecycleView.plan.mcp, mode: 'apply' });
+      const owned = recordMcpOwnership({ plan: lifecycleView.plan, registry: lifecycleView.registry, adapters: lifecycleView.adapters,
+        stateRoot: lifecycleView.stateRoot, ledger: lifecycleView.ledger });
+      printRecordedMcpOwnership(owned.recorded);
+      ledgerAfter = owned.ledger;
+    }
+    printPlanNotices(lifecycleView);
+
+    if (targets.includes('claude')) {
+      // A npm-packaged tarball does not reliably preserve the executable bit on arbitrary files
+      // (unlike git checkouts, which usually do) — copy-tree's mode-preserving copy only carries
+      // over whatever bit the source file actually has on this machine, so this runs after
+      // applyLifecycle (once the hook scripts are actually on disk) as a final, unconditional +x.
+      chmodHooksExecutable(dirs.claude);
+    }
+
+    writeManifest({ scopeRoot: lifecyclePaths.scopeRoot, scriptVersion: pkg.version, operation: 'install', repoRoot: SCRIPT_DIR, sourceCommit: commit, backupId: bid, tools: targets, date: new Date() });
+
+    // Pin what this install CHOSE, beside what earlier runs pinned. The ledger owns ownership; the
+    // lock owns selection — together they make the next update's delta a reviewable fact instead of a
+    // surprise.
+    const lockResult = recordLock(
+      scope.global ? { scope: 'global', homeDir: os.homedir() } : { scope: 'project', projectRoot: path.resolve(scope.projectRoot) },
+      lockDocument({
+        registry, scope: codexScope(scope), scopeRoot: scope.global ? os.homedir() : path.resolve(scope.projectRoot),
+        previous: lock, ledger: ledgerAfter, plannedTargets: targets, mcpSelections: plannedMcpSelections(lifecycleView),
+      }),
+    );
+    console.log(`[INFO] doflow.lock: ${lockResult.summary}`);
+
+    applyBackupRetention({ backupRoot, prune: o.prune, keep, bid });
+    storageAfterInstall({ scope: scope.global ? 'global' : 'project', scopeRoot: scope.global ? os.homedir() : path.resolve(scope.projectRoot) });
+
+    console.log('[OK] Installation complete!');
+  } finally {
+    hold?.release();
+  }
+}
+
+/** Run a backup step; a BackupError stops the command before anything is changed. */
+function backupStep(step: () => any): any {
+  try {
+    return step();
+  } catch (error: any) {
+    if (!(error instanceof BackupError)) throw error;
+    console.error(`[ERROR] Backup failed, nothing was changed: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+/** Print what a backup step wrote and return its id ('' when there was nothing to back up). */
+function reportBackup(backup: any): string {
+  if (!backup) {
+    console.error('[INFO]  Backup: nothing to back up (no file changes)');
+    return '';
+  }
+  console.error(`[INFO]  Backup created: ${backup.id} (${backup.files} file(s), ${formatBytes(backup.bytes)}; ${backup.absent} not present before the run)`);
+  return backup.id;
+}
+
+/** The dry-run backup lines for a set the real run would back up. */
+function printBackupDryRun(set: any, destination: string): void {
+  if (set.count === 0) {
+    console.log('[DRY]  Backup: nothing to back up (no file changes)');
+  } else {
+    console.log(`[DRY]  Would back up ${set.count} file(s), ${formatBytes(set.bytes)} (${set.bytes} bytes; ${set.absent} not present yet) to ${destination}`);
+  }
+  const mcpOnly = set.excluded.filter((item: any) => item.reason === 'mcp-entries-only').length;
+  if (mcpOnly > 0) console.log(`[DRY]  Not backed up: ${mcpOnly} file(s) holding only MCP entries`);
+}
+
+/** Keep the newest backups after a run that changed files; never changes the exit code. */
+function applyBackupRetention({ backupRoot, prune, keep, bid }: any): void {
+  let retention;
+  try {
+    retention = applyRetention({ backupRoot, keep, protect: bid ? [bid] : [] });
+  } catch (error: any) {
+    console.error(`[WARN]  Backups: could not apply retention: ${error.message}`);
+    return;
+  }
+  for (const failure of retention.failed) console.error(`[WARN]  Backups: could not remove ${failure.id}: ${failure.error}`);
+  console.error(`[INFO]  Backups: kept ${retention.kept}, removed ${retention.removed.length} (${retentionNote(prune, keep)})`);
+}
+
+module.exports = cmdInstall;
+module.exports.backupStep = backupStep;
+module.exports.reportBackup = reportBackup;
+module.exports.printBackupDryRun = printBackupDryRun;
+module.exports.applyBackupRetention = applyBackupRetention;

package/src/cli/commands/list-backups.ts

@@ -0,0 +1,21 @@
+'use strict';
+// `doflow list-backups` — the backup table for this scope. Takes no project-path positional
+// (rollback's one positional slot is the backup id); scope is -g/--global vs cwd-rooted project.
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+const { listBackups } = require('../../install/backup.ts');
+const { installPaths, printBackupTable } = require('../shared.ts');
+
+function cmdListBackups(o: any): void {
+  // rollback/list-backups don't take a project-path positional (their one positional slot is the
+  // backup id for rollback) — scope is -g/--global vs default project rooted at cwd.
+  const scope = { global: o.global, projectRoot: '.' };
+  const lifecyclePaths = installPaths(scope);
+  const rows = listBackups(lifecyclePaths.backupRoot);
+  // listBackups now reads the canonical root AND the legacy pre-.doflow one, so the footer must name
+  // the roots the rows actually came from: reporting restore points as living in a directory that
+  // does not exist on this machine sends a user looking for recovery material to the wrong place.
+  const roots = [...new Set(rows.map((r: any) => r.backupRoot))];
+  printBackupTable(rows, roots.length ? roots.join(', ') : lifecyclePaths.backupRoot);
+}
+
+module.exports = cmdListBackups;