@phnx-labs/agents-cli 1.22.120 → 1.22.121

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

@@ -1,37 +1,8 @@
-/**
- * Definition-vs-reality checks for `agents projects`.
- *
- * A project definition is hand-editable YAML that nothing validates against the
- * world it describes, so it can drift into being confidently wrong. The one that
- * bit for real: `repo:` said `<user>/agents-cli` while the checkout's `origin`
- * was `phnx-labs/agents-cli`. Both are real repositories, so nothing errored —
- * the card's merged-PR and release lines simply reported a stranger's repo (0
- * merges in 7 days instead of 100). A wrong answer that looks like a right one
- * is worse than a missing one, so the mismatch gets said out loud wherever the
- * def is shown.
- *
- * Findings carry their own fix, mirroring `DoctorFinding.remediation`
- * (`lib/devices/doctor-findings.ts`) — a warning the reader has to go work out
- * how to act on is half a warning. Pure: the caller supplies the observed
- * remote, so this is unit-testable with no git and no fixture repo.
- */
 import type { ProjectDef } from './projects.js';
-/** A definition that disagrees with the machine it describes. */
 interface ProjectFinding {
     project: string;
-    /** One line naming the disagreement, both sides quoted. */
     message: string;
-    /** The exact command that fixes it. */
     remediation: string;
 }
-/**
- * Compare a def's `repo` slug against the checkout's real `origin` remote.
- *
- * - remote unreadable (no checkout on this machine, not a git repo) → no
- *   finding. The def may be perfectly right; this machine just can't say.
- * - def has no `repo` → a finding only when a remote exists to adopt, so the
- *   fix is a real one-liner rather than a nag.
- * - they disagree → a finding. This is the case that silently lies.
- */
 export declare function checkRepoSlug(def: ProjectDef, actualRemote: string | undefined): ProjectFinding | undefined;
 export {};

package/dist/lib/project-doctor.js

