@akagilnc/pi-workflow-roles 0.1.2052 → 0.1.2058

package/dist/public-cli/main.js

@@ -16380,18 +16380,21 @@ async function writeRoleInvocationLedger(source, role, effectiveModel) {
     "utf8"
   );
 }
-async function recordEffectiveInvocationModel(runDirectory, model) {
+async function recordEffectiveInvocationModel(runDirectory, model, engine) {
   const ledgerPath = join6(runDirectory, "invocation.json");
   const current = JSON.parse(await readFile4(ledgerPath, "utf8"));
-  const next = {
-    ...current,
-    provider: model.provider,
-    model: model.model
-  };
-  if (model.thinking === void 0) {
-    delete next.thinking;
-  } else {
-    next.thinking = model.thinking;
+  const next = { ...current };
+  if (model !== void 0) {
+    next.provider = model.provider;
+    next.model = model.model;
+    if (model.thinking === void 0) {
+      delete next.thinking;
+    } else {
+      next.thinking = model.thinking;
+    }
+  }
+  if (engine !== void 0) {
+    next.engine = engine;
   }
   await writeFile2(
     ledgerPath,
@@ -18629,9 +18632,13 @@ async function markRunAdmitted(admitted) {
     ...admitted.role === "coder" || admitted.role === "fixer" ? { phase: admitted.phase } : {}
   });
 }
-async function markRunRunning(runDirectory, effectiveModel) {
-  if (effectiveModel !== void 0) {
-    await recordEffectiveInvocationModel(runDirectory, effectiveModel);
+async function markRunRunning(runDirectory, effectiveModel, effectiveEngine) {
+  if (effectiveModel !== void 0 || effectiveEngine !== void 0) {
+    await recordEffectiveInvocationModel(
+      runDirectory,
+      effectiveModel,
+      effectiveEngine
+    );
   }
   const current = await readRoleRunState(runDirectory);
   if (current === void 0) {
@@ -19410,6 +19417,16 @@ var init_collector_ledger = __esm({
   }
 });
 
+// src/engine-detour.ts
+var ENGINE_DETOUR_TOOL_NAME, AK_ROLE_ENGINE_ENV;
+var init_engine_detour = __esm({
+  "src/engine-detour.ts"() {
+    "use strict";
+    ENGINE_DETOUR_TOOL_NAME = "ak_engine_detour";
+    AK_ROLE_ENGINE_ENV = "AK_ROLE_ENGINE";
+  }
+});
+
 // src/work-subject-identity.ts
 import { resolve as resolve6 } from "node:path";
 function issueRoot(value) {
@@ -20563,34 +20580,46 @@ function boundErroredToolCandidate(entries, resultIndex, message, toolName) {
   const diagnostic = toolResultText(message);
   return bound === void 0 || diagnostic === "" ? void 0 : { candidate: bound.candidate, diagnostic, callIndex: bound.callIndex };
 }
-function extractCollectorInfrastructureFailure(entries) {
+function extractInfrastructureToolFailure(entries, spec) {
   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.isError !== true) continue;
-    if (typeof message.toolName !== "string" || !COLLECTOR_INFRASTRUCTURE_TOOLS.has(message.toolName)) {
+    if (typeof message.toolName !== "string" || !spec.matchTool(message.toolName)) {
       continue;
     }
     const diagnostic = toolResultText(message);
     if (diagnostic.length === 0) continue;
     return {
-      cause: "activation",
+      cause: spec.cause,
       diagnostic,
-      identity: { name: "CollectorInfrastructureError" }
+      identity: { name: spec.identityName }
     };
   }
   return void 0;
 }
-async function readCollectorInfrastructureFailure(sessionFile) {
+async function readInfrastructureToolFailure(sessionFile, spec) {
   try {
     const entries = await readBoundSessionEntries(sessionFile);
-    return extractCollectorInfrastructureFailure(entries);
+    return extractInfrastructureToolFailure(entries, spec);
   } catch {
     return void 0;
   }
 }
+async function readCollectorInfrastructureFailure(sessionFile) {
+  return readInfrastructureToolFailure(
+    sessionFile,
+    COLLECTOR_INFRASTRUCTURE_FAILURE_SPEC
+  );
+}
+async function readEngineDetourInfrastructureFailure(sessionFile) {
+  return readInfrastructureToolFailure(
+    sessionFile,
+    ENGINE_DETOUR_INFRASTRUCTURE_FAILURE_SPEC
+  );
+}
 function assertCollectorReceiptMatchesAdmitted(receipt, admitted) {
   if (receipt.repository !== admitted.repository.canonical) {
     throw collectorReceiptBindingFailure(
@@ -22386,7 +22415,7 @@ function presentFailureTerminal(terminal, io) {
     }));
   }
 }
-var CONCISE_DIAGNOSTIC_MAX_CHARS, COLLECTOR_INFRASTRUCTURE_TOOLS;
+var CONCISE_DIAGNOSTIC_MAX_CHARS, COLLECTOR_INFRASTRUCTURE_TOOLS, COLLECTOR_INFRASTRUCTURE_FAILURE_SPEC, ENGINE_DETOUR_INFRASTRUCTURE_FAILURE_SPEC;
 var init_settlement = __esm({
   "src/public-cli/settlement.ts"() {
     "use strict";
@@ -22399,6 +22428,7 @@ var init_settlement = __esm({
     init_run_lifecycle();
     init_compliance_transport();
     init_collector_ledger();
+    init_engine_detour();
     init_judge_output();
     init_collector_output();
     init_worker_output();
@@ -22419,6 +22449,16 @@ var init_settlement = __esm({
       COLLECTOR_REQUEST_TOOL,
       COLLECTOR_WAIT_TOOL
     ]);
+    COLLECTOR_INFRASTRUCTURE_FAILURE_SPEC = {
+      matchTool: (toolName) => COLLECTOR_INFRASTRUCTURE_TOOLS.has(toolName),
+      cause: "activation",
+      identityName: "CollectorInfrastructureError"
+    };
+    ENGINE_DETOUR_INFRASTRUCTURE_FAILURE_SPEC = {
+      matchTool: (toolName) => toolName === ENGINE_DETOUR_TOOL_NAME,
+      cause: "output",
+      identityName: "EngineDetourInfrastructureError"
+    };
   }
 });
 
@@ -23742,7 +23782,7 @@ async function presentControlledFailure6(admitted, failureInput, io) {
   };
 }
 async function dispatchAdmittedJudge(input) {
-  const { admitted, env, io, extraArgs, lease } = input;
+  const { admitted, env, io, extraArgs, lease, effectiveEngine } = input;
   try {
     const missingCredential = missingCredentialPreDispatchFailure(
       env.model,
@@ -23755,7 +23795,11 @@ async function dispatchAdmittedJudge(input) {
         io
       );
     }
-    await markRunRunning(admitted.runDirectory, env.model);
+    await markRunRunning(
+      admitted.runDirectory,
+      env.model,
+      effectiveEngine
+    );
     await clearTypedProviderHttpObservation(admitted.runDirectory);
     const childEnv = {
       ...process.env,
@@ -23765,6 +23809,12 @@ async function dispatchAdmittedJudge(input) {
       // and role-runtime can record typed provider HTTP observations.
       AK_ROLE_RUN_DIR: admitted.runDirectory
     };
+    delete childEnv[AK_ROLE_ENGINE_ENV];
+    if (env.engine !== void 0 && env.engine.trim() !== "") {
+      childEnv[AK_ROLE_ENGINE_ENV] = env.engine.trim();
+    } else {
+      childEnv[AK_ROLE_ENGINE_ENV] = void 0;
+    }
     const correlationId = admitted.correlationId ?? env.correlationId;
     if (correlationId !== void 0 && correlationId.trim() !== "") {
       childEnv.AK_CORRELATION_ID = correlationId;
@@ -23839,13 +23889,20 @@ async function dispatchAdmittedJudge(input) {
         terminal: auditIncomplete
       };
     }
+    const infrastructureFailure = await readEngineDetourInfrastructureFailure(
+      admitted.sessionFile
+    );
     const credentialFailure = postRunMissingCredentialFailure(
       result2,
       env.model,
       env.credentials
     );
     const resolution = await resolveAuditedRunnerFailureResolution({
-      runner: result2.knownFailure,
+      runner: result2.knownFailure ?? (infrastructureFailure === void 0 ? void 0 : {
+        cause: infrastructureFailure.cause,
+        diagnostic: infrastructureFailure.diagnostic,
+        ...infrastructureFailure.identity === void 0 ? {} : { identity: infrastructureFailure.identity }
+      }),
       sessionFile: admitted.sessionFile,
       credential: credentialFailure,
       runDirectory: admitted.runDirectory
@@ -23909,7 +23966,9 @@ async function runPublicJudge(argv, env, io, parseJudgeArgv2) {
     },
     io,
     extraArgs,
-    lease
+    lease,
+    // #358: only initial Judge dispatch records mechanical engine provenance.
+    ...env.engine === void 0 ? {} : { effectiveEngine: env.engine }
   });
 }
 async function runPublicResume(argv, env, io) {
@@ -23967,6 +24026,7 @@ async function runPublicResume(argv, env, io) {
 var init_judge_run = __esm({
   "src/public-cli/judge-run.ts"() {
     "use strict";
+    init_engine_detour();
     init_engine_material();
     init_explicit_internal();
     init_cli_errors();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akagilnc/pi-workflow-roles",
-  "version": "0.1.2052",
+  "version": "0.1.2058",
   "description": "Soul-bound workflow roles for Pi",
   "type": "module",
   "license": "Apache-2.0",

package/resources/engines/kimi.md

@@ -29,3 +29,7 @@ kimi --yolo --output-format text -p "YOUR_LABOR_PROMPT"
 
 Prefer `kimi --help` on the host over any remembered flag set. Do not wrap this
 engine behind `ak-role` flags.
+
+When the package detour tool is available, start exactly one subprocess through
+it with argv assembled from this material and the local CLI; return the stdout
+labor content to the same session for the existing typed submission path.

package/src/engine-detour-tool.ts

@@ -0,0 +1,142 @@
+/**
+ * Package-owned engine detour tool (#357 T2).
+ * Registered by shared role-runtime when Judge + engine activation signal is present.
+ * Forbidden in judge-role.ts (lifecycle ban — no spawn in role modules).
+ */
+import type {
+  AgentToolResult,
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+
+import {
+  ENGINE_DETOUR_ALREADY_USED_DIAGNOSTIC,
+  ENGINE_DETOUR_TOOL_NAME,
+  engineDetourFailureDiagnostic,
+  engineNameFromEnv,
+  isEngineDetourFailure,
+  runEngineDetourOnce,
+} from "./engine-detour.ts";
+
+const engineDetourArgsSchema = Type.Object(
+  {
+    argv: Type.Array(Type.String({ minLength: 1 }), {
+      minItems: 1,
+      description:
+        "Executable argv for one engine subprocess. First element is the command (PATH lookup); remaining elements are arguments. Assemble from engine method material — do not invent package flags.",
+    }),
+  },
+  { additionalProperties: false },
+);
+
+type EngineDetourArgs = Static<typeof engineDetourArgsSchema>;
+
+export type EngineDetourHostActions = {
+  failInfrastructure(
+    error: unknown,
+    ctx: ExtensionContext,
+    toolCallId?: string,
+  ): never;
+};
+
+export type EngineDetourToolRegistration = {
+  /** True when the tool definition was installed on this ExtensionAPI. */
+  readonly registered: boolean;
+};
+
+/**
+ * Register the engine-generic detour tool once for this process when Judge has
+ * an engine activation signal. Returns whether registration occurred.
+ * Once-latch is activation-scoped via the returned reset handle.
+ */
+export function registerEngineDetourTool(
+  pi: ExtensionAPI,
+  hostActions: EngineDetourHostActions,
+): EngineDetourToolRegistration & { resetLatch(): void } {
+  const engineName = engineNameFromEnv();
+  if (engineName === undefined) {
+    return {
+      registered: false,
+      resetLatch() {
+        /* no-op when unregistered */
+      },
+    };
+  }
+
+  let used = false;
+
+  pi.registerTool({
+    name: ENGINE_DETOUR_TOOL_NAME,
+    label: "Engine Detour",
+    description:
+      `Run one labor-engine subprocess (engine=${engineName}) and return its stdout to this session. Call at most once per activation. Assemble argv from the engine method material path delivered in the session prompt.`,
+    promptSnippet: "Run the configured labor engine once and return its stdout",
+    promptGuidelines: [
+      `Use ${ENGINE_DETOUR_TOOL_NAME} exactly once when engine method material is present.`,
+      "Pass argv assembled from the material and the host CLI — first element is the executable name on PATH.",
+      "On success, use the returned stdout as labor content for the existing typed submission tool.",
+    ],
+    parameters: engineDetourArgsSchema,
+    async execute(
+      toolCallId,
+      params,
+      signal,
+      _onUpdate,
+      ctx,
+    ): Promise<AgentToolResult<unknown>> {
+      if (used) {
+        hostActions.failInfrastructure(
+          new Error(ENGINE_DETOUR_ALREADY_USED_DIAGNOSTIC),
+          ctx,
+          toolCallId,
+        );
+      }
+      used = true;
+
+      const args = params as EngineDetourArgs;
+      const argv = Array.isArray(args.argv) ? args.argv : [];
+      if (argv.length === 0 || argv.some((part) => typeof part !== "string" || part.length === 0)) {
+        hostActions.failInfrastructure(
+          new Error("engine detour argv must be a non-empty string array"),
+          ctx,
+          toolCallId,
+        );
+      }
+
+      let result: Awaited<ReturnType<typeof runEngineDetourOnce>>;
+      try {
+        result = await runEngineDetourOnce({
+          argv,
+          cwd: ctx.cwd,
+          ...(signal === undefined ? {} : { signal }),
+        });
+      } catch (error) {
+        hostActions.failInfrastructure(error, ctx, toolCallId);
+      }
+
+      if (isEngineDetourFailure(result)) {
+        hostActions.failInfrastructure(
+          new Error(engineDetourFailureDiagnostic(result)),
+          ctx,
+          toolCallId,
+        );
+      }
+
+      return {
+        content: [{ type: "text" as const, text: result.stdout }],
+        details: {
+          tool: ENGINE_DETOUR_TOOL_NAME,
+          code: result.code,
+        },
+      };
+    },
+  });
+
+  return {
+    registered: true,
+    resetLatch() {
+      used = false;
+    },
+  };
+}

package/src/engine-detour.ts

@@ -0,0 +1,103 @@
+/**
+ * Engine-generic one-shot subprocess detour (#357 T2 / ADR 0069).
+ * Spawn once; no retry, hang surface, or per-engine branch.
+ * Material body is LLM data — this module only executes argv the model assembled.
+ */
+import { spawn } from "node:child_process";
+
+/** Package-owned detour tool name (settlement whitelist + session principal). */
+export const ENGINE_DETOUR_TOOL_NAME = "ak_engine_detour" as const;
+
+/** Env presence/name signal injected by public Judge run (registration gate only). */
+export const AK_ROLE_ENGINE_ENV = "AK_ROLE_ENGINE" as const;
+
+export const ENGINE_DETOUR_EMPTY_STDOUT_DIAGNOSTIC =
+  "engine detour produced empty stdout" as const;
+
+export const ENGINE_DETOUR_ALREADY_USED_DIAGNOSTIC =
+  "engine detour already used in this activation" as const;
+
+export type EngineDetourResult = Readonly<{
+  code: number;
+  stdout: string;
+  stderr: string;
+}>;
+
+export type EngineDetourRunInput = Readonly<{
+  argv: readonly string[];
+  cwd: string;
+  env?: NodeJS.ProcessEnv;
+  signal?: AbortSignal;
+}>;
+
+/**
+ * Run one engine subprocess. First argv element is the executable (PATH lookup).
+ * stdio: ignore stdin, pipe stdout+stderr. No shell, no retry, no hang timer.
+ */
+export async function runEngineDetourOnce(
+  input: EngineDetourRunInput,
+): Promise<EngineDetourResult> {
+  if (input.argv.length === 0) {
+    throw new Error("engine detour argv must be non-empty");
+  }
+  const command = input.argv[0]!;
+  const args = input.argv.slice(1);
+  return await new Promise<EngineDetourResult>((resolve, reject) => {
+    let settled = false;
+    const child = spawn(command, args, {
+      cwd: input.cwd,
+      env: input.env ?? process.env,
+      stdio: ["ignore", "pipe", "pipe"],
+      ...(input.signal === undefined ? {} : { signal: input.signal }),
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8").on("data", (chunk: string) => {
+      stdout += chunk;
+    });
+    child.stderr.setEncoding("utf8").on("data", (chunk: string) => {
+      stderr += chunk;
+    });
+    const fail = (error: unknown): void => {
+      if (settled) return;
+      settled = true;
+      reject(error instanceof Error ? error : new Error(String(error)));
+    };
+    child.on("error", (error) => fail(error));
+    child.on("close", (code) => {
+      if (settled) return;
+      settled = true;
+      resolve({ code: code ?? 1, stdout, stderr });
+    });
+  });
+}
+
+/** Failure predicate: nonzero exit OR stdout trim-empty (including whitespace-only). */
+export function isEngineDetourFailure(result: {
+  code: number;
+  stdout: string;
+}): boolean {
+  return result.code !== 0 || result.stdout.trim() === "";
+}
+
+/**
+ * Diagnostic string for shared settlement / Terminal Error Artifact.
+ * Prefer engine stderr 原样; whitespace-only/empty stderr is absent → stable fallback.
+ */
+export function engineDetourFailureDiagnostic(result: {
+  stderr: string;
+  code: number;
+  stdout: string;
+}): string {
+  if (result.stderr.trim().length > 0) return result.stderr;
+  if (result.stdout.trim() === "") return ENGINE_DETOUR_EMPTY_STDOUT_DIAGNOSTIC;
+  return `engine detour exited with code ${result.code}`;
+}
+
+/** Non-empty trimmed engine name from process.env, else undefined. */
+export function engineNameFromEnv(): string | undefined {
+  const raw = process.env[AK_ROLE_ENGINE_ENV];
+  if (typeof raw !== "string") return undefined;
+  const trimmed = raw.trim();
+  return trimmed === "" ? undefined : trimmed;
+}

package/src/public-cli/invocation.ts

@@ -239,28 +239,35 @@ async function writeRoleInvocationLedger(
 }
 
 /**
- * Merge the effective launch model onto the existing invocation identity page
- * (resume / temporary override path — same field shape as admission write).
+ * Merge the effective launch model (and optional initial engine) onto the
+ * existing invocation identity page (resume / temporary override path — same
+ * field shape as admission write).
  * Bare model clears any prior thinking key so absence stays honest.
+ * Engine is write-if-present only: undefined leaves any existing key untouched
+ * (resume model merge must not erase initial mechanical provenance).
  */
 export async function recordEffectiveInvocationModel(
   runDirectory: string,
-  model: InvocationEffectiveModel,
+  model?: InvocationEffectiveModel,
+  engine?: string,
 ): Promise<void> {
   const ledgerPath = join(runDirectory, "invocation.json");
   const current = JSON.parse(await readFile(ledgerPath, "utf8")) as Record<
     string,
     unknown
   >;
-  const next: Record<string, unknown> = {
-    ...current,
-    provider: model.provider,
-    model: model.model,
-  };
-  if (model.thinking === undefined) {
-    delete next.thinking;
-  } else {
-    next.thinking = model.thinking;
+  const next: Record<string, unknown> = { ...current };
+  if (model !== undefined) {
+    next.provider = model.provider;
+    next.model = model.model;
+    if (model.thinking === undefined) {
+      delete next.thinking;
+    } else {
+      next.thinking = model.thinking;
+    }
+  }
+  if (engine !== undefined) {
+    next.engine = engine;
   }
   await writeFile(
     ledgerPath,

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

@@ -6,6 +6,7 @@
 import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
+import { AK_ROLE_ENGINE_ENV } from "../engine-detour.ts";
 import { engineSessionMaterialFromOptions } from "../package-resources/engine-material.ts";
 import {
   runExplicitInternalActivation,
@@ -58,6 +59,7 @@ import {
   resolveControlledFailureResumeObservation,
   controlledFailureInputFromResolution,
   explicitInternalKnownFailureClassificationInput,
+  readEngineDetourInfrastructureFailure,
   settleJudgeFailureTerminalResult,
   trySettleJudgeTerminalResult,
   trySettleComplianceAuditIncompleteTerminalResult,
@@ -254,12 +256,17 @@ async function dispatchAdmittedJudge(input: {
   io: CliIo;
   extraArgs: string[];
   lease: RunWriterLease;
+  /**
+   * Mechanical engine provenance for initial Judge dispatch only.
+   * Explicit — never read from env.engine here, so resume cannot rewrite it.
+   */
+  effectiveEngine?: string;
 }): Promise<{
   exitCode: number;
   admitted: AdmittedJudgeInvocation;
   terminal?: TerminalResult;
 }> {
-  const { admitted, env, io, extraArgs, lease } = input;
+  const { admitted, env, io, extraArgs, lease, effectiveEngine } = input;
   try {
     // Fail closed at the public credential seam before model dispatch: missing
     // selected-provider auth must not be washed by ambient keys or zero-exit runs.
@@ -274,7 +281,11 @@ async function dispatchAdmittedJudge(input: {
         io,
       );
     }
-    await markRunRunning(admitted.runDirectory, env.model);
+    await markRunRunning(
+      admitted.runDirectory,
+      env.model,
+      effectiveEngine,
+    );
     // Attempt-scoped observation: drop any prior dispatch's 429 evidence so only
     // the current initial/resume attempt can qualify v1 resume.
     await clearTypedProviderHttpObservation(admitted.runDirectory);
@@ -287,6 +298,14 @@ 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;
+    }
     const correlationId = admitted.correlationId ?? env.correlationId;
     if (correlationId !== undefined && correlationId.trim() !== "") {
       childEnv.AK_CORRELATION_ID = correlationId;
@@ -368,6 +387,11 @@ async function dispatchAdmittedJudge(input: {
       };
     }
 
+    // Prefer engine-detour infrastructure failure already on the session principal
+    // over a later secondary provider-stop after abort (#357 T2 / collector-isomorphic).
+    const infrastructureFailure = await readEngineDetourInfrastructureFailure(
+      admitted.sessionFile,
+    );
     // Production-owned typed cause channel — never inferred from stderr wording.
     const credentialFailure = postRunMissingCredentialFailure(
       result,
@@ -375,7 +399,17 @@ async function dispatchAdmittedJudge(input: {
       env.credentials,
     );
     const resolution = await resolveAuditedRunnerFailureResolution({
-      runner: result.knownFailure,
+      runner:
+        result.knownFailure ??
+        (infrastructureFailure === undefined
+          ? undefined
+          : {
+              cause: infrastructureFailure.cause,
+              diagnostic: infrastructureFailure.diagnostic,
+              ...(infrastructureFailure.identity === undefined
+                ? {}
+                : { identity: infrastructureFailure.identity }),
+            }),
       sessionFile: admitted.sessionFile,
       credential: credentialFailure,
       runDirectory: admitted.runDirectory,
@@ -459,6 +493,8 @@ export async function runPublicJudge(
     io,
     extraArgs,
     lease,
+    // #358: only initial Judge dispatch records mechanical engine provenance.
+    ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
   });
 }
 

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

@@ -230,15 +230,23 @@ export async function markRunAdmitted(
 
 /**
  * Shared dispatch execution seam: record the effective launch model (initial or
- * resume override) onto invocation.json when known, then transition to running.
+ * 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)
+ * never touch the engine key.
  */
 export async function markRunRunning(
   runDirectory: string,
   effectiveModel?: InvocationEffectiveModel,
+  effectiveEngine?: string,
 ): Promise<void> {
-  if (effectiveModel !== undefined) {
-    await recordEffectiveInvocationModel(runDirectory, effectiveModel);
+  if (effectiveModel !== undefined || effectiveEngine !== undefined) {
+    await recordEffectiveInvocationModel(
+      runDirectory,
+      effectiveModel,
+      effectiveEngine,
+    );
   }
   const current = await readRoleRunState(runDirectory);
   if (current === undefined) {

package/src/public-cli/settlement.ts

@@ -33,6 +33,7 @@ import {
   COLLECTOR_REQUEST_TOOL,
   COLLECTOR_WAIT_TOOL,
 } from "../collector-ledger.ts";
+import { ENGINE_DETOUR_TOOL_NAME } from "../engine-detour.ts";
 import {
   JUDGE_OUTPUT_TOOL_NAME,
   type JudgeVerdict,
@@ -1348,13 +1349,33 @@ const COLLECTOR_INFRASTRUCTURE_TOOLS = new Set<string>([
   COLLECTOR_WAIT_TOOL,
 ]);
 
+/** Shared match/cause/identity knobs for session-principal infrastructure failures. */
+type InfrastructureFailureSpec = Readonly<{
+  matchTool: (toolName: string) => boolean;
+  cause: ControlledFailureCause;
+  identityName: string;
+}>;
+
+const COLLECTOR_INFRASTRUCTURE_FAILURE_SPEC: InfrastructureFailureSpec = {
+  matchTool: (toolName) => COLLECTOR_INFRASTRUCTURE_TOOLS.has(toolName),
+  cause: "activation",
+  identityName: "CollectorInfrastructureError",
+};
+
+const ENGINE_DETOUR_INFRASTRUCTURE_FAILURE_SPEC: InfrastructureFailureSpec = {
+  matchTool: (toolName) => toolName === ENGINE_DETOUR_TOOL_NAME,
+  cause: "output",
+  identityName: "EngineDetourInfrastructureError",
+};
+
 /**
- * Prefer a real Collector infrastructure tool failure already on the session
- * principal over a later secondary provider-stop (failure-honesty).
- * Observe/request/wait host failures keep their diagnostic identity (e.g. HTTP 404).
+ * Prefer a real infrastructure tool failure already on the session principal
+ * over a later secondary provider-stop (failure-honesty).
+ * Tool match + cause + identity are call-site parameters — one extraction body.
  */
-export function extractCollectorInfrastructureFailure(
+function extractInfrastructureToolFailure(
   entries: readonly SessionEntry[],
+  spec: InfrastructureFailureSpec,
 ): ControlledFailure | undefined {
   for (let i = entries.length - 1; i >= 0; i -= 1) {
     const entry = entries[i];
@@ -1364,33 +1385,82 @@ export function extractCollectorInfrastructureFailure(
     if (message.isError !== true) continue;
     if (
       typeof message.toolName !== "string" ||
-      !COLLECTOR_INFRASTRUCTURE_TOOLS.has(message.toolName)
+      !spec.matchTool(message.toolName)
     ) {
       continue;
     }
     const diagnostic = toolResultText(message);
     if (diagnostic.length === 0) continue;
     return {
-      cause: "activation",
+      cause: spec.cause,
       diagnostic,
-      identity: { name: "CollectorInfrastructureError" },
+      identity: { name: spec.identityName },
     };
   }
   return undefined;
 }
 
-/** Read the bound session principal for a Collector infrastructure tool failure. */
-export async function readCollectorInfrastructureFailure(
+/** Read the bound session principal for a parameterized infrastructure tool failure. */
+async function readInfrastructureToolFailure(
   sessionFile: string,
+  spec: InfrastructureFailureSpec,
 ): Promise<ControlledFailure | undefined> {
   try {
     const entries = await readBoundSessionEntries(sessionFile);
-    return extractCollectorInfrastructureFailure(entries);
+    return extractInfrastructureToolFailure(entries, spec);
   } catch {
     return undefined;
   }
 }
 
+/**
+ * Prefer a real Collector infrastructure tool failure already on the session
+ * principal over a later secondary provider-stop (failure-honesty).
+ * Observe/request/wait host failures keep their diagnostic identity (e.g. HTTP 404).
+ */
+export function extractCollectorInfrastructureFailure(
+  entries: readonly SessionEntry[],
+): ControlledFailure | undefined {
+  return extractInfrastructureToolFailure(
+    entries,
+    COLLECTOR_INFRASTRUCTURE_FAILURE_SPEC,
+  );
+}
+
+/** Read the bound session principal for a Collector infrastructure tool failure. */
+export async function readCollectorInfrastructureFailure(
+  sessionFile: string,
+): Promise<ControlledFailure | undefined> {
+  return readInfrastructureToolFailure(
+    sessionFile,
+    COLLECTOR_INFRASTRUCTURE_FAILURE_SPEC,
+  );
+}
+
+/**
+ * Prefer a real engine-detour infrastructure tool failure already on the session
+ * principal over a later secondary provider-stop (failure-honesty / #357 T2).
+ * Cause stays `output` — labor leg failed before accepted typed Receipt.
+ */
+export function extractEngineDetourInfrastructureFailure(
+  entries: readonly SessionEntry[],
+): ControlledFailure | undefined {
+  return extractInfrastructureToolFailure(
+    entries,
+    ENGINE_DETOUR_INFRASTRUCTURE_FAILURE_SPEC,
+  );
+}
+
+/** Read the bound session principal for an engine-detour infrastructure failure. */
+export async function readEngineDetourInfrastructureFailure(
+  sessionFile: string,
+): Promise<ControlledFailure | undefined> {
+  return readInfrastructureToolFailure(
+    sessionFile,
+    ENGINE_DETOUR_INFRASTRUCTURE_FAILURE_SPEC,
+  );
+}
+
 /**
  * Compare a validated receipt with the admitted Collector invocation identity.
  * Throws a typed output failure when any identity field mismatches.

package/src/role-runtime.ts

@@ -21,6 +21,7 @@ import {
   writeToolExecutionObservationRecord,
   type ToolExecutionObservationWriter,
 } from "./tool-execution-observation.ts";
+import { registerEngineDetourTool } from "./engine-detour-tool.ts";
 import { installPackageOwnedToolRegistration } from "./package-owned-tool-idle.ts";
 import { installWorkerGitHooks } from "./worker-submission-gates.ts";
 import { createReceiptDeliveryPolicy, NO_RECEIPT_LIFECYCLE_ENTRY_TYPE, RECEIPT_DELIVERY_PROMPT } from "./receipt-delivery-policy.ts";
@@ -284,6 +285,7 @@ export {
   type JudgeVerdict,
   type SoulAuditResult,
 } from "./judge-role.ts";
+export { ENGINE_DETOUR_TOOL_NAME, AK_ROLE_ENGINE_ENV } from "./engine-detour.ts";
 export {
   AGENT_TOOL_NAME,
   REVIEWER_OUTPUT_TOOL_NAME,
@@ -590,6 +592,8 @@ export function createRoleRuntimeExtension(
     let pendingNavigatorSettlement: Promise<void> | undefined;
     let navigatorWorkContext: NavigatorWorkContext | undefined;
     const pendingInfrastructureToolCallIds = new Set<string>();
+    // #357 T2: engine detour once-latch + registration (Judge+engine only).
+    let engineDetourRegistration: ReturnType<typeof registerEngineDetourTool> | undefined;
     // #288 primary-session thin adapter. The policy is the sole budget owner;
     // terminating-tool rejections and mechanical delivery requests share two turns.
     let receiptDelivery = createReceiptDeliveryPolicy();
@@ -1053,6 +1057,7 @@ export function createRoleRuntimeExtension(
       pendingNavigatorPresentation = undefined;
       pendingNavigatorSettlement = undefined;
       pendingInfrastructureToolCallIds.clear();
+      engineDetourRegistration?.resetLatch();
       navigatorWorkContext = undefined;
       // #351: OAuth keepalive is orthogonal to --ak-role; start before role early-return
       // so role-less sessions (and reload after shutdown stop) still keep tokens alive.
@@ -1164,6 +1169,14 @@ export function createRoleRuntimeExtension(
         }
 
         await executeActivationStage(entry.role, activationStage(entry.role, runtime), { clock, writeTrace });
+        // #357 T2: Judge+engine activation registers the package detour tool once.
+        // Gate is env presence only — no per-engine execute branch; no judge-role spawn.
+        if (entry.role === "judge" && engineDetourRegistration === undefined) {
+          engineDetourRegistration = registerEngineDetourTool(pi, hostActions);
+          if (!engineDetourRegistration.registered) {
+            engineDetourRegistration = undefined;
+          }
+        }
         // Worker gates ②④ + ① baseline: envelope arms the worktree after role install.
         // Parent session feeds #216 createRecordSession so baseline/bounce survive resume.
         if (entry.role === "coder" || entry.role === "fixer") {