@akagilnc/pi-workflow-roles 0.1.3749 → 0.1.3771

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,

package/src/collector-identity.ts

@@ -2,8 +2,11 @@ import type {
   GitHubMachineIdentity,
 } from "./collector-github.ts";
 import type { CollectorEvidenceRecord, HeadRelation } from "./collector-evidence.ts";
+import type { CollectorSubmissionProjection } from "./package-contracts/collector-output.ts";
 import { CorrectableSubmissionError } from "./submission-correctable-error.ts";
 
+export type { CollectorSubmissionProjection };
+
 export type CollectorMaterialRef = {
   kind: "review" | "issue_comment" | "review_comment" | "reaction";
   id: number;
@@ -21,7 +24,10 @@ export type CollectorMaterialRef = {
 export type CollectorFinding = {
   identity: GitHubMachineIdentity | null;
   source: CollectorMaterialRef;
+  /** Short classification label; not the finding summary. */
   category?: string;
+  /** Finding summary for the caller; not a body transcription. */
+  summary?: string;
   pointer: {
     repository: string;
     prNumber: number;
@@ -30,6 +36,8 @@ export type CollectorFinding = {
     authorLogin?: string;
     kind: CollectorMaterialRef["kind"];
     authoritativeTime?: string | null;
+    /** Corresponding commit when the evidence carries one. */
+    commitOid?: string | null;
   };
 };
 
@@ -121,9 +129,9 @@ export class CollectorUnknownEvidenceError extends CorrectableSubmissionError {
 }
 
 /**
- * #641 chain①: any malformed findings submission is a model misuse the model
- * can correct and resubmit — a branded correctable rejection on every supported
- * engine, never a round infrastructure failure.
+ * Evidence-binding failure for a finding pointer that resolves to the wrong kind
+ * of stored record, lacks a GitHub locator, or has no identity group — not a
+ * free-shape gate on the submission envelope.
  */
 export class CollectorFindingsValidationError extends CorrectableSubmissionError {
   constructor(message: string) {
@@ -133,11 +141,45 @@ export class CollectorFindingsValidationError extends CorrectableSubmissionError
 }
 
 /**
- * #641 chain①: turn model-submitted finding pointer refs into receipt findings.
- * Each pointer must resolve to a stored text-bearing evidence record; the
- * machine locator is enriched from the same record so receipt and volume agree
- * (指针可解析、开卷相符) by construction. Throws branded correctable
- * (non-fatal, model-visible) errors for unresolvable or mis-typed findings.
+ * #676 D6: non-OPEN targets keep collected materials and must not fire new review
+ * requests. Bounce the request as correctable so the seat can still seal output.
+ */
+export class CollectorNonOpenRequestError extends CorrectableSubmissionError {
+  constructor(prState: string) {
+    super(`通进司请求要求 OPEN 状态的 PR 快照；当前为 ${prState}，不再触发新评审，请直接交回已有材料`);
+    this.name = "CollectorNonOpenRequestError";
+  }
+}
+
+function candidateRecord(candidate: unknown): Record<string, unknown> | undefined {
+  if (candidate === undefined || candidate === null || typeof candidate !== "object" || Array.isArray(candidate)) {
+    return undefined;
+  }
+  return candidate as Record<string, unknown>;
+}
+
+/** Canonical top-level keys the collector output projection understands. */
+const COLLECTOR_OUTPUT_CANONICAL_KEYS = new Set([
+  "findings",
+  "unfinishedReasons",
+  "infrastructureFailure",
+]);
+
+/** Non-canonical own keys mean content was present but not under a projectable key. */
+function hasNonCanonicalOwnKeys(record: Record<string, unknown>): boolean {
+  for (const key of Object.keys(record)) {
+    if (!COLLECTOR_OUTPUT_CANONICAL_KEYS.has(key)) return true;
+  }
+  return false;
+}
+
+/**
+ * #641 chain① / #676: turn model-submitted finding pointer refs into receipt findings.
+ * Binds resolvable evidence references only — no pure shape rejection of the
+ * candidate envelope. Unknown refs, wrong kinds, missing GitHub locator, and
+ * missing identity group stay as binding failures. Unreadable findings content
+ * is not washed into "zero findings": projection facts record the gap so
+ * downstream can open the session 正本 (第 0 条 / #676 C).
  */
 export function enrichCollectorFindings(input: {
   candidate: unknown;
@@ -146,63 +188,129 @@ export function enrichCollectorFindings(input: {
   targetHead: string;
   repository: string;
   prNumber: number;
-}): void {
-  const candidate = input.candidate;
-  if (candidate === undefined || candidate === null) return;
-  if (typeof candidate !== "object" || Array.isArray(candidate)) {
-    throw new CollectorFindingsValidationError("通进司交件参数必须为对象");
+}): {
+  findingsSource: CollectorSubmissionProjection["findingsSource"];
+  findingsProjectedCount: number;
+  findingsUnprojected: boolean;
+} {
+  // Candidate present but not a record — content existed, none projected (#676 C).
+  if (input.candidate !== undefined && input.candidate !== null && candidateRecord(input.candidate) === undefined) {
+    return { findingsSource: "unreadable", findingsProjectedCount: 0, findingsUnprojected: true };
+  }
+  const record = candidateRecord(input.candidate);
+  if (record === undefined) {
+    return { findingsSource: "absent", findingsProjectedCount: 0, findingsUnprojected: false };
   }
-  const rawFindings = (candidate as { findings?: unknown }).findings;
-  if (rawFindings === undefined) return;
+  if (!Object.hasOwn(record, "findings")) {
+    // Non-canonical top-level content is not "absent" — record the projection gap (#676 C).
+    if (hasNonCanonicalOwnKeys(record)) {
+      return { findingsSource: "unreadable", findingsProjectedCount: 0, findingsUnprojected: true };
+    }
+    return { findingsSource: "absent", findingsProjectedCount: 0, findingsUnprojected: false };
+  }
+  const rawFindings = record["findings"];
   if (!Array.isArray(rawFindings)) {
-    throw new CollectorFindingsValidationError("通进司 findings 必须为数组");
+    // Key present but not an array — content exists, none projected. No shape bounce.
+    return { findingsSource: "unreadable", findingsProjectedCount: 0, findingsUnprojected: true };
   }
-  const byEvidenceId = new Map(input.records.map((record) => [record.evidenceId, record]));
+
+  const byEvidenceId = new Map(input.records.map((evidence) => [evidence.evidenceId, evidence]));
+  let projected = 0;
+  let unprojected = false;
   for (const raw of rawFindings) {
     if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
-      throw new CollectorFindingsValidationError("通进司 finding 必须为对象");
+      unprojected = true;
+      continue;
     }
-    const evidenceId = (raw as { evidenceId?: unknown }).evidenceId;
+    const item = raw as Record<string, unknown>;
+    const evidenceId = item.evidenceId;
     if (typeof evidenceId !== "string" || evidenceId.length === 0) {
-      throw new CollectorFindingsValidationError("通进司 finding 缺少可解析的 evidenceId 指针");
+      // Present item without a bindable pointer — keep gap fact, do not fabricate.
+      unprojected = true;
+      continue;
     }
-    const record = byEvidenceId.get(evidenceId);
-    if (record === undefined) {
+    const evidence = byEvidenceId.get(evidenceId);
+    if (evidence === undefined) {
       throw new CollectorUnknownEvidenceError(evidenceId);
     }
-    if (record.kind !== "review" && record.kind !== "issue_comment" && record.kind !== "review_comment") {
-      throw new CollectorFindingsValidationError(`通进司 finding 指针指向不可承 finding 的证据种类 ${record.kind}`);
+    if (evidence.kind !== "review" && evidence.kind !== "issue_comment" && evidence.kind !== "review_comment") {
+      throw new CollectorFindingsValidationError(`通进司 finding 指针指向不可承 finding 的证据种类 ${evidence.kind}`);
     }
-    if (record.githubId === undefined) {
+    if (evidence.githubId === undefined) {
       throw new CollectorFindingsValidationError(`通进司 finding 指针证据 ${evidenceId} 缺少 GitHub id`);
     }
-    const category = (raw as { category?: unknown }).category;
-    if (category !== undefined && (typeof category !== "string" || category.trim().length === 0)) {
-      throw new CollectorFindingsValidationError("通进司 finding category 必须为非空字符串");
-    }
-    const identity = record.machineIdentity ?? null;
+    const identity = evidence.machineIdentity ?? null;
     const group = input.groups.find((candidateGroup) => identityKey(candidateGroup.identity) === identityKey(identity));
     if (group === undefined) {
       throw new CollectorFindingsValidationError(`通进司 finding 指针证据 ${evidenceId} 无归属身份组`);
     }
+    // Bound finding keeps pointer; non-string category/summary are unprojected field gaps
+    // (pointer success ≠ full content projection) — #676 C / 3939511832.
+    const category = item.category;
+    const summary = item.summary;
+    if (Object.hasOwn(item, "category") && typeof category !== "string") unprojected = true;
+    if (Object.hasOwn(item, "summary") && typeof summary !== "string") unprojected = true;
     group.findings.push({
       identity,
       source: {
-        kind: record.kind,
-        id: record.githubId,
-        evidenceId: record.evidenceId,
-        headRelation: headRelationFor(record, input.targetHead),
+        kind: evidence.kind,
+        id: evidence.githubId,
+        evidenceId: evidence.evidenceId,
+        headRelation: headRelationFor(evidence, input.targetHead),
       },
-      ...(category === undefined ? {} : { category: category.trim() }),
+      ...(typeof category === "string" ? { category } : {}),
+      ...(typeof summary === "string" ? { summary } : {}),
       pointer: {
         repository: input.repository,
         prNumber: input.prNumber,
-        commentId: record.githubId,
-        ...(record.htmlUrl === undefined ? {} : { htmlUrl: record.htmlUrl }),
-        ...(record.authorLogin === undefined ? {} : { authorLogin: record.authorLogin }),
-        kind: record.kind,
-        authoritativeTime: record.authoritativeTime ?? null,
+        commentId: evidence.githubId,
+        ...(evidence.htmlUrl === undefined ? {} : { htmlUrl: evidence.htmlUrl }),
+        ...(evidence.authorLogin === undefined ? {} : { authorLogin: evidence.authorLogin }),
+        kind: evidence.kind,
+        authoritativeTime: evidence.authoritativeTime ?? null,
+        ...(evidence.commitOid === undefined ? {} : { commitOid: evidence.commitOid }),
       },
     });
+    projected += 1;
+  }
+  return {
+    findingsSource: "array",
+    findingsProjectedCount: projected,
+    findingsUnprojected: unprojected,
+  };
+}
+
+/**
+ * #676 D6/C: optional unfinished reasons from the model submission.
+ * Project readable strings; record when original content could not fully project
+ * (do not wash unreadable unfinishedReasons into "none").
+ */
+export function extractCollectorUnfinishedReasons(candidate: unknown): {
+  reasons: string[] | undefined;
+  source: CollectorSubmissionProjection["unfinishedReasonsSource"];
+  unprojected: boolean;
+} {
+  if (candidate !== undefined && candidate !== null && candidateRecord(candidate) === undefined) {
+    return { reasons: undefined, source: "unreadable", unprojected: true };
+  }
+  const record = candidateRecord(candidate);
+  if (record === undefined) {
+    return { reasons: undefined, source: "absent", unprojected: false };
   }
+  if (!Object.hasOwn(record, "unfinishedReasons")) {
+    // unfinishedReasons absent is fine when only findings (or nothing) present.
+    // Non-canonical keys alone are recorded on the findings projection path.
+    return { reasons: undefined, source: "absent", unprojected: false };
+  }
+  const raw = record["unfinishedReasons"];
+  if (!Array.isArray(raw)) {
+    return { reasons: undefined, source: "unreadable", unprojected: true };
+  }
+  const reasons = raw.filter((item): item is string => typeof item === "string");
+  const unprojected = reasons.length !== raw.length;
+  return {
+    reasons: reasons.length > 0 ? reasons : undefined,
+    source: "array",
+    unprojected,
+  };
 }

package/src/collector-ledger.ts

@@ -25,6 +25,7 @@ import {
   type GitHubPageDiagnostics,
   type GitHubPullRequest,
 } from "./collector-github.ts";
+import { CollectorNonOpenRequestError } from "./collector-identity.ts";
 import {
   collectorObserveArgsSchema,
   collectorOutputArgsSchema,
@@ -38,9 +39,12 @@ export const COLLECTOR_OBSERVE_TOOL = "ak_collector_observe";
 export const COLLECTOR_READ_TOOL = "ak_collector_read";
 export const COLLECTOR_REQUEST_TOOL = "ak_collector_request";
 export const COLLECTOR_WAIT_TOOL = "ak_collector_wait";
+/** #676 A: role-decided target bind — business tool, ledger-booked. */
+export const COLLECTOR_BIND_TARGET_TOOL = "ak_collector_bind_target";
 export { COLLECTOR_OUTPUT_TOOL };
 
 export const COLLECTOR_OPERATIONAL_TOOLS = [
+  COLLECTOR_BIND_TARGET_TOOL,
   COLLECTOR_OBSERVE_TOOL,
   COLLECTOR_READ_TOOL,
   COLLECTOR_REQUEST_TOOL,
@@ -157,7 +161,8 @@ export type CollectorTransportFailure = {
 
 export type CollectorConfigState = {
   repository: CollectorRepository;
-  prNumber: number;
+  /** Bound PR target; undefined until explicit flag, admission bind, or role bind-target tool. */
+  prNumber: number | undefined;
   manifest: CollectorManifest;
 };
 
@@ -195,6 +200,8 @@ export type CollectorLedger = {
   assertNotFatal(): void;
   recordActivation(clock: CollectorClock): void;
   recordOutputCandidate(): void;
+  /** #676 A: role-decided unique PR bind (business fact on the ledger). */
+  bindTarget(prNumber: number): void;
   beginOperational(toolName: string, toolCallId: string): void;
   completeOperational(toolCallId: string): void;
   noteCutoffObserved(): void;
@@ -326,6 +333,15 @@ export function createCollectorLedger(
   const prIdentity = (pr: GitHubPullRequest): string =>
     `${pr.state}|${pr.headOid}|${pr.updatedAt ?? ""}`;
 
+  const requireBoundPr = (): number => {
+    if (config.prNumber === undefined) {
+      throw new Error(
+        "Collector PR target is unbound; call ak_collector_bind_target with the role-decided issue/PR or pass --pr",
+      );
+    }
+    return config.prNumber;
+  };
+
   const fetchObserveSurfaces = async (
     transport: CollectorGitHubTransport,
     observedAt: string,
@@ -333,7 +349,7 @@ export function createCollectorLedger(
   ) => {
     const owner = config.repository.owner;
     const repo = config.repository.repo;
-    const prNumber = config.prNumber;
+    const prNumber = requireBoundPr();
     const signalOpt = signal === undefined ? {} : { signal };
     const user = await transport.getAuthenticatedUser(signalOpt);
     const prInitial = await transport.getPullRequest({
@@ -653,6 +669,26 @@ export function createCollectorLedger(
       outputCandidate = true;
     },
 
+    bindTarget(prNumber) {
+      assertNotFatal();
+      if (outputCandidate || pendingOutputCallId !== undefined) {
+        throw new Error("通进司已产出输出候选，本局不再受理目标绑定");
+      }
+      if (!Number.isSafeInteger(prNumber) || prNumber < 1) {
+        throw new Error("Collector bind target requires a positive safe-integer PR number");
+      }
+      if (config.prNumber !== undefined && config.prNumber !== prNumber) {
+        throw new Error(
+          `Collector target already bound to PR ${config.prNumber}; cannot rebind to ${prNumber}`,
+        );
+      }
+      config.prNumber = prNumber;
+      appendJournal("ak-collector-target-bound", {
+        prNumber,
+        repository: config.repository.canonical,
+      });
+    },
+
     beginOperational(toolName, toolCallId) {
       assertNotFatal();
       if (
@@ -833,7 +869,7 @@ export function createCollectorLedger(
         completedMono,
         host: "github.com",
         repository: config.repository.canonical,
-        prNumber: config.prNumber,
+        prNumber: requireBoundPr(),
         prState: pr.state,
         headOid: pr.headOid,
         complete: true,
@@ -875,10 +911,6 @@ export function createCollectorLedger(
       if (activationTime === undefined || deadlineTime === undefined) {
         throw latchFatal("通进司请求需要激活");
       }
-      if (pastCutoff(clock)) {
-        finalObservationRequired = true;
-        throw latchFatal("通进司请求不在资格截止前");
-      }
       if (ledger.unresolvedTransportFailure) {
         throw latchFatal("通进司请求时存在未恢复的传输失败");
       }
@@ -896,7 +928,12 @@ export function createCollectorLedger(
         throw new Error("通进司请求要求最新完整快照");
       }
       if (snapshot.prState !== "OPEN") {
-        throw latchFatal("通进司请求要求 OPEN 状态的 PR 快照");
+        // #676 D6: non-OPEN keeps materials; bounce before cutoff fatal so post-deadline materials still seal.
+        throw new CollectorNonOpenRequestError(snapshot.prState);
+      }
+      if (pastCutoff(clock)) {
+        finalObservationRequired = true;
+        throw latchFatal("通进司请求不在资格截止前");
       }
 
       const { body, marker } = buildCollectorRequestBody({
@@ -918,9 +955,10 @@ export function createCollectorLedger(
         );
       }
 
+      const boundPr = requireBoundPr();
       const attemptKey = [
         config.repository.canonical,
-        String(config.prNumber),
+        String(boundPr),
         snapshot.headOid,
         request.id,
       ].join("|");
@@ -951,7 +989,7 @@ export function createCollectorLedger(
       const result = await transport.createIssueComment({
         owner: config.repository.owner,
         repo: config.repository.repo,
-        prNumber: config.prNumber,
+        prNumber: boundPr,
         body,
         ...(signal === undefined ? {} : { signal }),
       });