@nanobpm/nano-workforce 0.26.0

package/actions/blackboard.test.ts

@@ -0,0 +1,195 @@
+// Tests for the /hooks/blackboard endpoint (Tier 1, issues #51 / #49 D4).
+import { assertEquals } from "jsr:@std/assert@1";
+import type { AppApi } from "@nanobpm/urban";
+import handler from "./blackboard.ts";
+
+// deno-lint-ignore no-explicit-any
+function memApp(): { app: AppApi; stores: Record<string, any[]> } {
+  // deno-lint-ignore no-explicit-any
+  const stores: Record<string, any[]> = {};
+  const seq: Record<string, number> = {};
+  function tbl(name: string, pk = "id") {
+    // deno-lint-ignore no-explicit-any
+    const rows = (stores[name] ??= [] as any[]);
+    return {
+      // deno-lint-ignore no-explicit-any require-await
+      async insert(row: any) {
+        if (pk === "id") {
+          const id = (seq[name] = (seq[name] ?? 0) + 1);
+          rows.push({ id, ...row });
+          return id;
+        }
+        rows.push({ ...row });
+        return row[pk];
+      },
+      // deno-lint-ignore no-explicit-any require-await
+      async find(where: any = {}) {
+        return rows.filter((r) => Object.entries(where).every(([k, v]) => r[k] === v));
+      },
+      // deno-lint-ignore no-explicit-any require-await
+      async findOne(where: any = {}) {
+        return rows.find((r) => Object.entries(where).every(([k, v]) => r[k] === v));
+      },
+    };
+  }
+  // deno-lint-ignore no-explicit-any
+  const app = { data: { table: (n: string, pk?: string) => tbl(n, pk) } } as any as AppApi;
+  return { app, stores };
+}
+
+function req(method: string, query: Record<string, string>) {
+  return {
+    method,
+    path: "/hooks/blackboard",
+    query: new URLSearchParams(query),
+    headers: new Headers(),
+    text: async () => "",
+  };
+}
+
+async function call(
+  app: AppApi,
+  method: string,
+  query: Record<string, string>,
+  body?: unknown,
+) {
+  // deno-lint-ignore no-explicit-any
+  const res = await handler({ req: req(method, query) as any, body }, app);
+  // deno-lint-ignore no-explicit-any
+  return res as any;
+}
+
+async function seedPlan(app: AppApi, planKey: string, token: string) {
+  await app.data.table("plans", "plan_key").insert({ plan_key: planKey, blackboard_token: token });
+}
+
+Deno.test("missing token → 400", async () => {
+  const { app } = memApp();
+  assertEquals((await call(app, "GET", {})).status, 400);
+});
+
+Deno.test("unknown token → 404 (does not reveal plans)", async () => {
+  const { app } = memApp();
+  await seedPlan(app, "o/r#1", "good");
+  assertEquals((await call(app, "GET", { token: "bad" })).status, 404);
+});
+
+Deno.test("POST appends then GET reads back, scoped by the token's plan", async () => {
+  const { app } = memApp();
+  await seedPlan(app, "o/r#1", "tok");
+  const post = await call(app, "POST", { token: "tok" }, {
+    author_task: "gap-2",
+    kind: "file-claim",
+    files: ["engine/tests.rs"],
+    body: "appending to shared boilerplate",
+  });
+  assertEquals(post.status, 201);
+  assertEquals(post.body.inserted, true);
+
+  const get = await call(app, "GET", { token: "tok" });
+  assertEquals(get.status, 200);
+  assertEquals(get.body.planKey, "o/r#1");
+  assertEquals(get.body.entries.length, 1);
+  assertEquals(get.body.entries[0].files, ["engine/tests.rs"]);
+  assertEquals(get.body.entries[0].kind, "file-claim");
+});
+
+Deno.test("POST with a blank body → 400", async () => {
+  const { app } = memApp();
+  await seedPlan(app, "o/r#1", "tok");
+  assertEquals((await call(app, "POST", { token: "tok" }, { body: "  " })).status, 400);
+});
+
+Deno.test("POST is idempotent on dedupe_key (retry → 200, not a duplicate)", async () => {
+  const { app, stores } = memApp();
+  await seedPlan(app, "o/r#1", "tok");
+  const body = { author_task: "t", body: "claim", dedupe_key: "t:claim:1" };
+  assertEquals((await call(app, "POST", { token: "tok" }, body)).status, 201);
+  const retry = await call(app, "POST", { token: "tok" }, body);
+  assertEquals(retry.status, 200);
+  assertEquals(retry.body.inserted, false);
+  assertEquals(stores["plan_blackboard"].length, 1);
+});
+
+Deno.test("GET ?since returns only newer entries", async () => {
+  const { app } = memApp();
+  await seedPlan(app, "o/r#1", "tok");
+  await call(app, "POST", { token: "tok" }, { body: "one" });
+  await call(app, "POST", { token: "tok" }, { body: "two" });
+  const all = await call(app, "GET", { token: "tok" });
+  const since = String(all.body.entries[0].id);
+  const tail = await call(app, "GET", { token: "tok", since });
+  assertEquals(tail.body.entries.map((e: { body: string }) => e.body), ["two"]);
+});
+
+Deno.test("GET returns a cursor at the plan head for incremental polling (Tier 2)", async () => {
+  const { app } = memApp();
+  await seedPlan(app, "o/r#1", "tok");
+  await call(app, "POST", { token: "tok" }, { body: "one" });
+  await call(app, "POST", { token: "tok" }, { body: "two" });
+  const all = await call(app, "GET", { token: "tok" });
+  assertEquals(all.body.cursor, all.body.entries[1].id, "cursor is the head id");
+  // Poll from the cursor: caught up, cursor holds.
+  const caughtUp = await call(app, "GET", { token: "tok", since: String(all.body.cursor) });
+  assertEquals(caughtUp.body.entries, []);
+  assertEquals(caughtUp.body.cursor, all.body.cursor);
+});
+
+Deno.test("POST file-claim surfaces a sibling's prior claim as a conflict (advisory)", async () => {
+  const { app } = memApp();
+  await seedPlan(app, "o/r#1", "tok");
+  const first = await call(app, "POST", { token: "tok" }, {
+    author_task: "gap-2",
+    kind: "file-claim",
+    files: ["engine/state.rs"],
+    body: "owns state.rs",
+  });
+  assertEquals(first.body.conflicts, [], "first claimer sees no conflict");
+
+  const second = await call(app, "POST", { token: "tok" }, {
+    author_task: "gap-8",
+    kind: "file-claim",
+    files: ["engine/state.rs"],
+    body: "also needs state.rs",
+  });
+  assertEquals(second.status, 201, "the later claim is still recorded (advisory, not blocked)");
+  assertEquals(second.body.conflicts.length, 1);
+  assertEquals(second.body.conflicts[0].author_task, "gap-2", "reports the first (winning) claimer");
+  assertEquals(second.body.conflicts[0].file, "engine/state.rs");
+});
+
+Deno.test("POST file-claim without author_task does not report the caller's own prior 'system' claim as a conflict", async () => {
+  const { app } = memApp();
+  await seedPlan(app, "o/r#1", "tok");
+  // First claim omits author_task → stored as "system".
+  const first = await call(app, "POST", { token: "tok" }, {
+    kind: "file-claim",
+    files: ["engine/state.rs"],
+    body: "system owns state.rs",
+  });
+  assertEquals(first.body.conflicts, []);
+  // Same anonymous caller claims the same file again. Because author_task normalizes to "system" for
+  // both the append and the conflict detection, the earlier "system" row is the caller's own and must
+  // not be reported as a sibling conflict.
+  const second = await call(app, "POST", { token: "tok" }, {
+    author_task: "   ",
+    kind: "file-claim",
+    files: ["engine/state.rs"],
+    body: "system re-claims state.rs",
+  });
+  assertEquals(second.status, 201);
+  assertEquals(second.body.conflicts, [], "own prior 'system' claim is not a conflict");
+});
+
+Deno.test("POST a non-file-claim carries no conflicts", async () => {
+  const { app } = memApp();
+  await seedPlan(app, "o/r#1", "tok");
+  const res = await call(app, "POST", { token: "tok" }, { author_task: "t", kind: "note", body: "fyi" });
+  assertEquals(res.body.conflicts, []);
+});
+
+Deno.test("unsupported method → 405", async () => {
+  const { app } = memApp();
+  await seedPlan(app, "o/r#1", "tok");
+  assertEquals((await call(app, "DELETE", { token: "tok" })).status, 405);
+});

