@cat-factory/executor-harness 1.31.6 → 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/agent.js

@@ -533,6 +533,24 @@ async function runCodingMode(job, opts) {
             ...(job.repo.provider ? { provider: job.repo.provider } : {}),
             signal: opts.signal,
         });
+        // `null` ⇒ the branch has nothing ahead of base, so there was no PR to open (a resumed
+        // branch whose earlier PR already merged). Record it as a clean no-op rather than a push,
+        // mirroring the no-changes outcome — the `runCodingAgent` guard normally catches this, so
+        // this is the belt-and-suspenders path when the ahead-of-base check couldn't determine it.
+        if (prUrl === null) {
+            if (job.noChangesIsError === false) {
+                return { pushed: false, branch: pushBranch, summary, stats, ...(usage ? { usage } : {}) };
+            }
+            return {
+                pushed: false,
+                branch: pushBranch,
+                summary,
+                stats,
+                error: noChangesReason('the work branch has no commits ahead of its base (nothing to open a PR for)', stats, stderrTail),
+                failureCause: 'no-changes',
+                ...(usage ? { usage } : {}),
+            };
+        }
         return { pushed: true, prUrl, branch: pushBranch, summary, stats, ...(usage ? { usage } : {}) };
     }
     return { pushed: true, branch: pushBranch, summary, stats, ...(usage ? { usage } : {}) };

package/dist/coding-agent.js

@@ -1,6 +1,6 @@
 import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
-import { branchHasCommitsSince, cloneExistingBranch, cloneRepo, commitTrackedEdits, createBranch, excludeFromGit, headCommit, listUntrackedFiles, prepareExistingCheckout, pushBranch, refreshFromBaseIfClean, remoteBranchExists, } from './git.js';
+import { branchAheadOfBase, branchHasCommitsSince, cloneExistingBranch, cloneRepo, commitTrackedEdits, createBranch, excludeFromGit, headCommit, listUntrackedFiles, prepareExistingCheckout, pushBranch, refreshFromBaseIfClean, remoteBranchExists, } from './git.js';
 import { FOLLOW_UPS_FILENAME, FollowUpTailer } from './follow-ups.js';
 import { acquireRepoCheckout, agentNeverActed, agentOutputTail, runAgentInWorkspace, } from './pi-workspace.js';
 import { log } from './logger.js';
@@ -238,7 +238,24 @@ export async function runCodingAgent(spec, opts = {}) {
                     files: leftover.slice(0, 20),
                 });
             }
