@cat-factory/executor-harness 1.139.1 → 1.141.0

package/README.md

@@ -4,7 +4,7 @@ The payload that runs **inside** a per-run Cloudflare Container (or a
 [self-hosted runner](https://github.com/kibertoad/cat-factory/blob/main/backend/docs/runner-pool-integration.md)) to perform real
 repo work with the [Pi coding agent](https://github.com/earendil-works/pi).
 
-It is a thin TypeScript wrapper (a `node:http` server on `:8080`) that the
+It is a thin TypeScript wrapper (a `node:http` server on `:27182`) that the
 Worker drives over a small **job protocol**. Jobs run **asynchronously**: a `POST`
 accepts the job and returns immediately with a `jobId`; the driver then polls
 `GET /jobs/{id}` for live progress and the terminal result.
@@ -442,7 +442,7 @@ verdict is stated.
 | `src/agent-shared.ts` | The few helpers every agent MODE shares (effort-report folding, the capability fields forwarded to `runAgentInWorkspace`). |
 | `src/logger.ts`    | Structured logging.                                                                                     |
 | `src/docker-status.ts` | This container's own verdict about its Docker daemon, as recorded by `entrypoint.sh`. Three-valued on purpose: a daemon that FAILED and a daemon nobody asked about are different facts, and only a DECIDED absence refuses a stand-up. See [Local infra: the container's Docker daemon](#local-infra-the-containers-docker-daemon). |
-| `src/agent-env.ts` | The env for anything the harness spawns into the agent's CHECKOUT: its own environment minus the variables that are facts about the HARNESS. Today that is `NODE_ENV` — the harness runs in production mode, and an inherited `NODE_ENV=production` makes npm omit devDependencies in a checkout that never asked for it. |
+| `src/agent-env.ts` | The env for anything the harness spawns into the agent's CHECKOUT: its own environment minus the variables that are facts about the HARNESS. Today that is `NODE_ENV` (the harness runs in production mode, and an inherited `NODE_ENV=production` makes npm omit devDependencies in a checkout that never asked for it) and `PORT` (the port this harness is listening on, so a service that reads it would bind the one address in the container's network namespace that is already taken). |
 
 ## Runner lifecycle knobs
 
@@ -451,7 +451,7 @@ runner):
 
 | Env var               | Default         | Effect                                                      |
 | --------------------- | --------------- | ----------------------------------------------------------- |
-| `PORT`                | `8080`          | HTTP port the harness listens on.                           |
+| `PORT`                | `27182`         | HTTP port the harness listens on. Deliberately not a port a service under test would pick: the harness shares the container's network namespace with the agent's own processes, and on `8080` it answered their health checks (see `src/harness-port.ts`). |
 | `JOB_MAX_DURATION_MS` | `3600000` (60m) | Hard ceiling on a job's wall-clock time; force-fails after. |
 | `JOB_INACTIVITY_MS`   | `600000` (10m)  | Kills a hung agent that produces no output for this long.   |
 | `JOB_TOOL_SILENCE_MS` | half `JOB_MAX_DURATION_MS` (30m at its default) | Kills an agent that keeps producing output but completes no tool call for this long: the "chatty hang" neither watchdog above can see, since streamed output resets the inactivity timer on every chunk while nothing gets done (stuck-run audit F13). Armed ONLY while an agent CLI that reports completed tool calls is running (each runner opens its own window and closes it on exit), so clone / dependency install / push / a validation loop's check commands sit outside it — they are activity-silent by nature and bounded by their own per-command timeouts — and each repair pass opens a fresh window. Derived from the job ceiling rather than fixed. It fires only when output arrived during the window that elapsed, which is what leaves a genuinely quiet run to `JOB_INACTIVITY_MS` and its clearer diagnostic. `0` disables it. |

package/dist/agent-env.d.ts

@@ -5,6 +5,17 @@
  * harness that a tool in the checkout will silently act on. It is not a sandbox (an agent can set
  * whatever it likes in its own shell) and not a secret filter (the harness holds per-job secrets
  * in `agentEnv`, never in `process.env`).
+ *
+ * `PORT` clears that bar the same way `NODE_ENV` does, and for the defect that moved the job
+ * server off 8080 in the first place. The port is handed to the container explicitly (the
+ * Kubernetes pod spec's `env`, the local adapters' `-e PORT=`, the native transport's per-process
+ * ephemeral port), so it sits in the harness's own environment, and `listen(process.env.PORT)` is
+ * the single most common way a service picks its port. Inherited, it aims the agent's own service
+ * at the one port in the namespace that is already taken: the service dies with `EADDRINUSE`, and
+ * a health check that also reads `$PORT` gets a 200 from the harness whose body begins
+ * `{"status":"ok"}`. That is the platform grading itself green in place of the product, which is
+ * exactly what moving the number was meant to stop, so moving it alone would have relocated the
+ * collision rather than closed it.
  */
 export declare const HARNESS_ONLY_ENV_NAMES: readonly string[];
 /**

package/dist/agent-env.js

@@ -4,10 +4,10 @@
 //
 // The rule this exists for: the harness process and the agent's checkout are two different
 // programs, and a few of the harness's own environment variables are actively wrong for the
-// second. `NODE_ENV=production` is the one that bit: npm reads it as `omit=dev`, so `npm install`
-// in a checkout silently skips devDependencies, leaving the agent with no test runner, no linter
-// and no build tool. One measured coder run spent six of its forty budgeted tool calls
-// discovering and undoing that (install, `npm ls`, `npm config get omit`, reinstall with
+// second. `NODE_ENV=production` is the one that bit first: npm reads it as `omit=dev`, so an
+// `npm install` in a checkout silently skips devDependencies, leaving the agent with no test
+// runner, no linter and no build tool. One measured coder run spent six of its forty budgeted
+// tool calls discovering and undoing that (install, `npm ls`, `npm config get omit`, reinstall with
 // `--include=dev`, re-check the bin directory, approve an install script) — all of it caused by a
 // variable the platform set, on a project the platform knows nothing about.
 //
@@ -26,8 +26,19 @@
  * harness that a tool in the checkout will silently act on. It is not a sandbox (an agent can set
  * whatever it likes in its own shell) and not a secret filter (the harness holds per-job secrets
  * in `agentEnv`, never in `process.env`).
+ *
+ * `PORT` clears that bar the same way `NODE_ENV` does, and for the defect that moved the job
+ * server off 8080 in the first place. The port is handed to the container explicitly (the
+ * Kubernetes pod spec's `env`, the local adapters' `-e PORT=`, the native transport's per-process
+ * ephemeral port), so it sits in the harness's own environment, and `listen(process.env.PORT)` is
+ * the single most common way a service picks its port. Inherited, it aims the agent's own service
+ * at the one port in the namespace that is already taken: the service dies with `EADDRINUSE`, and
+ * a health check that also reads `$PORT` gets a 200 from the harness whose body begins
+ * `{"status":"ok"}`. That is the platform grading itself green in place of the product, which is
+ * exactly what moving the number was meant to stop, so moving it alone would have relocated the
+ * collision rather than closed it.
  */
-export const HARNESS_ONLY_ENV_NAMES = ['NODE_ENV'];
+export const HARNESS_ONLY_ENV_NAMES = ['NODE_ENV', 'PORT'];
 /**
  * The child env for a command run in the agent's checkout: the harness's own environment minus
  * {@link HARNESS_ONLY_ENV_NAMES}, with each layer merged over it in order.

package/dist/environment-inventory.d.ts

@@ -52,6 +52,12 @@ export interface EnvironmentInventory {
      * "has not answered yet" is one of its answers (see {@link probeDockerDaemon}).
      */
     dockerDaemon: ToolPresence;
+    /**
+     * The port the harness's own job server holds in this network namespace. Not probed: the
+     * process reads its own {@link harnessListenPort}, which is the only honest answer when a
+     * deployment overrides `PORT` and the only one available before anything is listening.
+     */
+    harnessPort: number;
 }
 /**
  * The real runner: spawn the tool, bounded, and report what the spawn did.
@@ -113,6 +119,11 @@ export interface ProbeEnvironmentOptions {
      * both sides of the branch without an ambient environment variable deciding the outcome for it.
      */
     daemonExpected?: boolean;
