@phnx-labs/agents-cli 1.20.29 → 1.20.31

package/dist/lib/computer-rpc.d.ts

@@ -20,10 +20,15 @@ export declare function loadDefaultPeers(): string[];
 export declare function writeComputerPeers(allowedExecPaths: string[]): void;
 export declare function resolveHelperExec(): string | null;
 export declare function resolveHelperApp(): string | null;
+export declare function resolveTcpEndpoint(): {
+    host: string;
+    port: number;
+    token: string | null;
+} | null;
 export declare function openComputerClient(): ComputerClient;
 export declare const RPC_TIMEOUT_MS = 30000;
 export declare function resolveRpcTimeoutMs(env: string | undefined): number;
 export declare function describeTransport(): {
-    kind: 'socket' | 'stdio' | 'none';
+    kind: 'socket' | 'stdio' | 'tcp' | 'none';
     path: string | null;
 };

package/dist/lib/computer-rpc.js

@@ -187,9 +187,31 @@ export function resolveHelperApp() {
     // exec = <bundle>/Contents/MacOS/ComputerHelper
     return path.resolve(exec, '..', '..', '..');
 }
-// Pick the best transport. If the socket exists, use it. Otherwise fall
-// back to spawning the helper as a subprocess (legacy path).
+// Resolve the TCP endpoint for the Windows daemon (computer-helper-win), if
+// configured. The Windows helper binds loopback TCP (Program.cs) and the CLI
+// reaches it over an `ssh -L` tunnel, so the endpoint is a local forwarded
+// port. COMPUTER_HELPER_TCP is "host:port" (host defaults to 127.0.0.1);
+// COMPUTER_HELPER_TOKEN is the shared secret sent in the first `auth` frame.
+export function resolveTcpEndpoint() {
+    const raw = process.env.COMPUTER_HELPER_TCP;
+    if (!raw || raw.length === 0)
+        return null;
+    const [hostPart, portPart] = raw.includes(':') ? raw.split(':') : ['127.0.0.1', raw];
+    const port = Number(portPart);
+    if (!Number.isInteger(port) || port <= 0)
+        return null;
+    const token = process.env.COMPUTER_HELPER_TOKEN;
+    return { host: hostPart || '127.0.0.1', port, token: token && token.length > 0 ? token : null };
+}
+// Pick the best transport. Precedence:
+//   1. COMPUTER_HELPER_TCP -> the Windows daemon over a (tunneled) TCP port.
+//   2. the macOS launchd socket if it exists.
+//   3. spawning the helper as a subprocess (legacy/dev fallback).
 export function openComputerClient() {
+    const tcp = resolveTcpEndpoint();
+    if (tcp) {
+        return new TcpClient(tcp.host, tcp.port, tcp.token);
+    }
     const sockPath = resolveSocketPath();
     if (fs.existsSync(sockPath)) {
         return new SocketClient(sockPath);
@@ -297,6 +319,61 @@ class SocketClient extends BaseClient {
         });
     }
 }
