@phnx-labs/agents-cli 1.20.70 → 1.20.72

package/dist/lib/hosts/logs.js

@@ -54,6 +54,24 @@ export async function showHostTaskLog(id, follow, full = false) {
     process.stdout.write(full ? raw : tailLines(raw, HOST_LOG_TAIL_LINES));
     return { found: true, exitCode: 0 };
 }
+/**
+ * Machine-readable form of a host-dispatch task's log — the task record plus its
+ * combined stdout. Powers `agents logs <id> --json` for the host-task branch.
+ * Reconciles a still-'running' record from the remote `.exit` first, like the
+ * text path does.
+ */
+export function hostTaskLogJson(id) {
+    const task = loadTask(id);
+    if (!task)
+        return { found: false };
+    // reconcileTask returns the healed record; it does NOT mutate its argument in
+    // place. Emit the reconciled task so a run that finished between dispatch and
+    // this one-shot read surfaces its terminal status/exitCode, not a stale
+    // 'running'. (The text path can discard the return — it only reads the log by
+    // id — but this JSON payload carries task.status straight to the consumer.)
+    const reconciled = reconcileTask(task);
+    return { found: true, task: reconciled, log: readTaskLog(reconciled) };
+}
 /** Read the task's combined-stdout — local mirror first, else fetch+cache remote. */
 function readTaskLog(task) {
     try {

package/dist/lib/menubar/install-menubar.d.ts

@@ -26,6 +26,18 @@ export declare function menubarServiceInstalled(): boolean;
 export declare function ensureMenubarAppInstalled(opts?: {
     forceReinstall?: boolean;
 }): string | null;
+/**
+ * Restart the menu-bar launchd agent from a clean state.
+ *
+ * Always `bootout` first: on modern macOS `bootstrap` fails when the job is
+ * already bootstrapped, and the deprecated `load -w` fallback is unreliable.
+ * A prior WindowServer disconnect can leave the job throttled so that a plain
+ * `kickstart -k` does not bring it back; booting it out and bootstrapping fresh
+ * is the only sequence that reliably re-attaches the status item.
+ */
+export declare function restartMenubarLaunchAgent(uid: number, plist: string, exec?: (cmd: string, args: readonly string[], opts: {
+    stdio: ['ignore', 'ignore', 'ignore'];
+}) => Buffer): void;
 /**
  * Install + start the menu-bar helper as a launchd user service (idempotent).
  * Clears the sticky opt-out, installs the .app, writes the plist, and

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

@@ -210,6 +210,31 @@ ${envXml}
 </dict>
 </plist>`;
 }
+/**
+ * Restart the menu-bar launchd agent from a clean state.
+ *
+ * Always `bootout` first: on modern macOS `bootstrap` fails when the job is
+ * already bootstrapped, and the deprecated `load -w` fallback is unreliable.
+ * A prior WindowServer disconnect can leave the job throttled so that a plain
+ * `kickstart -k` does not bring it back; booting it out and bootstrapping fresh
+ * is the only sequence that reliably re-attaches the status item.
+ */
+export function restartMenubarLaunchAgent(uid, plist, exec = execFileSync) {
+    const serviceTarget = `gui/${uid}/${SERVICE_LABEL}`;
+    const opts = { stdio: ['ignore', 'ignore', 'ignore'] };
+    try {
+        exec('launchctl', ['bootout', serviceTarget], opts);
+    }
+    catch { /* may not be loaded */ }
+    try {
+        exec('launchctl', ['bootstrap', `gui/${uid}`, plist], opts);
+    }
+    catch { /* best effort */ }
+    try {
+        exec('launchctl', ['kickstart', serviceTarget], opts);
+    }
+    catch { /* best effort */ }
+}
 /**
  * Install + start the menu-bar helper as a launchd user service (idempotent).
  * Clears the sticky opt-out, installs the .app, writes the plist, and
@@ -232,19 +257,7 @@ export function enableMenubarService(opts = { clearOptOut: true }) {
     fs.mkdirSync(path.dirname(plist), { recursive: true });
     fs.writeFileSync(plist, generateServicePlist(exec));
     const uid = process.getuid?.() ?? 0;
-    try {
-        execFileSync('launchctl', ['bootstrap', `gui/${uid}`, plist], { stdio: ['ignore', 'ignore', 'ignore'] });
-    }
-    catch {
-        try {
-            execFileSync('launchctl', ['load', '-w', plist], { stdio: ['ignore', 'ignore', 'ignore'] });
-        }
-        catch { /* may already be loaded */ }
-    }
-    try {
-        execFileSync('launchctl', ['kickstart', '-k', `gui/${uid}/${SERVICE_LABEL}`], { stdio: ['ignore', 'ignore', 'ignore'] });
-    }
-    catch { /* best effort */ }
+    restartMenubarLaunchAgent(uid, plist);
     // Stamp the version we just installed so the upgrade self-heal can tell when
     // a later release ships a newer helper that needs reinstalling.
     try {

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

@@ -280,6 +280,11 @@ export declare function agentAutoLoadMetaSync(nameSetHash: string, bundles: Secr
  * per ~7d), so auto-caching is ON by default; opt out with
  * `secrets.agent.auto: false`. Best-effort; an unreadable meta reads as on. */
 export declare function secretsAgentAutoEnabled(): boolean;
+/** Default `sleepPersist` for a new unlock when `--durable` is not passed. OFF by
+ * default (the secure split default: survive restart, re-lock on sleep); set
+ * `secrets.agent.durable: true` in agents.yaml to make every unlock sleep-durable.
+ * Best-effort; an unreadable meta reads as off. */
+export declare function secretsAgentDurable(): boolean;
 /** Minimum / maximum bounds for the configurable hold window. A too-small value
  * would defeat the broker (constant re-prompts); a too-large one pins secrets in
  * memory far longer than intended. */

package/dist/lib/secrets/agent.js

@@ -34,6 +34,7 @@ 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 { rehydrateSessions, pruneSessionsOnSleep } from './session-store.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;
@@ -93,6 +94,20 @@ export function shouldTeardownVersionSkewedBroker(realHeldBundles) {
 function onDarwin() {
     return process.platform === 'darwin';
 }
+/**
+ * Build the broker's in-memory store, REHYDRATED from the durable session store
+ * (session-store.ts) so an unlock survives a daemon restart / agents-cli upgrade.
+ * Expired sessions are dropped; `--durable` and default entries alike come back
+ * (SLEEP already pruned the non-durable ones from the keychain while the broker
+ * was alive). Empty off darwin or when nothing was held.
+ */
+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 });
+    }
+    return store;
+}
 /** Broker runtime dir under the regenerable cache, locked to the user (0700).
  * AGENTS_SECRETS_AGENT_DIR overrides the location — a test seam so the suite can
  * run a real broker on a temp socket without touching the user's real dir. */
