FE-1220: Harden and document Petrinaut optimization execution isolation

[kube]

🌟 What is the purpose of this PR?

Bounds what the Petrinaut CLI subprocess can do, and writes down the isolation model the optimizer service depends on. A malicious optimization manifest can no longer leave descendants running after its study ends, and each CLI process is capped on CPU time, address space, and process count.

🔗 Related links

• FE-1220 — this issue
• FE-1217 — parent hardening issue
• SRE-830 — the out-of-repo ECS task settings this documents as required

🚫 Blocked by

• FE-1222, FE-1226: Classify optimization transport errors, auto-reconnect runs by id + cursor, and remove the legacy optimization path #9066 — layer 2 of a 3-PR stack (#9066 → this → #9060)

🔍 What does this change?

• petrinaut_client.py: a SIGKILL sweep of the CLI's process group on every close path, so descendants cannot outlive the study; resource.prlimit (Linux) bounds each CLI process via RLIMIT_CPU / RLIMIT_AS / RLIMIT_NPROC, configurable through HASH_PETRINAUT_OPT_CLI_* (0 disables).
• docker/Dockerfile: tini as PID 1, so any orphan that escapes the sweep is reaped instead of becoming a zombie under uvicorn.
• docs/threat-model.md (new): the execution path, per-layer mitigations, the required out-of-repo deployment configuration, and the documented decision that container/process isolation is sufficient — no additional V8 sandbox.
• README.md: the security/isolation section and the CLI limit environment variables.
• OPTIMIZATION_INTEGRATION.md: the CLI cancellation/shutdown contract that parents must implement.

Dropped during the rebase: this branch originally added a study wall-clock ceiling to the legacy stream_all/stream_best generators. main now bounds detached runs via HASH_PETRINAUT_OPT_MAX_STUDY_SECONDS (FE-1224), and #9066 below this in the stack deletes those generators entirely — so that part would have been written and then deleted.

The threat model is written against the current architecture rather than the one this branch was first drafted on: runs are detached and outlive their connections, ownership is enforced in the optimizer by account tag (a foreign run answers 404 so ids cannot be probed), and study-slot occupancy is bounded by the wall-clock ceiling plus detach-grace reaping instead of by connection deadlines. Each claim was checked against the code.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• does not modify any publishable blocks or libraries, or modifications do not need publishing

📜 Does this require a change to the docs?

The changes in this PR:

• require changes to docs which are made as part of this PR

🕸️ Does this require a change to the Turbo Graph?

The changes in this PR:

• do not affect the execution graph

⚠️ Known issues

• RLIMIT_NPROC is enforced by Linux against the service user's total task count, not this child's descendants; container-level pidsLimit (SRE-830) is the real backstop.
• prlimit is applied from the parent immediately after spawn, so the child is briefly unbounded; container limits remain the outer bound.
• A descendant that calls setsid()/setpgid() leaves the CLI's process group and escapes the sweep — documented in the threat model's limitations.
• Task-level settings (read-only rootfs, memory sizing, deny-all egress, pidsLimit) live in the out-of-repo infra and are tracked in SRE-830.

🛡 What tests cover this?

apps/petrinaut-opt: 93 pytest green on this layer — including the process-group sweep verified with a real grandchild process (mutation-checked: removing the sweep fails the test), prlimit application and env parsing, and the prompt-termination paths.

❓ How to test this?

1. cd apps/petrinaut-opt && uv run pytest
2. Build the image and confirm tini is PID 1: docker build --file apps/petrinaut-opt/docker/Dockerfile --tag petrinaut-opt:local . then docker run --rm petrinaut-opt:local ps -o pid,comm (or inspect the entrypoint).
3. Start a run, note the CLI's pid, kill the study, and confirm no descendant of that process group survives.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview	Aug 3, 2026 5:42pm
petrinaut	Ready	Preview	Aug 3, 2026 5:42pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Aug 3, 2026 5:42pm

[cursor]

PR Summary

Medium Risk
Touches subprocess lifecycle and resource limits on a security-sensitive optimization path; behavior is well-tested but mis-tuned RLIMIT_NPROC or memory limits could affect availability under load.

Overview
Hardens Petrinaut optimization execution isolation and documents the security model for reviewers and operators.

Runtime hardening (petrinaut_client, Dockerfile): every CLI shutdown now ends with a SIGKILL process-group sweep so grandchildren cannot outlive the study; tini is PID 1 to reap orphans. Linux prlimit on each spawned CLI bounds CPU, address space, and process count via HASH_PETRINAUT_OPT_CLI_* env vars. petrinaut_optimizer enforces a per-study wall-clock ceiling (HASH_PETRINAUT_OPT_MAX_STUDY_SECONDS, default 900s) on SSE streams, emitting a terminal error and tearing down the CLI without mislabeling a study that already queued its completion sentinel.

Documentation: new docs/threat-model.md (execution path, mitigations, limitations, required ECS settings, no extra V8 sandbox rationale); README lists isolation env vars; OPTIMIZATION_INTEGRATION.md documents parent cancellation/shutdown expectations.

Tests cover group sweep, rlimit application/parsing, study ceiling vs. boundary completion, and disabling limits in real-subprocess tests.

^{Reviewed by Cursor Bugbot for commit 47f2fea. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 47f2fea. Configure here.}

[cursor]

Pending sentinel misclassified as timeout

Medium Severity

When the study wall-clock deadline is reached, timeout handling treats an empty events queue as proof the study is still running. The worker always enqueues the completion sentinel via call_soon_threadsafe, so a study that just finished can look idle until that callback runs, triggering a false execution-limit error instead of the normal done path.

Additional Locations (1)

• apps/petrinaut-opt/src/petrinaut_optimizer.py#L426-L444

 

^{Reviewed by Cursor Bugbot for commit 47f2fea. Configure here.}

[kube]

Converted back to draft: the stack was reordered so the streaming fixes (#9057) and correlated logging (#9059) can merge first to debug the staging network error (FE-1217). #9059 no longer stacks on this branch; once it merges, this branch needs a rebase over it (reintroducing the sweep/ceiling log events and the threat-model rows that reference logging).

The base branch was changed.