docs(harness): revise Phase 1 estimates from runner exploration

[PattaraS]

Now based directly on main — the 1.1→1.2→1.3 stack this was originally stacked on has all landed, so this diff is doc-only and ready to merge on its own.

Workstream progress

Modular native-harness registry (designs/harness-modular-registry-proposal.md). This is a docs-only planning update — no PR number of its own in the phase sequence; it revises the plan the other PRs execute against.

• ✅ Phase 0 — file splits (refactor(cli): extract native TUI subcommands into cli_native.py #3047, refactor(server): split sessions route into facade + impl package #3097, [runner] Extract native terminal orchestration #3148, [tests] Split native app session tests by concern #3149) + costed plan (docs(harness): sync Phase 0 completion in modular-registry proposal #3212, docs(harness): break Phases 1 & 2 into a PR-by-PR breakdown #3217).
• ✅ 1.1 (feat(harness): add NativeHarnessProvider seam foundation (PR 1.1) #3239), 1.2 (refactor(harness): normalize native launcher pass-through args (PR 1.2) #3244), 1.3 (refactor(harness): route native resume through the provider seam (PR 1.3) #3314) — landed.
• 🔬 1.5a (runner spawn-env) exploration done — findings folded into this doc update.
• ⏳ 1.4, 1.5a/b/c, 1.6, 1.7, 1.8, then Phase 2 (2.1–2.4).

Related issue

N/A — planning-doc revision.

Summary

Reading the runner dispatch surface (rather than guessing from the coupling inventory) materially changed the shape of the remaining work. This updates the proposal's estimates and plan to match:

• Split PR 1.5 into a serial runner sub-stack:
  • 1.5a spawn-env (Med, 2–3d) — the bounded first measurement; collapses the two duplicated 11-arm blocks behind one build_spawn_env(session_id, *, server_client, labels) hook.
  • 1.5b launch (High, 4–6d) — the epicenter. _auto_create_<x>_terminal has 11 divergent signatures (3 common params; claude carries 9 extras), so the seam passes a NativeLaunchContext dataclass to a uniform provider.auto_create_terminal(ctx) adapter with explicit pre_launch hooks — not a single positional call.
  • 1.5c terminal-route (Med, 2d) — reuses 1.5b's context; codex/antigravity need an ownership-check + response-wrap hook.
• Re-scope 1.6 interrupt/stop upward (Med → Med–High, 2d → 3–4d): every handler closes over app-scope state (server_client, resource_registry, _publish_event, module dicts), so extraction needs a dependency-injection context, not a plain move.
• Revise totals: Phase 1 ~17–25 → ~20–29 eng-days; overall ~26–37 → ~29–41 eng-days across ~12 → ~14 PRs; critical path rewritten to the serial runner chain (1.1 → 1.2 → 1.5a → 1.5b → 1.5c → 1.6 → 2.2 → 2.3).
• Add a Calibration subsection recording the learning from 1.1–1.3 (additive PRs come in under estimate; the real cost is test-shape churn; the runner is the back-loaded risk) and settle the prior "signature uniformity" open question with the confirmed finding.
• Record harness-bench compatibility — the bench's selection/driver layer is already registry-driven, so a community native plugin auto-enumerates; the two remaining gaps close via PR 1.7 (seeding) and a small 1.8 capability field. Give 2.4 a benchable acceptance criterion.
• Mark the progress ledger 1.1/1.2/1.3 as landed (feat(harness): add NativeHarnessProvider seam foundation (PR 1.1) #3239/refactor(harness): normalize native launcher pass-through args (PR 1.2) #3244/refactor(harness): route native resume through the provider seam (PR 1.3) #3314) now that the stack has merged.

Test Plan

Docs-only. pre-commit run --files designs/harness-modular-registry-proposal.md passes. The runner claims (divergent _auto_create_* signatures, the two duplicated spawn-env blocks, closure-bound interrupt/stop handlers, the opencode turn-path cold-boot) were verified against omnigent/runner/app.py and omnigent/runner/native/orchestration.py at the current tree.

Demo

N/A — documentation only.

Type of change

• Bug fix
• Feature
• UI / frontend change
• Refactor / chore
• Docs
• Test / CI
• Breaking change

Test coverage

• Unit tests added / updated
• Integration tests added / updated
• E2E tests added / updated
• Manual verification completed
• Existing tests cover this change
• Not applicable

Coverage notes

Documentation-only change to a design proposal; no code paths are affected. The factual claims about the runner dispatch surface were verified by reading the current source as noted in the Test Plan.

This pull request and its description were written by Isaac.

[omnigent-ci]

Polly AI Review

Blocking issues

None. This is a docs-only revision to a design proposal; there are no code paths, contracts, or failure modes to break.

Security vulnerabilities

None. No code, dependencies, lockfiles, or extras are touched — the diff is a single Markdown file.

Non-blocking notes

I spot-checked the load-bearing factual claims against the current tree (omnigent/runner/app.py, omnigent/runner/native/orchestration.py), since the whole point of the PR is to replace guesses with source-grounded estimates. They hold up:

• 11 divergent _auto_create_*_terminal signatures — confirmed. orchestration.py defines exactly 11 native variants (opencode, pi, cursor, goose, hermes, kiro, qwen, kimi, codex, antigravity, claude), plus a non-native _auto_create_repl_terminal. Divergence is real.
• Two near-identical ~11-arm spawn-env blocks — confirmed, at roughly app.py ~2532–2624 and ~6063–6098 (the doc's "~2720 / ~6236" anchors are close enough for a planning doc but drift ~100–200 lines from the actual block starts; consider loosening to "~2.5k" / "~6.0k" so they don't rot as the file moves).
• codex/antigravity ownership-check + response-wrap hooks — confirmed: _is_runner_owned_codex_terminal, _is_runner_owned_antigravity_terminal, and _codex_ensure_response_with_policy_notice all exist and are wired into the ensure_native_terminal path.
• Interrupt/stop handlers close over app-scope state — confirmed: the handlers are nested inside create_runner_app, closing over server_client / resource_registry / _publish_event, with _AUTO_FORWARDER_TASKS and the _session_* dicts as module/enclosing state. The "needs DI, not a plain move" characterization is accurate.

Two small precision points, neither blocking:

• The "claude carries 9 extras" count is asserted but the diff only enumerates four (bundle_dir, skills_filter, auth_token_factory, resolve_launch_config, "…"). If the "9" is load-bearing for the 1.5b estimate, spelling out the full list (or softening to "several") would keep the doc from being contradicted by a later reader who counts.
• The line-number anchors throughout ("~2841–3316", "~6329", "~7462–7908") are inherently fragile in a doc that outlives the current tree. They're useful now; a one-line caveat that they're pinned to the current SHA would prevent future confusion.

No visual demonstration is required — this is a pure documentation change with no user-visible surface.

Summary

A clean, well-scoped docs-only update that revises the harness-registry proposal's estimates and plan to match what a real read of the runner dispatch surface revealed (1.5 split into 1.5a/b/c, 1.6 re-scoped upward, totals bumped to ~29–41 eng-days / ~14 PRs, plus a Calibration subsection). The substantive technical claims check out against the current source, the reasoning is sound and appropriately hedged ("measure 1.5a before committing a runner timeline"), and there is no code, security, or dependency risk. Approve; the only follow-ups are optional precision tweaks (the "9 extras" count and the fragility of hard-coded line anchors).

The review is already complete and posted; the cancelled sub-agent's result is no longer needed. Draining the inbox to clear it.The

The inbox is now drained — the sub-agent was cancelled after I had already gathered sufficient verification evidence from its working history. The review is complete and posted above. No further action needed.

---

_{Automated review by Polly · workflow run}

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[github-actions]

🏷️ Doc impact: no-doc-update

The change only edits an internal design/proposal doc under designs/ (planning, PR sequencing, and effort estimates) with no code, user-facing surface, integration, or built-in policy change.

_{Auto-classified on merge. Set the label manually before merging to override. · run}