@atlaso-labs/opencode 0.1.1 → 0.2.1

package/lib/mcp.ts

@@ -0,0 +1,300 @@
+/** Atlaso memory MCP server for OpenCode — inline, zero-dep, bun-native.
+ *
+ * Speaks JSON-RPC 2.0 over newline-delimited stdio (the MCP stdio transport) and
+ * exposes the 5 memory tools — recall / remember / forget / recent / status — that
+ * the OTHER Atlaso connectors ship. OpenCode launches it from its opencode.json `mcp`
+ * key as a `type:"local"` server: `bun run <install-dir>/atlaso-mcp.js`.
+ *
+ * WHY inline stdio (not remote): the plugin's hooks already mint this device's OWN
+ * per-tool credential at ~/.atlaso/tools/opencode.json, and this server reuses it via
+ * resolveCredential("opencode"). So capture (hooks) AND the MCP tools authorize with
+ * the SAME token — one credential, one unlink, no second OAuth consent. It works
+ * offline-first and never leaks the engine (thin client — it only knows the brain's URLs).
+ *
+ * STDOUT IS THE PROTOCOL — nothing but JSON-RPC frames may be written there. All
+ * diagnostics go to the debug file (lib/log). One complete JSON object per line.
+ */
+import { forget, health, loadAuth, recall, recent, remember } from "./atlaso";
+import { classifyScope } from "./capture";
+import { resolveCredential } from "./credential";
+import { cloudMode, online } from "./entitlement";
+import { REVOKED } from "./state";
+import { log } from "./log";
+import { currentProjectKey, currentProjectResolution, resultVisibleHere } from "./project";
+
+const NAME = "Atlaso";
+const VERSION = "0.1.0";
+const PROTOCOL = "2024-11-05";
+const TOOL = "opencode";
+
+// The 5-tool surface. Descriptions are the model's only cue for WHEN to call each —
+// keep them action-first and lean (the ~40-tool budget rewards brevity).
+export const TOOLS = [
+  {
+    name: "recall",
+    description:
+      "Search the user's Atlaso long-term memory for notes relevant to `query` — past decisions, preferences, conventions, project facts, gotchas. Call it before answering when prior context would help. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: { query: { type: "string" }, limit: { type: "integer", default: 5 } },
+      required: ["query"],
+    },
+  },
+  {
+    name: "remember",
+    description:
+      "Save a durable fact, decision, preference, or gotcha to Atlaso memory. Project facts stay in the current project; personal preferences remain available across projects. Use for things worth keeping, not transient chatter.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        text: { type: "string" },
+        scope: {
+          type: "string",
+          enum: ["personal", "project"],
+          description: "Optional override. Omit to infer personal vs project from the text.",
+        },
+      },
+      required: ["text"],
+    },
+  },
+  {
+    name: "forget",
+    description:
+      "Permanently delete a memory by its id (ids come from recall/recent). Destructive and not undoable — only when the user asks to forget something.",
+    inputSchema: {
+      type: "object",
+      properties: { id: { type: "string" } },
+      required: ["id"],
+    },
+  },
+  {
+    name: "recent",
+    description: "List the user's most recent memories (newest first). Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: { limit: { type: "integer", default: 10 } },
+    },
+  },
+  {
+    name: "status",
+    description:
+      "Atlaso memory health: connected?, how many memories are stored, and the memory health score (FMI). Read-only.",
+    inputSchema: { type: "object", properties: {} },
+  },
+] as const;
+
+const NOT_LINKED =
+  "Atlaso memory isn't linked on this device yet. Start a OpenCode chat (the plugin links automatically) or run `atlaso connect`.";
+
+
+/** Run one tool. Gates on the SAME entitlement/tombstone check the hooks use
+ *  (`online()`) BEFORE resolving a credential — otherwise a revoked or free-plan-
+ *  gated tool could resurrect on the shared bearer through an MCP call (the hooks
+ *  never can, because they gate first). Then resolves THIS device's per-tool
+ *  credential so every call authorizes as the cursor tool. */
+export async function dispatch(name: string, args: any): Promise<any> {
+  const shared = loadAuth();
+  if (!shared?.token) return { error: NOT_LINKED };
+  const deviceId = shared.device_id ?? null;
+  // The verified-verdict gate: revoked → stay down (sticky); free-plan non-active →
+  // local-only. Never resurrect a removed tool via the shared bearer.
+  if (!(await online(shared, { tool: TOOL, deviceId: deviceId }))) {
+    const mode = cloudMode(shared, { tool: TOOL, deviceId: deviceId });
+    return {
+      error:
+        mode.reason === REVOKED
+          ? "Atlaso memory was removed for OpenCode on this device. Re-add the plugin (or run `atlaso connect`) to turn it back on."
+          : "Atlaso memory is local-only for OpenCode right now — on the free plan only one tool per device is active. Upgrade or switch the active tool at https://app.atlaso.ai.",
+    };
+  }
+  const auth = await resolveCredential(TOOL);
+  if (!auth) return { error: NOT_LINKED };
+  const project = currentProjectKey();
+  switch (name) {
+    case "recall": {
+      const limit = Math.max(1, Math.min(50, Number(args?.limit ?? 5) || 5));
+      const results = await recall(
+        auth,
+        String(args?.query ?? ""),
+        limit,
+        project ?? undefined,
+      );
+      return {
+        results: results
+          .filter((r) => resultVisibleHere(r, project))
+          .slice(0, limit)
+          .map((r) => ({ id: r.id, content: r.content })),
+      };
+    }
+    case "recent": {
+      const limit = Math.max(1, Math.min(50, Number(args?.limit ?? 10) || 10));
+      // `/v1/memories` is global/newest-first, so over-fetch before filtering or a
+      // run of foreign-project rows could crowd every visible memory out of the page.
+      const fetchLimit = Math.min(200, Math.max(limit * 4, 40));
+      const memories = (await recent(auth, fetchLimit))
+        .filter((r) => resultVisibleHere(r, project))
+        .slice(0, limit)
+        .map((r) => ({ id: r.id, content: r.content }));
+      return { memories };
+    }
+    case "remember": {
+      const text = String(args?.text ?? "");
+      const requested = args?.scope === "personal" || args?.scope === "project"
+        ? args.scope
+        : null;
+      const scope = requested ?? classifyScope(text);
+      // NEVER refuse a deliberate save because we could not name the project.
+      // classifyScope defaults to "project", and this is a standalone MCP process
+      // with no hook payload and an arbitrary cwd, so currentProjectKey() is null
+      // more often than not — refusing meant "remember this" routinely failed on
+      // the user's highest-intent memory. Instead mark it unattributed and let it
+      // be visible everywhere: the server already treats a project-scoped row with
+      // no key as visible-with-provenance, which is the same fail-open rule
+      // auto-capture uses. Losing the scope is recoverable; losing the memory is
+      // not. (Bugbot #157, "Remember fails without project key".)
+      // 'none' and 'unknown' are NOT the same and must not be collapsed. A
+      // genuinely non-project root ($HOME) is real personal scope; a garbage
+      // measurement stays project-scoped but unattributed. Auto-capture already
+      // splits them, and claiming parity while collapsing them would be a lie.
+      let effScope = scope;
+      if (scope === "project" && !project && currentProjectResolution().status === "none") {
+        effScope = "personal";
+      }
+      const tags: string[] = [`scope:${effScope}`];
+      if (effScope === "project") {
+        if (project) tags.push(`project:${project}`);
+        else tags.push("project-unknown");
+      }
+      const id = await remember(auth, { text, tags });
+      if (!id) return { saved: false, error: "empty text, or the server was unreachable" };
+      return effScope === "project" && !project
+        ? { saved: true, id, scope: effScope, note: "saved without a project key — this project could not be identified, so the memory is visible everywhere" }
+        : { saved: true, id, scope: effScope };
+    }
+    case "forget": {
+      const id = String(args?.id ?? "");
+      const ok = await forget(auth, id);
+      return ok
+        ? { forgotten: true, id }
+        : { forgotten: false, id, note: "not forgotten — the server was unreachable. Try again when connected." };
+    }
+    case "status": {
+      const h = await health(auth);
+      if (!h) return { connected: false, error: "Atlaso memory is unreachable right now. Try again when connected." };
+      return { connected: true, fmi: h?.fmi ?? null, total: h?.deposit_count ?? null };
+    }
+    default:
+      throw new Error(`unknown tool: ${name}`);
+  }
+}
+
+// ── JSON-RPC 2.0 plumbing ────────────────────────────────────────────────────────
+const ok = (id: any, result: any) => ({ jsonrpc: "2.0", id, result });
+const rpcErr = (id: any, code: number, message: string) => ({ jsonrpc: "2.0", id, error: { code, message } });
+
+/** A dispatch payload that represents a tool-level failure — so tools/call can set the
+ *  MCP `isError` bit while STILL returning the readable JSON the model can act on. */
+function isFailure(r: any): boolean {
+  return !!(r && (r.error || r.saved === false || r.forgotten === false));
+}
+
+/** Handle one JSON-RPC message. Returns the response object, or null for a
+ *  notification (no id) that needs no reply. Never throws. */
+export async function handle(msg: any): Promise<any | null> {
+  const { id, method, params } = msg ?? {};
+  // JSON-RPC: a message with no id is a NOTIFICATION — NEVER reply to one. Replying
+  // would put an id-less frame on stdout and corrupt the transport. (This also covers
+  // notifications/initialized and any progress/cancelled notifications.)
+  if (id === undefined || id === null) return null;
+
+  switch (method) {
+    case "initialize":
+      return ok(id, {
+        // Advertise the version we actually implement — do NOT echo the client's
+        // requested version (that would claim support for a protocol we may not run).
+        protocolVersion: PROTOCOL,
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: NAME, version: VERSION },
+      });
+    case "ping":
+      return ok(id, {});
+    case "tools/list":
+      return ok(id, { tools: TOOLS });
+    case "tools/call": {
+      try {
+        const result = await dispatch(params?.name, params?.arguments ?? {});
+        // Tool-level problems ride back as readable content so the model can act on
+        // them, AND flag isError so a client keying off the bit doesn't read a failure
+        // as success.
+        return ok(id, {
+          content: [{ type: "text", text: JSON.stringify(result) }],
+          ...(isFailure(result) ? { isError: true } : {}),
+        });
+      } catch (e) {
+        return ok(id, {
+          content: [{ type: "text", text: JSON.stringify({ error: e instanceof Error ? e.message : String(e) }) }],
+          isError: true,
+        });
+      }
+    }
+    default:
+      return rpcErr(id, -32601, `method not found: ${method}`);
+  }
+}
+
+// Handlers may finish concurrently, but stdout is one byte stream. Serialize complete
+// frames (including backpressure) so large overlapping responses cannot interleave.
+let writeQueue: Promise<void> = Promise.resolve();
+function writeFrame(resp: any): Promise<void> {
+  const frame = JSON.stringify(resp) + "\n";
+  const write = () => new Promise<void>((resolve, reject) => {
+    process.stdout.write(frame, (err) => err ? reject(err) : resolve());
+  });
+  const task = writeQueue.then(write, write);
+  writeQueue = task.catch(() => {});
+  return task;
+}
+
+/** Read newline-delimited JSON-RPC from stdin, write responses to stdout. Handlers
+ *  run concurrently (no head-of-line blocking); frame writes are serialized. */
+async function main(): Promise<void> {
+  const decoder = new TextDecoder();
+  let buf = "";
+  const inflight = new Set<Promise<void>>(); // drained on EOF so no reply is lost
+  log("mcp", "server up");
+  for await (const chunk of Bun.stdin.stream()) {
+    buf += decoder.decode(chunk as Uint8Array, { stream: true });
+    let nl: number;
+    while ((nl = buf.indexOf("\n")) >= 0) {
+      const line = buf.slice(0, nl).trim();
+      buf = buf.slice(nl + 1);
+      if (!line) continue;
+      let msg: any;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        continue; // a malformed line is not a protocol frame — drop it
+      }
+      // Handlers run concurrently (no head-of-line blocking), but we keep a handle
+      // on each so EOF can drain them — otherwise the process could exit before the
+      // last frame's reply is written.
+      const p = handle(msg)
+        .then(async (resp) => {
+          if (resp) await writeFrame(resp);
+        })
+        .catch((e) => {
+          if (msg?.id != null) return writeFrame(rpcErr(msg.id, -32603, String(e)));
+        })
+        .finally(() => inflight.delete(p));
+      inflight.add(p);
+    }
+  }
+  await Promise.allSettled(inflight); // stdin closed — let pending replies flush
+}
+
+if (import.meta.main) {
+  main().catch((e) => {
+    log("mcp", `fatal ${e}`);
+    process.exit(1);
+  });
+}

