fix(work-driver): four defects in the merged-step mechanization

[randomm]

Context

PR #354 (issue #323) merged mechanized gh pr merge plus post-merge checkout restoration. A manual review after merge found four small defects, all confirmed present at f2e62af. None is urgent. Together they are roughly 150 lines and one PR.

Expected behaviour

Documentation matches implementation; no import cycles; a successful merge is never reported as a failure; every branch of detectMainline is tested.

Definition of done

• Docstring corrected. restoreCheckout's jsdoc at extension/src/work-driver-git.ts:99-120 claims "Throws on fatal errors (git itself broken, --ff-only refusal)". No path in that function throws — every error is caught and pushed as a note. Correct the docstring to match behaviour. Also reconcile its 4 numbered steps against the body's 5 numbered comments (~lines 139, 147, 151, 165, 186).

• Import cycle removed. work-driver-merged.ts:20 imports mechanizeOpsEnabled from work-driver-commit.ts, while work-driver-commit.ts:19 imports runSingleDispatch from work-driver-merged.ts. VERIFIED: this is NOT a module-init hazard — mechanizeOpsEnabled is only referenced inside a function body, so there is no circular evaluation at load time, which is why tsc and all offline tests pass. It is untidy rather than broken, and it contradicts work-driver-git.ts's own module header, which states that file exists specifically to avoid this cycle. Fix by moving mechanizeOpsEnabled to a leaf module.

• Successful merge no longer reported as failure. In extension/src/work-driver-merged-mechanized.ts (executeAndVerifyMerge, lines 75-138), the post-merge verification block catches an exception from the gh pr view call and returns {ok: false, reason: "post-merge verification failed"}. This catch executes AFTER gh pr merge has already succeeded — if the merge itself had thrown, the function would have returned earlier. So a transient network failure on the VERIFICATION call reports a merge failure for a merge that actually happened, causing the caller to emit a plumb-report and fall back to an LLM ops dispatch against an already-merged PR. Distinguish "the verification call failed" from "verification returned a state other than MERGED" — the latter is a genuine failure, the former is not.

  NOTE FOR REVIEWERS: an automated review initially disputed this finding, arguing the caller already distinguishes {merged: true} from {ok: false}. It does — but that is a different question. The defect is that ok: false is the WRONG value to return in this specific path, not that the caller fails to read it.

• detectMainline gains direct test coverage. It currently has ZERO direct tests anywhere in extension/smoke-tests/. It is a two-branch function — git symbolic-ref --short refs/remotes/origin/HEAD, then a gh repo view --json defaultBranchRef fallback — plus a both-failed error path. The fallback branch is not exercised transitively by restoreCheckout tests. Cover all three paths.

• Full offline gate passes.

Technical context

• extension/smoke-tests/test-work-driver-merged-mechanized.ts is 470 lines against a 500-line hard cap — 30 lines of headroom. New detectMainline tests will not fit; create a new test file.

Out of scope

• Any behaviour change to the merge path itself; it was reviewed and is correct.

[randomm]

DoD item 2 is obsolete — from the ten-agent /work audit (2026-08-12), verified against source rather than issue text.

The mechanizeOpsEnabled import cycle no longer exists:

$ grep -rn mechanizeOpsEnabled extension/src/*.ts
(no output)

#393 (7c6b0f1) deleted the symbol. Nothing to fix there.

The other three DoD items were not checked by this audit and should be treated as live. Not closing.

Also worth recording so a future cycle does not go looking: the Unknown role: driver defect fixed in #441 is not one of this issue's four items — I read them. runMerged dispatched a non-role after a successful mechanized merge, so a merged PR reported a failed cycle with teardown skipped. Separate defect, already shipped.