@akagilnc/pi-workflow-roles 0.1.3783 → 0.1.3795

package/src/collector-handbook.ts

@@ -0,0 +1,194 @@
+/**
+ * Collector bot handbook — opaque working memory under the book topology.
+ * Runtime stores and delivers UTF-8 text only; never parses free text into
+ * code state rules (parent #673 D3 / #677).
+ *
+ * Placement reuses the machine ledger home (ADR 0048) when the admitted
+ * session already sits under books/<bookKey>/ — no parallel persistence frame.
+ */
+import { readFile } from "node:fs/promises";
+import { join, sep } from "node:path";
+
+import { writeFileAtomically } from "./atomic-write.ts";
+import {
+  activationBookDirectory,
+  assertLedgerFileInsideHome,
+  ensureRealDirectoryTree,
+  resolveActivationLedgerHomeForPath,
+} from "./activation-ledger-topology.ts";
+import { COLLECTOR_HANDBOOK_MAX_BYTES } from "./collector-tool-schemas.ts";
+
+export type CollectorHandbookScope = "general" | "repo";
+
+export type CollectorHandbookRead = {
+  readonly general: string;
+  readonly repo: string;
+  readonly generalSource: "book" | "seed" | "empty";
+  readonly repoSource: "book" | "empty";
+  readonly generalPath: string;
+  readonly repoPath: string;
+};
+
+export type CollectorHandbookWriteResult = {
+  readonly scope: CollectorHandbookScope;
+  readonly path: string;
+  readonly byteLength: number;
+};
+
+export type CollectorHandbookStore = {
+  readonly root: string;
+  readonly repositoryCanonical: string;
+  read(): Promise<CollectorHandbookRead>;
+  write(scope: CollectorHandbookScope, body: string): Promise<CollectorHandbookWriteResult>;
+};
+
+export type CollectorHandbookPlacement = {
+  readonly ledgerHome: string;
+  readonly bookKey: string;
+  readonly root: string;
+};
+
+/**
+ * Derive handbook root from an admitted session/run path under
+ * `.ak-roles/books/<bookKey>/...`. Fails closed when topology is absent.
+ */
+export function resolveCollectorHandbookRoot(sessionPath: string): CollectorHandbookPlacement {
+  if (typeof sessionPath !== "string" || sessionPath.trim().length === 0) {
+    throw new Error("通进司手册要求非空 session 路径，且位于 books/<bookKey>/");
+  }
+  // Platform path segments only — never rewrite non-separator characters (POSIX `\\` is literal).
+  const segments = sessionPath.split(sep);
+  let bookKey: string | undefined;
+  for (let i = 0; i + 3 < segments.length; i += 1) {
+    if (segments[i] === ".ak-roles" && segments[i + 1] === "books") {
+      const candidate = segments[i + 2]!;
+      // Require a following segment so bookKey is a true path component under books/.
+      if (candidate.length > 0) {
+        bookKey = candidate;
+        break;
+      }
+    }
+  }
+  if (bookKey === undefined) {
+    throw new Error(
+      `通进司手册要求 session 位于 books/<bookKey>/；收到 ${sessionPath}`,
+    );
+  }
+  if (bookKey === "." || bookKey === "..") {
+    throw new Error(`通进司手册拒绝不安全 bookKey ${JSON.stringify(bookKey)}`);
+  }
+  const ledgerHome = resolveActivationLedgerHomeForPath(sessionPath);
+  const root = join(activationBookDirectory(ledgerHome, bookKey), "collector-handbook");
+  return { ledgerHome, bookKey, root };
+}
+
+/** Flat repo file name under handbook/repos/ — avoids nested owner/repo dirs. */
+function collectorHandbookRepoFileName(repositoryCanonical: string): string {
+  if (!/^[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/.test(repositoryCanonical)) {
+    throw new Error(
+      `通进司手册仓库文件要求规范 owner/repo，收到 ${JSON.stringify(repositoryCanonical)}`,
+    );
+  }
+  return `${repositoryCanonical.replaceAll("/", "__")}.md`;
+}
+
+export function createCollectorHandbookStore(input: {
+  readonly ledgerHome: string;
+  readonly handbookRoot: string;
+  readonly repositoryCanonical: string;
+  readonly seedGeneral?: string;
+}): CollectorHandbookStore {
+  const generalPath = join(input.handbookRoot, "general.md");
+  const repoDir = join(input.handbookRoot, "repos");
+  const repoPath = join(repoDir, collectorHandbookRepoFileName(input.repositoryCanonical));
+
+  /**
+   * ADR 0038: confine at the real read seam. Parent dirs must be physical under
+   * ledger home; the leaf must not be a pre-existing symlink (even in-home).
+   */
+  /** Sole UTF-8 budget seam — write and read share COLLECTOR_HANDBOOK_MAX_BYTES. */
+  const assertHandbookBudget = (body: string, label: string): number => {
+    const byteLength = Buffer.byteLength(body, "utf8");
+    if (byteLength > COLLECTOR_HANDBOOK_MAX_BYTES) {
+      throw new Error(
+        `通进司手册${label} UTF-8 至多 ${COLLECTOR_HANDBOOK_MAX_BYTES} 字节，收到 ${byteLength}`,
+      );
+    }
+    return byteLength;
+  };
+
+  const readOptional = async (path: string, parentDir: string): Promise<string | undefined> => {
+    ensureRealDirectoryTree(input.ledgerHome, parentDir);
+    assertLedgerFileInsideHome(path, input.ledgerHome);
+    try {
+      const body = await readFile(path, "utf8");
+      assertHandbookBudget(body, "正文");
+      return body;
+    } catch (error) {
+      if (isNotFound(error)) return undefined;
+      throw error;
+    }
+  };
+
+  return {
+    root: input.handbookRoot,
+    repositoryCanonical: input.repositoryCanonical,
+    async read() {
+      const bookGeneral = await readOptional(generalPath, input.handbookRoot);
+      const bookRepo = await readOptional(repoPath, repoDir);
+      if (bookGeneral !== undefined) {
+        return {
+          general: bookGeneral,
+          repo: bookRepo ?? "",
+          generalSource: "book",
+          repoSource: bookRepo === undefined ? "empty" : "book",
+          generalPath,
+          repoPath,
+        };
+      }
+      const seed = input.seedGeneral;
+      if (typeof seed === "string" && seed.length > 0) {
+        assertHandbookBudget(seed, "正文");
+        return {
+          general: seed,
+          repo: bookRepo ?? "",
+          generalSource: "seed",
+          repoSource: bookRepo === undefined ? "empty" : "book",
+          generalPath,
+          repoPath,
+        };
+      }
+      return {
+        general: "",
+        repo: bookRepo ?? "",
+        generalSource: "empty",
+        repoSource: bookRepo === undefined ? "empty" : "book",
+        generalPath,
+        repoPath,
+      };
+    },
+    async write(scope, body) {
+      // body string shape = collectorHandbookWriteArgsSchema; byte budget is business (UTF-8).
+      const byteLength = assertHandbookBudget(body, "正文");
+      ensureRealDirectoryTree(input.ledgerHome, input.handbookRoot);
+      const path = scope === "general" ? generalPath : repoPath;
+      if (scope === "repo") {
+        ensureRealDirectoryTree(input.ledgerHome, repoDir);
+      }
+      assertLedgerFileInsideHome(path, input.ledgerHome);
+      await writeFileAtomically(path, body);
+      return {
+        scope,
+        path,
+        byteLength,
+      };
+    },
+  };
+}
+
+function isNotFound(error: unknown): boolean {
+  return typeof error === "object"
+    && error !== null
+    && "code" in error
+    && (error as { code?: unknown }).code === "ENOENT";
+}

package/src/collector-identity.ts

@@ -151,6 +151,20 @@ export class CollectorNonOpenRequestError extends CorrectableSubmissionError {
   }
 }
 