+// TCP transport for the Windows daemon (computer-helper-win). The daemon
+// binds loopback only (Program.cs); the CLI reaches it over an `ssh -L`
+// tunnel, so `host` is typically 127.0.0.1 + a forwarded port. When a token
+// is configured the daemon accepts only an `auth` frame until authenticated,
+// so we send that first and gate every other call on it.
+class TcpClient extends BaseClient {
+    sock;
+    authReady;
+    constructor(host, port, token) {
+        super();
+        this.sock = createConnection({ host, port });
+        this.sock.setEncoding('utf8');
+        this.sock.on('data', (chunk) => this.handleChunk(chunk));
+        this.sock.on('error', (err) => {
+            this.closed = true;
+            this.failPending('socket_error', err.message);
+        });
+        this.sock.on('close', () => {
+            this.closed = true;
+            this.failPending('helper_exited', 'tcp connection closed before reply');
+        });
+        // Kick off the auth handshake synchronously so its frame (id 1) is the
+        // first thing written. No token → daemon is open (tunnel-gated).
+        this.authReady = token ? this.authenticate(token) : Promise.resolve();
+    }
+    async authenticate(token) {
+        const res = await super.call('auth', { token });
+        if (res.error)
+            throw new Error(`computer-helper auth failed: ${res.error.code}`);
+    }
+    async call(method, params) {
+        if (method !== 'auth') {
+            try {
+                await this.authReady;
+            }
+            catch (e) {
+                return { id: null, error: { code: 'auth_failed', message: e.message } };
+            }
+        }
+        return super.call(method, params);
+    }
+    send(payload) {
+        this.sock.write(payload);
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.sock.end();
+        await new Promise((resolve) => {
+            if (this.closed)
+                return resolve();
+            this.sock.on('close', () => resolve());
+        });
+    }
+}
 class StdioClient extends BaseClient {
     proc;
     constructor(helperPath) {
@@ -324,8 +401,14 @@ class StdioClient extends BaseClient {
     }
 }
 // Describe which transport is currently in use. Useful for diagnostics
-// like `agents computer status`.
+// like `agents computer status`. TCP takes precedence to match
+// openComputerClient() — when COMPUTER_HELPER_TCP is set we drive a remote
+// (Windows) daemon over a tunnel, so callers off macOS (no socket, no local
+// .app) must not be told "no transport". `path` is null: the endpoint is an
+// env-configured host:port, not an on-disk path.
 export function describeTransport() {
+    if (resolveTcpEndpoint())
+        return { kind: 'tcp', path: null };
     const sockPath = resolveSocketPath();
     if (fs.existsSync(sockPath))
         return { kind: 'socket', path: sockPath };

package/dist/lib/devices/registry.d.ts

@@ -76,3 +76,14 @@ export interface DeviceInput {
 export declare function upsertDevice(name: string, input: DeviceInput): Promise<DeviceProfile>;
 /** Remove a device. Returns false if it was not registered. */
 export declare function removeDevice(name: string): Promise<boolean>;
+/** Load the set of ignored node names. Missing file => empty set. A malformed
+ * file is a hard error for the same reason the registry is: silently returning
+ * [] would let the next write wipe the user's dismissals. */
+export declare function loadIgnored(): Promise<Set<string>>;
+/** True if `name` is on the ignore-list. */
+export declare function isIgnored(name: string): Promise<boolean>;
+/** Add a node name to the ignore-list. Idempotent. Returns the resulting set. */
+export declare function addIgnored(name: string): Promise<Set<string>>;
+/** Remove a node name from the ignore-list (un-ignore). Returns false if it was
+ * not ignored. */
+export declare function removeIgnored(name: string): Promise<boolean>;

package/dist/lib/devices/registry.js

@@ -18,7 +18,7 @@ import * as fsSync from 'fs';
 import * as path from 'path';
 import { randomBytes } from 'crypto';
 import lockfile from 'proper-lockfile';
-import { getDevicesRegistryPath } from '../state.js';
+import { getDevicesRegistryPath, getDevicesIgnoredPath } from '../state.js';
 function registryPath() {
     return getDevicesRegistryPath();
 }
@@ -166,3 +166,55 @@ export async function removeDevice(name) {
         return true;
     });
 }
+function ignoredPath() {
+    return getDevicesIgnoredPath();
+}
+/** Load the set of ignored node names. Missing file => empty set. A malformed
+ * file is a hard error for the same reason the registry is: silently returning
+ * [] would let the next write wipe the user's dismissals. */
+export async function loadIgnored() {
+    const p = ignoredPath();
+    let raw;
+    try {
+        raw = await fs.readFile(p, 'utf-8');
+    }
+    catch (err) {
+        if (err && err.code === 'ENOENT')
+            return new Set();
+        throw err;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return new Set(Array.isArray(parsed.ignored) ? parsed.ignored : []);
+    }
+    catch (err) {
+        throw new Error(`Device ignore-list corrupted at ${p}: ${err?.message ?? err}. Inspect and restore from backup.`);
+    }
+}
+/** True if `name` is on the ignore-list. */
+export async function isIgnored(name) {
+    return (await loadIgnored()).has(name);
+}
+/** Add a node name to the ignore-list. Idempotent. Returns the resulting set. */
+export async function addIgnored(name) {
+    assertValidDeviceName(name);
+    const p = ignoredPath();
+    return withRegistryLock(p, async () => {
+        const set = await loadIgnored();
+        set.add(name);
+        await atomicWriteJson(p, { ignored: [...set].sort(), updatedAt: new Date().toISOString() });
+        return set;
+    });
+}
+/** Remove a node name from the ignore-list (un-ignore). Returns false if it was
+ * not ignored. */
+export async function removeIgnored(name) {
+    const p = ignoredPath();
+    return withRegistryLock(p, async () => {
+        const set = await loadIgnored();
+        if (!set.delete(name))
+            return false;
+        await atomicWriteJson(p, { ignored: [...set].sort(), updatedAt: new Date().toISOString() });
+        return true;
+    });
+}

package/dist/lib/devices/sync.d.ts

@@ -0,0 +1,42 @@
+import { type TailscaleNode } from './tailscale.js';
+export interface DeviceSyncResult {
+    /** False when discovery could not run (e.g. tailscale absent) in soft mode. */
+    ok: boolean;
+    /** Number of tailscale nodes upserted into the registry. */
+    synced: number;
+    /** Node names discovered but neither registered-before nor ignored. */
+    pending: string[];
+    /** Populated when ok is false: why discovery was skipped. */
+    reason?: string;
+}
+/**
+ * Node names present on the tailnet but neither already in the registry nor on
+ * the ignore-list — i.e. genuinely new devices worth surfacing. Pure so the
+ * flag matrix is unit-testable without a live tailnet.
+ */
+export declare function computePendingDevices(nodes: TailscaleNode[], registered: Iterable<string>, ignored: Iterable<string>): string[];
+/**
+ * Ingest `tailscale status --json` into the registry. In soft mode a missing
+ * tailscale binary / unreachable daemon resolves to `{ ok: false }` instead of
+ * throwing, so callers wiring this into setup/sync never abort the whole run.
+ * The `pending` list is computed against the registry state BEFORE this sync so
+ * "new" means "not previously registered and not ignored".
+ */
+export declare function runDeviceSync(opts?: {
+    soft?: boolean;
+}): Promise<DeviceSyncResult>;
+/**
+ * The register/remove/ignore decision for the interactive curation picker.
+ * Pure so the highest-risk reconcile logic is unit-testable without a tailnet
+ * or a live prompt. `keep` is the set the user left checked; everything else is
+ * dismissed. Checked => register (and un-ignore if it was ignored). Unchecked
+ * => remove from the registry if it was there, and ignore it so auto-sync never
+ * re-adds it.
+ */
+export interface DeviceReconciliation {
+    toRegister: string[];
+    toUnignore: string[];
+    toRemove: string[];
+    toIgnore: string[];
+}
+export declare function planDeviceReconciliation(allNames: Iterable<string>, keep: Iterable<string>, registered: Iterable<string>, ignored: Iterable<string>): DeviceReconciliation;

package/dist/lib/devices/sync.js

@@ -0,0 +1,85 @@
+/**
+ * Reusable device discovery.
+ *
+ * `agents devices sync` was the only thing that ever populated the registry,
+ * and it was purely user-invoked — so the registry sat empty until someone
+ * remembered to run it. This module extracts the ingest so it can be triggered
+ * automatically (from `agents sync` and `agents setup`) without duplicating the
+ * tailscale-parse-and-upsert loop, and exposes the pure pending-device diff the
+ * curation picker and the menu-bar probe both need.
+ *
+ * Two failure modes, one function:
+ *   - hard (default): the CLI `agents devices sync` action wants a clear error
+ *     and a non-zero exit when tailscale is missing.
+ *   - soft (`soft: true`): auto-callers must never abort setup/sync because a
+ *     machine has no tailscale — they get a result with `ok: false` instead.
+ */
+import { loadDevices, loadIgnored, upsertDevice, } from './registry.js';
+import { nodeToDeviceInput, parseTailscaleStatus, tailscaleStatusJson, } from './tailscale.js';
+/**
+ * Node names present on the tailnet but neither already in the registry nor on
+ * the ignore-list — i.e. genuinely new devices worth surfacing. Pure so the
+ * flag matrix is unit-testable without a live tailnet.
+ */
+export function computePendingDevices(nodes, registered, ignored) {
+    const known = new Set(registered);
+    const skip = new Set(ignored);
+    return nodes
+        .map((n) => n.name)
+        .filter((name) => !known.has(name) && !skip.has(name));
+}
+/**
+ * Ingest `tailscale status --json` into the registry. In soft mode a missing
+ * tailscale binary / unreachable daemon resolves to `{ ok: false }` instead of
+ * throwing, so callers wiring this into setup/sync never abort the whole run.
+ * The `pending` list is computed against the registry state BEFORE this sync so
+ * "new" means "not previously registered and not ignored".
+ */
+export async function runDeviceSync(opts = {}) {
+    // Soft mode must be non-fatal for ANY failure, not just a missing tailscale:
+    // a corrupted registry/ignore file (both throw by design), a disk error, or
+    // registry lock contention (plausible when many agents SessionStart-autosync
+    // the same host at once) would otherwise abort the whole `agents sync`. The
+    // whole body is inside the guard so the "never a sync failure" promise holds.
+    try {
+        const nodes = parseTailscaleStatus(tailscaleStatusJson());
+        const [registeredBefore, ignored] = await Promise.all([loadDevices(), loadIgnored()]);
+        const pending = computePendingDevices(nodes, Object.keys(registeredBefore), ignored);
+        // Register/refresh every node the user has NOT dismissed. Skipping ignored
+        // nodes is what makes the "register all" default safe: a phone or someone
+        // else's laptop the user once dismissed never silently comes back.
+        let synced = 0;
+        for (const node of nodes) {
+            if (ignored.has(node.name))
+                continue;
+            await upsertDevice(node.name, nodeToDeviceInput(node));
+            synced++;
+        }
+        return { ok: true, synced, pending };
+    }
+    catch (err) {
+        if (opts.soft) {
+            return { ok: false, synced: 0, pending: [], reason: err?.message ?? String(err) };
+        }
+        throw err;
+    }
+}
+export function planDeviceReconciliation(allNames, keep, registered, ignored) {
+    const keepSet = new Set(keep);
+    const regSet = new Set(registered);
+    const ignSet = new Set(ignored);
+    const out = { toRegister: [], toUnignore: [], toRemove: [], toIgnore: [] };
+    for (const name of allNames) {
+        if (keepSet.has(name)) {
+            out.toRegister.push(name);
+            if (ignSet.has(name))
+                out.toUnignore.push(name);
+        }
+        else {
+            if (regSet.has(name))
+                out.toRemove.push(name);
+            out.toIgnore.push(name);
+        }
+    }
+    return out;
+}

package/dist/lib/exec.js

@@ -534,6 +534,20 @@ export function buildExecCommand(options) {
             cmd.push('--dangerously-bypass-approvals-and-sandbox');
         }
     }
