@phnx-labs/agents-cli 1.20.76 → 1.20.78

package/dist/lib/runner.js

@@ -27,8 +27,7 @@ import { loadTask as loadHostTask } from './hosts/tasks.js';
 import { reconcileTask as reconcileHostTask } from './hosts/reconcile.js';
 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 { getBinaryPath, isVersionInstalled, resolveVersion } from './versions.js';
 import { getConfiguredRunStrategy, resolveRunVersion, resolveAccountVersion, rotationFailoverChain, readinessFromCandidate, } from './rotate.js';
 import { readAuthHealth, isDeadVerdict } from './auth-health.js';
 import { machineId } from './machine-id.js';
@@ -399,19 +398,12 @@ 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;
-    }
+    // No Claude token is injected here. A routine authenticates through the pinned
+    // account's own CLAUDE_CONFIG_DIR login (buildExecEnv points it at the
+    // per-account version home), identical to interactive `agents run`. Claude
+    // Code's interactive session refreshes itself per-device; keeping the daemon
+    // out of the credential entirely is what avoids the fleet-wide rotation logout
+    // — a shared/rotating token was the cause, not the fix.
     if (timezone)
         out.TZ = timezone;
     return out;
@@ -512,11 +504,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 +735,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 +957,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
@@ -944,6 +1044,28 @@ export async function executeJobDetached(config) {
         completedAt: null,
         exitCode: null,
     };
