@phnx-labs/agents-cli 1.20.92 → 1.20.93

package/CHANGELOG.md

@@ -1,5 +1,126 @@
 # Changelog
 
+## 1.20.93
+
+- **`agents send` is a real delivery envelope; `notify` is just `--to owner` (RUSH-2123).** Flag-first form: `--to`, `--text`, `--channel`, `--attach`, `--url`. `--to owner` expands from `notify.owner` in agents.yaml. Positional text still works. Help names the three planes (deliver / record / control) so send is not confused with `feed post`, `activity`, or `message`/`sessions inject`. Source: `apps/cli/src/commands/send.ts`, `apps/cli/src/lib/channels/send.ts`.
+
+- **`agents events emit` — record events produced outside the CLI.** In-process code
+  calls `emit()` directly, but the producers that most need to record events are not
+  agents-cli processes: the Factory VS Code extension host, shell guards, external
+  tools. They now pipe JSONL on stdin —
+  `… | agents events emit --source factory`. `--source` is stamped as `module`, so
+  `agents events --module factory` filters to one producer. Routing is forced by the
+  stores rather than chosen: a milestone kind requires a `sessionId` and lands in that
+  session's activity log, everything else lands in the operational log. A milestone
+  with no `sessionId` is rejected, not quietly written elsewhere. Rejection is per
+  line, so one bad line never discards a batch, and the exit code is 1 if any line was
+  rejected. `--dry-run` validates without writing.
+  Source: `apps/cli/src/lib/events-ingest.ts`, `apps/cli/src/commands/events.ts`,
+  `apps/cli/docs/06-observability.md`.
+
+- **Four `factory.*` event kinds.** `factory.command`, `factory.action`, `factory.uri`
+  and `factory.launch` describe what a user did in the Factory VS Code extension.
+  `factory.launch` is a milestone — it carries the `sessionId` and `terminalId` that
+  later events join through — and `factory.uri` is audit-level, since an external
+  process driving the user's editor is a "who reached in from outside" fact.
+  Source: `apps/cli/src/lib/events.ts`, `apps/cli/src/lib/activity.ts`.
+
+- **`emit()` accepts a caller-supplied timestamp.** A batched producer records when
+  each event *happened* and flushes later; without this, every event in a flush was
+  stamped at flush time, collapsing their order and corrupting `--since` boundaries.
+  `ts` stays reserved against payload injection — only the explicit override can set
+  it. Source: `apps/cli/src/lib/events.ts`.
+
+- **Fixed: `agents _internal friction` recorded its own invocation.** The command
+  exists precisely because shell guards run before any `agents` process exists and so
+  cannot emit in-process, but it still fired the `command.start` / `command.end` audit
+  hooks, writing two records on top of every friction record. Recorder commands are now
+  exempt. Source: `apps/cli/src/index.ts`.
+
+- **Desktop notifications now show the agent on the right, not a second copy of
+  the app icon.** macOS draws two images on a banner: the sending app's icon on
+  the left and `contentImage` on the right (a YouTube notification uses the slots
+  for "YouTube" plus the channel avatar). agents-cli was putting its own lime mark
+  in the right slot, so both slots said the same thing. The right slot now carries
+  the harness the notification is *about* — a brand-colored tile with a two-letter
+  mark (`CL` claude, `CX` codex, `GK` grok, …), two letters because four harnesses
+  start with `c` and two with `g`. `agents run --notify` and agent/workflow
+  routines pass their harness through; a daemon heal, an overdue sweep, a command
+  routine, or a fan-out across several agents has no single agent and leaves the
+  right slot empty. Source:
+  `apps/cli/menubar/Sources/MenubarHelper/AgentAvatar.swift`,
+  `apps/cli/src/lib/menubar/notify-desktop.ts`, `apps/cli/src/lib/run-notify.ts`,
+  `apps/cli/src/lib/routine-notify.ts`, `apps/cli/docs/menubar.md`.
+
+- **`MenubarHelper --notify` gains `--agent <id>`.** The one-shot notifier accepts
+  the harness id that drives the right-hand avatar; omitting it is how a caller
+  says "no single agent owns this event".
+
+- **`agents projects status --fleet` — per-device workspace drift (beta).**
+  Projects are natively multi-device; `--fleet` adds a `fleet` line to the status
+  card showing, for each project, whether its workspace repos are present on every
+  fleet device, on which branch, ahead/behind their upstream (`↑`/`↓`), and how
+  many uncommitted changes they carry — plus a hidden `agents projects probe
+  --json <path...>` subcommand that is the peer half of the fan-out. One parallel
+  SSH call per device (12s timeout), **no `git fetch`** — drift is measured
+  against each peer's last-fetched upstream, and a repo with no upstream reports
+  no drift rather than zero. Peers that are unreachable or run an older CLI are
+  named once in a trailing note; `probe` itself is not beta-gated so peers answer
+  whenever their binary carries it. The schema gains `repos[].path` (home-relative
+  local checkout) to opt additional repos into probing beyond the primary `root`,
+  and `--json` gains per-project `workspaces[]` with the host-tagged probe rows.
+  The card's `live` line also counts agents on every box under `--fleet` via the
+  existing sessions fan-out. Source: `apps/cli/src/lib/project-probe.ts`,
+  `apps/cli/src/commands/projects.ts`, `apps/cli/src/lib/projects.ts`.
+
+- **`agents projects` outcomes on the card — agent×project members, releases,
+  Linear counts, and `projects link --linear` (beta).** The status card gains an
+  `agents` line under `live` naming WHICH harness is on each project
+  (`claude · running · RUSH-2107 @zion`, sorted running-first, capped at 6 with a
+  `+N more` tail; under `--fleet` remote agents carry their peer's hostname), a
+  latest-release tag on the `ships` line (primary repo only, best-effort
+  `gh release list`), and a `linear` line counting the bound Linear project's
+  issues by state type (`12/30 done · 5 in progress`) — best-effort with an 8s
+  budget, skipped by `--no-remote`, and omitted when the def has no
+  `linear.projectId`. The new `agents projects link <name> --linear [query]`
+  writes that binding: no query auto-suggests from the def name + repo slug via
+  the normalized-key matcher (ported from Factory's `linearProjects.ts`),
+  ambiguous/none prints the candidate list and exits 1. `--json` gains
+  `members[]`, `latestRelease`, and `linear`. Source:
+  `apps/cli/src/lib/project-status.ts`, `apps/cli/src/lib/linear-projects.ts`,
+  `apps/cli/src/lib/linear-project-counts.ts`, `apps/cli/src/commands/projects.ts`.
+
+- **Project sync no longer spams a warning per file it left alone.** Syncing a
+  project whose `.claude/commands/` you wrote yourself printed one wrapped
+  `Skipping project resource target …: already exists and is user-owned` line
+  per file — six hand-authored commands meant twelve lines of terminal noise in
+  the middle of `agents view claude`. Those files are the normal steady state,
+  not a warning, so the sync now reports them once, grouped, in plain words:
+  `Kept 6 of your own files in .claude/commands: debug.md, doc-gaps.md,
+  image-nbp.md, +3 more`. The list also rides out on `SyncResult.projectSkipped`
+  for callers that want it. Source: `apps/cli/src/lib/project-resources.ts`.
+
+- **`agents secrets` now tracks per-bundle usage and surfaces it.** Every secret
+  lifecycle/access event — create, import, export, view, access (a value read for
+  injection), unlock — funnels through the one `emitSecretAudit` chokepoint, which
+  writes to BOTH the append-only `~/.agents/events.jsonl` audit log AND a derived,
+  value-free read-model at `~/.agents/secrets/secrets.db` (never a secret value —
+  bundle name, event kind, key count, resolving agent/host, status only).
+  `agents secrets view <bundle>` now shows whether the bundle is currently
+  **unlocked** (held by the secrets-agent, so reads are prompt-free), a **usage**
+  summary ("accessed 42× (last 2h ago) · exported 3× (last 1d ago)"), and
+  **per-agent** attribution, and nudges when a bundle has no description (also at
+  `create` time). `agents secrets list` gains **`--sort uses`** (most frequently
+  accessed) alongside the existing `--sort used`, and the `--json` payloads carry
+  `uses`, `usage`, and `heldExpiresAt`. A new **`agents secrets activity [bundle]`**
+  prints the recent value-free event timeline (bounded to 90 days). Naming guidance
+  is taught in the help and skill: name a website bundle after its domain
+  (`stripe.com`, `openai.ai`), a desktop-app bundle after its binary suffix
+  (`slack.app`, `photoshop.exe`). Recording is best-effort and
+  `AGENTS_NO_USAGE_TRACK=1` disables it. Source:
+  `apps/cli/src/lib/secrets/usage-db.ts`, `apps/cli/src/lib/secrets/audit.ts`,
+  `apps/cli/src/commands/secrets.ts`, `apps/cli/src/lib/secrets/list-filter.ts`.
+
 ## 1.20.92
 
 - **`agents sessions` rows show creation time as well as last activity (RUSH-2107).**

package/dist/commands/events.js

@@ -17,6 +17,8 @@ import chalk from 'chalk';
 import * as fs from 'fs';
 import { getLogsPath } from '../lib/events.js';
 import { readUnifiedEvents } from '../lib/event-stream.js';
+import { ingestBatch } from '../lib/events-ingest.js';
+import { setHelpSections } from '../lib/help.js';
 /**
  * Resolve `--limit` into a record cap. `0` means "no cap" — without it there is
  * no way to read the whole stream, and any aggregation (group-by failure, count
@@ -97,8 +99,93 @@ function renderRow(r) {
     const agent = r.agent ? chalk.gray(` ${r.agent}`) : '';
     return `${time}  ${originLabel(r).padEnd(24)} ${user.padEnd(22)} ${ev.padEnd(26)}${agent}  ${detailFor(r)}`;
 }
+/** Read all of stdin. Returns '' when nothing is piped. */
+async function readStdin() {
+    if (process.stdin.isTTY)
+        return '';
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString('utf-8');
+}
+function registerEmitSubcommand(events) {
+    const emitCmd = events
+        .command('emit')
+        .description('Record events produced outside this process (reads JSONL on stdin)')
+        .requiredOption('--source <name>', 'Producer name; stamped as `module` so `events --module <name>` filters to it')
+        .option('--dry-run', 'Validate and report without writing')
+        .option('--json', 'Report {written, rejected} as JSON')
+        .action(async (opts, cmd) => {
+        // The parent `events` command also declares `--json` (for its read view).
+        // Commander binds a flag declared on BOTH to the parent, so a bare
+        // `events emit … --json` lands on parent.opts().json and the child sees
+        // undefined — the human string would print where a caller expects JSON.
+        // Read both, same as `feed post`.
+        const wantJson = Boolean(opts?.json ?? cmd?.parent?.opts?.().json);
+        const input = await readStdin();
+        if (input.trim() === '') {
+            console.error('events emit: nothing on stdin — pipe one JSON object per line.');
+            process.exitCode = 1;
+            return;
+        }
+        let result;
+        try {
+            result = ingestBatch(input, { source: opts.source, dryRun: opts.dryRun });
+        }
+        catch (err) {
+            console.error(`events emit: ${err instanceof Error ? err.message : String(err)}`);
+            process.exitCode = 1;
+            return;
+        }
+        if (wantJson) {
+            console.log(JSON.stringify({ written: result.written, rejected: result.rejected, routed: result.routed }, null, 2));
+        }
+        else if (result.rejected.length === 0) {
+            console.log(`${result.written} event(s) recorded${opts.dryRun ? ' (dry run)' : ''}.`);
+        }
+        else {
+            console.log(`${result.written} event(s) recorded${opts.dryRun ? ' (dry run)' : ''}.`);
+            console.error(`rejected ${result.rejected.length} line(s):`);
+            for (const r of result.rejected)
+                console.error(`  line ${r.line}: ${r.reason}`);
+        }
+        // Valid siblings are already written; a non-zero exit reports that the
+        // batch was not fully accepted without pretending nothing landed.
+        if (result.rejected.length > 0)
+            process.exitCode = 1;
+    });
+    setHelpSections(emitCmd, {
+        examples: `
+      # 1. Produce one JSON object per line (this is the whole input format).
+      printf '%s\\n' '{"event":"factory.command","commandId":"agents.newClaude"}' \\
+        | agents events emit --source factory
+
+      # 2. Flush a batch and check what landed.
+      agents events emit --source factory --json < batch.jsonl
+
+      # 3. Read it back. --limit 0 matters whenever you aggregate.
+      agents events --module factory --limit 0 --json
+    `,
+        notes: `
+      \`event\` is required and must be a known kind. \`ts\` (ISO-8601) is optional
+      and defaults to now — pass it so a batched producer records when each event
+      HAPPENED rather than when it flushed.
+
+      Envelope keys: ts, sessionId, mailboxId, terminalId, launchId, tmuxPane,
+      host, runtime, agent, tool, detail, url, project, cwd. Any other key is
+      payload and passes through the usual redaction.
+
+      A milestone kind (e.g. factory.launch) REQUIRES a sessionId — the activity
+      log is one file per session. Milestones route there; everything else goes
+      to the operational log. \`agents events\` reads both.
+
+      Rejection is per line: one bad line never discards the batch. Exit is 1 if
+      any line was rejected.
+    `,
+    });
+}
 export function registerEventsCommand(program) {
-    program
+    const events = program
         .command('events')
         .description('Read the unified event stream (operational + agent activity)')
         .option('--module <name>', 'Only events from this group (e.g. teams, secrets, activity)')
@@ -166,6 +253,9 @@ Examples:
         if (truncated)
             console.log(chalk.yellow(capNote));
     });
+    // `events` both reads (its own action, above) and writes (this subcommand) —
+    // the same shape as `feed` / `feed post`.
+    registerEmitSubcommand(events);
 }
 /** commander repeatable-option collector. */
 function collect(value, previous) {

package/dist/commands/projects.d.ts

@@ -9,4 +9,14 @@
  * lifecycle state, plan completion, open PRs, and tickets in flight.
  */
 import type { Command } from 'commander';
+/** Recursion guard: a peer answering a probe fan-out never re-fans-out itself. */
+export declare const PROJECTS_NO_FANOUT_ENV = "AGENTS_PROJECTS_LOCAL";
+/**
+ * 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 declare function formatFleetSkippedNote(skipped: string[]): string;
 export declare function registerProjectsCommands(program: Command): void;

package/dist/commands/projects.js

@@ -16,10 +16,36 @@ 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, } from '../lib/project-status.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(':');
@@ -54,7 +80,7 @@ function statusBar(r) {
         parts.push(chalk.gray(`+${r.agents - shown} other`));
     return parts.join(' · ') || chalk.gray('no live agents');
 }
-function renderCard(def, r, remote) {
+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`)}`;
@@ -62,6 +88,8 @@ function renderCard(def, r, remote) {
     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)`));
@@ -69,11 +97,25 @@ function renderCard(def, r, remote) {
         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}`);
@@ -100,6 +142,8 @@ export function registerProjectsCommands(program) {
       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: `
@@ -107,9 +151,14 @@ export function registerProjectsCommands(program) {
       machines with 'agents push/pull'. Enable with: agents beta enable projects.
     `,
     });
-    projects.hook('preAction', () => {
+    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);
@@ -239,6 +288,7 @@ export function registerProjectsCommands(program) {
         .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
@@ -257,14 +307,57 @@ export function registerProjectsCommands(program) {
         }
         const windowDays = Math.max(1, Number.parseInt(opts.window ?? '7', 10) || 7);
         const nowMs = Date.now();
-        const roll = rollupSessionsByProject(all, await getActiveSessions());
+        // --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 call (def.repo left unused → mergedPrs stays 0).
+        // 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) => {
-            remote.set(d.name, await enrichProjectSignals(d, windowDays, nowMs, { skipRemote: opts.remote === false }));
+            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);
@@ -272,22 +365,39 @@ export function registerProjectsCommands(program) {
                     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));
+        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
@@ -341,6 +451,77 @@ export function registerProjectsCommands(program) {
         }
         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>')

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