@khoavu882/doflow 2.0.1 → 2.0.2

package/src/install/manifest.js

@@ -25,6 +25,20 @@ function canonicalManifestPath(scopeRoot        )         {
   return path.join(path.resolve(scopeRoot), '.doflow', MANIFEST_FILE_NAME);
 }
 
+/** Atomic same-directory write of the manifest document. */
+function atomicWrite(file        , manifest        , date      )       {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  // Security: the temp file must live next to `file` itself, not a shared os.tmpdir() — a
+  // world-writable /tmp plus a PID+timestamp-derived (i.e. guessable) name is a symlink-race
+  // waiting to happen (plant a symlink at the predicted path, the write clobbers its target).
+  // 'wx' (O_CREAT|O_EXCL) refuses to open through an existing symlink or file at all, and being
+  // on the same filesystem as `file` makes the final rename a guaranteed atomic same-fs op
+  // (os.tmpdir() offered no such guarantee — e.g. containers where /tmp is a separate tmpfs mount).
+  const tmp = path.join(path.dirname(file), `.install-manifest-${process.pid}-${date.getTime()}.json.tmp`);
+  fs.writeFileSync(tmp, `${JSON.stringify(manifest, null, 2)}\n`, { flag: 'wx' });
+  fs.renameSync(tmp, file); // atomic on the same filesystem, matches sync.sh's mktemp + mv
+}
+
                               
                      
                      