@@ -442,7 +457,7 @@ export async function runSecretsAgent(opts = {}) {
             throw err;
         }
     }
-    const store = new Map();
+    const store = rehydrateStore();
     // emptySince tracks the last moment the store held something; the sweep exits
     // the process once it's been empty for IDLE_EXIT_MS so no idle broker lingers.
     let emptySince = Date.now();
@@ -589,6 +604,9 @@ export async function runSecretsAgent(opts = {}) {
             if (shouldWipeOnWatchEvent(chunk)) {
                 store.clear();
                 emptySince = Date.now();
+                // Split default: delete non-`--durable` durable sessions too, so a default
+                // unlock re-locks on sleep; `--durable` ones survive (session-store.ts).
+                pruneSessionsOnSleep();
             }
         });
         watcher.on('error', () => { watcher = null; });
@@ -627,7 +645,7 @@ export async function runSecretsAgent(opts = {}) {
 export async function startHostedBroker() {
     if (!onDarwin())
         return null;
-    const store = new Map();
+    const store = rehydrateStore();
     const sock = socketPath(); // agentDir() creates the 0700 dir as a side effect
     const handle = (req) => handleAgentRequest(store, req);
     const onConn = makeConnectionHandler(handle, readAgentToken);
@@ -651,8 +669,10 @@ export async function startHostedBroker() {
         watcher = spawn(getKeychainHelperPath(), ['watch-lock'], { stdio: ['ignore', 'pipe', 'ignore'] });
         watcher.stdout?.setEncoding('utf-8');
         watcher.stdout?.on('data', (chunk) => {
-            if (shouldWipeOnWatchEvent(chunk))
+            if (shouldWipeOnWatchEvent(chunk)) {
                 store.clear();
+                pruneSessionsOnSleep(); // split default — see runSecretsAgent's handler
+            }
         });
         watcher.on('error', () => { watcher = null; });
     }
@@ -912,6 +932,18 @@ export function secretsAgentAutoEnabled() {
         return true;
     }
 }
+/** Default `sleepPersist` for a new unlock when `--durable` is not passed. OFF by
+ * default (the secure split default: survive restart, re-lock on sleep); set
+ * `secrets.agent.durable: true` in agents.yaml to make every unlock sleep-durable.
+ * Best-effort; an unreadable meta reads as off. */
+export function secretsAgentDurable() {
+    try {
+        return readMeta().secrets?.agent?.durable === true;
+    }
+    catch {
+        return false;
+    }
+}
 /** Minimum / maximum bounds for the configurable hold window. A too-small value
  * would defeat the broker (constant re-prompts); a too-large one pins secrets in
  * memory far longer than intended. */

package/dist/lib/secrets/bundles.js

@@ -26,6 +26,7 @@ import { fileStore } from './filestore.js';
 import { emit } from '../events.js';
 import { readMeta } from '../state.js';
 import { agentGetSync, agentAutoLoadSync, agentGetMetaSync, agentAutoLoadMetaSync, agentEvictSync, secretsAgentAutoEnabled, secretsHoldMs } from './agent.js';
+import { loadSession, deleteSession } from './session-store.js';
 import { createHash } from 'node:crypto';
 const keychainStore = {
     has: hasKeychainToken,
@@ -362,6 +363,9 @@ export function writeBundle(bundle, opts = {}) {
     // re-resolves from the keychain instead of serving stale values.
     if (shouldEvictAfterBundleWrite(Boolean(opts.skipBrokerEviction), process.env.AGENTS_SECRETS_NO_AGENT, isKeychainBackendOverridden())) {
         agentEvictSync(bundle.name);
+        // Also drop any durable session snapshot, or a broker restart would rehydrate
+        // the stale env after a rotate/rename (session-store.ts).
+        deleteSession(bundle.name);
     }
 }
 export function deleteBundle(name) {
@@ -371,6 +375,7 @@ export function deleteBundle(name) {
         emit('secrets.delete', { module: 'secrets', bundle: name });
         if (shouldEvictAfterBundleWrite(false, process.env.AGENTS_SECRETS_NO_AGENT, isKeychainBackendOverridden())) {
             agentEvictSync(name);
+            deleteSession(name); // a deleted bundle must not be rehydratable
         }
     }
     return deleted;
@@ -787,6 +792,29 @@ export function readAndResolveBundleEnv(name, opts = {}) {
             });
             return filtered;
         }
+        // Durable-session fallback (Correction B). After a daemon restart / agents-cli
+        // upgrade the broker RAM is empty, so the fast-path above misses — but the
+        // unlock persisted a no-ACL session item (session-store.ts) that reads with NO
+        // Touch ID. Serve from it and re-warm the broker, so a warm bundle stays warm
+        // across restart — this fixes BOTH the interactive re-prompt and the headless
+        // throw below (which now fires only when there is genuinely no session).
+        const session = loadSession(name);
+        if (session) {
+            const filtered = filterAgentHitBySubsetAndExpiry({ bundle: session.bundle, env: session.env }, opts);
+            stampLastUsed(filtered.bundle);
+            // Re-warm the broker with the remaining TTL so later reads hit RAM and
+            // `agents secrets status` is honest. Best-effort; no-ops off darwin.
+            agentAutoLoadSync(name, session.bundle, session.env, Math.max(1, session.expiresAt - Date.now()));
+            emit('secrets.get', {
+                module: 'secrets',
+                bundle: name,
+                operation: opts.caller,
+                status: 'success',
+                source: 'session',
+                keyCount: Object.keys(filtered.env).length,
+            });
+            return filtered;
+        }
     }
     // Only keychain-backed bundles can pop a Touch ID prompt and are the only ones
     // the broker ever holds. A file-backed bundle resolves via passphrase with no

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

