@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/smart-launch.js

@@ -1,10 +1,3 @@
-/**
- * Device placement for `--device auto`.
- *
- * Explicit auto placement probes live fleet health and harness readiness.
- * Historical affinity remains for generic host resolution callers.
- * Account selection is separate (`--strategy balanced` / rotate.ts).
- */
 import { queryAffinityRollup } from './session/db.js';
 import { localMachineId } from './session/origin-machine.js';
 import { loadDevicesSync } from './devices/registry.js';
@@ -12,12 +5,7 @@ import { autoLaunchPreferredSet, describeAutoPool, filterAutoPool, isAutoPoolMem
 import { normalizeHost } from './machine-id.js';
 import { probePoolSignals } from './teams/placement-probe.js';
 import { pickBestDevice } from './teams/scheduler.js';
-/** Peakiness of usage weights; >1 amplifies the most-used option. */
 const DEFAULT_AFFINITY_ALPHA = 1.3;
-/**
- * Convert affinity rows into positive weights: launches^α (floor 1 for any
- * row with launches > 0 so a single-use host still participates).
- */
 export function affinityWeights(rows, alpha = DEFAULT_AFFINITY_ALPHA) {
     return rows
         .filter((r) => r.launches > 0 && r.key && r.key !== '(unknown)')
@@ -27,10 +15,6 @@ export function affinityWeights(rows, alpha = DEFAULT_AFFINITY_ALPHA) {
         weight: Math.max(1, Math.pow(r.launches, alpha)),
     }));
 }
-/**
- * Weighted random sample. Returns null when candidates is empty.
- * Pure — inject `rng` for tests.
- */
 export function sampleWeighted(candidates, rng = Math.random) {
     if (candidates.length === 0)
         return null;
@@ -45,21 +29,6 @@ export function sampleWeighted(candidates, rng = Math.random) {
     }
     return candidates[candidates.length - 1].key;
 }
-/**
- * Online device names from the local registry (+ local), narrowed to the
- * automatic-placement pool.
- *
- * The pool rule lives in `devices/pool.ts` and is an allowlist once any device
- * is marked `role=worker`: this is the single place both automatic-placement
- * paths (`resolveDeviceAuto`, `resolveDeviceAffinity`) get their candidates, so
- * marking workers moves every `--device auto` at once instead of one surface.
- *
- * It CAN return an empty list — a fleet where every marked worker is
- * offline, or where this box is the only candidate and is marked `personal`. That is a
- * real answer, and both callers fail loud on it rather than falling back to the
- * local machine (which would be the exact box the operator marked personal to
- * keep agents off).
- */
 export function listOnlineDeviceNames(localName = localMachineId()) {
     const names = new Set([normalizeHost(localName)]);
     try {
@@ -68,22 +37,15 @@ export function listOnlineDeviceNames(localName = localMachineId()) {
             if (!d || typeof d !== 'object')
                 continue;
             const online = d.tailscale?.online;
-            // No tailscale snapshot → treat as candidate (registry-only box).
             if (online === false)
                 continue;
             names.add(normalizeHost(name));
         }
     }
     catch {
-        /* registry missing — local only */
     }
     return filterAutoPool([...names]);
 }
