@nanobpm/nano-workforce 0.73.1 → 0.75.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.75.0](https://github.com/nanobpm/nano-workforce/compare/v0.74.0...v0.75.0) (2026-08-17)
+
+
+### Features
+
+* surface issue/PR titles on dispatch surfaces ([#248](https://github.com/nanobpm/nano-workforce/issues/248)) ([#249](https://github.com/nanobpm/nano-workforce/issues/249)) ([a63f6dd](https://github.com/nanobpm/nano-workforce/commit/a63f6dd9bab3040cdc61c807bdc999ce9a591299))
+
+# [0.74.0](https://github.com/nanobpm/nano-workforce/compare/v0.73.1...v0.74.0) (2026-08-16)
+
+
+### Features
+
+* **feature:** thread optional custom instructions to the implementation agent ([#247](https://github.com/nanobpm/nano-workforce/issues/247)) ([8b65495](https://github.com/nanobpm/nano-workforce/commit/8b65495a739b01560937fa108ed4def16c3ffd85))
+
 ## [0.73.1](https://github.com/nanobpm/nano-workforce/compare/v0.73.0...v0.73.1) (2026-08-16)
 
 

package/app/feature.test.ts

@@ -5,10 +5,27 @@
 // drive it against an in-memory data layer + a stub engine and assert the row shape, the
 // short-circuit on an already-running run, the in-place restart of a settled run, and the seeded
 // process variables (the single `task` slice + the base-branch brief).
-import { test } from "node:test";
+import { after, test } from "node:test";
 import { assertEquals } from "#test-assert";
 import { FEATURE_PROCESS_ID, FEATURE_TERMINAL_STATUSES, featureTaskId, startFeature } from "./feature.ts";
 
+// `startFeature` now fetches the issue title (issue #248) via the GitHub transport. Force the token
+// transport with no token so the fetch is a hermetic no-op (returns null) — no `gh` subprocess, no
+// network — and the row `title` deterministically coalesces to the `owner/repo#N` key. A dedicated
+// test below stubs a successful fetch to cover the real-title path. Capture the prior values and
+// restore them after this file's tests so the module-scope mutation never leaks into other test
+// files under concurrent `node --test`.
+const PRIOR_TRANSPORT = process.env["NANO_PR_GITHUB_TRANSPORT"];
+const PRIOR_TOKEN = process.env["GITHUB_TOKEN"];
+process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+delete process.env["GITHUB_TOKEN"];
+after(() => {
+  if (PRIOR_TRANSPORT === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+  else process.env["NANO_PR_GITHUB_TRANSPORT"] = PRIOR_TRANSPORT;
+  if (PRIOR_TOKEN === undefined) delete process.env["GITHUB_TOKEN"];
+  else process.env["GITHUB_TOKEN"] = PRIOR_TOKEN;
+});
+
 function memTable(rows: any[], key: string) {
   return {
     get: (k: any) => Promise.resolve(rows.find((r) => r[key] === k) ?? null),
@@ -114,6 +131,42 @@ test("startFeature: seeds the single task slice + base-branch brief onto the ins
   assertEquals(v.status, null);
 });
 
+test("startFeature: custom instructions ride the instance as a variable (trimmed)", async () => {
+  let captured: any = null;
+  const engine = {
+    createInstance: (req: any) => {
+      captured = req;
+      return Promise.resolve({ processInstanceKey: "PI-3" });
+    },
+  } as any;
+  await startFeature(
+    memData({ feature_runs: { rows: [], key: "feature_key" } }),
+    engine,
+    PARSED,
+    "main",
+    false,
+    false,
+    "  prefer Deno; keep the diff small  ",
+  );
+  assertEquals(captured.variables.customInstructions, "prefer Deno; keep the diff small");
+});
+
+test("startFeature: blank/absent custom instructions are seeded as null", async () => {
+  let captured: any = null;
+  const engine = {
+    createInstance: (req: any) => {
+      captured = req;
+      return Promise.resolve({ processInstanceKey: "PI-4" });
+    },
+  } as any;
+  // Absent (default arg) → null.
+  await startFeature(memData({ feature_runs: { rows: [], key: "feature_key" } }), engine, PARSED, "main", false, false);
+  assertEquals(captured.variables.customInstructions, null);
+  // Whitespace-only → null (so the appendPrompt FEEL skips the block instead of appending an empty heading).
+  await startFeature(memData({ feature_runs: { rows: [], key: "feature_key" } }), engine, PARSED, "main", false, false, "   ");
+  assertEquals(captured.variables.customInstructions, null);
+});
+
 test("startFeature: an already-running run short-circuits (no new instance)", async () => {
   const stores = {
     feature_runs: {
@@ -185,3 +238,48 @@ test("startFeature: a settled run is restarted in place (status reset, pr/outcom
   assertEquals(row.auto_merge, 1);
   assertEquals(row.process_key, "PI-2");
 });
+
+// Issue #248: the human-readable identity for the feature grids. Every start persists a non-blank
+// `title` — the fetched issue title when available, else the `owner/repo#N` key — on BOTH the insert
+// (new run) and update (in-place restart) paths, so the title-led grid never renders a blank cell.
+test("startFeature: coalesces title to the key when the fetch yields nothing (insert path)", async () => {
+  const stores = { feature_runs: { rows: [] as any[], key: "feature_key" } };
+  const engine = { createInstance: () => Promise.resolve({ processInstanceKey: "PI-T1" }) } as any;
+  await startFeature(memData(stores), engine, PARSED, "main", false, false);
+  assertEquals(stores.feature_runs.rows[0].title, "owner/repo#42");
+});
+
+test("startFeature: repopulates a non-blank title on the in-place restart (update path)", async () => {
+  const stores = {
+    feature_runs: {
+      rows: [{ feature_key: "owner/repo#42", status: "opened", title: null, process_key: "PI-OLD" }],
+      key: "feature_key",
+    },
+  };
+  const engine = { createInstance: () => Promise.resolve({ processInstanceKey: "PI-T2" }) } as any;
+  await startFeature(memData(stores), engine, PARSED, "main", false, false);
+  assertEquals(stores.feature_runs.rows[0].title, "owner/repo#42");
+});
+
+test("startFeature: persists the real issue title when the fetch succeeds", async () => {
+  const prevTok = process.env["GITHUB_TOKEN"];
+  const prevFetch = globalThis.fetch;
+  process.env["GITHUB_TOKEN"] = "t0ken";
+  globalThis.fetch = ((url: string | URL | Request) => {
+    const u = String(url);
+    if (u.endsWith("/repos/owner/repo/issues/42")) {
+      return Promise.resolve(new Response(JSON.stringify({ title: "Add the widget" }), { status: 200 }));
+    }
+    throw new Error(`unexpected fetch: ${u}`);
+  }) as typeof fetch;
+  try {
+    const stores = { feature_runs: { rows: [] as any[], key: "feature_key" } };
+    const engine = { createInstance: () => Promise.resolve({ processInstanceKey: "PI-T3" }) } as any;
+    await startFeature(memData(stores), engine, PARSED, "main", false, false);
+    assertEquals(stores.feature_runs.rows[0].title, "Add the widget");
+  } finally {
+    globalThis.fetch = prevFetch;
+    if (prevTok === undefined) delete process.env["GITHUB_TOKEN"];
+    else process.env["GITHUB_TOKEN"] = prevTok;
+  }
+});

package/app/feature.ts

@@ -15,6 +15,7 @@
 // Data access goes through the record gateway (`data.table`), never hand-written
 // SQL — matching app/plan.ts and app/service.ts.
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
+import { coalesceTitle, fetchIssueTitle } from "./github.ts";
 import { ESCALATION_SLA_TIMEOUT, normalizeBaseBranch, type ParsedIssue, renderBaseBranchBrief } from "./plan.ts";
 
 /** The BPMN process this module drives (resources/processes/feature.bpmn). */
@@ -32,6 +33,11 @@ export interface FeatureRun {
   repo: string;
   issue_number: number;
   issue_url: string;
+  /** Human-readable identity (the GitHub issue title) for the feature grids (issue #248). Fetched
+   * best-effort at `startFeature` and coalesced to the `owner/repo#N` key at write time, so it is
+   * ALWAYS non-blank — the grid's `{{title}}` template needs no fallback and a failed/absent title
+   * fetch still shows a usable identity (the key) rather than an empty cell. */
+  title: string | null;
   base_branch: string;
   status: FeatureRunStatus;
   process_key: string | null;
@@ -267,7 +273,14 @@ export async function startFeature(
   baseBranch: string,
   converge: boolean,
   autoMerge: boolean,
+  customInstructions: string | null = null,
 ) {
+  // Operator free-text steering for the implementation agent (issue #172 follow-on): blank/absent →
+  // null so the implement task's `appendPrompt` FEEL (`customInstructions = null`) skips the block
+  // rather than appending an empty "Operator custom instructions" heading.
+  const instructions = typeof customInstructions === "string" && customInstructions.trim() !== ""
+    ? customInstructions.trim()
+    : null;
   const table = featureRuns(data);
   const existing = await table.get(parsed.planKey);
   if (existing && !FEATURE_TERMINAL_STATUSES.includes(existing.status)) {
@@ -275,11 +288,20 @@ export async function startFeature(
   }
   const base = normalizeBaseBranch(baseBranch);
   const ts = now();
+  // Human-readable identity for the feature grids (issue #248): fetch the issue title best-effort
+  // and coalesce to the `owner/repo#N` key so `feature_runs.title` is ALWAYS non-blank (see the
+  // interface note); a blank/whitespace fetch counts as missing. A fetch failure never blocks the
+  // start (`fetchIssueTitle` returns null on any error).
+  const title = coalesceTitle(
+    await fetchIssueTitle(parsed.repo, parsed.number, process.env.GITHUB_TOKEN ?? ""),
+    parsed.planKey,
+  );
   if (existing) {
     await table.update(parsed.planKey, {
       status: "running",
       base_branch: base,
       issue_url: parsed.url,
+      title,
       pr_key: null,
       converge: converge ? 1 : 0,
       auto_merge: autoMerge ? 1 : 0,
@@ -296,6 +318,7 @@ export async function startFeature(
       repo: parsed.repo,
       issue_number: parsed.number,
       issue_url: parsed.url,
+      title,
       base_branch: base,
       status: "running",
       process_key: null,
@@ -356,6 +379,10 @@ export async function startFeature(
       // brief rides `appendPrompt` in the implement task, exactly like the epic implementer.
       baseBranch: base,
       baseBranchBrief: renderBaseBranchBrief(base),
+      // Optional operator steering, appended to the implement agent's prompt via the implement
+      // task's `appendPrompt` FEEL (feature.bpmn). Null when none was supplied; persists on the
+      // instance so it also rides the answer-loop redispatch back into the same implement task.
+      customInstructions: instructions,
     },
   });
   const processKey = processInstanceKey == null ? null : String(processInstanceKey);

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 { BaseBranchMustExistError, ensureBaseBranch, fetchPrFiles, isNotAPullRequestError } from "./github.ts";
+import { BaseBranchMustExistError, coalesceTitle, ensureBaseBranch, fetchIssueTitle, fetchPrFiles, isNotAPullRequestError } 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.
@@ -259,3 +259,79 @@ test("isNotAPullRequestError: transient failures stay blocking (false)", () => {
   assertEquals(isNotAPullRequestError(new Error("fetch failed")), false);
   assertEquals(isNotAPullRequestError(null), false);
 });
+
+// Issue #248: `fetchIssueTitle` labels the epics/feature rows with the real GitHub issue title. It
+// is best-effort and MUST be tolerant of failure (returns null, never throws) so a title fetch can
+// never block an epic/feature start — the caller falls back to the `owner/repo#N` key.
+function withTitleFetch<T>(
+  fetchImpl: typeof globalThis.fetch,
+  token: string | undefined,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevTok = process.env["GITHUB_TOKEN"];
+  const prevFetch = globalThis.fetch;
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  if (token === undefined) delete process.env["GITHUB_TOKEN"];
+  else process.env["GITHUB_TOKEN"] = token;
+  globalThis.fetch = fetchImpl;
+  const restore = () => {
+    globalThis.fetch = prevFetch;
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+    if (prevTok === undefined) delete process.env["GITHUB_TOKEN"];
+    else process.env["GITHUB_TOKEN"] = prevTok;
+  };
+  return fn().finally(restore);
+}
+
+test("fetchIssueTitle: returns the title on a successful token-transport read", async () => {
+  const stub = ((url: string | URL | Request) => {
+    assertEquals(String(url).endsWith("/repos/owner/repo/issues/248"), true);
+    return Promise.resolve(new Response(JSON.stringify({ title: "Surface titles" }), { status: 200 }));
+  }) as typeof fetch;
+  const title = await withTitleFetch(stub, "t0ken", () => fetchIssueTitle("owner/repo", 248, "t0ken"));
+  assertEquals(title, "Surface titles");
+});
+
+test("fetchIssueTitle: a non-2xx response yields null (best-effort, never throws)", async () => {
+  const stub = (() => Promise.resolve(new Response("nope", { status: 404 }))) as typeof fetch;
+  const title = await withTitleFetch(stub, "t0ken", () => fetchIssueTitle("owner/repo", 999, "t0ken"));
+  assertEquals(title, null);
+});
+
+test("fetchIssueTitle: a thrown transport error is swallowed to null", async () => {
+  const stub = (() => Promise.reject(new Error("network down"))) as typeof fetch;
+  const title = await withTitleFetch(stub, "t0ken", () => fetchIssueTitle("owner/repo", 7, "t0ken"));
+  assertEquals(title, null);
+});
+
+test("fetchIssueTitle: token mode with no token is a no-op (null)", async () => {
+  const stub = (() => {
+    throw new Error("fetch must not be called without a token");
+  }) as typeof fetch;
+  const title = await withTitleFetch(stub, undefined, () => fetchIssueTitle("owner/repo", 7, ""));
+  assertEquals(title, null);
+});
+
+// Issue #248: `coalesceTitle` guarantees a non-blank identity for the title-led grids. A best-effort
+// fetch can legitimately return "" (or whitespace) — `??` would persist that blank; `coalesceTitle`
+// treats it as missing (matching the 036 backfill's `trim(title) = ''`) and falls back to the key.
+test("coalesceTitle: a non-blank first candidate wins", () => {
+  assertEquals(coalesceTitle("Real title", "owner/repo#1"), "Real title");
+});
+
+test("coalesceTitle: null/undefined candidates fall through to the key", () => {
+  assertEquals(coalesceTitle(null, "owner/repo#1"), "owner/repo#1");
+  assertEquals(coalesceTitle(undefined, "owner/repo#1"), "owner/repo#1");
+});
+
+test("coalesceTitle: a blank/whitespace title counts as missing", () => {
+  assertEquals(coalesceTitle("", "owner/repo#1"), "owner/repo#1");
+  assertEquals(coalesceTitle("   ", "owner/repo#1"), "owner/repo#1");
+});
+
+test("coalesceTitle: skips a blank middle candidate to the next non-blank one", () => {
+  assertEquals(coalesceTitle("", "Prior title", "owner/repo#1"), "Prior title");
+  assertEquals(coalesceTitle(null, "  ", "owner/repo#1"), "owner/repo#1");
+});

package/app/github.ts

@@ -429,6 +429,50 @@ export async function fetchPrMeta(
   return { title: j.title ?? null, body: j.body ?? "", headRef: j.head?.ref ?? null };
 }
 
+/** Fetch an issue's title via the configured transport, mirroring `fetchPrMeta` (both `gh` and
+ * token transports). Best-effort and tolerant of failure: returns `null` when no transport is
+ * usable OR when the fetch fails/returns no title, so a caller can label a row with the real issue
+ * title on success and fall back to the `owner/repo#N` key otherwise — a title fetch must never
+ * block an epic/feature start. Unlike the merge-stage reads it does NOT throw on a transport
+ * failure; the identity it feeds is cosmetic, not a correctness gate. */
+export async function fetchIssueTitle(
+  repo: string,
+  number: number | string,
+  token: string,
+): Promise<string | null> {
+  try {
+    if (await useGh()) {
+      const out = await runGh(["issue", "view", String(number), "--repo", repo, "--json", "title"]);
+      // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+      const j = JSON.parse(out) as { title?: string };
+      return j.title ?? null;
+    }
+    if (!token) return null; // token mode with no token → no identity to fetch (caller falls back to the key)
+    const r = await fetch(`https://api.github.com/repos/${repo}/issues/${number}`, {
+      headers: { authorization: `Bearer ${token}`, accept: "application/vnd.github+json" },
+    });
+    if (!r.ok) return null;
+    // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+    const j = (await r.json()) as { title?: string };
+    return j.title ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Coalesce best-effort title candidates to a non-blank identity for the title-led grids (issue
+ * #248). A candidate that is null/undefined OR blank/whitespace-only is treated as missing —
+ * external data (`fetchIssueTitle`/`fetchPrMeta`) can legitimately return `""`, which `??` would
+ * wrongly persist as a blank identity cell. Returns the first non-blank candidate, else the last
+ * one (the caller's key fallback, which is always non-blank). Mirrors the 036 backfill's
+ * `trim(title) = ''` test so write-time and backfill agree. */
+export function coalesceTitle(...candidates: (string | null | undefined)[]): string {
+  for (const c of candidates) {
+    if (c != null && c.trim() !== "") return c;
+  }
+  return candidates[candidates.length - 1] ?? "";
+}
+
 /** A PR's merge state, narrowed to what the merge poller needs to classify landability.
  * `mergeStateStatus` uses GitHub's vocabulary (CLEAN | BLOCKED | BEHIND | DIRTY | UNSTABLE |
  * DRAFT | HAS_HOOKS | UNKNOWN). `failingChecks` is `-1` when the transport can't enumerate

package/app/plan.test.ts

@@ -4,7 +4,7 @@
 // `NaN`/`0` (e.g. unset, "", "abc"), the cap check `round + 1 >= cap` would never fire and the
 // planner could revise forever. `positiveIntEnv` must fall back to the default on any value that
 // is not a positive integer, so the loop is always bounded.
-import { test } from "node:test";
+import { after, test } from "node:test";
 import { assertEquals, assertRejects, assertThrows } from "#test-assert";
 import { positiveIntEnv } from "./plan.ts";
 
@@ -59,6 +59,23 @@ test("valid positive integer → honoured", () => {
 // asserts the `plan_reviews` rows for the plan key are gone after a re-plan.
 import { startPlan } from "./plan.ts";
 
+// `startPlan` now fetches the epic issue title (issue #248) via the GitHub transport. Force the
+// token transport with no token so the fetch is a hermetic no-op (returns null) and the row `title`
+// deterministically coalesces to the `owner/repo#N` key — no `gh` subprocess, no network. A
+// dedicated test below stubs a successful fetch to cover the real-title path. Capture the prior
+// values and restore them after this file's tests so the module-scope mutation never leaks into
+// other test files under concurrent `node --test`.
+const PRIOR_TRANSPORT = process.env["NANO_PR_GITHUB_TRANSPORT"];
+const PRIOR_TOKEN = process.env["GITHUB_TOKEN"];
+process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+delete process.env["GITHUB_TOKEN"];
+after(() => {
+  if (PRIOR_TRANSPORT === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+  else process.env["NANO_PR_GITHUB_TRANSPORT"] = PRIOR_TRANSPORT;
+  if (PRIOR_TOKEN === undefined) delete process.env["GITHUB_TOKEN"];
+  else process.env["GITHUB_TOKEN"] = PRIOR_TOKEN;
+});
+
 function memTable(rows: any[], key: string) {
   return {
     get: (k: any) => Promise.resolve(rows.find((r) => r[key] === k) ?? null),
@@ -499,3 +516,75 @@ test("findActivePlansByBase returns only non-terminal plans on the matching repo
   assertEquals(active.length, 1);
   assertEquals(active[0].plan_key, "o/x#1");
 });
+
+// Issue #248: the human-readable identity for the epics grids. `startPlan` persists a non-blank
+// `plans.title` on BOTH the insert (new epic) and update (re-plan) paths — the fetched issue title
+// when available, else the `owner/repo#N` key — so the title-led grid never renders a blank cell.
+test("startPlan coalesces title to the key when the fetch yields nothing (insert path)", async () => {
+  const PLAN_KEY = "owner/repo#248";
+  const stores: Record<string, { rows: any[]; key: string }> = {
+    plans: { rows: [], key: "plan_key" },
+    plan_tasks: { rows: [], key: "id" },
+    plan_reviews: { rows: [], key: "plan_key" },
+    plan_task_deps: { rows: [], key: "plan_key" },
+  };
+  const engine = { createInstance: () => Promise.resolve({ processInstanceKey: "PI-T1" }) } as any;
+  await startPlan(memData(stores), engine, {
+    repo: "owner/repo",
+    number: 248,
+    url: "https://github.com/owner/repo/issues/248",
+    planKey: PLAN_KEY,
+  }, "main");
+  assertEquals((stores.plans.rows[0] as any).title, PLAN_KEY);
+});
+
+test("startPlan repopulates a non-blank title on re-plan (update path)", async () => {
+  const PLAN_KEY = "owner/repo#249";
+  const stores: Record<string, { rows: any[]; key: string }> = {
+    plans: { rows: [{ plan_key: PLAN_KEY, status: "done", task_count: 0, title: null }], key: "plan_key" },
+    plan_tasks: { rows: [], key: "id" },
+    plan_reviews: { rows: [], key: "plan_key" },
+    plan_task_deps: { rows: [], key: "plan_key" },
+  };
+  const engine = { createInstance: () => Promise.resolve({ processInstanceKey: "PI-T2" }) } as any;
+  await startPlan(memData(stores), engine, {
+    repo: "owner/repo",
+    number: 249,
+    url: "https://github.com/owner/repo/issues/249",
+    planKey: PLAN_KEY,
+  }, "main");
+  assertEquals((stores.plans.rows[0] as any).title, PLAN_KEY);
+});
+
+test("startPlan persists the real epic issue title when the fetch succeeds", async () => {
+  const prevTok = process.env["GITHUB_TOKEN"];
+  const prevFetch = globalThis.fetch;
+  process.env["GITHUB_TOKEN"] = "t0ken";
+  globalThis.fetch = ((url: string | URL | Request) => {
+    const u = String(url);
+    if (u.endsWith("/repos/owner/repo/issues/250")) {
+      return Promise.resolve(new Response(JSON.stringify({ title: "Ship the epic" }), { status: 200 }));
+    }
+    throw new Error(`unexpected fetch: ${u}`);
+  }) as typeof fetch;
+  try {
+    const stores: Record<string, { rows: any[]; key: string }> = {
+      plans: { rows: [], key: "plan_key" },
+      plan_tasks: { rows: [], key: "id" },
+      plan_reviews: { rows: [], key: "plan_key" },
+      plan_task_deps: { rows: [], key: "plan_key" },
+    };
+    const engine = { createInstance: () => Promise.resolve({ processInstanceKey: "PI-T3" }) } as any;
+    await startPlan(memData(stores), engine, {
+      repo: "owner/repo",
+      number: 250,
+      url: "https://github.com/owner/repo/issues/250",
+      planKey: "owner/repo#250",
+    }, "main");
+    assertEquals((stores.plans.rows[0] as any).title, "Ship the epic");
+  } finally {
+    globalThis.fetch = prevFetch;
+    if (prevTok === undefined) delete process.env["GITHUB_TOKEN"];
+    else process.env["GITHUB_TOKEN"] = prevTok;
+  }
+});

package/app/plan.ts

@@ -12,7 +12,7 @@
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { blackboardUrl, mintBlackboardToken, renderCoordinationBrief } from "./blackboard.ts";
 import { DEFAULT_ESCALATION_SLA_TIMEOUT, escalationSlaTimeout } from "./escalationSla.ts";
-import { ensureBaseBranch, fetchDefaultBranch } from "./github.ts";
+import { coalesceTitle, ensureBaseBranch, fetchDefaultBranch, fetchIssueTitle } from "./github.ts";
 import { clearExclusions } from "./mergeExclusion.ts";
 import { clearTaskDeltas } from "./taskDelta.ts";
 
@@ -400,6 +400,15 @@ export async function startPlan(
   }
   const base = normalizeBaseBranch(baseBranch);
   const ts = now();
+  // Human-readable identity for the epics grids (issue #248): fetch the epic issue's title,
+  // best-effort. Coalesce to the `owner/repo#N` key at write time so `plans.title` is ALWAYS
+  // non-blank — the grid's `{{title}}` template then needs no fallback, and a failed/absent/blank
+  // fetch still shows a usable identity (the key) rather than an empty cell. A fetch failure never
+  // blocks the start (`fetchIssueTitle` returns null on any error).
+  const title = coalesceTitle(
+    await fetchIssueTitle(parsed.repo, parsed.number, process.env.GITHUB_TOKEN ?? ""),
+    parsed.planKey,
+  );
   // Mint (or reuse, on a re-plan) this plan's blackboard capability token, and render the
   // coordination brief that carries its concrete URL. The token is the credential; agents reach
   // the blackboard directly with the URL we seed into `appendPrompt` below (#51).
@@ -425,6 +434,7 @@ export async function startPlan(
       status: "planning",
       task_count: 0,
       issue_url: parsed.url,
+      title,
       outcome: null,
       blackboard_token: token,
       base_branch: base,
@@ -436,6 +446,7 @@ export async function startPlan(
       repo: parsed.repo,
       issue_number: parsed.number,
       issue_url: parsed.url,
+      title,
       status: "planning",
       task_count: 0,
       blackboard_token: token,

package/app/service.ts

@@ -14,6 +14,7 @@ import { agentSlaTimeout } from "./agentSla.ts";
 import { deriveFeatureBlockedPatch, deriveFeatureDelivery, deriveFeatureEscalationPatch, FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, FEATURE_RUN_STATUSES, type FeatureRun, type FeatureRunStatus, featureRuns } from "./feature.ts";
 import {
   classifyMergeability,
+  coalesceTitle,
   ensureFreshHeadRun,
   fetchPrHead,
   fetchPrMeta,
@@ -460,7 +461,11 @@ export async function submitPr(
       status: "converging",
       current_round: 1,
       url: parsed.url,
-      title: title ?? existing.title,
+      // Coalesce to the key so `pull_requests.title` stays non-blank for the title-led grids
+      // (issue #248): a fresh fetch wins, else the prior title, else the `owner/repo#N` key.
+      // A blank/whitespace title counts as missing (matches the 036 backfill), so an empty
+      // external title never lands as an unlabeled row.
+      title: coalesceTitle(title, existing.title, parsed.prKey),
       waiting_since: null,
       last_review_id: null,
       last_nudge_at: null,
@@ -476,7 +481,9 @@ export async function submitPr(
       repo: parsed.repo,
       number: parsed.number,
       url: parsed.url,
-      title,
+      // Coalesce to the key so the title-led grids never render a blank identity (issue #248);
+      // a blank/whitespace external title counts as missing (matches the 036 backfill).
+      title: coalesceTitle(title, parsed.prKey),
       status: "converging",
       current_round: 1,
       abandon_token: abandonToken,

package/db/migrations/035_feature_runs_title.sql

@@ -0,0 +1,17 @@
+-- Surface the GitHub issue title as the primary, human-readable identity on the
+-- feature grids (issue #248, L0). Every dispatch row was keyed only by
+-- `owner/repo#N` — meaningful while you remember the number, opaque hours later.
+--
+-- `plans.title` (004_planning.sql) and `pull_requests.title` already existed;
+-- `feature_runs` had no title column at all. Add one so `startFeature` can persist
+-- the fetched issue title (best-effort), coalesced to the `owner/repo#N` key at
+-- write time so the column is ALWAYS non-blank — the grid's `{{title}}` template
+-- then needs no fallback and a failed/absent fetch still shows a usable identity.
+--
+-- Forward-only, additive (expand): nullable with no default, so pre-#248 rows
+-- grandfather in as NULL. Write-time coalescing keeps new rows non-blank; the
+-- follow-up 036_backfill_titles.sql then backfills these legacy NULL/blank titles
+-- to the row key, so the title-led grids never render a blank identity cell.
+-- Numbered after the current highest prefix on origin/main (034); the runner wraps
+-- each file in its own transaction, so this file must NOT contain BEGIN/COMMIT.
+ALTER TABLE feature_runs ADD COLUMN title TEXT;

package/db/migrations/036_backfill_titles.sql

@@ -0,0 +1,18 @@
+-- Backfill legacy NULL/blank titles so the title-led grids (issue #248) never
+-- render a blank identity cell for pre-#248 rows.
+--
+-- 035_feature_runs_title.sql added `feature_runs.title` nullable, and both
+-- `plans.title` (004_planning.sql) and `pull_requests.title` (001_init.sql) have
+-- long allowed NULL. The dispatch/overview grids now render `template: "{{title}}"`
+-- directly off these tables with NO key fallback, so any historical row whose title
+-- is NULL or blank shows as an unlabeled row. `startPlan`/`startFeature`/the PR
+-- upsert already coalesce title to the `owner/repo#N` key at write time; this
+-- migration applies the same coalesce once to the rows that predate that behaviour.
+--
+-- Forward-only, additive (data-only): sets title to the row's key where it is
+-- currently NULL or blank. Idempotent — re-running is a no-op once titles are set.
+-- Numbered after the current highest prefix on origin/main (035); the runner wraps
+-- each file in its own transaction, so this file must NOT contain BEGIN/COMMIT.
+UPDATE plans         SET title = plan_key    WHERE title IS NULL OR trim(title) = '';
+UPDATE feature_runs  SET title = feature_key WHERE title IS NULL OR trim(title) = '';
+UPDATE pull_requests SET title = pr_key      WHERE title IS NULL OR trim(title) = '';

package/openapi.yaml

@@ -668,6 +668,13 @@ components:
           description: >-
             Opt in to sharing a custom integration base branch with another already-active epic. See
             `PlanStartByIssue.allowSharedBase`.
+        customInstructions:
+          type: string
+          maxLength: 8000
+          description: >-
+            OPTIONAL free-text steering appended to the implementation agent's prompt for this run
+            (via the implement task's `appendPrompt`). Blank/whitespace is treated as absent. Persists
+            on the instance, so it also applies to the agent's answer-loop redispatch.
     FeatureStartByUrl:
       type: object
       additionalProperties: false
@@ -698,6 +705,12 @@ components:
         allowSharedBase:
           type: boolean
           description: Share a custom integration base with another active epic. See `PlanStartByIssue.allowSharedBase`.
+        customInstructions:
+          type: string
+          maxLength: 8000
+          description: >-
+            OPTIONAL free-text steering appended to the implementation agent's prompt for this run.
+            See `FeatureStartByIssue.customInstructions`.
     MessageResult:
       type: object
       description: The result of publishing a message / answering an escalation. Shape varies by message

package/operations/startFeature.ts

@@ -115,12 +115,18 @@ export default defineOperation("startFeature", async ({ body }, app) => {
   // Auto-merge is only meaningful as a follow-on to convergence; pin it off when converge is off so
   // the persisted row and the process variable can't disagree.
   const autoMerge = converge && "autoMerge" in body && body.autoMerge === true;
-  const result = await startFeature(app.data, app.engine, parsed, normalizedBase, converge, autoMerge);
+  // Optional operator steering threaded to the implementation agent's prompt. Empty/whitespace is
+  // normalized to null downstream (startFeature) so it never appends an empty instruction block.
+  const customInstructions = "customInstructions" in body && typeof body.customInstructions === "string"
+    ? body.customInstructions
+    : null;
+  const result = await startFeature(app.data, app.engine, parsed, normalizedBase, converge, autoMerge, customInstructions);
   app.log.info("feature run started", {
     featureKey: parsed.planKey,
     requestedBaseBranch: normalizedBase,
     converge,
     autoMerge,
+    hasCustomInstructions: typeof customInstructions === "string" && customInstructions.trim() !== "",
     alreadyRunning: "alreadyRunning" in result && result.alreadyRunning === true,
   });
   return { status: 202, body: result };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.73.1",
+  "version": "0.75.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/pages/epic-detail.page.json

@@ -55,7 +55,7 @@
           "filter": [{ "field": "plan_key", "eqParam": true }]
         },
         "columns": [
-          { "field": "plan_key", "header": "Issue", "linkField": "issue_url" },
+          { "field": "title", "template": "{{title}}", "header": "Item", "linkField": "issue_url" },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
           { "field": "delivery", "header": "Delivery" },
           { "field": "wave_label", "header": "Wave" },

package/pages/epic.page.json

@@ -73,7 +73,7 @@
           { "label": "All", "filter": [] }
         ],
         "columns": [
-          { "field": "plan_key", "header": "Epic", "link": { "kind": "page", "page": "epic-detail", "keyField": "plan_key" } },
+          { "field": "title", "template": "{{title}}", "header": "Item", "link": { "kind": "page", "page": "epic-detail", "keyField": "plan_key" } },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
           { "field": "delivery", "header": "Delivery" },
           { "field": "base_branch", "header": "Base branch" },

package/pages/feature.page.json

@@ -42,6 +42,7 @@
         "fields": [
           { "key": "issue", "label": "owner/repo#123 or a GitHub issue URL", "type": "text", "required": true, "requiredMessage": "An issue reference is required (owner/repo#123 or an issue URL)" },
           { "key": "baseBranch", "label": "Base branch: the branch the PR targets, e.g. main. A missing epic/* branch is auto-created off default HEAD; a non-epic/* branch must already exist.", "type": "text", "required": true, "requiredMessage": "Name the branch the PR targets (e.g. main or epic/agent-protocol)" },
+          { "key": "customInstructions", "label": "Custom instructions (optional) \u2014 extra steering appended to the implementation agent's prompt, e.g. \u201cprefer Deno; keep the diff small; add integration tests\u201d", "type": "text" },
           { "key": "converge", "label": "Converge \u2014 hand the raised PR to the review-convergence loop", "type": "checkbox" },
           { "key": "autoMerge", "label": "Auto-merge \u2014 after convergence, drive the merge-loop (only applies when Converge is on)", "type": "checkbox" },
           { "key": "confirmDefaultBase", "label": "Confirm landing on the default branch \u2014 required only when the base above IS the repository default", "type": "checkbox" },
@@ -69,7 +70,7 @@
           { "label": "All", "filter": [] }
         ],
         "columns": [
-          { "field": "feature_key", "header": "Feature", "linkField": "issue_url" },
+          { "field": "title", "template": "{{title}}", "header": "Item", "linkField": "issue_url" },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
           { "field": "escalation_question", "header": "Escalation" },
           { "field": "base_branch", "header": "Base branch" },

package/pages/home.page.json

@@ -163,8 +163,9 @@
         ],
         "columns": [
           {
-            "field": "pr_key",
-            "header": "PR",
+            "field": "title",
+            "template": "{{title}}",
+            "header": "Item",
             "linkField": "url"
           },
           {

package/pages/overview.page.json

@@ -63,15 +63,9 @@
           ]
         },
         "columns": [
-          { "field": "pr_key", "header": "PR", "link": { "kind": "page", "page": "home", "keyField": "pr_key" } },
+          { "field": "title", "template": "{{title}}", "header": "Item", "link": { "kind": "page", "page": "home", "keyField": "pr_key" } },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
-          {
-            "field": "incident_message",
-            "header": "Incident",
-            "badge": { "tone": "danger", "label": "1" }
-          },
-          { "field": "current_round", "header": "Round" },
-          { "field": "active_worker", "header": "Agent" },
+          { "field": "current_round", "template": "{{current_round}} · {{active_worker}}", "header": "Round · Agent" },
           { "field": "updated_at", "header": "Updated" }
         ]
       }
@@ -94,13 +88,9 @@
           "filter": [{ "field": "status", "in": ["planning", "dispatched"] }]
         },
         "columns": [
-          { "field": "plan_key", "header": "Epic", "link": { "kind": "page", "page": "epic-detail", "keyField": "plan_key" } },
+          { "field": "title", "template": "{{title}}", "header": "Item", "link": { "kind": "page", "page": "epic-detail", "keyField": "plan_key" } },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
-          { "field": "delivery", "header": "Delivery" },
-          { "field": "base_branch", "header": "Base branch" },
           { "field": "wave_label", "header": "Wave" },
-          { "field": "task_count", "header": "Tasks" },
-          { "field": "issue_number", "header": "Issue", "linkField": "issue_url" },
           { "field": "updated_at", "header": "Updated" }
         ]
       }
@@ -123,14 +113,9 @@
           "filter": [{ "field": "status", "in": ["running", "escalated", "awaiting_operator"] }]
         },
         "columns": [
-          { "field": "feature_key", "header": "Feature", "link": { "kind": "page", "page": "feature", "keyField": "feature_key" } },
+          { "field": "title", "template": "{{title}}", "header": "Item", "link": { "kind": "page", "page": "feature", "keyField": "feature_key" } },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
-          { "field": "escalation_question", "header": "Escalation" },
-          { "field": "base_branch", "header": "Base branch" },
-          { "field": "pr_key", "header": "PR", "link": { "kind": "page", "page": "home", "keyField": "pr_key" } },
-          { "field": "converge", "header": "Converge" },
-          { "field": "auto_merge", "header": "Auto-merge" },
-          { "field": "outcome", "header": "Outcome" },
+          { "field": "delivery_label", "header": "Delivery" },
           { "field": "updated_at", "header": "Updated" }
         ],
         "rowActions": [

package/resources/processes/feature.bpmn

@@ -44,7 +44,7 @@
           <zeebe:linkedResource resourceId="feature.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
         </zeebe:linkedResources>
         <zeebe:ioMapping>
-          <zeebe:input source="=&#34;&#10;&#10;---&#10;&#10;&#34; + task.prompt + (if (baseBranchBrief = null) then &#34;&#34; else baseBranchBrief)" target="appendPrompt" />
+          <zeebe:input source="=&#34;&#10;&#10;---&#10;&#10;&#34; + task.prompt + (if (baseBranchBrief = null) then &#34;&#34; else baseBranchBrief) + (if (customInstructions = null) then &#34;&#34; else &#34;&#10;&#10;---&#10;&#10;## Operator custom instructions&#10;&#10;The operator supplied these instructions for this run — follow them:&#10;&#10;&#34; + customInstructions)" target="appendPrompt" />
           <zeebe:output source="=status" target="status" />
           <zeebe:output source="=question" target="question" />
         </zeebe:ioMapping>