@@ -88,19 +102,29 @@ function writeManifest({ scopeRoot, claudeDir, scriptVersion, operation, repoRoo
   const resources = managedResources ?? existingManagedResources;
   if (resources !== undefined) manifest.managed_resources = resources;
 
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  // Security: the temp file must live next to `file` itself, not a shared os.tmpdir() — a
-  // world-writable /tmp plus a PID+timestamp-derived (i.e. guessable) name is a symlink-race
-  // waiting to happen (plant a symlink at the predicted path, the write clobbers its target).
-  // 'wx' (O_CREAT|O_EXCL) refuses to open through an existing symlink or file at all, and being
-  // on the same filesystem as `file` makes the final rename a guaranteed atomic same-fs op
-  // (os.tmpdir() offered no such guarantee — e.g. containers where /tmp is a separate tmpfs mount).
-  const tmp = path.join(path.dirname(file), `.install-manifest-${process.pid}-${date.getTime()}.json.tmp`);
-  fs.writeFileSync(tmp, `${JSON.stringify(manifest, null, 2)}\n`, { flag: 'wx' });
-  fs.renameSync(tmp, file); // atomic on the same filesystem, matches sync.sh's mktemp + mv
+  atomicWrite(file, manifest, date);
   return file;
 }
 
+/**
+ * After a removal: stop listing `tools` as installed. Nothing else in the record changes except the
+ * operation and time, and a missing or unreadable manifest is left alone (nothing lists them).
+ * Returns whether the file was rewritten.
+ */
+function forgetManifestTools({ scopeRoot, tools, date = new Date() }                                                     )          {
+  const file = canonicalManifestPath(scopeRoot);
+  if (!fs.existsSync(file)) return false;
+  let manifest     ;
+  try { manifest = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return false; }
+  const listed = tools.filter((tool) => manifest?.tools && Object.hasOwn(manifest.tools, tool));
+  if (!listed.length) return false;
+  for (const tool of listed) delete manifest.tools[tool];
+  manifest.last_operation = 'remove';
+  manifest.last_run = date.toISOString().replace(/\.\d+Z$/, 'Z');
+  atomicWrite(file, manifest, date);
+  return true;
+}
+
 /** null if no manifest yet. */
 function readManifestFile(file        )      {
   if (!fs.existsSync(file)) return null;
@@ -141,5 +165,5 @@ function readManifest(claudeDir        )      {
 
 module.exports = {
   LEGACY_MANIFEST_FILE_NAME, MANIFEST_FILE_NAME, manifestPath, canonicalManifestPath,
-  writeManifest, readManifest, readInstallManifest,
+  writeManifest, forgetManifestTools, readManifest, readInstallManifest,
 };

package/src/install/paths.js

@@ -3,6 +3,7 @@
 // TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): authored as `.ts`, run directly by Node
 // native type-stripping — no build step, no runtime dependency. Body stays CommonJS so a `.js`
 // caller's `require('../install/paths.js')` keeps working while the rest of the tree is still `.js`.
+const fs = require('node:fs');
 const path = require('node:path');
 
 const DOFLOW_DIR_NAME = '.doflow';
@@ -72,7 +73,44 @@ function doflowPaths({ scopeRoot }            )              {
   };
 }
 
+/** The one spelling of a path that ownership comparisons use: `fs.realpathSync` of the resolved path,
+ * or the resolved path itself when it does not exist (nothing to follow yet). macOS reaches the
+ * temp folder as both /var/... and /private/var/..., and a ledger row written under one spelling
+ * must match the other. */
+function canonicalPath(target        )         {
+  const resolved = path.resolve(target);
+  try { return fs.realpathSync(resolved); } catch { return resolved; }
+}
+
+function rebaseString(value        , from        , to        )         {
+  if (value === from) return to;
+  return value.startsWith(from + path.sep) ? to + value.slice(from.length) : value;
+}
+
+function rebaseDeep(value     , from        , to        )      {
+  if (typeof value === 'string') return rebaseString(value, from, to);
+  if (Array.isArray(value)) return value.map((item) => rebaseDeep(item, from, to));
+  if (value && typeof value === 'object') {
+    const out      = {};
+    for (const key of Object.keys(value)) out[key] = rebaseDeep(value[key], from, to);
+    return out;
+  }
+  return value;
+}
+
+/** A ledger read from disk, with every path that names the scope root under a different spelling of
+ * it (the aliased path an earlier install recorded) rewritten to `scopeRoot`, the canonical one.
+ * The stored format is unchanged; a ledger already in canonical form, with no scope root of its
+ * own, or recording an unrelated directory is returned as it came. */
+function canonicalLedger(ledger     , scopeRoot        )      {
+  const recorded = ledger && typeof ledger.scopeRoot === 'string' && ledger.scopeRoot ? path.resolve(ledger.scopeRoot) : null;
+  if (!recorded || recorded === scopeRoot || canonicalPath(recorded) !== scopeRoot) return ledger;
+  return rebaseDeep(ledger, recorded, scopeRoot);
+}
+
 module.exports = {
+  canonicalPath,
+  canonicalLedger,
   DOFLOW_DIR_NAME,
   BACKUP_DIR_NAME,
   INSTALL_MANIFEST_FILE_NAME,

package/src/install/targets.js

@@ -14,6 +14,7 @@
 // caller's `require('../install/targets.js')` keeps working while the rest of the tree is still `.js`.
 const os = require('node:os');
 const path = require('node:path');
+const { canonicalPath } = require('./paths.js');
 
 const VALID = ['claude', 'codex', 'copilot', 'kiro', 'opencode', 'pi', 'antigravity'];
 
@@ -58,6 +59,14 @@ function resolveTargets(requested                      , { registry }
   return [...new Set(targets)];
 }
 
+/** The harnesses an install manifest lists as installed, in VALID order; [] when there is no
+ * manifest or it lists none DoFlow still knows (a retired id is not a target). `update` without
+ * `-t` acts on these instead of DEFAULT_TARGETS, so it never installs a harness the scope lacks. */
+function installedTargets(manifest     )           {
+  const tools = manifest?.tools ?? {};
+  return VALID.filter((id) => Object.hasOwn(tools, id) && tools[id]?.installed !== false);
+}
+
                            
                    
                        
@@ -91,7 +100,7 @@ function resolveTargets(requested                      , { registry }
  */
 function toolDirs(opts                  = {})                         {
   const { global = false, projectRoot = '.' } = opts;
-  const root = global ? os.homedir() : path.resolve(projectRoot);
+  const root = global ? os.homedir() : canonicalPath(projectRoot);
   return {
     claude: path.join(root, '.claude'),
     codex: path.join(root, '.codex'),
@@ -102,4 +111,4 @@ function toolDirs(opts                  = {})                         {
   };
 }
 
-module.exports = { VALID, DEFAULT_TARGETS, resolveTargets, toolDirs };
+module.exports = { VALID, DEFAULT_TARGETS, resolveTargets, installedTargets, toolDirs };

package/src/lifecycle/index.js

@@ -17,6 +17,7 @@ const { renderMcpIndex } = require('./mcp-index.js');
 const { hasBashCapableShell } = require('./bash-availability.js');
 const { planHookCompanions } = require('./hook-step.js');
 const { tieredRegistry, hookHoldersFromLedger, hooksTieredOff, withoutHookSources, planHookTierRemovals } = require('./hook-tier.js');
+const { forgetManifestTools } = require('../install/manifest.js');
 const { readLock, lockPackages } = require('../state/lockfile.js');
 const { resolveRegistrySource } = require('../adapters/resolve-source.js');
 const { planRetiredHarnesses, planHandovers, handoversFor, applyRetiredHarnesses, retiredReleaseKeys, claimKey } = require('./retired-harnesses.js');
@@ -118,6 +119,34 @@ function markUnownedAbsences(statuses     , ledger     , harness     ) {
   ));
 }
 
+/** An adapter verifies every asset the current source declares for it, comparing disk to source. For
+ * an asset the removal leaves this harness nothing to delete from, that is not its business: the
+ * files belong to another harness's rows (retained removals, or an older install that gave this
+ * harness no rows there: a v1.14.2 Pi install recorded none for the guidance, scripts and runtime
+ * trees) and so carry that install's legacy bytes. Those bytes read as conflicts on files this
+ * removal never touches, and the ones that do match source would be written back as NEW rows for
+ * the harness being removed. So for such an asset the `conflict` status, its `<assetId>: ...`
+ * conflict strings and its copy-tree resources are dropped. An asset the plan deletes from, or one
+ * where a ledger row has no removal, is judged exactly as before. Without a ledger nothing is
+ * proven settled, so the strict reading is kept. */
+function dropSettledAssetVerification(verification     , statuses     , conflicts     , removals     , ledger     ) {
+  const unchanged = { resources: verification.resources, statuses, conflicts };
+  if (!ledger) return unchanged;
+  const rows = (ledger.resources || []).filter((resource     ) => resource.harness === verification.harness);
+  const settled = (assetId     ) => !removals.some((change     ) => change.assetId === assetId && !change.retained)
+    && !rows.some((row     ) => row.assetId === assetId && !removals.some((change     ) => matchesChange(row, change)));
+  const settledAssets = new Set([
+    ...statuses.filter((status     ) => status?.status === 'conflict').map((status     ) => status.assetId),
+    ...verification.resources.filter((resource     ) => resource?.kind === 'copy-tree-file').map((resource     ) => resource.assetId),
+  ].filter((assetId     ) => assetId && settled(assetId)));
+  if (!settledAssets.size) return unchanged;
+  return {
+    resources: verification.resources.filter((resource     ) => !(resource?.kind === 'copy-tree-file' && settledAssets.has(resource.assetId))),
+    statuses: statuses.map((status     ) => (settledAssets.has(status?.assetId) && status.status === 'conflict' ? { ...status, status: 'not-managed' } : status)),
+    conflicts: conflicts.filter((reason     ) => ![...settledAssets].some((assetId) => String(reason).startsWith(`${assetId}: `))),
+  };
+}
+
 function normalizeRemovalVerification(verification     , changes     , ledger     ) {
   const removals = changes.filter((change     ) => change.operation === 'remove' && change.harness === verification.harness);
   if (!removals.length) return verification;
@@ -128,7 +157,9 @@ function normalizeRemovalVerification(verification     , changes     , ledger
   // before.
   const removed = removals.filter((change     ) => !change.retained);
   let statuses = [...verification.statuses];
-  const conflicts = [...(verification.conflicts || [])];
+  let conflicts = [...(verification.conflicts || [])];
+  let resources       ;
+  ({ resources, statuses, conflicts } = dropSettledAssetVerification(verification, statuses, conflicts, removals, ledger));
   for (const change of removed) {
     const outcome = reconcileRemovedChange(verification, statuses, change);
     if (outcome.conflict) { conflicts.push(outcome.conflict); continue; }
@@ -137,7 +168,7 @@ function normalizeRemovalVerification(verification     , changes     , ledger
   }
   // After reconciling the plan's own removals, so this only ever judges what the plan left over.
   statuses = markUnownedAbsences(statuses, ledger, verification.harness);
-  return { ...verification, statuses, conflicts, ok: removalVerificationOk(verification.ok, statuses, conflicts) };
+  return { ...verification, resources, statuses, conflicts, ok: removalVerificationOk(verification.ok, statuses, conflicts) };
 }
 
 /** An adapter may initially report ok:false because a now-removed resource is missing. Once
@@ -913,7 +944,15 @@ function updateLedger({ ledger, scope, scopeRoot, verifications, changes, recove
   // Record the relocation, then sweep the stale copy — but only when its bytes still hash to the
   // fingerprint DoFlow last verified there. A mismatch means someone edited that file after us:
   // their content outranks our tidiness, so the file stays and the unswept tombstone says why.
+  // An MCP entry is one member of a file the user shares, and the adapter has already taken it out
+  // of (or released it in) the old file by entry. A whole-file tombstone for it would carry the
+  // entry's fingerprint, never match the file's bytes and so stay unswept for good. Earlier runs
+  // left such rows behind for Pi's mcp.json (which borrows the guidance.codex-pointer asset id);
+  // they are retired here, and no file is touched.
+  next.tombstones = next.tombstones.filter((entry     ) => entry.sweptAt || entry.harness !== 'pi'
+    || entry.assetId !== 'guidance.codex-pointer' || path.basename(String(entry.fromTarget)) !== 'mcp.json');
   for (const resource of next.resources) {
+    if (resource.kind === 'mcp-server') continue;
     const prior = priorByIdentity.get(`${resource.harness}\u0000${resource.assetId}\u0000${resource.identity ?? ''}`);
     if (!prior || prior.target === resource.target) continue;
     if (!next.tombstones.some((entry     ) => entry.harness === resource.harness
@@ -925,6 +964,16 @@ function updateLedger({ ledger, scope, scopeRoot, verifications, changes, recove
       });
     }
   }
+  // A legacy retirement: an adapter removed an old projection that no row owned (its change carries
+  // `legacyRetirement.toTarget`, where the claim lives now). Journaled as a tombstone already swept.
+  for (const change of changes) {
+    if (!change.legacyRetirement || change.operation !== 'remove' || change.retained) continue;
+    const { harness, assetId, target: fromTarget, fingerprint } = change;
+    const toTarget = change.legacyRetirement.toTarget;
+    if (next.tombstones.some((entry     ) => entry.harness === harness && entry.fromTarget === fromTarget && entry.toTarget === toTarget)) continue;
+    const at = new Date().toISOString();
+    next.tombstones.push({ harness, assetId, fromTarget, toTarget, fingerprint, movedAt: at, sweptAt: at });
+  }
   const claims = new Set(next.resources.map((resource     ) => resource.target));
   for (const entry of next.tombstones) {
     if (entry.sweptAt || !fsImpl.existsSync(entry.fromTarget) || claims.has(entry.fromTarget)) continue;
@@ -1152,9 +1201,37 @@ function settleSuspendedProjection({ homeDir }     )       {
   }
 }
 
+/** Remove the directories a removal emptied, from each removed file's folder upward, tool root
+ * included (`.pi`, `.opencode`, `.agents`); `rmdir` refuses a folder that holds anything, so no
+ * file is touched. The walk stops at the scope root and never takes a shared `.config` folder. */
+function pruneEmptiedDirs(changes       , scopeRoot        , fsImpl      = fs) {
+  const root = path.resolve(scopeRoot);
+  for (const change of changes) {
+    if (change.operation !== 'remove' || change.retained || change.release || typeof change.target !== 'string') continue;
+    let dir = path.dirname(path.resolve(change.target));
+    if (!isUnder(dir, root)) continue;
+    // The removed file's own folders may already be gone; the first one still standing starts the walk.
+    while (dir !== root && isUnder(dir, root) && !fsImpl.existsSync(dir)) dir = path.dirname(dir);
+    while (dir !== root && isUnder(dir, root) && path.basename(dir) !== '.config') {
+      try { fsImpl.rmdirSync(dir); } catch { break; }
+      dir = path.dirname(dir);
+    }
+  }
+}
+
+/** Stop the install manifest listing a harness the removal left with no ownership row. */
+function forgetRemovedTools(targets          , ledger     , scopeRoot        ) {
+  const standing = new Set((ledger?.resources || []).map((resource     ) => resource.harness));
+  const gone = (targets || []).filter((harness) => !standing.has(harness));
+  if (gone.length) forgetManifestTools({ scopeRoot, tools: gone });
+}
+
 function removeLifecycle(options     ) {
   const plan = planLifecycle({ ...options, context: { ...(options.context || {}), operation: 'remove' } });
-  return applyLifecycle({ ...options, plan, mode: 'remove', acceptPrerequisites: options.acceptPrerequisites });
+  const result = applyLifecycle({ ...options, plan, mode: 'remove', acceptPrerequisites: options.acceptPrerequisites });
+  pruneEmptiedDirs(plan.targets.flatMap((target     ) => target.changes), plan.scopeRoot);
+  forgetRemovedTools(options.targets, result.ledger, plan.scopeRoot);
+  return result;
 }
 
 module.exports = { OPERATIONS, MCP_KEEP, recordMcpOwnership, isPackageAsset, registryScope, normalizeTargets, normalizeChange, matchesChange, normalizeRemovalVerification, adapterConflicts, planLifecycle, verifyLifecycle, applyLifecycle, removeLifecycle, updateLedger, mcpIndexPath, applyMcpIndex, targetNeedsHooks, assertBashAvailableForHooks, hookWiringStatus, markRetainedRemovals, retentionSummary, PRUNED_TREES, settleSuspendedProjection };

package/src/lifecycle/retired-harnesses.js

@@ -128,6 +128,20 @@ function markerState(text        )                              { return markedS
 /** Rule 3a's verdict for one retired row (IC-003, IC-007, design D7). */
                                                                                                                          
 
+/** The one rule for "the replacement manages this file": at project scope the replacement writes its
+ * declared instruction file whatever else shares it; at global scope it stays out while another live
+ * harness in `registry` declares the same file (that harness's adapter keeps it). The handover plan
+ * here and antigravity's `instructionTarget` both ask it, so a row is never released to a harness that
+ * then plans nothing. */
+function replacementManagesFile({ registry, harnessId, surface, target, scope, scopeRoot }     )          {
+  if (scope !== 'global') return true;
+  const declaredBy = (harness     ) => {
+    if (harness?.id === harnessId || !harness?.paths?.[surface]) return false;
+    try { return resolveHarnessPaths({ [surface]: harness.paths[surface] }, { scope: 'global', scopeRoot, homeDir: scopeRoot })[surface] === target; } catch { return false; }
+  };
+  return !(registry?.harnesses ?? []).some(declaredBy);
+}
+
 /**
  * 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`
@@ -155,6 +169,7 @@ function planHandovers({ registry, ledger, scope, scopeRoot, planned = [], fsImp
       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;
+      if (!replacementManagesFile({ registry, harnessId: to.id, surface: entry.surface, target: declared, scope, scopeRoot })) 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 });
@@ -315,4 +330,4 @@ function formatRetiredPlans(plans                      )           {
   ]);
 }
 
-module.exports = { planRetiredHarnesses, planHandovers, handoversFor, applyRetiredHarnesses, retiredReleaseKeys, formatRetiredPlans, claimKey };
+module.exports = { replacementManagesFile, planRetiredHarnesses, planHandovers, handoversFor, applyRetiredHarnesses, retiredReleaseKeys, formatRetiredPlans, claimKey };

package/src/lifecycle/view.js

@@ -19,6 +19,7 @@ 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 { canonicalPath, canonicalLedger } = require('../install/paths.js');
 const { formatRetiredPlans } = require('./retired-harnesses.js');
 const { resolveHookTier, hookTierWarnings } = require('./hook-tier.js');
 const { stateRoot, readLedger, defaultLedger } = require('../state/index.js');
@@ -51,9 +52,9 @@ function codexConfigResources(repoRoot     , fsImpl     ) {
  * 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, hookHarnesses, fsImpl = fs }     ) {
   const lifecycleScope = codexScope(scope);
-  const scopeRoot = scope.global ? os.homedir() : path.resolve(scope.projectRoot);
+  const scopeRoot = scope.global ? os.homedir() : canonicalPath(scope.projectRoot);
   const neutralStateRoot = stateRoot({ scope: lifecycleScope, projectRoot: scopeRoot, homeDir: scopeRoot });
-  const ledger = readLedger(neutralStateRoot) ?? defaultLedger({ scope: lifecycleScope, scopeRoot });
+  const ledger = canonicalLedger(readLedger(neutralStateRoot), scopeRoot) ?? 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

package/src/registry/index.js

@@ -582,6 +582,8 @@ const WORKER_BILLING = new Set(['free', 'metered', 'unknown']);
 const WORKER_KEYS = Object.freeze(['profile', 'billing', ...Object.keys(WORKER_CAPABILITIES), 'modelChecks']);
 const WORKER_ALLOWED_KEYS = Object.freeze([...WORKER_KEYS, ...Object.keys(WORKER_OPTIONAL_CAPABILITIES), 'family']);
 const WORKER_ENTRY_FIELDS = new Set(['status', 'evidence', 'verification', 'verifiedOn', 'reason']);
+// Soft hyphen, Mongolian vowel separator, zero-width and directional marks, word joiner and invisible operators, BOM.
+const INVISIBLE_CHARACTER = /[\u00ad\u180e\u200b-\u200f\u202a-\u202e\u2060-\u2064\u2066-\u206f\ufeff]/;
 const WORKER_RECIPE_FIELDS = new Set(['binary', 'versionArgv', 'argv', 'promptVia', 'parser', 'marker', 'quotaSignals']);
 const WORKER_QUOTA_SIGNALS_FIELDS = new Set(['signals', 'basis', 'evidence']);
 const WORKER_FACTS = new Set(['hooksLoaded', 'identityForwarded', 'guidanceLoaded', 'login']);
@@ -681,10 +683,25 @@ function validateWorker(value     , location        , errors          )       {
       else {
         for (const field of Object.keys(quota)) if (!WORKER_QUOTA_SIGNALS_FIELDS.has(field)) fail(key, `quotaSignals has unknown field '${field}'`);
         if (!Array.isArray(quota.signals) || quota.signals.length < 1 || quota.signals.length > 16) fail(key, 'quotaSignals.signals must contain 1 to 16 signals');
-        else for (const signal of quota.signals) {
-          if (typeof signal !== 'string' || signal !== signal.trim() || signal.length < 3 || signal.length > 64 || /[\u0000-\u001f\u007f]/.test(signal)) {
-            fail(key, 'quotaSignals.signals must be trimmed strings of 3 to 64 characters without control characters');
-            break;
+        else {
+          const folded = new Set        ();
+          for (const signal of quota.signals) {
+            if (typeof signal !== 'string' || signal !== signal.trim() || signal.length < 3 || signal.length > 64 || /[\u0000-\u001f\u007f]/.test(signal)) {
+              fail(key, 'quotaSignals.signals must be trimmed strings of 3 to 64 characters without control characters');
+              break;
+            }
+            // The matcher lowercases both sides, so a signal that differs only by case never adds a match; a
+            // zero-width or format character makes one that reads like another yet matches nothing.
+            if (INVISIBLE_CHARACTER.test(signal)) {
+              fail(key, 'quotaSignals.signals must not contain zero-width or invisible format characters');
+              break;
+            }
+            const lowered = signal.toLowerCase();
+            if (folded.has(lowered)) {
+              fail(key, `quotaSignals.signals has a duplicate signal '${signal}' (compared without letter case)`);
+              break;
+            }
+            folded.add(lowered);
           }
         }
         if (quota.basis !== 'unverified' && quota.basis !== 'transcript') fail(key, "quotaSignals.basis must be 'unverified' or 'transcript'");

package/src/release/docs-blocks.js

@@ -463,7 +463,11 @@ function main(argv          , root         = REPO_ROOT)         {
   }
   const findings = argv[0] === '--write' ? writeAll(root) : checkAll(root);
   for (const finding of findings) process.stderr.write(`docs-blocks: ${finding.page}: ${finding.id}: ${finding.kind}${finding.detail ? ` (${oneLine(finding.detail)})` : ''}\n`);
-  if (findings.length && argv[0] === '--check') process.stderr.write('docs-blocks: run node src/release/docs-blocks.js --write, then review the diff\n');
+  if (findings.length && argv[0] === '--check') {
+    process.stderr.write('docs-blocks: run node src/release/docs-blocks.js --write, then review the diff\n');
+    // --write rewrites llms.txt from the pages; when the rewritten text is itself over the cap, only shorter descriptions fix it.
+    if (findings.some((f) => f.kind === 'over-cap')) process.stderr.write(`docs-blocks: llms.txt over ${LLMS_CAP} bytes: if --write leaves it over, shorten the page descriptions it is built from\n`);
+  }
   return findings.length ? 1 : 0;
 }
 

package/src/runtime/advice/doctor.js

@@ -116,12 +116,12 @@ async function buildAdviceDoctor({ repoRoot = REPO_ROOT, projectRoot = process.c
         decisionModels: [], lastCall: latestCall(window.records),
       };
     }
-    return { decisionModel, advice, _inspection: inspection, _offReason: setting.state === 'off' ? offReason(setting) : null };
+    return { decisionModel, advice, _inspection: inspection, _offReason: setting.state === 'off' ? (loaded.ok ? offReason(setting) : `unreadable advice registry: ${loaded.detail}`) : null };
   } catch (error     ) {
     return { decisionModel: { setting: { state: 'off', reason: 'config-invalid', decidedBy: { user: null, project: null }, modelFrom: null, notes: [error.message] },
       endpoint: { url: null, state: 'not-checked', version: null, minVersion: null, versionOk: false, message: null },
       model: { name: null, installed: false, decisionCapable: false }, decisionModels: [], lastCall: null },
-      advice: { windowDays: WINDOW_DAYS, store: 'advice-picks-user', kinds: [], unreadableLines: 0 }, _inspection: null, _offReason: 'unreadable setting in decision-model.json' };
+      advice: { windowDays: WINDOW_DAYS, store: 'advice-picks-user', kinds: [], unreadableLines: 0 }, _inspection: null, _offReason: `advice doctor could not complete: ${error.message}` };
   }
 }
 

package/src/runtime/brief-tools.js

@@ -328,7 +328,7 @@ function adviceRecord(result     ) {
 /**
  * The tier renderer remains synchronous/pure; optional local advice is requested afterward.
  */
-async function handleBriefToolsCommand({ owner, tier, harness, slug, headingLevel, tasks, json = false, repoRoot = REPO_ROOT, projectRoot = process.cwd(), env = process.env, buildAdapters = null, probe = probeProviders, adviceClient = null }      = {}) {
+async function handleBriefToolsCommand({ owner, tier, harness, slug, headingLevel, tasks, json = false, repoRoot = REPO_ROOT, projectRoot = process.cwd(), env = process.env, buildAdapters = null, probe = probeProviders, adviceClient = null, now = () => new Date() }      = {}) {
   if (!owner) return usageError('brief-tools', '--owner is required (the agent type the brief is for)', json);
   const level = headingLevel === undefined ? 2 : Number(headingLevel);
   if (level !== 2 && level !== 3) return usageError('brief-tools', `--heading-level must be 2 or 3, got '${headingLevel}'`, json);
@@ -349,6 +349,7 @@ async function handleBriefToolsCommand({ owner, tier, harness, slug, headingLeve
     let markdown = rendered.markdown;
     const record      = rendered.record;
     record.missing.push(...notes);
+    record.createdAt = now().toISOString();
 
     const taskIds = Array.isArray(tasks) ? tasks : typeof tasks === 'string' ? tasks.split(',').filter(Boolean) : [];
     if (taskIds.length) {

package/src/runtime/capability-router.js

@@ -298,6 +298,15 @@ class CapabilityRouter {
     };
   }
 
+  /** The registry's `capabilities.mcp.toolName` template for a harness id, or null when it has none. */
+  harnessToolTemplate(harnessId        )                {
+    return this.harnessList().find((item     ) => item.id === harnessId)?.capabilities?.mcp?.toolName || null;
+  }
+
+  harnessList()        {
+    return parseYamlFile(path.join(this.registryDir, 'harnesses.json'), this.fsImpl).harnesses || [];
+  }
+
   /**
    * Formats concrete execution instructions for a provider based on intent parameters.
    *
@@ -320,7 +329,17 @@ class CapabilityRouter {
     // back to the registry entry with that id.
     const mcp = provider.mcp
       || Object.values(this.capabilities).flatMap((cap     ) => cap.providers || []).find((p     ) => p.id === provider.id && p.mcp)?.mcp;
-    const mcpTool = mcp ? { mcpTool: `mcp__${mcp.server}__${mcp.tool}` } : {};
+    // Default (no `params.harness`): the Claude tool-name form, unchanged. With a target harness:
+    // that harness's registry `capabilities.mcp.toolName` template, or — when it has no verified
+    // template — the neutral `{server, tool}` identifiers and no tool name.
+    let mcpTool      = {};
+    if (mcp && !params.harness) mcpTool = { mcpTool: `mcp__${mcp.server}__${mcp.tool}` };
+    else if (mcp) {
+      const template = this.harnessToolTemplate(params.harness);
+      mcpTool = template
+        ? { mcpTool: template.replace('{server}', () => mcp.server).replace('{tool}', () => mcp.tool) }
+        : { mcp: { server: mcp.server, tool: mcp.tool } };
+    }
     const withDisplay = (result     ) => ({ ...mcpTool, ...result, ...(result.argv ? { cliCommand: result.argv.map(shellQuote).join(' ') } : {}) });
 
     if (provider.id === 'semble.search') {
@@ -580,15 +599,19 @@ class CapabilityRouter {
  * @param {string} [options.projectRoot]
  * @returns {number} exit code
  */
-function handleRouteCommand({ intent, query, check = false, json = false, projectRoot }      = {})         {
+function handleRouteCommand({ intent, query, check = false, json = false, projectRoot, harness }      = {})         {
   const router = new CapabilityRouter({ repoRoot: REPO_ROOT, projectRoot });
   if (typeof intent !== 'string' || intent.trim() === '') {
     return usageError('route', `--intent is required. Declared intents: ${Object.keys(router.routes).join(', ')}`, json);
   }
 
+  if (harness !== undefined && !router.harnessList().some((item     ) => item.id === harness)) {
+    return usageError('route', `unknown --harness '${harness}'. Known harnesses: ${router.harnessList().map((item     ) => item.id).join(', ')}`, json);
+  }
+
   let resolution     ;
   try {
-    resolution = router.resolveIntent(intent, { query, path: projectRoot || '.' }, { deepCheck: check });
+    resolution = router.resolveIntent(intent, { query, path: projectRoot || '.', ...(harness ? { harness } : {}) }, { deepCheck: check });
   } catch (error     ) {
     return usageError('route', `${error.message}. Declared intents: ${Object.keys(router.routes).join(', ')}`, json, error);
   }

package/src/runtime/context/pointer.js

@@ -40,6 +40,14 @@ function inside(root        , file        , fsImpl = fs)                {
   return normalized;
 }
 
+/** `file` as a '/'-separated path under `root` as written, links not resolved, or null when it is not under `root`.
+ * A pointer keeps this logical path: a linked `agent-docs/` must not hide a user file from the ledger's path test. */
+function logicalRel(root        , file        )                {
+  const relative = path.relative(path.resolve(root), path.resolve(file));
+  if (!relative || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return null;
+  return relative.split(path.sep).join('/');
+}
+
 function lineSlice(lines          , startLine        , endLine        )         {
   return lines.slice(startLine - 1, endLine).join('\n') + '\n';
 }
@@ -157,8 +165,10 @@ function collectPointers({ projectRoot, feature, fsImpl = fs, intakeFile }     )
   const root = path.resolve(projectRoot);
   const pointers        = [];
   for (const source of sourceFiles({ projectRoot: root, feature, fsImpl, intakeFile })) {
-  const rel = inside(root, source.absolute, fsImpl);
-    if (!rel) continue;
+  // The realpath decides whether the file is inside the project; the pointer names it as it is written.
+    const real = inside(root, source.absolute, fsImpl);
+    if (!real) continue;
+    const rel = logicalRel(root, source.absolute) ?? real;
     const user = source.user || Boolean(originOf(rel));
     let text        ;
     try {
@@ -184,9 +194,11 @@ function collectPointers({ projectRoot, feature, fsImpl = fs, intakeFile }     )
 }
 
 function readPointerSlice({ projectRoot, pointer, fsImpl = fs }     )                                           {
-  const rel = inside(projectRoot, path.resolve(projectRoot, pointer.path), fsImpl);
-  if (!rel || rel !== pointer.path) return null;
-  const file = path.resolve(projectRoot, rel);
+  // A pointer path is a plain relative path under the project (a logical one through a link, or an older
+  // pointer's realpath) whose realpath is inside it too.
+  const absolute = path.resolve(projectRoot, pointer.path);
+  if (!inside(projectRoot, absolute, fsImpl) || logicalRel(projectRoot, absolute) !== pointer.path) return null;
+  const file = absolute;
   try {
     const lines = fsImpl.readFileSync(file, 'utf8').split(/\r?\n/);
     const slice = lineSlice(lines, pointer.range.startLine, pointer.range.endLine);