@phnx-labs/agents-cli 1.20.89 → 1.20.91

package/dist/lib/secrets/list-filter.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Filters for `agents secrets list`.
+ *
+ * The listing had no filtering at all: `--host`/`--device` pick a machine and
+ * `--json` picks a format, but nothing selected over the bundles themselves. On
+ * a fleet with fifty-odd bundles the answerable questions — which ones read with
+ * no Touch ID at all, which hold a raw literal, which have already expired, what
+ * has not been touched in three months — meant piping the table through grep, or
+ * were simply unanswerable.
+ *
+ * Everything here is pure: parsing produces a `SecretsListFilter`, and
+ * `bundleMatchesFilter` is a predicate over a bundle plus the ambient facts it
+ * cannot derive itself (which bundles the broker currently holds, and the
+ * current time). That keeps the whole surface unit-testable without a keychain.
+ *
+ * Shape follows the `agents sessions` house style: comma-separated lists, an
+ * unknown value is a loud error naming the valid set (never a silent ignore),
+ * and every axis narrows independently so they AND-compose.
+ */
+import { type SecretsBundle, type SecretsPolicy, type SecretsBackend, type SecretType } from './bundles.js';
+/** Ref kinds a var's value can have, from `describeBundle`. */
+export declare const REF_KINDS: readonly ["literal", "keychain", "env", "file", "exec"];
+export type RefKind = typeof REF_KINDS[number];
+/** Default window for `--expiring` with no argument — matches the EXPIRING column. */
+export declare const DEFAULT_EXPIRING_DAYS = 30;
+/** A parsed, validated filter. Every field is optional; absent ⇒ that axis does
+ * not narrow. All present axes must match (AND). */
+export interface SecretsListFilter {
+    /** Case-insensitive substring over bundle name and description. */
+    query?: string;
+    policy?: SecretsPolicy[];
+    backend?: SecretsBackend[];
+    type?: SecretType[];
+    kind?: RefKind[];
+    /** true ⇒ only bundles the broker holds; false ⇒ only those it does not. */
+    held?: boolean;
+    /** Only bundles with at least one var whose `expires` is already past. */
+    expired?: boolean;
+    /** Only bundles with at least one var expiring within this many days. */
+    expiringDays?: number;
+    /** Only bundles whose `last_used` is older than this epoch-ms (or never used). */
+    unusedBefore?: number;
+}
+/** The raw option bag commander hands us. */
+export interface SecretsListFilterOpts {
+    policy?: string;
+    backend?: string;
+    type?: string;
+    kind?: string;
+    held?: boolean;
+    notHeld?: boolean;
+    expired?: boolean;
+    expiring?: string | boolean;
+    unused?: string;
+}
+/**
+ * Validate one comma-separated enum list. An unknown value throws and names the
+ * whole valid set — a silent ignore would let `--policy hodl` quietly return
+ * every bundle, which reads as "nothing matches that" and is worse than an error.
+ * Values are lowercased, matching `parsePolicyOpt`'s handling of policy names.
+ */
+export declare function parseEnumList<T extends string>(raw: string, flag: string, valid: readonly T[]): T[];
+/** Build a validated filter from commander's option bag. Throws on bad input. */
+export declare function parseListFilters(opts: SecretsListFilterOpts, query?: string): SecretsListFilter;
+/** True when any axis is set — used to decide whether the empty state should
+ * explain itself rather than claim there are no bundles at all. */
+export declare function filterIsActive(f: SecretsListFilter): boolean;
+/** Expiry tallies for one bundle: how many vars are already past, and how many
+ * fall due within `withinDays`. */
+export declare function bundleExpiry(b: SecretsBundle, now: number, withinDays?: number): {
+    expired: number;
+    soon: number;
+};
+/** Ambient facts a bundle can't answer about itself. */
+export interface FilterContext {
+    /** Bundle name → hold expiry epoch-ms, from the broker. Empty off macOS. */
+    held: Map<string, number>;
+    now: number;
+}
+/** Does this bundle satisfy every set axis? Pure. */
+export declare function bundleMatchesFilter(b: SecretsBundle, f: SecretsListFilter, ctx: FilterContext): boolean;
+/** Sort fields for `--sort`. `name` is the default and matches `listBundles()`. */
+export declare const SORT_FIELDS: readonly ["name", "used", "created", "updated", "expiry"];
+export type SortField = typeof SORT_FIELDS[number];
+export declare function parseSortField(raw: string | undefined): SortField;
+/** Sort a copy. Time fields are most-recent-first (the useful direction for
+ * "what did I touch lately"); `expiry` is soonest-first; ties fall back to name
+ * so the order is stable. */
+export declare function sortBundles(bundles: SecretsBundle[], field: SortField): SecretsBundle[];
+/** Human summary of the active filters, for the empty state. `sessions` only
+ * echoes --project/--all on a miss, which leaves you guessing which flag emptied
+ * the list; naming every active axis is the difference between "nothing matched"
+ * and knowing what to relax. */
+export declare function describeFilter(f: SecretsListFilter): string;