+/** #678: wait window not open or already ended — bounce without latching fatal so materials still seal. */
+export class CollectorWaitWindowClosedError extends CorrectableSubmissionError {
+  constructor(action: "request" | "wait" | "wait-before-open") {
+    super(
+      action === "request"
+        ? "通进司请求不在资格截止前"
+        : action === "wait-before-open"
+          ? "通进司等待需要先在工作步骤开启等待窗（新建 PR 用创建成功时刻；已有 PR 在触发阶段结束后开启）"
+          : "通进司等待不在资格截止前",
+    );
+    this.name = "CollectorWaitWindowClosedError";
+  }
+}
+
 function candidateRecord(candidate: unknown): Record<string, unknown> | undefined {
   if (candidate === undefined || candidate === null || typeof candidate !== "object" || Array.isArray(candidate)) {
     return undefined;

package/src/collector-ledger.ts

@@ -1,10 +1,8 @@
-import Value from "typebox/value";
-
 import type { CollectorManifest, CollectorRepository } from "./collector-config.ts";
 import {
   applyEvidenceVersionHistory,
   assignWindowRelations,
-  COLLECTOR_ELIGIBILITY_MS,
+  COLLECTOR_DEFAULT_WAIT_WINDOW_MS,
   measureNormalizedBytes,
   normalizeAuthenticatedUserEvidence,
   normalizeIssueCommentEvidence,
@@ -25,22 +23,22 @@ import {
   type GitHubPageDiagnostics,
   type GitHubPullRequest,
 } from "./collector-github.ts";
-import { CollectorNonOpenRequestError } from "./collector-identity.ts";
 import {
-  collectorObserveArgsSchema,
-  collectorOutputArgsSchema,
-  collectorReadArgsSchema,
-  collectorRequestArgsSchema,
-  collectorWaitArgsSchema,
-} from "./collector-tool-schemas.ts";
+  CollectorNonOpenRequestError,
+  CollectorWaitWindowClosedError,
+} from "./collector-identity.ts";
 import { COLLECTOR_OUTPUT_TOOL } from "./package-contracts/collector-output.ts";
 
 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";
+/** #678 D4: open wait window at a work step — business tool, ledger-booked. */
+export const COLLECTOR_OPEN_WAIT_WINDOW_TOOL = "ak_collector_open_wait_window";
 /** #676 A: role-decided target bind — business tool, ledger-booked. */
 export const COLLECTOR_BIND_TARGET_TOOL = "ak_collector_bind_target";
+/** #677: opaque handbook write — business tool, ledger-booked. */
+export const COLLECTOR_HANDBOOK_WRITE_TOOL = "ak_collector_handbook_write";
 export { COLLECTOR_OUTPUT_TOOL };
 
 export const COLLECTOR_OPERATIONAL_TOOLS = [
@@ -48,7 +46,9 @@ export const COLLECTOR_OPERATIONAL_TOOLS = [
   COLLECTOR_OBSERVE_TOOL,
   COLLECTOR_READ_TOOL,
   COLLECTOR_REQUEST_TOOL,
+  COLLECTOR_OPEN_WAIT_WINDOW_TOOL,
   COLLECTOR_WAIT_TOOL,
+  COLLECTOR_HANDBOOK_WRITE_TOOL,
 ] as const;
 
 /**
@@ -57,7 +57,7 @@ export const COLLECTOR_OPERATIONAL_TOOLS = [
  * (evidenceId + htmlUrl) and is preserved in the volume, never unconditionally
  * transcribed into model context or receipt.
  */
-export const COLLECTOR_OBSERVE_BODY_HEAD_BYTES = 512;
+const COLLECTOR_OBSERVE_BODY_HEAD_BYTES = 512;
 
 function utf8SafePrefix(text: string, maxBytes: number): string {
   if (Buffer.byteLength(text, "utf8") <= maxBytes) return text;
@@ -89,6 +89,8 @@ export type ObserveModelView = {
   completedAt: string;
   prState: string;
   headOid: string;
+  /** PR create success time when known — new-PR wait-window startedAt (#678 D4). */
+  prCreatedAt?: string;
   complete: boolean;
   evidence: ObserveEvidenceEntry[];
   requestAttempts: Array<{
@@ -108,7 +110,7 @@ export type ObserveModelView = {
  * (collector-side; provider-visible observe details carry only this bounded
  * projection), never unconditionally transcribed into model context.
  */
-export function projectObserveContextView(modelView: ObserveModelView): ObserveModelView {
+function projectObserveContextView(modelView: ObserveModelView): ObserveModelView {
   return {
     ...modelView,
     evidence: modelView.evidence.map((entry) =>
@@ -121,9 +123,9 @@ export function projectObserveContextView(modelView: ObserveModelView): ObserveM
 export type CollectorOperationalTool = (typeof COLLECTOR_OPERATIONAL_TOOLS)[number];
 
 export const COLLECTOR_ACTIVATION_ENTRY_TYPE = "ak-collector-activation" as const;
-export const COLLECTOR_SNAPSHOT_ENTRY_TYPE = "ak-collector-snapshot" as const;
-export const COLLECTOR_REQUEST_ENTRY_TYPE = "ak-collector-request" as const;
-export const COLLECTOR_WAIT_ENTRY_TYPE = "ak-collector-wait" as const;
+const COLLECTOR_SNAPSHOT_ENTRY_TYPE = "ak-collector-snapshot" as const;
+const COLLECTOR_REQUEST_ENTRY_TYPE = "ak-collector-request" as const;
+const COLLECTOR_WAIT_ENTRY_TYPE = "ak-collector-wait" as const;
 
 export type CollectorRequestAttempt = {
   attemptId: string;
@@ -164,6 +166,15 @@ export type CollectorConfigState = {
   /** Bound PR target; undefined until explicit flag, admission bind, or role bind-target tool. */
   prNumber: number | undefined;
   manifest: CollectorManifest;
+  /**
+   * Wait window duration (#678 D4). Default 10 minutes; caller-configurable without code change.
+   * Window opens at a work step (PR create success / trigger-phase end), not session activation.
+   */
+  waitWindowMs: number;
+};
+
+export type CollectorLedgerConfigInput = Omit<CollectorConfigState, "waitWindowMs"> & {
+  waitWindowMs?: number;
 };
 
 /** Durable session journal sink owned by the shared execution seam. */
@@ -183,8 +194,11 @@ export type CollectorLedger = {
   readonly fatal: boolean;
   readonly fatalReason: string | undefined;
   readonly outputCandidate: boolean;
+  /** Session ready (before_agent_start); not the wait window. */
   readonly activationRecorded: boolean;
+  /** Wait-window start (receipt activationTime); undefined until openWaitWindow. */
   readonly activationTime: Date | undefined;
+  /** Wait-window end; undefined until openWaitWindow. */
   readonly deadlineTime: Date | undefined;
   readonly activationMono: number | undefined;
   readonly deadlineMono: number | undefined;
@@ -198,7 +212,13 @@ export type CollectorLedger = {
 
   latchFatal(reason: string, cause?: unknown): Error;
   assertNotFatal(): void;
+  /** Mark session ready for prep observe/request; does not open the wait window (#678). */
   recordActivation(clock: CollectorClock): void;
+  /**
+   * Open the wait window once at a work step. Optional startedAt covers new-PR create success;
+   * omit for existing-PR trigger-phase end (= now). Second call is a no-op (D6: updates do not reset).
+   */
+  openWaitWindow(clock: CollectorClock, options?: { startedAt?: Date }): void;
   recordOutputCandidate(): void;
   /** #676 A: role-decided unique PR bind (business fact on the ledger). */
   bindTarget(prNumber: number): void;
@@ -217,7 +237,7 @@ export type CollectorLedger = {
   }>;
 
   request(
-    input: { requestId: string; snapshotId: string },
+    input: { requestId: string; snapshotId: string; body?: string },
     transport: CollectorGitHubTransport,
     clock: CollectorClock,
     signal?: AbortSignal,
@@ -243,39 +263,31 @@ function isOperationalTool(name: string): name is CollectorOperationalTool {
   return (COLLECTOR_OPERATIONAL_TOOLS as readonly string[]).includes(name);
 }
 
-/** Shared Check owner for Collector tool argument shapes (schema seam, not batch law). */
-export function collectorToolArgumentsValid(
-  name: string,
-  args: unknown,
-): boolean {
-  // Residual envelope: reject missing/null args before schema check.
-  if (args === undefined || args === null) return false;
-  switch (name) {
-    case COLLECTOR_OBSERVE_TOOL:
-      return Value.Check(collectorObserveArgsSchema, args);
-    case COLLECTOR_READ_TOOL:
-      return Value.Check(collectorReadArgsSchema, args);
-    case COLLECTOR_REQUEST_TOOL:
-      return Value.Check(collectorRequestArgsSchema, args);
-    case COLLECTOR_WAIT_TOOL:
-      return Value.Check(collectorWaitArgsSchema, args);
-    case COLLECTOR_OUTPUT_TOOL:
-      return Value.Check(collectorOutputArgsSchema, args);
-    default:
-      return false;
+function resolveWaitWindowMs(raw: number | undefined): number {
+  if (raw === undefined) return COLLECTOR_DEFAULT_WAIT_WINDOW_MS;
+  if (!Number.isSafeInteger(raw) || raw < 1) {
+    throw new Error("通进司 waitWindowMs 须为正安全整数毫秒");
   }
+  return raw;
 }
 
 export function createCollectorLedger(
-  config: CollectorConfigState,
+  input: CollectorLedgerConfigInput,
   options?: CollectorLedgerOptions,
 ): CollectorLedger {
+  const config: CollectorConfigState = {
+    repository: input.repository,
+    prNumber: input.prNumber,
+    manifest: input.manifest,
+    waitWindowMs: resolveWaitWindowMs(input.waitWindowMs),
+  };
   const clock = options?.clock;
   const journal = options?.journal;
   let fatal = false;
   let fatalReason: string | undefined;
   let outputCandidate = false;
   let pendingOutputCallId: string | undefined;
+  let sessionReady = false;
   let activationTime: Date | undefined;
   let deadlineTime: Date | undefined;
   let activationMono: number | undefined;
@@ -326,7 +338,7 @@ export function createCollectorLedger(
   };
 
   const remainingMs = (clock: CollectorClock): number => {
-    if (deadlineMono === undefined) return COLLECTOR_ELIGIBILITY_MS;
+    if (deadlineMono === undefined) return config.waitWindowMs;
     return Math.max(0, deadlineMono - monoNowOrThrow(clock));
   };
 
@@ -335,9 +347,7 @@ export function createCollectorLedger(
 
   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",
-      );
+      throw new Error("通进司 PR 目标未绑定");
     }
     return config.prNumber;
   };
@@ -411,7 +421,9 @@ export function createCollectorLedger(
   };
 
   const commitActivationWindow = (nextActivation: Date, nextDeadline: Date): void => {
+    // D6: once open, PR updates / second open must not reset the window.
     if (activationTime !== undefined) return;
+    sessionReady = true;
     activationTime = nextActivation;
     deadlineTime = nextDeadline;
     bindDeadlineMonoFromWall();
@@ -551,6 +563,8 @@ export function createCollectorLedger(
       if (entry.customType === COLLECTOR_ACTIVATION_ENTRY_TYPE) {
         if (typeof data.activationTime === "string" && typeof data.deadlineTime === "string") {
           commitActivationWindow(new Date(data.activationTime), new Date(data.deadlineTime));
+        } else if (data.sessionReady === true) {
+          sessionReady = true;
         }
         continue;
       }
@@ -612,7 +626,7 @@ export function createCollectorLedger(
       return outputCandidate || pendingOutputCallId !== undefined;
     },
     get activationRecorded() {
-      return activationTime !== undefined;
+      return sessionReady;
     },
     get activationTime() {
       return activationTime;
@@ -651,16 +665,38 @@ export function createCollectorLedger(
     latchFatal,
     assertNotFatal,
 
-    recordActivation(clock) {
+    recordActivation(_clock) {
+      assertNotFatal();
+      if (sessionReady) return;
+      sessionReady = true;
+      // Session ready only — wait window opens later at a work step (#678 D4).
+      appendJournal(COLLECTOR_ACTIVATION_ENTRY_TYPE, {
+        sessionReady: true,
+      });
+    },
+
+    openWaitWindow(clock, options) {
       assertNotFatal();
-      if (activationTime !== undefined) return;
-      activationTime = clock.wallNow();
-      activationMono = clock.monoNow();
-      deadlineTime = new Date(activationTime.getTime() + COLLECTOR_ELIGIBILITY_MS);
-      deadlineMono = activationMono + COLLECTOR_ELIGIBILITY_MS;
+      if (!sessionReady) {
+        throw latchFatal("通进司开启等待窗需要先激活会话");
+      }
+      if (activationTime !== undefined) return; // D6: do not reset
+      const startedAt = options?.startedAt ?? clock.wallNow();
+      if (!(startedAt instanceof Date) || Number.isNaN(startedAt.getTime())) {
+        throw new Error("通进司等待窗 startedAt 须为有效时间");
+      }
+      const nextDeadline = new Date(startedAt.getTime() + config.waitWindowMs);
+      // Bind mono relative to current clock so a past startedAt shortens remaining correctly.
+      activationTime = startedAt;
+      deadlineTime = nextDeadline;
+      const wallNow = clock.wallNow().getTime();
+      const monoNow = clock.monoNow();
+      activationMono = monoNow - (wallNow - startedAt.getTime());
+      deadlineMono = monoNow + (nextDeadline.getTime() - wallNow);
       appendJournal(COLLECTOR_ACTIVATION_ENTRY_TYPE, {
         activationTime: activationTime.toISOString(),
         deadlineTime: deadlineTime.toISOString(),
+        waitWindowMs: config.waitWindowMs,
       });
     },
 
@@ -675,11 +711,11 @@ export function createCollectorLedger(
         throw new Error("通进司已产出输出候选，本局不再受理目标绑定");
       }
       if (!Number.isSafeInteger(prNumber) || prNumber < 1) {
-        throw new Error("Collector bind target requires a positive safe-integer PR number");
+        throw new Error("通进司绑定目标要求正安全整数 PR 号");
       }
       if (config.prNumber !== undefined && config.prNumber !== prNumber) {
         throw new Error(
-          `Collector target already bound to PR ${config.prNumber}; cannot rebind to ${prNumber}`,
+          `通进司目标已绑定 PR ${config.prNumber}，不可改绑为 ${prNumber}`,
         );
       }
       config.prNumber = prNumber;
@@ -764,7 +800,7 @@ export function createCollectorLedger(
 
     async observe(transport, clock, signal) {
       assertNotFatal();
-      if (activationTime === undefined) {
+      if (!sessionReady) {
         throw latchFatal("通进司观察需要激活");
       }
       if (signal?.aborted) {
@@ -872,6 +908,7 @@ export function createCollectorLedger(
         prNumber: requireBoundPr(),
         prState: pr.state,
         headOid: pr.headOid,
+        ...(pr.createdAt === undefined ? {} : { prCreatedAt: pr.createdAt }),
         complete: true,
         evidenceIds: storedIds,
         pageDiagnostics,
@@ -908,16 +945,32 @@ export function createCollectorLedger(
 
     async request(input, transport, clock, signal) {
       assertNotFatal();
-      if (activationTime === undefined || deadlineTime === undefined) {
+      if (!sessionReady) {
         throw latchFatal("通进司请求需要激活");
       }
       if (ledger.unresolvedTransportFailure) {
         throw latchFatal("通进司请求时存在未恢复的传输失败");
       }
 
-      const request = config.manifest.requests.find((item) => item.id === input.requestId);
-      if (request === undefined) {
-        throw new Error(`未知通进司 requestId "${input.requestId}"`);
+      // Sole request identity seam: trim once, then use everywhere (lookup/marker/attemptKey).
+      // Schema pattern rejects leading/trailing whitespace at host; trim still collapses
+      // direct ledger callers and any residual padding into one stable id (#677 D2).
+      if (typeof input.requestId !== "string") {
+        throw new Error("通进司 requestId 须为字符串");
+      }
+      const requestId = input.requestId.trim();
+      if (requestId.length === 0) {
+        throw new Error("通进司 requestId 须为非空（首尾空白不构成身份）");
+      }
+      const configured = config.manifest.requests.find((item) => item.id === requestId);
+      const roleBody = typeof input.body === "string" ? input.body : undefined;
+      if (configured === undefined) {
+        // #677: role-decided trigger from handbook/field activity — body required when not in manifest.
+        if (roleBody === undefined || roleBody.trim().length === 0) {
+          throw new Error(
+            `未知通进司 requestId "${requestId}" 且未提供 body；请提交角色判定的请求正文或使用 request-manifest`,
+          );
+        }
       }
 
       const snapshot = snapshots.find((item) => item.snapshotId === input.snapshotId);
@@ -933,13 +986,16 @@ export function createCollectorLedger(
       }
       if (pastCutoff(clock)) {
         finalObservationRequired = true;
-        throw latchFatal("通进司请求不在资格截止前");
+        // #678: do not latch fatal — materials must still seal after the window ends.
+        throw new CollectorWaitWindowClosedError("request");
       }
 
+      // Caller manifest body wins when requestId is configured; otherwise role body.
+      const configuredBody = configured?.requestBody ?? roleBody!;
       const { body, marker } = buildCollectorRequestBody({
-        configuredBody: request.requestBody,
+        configuredBody,
         manifestDigest: config.manifest.digest,
-        requestId: request.id,
+        requestId,
         headOid: snapshot.headOid,
       });
       const existingMarker = snapshot.evidenceIds.some((id) => {
@@ -951,7 +1007,7 @@ export function createCollectorLedger(
       });
       if (existingMarker) {
         throw new Error(
-          `通进司在此 HEAD 已有同 marker 的已认证请求 "${input.requestId}"`,
+          `通进司在此 HEAD 已有同 marker 的已认证请求 "${requestId}"`,
         );
       }
 
@@ -960,11 +1016,11 @@ export function createCollectorLedger(
         config.repository.canonical,
         String(boundPr),
         snapshot.headOid,
-        request.id,
+        requestId,
       ].join("|");
       if (attemptKeys.has(attemptKey)) {
         throw new Error(
-          `通进司进程内请求 "${request.id}" 在 HEAD ${snapshot.headOid} 的 attempt 已用`,
+          `通进司进程内请求 "${requestId}" 在 HEAD ${snapshot.headOid} 的 attempt 已用`,
         );
       }
 
@@ -972,7 +1028,7 @@ export function createCollectorLedger(
       const attemptId = sha256Text(`${attemptKey}:${startedAt}`).slice(0, 16);
       const attempt: CollectorRequestAttempt = {
         attemptId,
-        requestId: request.id,
+        requestId,
         observedHead: snapshot.headOid,
         snapshotId: snapshot.snapshotId,
         marker,
@@ -1017,7 +1073,7 @@ export function createCollectorLedger(
         return {
           status: "succeeded",
           attemptId,
-          requestId: request.id,
+          requestId,
           observedHead: snapshot.headOid,
           marker,
           commentEvidenceId: record.evidenceId,
@@ -1032,7 +1088,7 @@ export function createCollectorLedger(
         return {
           status: "ambiguous_loss",
           attemptId,
-          requestId: request.id,
+          requestId,
           observedHead: snapshot.headOid,
           marker,
           diagnostics: result.diagnostics,
@@ -1048,30 +1104,23 @@ export function createCollectorLedger(
 
     async wait(input, clock, signal) {
       assertNotFatal();
-      if (activationTime === undefined) {
+      if (!sessionReady) {
         throw latchFatal("通进司等待需要激活");
       }
-      if (!Number.isSafeInteger(input.durationMs) || input.durationMs < 1) {
-        throw new Error("通进司等待 durationMs 须为正安全整数");
-      }
-      if (input.durationMs > COLLECTOR_ELIGIBILITY_MS) {
-        throw new Error(
-          `通进司等待 durationMs 至多为 ${COLLECTOR_ELIGIBILITY_MS}`,
-        );
+      // #678: wait never invents a window start. Work-step open (create-success / trigger-end)
+      // must be explicit — silent "now" would break the new-PR create-success clock.
+      if (activationTime === undefined || deadlineTime === undefined) {
+        throw new CollectorWaitWindowClosedError("wait-before-open");
       }
+      // durationMs shape authority = collectorWaitArgsSchema (host parameters).
       if (pastCutoff(clock)) {
         finalObservationRequired = true;
-        throw latchFatal("通进司等待不在资格截止前");
+        throw new CollectorWaitWindowClosedError("wait");
       }
 
       const remaining = remainingMs(clock);
-      // Single-wait runtime cadence cap (v2 §6 / §9); schema max stays 15m.
-      const COLLECTOR_SINGLE_WAIT_MAX_MS = 300_000;
-      const effectiveMs = Math.min(
-        input.durationMs,
-        remaining,
-        COLLECTOR_SINGLE_WAIT_MAX_MS,
-      );
+      // Cap only by remaining window — no package-local single-wait ceiling (ADR 0035 / #678).
+      const effectiveMs = Math.min(input.durationMs, remaining);
       const startedAt = clock.wallNow().toISOString();
       const waitId = sha256Text(`wait:${startedAt}:${effectiveMs}`).slice(0, 16);
       await clock.sleep(effectiveMs, signal);
@@ -1163,6 +1212,9 @@ function buildObserveModelView(input: {
     completedAt: input.snapshot.completedAt,
     prState: input.snapshot.prState,
     headOid: input.snapshot.headOid,
+    ...(input.snapshot.prCreatedAt === undefined
+      ? {}
+      : { prCreatedAt: input.snapshot.prCreatedAt }),
     complete: input.snapshot.complete,
     evidence: relevant.map((record): ObserveEvidenceEntry => projectEvidenceEntryView(record)),
     requestAttempts: input.attempts.map((attempt) => ({