@cat-factory/executor-harness 1.120.0 → 1.122.0

package/README.md

@@ -320,7 +320,7 @@ Kimi / DeepSeek) and meters spend. The provider key never enters the container.
 
 | File               | Responsibility                                                                                          |
 | ------------------ | ------------------------------------------------------------------------------------------------------- |
-| `src/server.ts`    | HTTP entry point; routes `/health`, `/run`, `/bootstrap`, `/blueprint`, `/jobs/{id}`.                   |
+| `src/harness-server.ts` | HTTP entry point; routes `/health`, `/run`, `/bootstrap`, `/blueprint`, `/jobs/{id}`. Its file name and the `cat-factory-harness` process title it sets are both deliberate: this process is PID 1 beside an agent that runs arbitrary shell as the same user, so it must not answer to a pattern kill aimed at the service the agent just built. |
 | `src/runner.ts`    | `JobRegistry`: async job lifecycle, idempotent on `jobId`, progress tracking, and the three per-job watchdogs (max-duration, inactivity, tool-silence).                          |
 | `src/jsonl-stream.ts` | The BOUNDS on a child CLI's streams, shared by both runners: `JsonlLineReader` frames its JSONL stdout while refusing to buffer a runaway record, `BoundedTail` keeps a capped tail of raw output for failure quoting. Both watchdog timers and the poll endpoints share one event loop with this parsing, so an unbounded buffer here is how a container stops answering polls with no watchdog having fired. |
 | `src/job.ts`       | Request types + validators for the job specs.                                                           |
@@ -387,8 +387,8 @@ self-contained.
 
 ## Published image (GHCR + Docker Hub)
 
-This package is published to npm (its zero-dependency `dist/server.js` is the
-entry `@cat-factory/local-server` spawns in local native mode). In addition, its
+This package is published to npm (its zero-dependency `dist/harness-server.js` is
+the entry `@cat-factory/local-server` spawns in local native mode). In addition, its
 **Docker image** is published publicly, multi-arch (`linux/amd64` +
 `linux/arm64`), to **both GHCR and Docker Hub** so anyone can pull it without
 building from source:

package/dist/agent-runner.js

@@ -14,6 +14,7 @@ import { codexImageGapNote, createCodexHome, disposeCodexHome } from './codex-ho
 import { ProgressGuard } from './progress-guard.js';
 import { BoundedTail, JsonlLineReader } from './jsonl-stream.js';
 import { killChildProcess, spawnDetached } from './process.js';
+import { abortReasonOf } from './failure.js';
 import { describeProcessExit } from './process-exit.js';
 import { redact, registerKnownSecrets, secretsToRedact } from './redact.js';
 import { createSliceTracker, startSubagentWatcher } from './subagents.js';
