@nanobpm/nano-workforce 0.26.0

package/app/abandon.ts

@@ -0,0 +1,105 @@
+// nano-workforce — cooperative abandon check (issue #76).
+//
+// Cancelling a mid-flight convergence/merge run terminates the engine instance, but the external
+// `senior:*` agent servicing the current job keeps running and would still push a commit, open a
+// PR, or re-request a review. The engine signal (the discarded job → a failing `completeJob`)
+// arrives only AFTER that side effect. This module gives every side-effecting agent a per-PR
+// capability URL it curls RIGHT BEFORE an irreversible action; a cancelled run returns
+// `abandoned: true` and the agent stops without touching git.
+//
+// Design invariants (mirroring the blackboard, app/blackboard.ts):
+//   - CAPABILITY URL. The per-PR token IS the credential; the agent curls the exact URL it was
+//     handed in its prompt. An unknown token is a 404 (never leaks which PRs exist).
+//   - DERIVED, not a separate marker. `abandoned` is read straight off `pull_requests.status`,
+//     which `cancelRun` (app/service.ts) already sets to 'abandoned' on cancel. No new state to
+//     keep in sync.
+//   - ADVISORY. Like the blackboard, this never hard-locks; it narrows an unavoidable
+//     check-then-push (TOCTOU) window to near-zero. Job fencing in the harness (issue #76 layer 2)
+//     is what makes it airtight.
+import type { DataLayer } from "@nanobpm/urban";
+import { publicBaseUrl } from "./blackboard.ts";
+
+/** The one app-row status that means "this run was cancelled". Convergence/merge terminal states
+ * `converged`/`merged` are NOT abandonment — only an explicit cancel flips a live run here. */
+export const ABANDONED_STATUS = "abandoned";
+
+/** True when a PR's app-row status means the run was cancelled and the agent must not act. */
+export function isAbandoned(status: string | null | undefined): boolean {
+  return status === ABANDONED_STATUS;
+}
+
+/** A URL-safe, unguessable capability token (192 bits of randomness, base64url, no padding).
+ * Same shape as the blackboard token; kept local so the two channels stay independent. */
+export function mintAbandonToken(): string {
+  const bytes = new Uint8Array(24);
+  crypto.getRandomValues(bytes);
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/** The capability URL for a PR's abandon check: the token rides the query string so the agent can
+ * GET the exact string it was handed with no header assembly. */
+export function abandonUrl(token: string, base: string = publicBaseUrl()): string {
+  return `${base}/hooks/abandon?token=${encodeURIComponent(token)}`;
+}
+
+/** Resolve an abandon token back to its PR key, or undefined when the token is unknown. */
+export async function prKeyForAbandonToken(
+  data: DataLayer,
+  token: string,
+): Promise<string | undefined> {
+  if (!token) return undefined;
+  const row = await data
+    .table<{ pr_key: string; abandon_token: string | null }>("pull_requests", "pr_key")
+    .findOne({ abandon_token: token });
+  return row?.pr_key;
+}
+
+/** The abandon status of a PR, or undefined when the token is unknown. */
+export async function abandonStatusForToken(
+  data: DataLayer,
+  token: string,
+): Promise<{ prKey: string; status: string; abandoned: boolean } | undefined> {
+  if (!token) return undefined;
+  const row = await data
+    .table<{ pr_key: string; abandon_token: string | null; status: string }>(
+      "pull_requests",
+      "pr_key",
+    )
+    .findOne({ abandon_token: token });
+  if (!row) return undefined;
+  return { prKey: row.pr_key, status: row.status, abandoned: isAbandoned(row.status) };
+}
+
+/** The instruction block appended (verbatim, via `appendPrompt`) to each side-effecting agent's
+ * prompt. It owns its own leading rule (the FEEL that injects it concatenates with no separator),
+ * and carries the concrete, curl-able URL for THIS run plus the abort contract. */
+export function renderAbandonBrief(url: string): string {
+  return `
+
+---
+
+## Abort if this run was cancelled
+
+This run can be **cancelled** by a human while you work. If it is, the orchestration instance is
+gone and your eventual job completion will fail — so any commit, PR, or review you produce would be
+an **orphaned side effect** on a run nobody is waiting for.
+
+**Before every irreversible action — before you \`git push\`, open or update a PR, request a review,
+or merge — check whether the run is still wanted:**
+
+    curl -fsS "${url}"
+
+On success it returns \`{ "prKey": "...", "status": "...", "abandoned": true|false }\`. The \`-f\` is
+important: it makes \`curl\` **exit non-zero on an HTTP error** (e.g. a 404 when the run has been torn
+down), instead of silently printing an error body with exit 0.
+
+- **Abort** — make no commits, push nothing, open no PR, request no review — if EITHER the command
+  **fails** (non-zero exit: the run was cancelled/torn down or the endpoint is unreachable) OR the
+  JSON reports \`"abandoned": true\`. Leave the working tree as-is and exit. A failure when you later
+  try to complete the job is EXPECTED after a cancel — do not treat it as an error to retry.
+- **Proceed** only when the command **succeeds** AND reports \`"abandoned": false\` — and re-check
+  right before the push, since a cancel can land at any moment. Checking as late as possible keeps
+  the window tiny.`;
+}

package/app/baseGuard.test.ts

@@ -0,0 +1,35 @@
+// Unit tests for the dead-end-base guard decision (#60).
+import { assertEquals } from "jsr:@std/assert@1";
+import { type BaseTarget, isDeadEndBase } from "./baseGuard.ts";
+
+const t = (base: string, defaultBranch: string, landed: BaseTarget["landed"]): BaseTarget => ({
+  base,
+  defaultBranch,
+  landed,
+});
+
+Deno.test("dead-end: a non-default base that has already landed", () => {
+  // The exact #54 case: base 'feat/coordination-blackboard' merged to 'main' but wasn't deleted.
+  assertEquals(isDeadEndBase(t("feat/coordination-blackboard", "main", "landed")), true);
+});
+
+Deno.test("NOT a dead-end: the base IS the default branch (the common straight-to-main PR)", () => {
+  // Even if a same-named 'main' somehow reported landed, a PR targeting the default branch is the
+  // normal terminal target — never a dead-end.
+  assertEquals(isDeadEndBase(t("main", "main", "landed")), false);
+});
+
+Deno.test("NOT a dead-end: a live stacked base whose PR is still open", () => {
+  assertEquals(isDeadEndBase(t("feat/tier2", "main", "open")), false);
+});
+
+Deno.test("NOT a dead-end on ambiguity: base has no PR / transport couldn't tell (unknown)", () => {
+  // We block only on a positive `landed` signal, so a legitimately-stacked feature branch that
+  // simply has no PR yet is never wrongly held.
+  assertEquals(isDeadEndBase(t("feat/tier2", "main", "unknown")), false);
+});
+
+Deno.test("unknown-safe: blank base or blank default is never a dead-end", () => {
+  assertEquals(isDeadEndBase(t("", "main", "landed")), false);
+  assertEquals(isDeadEndBase(t("feat/x", "", "landed")), false);
+});

package/app/baseGuard.ts

@@ -0,0 +1,62 @@
+// Dead-end-base guard (#60).
+//
+// The merge stage was base-branch-blind: it ran `gh pr merge <n>` (or an enqueue) into whatever
+// base the PR targeted, never checking that base. In a stacked-PR epic (the model of #49, where
+// each decision PR stacks on the previous branch) a base branch can *itself* merge to the default
+// branch. GitHub only auto-retargets an open PR when its base is DELETED on merge; a
+// merged-but-undeleted base stays the target, `mergeStateStatus` reads CLEAN, and we would land
+// the PR into a dead branch whose contents never reach the default branch.
+//
+// This module detects that case so the merge worker can escalate (retarget) instead of landing.
+
+import { baseBranchLanded, fetchDefaultBranch, fetchPrBase } from "./github.ts";
+
+/** The landing-target facts the dead-end decision is made from. */
+export interface BaseTarget {
+  /** The PR's current base branch. */
+  base: string;
+  /** The repo's default branch (e.g. `main`). */
+  defaultBranch: string;
+  /** Whether the base branch has already landed — see {@link baseBranchLanded}. */
+  landed: "landed" | "open" | "unknown";
+}
+
+/** A base is a dead-end when it is **not** the default branch AND has already landed (a merged PR
+ * exists from it). Ambiguity (`open` / `unknown`) is deliberately never a dead-end: the guard
+ * blocks a merge only on a positive `landed` signal, so a legitimately-stacked PR whose base is
+ * still open — or a base with no PR at all — is never wrongly held. A blank base or default is
+ * unknown-safe → not a dead-end. */
+export function isDeadEndBase(t: BaseTarget): boolean {
+  if (!t.base || !t.defaultBranch) return false;
+  if (t.base === t.defaultBranch) return false;
+  return t.landed === "landed";
+}
+
+export interface BaseGuardResult {
+  deadEnd: boolean;
+  base: string;
+  defaultBranch: string;
+  landed: "landed" | "open" | "unknown";
+}
+
+/** Resolve a PR's landing target and decide whether it is a dead-end. Cheap for the common case:
+ * a PR that targets the default branch short-circuits before the `baseBranchLanded` lookup. Best
+ * effort — when a fact can't be resolved (no transport / GitHub hiccup) it returns `deadEnd:false`
+ * so the guard never blocks a merge on ambiguity; the caller may `.catch()` a transport throw to
+ * the same effect. */
+export async function checkBaseTarget(
+  repo: string,
+  number: number | string,
+  token: string,
+): Promise<BaseGuardResult> {
+  const [base, defaultBranch] = await Promise.all([
+    fetchPrBase(repo, number, token),
+    fetchDefaultBranch(repo, token),
+  ]);
+  if (!base || !defaultBranch || base === defaultBranch) {
+    return { deadEnd: false, base: base ?? "", defaultBranch: defaultBranch ?? "", landed: "unknown" };
+  }
+  const landed = await baseBranchLanded(repo, base, token);
+  const target: BaseTarget = { base, defaultBranch, landed };
+  return { deadEnd: isDeadEndBase(target), base, defaultBranch, landed };
+}

package/app/blackboard.test.ts

@@ -0,0 +1,295 @@
+// Unit tests for the epic coordination blackboard (Tier 1, issues #51 / #49 D4).
+import { assert, assertEquals, assertStringIncludes } from "jsr:@std/assert@1";
+import type { DataLayer } from "@nanobpm/urban";
+import {
+  appendEntry,
+  blackboardUrl,
+  detectFileClaimConflicts,
+  mintBlackboardToken,
+  normalizeKind,
+  planKeyForToken,
+  publicBaseUrl,
+  readBlackboard,
+  readBlackboardPage,
+  renderCoordinationBrief,
+} from "./blackboard.ts";
+
+// A tiny in-memory stand-in for the record gateway, matching the subset of the Table<T> API the
+// blackboard uses (insert/find/findOne). Mirrors the fake-app style used across the app tests.
+// deno-lint-ignore no-explicit-any
+function memData(): { data: DataLayer; 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 data = { table: (n: string, pk?: string) => tbl(n, pk) } as any as DataLayer;
+  return { data, stores };
+}
+
+Deno.test("mintBlackboardToken: URL-safe, unguessable, unique", () => {
+  const a = mintBlackboardToken();
+  const b = mintBlackboardToken();
+  assert(a !== b, "two mints must differ");
+  assert(/^[A-Za-z0-9_-]+$/.test(a), `token must be URL-safe base64url, got ${a}`);
+  assert(a.length >= 32, "token should carry enough entropy");
+});
+
+Deno.test("publicBaseUrl: honours the env override and trims a trailing slash", () => {
+  assertEquals(publicBaseUrl("https://pr.example.com/"), "https://pr.example.com");
+  assertEquals(publicBaseUrl("https://pr.example.com///"), "https://pr.example.com");
+});
+
+Deno.test("publicBaseUrl: a blank/whitespace override falls back instead of yielding a bad URL", () => {
+  const prev = process.env.NANO_PR_BASE_URL;
+  delete process.env.NANO_PR_BASE_URL;
+  try {
+    assertEquals(publicBaseUrl(""), "http://localhost:3000");
+    assertEquals(publicBaseUrl("   "), "http://localhost:3000");
+    assertEquals(blackboardUrl("t", publicBaseUrl("")), "http://localhost:3000/hooks/blackboard?token=t");
+  } finally {
+    if (prev === undefined) delete process.env.NANO_PR_BASE_URL;
+    else process.env.NANO_PR_BASE_URL = prev;
+  }
+});
+
+Deno.test("blackboardUrl: capability token rides the query string", () => {
+  assertEquals(
+    blackboardUrl("tok+en/x", "https://h"),
+    "https://h/hooks/blackboard?token=tok%2Ben%2Fx",
+  );
+});
+
+Deno.test("normalizeKind: valid passes through, anything else becomes note", () => {
+  assertEquals(normalizeKind("file-claim"), "file-claim");
+  assertEquals(normalizeKind("constraint-change"), "constraint-change");
+  assertEquals(normalizeKind("bogus"), "note");
+  assertEquals(normalizeKind(undefined), "note");
+});
+
+Deno.test("renderCoordinationBrief: leads with a separator and teaches the protocol + URL", () => {
+  const url = "https://h/hooks/blackboard?token=abc";
+  const brief = renderCoordinationBrief(url);
+  assert(brief.startsWith("\n\n---"), "must own a leading separator (appendPrompt adds none)");
+  assertStringIncludes(brief, url);
+  // read + write halves of the protocol
+  assertStringIncludes(brief, "curl -s");
+  assertStringIncludes(brief, "-X POST");
+  assertStringIncludes(brief, "author_task");
+  assertStringIncludes(brief, "file-claim");
+  assertStringIncludes(brief, "dedupe_key");
+  // Tier 2: teaches incremental re-reading via the cursor and reacting to a claim conflict.
+  assertStringIncludes(brief, "cursor");
+  assertStringIncludes(brief, "&since=");
+  assertStringIncludes(brief, "conflicts");
+});
+
+Deno.test("planKeyForToken: resolves a token to its plan, undefined otherwise", async () => {
+  const { data } = memData();
+  await data.table("plans", "plan_key").insert({ plan_key: "o/r#7", blackboard_token: "tok7" });
+  assertEquals(await planKeyForToken(data, "tok7"), "o/r#7");
+  assertEquals(await planKeyForToken(data, "nope"), undefined);
+  assertEquals(await planKeyForToken(data, ""), undefined);
+});
+
+Deno.test("appendEntry + readBlackboard: append, encode files, read back in write order", async () => {
+  const { data } = memData();
+  await appendEntry(data, "o/r#1", { author_task: "gap-2", kind: "file-claim", files: ["a.rs"], body: "touches a.rs" });
+  await appendEntry(data, "o/r#1", { author_task: "gap-8", kind: "note", body: "heads up" });
+  await appendEntry(data, "o/r#2", { body: "other plan" }); // must not leak across plans
+
+  const entries = await readBlackboard(data, "o/r#1");
+  assertEquals(entries.map((e) => e.author_task), ["gap-2", "gap-8"], "write order, scoped to plan");
+  assertEquals(entries[0].files, ["a.rs"], "files decoded to an array");
+  assertEquals(entries[1].files, [], "no files → empty array");
+  assertEquals(entries[1].author_task, "gap-8");
+});
+
+Deno.test("appendEntry: trims whitespace-padded file paths so stored/read values are clean", async () => {
+  const { data } = memData();
+  await appendEntry(data, "p", { kind: "file-claim", files: ["  engine/state.rs  ", "\tengine/mine.rs\n"], body: "claims" });
+  const [e] = await readBlackboard(data, "p");
+  assertEquals(e.files, ["engine/state.rs", "engine/mine.rs"], "paths stored trimmed, not whitespace-padded");
+});
+
+Deno.test("appendEntry: a missing author defaults to 'system' and kind is normalised", async () => {
+  const { data } = memData();
+  await appendEntry(data, "p", { body: "x", kind: "weird" as unknown });
+  const [e] = await readBlackboard(data, "p");
+  assertEquals(e.author_task, "system");
+  assertEquals(e.kind, "note");
+});
+
+Deno.test("appendEntry: idempotent on dedupe_key (a job retry re-POST is a no-op)", async () => {
+  const { data, stores } = memData();
+  const first = await appendEntry(data, "p", { author_task: "t", body: "claim", dedupe_key: "t:claim:1" });
+  const again = await appendEntry(data, "p", { author_task: "t", body: "claim", dedupe_key: "t:claim:1" });
+  assertEquals(first.inserted, true);
+  assertEquals(again.inserted, false, "second write with same dedupe_key is a no-op");
+  assertEquals(again.id, first.id, "returns the existing id");
+  assertEquals(stores["plan_blackboard"].length, 1, "exactly one row persisted");
+});
+
+Deno.test("appendEntry: a lost UNIQUE race collapses to a no-op instead of a 500", async () => {
+  // Simulate the concurrency window: two POSTs share a dedupe_key, both miss the findOne
+  // pre-check, then insert loses the race on the UNIQUE (plan_key, dedupe_key) index. The
+  // catch branch must re-read the winner's row and return it rather than propagate the throw.
+  const winner = { id: 42, plan_key: "p", dedupe_key: "t:claim:1", author_task: "t", body: "claim" };
+  let preCheckDone = false;
+  // deno-lint-ignore no-explicit-any
+  const table: any = {
+    // deno-lint-ignore require-await
+    async findOne() {
+      // Pre-check misses (row not yet visible); the recovery read after the collision hits.
+      if (!preCheckDone) {
+        preCheckDone = true;
+        return undefined;
+      }
+      return winner;
+    },
+    // deno-lint-ignore require-await
+    async insert() {
+      throw Object.assign(new Error("UNIQUE constraint failed: plan_blackboard.dedupe_key"), {
+        code: "SQLITE_CONSTRAINT_UNIQUE",
+      });
+    },
+  };
+  // deno-lint-ignore no-explicit-any
+  const data = { table: () => table } as any as DataLayer;
+  const res = await appendEntry(data, "p", { author_task: "t", body: "claim", dedupe_key: "t:claim:1" });
+  assertEquals(res.inserted, false, "a lost race is not a fresh insert");
+  assertEquals(res.id, 42, "returns the winning row's id");
+});
+
+Deno.test("appendEntry: a blank body is rejected", async () => {
+  const { data } = memData();
+  let threw = false;
+  try {
+    await appendEntry(data, "p", { body: "   " });
+  } catch {
+    threw = true;
+  }
+  assert(threw, "blank body must throw");
+});
+
+Deno.test("readBlackboard: since returns only newer entries (incremental poll)", async () => {
+  const { data } = memData();
+  await appendEntry(data, "p", { body: "one" });
+  await appendEntry(data, "p", { body: "two" });
+  await appendEntry(data, "p", { body: "three" });
+  const all = await readBlackboard(data, "p");
+  const tail = await readBlackboard(data, "p", { since: all[0].id });
+  assertEquals(tail.map((e) => e.body), ["two", "three"]);
+});
+
+Deno.test("readBlackboardPage: cursor is the plan head and lets an agent poll to caught-up (Tier 2)", async () => {
+  const { data } = memData();
+  await appendEntry(data, "p", { body: "one" });
+  await appendEntry(data, "p", { body: "two" });
+
+  const first = await readBlackboardPage(data, "p");
+  assertEquals(first.entries.map((e) => e.body), ["one", "two"]);
+  assertEquals(first.cursor, first.entries[1].id, "cursor is the head id");
+
+  // Poll again from the cursor: nothing new, and the cursor holds at the head (not reset to 0).
+  const caughtUp = await readBlackboardPage(data, "p", { since: first.cursor });
+  assertEquals(caughtUp.entries, []);
+  assertEquals(caughtUp.cursor, first.cursor, "a caught-up poll keeps the head cursor");
+
+  // A sibling posts; the next poll from the cursor returns only the new entry and advances.
+  await appendEntry(data, "p", { body: "three" });
+  const next = await readBlackboardPage(data, "p", { since: first.cursor });
+  assertEquals(next.entries.map((e) => e.body), ["three"]);
+  assertEquals(next.cursor, next.entries[0].id);
+});
+
+Deno.test("readBlackboardPage: an empty plan yields no entries and a zero cursor", async () => {
+  const { data } = memData();
+  const page = await readBlackboardPage(data, "empty");
+  assertEquals(page.entries, []);
+  assertEquals(page.cursor, 0);
+});
+
+Deno.test("detectFileClaimConflicts: a sibling's prior claim on the same file is surfaced", async () => {
+  const { data } = memData();
+  await appendEntry(data, "p", { author_task: "gap-2", kind: "file-claim", files: ["engine/state.rs"], body: "owns state.rs" });
+
+  const conflicts = await detectFileClaimConflicts(data, "p", {
+    author_task: "gap-8",
+    files: ["engine/state.rs", "engine/mine.rs"],
+  });
+  assertEquals(conflicts.length, 1, "only the overlapping file is a conflict");
+  assertEquals(conflicts[0].file, "engine/state.rs");
+  assertEquals(conflicts[0].author_task, "gap-2", "reports the first (winning) claimer");
+});
+
+Deno.test("detectFileClaimConflicts: your own prior claim and non-file-claim entries are not conflicts", async () => {
+  const { data } = memData();
+  await appendEntry(data, "p", { author_task: "gap-2", kind: "file-claim", files: ["a.rs"], body: "my earlier claim" });
+  await appendEntry(data, "p", { author_task: "gap-8", kind: "note", files: ["a.rs"], body: "just a note about a.rs" });
+
+  // Re-claiming my own file: no self-conflict, and the sibling's note (not a file-claim) is ignored.
+  assertEquals(
+    await detectFileClaimConflicts(data, "p", { author_task: "gap-2", files: ["a.rs"] }),
+    [],
+  );
+  // No files to claim → nothing to conflict on.
+  assertEquals(await detectFileClaimConflicts(data, "p", { author_task: "gap-9", files: [] }), []);
+});
+
+Deno.test("detectFileClaimConflicts: beforeId restricts to strictly prior claims (insertion order wins)", async () => {
+  const { data } = memData();
+  const prior = await appendEntry(data, "p", {
+    author_task: "gap-2",
+    kind: "file-claim",
+    files: ["a.rs"],
+    body: "prior sibling claim",
+  });
+  const mine = await appendEntry(data, "p", {
+    author_task: "gap-8",
+    kind: "file-claim",
+    files: ["a.rs"],
+    body: "my claim",
+  });
+  const later = await appendEntry(data, "p", {
+    author_task: "gap-9",
+    kind: "file-claim",
+    files: ["a.rs"],
+    body: "sibling that claimed after me",
+  });
+
+  // Computed after my insert, filtered to id < mine: only the strictly-prior sibling is a conflict —
+  // my own row and the later sibling's row are excluded even though both overlap the file.
+  const conflicts = await detectFileClaimConflicts(data, "p", {
+    author_task: "gap-8",
+    files: ["a.rs"],
+    beforeId: Number(mine.id),
+  });
+  assertEquals(conflicts.length, 1);
+  assertEquals(conflicts[0].id, Number(prior.id));
+  assertEquals(conflicts[0].author_task, "gap-2");
+  assert(Number(later.id) > Number(mine.id));
+});