@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/github/release-drift.d.ts

@@ -0,0 +1,45 @@
+import type { GhExec } from './pr-mergeable.js';
+export interface NpmVersion {
+    name: string;
+    version: string | null;
+    error: string | null;
+}
+export interface RepoRelease {
+    latestTag: string;
+    latestTagAt: string;
+    mergesSince: number;
+    mergesSinceComplete: boolean;
+    npm: NpmVersion | null;
+}
+export type TagRead = Omit<RepoRelease, 'mergesSince' | 'mergesSinceComplete'>;
+export declare function latestVersionTag(names: readonly string[]): string | null;
+export declare function packageJsonCandidates(changedFiles: readonly string[]): string[];
+export declare function releasedPackage(manifest: unknown, version: string): string | null;
+export declare const NPM_VERSION_TTL_MS: number;
+export type NpmView = (name: string) => Promise<string>;
+export declare const npmView: NpmView;
+export interface NpmVersionCache {
+    get(name: string): {
+        version: string | null;
+        error: string | null;
+        readAt: number;
+    } | undefined;
+    set(name: string, value: {
+        version: string | null;
+        error: string | null;
+        readAt: number;
+    }): void;
+}
+export declare function readLatestTag(slug: string, gh: GhExec, npm: {
+    view: NpmView;
+    cache: NpmVersionCache;
+    nowMs: number;
+}): Promise<TagRead | null>;
+export declare function withMergesSince(tag: TagRead, merged: ReadonlyArray<{
+    mergedAt: string;
+    baseRefName: string;
+}> | null, window: {
+    sinceMs: number;
+    truncated: boolean;
+    base: string | null;
+}): RepoRelease;

package/dist/lib/github/release-drift.js

@@ -0,0 +1,91 @@
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+const execFileAsync = promisify(execFile);
+const SEMVER_TAG = /^v?(\d+)\.(\d+)\.(\d+)$/;
+export function latestVersionTag(names) {
+    let best = null;
+    for (const name of names) {
+        const m = name.match(SEMVER_TAG);
+        if (!m)
+            continue;
+        const parts = [Number(m[1]), Number(m[2]), Number(m[3])];
+        if (!best || (parts[0] - best.parts[0] || parts[1] - best.parts[1] || parts[2] - best.parts[2]) > 0)
+            best = { name, parts };
+    }
+    return best?.name ?? null;
+}
+export function packageJsonCandidates(changedFiles) {
+    const changed = changedFiles.filter((f) => f === 'package.json' || f.endsWith('/package.json'));
+    return [...new Set([...changed, 'package.json'])];
+}
+export function releasedPackage(manifest, version) {
+    if (typeof manifest !== 'object' || manifest === null)
+        return null;
+    const m = manifest;
+    if (typeof m.name !== 'string' || !m.name || m.private === true || m.version !== version)
+        return null;
+    return m.name;
+}
+export const NPM_VERSION_TTL_MS = 60 * 60 * 1000;
+export const npmView = async (name) => {
+    const { stdout } = await execFileAsync('npm', ['view', name, 'version'], { timeout: 5000, encoding: 'utf-8' });
+    return stdout.trim();
+};
+const isNotFound = (err) => /\(HTTP 404\)|Not Found/i.test(String(err?.stderr ?? err));
+export async function readLatestTag(slug, gh, npm) {
+    const tags = (await gh(['api', `repos/${slug}/tags?per_page=100`, '--paginate', '--cache', '1h', '--jq', '.[] | [.name, .commit.sha] | @tsv']))
+        .split('\n').map((l) => l.trim()).filter(Boolean).map((l) => l.split('\t'));
+    const latestTag = latestVersionTag(tags.map(([name]) => name));
+    if (!latestTag)
+        return null;
+    const sha = tags.find(([name]) => name === latestTag)[1];
+    const commit = JSON.parse((await gh([
+        'api', `repos/${slug}/commits/${sha}`, '--cache', '1h', '--jq', '{date: .commit.committer.date, files: [.files[]?.filename]}',
+    ])).trim());
+    const version = latestTag.replace(/^v/, '');
+    let name = null;
+    for (const file of packageJsonCandidates(commit.files ?? [])) {
+        let manifest;
+        try {
+            const encoded = (await gh(['api', `repos/${slug}/contents/${file}?ref=${encodeURIComponent(latestTag)}`, '--cache', '1h', '--jq', '.content'])).trim();
+            manifest = JSON.parse(Buffer.from(encoded, 'base64').toString('utf-8'));
+        }
+        catch (err) {
+            if (isNotFound(err))
+                continue;
+            throw err;
+        }
+        name = releasedPackage(manifest, version);
+        if (name)
+            break;
+    }
+    return { latestTag, latestTagAt: commit.date, npm: name ? await readNpmVersion(name, npm) : null };
+}
+async function readNpmVersion(name, npm) {
+    const hit = npm.cache.get(name);
+    const age = hit ? npm.nowMs - hit.readAt : -1;
+    if (hit && age >= 0 && age < NPM_VERSION_TTL_MS)
+        return { name, version: hit.version, error: hit.error };
+    let read;
+    try {
+        const version = await npm.view(name);
+        read = version ? { version, error: null } : { version: null, error: `npm has no version of ${name}` };
+    }
+    catch (err) {
+        const stderr = String(err?.stderr ?? '').trim();
+        const killed = err?.killed;
+        read = { version: null, error: killed ? 'npm view timed out after 5 s' : (stderr.split('\n').find(Boolean) ?? String(err)) };
+    }
+    if (read.version !== null)
+        npm.cache.set(name, { ...read, readAt: npm.nowMs });
+    return { name, ...read };
+}
+export function withMergesSince(tag, merged, window) {
+    const tagMs = Date.parse(tag.latestTagAt);
+    const since = (merged ?? []).filter((m) => Date.parse(m.mergedAt) > tagMs && (window.base === null || m.baseRefName === window.base)).length;
+    return {
+        ...tag,
+        mergesSince: since,
+        mergesSinceComplete: merged !== null && window.base !== null && tagMs >= window.sinceMs && !window.truncated,
+    };
+}

