@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

package/src/lifecycle/retired-harnesses.js

@@ -0,0 +1,318 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * Retirement sweep (row 127 IC-003, design D2): release, delete or strip what a retired harness
+ * installed, driven only by the scope's ledger and the retired record in the registry. The retired
+ * harness has no adapter any more, so nothing here calls one.
+ *
+ * Every retired row gets exactly one change, first matching rule wins:
+ *  1. a live change in this run removes or supersedes its target      -> drop-row
+ *  2. a non-retired ledger row has the same claim key                  -> release (file stays)
+ *  3. kind copy-tree-file | hooks-script: absent -> drop-row; bytes equal the row's fingerprint and the
+ *     path resolves to itself -> delete; otherwise keep (named)
+ *  3a. a `removal.handover` entry (renderer + scope) at the replacement's own declared path: replacement
+ *     planned in this run -> handover (it rewrites the span itself); installed but not planned -> defer
+ *     (row and file stay, notice); otherwise on to rule 4. Decided by planHandovers before any live plan.
+ *  4. renderer in `markerSectionRenderers` -> strip-section (either start marker, see START_MARKERS); no
+ *     markers -> drop-row; malformed -> keep
+ *  5. renderer = `hookCommands.renderer` -> strip-hooks (exact frozen commands only); unparseable -> keep;
+ *     no matching command -> drop-row
+ *  6. anything else -> keep, `unknown row shape <kind>/<renderer>`
+ * Every action except `defer` gives the row up (retiredReleaseKeys). Actions that touch no file carry
+ * `release: true`, which keeps them out of the backup set like any other release; a handed-over file
+ * is backed up through the replacement's own change, which is the one write it gets.
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { isRetired } = require('../registry/index.js');
+const { resolveHarnessPaths } = require('../helper/harness-paths.js');
+const { ownershipKey, atomicJsonWrite } = require('../state/index.js');
+const { removeTree, readJson } = require('../adapters/copy-tree.js');
+const { removeMarkedSection, markedSpan, MARKER_START } = require('../helper/marker-merge.js');
+
+                                                                                                                         
+
+                         
+                                                                                                                   
+                                                                                 
+                                                                                
+                       
+                                                                            
+                                                     
+ 
+
+                              
+                                                                                    
+                                                                                                                   
+                    
+ 
+
+                                                                                         
+
+const WHOLE_FILE_KINDS = new Set(['copy-tree-file', 'hooks-script']);
+/** Actions with no filesystem effect: the row is given up and nothing is written or deleted. */
+const NO_FS_EFFECT = new Set               (['release', 'handover', 'defer', 'drop-row', 'keep']);
+/** The count each action adds to; every action has one, so the counts sum to the rows swept. */
+const COUNTED                                                            = {
+  delete: 'deleted', 'strip-section': 'stripped', 'strip-hooks': 'stripped', release: 'released', handover: 'released',
+  'drop-row': 'dropped', defer: 'deferred', keep: 'kept',
+};
+
+/** What one claim covers: a whole file, except an MCP entry, which is claimed on its own because
+ * several harnesses keep their servers side by side in one MCP file. The one definition: the
+ * lifecycle (src/lifecycle/index.js) imports it from here, since it requires this module. */
+function claimKey(record     )         {
+  return record.kind === 'mcp-server' ? `${record.target}\u0000${record.identity}` : record.target;
+}
+
+function sha256(bytes     )         { return crypto.createHash('sha256').update(bytes).digest('hex'); }
+
+/** Whether `target` is inside `scopeRoot` and resolves to that same place: no symlink between the
+ * scope root and the file (the file itself included) leads somewhere else. */
+function resolvesInPlace(target        , scopeRoot        , fsImpl     )          {
+  const rel = path.relative(scopeRoot, target);
+  if (!rel || rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) return false;
+  try { return fsImpl.realpathSync(target) === path.join(fsImpl.realpathSync(scopeRoot), rel); } catch { return false; }
+}
+
+/** The `hooks` value with every handler whose command is in `commands` taken out, and any matcher
+ * group, event array or the key itself that this left empty. Containers that were already empty,
+ * and every handler not in the list, stay as they are. Returns the new document, or null when no
+ * handler matched. */
+function stripHookCommands(doc     , key        , commands             )             {
+  const hooks = doc[key];
+  let removed = false;
+  const nextHooks                      = {};
+  for (const [event, groups] of Object.entries(hooks)) {
+    if (!Array.isArray(groups)) { nextHooks[event] = groups; continue; }
+    let eventChanged = false;
+    const nextGroups        = [];
+    for (const group of groups) {
+      if (!group || !Array.isArray(group.hooks)) { nextGroups.push(group); continue; }
+      const handlers = group.hooks.filter((handler     ) => !commands.has(handler?.command));
+      if (handlers.length === group.hooks.length) { nextGroups.push(group); continue; }
+      eventChanged = true;
+      if (handlers.length) nextGroups.push({ ...group, hooks: handlers });
+    }
+    if (eventChanged) removed = true;
+    if (!eventChanged || nextGroups.length) nextHooks[event] = eventChanged ? nextGroups : groups;
+  }
+  if (!removed) return null;
+  const next = { ...doc };
+  if (Object.keys(nextHooks).length) next[key] = nextHooks;
+  else delete next[key];
+  return next;
+}
+
+/** The hooks JSON at `target` parsed, or a reason it cannot be stripped. Absent file -> `absent`. */
+function readHooksDoc(target        , key        , fsImpl     )                                               {
+  const { exists, value, error } = readJson(target, { fsImpl });
+  if (!exists) return { absent: true };
+  if (error) return { error: 'not valid JSON' };
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return { error: 'not a JSON object' };
+  if (value[key] !== undefined && (!value[key] || typeof value[key] !== 'object' || Array.isArray(value[key]))) return { error: `'${key}' is not an object` };
+  return { doc: value };
+}
+
+/** The start markers a retired section may open with: marker-merge's, and the short one the retired
+ * gemini adapter wrote (src/adapters/gemini/index.ts @ c35f681b), which its real sections carry. Both
+ * close with MARKER_END. Only this sweep reads the short one; live harnesses never see it. */
+const START_MARKERS = [MARKER_START, '<!-- doflow:start -->'];
+
+/** Marker state of a file, by the rules removeMarkedSection applies with START_MARKERS. */
+function markerState(text        )                              { return markedSpan(text, START_MARKERS).state; }
+
+/** Rule 3a's verdict for one retired row (IC-003, IC-007, design D7). */
+                                                                                                                         
+
+/**
+ * Rule 3a, decided before the live harnesses plan, because the replacement needs the verdict to plan
+ * its own change: `context.handovers` for each `to`. A retired row qualifies when a `removal.handover`
+ * entry names its renderer and this scope, its file is still there in place, and the file is the one
+ * the replacement itself declares for that surface here. Then: `to` planned in this run -> handover,
+ * `edited` when the whole file no longer has the bytes the row recorded; `to` installed in the scope
+ * (a ledger row of it, or its `targets` entry; a lock pins only harnesses the ledger holds, IC-004)
+ * -> defer. Rules 2 and 3 come first, as in classify. Returns the decisions by ownership key.
+ */
+function planHandovers({ registry, ledger, scope, scopeRoot, planned = [], fsImpl = fs }     )                                {
+  const decisions = new Map                          ();
+  const retiredRecords = Array.isArray(registry?.retired) ? registry.retired : [];
+  if (!retiredRecords.length) return decisions;
+  const rows = (ledger?.resources ?? []).filter((row     ) => typeof row?.target === 'string' && typeof row?.harness === 'string');
+  const liveClaims = new Set        (rows.filter((row     ) => !isRetired(registry, row.harness)).map(claimKey));
+  const plannedIds = new Set        (planned);
+  for (const retired of retiredRecords) {
+    const entries = (retired.removal?.handover ?? []).filter((entry     ) => entry?.scope === scope);
+    if (!entries.length) continue;
+    for (const row of rows.filter((item     ) => item.harness === retired.id)) {
+      const entry = entries.find((item     ) => item.renderer === row.projection?.renderer);
+      if (!entry || liveClaims.has(claimKey(row)) || WHOLE_FILE_KINDS.has(row.kind)) continue;
+      const to = registry.harnesses?.find((harness     ) => harness.id === entry.to);
+      if (!to?.paths?.[entry.surface]) continue;
+      let declared                = null;
+      try { declared = resolveHarnessPaths({ [entry.surface]: to.paths[entry.surface] }, { scope, scopeRoot, homeDir: scopeRoot })[entry.surface]; } catch { continue; }
+      if (declared !== row.target || !fsImpl.existsSync(row.target) || !resolvesInPlace(row.target, scopeRoot, fsImpl)) continue;
+      const base = { to: to.id, target: row.target, fromKey: ownershipKey(row) };
+      if (plannedIds.has(to.id)) {
+        decisions.set(base.fromKey, { action: 'handover', ...base, edited: sha256(fsImpl.readFileSync(row.target)) !== row.fingerprint });
+      } else if (rows.some((item     ) => item.harness === to.id) || ledger?.targets?.[to.id]) {
+        decisions.set(base.fromKey, { action: 'defer', ...base, edited: false });
+      }
+    }
+  }
+  return decisions;
+}
+
+/** What the replacement is told about each handover in this run: `context.handovers` per harness id. */
+function handoversFor(decisions                               )                                                                           {
+  const byHarness = new Map                                                                     ();
+  for (const { action, to, target, fromKey, edited } of decisions.values()) {
+    if (action !== 'handover') continue;
+    if (!byHarness.has(to)) byHarness.set(to, []);
+    byHarness.get(to) .push({ target, fromKey, edited });
+  }
+  return byHarness;
+}
+
+/** Rule 3a in classify: the verdict planHandovers reached for this row before the live plans. */
+function handoverAction(row     , _retired     , context     )                        {
+  const decided = context.handovers?.get(ownershipKey(row));
+  return decided ? { action: decided.action } : null;
+}
+
+function classify(row     , retired     , context     )                 {
+  const { liveRemoved, superseded, liveClaims, scopeRoot, fsImpl } = context;
+  const key = claimKey(row);
+  const renderer = row.projection?.renderer;
+  // 1. A live change in this run already releases this row (a removal, or a prune naming it).
+  if (liveRemoved.has(key) || superseded.has(ownershipKey(row))) return { action: 'drop-row' };
+  // 2. A live harness still claims the file.
+  if (liveClaims.has(key)) return { action: 'release' };
+  // 3. Whole files DoFlow wrote: delete only its own unchanged bytes, at the path it recorded.
+  if (WHOLE_FILE_KINDS.has(row.kind)) {
+    if (!fsImpl.existsSync(row.target)) return { action: 'drop-row' };
+    if (!resolvesInPlace(row.target, scopeRoot, fsImpl)) return { action: 'keep', reason: 'resolves outside its recorded path' };
+    if (!fsImpl.statSync(row.target).isFile()) return { action: 'keep', reason: 'not a regular file' };
+    const current = sha256(fsImpl.readFileSync(row.target));
+    if (current !== row.fingerprint) return { action: 'keep', reason: 'changed since DoFlow wrote it' };
+    return { action: 'delete', fingerprint: current };
+  }
+  // 3a. Handover to the replacement (T-127-A5).
+  const handover = handoverAction(row, retired, context);
+  if (handover) return handover;
+  // 4. A marker section in a file the person also writes.
+  if (retired.removal.markerSectionRenderers.includes(renderer)) {
+    if (!fsImpl.existsSync(row.target)) return { action: 'drop-row' };
+    if (!resolvesInPlace(row.target, scopeRoot, fsImpl)) return { action: 'keep', reason: 'resolves outside its recorded path' };
+    const state = markerState(fsImpl.readFileSync(row.target, 'utf8'));
+    if (state === 'none') return { action: 'drop-row' };
+    if (state === 'malformed') return { action: 'keep', reason: 'malformed DoFlow markers' };
+    return { action: 'strip-section' };
+  }
+  // 5. Hook handlers in a shared JSON file: only the exact frozen commands.
+  const hookCommands = retired.removal.hookCommands;
+  if (renderer === hookCommands.renderer) {
+    const read = readHooksDoc(row.target, hookCommands.key, fsImpl);
+    if (read.absent) return { action: 'drop-row' };
+    if (read.error) return { action: 'keep', reason: read.error };
+    if (!resolvesInPlace(row.target, scopeRoot, fsImpl)) return { action: 'keep', reason: 'resolves outside its recorded path' };
+    if (read.doc[hookCommands.key] === undefined) return { action: 'drop-row' };
+    return stripHookCommands(read.doc, hookCommands.key, new Set(hookCommands.commands)) ? { action: 'strip-hooks' } : { action: 'drop-row' };
+  }
+  // 6. Nothing this sweep knows how to take back.
+  return { action: 'keep', reason: `unknown row shape ${row.kind ?? '(none)'}/${renderer ?? '(none)'}` };
+}
+
+/** One plan per retired harness that still has rows in this scope's ledger, in registry order. A ledger
+ * with no retired rows yields []. `livePlanChanges` are the live harnesses' planned changes, and
+ * `handovers` planHandovers' decisions for this same run. */
+function planRetiredHarnesses({ registry, ledger, scope, scopeRoot, livePlanChanges = [], handovers = new Map(), fsImpl = fs }     )                       {
+  const retiredRecords = Array.isArray(registry?.retired) ? registry.retired : [];
+  if (!retiredRecords.length) return [];
+  const rows = (ledger?.resources ?? []).filter((row     ) => typeof row?.target === 'string' && typeof row?.harness === 'string');
+  const liveRemoved = new Set        ();
+  const superseded = new Set        ();
+  for (const change of livePlanChanges) {
+    if (change?.operation !== 'remove' || typeof change.target !== 'string') continue;
+    liveRemoved.add(claimKey(change));
+    for (const key of change.supersedes ?? []) superseded.add(key);
+  }
+  const liveClaims = new Set        (rows.filter((row     ) => !isRetired(registry, row.harness)).map(claimKey));
+  const context = { registry, scope, scopeRoot, livePlanChanges, liveRemoved, superseded, liveClaims, handovers, fsImpl };
+
+  const plans                       = [];
+  for (const retired of retiredRecords) {
+    const own = rows.filter((row     ) => row.harness === retired.id);
+    if (!own.length) continue;
+    const plan                     = {
+      harness: retired.id, replacement: retired.replacement, scopeRoot, changes: [],
+      counts: { deleted: 0, stripped: 0, released: 0, dropped: 0, deferred: 0, kept: 0 }, notices: [],
+    };
+    for (const row of own) {
+      const { action, reason, fingerprint } = classify(row, retired, context);
+      const change                = {
+        harness: row.harness, retired: true, assetId: row.assetId, target: row.target,
+        ownershipKey: ownershipKey(row), ownershipIdentity: row.ownershipIdentity, action, operation: 'remove',
+        ...(reason ? { reason } : {}),
+        ...(NO_FS_EFFECT.has(action) ? { release: true } : {}),
+        ...(fingerprint ? { fingerprint } : {}),
+        ...(action === 'strip-hooks' ? { hookCommands: { key: retired.removal.hookCommands.key, commands: [...retired.removal.hookCommands.commands] } } : {}),
+      };
+      plan.changes.push(Object.freeze(change)                 );
+      plan.counts[COUNTED[action]] += 1;
+      if (action === 'keep') plan.notices.push(`kept ${path.relative(scopeRoot, row.target)}: ${reason}`);
+      if (action === 'defer') plan.notices.push(`${path.relative(scopeRoot, row.target)}: handed over on the next run that targets ${handovers.get(change.ownershipKey).to}`);
+    }
+    plans.push(plan);
+  }
+  return plans;
+}
+
+/** Carry out the plans: JSON hook strips first, then marker sections, then whole-file deletes, so no
+ * settings file is ever left naming a script that is already gone. Each step re-checks what the plan
+ * proved and throws rather than act on a file that changed since; the caller's recovery restores. */
+function applyRetiredHarnesses(plans                      , { fsImpl = fs }      = {})       {
+  const all = plans.flatMap((plan) => plan.changes.map((change) => ({ change, scopeRoot: plan.scopeRoot })));
+  const guard = (change               , scopeRoot        ) => {
+    if (fsImpl.existsSync(change.target) && !resolvesInPlace(change.target, scopeRoot, fsImpl)) {
+      throw new Error(`Refusing to change retired ${change.harness} resource ${change.target}: it resolves outside its recorded path`);
+    }
+  };
+  for (const { change, scopeRoot } of all) {
+    if (change.action !== 'strip-hooks' || !change.hookCommands) continue;
+    guard(change, scopeRoot);
+    const read = readHooksDoc(change.target, change.hookCommands.key, fsImpl);
+    if (read.absent) continue;
+    if (read.error) throw new Error(`Refusing to strip retired ${change.harness} hooks from ${change.target}: ${read.error}`);
+    if (read.doc[change.hookCommands.key] === undefined) continue;
+    const next = stripHookCommands(read.doc, change.hookCommands.key, new Set(change.hookCommands.commands));
+    if (next) atomicJsonWrite(change.target, next, { fsImpl });
+  }
+  for (const { change, scopeRoot } of all) {
+    if (change.action !== 'strip-section') continue;
+    guard(change, scopeRoot);
+    removeMarkedSection(change.target, { startMarkers: START_MARKERS });
+  }
+  const deletes = all.filter(({ change }) => change.action === 'delete');
+  for (const { change, scopeRoot } of deletes) guard(change, scopeRoot);
+  removeTree({ changes: deletes.map(({ change }) => ({ operation: 'remove', target: change.target, fingerprint: change.fingerprint, relPath: change.target })), fsImpl });
+}
+
+/** Every ledger row the plans give up: all of them except deferred ones. */
+function retiredReleaseKeys(plans                      )              {
+  return new Set(plans.flatMap((plan) => plan.changes.filter((change) => change.action !== 'defer').map((change) => change.ownershipKey)));
+}
+
+/** IC-003 output, for dry-run and apply alike: one summary line per retired harness, whose six counts
+ * sum to the rows it swept, then one line per kept or named item. No plans, no lines. */
+function formatRetiredPlans(plans                      )           {
+  return plans.flatMap((plan) => [
+    `[RETIRED] ${plan.harness} → ${plan.replacement}: deleted ${plan.counts.deleted}, stripped ${plan.counts.stripped}, released ${plan.counts.released}, dropped ${plan.counts.dropped}, deferred ${plan.counts.deferred}, kept ${plan.counts.kept}`,
+    ...plan.notices.map((notice) => `  ${notice}`),
+  ]);
+}
+
+module.exports = { planRetiredHarnesses, planHandovers, handoversFor, applyRetiredHarnesses, retiredReleaseKeys, formatRetiredPlans, claimKey };

