@akira-tl/forgerelay 0.4.6 → 0.4.7

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.4.7] - 2026-08-11
+
+### Added
+
+- Added independent `bash` execution deadlines with optional `timeoutMs`; `yieldTimeMs` now remains purely a feedback window, including `yieldTimeMs: 0` for immediate background handoff to a canonical `processId`.
+
+### Changed
+
+- Regular `bash` now defaults to a 10-second feedback window instead of occupying a full 300-second Host request; Agent-selected waits can still be up to 300 seconds, while execution can continue without a ForgeRelay deadline when `timeoutMs` is omitted.
+- Completed background processes keep full buffered output for five minutes, then compact to a bounded completion record deliverable for up to 24 hours. Completed results no longer block workspace close and are delivered with the close response when available.
+- Local `release:verify` now records a proof for the committed release HEAD, while the stable-tag `BeforeTool` Hook performs only a fast proof/HEAD/version/tag check before the push instead of rerunning the multi-minute release gate inside one MCP request.
+
+### Fixed
+
+- Propagated Host request cancellation through lifecycle Hooks and shell process waits. If a Host cancels while a blocking `BeforeTool` Hook is still running, ForgeRelay terminates the Hook and does not execute the original tool side effect; cancellation of an initial shell run also terminates a process whose `processId` has not yet been delivered.
+- Corrected `ProcessManager` yield bounding so a configured maximum also caps the default feedback window rather than only explicit `yieldTimeMs` values.
+- Made the new release-proof and Hook-cancellation test harnesses use cross-platform Node path and shell invocation forms, covering Windows drive-letter paths and `cmd.exe` Hook execution as well as POSIX hosts.
+
 ## [0.4.6] - 2026-08-11
 
 ### Added

package/README.md

@@ -163,13 +163,13 @@ Hook 是 ForgeRelay 的自动生命周期规则。首选方式是一个 Hook 一
     "tool": "bash",
     "commandRegex": "git\\s+push\\s+origin\\s+v\\d+\\.\\d+\\.\\d+"
   },
