@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/project-status.js

@@ -1,28 +1,9 @@
-/**
- * Project-level progress rollup — the headline of the projects subsystem.
- *
- * At 50–100 agents the per-agent activity line is noise; what matters is the
- * PROJECT. This aggregates the signals already carried per session (status,
- * plan progress, open PRs, tickets, worktrees) into one row per project, keyed
- * by matching each session's cwd to a defined project root (`projectNameForCwd`).
- * The session set is whatever the caller passes (today `getActiveSessions()` —
- * this machine's live view, matched by local-home cwd; a fleet-wide fan-out is a
- * deferred follow-up). Pure over an `ActiveSession[]` so the aggregation is
- * unit-testable; the merged-PR signal IS repo-global (harvested via `gh`) and the
- * artifact signal is local, both added in `enrichProjectSignals`.
- */
 import { execFile } from 'child_process';
 import { promisify } from 'util';
 import chalk from 'chalk';
 import { projectNameForCwd } from './projects.js';
 import { readRecentActivity } from './feed/activity.js';
 const execFileAsync = promisify(execFile);
-/**
- * How many recent merges `gh` is asked for. A repo busy enough that all of them
- * land inside the window has more than this — agents-cli itself merged 100 of
- * its 100 most recent PRs within 7 days — so the count is reported as a lower
- * bound rather than as a total.
- */
 const MERGED_PR_LIMIT = 100;
 function blank(name) {
     return {
@@ -36,15 +17,6 @@ function blank(name) {
         worktrees: 0,
     };
 }
-/**
- * Roll active sessions up by project. Returns a map keyed by project name,
- * containing only projects with at least one matched session — callers merge
- * with the full definition list to show zero-agent projects.
- */
-/**
- * Ensure every session carries a host for the card roster. Local
- * `getActiveSessions()` omits `machine`; remotes already set it. Pure.
- */
 export function withDefaultMachine(sessions, defaultHost) {
     return sessions.map((s) => (s.machine ? s : { ...s, machine: defaultHost }));
 }
@@ -91,32 +63,10 @@ export function rollupSessionsByProject(defs, sessions) {
     }
     return map;
 }
-/**
- * Statuses that mean the session is over. Taken from the repo's own rule
- * (`commands/sessions.ts`): "`closed` and `crashed` are unconditionally dead".
- * `orphaned` is NOT among them — `session/active.ts` defines it as "Alive, but
- * no client is attached", i.e. the agent outlived its window and is still
- * working. Counting it as dead understates the project by exactly the sessions
- * that are running unattended.
- */
 const DEAD_STATUSES = new Set(['closed', 'crashed']);
-/**
- * True when a session's status means it is over. Exported so the card can keep
- * the `agents` roster to live sessions: the headline and the `dead` row already
- * separate the two, and a roster that reads `crashed ×25` beside `23 live`
- * makes the reader distrust both numbers.
- */
 export function isDeadStatus(status) {
     return DEAD_STATUSES.has(status);
 }
