@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/doctor-diff.js

@@ -1,40 +1,3 @@
-/**
- * Per-version, per-cwd resource diff for `agents doctor <agent[@version]>`.
- *
- * Mirrors what `syncResourcesToVersion` writes into a version home, then
- * compares each kind back against its resolved source (project > user > system
- * > extra repos). Surfaces:
- *   - ok       — present in home, content matches resolved source
- *   - diff     — present in home, content differs from resolved source
- *   - missing  — resolved source exists, not present in home
- *   - extra    — present in home, no source in any layer
- *
- * Coverage — every kind `syncResourcesToVersion` writes is content-aware, so a
- * byte change under an unchanged name is `diff`, never a false `ok` (PHNX-3504):
- *   commands, skills, hooks, rules — full content compare with source layer.
- *   mcp        — structural compare of the home server def vs resolved source.
- *   subagents  — re-render source through the registry transform, byte-compare.
- *   workflows  — layout-aware per-harness content compare (dir tree or file).
- *   memory     — knowledge facts (~/.agents/memory/*.md), per-fact byte-compare.
- *   plugins    — per-item content compare of the marketplace mirror.
- *   permissions — per-rule compare in the harness's native vocabulary for the
- *     representable harnesses (claude/opencode/cursor/droid/openclaw); the lossy
- *     TOML/flag harnesses stay presence-only with an honest `detail`, never a
- *     faked `ok`.
- * A completeness test binds `DOCTOR_ALL_KINDS` to the writer set so a future
- * synced kind cannot silently become a blind spot. `promptcuts` is NOT a kind —
- * it is not version-scoped, so there is nothing per-home to diff.
- *
- * Intentional asymmetries (must mirror sync):
- *   - hooks ignore the project layer (`syncResourcesToVersion` skips
- *     project/.agents/hooks/ for safety).
- *   - rules/AGENTS.md is compared against the preset composition the rules writer
- *     emits (`composeRulesFromState`), re-rendered from the current `subrules/`
- *     fragments — so a fragment edit is caught even though `rules/AGENTS.md`
- *     never changed. A non-@-import home compiled by `agents refresh-rules`
- *     carries a leading `COMPILED_HEADER`, which is stripped before comparing so
- *     a header-compiled home still reconciles (the header is not source content).
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { AGENTS, agentConfigDirName, getMcpConfigPathForHome } from './agents.js';
@@ -88,19 +51,6 @@ function readSafe(file) {
 function fileExists(p) {
     return !!p && fs.existsSync(p) && !fs.lstatSync(p).isSymbolicLink();
 }
-/**
- * True when `filePath` is a git symlink that was CHECKED OUT AS A PLAIN TEXT
- * FILE — the shape git produces on a client without symlink support (Windows
- * without Developer Mode, `core.symlinks=false`). Such a file holds exactly the
- * link target (a relative path, no trailing newline) instead of the pointed-to
- * content. `lstat().isSymbolicLink()` is FALSE for it, so callers that only
- * skip real symlinks (e.g. the rules/permissions alias files CLAUDE.md /
- * GEMINI.md, which are symlinks to AGENTS.md in the repo) wrongly treat it as
- * an independent resource that no sync can ever reconcile (PHNX-3187). The
- * signal is unambiguous: a whole file with no newline whose entire content
- * resolves to an existing sibling path. Real markdown rule files always contain
- * newlines, so this never false-positives on genuine content.
- */
 export function isCheckedOutSymlink(filePath) {
     let content;
     try {
@@ -109,8 +59,6 @@ export function isCheckedOutSymlink(filePath) {
     catch {
         return false;
     }
-    // A git symlink blob is the bare target with no newline; any newline means
-    // this is real file content, not a link.
     if (content.length === 0 || content.length > 255 || /[\r\n]/.test(content))
         return false;
     const target = content.trim();
@@ -146,11 +94,6 @@ function buildLayerBases(cwd, kind, opts = {}) {
         out.push({ layer: 'extra', path: path.join(e.dir, kind), alias: e.alias });
     return out;
 }
-/**
- * Resolve directory-shaped source resources of `kind` by name across the layers
- * (project > user > system > extra; first layer wins a name collision), keeping
- * only entries whose directory satisfies `predicate` (e.g. holds `AGENT.md`).
- */
 function resolveSourceDirsByName(kind, cwd, excludeProject, predicate) {
     const out = new Map();
     for (const base of buildLayerBases(cwd, kind, { excludeProject })) {
@@ -176,18 +119,12 @@ function resolveSourceDirsByName(kind, cwd, excludeProject, predicate) {
     }
     return out;
 }
-// ─── commands ─────────────────────────────────────────────────────────────────
 function diffCommands(agent, version, cwd, excludeProject = false) {
     const agentConfig = AGENTS[agent];
     const isToml = agentConfig.format === 'toml';
     const ext = isToml ? '.toml' : '.md';
     const homeDir = getVersionCommandsDir(agent, version);
-    // Command-as-skill agents (kimi, codex>=0.117, grok) install every command as a
-    // SKILL wrapper at <agentDir>/skills/<cmd>/SKILL.md, not a native command file.
-    // The compare must follow that or every command false-reports as drifted.
     const asSkill = shouldInstallCommandAsSkill(agent, version);
-    // Agents that hold commands neither natively nor as skills (e.g. goose) must not
-    // report source commands as "missing" — they structurally can't take them.
     if (!asSkill && !supports(agent, 'commands', version).ok)
         return [];
     const agentDir = path.join(getVersionHomePath(agent, version), agentConfigDirName(agent));
@@ -208,10 +145,6 @@ function diffCommands(agent, version, cwd, excludeProject = false) {
             if (!entry.isFile() || !entry.name.endsWith('.md'))
                 continue;
             const name = entry.name.replace(/\.md$/, '');
-            // Directory docs (README/AGENTS/CLAUDE/GEMINI) live in commands/ but are
-            // documentation, not commands. `discoverCommands` and `resolveResource`
-            // both refuse them, so the sync writer never installs them — mirror that
-            // here or every one false-reports as a missing command no sync can clear.
             if (isDirectoryDoc('commands', name))
                 continue;
             if (sourceByName.has(name))
@@ -219,24 +152,12 @@ function diffCommands(agent, version, cwd, excludeProject = false) {
             sourceByName.set(name, { layer: base.layer, path: path.join(base.path, entry.name), alias: base.alias });
         }
     }
-    // The trusted skill roots the commands-as-skills writer consults to decide
-    // whether a real skill of the same name already owns a command's target slot.
     const skillRoots = asSkill ? trustedSkillRoots() : [];
     const rows = [];
     const seen = new Set();
     for (const [name, src] of sourceByName) {
         seen.add(name);
         if (!installed.has(name)) {
-            // Command-as-skill agents (codex >= 0.117, kimi): when a real skill of the
-            // same name exists in the sources, the skill wins the shared
-            // `skills/<name>/` slot and `installCommandSkillToVersion` deliberately
-            // writes no command wrapper (versions.ts keeps the real skill in
-            // skillsToSync and overwrites any wrapper). The command's behavior is
-            // provided by that same-named skill, so it is NOT missing drift — reporting
-            // it so drove an unclearable "N missing" loop (PHNX-3186). Mirror the
-            // writer's skip predicate exactly: a skill source of this name whose
-            // `agents_command` marker is not this command (a real skill, or a different
-            // command).
             if (asSkill && skillSourceExists(name, skillRoots) && readSkillSourceCommandMarker(name, skillRoots) !== name) {
                 rows.push({
                     kind: 'commands',
@@ -252,7 +173,6 @@ function diffCommands(agent, version, cwd, excludeProject = false) {
             continue;
         }
         if (asSkill) {
-            // Compare against the installed command-skill wrapper, not a native path.
             const matches = commandSkillMatches(agentDir, name, src.path);
             rows.push({
                 kind: 'commands',
@@ -265,7 +185,6 @@ function diffCommands(agent, version, cwd, excludeProject = false) {
             continue;
         }
         if (agent === 'goose') {
-            // Compare against the installed Goose recipe YAML + slash_commands registration.
             const matches = gooseCommandMatches(getVersionHomePath(agent, version), name, src.path);
             rows.push({
                 kind: 'commands',
@@ -295,17 +214,10 @@ function diffCommands(agent, version, cwd, excludeProject = false) {
             homePath,
         });
     }
-    // Plugin-bundled commands (installed as `<plugin>-<cmd>`) are source-managed by
-    // their plugin, tracked under the `plugins` kind — not extras. Without this,
-    // `agents doctor` shows every plugin command (swarm-plan, code-review, …) as an
-    // unmanaged extra, mirroring the orphan false-positive the prune path had.
     const pluginCommands = listPluginCommandNames();
     for (const name of installed) {
         if (seen.has(name))
             continue;
-        // Directory docs are excluded from the source scan above; a leftover copy in
-        // the home is not a command orphan — leave it out of the command diff
-        // entirely rather than flip it to a spurious `extra` row.
         if (isDirectoryDoc('commands', name))
             continue;
         if (pluginCommands.has(name))
@@ -319,14 +231,7 @@ function diffCommands(agent, version, cwd, excludeProject = false) {
     }
     return rows.sort((a, b) => a.name.localeCompare(b.name));
 }
-// ─── skills ───────────────────────────────────────────────────────────────────
 function diffSkills(agent, version, cwd, excludeProject = false) {
-    // Native ~/.agents/skills consumers (Gemini, …) read central skills directly.
-    // The orchestrator DELETES their version-home skills dir (syncResourcesToVersion)
-    // and registers no skills writer, so there is nothing in the version home to
-    // reconcile. Mirror diffVersionSkills' native gate (skills.ts) — without it
-    // every central skill is false-reported `missing` and held as unreconcilable
-    // forever (drift never clears for these agents).
     if (AGENTS[agent].nativeAgentsSkillsDir)
         return [];
     const homeDir = getVersionSkillsDir(agent, version);
@@ -379,15 +284,11 @@ function diffSkills(agent, version, cwd, excludeProject = false) {
     }
     return rows.sort((a, b) => a.name.localeCompare(b.name));
 }
-// ─── hooks ────────────────────────────────────────────────────────────────────
 function diffHooks(agent, version, cwd, inventory) {
     if (!AGENTS[agent].supportsHooks)
         return [];
     const installedByName = new Map(inventory.onDisk.map((e) => [e.name, e]));
-    // Sync intentionally excludes project/.agents/hooks/ — mirror that.
     const layerBases = buildLayerBases(cwd, 'hooks', { excludeProject: true });
-    // Group source files the same way the hook installer does (basename across
-    // script + sidecar data file); first-layer wins on name collision.
     const sourceByName = new Map();
     for (const base of layerBases) {
         if (!fs.existsSync(base.path))
@@ -434,7 +335,6 @@ function diffHooks(agent, version, cwd, inventory) {
     }
     return rows.sort((a, b) => a.name.localeCompare(b.name));
 }
-// ─── rules / memory ───────────────────────────────────────────────────────────
 function listRulesNames(cwd, excludeProject = false) {
     const projectDir = excludeProject ? null : getProjectAgentsDir(cwd);
     const userRules = getUserRulesDir();
@@ -463,10 +363,6 @@ function listRulesNames(cwd, excludeProject = false) {
                 continue;
             const filePath = path.join(base.path, file);
             const stat = fs.lstatSync(filePath);
-            // Skip the CLAUDE.md / GEMINI.md alias symlinks — both when they are real
-            // symlinks (posix) and when git checked them out as plain text files
-            // (Windows), so they are never mistaken for independent rule sources the
-            // writer can't produce (PHNX-3187).
             if (stat.isSymbolicLink() || isCheckedOutSymlink(filePath))
                 continue;
             const name = file.replace(/\.md$/, '');
@@ -478,26 +374,14 @@ function listRulesNames(cwd, excludeProject = false) {
     return out;
 }
 function expectedRuleContent(agent, name, version, sourcePath) {
-    // The instruction file (AGENTS → the agent's CLAUDE.md/GEMINI.md/AGENTS.md)
-    // is COMPOSED from `subrules/` fragments for the version's active preset —
-    // that is exactly what the rules writer emits (see
-    // staleness/writers/rules.ts → composeRulesFromState). Compare against the
-    // same rendering so a correctly-synced home file reconciles instead of being
-    // held forever against the raw `rules/AGENTS.md` (the whole-repo doc, which a
-    // preset composition deliberately never equals — system subrules don't
-    // auto-append). The `agent` is not part of the rendering (every capable agent
-    // gets identical composed bytes); it is kept for symmetry with the writer's
-    // per-agent dispatch and future per-agent presets.
     if (name === 'AGENTS') {
         try {
             return composeRulesFromState({ preset: getActiveRulesPreset(agent, version) }).content;
         }
         catch {
-            // No rules.yaml / unknown preset — the writer skips too; treat as unknown.
             return null;
         }
     }
-    // Any sibling top-level rules file syncs as a raw copy.
     return readSafe(sourcePath);
 }
 function diffRules(agent, version, cwd, excludeProject = false) {
@@ -505,11 +389,6 @@ function diffRules(agent, version, cwd, excludeProject = false) {
     const versionHome = getVersionHomePath(agent, version);
     const configDir = path.join(versionHome, agentConfigDirName(agent));
     const sourcesByName = listRulesNames(cwd, excludeProject);
-    // Files actually present in the version home. Include *.md siblings AND the
-    // agent's own instructions filename even when it is not *.md — cursor's rules
-    // file is `.cursorrules`, so an `.md`-only scan never saw it and reported the
-    // AGENTS rule `missing` on every sync, a phantom no reconcile could clear
-    // (PHNX-3186).
     const homeFiles = new Set();
     if (fs.existsSync(configDir)) {
         for (const f of fs.readdirSync(configDir)) {
@@ -534,10 +413,6 @@ function diffRules(agent, version, cwd, excludeProject = false) {
             rows.push({ kind: 'rules', name, status: 'diff', source: src.layer, sourcePath: src.path, homePath });
             continue;
         }
-        // A non-@-import home compiled by `agents refresh-rules` carries a leading
-        // COMPILED_HEADER the raw preset composition does not. Strip it before the
-        // compare so a header-compiled home still reconciles — the header is
-        // agents-cli provenance, not source content (PHNX-3504).
         if (name === 'AGENTS' && !supportsRulesImports(agent) && actual.startsWith(COMPILED_HEADER)) {
             actual = actual.slice(COMPILED_HEADER.length);
         }
@@ -550,10 +425,6 @@ function diffRules(agent, version, cwd, excludeProject = false) {
             homePath,
         });
     }
-    // Anything in the configDir matching an instructions filename or AGENTS.md
-    // but with no source is an extra. We only report files that look like rules
-    // — i.e. the agent's instructionsFile, plus any *.md siblings that came
-    // from the rules sync.
     const rulesFilenames = new Set();
     rulesFilenames.add(agentConfig.instructionsFile);
     for (const targetName of homeSeen)
@@ -568,14 +439,11 @@ function diffRules(agent, version, cwd, excludeProject = false) {
     }
     return rows.sort((a, b) => a.name.localeCompare(b.name));
 }
-// ─── mcp (content-aware) ────────────────────────────────────────────────────
 function diffMcp(agent, version, cwd, available, synced) {
     const versionHome = getVersionHomePath(agent, version);
     const syncedSet = new Set(synced);
     const availableSet = new Set(available);
     const homePath = getMcpConfigPathForHome(agent, versionHome);
-    // Resolve each available server's source def once (project trust off — this is
-    // a read-only diff, and the writer applies the same servers).
     const sourceByName = new Map(getMcpServersByName(available, { cwd, enforceProjectTrust: false }).map((s) => [s.name, s]));
     const rows = [];
     for (const name of available) {
@@ -599,7 +467,6 @@ function diffMcp(agent, version, cwd, available, synced) {
     }
     return rows.sort((a, b) => a.name.localeCompare(b.name));
 }
-// ─── permissions (content-aware where the native format allows) ──────────────
 function diffPermissions(agent, version, available, synced) {
     const versionHome = getVersionHomePath(agent, version);
     const syncedSet = new Set(synced);
@@ -616,9 +483,6 @@ function diffPermissions(agent, version, available, synced) {
             rows.push({ kind: 'permissions', name, status: matches ? 'ok' : 'diff' });
         }
         else {
-            // Lossy TOML/flag harness — the on-disk format carries no faithful
-            // per-group rule provenance, so we can only attest presence. Say so
-            // explicitly rather than fake a verified `ok` (PHNX-3504).
             rows.push({ kind: 'permissions', name, status: 'ok', detail: 'format cannot verify content' });
         }
     }
@@ -628,14 +492,10 @@ function diffPermissions(agent, version, available, synced) {
     }
     return rows.sort((a, b) => a.name.localeCompare(b.name));
 }
-// ─── subagents (content-aware) ───────────────────────────────────────────────
 function diffSubagents(agent, version, cwd, available, synced) {
     const versionHome = getVersionHomePath(agent, version);
     const syncedSet = new Set(synced);
     const availableSet = new Set(available);
-    // Resolve sources across the SAME layers `available` was built from
-    // (getAvailableResources is project-inclusive), so every available name finds
-    // its source dir for the content compare rather than false-diffing.
     const sourceByName = resolveSourceDirsByName('subagents', cwd, false, (dir) => fs.existsSync(path.join(dir, 'AGENT.md')));
     const rows = [];
     for (const name of available) {
@@ -659,7 +519,6 @@ function diffSubagents(agent, version, cwd, available, synced) {
     }
     return rows.sort((a, b) => a.name.localeCompare(b.name));
 }
-// ─── workflows (content-aware) ───────────────────────────────────────────────
 function diffWorkflows(agent, version, cwd, available, synced) {
     const versionHome = getVersionHomePath(agent, version);
     const syncedSet = new Set(synced);
@@ -685,22 +544,12 @@ function diffWorkflows(agent, version, cwd, available, synced) {
     }
     return rows.sort((a, b) => a.name.localeCompare(b.name));
 }
-// ─── memory (knowledge facts — content-aware) ────────────────────────────────
-/**
- * Diff synced knowledge-fact memory (~/.agents/memory/*.md fanned into each
- * capable home under `memoryTargetDir`). Distinct from the rules-preset list
- * that overloads `AvailableResources.memory` — this reads the canonical facts
- * (`listMemoryFacts`) and the home copies bounded by the `.agents-cli-memory.json`
- * manifest, so an untracked native memory file the user authored is never
- * mistaken for drift (PHNX-3504).
- */
 function diffMemory(agent, version, cwd) {
     if (!supports(agent, 'memory', version).ok)
         return [];
     const versionHome = getVersionHomePath(agent, version);
     const targetDir = path.join(versionHome, memoryTargetDir(agent));
     const facts = listMemoryFacts(cwd);
-    // The manifest names exactly the fact files agents-cli wrote (plus 'MEMORY').
     const managedManifestPath = path.join(targetDir, '.agents-cli-memory.json');
     let managed = [];
     try {
@@ -708,7 +557,7 @@ function diffMemory(agent, version, cwd) {
         if (Array.isArray(raw.facts))
             managed = raw.facts.filter((f) => typeof f === 'string');
     }
-    catch { /* no manifest → nothing managed yet */ }
+    catch { }
     const managedSet = new Set(managed);
     const rows = [];
     const factNames = new Set(facts.map((f) => f.name));
@@ -728,9 +577,6 @@ function diffMemory(agent, version, cwd) {
             homePath,
         });
     }
-    // A managed fact still on disk but no longer in the canonical set is an orphan
-    // the next sync would prune — surface it as extra. Never flag 'MEMORY' (the
-    // index, always regenerated) or an unmanaged native file (not ours to reconcile).
     for (const name of managedSet) {
         if (name === 'MEMORY' || factNames.has(name))
             continue;
@@ -740,7 +586,6 @@ function diffMemory(agent, version, cwd) {
     }
     return rows.sort((a, b) => a.name.localeCompare(b.name));
 }
-// ─── plugins (content-aware) ───────────────────────────────────────────────
 function listPluginSkillDirs(pluginDir) {
     const d = path.join(pluginDir, 'skills');
     try {
@@ -761,13 +606,6 @@ function listPluginCommandFiles(pluginDir) {
         return [];
     }
 }
-/**
- * Describe how a version's marketplace MIRROR of a plugin diverges from its
- * central source — the detail presence-only checks miss. Surfaces a stale mirror
- * version, a Claude-invalid manifest, and (the part users care about) the
- * plugin's own skills/commands that never made it into the mirror. Returns null
- * when the mirror faithfully matches source.
- */
 export function describePluginDrift(central, mirrorDir) {
     if (!fs.existsSync(mirrorDir))
         return 'mirror missing';
@@ -795,12 +633,6 @@ export function describePluginDrift(central, mirrorDir) {
         parts.push(`missing skill${missSkills.length > 1 ? 's' : ''}: ${missSkills.join(', ')}`);
     if (missCmds.length)
         parts.push(`missing command${missCmds.length > 1 ? 's' : ''}: ${missCmds.join(', ')}`);
-    // Content drift of a skill/command that exists in BOTH — the mirror kept the
-    // dir/file but its bytes went stale (PHNX-2955: a skill edit landed on origin
-    // and was pulled into central, but the per-version marketplace copy was never
-    // refreshed, so agents kept executing the OLD skill text while `plugins list`
-    // and `doctor` reported it `everywhere`/`ok`). Presence alone missed this; a
-    // content compare is what turns a stale mirror into a reportable `diff`.
     const staleSkills = centralSkills
         .filter((s) => mirrorSkills.has(s))
         .filter((s) => !dirsContentMatch(path.join(central.root, 'skills', s), path.join(mirrorDir, 'skills', s)))
@@ -826,7 +658,7 @@ function diffPlugins(agent, version, cwd) {
     const seen = new Set();
     for (const p of discoverPlugins({ cwd })) {
         if (seen.has(p.name))
-            continue; // dedupe across marketplaces for the readout
+            continue;
         seen.add(p.name);
         if (!synced.has(p.name)) {
             rows.push({ kind: 'plugins', name: p.name, status: 'missing', sourcePath: p.root });
@@ -854,8 +686,6 @@ export function diffVersionResources(agent, version, options = {}) {
     const excludeProject = options.excludeProject ?? false;
     const home = getVersionHomePath(agent, version);
     const requested = new Set(options.kinds ?? ALL_KINDS);
-    // When excluding the project layer, resolve every per-cwd lookup against a
-    // neutral cwd so no `<cwd>/.agents/` is ever discovered.
     const cwd = rawCwd;
     const projectDir = excludeProject ? null : getProjectAgentsDir(cwd);
     const available = getAvailableResources(cwd);
@@ -879,9 +709,6 @@ export function diffVersionResources(agent, version, options = {}) {
     const hookInventory = requested.has('hooks') ? getResourceInventory(agent, version, 'hooks', { cwd }) : undefined;
     if (hookInventory)
         empty.hooks = diffHooks(agent, version, cwd, hookInventory);
-    // Wiring check: a hook FILE can be present and byte-identical to source (ok
-    // above) yet never referenced in settings.json, so it never fires. Only
-    // meaningful when hooks are in scope.
     const hookWiring = hookInventory?.wiring;
     if (requested.has('rules'))
         empty.rules = diffRules(agent, version, cwd, excludeProject);
@@ -890,17 +717,11 @@ export function diffVersionResources(agent, version, options = {}) {
     if (requested.has('permissions')) {
         empty.permissions = diffPermissions(agent, version, supports(agent, 'allowlist', version).ok ? available.permissions : [], synced.permissions);
     }
-    // Subagents are version-gated (e.g. kimi >= 0.29.0). A version below the floor
-    // is never written any subagent by the sync writer, so counting the source
-    // ones as "missing" is phantom drift no sync can clear (PHNX-3186). Zero the
-    // available set when unsupported; a stale installed copy still surfaces `extra`.
     if (requested.has('subagents')) {
         empty.subagents = diffSubagents(agent, version, cwd, supports(agent, 'subagents', version).ok ? available.subagents : [], synced.subagents);
     }
     if (requested.has('plugins'))
         empty.plugins = diffPlugins(agent, version, cwd);
-    // Workflows are version-gated too (e.g. grok >= 0.2.111); zero the available
-    // set below the floor so a source workflow is not phantom-missing drift.
     if (requested.has('workflows')) {
         empty.workflows = diffWorkflows(agent, version, cwd, supports(agent, 'workflows', version).ok ? available.workflows : [], synced.workflows);
     }

package/dist/lib/drift-sync.d.ts

@@ -1,46 +1,17 @@
-/**
- * Interactive drift-sync flow — the single "we detected drift, want to fix it?"
- * action, shared by `agents sync status`, `agents doctor`, and the menu-bar "NEEDS
- * SYNC" row.
- *
- * It composes existing pieces, re-implementing nothing:
- *   - computeSyncStatus()          — the unified detection engine (sync-status.ts)
- *   - pullRepo()                   — fast-forward the `.system` repo (git.ts)
- *   - promptAgentVersionSelection() — the "which agent types / versions?" picker
- *   - repairAfterSync()            — the shared post-reconcile repair pass
- *                                    `agents sync` runs (heal + hook rewire +
- *                                    managed hook runtime shim repair)
- *
- * Combined flow (one confirmation): if `.system` is behind AND resources drifted,
- * a single "Sync all detected" both pulls `.system` and reconciles the chosen
- * version homes. The security posture is preserved — the `.system` pull only ever
- * happens on an explicit user choice here, never silently (see auto-pull-worker.ts
- * for why system auto-pull is off by default).
- */
 import { type VersionHealResult } from './heal.js';
 import { type UnifiedSyncStatus } from './sync-status.js';
 interface DriftSyncOptions {
     cwd?: string;
-    /** Reconcile everything detected with no prompts — the "kick it" path, also the
-     * non-TTY / menu-bar-launched-with-flag behavior. Pulls `.system` if behind. */
     yes?: boolean;
-    /** Pre-computed status, to avoid a second scan when the caller already has one. */
     status?: UnifiedSyncStatus;
-    /** Skip the drift summary — set by callers that already printed their own. */
     quiet?: boolean;
 }
 interface DriftSyncResult {
     systemBehindBefore: number;
     systemPulled: boolean;
     healed: VersionHealResult[];
-    /** True when the user declined at the prompt (nothing was changed). */
     cancelled: boolean;
-    /** True when there was no drift to act on in the first place. */
     nothingToDo: boolean;
 }
-/**
- * The unified "drift detected — sync now?" flow. Returns a structured result so
- * callers (menu-bar, doctor) can report without re-scanning.
- */
 export declare function promptDriftSync(opts?: DriftSyncOptions): Promise<DriftSyncResult>;
 export {};

package/dist/lib/drift-sync.js

@@ -1,22 +1,3 @@
-/**
- * Interactive drift-sync flow — the single "we detected drift, want to fix it?"
- * action, shared by `agents sync status`, `agents doctor`, and the menu-bar "NEEDS
- * SYNC" row.
- *
- * It composes existing pieces, re-implementing nothing:
- *   - computeSyncStatus()          — the unified detection engine (sync-status.ts)
- *   - pullRepo()                   — fast-forward the `.system` repo (git.ts)
- *   - promptAgentVersionSelection() — the "which agent types / versions?" picker
- *   - repairAfterSync()            — the shared post-reconcile repair pass
- *                                    `agents sync` runs (heal + hook rewire +
- *                                    managed hook runtime shim repair)
- *
- * Combined flow (one confirmation): if `.system` is behind AND resources drifted,
- * a single "Sync all detected" both pulls `.system` and reconciles the chosen
- * version homes. The security posture is preserved — the `.system` pull only ever
- * happens on an explicit user choice here, never silently (see auto-pull-worker.ts
- * for why system auto-pull is off by default).
- */
 import chalk from 'chalk';
 import { select, confirm } from '@inquirer/prompts';
 import { AGENTS } from './agents.js';
@@ -26,7 +7,6 @@ import { promptAgentVersionSelection } from './installations/versions.js';
 import { isInteractiveTerminal, isPromptCancelled } from './format.js';
 import { computeSyncStatus, formatDriftRows } from './sync-status.js';
 const agentName = (id) => AGENTS[id]?.name ?? id;
-/** "claude@2.1.170  2 drifted · 1 missing" for one version. */
 function versionLine(v) {
     const bits = [];
     if (v.counts.drifted)
@@ -36,7 +16,6 @@ function versionLine(v) {
     const label = `${agentName(v.agent)}@${v.version}`;
     return `  ${label.padEnd(28)} ${chalk.yellow(bits.join(' · '))}`;
 }
-/** Render the drift summary (system freshness + each version owed a sync). */
 function renderSummary(status, needing) {
     console.log(chalk.bold('\nSync status'));
     if (status.system.behind > 0) {
@@ -51,7 +30,6 @@ function renderSummary(status, needing) {
         console.log(chalk.gray(`  (${status.totals.orphan} orphan${status.totals.orphan === 1 ? '' : 's'} — run \`agents prune cleanup\`)`));
     }
 }
-/** Fast-forward the `.system` repo. Returns whether it actually moved. */
 async function pullSystem(status) {
     if (status.system.behind <= 0)
         return false;
@@ -63,15 +41,6 @@ async function pullSystem(status) {
     console.log(chalk.red(`Could not pull .system: ${res.error ?? 'unknown error'}`));
     return false;
 }
-/**
- * Reconcile a set of versions grouped by agent through the SHARED post-reconcile
- * repair pass (`repairAfterSync`) — the same superset the three `agents sync`
- * handlers run. Beyond the resources `heal()` fills, this also re-wires hooks
- * left unwired and repairs broken managed hook runtime shims, so drift-sync is
- * not a third orchestrator that silently skips shim repair. Renders each pass's
- * rewire / shim-repair detail; the heal rollup is printed separately by the
- * caller via `reportHealed`.
- */
 async function healVersions(versionsByAgent, cwd) {
     const out = [];
     for (const [agent, versions] of versionsByAgent) {
@@ -83,7 +52,6 @@ async function healVersions(versionsByAgent, cwd) {
     }
     return out;
 }
-/** Report which agents received what after a heal. */
 function reportHealed(healed) {
     const touched = healed.filter((v) => v.healed.length > 0);
     if (touched.length === 0) {
@@ -103,10 +71,6 @@ function groupNeeding(needing) {
     }
     return m;
 }
-/**
- * The unified "drift detected — sync now?" flow. Returns a structured result so
- * callers (menu-bar, doctor) can report without re-scanning.
- */
 export async function promptDriftSync(opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
     const status = opts.status ?? (await computeSyncStatus({ cwd }));
@@ -125,10 +89,8 @@ export async function promptDriftSync(opts = {}) {
     }
     if (!opts.quiet)
         renderSummary(status, needing);
-    // Non-interactive OR explicit --yes: reconcile everything detected.
     if (opts.yes || !isInteractiveTerminal()) {
         if (!opts.yes) {
-            // Non-TTY without --yes: report, don't act, don't throw.
             console.log(chalk.gray('\nRun `agents sync status --yes` to sync, or `agents sync status` in a terminal to choose.'));
             return base;
         }
@@ -137,7 +99,6 @@ export async function promptDriftSync(opts = {}) {
         reportHealed(healed);
         return { ...base, systemPulled, healed };
     }
-    // Interactive gate.
     let choice;
     try {
         choice = await select({
@@ -163,7 +124,6 @@ export async function promptDriftSync(opts = {}) {
         reportHealed(healed);
         return { ...base, systemPulled, healed };
     }
-    // choice === 'choose': optional .system pull, then per-agent/version selection.
     let systemPulled = false;
     if (systemBehind > 0) {
         try {