@phnx-labs/agents-cli 1.20.92 → 1.20.93

package/dist/lib/linear-project-counts.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Per-project Linear issue counts for the `agents projects status` card.
+ *
+ * When a project definition carries `linear.projectId` (set via
+ * `agents projects link <name> --linear`), the card shows one outcome line —
+ * `12/30 done · 5 in progress` — counted from the Linear GraphQL API by state
+ * TYPE (triage / backlog / unstarted / started / completed / canceled), never
+ * hardcoded state names, same convention as `auto-dispatch-linear.ts`.
+ *
+ * This is a best-effort card enrichment, not an explicit command: every failure
+ * (no credential, offline, API error, timeout) degrades to `undefined` and the
+ * card simply omits the line — never a hang, never a throw. `--no-remote`
+ * skips it (it's network). The API key resolves through the same chain the rest
+ * of the stack uses: $LINEAR_API_KEY → macOS Keychain (`resolveLinearApiKey`)
+ * → the linear-cli config (`~/.linear-cli/config.json` `apiKey`).
+ *
+ * Paging is capped (10 × 250 issues) so a pathological project can't burn the
+ * budget; a capped fetch reports `truncated: true` and the card renders the
+ * total as a lower bound (`2500+ done`), never as the complete count.
+ */
+/** The counts the card renders. `total` counts every issue in the project. */
+export interface LinearProjectCounts {
+    /** Issues in a `completed`-type state. */
+    done: number;
+    /** All issues in the project (any state type, including canceled). */
+    total: number;
+    /** Issues in a `started`-type state. */
+    inProgress: number;
+    /**
+     * True when the page cap cut the fetch short — `total` is then a LOWER
+     * bound (rendered `2500+`), never presented as the complete count.
+     */
+    truncated?: boolean;
+}
+/** The GraphQL response shape this module consumes (recorded for the tests). */
+export interface LinearIssuesResponse {
+    issues?: {
+        nodes?: Array<{
+            state?: {
+                type?: string;
+            } | null;
+        }>;
+        pageInfo?: {
+            hasNextPage?: boolean;
+            endCursor?: string | null;
+        };
+    };
+}
+/**
+ * Pure mapping: a Linear issues response → card counts, grouping by state
+ * type. Defensive at the boundary — a missing `issues`/`nodes` yields zeros,
+ * an issue with no state still counts toward `total`.
+ */
+export declare function countsFromIssuesResponse(data: LinearIssuesResponse): LinearProjectCounts;
+/**
+ * Fetch issue counts for one Linear project, paging `issues` filtered by
+ * project id. One shared AbortController bounds the WHOLE paged fetch at ~8s;
+ * any failure (no key, network, API error, abort) returns undefined so the
+ * card just omits the line. `fetchPage` is injectable for tests — the
+ * accumulator (cursor hand-off, cap) is the risky logic, not the HTTP.
+ */
+export declare function fetchLinearProjectCounts(projectId: string, fetchPage?: (projectId: string, after: string | undefined, signal: AbortSignal) => Promise<LinearIssuesResponse | undefined>): Promise<LinearProjectCounts | undefined>;

package/dist/lib/linear-project-counts.js

@@ -0,0 +1,122 @@
+/**
+ * Per-project Linear issue counts for the `agents projects status` card.
+ *
+ * When a project definition carries `linear.projectId` (set via
+ * `agents projects link <name> --linear`), the card shows one outcome line —
+ * `12/30 done · 5 in progress` — counted from the Linear GraphQL API by state
+ * TYPE (triage / backlog / unstarted / started / completed / canceled), never
+ * hardcoded state names, same convention as `auto-dispatch-linear.ts`.
+ *
+ * This is a best-effort card enrichment, not an explicit command: every failure
+ * (no credential, offline, API error, timeout) degrades to `undefined` and the
+ * card simply omits the line — never a hang, never a throw. `--no-remote`
+ * skips it (it's network). The API key resolves through the same chain the rest
+ * of the stack uses: $LINEAR_API_KEY → macOS Keychain (`resolveLinearApiKey`)
+ * → the linear-cli config (`~/.linear-cli/config.json` `apiKey`).
+ *
+ * Paging is capped (10 × 250 issues) so a pathological project can't burn the
+ * budget; a capped fetch reports `truncated: true` and the card renders the
+ * total as a lower bound (`2500+ done`), never as the complete count.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { resolveLinearApiKey } from './auto-dispatch-linear.js';
+const LINEAR_API = 'https://api.linear.app/graphql';
+/** Overall budget across all pages — the card must never hang on Linear. */
+const TIMEOUT_MS = 8_000;
+const PAGE_SIZE = 250;
+/** Hard page cap so a pathological project can't page forever within the budget. */
+const MAX_PAGES = 10;
+/**
+ * Pure mapping: a Linear issues response → card counts, grouping by state
+ * type. Defensive at the boundary — a missing `issues`/`nodes` yields zeros,
+ * an issue with no state still counts toward `total`.
+ */
+export function countsFromIssuesResponse(data) {
+    const nodes = data.issues?.nodes ?? [];
+    let done = 0;
+    let inProgress = 0;
+    for (const n of nodes) {
+        const type = n?.state?.type;
+        if (type === 'completed')
+            done++;
+        else if (type === 'started')
+            inProgress++;
+    }
+    return { done, total: nodes.length, inProgress };
+}
+/** $LINEAR_API_KEY → macOS Keychain → ~/.linear-cli/config.json. Null if none. */
+function resolveApiKey() {
+    const fromChain = resolveLinearApiKey();
+    if (fromChain)
+        return fromChain;
+    try {
+        const cfg = JSON.parse(fs.readFileSync(path.join(os.homedir(), '.linear-cli', 'config.json'), 'utf8'));
+        return cfg.apiKey?.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Fetch issue counts for one Linear project, paging `issues` filtered by
+ * project id. One shared AbortController bounds the WHOLE paged fetch at ~8s;
+ * any failure (no key, network, API error, abort) returns undefined so the
+ * card just omits the line. `fetchPage` is injectable for tests — the
+ * accumulator (cursor hand-off, cap) is the risky logic, not the HTTP.
+ */
+export async function fetchLinearProjectCounts(projectId, fetchPage = fetchLinearIssuesPage) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+    try {
+        const all = [];
+        let after;
+        let truncated = false;
+        for (let page = 0;; page++) {
+            const data = await fetchPage(projectId, after, ctrl.signal);
+            if (!data)
+                return undefined;
+            all.push(...(data.issues?.nodes ?? []));
+            const pi = data.issues?.pageInfo;
+            if (!pi?.hasNextPage || !pi.endCursor)
+                break;
+            if (page + 1 >= MAX_PAGES) {
+                // The cap cut the fetch short — total is a lower bound, say so.
+                truncated = true;
+                break;
+            }
+            after = pi.endCursor;
+        }
+        return { ...countsFromIssuesResponse({ issues: { nodes: all } }), ...(truncated ? { truncated } : {}) };
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** One real GraphQL page; undefined on any HTTP/API-level failure. */
+async function fetchLinearIssuesPage(projectId, after, signal) {
+    const apiKey = resolveApiKey();
+    if (!apiKey)
+        return undefined;
+    const res = await fetch(LINEAR_API, {
+        method: 'POST',
+        headers: { Authorization: apiKey, 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            query: 'query($p:ID!, $after:String){ issues(filter:{ project:{ id:{ eq:$p } } }, first:' +
+                PAGE_SIZE +
+                ', after:$after){ nodes{ state{ type } } pageInfo{ hasNextPage endCursor } } }',
+            variables: { p: projectId, after: after ?? null },
+        }),
+        signal,
+    });
+    if (!res.ok)
+        return undefined;
+    const json = (await res.json());
+    if (json.errors?.length || !json.data)
+        return undefined;
+    return json.data;
+}

package/dist/lib/linear-projects.d.ts

@@ -0,0 +1,50 @@
+/** The minimal Linear project shape the link flow needs (id + name + url). */
+export interface LinearProjectLite {
+    id: string;
+    name: string;
+    /** Project URL, when the `linear` CLI JSON carries one. Never fabricated. */
+    url?: string;
+}
+/**
+ * Collapse a Linear name / repo slug / folder path to one comparison key:
+ * lowercase, keep only the last path segment, strip separators.
+ *   "Agents CLI"            -> "agentscli"
+ *   "phnx-labs/agents-cli"  -> "agentscli"
+ *   "~/src/.../agents-cli"  -> "agentscli"
+ */
+export declare function normalizeProjectKey(s: string): string;
+/**
+ * Find the Linear project that best matches a repo slug or folder name.
+ * Exact normalized match first, then a containment fallback (either direction),
+ * so "agents-cli-web" still suggests "Agents CLI" when no exact peer exists.
+ *
+ * Kept for parity with the Factory original — the `link` command uses
+ * {@link pickLinearProject} instead: this one returns the FIRST match (silent
+ * on duplicate names), which is fine for a UI suggestion but never for a write
+ * path.
+ */
+export declare function matchLinearProject(slugOrName: string, projects: LinearProjectLite[]): LinearProjectLite | undefined;
+/** The outcome of picking one Linear project out of the workspace list. */
+export type LinearPick = {
+    kind: 'match';
+    project: LinearProjectLite;
+} | {
+    kind: 'candidates';
+    projects: LinearProjectLite[];
+} | {
+    kind: 'none';
+};
+/**
+ * Pick the Linear project a query refers to. An exact id or exact normalized
+ * name match is confident enough to write; anything weaker (several exact-name
+ * peers, or only containment matches) comes back as a candidate LIST for the
+ * user to disambiguate — the link command never guesses on a weak signal.
+ */
+export declare function pickLinearProject(query: string, projects: LinearProjectLite[]): LinearPick;
+/**
+ * List the workspace's Linear projects via the `linear` CLI on PATH. Throws a
+ * clear error when the binary is missing, errors, or returns a shape we can't
+ * use — this backs an explicit user command, so a silent empty list would send
+ * the user down a wrong "no matches" path.
+ */
+export declare function listLinearProjects(): LinearProjectLite[];

package/dist/lib/linear-projects.js

@@ -0,0 +1,114 @@
+// Linear project matching for `agents projects link --linear`.
+//
+// A project's identity shows up three ways — a Linear project name ("Agents CLI"),
+// a GitHub repo slug ("phnx-labs/agents-cli"), and a filesystem folder
+// (".../agents-cli"). normalizeProjectKey() collapses all three to one comparison
+// key so they compare equal, and matchLinearProject() binds a repo/folder to the
+// Linear project the user most likely means.
+//
+// Ported from apps/factory/src/core/linearProjects.ts (no cross-package imports —
+// repo rule); keep the two in sync. The matcher half is PURE so it unit-tests
+// without a live `linear` binary; the `linear projects --json` shell-out lives at
+// the bottom (listLinearProjects) and fails LOUD — it's behind an explicit user
+// command, not a best-effort card enrichment.
+import { execFileSync } from 'child_process';
+/**
+ * Collapse a Linear name / repo slug / folder path to one comparison key:
+ * lowercase, keep only the last path segment, strip separators.
+ *   "Agents CLI"            -> "agentscli"
+ *   "phnx-labs/agents-cli"  -> "agentscli"
+ *   "~/src/.../agents-cli"  -> "agentscli"
+ */
+export function normalizeProjectKey(s) {
+    const last = s.toLowerCase().split('/').filter(Boolean).pop() ?? '';
+    return last.replace(/[-_\s.]/g, '');
+}
+/**
+ * Find the Linear project that best matches a repo slug or folder name.
+ * Exact normalized match first, then a containment fallback (either direction),
+ * so "agents-cli-web" still suggests "Agents CLI" when no exact peer exists.
+ *
+ * Kept for parity with the Factory original — the `link` command uses
+ * {@link pickLinearProject} instead: this one returns the FIRST match (silent
+ * on duplicate names), which is fine for a UI suggestion but never for a write
+ * path.
+ */
+export function matchLinearProject(slugOrName, projects) {
+    const key = normalizeProjectKey(slugOrName);
+    if (!key)
+        return undefined;
+    const exact = projects.find((p) => normalizeProjectKey(p.name) === key);
+    if (exact)
+        return exact;
+    return projects.find((p) => {
+        const pk = normalizeProjectKey(p.name);
+        return pk.length > 0 && (pk.includes(key) || key.includes(pk));
+    });
+}
+/**
+ * Pick the Linear project a query refers to. An exact id or exact normalized
+ * name match is confident enough to write; anything weaker (several exact-name
+ * peers, or only containment matches) comes back as a candidate LIST for the
+ * user to disambiguate — the link command never guesses on a weak signal.
+ */
+export function pickLinearProject(query, projects) {
+    const q = query.trim();
+    if (!q)
+        return { kind: 'none' };
+    const byId = projects.find((p) => p.id === q);
+    if (byId)
+        return { kind: 'match', project: byId };
+    const key = normalizeProjectKey(q);
+    if (!key)
+        return { kind: 'none' };
+    const exact = projects.filter((p) => normalizeProjectKey(p.name) === key);
+    if (exact.length === 1)
+        return { kind: 'match', project: exact[0] };
+    if (exact.length > 1)
+        return { kind: 'candidates', projects: exact };
+    const containment = projects.filter((p) => {
+        const pk = normalizeProjectKey(p.name);
+        return pk.length > 0 && (pk.includes(key) || key.includes(pk));
+    });
+    return containment.length > 0 ? { kind: 'candidates', projects: containment } : { kind: 'none' };
+}
+/**
+ * List the workspace's Linear projects via the `linear` CLI on PATH. Throws a
+ * clear error when the binary is missing, errors, or returns a shape we can't
+ * use — this backs an explicit user command, so a silent empty list would send
+ * the user down a wrong "no matches" path.
+ */
+export function listLinearProjects() {
+    let out;
+    try {
+        out = execFileSync('linear', ['projects', '--json'], {
+            encoding: 'utf8',
+            timeout: 8000,
+            maxBuffer: 16 * 1024 * 1024,
+        });
+    }
+    catch {
+        throw new Error('Could not list Linear projects — is the `linear` CLI installed and logged in? (`brew install linear-cli`, `linear auth login`)');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(out);
+    }
+    catch {
+        throw new Error('`linear projects --json` returned invalid JSON');
+    }
+    if (!Array.isArray(parsed))
+        throw new Error('`linear projects --json` did not return a list');
+    return parsed.flatMap((x) => {
+        if (x && typeof x === 'object' && !Array.isArray(x)) {
+            const o = x;
+            if (typeof o.id === 'string' && typeof o.name === 'string') {
+                const p = { id: o.id, name: o.name };
+                if (typeof o.url === 'string')
+                    p.url = o.url;
+                return [p];
+            }
+        }
+        return [];
+    });
+}

package/dist/lib/menubar/notify-desktop.d.ts

@@ -4,8 +4,12 @@
  * The one place the daemon (overdue routines, heal, routine start/finish/output)
  * emits a native desktop notification. On macOS it routes through the installed
  * `MenubarHelper.app` companion — a one-shot `MenubarHelper --notify` invocation —
- * so the notification is attributed to that bundle and carries the agents-cli /
- * Agentialized mark instead of the generic AppleScript icon. When the companion
+ * so the notification is attributed to that bundle and carries the agents-cli
+ * mark instead of the generic AppleScript icon. A banner carries two images: the
+ * agents-cli app icon on the LEFT (the sender) and, when the event belongs to one
+ * harness, that agent's avatar on the RIGHT (`agent`, rendered by
+ * AgentAvatar.swift) — the same layout macOS gives a YouTube notification, app on
+ * the left and the channel on the right. When the companion
  * app is not installed (menu bar disabled, a Linux package, a dev checkout), it
  * degrades to `osascript` so an overdue/heal notice is never silently lost — the
  * generic icon is the acceptable cost of preserving delivery, not a bug hidden by
@@ -32,6 +36,17 @@ export interface DesktopNotification {
      * macOS-only (osascript / notify-send have no click target). See routine-notify.ts.
      */
     action?: string;
+    /**
+     * Harness the notification is ABOUT (`claude`, `codex`, … — an `AgentId`).
+     * macOS draws two images on a banner: the sending bundle's app icon on the
+     * LEFT and `contentImage` on the RIGHT. The companion renders this id as the
+     * right-hand avatar (AgentAvatar.swift), so a banner reads "agents-cli, about
+     * Claude" the way a YouTube notification reads "YouTube, from this channel".
+     * Omit it when no single harness owns the event (a daemon heal, a fan-out
+     * across several agents) — the right slot then stays empty rather than
+     * repeating the left one. macOS-only; osascript / notify-send carry no image.
+     */
+    agent?: string;
 }
 /** Argv for the MenubarHelper one-shot notify mode. Exported for tests. */
 export declare function buildMenubarNotifyArgs(n: DesktopNotification): string[];

package/dist/lib/menubar/notify-desktop.js

@@ -4,8 +4,12 @@
  * The one place the daemon (overdue routines, heal, routine start/finish/output)
  * emits a native desktop notification. On macOS it routes through the installed
  * `MenubarHelper.app` companion — a one-shot `MenubarHelper --notify` invocation —
- * so the notification is attributed to that bundle and carries the agents-cli /
- * Agentialized mark instead of the generic AppleScript icon. When the companion
+ * so the notification is attributed to that bundle and carries the agents-cli
+ * mark instead of the generic AppleScript icon. A banner carries two images: the
+ * agents-cli app icon on the LEFT (the sender) and, when the event belongs to one
+ * harness, that agent's avatar on the RIGHT (`agent`, rendered by
+ * AgentAvatar.swift) — the same layout macOS gives a YouTube notification, app on
+ * the left and the channel on the right. When the companion
  * app is not installed (menu bar disabled, a Linux package, a dev checkout), it
  * degrades to `osascript` so an overdue/heal notice is never silently lost — the
  * generic icon is the acceptable cost of preserving delivery, not a bug hidden by
@@ -35,6 +39,8 @@ export function buildMenubarNotifyArgs(n) {
         args.push('--subtitle', n.subtitle);
     if (n.action)
         args.push('--action', n.action);
+    if (n.agent)
+        args.push('--agent', n.agent);
     return args;
 }
 /** AppleScript for the osascript degradation path. Exported for tests. */

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

@@ -0,0 +1,75 @@
+/**
+ * Project workspace probing — the drift signal behind `projects status --fleet`.
+ *
+ * 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. */
+export 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.
+ */
+export declare function workspaceTargetsForDef(def: ProjectDef): string[];
+/**
+ * Parse a peer's `projects probe --json` 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[];

package/dist/lib/project-probe.js

@@ -0,0 +1,160 @@
+/**
+ * Project workspace probing — the drift signal behind `projects status --fleet`.
+ *
+ * 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';
+/** 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], {
+            encoding: 'utf8',
+            timeout: GIT_TIMEOUT_MS,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+    }
+    catch {
+        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')))
+        return status;
+    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;
+    const dirtyOut = git(absPath, ['status', '--porcelain']);
+    const lastCommit = git(absPath, ['log', '-1', '--format=%cI']);
+    if (branch === undefined && dirtyOut === undefined && lastCommit === undefined) {
+        status.error = '.git exists but git could not read this repo';
+        return status;
+    }
+    if (branch !== undefined)
+        status.branch = branch;
+    if (upstream !== undefined)
+        status.upstream = upstream;
+    if (counts !== undefined) {
+        const [behind, ahead] = counts.split(/\s+/).map(Number);
+        if (Number.isFinite(behind) && Number.isFinite(ahead)) {
+            status.behind = behind;
+            status.ahead = ahead;
+        }
+    }
+    if (dirtyOut !== undefined)
+        status.dirty = dirtyOut === '' ? 0 : dirtyOut.split('\n').length;
+    if (lastCommit !== undefined)
+        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.
+ */
+export function workspaceTargetsForDef(def) {
+    const targets = [def.root, ...(def.repos ?? []).map((r) => r.path)]
+        .filter((p) => typeof p === 'string' && p.length > 0)
+        .map((p) => toHomeRelative(expandLocalHome(p)));
+    return [...new Set(targets)];
+}
+/**
+ * Parse a peer's `projects probe --json` 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 {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    return parsed.flatMap((x) => {
+        if (x && typeof x === 'object' && !Array.isArray(x)) {
+            const o = x;
+            if (typeof o.path === 'string' && typeof o.present === 'boolean') {
+                return [{ ...o, host: 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');
+    if (s.error)
+        return chalk.yellow(`⚠ error: ${s.error}`);
+    const parts = [];
+    if (s.dirty !== undefined && s.dirty > 0)
+        parts.push(`${s.dirty} dirty`);
+    const drift = [
+        s.ahead !== undefined && s.ahead > 0 ? `↑${s.ahead}` : '',
+        s.behind !== undefined && s.behind > 0 ? `↓${s.behind}` : '',
+    ].filter(Boolean).join(' ');
+    if (drift)
+        parts.push(drift);
+    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;
+    return paths.map((p) => {
+        const rows = statuses
+            .filter((s) => s.path === p)
+            .sort((a, b) => a.host.localeCompare(b.host));
+        const body = rows.map((r) => `${chalk.cyan(r.host)}: ${formatWorkspaceLine(r)}`).join(chalk.dim('  ·  '));
+        return multi ? `${chalk.dim(`${p} · `)}${body}` : body;
+    });
+}

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

@@ -5,3 +5,11 @@ export interface ProjectResourceSyncResult {
 }
 export declare function projectAgentRoot(projectRoot: string, agent: AgentId): string;
 export declare function syncProjectResourcesToAgent(agent: AgentId, version: string, projectAgentsDir: string): ProjectResourceSyncResult;
+/**
+ * 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;