@phnx-labs/agents-cli 1.22.29 → 1.22.31

package/dist/lib/secrets/agent.js

@@ -142,6 +142,27 @@ export function shouldSelfHealForUpgrade(persistent, storeSize, runningVersion,
 export function shouldTeardownVersionSkewedBroker(realHeldBundles) {
     return realHeldBundles === 0;
 }
+/**
+ * Whether a version-skewed client may evict the reachable broker at all. The
+ * held-bundle gate above is necessary but not sufficient: a broker the always-on
+ * daemon is hosting must NEVER be client-evicted, even when it holds zero
+ * unlocks. teardownStaleBroker() recognizes only the standalone broker's
+ * pidPath() O_EXCL claim (the daemon writes ownerPath(), never pidPath()), so
+ * evicting a daemon-hosted broker unlinks its socket WITHOUT stopping the daemon;
+ * the daemon then keeps hostedBroker != null and shouldTakeOverBroker() refuses
+ * to re-host, orphaning its broker until the daemon restarts while every reader
+ * falls onto cold one-off brokers that re-prompt Touch ID — the storm. Deferring
+ * is safe: daemon code-version upgrades are handled by postinstall.js restarting
+ * it, and agentPing() already gated on PROTOCOL_VERSION, so a code-skewed daemon
+ * broker is still wire-compatible. Only when NO daemon owns the broker (churning
+ * dev installs with a dead/absent daemon — the case #435's client twin was built
+ * for) does the zero-held-bundles teardown apply, exactly as before.
+ */
+export function shouldClientEvictSkewedBroker(daemonRunning, realHeldBundles) {
+    if (daemonRunning)
+        return false;
+    return shouldTeardownVersionSkewedBroker(realHeldBundles);
+}
 function onDarwin() {
     return process.platform === 'darwin';
 }
@@ -175,6 +196,10 @@ function agentDir() {
 function socketPath() {
     return path.join(agentDir(), 'agent.sock');
 }
+/** Public accessor for the broker's socket path — `agents daemon status`/`services` reads it for display. */
+export function secretsBrokerSocketPath() {
+    return socketPath();
+}
 function pidPath() {
     return path.join(agentDir(), 'agent.pid');
 }
@@ -345,7 +370,7 @@ 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': {
-            // Walk own-harness → global so a `--for` grant wins over a global one and
+            // Walk own-harness → global so an `--agent` 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);
@@ -1285,10 +1310,6 @@ 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
@@ -1334,7 +1355,12 @@ export async function ensureAgentRunning(timeoutMs = 5000) {
     if (ping.reachable) {
         if (ping.cliVersion === undefined || ping.cliVersion === getCliVersionFresh())
             return true;
-        if (!shouldTeardownVersionSkewedBroker((await agentStatus()).length))
+        // A reachable but version-skewed broker: tear it down ONLY when no daemon
+        // hosts it and it holds no unlocks. Evicting a daemon-hosted broker orphans
+        // the daemon's socket and starts the Touch ID storm — see
+        // shouldClientEvictSkewedBroker.
+        const { isDaemonRunning } = await import('../daemon.js');
+        if (!shouldClientEvictSkewedBroker(isDaemonRunning(), (await agentStatus()).length))
             return true;
         await teardownStaleBroker();
     }

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

@@ -4,7 +4,7 @@
  * (bundles.ts).
  *
  * A grant is stored under a scope and read under a scope; the two must agree or
- * the bundle is invisible. `agents secrets unlock --for <agent>` exists to NARROW
+ * the bundle is invisible. `agents secrets unlock --agent <agent>` exists to NARROW
  * a grant to one harness, so an unlock without it is global by definition.
  *
  * This module deliberately has NO imports: agent.ts and session-store.ts already
@@ -13,14 +13,14 @@
  * and throw at runtime even though tsc is happy.
  */
 /**
- * Scope of an unlock that was not narrowed with `--for`: readable by every
+ * Scope of an unlock that was not narrowed with `--agent`: readable by every
  * harness. Not a valid harness name, so it can never collide with one.
  */
 export declare const GLOBAL_HARNESS = "*";
 /**
  * Scopes a reader consults, most specific first: its own harness, then the global
  * grant. This is the resolution order of the scoped-grant model — a narrow
- * `--for claude` unlock stays claude-only while an unscoped unlock serves
+ * `--agent claude` unlock stays claude-only while an unscoped unlock serves
  * everyone — not a fallback papering over a miss.
  */
 export declare function bundleScopeChain(harness: string | undefined): string[];

package/dist/lib/secrets/scope.js

@@ -4,7 +4,7 @@
  * (bundles.ts).
  *
  * A grant is stored under a scope and read under a scope; the two must agree or
- * the bundle is invisible. `agents secrets unlock --for <agent>` exists to NARROW
+ * the bundle is invisible. `agents secrets unlock --agent <agent>` exists to NARROW
  * a grant to one harness, so an unlock without it is global by definition.
  *
  * This module deliberately has NO imports: agent.ts and session-store.ts already
@@ -13,14 +13,14 @@
  * and throw at runtime even though tsc is happy.
  */
 /**
- * Scope of an unlock that was not narrowed with `--for`: readable by every
+ * Scope of an unlock that was not narrowed with `--agent`: readable by every
  * harness. Not a valid harness name, so it can never collide with one.
  */
 export const GLOBAL_HARNESS = '*';
 /**
  * Scopes a reader consults, most specific first: its own harness, then the global
  * grant. This is the resolution order of the scoped-grant model — a narrow
- * `--for claude` unlock stays claude-only while an unscoped unlock serves
+ * `--agent claude` unlock stays claude-only while an unscoped unlock serves
  * everyone — not a fallback papering over a miss.
  */
 export function bundleScopeChain(harness) {

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

@@ -93,10 +93,6 @@ 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

@@ -208,11 +208,6 @@ export function deleteLeaseSession(leaseId) {
     }
     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/{favorites.d.ts → bookmarks.d.ts}

@@ -1,39 +1,39 @@
 /**
- * Favorited (starred) sessions — the durable "keep this one handy" mark a human
- * puts on a session, deliberately kept OUT of the session index.
+ * Bookmarked sessions — the durable "keep this one handy" mark a human puts on a
+ * session, deliberately kept OUT of the session index.
  *
  * `sessions.db` is a rebuildable CACHE: a reindex or a schema bump throws its
- * rows away and re-derives them from the transcripts on disk. A favorite is not
+ * rows away and re-derives them from the transcripts on disk. A bookmark is not
  * derivable from a transcript — it is a human's choice — so a column there would
  * be silently lost on the next rebuild. It lives in `~/.agents/.history/` instead,
  * next to the actor sidecars, which is never pruned.
  *
  * One flat set of session ids. The id is the transcript's own uuid, so it is
  * stable and machine-independent — but the file is NOT synced today: session sync
- * carries `.history/backups/` (`lib/session/sync/agents.ts`), not this. Favorites
+ * carries `.history/backups/` (`lib/session/sync/agents.ts`), not this. Bookmarks
  * are therefore per-machine; carrying them across the fleet would mean adding
  * them to the sync manifest, which this does not do.
  *
- * Reads are memoized against the file's mtime — the picker asks `isFavorite` once
+ * Reads are memoized against the file's mtime — the picker asks `isBookmarked` once
  * per rendered row, and re-reading a JSON file per row on every keystroke is the
  * kind of cost that makes a TUI feel broken.
  */
-export declare function favoritesFilePath(): string;
+export declare function bookmarksFilePath(): string;
 /** Drop the memoized read. Tests that write the file directly need this; nothing
  *  in the CLI does, because every mutation here refreshes the cache itself. */
-export declare function clearFavoritesCache(): void;
+export declare function clearBookmarksCache(): void;
 /**
- * Every favorited session id. Empty (never throws) when the file is absent,
- * unreadable, or malformed — a corrupt favorites file must not take down
+ * Every bookmarked session id. Empty (never throws) when the file is absent,
+ * unreadable, or malformed — a corrupt bookmarks file must not take down
  * `agents sessions`.
  */
-export declare function listFavorites(): Set<string>;
-export declare function isFavorite(sessionId: string | undefined): boolean;
+export declare function listBookmarks(): Set<string>;
+export declare function isBookmarked(sessionId: string | undefined): boolean;
 /**
- * Set (or clear) the favorite mark on a session. Returns the resulting state, so
+ * Set (or clear) the bookmark mark on a session. Returns the resulting state, so
  * a caller can report it without a second read. A no-op write is skipped, which
  * keeps the file's mtime — and every other process's memoized read — untouched.
  */
-export declare function setFavorite(sessionId: string, on: boolean): boolean;
-/** Flip the mark; returns the new state (`true` = now favorited). */
-export declare function toggleFavorite(sessionId: string): boolean;
+export declare function setBookmark(sessionId: string, on: boolean): boolean;
+/** Flip the mark; returns the new state (`true` = now bookmarked). */
+export declare function toggleBookmark(sessionId: string): boolean;

package/dist/lib/session/{favorites.js → bookmarks.js}

@@ -1,28 +1,28 @@
 /**
- * Favorited (starred) sessions — the durable "keep this one handy" mark a human
- * puts on a session, deliberately kept OUT of the session index.
+ * Bookmarked sessions — the durable "keep this one handy" mark a human puts on a
+ * session, deliberately kept OUT of the session index.
  *
  * `sessions.db` is a rebuildable CACHE: a reindex or a schema bump throws its
- * rows away and re-derives them from the transcripts on disk. A favorite is not
+ * rows away and re-derives them from the transcripts on disk. A bookmark is not
  * derivable from a transcript — it is a human's choice — so a column there would
  * be silently lost on the next rebuild. It lives in `~/.agents/.history/` instead,
  * next to the actor sidecars, which is never pruned.
  *
  * One flat set of session ids. The id is the transcript's own uuid, so it is
  * stable and machine-independent — but the file is NOT synced today: session sync
- * carries `.history/backups/` (`lib/session/sync/agents.ts`), not this. Favorites
+ * carries `.history/backups/` (`lib/session/sync/agents.ts`), not this. Bookmarks
  * are therefore per-machine; carrying them across the fleet would mean adding
  * them to the sync manifest, which this does not do.
  *
- * Reads are memoized against the file's mtime — the picker asks `isFavorite` once
+ * Reads are memoized against the file's mtime — the picker asks `isBookmarked` once
  * per rendered row, and re-reading a JSON file per row on every keystroke is the
  * kind of cost that makes a TUI feel broken.
  */
 import fs from 'node:fs';
 import path from 'node:path';
 import { getHistoryDir } from '../state.js';
-export function favoritesFilePath() {
-    return path.join(getHistoryDir(), 'favorites.json');
+export function bookmarksFilePath() {
+    return path.join(getHistoryDir(), 'bookmarks.json');
 }
 /** Memoized parse, invalidated by the file's mtime+size (another process — or
  *  another machine's sync — can rewrite it under us). */
@@ -38,16 +38,16 @@ function statKey(file) {
 }
 /** Drop the memoized read. Tests that write the file directly need this; nothing
  *  in the CLI does, because every mutation here refreshes the cache itself. */
-export function clearFavoritesCache() {
+export function clearBookmarksCache() {
     cache = null;
 }
 /**
- * Every favorited session id. Empty (never throws) when the file is absent,
- * unreadable, or malformed — a corrupt favorites file must not take down
+ * Every bookmarked session id. Empty (never throws) when the file is absent,
+ * unreadable, or malformed — a corrupt bookmarks file must not take down
  * `agents sessions`.
  */
-export function listFavorites() {
-    const file = favoritesFilePath();
+export function listBookmarks() {
+    const file = bookmarksFilePath();
     const key = statKey(file);
     if (cache && cache.key === key)
         return cache.ids;
@@ -64,14 +64,14 @@ export function listFavorites() {
     cache = { key, ids };
     return ids;
 }
-export function isFavorite(sessionId) {
+export function isBookmarked(sessionId) {
     if (!sessionId)
         return false;
-    return listFavorites().has(sessionId);
+    return listBookmarks().has(sessionId);
 }
 /** Atomic write (tmp + rename) so a concurrent reader never sees a half file. */
-function writeFavorites(ids) {
-    const file = favoritesFilePath();
+function writeBookmarks(ids) {
+    const file = bookmarksFilePath();
     fs.mkdirSync(path.dirname(file), { recursive: true });
     const body = { version: 1, sessionIds: [...ids].sort() };
     const tmp = `${file}.${process.pid}.tmp`;
@@ -80,22 +80,22 @@ function writeFavorites(ids) {
     cache = { key: statKey(file), ids };
 }
 /**
- * Set (or clear) the favorite mark on a session. Returns the resulting state, so
+ * Set (or clear) the bookmark mark on a session. Returns the resulting state, so
  * a caller can report it without a second read. A no-op write is skipped, which
  * keeps the file's mtime — and every other process's memoized read — untouched.
  */
-export function setFavorite(sessionId, on) {
-    const ids = new Set(listFavorites());
+export function setBookmark(sessionId, on) {
+    const ids = new Set(listBookmarks());
     if (ids.has(sessionId) === on)
         return on;
     if (on)
         ids.add(sessionId);
     else
         ids.delete(sessionId);
-    writeFavorites(ids);
+    writeBookmarks(ids);
     return on;
 }
-/** Flip the mark; returns the new state (`true` = now favorited). */
-export function toggleFavorite(sessionId) {
-    return setFavorite(sessionId, !isFavorite(sessionId));
+/** Flip the mark; returns the new state (`true` = now bookmarked). */
+export function toggleBookmark(sessionId) {
+    return setBookmark(sessionId, !isBookmarked(sessionId));
 }

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

@@ -28,6 +28,7 @@ export declare const RESOURCE_INDEX_VERSION = 1;
  */
 /** Bump when facet extraction changes so cached rows recompute (stalls-by-model v6). */
 export declare const INSIGHTS_EXTRACTOR_VERSION = 6;
+export declare const PREVIEW_EXTRACTOR_VERSION = 1;
 /** Raw row shape returned from the sessions table. */
 export interface SessionRow {
     id: string;
@@ -390,6 +391,20 @@ export declare function writeSessionInsights<T>(entries: Array<{
 }>): void;
 /** Drop every cached facet row. Backs `agents insights --refresh`. */
 export declare function clearSessionInsights(): void;
+/** Read one derived preview only when it matches the transcript bytes on disk. */
+export declare function readSessionPreviewCache<T>(id: string, sourceStamp: {
+    fileMtimeMs: number | null;
+    fileSize: number | null;
+}): T | undefined;
+/** Persist normalized preview data against the exact transcript bytes parsed. */
+export declare function writeSessionPreviewCache<T>(entry: {
+    id: string;
+    fileMtimeMs: number | null;
+    fileSize: number | null;
+    preview: T;
+}): void;
+/** Plugin provenance already indexed for resources used by one session. */
+export declare function getSessionPlugins(id: string): string[];
 export type UsageRollupGroup = 'agent' | 'project' | 'day' | 'account';
 /**
  * Smart-launch affinity priors: group sessions by origin machine, harness, or

package/dist/lib/session/db.js

@@ -9,7 +9,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import Database from '../sqlite.js';
-import { parseSession } from './parse.js';
+import { parseSession, sessionFilePathContainer } from './parse.js';
 import { extractRecentDirectoriesTouched, extractTodoProgressFromEvents } from './state.js';
 import { getSessionsDir, getSessionsDbPath } from '../state.js';
 import { query as queryEvents, queryToolUsageForSessions } from '../events.js';
@@ -305,6 +305,18 @@ CREATE TABLE IF NOT EXISTS session_insights (
   computed_at INTEGER NOT NULL,
   facets TEXT NOT NULL
 );
+
+-- Normalized data behind sessions preview. Like session_insights this is a
+-- lazy, stamp-validated cache: opening one session parses only that transcript,
+-- while subsequent processes reuse the derived preview until its bytes change.
+CREATE TABLE IF NOT EXISTS session_preview_cache (
+  session_id TEXT PRIMARY KEY,
+  file_mtime_ms INTEGER,
+  file_size INTEGER,
+  extractor_version INTEGER NOT NULL,
+  computed_at INTEGER NOT NULL,
+  preview_json TEXT NOT NULL
+);
 `;
 /**
  * Bumping this invalidates every cached facet row without touching the schema
@@ -314,6 +326,7 @@ CREATE TABLE IF NOT EXISTS session_insights (
  */
 /** Bump when facet extraction changes so cached rows recompute (stalls-by-model v6). */
 export const INSIGHTS_EXTRACTOR_VERSION = 6;
+export const PREVIEW_EXTRACTOR_VERSION = 1;
 let dbInstance = null;
 /**
  * Apply schema migrations from `fromVersion` → SCHEMA_VERSION. The new
@@ -2291,18 +2304,36 @@ function clearSessionExistenceCache() {
     directoryMembershipSweepCount = 0;
 }
 function findMissingFilePaths(filePaths) {
+    // Existence is decided on the CONTAINER file, never the raw stored path. A
+    // composite `file_path` (`<container>#<id>`, e.g. OpenCode's `opencode.db#ses_…`)
+    // names a row INSIDE a shared file — its basename is never a directory entry,
+    // so a dirname/basename membership check on the composite string classified
+    // every such row as deleted and pruned it (RUSH-2357). Group the original
+    // paths under the container we actually stat, and map the verdict back so the
+    // returned set still holds the original `file_path` strings the caller keys on.
     const byDir = new Map();
     for (const p of filePaths) {
-        const dir = path.dirname(p);
-        let basenames = byDir.get(dir);
-        if (!basenames) {
-            basenames = new Set();
-            byDir.set(dir, basenames);
+        const container = sessionFilePathContainer(p);
+        const dir = path.dirname(container);
+        const base = path.basename(container);
+        let bases = byDir.get(dir);
+        if (!bases) {
+            bases = new Map();
+            byDir.set(dir, bases);
         }
-        basenames.add(path.basename(p));
+        let originals = bases.get(base);
+        if (!originals) {
+            originals = [];
+            bases.set(base, originals);
+        }
+        originals.push(p);
     }
     const missing = new Set();
-    for (const [dir, basenames] of byDir) {
+    const markMissing = (originals) => {
+        for (const original of originals)
+            missing.add(original);
+    };
+    for (const [dir, bases] of byDir) {
         let entries;
         try {
             const stat = fs.statSync(dir);
@@ -2324,17 +2355,16 @@ function findMissingFilePaths(filePaths) {
             // Directory itself is gone (or unreadable) — every file in it is missing.
             // Also covers the race where readdir loses to a concurrent delete: fall
             // back to a direct stat rather than assuming existence.
-            for (const base of basenames) {
+            for (const [base, originals] of bases) {
                 const filePath = path.join(dir, base);
                 if (!fs.existsSync(filePath))
-                    missing.add(filePath);
+                    markMissing(originals);
             }
             continue;
         }
-        for (const base of basenames) {
-            const filePath = path.join(dir, base);
+        for (const [base, originals] of bases) {
             if (!entries.has(base))
-                missing.add(filePath);
+                markMissing(originals);
         }
     }
     return missing;
@@ -2471,6 +2501,49 @@ export function writeSessionInsights(entries) {
 export function clearSessionInsights() {
     getDB().exec(`DELETE FROM session_insights`);
 }
+/** Read one derived preview only when it matches the transcript bytes on disk. */
+export function readSessionPreviewCache(id, sourceStamp) {
+    const row = getDB().prepare(`
+    SELECT pc.preview_json AS previewJson
+    FROM session_preview_cache pc
+    WHERE pc.session_id = ?
+      AND pc.extractor_version = ?
+      AND pc.file_mtime_ms IS ?
+      AND pc.file_size IS ?
+  `).get(id, PREVIEW_EXTRACTOR_VERSION, sourceStamp.fileMtimeMs, sourceStamp.fileSize);
+    if (!row)
+        return undefined;
+    try {
+        return JSON.parse(row.previewJson);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Persist normalized preview data against the exact transcript bytes parsed. */
+export function writeSessionPreviewCache(entry) {
+    getDB().prepare(`
+    INSERT INTO session_preview_cache
+      (session_id, file_mtime_ms, file_size, extractor_version, computed_at, preview_json)
+    VALUES (?, ?, ?, ?, ?, ?)
+    ON CONFLICT(session_id) DO UPDATE SET
+      file_mtime_ms = excluded.file_mtime_ms,
+      file_size = excluded.file_size,
+      extractor_version = excluded.extractor_version,
+      computed_at = excluded.computed_at,
+      preview_json = excluded.preview_json
+  `).run(entry.id, entry.fileMtimeMs, entry.fileSize, PREVIEW_EXTRACTOR_VERSION, Date.now(), JSON.stringify(entry.preview));
+}
+/** Plugin provenance already indexed for resources used by one session. */
+export function getSessionPlugins(id) {
+    const rows = getDB().prepare(`
+    SELECT DISTINCT plugin
+    FROM session_resource_usage
+    WHERE session_id = ? AND plugin IS NOT NULL AND plugin <> ''
+    ORDER BY plugin COLLATE NOCASE
+  `).all(id);
+    return rows.map(row => row.plugin);
+}
 export function queryAffinityRollup(options) {
     const db = getDB();
     const where = [];
@@ -2708,7 +2781,9 @@ export function backfillResourceUsage(filter = {}, onProgress) {
         result.scanned++;
         let stamp;
         try {
-            const st = fs.statSync(meta.filePath);
+            // Composite rows (`<container>#<id>`) stat their container file — the
+            // per-session bytes/mtime stamp is derived during discovery, not here.
+            const st = fs.statSync(sessionFilePathContainer(meta.filePath));
             stamp = { fileMtimeMs: st.mtimeMs, fileSize: st.size };
         }
         catch {
@@ -2787,7 +2862,7 @@ export function topSessionsByCost(n, options = {}) {
     // Over-fetch a small buffer to survive the on-disk liveness filter below.
     const sql = `SELECT * FROM sessions ${whereCost} ORDER BY cost_usd DESC, timestamp DESC LIMIT ${limit + 16}`;
     const rows = db.prepare(sql).all(...params);
-    const live = rows.filter(r => !r.file_path || fs.existsSync(r.file_path));
+    const live = rows.filter(r => !r.file_path || fs.existsSync(sessionFilePathContainer(r.file_path)));
     return live.slice(0, limit).map(r => ({
         meta: rowToMeta(r),
         costUsd: r.cost_usd ?? 0,