@phnx-labs/agents-cli 1.22.23 → 1.22.24

package/dist/commands/go.js

@@ -28,8 +28,9 @@ import { isPromptCancelled } from './utils.js';
 import { focusAction } from './focus.js';
 import { machineId } from '../lib/session/sync/config.js';
 import { attachTmux, runTmux } from '../lib/tmux/binary.js';
+import { paneExitStatus } from '../lib/tmux/session.js';
 import { getDefaultSocketPath } from '../lib/tmux/paths.js';
-import { sshStream, assertValidSshTarget, shellQuote } from '../lib/ssh-exec.js';
+import { sshExec, sshStream, assertValidSshTarget, shellQuote } from '../lib/ssh-exec.js';
 import { enumerateGhosttyTabs, assignGhosttyTabs } from '../lib/session/ghostty-tabs.js';
 const execFileAsync = promisify(execFile);
 export function registerGoCommand(program) {
@@ -208,15 +209,48 @@ export function describeWhere(s, self) {
         return { label: `${s.host ?? 'shell'} on ${remote}`, action: `open a shell on ${remote}` };
     return { label: s.host ?? 'unknown terminal', action: 'resume it (no live attach rail)' };
 }
-/** Default (attach-only): open a login shell on the remote, or refuse locally. */
+/** Probe the tmux process, not just retained provenance. This is deliberately
+ * called immediately before an attach so remain-on-exit panes cannot masquerade
+ * as living agent sessions. */
+export async function probeAttachRail(s, self) {
+    const mux = s.provenance?.mux;
+    if (mux?.kind !== 'tmux' || !mux.pane)
+        return { state: 'missing' };
+    const remote = s.machine && s.machine !== self ? s.machine : undefined;
+    if (!remote) {
+        const pane = await paneExitStatus(mux.pane, mux.socket ?? getDefaultSocketPath());
+        if (!pane.found)
+            return { state: 'missing' };
+        return pane.dead ? { state: 'dead', exitStatus: pane.status } : { state: 'alive' };
+    }
+    assertValidSshTarget(remote);
+    const sock = mux.socket ? `-S ${shellQuote(mux.socket)} ` : '';
+    const pane = shellQuote(mux.pane);
+    const command = `v=$(tmux ${sock}display-message -pt ${pane} -p '#{pane_dead} #{pane_dead_status}' 2>/dev/null) || { echo missing; exit 0; }; ` +
+        `printf '%s\\n' "$v"`;
+    const result = sshExec(remote, command, { timeoutMs: 15_000, multiplex: true });
+    if (result.code !== 0)
+        return { state: 'missing' };
+    const value = result.stdout.trim();
+    if (value === 'missing' || !value)
+        return { state: 'missing' };
+    const [dead, rawStatus] = value.split(/\s+/);
+    const exitStatus = Number.parseInt(rawStatus ?? '', 10);
+    return dead === '1'
+        ? { state: 'dead', exitStatus: Number.isFinite(exitStatus) ? exitStatus : undefined }
+        : { state: 'alive' };
+}
+/** Strict attach-only fallback: no pane means no attach. Never open a shell or
+ * start recovery, because both would violate the caller's no-fork intent. */
 export async function refuseFallback(s, remote) {
     if (remote) {
-        console.log(chalk.yellow(`${shortId(s)} on ${remote} isn't inside tmux — opening a shell on ${remote} instead.`));
-        assertValidSshTarget(remote);
-        process.exit(sshStream(remote, 'exec "${SHELL:-/bin/sh}" -l', { tty: true }));
+        console.log(chalk.yellow(`Can't attach ${shortId(s)} on ${remote} — it has no living tmux pane.`));
+        process.exitCode = 1;
+        return;
     }
     console.log(chalk.yellow(`Can't jump to ${shortId(s)} — it's in ${s.host ?? 'an unknown terminal'} with no attach rail (not tmux/Ghostty).`) +
         chalk.gray(`\nTry: agents sessions resume ${shortId(s)}`));
+    process.exitCode = 1;
 }
 export async function jumpTo(s, self, fallback = refuseFallback) {
     const remote = s.machine && s.machine !== self ? s.machine : undefined;
@@ -224,6 +258,11 @@ export async function jumpTo(s, self, fallback = refuseFallback) {
     // Path C: remote tmux — ssh in and attach, resolving the pane's session on the remote.
     if (remote) {
         if (mux?.kind === 'tmux' && mux.pane) {
+            const liveness = await probeAttachRail(s, self);
+            if (liveness.state !== 'alive') {
+                await fallback(s, remote);
+                return;
+            }
             assertValidSshTarget(remote);
             const sock = mux.socket ? `-S ${shellQuote(mux.socket)} ` : '';
             const p = shellQuote(mux.pane);
@@ -240,6 +279,11 @@ export async function jumpTo(s, self, fallback = refuseFallback) {
     }
     // Path B: local tmux — attach (or switch-client if we're already inside tmux).
     if (mux?.kind === 'tmux' && mux.pane) {
+        const liveness = await probeAttachRail(s, self);
+        if (liveness.state !== 'alive') {
+            await fallback(s, undefined);
+            return;
+        }
         const socket = mux.socket ?? getDefaultSocketPath();
         const { session, window } = await resolveLocalPane(socket, mux.pane);
         if (session && window != null) {

package/dist/commands/insights.js

@@ -340,7 +340,10 @@ async function insightsAction(options) {
         console.error(chalk.red('error: --min-messages must be a non-negative integer'));
         process.exit(1);
     }
-    const since = options.since ?? '30d';
+    // `--all` is the spelling people reach for; `--since all` is what the window parser
+    // speaks. Accept both rather than failing on an unknown option, and let an explicit
+    // --since win so `--all --since 7d` is not silently contradictory.
+    const since = options.since ?? (options.all ? 'all' : '30d');
     const sinceMs = since === 'all' ? undefined : parseTimeFilter(since);
     // Refresh the index first, exactly as `agents cost` does, so a report never silently
     // describes a stale picture of disk.
@@ -436,6 +439,7 @@ export function registerInsightsCommand(program) {
         .description('How you work — tools, friction, and rhythm, split by the account that did the work')
         .option('--json', 'Output the full report as JSON')
         .option('--since <time>', 'Window: 7d, 4w, 3mo, an ISO date, or "all" (default 30d)')
+        .option('--all', 'Every session ever indexed. Alias for --since all')
         .option('--by <dimension>', 'Group by: account (default), agent, project, or day')
         .option('--account <match>', 'Only sessions whose account key, email, or org contains this')
         .option('--agent <id>', 'Only one harness (claude, codex, droid, …)')
@@ -454,7 +458,7 @@ export function registerInsightsCommand(program) {
       agents insights --by project --since 90d
 
       # One account only, all of its history
-      agents insights --account "Turing Labs" --since all
+      agents insights --account "Turing Labs" --all
 
       # Machine-readable, for a dashboard or a slash command
       agents insights --json

package/dist/commands/inspect.js

@@ -22,12 +22,14 @@ import * as yaml from 'yaml';
 import { AGENTS, getCliState, resolveAgentName } from '../lib/agents.js';
 import { supports } from '../lib/capabilities.js';
 import { resolveConfiguredModel } from '../lib/models.js';
+import { getAgentModesCatalog } from '../lib/agent-modes.js';
 import { resolveSingleAgentTarget, AgentSpecError } from '../lib/agent-spec/index.js';
 import { readMeta, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getEnabledExtraRepos, } from '../lib/state.js';
 import { getVersionHomePath, isVersionIsolated, getIsolatedDefault, } from '../lib/versions.js';
 import { getShimsDir, getVersionedAliasPath } from '../lib/shims.js';
 import { getAgentResources, listResources, } from '../lib/resources.js';
 import { listHookEntriesFromDir } from '../lib/hooks.js';
+import { getResourceInventory } from '../lib/resource-inventory.js';
 import { listMcpServerConfigs, discoverMcpConfigsFromRepo } from '../lib/mcp.js';
 import { discoverPlugins, discoverPluginsInDir, pluginResourceGroups } from '../lib/plugins.js';
 import { PLUGIN_GROUP_COLORS } from './plugins.js';
@@ -113,7 +115,7 @@ function truncateValueForPrefix(prefix, value) {
 // ─── Command registration ────────────────────────────────────────────────────
 export function registerInspectCommand(program) {
     const cmd = addHostOption(program.command('inspect <target>'))
-        .description('Inspect one installed agent at one version, or a DotAgents repo (user|system|project|alias|path) — paths, capabilities, resources, drill into any kind.')
+        .description('Inspect one installed agent harness at one version (not a model), or a DotAgents repo — paths, capabilities, resources, and hook capable/on-disk/wired state.')
         .option('--brief', 'header + capabilities only; skip resources/sessions')
         .option('--json', 'machine-readable JSON output');
     for (const kind of DRILLABLE_KINDS) {
@@ -575,12 +577,14 @@ async function renderSummary(agent, version, versionHome, options) {
     const isIsolatedDefault = isolated && getIsolatedDefault(agent) === version;
     const capabilities = collectCapabilities(agent, version);
     const itemsByKind = options.brief ? null : collectItemsByKind(agent, versionHome);
+    const hookInventory = options.brief ? null : getResourceInventory(agent, version, 'hooks');
     const hookByScript = options.brief ? null : hookManifestByScript(loadCentralHookManifest());
     const mcpConfigs = options.brief ? null : new Map(listMcpServerConfigs().map(s => [s.name, s.config]));
     const sessions = options.brief ? null : {
         total: safeCountSessions(agent),
     };
     if (options.json) {
+        const modeCat = getAgentModesCatalog(agent, version);
         const json = {
             agent,
             version,
@@ -594,7 +598,14 @@ async function renderSummary(agent, version, versionHome, options) {
             strategy,
             installedShim: cliState?.installed === true ? cliState.path : null,
             capabilities,
-            resources: itemsByKind ? summaryResourcesJson(itemsByKind, hookByScript, mcpConfigs) : null,
+            modes: {
+                supported: modeCat.modes.map((m) => m.mode),
+                defaultMode: modeCat.defaultMode,
+                configuredMode: modeCat.configuredMode,
+                headlessPlan: modeCat.headlessPlan,
+                unsupported: modeCat.unsupported,
+            },
+            resources: itemsByKind ? summaryResourcesJson(itemsByKind, hookByScript, mcpConfigs, hookInventory) : null,
             sessions,
         };
         console.log(JSON.stringify(json, null, 2));
@@ -623,12 +634,23 @@ async function renderSummary(agent, version, versionHome, options) {
         const reason = res.ok ? '' : chalk.gray(`(${res.reason}${res.need ? ' ' + res.need : ''})`);
         console.log(`  ${cap.padEnd(10)} ${mark} ${reason}`);
     }
+    // Permission modes are a separate axis from the capability booleans above —
+    // same data as `agents modes <agent>`, kept next to the rest of the inspect
+    // surface so a human/agent does not have to leave this view.
+    {
+        const modeCat = getAgentModesCatalog(agent, version);
+        const modeList = modeCat.modes.map((m) => (m.isDefault ? `${m.mode}*` : m.mode)).join('/');
+        const cfg = modeCat.configuredMode ? chalk.gray(`  run default: ${modeCat.configuredMode}`) : '';
+        console.log(`  ${'modes'.padEnd(10)} ${chalk.cyan(modeList)}${cfg}`);
+        console.log(chalk.gray(`             agents modes ${agent}  ·  agents models ${agent}@${version}`));
+    }
     if (itemsByKind) {
         console.log('\n' + chalk.bold('Resources'));
         for (const kind of SIMPLE_KINDS) {
             printSimpleResourceRow(kind, itemsByKind[kind]);
         }
-        printExpandedSection('Hooks', hookRows(itemsByKind.hooks, hookByScript));
+        console.log(`  ${chalk.bold('Hooks')}  ${chalk.gray(formatHookInventoryCounts(hookInventory))}`);
+        printExpandedSection('Hook files', hookRows(itemsByKind.hooks, hookByScript));
         printExpandedSection('Plugins', pluginRows(itemsByKind.plugins));
         printExpandedSection('MCP', mcpRows(itemsByKind.mcp, mcpConfigs));
     }
@@ -769,13 +791,20 @@ function printSimpleResourceRow(kind, items) {
  * simple kinds add `names`, and the rich kinds add structured `items` (hook
  * events/predicates, mcp transport/url/command, plugin version + group counts).
  */
-function summaryResourcesJson(itemsByKind, hookByScript, mcpConfigs) {
+function summaryResourcesJson(itemsByKind, hookByScript, mcpConfigs, hookInventory) {
     const out = {};
     for (const kind of DRILLABLE_KINDS) {
         const items = itemsByKind[kind];
         const base = { total: items.length, bySource: countBySource(items.map(i => i.source)) };
         if (kind === 'hooks') {
-            out[kind] = { ...base, items: items.map(i => {
+            out[kind] = { ...base,
+                capable: hookInventory.capable,
+                declared: hookInventory.declared,
+                onDisk: hookInventory.onDisk,
+                wired: hookInventory.wired,
+                unmanaged: hookInventory.unmanaged,
+                wiringSupported: hookInventory.wiringSupported,
+                items: items.map(i => {
                     const h = hookByScript.get(i.name);
                     return { name: i.name, source: i.source, events: h?.events ?? [], matcher: h?.matcher, matches: h?.matches, cache: h?.cache };
                 }) };
@@ -800,6 +829,11 @@ function summaryResourcesJson(itemsByKind, hookByScript, mcpConfigs) {
     }
     return out;
 }
+function formatHookInventoryCounts(inventory) {
+    const wired = inventory.wiringSupported ? String(inventory.wired.length) : 'unknown';
+    const unmanaged = inventory.unmanaged.length > 0 ? ` · unmanaged ${inventory.unmanaged.length}` : '';
+    return `capable ${inventory.capable ? 'yes' : 'no'} · on-disk ${inventory.onDisk.length} · wired ${wired}${unmanaged}`;
+}
 function collectKind(agent, versionHome, kind) {
     switch (kind) {
         case 'commands':

package/dist/commands/menubar.js

@@ -51,7 +51,12 @@ function printStatus(s, opts = {}) {
         console.log(chalk.gray('  End them with `agents menubar setup`.'));
     }
     if (s.stale) {
-        console.log(chalk.yellow('\n  Installed AGI Menu is stale — runs on next `agents` startup, or `agents menubar setup` now.'));
+        // Not "runs on next startup": the self-heal only reinstalls from the install
+        // that owns the helper, or from another one once the takeover cooldown has
+        // passed (mayInstallMenubarHelper) — so on a box with several agents-cli
+        // copies this can persist for a while. `setup` bypasses the gate and is the
+        // immediate fix.
+        console.log(chalk.yellow('\n  Installed AGI Menu is stale — `agents menubar setup` updates it now.'));
     }
     else if (!s.serviceInstalled && !s.disabledByUser) {
         console.log(chalk.gray('\n  Set it up with `agents menubar setup`.'));

package/dist/commands/models.js

@@ -72,6 +72,7 @@ export function registerModelsCommand(program) {
         if (!agentSpec && !all) {
             console.log(chalk.gray('\n  `agents models <agent>` for one harness · `--all` for the full model list'));
             console.log(chalk.gray('  `agents models tier set <agent> <tier> <model>` to override a tier'));
+            console.log(chalk.gray('  Permission modes (--mode plan|edit|auto|skip): `agents modes <agent>`'));
         }
     });
     // Override subcommands. These WRITE agents.yaml so the user never hand-edits it;

package/dist/commands/modes.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `agents modes` — list the permission modes a harness accepts for
+ * `agents run` / `agents teams add`.
+ *
+ * Mirror of `agents models`: humans and orchestrating agents read this before
+ * picking `--mode plan|edit|auto|skip`. Modes are per-agent today (not version-
+ * gated); `agent@version` is accepted so the configured run.defaults mode for
+ * that version can be shown beside the catalog.
+ */
+import type { Command } from 'commander';
+/** Register `agents modes [agent[@version]]`. */
+export declare function registerModesCommand(program: Command): void;

package/dist/commands/modes.js

@@ -0,0 +1,147 @@
+/**
+ * `agents modes` — list the permission modes a harness accepts for
+ * `agents run` / `agents teams add`.
+ *
+ * Mirror of `agents models`: humans and orchestrating agents read this before
+ * picking `--mode plan|edit|auto|skip`. Modes are per-agent today (not version-
+ * gated); `agent@version` is accepted so the configured run.defaults mode for
+ * that version can be shown beside the catalog.
+ */
+import chalk from 'chalk';
+import { AGENTS, ALL_AGENT_IDS, agentLabel, formatAgentError, resolveAgentName, } from '../lib/agents.js';
+import { formatModeFlags, getAgentModesCatalog, } from '../lib/agent-modes.js';
+import { setHelpSections } from '../lib/help.js';
+import { getGlobalDefault, listInstalledVersions, resolveVersion, resolveVersionAlias } from '../lib/versions.js';
+/** Agents that show in the no-arg overview (skip hard-deprecated). */
+const MODE_AGENTS = ALL_AGENT_IDS.filter((id) => !AGENTS[id].deprecated?.hard);
+/** Register `agents modes [agent[@version]]`. */
+export function registerModesCommand(program) {
+    const modes = program
+        .command('modes [agentSpec]')
+        .description('Show which permission modes (--mode plan|edit|auto|skip) a harness supports for agents run / teams add')
+        .option('--json', 'Output machine-readable JSON')
+        .action((agentSpec, options) => {
+        const targets = resolveTargets(agentSpec);
+        if (targets.length === 0)
+            process.exit(1);
+        if (options.json) {
+            const out = targets.map(({ agent, version }) => {
+                const catalog = getAgentModesCatalog(agent, version);
+                return {
+                    agent,
+                    version,
+                    defaultMode: catalog.defaultMode,
+                    configuredMode: catalog.configuredMode,
+                    configuredModeSource: catalog.configuredModeSource,
+                    headlessPlan: catalog.headlessPlan,
+                    modes: catalog.modes.map((m) => ({
+                        mode: m.mode,
+                        flags: m.flags,
+                        description: m.description,
+                        isDefault: m.isDefault,
+                    })),
+                    unsupported: catalog.unsupported,
+                    notes: catalog.notes,
+                };
+            });
+            console.log(JSON.stringify(out, null, 2));
+            return;
+        }
+        let printed = 0;
+        for (const { agent, version, isDefault } of targets) {
+            if (printed > 0)
+                console.log();
+            printCatalog(getAgentModesCatalog(agent, version), version, isDefault);
+            printed++;
+        }
+        if (!agentSpec) {
+            console.log(chalk.gray('\n  `agents modes <agent>` for one harness · `agents modes claude@2.1.219` for a version\'s run default'));
+            console.log(chalk.gray('  Pass --mode on `agents run` / `agents teams add`. Models: `agents models <agent>`.'));
+        }
+    });
+    setHelpSections(modes, {
+        examples: `
+      agents modes
+      agents modes claude
+      agents modes claude@2.1.219
+      agents modes cursor --json
+    `,
+        notes: `
+      Permission modes control how much the agent can do (not which LLM model
+      runs — that is --model / agents models). Supported modes come from each
+      harness's capabilities table; unsupported requests degrade (auto→edit,
+      plan→safest native) or error (skip when missing).
+      'full' is a silent alias for skip.
+      agent@version is accepted so any configured run.defaults mode for that
+      version is shown; the mode list itself is per-agent today.
+    `,
+    });
+}
+function resolveTargets(agentSpec) {
+    if (!agentSpec) {
+        const targets = [];
+        for (const agent of MODE_AGENTS) {
+            const version = getGlobalDefault(agent) || listInstalledVersions(agent)[0] || null;
+            targets.push({ agent, version, isDefault: true });
+        }
+        return targets;
+    }
+    const [agentName, versionSpec] = agentSpec.split('@');
+    const agent = resolveAgentName(agentName);
+    if (!agent) {
+        console.error(chalk.red(formatAgentError(agentName, MODE_AGENTS)));
+        return [];
+    }
+    if (AGENTS[agent].deprecated?.hard) {
+        console.error(chalk.yellow(`${agent} is deprecated and no longer supports run modes.`));
+        return [];
+    }
+    if (versionSpec === 'all') {
+        const installed = listInstalledVersions(agent);
+        if (installed.length === 0) {
+            return [{ agent, version: null, isDefault: true }];
+        }
+        return installed.map((v) => ({
+            agent,
+            version: v,
+            isDefault: v === getGlobalDefault(agent),
+        }));
+    }
+    if (versionSpec) {
+        // resolveVersionAlias exits process if the concrete version is not installed.
+        const version = resolveVersionAlias(agent, versionSpec) ?? null;
+        return [{ agent, version, isDefault: version === getGlobalDefault(agent) }];
+    }
+    const version = resolveVersion(agent, process.cwd()) || getGlobalDefault(agent) || null;
+    return [{ agent, version, isDefault: true }];
+}
+function printCatalog(catalog, version, isDefault) {
+    const tag = version
+        ? ` ${chalk.bold(version)}${isDefault ? chalk.gray(' (default)') : ''}`
+        : chalk.gray(' (not installed)');
+    console.log(`${agentLabel(catalog.agent)}${tag}`);
+    console.log(chalk.gray('  modes:'));
+    for (const entry of catalog.modes) {
+        const star = entry.isDefault ? chalk.cyan('*') : ' ';
+        const flags = chalk.gray(formatModeFlags(entry.flags));
+        console.log(`  ${star} ${chalk.cyan(entry.mode.padEnd(6))} ${chalk.bold(entry.description)}  ${flags}`);
+    }
+    if (catalog.unsupported.length > 0) {
+        console.log(chalk.gray(`  unsupported: ${catalog.unsupported.join(', ')}`));
+    }
+    const defaultBits = [`native default ${chalk.white(catalog.defaultMode)}`];
+    if (catalog.configuredMode) {
+        const src = catalog.configuredModeSource ? chalk.gray(` (${catalog.configuredModeSource})`) : '';
+        defaultBits.push(`run default ${chalk.white(catalog.configuredMode)}${src}`);
+    }
+    console.log(chalk.gray(`  ${defaultBits.join(' · ')}`));
+    if (!catalog.headlessPlan && catalog.modes.some((m) => m.mode === 'plan')) {
+        console.log(chalk.yellow('  headless plan: not supported (interactive plan still works)'));
+    }
+    for (const note of catalog.notes) {
+        // Keep the full-alias note quiet; surface degrades more visibly.
+        if (note.startsWith("'full'"))
+            continue;
+        console.log(chalk.gray(`  note: ${note}`));
+    }
+}

package/dist/commands/secrets-sync.js

@@ -10,9 +10,10 @@ import chalk from 'chalk';
 import { listRemoteBundles, MIN_PASSPHRASE_LEN, pullBundle, pushBundle, } from '../lib/secrets/sync.js';
 import { bundleExists, listBundles } from '../lib/secrets/bundles.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+import { missingSyncPassphraseMessage, resolveSyncPassphraseFromEnv, warnEnvPassphraseReadableOnce, } from '../lib/secrets/sync-passphrase.js';
 async function promptPassphrase(message, confirm = false) {
     if (!isInteractiveTerminal()) {
-        throw new Error('A sync passphrase is required. Run from a TTY, or set AGENTS_SECRETS_PASSPHRASE.');
+        throw new Error(missingSyncPassphraseMessage());
     }
     const { password } = await import('@inquirer/prompts');
     const first = await password({ message, mask: true });
@@ -25,21 +26,18 @@ async function promptPassphrase(message, confirm = false) {
         throw new Error('Passphrases do not match.');
     return first;
 }
-// Print the env-var-source warning at most once per process so a `--all` push
-// over many bundles doesn't flood stderr with the same notice.
-let envPassphraseWarned = false;
 function passphraseFromEnvOrPrompt(confirm) {
-    const fromEnv = process.env.AGENTS_SECRETS_PASSPHRASE;
-    if (fromEnv) {
-        if (fromEnv.length < MIN_PASSPHRASE_LEN) {
+    // Env resolution (current name, then the deprecated master-key name) lives in
+    // lib/secrets/sync-passphrase.ts so this command and `agents sync` share one
+    // chokepoint — otherwise each call site warns separately and the "once per
+    // process" promise is a lie.
+    const { value } = resolveSyncPassphraseFromEnv();
+    if (value) {
+        if (value.length < MIN_PASSPHRASE_LEN) {
             return Promise.reject(new Error(`Passphrase must be at least ${MIN_PASSPHRASE_LEN} characters.`));
         }
-        if (!envPassphraseWarned) {
-            envPassphraseWarned = true;
-            process.stderr.write(chalk.yellow('warn: using AGENTS_SECRETS_PASSPHRASE. Env vars are readable by other same-user processes ' +
-                '(/proc, ps, crash dumps, CI logs) — rotate the passphrase after CI use.\n'));
-        }
-        return Promise.resolve(fromEnv);
+        warnEnvPassphraseReadableOnce();
+        return Promise.resolve(value);
     }
     return promptPassphrase('Sync passphrase', confirm);
 }

package/dist/commands/secrets.d.ts

@@ -48,9 +48,11 @@ export declare function parseImportSource(opts: {
  * defaults). Shared with the command action so the wiring is unit-testable
  * without a live SSH session.
  */
+export declare function resolveUnlockTtlMs(ttl: string | undefined, until: string | undefined, now?: number): number;
 export declare function buildRemoteUnlockArgs(names: string[], opts: {
     all?: boolean;
     ttl?: string;
+    until?: string;
     durable?: boolean;
 }): string[];
 /**

package/dist/commands/secrets.js

@@ -31,6 +31,7 @@ import { readMeta } from '../lib/state.js';
 import { parseDuration } from '../lib/hooks/cache.js';
 import { emit, query } from '../lib/events.js';
 import { emitSecretAudit } from '../lib/secrets/audit.js';
+import { SYNC_PASSPHRASE_ENV, resolveSyncPassphraseFromEnv } from '../lib/secrets/sync-passphrase.js';
 import { getBundleUsage, getAllBundleUsage, getUsageHistory, SECRET_USAGE_EVENTS, } from '../lib/secrets/usage-db.js';
 import { frequentlyPromptedBundles } from '../lib/secrets/unlock-hints.js';
 import { registerCommandGroups, setHelpSections } from '../lib/help.js';
@@ -266,11 +267,31 @@ function maybePrintSyncedHint(name, stillPresent) {
  * defaults). Shared with the command action so the wiring is unit-testable
  * without a live SSH session.
  */
+export function resolveUnlockTtlMs(ttl, until, now = Date.now()) {
+    if (ttl && until)
+        throw new Error('--ttl and --until are mutually exclusive.');
+    if (until) {
+        const expiresAt = Date.parse(until);
+        if (!Number.isFinite(expiresAt))
+            throw new Error("Invalid --until '" + until + "'. Use an ISO date or timestamp.");
+        if (expiresAt <= now)
+            throw new Error("Invalid --until '" + until + "': date must be in the future.");
+        return expiresAt - now;
+    }
+    if (ttl) {
+        const secs = parseDuration(ttl);
+        if (!secs)
+            throw new Error("Invalid --ttl '" + ttl + "'. Use e.g. 30m, 2h, 8h, 3d.");
+        return secs * 1000;
+    }
+    return secretsHoldMs();
+}
 export function buildRemoteUnlockArgs(names, opts) {
     return [
         'unlock',
         ...(opts.all ? ['--all'] : names),
         ...(opts.ttl ? ['--ttl', opts.ttl] : []),
+        ...(opts.until ? ['--until', opts.until] : []),
         // Forward --durable so a remote unlock honors it too; without this the remote
         // silently falls back to its own secrets.agent.durable default (off).
         ...(opts.durable ? ['--durable'] : []),
@@ -1957,7 +1978,7 @@ Examples:
         .option('--synced', 'When creating the bundle, store it in the age-encrypted synced secrets file')
         .option('--force', 'Overwrite an existing key in the bundle')
         .option('--purge', 'With --from icloud: delete the iCloud copies after a successful import (iCloud propagates the deletion to your other devices)')
-        .option('--from-file <path>', 'Import from an AES-256-GCM encrypted offline bundle file (needs AGENTS_SECRETS_PASSPHRASE; symmetric counterpart of export --to-file)')
+        .option('--from-file <path>', `Import from an AES-256-GCM encrypted offline bundle file (needs ${SYNC_PASSPHRASE_ENV}; symmetric counterpart of export --to-file)`)
         .option('--from-ssh', 'Pull the bundle from a fleet peer over SSH and import it locally (requires --host)')
         .option('--host <peer>', 'SSH peer to pull from when using --from-ssh (host alias or user@host)')
         .action(async (bundleName, opts) => {
@@ -1973,9 +1994,10 @@ Examples:
                 throw new Error('--from-file, --from-ssh, and --from/--from-1password are mutually exclusive; pick one import source.');
             }
             if (opts.fromFile) {
-                const passphrase = process.env.AGENTS_SECRETS_PASSPHRASE ?? '';
+                // Transport, not the local store's master key — see lib/secrets/sync-passphrase.ts.
+                const passphrase = resolveSyncPassphraseFromEnv().value ?? '';
                 if (!passphrase) {
-                    throw new Error('--from-file needs AGENTS_SECRETS_PASSPHRASE set to decrypt the bundle file.');
+                    throw new Error(`--from-file needs ${SYNC_PASSPHRASE_ENV} set to decrypt the bundle file.`);
                 }
                 const env = importBundleFromFile(opts.fromFile, passphrase);
                 const resolvedBundleName = bundleName ?? (await pickBundleName('import into'));
@@ -2063,7 +2085,7 @@ Examples:
         .option('--remote-backend <backend>', 'Backend for the bundle on the remote (with --host): keychain (default) or file. file is headless-readable via the remote\'s machine-local key; it forwards AGENTS_SECRETS_PASSPHRASE over stdin only if set (opt-in).', 'keychain')
         .option('--force', 'Overwrite existing keys/items on the target (used with --to-1password and --host)')
         .option('--format <shell|json>', 'Output for --plaintext export: shell (default) or json (lossless, machine-readable; used by remote resolve)', 'shell')
-        .option('--to-file <path>', 'Write the bundle as an AES-256-GCM encrypted offline file (needs AGENTS_SECRETS_PASSPHRASE; symmetric counterpart of import --from-file)')
+        .option('--to-file <path>', `Write the bundle as an AES-256-GCM encrypted offline file (needs ${SYNC_PASSPHRASE_ENV}; symmetric counterpart of import --from-file)`)
         .action(async (bundleName, opts) => {
         try {
             // `--device` is an alias for `--host` (fleet vocabulary parity with
@@ -2074,9 +2096,10 @@ Examples:
             const { readAndResolveBundleEnv, bundleToEnvPrefix, isReservedEnvName } = await import('../lib/secrets/bundles.js');
             const resolvedBundleName = bundleName ?? (await pickBundleName('export'));
             if (opts.toFile) {
-                const passphrase = process.env.AGENTS_SECRETS_PASSPHRASE ?? '';
+                // Transport, not the local store's master key — see lib/secrets/sync-passphrase.ts.
+                const passphrase = resolveSyncPassphraseFromEnv().value ?? '';
                 if (!passphrase) {
-                    throw new Error('--to-file needs AGENTS_SECRETS_PASSPHRASE set to encrypt the bundle. ' +
+                    throw new Error(`--to-file needs ${SYNC_PASSPHRASE_ENV} set to encrypt the bundle. ` +
                         'Set it for this command, then supply the same value when importing.');
                 }
                 const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: 'export --to-file', keyMode: 'storage', agentOnly: true });
@@ -2483,11 +2506,16 @@ Examples:
         .command('unlock [names...]')
         .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('--until <date>', 'Hold until this absolute date or timestamp (for example 2026-08-06T12:00:00Z). Mutually exclusive with --ttl.')
         .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>', 'Narrow the unlock to ONE harness type (for example claude, codex, or kimi). Default: the grant is global — every harness and a plain shell can read it, so one Touch ID covers them all.')
         .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) => {
+        if (opts.ttl && opts.until) {
+            console.error(chalk.red('--ttl and --until are mutually exclusive.'));
+            process.exit(1);
+        }
         // Single-valued (not variadic): a variadic --host greedily consumes the
         // positional bundle name (`unlock --host mac wztest` -> host=[mac,wztest],
         // names=[]). Unlock targets one remote at a time anyway.
@@ -2524,6 +2552,15 @@ Examples:
                 process.exit(1);
             return;
         }
+        if (opts.until) {
+            try {
+                resolveUnlockTtlMs(undefined, opts.until);
+            }
+            catch (err) {
+                console.error(chalk.red(err.message));
+                process.exit(1);
+            }
+        }
         if (process.platform !== 'darwin') {
             // No broker + no biometry prompt off darwin: secrets already resolve
             // durably from the OS store (libsecret / Credential Manager) on every
@@ -2537,15 +2574,15 @@ Examples:
             console.error(chalk.red('Specify one or more bundle names, or --all.'));
             process.exit(1);
         }
-        let ttlMs = secretsHoldMs(); // default hold, capped by secrets.agent.holdMs
-        if (opts.ttl) {
-            const secs = parseDuration(opts.ttl);
-            if (!secs) {
-                console.error(chalk.red(`Invalid --ttl '${opts.ttl}'. Use e.g. 30m, 2h, 8h, 3d.`));
-                process.exit(1);
-            }
-            ttlMs = secs * 1000;
+        let ttlMs;
+        try {
+            ttlMs = resolveUnlockTtlMs(opts.ttl, opts.until);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
         }
+        const expiresAt = Date.now() + ttlMs;
         if (!(await ensureAgentRunning())) {
             console.error(chalk.red('Could not start the secrets broker.'));
             process.exit(1);
@@ -2571,7 +2608,7 @@ Examples:
                     noAgent: true,
                     caller: 'unlock secrets',
                     agent: harness,
-                    duration: humanRemaining(Date.now() + ttlMs),
+                    duration: humanRemaining(expiresAt),
                     keyMode: 'storage',
                 });
                 // Migrations are authorized only by this explicit unlock. The bundle
@@ -2587,7 +2624,7 @@ Examples:
                     saveSession(name, {
                         bundle,
                         env,
-                        expiresAt: Date.now() + ttlMs,
+                        expiresAt,
                         sleepPersist: durable,
                         harness,
                     });
@@ -2606,7 +2643,7 @@ Examples:
                         agent: harness,
                         ttlMs,
                     });
-                    console.log(`${chalk.green('unlocked')} ${chalk.cyan(name)} ${chalk.gray(`(${Object.keys(env).length} keys, ${humanRemaining(Date.now() + ttlMs)})`)}`);
+                    console.log(`${chalk.green('unlocked')} ${chalk.cyan(name)} ${chalk.gray(`(${Object.keys(env).length} keys, ${humanRemaining(expiresAt)})`)}`);
                 }
                 else {
                     console.error(chalk.red(`Failed to load '${name}' into the agent.`));