@agentplate/cli 1.0.0

package/src/sessions/store.test.ts

@@ -0,0 +1,351 @@
+/**
+ * Tests for the session/run store.
+ *
+ * Per project policy we never mock the database: every test runs against a real
+ * bun:sqlite handle. We default to an in-memory DB (`:memory:`) for speed and
+ * isolation, plus one file-backed case to prove parent-directory creation and
+ * cross-reopen persistence.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { AgentSession, SessionState } from "../types.ts";
+import { createSessionStore, type SessionStore } from "./store.ts";
+
+/**
+ * Build a fully-populated AgentSession with sensible defaults; pass `overrides`
+ * to vary the fields a given test cares about. Centralizing this keeps each test
+ * focused on the behavior under exercise rather than on boilerplate.
+ */
+function makeSession(overrides: Partial<AgentSession> = {}): AgentSession {
+	const now = new Date().toISOString();
+	return {
+		id: crypto.randomUUID(),
+		agentName: `agent-${crypto.randomUUID().slice(0, 4)}`,
+		capability: "builder",
+		taskId: "task-1",
+		runId: "run-test",
+		worktreePath: "/tmp/wt",
+		branchName: "feature/x",
+		state: "booting",
+		parentAgent: null,
+		depth: 0,
+		pid: null,
+		runtimeSessionId: null,
+		startedAt: now,
+		lastActivity: now,
+		...overrides,
+	};
+}
+
+describe("createSessionStore — runs", () => {
+	let store: SessionStore;
+
+	beforeEach(() => {
+		store = createSessionStore(":memory:");
+	});
+
+	afterEach(() => {
+		store.close();
+	});
+
+	test("createRun returns an active run with a run- prefixed id", () => {
+		const run = store.createRun("nightly");
+		expect(run.id).toMatch(/^run-[0-9a-f]{8}$/);
+		expect(run.label).toBe("nightly");
+		expect(run.status).toBe("active");
+		// createdAt should be a valid ISO-8601 timestamp.
+		expect(Number.isNaN(Date.parse(run.createdAt))).toBe(false);
+	});
+
+	test("createRun without a label omits the label field", () => {
+		const run = store.createRun();
+		expect(run.label).toBeUndefined();
+		const fetched = store.getRun(run.id);
+		expect(fetched?.label).toBeUndefined();
+	});
+
+	test("getRun returns null for an unknown id", () => {
+		expect(store.getRun("run-missing")).toBeNull();
+	});
+
+	test("getRun round-trips a created run", () => {
+		const run = store.createRun("label-a");
+		const fetched = store.getRun(run.id);
+		expect(fetched).toEqual(run);
+	});
+
+	test("listRuns returns newest first and honors the limit", () => {
+		const a = store.createRun("a");
+		// Distinct createdAt values guarantee a stable DESC ordering.
+		Bun.sleepSync(2);
+		const b = store.createRun("b");
+		Bun.sleepSync(2);
+		const c = store.createRun("c");
+
+		const all = store.listRuns();
+		expect(all.map((r) => r.id)).toEqual([c.id, b.id, a.id]);
+
+		const limited = store.listRuns(2);
+		expect(limited.map((r) => r.id)).toEqual([c.id, b.id]);
+	});
+
+	test("completeRun flips status to completed", () => {
+		const run = store.createRun();
+		expect(store.getRun(run.id)?.status).toBe("active");
+		store.completeRun(run.id);
+		expect(store.getRun(run.id)?.status).toBe("completed");
+	});
+});
+
+describe("createSessionStore — sessions", () => {
+	let store: SessionStore;
+
+	beforeEach(() => {
+		store = createSessionStore(":memory:");
+	});
+
+	afterEach(() => {
+		store.close();
+	});
+
+	test("upsertSession inserts and getSession round-trips every field", () => {
+		const session = makeSession({
+			parentAgent: "lead-1",
+			depth: 2,
+			pid: 4242,
+			runtimeSessionId: "rt-123",
+		});
+		store.upsertSession(session);
+		const fetched = store.getSession(session.id);
+		expect(fetched).toEqual(session);
+	});
+
+	test("upsertSession preserves null fields", () => {
+		const session = makeSession({
+			parentAgent: null,
+			pid: null,
+			runtimeSessionId: null,
+		});
+		store.upsertSession(session);
+		const fetched = store.getSession(session.id);
+		expect(fetched?.parentAgent).toBeNull();
+		expect(fetched?.pid).toBeNull();
+		expect(fetched?.runtimeSessionId).toBeNull();
+	});
+
+	test("upsertSession on the same id updates fields but keeps startedAt", () => {
+		const original = makeSession({ state: "booting", capability: "scout" });
+		store.upsertSession(original);
+
+		// Re-upsert with the same id but a later startedAt and changed fields;
+		// startedAt must NOT be overwritten (sessions keep their birth time).
+		const mutated: AgentSession = {
+			...original,
+			state: "working",
+			capability: "builder",
+			pid: 99,
+			startedAt: new Date(Date.parse(original.startedAt) + 60_000).toISOString(),
+			lastActivity: new Date(Date.parse(original.lastActivity) + 60_000).toISOString(),
+		};
+		store.upsertSession(mutated);
+
+		const fetched = store.getSession(original.id);
+		expect(fetched?.state).toBe("working");
+		expect(fetched?.capability).toBe("builder");
+		expect(fetched?.pid).toBe(99);
+		expect(fetched?.startedAt).toBe(original.startedAt);
+		expect(fetched?.lastActivity).toBe(mutated.lastActivity);
+
+		// Still exactly one row for that id.
+		expect(store.listSessions().length).toBe(1);
+	});
+
+	test("getSession returns null for an unknown id", () => {
+		expect(store.getSession("nope")).toBeNull();
+	});
+
+	test("getSessionByAgent returns the most recent session for a name", () => {
+		const olderId = crypto.randomUUID();
+		const newerId = crypto.randomUUID();
+		const t0 = new Date().toISOString();
+		store.upsertSession(makeSession({ id: olderId, agentName: "dup", startedAt: t0 }));
+		const t1 = new Date(Date.parse(t0) + 1000).toISOString();
+		store.upsertSession(makeSession({ id: newerId, agentName: "dup", startedAt: t1 }));
+
+		const fetched = store.getSessionByAgent("dup");
+		expect(fetched?.id).toBe(newerId);
+	});
+
+	test("getSessionByAgent returns null when no session matches", () => {
+		expect(store.getSessionByAgent("ghost")).toBeNull();
+	});
+
+	test("setRuntimeSessionId persists the id and bumps lastActivity", () => {
+		const past = new Date(Date.now() - 60_000).toISOString();
+		const session = makeSession({ runtimeSessionId: null, lastActivity: past, startedAt: past });
+		store.upsertSession(session);
+
+		store.setRuntimeSessionId(session.id, "rt-xyz");
+		const fetched = store.getSession(session.id);
+		expect(fetched?.runtimeSessionId).toBe("rt-xyz");
+		expect(Date.parse(fetched?.lastActivity ?? "")).toBeGreaterThan(Date.parse(past));
+	});
+
+	test("touch refreshes lastActivity without changing state", () => {
+		const past = new Date(Date.now() - 60_000).toISOString();
+		const session = makeSession({ state: "idle", lastActivity: past, startedAt: past });
+		store.upsertSession(session);
+
+		store.touch(session.id);
+		const fetched = store.getSession(session.id);
+		expect(fetched?.state).toBe("idle");
+		expect(Date.parse(fetched?.lastActivity ?? "")).toBeGreaterThan(Date.parse(past));
+	});
+});
+
+describe("createSessionStore — state transitions", () => {
+	let store: SessionStore;
+
+	beforeEach(() => {
+		store = createSessionStore(":memory:");
+	});
+
+	afterEach(() => {
+		store.close();
+	});
+
+	test("updateSessionState walks a session through its lifecycle", () => {
+		const past = new Date(Date.now() - 60_000).toISOString();
+		const session = makeSession({ state: "booting", lastActivity: past, startedAt: past });
+		store.upsertSession(session);
+
+		const order: SessionState[] = ["working", "idle", "working", "completed"];
+		for (const next of order) {
+			store.updateSessionState(session.id, next);
+			expect(store.getSession(session.id)?.state).toBe(next);
+		}
+
+		// The transitions must also have advanced lastActivity past its seed.
+		const fetched = store.getSession(session.id);
+		expect(Date.parse(fetched?.lastActivity ?? "")).toBeGreaterThan(Date.parse(past));
+	});
+});
+
+describe("createSessionStore — listing and filtering", () => {
+	let store: SessionStore;
+
+	beforeEach(() => {
+		store = createSessionStore(":memory:");
+	});
+
+	afterEach(() => {
+		store.close();
+	});
+
+	test("listSessions orders by startedAt ascending and filters by run/state", () => {
+		const t = (ms: number) => new Date(Date.parse("2026-01-01T00:00:00.000Z") + ms).toISOString();
+		// run-a: one working, one completed. run-b: one working.
+		store.upsertSession(
+			makeSession({ runId: "run-a", state: "working", startedAt: t(0), agentName: "a1" }),
+		);
+		store.upsertSession(
+			makeSession({ runId: "run-a", state: "completed", startedAt: t(10), agentName: "a2" }),
+		);
+		store.upsertSession(
+			makeSession({ runId: "run-b", state: "working", startedAt: t(20), agentName: "b1" }),
+		);
+
+		// No filter: all three, ascending by startedAt.
+		const all = store.listSessions();
+		expect(all.map((s) => s.agentName)).toEqual(["a1", "a2", "b1"]);
+
+		// Filter by runId.
+		const runA = store.listSessions({ runId: "run-a" });
+		expect(runA.map((s) => s.agentName)).toEqual(["a1", "a2"]);
+
+		// Filter by state.
+		const working = store.listSessions({ state: "working" });
+		expect(working.map((s) => s.agentName).sort()).toEqual(["a1", "b1"]);
+
+		// Combined filter (AND).
+		const runAWorking = store.listSessions({ runId: "run-a", state: "working" });
+		expect(runAWorking.map((s) => s.agentName)).toEqual(["a1"]);
+
+		// A filter matching nothing returns an empty array.
+		expect(store.listSessions({ runId: "run-zzz" })).toEqual([]);
+	});
+});
+
+describe("createSessionStore — countActive", () => {
+	let store: SessionStore;
+
+	beforeEach(() => {
+		store = createSessionStore(":memory:");
+	});
+
+	afterEach(() => {
+		store.close();
+	});
+
+	test("countActive counts booting/working/idle and excludes terminal states", () => {
+		// run-1: booting, working, idle (3 active), plus completed/failed/stopped.
+		store.upsertSession(makeSession({ runId: "run-1", state: "booting" }));
+		store.upsertSession(makeSession({ runId: "run-1", state: "working" }));
+		store.upsertSession(makeSession({ runId: "run-1", state: "idle" }));
+		store.upsertSession(makeSession({ runId: "run-1", state: "completed" }));
+		store.upsertSession(makeSession({ runId: "run-1", state: "failed" }));
+		store.upsertSession(makeSession({ runId: "run-1", state: "stopped" }));
+		// run-2: one working.
+		store.upsertSession(makeSession({ runId: "run-2", state: "working" }));
+
+		// Global active count across both runs: 3 + 1 = 4.
+		expect(store.countActive()).toBe(4);
+		// Per-run scoping.
+		expect(store.countActive("run-1")).toBe(3);
+		expect(store.countActive("run-2")).toBe(1);
+		// Unknown run -> 0.
+		expect(store.countActive("run-none")).toBe(0);
+	});
+
+	test("countActive reflects state transitions", () => {
+		const s = makeSession({ runId: "run-x", state: "working" });
+		store.upsertSession(s);
+		expect(store.countActive("run-x")).toBe(1);
+
+		store.updateSessionState(s.id, "completed");
+		expect(store.countActive("run-x")).toBe(0);
+	});
+});
+
+describe("createSessionStore — file-backed database", () => {
+	let dir: string;
+
+	beforeEach(() => {
+		dir = mkdtempSync(join(tmpdir(), "agentplate-sessions-"));
+	});
+
+	afterEach(() => {
+		rmSync(dir, { recursive: true, force: true });
+	});
+
+	test("creates the parent directory and persists across reopen", () => {
+		// Point at a NON-existent nested path to exercise the mkdir-parent logic.
+		const dbPath = join(dir, "nested", "sessions.db");
+
+		const first = createSessionStore(dbPath);
+		const run = first.createRun("persisted");
+		const session = makeSession({ runId: run.id, state: "working" });
+		first.upsertSession(session);
+		first.close();
+
+		// Reopen the same file: data must still be there.
+		const second = createSessionStore(dbPath);
+		expect(second.getRun(run.id)?.label).toBe("persisted");
+		expect(second.getSession(session.id)?.state).toBe("working");
+		expect(second.countActive(run.id)).toBe(1);
+		second.close();
+	});
+});

