@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/project-pull.js

@@ -1,21 +1,3 @@
-/**
- * Project pull — fast-forward every fleet checkout of a named project.
- *
- * Safety contract (binding for all paths in this module):
- *   - Dirty trees are blocked immediately (no fetch attempted).
- *   - Only checkouts on the remote's default branch are fast-forwarded.
- *   - Local commits ahead of upstream block the pull.
- *   - Fast-forward ONLY — no rebase, no reset, no history rewrite.
- *   - Missing checkouts are reported, never cloned.
- *   - Malformed or partial peer envelopes fail CLOSED and LOUD (the parse
- *     returns `valid: false`, so the peer lands in `parseFailed` and drives a
- *     non-zero exit — never an empty result set that reads as "nothing to do").
- *   - Git hook symlinks are NEVER installed during a pull.
- *
- * The fan-out extends the `projects status` seam: the same
- * `projectRepoTargetsForDef` expansion drives both commands, so they
- * always operate on exactly the same set of directories.
- */
 import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -24,56 +6,18 @@ import { expandLocalHome } from './project-root.js';
 import { getRepoCommit, getRemoteUrl, pullRepo } from './git.js';
 import { parseOwnerRepoFromRemote } from './registry.js';
 import { machineId } from './machine-id.js';
-// ---------------------------------------------------------------------------
-// Target fingerprint
-// ---------------------------------------------------------------------------
-/**
- * Deterministic hash of a target list so the orchestrator can verify the peer
- * pulled the same set of directories it intended to request. Computed from the
- * canonical `path\0expectedSlug` representation, sorted so insertion order does
- * not matter.
- */
 export function fingerprintTargets(targets) {
     const lines = targets
         .map((t) => `${t.path}\0${t.expectedSlug ?? ''}`)
         .sort();
     return crypto.createHash('sha256').update(lines.join('\n')).digest('hex').slice(0, 16);
 }
-// ---------------------------------------------------------------------------
-// Target wire encoding (the `pull` → `pull-local` CLI-arg boundary)
-// ---------------------------------------------------------------------------
-/**
- * Encode a target list as the single `--targets` argument the orchestrating
- * `pull` hands to a peer's hidden `pull-local`.
- *
- * A target is a `{ path, expectedSlug }` PAIR, and both halves must survive the
- * hop: `expectedSlug` is what makes the peer refuse to fast-forward a directory
- * whose `origin` is a different repo, and it is also hashed into
- * {@link fingerprintTargets}. Sending bare paths therefore broke the fan-out
- * twice over — slug verification silently became a no-op on every peer, and the
- * peer's slug-less fingerprint could never match the caller's, so
- * {@link parseProjectPullEnvelope} discarded the peer's whole result set. JSON
- * keeps the pair intact; both transports quote it as one argument
- * (`shellQuote` on bash, `powershellQuote` inside a base64 `-EncodedCommand`
- * on Windows), so no escaping is owed here.
- */
 export function encodePullTargets(targets) {
     return JSON.stringify(targets.map((t) => (t.expectedSlug === undefined ? { path: t.path } : { path: t.path, expectedSlug: t.expectedSlug })));
 }
-/**
- * The exact `agents …` argv the fleet fan-out runs on each peer. Owned here,
- * beside the decoder, so the two halves of the hop cannot drift apart and a
- * test can exercise the real caller-side arguments rather than a retyped copy.
- */
 export function pullLocalArgs(targets) {
     return ['projects', 'pull-local', '--targets', encodePullTargets(targets)];
 }
-/**
- * Decode the `--targets` argument back into targets on the peer. THROWS on any
- * malformed input rather than returning a partial list: a peer that cannot tell
- * exactly which directories it was asked to pull must fail loudly, not
- * fast-forward a guessed subset.
- */
 export function decodePullTargets(raw) {
     let parsed;
     try {
@@ -98,22 +42,10 @@ export function decodePullTargets(raw) {
             : { path: o.path, expectedSlug: o.expectedSlug };
     });
 }
