@phnx-labs/agents-cli 1.20.78 → 1.20.82

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

@@ -43,12 +43,17 @@ export declare function isDangerousRemoteEnvKey(name: string): boolean;
  */
 export declare function resolveHostSshTarget(nameOrAlias: string): Promise<string>;
 /**
- * Merge `--host <single>` and `--hosts <a,b,c>` into an ordered, de-duplicated
- * list. Both flags compose; either alone works. Empty when neither is set.
+ * Merge `--host <single>` / `--hosts <a,b,c>` (and their `--device` / `--devices`
+ * aliases) into an ordered, de-duplicated list. All four flags compose; any alone
+ * works. `--device`/`--devices` resolve identically to `--host`/`--hosts` so the
+ * fleet-wide `--device` vocabulary (see `agents activity`, `agents run --device`)
+ * works on the secrets remote commands too. Empty when none is set.
  */
 export declare function parseHostsOption(opts: {
     host?: string;
     hosts?: string;
+    device?: string;
+    devices?: string;
 }): string[];
 /**
  * Split a `bundle@host` reference. No `@` → a local bundle (host undefined).
@@ -104,3 +109,71 @@ export declare function remoteSecretsStream(target: string, args: string[], opts
 export declare function remoteResolveEnv(target: string, bundle: string, opts?: {
     osLookupName?: string;
 }): Promise<Record<string, string>>;
+/**
+ * Outcome of a post-push read-back verification (see verifyRemoteKeychainPush).
+ *   - `ok`               — the pushed keys materialized readably on the remote.
+ *   - `locked-keychain`  — the read-back gave the SPECIFIC signal of a keychain
+ *                          that didn't persist (the remote's headless "not unlocked
+ *                          in the secrets agent" guard, or a "stored item … not
+ *                          found" on read-back, or pushed keys simply absent). Only
+ *                          this verdict earns the locked-login-keychain diagnosis +
+ *                          `--remote-backend file` steer.
+ *   - `error`            — a DIFFERENT failure (flaky SSH, timeout, unparseable
+ *                          payload). The raw error is re-surfaced verbatim, never
+ *                          mislabeled as a locked keychain.
+ */
+export type RemoteKeychainWriteVerification = {
+    ok: true;
+} | {
+    ok: false;
+    kind: 'locked-keychain';
+    reason: string;
+} | {
+    ok: false;
+    kind: 'error';
+    reason: string;
+};
+/**
+ * Decide whether a keychain-backed push to a remote actually PERSISTED its secret
+ * value items, given the read-back of that bundle from the remote's own store.
+ *
+ * The silent-failure this guards: pushing `--remote-backend keychain` (default) to
+ * a macOS host over headless SSH lands the bundle METADATA but not readable value
+ * items — the remote login keychain is locked in the non-interactive SSH context,
+ * so Security accepts the item WRITE at the DB level but the biometry-ACL'd item is
+ * unreadable, and the remote `import` still reports success (values written first,
+ * metadata `noAcl` last — bundles.ts writeBundleWithItems). The metadata-only bundle
+ * then fails every later read with the confusing `Bundle '<b>' key '<k>': stored
+ * item '<item>' not found` (bundles.ts resolveBundleEnv). We catch it by reading
+ * the bundle back the same way a release will (`secrets export --plaintext --format
+ * json`, driven headlessly on the remote so its `agentOnly` guard FAILS FAST before
+ * any keychain read — no Touch ID prompt) and confirming every pushed key returned.
+ *
+ * Pure so both branches are unit-testable without a real locked keychain: inject the
+ * "read-back failed / key absent" condition through `readBack`.
+ */
+export declare function evaluateKeychainWriteVerification(pushedKeys: string[], readBack: {
+    ok: true;
+    keys: string[];
+} | {
+    ok: false;
+    stderr: string;
+}): RemoteKeychainWriteVerification;
+/**
+ * The actionable error message for a failed keychain-over-SSH push verification.
+ * Names the cause (locked remote login keychain) and steers to the two real fixes:
+ * re-run with the headless-readable file backend, or unlock the remote keychain.
+ * Pure + exported so the exact guidance is asserted in tests.
+ */
+export declare function keychainWriteFailureMessage(host: string, bundle: string, reason: string): string;
+/**
+ * Read a bundle back from a remote over SSH (headlessly, so it fails fast rather
+ * than prompting Touch ID) and confirm the pushed keys materialized. Drives the
+ * remote's own `secrets export <bundle> --plaintext --format json` — the same read
+ * a headless release performs — but keeps only the KEY NAMES; the plaintext values
+ * are dropped immediately and never retained or logged. Returns a verification
+ * verdict; the caller renders `keychainWriteFailureMessage` on failure.
+ */
+export declare function verifyRemoteKeychainPush(target: string, bundle: string, pushedKeys: string[], opts?: {
+    osLookupName?: string;
+}): RemoteKeychainWriteVerification;

