@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/project-launch.js

@@ -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 * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as os from 'os';
@@ -46,15 +10,6 @@ import { compileRulesForProject } from './rules/compile.js';
 import { syncProjectResourcesToAgent } from './project-resources.js';
 import { discoverPluginsInDir, hasPluginExecSurfaces, inspectPluginCapabilities } from './plugins/plugins.js';
 import { MARKETPLACE_NAME, PROJECT_MARKETPLACE_NAME, SYSTEM_MARKETPLACE_NAME, addPluginToSettings, copyPluginToMarketplace, marketplaceNameFor, marketplaceRoot, pluginInstallDir, registerMarketplace, removePluginFromSettings, syncMarketplaceManifest, } from './plugins/plugin-marketplace.js';
-/**
- * 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 function runLaunchSync(opts) {
     const result = {
         rulesCompiled: false,
@@ -62,44 +17,24 @@ export function runLaunchSync(opts) {
         workspaceSkipped: [],
         marketplaces: {},
     };
-    // Step 1: project rules
     try {
         const r = compileRulesForProject(opts.cwd);
         result.rulesCompiled = r.compiled;
     }
     catch {
-        // Don't fail launch on a malformed project rules.yaml.
     }
-    // Step 2: workspace resource mirror
     const projectAgentsDir = getProjectAgentsDir(opts.cwd);
     if (projectAgentsDir) {
         const projectResources = syncProjectResourcesToAgent(opts.agent, opts.version, projectAgentsDir);
         result.workspaceLinks = projectResources.synced.length;
         result.workspaceSkipped = projectResources.skipped;
     }
-    // Step 3: scoped plugin marketplaces
     result.marketplaces = synthesizeScopedMarketplaces(opts.agent, opts.version, opts.cwd);
-    // Touch the shim's skip-fast sentinel. Best-effort — if this fails the
-    // shim just won't skip on the next launch, which is correct fallback.
     touchLaunchSentinel(opts.agent, opts.version, opts.cwd);
     return result;
 }
-/**
- * Path of the shim's skip-fast sentinel for this (agent, version, cwd) tuple.
- * Must match the SHIM-SIDE format in src/lib/installations/shims.ts (PROJECT_SLUG derivation),
- * which is the canonical `toPortableKey` mapping: drop the Windows drive colon
- * and fold `\`, `/`, and ` ` → `_`. On POSIX this is byte-identical to the old
- * `/` and ` ` → `_` slug; on Windows it yields a legal filename (no `C:\`).
- *
- * Cache leak note: this dir accumulates one zero-byte file per
- * (agent, version, project) tuple ever launched. Disk impact is negligible
- * (inodes only). A periodic GC belongs in `agents prune` — follow-up.
- */
 function launchSentinelPath(agent, version, cwd) {
     const slug = toPortableKey(cwd);
-    // Prefer $HOME (respects test overrides + matches bash's $HOME expansion in
-    // the shim), fall back to os.homedir() so the lookup never resolves to '/'
-    // if HOME is somehow unset.
     const home = process.env.HOME || os.homedir();
     return path.join(home, '.agents', '.cache', 'launch-sync', `${agent}@${version}@${slug}`);
 }
