@phnx-labs/agents-cli 1.20.77 → 1.20.82

package/dist/lib/runner.js

@@ -23,13 +23,12 @@ import { prepareJobHome, buildSpawnEnv, getJobHomePath } from './sandbox.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
 import { createTimer, maybeRotate, redactPrompt } from './events.js';
 import { normalizeMode, resolveHeadlessMode, buildExecEnv, detectRateLimit, detectAuthFailure, isAuthFailureFromLog, authFailureReason, } from './exec.js';
+import { resolveActor } from './actor.js';
 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 { resolveAccountSetupToken } from './secrets/account-token.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';
@@ -400,29 +399,22 @@ export function buildRoutineSpawnEnv(baseEnv, agent, version, timezone) {
         if (v !== undefined)
             out[k] = v;
     }
-    // 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).
+    // A routine authenticates through the pinned account's own CLAUDE_CONFIG_DIR
+    // login on THIS box (buildExecEnv points it at the per-account version home).
+    // 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.
     //
-    // 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;
-        }
-    }
+    // Injecting a token was already ruled out, but INHERITING one was not:
+    // buildExecEnv spreads the ambient process.env (exec.ts) and sanitizeProcessEnv
+    // only strips loader/interpreter vars, never credentials. So on any box whose
+    // daemon environment happens to carry CLAUDE_CODE_OAUTH_TOKEN, every routine
+    // spawn silently ran on that one shared rotating token instead of the host's
+    // own login — the exact fleet-wide-logout path, arriving by inheritance rather
+    // than injection. CI never caught it because CI has no token to inherit; a
+    // provisioned box does. Drop it here so a routine always uses the login of the
+    // machine it runs on.
+    delete out.CLAUDE_CODE_OAUTH_TOKEN;
     if (timezone)
         out.TZ = timezone;
     return out;
