@phnx-labs/agents-cli 1.20.25 → 1.20.27

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 ## Unreleased
 
+**`agents sessions --host <machine>`: query a remote machine's sessions live over SSH**
+
+- `agents sessions "<query>" --host <alias|user@host>` runs the same session query on a remote machine's own index over SSH and streams the result back — repeat `--host` (or pass several) to fan out across machines. SSH access is the only auth; there's no daemon or shared store. Targets are validated against a strict allowlist (`SSH_TARGET_RE`) to block flag-smuggling, and the forwarded invocation is double-quoted (`shellQuote`) so a query like `$(whoami)` survives as a literal string on both shell layers. Source: `src/lib/session/remote.ts`, `src/commands/sessions.ts`, `docs/05-sessions.md`.
+
+**Fix: migrations + menu-bar self-heal were silently disabled on Homebrew-node installs**
+
+- The "is this a dev build?" check walked `dirname(dirname(argv[1]))` looking for a `.git`, without resolving the bin symlink. On a Homebrew-node setup `agents` is `/opt/homebrew/bin/agents`, so it walked up to `/opt/homebrew` — **which is itself a git repo** — and false-positived as a dev build. Dev builds auto-set `AGENTS_SKIP_MIGRATION=1`, which gates **both** one-shot migrations **and** the menu-bar upgrade self-heal. Net effect: every Homebrew-node user ran with migrations and the menu-bar refresh permanently off.
+- Detection now `realpath`s the entrypoint (so a symlinked bin resolves into the real package dir) and requires the `.git`'s repo root to actually be the `@phnx-labs/agents-cli` package — an unrelated ancestor repo no longer counts. Extracted to `src/lib/startup/dev-build.ts` with tests covering the Homebrew symlink layout, a real checkout, and unrelated-ancestor cases.
+
+**Secrets default policy is now `daily` (one Touch ID per ~24h), not `always`**
+
+- The default prompt policy for bundles without an explicit one flipped from `always` (Touch ID on *every* read) to **`daily`** (one prompt, then held ~24h until screen-lock / sleep / logout). This is the fix for the prompt storm: a background reader like sessions-sync hammering a bundle now costs one Touch ID per ~24h instead of one per read.
+- **Auto-cache is on by default.** The secrets-agent is the mechanism that delivers the daily policy, so it self-caches a `daily` bundle on first read with no `secrets.agent.auto: true` needed. Opt out with `secrets.agent.auto: false`.
+- **Configurable, still flexible.** Set the global default in `agents.yaml` (`secrets.policy: always` to restore prompt-every-time), or override per bundle with `agents secrets policy <bundle> always` for high-value keys (signing, SSH) you want to confirm on every read.
+- **Explicit `always` now persists** under the legacy `tier: biometry` token (older CLIs read it as their own always default). Bundles with no stored policy inherit the configured default — so an existing always-by-default bundle quietly becomes `daily` on first read by the new CLI, which is the intended migration.
+
+**Menu bar: a macOS status item for agent activity (`agents menubar`)**
+
+- New no-Dock menu bar app showing live agent activity on the machine: a **NEEDS YOU** section (sessions awaiting input + failed/overdue routines), a per-agent **roster** (running / idle counts across installed agents), a **+ New session** launcher, and a one-line routines summary. The icon badges red `!` when something needs you, green with a count when sessions are running.
+- Reads state **directly from disk** — `live-terminals.json`, teams `meta.json`, and the cloud `tasks.db` — so opening the menu never triggers the costly sessions transcript re-index. The CLI is shelled only for actions (start a session, run a routine).
+- **Auto-enabled on macOS** for every user as a launchd login service (`com.phnx-labs.agents-menubar`); a fresh install brings the icon up with no manual step. Manage with `agents menubar enable | disable | status`. Opt out with `agents menubar disable` — sticky across upgrades.
+- **Upgrade self-heal:** the installed bundle is version-stamped, and the startup self-heal now re-installs the helper when a newer release ships a newer build (or the installed copy goes missing), instead of skipping whenever a service already existed. So `npm update` actually moves users onto the new helper binary + plist rather than leaving the old one running (#442). `agents menubar status` shows installed vs current version and staleness.
+- Docs: [Menu bar](docs/menubar.md). macOS only.
+
+**`agents repos view [name]`: inspect one repo's contents without opening it**
+
+- New `agents repo view <name>` (also reachable as `agents repos view`, now a first-class alias of the `repo` command) prints a single repo's git state and per-kind resource counts — `system`, `user`, `project`, or an extra-repo alias. Omit the name for an interactive picker over the registered repos. It reuses the `inspect` repo renderer, so output matches `agents inspect <repo>`; supports `--brief` and `--json`. Source: `src/commands/repo.ts`, `src/commands/inspect.ts`.
+
+**`agents doctor --fix` + a daemon safety check: heal the gap between defined and installed**
+
+- Root cause behind "a plugin/command silently vanished": a DotAgents repo can DEFINE a resource that never makes it into an agent home, and nothing closes the gap. Two concrete failure modes — (1) `agents plugins update`/`sync` only reconcile each agent's **default** version, so a non-default installed version keeps serving stale/invalid resources; (2) a plugin.json with a bare-name `skills`/`commands` field makes Claude Code **silently reject the entire plugin**, and the sync path only *warned*. The detection (`agents doctor`'s live-home diff) and the healing (`syncResourcesToVersion`) existed but were never wired together — and the sync fast-guard keyed off the staleness manifest, which is blind to home-side rot.
+- **`agents doctor --fix`** turns the read-only diagnosis into a heal: installs missing resources, repairs Claude-invalid plugin manifests (strips the bare `skills`/`commands` field — Claude auto-discovers from the dirs), fast-forwards stale plugins from their `.source`, and reconciles drift — across **every installed version**, not just defaults. With no target it heals the whole install; `agents doctor <agent> --fix` scopes to one.
+- **Daemon safety check:** the routines daemon now runs the same heal in conservative `safe` mode (~every 6h + ~30s after start) — it fixes only unambiguous gaps (missing resources, invalid manifests, *provably-unmodified* stale plugins) and **notifies rather than clobbers** on hand-edited content or a plugin it can't prove is pristine.
+- Built on the **live-home diff**, not the staleness manifest, so it catches drift the sync fast-guard can't. Heal **fills and fixes, never deletes** (orphans stay `agents prune cleanup`'s job), excludes the project layer (the global home isn't reconciled against per-cwd project resources), and **verifies after writing** — it only claims resources that actually reconciled, so repeated runs converge instead of "fixing" the same item forever.
+- `.source` now records the plugin version at pull time, a baseline that lets the safe path tell an untouched mirror (fast-forward) from a user edit (leave alone).
+- **`agents doctor` overview now covers every installed version, not just defaults.** Sync status and orphans previously reported only each agent's default version — so a stale NON-default version (the exact rot `--fix` heals) was invisible in the readout. Each version is now listed with its default marked. The **Agent CLIs** list also stops nagging: it shows the agents you actually run (ready, or managed-but-broken) and collapses the rest of the supported catalog to a single `+N more supported …` hint instead of a column of red "not installed" lines for tools you never adopted.
+
 **Secrets prompt policy: human-readable `always` / `daily`, and `secrets list` now shows it**
 
 - Renamed the secrets-agent `tier` to a **prompt policy** with plain-language names: `biometry` → **`always`** (ask every time), `session` → **`daily`** (ask once, then held ~24h until screen-lock / sleep / logout). The old name `session` was misleading — it never meant "once per login session" — and collided with the half-dozen other "session" concepts in the CLI (`agents sessions`, sessions-sync, pty/browser sessions). Set it with `agents secrets policy <bundle> [always|daily]`.

package/dist/commands/doctor.d.ts

@@ -15,8 +15,11 @@
  *      unified diff body for each divergent file. Mirrors the resolution that
  *      the shim drives at runtime: project > user > system > extras.
  *
- * Read-only: doctor never mutates state. Run `agents prune cleanup` to act on orphan
- * readouts, or just launch the agent to apply pending sync.
+ * Read-only by default: doctor diagnoses, it doesn't mutate. Pass `--fix` to
+ * heal the gaps it finds (install missing resources, repair Claude-invalid
+ * plugin manifests, refresh stale plugins, reconcile drift). Run
+ * `agents prune cleanup` to act on orphan readouts, or just launch the agent to
+ * apply pending sync.
  */
 import type { Command } from 'commander';
 export declare function registerDoctorCommand(program: Command): void;

package/dist/commands/doctor.js

@@ -10,22 +10,25 @@ import { diffVersionResources, DOCTOR_ALL_KINDS, } from '../lib/doctor-diff.js';
 import { unifiedDiff, colorizeUnifiedDiff } from '../lib/diff-text.js';
 import { listCliStatus } from '../lib/cli-resources.js';
 import { setHelpSections } from '../lib/help.js';
+import { heal, healChangedAnything } from '../lib/heal.js';
 import * as fs from 'fs';
 const AGENT_NAMES = Object.fromEntries(ALL_AGENT_IDS.map((id) => [id, AGENTS[id].name]));
 // ─── overview mode (no target) ────────────────────────────────────────────────
 function checkSyncStatus(cwd) {
     const rows = [];
+    // Every installed version, not just the default — a stale NON-default version
+    // (e.g. one you launched from yesterday) is exactly the rot that silently
+    // serves outdated/invalid resources and that `--fix` now heals. Hiding it here
+    // is why that class of bug went unnoticed.
     for (const agent of ALL_AGENT_IDS) {
-        const version = getGlobalDefault(agent);
-        if (!version)
-            continue;
-        const manifest = loadManifest(agent, version);
-        if (!manifest) {
-            rows.push({ agent, version, status: 'never-synced' });
-            continue;
+        const def = getGlobalDefault(agent);
+        for (const version of listInstalledVersions(agent)) {
+            const manifest = loadManifest(agent, version);
+            const status = !manifest
+                ? 'never-synced'
+                : isStale(manifest, agent, version, cwd) ? 'stale' : 'fresh';
+            rows.push({ agent, version, status, isDefault: version === def });
         }
-        const stale = isStale(manifest, agent, version, cwd);
-        rows.push({ agent, version, status: stale ? 'stale' : 'fresh' });
     }
     return rows;
 }
@@ -41,15 +44,11 @@ function countOrphans() {
         return row;
     };
     for (const { agent, version } of iterCommandsCapableVersions()) {
-        if (version !== getGlobalDefault(agent))
-            continue;
         const diff = diffVersionCommands(agent, version);
         if (diff.orphans.length > 0)
             ensure(agent, version).commands = diff.orphans.length;
     }
     for (const { agent, version } of iterSkillsCapableVersions()) {
-        if (version !== getGlobalDefault(agent))
-            continue;
         const diff = diffVersionSkills(agent, version);
         if (diff.orphans.length > 0)
             ensure(agent, version).skills = diff.orphans.length;
@@ -59,8 +58,6 @@ function countOrphans() {
     // never fire. (Distinct from the source-diff `diffVersionHooks().orphans`,
     // which false-flags valid system-sourced registered hooks.)
     for (const { agent, version } of iterHooksCapableVersions()) {
-        if (version !== getGlobalDefault(agent))
-            continue;
         const dead = listUnmanagedHooksInVersionHome(agent, version);
         if (dead.length > 0)
             ensure(agent, version).hooks = dead.length;
@@ -69,28 +66,40 @@ function countOrphans() {
 }
 function renderOverviewText(clis, syncRows, orphanRows, hostClis) {
     console.log(chalk.bold('Agent CLIs'));
-    if (Object.keys(clis).length === 0) {
-        console.log(chalk.gray('  (no agents reported)'));
+    // Show the fleet you actually run — agents that are ready in PATH, plus any
+    // you MANAGE (have installed versions) whose binary isn't resolving (a real
+    // problem). The other supported-but-unadopted agents collapse to one hint line
+    // instead of a column of red "not installed" nags for tools you never wanted.
+    const managed = new Set(ALL_AGENT_IDS.filter((a) => listInstalledVersions(a).length > 0));
+    const entries = Object.entries(clis);
+    const shown = entries.filter(([name, e]) => e.installed || managed.has(name));
+    const hidden = entries.filter(([name, e]) => !e.installed && !managed.has(name)).map(([name]) => name);
+    if (shown.length === 0) {
+        console.log(chalk.gray('  (none installed — `agents add <name>` to start)'));
     }
     else {
-        for (const [name, entry] of Object.entries(clis)) {
-            const pretty = AGENT_NAMES[name] || name;
+        for (const [name, entry] of shown) {
+            const pretty = (AGENT_NAMES[name] || name).padEnd(11);
             if (entry.installed) {
-                console.log(`  ${chalk.green('ready')}  ${pretty.padEnd(10)} ${chalk.gray(entry.path || '')}`);
+                console.log(`  ${chalk.green('ready')}  ${pretty} ${chalk.gray(entry.path || '')}`);
             }
             else {
-                console.log(`  ${chalk.red('no   ')}  ${pretty.padEnd(10)} ${chalk.gray(entry.error || 'not installed')}`);
+                console.log(`  ${chalk.red('no   ')}  ${pretty} ${chalk.gray(entry.error || 'not installed')}`);
             }
         }
     }
+    if (hidden.length > 0) {
+        console.log(chalk.gray(`  +${hidden.length} more supported (${hidden.join(', ')}) — \`agents add <name>\` to manage`));
+    }
     console.log();
-    console.log(chalk.bold('Sync status (default versions)'));
+    console.log(chalk.bold('Sync status (installed versions)'));
     if (syncRows.length === 0) {
-        console.log(chalk.gray('  (no default versions set; pin one with `agents use <agent>@<version>`)'));
+        console.log(chalk.gray('  (no versions installed; add one with `agents add <agent>@<version>`)'));
     }
     else {
         for (const row of syncRows) {
-            const label = `${AGENT_NAMES[row.agent] || row.agent}@${row.version}`;
+            const tag = row.isDefault ? chalk.gray(' (default)') : '';
+            const label = `${AGENT_NAMES[row.agent] || row.agent}@${row.version}${tag}`;
             if (row.status === 'fresh') {
                 console.log(`  ${chalk.green('fresh')}  ${label}`);
             }
@@ -103,7 +112,7 @@ function renderOverviewText(clis, syncRows, orphanRows, hostClis) {
         }
     }
     console.log();
-    console.log(chalk.bold('Orphans (default versions)'));
+    console.log(chalk.bold('Orphans (installed versions)'));
     if (orphanRows.length === 0) {
         console.log(chalk.gray('  (none — version homes match central sources)'));
     }
@@ -340,9 +349,77 @@ function renderTargetText(report, options) {
     }
     else {
         console.log(`  Verdict: ${verdictParts.join(', ')}.`);
-        console.log(chalk.gray(`  Run \`agents sync ${report.agent}@${report.version}\` to reconcile, or \`agents prune cleanup\` to drop extras.`));
+        console.log(chalk.gray(`  Run \`agents doctor ${report.agent}@${report.version} --fix\` to heal, or \`agents prune cleanup\` to drop extras.`));
     }
 }
+// ─── fix / heal mode ───────────────────────────────────────────────────────────
+function renderHealText(result) {
+    for (const r of result.repairedManifests) {
+        console.log(`  ${chalk.green('repair')}  plugin ${chalk.bold(r.plugin)} ${chalk.gray(`— dropped invalid ${r.droppedFields.join(', ')} field`)}`);
+    }
+    for (const r of result.refreshedPlugins) {
+        console.log(`  ${chalk.green('refresh')} plugin ${chalk.bold(r.plugin)}  ${chalk.gray(`${r.from} → ${r.to}`)}`);
+    }
+    for (const s of result.skippedPlugins) {
+        const why = s.reason === 'modified'
+            ? `locally modified — left as-is (run \`agents plugins update ${s.plugin}\` to force)`
+            : `no baseline recorded — left as-is (run \`agents plugins update ${s.plugin}\` to adopt)`;
+        console.log(`  ${chalk.yellow('hold  ')} plugin ${chalk.bold(s.plugin)}  ${chalk.gray(`${s.from} → ${s.upstream} available; ${why}`)}`);
+    }
+    for (const v of result.versions) {
+        const label = `${AGENT_NAMES[v.agent] || v.agent}@${v.version}`;
+        if (v.healed.length === 0 && v.skipped.length === 0)
+            continue;
+        const byKind = new Map();
+        for (const h of v.healed)
+            byKind.set(h.kind, (byKind.get(h.kind) ?? 0) + 1);
+        const parts = Array.from(byKind, ([k, n]) => `${n} ${k}`);
+        if (v.healed.length > 0) {
+            console.log(`  ${chalk.green('fixed ')}  ${label}  ${chalk.gray(parts.join(', '))}`);
+        }
+        const drift = v.skipped.filter((s) => s.reason === 'drift');
+        const unres = v.skipped.filter((s) => s.reason === 'unreconcilable');
+        if (drift.length > 0) {
+            console.log(`  ${chalk.yellow('drift ')}  ${label}  ${chalk.gray(`${drift.length} hand-edited — left as-is (use \`--diff\` to inspect)`)}`);
+        }
+        if (unres.length > 0) {
+            const names = unres.map((s) => `${s.kind}/${s.name}`).join(', ');
+            console.log(`  ${chalk.yellow('hold  ')}  ${label}  ${chalk.gray(`${unres.length} couldn't reconcile (${names}) — source/home mismatch the writer can't satisfy`)}`);
+        }
+    }
+    console.log();
+    const healed = result.versions.reduce((n, v) => n + v.healed.length, 0);
+    const touchedVersions = result.versions.filter((v) => v.healed.length > 0).length;
+    if (!healChangedAnything(result)) {
+        console.log(chalk.green('✓ Everything in sync — nothing to heal.'));
+    }
+    else {
+        const bits = [];
+        if (healed > 0)
+            bits.push(`${healed} resource${healed === 1 ? '' : 's'} across ${touchedVersions} version${touchedVersions === 1 ? '' : 's'}`);
+        if (result.repairedManifests.length > 0)
+            bits.push(`${result.repairedManifests.length} manifest${result.repairedManifests.length === 1 ? '' : 's'} repaired`);
+        if (result.refreshedPlugins.length > 0)
+            bits.push(`${result.refreshedPlugins.length} plugin${result.refreshedPlugins.length === 1 ? '' : 's'} refreshed`);
+        console.log(chalk.green(`✓ Healed ${bits.join(', ')}.`));
+    }
+}
+async function runFix(parsed, opts) {
+    // Heal targets the global install — project layer is irrelevant, so cwd is
+    // left to heal's neutral default rather than process.cwd().
+    if (!opts.json)
+        console.log(chalk.bold('Healing…'));
+    const result = await heal({
+        mode: 'full',
+        agent: parsed?.agent,
+        versions: parsed?.versions,
+    });
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    renderHealText(result);
+}
 // ─── command registration ────────────────────────────────────────────────────
 export function registerDoctorCommand(program) {
     const doctorCmd = program
@@ -350,6 +427,7 @@ export function registerDoctorCommand(program) {
         .description('Diagnose CLI availability, sync status, and resource divergence (optionally for a specific agent[@version]).')
         .option('--json', 'Output machine-readable JSON')
         .option('--diff', 'In target mode, include unified diffs for divergent files')
+        .option('--fix', 'Heal gaps: install missing resources, repair invalid plugin manifests, refresh stale plugins, and reconcile drift (all installed versions, or just the target)')
         .option('--kind <kinds>', 'Restrict to comma-separated resource kinds (commands,skills,hooks,rules,mcp,permissions,subagents,plugins,promptcuts)')
         .option('--cwd <path>', 'Resolution cwd for project layer detection (default: process.cwd())');
     setHelpSections(doctorCmd, {
@@ -368,10 +446,31 @@ export function registerDoctorCommand(program) {
 
       # Inspect only rules and hooks, with full diffs
       agents doctor claude@default --kind rules,hooks --diff
+
+      # Heal every gap across all installed versions
+      agents doctor --fix
+
+      # Heal just one agent (all its installed versions)
+      agents doctor claude --fix
     `,
     });
-    doctorCmd.action((target, opts) => {
+    doctorCmd.action(async (target, opts) => {
         const cwd = opts.cwd ? opts.cwd : process.cwd();
+        // --fix turns the read-only diagnosis into a heal. With no target it heals
+        // every installed version; with a target it scopes to that agent.
+        if (opts.fix) {
+            let scope = null;
+            if (target) {
+                const parsed = parseTargetArg(target);
+                if ('error' in parsed) {
+                    console.error(chalk.red(parsed.error));
+                    process.exit(1);
+                }
+                scope = parsed;
+            }
+            await runFix(scope, opts);
+            return;
+        }
         if (!target) {
             const clis = checkAllClis();
             const syncRows = checkSyncStatus(cwd);

package/dist/commands/inspect.d.ts

@@ -32,7 +32,7 @@ interface ResourceItem {
     /** For plugins: the resource categories (skills, commands, …) the bundle packages. */
     groups?: PluginResourceGroup[];
 }
-interface InspectOptions {
+export interface InspectOptions {
     brief?: boolean;
     json?: boolean;
     commands?: boolean | string;
@@ -66,6 +66,7 @@ export interface RepoTarget {
  * Returns null when the target is none of these.
  */
 export declare function resolveRepoTarget(target: string, cwd?: string): RepoTarget | null;
+export declare function inspectRepo(repo: RepoTarget, options: InspectOptions): Promise<void>;
 /** List one resource kind from a single repo root — no layering, no overrides. */
 export declare function collectRepoKind(repo: RepoTarget, kind: DrillableKind): ResourceItem[];
 /** Recursive size + file count of a path; symlinks are not followed. */

package/dist/commands/inspect.js

@@ -227,7 +227,7 @@ function isDotAgentsRoot(dir) {
     }
     return false;
 }
-async function inspectRepo(repo, options) {
+export async function inspectRepo(repo, options) {
     const drill = pickDrillKind(options);
     const jsonHead = { repo: repo.label, root: repo.root };
     if (drill) {

package/dist/commands/menubar.js

@@ -61,9 +61,14 @@ export function registerMenubarCommands(program) {
         console.log(`  running            ${yn(s.running)}`);
         console.log(`  service installed  ${yn(s.serviceInstalled)}`);
         console.log(`  app installed      ${s.installedApp ? chalk.gray(s.installedApp) : chalk.gray('no')}`);
+        console.log(`  installed version  ${s.installedVersion ? chalk.gray(s.installedVersion) : chalk.gray('unknown')}`);
+        console.log(`  current version    ${chalk.gray(s.currentVersion)}`);
         console.log(`  bundle source      ${s.source ? chalk.gray(s.source) : chalk.red('missing (cannot enable)')}`);
         console.log(`  disabled by user   ${yn(s.disabledByUser)}`);
-        if (!s.serviceInstalled && !s.disabledByUser) {
+        if (s.stale) {
+            console.log(chalk.yellow('\n  Installed helper is stale — runs on next `agents` startup, or `agents menubar enable` now.'));
+        }
+        else if (!s.serviceInstalled && !s.disabledByUser) {
             console.log(chalk.gray('\n  Enable it with `agents menubar enable`.'));
         }
     });

package/dist/commands/repo.js

@@ -7,6 +7,8 @@ import simpleGit from 'simple-git';
 import { confirm, input } from '@inquirer/prompts';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { setHelpSections } from '../lib/help.js';
+import { itemPicker } from '../lib/picker.js';
+import { inspectRepo, resolveRepoTarget, } from './inspect.js';
 const HOME = os.homedir();
 /**
  * Resolve a target argument to an absolute path.
@@ -162,6 +164,7 @@ async function listRepos(alias) {
 export function registerRepoCommands(program) {
     const repoCmd = program
         .command('repo')
+        .alias('repos')
         .description('Manage extra DotAgent repos alongside ~/.agents/ (for private or team skills).');
     setHelpSections(repoCmd, {
         examples: `
@@ -180,6 +183,9 @@ export function registerRepoCommands(program) {
       # See what's registered
       agents repo list
 
+      # View one repo's contents (git state + resource counts); omit the name for a picker
+      agents repos view system
+
       # Temporarily disable without deleting
       agents repo disable acme
     `,
@@ -356,6 +362,40 @@ export function registerRepoCommands(program) {
         .action(async (alias) => {
         await listRepos(alias);
     });
+    repoCmd
+        .command('view [name]')
+        .description("Show one repo's contents: git state and per-kind resource counts. Omit the name for an interactive picker.")
+        .option('--brief', 'header + git only; skip resource counts')
+        .option('--json', 'machine-readable JSON output')
+        .action(async (name, options) => {
+        if (name) {
+            const repo = resolveRepoTarget(name);
+            if (!repo) {
+                console.log(chalk.red(`Unknown repo "${name}". Use "system", "user", "project", or a registered extra alias.`));
+                process.exitCode = 1;
+                return;
+            }
+            await inspectRepo(repo, options);
+            return;
+        }
+        const targets = collectRepoTargets(undefined) || [];
+        if (!isInteractiveTerminal()) {
+            console.log(chalk.red('No repo name given and not an interactive terminal.'));
+            console.log(chalk.gray('Pass a name (e.g. `agents repos view system`) or run in a TTY for the picker.'));
+            process.exitCode = 1;
+            return;
+        }
+        const picked = await itemPicker({
+            message: 'Select a repo to view',
+            items: targets,
+            filter: (q) => targets.filter((t) => t.alias.toLowerCase().includes(q.toLowerCase())),
+            labelFor: (t) => `${chalk.cyan(t.alias.padEnd(10))} ${chalk.gray(t.dir)}`,
+        });
+        if (!picked)
+            return;
+        const repo = { label: picked.item.alias, root: picked.item.dir };
+        await inspectRepo(repo, options);
+    });
     repoCmd
         .command('remove <alias>')
         .alias('rm')

package/dist/commands/secrets.js

@@ -424,14 +424,15 @@ export function registerSecretsCommands(program) {
       never touch disk in plaintext. Every item is device-local and gated by Touch ID
       or device passcode; cross-machine sync is handled by 'agents secrets push/pull'.
 
-      Touch ID noise: macOS pops a prompt per bundle per process, so concurrent
-      agents each re-prompt. Each bundle has a prompt policy, shown in the POLICY
-      column of 'agents secrets list':
-        always (default)  ask for Touch ID every time — never auto-held.
-        daily             ask once, then hold it silently in the local agent up
+      Touch ID noise: macOS pops a prompt per bundle per process. Each bundle has
+      a prompt policy, shown in the POLICY column of 'agents secrets list':
+        daily (default)   ask once, then hold it silently in the local agent up
                           to ~24h, until screen-lock / sleep / logout or 'lock'.
-      Set it with 'agents secrets policy <bundle> daily'. 'agents secrets unlock
-      <bundle>' holds any bundle after one prompt regardless of policy. Nothing on disk.
+        always            ask for Touch ID every time — never auto-held.
+      The default is 'daily' (one Touch ID per ~24h); change it globally with
+      'secrets.policy' in agents.yaml, or per bundle with 'agents secrets policy
+      <bundle> always'. 'agents secrets unlock <bundle>' holds any bundle after one
+      prompt regardless of policy. Nothing on disk.
 
       See also:
         agents secrets policy <bundle> daily           ask once a day, not every run
@@ -623,7 +624,7 @@ export function registerSecretsCommands(program) {
         .description('Create an empty bundle')
         .option('--description <text>', 'Free-form description')
         .option('--allow-exec', 'Allow exec: refs in this bundle (off by default)')
-        .option('--policy <policy>', 'prompt policy: always (default, ask every time) or daily (ask once a day)')
+        .option('--policy <policy>', 'prompt policy: daily (default, ask once a day) or always (ask every time)')
         .addOption(new Option('--tier <policy>', 'deprecated alias for --policy').hideHelp())
         .option('--backend <backend>', 'storage backend: keychain (default) or file (passphrase-encrypted, headless-readable)', 'keychain')
         .option('--force', 'Overwrite an existing bundle')
@@ -631,7 +632,10 @@ export function registerSecretsCommands(program) {
         try {
             const resolvedName = name ?? (await promptBundleName());
             validateBundleName(resolvedName);
-            const policy = parsePolicyOpt(opts.policy ?? opts.tier);
+            // Leave policy unset unless the user explicitly chose one, so the bundle
+            // inherits the configured default (`daily`) instead of being pinned.
+            const policyOpt = opts.policy ?? opts.tier;
+            const policy = policyOpt ? parsePolicyOpt(policyOpt) : undefined;
             const backend = parseBackendOpt(opts.backend);
             if (bundleExists(resolvedName) && !opts.force) {
                 console.error(chalk.red(`Bundle '${resolvedName}' already exists. Use --force to overwrite.`));
@@ -647,7 +651,7 @@ export function registerSecretsCommands(program) {
             };
             writeBundle(bundle);
             const tags = [
-                policy === 'daily' ? 'policy: daily' : 'policy: always ask',
+                bundlePolicy(bundle) === 'daily' ? 'policy: daily' : 'policy: always ask',
                 backend === 'file' ? 'backend: file' : null,
             ].filter(Boolean);
             console.log(chalk.green(`Bundle '${resolvedName}' created (${tags.join(', ')}).`));
@@ -1430,7 +1434,7 @@ Examples:
     cmd
         .command('policy <bundle> [policy]')
         .alias('tier')
-        .description("Show or set a bundle's prompt policy: always (default, ask every time) or daily (ask once a day).")
+        .description("Show or set a bundle's prompt policy: daily (default, ask once a day) or always (ask every time).")
         .action((bundleName, policyArg) => {
         try {
             const bundle = readBundle(bundleName);
@@ -1443,7 +1447,7 @@ Examples:
             writeBundle(bundle);
             console.log(chalk.green(`${bundle.name} policy set to ${next}.`));
             if (next === 'daily') {
-                console.log(chalk.gray('Held by the secrets-agent after one unlock: run `agents secrets unlock`, or enable auto-cache with `secrets.agent.auto: true` in agents.yaml.'));
+                console.log(chalk.gray('Held by the secrets-agent for ~24h after one unlock (auto-cache is on by default; disable with `secrets.agent.auto: false` in agents.yaml).'));
             }
             else {
                 console.log(chalk.gray('Asks for Touch ID every time — never auto-held.'));

package/dist/commands/sessions.js

@@ -20,6 +20,7 @@ import { getActiveSessions } from '../lib/session/active.js';
 import { discoverSessions, countSessionsInScope, resolveSessionById, searchContentIndex } from '../lib/session/discover.js';
 import { filterTeamSessions } from '../lib/session/team-filter.js';
 import { parseSession } from '../lib/session/parse.js';
+import { runRemoteSessions } from '../lib/session/remote.js';
 import { renderConversationMarkdown, renderSummary, renderSummaryHeader, computeSummaryStats, renderJson, filterEvents, parseRoleList } from '../lib/session/render.js';
 import { renderMarkdown } from '../lib/markdown.js';
 import { colorAgent, resolveAgentName } from '../lib/agents.js';
@@ -313,6 +314,16 @@ async function renderActiveSessions(asJson) {
 }
 /** Main action handler for `agents sessions`. Routes to picker, table, or single-session render. */
 async function sessionsAction(query, options) {
+    if (options.host && options.host.length > 0) {
+        try {
+            runRemoteSessions(options.host);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+        return;
+    }
     if (options.active) {
         await renderActiveSessions(options.json === true);
         return;
@@ -1116,7 +1127,8 @@ export function registerSessionsCommands(program) {
         .option('--artifacts', 'List all files written or edited during a session')
         .option('--artifact <name>', 'Read a specific artifact by filename or path (outputs to stdout)')
         .option('--active', 'Show only sessions running right now across terminals, teams, cloud, and headless agents')
-        .option('--cloud', 'Source sessions from Rush Cloud (captured runs) instead of local disk');
+        .option('--cloud', 'Source sessions from Rush Cloud (captured runs) instead of local disk')
+        .option('-H, --host <target...>', 'Run this query on remote machine(s) over SSH (host alias or user@host; repeatable)');
     setHelpSections(sessionsCmd, {
         examples: `
       # Search prior sessions in this project by topic, file path, or command
@@ -1136,8 +1148,15 @@ export function registerSessionsCommands(program) {
 
       # Export for analysis
       agents sessions --since 30d --limit 200 --json > sessions.json
+
+      # Search another machine's sessions live over SSH (no sync needed)
+      agents sessions "auth bug" --last 3 --host yosemite-s1
+
+      # Fan the same query out across several machines
+      agents sessions --all "deploy script" --host box-a --host box-b
     `,
         notes: `
+      - --host runs the query on the remote's own index over SSH (host alias or user@host); repeat or pass several to fan out. SSH access is the only auth.
       - --include and --exclude are mutually exclusive.
       - --first and --last are mutually exclusive.
       - A filter flag (--include/--exclude/--first/--last) without --markdown/--json defaults to --markdown output.

package/dist/index.js

@@ -11,6 +11,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
+import { detectDevBuild } from './lib/startup/dev-build.js';
 // `ora`, `@inquirer/prompts`, `./commands/utils.js`, and the agents/versions/shims
 // modules are imported dynamically at their use sites: they are needed only on
 // interactive / update / shim-repair paths, never for fast commands like
@@ -37,18 +38,7 @@ import { NPM_PACKAGE_NAME, deriveGlobalPrefix, detectPackageManager, installPack
 // must not scribble on the user's real ~/.agents/), and skip the update prompt
 // (the "0.0.0-dev -> 1.x.y" message is misleading). Each individual env var
 // can still be set explicitly to override (set to '0' to re-enable).
-const IS_DEV_BUILD = (() => {
-    if (VERSION.startsWith('0.0.0-dev'))
-        return true;
-    try {
-        const cliPath = process.argv[1] || '';
-        const repoRoot = path.dirname(path.dirname(cliPath));
-        return fs.existsSync(path.join(repoRoot, '.git'));
-    }
-    catch {
-        return false;
-    }
-})();
+const IS_DEV_BUILD = detectDevBuild(process.argv[1] || '', VERSION);
 if (IS_DEV_BUILD) {
     if (process.env.AGENTS_NO_AUTOPULL === undefined)
         process.env.AGENTS_NO_AUTOPULL = '1';

package/dist/lib/agent-spec.d.ts

@@ -0,0 +1,36 @@
+import type { AgentId } from './types.js';
+export interface AgentTarget {
+    agent: AgentId;
+    /** Resolved exact version, or null when the agent has no installed versions yet. */
+    version: string | null;
+}
+/** Canonical qualifier set, in help/display order. `pinned` ≡ `default`. */
+export declare const AGENT_QUALIFIERS: readonly ["latest", "oldest", "pinned", "default", "all"];
+export type AgentQualifier = (typeof AGENT_QUALIFIERS)[number];
+/** Shared `--help` epilog so every agent-spec command documents the same grammar. */
+export declare const AGENT_SPEC_HELP: string;
+export declare class AgentSpecError extends Error {
+    constructor(message: string);
+}
+export interface ResolveAgentTargetsOptions {
+    /** Project dir for resolving a bare spec's project pin. Defaults to process.cwd(). */
+    cwd?: string;
+    /** Restrict the agents a spec may name (e.g. only mcp-capable). Defaults to all. */
+    availableAgents?: readonly AgentId[];
+}
+/**
+ * Resolve an agent spec (single or comma-list) into concrete installed targets.
+ * Domain = installed: `@latest`/`@oldest`/`@all` range over installed versions
+ * (`add`/`install` use a separate available-version path). Throws AgentSpecError
+ * on bad input — never calls process.exit, so it is safe on the hot path and in
+ * library contexts.
+ */
+export declare function resolveAgentTargets(spec: string, opts?: ResolveAgentTargetsOptions): AgentTarget[];
+/**
+ * Convenience for single-target commands (`use`, `run`): resolve a spec that
+ * must name exactly one installed version. Rejects `@all` / multi-target specs.
+ */
+export declare function resolveSingleAgentTarget(spec: string, opts?: ResolveAgentTargetsOptions): {
+    agent: AgentId;
+    version: string;
+};