@@ -1,29 +1,3 @@
-/**
- * Definition-vs-reality checks for `agents projects`.
- *
- * A project definition is hand-editable YAML that nothing validates against the
- * world it describes, so it can drift into being confidently wrong. The one that
- * bit for real: `repo:` said `<user>/agents-cli` while the checkout's `origin`
- * was `phnx-labs/agents-cli`. Both are real repositories, so nothing errored —
- * the card's merged-PR and release lines simply reported a stranger's repo (0
- * merges in 7 days instead of 100). A wrong answer that looks like a right one
- * is worse than a missing one, so the mismatch gets said out loud wherever the
- * def is shown.
- *
- * Findings carry their own fix, mirroring `DoctorFinding.remediation`
- * (`lib/devices/doctor-findings.ts`) — a warning the reader has to go work out
- * how to act on is half a warning. Pure: the caller supplies the observed
- * remote, so this is unit-testable with no git and no fixture repo.
- */
-/**
- * Compare a def's `repo` slug against the checkout's real `origin` remote.
- *
- * - remote unreadable (no checkout on this machine, not a git repo) → no
- *   finding. The def may be perfectly right; this machine just can't say.
- * - def has no `repo` → a finding only when a remote exists to adopt, so the
- *   fix is a real one-liner rather than a nag.
- * - they disagree → a finding. This is the case that silently lies.
- */
 export function checkRepoSlug(def, actualRemote) {
     if (!actualRemote)
         return undefined;

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

@@ -1,51 +1,10 @@
-/**
- * Where a project's work actually went, from the local git history.
- *
- * The card can say how many agents are running and how many PRs merged, but not
- * *what was worked on*. That answer is already sitting in the checkout — every
- * merged commit names the files it touched — so it costs no API call, no
- * credential, and no rate-limit budget. Measured at 0.23s on this repo's own
- * 7-day window (897 commits), which is why it runs unconditionally rather than
- * behind a flag.
- *
- * Deliberately NOT from `gh`: the GitHub API would spend a request per PR to
- * learn what `git log --name-only` already knows locally, and it would be wrong
- * on a monorepo whose interesting unit is a subdirectory rather than a repo.
- */
-/** One directory and how many file-touches landed in it during the window. */
 export interface FocusArea {
     path: string;
     touches: number;
 }
-/** Areas shown on the card before the tail is dropped. */
 export declare const FOCUS_LIMIT = 4;
-/**
- * Bucket a file path to its area. Files shallower than {@link DEPTH} bucket to
- * their own directory, so a repo-root `README.md` does not vanish.
- */
 export declare function focusBucket(file: string): string | undefined;
-/**
- * Rank areas by file-touches, descending, ties broken by path so the order is
- * stable across runs. Pure — the caller supplies the file list, so this is
- * testable without a git repo.
- */
 export declare function rankFocusAreas(files: string[], limit?: number): FocusArea[];
-/**
- * Read the window's changed files from a checkout. Best-effort in the same shape
- * as the rest of the card's enrichment: a missing checkout, a shallow clone, or
- * a repo with no commits in the window yields an empty list, never a throw.
- *
- * Reads the LOCAL default branch ref rather than fetching — a status command
- * must not mutate the repo it is describing, so the answer is only as fresh as
- * the user's last fetch, which is the correct trade for a read-only card.
- */
 export declare function readFocusAreas(root: string, windowDays: number): Promise<FocusArea[]>;
-/** Compact count: 2329 → "2.3k", under 1000 stays exact. */
 export declare function formatFocusCount(n: number): string;
-/**
- * One scannable focus line: path + count, with a single unit trailer so the
- * bare integer is never mistaken for commits or minutes.
- *
- *   apps/cli/src 2.3k  ·  apps/cli/docs 302  ·  apps/ext/src 245  file-touches (7d)
- */
 export declare function formatFocusAreas(areas: FocusArea[], windowDays: number): string;

package/dist/lib/project-focus.js

@@ -1,37 +1,9 @@
-/**
- * Where a project's work actually went, from the local git history.
- *
- * The card can say how many agents are running and how many PRs merged, but not
- * *what was worked on*. That answer is already sitting in the checkout — every
- * merged commit names the files it touched — so it costs no API call, no
- * credential, and no rate-limit budget. Measured at 0.23s on this repo's own
- * 7-day window (897 commits), which is why it runs unconditionally rather than
- * behind a flag.
- *
- * Deliberately NOT from `gh`: the GitHub API would spend a request per PR to
- * learn what `git log --name-only` already knows locally, and it would be wrong
- * on a monorepo whose interesting unit is a subdirectory rather than a repo.
- */
 import { execFile } from 'child_process';
 import { promisify } from 'util';
 const execFileAsync = promisify(execFile);
-/** How deep a bucket goes: `apps/cli/src`, not `apps` and not every leaf file. */
 const DEPTH = 3;
-/** Areas shown on the card before the tail is dropped. */
 export const FOCUS_LIMIT = 4;
-/**
- * Paths whose churn is process, not engineering.
- *
- * This repo files one changelog fragment per PR, so `.changelog` ranks second by
- * raw file-touches — presenting it as an "area of focus" would read as a signal
- * while measuring nothing but the number of PRs. Same for the generated
- * CHANGELOG and lockfiles.
- */
 const NOISE = /(^|\/)(\.changelog|CHANGELOG\.md|bun\.lock|package-lock\.json|yarn\.lock)(\/|$)/;
-/**
- * Bucket a file path to its area. Files shallower than {@link DEPTH} bucket to
- * their own directory, so a repo-root `README.md` does not vanish.
- */
 export function focusBucket(file) {
     if (NOISE.test(file))
         return undefined;
@@ -42,11 +14,6 @@ export function focusBucket(file) {
         return parts[0];
     return parts.slice(0, Math.min(DEPTH, parts.length - 1)).join('/');
 }
-/**
- * Rank areas by file-touches, descending, ties broken by path so the order is
- * stable across runs. Pure — the caller supplies the file list, so this is
- * testable without a git repo.
- */
 export function rankFocusAreas(files, limit = FOCUS_LIMIT) {
     const counts = new Map();
     for (const f of files) {
@@ -60,15 +27,6 @@ export function rankFocusAreas(files, limit = FOCUS_LIMIT) {
         .sort((a, b) => b.touches - a.touches || a.path.localeCompare(b.path))
         .slice(0, Math.max(1, limit));
 }
-/**
- * Read the window's changed files from a checkout. Best-effort in the same shape
- * as the rest of the card's enrichment: a missing checkout, a shallow clone, or
- * a repo with no commits in the window yields an empty list, never a throw.
- *
- * Reads the LOCAL default branch ref rather than fetching — a status command
- * must not mutate the repo it is describing, so the answer is only as fresh as
- * the user's last fetch, which is the correct trade for a read-only card.
- */
 export async function readFocusAreas(root, windowDays) {
     try {
         const { stdout } = await execFileAsync('git', ['-C', root, 'log', `--since=${windowDays} days ago`, '--name-only', '--pretty=format:'], { timeout: 5000, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 });
@@ -78,7 +36,6 @@ export async function readFocusAreas(root, windowDays) {
         return [];
     }
 }
-/** Compact count: 2329 → "2.3k", under 1000 stays exact. */
 export function formatFocusCount(n) {
     if (!Number.isFinite(n) || n < 0)
         return '0';
@@ -88,12 +45,6 @@ export function formatFocusCount(n) {
     const s = k >= 10 ? String(Math.round(k)) : k.toFixed(1).replace(/\.0$/, '');
     return `${s}k`;
 }
-/**
- * One scannable focus line: path + count, with a single unit trailer so the
- * bare integer is never mistaken for commits or minutes.
- *
- *   apps/cli/src 2.3k  ·  apps/cli/docs 302  ·  apps/ext/src 245  file-touches (7d)
- */
 export function formatFocusAreas(areas, windowDays) {
     if (areas.length === 0)
         return '';

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

@@ -1,67 +1,26 @@
-/**
- * Pure builders behind `agents projects import`.
- *
- * Currently supports one source: **Linear** (projects someone deliberately
- * created on the board). Results funnel through `writeProjectDef`.
- *
- * Everything here is a pure function of its arguments — no fs, no shell, no
- * process env. The command layer shells out to `linear` and hands the rows in;
- * that's what makes these testable against plain fixtures with no mocking.
- * The one exception is `toHomeRelative`, a string rewrite against `$HOME`.
- */
 import { type ProjectDef } from './projects.js';
 import { type LinearProjectLite } from './linear-projects.js';
-/** A row the import declined to write, with the reason to print. */
 export interface ImportSkip {
     name: string;
     reason: string;
 }
-/** What an import would write, and what it declined. */
 export interface ImportPlan {
     defs: ProjectDef[];
     skipped: ImportSkip[];
 }
-/** The validated shape of the `import` flags. */
 export interface ImportOptions {
     source: 'linear';
     force: boolean;
 }
-/** The raw commander flags, before validation. */
 export interface RawImportFlags {
     fromLinear?: boolean;
     force?: boolean;
 }
-/**
- * Validate the flag combination, throwing a user-facing message on the first
- * problem.
- */
 export declare function validateImportOpts(flags: RawImportFlags): ImportOptions;
-/**
- * Turn a Linear project name into a definition slug: lowercase, every run of
- * unusable characters collapsed to one `-`, trimmed of leading/trailing
- * punctuation, capped at the 64 chars `isSafeProjectName` allows. Returns `''`
- * when nothing usable survives — the caller skips those loudly.
- */
 export declare function slugifyProjectName(name: string): string;
-/** The local-checkout lookups the Linear builder needs, injected so it stays pure. */
 export interface LinearImportDeps {
-    /** Directory names directly under the configured projects root. */
     localDirs: string[];
-    /** Home-relative root path for one of `localDirs`. */
     resolveRoot: (dir: string) => string | undefined;
-    /** `owner/repo` from that checkout's origin remote, when it has one. */
     resolveOrigin: (dir: string) => string | undefined;
 }
-/**
- * Plan the Linear import. Every project becomes a def carrying its `linear`
- * link; the local checkout is bound **only on an exact normalized-name match**
- * (`matchLocalCheckoutExact`). The containment fallback that powers the `link`
- * suggestion is deliberately not used here — "Agents CLI" containing
- * "agents-cli-web" is a fine hint for a human to confirm, and a silently wrong
- * `root` on a write path.
- *
- * An existing def is preserved field-for-field; only `name` and `linear` are
- * overwritten, so a hand-set `description`/`contexts`/`integrations` survives a
- * re-import.
- */
 export declare function buildLinearImportCandidates(projects: LinearProjectLite[], existing: Map<string, ProjectDef>, deps: LinearImportDeps, opts: Pick<ImportOptions, 'force'>): ImportPlan;

package/dist/lib/project-import.js

@@ -1,31 +1,10 @@
-/**
- * Pure builders behind `agents projects import`.
- *
- * Currently supports one source: **Linear** (projects someone deliberately
- * created on the board). Results funnel through `writeProjectDef`.
- *
- * Everything here is a pure function of its arguments — no fs, no shell, no
- * process env. The command layer shells out to `linear` and hands the rows in;
- * that's what makes these testable against plain fixtures with no mocking.
- * The one exception is `toHomeRelative`, a string rewrite against `$HOME`.
- */
 import { isSafeProjectName } from './projects.js';
 import { matchLocalCheckoutExact } from './linear-projects.js';
-/**
- * Validate the flag combination, throwing a user-facing message on the first
- * problem.
- */
 export function validateImportOpts(flags) {
     if (!flags.fromLinear)
         throw new Error('Pick an import source: --from-linear.');
     return { source: 'linear', force: flags.force === true };
 }
-/**
- * Turn a Linear project name into a definition slug: lowercase, every run of
- * unusable characters collapsed to one `-`, trimmed of leading/trailing
- * punctuation, capped at the 64 chars `isSafeProjectName` allows. Returns `''`
- * when nothing usable survives — the caller skips those loudly.
- */
 export function slugifyProjectName(name) {
     const slug = name
         .toLowerCase()
@@ -36,18 +15,6 @@ export function slugifyProjectName(name) {
         .replace(/[-._]+$/g, '');
     return isSafeProjectName(slug) ? slug : '';
 }
-/**
- * Plan the Linear import. Every project becomes a def carrying its `linear`
- * link; the local checkout is bound **only on an exact normalized-name match**
- * (`matchLocalCheckoutExact`). The containment fallback that powers the `link`
- * suggestion is deliberately not used here — "Agents CLI" containing
- * "agents-cli-web" is a fine hint for a human to confirm, and a silently wrong
- * `root` on a write path.
- *
- * An existing def is preserved field-for-field; only `name` and `linear` are
- * overwritten, so a hand-set `description`/`contexts`/`integrations` survives a
- * re-import.
- */
 export function buildLinearImportCandidates(projects, existing, deps, opts) {
     const defs = [];
     const skipped = [];
@@ -68,9 +35,6 @@ export function buildLinearImportCandidates(projects, existing, deps, opts) {
             continue;
         }
         seen.add(name);
-        // The Linear display name is recorded verbatim (`p.name`), not the
-        // slugified def name: `agi` is the local id, "AGI" is what the board calls
-        // it, and agents read the latter when they name the project.
         const def = { ...prior, name, linear: { projectId: p.id, name: p.name } };
         if (p.url)
             def.linear.url = p.url;

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

@@ -1,70 +1,5 @@
-/**
- * The one worktree-aware cwd -> project fold.
- *
- * Several surfaces bucket work "by project": the `agents sessions` overview,
- * the `agents feed` timeline, and anything else that has a cwd and needs a
- * stable repo-level key. They must agree, or the same session shows up under
- * `agents-cli` in one view and `my-branch-slug` in another — so the rule lives
- * here and every caller delegates.
- *
- * The rule: a worktree cwd (`…/<repo>/.agents/worktrees/<slug>[/sub]`) folds to
- * the REPO directory name, so a worktree groups with the repo it branched from;
- * any other path resolves to its own basename. {@link projectKeyFromCwd} is pure
- * — no filesystem, no git, so it works identically for a remote peer's events as
- * for local ones; {@link resolveProjectKey} adds the filesystem repo-root walk
- * for paths this machine can see.
- */
-/**
- * Convert an absolute cwd to Claude Code's own project-folder name under
- * `~/.claude/projects/` (slashes and dots become dashes) — the encoding
- * Claude Code itself performs to name each project's session-transcript and
- * native-memory directory. Pure, no filesystem: session discovery and
- * native-memory sync both derive from this so they agree on one directory
- * for a given cwd.
- */
 export declare function claudeProjectDirName(cwd: string): string;
-/**
- * Resolve a stable project key from a working directory, or `undefined` when
- * the path carries nothing usable (empty, `/`, whitespace).
- */
 export declare function projectKeyFromCwd(cwd?: string | null): string | undefined;
-/**
- * The git working-tree root containing `dir`, by walking up for a `.git` entry
- * — a directory in a normal checkout, a file in a linked worktree, so one
- * `existsSync` covers both. Filesystem-only: no `git` process per lookup, which
- * matters because a timeline can hold dozens of distinct cwds.
- *
- * Returns `undefined` when `dir` is not inside a repo, when it does not exist
- * (a path from another machine), or when the only repo found IS the home
- * directory — a dotfiles repo at `$HOME` would otherwise swallow every
- * non-project directory under it into one bogus "project".
- */
 export declare function repoRootForCwd(dir: string, home?: string): string | undefined;
-/**
- * The main-repo `.agents` directory for a cwd, or `undefined` when the cwd is
- * not inside a repo.
- *
- * For a worktree cwd (`…/<repo>/.agents/worktrees/<slug>[/sub]`) this resolves
- * to the PRIMARY repo's `.agents` — the directory that actually holds the
- * worktrees — so a run started anywhere in the repo can write into any worktree.
- * For any other in-repo cwd it is `<repo-root>/.agents`.
- *
- * The single caller is Codex's `edit`-mode writable-root list: Codex's
- * `workspace-write` sandbox hardcodes `.agents/` (and `.codex/`) as read-only,
- * but naming the `.agents` directory itself as an explicit writable root
- * overrides that — so an in-repo build/test never hits EROFS on a path under
- * `.agents/worktrees/`. Filesystem-only (no `git` process): reuses the same
- * worktree-segment fold as {@link projectKeyFromCwd}.
- */
 export declare function repoAgentsDirForCwd(cwd?: string | null, home?: string): string | undefined;
-/**
- * Resolve the project key for a cwd **on this machine**: the repository it
- * belongs to when there is one (so a monorepo subdir like `<repo>/apps/cli`
- * groups under `<repo>`, not `cli`), else the directory itself.
- *
- * Each machine resolves its own paths — a peer answering a fan-out stamps the
- * project for its events before they cross the wire — so this is never asked
- * about a path it cannot see. {@link projectKeyFromCwd} is the pure fold for
- * everything else.
- */
 export declare function resolveProjectKey(cwd?: string | null, home?: string): string | undefined;

package/dist/lib/project-key.js

@@ -1,38 +1,10 @@
-/**
- * The one worktree-aware cwd -> project fold.
- *
- * Several surfaces bucket work "by project": the `agents sessions` overview,
- * the `agents feed` timeline, and anything else that has a cwd and needs a
- * stable repo-level key. They must agree, or the same session shows up under
- * `agents-cli` in one view and `my-branch-slug` in another — so the rule lives
- * here and every caller delegates.
- *
- * The rule: a worktree cwd (`…/<repo>/.agents/worktrees/<slug>[/sub]`) folds to
- * the REPO directory name, so a worktree groups with the repo it branched from;
- * any other path resolves to its own basename. {@link projectKeyFromCwd} is pure
- * — no filesystem, no git, so it works identically for a remote peer's events as
- * for local ones; {@link resolveProjectKey} adds the filesystem repo-root walk
- * for paths this machine can see.
- */
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 const WORKTREE_SEGMENT = '/.agents/worktrees/';
-/**
- * Convert an absolute cwd to Claude Code's own project-folder name under
- * `~/.claude/projects/` (slashes and dots become dashes) — the encoding
- * Claude Code itself performs to name each project's session-transcript and
- * native-memory directory. Pure, no filesystem: session discovery and
- * native-memory sync both derive from this so they agree on one directory
- * for a given cwd.
- */
 export function claudeProjectDirName(cwd) {
     return cwd.replace(/[/.]/g, '-');
 }
-/**
- * Resolve a stable project key from a working directory, or `undefined` when
- * the path carries nothing usable (empty, `/`, whitespace).
- */
 export function projectKeyFromCwd(cwd) {
     if (!cwd)
         return undefined;
@@ -49,28 +21,12 @@ export function projectKeyFromCwd(cwd) {
     const base = norm.slice(norm.lastIndexOf('/') + 1);
     return base || undefined;
 }
-/**
- * The git working-tree root containing `dir`, by walking up for a `.git` entry
- * — a directory in a normal checkout, a file in a linked worktree, so one
- * `existsSync` covers both. Filesystem-only: no `git` process per lookup, which
- * matters because a timeline can hold dozens of distinct cwds.
- *
- * Returns `undefined` when `dir` is not inside a repo, when it does not exist
- * (a path from another machine), or when the only repo found IS the home
- * directory — a dotfiles repo at `$HOME` would otherwise swallow every
- * non-project directory under it into one bogus "project".
- */
 export function repoRootForCwd(dir, home = os.homedir()) {
     const stop = path.resolve(home);
     let current = path.resolve(dir);
     for (;;) {
         if (fs.existsSync(path.join(current, '.git')))
             return current === stop ? undefined : current;
-        // Never climb past $HOME: an ancestor of home (/tmp, /, ...) is not part of
-        // any project this cwd belongs to, and treating one as the repo root would
-        // let unrelated host state (e.g. a stray /tmp/.git) swallow every loose
-        // directory under home. Mirrors the shim's own home boundary — see the codex
-        // adapter's shimExecTail (lib/harness/adapters/codex.ts).
         if (current === stop)
             return undefined;
         const parent = path.dirname(current);
@@ -79,22 +35,6 @@ export function repoRootForCwd(dir, home = os.homedir()) {
         current = parent;
     }
 }
-/**
- * The main-repo `.agents` directory for a cwd, or `undefined` when the cwd is
- * not inside a repo.
- *
- * For a worktree cwd (`…/<repo>/.agents/worktrees/<slug>[/sub]`) this resolves
- * to the PRIMARY repo's `.agents` — the directory that actually holds the
- * worktrees — so a run started anywhere in the repo can write into any worktree.
- * For any other in-repo cwd it is `<repo-root>/.agents`.
- *
- * The single caller is Codex's `edit`-mode writable-root list: Codex's
- * `workspace-write` sandbox hardcodes `.agents/` (and `.codex/`) as read-only,
- * but naming the `.agents` directory itself as an explicit writable root
- * overrides that — so an in-repo build/test never hits EROFS on a path under
- * `.agents/worktrees/`. Filesystem-only (no `git` process): reuses the same
- * worktree-segment fold as {@link projectKeyFromCwd}.
- */
 export function repoAgentsDirForCwd(cwd, home) {
     if (!cwd)
         return undefined;
@@ -105,16 +45,6 @@ export function repoAgentsDirForCwd(cwd, home) {
     const repoRoot = wtIdx > 0 ? norm.slice(0, wtIdx) : repoRootForCwd(norm, home);
     return repoRoot ? path.join(repoRoot, '.agents') : undefined;
 }
-/**
- * Resolve the project key for a cwd **on this machine**: the repository it
- * belongs to when there is one (so a monorepo subdir like `<repo>/apps/cli`
- * groups under `<repo>`, not `cli`), else the directory itself.
- *
- * Each machine resolves its own paths — a peer answering a fan-out stamps the
- * project for its events before they cross the wire — so this is never asked
- * about a path it cannot see. {@link projectKeyFromCwd} is the pure fold for
- * everything else.
- */
 export function resolveProjectKey(cwd, home) {
     if (!cwd)
         return undefined;

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

@@ -1,39 +1,3 @@
-/**
- * Launch-time project compile. Invoked by the agent shim's hot path (via
- * `agents sync --launch`) between version resolve and binary exec.
- *
- * Three responsibilities, all skip-fast when there's nothing to do:
- *
- * 1. Compile project rules from `<cwd>/.agents/rules/` into `<cwd>/AGENTS.md`
- *    (+ per-agent symlinks). Delegates to compileRulesForProject, which is
- *    the same helper management-side `agents sync` uses.
- *
- * 2. Copy project resources from `<cwd>/.agents/{commands,skills,subagents,workflows}`
- *    into the agent's workspace-local discovery dir (`<cwd>/.claude/`,
- *    `<cwd>/.codex/`, etc.) with an ownership manifest at
- *    `<cwd>/.{agent}/.agents-managed.json`. The manifest is the only clobber
- *    authority: paths it lists are removed and refreshed, pre-existing paths it
- *    does not list are skipped as user-owned.
- *
- * 3. Synthesize four scope-grouped plugin marketplaces under the version's
- *    `<versionHome>/.{agent}/plugins/marketplaces/` (for plugin-capable agents):
- *      - agents-cli         ← ~/.agents/plugins/*           (user scope, legacy name)
- *      - agents-system      ← ~/.agents/.system/plugins/*
- *      - extras-<alias>     ← ~/.agents-<alias>/plugins/*   (per enabled extra)
- *      - agents-project     ← <cwd>/.agents/plugins/*
- *    Each plugin is copied in (skip-fast via mtime cache), the marketplace
- *    catalog is rewritten only when contents change, and the marketplace is
- *    registered in known_marketplaces.json. Upstream marketplaces like
- *    "claude-plugins-official" are left untouched. Project- and extras-
- *    scope plugins do NOT auto-enable exec surfaces (.mcp.json, hooks, bin/,
- *    scripts/) — user must explicitly `agents plugins enable` them.
- *
- * Heavy work (version-home reconciliation, hook registration, MCP merging)
- * stays in `agents sync` without --launch and is NOT touched here. The
- * launch path is filesystem-only and skip-fast: sub-50ms when no source
- * has changed, scales linearly only with newly-modified plugins on the
- * change path.
- */
 import type { AgentId } from './types.js';
 import { pluginInstallDir } from './plugins/plugin-marketplace.js';
 interface LaunchSyncOptions {
@@ -42,23 +6,10 @@ interface LaunchSyncOptions {
     cwd: string;
 }
 interface LaunchSyncResult {
-    /** Project rules were re-compiled into cwd/AGENTS.md (+ per-agent symlinks). */
     rulesCompiled: boolean;
-    /** Number of workspace resource symlinks created or refreshed. */
     workspaceLinks: number;
-    /** Workspace resource paths we left alone because they exist and aren't ours. */
     workspaceSkipped: string[];
-    /** Map of marketplace name → plugin names installed under it. */
     marketplaces: Record<string, string[]>;
 }
-/**
- * Run the launch-time project compile. Safe to call on every agent launch:
- * each step is idempotent and skips when its inputs are missing.
- *
- * After a successful run, touches the shim-side skip-fast sentinel at
- * `~/.agents/.cache/launch-sync/<agent>@<version>@<projectslug>` so the next
- * shim invocation can skip the node spawn entirely when no source dir is
- * newer than the sentinel (shim schema v17+).
- */
 export declare function runLaunchSync(opts: LaunchSyncOptions): LaunchSyncResult;
 export { pluginInstallDir };