fix(examples): repair the e2e gallery fake and floor the workflow concurrency clamp

[anilkmr-a2z]

Two independent one-line fixes on the examples surface, plus the regression test the second one was missing.

On the two-fixes-one-PR shape: this is deliberate, not scope creep. Both defects are in the examples surface, both are one-line, and both were proven on current main; carrying them as one diff is cheaper to review than two PRs that touch adjacent files. Each is a separate commit, so either can be reverted alone.

---

Fix 1 - the e2e gallery fake omitted replayed

test/e2e/examples/test_examples_gallery_e2e.py's fake /terminals/run-step handler answered with terminal_id, last_message and status, but no replayed. The cao_workflow shim reads data["replayed"], so every test routed through the shim died with KeyError: 'replayed', surfacing as RunState.FAILED.

Before: 3 failed, 1 passed. After: 4 passed.

Failing tests now green:

• test_loop_example_records_n_iterations
• test_conditional_example_runs_only_the_taken_branch
• test_fanout_example_records_distinct_step_ids_per_shard

test_loop_raw_http_example_works_without_the_shim passed all along, because it bypasses the shim by design.

A reviewer running the default pytest invocation will see nothing wrong

addopts carries -m 'not e2e and not integration', which silently deselects all four of these tests. Reproducing the failure requires an explicit -m e2e:

uv run pytest --no-cov -q -m e2e test/e2e/examples/test_examples_gallery_e2e.py

Please use that exact invocation to check this; the bare path collects zero tests and reports success.

Why the fix belongs on the fake and not on the shim

This is the non-obvious call in this PR, so stating it plainly. The tempting "fix" is .get("replayed", False) in the shim. That would be wrong, and there is a comment at src/cao_workflow/__init__.py forbidding it on BR-3/TD-7 grounds. Quoting it:

Direct indexing, matching the three reads above - NEVER .get("replayed", False) (BR-3/TD-7). The field is non-optional with a default on RunStepResponse, so the server always serialises it; a defaulting read would silently re-manufacture the exact false replayed=False this flag exists to eliminate, and would hand the author a DEAD terminal_id labelled live. A KeyError is the honest failure.

So the KeyError was doing its job: it was correctly reporting that the fake was not a faithful stand-in for the real route. The shim is untouched by this PR.

Corroborating evidence that the fake is the defect: the sibling fake at examples/workflow/tests/conftest.py already carries "replayed": False along with this same rationale in a comment. The gallery fake was simply missed. This change makes the two consistent, copying that comment across so the next person does not "simplify" it away.

---

Fix 2 - the workflow concurrency clamp crashed on 0

examples/workflow/workflow.py computed:

max_workers = min(inputs.get("concurrency", 2), INPUTS["concurrency"]["default"])

That bounds the input from above but not from below. INPUTS declares concurrency as a bare int with no minimum, so --input concurrency=0 clears the pre-run validation gate, resolves through min(0, 2) to max_workers=0, and ThreadPoolExecutor(max_workers=0) raises:

ValueError: max_workers must be greater than 0

as an opaque traceback mid-run - after the sequential plan step has already executed. A negative value behaves identically. Verified directly against the real _validate_inputs gate:

concurrency=0:  validation PASSED resolved=0  -> max_workers=0   executor ValueError: max_workers must be greater than 0
concurrency=-1: validation PASSED resolved=-1 -> max_workers=-1  executor ValueError: max_workers must be greater than 0
concurrency=1:  validation PASSED resolved=1  -> max_workers=1   executor OK
concurrency=3:  validation PASSED resolved=3  -> max_workers=2   executor OK

The fix is a max(1, ...) floor. One worker serialises the fan-out units rather than dropping any, so a nonsense input degrades to slow instead of to a crash.

Regression test added

The clamp was only ever asserted in the upward direction (3 -> 2, plus the 2 -> 2 no-op at the default). No test ever passed a value below the default, which is exactly why the unbounded lower half shipped. The new test in examples/workflow/tests/ asserts 0 -> 1 and 1 -> 1, and additionally asserts that the validation gate really does admit 0 - since that premise is the whole reason the floor has to live in the script rather than in the input declaration.

Before: 8 passed, 1 skipped. After: 10 passed, 1 skipped.

uv run pytest --no-cov -p no:cacheprovider -q examples/workflow/tests/

The 1 skip is the live-provider test, correctly gated off by CAO_RUN_LIVE_PROVIDER_TESTS; this PR does not set it.

I confirmed the test guards the fix rather than merely passing alongside it: reverting only workflow.py and rerunning fails the new [0] case.

---

Verification summary

Check	Result
-m e2e test/e2e/examples/test_examples_gallery_e2e.py	3 failed 1 passed -> 4 passed
examples/workflow/tests/	8 passed 1 skipped -> 10 passed 1 skipped
New test fails without fix 2	Confirmed ([0] case)
black --check	clean
isort --check-only	clean
uv.lock in diff	absent (no dependency change; all commands run --frozen)
src/cao_workflow/__init__.py in diff	absent (the shim is correct as written)

Diff is 3 files, +39/-1.

Not fixed here

Refs #720 - a broad pytest examples/ fails to collect because examples/workflow/tests/__init__.py and examples/plugins/cao-discord/tests/__init__.py both claim the package name tests. CI is blind to it because CI passes the specific path. This PR does not address that; the candidate remedies both change import resolution for the suite and need a real verification run, so it is filed for a tracked decision instead. Referenced, deliberately not closed.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@c0c9b72). Learn more about missing BASE report.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #721   +/-   ##
=======================================
  Coverage        ?   91.63%           
=======================================
  Files           ?      203           
  Lines           ?    28444           
  Branches        ?        0           
=======================================
  Hits            ?    26065           
  Misses          ?     2379           
  Partials        ?        0           

Flag	Coverage Δ
unittests	91.63% <ø> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.