@phnx-labs/agents-cli 1.20.34 → 1.20.36

package/dist/lib/serve/data.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Read-only state assembly for `agents serve`.
+ *
+ * Reuses the SAME structured data the CLI already emits — no recomputation:
+ *  - teams: {@link handleTasks} + {@link handleStatus} + {@link toTaskStatusSummary}
+ *    (the shape behind `agents teams status --json`), plus a per-worktree
+ *    `git diff` via {@link gitDiff}.
+ *  - routines: {@link listJobs} (the shape behind `agents routines list --json`).
+ *  - cloud: {@link listTasks} from the local SQLite store (behind `agents cloud list --json`).
+ *
+ * Every panel is assembled independently: if one subsystem throws (e.g. the
+ * SQLite cloud store isn't provisioned on this box), that panel reports an
+ * `error` string and the others still render. This is an aggregator dashboard,
+ * not a fallback that hides a bug in a single code path.
+ */
+import { AgentManager } from '../teams/agents.js';
+import type { AgentStatusSummary } from '../teams/api.js';
+import type { JobConfig } from '../routines.js';
+import type { CloudTask } from '../cloud/types.js';
+/** One teammate's worktree and its current uncommitted diff. */
+export interface WorktreeDiff {
+    agent_id: string;
+    name: string | null;
+    agent_type: string;
+    status: string;
+    worktree_name: string | null;
+    worktree_path: string | null;
+    pr_url: string | null;
+    /** Uncommitted `git diff HEAD` for the worktree, capped. '' when clean/absent. */
+    diff: string;
+}
+/** One team: its per-teammate status summary plus per-worktree diffs. */
+export interface TeamPanel {
+    task_name: string;
+    agent_count: number;
+    running: number;
+    completed: number;
+    failed: number;
+    agents: AgentStatusSummary[];
+    worktrees: WorktreeDiff[];
+}
+/** A panel that either carries data or an error string (never both). */
+export type PanelResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: string;
+};
+/** The full read-only snapshot streamed to the browser. */
+export interface ServeState {
+    generated_at: string;
+    teams: PanelResult<TeamPanel[]>;
+    routines: PanelResult<JobConfig[]>;
+    cloud: PanelResult<CloudTask[]>;
+}
+/** Shape of the teammate fields needed to build a worktree diff. */
+export interface WorktreeAgentLike {
+    agentId: string;
+    name: string | null;
+    agentType: string;
+    status: string;
+    worktreeName: string | null;
+    worktreePath: string | null;
+    prUrl: string | null;
+}
+/**
+ * Build the per-worktree diffs for a set of teammates. Only teammates with a
+ * `worktreePath` produce a diff; each gets a real `git diff HEAD` via
+ * {@link gitDiff}. Pure over its inputs (no manager, no globals) so it can be
+ * unit-tested against a real temp git worktree.
+ */
+export declare function buildWorktreeDiffs(agents: WorktreeAgentLike[]): Promise<WorktreeDiff[]>;
+/**
+ * Assemble the full read-only snapshot. Each panel degrades independently to an
+ * `error` string so one unavailable subsystem never blanks the whole dashboard.
+ *
+ * @param cwd - Project root used for project-scoped routine discovery.
+ * @param manager - Injectable for tests; defaults to a fresh {@link AgentManager}.
+ */
+export declare function assembleState(cwd?: string, manager?: AgentManager): Promise<ServeState>;

package/dist/lib/serve/data.js