-            const hasWork = resumed || (await branchHasCommitsSince(dir, baseSha, signal));
+            // A fresh run produced work iff the branch advanced past its pre-run tip. A RESUMED
+            // run already carries prior work — UNLESS that branch turns out to have nothing ahead
+            // of the PR base (e.g. its earlier PR was merged with a merge commit, leaving the
+            // branch reachable from base and its best-effort delete skipped). Opening a PR for such
+            // a branch fails with GitHub's opaque 422 "No commits between ...", so a CONFIRMED-empty
+            // resumed branch is a no-op, not work. `undefined` (couldn't determine) keeps the prior
+            // resume-is-work behaviour; the PR-open path then no-ops on the 422 as a backstop.
+            const advancedThisPass = await branchHasCommitsSince(dir, baseSha, signal);
+            let hasWork = advancedThisPass || resumed;
+            if (resumed && !advancedThisPass) {
+                const ahead = await branchAheadOfBase(dir, spec.repo.baseBranch, spec.ghToken, signal);
+                if (ahead === false) {
+                    logger.info('coding-agent: resumed branch has no commits ahead of base — no-op', {
+                        base: spec.repo.baseBranch,
+                    });
+                    hasWork = false;
+                }
+            }
             if (!hasWork) {
                 logger.info('coding-agent: no changes produced', { ...stats });
                 outcome = {

package/dist/git.js

@@ -395,6 +395,36 @@ export async function excludeFromGit(dir, pattern, signal) {
 export async function branchHasCommitsSince(dir, baseSha, signal) {
     return (await headCommit(dir, signal)) !== baseSha;
 }
+/**
+ * Whether the checked-out branch carries at least one commit the PR base does NOT — i.e.
+ * `git rev-list --count <base>..HEAD > 0`. A resume clone is single-branch, so it has no
+ * `origin/<base>` tracking ref; this fetches the base into a dedicated local ref first and
+ * diffs HEAD against it.
+ *
+ * Tri-state on purpose:
+ *  - `true`  — confirmed ≥1 commit ahead (there is something to open a PR for).
+ *  - `false` — confirmed 0 commits ahead (the branch is reachable from base, e.g. its earlier
+ *              PR was merged with a merge commit and the best-effort branch delete was skipped).
+ *  - `undefined` — could not determine (fetch / rev-list error); the caller keeps its prior
+ *              behaviour rather than wrongly dropping a resumed branch that has real work.
+ *
+ * Used by the resume path to avoid declaring a merged/empty branch as work and then failing
+ * the run with GitHub's opaque 422 "No commits between <base> and <branch>".
+ */
+export async function branchAheadOfBase(dir, baseBranch, ghToken, signal) {
+    try {
+        await git(['fetch', 'origin', `+refs/heads/${baseBranch}:refs/cat-factory/base`], {
+            cwd: dir,
+            signal,
+            env: await authEnv(ghToken),
+        });
+        const count = (await git(['rev-list', '--count', 'refs/cat-factory/base..HEAD'], { cwd: dir, signal })).trim();
+        return Number(count) > 0;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Whether the checked-out branch has a real, examinable diff against
  * `origin/<baseBranch>` — i.e. the base branch's remote-tracking ref exists (so the
@@ -749,6 +779,13 @@ export async function openPullRequest(opts) {
             if (existing)
                 return existing;
         }
+        // The head branch has nothing ahead of base ("No commits between <base> and <head>").
+        // That is not an API failure — there is simply nothing to open a PR for (e.g. a resumed
+        // branch whose earlier PR was merged with a merge commit, leaving the branch reachable
+        // from base). Signal it with null so the caller records a clean no-op instead of failing
+        // the run with GitHub's opaque 422.
+        if (res.status === 422 && /no commits between/i.test(detail))
+            return null;
         throw new HarnessFailure('api', redactSecrets(`Failed to open PR (HTTP ${res.status}): ${detail.slice(0, 300)}`));
     }
     const body = (await res.json());

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.6",
+  "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/spend": "0.10.69",
-    "@cat-factory/server": "0.66.1"
+    "@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/agent.ts

@@ -626,6 +626,28 @@ async function runCodingMode(job: AgentJob, opts: RunOptions): Promise<AgentResu
       ...(job.repo.provider ? { provider: job.repo.provider } : {}),
       signal: opts.signal,
     })
+    // `null` ⇒ the branch has nothing ahead of base, so there was no PR to open (a resumed
+    // branch whose earlier PR already merged). Record it as a clean no-op rather than a push,
+    // mirroring the no-changes outcome — the `runCodingAgent` guard normally catches this, so
+    // this is the belt-and-suspenders path when the ahead-of-base check couldn't determine it.
+    if (prUrl === null) {
+      if (job.noChangesIsError === false) {
+        return { pushed: false, branch: pushBranch, summary, stats, ...(usage ? { usage } : {}) }
+      }
+      return {
+        pushed: false,
+        branch: pushBranch,
+        summary,
+        stats,
+        error: noChangesReason(
+          'the work branch has no commits ahead of its base (nothing to open a PR for)',
+          stats,
+          stderrTail,
+        ),
+        failureCause: 'no-changes',
+        ...(usage ? { usage } : {}),
+      }
+    }
     return { pushed: true, prUrl, branch: pushBranch, summary, stats, ...(usage ? { usage } : {}) }
   }
   return { pushed: true, branch: pushBranch, summary, stats, ...(usage ? { usage } : {}) }

package/src/coding-agent.ts

@@ -2,6 +2,7 @@ import { mkdir } from 'node:fs/promises'
 import { join } from 'node:path'
 import type { HarnessAuthFields, RepoSpec } from './job.js'
 import {
+  branchAheadOfBase,
   branchHasCommitsSince,
   cloneExistingBranch,
   cloneRepo,
@@ -343,7 +344,24 @@ export async function runCodingAgent(
           })
         }
 