package/dist/lib/github/rest.d.ts

@@ -1,65 +1,15 @@
-/**
- * REST-backed reads for PR CI state — the engine behind the `gh` overload shim.
- *
- * The problem this exists for: the whole fleet shares one GitHub token, and the
- * merge loop's `gh pr checks/view/list` are all **GraphQL**-backed. GraphQL is
- * metered on a 5000-POINT/hr budget separate from REST core (5000 req/hr), so the
- * fleet drains GraphQL while REST core sits idle, and every agent's CI watch dies
- * with `GraphQL: API rate limit already exceeded`. These functions answer the same
- * questions over REST, which is the budget nobody is using.
- *
- * They also fix PHNX-3042 (a superseded run's red reported as the current verdict):
- * `commits/{sha}/check-runs` returns ONLY runs for that exact SHA, so anchoring on
- * the PR's live head SHA can never surface a stale run from a superseded commit —
- * the head-exact property `gh pr checks`'s denormalized GraphQL rollup lacks.
- *
- * `gh api …` here draws REST core, and reuses {@link ghExec}'s hardened env
- * (`ghEnv` strips FORCE_COLOR / pins GH_NO_COLOR — this fleet exports FORCE_COLOR
- * and gh otherwise paints the JSON payload and JSON.parse dies).
- */
 import { type GhExec } from './pr-mergeable.js';
 import type { StatusCheck } from './pr-verdict.js';
-/** A rollup item shaped like `gh pr checks --json`, built from REST. */
 export interface RollupItem extends StatusCheck {
-    /** Check name / status context. */
     name: string;
-    /** html_url (check-run) or target_url (legacy status); may be empty. */
     link?: string;
 }
-/** PR head identity — the SHA every check query must anchor to. */
 interface PrHead {
     number: number;
     sha: string;
 }
