@akagilnc/pi-workflow-roles 0.1.2107 → 0.1.2114

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

@@ -7,6 +7,8 @@
 import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
+import { applyEngineChildEnv } from "../engine-detour.ts";
+import { engineSessionMaterialFromOptions } from "../package-resources/engine-material.ts";
 import {
   loadPackagedMethodSkillMaterial,
   resolvePackagedMethodSkillPath,
@@ -82,6 +84,8 @@ export type FixerRunEnv = {
   correlationId?: string;
   piRunner?: ExplicitInternalPiRunner;
   model?: SeatModelConfig;
+  /** Optional labor engine name (config→activation; session material + env signal). */
+  engine?: string;
   credentials?: CredentialProviders;
   createRunId?: () => string;
   extraPiArgs?: readonly string[];
@@ -99,10 +103,14 @@ export function buildFixerActivationExtraArgs(
   options: {
     packageRoot: string;
     model?: SeatModelConfig;
+    engine?: string;
     extraPiArgs?: readonly string[];
   },
 ): string[] {
-  const prompt = buildFixerTransportPrompt(admitted);
+  const prompt = buildFixerTransportPrompt(
+    admitted,
+    engineSessionMaterialFromOptions(options),
+  );
   const diagnosisSkillPath = resolvePackagedMethodSkillPath(
     options.packageRoot,
     "diagnosing-bugs",
@@ -275,12 +283,14 @@ async function dispatchAdmittedFixer(input: {
   extraArgs: string[];
   lease: RunWriterLease;
   methodMaterial: PackagedMethodSkillMaterial;
+  /** Mechanical engine provenance for initial Fixer dispatch only. */
+  effectiveEngine?: string;
 }): Promise<{
   exitCode: number;
   admitted: AdmittedFixerInvocation;
   terminal?: TerminalResult;
 }> {
-  const { admitted, env, io, extraArgs, lease, methodMaterial } = input;
+  const { admitted, env, io, extraArgs, lease, methodMaterial, effectiveEngine } = input;
   try {
     const missingCredential = missingCredentialPreDispatchFailure(
       env.model,
@@ -293,7 +303,7 @@ async function dispatchAdmittedFixer(input: {
         io,
       );
     }
-    await markRunRunning(admitted.runDirectory, env.model);
+    await markRunRunning(admitted.runDirectory, env.model, effectiveEngine);
     await clearTypedProviderHttpObservation(admitted.runDirectory);
 
     const childEnv: NodeJS.ProcessEnv = {
@@ -302,6 +312,7 @@ async function dispatchAdmittedFixer(input: {
       PI_CODING_AGENT_DIR: env.agentDir,
       AK_ROLE_RUN_DIR: admitted.runDirectory,
     };
+    applyEngineChildEnv(childEnv, env.engine);
     const correlationId = admitted.correlationId ?? env.correlationId;
     if (correlationId !== undefined && correlationId.trim() !== "") {
       childEnv.AK_CORRELATION_ID = correlationId;
@@ -494,6 +505,7 @@ export async function runPublicFixer(
   const extraArgs = buildFixerActivationExtraArgs(admitted, {
     packageRoot: env.packageRoot,
     ...(env.model === undefined ? {} : { model: env.model }),
+    ...(env.engine === undefined ? {} : { engine: env.engine }),
     ...(env.extraPiArgs === undefined ? {} : { extraPiArgs: env.extraPiArgs }),
   });
 
@@ -507,6 +519,8 @@ export async function runPublicFixer(
     extraArgs,
     lease,
     methodMaterial,
+    // #391: only initial Fixer dispatch records mechanical engine provenance.
+    ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
   });
 }
 

package/src/public-cli/invocation.ts

@@ -967,6 +967,7 @@ export async function admitCoderInvocation(
  */
 export function buildCoderTransportPrompt(
   admitted: AdmittedCoderInvocation,
+  engineMaterial?: EngineSessionMaterial,
 ): string {
   const lines: string[] = [admitted.instruction];
   if (admitted.attachments.length > 0) {
@@ -976,7 +977,7 @@ export function buildCoderTransportPrompt(
       lines.push(`- ${attachment.frozenPath}`);
     }
   }
-  return lines.join("\n");
+  return appendEngineSessionMaterial(lines, engineMaterial).join("\n");
 }
 
 export type AdmitFixerInvocationOptions = {
@@ -1123,6 +1124,7 @@ export async function admitFixerInvocation(
  */
 export function buildFixerTransportPrompt(
   admitted: AdmittedFixerInvocation,
+  engineMaterial?: EngineSessionMaterial,
 ): string {
   const lines: string[] = [admitted.instruction];
   if (admitted.attachments.length > 0) {
@@ -1132,7 +1134,7 @@ export function buildFixerTransportPrompt(
       lines.push(`- ${attachment.frozenPath}`);
     }
   }
-  return lines.join("\n");
+  return appendEngineSessionMaterial(lines, engineMaterial).join("\n");
 }
 
 function parsePositivePrOption(raw: string | undefined): number {
@@ -1415,9 +1417,10 @@ export async function admitCollectorInvocation(
  */
 export function buildCollectorTransportPrompt(
   _admitted: AdmittedCollectorInvocation,
+  engineMaterial?: EngineSessionMaterial,
 ): string {
   // Exact historical fixed kickoff bytes (one-shot observation).
-  return COLLECTOR_FIXED_KICKOFF;
+  return appendEngineSessionMaterial([COLLECTOR_FIXED_KICKOFF], engineMaterial).join("\n");
 }
 
 /** Positive Issue number grammar shared with Doctor case path identity. */
@@ -1727,6 +1730,7 @@ export async function admitDoctorInvocation(
 /** Build the Pi prompt transport for an admitted Doctor request. */
 export function buildDoctorTransportPrompt(
   admitted: AdmittedDoctorInvocation,
+  engineMaterial?: EngineSessionMaterial,
 ): string {
   const lines: string[] = [admitted.instructionEmpty ? "" : admitted.instruction];
   if (admitted.attachments.length > 0) {
@@ -1736,7 +1740,7 @@ export function buildDoctorTransportPrompt(
       lines.push(`- ${attachment.frozenPath}`);
     }
   }
-  return lines.join("\n");
+  return appendEngineSessionMaterial(lines, engineMaterial).join("\n");
 }
 
 /**
@@ -2160,6 +2164,7 @@ export async function admitMergerInvocation(
  */
 export function buildMergerTransportPrompt(
   admitted: AdmittedMergerInvocation,
+  engineMaterial?: EngineSessionMaterial,
 ): string {
   const lines: string[] = [
     `/skill:resolving-merge-conflicts ${admitted.instruction}`,
@@ -2171,7 +2176,7 @@ export function buildMergerTransportPrompt(
       lines.push(`- ${attachment.frozenPath}`);
     }
   }
-  return lines.join("\n");
+  return appendEngineSessionMaterial(lines, engineMaterial).join("\n");
 }
 
 const TAISHI_TICKET_NUMBER_PATTERN = /^[1-9]\d*$/;

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

@@ -6,7 +6,7 @@
 import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
-import { AK_ROLE_ENGINE_ENV } from "../engine-detour.ts";
+import { applyEngineChildEnv } from "../engine-detour.ts";
 import { engineSessionMaterialFromOptions } from "../package-resources/engine-material.ts";
 import {
   runExplicitInternalActivation,
@@ -298,14 +298,7 @@ async function dispatchAdmittedJudge(input: {
       // and role-runtime can record typed provider HTTP observations.
       AK_ROLE_RUN_DIR: admitted.runDirectory,
     };
-    // Engine presence/name signal: registration gate + label only (no per-engine branch).
-    // Delete ambient inheritance first; own-key undefined mask survives process.env re-merge.
-    delete childEnv[AK_ROLE_ENGINE_ENV];
-    if (env.engine !== undefined && env.engine.trim() !== "") {
-      childEnv[AK_ROLE_ENGINE_ENV] = env.engine.trim();
-    } else {
-      childEnv[AK_ROLE_ENGINE_ENV] = undefined;
-    }
+    applyEngineChildEnv(childEnv, env.engine);
     const correlationId = admitted.correlationId ?? env.correlationId;
     if (correlationId !== undefined && correlationId.trim() !== "") {
       childEnv.AK_CORRELATION_ID = correlationId;

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

@@ -8,6 +8,8 @@ import { join, resolve } from "node:path";
 
 import { ensureRealDirectoryTree } from "../activation-ledger-topology.ts";
 import { roleRunSessionCoordinates } from "../sitian-role-run-coordinates.ts";
+import { applyEngineChildEnv } from "../engine-detour.ts";
+import { engineSessionMaterialFromOptions } from "../package-resources/engine-material.ts";
 import {
   loadPackagedMethodSkillMaterial,
   resolvePackagedMethodSkillPath,
@@ -83,6 +85,8 @@ export type MergerRunEnv = {
   correlationId?: string;
   piRunner?: ExplicitInternalPiRunner;
   model?: SeatModelConfig;
+  /** Optional labor engine name (config→activation; session material + env signal). */
+  engine?: string;
   credentials?: CredentialProviders;
   createRunId?: () => string;
   extraPiArgs?: readonly string[];
@@ -100,10 +104,14 @@ export function buildMergerActivationExtraArgs(
   options: {
     packageRoot: string;
     model?: SeatModelConfig;
+    engine?: string;
     extraPiArgs?: readonly string[];
   },
 ): string[] {
-  const prompt = buildMergerTransportPrompt(admitted);
+  const prompt = buildMergerTransportPrompt(
+    admitted,
+    engineSessionMaterialFromOptions(options),
+  );
   const skillPath = resolvePackagedMethodSkillPath(
     options.packageRoot,
     "resolving-merge-conflicts",
@@ -271,12 +279,13 @@ async function dispatchAdmittedMerger(input: {
   extraArgs: string[];
   lease: RunWriterLease;
   methodMaterial: PackagedMethodSkillMaterial;
+  effectiveEngine?: string;
 }): Promise<{
   exitCode: number;
   admitted: AdmittedMergerInvocation;
   terminal?: TerminalResult;
 }> {
-  const { admitted, env, io, extraArgs, lease, methodMaterial } = input;
+  const { admitted, env, io, extraArgs, lease, methodMaterial, effectiveEngine } = input;
   try {
     const missingCredential = missingCredentialPreDispatchFailure(
       env.model,
@@ -289,7 +298,7 @@ async function dispatchAdmittedMerger(input: {
         io,
       );
     }
-    await markRunRunning(admitted.runDirectory, env.model);
+    await markRunRunning(admitted.runDirectory, env.model, effectiveEngine);
     await clearTypedProviderHttpObservation(admitted.runDirectory);
 
     const childEnv: NodeJS.ProcessEnv = {
@@ -298,6 +307,7 @@ async function dispatchAdmittedMerger(input: {
       PI_CODING_AGENT_DIR: env.agentDir,
       AK_ROLE_RUN_DIR: admitted.runDirectory,
     };
+    applyEngineChildEnv(childEnv, env.engine);
     const correlationId = admitted.correlationId ?? env.correlationId;
     if (correlationId !== undefined && correlationId.trim() !== "") {
       childEnv.AK_CORRELATION_ID = correlationId;
@@ -576,6 +586,7 @@ export async function runPublicMerger(
   const extraArgs = buildMergerActivationExtraArgs(admitted, {
     packageRoot: env.packageRoot,
     ...(env.model === undefined ? {} : { model: env.model }),
+    ...(env.engine === undefined ? {} : { engine: env.engine }),
     ...(env.extraPiArgs === undefined ? {} : { extraPiArgs: env.extraPiArgs }),
   });
 
@@ -589,6 +600,7 @@ export async function runPublicMerger(
     extraArgs,
     lease,
     methodMaterial,
+    ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
   });
 }
 

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

@@ -288,8 +288,8 @@ const GLOBAL_OPTIONS = [
     repeatable: false,
     form: "option",
     description: {
-      en: "Optional Judge/Reviewer labor engine for this invocation (owner pool-directive name; packaged notes attached when present; judge+reviewer only).",
-      zh: "本调用可选 Judge/Reviewer 劳动引擎（池令名字；有包内调法笔记则附卷；仅 Judge+Reviewer）。",
+      en: "Optional labor engine for this invocation (owner pool-directive name; packaged notes attached when present; any role).",
+      zh: "本调用可选劳动引擎（池令名字；有包内调法笔记则附卷；全部角色可用）。",
     },
   },
   {

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

@@ -7,7 +7,7 @@
 import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
-import { AK_ROLE_ENGINE_ENV } from "../engine-detour.ts";
+import { applyEngineChildEnv } from "../engine-detour.ts";
 import { engineSessionMaterialFromOptions } from "../package-resources/engine-material.ts";
 import {
   loadPackagedMethodSkillMaterial,
@@ -320,14 +320,7 @@ async function dispatchAdmittedReviewer(input: {
       PI_CODING_AGENT_DIR: env.agentDir,
       AK_ROLE_RUN_DIR: admitted.runDirectory,
     };
-    // Engine presence/name signal: registration gate + leg channel (no per-engine branch).
-    // Delete ambient inheritance first; own-key undefined mask survives process.env re-merge.
-    delete childEnv[AK_ROLE_ENGINE_ENV];
-    if (env.engine !== undefined && env.engine.trim() !== "") {
-      childEnv[AK_ROLE_ENGINE_ENV] = env.engine.trim();
-    } else {
-      childEnv[AK_ROLE_ENGINE_ENV] = undefined;
-    }
+    applyEngineChildEnv(childEnv, env.engine);
     const correlationId = admitted.correlationId ?? env.correlationId;
     if (correlationId !== undefined && correlationId.trim() !== "") {
       childEnv.AK_CORRELATION_ID = correlationId;

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

@@ -233,7 +233,7 @@ export async function markRunAdmitted(
  * resume override) and optional initial effective engine onto invocation.json
  * when known, then transition to running.
  * Role runners must not coordinate lifecycle ledger writes themselves.
- * Engine is write-if-present only — callers that omit it (resume / non-Judge)
+ * Engine is write-if-present only — callers that omit it (resume paths)
  * never touch the engine key.
  */
 export async function markRunRunning(

package/src/role-runtime.ts

@@ -597,7 +597,7 @@ export function createRoleRuntimeExtension(
     let pendingNavigatorSettlement: Promise<void> | undefined;
     let navigatorWorkContext: NavigatorWorkContext | undefined;
     const pendingInfrastructureToolCallIds = new Set<string>();
-    // #357 T2 / #378 / #380: engine detour once-latch + seat-fallback latch (Judge|Reviewer+engine).
+    // #357 T2 / #378 / #380 / #391: engine detour once-latch + seat-fallback latch (any role+engine).
     let engineDetourRegistration: ReturnType<typeof registerEngineDetourTool> | undefined;
     let engineLaborFallbackLatch = createEngineLaborFallbackLatch();
     // #288 primary-session thin adapter. The policy is the sole budget owner;
@@ -1187,13 +1187,10 @@ export function createRoleRuntimeExtension(
         }
 
         await executeActivationStage(entry.role, activationStage(entry.role, runtime), { clock, writeTrace });
-        // #357 T2 / #378 / #380: Judge|Reviewer+engine activation registers the package detour tool once.
+        // #357 T2 / #378 / #380 / #391: any role+engine activation registers the package detour tool once.
         // Gate is env presence only — no per-engine execute branch; no role-module spawn.
         // Seat-fallback latch is activation-scoped (installed at session_start) so legs share it.
-        if (
-          (entry.role === "judge" || entry.role === "reviewer") &&
-          engineDetourRegistration === undefined
-        ) {
+        if (engineDetourRegistration === undefined) {
           engineDetourRegistration = registerEngineDetourTool(pi, hostActions);
           if (!engineDetourRegistration.registered) {
             engineDetourRegistration = undefined;

package/src/worker-role.ts

@@ -6,6 +6,10 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
 import { openToolObjectFromUnion } from "./open-tool-schema.ts";
+import {
+  readActivationEngineLaborFallbackField,
+  withEngineLaborFallbackField,
+} from "./engine-labor-fallback.ts";
 
 import type {
   AnyCanonicalSkillBinding,
@@ -288,9 +292,14 @@ export function createFixerRoleRuntime(
               ctx,
               toolCallId,
             );
+            // #391: attach sole-built engineLaborFallback when detour fell back to seat labor.
+            const acceptedDetails = withEngineLaborFallbackField(
+              output,
+              readActivationEngineLaborFallbackField(),
+            );
             return {
               content: [{ type: "text" as const, text: "Fixer report accepted" }],
-              details: output,
+              details: acceptedDetails,
               terminate: true as const,
             };
           },
@@ -427,9 +436,14 @@ export function createCoderRoleRuntime(
               ctx,
               toolCallId,
             );
+            // #391: attach sole-built engineLaborFallback when detour fell back to seat labor.
+            const acceptedDetails = withEngineLaborFallbackField(
+              output,
+              readActivationEngineLaborFallbackField(),
+            );
             return {
               content: [{ type: "text" as const, text: "Coder report accepted" }],
-              details: output,
+              details: acceptedDetails,
               terminate: true as const,
             };
           },