@cat-factory/executor-harness 1.31.8 → 1.31.12

package/dist/agent-runner.js

@@ -2,7 +2,7 @@ import { spawn } from 'node:child_process';
 import { mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { killChildProcess } from './process.js';
+import { killChildProcess, spawnDetached } from './process.js';
 import { redact, secretsToRedact } from './redact.js';
 function isObject(value) {
     return typeof value === 'object' && value !== null;
@@ -28,6 +28,8 @@ function streamCli(command, args, prompt, opts, env, secrets, onEvent) {
             cwd: opts.cwd,
             env: { ...process.env, ...env },
             stdio: ['pipe', 'pipe', 'pipe'],
+            // Own process group (POSIX) so killChildProcess reaps the CLI's grandchildren too.
+            detached: spawnDetached,
         });
         child.stdin.on('error', () => { });
         child.stdin.end(prompt);

package/dist/frontend-infra.js

@@ -59,6 +59,9 @@ function guardProcess(child, label, logger) {
 export async function standUpFrontend(dir, infra, signal, onActivity, logger = log) {
     const startedAt = Date.now();
     const processes = [];
+    // The frontend app's directory: the checkout root, or a monorepo subdirectory when the config
+    // named one. install/build/serve run here and `outputDir`/`mockMappingsPath` are relative to it.
+    const workDir = infra.directory ? join(dir, infra.directory) : dir;
     // Keep the run's inactivity watchdog fed while the (activity-silent) install → build → serve
     // stand-up runs. A real frontend's `install` + `build` can exceed the harness inactivity
     // window (default 10 min, JOB_INACTIVITY_MS) — and unlike the Pi phase this stand-up emits
@@ -96,7 +99,7 @@ export async function standUpFrontend(dir, infra, signal, onActivity, logger = l
         const install = installCommand(infra);
         logger.info('agent(frontend): installing', { command: install.join(' ') });
         const installed = await exec(install[0], install.slice(1), {
-            cwd: dir,
+            cwd: workDir,
             signal,
             timeout: 8 * 60_000,
             maxBuffer: 16 * 1024 * 1024,
@@ -107,7 +110,7 @@ export async function standUpFrontend(dir, infra, signal, onActivity, logger = l
         const buildScript = infra.buildScript ?? DEFAULTS.buildScript;
         logger.info('agent(frontend): building', { buildScript });
         const built = await exec(pm, ['run', buildScript], {
-            cwd: dir,
+            cwd: workDir,
             signal,
             timeout: 12 * 60_000,
             maxBuffer: 16 * 1024 * 1024,
@@ -128,7 +131,7 @@ export async function standUpFrontend(dir, infra, signal, onActivity, logger = l
                     'is only served in static mode; relying on the forwarded env instead', { outputDir });
             }
             const shim = `window.env = ${JSON.stringify(infra.env)};\n`;
-            await writeFile(join(dir, outputDir, 'env.js'), shim, 'utf8').catch((err) => {
+            await writeFile(join(workDir, outputDir, 'env.js'), shim, 'utf8').catch((err) => {
                 // Best-effort, but no longer silent: a missing/renamed output dir would drop the shim
                 // and the app would read no URLs, so surface it in the log for diagnosis.
                 logger.warn('agent(frontend): could not write runtime env shim', {
@@ -139,9 +142,9 @@ export async function standUpFrontend(dir, infra, signal, onActivity, logger = l
         }
         // 3) WireMock for the mocked upstreams. Seeded from the FE repo's mappings dir when present;
         // otherwise it still binds the port (unmatched requests 404, gentler than ECONNREFUSED).
-        processes.push(await startWireMock(dir, infra, wiremockPort, logger));
+        processes.push(await startWireMock(workDir, infra, wiremockPort, logger));
         // 4) Serve the built app.
-        processes.push(startServe(dir, infra, servePort, outputDir, logger));
+        processes.push(startServe(workDir, infra, servePort, outputDir, logger));
         // 5) Health-check the served app AND WireMock before handing off, concurrently (WireMock is
         // a JVM that cold-starts slower than the static server). A dead WireMock would otherwise let
         // the agent start and hit ECONNREFUSED on the app's first mocked-upstream call.

package/dist/job.js

@@ -81,7 +81,7 @@ function parseHarnessAuth(o) {
  * `..` segment) — the agent's cwd is built from this, so a hostile value must never
  * point outside the cloned repo.
  */
-function sanitizeServiceDirectory(value) {
+function sanitizeServiceDirectory(value, field = 'repo.serviceDirectory') {
     if (typeof value !== 'string')
         return undefined;
     const normalized = value
@@ -94,7 +94,7 @@ function sanitizeServiceDirectory(value) {
     if (segments.length === 0)
         return undefined;
     if (segments.some((s) => s === '..')) {
-        throw new Error("Invalid job: 'repo.serviceDirectory' must be a path inside the repo");
+        throw new Error(`Invalid job: '${field}' must be a path inside the repo`);
     }
     return segments.join('/');
 }
@@ -301,8 +301,13 @@ function parseFrontendInfraSpec(o) {
     }
     const servePort = port(o.servePort);
     const wiremockPort = port(o.wiremockPort);
+    // The app's monorepo subdirectory becomes the install/build/serve cwd, so it goes through the
+    // same escape-guard as `repo.serviceDirectory` — strip slashes and reject any `..` segment so a
+    // hostile value can't point the stand-up outside the cloned repo.
+    const directory = sanitizeServiceDirectory(o.directory, 'frontend.directory');
     return {
         kind: 'frontend',
+        ...(directory ? { directory } : {}),
         ...(packageManager ? { packageManager } : {}),
         ...(typeof o.install === 'string' && o.install ? { install: o.install } : {}),
         ...(typeof o.buildScript === 'string' && o.buildScript ? { buildScript: o.buildScript } : {}),

package/dist/pi.js

@@ -2,7 +2,7 @@ import { spawn } from 'node:child_process';
 import { appendFile, mkdir, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
-import { killChildProcess } from './process.js';
+import { killChildProcess, spawnDetached } from './process.js';
 import { pathExists } from './fs-utils.js';
 import { redactSecrets } from './redact.js';
 import { log } from './logger.js';
@@ -573,6 +573,8 @@ export function runPi(opts) {
             // stdin is piped (not 'ignore') so the prompt is delivered out-of-band
             // rather than on argv — see the function doc for the injection rationale.
             stdio: ['pipe', 'pipe', 'pipe'],
+            // Own process group (POSIX) so killChildProcess reaps Pi's grandchildren too.
+            detached: spawnDetached,
         });
         // Hand Pi the prompt over stdin, then close it so print mode sees EOF and
         // runs. Ignore stdin errors (e.g. EPIPE if Pi exits before reading): the

package/dist/process.js

@@ -6,20 +6,48 @@ import { log } from './logger.js';
 // How long to wait after SIGTERM before escalating to SIGKILL.
 const KILL_GRACE_MS = 5_000;
 /**
- * Terminate a child process: SIGTERM first, then SIGKILL after a grace period if it
- * hasn't exited (ignored an ordinary terminate). The escalation timer is `unref()`d
- * so it never by itself keeps the event loop alive. Safe to call more than once.
+ * Signal a child and, when it was spawned detached (a process-group leader on POSIX — see
+ * `spawnDetached`), the whole group with it. The agent CLIs (`claude`/`codex`/Pi) spawn their
+ * own grandchildren (a shell tool, a build, their own git); a plain `child.kill()` reaps only
+ * the direct child and those grandchildren reparent to init and keep running unsupervised.
+ * `process.kill(-pid)` targets the group instead. Falls back to a direct kill on Windows (no
+ * POSIX process groups) or when the group send fails (already reaped, or the child wasn't
+ * spawned detached so no group of its own exists).
+ */
+function signalTree(child, signal) {
+    if (child.pid !== undefined && process.platform !== 'win32') {
+        try {
+            process.kill(-child.pid, signal);
+            return;
+        }
+        catch {
+            // Fall through to the direct kill below.
+        }
+    }
+    child.kill(signal);
+}
+/**
+ * Terminate a child process (and its group — see {@link signalTree}): SIGTERM first, then
+ * SIGKILL after a grace period if it hasn't exited (ignored an ordinary terminate). The
+ * escalation timer is `unref()`d so it never by itself keeps the event loop alive. Safe to
+ * call more than once.
  *
  * An actual escalation to SIGKILL is logged at warn level: a process that ignores
  * SIGTERM and has to be force-killed is a signal worth seeing (a wedged Pi/CLI), and
  * was previously invisible. Pass a child logger to carry the run's `jobId`.
  */
 export function killChildProcess(child, graceMs = KILL_GRACE_MS, logger = log) {
-    child.kill('SIGTERM');
+    signalTree(child, 'SIGTERM');
     setTimeout(() => {
         if (child.exitCode === null && child.signalCode === null) {
             logger.warn('killChildProcess: process ignored SIGTERM, escalating to SIGKILL', { graceMs });
-            child.kill('SIGKILL');
+            signalTree(child, 'SIGKILL');
         }
     }, graceMs).unref();
 }
+/**
+ * Whether a spawned agent CLI should be its own process-group leader so {@link killChildProcess}
+ * can reap the whole tree (its grandchildren) on abort. POSIX only; Windows has no process
+ * groups (and `detached` there spawns a new console we don't want), so it stays false.
+ */
+export const spawnDetached = process.platform !== 'win32';

package/dist/runner.js

@@ -20,7 +20,7 @@ export function loadRunnerLimits(env = process.env) {
     };
 }
 function toView(entry) {
-    const { promise: _promise, spanBuffer: _spanBuffer, followUpBuffer: _followUpBuffer, ...view } = entry;
+    const { promise: _promise, spanBuffer: _spanBuffer, followUpBuffer: _followUpBuffer, abort: _abort, ...view } = entry;
     return { ...view };
 }
 /**
@@ -90,6 +90,35 @@ export class JobRegistry {
         }
         return view;
     }
+    /**
+     * Abort every RUNNING job (fires each run's abort signal, which SIGTERM→SIGKILLs its
+     * CLI/git children via `killChildProcess`). The graceful-shutdown hook: a harness dying
+     * to SIGTERM must not orphan a live agent subprocess — reparented, it would keep working
+     * unsupervised (and, in native local mode, on the developer's own login). Returns the
+     * number of jobs aborted.
+     */
+    abortAll(reason) {
+        let aborted = 0;
+        for (const entry of this.jobs.values()) {
+            if (entry.state === 'running' && entry.abort) {
+                entry.abort(reason);
+                aborted += 1;
+            }
+        }
+        return aborted;
+    }
+    /**
+     * How many jobs are still RUNNING. Graceful shutdown polls this so it can exit the moment the
+     * aborted jobs have actually settled (the common case: the CLI honours SIGTERM in ms) instead
+     * of waiting out a fixed kill-grace window.
+     */
+    runningCount() {
+        let running = 0;
+        for (const entry of this.jobs.values())
+            if (entry.state === 'running')
+                running += 1;
+        return running;
+    }
     async drive(entry, job) {
         const controller = new AbortController();
         let killReason;
@@ -130,6 +159,8 @@ export class JobRegistry {
             resetInactivity();
         };
         resetInactivity();
+        // Expose the abort for shutdown (see abortAll); cleared in `finally` once the job settles.
+        entry.abort = (reason) => controller.abort(new Error(reason));
         jobLog.info('job started', {});
         try {
             const result = await this.run(job, {
@@ -182,6 +213,7 @@ export class JobRegistry {
         finally {
             clearTimeout(inactivity);
             clearTimeout(cap);
+            entry.abort = undefined;
             entry.heartbeatAt = Date.now();
         }
     }

package/dist/server.js

@@ -13,6 +13,11 @@ import { log } from './logger.js';
 // in the request body and live only for the duration of the job in an ephemeral
 // workspace.
 const PORT = Number(process.env.PORT ?? 8080);
+// Optional bind address. Default (unset) binds all interfaces — a container needs that for
+// its published port. The native local transport runs the harness UNSANDBOXED on the
+// developer's host and only ever connects over loopback, so it sets 127.0.0.1 to keep the
+// agent-spawning API off the LAN.
+const BIND_HOST = process.env.HARNESS_BIND_HOST?.trim() || undefined;
 // Optional inbound auth. When HARNESS_SHARED_SECRET is set, every non-health
 // request must present a matching `x-harness-secret` header (constant-time
 // compared). When it is unset the harness behaves as before (open), so local/dev
@@ -128,8 +133,35 @@ const server = createServer((req, res) => {
 });
 // Only auto-listen when run as the entry point (tests import handleRun directly).
 if (process.env.NODE_ENV !== 'test') {
-    server.listen(PORT, () => {
-        console.log(`executor-harness listening on :${PORT}`);
+    server.listen(PORT, BIND_HOST, () => {
+        console.log(`executor-harness listening on ${BIND_HOST ?? ''}:${PORT}`);
     });
+    // Graceful shutdown: dying to a bare SIGTERM/SIGINT (the default handler) would ORPHAN any
+    // in-flight `claude`/`codex`/git child — reparented, it keeps working unsupervised (and in
+    // native local mode on the developer's own login). Abort every running job first (the
+    // SIGTERM→SIGKILL escalation in killChildProcess), then exit as SOON as the aborted jobs have
+    // settled — the CLI usually honours SIGTERM in milliseconds, so don't block every shutdown on
+    // a fixed window. The 6s cap covers a job that ignored SIGTERM and had to be force-killed (the
+    // 5s escalation) plus a margin. Nothing running ⇒ exit immediately. A second signal takes the
+    // default (immediate) exit, since `once` leaves it unhandled.
+    const shutdown = (signal) => {
+        const aborted = Object.values(KINDS).reduce((count, { registry }) => count + registry.abortAll(`harness shutting down (${signal})`), 0);
+        log.info('shutting down', { signal, abortedJobs: aborted });
+        server.close();
+        if (aborted === 0) {
+            process.exit(0);
+            return;
+        }
+        const deadline = Date.now() + 6_000;
+        const timer = setInterval(() => {
+            const stillRunning = Object.values(KINDS).some(({ registry }) => registry.runningCount() > 0);
+            if (!stillRunning || Date.now() >= deadline) {
+                clearInterval(timer);
+                process.exit(0);
+            }
+        }, 50);
+    };
+    process.once('SIGTERM', () => shutdown('SIGTERM'));
+    process.once('SIGINT', () => shutdown('SIGINT'));
 }
 export { server };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.31.8",
+  "version": "1.31.12",
   "description": "Container payload: a thin TypeScript wrapper that runs the Pi coding agent against a cloned repo and opens a PR. Runs in the Cloudflare Container (and, in local native mode, as a host process); carries no secrets.",
   "repository": {
     "type": "git",
@@ -26,8 +26,8 @@
     "hono": "^4.12.27",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9",
-    "@cat-factory/server": "0.66.4",
-    "@cat-factory/spend": "0.10.70"
+    "@cat-factory/spend": "0.10.73",
+    "@cat-factory/server": "0.67.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent-runner.ts

@@ -3,7 +3,7 @@ import { mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import type { PiRunOutcome, PiRunStats, TodoProgress } from './pi.js'
-import { killChildProcess } from './process.js'
+import { killChildProcess, spawnDetached } from './process.js'
 import { redact, secretsToRedact } from './redact.js'
 
 // The alternate (subscription) harness runners. The Pi harness reaches models
@@ -93,6 +93,8 @@ function streamCli(
       cwd: opts.cwd,
       env: { ...process.env, ...env },
       stdio: ['pipe', 'pipe', 'pipe'],
+      // Own process group (POSIX) so killChildProcess reaps the CLI's grandchildren too.
+      detached: spawnDetached,
     })
     child.stdin.on('error', () => {})
     child.stdin.end(prompt)

package/src/frontend-infra.ts

@@ -83,6 +83,9 @@ export async function standUpFrontend(
 ): Promise<FrontendStandUp> {
   const startedAt = Date.now()
   const processes: ChildProcess[] = []
+  // The frontend app's directory: the checkout root, or a monorepo subdirectory when the config
+  // named one. install/build/serve run here and `outputDir`/`mockMappingsPath` are relative to it.
+  const workDir = infra.directory ? join(dir, infra.directory) : dir
   // Keep the run's inactivity watchdog fed while the (activity-silent) install → build → serve
   // stand-up runs. A real frontend's `install` + `build` can exceed the harness inactivity
   // window (default 10 min, JOB_INACTIVITY_MS) — and unlike the Pi phase this stand-up emits
@@ -121,7 +124,7 @@ export async function standUpFrontend(
     const install = installCommand(infra)
     logger.info('agent(frontend): installing', { command: install.join(' ') })
     const installed = await exec(install[0]!, install.slice(1), {
-      cwd: dir,
+      cwd: workDir,
       signal,
       timeout: 8 * 60_000,
       maxBuffer: 16 * 1024 * 1024,
@@ -133,7 +136,7 @@ export async function standUpFrontend(
     const buildScript = infra.buildScript ?? DEFAULTS.buildScript
     logger.info('agent(frontend): building', { buildScript })
     const built = await exec(pm, ['run', buildScript], {
-      cwd: dir,
+      cwd: workDir,
       signal,
       timeout: 12 * 60_000,
       maxBuffer: 16 * 1024 * 1024,
@@ -158,7 +161,7 @@ export async function standUpFrontend(
         )
       }
       const shim = `window.env = ${JSON.stringify(infra.env)};\n`
-      await writeFile(join(dir, outputDir, 'env.js'), shim, 'utf8').catch((err) => {
+      await writeFile(join(workDir, outputDir, 'env.js'), shim, 'utf8').catch((err) => {
         // Best-effort, but no longer silent: a missing/renamed output dir would drop the shim
         // and the app would read no URLs, so surface it in the log for diagnosis.
         logger.warn('agent(frontend): could not write runtime env shim', {
@@ -170,10 +173,10 @@ export async function standUpFrontend(
 
     // 3) WireMock for the mocked upstreams. Seeded from the FE repo's mappings dir when present;
     // otherwise it still binds the port (unmatched requests 404, gentler than ECONNREFUSED).
-    processes.push(await startWireMock(dir, infra, wiremockPort, logger))
+    processes.push(await startWireMock(workDir, infra, wiremockPort, logger))
 
     // 4) Serve the built app.
-    processes.push(startServe(dir, infra, servePort, outputDir, logger))
+    processes.push(startServe(workDir, infra, servePort, outputDir, logger))
 
     // 5) Health-check the served app AND WireMock before handing off, concurrently (WireMock is
     // a JVM that cold-starts slower than the static server). A dead WireMock would otherwise let

package/src/job.ts

@@ -146,7 +146,10 @@ function parseHarnessAuth(o: Record<string, unknown>): HarnessAuthFields {
  * `..` segment) — the agent's cwd is built from this, so a hostile value must never
  * point outside the cloned repo.
  */
-function sanitizeServiceDirectory(value: unknown): string | undefined {
+function sanitizeServiceDirectory(
+  value: unknown,
+  field = 'repo.serviceDirectory',
+): string | undefined {
   if (typeof value !== 'string') return undefined
   const normalized = value
     .trim()
@@ -156,7 +159,7 @@ function sanitizeServiceDirectory(value: unknown): string | undefined {
   const segments = normalized.split('/').filter((s) => s !== '' && s !== '.')
   if (segments.length === 0) return undefined
   if (segments.some((s) => s === '..')) {
-    throw new Error("Invalid job: 'repo.serviceDirectory' must be a path inside the repo")
+    throw new Error(`Invalid job: '${field}' must be a path inside the repo`)
   }
   return segments.join('/')
 }
@@ -290,6 +293,12 @@ export interface ServiceInfraSpec {
  */
 export interface FrontendInfraSpec {
   kind: 'frontend'
+  /**
+   * The frontend app's subdirectory within the checkout (a monorepo frontend). Absent ⇒ the
+   * checkout root. When set, install/build/serve run there and `outputDir`/`wiremockMappingsPath`
+   * are resolved relative to it.
+   */
+  directory?: string
   /** Package manager for install/build. Default `pnpm`. */
   packageManager?: 'pnpm' | 'npm' | 'yarn'
   /** Explicit install command, overriding the one derived from `packageManager`. */
@@ -659,8 +668,13 @@ function parseFrontendInfraSpec(o: Record<string, unknown>): FrontendInfraSpec {
   }
   const servePort = port(o.servePort)
   const wiremockPort = port(o.wiremockPort)
+  // The app's monorepo subdirectory becomes the install/build/serve cwd, so it goes through the
+  // same escape-guard as `repo.serviceDirectory` — strip slashes and reject any `..` segment so a
+  // hostile value can't point the stand-up outside the cloned repo.
+  const directory = sanitizeServiceDirectory(o.directory, 'frontend.directory')
   return {
     kind: 'frontend',
+    ...(directory ? { directory } : {}),
     ...(packageManager ? { packageManager } : {}),
     ...(typeof o.install === 'string' && o.install ? { install: o.install } : {}),
     ...(typeof o.buildScript === 'string' && o.buildScript ? { buildScript: o.buildScript } : {}),

package/src/pi.ts

@@ -2,7 +2,7 @@ import { spawn } from 'node:child_process'
 import { appendFile, mkdir, writeFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
-import { killChildProcess } from './process.js'
+import { killChildProcess, spawnDetached } from './process.js'
 import { pathExists } from './fs-utils.js'
 import { redactSecrets } from './redact.js'
 import { log } from './logger.js'
@@ -831,6 +831,8 @@ export function runPi(opts: {
         // stdin is piped (not 'ignore') so the prompt is delivered out-of-band
         // rather than on argv — see the function doc for the injection rationale.
         stdio: ['pipe', 'pipe', 'pipe'],
+        // Own process group (POSIX) so killChildProcess reaps Pi's grandchildren too.
+        detached: spawnDetached,
       },
     )
     // Hand Pi the prompt over stdin, then close it so print mode sees EOF and

package/src/process.ts

@@ -10,9 +10,31 @@ import { log, type Logger } from './logger.js'
 const KILL_GRACE_MS = 5_000
 
 /**
- * Terminate a child process: SIGTERM first, then SIGKILL after a grace period if it
- * hasn't exited (ignored an ordinary terminate). The escalation timer is `unref()`d
- * so it never by itself keeps the event loop alive. Safe to call more than once.
+ * Signal a child and, when it was spawned detached (a process-group leader on POSIX — see
+ * `spawnDetached`), the whole group with it. The agent CLIs (`claude`/`codex`/Pi) spawn their
+ * own grandchildren (a shell tool, a build, their own git); a plain `child.kill()` reaps only
+ * the direct child and those grandchildren reparent to init and keep running unsupervised.
+ * `process.kill(-pid)` targets the group instead. Falls back to a direct kill on Windows (no
+ * POSIX process groups) or when the group send fails (already reaped, or the child wasn't
+ * spawned detached so no group of its own exists).
+ */
+function signalTree(child: ChildProcess, signal: NodeJS.Signals): void {
+  if (child.pid !== undefined && process.platform !== 'win32') {
+    try {
+      process.kill(-child.pid, signal)
+      return
+    } catch {
+      // Fall through to the direct kill below.
+    }
+  }
+  child.kill(signal)
+}
+
+/**
+ * Terminate a child process (and its group — see {@link signalTree}): SIGTERM first, then
+ * SIGKILL after a grace period if it hasn't exited (ignored an ordinary terminate). The
+ * escalation timer is `unref()`d so it never by itself keeps the event loop alive. Safe to
+ * call more than once.
  *
  * An actual escalation to SIGKILL is logged at warn level: a process that ignores
  * SIGTERM and has to be force-killed is a signal worth seeing (a wedged Pi/CLI), and
@@ -23,11 +45,18 @@ export function killChildProcess(
   graceMs: number = KILL_GRACE_MS,
   logger: Logger = log,
 ): void {
-  child.kill('SIGTERM')
+  signalTree(child, 'SIGTERM')
   setTimeout(() => {
     if (child.exitCode === null && child.signalCode === null) {
       logger.warn('killChildProcess: process ignored SIGTERM, escalating to SIGKILL', { graceMs })
-      child.kill('SIGKILL')
+      signalTree(child, 'SIGKILL')
     }
   }, graceMs).unref()
 }
+
+/**
+ * Whether a spawned agent CLI should be its own process-group leader so {@link killChildProcess}
+ * can reap the whole tree (its grandchildren) on abort. POSIX only; Windows has no process
+ * groups (and `detached` there spawns a new console we don't want), so it stays false.
+ */
+export const spawnDetached = process.platform !== 'win32'

package/src/runner.ts

@@ -123,6 +123,8 @@ interface JobEntry<TResult extends JobResultBase> extends JobView<TResult> {
   spanBuffer: ToolSpan[]
   /** Follow-up items buffered since the last drain (see {@link JobView.followUps}). */
   followUpBuffer: FollowUpLine[]
+  /** Abort the in-flight run (see {@link JobRegistry.abortAll}); set while running only. */
+  abort?: (reason: string) => void
 }
 
 /** Watchdog windows that bound every job. Tunable via the container's env. */
@@ -158,6 +160,7 @@ function toView<TResult extends JobResultBase>(entry: JobEntry<TResult>): JobVie
     promise: _promise,
     spanBuffer: _spanBuffer,
     followUpBuffer: _followUpBuffer,
+    abort: _abort,
     ...view
   } = entry
   return { ...view }
@@ -228,6 +231,35 @@ export class JobRegistry<TJob = unknown, TResult extends JobResultBase = JobResu
     return view
   }
 
+  /**
+   * Abort every RUNNING job (fires each run's abort signal, which SIGTERM→SIGKILLs its
+   * CLI/git children via `killChildProcess`). The graceful-shutdown hook: a harness dying
+   * to SIGTERM must not orphan a live agent subprocess — reparented, it would keep working
+   * unsupervised (and, in native local mode, on the developer's own login). Returns the
+   * number of jobs aborted.
+   */
+  abortAll(reason: string): number {
+    let aborted = 0
+    for (const entry of this.jobs.values()) {
+      if (entry.state === 'running' && entry.abort) {
+        entry.abort(reason)
+        aborted += 1
+      }
+    }
+    return aborted
+  }
+
+  /**
+   * How many jobs are still RUNNING. Graceful shutdown polls this so it can exit the moment the
+   * aborted jobs have actually settled (the common case: the CLI honours SIGTERM in ms) instead
+   * of waiting out a fixed kill-grace window.
+   */
+  runningCount(): number {
+    let running = 0
+    for (const entry of this.jobs.values()) if (entry.state === 'running') running += 1
+    return running
+  }
+
   private async drive(entry: JobEntry<TResult>, job: TJob): Promise<void> {
     const controller = new AbortController()
     let killReason: 'inactivity' | 'max-duration' | undefined
@@ -271,6 +303,8 @@ export class JobRegistry<TJob = unknown, TResult extends JobResultBase = JobResu
       resetInactivity()
     }
     resetInactivity()
+    // Expose the abort for shutdown (see abortAll); cleared in `finally` once the job settles.
+    entry.abort = (reason) => controller.abort(new Error(reason))
 
     jobLog.info('job started', {})
     try {
@@ -327,6 +361,7 @@ export class JobRegistry<TJob = unknown, TResult extends JobResultBase = JobResu
     } finally {
       clearTimeout(inactivity)
       clearTimeout(cap)
+      entry.abort = undefined
       entry.heartbeatAt = Date.now()
     }
   }

package/src/server.ts

@@ -16,6 +16,12 @@ import { log } from './logger.js'
 
 const PORT = Number(process.env.PORT ?? 8080)
 
+// Optional bind address. Default (unset) binds all interfaces — a container needs that for
+// its published port. The native local transport runs the harness UNSANDBOXED on the
+// developer's host and only ever connects over loopback, so it sets 127.0.0.1 to keep the
+// agent-spawning API off the LAN.
+const BIND_HOST = process.env.HARNESS_BIND_HOST?.trim() || undefined
+
 // Optional inbound auth. When HARNESS_SHARED_SECRET is set, every non-health
 // request must present a matching `x-harness-secret` header (constant-time
 // compared). When it is unset the harness behaves as before (open), so local/dev
@@ -145,9 +151,40 @@ const server = createServer((req, res) => {
 
 // Only auto-listen when run as the entry point (tests import handleRun directly).
 if (process.env.NODE_ENV !== 'test') {
-  server.listen(PORT, () => {
-    console.log(`executor-harness listening on :${PORT}`)
+  server.listen(PORT, BIND_HOST, () => {
+    console.log(`executor-harness listening on ${BIND_HOST ?? ''}:${PORT}`)
   })
+
+  // Graceful shutdown: dying to a bare SIGTERM/SIGINT (the default handler) would ORPHAN any
+  // in-flight `claude`/`codex`/git child — reparented, it keeps working unsupervised (and in
+  // native local mode on the developer's own login). Abort every running job first (the
+  // SIGTERM→SIGKILL escalation in killChildProcess), then exit as SOON as the aborted jobs have
+  // settled — the CLI usually honours SIGTERM in milliseconds, so don't block every shutdown on
+  // a fixed window. The 6s cap covers a job that ignored SIGTERM and had to be force-killed (the
+  // 5s escalation) plus a margin. Nothing running ⇒ exit immediately. A second signal takes the
+  // default (immediate) exit, since `once` leaves it unhandled.
+  const shutdown = (signal: string): void => {
+    const aborted = Object.values(KINDS).reduce(
+      (count, { registry }) => count + registry.abortAll(`harness shutting down (${signal})`),
+      0,
+    )
+    log.info('shutting down', { signal, abortedJobs: aborted })
+    server.close()
+    if (aborted === 0) {
+      process.exit(0)
+      return
+    }
+    const deadline = Date.now() + 6_000
+    const timer = setInterval(() => {
+      const stillRunning = Object.values(KINDS).some(({ registry }) => registry.runningCount() > 0)
+      if (!stillRunning || Date.now() >= deadline) {
+        clearInterval(timer)
+        process.exit(0)
+      }
+    }, 50)
+  }
+  process.once('SIGTERM', () => shutdown('SIGTERM'))
+  process.once('SIGINT', () => shutdown('SIGINT'))
 }
 
 export { server }