@akagilnc/pi-workflow-roles 0.1.3783 → 0.1.3795

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
@@ -883,10 +884,10 @@ __export(session_assistant_usage_exports, {
 });
 import { join as join2 } from "node:path";
 async function readAssistantUsageFromSessionFile(sessionFile) {
-  const { readFile: readFile21 } = await import("node:fs/promises");
+  const { readFile: readFile22 } = await import("node:fs/promises");
   let text;
   try {
-    text = await readFile21(sessionFile, "utf8");
+    text = await readFile22(sessionFile, "utf8");
   } catch (error) {
     if (error?.code === "ENOENT") return void 0;
     throw error;
@@ -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 },
@@ -6085,8 +6092,22 @@ var init_option_definitions = __esm({
         repeatable: false,
         form: "option",
         description: {
-          en: "Optional request manifest JSON path ({requests:[{id,body}]}).",
-          zh: "\u53EF\u9009 request manifest JSON \u8DEF\u5F84\uFF08{requests:[{id,body}]}\uFF09\u3002"
+          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"
         }
       }
     ];
@@ -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
   };
 }
@@ -8518,11 +8554,11 @@ function parseAnalystCohortIssueToken(raw, flag) {
       `${flag} requires a comma-separated list of N or book:N`
     );
   }
-  const sep4 = trimmed.lastIndexOf(":");
-  if (sep4 > 0) {
-    const rhs = trimmed.slice(sep4 + 1);
+  const sep5 = trimmed.lastIndexOf(":");
+  if (sep5 > 0) {
+    const rhs = trimmed.slice(sep5 + 1);
     if (ANALYST_TICKET_NUMBER_PATTERN.test(rhs)) {
-      const bookKey = trimmed.slice(0, sep4);
+      const bookKey = trimmed.slice(0, sep5);
       if (bookKey.trim() === "") {
         throw new CliUsageError(
           `${flag} book:N requires a non-empty book key, got ${raw}`
@@ -11011,10 +11047,10 @@ function pairGateRounds(volumes) {
   return rounds.sort((a, b) => a.officerStartedAt.localeCompare(b.officerStartedAt)).map((round, index) => ({ ...round, roundIndex: index + 1 }));
 }
 async function resolveOfficerSessionFromPointerFile(pointerPath) {
-  const { readFile: readFile21 } = await import("node:fs/promises");
+  const { readFile: readFile22 } = await import("node:fs/promises");
   let raw;
   try {
-    raw = JSON.parse(await readFile21(pointerPath, "utf8"));
+    raw = JSON.parse(await readFile22(pointerPath, "utf8"));
   } catch (error) {
     throw new Error(
       `direct officer run pointer unreadable in ${pointerPath}: ${error instanceof Error ? error.message : String(error)}`,
@@ -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",
@@ -12504,76 +12550,7 @@ var init_collector_identity = __esm({
   }
 });
 
-// src/collector-tool-schemas.ts
-import { Type as Type13 } from "typebox";
-var collectorObserveArgsSchema, collectorRequestArgsSchema, collectorReadArgsSchema, collectorWaitArgsSchema, 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 = Type13.Object({}, { additionalProperties: false });
-    collectorRequestArgsSchema = Type13.Object({
-      requestId: Type13.String({ minLength: 1, description: "\u914D\u7F6E\u8BF7\u6C42\u8EAB\u4EFD" }),
-      snapshotId: Type13.String({ minLength: 1, description: "\u6700\u65B0\u7559\u5B58\u89C2\u5BDF\u5FEB\u7167" })
-    }, { additionalProperties: false });
-    collectorReadArgsSchema = Type13.Object({
-      evidenceId: Type13.String({ minLength: 1, description: "observe \u8FD4\u56DE\u7684\u6750\u6599\u8BC1\u636E id\uFF08evidenceId\uFF09" })
-    }, { additionalProperties: false });
-    collectorWaitArgsSchema = Type13.Object({
-      durationMs: Type13.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" })
-    }, { additionalProperties: false });
-    collectorBindTargetArgsSchema = Type13.Object({
-      prNumber: Type13.Optional(Type13.Unknown({
-        description: "\u89D2\u8272\u5224\u5B9A\u7684\u672C\u4ED3 PR \u53F7\uFF08\u6B63\u6574\u6570\uFF09\u3002\u4E0E issueNumber \u4E8C\u9009\u4E00\u6216\u540C\u6307\u552F\u4E00\u76EE\u6807\u3002\u5F62\u72B6\u6307\u5F15\uFF0C\u975E schema \u95F8\u3002"
-      })),
-      issueNumber: Type13.Optional(Type13.Unknown({
-        description: "\u89D2\u8272\u5224\u5B9A\u7684\u672C\u4ED3 issue \u53F7\uFF08\u6B63\u6574\u6570\uFF09\uFF1Bruntime \u7ECF\u7EBF\u4E0A\u5173\u8054\u89E3\u6790\u552F\u4E00 PR\u3002\u5F62\u72B6\u6307\u5F15\uFF0C\u975E schema \u95F8\u3002"
-      }))
-    }, { additionalProperties: true });
-    collectorFindingItemDeclaration = (() => {
-      const item = Type13.Object(
-        {
-          evidenceId: Type13.Unknown({
-            description: "observe \u8FD4\u56DE\u7684\u6750\u6599\u6307\u9488\uFF08\u5FC5\u586B\u8BED\u4E49\uFF09"
-          }),
-          category: Type13.Unknown({
-            description: "\u7B80\u77ED\u5F52\u7C7B\u6807\u7B7E\uFF0C\u4E0D\u662F\u6458\u8981"
-          }),
-          summary: Type13.Unknown({
-            description: "\u54EA\u4E2A bot\u3001\u4EC0\u4E48\u95EE\u9898\u7684\u6458\u8981\uFF1B\u4E0D\u8A8A\u6284\u6B63\u6587"
-          })
-        },
-        {
-          additionalProperties: true,
-          description: "\u5355\u6761 finding \u6307\u9488\uFF1AevidenceId + \u53EF\u9009 category/summary\u3002\u5F62\u72B6\u6307\u5F15\uFF0C\u975E schema \u95F8\u3002"
-        }
-      );
-      item.required = [];
-      return item;
-    })();
-    collectorOutputBaseSchema = openToolObject(
-      Type13.Object({
-        // No root type:array — host must not shape-reject non-array findings (#676 C).
-        // Nested item declarations ride `items` for registration preservation (ADR 0057).
-        findings: Type13.Unsafe({
-          description: "\u672C\u6B21\u6536\u96C6\u5230\u7684\u9010\u6761 findings\uFF08\u6307\u9488\u6570\u7EC4\u4E3A\u89C4\u8303\u5F62\uFF09\u3002\u96F6 finding \u7684\u6A21\u677F\u901A\u77E5\u4E0D\u5F97\u8FDB\u5165\uFF1B\u6B63\u5E38\u5B8C\u5DE5\u65E0 finding \u65F6\u7701\u7565\u3002\u5F62\u72B6\u6307\u5F15\uFF0C\u975E schema \u95F8\u3002",
-          items: collectorFindingItemDeclaration
-        }),
-        unfinishedReasons: Type13.Unknown({
-          description: "\u672A\u5B8C\u6210\u539F\u56E0\u5B57\u7B26\u4E32\u6570\u7EC4\uFF08\u989D\u5EA6/\u6545\u969C/\u7B49\u5F85\u5C4A\u6EE1\u7B49\u73B0\u573A\u4F9D\u636E\uFF09\uFF1B\u4E0D\u5F97\u628A\u672A\u5B8C\u6210\u8868\u8FF0\u4E3A\u65E0\u95EE\u9898\u3002\u65E0\u53EF\u62A5\u544A\u65F6\u7701\u7565\u3002\u5F62\u72B6\u6307\u5F15\uFF0C\u975E schema \u95F8\u3002"
-        })
-      })
-    );
-    collectorOutputArgsSchema = withInfrastructureFailureDeclaration(
-      collectorOutputBaseSchema
-    );
-  }
-});
-
 // src/collector-ledger.ts
-import Value2 from "typebox/value";
 function utf8SafePrefix(text, maxBytes) {
   if (Buffer.byteLength(text, "utf8") <= maxBytes) return text;
   const bytes = Buffer.from(text, "utf8");
@@ -12590,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;
@@ -12640,15 +12631,13 @@ 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 ?? ""}`;
   const requireBoundPr = () => {
     if (config.prNumber === void 0) {
-      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("\u901A\u8FDB\u53F8 PR \u76EE\u6807\u672A\u7ED1\u5B9A");
     }
     return config.prNumber;
   };
@@ -12711,6 +12700,7 @@ function createCollectorLedger(config, options) {
   };
   const commitActivationWindow = (nextActivation, nextDeadline) => {
     if (activationTime !== void 0) return;
+    sessionReady = true;
     activationTime = nextActivation;
     deadlineTime = nextDeadline;
     bindDeadlineMonoFromWall();
@@ -12818,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;
       }
@@ -12871,7 +12863,7 @@ function createCollectorLedger(config, options) {
       return outputCandidate || pendingOutputCallId !== void 0;
     },
     get activationRecorded() {
-      return activationTime !== void 0;
+      return sessionReady;
     },
     get activationTime() {
       return activationTime;
@@ -12908,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() {
@@ -12930,11 +12941,11 @@ function createCollectorLedger(config, options) {
         throw new Error("\u901A\u8FDB\u53F8\u5DF2\u4EA7\u51FA\u8F93\u51FA\u5019\u9009\uFF0C\u672C\u5C40\u4E0D\u518D\u53D7\u7406\u76EE\u6807\u7ED1\u5B9A");
       }
       if (!Number.isSafeInteger(prNumber) || prNumber < 1) {
-        throw new Error("Collector bind target requires a positive safe-integer PR number");
+        throw new Error("\u901A\u8FDB\u53F8\u7ED1\u5B9A\u76EE\u6807\u8981\u6C42\u6B63\u5B89\u5168\u6574\u6570 PR \u53F7");
       }
       if (config.prNumber !== void 0 && config.prNumber !== prNumber) {
         throw new Error(
-          `Collector target already bound to PR ${config.prNumber}; cannot rebind to ${prNumber}`
+          `\u901A\u8FDB\u53F8\u76EE\u6807\u5DF2\u7ED1\u5B9A PR ${config.prNumber}\uFF0C\u4E0D\u53EF\u6539\u7ED1\u4E3A ${prNumber}`
         );
       }
       config.prNumber = prNumber;
@@ -13005,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) {
@@ -13092,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,
@@ -13123,21 +13135,33 @@ 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");
       }
-      const request = config.manifest.requests.find((item) => item.id === input.requestId);
-      if (request === void 0) {
-        throw new Error(`\u672A\u77E5\u901A\u8FDB\u53F8 requestId "${input.requestId}"`);
+      if (typeof input2.requestId !== "string") {
+        throw new Error("\u901A\u8FDB\u53F8 requestId \u987B\u4E3A\u5B57\u7B26\u4E32");
+      }
+      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 snapshot = snapshots.find((item) => item.snapshotId === input.snapshotId);
+      const configured = config.manifest.requests.find((item) => item.id === requestId);
+      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(
+            `\u672A\u77E5\u901A\u8FDB\u53F8 requestId "${requestId}" \u4E14\u672A\u63D0\u4F9B body\uFF1B\u8BF7\u63D0\u4EA4\u89D2\u8272\u5224\u5B9A\u7684\u8BF7\u6C42\u6B63\u6587\u6216\u4F7F\u7528 request-manifest`
+          );
+        }
+      }
+      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");
@@ -13147,12 +13171,13 @@ 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({
-        configuredBody: request.requestBody,
+        configuredBody,
         manifestDigest: config.manifest.digest,
-        requestId: request.id,
+        requestId,
         headOid: snapshot.headOid
       });
       const existingMarker = snapshot.evidenceIds.some((id) => {
@@ -13161,7 +13186,7 @@ function createCollectorLedger(config, options) {
       });
       if (existingMarker) {
         throw new Error(
-          `\u901A\u8FDB\u53F8\u5728\u6B64 HEAD \u5DF2\u6709\u540C marker \u7684\u5DF2\u8BA4\u8BC1\u8BF7\u6C42 "${input.requestId}"`
+          `\u901A\u8FDB\u53F8\u5728\u6B64 HEAD \u5DF2\u6709\u540C marker \u7684\u5DF2\u8BA4\u8BC1\u8BF7\u6C42 "${requestId}"`
         );
       }
       const boundPr = requireBoundPr();
@@ -13169,18 +13194,18 @@ function createCollectorLedger(config, options) {
         config.repository.canonical,
         String(boundPr),
         snapshot.headOid,
-        request.id
+        requestId
       ].join("|");
       if (attemptKeys.has(attemptKey)) {
         throw new Error(
-          `\u901A\u8FDB\u53F8\u8FDB\u7A0B\u5185\u8BF7\u6C42 "${request.id}" \u5728 HEAD ${snapshot.headOid} \u7684 attempt \u5DF2\u7528`
+          `\u901A\u8FDB\u53F8\u8FDB\u7A0B\u5185\u8BF7\u6C42 "${requestId}" \u5728 HEAD ${snapshot.headOid} \u7684 attempt \u5DF2\u7528`
         );
       }
       const startedAt = clock2.wallNow().toISOString();
       const attemptId = sha256Text(`${attemptKey}:${startedAt}`).slice(0, 16);
       const attempt = {
         attemptId,
-        requestId: request.id,
+        requestId,
         observedHead: snapshot.headOid,
         snapshotId: snapshot.snapshotId,
         marker,
@@ -13222,7 +13247,7 @@ function createCollectorLedger(config, options) {
         return {
           status: "succeeded",
           attemptId,
-          requestId: request.id,
+          requestId,
           observedHead: snapshot.headOid,
           marker,
           commentEvidenceId: record4.evidenceId
@@ -13236,7 +13261,7 @@ function createCollectorLedger(config, options) {
         return {
           status: "ambiguous_loss",
           attemptId,
-          requestId: request.id,
+          requestId,
           observedHead: snapshot.headOid,
           marker,
           diagnostics: result.diagnostics
@@ -13248,30 +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 (!Number.isSafeInteger(input.durationMs) || input.durationMs < 1) {
-        throw new Error("\u901A\u8FDB\u53F8\u7B49\u5F85 durationMs \u987B\u4E3A\u6B63\u5B89\u5168\u6574\u6570");
-      }
-      if (input.durationMs > COLLECTOR_ELIGIBILITY_MS) {
-        throw new Error(
-          `\u901A\u8FDB\u53F8\u7B49\u5F85 durationMs \u81F3\u591A\u4E3A ${COLLECTOR_ELIGIBILITY_MS}`
-        );
+      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);
@@ -13279,7 +13294,7 @@ function createCollectorLedger(config, options) {
       const cutoffReached = pastCutoff(clock2);
       const record4 = {
         waitId,
-        requestedMs: input.durationMs,
+        requestedMs: input2.durationMs,
         effectiveMs,
         startedAt,
         endedAt,
@@ -13291,7 +13306,7 @@ function createCollectorLedger(config, options) {
       });
       return {
         waitId,
-        requestedMs: input.durationMs,
+        requestedMs: input2.durationMs,
         effectiveMs,
         cutoffReached,
         remainingMsAfter: remainingMs(clock2)
@@ -13350,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) => ({
@@ -13362,26 +13378,29 @@ function buildObserveModelView(input) {
     }))
   };
 }
-var COLLECTOR_OBSERVE_TOOL, COLLECTOR_READ_TOOL, COLLECTOR_REQUEST_TOOL, COLLECTOR_WAIT_TOOL, COLLECTOR_BIND_TARGET_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";
     init_collector_evidence();
     init_collector_github();
     init_collector_identity();
-    init_collector_tool_schemas();
     init_collector_output();
     COLLECTOR_OBSERVE_TOOL = "ak_collector_observe";
     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 = [
       COLLECTOR_BIND_TARGET_TOOL,
       COLLECTOR_OBSERVE_TOOL,
       COLLECTOR_READ_TOOL,
       COLLECTOR_REQUEST_TOOL,
-      COLLECTOR_WAIT_TOOL
+      COLLECTOR_OPEN_WAIT_WINDOW_TOOL,
+      COLLECTOR_WAIT_TOOL,
+      COLLECTOR_HANDBOOK_WRITE_TOOL
     ];
     COLLECTOR_OBSERVE_BODY_HEAD_BYTES = 512;
     COLLECTOR_ACTIVATION_ENTRY_TYPE = "ak-collector-activation";
@@ -17921,11 +17940,11 @@ async function summonPublicRole(options) {
   };
 }
 async function parentInvocationHost(sourceRunDirectory) {
-  const { readFile: readFile21 } = await import("node:fs/promises");
+  const { readFile: readFile22 } = await import("node:fs/promises");
   const path = join28(sourceRunDirectory, "invocation.json");
   let text;
   try {
-    text = await readFile21(path, "utf8");
+    text = await readFile22(path, "utf8");
   } catch (error) {
     const code = error instanceof Error && "code" in error ? error.code : void 0;
     throw new Error(
@@ -18026,7 +18045,7 @@ __export(compliance_transport_exports, {
   runComplianceAudit: () => runComplianceAudit,
   tryReadComplianceCandidate: () => tryReadComplianceCandidate
 });
-import { Type as Type14 } from "typebox";
+import { Type as Type13 } from "typebox";
 function readListField(value) {
   return Array.isArray(value) ? value : value === void 0 ? [] : [value];
 }
@@ -18124,9 +18143,9 @@ var init_compliance_transport = __esm({
     "use strict";
     init_auditor_dossier_tool();
     AUDITOR_DOSSIER_PROMPT = "\u672C run \u5377\u5B97\u5DF2\u5C31\u7EEA\u3002";
-    nonblank2 = Type14.String({ minLength: 1, pattern: "\\S" });
-    decisionGateSchema = Type14.Object({ question: nonblank2, options: Type14.Array(nonblank2, { minItems: 1 }) }, { additionalProperties: false });
-    complianceDecisionSchema = Type14.Object({ status: Type14.Unknown({ description: "pass | bounce | escalate \u2014 \u5F62\u72B6\u6307\u5F15\uFF0C\u975E schema \u95F8" }), violations: Type14.Array(nonblank2, { description: "\u89C2\u5BDF\u5230\u7684\u5408\u89C4\u8FDD\u89C4" }), conflicts: Type14.Array(nonblank2, { description: "\u672A\u51B3\u6743\u5A01\u6216\u6267\u884C\u51B2\u7A81" }), decisionGate: Type14.Union([decisionGateSchema, Type14.Null()], { description: "\u5347\u7EA7\u95EE\u9898\u4E0E\u53EF\u9009\u9009\u9879" }) }, { additionalProperties: true, required: [] });
+    nonblank2 = Type13.String({ minLength: 1, pattern: "\\S" });
+    decisionGateSchema = Type13.Object({ question: nonblank2, options: Type13.Array(nonblank2, { minItems: 1 }) }, { additionalProperties: false });
+    complianceDecisionSchema = Type13.Object({ status: Type13.Unknown({ description: "pass | bounce | escalate \u2014 \u5F62\u72B6\u6307\u5F15\uFF0C\u975E schema \u95F8" }), violations: Type13.Array(nonblank2, { description: "\u89C2\u5BDF\u5230\u7684\u5408\u89C4\u8FDD\u89C4" }), conflicts: Type13.Array(nonblank2, { description: "\u672A\u51B3\u6743\u5A01\u6216\u6267\u884C\u51B2\u7A81" }), decisionGate: Type13.Union([decisionGateSchema, Type13.Null()], { description: "\u5347\u7EA7\u95EE\u9898\u4E0E\u53EF\u9009\u9009\u9879" }) }, { additionalProperties: true, required: [] });
     COMPLIANCE_RESPONSE_ENTRY_TYPE = "ak_compliance_response";
     AUDITOR_PARENT_ATTEMPT_BINDING_ENTRY_TYPE = "ak_auditor_parent_attempt_binding";
     AUDITOR_COMPLIANCE_FAILURE_ENTRY_TYPE = "ak_auditor_compliance_failure";
@@ -18220,8 +18239,8 @@ var init_doctor_auditor = __esm({
 });
 
 // src/navigator-session-contracts.ts
-import { Type as Type15 } from "typebox";
-import { Value as Value3 } from "typebox/value";
+import { Type as Type14 } from "typebox";
+import { Value as Value2 } from "typebox/value";
 function navigatorUnavailableKey(value) {
   return typeof value === "string" && NAVIGATOR_UNAVAILABLE_KEYS.has(value) ? value : void 0;
 }
@@ -18372,26 +18391,26 @@ var init_navigator_session_contracts = __esm({
         this.originalCause = originalCause;
       }
     };
-    navigatorProviderFailureSchema = Type15.Object({
-      source: Type15.Union([
-        Type15.Literal("context"),
-        Type15.Literal("session"),
-        Type15.Literal("model"),
-        Type15.Literal("thinking"),
-        Type15.Literal("auth"),
-        Type15.Literal("quota"),
-        Type15.Literal("transport"),
-        Type15.Literal("unknown")
+    navigatorProviderFailureSchema = Type14.Object({
+      source: Type14.Union([
+        Type14.Literal("context"),
+        Type14.Literal("session"),
+        Type14.Literal("model"),
+        Type14.Literal("thinking"),
+        Type14.Literal("auth"),
+        Type14.Literal("quota"),
+        Type14.Literal("transport"),
+        Type14.Literal("unknown")
       ]),
-      cause: Type15.Union([
-        Type15.Literal("context"),
-        Type15.Literal("session"),
-        Type15.Literal("model"),
-        Type15.Literal("thinking"),
-        Type15.Literal("auth"),
-        Type15.Literal("quota"),
-        Type15.Literal("transport"),
-        Type15.Literal("unknown")
+      cause: Type14.Union([
+        Type14.Literal("context"),
+        Type14.Literal("session"),
+        Type14.Literal("model"),
+        Type14.Literal("thinking"),
+        Type14.Literal("auth"),
+        Type14.Literal("quota"),
+        Type14.Literal("transport"),
+        Type14.Literal("unknown")
       ])
     }, { additionalProperties: false });
   }
@@ -18743,7 +18762,7 @@ var init_navigator_public_session = __esm({
 import { createHash as createHash9 } from "node:crypto";
 import { resolve as resolve14 } from "node:path";
 import "@earendil-works/pi-coding-agent";
-import { Type as Type16 } from "typebox";
+import { Type as Type15 } from "typebox";
 function resolveNavigatorAuthorityMaterial(roleInput, fileAuthority) {
   if (roleInput !== void 0 && roleInput.trim() !== "") return roleInput;
   if (fileAuthority !== void 0 && fileAuthority.trim() !== "") return fileAuthority;
@@ -19406,8 +19425,8 @@ var init_navigator_attendance = __esm({
     NAVIGATOR_EVENT_TYPE = "ak-navigator-attendance";
     NAVIGATOR_PREPARE_ACCEPTED_TEXT = "\u6E38\u5955\u4F7F\u51C6\u5907\u5DF2\u63A5\u53D7";
     NAVIGATOR_TARGETS = PACKAGED_ROLE_REGISTRY.map(({ role, phases }) => ({ role, phases }));
-    prepareSchema = Type16.Object({
-      candidates: Type16.Optional(Type16.Unknown({
+    prepareSchema = Type15.Object({
+      candidates: Type15.Optional(Type15.Unknown({
         description: "\u65B9\u5411\u5019\u9009\uFF1Bcandidates[].next.role \u5FC5\u586B\uFF0Cphase \u53EF\u9009\uFF0Croute/matches/reason/command \u53EF\u9009\u4E0A\u4E0B\u6587\uFF0C\u975E\u53D7\u7406\u95F8"
       }))
     }, { additionalProperties: true });
@@ -19420,7 +19439,7 @@ var init_navigator_attendance = __esm({
 });
 
 // src/engine-detour-tool.ts
-import { Type as Type17 } from "typebox";
+import { Type as Type16 } from "typebox";
 function isCallerCancellation(error, signal) {
   if (signal?.aborted === true) return true;
   if (typeof error === "object" && error !== null && error.name === "AbortError") {
@@ -19495,9 +19514,9 @@ var init_engine_detour_tool = __esm({
   "src/engine-detour-tool.ts"() {
     "use strict";
     init_engine_detour();
-    engineDetourArgsSchema = Type17.Object(
+    engineDetourArgsSchema = Type16.Object(
       {
-        argv: Type17.Array(Type17.String({ minLength: 1 }), {
+        argv: Type16.Array(Type16.String({ minLength: 1 }), {
           minItems: 1,
           description: "\u9996\u9879\u4E3A PATH \u4E2D\u7684\u53EF\u6267\u884C\u6587\u4EF6\uFF0C\u5176\u4F59\u9879\u4E3A\u53C2\u6570\u3002"
         })
@@ -19824,7 +19843,7 @@ var init_oauth_keepalive = __esm({
 });
 
 // src/activation-trace.ts
-import { Type as Type18 } from "typebox";
+import { Type as Type17 } from "typebox";
 function namedActivationCause(error) {
   const evidenceId = `activation-cause-${++activationCauseEvidence}`;
   retainedActivationCauses.set(evidenceId, error);
@@ -19845,17 +19864,17 @@ var causeSchema, activationTraceRecordSchema, activationCauseEvidence, retainedA
 var init_activation_trace = __esm({
   "src/activation-trace.ts"() {
     "use strict";
-    causeSchema = Type18.Object({
-      identity: Type18.String({ minLength: 1 }),
-      name: Type18.String({ minLength: 1 }),
-      message: Type18.String(),
-      evidenceId: Type18.Optional(Type18.String({ minLength: 1 }))
+    causeSchema = Type17.Object({
+      identity: Type17.String({ minLength: 1 }),
+      name: Type17.String({ minLength: 1 }),
+      message: Type17.String(),
+      evidenceId: Type17.Optional(Type17.String({ minLength: 1 }))
     }, { additionalProperties: false });
-    activationTraceRecordSchema = Type18.Object({
-      role: Type18.String({ minLength: 1 }),
-      stageId: Type18.String({ pattern: "^[a-z][a-z0-9-]*$" }),
-      status: Type18.Literal("failed"),
-      timestamp: Type18.String({ format: "date-time" }),
+    activationTraceRecordSchema = Type17.Object({
+      role: Type17.String({ minLength: 1 }),
+      stageId: Type17.String({ pattern: "^[a-z][a-z0-9-]*$" }),
+      status: Type17.Literal("failed"),
+      timestamp: Type17.String({ format: "date-time" }),
       cause: causeSchema
     }, { additionalProperties: false });
     activationCauseEvidence = 0;
@@ -20137,10 +20156,10 @@ var init_stderr_jsonl = __esm({
 
 // src/tool-execution-observation.ts
 import { writeSync as writeSync3 } from "node:fs";
-import { Type as Type19 } from "typebox";
-import { Value as Value4 } from "typebox/value";
+import { Type as Type18 } from "typebox";
+import { Value as Value3 } from "typebox/value";
 function validateToolExecutionObservationRecord(record4) {
-  if (!Value4.Check(toolExecutionObservationRecordSchema, record4)) {
+  if (!Value3.Check(toolExecutionObservationRecordSchema, record4)) {
     throw new TypeError("Tool execution observation record does not match its contract");
   }
   return record4;
@@ -20231,29 +20250,274 @@ var init_tool_execution_observation = __esm({
     init_stderr_jsonl();
     TOOL_EXECUTION_UPDATE_THROTTLE_MS = 3e4;
     observationBase = {
-      role: Type19.String({ minLength: 1 }),
-      toolCallId: Type19.String({ minLength: 1 }),
-      toolName: Type19.String({ minLength: 1 }),
-      timestamp: Type19.String({ format: "date-time" })
+      role: Type18.String({ minLength: 1 }),
+      toolCallId: Type18.String({ minLength: 1 }),
+      toolName: Type18.String({ minLength: 1 }),
+      timestamp: Type18.String({ format: "date-time" })
     };
-    toolExecutionObservationRecordSchema = Type19.Union([
-      Type19.Object({
+    toolExecutionObservationRecordSchema = Type18.Union([
+      Type18.Object({
         ...observationBase,
-        event: Type19.Literal("tool_execution_start")
+        event: Type18.Literal("tool_execution_start")
       }, { additionalProperties: true }),
-      Type19.Object({
+      Type18.Object({
         ...observationBase,
-        event: Type19.Literal("tool_execution_update")
+        event: Type18.Literal("tool_execution_update")
       }, { additionalProperties: true }),
-      Type19.Object({
+      Type18.Object({
         ...observationBase,
-        event: Type19.Literal("tool_execution_end"),
-        isError: Type19.Boolean()
+        event: Type18.Literal("tool_execution_end"),
+        isError: Type18.Boolean()
       }, { additionalProperties: true })
     ]);
   }
 });
 
+// src/atomic-write.ts
+import { randomUUID as randomUUID6 } from "node:crypto";
+import { rename, rm as rm2, writeFile as writeFile8 } from "node:fs/promises";
+import { dirname as dirname17, join as join32 } from "node:path";
+async function writeFileAtomically(destination, contents) {
+  const parent = dirname17(destination);
+  const temporary = join32(parent, `.atomic-write-${randomUUID6()}.tmp`);
+  try {
+    await writeFile8(temporary, contents);
+    await rename(temporary, destination);
+  } catch (error) {
+    await rm2(temporary, { force: true }).catch(() => void 0);
+    throw error;
+  }
+}
+var init_atomic_write = __esm({
+  "src/atomic-write.ts"() {
+    "use strict";
+  }
+});
+
+// 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, collectorOpenWaitWindowArgsSchema, collectorBindTargetArgsSchema, collectorFindingItemDeclaration, collectorOutputBaseSchema, collectorOutputArgsSchema;
+var init_collector_tool_schemas = __esm({
+  "src/collector-tool-schemas.ts"() {
+    "use strict";
+    init_open_tool_schema();
+    init_terminating_infrastructure();
+    collectorObserveArgsSchema = Type19.Object({}, { additionalProperties: false });
+    COLLECTOR_REQUEST_ID_PATTERN = /^\S(?:.*\S)?$/;
+    collectorRequestArgsSchema = Type19.Object({
+      requestId: Type19.String({
+        minLength: 1,
+        pattern: COLLECTOR_REQUEST_ID_PATTERN.source,
+        description: "\u8BF7\u6C42\u8EAB\u4EFD\uFF08\u914D\u7F6E id \u6216\u89D2\u8272\u5224\u5B9A\u7684\u7A33\u5B9A id\uFF1B\u9996\u5C3E\u65E0\u7A7A\u767D\uFF09"
+      }),
+      snapshotId: Type19.String({ minLength: 1, description: "\u6700\u65B0\u7559\u5B58\u89C2\u5BDF\u5FEB\u7167" }),
+      body: Type19.Optional(Type19.String({
+        minLength: 1,
+        description: "\u89D2\u8272\u5224\u5B9A\u7684\u8BF7\u6C42\u6B63\u6587\uFF1Brequest-manifest \u672A\u6536\u5F55\u8BE5 requestId \u65F6\u5FC5\u586B"
+      }))
+    }, { additionalProperties: false });
+    COLLECTOR_HANDBOOK_MAX_BYTES = 64 * 1024;
+    collectorHandbookWriteArgsSchema = Type19.Object({
+      scope: Type19.Union([
+        Type19.Literal("general"),
+        Type19.Literal("repo")
+      ], { description: "general\uFF1D\u901A\u7528\u624B\u518C\uFF1Brepo\uFF1D\u5F53\u524D\u4ED3\u5E93\u5DEE\u5F02" }),
+      body: Type19.String({
+        description: `\u624B\u518C\u5168\u6587\uFF08opaque \u5DE5\u4F5C\u8BB0\u5FC6\uFF1B\u6574\u4EFD\u66FF\u6362\uFF1BUTF-8 \u81F3\u591A ${COLLECTOR_HANDBOOK_MAX_BYTES} \u5B57\u8282\uFF09`
+      })
+    }, { additionalProperties: false });
+    collectorReadArgsSchema = Type19.Object({
+      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,
+        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({
+        description: "\u89D2\u8272\u5224\u5B9A\u7684\u672C\u4ED3 PR \u53F7\uFF08\u6B63\u6574\u6570\uFF09\u3002\u4E0E issueNumber \u4E8C\u9009\u4E00\u6216\u540C\u6307\u552F\u4E00\u76EE\u6807\u3002\u5F62\u72B6\u6307\u5F15\uFF0C\u975E schema \u95F8\u3002"
+      })),
+      issueNumber: Type19.Optional(Type19.Unknown({
+        description: "\u89D2\u8272\u5224\u5B9A\u7684\u672C\u4ED3 issue \u53F7\uFF08\u6B63\u6574\u6570\uFF09\uFF1Bruntime \u7ECF\u7EBF\u4E0A\u5173\u8054\u89E3\u6790\u552F\u4E00 PR\u3002\u5F62\u72B6\u6307\u5F15\uFF0C\u975E schema \u95F8\u3002"
+      }))
+    }, { additionalProperties: true });
+    collectorFindingItemDeclaration = (() => {
+      const item = Type19.Object(
+        {
+          evidenceId: Type19.Unknown({
+            description: "observe \u8FD4\u56DE\u7684\u6750\u6599\u6307\u9488\uFF08\u5FC5\u586B\u8BED\u4E49\uFF09"
+          }),
+          category: Type19.Unknown({
+            description: "\u7B80\u77ED\u5F52\u7C7B\u6807\u7B7E\uFF0C\u4E0D\u662F\u6458\u8981"
+          }),
+          summary: Type19.Unknown({
+            description: "\u54EA\u4E2A bot\u3001\u4EC0\u4E48\u95EE\u9898\u7684\u6458\u8981\uFF1B\u4E0D\u8A8A\u6284\u6B63\u6587"
+          })
+        },
+        {
+          additionalProperties: true,
+          description: "\u5355\u6761 finding \u6307\u9488\uFF1AevidenceId + \u53EF\u9009 category/summary\u3002\u5F62\u72B6\u6307\u5F15\uFF0C\u975E schema \u95F8\u3002"
+        }
+      );
+      item.required = [];
+      return item;
+    })();
+    collectorOutputBaseSchema = openToolObject(
+      Type19.Object({
+        // No root type:array — host must not shape-reject non-array findings (#676 C).
+        // Nested item declarations ride `items` for registration preservation (ADR 0057).
+        findings: Type19.Unsafe({
+          description: "\u672C\u6B21\u6536\u96C6\u5230\u7684\u9010\u6761 findings\uFF08\u6307\u9488\u6570\u7EC4\u4E3A\u89C4\u8303\u5F62\uFF09\u3002\u96F6 finding \u7684\u6A21\u677F\u901A\u77E5\u4E0D\u5F97\u8FDB\u5165\uFF1B\u6B63\u5E38\u5B8C\u5DE5\u65E0 finding \u65F6\u7701\u7565\u3002\u5F62\u72B6\u6307\u5F15\uFF0C\u975E schema \u95F8\u3002",
+          items: collectorFindingItemDeclaration
+        }),
+        unfinishedReasons: Type19.Unknown({
+          description: "\u672A\u5B8C\u6210\u539F\u56E0\u5B57\u7B26\u4E32\u6570\u7EC4\uFF08\u989D\u5EA6/\u6545\u969C/\u7B49\u5F85\u5C4A\u6EE1\u7B49\u73B0\u573A\u4F9D\u636E\uFF09\uFF1B\u4E0D\u5F97\u628A\u672A\u5B8C\u6210\u8868\u8FF0\u4E3A\u65E0\u95EE\u9898\u3002\u65E0\u53EF\u62A5\u544A\u65F6\u7701\u7565\u3002\u5F62\u72B6\u6307\u5F15\uFF0C\u975E schema \u95F8\u3002"
+        })
+      })
+    );
+    collectorOutputArgsSchema = withInfrastructureFailureDeclaration(
+      collectorOutputBaseSchema
+    );
+  }
+});
+
+// src/collector-handbook.ts
+import { readFile as readFile18 } from "node:fs/promises";
+import { join as join33, sep as sep4 } from "node:path";
+function resolveCollectorHandbookRoot(sessionPath) {
+  if (typeof sessionPath !== "string" || sessionPath.trim().length === 0) {
+    throw new Error("\u901A\u8FDB\u53F8\u624B\u518C\u8981\u6C42\u975E\u7A7A session \u8DEF\u5F84\uFF0C\u4E14\u4F4D\u4E8E books/<bookKey>/");
+  }
+  const segments = sessionPath.split(sep4);
+  let bookKey;
+  for (let i = 0; i + 3 < segments.length; i += 1) {
+    if (segments[i] === ".ak-roles" && segments[i + 1] === "books") {
+      const candidate = segments[i + 2];
+      if (candidate.length > 0) {
+        bookKey = candidate;
+        break;
+      }
+    }
+  }
+  if (bookKey === void 0) {
+    throw new Error(
+      `\u901A\u8FDB\u53F8\u624B\u518C\u8981\u6C42 session \u4F4D\u4E8E books/<bookKey>/\uFF1B\u6536\u5230 ${sessionPath}`
+    );
+  }
+  if (bookKey === "." || bookKey === "..") {
+    throw new Error(`\u901A\u8FDB\u53F8\u624B\u518C\u62D2\u7EDD\u4E0D\u5B89\u5168 bookKey ${JSON.stringify(bookKey)}`);
+  }
+  const ledgerHome = resolveActivationLedgerHomeForPath(sessionPath);
+  const root = join33(activationBookDirectory(ledgerHome, bookKey), "collector-handbook");
+  return { ledgerHome, bookKey, root };
+}
+function collectorHandbookRepoFileName(repositoryCanonical) {
+  if (!/^[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/.test(repositoryCanonical)) {
+    throw new Error(
+      `\u901A\u8FDB\u53F8\u624B\u518C\u4ED3\u5E93\u6587\u4EF6\u8981\u6C42\u89C4\u8303 owner/repo\uFF0C\u6536\u5230 ${JSON.stringify(repositoryCanonical)}`
+    );
+  }
+  return `${repositoryCanonical.replaceAll("/", "__")}.md`;
+}
+function createCollectorHandbookStore(input) {
+  const generalPath = join33(input.handbookRoot, "general.md");
+  const repoDir = join33(input.handbookRoot, "repos");
+  const repoPath = join33(repoDir, collectorHandbookRepoFileName(input.repositoryCanonical));
+  const assertHandbookBudget = (body, label) => {
+    const byteLength = Buffer.byteLength(body, "utf8");
+    if (byteLength > COLLECTOR_HANDBOOK_MAX_BYTES) {
+      throw new Error(
+        `\u901A\u8FDB\u53F8\u624B\u518C${label} UTF-8 \u81F3\u591A ${COLLECTOR_HANDBOOK_MAX_BYTES} \u5B57\u8282\uFF0C\u6536\u5230 ${byteLength}`
+      );
+    }
+    return byteLength;
+  };
+  const readOptional = async (path, parentDir2) => {
+    ensureRealDirectoryTree(input.ledgerHome, parentDir2);
+    assertLedgerFileInsideHome(path, input.ledgerHome);
+    try {
+      const body = await readFile18(path, "utf8");
+      assertHandbookBudget(body, "\u6B63\u6587");
+      return body;
+    } catch (error) {
+      if (isNotFound(error)) return void 0;
+      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 !== void 0) {
+        return {
+          general: bookGeneral,
+          repo: bookRepo ?? "",
+          generalSource: "book",
+          repoSource: bookRepo === void 0 ? "empty" : "book",
+          generalPath,
+          repoPath
+        };
+      }
+      const seed = input.seedGeneral;
+      if (typeof seed === "string" && seed.length > 0) {
+        assertHandbookBudget(seed, "\u6B63\u6587");
+        return {
+          general: seed,
+          repo: bookRepo ?? "",
+          generalSource: "seed",
+          repoSource: bookRepo === void 0 ? "empty" : "book",
+          generalPath,
+          repoPath
+        };
+      }
+      return {
+        general: "",
+        repo: bookRepo ?? "",
+        generalSource: "empty",
+        repoSource: bookRepo === void 0 ? "empty" : "book",
+        generalPath,
+        repoPath
+      };
+    },
+    async write(scope, body) {
+      const byteLength = assertHandbookBudget(body, "\u6B63\u6587");
+      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) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+var init_collector_handbook = __esm({
+  "src/collector-handbook.ts"() {
+    "use strict";
+    init_atomic_write();
+    init_activation_ledger_topology();
+    init_collector_tool_schemas();
+  }
+});
+
 // src/collector-receipt.ts
 function fail4(message) {
   throw new Error(message);
@@ -20351,22 +20615,46 @@ 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;
-  return [
+  const handbook = activation.handbookView;
+  const lines = [
     "<collector_method>",
     `host: github.com`,
     `repository: ${activation.repository.canonical}`,
-    `prNumber: ${pr === void 0 ? "unbound \u2014 call ak_collector_bind_target with the role-decided issue/PR before observe" : String(pr)}`,
+    `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}`,
     "</collector_method>"
-  ].join("\n");
+  ];
+  if (handbook.general.length > 0 || handbook.repo.length > 0) {
+    const payload = JSON.stringify({
+      general: handbook.general,
+      repo: handbook.repo,
+      generalSource: handbook.generalSource,
+      repoSource: handbook.repoSource,
+      repository: activation.repository.canonical
+    }).replaceAll("<", "\\u003c");
+    lines.push("", "<collector_handbook>", payload, "</collector_handbook>");
+  }
+  return lines.join("\n");
 }
 function parsePositiveTicket(raw, label) {
   if (raw === void 0 || raw === null) return void 0;
   if (typeof raw === "number" && Number.isSafeInteger(raw) && raw >= 1) return raw;
   if (typeof raw === "string" && /^[1-9]\d*$/.test(raw.trim())) return Number(raw.trim());
-  throw new CollectorTargetBindError(`ak_collector_bind_target ${label} must be a positive safe integer`);
+  throw new CollectorTargetBindError(`\u901A\u8FDB\u53F8\u7ED1\u5B9A ${label} \u987B\u4E3A\u6B63\u5B89\u5168\u6574\u6570`);
 }
 function createCollectorRoleRuntime(pi, dependencies, hostActions) {
   let toolsRegistered = false;
@@ -20377,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");
       }
@@ -20388,20 +20677,36 @@ 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
       );
+      const sessionPath = ctx.sessionManager?.getSessionFile?.() ?? ctx.sessionManager?.getSessionDir?.();
+      if (typeof sessionPath !== "string" || sessionPath.length === 0) {
+        throw new Error("\u901A\u8FDB\u53F8\u624B\u518C\u8981\u6C42 session \u8DEF\u5F84\u4F4D\u4E8E books/<bookKey>/");
+      }
+      const placement = resolveCollectorHandbookRoot(sessionPath);
+      const seedGeneral = dependencies.loadHandbookSeed === void 0 ? void 0 : (await dependencies.loadHandbookSeed()).trim();
+      const handbook = createCollectorHandbookStore({
+        ledgerHome: placement.ledgerHome,
+        handbookRoot: placement.root,
+        repositoryCanonical: repository.canonical,
+        ...seedGeneral === void 0 || seedGeneral.length === 0 ? {} : { seedGeneral }
+      });
+      const handbookView = await handbook.read();
       return {
         soul,
         repository,
         manifest,
         ledger,
         transport,
-        clock
+        clock,
+        handbook,
+        handbookView
       };
     },
     assembleMaterials(activation, baseSystemPrompt) {
@@ -20454,7 +20759,7 @@ function createCollectorRoleRuntime(pi, dependencies, hostActions) {
             const issueNumber = parsePositiveTicket(params.issueNumber, "issueNumber");
             if (prNumber === void 0 && issueNumber === void 0) {
               throw new CollectorTargetBindError(
-                "ak_collector_bind_target requires role-decided prNumber and/or issueNumber"
+                "\u901A\u8FDB\u53F8\u7ED1\u5B9A\u987B\u7531\u89D2\u8272\u5224\u5B9A prNumber \u4E0E/\u6216 issueNumber"
               );
             }
             let bound = prNumber;
@@ -20466,18 +20771,18 @@ function createCollectorRoleRuntime(pi, dependencies, hostActions) {
               });
               if (associated.length === 0) {
                 throw new CollectorTargetBindError(
-                  `no PR associated with issue #${issueNumber} in ${activation.repository.canonical}; pass an explicit --pr or a different issueNumber`
+                  `${activation.repository.canonical} \u7684 issue #${issueNumber} \u65E0\u5173\u8054 PR\uFF1B\u8BF7\u6539\u7528\u660E\u786E --pr \u6216\u5176\u4ED6 issueNumber`
                 );
               }
               if (associated.length > 1) {
                 throw new CollectorTargetBindError(
-                  `multiple PRs associated with issue #${issueNumber}: ${associated.join(", ")}; pass an explicit prNumber or --pr`
+                  `issue #${issueNumber} \u5173\u8054\u591A\u4E2A PR\uFF1A${associated.join("\u3001")}\uFF1B\u8BF7\u6539\u7528\u660E\u786E prNumber \u6216 --pr`
                 );
               }
               const fromIssue = associated[0];
               if (prNumber !== void 0 && prNumber !== fromIssue) {
                 throw new CollectorTargetBindError(
-                  `prNumber ${prNumber} conflicts with issue #${issueNumber} association PR ${fromIssue}`
+                  `prNumber ${prNumber} \u4E0E issue #${issueNumber} \u5173\u8054 PR ${fromIssue} \u51B2\u7A81`
                 );
               }
               bound = fromIssue;
@@ -20569,8 +20874,8 @@ function createCollectorRoleRuntime(pi, dependencies, hostActions) {
       pi.registerTool({
         name: COLLECTOR_REQUEST_TOOL,
         label: "\u901A\u8FDB\u53F8\u8BF7\u6C42",
-        description: "\u6309\u914D\u7F6E\u8BF7\u6C42\u4F53\u4E0E\u5173\u8054\u6807\u8BB0\uFF0C\u5728\u6240\u5F15\u6700\u65B0\u5FEB\u7167 HEAD \u53D1\u4E00\u6B21\u8BF7\u6C42\u3002",
-        promptSnippet: "\u6309\u914D\u7F6E\u53D1\u4E00\u6B21\u8BF7\u6C42",
+        description: "\u5728\u6240\u5F15\u6700\u65B0\u5FEB\u7167 HEAD \u53D1\u4E00\u6B21\u8BF7\u6C42\u3002requestId \u53EF\u53D6\u914D\u7F6E\u6E05\u5355\uFF0C\u6216\u89D2\u8272\u4F9D\u624B\u518C/\u73B0\u573A\u5224\u5B9A\u7684\u7A33\u5B9A id\uFF1B\u540E\u8005\u987B\u540C\u65F6\u63D0\u4F9B body\u3002",
+        promptSnippet: "\u53D1\u4E00\u6B21\u8BC4\u5BA1\u8BF7\u6C42",
         parameters: requestSchema,
         async execute(toolCallId, params, signal, _onUpdate, ctx) {
           const activation = getActivation();
@@ -20578,7 +20883,11 @@ function createCollectorRoleRuntime(pi, dependencies, hostActions) {
           try {
             activation.ledger.beginOperational(COLLECTOR_REQUEST_TOOL, toolCallId);
             const details = await activation.ledger.request(
-              params,
+              {
+                requestId: params.requestId,
+                snapshotId: params.snapshotId,
+                ...typeof params.body === "string" ? { body: params.body } : {}
+              },
               activation.transport,
               activation.clock,
               signal
@@ -20597,11 +20906,95 @@ function createCollectorRoleRuntime(pi, dependencies, hostActions) {
           }
         }
       });
+      pi.registerTool({
+        name: COLLECTOR_HANDBOOK_WRITE_TOOL,
+        label: "\u901A\u8FDB\u53F8\u624B\u518C\u5199\u5165",
+        description: "\u5199\u5165\u901A\u7528\u624B\u518C\u6216\u5F53\u524D\u4ED3\u5E93\u5DEE\u5F02\u5168\u6587\uFF08\u6574\u4EFD\u66FF\u6362\uFF09\u3002",
+        promptSnippet: "\u66F4\u65B0 bot \u624B\u518C",
+        parameters: handbookWriteSchema,
+        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_HANDBOOK_WRITE_TOOL, toolCallId);
+            const details = await activation.handbook.write(params.scope, params.body);
+            activation.handbookView = await activation.handbook.read();
+            activation.ledger.completeOperational(toolCallId);
+            return {
+              content: [{
+                type: "text",
+                text: `\u624B\u518C\u5DF2\u5199\u5165\uFF1A${details.scope}`
+              }],
+              details: {
+                scope: details.scope,
+                path: details.path,
+                byteLength: details.byteLength,
+                generalSource: activation.handbookView.generalSource,
+                repoSource: activation.handbookView.repoSource
+              }
+            };
+          } catch (error) {
+            if (isCorrectableExecuteError(error)) throw error;
+            hostActions.failInfrastructure(error, ctx, toolCallId);
+          } finally {
+            try {
+              activation.ledger.completeOperational(toolCallId);
+            } catch {
+            }
+          }
+        }
+      });
+      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();
@@ -20622,6 +21015,7 @@ function createCollectorRoleRuntime(pi, dependencies, hostActions) {
               details
             };
           } catch (error) {
+            if (isCorrectableExecuteError(error)) throw error;
             hostActions.failInfrastructure(error, ctx, toolCallId);
           }
         }
