@akagilnc/pi-workflow-roles 0.1.2091 → 0.1.2101

package/README.md

@@ -11,7 +11,7 @@ pi install npm:@akagilnc/pi-workflow-roles
 export PATH="$HOME/.pi/agent/npm/node_modules/.bin:$PATH"
 ```
 
-Update with `pi update npm:@akagilnc/pi-workflow-roles`—never a second global `npm install -g`. Inspect with `ak-role roles` and `ak-role help <role>`; set per-seat defaults with `ak-role config set judge openai-codex/gpt-5.6-sol:high`.
+Update with `pi update npm:@akagilnc/pi-workflow-roles`—never a second global `npm install -g`. Inspect with `ak-role roles` and `ak-role help <role>`; set per-seat model defaults with `ak-role config set judge openai-codex/gpt-5.6-sol:high`; set or clear a persistent labor engine (judge|reviewer) with `ak-role config set-engine <seat> <name>` / `ak-role config unset-engine <seat>`.
 
 ## Reading results
 
@@ -31,10 +31,17 @@ Every run also prepares Navigator advice in the same Terminal. Configure it like
 
 ```bash
 ak-role config set navigator openai-codex/gpt-5.6-luna:medium
+# persistent labor engine (judge|reviewer only); one-shot override remains --engine
+ak-role config set-engine judge opus
+ak-role config unset-engine judge
 ```
 
+`config set` stores the seat model default; `config set-engine` / `unset-engine` store or clear the persistent labor-engine name on judge|reviewer only (same seats as `--engine`). Usage and refusal text are owned by `ak-role config` in the public CLI.
+
 Receipts are typed, so callers compose roles without parsing prose; ordering and stopping stay caller-owned. Programmatic consumers derive contracts from the exported schemas in `src/package-contracts/`, not from this guide.
 
+When a Judge/Reviewer labor-engine detour fails and the seat continues the labor on the main road, the typed receipt may carry a mechanical `engineLaborFallback` field: `{ engine, failure, laborBy: "seat" }`. It appears only after a real detour failure that fell back to seat labor (including package-owned idle timeout on the detour tool)—not on detour success or caller cancel. First failure wins for the activation; model-forged `engineLaborFallback` keys are stripped unless the package latch recorded one. Sole producer: `src/engine-labor-fallback.ts`; decision record: [ADR 0071](docs/adr/0071-engine-detour-failure-seat-fallback-declaration.md). This README only projects that contract.
+
 ## Call the roles
 
 Public option identity, aliases, requiredness, and mode faces live in the generated [Public CLI options](#public-cli-options-generated) table and in `ak-role help <command>` — both project the same typed source. The examples below are usage sketches, not a second flag contract. An instruction is optional for judge, collector, and doctor, and required nonblank for coder, fixer, reviewer, and merger.

package/README.zh-CN.md

@@ -11,7 +11,7 @@ pi install npm:@akagilnc/pi-workflow-roles
 export PATH="$HOME/.pi/agent/npm/node_modules/.bin:$PATH"
 ```
 
-更新用 `pi update npm:@akagilnc/pi-workflow-roles`——勿另起全局 `npm install -g`。查看能力：`ak-role roles`、`ak-role help <role>`；设席位默认：`ak-role config set judge openai-codex/gpt-5.6-sol:high`。
+更新用 `pi update npm:@akagilnc/pi-workflow-roles`——勿另起全局 `npm install -g`。查看能力：`ak-role roles`、`ak-role help <role>`；设席位模型默认：`ak-role config set judge openai-codex/gpt-5.6-sol:high`；设或清持久劳务引擎（仅 judge|reviewer）：`ak-role config set-engine <seat> <name>` / `ak-role config unset-engine <seat>`。
 
 ## 读结果
 
@@ -31,10 +31,17 @@ ak-role judge --attach ./plan.md "Review this plan." > result.txt
 
 ```bash
 ak-role config set navigator openai-codex/gpt-5.6-luna:medium
+# 持久劳务引擎（仅 judge|reviewer）；一次性覆盖仍用 --engine
+ak-role config set-engine judge opus
+ak-role config unset-engine judge
 ```
 
+`config set` 存席位模型默认；`config set-engine` / `unset-engine` 在 judge|reviewer 上写入或清除持久劳务引擎名（与 `--engine` 同轴）。用法与拒绝文案以公开 CLI 的 `ak-role config` 为准。
+
 回执是 typed 的，调用者不必解析散文即可组合角色；顺序与停止归调用者。编程消费者从 `src/package-contracts/` 导出推导契约，不从本文。
 
