@akagilnc/pi-workflow-roles 0.1.3758 → 0.1.3783

package/src/acp-host/role-envelope.ts

@@ -15,7 +15,7 @@ import type {
   RoleTurnKnownFailure,
   RoleTurnRequest,
 } from "../host-contracts.ts";
-import { packagedRoleInputFlag, packagedRolePhaseFlag } from "../packaged-role-registry.ts";
+import { packagedRoleInputFlag, packagedRoleOutputTool, packagedRolePhaseFlag } from "../packaged-role-registry.ts";
 import { stripSkillFrontmatter } from "../package-resources/method-skill.ts";
 import {
   createRoleRuntimeExtension,
@@ -27,12 +27,9 @@ import {
   type AcpRoleTurnHostConfig,
 } from "./role-turn-host.ts";
 import {
-  GatekeeperDecisionError,
-  WorkerCommitReminderError,
-  WorkerPrefixReminderError,
-  WorkerUnfinishedReasonReminderError,
-} from "../submission-errors.ts";
-import { isCorrectableExecuteError } from "../submission-correctable-error.ts";
+  isCorrectableExecuteError,
+  projectCorrectableExecuteRejection,
+} from "../submission-correctable-error.ts";
 import {
   buildNavigatorInfrastructureFailureFact,
   extractInfrastructureFailureEvidence,
@@ -98,7 +95,8 @@ export function projectAcpActivationFlags(request: RoleTurnRequest): Map<string,
   }
   if (activation.role === "collector") {
     flags.set("ak-collector-repo", activation.repo);
-    flags.set("ak-collector-pr", activation.pr);
+    // #676 D1: pr optional at admission; omit flag when role binds from materials.
+    if (activation.pr !== undefined) flags.set("ak-collector-pr", activation.pr);
     if (activation.requestManifestPath !== undefined) flags.set("ak-collector-request-manifest", activation.requestManifestPath);
   }
   return flags;
@@ -133,10 +131,33 @@ export function createComposedAcpRoleTurnHost(
   });
 }
 
