@akagilnc/pi-workflow-roles 0.1.2091 → 0.1.2101

package/src/judge-role.ts

@@ -8,6 +8,10 @@ import { Type, type Static } from "typebox";
 
 import { disposeComplianceDecision } from "./audit-escalation.ts";
 import type { ComplianceDecision } from "./compliance-transport.ts";
+import {
+  readActivationEngineLaborFallbackField,
+  withEngineLaborFallbackField,
+} from "./engine-labor-fallback.ts";
 
 import {
   JUDGE_OUTPUT_TOOL_NAME,
@@ -126,18 +130,21 @@ export function createJudgeRoleRuntime(
             } catch (error) {
               hostActions.failInfrastructure(error, ctx, toolCallId);
             }
+            // #380: attach sole-built engineLaborFallback when detour fell back to seat labor.
+            const laborFallback = readActivationEngineLaborFallbackField();
+            const acceptedDetails = withEngineLaborFallbackField(verdict, laborFallback);
             return disposeComplianceDecision<AgentToolResult<unknown>>(
               audit,
               {
                 pass: (usage) => ({
                   content: [{ type: "text" as const, text: "Judge verdict accepted" }],
-                  details: verdict,
+                  details: acceptedDetails,
                   terminate: true as const,
                   ...(usage === undefined ? {} : { usage }),
                 }),
                 noReceipt: (auditNoReceipt, usageProjection) => ({
                   content: [{ type: "text" as const, text: "Judge verdict accepted; compliance audit produced no receipt" }],
-                  details: { ...verdict, auditNoReceipt },
+                  details: { ...acceptedDetails, auditNoReceipt },
                   terminate: true as const,
                   ...usageProjection,
                 }),
@@ -149,7 +156,8 @@ export function createJudgeRoleRuntime(
                 escalate: (result) => result,
                 auditIncomplete: (result) => result,
               },
-              verdict,
+              // #380: escalate deliveredOutput must carry the same mechanical projection.
+              acceptedDetails,
             );
           },
         });

package/src/package-owned-tool-idle.ts

@@ -4,11 +4,16 @@
  * Fixed 183000ms silence clock on package-owned tool execute only.
  * Real producing onUpdate resets; final resolve/reject clears; timeout throws so
  * Pi settles the current call as an LLM-visible isError tool result. No retry,
- * role failure, process termination, signal abort, config, or Pi built-in coverage.
+ * role failure, process termination, config, or Pi built-in coverage.
  *
  * #339: do not name-exempt whole terminating tools. Outer idle stays armed for
  * pre/post-audit work. Only the real compliance-audit await suspends this single
  * layer (ADR 0059 owns that interval); resume re-arms the same outer backstop.
+ *
+ * #380: on idle, abort a derived tool signal (not the caller signal) so detour
+ * spawn cleanup and softFail can run through the existing AbortSignal path.
+ * Cooperative soft-settle may win; non-listeners still hard-reject after a
+ * microtask drain (no second timer).
  */
 import { AsyncLocalStorage } from "node:async_hooks";
 import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
@@ -28,6 +33,8 @@ const WRAPPED = Symbol.for("ak.packageOwnedToolIdleWrapped");
 type PackageOwnedToolIdleSuspension = {
   suspend(): void;
   resume(): void;
+  /** Reset the silence window (byte/activity signal from the active execute). */
+  poke(): void;
 };
 
 /**
@@ -46,6 +53,20 @@ export class PackageOwnedToolIdleTimeoutError extends Error {
   }
 }
 
+export function isPackageOwnedToolIdleTimeoutError(
+  value: unknown,
+): value is PackageOwnedToolIdleTimeoutError {
+  return (
+    value instanceof PackageOwnedToolIdleTimeoutError ||
+    (
+      typeof value === "object" &&
+      value !== null &&
+      (value as { name?: unknown }).name === "PackageOwnedToolIdleTimeoutError" &&
+      (value as { code?: unknown }).code === PACKAGE_OWNED_TOOL_IDLE_TIMEOUT_CODE
+    )
+  );
+}
+
 /** Minimal executable tool shape accepted by the shared idle wrapper. */
 export type PackageOwnedToolLike = {
   readonly name: string;
@@ -87,6 +108,15 @@ export async function withPackageOwnedToolIdleSuspended<T>(
   }
 }
 
