@cat-factory/executor-harness 1.31.8 → 1.31.10

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/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.10",
   "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/server": "0.66.6",
+    "@cat-factory/spend": "0.10.71"
   },
   "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/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 }