@openparachute/agent 0.1.2 → 0.2.0

package/src/oauth/state-store.test.ts

@@ -1,54 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-
-import { closeDb, initTestDb, runMigrations } from '../db/index.js';
-import { clearStateStore, consumeState, mintState, stateStoreSize } from './state-store.js';
-
-beforeEach(() => {
-  const db = initTestDb();
-  runMigrations(db);
-});
-
-afterEach(() => {
-  clearStateStore();
-  closeDb();
-});
-
-describe('oauth state-store', () => {
-  it('mints unique opaque tokens', () => {
-    const a = mintState({ provider: 'google', redirectUri: 'http://x/cb' });
-    const b = mintState({ provider: 'google', redirectUri: 'http://x/cb' });
-    expect(a).not.toBe(b);
-    expect(a.length).toBeGreaterThan(20);
-  });
-
-  it('round-trips context on consume', () => {
-    const state = mintState({
-      provider: 'google',
-      agentGroupId: 'grp-1',
-      redirectUri: 'http://x/cb',
-    });
-    const ctx = consumeState(state);
-    expect(ctx).toBeDefined();
-    expect(ctx?.provider).toBe('google');
-    expect(ctx?.agentGroupId).toBe('grp-1');
-    expect(ctx?.redirectUri).toBe('http://x/cb');
-  });
-
-  it('is single-use — second consume returns undefined', () => {
-    const state = mintState({ provider: 'google', redirectUri: 'http://x/cb' });
-    expect(consumeState(state)).toBeDefined();
-    expect(consumeState(state)).toBeUndefined();
-  });
-
-  it('returns undefined for unknown state', () => {
-    expect(consumeState('never-minted')).toBeUndefined();
-  });
-
-  it('treats expired entries as missing', () => {
-    const state = mintState({ provider: 'google', redirectUri: 'http://x/cb' });
-    // Simulate expiry via clear; consume of arbitrary key returns undefined.
-    clearStateStore();
-    expect(consumeState(state)).toBeUndefined();
-    expect(stateStoreSize()).toBe(0);
-  });
-});

package/src/oauth/state-store.ts

@@ -1,93 +0,0 @@
-/**
- * DB-backed OAuth state store. The `state` parameter passed in the
- * authorize redirect is a CSPRNG-random opaque string mapped here to
- * the originating context (provider, optional agentGroupId, redirect
- * URI, expires_at). Single-use: a state consumed at callback can never
- * be replayed.
- *
- * DB-backed (vs in-memory) so that a daemon restart between authorize
- * and callback doesn't drop the user's flow — they finish in their
- * browser, the callback hits a fresh process, and the row is still
- * there.
- */
-import crypto from 'crypto';
-
-import { getDb } from '../db/connection.js';
-import type { Database } from '../db/connection.js';
-
-const TTL_MS = 10 * 60 * 1000;
-
-export interface OauthStateContext {
-  provider: string;
-  agentGroupId: string | null;
-  redirectUri: string;
-  expiresAt: string;
-}
-
-interface PendingStateRow {
-  state: string;
-  provider: string;
-  agent_group_id: string | null;
-  redirect_uri: string;
-  created_at: string;
-  expires_at: string;
-}
-
-function db(): Database {
-  return getDb();
-}
-
-export function mintState(ctx: { provider: string; agentGroupId?: string | null; redirectUri: string }): string {
-  const state = crypto.randomBytes(24).toString('base64url');
-  const now = new Date();
-  const expires = new Date(now.getTime() + TTL_MS);
-  db()
-    .prepare(
-      `INSERT INTO pending_oauth_states
-         (state, provider, agent_group_id, redirect_uri, created_at, expires_at)
-       VALUES
-         (@state, @provider, @agent_group_id, @redirect_uri, @created_at, @expires_at)`,
-    )
-    .run({
-      state,
-      provider: ctx.provider,
-      agent_group_id: ctx.agentGroupId ?? null,
-      redirect_uri: ctx.redirectUri,
-      created_at: now.toISOString(),
-      expires_at: expires.toISOString(),
-    });
-  return state;
-}
-
-/** Single-use: returns the context and atomically removes the row. Expired rows return undefined. */
-export function consumeState(state: string): OauthStateContext | undefined {
-  const row = db().prepare<PendingStateRow>(`SELECT * FROM pending_oauth_states WHERE state = @state`).get({ state });
-  if (!row) return undefined;
-  db().prepare(`DELETE FROM pending_oauth_states WHERE state = @state`).run({ state });
-  if (new Date(row.expires_at).getTime() < Date.now()) return undefined;
-  return {
-    provider: row.provider,
-    agentGroupId: row.agent_group_id,
-    redirectUri: row.redirect_uri,
-    expiresAt: row.expires_at,
-  };
-}
-
-/** Sweeper — deletes any state past its TTL. Returns rows removed. Called from host-sweep. */
-export function sweepExpiredStates(): number {
-  const r = db()
-    .prepare(`DELETE FROM pending_oauth_states WHERE expires_at < @now`)
-    .run({ now: new Date().toISOString() });
-  return r.changes;
-}
-
-/** Test seam: drop everything. */
-export function clearStateStore(): void {
-  db().prepare(`DELETE FROM pending_oauth_states`).run();
-}
-
-/** Test seam: how many live entries (for assertion). */
-export function stateStoreSize(): number {
-  const r = db().prepare<{ n: number }>(`SELECT COUNT(*) AS n FROM pending_oauth_states`).get();
-  return r?.n ?? 0;
-}

