@phnx-labs/agents-cli 1.22.27 → 1.22.28

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

@@ -26,6 +26,7 @@
 import * as net from 'net';
 import type { SecretsBundle } from './bundles.js';
 import { GLOBAL_HARNESS, bundleScopeChain } from './scope.js';
+import { type SecretLease } from './lease.js';
 export { GLOBAL_HARNESS, bundleScopeChain };
 /** Default lifetime of an unlocked bundle when `--ttl` is not given. */
 export declare const DEFAULT_TTL_MS: number;
@@ -72,6 +73,7 @@ export interface StoredBundle {
     /** epoch ms; the entry is gone once Date.now() passes this. */
     expiresAt: number;
     harness: string;
+    lease?: SecretLease;
 }
 /** One unlocked bundle as reported by `status`. */
 export interface AgentStatusEntry {
@@ -79,6 +81,8 @@ export interface AgentStatusEntry {
     expiresAt: number;
     keyCount: number;
     harness: string;
+    leaseId?: string;
+    keys?: string[];
 }
 /**
  * Read the current broker capability token, or null if none is present. Clients
@@ -119,11 +123,16 @@ export type Request = {
     bundle: SecretsBundle;
     env: Record<string, string>;
     ttlMs: number;
+    lease?: SecretLease;
     token?: string;
 } | {
     cmd: 'lock';
     name?: string;
     token?: string;
+} | {
+    cmd: 'revoke';
+    leaseId: string;
+    token?: string;
 } | {
     cmd: 'status';
     token?: string;
@@ -143,6 +152,7 @@ export type Response = {
     hit: true;
     bundle: SecretsBundle;
     env: Record<string, string>;
+    lease?: SecretLease;
 } | {
     ok: true;
     cmd: 'load';
@@ -150,6 +160,10 @@ export type Response = {
     ok: true;
     cmd: 'lock';
     wiped: number;
+} | {
+    ok: true;
+    cmd: 'revoke';
+    wiped: number;
 } | {
     ok: true;
     cmd: 'status';
@@ -237,7 +251,7 @@ export declare function runSecretsAgent(opts?: {
  *
  * Serves the SAME socket and wire protocol as the standalone `runSecretsAgent`
  * — so every existing client (`agentGetSync`, `agentPing`, `agentAutoLoadSync`)
- * keeps working unchanged, no PROTOCOL_VERSION bump — but it is daemon-safe:
+ * keeps working through the versioned protocol — but it is daemon-safe:
  *
  *   - no pid-file single-instance guard (the daemon owns the instance);
  *   - no `process.exit`, no SIGTERM/SIGINT handlers, no self-heal/idle-exit
@@ -296,6 +310,7 @@ export declare function syncClientLaunch(sub: string[], agentsBin?: string): {
 export declare function agentGetSync(name: string, harness?: string): {
     bundle: SecretsBundle;
     env: Record<string, string>;
+    lease?: SecretLease;
 } | null;
 /**
  * Last non-empty line of a child's stdout — the payload line.
@@ -410,7 +425,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, harness?: string): void;
+export declare function agentAutoLoadSync(name: string, bundle: SecretsBundle, env: Record<string, string>, ttlMs: number, harness?: string, lease?: SecretLease): 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
@@ -425,10 +440,11 @@ 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, harness?: string): Promise<boolean>;
+export declare function agentLoad(name: string, bundle: SecretsBundle, env: Record<string, string>, ttlMs: number, harness?: string, lease?: SecretLease): 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>;
+export declare function agentRevoke(leaseId: string): Promise<number>;
 /** List currently-unlocked bundles, or [] when no broker is running. The
  * internal `secrets list` metadata-cache entry is filtered out here as well as
  * server-side: during a rollout a NEW client can talk to an OLD broker that

package/dist/lib/secrets/agent.js

@@ -35,9 +35,11 @@ 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 { deleteLeaseSession, rehydrateSessions, pruneSessionsOnSleep } from './session-store.js';
 import { SYNC_GET_CMD, SYNC_PING_CMD, SYNC_LOCK_CMD } from './sync-commands.js';
 import { MAX_LEASE_MS, MIN_LEASE_MS } from './lease.js';
+import { selectLeasedEnv } from './lease.js';
+import { emitSecretAudit } from './audit.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
@@ -45,7 +47,7 @@ import { MAX_LEASE_MS, MIN_LEASE_MS } from './lease.js';
 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;
+const PROTOCOL_VERSION = 3;
 /** Default lifetime of an unlocked bundle when `--ttl` is not given. */
 export const DEFAULT_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7d
 /**
@@ -154,7 +156,7 @@ function rehydrateStore(now = Date.now()) {
     const store = new Map();
     for (const { name, entry } of rehydrateSessions(now)) {
         const harness = entry.harness || GLOBAL_HARNESS;
-        store.set(scopedBundleKey(name, harness), { bundle: entry.bundle, env: entry.env, expiresAt: entry.expiresAt, harness });
+        store.set(scopedBundleKey(name, harness), { bundle: entry.bundle, env: entry.env, expiresAt: entry.expiresAt, harness, lease: entry.lease });
     }
     return store;
 }
@@ -352,16 +354,30 @@ export function handleAgentRequest(store, req, now = Date.now()) {
                     continue;
                 if (now >= e.expiresAt) {
                     store.delete(key);
+                    if (e.lease) {
+                        deleteLeaseSession(e.lease.id);
+                        emitSecretAudit({ event: 'secrets.lease-expire', bundle: e.bundle.name, operation: 'lease-expire', source: 'broker', status: 'success', keys: e.lease.keys, keyCount: e.lease.keys.length, agent: e.lease.harness });
+                    }
                     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, lease: e.lease };
             }
             return { ok: true, cmd: 'get', hit: false };
         }
-        case 'load':
+        case 'load': {
             const harness = req.harness || GLOBAL_HARNESS;
-            store.set(scopedBundleKey(req.name, harness), { bundle: req.bundle, env: req.env, expiresAt: now + req.ttlMs, harness });
+            let env = req.env;
+            if (req.lease) {
+                try {
+                    env = selectLeasedEnv(req.lease, req.env, now);
+                }
+                catch (err) {
+                    return { ok: false, error: err.message };
+                }
+            }
+            store.set(scopedBundleKey(req.name, harness), { bundle: req.bundle, env, expiresAt: req.lease?.expiresAt ?? now + req.ttlMs, harness, lease: req.lease });
             return { ok: true, cmd: 'load' };
+        }
         case 'lock': {
             if (req.name) {
                 let wiped = 0;
@@ -374,6 +390,13 @@ export function handleAgentRequest(store, req, now = Date.now()) {
             store.clear();
             return { ok: true, cmd: 'lock', wiped };
         }
+        case 'revoke': {
+            let wiped = 0;
+            for (const [key, entry] of store)
+                if (entry.lease?.id === req.leaseId && store.delete(key))
+                    wiped++;
+            return { ok: true, cmd: 'revoke', wiped };
+        }
         case 'status': {
             const entries = [];
             for (const [name, e] of store) {
@@ -381,7 +404,7 @@ export function handleAgentRequest(store, req, now = Date.now()) {
                     continue;
                 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 });
+                entries.push({ name: e.bundle.name, expiresAt: e.expiresAt, keyCount: Object.keys(e.env).length, harness: e.harness, leaseId: e.lease?.id, keys: e.lease?.keys });
             }
             return { ok: true, cmd: 'status', entries };
         }
@@ -649,8 +672,13 @@ export async function runSecretsAgent(opts = {}) {
     const sweep = () => {
         const now = Date.now();
         for (const [name, e] of store)
-            if (now >= e.expiresAt)
+            if (now >= e.expiresAt) {
                 store.delete(name);
+                if (e.lease) {
+                    deleteLeaseSession(e.lease.id);
+                    emitSecretAudit({ event: 'secrets.lease-expire', bundle: e.bundle.name, operation: 'lease-expire', source: 'broker', status: 'success', keys: e.lease.keys, keyCount: e.lease.keys.length, agent: e.lease.harness });
+                }
+            }
         const live = realBundleCount(store);
         // Self-heal onto a newer in-place install — but ONLY while no real unlocks
         // are held, so we never wipe live unlocks and force a re-prompt (#435). A
@@ -767,7 +795,7 @@ export async function runSecretsAgent(opts = {}) {
  *
  * Serves the SAME socket and wire protocol as the standalone `runSecretsAgent`
  * — so every existing client (`agentGetSync`, `agentPing`, `agentAutoLoadSync`)
- * keeps working unchanged, no PROTOCOL_VERSION bump — but it is daemon-safe:
+ * keeps working through the versioned protocol — but it is daemon-safe:
  *
  *   - no pid-file single-instance guard (the daemon owns the instance);
  *   - no `process.exit`, no SIGTERM/SIGINT handlers, no self-heal/idle-exit
@@ -796,9 +824,15 @@ export async function startHostedBroker() {
     // whole daemon down with it.
     const sweepTimer = setInterval(() => {
         const now = Date.now();
-        for (const [name, e] of store)
-            if (now >= e.expiresAt)
-                store.delete(name);
+        for (const [name, e] of store) {
+            if (now < e.expiresAt)
+                continue;
+            store.delete(name);
+            if (e.lease) {
+                deleteLeaseSession(e.lease.id);
+                emitSecretAudit({ event: 'secrets.lease-expire', bundle: e.bundle.name, operation: 'lease-expire', source: 'broker', status: 'success', keys: e.lease.keys, keyCount: e.lease.keys.length, agent: e.lease.harness });
+            }
+        }
     }, SWEEP_INTERVAL_MS);
     // Auto-lock on sleep, same as the standalone broker: the signed helper emits
     // LOCK/SLEEP lines; wipe the in-memory store on a wipe-worthy event.
@@ -944,7 +978,7 @@ export function agentGetSync(name, harness = GLOBAL_HARNESS) {
         const o = JSON.parse(lastLine(r.stdout));
         if (!o || typeof o !== 'object' || !o.env)
             return null;
-        return { bundle: o.bundle, env: o.env };
+        return { bundle: o.bundle, env: o.env, lease: o.lease };
     }
     catch {
         return null;
@@ -1026,7 +1060,7 @@ export async function runAgentGetSync(name, harness = GLOBAL_HARNESS) {
         // truncated on exit — the parent would see a partial or empty payload, treat
         // it as a miss, and fall through to a keychain read, silently costing the
         // Touch ID prompt this whole path exists to avoid.
-        const payload = JSON.stringify({ bundle: r.bundle, env: r.env }) + '\n';
+        const payload = JSON.stringify({ bundle: r.bundle, env: r.env, lease: r.lease }) + '\n';
         await new Promise((resolve) => { process.stdout.write(payload, () => resolve()); });
         return 0;
     }
@@ -1166,10 +1200,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, harness = GLOBAL_HARNESS) {
+export function agentAutoLoadSync(name, bundle, env, ttlMs, harness = GLOBAL_HARNESS, lease) {
     if (!onDarwin())
         return;
-    const payload = JSON.stringify({ name, bundle, env, ttlMs, harness });
+    const payload = JSON.stringify({ name, bundle, env, ttlMs, harness, lease });
     // 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
@@ -1236,13 +1270,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, payload.harness ?? GLOBAL_HARNESS);
+    const loaded = await agentLoad(payload.name, payload.bundle, payload.env, payload.ttlMs ?? DEFAULT_TTL_MS, payload.harness ?? GLOBAL_HARNESS, payload.lease);
     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 = GLOBAL_HARNESS) {
-    const r = await request({ cmd: 'load', name, bundle, env, ttlMs, harness });
+export async function agentLoad(name, bundle, env, ttlMs, harness = GLOBAL_HARNESS, lease) {
+    const r = await request({ cmd: 'load', name, bundle, env, ttlMs, harness, lease });
     return r?.ok === true && r.cmd === 'load';
 }
 /** Wipe one bundle (or all if name omitted) from the broker. Returns the count
@@ -1251,6 +1285,10 @@ export async function agentLock(name) {
     const r = await request({ cmd: 'lock', name });
     return r?.ok === true && r.cmd === 'lock' ? r.wiped : 0;
 }
+export async function agentRevoke(leaseId) {
+    const r = await request({ cmd: 'revoke', leaseId });
+    return r?.ok === true && r.cmd === 'revoke' ? r.wiped : 0;
+}
 /** List currently-unlocked bundles, or [] when no broker is running. The
  * internal `secrets list` metadata-cache entry is filtered out here as well as
  * server-side: during a rollout a NEW client can talk to an OLD broker that

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

@@ -1,4 +1,4 @@
-export type SecretAuditEvent = 'secrets.get' | 'secrets.unlocked' | 'secrets.create' | 'secrets.import' | 'secrets.export' | 'secrets.view';
+export type SecretAuditEvent = 'secrets.get' | 'secrets.unlocked' | 'secrets.create' | 'secrets.import' | 'secrets.export' | 'secrets.view' | 'secrets.lease-denied' | 'secrets.lease-expire';
 export interface SecretAuditParams {
     /** Which audit event this is — a read (`secrets.get`) or an unlock grant. */
     event: SecretAuditEvent;

package/dist/lib/secrets/audit.js

@@ -46,6 +46,8 @@ const USAGE_KIND = {
     'secrets.import': 'import',
     'secrets.export': 'export',
     'secrets.view': 'view',
+    'secrets.lease-denied': 'access',
+    'secrets.lease-expire': 'access',
 };
 /**
  * The agent/harness identity to attribute a secret access to. Explicit callers

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

@@ -264,9 +264,9 @@ export interface ResolveBundleOptions {
 export declare function canCacheResolvedEnv(bundle: SecretsBundle, selectedKeys: Set<string>, keyMode: ResolveBundleOptions['keyMode']): boolean;
 /**
  * Apply the --keys subset + expiry gate to an already-resolved snapshot from
- * the secrets-agent fast-path. The agent stores the FULL bundle env, so a
- * naive fast-path return would silently defeat --keys and inject expired
- * values. Mirrors the slow-path pre-checks in `resolveBundleEnv` /
+ * the secrets-agent fast-path. The agent stores either a full unlock or a
+ * scoped lease env, so a naive fast-path return could silently defeat --keys
+ * and inject expired values. Mirrors the slow-path pre-checks in `resolveBundleEnv` /
  * `readAndResolveBundleEnv` and returns a new env whose keys match the subset.
  *
  * Exported for tests; production callers reach it via the fast-path branch in

package/dist/lib/secrets/bundles.js

@@ -1033,9 +1033,9 @@ export function canCacheResolvedEnv(bundle, selectedKeys, keyMode) {
 }
 /**
  * Apply the --keys subset + expiry gate to an already-resolved snapshot from
- * the secrets-agent fast-path. The agent stores the FULL bundle env, so a
- * naive fast-path return would silently defeat --keys and inject expired
- * values. Mirrors the slow-path pre-checks in `resolveBundleEnv` /
+ * the secrets-agent fast-path. The agent stores either a full unlock or a
+ * scoped lease env, so a naive fast-path return could silently defeat --keys
+ * and inject expired values. Mirrors the slow-path pre-checks in `resolveBundleEnv` /
  * `readAndResolveBundleEnv` and returns a new env whose keys match the subset.
  *
  * Exported for tests; production callers reach it via the fast-path branch in
@@ -1230,7 +1230,12 @@ export function readAndResolveBundleEnv(name, opts = {}) {
         const harness = opts.agent || process.env.AGENTS_AGENT_NAME || GLOBAL_HARNESS;
         const hit = agentGetSync(name, harness);
         if (hit) {
-            // The agent stores the FULL bundle env. Apply the same subset filter and
+            const denied = (opts.keys ?? []).filter((key) => hit.lease && !hit.lease.keys.includes(key));
+            if (denied.length > 0) {
+                emitSecretAudit({ event: 'secrets.lease-denied', bundle: name, operation: opts.caller, source: 'agent', status: 'error', keys: denied, keyCount: denied.length, agent: harness, error: 'key outside lease scope' });
+                throw new Error(`Secret lease '${hit.lease?.id}' does not grant key(s): ${denied.join(', ')}`);
+            }
+            // The agent stores a full unlock or a scoped lease env. Apply the same subset filter and
             // expiry gate as the slow path — without this, `--secrets-keys X` would
             // silently inject every key and an expired key would flow through after
             // the first cache-populating run.
@@ -1256,13 +1261,18 @@ export function readAndResolveBundleEnv(name, opts = {}) {
         const resolved = resolveSession(name, Date.now(), harness);
         if (resolved) {
             const session = resolved.entry;
+            const denied = (opts.keys ?? []).filter((key) => session.lease && !session.lease.keys.includes(key));
+            if (denied.length > 0) {
+                emitSecretAudit({ event: 'secrets.lease-denied', bundle: name, operation: opts.caller, source: 'session', status: 'error', keys: denied, keyCount: denied.length, agent: harness, error: 'key outside lease scope' });
+                throw new Error(`Secret lease '${session.lease?.id}' does not grant key(s): ${denied.join(', ')}`);
+            }
             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. Re-warm under the scope the grant was
             // MADE in (resolved.harness), never the asking scope — re-warming a global
             // grant as `claude` would silently narrow it for every other harness.
-            agentAutoLoadSync(name, session.bundle, session.env, Math.max(1, session.expiresAt - Date.now()), resolved.harness);
+            agentAutoLoadSync(name, session.bundle, session.env, Math.max(1, session.expiresAt - Date.now()), resolved.harness, session.lease);
             emitSecretAudit({
                 event: 'secrets.get',
                 bundle: name,

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

@@ -51,6 +51,8 @@ export declare function encryptForFallback(plaintext: string, passphrase: string
 /** Decrypt an EncFile under a passphrase. Throws on wrong key or tampered
  *  ciphertext (auth-tag mismatch). Exported for tests. */
 export declare function decryptForFallback(enc: EncFile, passphrase: string): string;
+/** Absolute path of one encrypted file-store item. No read or decrypt occurs. */
+export declare function fileStoreItemPath(item: string): string;
 declare function fileHas(item: string): boolean;
 declare function fileGet(item: string): string;
 declare function fileGetBatch(items: string[]): Map<string, string>;

package/dist/lib/secrets/filestore.js

@@ -214,6 +214,10 @@ export function decryptForFallback(enc, passphrase) {
 function fileFor(item) {
     return path.join(fileDir(), `${item}.enc`);
 }
+/** Absolute path of one encrypted file-store item. No read or decrypt occurs. */
+export function fileStoreItemPath(item) {
+    return fileFor(item);
+}
 function fileHas(item) {
     return fs.existsSync(fileFor(item));
 }

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

@@ -25,6 +25,7 @@
  * persistence is an optimization, not a correctness dependency.
  */
 import type { SecretsBundle } from './bundles.js';
+import type { SecretLease } from './lease.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
@@ -39,6 +40,7 @@ export interface SessionEntry {
     /** true only for `--durable` unlocks — survives SLEEP. */
     sleepPersist: boolean;
     harness?: string;
+    lease?: SecretLease;
 }
 /** Metadata for one held bundle, kept in the index so we can rehydrate / prune
  * without reading every blob. */
@@ -90,6 +92,11 @@ export declare function loadSession(name: string, now?: number, harness?: string
 export declare function deleteBundleSessions(name: string): void;
 /** Delete one bundle's session blob and prune it from the index. */
 export declare function deleteSession(name: string, harness?: string): void;
+export declare function deleteLeaseSession(leaseId: string): number;
+export declare function activeLeaseSessions(now?: number): Array<{
+    name: string;
+    lease: SecretLease;
+}>;
 /** 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

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

@@ -192,6 +192,27 @@ export function deleteSession(name, harness = GLOBAL_HARNESS) {
         /* best-effort */
     }
 }
+export function deleteLeaseSession(leaseId) {
+    if (!shouldPersist())
+        return 0;
+    const index = readIndex();
+    let deleted = 0;
+    for (const [key, meta] of Object.entries(index.bundles)) {
+        const bundleName = key.split(':').slice(1).join(':');
+        const harness = meta.harness || GLOBAL_HARNESS;
+        const entry = loadSession(bundleName, Date.now(), harness);
+        if (entry?.lease?.id !== leaseId)
+            continue;
+        deleteSession(bundleName, harness);
+        deleted++;
+    }
+    return deleted;
+}
+export function activeLeaseSessions(now = Date.now()) {
+    return rehydrateSessions(now)
+        .filter((item) => Boolean(item.entry.lease))
+        .map(({ name, entry }) => ({ name, lease: entry.lease }));
+}
 /** Delete every session blob + the index (for `secrets lock --all`). */
 export function deleteAllSessions() {
     if (!shouldPersist())

package/dist/lib/session/active.d.ts

@@ -23,6 +23,42 @@ export declare function resolveOwner(pidActor: string | null | undefined, sessio
  * cwds are just gathered at a bounded spawn rate instead of a single burst.
  */
 export declare const LSOF_CONCURRENCY = 4;
+/**
+ * Process-local process-table memo (#2047). One `getActiveSessions` scan can
+ * call `ps -A` from the terminal path, the headless path, and host ancestry —
+ * without this, each is a full process-table snapshot. 5s is well under the
+ * ~10–30s menu-bar / `--active` poll so a quiet re-poll usually reuses the
+ * snapshot; a brand-new agent pid still appears on the next full refresh.
+ */
+export declare const PROCESS_TABLE_FRESH_MS = 5000;
+/**
+ * How long {@link listUnattributedActive} may reuse its last full `ps`+`lsof`
+ * result (#2047). Between full rescans the previous rows are re-emitted after
+ * dropping dead PIDs and PIDs that are now attributed. A *shrinking* attributed
+ * set forces a rescan so a process that just left teams/terminals can reappear
+ * as headless instead of vanishing until the next cold poll.
+ */
+export declare const UNATTRIBUTED_RESCAN_MS = 15000;
+/** Test seam: override the clock used by process-table / unattributed memos. */
+export declare function setActiveScanClockForTest(fn?: () => number): void;
+/** Test seam: drop the process-table + unattributed memos and their counters. */
+export declare function clearActiveScanCachesForTest(): void;
+/** Test seam: how many times the live `ps` / CIM path actually ran. */
+export declare function processTableLiveReadCountForTest(): number;
+/** Test seam: how many full unattributed (ps + lsof) rescans ran. */
+export declare function unattributedFullRescanCountForTest(): number;
+/**
+ * True when any pid in `prev` is absent from `next` — the attributed set
+ * shrank, so a process may need to reappear as unattributed. Pure for tests.
+ */
+export declare function attributedSetLostPids(prev: Set<number>, next: Set<number>): boolean;
+/**
+ * Drop rows whose pid is now attributed or no longer alive. Pure over the
+ * inputs so the unattributed TTL reuse path is unit-testable without a live
+ * process table. `alive` receives the row's `startedAtMs` so callers can apply
+ * the same pid-reuse guard {@link isPidAlive} uses elsewhere.
+ */
+export declare function filterCachedUnattributed(sessions: ActiveSession[], attributed: Set<number>, alive: (pid: number, startedAtMs?: number) => boolean): ActiveSession[];
 export type ActiveContext = 'terminal' | 'teams' | 'cloud' | 'headless';
 /**
  * Every status here is COMPUTED by the framework from observable signals — PID
@@ -348,6 +384,8 @@ export declare function resolveNamesToSessionIds(sessionNames: string[], deps: {
  * the start time can't be read, we keep the existence answer.
  */
 export declare function isPidAlive(pid: number, startedAtMs?: number): boolean;
+/** Test seam: drop the Claude session-file path memo. */
+export declare function clearClaudeSessionFileCacheForTest(): void;
 /**
  * Resolve a Claude transcript for `cwd` across the given project roots, newest
  * mtime winning when the same id/cwd resolves in more than one version home
@@ -431,6 +469,8 @@ interface LiveSignals {
     /** Rolling output-token throughput (tokens/sec). Undefined when no usage in the tail. */
     tokPerSec?: number;
 }
+/** Test seam: drop the in-process live-signals memo. */
+export declare function clearLiveSignalsCacheForTest(): void;
 /**
  * Derive the inferred state (working / waiting / idle + preview/badges) and, for
  * the two harnesses whose raw lines carry it, the output-token throughput.
@@ -444,6 +484,9 @@ interface LiveSignals {
  * `unknown` it used to fall through to. An opaque/untracked kind or an
  * unreadable/empty transcript yields an empty signal set, and the caller's
  * {@link resolveFallbackStatus} reports the honest live floor (`running`).
+ *
+ * Unchanged-mtime hits reuse the previous result (see {@link liveSignalsCache})
+ * so a 30s active-session poll does not re-tail every quiet transcript.
  */
 export declare function computeLiveSignals(kind: string, sessionFile: string | undefined, cwd: string | undefined, pidAlive: boolean): LiveSignals;
 /**
@@ -523,6 +566,12 @@ export declare function foldSubordinateAgents(candidates: AgentCandidate[], ppid
  * Classified by walking the ppid chain: any recognised UI ancestor (IDE
  * helper, terminal-app, or multiplexer) means `terminal`; nothing of the
  * sort means `headless` (daemon, launchd-spawned, orphan).
+ *
+ * Full `ps`+`lsof` rescans are throttled to {@link UNATTRIBUTED_RESCAN_MS}
+ * (#2047). Between rescans the previous rows are re-emitted after dropping
+ * dead PIDs and PIDs that are now attributed. A shrinking attributed set
+ * forces a rescan so a process that just left teams/terminals can reappear
+ * as headless.
  */
 export declare function listUnattributedActive(attributed: Set<number>): Promise<ActiveSession[]>;
 /** One tmux pane's resolved agent identity for the authoritative source. */