@nanobpm/nano-workforce 0.203.1 → 0.204.1

package/app/issuePrLink.ts

@@ -0,0 +1,312 @@
+// The canonical "PR opened" issue-link decision (issue #907).
+//
+// When a single-issue feature run delivers its PR, the claimed issue's comment thread must link to
+// it: the agent posts `🤖 Starting work…` (resources/prompts/feature.md) but nothing ever said
+// "PR opened: #N", so a reader saw the claim and then silence — and concluded the agent stalled
+// (camunda/camunda#19090: the PR existed, opened by a retry, but the thread never showed it).
+//
+// This module is the ONE host-side writer (derivation over duplication — NOT a second instruction
+// in each prompt). `pr.record-feature` calls it on the run's delivery point, which EVERY
+// PR-delivering path passes through: the agent's own `opened`, a retry's `opened`, and the
+// implement-cell reconcile step's ADOPTED `opened` (app/implementReconcile.ts) all converge there.
+//
+// Gating mirrors the claim rule: only when the run seeded `claimIssue: true` (a single-issue
+// feature run — app/feature.ts). An epic slice never sets it, so a wave slice NEVER comments on
+// the shared parent epic.
+//
+// Durable state machine (migration 125) — three columns on `feature_runs`:
+//   • `pr_link_want_pr_key` — the PR the issue is OWED a link for. Written by `requestIssuePrLink`
+//     (pr.record-feature) ONLY for a claimed single-issue run with a keyed PR.
+//   • `pr_linked_pr_key`    — CONFIRMED: written only after a successful POST or a marker match. A
+//     pending/in-flight claim is NEVER mistaken for a confirmed link.
+//   • `pr_link_lease_at`    — an EXPIRING in-flight lease, CAS-claimed before any GitHub I/O so two
+//     racing passes never both post. On ANY failure (unreadable scan, rejected/thrown POST, crash)
+//     the lease is simply left to expire — that is the retry backoff — and the poller's
+//     `pollIssuePrLinks` pass (app/service.ts → `retryOutstandingIssuePrLinks`) re-attempts every
+//     outstanding link through this same `attemptIssuePrLink`, so a transient failure never leaves
+//     the delivered PR unannounced and never fails or restarts the run.
+// Each comment also carries a hidden `<!-- nwf:pr-linked:#n <canonical-pr-url> -->` marker; the
+// issue's comments are scanned (ALL pages) before posting, which heals a crash between a successful
+// POST and the confirm. The marker keys on the canonical PR URL, not just the number, because PR
+// numbers are repository-local — a same-number PR in another repo must NOT satisfy the scan.
+//
+// Stale-lease safety: the lease is re-validated with a guarded CAS (re-claiming a FRESH timestamp)
+// IMMEDIATELY before the POST. A worker that stalls on the marker scan / title lookup past the lease
+// expiry can have its lease re-claimed by the poller (which then posts); when the worker resumes it
+// must NOT post a duplicate. The pre-post CAS rejects that stale holder (its claimed ts no longer
+// matches) BEFORE the write — the after-the-fact confirm guard would be too late.
+//
+// Targeting: the comment goes to the CLAIMED ISSUE (the run row's `repo` + `issue_number`), never
+// to the PR's repository — a cross-repo PR is looked up (title) in its own repo only.
+//
+// Best-effort throughout: every path resolves to a status string and NEVER throws.
+import type { DataLayer } from "@nanobpm/urban";
+import { featureRuns } from "./feature.ts";
+import { fetchPrMeta, runGh, useGh } from "./github.ts";
+import { parsePr } from "./prParse.ts";
+
+/** The hidden per-PR dedupe marker prefix carried by every PR-opened comment. The full marker is
+ *  `<!-- nwf:pr-linked:#<number> <canonical-pr-url> -->`; scanning for it makes a repeated pass
+ *  idempotent even when the durable claim was lost (crash between the POST and the record write).
+ *  The canonical PR URL is part of the marker because PR numbers are repository-local: a number-only
+ *  marker would let a same-number PR in a DIFFERENT repo satisfy the scan and confirm a link that
+ *  was never announced (issue #907 review). */
+export const ISSUE_PR_LINK_MARKER_PREFIX = "<!-- nwf:pr-linked:#";
+
+/** Build the full dedupe marker for one PR: `<!-- nwf:pr-linked:#<number> <canonical-pr-url> -->`.
+ *  The URL disambiguates a same-number PR in another repository. */
+export function issuePrLinkMarker(pr: { number: number; url: string }): string {
+  return `${ISSUE_PR_LINK_MARKER_PREFIX}${pr.number} ${pr.url} -->`;
+}
+
+/** The discriminated outcome of a link attempt — logged by the caller so a skipped/failed link is
+ *  observable without ever failing the run. */
+export type IssuePrLinkOutcome =
+  | "posted" // the comment was posted and the link confirmed
+  | "already-recorded" // the confirmed record already names the owed PR — no GitHub I/O at all
+  | "already-marked" // the marker scan found the comment — link confirmed without re-posting
+  | "claim-lost" // another pass holds a live lease (or the CAS lost) — that pass owns the attempt
+  | "post-failed" // GitHub rejected/threw on the POST — lease left to expire; the poller retries
+  | "list-failed" // the marker scan was unreadable — nothing posted blind; the poller retries
+  | "skipped"; // not a claimed single-issue run, no PR, no row, or a guard failure
+
+/** The comment body: one line naming the PR (number, optional title, URL) plus the hidden marker. */
+export function prOpenedCommentBody(pr: { number: number; title?: string | null; url: string }): string {
+  const title = typeof pr.title === "string" && pr.title.trim() !== "" ? ` — ${pr.title.trim()}` : "";
+  return `🤖 Pull request opened: #${pr.number}${title}  (${pr.url})\n\n${issuePrLinkMarker(pr)}`;
+}
+
+/** How long an in-flight lease blocks other passes. A crash or failure leaves it to expire, after
+ *  which the poller retries — so this is also the retry backoff. */
+export const ISSUE_PR_LINK_LEASE_MS = 5 * 60 * 1000;
+
+/** Hard deadline on EVERY GitHub read/write this module makes (both transports). Kept well below the
+ *  lease so a pass that re-validated its lease immediately before the POST still owns it for the
+ *  whole pending write: a POST can never outlive the lease and race a poller re-claim into a
+ *  duplicate. A timed-out POST is `post-failed` (never confirmed); the lease then expires and the
+ *  retry's marker scan heals the case where GitHub committed it anyway. */
+export const ISSUE_PR_LINK_IO_TIMEOUT_MS = 60 * 1000;
+
+const PAGE_SIZE = 100;
+/** Hard bound on pages scanned (10k comments) so a pathological issue can't loop forever. Hitting it
+ *  is treated as UNREADABLE (fail closed: never post blind). */
+const MAX_PAGES = 100;
+
+/** List the bodies of EVERY comment on an issue, across all pages. `null` when no transport is
+ *  usable; THROWS on a transport failure (or an over-long thread) so the caller can distinguish
+ *  "unreadable" (post nothing) from "empty". */
+async function listIssueCommentBodies(
+  repo: string,
+  issueNumber: number,
+  token: string,
+  timeoutMs: number,
+): Promise<string[] | null> {
+  const ghMode = await useGh();
+  if (!ghMode && !token) return null;
+  const bodies: string[] = [];
+  for (let page = 1; page <= MAX_PAGES; page++) {
+    const path = `repos/${repo}/issues/${issueNumber}/comments?per_page=${PAGE_SIZE}&page=${page}`;
+    let arr: unknown;
+    if (ghMode) {
+      arr = JSON.parse(await runGh(["api", path], { timeoutMs }));
+    } else {
+      const r = await fetch(`https://api.github.com/${path}`, {
+        headers: { authorization: `Bearer ${token}`, accept: "application/vnd.github+json" },
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+      if (!r.ok) throw new Error(`github ${r.status} ${r.statusText}`.trim());
+      arr = await r.json();
+    }
+    if (!Array.isArray(arr)) throw new Error("github: unexpected comments payload");
+    for (const c of arr) {
+      const body = c !== null && typeof c === "object" && "body" in c ? c.body : "";
+      bodies.push(typeof body === "string" ? body : "");
+    }
+    if (arr.length < PAGE_SIZE) return bodies;
+  }
+  throw new Error(`github: issue ${repo}#${issueNumber} has more than ${MAX_PAGES * PAGE_SIZE} comments`);
+}
+
+/** Post one comment on an issue. Returns whether GitHub accepted it; `false` when no transport is
+ *  usable or EITHER transport rejected or threw (a connection failure is normalised, never thrown). */
+async function postIssueComment(
+  repo: string,
+  issueNumber: number,
+  body: string,
+  token: string,
+  timeoutMs: number,
+): Promise<boolean> {
+  try {
+    if (await useGh()) {
+      await runGh(["issue", "comment", String(issueNumber), "--repo", repo, "--body", body], { timeoutMs });
+      return true;
+    }
+    if (!token) return false;
+    const r = await fetch(`https://api.github.com/repos/${repo}/issues/${issueNumber}/comments`, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${token}`,
+        accept: "application/vnd.github+json",
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ body }),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    return r.ok;
+  } catch {
+    return false;
+  }
+}
+
+export interface RequestIssuePrLinkInput {
+  /** The run's `feature_key` (`owner/repo#N`) — the durable record key. */
+  featureKey: string;
+  /** The delivered PR key (null/undefined ⇒ nothing to announce). */
+  prKey: string | null | undefined;
+  /** The run's `claimIssue` seed — true ONLY for single-issue feature runs (app/feature.ts). */
+  claimIssue: unknown;
+}
+
+/** Record that the claimed issue is OWED a "PR opened" link for `prKey`, then attempt it once.
+ *  Called by pr.record-feature; a failed attempt is retried by the poller (`retryOutstandingIssuePrLinks`).
+ *  Resolves to the outcome (never throws). */
+export async function requestIssuePrLink(
+  input: RequestIssuePrLinkInput,
+  data: DataLayer,
+  token: string = process.env.GITHUB_TOKEN ?? "",
+): Promise<IssuePrLinkOutcome> {
+  try {
+    // Gate: claimed single-issue runs only, with a keyed PR. An epic slice (`claimIssue` unset) and a
+    // blocked/skipped run (no PR) are a pure no-op — no state, no GitHub I/O.
+    if (input.claimIssue !== true) return "skipped";
+    if (!input.prKey || !parsePr(input.prKey)) return "skipped";
+    const r = await data
+      .open()
+      .exec(`UPDATE "feature_runs" SET "pr_link_want_pr_key" = ? WHERE "feature_key" = ?`, [
+        input.prKey,
+        input.featureKey,
+      ]);
+    if (r.changed === 0) return "skipped";
+    return await attemptIssuePrLink(input.featureKey, data, token);
+  } catch {
+    return "skipped";
+  }
+}
+
+/** Attempt the OWED link for one run (the single canonical attempt, shared by record-feature and the
+ *  poller retry). Never throws. */
+export async function attemptIssuePrLink(
+  featureKey: string,
+  data: DataLayer,
+  token: string = process.env.GITHUB_TOKEN ?? "",
+  now: () => Date = () => new Date(),
+  ioTimeoutMs: number = ISSUE_PR_LINK_IO_TIMEOUT_MS,
+): Promise<IssuePrLinkOutcome> {
+  try {
+    const row = await featureRuns(data).get(featureKey);
+    if (!row) return "skipped";
+    const want = row.pr_link_want_pr_key ?? null;
+    const pr = want ? parsePr(want) : null;
+    if (!want || !pr) return "skipped";
+    // The confirmed record already names the owed PR — no GitHub I/O at all.
+    if (row.pr_linked_pr_key === want) return "already-recorded";
+    const issueRepo = typeof row.repo === "string" ? row.repo : "";
+    const issueNumber = Number(row.issue_number);
+    if (!issueRepo || !Number.isInteger(issueNumber) || issueNumber <= 0) return "skipped";
+    // Claim an EXPIRING lease before any GitHub I/O (guarded CAS): only a free or expired lease, for
+    // a still-owed and still-unconfirmed PR, flips — so two racing passes never both post.
+    const t = now();
+    const ts = t.toISOString();
+    const expired = new Date(t.getTime() - ISSUE_PR_LINK_LEASE_MS).toISOString();
+    const claim = await data
+      .open()
+      .exec(
+        `UPDATE "feature_runs" SET "pr_link_lease_at" = ? WHERE "feature_key" = ? AND "pr_link_want_pr_key" = ? AND ("pr_linked_pr_key" IS NULL OR "pr_linked_pr_key" != ?) AND ("pr_link_lease_at" IS NULL OR "pr_link_lease_at" < ?)`,
+        [ts, featureKey, want, want, expired],
+      );
+    if (claim.changed === 0) return "claim-lost";
+    // Confirm the link, releasing the lease. Guards on the CURRENT lease ts (the one this pass last
+    // (re-)claimed), so only the live holder confirms.
+    const confirm = async (leaseTs: string) => {
+      await data
+        .open()
+        .exec(
+          `UPDATE "feature_runs" SET "pr_linked_pr_key" = ?, "pr_link_lease_at" = NULL WHERE "feature_key" = ? AND "pr_link_lease_at" = ?`,
+          [want, featureKey, leaseTs],
+        );
+    };
+    // The marker scan (every page) heals a crash between a successful POST and the confirm.
+    let bodies: string[] | null;
+    try {
+      bodies = await listIssueCommentBodies(issueRepo, issueNumber, token, ioTimeoutMs);
+    } catch {
+      // UNREADABLE — posting blind could double-post. Leave the lease to expire; the poller retries.
+      return "list-failed";
+    }
+    const marker = issuePrLinkMarker(pr);
+    if (bodies?.some((b) => b.includes(marker))) {
+      await confirm(ts);
+      return "already-marked";
+    }
+    // The title is best-effort, read from the PR's OWN repository.
+    let title: string | null = null;
+    try {
+      title = (await fetchPrMeta(pr.repo, pr.number, token, ioTimeoutMs))?.title ?? null;
+    } catch {
+      title = null;
+    }
+    // Re-validate lease ownership IMMEDIATELY before the write. The scan + title lookup above are
+    // each bounded by ioTimeoutMs (so a hung read can never wedge pr.record-feature or the poller
+    // pass), but together they can still approach the lease: if this pass stalled past the lease expiry, the poller may have re-claimed the
+    // lease and posted — and the after-the-fact confirm guard runs too late to stop a duplicate.
+    // Re-claim a FRESH timestamp guarded on the one this pass holds: only the CURRENT holder flips
+    // (changed=1), extending its lease through the write; a stale holder whose ts was overwritten
+    // gets changed=0 and backs off WITHOUT posting.
+    const ts2 = now().toISOString();
+    const stillHolder = await data
+      .open()
+      .exec(`UPDATE "feature_runs" SET "pr_link_lease_at" = ? WHERE "feature_key" = ? AND "pr_link_lease_at" = ?`, [
+        ts2,
+        featureKey,
+        ts,
+      ]);
+    if (stillHolder.changed === 0) return "claim-lost";
+    const posted = await postIssueComment(
+      issueRepo,
+      issueNumber,
+      prOpenedCommentBody({ number: pr.number, title, url: pr.url }),
+      token,
+      ioTimeoutMs,
+    );
+    // A failure leaves the lease to expire (never confirmed) — the poller's retry pass re-attempts.
+    if (!posted) return "post-failed";
+    await confirm(ts2);
+    return "posted";
+  } catch {
+    return "skipped";
+  }
+}
+
+/** The poller retry pass: re-attempt every OUTSTANDING owed link (owed, unconfirmed, lease free or
+ *  expired). Only rows pr.record-feature marked as owed are scanned — never pre-#907 rows or epic
+ *  slices. Never throws. */
+export async function retryOutstandingIssuePrLinks(
+  data: DataLayer,
+  token: string = process.env.GITHUB_TOKEN ?? "",
+  now: () => Date = () => new Date(),
+): Promise<Record<string, IssuePrLinkOutcome>> {
+  const out: Record<string, IssuePrLinkOutcome> = {};
+  try {
+    const expired = new Date(now().getTime() - ISSUE_PR_LINK_LEASE_MS).toISOString();
+    const rows = await data
+      .open()
+      .query<{ feature_key: string }>(
+        `SELECT "feature_key" FROM "feature_runs" WHERE "pr_link_want_pr_key" IS NOT NULL AND ("pr_linked_pr_key" IS NULL OR "pr_linked_pr_key" != "pr_link_want_pr_key") AND ("pr_link_lease_at" IS NULL OR "pr_link_lease_at" < ?)`,
+        [expired],
+      );
+    for (const r of rows) out[r.feature_key] = await attemptIssuePrLink(r.feature_key, data, token, now);
+  } catch {
+    // Best-effort: a link retry must never break the poll loop.
+  }
+  return out;
+}

package/app/service.ts

@@ -59,6 +59,7 @@ import {
   requestCopilotReview,
 } from "./github.ts";
 import { activeStatusesFor, derivedTrackingTable } from "./instanceTracking.ts";
+import { retryOutstandingIssuePrLinks } from "./issuePrLink.ts";
 import { pollLineage } from "./lineage.ts";
 import { mergeableRepollInterval, mergeableWaitTimeout } from "./mergeableWait.ts";
 import { mergeLanes, readExclusions } from "./mergeExclusion.ts";
@@ -3922,6 +3923,8 @@ export async function pollOnce(
   await pollWaitGate(data);
   await pollPromotion(data, engine, token);
   await pollFeatureDelivery(data, engine);
+  // Issue #907: retry every owed-but-unconfirmed "PR opened" issue link (best-effort, never throws).
+  await retryOutstandingIssuePrLinks(data, token);
   await pollLineage(data);
   await pollUserTasks(data, engine, engineRest);
   // The escalation steward is an OPTIONAL, best-effort pass: a steward-specific failure (a search or

package/db/migrations/125_feature_runs_pr_linked.sql

@@ -0,0 +1,78 @@
+-- Issue #907: the host posts one idempotent "PR opened" comment on the claimed issue when a
+-- single-issue feature run delivers its PR (app/issuePrLink.ts — attempted inline by
+-- pr.record-feature and RETRIED by the poller's `pollIssuePrLinks` pass until it lands).
+--
+-- Three columns carry the durable link state machine:
+--   • `pr_link_want_pr_key` — the `owner/repo#N` PR the claimed issue is OWED a link for. Written by
+--     pr.record-feature ONLY for a claimed single-issue run that delivered a keyed PR, so the
+--     poller's retry pass never touches pre-#907 rows or epic slices.
+--   • `pr_linked_pr_key`    — CONFIRMED: set only after a successful POST or a marker match. A link is
+--     outstanding while it differs from `pr_link_want_pr_key`.
+--   • `pr_link_lease_at`    — a short-lived in-flight lease (ISO time), claimed with a guarded CAS
+--     before any GitHub write so two racing passes never both post. A crash or failure leaves the
+--     lease to EXPIRE (it is never mistaken for a confirmed link), which doubles as retry backoff.
+-- The hidden `<!-- nwf:pr-linked:#n -->` marker scanned on the issue's comments heals a crash
+-- between a successful POST and the confirm write.
+--
+-- Additive (expand): a nullable column with no default write — existing rows read NULL (never
+-- linked), exactly the pre-#907 state (no comment was ever posted for them).
+--
+-- The column is mirrored through the `delivery_units` aggregate so the `feature_runs__units` compat
+-- VIEW stays row-for-row equal to `feature_runs` (ADR 0006, parity-tested in
+-- app/deliveryUnit.test.ts): the Feature sync triggers (089) and VIEW (091) are re-created verbatim
+-- plus `pr_linked_pr_key`, exactly as migration 116 did for `human_approval` and 120 for
+-- `auto_resolve_escalations`.
+
+ALTER TABLE feature_runs ADD COLUMN pr_linked_pr_key TEXT;
+ALTER TABLE feature_runs ADD COLUMN pr_link_want_pr_key TEXT;
+ALTER TABLE feature_runs ADD COLUMN pr_link_lease_at TEXT;
+
+ALTER TABLE delivery_units ADD COLUMN pr_linked_pr_key TEXT;
+ALTER TABLE delivery_units ADD COLUMN pr_link_want_pr_key TEXT;
+ALTER TABLE delivery_units ADD COLUMN pr_link_lease_at TEXT;
+
+DROP TRIGGER IF EXISTS feature_runs__du_ai;
+CREATE TRIGGER feature_runs__du_ai AFTER INSERT ON feature_runs
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, repo, issue_number, issue_url, title, base_branch, status, process_key, pr_key, converge, auto_merge, human_approval, auto_resolve_escalations, outcome, delivery_label, pr_linked_pr_key, pr_link_want_pr_key, pr_link_lease_at, acknowledged_at, stage, stage_state, stage_skipped, attention, list_bucket, created_at, updated_at)
+  VALUES ('feature:' || NEW.feature_key, 'feature', NEW.feature_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'running' THEN 'running' WHEN NEW.status = 'escalated' THEN 'escalated' WHEN NEW.status = 'opened' THEN 'opened' WHEN NEW.status = 'converging' THEN 'converging' WHEN NEW.status = 'awaiting_operator' THEN 'awaiting_operator' WHEN NEW.status = 'merged' THEN 'merged' WHEN NEW.status = 'converged' THEN 'converged' WHEN NEW.status = 'blocked' THEN 'blocked' WHEN NEW.status = 'skipped' THEN 'skipped' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('opened', 'converging', 'merged', 'converged', 'blocked', 'skipped', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('running', 'escalated', 'awaiting_operator') THEN 'dispatched' ELSE NULL END, NEW.repo, NEW.issue_number, NEW.issue_url, NEW.title, NEW.base_branch, NEW.status, NEW.process_key, NEW.pr_key, NEW.converge, NEW.auto_merge, NEW.human_approval, NEW.auto_resolve_escalations, NEW.outcome, NEW.delivery_label, NEW.pr_linked_pr_key, NEW.pr_link_want_pr_key, NEW.pr_link_lease_at, NEW.acknowledged_at, NEW.stage, NEW.stage_state, NEW.stage_skipped, NEW.attention, NEW.list_bucket, NEW.created_at, NEW.updated_at);
+END;
+
+DROP TRIGGER IF EXISTS feature_runs__du_au;
+CREATE TRIGGER feature_runs__du_au AFTER UPDATE ON feature_runs
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, repo, issue_number, issue_url, title, base_branch, status, process_key, pr_key, converge, auto_merge, human_approval, auto_resolve_escalations, outcome, delivery_label, pr_linked_pr_key, pr_link_want_pr_key, pr_link_lease_at, acknowledged_at, stage, stage_state, stage_skipped, attention, list_bucket, created_at, updated_at)
+  VALUES ('feature:' || NEW.feature_key, 'feature', NEW.feature_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'running' THEN 'running' WHEN NEW.status = 'escalated' THEN 'escalated' WHEN NEW.status = 'opened' THEN 'opened' WHEN NEW.status = 'converging' THEN 'converging' WHEN NEW.status = 'awaiting_operator' THEN 'awaiting_operator' WHEN NEW.status = 'merged' THEN 'merged' WHEN NEW.status = 'converged' THEN 'converged' WHEN NEW.status = 'blocked' THEN 'blocked' WHEN NEW.status = 'skipped' THEN 'skipped' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('opened', 'converging', 'merged', 'converged', 'blocked', 'skipped', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('running', 'escalated', 'awaiting_operator') THEN 'dispatched' ELSE NULL END, NEW.repo, NEW.issue_number, NEW.issue_url, NEW.title, NEW.base_branch, NEW.status, NEW.process_key, NEW.pr_key, NEW.converge, NEW.auto_merge, NEW.human_approval, NEW.auto_resolve_escalations, NEW.outcome, NEW.delivery_label, NEW.pr_linked_pr_key, NEW.pr_link_want_pr_key, NEW.pr_link_lease_at, NEW.acknowledged_at, NEW.stage, NEW.stage_state, NEW.stage_skipped, NEW.attention, NEW.list_bucket, NEW.created_at, NEW.updated_at);
+END;
+
+DROP VIEW IF EXISTS feature_runs__units;
+CREATE VIEW feature_runs__units AS
+SELECT
+  du.legacy_key AS feature_key,
+  du.repo AS repo,
+  du.issue_number AS issue_number,
+  du.issue_url AS issue_url,
+  du.base_branch AS base_branch,
+  du.status AS status,
+  du.process_key AS process_key,
+  du.pr_key AS pr_key,
+  du.converge AS converge,
+  du.auto_merge AS auto_merge,
+  du.human_approval AS human_approval,
+  du.auto_resolve_escalations AS auto_resolve_escalations,
+  du.outcome AS outcome,
+  du.created_at AS created_at,
+  du.updated_at AS updated_at,
+  du.delivery_label AS delivery_label,
+  du.pr_linked_pr_key AS pr_linked_pr_key,
+  du.pr_link_want_pr_key AS pr_link_want_pr_key,
+  du.pr_link_lease_at AS pr_link_lease_at,
+  du.title AS title,
+  du.acknowledged_at AS acknowledged_at,
+  du.stage AS stage,
+  du.stage_state AS stage_state,
+  du.stage_skipped AS stage_skipped,
+  du.attention AS attention,
+  du.list_bucket AS list_bucket
+FROM delivery_units du
+WHERE du.kind = 'feature';

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.1",
+  "version": "0.204.1",
   "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",
@@ -66,7 +66,7 @@
   },
   "dependencies": {
     "@nanobpm/agentic": "^0.15.0",
-    "@nanobpm/urban": "^0.96.0",
+    "@nanobpm/urban": "^0.98.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2"
   },
   "devDependencies": {

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" />