package/src/lifecycle/view.js

@@ -2,7 +2,7 @@
 
 // TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
 // lifecycle-view.js — CLI-facing view over the registry/lifecycle path: computes a plan across
-// every requested harness (claude/codex/gemini) from a loaded registry, a neutral ledger, and the
+// every requested harness (claude, codex, opencode, pi, copilot, kiro, antigravity) from a loaded registry, a neutral ledger, and the
 // Codex-native source locations under `repoRoot`, then renders/gates it for bin/doflow.js's
 // install/update/remove/status commands.
 const fs = require('node:fs');
@@ -13,16 +13,17 @@ const { createAdapterRegistry } = require('../adapters/index.js');
 const { declaredHarnessPaths } = require('../helper/harness-paths.js');
 const claudeAdapter = require('../adapters/claude/index.js');
 const codexAdapter = require('../adapters/codex/index.js');
-const { createGeminiAdapter } = require('../adapters/gemini/index.js');
 const { createOpenCodeAdapter } = require('../adapters/opencode/index.js');
 const { createPiAdapter } = require('../adapters/pi/index.js');
 const { createCopilotAdapter } = require('../adapters/copilot/index.js');
 const { createKiroAdapter } = require('../adapters/kiro/index.js');
 const { createAntigravityAdapter } = require('../adapters/antigravity/index.js');
 const { planLifecycle } = require('./index.js');