package/lib/outbox.ts

@@ -0,0 +1,348 @@
+/** Durable write-ahead outbox for cloud deposits.
+ *
+ *  WHY THIS EXISTS. v1 of this connector was online-first: `capture` built an item,
+ *  POSTed it once, and on ANY failure — timeout, 500, 429, a wifi blip, a brain
+ *  restart mid-deploy — logged `saved=false` and moved on. The memory was gone, and
+ *  neither the user nor we would ever know. The four Python connectors never had
+ *  this hole because they sit on `atlaso_client`'s SQLite cache + outbox. This is
+ *  the same guarantee for the two TypeScript connectors, in the shape their runtime
+ *  allows.
+ *
+ *  THE HARD CONSTRAINT. opencode plugin callbacks are short-lived too — a hook
+ *  event spawns a process that exits. There is no daemon and no timer, so a retry
+ *  can only ever be driven by on-disk state that a LATER hook invocation picks up.
+ *  Everything here is therefore synchronous file I/O with no in-memory state.
+ *
+ *  WRITE-AHEAD, NOT WRITE-BEHIND. The item is persisted BEFORE the network call,
+ *  not after it fails. A process killed mid-request (editor quit, machine sleep,
+ *  hook timeout) has already durably recorded the memory. Enqueue-then-send is the
+ *  only ordering that survives the process dying inside `fetch`.
+ *
+ *  STORAGE: one file per item, written tmp+rename so a reader never sees a partial
+ *  record and a torn write cannot corrupt the queue. Chosen over a single JSONL log
+ *  because two opencode sessions are two concurrent plugin processes appending to the
+ *  same file — an append race on records larger than PIPE_BUF interleaves and
+ *  destroys both. Per-file also makes quarantine a rename and bounds a readdir.
+ *  Chosen over `node:sqlite` because these plugins run on Bun, and over `bun:sqlite`
+ *  because a file-drop plugin must not depend on one runtime's builtin.
+ *
+ *  DEDUPE: the filename is a hash of `client_id`, which is already the server's
+ *  per-item idempotency key (content-derived in capture.ts). Re-enqueueing the same
+ *  turn OVERWRITES rather than duplicating, and a retry of an ambiguous timeout can
+ *  never produce a double memory server-side.
+ *
+ *  NOTHING IS EVER SILENTLY DROPPED. An item the server will always reject, or one
+ *  that exhausts its attempts, is QUARANTINED — moved aside and recorded in a
+ *  ledger — never deleted. That is a product rule, not an implementation detail.
+ */
+import { createHash } from "node:crypto";
+import {
+  closeSync,
+  existsSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+  appendFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { atlasoDir, type DepositItem } from "./atlaso";
+
+/** Bounds are read PER CALL, not at module load — the same convention lock.ts uses
+ *  for its timeout ("read per-call so it stays env-overridable for tests"). Module-
+ *  load constants would force tests to re-import the module under a different
+ *  specifier to change them, which is neither type-safe nor honest about the
+ *  runtime behaviour we actually ship. */
+function num(env: string, dflt: number): number {
+  const n = parseInt(process.env[env] ?? "", 10);
+  return Number.isFinite(n) && n > 0 ? n : dflt;
+}
+
+/** How many items one drain pass will attempt. Bounds the wall-clock a hook can
+ *  spend so a large backlog never stalls the editor; the rest go next hook. */
+export const maxDrainPerRun = () => num("ATLASO_OUTBOX_DRAIN", 25);
+/** Hard queue ceiling. Beyond this the OLDEST are quarantined (not dropped). */
+export const maxQueue = () => num("ATLASO_OUTBOX_MAX", 5000);
+/** An item older than this has almost certainly outlived its usefulness, but it is
+ *  still quarantined rather than deleted so it can be recovered/inspected. */
+export const maxAgeMs = () => num("ATLASO_OUTBOX_MAX_AGE_MS", 30 * 24 * 3600 * 1000);
+/** Attempts before we stop retrying and quarantine. Generous: transient brain
+ *  outages should not burn through this in one bad afternoon. */
+export const maxAttempts = () => num("ATLASO_OUTBOX_MAX_ATTEMPTS", 25);
+
+export interface OutboxRecord {
+  client_id: string;
+  item: DepositItem;
+  enqueued_at: number;
+  attempts: number;
+  last_error?: string;
+}
+
+/** What a push attempt concluded about ONE item. Drives whether it leaves the
+ *  queue, stays for a retry, or is parked forever. */
+export type Disposition = "settled" | "retry" | "quarantine";
+
+export function outboxDir(tool: string): string {
+  return join(atlasoDir(), "outbox", tool);
+}
+export function quarantineDir(tool: string): string {
+  return join(outboxDir(tool), "quarantine");
+}
+function ledgerPath(tool: string): string {
+  return join(outboxDir(tool), "quarantine.log");
+}
+
+/** sha256 of the idempotency key — filesystem-safe, collision-free in practice, and
+ *  deterministic so the same turn always maps to the same file (dedupe). */
+function fileFor(clientId: string): string {
+  return createHash("sha256").update(clientId).digest("hex").slice(0, 32) + ".json";
+}
+
+function ensureDir(p: string): boolean {
+  try {
+    mkdirSync(p, { recursive: true, mode: 0o700 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Atomic single-file write: unique temp in the SAME directory (so rename is a
+ *  cheap intra-filesystem move), fsync the bytes, then rename over the target.
+ *  A reader therefore sees either the old record or the new one, never a splice. */
+function writeAtomic(path: string, body: string): boolean {
+  const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  let fd: number | null = null;
+  try {
+    writeFileSync(tmp, body, { mode: 0o600 });
+    try {
+      fd = openSync(tmp, "r+");
+      fsyncSync(fd); // durability: survive a machine crash, not just a process exit
+    } catch {
+      /* fsync unavailable/unsupported — the rename below is still atomic */
+    } finally {
+      if (fd !== null) {
+        try {
+          closeSync(fd);
+        } catch {
+          /* already closed */
+        }
+      }
+    }
+    renameSync(tmp, path);
+    return true;
+  } catch {
+    try {
+      unlinkSync(tmp);
+    } catch {
+      /* temp already gone */
+    }
+    return false;
+  }
+}
+
+/**
+ * Persist an item BEFORE it is sent. Idempotent on `client_id`: enqueueing the
+ * same turn twice (Cursor fires stop AND sessionEnd for one turn) overwrites.
+ * Returns false only if the disk itself is unusable — the caller still attempts
+ * the network, so a read-only home directory degrades to today's behaviour rather
+ * than blocking capture.
+ */
+export function enqueue(tool: string, item: DepositItem): boolean {
+  const dir = outboxDir(tool);
+  if (!ensureDir(dir)) return false;
+  const existing = readRecord(join(dir, fileFor(item.client_id)));
+  const rec: OutboxRecord = {
+    client_id: item.client_id,
+    item,
+    // Preserve the ORIGINAL enqueue time across re-enqueues so age bounds measure
+    // how long the memory has been stranded, not when we last saw the turn.
+    enqueued_at: existing?.enqueued_at ?? Date.now(),
+    attempts: existing?.attempts ?? 0,
+  };
+  return writeAtomic(join(dir, fileFor(item.client_id)), JSON.stringify(rec));
+}
+
+function readRecord(path: string): OutboxRecord | null {
+  try {
+    const rec = JSON.parse(readFileSync(path, "utf8")) as OutboxRecord;
+    if (!rec || typeof rec.client_id !== "string" || !rec.item) return null;
+    if (typeof rec.attempts !== "number") rec.attempts = 0;
+    if (typeof rec.enqueued_at !== "number") rec.enqueued_at = Date.now();
+    return rec;
+  } catch {
+    return null; // missing, unparseable, or truncated — caller decides
+  }
+}
+
+/** True if anything is waiting. Deliberately cheap (one readdir, no parsing) so it
+ *  can be called from the latency-sensitive prompt path without cost. */
+export function hasPending(tool: string): boolean {
+  try {
+    for (const f of readdirSync(outboxDir(tool))) if (f.endsWith(".json")) return true;
+  } catch {
+    /* no dir yet */
+  }
+  return false;
+}
+
+/**
+ * Oldest-first slice of the queue, capped at `limit`.
+ *
+ * A file that will not parse is QUARANTINED on sight rather than skipped: left in
+ * place it would be re-read and re-fail on every single drain, forever.
+ */
+export function pending(tool: string, limit = maxDrainPerRun()): OutboxRecord[] {
+  const dir = outboxDir(tool);
+  let names: string[];
+  try {
+    names = readdirSync(dir).filter((f) => f.endsWith(".json"));
+  } catch {
+    return [];
+  }
+  const recs: OutboxRecord[] = [];
+  for (const name of names) {
+    const rec = readRecord(join(dir, name));
+    if (rec) recs.push(rec);
+    else quarantineFile(tool, name, "unreadable");
+  }
+  recs.sort((a, b) => a.enqueued_at - b.enqueued_at);
+  return recs.slice(0, limit);
+}
+
+/** Item accepted (or already known) by the server — remove it. */
+export function settle(tool: string, clientId: string): void {
+  try {
+    unlinkSync(join(outboxDir(tool), fileFor(clientId)));
+  } catch {
+    /* already gone — settling twice is fine */
+  }
+}
+
+/** Record a failed attempt. Quarantines once attempts are exhausted, so a
+ *  permanently-poisoned item can never wedge the queue ahead of good ones. */
+export function bumpAttempt(tool: string, rec: OutboxRecord, error: string): Disposition {
+  const next: OutboxRecord = { ...rec, attempts: rec.attempts + 1, last_error: error.slice(0, 200) };
+  if (next.attempts >= maxAttempts()) {
+    quarantine(tool, rec, `max attempts (${next.attempts}): ${error}`);
+    return "quarantine";
+  }
+  writeAtomic(join(outboxDir(tool), fileFor(rec.client_id)), JSON.stringify(next));
+  return "retry";
+}
+
+/** Park an item permanently, with a reason, in a place a human can find it.
+ *  NEVER deletes: the founder's rule is that a user's memory is never silently
+ *  lost, and "we gave up" is exactly the case where that rule earns its keep. */
+export function quarantine(tool: string, rec: OutboxRecord, reason: string): void {
+  quarantineFile(tool, fileFor(rec.client_id), reason);
+}
+
+function quarantineFile(tool: string, name: string, reason: string): void {
+  const qdir = quarantineDir(tool);
+  if (!ensureDir(qdir)) return;
+  const from = join(outboxDir(tool), name);
+  try {
+    renameSync(from, join(qdir, name));
+  } catch {
+    return; // vanished under us — nothing to park
+  }
+  try {
+    appendFileSync(
+      ledgerPath(tool),
+      JSON.stringify({ at: new Date().toISOString(), file: name, reason: reason.slice(0, 300) }) + "\n",
+      { mode: 0o600 },
+    );
+  } catch {
+    /* the ledger is diagnostics; losing a line must not fail the quarantine */
+  }
+}
+
+/** Count of parked items — surfaced by `atlaso status` so this is visible, not
+ *  a silent graveyard. */
+export function quarantineCount(tool: string): number {
+  try {
+    return readdirSync(quarantineDir(tool)).filter((f) => f.endsWith(".json")).length;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Keep the queue bounded. Over-age and over-count items are QUARANTINED, oldest
+ * first — never unlinked. Runs before a drain so bounds are enforced even if the
+ * network has been down for a month.
+ */
+export function enforceBounds(tool: string, now = Date.now()): number {
+  const dir = outboxDir(tool);
+  let names: string[];
+  try {
+    names = readdirSync(dir).filter((f) => f.endsWith(".json"));
+  } catch {
+    return 0;
+  }
+  let parked = 0;
+  const aged: Array<{ name: string; at: number }> = [];
+  for (const name of names) {
+    const rec = readRecord(join(dir, name));
+    let at: number;
+    if (rec) at = rec.enqueued_at;
+    else {
+      // Unreadable: fall back to mtime so it still participates in bounds.
+      try {
+        at = statSync(join(dir, name)).mtimeMs;
+      } catch {
+        continue;
+      }
+    }
+    if (now - at > maxAgeMs()) {
+      quarantineFile(tool, name, "max age exceeded");
+      parked++;
+    } else {
+      aged.push({ name, at });
+    }
+  }
+  const cap = maxQueue();
+  if (aged.length > cap) {
+    aged.sort((a, b) => a.at - b.at);
+    for (const { name } of aged.slice(0, aged.length - cap)) {
+      quarantineFile(tool, name, "queue over capacity");
+      parked++;
+    }
+  }
+  return parked;
+}
+
+/** Present only so tests can start from a known state. */
+export function _resetForTests(tool: string): void {
+  for (const dir of [quarantineDir(tool), outboxDir(tool)]) {
+    try {
+      for (const f of readdirSync(dir)) {
+        try {
+          unlinkSync(join(dir, f));
+        } catch {
+          /* a subdirectory (quarantine/) — skip */
+        }
+      }
+    } catch {
+      /* absent */
+    }
+  }
+}
+
+export function _ledgerPathForTests(tool: string): string {
+  return ledgerPath(tool);
+}
+
+export function _existsForTests(tool: string, clientId: string): boolean {
+  return existsSync(join(outboxDir(tool), fileFor(clientId)));
+}
+
+export function _quarantinedForTests(tool: string, clientId: string): boolean {
+  return existsSync(join(quarantineDir(tool), fileFor(clientId)));
+}