Centralize agent task cleanup into one signal-safe coordinator

The executor previously carried four independent cleanup sites for the
private runtime source root and the runner workspace seed snapshot:
mid-run awaits, an inline catch-path duplicate, a partial exit hook, and
signal handlers that cleaned only one of the two resources and exited
128 for every signal.

Replace them with a single idempotent module-level coordinator that
claims both roots exactly once and chains repeat invocations onto the
in-flight cleanup instead of racing it. The top-level normal and
failure paths route through one finally; SIGINT/SIGTERM/SIGHUP await
the same coordinator before exiting with the conventional 128+signum
code; the process exit hook keeps a bounded synchronous best-effort
fallback for abrupt exits. Error reporting and redaction are
preserved, and stderr messages are now redacted while the private root
is still known.

A deterministic interruption test starts the executor in a child
process, pauses it immediately after seed snapshot creation through a
narrowly scoped NODE_ENV=test marker-file hook that is inert in
production, delivers each signal, and asserts the temp seed snapshot
directory is removed, the conventional exit code is set, and no runner
workspace content survives. A normal run in the same harness proves
routine cleanup still passes.

Author: chubes4

.github/scripts/run-agent-task/execute-native-agent-task.mjs

@@ -20,6 +20,41 @@ const secretValues = ["OPENAI_API_KEY", "MODEL_PROVIDER_SECRET_1", "MODEL_PROVID
 let privateRuntimeSourceRoot = ""
 let privateRuntimeSourceRootForSanitization = ""
 let runnerWorkspaceSeedSnapshot
+
+const SIGNAL_EXIT_CODES = { SIGINT: 130, SIGTERM: 143, SIGHUP: 129 }
+let materializedSourceCleanup
+function claimMaterializedSourcePaths() {
+  const paths = []
+  if (runnerWorkspaceSeedSnapshot) {
+    paths.push(runnerWorkspaceSeedSnapshot.source)
+    runnerWorkspaceSeedSnapshot = undefined
+  }
+  if (privateRuntimeSourceRoot) {
+    paths.push(privateRuntimeSourceRoot)
+    privateRuntimeSourceRoot = ""
+  }
+  return paths
+}
+// Single idempotent cleanup coordinator for the private runtime source
+// materialization root and the runner workspace seed snapshot. Every
+// completion path (normal, failure, signal) awaits this coordinator; repeat
+// invocations chain onto the in-flight cleanup instead of racing it.
+function cleanupMaterializedSources() {
+  materializedSourceCleanup = (materializedSourceCleanup ?? Promise.resolve())
+    .then(() => Promise.all(claimMaterializedSourcePaths().map((path) => rm(path, { recursive: true, force: true }))))
+  return materializedSourceCleanup
+}
+process.once("exit", () => {
+  // Bounded synchronous best-effort fallback for abrupt exits; on every
+  // awaited path the coordinator has already claimed these roots.
+  for (const path of claimMaterializedSourcePaths()) {
+    try { rmSync(path, { recursive: true, force: true, maxRetries: 0 }) } catch { /* best effort */ }
+  }
+})
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+  process.once(signal, () => { cleanupMaterializedSources().finally(() => process.exit(SIGNAL_EXIT_CODES[signal])) })
+}
+
 function redact(value) {
   if (typeof value === "string") return secretValues.reduce((output, secret) => output.split(secret).join("[REDACTED]"), value)
   if (Array.isArray(value)) return value.map(redact)
@@ -220,6 +255,17 @@ async function testRuntimeFixtures(externalPackageSource) {
   return fixtures
 }
 
+// Test-only interruption hook: inert in production (requires NODE_ENV=test and
+// an explicit marker path). Publishes the seed snapshot location, then holds a
+// bounded window so a harness can deliver a termination signal.
+async function testPauseAfterSeedSnapshot(seedSnapshot) {
+  if (process.env.NODE_ENV !== "test") return
+  const markerPath = string(process.env.WP_CODEBOX_TEST_SEED_SNAPSHOT_PAUSE_FILE)
+  if (!markerPath) return
+  await writeFile(markerPath, `${JSON.stringify({ schema: "wp-codebox/test-seed-snapshot-pause/v1", seed_snapshot_source: seedSnapshot?.source ?? "" })}\n`)
+  await new Promise((resolvePause) => setTimeout(resolvePause, 120_000))
+}
+
 function runtimeSourceFixtureRoot(value) {
   const paths = []
   const collect = (entry) => {
@@ -307,24 +353,6 @@ const runtimeInputPath = join(workspace, ".codebox", "native-agent-task-input.js
 const resultPath = join(workspace, ".codebox", "agent-task-workflow-result.json")
 const controlledCodeboxPath = resolve(requestPath, "..")
  const nativeResultPath = join(controlledCodeboxPath, "native-agent-task-result.json")
-let cleaningPrivateRuntimeSources = false
- async function cleanupPrivateRuntimeSources() {
-  if (cleaningPrivateRuntimeSources || !privateRuntimeSourceRoot) return
-  cleaningPrivateRuntimeSources = true
-  const root = privateRuntimeSourceRoot
-  privateRuntimeSourceRoot = ""
-  await rm(root, { recursive: true, force: true })
- }
- async function cleanupRunnerWorkspaceSeedSnapshot() {
-   if (!runnerWorkspaceSeedSnapshot) return
-   const source = runnerWorkspaceSeedSnapshot.source
-   runnerWorkspaceSeedSnapshot = undefined
-   await rm(source, { recursive: true, force: true })
- }
-process.once("exit", () => { if (privateRuntimeSourceRoot) rmSync(privateRuntimeSourceRoot, { recursive: true, force: true }) })
-for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
-  process.once(signal, () => { cleanupPrivateRuntimeSources().finally(() => process.exit(128)) })
-}
   const runnerWorkspaceTools = [
    "workspace_read", "workspace_ls", "workspace_grep", "workspace_write", "workspace_edit", "workspace_apply_patch",
    "workspace_show", "workspace_git_status", "workspace_git_diff",
@@ -346,6 +374,7 @@ if (accessError) {
  }
 
  if (request.runner_workspace?.enabled) runnerWorkspaceSeedSnapshot = await createRunnerWorkspaceSeedSnapshot(workspace)
+ await testPauseAfterSeedSnapshot(runnerWorkspaceSeedSnapshot)
 
 const testFixtures = await testRuntimeFixtures(externalPackageSource)
 const skipMaterialization = process.env.NODE_ENV === "test" && (process.env.WP_CODEBOX_TEST_SKIP_MATERIALIZATION === "true" || Boolean(testFixtures.materializedPackage || testFixtures.runtimeSourceInputs))
@@ -430,7 +459,6 @@ let execution = { code: 0, stdout: "", stderr: "", stdout_truncated: false, stde
  if (request.run_agent && !request.dry_run) {
    execution = await command("node", [codeboxCliPath, "agent-task-run", "--input-file", executionInputPath, "--result-file", nativeResultPath], workspace, agentEnvironment())
  }
- await cleanupRunnerWorkspaceSeedSnapshot()
 
 // Public package bytes are embedded in the runtime recipe and consumed only by
 // the Playground bootstrap before the agent's tools are resolved.
@@ -455,7 +483,6 @@ if (execution.code === 0 && runtimeResult.success === true && request.runner_wor
     downstreamFailure = { stage: "apply", message: bounded(error instanceof Error ? error.message : String(error), MAX_OUTPUT_CHARS) }
   }
 }
-await cleanupPrivateRuntimeSources()
 runtimeResult = sanitizeRuntimeSourceValue(runtimeResult, runtimeSourceOutputRoots)
 privateRuntimeSourceRootForSanitization = runtimeSourceOutputRoots
 assertNoRuntimeSourcePaths(runtimeResult, privateRuntimeSourceRootForSanitization)
@@ -565,20 +592,9 @@ if (!success) process.exitCode = 1
 try {
   await executeNativeAgentTask()
 } catch (error) {
-  try {
-    await writeNormalizedFailure(error)
-  } finally {
-    if (runnerWorkspaceSeedSnapshot) {
-      const source = runnerWorkspaceSeedSnapshot.source
-      runnerWorkspaceSeedSnapshot = undefined
-      await rm(source, { recursive: true, force: true })
-    }
-    if (privateRuntimeSourceRoot) {
-      const root = privateRuntimeSourceRoot
-      privateRuntimeSourceRoot = ""
-      await rm(root, { recursive: true, force: true })
-    }
-  }
+  await writeNormalizedFailure(error)
   console.error(bounded(error instanceof Error ? error.message : String(error), MAX_OUTPUT_CHARS))
   process.exitCode = 1
+} finally {
+  await cleanupMaterializedSources()
 }

.github/workflows/agent-task-contracts.yml

@@ -18,6 +18,7 @@ on:
       - "tests/runtime-sources-materialization.test.ts"
       - "tests/runtime-sources-playground-integration.test.ts"
       - "tests/execute-native-agent-task-playground-e2e.test.ts"
+      - "tests/execute-native-agent-task-interruption.test.mjs"
       - "tests/redaction.test.ts"
       - "tests/production-boundary-enforcement.test.ts"
       - "tests/runtime-tool-policy.test.ts"
@@ -38,6 +39,7 @@ on:
       - "tests/runtime-sources-materialization.test.ts"
       - "tests/runtime-sources-playground-integration.test.ts"
       - "tests/execute-native-agent-task-playground-e2e.test.ts"
+      - "tests/execute-native-agent-task-interruption.test.mjs"
       - "tests/redaction.test.ts"
       - "tests/production-boundary-enforcement.test.ts"
       - "tests/runtime-tool-policy.test.ts"
@@ -58,6 +60,7 @@ jobs:
       - run: npm run test:agent-task-contracts
       - run: npm run test:runtime-sources-playground-integration
       - run: npm run test:native-agent-task-playground-e2e
+      - run: npm run test:native-agent-task-interruption
       - run: npm run test:redaction
       - run: npm run test:production-boundary-enforcement
       - run: npm run test:runtime-tool-policy

package.json

@@ -130,6 +130,7 @@
     "test:runner-workspace-apply": "tsx tests/runner-workspace-apply.test.ts",
     "test:runner-workspace-publisher": "node tests/runner-workspace-publisher.test.mjs",
     "test:native-agent-task-lifecycle": "node tests/execute-native-agent-task-lifecycle.test.mjs",
+    "test:native-agent-task-interruption": "node tests/execute-native-agent-task-interruption.test.mjs",
     "test:native-agent-task-playground-e2e": "tsx tests/execute-native-agent-task-playground-e2e.test.ts",
     "test:bench-command-step-behavior": "tsx tests/bench-command-step-behavior.test.ts",
     "test:generic-primitives": "npm run test:artifact-path-primitives && npm run test:browser-callback-materialization-contracts && npm run test:source-package-compiler-primitives && npm run test:bench-command-step-behavior && npm run test:generic-ability-runtime-run",

tests/execute-native-agent-task-interruption.test.mjs

@@ -0,0 +1,111 @@
+import assert from "node:assert/strict"
+import { existsSync } from "node:fs"
+import { mkdtemp, mkdir, readdir, readFile, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join, resolve } from "node:path"
+import { spawn } from "node:child_process"
+import { setTimeout as delay } from "node:timers/promises"
+
+const root = resolve(".")
+const executor = join(root, ".github/scripts/run-agent-task/execute-native-agent-task.mjs")
+const SIGNAL_EXIT_CODES = { SIGINT: 130, SIGTERM: 143, SIGHUP: 129 }
+
+async function prepare() {
+  const temp = await mkdtemp(join(tmpdir(), "wp-codebox-native-interruption-"))
+  // A dedicated TMPDIR makes seed-snapshot residue deterministic to observe.
+  const seedTemp = join(temp, "seed-tmp")
+  const workspace = join(temp, "workspace")
+  await mkdir(seedTemp, { recursive: true })
+  await mkdir(join(workspace, ".codebox"), { recursive: true })
+  await writeFile(join(workspace, "README.md"), "before\n")
+  const request = {
+    schema: "wp-codebox/agent-task-workflow-request/v1",
+    model: { provider: "openai", name: "gpt-5" },
+    external_package_source: {
+      repository: "owner/agents",
+      revision: "a".repeat(40),
+      path: "agent.agent.json",
+      digest: `sha256-bytes-v1:${"b".repeat(64)}`,
+    },
+    runtime_sources: [],
+    workload: { id: "interruption-1", label: "Interruption" },
+    target_repo: "owner/repo",
+    prompt: "Interruption lifecycle fixture.",
+    writable_paths: "README.md",
+    runner_workspace: { enabled: true, repo: "owner/repo", base: "main", branch_prefix: "wp-codebox/agent-task/" },
+    verification_commands: [],
+    drift_checks: [],
+    success: { requires_pr: false },
+    access: { caller_repo: "owner/repo", allowed_repos: ["owner/repo"], access_token_repos: ["owner/repo"] },
+    limits: { max_turns: 1, time_budget_ms: 1000 },
+    artifacts: { expected: [], declarations: [] },
+    outputs: { projections: {} },
+    callback_data: {},
+    run_agent: true,
+    dry_run: true,
+  }
+  await writeFile(join(workspace, ".codebox", "agent-task-request.json"), JSON.stringify(request))
+  return { temp, seedTemp, workspace }
+}
+
+function spawnExecutor({ seedTemp, workspace }, extraEnv = {}) {
+  const child = spawn(process.execPath, [executor], {
+    cwd: workspace,
+    env: {
+      ...process.env,
+      NODE_ENV: "test",
+      TMPDIR: seedTemp,
+      AGENT_TASK_REQUEST_PATH: join(workspace, ".codebox", "agent-task-request.json"),
+      AGENT_TASK_WORKSPACE: workspace,
+      WP_CODEBOX_WORKFLOW_ROOT: root,
+      GITHUB_TOKEN: "token",
+      EXTERNAL_PACKAGE_SOURCE_POLICY: JSON.stringify({ version: 1, repositories: { "owner/agents": ["agent.agent.json"] } }),
+      ...extraEnv,
+    },
+  })
+  let stderr = ""
+  child.stderr.on("data", (chunk) => { stderr += chunk })
+  const closed = new Promise((done) => { child.on("close", (code, signal) => done({ code, signal, stderr })) })
+  return { child, closed }
+}
+
+async function seedSnapshotEntries(seedTemp) {
+  return (await readdir(seedTemp)).filter((entry) => entry.startsWith("wp-codebox-runner-workspace-seed-"))
+}
+
+for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) {
+  const fixture = await prepare()
+  const pauseFile = join(fixture.temp, "pause.json")
+  const { child, closed } = spawnExecutor(fixture, { WP_CODEBOX_TEST_SEED_SNAPSHOT_PAUSE_FILE: pauseFile })
+
+  const deadline = Date.now() + 30_000
+  while (!existsSync(pauseFile)) {
+    assert.ok(Date.now() < deadline, `executor did not reach the seed snapshot pause hook for ${signal}`)
+    await delay(50)
+  }
+  const marker = JSON.parse(await readFile(pauseFile, "utf8"))
+  assert.equal(marker.schema, "wp-codebox/test-seed-snapshot-pause/v1")
+  assert.ok(marker.seed_snapshot_source.startsWith(fixture.seedTemp), "seed snapshot is created under the controlled TMPDIR")
+  assert.ok(existsSync(marker.seed_snapshot_source), "seed snapshot exists while the executor is paused")
+
+  child.kill(signal)
+  const exit = await closed
+  assert.equal(exit.signal, null, `the executor handles ${signal} itself instead of dying to the default signal action\n${exit.stderr}`)
+  assert.equal(exit.code, SIGNAL_EXIT_CODES[signal], `conventional exit code for ${signal}\n${exit.stderr}`)
+  assert.equal(existsSync(marker.seed_snapshot_source), false, `the temp seed snapshot directory is removed on ${signal}`)
+  assert.deepEqual(await seedSnapshotEntries(fixture.seedTemp), [], `no runner workspace seed content survives ${signal}`)
+  assert.equal(await readFile(join(fixture.workspace, "README.md"), "utf8"), "before\n", "the host workspace is untouched")
+  assert.deepEqual((await readdir(join(fixture.workspace, ".codebox"))).sort(), ["agent-task-artifacts", "agent-task-request.json"], "no runner workspace materials survive in the workspace")
+  assert.deepEqual(await readdir(join(fixture.workspace, ".codebox", "agent-task-artifacts")), [], "no artifacts are staged before interruption")
+}
+
+// Normal completion continues to clean up through the same coordinator.
+const fixture = await prepare()
+const { closed } = spawnExecutor(fixture)
+const exit = await closed
+assert.equal(exit.code, 0, exit.stderr)
+assert.deepEqual(await seedSnapshotEntries(fixture.seedTemp), [], "no runner workspace seed content survives a normal run")
+const result = JSON.parse(await readFile(join(fixture.workspace, ".codebox", "agent-task-workflow-result.json"), "utf8"))
+assert.equal(result.status, "skipped")
+
+console.log("native agent task interruption ok")

tests/runtime-sources-materialization.test.ts

@@ -287,7 +287,11 @@ await withTempDir("wp-codebox-runtime-sources-workflow-", async (directory) => {
 
 const executor = await readFile(new URL("../.github/scripts/run-agent-task/execute-native-agent-task.mjs", import.meta.url), "utf8")
 assert.match(executor, /for \(const signal of \["SIGINT", "SIGTERM", "SIGHUP"\]\)/)
-assert.match(executor, /cleanupPrivateRuntimeSources\(\)\.finally\(\(\) => process\.exit\(128\)\)/)
+assert.match(executor, /const SIGNAL_EXIT_CODES = \{ SIGINT: 130, SIGTERM: 143, SIGHUP: 129 \}/)
+assert.match(executor, /cleanupMaterializedSources\(\)\.finally\(\(\) => process\.exit\(SIGNAL_EXIT_CODES\[signal\]\)\)/)
+assert.match(executor, /\} finally \{\n  await cleanupMaterializedSources\(\)\n\}/, "every top-level completion path routes through the single cleanup coordinator")
+assert.equal(executor.match(/function cleanupMaterializedSources/g)?.length, 1, "cleanup stays centralized in one coordinator")
+assert.doesNotMatch(executor, /cleanupPrivateRuntimeSources|cleanupRunnerWorkspaceSeedSnapshot/, "no duplicate independent cleanup logic")
 assert.match(executor, /const executionInputPath = privateRuntimeSourceRoot \? join\(privateRuntimeSourceRoot, "native-agent-task-input\.json"\) : runtimeInputPath/)
 assert.match(executor, /const privatePreparationRoot = privateRuntimeSourceRoot \? join\(privateRuntimeSourceRoot, "prepared-runtime-sources"\) : ""/)
 assert.match(executor, /sanitizeRuntimeSourceValue\(nativeRuntimeResult, privateRuntimeSourceRootForSanitization\)/)