+当 Judge/Reviewer 劳务引擎绕行失败、座席回到主路继续劳务时，typed 回执可带机械字段 `engineLaborFallback`：`{ engine, failure, laborBy: "seat" }`。仅在真实绕行失败并座席顶班后出现（含 detour 工具命中 package-owned idle 超时）——成功绕行或调用方 cancel 不出现。同一次 activation 内先到先得；无包内 latch 时剥离模型伪造的 `engineLaborFallback` 键。唯一构造点：`src/engine-labor-fallback.ts`；决策记录：[ADR 0071](docs/adr/0071-engine-detour-failure-seat-fallback-declaration.md)。本文只投影该契约。
+
 ## 调用百官
 
 公开 option 身份、别名、必填性与 mode 面以生成区 [公开 CLI 选项（生成）](#公开-cli-选项生成) 与 `ak-role help <command>` 为准——二者同源。下例只是用法速写，不是第二份旗标合同。指令对大理寺、门下省、太医署可省略，对将作监、修内司、御史台、校书郎必须非空。

package/dist/engine-detour-tool.js

@@ -1,16 +1,51 @@
 import { Type } from "typebox";
 import { ENGINE_DETOUR_ALREADY_USED_DIAGNOSTIC, ENGINE_DETOUR_TOOL_NAME, engineDetourFailureDiagnostic, engineNameFromEnv, isEngineDetourFailure, runEngineDetourOnce, } from "./engine-detour.js";
-import { wrapPackageOwnedToolDefinition } from "./package-owned-tool-idle.js";
+import { activationEngineLaborFallbackLatch, recordEngineLaborFallback, } from "./engine-labor-fallback.js";
+import { isPackageOwnedToolIdleTimeoutError, pokePackageOwnedToolIdle, wrapPackageOwnedToolDefinition, } from "./package-owned-tool-idle.js";
 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. Build argv from the host CLI actual interface for the configured engine name; when optional packaged notes are present in the session prompt, follow those bytes. Do not invent package flags.",
     }),
 }, { additionalProperties: false });
