@akagilnc/pi-workflow-roles 0.1.3789 → 0.1.3797

package/README.md

@@ -92,9 +92,11 @@ ak-role coder apply --attach ./plan.md "Implement the approved slice."
 # reviewer — fixed-target two-axis review; completed ≠ approved, read the findings
 ak-role reviewer --base main "Review the branch."
 
-# collector — GitHub PR review evidence (bind target, read handbook/field activity, trigger as needed, return materials)
+# collector — GitHub PR review evidence (bind target, read handbook/field activity, trigger as needed, wait window, return materials)
 ak-role collector --pr 42 --repo owner/repository "Collect findings for the assigned issue."
 ak-role collector --repo owner/repository "Collect findings for #42"
+# optional: wait-window ms after the work step opens (default 600000 = 10 minutes)
+ak-role collector --pr 42 --repo owner/repository --wait-ms 120000 "Collect with a 2-minute window."
 
 # fixer — repair the assigned findings
 ak-role fixer --attach ./findings.md --prerequisites ./prereqs.json "Repair the findings."

package/README.zh-CN.md

@@ -86,9 +86,11 @@ ak-role coder apply --attach ./plan.md "Implement the approved slice."
 # 御史台——固定目标双轴察举；completed ≠ 准行，findings 在 Terminal 里
 ak-role reviewer --base main "Review the branch."
 
-# 通进司——GitHub PR 收证（认票、读手册/现场活动、按需触发、交回材料）
+# 通进司——GitHub PR 收证（认票、读手册/现场活动、按需触发、等待窗、交回材料）
 ak-role collector --pr 42 --repo owner/repository "为所指 issue 收证。"
 ak-role collector --repo owner/repository "为 #42 收证。"
+# 可选：工作步骤开启后的等待窗毫秒（默认 600000＝十分钟）
+ak-role collector --pr 42 --repo owner/repository --wait-ms 120000 "两分钟窗收证。"
 
 # 修内司——缮修所指 findings
 ak-role fixer --attach ./findings.md --prerequisites ./prereqs.json "Repair the findings."

package/dist/acp-host/production-host.js