@@ -112,10 +113,19 @@ function streamCli(cli, prompt, opts, env, secrets, onEvent) {
                 });
             }
             if (aborted) {
-                // Carry the tail on the rejection so a caller that REPLACES this generic message with a
-                // more specific cause (the no-progress guard's diagnostic) can still append it — the
-                // stderr is often the only evidence of what the CLI was doing when it was killed.
-                reject(Object.assign(new Error('agent run aborted by watchdog'), { stderrTail }));
+                // SAY WHO ABORTED IT. Every abort reaches this branch, not just a watchdog's: the
+                // shutdown handler aborts every running job (`harness shutting down (SIGTERM)`) and so
+                // does a backend-requested stop. A watchdog kill is relabelled downstream from the
+                // structured `killReason`, so hard-coding "aborted by watchdog" here was wrong for
+                // exactly the aborts that have nothing else to say: a job killed because something
+                // shut the harness down reported a watchdog that never fired, which is a wrong lead in
+                // the one log an operator has. The reason rides `signal.reason` (see `runner.ts`'s
+                // `entry.abort`), the way `settlePiRun` already reads it on the Pi path.
+                //
+                // Carry the tail on the rejection so a caller that REPLACES this message with a more
+                // specific cause (the no-progress guard's diagnostic) can still append it: the stderr
+                // is often the only evidence of what the CLI was doing when it was killed.
+                reject(Object.assign(new Error(abortReasonOf(opts.signal)), { stderrTail }));
                 return;
             }
             if (code !== 0) {

package/dist/failure.d.ts

@@ -64,3 +64,14 @@ export declare function maxDurationAbortMessage(maxDurationMs: number): string;
  * is exactly why the inactivity watchdog never fired.
  */
 export declare function toolSilenceAbortMessage(toolSilenceMs: number): string;
+/**
+ * What an aborted CLI run says about WHY, read off the signal that killed it.
+ *
+ * Every abort funnels through one `AbortController` whose reason the caller supplies (a
+ * watchdog's own phrase, `harness shutting down (SIGTERM)`, a backend-requested stop), so the
+ * signal is the only place that distinction survives the kill. A watchdog abort is relabelled
+ * further downstream from the structured `killReason`, which is precisely why the fallback here
+ * must NOT name one: an abort with nothing else to say is not a timeout, and saying it was sends
+ * whoever reads the job's failure looking for a watchdog that never fired.
+ */
+export declare function abortReasonOf(signal: AbortSignal | undefined): string;

package/dist/failure.js

@@ -95,3 +95,35 @@ export function toolSilenceAbortMessage(toolSilenceMs) {
     return (`Aborted: the agent produced output but completed no tool call for ` +
         `${Math.round(toolSilenceMs / 1000)}s`);
 }
+/**
+ * What an aborted CLI run says about WHY, read off the signal that killed it.
+ *
+ * Every abort funnels through one `AbortController` whose reason the caller supplies (a
+ * watchdog's own phrase, `harness shutting down (SIGTERM)`, a backend-requested stop), so the
+ * signal is the only place that distinction survives the kill. A watchdog abort is relabelled
+ * further downstream from the structured `killReason`, which is precisely why the fallback here
+ * must NOT name one: an abort with nothing else to say is not a timeout, and saying it was sends
+ * whoever reads the job's failure looking for a watchdog that never fired.
+ */
+export function abortReasonOf(signal) {
+    const reason = signal?.reason;
+    if (isContentlessAbort(reason))
+        return 'agent run aborted';
+    return reason instanceof Error && reason.message.trim() ? reason.message : 'agent run aborted';
+}
+/**
+ * Whether an abort reason is the platform's OWN, i.e. the one a reasonless `abort()` supplies.
+ *
+ * Without this the fallback above is unreachable. `controller.abort()` with no argument does not
+ * leave `signal.reason` empty: it sets an `AbortError` DOMException, which on Node IS an `Error`
+ * and whose message is the contentless "This operation was aborted". So every abort that has
+ * nothing to say (the no-progress guard's, whose real diagnostic is folded in by its caller)
+ * surfaced that sentence instead, which reads like a quoted cause and names nothing.
+ *
+ * Keyed on the NAME rather than `instanceof DOMException`, so it holds wherever the class is not a
+ * global. A timeout abort (`AbortSignal.timeout`) keeps its own `TimeoutError` message, which does
+ * say something.
+ */
+function isContentlessAbort(reason) {
+    return reason instanceof Error && reason.name === 'AbortError';
+}

package/dist/harness-server.d.ts

@@ -0,0 +1,16 @@
+import { type IncomingMessage, type ServerResponse } from 'node:http';
+declare const server: import("node:http").Server<typeof IncomingMessage, typeof ServerResponse>;
+/**
+ * What this process calls itself once it is running, and the second half of the naming defence
+ * described in the header (the file name is the first).
+ *
+ * Setting it rewrites BOTH halves of what a pattern kill matches on Linux: `/proc/<pid>/cmdline`
+ * becomes this string in full, and `/proc/<pid>/comm` its first 15 characters. So neither
+ * `pkill -f 'node dist/…'` (cmdline) nor a bare `pkill node` (name) can name the harness, and a
+ * hand-rolled `/proc` sweep for the agent's own service finds only that service.
+ *
+ * It is deliberately NOT a path: an agent looking for what it started searches for what it
+ * started, and nothing an agent runs is called this.
+ */
+export declare const PROCESS_TITLE = "cat-factory-harness";
+export { server };

package/dist/{server.js → harness-server.js}

@@ -15,6 +15,14 @@ import { HARNESS_VERSION } from './version.js';
 // Nothing here holds long-lived secrets: the per-job GitHub + proxy tokens arrive
 // in the request body and live only for the duration of the job in an ephemeral
 // workspace.
+//
+// THE FILE NAME IS LOAD-BEARING, and so is {@link PROCESS_TITLE} below. This process is
+// PID 1 of the job container, running as the same uid as the agent's own shell, so any
+// pattern kill the agent runs can reach it. It used to be `dist/server.js`, which is
+// also what an ordinary Node service builds to: a coder run that had just smoke-tested
+// the service it wrote ran `pkill -f 'node dist/server.js'` to stop it, matched PID 1,
+// and shut the harness down mid-job. The engine could only see a container that
+// vanished, so it reported an eviction and re-dispatched into the same trap.
 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
@@ -185,8 +193,23 @@ const server = createServer((req, res) => {
         return send(res, 404, { error: 'not found' });
     })();
 });