@@ -518,6 +510,28 @@ function spawnJobAttempt(cmd, env, attemptLogPath, timeoutMs, combinedLogPath) {
  * Single-shot path: pre-flight version/account selection + mid-run rate-limit
  * failover across healthy same-agent accounts (RUSH-1016).
  */
+/**
+ * Actor provenance for a routine run (RUSH-2020): `actor` is the routine's
+ * CREATOR (carried from the job config), `triggeredBy` is whoever kicked off THIS
+ * run (`resolveActor().id` — a person for a manual run, `UNRESOLVED@<host>` for an
+ * unattended scheduled fire). Spread into every RunMeta so a fired cron traces
+ * back to the person who scheduled it.
+ */
+function runProvenance(config) {
+    return { ...(config.actor ? { actor: config.actor } : {}), triggeredBy: resolveActor().id };
+}
+/**
+ * Inject the routine creator's actor into a run's base env so the fired agent
+ * INHERITS it (the `AGENTS_ACTOR` path in actor.ts) instead of re-resolving to
+ * `UNRESOLVED@<host>` on an unattended fire — so its session, events, and commits
+ * all attribute to the person who scheduled the routine (RUSH-2020). Mutates and
+ * returns the same env object for call-site brevity.
+ */
+function injectRoutineActor(env, config) {
+    if (config.actor && !env.AGENTS_ACTOR)
+        env.AGENTS_ACTOR = config.actor;
+    return env;
+}
 export async function executeJob(config, deps) {
     const eligibility = checkJobDeviceEligibility(config);
     if (eligibility) {
@@ -564,9 +578,9 @@ export async function executeJob(config, deps) {
     const runId = generateRunId();
     const runDir = getRunDir(config.name, runId);
     fs.mkdirSync(runDir, { recursive: true });
-    const baseEnv = useSandbox
+    const baseEnv = injectRoutineActor(useSandbox
         ? buildSpawnEnv(overlayHome)
-        : { ...process.env };
+        : { ...process.env }, config);
     // Workflows run via `agents run <workflow>` which delegates to claude under the hood.
     // Use 'claude' as the effective agent for report extraction and metadata when workflow is set.
     // (command jobs branched out earlier, so config.agent is set on the non-workflow path.)
@@ -574,6 +588,7 @@ export async function executeJob(config, deps) {
     const meta = {
         jobName: config.name,
         runId,
+        ...runProvenance(config),
         agent: effectiveAgent,
         ...(config.workflow ? { workflow: config.workflow } : {}),
         pid: null,
@@ -789,6 +804,7 @@ async function executeJobOnCloud(config, opts) {
     const meta = {
         jobName: config.name,
         runId,
+        ...runProvenance(config),
         agent: config.agent,
         pid: null,
         spawnedAt: Date.now(),
@@ -860,6 +876,7 @@ async function executeJobOnHost(config, opts) {
     const meta = {
         jobName: config.name,
         runId,
+        ...runProvenance(config),
         agent: config.agent,
         pid: null, // no local process — the run lives on the host
         spawnedAt: Date.now(),
@@ -907,6 +924,7 @@ async function executeCommandJobForeground(config) {
     const meta = {
         jobName: config.name,
         runId,
+        ...runProvenance(config),
         command: config.command,
         pid: null,
         spawnedAt: Date.now(),
@@ -1038,9 +1056,9 @@ export async function executeJobDetached(config, hooks) {
     fs.mkdirSync(runDir, { recursive: true });
     const stdoutPath = path.join(runDir, 'stdout.log');
     const stdoutFd = fs.openSync(stdoutPath, 'w', 0o600);
-    const baseEnv = useSandbox
+    const baseEnv = injectRoutineActor(useSandbox
         ? buildSpawnEnv(overlayHome)
-        : { ...process.env };
+        : { ...process.env }, config);
     const spawnEnv = dispatchesViaAgentsRun(config)
         ? (() => {
             const e = { ...baseEnv };
@@ -1054,6 +1072,7 @@ export async function executeJobDetached(config, hooks) {
     const meta = {
         jobName: config.name,
         runId,
+        ...runProvenance(config),
         agent: effectiveAgent,
         ...(config.workflow ? { workflow: config.workflow } : {}),
         pid: null,
@@ -1063,6 +1082,28 @@ export async function executeJobDetached(config, hooks) {
         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 }),
@@ -1152,6 +1193,7 @@ function executeCommandJobDetached(config, hooks) {
     const meta = {
         jobName: config.name,
         runId,
+        ...runProvenance(config),
         command: config.command,
         pid: null,
         spawnedAt: Date.now(),

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 = {
@@ -75,16 +69,6 @@ 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/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;
 /**
@@ -204,6 +206,22 @@ type BrokerConnectionHandler = (conn: net.Socket) => void;
  * rotation on broker restart is picked up without rebuilding the handler.
  */
 export declare function makeConnectionHandler(handle: (req: Request) => Response, token: () => string | null): BrokerConnectionHandler;
+/**
+ * Whether a live process still owns the broker pid file.
+ *
+ * A single missed `agentPing` is NOT proof the owner is dead — the broker is
+ * single-threaded, so a big `get` or the rehydrate at startup can blow the
+ * 700ms ping budget while the process is perfectly healthy. Treating that as
+ * death let a starting broker unlink a live socket and rebind, leaving the old
+ * process alive holding every unlocked bundle in RAM that no client could reach
+ * any more (observed live: two brokers, one socket path, two kernel sockets).
+ * The pid file is the second, independent liveness signal that makes the reclaim
+ * safe.
+ */
+/** Drop our ownership record, but only if it is still ours — never clobber a
+ *  successor that already claimed the socket. */
+export declare function releaseBrokerPid(): void;
+export declare function brokerPidAlive(): boolean;
 /**
  * Run the broker in the foreground. Spawned detached by ensureAgentRunning via
  * `agents secrets _agent-run`. Holds the store in memory, serves the socket,

package/dist/lib/secrets/agent.js

@@ -30,12 +30,18 @@ import * as path from 'path';
 import { randomBytes } from 'crypto';
 import { spawn, spawnSync, execFileSync } from 'child_process';
 import { getHelpersDir, readMeta } from '../state.js';
-import { isAlive } from '../platform/process.js';
+import { isAlive, waitForExit } 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 = 2;
@@ -59,6 +65,19 @@ export const META_CACHE_PREFIX = '!meta:';
 const IDLE_EXIT_MS = 5 * 60 * 1000; // 5m
 /** How often the broker sweeps expired entries. */
 const SWEEP_INTERVAL_MS = 30 * 1000;
+/** How many times a starting broker probes an in-use socket before treating its
+ * owner as gone. One probe is not enough: the broker is single-threaded, so a
+ * large read or the startup rehydrate can outlast a single ping budget while the
+ * process is healthy. */
+const BIND_PROBE_ATTEMPTS = 3;
+/** How long a broker teardown waits for the old process to actually exit before
+ * clearing its socket + ownership record. */
+const BROKER_STOP_GRACE_MS = 3000;
+/** Pause between those probes. */
+const BIND_PROBE_INTERVAL_MS = 250;
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 /**
  * Timeouts for the three synchronous broker clients, split across the process
  * boundary they now straddle.
@@ -133,7 +152,7 @@ function onDarwin() {
 function rehydrateStore(now = Date.now()) {
     const store = new Map();
     for (const { name, entry } of rehydrateSessions(now)) {
-        const harness = entry.harness || 'cli';
+        const harness = entry.harness || GLOBAL_HARNESS;
         store.set(scopedBundleKey(name, harness), { bundle: entry.bundle, env: entry.env, expiresAt: entry.expiresAt, harness });
     }
     return store;
@@ -164,6 +183,20 @@ function pidPath() {
 function tokenPath() {
     return path.join(agentDir(), 'agent.token');
 }
+/**
+ * Path of the CURRENT SOCKET OWNER's pid.
+ *
+ * Deliberately NOT `agent.pid`: that file is the standalone service's O_EXCL
+ * single-instance claim, and a standalone that loses the socket race stays alive
+ * and quiescent while holding it (so launchd's KeepAlive doesn't restart-loop
+ * it), ready to take over if the hosted broker stops. Overloading it as the
+ * socket-ownership record made the standalone see a live holder and exit
+ * immediately — the exact restart loop that guard exists to prevent. This file
+ * answers a different question: which pid is serving the socket right now.
+ */
+function ownerPath() {
+    return path.join(agentDir(), 'agent.owner');
+}
 /**
  * Read the current broker capability token, or null if none is present. Clients
  * read it fresh per request and attach it to every non-ping command; a broker
@@ -309,17 +342,23 @@ 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 key = scopedBundleKey(req.name, req.harness || 'cli');
-            const e = store.get(key);
-            if (!e || now >= e.expiresAt) {
-                if (e)
-                    store.delete(key); // 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':
-            const harness = req.harness || 'cli';
+            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': {
@@ -413,11 +452,45 @@ export function makeConnectionHandler(handle, token) {
         conn.on('error', () => { });
     };
 }
+/**
+ * Whether a live process still owns the broker pid file.
+ *
+ * A single missed `agentPing` is NOT proof the owner is dead — the broker is
+ * single-threaded, so a big `get` or the rehydrate at startup can blow the
+ * 700ms ping budget while the process is perfectly healthy. Treating that as
+ * death let a starting broker unlink a live socket and rebind, leaving the old
+ * process alive holding every unlocked bundle in RAM that no client could reach
+ * any more (observed live: two brokers, one socket path, two kernel sockets).
+ * The pid file is the second, independent liveness signal that makes the reclaim
+ * safe.
+ */
+/** Drop our ownership record, but only if it is still ours — never clobber a
+ *  successor that already claimed the socket. */
+export function releaseBrokerPid() {
+    try {
+        if (parseInt(fs.readFileSync(ownerPath(), 'utf-8').trim(), 10) === process.pid) {
+            fs.unlinkSync(ownerPath());
+        }
+    }
+    catch { /* absent or unreadable — nothing to release */ }
+}
+export function brokerPidAlive() {
+    try {
+        const holder = parseInt(fs.readFileSync(ownerPath(), 'utf-8').trim(), 10);
+        return !isNaN(holder) && holder !== process.pid && isAlive(holder);
+    }
+    catch {
+        return false; // no pid file → nothing claims ownership
+    }
+}
 /**
  * Bind the shared broker socket without stealing it from another live owner.
  * Both the standalone service and daemon-hosted broker use this single path so
  * either startup order is safe: a reachable owner wins, while an unreachable
  * stale socket is reclaimed once.
+ *
+ * "Unreachable" is established with retries plus a pid-file liveness check, never
+ * a single ping — see {@link brokerPidAlive}.
  */
 async function bindBrokerSocket(sock, onConnection) {
     const listenOnce = () => new Promise((resolve, reject) => {
@@ -441,14 +514,38 @@ async function bindBrokerSocket(sock, onConnection) {
                 writeAgentToken();
             }
             catch { /* dir 0700 gates the socket regardless */ }
+            // Record ownership at the same moment, for the same reason. The
+            // daemon-hosted broker deliberately skips the O_EXCL pid-file GUARD (the
+            // daemon owns its instance), but without an ownership RECORD
+            // brokerPidAlive() has nothing to read — so a later starter saw an
+            // ownerless socket and reclaimed the live hosted broker anyway, which is
+            // the primary configuration and the one that actually orphaned here.
+            // Writing it from the confirmed owner covers both broker flavours.
+            try {
+                fs.writeFileSync(ownerPath(), String(process.pid));
+            }
+            catch { /* dir 0700 gates it */ }
             resolve(server);
         });
     });
     let bound = await listenOnce();
     if (bound !== 'inuse')
         return bound;
-    if ((await agentPing()).reachable)
-        return null;
+    // Give a busy owner several chances before concluding it is gone. One slow
+    // ping used to be enough to evict a healthy broker and orphan its RAM.
+    for (let attempt = 0; attempt < BIND_PROBE_ATTEMPTS; attempt++) {
+        if ((await agentPing()).reachable)
+            return null;
+        if (attempt < BIND_PROBE_ATTEMPTS - 1)
+            await delay(BIND_PROBE_INTERVAL_MS);
+    }
+    // Silent but alive is still alive: refuse to steal the socket from a process
+    // that still owns the pid file, and let the caller surface the wedge instead
+    // of quietly starting a second broker on the same path.
+    if (brokerPidAlive()) {
+        throw new Error(`Secrets broker socket is held by a live process that is not answering: ${sock}. ` +
+            `Run 'agents secrets lock --all' then retry, or stop the stuck broker.`);
+    }
     try {
         fs.unlinkSync(sock);
     }
@@ -625,6 +722,7 @@ export async function runSecretsAgent(opts = {}) {
             fs.unlinkSync(sock);
         }
         catch { /* gone */ }
+        releaseBrokerPid();
         releasePid();
     };
     sweepTimer = setInterval(sweep, SWEEP_INTERVAL_MS);
@@ -734,6 +832,7 @@ export async function startHostedBroker() {
                 fs.unlinkSync(sock);
             }
             catch { /* gone */ }
+            releaseBrokerPid();
         },
     };
 }
@@ -834,7 +933,7 @@ 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, harness = 'cli') {
+export function agentGetSync(name, harness = GLOBAL_HARNESS) {
     if (!agentSocketExists())
         return null;
     const r = syncClient([SYNC_GET_CMD, name, harness], SYNC_GET_TIMEOUT_MS);
@@ -914,7 +1013,7 @@ 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, harness = 'cli') {
+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
@@ -1066,7 +1165,7 @@ 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, harness = 'cli') {
+export function agentAutoLoadSync(name, bundle, env, ttlMs, harness = GLOBAL_HARNESS) {
     if (!onDarwin())
         return;
     const payload = JSON.stringify({ name, bundle, env, ttlMs, harness });
@@ -1136,12 +1235,12 @@ 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, payload.harness ?? 'cli');
+    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, harness = 'cli') {
+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';
 }
@@ -1236,6 +1335,12 @@ export async function ensureAgentRunning(timeoutMs = 5000) {
             process.kill(stalePid, 'SIGTERM');
         }
         catch { /* already dead */ }
+        // Wait for it to actually go before clearing its socket and ownership
+        // record. Unlinking them under a live broker is what leaves an orphan
+        // holding every unlocked bundle in RAM with no way to reach it — and it also
+        // destroys the very record brokerPidAlive() reads, so the successor sees an
+        // ownerless socket and reclaims it regardless.
+        waitForExit(stalePid, BROKER_STOP_GRACE_MS);
     }
     try {
         fs.unlinkSync(socketPath());
@@ -1245,6 +1350,10 @@ export async function ensureAgentRunning(timeoutMs = 5000) {
         fs.unlinkSync(pidPath());
     }
     catch { /* gone */ }
+    try {
+        fs.unlinkSync(ownerPath());
+    }
+    catch { /* gone */ }
     const { cmd, args } = brokerSpawn();
     spawn(cmd, args, { stdio: 'ignore', detached: true }).unref();
     const deadline = Date.now() + timeoutMs;
@@ -1274,6 +1383,7 @@ async function teardownStaleBroker() {
             process.kill(pid, 'SIGTERM');
         }
         catch { /* gone */ }
+        waitForExit(pid, BROKER_STOP_GRACE_MS); // same reason as ensureAgentRunning
     }
     try {
         fs.unlinkSync(socketPath());
@@ -1283,4 +1393,8 @@ async function teardownStaleBroker() {
         fs.unlinkSync(pidPath());
     }
     catch { /* gone */ }
+    try {
+        fs.unlinkSync(ownerPath());
+    }
+    catch { /* gone */ }
 }

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

@@ -0,0 +1,46 @@
+export type SecretAuditEvent = 'secrets.get' | 'secrets.unlocked';
+export interface SecretAuditParams {
+    /** Which audit event this is — a read (`secrets.get`) or an unlock grant. */
+    event: SecretAuditEvent;
+    /** Bundle name (never a value). */
+    bundle?: string;
+    /** Raw keychain item/service name for `secrets get <item>` (never a value). */
+    item?: string;
+    /** Free-form operation/caller label, e.g. 'export to shell', 'unlock'. */
+    operation?: string;
+    /**
+     * Where the read/grant originated: agent | session | reveal | raw-item |
+     * remote | sync-push | broker | broker+durable.
+     */
+    source?: string;
+    status?: 'success' | 'error';
+    /** Env/key NAMES exposed — names only, never values. */
+    keys?: string[];
+    keyCount?: number;
+    /** Subset of `keys` backed by the OS keychain — names only. */
+    keychainKeys?: string[];
+    /** Count of resolved values by kind (literal / keychain / env / ...). */
+    kindCounts?: Record<string, number>;
+    /**
+     * Resolving agent/harness identity the access was scoped to (`*` = a global
+     * grant readable by every harness). Falls back to `$AGENTS_AGENT_NAME`.
+     */
+    agent?: string;
+    /** Remote host the value was pulled from, when applicable. */
+    host?: string;
+    /** Grant lifetime in ms (`secrets.unlocked` only). */
+    ttlMs?: number;
+    error?: string;
+}
+/**
+ * The agent/harness identity to attribute a secret access to. Explicit callers
+ * (the bundle reader knows the scope it resolved under) win; otherwise fall back
+ * to the ambient `$AGENTS_AGENT_NAME` set on every agent launch.
+ */
+export declare function resolveAuditAgent(explicit?: string): string | undefined;
+/**
+ * Emit one value-free secret audit event to the raw/operational event stream and
+ * the persisted audit log. Only ever pass metadata — the secret value must never
+ * reach this function.
+ */
+export declare function emitSecretAudit(p: SecretAuditParams): void;