@@ -20674,13 +21068,14 @@ function createCollectorRoleRuntime(pi, dependencies, hostActions) {
     }
   };
 }
-var CollectorNormalCompletionDeclarationError, CollectorTargetBindError, COLLECTOR_REQUIRED_TOOLS, COLLECTOR_TRANSPORT_FLAGS, observeSchema, readSchema, requestSchema, waitSchema, bindSchema, 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";
     init_collector_config();
     init_collector_evidence();
     init_collector_github();
+    init_collector_handbook();
     init_collector_ledger();
     init_collector_receipt();
     init_collector_tool_schemas();
@@ -20705,7 +21100,9 @@ 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
     ];
     COLLECTOR_TRANSPORT_FLAGS = Object.freeze([
@@ -20729,13 +21126,22 @@ 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;
     outputSchema = collectorOutputArgsSchema;
   }
 });
@@ -21846,11 +22252,11 @@ function reliableWindow(cwd, baseline, head) {
   const raw = git2(cwd, ["log", "--format=%P%x1e%s", range]);
   if (raw.length === 0) return [];
   return raw.split("\n").flatMap((line2) => {
-    const sep4 = line2.indexOf("");
-    if (sep4 < 0) return [];
+    const sep5 = line2.indexOf("");
+    if (sep5 < 0) return [];
     return [{
-      subject: line2.slice(sep4 + 1),
-      merge: line2.slice(0, sep4).trim().includes(" ")
+      subject: line2.slice(sep5 + 1),
+      merge: line2.slice(0, sep5).trim().includes(" ")
     }];
   });
 }