@@ -107,11 +42,9 @@ function touchLaunchSentinel(agent, version, cwd) {
     try {
         const sentinel = launchSentinelPath(agent, version, cwd);
         fs.mkdirSync(path.dirname(sentinel), { recursive: true });
-        // Empty content — purely an mtime carrier for the shim's `[ -nt ]` compare.
         fs.writeFileSync(sentinel, '');
     }
     catch {
-        // best-effort
     }
 }
 function makeScope(spec, pluginsDir, autoEnableExecSurfaces, precedence) {
@@ -119,8 +52,6 @@ function makeScope(spec, pluginsDir, autoEnableExecSurfaces, precedence) {
 }
 function collectPluginScopes(cwd) {
     const scopes = [];
-    // Precedence: project > extras > user > system. Same direction the rules
-    // composition uses (project layer shadows base layers).
     scopes.push(makeScope({ kind: 'system', root: getSystemPluginsDir() }, getSystemPluginsDir(), true, 0));
     scopes.push(makeScope({ kind: 'user' }, getPluginsDir(), true, 1));
     for (const extra of getEnabledExtraRepos()) {
@@ -146,9 +77,6 @@ function synthesizeScopedMarketplaces(agent, version, cwd) {
     }
     if (!fs.existsSync(versionHome))
         return result;
-    // First pass: resolve cross-scope plugin name collisions by precedence.
-    // For each plugin name, the scope with the highest precedence wins; the
-    // plugin is installed only into that scope's marketplace.
     const winner = new Map();
     for (const scope of collectPluginScopes(cwd)) {
         if (!fs.existsSync(scope.pluginsDir))
@@ -162,8 +90,6 @@ function synthesizeScopedMarketplaces(agent, version, cwd) {
     }
     if (winner.size === 0)
         return result;
-    // Group winners by their winning scope and synthesize one marketplace per
-    // scope. Skip-fast: scope hash sentinel short-circuits unchanged scopes.
     const byScope = new Map();
     for (const { scope, plugin } of winner.values()) {
         let bucket = byScope.get(scope.marketplaceName);
@@ -179,9 +105,6 @@ function synthesizeScopedMarketplaces(agent, version, cwd) {
         if (installed.length > 0)
             result[scope.marketplaceName] = installed;
     }
-    // Sweep any orphaned `<plugin>@*` keys whose plugin name is now owned by a
-    // different scope (e.g. plugin moved from user to project). Without this,
-    // the OLD scope's enabledPlugins key stays set forever, double-enabling.
     pruneLosingScopeEnables(agent, versionHome, winner);
     return result;
 }
@@ -190,8 +113,6 @@ function installScope(agent, versionHome, scope, plugins) {
     const sentinelPath = path.join(marketplaceRoot(scope.spec, agent, versionHome), '.agents-launch-sync');
     const existingHash = readScopeHash(sentinelPath);
     if (existingHash === newHash) {
-        // Nothing changed since last launch — fast path. Verify the manifest
-        // dir still exists; if a user blew it away, force a re-sync.
         if (fs.existsSync(path.dirname(sentinelPath))) {
             return plugins.map((p) => p.name);
         }
@@ -203,15 +124,12 @@ function installScope(agent, versionHome, scope, plugins) {
             installed.push(plugin.name);
         }
         catch {
-            // Individual plugin copy failure — keep going on the others.
         }
     }
     if (installed.length === 0)
         return [];
     syncMarketplaceManifest(scope.spec, agent, versionHome);
     registerMarketplace(scope.spec, agent, versionHome);
-    // Enable each plugin in settings unless the scope withholds auto-enable for
-    // exec surfaces (project + extras) AND the plugin actually ships any.
     for (const plugin of plugins) {
         if (!installed.includes(plugin.name))
             continue;
@@ -237,12 +155,6 @@ function pruneLosingScopeEnables(agent, versionHome, winner) {
         }
     }
 }
-/**
- * Hash the plugin set so we can skip-fast when nothing changed since the
- * last launch. Includes the source path (catches moves), the .claude-plugin/
- * plugin.json content (catches metadata edits), and the file-mtime+size
- * fingerprint of every file in the plugin (catches code edits).
- */
 function computeScopeHash(plugins) {
     const hash = crypto.createHash('sha256');
     for (const plugin of [...plugins].sort((a, b) => a.name.localeCompare(b.name))) {
@@ -274,7 +186,7 @@ function fingerprintDir(dir, hash) {
                 const stat = fs.lstatSync(abs);
                 hash.update(`F ${entry.name} ${stat.size} ${stat.mtimeMs}\n`);
             }
-            catch { /* race during launch — skip */ }
+            catch { }
         }
     }
 }
@@ -291,7 +203,6 @@ function writeScopeHash(sentinelPath, hash) {
         fs.mkdirSync(path.dirname(sentinelPath), { recursive: true });
         fs.writeFileSync(sentinelPath, hash + '\n');
     }
-    catch { /* best-effort; missing sentinel just means next launch does full work */ }
+    catch { }
 }
-// Re-export for the test's structural assertions; not used internally.
 export { pluginInstallDir };

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

@@ -1,116 +1,30 @@
-/**
- * Project workspace probing — the drift signal behind `projects status`.
- *
- * Projects are natively multi-device: the same definition (home-relative paths)
- * re-roots on every fleet machine, and the question is whether the project's
- * repos are PRESENT on each box, on which branch, how far ahead/behind their
- * upstream, and whether they carry uncommitted changes. This module is the pure
- * local half: given a set of home-relative paths it probes each one with a
- * handful of read-only git calls. Drift is measured against the LAST-FETCHED
- * upstream (`@{upstream}`) — deliberately no `git fetch`, so a probe is fast
- * and offline-safe. The fleet half (`--fleet`) just runs this probe on every
- * peer via the canonical `remote-agents-json` SSH fan-out.
- */
 import { type ProjectDef } from './projects.js';
-/** The on-disk state of one workspace repo on one machine. */
 interface RepoWorkspaceStatus {
-    /** The probed path, echoed home-relative (re-roots per machine). */
     path: string;
-    /** `.git` exists (a directory, or a FILE for a linked worktree). */
     present: boolean;
     branch?: string;
-    /** The configured upstream ref (e.g. `origin/main`); absent → no upstream. */
     upstream?: string;
-    /** Commits on HEAD not on the upstream. Undefined without an upstream. */
     ahead?: number;
-    /** Commits on the upstream not on HEAD. Undefined without an upstream. */
     behind?: number;
-    /** Uncommitted (incl. untracked) paths from `git status --porcelain`. */
     dirty?: number;
-    /** ISO 8601 committer date of HEAD. */
     lastCommit?: string;
-    /** `.git` exists but git could not read it — never looks silently clean. */
     error?: string;
 }
-/** A probe result tagged with the machine that answered (the fleet view). */
 export interface HostWorkspaceStatus extends RepoWorkspaceStatus {
     host: string;
 }
-/**
- * Probe one workspace repo. A missing path yields `{present: false}` and no
- * git call is made. On a present repo every signal is best-effort: whatever
- * succeeded is reported, and a repo whose `.git` exists yet every git call
- * failed surfaces as present-with-error rather than silently clean.
- */
 export declare function probeRepoWorkspace(absPath: string): RepoWorkspaceStatus;
-/** Probe each home-relative path (expanded against the local home), in order. */
 export declare function probeProjectWorkspaces(paths: string[]): RepoWorkspaceStatus[];
-/**
- * The home-relative paths to probe for a project definition: its `root` plus
- * each `repos[].path` (the opt-in for additional repos), deduped. Every target
- * is normalized through the same `toHomeRelative(expandLocalHome(...))` the
- * probe echoes, so a hand-edited def (absolute path under home, trailing
- * slash) matches its probe rows exactly — `writeProjectDef` normalizes on
- * write, but defs are hand-editable YAML and never silently drop a row.
- *
- * The walk itself lives in `projects.ts` so the probe and the spawn grants read
- * one definition of "the project's directories" instead of two that drift.
- */
 export declare function workspaceTargetsForDef(def: ProjectDef): string[];
-/**
- * Parse a peer's `projects probe` stdout, tagging each row with the
- * machine that answered. Defensive against version skew / partial output, the
- * same boundary contract as `parseRemoteActive`: non-JSON or a non-array
- * yields `[]`, and rows without a `path`/`present` core are dropped.
- */
 export declare function parseRemoteProbe(stdout: string, machine: string): HostWorkspaceStatus[];
-/**
- * One workspace's compact state: `✓ clean · main`, `⚠ 12 dirty · ↑3 ↓1 ·
- * feature/x`, `✗ missing`, or `⚠ error: …`. Pure — chalk styling only.
- */
 export declare function formatWorkspaceLine(s: RepoWorkspaceStatus): string;
-/**
- * The fleet view of one project's workspaces: one content line per probed
- * path (host-sorted `host: state` cells joined by ` · `), labelled with the
- * path when a project probes more than one. Pure — the caller adds the
- * `fleet` row label.
- */
 export declare function formatFleetWorkspaces(statuses: HostWorkspaceStatus[]): string[];
-/**
- * One-line fleet health summary — `6/13 clean · 4 behind · 4 dirty · 1 missing`.
- * Sits ABOVE the per-host {@link formatFleetWorkspaces} table so the card is
- * scannable without reading every host cell; the table keeps the per-host branch
- * and drift detail. Zero buckets are omitted. `behind` colours red when any host
- * is ≥10 behind (matching the footer's critical threshold), else yellow; a host
- * that is both behind and dirty counts in both. Each host×path row is one unit,
- * the same unit the table renders. Pure — chalk styling only.
- */
 export declare function formatFleetSummary(statuses: HostWorkspaceStatus[]): string;
-/** Severity for a workspace/repo warning on the project card. */
 type WorkspaceWarningSeverity = 'critical' | 'continue';
 interface WorkspaceWarning {
     severity: WorkspaceWarningSeverity;
     text: string;
     remediation?: string;
 }
-/**
- * Turn probed workspace rows into card-footer warnings, GROUPED by root cause so
- * a fleet where eight hosts drift is a few lines, not sixteen (each with its own
- * repeated remediation).
- *
- * - missing / unreadable git → critical (agents there cannot share a tree)
- * - behind upstream → critical when ANY host is ≥10 commits behind, else continue
- * - dirty tree → continue (local work is fine; just note it)
- * - ahead-only is not a warning (that is progress waiting to push)
- *
- * Within one probed path, all behind hosts collapse to one warning listing each
- * host with its count (`4 hosts behind origin/main — mac-mini ↓172, …`) plus one
- * shared remediation; a lone host keeps its full sentence. Missing and dirty
- * collapse the same way. `error` stays per-host (each message is distinct).
- * Grouping is per path so two different repos never merge into one count. Unlike
- * doctor's `emitGroup`, the list names EVERY host, not the first two — each
- * host's drift count differs and is individually actionable. Pure — chalk only.
- * Caller decides whether the rows came from `--fleet` or a local probe.
- */
 export declare function workspaceWarnings(statuses: HostWorkspaceStatus[]): WorkspaceWarning[];
 export {};

package/dist/lib/project-probe.js

@@ -1,29 +1,10 @@
-/**
- * Project workspace probing — the drift signal behind `projects status`.
- *
- * Projects are natively multi-device: the same definition (home-relative paths)
- * re-roots on every fleet machine, and the question is whether the project's
- * repos are PRESENT on each box, on which branch, how far ahead/behind their
- * upstream, and whether they carry uncommitted changes. This module is the pure
- * local half: given a set of home-relative paths it probes each one with a
- * handful of read-only git calls. Drift is measured against the LAST-FETCHED
- * upstream (`@{upstream}`) — deliberately no `git fetch`, so a probe is fast
- * and offline-safe. The fleet half (`--fleet`) just runs this probe on every
- * peer via the canonical `remote-agents-json` SSH fan-out.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { execFileSync } from 'child_process';
 import chalk from 'chalk';
 import { expandLocalHome, toHomeRelative } from './project-root.js';
 import { projectProbeTargets } from './projects.js';
-/** Per-call git budget. A read-only git call taking >3s is wedged by any
- * definition (NFS stall, index lock) — and the fleet fan-out SIGKILLs the SSH
- * hop at 12s, so a probe must fit inside that budget to avoid a slow peer
- * being misreported as unreachable: 3s × 5 calls leaves headroom even when
- * one repo is genuinely stuck. */
 const GIT_TIMEOUT_MS = 3_000;
-/** One read-only git call against `absPath`; undefined on any failure. */
 function git(absPath, args) {
     try {
         return execFileSync('git', ['-C', absPath, ...args], {
@@ -36,12 +17,6 @@ function git(absPath, args) {
         return undefined;
     }
 }
-/**
- * Probe one workspace repo. A missing path yields `{present: false}` and no
- * git call is made. On a present repo every signal is best-effort: whatever
- * succeeded is reported, and a repo whose `.git` exists yet every git call
- * failed surfaces as present-with-error rather than silently clean.
- */
 export function probeRepoWorkspace(absPath) {
     const status = { path: toHomeRelative(absPath), present: false };
     if (!fs.existsSync(path.join(absPath, '.git')))
@@ -49,8 +24,6 @@ export function probeRepoWorkspace(absPath) {
     status.present = true;
     const branch = git(absPath, ['rev-parse', '--abbrev-ref', 'HEAD']);
     const upstream = git(absPath, ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}']);
-    // `--left-right --count A...B` prints "<left>\t<right>" — left is
-    // upstream-only (we are BEHIND by that much), right is HEAD-only (AHEAD).
     const counts = upstream !== undefined
         ? git(absPath, ['rev-list', '--left-right', '--count', '@{upstream}...HEAD'])
         : undefined;
@@ -77,30 +50,12 @@ export function probeRepoWorkspace(absPath) {
         status.lastCommit = lastCommit;
     return status;
 }
-/** Probe each home-relative path (expanded against the local home), in order. */
 export function probeProjectWorkspaces(paths) {
     return paths.map((p) => probeRepoWorkspace(expandLocalHome(p)));
 }
-/**
- * The home-relative paths to probe for a project definition: its `root` plus
- * each `repos[].path` (the opt-in for additional repos), deduped. Every target
- * is normalized through the same `toHomeRelative(expandLocalHome(...))` the
- * probe echoes, so a hand-edited def (absolute path under home, trailing
- * slash) matches its probe rows exactly — `writeProjectDef` normalizes on
- * write, but defs are hand-editable YAML and never silently drop a row.
- *
- * The walk itself lives in `projects.ts` so the probe and the spawn grants read
- * one definition of "the project's directories" instead of two that drift.
- */
 export function workspaceTargetsForDef(def) {
     return projectProbeTargets(def);
 }
-/**
- * Parse a peer's `projects probe` stdout, tagging each row with the
- * machine that answered. Defensive against version skew / partial output, the
- * same boundary contract as `parseRemoteActive`: non-JSON or a non-array
- * yields `[]`, and rows without a `path`/`present` core are dropped.
- */
 export function parseRemoteProbe(stdout, machine) {
     let parsed;
     try {
@@ -121,10 +76,6 @@ export function parseRemoteProbe(stdout, machine) {
         return [];
     });
 }
-/**
- * One workspace's compact state: `✓ clean · main`, `⚠ 12 dirty · ↑3 ↓1 ·
- * feature/x`, `✗ missing`, or `⚠ error: …`. Pure — chalk styling only.
- */
 export function formatWorkspaceLine(s) {
     if (!s.present)
         return chalk.red('✗ missing');
@@ -142,12 +93,6 @@ export function formatWorkspaceLine(s) {
     const head = parts.length > 0 ? chalk.yellow(`⚠ ${parts.join(' · ')}`) : chalk.green('✓ clean');
     return s.branch ? `${head} ${chalk.dim('·')} ${s.branch}` : head;
 }
-/**
- * The fleet view of one project's workspaces: one content line per probed
- * path (host-sorted `host: state` cells joined by ` · `), labelled with the
- * path when a project probes more than one. Pure — the caller adds the
- * `fleet` row label.
- */
 export function formatFleetWorkspaces(statuses) {
     const paths = [...new Set(statuses.map((s) => s.path))];
     const multi = paths.length > 1;
@@ -159,15 +104,6 @@ export function formatFleetWorkspaces(statuses) {
         return multi ? `${chalk.dim(`${p} · `)}${body}` : body;
     });
 }
-/**
- * One-line fleet health summary — `6/13 clean · 4 behind · 4 dirty · 1 missing`.
- * Sits ABOVE the per-host {@link formatFleetWorkspaces} table so the card is
- * scannable without reading every host cell; the table keeps the per-host branch
- * and drift detail. Zero buckets are omitted. `behind` colours red when any host
- * is ≥10 behind (matching the footer's critical threshold), else yellow; a host
- * that is both behind and dirty counts in both. Each host×path row is one unit,
- * the same unit the table renders. Pure — chalk styling only.
- */
 export function formatFleetSummary(statuses) {
     const total = statuses.length;
     let clean = 0;
@@ -181,7 +117,7 @@ export function formatFleetSummary(statuses) {
             continue;
         }
         if (s.error)
-            continue; // unreadable — neither clean nor a drift bucket (surfaced in the footer)
+            continue;
         const isBehind = s.behind !== undefined && s.behind > 0;
         const isDirty = s.dirty !== undefined && s.dirty > 0;
         if (isBehind) {
@@ -203,25 +139,6 @@ export function formatFleetSummary(statuses) {
         parts.push(chalk.red(`${missing} missing`));
     return parts.join(chalk.dim(' · '));
 }
-/**
- * Turn probed workspace rows into card-footer warnings, GROUPED by root cause so
- * a fleet where eight hosts drift is a few lines, not sixteen (each with its own
- * repeated remediation).
- *
- * - missing / unreadable git → critical (agents there cannot share a tree)
- * - behind upstream → critical when ANY host is ≥10 commits behind, else continue
- * - dirty tree → continue (local work is fine; just note it)
- * - ahead-only is not a warning (that is progress waiting to push)
- *
- * Within one probed path, all behind hosts collapse to one warning listing each
- * host with its count (`4 hosts behind origin/main — mac-mini ↓172, …`) plus one
- * shared remediation; a lone host keeps its full sentence. Missing and dirty
- * collapse the same way. `error` stays per-host (each message is distinct).
- * Grouping is per path so two different repos never merge into one count. Unlike
- * doctor's `emitGroup`, the list names EVERY host, not the first two — each
- * host's drift count differs and is individually actionable. Pure — chalk only.
- * Caller decides whether the rows came from `--fleet` or a local probe.
- */
 export function workspaceWarnings(statuses) {
     const out = [];
     const where = (s) => (s.host ? s.host : 'local');
@@ -230,7 +147,6 @@ export function workspaceWarnings(statuses) {
         const pathBit = path ? ` (${path})` : '';
         const rows = statuses.filter((s) => s.path === path);
         const present = rows.filter((s) => s.present && !s.error);
-        // Missing checkout — grouped critical, a lone host keeps its full sentence.
         const missing = rows.filter((s) => !s.present).sort((a, b) => where(a).localeCompare(where(b)));
         if (missing.length === 1) {
             out.push({
@@ -246,11 +162,9 @@ export function workspaceWarnings(statuses) {
                 remediation: 'clone or sync the project root on those hosts before landing agents there',
             });
         }
-        // Unreadable git — one per host, since each error message is distinct.
         for (const s of rows.filter((s) => s.present && s.error).sort((a, b) => where(a).localeCompare(where(b)))) {
             out.push({ severity: 'critical', text: `${where(s)}: ${s.error}${pathBit}` });
         }
-        // Behind upstream — grouped, worst count first, one shared remediation.
         const behind = present
             .filter((s) => s.behind !== undefined && s.behind > 0)
             .sort((a, b) => (b.behind ?? 0) - (a.behind ?? 0) || where(a).localeCompare(where(b)));
@@ -272,7 +186,6 @@ export function workspaceWarnings(statuses) {
                 remediation: 'pull (or rebase) before agents on these hosts open PRs against a stale base',
             });
         }
-        // Dirty tree — grouped, most changes first, no remediation (local work is fine).
         const dirty = present
             .filter((s) => s.dirty !== undefined && s.dirty > 0)
             .sort((a, b) => (b.dirty ?? 0) - (a.dirty ?? 0) || where(a).localeCompare(where(b)));

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

@@ -1,129 +1,33 @@
-/**
- * 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 { type ProjectRepoTarget } from './projects.js';
 import { type RemoteAgentsJsonParseResult } from './remote-agents-json.js';
 export type ProjectPullStatus = 'updated' | 'current' | 'missing' | 'blocked' | 'failed';
 export interface ProjectPullResult {
-    /** Machine that ran the pull (from {@link machineId}). */
     host: string;
-    /** Home-relative path — re-roots on each fleet device. */
     path: string;
-    /** Expected GitHub slug, echoed from the target for reference. */
     expectedSlug?: string;
     status: ProjectPullStatus;
     branch?: string;
     upstream?: string;
-    /** Short commit hash HEAD was at before the pull. */
     before?: string;
-    /** Short commit hash HEAD is at after the pull. */
     after?: string;
-    /** Human-readable status or error; present when status is not `current`. */
     message?: string;
 }
-/** The wire format this machine emits for the fleet fan-out. Fail-closed on parse. */
 interface ProjectPullEnvelope {
     schemaVersion: 1;
     kind: 'project-pull';
-    /** The emitting machine's {@link machineId} — verified by the caller. */
     machine: string;
-    /** Hash of the target list the caller sent — verified before trusting results. */
     targetFingerprint: string;
     results: ProjectPullResult[];
 }
-/**
- * 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 declare function fingerprintTargets(targets: ProjectRepoTarget[]): string;
-/**
- * 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 declare function encodePullTargets(targets: ProjectRepoTarget[]): string;
-/**
- * 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 declare function pullLocalArgs(targets: ProjectRepoTarget[]): string[];
-/**
- * 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 declare function decodePullTargets(raw: string): ProjectRepoTarget[];
-/**
- * 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 declare function pullProjectTargets(targets: ProjectRepoTarget[], host?: string): Promise<ProjectPullResult[]>;
 export declare function buildPullEnvelope(results: ProjectPullResult[], targets: ProjectRepoTarget[]): ProjectPullEnvelope;
-/**
- * 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 declare function parseProjectPullEnvelope(stdout: string, machine: string, opts?: {
     expectedFingerprint?: string;
 }): RemoteAgentsJsonParseResult<ProjectPullResult>;
-/**
- * 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 declare function projectPullComplete(results: ProjectPullResult[]): boolean;
-/**
- * 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 declare function printProjectPullSummary(projectName: string, results: ProjectPullResult[], unavailableDevices: string[], unverifiedDevices?: string[]): void;
 export {};