@phnx-labs/agents-cli 1.20.91 → 1.20.93

package/dist/commands/projects.js

@@ -0,0 +1,539 @@
+/**
+ * `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. Beta-gated on
+ * `isBetaEnabled('projects')`, mirroring `agents factory`.
+ *
+ * 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 { execFileSync, spawnSync } from 'child_process';
+import { betaEnableHint, isBetaEnabled } from '../lib/beta.js';
+import { setHelpSections } from '../lib/help.js';
+import { getMainRepoRoot } from '../lib/git.js';
+import { parseOwnerRepoFromRemote } from '../lib/registry.js';
+import { toHomeRelative } from '../lib/project-root.js';
+import { machineId } from '../lib/machine-id.js';
+import { getActiveSessions } from '../lib/session/active.js';
+import { gatherRemoteActive } from '../lib/session/remote-active.js';
+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 { fetchLinearProjectCounts } from '../lib/linear-project-counts.js';
+import { listLinearProjects, pickLinearProject } from '../lib/linear-projects.js';
+/** Recursion guard: a peer answering a probe fan-out never re-fans-out itself. */
+export 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;
+/**
+ * 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 '';
+    const named = skipped.slice(0, SKIPPED_NAME_LIMIT);
+    const rest = skipped.length - named.length;
+    const list = rest > 0 ? `${named.join(', ')} +${rest}` : named.join(', ');
+    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`);
+}
+/** `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() };
+}
+/** Best-effort `owner/repo` from a repo's origin remote. */
+function originSlug(cwd) {
+    try {
+        const url = execFileSync('git', ['remote', 'get-url', 'origin'], { cwd, encoding: 'utf8' }).trim();
+        return parseOwnerRepoFromRemote(url) ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function statusBar(r) {
+    const parts = [];
+    const push = (n, label, color) => {
+        if (n && n > 0)
+            parts.push(color(`${n} ${label}`));
+    };
+    push(r.byStatus.running, 'running', chalk.green);
+    push(r.byStatus.idle, 'idle', chalk.gray);
+    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`));
+    return parts.join(' · ') || chalk.gray('no live agents');
+}
+function renderCard(def, r, remote, fleet, linear) {
+    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}`);
+    if (def.description)
+        console.log(`  ${chalk.dim(def.description)}`);
+    console.log(`  ${chalk.dim('live')}     ${r ? statusBar(r) : chalk.gray('no live agents')}`);
+    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 (r?.openPrs.length)
+        ships.push(`${r.openPrs.length} open PR${r.openPrs.length === 1 ? '' : 's'}`);
+    if (r?.worktrees)
+        ships.push(`${r.worktrees} worktree${r.worktrees === 1 ? '' : 's'}`);
+    if (remote?.latestRelease)
+        ships.push(remote.latestRelease.tag);
+    if (ships.length)
+        console.log(`  ${chalk.dim('ships')}    ${ships.join(' · ')}`);
+    if (linear) {
+        console.log(`  ${chalk.dim('linear')}   ${linear.done}/${linear.total}${linear.truncated ? '+' : ''} done · ${linear.inProgress} in progress`);
+    }
+    if (r && r.tickets.length) {
+        console.log(`  ${chalk.dim('tickets')}  ${r.tickets.slice(0, 8).join(' · ')}${r.tickets.length > 8 ? ' …' : ''}`);
+    }
+    if (fleet) {
+        const lines = formatFleetWorkspaces(fleet);
+        if (lines.length === 0) {
+            console.log(`  ${chalk.dim('fleet')}    ${chalk.gray('no workspace paths (set root or repos[].path)')}`);
+        }
+        lines.forEach((line, i) => {
+            console.log(`  ${chalk.dim((i === 0 ? 'fleet' : '').padEnd(5))}    ${line}`);
+        });
+    }
+    if (remote?.artifacts) {
+        const last = remote.lastArtifact ? `  ${chalk.dim(`· last: ${remote.lastArtifact}`)}` : '';
+        console.log(`  ${chalk.dim('proof')}    ${remote.artifacts} artifact${remote.artifacts === 1 ? '' : 's'} (${remote.windowDays}d)${last}`);
+    }
+    const repos = [def.repo, ...(def.repos ?? []).map((x) => x.slug)].filter(Boolean);
+    if (repos.length)
+        console.log(`  ${chalk.dim('repos')}    ${[...new Set(repos)].join(' · ')}`);
+    if (def.contexts?.length) {
+        console.log(`  ${chalk.dim('context')}  ${def.contexts.map((c) => c.path).join(' · ')}`);
+    }
+    if (def.integrations?.length) {
+        console.log(`  ${chalk.dim('links')}    ${def.integrations.map((i) => i.label ?? i.kind).join(' · ')}`);
+    }
+    console.log('');
+}
+export function registerProjectsCommands(program) {
+    const enabled = isBetaEnabled('projects');
+    const projects = program
+        .command('projects', { hidden: !enabled })
+        .description('Named multi-repo projects with a progress rollup.');
+    setHelpSections(projects, {
+        examples: `
+      agents projects add rush --repo phnx-labs/rush --path apps/web
+      agents projects list
+      agents projects status              # progress card for every project
+      agents projects status rush --json  # one project, machine-readable
+      agents projects status --fleet      # + per-device workspace drift over SSH
+      agents projects link rush --linear  # bind the Linear project (auto-suggest)
+      agents run --project rush           # land an agent in the project
+    `,
+        notes: `
+      Definitions are hand-editable YAML in ~/.agents/projects/ and sync across
+      machines with 'agents push/pull'. Enable with: agents beta enable projects.
+    `,
+    });
+    projects.hook('preAction', (_thisCommand, actionCommand) => {
+        if (enabled)
+            return;
+        // `probe` is the peer half of `status --fleet`: it must answer whenever the
+        // binary carries it, even where the beta flag is off — a gated peer would
+        // look unreachable to every fleet member on a newer CLI.
+        if (actionCommand.name() === 'probe')
+            return;
+        console.error(chalk.red('agents projects is in beta.'));
+        console.error(chalk.gray(betaEnableHint('projects')));
+        process.exit(1);
+    });
+    // ---- list ----
+    projects
+        .command('list')
+        .description('List defined projects with their root, repo, and live agent count.')
+        .option('--json', 'Machine-readable output')
+        .action(async (opts) => {
+        const defs = listProjectDefs();
+        if (opts.json) {
+            const roll = rollupSessionsByProject(defs, await getActiveSessions());
+            console.log(JSON.stringify(defs.map((d) => ({ ...d, agents: roll.get(d.name)?.agents ?? 0 })), null, 2));
+            return;
+        }
+        if (!defs.length) {
+            console.log(chalk.gray('No projects defined. Add one: agents projects add <name>'));
+            return;
+        }
+        const roll = rollupSessionsByProject(defs, await getActiveSessions());
+        for (const d of defs) {
+            const agents = roll.get(d.name)?.agents ?? 0;
+            const repo = d.repo ?? d.repos?.[0]?.slug ?? '';
+            console.log(`  ${chalk.bold(d.name.padEnd(16))} ${chalk.dim((d.root ?? d.defaultPath ?? '').padEnd(32))} ${chalk.cyan(repo.padEnd(24))} ${agents} agents`);
+        }
+    });
+    // ---- add ----
+    projects
+        .command('add <name>')
+        .description('Define a project. Infers root and repo from the current git repo when not given.')
+        .option('--root <path>', 'Repo / monorepo root (defaults to the current git repo root)')
+        .option('--path <subdir>', 'Default cwd for agents (a monorepo subdir)')
+        .option('--repo <owner/repo>', 'Primary GitHub slug (defaults to the origin remote)')
+        .option('--context <path:purpose...>', 'A described starting point; repeatable')
+        .option('--linear <url-or-id>', 'Linear project URL or id')
+        .option('--force', 'Overwrite an existing definition')
+        .action(async (name, opts) => {
+        if (!isSafeProjectName(name)) {
+            console.error(chalk.red(`Invalid project name: "${name}" (letters, digits, ., _, - only)`));
+            process.exit(1);
+        }
+        if (loadProjectDef(name) && !opts.force) {
+            console.error(chalk.red(`Project "${name}" already exists. Use --force to overwrite, or 'agents projects edit ${name}'.`));
+            process.exit(1);
+        }
+        const cwd = process.cwd();
+        let root = opts.root;
+        if (!root) {
+            try {
+                root = toHomeRelative(await getMainRepoRoot(cwd));
+            }
+            catch {
+                console.error(chalk.red('Not inside a git repo — pass --root <path> explicitly.'));
+                process.exit(1);
+            }
+        }
+        const repo = opts.repo ?? originSlug(cwd);
+        const def = { name, root };
+        if (opts.path)
+            def.defaultPath = `${root.replace(/\/$/, '')}/${opts.path.replace(/^\//, '')}`;
+        if (repo)
+            def.repo = repo;
+        if (opts.context?.length)
+            def.contexts = opts.context.map(parseContextFlag);
+        if (opts.linear) {
+            def.linear = /^https?:/.test(opts.linear) ? { url: opts.linear } : { projectId: opts.linear };
+        }
+        const target = writeProjectDef(def);
+        console.log(chalk.green(`Defined project "${name}"`));
+        console.log(chalk.gray(`  ${target}`));
+        console.log(chalk.gray(`  root ${def.root}${def.repo ? `  ·  repo ${def.repo}` : ''}`));
+    });
+    // ---- show ----
+    projects
+        .command('show <name>')
+        .description('Show a project definition, resolved paths, repos, contexts, and links.')
+        .option('--json', 'Machine-readable output')
+        .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);
+        }
+        if (opts.json) {
+            console.log(JSON.stringify(def, null, 2));
+            return;
+        }
+        console.log(chalk.bold(def.name) + (def.description ? chalk.dim(`  — ${def.description}`) : ''));
+        if (def.root)
+            console.log(`  root         ${def.root}`);
+        if (def.defaultPath)
+            console.log(`  defaultPath  ${def.defaultPath}`);
+        const repos = [def.repo, ...(def.repos ?? []).map((r) => (r.subpath ? `${r.slug} (${r.subpath})` : r.slug))].filter(Boolean);
+        if (repos.length)
+            console.log(`  repos        ${repos.join(', ')}`);
+        for (const c of def.contexts ?? [])
+            console.log(`  context      ${chalk.cyan(c.path)} — ${c.purpose}`);
+        for (const i of def.integrations ?? [])
+            console.log(`  ${i.kind.padEnd(12)} ${i.url}${i.label ? chalk.dim(`  (${i.label})`) : ''}`);
+        if (def.linear?.url || def.linear?.projectId)
+            console.log(`  linear       ${def.linear.url ?? def.linear.projectId}`);
+        for (const d of def.docs ?? [])
+            console.log(`  doc          ${d}`);
+        console.log(chalk.gray(`  ${projectDefPath(name)}`));
+    });
+    // ---- edit ----
+    projects
+        .command('edit <name>')
+        .description('Open the project YAML in $EDITOR (it is hand-editable regardless).')
+        .action((name) => {
+        const target = projectDefPath(name);
+        if (!fs.existsSync(target)) {
+            console.error(chalk.red(`No project named "${name}". Create it: agents projects add ${name}`));
+            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);
+    });
+    // ---- status ----
+    projects
+        .command('status [name]')
+        .description('Progress rollup: agents, plan %, merged/open PRs, tickets, and artifacts per project.')
+        .option('--json', 'Machine-readable output')
+        .option('--window <days>', 'Window for merged PRs and artifacts', '7')
+        .option('--no-remote', 'Skip the GitHub lookup (merged-PR count); faster, offline')
+        .option('--fleet', 'Also dial every fleet device for workspace presence, branch, and drift (one SSH per peer)')
+        .action(async (name, opts) => {
+        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(`No project named "${name}".`));
+            process.exit(1);
+        }
+        if (!defs.length) {
+            if (opts.json)
+                console.log('[]');
+            else
+                console.log(chalk.gray('No projects defined. Add one: agents projects add <name>'));
+            return;
+        }
+        const windowDays = Math.max(1, Number.parseInt(opts.window ?? '7', 10) || 7);
+        const nowMs = Date.now();
+        // --fleet: 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 whole fleet via the existing sessions
+        // fan-out. Both are opt-in — they dial the fleet.
+        const fleetTargets = opts.fleet ? [...new Set(defs.flatMap(workspaceTargetsForDef))] : [];
+        let fleetWs = [];
+        let fleetSkipped = [];
+        let fleetSessions = [];
+        if (opts.fleet) {
+            const self = machineId();
+            fleetWs.push(...probeProjectWorkspaces(fleetTargets).map((s) => ({ ...s, host: self })));
+            const [probeRes, activeRes] = await Promise.all([
+                fleetTargets.length > 0
+                    ? gatherRemoteAgentsJson({
+                        args: ['projects', 'probe', '--json', ...fleetTargets],
+                        noFanoutEnv: PROJECTS_NO_FANOUT_ENV,
+                        parse: parseRemoteProbe,
+                        quiet: true,
+                    })
+                    : Promise.resolve({ items: [], deviceCount: 0, skipped: [] }),
+                gatherRemoteActive(undefined, { quiet: true }),
+            ]);
+            fleetWs.push(...probeRes.items);
+            fleetSkipped = probeRes.skipped;
+            fleetSessions = activeRes.sessions;
+        }
+        const roll = rollupSessionsByProject(all, [...await getActiveSessions(), ...fleetSessions]);
+        // Enrich only the shown projects. --no-remote still reads the local artifact
+        // log but skips the gh calls + Linear counts (both are network).
+        const remote = new Map();
+        const linear = new Map();
+        await Promise.all(defs.map(async (d) => {
+            const skipRemote = opts.remote === false;
+            const [sig, counts] = await Promise.all([
+                enrichProjectSignals(d, windowDays, nowMs, { skipRemote }),
+                !skipRemote && d.linear?.projectId
+                    ? fetchLinearProjectCounts(d.linear.projectId)
+                    : Promise.resolve(undefined),
+            ]);
+            remote.set(d.name, sig);
+            if (counts)
+                linear.set(d.name, counts);
+        }));
+        /** 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));
+        };
+        if (opts.json) {
+            if (fleetSkipped.length > 0)
+                process.stderr.write(formatFleetSkippedNote(fleetSkipped));
+            console.log(JSON.stringify(defs.map((d) => {
+                const r = roll.get(d.name);
+                const rem = remote.get(d.name);
+                return {
+                    name: d.name,
+                    agents: r?.agents ?? 0,
+                    byStatus: r?.byStatus ?? {},
+                    members: r?.members ?? [],
+                    plan: r?.plan ?? { done: 0, total: 0 },
+                    planPct: r ? planPct(r.plan) ?? null : null,
+                    openPrs: r?.openPrs ?? [],
+                    mergedPrs: rem?.mergedPrs ?? 0,
+                    latestRelease: rem?.latestRelease ?? null,
+                    linear: linear.get(d.name) ?? null,
+                    tickets: r?.tickets ?? [],
+                    worktrees: r?.worktrees ?? 0,
+                    artifacts: rem?.artifacts ?? 0,
+                    lastArtifact: rem?.lastArtifact ?? null,
+                    windowDays,
+                    repos: [d.repo, ...(d.repos ?? []).map((r2) => r2.slug)].filter(Boolean),
+                    ...(opts.fleet ? { workspaces: fleetFor(d) } : {}),
+                };
+            }), null, 2));
+            return;
+        }
+        for (const d of defs) {
+            renderCard(d, roll.get(d.name), remote.get(d.name), opts.fleet ? fleetFor(d) : undefined, linear.get(d.name));
+        }
+        if (fleetSkipped.length > 0)
+            process.stdout.write(formatFleetSkippedNote(fleetSkipped));
+    });
+    // ---- 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.')
+        .option('--json', 'Machine-readable output (the only output format)')
+        .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));
+    });
+    // ---- import ----
+    projects
+        .command('import')
+        .description('Absorb the Factory project registry (~/.agents/factory/projects.json) into YAML definitions.')
+        .requiredOption('--from-factory', 'Import from the Factory projects.json registry')
+        .option('--force', 'Overwrite existing definitions')
+        .action((opts) => {
+        const src = factoryProjectsPath();
+        let rawText;
+        try {
+            rawText = fs.readFileSync(src, 'utf8');
+        }
+        catch {
+            console.error(chalk.red(`No Factory registry at ${src}`));
+            process.exit(1);
+        }
+        let rows;
+        try {
+            rows = JSON.parse(rawText);
+        }
+        catch {
+            console.error(chalk.red(`Factory registry at ${src} is not valid JSON`));
+            process.exit(1);
+        }
+        const list = Array.isArray(rows) ? rows : Array.isArray(rows.projects) ? rows.projects : [];
+        let created = 0;
+        let skipped = 0;
+        for (const raw of list) {
+            if (!raw || typeof raw !== 'object')
+                continue;
+            const o = raw;
+            const name = typeof o.name === 'string' ? o.name : undefined;
+            if (!name || !isSafeProjectName(name)) {
+                skipped++;
+                continue;
+            }
+            if (loadProjectDef(name) && !opts.force) {
+                skipped++;
+                continue;
+            }
+            const def = { name };
+            if (typeof o.path === 'string')
+                def.root = toHomeRelative(o.path);
+            if (typeof o.repoSlug === 'string')
+                def.repo = o.repoSlug;
+            if (typeof o.linearProjectId === 'string')
+                def.linear = { projectId: o.linearProjectId };
+            writeProjectDef(def);
+            created++;
+        }
+        console.log(chalk.green(`Imported ${created} project${created === 1 ? '' : 's'}${skipped ? chalk.gray(` (${skipped} skipped)`) : ''}`));
+    });
+    // ---- link ----
+    projects
+        .command('link <name>')
+        .description('Attach an external tracker to a project definition (writes linear.projectId into the YAML).')
+        .option('--linear [query]', 'Bind a Linear project by exact name or id; no value auto-suggests from the def name + repo')
+        .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);
+        }
+        if (opts.linear === undefined) {
+            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();
+        }
+        catch (e) {
+            console.error(chalk.red(e instanceof Error ? e.message : String(e)));
+            process.exit(1);
+        }
+        const query = typeof opts.linear === 'string' ? opts.linear.trim() : '';
+        let pick;
+        if (query) {
+            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);
+                if (d.kind === 'match') {
+                    pick = d;
+                    break;
+                }
+                if (pick.kind === 'none')
+                    pick = d;
+            }
+        }
+        if (pick.kind !== 'match') {
+            if (pick.kind === 'candidates') {
+                console.error(chalk.yellow(`No confident Linear match${query ? ` for "${query}"` : ` for "${def.name}"`}. Candidates:`));
+                for (const c of pick.projects)
+                    console.error(`  ${chalk.cyan(c.id)}  ${c.name}`);
+            }
+            else {
+                console.error(chalk.yellow(`No Linear project matches${query ? ` "${query}"` : ` "${def.name}"`}. Available:`));
+                for (const c of list)
+                    console.error(`  ${chalk.cyan(c.id)}  ${c.name}`);
+            }
+            console.error(chalk.gray(`Re-run with an explicit name or id: agents projects link ${name} --linear "<name-or-id>"`));
+            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})`));
+        }
+        def.linear = { ...def.linear, projectId: p.id };
+        if (p.url)
+            def.linear.url = p.url;
+        writeProjectDef(def);
+        console.log(chalk.green(`${def.name} → Linear project "${p.name}" (${p.id})${p.url ? ` ${p.url}` : ''}`));
+    });
+    // ---- rm ----
+    projects
+        .command('rm <name>')
+        .alias('remove')
+        .description('Delete a project definition. Never touches the repo.')
+        .action((name) => {
+        if (removeProjectDef(name)) {
+            console.log(chalk.green(`Removed project "${name}"`));
+        }
+        else {
+            console.error(chalk.red(`No project named "${name}".`));
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/secrets.d.ts

@@ -10,6 +10,7 @@ import { SSH_TARGET_RE, assertValidSshTarget } from '../lib/ssh-exec.js';
 import { quoteWin32ExecArg } from '../lib/platform/index.js';
 import { type SecretsBackend, type SecretsBundle, type SecretsPolicy } from '../lib/secrets/bundles.js';
 import { type SecretsListFilterOpts } from '../lib/secrets/list-filter.js';
+import { type BundleUsageSummary } from '../lib/secrets/usage-db.js';
 /** Read all available data from stdin synchronously, trimmed. */
 /**
  * Read the raw `.env` text for `import --from <path|->`. A `-` reads the .env
@@ -125,6 +126,22 @@ export declare function formatHoldWindow(ms: number): string;
  * shared by the POLICY column, the `--held` filter, and the JSON payload, so the
  * three can never disagree about the same bundle. */
 export declare function liveHold(expiresAt: number | undefined, now?: number): number | null;
+/**
+ * Compact one-line usage summary for `secrets view` — each recorded event with
+ * its count and how long ago it last happened ("accessed 42× (last 2h ago) ·
+ * exported 3× (last 1d ago)"). Empty string when nothing has been recorded yet.
+ * Pure — unit-tested.
+ */
+export declare function formatUsageLine(summary: BundleUsageSummary | undefined): string;
+/**
+ * The held-state line for `secrets view`: whether the secrets-agent currently
+ * holds this bundle (so reads are prompt-free) and for how long, or that Touch
+ * ID is required on the next read. Only meaningful for keychain bundles on macOS
+ * — file/vault backends have no broker to hold, and a `never`-policy bundle is
+ * always readable — so both return an empty line and the caller skips it.
+ * `heldExpiresAt` is the max expiry across every held scope.
+ */
+export declare function renderViewStatusLine(b: SecretsBundle, heldExpiresAt: number | null): string;
 /**
  * The EXPIRING cell. Counts keys needing attention — already expired plus due
  * within 30 days — and colours by the worst of the two: red once anything has