@phnx-labs/agents-cli 1.22.35 → 1.22.37

package/dist/lib/session/active.js

@@ -24,21 +24,22 @@ import { promisify } from 'util';
 import { listActiveTasks } from '../cloud/store.js';
 import { AgentManager } from '../teams/agents.js';
 import { getTerminalsDir } from '../state.js';
-import { readPidSessionEntry, listPidSessionEntries, prunePidSessionRegistry } from './pid-registry.js';
+import { readPidSessionEntry, listPidSessionEntries, prunePidSessionRegistry, sessionIdFromLivePid, isSessionIdShape, } from './pid-registry.js';
 import { readSessionActorRecord, writeSessionAliasRecord } from './actor-sidecar.js';
 import { loadHookSessionIndex, resolveHookSessionRecord, readStateSessionRecord } from './hook-sessions.js';
 import { buildClaudeLabelMap, getAgentSessionDirs } from './discover.js';
 import { buildRunNameMap } from './run-names.js';
-import { latestSessionFileForCwd, findSessionsByShortIds } from './db.js';
+import { latestSessionFileForCwd, findSessionsByShortIds, findSessionMachinesByIds } from './db.js';
 import { extractSessionTopic } from './prompt.js';
 import { readSessionTailWithRaw } from './tail.js';
 import { parseSession } from './parse.js';
 import { computeTokPerSec } from './throughput.js';
 import { inferSessionState } from './state.js';
-import { isSessionTrackedAgent, SESSION_AGENTS } from './types.js';
+import { isSessionTrackedAgent, SESSION_AGENTS, AG_TMUX_NAME_RE } from './types.js';
 import { AGENTS } from '../agents.js';
 import { detectProvenance } from './provenance.js';
 import { loadDevices } from '../devices/registry.js';
+import { machineId, normalizeHost } from '../machine-id.js';
 import { presenceFromStore } from './detached.js';
 import { classifyHostLink, HOST_HEARTBEAT_STALE_MS } from './host-link.js';
 import { mapBounded } from '../concurrency.js';
