@phnx-labs/agents-cli 1.22.120 → 1.22.121

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

@@ -1,119 +1,24 @@
-/**
- * Projects-root resolution for the `agents run --project <slug>` shorthand.
- *
- * Projects follow a predictable layout — `<root>/<repo>` (e.g.
- * `~/src/github.com/<user>/<repo>`), with git worktrees under
- * `<repo>/.agents/worktrees/<slug>`. The root is auto-inferred from the repo you
- * launch inside (the directory ABOVE the git root) and cached in `agents.yaml`
- * so later runs resolve a bare slug from anywhere. It is stored home-relative
- * (`~/…`) when it sits under `$HOME`, so the SAME value resolves on a remote
- * host whose home differs (`/home/<user>` vs `/Users/<user>`): a `--device` run
- * keeps the `~` and lets the remote login shell expand it (see `remoteCdPrefix`
- * in `hosts/dispatch.ts`), while a local run expands `~` against the local home.
- */
-/** Rewrite an absolute path under the local home to a `~/`-relative string; pass others through. */
 export declare function toHomeRelative(abs: string): string;
-/** Expand a leading `~`/`$HOME` against the LOCAL home. Other paths pass through unchanged. */
 export declare function expandLocalHome(p: string): string;
-/**
- * Make a `--cwd`/`--project` value portable to a remote host: an absolute path
- * under the LOCAL home (which the local shell already expanded from `~`) becomes
- * `~/…` so the *remote* shell re-roots it at its own home. Paths already anchored
- * at `~`/`$HOME` pass through; other absolute or relative paths are left as-is
- * (used verbatim on the host). Explicit `--remote-cwd` is NOT run through this —
- * it is a literal remote path by contract.
- */
 export declare function toRemotePortable(p: string): string;
-/**
- * If `p` is anchored at the home dir — a leading `~` or `$HOME` — return the
- * remainder (no leading slash), else null. Callers that want a local-home
- * absolute (`/Users/<me>/x`, from a shell-expanded `--cwd ~/x`) re-rooted at the
- * remote home normalize it to `~/x` first (`toRemotePortable`); explicit
- * `--remote-cwd` is left literal and so is never re-rooted here.
- *
- * The canonical home-anchor stripper — shared by `remoteCdPrefix`,
- * `deriveMirroredCwd`, and the interactive-login shell builder
- * (`devices/connect.ts`), so there is exactly one notion of "the part below the
- * home dir".
- */
 export declare function homeRemainder(p: string): string | null;
-/**
- * Derive the remote directory to mirror from the local cwd, for a host run the
- * caller gave no `--cwd`/`--remote-cwd` (and for an interactive `agents ssh`
- * login with no command).
- *
- * Without this a `--device` run — or an `agents ssh <device>` login — lands in the
- * remote `$HOME`, so an agent launched from a repo starts with no project
- * context and the user has to `cd` by hand. Only a cwd under the LOCAL home is
- * mirrored — that is the part with a meaningful remote analogue (`~/src/x`
- * re-roots onto the remote home). A path outside home returns undefined:
- * `/opt/thing` on this box says nothing about the target's filesystem, so the
- * run keeps the remote home.
- */
 export declare function deriveMirroredCwd(localCwd: string): string | undefined;
-/**
- * Build a `cd <dir> && ` prefix that resolves on the REMOTE host.
- *
- * A `~`/`$HOME`-anchored path must resolve against the REMOTE user's home, not
- * the local one (`/home/<me>` vs `/Users/<me>`). We emit an unquoted `"$HOME"`
- * for that segment — the remote login shell expands it — and shell-quote the
- * remainder. Any other path (absolute or relative) is quoted verbatim.
- *
- * `mirror` marks a directory the caller DERIVED from the local cwd rather than
- * one the user asked for (see `deriveMirroredCwd`). The same repo checked out at
- * the same home-relative path on both boxes is the common fleet layout, so
- * mirroring lands the remote agent in the project instead of `$HOME`. It is a
- * best-effort mirror by definition — the host may simply not have that checkout
- * — so a missing directory falls back to the remote home instead of failing the
- * run. An explicit `--cwd`/`--remote-cwd` is never mirrored: the user named that
- * directory, so a missing one must surface as a `cd` error.
- */
 export declare function remoteCdPrefix(remoteCwd?: string, opts?: {
     mirror?: boolean;
 }): string;