-/**
- * The error both automatic-placement resolvers raise when device roles leave no
- * candidate at all. Fail loud: the alternative — quietly running on the local
- * machine — puts the agent on the box the operator marked `personal`.
- */
 export function formatEmptyAutoPoolError() {
     const marked = describeAutoPool();
     return (`agents: no device is eligible for automatic placement${marked ? ` (${marked})` : ''} — ` +
@@ -98,15 +60,10 @@ export function formatNoHealthyDeviceError(pool, signals, agent) {
             reason = signal.headroom === 'loaded'
                 ? 'overloaded'
                 : signal.installed !== true || signal.signedIn !== true
-                    // Surface the box's OWN reason (`runReady.reason`, e.g. "all
-                    // signed_out") when it gave one, rather than a bare "no ready harness
-                    // account" that leaves the operator guessing (PHNX-4116).
                     ? `no ready harness account${signal.reason ? ` (${signal.reason})` : ''}`
                     : 'ineligible';
         }
         else if (signal?.timedOut) {
-            // A slow link is not an offline box. Saying "unreachable" here sent
-            // operators hunting a fleet outage that did not exist (PHNX-3682).
             timedOutCount++;
             reason = 'probe timed out';
         }
@@ -119,14 +76,8 @@ export function formatNoHealthyDeviceError(pool, signals, agent) {
         return `${key} (${reason})`;
     }).join(', ');
     const target = agent ? `can run ${agent}` : "for 'run auto'";
-    // Name the role narrowing when there is one: a fleet where every box but two
-    // is filtered out by a worker mark reads as "the fleet is down" without it.
-    // Roster on `pool` so a fleet-wide role default reaches a doc-less device
-    // in this error's own candidate set, not just the ones with a doc.
     const marked = describeAutoPool({ roster: pool });
     const poolNote = marked ? ` [pool: ${marked}]` : '';
-    // Only talk about usage windows when a device was actually turned away for
-    // one. A pool that timed out needs a link/latency hint, not a reset time.
     const scope = timedOutCount === pool.length
         ? `every probe (${pool.length}) exceeded`
         : `${timedOutCount} of ${pool.length} probes exceeded`;
@@ -136,19 +87,9 @@ export function formatNoHealthyDeviceError(pool, signals, agent) {
         : '; earliest window resets unknown';
     return `agents: no healthy device ${target}${poolNote} — excluded: ${excluded}${hint}`;
 }
-/**
- * Pick the least-loaded healthy device that can run `agent` when the harness is
- * known. `run auto` omits the agent and treats any ready account on the device
- * as eligible. The local machine participates in the
- * same probe and must pass the same eligibility checks. An empty eligible pool
- * fails loud; automatic placement never silently becomes a local launch.
- */
 export async function resolveDeviceAuto(agent, opts = {}) {
     const local = normalizeHost(opts.localMachine ?? localMachineId());
     const pool = [...new Set((opts.eligibleHosts ?? listOnlineDeviceNames(local)).map(normalizeHost))];
-    // The local machine participates in the same probe as every peer — unless a
-    // role excludes it. Adding it unconditionally would put agents back on the box
-    // the operator marked `personal` precisely to keep them off it.
     if (!pool.includes(local) && isAutoPoolMember(local))
         pool.push(local);
     if (pool.length === 0)
@@ -179,8 +120,6 @@ export async function resolveDeviceAuto(agent, opts = {}) {
     if (eligiblePool.length === 0) {
         throw new Error(formatNoHealthyDeviceError(pool, signals, agent));
     }
-    // `agents devices config <name> auto-launch.preferred on` boosts a device in the ranking — resolved
-    // over the same pool so a fleet default reaches a doc-less box.
     const preferred = opts.preferred ?? autoLaunchPreferredSet(pool, { roster: pool });
     const picked = pickBestDevice(eligiblePool, [], { signals, agentLabel: agent, preferred });
     return {
@@ -194,26 +133,12 @@ export async function resolveDeviceAuto(agent, opts = {}) {
         })),
     };
 }