+function seatFallbackToolResult(field, failure) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Engine detour failed: ${failure}. Perform the labor in this session (seat main road) and submit via the existing typed path. A mechanical fallback declaration will attach to the typed receipt.`,
+            },
+        ],
+        details: {
+            tool: ENGINE_DETOUR_TOOL_NAME,
+            detourFailed: true,
+            ...field,
+        },
+    };
+}
+/** Caller/upper-layer cancel must propagate; idle backstop is seat-fallback, not cancel. */
+function isCallerCancellation(error, signal) {
+    if (isPackageOwnedToolIdleTimeoutError(error))
+        return false;
+    if (signal !== undefined &&
+        isPackageOwnedToolIdleTimeoutError(signal.reason)) {
+        return false;
+    }
+    if (signal?.aborted === true)
+        return true;
+    if (typeof error === "object" &&
+        error !== null &&
+        error.name === "AbortError") {
+        return true;
+    }
+    return false;
+}
 /**
  * Build one once-latch detour tool definition for a configured engine name.
  * `latch` is shared so parent registration can reset between activations.
- * `fail` owns host abort (parent) vs throw (evidence child).
+ * `fail` owns host abort (parent) vs throw (evidence child) for tool misuse only.
+ * Engine process failure (nonzero/empty/spawn/idle-timeout) soft-returns seat fallback (#380).
+ * Caller AbortSignal cancel propagates without writing fallback.
  */
 export function createEngineDetourToolDefinition(input) {
     const latch = input.latch ?? { used: false };
@@ -24,6 +59,7 @@ export function createEngineDetourToolDefinition(input) {
             `Use ${ENGINE_DETOUR_TOOL_NAME} exactly once for the configured engine (${engineName}). Optional packaged notes are guidance when present; a bare engine name alone is also a valid call path.`,
             "Pass argv for the host CLI of this engine name — first element is the executable name on PATH. Follow optional packaged notes when delivered; otherwise act from the engine name and the host CLI actual interface. Do not invent package flags.",
             "On success, use the returned stdout as labor content for the existing typed submission / report path.",
+            "On engine failure the tool returns a soft failure: continue labor in this session and submit via the existing typed path. Do not treat engine failure as a reason to withhold the typed receipt.",
         ],
         parameters: engineDetourArgsSchema,
         async execute(toolCallId, params, signal, _onUpdate, ctx) {
@@ -36,19 +72,36 @@ export function createEngineDetourToolDefinition(input) {
             if (argv.length === 0 || argv.some((part) => typeof part !== "string" || part.length === 0)) {
                 input.fail(new Error("engine detour argv must be a non-empty string array"), toolCallId, ctx);
             }
+            const softFail = (failure) => {
+                // Activation-scoped latch is the sole shared recorder (parent seat + legs).
+                const fallbackLatch = activationEngineLaborFallbackLatch() ?? { field: undefined };
+                const field = recordEngineLaborFallback(fallbackLatch, {
+                    engine: engineName,
+                    failure,
+                });
+                return seatFallbackToolResult(field, failure);
+            };
             let result;
             try {
+                // Byte activity on stdout/stderr touches the outer package-owned idle clock
+                // (183s silence law unchanged). True hangs still die; slow streaming engines live.
                 result = await runEngineDetourOnce({
                     argv,
                     cwd: ctx.cwd,
                     ...(signal === undefined ? {} : { signal }),
+                    onOutputActivity: pokePackageOwnedToolIdle,
                 });
             }
             catch (error) {
-                input.fail(error instanceof Error ? error : new Error(String(error)), toolCallId, ctx);
+                // Caller cancel: propagate. Idle backstop + spawn/engine failure: seat fallback.
+                if (isCallerCancellation(error, signal)) {
+                    throw error;
+                }
+                const failure = error instanceof Error ? error.message : String(error);
+                return softFail(failure.trim() === "" ? "engine detour spawn failed" : failure);
             }
             if (isEngineDetourFailure(result)) {
-                input.fail(new Error(engineDetourFailureDiagnostic(result)), toolCallId, ctx);
+                return softFail(engineDetourFailureDiagnostic(result));
             }
             return {
                 content: [{ type: "text", text: result.stdout }],

package/dist/engine-detour.js

@@ -10,9 +10,21 @@ export const ENGINE_DETOUR_TOOL_NAME = "ak_engine_detour";
 export const AK_ROLE_ENGINE_ENV = "AK_ROLE_ENGINE";
 export const ENGINE_DETOUR_EMPTY_STDOUT_DIAGNOSTIC = "engine detour produced empty stdout";
 export const ENGINE_DETOUR_ALREADY_USED_DIAGNOSTIC = "engine detour already used in this activation";
+function abortReasonError(signal) {
+    const reason = signal.reason;
+    if (reason instanceof Error)
+        return reason;
+    if (typeof reason === "string" && reason.trim() !== "") {
+        return new Error(reason);
+    }
+    const error = new Error("aborted");
+    error.name = "AbortError";
+    return error;
+}
 /**
  * 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.
+ * AbortSignal cancels the child immediately via an explicit listener (reason preserved).
  */
 export async function runEngineDetourOnce(input) {
     if (input.argv.length === 0) {
@@ -22,32 +34,69 @@ export async function runEngineDetourOnce(input) {
     const args = input.argv.slice(1);
     return await new Promise((resolve, reject) => {
         let settled = false;
+        const signal = input.signal;
+        // Own abort→kill explicitly so rejection preserves signal.reason (caller cancel
+        // vs package-owned idle). Do not pass `signal` to spawn (Node replaces reason).
         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 = "";
+        const noteActivity = (chunk) => {
+            if (chunk.length === 0)
+                return;
+            input.onOutputActivity?.();
+        };
         child.stdout.setEncoding("utf8").on("data", (chunk) => {
             stdout += chunk;
+            noteActivity(chunk);
         });
         child.stderr.setEncoding("utf8").on("data", (chunk) => {
             stderr += chunk;
+            noteActivity(chunk);
         });
         const fail = (error) => {
             if (settled)
                 return;
             settled = true;
+            if (signal !== undefined) {
+                signal.removeEventListener("abort", onAbort);
+            }
             reject(error instanceof Error ? error : new Error(String(error)));
         };
-        child.on("error", (error) => fail(error));
-        child.on("close", (code) => {
+        const succeed = (result) => {
             if (settled)
                 return;
             settled = true;
-            resolve({ code: code ?? 1, stdout, stderr });
+            if (signal !== undefined) {
+                signal.removeEventListener("abort", onAbort);
+            }
+            resolve(result);
+        };
+        const onAbort = () => {
+            // Fail synchronously so cooperative idle/cancel paths can soft-settle
+            // before the outer package-owned idle hard-reject drain.
+            fail(signal !== undefined ? abortReasonError(signal) : new Error("aborted"));
+            try {
+                child.kill("SIGTERM");
+            }
+            catch {
+                // already exited
+            }
+        };
+        if (signal !== undefined) {
+            if (signal.aborted) {
+                onAbort();
+            }
+            else {
+                signal.addEventListener("abort", onAbort, { once: true });
+            }
+        }
+        child.on("error", (error) => fail(error));
+        child.on("close", (code) => {
+            succeed({ code: code ?? 1, stdout, stderr });
         });
     });
 }

package/dist/engine-labor-fallback.js

@@ -0,0 +1,121 @@
+/**
+ * #380 — sole shared seat-fallback declaration after engine detour failure.
+ * Detour rejoins the main road (ADR 0069); silence is the only crime.
+ * Construction of the typed receipt field lives in exactly one site (S1).
+ */
+/** Activation-scoped latch holder (one parent seat activation at a time). */
+let activationLatch;
+/** Sole construction site for typed receipt field `engineLaborFallback` (#380 S1). */
+export function buildEngineLaborFallbackField(input) {
+    return Object.freeze({
+        engineLaborFallback: Object.freeze({
+            engine: input.engine,
+            failure: input.failure,
+            laborBy: "seat",
+        }),
+    });
+}
+export function createEngineLaborFallbackLatch() {
+    return { field: undefined };
+}
+/**
+ * Record first detour failure for this latch (first wins; parallel legs share one field).
+ * Always returns the latched first-wins value so tool details and receipt projection match.
+ */
+export function recordEngineLaborFallback(latch, input) {
+    const field = buildEngineLaborFallbackField(input);
+    if (latch.field === undefined)
+        latch.field = field;
+    return latch.field;
+}
+export function readEngineLaborFallbackField(latch) {
+    return latch?.field;
+}
+/**
+ * Merge sole-built field into typed receipt details.
+ * Spread only — must not construct the field key again (S1).
+ * Without a mechanical latch, strip any model-injected reserved key (no forged declaration).
+ */
+export function withEngineLaborFallbackField(receipt, field) {
+    if (field !== undefined) {
+        return { ...receipt, ...field };
+    }
+    if (!Object.prototype.hasOwnProperty.call(receipt, "engineLaborFallback")) {
+        return receipt;
+    }
+    const { engineLaborFallback: _forged, ...rest } = receipt;
+    return rest;
+}
+/** Install the activation-scoped latch (Judge/Reviewer session_start). */
+export function installActivationEngineLaborFallbackLatch(latch) {
+    activationLatch = latch;
+}
+/** Clear activation latch (session end / next activation). */
+export function clearActivationEngineLaborFallbackLatch() {
+    activationLatch = undefined;
+}
+/** Active activation latch, if any (legs inherit parent seat activation). */
+export function activationEngineLaborFallbackLatch() {
+    return activationLatch;
+}
+/** Read fallback field from the active activation latch. */
+export function readActivationEngineLaborFallbackField() {
+    return readEngineLaborFallbackField(activationLatch);
+}
+/**
+ * Read a previously attached declaration from a typed receipt / details object.
+ * Rebuilds via the sole construction site — callers must spread, never re-key.
+ */
+export function readEngineLaborFallbackFieldFrom(source) {
+    if (typeof source !== "object" || source === null || Array.isArray(source)) {
+        return undefined;
+    }
+    let raw;
+    try {
+        raw = source.engineLaborFallback;
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        return undefined;
+    const rec = raw;
+    if (typeof rec.engine !== "string" ||
+        typeof rec.failure !== "string" ||
+        rec.laborBy !== "seat") {
+        return undefined;
+    }
+    return buildEngineLaborFallbackField({
+        engine: rec.engine,
+        failure: rec.failure,
+    });
+}
+/**
+ * Restore activation latch from durable session tool results (#380 resume).
+ * Scans existing same-session detour tool results only — no sidecar / new entry type.
+ * Replays through recordEngineLaborFallback so first-wins + sole producer stay intact.
+ */
+export function restoreEngineLaborFallbackFromSessionEntries(latch, entries, toolName) {
+    for (const entry of entries) {
+        if (typeof entry !== "object" || entry === null)
+            continue;
+        const row = entry;
+        if (row.type !== "message")
+            continue;
+        const message = row.message;
+        if (typeof message !== "object" || message === null)
+            continue;
+        const msg = message;
+        if (msg.role !== "toolResult")
+            continue;
+        if (msg.toolName !== toolName)
+            continue;
+        const field = readEngineLaborFallbackFieldFrom(msg.details);
+        if (field === undefined)
+            continue;
+        recordEngineLaborFallback(latch, {
+            engine: field.engineLaborFallback.engine,
+            failure: field.engineLaborFallback.failure,
+        });
+    }
+}

package/dist/evidence-child-executor.js

@@ -472,16 +472,14 @@ export async function executeEvidenceChild(workspace, prompt, context, options =
                     engine: engineName,
                     packageRoot: options.packageRoot,
                 });
-        // #378: detour failure is durable for this leg — later assistant reports cannot wash it.
-        let engineDetourFailure;
+        // #378/#380: same detour tool as parent seat. Engine process failure soft-returns
+        // seat main-road fallback (ADR 0069 detour-rejoins-main-road); tool misuse still throws.
         const engineDetourTool = engineName === undefined
             ? undefined
             : createEngineDetourToolDefinition({
                 engineName,
                 fail(error) {
-                    const failure = error instanceof Error ? error : new Error(String(error));
-                    engineDetourFailure = failure;
-                    throw failure;
+                    throw error instanceof Error ? error : new Error(String(error));
                 },
             });
         // No tools allowlist — Pi defaults + unrestricted evidence surface (ADR 0064).
@@ -520,18 +518,8 @@ export async function executeEvidenceChild(workspace, prompt, context, options =
                 await session.prompt(delivered);
             }
             catch (error) {
-                // Engine detour fail becomes isError toolResult and must outrank a later
-                // provider-shaped throw from the same prompt turn (#378).
-                if (engineDetourFailure !== undefined) {
-                    throw classifiedError(engineDetourFailure, "child");
-                }
                 throw classifiedError(error, "provider");
             }
-            // Launched-leg detour non-zero / empty stdout / spawn failure is infrastructure:
-            // reject the leg even when the model still emits a non-blank report afterward.
-            if (engineDetourFailure !== undefined) {
-                throw classifiedError(engineDetourFailure, "child");
-            }
             if (signal?.aborted)
                 throw new Error("Evidence child was cancelled");
             const lastAssistant = [...session.messages]

package/dist/package-owned-tool-idle.js

@@ -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 { DEFAULT_STREAM_IDLE_TIMEOUT_MS, createStreamIdleGuard, } from "./stream-idle-guard.js";
@@ -29,6 +34,13 @@ export class PackageOwnedToolIdleTimeoutError extends Error {
         this.name = "PackageOwnedToolIdleTimeoutError";
     }
 }
+export function isPackageOwnedToolIdleTimeoutError(value) {
+    return (value instanceof PackageOwnedToolIdleTimeoutError ||
+        (typeof value === "object" &&
+            value !== null &&
+            value.name === "PackageOwnedToolIdleTimeoutError" &&
+            value.code === PACKAGE_OWNED_TOOL_IDLE_TIMEOUT_CODE));
+}
 /**
  * Package-tool activity includes content production and host-only details
  * progress. Keep the observation-plane oracle separate: its stderr heartbeat
@@ -68,6 +80,14 @@ export async function withPackageOwnedToolIdleSuspended(run) {
         scope.resume();
     }
 }
+/**
+ * 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() {
+    packageOwnedToolIdleScope.getStore()?.poke();
+}
 /**
  * Single shared execute wrapper for package-owned tool definitions.
  * Idempotent: wrapping twice returns the same protected definition.
@@ -79,7 +99,7 @@ export function wrapPackageOwnedToolDefinition(tool) {
         return tool;
     const originalExecute = tool.execute.bind(tool);
     const wrappedExecute = function packageOwnedToolIdleExecute(...args) {
-        const signal = args[2];
+        const parentSignal = args[2];
         const onUpdate = args[3];
         return new Promise((resolve, reject) => {
             let settled = false;
@@ -87,16 +107,47 @@ export function wrapPackageOwnedToolDefinition(tool) {
             let idle = createStreamIdleGuard({
                 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 = () => {
+                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 = () => {
+                idle.signal.removeEventListener("abort", onIdle);
+                idle.dispose();
+                parentSignal?.removeEventListener("abort", onParentAbort);
+            };
             const settle = (deliver) => {
                 if (settled)
                     return;
                 settled = true;
-                idle.signal.removeEventListener("abort", onIdle);
-                idle.dispose();
+                cleanup();
                 deliver();
             };
             const onIdle = () => {
-                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 });
             const suspension = {
@@ -118,6 +169,11 @@ export function wrapPackageOwnedToolDefinition(tool) {
                     });
                     idle.signal.addEventListener("abort", onIdle, { once: true });
                 },
+                poke() {
+                    if (settled || suspended)
+                        return;
+                    idle.poke();
+                },
             };
             const guardedOnUpdate = onUpdate === undefined
                 ? undefined
@@ -129,8 +185,9 @@ export function wrapPackageOwnedToolDefinition(tool) {
                     onUpdate(partialResult);
                 };
             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 () => {
                 try {