package/dist/lib/secrets/list-filter.js

@@ -0,0 +1,245 @@
+/**
+ * Filters for `agents secrets list`.
+ *
+ * The listing had no filtering at all: `--host`/`--device` pick a machine and
+ * `--json` picks a format, but nothing selected over the bundles themselves. On
+ * a fleet with fifty-odd bundles the answerable questions — which ones read with
+ * no Touch ID at all, which hold a raw literal, which have already expired, what
+ * has not been touched in three months — meant piping the table through grep, or
+ * were simply unanswerable.
+ *
+ * Everything here is pure: parsing produces a `SecretsListFilter`, and
+ * `bundleMatchesFilter` is a predicate over a bundle plus the ambient facts it
+ * cannot derive itself (which bundles the broker currently holds, and the
+ * current time). That keeps the whole surface unit-testable without a keychain.
+ *
+ * Shape follows the `agents sessions` house style: comma-separated lists, an
+ * unknown value is a loud error naming the valid set (never a silent ignore),
+ * and every axis narrows independently so they AND-compose.
+ */
+import { parseCommaSeparatedList } from '../../commands/utils.js';
+// From the leaf module, NOT discover.js — the latter imports `../sqlite.js`, so
+// reaching through it for one parser would pull node:sqlite into every `agents
+// secrets` invocation and print Node's SQLite ExperimentalWarning on stderr.
+import { parseTimeFilter } from '../session/relative-time.js';
+import { describeBundle, bundlePolicy, SECRET_TYPES, } from './bundles.js';
+/** Ref kinds a var's value can have, from `describeBundle`. */
+export const REF_KINDS = ['literal', 'keychain', 'env', 'file', 'exec'];
+const POLICIES = ['always', 'hold', 'never'];
+const BACKENDS = ['keychain', 'file', 'vault'];
+/** Default window for `--expiring` with no argument — matches the EXPIRING column. */
+export const DEFAULT_EXPIRING_DAYS = 30;
+/**
+ * Validate one comma-separated enum list. An unknown value throws and names the
+ * whole valid set — a silent ignore would let `--policy hodl` quietly return
+ * every bundle, which reads as "nothing matches that" and is worse than an error.
+ * Values are lowercased, matching `parsePolicyOpt`'s handling of policy names.
+ */
+export function parseEnumList(raw, flag, valid) {
+    const parts = parseCommaSeparatedList(raw).map((s) => s.toLowerCase());
+    if (parts.length === 0) {
+        throw new Error(`${flag} requires at least one value. Valid values: ${valid.join(', ')}`);
+    }
+    for (const p of parts) {
+        if (!valid.includes(p)) {
+            throw new Error(`Invalid value "${p}" for ${flag}. Valid values: ${valid.join(', ')}`);
+        }
+    }
+    // De-dup so `--policy hold,hold` behaves like `--policy hold`.
+    return [...new Set(parts)];
+}
+/** Parse `--expiring` — a bare flag means the default window, a value means N days. */
+function parseExpiringDays(raw) {
+    if (raw === undefined || raw === false)
+        return undefined;
+    if (raw === true || raw === '')
+        return DEFAULT_EXPIRING_DAYS;
+    const n = Number(raw);
+    // 0 is rejected rather than accepted as a no-op: the window is `0 <= d < N`,
+    // so `--expiring 0` can never match anything, not even a key expiring today.
+    // A flag that silently returns nothing is worse than one that says why.
+    if (!Number.isFinite(n) || !Number.isInteger(n) || n < 1) {
+        throw new Error(`Invalid --expiring '${raw}'. Use a whole number of days >= 1, e.g. --expiring 7. ` +
+            'For keys that have already lapsed, use --expired.');
+    }
+    return n;
+}
+/** Build a validated filter from commander's option bag. Throws on bad input. */
+export function parseListFilters(opts, query) {
+    if (opts.held && opts.notHeld) {
+        throw new Error('--held and --not-held are mutually exclusive');
+    }
+    const filter = {};
+    const trimmedQuery = query?.trim();
+    if (trimmedQuery)
+        filter.query = trimmedQuery.toLowerCase();
+    if (opts.policy)
+        filter.policy = parseEnumList(opts.policy, '--policy', POLICIES);
+    if (opts.backend)
+        filter.backend = parseEnumList(opts.backend, '--backend', BACKENDS);
+    if (opts.type)
+        filter.type = parseEnumList(opts.type, '--type', SECRET_TYPES);
+    if (opts.kind)
+        filter.kind = parseEnumList(opts.kind, '--kind', REF_KINDS);
+    if (opts.held)
+        filter.held = true;
+    if (opts.notHeld)
+        filter.held = false;
+    if (opts.expired)
+        filter.expired = true;
+    const expiringDays = parseExpiringDays(opts.expiring);
+    if (expiringDays !== undefined)
+        filter.expiringDays = expiringDays;
+    if (opts.unused) {
+        // parseTimeFilter turns '90d' into "the epoch-ms 90 days ago"; a bundle is
+        // unused when its last_used predates that instant.
+        const cutoff = parseTimeFilter(opts.unused);
+        if (!cutoff) {
+            throw new Error(`Invalid --unused '${opts.unused}'. Use e.g. 30d, 4w, 3mo, or an ISO date.`);
+        }
+        filter.unusedBefore = cutoff;
+    }
+    return filter;
+}
+/** True when any axis is set — used to decide whether the empty state should
+ * explain itself rather than claim there are no bundles at all. */
+export function filterIsActive(f) {
+    return Object.keys(f).length > 0;
+}
+/** Whole days from now until end-of-day UTC of an ISO date. Negative once past.
+ * Mirrors the `daysUntil` used by the human render so the filter and the column
+ * can never disagree about whether something has expired. */
+function daysUntil(iso, now) {
+    const target = new Date(`${iso}T23:59:59Z`).getTime();
+    return Math.floor((target - now) / (24 * 60 * 60 * 1000));
+}
+/** Expiry tallies for one bundle: how many vars are already past, and how many
+ * fall due within `withinDays`. */
+export function bundleExpiry(b, now, withinDays = DEFAULT_EXPIRING_DAYS) {
+    let expired = 0;
+    let soon = 0;
+    for (const m of Object.values(b.meta ?? {})) {
+        if (!m.expires)
+            continue;
+        const d = daysUntil(m.expires, now);
+        if (d < 0)
+            expired++;
+        else if (d < withinDays)
+            soon++;
+    }
+    return { expired, soon };
+}
+/** Does this bundle satisfy every set axis? Pure. */
+export function bundleMatchesFilter(b, f, ctx) {
+    if (f.query) {
+        const haystack = `${b.name} ${b.description ?? ''}`.toLowerCase();
+        if (!haystack.includes(f.query))
+            return false;
+    }
+    if (f.policy && !f.policy.includes(bundlePolicy(b)))
+        return false;
+    if (f.backend && !f.backend.includes(b.backend ?? 'keychain'))
+        return false;
+    if (f.held !== undefined) {
+        // A lapsed entry is not held — same liveness rule the POLICY column uses.
+        const exp = ctx.held.get(b.name);
+        const isHeld = exp !== undefined && exp > ctx.now;
+        if (isHeld !== f.held)
+            return false;
+    }
+    if (f.type) {
+        const types = Object.values(b.meta ?? {}).map((m) => m.type).filter(Boolean);
+        if (!types.some((t) => f.type.includes(t)))
+            return false;
+    }
+    if (f.kind) {
+        const kinds = describeBundle(b).map((e) => e.kind);
+        if (!kinds.some((k) => f.kind.includes(k)))
+            return false;
+    }
+    if (f.expired || f.expiringDays !== undefined) {
+        const { expired, soon } = bundleExpiry(b, ctx.now, f.expiringDays ?? DEFAULT_EXPIRING_DAYS);
+        if (f.expired && expired === 0)
+            return false;
+        if (f.expiringDays !== undefined && soon === 0)
+            return false;
+    }
+    if (f.unusedBefore !== undefined) {
+        // Never used counts as unused — it is the strongest form of the answer.
+        if (b.last_used && new Date(b.last_used).getTime() >= f.unusedBefore)
+            return false;
+    }
+    return true;
+}
+/** Sort fields for `--sort`. `name` is the default and matches `listBundles()`. */
+export const SORT_FIELDS = ['name', 'used', 'created', 'updated', 'expiry'];
+export function parseSortField(raw) {
+    if (!raw)
+        return 'name';
+    const v = raw.toLowerCase();
+    if (!SORT_FIELDS.includes(v)) {
+        throw new Error(`Invalid --sort '${raw}'. Valid values: ${SORT_FIELDS.join(', ')}`);
+    }
+    return v;
+}
+/** Epoch-ms of a bundle's soonest expiry, or Infinity when nothing expires — so
+ * `--sort expiry` puts the most urgent first and never-expiring bundles last. */
+function soonestExpiry(b) {
+    let soonest = Infinity;
+    for (const m of Object.values(b.meta ?? {})) {
+        if (!m.expires)
+            continue;
+        const t = new Date(`${m.expires}T23:59:59Z`).getTime();
+        if (t < soonest)
+            soonest = t;
+    }
+    return soonest;
+}
+/** Sort a copy. Time fields are most-recent-first (the useful direction for
+ * "what did I touch lately"); `expiry` is soonest-first; ties fall back to name
+ * so the order is stable. */
+export function sortBundles(bundles, field) {
+    const stamp = (iso) => (iso ? new Date(iso).getTime() : 0);
+    const byName = (a, z) => a.name.localeCompare(z.name);
+    const out = [...bundles];
+    if (field === 'name')
+        return out.sort(byName);
+    out.sort((a, z) => {
+        if (field === 'expiry') {
+            const d = soonestExpiry(a) - soonestExpiry(z);
+            return d !== 0 ? d : byName(a, z);
+        }
+        const key = field === 'used' ? 'last_used' : field === 'created' ? 'created_at' : 'updated_at';
+        const d = stamp(z[key]) - stamp(a[key]);
+        return d !== 0 ? d : byName(a, z);
+    });
+    return out;
+}
+/** Human summary of the active filters, for the empty state. `sessions` only
+ * echoes --project/--all on a miss, which leaves you guessing which flag emptied
+ * the list; naming every active axis is the difference between "nothing matched"
+ * and knowing what to relax. */
+export function describeFilter(f) {
+    const parts = [];
+    if (f.query)
+        parts.push(`matching "${f.query}"`);
+    if (f.policy)
+        parts.push(`policy ${f.policy.join('/')}`);
+    if (f.backend)
+        parts.push(`backend ${f.backend.join('/')}`);
+    if (f.type)
+        parts.push(`type ${f.type.join('/')}`);
+    if (f.kind)
+        parts.push(`kind ${f.kind.join('/')}`);
+    if (f.held === true)
+        parts.push('currently held');
+    if (f.held === false)
+        parts.push('not currently held');
+    if (f.expired)
+        parts.push('with an expired key');
+    if (f.expiringDays !== undefined)
+        parts.push(`expiring within ${f.expiringDays}d`);
+    if (f.unusedBefore !== undefined)
+        parts.push('unused since the given cutoff');
+    return parts.join(', ');
+}

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

