@phnx-labs/agents-cli 1.20.39 → 1.20.41

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 1.20.41
+
+- **NEW: `agents sessions focus [id]`** — one command to get back to a session, however it's reachable. It **attaches** a live session in place (tmux `switch-client`/`attach-session`, a remote tmux over `ssh -tt`, or a Ghostty tab — joining the live process without forking); where there's **no live terminal to attach**, it **opens a new tab and resumes** the session — locally, or on the remote peer over SSH (`runOnPeer`, so the peer resolves the version-pinned binary). No id opens the rich live-session picker (this-machine first). Reuses the live-session detection and the terminal launch engine (`openSurfaces`), and folds `go`'s attach paths in. Source: `src/commands/focus.ts`, `src/commands/go.ts`.
+- **`--device` is now a first-class alias of `--host`** on every host-routable command (`sessions`, `run`, …), registered centrally on `addHostOption` so a local fall-through no longer errors. Source: `src/lib/hosts/`.
+- **`agents computer` steers Electron/webview targets over CDP** instead of reporting a fake success when the native-automation path can't reach them (#716).
+- **Secrets: the "remember" policy hold now lasts 7 days and survives screen-lock**, instead of re-prompting after every lock/sleep; stale copies are evicted when a policy is tightened. Source: `src/lib/secrets/`.
+- **Fixes:** shim `machine_id()` normalizes to match `normalizeHost()`, and shim resolution honors the per-device default pin (not just the central `agents.yaml`).
+- **`agents sessions go` is retired as a deprecated alias for `agents sessions focus --attach-only`.** `go` was already a strict subset of `focus` — its only unique behavior was "attach the live terminal or refuse, never fork/resume." That behavior is now a first-class `--attach-only` flag on `focus` (`focus.ts`: `selectFallback()` picks `refuseFallback` under `--attach-only`, else the resume-in-a-new-tab fallback). `go` now prints a one-line deprecation notice and delegates to `focusAction(id, { attachOnly: true })`; the shared reach engine (`jumpTo`/`gatherLiveTargets`/`pickLiveTarget`/`refuseFallback`) still lives in `go.ts` and is imported by `focus.ts`. Source: `src/commands/go.ts`, `src/commands/focus.ts`.
+- **`agents sessions --json --host <h>` now emits a clean JSON array** of recent (non-active) sessions instead of the legacy per-host raw banner stream, so a UI can fetch a remote device's recent sessions when it has no live agents. `serializeSessionsJson()` is shared by the local and remote `--json` paths; `runRemoteSessionsJson()` reuses the existing `gatherRemoteList` SSH fan-out. The non-JSON banner path and `--active` are unchanged (#711).
+
 ## 1.20.36
 
 **[windows] `agents sessions --active` detects sessions on Windows, and shim launches carry cwd + session identity everywhere**

package/dist/commands/computer-actions.d.ts

@@ -80,4 +80,6 @@ export declare function shouldRaise(opts: {
     id?: string;
     raise?: boolean;
 }): boolean;
+export declare function appPathIsElectron(appPath: string | null, exists?: (p: string) => boolean): boolean;
+export declare function electronWebviewTip(appLabel: string): string;
 export declare function registerActionCommands(program: Command): void;

package/dist/commands/computer-actions.js

@@ -6,6 +6,7 @@
 // The daemon already implements every method; this file is the thin, typed
 // CLI skin over it plus a shared target resolver so callers stay in bundle-id
 // space and never hand-manage pids.