-/**
- * Resolve a PR's current head SHA over REST (`GET repos/{repo}/pulls/{n}`).
- *
- * This is the anchor for every check query: pinning to the live head SHA is what
- * makes the watch immune to a superseded run's verdict (PHNX-3042). Throws if the
- * PR has no head SHA (deleted / not found) rather than returning a wrong empty.
- */
 export declare function prHead(repo: string, number: number, gh?: GhExec): Promise<PrHead>;
-/**
- * The status-check rollup for ONE commit SHA, over REST — the union of the two
- * GitHub subsystems `gh pr checks`'s GraphQL rollup merges for you:
- *
- *   - `GET commits/{sha}/check-runs` — GitHub Actions + check-run apps (paginated).
- *   - `GET commits/{sha}/status`     — legacy commit statuses (external CI).
- *
- * Deduped by name; a check-run wins over a legacy status of the same context.
- * Fields are ASCII-upper-cased to match {@link StatusCheck}, which
- * {@link isCiGreen} reads as `conclusion || state || status`.
- */
 export declare function rollupForSha(repo: string, sha: string, gh?: GhExec): Promise<RollupItem[]>;
-/**
- * How many check-suites are still queued/in_progress for a SHA.
- *
- * Disambiguates the empty rollup: a suite that is `queued`/`in_progress` with no
- * runs yet means "checks are coming, not registered" (keep polling), NOT "this PR
- * has no checks" (terminal). Without this, a `--watch` on a freshly-pushed SHA
- * would read an empty rollup as green before CI registers.
- */
 export declare function pendingCheckSuites(repo: string, sha: string, gh?: GhExec): Promise<number>;
-/** True when gh stderr is the rate-limit outcome the shim should switch to REST on. */
 export declare function isRateLimitError(stderr: string): boolean;
 export {};

package/dist/lib/github/rest.js

@@ -1,24 +1,4 @@
-/**
- * REST-backed reads for PR CI state — the engine behind the `gh` overload shim.
- *
- * The problem this exists for: the whole fleet shares one GitHub token, and the
- * merge loop's `gh pr checks/view/list` are all **GraphQL**-backed. GraphQL is
- * metered on a 5000-POINT/hr budget separate from REST core (5000 req/hr), so the
- * fleet drains GraphQL while REST core sits idle, and every agent's CI watch dies
- * with `GraphQL: API rate limit already exceeded`. These functions answer the same
- * questions over REST, which is the budget nobody is using.
- *
- * They also fix PHNX-3042 (a superseded run's red reported as the current verdict):
- * `commits/{sha}/check-runs` returns ONLY runs for that exact SHA, so anchoring on
- * the PR's live head SHA can never surface a stale run from a superseded commit —
- * the head-exact property `gh pr checks`'s denormalized GraphQL rollup lacks.
- *
- * `gh api …` here draws REST core, and reuses {@link ghExec}'s hardened env
- * (`ghEnv` strips FORCE_COLOR / pins GH_NO_COLOR — this fleet exports FORCE_COLOR
- * and gh otherwise paints the JSON payload and JSON.parse dies).
- */
 import { ghExec } from './pr-mergeable.js';
