@akagilnc/pi-workflow-roles 0.1.3783 → 0.1.3795

package/src/collector-role.ts

@@ -17,6 +17,7 @@ import {
   type CollectorRepository,
 } from "./collector-config.ts";
 import {
+  COLLECTOR_DEFAULT_WAIT_WINDOW_MS,
   createSystemCollectorClock,
   type CollectorClock,
 } from "./collector-evidence.ts";
@@ -25,9 +26,16 @@ import {
   listPullRequestNumbersByTicket,
   type CollectorGitHubTransport,
 } from "./collector-github.ts";
+import {
+  createCollectorHandbookStore,
+  resolveCollectorHandbookRoot,
+  type CollectorHandbookStore,
+} from "./collector-handbook.ts";
 import {
   COLLECTOR_BIND_TARGET_TOOL,
+  COLLECTOR_HANDBOOK_WRITE_TOOL,
   COLLECTOR_OBSERVE_TOOL,
+  COLLECTOR_OPEN_WAIT_WINDOW_TOOL,
   COLLECTOR_OUTPUT_TOOL,
   COLLECTOR_READ_TOOL,
   COLLECTOR_REQUEST_TOOL,
@@ -42,7 +50,9 @@ import {
 } from "./collector-receipt.ts";
 import {
   collectorBindTargetArgsSchema,
+  collectorHandbookWriteArgsSchema,
   collectorObserveArgsSchema,
+  collectorOpenWaitWindowArgsSchema,
   collectorOutputArgsSchema,
   collectorReadArgsSchema,
   collectorRequestArgsSchema,
@@ -76,7 +86,9 @@ export class CollectorTargetBindError extends CorrectableSubmissionError {
 
 export {
   COLLECTOR_BIND_TARGET_TOOL,
+  COLLECTOR_HANDBOOK_WRITE_TOOL,
   COLLECTOR_OBSERVE_TOOL,
+  COLLECTOR_OPEN_WAIT_WINDOW_TOOL,
   COLLECTOR_OUTPUT_TOOL,
   COLLECTOR_READ_TOOL,
   COLLECTOR_REQUEST_TOOL,
@@ -88,7 +100,9 @@ export const COLLECTOR_REQUIRED_TOOLS = [
   COLLECTOR_OBSERVE_TOOL,
   COLLECTOR_READ_TOOL,
   COLLECTOR_REQUEST_TOOL,
+  COLLECTOR_OPEN_WAIT_WINDOW_TOOL,
   COLLECTOR_WAIT_TOOL,
+  COLLECTOR_HANDBOOK_WRITE_TOOL,
   COLLECTOR_OUTPUT_TOOL,
 ] as const;
 
@@ -118,26 +132,50 @@ export const COLLECTOR_TRANSPORT_FLAGS = Object.freeze([
       type: "string" as const,
     }),
   }),
+  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" as const,
+    }),
+  }),
 ] as const);
 
 const observeSchema = collectorObserveArgsSchema;
 const readSchema = collectorReadArgsSchema;
 const requestSchema = collectorRequestArgsSchema;
+const openWaitWindowSchema = collectorOpenWaitWindowArgsSchema;
 const waitSchema = collectorWaitArgsSchema;
 const bindSchema = collectorBindTargetArgsSchema;
+const handbookWriteSchema = collectorHandbookWriteArgsSchema;
 const outputSchema = collectorOutputArgsSchema;
 
 type RequestParams = Static<typeof requestSchema>;
 type ReadParams = Static<typeof readSchema>;
+type OpenWaitWindowParams = Static<typeof openWaitWindowSchema>;
 type WaitParams = Static<typeof waitSchema>;
 type BindParams = Static<typeof bindSchema>;
+type HandbookWriteParams = Static<typeof handbookWriteSchema>;
 type OutputParams = Static<typeof outputSchema>;
 