-  "command": "npm run release:verify",
-  "timeoutSeconds": 300,
+  "command": "node scripts/release-proof.mjs check-hook",
+  "timeoutSeconds": 30,
   "report": true
 }
 ```
 
-命中 `BeforeTool` 后，Hook 先执行；成功才继续原始 `git push`，失败则直接阻断。Hook 结果会回到 Agent，Agent 应向用户说明重要 Hook 是否通过或阻断了操作。`report:false` 可以隐藏不重要的成功报告，但阻断失败始终可见。
+耗时的 `npm run release:verify` 应先在已提交的 release-ready HEAD 上运行，它会写入绑定 HEAD/package version 的本地 release proof。命中 `BeforeTool` 后，Hook 只快速验证该 proof、clean working tree（含 untracked）与 tag 指向；成功才继续原始 `git push`，失败则直接阻断。这样发布 gate 不依赖一个持续数分钟的 MCP 请求。Hook 结果会回到 Agent，Agent 应向用户说明重要 Hook 是否通过或阻断了操作。`report:false` 可以隐藏不重要的成功报告，但阻断失败始终可见。
 
 旧的 inline `hooks` 和聚合 `hooks.json` 仍兼容；新配置建议都用独立 `hooks/*.json` 文件。
 
@@ -292,10 +292,11 @@ npm run release:major
 npm run release:verify
 ```
 
-Daily branch pushes do not run cloud CI. When preparing a release, run the full
-local release verification first. `release:verify` includes a focused parity pass
-in an isolated Node 22.19.0 environment with its own `npm ci`, matching the cloud
-CI runtime for native addons and high-risk LSP lifecycle tests. Pushing a matching
+Daily branch pushes do not run cloud CI. When preparing a release, commit the
+release-ready tree and run the full local release verification on that clean HEAD.
+`release:verify` includes a focused parity pass in an isolated Node 22.19.0 environment
+with its own `npm ci`, matching the cloud CI runtime for native addons and high-risk
+LSP lifecycle tests, then writes the local proof consumed by the tag-push Hook. Pushing a matching
 `vX.Y.Z` tag to `Akira-TL/forgerelay` is the only cloud CI and publish trigger:
 GitHub Actions runs the reusable multi-platform CI, then publishes
 `@akira-tl/forgerelay` and creates the matching GitHub Release only after CI

package/dist/hooks.js

@@ -105,7 +105,8 @@ export async function runToolWithHooks(runner, options) {
         executions.push(...await runner.run("BeforeTool", {
             ...options.invocation,
             payload: basePayload,
-        }));
+        }, options.signal));
+        options.signal?.throwIfAborted();
         const result = await options.operation();
         const afterCwd = options.afterCwd?.(result);
         if (options.isFailure?.(result)) {
@@ -113,7 +114,7 @@ export async function runToolWithHooks(runner, options) {
                 ...options.invocation,
                 cwd: afterCwd,
                 payload: basePayload,
-            }));
+            }, options.signal));
             const reported = attachHookReports(result, executions);
             return decorateToolResult(runner, options.invocation.workspaceId, reported);
         }
@@ -121,14 +122,14 @@ export async function runToolWithHooks(runner, options) {
             ...options.invocation,
             cwd: afterCwd,
             payload: basePayload,
-        }));
+        }, options.signal));
         const changedPaths = options.changedPaths?.(result) ?? [];
         if (changedPaths.length > 0) {
             executions.push(...await runner.run("AfterFileChange", {
                 ...options.invocation,
                 cwd: afterCwd,
                 payload: { ...basePayload, paths: changedPaths },
-            }));
+            }, options.signal));
         }
         const reported = attachHookReports(result, executions);
         return decorateToolResult(runner, options.invocation.workspaceId, reported);
@@ -137,13 +138,15 @@ export async function runToolWithHooks(runner, options) {
         if (error instanceof HookExecutionError) {
             executions.push(...error.executions);
         }
-        executions.push(...await runner.run("AfterToolFailure", {
-            ...options.invocation,
-            payload: {
-                ...basePayload,
-                errorType: error instanceof Error ? error.name : "Error",
-            },
-        }));
+        if (!options.signal?.aborted) {
+            executions.push(...await runner.run("AfterToolFailure", {
+                ...options.invocation,
+                payload: {
+                    ...basePayload,
+                    errorType: error instanceof Error ? error.name : "Error",
+                },
+            }, options.signal));
+        }
         const reportedError = appendHookReportsToError(error, executions);
         throw decorateToolResult(runner, options.invocation.workspaceId, reportedError);
     }
@@ -219,7 +222,8 @@ export class HookRunner {
     decorateResult(workspaceId, result) {
         return (this.resultDecorator?.(workspaceId, result) ?? result);
     }
-    async run(event, invocation) {
+    async run(event, invocation, signal) {
+        signal?.throwIfAborted();
         const projectRoot = event === "AfterWorktreeClose" && invocation.sourceRoot
             ? invocation.sourceRoot
             : invocation.workspaceRoot;
@@ -246,7 +250,8 @@ export class HookRunner {
                 }]
             : [];
         for (const [index, { scope, handler, invocation: matchedInvocation }] of handlers.entries()) {
-            const execution = await this.runHandler(event, handler, index, matchedInvocation, scope);
+            signal?.throwIfAborted();
+            const execution = await this.runHandler(event, handler, index, matchedInvocation, scope, signal);
             executions.push(execution);
             logEvent(this.logging, execution.status === "passed" ? "info" : "warn", "hook_call", {
                 hookEvent: event,
@@ -267,7 +272,7 @@ export class HookRunner {
         }
         return executions;
     }
-    async runHandler(event, handler, index, invocation, scope) {
+    async runHandler(event, handler, index, invocation, scope, signal) {
         const startedAt = performance.now();
         const name = handler.name ?? `${event} handler ${index + 1}`;
         const shell = resolveShellCommand(handler.command, process.platform, this.baseEnv);
@@ -282,6 +287,7 @@ export class HookRunner {
                 env,
                 timeoutMs: handler.timeoutSeconds * 1_000,
                 detached,
+                signal,
             });
             const durationMs = Math.round(performance.now() - startedAt);
             if (result.exitCode === 0 && !result.timedOut) {
@@ -311,6 +317,8 @@ export class HookRunner {
             };
         }
         catch (error) {
+            if (signal?.aborted)
+                throw error;
             return {
                 event,
                 name,
@@ -522,6 +530,7 @@ function hookEnvironment(baseEnv, event, invocation) {
     };
 }
 function executeHookCommand(input) {
+    input.signal?.throwIfAborted();
     return new Promise((resolve, reject) => {
         const child = spawn(input.executable, input.args, {
             cwd: input.cwd,
@@ -535,6 +544,18 @@ function executeHookCommand(input) {
         let stderr = "";
         let timedOut = false;
         let forceKillTimer;
+        let aborted = false;
+        const abort = () => {
+            if (aborted)
+                return;
+            aborted = true;
+            terminateProcessTree(child, "SIGTERM", input.detached);
+            forceKillTimer = setTimeout(() => {
+                terminateProcessTree(child, "SIGKILL", input.detached);
+            }, 500);
+            forceKillTimer.unref();
+        };
+        input.signal?.addEventListener("abort", abort, { once: true });
         child.stdout?.on("data", (chunk) => {
             stdout = appendCaptured(stdout, chunk);
         });
@@ -554,12 +575,20 @@ function executeHookCommand(input) {
             clearTimeout(timeout);
             if (forceKillTimer)
                 clearTimeout(forceKillTimer);
+            input.signal?.removeEventListener("abort", abort);
             reject(error);
         });
         child.once("close", (exitCode, signal) => {
             clearTimeout(timeout);
             if (forceKillTimer)
                 clearTimeout(forceKillTimer);
+            input.signal?.removeEventListener("abort", abort);
+            if (aborted) {
+                reject(input.signal?.reason instanceof Error
+                    ? input.signal.reason
+                    : Object.assign(new Error("Hook execution cancelled by Host."), { name: "AbortError" }));
+                return;
+            }
             resolve({ exitCode, signal, stdout, stderr, timedOut });
         });
     });

package/dist/mcp/server-instructions.js

@@ -30,7 +30,7 @@ export function buildToolDescriptions(config) {
         rename: `Rename or move one file or directory inside an open workspace or the OS temp directory without overwriting an existing destination. Source and destination must both remain inside the permitted file roots. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
         delete: `Delete one file or directory inside an open workspace or the OS temp directory. Non-empty directories require recursive=true. An allowed root itself cannot be deleted. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
         applyPatch: `Apply one Codex-style patch inside an open workspace or the OS temp directory. Supports adding, overwriting, updating, deleting, and moving files. Workspace paths must remain relative; absolute paths are accepted only inside the OS temp directory. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
-        shell: `Run or manage a shell process inside an open workspace.${shellSurface} Commands execute with the local user's authority; workspace filesystem containment does not make shell execution a sandbox. action=run (default) starts a command and waits up to 300 seconds; action=process uses its processId to poll, wait, write input, resize a PTY, or interrupt it. Completed background commands may also be reported later for the same workspaceId. Call ${toolNames.openWorkspace} first and pass workspaceId. Expose this capability only behind strong authentication.`,
+        shell: `Run or manage a shell process inside an open workspace.${shellSurface} Commands execute with the local user's authority; workspace containment does not make shell execution a sandbox. For action=run, yieldTimeMs is only the feedback wait (default 10000ms; 0 returns a processId immediately) and optional timeoutMs is the independent total execution limit. action=process polls/waits for incremental output, writes input, resizes a PTY, or interrupts by processId. Keep explicit waits below the Host request deadline; use 60000ms only when supported. Completed background results may be attached to a later result for the same workspaceId. Call ${toolNames.openWorkspace} first and pass workspaceId. Expose this capability only behind strong authentication.`,
         shellCommand: "Shell command to run with the local user's authority.",
     };
 }

package/dist/process-sessions.js

@@ -6,21 +6,33 @@ const DEFAULT_POLL_YIELD_MS = 5_000;
 const MAX_START_YIELD_MS = 300_000;
 const MAX_COMMAND_YIELD_MS = 300_000;
 const MAX_POLL_YIELD_MS = 300_000;
+const MAX_EXECUTION_TIMEOUT_MS = 24 * 60 * 60 * 1_000;
 const DEFAULT_MAX_OUTPUT_TOKENS = 10_000;
 const DEFAULT_BUFFER_CHARACTERS = 256_000;
 const DEFAULT_MAX_ACTIVE_PROCESSES = 64;
 const DEFAULT_MAX_COMPLETED_PROCESSES = 128;
 const COMPLETED_PROCESS_TTL_MS = 5 * 60 * 1_000;
+const COMPACT_COMPLETION_TTL_MS = 24 * 60 * 60 * 1_000;
+const COMPACT_COMPLETION_CHARACTERS = 16 * 1024;
+const COMPACT_COMPLETION_OUTPUT_TOKENS = COMPACT_COMPLETION_CHARACTERS / 4;
 const DEFAULT_COLUMNS = 80;
 const DEFAULT_ROWS = 24;
 function boundedInteger(value, fallback, maximum) {
     if (value === undefined)
-        return fallback;
+        return Math.min(fallback, maximum);
     if (!Number.isFinite(value) || value < 0) {
         throw new Error("Duration and output limits must be non-negative.");
     }
     return Math.min(Math.floor(value), maximum);
 }
+function optionalExecutionTimeout(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isInteger(value) || value < 1 || value > MAX_EXECUTION_TIMEOUT_MS) {
+        throw new Error(`Execution timeout must be an integer between 1 and ${MAX_EXECUTION_TIMEOUT_MS}ms.`);
+    }
+    return value;
+}
 function terminalSize(value, fallback) {
     if (value === undefined)
         return fallback;
@@ -215,9 +227,11 @@ export class ProcessManager {
         this.monotonicNow = options.monotonicNow ?? (() => performance.now());
     }
     async start(input) {
+        input.signal?.throwIfAborted();
         if (this.stats().running >= this.maxActiveProcesses) {
             throw new Error(`Active process limit reached (${this.maxActiveProcesses}). Poll, interrupt, or wait for an existing process before starting another.`);
         }
+        const executionTimeoutMs = optionalExecutionTimeout(input.timeoutMs);
         const processEntry = this.createProcess(input);
         this.processes.set(processEntry.id, processEntry);
         try {
@@ -230,8 +244,19 @@ export class ProcessManager {
             this.processes.delete(processEntry.id);
             throw error;
         }
+        this.armExecutionTimeout(processEntry, executionTimeoutMs);
         const yieldTimeMs = boundedInteger(input.yieldTimeMs, DEFAULT_EXEC_YIELD_MS, this.maxStartYieldMs);
-        await this.waitForExit(processEntry, yieldTimeMs);
+        try {
+            await this.waitForExit(processEntry, yieldTimeMs, input.signal);
+            input.signal?.throwIfAborted();
+        }
+        catch (error) {
+            if (input.signal?.aborted) {
+                processEntry.discardOnFinish = true;
+                this.stopProcess(processEntry, "SIGTERM");
+            }
+            throw error;
+        }
         if (processEntry.running)
             processEntry.background = true;
         const snapshot = this.consume(processEntry, input.maxOutputTokens);
@@ -263,7 +288,7 @@ export class ProcessManager {
             const fallback = interactionRequested ? DEFAULT_INTERACTIVE_YIELD_MS : DEFAULT_POLL_YIELD_MS;
             const maximum = interactionRequested ? MAX_COMMAND_YIELD_MS : MAX_POLL_YIELD_MS;
             const yieldTimeMs = boundedInteger(input.yieldTimeMs, fallback, maximum);
-            await this.waitForExit(processEntry, yieldTimeMs);
+            await this.waitForExit(processEntry, yieldTimeMs, input.signal);
         }
         const snapshot = this.consume(processEntry, input.maxOutputTokens);
         if (!processEntry.running)
@@ -271,7 +296,9 @@ export class ProcessManager {
         return snapshot;
     }
     activeWorkspaceIds() {
-        return new Set([...this.processes.values()].map((processEntry) => processEntry.workspaceId));
+        return new Set([...this.processes.values()]
+            .filter((processEntry) => processEntry.running)
+            .map((processEntry) => processEntry.workspaceId));
     }
     stats() {
         let running = 0;
@@ -311,10 +338,17 @@ export class ProcessManager {
         if (processEntry.running)
             processEntry.process?.kill("SIGTERM");
     }
+    discardUndelivered(workspaceId, processId) {
+        const processEntry = this.getOwnedProcess(workspaceId, processId);
+        processEntry.discardOnFinish = true;
+        if (processEntry.running)
+            this.stopProcess(processEntry, "SIGTERM");
+        else
+            this.removeProcess(processEntry.id);
+    }
     shutdown() {
         for (const processEntry of this.processes.values()) {
-            if (processEntry.cleanupTimer)
-                clearTimeout(processEntry.cleanupTimer);
+            this.clearProcessTimers(processEntry);
             if (processEntry.running)
                 processEntry.process?.kill("SIGTERM");
         }
@@ -322,19 +356,32 @@ export class ProcessManager {
         this.completedByWorkspace.clear();
         this.completedProcessIds.length = 0;
     }
-    async waitForExit(processEntry, yieldTimeMs) {
+    async waitForExit(processEntry, yieldTimeMs, signal) {
+        signal?.throwIfAborted();
         let timer;
+        let abortListener;
         try {
-            await Promise.race([
+            const waits = [
                 processEntry.exitPromise,
                 new Promise((resolve) => {
                     timer = setTimeout(resolve, yieldTimeMs);
                 }),
-            ]);
+            ];
+            if (signal) {
+                waits.push(new Promise((_resolve, reject) => {
+                    abortListener = () => reject(signal.reason instanceof Error
+                        ? signal.reason
+                        : Object.assign(new Error("Process wait cancelled by Host."), { name: "AbortError" }));
+                    signal.addEventListener("abort", abortListener, { once: true });
+                }));
+            }
+            await Promise.race(waits);
         }
         finally {
             if (timer)
                 clearTimeout(timer);
+            if (signal && abortListener)
+                signal.removeEventListener("abort", abortListener);
         }
     }
     createProcess(input) {
@@ -351,7 +398,10 @@ export class ProcessManager {
             rows: terminalSize(input.rows, DEFAULT_ROWS),
             buffer: new HeadTailBuffer(this.maxBufferCharacters),
             running: true,
+            timedOut: false,
+            outputWasTruncated: false,
             background: false,
+            discardOnFinish: false,
             exitPromise,
             resolveExit,
         };
@@ -423,9 +473,18 @@ export class ProcessManager {
         processEntry.running = false;
         processEntry.exitCode = exitCode;
         processEntry.signal = signal;
+        processEntry.finishedAtMonotonic = this.monotonicNow();
         processEntry.process = undefined;
+        if (processEntry.executionTimeoutTimer)
+            clearTimeout(processEntry.executionTimeoutTimer);
+        if (processEntry.forceKillTimer)
+            clearTimeout(processEntry.forceKillTimer);
         processEntry.resolveExit();
-        processEntry.cleanupTimer = setTimeout(() => this.removeProcess(processEntry.id), this.completedProcessTtlMs);
+        if (processEntry.discardOnFinish) {
+            this.removeProcess(processEntry.id);
+            return;
+        }
+        processEntry.cleanupTimer = setTimeout(() => this.compactCompletedProcess(processEntry), this.completedProcessTtlMs);
         processEntry.cleanupTimer.unref();
         if (processEntry.background) {
             const completed = this.completedByWorkspace.get(processEntry.workspaceId) ?? [];
@@ -442,6 +501,17 @@ export class ProcessManager {
             }
         }
     }
+    compactCompletedProcess(processEntry) {
+        if (processEntry.running || !this.processes.has(processEntry.id))
+            return;
+        const compacted = this.consume(processEntry, COMPACT_COMPLETION_OUTPUT_TOKENS);
+        processEntry.buffer = new HeadTailBuffer(COMPACT_COMPLETION_CHARACTERS);
+        processEntry.buffer.append(compacted.output);
+        processEntry.outputWasTruncated = compacted.outputTruncated;
+        const remainingMs = Math.max(1, COMPACT_COMPLETION_TTL_MS - this.completedProcessTtlMs);
+        processEntry.cleanupTimer = setTimeout(() => this.removeProcess(processEntry.id), remainingMs);
+        processEntry.cleanupTimer.unref();
+    }
     append(processEntry, output) {
         processEntry.buffer.append(output);
     }
@@ -449,18 +519,53 @@ export class ProcessManager {
         const limit = boundedInteger(maxOutputTokens, DEFAULT_MAX_OUTPUT_TOKENS, 100_000);
         const maxCharacters = Math.max(256, limit * 4);
         const buffered = processEntry.buffer.drain(maxCharacters);
+        if (buffered.truncated)
+            processEntry.outputWasTruncated = true;
         const processId = processEntry.running ? processEntry.id : undefined;
+        const endedAt = processEntry.finishedAtMonotonic ?? this.monotonicNow();
         return {
             processId,
             sessionId: processId,
             output: buffered.output,
-            outputTruncated: buffered.truncated,
+            outputTruncated: processEntry.outputWasTruncated,
             running: processEntry.running,
             exitCode: processEntry.exitCode,
             signal: processEntry.signal,
-            wallTimeMs: Math.max(0, Math.round(this.monotonicNow() - processEntry.startedAtMonotonic)),
+            timedOut: processEntry.timedOut,
+            wallTimeMs: Math.max(0, Math.round(endedAt - processEntry.startedAtMonotonic)),
         };
     }
+    armExecutionTimeout(processEntry, timeoutMs) {
+        if (timeoutMs === undefined)
+            return;
+        processEntry.executionTimeoutTimer = setTimeout(() => {
+            if (!processEntry.running)
+                return;
+            processEntry.timedOut = true;
+            this.stopProcess(processEntry, "SIGTERM");
+        }, timeoutMs);
+        processEntry.executionTimeoutTimer.unref();
+    }
+    stopProcess(processEntry, signal) {
+        if (!processEntry.running)
+            return;
+        processEntry.process?.kill(signal);
+        if (processEntry.forceKillTimer)
+            clearTimeout(processEntry.forceKillTimer);
+        processEntry.forceKillTimer = setTimeout(() => {
+            if (processEntry.running)
+                processEntry.process?.kill("SIGKILL");
+        }, 500);
+        processEntry.forceKillTimer.unref();
+    }
+    clearProcessTimers(processEntry) {
+        if (processEntry.cleanupTimer)
+            clearTimeout(processEntry.cleanupTimer);
+        if (processEntry.executionTimeoutTimer)
+            clearTimeout(processEntry.executionTimeoutTimer);
+        if (processEntry.forceKillTimer)
+            clearTimeout(processEntry.forceKillTimer);
+    }
     getOwnedProcess(workspaceId, processId) {
         const processEntry = this.processes.get(processId);
         if (!processEntry)
@@ -472,8 +577,8 @@ export class ProcessManager {
     }
     removeProcess(processId) {
         const processEntry = this.processes.get(processId);
-        if (processEntry?.cleanupTimer)
-            clearTimeout(processEntry.cleanupTimer);
+        if (processEntry)
+            this.clearProcessTimers(processEntry);
         this.processes.delete(processId);
         const completedIndex = this.completedProcessIds.indexOf(processId);
         if (completedIndex >= 0)