fix(web-ai): honor --family and bound assistant DOM reads by the polling deadline

[dbc-hbin]

Fixes #87
Fixes #88

Two related web-ai defects, one commit each, so they can still be reviewed independently:

• a2dc3e1 — --family never reached ChatGPT model selection (web-ai CLI silently ignores documented --family #87)
• 79db5d1 — assistant DOM reads were not bounded by the polling deadline (pollWebAi can hang past --timeout when assistant DOM evaluation stalls #88)

They are combined because both touch web-ai/chatgpt.mjs and both bump line counts in structure/str_func.md, so merging them separately would need a npm run fix:counts conflict resolution in between. Verified together below.

---

#87 — --family was accepted and silently ignored

--family is advertised by the top-level help, README, the bundled web-ai skill, and the web_ai_submit_prompt MCP schema, but the value never reached model selection. The send/query parser runs with strict: false, so the flag was swallowed:

agbrowse web-ai render --vendor chatgpt --family gpt-5.6-sol \
  --model thinking --effort high --inline-only --prompt "check" --json
# → status: rendered

--family bogus-family returned the same rendered/exit 0, so neither output proved anything about the family. Agent workflows could report that GPT-5.6 Sol was explicitly enforced while using whatever family happened to be selected in the browser.

web-ai/chatgpt-model.mjs already implemented family selection and post-click verification (selectChatGptFamily, normalizeChatGptFamilyChoice); only the wiring was missing, so the fix is small.

Changes

• declare family in the send/query parser and carry it into the normalized input
• pass { family, effort } into selectChatGptModel and the model capability probe
• forward family in web_ai_submit_prompt, failing closed when sent to a provider with no Chat family axis
• validate the alias in CLI preflight, before any browser mutation
• document --family in web-ai help, which omitted it while the top-level help advertised it

Omitting --family is unchanged: the family currently selected in the UI is preserved and no submenu is touched.

--family gpt-5.6-sol|gpt-5.5|gpt-5.4|gpt-5.3|o3   accepted, selected and verified
--family gpt-5.6-luna                              unsupported ChatGPT family: gpt-5.6-luna
--vendor gemini --family gpt-5.6-sol               --family is supported only for ChatGPT

An unsupported family also makes the model capability probe report fail, so a probe result is no longer mistaken for proof that the family was enforced.

#88 — polling could outlive --timeout

pollWebAi checks its deadline only at the while boundary, then awaits readAssistantMessages(), which called page.evaluate() with no per-call bound. Playwright's page.evaluate() accepts no timeout option (only locator.evaluate does), so when assistant-message extraction stalled on a large conversation, control never reached the next deadline check. The process and session lock stayed alive while the stderr heartbeat went silent — matching the report where sessions doctor showed a valid target, a healthy command-lock heartbeat, and no CDP or login failure.

The same function also serialized every historical assistant turn on each 500 ms tick, then sliced off everything before baseline.assistantCount.

Changes

• add withAssistantReadTimeout() and resolveAssistantReadBudgetMs(); each read races the smaller of the remaining deadline and a per-read ceiling
• bound the page.evaluate() path, the locator fallback, and the post-timeout recovery read, which otherwise re-hung the command it exists to rescue
• add readAssistantTextsAfterIndex(): count turns in-page, serialize only turns after the baseline
• keep emitting the poll heartbeat while reads stall, since silence with a live process was the original symptom
• surface assistant-dom-read-timeout:<n> on the timeout envelope so a stalled read is distinguishable from ongoing generation

A read that exceeds its budget retries on the next tick; at the deadline the existing recoverable provider.poll-timeout envelope is returned, so poll and sessions resume semantics are unchanged.

Two judgment calls worth review:

• Exhausting the budget exactly at the loop boundary is treated as the deadline itself, not a DOM-read failure, so ordinary timeouts are not mislabeled as stalls.
• When reads were already stalling, the recovery read uses a shorter (2s) budget so recovery cannot extend the command by another full ceiling.

The trimmed read falls back to the full read whenever it observes no turns, keeping pages that cannot serialize the object argument on the previous behavior.

---

Verification

Full suite, integrated, with Playwright's pinned Chromium installed so nothing is skipped:

npx playwright-core install chromium     # matches playwright-core 1.58.2 (build 1208)
npx vitest run test/unit test/integration test/e2e

  main (a03de27):  161 files, 1437 passed
  this branch:     163 files, 1454 passed, 0 skipped

All 1437 baseline tests still pass; the delta is the 17 new tests. Also green:

npm run gate:all                  # all 16 release gates
npm run typecheck                 # clean
npm run check:strict-baseline     # OK
npm run test:contract-drift       # 1 passed
npm run test:eval                 # 32 passed
npm run test:eval-fixtures        # regressions: []
npm run test:mcp                  # 45 passed
npm run test:trace-policy         # 42 passed
npm run test:source-audit         # 14 passed
npm run smoke:bins                # ok
npm run check:module-graph        # 356 files, max tier 11
bash structure/check-doc-drift.sh # 164 passed
bash structure/verify-counts.sh   # 76 passed (str_func.md refreshed via fix:counts)

typecheck:checkjs / typecheck:checkjs-dom have pre-existing errors on main; I diffed per-file error counts against the a03de27 baseline and this branch adds none.

New tests

• test/unit/web-ai-chatgpt-family-wiring.test.mjs — asserts at the module boundary that the alias reaches selectChatGptModel and the probe, that omitting it keeps the zero-mutation contract, and that an unsupported family fails closed without touching the page
• test/unit/web-ai-assistant-read-deadline.test.mjs — drives pollWebAi with a page.evaluate() that never resolves and asserts the command still honors its deadline and reports the stall; also covers the budget helpers and proves historical turns are no longer re-serialized

Both were checked against the unfixed code: dropping the family argument fails the wiring test, and removing the read bound makes the poll test hang until the runner's own timeout.

Live Chrome check

Because the deterministic tests use stub pages, I also ran both read paths against real Chrome over CDP on a ~2 MB, 40-turn conversation:

	full read (old)	post-baseline read (new)
evaluate time	64 ms	2 ms
serialized	1,980,271 chars	49,507 chars

That is ~1.93 MB of text no longer serialized per 500 ms tick, and the trimmed read still reports the correct total turn count (40).

End-to-end on a real Playwright page whose assistant read never resolves:

requested timeout: 5s
actual elapsed:    7.1s
status:            timeout (ok: false, recoverable: true, retryHint: poll-or-resume)
warnings:          ["assistant-dom-read-timeout:2"]

Before this change that call did not return at all. The 2.1s overshoot is the intentional post-timeout recovery read under its 2s budget.

Not verified

I did not reproduce the original failure against a live ChatGPT conversation with 40–60 KB assistant answers, so the real-world stall threshold remains unmeasured; the deadline behavior itself is covered deterministically and against real Chrome.

One existing fake page in web-ai-provider-session.test.mjs keyed its answer sequence off a raw evaluate call count, so it now keys off the assistant-read argument shape instead. Its assertions are unchanged.

[dbc-hbin]

Rebased onto main at v0.1.19 (1463a53) to clear the merge conflict, which was only the structure/str_func.md line-count rows; resolved with npm run fix:counts. No code changes in the rebase, and both commits are still separate.

Re-verified on top of v0.1.19:

npx vitest run test/unit test/integration test/e2e

  origin/main (1463a53):  162 files, 1448 passed
  this branch  (4ada9cb): 164 files, 1465 passed, 0 skipped

All 1448 baseline tests still pass; the delta is the 17 new tests. Also green: npm run gate:all (16/16), typecheck, check:strict-baseline, check-doc-drift.sh (164), verify-counts.sh (76).

The Contract Drift Check workflow shows action_required because this is a fork PR and needs maintainer approval to run. I ran its four steps locally against this commit:

npm run test:contract-drift                              # 1 passed
npm run test:eval                                        # 32 passed
npm run test:eval-fixtures                               # regressions: []
AGBROWSE_DRIFT_MODE=fixture npm run eval:web-ai:fixtures # ok: true, regressions: []

Note for whichever order you merge in: nothing here touches the new postinstall star-prompt work from v0.1.19.

[lidge-jun]

Thanks for this PR — both fixes were real, and both shaped what landed. We could not take the patches directly: dev's assistant reader was already refactored to the split snapshot reader (web-ai/chatgpt-response-dom.mjs:297), so the #88 hunks no longer apply, and the trimmed read would break the wrapped/wrapperless correlation. Instead dev carries independent implementations covering both commits: --family now reaches the model probe fail-closed and MCP rejects non-ChatGPT family combinations (76e4793), and every assistant DOM read, recovery read, and session-store write is bounded by the polling deadline (8a971ff through 107233e — see devlog/_plan/260731_webai_poll_deadline/). Closing in favor of those; the campaign devlog credits this PR as the trigger.