harness-everything 0.21.0 → 0.22.1

package/docs/platform-capabilities.md

@@ -129,5 +129,13 @@ structural floor. Canonical and packaged runtime copies use the same
 contract; this establishes no new live-host capability. Python, PyTorch and a
 compatible local checkpoint are optional external dependencies, not npm payloads;
 the explicit `npm run system-one:install` sets them up and hooks never run it.
+With `transport: "resident"`, an opted-in router hook may spawn one detached
+loopback-only Python server per manifest. One retained Windows + Claude Code
+headless session showed the hook-spawned server outliving the host; macOS/Linux
+and Codex hosts are not live-verified, and this does not change the matrix.
+Hooks read the mode from the host process environment: Claude Code settings
+`env` reaches hooks and every agent-run command, while a Codex started from an
+ordinary terminal sees it only when set at user/OS level. Keep the mode `off`
+until a Harness-trained checkpoint passes the rollout gates.
 Public Skills-only artifacts do not acquire lifecycle hooks from this feature.
 See [System One routing](system-one-routing.md) for limits, rollback and evidence.

package/docs/system-one-routing.md

@@ -68,10 +68,13 @@ installs the pinned `cua_s1` Git URL. It downloads the `cua-ai/cua-s1-forms`
 safetensors weights and JSON sidecar at Hugging Face revision
 `f54adbf447f4ca6ec259f529ee3f2e3e09f8cc71`, verifies pinned sizes and SHA-256
 before an atomic write (the pickle `.pt` is never fetched), and writes
-`<dir>/manifest.json` with `timeoutMs: 10000`. The default `<dir>` is
+`<dir>/manifest.json` with `timeoutMs: 10000`, `transport: "resident"` and
+`idleTimeoutMs: 1800000`. The default `<dir>` is
 `~/.agents/harness-everything/system-one`; `--dir` takes an absolute path and
 `--dry-run` prints the plan without changes. Acceptance requires a `pinned`
-provenance probe and one real CPU inference; otherwise the exit code is 1.
+provenance probe and one real warm CPU inference through a resident server that
+the installer starts and then stops; otherwise the exit code is 1. Child-process
+output goes to stderr; stdout carries only the JSON report.
 Torch/numpy/safetensors versions resolve at install time and are recorded by
 the probe. The installer does not change the router mode: it prints
 `HARNESS_SYSTEM_ONE_MODE=shadow` and the manifest path for the host
@@ -88,13 +91,93 @@ No prompts or model values are written to disk or echoed in error messages.
 
 The Node transport has a hard timeout and a 1 MiB stdout/stderr bound; it kills
 the direct child on timeout. It starts one short-lived Python process per score
-request. This is an evaluation bridge, not a warm, persistent low-latency server.
+request. This is the default `oneshot` transport, not a warm server; see the
+resident provider below.
 The process cannot execute actions and is not given a CUA driver. Failures return
 `{status: 'unavailable', reason}` with a bounded reason code; malformed score
 responses are checked by Phase 0. Transport fixtures prove IPC and failure
 handling only. Real checkpoint inference and measured CPU latency remain a
 separate gate, with explicit unavailable evidence if dependencies are absent.
 
