@phnx-labs/agents-cli 1.20.76 → 1.20.77

package/dist/lib/runner.js

@@ -29,6 +29,7 @@ import { backgroundSpawnOptions } from './platform/process.js';
 import { walkForFiles } from './fs-walk.js';
 import { getBinaryPath, getVersionHomePath, isVersionInstalled, resolveVersion } from './versions.js';
 import { claudeHomeHasOwnCredential } from './agents.js';
+import { resolveAccountSetupToken } from './secrets/account-token.js';
 import { getConfiguredRunStrategy, resolveRunVersion, resolveAccountVersion, rotationFailoverChain, readinessFromCandidate, } from './rotate.js';
 import { readAuthHealth, isDeadVerdict } from './auth-health.js';
 import { machineId } from './machine-id.js';
@@ -399,18 +400,28 @@ export function buildRoutineSpawnEnv(baseEnv, agent, version, timezone) {
         if (v !== undefined)
             out[k] = v;
     }
-    // RUSH-1979: the daemon injects one ambient CLAUDE_CODE_OAUTH_TOKEN (RUSH-1759)
-    // so a token-less default account still authenticates. When balanced rotation
-    // pins THIS spawn to a specific account's CLAUDE_CONFIG_DIR that holds its own
-    // credential, that ambient token would shadow the account (Claude and the Linux
-    // shim both prefer the env var) — making the pool inert and 401ing on the one
-    // stale token. Drop it here so the pinned account authenticates itself; keep it
-    // when the account has no on-disk credential (the RUSH-1759 default).
-    if (agent === 'claude' &&
-        version &&
-        out.CLAUDE_CONFIG_DIR &&
-        claudeHomeHasOwnCredential(getVersionHomePath('claude', version))) {
-        delete out.CLAUDE_CODE_OAUTH_TOKEN;
+    // A headless routine should authenticate the rotation-pinned account via its
+    // long-lived, NON-rotating setup-token, not the interactive OAuth session.
+    // Claude Code's interactive session uses single-use rotating refresh tokens: one
+    // fleet machine refreshing invalidates that account on every other machine, so
+    // they 401 and log out (Claude Code #25609 / #56339) — the fleet-wide daily
+    // logout. If the daemon injected this account's per-account
+    // CLAUDE_CODE_OAUTH_TOKEN_<slug> (from a headless-readable no-ACL bundle), use it;
+    // that also works on macOS, where the drop path below is inert
+    // (claudeHomeHasOwnCredential is false on darwin, agents.ts).
+    //
+    // Fallback (RUSH-1979): with no per-account token, keep the prior behavior — drop
+    // the single ambient CLAUDE_CODE_OAUTH_TOKEN when the pinned account has its own
+    // on-disk credential (Linux) so it isn't shadowed; keep it otherwise.
+    if (agent === 'claude' && version && out.CLAUDE_CONFIG_DIR) {
+        const home = getVersionHomePath('claude', version);
+        const accountToken = resolveAccountSetupToken(baseEnv, home);
+        if (accountToken) {
+            out.CLAUDE_CODE_OAUTH_TOKEN = accountToken;
+        }
+        else if (claudeHomeHasOwnCredential(home)) {
+            delete out.CLAUDE_CODE_OAUTH_TOKEN;
+        }
     }
     if (timezone)
         out.TZ = timezone;
@@ -512,11 +523,19 @@ export async function executeJob(config, deps) {
     if (eligibility) {
         throw new Error(eligibility.message);
     }
-    // `host:` placement — the job body runs on another machine over SSH; local
-    // version selection / sandbox / spawn do not apply. Sync callers (manual
-    // `routines run`, catchup) follow the remote run to completion.
-    if (config.host) {
-        return executeJobOnHost(config, { detached: false });
+    // Placement (hostStrategy / bare host:) — body may run on another machine
+    // over SSH or in the cloud; local version selection / sandbox / spawn then
+    // do not apply. Sync callers (manual `routines run`, catchup) follow the
+    // remote run to completion when possible.
+    {
+        const { resolvePlacementTarget } = await import('./routines-placement.js');
+        const target = resolvePlacementTarget(config);
+        if (target.mode === 'host') {
+            return executeJobOnHost({ ...config, host: target.host }, { detached: false });
+        }
+        if (target.mode === 'cloud') {
+            return executeJobOnCloud(config, { detached: false });
+        }
     }
     // Command-mode: run a plain shell command directly (no agent, no rotation,
     // no pinning, no sandbox overlay). Reuses the run-record machinery so
@@ -735,6 +754,86 @@ export async function executeJob(config, deps) {
     timer.end({ status: 'failed', exitCode: 1, runId });
     return { meta, reportPath: null };
 }
+/**
+ * Dispatch a routine to the agent's native cloud provider (or the configured
+ * default). Writes a local run record with `cloudTaskId` so list/runs still
+ * work; does not wait for cloud completion on the detached path.
+ */
+async function executeJobOnCloud(config, opts) {
+    if (config.workflow) {
+        throw new Error(`Routine '${config.name}' runs a workflow bundle, which can't execute in the cloud yet — remove 'hostStrategy: cloud' or 'workflow:'.`);
+    }
+    if (config.loop) {
+        throw new Error(`Routine '${config.name}' uses 'loop:', which can't execute in the cloud yet — remove 'hostStrategy: cloud' or 'loop:'.`);
+    }
+    if (config.command) {
+        throw new Error(`Routine '${config.name}' uses 'command:', which can't execute in the cloud yet — remove 'hostStrategy: cloud' or 'command:'.`);
+    }
+    if (!config.agent) {
+        throw new Error(`Routine '${config.name}' hostStrategy: cloud requires an agent`);
+    }
+    const { resolveProvider } = await import('./cloud/registry.js');
+    const { insertTask } = await import('./cloud/store.js');
+    const provider = resolveProvider(undefined, config.agent);
+    const timer = createTimer('agent.run', {
+        agent: config.agent,
+        jobName: config.name,
+        mode: config.mode,
+        placement: 'cloud',
+        ...redactPrompt(config.prompt),
+        schedule: config.schedule,
+    });
+    const runId = generateRunId();
+    const runDir = getRunDir(config.name, runId);
+    fs.mkdirSync(runDir, { recursive: true });
+    const meta = {
+        jobName: config.name,
+        runId,
+        agent: config.agent,
+        pid: null,
+        spawnedAt: Date.now(),
+        status: 'running',
+        startedAt: new Date().toISOString(),
+        completedAt: null,
+        exitCode: null,
+    };
+    writeRunMeta(meta);
+    try {
+        const task = await provider.dispatch({
+            prompt: resolveJobPrompt(config),
+            agent: config.agent,
+            repo: config.repo,
+            timeout: config.timeout,
+            model: config.config?.model,
+        });
+        try {
+            insertTask(task);
+        }
+        catch { /* store is best-effort */ }
+        meta.cloudTaskId = task.id;
+        meta.cloudProvider = task.provider;
+        // Terminal cloud responses (e.g. antigravity) finalize immediately.
+        // Async providers leave the run `running` with the cloud task id for
+        // the user to follow via `agents cloud status`.
+        if (task.status === 'completed') {
+            finalizeRunMeta(meta, 'completed', 0);
+        }
+        else if (task.status === 'failed' || task.status === 'cancelled') {
+            finalizeRunMeta(meta, 'failed', 1, { errorMessage: task.summary ?? `cloud ${task.status}` });
+        }
+        // Non-terminal statuses stay `running` for both detached and sync paths;
+        // the user follows via `agents cloud status <id>`.
+        writeRunMeta(meta);
+        timer.end({ status: meta.status, exitCode: meta.exitCode ?? undefined, runId });
+        return { meta, reportPath: null };
+    }
+    catch (err) {
+        finalizeRunMeta(meta, 'failed', 1, { errorMessage: err.message });
+        writeRunMeta(meta);
+        timer.end({ status: 'failed', exitCode: 1, runId, error: err.message });
+        throw err;
+    }
+}
 async function executeJobOnHost(config, opts) {
     if (config.workflow) {
         throw new Error(`Routine '${config.name}' runs a workflow bundle, which can't execute on a host yet — remove 'host:' or 'workflow:'.`);
@@ -877,24 +976,44 @@ async function executeCommandJobForeground(config) {
     });
     return { meta, reportPath: null };
 }
+/** Invoke a lifecycle hook without letting a caller error break run finalization. */
+function safeHook(fn) {
+    if (!fn)
+        return;
+    try {
+        fn();
+    }
+    catch { /* hooks are best-effort */ }
+}
 /** Spawn a job as a detached process and return immediately with run metadata. */
-/** Spawn a job as a detached process and return immediately with run metadata. */
-export async function executeJobDetached(config) {
+export async function executeJobDetached(config, hooks) {
     const eligibility = checkJobDeviceEligibility(config);
     if (eligibility) {
         process.stderr.write(`[agents] daemon: skipping '${config.name}' — ${eligibility.message}\n`);
         throw new Error(eligibility.message);
     }
-    // `host:` placement — dispatch over SSH and return; the monitor finalizes.
-    if (config.host) {
-        const { meta } = await executeJobOnHost(config, { detached: true });
-        return meta;
+    // Placement (hostStrategy / bare host:) — dispatch off-box and return; the
+    // monitor finalizes host: runs, cloud runs stay terminal when dispatch ends.
+    // Either way the in-process onFinish hook does not fire for off-box routines
+    // (the monitor tick observes an already-finalized record), so notify-desktop
+    // sends the finish notification only for local detached runs below (RUSH-2030).
+    {
+        const { resolvePlacementTarget } = await import('./routines-placement.js');
+        const target = resolvePlacementTarget(config);
+        if (target.mode === 'host') {
+            const { meta } = await executeJobOnHost({ ...config, host: target.host }, { detached: true });
+            return meta;
+        }
+        if (target.mode === 'cloud') {
+            const { meta } = await executeJobOnCloud(config, { detached: true });
+            return meta;
+        }
     }
     // Command-mode: fire a plain shell command detached (no agent, no rotation,
     // no pinning, no sandbox overlay). Still writes a run record so the daemon,
     // list/runs, and overdue tracking keep working.
     if (config.command) {
-        return executeCommandJobDetached(config);
+        return executeCommandJobDetached(config, hooks);
     }
     // Pre-flight: pick a healthy version/account so the daemon does not launch
     // into a credit-exhausted install. Detached cannot mid-run failover (no exit
@@ -962,6 +1081,9 @@ export async function executeJobDetached(config) {
         const isAuthFailure = !!errorMessage && errorMessage.startsWith('auth_failed:');
         if (status !== 'timeout' && !isAuthFailure)
             extractAndSaveReport(stdoutPath, effectiveAgent, runDir);
+        // Fire the finish/output notification AFTER the report is written so the hook
+        // can read report.md (RUSH-2030). Best-effort; never breaks finalization.
+        safeHook(hooks?.onFinish ? () => hooks.onFinish(meta) : undefined);
     };
     child.on('exit', (code) => {
         let logText = '';
@@ -1008,7 +1130,7 @@ export async function executeJobDetached(config) {
  * un-sandboxed, unref, then record the pid. The daemon does not wait for exit;
  * `monitorRunningJobs` reaps the record on the next tick.
  */
-function executeCommandJobDetached(config) {
+function executeCommandJobDetached(config, hooks) {
     const runId = generateRunId();
     const runDir = getRunDir(config.name, runId);
     fs.mkdirSync(runDir, { recursive: true });
@@ -1053,6 +1175,9 @@ function executeCommandJobDetached(config) {
         settled = true;
         finalizeRunMeta(meta, status, exitCode, errorMessage ? { errorMessage } : undefined);
         writeRunMeta(meta);
+        // Finish notification (RUSH-2030). For command routines the threshold only
+        // surfaces failures, decided in routine-notify.ts. Best-effort.
+        safeHook(hooks?.onFinish ? () => hooks.onFinish(meta) : undefined);
     };
     child.on('exit', (code) => settle(code === 0 ? 'completed' : 'failed', code ?? 1));
     child.on('error', (err) => {

package/dist/lib/sandbox.js

@@ -75,6 +75,16 @@ export function buildSpawnEnv(overlayHome, extraEnv) {
             env[key] = process.env[key];
         }
     }
+    // Per-account Claude setup-tokens: the daemon injects a CLAUDE_CODE_OAUTH_TOKEN_<slug>
+    // for each account so a routine authenticates its rotation-pinned account via a
+    // long-lived, non-rotating token (see runner.ts buildRoutineSpawnEnv). Forward every
+    // such key by prefix — same trust tier as CLAUDE_CODE_OAUTH_TOKEN above; still no API
+    // keys or other provider secrets.
+    for (const key of Object.keys(process.env)) {
+        if (key.startsWith('CLAUDE_CODE_OAUTH_TOKEN_') && process.env[key]) {
+            env[key] = process.env[key];
+        }
+    }
     if (extraEnv) {
         Object.assign(env, extraEnv);
     }

package/dist/lib/secrets/account-token.d.ts

@@ -0,0 +1,20 @@
+/** The `CLAUDE_CODE_OAUTH_TOKEN_<slug>` env key for a given account email/id. */
+export declare function accountTokenKey(account: string): string;
+/**
+ * Read the signed-in account email for a Claude version home from
+ * `oauthAccount.emailAddress`. Sync, no keychain, no network. Tries both stores
+ * the canonical resolver uses (agents.ts getAccountInfo): the shim-set
+ * `CLAUDE_CONFIG_DIR` location `<home>/.claude/.claude.json` first, then the
+ * home-level `<home>/.claude.json` (an account signed in via the IDE / direct
+ * binary without the shim writes there). Returns null when neither has a usable
+ * email.
+ */
+export declare function readClaudeAccountEmail(home: string): string | null;
+/**
+ * Resolve the per-account setup-token for the account pinned to `home`, looking
+ * it up in the provided env (the daemon injects the `claude` bundle's
+ * `CLAUDE_CODE_OAUTH_TOKEN_*` keys). Returns null when the home has no known
+ * account, or no matching per-account token is present — callers then leave the
+ * existing ambient/interactive credential untouched (a safe no-op).
+ */
+export declare function resolveAccountSetupToken(env: Record<string, string | undefined>, home: string): string | null;

package/dist/lib/secrets/account-token.js

@@ -0,0 +1,64 @@
+// Per-account Claude setup-token resolution.
+//
+// A headless/unattended Claude run should authenticate with the account's
+// long-lived `claude setup-token` (exported as a per-account
+// `CLAUDE_CODE_OAUTH_TOKEN_<slug>` env var), NOT the interactive OAuth session.
+// Claude Code's interactive session uses single-use ROTATING refresh tokens: when
+// one machine refreshes, the server invalidates the old refresh token globally, so
+// every other machine on that account 401s and gets logged out (Claude Code
+// #25609 / #56339). The 1-year setup-token sits earlier in the auth precedence
+// (`CLAUDE_CODE_OAUTH_TOKEN`, before subscription login) and does not participate
+// in that rotation — so per-account setup-tokens keep the fleet signed in.
+//
+// The per-account env key encodes the account email. The convention (verified
+// against live bundles, e.g. `muqsit@getrush.ai` →
+// `CLAUDE_CODE_OAUTH_TOKEN_MUQSIT_AT_GETRUSH_DOT_AI`): upper-case, `@`→`_AT_`,
+// `.`→`_DOT_`, any other non-alphanumeric → `_`.
+import fs from 'node:fs';
+import path from 'node:path';
+/** The `CLAUDE_CODE_OAUTH_TOKEN_<slug>` env key for a given account email/id. */
+export function accountTokenKey(account) {
+    const slug = account
+        .trim()
+        .toUpperCase()
+        .replace(/@/g, '_AT_')
+        .replace(/\./g, '_DOT_')
+        .replace(/[^A-Z0-9_]/g, '_');
+    return `CLAUDE_CODE_OAUTH_TOKEN_${slug}`;
+}
+/**
+ * Read the signed-in account email for a Claude version home from
+ * `oauthAccount.emailAddress`. Sync, no keychain, no network. Tries both stores
+ * the canonical resolver uses (agents.ts getAccountInfo): the shim-set
+ * `CLAUDE_CONFIG_DIR` location `<home>/.claude/.claude.json` first, then the
+ * home-level `<home>/.claude.json` (an account signed in via the IDE / direct
+ * binary without the shim writes there). Returns null when neither has a usable
+ * email.
+ */
+export function readClaudeAccountEmail(home) {
+    for (const p of [path.join(home, '.claude', '.claude.json'), path.join(home, '.claude.json')]) {
+        try {
+            const email = JSON.parse(fs.readFileSync(p, 'utf-8')).oauthAccount?.emailAddress;
+            if (typeof email === 'string' && email.trim().length > 0)
+                return email.trim();
+        }
+        catch {
+            // Missing/unreadable/malformed at this location — try the next.
+        }
+    }
+    return null;
+}
+/**
+ * Resolve the per-account setup-token for the account pinned to `home`, looking
+ * it up in the provided env (the daemon injects the `claude` bundle's
+ * `CLAUDE_CODE_OAUTH_TOKEN_*` keys). Returns null when the home has no known
+ * account, or no matching per-account token is present — callers then leave the
+ * existing ambient/interactive credential untouched (a safe no-op).
+ */
+export function resolveAccountSetupToken(env, home) {
+    const email = readClaudeAccountEmail(home);
+    if (!email)
+        return null;
+    const token = env[accountTokenKey(email)];
+    return typeof token === 'string' && token.trim().length > 0 ? token.trim() : null;
+}

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

@@ -69,12 +69,14 @@ export interface StoredBundle {
     env: Record<string, string>;
     /** epoch ms; the entry is gone once Date.now() passes this. */
     expiresAt: number;
+    harness: string;
 }
 /** One unlocked bundle as reported by `status`. */
 export interface AgentStatusEntry {
     name: string;
     expiresAt: number;
     keyCount: number;
+    harness: string;
 }
 /**
  * Read the current broker capability token, or null if none is present. Clients
@@ -106,10 +108,12 @@ export type Request = {
 } | {
     cmd: 'get';
     name: string;
+    harness?: string;
     token?: string;
 } | {
     cmd: 'load';
     name: string;
+    harness?: string;
     bundle: SecretsBundle;
     env: Record<string, string>;
     ttlMs: number;
@@ -166,6 +170,7 @@ export type Response = {
  * exiting. Pure + exported for unit testing.
  */
 export declare function realBundleCount(store: Map<string, StoredBundle>): number;
+export declare function scopedBundleKey(name: string, harness: string): string;
 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.
@@ -270,7 +275,7 @@ export declare function syncClientLaunch(sub: string[], agentsBin?: string): {
  * null if the agent isn't running / doesn't hold this bundle / anything fails
  * (soft — caller falls through to the real keychain). macOS only.
  */
-export declare function agentGetSync(name: string): {
+export declare function agentGetSync(name: string, harness?: string): {
     bundle: SecretsBundle;
     env: Record<string, string>;
 } | null;
@@ -308,7 +313,7 @@ export declare function agentReachableSync(): boolean;
 export declare function agentEvictSync(name: string): void;
 /** Body of `__secrets-get <name>`. Prints `{bundle, env}` as JSON on a
  * cache hit. Exit 0 = hit, 3 = miss or broker down. */
-export declare function runAgentGetSync(name: string): Promise<number>;
+export declare function runAgentGetSync(name: string, harness?: string): Promise<number>;
 /** Body of `__secrets-ping`. Exit 0 = a broker is listening and speaking
  * our protocol, 3 = nothing there. Deliberately does NOT gate on
  * PROTOCOL_VERSION: this only decides whether the auto-cache may take the
@@ -387,7 +392,7 @@ export declare function clampHoldMs(v: unknown): number;
  * The worker reuses the robust `ensureAgentRunning` path (spawn-then-ping) rather
  * than a tight inline retry loop. Best-effort; never throws. macOS only.
  */
-export declare function agentAutoLoadSync(name: string, bundle: SecretsBundle, env: Record<string, string>, ttlMs: number): void;
+export declare function agentAutoLoadSync(name: string, bundle: SecretsBundle, env: Record<string, string>, ttlMs: number, harness?: string): void;
 /**
  * Body of the hidden `secrets _agent-load` worker. Reads one `{name, bundle,
  * env, ttlMs}` payload from stdin, ensures the broker is up (robust, generous
@@ -402,7 +407,7 @@ export declare function agentAutoLoadSync(name: string, bundle: SecretsBundle, e
  */
 export declare function runAgentLoadFromStdin(): Promise<void>;
 /** Store a resolved bundle in the broker. Returns false on transport failure. */
-export declare function agentLoad(name: string, bundle: SecretsBundle, env: Record<string, string>, ttlMs: number): Promise<boolean>;
+export declare function agentLoad(name: string, bundle: SecretsBundle, env: Record<string, string>, ttlMs: number, harness?: string): Promise<boolean>;
 /** Wipe one bundle (or all if name omitted) from the broker. Returns the count
  * wiped, or 0 when no broker is running. */
 export declare function agentLock(name?: string): Promise<number>;

package/dist/lib/secrets/agent.js

@@ -38,7 +38,7 @@ import { rehydrateSessions, pruneSessionsOnSleep } from './session-store.js';
 import { SYNC_GET_CMD, SYNC_PING_CMD, SYNC_LOCK_CMD } from './sync-commands.js';
 /** Bumped when the wire protocol changes; a client that pings a mismatched
  * server kills and respawns it rather than talking a stale dialect. */
-const PROTOCOL_VERSION = 1;
+const PROTOCOL_VERSION = 2;
 /** Default lifetime of an unlocked bundle when `--ttl` is not given. */
 export const DEFAULT_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7d
 /**
@@ -133,7 +133,8 @@ function onDarwin() {
 function rehydrateStore(now = Date.now()) {
     const store = new Map();
     for (const { name, entry } of rehydrateSessions(now)) {
-        store.set(name, { bundle: entry.bundle, env: entry.env, expiresAt: entry.expiresAt });
+        const harness = entry.harness || 'cli';
+        store.set(scopedBundleKey(name, harness), { bundle: entry.bundle, env: entry.env, expiresAt: entry.expiresAt, harness });
     }
     return store;
 }
@@ -291,11 +292,14 @@ export async function uninstallSecretsAgentService() {
  */
 export function realBundleCount(store) {
     let n = 0;
-    for (const name of store.keys())
-        if (!name.startsWith(META_CACHE_PREFIX))
+    for (const e of store.values())
+        if (!e.bundle.name.startsWith(META_CACHE_PREFIX))
             n++;
     return n;
 }
+export function scopedBundleKey(name, harness) {
+    return `${harness}:${name}`;
+}
 export function handleAgentRequest(store, req, now = Date.now()) {
     switch (req.cmd) {
         case 'ping':
@@ -305,20 +309,26 @@ export function handleAgentRequest(store, req, now = Date.now()) {
             // the broker is running pre-upgrade code and should be restarted.
             return { ok: true, cmd: 'ping', version: PROTOCOL_VERSION, cliVersion: getCliVersion() };
         case 'get': {
-            const e = store.get(req.name);
+            const key = scopedBundleKey(req.name, req.harness || 'cli');
+            const e = store.get(key);
             if (!e || now >= e.expiresAt) {
                 if (e)
-                    store.delete(req.name); // drop expired on read
+                    store.delete(key); // drop expired on read
                 return { ok: true, cmd: 'get', hit: false };
             }
             return { ok: true, cmd: 'get', hit: true, bundle: e.bundle, env: e.env };
         }
         case 'load':
-            store.set(req.name, { bundle: req.bundle, env: req.env, expiresAt: now + req.ttlMs });
+            const harness = req.harness || 'cli';
+            store.set(scopedBundleKey(req.name, harness), { bundle: req.bundle, env: req.env, expiresAt: now + req.ttlMs, harness });
             return { ok: true, cmd: 'load' };
         case 'lock': {
             if (req.name) {
-                return { ok: true, cmd: 'lock', wiped: store.delete(req.name) ? 1 : 0 };
+                let wiped = 0;
+                for (const [key, entry] of store)
+                    if (entry.bundle.name === req.name && store.delete(key))
+                        wiped++;
+                return { ok: true, cmd: 'lock', wiped };
             }
             const wiped = store.size;
             store.clear();
@@ -329,9 +339,9 @@ export function handleAgentRequest(store, req, now = Date.now()) {
             for (const [name, e] of store) {
                 if (now >= e.expiresAt)
                     continue;
-                if (name.startsWith(META_CACHE_PREFIX))
-                    continue; // internal list cache, not a user bundle
-                entries.push({ name, expiresAt: e.expiresAt, keyCount: Object.keys(e.env).length });
+                if (e.bundle.name.startsWith(META_CACHE_PREFIX))
+                    continue; // internal list cache
+                entries.push({ name: e.bundle.name, expiresAt: e.expiresAt, keyCount: Object.keys(e.env).length, harness: e.harness });
             }
             return { ok: true, cmd: 'status', entries };
         }
@@ -824,10 +834,10 @@ function syncClient(sub, timeout) {
  * null if the agent isn't running / doesn't hold this bundle / anything fails
  * (soft — caller falls through to the real keychain). macOS only.
  */
-export function agentGetSync(name) {
+export function agentGetSync(name, harness = 'cli') {
     if (!agentSocketExists())
         return null;
-    const r = syncClient([SYNC_GET_CMD, name], SYNC_GET_TIMEOUT_MS);
+    const r = syncClient([SYNC_GET_CMD, name, harness], SYNC_GET_TIMEOUT_MS);
     if (!r || r.status !== 0 || !r.stdout)
         return null;
     try {
@@ -904,8 +914,8 @@ export function agentEvictSync(name) {
 // so a cache hit never runs checkForUpdates() or forks a detached sync.
 /** Body of `__secrets-get <name>`. Prints `{bundle, env}` as JSON on a
  * cache hit. Exit 0 = hit, 3 = miss or broker down. */
-export async function runAgentGetSync(name) {
-    const r = await request({ cmd: 'get', name }, SOCKET_GET_TIMEOUT_MS);
+export async function runAgentGetSync(name, harness = 'cli') {
+    const r = await request({ cmd: 'get', name, harness }, SOCKET_GET_TIMEOUT_MS);
     if (r?.ok === true && r.cmd === 'get' && r.hit) {
         // Trailing newline: the parent reads the LAST line (see lastLine), so the
         // payload must terminate the stream even if anything ever precedes it.
@@ -1056,10 +1066,10 @@ export function clampHoldMs(v) {
  * The worker reuses the robust `ensureAgentRunning` path (spawn-then-ping) rather
  * than a tight inline retry loop. Best-effort; never throws. macOS only.
  */
-export function agentAutoLoadSync(name, bundle, env, ttlMs) {
+export function agentAutoLoadSync(name, bundle, env, ttlMs, harness = 'cli') {
     if (!onDarwin())
         return;
-    const payload = JSON.stringify({ name, bundle, env, ttlMs });
+    const payload = JSON.stringify({ name, bundle, env, ttlMs, harness });
     // Broker actually LISTENING → deterministic synchronous warm (bounded; the read
     // already paid a Touch ID, so <1s here is invisible). We gate on a real liveness
     // ping, NOT mere socket-file existence: a broker that died leaving its socket
@@ -1126,13 +1136,13 @@ export async function runAgentLoadFromStdin() {
         process.exitCode = 1; // broker couldn't be brought up — did NOT load
         return;
     }
-    const loaded = await agentLoad(payload.name, payload.bundle, payload.env, payload.ttlMs ?? DEFAULT_TTL_MS);
+    const loaded = await agentLoad(payload.name, payload.bundle, payload.env, payload.ttlMs ?? DEFAULT_TTL_MS, payload.harness ?? 'cli');
     if (!loaded)
         process.exitCode = 1; // transport failed — did NOT load
 }
 /** Store a resolved bundle in the broker. Returns false on transport failure. */
-export async function agentLoad(name, bundle, env, ttlMs) {
-    const r = await request({ cmd: 'load', name, bundle, env, ttlMs });
+export async function agentLoad(name, bundle, env, ttlMs, harness = 'cli') {
+    const r = await request({ cmd: 'load', name, bundle, env, ttlMs, harness });
     return r?.ok === true && r.cmd === 'load';
 }
 /** Wipe one bundle (or all if name omitted) from the broker. Returns the count

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

@@ -198,6 +198,12 @@ export interface ResolveBundleOptions {
      * about to read the bundle.
      */
     caller?: string;
+    /** Harness type whose unlock may be reused (claude, codex, kimi, ...). */
+    agent?: string;
+    /** Human duration rendered in the Touch ID prompt. */
+    duration?: string;
+    /** Explicitly permit this agent request to raise interactive authentication. */
+    interactiveUnlock?: boolean;
     /**
      * Skip the secrets-agent fast-path and read straight from the keychain
      * (popping Touch ID). Set by callers that must NOT serve a cached snapshot —
@@ -272,15 +278,19 @@ export declare function resolveBundleEnv(bundle: SecretsBundle, _opts?: ResolveB
  * True when the current process is a background / non-interactive context that
  * must NEVER raise a Keychain biometry prompt on the interactive user's screen —
  * a prompt nobody is watching. Two signals, either sufficient:
- *   - `AGENTS_RUNTIME` is `headless` or `teams` (set on the child env by
- *     `agents run --headless`, scheduled routines, and teammates — see
- *     exec.ts:resolveInteractive, runner.ts, teams/agents.ts).
+ *   - `AGENTS_RUNTIME` is `headless`, `teams`, or `terminal` — i.e. ANY agent
+ *     launch, interactive included, and inherited by everything spawned beneath
+ *     one (set on the child env by `agents run --headless`, scheduled routines,
+ *     teammates, and interactive runs — see exec.ts:430, runner.ts,
+ *     teams/agents.ts).
  *   - neither stdin nor stdout is a TTY (a detached/backgrounded task whose
  *     stdio is redirected to a log — e.g. a release script run in the
  *     background as `( ... ) >log 2>&1 </dev/null`).
  * `AGENTS_SECRETS_NO_PROMPT=1` forces headless-safe; `=0` force-allows a prompt
- * even in a non-TTY context. An interactive `eval "$(agents secrets export X)"`
- * keeps its terminal stdin, so it is NOT classified headless and still prompts.
+ * even in a non-TTY context. An `eval "$(agents secrets export X)"` typed in a
+ * PLAIN shell has no AGENTS_RUNTIME, so it is not classified headless and still
+ * prompts. Run beneath an agent it inherits AGENTS_RUNTIME and resolves
+ * broker-only — the agent, not the human, is the caller there.
  *
  * Only **macOS keychain** reads pop an interactive Touch ID sheet — the secrets
  * broker itself is a no-op off darwin (see agent.ts), and libsecret (Linux) /
@@ -293,7 +303,10 @@ export declare function resolveBundleEnv(bundle: SecretsBundle, _opts?: ResolveB
  * fast with an actionable error instead of hijacking Touch ID. This generalizes
  * the per-caller pattern already used by the daemon (daemon.ts:readDaemonClaudeOAuthToken).
  */
-export declare function isHeadlessSecretsContext(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+export declare function isHeadlessSecretsContext(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, tty?: {
+    stdin?: boolean;
+    stdout?: boolean;
+}): boolean;
 /**
  * Read a bundle's metadata AND resolve its env in a single Touch ID prompt.
  *
@@ -311,6 +324,7 @@ export declare function readAndResolveBundleEnv(name: string, opts?: ResolveBund
     bundle: SecretsBundle;
     env: Record<string, string>;
 };
+export declare function humanUnlockDuration(ms: number): string;
 export declare function keychainRef(key: string): string;
 /** Options for rotateBundleSecret. */
 export interface RotateOptions {