@@ -0,0 +1,91 @@
+/**
+ * Read-only state assembly for `agents serve`.
+ *
+ * Reuses the SAME structured data the CLI already emits — no recomputation:
+ *  - teams: {@link handleTasks} + {@link handleStatus} + {@link toTaskStatusSummary}
+ *    (the shape behind `agents teams status --json`), plus a per-worktree
+ *    `git diff` via {@link gitDiff}.
+ *  - routines: {@link listJobs} (the shape behind `agents routines list --json`).
+ *  - cloud: {@link listTasks} from the local SQLite store (behind `agents cloud list --json`).
+ *
+ * Every panel is assembled independently: if one subsystem throws (e.g. the
+ * SQLite cloud store isn't provisioned on this box), that panel reports an
+ * `error` string and the others still render. This is an aggregator dashboard,
+ * not a fallback that hides a bug in a single code path.
+ */
+import { AgentManager } from '../teams/agents.js';
+import { handleTasks, handleStatus, toTaskStatusSummary } from '../teams/api.js';
+import { gitDiff } from '../teams/worktree.js';
+import { listJobs } from '../routines.js';
+import { listTasks as listCloudTasks } from '../cloud/store.js';
+/**
+ * Build the per-worktree diffs for a set of teammates. Only teammates with a
+ * `worktreePath` produce a diff; each gets a real `git diff HEAD` via
+ * {@link gitDiff}. Pure over its inputs (no manager, no globals) so it can be
+ * unit-tested against a real temp git worktree.
+ */
+export async function buildWorktreeDiffs(agents) {
+    const withTree = agents.filter((a) => !!a.worktreePath);
+    return Promise.all(withTree.map(async (a) => ({
+        agent_id: a.agentId,
+        name: a.name,
+        agent_type: a.agentType,
+        status: a.status,
+        worktree_name: a.worktreeName,
+        worktree_path: a.worktreePath,
+        pr_url: a.prUrl,
+        diff: await gitDiff(a.worktreePath),
+    })));
+}
+/** Assemble the teams panel: overview counts, status summaries, worktree diffs. */
+async function assembleTeams(manager) {
+    const { tasks } = await handleTasks(manager, 1000);
+    const panels = [];
+    for (const t of tasks) {
+        const status = toTaskStatusSummary(await handleStatus(manager, t.task_name, 'all'));
+        const teamAgents = await manager.listByTask(t.task_name);
+        const worktrees = await buildWorktreeDiffs(teamAgents.map((a) => ({
+            agentId: a.agentId,
+            name: a.name,
+            agentType: a.agentType,
+            status: a.status,
+            worktreeName: a.worktreeName,
+            worktreePath: a.worktreePath,
+            prUrl: a.prUrl,
+        })));
+        panels.push({
+            task_name: t.task_name,
+            agent_count: t.agent_count,
+            running: t.running,
+            completed: t.completed,
+            failed: t.failed,
+            agents: status.agents,
+            worktrees,
+        });
+    }
+    return panels;
+}
+/**
+ * Assemble the full read-only snapshot. Each panel degrades independently to an
+ * `error` string so one unavailable subsystem never blanks the whole dashboard.
+ *
+ * @param cwd - Project root used for project-scoped routine discovery.
+ * @param manager - Injectable for tests; defaults to a fresh {@link AgentManager}.
+ */
+export async function assembleState(cwd = process.cwd(), manager = new AgentManager()) {
+    const [teams, routines, cloud] = await Promise.all([
+        assembleTeams(manager).then((data) => ({ ok: true, data }), (err) => ({ ok: false, error: String(err?.message ?? err) })),
+        Promise.resolve()
+            .then(() => listJobs(cwd))
+            .then((data) => ({ ok: true, data }), (err) => ({ ok: false, error: String(err?.message ?? err) })),
+        Promise.resolve()
+            .then(() => listCloudTasks({ limit: 50 }))
+            .then((data) => ({ ok: true, data }), (err) => ({ ok: false, error: String(err?.message ?? err) })),
+    ]);
+    return {
+        generated_at: new Date().toISOString(),
+        teams,
+        routines,
+        cloud,
+    };
+}

package/dist/lib/serve/page.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Self-contained HTML page for `agents serve`. No framework, no external assets
+ * — a single inline <style> + <script> that subscribes to /events (SSE) and
+ * re-renders the panels on each snapshot. Terminal-coded per the agents-cli
+ * brand: #0a0a0a bg, #a3e635 lime accent, JetBrains Mono.
+ */
+export declare function renderPage(): string;