+/**
+ * Touch the active package-owned execute idle clock (reuse stream-idle-guard poke).
+ * No-op outside a wrapped package-owned execute or while that layer is suspended.
+ * Used by long-running tools (engine detour) that see real subprocess output bytes.
+ */
+export function pokePackageOwnedToolIdle(): void {
+  packageOwnedToolIdleScope.getStore()?.poke();
+}
+
 /**
  * Single shared execute wrapper for package-owned tool definitions.
  * Idempotent: wrapping twice returns the same protected definition.
@@ -103,7 +133,7 @@ export function wrapPackageOwnedToolDefinition<T extends PackageOwnedToolLike>(t
   const wrappedExecute = function packageOwnedToolIdleExecute(
     ...args: unknown[]
   ): Promise<unknown> {
-    const signal = args[2] as AbortSignal | undefined;
+    const parentSignal = args[2] as AbortSignal | undefined;
     const onUpdate = args[3] as ((partialResult: unknown) => void) | undefined;
     return new Promise((resolve, reject) => {
       let settled = false;
@@ -112,15 +142,46 @@ export function wrapPackageOwnedToolDefinition<T extends PackageOwnedToolLike>(t
         idleTimeoutMs: PACKAGE_OWNED_TOOL_IDLE_TIMEOUT_MS,
       });
 
+      // Derived tool signal: caller cancel forwards; idle aborts this only (not parent).
+      const toolController = new AbortController();
+      const onParentAbort = (): void => {
+        if (toolController.signal.aborted) return;
+        toolController.abort(parentSignal?.reason);
+      };
+      if (parentSignal !== undefined) {
+        if (parentSignal.aborted) {
+          toolController.abort(parentSignal.reason);
+        } else {
+          parentSignal.addEventListener("abort", onParentAbort);
+        }
+      }
+
+      const cleanup = (): void => {
+        idle.signal.removeEventListener("abort", onIdle);
+        idle.dispose();
+        parentSignal?.removeEventListener("abort", onParentAbort);
+      };
+
       const settle = (deliver: () => void): void => {
         if (settled) return;
         settled = true;
-        idle.signal.removeEventListener("abort", onIdle);
-        idle.dispose();
+        cleanup();
         deliver();
       };
       const onIdle = (): void => {
-        settle(() => reject(new PackageOwnedToolIdleTimeoutError()));
+        const idleError = new PackageOwnedToolIdleTimeoutError();
+        if (!toolController.signal.aborted) {
+          toolController.abort(idleError);
+        }
+        // Cooperative tools (detour) soft-settle via the aborted signal in the
+        // next microtasks. Non-listeners still hard-reject after a short drain
+        // of those microtasks — no second wall-clock timer.
+        void Promise.resolve()
+          .then(() => {})
+          .then(() => {})
+          .then(() => {
+            settle(() => reject(idleError));
+          });
       };
       idle.signal.addEventListener("abort", onIdle, { once: true });
 
@@ -141,6 +202,10 @@ export function wrapPackageOwnedToolDefinition<T extends PackageOwnedToolLike>(t
           });
           idle.signal.addEventListener("abort", onIdle, { once: true });
         },
+        poke(): void {
+          if (settled || suspended) return;
+          idle.poke();
+        },
       };
 
       const guardedOnUpdate = onUpdate === undefined
@@ -152,8 +217,9 @@ export function wrapPackageOwnedToolDefinition<T extends PackageOwnedToolLike>(t
           };
 
       const callArgs = args.slice();
-      // Preserve the original signal at args[2]; timeout must not abort it.
-      callArgs[2] = signal;
+      // Pass derived signal so idle/cancel can clean up subprocesses without
+      // aborting the caller/parent agent signal identity.
+      callArgs[2] = toolController.signal;
       callArgs[3] = guardedOnUpdate;
 
       void packageOwnedToolIdleScope.run(suspension, async () => {

package/src/public-cli/cli.ts

@@ -13,7 +13,7 @@ import {
   formatModelSpec,
   loadCredentialProviders,
   loadPublicCliConfig,
-  parsePersistentModelSpec,
+  parseModelSpec,
   resolveEffectiveSeat,
   savePublicCliConfig,
   isEngineAxisSeat,
@@ -418,7 +418,7 @@ function renderHelp(): string {
   lines.push(
     "",
     "Role options: ak-role help <command>",
-    "Persistent config: ak-role config set <seat> <provider/model:thinking>",
+    "Persistent config: ak-role config set <seat> <provider/model[:thinking]>",
     "Persistent engine (judge|reviewer): ak-role config set-engine <seat> <name> | unset-engine <seat>",
     "Effective seats: ak-role roles",
   );
@@ -507,7 +507,7 @@ async function runConfigCommand(
   if (args[0] === "set") {
     if (args.length < 3) {
       throw new CliUsageError(
-        "usage: ak-role config set <seat> <provider/model:thinking>",
+        "usage: ak-role config set <seat> <provider/model[:thinking]>",
       );
     }
     // Bulk: repeated seat spec pairs after `set`
@@ -524,7 +524,9 @@ async function runConfigCommand(
       if (!isPublicConfigurableSeat(seat)) {
         throw new CliUsageError(`unknown configurable seat: ${seat}`);
       }
-      config = setPersistentSeatConfig(config, seat, parsePersistentModelSpec(spec));
+      // #384: persistent seat config shares the invocation model grammar.
+      // Bare provider/model stores as-is; :thinking suffix still required only when colon present.
+      config = setPersistentSeatConfig(config, seat, parseModelSpec(spec));
     }
     await savePublicCliConfig(config, home);
     io.stdout(renderConfig(config));

package/src/public-cli/config.ts

@@ -23,7 +23,7 @@ export type CredentialProviders = {
 
 export type SeatModelConfig = ModelRef;
 
-/** Persistent seat row: required model triple + optional engine axis (#356). */
+/** Persistent seat row: provider/model[:thinking] + optional engine axis (#356/#384). */
 export type PersistentSeatConfig = SeatModelConfig & {
   engine?: string;
 };