-/**
- * Resolve host for `--device auto`. Does NOT pick harness or accounts.
- *
- * Draws from the same automatic-placement pool as {@link resolveDeviceAuto}, so
- * `agents ssh auto`, the generic `--device auto` passthrough, and `matchHost`'s
- * `auto` sentinel honour device roles too. Throws when roles leave the pool
- * empty — a `null` host here means "run locally", which for a box marked
- * `personal` is the outcome the mark exists to prevent.
- */
 export function resolveDeviceAffinity(opts = {}) {
     const local = normalizeHost(opts.localMachine ?? localMachineId());
     const alpha = opts.alpha ?? DEFAULT_AFFINITY_ALPHA;
     const rng = opts.rng ?? Math.random;
     const sinceDays = opts.sinceDays ?? 14;
     const sinceMs = Date.now() - sinceDays * 24 * 60 * 60 * 1000;
-    // `listOnlineDeviceNames` always contained the local machine before device
-    // roles existed, so an empty default list can only mean roles excluded
-    // everything — fail loud, exactly as resolveDeviceAuto does. An explicitly
-    // empty `eligibleHosts` is the caller's own list and keeps the historical
-    // degrade-to-local behavior.
     const usingDefaultPool = opts.eligibleHosts === undefined;
     const eligible = new Set((opts.eligibleHosts ?? listOnlineDeviceNames(local)).map(normalizeHost));
     if (eligible.size === 0) {
@@ -229,7 +154,6 @@ export function resolveDeviceAffinity(opts = {}) {
             onlyCli: true,
             project: opts.project,
         });
-    // Hosts with history get launches^α; online hosts with no history explore at weight 1.
     const launchesByHost = new Map();
     for (const r of deviceRows) {
         const k = normalizeHost(r.key);
@@ -257,16 +181,10 @@ export function resolveDeviceAffinity(opts = {}) {
         pickedDeviceKey,
     };
 }
-/** True when a host flag value means affinity pick. */
 export function isDeviceAuto(value) {
     return typeof value === 'string' && value.trim().toLowerCase() === 'auto';
 }
 const HOST_SLOTS = ['host', 'device', 'on', 'computer'];
-/**
- * Apply `--device auto` onto run options.
- * Mutates `options` in place. Placement failures propagate without rewriting
- * `auto`, so callers fail loud instead of silently launching locally.
- */
 export async function applyDeviceAutoToOptions(options, deps = {}) {
     const hasAuto = HOST_SLOTS.some((k) => isDeviceAuto(options[k]));
     if (!hasAuto) {
@@ -275,7 +193,7 @@ export async function applyDeviceAutoToOptions(options, deps = {}) {
     const accountPickerRequested = deps.accountPickerRequested ?? false;
     const resolve = deps.resolve ?? ((accountPicker) => resolveDeviceAuto(deps.agent, { accountPicker }));
     const plan = await resolve(accountPickerRequested);
-    const concrete = plan.host; // null = local
+    const concrete = plan.host;
     for (const k of HOST_SLOTS) {
         if (isDeviceAuto(options[k])) {
             options[k] = concrete ?? undefined;

package/dist/lib/snapshot.d.ts

@@ -1,24 +1,8 @@
-/**
- * `agents devices snapshot` — one-process fleet consumer snapshot.
- *
- * Consumers (Factory watchdog, menubar, fleet scripts) used to fork:
- *   agents view <agent> --json  × N harnesses
- *   agents sessions --active --json
- *   agents feed --json          (sometimes)
- *
- * That is N+2 process starts per poll tick. This module gathers the same
- * shapes in one invocation so poll count drops to 1 without redefining
- * `agents sync status` (which stays the UnifiedSyncStatus sync contract).
- *
- * Stores are not merged — inventory still comes from view, active rows from
- * sessions, blocks from feed. Only the reader is consolidated.
- */
 import { type OpenBlock } from './feed/feed.js';
 import { type FleetAgentCounts } from './fleet-status.js';
 import type { AgentId } from './types.js';
 import type { UnifiedSyncStatus } from './sync-status.js';
 import type { ViewJsonAgent } from './view-types.js';
-/** One open-block row in the optional feed summary (no full question bodies). */
 interface SnapshotFeedBlock {
     blockId: string;
     sessionId: string;
@@ -30,12 +14,10 @@ interface SnapshotFeedBlock {
     questionCount: number;
     ts: string;
 }
-/** Compact feed slice for needs-you polls. */
 export interface SnapshotFeedSummary {
     openBlocks: number;
     blocks: SnapshotFeedBlock[];
 }
-/** Active-session row as emitted by `sessions --active --json`. */
 export type SnapshotSessionRow = {
     ticketId: string | null;
     project: string | null;
@@ -43,49 +25,26 @@ export type SnapshotSessionRow = {
     viewingIn: string | null;
     [key: string]: unknown;
 };
-/**
- * Stable machine-readable contract for `agents devices snapshot --json`.
- * Bump `version` only on breaking shape changes.
- */
 export interface FleetSnapshot {
     version: 1;
-    /** Host that produced this snapshot (machineId). */
     host: string;
-    /** ISO-8601 capture time. */
     capturedAt: string;
-    /** Installed agent inventory — same shape as `agents view --json`. */
     inventory: ViewJsonAgent[];
-    /** Live sessions — same row shape as `agents sessions --active --json`. */
     sessions: SnapshotSessionRow[];
-    /** How many remote devices contributed sessions (0 when --local). */
     remoteDeviceCount: number;
-    /** Running/live tallies derived from `sessions` (same as fleet-status). */
     agents: FleetAgentCounts;
-    /** Present when --with-feed. */
     feed?: SnapshotFeedSummary;
-    /** Present when --with-sync (UnifiedSyncStatus; does not replace `agents sync status`). */
     sync?: UnifiedSyncStatus;
 }
 interface ComputeSnapshotOptions {
-    /** Restrict inventory to one agent id. */
     agent?: AgentId;
-    /** Local sessions only — no cross-machine SSH fan-out. Default true for cheap polls. */
     local?: boolean;
-    /** Explicit host filter for the sessions gather (same semantics as sessions --active). */
     hosts?: string[];
-    /** Include open feed-block summary. */
     withFeed?: boolean;
-    /** Include UnifiedSyncStatus (opt-in; can be slower). */
     withSync?: boolean;
-    /** Cap feed.blocks length (default 50). */
     feedLimit?: number;
 }
-/** Summarize open blocks for the snapshot feed slice. Pure / unit-testable. */
 export declare function summarizeFeedBlocks(blocks: ReadonlyArray<OpenBlock>, limit?: number): SnapshotFeedSummary;
-/**
- * Assemble a snapshot payload from already-gathered pieces. Pure so tests do
- * not need live process scans or network.
- */
 export declare function assembleSnapshot(parts: {
     host: string;
     capturedAt: string;
@@ -95,10 +54,5 @@ export declare function assembleSnapshot(parts: {
     feed?: SnapshotFeedSummary;
     sync?: UnifiedSyncStatus;
 }): FleetSnapshot;
-/**
- * Gather inventory + active sessions (+ optional feed/sync) in one process.
- * Default `local: true` keeps the common poll path free of SSH fan-out; pass
- * `local: false` (or hosts) to match full `sessions --active` fleet scope.
- */
 export declare function computeSnapshot(opts?: ComputeSnapshotOptions): Promise<FleetSnapshot>;
 export {};

package/dist/lib/snapshot.js

@@ -1,22 +1,6 @@
-/**
- * `agents devices snapshot` — one-process fleet consumer snapshot.
- *
- * Consumers (Factory watchdog, menubar, fleet scripts) used to fork:
- *   agents view <agent> --json  × N harnesses
- *   agents sessions --active --json
- *   agents feed --json          (sometimes)
- *
- * That is N+2 process starts per poll tick. This module gathers the same
- * shapes in one invocation so poll count drops to 1 without redefining
- * `agents sync status` (which stays the UnifiedSyncStatus sync contract).
- *
- * Stores are not merged — inventory still comes from view, active rows from
- * sessions, blocks from feed. Only the reader is consolidated.
- */
 import { machineId } from './machine-id.js';
 import { listBlocks } from './feed/feed.js';
 import { computeAgentCounts } from './fleet-status.js';
-/** Summarize open blocks for the snapshot feed slice. Pure / unit-testable. */
 export function summarizeFeedBlocks(blocks, limit = 50) {
     const sorted = [...blocks].sort((a, b) => (a.ts < b.ts ? 1 : a.ts > b.ts ? -1 : 0));
     const slice = sorted.slice(0, Math.max(0, limit));
@@ -35,10 +19,6 @@ export function summarizeFeedBlocks(blocks, limit = 50) {
         })),
     };
 }
-/**
- * Assemble a snapshot payload from already-gathered pieces. Pure so tests do
- * not need live process scans or network.
- */
 export function assembleSnapshot(parts) {
     return {
         version: 1,
@@ -56,21 +36,15 @@ export function assembleSnapshot(parts) {
         ...(parts.sync ? { sync: parts.sync } : {}),
     };
 }
-/**
- * Gather inventory + active sessions (+ optional feed/sync) in one process.
- * Default `local: true` keeps the common poll path free of SSH fan-out; pass
- * `local: false` (or hosts) to match full `sessions --active` fleet scope.
- */
 export async function computeSnapshot(opts = {}) {
-    // Default local-only sessions (cheap poll). Explicit hosts → scoped fan-out.
-    // local: false (from --all-hosts) → full sessions --active fan-out.
     const localOnly = opts.hosts?.length ? false : opts.local !== false;
-    const [{ collectAgentsJson }, sessionsMod] = await Promise.all([
+    const [{ collectAgentsJson }, rosterMod, { serializeActiveSessionsForJson }] = await Promise.all([
         import('../commands/view.js'),
-        import('../commands/sessions.js'),
+        import('../commands/ps-roster.js'),
+        import('./session/active.js'),
     ]);
     const inventoryP = collectAgentsJson(opts.agent);
-    const sessionsP = sessionsMod.gatherActiveSessions({
+    const sessionsP = rosterMod.gatherActiveSessions({
         local: localOnly,
         hosts: opts.hosts,
     });
@@ -86,7 +60,7 @@ export async function computeSnapshot(opts = {}) {
         feedP,
         syncP,
     ]);
-    const sessions = sessionsMod.serializeActiveSessionsForJson(gathered.sessions);
+    const sessions = serializeActiveSessionsForJson(gathered.sessions);
     return assembleSnapshot({
         host: machineId(),
         capturedAt: new Date().toISOString(),

package/dist/lib/spinner.d.ts

@@ -1,39 +1,2 @@
-/**
- * Ctrl-C-safe spinner factory.
- *
- * `ora` defaults to `discardStdin: true`, which — on a TTY — flips stdin into
- * raw mode for the lifetime of the spinner (via `stdin-discarder`). Raw mode
- * disables the terminal's own ISIG translation, so a Ctrl-C keystroke no longer
- * generates SIGINT; `stdin-discarder` tries to compensate by re-emitting SIGINT
- * when it reads a 0x03 byte, but that read only happens when stdin is in
- * *flowing* mode. At CLI startup a fresh `process.stdin` has `flowing === null`,
- * so `stdin.isPaused()` returns false, the discarder skips its `stdin.resume()`,
- * and its `prependListener('data')` never switches the stream to flowing —
- * because Node's readable only auto-resumes for `on('data')`, not
- * `prependListener('data')`. The net effect: while such a spinner is running,
- * Ctrl-C is swallowed entirely — the terminal won't raise SIGINT and the
- * discarder never sees the byte to re-raise it.
- *
- * That is invisible for a sub-second spinner, but any spinner wrapping a long
- * idle wait — a cross-machine SSH fan-out, a fleet search — traps the user for
- * the full duration (measured: `agents sessions --flat` could not be Ctrl-C'd
- * for the entire ~12s+ sweep and had to be SIGKILLed). The global SIGINT handler
- * in `index.ts` (`process.exit(130)`) is correct; it simply never fires because
- * no SIGINT is ever raised.
- *
- * Setting `discardStdin: false` keeps the terminal in cooked mode, so Ctrl-C
- * raises SIGINT normally (the terminal also SIGINTs the whole foreground process
- * group, reaping the outstanding `ssh` children) and the global handler exits
- * promptly. The only thing lost is cosmetic stray-keystroke discarding during
- * the spin — a worthwhile trade for a spinner the user must be able to abort.
- *
- * Use this for any spinner that wraps a network / fleet / SSH wait. A truly
- * instantaneous local spinner can still use `ora` directly, but preferring this
- * everywhere is harmless.
- */
 import { type Options, type Ora } from 'ora';
-/**
- * Build an interruptible spinner — a drop-in for `ora(text)` that keeps Ctrl-C
- * working. Returns an unstarted {@link Ora}; call `.start()` as usual.
- */
 export declare function interruptibleSpinner(text?: string, options?: Omit<Options, 'discardStdin'>): Ora;

package/dist/lib/spinner.js

@@ -1,41 +1,4 @@
-/**
- * Ctrl-C-safe spinner factory.
- *
- * `ora` defaults to `discardStdin: true`, which — on a TTY — flips stdin into
- * raw mode for the lifetime of the spinner (via `stdin-discarder`). Raw mode
- * disables the terminal's own ISIG translation, so a Ctrl-C keystroke no longer
- * generates SIGINT; `stdin-discarder` tries to compensate by re-emitting SIGINT
- * when it reads a 0x03 byte, but that read only happens when stdin is in
- * *flowing* mode. At CLI startup a fresh `process.stdin` has `flowing === null`,
- * so `stdin.isPaused()` returns false, the discarder skips its `stdin.resume()`,
- * and its `prependListener('data')` never switches the stream to flowing —
- * because Node's readable only auto-resumes for `on('data')`, not
- * `prependListener('data')`. The net effect: while such a spinner is running,
- * Ctrl-C is swallowed entirely — the terminal won't raise SIGINT and the
- * discarder never sees the byte to re-raise it.
- *
- * That is invisible for a sub-second spinner, but any spinner wrapping a long
- * idle wait — a cross-machine SSH fan-out, a fleet search — traps the user for
- * the full duration (measured: `agents sessions --flat` could not be Ctrl-C'd
- * for the entire ~12s+ sweep and had to be SIGKILLed). The global SIGINT handler
- * in `index.ts` (`process.exit(130)`) is correct; it simply never fires because
- * no SIGINT is ever raised.
- *
- * Setting `discardStdin: false` keeps the terminal in cooked mode, so Ctrl-C
- * raises SIGINT normally (the terminal also SIGINTs the whole foreground process
- * group, reaping the outstanding `ssh` children) and the global handler exits
- * promptly. The only thing lost is cosmetic stray-keystroke discarding during
- * the spin — a worthwhile trade for a spinner the user must be able to abort.
- *
- * Use this for any spinner that wraps a network / fleet / SSH wait. A truly
- * instantaneous local spinner can still use `ora` directly, but preferring this
- * everywhere is harmless.
- */
 import ora from 'ora';
-/**
- * Build an interruptible spinner — a drop-in for `ora(text)` that keeps Ctrl-C
- * working. Returns an unstarted {@link Ora}; call `.start()` as usual.
- */
 export function interruptibleSpinner(text, options) {
     return ora({ ...options, ...(text !== undefined ? { text } : {}), discardStdin: false });
 }

package/dist/lib/sqlite.d.ts

@@ -1,16 +1,3 @@
-/**
- * Runtime-aware compatibility shim for SQLite.
- *
- * Picks `bun:sqlite` under Bun and `node:sqlite` under Node (>=22.5). Avoids
- * the native `better-sqlite3` addon entirely so there is no prebuild compile
- * and no Node/Bun ABI mismatch. Both runtimes are production: `dist/index.js`
- * runs under Node, while the signed standalone `dist/bin/agents` (what the
- * shims exec) embeds Bun.
- *
- * Exposes the small better-sqlite3-shaped surface area the rest of the
- * codebase already uses: `prepare/exec/pragma/transaction/close` on the DB,
- * `run/get/all` on statements.
- */
 interface NativeStmt {
     run(...args: unknown[]): RunResult;
     get(...args: unknown[]): unknown;

package/dist/lib/sqlite.js

@@ -1,26 +1,8 @@
-/**
- * Runtime-aware compatibility shim for SQLite.
- *
- * Picks `bun:sqlite` under Bun and `node:sqlite` under Node (>=22.5). Avoids
- * the native `better-sqlite3` addon entirely so there is no prebuild compile
- * and no Node/Bun ABI mismatch. Both runtimes are production: `dist/index.js`
- * runs under Node, while the signed standalone `dist/bin/agents` (what the
- * shims exec) embeds Bun.
- *
- * Exposes the small better-sqlite3-shaped surface area the rest of the
- * codebase already uses: `prepare/exec/pragma/transaction/close` on the DB,
- * `run/get/all` on statements.
- */
 import { createRequire } from 'module';
 const isBun = typeof globalThis.Bun !== 'undefined';
 const require = createRequire(import.meta.url);
-// node:sqlite emits a process-level ExperimentalWarning the first time it loads.
-// The packaged CLI launches Node with --no-warnings=ExperimentalWarning, but a
-// direct `node dist/...` run (and vitest's subprocesses) does not, so the warning
-// would leak onto stderr and break any command whose --json output is asserted to
-// be clean. Suppress only that single warning for the duration of the load; every
-// other warning passes through untouched.
 function loadNodeSqlite() {
+    // Suppress only node:sqlite's experimental warning; preserve every other process warning.
     const original = process.emitWarning;
     const filtered = ((warning, ...rest) => {
         const name = warning instanceof Error
@@ -41,52 +23,14 @@ function loadNodeSqlite() {
         process.emitWarning = original;
     }
 }
-// Keep BOTH runtimes on createRequire() so Vitest doesn't try to prebundle the
-// built-in sqlite module as a userland package during test collection.
-//
-// The Bun arm used to be `await import('bun:sqlite' as string)`, which made this
-// a TOP-LEVEL AWAIT. esbuild cannot lower top-level await to CJS, so every test
-// that spawns a subprocess through `tsx` (CJS mode) died at transform time with
-// `Top-level await is currently not supported with the "cjs" output format` --
-// 49 failures across 7 files, none of which touch sqlite. `require` is
-// synchronous, so the await disappears and with it the whole failure class.
-//
-// The specifier is held in a variable, not written inline: a literal
-// `require('bun:sqlite')` is statically analyzable, so bundlers and Vitest's
-// collector try to resolve a module that does not exist off-Bun. That
-// indirection is what the old `as string` cast was doing for the dynamic import.
 const BUN_SQLITE = 'bun:sqlite';
 const sqliteMod = isBun
     ? require(BUN_SQLITE)
     : loadNodeSqlite();
-// bun:sqlite exports `Database`; node:sqlite exports `DatabaseSync`.
 const NativeDatabase = sqliteMod.Database
     ?? sqliteMod.DatabaseSync;
-/**
- * bun:sqlite binds a named-parameter object ONLY when its keys carry the SQL
- * sigil (`{ '@id': … }` for `VALUES (@id)`); bare keys (`{ id: … }`) match
- * nothing and every parameter stays NULL, so the first NOT NULL column raises a
- * constraint error and the write is lost. node:sqlite accepts the bare keys.
- * `strict: true` makes bun accept them too, so the bare-key call shape this
- * codebase uses works on both runtimes. node:sqlite has no such option and
- * rejects a second argument that isn't an object, so the argument list is built
- * per runtime.
- *
- * The two runtimes are still not interchangeable at the edges, and only bun's
- * half is exercised by the shipped binary rather than by vitest — so keep binds
- * inside the intersection:
- *   - omit a named key: bun throws `Missing parameter "x"`, node binds NULL.
- *   - pass an extra named key: bun accepts it, node throws `Unknown named
- *     parameter`.
- *   - use sigil keys (`{'@id': …}`): node accepts them, strict bun rejects them.
- *   - a single non-plain object positional arg (e.g. `run(new Date())`) reaches
- *     the named path via bindArgs below and throws under strict bun.
- */
 const NATIVE_ARGS = isBun ? [{ strict: true }] : [];
 function bindArgs(params) {
-    // Both bindings accept positional `(a, b, c)` and named `({ a, b, c })`
-    // forms — bun only under `strict: true` (see NATIVE_ARGS). Pass an object
-    // through unchanged so callers using named binds work.
     if (params.length === 1 &&
         params[0] !== null &&
         typeof params[0] === 'object' &&
@@ -122,24 +66,12 @@ class Database {
     exec(sql) {
         this.inner.exec(sql);
     }
-    // node:sqlite has no dedicated `pragma()` and bun:sqlite's signature differs
-    // slightly from better-sqlite3. `exec('PRAGMA ...')` works on both and is
-    // sufficient for the setter pragmas (`journal_mode = WAL`) used here.
-    // Reader pragmas in this codebase use `db.prepare(...).all()`.
     pragma(stmt) {
         this.inner.exec(`PRAGMA ${stmt}`);
     }
-    // Wrap fn in BEGIN IMMEDIATE/COMMIT, ROLLBACK on throw. Manual on both
-    // runtimes because node:sqlite has no `db.transaction(fn)`.
-    //
-    // BEGIN IMMEDIATE (not BEGIN DEFERRED) is required for write transactions in
-    // WAL mode. BEGIN DEFERRED upgrades the lock lazily on the first write; if
-    // another writer already committed since the transaction started, SQLite
-    // returns SQLITE_BUSY_SNAPSHOT (a sub-code of SQLITE_BUSY that the busy
-    // handler does NOT retry). BEGIN IMMEDIATE claims the write lock upfront so
-    // the busy handler fires correctly and respects busy_timeout.
     transaction(fn) {
         return (...args) => {
+            // IMMEDIATE serializes writers before the callback observes transaction state.
             this.inner.exec('BEGIN IMMEDIATE');
             try {
                 const result = fn(...args);
@@ -150,7 +82,7 @@ class Database {
                 try {
                     this.inner.exec('ROLLBACK');
                 }
-                catch { /* original error wins */ }
+                catch { }
                 throw err;
             }
         };