+    // Auth preflight (mirrors executeJob): with no injected token, a daemon-fired
+    // Claude routine authenticates via the pinned account's own CLAUDE_CONFIG_DIR
+    // login. If the last live probe rejected that (agent, version)'s token, the run
+    // is guaranteed to 401 — fail fast with a re-login hint instead of spawning a
+    // doomed run + poisoned report. Cache-only; fails OPEN on any non-dead/missing
+    // verdict, and agents with no live probe (codex/gemini/grok) are never blocked.
+    const preflightVersion = launch.chain[0]?.version;
+    if (preflightVersion) {
+        const health = readAuthHealth(machineId(), effectiveAgent, preflightVersion);
+        if (health && isDeadVerdict(health.verdict)) {
+            const reason = `auth_preflight: ${health.verdict}`;
+            process.stderr.write(`[agents] routine ${config.name}: ${effectiveAgent}@${preflightVersion} token ${health.verdict} — skipping run (re-login required)\n`);
+            try {
+                fs.closeSync(stdoutFd);
+            }
+            catch { /* already closed */ }
+            finalizeRunMeta(meta, 'failed', 1, { errorMessage: reason });
+            writeRunMeta(meta);
+            archiveRoutineTranscripts(meta, runDir, overlayHome);
+            return meta;
+        }
+    }
     const child = spawn(cmd[0], cmd.slice(1), {
         stdio: ['ignore', stdoutFd, stdoutFd],
         ...backgroundSpawnOptions({ fdStdio: true }),
@@ -962,6 +1084,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 +1133,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 +1178,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

@@ -44,12 +44,6 @@ const ENV_ALLOWLIST = [
     'VISUAL',
     'NO_COLOR',
     'FORCE_COLOR',
-    // Headless Claude auth: the routines daemon injects CLAUDE_CODE_OAUTH_TOKEN
-    // from the `claude` secrets bundle (see daemon.ts). Without this allowlist
-    // entry, sandboxed routine spawns drop the token and look "unconfigured".
-    // Intentionally NOT ANTHROPIC_API_KEY / other provider secrets — those stay
-    // stripped (see tests/sandbox.test.ts "does not include sensitive env vars").
-    'CLAUDE_CODE_OAUTH_TOKEN',
 ];
 /** Tools safe to grant as wildcards (no filesystem access). */
 const SAFE_TOOLS = {

package/dist/lib/secrets/Agents CLI.app/Contents/Info.plist

@@ -8,6 +8,8 @@
   <string>Agents CLI</string>
   <key>CFBundleDisplayName</key>
   <string>Agents CLI</string>
+  <key>CFBundleIconFile</key>
+  <string>AppIcon</string>
   <key>CFBundleExecutable</key>
   <string>Agents CLI</string>
   <key>CFBundlePackageType</key>

package/dist/lib/secrets/Agents CLI.app/Contents/_CodeSignature/CodeResources

@@ -3,9 +3,21 @@
 <plist version="1.0">
 <dict>
 	<key>files</key>
-	<dict/>
+	<dict>
+		<key>Resources/AppIcon.icns</key>
+		<data>
+		Vd5nfogg74zSRNspluv4uvDecUA=
+		</data>
+	</dict>
 	<key>files2</key>
 	<dict>
+		<key>Resources/AppIcon.icns</key>
+		<dict>
+			<key>hash2</key>
+			<data>
+			DznVe0VgYOux7+B/aiHNgGYLCvSJKzgXDTPJn2jNkNg=
+			</data>
+		</dict>
 		<key>embedded.provisionprofile</key>
 		<dict>
 			<key>hash2</key>

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

@@ -25,6 +25,8 @@
  */
 import * as net from 'net';
 import type { SecretsBundle } from './bundles.js';
+import { GLOBAL_HARNESS, bundleScopeChain } from './scope.js';
+export { GLOBAL_HARNESS, bundleScopeChain };
 /** Default lifetime of an unlocked bundle when `--ttl` is not given. */
 export declare const DEFAULT_TTL_MS: number;
 /**
@@ -69,12 +71,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 +110,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 +172,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 +277,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 +315,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 +394,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 +409,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

@@ -34,11 +34,17 @@ import { isAlive } from '../platform/process.js';
 import { getKeychainHelperPath } from './install-helper.js';
 import { getCliVersion, getCliVersionFresh } from '../version.js';
 import { getCliLaunch } from '../cli-entry.js';
+import { GLOBAL_HARNESS, bundleScopeChain } from './scope.js';
 import { rehydrateSessions, pruneSessionsOnSleep } from './session-store.js';
 import { SYNC_GET_CMD, SYNC_PING_CMD, SYNC_LOCK_CMD } from './sync-commands.js';
+// Re-exported so callers already reaching for agent.js keep one obvious home for
+// the scope vocabulary; the definitions live in the leaf module scope.ts because
+// agent.ts and session-store.ts import each other and a cyclic `const` read can
+// hit the ESM temporal dead zone at runtime.
+export { GLOBAL_HARNESS, bundleScopeChain };
 /** 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 +139,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 || GLOBAL_HARNESS;
+        store.set(scopedBundleKey(name, harness), { bundle: entry.bundle, env: entry.env, expiresAt: entry.expiresAt, harness });
     }
     return store;
 }
@@ -291,11 +298,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 +315,32 @@ 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);
-            if (!e || now >= e.expiresAt) {
-                if (e)
-                    store.delete(req.name); // drop expired on read
-                return { ok: true, cmd: 'get', hit: false };
+            // Walk own-harness → global so a `--for` grant wins over a global one and
+            // an unscoped unlock serves every harness (bundleScopeChain).
+            for (const scope of bundleScopeChain(req.harness)) {
+                const key = scopedBundleKey(req.name, scope);
+                const e = store.get(key);
+                if (!e)
+                    continue;
+                if (now >= e.expiresAt) {
+                    store.delete(key);
+                    continue;
+                } // drop expired on read
+                return { ok: true, cmd: 'get', hit: true, bundle: e.bundle, env: e.env };
             }
-            return { ok: true, cmd: 'get', hit: true, bundle: e.bundle, env: e.env };
+            return { ok: true, cmd: 'get', hit: false };
         }
         case 'load':
-            store.set(req.name, { bundle: req.bundle, env: req.env, expiresAt: now + req.ttlMs });
+            const harness = req.harness || GLOBAL_HARNESS;
+            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 +351,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 +846,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 = GLOBAL_HARNESS) {
     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 +926,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 = GLOBAL_HARNESS) {
+    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 +1078,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 = GLOBAL_HARNESS) {
     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 +1148,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 ?? GLOBAL_HARNESS);
     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 = GLOBAL_HARNESS) {
+    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) /
@@ -291,9 +301,12 @@ export declare function resolveBundleEnv(bundle: SecretsBundle, _opts?: ResolveB
  *
  * A read in a macOS headless context resolves broker-only (agentOnly) and fails
  * fast with an actionable error instead of hijacking Touch ID. This generalizes
- * the per-caller pattern already used by the daemon (daemon.ts:readDaemonClaudeOAuthToken).
+ * the per-caller broker-only pattern used across the headless secrets readers.
  */
-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 {