package/actions/blackboard.ts

@@ -0,0 +1,76 @@
+// GET/POST /hooks/blackboard?token=<capabilityToken> — the epic coordination blackboard endpoint
+// (Tier 1, issues #51 / #49 D4).
+//
+// This is a DIRECT side-channel for agents, distinct from the c8ctl-nano activation/completion
+// channel. The per-plan capability token (query string) IS the credential: it scopes every read
+// and write to exactly one plan, so no shared secret is needed — the agent curls the exact URL it
+// was handed in its prompt. An unknown token is a 404 (never leaks which plans exist).
+//
+//   GET  → { planKey, entries: [ { id, author_task, kind, files, body, wave, created_at } ], cursor }
+//          optional ?since=<id> returns only entries with id > since (incremental poll). `cursor` is
+//          the plan's current head id; pass it back as `since` on the next poll (Tier 2).
+//   POST → append one entry: { author_task?, kind?, files?, body, wave?, dedupe_key? }. Idempotent
+//          on (plan, dedupe_key). Returns { id, inserted, conflicts } — `conflicts` lists prior
+//          sibling `file-claim`s on the same file(s) (advisory first-writer-wins; never a lock).
+import type { ActionHandler } from "@nanobpm/urban";
+import {
+  appendEntry,
+  detectFileClaimConflicts,
+  normalizeKind,
+  planKeyForToken,
+  readBlackboardPage,
+} from "../app/blackboard.ts";
+
+const handler: ActionHandler = async ({ req, body }, app) => {
+  const token = (req.query.get("token") ?? req.headers.get("x-blackboard-token") ?? "").trim();
+  if (!token) return { status: 400, body: { error: "missing blackboard token" } };
+  const planKey = await planKeyForToken(app.data, token);
+  if (!planKey) return { status: 404, body: { error: "unknown blackboard token" } };
+
+  if (req.method === "GET") {
+    const rawSince = req.query.get("since");
+    const since = rawSince != null && /^\d+$/.test(rawSince) ? Number(rawSince) : undefined;
+    const { entries, cursor } = await readBlackboardPage(app.data, planKey, { since });
+    return { status: 200, body: { planKey, entries, cursor } };
+  }
+
+  if (req.method === "POST") {
+    const b = (body ?? {}) as Record<string, unknown>;
+    const text = typeof b.body === "string" ? b.body.trim() : "";
+    if (!text) return { status: 400, body: { error: "'body' (the note text) is required" } };
+    const kind = normalizeKind(b.kind);
+    const files = Array.isArray(b.files) ? b.files.map(String) : [];
+    // Normalize once (trim + default to "system") so the value we send to appendEntry matches the
+    // value we send to detectFileClaimConflicts. Otherwise an omitted/blank author_task is stored as
+    // "system" but conflict detection sees "", and the caller's own prior "system" claims are wrongly
+    // reported as sibling conflicts.
+    const author_task = (typeof b.author_task === "string" ? b.author_task.trim() : "") || "system";
+    const res = await appendEntry(app.data, planKey, {
+      author_task,
+      kind,
+      files,
+      body: text,
+      wave: typeof b.wave === "number" ? b.wave : null,
+      dedupe_key: typeof b.dedupe_key === "string" ? b.dedupe_key : undefined,
+    });
+    // Advisory conflict-of-intent: surface prior sibling claims on the same file(s). Computed AFTER
+    // the append and filtered to claims strictly before ours (id < res.id), so first-writer-wins is
+    // decided by insertion order — a sibling that raced a claim in between is still caught, and our
+    // own just-written row is never reported. Never blocks the append — the agent decides how to react.
+    const conflicts = kind === "file-claim"
+      ? await detectFileClaimConflicts(app.data, planKey, {
+        author_task,
+        files,
+        beforeId: Number(res.id),
+      })
+      : [];
+    return {
+      status: res.inserted ? 201 : 200,
+      body: { id: Number(res.id), inserted: res.inserted, conflicts },
+    };
+  }
+
+  return { status: 405, body: { error: "method not allowed (use GET or POST)" } };
+};
+
+export default handler;