-// ---------------------------------------------------------------------------
-// Local pull
-// ---------------------------------------------------------------------------
-/**
- * Pull each target on THIS machine, sequentially (concurrent worktree writes
- * can corrupt the git index). Returns one result per target.
- *
- * Missing checkouts (no directory or no `.git`) are reported as `missing` and
- * skipped — never cloned. A slug mismatch (the directory's `origin` remote does
- * not match the expected slug) is reported as `blocked`.
- */
 export async function pullProjectTargets(targets, host = machineId()) {
     const results = [];
     for (const target of targets) {
         const absPath = expandLocalHome(target.path);
-        // Missing directory or not a git repo: report and skip.
         if (!fs.existsSync(absPath) || !fs.existsSync(path.join(absPath, '.git'))) {
             results.push({
                 host,
@@ -124,11 +56,6 @@ export async function pullProjectTargets(targets, host = machineId()) {
             });
             continue;
         }
-        // Slug verification: if the project def declares a slug, the directory's
-        // origin must match it. A mismatch means the path hosts a different repo
-        // and we must not fast-forward it under a wrong project's command.
-        // An unreadable remote URL or an unrecognised remote shape is also blocked —
-        // we cannot confirm the checkout is the right repo, so we fail closed.
         if (target.expectedSlug) {
             const remoteUrl = await getRemoteUrl(absPath);
             if (remoteUrl === null) {
@@ -163,11 +90,8 @@ export async function pullProjectTargets(targets, host = machineId()) {
                 continue;
             }
         }
-        // Capture HEAD before the pull for the before→after diff in output.
-        // getRepoCommit already returns an 8-char short hash and never throws.
         const beforeRaw = await getRepoCommit(absPath);
         const before = beforeRaw === 'unknown' ? undefined : beforeRaw;
-        // Fast-forward in strict mode. The option contract is documented on PullRepoOptions.
         let pull;
         try {
             pull = await pullRepo(absPath, { mode: 'default-branch-fast-forward' });
@@ -196,7 +120,6 @@ export async function pullProjectTargets(targets, host = machineId()) {
             continue;
         }
         const after = pull.commit;
-        // Both are 8-char short hashes; equal → already up-to-date.
         const status = before !== undefined && before !== after ? 'updated' : 'current';
         results.push({
             host,
@@ -210,9 +133,6 @@ export async function pullProjectTargets(targets, host = machineId()) {
     }
     return results;
 }
-// ---------------------------------------------------------------------------
-// Envelope builder (used by the hidden `pull-local` peer command)
-// ---------------------------------------------------------------------------
 export function buildPullEnvelope(results, targets) {
     return {
         schemaVersion: 1,
@@ -222,24 +142,6 @@ export function buildPullEnvelope(results, targets) {
         results,
     };
 }
-// ---------------------------------------------------------------------------
-// Envelope parser (fail-closed — every validation failure returns [])
-// ---------------------------------------------------------------------------
-/**
- * Parse a peer's `projects pull-local` stdout. Fails CLOSED **and
- * LOUD**: any structural anomaly (wrong schema version, wrong kind, machine
- * mismatch, fingerprint mismatch, non-array results, malformed rows) returns
- * `{ items: [], valid: false }` rather than silently accepting a partial or
- * spoofed payload.
- *
- * `valid: false` is what makes the failure visible. A bare `[]` normalizes to
- * `{ items: [], valid: true }` in `normalizeRemoteAgentsJsonParse`, so the peer
- * would be recorded as having answered with nothing to report — indistinguishable
- * from a device that genuinely had no work, even though it had already run
- * `git fetch` + `merge --ff-only` or hit a real `blocked`/`failed`. Returning
- * the result shape instead lands the peer in `parseFailed`, which the caller
- * both prints and treats as a non-zero exit.
- */
 export function parseProjectPullEnvelope(stdout, machine, opts = {}) {
     const rejected = { items: [], valid: false };
     let parsed;
@@ -252,7 +154,6 @@ export function parseProjectPullEnvelope(stdout, machine, opts = {}) {
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
         return rejected;
     const env = parsed;
-    // Every field is load-bearing — a partial envelope is not trusted.
     if (env.schemaVersion !== 1)
         return rejected;
     if (env.kind !== 'project-pull')
@@ -266,9 +167,6 @@ export function parseProjectPullEnvelope(stdout, machine, opts = {}) {
     const validStatuses = new Set(['updated', 'current', 'missing', 'blocked', 'failed']);
     const items = [];
     for (const x of env.results) {
-        // A malformed ROW is the same class of failure as a malformed envelope:
-        // dropping it would hide one directory's real outcome inside an otherwise
-        // healthy-looking answer.
         if (!x || typeof x !== 'object' || Array.isArray(x))
             return rejected;
         const r = x;
@@ -297,20 +195,9 @@ export function parseProjectPullEnvelope(stdout, machine, opts = {}) {
     }
     return { items, valid: true };
 }
-// ---------------------------------------------------------------------------
-// Exit-code predicate
-// ---------------------------------------------------------------------------
-/**
- * Returns `true` when every pull completed successfully (`updated` or
- * `current`). `missing` paths are skipped by design — their absence does not
- * count as a failure. `blocked` and `failed` paths drive a non-zero exit.
- */
 export function projectPullComplete(results) {
     return results.every((r) => r.status !== 'blocked' && r.status !== 'failed');
 }
-// ---------------------------------------------------------------------------
-// Human-readable output
-// ---------------------------------------------------------------------------
 function statusIcon(s) {
     switch (s) {
         case 'updated': return chalk.green('✓');
@@ -339,15 +226,6 @@ function statusLabel(r) {
             return `${chalk.red('failed')}${r.message ? chalk.dim(` — ${r.message}`) : ''}`;
     }
 }
-/**
- * Print a human-readable per-host / per-path pull summary to stdout, followed
- * by a one-line counts footer. Does not exit — the caller controls the exit code.
- *
- * `unavailableDevices` never answered (offline, no CLI, timed out).
- * `unverifiedDevices` DID answer but their envelope failed verification, so
- * their real outcome is unknown — a strictly worse state than silence, and the
- * one the caller turns into a non-zero exit.
- */
 export function printProjectPullSummary(projectName, results, unavailableDevices, unverifiedDevices = []) {
     const counts = { updated: 0, current: 0, missing: 0, blocked: 0, failed: 0 };
     for (const r of results)

package/dist/lib/project-resources.d.ts

@@ -4,51 +4,7 @@ interface ProjectResourceSyncResult {
     skipped: string[];
 }
 export declare function syncProjectResourcesToAgent(agent: AgentId, version: string, projectAgentsDir: string): ProjectResourceSyncResult;
-/**
- * Turn the manifest's managed paths (relative to agentRoot) into anchored,
- * POSIX, `referenceRoot`-relative ignore entries. `referenceRoot` is the
- * directory the anchored `/…` patterns resolve against — the git worktree root
- * for a `.git/info/exclude` block, since git anchors info/exclude patterns at
- * the top of the working tree (not at the harness dir). Two guards keep it
- * honest:
- *   - drop any path that escapes the harness config dir (e.g. grok writes
- *     commands back into the tracked `.agents/` tree via a `../` subdir —
- *     ignoring that would hide tracked source; separate bug, PHNX-3718);
- *   - the manifest only ever holds paths the sync itself generated (pre-existing
- *     user/committed files are skipped and never recorded), so ignoring exactly
- *     these never masks a hand-authored or committed file (e.g. a repo that
- *     commits its own `.claude/CLAUDE.md` keeps it — it is not in the manifest).
- */
 export declare function managedGitignoreEntries(agentRoot: string, referenceRoot: string, managed: string[]): string[];
-/**
- * Stop git tracking `relPath` in the DotAgents clone at `repoDir` and keep it
- * locally ignored — the PHNX-3718 pattern, applied to a shared config file the
- * user repo should no longer carry (e.g. the duplicated CHANGELOG.md; the
- * canonical copy ships in `.system/`).
- *
- * The ignore entry goes in `.git/info/exclude`, NOT `.gitignore`: a tracked
- * `.gitignore` block would itself show as `M .gitignore` on every clone and
- * reintroduce the exact dirty-tree-blocks-pull failure this whole effort exists
- * to kill. info/exclude is per-clone and never committed, so the working tree
- * stays clean at rest.
- *
- * Idempotent and convergent: when the path is still tracked it is removed from
- * the index (the working file is kept) AND that removal is committed — a bare
- * `git rm --cached` would leave a staged deletion, which is itself a dirty tree
- * that re-arms the very pull trip this exists to prevent. The single removal
- * commit also propagates the de-track fleet-wide: peers pull it and converge,
- * their next run finding nothing to untrack. The exclude block is rewritten in
- * place, unioning `relPath` with any entries already there, so a second run is a
- * no-op. Fails open outside a git repo. Returns whether the path was untracked
- * by this call (a signal for the caller's one-time log).
- */
 export declare function detrackViaGitExclude(repoDir: string, relPath: string): boolean;
-/**
- * One human line for the files a project sync left alone because you already
- * wrote them. This is the normal steady state — every sync of a project whose
- * `.claude/commands/` you hand-authored hits it — so it is a single grouped
- * line, not one wrapped warning per file, and it says "yours" rather than the
- * internal "user-owned". Returns null when nothing was skipped.
- */
 export declare function formatKeptProjectResources(skipped: string[]): string | null;
 export {};

package/dist/lib/project-resources.js

@@ -35,18 +35,6 @@ export function syncProjectResourcesToAgent(agent, version, projectAgentsDir) {
     syncProjectWorkflows(agent, version, projectAgentsDir, projectRoot, agentRoot, result, next);
     if (next.size > 0 || manifest) {
         writeProjectManifest(agentRoot, Array.from(next).sort());
-        // The sync is a code generator: the per-harness dir it writes into the
-        // project tree (.factory/, .opencode/, …) is a regenerable copy of
-        // .agents/{commands,skills,…}, refreshed on every launch. Left untracked it
-        // dirties `git status` and can block `git merge`/`checkout` when a stray
-        // commit of the same path collides. So the generator owns its ignore rule:
-        // reconcile a per-agent marker block listing exactly the paths it manages.
-        // That block lives in `.git/info/exclude` — git's per-clone, uncommitted
-        // ignore file — NOT the tracked `.gitignore`: these entries are never
-        // committed upstream, so writing them into `.gitignore` left every launch
-        // with a permanent `M .gitignore` that blocked `git pull` (PHNX-3718).
-        // Passing the manifest set (empty when a sync clears a harness) also prunes
-        // the block. See PHNX-3717 for the self-managed-ignore feature.
         reconcileManagedIgnore(projectRoot, agent, agentRoot, Array.from(next).sort());
     }
     return result;
@@ -78,21 +66,6 @@ function gitignoreMarkers(agent) {
         end: `# <<< ${GITIGNORE_MARKER}: ${agent} <<<`,
     };
 }
-/**
- * Turn the manifest's managed paths (relative to agentRoot) into anchored,
- * POSIX, `referenceRoot`-relative ignore entries. `referenceRoot` is the
- * directory the anchored `/…` patterns resolve against — the git worktree root
- * for a `.git/info/exclude` block, since git anchors info/exclude patterns at
- * the top of the working tree (not at the harness dir). Two guards keep it
- * honest:
- *   - drop any path that escapes the harness config dir (e.g. grok writes
- *     commands back into the tracked `.agents/` tree via a `../` subdir —
- *     ignoring that would hide tracked source; separate bug, PHNX-3718);
- *   - the manifest only ever holds paths the sync itself generated (pre-existing
- *     user/committed files are skipped and never recorded), so ignoring exactly
- *     these never masks a hand-authored or committed file (e.g. a repo that
- *     commits its own `.claude/CLAUDE.md` keeps it — it is not in the manifest).
- */
 export function managedGitignoreEntries(agentRoot, referenceRoot, managed) {
     const root = path.resolve(agentRoot);
     const entries = new Set();
@@ -109,32 +82,12 @@ export function managedGitignoreEntries(agentRoot, referenceRoot, managed) {
     }
     return Array.from(entries).sort();
 }
-/**
- * Ask git where the local, per-clone ignore file lives and where the worktree
- * top is, resolved robustly for every layout by delegating to git itself:
- *   - normal repo → `<root>/.git/info/exclude`;
- *   - monorepo subdir → the same file even when `.git` is several levels up
- *     (`projectRoot`, the parent of `.agents/`, is not the git root);
- *   - linked worktree / submodule → `.git` is a FILE (`gitdir: …`), and
- *     `--git-path info/exclude` resolves to the shared COMMON dir so the block
- *     applies across every worktree.
- * `--path-format=absolute` forces absolute paths regardless of the `-C` cwd.
- * One `git rev-parse` yields both paths (exclude path first, worktree root
- * second), so the launch path spawns git ONCE, not twice.
- * Returns null when `dir` is not inside a git repo (git exits non-zero), which
- * fails the feature open (no-op) exactly like the old in-tree check did.
- */
 function resolveGitExcludeTarget(dir) {
     try {
         const out = execFileSync('git', ['-C', dir, 'rev-parse', '--path-format=absolute', '--git-path', 'info/exclude', '--show-toplevel'], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
         const [excludePath, worktreeRoot] = out.split('\n').map((l) => l.trim());
         if (!excludePath || !worktreeRoot)
             return null;
-        // Fail open on anything that isn't a clean pair of ABSOLUTE paths. A git
-        // older than 2.31 (predates `--path-format`) echoes the unrecognized flag
-        // back on stdout instead of erroring, which would otherwise shift the parse
-        // and have mkdirSync create a stray `--path-format=absolute` dir. The
-        // absolute-path check turns that into a clean no-op.
         if (!path.isAbsolute(excludePath) || !path.isAbsolute(worktreeRoot))
             return null;
         return { excludePath, worktreeRoot };
@@ -143,7 +96,6 @@ function resolveGitExcludeTarget(dir) {
         return null;
     }
 }
-/** True when git tracks `absPath` in the repo `dir` sits in. */
 function isTrackedByGit(dir, absPath) {
     try {
         execFileSync('git', ['-C', dir, 'ls-files', '--error-unmatch', '--', absPath], {
@@ -155,38 +107,16 @@ function isTrackedByGit(dir, absPath) {
         return false;
     }
 }
-/**
- * Apply this agent's managed block to ignore-file content, IN PLACE — used both
- * to write the block into `.git/info/exclude` and to strip a leftover block from
- * a legacy tracked `.gitignore` (entries `[]` prunes).
- *
- * In-place replacement (not strip-then-append) is load-bearing: appending would
- * move this agent's block behind every other agent's block on each resync, so in
- * a repo synced by 2+ harnesses whichever one launched last would get bumped to
- * the end — rewriting `.gitignore` on every launch forever. Replacing the block
- * where it already sits keeps the file byte-stable once written.
- *
- * Returns the new content, `content` unchanged when there is nothing to do, or
- * `null` when the block is unparseable (a begin marker with no matching end —
- * hand-truncated or a botched merge). In that case we refuse to edit rather than
- * treat everything to EOF as the block and silently delete the user's rules
- * below the orphaned marker.
- */
 function applyManagedBlock(content, begin, end, entries) {
     const lines = content.split('\n');
     const bi = lines.indexOf(begin);
     if (bi !== -1) {
         const ei = lines.indexOf(end, bi + 1);
         if (ei === -1)
-            return null; // orphaned begin marker — never truncate to EOF
+            return null;
         if (entries.length > 0) {
             return [...lines.slice(0, bi), begin, ...entries, end, ...lines.slice(ei + 1)].join('\n');
         }
-        // Prune the block, tidying the blank lines that hugged it. Unreached on the
-        // reconcileManagedIgnore write path (its entries always include the manifest,
-        // so entries.length is never 0 there), but the load-bearing case for
-        // stripLegacyManagedGitignoreBlock, which calls with entries=[] to migrate a
-        // leftover block out of the tracked .gitignore.
         const before = lines.slice(0, bi);
         const after = lines.slice(ei + 1);
         while (before.length && before[before.length - 1].trim() === '')
@@ -197,44 +127,17 @@ function applyManagedBlock(content, begin, end, entries) {
         return rest.length > 0 ? `${rest}\n` : '';
     }
     if (entries.length === 0)
-        return content; // no block, nothing to add
+        return content;
     const body = content.replace(/\n+$/, '');
     const block = [begin, ...entries, end].join('\n');
     return body.length > 0 ? `${body}\n\n${block}\n` : `${block}\n`;
 }
-/**
- * Reconcile a per-agent managed block in `.git/info/exclude` so the generated
- * per-harness resource dir never shows as untracked dirt — WITHOUT dirtying the
- * tracked `.gitignore`. Idempotent and convergent: replaces the block in place
- * and writes only when the content actually changes, so the launch hot path does
- * not churn the file (or its watchers) every run — even in a project synced by
- * several harnesses. When a sync clears a harness's resources the block does not
- * vanish: it shrinks to the lone `.agents-managed.json` entry (that file still
- * sits in the harness dir and must stay ignored), so the block is only ever
- * fully pruned by hand, never via this call path. Fails open (no-op) outside a
- * git working tree.
- *
- * Also self-heals repos dirtied by the previous behavior: PHNX-3717 wrote these
- * blocks into `<projectRoot>/.gitignore`, which is never committed upstream, so
- * every launch left a permanent `M .gitignore` that blocked `git pull`
- * (PHNX-3718). `stripLegacyManagedGitignoreBlock` removes this agent's leftover
- * block from that tracked file on the next launch, cleaning the diff instead of
- * stranding it.
- */
 function reconcileManagedIgnore(projectRoot, agent, agentRoot, managed) {
-    // Migrate away from the old tracked-.gitignore location first, so an already
-    // dirtied repo cleans itself even if git resolution below fails.
     stripLegacyManagedGitignoreBlock(projectRoot, agent);
     const target = resolveGitExcludeTarget(projectRoot);
     if (!target)
-        return; // not a git repo — fail open
+        return;
     const { begin, end } = gitignoreMarkers(agent);
-    // Ignore the manifest marker file too, not just the synced resources: the
-    // sync always writes `<agentRoot>/.agents-managed.json`, so without this the
-    // harness dir still shows as untracked in `git status` on the strength of that
-    // one file (defeating the whole point). It lives at agentRoot, so it resolves
-    // through the same anchoring + escape guard as any managed path. Anchored to
-    // the worktree root, since info/exclude patterns resolve against the tree top.
     const entries = managedGitignoreEntries(agentRoot, target.worktreeRoot, [MANIFEST_FILE, ...managed]);
     let original = '';
     try {
@@ -246,20 +149,11 @@ function reconcileManagedIgnore(projectRoot, agent, agentRoot, managed) {
     const next = applyManagedBlock(original, begin, end, entries);
     if (next === null || next === original)
         return;
-    fs.mkdirSync(path.dirname(target.excludePath), { recursive: true }); // create info/ if missing
+    fs.mkdirSync(path.dirname(target.excludePath), { recursive: true });
     const tmp = target.excludePath + '.tmp';
     fs.writeFileSync(tmp, next);
     fs.renameSync(tmp, target.excludePath);
 }
-/**
- * Remove this agent's leftover managed block from a tracked `<projectRoot>/
- * .gitignore` written by the pre-PHNX-3718 behavior. Strips ONLY the fenced
- * block (leaving every hand-written rule untouched), never creates the file,
- * and never touches a `.gitignore` that carries no block of ours. If stripping
- * empties a file we created (its only content was our block), the empty file is
- * removed when git does not track it — an empty untracked `.gitignore` would
- * still read as `?? .gitignore` dirt, the very thing this migration clears.
- */
 function stripLegacyManagedGitignoreBlock(projectRoot, agent) {
     const gitignorePath = path.join(projectRoot, '.gitignore');
     let original;
@@ -267,12 +161,9 @@ function stripLegacyManagedGitignoreBlock(projectRoot, agent) {
         original = fs.readFileSync(gitignorePath, 'utf-8');
     }
     catch {
-        return; // no .gitignore — nothing to migrate
+        return;
     }
     const { begin, end } = gitignoreMarkers(agent);
-    // Empty entries → applyManagedBlock prunes the block; returns `original`
-    // unchanged when there is no block, or null on an orphaned begin marker
-    // (which we refuse to touch rather than truncate the user's rules).
     const stripped = applyManagedBlock(original, begin, end, []);
     if (stripped === null || stripped === original)
         return;
@@ -286,45 +177,15 @@ function stripLegacyManagedGitignoreBlock(projectRoot, agent) {
 }
 const DETRACK_BEGIN = '# BEGIN agents-cli detracked (managed)';
 const DETRACK_END = '# END agents-cli detracked (managed)';
-/**
- * Stop git tracking `relPath` in the DotAgents clone at `repoDir` and keep it
- * locally ignored — the PHNX-3718 pattern, applied to a shared config file the
- * user repo should no longer carry (e.g. the duplicated CHANGELOG.md; the
- * canonical copy ships in `.system/`).
- *
- * The ignore entry goes in `.git/info/exclude`, NOT `.gitignore`: a tracked
- * `.gitignore` block would itself show as `M .gitignore` on every clone and
- * reintroduce the exact dirty-tree-blocks-pull failure this whole effort exists
- * to kill. info/exclude is per-clone and never committed, so the working tree
- * stays clean at rest.
- *
- * Idempotent and convergent: when the path is still tracked it is removed from
- * the index (the working file is kept) AND that removal is committed — a bare
- * `git rm --cached` would leave a staged deletion, which is itself a dirty tree
- * that re-arms the very pull trip this exists to prevent. The single removal
- * commit also propagates the de-track fleet-wide: peers pull it and converge,
- * their next run finding nothing to untrack. The exclude block is rewritten in
- * place, unioning `relPath` with any entries already there, so a second run is a
- * no-op. Fails open outside a git repo. Returns whether the path was untracked
- * by this call (a signal for the caller's one-time log).
- */
 export function detrackViaGitExclude(repoDir, relPath) {
     const target = resolveGitExcludeTarget(repoDir);
     if (!target)
-        return false; // not a git repo — nothing to de-track or ignore.
+        return false;
     let untrackedNow = false;
     const abs = path.join(repoDir, relPath);
     if (isTrackedByGit(repoDir, abs)) {
         try {
-            // Unstage anything else first so the removal commit records ONLY this
-            // path's deletion — a mixed reset (index only, worktree untouched). At
-            // migration time the index is already clean; this just makes the scope
-            // guaranteed rather than assumed.
             execFileSync('git', ['-C', repoDir, 'reset', '-q'], { stdio: ['ignore', 'ignore', 'ignore'] });
-            // --cached keeps the working file; the commit records the removal so the
-            // tree is clean at rest and the de-track converges across the fleet. A
-            // pathspec commit would re-read the still-present worktree file and undo
-            // the removal, so the commit takes the staged index (just this deletion).
             execFileSync('git', ['-C', repoDir, 'rm', '--cached', '--quiet', '--', relPath], {
                 stdio: ['ignore', 'ignore', 'ignore'],
             });
@@ -333,21 +194,15 @@ export function detrackViaGitExclude(repoDir, relPath) {
             untrackedNow = true;
         }
         catch {
-            // rm/commit can fail (e.g. mid-rebase, index.lock); the ignore entry below
-            // still lands and the next migration run retries the untrack. Fail open —
-            // but roll back a staged-but-uncommitted removal so we never LEAVE a dirty
-            // staged deletion behind (which would re-arm the pull trip).
             try {
                 execFileSync('git', ['-C', repoDir, 'reset', '-q', '--', relPath], {
                     stdio: ['ignore', 'ignore', 'ignore'],
                 });
             }
-            catch { /* nothing staged to reset */ }
+            catch { }
             untrackedNow = false;
         }
     }
-    // Anchor to the worktree root so the pattern matches only the top-level file,
-    // exactly like git anchors a leading-slash info/exclude entry.
     const entry = '/' + relPath.split(path.sep).join('/');
     let original = '';
     try {
@@ -367,7 +222,6 @@ export function detrackViaGitExclude(repoDir, relPath) {
     }
     return untrackedNow;
 }
-/** The entries currently inside a `begin`/`end` managed block, or `[]`. */
 function extractManagedEntries(content, begin, end) {
     const lines = content.split('\n');
     const bi = lines.indexOf(begin);
@@ -396,7 +250,6 @@ function removePath(p) {
             fs.rmSync(p, { recursive: true, force: true });
     }
     catch {
-        // already absent
     }
 }
 function pathExists(p) {
@@ -430,15 +283,6 @@ function projectEntries(projectAgentsDir, kind) {
         return [];
     }
 }
-/**
- * Manifest paths are persisted to `.agents-managed.json`, which lives in the
- * version-controlled project dir and therefore travels between machines. Store
- * them POSIX-style: `path.join` yields `skills\myskill` on Windows, and a
- * manifest carrying that would silently fail to match — and so fail to clean up
- * its managed files — when the same project is synced on macOS or Linux.
- * Normalizing on both write and read also repairs manifests written by earlier
- * Windows builds.
- */
 function toPosixRel(rel) {
     return rel.replace(/\\/g, '/');
 }
@@ -450,13 +294,6 @@ function record(kind, name, relPaths, result, manifestPaths) {
 function skip(dest, projectRoot, result) {
     result.skipped.push(path.relative(projectRoot, dest));
 }
-/**
- * One human line for the files a project sync left alone because you already
- * wrote them. This is the normal steady state — every sync of a project whose
- * `.claude/commands/` you hand-authored hits it — so it is a single grouped
- * line, not one wrapped warning per file, and it says "yours" rather than the
- * internal "user-owned". Returns null when nothing was skipped.
- */
 export function formatKeptProjectResources(skipped) {
     if (skipped.length === 0)
         return null;
@@ -599,7 +436,6 @@ function syncProjectSubagents(agent, version, projectAgentsDir, projectRoot, age
             record('subagents', sub.name, occupied.map((entry) => path.relative(agentRoot, entry.path)), result, manifestPaths);
         }
         catch {
-            // Malformed source or unsupported transform; skip this item.
         }
     }
 }