@nanobpm/nano-workforce 0.56.0 → 0.57.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.57.0](https://github.com/nanobpm/nano-workforce/compare/v0.56.0...v0.57.0) (2026-08-13)
+
+
+### Features
+
+* **app-view:** show epic base branch in epics overview grid ([#159](https://github.com/nanobpm/nano-workforce/issues/159)) ([#164](https://github.com/nanobpm/nano-workforce/issues/164)) ([216cb0f](https://github.com/nanobpm/nano-workforce/commit/216cb0f515561fbaa646725593707ae6a2418246))
+
 # [0.56.0](https://github.com/nanobpm/nano-workforce/compare/v0.55.0...v0.56.0) (2026-08-13)
 
 

package/README.md

@@ -231,9 +231,17 @@ fleet"** form, or POST the same operation the form does:
 ```bash
 curl -sS -X POST http://localhost:3000/app/api/actions/start/plan-fanout \
   -H 'content-type: application/json' \
-  -d '{ "issue": "owner/repo#123" }'
+  -d '{ "issue": "owner/repo#123", "baseBranch": "epic/agent-protocol" }'
 ```
 
+`baseBranch` is **required** (ADR 0003) — it's the integration branch the whole fleet
+branches off and opens every PR against. A missing `epic/*` base is auto-created off the
+default branch's HEAD; a missing non-`epic/*` base is a `400` (must already exist). Two
+optional flags gate the dangerous cases: `confirmDefaultBase: true` is required to name the
+repository default branch as the base, and `allowSharedBase: true` is required when another
+active epic already targets the same custom base. See
+[ADR 0003](docs/adr/0003-epic-base-branch-admission.md) for the full admission model.
+
 ---
 
 ## Configuration

package/SPEC.md

@@ -466,8 +466,12 @@ scalar-only and cannot express the `tasks`/`results` lists, so the workers self-
 `plan_tasks` (one row per slice, tracking its `status`/`pr_key`/`summary`).
 
 **Entry points**: the epic page's "Hand an issue to the fleet" form or
-`POST /app/api/actions/start/plan-fanout` (`{ issue | url }`) — the same flat
-operation the form posts.
+`POST /app/api/actions/start/plan-fanout` (either `{ issue, baseBranch }` or
+`{ url, baseBranch }` — a `oneOf` naming the target by **exactly one** of `issue`
+(`owner/repo#123`) or `url`, plus optional `confirmDefaultBase`/`allowSharedBase`) —
+the same flat operation the form posts. `baseBranch`
+is required and admitted through the ADR 0003 gate (auto-create `epic/*`, confirm-default,
+shared-base guard).
 
 **Visibility**: the home page adds a **Plans** grid (Active: planning/dispatched;
 History: done/failed/abandoned) with a `plan_tasks` child grid showing each task's

package/app/agentGuide.ts

@@ -31,7 +31,7 @@ const RAW_GUIDE: string = (() => {
       "- `GET /status` — every PR in flight, with its engine `processKey` and any open escalation.",
       "- `GET /version` — which code is live.",
       "- `POST /actions/start/convergence-loop` — submit a PR (`{ pr, convergeOnly?, maxRounds?, dependsOn? }`).",
-      "- `POST /actions/start/plan-fanout` — submit an epic (`{ issue }`).",
+      "- `POST /actions/start/plan-fanout` — submit an epic (`{ issue, baseBranch }` or `{ url, baseBranch }`; base is required — a missing `epic/*` base is auto-created, and `confirmDefaultBase`/`allowSharedBase` gate the default-branch and shared-base cases — see ADR 0003).",
       "- `POST /actions/message` — answer an escalation (`escalation-answered`, correlate by PR key).",
       "",
       "Engine (Camunda-8 v2 REST) base for debugging: `__ENGINE__`.",

package/app/github.test.ts

@@ -3,7 +3,7 @@
 // the merge-exclusion graph. Force the token transport and stub `globalThis.fetch`.
 import { test } from "node:test";
 import { assertEquals, assertRejects } from "#test-assert";
-import { fetchPrFiles } from "./github.ts";
+import { BaseBranchMustExistError, ensureBaseBranch, fetchPrFiles } from "./github.ts";
 
 // A fake `fetch` that serves `pages` of file batches; each page N (1-based) returns `pages[N-1]`
 // files (named `f{index}`), setting a `Link: rel="next"` header whenever a later page exists.
@@ -58,3 +58,181 @@ test("fetchPrFiles: throws when the cap genuinely truncates (full last page + ne
     "truncated",
   );
 });
+
+// ── ensureBaseBranch (ADR 0003 rule 2) ──────────────────────────────────────
+// Force the token transport and stub `globalThis.fetch` so the create-if-missing primitive is
+// exercised end-to-end without touching the network: git-ref lookups, default-branch resolution,
+// and ref creation are all served from an in-memory repo model that records every create call.
+interface FakeRepo {
+  repo: string;
+  defaultBranch: string;
+  branches: Map<string, string>; // branch name → head sha (includes the default branch)
+  creates: { ref: string; sha: string }[];
+}
+
+function jsonResponse(obj: unknown, status = 200): Response {
+  return new Response(JSON.stringify(obj), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function githubFetch(state: FakeRepo) {
+  return (url: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const u = new URL(String(url));
+    const method = (init?.method ?? "GET").toUpperCase();
+    const path = u.pathname;
+    // Repo metadata → default branch (fetchDefaultBranch token mode).
+    if (method === "GET" && path === `/repos/${state.repo}`) {
+      return Promise.resolve(jsonResponse({ default_branch: state.defaultBranch }));
+    }
+    // Git ref lookup → head sha or 404.
+    const refPrefix = `/repos/${state.repo}/git/ref/heads/`;
+    if (method === "GET" && path.startsWith(refPrefix)) {
+      const branch = decodeURIComponent(path.slice(refPrefix.length));
+      const sha = state.branches.get(branch);
+      if (sha === undefined) return Promise.resolve(new Response("Not Found", { status: 404 }));
+      return Promise.resolve(jsonResponse({ ref: `refs/heads/${branch}`, object: { sha } }));
+    }
+    // Create ref.
+    if (method === "POST" && path === `/repos/${state.repo}/git/refs`) {
+      // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+      const body = JSON.parse(String(init?.body ?? "{}")) as { ref?: string; sha?: string };
+      const ref = String(body.ref ?? "");
+      const sha = String(body.sha ?? "");
+      const branch = ref.replace(/^refs\/heads\//, "");
+      if (state.branches.has(branch)) {
+        return Promise.resolve(jsonResponse({ message: "Reference already exists" }, 422));
+      }
+      state.creates.push({ ref, sha });
+      state.branches.set(branch, sha);
+      return Promise.resolve(jsonResponse({ ref }, 201));
+    }
+    return Promise.resolve(new Response(`unexpected ${method} ${path}`, { status: 500 }));
+  };
+}
+
+async function withGithub<T>(state: FakeRepo, fn: () => Promise<T>): Promise<T> {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevFetch = globalThis.fetch;
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  globalThis.fetch = githubFetch(state) as typeof fetch;
+  try {
+    return await fn();
+  } finally {
+    globalThis.fetch = prevFetch;
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+  }
+}
+
+test("ensureBaseBranch: existing branch is a no-op (never creates/resets the ref)", async () => {
+  const state: FakeRepo = {
+    repo: "o/exists",
+    defaultBranch: "main",
+    branches: new Map([
+      ["main", "mainsha"],
+      ["epic/already-there", "existingsha"],
+    ]),
+    creates: [],
+  };
+  const result = await withGithub(state, () =>
+    ensureBaseBranch(state.repo, "epic/already-there", "tok"),
+  );
+  assertEquals(result, "exists");
+  assertEquals(state.creates.length, 0);
+  // The ref must be left untouched.
+  assertEquals(state.branches.get("epic/already-there"), "existingsha");
+});
+
+test("ensureBaseBranch: missing epic/* branch is created off the default branch HEAD", async () => {
+  const state: FakeRepo = {
+    repo: "o/create-epic",
+    defaultBranch: "main",
+    branches: new Map([["main", "defaulthead"]]),
+    creates: [],
+  };
+  const result = await withGithub(state, () =>
+    ensureBaseBranch(state.repo, "epic/new-feature", "tok"),
+  );
+  assertEquals(result, "created");
+  assertEquals(state.creates, [{ ref: "refs/heads/epic/new-feature", sha: "defaulthead" }]);
+});
+
+test("ensureBaseBranch: idempotent — a second call once the branch exists is a no-op", async () => {
+  const state: FakeRepo = {
+    repo: "o/idempotent",
+    defaultBranch: "main",
+    branches: new Map([["main", "defaulthead"]]),
+    creates: [],
+  };
+  const first = await withGithub(state, () => ensureBaseBranch(state.repo, "epic/twice", "tok"));
+  assertEquals(first, "created");
+  assertEquals(state.creates.length, 1);
+  // Re-plan / durable head-task re-run: the branch now exists → clean no-op, no second create.
+  const second = await withGithub(state, () => ensureBaseBranch(state.repo, "epic/twice", "tok"));
+  assertEquals(second, "exists");
+  assertEquals(state.creates.length, 1);
+});
+
+test(
+  'ensureBaseBranch: concurrent create race (GET 404 then POST 422) reports "exists", not "created"',
+  async () => {
+    // Simulate losing the create race: the ref lookup 404s (so we attempt a create), but by the
+    // time our POST lands another actor has already created the ref → GitHub answers 422. The
+    // 422 is idempotent, and the outcome must be the honest "exists" (we did not create it), not
+    // a misleading "created". This locks in the retriable semantics for a concurrent create.
+    const state: FakeRepo = {
+      repo: "o/race",
+      defaultBranch: "main",
+      branches: new Map([["main", "defaulthead"]]),
+      creates: [],
+    };
+    // The git-ref lookup for the epic branch always 404s (as if it does not exist yet), while a
+    // concurrent actor has "already created" it so our POST sees a 422.
+    const base = githubFetch(state);
+    const racingFetch = (url: string | URL | Request, init?: RequestInit): Promise<Response> => {
+      const u = new URL(String(url));
+      const method = (init?.method ?? "GET").toUpperCase();
+      const path = u.pathname;
+      if (method === "GET" && path === `/repos/${state.repo}/git/ref/heads/epic/raced`) {
+        return Promise.resolve(new Response("Not Found", { status: 404 }));
+      }
+      if (method === "POST" && path === `/repos/${state.repo}/git/refs`) {
+        return Promise.resolve(jsonResponse({ message: "Reference already exists" }, 422));
+      }
+      return base(url, init);
+    };
+    const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+    const prevFetch = globalThis.fetch;
+    process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+    globalThis.fetch = racingFetch as typeof fetch;
+    try {
+      const result = await ensureBaseBranch(state.repo, "epic/raced", "tok");
+      assertEquals(result, "exists");
+    } finally {
+      globalThis.fetch = prevFetch;
+      if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+      else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+    }
+  },
+);
+
+test("ensureBaseBranch: missing non-epic/* branch throws BaseBranchMustExistError", async () => {
+  const state: FakeRepo = {
+    repo: "o/typo",
+    defaultBranch: "main",
+    branches: new Map([["main", "defaulthead"]]),
+    creates: [],
+  };
+  const err = await withGithub(state, () =>
+    assertRejects(
+      () => ensureBaseBranch(state.repo, "feature/typo", "tok"),
+      BaseBranchMustExistError,
+      "feature/typo",
+    ),
+  );
+  assertEquals(err instanceof BaseBranchMustExistError, true);
+  // A rejected non-epic/* base must never spawn a wrong-rooted branch.
+  assertEquals(state.creates.length, 0);
+});

package/app/github.ts

@@ -454,6 +454,12 @@ export async function fetchDefaultBranch(repo: string, token: string): Promise<s
   return name;
 }
 
+/** Test-only: drop the memoized default-branch entries so a suite can't leak a warmed cache
+ * (which ignores transport/token state on a hit) into a test that expects a cold lookup. */
+export function resetDefaultBranchCache(): void {
+  defaultBranchCache.clear();
+}
+
 /** Whether a branch has already *landed* — i.e. it is the head of a `MERGED` PR. Returns:
  *   • `landed`  — a merged PR exists from this branch → the branch is a dead-end target
  *   • `open`    — an open PR exists from it (still alive)
@@ -672,3 +678,129 @@ export async function enqueueViaComment(
   });
   return r.ok;
 }
+
+// ── Epic base-branch admission (ADR 0003, rule 2) ───────────────────────────
+// `ensureBaseBranch` is the create-if-missing primitive that guarantees an epic's integration
+// branch exists BEFORE any task fans out, with an `epic/*` guard so a typo can't silently spawn a
+// wrong-rooted branch. It is idempotent — an existing branch is a NO-OP (the ref is never reset,
+// which would nuke in-flight task PRs stacked on it) — so it is safe to call repeatedly: at
+// admission (fail fast), from the durable `ensure-base-branch` head task, and again on a re-plan.
+
+/** Thrown when a base branch that does NOT match the `epic/*` convention is missing. A
+ * non-`epic/*` base must already exist — a mistyped name is an operator error, not something to
+ * auto-create off the default branch (that would silently produce a wrong-rooted branch). */
+export class BaseBranchMustExistError extends Error {
+  readonly branch: string;
+  constructor(branch: string) {
+    super(
+      `base branch "${branch}" does not exist and is not an epic/* branch, so it will not be ` +
+        `auto-created — create it first, or use the epic/* convention for an auto-created ` +
+        `integration branch`,
+    );
+    this.name = "BaseBranchMustExistError";
+    this.branch = branch;
+  }
+}
+
+/** Whether `branch` matches the auto-creatable `epic/*` convention (migration 019). */
+function isEpicBranch(branch: string): boolean {
+  return branch.startsWith("epic/");
+}
+
+/** Resolve the head commit SHA of `branch` on `repo`, or `null` when the branch does not exist
+ * (a 404 from the git-ref endpoint). Throws only on a genuine transport failure. */
+async function branchHeadSha(repo: string, branch: string, token: string): Promise<string | null> {
+  const apiPath = `repos/${repo}/git/ref/heads/${branch}`;
+  if (await useGh()) {
+    try {
+      const out = await runGh(["api", apiPath]);
+      // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+      const j = JSON.parse(out) as { object?: { sha?: string } };
+      return j.object?.sha ?? null;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (/\b404\b|not found|no such/i.test(msg)) return null;
+      throw err;
+    }
+  }
+  if (!token) throw new Error(`no GitHub transport available to read ${apiPath}`);
+  const r = await fetch(`https://api.github.com/${apiPath}`, {
+    headers: { authorization: `Bearer ${token}`, accept: "application/vnd.github+json" },
+  });
+  if (r.status === 404) return null;
+  if (!r.ok) throw new Error(`github ${r.status} ${r.statusText}`.trim());
+  // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+  const j = (await r.json()) as { object?: { sha?: string } };
+  return j.object?.sha ?? null;
+}
+
+/** Create `refs/heads/<branch>` pointing at `sha`. Idempotent: a concurrent create / re-plan
+ * that already made the ref (GitHub `422 Reference already exists`) is treated as a no-op.
+ * Returns `true` when this call actually created the ref, `false` when it lost the race and the
+ * ref already existed (the 422 case) — so the caller can report an honest exists/created outcome. */
+async function createBranchRef(
+  repo: string,
+  branch: string,
+  sha: string,
+  token: string,
+): Promise<boolean> {
+  const ref = `refs/heads/${branch}`;
+  if (await useGh()) {
+    try {
+      await runGh(["api", `repos/${repo}/git/refs`, "-X", "POST", "-f", `ref=${ref}`, "-f", `sha=${sha}`]);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (/\b422\b|already exists/i.test(msg)) return false; // idempotent — someone else created it
+      throw err;
+    }
+    return true;
+  }
+  if (!token) throw new Error(`no GitHub transport available to create ${ref}`);
+  const r = await fetch(`https://api.github.com/repos/${repo}/git/refs`, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${token}`,
+      accept: "application/vnd.github+json",
+      "content-type": "application/json",
+    },
+    body: JSON.stringify({ ref, sha }),
+  });
+  if (r.ok) return true;
+  if (r.status === 422) return false; // reference already exists — idempotent
+  throw new Error(`github ${r.status} ${r.statusText}: ${(await r.text()).slice(0, 300)}`.trim());
+}
+
+/** The outcome of `ensureBaseBranch`: the branch was already present (`exists`, a no-op) or was
+ * just created off the default branch HEAD (`created`). */
+export type EnsureBaseBranchResult = "exists" | "created";
+
+/** Guarantee the epic base `branch` exists on `repo` (ADR 0003 rule 2), idempotently:
+ *   • already exists → `"exists"` — NO-OP; the ref is never moved/reset.
+ *   • missing and matches `epic/*` → create `refs/heads/<branch>` off the default branch HEAD,
+ *     return `"created"`.
+ *   • missing and not `epic/*` → throw `BaseBranchMustExistError` (a non-`epic/*` base must
+ *     pre-exist; a typo must fail fast, not silently spawn a wrong-rooted branch).
+ * Safe to call repeatedly (at admission AND as the durable head task, and on a re-plan). */
+export async function ensureBaseBranch(
+  repo: string,
+  branch: string,
+  token: string,
+): Promise<EnsureBaseBranchResult> {
+  const existing = await branchHeadSha(repo, branch, token);
+  if (existing !== null) return "exists"; // never reset an existing ref
+
+  if (!isEpicBranch(branch)) throw new BaseBranchMustExistError(branch);
+
+  const defaultBranch = await fetchDefaultBranch(repo, token);
+  if (!defaultBranch) {
+    throw new Error(`cannot resolve the default branch of ${repo} to create ${branch}`);
+  }
+  const defaultSha = await branchHeadSha(repo, defaultBranch, token);
+  if (!defaultSha) {
+    throw new Error(`cannot resolve HEAD of default branch ${defaultBranch} on ${repo} to create ${branch}`);
+  }
+  // A concurrent create / re-plan may have raced us to the ref (GitHub 422); in that case it
+  // already exists and we did not create it, so report "exists" rather than misleading "created".
+  const created = await createBranchRef(repo, branch, defaultSha, token);
+  return created ? "created" : "exists";
+}