package/src/sessions/store.ts

@@ -0,0 +1,350 @@
+/**
+ * SQLite-backed store for agent sessions and runs.
+ *
+ * Sessions track the lifecycle of every spawned agent; runs group together all
+ * the sessions started during one coordinator session. Both tables live in the
+ * same database (`.agentplate/sessions.db`) so a single WAL file covers the whole
+ * lifecycle and status-style commands read everything from one handle.
+ *
+ * This module exposes a *factory* (`createSessionStore`) rather than a class.
+ * The returned object is the public surface; the `Database` handle and the
+ * row<->record mapping stay private in the closure. All column<->field
+ * translation lives in one place (`rowToRun` / `rowToSession`) so the snake_case
+ * SQL schema never leaks into the rest of the codebase, which only ever sees the
+ * camelCase `RunRecord` / `AgentSession` shapes from `types.ts`.
+ */
+
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { openDatabase } from "../db/sqlite.ts";
+import type { AgentSession, Capability, RunRecord, SessionState } from "../types.ts";
+
+/**
+ * Sessions considered "active" for concurrency accounting. Mirrors the
+ * pre-terminal states of {@link SessionState}: an agent that is still booting,
+ * actively working, or idle (awaiting its next turn / nudge) counts against the
+ * fleet/per-run caps. Terminal states (completed/failed/stopped) do not.
+ *
+ * Kept here (not in types.ts, which we must not edit) as a `const` tuple so the
+ * compiler still checks the values against `SessionState` and `countActive`
+ * stays single-sourced.
+ */
+const ACTIVE_STATES: readonly SessionState[] = ["booting", "working", "idle"];
+
+/**
+ * Filter for {@link SessionStore.listSessions}. Both fields are optional and
+ * AND-combined; omit both to list every session. Local to this store (purely a
+ * query convenience), so it is defined here rather than in shared types.
+ */
+export interface SessionListFilter {
+	runId?: string;
+	state?: SessionState;
+}
+
+/** Public surface of the session/run store, returned by `createSessionStore`. */
+export interface SessionStore {
+	// --- Runs ---
+	createRun(label?: string): RunRecord;
+	getRun(id: string): RunRecord | null;
+	listRuns(limit?: number): RunRecord[];
+	completeRun(id: string): void;
+	// --- Sessions ---
+	upsertSession(session: AgentSession): void;
+	getSession(id: string): AgentSession | null;
+	getSessionByAgent(agentName: string): AgentSession | null;
+	listSessions(filter?: SessionListFilter): AgentSession[];
+	updateSessionState(id: string, state: SessionState): void;
+	setRuntimeSessionId(id: string, runtimeSessionId: string): void;
+	touch(id: string): void;
+	countActive(runId?: string): number;
+	// --- Lifecycle ---
+	close(): void;
+}
+
+// DDL is idempotent (`IF NOT EXISTS`). Nullable columns (no NOT NULL) mirror the
+// `| null` fields in the record types so `null` round-trips faithfully. The
+// `runs` table stores no `completed_at`: `RunRecord` has no such field, so
+// completion is captured solely by flipping `status` to 'completed'.
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS runs (
+	id TEXT PRIMARY KEY,
+	created_at TEXT NOT NULL,
+	status TEXT NOT NULL DEFAULT 'active',
+	label TEXT
+);
+
+CREATE TABLE IF NOT EXISTS sessions (
+	id TEXT PRIMARY KEY,
+	agent_name TEXT NOT NULL,
+	capability TEXT NOT NULL,
+	task_id TEXT NOT NULL,
+	run_id TEXT NOT NULL,
+	worktree_path TEXT NOT NULL,
+	branch_name TEXT NOT NULL,
+	state TEXT NOT NULL,
+	parent_agent TEXT,
+	depth INTEGER NOT NULL DEFAULT 0,
+	pid INTEGER,
+	runtime_session_id TEXT,
+	started_at TEXT NOT NULL,
+	last_activity TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_sessions_run ON sessions(run_id);
+CREATE INDEX IF NOT EXISTS idx_sessions_agent ON sessions(agent_name);
+CREATE INDEX IF NOT EXISTS idx_sessions_state ON sessions(state);
+`;
+
+// Raw row shapes as returned by bun:sqlite (snake_case columns, nullable where
+// the schema allows NULL). Mapped to camelCase records before leaving the module.
+interface RunRow {
+	id: string;
+	created_at: string;
+	status: string;
+	label: string | null;
+}
+
+interface SessionRow {
+	id: string;
+	agent_name: string;
+	capability: string;
+	task_id: string;
+	run_id: string;
+	worktree_path: string;
+	branch_name: string;
+	state: string;
+	parent_agent: string | null;
+	depth: number;
+	pid: number | null;
+	runtime_session_id: string | null;
+	started_at: string;
+	last_activity: string;
+}
+
+function rowToRun(row: RunRow): RunRecord {
+	// `status` is constrained to 'active' | 'completed' by our own writes; the DB
+	// column is plain TEXT so we narrow on read. `label` is optional on the record
+	// (omit the key entirely when the column is NULL rather than carrying `null`,
+	// since RunRecord.label is `string | undefined`, not nullable).
+	const record: RunRecord = {
+		id: row.id,
+		createdAt: row.created_at,
+		status: row.status as RunRecord["status"],
+	};
+	if (row.label !== null) record.label = row.label;
+	return record;
+}
+
+function rowToSession(row: SessionRow): AgentSession {
+	return {
+		id: row.id,
+		agentName: row.agent_name,
+		// `capability` is constrained to Capability by writers; narrow on read.
+		capability: row.capability as Capability,
+		taskId: row.task_id,
+		runId: row.run_id,
+		worktreePath: row.worktree_path,
+		branchName: row.branch_name,
+		state: row.state as SessionState,
+		parentAgent: row.parent_agent,
+		depth: row.depth,
+		pid: row.pid,
+		runtimeSessionId: row.runtime_session_id,
+		startedAt: row.started_at,
+		lastActivity: row.last_activity,
+	};
+}
+
+// SQL IN-list of active states, built from the single ACTIVE_STATES source.
+// Values are hard-coded literals (no user input), so quoting them is safe; we
+// still derive the list programmatically so it never drifts from the constant.
+const ACTIVE_STATES_SQL = `(${ACTIVE_STATES.map((s) => `'${s}'`).join(", ")})`;
+
+/**
+ * Open (or create) the session/run store at `dbPath`.
+ *
+ * Pass `":memory:"` for an ephemeral in-process database (tests). For a file
+ * path the parent directory is created if missing, so callers don't have to
+ * pre-make `.agentplate/` themselves.
+ */
+export function createSessionStore(dbPath: string): SessionStore {
+	// openDatabase (bun:sqlite under it) will not create intermediate
+	// directories, so ensure the parent exists for file-backed databases.
+	if (dbPath !== ":memory:") {
+		mkdirSync(dirname(dbPath), { recursive: true });
+	}
+	// Guard on `runs.created_at`: the unrelated @ag-eco/agentplate-cli creates a
+	// `runs` table with `started_at` instead, which would break our inserts.
+	const db = openDatabase(dbPath, { guard: { table: "runs", columns: ["created_at"] } });
+	db.exec(SCHEMA);
+
+	// --- Runs ---
+
+	function createRun(label?: string): RunRecord {
+		// Short, human-scannable id: `run-` + first 8 hex chars of a UUID.
+		// Collision risk across a single project's run history is negligible.
+		const id = `run-${crypto.randomUUID().slice(0, 8)}`;
+		const createdAt = new Date().toISOString();
+		db.query("INSERT INTO runs (id, created_at, status, label) VALUES (?, ?, 'active', ?)").run(
+			id,
+			createdAt,
+			label ?? null,
+		);
+		const record: RunRecord = { id, createdAt, status: "active" };
+		if (label !== undefined) record.label = label;
+		return record;
+	}
+
+	function getRun(id: string): RunRecord | null {
+		const row = db.query("SELECT * FROM runs WHERE id = ?").get(id) as RunRow | null;
+		return row ? rowToRun(row) : null;
+	}
+
+	function listRuns(limit = 50): RunRecord[] {
+		// Newest first: the orchestrator usually cares about the current/last run.
+		const rows = db
+			.query("SELECT * FROM runs ORDER BY created_at DESC LIMIT ?")
+			.all(limit) as RunRow[];
+		return rows.map(rowToRun);
+	}
+
+	function completeRun(id: string): void {
+		// RunRecord has no completedAt; completion is captured by status alone.
+		db.query("UPDATE runs SET status = 'completed' WHERE id = ?").run(id);
+	}
+
+	// --- Sessions ---
+
+	function upsertSession(session: AgentSession): void {
+		// Idempotent upsert keyed on the session id. `started_at` is intentionally
+		// NOT overwritten on conflict (a session keeps its original birth time);
+		// every other field, including `last_activity`, reflects the latest write.
+		db.query(
+			`INSERT INTO sessions (
+				id, agent_name, capability, task_id, run_id, worktree_path, branch_name,
+				state, parent_agent, depth, pid, runtime_session_id, started_at, last_activity
+			) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+			ON CONFLICT(id) DO UPDATE SET
+				agent_name = excluded.agent_name,
+				capability = excluded.capability,
+				task_id = excluded.task_id,
+				run_id = excluded.run_id,
+				worktree_path = excluded.worktree_path,
+				branch_name = excluded.branch_name,
+				state = excluded.state,
+				parent_agent = excluded.parent_agent,
+				depth = excluded.depth,
+				pid = excluded.pid,
+				runtime_session_id = excluded.runtime_session_id,
+				last_activity = excluded.last_activity`,
+		).run(
+			session.id,
+			session.agentName,
+			session.capability,
+			session.taskId,
+			session.runId,
+			session.worktreePath,
+			session.branchName,
+			session.state,
+			session.parentAgent,
+			session.depth,
+			session.pid,
+			session.runtimeSessionId,
+			session.startedAt,
+			session.lastActivity,
+		);
+	}
+
+	function getSession(id: string): AgentSession | null {
+		const row = db.query("SELECT * FROM sessions WHERE id = ?").get(id) as SessionRow | null;
+		return row ? rowToSession(row) : null;
+	}
+
+	function getSessionByAgent(agentName: string): AgentSession | null {
+		// Agent names can be reused across runs; return the most recent session for
+		// that name so callers see the live one.
+		const row = db
+			.query("SELECT * FROM sessions WHERE agent_name = ? ORDER BY started_at DESC LIMIT 1")
+			.get(agentName) as SessionRow | null;
+		return row ? rowToSession(row) : null;
+	}
+
+	function listSessions(filter?: SessionListFilter): AgentSession[] {
+		// Build the WHERE clause dynamically; params stay positional so values are
+		// always parameterized (no string interpolation of user-supplied data).
+		const clauses: string[] = [];
+		const params: string[] = [];
+		if (filter?.runId !== undefined) {
+			clauses.push("run_id = ?");
+			params.push(filter.runId);
+		}
+		if (filter?.state !== undefined) {
+			clauses.push("state = ?");
+			params.push(filter.state);
+		}
+		const where = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
+		const rows = db
+			.query(`SELECT * FROM sessions ${where} ORDER BY started_at ASC`)
+			.all(...params) as SessionRow[];
+		return rows.map(rowToSession);
+	}
+
+	function updateSessionState(id: string, state: SessionState): void {
+		// A state change is, by definition, activity — bump last_activity too.
+		const now = new Date().toISOString();
+		db.query("UPDATE sessions SET state = ?, last_activity = ? WHERE id = ?").run(state, now, id);
+	}
+
+	function setRuntimeSessionId(id: string, runtimeSessionId: string): void {
+		// Learning the runtime session id (e.g. for `--resume`) counts as activity.
+		const now = new Date().toISOString();
+		db.query("UPDATE sessions SET runtime_session_id = ?, last_activity = ? WHERE id = ?").run(
+			runtimeSessionId,
+			now,
+			id,
+		);
+	}
+
+	function touch(id: string): void {
+		// Pure heartbeat: refresh last_activity without changing any other field.
+		const now = new Date().toISOString();
+		db.query("UPDATE sessions SET last_activity = ? WHERE id = ?").run(now, id);
+	}
+
+	function countActive(runId?: string): number {
+		// Active = booting | working | idle (see ACTIVE_STATES). Used by schedulers
+		// to enforce per-run / global concurrency caps.
+		if (runId !== undefined) {
+			const row = db
+				.query(
+					`SELECT COUNT(*) AS n FROM sessions WHERE run_id = ? AND state IN ${ACTIVE_STATES_SQL}`,
+				)
+				.get(runId) as { n: number };
+			return row.n;
+		}
+		const row = db
+			.query(`SELECT COUNT(*) AS n FROM sessions WHERE state IN ${ACTIVE_STATES_SQL}`)
+			.get() as { n: number };
+		return row.n;
+	}
+
+	function close(): void {
+		db.close();
+	}
+
+	return {
+		createRun,
+		getRun,
+		listRuns,
+		completeRun,
+		upsertSession,
+		getSession,
+		getSessionByAgent,
+		listSessions,
+		updateSessionState,
+		setRuntimeSessionId,
+		touch,
+		countActive,
+		close,
+	};
+}