+function parseWaitWindowMsFlag(raw: unknown): number {
+  if (raw === undefined || 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");
+}
+
 export type CollectorRoleDependencies = {
   loadSoul(): Promise<string>;
   createTransport(): CollectorGitHubTransport;
   createClock?(): CollectorClock;
   createLedger(config: CollectorConfigState, clock: CollectorClock, ctx: HostContext): CollectorLedger;
+  /** Optional packaged seed for first-use general handbook (#677). */
+  loadHandbookSeed?(): Promise<string>;
 };
 
 export type CollectorRoleHostActions = {
@@ -151,25 +189,52 @@ export type CollectorActivation = {
   ledger: CollectorLedger;
   transport: CollectorGitHubTransport;
   clock: CollectorClock;
+  handbook: CollectorHandbookStore;
+  /** Loaded at activate; refreshed after handbook write for same-session materials. */
+  handbookView: {
+    general: string;
+    repo: string;
+    generalSource: "book" | "seed" | "empty";
+    repoSource: "book" | "empty";
+    generalPath: string;
+    repoPath: string;
+  };
 };
 
 function buildMethodContext(activation: CollectorActivation): string {
   const pr = activation.ledger.config.prNumber;
-  return [
+  const handbook = activation.handbookView;
+  const lines = [
     "<collector_method>",
     `host: github.com`,
     `repository: ${activation.repository.canonical}`,
-    `prNumber: ${pr === undefined ? "unbound — call ak_collector_bind_target with the role-decided issue/PR before observe" : String(pr)}`,
+    `prNumber: ${pr === undefined ? "未绑定" : 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");
+  ];
+  // Opaque working memory only — no directional instructions (ADR 0073).
+  // JSON + `<` → \u003c keeps bodies from forging the delivery close tag (#677).
+  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: unknown, label: string): number | undefined {
   if (raw === undefined || raw === null) return undefined;
   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(`通进司绑定 ${label} 须为正安全整数`);
 }
 
 /**
@@ -205,6 +270,7 @@ export function createCollectorRoleRuntime(
       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");
       }
@@ -219,15 +285,36 @@ export function createCollectorRoleRuntime(
       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,
       );
 
+      // #677: handbook under admitted book topology (session path → books/<key>/collector-handbook).
+      const sessionPath = ctx.sessionManager?.getSessionFile?.()
+        ?? ctx.sessionManager?.getSessionDir?.();
+      if (typeof sessionPath !== "string" || sessionPath.length === 0) {
+        throw new Error("通进司手册要求 session 路径位于 books/<bookKey>/");
+      }
+      const placement = resolveCollectorHandbookRoot(sessionPath);
+      const seedGeneral = dependencies.loadHandbookSeed === undefined
+        ? undefined
+        : (await dependencies.loadHandbookSeed()).trim();
+      const handbook = createCollectorHandbookStore({
+        ledgerHome: placement.ledgerHome,
+        handbookRoot: placement.root,
+        repositoryCanonical: repository.canonical,
+        ...(seedGeneral === undefined || seedGeneral.length === 0
+          ? {}
+          : { seedGeneral }),
+      });
+      const handbookView = await handbook.read();
+
       return {
         soul,
         repository,
@@ -235,6 +322,8 @@ export function createCollectorRoleRuntime(
         ledger,
         transport,
         clock,
+        handbook,
+        handbookView,
       };
     },
 
@@ -297,7 +386,7 @@ export function createCollectorRoleRuntime(
             const issueNumber = parsePositiveTicket(params.issueNumber, "issueNumber");
             if (prNumber === undefined && issueNumber === undefined) {
               throw new CollectorTargetBindError(
-                "ak_collector_bind_target requires role-decided prNumber and/or issueNumber",
+                "通进司绑定须由角色判定 prNumber 与/或 issueNumber",
               );
             }
 
@@ -310,18 +399,18 @@ export function createCollectorRoleRuntime(
               });
               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} 的 issue #${issueNumber} 无关联 PR；请改用明确 --pr 或其他 issueNumber`,
                 );
               }
               if (associated.length > 1) {
                 throw new CollectorTargetBindError(
-                  `multiple PRs associated with issue #${issueNumber}: ${associated.join(", ")}; pass an explicit prNumber or --pr`,
+                  `issue #${issueNumber} 关联多个 PR：${associated.join("、")}；请改用明确 prNumber 或 --pr`,
                 );
               }
               const fromIssue = associated[0]!;
               if (prNumber !== undefined && prNumber !== fromIssue) {
                 throw new CollectorTargetBindError(
-                  `prNumber ${prNumber} conflicts with issue #${issueNumber} association PR ${fromIssue}`,
+                  `prNumber ${prNumber} 与 issue #${issueNumber} 关联 PR ${fromIssue} 冲突`,
                 );
               }
               bound = fromIssue;
@@ -422,8 +511,8 @@ export function createCollectorRoleRuntime(
       pi.registerTool({
         name: COLLECTOR_REQUEST_TOOL,
         label: "通进司请求",
-        description: "按配置请求体与关联标记，在所引最新快照 HEAD 发一次请求。",
-        promptSnippet: "按配置发一次请求",
+        description: "在所引最新快照 HEAD 发一次请求。requestId 可取配置清单，或角色依手册/现场判定的稳定 id；后者须同时提供 body。",
+        promptSnippet: "发一次评审请求",
         parameters: requestSchema,
         async execute(toolCallId: string, params: RequestParams, signal: AbortSignal | undefined, _onUpdate: unknown, ctx: HostContext) {
           const activation = getActivation();
@@ -431,7 +520,11 @@ export function createCollectorRoleRuntime(
           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,
@@ -451,11 +544,101 @@ export function createCollectorRoleRuntime(
         },
       });
 
+      pi.registerTool({
+        name: COLLECTOR_HANDBOOK_WRITE_TOOL,
+        label: "通进司手册写入",
+        description: "写入通用手册或当前仓库差异全文（整份替换）。",
+        promptSnippet: "更新 bot 手册",
+        parameters: handbookWriteSchema,
+        async execute(toolCallId: string, params: HandbookWriteParams, _signal: AbortSignal | undefined, _onUpdate: unknown, ctx: HostContext) {
+          const activation = getActivation();
+          if (activation === undefined) throw new Error("通进司未激活");
+          try {
+            activation.ledger.beginOperational(COLLECTOR_HANDBOOK_WRITE_TOOL, toolCallId);
+            // scope/body shape authority = collectorHandbookWriteArgsSchema (host parameters).
+            const details = await activation.handbook.write(params.scope, params.body);
+            activation.handbookView = await activation.handbook.read();
+            activation.ledger.completeOperational(toolCallId);
+            return {
+              content: [{
+                type: "text" as const,
+                text: `手册已写入：${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 {
+              // already completed or not begun
+            }
+          }
+        },
+      });
+
+      pi.registerTool({
+        name: COLLECTOR_OPEN_WAIT_WINDOW_TOOL,
+        label: "通进司开启等待窗",
+        description:
+          "在工作步骤上开启等待窗：新建并自动触发的 PR 传创建成功时刻；已有 PR 在触发阶段结束后省略 startedAt（=现在）。窗长由使用方配置，默认十分钟；开启后不因 PR 更新重置。",
+        promptSnippet: "按工作步骤开启等待窗",
+        parameters: openWaitWindowSchema,
+        async execute(toolCallId: string, params: OpenWaitWindowParams, _signal: AbortSignal | undefined, _onUpdate: unknown, ctx: HostContext) {
+          const activation = getActivation();
+          if (activation === undefined) throw new Error("通进司未激活");
+          try {
+            activation.ledger.beginOperational(COLLECTOR_OPEN_WAIT_WINDOW_TOOL, toolCallId);
+            let startedAt: Date | undefined;
+            if (typeof params.startedAt === "string" && params.startedAt.trim().length > 0) {
+              const parsed = new Date(params.startedAt);
+              if (Number.isNaN(parsed.getTime())) {
+                throw new Error("通进司等待窗 startedAt 须为有效 ISO 时间");
+              }
+              startedAt = parsed;
+            }
+            activation.ledger.openWaitWindow(
+              activation.clock,
+              startedAt === undefined ? undefined : { startedAt },
+            );
+            activation.ledger.completeOperational(toolCallId);
+            return {
+              content: [{
+                type: "text" as const,
+                text: "等待窗已开启",
+              }],
+              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 {
+              // already completed or not begun
+            }
+          }
+        },
+      });
+
       pi.registerTool({
         name: COLLECTOR_WAIT_TOOL,
         label: "通进司等待",
-        description: "再观察前等待；单次上限五分钟且不超剩余资格。",
-        promptSnippet: "资格截止前等待",
+        description: "再观察前等待；实际睡眠不超过剩余等待窗。",
+        promptSnippet: "等待窗内等待",
         parameters: waitSchema,
         async execute(toolCallId: string, params: WaitParams, signal: AbortSignal | undefined, _onUpdate: unknown, ctx: HostContext) {
           const activation = getActivation();
@@ -476,6 +659,7 @@ export function createCollectorRoleRuntime(
               details,
             };
           } catch (error) {
+            if (isCorrectableExecuteError(error)) throw error;
             hostActions.failInfrastructure(error, ctx, toolCallId);
           }
         },

package/src/collector-tool-schemas.ts

@@ -1,18 +1,56 @@
 import { Type, type Static } from "typebox";
-import { COLLECTOR_ELIGIBILITY_MS } from "./collector-evidence.ts";
 import { openToolObject } from "./open-tool-schema.ts";
 import { withInfrastructureFailureDeclaration } from "./package-contracts/terminating-infrastructure.ts";
 
 export const collectorObserveArgsSchema = Type.Object({}, { additionalProperties: false });
+/**
+ * Stable request identity: non-empty after trim, no leading/trailing whitespace.
+ * Host schema + ledger identity seam share this contract (#677 / D2 dedup).
+ */
+export const COLLECTOR_REQUEST_ID_PATTERN = /^\S(?:.*\S)?$/;
 export const collectorRequestArgsSchema = Type.Object({
-  requestId: Type.String({ minLength: 1, description: "配置请求身份" }),
+  requestId: Type.String({
+    minLength: 1,
+    pattern: COLLECTOR_REQUEST_ID_PATTERN.source,
+    description: "请求身份（配置 id 或角色判定的稳定 id；首尾无空白）",
+  }),
   snapshotId: Type.String({ minLength: 1, description: "最新留存观察快照" }),
+  body: Type.Optional(Type.String({
+    minLength: 1,
+    description: "角色判定的请求正文；request-manifest 未收录该 requestId 时必填",
+  })),
+}, { additionalProperties: false });
+/** UTF-8 byte ceiling per handbook body — keeps next activation materials inside context budget. */
+export const COLLECTOR_HANDBOOK_MAX_BYTES = 64 * 1024;
+export const collectorHandbookWriteArgsSchema = Type.Object({
+  scope: Type.Union([
+    Type.Literal("general"),
+    Type.Literal("repo"),
+  ], { description: "general＝通用手册；repo＝当前仓库差异" }),
+  body: Type.String({
+    description: `手册全文（opaque 工作记忆；整份替换；UTF-8 至多 ${COLLECTOR_HANDBOOK_MAX_BYTES} 字节）`,
+  }),
 }, { additionalProperties: false });
 export const collectorReadArgsSchema = Type.Object({
   evidenceId: Type.String({ minLength: 1, description: "observe 返回的材料证据 id（evidenceId）" }),
 }, { additionalProperties: false });
 export const collectorWaitArgsSchema = Type.Object({
-  durationMs: Type.Integer({ minimum: 1, maximum: COLLECTOR_ELIGIBILITY_MS, description: "等待毫秒；单次上限五分钟且不超剩余资格" }),
+  durationMs: Type.Integer({
+    minimum: 1,
+    description: "等待毫秒；实际睡眠不超过剩余等待窗（#678；无包内单次任意上限）",
+  }),
+}, { additionalProperties: false });
+
+/**
+ * #678 D4: open the wait window at a work step.
+ * Omit startedAt for existing-PR trigger-phase end (= now).
+ * Pass PR creation success time for new-PR auto-trigger rounds.
+ */
+export const collectorOpenWaitWindowArgsSchema = Type.Object({
+  startedAt: Type.Optional(Type.String({
+    minLength: 1,
+    description: "等待窗起点 ISO 时间；新建 PR 用创建成功时刻；省略＝现在（触发阶段结束）",
+  })),
 }, { additionalProperties: false });
 
 /**
@@ -88,5 +126,6 @@ export type CollectorObserveArgs = Static<typeof collectorObserveArgsSchema>;
 export type CollectorRequestArgs = Static<typeof collectorRequestArgsSchema>;
 export type CollectorReadArgs = Static<typeof collectorReadArgsSchema>;
 export type CollectorWaitArgs = Static<typeof collectorWaitArgsSchema>;
+export type CollectorOpenWaitWindowArgs = Static<typeof collectorOpenWaitWindowArgsSchema>;
 export type CollectorBindTargetArgs = Static<typeof collectorBindTargetArgsSchema>;
 export type CollectorOutputArgs = Static<typeof collectorOutputArgsSchema>;

package/src/host-contracts.ts

@@ -106,6 +106,8 @@ export type RoleTurnActivation =
       /** Bound PR when known at admission; omit when role will bind from materials. */
       readonly pr?: string;
       readonly requestManifestPath?: string;
+      /** Wait-window ms as decimal string (#678 D4); omit → package default 10 minutes. */
+      readonly waitMs?: string;
     }
   | { readonly role: "doctor"; readonly casePath: string }
   | {

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

@@ -116,6 +116,7 @@ function buildActivationFlagArgs(activation: RoleTurnActivation): string[] {
         ...(activation.requestManifestPath === undefined
           ? []
           : ["--ak-collector-request-manifest", activation.requestManifestPath]),
+        ...(activation.waitMs === undefined ? [] : ["--ak-collector-wait-ms", activation.waitMs]),
       ];
     case "doctor":
       return ["--ak-role", "doctor", "--ak-doctor-case", activation.casePath];

package/src/public-cli/collector-run.ts

@@ -54,6 +54,7 @@ export function buildCollectorTurnRequest(
         // #676 A: omit pr when unbound — role binds via ak_collector_bind_target.
         ...(admitted.prNumber === undefined ? {} : { pr: String(admitted.prNumber) }),
         ...(admitted.requestManifestPath === undefined ? {} : { requestManifestPath: admitted.requestManifestPath }),
+        ...(admitted.waitWindowMs === undefined ? {} : { waitMs: String(admitted.waitWindowMs) }),
       },
     },
     options,
@@ -83,6 +84,7 @@ export async function runPublicCollector(
       ...(parsed.project === undefined ? {} : { project: parsed.project }),
       ...(parsed.repo === undefined ? {} : { repo: parsed.repo }),
       ...(parsed.requestManifestPath === undefined ? {} : { requestManifestPath: parsed.requestManifestPath }),
+      ...(parsed.waitWindowMs === undefined ? {} : { waitWindowMs: parsed.waitWindowMs }),
       ...(env.createRunId === undefined ? {} : { createRunId: env.createRunId }),
       ...(env.model === undefined ? {} : { model: env.model }),
     });

package/src/public-cli/invocation.ts

@@ -178,6 +178,8 @@ export type AdmittedCollectorInvocation = AdmittedRoleInvocationBase & {
   readonly repository: CollectorRepository;
   readonly requestManifestPath?: string;
   readonly manifestDigest: string;
+  /** Wait-window ms (#678 D4); default applied at role activate when omitted. */
+  readonly waitWindowMs?: number;
 };
 
 export type AdmittedDoctorInvocation = AdmittedRoleInvocationBase & {
@@ -727,6 +729,8 @@ export type ParseCollectorArgvResult = {
   project?: string;
   repo?: string;
   requestManifestPath?: string;
+  /** Optional wait-window ms (#678 D4). */
+  waitWindowMs?: number;
 };
 
 export type ParseDoctorArgvResult = {
@@ -1722,6 +1726,7 @@ export function parseCollectorArgv(args: readonly string[]): ParseCollectorArgvR
   let repo: string | undefined;
   let prNumber: number | undefined;
   let requestManifestPath: string | undefined;
+  let waitWindowMs: number | undefined;
   const positional: string[] = [];
   const tokens = [...args];
   const definitions = roleOptions("collector");
@@ -1754,6 +1759,17 @@ export function parseCollectorArgv(args: readonly string[]): ParseCollectorArgvR
         requestManifestPath = requireOptionPath(taken.def.canonical, taken.value);
         continue;
       }
+      if (taken.def.id === "wait-ms") {
+        if (taken.value === undefined || !/^[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()!;
@@ -1772,6 +1788,7 @@ export function parseCollectorArgv(args: readonly string[]): ParseCollectorArgvR
     ...(project === undefined ? {} : { project }),
     ...(repo === undefined ? {} : { repo }),
     ...(requestManifestPath === undefined ? {} : { requestManifestPath }),
+    ...(waitWindowMs === undefined ? {} : { waitWindowMs }),
   };
 }
 
@@ -1845,6 +1862,8 @@ export type AdmitCollectorInvocationOptions = {
   repo?: string;
   /** Optional public request configuration; copied into the admitted run. */
   requestManifestPath?: string;
+  /** Optional wait-window ms (#678 D4). */
+  waitWindowMs?: number;
   createRunId?: () => string;
   /** Effective model for this invocation — written onto invocation.json. */
   model?: InvocationEffectiveModel;
@@ -1947,6 +1966,7 @@ export async function admitCollectorInvocation(
     repository: repository.canonical,
     repositoryDisplay: repository.display,
     ...(requestManifestPath === undefined ? {} : { requestManifestPath }),
+    ...(options.waitWindowMs === undefined ? {} : { waitWindowMs: options.waitWindowMs }),
     manifestDigest,
     attachments: attachments.map((a) => ({
       provenancePath: a.provenancePath,
@@ -1977,6 +1997,7 @@ export async function admitCollectorInvocation(
     ...(prNumber === undefined ? {} : { prNumber }),
     repository,
     ...(requestManifestPath === undefined ? {} : { requestManifestPath }),
+    ...(options.waitWindowMs === undefined ? {} : { waitWindowMs: options.waitWindowMs }),
     manifestDigest,
   };
 }

package/src/public-cli/option-definitions.ts

@@ -598,8 +598,22 @@ const COLLECTOR_OPTIONS = [
     repeatable: false,
     form: "option",
     description: {
-      en: "Optional request manifest JSON path ({requests:[{id,body}]}).",
-      zh: "可选 request manifest JSON 路径（{requests:[{id,body}]}）。",
+      en: "Optional request manifest JSON path ({requests:[{id,body}]}). Role may also decide request bodies from handbook/field activity without this file.",
+      zh: "可选 request manifest JSON 路径（{requests:[{id,body}]}）。角色亦可依手册/现场自行判定请求正文，不必依赖本文件。",
+    },
+  },
+  {
+    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: "工作步骤开启后的等待窗时长（毫秒；默认 600000＝十分钟）。改配置即可，无需改代码。",
     },
   },
 ] as const satisfies readonly PublicOptionDefinition[];

package/src/public-cli/run-lifecycle.ts

@@ -1149,6 +1149,8 @@ type LoadedAdmittedRequestFields = {
   readonly repositoryDisplay?: string;
   readonly requestManifestPath?: string;
   readonly manifestDigest?: string;
+  /** Collector wait-window ms restored on resume (#678). */
+  readonly waitWindowMs?: number;
   /** Doctor — admitted single-case identity restored on resume (#633). */
   readonly issueNumber?: number;
   readonly caseRunsPath?: string;
@@ -1244,6 +1246,7 @@ async function loadResumableRunRecord(
   let repositoryDisplay: string | undefined;
   let requestManifestPath: string | undefined;
   let manifestDigest: string | undefined;
+  let waitWindowMs: number | undefined;
   let issueNumber: number | undefined;
   let caseRunsPath: string | undefined;
   let caseIdentity: DoctorCaseIdentity | undefined;
@@ -1304,6 +1307,9 @@ async function loadResumableRunRecord(
       if (typeof record.manifestDigest === "string" && record.manifestDigest.trim() !== "") {
         manifestDigest = record.manifestDigest;
       }
+      if (typeof record.waitWindowMs === "number" && Number.isSafeInteger(record.waitWindowMs) && record.waitWindowMs >= 1) {
+        waitWindowMs = record.waitWindowMs;
+      }
       // Doctor — admitted single-case identity (#633 resume).
       if (typeof record.issueNumber === "number" && Number.isSafeInteger(record.issueNumber) && record.issueNumber >= 1) {
         issueNumber = record.issueNumber;
@@ -1471,6 +1477,7 @@ async function loadResumableRunRecord(
       ...(repositoryDisplay === undefined ? {} : { repositoryDisplay }),
       ...(requestManifestPath === undefined ? {} : { requestManifestPath }),
       ...(manifestDigest === undefined ? {} : { manifestDigest }),
+      ...(waitWindowMs === undefined ? {} : { waitWindowMs }),
       ...(issueNumber === undefined ? {} : { issueNumber }),
       ...(caseRunsPath === undefined ? {} : { caseRunsPath }),
       ...(caseIdentity === undefined ? {} : { caseIdentity }),
@@ -1913,6 +1920,9 @@ export async function loadResumableCollectorRun(
     ...(loaded.admittedFields.requestManifestPath === undefined
       ? {}
       : { requestManifestPath: loaded.admittedFields.requestManifestPath }),
+    ...(loaded.admittedFields.waitWindowMs === undefined
+      ? {}
+      : { waitWindowMs: loaded.admittedFields.waitWindowMs }),
     manifestDigest,
   };
   return seatLoadedResult(loaded, admitted);

package/src/role-runtime.ts

@@ -611,6 +611,8 @@ export type RoleRuntimeDependencies = {
   /** Shared-seam issue-fetch capability for Reviewer Spec self-fetch (#343). */
   createReviewerIssueFetcher?(): ReviewerIssueFetcher;
   loadCollectorSoul?(): Promise<string>;
+  /** #677: optional packaged seed for first-use general bot handbook. */
+  loadCollectorHandbookSeed?(): Promise<string>;
   createCollectorTransport?(): CollectorGitHubTransport;
   loadDoctorSoul?(): Promise<string>;
   loadNotarySoul?(): Promise<string>;
@@ -1717,6 +1719,9 @@ export function createRoleRuntimeExtension(
         ...(dependencies.createCollectorClock === undefined
           ? {}
           : { createClock: dependencies.createCollectorClock }),
+        ...(dependencies.loadCollectorHandbookSeed === undefined
+          ? {}
+          : { loadHandbookSeed: dependencies.loadCollectorHandbookSeed }),
       },
       hostActions,
     );