@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/commands/projects.js

@@ -1,12 +1,3 @@
-/**
- * `agents projects` — named, multi-repo projects and the progress
- * rollup. Definitions live in `~/.agents/projects/<name>.yaml` (see
- * `lib/projects.ts`); this registers the command tree over them.
- *
- * The headline is `status`: instead of the vague per-agent activity line, it
- * rolls every session up by project (matched on cwd) into one card — agents by
- * lifecycle state, plan completion, open PRs, and tickets in flight.
- */
 import chalk from 'chalk';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -30,29 +21,24 @@ import { checkRepoSlug } from '../lib/project-doctor.js';
 import { formatFocusAreas, readFocusAreas } from '../lib/project-focus.js';
 import { formatVerdict, scheduleVerdict } from '../lib/project-schedule.js';
 import { buildLinearImportCandidates, validateImportOpts, } from '../lib/project-import.js';
-import { buildProjectPrs, mergeProjectPr, resolveTargetSlugs, MERGE_METHODS } from '../lib/github/project-prs.js';
+import { approveProjectPr, buildProjectPrs, commentOnProjectPr, markProjectPrReady, mergeProjectPr, resolveTargetSlugs, setProjectPrAutoMerge, MERGE_METHODS, MERGED_WINDOW_DAYS, } from '../lib/github/project-prs.js';
 import { ghExec } from '../lib/github/pr-mergeable.js';
-/** Recursion guard: a peer answering a probe fan-out never re-fans-out itself. */
+import { readCiFailure, rerunFailedJobs } from '../lib/github/ci-failure.js';
+import { registerProjectTodoCommands } from './projects-todo.js';
+function ciMark(state) {
+    if (state === 'SUCCESS')
+        return chalk.green('✓');
+    if (state === 'FAILURE' || state === 'ERROR')
+        return chalk.red('✗');
+    if (state === 'PENDING' || state === 'EXPECTED')
+        return chalk.yellow('●');
+    return ' ';
+}
 const PROJECTS_NO_FANOUT_ENV = 'AGENTS_PROJECTS_LOCAL';
-/** Max peers named in the skipped note before the rest collapse to `+N`. */
 const SKIPPED_NAME_LIMIT = 4;
-/**
- * A path-shaped `agents projects view` argument — `.`, `..`, a `~`-prefixed
- * value, or anything containing a path separator — means "auto-detect the
- * project for this DIRECTORY", not "a project named literally this". A bare
- * token (no separators) stays a project name, exactly as before.
- */
 export function looksLikePath(token) {
     return token === '.' || token === '..' || token.startsWith('~') || token.includes('/');
 }
-/**
- * Best-effort cwd->project detection for `agents projects view <path>`. Delegates
- * to the shared {@link projectNameForCwd} (def-root containment, longest wins),
- * then reads the matched definition's Linear binding and root so ONE call yields
- * the name AND the Linear projectId. Fail-open: an all-null shape when nothing
- * contains the path — never throws, so a scripted caller stays unscoped rather
- * than crashing. This subsumes the removed `agents projects for-cwd`.
- */
 export function detectProjectForPath(cwd, defs) {
     const name = projectNameForCwd(cwd, defs);
     const def = name ? defs.find((d) => d.name === name) : undefined;
@@ -65,13 +51,6 @@ export function detectProjectForPath(cwd, defs) {
         root: def?.root ?? null,
     };
 }
