@phnx-labs/agents-cli 1.20.87 → 1.20.89

package/dist/commands/exec.js

@@ -1667,7 +1667,7 @@ export function registerRunCommand(program) {
             const { pickSessionInteractive } = await import('./sessions.js');
             const { buildContinuePrompt } = await import('../lib/loop.js');
             // Freshen the index for this agent before any lookup (incremental, cached).
-            // AgentId is wider than SessionAgentId (cursor/amp/… keep no transcripts);
+            // AgentId is wider than SessionAgentId (amp/kiro/goose/copilot keep no transcripts);
             // those simply yield no matches and fall through to the not-found error.
             const sessionAgent = agent;
             await discoverSessions({ agent: sessionAgent, version });
@@ -1899,8 +1899,8 @@ export function registerRunCommand(program) {
         // safest native mode (modes[0], typically edit). That covers both the
         // implicit default and an explicit `--mode plan`, so multi-agent
         // scripts can pass a uniform plan flag without per-agent branching.
-        // Elevation is never silent: we warn on stderr (yellow when the user
-        // explicitly asked for plan; gray for the implicit default / auto).
+        // Mode degradation is never silent: buildExecCommand emits one stderr
+        // warning for the requested-to-resolved transition unless --quiet is set.
         // `skip` still hard-fails when unsupported — pretending we bypassed
         // permissions would be unsafe.
         const modeIsDefault = modeSource === 'default';
@@ -1913,20 +1913,7 @@ export function registerRunCommand(program) {
             console.error(chalk.red(err.message));
             process.exit(1);
         }
-        if (resolvedMode !== requestedMode) {
-            mode = resolvedMode;
-            if (!options.quiet) {
-                if (requestedMode === 'plan' && !modeIsDefault) {
-                    process.stderr.write(chalk.yellow(`[agents] ${agent} has no read-only 'plan' mode; using '${mode}' (writable) instead. Pass --mode ${mode} to silence this.\n`));
-                }
-                else {
-                    process.stderr.write(chalk.gray(`[agents] ${agent} has no '${requestedMode}' mode; using '${mode}'\n`));
-                }
-            }
-        }
-        else {
-            mode = resolvedMode;
-        }
+        mode = resolvedMode;
         // Fail fast on the headless-plan stall footgun: a slash command run
         // headless under the implicit default 'plan' mode hangs forever at
         // ExitPlanMode (no TTY to approve the plan). Tell the user how to fix it
@@ -1935,7 +1922,7 @@ export function registerRunCommand(program) {
         const stallCmd = headlessPlanStallCommand({
             prompt,
             interactive: options.interactive,
-            mode,
+            mode: resolvedMode,
             modeIsDefault,
         });
         if (stallCmd) {
@@ -2029,7 +2016,7 @@ export function registerRunCommand(program) {
             version,
             prompt,
             interactive: options.interactive || forceInteractive,
-            mode,
+            mode: requestedMode,
             effort,
             cwd: options.cwd,
             model,
@@ -2040,6 +2027,7 @@ export function registerRunCommand(program) {
             name: options.name,
             resume: resumeNative,
             verbose: options.verbose,
+            modeWarningState: { quiet: options.quiet },
             // --raw, --no-tmux (commander negation → options.tmux === false), and
             // --disable-tmux all bypass the interactive tmux wrapper. AGENTS_NO_TMUX=1
             // does the same via the env check in exec.ts.

package/dist/commands/factory.js

@@ -6,6 +6,7 @@ import { homedir } from 'os';
 import { betaEnableHint, isBetaEnabled } from '../lib/beta.js';
 import { insertTask } from '../lib/cloud/store.js';
 import { emit } from '../lib/events.js';
+import { buildFactorySnapshot } from '../lib/factory/snapshot.js';
 function requireFactoryUrl() {
     const url = process.env.FACTORY_FLOOR_URL;
     if (!url) {
@@ -51,14 +52,28 @@ export function registerFactoryCommands(program) {
 Examples:
   agents factory submit PROJ-123
   agents factory submit https://linear.app/example/issue/PROJ-123
+  agents factory snapshot --json
 `);
-    factory.hook('preAction', () => {
-        if (enabled)
+    factory.hook('preAction', (_thisCommand, actionCommand) => {
+        // Foreman must be able to read its tick input before any beta-gated action.
+        if (enabled || actionCommand.name() === 'snapshot')
             return;
         console.error(chalk.red('agents factory is in beta.'));
         console.error(chalk.gray(betaEnableHint('factory')));
         process.exit(1);
     });
+    factory
+        .command('snapshot')
+        .description('Read the complete Software Factory state without dispatching or changing it.')
+        .option('--json', 'Output the stable machine-readable snapshot')
+        .action(async (opts) => {
+        const snapshot = await buildFactorySnapshot();
+        if (opts.json) {
+            console.log(JSON.stringify(snapshot, null, 2));
+            return;
+        }
+        renderSnapshot(snapshot);
+    });
     factory
         .command('submit <linear-ref>')
         .description('Submit a Linear issue (PROJ-123 or URL) to the Software Factory.')
@@ -93,3 +108,12 @@ Examples:
         console.log(`  tail output  agents cloud logs ${result.cloud_execution_id}`);
     });
 }
+function renderSnapshot(snapshot) {
+    console.log(chalk.bold(`Factory snapshot ${snapshot.generatedAt}`));
+    console.log(`  sessions     ${snapshot.sessions.length}`);
+    console.log(`  open PRs     ${snapshot.prs.length}`);
+    console.log(`  devices      ${snapshot.devices.length}`);
+    for (const [project, queue] of Object.entries(snapshot.queues)) {
+        console.log(`  ${project.padEnd(12)} todo ${queue.todo} · in progress ${queue.inProgress} · blocked ${queue.blocked}`);
+    }
+}

package/dist/commands/funnel.js

@@ -1,5 +1,5 @@
 import chalk from 'chalk';
-import { buildFunnelStatusCommand, buildFunnelUpCommand, parseFunnelPort } from '../lib/funnel.js';
+import { buildFunnelDownCommand, buildFunnelStatusCommand, buildFunnelUpCommand, parseFunnelPort } from '../lib/funnel.js';
 import { resolveHost } from '../lib/hosts/registry.js';
 import { resolveRemoteOsSync } from '../lib/hosts/remote-os.js';
 import { sshTargetFor } from '../lib/hosts/types.js';
@@ -59,4 +59,19 @@ export function registerFunnelCommand(program) {
             process.exit(1);
         }
     });
+    funnel
+        .command('down <host>')
+        .description('Disable Tailscale Funnel exposure for a public HTTPS port.')
+        .option('--port <n>', 'Public Funnel port: 443, 8443, or 10000', '443')
+        .action(async (host, opts) => {
+        try {
+            const publicPort = parseFunnelPort(opts.port ?? '443');
+            await runOnHost(host, buildFunnelDownCommand(publicPort));
+            console.log(chalk.green(`Funnel disabled on ${host}: public :${publicPort}`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
 }

package/dist/commands/inspect.js

@@ -32,6 +32,7 @@ import { listMcpServerConfigs, discoverMcpConfigsFromRepo } from '../lib/mcp.js'
 import { discoverPlugins, discoverPluginsInDir, pluginResourceGroups } from '../lib/plugins.js';
 import { PLUGIN_GROUP_COLORS } from './plugins.js';
 import { countSessionsInScope } from '../lib/session/discover.js';
+import { isSessionTrackedAgent } from '../lib/session/types.js';
 import { damerauLevenshtein } from '../lib/fuzzy.js';
 import { terminalWidth, truncateToWidth, stringWidth, stripAnsi } from '../lib/session/width.js';
 /** Resource kinds the inspect command can drill into. */
@@ -1256,14 +1257,11 @@ function safeStat(p) {
         return null;
     }
 }
-const SESSION_AGENTS = new Set([
-    'claude', 'codex', 'gemini', 'opencode', 'openclaw', 'rush', 'hermes', 'grok', 'kimi', 'droid',
-]);
 function safeCountSessions(agent) {
-    if (!SESSION_AGENTS.has(agent))
+    if (!isSessionTrackedAgent(agent))
         return 0;
     try {
-        return countSessionsInScope({ agent: agent });
+        return countSessionsInScope({ agent });
     }
     catch {
         return 0;

package/dist/commands/menubar.js

@@ -7,7 +7,8 @@
  * user; these commands are the manual override.
  */
 import chalk from 'chalk';
-import { enableMenubarService, disableMenubarService, getMenubarStatus, } from '../lib/menubar/install-menubar.js';
+import { setHelpSections } from '../lib/help.js';
+import { enableMenubarService, disableMenubarService, getMenubarStatus, runMenubarSetup, } from '../lib/menubar/install-menubar.js';
 function notMac() {
     if (process.platform !== 'darwin') {
         console.log(chalk.yellow('The menu bar helper is macOS only.'));
@@ -15,10 +16,122 @@ function notMac() {
     }
     return false;
 }
+/** Shared status readout — `status`, bare `menubar`, and `setup --check` all end here. */
+function printStatus(s, opts = {}) {
+    const yn = (b) => (b ? chalk.green('yes') : chalk.gray('no'));
+    console.log(chalk.bold('Menu bar helper\n'));
+    console.log(`  running            ${yn(s.running)}`);
+    console.log(`  service installed  ${yn(s.serviceInstalled)}`);
+    if (opts.brief) {
+        console.log(chalk.gray('\n  setup | enable | disable | status'));
+        return;
+    }
+    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)}`);
+    // Two copies of the INSTALLED bundle is the duplicate the user sees as two
+    // agents marks in the menu bar. It used to read as a healthy `running: yes`.
+    if (s.instances.length > 1) {
+        console.log(chalk.yellow(`\n  ${s.instances.length} copies of the installed helper are running — that is the duplicate menu-bar icon:`));
+        for (const p of s.instances)
+            console.log(chalk.gray(`    ${p.pid}  ${p.executable}`));
+        console.log(chalk.gray('  Fix it with `agents menubar setup`.'));
+    }
+    if (s.foreignInstances.length > 0) {
+        // RegisterEventHotKey is first-come, so the helper that registered the
+        // chord first owns Cmd-Shift-V/O. A process list cannot say which that
+        // was — only that a rival exists — so report the conflict, not a winner.
+        // The loser has no other symptom: its chords simply never fire.
+        const n = s.foreignInstances.length;
+        console.log(chalk.yellow(`\n  ${n} other helper process${n === 1 ? '' : 'es'} running — ${n === 1 ? 'it' : 'they'} may hold Cmd-Shift-V/O instead of the installed one:`));
+        for (const p of s.foreignInstances)
+            console.log(chalk.gray(`    ${p.pid}  ${p.executable}`));
+        console.log(chalk.gray('  End them with `agents menubar setup`.'));
+    }
+    if (s.stale) {
+        console.log(chalk.yellow('\n  Installed helper is stale — runs on next `agents` startup, or `agents menubar setup` now.'));
+    }
+    else if (!s.serviceInstalled && !s.disabledByUser) {
+        console.log(chalk.gray('\n  Set it up with `agents menubar setup`.'));
+    }
+}
+function printSetupResult(r) {
+    console.log(chalk.bold('Menu bar setup\n'));
+    for (const step of r.steps) {
+        const mark = step.outcome === 'failed' ? chalk.red('✗')
+            : step.outcome === 'changed' ? chalk.green('+') : chalk.green('✓');
+        console.log(`  ${mark} ${step.name.padEnd(15)} ${chalk.gray(step.detail)}`);
+    }
+    console.log();
+    if (r.configured) {
+        console.log(chalk.green('Menu bar configured.') + chalk.gray('  One agents mark, started at login.'));
+    }
+    else {
+        console.log(chalk.red('Menu bar not fully configured.') + chalk.gray('  See the failed step above.'));
+    }
+}
 export function registerMenubarCommands(program) {
     const menubar = program
         .command('menubar')
         .description('Manage the macOS menu-bar helper (running sessions, agents awaiting input, routines)');
+    // `setup` is the one command that gets a machine to the intended state:
+    // exactly one status item, started at login. `enable` stays the narrow
+    // install+start; setup adds duplicate cleanup and verifies the end state.
+    const setup = menubar
+        .command('setup')
+        .description('Configure the menu bar end-to-end: one instance, started at login')
+        .option('--check', 'Report the current state, change nothing')
+        .option('--json', 'Emit machine-readable JSON')
+        .action((options) => {
+        if (options.check) {
+            const s = getMenubarStatus();
+            if (options.json) {
+                process.stdout.write(JSON.stringify(s) + '\n');
+                return;
+            }
+            if (notMac())
+                return;
+            printStatus(s);
+            return;
+        }
+        if (!options.json && notMac())
+            return;
+        const r = runMenubarSetup();
+        if (options.json) {
+            process.stdout.write(JSON.stringify(r) + '\n');
+        }
+        else {
+            printSetupResult(r);
+        }
+        if (!r.configured)
+            process.exitCode = 1;
+    });
+    setHelpSections(setup, {
+        examples: `
+      # Configure the menu bar end-to-end (idempotent — safe to re-run)
+      agents menubar setup
+
+      # Two agents marks in the menu bar? This ends the duplicate.
+      agents menubar setup
+
+      # See the current state without changing anything
+      agents menubar setup --check
+    `,
+        notes: `
+      Configures, in order: every running helper ended, the helper bundle at
+      ~/Library/Application Support/agents-cli, its code signature, the launchd
+      login item (com.phnx-labs.agents-menubar — RunAtLoad + KeepAlive), then
+      verifies exactly one helper came back up.
+
+      Every running helper is ended and launchd restarts one, so the survivor is
+      always the login-managed copy. Exits nonzero if it cannot reach that state.
+
+      Setup clears a previous \`agents menubar disable\`. To turn the menu bar off
+      again, run \`agents menubar disable\`.
+    `,
+    });
     menubar
         .command('enable')
         .description('Install and start the menu-bar helper (launches at login)')
@@ -40,7 +153,7 @@ export function registerMenubarCommands(program) {
         if (notMac())
             return;
         disableMenubarService();
-        console.log(chalk.green('Menu bar helper disabled.') + chalk.gray('  Re-enable any time with `agents menubar enable`.'));
+        console.log(chalk.green('Menu bar helper disabled.') + chalk.gray('  Re-enable any time with `agents menubar setup`.'));
     });
     menubar
         .command('status')
@@ -56,33 +169,7 @@ export function registerMenubarCommands(program) {
             console.log(chalk.yellow('The menu bar helper is macOS only.'));
             return;
         }
-        const yn = (b) => (b ? chalk.green('yes') : chalk.gray('no'));
-        console.log(chalk.bold('Menu bar helper\n'));
-        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.foreignInstances.length > 0) {
-            // RegisterEventHotKey is first-come, so the helper that registered the
-            // chord first owns Cmd-Shift-V/O. A process list cannot say which that
-            // was — only that a rival exists — so report the conflict, not a
-            // winner. The loser
-            // has no other symptom: its chords simply never fire.
-            const n = s.foreignInstances.length;
-            console.log(chalk.yellow(`\n  ${n} other helper process${n === 1 ? '' : 'es'} running — ${n === 1 ? 'it' : 'they'} may hold Cmd-Shift-V/O instead of the installed one:`));
-            for (const p of s.foreignInstances)
-                console.log(chalk.gray(`    ${p.pid}  ${p.executable}`));
-            console.log(chalk.gray('  End it, then `agents menubar enable` to restart the installed helper.'));
-        }
-        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`.'));
-        }
+        printStatus(s);
     });
     // Bare `agents menubar` -> status.
     menubar.action(() => {
@@ -91,10 +178,6 @@ export function registerMenubarCommands(program) {
             console.log(chalk.yellow('The menu bar helper is macOS only.'));
             return;
         }
-        const yn = (b) => (b ? chalk.green('yes') : chalk.gray('no'));
-        console.log(chalk.bold('Menu bar helper\n'));
-        console.log(`  running            ${yn(s.running)}`);
-        console.log(`  service installed  ${yn(s.serviceInstalled)}`);
-        console.log(chalk.gray('\n  enable | disable | status'));
+        printStatus(s, { brief: true });
     });
 }

package/dist/commands/routines.js

@@ -19,7 +19,7 @@ import { fireWebhookJobs, matchJobsToWebhook } from '../lib/triggers/webhook.js'
 import { getRoutinesDir } from '../lib/state.js';
 import { IS_WINDOWS } from '../lib/platform/index.js';
 import { safeJoin } from '../lib/paths.js';
-import { executeJob, executeJobDetached, monitorRunningJobs } from '../lib/runner.js';
+import { executeJob, executeJobDetached, monitorRunningJobs, ROUTINE_AGENT_IDS } from '../lib/runner.js';
 import { JobScheduler } from '../lib/scheduler.js';
 import { detectOverdueJobs } from '../lib/overdue.js';
 import { isInteractiveTerminal, requireInteractiveSelection } from './utils.js';
@@ -70,6 +70,8 @@ function fireConditionLabel(job) {
             job.trigger.action ? `action=${job.trigger.action}` : null,
             job.trigger.teamKey ? `team=${job.trigger.teamKey}` : null,
             job.trigger.label ? `label=${job.trigger.label}` : null,
+            job.trigger.stateTo ? `stateTo=${job.trigger.stateTo}` : null,
+            job.trigger.stateFrom ? `stateFrom=${job.trigger.stateFrom}` : null,
         ].filter(Boolean).join(', ');
         return `on linear:${job.trigger.event}${filters ? ` (${filters})` : ''}`;
     }
@@ -261,6 +263,10 @@ function parseRoutineTrigger(options) {
             trigger.teamKey = options.teamKey;
         if (typeof options.label === 'string')
             trigger.label = options.label;
+        if (typeof options.stateTo === 'string')
+            trigger.stateTo = options.stateTo;
+        if (typeof options.stateFrom === 'string')
+            trigger.stateFrom = options.stateFrom;
         return trigger;
     }
     throw new Error('--on source must be github or linear');
@@ -572,7 +578,7 @@ export function registerRoutinesCommands(program) {
         .command('add [nameOrPath]')
         .description('Create a new routine from a YAML file or inline flags. Starts the scheduler automatically if it is not already running.')
         .option('-s, --schedule <cron>', 'Cron schedule in standard format (5 fields: minute hour day month weekday)')
-        .option('-a, --agent <agent>', 'Which agent runs this routine: claude, codex, antigravity, cursor, or opencode')
+        .option('-a, --agent <agent>', `Which agent runs this routine: ${ROUTINE_AGENT_IDS.join(', ')}`)
         .option('--workflow <name>', 'Run an installed workflow (~/.agents/workflows/<name>) via `agents run`. Mutually exclusive with --agent.')
         .option('--command <sh>', 'Run a plain shell command directly (no agent, no auth, no sandbox) — for deterministic housekeeping routines. Mutually exclusive with --agent and --workflow; --prompt is not used.')
         .option('-p, --prompt <prompt>', 'Task instruction for the agent')
@@ -591,6 +597,8 @@ export function registerRoutinesCommands(program) {
         .option('--action <name>', 'Webhook action filter for --on triggers (GitHub: labeled/opened; Linear: update)')
         .option('--team-key <key>', 'Linear team key filter for --on linear:<event> (e.g. RUSH)')
         .option('--label <name>', 'Label filter for --on triggers (GitHub label name or Linear issue label)')
+        .option('--state-to <name>', 'Linear current-state filter for --on linear:<event> (e.g. Plan)')
+        .option('--state-from <name>', 'Linear previous-state filter for --on linear:<event> (e.g. Triage)')
         .option('--end-at <iso>', 'Stop firing on or after this ISO 8601 timestamp (e.g., "2026-12-31T23:59:00Z"); routine auto-disables.')
         .option('--disabled', 'Create the routine but keep it paused (enable later with resume)')
         .option('--resume <sessionId>', 'At fire time, resume this existing session id (via `agents run <agent> --resume`) instead of starting fresh — the actual session reopens with full context and the prompt becomes its next turn. Powers self-scheduled wake-ups (e.g. /hibernate). Requires --agent claude or codex; runs un-sandboxed (the session store lives in the real home, not the job overlay).')
@@ -884,12 +892,26 @@ export function registerRoutinesCommands(program) {
     routinesCmd
         .command('edit [name]')
         .description('Open a routine in $EDITOR. Creates a new YAML template if the routine does not exist.')
-        .action(async (name) => {
+        .option('--state-to <name>', 'Update the Linear current-state filter before opening the editor')
+        .option('--state-from <name>', 'Update the Linear previous-state filter before opening the editor')
+        .action(async (name, options) => {
         if (!name) {
             name = await pickJob('Select job to edit', undefined, ['agents routines edit <name>']) ?? undefined;
             if (!name)
                 return;
         }
+        const existing = readJob(name);
+        if (existing && (options.stateTo !== undefined || options.stateFrom !== undefined)) {
+            if (!existing.trigger || existing.trigger.type !== 'linear_event') {
+                console.error(chalk.red(`'${name}' does not have a Linear trigger; --state-to/--state-from only apply to linear triggers`));
+                process.exit(1);
+            }
+            if (options.stateTo !== undefined)
+                existing.trigger.stateTo = options.stateTo || undefined;
+            if (options.stateFrom !== undefined)
+                existing.trigger.stateFrom = options.stateFrom || undefined;
+            writeJob(existing);
+        }
         const jobPath = getJobPath(name);
         if (!jobPath) {
             // Job doesn't exist - create a new one

package/dist/commands/secrets-rotate-passphrase.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `agents secrets rotate-passphrase` — rotate the encrypted file store's
+ * machine-local master passphrase (RUSH-1975).
+ *
+ * Re-encrypts every `<item>.enc` under a freshly generated key and rewrites the
+ * 0600 key file in place, atomically: the new store is staged, verified
+ * (round-trip + count), fsync'd, then swapped by directory rename, so a crash
+ * leaves the old store intact and readable. Headless-safe and Linux-first — the
+ * remediation path for a compromised passphrase (RUSH-1968), where the two
+ * supported alternatives are unacceptable (a hand-rolled non-atomic script, or
+ * export-to-plaintext which is the exposure being fixed).
+ *
+ * Dry-run by default, matching `import-keyring`; `--commit` performs the swap.
+ */
+import type { Command } from 'commander';
+/** Register `agents secrets rotate-passphrase` on the parent secrets Command. */
+export declare function registerSecretsRotatePassphraseCommand(secrets: Command): void;

package/dist/commands/secrets-rotate-passphrase.js

@@ -0,0 +1,96 @@
+/**
+ * `agents secrets rotate-passphrase` — rotate the encrypted file store's
+ * machine-local master passphrase (RUSH-1975).
+ *
+ * Re-encrypts every `<item>.enc` under a freshly generated key and rewrites the
+ * 0600 key file in place, atomically: the new store is staged, verified
+ * (round-trip + count), fsync'd, then swapped by directory rename, so a crash
+ * leaves the old store intact and readable. Headless-safe and Linux-first — the
+ * remediation path for a compromised passphrase (RUSH-1968), where the two
+ * supported alternatives are unacceptable (a hand-rolled non-atomic script, or
+ * export-to-plaintext which is the exposure being fixed).
+ *
+ * Dry-run by default, matching `import-keyring`; `--commit` performs the swap.
+ */
+import chalk from 'chalk';
+import { machinePassphraseExists, rotatePassphrase } from '../lib/secrets/filestore.js';
+import { agentStatus } from '../lib/secrets/agent.js';
+/** Register `agents secrets rotate-passphrase` on the parent secrets Command. */
+export function registerSecretsRotatePassphraseCommand(secrets) {
+    secrets
+        .command('rotate-passphrase')
+        .description('Re-key the encrypted file store under a new machine-local passphrase (atomic, headless-safe). Dry-run by default.')
+        .option('--commit', 'Perform the rotation (default is dry-run reporting only)')
+        .option('--dry-run', 'Report bundle count and round-trip result without re-keying (the default). Still heals an interrupted rotation — that is the one thing it writes.')
+        .option('--force', 'Override the safety refusals (held broker unlocks, or a passphrase exported in the environment)')
+        .addHelpText('after', `
+Rotates the auto-provisioned file-store key at ~/.agents/.secrets-key/passphrase:
+decrypts every item under the current key, re-encrypts under a new one, verifies
+every item round-trips, then swaps the store and key file atomically. A crash
+before the swap leaves the old store readable with the old key; a crash inside the
+swap self-heals on the next rotate-passphrase run (not on an ordinary get). No
+plaintext secret value or passphrase is ever written to disk, argv, or a log.
+
+Examples:
+  # Report what would rotate (no writes)
+  agents secrets rotate-passphrase
+
+  # Perform the rotation
+  agents secrets rotate-passphrase --commit`)
+        .action(async (opts) => {
+        try {
+            if (opts.commit && opts.dryRun) {
+                throw new Error('--commit and --dry-run are mutually exclusive.');
+            }
+            const dryRun = !opts.commit;
+            if (!machinePassphraseExists()) {
+                throw new Error('No machine-local passphrase is provisioned on this box, so there is nothing to rotate. ' +
+                    'This command re-keys the file store\'s auto-provisioned key at ~/.agents/.secrets-key/passphrase.');
+            }
+            // Guard 1: refuse while the secrets-agent holds live unlocks (macOS), so a
+            // concurrent read cannot land against a half-swapped store. --force overrides.
+            if (!dryRun && !opts.force) {
+                const held = await agentStatus();
+                if (held.length > 0) {
+                    throw new Error(`The secrets-agent is holding ${held.length} unlocked bundle(s) (${held.map((e) => e.name).join(', ')}). ` +
+                        'Lock them first (`agents secrets lock --all`) so no concurrent read races the rotation, or pass --force.');
+                }
+            }
+            // Guard 2: a passphrase exported in the environment shadows the on-disk key
+            // file with a now-stale value after the rotation, breaking every read. This
+            // is the exact RUSH-1968 footgun — refuse the commit and point at the fix.
+            if (!dryRun && !opts.force && (process.env.AGENTS_SECRETS_PASSPHRASE ?? '').length > 0) {
+                throw new Error('AGENTS_SECRETS_PASSPHRASE is set in this environment; it would shadow the rotated key file ' +
+                    'with a stale value and break every read. Unset it (this is the RUSH-1968 fix) before rotating, or pass --force.');
+            }
+            const report = rotatePassphrase({ dryRun });
+            console.log(`${chalk.bold(String(report.bundleCount))} item(s) decrypt under the current key and ` +
+                `${report.roundTripOk ? chalk.green('round-trip cleanly') : chalk.red('failed to round-trip')} under a new key.`);
+            if (report.skipped.length > 0) {
+                console.log(chalk.gray(`skipped ${report.skipped.length} orphan file(s) (not re-keyed):`));
+                for (const s of report.skipped)
+                    console.log(chalk.gray(`  - ${s}`));
+            }
+            if (report.dryRun) {
+                if (report.recoveredInterruptedRotation) {
+                    // Be precise: this run DID write. Recovery is deliberately not gated on
+                    // --commit, because healing is how a crashed store becomes readable
+                    // again without re-keying it.
+                    console.log(chalk.yellow('Recovered an interrupted rotation: the store was healed back to a single ' +
+                        'readable state. That is the only thing this dry run wrote — no re-keying happened.'));
+                }
+                else {
+                    console.log(chalk.gray('Dry-run: nothing written.'));
+                }
+                console.log(chalk.gray(`Pass --commit to re-encrypt the store and swap the key file (${report.keyFilePath}).`));
+                return;
+            }
+            console.log(chalk.green(`Rotated: re-encrypted ${report.bundleCount} item(s) and rewrote ${report.keyFilePath} (mode 0600).`));
+            console.log(chalk.gray('The previous key and ciphertext were removed. Any process still holding the old passphrase in its environment must be restarted.'));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/secrets.js

@@ -38,6 +38,7 @@ import { getVaultSession, vaultExists } from '../lib/secrets/vault.js';
 import { registerSecretsSyncCommands } from './secrets-sync.js';
 import { registerSecretsMigrateAclCommand } from './secrets-migrate.js';
 import { registerSecretsImportKeyringCommand } from './secrets-import.js';
+import { registerSecretsRotatePassphraseCommand } from './secrets-rotate-passphrase.js';
 /** Prompt the user for a secret value with masked input. Requires an interactive TTY. */
 async function promptForSecret(message) {
     if (!isInteractiveTerminal()) {
@@ -2419,6 +2420,7 @@ Examples:
     registerSecretsSyncCommands(cmd);
     registerSecretsMigrateAclCommand(cmd);
     registerSecretsImportKeyringCommand(cmd);
+    registerSecretsRotatePassphraseCommand(cmd);
 }
 /** Validate a prompt-policy value, throwing a clear message on a bad one (the
  * caller's try/catch renders it and exits). Accepts the legacy `biometry` /

package/dist/commands/sessions.d.ts

@@ -136,11 +136,17 @@ export declare function linkCwdCell(s: Pick<SessionMeta, 'cwd' | '_remote'>, lab
  * (null when unknown) alongside the raw fields, so every active row is joinable.
  * `project` uses the same derivation SessionMeta does — basename(cwd) (see
  * discover.ts) — so the active view and the history view join identically.
+ *
+ * `viewingIn` flattens to the same display string the row renderer prints —
+ * `'codium tab 3'` / `'detached'` / null — so a consumer can tell a watched
+ * session from an orphaned one (its terminal died, the agent is still running)
+ * without re-implementing the tmux client lookup.
  */
-export declare function serializeActiveSessionsForJson(sessions: ActiveSession[]): Array<ActiveSession & {
+export declare function serializeActiveSessionsForJson(sessions: ActiveSession[]): Array<Omit<ActiveSession, 'viewingIn'> & {
     ticketId: string | null;
     project: string | null;
     prLink: string | null;
+    viewingIn: string | null;
 }>;
 /**
  * Compact owner display for the `--active` owner column: the local-part of a