@nanobpm/nano-workforce 0.203.0 → 0.204.0

package/e2e/feature-run.e2e.ts

@@ -163,6 +163,49 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
 
         const prs = await app.db.table<PrRow>("pull_requests", "pr_key").find({});
         assert.equal(prs.length, 0, "raise-only did NOT enroll the PR into the convergence loop");
+
+        // Issue #907: the HOST posted exactly one idempotent "PR opened" comment on the claimed
+        // issue, and recorded the link on the run row so a repeated pass never double-posts.
+        // (Snapshot the issue's comments: the github state is shared across this file's tests.)
+        const comments = (githubState.issueComments.get(7) ?? []).filter((c) => c.body.includes("nwf:pr-linked:#101"));
+        assert.equal(comments.length, 1, "exactly one comment was posted on the claimed issue for PR #101");
+        assert.ok(comments[0].body.includes("Pull request opened: #101"), "the comment names the PR");
+        assert.ok(
+          comments[0].body.includes("<!-- nwf:pr-linked:#101 https://github.com/owner/repo/pull/101 -->"),
+          "the comment carries the URL-keyed dedupe marker",
+        );
+        assert.equal(
+          (run as unknown as { pr_linked_pr_key: string | null }).pr_linked_pr_key,
+          "owner/repo#101",
+          "the durable link record was written",
+        );
+      },
+    );
+  });
+
+  test("idempotence: re-running record-feature for the SAME delivered PR posts nothing more (issue #907)", async () => {
+    // A retried at-least-once `record-feature` job (or a second reconcile pass) must never
+    // double-post the "PR opened" comment: the durable `pr_linked_pr_key` claim short-circuits the
+    // repeat before any GitHub write.
+    await withApp(
+      { "senior:feature": () => ({ status: "opened", pr: "owner/repo#101", summary: "built it" }) },
+      { baseBranch: "epic/e2e" },
+      async ({ app, featureKey }) => {
+        const before = (githubState.issueComments.get(7) ?? []).length;
+        assert.equal(before >= 0, true);
+        // Drive the REAL record-feature handler a second time with the same delivered PR (the
+        // at-least-once repeat / second reconcile pass), against the SAME live app DB.
+        const { default: recordFeature } = await import("../workers/record-feature/worker.ts");
+        const log = { info: () => {}, warn: () => {}, error: () => {} };
+        await recordFeature(
+          { jobKey: "repeat-1", variables: { featureKey, status: "opened", pr: "owner/repo#101", claimIssue: true } } as never,
+          { data: app.db, log } as never,
+        );
+        assert.equal(
+          (githubState.issueComments.get(7) ?? []).length,
+          before,
+          "a repeated record pass posted NO second comment",
+        );
       },
     );
   });
@@ -272,7 +315,7 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
           calls += 1;
           return calls === 1
             ? { status: "escalated", question: "Which API should I use?", summary: "parked for a human" }
-            : { status: "opened", pr: "owner/repo#103", summary: "resumed and opened" };
+            : { status: "opened", pr: "owner/repo#104", summary: "resumed and opened" };
         },
       },
       { baseBranch: "epic/e2e" },
@@ -298,6 +341,13 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
         );
         assert.ok(!flows.includes("ic_gw_answer->ic_end"), "the abandon (default) flow was NOT taken");
         assert.equal(calls, 2, "the implementation agent was re-dispatched exactly once after the answer");
+
+        // Issue #907: the RETRY opened the PR — the host still posted exactly one "PR opened"
+        // comment on the claimed issue (the first, escalated pass delivered no PR, so nothing was
+        // posted before the answer). Uses a PR number (#104) no earlier scenario links, so a pre-existing marker in the shared github state cannot satisfy this.
+        const comments = (githubState.issueComments.get(7) ?? []).filter((c) => c.body.includes("nwf:pr-linked:#104"));
+        assert.equal(comments.length, 1, "exactly one comment was posted across the escalate+resume");
+        assert.ok(comments[0].body.includes("Pull request opened: #104"), "the comment names the retry-opened PR");
       },
     );
   });
@@ -388,6 +438,13 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
             !tasks.some((t) => t.elementId === "escalation"),
             "no human-escalation task was created for the adopted run",
           );
