@phnx-labs/agents-cli 1.20.40 → 1.20.42

package/dist/lib/exec.js

@@ -19,6 +19,8 @@ import { getShimsDir } from './state.js';
 import { writePidSessionEntry, extractSessionIdArg } from './session/pid-registry.js';
 import { mailboxDir, isValidMailboxId } from './mailbox.js';
 import { composeWin32CommandLine } from './platform/index.js';
+import { isTmuxInstalled } from './tmux/binary.js';
+import { shellQuote } from './ssh-exec.js';
 /**
  * Map a raw mode string (CLI flag, YAML field, env var) to the canonical Mode.
  *
@@ -753,6 +755,131 @@ export async function execShimPassthrough(agent, rawArgs, cwd, pinnedVersion) {
         });
     });
 }
+/**
+ * Decide whether to run an interactive agent INSIDE a detached tmux session on
+ * the shared socket (then attach the current TTY) instead of a bare spawn.
+ *
+ * tmux-wrapping gives every interactive agent an exact, unique `%pane` handle so
+ * `agents sessions --active` can tell co-located agents apart, and lets `agents
+ * focus` re-attach a live session without forking it. Pure so the gate is unit-
+ * tested independently of the (side-effecting) spawn.
+ *
+ * All five guards must pass:
+ *   - interactive     — a headless `-p` run has no TTY to attach; keep bare spawn.
+ *   - not Windows     — no tmux path on win32.
+ *   - not already in tmux — nesting tmux-in-tmux is pointless and confusing.
+ *   - not --raw       — explicit opt-out.
+ *   - not AGENTS_NO_TMUX=1 — env opt-out (CI, scripts, the shim passthrough path).
+ *   - tmux installed  — otherwise there is nothing to wrap with.
+ */
+export function shouldWrapInTmux(ctx) {
+    if (!ctx.interactive)
+        return false;
+    if (ctx.platform === 'win32')
+        return false;
+    if (ctx.inTmux)
+        return false;
+    if (ctx.raw)
+        return false;
+    if (ctx.noTmuxEnv)
+        return false;
+    if (!ctx.tmuxAvailable)
+        return false;
+    return true;
+}
+/**
+ * Build the shell command that runs an agent inside a tmux pane with the exact
+ * env the bare spawn would use. tmux runs it via `sh -c <cmd>`; we `exec env
+ * K=V … <agent> <args…>` so:
+ *   - `env` materializes the full agent env INTO the pane, independent of the
+ *     (possibly stale, shared) tmux server environment — additive, so tmux's own
+ *     $TMUX / $TMUX_PANE still reach the agent for provenance detection;
+ *   - `exec` replaces the shell so the agent is the pane's leaf process (clean
+ *     `#{pane_pid}`, clean signal delivery on detach/kill).
+ * Keys are filtered to valid identifiers so exported shell functions
+ * (`BASH_FUNC_*%%`) can't make `env` choke.
+ */
+export function buildTmuxAgentCommand(executable, args, env) {
+    const envPrefix = Object.entries(env)
+        .filter(([k, v]) => v !== undefined && EXEC_ENV_KEY_PATTERN.test(k))
+        .map(([k, v]) => `${k}=${shellQuote(String(v))}`)
+        .join(' ');
+    const agentCmd = [executable, ...args].map(shellQuote).join(' ');
+    return `exec env ${envPrefix} ${agentCmd}`;
+}
+/**
+ * Run an interactive agent inside a detached tmux session on the shared socket,
+ * attach the current TTY, and propagate the wrapped agent's exit code.
+ *
+ * Lifecycle:
+ *   1. createSession() launches `sh -c 'exec env … agent'` detached, remain-on-exit
+ *      on (global), and returns the pane id.
+ *   2. A per-session `pane-died` hook detaches the attach client the instant the
+ *      AGENT pane exits, so attach returns instead of parking on a dead pane. The
+ *      hook is guarded on `#{hook_pane}` so it fires ONLY for the agent pane —
+ *      user-created splits (Ctrl-b " / %) that the user exits are closed in place
+ *      (`kill-pane`) instead of tearing down the whole client, so exiting one
+ *      split leaves the agent running full-window rather than kicking you out.
+ *   3. We record the agent pane's pid → session mapping (WITH the tmux pane) so the
+ *      headless active-scan attributes it, then attach the TTY (blocking).
+ *   4. On return: if the pane is dead the agent exited — read its status, tear the
+ *      session down, return that code. If the pane is still alive the user detached
+ *      (Ctrl-b d) — return 0 and LEAVE the session for `agents focus` to re-attach.
+ */
+async function runInTmux(options, executable, args) {
+    const { createSession, killSession, paneExitStatus, setSessionHook, slugifyName } = await import('./tmux/session.js');
+    const { getDefaultSocketPath } = await import('./tmux/paths.js');
+    const { attachTmux, runTmux } = await import('./tmux/binary.js');
+    const socket = getDefaultSocketPath();
+    const cwd = options.cwd || process.cwd();
+    const idSeed = (options.sessionId ?? randomUUID()).slice(0, 8);
+    const name = slugifyName(`ag-${options.agent}-${idSeed}`);
+    const cmd = buildTmuxAgentCommand(executable, args, buildExecEnv(options));
+    const labels = { agent: options.agent };
+    if (options.sessionId)
+        labels.sessionId = options.sessionId;
+    const meta = await createSession({ name, cmd, cwd, socket, source: 'cli', labels });
+    const pane = meta.pane;
+    if (pane) {
+        // When the AGENT pane dies, detach the client (don't kill) so the session
+        // survives just long enough to read the dead pane's exit status below. The
+        // `#{hook_pane}` guard scopes this to the agent pane only: if the user splits
+        // the window and exits one of THEIR panes, the else-branch `kill-pane` closes
+        // that split in place instead of detaching everyone (the pane-died hook runs
+        // in the dead pane's context, so bare `kill-pane` targets it). Without the
+        // guard, exiting any split kicked the user clean out of tmux.
+        await setSessionHook(name, 'pane-died', `if -F '#{==:#{hook_pane},${pane}}' 'detach-client -s =${name}' 'kill-pane'`, socket);
+        // Record the agent's OS pid (the pane leaf, thanks to `exec`) WITH its tmux
+        // pane so the active-scan attributes it exactly and shows the %pane.
+        let panePid = 0;
+        try {
+            const r = await runTmux({ socket, args: ['display-message', '-pt', pane, '-p', '#{pane_pid}'], throwOnError: false });
+            panePid = parseInt(r.stdout.trim(), 10) || 0;
+        }
+        catch { /* best-effort */ }
+        writePidSessionEntry({
+            pid: panePid,
+            agent: options.agent,
+            sessionId: options.sessionId,
+            cwd,
+            tmuxPane: pane,
+            startedAtMs: Date.now(),
+        });
+    }
+    // The agent could exit before we attach (fast failure). Don't attach to an
+    // already-dead pane — read its status directly and tear down.
+    const before = pane ? await paneExitStatus(pane, socket) : { dead: false };
+    if (!before.dead) {
+        await attachTmux({ socket, args: ['attach-session', '-t', name] });
+    }
+    const after = pane ? await paneExitStatus(pane, socket) : { dead: false };
+    if (after.dead) {
+        await killSession(name, socket).catch(() => { });
+        return { exitCode: after.status ?? 0, stderr: '' };
+    }
+    // Pane still alive → the user detached; keep the session for `agents focus`.
+    return { exitCode: 0, stderr: '' };
+}
 /**
  * Spawn an agent process and return its exit code plus a tee'd copy of stderr.
  *
@@ -800,6 +927,29 @@ async function spawnAgent(options) {
         command: executable,
         args: redactArgs(args.slice(0, 10)),
     });
+    // Interactive spawn-wrap: on macOS/Linux, run the agent INSIDE a shared-socket
+    // tmux session (then attach this TTY) so it gets a unique, addressable %pane.
+    // Headless runs, Windows, already-in-tmux, --raw, and AGENTS_NO_TMUX=1 keep the
+    // bare spawn below. See shouldWrapInTmux / runInTmux.
+    if (shouldWrapInTmux({
+        interactive,
+        platform: process.platform,
+        inTmux: !!process.env.TMUX,
+        raw: options.raw === true,
+        noTmuxEnv: process.env.AGENTS_NO_TMUX === '1',
+        tmuxAvailable: isTmuxInstalled(),
+    })) {
+        timer.mark('startup');
+        try {
+            const result = await runInTmux(options, executable, args);
+            timer.end({ exitCode: result.exitCode, status: result.exitCode === 0 ? 'success' : 'failed' });
+            return result;
+        }
+        catch (err) {
+            timer.end({ error: err.message, exitCode: -1, status: 'error' });
+            throw err;
+        }
+    }
     return new Promise((resolve, reject) => {
         // Interactive mode inherits all stdio so the CLI owns the TTY (TUI
         // rendering, raw-mode keystrokes, colored output). Headless mode pipes

package/dist/lib/hooks/cache.d.ts

@@ -5,7 +5,7 @@ import type { HookCache, HookCacheConfig } from '../types.js';
  * Returns null if the value is missing or unparseable.
  */
 export declare function parseCacheConfig(raw: HookCache | undefined): HookCacheConfig | null;