+## Resident provider (Phase 4 prerequisite)
+
+The one-shot bridge pays Python start, `import torch` and checkpoint load on every
+call (measured ≈5 s on CPU); warm in-process inference is a few milliseconds. The
+manifest may set `transport: "resident"` (default `"oneshot"`) and optional
+`idleTimeoutMs` (60000–14400000, default 1800000) to keep one verified model in
+memory. Other manifest rules are unchanged; the timeout remains one-shot only.
+
+**Lifecycle.** A resident-mode score never blocks on model loading. If no live
+server exists, the Node provider creates a start lock with exclusive-create,
+spawns `cua_adapter.py --serve` detached with the configured Python (no shell),
+and returns `unavailable/provider-starting`, so the lexical route is used for
+that prompt. Concurrent callers seeing a lock younger than 60 s do not spawn
+again. The server verifies artifact hashes before `load_checkpoint`, writes its
+state file atomically, then removes the lock. A startup failure writes a bounded
+reason into the lock and exits; callers report `provider-unavailable` without
+respawning until the lock is 60 s old. An executable that cannot be spawned at
+all is detected synchronously (no child PID) and recorded as `spawn-failed` the
+same way. The server exits after `idleTimeoutMs` without requests, on
+`shutdown`, when either checkpoint file's size or modification time changes
+(`artifact-changed`), or as soon as its state file no longer names its PID and
+token (replaced, corrupted or deleted), so an undiscoverable server never
+lingers as an orphan. It deletes only a state file that still names it.
+
+**Files.** State and lock live beside the manifest as
+`system-one-resident-<digest>.json` / `.starting`, where `<digest>` is the first
+16 hex digits of SHA-256 of the parsed manifest re-serialized with `JSON.stringify`
+(file key order). Editing the manifest
+therefore selects a new server; the old one exits when idle. The state file has
+exactly `schemaVersion: 1`, `pid`, `port`, `token` (64 hex), and `startedAt`, and
+is created with mode 0600; on Windows the file instead receives an explicit
+DACL with inheritance removed and a single full-control entry for the current
+user's SID before the token is written. The manifest directory must still be
+writable only by that user: whoever can replace files there can redirect the
+client, and whoever can edit the manifest chooses the executable.
+
+**Protocol.** The server binds only `127.0.0.1` on an ephemeral port and handles
+one request per connection: one newline-terminated JSON object of at most 2 MiB
+with `token`, `op` (`score`, `ping`, `shutdown`) and, for `score`, a request with
+the exact Phase 0 structure (fields, lowercase IDs, unique options, 2–256
+options, 64-hex fingerprints). Connections are served concurrently, up to 64, each
+with a 1 s read deadline; beyond that the reply is `busy`. Inference itself is
+serialized, so a silent or slow client cannot delay other callers. Tokens are compared in constant time; a mismatch returns
+`{ok: false, reason: "unauthorized"}`. `score` applies the same byte limits
+(no truncation) and returns `{ok: true, response}` in the Phase 0 response
+format, which Phase 0 validation still checks. Any other failure returns
+`{ok: false, reason}` with a bounded code; no prompt, traceback, path or score is
+echoed in errors. The server never executes actions and is not given a driver.
+
+**Client.** The hook entry pre-scores asynchronously. When `tier-router.js` runs
+as a script (the kernel and packaged hooks spawn it) in `shadow` or `prefer`
+mode, it builds the fixed-catalog tier request before routing and makes one
+direct async loopback round trip (`scoreAsync`), with no worker thread. Start,
+lock, stale-state, deadline (1000 ms) and reply-limit (1 MiB) rules are the same
+as the synchronous path. The router uses the pre-scored result only when its
+request hash equals the request the router builds; otherwise it scores
+synchronously. A pre-score error is reported exactly as a synchronous scorer
+error would be. In `off` mode the entry neither pre-scores nor contacts a
+provider. The synchronous `score` API remains for programmatic callers: it
+makes the same round trip on a worker thread and waits with `Atomics.wait`.
+Starting that worker costs 29–41 ms per call on the reference host, which is why
+the hook avoids it. The paired measurements are in
+[cua-s1-forms-resident-async-cpu-2026-09-23](../benchmarks/results/system-one/cua-s1-forms-resident-async-cpu-2026-09-23/README.md).
+Both paths map results to the existing reasons: timeout → `provider-timeout` (no respawn);
+refused connection or dead PID → stale state removed and a new start
+(`provider-starting`); `unauthorized` → `provider-unavailable`; any other
+server-declined request → `provider-exit`; malformed replies → `provider-json`.
+
+**Operators.** `node harness-everything/scripts/system-one/resident.js
+start|status|stop <absolute manifest>` controls a server explicitly; `start`
+waits up to 60 s for readiness. The evaluation CLI waits for readiness before
+measuring, so resident runs are recorded with `coldStart: false`. It times
+`scoreAsync`, the path the hook uses, so `warmLatency` measures what a prompt
+actually pays. The installer
+writes `transport: "resident"`, verifies one resident score, and stops the server
+it started. Repository tests use a stub scorer behind the real server/protocol
+code; they prove the mechanism, not host survival of detached processes or model
+quality. Those require retained evidence.
+
 ## Phase 2: tier integration and rollback
 
 Set `HARNESS_SYSTEM_ONE_MODE=off|shadow|prefer` in the host environment. Default