+    else if (options.agent === 'kimi' && !interactive) {
+        // kimi's headless prompt mode (`-p`/`--prompt`) is self-contained and REFUSES
+        // to be combined with any startup-mode flag: `--plan`, `--auto`, and `--yolo`
+        // all abort with "Cannot combine --prompt with --X" (verified against the live
+        // kimi CLI). The write-capable modes (edit/auto/skip) all collapse to kimi's
+        // default `-p` behavior, which already auto-approves tool calls, so we emit no
+        // mode flag. Plan (read-only) has no headless equivalent, so fail closed rather
+        // than silently letting a plan-mode run mutate the workspace.
+        if (resolvedMode === 'plan') {
+            throw new Error('kimi has no headless read-only mode: `--prompt` cannot be combined with `--plan`. ' +
+                'Run kimi in plan mode interactively (omit the prompt), or use --mode edit, auto, or skip.');
+        }
+        // edit/auto/skip: emit no mode flag — `kimi -p` auto-runs.
+    }
     else {
         cmd.push(...modeFlags);
     }

package/dist/lib/models.js

@@ -165,6 +165,26 @@ export function locateModelSource(agent, version) {
             return { path: pathBin, kind: 'cli' };
         return null;
     }
+    if (agent === 'antigravity') {
+        // The `agy` shim under node_modules/.bin exposes `agy models`. We don't parse
+        // any bundle; the CLI produces its own (display-name-only) catalog.
+        const cli = path.join(versionDir, 'node_modules', '.bin', 'agy');
+        if (fs.existsSync(cli))
+            return { path: cli, kind: 'cli' };
+        const pathBin = findOnPath('agy');
+        if (pathBin)
+            return { path: pathBin, kind: 'cli' };
+        return null;
+    }
+    if (agent === 'kimi') {
+        const cli = path.join(versionDir, 'node_modules', '.bin', 'kimi');
+        if (fs.existsSync(cli))
+            return { path: cli, kind: 'cli' };
+        const pathBin = findOnPath('kimi');
+        if (pathBin)
+            return { path: pathBin, kind: 'cli' };
+        return null;
+    }
     if (agent === 'cursor') {
         // cursor-agent is installed via curl script, not agents-cli. Version argument
         // is accepted for API symmetry but ignored -- cursor lives on PATH.
@@ -606,6 +626,114 @@ function extractOpenClawCatalog(binaryPath) {
     }));
     return { models, aliases: {} };
 }