+/**
+ * What this process calls itself once it is running, and the second half of the naming defence
+ * described in the header (the file name is the first).
+ *
+ * Setting it rewrites BOTH halves of what a pattern kill matches on Linux: `/proc/<pid>/cmdline`
+ * becomes this string in full, and `/proc/<pid>/comm` its first 15 characters. So neither
+ * `pkill -f 'node dist/…'` (cmdline) nor a bare `pkill node` (name) can name the harness, and a
+ * hand-rolled `/proc` sweep for the agent's own service finds only that service.
+ *
+ * It is deliberately NOT a path: an agent looking for what it started searches for what it
+ * started, and nothing an agent runs is called this.
+ */
+export const PROCESS_TITLE = 'cat-factory-harness';
 // Only auto-listen when run as the entry point (tests import handleRun directly).
 if (process.env.NODE_ENV !== 'test') {
+    // Before `listen`, so no job can be accepted while this process still answers to `node`.
+    process.title = PROCESS_TITLE;
     server.listen(PORT, BIND_HOST, () => {
         console.log(`executor-harness listening on ${BIND_HOST ?? ''}:${PORT}`);
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.120.0",
+  "version": "1.122.0",
   "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",
@@ -12,9 +12,9 @@
     "src"
   ],
   "type": "module",
-  "main": "./dist/server.js",
+  "main": "./dist/harness-server.js",
   "exports": {
-    ".": "./dist/server.js",
+    ".": "./dist/harness-server.js",
     "./embed": "./src/embed.ts",
     "./claude-call-aggregator": {
       "types": "./dist/claude-call-aggregator.d.ts",
@@ -30,14 +30,14 @@
     "hono": "^4.13.1",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/kernel": "0.299.1",
-    "@cat-factory/server": "0.286.0",
-    "@cat-factory/spend": "0.15.93"
+    "@cat-factory/kernel": "0.300.0",
+    "@cat-factory/server": "0.287.0",
+    "@cat-factory/spend": "0.15.94"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
-    "start": "node dist/server.js",
+    "start": "node dist/harness-server.js",
     "test": "vitest run",
     "test:run": "vitest run",
     "test:acceptance": "vitest run --config vitest.acceptance.config.ts",

package/src/agent-runner.ts

@@ -37,6 +37,7 @@ import { codexImageGapNote, createCodexHome, disposeCodexHome } from './codex-ho
 import { ProgressGuard, type ProgressGuardLimits } from './progress-guard.js'
 import { BoundedTail, JsonlLineReader } from './jsonl-stream.js'
 import { killChildProcess, spawnDetached } from './process.js'
+import { abortReasonOf } from './failure.js'
 import { describeProcessExit } from './process-exit.js'
 import { redact, registerKnownSecrets, secretsToRedact } from './redact.js'
 import { createSliceTracker, startSubagentWatcher, type SliceReview } from './subagents.js'
@@ -307,10 +308,19 @@ function streamCli(
         })
       }
       if (aborted) {
-        // Carry the tail on the rejection so a caller that REPLACES this generic message with a
-        // more specific cause (the no-progress guard's diagnostic) can still append it — the
-        // stderr is often the only evidence of what the CLI was doing when it was killed.
-        reject(Object.assign(new Error('agent run aborted by watchdog'), { stderrTail }))
+        // SAY WHO ABORTED IT. Every abort reaches this branch, not just a watchdog's: the
+        // shutdown handler aborts every running job (`harness shutting down (SIGTERM)`) and so
+        // does a backend-requested stop. A watchdog kill is relabelled downstream from the
+        // structured `killReason`, so hard-coding "aborted by watchdog" here was wrong for
+        // exactly the aborts that have nothing else to say: a job killed because something
+        // shut the harness down reported a watchdog that never fired, which is a wrong lead in
+        // the one log an operator has. The reason rides `signal.reason` (see `runner.ts`'s
+        // `entry.abort`), the way `settlePiRun` already reads it on the Pi path.
+        //
+        // Carry the tail on the rejection so a caller that REPLACES this message with a more
+        // specific cause (the no-progress guard's diagnostic) can still append it: the stderr
+        // is often the only evidence of what the CLI was doing when it was killed.
+        reject(Object.assign(new Error(abortReasonOf(opts.signal)), { stderrTail }))
         return
       }
       if (code !== 0) {

package/src/failure.ts

@@ -111,3 +111,36 @@ export function toolSilenceAbortMessage(toolSilenceMs: number): string {
     `${Math.round(toolSilenceMs / 1000)}s`
   )
 }
+
+/**
+ * What an aborted CLI run says about WHY, read off the signal that killed it.
+ *
+ * Every abort funnels through one `AbortController` whose reason the caller supplies (a
+ * watchdog's own phrase, `harness shutting down (SIGTERM)`, a backend-requested stop), so the
+ * signal is the only place that distinction survives the kill. A watchdog abort is relabelled
+ * further downstream from the structured `killReason`, which is precisely why the fallback here
+ * must NOT name one: an abort with nothing else to say is not a timeout, and saying it was sends
+ * whoever reads the job's failure looking for a watchdog that never fired.
+ */
+export function abortReasonOf(signal: AbortSignal | undefined): string {
+  const reason = signal?.reason
+  if (isContentlessAbort(reason)) return 'agent run aborted'
+  return reason instanceof Error && reason.message.trim() ? reason.message : 'agent run aborted'
+}
+
+/**
+ * Whether an abort reason is the platform's OWN, i.e. the one a reasonless `abort()` supplies.
+ *
+ * Without this the fallback above is unreachable. `controller.abort()` with no argument does not
+ * leave `signal.reason` empty: it sets an `AbortError` DOMException, which on Node IS an `Error`
+ * and whose message is the contentless "This operation was aborted". So every abort that has
+ * nothing to say (the no-progress guard's, whose real diagnostic is folded in by its caller)
+ * surfaced that sentence instead, which reads like a quoted cause and names nothing.
+ *
+ * Keyed on the NAME rather than `instanceof DOMException`, so it holds wherever the class is not a
+ * global. A timeout abort (`AbortSignal.timeout`) keeps its own `TimeoutError` message, which does
+ * say something.
+ */
+function isContentlessAbort(reason: unknown): boolean {
+  return reason instanceof Error && reason.name === 'AbortError'
+}

package/src/{server.ts → harness-server.ts}

@@ -16,6 +16,14 @@ import { HARNESS_VERSION } from './version.js'
 // Nothing here holds long-lived secrets: the per-job GitHub + proxy tokens arrive
 // in the request body and live only for the duration of the job in an ephemeral
 // workspace.
+//
+// THE FILE NAME IS LOAD-BEARING, and so is {@link PROCESS_TITLE} below. This process is
+// PID 1 of the job container, running as the same uid as the agent's own shell, so any
+// pattern kill the agent runs can reach it. It used to be `dist/server.js`, which is
+// also what an ordinary Node service builds to: a coder run that had just smoke-tested
+// the service it wrote ran `pkill -f 'node dist/server.js'` to stop it, matched PID 1,
+// and shut the harness down mid-job. The engine could only see a container that
+// vanished, so it reported an eviction and re-dispatched into the same trap.
 
 const PORT = Number(process.env.PORT ?? 8080)
 
@@ -202,8 +210,24 @@ const server = createServer((req, res) => {
   })()
 })
 