@@ -6,6 +6,7 @@ import { type SessionAttachment } from './types.js';
 import { type SessionProvenance } from './provenance.js';
 import { type DeviceRegistry } from '../devices/registry.js';
 import { type Presence } from './detached.js';
+import { type HostLink } from './host-link.js';
 /**
  * The owner (actor id) to show for a session in `--active`. Prefers the actor
  * recorded on the live-attribution source (the pid registry / teammate record),
@@ -44,7 +45,11 @@ export type ActiveContext = 'terminal' | 'teams' | 'cloud' | 'headless';
  * antigravity) gets a real working/waiting/idle from its own parser — see
  * {@link computeLiveSignals}, {@link lifecycleStatus} and {@link resolveFallbackStatus}.
  */
-export type ActiveStatus = 'running' | 'idle' | 'queued' | 'input_required' | 'closed' | 'abandoned' | 'unknown';
+export type ActiveStatus = 'running' | 'idle' | 'queued' | 'input_required' | 'closed' | 'abandoned'
+/** Alive, but no client is attached — the host window died and the agent outlived it. */
+ | 'orphaned'
+/** The host window died and took the agent with it — an unclean exit, not a normal close. */
+ | 'crashed' | 'unknown';
 export interface ActiveSession {
     context: ActiveContext;
     kind: string;
@@ -122,6 +127,35 @@ export interface ActiveSession {
      * from the detach store — never asserted by a source.
      */
     presence?: Presence;
+    /**
+     * Whether anything is still on the other end of this session — folded on at the
+     * end of {@link getActiveSessions} by {@link foldHostLink} from the raw signals
+     * below, never asserted by a source. Drives the `orphaned` / `crashed` statuses.
+     */
+    hostLink?: HostLink;
+    /**
+     * Whether this session's process was alive at scan time — the boolean
+     * {@link applyState} already computes, kept rather than thrown away.
+     *
+     * `status` cannot stand in for it. `abandoned` fires on transcript staleness
+     * BEFORE the liveness check, so it covers a live-but-stuck process as well as
+     * a long-dead one; only `closed`/`crashed` are unconditionally dead. A consumer
+     * that must tell "still there, just quiet" from "gone" needs this, not the
+     * status. Absent from cloud rows (no pid) and from a peer running an older CLI.
+     */
+    pidAlive?: boolean;
+    /**
+     * Clients attached to this session's tmux session (`#{session_attached}`), for
+     * a tmux-hosted row. Absent — NOT zero — when the session is not tmux-hosted:
+     * zero means "tmux says nobody is looking", absent means "we cannot tell".
+     */
+    tmuxClients?: number;
+    /**
+     * When the owning IDE window last refreshed its slice of the live-terminals
+     * registry. Absent for a session no IDE window owns. A stale value means that
+     * window is gone — see {@link HOST_HEARTBEAT_STALE_MS}.
+     */
+    windowHeartbeatMs?: number;
     /** How many live PIDs resolve to this same session (subagents/forks). 1 unless collapsed. */
     pidCount?: number;
     /**
@@ -208,6 +242,24 @@ export interface ActiveSession {
         app: string;
         tab?: number;
     };
+    /**
+     * The editor tab that launched this agent (`AGENT_TERMINAL_ID`), from the pid
+     * registry. This is the one identifier that survives an SSH hop AND a session
+     * rotation: a Factory tab offloaded to a device has no local process to inspect,
+     * and its spawn-time session id goes stale the moment the agent moves to another
+     * session (`/clear`, exit-and-rerun), so `--active --host <device>` joined on
+     * this is how that tab re-identifies its own session. Absent for any launch that
+     * did not inherit a terminal id.
+     */
+    terminalId?: string;
+    /**
+     * tmux pane id (`%N`) when this row was discovered via the tmux source AND its
+     * session id could not be resolved (a born-unidentifiable non-Claude pane). It
+     * is the dedupe key for such id-less rows, so two anonymous panes in the same
+     * cwd render as two distinct rows instead of collapsing onto each other. Unset
+     * once a session id resolves (the id is the identity then).
+     */
+    paneId?: string;
 }
 export declare function activeStatusFromCloudStatus(status: CloudTaskStatus): ActiveStatus;
 export interface ActiveQueryOptions {
@@ -238,6 +290,22 @@ export declare const ABANDONED_STALE_MS: number;
  * `.exe` suffix (`claude.exe`), so basename + suffix-strip before the lookup.
  */
 export declare function agentKindFromComm(commRaw: string): string | undefined;
+/** Agent kind from an `ag-<agent>-<shortid>` tmux session name, else undefined. */
+export declare function agentKindFromName(sessName: string): string | undefined;
+/** The 8-char session-id prefix from an `ag-<agent>-<shortid>` name, else undefined. */
+export declare function shortIdFromName(sessName: string): string | undefined;
+/**
+ * Map every `ag-<agent>-<shortid>` tmux session name to its full session UUID in
+ * ONE batched DB lookup. The live scan calls this once per poll (not per pane),
+ * then resolvePaneIdentity reads the map — the recovery that makes a detached
+ * agent findable by `focus <id>` even when its durable identity records are gone.
+ * `findSessionsByShortIds` is injected so this stays unit-testable without a DB.
+ */
+export declare function resolveNamesToSessionIds(sessionNames: string[], deps: {
+    findSessionsByShortIds: (shortIds: string[]) => Map<string, {
+        id: string;
+    }>;
+}): Map<string, string>;
 /**
  * True when `pid` names a live process AND — when a session's recorded
  * `startedAtMs` is supplied — that process is plausibly the SAME one, not a later
@@ -446,11 +514,11 @@ export interface PaneIdentity {
  * `source: 'teams'` panes are skipped — teammates are surfaced by listTeamsActive.
  * Pure so it is unit-tested without tmux.
  */
-export declare function resolvePaneIdentity(pane: string, meta: {
+export declare function resolvePaneIdentity(pane: string, sessName: string, meta: {
     labels?: Record<string, string>;
     source?: string;
     pane?: string;
-} | null, liveEntry: PidSessionEntry | undefined, getHookIndex: () => HookSessionIndex): PaneIdentity | undefined;
+} | null, liveEntry: PidSessionEntry | undefined, getHookIndex: () => HookSessionIndex, nameToFullId: Map<string, string>): PaneIdentity | undefined;
 /**
  * Agents hosted in the shared-socket tmux server — the authoritative source for
  * tmux-hosted interactive spawns (see src/lib/exec.ts `runInTmux`). Enumerates
@@ -471,6 +539,44 @@ export declare function listTmuxAgentSessions(): Promise<ActiveSession[]>;
  * terminal/headless row for the same session id.
  */
 export declare function getActiveSessions(opts?: ActiveQueryOptions): Promise<ActiveSession[]>;
+/**
+ * Fold tmux's attached-client count onto every tmux-hosted row.
+ *
+ * Keyed off `provenance.mux` — which {@link enrichProvenance} has already stamped
+ * on any row whose process env names a tmux pane — rather than off
+ * {@link listTmuxAgentSessions}. That source only emits a row when it can resolve
+ * the pane's agent IDENTITY (launch registry or session meta), and on a machine
+ * where neither resolves it emits nothing at all while the same sessions still
+ * arrive through the terminal/headless sources carrying full tmux provenance.
+ * Hanging the client count off the identity-resolving source would have made the
+ * whole orphan signal silently dead on exactly those machines.
+ *
+ * One `list-panes` per distinct socket, and only when some row is tmux-hosted —
+ * a fleet with no tmux pays nothing. A query failure leaves the count undefined,
+ * which the classifier reads as "cannot tell", never as a false zero.
+ */
+export declare function foldTmuxClients(rows: ActiveSession[]): Promise<void>;
+/**
+ * Fold the host link onto each row and, where it changes the answer, onto the
+ * status. Runs AFTER {@link foldPresence}, because a deliberately backgrounded
+ * session (`presence` `background`/`parked`) is supposed to have no client and
+ * must not be reported as an orphan.
+ *
+ * Precedence is deliberate, and the two new statuses slot in where they add
+ * information rather than destroy it:
+ *
+ *   - `abandoned` wins outright. A days-stale session is already dangling; that
+ *     it also lost its window is not the headline, and it keeps a crashed row
+ *     from lingering as an alert forever.
+ *   - `crashed` REPLACES `closed`. Both mean the process is gone, but `closed`
+ *     reads as a normal exit; `crashed` says the host window went down with it
+ *     and never cleaned up.
+ *   - `orphaned` replaces only `idle` / `input_required`. A session still WORKING
+ *     with nobody watching is a normal headless run, and flagging every one would
+ *     bury the real signal. A session sitting idle — or worse, waiting on a
+ *     question — with no client attached is the stranded case: nobody is coming.
+ */
+export declare function foldHostLink(rows: ActiveSession[]): void;
 /**
  * Resolve each teams row's `orchestratorLabel` from the orchestrator's own row,
  * when that orchestrator session is itself in the active set (it usually is — the