[CompleteDotTech]

Refs CompleteTech-LLC/complete.tech#17 (step 1, part 2: per-request admission guard). Scanning stays disabled by default; nothing here enables it or provisions a worker.

What changes

Before every connection to the customer's site the sandboxed scanner (uid 65534, no key) asks the root supervisor over a private socket pair; the supervisor calls a new signed POST /ct-scan/v1/admit; WordPress decides under the queue lock that also serializes customer Stop, operator revocation, expiry, claims, starts and results:

• job running, lease and scope hash match, lease unexpired, recipient confirmed, saved authorization still reads back unchanged/unexpired/unrevoked, frozen profile known;
• previous grant at least 1 s old (central 1 req/s pacing); budget (r2-header-v1: 20 requests = robots.txt <=6 hops + homepage <=6 hops + one http->https change) not exhausted;
• the reservation + time are written in one compare-and-set update. Grant = reserved and consumed at once, valid 1 s, one connection.

Supervisor/scanner: no grant => no connection (PinnedOpener asks after DNS/public-IP validation and before any socket, re-checks freshness immediately before connect, reports done); one grant outstanding; sequence-numbered request/reply and a poisoned channel on any error; lifetime and 10 s bound measured from just before the granting call; supervisor kills the scanner on refusal, protocol violation, request_deadline_exceeded, or when a 2 s liveness probe (own thread, also during backoff) reports cancelled/expired/revoked/integration-disabled. SubprocessRunner.run refuses to start without a gate; the scanner refuses to run without the socket. Schema 3 (profile_id, http_admitted, last_admit_ms); Stop and operator revoke now wait up to 3 s for the lock.

Review with git diff -w: runner.py is mostly re-indentation (try/finally to close the socket).

Fail-closed behavior

Unreachable/slow/garbled guard, 4xx/5xx, wrong schema, disabled integration, unknown profile, clock moving backwards, unconfirmed recipient, lost compare-and-set, thrown exception in the locked region, expired grant, out-of-sequence/oversized/unknown message, missing gate, missing socket: all are refusals that end the run as a failed receipt (admission_<reason>). Never a clean result, no automatic rescan, no budget reset by recovery/duplicate delivery/schema upgrade (a job running at the 2->3 upgrade gets no fresh budget).

Tests (all local; no third-party target)

• test_admission.py (new, 52): gate, pump state machine, child client, desync, opener guard, real scanner entry point, real child process + local server for: budget stop, cancel before start / during an in-flight request / during backoff, deadline kill, protocol violation.
• integrations/wordpress/tests/admission.php (new): cancellation/admission race in both orders and under real lock contention (second process holds the lock; Stop waits then wins), operator revocation, expiry, lease lapse, budget, pacing, clock anomaly, wrong lease/scope, unconfirmed, unknown profile, changed authorization, duplicate delivery, compare-and-set loss, injected DB fault, schema upgrade, disabled kill switch, store unavailable. Helpers extracted to tests/support.php.
• deployment/test-http-worker.py: real signed HTTP round trip of admit/probe/pacing/foreign lease/finished job.
• Root-only: real uid-65534 child speaks the protocol over the inherited fd (CI container step now also runs test_admission); packaged smoke test gets a gate.
• Locally: Python 118 OK (4 root-only skipped, ran in CI); WordPress suites against a disposable MariaDB 11.4 + WordPress 6.8.3; HTTP test against that WordPress. CI on the head: green (ubuntu+windows, py3.10/3.14, WordPress/Docker job).
• Independent adversarial and acceptance/mutation reviews found a request/reply desync (fixed with sequence ids + poisoning), refusals reported as completed (fixed), unbounded blocking probe (own thread, 4 s budget), lifetime measured from receipt (fixed), maintenance under the lock (removed), upgrade budget (fixed), and several test gaps (added).

Reviewer: please attack

1. Any path that opens a socket to the target without a fresh grant (DNS-before-admit ordering, redirects/robots, TLS, exception paths skipping done).
2. Lock semantics: GET_LOCK lost on a silent $wpdb reconnect (CAS is the backstop); Stop/revoke wait of 3 s vs admission 0 s.
3. Child can ignore the protocol and open its own sockets: not preventable here; needs host/container egress filtering (deployment/compose.yaml does not enforce it). Supervisor still kills by deadline/probe.
4. Admission answers are TLS-protected but not signed.
5. In-flight bound: probe interval 2 s + latency; DNS lookups of the authorized host occur before admission.

Not done / needs owner

• The Stop page still says "a check that has already started may finish its current requests" (accurate; now at most one request). Updating customer-facing copy is left to the owner.
• Vendoring into complete.tech (mu-plugins/ct-scan.php, docs/php2shell-source.json) is a separate excluded PR held for the owner.

Second independent review (after the first round of fixes)

Re-verified the earlier fixes and found: (high) a slow-but-successful WordPress round trip made the delivered grant stale and the pump killed the whole scan -> now a grant older than 0.6 s is discarded and asked for again (at most twice; the slot stays spent), then refused; (medium) the in-flight probe was never joined and the admission call could outlive a shutdown or the scan deadline -> the runner waits for the probe, the gate honours the scan deadline, and a shutdown interrupts a slow call. Accepted/documented: an abandoned guard call can still land at WordPress after the supervisor gave up (the slot is simply spent); probe/admit slugs are prefixed by the pump.

Fail-closed review round 2 (coordinator findings)

Fixed in this PR, each with tests that fail without the fix (mutation-checked):

• Activation requires egress_enforced: true (loader refuses otherwise); docs/README/example config state it; unverified nftables egress sketch added (not a claim of enforcement). In-flight bound is exactly 10 s from the grant (no grace). Authorization read from the DB, not the object cache. A completed result needs >= 1 admitted request. Failed schema upgrade: one error_log, 5-minute back-off, plugin 0.2.0. Special-purpose IP ranges listed explicitly (CGNAT, documentation, benchmarking, 3fff::/20, 6to4, NAT64, ...), tested independent of the interpreter's ipaddress.

Review round 3

• A probe that hit the busy queue lock (queue_busy, often the supervisor's own concurrent admission racing for the no-wait lock) or an internal admission_error killed the scan. Such a probe is now retried briefly within one call budget and then treated as inconclusive, like an unreachable guard; the next admission still fails closed, and explicit refusals stay fatal.
• The stale-grant re-ask path now honours the four-second admission deadline, so one admission stays within about eight seconds as documented.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	🔄 Running since 2026-10-23T19:38:58.156859Z	0bd4510	Draft marked ready
🔒 Security Review	✅ Completed 2026-10-23T19:40:35.546189Z	0bd4510	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.