-/** Parse "30s" | "5m" | "1h" | plain seconds. Returns seconds, or null on failure. */
+/** Parse "30s" | "5m" | "1h" | "7d" | plain seconds. Returns seconds, or null on failure. */
 export declare function parseDuration(d: number | string | undefined): number | null;
 /**
  * Reject hook names that could escape the shims directory when interpolated

package/dist/lib/hooks/cache.js

@@ -51,19 +51,21 @@ function parseShorthand(s) {
         return null;
     return { ttl: ttlSec, key: 'global', prefetch };
 }
-/** Parse "30s" | "5m" | "1h" | plain seconds. Returns seconds, or null on failure. */
+/** Parse "30s" | "5m" | "1h" | "7d" | plain seconds. Returns seconds, or null on failure. */
 export function parseDuration(d) {
     if (d == null)
         return null;
     if (typeof d === 'number')
         return Number.isFinite(d) && d > 0 ? Math.floor(d) : null;
-    const m = d.trim().match(/^(\d+)\s*(s|sec|secs|m|min|mins|h|hr|hrs)?$/i);
+    const m = d.trim().match(/^(\d+)\s*(s|sec|secs|m|min|mins|h|hr|hrs|d|day|days)?$/i);
     if (!m)
         return null;
     const value = parseInt(m[1], 10);
     if (!Number.isFinite(value) || value <= 0)
         return null;
     const unit = (m[2] || 's').toLowerCase();
+    if (unit.startsWith('d'))
+        return value * 86400;
     if (unit.startsWith('h'))
         return value * 3600;
     if (unit.startsWith('m'))

package/dist/lib/hosts/option.js

@@ -13,6 +13,7 @@
 export function addHostOption(cmd) {
     return cmd
         .option('-H, --host <name>', 'Run this command on another machine over SSH instead of locally — a device, a registered host, or user@host. See `agents devices` / `agents hosts`.')
+        .option('--device <name>', 'Alias of --host: run this command on a registered device (from `agents devices`).')
         .option('--remote-cwd <dir>', 'Working directory on the host for --host runs.')
         .option('--no-tty', 'Force non-interactive output for --host runs even from a terminal.')
         .option('--any', 'With --host <cap> (a capability tag), pick any matching host instead of erroring when several match.');

package/dist/lib/hosts/passthrough.d.ts

@@ -20,9 +20,9 @@
 export declare function flagValue(args: string[], long: string, short?: string): string | undefined;
 /**
  * Route `agents <command> … --host <name>` to a remote if the command is
- * host-routable and a `--host` was given. Returns `false` (run locally) when
- * there is no `--host`, the command isn't in the table, or the target is this
- * very machine.
+ * host-routable and a `--host` (or its `--device` alias) was given. Returns
+ * `false` (run locally) when neither flag is present, the command isn't in the
+ * table, or the target is this very machine.
  *
  * @param command the resolved subcommand name (`process.argv`'s first non-flag).
  * @param allArgs `process.argv.slice(2)` — the command name followed by its args.

package/dist/lib/hosts/passthrough.js

@@ -80,9 +80,9 @@ async function resolveTargetHost(name, any) {
 }
 /**
  * Route `agents <command> … --host <name>` to a remote if the command is
- * host-routable and a `--host` was given. Returns `false` (run locally) when
- * there is no `--host`, the command isn't in the table, or the target is this
- * very machine.
+ * host-routable and a `--host` (or its `--device` alias) was given. Returns
+ * `false` (run locally) when neither flag is present, the command isn't in the
+ * table, or the target is this very machine.
  *
  * @param command the resolved subcommand name (`process.argv`'s first non-flag).
  * @param allArgs `process.argv.slice(2)` — the command name followed by its args.
@@ -91,7 +91,17 @@ export async function maybeRunOnHost(command, allArgs) {
     const spec = REMOTE_PASSTHROUGH[command];
     if (!spec)
         return false;
-    const hostName = flagValue(allArgs, 'host', 'H');
+    // `--device` is a first-class alias of `--host` (mirrors `agents run`); the
+    // device registry is the source of truth for machine identity. Reject a
+    // conflicting pair rather than silently preferring one — same rule as run.
+    const hostFlag = flagValue(allArgs, 'host', 'H');
+    const deviceFlag = flagValue(allArgs, 'device');
+    if (hostFlag && deviceFlag && hostFlag !== deviceFlag) {
+        console.error(chalk.red('Conflicting --host/--device values — pass just one.'));
+        process.exitCode = 1;
+        return true;
+    }
+    const hostName = hostFlag ?? deviceFlag;
     if (!hostName)
         return false;
     // Running against your own machine is just a local run — skip the SSH round-trip.

package/dist/lib/hosts/remote-cmd.d.ts

@@ -25,7 +25,13 @@ export interface StripSpec {
  * @param args the command's args (already past the command name).
  */
 export declare function stripRoutingFlags(args: string[], specs: StripSpec[]): string[];
-/** The routing flags every `--host`-capable command shares. */
+/**
+ * The routing flags every `--host`-capable command shares. `--device` is a
+ * first-class alias of `--host` (the device registry is the source of truth for
+ * machine identity — see `agents devices`), mirroring `agents run --device`.
+ * Both are stripped before forwarding so the alias never leaks to the remote
+ * binary (which would re-trigger routing).
+ */
 export declare const HOST_ROUTING_SPECS: StripSpec[];
 /**
  * Build the single command string for `ssh <target> <cmd>`. The forwarded args

package/dist/lib/hosts/remote-cmd.js

@@ -38,9 +38,16 @@ export function stripRoutingFlags(args, specs) {
     }
     return out;
 }
-/** The routing flags every `--host`-capable command shares. */
+/**
+ * The routing flags every `--host`-capable command shares. `--device` is a
+ * first-class alias of `--host` (the device registry is the source of truth for
+ * machine identity — see `agents devices`), mirroring `agents run --device`.
+ * Both are stripped before forwarding so the alias never leaks to the remote
+ * binary (which would re-trigger routing).
+ */
 export const HOST_ROUTING_SPECS = [
     { long: 'host', short: 'H', takesValue: true },
+    { long: 'device', takesValue: true },
     { long: 'remote-cwd', takesValue: true },
 ];
 /**

package/dist/lib/menubar/install-menubar.js

@@ -77,7 +77,7 @@ export function menubarServiceInstalled() {
  * Locate the source `.app` shipped alongside the compiled JS.
  *   1. dist/lib/menubar/MenubarHelper.app — npm install layout (sibling of this file)
  *   2. <repo>/bin/MenubarHelper.app       — raw working tree (tsx/dev)
- *   3. <repo>/packages/menubar-helper/dist/MenubarHelper.app — fresh local build
+ *   3. apps/cli/menubar/dist/MenubarHelper.app — fresh local build
  */
 function sourceAppPath() {
     const candidates = [];
@@ -85,7 +85,7 @@ function sourceAppPath() {
         const here = path.dirname(fileURLToPath(import.meta.url));
         candidates.push(path.join(here, APP_BUNDLE_NAME));
         candidates.push(path.resolve(here, '..', '..', '..', 'bin', APP_BUNDLE_NAME));
-        candidates.push(path.resolve(here, '..', '..', '..', 'packages', 'menubar-helper', 'dist', APP_BUNDLE_NAME));
+        candidates.push(path.resolve(here, '..', '..', '..', 'menubar', 'dist', APP_BUNDLE_NAME));
     }
     catch {
         /* import.meta.url unavailable */

package/dist/lib/secrets/agent.d.ts

@@ -16,8 +16,9 @@
  * trust boundary the keychain already concedes (docs/secrets.md: the ACL is
  * user-presence, not code-identity — any same-user process can pop the prompt
  * and read), minus the visible prompt. We bound it with: explicit per-bundle
- * opt-in (nothing is held unless you `unlock` it), an absolute TTL, auto-lock
- * on screen-lock / sleep, and `agents secrets lock`. Nothing ever touches disk.
+ * opt-in (nothing is held unless you `unlock` it), an absolute TTL (~7d), an
+ * auto-wipe on sleep / logout, and `agents secrets lock`. A bare screen-lock is
+ * NOT a wipe (the login password already gates it). Nothing ever touches disk.
  *
  * macOS only: Linux libsecret has no biometry prompt, so there's nothing to
  * deduplicate — every entry point here no-ops off darwin.
@@ -30,7 +31,7 @@ export declare const DEFAULT_TTL_MS: number;
  * The broker holds the resolved bundle-metadata array (names/policy/timestamps,
  * NO resolved secret values beyond the literals already in metadata) keyed by a
  * hash of the current keychain bundle name-set, so the second and later
- * `secrets list` within the daily window read metadata without a Touch ID
+ * `secrets list` within the hold window read metadata without a Touch ID
  * prompt. Keyed by the name-set hash so adding/removing/renaming a bundle
  * changes the key and misses the cache automatically — no active invalidation.
  * The '!' sentinel can never collide with a real bundle name
@@ -43,7 +44,7 @@ export declare const META_CACHE_PREFIX = "!meta:";
  * code (exit so launchd relaunches it). Only when the store is EMPTY: exiting
  * with bundles still unlocked wipes them from memory, so the next reader falls
  * back to a direct keychain read and re-prompts for Touch ID. Deferring the
- * restart until the cache is idle (TTL-expired / screen-locked) means an
+ * restart until the cache is idle (TTL-expired / slept) means an
  * in-place `npm i -g` never wipes a hot cache — the new code is adopted at the
  * next quiet moment instead. See #435: rapid repeated upgrades wiped a hot
  * cache on every bump and produced a recurring Touch ID storm.
@@ -141,10 +142,20 @@ export type Response = {
  */
 export declare function realBundleCount(store: Map<string, StoredBundle>): number;
 export declare function handleAgentRequest(store: Map<string, StoredBundle>, req: Request, now?: number): Response;
+/**
+ * Decide whether a `watch-lock` helper line should wipe the in-memory store.
+ * The helper emits `LOCK` on screen-lock / screensaver and `SLEEP` on system
+ * sleep. We wipe on SLEEP only: a bare screen-lock is already gated by the login
+ * password, and with the ~7d hold, re-authing after every lock would defeat the
+ * point. Logout needs no line — it tears down the launchd session and kills the
+ * broker outright. Pure + exported so the LOCK-survives / SLEEP-wipes contract
+ * has direct regression coverage (the inline stdout handler isn't unit-testable).
+ */
+export declare function shouldWipeOnWatchEvent(chunk: string): boolean;
 /**
  * Run the broker in the foreground. Spawned detached by ensureAgentRunning via
  * `agents secrets _agent-run`. Holds the store in memory, serves the socket,
- * sweeps expired entries, wipes on screen-lock/sleep, and self-exits when idle.
+ * sweeps expired entries, wipes on sleep, and self-exits when idle.
  */
 export declare function runSecretsAgent(opts?: {
     service?: boolean;
@@ -171,7 +182,7 @@ export declare function agentGetSync(name: string): {
 export declare function agentGetMetaSync(nameSetHash: string): SecretsBundle[] | null;
 /**
  * Fire-and-forget: populate the broker with a freshly-read metadata snapshot so
- * the next `secrets list` within the daily window renders without a prompt.
+ * the next `secrets list` within the hold window renders without a prompt.
  * Stored as an ordinary entry (placeholder bundle, snapshot in env) under the
  * reserved META_CACHE_PREFIX key; the snapshot travels over stdin to the
  * detached worker (never argv/disk), same as value caching. macOS only.
@@ -179,7 +190,7 @@ export declare function agentGetMetaSync(nameSetHash: string): SecretsBundle[] |
 export declare function agentAutoLoadMetaSync(nameSetHash: string, bundles: SecretsBundle[], ttlMs: number): void;
 /** True unless `secrets.agent.auto` is explicitly disabled in agents.yaml. The
  * broker is the mechanism that delivers the `daily` default policy (one Touch ID
- * per ~24h), so auto-caching is ON by default; opt out with
+ * per ~7d), so auto-caching is ON by default; opt out with
  * `secrets.agent.auto: false`. Best-effort; an unreadable meta reads as on. */
 export declare function secretsAgentAutoEnabled(): boolean;
 /**

package/dist/lib/secrets/agent.js

@@ -16,8 +16,9 @@
  * trust boundary the keychain already concedes (docs/secrets.md: the ACL is
  * user-presence, not code-identity — any same-user process can pop the prompt
  * and read), minus the visible prompt. We bound it with: explicit per-bundle
- * opt-in (nothing is held unless you `unlock` it), an absolute TTL, auto-lock
- * on screen-lock / sleep, and `agents secrets lock`. Nothing ever touches disk.
+ * opt-in (nothing is held unless you `unlock` it), an absolute TTL (~7d), an
+ * auto-wipe on sleep / logout, and `agents secrets lock`. A bare screen-lock is
+ * NOT a wipe (the login password already gates it). Nothing ever touches disk.
  *
  * macOS only: Linux libsecret has no biometry prompt, so there's nothing to
  * deduplicate — every entry point here no-ops off darwin.
@@ -35,13 +36,13 @@ import { getCliVersion, getCliVersionFresh } from '../version.js';
  * server kills and respawns it rather than talking a stale dialect. */
 const PROTOCOL_VERSION = 1;
 /** Default lifetime of an unlocked bundle when `--ttl` is not given. */
-export const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000; // 24h
+export const DEFAULT_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7d
 /**
  * Reserved store-key prefix for the `secrets list` metadata snapshot cache.
  * The broker holds the resolved bundle-metadata array (names/policy/timestamps,
  * NO resolved secret values beyond the literals already in metadata) keyed by a
  * hash of the current keychain bundle name-set, so the second and later
- * `secrets list` within the daily window read metadata without a Touch ID
+ * `secrets list` within the hold window read metadata without a Touch ID
  * prompt. Keyed by the name-set hash so adding/removing/renaming a bundle
  * changes the key and misses the cache automatically — no active invalidation.
  * The '!' sentinel can never collide with a real bundle name
@@ -59,7 +60,7 @@ const SWEEP_INTERVAL_MS = 30 * 1000;
  * code (exit so launchd relaunches it). Only when the store is EMPTY: exiting
  * with bundles still unlocked wipes them from memory, so the next reader falls
  * back to a direct keychain read and re-prompts for Touch ID. Deferring the
- * restart until the cache is idle (TTL-expired / screen-locked) means an
+ * restart until the cache is idle (TTL-expired / slept) means an
  * in-place `npm i -g` never wipes a hot cache — the new code is adopted at the
  * next quiet moment instead. See #435: rapid repeated upgrades wiped a hot
  * cache on every bump and produced a recurring Touch ID storm.
@@ -301,10 +302,22 @@ export function handleAgentRequest(store, req, now = Date.now()) {
         }
     }
 }
+/**
+ * Decide whether a `watch-lock` helper line should wipe the in-memory store.
+ * The helper emits `LOCK` on screen-lock / screensaver and `SLEEP` on system
+ * sleep. We wipe on SLEEP only: a bare screen-lock is already gated by the login
+ * password, and with the ~7d hold, re-authing after every lock would defeat the
+ * point. Logout needs no line — it tears down the launchd session and kills the
+ * broker outright. Pure + exported so the LOCK-survives / SLEEP-wipes contract
+ * has direct regression coverage (the inline stdout handler isn't unit-testable).
+ */
+export function shouldWipeOnWatchEvent(chunk) {
+    return /\bSLEEP\b/.test(chunk);
+}
 /**
  * Run the broker in the foreground. Spawned detached by ensureAgentRunning via
  * `agents secrets _agent-run`. Holds the store in memory, serves the socket,
- * sweeps expired entries, wipes on screen-lock/sleep, and self-exits when idle.
+ * sweeps expired entries, wipes on sleep, and self-exits when idle.
  */
 export async function runSecretsAgent(opts = {}) {
     if (!onDarwin())
@@ -351,9 +364,9 @@ export async function runSecretsAgent(opts = {}) {
     // this value for the process lifetime; getCliVersionFresh re-reads on disk.
     const runningVersion = getCliVersion();
     // "Warmth" for self-heal / idle-exit counts only real unlocked bundles, NOT
-    // the internal `secrets list` metadata cache (#524). Otherwise a 24h-TTL list
+    // the internal `secrets list` metadata cache (#524). Otherwise a 7d-TTL list
     // cache would keep the store non-empty and (a) block the persistent broker
-    // from self-healing onto a freshly-installed version for up to a day (#435's
+    // from self-healing onto a freshly-installed version for up to a week (#435's
     // gate is size===0), and (b) stop a one-off broker from ever idle-exiting. The
     // metadata cache is a disposable list snapshot — wiping it on upgrade/idle
     // costs at most one extra prompt on the next `secrets list`.
@@ -450,15 +463,19 @@ export async function runSecretsAgent(opts = {}) {
         });
     });
     sweepTimer = setInterval(sweep, SWEEP_INTERVAL_MS);
-    // Auto-lock on screen-lock / sleep. The signed helper emits LOCK / SLEEP
-    // lines; on any of them we wipe everything. If the installed helper predates
-    // watch-lock (exits non-zero immediately), we fall back to TTL-only and log
-    // nothing — the unlock already warned when lock_on_sleep couldn't be armed.
+    // Auto-lock on sleep. The signed helper emits LOCK / SLEEP lines; we wipe
+    // everything on SLEEP (and, implicitly, logout — that tears down the launchd
+    // session and kills this in-memory broker). A bare screen-lock is deliberately
+    // NOT a wipe: with the ~7d hold, re-prompting after every lock would defeat the
+    // point, and a locked screen is already gated by the login password. If the
+    // installed helper predates watch-lock (exits non-zero immediately), we fall
+    // back to TTL-only and log nothing — the unlock already warned when
+    // lock_on_sleep couldn't be armed.
     try {
         watcher = spawn(getKeychainHelperPath(), ['watch-lock'], { stdio: ['ignore', 'pipe', 'ignore'] });
         watcher.stdout?.setEncoding('utf-8');
         watcher.stdout?.on('data', (chunk) => {
-            if (/\b(LOCK|SLEEP)\b/.test(chunk)) {
+            if (shouldWipeOnWatchEvent(chunk)) {
                 store.clear();
                 emptySince = Date.now();
             }
@@ -590,7 +607,7 @@ export function agentGetMetaSync(nameSetHash) {
 }
 /**
  * Fire-and-forget: populate the broker with a freshly-read metadata snapshot so
- * the next `secrets list` within the daily window renders without a prompt.
+ * the next `secrets list` within the hold window renders without a prompt.
  * Stored as an ordinary entry (placeholder bundle, snapshot in env) under the
  * reserved META_CACHE_PREFIX key; the snapshot travels over stdin to the
  * detached worker (never argv/disk), same as value caching. macOS only.
@@ -604,7 +621,7 @@ export function agentAutoLoadMetaSync(nameSetHash, bundles, ttlMs) {
 }
 /** True unless `secrets.agent.auto` is explicitly disabled in agents.yaml. The
  * broker is the mechanism that delivers the `daily` default policy (one Touch ID
- * per ~24h), so auto-caching is ON by default; opt out with
+ * per ~7d), so auto-caching is ON by default; opt out with
  * `secrets.agent.auto: false`. Best-effort; an unreadable meta reads as on. */
 export function secretsAgentAutoEnabled() {
     try {

package/dist/lib/secrets/bundles.d.ts

@@ -40,11 +40,13 @@ export interface VarMeta {
 }
 /**
  * A bundle's prompt policy — how often macOS asks for Touch ID to read it:
- * - `daily` (default): ask once, then hold it silently for up to ~24h. Eligible
- *   for the secrets-agent — the first real keychain read auto-loads it (auto-cache
- *   is on by default) so concurrent runs read it silently, or `unlock` it
- *   explicitly. Held from that unlock (not refreshed on use); re-asks sooner
- *   after screen-lock, sleep, logout, or `agents secrets lock`.
+ * - `daily` (default): ask once, then hold it silently for up to ~7 days.
+ *   (Historical name — the window is now a rolling ~1 week, not one calendar day.)
+ *   Eligible for the secrets-agent — the first real keychain read auto-loads it
+ *   (auto-cache is on by default) so concurrent runs read it silently, or `unlock`
+ *   it explicitly. Held from that unlock (not refreshed on use); re-asks sooner
+ *   after sleep, logout, or `agents secrets lock`. A bare screen-lock does NOT
+ *   drop it (the login password already gates a locked screen).
  * - `always`: asks every time. Never auto-held — only an explicit `agents
  *   secrets unlock` ever holds it; every other read pops Touch ID. Opt a
  *   high-value bundle into this when you want to confirm every single read.
@@ -107,7 +109,7 @@ export declare function bundleExists(name: string): boolean;
 export declare function readBundle(name: string): SecretsBundle;
 /** The default prompt policy applied to bundles without an explicit per-bundle
  * policy. Configurable via `secrets.policy` in agents.yaml; `daily` (one Touch
- * ID per ~24h) unless the user explicitly opts back into prompt-every-time with
+ * ID per ~7d) unless the user explicitly opts back into prompt-every-time with
  * `always`. Best-effort: an unreadable config falls back to the `daily` default. */
 export declare function secretsDefaultPolicy(): SecretsPolicy;
 /** The effective prompt policy of a bundle (absent ⇒ the configured default). */

package/dist/lib/secrets/bundles.js

@@ -263,7 +263,7 @@ function parsePolicy(raw) {
 }
 /** The default prompt policy applied to bundles without an explicit per-bundle
  * policy. Configurable via `secrets.policy` in agents.yaml; `daily` (one Touch
- * ID per ~24h) unless the user explicitly opts back into prompt-every-time with
+ * ID per ~7d) unless the user explicitly opts back into prompt-every-time with
  * `always`. Best-effort: an unreadable config falls back to the `daily` default. */
 export function secretsDefaultPolicy() {
     try {
@@ -336,13 +336,13 @@ export function writeBundle(bundle) {
     // of the tier. On an un-updated pinned helper this write fails loudly (the
     // no-ACL command is missing) rather than silently landing an ACL'd item.
     itemStore(backend).set(bundleMetaItem(bundle.name), json, { noAcl: bundle.policy === 'never' });
-    emit('secrets.set', { bundle: bundle.name });
+    emit('secrets.set', { module: 'secrets', bundle: bundle.name });
 }
 export function deleteBundle(name) {
     validateBundleName(name);
     const deleted = itemStore(bundleBackend(name)).delete(bundleMetaItem(name));
     if (deleted) {
-        emit('secrets.delete', { bundle: name });
+        emit('secrets.delete', { module: 'secrets', bundle: name });
     }
     return deleted;
 }
@@ -414,11 +414,15 @@ export function listBundles() {
             // so the getKeychainTokens batch below pops Touch ID on every `secrets
             // list` — the broker/`daily` mechanism only ever covered value reads, not
             // this listing. Serve a broker-cached metadata snapshot when one is held,
-            // so only the first list per ~24h prompts. The cache key is a hash of the
+            // so only the first list per ~7d prompts. The cache key is a hash of the
             // current keychain name-set (enumerated silently above): add / remove /
             // rename a bundle and the key changes, so the stale snapshot is never
-            // served — no active invalidation needed. Values are never cached here;
-            // this is metadata only.
+            // served. A same-name metadata edit (e.g. `secrets policy <b> always`)
+            // does NOT change the key, so the POLICY column in `secrets list` can lag
+            // by up to the hold window (~7d) until the next name-set change or `lock`.
+            // This is cosmetic only — enforcement always reads the bundle's live
+            // policy (readBundle), never this snapshot, and `secrets view <b>` shows
+            // the fresh value immediately. Values are never cached here; metadata only.
             const useAgent = process.env.AGENTS_SECRETS_NO_AGENT !== '1' &&
                 !isKeychainBackendOverridden() &&
                 secretsAgentAutoEnabled();
@@ -444,7 +448,7 @@ export function listBundles() {
                 }
                 for (const bundle of keychainBundles)
                     out.push(bundle);
-                // Populate the broker for the rest of the daily window (fire-and-forget).
+                // Populate the broker for the rest of the hold window (fire-and-forget).
                 if (useAgent && keychainBundles.length > 0) {
                     agentAutoLoadMetaSync(nameSetHash, keychainBundles, DEFAULT_TTL_MS);
                 }
@@ -688,6 +692,7 @@ export function readAndResolveBundleEnv(name, opts = {}) {
             const filtered = filterAgentHitBySubsetAndExpiry(hit, opts);
             stampLastUsed(filtered.bundle);
             emit('secrets.get', {
+                module: 'secrets',
                 bundle: name,
                 caller: opts.caller,
                 status: 'success',
@@ -777,6 +782,7 @@ export function readAndResolveBundleEnv(name, opts = {}) {
     keychainKeys.sort();
     const emitReadAudit = (status, err) => {
         emit('secrets.get', {
+            module: 'secrets',
             bundle: bundle.name,
             caller: opts.caller,
             status,
@@ -939,7 +945,7 @@ export function renameBundle(oldName, newName, opts = {}) {
         store.delete(oldItem);
     }
     deleteBundle(oldName);
-    emit('secrets.rename', { from: oldName, to: newName });
+    emit('secrets.rename', { module: 'secrets', from: oldName, to: newName });
 }
 /**
  * The store (keychain or encrypted file) that carries a bundle's items. The

package/dist/lib/secrets/remote.js

@@ -17,6 +17,7 @@
  */
 import { sshExec, assertValidSshTarget } from '../ssh-exec.js';
 import { resolveHost } from '../hosts/registry.js';
+import { emit } from '../events.js';
 import { sshTargetFor } from '../hosts/types.js';
 import { buildRemoteAgentsInvocation } from '../hosts/remote-cmd.js';
 import { resolveRemoteOsSync } from '../hosts/remote-os.js';
@@ -136,5 +137,18 @@ export async function remoteResolveEnv(target, bundle) {
     for (const [k, v] of Object.entries(parsed)) {
         env[k] = typeof v === 'string' ? v : String(v);
     }
+    // The remote host audits its own `secrets export` read; this emit records the
+    // event on the INITIATING host too (values were pulled into this process and
+    // injected locally). Covers `secrets exec --host` and `run --secrets b@host`.
+    // Values never enter the payload — only the bundle, target host, and count.
+    emit('secrets.get', {
+        module: 'secrets',
+        bundle,
+        caller: 'remote resolve',
+        source: 'remote',
+        host: target,
+        status: 'success',
+        keyCount: Object.keys(env).length,
+    });
     return env;
 }