@khoavu882/doflow 2.0.0-beta.5 → 2.0.1

package/src/helper/semver.js

@@ -0,0 +1,94 @@
+'use strict';
+
+// SemVer 2.0.0 parsing and precedence, and the package host-range grammar (IC-016).
+// No dependency: DoFlow ships `2.0.0-beta.N`, so prerelease precedence is part of the contract.
+                                                                                    
+                                                            
+                                                                             
+                                                                                                
+
+const HOST_RANGE_GRAMMAR = 'one or more comparators separated by single spaces, all of which must hold: '
+  + '>=V, <V, =V or a bare V (exact), where V is a full semver 2.0.0 version; '
+  + 'an upper bound (<V, =V or a bare V) is required; no ^, ~, ||, x or *';
+
+function parseSemVer(value        )                {
+  const match = value.match(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/);
+  if (!match) return null;
+  const prerelease = match[4] ? match[4].split('.') : [];
+  if (prerelease.some((identifier) => /^\d+$/.test(identifier)
+    && identifier.length > 1 && identifier.startsWith('0'))) return null;
+  return { major: match[1], minor: match[2], patch: match[3], prerelease };
+}
+
+function compareNumeric(left        , right        )         {
+  if (left.length !== right.length) return left.length < right.length ? -1 : 1;
+  if (left === right) return 0;
+  return left < right ? -1 : 1;
+}
+
+function compareSemVer(leftValue        , rightValue        )                {
+  const left = parseSemVer(leftValue);
+  const right = parseSemVer(rightValue);
+  if (!left || !right) return null;
+
+  for (const key of ['major', 'minor', 'patch']         ) {
+    const order = compareNumeric(left[key], right[key]);
+    if (order !== 0) return order;
+  }
+
+  if (left.prerelease.length === 0 && right.prerelease.length === 0) return 0;
+  if (left.prerelease.length === 0) return 1;
+  if (right.prerelease.length === 0) return -1;
+
+  const length = Math.min(left.prerelease.length, right.prerelease.length);
+  for (let index = 0; index < length; index++) {
+    const leftId = left.prerelease[index];
+    const rightId = right.prerelease[index];
+    const leftNumeric = /^\d+$/.test(leftId);
+    const rightNumeric = /^\d+$/.test(rightId);
+    if (leftNumeric && rightNumeric) {
+      const order = compareNumeric(leftId, rightId);
+      if (order !== 0) return order;
+    } else if (leftNumeric !== rightNumeric) {
+      return leftNumeric ? -1 : 1;
+    } else if (leftId !== rightId) {
+      return leftId < rightId ? -1 : 1;
+    }
+  }
+  if (left.prerelease.length === right.prerelease.length) return 0;
+  return left.prerelease.length < right.prerelease.length ? -1 : 1;
+}
+
+function refused(message        )            {
+  return { ok: false, error: { code: 'bad-type', message, allowed: HOST_RANGE_GRAMMAR } };
+}
+
+// Never throws: a refused range comes back as { ok: false, error } for the caller to turn into a finding.
+function parseHostRange(text         )            {
+  if (typeof text !== 'string') return refused('the host range must be a string');
+  const comparators               = [];
+  for (const token of text.split(' ')) {
+    const match = token.match(/^(>=|<|=)?(.+)$/);
+    if (!match || parseSemVer(match[2]) === null) {
+      return refused(`"${token}" is not a comparator of the host range grammar`);
+    }
+    comparators.push({ op: (match[1] || '=')                    , version: match[2] });
+  }
+  if (!comparators.some((comparator) => comparator.op !== '>=')) {
+    return refused('the host range has no upper bound');
+  }
+  return { ok: true, comparators };
+}
+
+// `range` is the range text or a parseHostRange result; a refused range or an invalid version satisfies nothing.
+function satisfiesHostRange(version        , range                    )          {
+  const parsed = typeof range === 'string' ? parseHostRange(range) : range;
+  if (!parsed.ok) return false;
+  return parsed.comparators.every(({ op, version: bound }) => {
+    const order = compareSemVer(version, bound);
+    if (order === null) return false;
+    return op === '>=' ? order >= 0 : op === '<' ? order < 0 : order === 0;
+  });
+}
+
+module.exports = { parseSemVer, compareSemVer, parseHostRange, satisfiesHostRange, HOST_RANGE_GRAMMAR };

package/src/install/backup.js

@@ -24,7 +24,7 @@ const { sourceCommit: gitSourceCommit } = require('../helper/git.js');
 const {
   legacyBackupReadRoot, isLegacyBackupReadRoot, scopeRootFromCanonicalBackupRoot,
 } = require('./paths.js');
-const { validateLedger } = require('../state/index.js');
+const { validateLedger, ownershipKey } = require('../state/index.js');
 
 /** Where a listed/restorable backup was found. 'current' = the canonical `.doflow/backups` root the
  * installer writes to; 'legacy' = the pre-7de6d5f `.claude/backups` root, readable only. Callers
@@ -69,6 +69,8 @@ function backupId(op        , date      )         {
 const MANIFEST_FILE = '.manifest.json';
 const OWNER_FILE = '.owner.json';
 const TEMP_PREFIX = '.tmp-';
+/** A backup retention is removing: renamed here first so a half-removed backup is never listed or counted. */
+const REMOVING_PREFIX = '.tmp-del-';
 const STALE_TEMP_MS = 24 * 60 * 60 * 1000;
 const MAX_ID_ATTEMPTS = 1000;
 const RENAME_COLLISION_CODES = new Set(['EEXIST', 'ENOTEMPTY', 'EPERM', 'EACCES']);