+    /**
+     * The port the harness holds, defaulting to what this process is actually listening on. Injected
+     * only so the suite can assert the rendered line without an ambient `PORT` deciding its text.
+     */
+    harnessPort?: number;
 }
 /**
  * Probe the machine. EVERYTHING runs concurrently, the daemon included.

package/dist/environment-inventory.js

@@ -1,6 +1,7 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { log } from './logger.js';
+import { harnessListenPort } from './harness-port.js';
 // ---------------------------------------------------------------------------
 // What this machine actually has, probed ONCE per job and stated to the agent.
 //
@@ -261,7 +262,7 @@ export async function probeEnvironment(run, opts = {}) {
         }))),
         probeDockerDaemon(run, opts),
     ]);
-    return { tools, dockerDaemon };
+    return { tools, dockerDaemon, harnessPort: opts.harnessPort ?? harnessListenPort() };
 }
 /**
  * Ask the daemon itself, and do not mistake a daemon that is STARTING for one that is not there.
@@ -342,6 +343,7 @@ export function renderEnvironmentInventory(inventory) {
             `nor absent: ${unknown.join(', ')}.`);
     }
     lines.push(dockerDaemonLine(inventory.dockerDaemon));
+    lines.push(harnessPortLine(inventory.harnessPort));
     // Stated as a FACT and not as an errand. This block is appended to the system prompt after the
     // effort-report directive, whose closing sentences are the prompt's ordering rule (write the
     // sentinel, then reply, and no tool call after the reply). "Check for that one yourself before
@@ -352,6 +354,29 @@ export function renderEnvironmentInventory(inventory) {
         'rather than missing.');
     return lines.join('\n');
 }
+/**
+ * The one port line: what the platform already holds, and why a request to it is not evidence.
+ *
+ * Stated because the harness shares this network namespace with everything the agent starts, so a
+ * port it holds is a port the agent cannot have, and because the failure that follows is not a
+ * refusal but a WRONG ANSWER. The harness answers `/health` with a 200 whose body begins
+ * `{"status":"ok"}`, so a tester that probes the port its service was supposed to be on grades the
+ * platform green and says nothing. A run hit exactly that: the service under test was specified to
+ * listen on 8080, the harness held it, the app died with `EADDRINUSE`, and only a second route with
+ * a distinctive body gave the trap away.
+ *
+ * The default port has since moved out of the range anything reaches for by habit, which is the
+ * real fix. This line is what remains true whatever a deployment sets `PORT` to, and it names the
+ * NUMBER rather than the danger so an agent can pick another port up front instead of diagnosing a
+ * bind failure it did not cause.
+ */
+function harnessPortLine(port) {
+    return (`Port ${port} is already bound here, by the platform's harness process itself. Do not start ` +
+        'anything on it, and do not read what it serves as your own service: it answers requests, ' +
+        `including a 200 on \`/health\` with a JSON body that begins \`{"status":"ok"}\`, so a health ` +
+        'check aimed at it passes without your service ever having run. Bind anything you start ' +
+        'somewhere else.');
+}
 /** The Docker line, which says something different in each of the three cases. */
 function dockerDaemonLine(daemon) {
     if (daemon.status === 'present') {
@@ -387,6 +412,7 @@ export async function appendEnvironmentInventory(systemPrompt, opts = {}) {
         const inventory = await probeEnvironment(opts.run ?? spawnProbeRunner(opts.signal), {
             ...(opts.sleep ? { sleep: opts.sleep } : {}),
             ...(opts.daemonExpected === undefined ? {} : { daemonExpected: opts.daemonExpected }),
+            ...(opts.harnessPort === undefined ? {} : { harnessPort: opts.harnessPort }),
         });
         logger.info('agent: probed the environment', {
             installed: inventory.tools

package/dist/frontend-infra.js

@@ -4,6 +4,7 @@ import { writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { killChildProcess } from './process.js';
 import { agentChildEnv } from './agent-env.js';
+import { harnessListenPort } from './harness-port.js';
 import { pathExists } from './fs-utils.js';
 import { captureRedactedOutput, redactSecrets } from './redact.js';
 import { log } from './logger.js';
@@ -51,6 +52,38 @@ function guardProcess(child, label, logger) {
     });
     return child;
 }
+/**
+ * The refusal a configured serve port owes when it is the port this harness process is listening
+ * on, else `undefined`.
+ *
+ * The contracts-side guard (`resolveFrontendServePort`) already reserves the DEFAULT harness port,
+ * and that is the right rule where it lives: the backend derives the tester's allowed CORS origin
+ * from the same call, so both sides agree on one number. But it is a PREDICTION. A deployment sets
+ * `PORT` per pod and a Kubernetes runner pool carries its own `harnessPort`, so the port actually
+ * held here can be one the shared constant never named. This is the only place both facts are
+ * known, so it is the only place that can tell.
+ *
+ * It refuses rather than relocating, for the defect that moved the job server off 8080 in the first
+ * place: on a collision the serve dies with `EADDRINUSE` and the health check that follows gets a
+ * 200 from the HARNESS, so the stand-up would hand the agent a serving app that never started and
+ * the tester would grade the platform in its place. Serving somewhere else instead would be a
+ * second wrong answer, since the CORS origin the backend allows was derived from the port that was
+ * asked for. Naming the collision is what leaves a human something to re-pick.
+ */
+function harnessPortCollision(servePort, serveUrl, logger) {
+    const harnessPort = harnessListenPort();
+    if (servePort !== harnessPort)
+        return undefined;
+    logger.warn('agent(frontend): serve port collides with the harness port', {
+        servePort,
+        harnessPort,
+    });
+    return (`the frontend was not served: its configured port ${servePort} is the port this job's ` +
+        `harness is listening on, so the app could not bind it and a health check against ` +
+        `${serveUrl} would have been answered by the harness rather than the app. Report this as an ` +
+        `infra gap, not an app defect: the frame's serve port (or the runner pool's harness port) ` +
+        `has to change.`);
+}
 /**
  * Build the frontend, start WireMock, serve the built app and health-check both. Best-effort,
  * like the docker-compose stand-up: a failed build / server that never binds is surfaced to
@@ -95,6 +128,11 @@ export async function standUpFrontend(dir, infra, run, logger = log) {
             ...extra,
         };
     };
+    // Refused BEFORE the install/build spend: a serve port equal to the one this harness holds can
+    // never carry the app, and would be GRADED as if it did.
+    const collision = harnessPortCollision(servePort, serveUrl, logger);
+    if (collision)
+        return { processes, note: collision, record: record({ error: collision }) };
     const buildEnv = (infra.envInjection ?? DEFAULTS.envInjection) === 'build' ? (infra.env ?? {}) : {};
     // The job's own env (see `RunOptions.agentEnv`) — today the private-registry npmrc pointer.
     // The stand-up is spawned by the HARNESS, not by the agent, so it does not inherit whatever the

package/dist/harness-port.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The default in-container port, and deliberately NOT 8080.
+ *
+ * The harness is PID 1 of the job container and shares the network namespace with everything the
+ * agent starts, so whatever port it holds is a port the agent cannot have. On 8080 that collision
+ * was not merely inconvenient, it was a WRONG ANSWER: 8080 is the most common default for a
+ * containerised HTTP service, so a service under test started there died with `EADDRINUSE`, and a
+ * tester that then probed `http://127.0.0.1:8080/health` got a 200 from the harness whose body
+ * begins `{"status":"ok"}`. Every ordinary health assertion (a substring match, `status === 'ok'`,
+ * a 200-check) passes against the platform instead of the product, and the run is graded green on
+ * a service that never started.
+ *
+ * The value is arbitrary within three constraints, and only the constraints matter:
+ *
+ *   - above 1023, since the harness runs unprivileged;
+ *   - nowhere near the ports a developer or an agent reaches for by habit (3000, 4173, 5000, 8000,
+ *     8080, 8081, 8443, 8888, 9000, …), which is what rules out the whole low band;
+ *   - below 32768, the floor of Linux's default ephemeral range, so an OUTBOUND connection from
+ *     the agent's own processes can never already hold it when the harness starts.
+ *
+ * Changing it is an image change: the transports address the harness at
+ * `@cat-factory/contracts`' `HARNESS_JOB_PORT`, which `harness-contract.conformity.test.ts` pins
+ * to this number, and a deployment's own runner pool publishes it pod-side.
+ */
+export declare const DEFAULT_HARNESS_PORT = 27182;
+/**
+ * The port this process actually listens on: `PORT` when the deployment sets one (the native local
+ * transport picks an ephemeral port per harness process and passes it that way), else the default.
+ */
+export declare function harnessListenPort(env?: NodeJS.ProcessEnv): number;

package/dist/harness-port.js

@@ -0,0 +1,38 @@
+// The port the harness's own job HTTP server binds inside the job container, and the one fact
+// about it the rest of the harness needs.
+//
+// It is its own module because two unrelated things read it: `harness-server.ts`, which binds it,
+// and `environment-inventory.ts`, which STATES it to the agent. Reading it back off the server
+// module would make the inventory import the process that imports the agent.
+/**
+ * The default in-container port, and deliberately NOT 8080.
+ *
+ * The harness is PID 1 of the job container and shares the network namespace with everything the
+ * agent starts, so whatever port it holds is a port the agent cannot have. On 8080 that collision
+ * was not merely inconvenient, it was a WRONG ANSWER: 8080 is the most common default for a
+ * containerised HTTP service, so a service under test started there died with `EADDRINUSE`, and a
+ * tester that then probed `http://127.0.0.1:8080/health` got a 200 from the harness whose body
+ * begins `{"status":"ok"}`. Every ordinary health assertion (a substring match, `status === 'ok'`,
+ * a 200-check) passes against the platform instead of the product, and the run is graded green on
+ * a service that never started.
+ *
+ * The value is arbitrary within three constraints, and only the constraints matter:
+ *
+ *   - above 1023, since the harness runs unprivileged;
+ *   - nowhere near the ports a developer or an agent reaches for by habit (3000, 4173, 5000, 8000,
+ *     8080, 8081, 8443, 8888, 9000, …), which is what rules out the whole low band;
+ *   - below 32768, the floor of Linux's default ephemeral range, so an OUTBOUND connection from
+ *     the agent's own processes can never already hold it when the harness starts.
+ *
+ * Changing it is an image change: the transports address the harness at
+ * `@cat-factory/contracts`' `HARNESS_JOB_PORT`, which `harness-contract.conformity.test.ts` pins
+ * to this number, and a deployment's own runner pool publishes it pod-side.
+ */
+export const DEFAULT_HARNESS_PORT = 27182;
+/**
+ * The port this process actually listens on: `PORT` when the deployment sets one (the native local
+ * transport picks an ephemeral port per harness process and passes it that way), else the default.
+ */
+export function harnessListenPort(env = process.env) {
+    return Number(env.PORT ?? DEFAULT_HARNESS_PORT);
+}

package/dist/harness-server.js

@@ -6,6 +6,7 @@ import { handleAgent } from './agent.js';
 import { handleInline } from './inline.js';
 import { redactSecrets } from './git.js';
 import { readDockerStatus } from './docker-status.js';
+import { harnessListenPort } from './harness-port.js';
 import { JobRegistry, loadRunnerLimits } from './runner.js';
 import { log } from './logger.js';
 import { HARNESS_VERSION } from './version.js';
@@ -24,7 +25,7 @@ import { HARNESS_VERSION } from './version.js';
 // 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);
+const PORT = harnessListenPort();
 // 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.139.1",
+  "version": "1.141.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",
@@ -25,9 +25,10 @@
     "access": "public"
   },
   "devDependencies": {
-    "@cat-factory/kernel": "0.321.1",
-    "@cat-factory/server": "0.307.0",
-    "@cat-factory/spend": "0.16.18",
+    "@cat-factory/contracts": "0.332.0",
+    "@cat-factory/kernel": "0.321.3",
+    "@cat-factory/server": "0.307.2",
+    "@cat-factory/spend": "0.16.20",
     "@hono/node-server": "^2.1.1",
     "@types/node": "^26.2.0",
     "hono": "^4.13.4",

package/src/agent-env.ts

@@ -4,10 +4,10 @@
 //
 // The rule this exists for: the harness process and the agent's checkout are two different
 // programs, and a few of the harness's own environment variables are actively wrong for the
-// second. `NODE_ENV=production` is the one that bit: npm reads it as `omit=dev`, so `npm install`
-// in a checkout silently skips devDependencies, leaving the agent with no test runner, no linter
-// and no build tool. One measured coder run spent six of its forty budgeted tool calls
-// discovering and undoing that (install, `npm ls`, `npm config get omit`, reinstall with
+// second. `NODE_ENV=production` is the one that bit first: npm reads it as `omit=dev`, so an
+// `npm install` in a checkout silently skips devDependencies, leaving the agent with no test
+// runner, no linter and no build tool. One measured coder run spent six of its forty budgeted
+// tool calls discovering and undoing that (install, `npm ls`, `npm config get omit`, reinstall with
 // `--include=dev`, re-check the bin directory, approve an install script) — all of it caused by a
 // variable the platform set, on a project the platform knows nothing about.
 //
@@ -27,8 +27,19 @@
  * harness that a tool in the checkout will silently act on. It is not a sandbox (an agent can set
  * whatever it likes in its own shell) and not a secret filter (the harness holds per-job secrets
  * in `agentEnv`, never in `process.env`).
+ *
+ * `PORT` clears that bar the same way `NODE_ENV` does, and for the defect that moved the job
+ * server off 8080 in the first place. The port is handed to the container explicitly (the
+ * Kubernetes pod spec's `env`, the local adapters' `-e PORT=`, the native transport's per-process
+ * ephemeral port), so it sits in the harness's own environment, and `listen(process.env.PORT)` is
+ * the single most common way a service picks its port. Inherited, it aims the agent's own service
+ * at the one port in the namespace that is already taken: the service dies with `EADDRINUSE`, and
+ * a health check that also reads `$PORT` gets a 200 from the harness whose body begins
+ * `{"status":"ok"}`. That is the platform grading itself green in place of the product, which is
+ * exactly what moving the number was meant to stop, so moving it alone would have relocated the
+ * collision rather than closed it.
  */
-export const HARNESS_ONLY_ENV_NAMES: readonly string[] = ['NODE_ENV']
+export const HARNESS_ONLY_ENV_NAMES: readonly string[] = ['NODE_ENV', 'PORT']
 
 /**
  * The child env for a command run in the agent's checkout: the harness's own environment minus

package/src/environment-inventory.ts

@@ -1,6 +1,7 @@
 import { execFile } from 'node:child_process'
 import { promisify } from 'node:util'
 import { log, type Logger } from './logger.js'
+import { harnessListenPort } from './harness-port.js'
 
 // ---------------------------------------------------------------------------
 // What this machine actually has, probed ONCE per job and stated to the agent.
@@ -85,6 +86,12 @@ export interface EnvironmentInventory {
    * "has not answered yet" is one of its answers (see {@link probeDockerDaemon}).
    */
   dockerDaemon: ToolPresence
+  /**
+   * The port the harness's own job server holds in this network namespace. Not probed: the
+   * process reads its own {@link harnessListenPort}, which is the only honest answer when a
+   * deployment overrides `PORT` and the only one available before anything is listening.
+   */
+  harnessPort: number
 }
 
 /**
@@ -298,6 +305,11 @@ export interface ProbeEnvironmentOptions {
    * both sides of the branch without an ambient environment variable deciding the outcome for it.
    */
   daemonExpected?: boolean
+  /**
+   * The port the harness holds, defaulting to what this process is actually listening on. Injected
+   * only so the suite can assert the rendered line without an ambient `PORT` deciding its text.
+   */
+  harnessPort?: number
 }
 
 /**
@@ -336,7 +348,7 @@ export async function probeEnvironment(
     ),
     probeDockerDaemon(run, opts),
   ])
-  return { tools, dockerDaemon }
+  return { tools, dockerDaemon, harnessPort: opts.harnessPort ?? harnessListenPort() }
 }
 
 /**
@@ -430,6 +442,7 @@ export function renderEnvironmentInventory(inventory: EnvironmentInventory): str
     )
   }
   lines.push(dockerDaemonLine(inventory.dockerDaemon))
+  lines.push(harnessPortLine(inventory.harnessPort))
   // Stated as a FACT and not as an errand. This block is appended to the system prompt after the
   // effort-report directive, whose closing sentences are the prompt's ordering rule (write the
   // sentinel, then reply, and no tool call after the reply). "Check for that one yourself before
@@ -443,6 +456,32 @@ export function renderEnvironmentInventory(inventory: EnvironmentInventory): str
   return lines.join('\n')
 }
 
+/**
+ * The one port line: what the platform already holds, and why a request to it is not evidence.
+ *
+ * Stated because the harness shares this network namespace with everything the agent starts, so a
+ * port it holds is a port the agent cannot have, and because the failure that follows is not a
+ * refusal but a WRONG ANSWER. The harness answers `/health` with a 200 whose body begins
+ * `{"status":"ok"}`, so a tester that probes the port its service was supposed to be on grades the
+ * platform green and says nothing. A run hit exactly that: the service under test was specified to
+ * listen on 8080, the harness held it, the app died with `EADDRINUSE`, and only a second route with
+ * a distinctive body gave the trap away.
+ *
+ * The default port has since moved out of the range anything reaches for by habit, which is the
+ * real fix. This line is what remains true whatever a deployment sets `PORT` to, and it names the
+ * NUMBER rather than the danger so an agent can pick another port up front instead of diagnosing a
+ * bind failure it did not cause.
+ */
+function harnessPortLine(port: number): string {
+  return (
+    `Port ${port} is already bound here, by the platform's harness process itself. Do not start ` +
+    'anything on it, and do not read what it serves as your own service: it answers requests, ' +
+    `including a 200 on \`/health\` with a JSON body that begins \`{"status":"ok"}\`, so a health ` +
+    'check aimed at it passes without your service ever having run. Bind anything you start ' +
+    'somewhere else.'
+  )
+}
+
 /** The Docker line, which says something different in each of the three cases. */
 function dockerDaemonLine(daemon: ToolPresence): string {
   if (daemon.status === 'present') {
@@ -488,6 +527,7 @@ export async function appendEnvironmentInventory(
     const inventory = await probeEnvironment(opts.run ?? spawnProbeRunner(opts.signal), {
       ...(opts.sleep ? { sleep: opts.sleep } : {}),
       ...(opts.daemonExpected === undefined ? {} : { daemonExpected: opts.daemonExpected }),
+      ...(opts.harnessPort === undefined ? {} : { harnessPort: opts.harnessPort }),
     })
     logger.info('agent: probed the environment', {
       installed: inventory.tools

package/src/frontend-infra.ts

@@ -6,6 +6,7 @@ import type { FrontendInfraSpec, InfraSetupRecord } from './job.js'
 import type { RunOptions } from './runner.js'
 import { killChildProcess } from './process.js'
 import { agentChildEnv } from './agent-env.js'
+import { harnessListenPort } from './harness-port.js'
 import { pathExists } from './fs-utils.js'
 import { captureRedactedOutput, redactSecrets } from './redact.js'
 import { log, type Logger } from './logger.js'
@@ -70,6 +71,44 @@ function guardProcess(child: ChildProcess, label: string, logger: Logger): Child
   return child
 }
 
+/**
+ * The refusal a configured serve port owes when it is the port this harness process is listening
+ * on, else `undefined`.
+ *
+ * The contracts-side guard (`resolveFrontendServePort`) already reserves the DEFAULT harness port,
+ * and that is the right rule where it lives: the backend derives the tester's allowed CORS origin
+ * from the same call, so both sides agree on one number. But it is a PREDICTION. A deployment sets
+ * `PORT` per pod and a Kubernetes runner pool carries its own `harnessPort`, so the port actually
+ * held here can be one the shared constant never named. This is the only place both facts are
+ * known, so it is the only place that can tell.
+ *
+ * It refuses rather than relocating, for the defect that moved the job server off 8080 in the first
+ * place: on a collision the serve dies with `EADDRINUSE` and the health check that follows gets a
+ * 200 from the HARNESS, so the stand-up would hand the agent a serving app that never started and
+ * the tester would grade the platform in its place. Serving somewhere else instead would be a
+ * second wrong answer, since the CORS origin the backend allows was derived from the port that was
+ * asked for. Naming the collision is what leaves a human something to re-pick.
+ */
+function harnessPortCollision(
+  servePort: number,
+  serveUrl: string,
+  logger: Logger,
+): string | undefined {
+  const harnessPort = harnessListenPort()
+  if (servePort !== harnessPort) return undefined
+  logger.warn('agent(frontend): serve port collides with the harness port', {
+    servePort,
+    harnessPort,
+  })
+  return (
+    `the frontend was not served: its configured port ${servePort} is the port this job's ` +
+    `harness is listening on, so the app could not bind it and a health check against ` +
+    `${serveUrl} would have been answered by the harness rather than the app. Report this as an ` +
+    `infra gap, not an app defect: the frame's serve port (or the runner pool's harness port) ` +
+    `has to change.`
+  )
+}
+
 /**
  * Build the frontend, start WireMock, serve the built app and health-check both. Best-effort,
  * like the docker-compose stand-up: a failed build / server that never binds is surfaced to
@@ -118,6 +157,11 @@ export async function standUpFrontend(
     }
   }
 
+  // Refused BEFORE the install/build spend: a serve port equal to the one this harness holds can
+  // never carry the app, and would be GRADED as if it did.
+  const collision = harnessPortCollision(servePort, serveUrl, logger)
+  if (collision) return { processes, note: collision, record: record({ error: collision }) }
+
   const buildEnv =
     (infra.envInjection ?? DEFAULTS.envInjection) === 'build' ? (infra.env ?? {}) : {}
   // The job's own env (see `RunOptions.agentEnv`) — today the private-registry npmrc pointer.

package/src/harness-port.ts

@@ -0,0 +1,40 @@
+// The port the harness's own job HTTP server binds inside the job container, and the one fact
+// about it the rest of the harness needs.
+//
+// It is its own module because two unrelated things read it: `harness-server.ts`, which binds it,
+// and `environment-inventory.ts`, which STATES it to the agent. Reading it back off the server
+// module would make the inventory import the process that imports the agent.
+
+/**
+ * The default in-container port, and deliberately NOT 8080.
+ *
+ * The harness is PID 1 of the job container and shares the network namespace with everything the
+ * agent starts, so whatever port it holds is a port the agent cannot have. On 8080 that collision
+ * was not merely inconvenient, it was a WRONG ANSWER: 8080 is the most common default for a
+ * containerised HTTP service, so a service under test started there died with `EADDRINUSE`, and a
+ * tester that then probed `http://127.0.0.1:8080/health` got a 200 from the harness whose body
+ * begins `{"status":"ok"}`. Every ordinary health assertion (a substring match, `status === 'ok'`,
+ * a 200-check) passes against the platform instead of the product, and the run is graded green on
+ * a service that never started.
+ *
+ * The value is arbitrary within three constraints, and only the constraints matter:
+ *
+ *   - above 1023, since the harness runs unprivileged;
+ *   - nowhere near the ports a developer or an agent reaches for by habit (3000, 4173, 5000, 8000,
+ *     8080, 8081, 8443, 8888, 9000, …), which is what rules out the whole low band;
+ *   - below 32768, the floor of Linux's default ephemeral range, so an OUTBOUND connection from
+ *     the agent's own processes can never already hold it when the harness starts.
+ *
+ * Changing it is an image change: the transports address the harness at
+ * `@cat-factory/contracts`' `HARNESS_JOB_PORT`, which `harness-contract.conformity.test.ts` pins
+ * to this number, and a deployment's own runner pool publishes it pod-side.
+ */
+export const DEFAULT_HARNESS_PORT = 27182
+
+/**
+ * The port this process actually listens on: `PORT` when the deployment sets one (the native local
+ * transport picks an ephemeral port per harness process and passes it that way), else the default.
+ */
+export function harnessListenPort(env: NodeJS.ProcessEnv = process.env): number {
+  return Number(env.PORT ?? DEFAULT_HARNESS_PORT)
+}

package/src/harness-server.ts

@@ -6,6 +6,7 @@ import { handleAgent } from './agent.js'
 import { handleInline } from './inline.js'
 import { redactSecrets } from './git.js'
 import { readDockerStatus } from './docker-status.js'
+import { harnessListenPort } from './harness-port.js'
 import { JobRegistry, loadRunnerLimits, type JobResultBase, type RunOptions } from './runner.js'
 import { log } from './logger.js'
 import { HARNESS_VERSION } from './version.js'
@@ -26,7 +27,7 @@ import { HARNESS_VERSION } from './version.js'
 // 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)
+const PORT = harnessListenPort()
 
 // 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