package/actions/cancel.ts

@@ -0,0 +1,29 @@
+// POST /app/actions/cancel — override the generic row-cancel action. Terminating the engine
+// instance emits no completion event, so reconcile the app row (status='abandoned', clear the
+// open escalation) here. Accepts either `processInstanceKey` or the `prKey` the status endpoint
+// reports, so a caller can cancel a run it discovered via GET /app/status.
+import type { ActionHandler } from "@nanobpm/urban";
+import { cancelRun } from "../app/service.ts";
+
+const str = (v: unknown): string | undefined => {
+  if (v == null) return undefined;
+  const s = String(v).trim();
+  return s === "" ? undefined : s;
+};
+
+const handler: ActionHandler = async ({ body }, app) => {
+  const b = (body ?? {}) as { processInstanceKey?: unknown; prKey?: unknown };
+  const processInstanceKey = str(b.processInstanceKey);
+  const prKey = str(b.prKey);
+  if (!processInstanceKey && !prKey) {
+    return { status: 400, body: { error: "processInstanceKey or prKey is required" } };
+  }
+  if (processInstanceKey && prKey) {
+    return { status: 400, body: { error: "provide exactly one of processInstanceKey or prKey" } };
+  }
+  const r = await cancelRun(app.data, app.engine, { processInstanceKey, prKey });
+  if (r.ok) return { status: 200, body: r };
+  return { status: r.kind === "terminal" ? 409 : 404, body: r };
+};
+
+export default handler;