@@ -126,6 +209,11 @@ selected candidate, model identity, confidence and margin; it omits prompt text,
 score vectors and artifact paths. The existing router contract schema is unchanged.
 Kernel/packaged entry points inherit these host environment variables. Prompts
 and hook payload fields cannot set model configuration or launch executables.
+Claude Code settings `env` is hot-reloaded and reaches hooks and every command
+the agent runs; Codex hooks inherit the `codex` process environment, so a Codex
+started from an ordinary terminal needs user/OS-level variables (which then apply
+to every program the user starts). The recommended setting is `off` until a
+`harness-routing-v1` checkpoint passes the rollout gates.
 Repository tests establish mechanism/package evidence only; actual host loading
 and semantic quality remain unverified until retained sessions demonstrate them.
 

package/evals/pilot-router-nonsoftware/graders/no-tier-language.md

@@ -0,0 +1,6 @@
+---
+type: regex
+pattern: '(Tier 1|Tier 2|Tier 3|Routing Checkpoint)'
+match: not_contains
+weight: 1
+---

package/evals/pilot-router-nonsoftware/graders/skill-not-fired.md

@@ -0,0 +1,9 @@
+---
+type: tool_used
+tool: Skill
+input_match: '"skill"\s*:\s*"(?:[\w-]+:)?harness-everything"'
+min: 0
+max: 0
+arm: both
+weight: 1
+---

package/evals/pilot-router-nonsoftware/prompt.md

@@ -0,0 +1,8 @@
+---
+max_turns: 10
+allowed_tools: [Read, Glob, Grep, Skill]
+tags: [pilot, negative-trigger]
+description: "Casual non-software small talk must not engage the harness-everything router."
+---
+
+What's the difference between latte and cappuccino?

package/evals/pilot-router-tier3/graders/skill-fired.md

@@ -0,0 +1,6 @@
+---
+type: tool_used
+tool: Skill
+input_match: '"skill"\s*:\s*"(?:[\w-]+:)?harness-everything"'
+weight: 1
+---

package/evals/pilot-router-tier3/prompt.md

@@ -0,0 +1,8 @@
+---
+max_turns: 15
+allowed_tools: [Read, Glob, Grep, Skill]
+tags: [pilot, positive-trigger, tier-3]
+description: "Architectural, repo-wide request should route through the harness-everything router and land on Tier 3."
+---
+
+Route this coding request: split our monolith into two services (orders and billing) with an event bus between them; this touches deployment, data migration, and every team's code.

package/evals/pilot-tdd-bugfix/graders/skill-fired.md

@@ -0,0 +1,6 @@
+---
+type: tool_used
+tool: Skill
+input_match: '"skill"\s*:\s*"(?:[\w-]+:)?tdd"'
+weight: 1
+---

package/evals/pilot-tdd-bugfix/prompt.md

@@ -0,0 +1,8 @@
+---
+max_turns: 15
+allowed_tools: [Read, Glob, Grep, Skill]
+tags: [pilot, positive-trigger]
+description: "A bug-fix request that asks for a regression test should engage the tdd skill's RED/GREEN loop."
+---
+
+Fix a bug with a regression test: the discount calculation rounds wrong for prices ending in .99.

package/evals/pilot-tdd-trivia/graders/no-red-phase-claim.md

@@ -0,0 +1,7 @@
+---
+type: regex
+pattern: '(writing a failing test now|entering RED)'
+flags: i
+match: not_contains
+weight: 1
+---

package/evals/pilot-tdd-trivia/graders/skill-not-fired.md