-/**
- * Split a rollup's sessions into what is working and what is wreckage.
- *
- * The headline used to be the raw session count, which on a real project read
- * `39 agents` when 19 of those had crashed. A count that is half corpses is not
- * a throughput signal — but the corpses are worth their own number, because 19
- * crashed sessions is itself a thing to go fix.
- */
 export function liveDeadSplit(byStatus) {
     let live = 0;
     let dead = 0;
@@ -135,14 +85,6 @@ export function liveDeadSplit(byStatus) {
     deadByStatus.sort((a, b) => b.n - a.n || a.status.localeCompare(b.status));
     return { live, dead, deadByStatus };
 }
-/**
- * The `dead` row body: `41 crashed` when every dead session shares one status,
- * else `12 finished or lost (8 crashed, 4 closed)`. The generic "finished or
- * lost" only earns its keep when the statuses actually differ — with a single
- * status it just hides which one behind a parenthetical that repeats the count.
- * Pure — chalk styling only; the caller adds the `dead` label. Assumes
- * `split.dead > 0` (the caller gates on it).
- */
 export function formatDeadSummary(split) {
     if (split.deadByStatus.length === 1) {
         return chalk.yellow(`${split.dead} ${split.deadByStatus[0].status}`);
@@ -150,13 +92,7 @@ export function formatDeadSummary(split) {
     const detail = split.deadByStatus.map((d) => `${d.n} ${d.status}`).join(', ');
     return `${chalk.yellow(`${split.dead} finished or lost`)} ${chalk.dim(`(${detail})`)}`;
 }
-/**
- * Display order for the members line: the states a human scans for first
- * (running, then idle, then need-input, then queued), everything else after,
- * status name then agent name ascending within a state.
- */
 const MEMBER_STATUS_RANK = { running: 0, idle: 1, input_required: 2, queued: 3 };
-/** Sort members for the card: running first, then idle, then the rest; agent name asc within a state. */
 export function sortProjectMembers(members) {
     return [...members].sort((a, b) => {
         const ra = MEMBER_STATUS_RANK[a.status] ?? 4;
@@ -168,14 +104,8 @@ export function sortProjectMembers(members) {
         return a.agent.localeCompare(b.agent);
     });
 }
-/** Cap for the members line before it collapses to `+N more`. */
 export const MEMBERS_LINE_LIMIT = 6;
-/** Cap for host groups on the multi-line agents roster. */
 const MEMBERS_HOST_LIMIT = 8;
-/**
- * Collapse members into distinct state cells (`agent · status · ticket[@host]`),
- * counting duplicates as `×N`. Pure.
- */
 function collapseMemberCells(members, opts = {}) {
     const includeHost = opts.includeHostOnCell !== false;
     const counts = new Map();
@@ -202,29 +132,11 @@ function formatCollapsedCells(cells, memberTotal, limit) {
     const parts = shown.map(({ cell, n }) => (n > 1 ? `${cell} ×${n}` : cell));
     return parts.join(chalk.dim('  ·  ')) + (more > 0 ? chalk.dim(`  ·  +${more} more`) : '');
 }
-/**
- * The `agents` line under `live`: one cell per DISTINCT member state —
- * `claude · running · RUSH-2107 @zion` — with identical cells collapsed to a
- * `×N` count (35 same-harness sessions in one state are one fact, not six
- * truncated duplicates), capped at {@link MEMBERS_LINE_LIMIT} cells with a
- * `+N more` tail counting members, not cells. Pure (chalk styling only); the
- * caller adds the label.
- *
- * Prefer {@link formatProjectMembersByHost} on the card: a flat line hides which
- * machine is running the work when the same harness×status spans hosts.
- */
 export function formatProjectMembers(members, limit = MEMBERS_LINE_LIMIT) {
     if (members.length === 0)
         return '';
     return formatCollapsedCells(collapseMemberCells(members, { includeHostOnCell: true }), members.length, limit);
 }
-/**
- * Host-grouped agents roster. One content line per host:
- * `@zion  claude · running ×9  ·  claude · idle ×4`
- *
- * When no member carries a host (local-only rollup with no machine stamp), falls
- * back to a single flat line via {@link formatProjectMembers}. Pure.
- */
 export function formatProjectMembersByHost(members, opts = {}) {
     if (members.length === 0)
         return [];
@@ -242,12 +154,10 @@ export function formatProjectMembersByHost(members, opts = {}) {
         else
             byHost.set(key, [m]);
     }
-    // Local-only (no host stamps at all) — keep the compact one-liner.
     if (!anyHost) {
         const line = formatProjectMembers(members, cellLimit);
         return line ? [line] : [];
     }
-    // Hosts with the most members first, then name; unstamped ("") last.
     const hosts = [...byHost.entries()].sort((a, b) => {
         if (a[0] === '' && b[0] !== '')
             return 1;
@@ -262,7 +172,6 @@ export function formatProjectMembersByHost(members, opts = {}) {
     const hostWidth = Math.max(...shownHosts.map(([h]) => (h ? `@${h}` : '@local').length), 1);
     const lines = shownHosts.map(([host, ms]) => {
         const label = (host ? `@${host}` : '@local').padEnd(hostWidth);
-        // Host is the row key — do not repeat @host on every cell.
         const cells = collapseMemberCells(ms, { includeHostOnCell: false });
         const body = formatCollapsedCells(cells, ms.length, cellLimit);
         return `${chalk.cyan(label)}  ${body}`;
@@ -273,23 +182,13 @@ export function formatProjectMembersByHost(members, opts = {}) {
     }
     return lines;
 }
-/**
- * Severity markers for the warnings footer. User-facing by design: critical
- * stops you (wrong repo, missing checkout, large drift); continue is a soft
- * nudge (dirty tree, schedule not measurable).
- */
 export function warningEmoji(severity) {
     return severity === 'critical' ? '🔴' : '⚠️';
 }
-/** Stable sort: critical first, then continue; stable within a tier. */
 function sortProjectWarnings(warnings) {
     const rank = { critical: 0, continue: 1 };
     return [...warnings].sort((a, b) => rank[a.severity] - rank[b.severity] || a.text.localeCompare(b.text));
 }
-/**
- * Format one or more warning lines for the card footer. Pure (chalk only).
- * Returns empty when there is nothing to say.
- */
 export function formatProjectWarnings(warnings) {
     if (warnings.length === 0)
         return [];
@@ -303,13 +202,6 @@ export function formatProjectWarnings(warnings) {
     }
     return lines;
 }
-/**
- * Harvest the signals that don't live on the active-session list: recently
- * merged PRs (from GitHub via `gh`) and artifacts agents produced (from the
- * local activity-milestone log, matched to the project by cwd). Best-effort —
- * a missing `gh`, no auth, or no repo degrades to zero rather than throwing, so
- * `projects status` still renders. `nowMs` is injected for testability.
- */
 export async function enrichProjectSignals(def, windowDays, nowMs, opts = {}) {
     const sinceMs = nowMs - windowDays * 86_400_000;
     const out = { windowDays, mergedPrs: 0, artifacts: 0 };
@@ -321,25 +213,17 @@ export async function enrichProjectSignals(def, windowDays, nowMs, opts = {}) {
             out.lastArtifact = mine[0].detail;
     }
     catch {
-        /* activity log unreadable — best-effort */
     }
     if (def.repo && !opts.skipRemote) {
         try {
             const { stdout } = await execFileAsync('gh', ['pr', 'list', '--repo', def.repo, '--state', 'merged', '--json', 'number,mergedAt', '--limit', String(MERGED_PR_LIMIT)], { timeout: 8000, encoding: 'utf8' });
             const rows = JSON.parse(stdout);
             out.mergedPrs = rows.filter((r) => r.mergedAt && Date.parse(r.mergedAt) >= sinceMs).length;
-            // `--limit 100` caps the fetch, so a busy repo where every one of the 100
-            // most recent merges falls inside the window has MORE than 100 — this repo
-            // really does. Say so (`100+`) rather than presenting a cap as a count,
-            // the same contract `LinearProjectCounts.truncated` already keeps.
             if (rows.length >= MERGED_PR_LIMIT && out.mergedPrs >= MERGED_PR_LIMIT)
                 out.mergedPrsTruncated = true;
         }
         catch {
-            /* gh missing / unauthenticated / repo not found — skip this signal */
         }
-        // Latest release of the PRIMARY repo only (repos[] is deliberately not
-        // scanned — one release line per card). Same best-effort degradation.
         try {
             const { stdout } = await execFileAsync('gh', ['release', 'list', '-R', def.repo, '-L', '1', '--json', 'tagName,publishedAt'], { timeout: 8000, encoding: 'utf8' });
             const rows = JSON.parse(stdout);
@@ -348,7 +232,6 @@ export async function enrichProjectSignals(def, windowDays, nowMs, opts = {}) {
                 out.latestRelease = { tag: first.tagName, publishedAt: first.publishedAt ?? '' };
         }
         catch {
-            /* gh missing / unauthenticated / repo has no releases — skip this signal */
         }
     }
     return out;

package/dist/lib/projects.d.ts

@@ -1,266 +1,69 @@
-/**
- * Named project definitions — the layer above the `--project <slug>` convention.
- *
- * `agents run --project <slug>` already resolves a bare name to a working
- * directory by pure convention (`<projectRoot>/<slug>`, see `project-root.ts`).
- * This module adds editable definitions on top: one YAML file per project under
- * `~/.agents/projects/<name>.yaml`, sitting beside the existing `routines/`,
- * `monitors/`, and `teams/` dirs in the user repo.
- *
- * That location makes definitions SYNCABLE, not automatically synced: they ride
- * the user repo only once they are committed to it, via `agents repo push user`
- * (`agents push` was removed). Until then the directory is untracked, and a
- * reconcile that cleans the working tree deletes it — observed twice on one
- * machine, taking four definitions with it each time. The recovery is an
- * orphaned `chore(local): save …-sync drift` commit, which is not a guarantee:
- * unreachable objects are collected. Say "commit them" rather than "for free".
- *
- * A defined project can name itself
- * independently of its folder, bind more than one repo, pin a monorepo subpath,
- * describe context subdirectories an agent should start from, carry a Linear
- * link and external integrations, and set an explicit default path.
- *
- * Portable by construction: `root`/`defaultPath` are stored home-relative
- * (`~/…`) via `toHomeRelative`, so the same definition re-roots on any machine
- * whose home differs — the exact mechanism `project-root.ts` already relies on.
- *
- * Resolution stays additive: an undefined slug still resolves exactly as today
- * (see `resolveProjectRef`), a defined one overrides it.
- */
-/** A git repo bound to a project, with an optional monorepo subpath. */
 export interface ProjectRepo {
-    /** GitHub slug `owner/repo`. */
     slug: string;
-    /** Optional path within the repo an agent working this project cares about. */
     subpath?: string;
-    /**
-     * Optional home-relative local checkout of this repo. The def's `root` only
-     * knows the primary repo on disk; `path` opts an additional repo into
-     * workspace probing (`projects status`).
-     */
     path?: string;
 }
-/**
- * One checkout target for `projects pull`: a home-relative path plus the
- * expected GitHub slug so the pull step can verify the remote matches before
- * fast-forwarding. `expectedSlug` is absent when a bound dir has no declared
- * slug (the pull still fast-forwards; it just skips the slug check).
- */
 export interface ProjectRepoTarget {
-    /** Home-relative path — re-roots on each fleet device. */
     path: string;
-    /** Expected GitHub slug (`owner/repo`) for the remote; absent = unchecked. */
     expectedSlug?: string;
 }
-/**
- * A described context anchor: a subdirectory plus what it is. Agents starting on
- * the project read `purpose` to know where to look — an indexed starting point,
- * not just a path. This is the richer form of the single monorepo-focus dir.
- */
 export interface ProjectContext {
-    /** Path relative to the project root (e.g. `apps/web`). */
     path: string;
-    /** One line on how this subtree relates to the project. */
     purpose: string;
 }
-/**
- * A project goal — the OKR-shaped "why". A project serves one or more goals: a
- * qualitative `objective` ("Ship agents-cli 2.0") and an optional `measure`, the
- * key result that says whether it's landing ("fleet on 2.x", "p95 < 200ms"). The
- * goal is the outcome the work is chasing; milestones (dated checkpoints, pulled
- * from Linear) and live work (agents / PRs / artifacts) are how far along it is.
- */
 export interface ProjectGoal {
-    /** The outcome, in a line. */
     objective: string;
-    /** Optional key result — how success is measured. */
     measure?: string;
 }
-/** An external context source hung off the project (surfaced in `projects show`). */
 export interface ProjectIntegration {
-    /** e.g. `gdrive`, `notion`, `figma`, `url`. */
     kind: string;
     url: string;
     label?: string;
 }
-/** The parsed `~/.agents/projects/<name>.yaml`. */
 export interface ProjectDef {
-    /** Stable id; matches the filename; what `--project` takes. */
     name: string;
     description?: string;
-    /** Repo / monorepo root, home-relative for portability. */
     root?: string;
-    /** Where an agent's cwd lands. Defaults to `root` when unset. */
     defaultPath?: string;
-    /** Primary GitHub slug (`owner/repo`) — for PR / CI / status roll-up. */
     repo?: string;
-    /** All bound repos, each with an optional monorepo subpath. */
     repos?: ProjectRepo[];
-    /** Described starting points inside the project. */
     contexts?: ProjectContext[];
-    /** The outcomes this project serves (OKR-shaped); a project may have several. */
     goals?: ProjectGoal[];
-    /** External context sources (Drive, docs, …). */
     integrations?: ProjectIntegration[];
-    /** Linear project link — reuses the existing GraphQL path. */
     linear?: {
         projectId?: string;
         url?: string;
         name?: string;
     };
-    /** Free-form doc links surfaced in `projects show`. */
     docs?: string[];
-    /**
-     * Auto-dispatch settings. When `enabled` is true and `maxAgents > 0` and the
-     * project has a `linear.projectId`, the daemon polls Linear for delegated-Todo
-     * tickets and dispatches them up to the concurrency cap.
-     */
     dispatch?: {
-        /** Opt-in: enable auto-dispatch for this project (default: off). */
         enabled?: boolean;
-        /** Per-project concurrency cap for auto-dispatched agents. */
         maxAgents?: number;
-        /** Optional provider pin: 'rush' | 'codex' | 'factory' | 'host' | … */
         provider?: string;
-        /** For provider='host': which machine to dispatch onto (name/device/cap tag). */
         host?: string;
     };
 }
-/** A project name safe to use as a filename: no separators, `..`, or leading dot. */
 export declare function isSafeProjectName(name: string): boolean;
-/** Absolute path to a project's YAML definition. Throws on an unsafe name. */
 export declare function projectDefPath(name: string): string;
-/**
- * Validate a raw parsed object into a `ProjectDef`, throwing an actionable error
- * on the first problem. A malformed document or identity (bad/mismatched name)
- * throws; malformed entries inside the optional lists (`repos`/`contexts`/
- * `integrations`) are dropped so one bad row can't sink an otherwise good def.
- */
 export declare function validateProjectDef(raw: unknown, sourceName?: string): ProjectDef;
-/**
- * Load a single project definition by name. Returns undefined when the file is
- * absent (the common "not a defined project, fall back to convention" case) but
- * throws when a file EXISTS and is malformed — a broken definition is loud.
- */
 export declare function loadProjectDef(name: string): ProjectDef | undefined;
-/**
- * List every defined project, sorted by name. A missing projects directory is
- * the empty state; malformed definitions and filesystem failures stay loud so
- * CLI callers (including Factory) can show the actual error.
- */
 export declare function listProjectDefs(): ProjectDef[];
-/**
- * Persist a project definition, normalizing `root`/`defaultPath` to home-relative
- * so it stays portable across machines. Creates the projects dir on first write.
- * Writes via temp+rename so readers never see a partial file.
- */
 export declare function writeProjectDef(def: ProjectDef): string;
-/** Delete a project definition. Returns true if a file was removed. Never touches the repo. */
 export declare function removeProjectDef(name: string): boolean;
-/**
- * The cwd an agent lands in for a defined project: `defaultPath` when set, else
- * `root`. Home-relative when `forRemote` (the remote shell expands `~`), else
- * expanded against the local home. Returns undefined when neither is set.
- */
 export declare function projectBasePath(def: ProjectDef, forRemote: boolean): string | undefined;
-/**
- * All checkout targets for a project definition, each tagged with its expected
- * GitHub slug. The primary root carries `def.repo`; each `repos[i].path`
- * carries `repos[i].slug`. Paths are home-relative (re-root per fleet device)
- * and include missing checkouts so a remote peer can answer `missing` for them.
- *
- * This is the single authoritative expansion for both `projects status` (via
- * {@link projectProbeTargets}) and `projects pull`, so the two commands always
- * operate on exactly the same set of directories.
- */
 export declare function projectRepoTargetsForDef(def: ProjectDef): ProjectRepoTarget[];
-/**
- * The directories `projects status` probes across the fleet: the repo root plus
- * every bound checkout, home-relative so each host re-roots them, and including
- * directories absent here so a peer can still answer `✗ missing` for them.
- */
 export declare function projectProbeTargets(def: ProjectDef): string[];
-/**
- * The directories an agent spawned on this project should reach: the cwd first
- * (`resolveDefinedProjectPath`, so cwd behavior is unchanged), then every other
- * bound repo. `forRemote` keeps them `~/…` so the remote shell re-roots them at
- * its own `$HOME`; locally they are absolute and filtered to what exists.
- *
- * Callers pass the resolved primary so a `--project slug@worktree` run grants
- * the sibling repos alongside the worktree it actually landed in.
- */
 export declare function projectDirsAbs(def: ProjectDef, opts: {
     forRemote: boolean;
     primary?: string;
 }): string[];
-/**
- * The repository paths a project claims, as `{ slug, prefix }` with `prefix`
- * repo-relative and `dir/` shaped — the same ownership {@link projectRootsAbs}
- * applies to a session's cwd, expressed against the repository instead of a
- * checkout: a `defaultPath` narrowed under `root` claims that subtree of the
- * primary `repo`, and a `repos[]` entry with a `subpath` claims that subpath. A
- * project with no narrowed claim on a repository claims all of it and yields no
- * row for it. Two cases of {@link projectRootsAbs} have no repository form and
- * yield nothing here: a `defaultPath` outside `root` (no repo-relative path),
- * and the weak root of a narrowed project (it only takes what nobody claims,
- * which for a PR is the `repo-wide` scope).
- */
 export declare function repoPathClaims(def: ProjectDef): Array<{
     slug: string;
     prefix: string;
 }>;
-/**
- * Which defined project a session belongs to, derived from its working
- * directory. A session whose `cwd` sits inside a project's repo root (or a
- * worktree under it) is a member; the LONGEST matching root wins so a nested
- * project beats its parent. Returns undefined when no definition contains the
- * path.
- *
- * The comparison is against the LOCAL home: roots and the cwd are both expanded
- * with `expandLocalHome` and resolved, so this matches sessions whose cwd shares
- * this machine's home layout. A session recorded on a different-home machine
- * (`/Users/x/…` vs `/home/x/…`) will not match until the fleet-wide,
- * home-relative variant lands (see docs/concepts.md).
- */
 export declare function projectNameForCwd(cwd: string | undefined, defs: ProjectDef[]): string | undefined;
 export declare function listProjectDefsCached(): ProjectDef[];
-/** Drop the {@link listProjectDefsCached} memo — for tests that rewrite the dir within one mtime tick. */
 export declare function resetProjectDefsCache(): void;
-/**
- * The **confirmed** project for a working directory, or `undefined` when the
- * association is not confirmed (PHNX-3999 F08/F09).
- *
- * Confirmed means exactly one thing: a registered project definition
- * ({@link projectNameForCwd}) whose root contains this path. Being inside *some*
- * git repository is NOT a project association — a repo nobody registered, a
- * checkout of someone else's code, or a loose directory that merely has a
- * `.git` in it would each invent a project name out of a folder, which is the
- * wrong-grouping the owner's recording shows at 01:30–01:56. So is a bare
- * directory basename ({@link resolveProjectKey}, which always answers).
- *
- * A consumer renders `undefined` as Uncategorized and keeps the session
- * reachable in its full list — nothing is hidden by not being grouped.
- *
- * Use {@link resolveProjectNameForCwd} instead when you want a best-effort
- * bucket KEY for joining rows; use this when the answer is shown to a person as
- * "this work belongs to that project".
- */
 export declare function confirmedProjectForCwd(cwd: string | undefined | null, defs?: ProjectDef[]): string | undefined;
-/**
- * The canonical project label for a cwd, for every surface that buckets work by
- * project (the activity timeline, feed posts, the sessions overview): the
- * DEFINED project whose root contains the cwd (longest root wins, so a
- * multi-repo project reads as one bucket), else the repository-level key from
- * {@link resolveProjectKey}. `defs` comes from {@link listProjectDefs}, which is
- * fail-open — with no definitions this degrades to exactly today's behavior.
- */
 export declare function resolveProjectNameForCwd(cwd: string | undefined | null, defs: ProjectDef[]): string | undefined;
-/**
- * Resolve a defined project's ref to a working directory, mirroring
- * `buildProjectPath`'s `forRemote` contract (a home-relative `~/…` for the
- * remote shell to expand, an absolute local path otherwise). A `@worktree`
- * lands under the repo ROOT's `.agents/worktrees/`, not the `defaultPath`
- * subdir — worktrees are per-repo, not per-focus. Returns undefined when the
- * definition carries no `root`/`defaultPath` (caller falls back to convention).
- */
 export declare function resolveDefinedProjectPath(def: ProjectDef, worktree: string | undefined, forRemote: boolean): string | undefined;