For Stakeholders
The decision in one paragraph
The manual "refresh a PR's AI documentation" action used to run detached — the CI job reported success the moment it launched a background agent, long before the site actually existed. That produced a misleading green checkmark and no way to watch or trust progress. This PR makes that action run in the foreground: the job now streams the agent's live work and only reports success when the site is published. To pay for the longer-held job, the timeout was raised (30 → 90 minutes) and a second CI runner slot was brought online so routine per-PR deploys keep flowing.
Why it matters
- Correct signals. A build system that says "done" before it's done erodes
trust in every other signal it sends. This restores "green means done" for a common action.
- Debuggability. Failures that used to happen invisibly in a detached
container are now in the job log, where they can be seen and fixed.
- Throughput protection. The second runner slot means the org can run a
long, watched docs job and keep shipping PR deploys — no serialization penalty.
Cost
- Runner time. A foreground docs job now **holds a runner slot for its full
duration** (~15–40 min typical, up to ~1h with a fresh sandbox deploy) instead of releasing it in seconds. That cost is offset by the new second slot.
- Infrastructure. One additional self-hosted runner slot on the homelab.
This is an operational/hosting cost, not a per-run cloud bill (self-hosted).
- No product/engineering opportunity cost beyond the review of a 13-line
workflow diff.
Risk
| Risk | Severity | Mitigation in this PR |
|---|---|---|
| Long docs job starves PR deploys | Medium | Second runner slot added so deploys keep a free slot. |
| Docs job exceeds old 30-min limit | Medium | Timeout raised to 90 min. |
| Detached auto-gen loses its fast-return benefit | — | Left detached on purpose; only the manual action changed. |
| Second slot not actually provisioned | Medium | Open item — the slot is infra, not in this diff. See For Quality. |
| Stale comment elsewhere claims "single-slot" | Low | Documentation drift in sandbox-qa.yml; flagged, not fixed here. |
What this is not
- Not a customer feature and not released.
- Not a performance improvement — it does not make docs faster.
- Not a change to auto-generation, QA, deploy, reseed, reset, or destroy.
Strategic read
Small, disciplined maintenance of an already-differentiated capability (per-change preview environments + AI walkthroughs). The value is operational trust: the internal tooling now tells the truth about its own completion, and the org added capacity so improving that truthfulness didn't cost throughput. Low risk, low cost, clear payoff — contingent on the second runner slot actually being live, which sits outside this repository and should be verified before merge.