@@ -123,7 +123,7 @@ export function isEngineAxisSeat(seat: string): seat is "judge" | "reviewer" {
 
 /**
  * Set or clear persistent engine on Judge or Reviewer (#356 / #378).
- * Engine-only seats are rejected — model triple remains required.
+ * Engine-only seats are rejected — provider/model[:thinking] remains required first.
  */
 export function setPersistentSeatEngine(
   config: PublicCliConfig,
@@ -136,7 +136,7 @@ export function setPersistentSeatEngine(
   const previous = config.seats[seat];
   if (previous === undefined) {
     throw new Error(
-      `config seat ${seat} has no persistent model; set provider/model:thinking before engine`,
+      `config seat ${seat} has no persistent model; set provider/model[:thinking] before engine`,
     );
   }
   if (engine === undefined) {
@@ -226,30 +226,12 @@ export function parseModelSpec(
   }
   const provider = modelPart.slice(0, slash);
   const model = modelPart.slice(slash + 1);
-  // #346: bare provider/model is legal on invocation — do not invent thinking.
-  // Persistent config set still requires thinking via parsePersistentModelSpec.
+  // #346/#384: bare provider/model is legal — do not invent thinking.
   return thinking === undefined
     ? { provider, model }
     : { provider, model, thinking };
 }
 
-/** Persistent seat config keeps the three-part provider/model:thinking grammar. */
-export function parsePersistentModelSpec(spec: string): SeatModelConfig & {
-  thinking: PublicThinkingLevel;
-} {
-  const parsed = parseModelSpec(spec);
-  if (parsed.thinking === undefined) {
-    throw new Error(
-      `model specification requires a thinking level (provider/model:thinking), got ${spec}`,
-    );
-  }
-  return {
-    provider: parsed.provider,
-    model: parsed.model,
-    thinking: parsed.thinking,
-  };
-}
-
 export function formatModelSpec(selection: SeatModelConfig): string {
   const base = `${selection.provider}/${selection.model}`;
   return selection.thinking === undefined ? base : `${base}:${selection.thinking}`;
@@ -308,16 +290,21 @@ function parseSeatModelConfig(value: unknown, seat: string): PersistentSeatConfi
   if (typeof raw.model !== "string" || raw.model.trim() === "") {
     throw new Error(`config seat ${seat} requires model`);
   }
-  if (
-    typeof raw.thinking !== "string" ||
-    !THINKING_LEVELS.has(raw.thinking as PublicThinkingLevel)
-  ) {
-    throw new Error(`config seat ${seat} requires a valid thinking level`);
+  // #384: thinking is optional on persistent seats; when present it must be typed.
+  if (raw.thinking !== undefined) {
+    if (
+      typeof raw.thinking !== "string" ||
+      !THINKING_LEVELS.has(raw.thinking as PublicThinkingLevel)
+    ) {
+      throw new Error(`config seat ${seat} requires a valid thinking level`);
+    }
   }
   const parsed: PersistentSeatConfig = {
     provider: raw.provider,
     model: raw.model,
-    thinking: raw.thinking as PublicThinkingLevel,
+    ...(raw.thinking === undefined
+      ? {}
+      : { thinking: raw.thinking as PublicThinkingLevel }),
   };
   if (raw.engine !== undefined) {
     // Shape only: engine must be a string field. Path-safety syntax is deferred to

package/src/public-cli/settlement.ts

@@ -34,6 +34,7 @@ import {
   COLLECTOR_WAIT_TOOL,
 } from "../collector-ledger.ts";
 import { ENGINE_DETOUR_TOOL_NAME } from "../engine-detour.ts";
+import { readEngineLaborFallbackFieldFrom } from "../engine-labor-fallback.ts";
 import {
   JUDGE_OUTPUT_TOOL_NAME,
   type JudgeVerdict,
@@ -1060,7 +1061,12 @@ function judgeDecisiveFacts(
   verdict: object,
   judgeStatus: JudgeVerdict["judgeStatus"],
 ): Record<string, unknown> {
-  const facts: Record<string, unknown> = { judgeStatus, ...auditNoReceiptDecisiveFact(verdict) };
+  const facts: Record<string, unknown> = {
+    judgeStatus,
+    ...auditNoReceiptDecisiveFact(verdict),
+    // #380: spread sole-built field; do not re-key here (S1).
+    ...readEngineLaborFallbackFieldFrom(verdict),
+  };
   if (judgeStatus === "continue") {
     const fix = safelyRead(verdict, "fix");
     if (fix.readable && isRecord(fix.value)) {
@@ -1260,6 +1266,8 @@ function reviewerDecisiveFacts(
     reportAxes,
     acceptedBatchPresent: acceptedBatch.readable && acceptedBatch.value !== undefined,
     ...auditNoReceiptDecisiveFact(candidate),
+    // #380: spread sole-built field; do not re-key here (S1).
+    ...readEngineLaborFallbackFieldFrom(candidate),
   };
   if (status.readable && typeof status.value === "string") facts.reviewerStatus = status.value;
   if (

package/src/reviewer-role.ts

@@ -7,6 +7,10 @@ export type { CanonicalSkillBinding };
 import { disposeComplianceDecision } from "./audit-escalation.ts";
 import type { ComplianceDecision } from "./compliance-transport.ts";
 import { appendActiveSessionCustomEntry } from "./compliance-transport.ts";
+import {
+  readActivationEngineLaborFallbackField,
+  withEngineLaborFallbackField,
+} from "./engine-labor-fallback.ts";
 import { REVIEWER_CANDIDATE_ENTRY_TYPE } from "./dossier-resolution.ts";
 import { type ReviewerSpecDisposition } from "./reviewer-construction.ts";
 import { createReviewerDispatcher, type AcceptedReviewerDispatch, type AcceptedReviewerExecution, type ReviewerIssueFetcher, type ReviewerPinnedGitReader } from "./reviewer-dispatch.ts";
@@ -145,11 +149,15 @@ export function createReviewerRoleRuntime(
             const output = validateReviewerIntent(parameters);
             let record: ReviewerExecutionRecord;
             try { record = ledger.recordForAudit(output.status); } catch (error) { if ((error as any)?.fatalReviewerInfrastructure) hostActions.failInfrastructure(error, toolCtx, id); throw error; }
-            const candidate = assembleRuntimeReviewerReceipt({
-              intent: output,
-              record,
-              canonicalSkillText: binding.snapshot.raw,
-            });
+            const candidate = withEngineLaborFallbackField(
+              assembleRuntimeReviewerReceipt({
+                intent: output,
+                record,
+                canonicalSkillText: binding.snapshot.raw,
+              }),
+              // #380: sole-built declaration when any leg detour fell back to seat labor.
+              readActivationEngineLaborFallbackField(),
+            );
             // First-record-then-audit: candidate lands on the parent session books
             // before the auditor is spawned (zero hand-delivery).
             try {

package/src/role-runtime.ts

@@ -21,7 +21,13 @@ import {
   writeToolExecutionObservationRecord,
   type ToolExecutionObservationWriter,
 } from "./tool-execution-observation.ts";
+import { ENGINE_DETOUR_TOOL_NAME } from "./engine-detour.ts";
 import { registerEngineDetourTool } from "./engine-detour-tool.ts";
+import {
+  createEngineLaborFallbackLatch,
+  installActivationEngineLaborFallbackLatch,
+  restoreEngineLaborFallbackFromSessionEntries,
+} from "./engine-labor-fallback.ts";
 import { installPackageOwnedToolRegistration } from "./package-owned-tool-idle.ts";
 import { createReceiptDeliveryPolicy, NO_RECEIPT_LIFECYCLE_ENTRY_TYPE, RECEIPT_DELIVERY_PROMPT } from "./receipt-delivery-policy.ts";
 import { createOAuthKeepalive, type OAuthKeepaliveOptions } from "./oauth-keepalive.ts";
@@ -591,8 +597,9 @@ export function createRoleRuntimeExtension(
     let pendingNavigatorSettlement: Promise<void> | undefined;
     let navigatorWorkContext: NavigatorWorkContext | undefined;
     const pendingInfrastructureToolCallIds = new Set<string>();
-    // #357 T2 / #378: engine detour once-latch + registration (Judge|Reviewer+engine).
+    // #357 T2 / #378 / #380: engine detour once-latch + seat-fallback latch (Judge|Reviewer+engine).
     let engineDetourRegistration: ReturnType<typeof registerEngineDetourTool> | undefined;
+    let engineLaborFallbackLatch = createEngineLaborFallbackLatch();
     // #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();
@@ -1056,6 +1063,18 @@ export function createRoleRuntimeExtension(
       pendingNavigatorPresentation = undefined;
       pendingNavigatorSettlement = undefined;
       pendingInfrastructureToolCallIds.clear();
+      engineLaborFallbackLatch = createEngineLaborFallbackLatch();
+      // #380 resume: restore sole-built fallback from durable same-session detour results.
+      const sessionEntries =
+        typeof ctx.sessionManager?.getEntries === "function"
+          ? ctx.sessionManager.getEntries()
+          : [];
+      restoreEngineLaborFallbackFromSessionEntries(
+        engineLaborFallbackLatch,
+        sessionEntries,
+        ENGINE_DETOUR_TOOL_NAME,
+      );
+      installActivationEngineLaborFallbackLatch(engineLaborFallbackLatch);
       engineDetourRegistration?.resetLatch();
       navigatorWorkContext = undefined;
       // #351: OAuth keepalive is orthogonal to --ak-role; start before role early-return
@@ -1168,8 +1187,9 @@ export function createRoleRuntimeExtension(
         }
 
         await executeActivationStage(entry.role, activationStage(entry.role, runtime), { clock, writeTrace });
-        // #357 T2 / #378: Judge|Reviewer+engine activation registers the package detour tool once.
+        // #357 T2 / #378 / #380: Judge|Reviewer+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