@@ -0,0 +1,9 @@
+---
+type: tool_used
+tool: Skill
+input_match: '"skill"\s*:\s*"(?:[\w-]+:)?tdd"'
+min: 0
+max: 0
+arm: both
+weight: 1
+---

package/evals/pilot-tdd-trivia/prompt.md

@@ -0,0 +1,8 @@
+---
+max_turns: 10
+allowed_tools: [Read, Glob, Grep, Skill]
+tags: [pilot, negative-trigger]
+description: "A one-line trivia question about TDD terminology must not start a RED/GREEN test-writing loop."
+---
+
+In one sentence, what does the RED phase of test-driven development mean?

package/evals/pilot-verify-discussion/graders/no-verification-claim.md

@@ -0,0 +1,7 @@
+---
+type: regex
+pattern: '(running the verification report|verification passed)'
+flags: i
+match: not_contains
+weight: 1
+---

package/evals/pilot-verify-discussion/graders/skill-not-fired.md

@@ -0,0 +1,9 @@
+---
+type: tool_used
+tool: Skill
+input_match: '"skill"\s*:\s*"(?:[\w-]+:)?verification-loop"'
+min: 0
+max: 0
+arm: both
+weight: 1
+---

package/evals/pilot-verify-discussion/prompt.md

@@ -0,0 +1,8 @@
+---
+max_turns: 10
+allowed_tools: [Read, Glob, Grep, Skill]
+tags: [pilot, negative-trigger]
+description: "A design discussion with no completed work must not launch the verification-loop skill."
+---
+
+Sketch two possible approaches for caching API responses and list trade-offs. Don't write any code yet.

package/evals/pilot-verify-preship/graders/skill-fired.md

@@ -0,0 +1,6 @@
+---
+type: tool_used
+tool: Skill
+input_match: '"skill"\s*:\s*"(?:[\w-]+:)?verification-loop"'
+weight: 1
+---

package/evals/pilot-verify-preship/prompt.md

@@ -0,0 +1,8 @@
+---
+max_turns: 15
+allowed_tools: [Read, Glob, Grep, Skill]
+tags: [pilot, positive-trigger]
+description: "A pre-completion request to prove work is done should trigger the verification-loop skill."
+---
+
+You said the refactor is finished. Run the full verification loop and show me the evidence before we call this done.

package/harness-everything/SKILL.md

@@ -4,7 +4,7 @@ description: "Route software/project work through Harness: classify tier/topolog
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.21.0
+  version: 0.22.1
 ---
 
 # Harness Everything

package/harness-everything/scripts/system-one/cua_adapter.py

@@ -1,9 +1,16 @@
 """Optional CPU CUA-S1 bridge. Stdout is protocol-only; never execute UI actions."""
 import hashlib
+import hmac
 import json
+import os
 from pathlib import Path
 import re
+import secrets
+import socket
+import subprocess
 import sys
+import threading
+import time
 
 
 def verify_artifacts(manifest):
@@ -25,18 +32,23 @@ def check_limits(request, config):
         raise ValueError('input-too-long')
 
 
-def infer(request, manifest):
-    weights = verify_artifacts(manifest)
+def load_scorer(weights, manifest):
+    """Load the verified checkpoint once; return (score(request) -> probabilities, config)."""
     import torch
     from cua_s1.model import ChoiceExample, load_checkpoint
 
     torch.set_num_threads(1)
     torch.use_deterministic_algorithms(True)
     model, collator, config = load_checkpoint(weights, 'cpu')
-    check_limits(request, config)
-    example = ChoiceExample(context=request['context'], options=tuple(o['text'] for o in request['options']), label=0)
-    with torch.inference_mode():
-        probabilities = model(collator([example])).softmax(-1)[0].tolist()
+
+    def score(request):
+        example = ChoiceExample(context=request['context'], options=tuple(o['text'] for o in request['options']), label=0)
+        with torch.inference_mode():
+            return model(collator([example])).softmax(-1)[0].tolist()
+    return score, config
+
+
+def build_response(request, manifest, probabilities):
     return {
         'schemaVersion': 1, 'requestHash': request['requestHash'], 'catalogHash': request['catalogHash'],
         'model': {'id': manifest['modelId'], 'revision': manifest['revision'], 'domain': manifest['domain']},
@@ -44,6 +56,251 @@ def infer(request, manifest):
     }
 
 
