@phnx-labs/agents-cli 1.20.76 → 1.20.77

package/dist/commands/routines.js

@@ -12,7 +12,8 @@ import * as path from 'path';
 import * as yaml from 'yaml';
 import { isDaemonRunning, signalDaemonReload, startDaemon, stopDaemon, readDaemonLog, getDaemonStatus, } from '../lib/daemon.js';
 import { humanizeCron, humanizeNextRun, formatRepoLink, REPO_DISPLAY_MAX } from '../lib/routines-format.js';
-import { listJobs as listAllJobs, deleteJob, readJob, validateJob, writeJob, setJobEnabled, listRuns, getLatestRun, getRunDir, getJobPath, parseAtTime, jobRunsOnThisDevice, checkJobDeviceEligibility, normalizeTriggerEvent, } from '../lib/routines.js';
+import { listJobs as listAllJobs, deleteJob, readJob, validateJob, writeJob, setJobEnabled, listRuns, getLatestRun, getRunDir, getJobPath, parseAtTime, jobRunsOnThisDevice, checkJobDeviceEligibility, normalizeTriggerEvent, parseHostStrategy, resolveHostStrategy, placementRequiresFiringPin, HOST_STRATEGIES, } from '../lib/routines.js';
+import { discoverProjectRoutinesAt, enableProjectRoutines, disableProjectRoutines, syncProjectRoutines, syncAllProjectRoutines, listEnabledProjectRoots, resolveProjectRoot, displayProjectPath, listProjectRoutineFiles, } from '../lib/routines-project.js';
 import { fireWebhookJobs, matchJobsToWebhook } from '../lib/triggers/webhook.js';
 import { getRoutinesDir } from '../lib/state.js';
 import { IS_WINDOWS } from '../lib/platform/index.js';
