@phnx-labs/agents-cli 1.21.1 → 1.21.2

package/dist/commands/perf.js

@@ -6,6 +6,7 @@
  *   agents perf hooks        per-hook p50/p99 + cache hit rates
  *   agents perf commands     slowest CLI command paths (from command.end)
  *   agents perf run          agent.run / perf.timing labels
+ *   agents perf friction     sessions stuck repeatedly hitting the same guard
  *
  * Soft-joins sessions.db via shared string keys (session_id, agent, machine) —
  * no foreign keys. Warehouse lives at ~/.agents/.cache/perf/perf.db (safe to wipe).
@@ -13,6 +14,8 @@
 import chalk from 'chalk';
 import { aggregateSamples, perfDbPath, } from '../lib/perf/db.js';
 import { formatMs, formatCacheColumn, DEFAULT_SLOW_HOOK_WARN_MS, loadHookFireEvents, aggregateHookProfile, } from '../lib/hooks/profile.js';
+import { query } from '../lib/events.js';
+import { detectRepeatedGuardBlocks } from '../lib/friction-heuristics.js';
 function parseDays(raw) {
     const n = parseInt(raw ?? '7', 10);
     return Number.isFinite(n) && n > 0 ? n : 7;
@@ -26,11 +29,12 @@ function parseLimit(raw, fallback) {
     return Number.isFinite(n) && n > 0 ? n : fallback;
 }
 /** Map warehouse rows shaped like hook.fire into the existing HookProfileRow UI. */
-function asHookRows(rows) {
+export function asHookRows(rows) {
     return rows.map((r) => ({
         hook: r.label,
         n: r.n,
         p50Ms: r.p50Ms,
+        p95Ms: r.p95Ms,
         p99Ms: r.p99Ms,
         meanMs: r.meanMs,
         maxMs: r.maxMs,
@@ -38,6 +42,9 @@ function asHookRows(rows) {
         cacheStalePct: r.cacheStalePct ?? 0,
         cacheMissPct: r.cacheMissPct ?? 0,
         errorCount: r.errorCount ?? 0,
+        errorRate: r.errorRate,
+        timeoutRate: r.timeoutRate,
+        project: r.project,
     }));
 }
 function printTable(headers, widths, lines, slowFlags) {
@@ -50,23 +57,34 @@ function printTable(headers, widths, lines, slowFlags) {
         console.log(slowFlags[i] ? chalk.yellow(line) : line);
     }
 }
-function renderHookTable(rows, warnMs) {
+/** `err:12% to:4%` when either rate is present, else ''. */
+function formatRateColumn(r) {
+    const parts = [];
+    if (r.errorRate)
+        parts.push(`err:${Math.round(r.errorRate * 100)}%`);
+    if (r.timeoutRate)
+        parts.push(`to:${Math.round(r.timeoutRate * 100)}%`);
+    return parts.join(' ');
+}
+export function renderHookTable(rows, warnMs) {
     if (rows.length === 0) {
         console.log(chalk.gray('No hook timing samples yet.'));
         console.log(chalk.gray(`Warehouse: ${perfDbPath()}`));
         console.log(chalk.gray('Hooks write via cache/matches shims into the spool; run a session or resync hooks.'));
         return;
     }
-    const widths = { hook: 36, n: 5, p50: 7, p99: 7, mean: 7, max: 7, cache: 28 };
+    const widths = { hook: 36, n: 5, p50: 7, p95: 7, p99: 7, mean: 7, max: 7, cache: 22, rate: 14 };
     const pad = (s, w) => (s.length >= w ? s.slice(0, w) : s + ' '.repeat(w - s.length));
     const header = [
         pad('HOOK', widths.hook),
         pad('N', widths.n),
         pad('P50', widths.p50),
+        pad('P95', widths.p95),
         pad('P99', widths.p99),
         pad('MEAN', widths.mean),
         pad('MAX', widths.max),
         pad('CACHE', widths.cache),
+        pad('ERR/TIMEOUT', widths.rate),
     ].join(' ');
     console.log(chalk.bold(header));
     console.log(chalk.gray('─'.repeat(header.length)));
@@ -78,10 +96,12 @@ function renderHookTable(rows, warnMs) {
             pad(r.hook, widths.hook),
             pad(String(r.n), widths.n),
             pad(formatMs(r.p50Ms), widths.p50),
+            pad(formatMs(r.p95Ms), widths.p95),
             pad(formatMs(r.p99Ms), widths.p99),
             pad(formatMs(r.meanMs), widths.mean),
             pad(formatMs(r.maxMs), widths.max),
             pad(cacheCol, widths.cache),
+            pad(formatRateColumn(r), widths.rate),
         ].join(' ') + warning;
         console.log(slow ? chalk.yellow(line) : line);
     }
@@ -92,30 +112,34 @@ function renderLabelTable(title, rows, warnMs, limit) {
         console.log(chalk.gray(`No ${title} samples yet.`));
         return;
     }
-    const widths = [40, 5, 7, 7, 7, 7];
-    printTable(['LABEL', 'N', 'P50', 'P99', 'MEAN', 'MAX'], widths, sliced.map((r) => [
+    const widths = [40, 5, 7, 7, 7, 7, 7, 14];
+    printTable(['LABEL', 'N', 'P50', 'P95', 'P99', 'MEAN', 'MAX', 'ERR/TIMEOUT'], widths, sliced.map((r) => [
         r.label,
         String(r.n),
         formatMs(r.p50Ms),
+        formatMs(r.p95Ms),
         formatMs(r.p99Ms),
         formatMs(r.meanMs),
         formatMs(r.maxMs),
+        formatRateColumn(r),
     ]), sliced.map((r) => r.p99Ms > warnMs));
 }
 /**
  * Prefer SQLite samples; fall back to the legacy daily JSONL so existing
- * instrumentation still surfaces until shims are resynced.
+ * instrumentation still surfaces until shims are resynced. `project` only
+ * narrows the SQLite path — the legacy JSONL log has no cwd, so a fallback
+ * hit ignores it (a caller filtering by project has no legacy rows to miss).
  */
-function loadHookProfile(days) {
-    const fromDb = asHookRows(aggregateSamples({ days, kinds: ['hook.fire'] }));
-    if (fromDb.length > 0)
+export function loadHookProfile(days, project) {
+    const fromDb = asHookRows(aggregateSamples({ days, kinds: ['hook.fire'], project }));
+    if (fromDb.length > 0 || project)
         return fromDb;
     return aggregateHookProfile(loadHookFireEvents(days));
 }
 function hooksAction(opts) {
     const days = parseDays(opts.days);
     const warnMs = parseWarnMs(opts.warnMs, DEFAULT_SLOW_HOOK_WARN_MS);
-    const rows = loadHookProfile(days);
+    const rows = loadHookProfile(days, opts.project);
     if (opts.json) {
         console.log(JSON.stringify(rows, null, 2));
         return;
@@ -126,7 +150,7 @@ function commandsAction(opts) {
     const days = parseDays(opts.days);
     const warnMs = parseWarnMs(opts.warnMs, 500);
     const limit = parseLimit(opts.limit, 40);
-    const rows = aggregateSamples({ days, kinds: ['command.end'] });
+    const rows = aggregateSamples({ days, kinds: ['command.end'], project: opts.project });
     if (opts.json) {
         console.log(JSON.stringify(rows.slice(0, limit), null, 2));
         return;
@@ -137,42 +161,69 @@ function runAction(opts) {
     const days = parseDays(opts.days);
     const warnMs = parseWarnMs(opts.warnMs, 60_000);
     const limit = parseLimit(opts.limit, 40);
-    const rows = aggregateSamples({ days, kinds: ['perf.timing'] });
+    const rows = aggregateSamples({ days, kinds: ['perf.timing'], project: opts.project });
     if (opts.json) {
         console.log(JSON.stringify(rows.slice(0, limit), null, 2));
         return;
     }
     renderLabelTable('run/timing', rows, warnMs, limit);
 }
+/**
+ * Sessions stuck repeatedly hitting the SAME guard block (git-guard,
+ * rm-guard, git-require-clean-tree, …) instead of adapting after the first
+ * denial. Reads the `friction` event sink (emitFriction in events.ts) that
+ * guard hooks self-report into via `agents _internal friction` before they
+ * exit 2 — see lib/friction-heuristics.ts for the grouping.
+ */
+function frictionAction(opts) {
+    const days = parseDays(opts.days);
+    const startDate = new Date(Date.now() - days * 86_400_000);
+    const events = query({ eventTypes: ['friction'], startDate });
+    const findings = detectRepeatedGuardBlocks(events);
+    if (opts.json) {
+        console.log(JSON.stringify(findings, null, 2));
+        return;
+    }
+    if (findings.length === 0) {
+        console.log(chalk.gray(`No repeated guard blocks in the last ${days} day${days === 1 ? '' : 's'}.`));
+        return;
+    }
+    console.log(chalk.bold(`Repeated guard blocks — last ${days} day${days === 1 ? '' : 's'}\n`));
+    const widths = [14, 10, 24, 5, 22, 22];
+    printTable(['SESSION', 'SURFACE', 'FAILURE ID', 'N', 'FIRST', 'LAST'], widths, findings.map((f) => [f.session, f.surface, f.failureId, String(f.count), f.firstTs, f.lastTs]), findings.map(() => false));
+}
 function summaryAction(opts) {
     const days = parseDays(opts.days);
+    const project = opts.project;
     if (opts.json) {
         console.log(JSON.stringify({
             days,
+            project: project ?? null,
             warehouse: perfDbPath(),
-            hooks: loadHookProfile(days),
-            commands: aggregateSamples({ days, kinds: ['command.end'] }).slice(0, 20),
-            run: aggregateSamples({ days, kinds: ['perf.timing'] }).slice(0, 20),
+            hooks: loadHookProfile(days, project),
+            commands: aggregateSamples({ days, kinds: ['command.end'], project }).slice(0, 20),
+            run: aggregateSamples({ days, kinds: ['perf.timing'], project }).slice(0, 20),
         }, null, 2));
         return;
     }
-    console.log(chalk.bold(`agents perf — last ${days} day${days === 1 ? '' : 's'}`));
+    console.log(chalk.bold(`agents perf — last ${days} day${days === 1 ? '' : 's'}${project ? ` — project ${project}` : ''}`));
     console.log(chalk.gray(`warehouse: ${perfDbPath()}  (disposable; soft-join sessions via session_id/agent/machine)`));
     console.log('');
     console.log(chalk.bold('Commands (slowest by p99)'));
-    renderLabelTable('command', aggregateSamples({ days, kinds: ['command.end'] }), parseWarnMs(opts.warnMs, 500), 12);
+    renderLabelTable('command', aggregateSamples({ days, kinds: ['command.end'], project }), parseWarnMs(opts.warnMs, 500), 12);
     console.log('');
     console.log(chalk.bold('Hooks'));
-    renderHookTable(loadHookProfile(days), parseWarnMs(opts.warnMs, DEFAULT_SLOW_HOOK_WARN_MS));
+    renderHookTable(loadHookProfile(days, project), parseWarnMs(opts.warnMs, DEFAULT_SLOW_HOOK_WARN_MS));
     console.log('');
     console.log(chalk.bold('Runs (perf.timing)'));
-    renderLabelTable('run/timing', aggregateSamples({ days, kinds: ['perf.timing'] }), parseWarnMs(opts.warnMs, 60_000), 12);
+    renderLabelTable('run/timing', aggregateSamples({ days, kinds: ['perf.timing'], project }), parseWarnMs(opts.warnMs, 60_000), 12);
 }
 function attachSharedOptions(cmd) {
     return cmd
         .option('--days <n>', 'Days of samples to include', '7')
         .option('--warn-ms <n>', 'p99 above this is highlighted')
         .option('--limit <n>', 'Max rows in the table', '40')
+        .option('--project <key>', 'Scope to one project (the repo directory name a sample\'s cwd resolves to — see project-key.ts)')
         .option('--json', 'Emit JSON instead of a table');
 }
 /**
@@ -195,11 +246,13 @@ Identity columns reuse sessions/events string shapes (session_id, agent, machine
 for soft cross-reference; there are no foreign keys.
 
 Examples:
-  agents perf                     # summary: commands + hooks + runs
-  agents perf hooks               # per-hook p50/p99 + cache hit rate
-  agents perf commands --days 30  # slowest CLI entrypoints
-  agents perf run --json          # agent.run timings as JSON
+  agents perf                        # summary: commands + hooks + runs
+  agents perf hooks                  # per-hook p50/p95/p99 + cache hit rate
+  agents perf commands --days 30     # slowest CLI entrypoints
+  agents perf run --json             # agent.run timings as JSON
   agents perf hooks --warn-ms 500
+  agents perf hooks --project agents-cli  # scope to one repo's samples
+  agents perf friction               # sessions stuck retrying the same guard block
 `);
     // Options live on the parent so `agents perf --json` and
     // `agents perf commands --json` both work (see leafOpts).
@@ -218,4 +271,8 @@ Examples:
         .action(function run() {
         runAction(leafOpts(this));
     });
+    perf.command('friction').description('Sessions stuck repeatedly hitting the same guard block')
+        .action(function friction() {
+        frictionAction(leafOpts(this));
+    });
 }

package/dist/commands/projects.d.ts

@@ -20,6 +20,8 @@ export declare const PROJECTS_NO_FANOUT_ENV = "AGENTS_PROJECTS_LOCAL";
  * string when everything answered.
  */
 export declare function formatFleetSkippedNote(skipped: string[]): string;
+/** Best-effort `owner/repo` from a repo's origin remote. */
+export declare function originSlug(cwd: string): string | undefined;
 /** One `projects list` row, pre-render. */
 export interface ProjectListRow {
     name: string;
@@ -45,6 +47,15 @@ export declare function computeProjectListWidths(rows: ProjectListRow[]): {
  * read it as UTC and shift the answer by a day for anyone west of Greenwich.
  */
 export declare function formatMilestoneDue(targetDate: string, nowMs: number): string | undefined;
+/**
+ * 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 declare function formatMilestoneLines(milestones: LinearMilestone[], next: LinearMilestone | undefined, nowMs: number, limit: number): string[];
 /** The `next` card line: what this project is due to hit, and how far along it is. */
 export declare function formatNextMilestone(ms: LinearMilestone, nowMs: number): string;
 export declare function registerProjectsCommands(program: Command): void;

package/dist/commands/projects.js

@@ -25,9 +25,10 @@ import { gatherRemoteAgentsJson } from '../lib/remote-agents-json.js';
 import { factoryProjectsPath } from '../lib/auto-dispatch.js';
 import { formatFleetWorkspaces, parseRemoteProbe, probeProjectWorkspaces, workspaceTargetsForDef, } from '../lib/project-probe.js';
 import { listProjectDefs, loadProjectDef, writeProjectDef, removeProjectDef, projectDefPath, isSafeProjectName, } from '../lib/projects.js';
-import { rollupSessionsByProject, planPct, enrichProjectSignals, formatProjectMembers, } from '../lib/project-status.js';
+import { rollupSessionsByProject, liveDeadSplit, enrichProjectSignals, formatProjectMembers, } from '../lib/project-status.js';
 import { fetchLinearProjectCounts } from '../lib/linear-project-counts.js';
 import { listLinearProjects, pickLinearProject } from '../lib/linear-projects.js';
+import { checkRepoSlug } from '../lib/project-doctor.js';
 import { buildFactoryImportCandidates, buildLinearImportCandidates, validateImportOpts, } from '../lib/project-import.js';
 /** Recursion guard: a peer answering a probe fan-out never re-fans-out itself. */
 export const PROJECTS_NO_FANOUT_ENV = 'AGENTS_PROJECTS_LOCAL';
@@ -57,7 +58,7 @@ function parseContextFlag(raw) {
     return { path: raw.slice(0, i).trim(), purpose: raw.slice(i + 1).trim() };
 }
 /** Best-effort `owner/repo` from a repo's origin remote. */
-function originSlug(cwd) {
+export function originSlug(cwd) {
     try {
         const url = execFileSync('git', ['remote', 'get-url', 'origin'], { cwd, encoding: 'utf8' }).trim();
         return parseOwnerRepoFromRemote(url) ?? undefined;
@@ -94,7 +95,9 @@ function runFactoryImport(existing, opts) {
         : Array.isArray(parsed?.projects)
             ? parsed.projects
             : [];
-    return buildFactoryImportCandidates(rows, existing, opts);
+    // The checkout's real `origin` overrides the registry's path-derived slug —
+    // see buildFactoryImportCandidates for why the path guess is not trustworthy.
+    return buildFactoryImportCandidates(rows, existing, opts, (root) => originSlug(expandLocalHome(root)));
 }
 /**
  * List the workspace's Linear projects and plan their import, binding each to a
@@ -183,6 +186,40 @@ 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;
+    const ordered = [...lead, ...others];
+    const shown = ordered.slice(0, Math.max(1, limit));
+    const out = shown.map((m, i) => {
+        const label = i === 0 && lead.length > 0 ? 'next' : i === 0 ? 'plan' : '';
+        return `  ${chalk.dim(label.padEnd(4))}     ${formatNextMilestone(m, nowMs)}`;
+    });
+    const rest = milestones.length - shown.length;
+    if (rest > 0) {
+        out.push(`  ${' '.repeat(4)}     ${chalk.dim(`+${rest} more milestone${rest === 1 ? '' : 's'} — agents projects view <name>`)}`);
+    }
+    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)];
@@ -206,25 +243,39 @@ 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);
-    // Sessions in a non-live state (orphaned/crashed/unknown) count toward the
-    // headline — render the remainder so the bar never sums to less than it.
-    if (r.agents > shown)
-        parts.push(chalk.gray(`+${r.agents - shown} other`));
+    // 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');
 }
-function renderCard(def, r, remote, fleet, linear, nowMs = Date.now()) {
-    const agents = r?.agents ?? 0;
-    const pct = r ? planPct(r.plan) : undefined;
-    const planStr = pct === undefined ? '' : `  ·  ${chalk.cyan(`${pct}% plan`)}`;
-    console.log(`${chalk.bold(def.name)}  ${chalk.dim('·')}  ${chalk.bold(`${agents} agents`)}${planStr}`);
+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) {
+    // 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%`.
+    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.
+        const detail = split.deadByStatus.map((d) => `${d.n} ${d.status}`).join(', ');
+        console.log(`  ${chalk.dim('dead')}     ${chalk.yellow(`${split.dead} finished or lost`)} ${chalk.dim(`(${detail})`)}`);
+    }
     if (r && r.members.length)
         console.log(`  ${chalk.dim('agents')}   ${formatProjectMembers(r.members)}`);
     const ships = [];
-    if (remote?.mergedPrs)
-        ships.push(chalk.green(`${remote.mergedPrs} merged (${remote.windowDays}d)`));
+    if (remote?.mergedPrs) {
+        ships.push(chalk.green(`${remote.mergedPrs}${remote.mergedPrsTruncated ? '+' : ''} merged (${remote.windowDays}d)`));
+    }
     if (r?.openPrs.length)
         ships.push(`${r.openPrs.length} open PR${r.openPrs.length === 1 ? '' : 's'}`);
     if (r?.worktrees)
@@ -236,8 +287,8 @@ function renderCard(def, r, remote, fleet, linear, nowMs = Date.now()) {
     if (linear) {
         console.log(`  ${chalk.dim('linear')}   ${linear.done}/${linear.total}${linear.truncated ? '+' : ''} done · ${linear.inProgress} in progress`);
     }
-    if (linear?.nextMilestone) {
-        console.log(`  ${chalk.dim('next')}     ${formatNextMilestone(linear.nextMilestone, nowMs)}`);
+    for (const line of formatMilestoneLines(linear?.milestones ?? [], linear?.nextMilestone, nowMs, milestoneLimit)) {
+        console.log(line);
     }
     if (r && r.tickets.length) {
         console.log(`  ${chalk.dim('tickets')}  ${r.tickets.slice(0, 8).join(' · ')}${r.tickets.length > 8 ? ' …' : ''}`);
@@ -258,6 +309,14 @@ function renderCard(def, r, remote, fleet, linear, nowMs = Date.now()) {
     const repos = [def.repo, ...(def.repos ?? []).map((x) => x.slug)].filter(Boolean);
     if (repos.length)
         console.log(`  ${chalk.dim('repos')}    ${[...new Set(repos)].join(' · ')}`);
+    // A def whose `repo` disagrees with the checkout's origin reads PR and release
+    // counts from a DIFFERENT repository — both slugs resolve, so nothing errors
+    // and the wrong numbers look right. Say it here, with the fix attached.
+    const mismatch = def.root ? checkRepoSlug(def, originSlug(expandLocalHome(def.root))) : undefined;
+    if (mismatch) {
+        console.log(`  ${chalk.yellow('!')}        ${chalk.yellow(mismatch.message)}`);
+        console.log(`  ${' '.repeat(8)}${chalk.gray(mismatch.remediation)}`);
+    }
     if (def.contexts?.length) {
         console.log(`  ${chalk.dim('context')}  ${def.contexts.map((c) => c.path).join(' · ')}`);
     }
@@ -381,17 +440,24 @@ export function registerProjectsCommands(program) {
     });
     // ---- show ----
     projects
-        .command('show <name>')
-        .description('Show a project definition, resolved paths, repos, contexts, and links.')
+        .command('view <name>')
+        .alias('show')
+        .description('Show a project definition, resolved paths, repos, contexts, links, and milestones.')
         .option('--json', 'Machine-readable output')
-        .action((name, opts) => {
+        .option('--no-remote', 'Skip the Linear lookup; definition only')
+        .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);
         }
+        // Every milestone the project declares, not just the next one — the whole
+        // point of opening ONE project is to see the shape of its plan.
+        const counts = opts.remote !== false && def.linear?.projectId
+            ? await fetchLinearProjectCounts(def.linear.projectId)
+            : undefined;
         if (opts.json) {
-            console.log(JSON.stringify(def, null, 2));
+            console.log(JSON.stringify({ ...def, linear: { ...def.linear, ...(counts ?? {}) } }, null, 2));
             return;
         }
         console.log(chalk.bold(def.name) + (def.description ? chalk.dim(`  — ${def.description}`) : ''));
@@ -410,6 +476,24 @@ export function registerProjectsCommands(program) {
             console.log(`  linear       ${def.linear.url ?? def.linear.projectId}`);
         for (const d of def.docs ?? [])
             console.log(`  doc          ${d}`);
+        if (counts) {
+            const staleNote = counts.stale ? chalk.dim('  (cached)') : '';
+            console.log(`  issues       ${counts.done}/${counts.total}${counts.truncated ? '+' : ''} done · ${counts.inProgress} in progress${staleNote}`);
+        }
+        const ms = counts?.milestones ?? [];
+        if (ms.length) {
+            console.log(`  ${chalk.bold('milestones')}`);
+            for (const m of ms) {
+                const mark = m.name === counts?.nextMilestone?.name ? chalk.cyan('next') : '';
+                console.log(`    ${mark.padEnd(6)}     ${formatNextMilestone(m, Date.now())}`);
+            }
+            // A milestone nothing is filed against cannot report progress. Say that
+            // once, plainly, rather than printing a row of silent 0%s.
+            const unfiled = ms.filter((m) => m.total === 0).length;
+            if (unfiled === ms.length) {
+                console.log(`    ${chalk.yellow('!')}          ${chalk.yellow(`no issues are assigned to any milestone — progress against them cannot be measured`)}`);
+            }
+        }
         console.log(chalk.gray(`  ${projectDefPath(name)}`));
     });
     // ---- edit ----
@@ -514,7 +598,8 @@ export function registerProjectsCommands(program) {
                     byStatus: r?.byStatus ?? {},
                     members: r?.members ?? [],
                     plan: r?.plan ?? { done: 0, total: 0 },
-                    planPct: r ? planPct(r.plan) ?? null : null,
+                    live: r ? liveDeadSplit(r.byStatus).live : 0,
+                    dead: r ? liveDeadSplit(r.byStatus).dead : 0,
                     openPrs: r?.openPrs ?? [],
                     mergedPrs: rem?.mergedPrs ?? 0,
                     latestRelease: rem?.latestRelease ?? null,
@@ -577,6 +662,53 @@ export function registerProjectsCommands(program) {
             console.log(chalk.gray('  (widen with --min-confidence medium or --all)'));
         }
     });
+    // ---- set ----
+    projects
+        .command('set <name>')
+        .description('Change one field on a project definition, preserving everything else.')
+        .option('--repo <owner/repo>', 'Primary GitHub slug')
+        .option('--root <path>', 'Repo / monorepo root')
+        .option('--path <subdir>', 'Default cwd for agents (a monorepo subdir)')
+        .option('--description <text>', 'One-line description shown on the card')
+        .action((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 fields = ['repo', 'root', 'path', 'description'].filter((k) => opts[k] !== undefined);
+        if (fields.length === 0) {
+            console.error(chalk.red('Nothing to set. Pass a field, e.g. --repo <owner/repo>.'));
+            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)
+            def.root = opts.root;
+        if (opts.description !== undefined)
+            def.description = opts.description;
+        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.`));
+                console.error(chalk.gray(`  Set one first: agents projects set ${def.name} --root <path> --path ${opts.path}`));
+                process.exit(1);
+            }
+            def.defaultPath = `${base}/${opts.path.replace(/^\//, '')}`;
+        }
+        writeProjectDef(def);
+        console.log(chalk.green(`Updated ${def.name}`));
+        for (const f of fields)
+            console.log(chalk.gray(`  ${f}  ${f === 'path' ? def.defaultPath : def[f]}`));
+    });
     // ---- link ----
     projects
         .command('link <name>')

package/dist/commands/routines.js

@@ -14,7 +14,7 @@ import { isDaemonRunning, signalDaemonReload, startDaemon, stopDaemon, readDaemo
 import { assertSchedulerEnabled } from '../lib/device-config.js';
 import { resolveAgentName, isAgentHardDeprecated, hardDeprecationError } from '../lib/agents.js';
 import { humanizeCron, humanizeNextRun, formatRepoLink, REPO_DISPLAY_MAX } from '../lib/routines-format.js';
-import { listJobs as listAllJobs, deleteJob, readJob, validateJob, writeJob, setJobEnabled, listRuns, getLatestRun, getRunDir, getJobPath, parseAtTime, hasCompletedOneShotRun, isOneShotLikeSchedule, isOneShotRoutine, isPastOneShotRoutine, jobRunsOnThisDevice, checkJobDeviceEligibility, normalizeTriggerEvent, parseHostStrategy, resolveHostStrategy, placementRequiresFiringPin, HOST_STRATEGIES, } from '../lib/routines.js';
+import { listJobs as listAllJobs, deleteJob, readJob, validateJob, writeJob, setJobEnabled, listRuns, routineStats, getLatestRun, getRunDir, getJobPath, parseAtTime, hasCompletedOneShotRun, isOneShotLikeSchedule, isOneShotRoutine, isPastOneShotRoutine, jobRunsOnThisDevice, checkJobDeviceEligibility, normalizeTriggerEvent, parseHostStrategy, resolveHostStrategy, placementRequiresFiringPin, HOST_STRATEGIES, } from '../lib/routines.js';
 import { discoverProjectRoutinesAt, enableProjectRoutines, disableProjectRoutines, syncProjectRoutines, syncAllProjectRoutines, listEnabledProjectRoots, resolveProjectRoot, displayProjectPath, listProjectRoutineFiles, } from '../lib/routines-project.js';
 import { fireWebhookJobs, matchJobsToWebhook } from '../lib/triggers/webhook.js';
 import { getRoutinesDir } from '../lib/state.js';
@@ -359,6 +359,7 @@ function runMetaJson(run) {
         completedAt: run.completedAt,
         exitCode: run.exitCode,
         errorMessage: run.errorMessage ?? null,
+        duration: run.duration ?? null,
     };
 }
 export function buildRunsJson(runs) {
@@ -1034,6 +1035,50 @@ export function registerRoutinesCommands(program) {
             console.log(`  ${run.runId}  ${status}  ${run.startedAt}`);
         }
     });
+    routinesCmd
+        .command('stats [name]')
+        .description('Duration + outcome rollup per job: run count, failed, missed, avg/p50/p95 duration')
+        .option('--json', 'Emit machine-readable JSON')
+        .action(async (name, options) => {
+        // No name: summarize every job (like `routines list`). A name narrows to
+        // one job's rollup — no interactive picker, since a bare `stats` already
+        // has a useful all-jobs default.
+        if (!name) {
+            const jobs = listAllJobs();
+            const rows = jobs.map((j) => ({ name: j.name, ...routineStats(j.name) }));
+            if (options.json) {
+                writeJson({ jobs: rows });
+                return;
+            }
+            if (rows.length === 0) {
+                console.log(chalk.gray('No jobs configured'));
+                return;
+            }
+            console.log(chalk.bold('Routine stats\n'));
+            const pad = (s, w) => (s.length >= w ? s.slice(0, w) : s + ' '.repeat(w - s.length));
+            console.log(chalk.gray(`  ${pad('JOB', 28)} ${pad('N', 5)} ${pad('FAILED', 7)} ${pad('MISSED', 7)} ${pad('AVG', 7)} ${pad('P50', 7)} P95`));
+            for (const r of rows) {
+                console.log(`  ${pad(r.name, 28)} ${pad(String(r.count), 5)} ${pad(String(r.failed), 7)} ${pad(String(r.missed), 7)} ${pad(`${r.avgMs}ms`, 7)} ${pad(`${r.p50}ms`, 7)} ${r.p95}ms`);
+            }
+            return;
+        }
+        const stats = routineStats(name);
+        if (options.json) {
+            writeJson({ jobId: name, name, ...stats });
+            return;
+        }
+        if (stats.count === 0) {
+            console.log(chalk.yellow(`No runs found for job '${name}'`));
+            return;
+        }
+        console.log(chalk.bold(`Stats: ${name}\n`));
+        console.log(`  Runs:     ${stats.count}`);
+        console.log(`  Failed:   ${stats.failed}`);
+        console.log(`  Missed:   ${stats.missed}`);
+        console.log(`  Avg:      ${stats.avgMs}ms`);
+        console.log(`  P50:      ${stats.p50}ms`);
+        console.log(`  P95:      ${stats.p95}ms`);
+    });
     routinesCmd
         .command('run [name]')
         .description('Execute a routine right now in the foreground. Ignores the schedule; useful for testing before enabling.')