+import { execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import { openComputerClient, describeTransport, resolvePolicyPath, } from '../lib/computer-rpc.js';
@@ -288,6 +289,59 @@ async function applyFocusPolicy(client, pid, opts) {
     if (shouldRaise(opts))
         unwrap(await client.call('focus_window', { pid }));
 }
+// Electron/webview steering. macOS accepts an AX action (AXPress / set-AXValue)
+// on an Electron/Chromium window, but it does NOT run the web app's real DOM
+// handlers — React ignores it — so a reported `clicked`/`typed` on a webview can
+// be a silent no-op. Detect Electron targets and steer the caller to CDP
+// (`agents browser --electron`), which drives the webview for real. We warn, not
+// block: the caller may still want the raw action (e.g. to focus + coordinate).
+const electronCache = new Map();
+// Resolve a bundle id to its .app path via Spotlight. Best-effort; null on miss.
+function appPathForBundle(bundleId) {
+    try {
+        const out = execFileSync('mdfind', [`kMDItemCFBundleIdentifier == '${bundleId}'`], {
+            encoding: 'utf-8',
+            timeout: 3000,
+        });
+        return out.split('\n').map((s) => s.trim()).find((s) => s.endsWith('.app')) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+// Pure + unit-tested: does the .app at this path bundle the Electron framework?
+export function appPathIsElectron(appPath, exists = fs.existsSync) {
+    if (!appPath)
+        return false;
+    return exists(path.join(appPath, 'Contents', 'Frameworks', 'Electron Framework.framework'));
+}
+// Is the app for this bundle id an Electron/webview app? macOS-only; memoized so
+// the mdfind lookup runs at most once per bundle id per process.
+function isElectronApp(bundleId) {
+    if (!bundleId || process.platform !== 'darwin')
+        return false;
+    const cached = electronCache.get(bundleId);
+    if (cached !== undefined)
+        return cached;
+    const result = appPathIsElectron(appPathForBundle(bundleId));
+    electronCache.set(bundleId, result);
+    return result;
+}
+// Pure + unit-tested: the CDP-steer note printed for a webview target.
+export function electronWebviewTip(appLabel) {
+    return `note: ${appLabel} is an Electron/web UI — an AX click/type may not reach the webview `
+        + `(a reported success can be a no-op). To drive it reliably, relaunch it with `
+        + '`--remote-debugging-port=9222` and use `agents browser --electron` (CDP).';
+}
+// Print the CDP steer when the target is a known Electron app. Keyed off --bundle
+// (the recommended way to target); a frontmost-resolved target without --bundle is
+// left alone to avoid a second RPC on the hot path. Skipped for remote --host.
+function warnIfElectronWebview(opts) {
+    if (opts.host)
+        return;
+    if (opts.bundle && isElectronApp(opts.bundle))
+        console.error(electronWebviewTip(opts.bundle));
+}
 function emit(result, json, human) {
     if (json) {
         console.log(JSON.stringify(result, null, 2));
@@ -355,6 +409,7 @@ export function registerActionCommands(program) {
         .option('--json', 'Emit JSON'))).action(async (opts) => {
         await withClient(async (client) => {
             const pid = await resolveTargetPid(client, opts, { verb: 'click' });
+            warnIfElectronWebview(opts);
             const spec = buildElementOrCoords(opts);
             if (!spec.ok) {
                 console.error(spec.error);
@@ -377,6 +432,7 @@ export function registerActionCommands(program) {
         .option('--json', 'Emit JSON'))).action(async (opts) => {
         await withClient(async (client) => {
             const pid = await resolveTargetPid(client, opts, { verb: 'right-click' });
+            warnIfElectronWebview(opts);
             const spec = buildElementOrCoords(opts);
             if (!spec.ok) {
                 console.error(spec.error);
@@ -397,6 +453,7 @@ export function registerActionCommands(program) {
         .option('--json', 'Emit JSON'))).action(async (opts) => {
         await withClient(async (client) => {
             const pid = await resolveTargetPid(client, opts, { verb: 'type' });
+            warnIfElectronWebview(opts);
             const spec = buildElementOrCoords(opts);
             if (!spec.ok) {
                 console.error(spec.error);
@@ -424,6 +481,7 @@ export function registerActionCommands(program) {
         .option('--json', 'Emit JSON')).action(async (opts) => {
         await withClient(async (client) => {
             const pid = await resolveTargetPid(client, opts, { verb: 'type-text' });
+            warnIfElectronWebview(opts);
             await applyFocusPolicy(client, pid, opts);
             const params = { pid, text: opts.text };
             if (opts.commit)
@@ -448,6 +506,7 @@ export function registerActionCommands(program) {
         .option('--json', 'Emit JSON')).action(async (opts) => {
         await withClient(async (client) => {
             const pid = await resolveTargetPid(client, opts, { verb: 'key' });
+            warnIfElectronWebview(opts);
             await applyFocusPolicy(client, pid, opts);
             const params = { pid, keys: opts.keys };
             if (opts.requireFrontmost)

package/dist/commands/focus.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `agents sessions focus [id]` — take me to a live session, however it's reachable.
+ *
+ * Same detection as `go`, but where `go` *refuses* an un-attachable session,
+ * `focus` **opens a new tab and resumes it** — locally, or on the remote over SSH
+ * (via the terminal launch engine's `openSurfaces`, `host` = the peer). So:
+ *   - in tmux (local/remote)   -> attach the live pane (join it, no fork)
+ *   - in Ghostty               -> focus its tab
+ *   - headless / plain / etc.  -> new tab + `resume` (a copy if it's mid-run — the
+ *                                  original keeps going; a clean continue if it's idle)
+ *
+ * NOTE: joining a live process without forking is only possible via tmux — that's
+ * why `--tmux`-wrapped launches are worth it for sessions you'll want back live.
+ */
+import type { Command } from 'commander';
+import { type UnreachableFallback } from './go.js';
+import type { ActiveSession } from '../lib/session/active.js';
+import type { SessionMeta } from '../lib/session/types.js';
+export declare function registerFocusCommand(program: Command): void;
+/**
+ * Which fallback fires when a session has no attach rail. `--attach-only` (the old
+ * `go`) refuses; the default opens a new tab and resumes a copy. Pure so it's testable
+ * without touching `jumpTo`'s side effects.
+ */
+export declare function selectFallback(attachOnly: boolean | undefined): UnreachableFallback;
+export declare function focusAction(id: string | undefined, opts: {
+    local?: boolean;
+    attachOnly?: boolean;
+}): Promise<void>;
+/** Minimal SessionMeta for a live session, enough for `buildResumeCommand` + placement. */
+export declare function metaFromActive(s: ActiveSession): SessionMeta;

package/dist/commands/focus.js

@@ -0,0 +1,150 @@
+/**
+ * `agents sessions focus [id]` — take me to a live session, however it's reachable.
+ *
+ * Same detection as `go`, but where `go` *refuses* an un-attachable session,
+ * `focus` **opens a new tab and resumes it** — locally, or on the remote over SSH
+ * (via the terminal launch engine's `openSurfaces`, `host` = the peer). So:
+ *   - in tmux (local/remote)   -> attach the live pane (join it, no fork)
+ *   - in Ghostty               -> focus its tab
+ *   - headless / plain / etc.  -> new tab + `resume` (a copy if it's mid-run — the
+ *                                  original keeps going; a clean continue if it's idle)
+ *
+ * NOTE: joining a live process without forking is only possible via tmux — that's
+ * why `--tmux`-wrapped launches are worth it for sessions you'll want back live.
+ */
+import fs from 'node:fs';
+import chalk from 'chalk';
+import { gatherLiveTargets, pickLiveTarget, jumpTo, refuseFallback } from './go.js';
+import { buildResumeCommand, resumeSessionInPlace } from './sessions.js';
+import { runOnPeer } from '../lib/session/remote-list.js';
+import { discoverSessions } from '../lib/session/discover.js';
+import { openSurfaces, currentContext, availableBackends, detectCurrentBackend, } from '../lib/terminal/index.js';
+import { isInteractiveTerminal } from './utils.js';
+export function registerFocusCommand(program) {
+    program
+        .command('focus')
+        .argument('[id]', 'Short/full session id to focus; omit for an interactive picker')
+        .option('--local', 'Only this machine (skip the cross-host sweep)')
+        .option('--attach-only', 'Attach only — never open a new tab / resume a copy (the old `go` behavior)')
+        .description('Focus a live session — attach its terminal, or open a new tab and resume it')
+        .action(async (id, opts) => {
+        await focusAction(id, opts);
+    });
+}
+/**
+ * Which fallback fires when a session has no attach rail. `--attach-only` (the old
+ * `go`) refuses; the default opens a new tab and resumes a copy. Pure so it's testable
+ * without touching `jumpTo`'s side effects.
+ */
+export function selectFallback(attachOnly) {
+    return attachOnly ? refuseFallback : resumeInNewTab;
+}
+export async function focusAction(id, opts) {
+    const { self, activeById } = await gatherLiveTargets(!!opts.local);
+    const fallback = selectFallback(opts.attachOnly);
+    if (id) {
+        const q = id.toLowerCase();
+        const matches = [...activeById.values()].filter((s) => s.sessionId.toLowerCase().startsWith(q));
+        if (matches.length === 1) {
+            await jumpTo(matches[0], self, fallback);
+            return;
+        }
+        if (matches.length > 1) {
+            console.error(chalk.red(`"${id}" is ambiguous (${matches.length} live matches). Use more of the id.`));
+            process.exitCode = 1;
+            return;
+        }
+        // Not live — it's a past session; resume is the right tool (multi-select + placement).
+        console.log(chalk.yellow(`No live session matching "${id}".`) +
+            chalk.gray(`\nTo resume a past session: agents sessions resume ${id}`));
+        process.exitCode = 1;
+        return;
+    }
+    if (!isInteractiveTerminal()) {
+        console.error(chalk.red('focus needs an interactive terminal, or pass a session id.'));
+        process.exitCode = 1;
+        return;
+    }
+    if (activeById.size === 0) {
+        console.log(chalk.gray('No live sessions to focus. To resume a past one: agents sessions resume'));
+        return;
+    }
+    const target = await pickLiveTarget(activeById, self, 'Focus a live session:', 'focus');
+    if (!target)
+        return;
+    await jumpTo(target, self, fallback);
+}
+function shortId(s) {
+    return (s.sessionId ?? '').slice(0, 8) || '-';
+}
+/** Minimal SessionMeta for a live session, enough for `buildResumeCommand` + placement. */
+export function metaFromActive(s) {
+    return {
+        id: s.sessionId ?? '',
+        shortId: shortId(s),
+        agent: s.kind,
+        timestamp: new Date(s.startedAtMs ?? Date.now()).toISOString(),
+        filePath: '',
+        cwd: s.cwd,
+    };
+}
+/** Look up the rich indexed SessionMeta by id so `version` survives (version-pinned resume). */
+async function richMetaById(id) {
+    try {
+        const metas = await discoverSessions({ all: true, since: '90d', limit: 2000 });
+        return metas.find((m) => m.id === id) ?? metas.find((m) => m.id.startsWith(id));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * `focus`'s fallback for a session with no attach rail: reopen it and hand you to it.
+ *   - remote → resume ON the peer over SSH (foreground) — the peer resolves the pinned
+ *              version and holds the transcript, and `-tt` delivers you there.
+ *   - local  → resume in a new tab in your terminal, version-pinned via the indexed meta.
+ * Note: for a session that's still mid-run, this opens a COPY (the original keeps going);
+ * only tmux can *join* a live one without forking (see the header).
+ */
+const resumeInNewTab = async (s, remote) => {
+    const id = s.sessionId ?? '';
+    if (!id) {
+        console.log(chalk.yellow('This session has no id to resume.'));
+        return;
+    }
+    // Remote: the transcript + pinned version live on the peer, so resume THERE over SSH.
+    // runOnPeer runs `agents sessions resume <id>` with a real TTY (`-tt`) in the foreground —
+    // it actually delivers you to the session (the peer picks the right version + HOME).
+    if (remote) {
+        console.log(chalk.gray(`${shortId(s)} has no live terminal on ${remote} — resuming it there over SSH…`));
+        const rc = await runOnPeer(['sessions', 'resume', id], remote, { tty: true });
+        if (rc === 'no-target') {
+            console.log(chalk.red(`${remote} isn't reachable as a device. Try: agents devices sync`));
+            console.log(chalk.gray(`  or run it yourself: ssh ${remote} 'agents sessions resume ${shortId(s)}'`));
+        }
+        return;
+    }
+    // Local: resume in a new tab. Use the indexed meta so the version-pinned binary
+    // resumes in the same isolated HOME the transcript was written in.
+    const meta = (await richMetaById(id)) ?? metaFromActive(s);
+    const command = buildResumeCommand(meta);
+    if (!command) {
+        console.log(chalk.yellow(`${meta.shortId} — ${meta.agent} sessions aren't resumable, so there's no way to reopen it.`));
+        return;
+    }
+    const cwd = meta.cwd && fs.existsSync(meta.cwd) ? meta.cwd : process.cwd();
+    const ctx = currentContext();
+    const backend = detectCurrentBackend(ctx) ?? availableBackends(ctx)[0]?.id;
+    if (!backend) {
+        // No tab-capable surface (off-macOS, not in tmux) — resume in this process.
+        await resumeSessionInPlace(meta);
+        return;
+    }
+    console.log(chalk.gray(`${shortId(s)} has no live terminal to attach — opening a new ${backend} tab and resuming a copy.`));
+    const results = await openSurfaces([{ cwd, command }], { backend, packing: 'tabs' });
+    const r = results[0];
+    if (!r || !r.ok) {
+        console.log(chalk.red(`  failed to open — ${r?.error ?? 'unknown error'}`));
+        console.log(chalk.gray(`  try: agents sessions resume ${meta.shortId}`));
+    }
+};

package/dist/commands/go.d.ts

@@ -1,21 +1,35 @@
 /**
- * `agents sessions go [id]` — jump to a LIVE agent session's terminal.
+ * `agents sessions go [id]` — DEPRECATED alias for `agents sessions focus --attach-only`.
  *
- * No id  -> the SAME rich interactive picker as `agents sessions` (worktree, PR,
- *           changed files, tools, tests, last response — this-machine first),
- *           filtered to sessions that are running right now.
- * With id -> jump directly.
+ * `go` was "attach or refuse" (never fork/resume). `focus --attach-only` is exactly
+ * that behavior, so `go` now prints a deprecation notice and delegates to `focusAction`.
  *
- * "Jump" is not "resume" (which spawns a new process from the transcript). It walks
- * you to the already-running terminal:
- *   local tmux    -> attach (switch-client when already inside tmux)
- *   local Ghostty -> focus its tab (Cmd+<n> via System Events; tab # from ghostty-tabs)
- *   remote tmux   -> ssh -tt + tmux attach (pane->session resolved on the remote)
- *   otherwise     -> refuse with a reason + resume hint (cloud / no attach rail)
+ * This file still owns the shared reach engine that `focus` imports:
+ *   - `gatherLiveTargets` / `pickLiveTarget` / `buildLivePool` — live-session discovery + picker
+ *   - `jumpTo` — the side-effecting jump: attach the already-running terminal
+ *       local tmux    -> attach (switch-client when already inside tmux)
+ *       local Ghostty -> focus its tab (Cmd+<n> via System Events; tab # from ghostty-tabs)
+ *       remote tmux   -> ssh -tt + tmux attach (pane->session resolved on the remote)
+ *       otherwise     -> hand off to the `UnreachableFallback` (attach-only refuses; focus resumes)
+ *   - `refuseFallback` — the attach-only fallback (remote -> login shell; local -> refuse)
  */
 import type { Command } from 'commander';
 import { type ActiveSession } from '../lib/session/active.js';
+import type { SessionMeta } from '../lib/session/types.js';
 export declare function registerGoCommand(program: Command): void;
+/** Live jump targets (local + remote), keyed by session id. Cloud excluded (no pid). */
+export declare function gatherLiveTargets(local: boolean): Promise<{
+    self: string;
+    activeById: Map<string, ActiveSession>;
+}>;
+/** Interactive pick over the live sessions' rich SessionMeta; returns the chosen live session. */
+export declare function pickLiveTarget(activeById: Map<string, ActiveSession>, self: string, message: string, enterHint: string): Promise<ActiveSession | null>;
+/**
+ * Map each live session to its rich SessionMeta (worktree/PR/changes/tools/tests
+ * via the shared picker), reusing `discoverSessions`. Remote or unindexed live
+ * sessions get a minimal synthesized meta so they still appear and jump.
+ */
+export declare function buildLivePool(activeById: Map<string, ActiveSession>, self: string): Promise<SessionMeta[]>;
 export interface Where {
     label: string;
     action: string;
@@ -26,3 +40,12 @@ export interface Where {
  * `jumpTo` below: remote-tmux, then local-tmux, then ghostty, then refuse.
  */
 export declare function describeWhere(s: ActiveSession, self: string): Where;
+/**
+ * What to do when a session can't be *attached* (no tmux/Ghostty rail). `go`
+ * refuses; `focus` opens a new tab and resumes. `remote` is the peer name when
+ * the session lives on another machine, else undefined.
+ */
+export type UnreachableFallback = (s: ActiveSession, remote: string | undefined) => void | Promise<void>;
+/** Default (attach-only): open a login shell on the remote, or refuse locally. */
+export declare function refuseFallback(s: ActiveSession, remote: string | undefined): Promise<void>;
+export declare function jumpTo(s: ActiveSession, self: string, fallback?: UnreachableFallback): Promise<void>;

package/dist/commands/go.js

@@ -1,17 +1,17 @@
 /**
- * `agents sessions go [id]` — jump to a LIVE agent session's terminal.
+ * `agents sessions go [id]` — DEPRECATED alias for `agents sessions focus --attach-only`.
  *
- * No id  -> the SAME rich interactive picker as `agents sessions` (worktree, PR,
- *           changed files, tools, tests, last response — this-machine first),
- *           filtered to sessions that are running right now.
- * With id -> jump directly.
+ * `go` was "attach or refuse" (never fork/resume). `focus --attach-only` is exactly
+ * that behavior, so `go` now prints a deprecation notice and delegates to `focusAction`.
  *
- * "Jump" is not "resume" (which spawns a new process from the transcript). It walks
- * you to the already-running terminal:
- *   local tmux    -> attach (switch-client when already inside tmux)
- *   local Ghostty -> focus its tab (Cmd+<n> via System Events; tab # from ghostty-tabs)
- *   remote tmux   -> ssh -tt + tmux attach (pane->session resolved on the remote)
- *   otherwise     -> refuse with a reason + resume hint (cloud / no attach rail)
+ * This file still owns the shared reach engine that `focus` imports:
+ *   - `gatherLiveTargets` / `pickLiveTarget` / `buildLivePool` — live-session discovery + picker
+ *   - `jumpTo` — the side-effecting jump: attach the already-running terminal
+ *       local tmux    -> attach (switch-client when already inside tmux)
+ *       local Ghostty -> focus its tab (Cmd+<n> via System Events; tab # from ghostty-tabs)
+ *       remote tmux   -> ssh -tt + tmux attach (pane->session resolved on the remote)
+ *       otherwise     -> hand off to the `UnreachableFallback` (attach-only refuses; focus resumes)
+ *   - `refuseFallback` — the attach-only fallback (remote -> login shell; local -> refuse)
  */
 import chalk from 'chalk';
 import path from 'path';
@@ -21,8 +21,8 @@ import { getActiveSessions, findSessionFileForKind } from '../lib/session/active
 import { gatherRemoteActive } from '../lib/session/remote-active.js';
 import { discoverSessions } from '../lib/session/discover.js';
 import { dedupeByMachineSession, mergeLocalFirst, pickSessionInteractive } from './sessions.js';
+import { focusAction } from './focus.js';
 import { machineId } from '../lib/session/sync/config.js';
-import { isInteractiveTerminal } from './utils.js';
 import { attachTmux, runTmux } from '../lib/tmux/binary.js';
 import { getDefaultSocketPath } from '../lib/tmux/paths.js';
 import { sshStream, assertValidSshTarget, shellQuote } from '../lib/ssh-exec.js';
@@ -33,20 +33,21 @@ export function registerGoCommand(program) {
         .command('go')
         .argument('[id]', 'Short/full session id to jump to; omit for an interactive picker')
         .option('--local', 'Only this machine (skip the cross-host sweep)')
-        .description('Jump to a live agent session — attach its tmux, or focus its terminal tab')
+        .description('Deprecated alias for `sessions focus --attach-only`')
         .action(async (id, opts) => {
-        await goAction(id, opts);
+        console.error(chalk.yellow('`sessions go` is deprecated — use `sessions focus --attach-only`'));
+        await focusAction(id, { local: opts.local, attachOnly: true });
     });
 }
-async function goAction(id, opts) {
+/** Live jump targets (local + remote), keyed by session id. Cloud excluded (no pid). */
+export async function gatherLiveTargets(local) {
     const self = machineId();
-    // Live jump targets (local + remote), keyed by session id.
     const localActive = await getActiveSessions();
     for (const s of localActive)
         if (!s.machine)
             s.machine = self;
     let active = localActive;
-    if (!opts.local) {
+    if (!local) {
         try {
             const remote = await gatherRemoteActive();
             active = dedupeByMachineSession([...localActive, ...remote.sessions]);
@@ -57,54 +58,24 @@ async function goAction(id, opts) {
     for (const s of active)
         if (s.context !== 'cloud' && s.sessionId)
             activeById.set(s.sessionId, s);
-    if (activeById.size === 0) {
-        console.log(chalk.gray('No live agent sessions to jump to.'));
-        return;
-    }
-    // Direct jump by id — no picker.
-    if (id) {
-        const q = id.toLowerCase();
-        const matches = [...activeById.values()].filter((s) => s.sessionId.toLowerCase().startsWith(q));
-        if (matches.length === 0) {
-            console.error(chalk.red(`No live session matching "${id}".`));
-            process.exitCode = 1;
-            return;
-        }
-        if (matches.length > 1) {
-            console.error(chalk.red(`"${id}" is ambiguous (${matches.length} matches). Use more of the id.`));
-            process.exitCode = 1;
-            return;
-        }
-        await jumpTo(matches[0], self);
-        return;
-    }
-    if (!isInteractiveTerminal()) {
-        console.error(chalk.red('go needs an interactive terminal, or pass a session id.'));
-        process.exitCode = 1;
-        return;
-    }
-    // Reuse the rich `sessions` picker over the live sessions' full SessionMeta.
+    return { self, activeById };
+}
+/** Interactive pick over the live sessions' rich SessionMeta; returns the chosen live session. */
+export async function pickLiveTarget(activeById, self, message, enterHint) {
     const pool = await buildLivePool(activeById, self);
-    if (pool.length === 0) {
-        console.log(chalk.gray('No live sessions to jump to.'));
-        return;
-    }
-    const picked = await pickSessionInteractive(pool, 'Jump to a live session:', undefined, 0, 'jump');
+    if (pool.length === 0)
+        return null;
+    const picked = await pickSessionInteractive(pool, message, undefined, 0, enterHint);
     if (!picked)
-        return;
-    const target = activeById.get(picked.session.id);
-    if (!target) {
-        console.log(chalk.yellow(`${picked.session.shortId} is no longer live — try: `) + chalk.gray(`agents sessions resume ${picked.session.shortId}`));
-        return;
-    }
-    await jumpTo(target, self);
+        return null;
+    return activeById.get(picked.session.id) ?? null;
 }
 /**
  * Map each live session to its rich SessionMeta (worktree/PR/changes/tools/tests
  * via the shared picker), reusing `discoverSessions`. Remote or unindexed live
  * sessions get a minimal synthesized meta so they still appear and jump.
  */
-async function buildLivePool(activeById, self) {
+export async function buildLivePool(activeById, self) {
     let metas = [];
     try {
         metas = await discoverSessions({ all: true, since: '30d', limit: 1000 });
@@ -161,7 +132,17 @@ 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)' };
 }
-async function jumpTo(s, self) {
+/** Default (attach-only): open a login shell on the remote, or refuse locally. */
+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 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)}`));
+}
+export async function jumpTo(s, self, fallback = refuseFallback) {
     const remote = s.machine && s.machine !== self ? s.machine : undefined;
     const mux = s.provenance?.mux;
     // Path C: remote tmux — ssh in and attach, resolving the pane's session on the remote.
@@ -177,9 +158,9 @@ async function jumpTo(s, self) {
             console.log(chalk.gray(`Attaching ${shortId(s)} on ${remote} over SSH — Ctrl-b d to detach.`));
             process.exit(sshStream(remote, remoteCmd, { tty: true }));
         }
-        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 }));
+        // Remote, not in tmux → hand off to the fallback (go: shell; focus: resume in a tab).
+        await fallback(s, remote);
+        return;
     }
     // Path B: local tmux — attach (or switch-client if we're already inside tmux).
     if (mux?.kind === 'tmux' && mux.pane) {
@@ -218,9 +199,8 @@ async function jumpTo(s, self) {
             chalk.gray(tab != null ? ` — switch to tab ${tab} (Cmd+${tab}).` : " — couldn't pinpoint its tab (same-repo forks are ambiguous); switch tabs manually."));
         return;
     }
-    // Path D: refuse with a reason.
-    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)}`));
+    // Path D: no attach rail (headless / plain terminal) → hand off to the fallback.
+    await fallback(s, undefined);
 }
 /** Resolve a local tmux pane id to its session name + window index. */
 async function resolveLocalPane(socket, pane) {

package/dist/commands/secrets.js

@@ -490,7 +490,7 @@ export function registerSecretsCommands(program) {
       # See what's in the bundle (values masked); shows its prompt policy
       agents secrets view prod
 
-      # Stop a noisy automation bundle from prompting every run: ask once a day
+      # Stop a noisy automation bundle from prompting every run: ask once a week
       agents secrets policy prod daily
 
       # Eval the bundle into your current shell
@@ -510,15 +510,16 @@ export function registerSecretsCommands(program) {
       Touch ID noise: macOS pops a prompt per bundle per process. Each bundle has
       a prompt policy, shown in the POLICY column of 'agents secrets list':
         daily (default)   ask once, then hold it silently in the local agent up
-                          to ~24h, until screen-lock / sleep / logout or 'lock'.
+                          to ~7 days, until sleep / logout or 'lock' (a bare
+                          screen-lock does NOT drop it). Name is historical.
         always            ask for Touch ID every time — never auto-held.
-      The default is 'daily' (one Touch ID per ~24h); change it globally with
+      The default is 'daily' (one Touch ID per ~7 days); change it globally with
       'secrets.policy' in agents.yaml, or per bundle with 'agents secrets policy
       <bundle> always'. 'agents secrets unlock <bundle>' holds any bundle after one
       prompt regardless of policy. Nothing on disk.
 
       See also:
-        agents secrets policy <bundle> daily           ask once a day, not every run
+        agents secrets policy <bundle> daily           ask once a week, not every run
         agents secrets unlock <bundle>                 hold a bundle after one Touch ID
         agents secrets lock                            wipe held bundles (re-prompt next read)
         agents secrets status                          show held bundles + when they lock
@@ -623,7 +624,7 @@ export function registerSecretsCommands(program) {
             }
             else {
                 console.log(bundlePolicy(bundle) === 'daily'
-                    ? chalk.gray('policy: daily (ask once, then held ~24h until screen-lock / sleep / logout)')
+                    ? chalk.gray('policy: daily (ask once, then held ~7 days until sleep / logout — screen-lock does not drop it)')
                     : chalk.gray('policy: always (asks for Touch ID every time — never auto-held)'));
             }
             if (bundle.created_at)
@@ -747,7 +748,7 @@ export function registerSecretsCommands(program) {
         .description('Create an empty bundle')
         .option('--description <text>', 'Free-form description')
         .option('--allow-exec', 'Allow exec: refs in this bundle (off by default)')
-        .option('--policy <policy>', 'prompt policy: daily (default, ask once a day), always (ask every time), or never (silent, NO biometry ACL — needs --i-understand)')
+        .option('--policy <policy>', 'prompt policy: daily (default, ask once a week), always (ask every time), or never (silent, NO biometry ACL — needs --i-understand)')
         .addOption(new Option('--tier <policy>', 'deprecated alias for --policy').hideHelp())
         .option('--i-understand', 'Confirm creating a "never"-policy bundle (no biometry ACL) without an interactive prompt')
         .option('--backend <backend>', 'storage backend: keychain (default) or file (passphrase-encrypted, headless-readable)', 'keychain')
@@ -1528,7 +1529,7 @@ Examples:
     cmd
         .command('unlock [names...]')
         .description('Hold a bundle in the secrets-agent after one Touch ID, so concurrent runs read it without re-prompting (macOS).')
-        .option('--ttl <duration>', 'How long to hold it (e.g. 30m, 8h). Default 24h.')
+        .option('--ttl <duration>', 'How long to hold it (e.g. 30m, 8h, 3d). Default 7d.')
         .option('--all', 'Unlock every configured bundle')
         .action(async (names, opts) => {
         if (process.platform !== 'darwin') {
@@ -1544,7 +1545,7 @@ Examples:
         if (opts.ttl) {
             const secs = parseDuration(opts.ttl);
             if (!secs) {
-                console.error(chalk.red(`Invalid --ttl '${opts.ttl}'. Use e.g. 30m, 2h, 8h.`));
+                console.error(chalk.red(`Invalid --ttl '${opts.ttl}'. Use e.g. 30m, 2h, 8h, 3d.`));
                 process.exit(1);
             }
             ttlMs = secs * 1000;
@@ -1628,7 +1629,7 @@ Examples:
     cmd
         .command('policy <bundle> [policy]')
         .alias('tier')
-        .description("Show or set a bundle's prompt policy: daily (default, ask once a day), always (ask every time), or never (silent, NO biometry ACL).")
+        .description("Show or set a bundle's prompt policy: daily (default, ask once a week), always (ask every time), or never (silent, NO biometry ACL).")
         .option('--i-understand', 'Confirm switching to the "never" policy (no biometry ACL) without an interactive prompt')
         .action(async (bundleName, policyArg, opts) => {
         try {
@@ -1644,11 +1645,23 @@ Examples:
                 console.error(chalk.yellow('Aborted.'));
                 return;
             }
+            const wasDaily = bundlePolicy(bundle) === 'daily';
             bundle.policy = next;
             writeBundle(bundle);
+            // Tightening daily -> always/never must take effect NOW, not up to the
+            // ~7d hold later. If the broker is already serving this bundle silently
+            // (auto-cached under the old `daily` policy), evict it so the next read
+            // re-prompts (`always`) or reads its no-ACL item directly (`never`).
+            // macOS-only + best-effort; agentLock no-ops off darwin / with no broker.
+            if (wasDaily && next !== 'daily') {
+                try {
+                    await agentLock(bundle.name);
+                }
+                catch { /* broker down — nothing held */ }
+            }
             console.log(chalk.green(`${bundle.name} policy set to ${next}.`));
             if (next === 'daily') {
-                console.log(chalk.gray('Held by the secrets-agent for ~24h after one unlock (auto-cache is on by default; disable with `secrets.agent.auto: false` in agents.yaml).'));
+                console.log(chalk.gray('Held by the secrets-agent for ~7 days after one unlock (auto-cache is on by default; disable with `secrets.agent.auto: false` in agents.yaml).'));
             }
             else if (next === 'always') {
                 console.log(chalk.gray('Asks for Touch ID every time — never auto-held.'));

package/dist/commands/sessions.d.ts

@@ -98,6 +98,15 @@ export declare function dedupeByMachineSession(sessions: ActiveSession[]): Activ
  * `localMachine` is injected so the ordering is testable without os.hostname().
  */
 export declare function mergeLocalFirst(sessions: SessionMeta[], localMachine: string): SessionMeta[];
+/**
+ * Serialize a `SessionMeta[]` to the clean JSON shape the `--json` listing
+ * emits: strip the internal-only scoring/provenance fields (`_matchedTerms`,
+ * `_bm25Score`, `_remote`) that are search/fan-out bookkeeping, never part of
+ * the public record, then pretty-print as a 2-space array with a trailing
+ * newline. The single seam shared by the local `--json` path and the
+ * `--json --host` remote fan-out so both emit byte-identical row shapes.
+ */
+export declare function serializeSessionsJson(sessions: SessionMeta[]): string;
 /**
  * Whether the local machine's sessions belong in an `--active` view. Local is
  * included by default; an explicit `--host`/`--device` list scopes the view to

package/dist/commands/sessions.js

@@ -40,6 +40,7 @@ import { registerSessionsTailCommand } from './sessions-tail.js';
 import { registerSessionsSyncCommand } from './sessions-sync.js';
 import { registerSessionsResumeCommand } from './sessions-resume.js';
 import { registerGoCommand } from './go.js';
+import { registerFocusCommand } from './focus.js';
 import { registerSessionsInjectCommand } from './sessions-inject.js';
 const SESSION_AGENT_FILTER_HELP = `Filter by agent, e.g. claude, codex, claude@2.0.65`;
 /**
@@ -507,6 +508,40 @@ export function mergeLocalFirst(sessions, localMachine) {
     });
     return keys.flatMap((k) => byMachine.get(k));
 }
+/**
+ * Serialize a `SessionMeta[]` to the clean JSON shape the `--json` listing
+ * emits: strip the internal-only scoring/provenance fields (`_matchedTerms`,
+ * `_bm25Score`, `_remote`) that are search/fan-out bookkeeping, never part of
+ * the public record, then pretty-print as a 2-space array with a trailing
+ * newline. The single seam shared by the local `--json` path and the
+ * `--json --host` remote fan-out so both emit byte-identical row shapes.
+ */
+export function serializeSessionsJson(sessions) {
+    const serializable = sessions.map((s) => {
+        const { _matchedTerms, _bm25Score, _remote, ...rest } = s;
+        return rest;
+    });
+    return JSON.stringify(serializable, null, 2) + '\n';
+}
+/**
+ * `agents sessions --json --host <h>` — fan the RECENT (non-active) listing out
+ * to the named host(s) and emit ONE clean merged `SessionMeta[]` JSON array,
+ * the same shape the local `--json` path emits. Reuses `gatherRemoteList` (the
+ * exact SSH fan-out the interactive cross-machine listing already uses) and
+ * serializes the merged, machine-tagged rows — instead of `runRemoteSessions`,
+ * which streams each remote's raw stdout under a per-host banner and so can
+ * never be JSON.parsed. A dead host contributes `[]` (with a stderr note from
+ * the fan-out), so stdout is always a valid array and the exit stays 0.
+ */
+async function runRemoteSessionsJson(hosts) {
+    // Forward the caller's own filters (query, --limit, --since, …) minus --host,
+    // and guarantee --json so each peer answers with a parseable array.
+    const forwarded = buildForwardedArgs(process.argv, new Set(hosts));
+    if (!forwarded.includes('--json'))
+        forwarded.push('--json');
+    const { sessions } = await gatherRemoteList(forwarded, hosts);
+    process.stdout.write(serializeSessionsJson(sessions));
+}
 /**
  * `running N · idle N · waiting N · queued N` for a bucket of sessions (zero
  * buckets omitted). Same bucketing as the grand-total summary so per-group
@@ -715,10 +750,17 @@ async function sessionsAction(query, options) {
     if (options.device && options.device.length > 0) {
         options.host = [...(options.host ?? []), ...options.device];
     }
-    // --host WITHOUT --active keeps the legacy per-host stream (each remote's raw
-    // stdout under a `── host ──` banner). With --active, the hosts are folded
-    // into the merged machine-grouped view instead (handled below).
+    // --host WITHOUT --active. `--json` fans the recent listing out and emits ONE
+    // clean merged SessionMeta[] array (same shape as the local --json path), for
+    // scripts/extensions that JSON.parse a remote's history. Without --json it
+    // keeps the legacy per-host stream (each remote's raw stdout under a
+    // `── host ──` banner). With --active, the hosts are folded into the merged
+    // machine-grouped view instead (handled below).
     if (options.host && options.host.length > 0 && !options.active) {
+        if (options.json) {
+            await runRemoteSessionsJson(options.host);
+            return;
+        }
         try {
             runRemoteSessions(options.host);
         }
@@ -858,11 +900,7 @@ async function sessionsAction(query, options) {
         }
         if (options.json) {
             const filtered = searchQuery ? filterSessionsByQuery(sessions, searchQuery) : sessions;
-            const serializable = filtered.map(s => {
-                const { _matchedTerms, _bm25Score, _remote, ...rest } = s;
-                return rest;
-            });
-            process.stdout.write(JSON.stringify(serializable, null, 2) + '\n');
+            process.stdout.write(serializeSessionsJson(filtered));
             return;
         }
         // Cross-machine fan-out: unless --local (or we ARE a peer answering a
@@ -2014,6 +2052,7 @@ export function registerSessionsCommands(program) {
     registerSessionsSyncCommand(sessionsCmd);
     registerSessionsResumeCommand(sessionsCmd);
     registerGoCommand(sessionsCmd);
+    registerFocusCommand(sessionsCmd);
     registerSessionsInjectCommand(sessionsCmd);
 }
 function formatNoSessionsMessage(showAll, project) {

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/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 {
@@ -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);
                 }

package/dist/lib/shims.d.ts

@@ -77,7 +77,7 @@ export interface ConflictInfo {
  *         top-level entry add/remove — deep edits to plugin contents won't
  *         trigger auto-resync, run `agents sync` for that.
  */
-export declare const SHIM_SCHEMA_VERSION = 23;
+export declare const SHIM_SCHEMA_VERSION = 24;
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.

package/dist/lib/shims.js

@@ -211,7 +211,7 @@ async function promptConflictStrategy(conflictInfos) {
 // v22 — export DISABLE_AUTOUPDATER=1 for claude shims so a pinned per-version
 //        install can't self-mutate: Claude Code's background auto-updater would
 //        otherwise rewrite the pinned binary in place. Explicit user value wins.
-export const SHIM_SCHEMA_VERSION = 23;
+export const SHIM_SCHEMA_VERSION = 24;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
 function shellQuote(value) {
@@ -346,16 +346,38 @@ find_project_version() {
   return 1
 }
 
-# Resolve version from agents.yaml (user default)
+# Parse the agents: default map of one agents.yaml for this AGENT's version.
+parse_agents_default() {
+  local meta="$1"
+  [ -f "$meta" ] || return 0
+  awk -v agent="$AGENT" '
+    /^agents:/ { in_agents=1; next }
+    in_agents && /^[^ ]/ { in_agents=0 }
+    in_agents && $0 ~ "^  " agent ":" { gsub(/.*:[[:space:]]*["'"'"']?|["'"'"']?[[:space:]]*$/, ""); print; exit }
+  ' "$meta"
+}
+
+# This machine's device id — mirrors machineId()/normalizeHost() in
+# src/lib/machine-id.ts: first hostname label, lowercased, non-[a-z0-9_-] -> '-'.
+# MUST stay in sync or the shim reads the wrong device folder.
+machine_id() {
+  local raw="\${AGENTS_SYNC_MACHINE_ID:-$(hostname 2>/dev/null)}"
+  # first label -> trim -> lowercase -> non-[a-z0-9_-] to '-' (matches normalizeHost order).
+  raw=$(printf '%s' "$raw" | cut -d. -f1 | sed 's/^[[:space:]]*//; s/[[:space:]]*$//' | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9_-]/-/g')
+  [ -n "$raw" ] && printf '%s' "$raw" || printf 'unknown'
+}
+
+# Resolve the default version. The agents: version pins are stored PER-DEVICE at
+# devices/<machine>/agents.yaml (moved there so multi-machine syncs never
+# conflict); read that first, then fall back to the central agents.yaml for
+# pre-split installs. Must match readMeta()'s central+device merge in state.ts --
+# reading only the central file (the old behavior) missed every device pin and
+# made the shim re-prompt "no default set" on every launch.
 resolve_default_version() {
-  local meta="$AGENTS_USER_DIR/agents.yaml"
-  if [ -f "$meta" ]; then
-    awk -v agent="$AGENT" '
-      /^agents:/ { in_agents=1; next }
-      in_agents && /^[^ ]/ { in_agents=0 }
-      in_agents && $0 ~ "^  " agent ":" { gsub(/.*:[[:space:]]*["'"'"']?|["'"'"']?[[:space:]]*$/, ""); print; exit }
-    ' "$meta"
-  fi
+  local v
+  v=$(parse_agents_default "$AGENTS_USER_DIR/devices/$(machine_id)/agents.yaml")
+  [ -n "$v" ] || v=$(parse_agents_default "$AGENTS_USER_DIR/agents.yaml")
+  printf '%s' "$v"
 }
 
 # Find the latest installed version by numeric component comparison.

package/dist/lib/types.d.ts

@@ -599,9 +599,9 @@ export interface Meta {
     run?: RunConfig;
     /** macOS secrets-agent config. `policy` is the default prompt policy for
      * bundles without an explicit per-bundle policy: `daily` (the default) asks
-     * once per ~24h, `always` asks every time. `auto` (default on) lets the first
-     * real keychain read of a `daily` bundle populate the broker so concurrent
-     * runs read silently — set it `false` to force a prompt on every read. */
+     * once per ~7 days, `always` asks every time. `auto` (default on) lets the
+     * first real keychain read of a `daily` bundle populate the broker so
+     * concurrent runs read silently — set it `false` to force a prompt on every read. */
     secrets?: {
         policy?: 'always' | 'daily';
         agent?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.39",
+  "version": "1.20.41",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",