@@ -22468,8 +22874,8 @@ var init_activation_reconciliation = __esm({
 
 // src/role-runtime.ts
 import { readFileSync as readFileSync5, writeSync as writeSync4 } from "node:fs";
-import { join as join32 } from "node:path";
-import { Value as Value5 } from "typebox/value";
+import { join as join34 } from "node:path";
+import { Value as Value4 } from "typebox/value";
 function decodeReviewerAdmittedInputs(getFlag) {
   let reviewScopeKeys;
   const rawScopeKeys = getFlag("ak-review-scope-keys");
@@ -22596,7 +23002,7 @@ function activationStage(role, runtime) {
   }
 }
 function validateActivationTraceRecord(record4) {
-  if (!Value5.Check(activationTraceRecordSchema, record4)) {
+  if (!Value4.Check(activationTraceRecordSchema, record4)) {
     throw new TypeError("Activation trace record does not match its closed contract");
   }
   return record4;
@@ -22840,7 +23246,7 @@ function readDiaristRunCoordinates() {
   if (typeof runDirectory !== "string" || runDirectory.trim() === "") {
     throw new Error("diarist accept requires AK_ROLE_RUN_DIR");
   }
-  const admittedPath = join32(runDirectory, "admitted-request.json");
+  const admittedPath = join34(runDirectory, "admitted-request.json");
   const admitted = JSON.parse(readFileSync5(admittedPath, "utf8"));
   if (typeof admitted.projectRoot !== "string" || admitted.projectRoot.trim() === "") {
     throw new Error(`diarist admitted-request missing projectRoot (${admittedPath})`);
@@ -23458,7 +23864,8 @@ function createRoleRuntimeExtension(dependencies) {
             dossierEntries: context.sessionManager?.getEntries?.() ?? []
           });
         },
-        ...dependencies.createCollectorClock === void 0 ? {} : { createClock: dependencies.createCollectorClock }
+        ...dependencies.createCollectorClock === void 0 ? {} : { createClock: dependencies.createCollectorClock },
+        ...dependencies.loadCollectorHandbookSeed === void 0 ? {} : { loadHandbookSeed: dependencies.loadCollectorHandbookSeed }
       },
       hostActions
     );
@@ -24199,9 +24606,9 @@ __export(in_process_session_exports, {
   DEFAULT_COMPLIANCE_IDLE_MAX_RETRIES: () => DEFAULT_COMPLIANCE_IDLE_MAX_RETRIES,
   openPiInProcessSession: () => openPiInProcessSession
 });
-import { mkdtemp as mkdtemp2, rm as rm2 } from "node:fs/promises";
+import { mkdtemp as mkdtemp2, rm as rm3 } from "node:fs/promises";
 import { tmpdir as tmpdir2 } from "node:os";
-import { join as join33 } from "node:path";
+import { join as join35 } from "node:path";
 import {
   createAgentSession,
   DefaultResourceLoader,
@@ -24324,7 +24731,7 @@ async function openPiInProcessSession(options) {
   let scratchDir;
   let resolvedAgentDir = options.agentDir;
   if (resolvedAgentDir === void 0) {
-    scratchDir = await mkdtemp2(join33(options.credentialScratchParent ?? tmpdir2(), "ak-institutional-"));
+    scratchDir = await mkdtemp2(join35(options.credentialScratchParent ?? tmpdir2(), "ak-institutional-"));
     resolvedAgentDir = scratchDir;
   }
   try {
@@ -24806,7 +25213,7 @@ async function openPiInProcessSession(options) {
         }
         if (scratchDir !== void 0) {
           try {
-            await rm2(scratchDir, { recursive: true, force: true });
+            await rm3(scratchDir, { recursive: true, force: true });
           } catch (error) {
             cleanupFailures.push(error);
           }
@@ -24831,7 +25238,7 @@ async function openPiInProcessSession(options) {
   } catch (openError) {
     if (scratchDir !== void 0) {
       try {
-        await rm2(scratchDir, { recursive: true, force: true });
+        await rm3(scratchDir, { recursive: true, force: true });
       } catch (cleanupFailure) {
         throw new AggregateError(
           [openError, cleanupFailure],
@@ -25018,9 +25425,9 @@ var init_reviewer_child_executor = __esm({
 
 // src/reviewer-workspace.ts
 import { spawn as spawn4 } from "node:child_process";
-import { mkdtemp as mkdtemp3, rm as rm3 } from "node:fs/promises";
+import { mkdtemp as mkdtemp3, rm as rm4 } from "node:fs/promises";
 import { tmpdir as tmpdir3 } from "node:os";
-import { join as join34 } from "node:path";
+import { join as join36 } from "node:path";
 async function runCommand(command, args, options = {}) {
   return await new Promise((resolve20, reject) => {
     const child = spawn4(command, args, { ...options.cwd === void 0 ? {} : { cwd: options.cwd }, stdio: ["ignore", "pipe", "pipe"], signal: options.signal });
@@ -25069,8 +25476,8 @@ async function prepareSnapshot(accepted, signal, dependencies) {
     if (!sameReviewerPinnedTarget({ repositoryRoot: accepted.repositoryRoot, objectFormat, targetHead }, accepted)) throw new Error("Accepted Reviewer target identity no longer matches the repository");
     await git3(accepted.repositoryRoot, ["cat-file", "-e", `${targetHead}^{commit}`], signal);
     dependencies.fault?.("mirror.before-create");
-    mirrorRoot = await mkdtemp3(join34(tmpdir3(), "ak-reviewer-snapshot-"));
-    const mirrorPath = join34(mirrorRoot, "repository.git");
+    mirrorRoot = await mkdtemp3(join36(tmpdir3(), "ak-reviewer-snapshot-"));
+    const mirrorPath = join36(mirrorRoot, "repository.git");
     dependencies.fault?.("mirror.create");
     await runCommand("git", ["init", "--bare", `--object-format=${accepted.objectFormat}`, mirrorPath], signal === void 0 ? {} : { signal });
     await git3(mirrorPath, ["fetch", "--no-tags", accepted.repositoryRoot, targetHead], signal);
@@ -25087,7 +25494,7 @@ async function prepareClone(snapshot, signal, dependencies) {
   const target = { repositoryRoot: snapshot.repositoryRoot, objectFormat: snapshot.objectFormat, targetHead: snapshot.targetHead, refs: { ...snapshot.refs } };
   try {
     dependencies.fault?.("workspace.before-create");
-    workspace = await mkdtemp3(join34(tmpdir3(), "ak-reviewer-leg-"));
+    workspace = await mkdtemp3(join36(tmpdir3(), "ak-reviewer-leg-"));
     dependencies.fault?.("workspace.init");
     await git3(workspace, ["init", `--object-format=${snapshot.objectFormat}`, "--initial-branch=ak-reviewer-unborn"], signal);
     dependencies.fault?.("workspace.fetch");
@@ -25121,12 +25528,12 @@ function createReviewerWorkspaceOwner(dependencies = {}) {
       return Object.freeze({ target: frozenTarget, workspaces: Object.freeze(workspaces) });
     },
     async dispose(workspace) {
-      await rm3(workspace.path, { recursive: true, force: false });
+      await rm4(workspace.path, { recursive: true, force: false });
       return "deleted";
     },
     async shutdown() {
       if (ownedSnapshot === void 0) return;
-      cleanupPromise ??= rm3(ownedSnapshot.mirrorRoot, { recursive: true, force: false });
+      cleanupPromise ??= rm4(ownedSnapshot.mirrorRoot, { recursive: true, force: false });
       await cleanupPromise;
     }
   };
@@ -25288,7 +25695,7 @@ var init_reviewer_agent = __esm({
 });
 
 // src/acp-host/production-host.ts
-import { readFile as readFile20 } from "node:fs/promises";
+import { readFile as readFile21 } from "node:fs/promises";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 
 // src/canonical-skill-binding.ts
@@ -25502,9 +25909,9 @@ init_auditor_soul();
 init_session_opening_materials();
 
 // src/acp-host/description.ts
-import { join as join35 } from "node:path";
+import { join as join37 } from "node:path";
 function resolveAcpBinary(description, operatorHome) {
-  return join35(operatorHome, ...description.binaryFromHome);
+  return join37(operatorHome, ...description.binaryFromHome);
 }
 function acpStdioArgs(description, model, seat) {
   const { prefix, suffix, modelFlag, thinkingFlag } = description.argv;
@@ -25527,10 +25934,10 @@ init_gatekeeper_pass_envelope();
 init_packaged_role_registry();
 init_method_skill();
 init_role_runtime();
-import { randomUUID as randomUUID6 } from "node:crypto";
-import { mkdir as mkdir5, readFile as readFile18, writeFile as writeFile8 } from "node:fs/promises";
+import { randomUUID as randomUUID7 } from "node:crypto";
+import { mkdir as mkdir5, readFile as readFile19, writeFile as writeFile9 } from "node:fs/promises";
 import { createServer } from "node:net";
-import { basename as basename7, dirname as dirname17, join as join36 } from "node:path";
+import { basename as basename7, dirname as dirname18, join as join38 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
 // src/acp-host/role-turn-host.ts
@@ -25829,7 +26236,7 @@ function buildAcpSkillExpansion(methodSkills, prompt) {
   return Object.freeze({
     name: parsed.name,
     location: method.path,
-    content: `References are relative to ${dirname17(method.path)}.
+    content: `References are relative to ${dirname18(method.path)}.
 
 ${method.body}`,
     userMessage: parsed.userMessage
@@ -25861,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;
 }
@@ -25881,7 +26289,7 @@ function createComposedAcpRoleTurnHost(config) {
       dependencies: config.roleRuntimeDependencies,
       // Same durable-principal path settlement uses for isAvailable (#617 DK-4 layout).
       sessionFile: config.sessionIdentity.resolveSessionFile(request.principal),
-      socketPath: config.socketPath?.(request) ?? `/tmp/ak-acp-mcp-${randomUUID6()}.sock`
+      socketPath: config.socketPath?.(request) ?? `/tmp/ak-acp-mcp-${randomUUID7()}.sock`
     })
   });
 }
@@ -25913,19 +26321,19 @@ async function prepareAcpRoleEnvelope(options) {
   let rejection;
   let infrastructureRoundFailure;
   const hostAbort = new AbortController();
-  const runId = request.runDirectory.split("/").filter(Boolean).at(-1) ?? randomUUID6();
+  const runId = request.runDirectory.split("/").filter(Boolean).at(-1) ?? randomUUID7();
   await mkdir5(request.runDirectory, { recursive: true });
   for (const method of request.methods) {
     if (method.kind !== "skill") continue;
-    const name = basename7(dirname17(method.path));
-    const raw = await readFile18(method.path, "utf8");
+    const name = basename7(dirname18(method.path));
+    const raw = await readFile19(method.path, "utf8");
     methodSkills.set(name, { path: method.path, body: stripSkillFrontmatter(raw).trim() });
   }
-  let sessionFile = options.sessionFile ?? join36(request.runDirectory, "session", "session.jsonl");
-  await mkdir5(dirname17(sessionFile), { recursive: true });
+  let sessionFile = options.sessionFile ?? join38(request.runDirectory, "session", "session.jsonl");
+  await mkdir5(dirname18(sessionFile), { recursive: true });
   if (request.continuation.kind !== "resume") {
     try {
-      await writeFile8(
+      await writeFile9(
         sessionFile,
         `${JSON.stringify({
           type: "session",
@@ -25949,7 +26357,7 @@ async function prepareAcpRoleEnvelope(options) {
       getLeafEntry: () => sessionEntries.at(-1),
       getLeafId: () => runId,
       getEntries: () => sessionEntries,
-      getSessionDir: () => dirname17(sessionFile),
+      getSessionDir: () => dirname18(sessionFile),
       getSessionFile: () => sessionFile,
       getHeader: () => ({ type: "session", id: runId }),
       setSessionFile(path) {
@@ -26050,7 +26458,7 @@ async function prepareAcpRoleEnvelope(options) {
     }
   };
   createRoleRuntimeExtension(options.dependencies)(envelope);
-  const token = randomUUID6();
+  const token = randomUUID7();
   const server = createServer((socket) => serveSocket(socket));
   function rememberProjectedRejection(details, toolCallId) {
     if (typeof details !== "object" || details === null) return;
@@ -26127,7 +26535,7 @@ async function prepareAcpRoleEnvelope(options) {
   async function invokeAkTool(name, args) {
     const tool = tools.get(name);
     if (tool === void 0) throw new Error(`Unknown AK tool: ${name}`);
-    const toolCallId = randomUUID6();
+    const toolCallId = randomUUID7();
     calls.push({ toolCallId, toolName: name });
     sessionEntries.push({
       type: "message",
@@ -26335,7 +26743,7 @@ async function prepareAcpRoleEnvelope(options) {
         message: { role: "user", content: prompt }
       });
     }
-    const methodPrompt = (await Promise.all(request.methods.map(({ path }) => readFile18(path, "utf8")))).join("\n\n");
+    const methodPrompt = (await Promise.all(request.methods.map(({ path }) => readFile19(path, "utf8")))).join("\n\n");
     const promptResults = await emit("before_agent_start", {
       prompt,
       systemPrompt: methodPrompt,
@@ -26396,12 +26804,12 @@ async function prepareAcpRoleEnvelope(options) {
 // src/acp-host/seat-profile-soul.ts
 import { constants as constants3 } from "node:fs";
 import { access as access4, copyFile, lstat as lstat6, mkdir as mkdir6, readlink, symlink, unlink as unlink4 } from "node:fs/promises";
-import { dirname as dirname18, join as join37, relative as relative3, resolve as resolve19 } from "node:path";
+import { dirname as dirname19, join as join39, relative as relative3, resolve as resolve19 } from "node:path";
 function seatProfileName(spec, role) {
   return `${spec.namePrefix}${role}`;
 }
 function packageRoleSoulPath(packageRoot, role) {
-  return join37(packageRoot, "souls", `${role}.md`);
+  return join39(packageRoot, "souls", `${role}.md`);
 }
 async function pathExists(path) {
   try {
@@ -26418,16 +26826,16 @@ async function ensureSeatProfileSoul(options) {
   if (!await pathExists(soulTarget)) {
     throw new Error(`packaged role soul missing: ${soulTarget}`);
   }
-  const profilesRoot = join37(operatorHome, ...spec.profilesRootFromHome);
-  const profileDir = join37(profilesRoot, profileName);
-  const hostRoot = dirname18(profilesRoot);
-  const soulPath = join37(profileDir, spec.soulFileName);
+  const profilesRoot = join39(operatorHome, ...spec.profilesRootFromHome);
+  const profileDir = join39(profilesRoot, profileName);
+  const hostRoot = dirname19(profilesRoot);
+  const soulPath = join39(profileDir, spec.soulFileName);
   if (!await pathExists(profileDir)) {
     await mkdir6(profileDir, { recursive: true });
     for (const name of ["auth.json", ".env", "config.yaml"]) {
-      const source = join37(hostRoot, name);
+      const source = join39(hostRoot, name);
       if (!await pathExists(source)) continue;
-      await copyFile(source, join37(profileDir, name));
+      await copyFile(source, join39(profileDir, name));
     }
   } else {
     await mkdir6(profileDir, { recursive: true });
@@ -26453,17 +26861,17 @@ async function ensureSeatProfileSoul(options) {
 }
 
 // src/acp-host/session-identity.ts
-import { mkdir as mkdir7, readFile as readFile19, rename, writeFile as writeFile9 } from "node:fs/promises";
-import { dirname as dirname19, join as join38 } from "node:path";
+import { mkdir as mkdir7, readFile as readFile20, rename as rename2, writeFile as writeFile10 } from "node:fs/promises";
+import { dirname as dirname20, join as join40 } from "node:path";
 function createAcpSessionIdentityAuthority(authority, sessionBindingFile) {
-  const bindingPath = (principal) => join38(authority.decode(principal).sessionDirectory, sessionBindingFile);
+  const bindingPath = (principal) => join40(authority.decode(principal).sessionDirectory, sessionBindingFile);
   return {
     resolveSessionFile(principal) {
       return authority.decode(principal).sessionFile;
     },
     async load(principal) {
       try {
-        const value = JSON.parse(await readFile19(bindingPath(principal), "utf8"));
+        const value = JSON.parse(await readFile20(bindingPath(principal), "utf8"));
         if (typeof value !== "object" || value === null || typeof value.sessionId !== "string") {
           throw new Error("durable ACP session binding is invalid");
         }
@@ -26475,11 +26883,11 @@ function createAcpSessionIdentityAuthority(authority, sessionBindingFile) {
     },
     async bind(principal, sessionId) {
       const target = bindingPath(principal);
-      await mkdir7(dirname19(target), { recursive: true });
+      await mkdir7(dirname20(target), { recursive: true });
       const temporary = `${target}.${process.pid}.tmp`;
-      await writeFile9(temporary, `${JSON.stringify({ sessionId })}
+      await writeFile10(temporary, `${JSON.stringify({ sessionId })}
 `, { encoding: "utf8", mode: 384 });
-      await rename(temporary, target);
+      await rename2(temporary, target);
     }
   };
 }
@@ -26488,6 +26896,9 @@ function createAcpSessionIdentityAuthority(authority, sessionBindingFile) {
 var navigatorRoutePlaybookPath = fileURLToPath3(
   new URL("../../resources/navigator-route-playbook.md", import.meta.url)
 );
+var collectorHandbookSeedPath = fileURLToPath3(
+  new URL("../../resources/collector-bot-handbook.md", import.meta.url)
+);
 function createAcpRoleRuntimeDependencies(packageRoot) {
   const doctorAuditor = createPiDoctorAuditor();
   const reviewerAgent = createPerDispatchReviewerAgent({ packageRoot });
@@ -26495,13 +26906,14 @@ function createAcpRoleRuntimeDependencies(packageRoot) {
   return {
     loadJudgeSoul: () => loadMainRoleSessionMaterials("judge"),
     loadFixerSoul: () => loadMainRoleSessionMaterials("fixer"),
-    loadFixPacket: (path) => readFile20(path, "utf8"),
+    loadFixPacket: (path) => readFile21(path, "utf8"),
     loadCoderSoul: () => loadMainRoleSessionMaterials("coder"),
-    loadCoderTask: (path) => readFile20(path, "utf8"),
+    loadCoderTask: (path) => readFile21(path, "utf8"),
     loadReviewerSoul: () => loadMainRoleSessionMaterials("reviewer"),
     createReviewerPinnedGitReader: () => createReviewerPinnedGitReader(),
     createReviewerIssueFetcher: () => createGhIssueSoftFetcher(),
     loadCollectorSoul: () => loadMainRoleSessionMaterials("collector"),
+    loadCollectorHandbookSeed: () => readFile21(collectorHandbookSeedPath, "utf8"),
     createCollectorTransport: () => createGhCollectorGitHubTransport(),
     loadDoctorSoul: () => loadMainRoleSessionMaterials("doctor"),
     loadDoctorCase,
@@ -26515,7 +26927,7 @@ function createAcpRoleRuntimeDependencies(packageRoot) {
     loadDiaristSoul: () => loadMainRoleSessionMaterials("diarist"),
     loadNotarySourceRun: loadNotarySourceRunLocator,
     loadMergerSoul: () => loadMainRoleSessionMaterials("merger"),
-    loadMergerInput: async (path) => JSON.parse(await readFile20(path, "utf8")),
+    loadMergerInput: async (path) => JSON.parse(await readFile21(path, "utf8")),
     createMergerGitState: (repositoryRoot) => createProductionMergerGitState(repositoryRoot),
     async loadCanonicalSkillBinding(name) {
       if (name === "tdd") {
@@ -26544,7 +26956,7 @@ function createAcpRoleRuntimeDependencies(packageRoot) {
       authority: options.authority,
       invocationId: options.invocationId,
       loadSoul: () => loadMainRoleSessionMaterials("navigator"),
-      loadRoutePlaybook: () => readFile20(navigatorRoutePlaybookPath, "utf8"),
+      loadRoutePlaybook: () => readFile21(navigatorRoutePlaybookPath, "utf8"),
       loadRoleHelp: async (role) => formatNavigatorRoleHelp(role),
       createSession: navigatorSessionFactory,
       ...options.contextError === void 0 ? {} : { contextError: options.contextError },