-        const hasWork = resumed || (await branchHasCommitsSince(dir, baseSha, signal))
+        // A fresh run produced work iff the branch advanced past its pre-run tip. A RESUMED
+        // run already carries prior work — UNLESS that branch turns out to have nothing ahead
+        // of the PR base (e.g. its earlier PR was merged with a merge commit, leaving the
+        // branch reachable from base and its best-effort delete skipped). Opening a PR for such
+        // a branch fails with GitHub's opaque 422 "No commits between ...", so a CONFIRMED-empty
+        // resumed branch is a no-op, not work. `undefined` (couldn't determine) keeps the prior
+        // resume-is-work behaviour; the PR-open path then no-ops on the 422 as a backstop.
+        const advancedThisPass = await branchHasCommitsSince(dir, baseSha, signal)
+        let hasWork = advancedThisPass || resumed
+        if (resumed && !advancedThisPass) {
+          const ahead = await branchAheadOfBase(dir, spec.repo.baseBranch, spec.ghToken, signal)
+          if (ahead === false) {
+            logger.info('coding-agent: resumed branch has no commits ahead of base — no-op', {
+              base: spec.repo.baseBranch,
+            })
+            hasWork = false
+          }
+        }
         if (!hasWork) {
           logger.info('coding-agent: no changes produced', { ...stats })
           outcome = {

package/src/git.ts

@@ -495,6 +495,43 @@ export async function branchHasCommitsSince(
   return (await headCommit(dir, signal)) !== baseSha
 }
 
+/**
+ * Whether the checked-out branch carries at least one commit the PR base does NOT — i.e.
+ * `git rev-list --count <base>..HEAD > 0`. A resume clone is single-branch, so it has no
+ * `origin/<base>` tracking ref; this fetches the base into a dedicated local ref first and
+ * diffs HEAD against it.
+ *
+ * Tri-state on purpose:
+ *  - `true`  — confirmed ≥1 commit ahead (there is something to open a PR for).
+ *  - `false` — confirmed 0 commits ahead (the branch is reachable from base, e.g. its earlier
+ *              PR was merged with a merge commit and the best-effort branch delete was skipped).
+ *  - `undefined` — could not determine (fetch / rev-list error); the caller keeps its prior
+ *              behaviour rather than wrongly dropping a resumed branch that has real work.
+ *
+ * Used by the resume path to avoid declaring a merged/empty branch as work and then failing
+ * the run with GitHub's opaque 422 "No commits between <base> and <branch>".
+ */
+export async function branchAheadOfBase(
+  dir: string,
+  baseBranch: string,
+  ghToken: string,
+  signal?: AbortSignal,
+): Promise<boolean | undefined> {
+  try {
+    await git(['fetch', 'origin', `+refs/heads/${baseBranch}:refs/cat-factory/base`], {
+      cwd: dir,
+      signal,
+      env: await authEnv(ghToken),
+    })
+    const count = (
+      await git(['rev-list', '--count', 'refs/cat-factory/base..HEAD'], { cwd: dir, signal })
+    ).trim()
+    return Number(count) > 0
+  } catch {
+    return undefined
+  }
+}
+
 /**
  * Whether the checked-out branch has a real, examinable diff against
  * `origin/<baseBranch>` — i.e. the base branch's remote-tracking ref exists (so the
@@ -876,7 +913,7 @@ function backoffMs(attempt: number): number {
  * GitLab whose host isn't named `gitlab.*` still opens an MR instead of being misrouted to
  * GitHub's API. The GitHub path is unchanged.
  */
-export async function openPullRequest(opts: OpenPullRequestOptions): Promise<string> {
+export async function openPullRequest(opts: OpenPullRequestOptions): Promise<string | null> {
   const provider = opts.provider ?? (opts.cloneUrl ? inferVcsProvider(opts.cloneUrl) : 'github')
   if (provider === 'gitlab') {
     if (!opts.cloneUrl) {
@@ -917,6 +954,12 @@ export async function openPullRequest(opts: OpenPullRequestOptions): Promise<str
       const existing = await findOpenPullRequestUrl(opts)
       if (existing) return existing
     }
+    // The head branch has nothing ahead of base ("No commits between <base> and <head>").
+    // That is not an API failure — there is simply nothing to open a PR for (e.g. a resumed
+    // branch whose earlier PR was merged with a merge commit, leaving the branch reachable
+    // from base). Signal it with null so the caller records a clean no-op instead of failing
+    // the run with GitHub's opaque 422.
+    if (res.status === 422 && /no commits between/i.test(detail)) return null
     throw new HarnessFailure(
       'api',
       redactSecrets(`Failed to open PR (HTTP ${res.status}): ${detail.slice(0, 300)}`),

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 }