+/**
+ * What this process calls itself once it is running, and the second half of the naming defence
+ * described in the header (the file name is the first).
+ *
+ * Setting it rewrites BOTH halves of what a pattern kill matches on Linux: `/proc/<pid>/cmdline`
+ * becomes this string in full, and `/proc/<pid>/comm` its first 15 characters. So neither
+ * `pkill -f 'node dist/…'` (cmdline) nor a bare `pkill node` (name) can name the harness, and a
+ * hand-rolled `/proc` sweep for the agent's own service finds only that service.
+ *
+ * It is deliberately NOT a path: an agent looking for what it started searches for what it
+ * started, and nothing an agent runs is called this.
+ */
+export const PROCESS_TITLE = 'cat-factory-harness'
+
 // Only auto-listen when run as the entry point (tests import handleRun directly).
 if (process.env.NODE_ENV !== 'test') {
+  // Before `listen`, so no job can be accepted while this process still answers to `node`.
+  process.title = PROCESS_TITLE
   server.listen(PORT, BIND_HOST, () => {
     console.log(`executor-harness listening on ${BIND_HOST ?? ''}:${PORT}`)
   })

package/dist/server.d.ts

@@ -1,3 +0,0 @@
-import { type IncomingMessage, type ServerResponse } from 'node:http';
-declare const server: import("node:http").Server<typeof IncomingMessage, typeof ServerResponse>;
-export { server };