@@ -22,6 +22,7 @@
  * through the explicit export/import flow in src/lib/secrets/sync.ts
  * rather than the system's cloud-keychain path.
  */
+import { type SpawnSyncOptions } from 'child_process';
 import type { NativeImportReport } from './fallback.js';
 export type { NativeImportReport, NativeImportResult, NativeImportStatus } from './fallback.js';
 export declare const SECRETS_ITEM_PREFIX = "agents-cli.secrets.";
@@ -221,6 +222,19 @@ export declare function getKeychainTokens(items: string[]): Map<string, string>;
  * a `ps` snapshot. Exported so a test can assert the value is absent from argv.
  */
 export declare function buildAddGenericPasswordArgs(account: string, item: string): string[];
+/**
+ * spawnSync options for the bare `-w` keychain write. Pure so the two
+ * load-bearing properties are unit-testable without touching the real keychain:
+ *   - `input` pipes the value TWICE (bare `-w` prompts enter+confirm; one line
+ *     fails the confirm and stores an empty secret).
+ *   - `detached: true` runs `security` in a new session with no controlling
+ *     terminal, so readpassphrase(3) falls back to our piped stdin instead of
+ *     prompting the user's `/dev/tty` in an interactive shell (see setKeychainToken).
+ */
+export declare function buildAddGenericPasswordSpawnOptions(value: string): SpawnSyncOptions & {
+    input: string;
+    detached: boolean;
+};
 export declare function setKeychainToken(item: string, value: string, opts?: {
     noAcl?: boolean;
 }): void;