+const { formatRetiredPlans } = require('./retired-harnesses.js');
+const { resolveHookTier, hookTierWarnings } = require('./hook-tier.js');
 const { stateRoot, readLedger, defaultLedger } = require('../state/index.js');
 const { selectAssets } = require('../registry/index.js');
-const { defaultLock, readLock, writeLock, diffLocks, removeLock, pinnedSelections } = require('../state/lockfile.js');
+const { defaultLock, readLock, writeLock, diffLocks, removeLock, pinnedSelections, lockPackages } = require('../state/lockfile.js');
 // Tolerant because the projected runtime under `.doflow/runtime/` ships bin/, src/ and
 // core/registry/ but no package.json — see the `runtime.*` assets in core/registry/assets.json.
 // A hard require here would make every Node-backed verb fail in an install, which is the exact
@@ -48,17 +49,18 @@ function codexConfigResources(repoRoot     , fsImpl     ) {
  * mutation path until every native adapter has CLI-level parity.
  * `registry` is loaded once per command (by the caller) and threaded through here rather than
  * reloaded — the same registry also resolves every harness's MCP selection for that command. */
-function registryLifecycleView({ registry, scope, targets, mcpSelections = {}, mcpAdoptable = {}, retainedMcpIds = [], operation, repoRoot, force = false, adopt = false, permissions = false, statusline = false, fsImpl = fs }     ) {
+function registryLifecycleView({ registry, scope, targets, mcpSelections = {}, mcpAdoptable = {}, retainedMcpIds = [], operation, repoRoot, force = false, adopt = false, permissions = false, statusline = false, hookHarnesses, fsImpl = fs }     ) {
   const lifecycleScope = codexScope(scope);
   const scopeRoot = scope.global ? os.homedir() : path.resolve(scope.projectRoot);
   const neutralStateRoot = stateRoot({ scope: lifecycleScope, projectRoot: scopeRoot, homeDir: scopeRoot });
   const ledger = readLedger(neutralStateRoot) ?? defaultLedger({ scope: lifecycleScope, scopeRoot });
+  const tier = hookHarnesses ? { harnesses: hookHarnesses, workers: null } : resolveHookTier();
   // Mirrors buildAdapterRegistry() in src/cli/shared.js — including the declared-paths wiring —
   // and is kept as a literal construction here because the registry guard pins every declared
   // harness into each adapter-registry call site by parsing it.
   const declared = declaredHarnessPaths();
   const adapters = createAdapterRegistry({ claude: claudeAdapter.createClaudeAdapter({ declaredPaths: declared.claude }),
-    codex: codexAdapter.createCodexAdapter({ declaredPaths: declared.codex }), gemini: createGeminiAdapter({ declaredPaths: declared.gemini }),
+    codex: codexAdapter.createCodexAdapter({ declaredPaths: declared.codex }),
     opencode: createOpenCodeAdapter({ declaredPaths: declared.opencode }), pi: createPiAdapter({ declaredPaths: declared.pi }),
     copilot: createCopilotAdapter({ declaredPaths: declared.copilot }), kiro: createKiroAdapter({ declaredPaths: declared.kiro }),
     antigravity: createAntigravityAdapter({ declaredPaths: declared.antigravity }) });
@@ -68,19 +70,21 @@ function registryLifecycleView({ registry, scope, targets, mcpSelections = {}, m
     codexAgentsSourceDir: path.join(repoRoot, 'core', 'harnesses', 'codex', 'agents'),
     codexHooksSourceFile: path.join(repoRoot, 'core', 'harnesses', 'codex', 'hooks', 'hooks.json'),
     codexHooksSourceDir: path.join(repoRoot, 'core', 'harnesses', 'codex', 'hooks'),
-    geminiHooksSourceFile: path.join(repoRoot, 'core', 'harnesses', 'gemini', 'hooks', 'hooks.json'),
-    geminiHooksSourceDir: path.join(repoRoot, 'core', 'harnesses', 'gemini', 'hooks'),
     operation,
     force,
     adopt,
     permissions,
     statusline,
+    // maint-hooks: the person's hook tier (a caller may pass its own); every harness outside it gets content only.
+    hookHarnesses: tier.harnesses,
   } });
-  return { registry, stateRoot: neutralStateRoot, ledger, plan, adapters };
+  const hookWarnings = operation === 'remove' ? [] : hookTierWarnings(registry, plan.targets.filter((t     ) => !t.skipped).map((t     ) => t.harness), tier);
+  return { registry, stateRoot: neutralStateRoot, ledger, plan, adapters, hookWarnings };
 }
 
 function printRegistryLifecycle(view     , prefix = '[PLAN]') {
   console.log(`${prefix} Registry lifecycle: ${view.plan.changes.length} native change(s), ${view.plan.conflicts.length} conflict(s), ${view.plan.prerequisites.length} prerequisite(s)`);
+  for (const warning of view.hookWarnings ?? []) console.log(`[WARN] ${warning}`);
   for (const target of view.plan.targets) {
     console.log(`${prefix}   ${target.harness}: ${target.changes.length} change(s)${target.conflicts.length ? `; conflicts: ${target.conflicts.join('; ')}` : ''}`);
     const hookChange = target.changes.find((change     ) => change.nativeComponent === 'hooks');
@@ -89,19 +93,29 @@ function printRegistryLifecycle(view     , prefix = '[PLAN]') {
     }
     for (const notice of target.notices ?? []) console.log(`${prefix}   ${target.harness}: ${notice}`);
   }
+  printRetiredPlans(view);
   console.log(`${prefix} Neutral state: ${view.stateRoot}${readLedger(view.stateRoot) ? ' (existing ledger)' : ' (not yet created)'}`);
 }
 
+/** The retirement lines (row 127 IC-003), the same under --dry-run and after an apply: one
+ * `[RETIRED] <id> → <replacement>: deleted N, stripped N, released N, dropped N, deferred N, kept N`
+ * summary per retired harness the plan sweeps, then one line per kept or deferred item. Nothing
+ * when the ledger holds no retired row. */
+function printRetiredPlans(view     ) {
+  for (const line of formatRetiredPlans(view.plan.retiredHarnesses ?? [])) console.log(line);
+}
+
 /** Prints the plan's notices after a real run. Independent of whether anything changed: a no-op
  * reinstall of a harness that has a gap must still say so. */
 function printPlanNotices(view     ) {
+  for (const warning of view.hookWarnings ?? []) console.log(`[WARN] ${warning}`);
   for (const { harness, notice } of view.plan.notices) console.log(`[INFO] ${harness}: ${notice}`);
 }
 
 /** Harnesses whose native resources are reconciled through the registry/lifecycle path (all of
  * them, as of this wiring). Kept as an explicit list — rather than reusing VALID from
  * src/targets.js — so a future non-lifecycle target doesn't silently gain lifecycle behavior. */
-const LIFECYCLE_HARNESSES = ['claude', 'codex', 'gemini', 'opencode', 'pi', 'copilot', 'kiro', 'antigravity'];
+const LIFECYCLE_HARNESSES = ['claude', 'codex', 'opencode', 'pi', 'copilot', 'kiro', 'antigravity'];
 
 function assertSafeRegistryPlan(view     ) {
   if (view.plan.safe) return;
@@ -117,13 +131,18 @@ function assertSafeRegistryPlan(view     ) {
  * as the ledger (as the run left it) still holds a resource of that harness, so a narrower later run
  * never drops another harness's pin and a harness whose last resource is gone leaves it. MCP
  * selections carry over for pinned harnesses and are replaced by the rows this run resolved, `[]`
- * included. Assets are recomputed from the registry for every pinned harness. `null` when no harness
- * stays pinned. */
+ * included. Assets are recomputed from the registry for every pinned harness. The previous lock's
+ * `packages` (122 IC-007) are not registry-derived, so they are carried forward unchanged, and a lock
+ * that holds packages stays as `targets: []` once no harness is pinned. `null` when no harness stays
+ * pinned and no package is recorded. Only live harnesses are pinned (row 127 IC-004): a previous pin
+ * of a retired id is dropped, even while the ledger still holds its rows. */
 function lockDocument({ registry, scope, scopeRoot, previous = null, ledger, plannedTargets = [], mcpSelections = {}, sourceVersion = pkg.version, now = new Date() }     ) {
   const held = new Set((ledger?.resources ?? []).map((resource     ) => resource?.harness));
+  const live = new Set(registry.harnesses.map((harness     ) => harness.id));
   const pinned = [...new Set([...(previous?.targets ?? []).map((entry     ) => entry.harness), ...plannedTargets])]
-    .filter((harness) => held.has(harness)).sort();
-  if (!pinned.length) return null;
+    .filter((harness) => held.has(harness) && live.has(harness)).sort();
+  const packages = lockPackages(previous);
+  if (!pinned.length && !packages.length) return null;
   const assets = [];
   for (const harness of pinned) {
     for (const asset of selectAssets(registry, { harness })) {
@@ -139,6 +158,7 @@ function lockDocument({ registry, scope, scopeRoot, previous = null, ledger, pla
     targets: pinned.map((harness) => ({ harness })),
     assets,
     mcpSelections: Object.fromEntries(pinned.filter((harness) => Array.isArray(rows[harness])).map((harness) => [harness, rows[harness]])),
+    ...(packages.length ? { packages } : {}),
   };
 }
 
@@ -150,7 +170,7 @@ function lockDelta(previous     , next     ) {
   if (!previous) return { changed: true, summary: 'created' };
   const diff = diffLocks(previous, next);
   if (diff.clean) return { changed: false, summary: 'unchanged' };
-  const count = ['targets', 'assets']
+  const count = ['targets', 'assets', 'packages']
     .flatMap((section) => Object.values     (diff[section]).map((list     ) => list.length))
     .reduce((sum, n) => sum + n, 0)
     + diff.mcpSelections.changed.length + (diff.meta.sourceVersion ? 1 : 0);
@@ -170,6 +190,6 @@ function recordLock(scopeArgs     , next     , { fsImpl = fs }      = {}) {
 }
 
 module.exports = {
-  codexScope, registryLifecycleView, printRegistryLifecycle, printPlanNotices, LIFECYCLE_HARNESSES, assertSafeRegistryPlan,
+  codexScope, registryLifecycleView, printRegistryLifecycle, printRetiredPlans, printPlanNotices, LIFECYCLE_HARNESSES, assertSafeRegistryPlan,
   lockDocument, lockDelta, recordLock,
 };