package/actions/feature-answer-hook.ts

@@ -0,0 +1,44 @@
+// POST /hooks/feature-answer — answer an implementation-phase task escalation out
+// of band (optional shared-secret guard via X-Hook-Secret, enforced only when
+// NANO_PR_WEBHOOK_SECRET is set — mirrors /hooks/submit and /hooks/plan), issue #25.
+// Lets an external
+// system (a chat relay, a CI job, a human via curl) resume a parked implementation
+// agent without the page. Same idempotent `answerTaskEscalation` path the page's
+// answer form uses.
+//
+// Body accepts either the raw correlation key or a plan+task pair:
+//   { "corrKey": "owner/repo#12:task-3", "answer": "…" }
+//   { "plan": "owner/repo#12", "task": "task-3", "answer": "…" }
+import type { ActionHandler } from "@nanobpm/urban";
+import { answerTaskEscalation, featureCorrKey } from "../app/plan.ts";
+
+const WEBHOOK_SECRET = process.env.NANO_PR_WEBHOOK_SECRET ?? "";
+
+const str = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
+
+const handler: ActionHandler = async ({ req, body }, app) => {
+  if (WEBHOOK_SECRET && req.headers.get("x-hook-secret") !== WEBHOOK_SECRET) {
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  const b = (body ?? {}) as {
+    corrKey?: unknown;
+    plan?: unknown;
+    task?: unknown;
+    answer?: unknown;
+  };
+  const answer = str(b.answer);
+  if (!answer) return { status: 400, body: { error: "answer is required" } };
+
+  const corrKey = str(b.corrKey) || (str(b.plan) && str(b.task) ? featureCorrKey(str(b.plan), str(b.task)) : "");
+  if (!corrKey) {
+    return {
+      status: 400,
+      body: { error: "provide corrKey, or both plan (owner/repo#N) and task" },
+    };
+  }
+
+  const r = await answerTaskEscalation(app.data, app.engine, corrKey, answer);
+  return { status: r.ok ? 200 : 404, body: r };
+};
+
+export default handler;

package/actions/message.ts

@@ -0,0 +1,49 @@
+// POST /app/actions/message — override the generic publishMessage action. For the
+// `escalation-answered` message we run the review answer flow, and for
+// `feature-escalation-answered` the implementation-phase (per-task) answer flow
+// (issue #25): record the answer, resume the parked token, then re-surface the
+// next open escalation. Any other message falls back to a plain publishMessage
+// (this override shadows the generic route entirely, so the fallback preserves it).
+import type { ActionHandler } from "@nanobpm/urban";
+import { answerEscalation } from "../app/service.ts";
+import { answerTaskEscalation, FEATURE_ESCALATION_MESSAGE } from "../app/plan.ts";
+
+const handler: ActionHandler = async ({ body }, app) => {
+  const b = (body ?? {}) as {
+    name?: unknown;
+    correlationKey?: unknown;
+    variables?: Record<string, unknown>;
+  };
+  const name = String(b.name ?? "");
+  if (!name) return { status: 400, body: { error: "name is required" } };
+
+  if (name === "escalation-answered") {
+    const prKey = String(b.correlationKey ?? "");
+    const answer = String((b.variables?.answer ?? "") as string).trim();
+    if (!prKey) return { status: 400, body: { error: "correlationKey is required" } };
+    if (!answer) return { status: 400, body: { error: "answer is required" } };
+    const r = await answerEscalation(app.data, app.engine, prKey, answer);
+    return { status: r.ok ? 200 : 404, body: r };
+  }
+
+  if (name === FEATURE_ESCALATION_MESSAGE) {
+    // Implementation-phase task escalation (issue #25): correlationKey is the
+    // task's `<plan_key>:<task_id>`; record the answer, resume the parked child,
+    // and re-surface the next open escalation.
+    const corrKey = String(b.correlationKey ?? "");
+    const answer = String((b.variables?.answer ?? "") as string).trim();
+    if (!corrKey) return { status: 400, body: { error: "correlationKey is required" } };
+    if (!answer) return { status: 400, body: { error: "answer is required" } };
+    const r = await answerTaskEscalation(app.data, app.engine, corrKey, answer);
+    return { status: r.ok ? 200 : 404, body: r };
+  }
+
+  await app.engine.publishMessage({
+    name,
+    correlationKey: b.correlationKey != null ? String(b.correlationKey) : undefined,
+    variables: b.variables,
+  });
+  return { status: 200, body: { ok: true } };
+};
+
+export default handler;

package/actions/plan-hook.ts

@@ -0,0 +1,19 @@
+// POST /hooks/plan — kick off a planning fan-out out of band (shared-secret auth via
+// X-Hook-Secret). Lets an external system (a GitHub webhook relay on issue open/label, a CI job)
+// hand an issue to the fleet. Same idempotent startPlan path as the page's "Plan issue" action.
+import type { ActionHandler } from "@nanobpm/urban";
+import { parseIssue, startPlan } from "../app/plan.ts";
+
+const WEBHOOK_SECRET = process.env.NANO_PR_WEBHOOK_SECRET ?? "";
+
+const handler: ActionHandler = async ({ req, body }, app) => {
+  if (WEBHOOK_SECRET && req.headers.get("x-hook-secret") !== WEBHOOK_SECRET) {
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  const b = (body ?? {}) as { url?: unknown; issue?: unknown };
+  const parsed = parseIssue(String((b.issue ?? b.url ?? "") as string));
+  if (!parsed) return { status: 400, body: { error: "could not parse issue (use owner/repo#123 or an issue URL)" } };
+  return { status: 202, body: await startPlan(app.data, app.engine, parsed) };
+};
+
+export default handler;

package/actions/plan-start.ts

@@ -0,0 +1,17 @@
+// POST /app/actions/start/plan-fanout — override the generic "start process" action for the
+// planning fan-out. We parse the issue reference and register/refresh the plan aggregate
+// (idempotent on planKey) before starting the process.
+import type { ActionHandler } from "@nanobpm/urban";
+import { parseIssue, startPlan } from "../app/plan.ts";
+
+const handler: ActionHandler = async ({ body }, app) => {
+  const vars = ((body as { variables?: Record<string, unknown> })?.variables ?? {}) as Record<string, unknown>;
+  const raw = String((vars.issue ?? vars.url ?? "") as string).trim();
+  const parsed = parseIssue(raw);
+  if (!parsed) {
+    return { status: 400, body: { error: "could not parse issue (use owner/repo#123 or an issue URL)" } };
+  }
+  return { status: 202, body: await startPlan(app.data, app.engine, parsed) };
+};
+
+export default handler;

package/actions/start.ts

@@ -0,0 +1,19 @@
+// POST /app/actions/start/convergence-loop — override the generic "start process" action.
+// The generic runtime would just createInstance; we first parse the PR reference and
+// register/refresh the PR aggregate (idempotent on prKey) before starting the loop.
+import type { ActionHandler } from "@nanobpm/urban";
+import { clampRounds, MAX_ROUNDS, parsePr, submitPr } from "../app/service.ts";
+
+const handler: ActionHandler = async ({ body }, app) => {
+  const vars = ((body as { variables?: Record<string, unknown> })?.variables ?? {}) as Record<string, unknown>;
+  const raw = String((vars.pr ?? vars.url ?? "") as string).trim();
+  const parsed = parsePr(raw);
+  if (!parsed) {
+    return { status: 400, body: { error: "could not parse PR (use owner/repo#123 or a PR URL)" } };
+  }
+  const dependsOn = Array.isArray(vars.dependsOn) ? vars.dependsOn.map((d) => String(d)) : [];
+  const maxRounds = clampRounds(vars.maxRounds, MAX_ROUNDS);
+  return { status: 202, body: await submitPr(app.data, app.engine, parsed, dependsOn, maxRounds) };
+};
+
+export default handler;

package/actions/status.ts

@@ -0,0 +1,22 @@
+// GET /app/status — list the PRs currently in flight (every tracked PR not converged/abandoned).
+// A read-only projection over the app datasource so an operator or an external automation
+// harness can see active work — and grab a prKey to cancel — without opening the DB or the UI.
+//
+// Optional shared-secret guard, mirroring /hooks/submit: when NANO_PR_WEBHOOK_SECRET is set,
+// callers must present it via the x-hook-secret header. Unset → open (unchanged default). The
+// pages UI does not call this endpoint (its grid reads the datasource directly), so the guard
+// never affects the UI.
+import type { ActionHandler } from "@nanobpm/urban";
+import { activePrs } from "../app/service.ts";
+
+const SECRET = process.env.NANO_PR_WEBHOOK_SECRET ?? "";
+
+const handler: ActionHandler = async ({ req }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  const prs = await activePrs(app.data);
+  return { status: 200, body: { count: prs.length, prs } };
+};
+
+export default handler;

package/actions/webhook-submit.ts

@@ -0,0 +1,21 @@
+// POST /hooks/submit — submit a PR out-of-band (shared-secret auth via X-Hook-Secret). Not
+// part of the page UI; lets an external system (a GitHub webhook relay, a CI job) kick off a
+// convergence run. Same idempotent submit path as the page's "Start review" action.
+import type { ActionHandler } from "@nanobpm/urban";
+import { clampRounds, MAX_ROUNDS, parsePr, submitPr } from "../app/service.ts";
+
+const WEBHOOK_SECRET = process.env.NANO_PR_WEBHOOK_SECRET ?? "";
+
+const handler: ActionHandler = async ({ req, body }, app) => {
+  if (WEBHOOK_SECRET && req.headers.get("x-hook-secret") !== WEBHOOK_SECRET) {
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  const b = (body ?? {}) as { url?: unknown; pr?: unknown; dependsOn?: unknown; maxRounds?: unknown };
+  const parsed = parsePr(String((b.url ?? b.pr ?? "") as string));
+  if (!parsed) return { status: 400, body: { error: "could not parse PR url" } };
+  const dependsOn = Array.isArray(b.dependsOn) ? b.dependsOn.map((d) => String(d)) : [];
+  const maxRounds = clampRounds(b.maxRounds, MAX_ROUNDS);
+  return { status: 202, body: await submitPr(app.data, app.engine, parsed, dependsOn, maxRounds) };
+};
+
+export default handler;

package/app/abandon.test.ts

@@ -0,0 +1,97 @@
+// Tests for the cooperative abandon-check helpers (issue #76).
+import { assertEquals, assertNotEquals } from "jsr:@std/assert@1";
+import type { DataLayer } from "@nanobpm/urban";
+import {
+  abandonStatusForToken,
+  abandonUrl,
+  isAbandoned,
+  mintAbandonToken,
+  prKeyForAbandonToken,
+  renderAbandonBrief,
+} from "./abandon.ts";
+
+// deno-lint-ignore no-explicit-any
+function memData(): DataLayer {
+  // deno-lint-ignore no-explicit-any
+  const stores: Record<string, any[]> = {};
+  function tbl(name: string) {
+    // deno-lint-ignore no-explicit-any
+    const rows = (stores[name] ??= [] as any[]);
+    return {
+      // deno-lint-ignore no-explicit-any require-await
+      async insert(row: any) {
+        rows.push({ ...row });
+        return row.pr_key;
+      },
+      // deno-lint-ignore no-explicit-any require-await
+      async findOne(where: any = {}) {
+        return rows.find((r) => Object.entries(where).every(([k, v]) => r[k] === v));
+      },
+    };
+  }
+  // deno-lint-ignore no-explicit-any
+  return { table: (n: string) => tbl(n) } as any as DataLayer;
+}
+
+async function seedPr(data: DataLayer, pr_key: string, abandon_token: string, status: string) {
+  await data.table("pull_requests", "pr_key").insert({ pr_key, abandon_token, status });
+}
+
+Deno.test("isAbandoned is true only for the 'abandoned' status", () => {
+  assertEquals(isAbandoned("abandoned"), true);
+  assertEquals(isAbandoned("converging"), false);
+  assertEquals(isAbandoned("converged"), false);
+  assertEquals(isAbandoned("merged"), false);
+  assertEquals(isAbandoned(null), false);
+  assertEquals(isAbandoned(undefined), false);
+});
+
+Deno.test("mintAbandonToken is url-safe, unpadded, and unique", () => {
+  const a = mintAbandonToken();
+  const b = mintAbandonToken();
+  assertNotEquals(a, b);
+  assertEquals(/^[A-Za-z0-9_-]+$/.test(a), true, "base64url, no padding");
+  assertEquals(a.includes("="), false);
+});
+
+Deno.test("abandonUrl carries the token on the query string (url-encoded)", () => {
+  assertEquals(
+    abandonUrl("tok+/=", "https://host"),
+    "https://host/hooks/abandon?token=tok%2B%2F%3D",
+  );
+});
+
+Deno.test("renderAbandonBrief embeds the concrete URL and the stop contract", () => {
+  const brief = renderAbandonBrief("https://host/hooks/abandon?token=tok");
+  assertEquals(brief.includes("https://host/hooks/abandon?token=tok"), true);
+  assertEquals(brief.includes("abandoned"), true);
+  assertEquals(brief.includes("Abort"), true);
+  // Must use `curl -f` so a 404 (torn-down run) fails the command instead of exiting 0 with an
+  // error body the agent would parse as "not abandoned".
+  assertEquals(brief.includes("curl -fsS"), true);
+});
+
+Deno.test("prKeyForAbandonToken resolves a known token and rejects unknowns", async () => {
+  const data = memData();
+  await seedPr(data, "o/r#1", "tok", "converging");
+  assertEquals(await prKeyForAbandonToken(data, "tok"), "o/r#1");
+  assertEquals(await prKeyForAbandonToken(data, "nope"), undefined);
+  assertEquals(await prKeyForAbandonToken(data, ""), undefined);
+});
+
+Deno.test("abandonStatusForToken derives abandoned from the row status", async () => {
+  const data = memData();
+  await seedPr(data, "o/r#1", "live", "converging");
+  await seedPr(data, "o/r#2", "dead", "abandoned");
+  assertEquals(await abandonStatusForToken(data, "live"), {
+    prKey: "o/r#1",
+    status: "converging",
+    abandoned: false,
+  });
+  assertEquals(await abandonStatusForToken(data, "dead"), {
+    prKey: "o/r#2",
+    status: "abandoned",
+    abandoned: true,
+  });
+  assertEquals(await abandonStatusForToken(data, "nope"), undefined);
+});