@@ -131,6 +132,24 @@ function ensureSchedulerRunning(opts = {}) {
 function writeJson(payload) {
     process.stdout.write(JSON.stringify(payload) + '\n');
 }
+function printSyncResult(sync) {
+    console.log(chalk.bold(displayProjectPath(sync.projectRoot)));
+    if (sync.synced.length === 0 && sync.skipped.length === 0 && sync.removed.length === 0 && sync.errors.length === 0) {
+        console.log(chalk.gray('  (no project routines)'));
+    }
+    if (sync.synced.length > 0) {
+        console.log(chalk.green(`  synced: ${sync.synced.join(', ')}`));
+    }
+    if (sync.removed.length > 0) {
+        console.log(chalk.gray(`  removed: ${sync.removed.join(', ')}`));
+    }
+    for (const s of sync.skipped) {
+        console.log(chalk.yellow(`  skipped ${s.name}: ${s.reason}`));
+    }
+    for (const e of sync.errors) {
+        console.log(chalk.red(`  error ${e.name}: ${e.error}`));
+    }
+}
 function runMetaJson(run) {
     return {
         jobId: run.jobName,
@@ -233,6 +252,14 @@ export function registerRoutinesCommands(program) {
       # Create from YAML (for complex routines with multiple settings)
       agents routines add weekly-report.yml
 
+      # Place the job body on a fleet device / cloud / named host (not --host)
+      agents routines add drain --schedule "0 3 * * *" --agent claude --placement fleet --prompt "Drain queue"
+      agents routines add review --schedule "0 9 * * 1" --agent claude --placement cloud --prompt "Review open PRs"
+
+      # Opt a project's .agents/routines/*.yml into daemon firing (never auto)
+      agents routines enable-project --yes
+      agents routines sync
+
       # List all routines and their next run times
       agents routines list
 
@@ -323,6 +350,10 @@ export function registerRoutinesCommands(program) {
                     timezone: job.timezone ?? null,
                     devices: job.devices ?? [],
                     host: job.host ?? null,
+                    hostStrategy: resolveHostStrategy(job),
+                    source: job.source ?? null,
+                    sourceRepo: job.source?.repo ?? job.repo ?? null,
+                    sourceBranch: job.source?.branch ?? null,
                     runsHere: jobRunsOnThisDevice(job),
                     enabled: job.enabled,
                     overdue: overdueSet.has(job.name),
@@ -368,7 +399,12 @@ export function registerRoutinesCommands(program) {
             }
             const latestRun = getLatestRun(job.name);
             const lastStatus = latestRun?.status || '-';
-            const repoInfo = formatRepoLink(job.repo);
+            // Prefer project-source repo (with optional @branch) over bare job.repo.
+            const sourceRepo = job.source?.repo ?? job.repo;
+            const sourceLabel = sourceRepo
+                ? (job.source?.branch ? `${sourceRepo}@${job.source.branch}` : sourceRepo)
+                : null;
+            const repoInfo = formatRepoLink(sourceLabel ?? job.repo);
             const repoCell = link(repoInfo.display, repoInfo.href);
             // Pad based on the display string, not the raw cell (which may include escape codes).
             const repoPadding = Math.max(0, REPO_W - repoInfo.display.length);
@@ -376,8 +412,16 @@ export function registerRoutinesCommands(program) {
             // chalk adds escape codes; pad the raw word and let chalk wrap it.
             const enabledWord = job.enabled ? 'yes' : 'no';
             const enabledPad = Math.max(0, ENABLED_W - enabledWord.length);
-            // Placement (`→host`) rides in the Devices cell: eligibility →execution.
-            const deviceFull = [job.devices?.join(',') ?? '', job.host ? `→${job.host}` : '']
+            // Placement rides in the Devices cell: eligibility →execution strategy.
+            const strategy = resolveHostStrategy(job);
+            const placementTag = strategy === 'local'
+                ? (job.host ? `→${job.host}` : '')
+                : strategy === 'host'
+                    ? `→${job.host ?? '?'}`
+                    : strategy === 'fleet'
+                        ? '→fleet'
+                        : '→cloud';
+            const deviceFull = [job.devices?.join(',') ?? '', placementTag]
                 .filter(Boolean)
                 .join(' ');
             const deviceWord = deviceFull.length === 0
@@ -423,7 +467,8 @@ export function registerRoutinesCommands(program) {
         .option('-t, --timeout <timeout>', 'Kill the agent if it runs longer than this (e.g., 10m, 2h, 3d, 1w; max 1w)', '10m')
         .option('--timezone <tz>', 'Interpret schedule in this timezone (e.g., America/Los_Angeles)')
         .option('--devices <names>', 'Fleet allowlist (comma-separated): only listed devices schedule and fire this routine. Omit for unrestricted.')
-        .option('--run-on <name>', 'Execute the job body on this machine over SSH (a registered host, device, capability tag, or user@host). Placement, not eligibility — see --devices. Auto-pins devices to THIS machine unless --devices is given.')
+        .option('--run-on <name>', 'Execute the job body on this machine over SSH (a registered host, device, capability tag, or user@host). Sets hostStrategy=host. Placement, not eligibility — see --devices. Auto-pins devices to THIS machine unless --devices is given.')
+        .option('--placement <strategy>', `Where the job body runs: ${HOST_STRATEGIES.join('|')} (default: local, or host when --run-on is set). Not the same as --host (which manages routines on a remote machine).`)
         .option('--run-cwd <dir>', 'Working directory on the --run-on host (--remote-cwd is taken by the remote-management passthrough)')
         .option('--at <time>', 'One-shot mode: run once at this time (e.g., "14:30" or "2026-02-24 09:00"), then disable')
         .option('--on <source:event>', 'Webhook trigger instead of/in addition to a schedule: github:pull_request or linear:Issue')
@@ -490,12 +535,29 @@ export function registerRoutinesCommands(program) {
             if (options.devices !== undefined) {
                 devices = await parseAndValidateDevices(options.devices);
             }
-            // --run-on without a --devices pin would fire on EVERY daemon in the
-            // fleet, each dispatching to the same host — duplicate runs. Pin to
-            // this machine unless the user chose an explicit eligibility set.
-            if (options.runOn && !devices) {
+            let hostStrategy;
+            try {
+                hostStrategy = parseHostStrategy(options.placement) ?? undefined;
+            }
+            catch (err) {
+                console.error(chalk.red(err.message));
+                process.exit(1);
+            }
+            // --run-on implies host strategy when the user didn't pick one.
+            if (options.runOn && !hostStrategy)
+                hostStrategy = 'host';
+            if (hostStrategy === 'host' && !options.runOn) {
+                console.error(chalk.red('--placement host requires --run-on <name>'));
+                process.exit(1);
+            }
+            // Off-box placement without a --devices pin would fire on EVERY daemon
+            // in the fleet, each dispatching once — duplicate runs (RUSH-1980).
+            // Pin to this machine unless the user chose an explicit eligibility set.
+            const strategyForPin = hostStrategy
+                ?? (options.runOn ? 'host' : 'local');
+            if (placementRequiresFiringPin(strategyForPin) && !devices) {
                 devices = [machineId()];
-                console.error(chalk.gray(`--run-on set with no --devices: pinned firing to this machine (${devices[0]}).`));
+                console.error(chalk.gray(`--placement ${strategyForPin} with no --devices: pinned firing to this machine (${devices[0]}).`));
             }
             const config = {
                 name: nameOrPath,
@@ -512,6 +574,7 @@ export function registerRoutinesCommands(program) {
                 timezone: options.timezone,
                 ...(devices ? { devices } : {}),
                 ...(options.runOn ? { host: options.runOn } : {}),
+                ...(hostStrategy ? { hostStrategy } : {}),
                 ...(options.runCwd ? { remoteCwd: options.runCwd } : {}),
                 ...(runOnce ? { runOnce: true } : {}),
                 ...(options.endAt ? { endAt: options.endAt } : {}),
@@ -586,11 +649,12 @@ export function registerRoutinesCommands(program) {
                 enabled: true,
                 ...parsed,
             };
-            // Same duplicate-fire guard as the --run-on flag: a host-placed routine
+            // Same duplicate-fire guard as --placement/--run-on: off-box placement
             // with no eligibility pin would fire from every daemon in the fleet.
-            if (config.host && (!config.devices || config.devices.length === 0)) {
+            const fileStrategy = resolveHostStrategy(config);
+            if (placementRequiresFiringPin(fileStrategy) && (!config.devices || config.devices.length === 0)) {
                 config.devices = [machineId()];
-                console.error(chalk.gray(`host: set with no devices pin: pinned firing to this machine (${config.devices[0]}).`));
+                console.error(chalk.gray(`${fileStrategy} placement with no devices pin: pinned firing to this machine (${config.devices[0]}).`));
             }
             writeJob(config);
             if (options.json) {
@@ -1120,6 +1184,12 @@ export function registerRoutinesCommands(program) {
             process.exit(1);
         }
         if (options.clear) {
+            const strategy = resolveHostStrategy(job);
+            if (placementRequiresFiringPin(strategy)) {
+                console.error(chalk.red(`Cannot clear devices for hostStrategy: ${strategy} — without a pin every fleet daemon would dispatch once.`));
+                console.error(chalk.gray(`Keep a single-machine pin (e.g. --set ${machineId()}) or switch to --placement local.`));
+                process.exit(1);
+            }
             job.devices = undefined;
             writeJob(job);
             console.log(chalk.green(`Devices cleared for '${name}' — runs on all devices`));
@@ -1130,6 +1200,12 @@ export function registerRoutinesCommands(program) {
         if (hasSet) {
             const devices = await parseAndValidateDevices(options.set);
             job.devices = devices;
+            // Re-validate so host/fleet/cloud can't be left with an empty set via --set ""
+            const errs = validateJob(job);
+            if (errs.length > 0) {
+                console.error(chalk.red(errs.join('\n')));
+                process.exit(1);
+            }
             writeJob(job);
             console.log(chalk.green(`Devices for '${name}' set to: ${devices.join(', ')}`));
             if (isDaemonRunning())
@@ -1158,6 +1234,11 @@ export function registerRoutinesCommands(program) {
                 })),
             });
             if (selected.length === 0) {
+                const strategy = resolveHostStrategy(job);
+                if (placementRequiresFiringPin(strategy)) {
+                    console.error(chalk.red(`Cannot clear devices for hostStrategy: ${strategy} — without a pin every fleet daemon would dispatch once.`));
+                    return;
+                }
                 job.devices = undefined;
                 writeJob(job);
                 console.log(chalk.green(`Devices cleared for '${name}' — runs on all devices`));
@@ -1250,6 +1331,183 @@ export function registerRoutinesCommands(program) {
             console.log(chalk.gray('\n  Start the scheduler to begin firing routines: agents routines start'));
         }
     });
+    routinesCmd
+        .command('enable-project [path]')
+        .description('Opt a project\'s .agents/routines/*.yml into daemon firing. Requires explicit approval — project routines never auto-fire from a cloned repo. Materialises copies into ~/.agents/routines/ with source provenance.')
+        .option('--yes', 'Skip the interactive confirmation prompt')
+        .option('--json', 'Emit machine-readable JSON')
+        .action(async (projectPath, options) => {
+        const root = projectPath
+            ? path.resolve(projectPath)
+            : resolveProjectRoot(process.cwd());
+        if (!root) {
+            console.error(chalk.red('No project .agents/ directory found from the current directory.'));
+            console.error(chalk.gray('Run from inside a project, or pass the project path: agents routines enable-project /path/to/repo'));
+            process.exit(1);
+        }
+        const files = listProjectRoutineFiles(root);
+        if (files.length === 0) {
+            console.error(chalk.red(`No routines found under ${path.join(root, '.agents', 'routines')}`));
+            process.exit(1);
+        }
+        if (!options.yes) {
+            if (!isInteractiveTerminal()) {
+                console.error(chalk.red('Refusing to enable project routines non-interactively without --yes.'));
+                console.error(chalk.gray(`Found ${files.length} routine(s) in ${displayProjectPath(root)}. Re-run with --yes to confirm.`));
+                process.exit(1);
+            }
+            try {
+                const { confirm } = await import('@inquirer/prompts');
+                const ok = await confirm({
+                    message: `Enable daemon firing for ${files.length} project routine(s) in ${displayProjectPath(root)}?`,
+                    default: false,
+                });
+                if (!ok) {
+                    console.log(chalk.gray('Cancelled'));
+                    return;
+                }
+            }
+            catch (err) {
+                if (isPromptCancelled(err)) {
+                    console.log(chalk.gray('Cancelled'));
+                    return;
+                }
+                throw err;
+            }
+        }
+        const newly = enableProjectRoutines(root);
+        const sync = syncProjectRoutines(root);
+        if (isDaemonRunning())
+            signalDaemonReload();
+        if (options.json) {
+            writeJson({
+                ok: true,
+                projectRoot: root,
+                newlyEnabled: newly,
+                synced: sync.synced,
+                skipped: sync.skipped,
+                removed: sync.removed,
+                errors: sync.errors,
+            });
+            return;
+        }
+        console.log(chalk.green(newly
+            ? `Enabled project routines for ${displayProjectPath(root)}`
+            : `Project routines already enabled for ${displayProjectPath(root)}`));
+        if (sync.synced.length > 0) {
+            console.log(chalk.gray(`  Synced: ${sync.synced.join(', ')}`));
+        }
+        for (const s of sync.skipped) {
+            console.log(chalk.yellow(`  Skipped ${s.name}: ${s.reason}`));
+        }
+        for (const e of sync.errors) {
+            console.log(chalk.red(`  Error ${e.name}: ${e.error}`));
+        }
+        console.log(chalk.gray('Daemon will fire these after reload. Re-sync later with: agents routines sync'));
+    });
+    routinesCmd
+        .command('disable-project [path]')
+        .description('Remove a project from the project-routines allowlist. Use --remove-synced to also delete the user-layer copies.')
+        .option('--remove-synced', 'Delete user-layer routines that were materialised from this project')
+        .option('--json', 'Emit machine-readable JSON')
+        .action(async (projectPath, options) => {
+        const root = projectPath
+            ? path.resolve(projectPath)
+            : resolveProjectRoot(process.cwd());
+        if (!root) {
+            console.error(chalk.red('No project .agents/ directory found from the current directory.'));
+            process.exit(1);
+        }
+        const result = disableProjectRoutines(root, { removeSynced: options.removeSynced });
+        if (isDaemonRunning())
+            signalDaemonReload();
+        if (options.json) {
+            writeJson({ ok: true, projectRoot: root, ...result });
+            return;
+        }
+        if (!result.removed) {
+            console.log(chalk.gray(`Project ${displayProjectPath(root)} was not on the allowlist`));
+        }
+        else {
+            console.log(chalk.green(`Disabled project routines for ${displayProjectPath(root)}`));
+        }
+        if (result.deletedJobs.length > 0) {
+            console.log(chalk.gray(`  Removed user-layer copies: ${result.deletedJobs.join(', ')}`));
+        }
+    });
+    routinesCmd
+        .command('sync [path]')
+        .description('Refresh user-layer copies of opted-in project routines from their .agents/routines/*.yml sources. With no path, syncs every enabled project. Also runs automatically on daemon reload (SIGHUP).')
+        .option('--json', 'Emit machine-readable JSON')
+        .action(async (projectPath, options) => {
+        if (projectPath) {
+            const root = path.resolve(projectPath);
+            const isEnabled = listEnabledProjectRoots().some((p) => p === root);
+            if (!isEnabled) {
+                console.error(chalk.red(`Project ${displayProjectPath(root)} is not enabled. Run: agents routines enable-project ${root}`));
+                process.exit(1);
+            }
+            const sync = syncProjectRoutines(root);
+            if (isDaemonRunning())
+                signalDaemonReload();
+            if (options.json) {
+                writeJson({ ok: true, ...sync });
+                return;
+            }
+            printSyncResult(sync);
+            return;
+        }
+        const all = syncAllProjectRoutines();
+        if (isDaemonRunning())
+            signalDaemonReload();
+        if (options.json) {
+            writeJson({ ok: true, ...all });
+            return;
+        }
+        if (all.projects.length === 0 && all.missing.length === 0) {
+            console.log(chalk.gray('No project roots on the routines allowlist.'));
+            console.log(chalk.gray('  Enable one with: agents routines enable-project'));
+            return;
+        }
+        for (const p of all.projects)
+            printSyncResult(p);
+        for (const m of all.missing) {
+            console.log(chalk.yellow(`Missing project root (still on allowlist): ${displayProjectPath(m)}`));
+        }
+    });
+    routinesCmd
+        .command('projects')
+        .description('List project roots opted into daemon-fired project routines')
+        .option('--json', 'Emit machine-readable JSON')
+        .action((options) => {
+        const roots = listEnabledProjectRoots();
+        if (options.json) {
+            writeJson(roots.map((r) => ({
+                path: r,
+                display: displayProjectPath(r),
+                routines: listProjectRoutineFiles(r).map((f) => f.name),
+            })));
+            return;
+        }
+        if (roots.length === 0) {
+            console.log(chalk.gray('No projects enabled. Use: agents routines enable-project'));
+            // Offer a discovery hint for the current project.
+            const discovered = discoverProjectRoutinesAt(process.cwd());
+            if (discovered) {
+                console.log(chalk.gray(`  Found ${discovered.files.length} routine(s) in ${displayProjectPath(discovered.projectRoot)} — enable with: agents routines enable-project`));
+            }
+            return;
+        }
+        console.log(chalk.bold('Enabled project routines\n'));
+        for (const r of roots) {
+            const files = listProjectRoutineFiles(r);
+            console.log(`  ${chalk.cyan(displayProjectPath(r))}  ${chalk.gray(`(${files.length} routine${files.length === 1 ? '' : 's'})`)}`);
+            for (const f of files) {
+                console.log(chalk.gray(`    - ${f.name}`));
+            }
+        }
+        console.log();
+    });
     routinesCmd
         .command('scheduler-logs')
         .description('Read scheduler log output (for debugging why a routine did not fire). Use --follow to stream.')

package/dist/commands/secrets.js

@@ -18,16 +18,17 @@ import { ensureDaemonStarted, isDaemonRunning } from '../lib/daemon.js';
 import { parseHostsOption, remoteResolveEnv, remoteSecretsRaw, remoteSecretsStream, resolveHostSshTarget, } from '../lib/secrets/remote.js';
 import { remoteShellFor, buildWindowsStdinImportCommand } from '../lib/hosts/remote-cmd.js';
 import { resolveRemoteOsSync } from '../lib/hosts/remote-os.js';
-import { bundleExists, bundleItemStore, bundlePolicy, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, isHeadlessSecretsContext, readBundle, readBundleIfDecryptable, renameBundle, rotateBundleSecret, sanitizeProcessEnv, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, writeBundleWithItems, } from '../lib/secrets/bundles.js';
+import { bundleBackend, bundleExists, bundleItemStore, bundlePolicy, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, isHeadlessSecretsContext, readBundle, readBundleIfDecryptable, renameBundle, rotateBundleSecret, sanitizeProcessEnv, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, writeBundleWithItems, } from '../lib/secrets/bundles.js';
 import { encryptForFallback, decryptForFallback } from '../lib/secrets/filestore.js';
 import { getKeychainToken, getKeychainTokens, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from '../lib/secrets/index.js';
 import { assertOpAvailable, createPasswordItem, deleteItemByTitle, extractSecrets, itemExistsByTitle, listItems, listVaults, } from '../lib/onepassword.js';
 import { secretsHoldMs, secretsAgentDurable, agentLoad, agentLock, agentPing, agentStatus, ensureAgentRunning, runAgentLoadFromStdin, runSecretsAgent, uninstallSecretsAgentService, } from '../lib/secrets/agent.js';
-import { saveSession, deleteSession, deleteAllSessions } from '../lib/secrets/session-store.js';
+import { saveSession, deleteBundleSessions, deleteAllSessions } from '../lib/secrets/session-store.js';
 import { getCliVersionFresh } from '../lib/version.js';
 import { readMeta } from '../lib/state.js';
 import { parseDuration } from '../lib/hooks/cache.js';
-import { emit } from '../lib/events.js';
+import { emit, query } from '../lib/events.js';
+import { frequentlyPromptedBundles } from '../lib/secrets/unlock-hints.js';
 import { registerCommandGroups, setHelpSections } from '../lib/help.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { discoverSyncedBundles, importSyncedBundle, } from '../lib/secrets/icloud-import.js';
@@ -1096,8 +1097,9 @@ export function registerSecretsCommands(program) {
                 process.exit(1);
             }
             // `secrets get` is the scriptable automation primitive ($(agents secrets
-            // get bundle KEY)); when embedded in a headless routine/CI script it must
-            // not pop an unwatched Touch ID prompt. Interactive use still prompts.
+            // get bundle KEY)); when embedded in a headless routine/CI script — or run
+            // beneath any agent, which inherits AGENTS_RUNTIME — it must not pop an
+            // unwatched Touch ID prompt. Typed in a plain shell it still prompts.
             const { env } = readAndResolveBundleEnv(item, { caller: 'secrets get', keys: [key], keyMode: 'storage', agentOnly: isHeadlessSecretsContext() });
             if (!(key in env)) {
                 console.error(chalk.red(`Key '${key}' not in bundle '${item}'.`));
@@ -1816,10 +1818,10 @@ Examples:
                 process.exit(1);
             }
             // `agents secrets export --plaintext` is what release/CI scripts eval.
-            // When it runs detached (both stdio non-TTY) or under a headless agent,
-            // resolve broker-only so it can never pop a Touch ID sheet on the
-            // interactive user's screen. An interactive `eval "$(...)"` keeps its
-            // terminal stdin, so it is not headless and still prompts.
+            // When it runs detached (both stdio non-TTY) or beneath ANY agent — which
+            // inherits AGENTS_RUNTIME — resolve broker-only so it can never pop a Touch
+            // ID sheet on the interactive user's screen. An `eval "$(...)"` typed in a
+            // plain shell carries no AGENTS_RUNTIME, so it is not headless and still prompts.
             const { env } = readAndResolveBundleEnv(resolvedBundleName, {
                 caller: `export to shell`,
                 keyMode: 'process',
@@ -2055,6 +2057,7 @@ Examples:
         .description('Hold a bundle in the secrets-agent after one Touch ID, so concurrent runs read it without re-prompting (macOS). With --host, unlock FILE-backed bundle(s) on a remote (the passphrase prompt surfaces over the SSH TTY); keychain/biometry bundles are GUI-only and can\'t be remote-unlocked.')
         .option('--ttl <duration>', 'How long to hold it (e.g. 30m, 8h, 3d). Default 7d.')
         .option('--durable', 'Keep the unlock across sleep + reboot too (default: survives upgrade/restart but re-locks on sleep). Set secrets.agent.durable in agents.yaml to make this the default.')
+        .option('--for <agent>', 'Scope the unlock to one harness type (for example claude, codex, or kimi).')
         .option('--all', 'Unlock every configured bundle')
         .option('--host <target>', 'Unlock the bundle(s) on this remote machine over SSH instead of locally (file-backed bundles only — the remote\'s passphrase prompt surfaces on your terminal over a -tt session). Single-valued (NOT variadic) so it never swallows the bundle name: `unlock <name> --host <machine>`.')
         .action(async (names, opts) => {
@@ -2127,12 +2130,19 @@ Examples:
         // (single-instance start lock, #414) and best-effort — never blocks unlock.
         ensureDaemonStarted();
         let loaded = 0;
+        const harness = opts.for || process.env.AGENTS_AGENT_NAME || 'cli';
         for (const name of targets) {
             try {
                 // noAgent: read the real keychain (one Touch ID) rather than the
                 // agent we're about to populate.
-                const { bundle, env } = readAndResolveBundleEnv(name, { noAgent: true, caller: 'unlock', keyMode: 'storage' });
-                if (await agentLoad(name, bundle, env, ttlMs)) {
+                const { bundle, env } = readAndResolveBundleEnv(name, {
+                    noAgent: true,
+                    caller: 'unlock secrets',
+                    agent: harness,
+                    duration: humanRemaining(Date.now() + ttlMs),
+                    keyMode: 'storage',
+                });
+                if (await agentLoad(name, bundle, env, ttlMs, harness)) {
                     loaded++;
                     // Persist a durable session snapshot so the unlock survives a daemon
                     // restart / upgrade (and sleep too, with --durable). session-store.ts.
@@ -2141,6 +2151,7 @@ Examples:
                         env,
                         expiresAt: Date.now() + ttlMs,
                         sleepPersist: opts.durable ?? secretsAgentDurable(),
+                        harness,
                     });
                     console.log(`${chalk.green('unlocked')} ${chalk.cyan(name)} ${chalk.gray(`(${Object.keys(env).length} keys, ${humanRemaining(Date.now() + ttlMs)})`)}`);
                 }
@@ -2170,7 +2181,7 @@ Examples:
             let total = 0;
             for (const name of names) {
                 total += await agentLock(name);
-                deleteSession(name); // also drop the durable snapshot, or a restart re-warms it
+                deleteBundleSessions(name); // drop every harness scope
             }
             console.log(total > 0 ? chalk.green(`Locked ${total} bundle(s).`) : chalk.gray('Nothing to lock.'));
         }
@@ -2216,16 +2227,47 @@ Examples:
         } })();
         console.log(chalk.gray(`hold: ${holdStr}${configured ? ' (secrets.agent.holdMs)' : ' (default)'} — a daily bundle prompts once, then stays silent for this long or until sleep/logout.`));
         const entries = await agentStatus();
+        const held = new Set(entries.map((e) => e.name));
         if (entries.length === 0) {
             console.log(chalk.gray('No bundles held. The next read of each daily bundle will prompt once, then hold.'));
             console.log(chalk.gray('Pre-warm now with: agents secrets unlock <bundle>  (or --all)'));
-            return;
         }
-        console.log(chalk.bold(`${'BUNDLE'.padEnd(24)} ${'KEYS'.padEnd(5)} LOCKS IN`));
-        for (const e of entries) {
-            console.log(`${chalk.cyan(e.name.padEnd(24))} ${String(e.keyCount).padEnd(5)} ${humanRemaining(e.expiresAt)}`);
+        else {
+            console.log(chalk.bold(`${'BUNDLE'.padEnd(24)} ${'KEYS'.padEnd(5)} LOCKS IN`));
+            for (const e of entries) {
+                console.log(`${chalk.cyan(e.name.padEnd(24))} ${String(e.keyCount).padEnd(5)} ${humanRemaining(e.expiresAt)}`);
+            }
+            console.log(chalk.gray('Reads of held bundles are silent; any bundle not listed prompts once on its next read.'));
+        }
+        // Usage hint: bundles you keep getting a Touch ID prompt for — a keychain
+        // read that fell through to biometry (not served by the broker/session)
+        // >= a few times in the last week, and not currently held. Unlocking each
+        // once silences it for the hold window. This runs even when NO bundle is
+        // held — that user re-prompts on every read and most needs the nudge.
+        // Excludes `never`/no-ACL bundles (never prompt) and file/vault bundles
+        // (resolve by passphrase, not the keychain broker — `unlock` is a no-op).
+        try {
+            const weekAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
+            const reads = query({ eventTypes: ['secrets.get'], startDate: weekAgo });
+            const hot = frequentlyPromptedBundles(reads, held, { minReads: 3 }).filter((h) => {
+                try {
+                    return bundleBackend(h.name) === 'keychain' && bundlePolicy(readBundle(h.name)) !== 'never';
+                }
+                catch {
+                    return false; // bundle gone / unreadable metadata — nothing to suggest
+                }
+            });
+            if (hot.length > 0) {
+                console.log();
+                console.log(chalk.bold('Prompted often — unlock once to silence:'));
+                for (const h of hot) {
+                    console.log(`${chalk.cyan(h.name.padEnd(24))} ${chalk.gray(`${h.count}× in the last 7d`)}  →  ${chalk.green(`agents secrets unlock ${h.name}`)}`);
+                }
+            }
+        }
+        catch {
+            // Best-effort hint — never let usage analysis break `secrets status`.
         }
-        console.log(chalk.gray('Reads of held bundles are silent; any bundle not listed prompts once on its next read.'));
     });
     cmd
         .command('policy <bundle> [policy]')

package/dist/commands/sessions-browser.js

@@ -197,6 +197,16 @@ function applyFilters(rows, live, f, self) {
         out = out.filter((r) => live.has(r.id));
     return out;
 }
+/** Derive the SSH-launch origin tag for a picker row from the live index. Set
+ * only when the live session's provenance is ssh transport; `device` is the
+ * resolved origin device (absent → the row shows a bare `ssh`). Rows without a
+ * live entry (the running filter off) get no tag — provenance is live-only. */
+function sshOriginTagFor(live, id) {
+    const p = live?.get(id)?.provenance;
+    if (p?.transport !== 'ssh')
+        return undefined;
+    return p.origin?.device ? { device: p.origin.device } : {};
+}
 function headerFor(f) {
     const bits = [
         `device:${f.device ?? 'all'}`,
@@ -287,7 +297,7 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
         initialFilter,
         load,
         keyFor: (s) => s.id,
-        labelFor: (s, q) => formatPickerLabel(s, q, cols),
+        labelFor: (s, q) => formatPickerLabel(s, q, cols, sshOriginTagFor(liveCache, s.id)),
         matches: sessionMatchesQuery,
         buildPreview,
         headerFor,

package/dist/commands/sessions-picker.d.ts

@@ -1,4 +1,17 @@
-import type { SessionMeta } from '../lib/session/types.js';
+import type { SessionMeta, TodoProgress } from '../lib/session/types.js';
+/**
+ * Compact checklist tally for list rows and previews (RUSH-2045).
+ * Example: `✓6/8 · A5 wiring runner`. Empty string when there is no list.
+ * Consumes `SessionMeta.todos` / `ActiveSession.todos` as populated by the
+ * state engine — does not re-parse transcripts.
+ */
+export declare function formatTodoCompact(todos?: Pick<TodoProgress, 'done' | 'total' | 'activeForm'> | null): string;
+/**
+ * Best-effort GitHub repo URL from a checkout path shaped like
+ * `…/github.com/<owner>/<repo>/…`. Used to make the project name clickable
+ * when no Linear project URL is available.
+ */
+export declare function githubRepoUrlFromCwd(cwd?: string): string | undefined;
 export interface PickedSession {
     session: SessionMeta;
     action: 'resume' | 'view';