+
+          // Issue #907: the ADOPTED PR was announced on the claimed issue exactly once — the
+          // reconcile path delivers the PR without the agent reporting it, and the host-side link
+          // covers it all the same. (Filtered to THIS PR's marker — the github state is shared.)
+          const comments = (githubState.issueComments.get(7) ?? []).filter((c) => c.body.includes("nwf:pr-linked:#801"));
+          assert.equal(comments.length, 1, "exactly one comment was posted for the adopted PR");
+          assert.ok(comments[0].body.includes("Pull request opened: #801"), "the comment names the adopted PR");
         },
       );
     } finally {

package/e2e/plan-fanout.e2e.ts

@@ -57,6 +57,8 @@ type Stub = (job: EngineJob) => Record<string, unknown> | void;
 describe("plan-fanout escalations (U2 — task + plan-review + trial-merge → userTask + form)", () => {
   const savedEnv = new Map<string, string | undefined>();
   let restoreGithub: (() => void) | undefined;
+  // The shared hermetic GitHub state (issue #907 asserts NO epic-slice comment lands on the parent).
+  const githubState = admitGithubState("owner/repo", "main");
 
   before(() => {
     for (const [k, v] of Object.entries(GITHUB_ENV_OVERRIDES)) {
@@ -65,7 +67,7 @@ describe("plan-fanout escalations (U2 — task + plan-review + trial-merge → u
     }
     // ADR 0003: `startPlanFanout` + the `pr.ensure-base-branch` head task now pass through base
     // admission, which reads/creates the base ref. Pin the hermetic `token` transport + fetch stub.
-    restoreGithub = installAdmitGithub(admitGithubState("owner/repo", "main"));
+    restoreGithub = installAdmitGithub(githubState);
   });
 
   after(() => {
@@ -452,6 +454,27 @@ describe("plan-fanout escalations (U2 — task + plan-review + trial-merge → u
     );
   });
 
+  test("an epic slice that opens a PR posts NO comment on the parent epic (issue #907)", async () => {
+    // The "PR opened" issue link is gated on `claimIssue`, which only a single-issue feature run
+    // seeds (app/feature.ts). An epic slice's `issue` is the SHARED parent epic, which must never be
+    // claimed or commented per-slice — so a slice that opens its PR leaves the epic's thread empty.
+    const before = (githubState.issueComments.get(1) ?? []).length;
+    await withApp(
+      {
+        "senior:plan": singleTaskPlan,
+        "senior:plan-review": approveReview,
+        "senior:feature": () => ({ status: "opened", pr: "owner/repo#101", summary: "opened the slice" }),
+      },
+      async () => {
+        assert.equal(
+          (githubState.issueComments.get(1) ?? []).length,
+          before,
+          "the parent epic gained NO comment from the slice's delivered PR",
+        );
+      },
+    );
+  });
+
   // Capability edge (issue #289): a task that declares cross-repo `needs` must PARK at the
   // `wait-caps-resolved` barrier (never take the no-needs shortcut), and publishing `caps-resolved`
   // correlated on the per-task barrier key `<planKey>:<taskId>` must release it into `implement-task`

package/e2e/support/github-admit.ts

@@ -20,6 +20,9 @@ export interface AdmitGithubState {
    *  head via `listPrsForHead`. Empty by default → the pulls listing returns `[]` (no adoptable PR),
    *  so suites that don't opt in keep exactly today's escalate behaviour. */
   openPrs: Map<string, { number: number; base?: string }>;
+  /** Issue comments keyed by issue number (issue #907): the record-feature "PR opened" link lists
+   *  existing comments (marker dedupe) and POSTs new ones here. Seeded empty. */
+  issueComments: Map<number, { body: string }[]>;
 }
 
 /** Build a fresh admit-github state with the default branch pre-seeded with a HEAD sha so an
@@ -35,6 +38,7 @@ export function admitGithubState(
     creates: [],
     resets: [],
     openPrs: new Map(),
+    issueComments: new Map(),
   };
 }
 
@@ -95,6 +99,35 @@ function admitFetch(state: AdmitGithubState) {
         ]),
       );
     }
+    // GET /repos/{repo}/pulls/{n} → a PR's meta (fetchPrMeta — the "PR opened" link's best-effort
+    // title read, issue #907). Served from the openPrs entry when one names this number.
+    const pullMatch = path.match(/^\/repos\/([^/]+\/[^/]+)\/pulls\/(\d+)$/);
+    if (method === "GET" && pullMatch) {
+      const number = Number(pullMatch[2]);
+      for (const [branch, hit] of state.openPrs) {
+        if (hit.number === number) {
+          return Promise.resolve(
+            json({ title: `PR #${number}`, body: "", head: { ref: branch }, base: { ref: hit.base ?? state.defaultBranch } }),
+          );
+        }
+      }
+      return Promise.resolve(json({ title: `PR #${number}`, body: "", head: { ref: null }, base: { ref: state.defaultBranch } }));
+    }
+    // GET /repos/{repo}/issues/{n}/comments → the issue's comments (the "PR opened" marker dedupe
+    // scan, issue #907). POST appends a comment.
+    const commentsMatch = path.match(/^\/repos\/([^/]+\/[^/]+)\/issues\/(\d+)\/comments$/);
+    if (commentsMatch) {
+      const issueNumber = Number(commentsMatch[2]);
+      if (method === "GET") return Promise.resolve(json(state.issueComments.get(issueNumber) ?? []));
+      if (method === "POST") {
+        // biome-ignore lint/plugin: runtime contract boundary for parsed JSON
+        const body = JSON.parse(String(init?.body ?? "{}")) as { body?: string };
+        const list = state.issueComments.get(issueNumber) ?? [];
+        list.push({ body: String(body.body ?? "") });
+        state.issueComments.set(issueNumber, list);
+        return Promise.resolve(json({ id: list.length }, 201));
+      }
+    }
     // Any other endpoint is a best-effort read the sealed transport used to skip → 404 (null).
     return Promise.resolve(new Response("Not Found", { status: 404 }));
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.203.0",
+  "version": "0.204.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/resources/processes/feature.bpmn

@@ -8,6 +8,7 @@
           <nano:extend name="status" type="string" optional="true" />
           <nano:extend name="pr" type="string" optional="true" />
           <nano:extend name="summary" type="string" optional="true" />
+          <nano:extend name="claimIssue" type="boolean" optional="true" />
         </nano:shape>
         <nano:shape id="RecordFeatureImplementingIn" name="Record feature implementing — input">
           <nano:extend name="featureKey" type="string" optional="true" />

package/resources/processes/implement-cell.bpmn

@@ -29,6 +29,7 @@
         <zeebe:ioMapping>
           <zeebe:input source="=&#34;&#10;&#10;---&#10;&#10;&#34; + task.prompt + (if (is defined(baseBranchBrief) and baseBranchBrief != null) then baseBranchBrief else &#34;&#34;) + (if (is defined(blackboardBrief) and blackboardBrief != null) then blackboardBrief else &#34;&#34;) + (if (is defined(resolvedDepsBrief) and resolvedDepsBrief != null) then resolvedDepsBrief else &#34;&#34;) + (if (is defined(resolvedArtifacts) = false or resolvedArtifacts = null or count(resolvedArtifacts[item != null]) = 0) then &#34;&#34; else (&#34;&#10;&#10;---&#10;&#10;**Bound upstream readiness.** Build/install/clone against EXACTLY these resolved published versions (the ones first carrying the awaited capability), and bump the consumer dependency to them — never merely the newest:&#10;&#10;&#34; + string join(resolvedArtifacts[item != null], &#34;&#10;&#34;))) + (if (is defined(customInstructions) = false or 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) + (if (is defined(retryNudge) and retryNudge != null) then retryNudge else &#34;&#34;)" target="appendPrompt" />
           <zeebe:input source="=if (is defined(transcriptUrlBase)) then transcriptUrlBase else null" target="transcriptUrlBase" />
+          <zeebe:input source="=if (is defined(claimIssue)) then claimIssue else null" target="claimIssue" />
           <zeebe:output source="=status" target="status" />
           <zeebe:output source="=question" target="question" />
           <zeebe:output source="=if (is defined(summary)) then summary else null" target="summary" />

package/skills/nano-workforce/SKILL.md

@@ -11,27 +11,15 @@ implements → converges** them across a fleet of coding agents, and runs
 **agent-authored delivery graphs** (heterogeneous cross-repo, human-in-the-loop
 DAGs — ADR 0005).
 
-**This skill is a thin bootstrap by design.** It does not describe the endpoints.
-Every running nwf instance is self-describing — over **MCP** where your client
-supports it, and over its **live operator guide** everywhere else. Your job is to
-reach that live surface and follow it, never to work from a cached copy that drifts
-across versions and instances.
-
-There are two paths. **Prefer MCP (§A).** If your client has no MCP support, use the
-fetch-the-live-guide fallback (§B). Both talk to the same app; MCP is a projection of
-the same OpenAPI contract, not a different system (ADR 0067).
+**This skill is a thin bootstrap.** Every running instance describes itself, over **MCP**
+(§A, preferred) or through its **live operator guide** (§B). Reach that live surface and
+follow it rather than a cached copy that drifts between versions.
 
 ## A. Preferred — drive over MCP
 
-The Urban runtime serves a Streamable-HTTP MCP endpoint at **`/app/mcp`** for every
-instance, with **zero app-side MCP code**: the app's operations are projected into
-tools from its OpenAPI spec, alongside a framework-owned engine-debug tool family
-(process instances, wait states, variables, incidents) and the app's projection
-reads. The operator **guide** (the same guide as §B) is itself one of those projected
-tools — `GET /app/api/agent` becomes the `getAgentInstructions` read tool — so the
-workflow knowledge (orient first, preview before dispatch, escalations are for humans)
-is discoverable over the same channel as the drive tools; the runtime additionally
-serves its derived **system brief** as an MCP resource plus an orientation prompt.
+Every instance serves a Streamable-HTTP MCP endpoint at **`/app/mcp`**. Its tools are the
+app's operations (projected from its OpenAPI spec) plus framework engine-debug tools. The
+operator guide itself is the `getAgentInstructions` tool.
 
 **Register one MCP server entry per instance.** Naming the instance
 (`"drive workforce-merlin"`) makes the wrong-instance mistake structurally
@@ -64,14 +52,9 @@ Then: start a session, confirm the `workforce-*` tools appear, and ask the agent
 use a **named** instance (`"Using workforce-local, show what's in flight and any open
 escalations"`). It should call the status operation tool, not curl.
 
-**Guard posture.** When `NANO_PR_WEBHOOK_SECRET` is **unset**, both reads (status,
-instances, incidents, projections, the operator guide) and mutations (submit work,
-answer escalations, cancel/retry/resolve) work from loopback with no credential. When it
-**is set**, that secret is required as an `x-hook-secret` header on **both reads and
-mutations** — read endpoints like `getAgentInstructions`/`getVersion` also return `401`
-without it — put it in the server entry's `headers`, never in chat. **Operator-only doors stay operator-only:** the delivery-graph
-dispatch/dismiss lifecycle (the human clicking Dispatch *is* the approval, ADR 0005)
-is `x-mcp`-excluded and is **not** a tool — dispatch stays a human action in the
+**Guard posture.** If `NANO_PR_WEBHOOK_SECRET` is set, every read and mutation needs it as an
+`x-hook-secret` header (otherwise `401`). Put it in the server entry's `headers`, never in
+chat. Delivery-graph dispatch is deliberately **not** a tool: it stays a human action in the
 cockpit.
 
 The full server-entry recipes (multiple instances, Basic-Auth-fronted instances,
@@ -129,45 +112,17 @@ curl -sS ${NANO_PR_WEBHOOK_SECRET:+-H "x-hook-secret: $NANO_PR_WEBHOOK_SECRET"}
 `GET /app/api/agent` (`getAgentInstructions`) returns
 `{ format, appVersion, generatedAt, baseUrl, engineBase, instructions }` — the
 authoritative, version-matched operator guide, every example keyed to this
-instance. Read it in full and follow it for orientation, submitting work, answering
-escalations, and debugging. **Re-fetch it at the start of every session.** (This is
-the same prose the `getAgentInstructions` MCP tool serves in §A.)
-
-### B.3 Orient before acting
-
-```bash
-curl -sS "$BASE/version" | jq   # app/urban version, git sha, uptime
-curl -sS "$BASE/status"  | jq   # every PR/instance in flight + open escalations
-```
-
-`/status` is the primary situational-awareness endpoint — check it before you submit
-or unstick anything.
-
-### B.4 What you can drive (all detailed in the live guide)
-
-- **Submit a PR** for review convergence — `POST $BASE/actions/start/convergence-loop`.
-- **Submit an issue/epic** for plan → implement → converge — `POST $BASE/actions/start/plan-fanout`.
-- **Submit a delivery graph** (ADR 0005) — propose → preview → approve → **dispatch**.
-  Compile/preview is a pure, side-effect-free path; **dispatch is an operator action
-  in the cockpit**, not an agent door.
-- **Answer an escalation** — `POST $BASE/actions/complete-user-task`, or the agent
-  hook `POST $BASE/hooks/agent-complete` (`agentCompleteEscalation`).
-- **Debug** — relate an in-flight PR to its engine process instance via `processKey`
-  from `/status`, then inspect and unstick it against the engine REST base
-  (`engineBase` from the guide).
+instance. Read it and follow it: orientation, submitting work, answering escalations,
+debugging. **Re-fetch it every session.** For one section, use
+`GET $BASE/agent/guide?section=<id>` (no `section` = table of contents).
 
 ## Principles
 
-- **Discover, don't declare.** Prefer the live surface (MCP tools including the
-  operator-guide tool, or the live guide and `/status`) over any assumption baked into
-  this file. If this skill and the live surface disagree, the live surface wins.
-- **Confirm the target instance.** Never run a side-effecting call against an assumed
-  base URL. With MCP, name the server entry; with the fallback, know — and when
-  ambiguous, ask — which instance you're driving.
-- **Preview before dispatch.** For delivery graphs and any bulk action, use the pure
-  preview/validate path first and show the user the plan before the side-effecting
-  start. Dispatch itself is the operator's call.
-- **Idempotency.** Submissions carry dedupe keys; re-submitting the same work must not
-  double-dispatch. Honour the keys the guide documents.
-- **Escalations are for humans.** When the workforce parks on a human node, surface it
-  with options; don't silently auto-answer design/product decisions.
+- **The live surface wins.** If this skill and the instance disagree, follow the instance.
+- **Confirm the target instance** before any side-effecting call (name the MCP server entry,
+  or ask when the base URL is ambiguous).
+- **Preview before dispatch.** Show the user the plan before any bulk or side-effecting start.
+  Dispatching a delivery graph is the operator's call.
+- **Submissions are idempotent.** Re-submitting the same work must not double-dispatch.
+- **Escalations are for humans.** Surface them with options; don't silently answer design or
+  product decisions.

package/workers/record-feature/worker.test.ts

@@ -0,0 +1,256 @@
+// Unit coverage for pr.record-feature's "PR opened" issue link (issue #907).
+//
+// record-feature is the ONE point every PR-delivering path of a single-issue feature run passes
+// through — the agent's own `opened`, a retry's `opened`, and the reconcile step's ADOPTED `opened`
+// all land here — so it is the canonical host-side writer of the idempotent
+// `🤖 Pull request opened: #n` comment on the claimed issue. The decision itself lives in
+// app/issuePrLink.ts (exhaustively covered in app/issuePrLink.test.ts); these tests pin the
+// WIRING: the worker records the owed link + attempts it only for a claimed (single-issue) run
+// that delivered a keyed PR, the comment targets the CLAIMED issue (the run row's repo +
+// issue_number, not the PR's repository), and a failed comment never fails the job.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { noopLog } from "../../test/log.ts";
+import handler from "./worker.ts";
+
+// biome-ignore lint/suspicious/noExplicitAny: tiny in-memory app double, mirrors record-feature-implementing.worker.test
+function fakeApp(rows: Record<string, unknown>[]): { app: any; linkWrites: string[] } {
+  const stores: Record<string, Record<string, unknown>[]> = { feature_runs: rows };
+  const linkWrites: string[] = [];
+  return {
+    app: {
+      stores,
+      data: {
+        table(name: string, key: string) {
+          const store = (stores[name] ??= []);
+          return {
+            // biome-ignore lint/suspicious/noExplicitAny: test double
+            get: (k: any) => Promise.resolve(store.find((r) => r[key] === k)),
+            // biome-ignore lint/suspicious/noExplicitAny: test double
+            update: (k: any, patch: any) => {
+              const row = store.find((r) => r[key] === k);
+              if (row) Object.assign(row, patch);
+              return Promise.resolve(row);
+            },
+          };
+        },
+        open() {
+          return {
+            exec(sql: string, params: unknown[]) {
+              linkWrites.push(sql);
+              // Mirror the issue-link state machine's SQL on the in-memory row so the link record
+              // is observable: the owed write, the lease CAS, and the confirm.
+              const row = stores.feature_runs[0];
+              if (!row) return { changed: 0 };
+              if (/SET "pr_link_want_pr_key" = \?/.test(sql)) {
+                row.pr_link_want_pr_key = String(params[0]);
+                return { changed: 1 };
+              }
+              if (/SET "pr_link_lease_at" = \?/.test(sql)) {
+                row.pr_link_lease_at = String(params[0]);
+                return { changed: 1 };
+              }
+              if (/SET "pr_linked_pr_key" = \?, "pr_link_lease_at" = NULL/.test(sql)) {
+                row.pr_linked_pr_key = String(params[0]);
+                row.pr_link_lease_at = null;
+                return { changed: 1 };
+              }
+              return { changed: 0 };
+            },
+          };
+        },
+      },
+      log: noopLog(),
+    },
+    linkWrites,
+  };
+}
+
+/** Hermetic GitHub stub (token transport + fetch double) capturing posted comment bodies and the
+ *  path of every call (so a test can pin WHICH repo/issue a comment or title read targeted). */
+function stubGithubComments(existing: { body: string }[] = [], opts: { failPost?: boolean } = {}) {
+  const prevTransport = process.env.NANO_PR_GITHUB_TRANSPORT;
+  const prevToken = process.env.GITHUB_TOKEN;
+  const prevFetch = globalThis.fetch;
+  process.env.NANO_PR_GITHUB_TRANSPORT = "token";
+  process.env.GITHUB_TOKEN = "t";
+  const posted: string[] = [];
+  const calls: string[] = [];
+  globalThis.fetch = (async (url: string | URL | Request, init?: RequestInit) => {
+    const method = (init?.method ?? "GET").toUpperCase();
+    const u = new URL(String(url));
+    calls.push(`${method} ${u.pathname}`);
+    if (method === "GET" && /\/issues\/\d+\/comments$/.test(u.pathname)) {
+      return new Response(JSON.stringify(existing), { status: 200 });
+    }
+    if (method === "GET" && /\/issues\/\d+$/.test(u.pathname)) {
+      return new Response(JSON.stringify({ title: "the issue" }), { status: 200 });
+    }
+    if (method === "GET" && /\/pulls\/\d+$/.test(u.pathname)) {
+      return new Response(JSON.stringify({ title: "the PR" }), { status: 200 });
+    }
+    if (method === "POST" && /\/issues\/\d+\/comments$/.test(u.pathname)) {
+      if (opts.failPost) return new Response("boom", { status: 500 });
+      // biome-ignore lint/plugin: runtime contract boundary for parsed JSON in a test double
+      posted.push(String((JSON.parse(String(init?.body ?? "{}")) as { body?: string }).body ?? ""));
+      return new Response(JSON.stringify({ id: 1 }), { status: 201 });
+    }
+    return new Response("Not Found", { status: 404 });
+  }) as typeof fetch;
+  return {
+    posted,
+    calls,
+    restore: () => {
+      globalThis.fetch = prevFetch;
+      if (prevTransport === undefined) delete process.env.NANO_PR_GITHUB_TRANSPORT;
+      else process.env.NANO_PR_GITHUB_TRANSPORT = prevTransport;
+      if (prevToken === undefined) delete process.env.GITHUB_TOKEN;
+      else process.env.GITHUB_TOKEN = prevToken;
+    },
+  };
+}
+
+const ROW = { feature_key: "owner/repo#7", repo: "owner/repo", issue_number: 7, status: "running" };
+
+test("an opened run on a claimed issue posts the PR-opened comment and records the link", async () => {
+  const gh = stubGithubComments();
+  const rows = [{ ...ROW }];
+  const { app } = fakeApp(rows);
+  try {
+    const out = await handler(
+      { jobKey: "j1", variables: { featureKey: "owner/repo#7", status: "opened", pr: "owner/repo#101", claimIssue: true } } as never,
+      app,
+    );
+    assertEquals(out.featureStatus, "opened");
+    assertEquals(out.prKey, "owner/repo#101");
+    assertEquals(gh.posted.length, 1, "the claimed issue got the PR-opened comment");
+    assert(gh.posted[0].includes("Pull request opened: #101"), "the comment names the PR");
+    assert(
+      gh.posted[0].includes("<!-- nwf:pr-linked:#101 https://github.com/owner/repo/pull/101 -->"),
+      "the comment carries the URL-keyed dedupe marker",
+    );
+    assertEquals(rows[0].pr_link_want_pr_key, "owner/repo#101", "the owed link was recorded");
+    assertEquals(rows[0].pr_linked_pr_key, "owner/repo#101", "the durable link was confirmed");
+  } finally {
+    gh.restore();
+  }
+});
+
+test("an ADOPTED opened (reconcile path) posts the comment too — the worker cannot tell the difference", async () => {
+  const gh = stubGithubComments();
+  const rows = [{ ...ROW }];
+  const { app } = fakeApp(rows);
+  try {
+    // The reconcile step re-emitted status=opened + pr for a PR the harness never reported; the
+    // record worker treats it exactly like an agent-reported opened.
+    await handler(
+      { jobKey: "j2", variables: { featureKey: "owner/repo#7", status: "opened", pr: "owner/repo#801", claimIssue: true } } as never,
+      app,
+    );
+    assertEquals(gh.posted.length, 1, "the adopted PR was announced on the issue");
+    assert(gh.posted[0].includes("#801"), "the comment names the adopted PR");
+  } finally {
+    gh.restore();
+  }
+});
+
+test("a CROSS-REPO PR comments on the CLAIMED issue (the run row's repo + issue_number), not the PR's repo", async () => {
+  // Regression for the review finding: the old worker derived the comment target from the PR's
+  // repository + the issue NUMBER, so a run for owner/issues#7 delivering owner/code#101 commented
+  // on owner/code#7 (or 404'd). The target must come from the run row; the PR repo is used only
+  // for the title lookup.
+  const gh = stubGithubComments();
+  const rows = [{ feature_key: "owner/issues#7", repo: "owner/issues", issue_number: 7, status: "running" }];
+  const { app } = fakeApp(rows);
+  try {
+    const out = await handler(
+      { jobKey: "j2x", variables: { featureKey: "owner/issues#7", status: "opened", pr: "owner/code#101", claimIssue: true } } as never,
+      app,
+    );
+    assertEquals(out.prKey, "owner/code#101");
+    assertEquals(gh.posted.length, 1, "the claimed issue got the PR-opened comment");
+    assert(
+      gh.calls.some((c) => c === "POST /repos/owner/issues/issues/7/comments"),
+      `the comment landed on the claimed issue owner/issues#7 (calls: ${gh.calls.join(", ")})`,
+    );
+    assert(
+      gh.calls.some((c) => c === "GET /repos/owner/code/pulls/101"),
+      "the PR title was read from the PR's OWN repository",
+    );
+    assert(
+      !gh.calls.some((c) => c.includes("/repos/owner/code/issues/")),
+      "the PR repository's issues were never targeted",
+    );
+    assert(gh.posted[0].includes("https://github.com/owner/code/pull/101"), "the comment links the cross-repo PR");
+  } finally {
+    gh.restore();
+  }
+});
+
+test("a repeated record pass for the SAME PR posts nothing more (idempotent)", async () => {
+  const gh = stubGithubComments();
+  const rows = [{ ...ROW, pr_link_want_pr_key: "owner/repo#101", pr_linked_pr_key: "owner/repo#101" }];
+  const { app, linkWrites } = fakeApp(rows);
+  try {
+    await handler(
+      { jobKey: "j3", variables: { featureKey: "owner/repo#7", status: "opened", pr: "owner/repo#101", claimIssue: true } } as never,
+      app,
+    );
+    assertEquals(gh.posted.length, 0, "no duplicate comment");
+    assert(
+      !linkWrites.some((sql) => /SET "pr_link_lease_at"/.test(sql)),
+      "the confirmed link short-circuited before the lease CAS (and before any GitHub read)",
+    );
+  } finally {
+    gh.restore();
+  }
+});
+
+test("an epic slice (claimIssue unset) posts NOTHING on its parent epic", async () => {
+  const gh = stubGithubComments();
+  const rows = [{ ...ROW }];
+  const { app, linkWrites } = fakeApp(rows);
+  try {
+    await handler(
+      { jobKey: "j4", variables: { featureKey: "owner/repo#7", status: "opened", pr: "owner/repo#101" } } as never,
+      app,
+    );
+    assertEquals(gh.posted.length, 0, "no comment was posted");
+    assertEquals(linkWrites.length, 0, "no link state was written");
+  } finally {
+    gh.restore();
+  }
+});
+
+test("a blocked run posts nothing", async () => {
+  const gh = stubGithubComments();
+  const rows = [{ ...ROW }];
+  const { app } = fakeApp(rows);
+  try {
+    const out = await handler(
+      { jobKey: "j5", variables: { featureKey: "owner/repo#7", status: "blocked", claimIssue: true } } as never,
+      app,
+    );
+    assertEquals(out.featureStatus, "blocked");
+    assertEquals(gh.posted.length, 0);
+  } finally {
+    gh.restore();
+  }
+});
+
+test("a failed comment POST never fails the job — the run still records opened", async () => {
+  const gh = stubGithubComments([], { failPost: true });
+  const rows = [{ ...ROW }];
+  const { app } = fakeApp(rows);
+  try {
+    const out = await handler(
+      { jobKey: "j6", variables: { featureKey: "owner/repo#7", status: "opened", pr: "owner/repo#101", claimIssue: true } } as never,
+      app,
+    );
+    assertEquals(out.featureStatus, "opened", "the job completed normally");
+    assertEquals(rows[0].status, "opened", "the run row was still recorded");
+    assertEquals(rows[0].pr_key, "owner/repo#101");
+  } finally {
+    gh.restore();
+  }
+});

package/workers/record-feature/worker.ts

@@ -11,8 +11,18 @@
 //
 // Enrollment itself lives in the separate `pr.converge-feature` worker (gated by the `converge?`
 // branch) so the hand-off is legible in the process, not buried in a persistence step.
+//
+// This is ALSO the one point every PR-delivering path passes through — the agent's own `opened`,
+// a retry's `opened`, and the implement-cell reconcile step's ADOPTED `opened` all land here — so
+// it is the canonical host-side writer of the idempotent "PR opened" comment on the claimed issue
+// (issue #907, app/issuePrLink.ts): a claimed single-issue run (`claimIssue`) that delivered a
+// keyed PR gets exactly one `🤖 Pull request opened: #n` comment on its issue, however the PR was
+// delivered. Epic slices never set `claimIssue`, so they never comment on the parent epic. The
+// comment is best-effort — a failure never fails the run; the owed link is persisted and the
+// poller's retry pass (app/service.ts → retryOutstandingIssuePrLinks) re-attempts it.
 import type { AppJobHandler } from "@nanobpm/urban";
 import { type FeatureRunStatus, featureRuns } from "../../app/feature.ts";
+import { requestIssuePrLink } from "../../app/issuePrLink.ts";
 import { parsePr } from "../../app/service.ts";
 import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
@@ -58,6 +68,23 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   });
   app.log.info("record-feature", { featureKey, featureStatus, rowStatus, prKey });
 
+  // Issue #907: announce the delivered PR on the claimed issue — ONE idempotent comment, posted by
+  // the HOST so every delivery path (agent-opened, retry-opened, reconcile-adopted) covers it.
+  // Only a claimed single-issue run (`claimIssue`) with a keyed PR qualifies; epic slices never set
+  // `claimIssue`, so they never comment on the parent epic. The ISSUE target comes from the run row
+  // (`repo` + `issue_number`), never from the PR's repository, so a cross-repo PR still lands on the
+  // claimed issue. Best-effort: a failed attempt leaves the owed link for the poller to retry and
+  // never fails the run.
+  const link = await requestIssuePrLink(
+    {
+      featureKey,
+      prKey,
+      claimIssue: job.variables.claimIssue,
+    },
+    app.data,
+  );
+  if (link !== "skipped") app.log.info("record-feature: issue PR link", { featureKey, prKey, link });
+
   return { featureStatus, prKey };
 };