package/src/parachute/README.md

@@ -1,27 +0,0 @@
-# src/parachute/
-
-Parachute Vault integration for Paraclaw.
-
-## What this brings
-
-Each Paraclaw agent group gets optional access to a [Parachute Vault](https://github.com/ParachuteComputer/parachute-vault). The vault is the user's open knowledge graph — notes, tags, links, structured metadata — already running on their machine and already used by every other AI client they've connected (Claude Code, Notes, etc.).
-
-Composing the two:
-
-- **Each claw gets a scoped vault token** (`vault:read` / `vault:write` / `vault:admin`) at attach time. Token-as-capability is the boundary; the agent literally can't exceed its scope.
-- **The vault MCP server is wired into the agent's container** as an `http` transport entry in `container.json`. The agent uses the same nine MCP tools any other Parachute client gets (`query-notes`, `create-note`, `update-note`, etc.).
-- **What the claw does with vault access is up to the claw.** This integration grants capability; it doesn't dictate convention. A claw might write nothing to vault (read-only researcher); another might capture every message into structured note paths; another might not use vault at all even though it has access. The framework is opinion-free here.
-
-## Files
-
-- **`vault-mcp.ts`** — pure helpers: `buildVaultMcpServer(opts)` constructs the `McpServerConfig` for a vault attach, `attachVaultToGroup(folder, opts)` upserts that entry into the group's `container.json`, `detachVaultFromGroup(folder, name)` removes it.
-- **`types.ts`** — narrow types for vault attachments + scope strings.
-- **`create-agent.ts`** — single-call agent group creation used by the web wizard.
-- **`group-status.ts`** — heartbeat-based liveness probe for the UI.
-
-The matching CLI surface lives in [`scripts/parachute.ts`](../../scripts/parachute.ts) (`pnpm run parachute attach-vault <group>` etc.).
-
-## What we deliberately do NOT do here
-
-- **No vault note path conventions.** No `claws/<name>` tree, no auto-mirroring of agent runs to vault, no auto-CLAUDE.md sync. Those would impose a vault layout on every user; we don't.
-- **No replacement of the SQLite session queues.** Per-session `inbound.db` / `outbound.db` are the right pattern for transient message handling. Vault is for durable, queryable, user-facing state — different concern.

package/src/parachute/create-agent.test.ts

@@ -1,83 +0,0 @@
-/**
- * Tests for `createParachuteAgentGroup` — focused on the default vault
- * token label. The web/server `POST /api/agent-groups` path was caught in
- * the 0.1.0 sweep, but the programmatic surface in this module — used by
- * the MCP tool `create-agent-group` and any caller that hits the helper
- * directly — needs the same `agent-${folder}` default. Reviewer caught this
- * miss on PR #112.
- */
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-
-vi.mock('./vault-mcp.js', async () => {
-  const actual = await vi.importActual<typeof import('./vault-mcp.js')>('./vault-mcp.js');
-  return {
-    ...actual,
-    attachVaultToGroup: vi.fn(),
-    readVaultAttachment: vi.fn(() => null),
-  };
-});
-
-vi.mock('../db/agent-groups.js', () => ({
-  createAgentGroup: vi.fn(),
-  getAgentGroupByFolder: vi.fn(() => undefined),
-}));
-
-vi.mock('../group-init.js', () => ({
-  initGroupFilesystem: vi.fn(),
-}));
-
-let createParachuteAgentGroup: typeof import('./create-agent.js').createParachuteAgentGroup;
-let attachVaultToGroup: ReturnType<typeof vi.fn>;
-
-beforeEach(async () => {
-  vi.resetModules();
-  ({ createParachuteAgentGroup } = await import('./create-agent.js'));
-  ({ attachVaultToGroup } = (await import('./vault-mcp.js')) as unknown as {
-    attachVaultToGroup: ReturnType<typeof vi.fn>;
-  });
-  attachVaultToGroup.mockClear();
-});
-
-afterEach(() => {
-  vi.clearAllMocks();
-});
-
-describe('createParachuteAgentGroup default vault token label', () => {
-  it('defaults to `agent-${folder}` when caller omits tokenLabel', () => {
-    createParachuteAgentGroup({
-      name: 'Forge',
-      folder: 'forge',
-      vault: {
-        scope: 'vault:read',
-        token: 'pvt_test',
-      },
-    });
-
-    expect(attachVaultToGroup).toHaveBeenCalledTimes(1);
-    expect(attachVaultToGroup.mock.calls[0]![0]).toMatchObject({
-      folder: 'forge',
-      tokenLabel: 'agent-forge',
-    });
-  });
-
-  it('respects an explicit tokenLabel override (e.g. operator-typed `claw-`)', () => {
-    createParachuteAgentGroup({
-      name: 'Forge',
-      folder: 'forge',
-      vault: {
-        scope: 'vault:read',
-        token: 'pvt_test',
-        tokenLabel: 'claw-forge',
-      },
-    });
-
-    expect(attachVaultToGroup.mock.calls[0]![0]).toMatchObject({
-      tokenLabel: 'claw-forge',
-    });
-  });
-
-  it('does not call attachVaultToGroup when no vault opts are passed', () => {
-    createParachuteAgentGroup({ name: 'Solo', folder: 'solo' });
-    expect(attachVaultToGroup).not.toHaveBeenCalled();
-  });
-});

package/src/parachute/create-agent.ts

@@ -1,122 +0,0 @@
-/**
- * Create a Parachute agent group from a single call.
- *
- * Wraps the central-DB write (`createAgentGroup`) and on-disk init
- * (`initGroupFilesystem`) into one shim, with optional inline vault
- * attachment via `attachVaultToGroup`. Channel wiring is intentionally NOT
- * here — the wizard creates a channel-less group; channel install is its
- * own surface (paraclaw#2).
- */
-import { createAgentGroup as dbCreateAgentGroup, getAgentGroupByFolder } from '../db/agent-groups.js';
-import { initGroupFilesystem } from '../group-init.js';
-import { normalizeName } from '../modules/agent-to-agent/db/agent-destinations.js';
-import type { AgentGroup } from '../types.js';
-
-import type { VaultAttachment, VaultScope } from './types.js';
-import { attachVaultToGroup, readVaultAttachment } from './vault-mcp.js';
-
-const FOLDER_RE = /^[a-z0-9](?:[a-z0-9-]{0,46}[a-z0-9])?$/;
-const FOLDER_MAX = 48;
-
-export interface FolderValidationOk {
-  ok: true;
-}
-export interface FolderValidationFail {
-  ok: false;
-  reason: string;
-}
-export type FolderValidation = FolderValidationOk | FolderValidationFail;
-
-export function validateFolderSlug(slug: string): FolderValidation {
-  if (!slug) return { ok: false, reason: 'folder slug is required' };
-  if (slug.length > FOLDER_MAX) {
-    return { ok: false, reason: `folder slug must be ≤ ${FOLDER_MAX} chars` };
-  }
-  if (!FOLDER_RE.test(slug)) {
-    return {
-      ok: false,
-      reason: 'folder slug must be lowercase letters, digits, and dashes; cannot start or end with a dash',
-    };
-  }
-  return { ok: true };
-}
-
-export function suggestFolderSlug(name: string): string {
-  return normalizeName(name).slice(0, FOLDER_MAX);
-}
-
-export function isFolderTaken(folder: string): boolean {
-  return getAgentGroupByFolder(folder) !== undefined;
-}
-
-export interface CreateAgentGroupVaultOpts {
-  scope: VaultScope;
-  vaultBaseUrl?: string;
-  tokenLabel?: string;
-  /** If absent, callers higher up the stack mint via `parachute vault tokens create`. */
-  token: string;
-  mcpName?: string;
-  instructions?: string;
-}
-
-export interface CreateAgentGroupOpts {
-  name: string;
-  folder: string;
-  instructions?: string;
-  /** Optional inline vault attachment. The token must already be in hand. */
-  vault?: CreateAgentGroupVaultOpts;
-}
-
-export interface CreateAgentGroupResult {
-  group: AgentGroup;
-  vault: VaultAttachment | null;
-}
-
-/**
- * Create a new agent group: validate, write DB row, initialize filesystem,
- * optionally attach a vault. NOT idempotent — `isFolderTaken` is the gate
- * the caller must check; this throws if the folder already exists.
- */
-export function createParachuteAgentGroup(opts: CreateAgentGroupOpts): CreateAgentGroupResult {
-  const folderCheck = validateFolderSlug(opts.folder);
-  if (!folderCheck.ok) {
-    throw new Error(`invalid folder slug: ${folderCheck.reason}`);
-  }
-  const trimmedName = opts.name.trim();
-  if (!trimmedName) {
-    throw new Error('agent name is required');
-  }
-  if (isFolderTaken(opts.folder)) {
-    throw new Error(`agent group folder already exists: ${opts.folder}`);
-  }
-
-  const id = `ag-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-  const created_at = new Date().toISOString();
-  const group: AgentGroup = {
-    id,
-    name: trimmedName,
-    folder: opts.folder,
-    agent_provider: null,
-    secret_mode: 'selective',
-    created_at,
-  };
-
-  dbCreateAgentGroup(group);
-  initGroupFilesystem(group, { instructions: opts.instructions });
-
-  let vault: VaultAttachment | null = null;
-  if (opts.vault) {
-    attachVaultToGroup({
-      folder: group.folder,
-      vaultBaseUrl: opts.vault.vaultBaseUrl ?? 'http://127.0.0.1:1940/vault/default',
-      vaultToken: opts.vault.token,
-      scope: opts.vault.scope,
-      tokenLabel: opts.vault.tokenLabel ?? `agent-${group.folder}`,
-      mcpName: opts.vault.mcpName,
-      instructions: opts.vault.instructions,
-    });
-    vault = readVaultAttachment(group.folder, opts.vault.mcpName);
-  }
-
-  return { group, vault };
-}

package/src/parachute/group-status.test.ts

@@ -1,165 +0,0 @@
-/**
- * Tests for getGroupStatus — the helper the web server uses to compute
- * "is this agent group's container alive?" without depending on
- * container-runner.ts's in-memory map (different process from web server).
- */
-import { openDb } from '../db/connection.js';
-import fs from 'node:fs';
-import path from 'node:path';
-
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-
-vi.mock('../config.js', async () => {
-  const actual = await vi.importActual('../config.js');
-  return { ...actual, DATA_DIR: '/tmp/paraclaw-group-status-test' };
-});
-
-const TEST_DIR = '/tmp/paraclaw-group-status-test';
-
-let initTestDb: typeof import('../db/index.js').initTestDb;
-let closeDb: typeof import('../db/index.js').closeDb;
-let runMigrations: typeof import('../db/index.js').runMigrations;
-let createAgentGroup: typeof import('../db/index.js').createAgentGroup;
-let createSession: typeof import('../db/sessions.js').createSession;
-let getGroupStatus: typeof import('./group-status.js').getGroupStatus;
-let inboundDbPath: typeof import('../session-manager.js').inboundDbPath;
-let outboundDbPath: typeof import('../session-manager.js').outboundDbPath;
-let heartbeatPath: typeof import('../session-manager.js').heartbeatPath;
-let INBOUND_SCHEMA: string;
-let OUTBOUND_SCHEMA: string;
-
-beforeEach(async () => {
-  if (fs.existsSync(TEST_DIR)) fs.rmSync(TEST_DIR, { recursive: true });
-  fs.mkdirSync(TEST_DIR, { recursive: true });
-
-  // Imported lazily so the config.js mock is in effect when modules cache it.
-  ({ initTestDb, closeDb, runMigrations, createAgentGroup } = await import('../db/index.js'));
-  ({ createSession } = await import('../db/sessions.js'));
-  ({ getGroupStatus } = await import('./group-status.js'));
-  ({ inboundDbPath, outboundDbPath, heartbeatPath } = await import('../session-manager.js'));
-  ({ INBOUND_SCHEMA, OUTBOUND_SCHEMA } = await import('../db/schema.js'));
-
-  const db = initTestDb();
-  runMigrations(db);
-
-  createAgentGroup({
-    id: 'ag-1',
-    name: 'Forge',
-    folder: 'forge',
-    agent_provider: null,
-    created_at: '2026-04-27T00:00:00.000Z',
-  });
-});
-
-afterEach(() => {
-  closeDb();
-  if (fs.existsSync(TEST_DIR)) fs.rmSync(TEST_DIR, { recursive: true });
-});
-
-function makeSession(id: string) {
-  createSession({
-    id,
-    agent_group_id: 'ag-1',
-    messaging_group_id: null,
-    thread_id: null,
-    agent_provider: null,
-    status: 'active',
-    container_status: 'running',
-    last_active: '2026-04-27T00:00:00.000Z',
-    created_at: '2026-04-27T00:00:00.000Z',
-  });
-  fs.mkdirSync(path.dirname(heartbeatPath('ag-1', id)), { recursive: true });
-}
-
-function writeHeartbeat(sessionId: string, mtimeMs: number) {
-  const p = heartbeatPath('ag-1', sessionId);
-  fs.writeFileSync(p, '');
-  fs.utimesSync(p, mtimeMs / 1000, mtimeMs / 1000);
-}
-
-function seedInboundDb(sessionId: string, lastTimestamp: string) {
-  const dbPath = inboundDbPath('ag-1', sessionId);
-  const db = openDb(dbPath);
-  db.exec(INBOUND_SCHEMA);
-  db.prepare("INSERT INTO messages_in (id, kind, timestamp, content) VALUES ('m1', 'msg', ?, '{}')").run(lastTimestamp);
-  db.close();
-}
-
-function seedOutboundDb(sessionId: string, lastTimestamp: string) {
-  const dbPath = outboundDbPath('ag-1', sessionId);
-  const db = openDb(dbPath);
-  db.exec(OUTBOUND_SCHEMA);
-  db.prepare("INSERT INTO messages_out (id, kind, timestamp, content) VALUES ('o1', 'msg', ?, '{}')").run(
-    lastTimestamp,
-  );
-  db.close();
-}
-
-describe('getGroupStatus', () => {
-  it('returns null for unknown folder', () => {
-    expect(getGroupStatus('does-not-exist')).toBeNull();
-  });
-
-  it('returns empty status for a group with no sessions', () => {
-    const status = getGroupStatus('forge');
-    expect(status).not.toBeNull();
-    expect(status!.containerRunning).toBe(false);
-    expect(status!.activeSessionCount).toBe(0);
-    expect(status!.sessionCount).toBe(0);
-    expect(status!.sessions).toEqual([]);
-  });
-
-  it('marks a session alive when its heartbeat is fresh', () => {
-    const now = Date.parse('2026-04-27T12:00:00.000Z');
-    makeSession('s-fresh');
-    writeHeartbeat('s-fresh', now - 30_000); // 30s ago — well under 90s threshold
-
-    const status = getGroupStatus('forge', { nowMs: now });
-    expect(status!.containerRunning).toBe(true);
-    expect(status!.activeSessionCount).toBe(1);
-    expect(status!.sessions[0].alive).toBe(true);
-    expect(status!.sessions[0].lastHeartbeatAt).toBe(new Date(now - 30_000).toISOString());
-  });
-
-  it('marks a session dead when heartbeat is older than the threshold', () => {
-    const now = Date.parse('2026-04-27T12:00:00.000Z');
-    makeSession('s-stale');
-    writeHeartbeat('s-stale', now - 120_000); // 2 min ago
-
-    const status = getGroupStatus('forge', { nowMs: now });
-    expect(status!.containerRunning).toBe(false);
-    expect(status!.activeSessionCount).toBe(0);
-    expect(status!.sessions[0].alive).toBe(false);
-  });
-
-  it('aggregates last-message timestamps across sessions', () => {
-    const now = Date.parse('2026-04-27T12:00:00.000Z');
-
-    makeSession('s-a');
-    writeHeartbeat('s-a', now - 5_000);
-    seedInboundDb('s-a', '2026-04-27T11:55:00.000Z');
-    seedOutboundDb('s-a', '2026-04-27T11:56:00.000Z');
-
-    makeSession('s-b');
-    writeHeartbeat('s-b', now - 10_000);
-    seedInboundDb('s-b', '2026-04-27T11:58:00.000Z'); // newer
-    seedOutboundDb('s-b', '2026-04-27T11:50:00.000Z'); // older
-
-    const status = getGroupStatus('forge', { nowMs: now });
-    expect(status!.activeSessionCount).toBe(2);
-    expect(status!.lastMessageInAt).toBe('2026-04-27T11:58:00.000Z');
-    expect(status!.lastMessageOutAt).toBe('2026-04-27T11:56:00.000Z');
-  });
-
-  it('tolerates missing session dirs and DBs', () => {
-    const now = Date.parse('2026-04-27T12:00:00.000Z');
-    // Session row exists but no heartbeat / DB files have been created yet.
-    makeSession('s-empty');
-
-    const status = getGroupStatus('forge', { nowMs: now });
-    expect(status!.containerRunning).toBe(false);
-    expect(status!.sessions[0].alive).toBe(false);
-    expect(status!.sessions[0].lastMessageInAt).toBeNull();
-    expect(status!.sessions[0].lastMessageOutAt).toBeNull();
-  });
-});

package/src/parachute/group-status.ts

@@ -1,136 +0,0 @@
-/**
- * Live status for an agent group: whether its container is alive right now,
- * how many sessions are active, and last-message timestamps from the per-
- * session DBs.
- *
- * The web server polls this so the UI can show "which agents are alive."
- * `isContainerRunning(sessionId)` (in-memory map in container-runner.ts) is
- * host-process scoped — useless from the web server. Heartbeat file mtime
- * is the only cross-process liveness signal:
- *
- *   data/sessions/<agent_group_id>/<session_id>/.heartbeat
- *
- * The container's agent-runner touches this on every poll iteration. The
- * host sweep runs at 60s intervals; we use 90s as the "alive" threshold
- * so the dot doesn't blink during a sweep tick.
- */
-import fs from 'node:fs';
-
-import { type Database, openDb } from '../db/connection.js';
-
-import { getAgentGroupByFolder } from '../db/agent-groups.js';
-import { getSessionsByAgentGroup } from '../db/sessions.js';
-import { heartbeatPath, inboundDbPath, outboundDbPath } from '../session-manager.js';
-
-export const DEFAULT_ALIVE_THRESHOLD_MS = 90_000;
-
-export interface SessionStatus {
-  sessionId: string;
-  status: 'active' | 'closed';
-  containerStatus: 'running' | 'idle' | 'stopped';
-  alive: boolean;
-  lastHeartbeatAt: string | null;
-  lastMessageInAt: string | null;
-  lastMessageOutAt: string | null;
-  createdAt: string;
-  lastActiveAt: string | null;
-}
-
-export interface GroupStatus {
-  containerRunning: boolean;
-  activeSessionCount: number;
-  sessionCount: number;
-  lastHeartbeatAt: string | null;
-  lastMessageInAt: string | null;
-  lastMessageOutAt: string | null;
-  sessions: SessionStatus[];
-}
-
-export interface GroupStatusOpts {
-  /** Override the alive threshold (mainly for tests). */
-  aliveThresholdMs?: number;
-  /** Inject "now" for deterministic tests. */
-  nowMs?: number;
-}
-
-export function getGroupStatus(folder: string, opts: GroupStatusOpts = {}): GroupStatus | null {
-  const group = getAgentGroupByFolder(folder);
-  if (!group) return null;
-
-  const aliveThresholdMs = opts.aliveThresholdMs ?? DEFAULT_ALIVE_THRESHOLD_MS;
-  const nowMs = opts.nowMs ?? Date.now();
-
-  const sessions = getSessionsByAgentGroup(group.id).map((s) =>
-    readSessionStatus(group.id, s, nowMs, aliveThresholdMs),
-  );
-
-  return {
-    containerRunning: sessions.some((s) => s.alive),
-    activeSessionCount: sessions.filter((s) => s.alive).length,
-    sessionCount: sessions.filter((s) => s.status === 'active').length,
-    lastHeartbeatAt: latest(sessions.map((s) => s.lastHeartbeatAt)),
-    lastMessageInAt: latest(sessions.map((s) => s.lastMessageInAt)),
-    lastMessageOutAt: latest(sessions.map((s) => s.lastMessageOutAt)),
-    sessions,
-  };
-}
-
-function readSessionStatus(
-  agentGroupId: string,
-  session: {
-    id: string;
-    status: 'active' | 'closed';
-    container_status: 'running' | 'idle' | 'stopped';
-    created_at: string;
-    last_active: string | null;
-  },
-  nowMs: number,
-  aliveThresholdMs: number,
-): SessionStatus {
-  const heartbeatMs = readHeartbeatMtimeMs(agentGroupId, session.id);
-  const alive = heartbeatMs > 0 && nowMs - heartbeatMs <= aliveThresholdMs;
-
-  return {
-    sessionId: session.id,
-    status: session.status,
-    containerStatus: session.container_status,
-    alive,
-    lastHeartbeatAt: heartbeatMs > 0 ? new Date(heartbeatMs).toISOString() : null,
-    lastMessageInAt: maxTimestamp(inboundDbPath(agentGroupId, session.id), 'messages_in'),
-    lastMessageOutAt: maxTimestamp(outboundDbPath(agentGroupId, session.id), 'messages_out'),
-    createdAt: session.created_at,
-    lastActiveAt: session.last_active,
-  };
-}
-
-function readHeartbeatMtimeMs(agentGroupId: string, sessionId: string): number {
-  try {
-    return fs.statSync(heartbeatPath(agentGroupId, sessionId)).mtimeMs;
-  } catch {
-    return 0;
-  }
-}
-
-function maxTimestamp(dbPath: string, table: 'messages_in' | 'messages_out'): string | null {
-  if (!fs.existsSync(dbPath)) return null;
-  let db: Database | null = null;
-  try {
-    db = openDb(dbPath, { readonly: true });
-    const row = db.prepare(`SELECT MAX(timestamp) AS ts FROM ${table}`).get() as { ts: string | null } | undefined;
-    return row?.ts ?? null;
-  } catch {
-    // Session DB not initialized yet, schema mismatch, or transient lock — caller treats null as "no data".
-    return null;
-  } finally {
-    db?.close();
-  }
-}
-
-function latest(values: (string | null)[]): string | null {
-  let best: string | null = null;
-  for (const v of values) {
-    if (!v) continue;
-    if (!best || v > best) best = v;
-  }
-  return best;
-}