-/** Parse newline-delimited JSON (gh `--jq` streams one object per line/page). */
 function parseNdjson(out) {
     const rows = [];
     for (const line of out.split('\n')) {
@@ -29,30 +9,12 @@ function parseNdjson(out) {
     }
     return rows;
 }
-/**
- * Resolve a PR's current head SHA over REST (`GET repos/{repo}/pulls/{n}`).
- *
- * This is the anchor for every check query: pinning to the live head SHA is what
- * makes the watch immune to a superseded run's verdict (PHNX-3042). Throws if the
- * PR has no head SHA (deleted / not found) rather than returning a wrong empty.
- */
 export async function prHead(repo, number, gh = ghExec) {
     const sha = (await gh(['api', `repos/${repo}/pulls/${number}`, '--jq', '.head.sha'])).trim();
     if (!sha)
         throw new Error(`no head SHA for ${repo}#${number}`);
     return { number, sha };
 }
-/**
- * The status-check rollup for ONE commit SHA, over REST — the union of the two
- * GitHub subsystems `gh pr checks`'s GraphQL rollup merges for you:
- *
- *   - `GET commits/{sha}/check-runs` — GitHub Actions + check-run apps (paginated).
- *   - `GET commits/{sha}/status`     — legacy commit statuses (external CI).
- *
- * Deduped by name; a check-run wins over a legacy status of the same context.
- * Fields are ASCII-upper-cased to match {@link StatusCheck}, which
- * {@link isCiGreen} reads as `conclusion || state || status`.
- */
 export async function rollupForSha(repo, sha, gh = ghExec) {
     const [runsRaw, statusRaw] = await Promise.all([
         gh([
@@ -69,7 +31,6 @@ export async function rollupForSha(repo, sha, gh = ghExec) {
         ]),
     ]);
     const byName = new Map();
-    // Legacy statuses first; check-runs override on a name collision.
     for (const s of parseNdjson(statusRaw)) {
         byName.set(String(s.name), { name: String(s.name), state: str(s.state), link: str(s.link) });
     }
@@ -83,14 +44,6 @@ export async function rollupForSha(repo, sha, gh = ghExec) {
     }
     return [...byName.values()];
 }
-/**
- * How many check-suites are still queued/in_progress for a SHA.
- *
- * Disambiguates the empty rollup: a suite that is `queued`/`in_progress` with no
- * runs yet means "checks are coming, not registered" (keep polling), NOT "this PR
- * has no checks" (terminal). Without this, a `--watch` on a freshly-pushed SHA
- * would read an empty rollup as green before CI registers.
- */
 export async function pendingCheckSuites(repo, sha, gh = ghExec) {
     const out = await gh([
         'api', `repos/${repo}/commits/${sha}/check-suites`,
@@ -100,9 +53,7 @@ export async function pendingCheckSuites(repo, sha, gh = ghExec) {
     const n = Number.parseInt(out.trim(), 10);
     return Number.isFinite(n) ? n : 0;
 }
-/** The exact GitHub GraphQL primary rate-limit signal (never the bare noun). */
 const RATE_LIMIT_SIGNAL = /GraphQL: API rate limit (?:already )?exceeded|You have exceeded a secondary rate limit/i;
-/** True when gh stderr is the rate-limit outcome the shim should switch to REST on. */
 export function isRateLimitError(stderr) {
     return RATE_LIMIT_SIGNAL.test(stderr);
 }

package/dist/lib/github/viewer.d.ts

@@ -0,0 +1,27 @@
+import { type GhExec } from './pr-mergeable.js';
+export interface GithubViewer {
+    login: string;
+    name: string | null;
+    avatarUrl: string | null;
+    emailSha256: string | null;
+}
+interface ViewerCacheRecord {
+    checkedAt: number;
+    ok: boolean;
+    viewer: GithubViewer | null;
+}
+export declare const VIEWER_FRESH_MS: number;
+export declare const VIEWER_RETRY_MS: number;
+export declare const VIEWER_REFRESH_TIMEOUT_MS = 5000;
+export declare function viewerCachePath(cacheDir?: string): string;
+export declare function emailDigest(email: string): string;
+export declare function parseViewer(raw: string): GithubViewer | null;
+export declare function fetchViewerProfile(gh?: GhExec): Promise<GithubViewer | null>;
+export declare function isViewerRecordFresh(rec: ViewerCacheRecord, nowMs?: number): boolean;
+interface CachedViewerOptions {
+    gh?: GhExec;
+    cacheDir?: string;
+    nowMs?: number;
+}
+export declare function cachedViewer(opts?: CachedViewerOptions): Promise<GithubViewer | null>;
+export {};

package/dist/lib/github/viewer.js

@@ -0,0 +1,101 @@
+import { createHash } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { httpsUrl } from '../actor.js';
+import { atomicWriteJsonSync } from '../fs-atomic.js';
+import { getCacheDir } from '../state.js';
+import { ghExec } from './pr-mergeable.js';
+const VIEWER_JQ = '{login, avatar_url, name, email}';
+export const VIEWER_FRESH_MS = 24 * 60 * 60_000;
+export const VIEWER_RETRY_MS = 60 * 60_000;
+export const VIEWER_REFRESH_TIMEOUT_MS = 5_000;
+export function viewerCachePath(cacheDir = getCacheDir()) {
+    return path.join(cacheDir, 'github-viewer.json');
+}
+export function emailDigest(email) {
+    return createHash('sha256').update(email.trim().toLowerCase()).digest('hex');
+}
+function nonEmpty(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+export function parseViewer(raw) {
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    const login = nonEmpty(data?.login);
+    if (!login)
+        return null;
+    const email = nonEmpty(data.email);
+    return {
+        login,
+        name: nonEmpty(data.name),
+        avatarUrl: httpsUrl(nonEmpty(data.avatar_url) ?? undefined) ?? null,
+        emailSha256: email ? emailDigest(email) : null,
+    };
+}
+export async function fetchViewerProfile(gh = ghExec) {
+    try {
+        return parseViewer(await gh(['api', 'user', '--cache', '24h', '--jq', VIEWER_JQ]));
+    }
+    catch {
+        return null;
+    }
+}
+function storedViewer(v) {
+    if (v === null)
+        return null;
+    if (!v || typeof v !== 'object')
+        return undefined;
+    const { login, name, avatarUrl, emailSha256 } = v;
+    if (typeof login !== 'string' || !login)
+        return undefined;
+    if (name !== null && typeof name !== 'string')
+        return undefined;
+    if (avatarUrl !== null && !(typeof avatarUrl === 'string' && httpsUrl(avatarUrl) === avatarUrl))
+        return undefined;
+    if (emailSha256 !== null && !(typeof emailSha256 === 'string' && /^[0-9a-f]{64}$/.test(emailSha256)))
+        return undefined;
+    return { login, name, avatarUrl, emailSha256 };
+}
+function readRecord(file) {
+    let rec;
+    try {
+        rec = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+    if (typeof rec?.checkedAt !== 'number' || typeof rec.ok !== 'boolean')
+        return null;
+    const viewer = storedViewer(rec.viewer);
+    if (viewer === undefined)
+        return null;
+    return { checkedAt: rec.checkedAt, ok: rec.ok, viewer };
+}
+export function isViewerRecordFresh(rec, nowMs = Date.now()) {
+    const age = nowMs - rec.checkedAt;
+    return age >= 0 && age <= (rec.ok ? VIEWER_FRESH_MS : VIEWER_RETRY_MS);
+}
+export async function cachedViewer(opts = {}) {
+    const file = viewerCachePath(opts.cacheDir);
+    const nowMs = opts.nowMs ?? Date.now();
+    const prev = readRecord(file);
+    if (prev && isViewerRecordFresh(prev, nowMs))
+        return prev.viewer;
+    const gh = opts.gh ?? ((args) => ghExec(args, { timeoutMs: VIEWER_REFRESH_TIMEOUT_MS }));
+    const fetched = await fetchViewerProfile(gh);
+    const next = fetched
+        ? { checkedAt: nowMs, ok: true, viewer: fetched }
+        : { checkedAt: nowMs, ok: false, viewer: prev?.viewer ?? null };
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        atomicWriteJsonSync(file, next);
+    }
+    catch {
+    }
+    return next.viewer;
+}

package/dist/lib/goose-commands.d.ts

@@ -1,40 +1,11 @@
-/**
- * Goose slash-command install/remove/list/compare.
- *
- * Goose has no native slash-command file format — a slash command is a recipe
- * YAML file registered in `~/.config/goose/config.yaml` under a `slash_commands`
- * array: `[{ command: "<name>", recipe_path: "<abs path to recipe.yaml>" }]`.
- * (See goose-docs.ai context-engineering/slash-commands.)
- *
- * agents-cli writes each command's recipe to `<versionHome>/.config/goose/commands/
- * <name>.yaml` — a dir distinct from the workflow recipes dir
- * (`.config/goose/recipes/`) so the workflow detector never treats a command
- * recipe as a workflow — and registers/unregisters the `slash_commands` entry in
- * `config.yaml` via a read-modify-write that preserves every other key
- * (`mcp_servers`, `extensions`, …). Under agents-cli version isolation HOME is the
- * version home, so both files live under it and the absolute `recipe_path`
- * resolves correctly at goose runtime.
- */
-/** Directory holding Goose slash-command recipe YAML files in a version home. */
 export declare function gooseCommandsDir(versionHome: string): string;
-/** Path to the Goose config.yaml (holds the `slash_commands` registry) in a version home. */
 export declare function gooseCommandConfigPath(versionHome: string): string;
-/**
- * Install a command into a Goose version home: write its recipe YAML and register
- * the `slash_commands` entry in config.yaml.
- */
 export declare function installGooseCommandToVersion(versionHome: string, commandName: string, sourcePath: string): {
     success: boolean;
     error?: string;
 };
-/** List Goose command names (recipe files) installed in a version home. */
 export declare function listGooseCommandsInVersion(versionHome: string): string[];
-/** Whether an installed Goose command recipe matches the central Markdown source. */
 export declare function gooseCommandMatches(versionHome: string, commandName: string, sourcePath: string): boolean;
-/**
- * Remove a Goose command from a version home: soft-delete the recipe to `trashDir`
- * (when provided) and unregister its `slash_commands` entry.
- */
 export declare function removeGooseCommandFromVersion(versionHome: string, commandName: string, trashDir?: string): {
     success: boolean;
     error?: string;

package/dist/lib/goose-commands.js

@@ -1,40 +1,14 @@
-/**
- * Goose slash-command install/remove/list/compare.
- *
- * Goose has no native slash-command file format — a slash command is a recipe
- * YAML file registered in `~/.config/goose/config.yaml` under a `slash_commands`
- * array: `[{ command: "<name>", recipe_path: "<abs path to recipe.yaml>" }]`.
- * (See goose-docs.ai context-engineering/slash-commands.)
- *
- * agents-cli writes each command's recipe to `<versionHome>/.config/goose/commands/
- * <name>.yaml` — a dir distinct from the workflow recipes dir
- * (`.config/goose/recipes/`) so the workflow detector never treats a command
- * recipe as a workflow — and registers/unregisters the `slash_commands` entry in
- * `config.yaml` via a read-modify-write that preserves every other key
- * (`mcp_servers`, `extensions`, …). Under agents-cli version isolation HOME is the
- * version home, so both files live under it and the absolute `recipe_path`
- * resolves correctly at goose runtime.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { safeJoin } from './paths.js';
 import { markdownToGooseRecipe } from './convert.js';
-/** Directory holding Goose slash-command recipe YAML files in a version home. */
 export function gooseCommandsDir(versionHome) {
     return path.join(versionHome, '.config', 'goose', 'commands');
 }
-/** Path to the Goose config.yaml (holds the `slash_commands` registry) in a version home. */
 export function gooseCommandConfigPath(versionHome) {
     return path.join(versionHome, '.config', 'goose', 'config.yaml');
 }
-/**
- * Read the goose config.yaml as a mutable object. Throws — rather than returning
- * `{}` — when a NON-EMPTY file fails to parse or isn't a mapping, so the caller
- * (which rewrites the whole file) never silently clobbers a real user config
- * (`mcp_servers`, `GOOSE_MODEL`, `extensions`, …). A missing or genuinely empty
- * file returns `{}`.
- */
 function readGooseConfig(configPath) {
     if (!fs.existsSync(configPath))
         return {};
@@ -50,7 +24,7 @@ function readGooseConfig(configPath) {
             `(${err.message}). Fix or remove it, then re-sync.`);
     }
     if (parsed === null || parsed === undefined)
-        return {}; // comments/whitespace only
+        return {};
     if (typeof parsed !== 'object' || Array.isArray(parsed)) {
         throw new Error(`Refusing to rewrite goose config at ${configPath}: expected a YAML mapping but found ` +
             `${Array.isArray(parsed) ? 'a list' : typeof parsed}.`);
@@ -63,16 +37,12 @@ function readSlashCommands(config) {
         return [];
     return raw.filter((e) => !!e && typeof e === 'object' && typeof e.command === 'string');
 }
-/**
- * Register (or update) a `slash_commands` entry for `commandName` pointing at
- * `recipePath`, preserving every other config key and other entries. Idempotent.
- */
 function registerSlashCommand(configPath, commandName, recipePath) {
     const config = readGooseConfig(configPath);
     const entries = readSlashCommands(config);
     const existing = entries.find((e) => e.command === commandName);
     if (existing && existing.recipe_path === recipePath)
-        return; // already current — no rewrite
+        return;
     const next = entries.filter((e) => e.command !== commandName);
     next.push({ command: commandName, recipe_path: recipePath });
     next.sort((a, b) => a.command.localeCompare(b.command));
@@ -80,14 +50,13 @@ function registerSlashCommand(configPath, commandName, recipePath) {
     fs.mkdirSync(path.dirname(configPath), { recursive: true });
     fs.writeFileSync(configPath, yaml.stringify(config), 'utf-8');
 }
-/** Remove the `slash_commands` entry for `commandName`, preserving all other config. */
 function unregisterSlashCommand(configPath, commandName) {
     if (!fs.existsSync(configPath))
         return;
     const config = readGooseConfig(configPath);
     const entries = readSlashCommands(config);
     if (!entries.some((e) => e.command === commandName))
-        return; // nothing to do
+        return;
     const next = entries.filter((e) => e.command !== commandName);
     if (next.length > 0) {
         config.slash_commands = next;
@@ -97,15 +66,10 @@ function unregisterSlashCommand(configPath, commandName) {
     }
     fs.writeFileSync(configPath, yaml.stringify(config), 'utf-8');
 }
-/** Serialize a Goose command recipe from a central Markdown command file. */
 function buildGooseCommandRecipe(commandName, sourcePath) {
     const markdown = fs.readFileSync(sourcePath, 'utf-8');
     return yaml.stringify(markdownToGooseRecipe(commandName, markdown));
 }
-/**
- * Install a command into a Goose version home: write its recipe YAML and register
- * the `slash_commands` entry in config.yaml.
- */
 export function installGooseCommandToVersion(versionHome, commandName, sourcePath) {
     try {
         const dir = gooseCommandsDir(versionHome);
@@ -119,7 +83,6 @@ export function installGooseCommandToVersion(versionHome, commandName, sourcePat
         return { success: false, error: err.message };
     }
 }
-/** List Goose command names (recipe files) installed in a version home. */
 export function listGooseCommandsInVersion(versionHome) {
     const dir = gooseCommandsDir(versionHome);
     if (!fs.existsSync(dir))
@@ -129,15 +92,11 @@ export function listGooseCommandsInVersion(versionHome) {
         .map((f) => f.slice(0, -'.yaml'.length))
         .sort();
 }
-/** Whether an installed Goose command recipe matches the central Markdown source. */
 export function gooseCommandMatches(versionHome, commandName, sourcePath) {
     const recipePath = safeJoin(gooseCommandsDir(versionHome), `${commandName}.yaml`);
     if (!fs.existsSync(recipePath) || !fs.existsSync(sourcePath))
         return false;
     try {
-        // The slash_commands entry must also be registered for the command to be live.
-        // (An unparseable config.yaml surfaces here as "not a match" → a re-sync, which
-        // fails loudly rather than clobbering, instead of a crash during a read-only diff.)
         const registered = readSlashCommands(readGooseConfig(gooseCommandConfigPath(versionHome)))
             .some((e) => e.command === commandName);
         if (!registered)
@@ -150,10 +109,6 @@ export function gooseCommandMatches(versionHome, commandName, sourcePath) {
         return false;
     }
 }
-/**
- * Remove a Goose command from a version home: soft-delete the recipe to `trashDir`
- * (when provided) and unregister its `slash_commands` entry.
- */
 export function removeGooseCommandFromVersion(versionHome, commandName, trashDir) {
     try {
         const recipePath = safeJoin(gooseCommandsDir(versionHome), `${commandName}.yaml`);