@@ -274,7 +275,7 @@ export function agentKindFromComm(commRaw) {
  * and validating there would silently drop grok/kimi/antigravity — the exact
  * harness-parity gap we are fixing.
  */
-const AG_NAME_RE = /^ag-([a-z][a-z0-9-]*?)-([0-9a-f]{8})$/i;
+const AG_NAME_RE = AG_TMUX_NAME_RE;
 /** Agent kind from an `ag-<agent>-<shortid>` tmux session name, else undefined. */
 export function agentKindFromName(sessName) {
     const m = AG_NAME_RE.exec(sessName);
@@ -867,6 +868,7 @@ export function summarizeMission(prompt) {
 export async function listTeamsActive(opts = {}) {
     const mgr = new AgentManager(undefined, undefined, undefined, undefined, undefined, opts.localOnly ?? false);
     const running = await mgr.listRunning();
+    const self = machineId();
     return running.map((a) => {
         // The teammate's OWN transcript is `remoteSessionId` (captured from its first
         // stream event). `parentSessionId` is the ORCHESTRATOR that spawned the team
@@ -880,11 +882,27 @@ export async function listTeamsActive(opts = {}) {
         const pidAlive = a.pid ? isPidAlive(a.pid) : true;
         const { state, tokPerSec } = computeLiveSignals(a.agentType, sessionFile, a.cwd ?? undefined, pidAlive);
         const resolvedId = ownSessionId ?? sessionIdFromFile(sessionFile);
+        // A remote teams teammate (`teams add --device <peer>`) EXECUTES on that
+        // peer, not on this orchestrator box — but it gets no host-dispatch index
+        // row, so `foldExecutionMachine` can't reach it and the self-stamp in
+        // `commands/sessions.ts` would claim it, listing a peer's teammate under
+        // `--device <orchestrator>` (SES-GAP-10). Attribute the row to the execution
+        // host and mark the dispatcher, the same shape `run --device` gets: `machine`
+        // survives the cross-machine fan-out because `parseRemoteActive` keeps an
+        // `offloadedFrom` row's own machine, and `offloadedFrom` is COMPARED to this
+        // box by `sessionProcessIsLocal` (never merely tested), so a third box seeing
+        // this row over the fan-out reads it as the peer's, not its own. A local
+        // teammate (no `hostName`, or pinned to this box) is left unattributed for
+        // the self-stamp.
+        const execHost = a.hostName ? normalizeHost(a.hostName) : undefined;
+        const offloaded = execHost !== undefined && execHost !== self;
         return applyState({
             context: 'teams',
             kind: a.agentType,
             pid: a.pid ?? undefined,
             sessionId: resolvedId,
+            machine: offloaded ? execHost : undefined,
+            offloadedFrom: offloaded ? self : undefined,
             orchestratorSessionId: a.parentSessionId ?? undefined,
             cwd: a.cwd ?? undefined,
             label: a.name ?? undefined,
@@ -1214,11 +1232,16 @@ export function readAncestorSessionEntry(pid, ppidMap, kind, readEntry = readPid
  * as its own headless row. Two exceptions keep their own row: a candidate with
  * its own registry entry — on its pid OR on a wrapper ancestor strictly below
  * the pid it would fold into (the shim's entry lands on the cmd.exe
- * intermediary on Windows) — and a child of a *different* agent kind (claude
- * shelling out to codex is a real second session, not a fork).
+ * intermediary on Windows) — a child whose live argv carries `--session-id`
+ * (RUSH-2384: empty by-pid must not fold a real session into a parent and
+ * drop it from the active set) — and a child of a *different* agent kind
+ * (claude shelling out to codex is a real second session, not a fork).
  * Returns the kept roots plus, per root pid, how many descendants folded in.
+ *
+ * `hasLiveSessionId` defaults to reading `--session-id` from the live process
+ * argv; tests inject a pure predicate so they do not need real agent pids.
  */
-export function foldSubordinateAgents(candidates, ppidMap, readEntry) {
+export function foldSubordinateAgents(candidates, ppidMap, readEntry, hasLiveSessionId = (pid) => sessionIdFromLivePid(pid) != null) {
     const kindByPid = new Map(candidates.map(c => [c.pid, c.kind]));
     const nearestSameKindAncestor = (pid, kind) => {
         let cur = ppidMap.get(pid);
@@ -1234,9 +1257,13 @@ export function foldSubordinateAgents(candidates, ppidMap, readEntry) {
     // Own launch identity: a matching-kind registry entry on the candidate or on
     // any wrapper between it and the pid it would fold into (exclusive). Entries
     // above the fold target belong to that ancestor's session, not this one.
+    // A live `--session-id` on argv is also own identity (RUSH-2384) — the
+    // registry is often empty while the process still names its session.
     const hasOwnSession = (c, stopPid) => {
         if (readEntry(c.pid)?.agent === c.kind)
             return true;
+        if (hasLiveSessionId(c.pid))
+            return true;
         let cur = ppidMap.get(c.pid);
         const seen = new Set();
         while (cur && cur > 1 && cur !== stopPid && !seen.has(cur)) {
@@ -1366,11 +1393,13 @@ async function listUnattributedActiveLive(attributed) {
         // path). Absent entirely (direct launch outside agents-cli) → heuristic.
         const entry = readPidSessionEntry(pid) ?? readAncestorSessionEntry(pid, ppidMap, kind);
         // Exact session id, in priority: (1) the id we recorded at launch (Claude,
-        // known up front via --session-id); (2) the agent's OWN SessionStart hook,
+        // known up front via --session-id); (2) the live process's own argv
+        // `--session-id` (RUSH-2384 — by-pid is often empty mid-run while the
+        // process still advertises the id); (3) the agent's OWN SessionStart hook,
         // authoritative for non-Claude and for agents we didn't launch, joined by
         // launchId/terminalId/pid and kind-guarded against a stale reused-pid file;
-        // (3) the newest-jsonl heuristic (sessionIdFromFile, below).
-        let exactId = entry?.sessionId;
+        // (4) the newest-jsonl heuristic (sessionIdFromFile, below).
+        let exactId = entry?.sessionId ?? sessionIdFromLivePid(pid);
         // The hook record (when we fall to it) also carries the SessionStart `ts` — the
         // real session-start epoch. Capture it so terminal/headless rows get a
         // `startedAtMs` instead of rendering "0s ago" (they set none before this).
@@ -1386,6 +1415,16 @@ async function listUnattributedActiveLive(attributed) {
             });
             exactId = hookRec?.session_id;
         }
+        // RUSH-2501: the hook-sessions index (terminals/sessions/) is populated only
+        // by @agents/session-tracker, which is not deployed on most fleet machines.
+        // The DEPLOYED SessionStart hook writes to state/sessions/<pid>.json instead.
+        // Try that path when the index lookup found nothing, so cursor/grok/kimi/droid
+        // agents (which carry no --session-id argv) can be attributed.
+        if (!exactId) {
+            const stateRec = readStateSessionRecord(pid, entry?.startedAtMs);
+            if (stateRec)
+                exactId = stateRec.session_id;
+        }
         const cwd = cwds[i] ?? entry?.cwd ?? undefined;
         const sessionFile = findSessionFileForKind(kind, cwd, exactId);
         const topic = sessionFile ? quickExtractTopic(sessionFile) : undefined;
@@ -1670,9 +1709,34 @@ export async function getActiveSessions(opts = {}) {
     foldPresence(merged);
     await foldTmuxClients(merged);
     foldHostLink(merged);
+    // Runs before the row leaves this box so every consumer — local render, the
+    // `--json` a peer answers a fan-out with, the browser's device filter — sees
+    // the EXECUTION host rather than the dispatcher (RUSH-2479).
+    foldExecutionMachine(merged, recordedMachineLookup(merged), machineId());
     annotateOrchestratorLabels(merged);
     return merged;
 }
+/**
+ * True when a live agent process on this host carries `--session-id <id>` in
+ * its argv. RUSH-2384 last-resort for `agents message`: getActiveSessions can
+ * still miss a row (teams status flap, attributed-ancestor skip), but the
+ * process table + argv are ground truth for "this session is alive and
+ * mailbox-reachable". Only UUID-shaped ids are accepted so a short prefix
+ * never false-matches.
+ */
+export async function isSessionIdLiveOnProcessTable(sessionId, deps = {}) {
+    if (!isSessionIdShape(sessionId))
+        return false;
+    const readTable = deps.readTable ?? (async () => readProcessTable());
+    const sessionIdOf = deps.sessionIdOf ?? sessionIdFromLivePid;
+    for (const row of await readTable()) {
+        if (!row.kind)
+            continue;
+        if (sessionIdOf(row.pid) === sessionId)
+            return true;
+    }
+    return false;
+}
 /**
  * Fold tmux's attached-client count onto every tmux-hosted row.
  *
@@ -1748,6 +1812,97 @@ export async function foldTmuxClients(rows) {
  *     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.
  */
+/**
+ * Attribute each live row to the machine the session actually EXECUTES on.
+ *
+ * A host-dispatched run (`agents run --device <peer>`) leaves a live process on
+ * the DISPATCHING box — the ssh/TTY shim — carrying the remote run's session id.
+ * Nothing about that local process knows the agent is on the peer, so the row
+ * was tagged with THIS machine: `--device <dispatcher>` then claimed a session
+ * that is not running here, and its preview dead-ended at "full transcript not
+ * indexed here" because the transcript lives on the peer (RUSH-2479).
+ *
+ * The dispatch already recorded the truth. `registerHostSession` /
+ * `registerInteractiveHostSession` write the index row with
+ * `machine: normalizeHost(task.host)` (`lib/hosts/session-index.ts:55,134`), so
+ * this folds that recorded machine back onto the live row. Every consumer then
+ * agrees on one owner: the `--host`/`--device` scope, the browser's device
+ * filter, `_remote`/preview routing (`liveSessionToMeta`), and the id resolver.
+ *
+ * Two rows are deliberately left alone:
+ *   - one the cross-machine fan-out already attributed to a peer — that is the
+ *     peer's own self-report, which outranks this box's index copy;
+ *   - one whose indexed machine IS this box — nothing was offloaded.
+ *
+ * Pure over the array; `machineOf` is injected so the join is unit-tested
+ * without a SQLite index.
+ */
+export function foldExecutionMachine(rows, machineOf, self) {
+    for (const s of rows) {
+        if (!s.sessionId)
+            continue;
+        if (s.machine && s.machine !== self)
+            continue;
+        const recorded = machineOf(s.sessionId);
+        if (!recorded || recorded === self)
+            continue;
+        s.machine = recorded;
+        s.offloadedFrom = self;
+    }
+}
+/**
+ * Is the PROCESS behind this row running on this machine?
+ *
+ * `machine` answers a different question — "where does the agent execute" —
+ * which is what a `--device` scope, preview routing, and resume ownership need.
+ * For an offloaded run the two answers diverge: {@link foldExecutionMachine}
+ * points `machine` at the peer, while the shim process, its tmux pane, and its
+ * terminal window are all still HERE. `offloadedFrom` marks exactly that row.
+ *
+ * Any caller reaching for a LOCAL pid, pane, or window must ask this rather
+ * than `machine === self`. A local tmux pane id (`%N`) handed to a peer's tmux
+ * server does not fail — pane ids are small per-server integers, so it can
+ * resolve against an unrelated pane and attach the user to someone else's
+ * session. That is why this predicate exists instead of ten copies of the
+ * comparison.
+ */
+export function sessionProcessIsLocal(s, self) {
+    // `offloadedFrom` names WHICH box holds the shim, so it must be compared, not
+    // merely tested. These rows travel: `--active --json` spreads them verbatim
+    // and the fan-out preserves their foreign `machine`, so a THIRD box sees
+    // `{machine: B, offloadedFrom: A}` — a shim that is emphatically not its own.
+    // Answering "local" there sends the caller down the local-tmux path with
+    // A's pane id, attaching an unrelated pane on C: the same hazard this
+    // predicate exists to prevent, one machine over.
+    if (s.offloadedFrom)
+        return s.offloadedFrom === self;
+    return !s.machine || s.machine === self;
+}
+/**
+ * The machine to reach for this session's PROCESS — its pid, tmux pane, and
+ * window — or `undefined` when that process is right here.
+ *
+ * Not the same as `machine`, which is where the AGENT executes. For an offloaded
+ * run the process lives on the dispatcher (`offloadedFrom`) while the agent runs
+ * on the peer, so a caller that ssh'd to `machine` would carry the dispatcher's
+ * pane id to a box that never had it.
+ */
+export function sessionProcessHost(s, self) {
+    if (sessionProcessIsLocal(s, self))
+        return undefined;
+    return s.offloadedFrom ?? s.machine;
+}
+/**
+ * The index lookup behind {@link foldExecutionMachine}. One batched query for
+ * every live row (`findSessionMachinesByIds`), not a per-row `SELECT *` —
+ * `getActiveSessions` is a hot path the daemon, menubar, and watchdog all poll.
+ * Best-effort: an unavailable DB yields an empty map, leaving rows attributed
+ * to this box rather than failing the whole live view.
+ */
+function recordedMachineLookup(rows) {
+    const byId = findSessionMachinesByIds(rows.map((s) => s.sessionId).filter((id) => !!id));
+    return (id) => byId.get(id);
+}
 export function foldHostLink(rows) {
     for (const s of rows) {
         // Cloud tasks have no local pid, window, or tmux server; there is no host

package/dist/lib/session/actor-sidecar.d.ts

@@ -1,4 +1,4 @@
-import type { SessionRunMode } from './types.js';
+import { type SessionRunMode } from './types.js';
 export interface SessionActorRecord {
     sessionId: string;
     /** Resolved actor id (`resolveActor().id`) — the responsible human/agent. */

package/dist/lib/session/actor-sidecar.js

@@ -17,6 +17,7 @@
 import fs from 'fs';
 import path from 'path';
 import { getHistoryDir } from '../state.js';
+import { isAgentTmuxAlias } from './types.js';
 function sidecarDir() {
     return path.join(getHistoryDir(), 'by-session');
 }
@@ -34,7 +35,7 @@ function recordPath(sessionId) {
     return path.join(sidecarDir(), `${sessionId}.json`);
 }
 function isSafeAlias(alias) {
-    return /^ag-[a-z][a-z0-9-]*-[0-9a-f]{8}$/i.test(alias);
+    return isAgentTmuxAlias(alias);
 }
 function hasRecordData(record) {
     return typeof record.actor === 'string'

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

@@ -11,8 +11,8 @@ import type { SessionAgentId, SessionEvent, SessionMeta } from './types.js';
 import { type IndexedToolCall } from './tool-calls.js';
 /** Current schema version; bumped when migrations are added. Exported so tests
  * assert against the constant instead of hardcoding a number that every bump
- * then has to chase (docs/05-sessions.md calls the constant the source of truth). */
-export declare const SCHEMA_VERSION = 37;
+ * then has to chase (docs/sessions.md calls the constant the source of truth). */
+export declare const SCHEMA_VERSION = 39;
 /**
  * Bump to force `agents sessions backfill resources` to re-derive every
  * session's skill/slash-command tallies on its next run (resource_scan_ledger
@@ -81,6 +81,13 @@ export interface SessionRow {
     /** NULL means "not yet computed" (a row scanned before this field existed) — see rowToMeta. */
     used_browser: number | null;
     used_computer: number | null;
+    /**
+     * Epoch ms the transcript file was first confirmed gone while content survived
+     * (RUSH-2436); NULL = live/never archived. Optional because the scanner upsert
+     * write-payload never sets it — the INSERT column list omits it, so a rescan
+     * preserves the sticky stamp; it is written only by querySessions.
+     */
+    archived_at?: number | null;
 }
 /** File stat snapshot used to detect changes between scan runs. */
 export interface ScanStamp {
@@ -403,6 +410,26 @@ export declare function writeSessionPreviewCache<T>(entry: {
     fileSize: number | null;
     preview: T;
 }): 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
+ * the content that survives the transcript file being deleted (RUSH-2436): the
+ * render path reads it so a file-gone session still shows its user prompts, and
+ * querySessions uses its presence to tell a genuine archived session (has
+ * content) from a phantom (a stale/moved file_path with none). Returns undefined
+ * when no row exists; an empty string when a row exists but carried no content.
+ */
+export declare function readSessionContent(id: string): string | undefined;
+/**
+ * Read the last-computed preview digest for a session by id, validated against
+ * the session row's OWN stored file stamp rather than a live `fs.stat` — the
+ * transcript file is gone, so there is nothing on disk to stat, but the preview
+ * cache was written with the same `file_mtime_ms`/`file_size` the sessions row
+ * still records, so the join re-establishes that stamp. Backs the file-gone
+ * render/preview path (RUSH-2436). Returns undefined when no cached digest
+ * survives for this session.
+ */
+export declare function readArchivedSessionPreview<T>(id: string): T | undefined;
 /** Plugin provenance already indexed for resources used by one session. */
 export declare function getSessionPlugins(id: string): string[];
 export type UsageRollupGroup = 'agent' | 'project' | 'day' | 'account';
@@ -562,6 +589,16 @@ export interface TopCostSession {
  */
 export declare function topSessionsByCost(n: number, options?: QueryOptions): TopCostSession[];
 /** Look up a single session by its unique ID. */
+/**
+ * Batch-resolve session ids to the machine each one runs on, in ONE indexed
+ * query. `getActiveSessions` needs only this column for every live row, and
+ * `getSessionById` would re-`prepare` a `SELECT *` and materialize a full
+ * `SessionMeta` per id to read it — mirrors {@link findSessionsByShortIds}'s
+ * single-round-trip pattern. Ids absent from the index are simply absent from
+ * the map. Best-effort: an unavailable DB yields an empty map, so the live view
+ * still renders (the caller then leaves rows attributed to this box).
+ */
+export declare function findSessionMachinesByIds(ids: string[]): Map<string, string>;
 export declare function getSessionById(id: string): SessionMeta | null;
 /**
  * Resolve a full-or-partial session id against the index, exact-first then
@@ -570,6 +607,12 @@ export declare function getSessionById(id: string): SessionMeta | null;
  * short id. An exact hit short-circuits so a complete id never also drags in its
  * prefix siblings. `scope` narrows by agent / version / project (cwd) so an
  * ambiguous prefix disambiguates against the caller's context.
+ *
+ * Routes through the full querySessions existence check (NOT skipExistenceCheck)
+ * on purpose (RUSH-2436): that check now KEEPS a file-gone session whose user
+ * turns still live in session_text (flagged archived) and only suppresses a
+ * contentless phantom — so `agents sessions <id>` resolves an archived session
+ * instead of failing with "No session found", while a phantom id still misses.
  */
 export declare function findSessionsById(idQuery: string, scope?: Pick<QueryOptions, 'agent' | 'version' | 'cwd' | 'project'>): SessionMeta[];
 /**
@@ -631,3 +674,134 @@ export declare function getRowCount(): {
  * Returns the number of session rows updated.
  */
 export declare function updateSessionFilePaths(oldPrefix: string, newPrefix: string): number;
+/** Per-kind capture tallies for a browser task. Counts only -- never the bytes. */
+export interface BrowserCaptureCounts {
+    screenshot: number;
+    pdf: number;
+    recording: number;
+    download: number;
+}
+/** One durable browser-task row. `machine` defaults to this device. */
+export interface BrowserSessionRecord {
+    task: string;
+    profile: string;
+    sessionId?: string;
+    launchId?: string;
+    actor?: string;
+    machine?: string;
+    startedAt?: number;
+    lastActivity?: number;
+    counts?: Partial<BrowserCaptureCounts>;
+    captureDir?: string;
+    capturesRemote?: string;
+}
+/** One durable computer-use invocation row. `machine` defaults to this device. */
+export interface ComputerSessionRecord {
+    invocationId: string;
+    sessionId?: string;
+    launchId?: string;
+    actor?: string;
+    machine?: string;
+    startedAt?: number;
+    lastActivity?: number;
+    actionCount?: number;
+    taskPreview?: string;
+}
+/**
+ * Upsert one browser task's durable metadata.
+ *
+ * Called at task START. This executes INSIDE the browser daemon (daemon.ts
+ * constructs BrowserService; ipc.ts dispatches `start` to it), which makes the
+ * shared daemon a writer of this DB — but the identity it writes is RESOLVED IN
+ * THE CALLING CLI PROCESS and forwarded over IPC, never resolved here. That
+ * distinction is the whole fix: resolving it daemon-side would attribute every
+ * task to the daemon's own actor (the RUSH-2020 bug).
+ *
+ * `agents browser stop` deliberately does NOT delete this row: the whole point
+ * is that the link outlives the task.
+ *
+ * Identity fields are only ever widened, never blanked. A later capture-count
+ * update carries no session id, and `COALESCE(excluded.…, browser_sessions.…)`
+ * keeps the one recorded at start rather than overwriting it with NULL --
+ * otherwise the second write would undo exactly what the first was for.
+ */
+export declare function recordBrowserSession(record: BrowserSessionRecord): void;
+/**
+ * Upsert one computer-use invocation's durable metadata.
+ *
+ * `action_count` accumulates: a `computer run` loop emits many actions under one
+ * invocation id, and each arrives as its own call, so the count is incremented
+ * rather than replaced. Identity is widened-only, for the same reason as above.
+ */
+export declare function recordComputerSession(record: ComputerSessionRecord): void;
+/** A stored browser row as read back, with counts rehydrated. */
+export interface StoredBrowserSession extends Required<Pick<BrowserSessionRecord, 'task' | 'profile'>> {
+    sessionId?: string;
+    launchId?: string;
+    actor?: string;
+    machine: string;
+    startedAt: number;
+    lastActivity?: number;
+    counts: BrowserCaptureCounts;
+    captureDir?: string;
+    capturesRemote?: string;
+}
+/**
+ * Stored browser tasks, newest first; optionally scoped to one profile.
+ *
+ * A PROFILE-SCOPED read is deliberately unbounded. These rows are the identity
+ * for capture dirs that still exist on disk, and dropping the oldest ones would
+ * silently regress exactly those tasks to `unlinked` — the symptom this whole
+ * change removes, reappearing at a higher threshold. The row count is already
+ * bounded by the tasks that profile has ever run, and each row is a short
+ * metadata record. Only the unscoped read (every profile, used for overviews)
+ * takes a ceiling, since that one has no natural bound.
+ */
+export declare function listBrowserSessionRecords(profile?: string, opts?: {
+    limit?: number;
+}): StoredBrowserSession[];
+/** One stored browser task by its (profile, task) key, or null. */
+export declare function getBrowserSessionRecord(profile: string, task: string): StoredBrowserSession | null;
+/** A stored computer-use invocation as read back. */
+export interface StoredComputerSession {
+    invocationId: string;
+    sessionId?: string;
+    launchId?: string;
+    actor?: string;
+    machine: string;
+    startedAt: number;
+    lastActivity?: number;
+    actionCount: number;
+    taskPreview?: string;
+}
+/**
+ * Retention for the tool-session tables.
+ *
+ * These are the durable answer to a ledger that prunes at 7 days, so they are
+ * deliberately long-lived — but "durable" is not "unbounded". `computer_sessions`
+ * takes one row per `agents computer` CLI PROCESS (`COMPUTER_INVOCATION_ID` is
+ * minted per process), and an agent driving a desktop invokes that hundreds of
+ * times a day, so an unbounded table would grow without limit and be read in
+ * full on every listing.
+ */
+export declare const TOOL_SESSION_MAX_AGE_DAYS = 365;
+/** Default ceiling on rows one listing will read. */
+export declare const TOOL_SESSION_LIST_LIMIT = 2000;
+/**
+ * Drop tool-session rows past {@link TOOL_SESSION_MAX_AGE_DAYS}.
+ *
+ * Called from the listing path, never from the write hot path: an
+ * `agents computer` action must not pay for a table sweep (see the fail-soft
+ * note on `recordComputerSession`'s caller). Returns rows deleted.
+ */
+export declare function pruneToolSessions(maxAgeDays?: number): number;
+/**
+ * Stored computer-use invocations, newest first, bounded.
+ *
+ * The limit is a real ceiling, not a nicety: `--json` serializes whatever this
+ * returns, so an unbounded read would dump the entire table on every call.
+ */
+export declare function listComputerSessionRecords(opts?: {
+    limit?: number;
+    startedBeforeMs?: number;
+}): StoredComputerSession[];