@akagilnc/pi-workflow-roles 0.1.3749 → 0.1.3771

package/src/public-cli/invocation.ts

@@ -31,13 +31,14 @@ import {
 } from "../doctor-evidence.ts";
 import type { DoctorCaseIdentity } from "../doctor-contracts.ts";
 import {
-  COLLECTOR_FIXED_KICKOFF,
   emptyCollectorManifest,
   loadCollectorManifest,
   parseCollectorPrNumber,
   parseCollectorRepository,
   type CollectorRepository,
 } from "../collector-config.ts";
+import { resolveCollectorTarget } from "../collector-target.ts";
+import { ownerRepoFromGitHubRemoteUrl } from "./github-remote.ts";
 import {
   FixerPacketValidationError,
   parseFixerPrerequisites,
@@ -172,7 +173,8 @@ export type AdmittedFixerInvocation = AdmittedRoleInvocationBase & {
 
 export type AdmittedCollectorInvocation = AdmittedRoleInvocationBase & {
   readonly role: "collector";
-  readonly prNumber: number;
+  /** Bound at admission when explicit/--pr or unique head/commit; otherwise role binds. */
+  readonly prNumber?: number;
   readonly repository: CollectorRepository;
   readonly requestManifestPath?: string;
   readonly manifestDigest: string;
@@ -718,7 +720,8 @@ export type ParseFixerArgvResult = {
 };
 
 export type ParseCollectorArgvResult = {
-  prNumber: number;
+  /** Explicit --pr when provided; admission resolves from context when absent (#676 D1). */
+  prNumber?: number;
   instruction: string;
   attachmentPaths: string[];
   project?: string;
@@ -1759,10 +1762,11 @@ export function parseCollectorArgv(args: readonly string[]): ParseCollectorArgvR
     }
     positional.push(token);
   }
-  // Unconditional required (e.g. --pr) from typed table via shared consumer (#342).
+  // Unconditional required from typed table via shared consumer (#342).
+  // #676 D1: --pr is optional; ambiguous targets reject at admission, not by guessing.
   options.assertRequired();
   return {
-    prNumber: prNumber!,
+    ...(prNumber === undefined ? {} : { prNumber }),
     instruction: positional.join(" "),
     attachmentPaths,
     ...(project === undefined ? {} : { project }),
@@ -1774,6 +1778,7 @@ export function parseCollectorArgv(args: readonly string[]): ParseCollectorArgvR
 /**
  * Resolve owner/repo from the project's `origin` remote (github.com only).
  * Supports https and SSH GitHub URL shapes; never scrapes instruction prose.
+ * Missing origin / non-github remote → usage. Git execution failure → true cause (exit 1).
  */
 export function resolveGitHubRemoteRepository(
   projectRoot: string,
@@ -1786,10 +1791,16 @@ export function resolveGitHubRemoteRepository(
       stdio: ["ignore", "pipe", "pipe"],
     }).trim();
   } catch (error) {
-    throw new CliUsageError(
-      "collector requires a github.com origin remote or an explicit --repo owner/repo",
-      { cause: error },
-    );
+    // git remote get-url exit 2 = no such remote; other failures keep true cause.
+    if (isGitRemoteMissing(error)) {
+      throw new CliUsageError(
+        "collector requires a github.com origin remote or an explicit --repo owner/repo",
+        { cause: error },
+      );
+    }
+    throw new Error("collector git failed: cannot read origin remote URL", {
+      cause: error instanceof Error ? error : new Error(String(error)),
+    });
   }
   if (remoteUrl.length === 0) {
     throw new CliUsageError(
@@ -1811,44 +1822,22 @@ export function resolveGitHubRemoteRepository(
   }
 }
 
-function ownerRepoFromGitHubRemoteUrl(remoteUrl: string): string | undefined {
-  const trimmed = remoteUrl.trim();
-  // git@github.com:owner/repo.git — exact owner/repo identity only.
-  const scp = /^git@github\.com:([^/\s]+)\/([^/\s]+?)(?:\.git)?$/i.exec(trimmed);
-  if (scp) {
-    return `${scp[1]}/${stripGitSuffix(scp[2]!)}`;
-  }
-  // ssh://git@github.com/owner/repo(.git) — exact owner/repo identity only.
-  const ssh = /^ssh:\/\/git@github\.com\/([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/i.exec(
-    trimmed,
-  );
-  if (ssh) {
-    return `${ssh[1]}/${stripGitSuffix(ssh[2]!)}`;
-  }
-  // https://github.com/owner/repo(.git) and git://github.com/... — exact two-segment path.
-  let parsed: URL;
-  try {
-    parsed = new URL(trimmed);
-  } catch {
-    return undefined;
-  }
-  if (!/^github\.com$/i.test(parsed.hostname)) return undefined;
-  // Non-identity URL material (query/hash/extra path) is not a repository remote.
-  if (parsed.search !== "" || parsed.hash !== "") return undefined;
-  const parts = parsed.pathname.split("/").filter((p) => p.length > 0);
-  if (parts.length !== 2) return undefined;
-  return `${parts[0]}/${stripGitSuffix(parts[1]!)}`;
-}
-
-function stripGitSuffix(name: string): string {
-  return name.toLowerCase().endsWith(".git") ? name.slice(0, -4) : name;
+/**
+ * git remote get-url: exit 2 = no such remote on common git (missing config).
+ * Other statuses keep true cause — do not broaden into usage (#676 B).
+ */
+function isGitRemoteMissing(error: unknown): boolean {
+  if (typeof error !== "object" || error === null) return false;
+  const status = (error as { status?: unknown }).status;
+  return status === 2;
 }
 
 export type AdmitCollectorInvocationOptions = {
   home: string;
   principalAuthority: DurablePrincipalAuthority;
   cwd: string;
-  prNumber: number;
+  /** Explicit PR when provided; resolved from context when absent (#676 D1). */
+  prNumber?: number;
   instruction?: string;
   attachmentPaths?: readonly string[];
   project?: string;
@@ -1863,8 +1852,8 @@ export type AdmitCollectorInvocationOptions = {
 
 /**
  * Admit a Collector Role run: assemble the retained leg manifest from typed
- * declarations, resolve repository identity, and place the session under #78.
- * Does not preflight PR/author existence against GitHub.
+ * declarations, resolve repository + PR target (#676 D1), and place the session under #78.
+ * Explicit PR is not preflighted for existence; context resolution uses online association.
  */
 export async function admitCollectorInvocation(
   options: AdmitCollectorInvocationOptions,
@@ -1872,12 +1861,14 @@ export async function admitCollectorInvocation(
   if (options.project !== undefined) {
     requireOptionPath("--project", options.project);
   }
-  let prNumber: number;
-  try {
-    prNumber = parseCollectorPrNumber(options.prNumber);
-  } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
-    throw new CliUsageError(detail, { cause: error });
+  let explicitPrNumber: number | undefined;
+  if (options.prNumber !== undefined) {
+    try {
+      explicitPrNumber = parseCollectorPrNumber(options.prNumber);
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      throw new CliUsageError(detail, { cause: error });
+    }
   }
 
   const projectRoot = resolve(options.project ?? options.cwd);
@@ -1924,16 +1915,25 @@ export async function admitCollectorInvocation(
   ensureRealDirectoryTree(ledgerHome, sessionDirectory);
   ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
 
+  // #676 A: freeze task materials BEFORE target resolution so the role receives
+  // real instruction + attachments. Admission binds only explicit --pr or unique
+  // head/commit association — task-text scrape is not a target lock.
   const attachments = await freezeAttachments(options.attachmentPaths ?? [], attachmentsDirectory);
+  const instruction = options.instruction ?? "";
+  const instructionEmpty = instruction.trim() === "";
+
+  const target = await resolveCollectorTarget({
+    projectRoot,
+    repository,
+    ...(explicitPrNumber === undefined ? {} : { explicitPrNumber }),
+  });
+  const prNumber = target.kind === "bound" ? target.prNumber : undefined;
 
   let requestManifestPath: string | undefined;
   if (manifestCanonicalJson !== undefined) {
     requestManifestPath = join(runDirectory, "request-manifest.json");
     await writeFile(requestManifestPath, manifestCanonicalJson, "utf8");
   }
-
-  const instruction = options.instruction ?? "";
-  const instructionEmpty = instruction.trim() === "";
   const admitted = {
     role: "collector" as const,
     runId,
@@ -1943,7 +1943,7 @@ export async function admitCollectorInvocation(
     principal,
     instruction,
     instructionEmpty,
-    prNumber,
+    ...(prNumber === undefined ? {} : { prNumber }),
     repository: repository.canonical,
     repositoryDisplay: repository.display,
     ...(requestManifestPath === undefined ? {} : { requestManifestPath }),
@@ -1974,7 +1974,7 @@ export async function admitCollectorInvocation(
     runDirectory,
     principal,
     admittedRequestPath,
-    prNumber,
+    ...(prNumber === undefined ? {} : { prNumber }),
     repository,
     ...(requestManifestPath === undefined ? {} : { requestManifestPath }),
     manifestDigest,
@@ -1982,15 +1982,16 @@ export async function admitCollectorInvocation(
 }
 
 /**
- * Collector always consumes the fixed packaged kickoff (one-shot observation).
- * Optional public instruction is retained only in the admitted request.
+ * #676 A: Collector consumes the real call task + frozen attachments so the role
+ * can identify issue/PR from materials via ak_collector_bind_target. Explicit --pr
+ * still wins at admission; unique head/commit association also binds. No fixed
+ * kickoff rewrite of the caller task; no mechanical task-text target lock.
  */
 export function buildCollectorTransportPrompt(
-  _admitted: AdmittedCollectorInvocation,
+  admitted: AdmittedCollectorInvocation,
   engineMaterial?: EngineSessionMaterial,
 ): string {
-  // Exact historical fixed kickoff bytes (one-shot observation).
-  return appendEngineSessionMaterial([COLLECTOR_FIXED_KICKOFF], engineMaterial).join("\n");
+  return buildInstructionTransportPrompt(admitted, engineMaterial);
 }
 
 /** Positive Issue number grammar shared with Doctor case path identity. */

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

@@ -565,12 +565,13 @@ const COLLECTOR_OPTIONS = [
     canonical: "--pr",
     aliases: [],
     valueMetavar: "number",
-    required: true,
+    // #676 D1: optional when context uniquely determines the PR; ambiguous → require explicit.
+    required: false,
     repeatable: false,
     form: "option",
     description: {
-      en: "Required positive GitHub pull request number.",
-      zh: "必填；正整数 GitHub PR 号。",
+      en: "Positive GitHub pull request number. Optional when unique branch/HEAD association binds the PR, or when the Collector role can decide the target from task materials via bind-target; multi-candidate git context or a role that cannot decide requires an explicit value.",
+      zh: "正整数 GitHub PR 号。分支/HEAD 唯一关联可绑定时可省略；亦可由通进司从任务材料经 bind-target 判定。git 多候选或角色无法判定时必须显式提供。",
     },
   },
   {
@@ -1199,9 +1200,10 @@ const ROLE_COMMAND_HELP = {
   collector: {
     command: "collector",
     summary: "Collect GitHub PR review evidence.",
-    usage: ["ak-role collector --pr <number> [options] [instruction]"],
+    usage: ["ak-role collector [--pr <number>] [options] [instruction]"],
     examples: [
       "ak-role collector --pr 42 --repo owner/repository",
+      "ak-role collector --repo owner/repository \"Collect findings for #42\"",
       "ak-role collector --pr 42 --request-manifest ./requests.json",
     ],
   },

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

@@ -1883,8 +1883,8 @@ export async function loadResumableCollectorRun(
     );
   }
   const { prNumber, repository, repositoryDisplay, manifestDigest } = loaded.admittedFields;
+  // #676 A: prNumber may be unbound at admission (role bind-target). Repository is required.
   if (
-    prNumber === undefined ||
     repository === undefined ||
     repositoryDisplay === undefined ||
     manifestDigest === undefined
@@ -1908,7 +1908,7 @@ export async function loadResumableCollectorRun(
   const admitted: AdmittedCollectorInvocation = {
     role: "collector",
     ...resumedBaseAdmitted(loaded),
-    prNumber,
+    ...(prNumber === undefined ? {} : { prNumber }),
     repository: parsedRepository,
     ...(loaded.admittedFields.requestManifestPath === undefined
       ? {}

package/src/public-cli/settlement.ts

@@ -44,6 +44,7 @@ import {
 // COMPLIANCE_RESPONSE_ENTRY_TYPE remains for boundRetainedAuditResponse (call/result
 // interval binding on historical session bytes). Provider-stop retain authority is Sitian.
 import {
+  COLLECTOR_BIND_TARGET_TOOL,
   COLLECTOR_OBSERVE_TOOL,
   COLLECTOR_READ_TOOL,
   COLLECTOR_REQUEST_TOOL,
@@ -375,12 +376,36 @@ export function formatFailureStderrDiagnostic(failure: ControlledFailure): strin
   return formatCliDiagnostic(boundConciseDiagnostic(oneLine));
 }
 
-/** Pre-admission structural rejection: stderr only, no run, no Terminal. */
+/**
+ * #676 B: one cause face for public stderr — Error.message, else object JSON with
+ * status/body/headers when present, else String. Never wash objects to [object Object].
+ */
+export function formatErrorCauseDetail(cause: unknown): string {
+  if (cause instanceof Error) return cause.message;
+  if (typeof cause === "object" && cause !== null) {
+    try {
+      return JSON.stringify(cause);
+    } catch {
+      return String(cause);
+    }
+  }
+  return String(cause);
+}
+
+/** Pre-admission structural rejection: stderr only, no run, no Terminal. Cause retained when present. */
 export function presentStructuralRejection(
-  error: { message: string },
+  error: { message: string; cause?: unknown },
   io: { stderr: (text: string) => void },
 ): void {
-  io.stderr(formatCliDiagnostic(error.message));
+  let message = error.message;
+  const cause = error.cause;
+  if (cause !== undefined) {
+    const detail = formatErrorCauseDetail(cause);
+    if (detail.trim().length > 0) {
+      message = `${message}; cause: ${detail}`;
+    }
+  }
+  io.stderr(formatCliDiagnostic(message));
 }
 
 /** ControlledFailure face without admitted-run Terminal (stdout body + stderr line). */
@@ -1520,6 +1545,34 @@ function toolResultText(message: SessionMessage): string {
     .trim();
 }
 
+/**
+ * #676 D1/J3: durable bind-target rejection on the current attempt → public no_receipt facts.
+ * Callers must learn they need explicit --pr without opening the session 正本.
+ * Authority is the latest bind-target toolResult only — a later success clears an earlier failure.
+ */
+function extractCollectorTargetBindRejection(
+  entries: readonly SessionEntry[],
+): { readonly diagnostic: string; readonly code?: string } | undefined {
+  for (let i = entries.length - 1; i >= 0; i -= 1) {
+    const entry = entries[i];
+    if (entry?.type !== "message") continue;
+    const message = entry.message;
+    if (message?.role !== "toolResult") continue;
+    if (message.toolName !== COLLECTOR_BIND_TARGET_TOOL) continue;
+    // Latest bind result wins: success means the attempt is no longer rejected.
+    if (message.isError !== true) return undefined;
+    const diagnostic = toolResultText(message);
+    if (diagnostic.length === 0) return undefined;
+    const details = message.details;
+    const code =
+      isRecord(details) && typeof details.code === "string" && details.code.trim() !== ""
+        ? details.code
+        : undefined;
+    return code === undefined ? { diagnostic } : { diagnostic, code };
+  }
+  return undefined;
+}
+
 type BoundErroredToolCandidate = {
   candidate: unknown;
   diagnostic: string;
@@ -1697,7 +1750,9 @@ export function assertCollectorReceiptMatchesAdmitted(
       `Collector receipt repository "${receipt.repository}" does not match admitted repository "${admitted.repository.canonical}"`,
     );
   }
-  if (receipt.prNumber !== admitted.prNumber) {
+  // #676 A: when admission left the target unbound, receipt.prNumber is the role bind.
+  // When admission bound explicitly/head-commit, receipt must match.
+  if (admitted.prNumber !== undefined && receipt.prNumber !== admitted.prNumber) {
     throw collectorReceiptBindingFailure(
       `Collector receipt prNumber ${receipt.prNumber} does not match admitted prNumber ${admitted.prNumber}`,
     );
@@ -2787,7 +2842,7 @@ export async function publishCollectorArtifacts(
       {
         runId: admitted.runId,
         role: "collector",
-        prNumber: admitted.prNumber,
+        ...(admitted.prNumber === undefined ? {} : { prNumber: admitted.prNumber }),
         repository: admitted.repository.canonical,
         manifestDigest: admitted.manifestDigest,
         sessionDirectory: coordinates.sessionDirectory,
@@ -4178,7 +4233,19 @@ export async function settleFailureTerminalResult(
         try {
           const facts = parseNoReceiptLifecycleFacts(raw);
           if (facts.runPointer === admitted.runDirectory && facts.attemptPointer === `current:${admitted.runDirectory}`) {
-            const decisiveFacts: NoReceiptLifecycleFacts = facts;
+            let decisiveFacts: NoReceiptLifecycleFacts & Record<string, unknown> = facts;
+            // #676 D1/J3: project durable bind-target rejection onto public no_receipt facts.
+            if (admitted.role === "collector") {
+              const bindRejection = extractCollectorTargetBindRejection(entries.slice(attemptStart));
+              if (bindRejection !== undefined) {
+                decisiveFacts = {
+                  ...facts,
+                  targetBindRejected: true,
+                  targetBindDiagnostic: bindRejection.diagnostic,
+                  ...(bindRejection.code === undefined ? {} : { targetBindCode: bindRejection.code }),
+                };
+              }
+            }
             // #478: no_receipt is still a public Terminal — project accepted gate facts.
             return withOptionalGateProjection(
               {
@@ -4285,6 +4352,15 @@ export function presentFailureTerminal(
       cause: terminal.roleOutcome.cause,
       diagnostic: terminal.roleOutcome.diagnostic,
     }));
+    return;
+  }
+  // #676 D1/J3: no_receipt stays lawful exit 0; surface durable target-bind clarification on stderr.
+  const bindDiagnostic = terminal.roleOutcome.decisiveFacts.targetBindDiagnostic;
+  if (typeof bindDiagnostic === "string" && bindDiagnostic.trim() !== "") {
+    io.stderr(formatFailureStderrDiagnostic({
+      cause: "output",
+      diagnostic: bindDiagnostic,
+    }));
   }
 }
 

package/src/role-runtime.ts

@@ -43,12 +43,10 @@ import type { AnyCanonicalSkillBinding } from "./canonical-skill-binding.ts";
 import type { CollectorClock } from "./collector-evidence.ts";
 import type { CollectorGitHubTransport } from "./collector-github.ts";
 import {
-  COLLECTOR_OBSERVE_TOOL,
-  COLLECTOR_OUTPUT_TOOL,
-  COLLECTOR_READ_TOOL,
-  COLLECTOR_REQUEST_TOOL,
-  COLLECTOR_WAIT_TOOL,
+  COLLECTOR_REQUIRED_TOOLS,
+  COLLECTOR_TRANSPORT_FLAGS,
   createCollectorRoleRuntime,
+  type CollectorActivation,
 } from "./collector-role.ts";
 import type { ComplianceDecision } from "./compliance-transport.ts";
 import { createDoctorRoleRuntime } from "./doctor-role.ts";
@@ -449,7 +447,9 @@ type ActivationRuntime = {
   decodeReviewerAdmitted(): ReviewerAdmittedInputs;
   /** Envelope stores live parent activation for agent_start prompt assembly. */
   bindReviewerParent(activation: ReviewerActivation): void;
-  collector: { activate(context: HostContext, event: { reason: string }): Promise<void> };
+  collector: {
+    activate(context: HostContext, event: { reason: string }): Promise<void>;
+  };
   doctor: { activate(): Promise<void> };
   notary: {
     activate(admitted?: import("./notary-role.ts").NotaryAdmittedTicket): Promise<void>;
@@ -629,7 +629,6 @@ export type RoleRuntimeDependencies = {
   createMergerGitState?(repositoryRoot: string): MergerRoleDependencies["gitState"];
   auditDoctorCompliance?(options: { context: HostContext; signal?: AbortSignal }): Promise<ComplianceDecision>;
   createCollectorClock?(): CollectorClock;
-  collectorPackageExtensionPath?: string;
   createNavigatorAttendance?(options: { context: HostContext; role: string; phase: NavigatorPhase; subjectKey: string; subject: string; authority: string; contextError?: unknown; invocationId: string; onEvent: (event: import("./navigator-attendance.ts").NavigatorEvent, report: import("./navigator-attendance.ts").NavigatorReport) => void | Promise<void> }): NavigatorAttendanceDependency | Promise<NavigatorAttendanceDependency>;
   loadNavigatorWorkContext?(options: { context: HostContext; role: string; phase: NavigatorPhase; getFlag?: (name: string) => unknown }): Promise<NavigatorWorkContext>;
   loadCanonicalSkillBinding?(
@@ -1144,6 +1143,10 @@ export function createRoleRuntimeExtension(
     for (const flag of GLEANER_LEFT_TRANSPORT_FLAGS) {
       roleHost.registerFlag(flag.name, flag.definition);
     }
+    // Collector transport flags: shared envelope owns registration (ADR 0018 / #676 E).
+    for (const flag of COLLECTOR_TRANSPORT_FLAGS) {
+      roleHost.registerFlag(flag.name, flag.definition);
+    }
 
     let admitted = false;
     let selectedRole: string | undefined;
@@ -1305,10 +1308,46 @@ export function createRoleRuntimeExtension(
           }),
         };
       }
+      // #676 E / J1: collector materials + drift gates share this envelope hook (no parallel register).
+      if (role === "collector" && activeCollector !== undefined) {
+        const options = event.systemPromptOptions;
+        if (options.skills && options.skills.length > 0) {
+          failInfrastructure(
+            activeCollector.ledger.latchFatal("通进司检测到系统提示中的环境 skills"),
+            ctx,
+          );
+        }
+        if (options.contextFiles && options.contextFiles.length > 0) {
+          failInfrastructure(
+            activeCollector.ledger.latchFatal("通进司检测到系统提示中的环境 context files"),
+            ctx,
+          );
+        }
+        if (
+          typeof options.appendSystemPrompt === "string"
+          && options.appendSystemPrompt.trim().length > 0
+        ) {
+          failInfrastructure(
+            activeCollector.ledger.latchFatal("通进司检测到 appendSystemPrompt 漂移"),
+            ctx,
+          );
+        }
+        if (!collectorFirstDispatchDone) {
+          collectorFirstDispatchDone = true;
+          activeCollector.ledger.recordActivation(activeCollector.clock);
+        }
+        return {
+          systemPrompt: collectorBusiness.assembleMaterials(activeCollector, event.systemPrompt),
+        };
+      }
     });
     roleHost.on("tool_result", async (event) => {
       const role = selectedRole;
       if (role === undefined) return;
+      // #676 E / J1: collector operational bookkeeping on the shared tool_result seam.
+      if (role === "collector" && activeCollector !== undefined) {
+        collectorBusiness.onToolResult(activeCollector, event);
+      }
       const pendingInfra = pendingInfrastructureFailures.get(event.toolCallId);
       const isRoleInfrastructureFailure = pendingInfra !== undefined;
       if (pendingInfra !== undefined) pendingInfrastructureFailures.delete(event.toolCallId);
@@ -1439,6 +1478,16 @@ export function createRoleRuntimeExtension(
         priorFetch = undefined;
         fetchWrapped = false;
       }
+      // #676 J4: collector fatal latch must surface nonzero exit on shutdown (envelope-owned).
+      if (
+        selectedRole === "collector"
+        && activeCollector !== undefined
+        && activeCollector.ledger.fatal
+      ) {
+        if (process.exitCode === undefined || process.exitCode === 0) {
+          process.exitCode = 1;
+        }
+      }
       // Flush any still-pending affirmative attendance before teardown. Accepted
       // grace-timeout paths normally emit on agent_settled; abort can skip that hook.
       const presentation = pendingNavigatorPresentation;
@@ -1630,7 +1679,11 @@ export function createRoleRuntimeExtension(
         completedMerge(mergeCommitId, automaticMergeTreeId) { if (!sessionMergerGitState) throw new Error("Merger runtime dependencies are not configured"); return sessionMergerGitState.completedMerge(mergeCommitId, automaticMergeTreeId); },
       },
     }, hostActions);
-    const collector = createCollectorRoleRuntime(
+    // #676 E: shared envelope owns collector lifecycle (mode/fork, tool surface,
+    // event gates). Role module supplies business activate/tools/materials only.
+    let activeCollector: CollectorActivation | undefined;
+    let collectorFirstDispatchDone = false;
+    const collectorBusiness = createCollectorRoleRuntime(
       roleHost,
       {
         async loadSoul() {
@@ -1664,14 +1717,114 @@ export function createRoleRuntimeExtension(
         ...(dependencies.createCollectorClock === undefined
           ? {}
           : { createClock: dependencies.createCollectorClock }),
-        ...(dependencies.collectorPackageExtensionPath === undefined
-          ? {}
-          : {
-            packageExtensionPath: dependencies.collectorPackageExtensionPath,
-          }),
       },
       hostActions,
     );
+    // #676 J1: business tools + tool_call gate register only behind admission/activation.
+    // before_agent_start / tool_result collector branches live on the shared envelope hooks above.
+    //
+    // #676 J4 dispositions for guards removed from the role-private collector module:
+    // - skills/contextFiles/appendSystemPrompt fail-closed → shared before_agent_start (above).
+    // - ambient skill/prompt/template commands → activate (below).
+    // - session_shutdown fatal exitCode → shared session_shutdown (above).
+    // - subsequent-input latchFatal + fixed-kickoff rewrite → intentionally not migrated:
+    //   #676 materials-first multi-turn abolished the single-shot fixed kickoff; multi-turn
+    //   observe/request/wait requires later inputs. Judge r1: fixed-kickoff equality delete is authorized.
+    // - tool sourceInfo path override check → intentionally not migrated: depended on
+    //   packageExtensionPath deleted under ADR 0018 / #676 E envelope ownership; uniqueness
+    //   + setActiveTools inventory checks remain on activate.
+    let collectorToolCallRegistered = false;
+    const collector = {
+      async activate(context: HostContext, event: { reason: string }) {
+        activeCollector = undefined;
+        collectorFirstDispatchDone = false;
+        // Envelope-owned mode / fork-reload gates (not role-private lifecycle).
+        if (context.mode !== "print" && context.mode !== "json") {
+          throw new Error(
+            `Collector supports only print or json mode (got ${context.mode})`,
+          );
+        }
+        if (event.reason === "fork" || event.reason === "reload") {
+          throw new Error(
+            `Collector does not support session_start reason ${event.reason}`,
+          );
+        }
+        // #676 J4: ambient skill/prompt/template commands fail closed at activation.
+        const commands = roleHost.getCommands?.() ?? [];
+        const ambientCommands = commands.filter((command) => {
+          const name = command.name.toLowerCase();
+          return (
+            name.includes("skill")
+            || name.includes("prompt")
+            || name.startsWith("template")
+          );
+        });
+        if (ambientCommands.length > 0) {
+          throw new Error(
+            `Collector detected ambient instruction commands: ${
+              ambientCommands.map((c) => c.name).join(", ")
+            }`,
+          );
+        }
+        // Business tools behind admission barrier (inert-without-role invariant).
+        // First activation: fail closed if a required name is already occupied.
+        // Later activations reuse the once-registered tools (registerBusinessTools is idempotent).
+        const preExisting = roleHost.getAllTools();
+        const alreadyRegistered = COLLECTOR_REQUIRED_TOOLS.every((required) =>
+          preExisting.some((tool) => tool.name === required),
+        );
+        if (!alreadyRegistered) {
+          for (const required of COLLECTOR_REQUIRED_TOOLS) {
+            const prior = preExisting.filter((tool) => tool.name === required);
+            if (prior.length > 0) {
+              throw new Error(`Collector required tool name collision: ${required}`);
+            }
+          }
+        }
+        collectorBusiness.registerBusinessTools(() => activeCollector);
+        const allTools = roleHost.getAllTools();
+        for (const required of COLLECTOR_REQUIRED_TOOLS) {
+          const matches = allTools.filter((tool) => tool.name === required);
+          if (matches.length === 0) {
+            throw new Error(`Collector required tool missing: ${required}`);
+          }
+          if (matches.length > 1) {
+            throw new Error(`Collector required tool name collision: ${required}`);
+          }
+        }
+        roleHost.setActiveTools([...COLLECTOR_REQUIRED_TOOLS]);
+        const active = new Set(roleHost.getActiveTools());
+        for (const required of COLLECTOR_REQUIRED_TOOLS) {
+          if (!active.has(required)) {
+            throw new Error(`Collector failed to activate required tool ${required}`);
+          }
+        }
+        for (const name of active) {
+          if (!(COLLECTOR_REQUIRED_TOOLS as readonly string[]).includes(name)) {
+            throw new Error(`Collector active tool surface includes unexpected ${name}`);
+          }
+        }
+        // Seat-scoped tool_call gate — registered only after collector admission (no install-time tool_call).
+        if (!collectorToolCallRegistered) {
+          collectorToolCallRegistered = true;
+          roleHost.on("tool_call", (toolEvent) => {
+            if (activeCollector === undefined || selectedRole !== "collector") return;
+            if (!(COLLECTOR_REQUIRED_TOOLS as readonly string[]).includes(toolEvent.toolName)) {
+              return {
+                block: true,
+                reason: `通进司禁用工具 ${toolEvent.toolName}`,
+              };
+            }
+            return collectorBusiness.onToolCall(activeCollector, toolEvent);
+          });
+        }
+        const activation = await collectorBusiness.activate(context);
+        if (activation.ledger.activationRecorded) {
+          collectorFirstDispatchDone = true;
+        }
+        activeCollector = activation;
+      },
+    };
 
     const clock = dependencies.activationClock ?? (() => new Date().toISOString());
     const writeTrace = dependencies.activationTraceWriter ?? writeActivationTraceRecord;