@@ -348,6 +348,7 @@ function normalizePullRequest(raw) {
     number,
     state,
     headOid: head["sha"],
+    ...typeof raw["created_at"] === "string" ? { createdAt: raw["created_at"] } : {},
     ...typeof raw["updated_at"] === "string" ? { updatedAt: raw["updated_at"] } : {},
     url: htmlUrl,
     raw
@@ -1982,7 +1983,8 @@ function buildActivationFlagArgs(activation) {
         "--ak-collector-repo",
         activation.repo,
         ...activation.pr === void 0 ? [] : ["--ak-collector-pr", activation.pr],
-        ...activation.requestManifestPath === void 0 ? [] : ["--ak-collector-request-manifest", activation.requestManifestPath]
+        ...activation.requestManifestPath === void 0 ? [] : ["--ak-collector-request-manifest", activation.requestManifestPath],
+        ...activation.waitMs === void 0 ? [] : ["--ak-collector-wait-ms", activation.waitMs]
       ];
     case "doctor":
       return ["--ak-role", "doctor", "--ak-doctor-case", activation.casePath];
@@ -5104,6 +5106,7 @@ async function loadResumableRunRecord(home, runId, authority) {
   let repositoryDisplay;
   let requestManifestPath;
   let manifestDigest;
+  let waitWindowMs;
   let issueNumber;
   let caseRunsPath;
   let caseIdentity2;
@@ -5157,6 +5160,9 @@ async function loadResumableRunRecord(home, runId, authority) {
       if (typeof record4.manifestDigest === "string" && record4.manifestDigest.trim() !== "") {
         manifestDigest = record4.manifestDigest;
       }
+      if (typeof record4.waitWindowMs === "number" && Number.isSafeInteger(record4.waitWindowMs) && record4.waitWindowMs >= 1) {
+        waitWindowMs = record4.waitWindowMs;
+      }
       if (typeof record4.issueNumber === "number" && Number.isSafeInteger(record4.issueNumber) && record4.issueNumber >= 1) {
         issueNumber = record4.issueNumber;
       }
@@ -5272,6 +5278,7 @@ async function loadResumableRunRecord(home, runId, authority) {
       ...repositoryDisplay === void 0 ? {} : { repositoryDisplay },
       ...requestManifestPath === void 0 ? {} : { requestManifestPath },
       ...manifestDigest === void 0 ? {} : { manifestDigest },
+      ...waitWindowMs === void 0 ? {} : { waitWindowMs },
       ...issueNumber === void 0 ? {} : { issueNumber },
       ...caseRunsPath === void 0 ? {} : { caseRunsPath },
       ...caseIdentity2 === void 0 ? {} : { caseIdentity: caseIdentity2 },
@@ -6088,6 +6095,20 @@ var init_option_definitions = __esm({
           en: "Optional request manifest JSON path ({requests:[{id,body}]}). Role may also decide request bodies from handbook/field activity without this file.",
           zh: "\u53EF\u9009 request manifest JSON \u8DEF\u5F84\uFF08{requests:[{id,body}]}\uFF09\u3002\u89D2\u8272\u4EA6\u53EF\u4F9D\u624B\u518C/\u73B0\u573A\u81EA\u884C\u5224\u5B9A\u8BF7\u6C42\u6B63\u6587\uFF0C\u4E0D\u5FC5\u4F9D\u8D56\u672C\u6587\u4EF6\u3002"
         }
+      },
+      {
+        id: "wait-ms",
+        owner: "collector",
+        canonical: "--wait-ms",
+        aliases: [],
+        valueMetavar: "ms",
+        required: false,
+        repeatable: false,
+        form: "option",
+        description: {
+          en: "Wait-window duration in milliseconds after the work step opens (default 600000 = 10 minutes). Does not require a code change to adjust.",
+          zh: "\u5DE5\u4F5C\u6B65\u9AA4\u5F00\u542F\u540E\u7684\u7B49\u5F85\u7A97\u65F6\u957F\uFF08\u6BEB\u79D2\uFF1B\u9ED8\u8BA4 600000\uFF1D\u5341\u5206\u949F\uFF09\u3002\u6539\u914D\u7F6E\u5373\u53EF\uFF0C\u65E0\u9700\u6539\u4EE3\u7801\u3002"
+        }
       }
     ];
     DOCTOR_OPTIONS = [
@@ -7500,6 +7521,7 @@ function parseCollectorArgv(args) {
   let repo;
   let prNumber;
   let requestManifestPath;
+  let waitWindowMs;
   const positional = [];
   const tokens = [...args];
   const definitions = roleOptions("collector");
@@ -7532,6 +7554,17 @@ function parseCollectorArgv(args) {
         requestManifestPath = requireOptionPath(taken.def.canonical, taken.value);
         continue;
       }
+      if (taken.def.id === "wait-ms") {
+        if (taken.value === void 0 || !/^[1-9]\d*$/.test(taken.value.trim())) {
+          throw new CliUsageError("--wait-ms requires a positive safe-integer millisecond value");
+        }
+        const parsed = Number(taken.value.trim());
+        if (!Number.isSafeInteger(parsed) || parsed < 1) {
+          throw new CliUsageError("--wait-ms requires a positive safe-integer millisecond value");
+        }
+        waitWindowMs = parsed;
+        continue;
+      }
       throw new CliUsageError(`unknown collector option: ${taken.def.canonical}`);
     }
     const token = tokens.shift();
@@ -7547,7 +7580,8 @@ function parseCollectorArgv(args) {
     attachmentPaths,
     ...project === void 0 ? {} : { project },
     ...repo === void 0 ? {} : { repo },
-    ...requestManifestPath === void 0 ? {} : { requestManifestPath }
+    ...requestManifestPath === void 0 ? {} : { requestManifestPath },
+    ...waitWindowMs === void 0 ? {} : { waitWindowMs }
   };
 }
 function resolveGitHubRemoteRepository(projectRoot) {
@@ -7672,6 +7706,7 @@ async function admitCollectorInvocation(options) {
     repository: repository.canonical,
     repositoryDisplay: repository.display,
     ...requestManifestPath === void 0 ? {} : { requestManifestPath },
+    ...options.waitWindowMs === void 0 ? {} : { waitWindowMs: options.waitWindowMs },
     manifestDigest,
     attachments: attachments.map((a) => ({
       provenancePath: a.provenancePath,
@@ -7701,6 +7736,7 @@ async function admitCollectorInvocation(options) {
     ...prNumber === void 0 ? {} : { prNumber },
     repository,
     ...requestManifestPath === void 0 ? {} : { requestManifestPath },
+    ...options.waitWindowMs === void 0 ? {} : { waitWindowMs: options.waitWindowMs },
     manifestDigest
   };
 }
@@ -12094,6 +12130,7 @@ function normalizePullRequestEvidence(pr, observedAt) {
     number: pr.number,
     state: pr.state,
     headOid: pr.headOid,
+    createdAt: pr.createdAt ?? null,
     updatedAt: pr.updatedAt ?? null,
     htmlUrl: pr.url
   });
@@ -12107,6 +12144,7 @@ function normalizePullRequestEvidence(pr, observedAt) {
     state: pr.state,
     commitOid: pr.headOid,
     htmlUrl: pr.url,
+    // Version clock stays updatedAt. Create success for the wait window is snapshot.prCreatedAt only (#678).
     authoritativeTime: pr.updatedAt ?? null,
     firstObservedAt: observedAt,
     raw: pr.raw
@@ -12304,11 +12342,11 @@ function assignWindowRelations(records2, activationTime, deadlineTime) {
     }
   }
 }
-var COLLECTOR_ELIGIBILITY_MS;
+var COLLECTOR_DEFAULT_WAIT_WINDOW_MS;
 var init_collector_evidence = __esm({
   "src/collector-evidence.ts"() {
     "use strict";
-    COLLECTOR_ELIGIBILITY_MS = 15 * 60 * 1e3;
+    COLLECTOR_DEFAULT_WAIT_WINDOW_MS = 10 * 60 * 1e3;
   }
 });
 
@@ -12473,7 +12511,7 @@ function extractCollectorUnfinishedReasons(candidate) {
     unprojected
   };
 }
-var CollectorUnknownEvidenceError, CollectorFindingsValidationError, CollectorNonOpenRequestError, COLLECTOR_OUTPUT_CANONICAL_KEYS;
+var CollectorUnknownEvidenceError, CollectorFindingsValidationError, CollectorNonOpenRequestError, CollectorWaitWindowClosedError, COLLECTOR_OUTPUT_CANONICAL_KEYS;
 var init_collector_identity = __esm({
   "src/collector-identity.ts"() {
     "use strict";
@@ -12496,6 +12534,14 @@ var init_collector_identity = __esm({
         this.name = "CollectorNonOpenRequestError";
       }
     };
+    CollectorWaitWindowClosedError = class extends CorrectableSubmissionError {
+      constructor(action) {
+        super(
+          action === "request" ? "\u901A\u8FDB\u53F8\u8BF7\u6C42\u4E0D\u5728\u8D44\u683C\u622A\u6B62\u524D" : action === "wait-before-open" ? "\u901A\u8FDB\u53F8\u7B49\u5F85\u9700\u8981\u5148\u5728\u5DE5\u4F5C\u6B65\u9AA4\u5F00\u542F\u7B49\u5F85\u7A97\uFF08\u65B0\u5EFA PR \u7528\u521B\u5EFA\u6210\u529F\u65F6\u523B\uFF1B\u5DF2\u6709 PR \u5728\u89E6\u53D1\u9636\u6BB5\u7ED3\u675F\u540E\u5F00\u542F\uFF09" : "\u901A\u8FDB\u53F8\u7B49\u5F85\u4E0D\u5728\u8D44\u683C\u622A\u6B62\u524D"
+        );
+        this.name = "CollectorWaitWindowClosedError";
+      }
+    };
     COLLECTOR_OUTPUT_CANONICAL_KEYS = /* @__PURE__ */ new Set([
       "findings",
       "unfinishedReasons",
@@ -12521,13 +12567,27 @@ function projectObserveContextView(modelView) {
 function isOperationalTool(name) {
   return COLLECTOR_OPERATIONAL_TOOLS.includes(name);
 }
-function createCollectorLedger(config, options) {
+function resolveWaitWindowMs(raw) {
+  if (raw === void 0) return COLLECTOR_DEFAULT_WAIT_WINDOW_MS;
+  if (!Number.isSafeInteger(raw) || raw < 1) {
+    throw new Error("\u901A\u8FDB\u53F8 waitWindowMs \u987B\u4E3A\u6B63\u5B89\u5168\u6574\u6570\u6BEB\u79D2");
+  }
+  return raw;
+}
+function createCollectorLedger(input, options) {
+  const config = {
+    repository: input.repository,
+    prNumber: input.prNumber,
+    manifest: input.manifest,
+    waitWindowMs: resolveWaitWindowMs(input.waitWindowMs)
+  };
   const clock = options?.clock;
   const journal = options?.journal;
   let fatal2 = false;
   let fatalReason;
   let outputCandidate = false;
   let pendingOutputCallId;
+  let sessionReady = false;
   let activationTime;
   let deadlineTime;
   let activationMono;
@@ -12571,7 +12631,7 @@ function createCollectorLedger(config, options) {
     return monoNowOrThrow(clock2) >= deadlineMono;
   };
   const remainingMs = (clock2) => {
-    if (deadlineMono === void 0) return COLLECTOR_ELIGIBILITY_MS;
+    if (deadlineMono === void 0) return config.waitWindowMs;
     return Math.max(0, deadlineMono - monoNowOrThrow(clock2));
   };
   const prIdentity = (pr) => `${pr.state}|${pr.headOid}|${pr.updatedAt ?? ""}`;
@@ -12640,6 +12700,7 @@ function createCollectorLedger(config, options) {
   };
   const commitActivationWindow = (nextActivation, nextDeadline) => {
     if (activationTime !== void 0) return;
+    sessionReady = true;
     activationTime = nextActivation;
     deadlineTime = nextDeadline;
     bindDeadlineMonoFromWall();
@@ -12747,6 +12808,8 @@ function createCollectorLedger(config, options) {
       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;
       }
@@ -12800,7 +12863,7 @@ function createCollectorLedger(config, options) {
       return outputCandidate || pendingOutputCallId !== void 0;
     },
     get activationRecorded() {
-      return activationTime !== void 0;
+      return sessionReady;
     },
     get activationTime() {
       return activationTime;
@@ -12837,16 +12900,35 @@ function createCollectorLedger(config, options) {
     },
     latchFatal,
     assertNotFatal,
-    recordActivation(clock2) {
+    recordActivation(_clock) {
       assertNotFatal();
+      if (sessionReady) return;
+      sessionReady = true;
+      appendJournal(COLLECTOR_ACTIVATION_ENTRY_TYPE, {
+        sessionReady: true
+      });
+    },
+    openWaitWindow(clock2, options2) {
+      assertNotFatal();
+      if (!sessionReady) {
+        throw latchFatal("\u901A\u8FDB\u53F8\u5F00\u542F\u7B49\u5F85\u7A97\u9700\u8981\u5148\u6FC0\u6D3B\u4F1A\u8BDD");
+      }
       if (activationTime !== void 0) return;
-      activationTime = clock2.wallNow();
-      activationMono = clock2.monoNow();
-      deadlineTime = new Date(activationTime.getTime() + COLLECTOR_ELIGIBILITY_MS);
-      deadlineMono = activationMono + COLLECTOR_ELIGIBILITY_MS;
+      const startedAt = options2?.startedAt ?? clock2.wallNow();
+      if (!(startedAt instanceof Date) || Number.isNaN(startedAt.getTime())) {
+        throw new Error("\u901A\u8FDB\u53F8\u7B49\u5F85\u7A97 startedAt \u987B\u4E3A\u6709\u6548\u65F6\u95F4");
+      }
+      const nextDeadline = new Date(startedAt.getTime() + config.waitWindowMs);
+      activationTime = startedAt;
+      deadlineTime = nextDeadline;
+      const wallNow = clock2.wallNow().getTime();
+      const monoNow = clock2.monoNow();
+      activationMono = monoNow - (wallNow - startedAt.getTime());
+      deadlineMono = monoNow + (nextDeadline.getTime() - wallNow);
       appendJournal(COLLECTOR_ACTIVATION_ENTRY_TYPE, {
         activationTime: activationTime.toISOString(),
-        deadlineTime: deadlineTime.toISOString()
+        deadlineTime: deadlineTime.toISOString(),
+        waitWindowMs: config.waitWindowMs
       });
     },
     recordOutputCandidate() {
@@ -12934,7 +13016,7 @@ function createCollectorLedger(config, options) {
     },
     async observe(transport, clock2, signal) {
       assertNotFatal();
-      if (activationTime === void 0) {
+      if (!sessionReady) {
         throw latchFatal("\u901A\u8FDB\u53F8\u89C2\u5BDF\u9700\u8981\u6FC0\u6D3B");
       }
       if (signal?.aborted) {
@@ -13021,6 +13103,7 @@ function createCollectorLedger(config, options) {
         prNumber: requireBoundPr(),
         prState: pr.state,
         headOid: pr.headOid,
+        ...pr.createdAt === void 0 ? {} : { prCreatedAt: pr.createdAt },
         complete: true,
         evidenceIds: storedIds,
         pageDiagnostics,
@@ -13052,23 +13135,23 @@ function createCollectorLedger(config, options) {
         contextView: projectObserveContextView(modelView)
       };
     },
-    async request(input, transport, clock2, signal) {
+    async request(input2, transport, clock2, signal) {
       assertNotFatal();
-      if (activationTime === void 0 || deadlineTime === void 0) {
+      if (!sessionReady) {
         throw latchFatal("\u901A\u8FDB\u53F8\u8BF7\u6C42\u9700\u8981\u6FC0\u6D3B");
       }
       if (ledger.unresolvedTransportFailure) {
         throw latchFatal("\u901A\u8FDB\u53F8\u8BF7\u6C42\u65F6\u5B58\u5728\u672A\u6062\u590D\u7684\u4F20\u8F93\u5931\u8D25");
       }
-      if (typeof input.requestId !== "string") {
+      if (typeof input2.requestId !== "string") {
         throw new Error("\u901A\u8FDB\u53F8 requestId \u987B\u4E3A\u5B57\u7B26\u4E32");
       }
-      const requestId = input.requestId.trim();
+      const requestId = input2.requestId.trim();
       if (requestId.length === 0) {
         throw new Error("\u901A\u8FDB\u53F8 requestId \u987B\u4E3A\u975E\u7A7A\uFF08\u9996\u5C3E\u7A7A\u767D\u4E0D\u6784\u6210\u8EAB\u4EFD\uFF09");
       }
       const configured = config.manifest.requests.find((item) => item.id === requestId);
-      const roleBody = typeof input.body === "string" ? input.body : void 0;
+      const roleBody = typeof input2.body === "string" ? input2.body : void 0;
       if (configured === void 0) {
         if (roleBody === void 0 || roleBody.trim().length === 0) {
           throw new Error(
@@ -13076,9 +13159,9 @@ function createCollectorLedger(config, options) {
           );
         }
       }
-      const snapshot = snapshots.find((item) => item.snapshotId === input.snapshotId);
+      const snapshot = snapshots.find((item) => item.snapshotId === input2.snapshotId);
       if (snapshot === void 0) {
-        throw new Error(`\u672A\u77E5\u901A\u8FDB\u53F8 snapshotId "${input.snapshotId}"`);
+        throw new Error(`\u672A\u77E5\u901A\u8FDB\u53F8 snapshotId "${input2.snapshotId}"`);
       }
       if (snapshot.snapshotId !== latestCompleteSnapshotId) {
         throw new Error("\u901A\u8FDB\u53F8\u8BF7\u6C42\u8981\u6C42\u6700\u65B0\u5B8C\u6574\u5FEB\u7167");
@@ -13088,7 +13171,7 @@ function createCollectorLedger(config, options) {
       }
       if (pastCutoff(clock2)) {
         finalObservationRequired = true;
-        throw latchFatal("\u901A\u8FDB\u53F8\u8BF7\u6C42\u4E0D\u5728\u8D44\u683C\u622A\u6B62\u524D");
+        throw new CollectorWaitWindowClosedError("request");
       }
       const configuredBody = configured?.requestBody ?? roleBody;
       const { body, marker } = buildCollectorRequestBody({
@@ -13190,22 +13273,20 @@ function createCollectorLedger(config, options) {
       journalRequest(void 0);
       throw latchFatal(`\u901A\u8FDB\u53F8\u8BF7\u6C42\u88AB\u62D2\uFF1A${result.diagnostics}`);
     },
-    async wait(input, clock2, signal) {
+    async wait(input2, clock2, signal) {
       assertNotFatal();
-      if (activationTime === void 0) {
+      if (!sessionReady) {
         throw latchFatal("\u901A\u8FDB\u53F8\u7B49\u5F85\u9700\u8981\u6FC0\u6D3B");
       }
+      if (activationTime === void 0 || deadlineTime === void 0) {
+        throw new CollectorWaitWindowClosedError("wait-before-open");
+      }
       if (pastCutoff(clock2)) {
         finalObservationRequired = true;
-        throw latchFatal("\u901A\u8FDB\u53F8\u7B49\u5F85\u4E0D\u5728\u8D44\u683C\u622A\u6B62\u524D");
+        throw new CollectorWaitWindowClosedError("wait");
       }
       const remaining = remainingMs(clock2);
-      const COLLECTOR_SINGLE_WAIT_MAX_MS = 3e5;
-      const effectiveMs = Math.min(
-        input.durationMs,
-        remaining,
-        COLLECTOR_SINGLE_WAIT_MAX_MS
-      );
+      const effectiveMs = Math.min(input2.durationMs, remaining);
       const startedAt = clock2.wallNow().toISOString();
       const waitId = sha256Text(`wait:${startedAt}:${effectiveMs}`).slice(0, 16);
       await clock2.sleep(effectiveMs, signal);
@@ -13213,7 +13294,7 @@ function createCollectorLedger(config, options) {
       const cutoffReached = pastCutoff(clock2);
       const record4 = {
         waitId,
-        requestedMs: input.durationMs,
+        requestedMs: input2.durationMs,
         effectiveMs,
         startedAt,
         endedAt,
@@ -13225,7 +13306,7 @@ function createCollectorLedger(config, options) {
       });
       return {
         waitId,
-        requestedMs: input.durationMs,
+        requestedMs: input2.durationMs,
         effectiveMs,
         cutoffReached,
         remainingMsAfter: remainingMs(clock2)
@@ -13284,6 +13365,7 @@ function buildObserveModelView(input) {
     completedAt: input.snapshot.completedAt,
     prState: input.snapshot.prState,
     headOid: input.snapshot.headOid,
+    ...input.snapshot.prCreatedAt === void 0 ? {} : { prCreatedAt: input.snapshot.prCreatedAt },
     complete: input.snapshot.complete,
     evidence: relevant.map((record4) => projectEvidenceEntryView(record4)),
     requestAttempts: input.attempts.map((attempt) => ({
@@ -13296,7 +13378,7 @@ function buildObserveModelView(input) {
     }))
   };
 }
-var COLLECTOR_OBSERVE_TOOL, COLLECTOR_READ_TOOL, COLLECTOR_REQUEST_TOOL, COLLECTOR_WAIT_TOOL, COLLECTOR_BIND_TARGET_TOOL, COLLECTOR_HANDBOOK_WRITE_TOOL, COLLECTOR_OPERATIONAL_TOOLS, COLLECTOR_OBSERVE_BODY_HEAD_BYTES, COLLECTOR_ACTIVATION_ENTRY_TYPE, COLLECTOR_SNAPSHOT_ENTRY_TYPE, COLLECTOR_REQUEST_ENTRY_TYPE, COLLECTOR_WAIT_ENTRY_TYPE;
+var COLLECTOR_OBSERVE_TOOL, COLLECTOR_READ_TOOL, COLLECTOR_REQUEST_TOOL, COLLECTOR_WAIT_TOOL, COLLECTOR_OPEN_WAIT_WINDOW_TOOL, COLLECTOR_BIND_TARGET_TOOL, COLLECTOR_HANDBOOK_WRITE_TOOL, COLLECTOR_OPERATIONAL_TOOLS, COLLECTOR_OBSERVE_BODY_HEAD_BYTES, COLLECTOR_ACTIVATION_ENTRY_TYPE, COLLECTOR_SNAPSHOT_ENTRY_TYPE, COLLECTOR_REQUEST_ENTRY_TYPE, COLLECTOR_WAIT_ENTRY_TYPE;
 var init_collector_ledger = __esm({
   "src/collector-ledger.ts"() {
     "use strict";
@@ -13308,6 +13390,7 @@ var init_collector_ledger = __esm({
     COLLECTOR_READ_TOOL = "ak_collector_read";
     COLLECTOR_REQUEST_TOOL = "ak_collector_request";
     COLLECTOR_WAIT_TOOL = "ak_collector_wait";
+    COLLECTOR_OPEN_WAIT_WINDOW_TOOL = "ak_collector_open_wait_window";
     COLLECTOR_BIND_TARGET_TOOL = "ak_collector_bind_target";
     COLLECTOR_HANDBOOK_WRITE_TOOL = "ak_collector_handbook_write";
     COLLECTOR_OPERATIONAL_TOOLS = [
@@ -13315,6 +13398,7 @@ var init_collector_ledger = __esm({
       COLLECTOR_OBSERVE_TOOL,
       COLLECTOR_READ_TOOL,
       COLLECTOR_REQUEST_TOOL,
+      COLLECTOR_OPEN_WAIT_WINDOW_TOOL,
       COLLECTOR_WAIT_TOOL,
       COLLECTOR_HANDBOOK_WRITE_TOOL
     ];
@@ -20212,11 +20296,10 @@ var init_atomic_write = __esm({
 
 // src/collector-tool-schemas.ts
 import { Type as Type19 } from "typebox";
-var collectorObserveArgsSchema, COLLECTOR_REQUEST_ID_PATTERN, collectorRequestArgsSchema, COLLECTOR_HANDBOOK_MAX_BYTES, collectorHandbookWriteArgsSchema, collectorReadArgsSchema, collectorWaitArgsSchema, collectorBindTargetArgsSchema, collectorFindingItemDeclaration, collectorOutputBaseSchema, collectorOutputArgsSchema;
+var collectorObserveArgsSchema, COLLECTOR_REQUEST_ID_PATTERN, collectorRequestArgsSchema, COLLECTOR_HANDBOOK_MAX_BYTES, collectorHandbookWriteArgsSchema, collectorReadArgsSchema, collectorWaitArgsSchema, collectorOpenWaitWindowArgsSchema, collectorBindTargetArgsSchema, collectorFindingItemDeclaration, collectorOutputBaseSchema, collectorOutputArgsSchema;
 var init_collector_tool_schemas = __esm({
   "src/collector-tool-schemas.ts"() {
     "use strict";
-    init_collector_evidence();
     init_open_tool_schema();
     init_terminating_infrastructure();
     collectorObserveArgsSchema = Type19.Object({}, { additionalProperties: false });
@@ -20247,7 +20330,16 @@ var init_collector_tool_schemas = __esm({
       evidenceId: Type19.String({ minLength: 1, description: "observe \u8FD4\u56DE\u7684\u6750\u6599\u8BC1\u636E id\uFF08evidenceId\uFF09" })
     }, { additionalProperties: false });
     collectorWaitArgsSchema = Type19.Object({
-      durationMs: Type19.Integer({ minimum: 1, maximum: COLLECTOR_ELIGIBILITY_MS, description: "\u7B49\u5F85\u6BEB\u79D2\uFF1B\u5355\u6B21\u4E0A\u9650\u4E94\u5206\u949F\u4E14\u4E0D\u8D85\u5269\u4F59\u8D44\u683C" })
+      durationMs: Type19.Integer({
+        minimum: 1,
+        description: "\u7B49\u5F85\u6BEB\u79D2\uFF1B\u5B9E\u9645\u7761\u7720\u4E0D\u8D85\u8FC7\u5269\u4F59\u7B49\u5F85\u7A97\uFF08#678\uFF1B\u65E0\u5305\u5185\u5355\u6B21\u4EFB\u610F\u4E0A\u9650\uFF09"
+      })
+    }, { additionalProperties: false });
+    collectorOpenWaitWindowArgsSchema = Type19.Object({
+      startedAt: Type19.Optional(Type19.String({
+        minLength: 1,
+        description: "\u7B49\u5F85\u7A97\u8D77\u70B9 ISO \u65F6\u95F4\uFF1B\u65B0\u5EFA PR \u7528\u521B\u5EFA\u6210\u529F\u65F6\u523B\uFF1B\u7701\u7565\uFF1D\u73B0\u5728\uFF08\u89E6\u53D1\u9636\u6BB5\u7ED3\u675F\uFF09"
+      }))
     }, { additionalProperties: false });
     collectorBindTargetArgsSchema = Type19.Object({
       prNumber: Type19.Optional(Type19.Unknown({
@@ -20523,6 +20615,15 @@ var init_collector_receipt = __esm({
 });
 
 // src/collector-role.ts
+function parseWaitWindowMsFlag(raw) {
+  if (raw === void 0 || raw === null || raw === "") return COLLECTOR_DEFAULT_WAIT_WINDOW_MS;
+  if (typeof raw === "number" && Number.isSafeInteger(raw) && raw >= 1) return raw;
+  if (typeof raw === "string" && /^[1-9]\d*$/.test(raw.trim())) {
+    const value = Number(raw.trim());
+    if (Number.isSafeInteger(value) && value >= 1) return value;
+  }
+  throw new Error("Collector --ak-collector-wait-ms must be a positive safe-integer millisecond string");
+}
 function buildMethodContext(activation) {
   const pr = activation.ledger.config.prNumber;
   const handbook = activation.handbookView;
@@ -20531,6 +20632,7 @@ function buildMethodContext(activation) {
     `host: github.com`,
     `repository: ${activation.repository.canonical}`,
     `prNumber: ${pr === void 0 ? "\u672A\u7ED1\u5B9A" : String(pr)}`,
+    `waitWindowMs: ${String(activation.ledger.config.waitWindowMs)}`,
     `requests: ${JSON.stringify(activation.manifest.requests.map((request) => ({ id: request.id })))}`,
     `handbookGeneralSource: ${handbook.generalSource}`,
     `handbookRepoSource: ${handbook.repoSource}`,
@@ -20563,6 +20665,7 @@ function createCollectorRoleRuntime(pi, dependencies, hostActions) {
       const repoFlag = pi.getFlag("ak-collector-repo");
       const prFlag = pi.getFlag("ak-collector-pr");
       const requestManifestFlag = pi.getFlag("ak-collector-request-manifest");
+      const waitMsFlag = pi.getFlag("ak-collector-wait-ms");
       if (typeof repoFlag !== "string" || repoFlag.trim().length === 0) {
         throw new Error("Collector requires --ak-collector-repo");
       }
@@ -20574,10 +20677,11 @@ function createCollectorRoleRuntime(pi, dependencies, hostActions) {
         prNumber = parseCollectorPrNumber(prFlag);
       }
       const manifest = typeof requestManifestFlag === "string" && requestManifestFlag.trim().length > 0 ? await loadCollectorManifest(requestManifestFlag) : emptyCollectorManifest();
+      const waitWindowMs = parseWaitWindowMsFlag(waitMsFlag);
       const clock = dependencies.createClock?.() ?? createSystemCollectorClock();
       const transport = dependencies.createTransport();
       const ledger = dependencies.createLedger(
-        { repository, prNumber, manifest },
+        { repository, prNumber, manifest, waitWindowMs },
         clock,
         ctx
       );
@@ -20840,11 +20944,57 @@ function createCollectorRoleRuntime(pi, dependencies, hostActions) {
           }
         }
       });
+      pi.registerTool({
+        name: COLLECTOR_OPEN_WAIT_WINDOW_TOOL,
+        label: "\u901A\u8FDB\u53F8\u5F00\u542F\u7B49\u5F85\u7A97",
+        description: "\u5728\u5DE5\u4F5C\u6B65\u9AA4\u4E0A\u5F00\u542F\u7B49\u5F85\u7A97\uFF1A\u65B0\u5EFA\u5E76\u81EA\u52A8\u89E6\u53D1\u7684 PR \u4F20\u521B\u5EFA\u6210\u529F\u65F6\u523B\uFF1B\u5DF2\u6709 PR \u5728\u89E6\u53D1\u9636\u6BB5\u7ED3\u675F\u540E\u7701\u7565 startedAt\uFF08=\u73B0\u5728\uFF09\u3002\u7A97\u957F\u7531\u4F7F\u7528\u65B9\u914D\u7F6E\uFF0C\u9ED8\u8BA4\u5341\u5206\u949F\uFF1B\u5F00\u542F\u540E\u4E0D\u56E0 PR \u66F4\u65B0\u91CD\u7F6E\u3002",
+        promptSnippet: "\u6309\u5DE5\u4F5C\u6B65\u9AA4\u5F00\u542F\u7B49\u5F85\u7A97",
+        parameters: openWaitWindowSchema,
+        async execute(toolCallId, params, _signal, _onUpdate, ctx) {
+          const activation = getActivation();
+          if (activation === void 0) throw new Error("\u901A\u8FDB\u53F8\u672A\u6FC0\u6D3B");
+          try {
+            activation.ledger.beginOperational(COLLECTOR_OPEN_WAIT_WINDOW_TOOL, toolCallId);
+            let startedAt;
+            if (typeof params.startedAt === "string" && params.startedAt.trim().length > 0) {
+              const parsed = new Date(params.startedAt);
+              if (Number.isNaN(parsed.getTime())) {
+                throw new Error("\u901A\u8FDB\u53F8\u7B49\u5F85\u7A97 startedAt \u987B\u4E3A\u6709\u6548 ISO \u65F6\u95F4");
+              }
+              startedAt = parsed;
+            }
+            activation.ledger.openWaitWindow(
+              activation.clock,
+              startedAt === void 0 ? void 0 : { startedAt }
+            );
+            activation.ledger.completeOperational(toolCallId);
+            return {
+              content: [{
+                type: "text",
+                text: "\u7B49\u5F85\u7A97\u5DF2\u5F00\u542F"
+              }],
+              details: {
+                activationTime: activation.ledger.activationTime?.toISOString(),
+                deadlineTime: activation.ledger.deadlineTime?.toISOString(),
+                waitWindowMs: activation.ledger.config.waitWindowMs
+              }
+            };
+          } catch (error) {
+            if (isCorrectableExecuteError(error)) throw error;
+            hostActions.failInfrastructure(error, ctx, toolCallId);
+          } finally {
+            try {
+              activation.ledger.completeOperational(toolCallId);
+            } catch {
+            }
+          }
+        }
+      });
       pi.registerTool({
         name: COLLECTOR_WAIT_TOOL,
         label: "\u901A\u8FDB\u53F8\u7B49\u5F85",
-        description: "\u518D\u89C2\u5BDF\u524D\u7B49\u5F85\uFF1B\u5355\u6B21\u4E0A\u9650\u4E94\u5206\u949F\u4E14\u4E0D\u8D85\u5269\u4F59\u8D44\u683C\u3002",
-        promptSnippet: "\u8D44\u683C\u622A\u6B62\u524D\u7B49\u5F85",
+        description: "\u518D\u89C2\u5BDF\u524D\u7B49\u5F85\uFF1B\u5B9E\u9645\u7761\u7720\u4E0D\u8D85\u8FC7\u5269\u4F59\u7B49\u5F85\u7A97\u3002",
+        promptSnippet: "\u7B49\u5F85\u7A97\u5185\u7B49\u5F85",
         parameters: waitSchema,
         async execute(toolCallId, params, signal, _onUpdate, ctx) {
           const activation = getActivation();
@@ -20865,6 +21015,7 @@ function createCollectorRoleRuntime(pi, dependencies, hostActions) {
               details
             };
           } catch (error) {
+            if (isCorrectableExecuteError(error)) throw error;
             hostActions.failInfrastructure(error, ctx, toolCallId);
           }
         }
@@ -20917,7 +21068,7 @@ function createCollectorRoleRuntime(pi, dependencies, hostActions) {
     }
   };
 }
-var CollectorNormalCompletionDeclarationError, CollectorTargetBindError, COLLECTOR_REQUIRED_TOOLS, COLLECTOR_TRANSPORT_FLAGS, observeSchema, readSchema, requestSchema, waitSchema, bindSchema, handbookWriteSchema, outputSchema;
+var CollectorNormalCompletionDeclarationError, CollectorTargetBindError, COLLECTOR_REQUIRED_TOOLS, COLLECTOR_TRANSPORT_FLAGS, observeSchema, readSchema, requestSchema, openWaitWindowSchema, waitSchema, bindSchema, handbookWriteSchema, outputSchema;
 var init_collector_role = __esm({
   "src/collector-role.ts"() {
     "use strict";
@@ -20949,6 +21100,7 @@ var init_collector_role = __esm({
       COLLECTOR_OBSERVE_TOOL,
       COLLECTOR_READ_TOOL,
       COLLECTOR_REQUEST_TOOL,
+      COLLECTOR_OPEN_WAIT_WINDOW_TOOL,
       COLLECTOR_WAIT_TOOL,
       COLLECTOR_HANDBOOK_WRITE_TOOL,
       COLLECTOR_OUTPUT_TOOL
@@ -20974,11 +21126,19 @@ var init_collector_role = __esm({
           description: "Path to the Collector v1 request manifest JSON file.",
           type: "string"
         })
+      }),
+      Object.freeze({
+        name: "ak-collector-wait-ms",
+        definition: Object.freeze({
+          description: `Collector wait-window duration in milliseconds (default ${COLLECTOR_DEFAULT_WAIT_WINDOW_MS}). Caller-configurable; opens at a work step, not session start (#678 D4).`,
+          type: "string"
+        })
       })
     ]);
     observeSchema = collectorObserveArgsSchema;
     readSchema = collectorReadArgsSchema;
     requestSchema = collectorRequestArgsSchema;
+    openWaitWindowSchema = collectorOpenWaitWindowArgsSchema;
     waitSchema = collectorWaitArgsSchema;
     bindSchema = collectorBindTargetArgsSchema;
     handbookWriteSchema = collectorHandbookWriteArgsSchema;
@@ -26108,6 +26268,7 @@ function projectAcpActivationFlags(request) {
     flags.set("ak-collector-repo", activation.repo);
     if (activation.pr !== void 0) flags.set("ak-collector-pr", activation.pr);
     if (activation.requestManifestPath !== void 0) flags.set("ak-collector-request-manifest", activation.requestManifestPath);
+    if (activation.waitMs !== void 0) flags.set("ak-collector-wait-ms", activation.waitMs);
   }
   return flags;
 }

package/dist/collector-evidence.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
-export const COLLECTOR_ELIGIBILITY_MS = 15 * 60 * 1000;
+/** Default collector wait window (D4): 10 minutes from the work-step open, not from session activation. */
+export const COLLECTOR_DEFAULT_WAIT_WINDOW_MS = 10 * 60 * 1000;
 export function createSystemCollectorClock() {
     const start = process.hrtime.bigint();
     return {
@@ -76,6 +77,7 @@ export function normalizePullRequestEvidence(pr, observedAt) {
         number: pr.number,
         state: pr.state,
         headOid: pr.headOid,
+        createdAt: pr.createdAt ?? null,
         updatedAt: pr.updatedAt ?? null,
         htmlUrl: pr.url,
     });
@@ -89,6 +91,7 @@ export function normalizePullRequestEvidence(pr, observedAt) {
         state: pr.state,
         commitOid: pr.headOid,
         htmlUrl: pr.url,
+        // Version clock stays updatedAt. Create success for the wait window is snapshot.prCreatedAt only (#678).
         authoritativeTime: pr.updatedAt ?? null,
         firstObservedAt: observedAt,
         raw: pr.raw,

package/dist/collector-github.js

@@ -289,6 +289,7 @@ export function normalizePullRequest(raw) {
         number,
         state,
         headOid: head["sha"],
+        ...(typeof raw["created_at"] === "string" ? { createdAt: raw["created_at"] } : {}),
         ...(typeof raw["updated_at"] === "string" ? { updatedAt: raw["updated_at"] } : {}),
         url: htmlUrl,
         raw,