package/dist/lib/serve/page.js

@@ -0,0 +1,140 @@
+/**
+ * Self-contained HTML page for `agents serve`. No framework, no external assets
+ * — a single inline <style> + <script> that subscribes to /events (SSE) and
+ * re-renders the panels on each snapshot. Terminal-coded per the agents-cli
+ * brand: #0a0a0a bg, #a3e635 lime accent, JetBrains Mono.
+ */
+export function renderPage() {
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>agents serve</title>
+<style>
+  :root {
+    --bg: #0a0a0a; --panel: #121212; --border: #262626; --fg: #e5e5e5;
+    --dim: #737373; --accent: #a3e635; --add: #4ade80; --del: #f87171; --hunk: #60a5fa;
+  }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; background: var(--bg); color: var(--fg);
+    font-family: ui-monospace, "JetBrains Mono", "SF Mono", Menlo, monospace;
+    font-size: 13px; line-height: 1.5;
+  }
+  header {
+    position: sticky; top: 0; z-index: 10; background: var(--bg);
+    border-bottom: 1px solid var(--border); padding: 12px 20px;
+    display: flex; align-items: center; gap: 12px;
+  }
+  header .mark { color: var(--accent); font-weight: 700; letter-spacing: .5px; }
+  header .status { color: var(--dim); }
+  header .dot { display: inline-block; width: 8px; height: 8px; border-radius: 50%; background: var(--del); margin-right: 6px; vertical-align: middle; }
+  header .dot.live { background: var(--accent); }
+  main { padding: 20px; max-width: 1100px; margin: 0 auto; display: grid; gap: 24px; }
+  h2 { font-size: 14px; color: var(--accent); border-bottom: 1px solid var(--border); padding-bottom: 6px; margin: 0 0 12px; text-transform: uppercase; letter-spacing: 1px; }
+  .card { background: var(--panel); border: 1px solid var(--border); border-radius: 6px; padding: 14px; margin-bottom: 12px; }
+  .row { display: flex; justify-content: space-between; gap: 12px; flex-wrap: wrap; }
+  .muted { color: var(--dim); }
+  .badge { font-size: 11px; padding: 1px 7px; border-radius: 10px; border: 1px solid var(--border); }
+  .badge.running { color: var(--accent); border-color: var(--accent); }
+  .badge.completed { color: var(--add); border-color: var(--add); }
+  .badge.failed { color: var(--del); border-color: var(--del); }
+  a { color: var(--hunk); text-decoration: none; }
+  a:hover { text-decoration: underline; }
+  details { margin-top: 8px; }
+  summary { cursor: pointer; color: var(--dim); }
+  pre.diff { overflow-x: auto; background: #0d0d0d; border: 1px solid var(--border); border-radius: 4px; padding: 10px; margin: 8px 0 0; white-space: pre; }
+  pre.diff .a { color: var(--add); } pre.diff .d { color: var(--del); } pre.diff .h { color: var(--hunk); } pre.diff .m { color: var(--dim); }
+  .err { color: var(--del); }
+  .empty { color: var(--dim); font-style: italic; }
+  table { width: 100%; border-collapse: collapse; }
+  td, th { text-align: left; padding: 4px 8px; border-bottom: 1px solid var(--border); vertical-align: top; }
+  th { color: var(--dim); font-weight: 500; }
+</style>
+</head>
+<body>
+<header>
+  <span class="mark">agents serve</span>
+  <span class="status"><span class="dot" id="dot"></span><span id="conn">connecting…</span></span>
+  <span class="status" id="ts"></span>
+</header>
+<main>
+  <section><h2>Teams &amp; Diffs</h2><div id="teams"></div></section>
+  <section><h2>Routines</h2><div id="routines"></div></section>
+  <section><h2>Cloud</h2><div id="cloud"></div></section>
+</main>
+<script>
+const $ = (id) => document.getElementById(id);
+const esc = (s) => String(s == null ? '' : s).replace(/[&<>"]/g, (c) => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;'}[c]));
+// href allowlist: only http(s) URLs are linkable. esc() blocks attribute
+// breakout, but a javascript:/data: URL would still execute on click — so a
+// non-http(s) pr_url renders as an inert '#' rather than a live link.
+const safeUrl = (u) => { const s = String(u == null ? '' : u); return /^https?:\\/\\//i.test(s) ? s : '#'; };
+function colorDiff(text) {
+  return esc(text).split('\\n').map((line) => {
+    if (line.startsWith('+')) return '<span class="a">' + line + '</span>';
+    if (line.startsWith('-')) return '<span class="d">' + line + '</span>';
+    if (line.startsWith('@@')) return '<span class="h">' + line + '</span>';
+    if (line.startsWith('diff ') || line.startsWith('index ')) return '<span class="m">' + line + '</span>';
+    return line;
+  }).join('\\n');
+}
+function panelError(el, error) { el.innerHTML = '<div class="card err">error: ' + esc(error) + '</div>'; }
+
+function renderTeams(res) {
+  const el = $('teams');
+  if (!res.ok) return panelError(el, res.error);
+  if (!res.data.length) { el.innerHTML = '<div class="empty">no teams</div>'; return; }
+  el.innerHTML = res.data.map((t) => {
+    const agents = t.agents.map((a) =>
+      '<div class="row"><span>' + esc(a.name || a.agent_id.slice(0,8)) +
+      ' <span class="muted">' + esc(a.agent_type) + '</span>' +
+      (a.pr_url ? ' <a href="' + esc(safeUrl(a.pr_url)) + '" target="_blank">PR</a>' : '') +
+      '</span><span class="badge ' + esc(a.status) + '">' + esc(a.status) + '</span></div>'
+    ).join('');
+    const worktrees = t.worktrees.map((w) => {
+      const body = w.diff
+        ? '<details><summary>diff · ' + esc(w.worktree_name || w.worktree_path) + '</summary><pre class="diff">' + colorDiff(w.diff) + '</pre></details>'
+        : '<div class="muted">' + esc(w.worktree_name || w.worktree_path) + ' — no uncommitted changes</div>';
+      return body;
+    }).join('');
+    return '<div class="card"><div class="row"><strong>' + esc(t.task_name) + '</strong>' +
+      '<span class="muted">' + t.running + ' running · ' + t.completed + ' done · ' + t.failed + ' failed</span></div>' +
+      agents + worktrees + '</div>';
+  }).join('');
+}
+function renderRoutines(res) {
+  const el = $('routines');
+  if (!res.ok) return panelError(el, res.error);
+  if (!res.data.length) { el.innerHTML = '<div class="empty">no routines</div>'; return; }
+  el.innerHTML = '<div class="card"><table><tr><th>name</th><th>schedule</th><th>agent</th><th>enabled</th></tr>' +
+    res.data.map((j) => '<tr><td>' + esc(j.name) + '</td><td class="muted">' + esc(j.schedule) + '</td><td>' +
+      esc(j.workflow ? 'wf:' + j.workflow : j.agent) + '</td><td>' + (j.enabled ? 'yes' : '<span class="muted">no</span>') + '</td></tr>').join('') +
+    '</table></div>';
+}
+function renderCloud(res) {
+  const el = $('cloud');
+  if (!res.ok) return panelError(el, res.error);
+  if (!res.data.length) { el.innerHTML = '<div class="empty">no cloud tasks</div>'; return; }
+  el.innerHTML = '<div class="card"><table><tr><th>id</th><th>provider</th><th>status</th><th>repo</th><th></th></tr>' +
+    res.data.map((c) => '<tr><td>' + esc(c.id.slice(0,10)) + '</td><td>' + esc(c.provider) + '</td><td><span class="badge ' + esc(c.status) + '">' +
+      esc(c.status) + '</span></td><td class="muted">' + esc(c.repo || '') + '</td><td>' +
+      (c.prUrl ? '<a href="' + esc(safeUrl(c.prUrl)) + '" target="_blank">PR</a>' : '') + '</td></tr>').join('') +
+    '</table></div>';
+}
+function render(state) {
+  renderTeams(state.teams); renderRoutines(state.routines); renderCloud(state.cloud);
+  $('ts').textContent = 'updated ' + new Date(state.generated_at).toLocaleTimeString();
+}
+function setConn(live) {
+  $('dot').className = 'dot' + (live ? ' live' : '');
+  $('conn').textContent = live ? 'live' : 'reconnecting…';
+}
+const src = new EventSource('/events');
+src.addEventListener('state', (e) => { setConn(true); render(JSON.parse(e.data)); });
+src.onerror = () => setConn(false);
+</script>
+</body>
+</html>`;
+}

package/dist/lib/serve/server.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Read-only localhost HTTP + Server-Sent-Events server for `agents serve`.
+ *
+ * There is deliberately NO framework and NO mutation surface:
+ *  - binds 127.0.0.1 only (loopback) — never reachable off the machine;
+ *  - answers GET only (every other method → 405);
+ *  - routes: `GET /` → HTML page, `GET /api/state` → JSON snapshot,
+ *    `GET /events` → SSE stream that re-pushes the snapshot on an interval.
+ *
+ * The whole thing is a viewer over data other commands already own
+ * ({@link assembleState}); it writes nothing.
+ */
+import http from 'http';
+import type { ServeState } from './data.js';
+/** Loopback address — the server binds here and nowhere else. */
+export declare const SERVE_HOST = "127.0.0.1";
+/** Default port for `agents serve`. */
+export declare const DEFAULT_SERVE_PORT = 4477;
+/** Default SSE push cadence. */
+export declare const DEFAULT_INTERVAL_MS = 3000;
+export interface ServeOptions {
+    /** Project root for project-scoped routine discovery. Defaults to process.cwd(). */
+    cwd?: string;
+    /** SSE push cadence in ms. Defaults to {@link DEFAULT_INTERVAL_MS}. */
+    intervalMs?: number;
+    /**
+     * Snapshot data source. Defaults to {@link assembleState}. Read-only DI seam
+     * so tests can drive SSE lifecycle timing deterministically (e.g. gate the
+     * first snapshot to reproduce a mid-snapshot disconnect); production never
+     * sets it.
+     */
+    snapshot?: () => Promise<ServeState>;
+}
+/**
+ * Create (but do not start) the read-only serve server. Caller invokes
+ * `.listen(port, SERVE_HOST)`. Returned so tests can bind an ephemeral port.
+ */
+export declare function createServeServer(opts?: ServeOptions): http.Server;
+/**
+ * Start the serve server on `port`, bound to loopback. Resolves with the
+ * actual bound port (useful when `port === 0` for tests).
+ */
+export declare function startServeServer(port?: number, opts?: ServeOptions): Promise<{
+    server: http.Server;
+    port: number;
+}>;

package/dist/lib/serve/server.js

@@ -0,0 +1,115 @@
+/**
+ * Read-only localhost HTTP + Server-Sent-Events server for `agents serve`.
+ *
+ * There is deliberately NO framework and NO mutation surface:
+ *  - binds 127.0.0.1 only (loopback) — never reachable off the machine;
+ *  - answers GET only (every other method → 405);
+ *  - routes: `GET /` → HTML page, `GET /api/state` → JSON snapshot,
+ *    `GET /events` → SSE stream that re-pushes the snapshot on an interval.
+ *
+ * The whole thing is a viewer over data other commands already own
+ * ({@link assembleState}); it writes nothing.
+ */
+import http from 'http';
+import { assembleState } from './data.js';
+import { renderPage } from './page.js';
+/** Loopback address — the server binds here and nowhere else. */
+export const SERVE_HOST = '127.0.0.1';
+/** Default port for `agents serve`. */
+export const DEFAULT_SERVE_PORT = 4477;
+/** Default SSE push cadence. */
+export const DEFAULT_INTERVAL_MS = 3000;
+/**
+ * Create (but do not start) the read-only serve server. Caller invokes
+ * `.listen(port, SERVE_HOST)`. Returned so tests can bind an ephemeral port.
+ */
+export function createServeServer(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const intervalMs = opts.intervalMs ?? DEFAULT_INTERVAL_MS;
+    const snapshot = opts.snapshot ?? (() => assembleState(cwd));
+    const server = http.createServer(async (req, res) => {
+        // Read-only: reject anything that could mutate. Only GET is served.
+        if (req.method !== 'GET') {
+            res.writeHead(405, { 'content-type': 'text/plain', allow: 'GET' });
+            res.end('method not allowed');
+            return;
+        }
+        const url = (req.url || '/').split('?')[0];
+        if (url === '/' || url === '/index.html') {
+            const html = renderPage();
+            res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+            res.end(html);
+            return;
+        }
+        if (url === '/api/state') {
+            try {
+                const state = await snapshot();
+                res.writeHead(200, { 'content-type': 'application/json; charset=utf-8' });
+                res.end(JSON.stringify(state));
+            }
+            catch (err) {
+                res.writeHead(500, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ error: String(err?.message ?? err) }));
+            }
+            return;
+        }
+        if (url === '/events') {
+            res.writeHead(200, {
+                'content-type': 'text/event-stream',
+                'cache-control': 'no-cache',
+                connection: 'keep-alive',
+            });
+            let closed = false;
+            // Declare the timer first and register the disconnect cleanup BEFORE the
+            // first `await push()`. `assembleState()` (team scan + git diffs) can be
+            // slow; if the client disconnects during it, the one-shot 'close' must
+            // already have a listener — otherwise it fires into the void, the interval
+            // starts anyway, and we leak a timer writing to a destroyed socket forever.
+            let timer;
+            req.on('close', () => {
+                closed = true;
+                if (timer)
+                    clearInterval(timer);
+            });
+            const push = async () => {
+                if (closed)
+                    return;
+                try {
+                    const state = await snapshot();
+                    if (closed)
+                        return;
+                    res.write(`event: state\ndata: ${JSON.stringify(state)}\n\n`);
+                }
+                catch (err) {
+                    if (!closed)
+                        res.write(`event: error\ndata: ${JSON.stringify({ error: String(err) })}\n\n`);
+                }
+            };
+            await push(); // immediate first frame
+            // Only arm the interval if the client is still connected. If 'close' fired
+            // during the first push, `closed` is already true (and the handler ran
+            // while `timer` was undefined), so starting an interval here would leak.
+            if (!closed)
+                timer = setInterval(push, intervalMs);
+            return;
+        }
+        res.writeHead(404, { 'content-type': 'text/plain' });
+        res.end('not found');
+    });
+    return server;
+}
+/**
+ * Start the serve server on `port`, bound to loopback. Resolves with the
+ * actual bound port (useful when `port === 0` for tests).
+ */
+export function startServeServer(port = DEFAULT_SERVE_PORT, opts = {}) {
+    const server = createServeServer(opts);
+    return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, SERVE_HOST, () => {
+            const addr = server.address();
+            const boundPort = typeof addr === 'object' && addr ? addr.port : port;
+            resolve({ server, port: boundPort });
+        });
+    });
+}

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

@@ -1,5 +1,13 @@
+import { type PidSessionEntry } from './pid-registry.js';
 import { type SessionActivity, type AwaitingReason, type DetectedPr, type DetectedWorktree, type DetectedTicket } from './state.js';
 import { type SessionProvenance } from './provenance.js';
+/**
+ * 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
+ * (CrowdStrike Falcon) as lateral-movement recon. Results are identical — the
+ * cwds are just gathered at a bounded spawn rate instead of a single burst.
+ */
+export declare const LSOF_CONCURRENCY = 4;
 export type ActiveContext = 'terminal' | 'teams' | 'cloud' | 'headless';
 export type ActiveStatus = 'running' | 'idle' | 'queued' | 'input_required';
 export interface ActiveSession {
@@ -38,6 +46,13 @@ export interface ActiveSession {
      * Absent for cloud sessions (no local pid) and any pid whose env is unreadable.
      */
     provenance?: SessionProvenance;
+    /**
+     * The machine this session runs on, as a normalized device id (machineId()
+     * form). Set when merging cross-machine results so the grouped `--active`
+     * view can bucket by computer. Absent for a purely local query (the renderer
+     * falls back to provenance.host, then the local machine).
+     */
+    machine?: string;
     teamName?: string;
     agentId?: string;
     cloudProvider?: string;
@@ -62,6 +77,51 @@ export declare function listTeamsActive(): Promise<ActiveSession[]>;
 export declare function listTerminalsActive(): Promise<ActiveSession[]>;
 /** Cloud tasks still in a non-terminal state. `tasks.db` may not exist; that's fine. */
 export declare function listCloudActive(): ActiveSession[];
+interface ProcRow {
+    pid: number;
+    ppid: number;
+    comm: string;
+    kind?: string;
+}
+/** Parse `ConvertTo-Csv` output of Win32_Process rows. Exported for tests. */
+export declare function parseWin32ProcessCsv(out: string): ProcRow[];
+/**
+ * Resolve every candidate PID's cwd, bounded and staggered so the probes no
+ * longer fan out as one simultaneous system-wide `lsof` burst (a behavioral-EDR
+ * recon trigger). Order matches the input `pids`. The `probe` seam is injectable
+ * for testing the bound; production always uses the real `lsof`-backed probe.
+ */
+export declare function resolveCwds(pids: number[], probe?: (pid: number) => Promise<string | undefined>): Promise<(string | undefined)[]>;
+export interface AgentCandidate {
+    pid: number;
+    kind: string;
+}
+/**
+ * Find the launch registry entry recorded by a WRAPPER of this process. The
+ * shim delegate records the pid it spawned, but on Windows the `.cmd` shell
+ * path makes that a cmd.exe intermediary whose child is the real agent binary
+ * — so the agent pid itself has no entry and the wrapper one ancestor up does.
+ * The nearest entry wins, and only if its agent matches the candidate's kind:
+ * a claude session shelling out to codex must not hand codex its identity.
+ */
+export declare function readAncestorSessionEntry(pid: number, ppidMap: Map<number, number>, kind: string, readEntry?: (pid: number) => PidSessionEntry | undefined): PidSessionEntry | undefined;
+/**
+ * Collapse agent processes spawned by another live agent process of the same
+ * kind onto their nearest kept ancestor. Claude runs subagents, forks, and
+ * even its bundled ripgrep as child `claude` processes — on POSIX those
+ * children resolve to the parent's cwd and collapse in dedupeBySession, but
+ * where no cwd can be recovered (Windows has no lsof) every fork would print
+ * 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).
+ * Returns the kept roots plus, per root pid, how many descendants folded in.
+ */
+export declare function foldSubordinateAgents(candidates: AgentCandidate[], ppidMap: Map<number, number>, readEntry: (pid: number) => PidSessionEntry | undefined): {
+    kept: AgentCandidate[];
+    foldedByRoot: Map<number, number>;
+};
 /**
  * Agent processes not attributed to a team or the runtime registry.
  * Classified by walking the ppid chain: any recognised UI ancestor (IDE
@@ -75,3 +135,4 @@ export declare function listUnattributedActive(attributed: Set<number>): Promise
  * already-attributed PIDs removed.
  */
 export declare function getActiveSessions(opts?: ActiveQueryOptions): Promise<ActiveSession[]>;
+export {};