FE-1412: Scale the Python client's timeout for seeded trials

[kube]

🌟 What is the purpose of this PR?

Top of the FE-1408 stack: makes the Python side ready for trials that run multiple seeded simulations. The seeded runs execute sequentially in the CLI, so one optimization.evaluate may legally take seedsPerTrial × the single-run time — the client's fixed 240 s response deadline must scale with it.

Stack #9226: FE-1410 → FE-1411 → FE-1408 → FE-1413 → FE-1270 → this PR.

🔗 Related links

• FE-1412 (internal) — this PR
• FE-1408 (internal) — parent: seeded trials in the CLI

🔍 What does this change?

@local/petrinaut-python (consumed by apps/petrinaut-opt):

• OptimizationSession.describe_optimization() validates the reported study.seedsPerTrial (integer, 1–100; protocol error otherwise) and multiplies the per-response deadline by it.
• A new end-to-end test drives a two-seed trial against the real built CLI, asserting the derived seed sequence [42, 1013904268], the per-seed replicates, and the mean objective.
• The optimizer README documents the sequential seeded-runs behaviour and the scaled deadline.

No image changes: the seeded runs are sequential, so no worker permissions or pool caps are needed.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• modifies workspaces but not a publishable library

📜 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 (bindings + optimizer READMEs)

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

The changes in this PR:

• do not affect the execution graph

🛡 What tests cover this?

• Bindings (26 tests): timeout scaling from the described seedsPerTrial, rejection of invalid values, and the sequential two-seed e2e against the real bundle.
• petrinaut-opt: full suite (75) unchanged and green.

❓ How to test this?

turbo run test:unit --filter @local/petrinaut-python --filter @apps/petrinaut-opt

🤖 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 20, 2026 10:53am
petrinaut	Ready	Preview	Aug 20, 2026 10:53am
petrinaut-docs	Ready	Preview	Aug 20, 2026 10:53am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Aug 20, 2026 10:53am

[cursor]

PR Summary

^{Cursor Bugbot is generating a summary for commit 7007b77. Configure here.}

[Copilot]

Pull request overview

Scales Python optimization response timeouts for sequential seeded trials and documents the behavior.

Changes:

• Validates seedsPerTrial and scales response deadlines.
• Adds unit and CLI end-to-end coverage.
• Documents seeded execution and timeout behavior.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
session.py	Stores the base response timeout.
optimization.py	Validates seed count and scales timeouts.
test_optimization_session.py	Tests scaling and invalid values.
test_e2e_cli.py	Tests a two-seed CLI trial.
Python README.md	Documents scaled deadlines.
Optimizer README.md	Documents sequential seeded trials.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.