package/dist/lib/secrets/remote.js

@@ -17,7 +17,7 @@
  */
 import { sshExec, sshStream, assertValidSshTarget } from '../ssh-exec.js';
 import { resolveHost } from '../hosts/registry.js';
-import { emit } from '../events.js';
+import { emitSecretAudit } from './audit.js';
 import { sshTargetFor } from '../hosts/types.js';
 import { buildRemoteAgentsInvocation } from '../hosts/remote-cmd.js';
 import { resolveRemoteOsSync } from '../hosts/remote-os.js';
@@ -74,8 +74,11 @@ export async function resolveHostSshTarget(nameOrAlias) {
     return nameOrAlias;
 }
 /**
- * Merge `--host <single>` and `--hosts <a,b,c>` into an ordered, de-duplicated
- * list. Both flags compose; either alone works. Empty when neither is set.
+ * Merge `--host <single>` / `--hosts <a,b,c>` (and their `--device` / `--devices`
+ * aliases) into an ordered, de-duplicated list. All four flags compose; any alone
+ * works. `--device`/`--devices` resolve identically to `--host`/`--hosts` so the
+ * fleet-wide `--device` vocabulary (see `agents activity`, `agents run --device`)
+ * works on the secrets remote commands too. Empty when none is set.
  */
 export function parseHostsOption(opts) {
     const out = [];
@@ -89,9 +92,14 @@ export function parseHostsOption(opts) {
     };
     if (opts.host)
         push(opts.host);
+    if (opts.device)
+        push(opts.device);
     if (opts.hosts)
         for (const h of opts.hosts.split(','))
             push(h);
+    if (opts.devices)
+        for (const h of opts.devices.split(','))
+            push(h);
     return out;
 }
 /**
@@ -203,8 +211,8 @@ export async function remoteResolveEnv(target, bundle, opts = {}) {
     // event on the INITIATING host too (values were pulled into this process and
     // injected locally). Covers `secrets exec --host` and `run --secrets b@host`.
     // Values never enter the payload — only the bundle, target host, and count.
-    emit('secrets.get', {
-        module: 'secrets',
+    emitSecretAudit({
+        event: 'secrets.get',
         bundle,
         operation: 'remote resolve',
         source: 'remote',
@@ -214,3 +222,129 @@ export async function remoteResolveEnv(target, bundle, opts = {}) {
     });
     return env;
 }
+/**
+ * The remote's headless read-back raises one of these when a keychain-backed bundle
+ * has metadata but no readable value items — the exact locked-login-keychain
+ * signature. Anything else (connection refused, timeout, host key error) is a
+ * transient/unrelated failure and must NOT be mislabeled as a locked keychain.
+ */
+function isLockedKeychainReadBackError(stderr) {
+    const s = stderr.toLowerCase();
+    return (
+    // bundles.ts agentOnly guard: "…is not unlocked in the secrets agent…"
+    s.includes('not unlocked') ||
+        s.includes('secrets agent') ||
+        // resolveBundleEnv: "Bundle '<b>' key '<k>': stored item '<item>' not found."
+        s.includes('stored item') ||
+        s.includes('not found'));
+}
+/**
+ * Decide whether a keychain-backed push to a remote actually PERSISTED its secret
+ * value items, given the read-back of that bundle from the remote's own store.
+ *
+ * The silent-failure this guards: pushing `--remote-backend keychain` (default) to
+ * a macOS host over headless SSH lands the bundle METADATA but not readable value
+ * items — the remote login keychain is locked in the non-interactive SSH context,
+ * so Security accepts the item WRITE at the DB level but the biometry-ACL'd item is
+ * unreadable, and the remote `import` still reports success (values written first,
+ * metadata `noAcl` last — bundles.ts writeBundleWithItems). The metadata-only bundle
+ * then fails every later read with the confusing `Bundle '<b>' key '<k>': stored
+ * item '<item>' not found` (bundles.ts resolveBundleEnv). We catch it by reading
+ * the bundle back the same way a release will (`secrets export --plaintext --format
+ * json`, driven headlessly on the remote so its `agentOnly` guard FAILS FAST before
+ * any keychain read — no Touch ID prompt) and confirming every pushed key returned.
+ *
+ * Pure so both branches are unit-testable without a real locked keychain: inject the
+ * "read-back failed / key absent" condition through `readBack`.
+ */
+export function evaluateKeychainWriteVerification(pushedKeys, readBack) {
+    if (!readBack.ok) {
+        const stderr = readBack.stderr.trim();
+        if (isLockedKeychainReadBackError(stderr)) {
+            // The remote's own headless read raised the not-unlocked / not-found signal —
+            // exactly the confusing error the user hits later. Surface it now, at push
+            // time, with the fix.
+            return {
+                ok: false,
+                kind: 'locked-keychain',
+                reason: `the remote could not read it back${stderr ? ` (${stderr})` : ''}`,
+            };
+        }
+        // A transient / unrelated failure (flaky SSH, timeout, bad payload). Re-surface
+        // verbatim — do NOT diagnose a locked keychain from a connection error.
+        return {
+            ok: false,
+            kind: 'error',
+            reason: stderr || 'read-back failed',
+        };
+    }
+    const present = new Set(readBack.keys);
+    const missing = pushedKeys.filter((k) => !present.has(k));
+    if (missing.length > 0) {
+        // Read-back succeeded but some pushed keys are absent — the value items didn't
+        // persist. Same locked-keychain cause and fix.
+        return {
+            ok: false,
+            kind: 'locked-keychain',
+            reason: `${missing.length} of ${pushedKeys.length} key(s) did not persist on the remote ` +
+                `(missing: ${missing.slice(0, 5).join(', ')}${missing.length > 5 ? ', …' : ''})`,
+        };
+    }
+    return { ok: true };
+}
+/**
+ * The actionable error message for a failed keychain-over-SSH push verification.
+ * Names the cause (locked remote login keychain) and steers to the two real fixes:
+ * re-run with the headless-readable file backend, or unlock the remote keychain.
+ * Pure + exported so the exact guidance is asserted in tests.
+ */
+export function keychainWriteFailureMessage(host, bundle, reason) {
+    return (`${host}: pushed '${bundle}' but the keychain items did not persist — ${reason}. ` +
+        `A macOS login keychain is LOCKED under headless SSH, so a keychain-backed write ` +
+        `lands the bundle metadata but no readable secret items, and later reads fail with ` +
+        `"stored item '…' not found". Re-run with a headless-readable backend:\n` +
+        `    agents secrets export ${bundle} --host ${host} --remote-backend file\n` +
+        `(needs AGENTS_SECRETS_PASSPHRASE set locally), or unlock the remote keychain first ` +
+        `(e.g. an interactive login / \`agents secrets unlock\` on ${host}) and retry.`);
+}
+/**
+ * Read a bundle back from a remote over SSH (headlessly, so it fails fast rather
+ * than prompting Touch ID) and confirm the pushed keys materialized. Drives the
+ * remote's own `secrets export <bundle> --plaintext --format json` — the same read
+ * a headless release performs — but keeps only the KEY NAMES; the plaintext values
+ * are dropped immediately and never retained or logged. Returns a verification
+ * verdict; the caller renders `keychainWriteFailureMessage` on failure.
+ */
+export function verifyRemoteKeychainPush(target, bundle, pushedKeys, opts = {}) {
+    const remoteCmd = buildRemoteAgentsInvocation(['secrets', 'export', bundle, '--plaintext', '--format', 'json'], undefined, osForTarget(target, opts.osLookupName));
+    const res = sshExec(target, remoteCmd, { timeoutMs: REMOTE_TIMEOUT_MS });
+    if (res.code !== 0) {
+        const why = res.timedOut ? 'timed out' : res.code === null ? 'ssh failed' : `exit ${res.code}`;
+        const stderr = `${why}${(res.stderr || res.stdout || '').trim() ? `: ${(res.stderr || res.stdout).trim()}` : ''}`;
+        return evaluateKeychainWriteVerification(pushedKeys, { ok: false, stderr });
+    }
+    // Take the outer { … } object (tolerate login-shell banner noise), read the key
+    // names, and immediately discard the values — we only need presence here.
+    const raw = res.stdout;
+    const start = raw.indexOf('{');
+    const end = raw.lastIndexOf('}');
+    const jsonText = start >= 0 && end >= start ? raw.slice(start, end + 1) : raw.trim();
+    let keys;
+    try {
+        const parsed = JSON.parse(jsonText);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return evaluateKeychainWriteVerification(pushedKeys, {
+                ok: false,
+                stderr: 'unexpected read-back payload',
+            });
+        }
+        keys = Object.keys(parsed);
+    }
+    catch {
+        return evaluateKeychainWriteVerification(pushedKeys, {
+            ok: false,
+            stderr: 'could not parse read-back JSON',
+        });
+    }
+    return evaluateKeychainWriteVerification(pushedKeys, { ok: true, keys });
+}

