Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

test(mcp-host): pin the shell cleanup bounds with a group that never disappears

Alfredo Lopez472ca6bfd763
diff --git a/docs/operations/gfs-large-file-host-downloads.md b/docs/operations/gfs-large-file-host-downloads.md
index 8cad1fb0d..33bba65cd 100644
--- a/docs/operations/gfs-large-file-host-downloads.md
+++ b/docs/operations/gfs-large-file-host-downloads.md
@@ -167,7 +167,7 @@ Partial reads are not possible, because publication is an atomic `rename` of
Unix directory modes and random directory names do not provide cross-caller OS isolation when a Host shares one UID. Approved arbitrary shell access remains a documented Stage 1 residual; stronger executor isolation is separate Stage 2 work.
-Shell cleanup signals and waits for the detached process group before the tool result is returned, or reports `process_group_termination_failed` when its termination cannot be confirmed. A process that moved outside that group (for example through `setsid` or a detached spawn) can keep stdout/stderr open after the group is gone, so the Host bounds settlement without waiting for those pipes to close. After a timeout, cancellation or output overflow, termination has 5000 ms of SIGTERM grace and the call settles at the 6000 ms cleanup budget at the latest. When the command exits on its own, the Host checks every 1000 ms whether the process group is gone and settles once it is. In both cases the Host stops output capture, the result starts with `[stdio_held_by_detached_process: <reason>; ...]` and is an error, and a `shell_stdio_held_by_detached_process` warning is logged. The escaped process is not signalled and may keep running; this bounds the call, it does not contain the process. Redirect background output to a file or `/dev/null`. Operating systems may reuse a process-group identifier after the original leader has been reaped; Stage 1 narrows that window by signaling immediately on leader close, but stronger executor identity is required to eliminate it.
+Shell cleanup signals and waits for the detached process group before the tool result is returned, or reports `process_group_termination_failed` when its termination cannot be confirmed. A process that moved outside that group (for example through `setsid` or a detached spawn) can keep stdout/stderr open after the group is gone, so the Host bounds settlement without waiting for those pipes to close. After a timeout, cancellation or output overflow, termination has 5000 ms of SIGTERM grace and the call settles at the 6000 ms cleanup budget at the latest. When the command exits on its own, the Host checks every 1000 ms whether the process group is gone and settles once it is. If the group never disappears, the execution timeout still applies, followed by the same 6000 ms cleanup budget. In both cases the Host stops output capture, the result starts with `[stdio_held_by_detached_process: <reason>; ...]` and is an error, and a `shell_stdio_held_by_detached_process` warning is logged. The escaped process is not signalled and may keep running; this bounds the call, it does not contain the process. Redirect background output to a file or `/dev/null`. Operating systems may reuse a process-group identifier after the original leader has been reaped; Stage 1 narrows that window by signaling immediately on leader close, but stronger executor identity is required to eliminate it.
Generic workspace tools reject direct and symlink-resolved access to
`.gfs-downloads` and the complete `.gfs-download-store` accounting namespace
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 054066a5c..d9d3505c7 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.517",
+ "version": "0.1.518",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.517",
+ "version": "0.1.518",
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
"@anthropic-ai/sdk": "^0.32.0",
diff --git a/mcp-host/package.json b/mcp-host/package.json
index b04e555e1..79016774d 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.517",
+ "version": "0.1.518",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/core/tools/__tests__/shell.detachedStdio.test.ts b/mcp-host/src/core/tools/__tests__/shell.detachedStdio.test.ts
index b184df796..9a6365b0f 100644
--- a/mcp-host/src/core/tools/__tests__/shell.detachedStdio.test.ts
+++ b/mcp-host/src/core/tools/__tests__/shell.detachedStdio.test.ts
@@ -17,6 +17,18 @@ vi.mock('child_process', async importOriginal => {
return { ...actual, spawn: vi.fn(actual.spawn) }
})
+// The fake clock does not reach node:timers/promises, so the group-termination
+// poll sleeps through the global setTimeout: real under real timers, fake under
+// a fake clock.
+vi.mock('node:timers/promises', async importOriginal => {
+ const actual = await importOriginal<typeof import('node:timers/promises')>()
+ return {
+ ...actual,
+ setTimeout: (delayMs: number) =>
+ new Promise<void>(resolve => globalThis.setTimeout(resolve, delayMs)),
+ }
+})
+
/** Mirrors ShellTool.MAX_RESULT_BYTES (1 MB minus 2048 bytes of headroom). */
const MAX_RESULT_BYTES = 1024 * 1024 - 2048
/** Delay before a timeout or cancellation is triggered on a real process. */
@@ -539,4 +551,118 @@ describe('ShellTool single finalizer races (#1028 P1, hermetic child)', () => {
{ component: 'ShellTool', errorCode: 'EINVAL' },
])
})
+
+ /** Fakes performance.now as well, so the termination deadline follows the fake clock. */
+ const useFakeClock = () =>
+ vi.useFakeTimers({
+ toFake: [
+ 'setTimeout',
+ 'clearTimeout',
+ 'setInterval',
+ 'clearInterval',
+ 'setImmediate',
+ 'clearImmediate',
+ 'Date',
+ 'performance',
+ ],
+ })
+
+ /** Intercepts process.kill; the group probe never confirms absence. */
+ function groupThatNeverDisappears() {
+ const signals: Array<{ pid: number; signal: unknown; at: number }> = []
+ vi.spyOn(process, 'kill').mockImplementation((pid: number, signal?: string | number) => {
+ signals.push({ pid, signal, at: performance.now() })
+ return true
+ })
+ return signals
+ }
+
+ const TIMEOUT_FOOTER = (timeoutMs: number) =>
+ `[Command killed after ${timeoutMs}ms timeout — partial output above]`
+
+ for (const closeAfterSigtermMs of [100, SHELL_TIMEOUT_CLEANUP_MS - 100]) {
+ it(`R1-H1: a close delivered ${closeAfterSigtermMs}ms after SIGTERM with a group probe that never confirms absence settles within the cleanup budget and reports process_group_termination_failed`, async () => {
+ useFakeClock()
+ const child = hermeticChild()
+ vi.mocked(spawn).mockImplementationOnce(() => child as never)
+ const signals = groupThatNeverDisappears()
+ const timeoutMs = 1_000
+ let settledAt: number | undefined
+ const execution = new ShellTool(workspacePath, timeoutMs, []).execute({
+ command: 'hermetic command',
+ })
+ void execution.then(() => {
+ settledAt = performance.now()
+ })
+ child.stdout.emit('data', Buffer.from('partial'))
+ await vi.advanceTimersByTimeAsync(timeoutMs)
+ const sigterm = signals.find(entry => entry.signal === 'SIGTERM')
+ expect(sigterm).toMatchObject({ pid: -FAKE_PID })
+ const terminationStartedAt = sigterm!.at
+
+ await vi.advanceTimersByTimeAsync(closeAfterSigtermMs)
+ expect(settledAt).toBeUndefined()
+ child.signalCode = 'SIGTERM'
+ child.emit('close', null)
+ await vi.advanceTimersByTimeAsync(SHELL_TIMEOUT_CLEANUP_MS)
+
+ expect(settledAt).toBeDefined()
+ expect(settledAt! - terminationStartedAt).toBeLessThanOrEqual(SHELL_TIMEOUT_CLEANUP_MS)
+ const result = await execution
+ expect(result.is_error).toBe(true)
+ expect(result.content).toBe(
+ `stdout:\npartial\n\n${TIMEOUT_FOOTER(timeoutMs)}\n\n[process_group_termination_failed]`
+ )
+ // Witness: close verification ran and probed the group after close.
+ const probesAfterClose = signals.filter(
+ entry => entry.signal === 0 && entry.at >= terminationStartedAt + closeAfterSigtermMs
+ )
+ expect(probesAfterClose.length).toBeGreaterThan(0)
+ expect(vi.getTimerCount()).toBe(0)
+ })
+ }
+
+ it('R1-H1: a natural exit whose group never disappears and whose stdio never closes is bounded by the execution timeout plus the cleanup budget', async () => {
+ useFakeClock()
+ const child = hermeticChild()
+ vi.mocked(spawn).mockImplementationOnce(() => child as never)
+ const signals = groupThatNeverDisappears()
+ const timeoutMs = 3 * SHELL_STDIO_DRAIN_MS + SHELL_STDIO_DRAIN_MS / 2
+ const startedAt = performance.now()
+ let settledAt: number | undefined
+ const execution = new ShellTool(workspacePath, timeoutMs, []).execute({
+ command: 'hermetic command',
+ })
+ void execution.then(() => {
+ settledAt = performance.now()
+ })
+ child.stdout.emit('data', Buffer.from('natural output'))
+ child.exitCode = 0
+ child.emit('exit', 0, null)
+
+ await vi.advanceTimersByTimeAsync(timeoutMs)
+ // Witness: the drain poll probed the live group before the execution timeout.
+ const drainProbes = signals.filter(
+ entry => entry.signal === 0 && entry.at < startedAt + timeoutMs
+ )
+ expect(drainProbes).toHaveLength(3)
+ expect(signals.filter(entry => entry.signal === 'SIGTERM')).toEqual([
+ { pid: -FAKE_PID, signal: 'SIGTERM', at: startedAt + timeoutMs },
+ ])
+
+ await vi.advanceTimersByTimeAsync(SHELL_TIMEOUT_CLEANUP_MS - 1)
+ expect(settledAt).toBeUndefined()
+ await vi.advanceTimersByTimeAsync(1)
+
+ expect(settledAt).toBe(startedAt + timeoutMs + SHELL_TIMEOUT_CLEANUP_MS)
+ const result = await execution
+ expect(result.is_error).toBe(true)
+ expect(result.content).toBe(
+ `${notice('timeout')}stdout:\nnatural output\n\n${TIMEOUT_FOOTER(timeoutMs)}\n\n[process_group_termination_failed]`
+ )
+ expect(heldWarnings()).toEqual([
+ expect.objectContaining({ reason: 'timeout', processGroupTerminated: false }),
+ ])
+ expect(vi.getTimerCount()).toBe(0)
+ })
})
diff --git a/scripts/ci/pinned-vitest-cases/mcp-host.json b/scripts/ci/pinned-vitest-cases/mcp-host.json
index 6915cd845..56f72873c 100644
--- a/scripts/ci/pinned-vitest-cases/mcp-host.json
+++ b/scripts/ci/pinned-vitest-cases/mcp-host.json
@@ -127,6 +127,14 @@
"suite": "shell.detachedStdio.test.ts",
"fullName": "ShellTool with stdio held by a process outside its group (#1028 P1) P1-g: an asynchronous start failure reports only the error code and publishes one result"
},
+ {
+ "suite": "shell.detachedStdio.test.ts",
+ "fullName": "ShellTool single finalizer races (#1028 P1, hermetic child) R1-H1: a close delivered 5900ms after SIGTERM with a group probe that never confirms absence settles within the cleanup budget and reports process_group_termination_failed"
+ },
+ {
+ "suite": "shell.detachedStdio.test.ts",
+ "fullName": "ShellTool single finalizer races (#1028 P1, hermetic child) R1-H1: a natural exit whose group never disappears and whose stdio never closes is bounded by the execution timeout plus the cleanup budget"
+ },
{
"suite": "config.toolProgressInterval.test.ts",
"fullName": "CLERUM_TOOL_PROGRESS_INTERVAL_MS (#1028 P2) P2-b: malformed and sub-second values stop startup with the exact message and do not echo the value"