-/** The configured projects root (home-relative or absolute), or undefined when unset. */
 export declare function getProjectRoot(): string | undefined;
-/** Set (override) the cached projects root. Stored home-relative when under `$HOME`. */
 export declare function setProjectRoot(rootPath: string): string;
-/**
- * Infer the projects root from `cwd`: the directory ABOVE the git repo root
- * (cwd inside `~/src/github.com/user/repo` → `~/src/github.com/user`). Returns a
- * home-relative string when under `$HOME`; undefined when `cwd` is not in a repo.
- */
 export declare function inferProjectRoot(cwd: string): Promise<string | undefined>;
 interface ProjectRef {
     slug: string;
     worktree?: string;
 }
-/** Parse a `--project` value of the form `<slug>[@<worktree>]`. */
 export declare function parseProjectRef(ref: string): ProjectRef;
-/**
- * Join a root + `--project` ref into a working directory. Pure (no I/O) so the
- * slug/worktree layout is unit-testable. `forRemote` keeps the path
- * home-relative (`~/…`) for the remote shell to expand; otherwise it is expanded
- * against the local home into an absolute path.
- */
 export declare function buildProjectPath(root: string, ref: string, forRemote: boolean): string;
-/**
- * Resolve a `--project` ref to a working directory, inferring/caching the root.
- *
- * `forRemote: true` returns a home-relative path (`~/…`) so the REMOTE login
- * shell expands `~`/`$HOME` to its own home. `forRemote: false` returns an
- * absolute local path and verifies it exists (so a mistyped slug fails loudly).
- */
 export declare function resolveProjectRef(ref: string, opts: {
     forRemote: boolean;
     cwd?: string;
 }): Promise<string>;