package/dist/lib/secrets/index.js

@@ -506,6 +506,11 @@ export function computeRekeyPlan(services, values, key) {
             if (dot > 0)
                 noAcl = bundleNoAcl(rest.slice(0, dot));
         }
+        // Durable "unlocked session" items (agents-cli.session.*, see session-store.ts)
+        // are always no-ACL — re-wrapping them in a biometry ACL on rekey would break
+        // their silent (no-Touch-ID) reads that the rehydrate/fallback paths depend on.
+        if (service.startsWith('agents-cli.session.'))
+            noAcl = true;
         items.push({ oldService: service, newService: hashedServiceName(service, key), noAcl });
     }
     return { items, unreadable };
@@ -853,6 +858,25 @@ function parseBatchRecords(out, record) {
 export function buildAddGenericPasswordArgs(account, item) {
     return ['add-generic-password', '-U', '-a', account, '-s', item, '-w'];
 }
+/**
+ * spawnSync options for the bare `-w` keychain write. Pure so the two
+ * load-bearing properties are unit-testable without touching the real keychain:
+ *   - `input` pipes the value TWICE (bare `-w` prompts enter+confirm; one line
+ *     fails the confirm and stores an empty secret).
+ *   - `detached: true` runs `security` in a new session with no controlling
+ *     terminal, so readpassphrase(3) falls back to our piped stdin instead of
+ *     prompting the user's `/dev/tty` in an interactive shell (see setKeychainToken).
+ */
+export function buildAddGenericPasswordSpawnOptions(value) {
+    // `detached` is honored by spawnSync at runtime (libuv setsid) but is not
+    // declared on Node's SpawnSyncOptions type, so widen the return explicitly.
+    return {
+        input: `${value}\n${value}\n`,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: 10_000,
+        detached: true,
+    };
+}
 export function setKeychainToken(item, value, opts) {
     // Validate the CLEARTEXT name (a hashed storage name is always clean), then
     // resolve the storage name.
@@ -893,11 +917,18 @@ export function setKeychainToken(item, value, opts) {
         // (assertValueStorable above), so each line carries the whole secret verbatim
         // (no shell/quoting layer). `timeout` bounds the call so a context that cannot
         // read the prompt fails loudly instead of hanging.
-        const sec = spawnSync('/usr/bin/security', buildAddGenericPasswordArgs(os.userInfo().username, item), {
-            input: `${value}\n${value}\n`,
-            stdio: ['pipe', 'pipe', 'pipe'],
-            timeout: 10_000,
-        });
+        //
+        // `detached: true` is load-bearing, not an afterthought: readpassphrase(3)
+        // reads from the *controlling terminal* (`/dev/tty`) when one exists, and only
+        // falls back to fd 0 when it cannot open one. So piping over stdin works in a
+        // headless/CI context (no controlling tty) but is IGNORED in an interactive
+        // shell — there `security` prompts the real user ("password data for new
+        // item:") and hangs to the timeout, and any keystroke would be stored AS the
+        // secret. `detached` runs the child in a new session (setsid) with no
+        // controlling terminal, so readpassphrase always falls back to our piped
+        // stdin. Without it, an interactive `agents view` (refreshing+saving a Claude
+        // OAuth token) or `agents secrets add` pops a keychain password sheet.
+        const sec = spawnSync('/usr/bin/security', buildAddGenericPasswordArgs(os.userInfo().username, item), buildAddGenericPasswordSpawnOptions(value));
         if (sec.status !== 0) {
             const msg = sec.stderr?.toString().trim();
             throw new Error(msg || `Failed to write keychain item '${item}'.`);

package/dist/lib/secrets/session-store.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Durable "unlocked session" store (macOS).
+ *
+ * The secrets broker (agent.ts) holds unlocked bundles only in RAM, so an
+ * `agents secrets unlock` grant is lost whenever that process dies: on an
+ * agents-cli upgrade (the postinstall bounces the daemon) and on system SLEEP.
+ * This module persists the resolved bundle+env of an unlocked bundle as a
+ * NO-ACL keychain item — the `set-no-acl` write path, `kSecAttrAccessibleAfter-
+ * FirstUnlockThisDeviceOnly`, whose reads never pop Touch ID — so the broker can
+ * REHYDRATE it on start and reads can FALL BACK to it when the broker RAM misses.
+ *
+ * Split-default posture: `sleepPersist` is false by default — the item is deleted
+ * on SLEEP so the bundle re-locks on sleep but survives restart/upgrade; the
+ * `--durable` flag sets it true so it survives sleep too. Both expire at the TTL.
+ *
+ * Cross-platform: a NO-OP off macOS. Linux (secret-service) and Windows
+ * (Credential Manager) have no broker and resolve secrets durably from the OS
+ * store on every read with no prompt (see agent.ts:onDarwin gates) — there is no
+ * ephemeral unlock to persist.
+ *
+ * NEVER enumerate session items: once keychain-name hashing (#316) is active a
+ * `list('agents-cli.session.')` matches nothing. All I/O is by KNOWN name — one
+ * fixed-name index item lists the held bundles + their metadata, and one blob per
+ * bundle holds the env. Every adapter call is best-effort and never throws;
+ * persistence is an optimization, not a correctness dependency.
+ */
+import type { SecretsBundle } from './bundles.js';
+/** Prefix for all durable session items (device-local, no-ACL). */
+export declare const SESSION_ITEM_PREFIX = "agents-cli.session.";
+/** Fixed-name index item — the ONLY thing we ever need to find without a known
+ * bundle name, so it is read/written by this exact name (never enumerated). */
+export declare const SESSION_INDEX_ITEM = "agents-cli.session.index";
+/** One persisted unlocked bundle (mirrors the broker's StoredBundle + posture). */
+export interface SessionEntry {
+    bundle: SecretsBundle;
+    env: Record<string, string>;
+    /** epoch ms; the entry is dead once Date.now() passes this. */
+    expiresAt: number;
+    /** true only for `--durable` unlocks — survives SLEEP. */
+    sleepPersist: boolean;
+}
+/** Metadata for one held bundle, kept in the index so we can rehydrate / prune
+ * without reading every blob. */
+export interface SessionIndexMeta {
+    expiresAt: number;
+    sleepPersist: boolean;
+}
+export interface SessionIndex {
+    bundles: Record<string, SessionIndexMeta>;
+}
+/** The bundle names in the index that are still within their TTL at `now`. */
+export declare function selectRehydratable(index: SessionIndex, now: number): string[];
+/** Split an index on a SLEEP event: keep `sleepPersist` entries, report the rest
+ * (which the caller deletes from the keychain). Default entries re-lock on sleep. */
+export declare function pruneOnSleep(index: SessionIndex): {
+    survivors: SessionIndex;
+    deletedNames: string[];
+};
+/** Drop entries past their TTL; report which were dropped so the caller can
+ * delete their blobs. */
+export declare function pruneExpired(index: SessionIndex, now: number): {
+    survivors: SessionIndex;
+    expiredNames: string[];
+};
+/** Insert/replace one bundle in the index (pure). */
+export declare function upsertEntry(index: SessionIndex, name: string, meta: SessionIndexMeta): SessionIndex;
+/** Remove one bundle from the index (pure). */
+export declare function removeEntry(index: SessionIndex, name: string): SessionIndex;
+/** Read the session index by its fixed name. `{bundles:{}}` when absent/unreadable. */
+export declare function readIndex(): SessionIndex;
+/** Persist the index as a no-ACL item. Deletes the item when empty (tidy). */
+export declare function writeIndex(index: SessionIndex): void;
+/** Persist one unlocked bundle: write its blob no-ACL and record it in the index. */
+export declare function saveSession(name: string, entry: SessionEntry): void;
+/** Read one session blob by known name. Null when absent/expired/malformed. */
+export declare function loadSession(name: string, now?: number): SessionEntry | null;
+/** Delete one bundle's session blob and prune it from the index. */
+export declare function deleteSession(name: string): void;
+/** Delete every session blob + the index (for `secrets lock --all`). */
+export declare function deleteAllSessions(): void;
+/** Rehydrate every unexpired session into `[name, entry]` pairs for the broker to
+ * load on start; prunes expired index entries + blobs as a side effect. Survives
+ * upgrade/restart. Empty off darwin or when nothing is held. */
+export declare function rehydrateSessions(now?: number): Array<{
+    name: string;
+    entry: SessionEntry;
+}>;
+/** On a SLEEP event: delete every non-`--durable` session (blob + index entry),
+ * keep the durable ones. Default bundles thus re-lock on sleep. */
+export declare function pruneSessionsOnSleep(): void;

package/dist/lib/secrets/session-store.js

@@ -0,0 +1,221 @@
+/**
+ * Durable "unlocked session" store (macOS).
+ *
+ * The secrets broker (agent.ts) holds unlocked bundles only in RAM, so an
+ * `agents secrets unlock` grant is lost whenever that process dies: on an
+ * agents-cli upgrade (the postinstall bounces the daemon) and on system SLEEP.
+ * This module persists the resolved bundle+env of an unlocked bundle as a
+ * NO-ACL keychain item — the `set-no-acl` write path, `kSecAttrAccessibleAfter-
+ * FirstUnlockThisDeviceOnly`, whose reads never pop Touch ID — so the broker can
+ * REHYDRATE it on start and reads can FALL BACK to it when the broker RAM misses.
+ *
+ * Split-default posture: `sleepPersist` is false by default — the item is deleted
+ * on SLEEP so the bundle re-locks on sleep but survives restart/upgrade; the
+ * `--durable` flag sets it true so it survives sleep too. Both expire at the TTL.
+ *
+ * Cross-platform: a NO-OP off macOS. Linux (secret-service) and Windows
+ * (Credential Manager) have no broker and resolve secrets durably from the OS
+ * store on every read with no prompt (see agent.ts:onDarwin gates) — there is no
+ * ephemeral unlock to persist.
+ *
+ * NEVER enumerate session items: once keychain-name hashing (#316) is active a
+ * `list('agents-cli.session.')` matches nothing. All I/O is by KNOWN name — one
+ * fixed-name index item lists the held bundles + their metadata, and one blob per
+ * bundle holds the env. Every adapter call is best-effort and never throws;
+ * persistence is an optimization, not a correctness dependency.
+ */
+import { getKeychainToken, setKeychainToken, deleteKeychainToken, isKeychainBackendOverridden } from './index.js';
+/** Prefix for all durable session items (device-local, no-ACL). */
+export const SESSION_ITEM_PREFIX = 'agents-cli.session.';
+/** Fixed-name index item — the ONLY thing we ever need to find without a known
+ * bundle name, so it is read/written by this exact name (never enumerated). */
+export const SESSION_INDEX_ITEM = 'agents-cli.session.index';
+// ─── Pure core (no I/O — unit-testable on any platform) ─────────────────────
+/** The bundle names in the index that are still within their TTL at `now`. */
+export function selectRehydratable(index, now) {
+    return Object.entries(index.bundles)
+        .filter(([, m]) => now < m.expiresAt)
+        .map(([name]) => name);
+}
+/** Split an index on a SLEEP event: keep `sleepPersist` entries, report the rest
+ * (which the caller deletes from the keychain). Default entries re-lock on sleep. */
+export function pruneOnSleep(index) {
+    const survivors = { bundles: {} };
+    const deletedNames = [];
+    for (const [name, m] of Object.entries(index.bundles)) {
+        if (m.sleepPersist)
+            survivors.bundles[name] = m;
+        else
+            deletedNames.push(name);
+    }
+    return { survivors, deletedNames };
+}
+/** Drop entries past their TTL; report which were dropped so the caller can
+ * delete their blobs. */
+export function pruneExpired(index, now) {
+    const survivors = { bundles: {} };
+    const expiredNames = [];
+    for (const [name, m] of Object.entries(index.bundles)) {
+        if (now < m.expiresAt)
+            survivors.bundles[name] = m;
+        else
+            expiredNames.push(name);
+    }
+    return { survivors, expiredNames };
+}
+/** Insert/replace one bundle in the index (pure). */
+export function upsertEntry(index, name, meta) {
+    return { bundles: { ...index.bundles, [name]: meta } };
+}
+/** Remove one bundle from the index (pure). */
+export function removeEntry(index, name) {
+    const { [name]: _drop, ...rest } = index.bundles;
+    void _drop;
+    return { bundles: rest };
+}
+// ─── Keychain adapter (macOS only; best-effort, never throws) ────────────────
+/** Whether to actually persist. macOS in production; also whenever a test
+ * keychain backend is installed, so the adapter is exercisable on Linux CI
+ * against an in-memory store (mirrors the broker's hermetic-test gating). In real
+ * Linux/Windows production this is false — secrets already persist in the OS store
+ * with no broker, so there is nothing to mirror. */
+function shouldPersist() {
+    return process.platform === 'darwin' || isKeychainBackendOverridden();
+}
+function sessionBlobItem(name) {
+    return `${SESSION_ITEM_PREFIX}${name}`;
+}
+/** Read the session index by its fixed name. `{bundles:{}}` when absent/unreadable. */
+export function readIndex() {
+    try {
+        const raw = getKeychainToken(SESSION_INDEX_ITEM);
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && parsed.bundles)
+            return parsed;
+    }
+    catch {
+        /* absent or malformed → empty */
+    }
+    return { bundles: {} };
+}
+/** Persist the index as a no-ACL item. Deletes the item when empty (tidy). */
+export function writeIndex(index) {
+    try {
+        if (Object.keys(index.bundles).length === 0) {
+            deleteKeychainToken(SESSION_INDEX_ITEM);
+            return;
+        }
+        setKeychainToken(SESSION_INDEX_ITEM, JSON.stringify(index), { noAcl: true });
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Persist one unlocked bundle: write its blob no-ACL and record it in the index. */
+export function saveSession(name, entry) {
+    if (!shouldPersist())
+        return;
+    try {
+        setKeychainToken(sessionBlobItem(name), JSON.stringify(entry), { noAcl: true });
+        writeIndex(upsertEntry(readIndex(), name, { expiresAt: entry.expiresAt, sleepPersist: entry.sleepPersist }));
+    }
+    catch {
+        /* best-effort — persistence is an optimization */
+    }
+}
+/** Read one session blob by known name. Null when absent/expired/malformed. */
+export function loadSession(name, now = Date.now()) {
+    if (!shouldPersist())
+        return null;
+    try {
+        const raw = getKeychainToken(sessionBlobItem(name));
+        const entry = JSON.parse(raw);
+        if (!entry || typeof entry !== 'object' || !entry.bundle || !entry.env)
+            return null;
+        if (now >= entry.expiresAt) {
+            deleteSession(name); // drop expired on read, mirroring the broker's get handler
+            return null;
+        }
+        return entry;
+    }
+    catch {
+        return null;
+    }
+}
+/** Delete one bundle's session blob and prune it from the index. */
+export function deleteSession(name) {
+    if (!shouldPersist())
+        return;
+    try {
+        deleteKeychainToken(sessionBlobItem(name));
+        writeIndex(removeEntry(readIndex(), name));
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Delete every session blob + the index (for `secrets lock --all`). */
+export function deleteAllSessions() {
+    if (!shouldPersist())
+        return;
+    try {
+        for (const name of Object.keys(readIndex().bundles)) {
+            try {
+                deleteKeychainToken(sessionBlobItem(name));
+            }
+            catch { /* keep going */ }
+        }
+        deleteKeychainToken(SESSION_INDEX_ITEM);
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Rehydrate every unexpired session into `[name, entry]` pairs for the broker to
+ * load on start; prunes expired index entries + blobs as a side effect. Survives
+ * upgrade/restart. Empty off darwin or when nothing is held. */
+export function rehydrateSessions(now = Date.now()) {
+    if (!shouldPersist())
+        return [];
+    const out = [];
+    try {
+        const index = readIndex();
+        const { survivors, expiredNames } = pruneExpired(index, now);
+        for (const name of expiredNames) {
+            try {
+                deleteKeychainToken(sessionBlobItem(name));
+            }
+            catch { /* keep going */ }
+        }
+        if (expiredNames.length)
+            writeIndex(survivors);
+        for (const name of selectRehydratable(survivors, now)) {
+            const entry = loadSession(name, now);
+            if (entry)
+                out.push({ name, entry });
+        }
+    }
+    catch {
+        /* best-effort */
+    }
+    return out;
+}
+/** On a SLEEP event: delete every non-`--durable` session (blob + index entry),
+ * keep the durable ones. Default bundles thus re-lock on sleep. */
+export function pruneSessionsOnSleep() {
+    if (!shouldPersist())
+        return;
+    try {
+        const { survivors, deletedNames } = pruneOnSleep(readIndex());
+        for (const name of deletedNames) {
+            try {
+                deleteKeychainToken(sessionBlobItem(name));
+            }
+            catch { /* keep going */ }
+        }
+        writeIndex(survivors);
+    }
+    catch {
+        /* best-effort */
+    }
+}