-/**
- * One compact trailing note for peers that didn't answer the `--fleet`
- * fan-out — unreachable, running an agents-cli too old to carry `projects
- * probe`, or too slow to finish inside the 12s SSH budget. Mirrors
- * `formatUnreachableNote` (activity) with the probe-specific reasons; empty
- * string when everything answered.
- */
 export function formatFleetSkippedNote(skipped) {
     if (skipped.length === 0)
         return '';
@@ -81,14 +60,6 @@ export function formatFleetSkippedNote(skipped) {
     const noun = skipped.length === 1 ? 'device' : 'devices';
     return chalk.gray(`  · ${skipped.length} ${noun} didn't answer (unreachable, older agents-cli, or timed out): ${list}\n`);
 }
-/**
- * One compact trailing note for peers that DID answer a fan-out but whose
- * payload failed verification — a wrong machine id, a fingerprint that doesn't
- * match the targets we sent, or a malformed row. Deliberately separate from
- * {@link formatFleetSkippedNote}: silence means a peer never ran, while this
- * means it ran and we cannot trust what it reports, which is the worse state.
- * Empty string when every answer verified.
- */
 export function formatFleetUnverifiedNote(unverified) {
     if (unverified.length === 0)
         return '';
@@ -98,14 +69,12 @@ export function formatFleetUnverifiedNote(unverified) {
     const noun = unverified.length === 1 ? 'device' : 'devices';
     return chalk.red(`  · ${unverified.length} ${noun} answered with a result that could not be verified: ${list}\n`);
 }
-/** `path:purpose` → a context anchor. Purpose may contain colons. */
 function parseContextFlag(raw) {
     const i = raw.indexOf(':');
     if (i === -1)
         return { path: raw.trim(), purpose: '' };
     return { path: raw.slice(0, i).trim(), purpose: raw.slice(i + 1).trim() };
 }
-/** `objective:measure` → a goal. The measure is optional; the objective may contain colons only after the first is claimed. */
 function parseGoalFlag(raw) {
     const i = raw.indexOf(':');
     if (i === -1)
@@ -116,14 +85,6 @@ function parseGoalFlag(raw) {
         goal.measure = measure;
     return goal;
 }
-/**
- * Best-effort `owner/repo` from a repo's origin remote.
- *
- * `stderr: 'ignore'` is load-bearing, not tidiness. A checkout with no origin
- * makes git print `error: No such remote 'origin'` on ITS stderr, which is the
- * terminal's — the catch below never sees it. Absence of a remote is an
- * expected answer here (`undefined`), not something to report.
- */
 export function originSlug(cwd) {
     try {
         const url = execFileSync('git', ['remote', 'get-url', 'origin'], {
@@ -137,18 +98,6 @@ export function originSlug(cwd) {
         return undefined;
     }
 }
-/**
- * Turn a `--dir` / `--add-dir` value into a `repos[]` row.
- *
- * The slug comes from the DIRECTORY'S OWN origin remote, never from its path:
- * a checkout at `~/src/github.com/muqsitnawaz/agents-cli` whose origin is
- * `phnx-labs/agents-cli` must record the remote it actually pushes to. Pass
- * `slugOverride` for a directory with no origin (a vendored tree, a fresh
- * `git init`).
- *
- * The stored `path` is left for `writeProjectDef` to normalize home-relative,
- * so the same definition re-roots on every machine.
- */
 export function projectRepoFromDir(dir, slugOverride) {
     const abs = path.resolve(expandLocalHome(dir));
     if (!fs.existsSync(abs))
@@ -165,12 +114,6 @@ export function projectRepoFromDir(dir, slugOverride) {
     }
     return { ok: true, repo: { slug, path: toHomeRelative(abs) } };
 }
-/**
- * List the workspace's Linear projects and plan their import, binding each to a
- * local checkout under the configured projects root when the names match
- * exactly. A missing / logged-out `linear` CLI is loud (this is an explicit user
- * command), and nothing is written before the whole plan is built.
- */
 function runLinearImport(existing, opts) {
     let list;
     try {
@@ -180,8 +123,6 @@ function runLinearImport(existing, opts) {
         console.error(chalk.red(e instanceof Error ? e.message : String(e)));
         process.exit(1);
     }
-    // No projects root configured (or unreadable) → no local matching; every def
-    // still imports, carrying its Linear link and nothing it can't prove.
     const rootAbs = getProjectRoot() ? expandLocalHome(getProjectRoot()) : undefined;
     let localDirs = [];
     if (rootAbs) {
@@ -201,14 +142,7 @@ function runLinearImport(existing, opts) {
         resolveOrigin: (dir) => (rootAbs ? originSlug(path.join(rootAbs, dir)) : undefined),
     }, opts);
 }
-/** Longest path a `list` row shows before it truncates. */
 const LIST_PATH_MAX = 48;
-/**
- * Column widths for `projects list`, sized to the rows actually being printed.
- * Fixed padding was the bug: home-relative roots run past 50 characters, so a
- * hardcoded 32 pushed the repo column off its gridline on every long path.
- * Paths longer than {@link LIST_PATH_MAX} truncate rather than widen the table.
- */
 export function computeProjectListWidths(rows) {
     const widest = (pick, cap) => Math.min(cap, rows.reduce((w, r) => Math.max(w, pick(r).length), 0));
     return {
@@ -217,13 +151,6 @@ export function computeProjectListWidths(rows) {
         repo: widest((r) => r.repo, 64),
     };
 }
-/**
- * A milestone's target date as a person would say it — "due tomorrow",
- * "overdue by 3 days", "due Aug 21" — never a raw `2026-08-21` or a duration in
- * hours. Linear stores a calendar date with no timezone, so both sides are
- * compared at LOCAL midnight; parsing `YYYY-MM-DD` with `new Date(str)` would
- * read it as UTC and shift the answer by a day for anyone west of Greenwich.
- */
 export function formatMilestoneDue(targetDate, nowMs) {
     const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(targetDate.trim());
     if (!m)
@@ -252,25 +179,10 @@ export function formatMilestoneDue(targetDate, nowMs) {
     });
     return `due ${label}`;
 }
-/**
- * The milestone block. `status` prints one line — the next checkpoint — because
- * a roll-up across projects has to stay scannable. `view` prints every declared
- * milestone, because "how many are there and when are they due" is the shape of
- * the plan and the reason to open one project.
- *
- * Pure (chalk only) so the layout is testable without a Linear account.
- */
 export function formatMilestoneLines(milestones, next, nowMs, limit) {
     if (milestones.length === 0) {
-        // `next` without a list only happens on a cached answer written before the
-        // list existed; render what we have rather than dropping the row.
         return next ? [`  ${chalk.dim('next')}     ${formatNextMilestone(next, nowMs)}`] : [];
     }
-    // The next milestone leads, always. Linear can flag a LATER-dated milestone
-    // as next, and `milestones` is date-ordered — so slicing the front would show
-    // an earlier one and hide the actual next behind "+N more", which is the one
-    // thing this row exists to say. Identity is name+targetDate: two milestones
-    // can share a name, and matching on name alone labelled the wrong row.
     const key = (m) => `${m.name}${m.targetDate ?? ''}`;
     const lead = next ? milestones.filter((m) => key(m) === key(next)).slice(0, 1) : [];
     const others = next ? milestones.filter((m) => key(m) !== key(next)) : milestones;
@@ -286,11 +198,8 @@ export function formatMilestoneLines(milestones, next, nowMs, limit) {
     }
     return out;
 }
-/** The `next` card line: what this project is due to hit, and how far along it is. */
 export function formatNextMilestone(ms, nowMs) {
     const parts = [chalk.bold(ms.name)];
-    // A milestone with nothing filed under it yet has no progress to report —
-    // `0/0` is noise, not information.
     if (ms.total > 0)
         parts.push(`${ms.done}/${ms.total}`);
     const due = ms.targetDate ? formatMilestoneDue(ms.targetDate, nowMs) : undefined;
@@ -309,36 +218,16 @@ function statusBar(r) {
     push(r.byStatus.input_required, 'need-input', chalk.yellow);
     push(r.byStatus.queued, 'queued', chalk.gray);
     const shown = (r.byStatus.running ?? 0) + (r.byStatus.idle ?? 0) + (r.byStatus.input_required ?? 0) + (r.byStatus.queued ?? 0);
-    // The remainder is the LIVE sessions in a state without its own chip
-    // (orphaned, unknown). Dead ones are on their own row now, so counting them
-    // here made the line disagree with the headline — `19 live` beside
-    // `+24 other`, which invites the reader to trust neither.
     const live = liveDeadSplit(r.byStatus).live;
     if (live > shown)
         parts.push(chalk.gray(`+${live - shown} other`));
     return parts.join(' · ') || chalk.gray('no live agents');
 }
-/**
- * Gather the live/remote/Linear/focus signals for the projects about to be
- * rendered. `status` and `view` share this deliberately: `view` used to build
- * its own thinner picture, so the command you open to learn everything about
- * ONE project showed strictly less than the roll-up across all of them — no
- * agents, no ships, no focus, no schedule verdict. One gatherer means a signal
- * added for either surface appears on both.
- *
- * Only the shown projects are enriched. `skipRemote` still reads the local
- * artifact log and git focus, and skips just the network calls (`gh`, Linear).
- */
 async function enrichProjectsForRender(defs, all, opts) {
-    // Local getActiveSessions() leaves `machine` unset (the sessions renderer
-    // falls back to this box). Host-grouped agents need an explicit stamp so
-    // under `--fleet` this box does not render as `@local` next to peers that
-    // carry real device ids.
     const local = withDefaultMachine(await getActiveSessions(), machineId());
     const roll = rollupSessionsByProject(all, [...local, ...(opts.extraSessions ?? [])]);
     const remote = new Map();
     const linear = new Map();
-    // Local git, no API, no rate limit — measured 0.23s over a 897-commit week.
     const focus = new Map();
     await Promise.all(defs.map(async (d) => {
         const [sig, counts] = await Promise.all([
@@ -355,34 +244,15 @@ async function enrichProjectsForRender(defs, all, opts) {
     }));
     return { roll, remote, linear, focus };
 }
-function renderCard(def, r, remote, fleet, linear, nowMs = Date.now(), 
-/** How many milestones to print. `status` shows the next one; `view` shows all. */
-milestoneLimit = 1, 
-/** Directories the window's work landed in, from local git. */
-focus = [], 
-/** `view` mode: the caller prints the stored definition in full afterwards. */
-detail = false, 
-/**
- * Workspace probe rows used only for the warnings footer. May be the full
- * `--fleet` set or a local-only probe so drift is never silent by default.
- */
-warnWorkspaces = []) {
-    // The headline counts LIVE agents. It used to be every matched session, which
-    // read `39 agents` on a project where 19 had crashed. `planPct` used to sit
-    // here too and is gone: it summed each session's latest checklist snapshot,
-    // so one agent opening a fresh 40-item plan rendered the whole project `0%`.
+function renderCard(def, r, remote, fleet, linear, nowMs = Date.now(), milestoneLimit = 1, focus = [], detail = false, warnWorkspaces = []) {
     const split = r ? liveDeadSplit(r.byStatus) : { live: 0, dead: 0, deadByStatus: [] };
     console.log(`${chalk.bold(def.name)}  ${chalk.dim('·')}  ${chalk.bold(`${split.live} live`)}`);
     if (def.description)
         console.log(`  ${chalk.dim(def.description)}`);
     console.log(`  ${chalk.dim('live')}     ${r ? statusBar(r) : chalk.gray('no live agents')}`);
     if (split.dead > 0) {
-        // Wreckage is worth a number of its own — 19 crashed sessions is a thing to
-        // go fix, not a throughput signal to fold into the headline.
         console.log(`  ${chalk.dim('dead')}     ${formatDeadSummary(split)}`);
     }
-    // Live only, grouped by host when machine stamps exist so "who is on which
-    // box" is visible. Flat collapse hid that when harness×status matched across hosts.
     const liveMembers = r?.members.filter((m) => !isDeadStatus(m.status)) ?? [];
     if (liveMembers.length) {
         const agentLines = formatProjectMembersByHost(liveMembers);
@@ -409,8 +279,6 @@ warnWorkspaces = []) {
     for (const line of formatMilestoneLines(linear?.milestones ?? [], linear?.nextMilestone, nowMs, milestoneLimit)) {
         console.log(line);
     }
-    // Informational schedule only. Warn-level verdicts land in the footer so the
-    // bottom of the card is the one place you look for "what needs attention".
     const verdict = linear?.milestones?.length ? formatVerdict(scheduleVerdict(linear.milestones, nowMs)) : undefined;
     if (verdict && !verdict.warn) {
         console.log(`  ${chalk.dim('schedule')} ${verdict.text}`);
@@ -428,9 +296,6 @@ warnWorkspaces = []) {
             console.log(`  ${chalk.dim('fleet')}    ${chalk.gray('no workspace paths (set root or repos[].path)')}`);
         }
         else {
-            // A compact health line first (scan without reading every host), then the
-            // full per-host table under it. The grouped footer carries the actionable
-            // subset; this line + the table carry the whole picture.
             [formatFleetSummary(fleet), ...table].forEach((line, i) => {
                 console.log(`  ${chalk.dim((i === 0 ? 'fleet' : '').padEnd(5))}    ${line}`);
             });
@@ -443,8 +308,6 @@ warnWorkspaces = []) {
     const repos = [def.repo, ...(def.repos ?? []).map((x) => x.slug)].filter(Boolean);
     if (repos.length)
         console.log(`  ${chalk.dim('repos')}    ${[...new Set(repos)].join(' · ')}`);
-    // Warnings footer — critical (🔴) then continue (⚠️). Sources: repo slug
-    // mismatch, workspace drift/dirty/missing, schedule that cannot measure.
     const warnings = [];
     const mismatch = def.root ? checkRepoSlug(def, originSlug(expandLocalHome(def.root))) : undefined;
     if (mismatch) {
@@ -466,8 +329,6 @@ warnWorkspaces = []) {
     }
     for (const line of formatProjectWarnings(warnings))
         console.log(line);
-    // `view` prints these in full (path + purpose, label + URL) right below, so
-    // the compact one-line summaries would just say the same thing twice.
     if (!detail && def.goals?.length) {
         console.log(`  ${chalk.dim('goal')}     ${def.goals.map((g) => g.objective).join(' · ')}`);
     }
@@ -480,10 +341,6 @@ warnWorkspaces = []) {
     if (!detail)
         console.log('');
 }
-/**
- * Merge `--device a b` (variadic) and `--devices a,b,c` (comma list) into one
- * deduped device filter; undefined when neither was given (= whole fleet).
- */
 function resolveDeviceFilter(device, devices) {
     const merged = [
         ...(device ?? []),
@@ -491,7 +348,6 @@ function resolveDeviceFilter(device, devices) {
     ];
     return merged.length ? [...new Set(merged)] : undefined;
 }
-/** Print the YAML-side fields that sit under the shared card in `view` mode. */
 function printProjectDefinition(def, name) {
     console.log();
     if (def.root)
@@ -518,6 +374,57 @@ function printProjectDefinition(def, name) {
         console.log(`  ${chalk.dim('doc')}      ${d}`);
     console.log(chalk.gray(`  ${projectDefPath(name)}`));
 }
+function prFail(message) {
+    console.error(chalk.red(message));
+    process.exit(1);
+}
+function prProjectOrExit(name) {
+    return loadProjectDef(name) ?? prFail(`No project named "${name}". List them: agents projects list`);
+}
+function prNumberOrExit(raw) {
+    const t = raw.trim();
+    const number = /^\d+$/.test(t) ? Number.parseInt(t, 10) : NaN;
+    if (!Number.isSafeInteger(number) || number <= 0)
+        prFail(`--number expects a positive integer, got "${raw}".`);
+    return number;
+}
+function prShaOrExit(raw) {
+    const sha = raw.trim();
+    if (!/^[0-9a-f]{7,40}$/i.test(sha))
+        prFail(`--sha expects a commit SHA, got "${raw}".`);
+    return sha;
+}
+function prCommentBodyOrExit(body, bodyFile) {
+    if ((body === undefined) === (bodyFile === undefined))
+        prFail('Pass exactly one of --body <text> or --body-file <path|->.');
+    let text = body;
+    if (bodyFile !== undefined) {
+        try {
+            text = fs.readFileSync(bodyFile === '-' ? 0 : bodyFile, 'utf-8');
+        }
+        catch (e) {
+            prFail(`Could not read --body-file ${bodyFile}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    if (!text || !text.trim())
+        prFail('The comment is empty.');
+    return text.trimEnd();
+}
+function prMethodOrExit(raw) {
+    if (raw !== undefined && !MERGE_METHODS.includes(raw)) {
+        prFail(`--method expects one of ${MERGE_METHODS.join(', ')}, got "${raw}".`);
+    }
+    return raw;
+}
+async function prRepoOrExit(def, repo) {
+    try {
+        const [resolved] = await resolveTargetSlugs(def, repo, ghExec);
+        return resolved;
+    }
+    catch (e) {
+        return prFail(e instanceof Error ? e.message : String(e));
+    }
+}
 export function registerProjectsCommands(program) {
     const projects = program
         .command('projects')
@@ -553,7 +460,6 @@ export function registerProjectsCommands(program) {
       an --add-dir grant (Claude, Codex, Cursor, Kimi, Grok consume it; others ignore).
     `,
     });
-    // ---- list ----
     projects
         .command('list')
         .description('List defined projects (definitions only by default; no session scan).')
@@ -561,9 +467,6 @@ export function registerProjectsCommands(program) {
         .option('--with-agents', 'Include local active agent counts (opt-in; never SSH)')
         .action(async (opts) => {
         const defs = listProjectDefs();
-        // Definitions-only by default: zero session scan / SSH. --with-agents is
-        // an explicit opt-in for local active counts only (getActiveSessions is
-        // local; it never fans out).
         const roll = opts.withAgents
             ? rollupSessionsByProject(defs, await getActiveSessions())
             : undefined;
@@ -589,7 +492,6 @@ export function registerProjectsCommands(program) {
             console.log(`  ${chalk.bold(row.name.padEnd(w.name))} ${chalk.dim(row.path.padEnd(w.path))} ${chalk.cyan(row.repo.padEnd(w.repo))}${agentsSuffix}`);
         }
     });
-    // ---- add ----
     projects
         .command('add <name>')
         .description('Define a project. Infers root and repo from the current git repo when not given.')
@@ -656,8 +558,6 @@ export function registerProjectsCommands(program) {
     async function runProjectCard(name, opts, mode) {
         const detail = mode === 'view';
         const all = listProjectDefs();
-        // Named lookup goes through the strict single-def loader so a broken
-        // <name>.yaml surfaces its validation error instead of "No project named".
         const defs = name ? [loadProjectDef(name)].filter((d) => d !== undefined) : all;
         if (name && !defs.length) {
             console.error(chalk.red(detail
@@ -674,11 +574,6 @@ export function registerProjectsCommands(program) {
         }
         const windowDays = Math.max(1, Number.parseInt(opts.window ?? '7', 10) || 7);
         const nowMs = Date.now();
-        // Fleet is the default: probe each shown def's workspace paths (root +
-        // repos[].path) locally AND on every peer in one parallel SSH round, and
-        // widen the live-session rollup to the fleet via the sessions fan-out.
-        // `--device`/`--devices` scopes the remote fan-out to a subset; with no
-        // filter every registered device is dialled.
         const fleetTargets = [...new Set(defs.flatMap(workspaceTargetsForDef))];
         let fleetWs = [];
         let fleetSkipped = [];
@@ -708,7 +603,6 @@ export function registerProjectsCommands(program) {
             skipRemote: opts.remote === false,
             extraSessions: fleetSessions,
         });
-        /** This def's slice of the fleet probe, in its own target order. */
         const fleetFor = (d) => {
             const targets = new Set(workspaceTargetsForDef(d));
             return fleetWs.filter((s) => targets.has(s.path));
@@ -716,9 +610,6 @@ export function registerProjectsCommands(program) {
         if (opts.json) {
             if (fleetSkipped.length > 0)
                 process.stderr.write(formatFleetSkippedNote(fleetSkipped));
-            // `view` used to nest the def fields at the top level and omit plan /
-            // worktrees / windowDays; keep one machine shape for both verbs so a
-            // consumer that switches `status`↔`view` does not re-learn the schema.
             console.log(JSON.stringify(defs.map((d) => {
                 const r = roll.get(d.name);
                 const rem = remote.get(d.name);
@@ -748,11 +639,7 @@ export function registerProjectsCommands(program) {
             }), null, 2));
             return;
         }
-        // Compact rollup shows the next milestone; `view` shows every declared one.
         const milestoneLimit = detail ? Number.POSITIVE_INFINITY : 1;
-        // Stamp the fleet-wide rollup with when it was taken, so a scrollback isn't
-        // mistaken for a live snapshot. A single named `view` skips it (one card, and
-        // its own detail makes the freshness obvious).
         if (!detail) {
             const t = new Date(nowMs);
             const hhmm = `${String(t.getHours()).padStart(2, '0')}:${String(t.getMinutes()).padStart(2, '0')}`;
@@ -760,10 +647,7 @@ export function registerProjectsCommands(program) {
             console.log('');
         }
         for (const d of defs) {
-            renderCard(d, roll.get(d.name), remote.get(d.name), fleetFor(d), linear.get(d.name), nowMs, milestoneLimit, focus.get(d.name) ?? [], detail, 
-            // Always feed workspace rows into the warnings footer so behind/dirty
-            // is never silent.
-            fleetFor(d));
+            renderCard(d, roll.get(d.name), remote.get(d.name), fleetFor(d), linear.get(d.name), nowMs, milestoneLimit, focus.get(d.name) ?? [], detail, fleetFor(d));
             if (detail)
                 printProjectDefinition(d, d.name);
         }
@@ -781,12 +665,6 @@ export function registerProjectsCommands(program) {
         .option('--device <name...>', 'Scope fleet status to one or more devices (repeatable)')
         .option('--devices <names>', 'Scope fleet status to a comma-separated list of devices')
         .action(async (name, rawOpts) => {
-        // Path mode: an explicit --path, or a path-shaped positional (., .., a
-        // ~-prefixed value, or a /-containing value) means "auto-detect the
-        // project for this DIRECTORY" rather than "a project named literally
-        // this". projectNameForCwd resolves the dir (expandLocalHome +
-        // path.resolve), so `.`, `~/…`, and relative paths all normalize. This
-        // subsumes the removed `agents projects for-cwd`.
         let detectDir;
         if (typeof rawOpts.path === 'string')
             detectDir = rawOpts.path;
@@ -804,13 +682,8 @@ export function registerProjectsCommands(program) {
                 console.log(chalk.gray(`No defined project contains ${detectDir}`));
                 return;
             }
-            // Non-JSON: fall through and render the full card for the detected project.
             name = detection.name;
         }
-        // Named invocation = `view` depth (all milestones + definition). Unnamed
-        // stays the scannable multi-project rollup. `view` is a commander alias
-        // of this same command, so there is only one implementation.
-        // Fleet is dialled by default; --device/--devices narrows it to a subset.
         const opts = {
             json: rawOpts.json,
             window: rawOpts.window,
@@ -820,12 +693,9 @@ export function registerProjectsCommands(program) {
         const mode = name ? 'view' : 'status';
         await runProjectCard(name, opts, mode);
     });
-    // ---- prs ----
-    // `list` is the default so `prs <name>` keeps its shape; a bare parent with
-    // no options of its own is what lets `prs merge` own --repo/--number/--json.
     const prsCmd = projects
         .command('prs')
-        .description('A project\'s open pull requests: list them (default), or merge one.');
+        .description('A project\'s open pull requests: list them (default), act on one (ready, review, comment, merge), or read and re-run failed CI (failure, rerun).');
     const prsListCmd = prsCmd
         .command('list <name>', { isDefault: true })
         .description('Every OPEN pull request across a project\'s attached repos (drafts included, no author filter), scoped to this project\'s paths in a shared repo.')
@@ -844,8 +714,6 @@ export function registerProjectsCommands(program) {
                 console.error(chalk.red('--number names one PR in one repo; pass --repo <owner/repo> with it.'));
                 process.exit(1);
             }
-            // Require the WHOLE token to be digits — Number.parseInt would accept
-            // "12junk" / "12.9" as 12 and silently query the wrong PR.
             const raw = opts.number.trim();
             number = /^\d+$/.test(raw) ? Number.parseInt(raw, 10) : NaN;
             if (!Number.isSafeInteger(number) || number <= 0) {
@@ -858,17 +726,10 @@ export function registerProjectsCommands(program) {
             envelope = await buildProjectPrs(def, { repo: opts.repo, number }, undefined, listProjectDefs());
         }
         catch (e) {
-            // A restriction error (repo not attached) is a hard, up-front failure —
-            // distinct from a per-repo fetch failure, which rides in the envelope.
             console.error(chalk.red(e instanceof Error ? e.message : String(e)));
             process.exit(1);
         }
         if (opts.json) {
-            // A machine caller reads the envelope from stdout regardless of exit
-            // code: `partial` + per-repo `error` ARE the failure signal, and the
-            // successful repositories ride alongside them. So --json always exits 0
-            // (the envelope is authoritative); a native consumer must not discard
-            // stdout on a non-zero exit. Only the human path below exits non-zero.
             console.log(JSON.stringify(envelope, null, 2));
             return;
         }
@@ -878,18 +739,35 @@ export function registerProjectsCommands(program) {
                     console.log(`${chalk.bold(r.slug)}  ${chalk.red(`— fetch failed: ${r.error}`)}`);
                     continue;
                 }
-                console.log(`${chalk.bold(r.slug)}  ${chalk.dim(`${r.pullRequests.length} open`)}`);
+                const branch = r.defaultBranch ? `  ${r.defaultBranch.name} ${ciMark(r.defaultBranch.ciState)}` : '';
+                console.log(`${chalk.bold(r.slug)}  ${chalk.dim(`${r.pullRequests.length} open`)}${branch}`);
                 for (const pr of r.pullRequests) {
                     const draft = pr.isDraft ? chalk.gray(' [draft]') : '';
                     const wide = pr.scope === 'repo-wide' ? chalk.gray(' [repo-wide]') : '';
-                    console.log(`  #${pr.number}${draft}${wide}  ${pr.title}  ${chalk.gray(`@${pr.author.login} · ${pr.headRefName}`)}`);
+                    console.log(`  ${ciMark(pr.ciState)} #${pr.number}${draft}${wide}  ${pr.title}  ${chalk.gray(`@${pr.author.login} · ${pr.headRefName}`)}`);
+                }
+                if (r.release) {
+                    const npm = r.release.npm?.version ? ` · npm ${r.release.npm.version}` : '';
+                    const since = `${r.release.mergesSince}${r.release.mergesSinceComplete ? '' : '+'}`;
+                    console.log(chalk.dim(`  ${r.release.latestTag} tagged ${r.release.latestTagAt.slice(0, 10)}${npm} · ${since} merged since`));
+                }
+                if (r.releaseError)
+                    console.log(chalk.yellow(`  Latest release could not be read: ${r.releaseError}`));
+                if (r.ciError)
+                    console.log(chalk.yellow(`  CI and merged PRs are incomplete: ${r.ciError}`));
+                if (r.truncated)
+                    console.log(chalk.yellow('  Merged list may be missing PRs: too many closed PRs were updated this week to read them all.'));
+                if (r.recentlyMerged.length > 0) {
+                    console.log(chalk.dim(`  merged in the last ${MERGED_WINDOW_DAYS} days:`));
+                    for (const pr of r.recentlyMerged) {
+                        console.log(`  ${ciMark(pr.ciState)} #${pr.number}  ${pr.title}  ${chalk.gray(`@${pr.author.login} · ${pr.mergedAt.slice(0, 10)}`)}`);
+                    }
                 }
             }
             if (envelope.partial) {
                 console.log(chalk.yellow('\nSome repositories could not be fetched — the list above is incomplete.'));
             }
         }
-        // A partial result (any repo fetch failed) is not a clean success.
         if (envelope.partial)
             process.exit(1);
     });
@@ -900,36 +778,15 @@ export function registerProjectsCommands(program) {
         .requiredOption('--number <n>', 'The PR number')
         .requiredOption('--sha <head-sha>', 'The head SHA you reviewed; GitHub refuses if the branch moved since')
         .option('--method <method>', `${MERGE_METHODS.join(' | ')} (default: the first the repo allows, in that order)`)
+        .option('--admin', 'Merge a PR branch protection blocks, as a repository admin. For a person\'s explicit confirm only; agents must never pass it')
         .option('--json', 'Machine-readable result')
         .action(async (name, opts) => {
-        const def = loadProjectDef(name);
-        if (!def) {
-            console.error(chalk.red(`No project named "${name}". List them: agents projects list`));
-            process.exit(1);
-        }
-        const raw = opts.number.trim();
-        const number = /^\d+$/.test(raw) ? Number.parseInt(raw, 10) : NaN;
-        if (!Number.isSafeInteger(number) || number <= 0) {
-            console.error(chalk.red(`--number expects a positive integer, got "${opts.number}".`));
-            process.exit(1);
-        }
-        if (!/^[0-9a-f]{7,40}$/i.test(opts.sha.trim())) {
-            console.error(chalk.red(`--sha expects a commit SHA, got "${opts.sha}".`));
-            process.exit(1);
-        }
-        if (opts.method !== undefined && !MERGE_METHODS.includes(opts.method)) {
-            console.error(chalk.red(`--method expects one of ${MERGE_METHODS.join(', ')}, got "${opts.method}".`));
-            process.exit(1);
-        }
-        let repo;
-        try {
-            [repo] = await resolveTargetSlugs(def, opts.repo, ghExec);
-        }
-        catch (e) {
-            console.error(chalk.red(e instanceof Error ? e.message : String(e)));
-            process.exit(1);
-        }
-        const result = await mergeProjectPr(repo, number, opts.sha.trim(), opts.method);
+        const def = prProjectOrExit(name);
+        const number = prNumberOrExit(opts.number);
+        const sha = prShaOrExit(opts.sha);
+        const method = prMethodOrExit(opts.method);
+        const repo = await prRepoOrExit(def, opts.repo);
+        const result = await mergeProjectPr(repo, number, sha, method, { admin: opts.admin === true });
         if (opts.json) {
             console.log(JSON.stringify(result, null, 2));
         }
@@ -950,16 +807,263 @@ export function registerProjectsCommands(program) {
     `,
         notes: `
       The merge is a single REST call pinned to --sha: if anything was pushed after
-      you read the PR, GitHub refuses and nothing merges. Branch protection, required
-      checks and reviews stay GitHub's to enforce; a refusal exits 1 with GitHub's
-      message (merged: false in --json).
+      you read the PR, GitHub refuses and nothing merges. Without --admin, a PR whose
+      live mergeable_state is not clean/unstable/has_hooks (blocked by a pending or red
+      required check or a review, behind, conflicted, or not computed yet) is refused
+      before the call. --admin skips that refusal and lets a
+      repository admin merge past branch protection where GitHub allows it; it exists
+      for a person's explicit confirm (AGI Menu's "Confirm admin merge") and agents
+      must never pass it. To land a PR once its checks pass, use prs automerge. A
+      refusal exits 1 with GitHub's reason (merged: false in --json).
+    `,
+    });
+    const automergeCmd = prsCmd
+        .command('automerge <name>')
+        .description('Turn GitHub auto-merge on (or off with --off) for one open PR, so it merges itself once its required checks pass.')
+        .requiredOption('--repo <owner/repo>', 'One of the project\'s attached repos')
+        .requiredOption('--number <n>', 'The PR number')
+        .option('--sha <head-sha>', 'The head SHA you reviewed (required to turn it on); GitHub refuses if the branch moved since')
+        .option('--method <method>', `${MERGE_METHODS.join(' | ')} (default: the first the repo allows, in that order)`)
+        .option('--off', 'Turn auto-merge off instead')
+        .option('--json', 'Machine-readable result')
+        .action(async (name, opts) => {
+        const def = prProjectOrExit(name);
+        const number = prNumberOrExit(opts.number);
+        const enable = opts.off !== true;
+        if (enable && opts.sha === undefined)
+            prFail('Pass --sha <head-sha>: auto-merge is pinned to the head you reviewed.');
+        if (!enable && opts.method !== undefined)
+            prFail('--method only applies when turning auto-merge on.');
+        const sha = opts.sha === undefined ? undefined : prShaOrExit(opts.sha);
+        const method = prMethodOrExit(opts.method);
+        const repo = await prRepoOrExit(def, opts.repo);
+        const result = await setProjectPrAutoMerge(repo, number, enable && sha !== undefined ? { enable: true, sha, method } : { enable: false });
+        const ok = result.enabled === enable;
+        if (opts.json)
+            console.log(JSON.stringify(result, null, 2));
+        else if (ok)
+            console.log(`${chalk.green(result.message)}: ${repo}#${number}`);
+        else
+            console.error(chalk.red(`Auto-merge not changed: ${repo}#${number}: ${result.message}`));
+        if (!ok)
+            process.exit(1);
+    });
+    setHelpSections(automergeCmd, {
+        examples: `
+      agents projects prs rush --json --repo phnx-labs/agi-cli --number 3646   # read headSha + merge.autoMergeAllowed
+      agents projects prs automerge rush --repo phnx-labs/agi-cli --number 3646 --sha <headSha>
+      agents projects prs automerge rush --repo phnx-labs/agi-cli --number 3646 --off --json
+    `,
+        notes: `
+      GitHub has no REST endpoint for auto-merge, so each call is one GraphQL
+      mutation (enablePullRequestAutoMerge / disablePullRequestAutoMerge) after a REST
+      read. Turning it on passes expectedHeadOid, so a branch that moved since --sha
+      is refused. The repository must allow auto-merge (merge.autoMergeAllowed in
+      prs --json), and GitHub refuses it on a PR that can already merge: use prs merge
+      for that. Exits 1 unless auto-merge ends in the requested state.
+    `,
+    });
+    const readyCmd = prsCmd
+        .command('ready <name>')
+        .description('Mark one draft PR of a project ready for review.')
+        .requiredOption('--repo <owner/repo>', 'One of the project\'s attached repos')
+        .requiredOption('--number <n>', 'The PR number')
+        .option('--sha <head-sha>', 'The head SHA you looked at; refused if the branch moved since')
+        .option('--json', 'Machine-readable result')
+        .action(async (name, opts) => {
+        const def = prProjectOrExit(name);
+        const number = prNumberOrExit(opts.number);
+        const sha = opts.sha === undefined ? undefined : prShaOrExit(opts.sha);
+        const repo = await prRepoOrExit(def, opts.repo);
+        const result = await markProjectPrReady(repo, number, sha);
+        if (opts.json)
+            console.log(JSON.stringify(result, null, 2));
+        else if (result.ready)
+            console.log(`${chalk.green(result.message)}: ${repo}#${number}`);
+        else
+            console.error(chalk.red(`Not marked ready: ${repo}#${number}: ${result.message}`));
+        if (!result.ready)
+            process.exit(1);
+    });
+    setHelpSections(readyCmd, {
+        examples: `
+      agents projects prs rush --json --repo phnx-labs/agi-cli --number 3646   # read isDraft + headSha
+      agents projects prs ready rush --repo phnx-labs/agi-cli --number 3646 --sha <headSha>
+      agents projects prs ready rush --repo phnx-labs/agi-cli --number 3646 --json
+    `,
+        notes: `
+      GitHub has no REST endpoint for this, so it is one GraphQL mutation
+      (markPullRequestReadyForReview) after a REST read. A PR that is already ready
+      succeeds without a write. With --sha, a head that moved is refused before the
+      write; GitHub cannot pin the mutation itself, so that check is not atomic.
+    `,
+    });
+    const reviewCmd = prsCmd
+        .command('review <name>')
+        .description('Approve one open PR of a project, pinned to the head SHA you reviewed.')
+        .requiredOption('--repo <owner/repo>', 'One of the project\'s attached repos')
+        .requiredOption('--number <n>', 'The PR number')
+        .requiredOption('--sha <head-sha>', 'The head SHA you reviewed; refused if the branch moved since')
+        .option('--approve', 'Submit an approving review (the only review this command submits)')
+        .option('--body <text>', 'Text to post with the approval')
+        .option('--json', 'Machine-readable result')
+        .action(async (name, opts) => {
+        const def = prProjectOrExit(name);
+        const number = prNumberOrExit(opts.number);
+        const sha = prShaOrExit(opts.sha);
+        if (!opts.approve)
+            prFail('Pass --approve: approving is the only review this command submits.');
+        const repo = await prRepoOrExit(def, opts.repo);
+        const result = await approveProjectPr(repo, number, sha, opts.body);
+        if (opts.json)
+            console.log(JSON.stringify(result, null, 2));
+        else if (result.submitted)
+            console.log(`${chalk.green('Approved')} ${repo}#${number} at ${chalk.gray((result.sha ?? '').slice(0, 7))}`);
+        else
+            console.error(chalk.red(`Not approved: ${repo}#${number}: ${result.message}`));
+        if (!result.submitted)
+            process.exit(1);
+    });
+    setHelpSections(reviewCmd, {
+        examples: `
+      agents projects prs rush --json --repo phnx-labs/agi-cli --number 3646   # read headSha
+      agents projects prs review rush --repo phnx-labs/agi-cli --number 3646 --approve --sha <headSha>
+      agents projects prs review rush --repo phnx-labs/agi-cli --number 3646 --approve --sha <headSha> --body "Checked the migration" --json
+    `,
+        notes: `
+      One REST call (POST pulls/{n}/reviews, event APPROVE). The live head is read
+      first and a moved head is refused; the review carries commit_id = that SHA, so
+      it is recorded against the code you saw. On your own PR it answers at once
+      (exit 1, submitted: false) without calling GitHub, which never allows that.
+    `,
+    });
+    const commentCmd = prsCmd
+        .command('comment <name>')
+        .description('Post a comment on one open PR of a project.')
+        .requiredOption('--repo <owner/repo>', 'One of the project\'s attached repos')
+        .requiredOption('--number <n>', 'The PR number')
+        .option('--body <text>', 'The comment text')
+        .option('--body-file <path>', 'Read the comment from a file; - reads stdin')
+        .option('--json', 'Machine-readable result')
+        .action(async (name, opts) => {
+        const def = prProjectOrExit(name);
+        const number = prNumberOrExit(opts.number);
+        const body = prCommentBodyOrExit(opts.body, opts.bodyFile);
+        const repo = await prRepoOrExit(def, opts.repo);
+        const result = await commentOnProjectPr(repo, number, body);
+        if (opts.json)
+            console.log(JSON.stringify(result, null, 2));
+        else if (result.commented)
+            console.log(`${chalk.green('Commented')} on ${repo}#${number} ${chalk.gray(result.url ?? '')}`);
+        else
+            console.error(chalk.red(`Not commented: ${repo}#${number}: ${result.message}`));
+        if (!result.commented)
+            process.exit(1);
+    });
+    setHelpSections(commentCmd, {
+        examples: `
+      agents projects prs comment rush --repo phnx-labs/agi-cli --number 3646 --body "Looks good once CI is green"
+      printf 'Two notes:\\n- one\\n- two\\n' | agents projects prs comment rush --repo phnx-labs/agi-cli --number 3646 --body-file - --json
+    `,
+        notes: `
+      One REST call (POST issues/{n}/comments), not the GraphQL-backed gh pr comment.
+      Pass exactly one of --body or --body-file; an empty comment is refused.
+    `,
+    });
+    const failureCmd = prsCmd
+        .command('failure <name>')
+        .description('Why one commit\'s CI failed: each failing check with the error lines of its job log.')
+        .requiredOption('--repo <owner/repo>', 'One of the project\'s attached repos')
+        .requiredOption('--sha <commit>', 'The commit whose checks failed: a PR head, a merge commit, or the default branch head')
+        .option('--json', 'Machine-readable result')
+        .action(async (name, opts) => {
+        const def = prProjectOrExit(name);
+        const sha = prShaOrExit(opts.sha);
+        const repo = await prRepoOrExit(def, opts.repo);
+        const report = await readCiFailure(repo, sha);
+        if (opts.json) {
+            console.log(JSON.stringify(report, null, 2));
+        }
+        else if (report.error) {
+            console.error(chalk.red(`Could not read the checks of ${repo}@${sha.slice(0, 7)}: ${report.error}`));
+        }
+        else if (report.checks.length === 0) {
+            console.log(`No failing checks on ${repo}@${sha.slice(0, 7)}.`);
+        }
+        else {
+            for (const check of report.checks) {
+                console.log(`${chalk.red('✗')} ${chalk.bold(check.name)}  ${chalk.gray(check.conclusion.toLowerCase())}${check.url ? `  ${chalk.gray(check.url)}` : ''}`);
+                for (const line of check.excerpt)
+                    console.log(`    ${line}`);
+                if (check.excerptError)
+                    console.log(chalk.yellow(`    ${check.excerptError}`));
+                if (check.runId !== null)
+                    console.log(chalk.gray(`    re-run: agents projects prs rerun ${name} --repo ${repo} --run-id ${check.runId}`));
+            }
+        }
+        if (report.error)
+            process.exit(1);
+    });
+    setHelpSections(failureCmd, {
+        examples: `
+      agents projects prs rush --json                                   # read a ✗: defaultBranch.sha, a PR's headSha, or a merge's mergeCommitSha
+      agents projects prs failure rush --repo phnx-labs/agi-cli --sha <sha>
+      agents projects prs failure rush --repo phnx-labs/agi-cli --sha <sha> --json
+    `,
+        notes: `
+      REST only: the commit's check runs and statuses, then each failing GitHub
+      Actions job's log (GET actions/jobs/{job}/logs). The excerpt drops timestamps,
+      colour and the runner's cleanup after "Post job cleanup.", and keeps the lines
+      that read like an error with one line of context each side, at most 12. A log
+      that cannot be read empties that excerpt and says why in excerptError; a check
+      that is not an Actions job has no log here. Exits 1 only when the checks
+      themselves could not be read.
+    `,
+    });
+    const rerunCmd = prsCmd
+        .command('rerun <name>')
+        .description('Re-run the failed jobs of one GitHub Actions workflow run.')
+        .requiredOption('--repo <owner/repo>', 'One of the project\'s attached repos')
+        .requiredOption('--run-id <id>', 'The workflow run (runId from prs failure --json)')
+        .option('--json', 'Machine-readable result')
+        .action(async (name, opts) => {
+        const def = prProjectOrExit(name);
+        const raw = opts.runId.trim();
+        const runId = /^\d+$/.test(raw) ? Number(raw) : NaN;
+        if (!Number.isSafeInteger(runId) || runId <= 0)
+            prFail(`--run-id expects a positive integer, got "${opts.runId}".`);
+        const repo = await prRepoOrExit(def, opts.repo);
+        const result = await rerunFailedJobs(repo, runId);
+        if (opts.json)
+            console.log(JSON.stringify(result, null, 2));
+        else if (result.requested)
+            console.log(`${chalk.green(result.message)}: ${repo} run ${runId}`);
+        else
+            console.error(chalk.red(`Not re-run: ${repo} run ${runId}: ${result.message}`));
+        if (!result.requested)
+            process.exit(1);
+    });
+    setHelpSections(rerunCmd, {
+        examples: `
+      agents projects prs failure rush --repo phnx-labs/agi-cli --sha <sha> --json   # runId per failing check
+      agents projects prs rerun rush --repo phnx-labs/agi-cli --run-id 37243157132
+    `,
+        notes: `
+      One REST call (POST actions/runs/{id}/rerun-failed-jobs). Re-running only
+      repeats jobs, so it is safe to click again; GitHub refuses a run that is still
+      in progress (exit 1, requested: false in --json).
     `,
     });
     setHelpSections(prsCmd, {
         examples: `
       agents projects prs rush --json                       # every open PR across rush's repos (= prs list rush)
       agents projects prs rush --json --repo phnx-labs/agi-cli --number 3646  # one PR, with checks + mergeability
+      agents projects prs ready rush --repo phnx-labs/agi-cli --number 3646 --sha <headSha>
+      agents projects prs review rush --repo phnx-labs/agi-cli --number 3646 --approve --sha <headSha>
+      agents projects prs comment rush --repo phnx-labs/agi-cli --number 3646 --body-file -
       agents projects prs merge rush --repo phnx-labs/agi-cli --number 3646 --sha <headSha>
+      agents projects prs failure rush --repo phnx-labs/agi-cli --sha <sha>
+      agents projects prs rerun rush --repo phnx-labs/agi-cli --run-id <runId>
     `,
     });
     setHelpSections(prsListCmd, {
@@ -989,7 +1093,7 @@ export function registerProjectsCommands(program) {
       partial (JSON reports errors per repository; text mode exits non-zero).
     `,
     });
-    // ---- edit ----
+    registerProjectTodoCommands(projects);
     projects
         .command('edit <name>')
         .description('Open the project YAML in $EDITOR (it is hand-editable regardless).')
@@ -1000,33 +1104,21 @@ export function registerProjectsCommands(program) {
             process.exit(1);
         }
         const editor = process.env.VISUAL || process.env.EDITOR || 'vi';
-        // $EDITOR commonly carries args ("code --wait") — split like monitors/routines do.
         const parts = editor.split(/\s+/).filter(Boolean);
         const res = spawnSync(parts[0], [...parts.slice(1), target], { stdio: 'inherit' });
         process.exit(res.status ?? 0);
     });
-    // ---- probe (hidden; the peer half of `status --fleet`) ----
     projects
         .command('probe [paths...]', { hidden: true })
         .description('Probe workspace repos (presence, branch, drift, dirtiness) and print JSON. Answers for this machine only.')
         .action((paths) => {
-        // Never fans out — the recursion guard env is set by the parent fan-out,
-        // and this command has no remote code path either way.
         console.log(JSON.stringify(probeProjectWorkspaces(paths ?? []), null, 2));
     });
-    // ---- pull-local (hidden; the peer half of `pull`) ----
     projects
         .command('pull-local', { hidden: true })
         .description('Fast-forward workspace repos (default-branch only) and print JSON. Answers for this machine only.')
         .requiredOption('--targets <json>', 'JSON array of {path, expectedSlug} targets, from the orchestrating `pull`')
         .action(async (opts) => {
-        // Never fans out — this is the peer half of the fleet fan-out.
-        //
-        // Targets arrive as {path, expectedSlug} PAIRS, not bare paths: the slug
-        // is what lets this machine refuse to fast-forward a directory hosting a
-        // different repo, and it is hashed into the fingerprint the caller
-        // verifies. Decoding failures exit non-zero so the caller records this
-        // peer as skipped instead of reading a missing answer as "nothing to do".
         let targets;
         try {
             targets = decodePullTargets(opts.targets);
@@ -1039,7 +1131,6 @@ export function registerProjectsCommands(program) {
         const envelope = buildPullEnvelope(results, targets);
         console.log(JSON.stringify(envelope, null, 2));
     });
-    // ---- pull ----
     const pullCmd = projects
         .command('pull <name>')
         .description('Fast-forward every fleet checkout of a named project to its remote default branch.')
@@ -1058,14 +1149,8 @@ export function registerProjectsCommands(program) {
             process.exit(0);
         }
         const deviceFilter = resolveDeviceFilter(rawOpts.device, rawOpts.devices);
-        // Pull locally first.
         const self = machineId();
         const localResults = await pullProjectTargets(targets, self);
-        // Fan out to fleet peers. Send the full {path, expectedSlug} targets —
-        // bare paths would disable slug verification on every peer AND make the
-        // peer's fingerprint (which hashes the slug) unmatchable, so its whole
-        // answer would be discarded. Compute the fingerprint once so every peer
-        // envelope can be verified against the exact target set we sent.
         const expectedFingerprint = fingerprintTargets(targets);
         const remoteRes = await gatherRemoteAgentsJson({
             args: pullLocalArgs(targets),
@@ -1077,10 +1162,6 @@ export function registerProjectsCommands(program) {
         });
         const allResults = [...localResults, ...remoteRes.items];
         if (rawOpts.json) {
-            // Mirror `status --json`: peers that didn't answer, or answered
-            // unverifiably, go to stderr so a machine caller can still tell them
-            // apart from a device with nothing to report (the JSON array itself
-            // stays a clean result list).
             if (remoteRes.skipped.length > 0)
                 process.stderr.write(formatFleetSkippedNote(remoteRes.skipped));
             if (remoteRes.parseFailed.length > 0)
@@ -1090,8 +1171,6 @@ export function registerProjectsCommands(program) {
         else {
             printProjectPullSummary(name, allResults, remoteRes.skipped, remoteRes.parseFailed);
         }
-        // A peer whose answer could not be verified already ran a real pull whose
-        // outcome we cannot see — that is a failed pull, not a quiet success.
         if (!projectPullComplete(allResults) || remoteRes.parseFailed.length > 0) {
             process.exit(1);
         }
@@ -1119,7 +1198,6 @@ export function registerProjectsCommands(program) {
       as unavailable and does not.
     `,
     });
-    // ---- import ----
     projects
         .command('import')
         .description('Import project definitions from Linear (via the `linear` CLI).')
@@ -1144,7 +1222,6 @@ export function registerProjectsCommands(program) {
         for (const skip of result.skipped)
             console.log(chalk.gray(`  skip ${skip.name}: ${skip.reason}`));
     });
-    // ---- set ----
     projects
         .command('set <name>')
         .description('Change one field on a project definition, preserving everything else.')
@@ -1168,15 +1245,10 @@ export function registerProjectsCommands(program) {
             console.error(chalk.red('Nothing to set. Pass a field, e.g. --repo <owner/repo>.'));
             process.exit(1);
         }
-        // One --slug cannot name two directories. Refuse rather than guess which
-        // --add-dir it was meant for.
         if (opts.slug && opts.addDir.length !== 1) {
             console.error(chalk.red('--slug names a single --add-dir; pass exactly one --add-dir with it.'));
             process.exit(1);
         }
-        // Load, mutate the named fields, write back — the `link` pattern. NEVER
-        // the `add --force` pattern, which rebuilds the def from flags alone and
-        // silently drops linear/contexts/integrations that were not re-passed.
         if (opts.repo !== undefined)
             def.repo = opts.repo;
         if (opts.root !== undefined)
@@ -1186,11 +1258,6 @@ export function registerProjectsCommands(program) {
         if (opts.goal?.length)
             def.goals = opts.goal.map(parseGoalFlag);
         if (opts.path !== undefined) {
-            // `--path` is a subdir OF the root, so without one there is nothing to
-            // hang it off. A def imported with `--from-linear` that found no local
-            // checkout carries name + linear and no root — joining against '' there
-            // would silently write `/apps/cli`, an absolute path at the filesystem
-            // root, and the def would resolve somewhere that does not exist.
             const base = (opts.root ?? def.root ?? '').replace(/\/$/, '');
             if (!base) {
                 console.error(chalk.red(`"${def.name}" has no root, so --path has nothing to resolve against.`));
@@ -1199,8 +1266,6 @@ export function registerProjectsCommands(program) {
             }
             def.defaultPath = `${base}/${opts.path.replace(/^\//, '')}`;
         }
-        // --rm-dir before --add-dir, so re-pointing one directory in a single
-        // command (`--rm-dir old --add-dir new`) does what it reads like.
         const removed = [];
         for (const d of opts.rmDir) {
             const target = path.resolve(expandLocalHome(d));
@@ -1241,7 +1306,6 @@ export function registerProjectsCommands(program) {
         for (const r of added)
             console.log(chalk.gray(`  + dir  ${r.path}  ·  ${r.slug}`));
     });
-    // ---- link ----
     projects
         .command('link <name>')
         .description('Attach an external tracker to a project definition (writes linear.projectId + name into the YAML; re-run to pick up a Linear rename).')
@@ -1256,8 +1320,6 @@ export function registerProjectsCommands(program) {
             console.error(chalk.red('Nothing to link. Pass a tracker flag, e.g. --linear [query].'));
             process.exit(1);
         }
-        // Explicit user command — a missing/unauthenticated `linear` CLI is loud,
-        // unlike the best-effort card enrichment.
         let list;
         try {
             list = listLinearProjects();
@@ -1272,9 +1334,6 @@ export function registerProjectsCommands(program) {
             pick = pickLinearProject(query, list);
         }
         else {
-            // Auto-suggest from the def's own identity — the primary repo slug is
-            // the sharpest key, then the def name. Only an exact normalized match
-            // writes itself; anything weaker asks the user to disambiguate.
             pick = { kind: 'none' };
             for (const hint of [def.repo, def.name].filter((h) => typeof h === 'string' && h.length > 0)) {
                 const d = pickLinearProject(hint, list);
@@ -1301,21 +1360,16 @@ export function registerProjectsCommands(program) {
             process.exit(1);
         }
         const p = pick.project;
-        // Preserve every other field — load, set linear, write back. Keep a
-        // previously linked url when the new CLI row carries none.
         if (def.linear?.projectId && def.linear.projectId !== p.id) {
             console.log(chalk.gray(`  replacing previous Linear link (${def.linear.projectId})`));
         }
         if (def.linear?.name && def.linear.name !== p.name) {
             console.log(chalk.gray(`  renaming "${def.linear.name}" → "${p.name}" (Linear is authoritative)`));
         }
-        // Assigned, not spread over `def.linear`: a spread would resurrect a url
-        // that nextLinearLink deliberately dropped. The block has no other fields.
         def.linear = nextLinearLink(def.linear, p);
         writeProjectDef(def);
         console.log(chalk.green(`${def.name} → Linear project "${p.name}" (${p.id})${p.url ? ` ${p.url}` : ''}`));
     });
-    // ---- save ----
     projects
         .command('save')
         .description('Create or update one project from a complete ProjectDef JSON object on stdin.')
@@ -1357,7 +1411,6 @@ export function registerProjectsCommands(program) {
         }
         console.log(JSON.stringify(saved, null, 2));
     });
-    // ---- rm ----
     projects
         .command('remove <name>')
         .alias('rm')