-/**
- * Resolve a `--project` ref to the cwd an agent lands in PLUS the other
- * directories that project binds, so a spawn can grant them.
- *
- * `cwd` is exactly what `resolveProjectRef` returns — this never changes where
- * an agent starts. `extraDirs` is every other `repos[].path`, and is empty for
- * a convention-resolved project (no definition means no bound repos) and for a
- * definition that binds only its primary checkout.
- */
 export declare function resolveProjectDirs(ref: string, opts: {
     forRemote: boolean;
     cwd?: string;

package/dist/lib/project-root.js

@@ -1,16 +1,3 @@
-/**
- * Projects-root resolution for the `agents run --project <slug>` shorthand.
- *
- * Projects follow a predictable layout — `<root>/<repo>` (e.g.
- * `~/src/github.com/<user>/<repo>`), with git worktrees under
- * `<repo>/.agents/worktrees/<slug>`. The root is auto-inferred from the repo you
- * launch inside (the directory ABOVE the git root) and cached in `agents.yaml`
- * so later runs resolve a bare slug from anywhere. It is stored home-relative
- * (`~/…`) when it sits under `$HOME`, so the SAME value resolves on a remote
- * host whose home differs (`/home/<user>` vs `/Users/<user>`): a `--device` run
- * keeps the `~` and lets the remote login shell expand it (see `remoteCdPrefix`
- * in `hosts/dispatch.ts`), while a local run expands `~` against the local home.
- */
 import * as os from 'os';
 import * as path from 'path';
 import * as fs from 'fs';
@@ -20,7 +7,6 @@ import { toPosix } from './platform/index.js';
 import { loadProjectDef, projectDirsAbs, resolveDefinedProjectPath } from './projects.js';
 import { shellQuote } from './ssh-exec.js';
 const HOME = process.env.HOME ?? os.homedir();
-/** Rewrite an absolute path under the local home to a `~/`-relative string; pass others through. */
 export function toHomeRelative(abs) {
     const rel = path.relative(HOME, abs);
     if (rel === '')
@@ -29,7 +15,6 @@ export function toHomeRelative(abs) {
         return `~/${toPosix(rel)}`;
     return abs;
 }
-/** Expand a leading `~`/`$HOME` against the LOCAL home. Other paths pass through unchanged. */
 export function expandLocalHome(p) {
     if (p === '~' || p === '$HOME')
         return HOME;
@@ -39,14 +24,6 @@ export function expandLocalHome(p) {
         return path.join(HOME, p.slice(6));
     return p;
 }
-/**
- * Make a `--cwd`/`--project` value portable to a remote host: an absolute path
- * under the LOCAL home (which the local shell already expanded from `~`) becomes
- * `~/…` so the *remote* shell re-roots it at its own home. Paths already anchored
- * at `~`/`$HOME` pass through; other absolute or relative paths are left as-is
- * (used verbatim on the host). Explicit `--remote-cwd` is NOT run through this —
- * it is a literal remote path by contract.
- */
 export function toRemotePortable(p) {
     if (p.startsWith('~') || p.startsWith('$HOME'))
         return p;
@@ -54,18 +31,6 @@ export function toRemotePortable(p) {
         return toHomeRelative(p);
     return p;
 }
-/**
- * If `p` is anchored at the home dir — a leading `~` or `$HOME` — return the
- * remainder (no leading slash), else null. Callers that want a local-home
- * absolute (`/Users/<me>/x`, from a shell-expanded `--cwd ~/x`) re-rooted at the
- * remote home normalize it to `~/x` first (`toRemotePortable`); explicit
- * `--remote-cwd` is left literal and so is never re-rooted here.
- *
- * The canonical home-anchor stripper — shared by `remoteCdPrefix`,
- * `deriveMirroredCwd`, and the interactive-login shell builder
- * (`devices/connect.ts`), so there is exactly one notion of "the part below the
- * home dir".
- */
 export function homeRemainder(p) {
     if (p === '~' || p === '$HOME')
         return '';
@@ -75,40 +40,10 @@ export function homeRemainder(p) {
         return p.slice(6);
     return null;
 }
-/**
- * Derive the remote directory to mirror from the local cwd, for a host run the
- * caller gave no `--cwd`/`--remote-cwd` (and for an interactive `agents ssh`
- * login with no command).
- *
- * Without this a `--device` run — or an `agents ssh <device>` login — lands in the
- * remote `$HOME`, so an agent launched from a repo starts with no project
- * context and the user has to `cd` by hand. Only a cwd under the LOCAL home is
- * mirrored — that is the part with a meaningful remote analogue (`~/src/x`
- * re-roots onto the remote home). A path outside home returns undefined:
- * `/opt/thing` on this box says nothing about the target's filesystem, so the
- * run keeps the remote home.
- */
 export function deriveMirroredCwd(localCwd) {
     const portable = toRemotePortable(localCwd);
     return homeRemainder(portable) === null ? undefined : portable;
 }
-/**
- * Build a `cd <dir> && ` prefix that resolves on the REMOTE host.
- *
- * A `~`/`$HOME`-anchored path must resolve against the REMOTE user's home, not
- * the local one (`/home/<me>` vs `/Users/<me>`). We emit an unquoted `"$HOME"`
- * for that segment — the remote login shell expands it — and shell-quote the
- * remainder. Any other path (absolute or relative) is quoted verbatim.
- *
- * `mirror` marks a directory the caller DERIVED from the local cwd rather than
- * one the user asked for (see `deriveMirroredCwd`). The same repo checked out at
- * the same home-relative path on both boxes is the common fleet layout, so
- * mirroring lands the remote agent in the project instead of `$HOME`. It is a
- * best-effort mirror by definition — the host may simply not have that checkout
- * — so a missing directory falls back to the remote home instead of failing the
- * run. An explicit `--cwd`/`--remote-cwd` is never mirrored: the user named that
- * directory, so a missing one must surface as a `cd` error.
- */
 export function remoteCdPrefix(remoteCwd, opts = {}) {
     if (!remoteCwd)
         return '';
@@ -121,21 +56,14 @@ export function remoteCdPrefix(remoteCwd, opts = {}) {
     }
     return `cd ${shellQuote(remoteCwd)} && `;
 }
-/** The configured projects root (home-relative or absolute), or undefined when unset. */
 export function getProjectRoot() {
     return readMeta().projectRoot;
 }
-/** Set (override) the cached projects root. Stored home-relative when under `$HOME`. */
 export function setProjectRoot(rootPath) {
     const stored = toHomeRelative(path.resolve(expandLocalHome(rootPath)));
     updateMeta({ projectRoot: stored });
     return stored;
 }
-/**
- * Infer the projects root from `cwd`: the directory ABOVE the git repo root
- * (cwd inside `~/src/github.com/user/repo` → `~/src/github.com/user`). Returns a
- * home-relative string when under `$HOME`; undefined when `cwd` is not in a repo.
- */
 export async function inferProjectRoot(cwd) {
     try {
         const mainRoot = await getMainRepoRoot(cwd);
@@ -145,10 +73,6 @@ export async function inferProjectRoot(cwd) {
         return undefined;
     }
 }
-/**
- * Resolve the projects root, auto-inferring and caching on first use. Throws an
- * actionable error when it is neither configured nor inferrable from `cwd`.
- */
 async function ensureProjectRoot(cwd) {
     const existing = getProjectRoot();
     if (existing)
@@ -163,19 +87,12 @@ async function ensureProjectRoot(cwd) {
     process.stderr.write(`[project] cached projects root: ${inferred}\n`);
     return inferred;
 }
-/** Parse a `--project` value of the form `<slug>[@<worktree>]`. */
 export function parseProjectRef(ref) {
     const at = ref.indexOf('@');
     if (at === -1)
         return { slug: ref };
     return { slug: ref.slice(0, at), worktree: ref.slice(at + 1) || undefined };
 }
-/**
- * Join a root + `--project` ref into a working directory. Pure (no I/O) so the
- * slug/worktree layout is unit-testable. `forRemote` keeps the path
- * home-relative (`~/…`) for the remote shell to expand; otherwise it is expanded
- * against the local home into an absolute path.
- */
 export function buildProjectPath(root, ref, forRemote) {
     const { slug, worktree } = parseProjectRef(ref);
     if (!slug)
@@ -185,19 +102,10 @@ export function buildProjectPath(root, ref, forRemote) {
         rel += `/.agents/worktrees/${worktree}`;
     return forRemote ? rel : path.resolve(expandLocalHome(rel));
 }
-/**
- * Resolve a `--project` ref to a working directory, inferring/caching the root.
- *
- * `forRemote: true` returns a home-relative path (`~/…`) so the REMOTE login
- * shell expands `~`/`$HOME` to its own home. `forRemote: false` returns an
- * absolute local path and verifies it exists (so a mistyped slug fails loudly).
- */
 export async function resolveProjectRef(ref, opts) {
     const { slug, worktree } = parseProjectRef(ref);
     if (!slug)
         throw new Error(`Invalid --project value: "${ref}"`);
-    // Definition first: a named project in ~/.agents/projects/<slug>.yaml overrides
-    // the <root>/<slug> convention. Absent (or root-less) → fall through unchanged.
     const def = loadProjectDef(slug);
     if (def) {
         const fromDef = resolveDefinedProjectPath(def, worktree, opts.forRemote);
@@ -216,15 +124,6 @@ export async function resolveProjectRef(ref, opts) {
     }
     return resolved;
 }
-/**
- * Resolve a `--project` ref to the cwd an agent lands in PLUS the other
- * directories that project binds, so a spawn can grant them.
- *
- * `cwd` is exactly what `resolveProjectRef` returns — this never changes where
- * an agent starts. `extraDirs` is every other `repos[].path`, and is empty for
- * a convention-resolved project (no definition means no bound repos) and for a
- * definition that binds only its primary checkout.
- */
 export async function resolveProjectDirs(ref, opts) {
     const resolved = await resolveProjectRef(ref, opts);
     const { slug } = parseProjectRef(ref);

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

@@ -1,37 +1,5 @@
-/**
- * What a project's milestone dates prove about its schedule — and nothing more.
- *
- * The tempting version of this file computes "on track / at risk". It cannot be
- * written honestly against this data. Probed live against a real workspace:
- *
- *   health: null            projectUpdates: []
- *   startDate: null         targetDate: null
- *   scopeHistory: []        completedScopeHistory: []
- *
- * "Behind schedule" needs either start+target dates to interpolate an expected
- * progress line, or a history series to extrapolate a finish date. Both are
- * absent, so any on-track/at-risk chip would be invented — and a confident wrong
- * answer on a status card is worse than a blank one, because it is unfalsifiable
- * from the card itself.
- *
- * So every verdict here is arithmetic on a stored date or a count:
- *
- *   overdue        a milestone's targetDate has passed and it is unfinished
- *   due-soon       the next one lands within DUE_SOON_DAYS
- *   untracked      milestones exist but nothing is filed against any of them,
- *                  so their progress is not measurable
- *   scheduled      dated milestones ahead, none due soon, work is filed
- *   no-dates       milestones exist, none carries a date
- *   none           the project declares no milestones
- *
- * `declared` relays Linear's OWN health when a human has posted one. It is
- * passed through and attributed, never synthesized — if the user starts posting
- * project updates, their answer wins over anything derived here.
- */
 import type { LinearMilestone } from './linear-project-counts.js';
-/** How far ahead counts as "due soon" — one sprint's notice. */
 export declare const DUE_SOON_DAYS = 14;
-/** A verdict about the schedule, as a tagged union so `--json` stays stable. */
 type ProjectVerdict = {
     kind: 'declared';
     health: string;
@@ -56,19 +24,8 @@ type ProjectVerdict = {
 } | {
     kind: 'none';
 };
-/** Whole days from `nowMs` to a `YYYY-MM-DD` date, compared at LOCAL midnight. */
 export declare function daysUntil(targetDate: string, nowMs: number): number | undefined;
-/**
- * Decide what the dates prove. Precedence is time-sensitivity first:
- *
- *   declared > overdue > due-soon > untracked > no-dates > scheduled
- *
- * An overdue milestone outranks an approaching one, and both outrank the
- * observation that nothing is filed — a deadline moves, that observation does
- * not. `declared` overrides everything, because a human said it.
- */
 export declare function scheduleVerdict(milestones: LinearMilestone[], nowMs: number, declaredHealth?: string | null): ProjectVerdict;
-/** One line for the card. Returns undefined for `none` — an empty row says nothing. */
 export declare function formatVerdict(v: ProjectVerdict): {
     text: string;
     warn: boolean;

package/dist/lib/project-schedule.js

@@ -1,36 +1,4 @@
-/**
- * What a project's milestone dates prove about its schedule — and nothing more.
- *
- * The tempting version of this file computes "on track / at risk". It cannot be
- * written honestly against this data. Probed live against a real workspace:
- *
- *   health: null            projectUpdates: []
- *   startDate: null         targetDate: null
- *   scopeHistory: []        completedScopeHistory: []
- *
- * "Behind schedule" needs either start+target dates to interpolate an expected
- * progress line, or a history series to extrapolate a finish date. Both are
- * absent, so any on-track/at-risk chip would be invented — and a confident wrong
- * answer on a status card is worse than a blank one, because it is unfalsifiable
- * from the card itself.
- *
- * So every verdict here is arithmetic on a stored date or a count:
- *
- *   overdue        a milestone's targetDate has passed and it is unfinished
- *   due-soon       the next one lands within DUE_SOON_DAYS
- *   untracked      milestones exist but nothing is filed against any of them,
- *                  so their progress is not measurable
- *   scheduled      dated milestones ahead, none due soon, work is filed
- *   no-dates       milestones exist, none carries a date
- *   none           the project declares no milestones
- *
- * `declared` relays Linear's OWN health when a human has posted one. It is
- * passed through and attributed, never synthesized — if the user starts posting
- * project updates, their answer wins over anything derived here.
- */
-/** How far ahead counts as "due soon" — one sprint's notice. */
 export const DUE_SOON_DAYS = 14;
-/** Whole days from `nowMs` to a `YYYY-MM-DD` date, compared at LOCAL midnight. */
 export function daysUntil(targetDate, nowMs) {
     const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(targetDate.trim());
     if (!m)
@@ -43,15 +11,6 @@ export function daysUntil(targetDate, nowMs) {
     return Math.round((due.getTime() - today.getTime()) / 86_400_000);
 }
 const unfinished = (m) => m.total === 0 || m.done < m.total;
-/**
- * Decide what the dates prove. Precedence is time-sensitivity first:
- *
- *   declared > overdue > due-soon > untracked > no-dates > scheduled
- *
- * An overdue milestone outranks an approaching one, and both outrank the
- * observation that nothing is filed — a deadline moves, that observation does
- * not. `declared` overrides everything, because a human said it.
- */
 export function scheduleVerdict(milestones, nowMs, declaredHealth) {
     if (declaredHealth)
         return { kind: 'declared', health: declaredHealth };
@@ -65,28 +24,17 @@ export function scheduleVerdict(milestones, nowMs, declaredHealth) {
     const worst = dated[0];
     if (worst && worst.days < 0)
         return { kind: 'overdue', milestone: worst.m.name, days: -worst.days };
-    // A date bearing down is time-sensitive; "nothing is filed" is a standing
-    // condition that will still be true tomorrow. So an approaching deadline is
-    // reported even when the milestone has no issues against it — reversing these
-    // hid a milestone due in two days behind "3 milestones, no issues filed".
     if (worst && worst.days <= DUE_SOON_DAYS)
         return { kind: 'due-soon', milestone: worst.m.name, days: worst.days };
-    // Nothing is filed against ANY milestone, so no progress can be computed for
-    // them — the useful thing to say, and the actual state of a project whose
-    // milestones were created before its issues. Checked against the full list,
-    // not just the open ones: a COMPLETED milestone necessarily has issues, so a
-    // project with one cannot honestly be called untracked.
     if (milestones.every((m) => m.total === 0))
         return { kind: 'untracked', milestones: milestones.length };
     if (!worst)
         return { kind: 'no-dates', milestones: open.length };
     return { kind: 'scheduled', milestone: worst.m.name, days: worst.days };
 }
-/** One line for the card. Returns undefined for `none` — an empty row says nothing. */
 export function formatVerdict(v) {
     switch (v.kind) {
         case 'declared':
-            // Attributed, so nobody mistakes a human's call for a derived one.
             return { text: `per Linear: ${v.health}`, warn: v.health.toLowerCase() !== 'ontrack' };
         case 'overdue':
             return { text: `${v.milestone} overdue by ${v.days} day${v.days === 1 ? '' : 's'}`, warn: true };

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

@@ -1,176 +1,68 @@
-/**
- * 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 type { ActiveSession, ActiveStatus } from './session/active.js';
 import { type ProjectDef } from './projects.js';
-/** One live agent on a project — the WHO behind the byStatus count. */
 export interface ProjectMember {
-    /** Harness name (claude / codex / …), from the session's `kind`. */
     agent: string;
-    /** Lifecycle status (running / idle / …). */
     status: string;
-    /** Tracker ticket the session is tied to, when any. */
     ticket?: string;
-    /** Machine the session runs on (provenance host / fleet peer), when known. */
     host?: string;
 }
-/** One project's live session rollup. */
 export interface ProjectSessionRollup {
     name: string;
-    /** Total sessions whose cwd is inside this project. */
     agents: number;
-    /** Count per lifecycle status. */
     byStatus: Partial<Record<ActiveStatus, number>>;
-    /** Which agents are on the project (one per matched session). */
     members: ProjectMember[];
-    /** Summed checklist progress across this project's sessions. */
     plan: {
         done: number;
         total: number;
     };
-    /** Distinct open PRs held by this project's sessions. */
     openPrs: {
         url: string;
         number?: number;
     }[];
-    /** Distinct tickets worked or created by this project's sessions. */
     tickets: string[];
-    /** Sessions running inside a worktree. */
     worktrees: number;
 }
-/**
- * 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 declare function withDefaultMachine<T extends {
     machine?: string;
 }>(sessions: T[], defaultHost: string): T[];
 export declare function rollupSessionsByProject(defs: ProjectDef[], sessions: ActiveSession[]): Map<string, ProjectSessionRollup>;
-/**
- * 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 declare function isDeadStatus(status: string): boolean;
-/** Live vs finished sessions on a project. */
 interface LiveDeadSplit {
     live: number;
     dead: number;
-    /** Dead broken out by status, for the card's parenthetical. */
     deadByStatus: Array<{
         status: string;
         n: number;
     }>;
 }
-/**
- * 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 declare function liveDeadSplit(byStatus: Partial<Record<ActiveStatus, number>>): LiveDeadSplit;
-/**
- * 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 declare function formatDeadSummary(split: LiveDeadSplit): string;
-/** Sort members for the card: running first, then idle, then the rest; agent name asc within a state. */
 export declare function sortProjectMembers(members: ProjectMember[]): ProjectMember[];
-/** Cap for the members line before it collapses to `+N more`. */
 export declare const MEMBERS_LINE_LIMIT = 6;
-/**
- * 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 declare function formatProjectMembers(members: ProjectMember[], limit?: number): string;
-/**
- * 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 declare function formatProjectMembersByHost(members: ProjectMember[], opts?: {
     cellLimit?: number;
     hostLimit?: number;
 }): string[];
-/** A card-level warning collected for the footer. */
 export type ProjectWarningSeverity = 'critical' | 'continue';
 export interface ProjectWarning {
     severity: ProjectWarningSeverity;
-    /** One human line. */
     text: string;
-    /** Optional fix or next step. */
     remediation?: string;
 }
-/**
- * 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 declare function warningEmoji(severity: ProjectWarningSeverity): string;
-/**
- * Format one or more warning lines for the card footer. Pure (chalk only).
- * Returns empty when there is nothing to say.
- */
 export declare function formatProjectWarnings(warnings: ProjectWarning[]): string[];
-/** Harvested signals not on the session list: repo-global merged PRs + releases, local artifacts, in a time window. */
 export interface ProjectRemoteSignals {
     windowDays: number;
-    /** PRs merged into the primary repo within the window (via `gh`). */
     mergedPrs: number;
-    /**
-     * True when the `gh` fetch cap cut the count short — `mergedPrs` is then a
-     * LOWER bound (rendered `100+`), never presented as the complete count. Same
-     * contract `LinearProjectCounts.truncated` keeps for the Linear line.
-     */
     mergedPrsTruncated?: boolean;
-    /** Artifacts agents produced within the window (activity.created milestones). */
     artifacts: number;
-    /** Basename of the most recent artifact, when any. */
     lastArtifact?: string;
-    /** Latest release of the PRIMARY repo (via `gh release list`), when any. */
     latestRelease?: {
         tag: string;
         publishedAt: string;
     };
 }
-/**
- * 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 declare function enrichProjectSignals(def: ProjectDef, windowDays: number, nowMs: number, opts?: {
     activityRoot?: string;
     skipRemote?: boolean;