@@ -129,7 +131,9 @@ function createFileBackup({
       fsImpl.mkdirSync(backupRoot, { recursive: true });
       fsImpl.mkdirSync(tmpDir);
       tmpCreated = true;
-      const owner = { pid: process.pid, hostname: os.hostname(), startedAt: date.toISOString() };
+      // When this run started, not `date`: that is the time the backup is named for, and a caller may pass any
+      // date. isStaleTemp measures a temp's age from this field.
+      const owner = { pid: process.pid, hostname: os.hostname(), startedAt: new Date().toISOString() };
       fsImpl.writeFileSync(path.join(tmpDir, OWNER_FILE), `${JSON.stringify(owner)}\n`, { flag: 'wx' });
     } catch (err) { throw writeFailure(err); }
 
@@ -234,6 +238,35 @@ function defaultIsAlive(pid        )          {
   }
 }
 
+/**
+ * The id of this process's pid namespace where the platform exposes one (Linux: the target of
+ * `/proc/self/ns/pid`, such as `pid:[4026531836]`), else the empty string. A pid means something only
+ * inside the namespace that issued it; two containers can share a hostname and not a pid space.
+ */
+function pidNamespaceId()         {
+  try { return fs.readlinkSync('/proc/self/ns/pid'); } catch { return ''; }
+}
+
+/**
+ * Eight hex digits that identify the host and pid namespace in a rename-aside name. A pid means
+ * something only in the namespace it was issued in, so an aside is judged by pid only by a process
+ * in the same namespace on the same host. Where no namespace id exists the tag is the hostname alone.
+ */
+function hostTag(hostname         = os.hostname(), pidNamespace         = pidNamespaceId())         {
+  return crypto.createHash('sha1').update(`${hostname}\0${pidNamespace}`).digest('hex').slice(0, 8);
+}
+
+/**
+ * The owner a rename-aside folder (`.tmp-del-<id>-<host tag>-<pid>-<8 hex>`) names, or null when the
+ * name does not carry one. Ids contain `-`, so the fields are read from the end. Names without a host
+ * tag (an earlier layout that never shipped: it existed only on unreleased commits, so no migration)
+ * are unparseable and are kept.
+ */
+function removingOwner(name        )                                       {
+  const m = /-([0-9a-f]{8})-([0-9]+)-[0-9a-f]{8}$/.exec(name);
+  return m ? { host: m[1], pid: Number(m[2]) } : null;
+}
+
 function isStaleTemp(dir        , { now, fsImpl, isAlive, hostname }     )          {
   let owner = null;
   try { owner = JSON.parse(fsImpl.readFileSync(path.join(dir, OWNER_FILE), 'utf8')); } catch { /* no owner */ }
@@ -247,15 +280,25 @@ function isStaleTemp(dir        , { now, fsImpl, isAlive, hostname }     )
 /**
  * Remove `.tmp-*` directories left in `backupRoot` by runs that died: the owner process is gone on
  * this host, or the temp is older than 24 hours. Returns how many were removed.
+ *
+ * A `.tmp-del-*` rename-aside is a backup a retention pass is deleting, so age says nothing about it
+ * (it keeps the backup's own, possibly old, mtime and may be rolled back if the delete fails). It is
+ * removed only by the host and pid namespace named in it, and only when the pid in its name is not
+ * alive; any other host's or namespace's aside, and one whose name carries no owner, is left alone.
  */
-function sweepStaleTemps(backupRoot        , { now = Date.now(), fsImpl = fs, isAlive = defaultIsAlive, hostname = os.hostname() }      = {})         {
+function sweepStaleTemps(backupRoot        , { now = Date.now(), fsImpl = fs, isAlive = defaultIsAlive, hostname = os.hostname(), pidNamespace = pidNamespaceId() }      = {})         {
   assertMutableBackupRoot(backupRoot, 'clean up backups');
   if (!fsImpl.existsSync(backupRoot)) return 0;
   let removed = 0;
   for (const e of fsImpl.readdirSync(backupRoot, { withFileTypes: true })) {
     if (!e.isDirectory() || !e.name.startsWith(TEMP_PREFIX)) continue;
     const dir = path.join(backupRoot, e.name);
-    if (!isStaleTemp(dir, { now, fsImpl, isAlive, hostname })) continue;
+    if (e.name.startsWith(REMOVING_PREFIX)) {
+      // Removed only by the host that made it, and only once its pid is gone there. Another host's
+      // (or an unparseable) aside is kept: its pass may be live where this one cannot see it.
+      const owner = removingOwner(e.name);
+      if (owner === null || owner.host !== hostTag(hostname, pidNamespace) || isAlive(owner.pid)) continue;
+    } else if (!isStaleTemp(dir, { now, fsImpl, isAlive, hostname })) continue;
     try {
       fsImpl.rmSync(dir, { recursive: true, force: true });
       removed += 1;
@@ -347,7 +390,7 @@ function formatBytes(n                           )         {
 
 /** Security guard: a backup id is a directory *name*, never a path — reject traversal/absolute ids. */
 function assertSafeBackupId(bid        )       {
-  if (!bid || bid.includes('/') || bid.includes('\\') || bid === '..' || bid.includes('..')) {
+  if (!bid || bid === '.' || bid.includes('/') || bid.includes('\\') || bid === '..' || bid.includes('..')) {
     throw new Error(`Invalid backup id: '${bid}'`);
   }
 }
@@ -441,6 +484,9 @@ function refusalOf(entry     , target        , { scope, scopeRoot, bkDir, fsImpl
   } catch {
     return 'content missing from backup';
   }
+  // A restore chmods the file it writes to this mode, so a manifest that lacks one (or holds anything
+  // but a permission mask) is refused here, with a name, rather than failing inside the write.
+  if (!Number.isInteger(entry.mode) || entry.mode < 0 || entry.mode > 0o7777) return 'invalid mode';
   return null;
 }
 
@@ -473,6 +519,8 @@ function planRestore({ bid, backupRoot, scope, scopeRoot, targets, explicitTarge
     untargeted: 0,
     snapshot: [],
     v1: null,
+    // --target narrows the ledger with the files: the retired-harness rule of mergeRestoredLedger is off.
+    narrowed: Boolean(explicitTargets),
   };
   const wanted = new Set(targets);
 
@@ -535,13 +583,25 @@ function planRestore({ bid, backupRoot, scope, scopeRoot, targets, explicitTarge
  * the backup does not hold and rows of MCP entries (a file holding only MCP entries is never backed
  * up) stay as they are; restoring the whole old ledger would make DoFlow forget files and entries it
  * still has on disk. With no current ledger the backup's is taken whole.
+ *
+ * A harness in `retired` (retired in the registry now, row 127) is the exception: every row of it
+ * and its `targets` entry come back as the backup holds them. A sweep that retired it released some
+ * rows with no file effect (a file a live harness still claims), so no file of theirs is in the backup,
+ * yet the run dropped them. Only the sweep ever changes a retired row, so the backup's copy is never
+ * staler than the current one; a current row of it the backup lacks stays. A restored row whose file
+ * a live harness now claims is released by the next sweep (claim rule 2), file untouched.
  */
-function mergeRestoredLedger(backup     , current     , restored             )      {
+function mergeRestoredLedger(backup     , current     , restored             , retired              = new Set())      {
   if (!current) return backup;
   const at = (target     ) => typeof target === 'string' && restored.has(path.resolve(target));
+  const whole = (row     ) => retired.has(row?.harness);
+  const back = backup.resources.filter((r     ) => at(r.target) || whole(r));
+  const backKeys = new Set(back.filter(whole).map(ownershipKey));
+  const targets = Object.entries(backup.targets ?? {}).filter(([id]) => retired.has(id));
   return {
     ...current,
-    resources: [...current.resources.filter((r     ) => !at(r.target)), ...backup.resources.filter((r     ) => at(r.target))],
+    ...(targets.length ? { targets: { ...current.targets, ...Object.fromEntries(targets) } } : {}),
+    resources: [...current.resources.filter((r     ) => !at(r.target) && !(whole(r) && backKeys.has(ownershipKey(r)))), ...back],
     tombstones: [
       ...(current.tombstones ?? []).filter((t     ) => !at(t.fromTarget)),
       ...(backup.tombstones ?? []).filter((t     ) => at(t.fromTarget)),
@@ -549,21 +609,32 @@ function mergeRestoredLedger(backup     , current     , restored             )
   };
 }
 
+/** Ids the registry retires (row 127 IC-001): `registry` when a caller passes one, else the shipped
+ * registry. One that cannot be read retires nothing, which leaves the merge per restored file. */
+function retiredIds(registry     )              {
+  if (registry === undefined) {
+    const { REPO_ROOT } = require('../helper/repo-root.js');
+    try { registry = require('../registry/index.js').loadRegistry({ repoRoot: REPO_ROOT }); } catch { registry = null; }
+  }
+  return new Set((Array.isArray(registry?.retired) ? registry.retired : []).map((entry     ) => entry?.id).filter((id     ) => typeof id === 'string'));
+}
+
 /** The bytes a ledger restore item writes: the backup's ledger merged onto the current one. */
-function restoredLedgerBytes(item     , restored             , fsImpl     )         {
+function restoredLedgerBytes(item     , restored             , retired             , fsImpl     )         {
   const backup = validateLedger(JSON.parse(fsImpl.readFileSync(item.stored, 'utf8')));
   const current = fsImpl.existsSync(item.path) ? validateLedger(JSON.parse(fsImpl.readFileSync(item.path, 'utf8'))) : null;
-  return Buffer.from(`${JSON.stringify(validateLedger(mergeRestoredLedger(backup, current, restored)), null, 2)}\n`);
+  return Buffer.from(`${JSON.stringify(validateLedger(mergeRestoredLedger(backup, current, restored, retired)), null, 2)}\n`);
 }
 
 /**
  * Carry out a plan from planRestore. Format 2 writes each restore item through a temp file renamed
  * over the target (or straight through a symlinked target, which stays a link); a failed item is
  * reported and the rest continue. The ownership ledger goes last and restores only the rows of the
- * files written back before it (mergeRestoredLedger). It never deletes a file and never writes
+ * files written back before it, plus every row of a retired harness unless --target narrowed the
+ * restore (mergeRestoredLedger); `registry` is for tests, omitted the shipped one is read. It never deletes a file and never writes
  * outside `plan.restore`. A 1.19 plan goes through restoreBackup unchanged.
  */
-function executeRestore(plan     , { backupRoot, dryRun = false, fsImpl = fs }     )      {
+function executeRestore(plan     , { backupRoot, dryRun = false, registry, fsImpl = fs }     )      {
   if (plan.format !== 2) {
     const toolDirs = Object.fromEntries(plan.v1.tools.map((t     ) => [t.tool, t.dstDir]));
     restoreBackup({ bid: plan.bid, backupRoot, dirs: toolDirs, dryRun });
@@ -583,7 +654,7 @@ function executeRestore(plan     , { backupRoot, dryRun = false, fsImpl = fs }
     try {
       const dir = path.dirname(item.path);
       fsImpl.mkdirSync(dir, { recursive: true });
-      const bytes = item.ledger ? restoredLedgerBytes(item, files, fsImpl) : fsImpl.readFileSync(item.stored);
+      const bytes = item.ledger ? restoredLedgerBytes(item, files, plan.narrowed ? new Set() : retiredIds(registry), fsImpl) : fsImpl.readFileSync(item.stored);
       let isLink = false;
       try {
         isLink = fsImpl.lstatSync(item.path).isSymbolicLink();
@@ -685,7 +756,12 @@ function applyRetention({ backupRoot, keep, protect = [], reserve = 0, dryRun =
   const protectedCandidates = candidates.filter((c) => protectedIds.has(c.id));
   const ordered = [...protectedCandidates, ...candidates.filter((c) => !protectedIds.has(c.id))];
   const keepCount = keep === 0 ? ordered.length : Math.max(keep - reserve, protectedCandidates.length);
-  const removal = ordered.slice(keepCount).map((c) => c.id);
+  // The protected backup is the run's own, so one newer than it was made by another run that finished
+  // after it; this pass only reaps history older than its own backup.
+  const newestProtected = protectedCandidates[0];
+  const removal = ordered.slice(keepCount)
+    .filter((c) => !newestProtected || compareSortKeys(c, newestProtected) >= 0)
+    .map((c) => c.id);
 
   if (dryRun || keep === 0) {
     if (dryRun) result.wouldRemove = removal;
@@ -693,16 +769,30 @@ function applyRetention({ backupRoot, keep, protect = [], reserve = 0, dryRun =
     return result;
   }
 
+  // Also deletes what an earlier pass renamed aside and died before deleting (a `.tmp-del-*` whose pid
+  // is dead): already out of every listing, so it goes at once. One whose pid is alive belongs to a
+  // pass that may still roll it back, so it is never touched here, whatever its age.
   result.sweptTemps = sweepStaleTemps(backupRoot, { now, fsImpl });
   for (const id of removal) {
     const dir = path.join(backupRoot, id);
     // Another run's retention pass may have removed it already.
     if (!fsImpl.existsSync(dir)) continue;
+    // One rename takes the backup out of the listing whole; the deletion then happens out of sight.
+    const aside = path.join(backupRoot, `${REMOVING_PREFIX}${id}-${hostTag()}-${process.pid}-${crypto.randomBytes(4).toString('hex')}`);
     try {
-      fsImpl.rmSync(dir, { recursive: true, force: true });
+      fsImpl.renameSync(dir, aside);
+    } catch (err     ) {
+      if (err.code !== 'ENOENT') result.failed.push({ id, error: err.message });
+      continue;
+    }
+    try {
+      fsImpl.rmSync(aside, { recursive: true, force: true });
       result.removed.push(id);
     } catch (err     ) {
+      // Not removed: put it back under its id so it is still counted and listed, as when it was
+      // removed in place. If that fails too the aside folder is not listed and the next pass deletes it.
       result.failed.push({ id, error: err.message });
+      try { fsImpl.renameSync(aside, dir); } catch { /* the next pass cleans the aside folder */ }
     }
   }
   result.kept = ordered.filter((c) => fsImpl.existsSync(path.join(backupRoot, c.id))).length;
@@ -718,7 +808,7 @@ function retentionNote(prune                           , keep        )         {
 
 module.exports = {
   backupId, restoreBackup, listBackups, assertSafeBackupId, scopeRelative, retentionNote,
-  backupReadRoots, BACKUP_ORIGIN_CURRENT, BACKUP_ORIGIN_LEGACY,
+  backupReadRoots, hostTag, BACKUP_ORIGIN_CURRENT, BACKUP_ORIGIN_LEGACY,
   BackupError, DEFAULT_BACKUP_RETENTION, createFileBackup, sweepStaleTemps, classifyBackupDir,
   sortKey, backupSize, formatBytes, planRestore, executeRestore, mergeRestoredLedger, applyRetention,
 };

package/src/install/context.js

@@ -46,7 +46,7 @@ function printContext(ctx     )       {
     '[CONTEXT] Resolved install context',
     `  scope         : ${ctx.scope}  (root: ${ctx.scopeRoot})`,
     `  targets       : ${ctx.targets.join(', ')}`,
-    ...ctx.targets.map((t        ) => `    ${t.padEnd(7)}-> ${ctx.dirs[t]}`),
+    ...ctx.targets.map((t        ) => `    ${t.padEnd(7)}-> ${ctx.dirs[t] ?? '(resolved by adapter)'}`),
     `  repo root     : ${ctx.repoRoot}`,
     `  source commit : ${ctx.sourceCommit}`,
     `  node          : ${ctx.nodeVersion}`,

package/src/install/targets.js

@@ -1,6 +1,6 @@
 'use strict';
 // targets.js — target validation + install-dir resolution.
-// PARITY: sync.sh is global-only — $HOME/.{claude,codex,gemini}, hardcoded, NOT CLAUDE_CONFIG_DIR.
+// PARITY: sync.sh is global-only — $HOME/.{claude,codex}, hardcoded, NOT CLAUDE_CONFIG_DIR.
 // doflow extends this with a second, DoFlow-only scope: project-local install (this repo's own
 // .claude/ is a real precedent — Claude Code, Codex, and Copilot all support project-scoped config
 // alongside global, see agent-docs/research/context-setup-claude-codex-copilot.md).
@@ -15,25 +15,43 @@
 const os = require('node:os');
 const path = require('node:path');
 
-const VALID = ['claude', 'codex', 'gemini', 'copilot', 'kiro', 'opencode', 'pi', 'antigravity'];
+const VALID = ['claude', 'codex', 'copilot', 'kiro', 'opencode', 'pi', 'antigravity'];
 
 /** The target used when `--target` is omitted. Deliberately one harness, not all of VALID: an
  * install with no flag should touch the one tool the user almost certainly has, not write
  * configuration into every harness DoFlow knows about — several of which may not be installed at
  * all. That mattered less when VALID was three entries and matters more as it grows. Ask for the
- * rest explicitly with `--target claude,codex,gemini`. */
+ * rest explicitly with `--target claude,codex,antigravity`. */
 const DEFAULT_TARGETS = ['claude'];
 
 const TARGET_ALIASES                         = {
   agy: 'antigravity',
 };
 
-/** Default to DEFAULT_TARGETS; validate any explicitly requested. */
-function resolveTargets(requested                      )           {
+/** The registry's retired record for `id`, or null. The registry is read only for an id outside
+ * VALID, and a registry that cannot be read leaves the id unknown rather than failing differently. */
+function retiredTarget(id        , registry     )      {
+  const { loadRegistry, retiredFor } = require('../registry/index.js');
+  if (!registry) {
+    const { REPO_ROOT } = require('../helper/repo-root.js');
+    try { registry = loadRegistry({ repoRoot: REPO_ROOT }); } catch { return null; }
+  }
+  return retiredFor(registry, id);
+}
+
+/** Default to DEFAULT_TARGETS; validate any explicitly requested. A retired id (row 127 IC-002) is
+ * refused like an unknown one, naming its replacement. `registry` is for tests; omitted, the
+ * shipped registry is read. */
+function resolveTargets(requested                      , { registry }                     = {})           {
   const rawTargets = requested && requested.length ? requested : [...DEFAULT_TARGETS];
   const targets = rawTargets.map((t) => TARGET_ALIASES[t] || t);
   for (const t of targets) {
     if (!VALID.includes(t)) {
+      const retired = retiredTarget(t, registry);
+      if (retired) {
+        const alias = Object.keys(TARGET_ALIASES).find((key) => TARGET_ALIASES[key] === retired.replacement);
+        throw new Error(`Target '${t}' was retired on ${retired.retiredOn}; use '${retired.replacement}'${alias ? ` (alias ${alias})` : ''}. Its DoFlow files are released by the next 'doflow install' or 'doflow update' in that scope.`);
+      }
       throw new Error(`Unknown target: '${t}' (valid: ${VALID.join(', ')})`);
     }
   }
@@ -47,16 +65,14 @@ function resolveTargets(requested                      )           {
 
 /**
  * Map tool -> install root.
- *   global=true         -> $HOME/.{claude,codex,gemini,copilot,kiro,pi}, $HOME/.config/opencode
- *                          (sync.sh parity for claude/codex/gemini; the four new harnesses follow
- *                          each one's own documented global root — see below)
- *   global=false (dflt) -> <resolved projectRoot>/.{claude,codex,kiro,opencode,pi}, but .agents for
- *     gemini and .github for copilot — both deliberately asymmetric with their own global-scope
- *     directory, for reasons native to each harness (see per-key notes below).
+ *   global=true         -> $HOME/.{claude,codex,copilot,kiro,pi}, $HOME/.config/opencode
+ *                          (sync.sh parity for claude/codex; the other harnesses follow each one's
+ *                          own documented global root — see below)
+ *   global=false (dflt) -> <resolved projectRoot>/.{claude,codex,kiro,opencode,pi}, but .github for
+ *     copilot — deliberately asymmetric with its own global-scope directory, for reasons native to
+ *     the harness (see per-key notes below). antigravity has no entry: its adapter resolves its
+ *     own paths from core/registry/harnesses.json.
  *
- *   gemini   -> project-scoped Gemini config follows the Antigravity customization convention, not
- *               `.gemini/`, so it is asymmetric with its own global directory and with the other
- *               targets.
  *   copilot  -> Copilot has no single native root the way Claude's `.claude` is one: instructions,
  *               skills, agents, and MCP each live under a different path (see design.md §4's
  *               native-surfaces table). `.github` is the project root DoFlow treats as Copilot's
@@ -67,7 +83,7 @@ function resolveTargets(requested                      )           {
  *               the clean, symmetric case.
  *   opencode -> Global config is `~/.config/opencode`, NOT `~/.opencode/` — a path DoFlow's own
  *               docs asserted incorrectly for several releases (see src/adapters/opencode/index.js).
- *               Project scope is `.opencode`, asymmetric with the global path the same way gemini's
+ *               Project scope is `.opencode`, asymmetric with the global path the same way copilot's
  *               is.
  *   pi       -> Global config is `~/.pi/agent` — note the `agent/` segment; `~/.pi/settings.json`
  *               is not a location Pi reads. Project scope is `.pi` (see
@@ -79,7 +95,6 @@ function toolDirs(opts                  = {})                         {
   return {
     claude: path.join(root, '.claude'),
     codex: path.join(root, '.codex'),
-    gemini: global ? path.join(root, '.gemini') : path.join(root, '.agents'),
     copilot: global ? path.join(root, '.copilot') : path.join(root, '.github'),
     kiro: path.join(root, '.kiro'),
     opencode: global ? path.join(root, '.config', 'opencode') : path.join(root, '.opencode'),

package/src/lifecycle/coverage.js

@@ -2,11 +2,11 @@
 
 const crypto = require('node:crypto');
 const CLASS_ORDER = Object.freeze(['unknown', 'unsupported', 'observation', 'advisory', 'blocking']);
-const POLICY_ORDER = Object.freeze(['pre-implementation-gate', 'pre-bash-guard', 'session-context', 'mcp-tool-guard', 'stop-check']);
-const HARNESS_ORDER = Object.freeze(['claude', 'codex', 'gemini', 'opencode', 'pi', 'copilot', 'kiro', 'antigravity']);
+const HARNESS_ORDER = Object.freeze(['claude', 'codex', 'opencode', 'pi', 'copilot', 'kiro', 'antigravity']);
+const BEHAVIOUR_ORDER = Object.freeze(['context-authority', 'default-silence', 'summary-scope', 'summary-grant', 'identity', 'check-freshness']);
 const NEVER_BLOCKING_EVENTS = new Set([
   'pi\u0000tool_execution_start', 'antigravity\u0000PostToolUse', 'antigravity\u0000PreInvocation',
-  'antigravity\u0000PostInvocation', 'gemini\u0000AfterTool', 'claude\u0000PostToolUse', 'codex\u0000PostToolUse',
+  'antigravity\u0000PostInvocation', 'claude\u0000PostToolUse', 'codex\u0000PostToolUse',
 ]);
 function stable(value     )         {
   if (Array.isArray(value)) return `[${value.map(stable).join(',')}]`;
@@ -42,16 +42,4 @@ function enforcementFor(coverage     , query
     reason: weakest ? `${weakest.class} at (${weakest.policy}, ${weakest.harness}, ${weakest.event}, ${weakest.profile})` : `unknown at (${query.policy}, ${query.harness}, *, ${query.profile ?? '*'})`,
   };
 }
-function renderEnforcementMatrix(coverage     )         {
-  const order = (items                   , value        ) => {
-    const index = items.indexOf(value);
-    return index < 0 ? items.length : index;
-  };
-  const rows = [...coverage.rows].sort((a     , b     ) => order(POLICY_ORDER, a.policy) - order(POLICY_ORDER, b.policy)
-    || order(HARNESS_ORDER, a.harness) - order(HARNESS_ORDER, b.harness)
-    || a.event.localeCompare(b.event) || a.profile.localeCompare(b.profile));
-  const lines = [`Schema ${coverage.schemaVersion}; revision ${coverage.revision}; ${coverage.rowsDigest}`, '| Policy | Harness | Native event | Profile | Class | Verification | Prerequisites | Does not cover |', '|---|---|---|---|---|---|---|---|'];
-  for (const row of rows) lines.push(`| ${row.policy} | ${row.harness} | ${row.event} | ${row.profile} | ${row.class} | ${row.verification} | ${(row.prerequisites || []).join(', ')} | ${(row.doesNotCover || []).join(', ')} |`);
-  return lines.join('\n');
-}
-module.exports = { enforcementFor, renderEnforcementMatrix, rowsDigest, UnknownEnforcementTarget, NEVER_BLOCKING_EVENTS };
+module.exports = { enforcementFor, BEHAVIOUR_ORDER, HARNESS_ORDER, rowsDigest, UnknownEnforcementTarget, NEVER_BLOCKING_EVENTS };

package/src/lifecycle/hook-tier.js

@@ -0,0 +1,160 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+// Hook tiers (maint-hooks). Content (guidance, skills, agents, MCP) goes to every harness; DoFlow's
+// enforcement (hooks, gates, the bridge) goes only to the harnesses the `hooks.harnesses` setting
+// names. A harness outside that list is planned against a registry copy in which its `hooks`
+// capability is unavailable, so the same seams that already handle a harness without hooks drop
+// its hook assets, render its lifecycle policies as guidance fallbacks and skip its bespoke hook
+// config; the removal of what an earlier install wrote is planned from the ledger, as an uninstall
+// of those resources alone.
+
+const HOOKS_KEY = 'hooks.harnesses';
+const TIER_REASON = `not in ${HOOKS_KEY}`;
+const WORKERS_KEY = 'workers.enabled';
+
+/** The hook tier plus the worker harnesses the person configured (`workers.enabled` set in a settings
+ * file; null when it is the shipped default), for the run's warnings (maint-hooks R-4). */
+function resolveHookTier({ env = process.env, loadSettings }                                                                   = {})                                                    {
+  if (!loadSettings) {
+    const fs = require('node:fs');
+    const path = require('node:path');
+    const { configHome } = require('../runtime/config-home.js');
+    const dir = configHome(env).dir;
+    if (!dir || !fs.existsSync(path.join(dir, 'settings.json'))) {
+      const registry = JSON.parse(fs.readFileSync(path.join(__dirname, '..', '..', 'core', 'registry', 'settings.json'), 'utf8'));
+      return { harnesses: [...registry.keys[HOOKS_KEY].default], workers: null };
+    }
+  }
+  const load = loadSettings ?? require('../runtime/settings/resolve.js').loadSettings;
+  const view = load({ global: true, env: { ...env }, only: [HOOKS_KEY, WORKERS_KEY] });
+  const resolution = view.get(HOOKS_KEY, 'global');
+  const workers = view.get(WORKERS_KEY, 'global');
+  const configured = Array.isArray(workers?.value) && workers?.origin?.layer && workers.origin.layer !== 'default';
+  return {
+    harnesses: Array.isArray(resolution?.value) ? [...resolution.value] : [],
+    workers: configured ? workers.value.filter((id     ) => typeof id === 'string' && id !== 'primary').map((id        ) => id.split(/[:/]/)[0]) : null,
+  };
+}
+
+/** One WARN line per planned harness that gets no hooks although it is the primary session (claude)
+ * or a worker the person configured: there it runs without DoFlow's gates. */
+function hookTierWarnings(registry     , targets          , tier                                                   )           {
+  const warnings           = [];
+  for (const harness of registry.harnesses) {
+    if (!targets.includes(harness.id) || tier.harnesses.includes(harness.id) || !getsHooks(registry, harness)) continue;
+    const role = harness.id === 'claude' ? 'the primary session' : tier.workers?.includes(harness.id) ? `a worker in ${WORKERS_KEY}` : null;
+    if (role) warnings.push(`${harness.id} is ${role} but not in ${HOOKS_KEY}: it runs without DoFlow's hooks or gates`);
+  }
+  return warnings;
+}
+
+/** Whether a harness is outside the hook tier. `hookHarnesses` undefined means no tier was resolved
+ * (an in-process caller): every harness keeps its hooks, as before the setting existed. */
+function outsideHookTier(harnessId        , hookHarnesses                  )          {
+  return Array.isArray(hookHarnesses) && !hookHarnesses.includes(harnessId);
+}
+
+/** Whether DoFlow installs any hook for a harness: its hooks are supported, or a hook asset applies
+ * to it (Pi's guard extension). OpenCode gets none, so the tier leaves it as it is. */
+function getsHooks(registry     , harness     )          {
+  const hooks = harness.capabilities?.hooks;
+  if (!hooks || hooks.status === 'unavailable') return false;
+  if (hooks.status === 'supported') return true;
+  const { selectAssets } = require('../registry/index.js');
+  return selectAssets(registry, { harness: harness.id, capability: 'hooks' }).length > 0;
+}
+
+/** The registry a harness outside the tier is planned against: the same object graph, with that
+ * harness's `hooks` capability unavailable. A harness DoFlow installs no hook for, or that is in the
+ * tier, is returned unchanged. */
+function tieredRegistry(registry     , hookHarnesses                  )      {
+  if (!Array.isArray(hookHarnesses)) return registry;
+  let changed = false;
+  const harnesses = registry.harnesses.map((harness     ) => {
+    const hooks = harness.capabilities?.hooks;
+    if (!outsideHookTier(harness.id, hookHarnesses) || !getsHooks(registry, harness)) return harness;
+    changed = true;
+    return { ...harness, capabilities: { ...harness.capabilities, hooks: { ...hooks, status: 'unavailable', reason: TIER_REASON, tiered: true } } };
+  });
+  return changed ? { ...registry, harnesses } : registry;
+}
+
+/** The harness ids whose hooks a removal must take: those the ledger records hook resources for. A
+ * removal plans what an install wrote, so a harness installed outside the tier (no hook rows) plans
+ * no hook removal, and never claims a shared hook file another harness still owns. */
+function hookHoldersFromLedger(registry     , ledger     )           {
+  const { selectAssets } = require('../registry/index.js');
+  const rows = ledger?.resources ?? [];
+  return registry.harnesses.filter((harness     ) => {
+    const hookIds = new Set        (selectAssets(registry, { harness: harness.id, capability: 'hooks' }).map((asset     ) => asset.id));
+    return rows.some((row     ) => row?.harness === harness.id && isHookResource(row, hookIds));
+  }).map((harness     ) => harness.id);
+}
+
+/** Whether a (possibly tiered) harness declaration had its hooks switched off by the tier. */
+function hooksTieredOff(harness     )          {
+  return harness?.capabilities?.hooks?.tiered === true;
+}
+
+/** The context keys that hand an adapter a bespoke hook source (Codex hooks.json). A harness outside the tier is planned without them, and with `hooksOff` set for the
+ * adapters whose hooks ride a non-hook asset (Claude's settings.json). */
+const HOOK_SOURCE_KEYS = ['codexHooksSourceFile', 'codexHooksSourceDir'];
+
+function withoutHookSources(context     )      {
+  const next      = { ...context, hooksOff: true };
+  for (const key of HOOK_SOURCE_KEYS) delete next[key];
+  return next;
+}
+
+/** Renderers and resource kinds that only ever carry hook state, whatever asset id they ride on
+ * (Codex files its bespoke hook resources under a guidance asset id). */
+const HOOK_RENDERERS = new Set(['codex-hooks', 'antigravity-hooks', 'pi-guard-extension']);
+const HOOK_KINDS = new Set(['hooks-file', 'hooks-script']);
+
+function isHookResource(item     , hookIds             )          {
+  return hookIds.has(item?.assetId) || item?.nativeComponent === 'hooks' || HOOK_KINDS.has(item?.kind)
+    || HOOK_RENDERERS.has(item?.projection?.renderer);
+}
+
+/**
+ * Add to a harness's content plan the removal of the hooks an earlier install wrote for it, planned by
+ * the adapter's own remove path against the full registry and kept to hook changes only. Nothing is
+ * planned when the ledger holds no hook row for the harness. The removals carry `hookTier: true`, so
+ * applyLifecycle runs them through `adapter.remove` with `hookTierInput`.
+ */
+function planHookTierRemovals({ target, registry, adapter, harness, scope, scopeRoot, ledger, context, normalizeChange, adapterConflicts }     )      {
+  const { selectAssets } = require('../registry/index.js');
+  const { projectAdapterInput } = require('../adapters/index.js');
+  const { renderPolicies } = require('./policies.js');
+  if (harness.capabilities?.hooks?.status === 'unavailable') return target;
+  const hookIds = new Set        (selectAssets(registry, { harness: harness.id, capability: 'hooks' }).map((asset     ) => asset.id));
+  const rows = (ledger?.resources ?? []).filter((row     ) => row?.harness === harness.id && isHookResource(row, hookIds));
+  if (!rows.length) return target;
+  const assets = selectAssets(registry, { harness: harness.id });
+  const policies = renderPolicies(registry, { harness: harness.id });
+  const input = projectAdapterInput({ registry, harness, scope, scopeRoot, assets, mcp: [], mcpAdoptable: [], policies,
+    context: { ...context, operation: 'remove' } });
+  const discovery = adapter.discover({ ...input, registry, ledger });
+  const result = adapter.plan({ ...input, registry, ledger, discovery });
+  // A removal the content plan already carries (an adapter that plans its own hooks off) is not planned twice.
+  const planned = new Set(target.changes.map((change     ) => `${change.ownershipIdentity}\0${change.target}`));
+  const removals = (result.changes || []).filter((change     ) => isHookResource(change, hookIds)
+    && !planned.has(`${change.ownershipIdentity ?? change.ownership}\0${change.target}`))
+    .map((change     ) => Object.freeze({ ...normalizeChange(change, { harness, assets }), hookTier: true }));
+  const conflicts = adapterConflicts(result, harness).filter((reason     ) => /hook/i.test(String(reason)));
+  if (!removals.length && !conflicts.length) return target;
+  const used = new Set(removals.map((change     ) => change.assetId));
+  const extraAssets = assets.filter((asset     ) => used.has(asset.id) && !target.assets.some((own     ) => own.id === asset.id));
+  const changes = [...target.changes, ...removals];
+  const requiredNativeResources = target.requiredNativeResources === target.changes ? changes : [...target.requiredNativeResources, ...removals];
+  return {
+    ...target, assets: [...target.assets, ...extraAssets], changes, requiredNativeResources,
+    conflicts: [...target.conflicts, ...conflicts],
+    notices: [...target.notices, `removing ${harness.id} hooks: ${TIER_REASON} (content stays)`],
+    hookTierInput: input,
+  };
+}
+
+module.exports = { TIER_REASON, resolveHookTier, hookTierWarnings, tieredRegistry, hookHoldersFromLedger, hooksTieredOff, withoutHookSources, planHookTierRemovals };