@akagilnc/pi-workflow-roles 0.1.2089 → 0.1.2096

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/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