+/** JSON Schema draft-07 document for host-native `--json-schema` (headless). */
+export function terminatingToolJsonSchema(parameters: unknown): Readonly<Record<string, unknown>> {
+  const cloned = JSON.parse(JSON.stringify(parameters)) as Record<string, unknown>;
+  // $schema last so a newer declaration on the tool parameters cannot override draft-07.
+  return Object.freeze({
+    ...cloned,
+    $schema: "http://json-schema.org/draft-07/schema#",
+  });
+}
+
 export async function prepareAcpRoleEnvelope(options: {
   readonly request: RoleTurnRequest;
   readonly dependencies: RoleRuntimeDependencies;
+  /**
+   * MCP unix socket path for the protocol-relay child. Always required — AK tools
+   * ride this single MCP path; headless structured_output reuses the same
+   * terminating-tool ledger path without listing the terminating tool on MCP.
+   */
   readonly socketPath: string;
+  /**
+   * Whether MCP `tools/list` advertises the role terminating tool.
+   * ACP keeps it listed (session-tool receipt). Headless hides it so the host
+   * native `--json-schema` / structured_output is the sole schema channel
+   * (#750 submission-tool-is-schema-channel) and empty MCP probes cannot
+   * pre-empt a later structured_output.
+   */
+  readonly listTerminatingToolOnMcp?: boolean;
   /**
    * Durable principal session path (header layout only).
    * Production passes DurablePrincipalAuthority.decode(principal).sessionFile so
@@ -145,6 +166,14 @@ export async function prepareAcpRoleEnvelope(options: {
   readonly sessionFile?: string;
 }): Promise<AcpPreparedTurn> {
   const { request } = options;
+  if (options.socketPath === "") {
+    throw new Error("prepareAcpRoleEnvelope requires socketPath");
+  }
+  const listTerminatingToolOnMcp = options.listTerminatingToolOnMcp !== false;
+  const earlyTerminatingTool = packagedRoleOutputTool(request.activation.role);
+  if (earlyTerminatingTool === undefined) {
+    throw new Error(`role has no terminating tool: ${request.activation.role}`);
+  }
   const flags = projectAcpActivationFlags(request);
   const tools = new Map<string, HostToolDefinition>();
   const handlers = new Map<string, Handler[]>();
@@ -405,6 +434,87 @@ export async function prepareAcpRoleEnvelope(options: {
     await emit("tool_execution_end", { toolCallId, toolName, isError: projected.isError });
     return projected;
   }
+  /**
+   * Shared terminating/support tool path for MCP relay and headless structured_output.
+   * Books the call, runs execute, projects tool_result; does not emit turn_end (closeRound).
+   */
+  async function invokeAkTool(name: string, args: unknown): Promise<{
+    content: ContentPart[];
+    isError: boolean;
+    blocked?: true;
+  }> {
+    const tool = tools.get(name);
+    if (tool === undefined) throw new Error(`Unknown AK tool: ${name}`);
+    const toolCallId = randomUUID();
+    calls.push({ toolCallId, toolName: name });
+    // First-record-then-audit: book the tool-call leaf in memory before execute so
+    // judge/doctor subject gates see the candidate on parent session books.
+    sessionEntries.push({
+      type: "message",
+      message: {
+        role: "assistant" as const,
+        content: [{
+          type: "toolCall",
+          id: toolCallId,
+          name,
+          arguments: args ?? {},
+        }],
+      },
+    });
+    try {
+      await emit("tool_execution_start", { toolCallId, toolName: name });
+      const blocked = (await emit("tool_call", { toolCallId, toolName: name, input: (args ?? {}) as Record<string, unknown> }))
+        .some((value) => typeof value === "object" && value !== null && "block" in value && value.block === true);
+      if (blocked) {
+        // Lawful seatbelt/block stays bare rejection — not infrastructure (#593 r3).
+        return { content: [{ type: "text", text: `AK tool blocked: ${name}` }], isError: true, blocked: true };
+      }
+    } catch (error) {
+      // Pre-execution emit failure shares the non-correctable infra pathway (#593 r3).
+      const declared = declareRoundInfrastructureFailure(error);
+      try {
+        const projected = await projectToolResult(toolCallId, name, {
+          content: declared.content,
+          details: declared.details,
+          isError: true,
+        });
+        return { content: projected.content, isError: true };
+      } catch {
+        return { content: declared.content, isError: true };
+      }
+    }
+    try {
+      const result = await tool.execute(toolCallId, (args ?? {}) as never, undefined, undefined, context);
+      const projected = await projectToolResult(toolCallId, name, {
+        content: result.content,
+        details: result.details,
+        isError: false,
+      });
+      // Candidate only: seal waits for closeRound after the host round boundary.
+      return { content: projected.content, isError: projected.isError };
+    } catch (error) {
+      let content: ContentPart[];
+      let details: Record<string, unknown>;
+      if (isCorrectableExecuteError(error)) {
+        const projected = projectCorrectableExecuteRejection(error);
+        content = [{ type: "text", text: projected.diagnostic }];
+        details = projected.details;
+      } else {
+        // Slot-before-abort; projectToolResult may still project durable details.
+        ({ content, details } = declareRoundInfrastructureFailure(error));
+      }
+      // The shared envelope's tool_result handler is the sole classifier:
+      // it projects either the structured submission non-pass (correctable
+      // rejection) or the typed infrastructure fact onto the reply.
+      const projected = await projectToolResult(toolCallId, name, {
+        content,
+        details,
+        isError: true,
+      });
+      return { content: projected.content, isError: projected.isError };
+    }
+  }
+
   function reply(socket: Socket, id: number, result?: unknown, error?: unknown): void {
     const rpcError = error instanceof Error
       ? { code: "ak-relay-failure", name: error.name, message: error.message }
@@ -426,7 +536,9 @@ export async function prepareAcpRoleEnvelope(options: {
           if (rpc.token !== token) { reply(socket, rpc.id, undefined, "unauthorized relay"); return; }
           try {
             if (rpc.method === "tools/list") {
-              reply(socket, rpc.id, { tools: [...tools.values()].map((tool) => {
+              const listed = [...tools.values()].filter((tool) =>
+                listTerminatingToolOnMcp || tool.name !== earlyTerminatingTool);
+              reply(socket, rpc.id, { tools: listed.map((tool) => {
                 return { name: tool.name, description: tool.description, inputSchema: tool.parameters };
               }) });
               return;
@@ -435,107 +547,24 @@ export async function prepareAcpRoleEnvelope(options: {
             const params = rpc.params as ToolCallParams | undefined;
             const name = params?.name;
             if (typeof name !== "string") throw new Error("MCP tool name is missing");
-            const tool = tools.get(name);
-            if (tool === undefined) throw new Error(`Unknown AK tool: ${name}`);
-            const toolCallId = randomUUID();
-            calls.push({ toolCallId, toolName: name });
-            // First-record-then-audit: book the tool-call leaf in memory before execute so
-            // judge/doctor subject gates see the candidate on parent session books.
-            {
-              const message = {
-                role: "assistant" as const,
-                content: [{
-                  type: "toolCall",
-                  id: toolCallId,
-                  name,
-                  arguments: params?.arguments ?? {},
-                }],
-              };
-              sessionEntries.push({ type: "message", message });
+            // Headless schema channel owns the terminating receipt — refuse MCP
+            // terminating calls so an empty probe cannot book a non-sealable candidate.
+            if (!listTerminatingToolOnMcp && name === earlyTerminatingTool) {
+              throw new Error(`terminating tool ${name} is schema-channel only on this host`);
             }
-            try {
-              await emit("tool_execution_start", { toolCallId, toolName: name });
-              const blocked = (await emit("tool_call", { toolCallId, toolName: name, input: params?.arguments ?? {} }))
-                .some((value) => typeof value === "object" && value !== null && "block" in value && value.block === true);
-              if (blocked) {
-                // Lawful seatbelt/block stays bare RPC rejection — not infrastructure (#593 r3).
-                reply(socket, rpc.id, undefined, new Error(`AK tool blocked: ${name}`));
-                return;
-              }
-            } catch (error) {
-              // Pre-execution emit failure (e.g. observation writer) shares the same
-              // non-correctable infra pathway as execute throws (#593 r3).
-              const declared = declareRoundInfrastructureFailure(error);
-              try {
-                const projected = await projectToolResult(toolCallId, name, {
-                  content: declared.content,
-                  details: declared.details,
-                  isError: true,
-                });
-                reply(socket, rpc.id, {
-                  content: projected.content,
-                  isError: true,
-                });
-              } catch {
-                // Slot already filled; durable projection may have partially failed.
-                reply(socket, rpc.id, {
-                  content: declared.content,
-                  isError: true,
-                });
-              }
+            const outcome = await invokeAkTool(name, params?.arguments ?? {});
+            if (outcome.blocked === true) {
+              reply(socket, rpc.id, undefined, new Error(outcome.content.map((p) => p.type === "text" ? p.text : "").join("")));
               return;
             }
-            try {
-              const result = await tool.execute(toolCallId, (params?.arguments ?? {}) as never, undefined, undefined, context);
-              const projected = await projectToolResult(toolCallId, name, {
-                content: result.content,
-                details: result.details,
-                isError: false,
-              });
-              // Candidate only: do not emit turn_end here. Seal waits for the typed ACP
-              // round boundary (closeRound after session/prompt), so delayed siblings stay
-              // in the same round instead of becoming silent post-seal anomalies.
-              reply(socket, rpc.id, { content: projected.content, ...(projected.isError ? { isError: true } : {}) });
-            } catch (error) {
-              let content: ContentPart[];
-              let details: Record<string, unknown>;
-              if (isCorrectableExecuteError(error)) {
-                const diagnostic = error instanceof Error ? error.message : String(error);
-                content = [{ type: "text", text: diagnostic }];
-                if (error instanceof GatekeeperDecisionError) {
-                  details = { ...error.result };
-                } else if (
-                  error instanceof WorkerCommitReminderError
-                  || error instanceof WorkerPrefixReminderError
-                  || error instanceof WorkerUnfinishedReasonReminderError
-                ) {
-                  details = { code: error.code };
-                } else if (typeof (error as unknown as { code?: unknown }).code === "string") {
-                  details = { code: (error as unknown as { code: string }).code };
-                } else {
-                  details = { code: error instanceof Error && error.name ? error.name : "correctable-submission-error" };
-                }
-              } else {
-                // Slot-before-abort; projectToolResult may still project durable details.
-                ({ content, details } = declareRoundInfrastructureFailure(error));
-              }
-              // The shared envelope's tool_result handler is the sole classifier:
-              // it projects either the structured submission non-pass (correctable
-              // rejection) or the typed infrastructure fact onto the reply.
-              const projected = await projectToolResult(toolCallId, name, {
-                content,
-                details,
-                isError: true,
-              });
-              reply(socket, rpc.id, { content: projected.content, ...(projected.isError ? { isError: true } : {}) });
-            }
+            reply(socket, rpc.id, { content: outcome.content, ...(outcome.isError ? { isError: true } : {}) });
           } catch (error) { reply(socket, rpc.id, undefined, error); }
         })();
       }
     });
   }
-  await listen(server, options.socketPath);
   const relay = fileURLToPath(new URL("./mcp-relay.mjs", import.meta.url));
+  await listen(server, options.socketPath);
   let disposed = false;
   // Tools execute in this process (relay is protocol-only). Mirror Pi's child-env
   // AK_ROLE_RUN_DIR / AK_ROLE_COURT_ATTEMPT injection onto the parent so ledger
@@ -566,8 +595,6 @@ export async function prepareAcpRoleEnvelope(options: {
     } catch (error) {
       cleanupFailures.push(error);
     }
-    // Server closure is unconditional: a shutdown-handler failure must not leave
-    // the listening MCP server keeping the completed invocation alive.
     try {
       const closeAll = (server as unknown as { closeAllConnections?: () => void }).closeAllConnections;
       if (typeof closeAll === "function") closeAll.call(server);
@@ -585,6 +612,14 @@ export async function prepareAcpRoleEnvelope(options: {
     }
   };
 
+  const terminatingToolName: string = earlyTerminatingTool;
+  async function ingestStructuredOutput(params: unknown): Promise<void> {
+    // MCP path may already have invoked the terminating tool this round; skip the
+    // duplicate so structured_output + tool-call does not arm non-sole.
+    if (calls.some((call) => call.toolName === terminatingToolName)) return;
+    await invokeAkTool(terminatingToolName, params ?? {});
+  }
+
   const closeRound: AcpPreparedTurn["closeRound"] = async () => {
     // Typed round boundary: hand the complete call list to the shared ledger once.
     if (calls.length > 0) {
@@ -668,6 +703,11 @@ export async function prepareAcpRoleEnvelope(options: {
     else process.env.AK_ROLE_COURT_ATTEMPT = request.courtAttemptId;
     runDirInjected = true;
 
+    const terminating = tools.get(terminatingToolName);
+    if (terminating === undefined) {
+      throw new Error(`terminating tool not registered after activation: ${terminatingToolName}`);
+    }
+    const jsonSchema = terminatingToolJsonSchema(terminating.parameters);
     return {
       mcpServers: [{
         name: `ak-${request.activation.role}`,
@@ -683,6 +723,9 @@ export async function prepareAcpRoleEnvelope(options: {
       abortSignal: hostAbort.signal,
       closeRound,
       dispose,
+      jsonSchema,
+      terminatingToolName,
+      ingestStructuredOutput,
     };
   } catch (error) {
     // listen already succeeded; dispose is not yet caller-owned. Release the

package/src/acp-host/role-turn-host.ts

@@ -43,6 +43,18 @@ export type AcpPreparedTurn = Readonly<{
     | { readonly accepted: false; readonly failure: RoleTurnKnownFailure }
   >;
   dispose?(): Promise<void>;
+  /**
+   * Headless CLI family (#645): role terminating-tool schema for host-native
+   * `--json-schema`. Present for every prepared turn; ACP ignores it.
+   */
+  jsonSchema: Readonly<Record<string, unknown>>;
+  /** Terminating tool name whose schema is `jsonSchema`. */
+  terminatingToolName: string;
+  /**
+   * Headless CLI family: feed host-native `structured_output` through the same
+   * terminating-tool path the MCP relay uses (ledger + gates). ACP ignores it.
+   */
+  ingestStructuredOutput(params: unknown): Promise<void>;
 }>;
 
 /** Fold structured system-prompt authority into the provider-visible ACP override. */

package/src/collector-config.ts

@@ -4,7 +4,6 @@ import { readFile } from "node:fs/promises";
 export const COLLECTOR_HOST = "github.com" as const;
 export const COLLECTOR_OWNER_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/;
 export const COLLECTOR_REPO_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,98}[A-Za-z0-9])?$/;
-export const COLLECTOR_FIXED_KICKOFF = "采集目标已受理，本局开始。";
 
 export type CollectorRepository = {
   display: string;

package/src/collector-github.ts

@@ -1,6 +1,8 @@
 import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
 
+import { parseCollectorPrNumber } from "./collector-config.ts";
+
 export type GitHubPullRequest = {
   number: number;
   state: string;
@@ -199,6 +201,232 @@ function parseJson(text: string, label: string): unknown {
   }
 }
 
+/**
+ * Shared PR-list payload parse for admission target lookup (#676 D1/D7).
+ * Every entry must carry a positive safe-integer number — malformed items fail
+ * the response (do not skip then claim uniqueness).
+ */
+export function parsePullRequestNumberList(raw: unknown, label: string): number[] {
+  if (!Array.isArray(raw)) {
+    throw new Error(`GitHub ${label} payload is not a list`);
+  }
+  const numbers: number[] = [];
+  for (const item of raw) {
+    if (!isRecord(item)) {
+      throw new Error(`GitHub ${label} payload contains a non-object pull request entry`);
+    }
+    try {
+      numbers.push(parseCollectorPrNumber(item["number"]));
+    } catch (error) {
+      throw new Error(`GitHub ${label} payload contains an invalid pull request number`, {
+        cause: error,
+      });
+    }
+  }
+  return numbers;
+}
+
+/**
+ * Online PR association by head owner:ref (state=all). Caller supplies the real
+ * head owner from branch context — never assume base repository owner is the fork head.
+ * Transport/HTTP/JSON failures throw with true cause (not target-ambiguity wash).
+ */
+export async function listPullRequestNumbersByHead(
+  runner: GhApiRunner,
+  input: {
+    readonly owner: string;
+    readonly repo: string;
+    readonly headOwner: string;
+    readonly headRef: string;
+    readonly signal?: AbortSignal;
+  },
+): Promise<number[]> {
+  const head = `${input.headOwner}:${input.headRef}`;
+  const path =
+    `/repos/${input.owner}/${input.repo}/pulls?head=${encodeURIComponent(head)}&state=all&per_page=100`;
+  const response = await runner(
+    ["api", "--hostname", "github.com", "--include", "-X", "GET", path],
+    input.signal === undefined ? {} : { signal: input.signal },
+  );
+  if (response.status < 200 || response.status >= 300) {
+    throw new Error(`GitHub ${path} failed with HTTP ${response.status}`, {
+      cause: {
+        endpoint: path,
+        status: response.status,
+        headers: response.headers,
+        body: response.bodyText,
+      },
+    });
+  }
+  return parsePullRequestNumberList(parseJson(response.bodyText, path), path);
+}
+
+/**
+ * Online PR association for a commit SHA (fork-safe; works when the commit is on the PR).
+ * Transport/HTTP/JSON failures throw with true cause.
+ */
+export async function listPullRequestNumbersByCommit(
+  runner: GhApiRunner,
+  input: {
+    readonly owner: string;
+    readonly repo: string;
+    readonly commitSha: string;
+    readonly signal?: AbortSignal;
+  },
+): Promise<number[]> {
+  const path = `/repos/${input.owner}/${input.repo}/commits/${encodeURIComponent(input.commitSha)}/pulls`;
+  const response = await runner(
+    ["api", "--hostname", "github.com", "--include", "-X", "GET", path],
+    input.signal === undefined ? {} : { signal: input.signal },
+  );
+  if (response.status < 200 || response.status >= 300) {
+    throw new Error(`GitHub ${path} failed with HTTP ${response.status}`, {
+      cause: {
+        endpoint: path,
+        status: response.status,
+        headers: response.headers,
+        body: response.bodyText,
+      },
+    });
+  }
+  return parsePullRequestNumberList(parseJson(response.bodyText, path), path);
+}
+
+/**
+ * Online association for a structured ticket number (#676 D1):
+ * - Number is itself a pull request → that PR.
+ * - Number is an issue → PRs linked via timeline cross-reference / closed-by.
+ * Transport/HTTP/JSON failures throw with true cause.
+ * 404 / empty association → [].
+ */
+export async function listPullRequestNumbersByTicket(
+  runner: GhApiRunner,
+  input: {
+    readonly owner: string;
+    readonly repo: string;
+    readonly ticketNumber: number;
+    readonly signal?: AbortSignal;
+  },
+): Promise<number[]> {
+  const issuePath = `/repos/${input.owner}/${input.repo}/issues/${input.ticketNumber}`;
+  const issueResponse = await runner(
+    ["api", "--hostname", "github.com", "--include", "-X", "GET", issuePath],
+    input.signal === undefined ? {} : { signal: input.signal },
+  );
+  if (issueResponse.status === 404) return [];
+  if (issueResponse.status < 200 || issueResponse.status >= 300) {
+    throw new Error(`GitHub ${issuePath} failed with HTTP ${issueResponse.status}`, {
+      cause: {
+        endpoint: issuePath,
+        status: issueResponse.status,
+        headers: issueResponse.headers,
+        body: issueResponse.bodyText,
+      },
+    });
+  }
+  const issueRaw = parseJson(issueResponse.bodyText, issuePath);
+  if (!isRecord(issueRaw)) {
+    throw new Error(`GitHub ${issuePath} payload is not an object`);
+  }
+  // Issues endpoint returns PRs too — own-key pull_request means the number is the PR.
+  if (Object.hasOwn(issueRaw, "pull_request")) {
+    return [parseCollectorPrNumber(issueRaw["number"] ?? input.ticketNumber)];
+  }
+
+  // Linked PRs: GraphQL closed-by + cross-referenced PR sources (existing gh runner seam).
+  const query = `query($owner: String!, $repo: String!, $number: Int!) {
+  repository(owner: $owner, name: $repo) {
+    issue(number: $number) {
+      closedByPullRequestsReferences(first: 50) { nodes { number } }
+      timelineItems(first: 100, itemTypes: [CROSS_REFERENCED_EVENT, CONNECTED_EVENT]) {
+        nodes {
+          __typename
+          ... on CrossReferencedEvent {
+            source { ... on PullRequest { number } }
+          }
+          ... on ConnectedEvent {
+            subject { ... on PullRequest { number } }
+          }
+        }
+      }
+    }
+  }
+}`;
+  const args = [
+    "api",
+    "graphql",
+    "--hostname",
+    "github.com",
+    "--include",
+    "-f",
+    `query=${query}`,
+    "-f",
+    `owner=${input.owner}`,
+    "-f",
+    `repo=${input.repo}`,
+    "-F",
+    `number=${input.ticketNumber}`,
+  ];
+  const gqlResponse = await runner(
+    args,
+    input.signal === undefined ? {} : { signal: input.signal },
+  );
+  if (gqlResponse.status < 200 || gqlResponse.status >= 300) {
+    throw new Error(`GitHub GraphQL issue→PR failed with HTTP ${gqlResponse.status}`, {
+      cause: {
+        endpoint: "graphql",
+        status: gqlResponse.status,
+        headers: gqlResponse.headers,
+        body: gqlResponse.bodyText,
+      },
+    });
+  }
+  let payload: unknown;
+  try {
+    payload = JSON.parse(gqlResponse.bodyText);
+  } catch (error) {
+    throw new Error("GitHub GraphQL issue→PR returned malformed JSON", { cause: error });
+  }
+  if (!isRecord(payload)) {
+    throw new Error("GitHub GraphQL issue→PR payload is not an object");
+  }
+  if (payload.errors !== undefined) {
+    throw new Error(`GitHub GraphQL issue→PR errors: ${JSON.stringify(payload.errors).slice(0, 600)}`, {
+      cause: { body: gqlResponse.bodyText, errors: payload.errors },
+    });
+  }
+  const data = payload.data;
+  if (!isRecord(data)) return [];
+  const repository = data["repository"];
+  if (!isRecord(repository)) return [];
+  const issue = repository["issue"];
+  if (!isRecord(issue)) return [];
+  const numbers: number[] = [];
+  const closedBy = issue["closedByPullRequestsReferences"];
+  if (isRecord(closedBy) && Array.isArray(closedBy["nodes"])) {
+    for (const node of closedBy["nodes"]) {
+      if (isRecord(node) && typeof node["number"] === "number") {
+        numbers.push(parseCollectorPrNumber(node["number"]));
+      }
+    }
+  }
+  const timeline = issue["timelineItems"];
+  if (isRecord(timeline) && Array.isArray(timeline["nodes"])) {
+    for (const node of timeline["nodes"]) {
+      if (!isRecord(node)) continue;
+      const source = node["source"];
+      if (isRecord(source) && typeof source["number"] === "number") {
+        numbers.push(parseCollectorPrNumber(source["number"]));
+      }
+      const subject = node["subject"];
+      if (isRecord(subject) && typeof subject["number"] === "number") {
+        numbers.push(parseCollectorPrNumber(subject["number"]));
+      }
+    }
+  }
+  return [...new Set(numbers)];
+}
+
 let commentFailureEvidence = 0;
 function commentFailureCause(error: unknown) {
   return {
@@ -249,13 +477,19 @@ export function normalizePullRequest(raw: unknown): GitHubPullRequest {
     throw new Error("GitHub pull request payload missing head.sha");
   }
   const number = requireNumber(raw["number"], "number");
-  const state = requireString(raw["state"], "state").toUpperCase();
+  // GitHub REST: merged PRs keep state="closed" and set merged/merged_at. Project the
+  // real merge fact so receipt/settlement can distinguish merged from merely closed (#676 D6).
+  const mergedFlag = raw["merged"] === true
+    || (typeof raw["merged_at"] === "string" && raw["merged_at"].length > 0);
+  const rawState = requireString(raw["state"], "state").toUpperCase();
+  // After toUpperCase the only OPEN spelling is "OPEN"; keep MERGED vs CLOSED distinction.
+  const state = mergedFlag ? "MERGED" : rawState;
   const htmlUrl = typeof raw["html_url"] === "string"
     ? raw["html_url"]
     : `https://github.com/unknown/unknown/pull/${number}`;
   return {
     number,
-    state: state === "OPEN" || state === "open" ? "OPEN" : state,
+    state,
     headOid: head["sha"],
     ...(typeof raw["updated_at"] === "string" ? { updatedAt: raw["updated_at"] } : {}),
     url: htmlUrl,