package/dist/lib/secrets/sync.js

@@ -14,7 +14,7 @@ import * as crypto from 'crypto';
 import { deleteKeychainToken, getKeychainToken, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from './index.js';
 import { readBundle, writeBundle, keychainItemsForBundle, validateBundleName, } from './bundles.js';
 import { rushSyncBackend } from './drivers/rush.js';
-import { emit } from '../events.js';
+import { emitSecretAudit } from './audit.js';
 // PBKDF2 cost. 600k SHA-256 iters matches OWASP 2023+ guidance and keeps a
 // passphrase prompt under a second on the hardware the CLI targets.
 const PBKDF2_ITER = 600_000;
@@ -190,8 +190,8 @@ export async function pushBundle(name, opts) {
     // bundle off-machine — the most sensitive read there is. It bypasses
     // readAndResolveBundleEnv, so audit it explicitly. Values never enter the
     // payload; only the bundle name and how many keys were read.
-    emit('secrets.get', {
-        module: 'secrets',
+    emitSecretAudit({
+        event: 'secrets.get',
         bundle: name,
         operation: 'sync push',
         source: 'sync-push',

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

@@ -1,11 +1,20 @@
 import type { CloudTaskStatus } from '../cloud/types.js';
 import { type PidSessionEntry } from './pid-registry.js';
 import { type HookSessionIndex } from './hook-sessions.js';
-import { type SessionActivity, type AwaitingReason, type StructuredQuestion, type TodoProgress, type DetectedPr, type DetectedWorktree, type DetectedTicket } from './state.js';
-import type { SessionAttachment } from './types.js';
+import { type SessionState, type SessionActivity, type AwaitingReason, type StructuredQuestion, type TodoProgress, type DetectedPr, type DetectedWorktree, type DetectedTicket } from './state.js';
+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';
+/**
+ * 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),
+ * but falls back to the durable per-session actor sidecar — written at spawn and,
+ * unlike the pid entry, NOT overwritten by the SessionStart hook's own by-pid
+ * write. Without this fallback a real `agents run` shows no owner whenever the
+ * hook's actor-less entry wins the by-pid file (RUSH-2018 fix).
+ */
+export declare function resolveOwner(pidActor: string | null | undefined, sessionId: string | undefined): string | undefined;
 /**
  * Per-PID `lsof` probes run bounded and staggered rather than as one parallel
  * fan-out: a simultaneous system-wide `lsof` burst reads to behavioral EDR
@@ -15,14 +24,27 @@ import { type Presence } from './detached.js';
 export declare const LSOF_CONCURRENCY = 4;
 export type ActiveContext = 'terminal' | 'teams' | 'cloud' | 'headless';
 /**
- * `unknown` = the process is alive but we cannot introspect what it is doing —
- * a live harness whose transcript format we do not parse (everything but
- * claude/codex), or a resolvable transcript whose `stat` momentarily failed. It
- * is NOT a synonym for idle: idle is a positive "not mid-turn, not waiting on
- * you" conclusion drawn from a readable transcript; unknown is the honest "we
- * can't tell", which we refuse to fake as idle.
+ * Every status here is COMPUTED by the framework from observable signals — PID
+ * liveness and transcript last-write (mtime) — never self-reported by the agent.
+ *
+ *   - `running` / `idle` / `input_required` — a live process's working / stopped
+ *     / waiting-on-you activity, from its transcript (see {@link computeLiveSignals}).
+ *   - `queued` — dispatched, work in the pipeline (cloud/headless launch).
+ *   - `closed` — the PID is dead. The process has exited; report that, don't
+ *     fabricate `idle` ("done, waiting for you") for a process that is simply gone.
+ *   - `abandoned` — no transcript write in {@link ABANDONED_STALE_MS} (days): the
+ *     session is dangling, whether its PID is dead (long gone) or still alive but
+ *     stuck making no progress. A soft signal — it clears the moment it writes again.
+ *   - `unknown` — the residual: genuinely NO signal (no PID info AND no file).
+ *
+ * A LIVE, fresh process is never `unknown` — "the process is alive" is itself a
+ * positive signal, so an opaque/unparseable live harness resolves to `running`
+ * (its honest floor), and every tracked harness with a locatable, parseable
+ * transcript (claude, codex, grok, droid, rush, gemini, kimi, hermes, opencode,
+ * 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' | 'unknown';
+export type ActiveStatus = 'running' | 'idle' | 'queued' | 'input_required' | 'closed' | 'abandoned' | 'unknown';
 export interface ActiveSession {
     context: ActiveContext;
     kind: string;
@@ -109,6 +131,14 @@ export interface ActiveSession {
      * Absent for cloud sessions (no local pid) and any pid whose env is unreadable.
      */
     provenance?: SessionProvenance;
+    /**
+     * Who initiated this session — the resolved actor id stamped at spawn
+     * (`resolveActor().id`, read back from the pid registry / teammate record).
+     * A tailnet login/email for a resolved human, `UNRESOLVED@<host>` when it
+     * couldn't be determined, absent when the launch predates actor stamping.
+     * Surfaced as the owner column in `--active` (RUSH-2018).
+     */
+    owner?: string;
     /**
      * The machine this session runs on, as a normalized device id (machineId()
      * form). Set when merging cross-machine results so the grouped `--active`
@@ -172,6 +202,16 @@ export interface ActiveQueryOptions {
  * transcript just because a GUI app service with the same basename is alive.
  */
 export declare const ACTIVE_SESSION_STALE_MS: number;
+/**
+ * A session whose transcript hasn't been written in this long is ABANDONED /
+ * dangling — the framework can no longer treat it as live work, whether its PID
+ * is dead (long gone) or still alive but making no progress (a hung agent).
+ * Two days: past a normal work gap, well short of a session legitimately kept
+ * open across a long weekend. Deliberately far wider than
+ * {@link ACTIVE_SESSION_STALE_MS} (which bounds transcript-borrowing, a different
+ * concern) — this is the lifecycle threshold, not the freshness window.
+ */
+export declare const ABANDONED_STALE_MS: number;
 /**
  * Resolve an agent kind from a process's reported executable. `comm` may be an
  * absolute path (shim-launched agents), and Windows image names carry an
@@ -219,30 +259,74 @@ export declare function sessionFileTimes(sessionFile: string | undefined): {
     birthtimeMs?: number;
     mtimeMs?: number;
 };
+/**
+ * The lifecycle status computed purely from the two hard signals the framework
+ * always has — PID liveness and transcript last-write (mtime) — independent of
+ * anything the agent self-reports or what its last transcript turn happened to
+ * look like. Returns the definitive lifecycle label when one applies, or
+ * `undefined` when the process is live and fresh (so the caller uses the richer
+ * activity-derived status instead).
+ *
+ *   - No write in {@link ABANDONED_STALE_MS} ⇒ `abandoned` (dangling): a
+ *     days-stale session is not live work, whether its PID is dead (long gone)
+ *     or still alive but stuck. Checked first — it outranks a bare `closed`.
+ *   - Otherwise, PID dead ⇒ `closed`: the process has exited. This is the fix
+ *     for the old "dead PID reports idle" lie — `idle` reads as "done, waiting
+ *     for you", but a dead process is done, period.
+ *   - Otherwise (alive + fresh) ⇒ `undefined`: defer to the activity engine.
+ */
+export declare function lifecycleStatus(pidAlive: boolean, mtimeMs: number | undefined, nowMs?: number): ActiveStatus | undefined;
 /**
  * The ONE place a fallback status is decided when no rich transcript state is
- * available — a non-Claude/Codex kind we cannot parse, or a Claude/Codex tail
- * that was empty or unreadable. Honest by construction: it never asserts a status
- * it cannot justify from a measured signal.
+ * available — an opaque kind we cannot parse (cursor, openclaw), or a transcript
+ * whose parse/tail was empty or unreadable. Honest by construction: computed from
+ * PID + mtime, never a fabricated `idle`.
  *
- *   - Resolvable transcript, readable mtime → the MEASURED freshness signal:
- *     written within ACTIVE_MTIME_WINDOW_MS ⇒ `running`, else `idle`.
- *   - Resolvable transcript whose `stat` throws (file vanished / permission) → we
- *     genuinely cannot tell ⇒ `unknown`. (This branch previously returned
- *     `running`, which contradicted the `idle` default one branch up.)
- *   - No resolvable transcript but the process is alive → alive-but-opaque ⇒
- *     `unknown`. This is the truthful answer for a live gemini / droid / cursor /
- *     opencode whose format we don't parse — NOT a fabricated `idle` (which the
- *     UI reads as "done and waiting"), and it never lies as `running` either.
- *   - No transcript and the process is not known alive → nothing to report ⇒ `idle`.
+ *   - Dead PID, or a days-stale transcript ⇒ {@link lifecycleStatus} (`closed` /
+ *     `abandoned`). A dead process is `closed`, not the old fabricated `idle`
+ *     (which the UI reads as "done, waiting for you"); a dead process whose file
+ *     also vanished is still `closed` (death is a definitive answer, not `unknown`).
+ *   - Live + fresh ⇒ `running`. A live process is, at minimum, running: we may
+ *     not see WHAT an opaque harness (or an empty tail) is doing, but the process
+ *     being alive is a positive signal — never a blank `unknown` (the old blanket
+ *     bug for every non-claude/codex live agent) nor a downgraded `idle`.
  */
-export declare function resolveFallbackStatus(sessionFile: string | undefined, pidAlive: boolean): ActiveStatus;
+export declare function resolveFallbackStatus(sessionFile: string | undefined, pidAlive: boolean, nowMs?: number): ActiveStatus;
 /**
- * Locate the live transcript for an agent process. Claude files are keyed by
- * cwd (+ optional session uuid); Codex files are date-partitioned, so we resolve
- * the newest indexed Codex session for the cwd instead.
+ * Locate the live transcript for an agent process. Claude files are keyed by cwd
+ * (+ optional session uuid), so they resolve straight off disk. Every OTHER
+ * tracked harness — Codex (date-partitioned), plus grok / droid / rush / gemini /
+ * kimi / hermes / opencode / antigravity (per-session dirs, SQLite, single-JSON)
+ * — is resolved through the session index by cwd: the newest indexed transcript
+ * for that cwd, bounded by ACTIVE_SESSION_STALE_MS so a live pid never borrows a
+ * weeks-old transcript. This is what lets a live NON-claude/codex agent get a real
+ * status instead of falling through to `unknown` (the file feeds
+ * {@link computeLiveSignals}). An opaque kind we don't track (cursor) still yields
+ * undefined here and degrades honestly to a live `running`.
  */
 export declare function findSessionFileForKind(kind: string, cwd?: string, sessionId?: string): string | undefined;
+/** Live per-session signals derived from one transcript-tail read. */
+interface LiveSignals {
+    /** Rich inferred state (activity/preview/badges). Undefined when unreadable. */
+    state?: SessionState;
+    /** Rolling output-token throughput (tokens/sec). Undefined when no usage in the tail. */
+    tokPerSec?: number;
+}
+/**
+ * Derive the inferred state (working / waiting / idle + preview/badges) and, for
+ * the two harnesses whose raw lines carry it, the output-token throughput.
+ *
+ * Claude/Codex take the fast bounded byte-tail ({@link readSessionTailWithRaw}) —
+ * the hot path, and the only two that also yield throughput (their raw lines
+ * carry usage the event model drops). EVERY OTHER tracked harness (grok, droid,
+ * rush, gemini, kimi, hermes, opencode, antigravity) is parsed with its own
+ * parser and run through the SAME {@link inferSessionState}, so a live
+ * non-claude/codex agent gets a real working/waiting/idle instead of the blanket
+ * `unknown` it used to fall through to. An opaque/untracked kind (cursor) or an
+ * unreadable/empty transcript yields an empty signal set, and the caller's
+ * {@link resolveFallbackStatus} reports the honest live floor (`running`).
+ */
+export declare function computeLiveSignals(kind: string, sessionFile: string | undefined, cwd: string | undefined, pidAlive: boolean): LiveSignals;
 /** Live teams teammates. Reuses AgentManager which already polls PIDs via `kill -0`. */
 export declare function listTeamsActive(): Promise<ActiveSession[]>;
 /** Live editor-terminal agents across every IDE window. */