@phnx-labs/agents-cli 1.22.115 → 1.22.116

package/dist/lib/menubar/snapshot.js

@@ -2,7 +2,9 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { buildRoutineListJson } from '../scheduling/routines.js';
 import { backfillActiveRowsFromIndex, isRunningLiveSession, serializeActiveSessionsForJson, serializeSessionsJson } from '../session/active.js';
-import { getConfigValue, loadAutoLaunchPreferences } from '../device-config.js';
+import { getConfigValue, listConfiguredDeviceRoles, loadAutoLaunchPreferences } from '../device-config.js';
+import { filterAutoPool } from '../devices/pool.js';
+import { isFreshDeviceStats, readStatsCache } from '../devices/stats-cache.js';
 import { MENUBAR_MENU_PROPERTIES } from '../config-keys.js';
 import { migrateMenubarPreferencesFromUserDefaults } from './migrate-prefs.js';
 import { loadDevices } from '../devices/registry.js';
@@ -35,12 +37,20 @@ export function buildMenuPreferences() {
  */
 async function buildMenubarDevices() {
     const reg = await loadDevices();
+    const roster = Object.keys(reg);
     // Pass the roster so a fleet-wide default (fleet.defaults.config) reaches
     // devices that have no doc of their own.
-    const prefs = loadAutoLaunchPreferences(Object.keys(reg));
+    const prefs = loadAutoLaunchPreferences(roster);
+    const roles = listConfiguredDeviceRoles(roster);
+    // The placement verdict from the one canonical filter — not a re-implementation
+    // of the role rule (`devices/pool.ts` owns it).
+    const autoEligible = new Set(filterAutoPool(roster, { roles, autoLaunch: prefs }));
+    // Cache read only: no ssh, no probe, so this still rides the existing snapshot
+    // poll (docs/menubar.md: the menu bar must not probe the fleet per render).
+    const stats = readStatsCache();
     const interactiveHost = getConfigValue('interactive.host').value;
     const self = machineId();
-    return Object.keys(reg)
+    return roster
         .sort()
         .map((name) => ({
         name,
@@ -50,8 +60,37 @@ async function buildMenubarDevices() {
         interactive: name === interactiveHost,
         isLocal: name === self,
         preferred: prefs[name]?.preferred === true,
+        role: roles[name] ?? 'unknown',
+        autoEligible: autoEligible.has(name),
+        stats: projectDeviceStats(stats[name]),
     }));
 }
+/**
+ * Project one cached {@link DeviceStats} row into the snapshot shape, or `null`
+ * when the device has no cached reading at all.
+ *
+ * `?? null` rather than a default: an absent number means "not observed", and the
+ * menu renders that as unavailable. A 0 would be indistinguishable from a real
+ * measurement of an idle box or a full disk.
+ */
+export function projectDeviceStats(row) {
+    if (!row)
+        return null;
+    return {
+        reachable: row.reachable,
+        observedAt: new Date(row.fetchedAt).toISOString(),
+        stale: !isFreshDeviceStats(row),
+        cpus: row.ncpu ?? null,
+        memTotalBytes: row.memTotalBytes ?? null,
+        memFreeBytes: row.memFreeBytes ?? null,
+        memPercent: row.memPercent ?? null,
+        diskTotalBytes: row.diskTotalBytes ?? null,
+        diskFreeBytes: row.diskFreeBytes ?? null,
+        diskUsedPercent: row.diskUsedPercent ?? null,
+        loadPercent: row.loadPercent ?? null,
+        specsObservedAt: row.specsFetchedAt ? new Date(row.specsFetchedAt).toISOString() : null,
+    };
+}
 export function readLastWatchdogTick(stateDir = path.join(getRuntimeStateDir(), 'watchdog')) {
     try {
         return JSON.parse(fs.readFileSync(path.join(stateDir, 'last-tick.json'), 'utf-8'));

package/dist/lib/open-url.js

@@ -9,10 +9,10 @@
  * The OS handler has none of that.
  *
  * Before this seam existed, `agents browser navigate` honoured the configured
- * profile and nothing else did: `fleet login`, `devices lease`, `feedback`, and
+ * profile and nothing else did: `devices lease`, `feedback`, and
  * the browser-session artifact opener each shelled straight to `open`/`xdg-open`,
  * so every one of them landed in whatever the OS handler happened to be. This
- * module replaces all of those call sites; do not add a sixth raw `open`.
+ * module replaces all of those call sites; do not add a new raw `open`.
  *
  * Never throws. A viewer that cannot be reached degrades to the OS handler with
  * one stderr line naming the reason, and a total failure returns `via: 'none'`

package/dist/lib/projects.d.ts

@@ -207,6 +207,29 @@ export declare function projectDirsAbs(def: ProjectDef, opts: {
  * home-relative variant lands (see docs/concepts.md).
  */
 export declare function projectNameForCwd(cwd: string | undefined, defs: ProjectDef[]): string | undefined;
+export declare function listProjectDefsCached(): ProjectDef[];
+/** Drop the {@link listProjectDefsCached} memo — for tests that rewrite the dir within one mtime tick. */
+export declare function resetProjectDefsCache(): void;
+/**
+ * The **confirmed** project for a working directory, or `undefined` when the
+ * association is not confirmed (PHNX-3999 F08/F09).
+ *
+ * Confirmed means exactly one thing: a registered project definition
+ * ({@link projectNameForCwd}) whose root contains this path. Being inside *some*
+ * git repository is NOT a project association — a repo nobody registered, a
+ * checkout of someone else's code, or a loose directory that merely has a
+ * `.git` in it would each invent a project name out of a folder, which is the
+ * wrong-grouping the owner's recording shows at 01:30–01:56. So is a bare
+ * directory basename ({@link resolveProjectKey}, which always answers).
+ *
+ * A consumer renders `undefined` as Uncategorized and keeps the session
+ * reachable in its full list — nothing is hidden by not being grouped.
+ *
+ * Use {@link resolveProjectNameForCwd} instead when you want a best-effort
+ * bucket KEY for joining rows; use this when the answer is shown to a person as
+ * "this work belongs to that project".
+ */
+export declare function confirmedProjectForCwd(cwd: string | undefined | null, defs?: ProjectDef[]): string | undefined;
 /**
  * The canonical project label for a cwd, for every surface that buckets work by
  * project (the activity timeline, feed posts, the sessions overview): the

package/dist/lib/projects.js

@@ -455,6 +455,84 @@ export function projectNameForCwd(cwd, defs) {
     }
     return best ?? weakBest;
 }
+/**
+ * Definition list, memoized against a stamp over the definition FILES, for the
+ * per-tick readers (PHNX-3999).
+ *
+ * {@link listProjectDefs} parses every `<name>.yaml`, which is the right cost for
+ * a command but not for a row builder on the `feed watch` / `sessions watch`
+ * stream — that runs twice a second for as long as an editor window is open (see
+ * `AGENTS.md`, every tick is budgeted). One `readdir` plus one `stat` per
+ * definition replaces N YAML parses.
+ *
+ * The stamp is each file's name + mtime + size, NOT the directory's mtime: editing
+ * a definition in place — retargeting a project's `root`, which is exactly what
+ * changes which sessions belong to it — moves the FILE's mtime and leaves the
+ * directory's untouched, so a directory stamp would serve a stale association for
+ * the life of the process. An unreadable directory is not cached: the next call
+ * retries.
+ */
+let projectDefsMemo = null;
+function projectDefsStamp() {
+    try {
+        const dir = getProjectsDir();
+        const files = fs.readdirSync(dir).filter((f) => f.endsWith('.yaml')).sort();
+        return files
+            .map((f) => {
+            try {
+                const st = fs.statSync(path.join(dir, f));
+                return `${f}:${st.mtimeMs}:${st.size}`;
+            }
+            catch {
+                // Removed between readdir and stat — its absence is part of the stamp.
+                return `${f}:gone`;
+            }
+        })
+            .join('\n');
+    }
+    catch {
+        return null;
+    }
+}
+export function listProjectDefsCached() {
+    const stamp = projectDefsStamp();
+    // No projects dir (or unreadable): nothing is confirmed, and nothing to cache.
+    if (stamp === null)
+        return [];
+    if (projectDefsMemo && projectDefsMemo.stamp === stamp)
+        return projectDefsMemo.defs;
+    const defs = listProjectDefs();
+    projectDefsMemo = { stamp, defs };
+    return defs;
+}
+/** Drop the {@link listProjectDefsCached} memo — for tests that rewrite the dir within one mtime tick. */
+export function resetProjectDefsCache() {
+    projectDefsMemo = null;
+}
+/**
+ * The **confirmed** project for a working directory, or `undefined` when the
+ * association is not confirmed (PHNX-3999 F08/F09).
+ *
+ * Confirmed means exactly one thing: a registered project definition
+ * ({@link projectNameForCwd}) whose root contains this path. Being inside *some*
+ * git repository is NOT a project association — a repo nobody registered, a
+ * checkout of someone else's code, or a loose directory that merely has a
+ * `.git` in it would each invent a project name out of a folder, which is the
+ * wrong-grouping the owner's recording shows at 01:30–01:56. So is a bare
+ * directory basename ({@link resolveProjectKey}, which always answers).
+ *
+ * A consumer renders `undefined` as Uncategorized and keeps the session
+ * reachable in its full list — nothing is hidden by not being grouped.
+ *
+ * Use {@link resolveProjectNameForCwd} instead when you want a best-effort
+ * bucket KEY for joining rows; use this when the answer is shown to a person as
+ * "this work belongs to that project".
+ */
+export function confirmedProjectForCwd(cwd, defs = listProjectDefsCached()) {
+    if (!cwd)
+        return undefined;
+    return projectNameForCwd(cwd, defs);
+}
 /**
  * The canonical project label for a cwd, for every surface that buckets work by
  * project (the activity timeline, feed posts, the sessions overview): the

package/dist/lib/secrets-cli.d.ts

@@ -1,9 +1,9 @@
 export declare const SECRETS_CLI_NAME = "secrets";
 export declare const SECRETS_CLI_PACKAGE = "@phnx-labs/secrets-cli";
 /** Published standalone `agents setup secrets` installs; bump with the protocol. */
-export declare const SECRETS_CLI_VERSION = "0.1.4";
-export declare const SECRETS_CLI_SPEC = "@phnx-labs/secrets-cli@0.1.4";
-export declare const SECRETS_CLI_INSTALL_HINT = "npm i -g @phnx-labs/secrets-cli@0.1.4";
+export declare const SECRETS_CLI_VERSION = "0.1.5";
+export declare const SECRETS_CLI_SPEC = "@phnx-labs/secrets-cli@0.1.5";
+export declare const SECRETS_CLI_INSTALL_HINT = "npm i -g @phnx-labs/secrets-cli@0.1.5";
 /**
  * True when `$SECRETS_BIN` is set or a real `secrets` executable is on PATH
  * outside agents-cli's shims dir. Does not spawn the binary.

package/dist/lib/secrets-cli.js

@@ -15,7 +15,7 @@ import { findInPath } from './agent-spec/agents.js';
 export const SECRETS_CLI_NAME = 'secrets';
 export const SECRETS_CLI_PACKAGE = '@phnx-labs/secrets-cli';
 /** Published standalone `agents setup secrets` installs; bump with the protocol. */
-export const SECRETS_CLI_VERSION = '0.1.4';
+export const SECRETS_CLI_VERSION = '0.1.5';
 export const SECRETS_CLI_SPEC = `${SECRETS_CLI_PACKAGE}@${SECRETS_CLI_VERSION}`;
 export const SECRETS_CLI_INSTALL_HINT = `npm i -g ${SECRETS_CLI_SPEC}`;
 /**

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

@@ -71,6 +71,7 @@ export declare function activeSessionProjectKey(s: Pick<ActiveSession, 'cwd' | '
 export declare function serializeActiveSessionsForJson(sessions: ActiveSession[]): Array<Omit<ActiveSession, 'viewingIn'> & {
     ticketId: string | null;
     project: string;
+    confirmedProject: string | null;
     prLink: string | null;
     viewingIn: string | null;
 }>;

package/dist/lib/session/active.js

@@ -38,6 +38,7 @@ import { computeTokPerSec } from './throughput.js';
 import { inferSessionState } from './state.js';
 import { isSessionTrackedAgent, SESSION_AGENTS, AG_TMUX_NAME_RE } from './types.js';
 import { AGENTS } from '../agents.js';
+import { confirmedProjectForCwd, listProjectDefsCached } from '../projects.js';
 import { detectProvenance } from './provenance.js';
 import { loadDevices } from '../devices/registry.js';
 import { machineId, normalizeHost } from '../machine-id.js';
@@ -227,10 +228,17 @@ export function activeSessionProjectKey(s) {
     return s.context === 'cloud' ? 'cloud' : 'other';
 }
 export function serializeActiveSessionsForJson(sessions) {
+    // One definition read for the whole batch, not per row (PHNX-3999 F08/F09).
+    const defs = listProjectDefsCached();
     return sessions.map((s) => ({
         ...s,
         ticketId: s.ticket?.id ?? null,
         project: activeSessionProjectKey(s),
+        // The project a person is shown this row under, or null for Uncategorized.
+        // `project` above is the always-present join KEY (basename of the cwd, or the
+        // explicit cloud/other bucket) and stays exactly as it was — grouping by it is
+        // what filed unbound directories as projects of their own.
+        confirmedProject: confirmedProjectForCwd(s.cwd, defs) ?? null,
         prLink: s.pr?.url ?? null,
         viewingIn: viewingInLabel(s) ?? null,
     }));

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

@@ -31,8 +31,13 @@ export declare const SCHEMA_VERSION = 50;
  * v4 (PHNX-3621 leftover) invalidates Grok rows stamped before the bounded
  * chat_history.jsonl prefix read filled firstUserMessage.
  * v5 (PHNX-3939) restores first-meta Codex fork ownership, including cold files.
+ * v6 (PHNX-3999) invalidates rows whose stored `label` is harness scaffolding — a
+ * `<bash-input>` shell echo, a `<command-name>` wrapper, a bare `/clear` — which
+ * `cleanGeneratedSessionLabel` now rejects. The label is written at index time, so
+ * without this bump every already-indexed session keeps showing the junk title
+ * until its transcript happens to change.
  */
-export declare const CONTENT_INDEX_VERSION = 5;
+export declare const CONTENT_INDEX_VERSION = 6;
 /**
  * Bumping this invalidates every cached facet row without touching the schema
  * version, so a change to the extraction logic (a new metric, a corrected bucket)
@@ -106,7 +111,9 @@ export interface QueryOptions {
     plugin?: string;
 }
 /** Open (or return the cached) sessions database, applying migrations as needed. */
-export declare function getDB(): Database.Database;
+export declare function getDB(initialBusyTimeoutMs?: number): Database.Database;
+/** Bound synchronous cache contention without changing other database callers. */
+export declare function withSessionDBTimeout<T>(timeoutMs: number, operation: () => T): T;
 /** Close the cached database connection. */
 export declare function closeDB(): void;
 interface FtsOptimizeResult {
@@ -428,6 +435,60 @@ export declare function writeSessionPreviewCache<T>(entry: {
     fileSize: number | null;
     preview: T;
 }): void;
+/** Bump when the cached remote preview envelope shape changes so cached rows recompute (PHNX-3999 v1). */
+export declare const REMOTE_PREVIEW_SCHEMA_VERSION = 1;
+/**
+ * Per-envelope cache-write cap. The bounded fields above make a well-formed
+ * envelope small; this exists to refuse an outlier (a version-skewed peer, or
+ * a future field that forgets to bound itself) rather than let ONE session
+ * blow the total budget. A refused write is NOT an error — the caller still
+ * gets the live envelope for this call, it simply is not persisted, so the
+ * next call re-fetches instead of silently caching a giant blob.
+ */
+export declare const REMOTE_PREVIEW_ENVELOPE_MAX_BYTES: number;
+export interface RemotePreviewCacheRow {
+    /** When the envelope currently stored here (if `ok`) was fetched. */
+    fetchedAt: number;
+    /** Whether `envelope` is a real, successfully-fetched payload. */
+    ok: boolean;
+    envelope?: unknown;
+    failureReason?: string;
+    consecutiveFailures: number;
+    /** Epoch ms before which a fresh fetch attempt should be skipped (negative backoff). */
+    nextAttemptAt: number;
+    /** The caller's own last-observed `--revision` cursor, or undefined if no
+     * caller has ever supplied one for this (device, sessionId) pair. */
+    lastCallerRevision?: string;
+}
+/** Read the durable cached remote preview row for one (device, sessionId) pair,
+ * regardless of whether it currently holds a successful envelope. Undefined
+ * means this box has never attempted (or recorded) a fetch for that pair. */
+export declare function readRemotePreviewCache(device: string, sessionId: string): RemotePreviewCacheRow | undefined;
+/**
+ * Record the caller's own `--revision` cursor for one (device, sessionId)
+ * pair, independent of any fetch. A no-op if no row exists yet (nothing to
+ * compare against on a session this box has never fetched). This is what lets
+ * "same revision as last time" serve the durable cache with zero SSH
+ * indefinitely — the comparison is against THIS value, never against the
+ * envelope's own `details.sourceRevision` (which may be a different format).
+ */
+export declare function writeRemotePreviewCallerRevision(device: string, sessionId: string, revision: string): void;
+/**
+ * Record a successful remote fetch: replaces the payload and resets backoff.
+ * An envelope over {@link REMOTE_PREVIEW_ENVELOPE_MAX_BYTES} is refused —
+ * this is a write-path bound, not a request failure: the caller already has
+ * the live envelope for this call from the fetch that produced it, this only
+ * decides whether it is worth persisting.
+ */
+export declare function writeRemotePreviewCacheSuccess(device: string, sessionId: string, envelope: unknown, fetchedAt?: number, revision?: string): void;
+/**
+ * Record a failed remote fetch attempt with exponential backoff, WITHOUT
+ * discarding a prior good envelope — a session that answered once and is now
+ * offline still degrades to that last-good payload (read back via
+ * {@link readRemotePreviewCache}'s `ok`/`envelope`), annotated stale by the
+ * caller, rather than losing it the moment one attempt fails.
+ */
+export declare function writeRemotePreviewCacheFailure(device: string, sessionId: string, reason: string, backoffMs: (consecutiveFailures: number) => number, now?: number): void;
 /**
  * The session's durable user-turn text, as stored in the `session_text` FTS
  * `content` column at scan time (all harnesses, keyed by session_id). This is
@@ -510,7 +571,10 @@ export declare function readSessionTimelineEntry(id: string): SessionTimelineCac
  * read path. Deliberately does NOT parse the resume state: a live row needs the
  * 8 steps and the request, never the fold's bookkeeping.
  */
-export declare function readSessionTimelineAny(id: string): SessionTimelineProjection | undefined;
+export declare function readSessionTimelineAny(id: string, stamp?: {
+    fileMtimeMs: number;
+    fileSize: number;
+}): SessionTimelineProjection | undefined;
 /** Persist a folded timeline against the exact transcript bytes it was folded to. */
 export declare function writeSessionTimeline(entry: {
     id: string;