+/**
+ * Extract Antigravity's catalog via `agy models`. Antigravity is unusual: it
+ * prints DISPLAY NAMES ONLY, one per line, with no machine ids and no --json:
+ *   Gemini 3.5 Flash (Medium)
+ *   Claude Sonnet 4.6 (Thinking)
+ * Verified (agy 1.0.11) that those display strings ARE the accepted `--model`
+ * values -- `agy --model "Claude Opus 4.6 (Thinking)"` routes to that model,
+ * and an unknown value silently falls back to the first row. So we use each
+ * display string as both id and displayName, and mark the first row default.
+ */
+function extractAntigravityCatalog(binaryPath) {
+    let stdout;
+    try {
+        stdout = execFileSync(binaryPath, ['models'], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 15_000,
+            maxBuffer: 8 * 1024 * 1024,
+        });
+    }
+    catch {
+        return { models: [], aliases: {} };
+    }
+    // Strip ANSI in case a spinner or color codes slip through.
+    // eslint-disable-next-line no-control-regex
+    const plain = stdout.replace(/\x1b\[[0-9;]*[A-Za-z]/g, '');
+    const models = [];
+    const seen = new Set();
+    for (const raw of plain.split('\n')) {
+        const name = raw.trim();
+        if (!name)
+            continue;
+        // Guard against any stray banner/usage lines: real rows look like
+        // "<Vendor> <Model> (<Level>)". Require an alphanumeric start and a
+        // parenthesized suffix, which every observed model row has.
+        if (!/^[A-Za-z0-9].*\([^)]+\)\s*$/.test(name))
+            continue;
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        models.push({
+            id: name,
+            displayName: name,
+            // Antigravity's first listed model is its default (unknown --model values
+            // fall back to it), so flag the first row we accept.
+            isDefault: models.length === 0,
+        });
+    }
+    return { models, aliases: {} };
+}
+/**
+ * Extract Kimi's catalog via `kimi provider list --json`, which emits the raw
+ * providers/models config. Model ids are the `models` object keys (e.g.
+ * `kimi-code/kimi-for-coding`). The default is reported on a separate plain
+ * `Default model: <id>` line by `kimi provider list` (no flags), so we run that
+ * too to flag the default row.
+ */
+function extractKimiCatalog(binaryPath) {
+    let jsonOut;
+    try {
+        jsonOut = execFileSync(binaryPath, ['provider', 'list', '--json'], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 15_000,
+            maxBuffer: 16 * 1024 * 1024,
+        });
+    }
+    catch {
+        return { models: [], aliases: {} };
+    }
+    const firstBrace = jsonOut.indexOf('{');
+    if (firstBrace === -1)
+        return { models: [], aliases: {} };
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonOut.slice(firstBrace));
+    }
+    catch {
+        return { models: [], aliases: {} };
+    }
+    // Resolve the default model id from the plain listing's "Default model:" line.
+    let defaultId = null;
+    try {
+        const plain = execFileSync(binaryPath, ['provider', 'list'], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 10_000,
+            maxBuffer: 4 * 1024 * 1024,
+        });
+        const m = plain.match(/Default model:\s*(\S+)/);
+        if (m)
+            defaultId = m[1];
+    }
+    catch {
+        /* default flag is best-effort */
+    }
+    const modelsObj = parsed?.models && typeof parsed.models === 'object' ? parsed.models : {};
+    const models = [];
+    for (const id of Object.keys(modelsObj)) {
+        const info = modelsObj[id] ?? {};
+        models.push({
+            id,
+            displayName: typeof info.displayName === 'string' ? info.displayName : undefined,
+            isDefault: defaultId != null && id === defaultId,
+        });
+    }
+    return { models, aliases: {} };
+}
 /**
  * Build (or load from cache) the model catalog for a specific (agent, version).
  * Cache is keyed on source-file mtime (binary or js module), so re-extracts
@@ -654,6 +782,10 @@ export function getModelCatalog(agent, version) {
             ({ models, aliases } = extractCursorCatalog(src.path));
         else if (agent === 'openclaw')
             ({ models, aliases } = extractOpenClawCatalog(src.path));
+        else if (agent === 'antigravity')
+            ({ models, aliases } = extractAntigravityCatalog(src.path));
+        else if (agent === 'kimi')
+            ({ models, aliases } = extractKimiCatalog(src.path));
     }
     const catalog = {
         agent,
@@ -663,11 +795,12 @@ export function getModelCatalog(agent, version) {
         models,
         aliases,
     };
-    // Don't cache empty CLI extractions: the CLI may have been mid-install,
-    // network-dependent, or transiently failing. Caching 0 models would mask
-    // the real catalog forever (mtime won't change). Bundle/binary/js sources
-    // are deterministic, so cache those even when empty.
-    if (src.kind !== 'cli' || models.length > 0) {
+    // Never cache an empty extraction, regardless of source kind. A 0-model
+    // result is always suspect: the CLI may have been mid-install, network-
+    // dependent, or transiently failing, and a js/bundle/binary extractor that
+    // regex-misses would otherwise pin an empty catalog forever (mtime won't
+    // change until the source file does). Only persist a non-empty catalog.
+    if (models.length > 0) {
         cache.entries[key] = { sourcePath: src.path, mtime, catalog };
         saveCache();
     }

package/dist/lib/runner.js

@@ -95,14 +95,14 @@ export function buildJobCommand(config, resolvedPrompt) {
         appendModelAndReasoning(cmd, config);
     }
     if (config.agent === 'kimi') {
+        // kimi daemon jobs always run headless via `--prompt`, which cannot be
+        // combined with any startup-mode flag (--plan/--auto/--yolo all abort with
+        // "Cannot combine --prompt with --X"). edit/auto/skip reduce to kimi's default
+        // headless auto-run, so emit no flag; plan has no headless read-only
+        // equivalent, so fail closed rather than silently allowing writes.
         if (mode === 'plan') {
-            cmd.push('--plan');
-        }
-        else if (mode === 'auto') {
-            cmd.push('--auto');
-        }
-        else if (mode === 'skip') {
-            cmd.push('--yolo');
+            throw new Error('kimi has no headless read-only mode: routine jobs cannot run kimi with --mode plan ' +
+                '(kimi rejects --prompt + --plan). Use --mode edit, auto, or skip.');
         }
         appendModelAndReasoning(cmd, config);
     }

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

@@ -1,3 +1,4 @@
+import { type SessionActivity, type AwaitingReason, type DetectedPr, type DetectedWorktree, type DetectedTicket } from './state.js';
 export type ActiveContext = 'terminal' | 'teams' | 'cloud' | 'headless';
 export type ActiveStatus = 'running' | 'idle' | 'queued' | 'input_required';
 export interface ActiveSession {
@@ -12,9 +13,23 @@ export interface ActiveSession {
     label?: string;
     /** First meaningful line of the initial prompt (extracted topic). */
     topic?: string;
+    /** Live preview: the latest turn (agent message or tool action), from the state engine. */
+    preview?: string;
+    /** Inferred activity: working / waiting_input / idle (from the transcript tail). */
+    activity?: SessionActivity;
+    /** Why the agent is waiting, when activity is waiting_input. */
+    awaitingReason?: AwaitingReason;
+    /** PR opened during the session. */
+    pr?: DetectedPr;
+    /** Worktree the session runs in. */
+    worktree?: DetectedWorktree;
+    /** Tracker ticket the session is tied to. */
+    ticket?: DetectedTicket;
     sessionFile?: string;
     startedAtMs?: number;
     status: ActiveStatus;
+    /** How many live PIDs resolve to this same session (subagents/forks). 1 unless collapsed. */
+    pidCount?: number;
     teamName?: string;
     agentId?: string;
     cloudProvider?: string;