+def infer(request, manifest):
+    weights = verify_artifacts(manifest)
+    score, config = load_scorer(weights, manifest)
+    check_limits(request, config)
+    return build_response(request, manifest, score(request))
+
+
+MAX_REQUEST_BYTES = 2 * 1024 * 1024
+MAX_OPTIONS = 256
+MAX_CLIENTS = 64
+READ_DEADLINE_S = 1.0  # never longer than the Node client's 1000 ms call deadline
+STARTUP_REASONS = ('artifact-hash', 'checkpoint-format')
+ID_PATTERN = re.compile(r'[a-z0-9._-]{1,80}')
+HASH_PATTERN = re.compile(r'[0-9a-f]{64}')
+_USER_SID = []
+
+
+def _artifact_stamp(weights):
+    return [(p.stat().st_size, p.stat().st_mtime_ns) for p in (weights, weights.with_suffix('.json'))]
+
+
+def _restrict_to_current_user(path):
+    """Windows: replace the whole DACL with one protected full-control ACE for the current user.
+
+    Editing ACEs is not enough: some hosts create files with explicit (non-inherited) SYSTEM,
+    Administrators or OWNER RIGHTS entries that survive `icacls /inheritance:r /grant:r`.
+    """
+    if os.name != 'nt':
+        return
+    import ctypes
+    from ctypes import wintypes
+    if not _USER_SID:
+        tools = Path(os.environ.get('SystemRoot', 'C:/Windows')) / 'System32'
+        out = subprocess.run([str(tools / 'whoami.exe'), '/user', '/fo', 'csv', '/nh'],
+                             capture_output=True, text=True, timeout=10, check=True).stdout
+        sid = out.strip().split(',')[-1].strip().strip('"')
+        if not re.fullmatch(r'S-1-[0-9-]+', sid):
+            raise OSError('user-sid')
+        _USER_SID.append(sid)
+    advapi32 = ctypes.WinDLL('advapi32', use_last_error=True)
+    kernel32 = ctypes.WinDLL('kernel32', use_last_error=True)
+    descriptor = ctypes.c_void_p()
+    if not advapi32.ConvertStringSecurityDescriptorToSecurityDescriptorW(
+            f'D:P(A;;FA;;;{_USER_SID[0]})', 1, ctypes.byref(descriptor), None):
+        raise OSError('dacl-build')
+    try:
+        present, defaulted, dacl = wintypes.BOOL(), wintypes.BOOL(), ctypes.c_void_p()
+        if not advapi32.GetSecurityDescriptorDacl(descriptor, ctypes.byref(present), ctypes.byref(dacl), ctypes.byref(defaulted)):
+            raise OSError('dacl-read')
+        SE_FILE_OBJECT, DACL_INFO, PROTECTED_DACL_INFO = 1, 0x4, 0x80000000
+        advapi32.SetNamedSecurityInfoW.argtypes = [wintypes.LPWSTR, ctypes.c_int, wintypes.DWORD,
+                                                   ctypes.c_void_p, ctypes.c_void_p, ctypes.c_void_p, ctypes.c_void_p]
+        if advapi32.SetNamedSecurityInfoW(str(path), SE_FILE_OBJECT, DACL_INFO | PROTECTED_DACL_INFO, None, None, dacl, None) != 0:
+            raise OSError('dacl-set')
+    finally:
+        kernel32.LocalFree(descriptor)
+
+
+def _write_private_json(target, value):
+    """Atomic replace of an owner-only file (0600; explicit owner-only DACL on Windows) before the token is written."""
+    tmp = target.with_name(f'.{target.name}.{os.getpid()}.{secrets.token_hex(4)}.tmp')
+    os.close(os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600))
+    _restrict_to_current_user(tmp)
+    with open(tmp, 'w', encoding='utf-8') as handle:
+        json.dump(value, handle)
+    os.replace(tmp, target)
+
+
+def _read_request_line(conn):
+    buffer = bytearray()
+    while b'\n' not in buffer and len(buffer) <= MAX_REQUEST_BYTES:
+        chunk = conn.recv(65536)
+        if not chunk:
+            break
+        buffer.extend(chunk)
+    if len(buffer.split(b'\n', 1)[0]) > MAX_REQUEST_BYTES:
+        # Drain to EOF (bounded by size and the read deadline) so the reply is not lost to a reset.
+        drained = 0
+        try:
+            while drained < 8 * MAX_REQUEST_BYTES and conn.recv(65536):
+                drained += 65536
+        except OSError:
+            pass
+        raise ValueError('request-limit')
+    return bytes(buffer).split(b'\n', 1)[0]
+
+
+def _valid_score_request(request):
+    """Phase 0 request structure. Hashes are fingerprints, not authentication, so they are shape-checked only."""
+    if (not isinstance(request, dict)
+            or set(request) != {'schemaVersion', 'task', 'context', 'options', 'catalogHash', 'requestHash'}
+            or request['schemaVersion'] != 1 or not isinstance(request['task'], str) or not ID_PATTERN.fullmatch(request['task'])
+            or not isinstance(request['context'], str)
+            or not all(isinstance(request[k], str) and HASH_PATTERN.fullmatch(request[k]) for k in ('catalogHash', 'requestHash'))):
+        return False
+    options = request['options']
+    if not isinstance(options, list) or not 2 <= len(options) <= MAX_OPTIONS:
+        return False
+    if any(not isinstance(o, dict) or set(o) != {'id', 'text'} or not isinstance(o['id'], str)
+           or not ID_PATTERN.fullmatch(o['id']) or not isinstance(o['text'], str) for o in options):
+        return False
+    return len({o['id'] for o in options}) == len(options)
+
+
+def _handle(conn, token, manifest, weights, stamp, score, config):
+    """Return (reply, stop). Errors carry bounded reason codes only: no prompt, path, or traceback."""
+    invalid = {'ok': False, 'reason': 'invalid-request'}
+    try:
+        line = _read_request_line(conn)
+    except ValueError:
+        return {'ok': False, 'reason': 'request-limit'}, False
+    except OSError:
+        return invalid, False
+    try:
+        message = json.loads(line)
+    except ValueError:
+        return invalid, False
+    if not isinstance(message, dict):
+        return invalid, False
+    supplied = message.get('token')
+    if not isinstance(supplied, str) or not hmac.compare_digest(supplied.encode('utf-8'), token.encode('utf-8')):
+        return {'ok': False, 'reason': 'unauthorized'}, False
+    op = message.get('op')
+    if op == 'ping':
+        return {'ok': True, 'pid': os.getpid(), 'model': {'id': manifest['modelId'], 'revision': manifest['revision'], 'domain': manifest['domain']}}, False
+    if op == 'shutdown':
+        return {'ok': True}, True
+    if op != 'score' or not _valid_score_request(message.get('request')):
+        return invalid, False
+    try:
+        changed = _artifact_stamp(weights) != stamp
+    except OSError:
+        changed = True
+    if changed:
+        return {'ok': False, 'reason': 'artifact-changed'}, True
+    request = message['request']
+    try:
+        check_limits(request, config)
+    except ValueError:
+        return {'ok': False, 'reason': 'input-too-long'}, False
+    try:
+        return {'ok': True, 'response': build_response(request, manifest, score(request))}, False
+    except Exception:
+        return {'ok': False, 'reason': 'score-failed'}, False
+
+
+def serve(manifest, state_path, lock_path, scorer_factory=None, idle_timeout_s=None):
+    """Resident loopback scorer: verify, load once, publish state, serve until idle/shutdown/artifact change."""
+    state_path, lock_path = Path(state_path), Path(lock_path)
+    try:
+        weights = verify_artifacts(manifest)
+        stamp = _artifact_stamp(weights)
+        score, config = (scorer_factory or load_scorer)(weights, manifest)
+    except Exception as exc:
+        reason = str(exc) if str(exc) in STARTUP_REASONS else 'load-failed'
+        try:
+            _write_private_json(lock_path, {'failed': reason, 'at': time.time()})
+        except OSError:
+            pass
+        return 1
+    idle = idle_timeout_s if idle_timeout_s is not None else manifest.get('idleTimeoutMs', 1800000) / 1000
+    token = secrets.token_hex(32)
+    pid = os.getpid()
+    stop = threading.Event()
+    score_lock = threading.Lock()  # one model, one inference at a time; connections are handled concurrently
+    slots = threading.BoundedSemaphore(MAX_CLIENTS)
+
+    def guarded_score(request):
+        with score_lock:
+            return score(request)
+
+    def send(conn, reply):
+        try:
+            conn.sendall((json.dumps(reply, allow_nan=False) + '\n').encode('utf-8'))
+        except OSError:
+            pass
+
+    def worker(conn):
+        try:
+            with conn:
+                conn.settimeout(READ_DEADLINE_S)
+                reply, halt = _handle(conn, token, manifest, weights, stamp, guarded_score, config)
+                send(conn, reply)
+            if halt:
+                stop.set()
+        finally:
+            slots.release()
+
+    server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    try:
+        server.bind(('127.0.0.1', 0))
+        server.listen(MAX_CLIENTS)
+        server.settimeout(0.25)
+        _write_private_json(state_path, {'schemaVersion': 1, 'pid': pid, 'port': server.getsockname()[1], 'token': token, 'startedAt': time.time()})
+        try:
+            lock_path.unlink()
+        except FileNotFoundError:
+            pass
+        last = time.monotonic()
+        # A server whose state file no longer names it is undiscoverable (replaced or corrupted): exit, never orphan.
+        while not stop.is_set() and time.monotonic() - last <= idle and _owns_state(state_path, pid, token):
+            try:
+                conn, _ = server.accept()
+            except socket.timeout:
+                continue
+            last = time.monotonic()
+            if not slots.acquire(blocking=False):
+                with conn:
+                    conn.settimeout(0.2)
+                    try:
+                        _read_request_line(conn)
+                    except (OSError, ValueError):
+                        pass
+                    send(conn, {'ok': False, 'reason': 'busy'})
+                continue
+            threading.Thread(target=worker, args=(conn,), daemon=True).start()
+    finally:
+        server.close()
+        if _owns_state(state_path, pid, token, missing=False):
+            try:
+                state_path.unlink()
+            except OSError:
+                pass
+    return 0
+
+
+def _owns_state(state_path, pid, token, missing=False):
+    """True while the state file still names this server. A transient Windows sharing violation counts as owned."""
+    try:
+        data = json.loads(state_path.read_text(encoding='utf-8'))
+    except FileNotFoundError:
+        return missing
+    except OSError:
+        return True
+    except ValueError:
+        return False
+    return isinstance(data, dict) and data.get('pid') == pid and data.get('token') == token
+
+
+def serve_main(argv, scorer_factory=None):
+    if len(argv) != 3:
+        return 2
+    return serve(json.loads(argv[0]), argv[1], argv[2], scorer_factory=scorer_factory)
+
+
 def source_revision(direct_url_text):
     """Return the PEP 610 VCS commit recorded at install time, or None when unprovable."""
     try:
@@ -76,6 +333,8 @@ def main():
         if sys.argv[1:] == ['--provenance']:
             print(json.dumps(provenance(), allow_nan=False))
             return 0
+        if sys.argv[1:2] == ['--serve']:
+            return serve_main(sys.argv[2:])
         manifest = json.loads(sys.argv[1])
         raw = sys.stdin.buffer.read(2 * 1024 * 1024 + 1)
         if len(raw) > 2 * 1024 * 1024: