Repository navigation
docs(solutions): capture nine learnings from the dual-host and Fro Bot work - #590
Conversation
…t work ce:compound (full mode) round over the 2026-11-20/21 work: - new: Fro Bot autoheal fixes discarded (output-mode), fork-PR head checkout with the bot PAT, Biome corrupting frontmatter/CHANGELOG, stale RPC port-file leak, test env 'undefined' restore + wall-clock flakes, Bun version-scoped override, V2 TUI server discovery by pid, live-check rig isolation - updated: re-entrant dialog doc (host dialogs are now the shipped design; slashName; V2 mode:'global') - repair frontmatter of 4 brainstorm/ideation/research docs; add tests/docs-frontmatter.test.ts so a formatter can't silently break indexing - harden tests/fixtures/bin/copilot to fail on a missing fixture (#579 class) - refresh notes: OpenTUI plan completed, AGENTS.md Biome exclusions, sweep and discriminator caveats in older docs, research section 6 resolution
fro-bot
left a comment
There was a problem hiding this comment.
Verdict: PASS
This PR changes documentation, one new unit test and one test shim. It adds no runtime plugin code. I checked the new and changed docs against the current source, package.json, biome.json and .github/workflows/fro-bot.yaml, and they match. I found no blocking issues.
Review method: I loaded ce:review in mode:read-only base:origin/main, but I did not dispatch the persona agents or run the screen/merge pipeline. The diff has no production TypeScript, so I reviewed it directly against the pinned base (df8155b). Every claim below was checked against the repository files. I ran no build, lint, typecheck or test commands.
Blocking issues
None
Non-blocking concerns
tests/docs-frontmatter.test.ts:8,14-15: the frontmatter regex can match too far.^---\n([\s\S]*?)\n---\nis lazy. If a formatter or hand edit removes the closing---, it matches up to a later---horizontal rule in the body.- That could parse body text as YAML and either throw (a loud failure, which is acceptable) or pass wrongly.
- It would be tighter to assert that the captured block contains no markdown headings, or to require the closing fence on its own line followed by a blank line or the end of the file.
- The corruption mode that actually happened (re-indented keys) is caught by the current test, so this is hardening, not a defect.
AGENTS.mdarchitecture tree is missing files that the new docs cite.src/runtime/rpc-paths.tsandsrc/runtime/rpc-port-sweep.tsboth exist, and the new learnings and the two-entrypoint doc refer to them. Neither appears in theruntime/listing.tests/helpers/env.tsis cited by the test-flake doc and is not listed undertests/either.- The omission predates this PR, but this PR is what makes the docs lean on those files.
docs/solutions/build-errors/biome-markdown-formatter-corrupts-...mduses wording that goes stale.- Line 83 says "This PR also adds a
Bun.YAML.parsefrontmatter check". A durable learning should name the test file (tests/docs-frontmatter.test.ts) instead. - The doc says #588 repaired 10 docs but does not mention the four extra docs repaired here. The body of
tests/docs-frontmatter.test.tsalready lists them as covered, so a one-line mention would close the gap.
- Line 83 says "This PR also adds a
docs/solutions/best-practices/per-instance-pid-files-...md(Related section): the new bullet is followed by a blank line, so the list is split from the existing "See …" bullets. Docs formatting is off, so nothing will fix this automatically.tests/fixtures/bin/copilot(shim) behaviour change.- The shim now exits 66 when
happy-path.jsonlis missing. The old shim exited 0 with no output, so this is the right change (the #579 class). - The final exit status is now
cat's rather than a hardcodedexit 0. That is fine underset -eu. - The shim still hard-sleeps 1s, which is acceptable because it is only used by
tests/host-contract/.
- The shim now exits 66 when
Missing tests
None. The new tests/docs-frontmatter.test.ts is itself the regression guard for the Biome-corruption class. It runs under test:unit because it matches tests/*.test.ts, and Bun.YAML is already used in tests/host-contract-pins.test.ts.
A negative-path test would be optional: a small fixture string that is known to be corrupt and is asserted to throw. The suite already asserts that a corrupt block would fail, so this is nice to have only.
Risk assessment (LOW)
- Regression likelihood: very low. There are no changes under
src/,distoutput,package.jsonor workflows. The only executable changes are a test file and a fixture shim that only the host-contract matrix uses. - Security: no secrets, PATs, tokens or PII in the new docs. I grepped
docs/solutionsfor token patterns (ghp_,github_pat_,sk-…, private-key headers) and found nothing. The docs mentionFRO_BOT_PATand bearer tokens only by name. - Doc accuracy: the claims I spot-checked hold.
- The
fro-bot.yamldetails match the workflow: thepreheadstep,trusted-head-sha, theauthor_associationgates,output-mode, theapproval-backstopjob andpersist-credentials: false. - The
"brace-expansion@2": "^2.1.8"override and theprepublishOnlyscript matchpackage.json. - The Biome exclusions match
biome.json. - The dialog and registration details match
src/tui/index.tsxandstatus-dialogs.tsx. The V2mode: 'global'layer andslashName: 'copilot-status'are both present. rpc-port-sweep.ts,rpc-paths.tsandtests/rpc-port-sweep.test.tsexist, as does the log lineremoved N stale RPC port file(s) from exited sessions.tests/helpers/env.tsalso exists.
- The
- Protected artifacts: the edits under
docs/brainstorms,docs/plans,docs/researchanddocs/solutionsare in-place refreshes. None removes a document. - Changeset: none is needed. There is no user-visible change to the published package.
- Blast radius on a parent OpenCode session: none. Nothing here ships in
dist.
Run Summary
| Field | Value |
|---|---|
| Event | pull_request |
| Repository | marcusrbrown/opencode-copilot-delegate |
| Run ID | 44915879478 |
| Cache | hit |
| Session | ses_e016a9f6bffevGoK0fYJgvXS6R |
…ening) - AGENTS.md tree lists rpc-paths.ts, rpc-port-sweep.ts, tests/helpers/env.ts and tests/host-contract/, which the new learnings cite - L3 names tests/docs-frontmatter.test.ts instead of 'this PR' and records the four extra docs repaired in #590 - frontmatter test rejects a block containing a markdown heading (a missing closing fence) and pins that the Biome corruption shape fails to parse - pid-files Related list no longer split by a blank line
|
Here is how each review note was handled, in 78e5a75:
|
fro-bot
left a comment
There was a problem hiding this comment.
Verdict: PASS
This is a re-review of the new commit 78e5a75. I read the delta against 2af84b7. It only touches AGENTS.md, two docs and tests/docs-frontmatter.test.ts, and it addresses every note from my earlier review. I ran no build, lint, typecheck or test commands. I reviewed the diff directly and did not dispatch the ce:review personas, since nothing under src/ changed.
Blocking issues
None
Non-blocking concerns
tests/docs-frontmatter.test.tsheading guard is slightly broader than its comment says./^#{1,6} /malso matches a column-0 YAML comment line such as# note, which is valid frontmatter.- No existing doc trips it (the author reports 54/0), and a false failure would be loud and easy to fix, so I would leave it as is.
- If it ever fires on a legitimate comment, switch to a pattern that excludes comments or add a short allow note.
Missing tests
None. The new negative test (rejects the corruption Biome produced) pins the exact failure shape from #492, which was keys indented under a list item. The heading assertion covers the lazy-fence case.
Risk assessment (LOW)
- Review follow-ups resolved: each of my earlier non-blocking notes is addressed in the diff.
AGENTS.mdnow listsrpc-paths.ts,rpc-port-sweep.ts,tests/helpers/env.tsandtests/host-contract/.- The Biome doc now names
tests/docs-frontmatter.test.tsinstead of "this PR" and records the four extra docs repaired in #590. - The stray blank line in the pid-file Related list is gone.
- Regression likelihood: very low. The only executable change in the delta is test code, and the earlier shim change is unchanged.
- Security: no secrets, tokens or PII added. The delta is prose plus a test with synthetic YAML.
- Changeset: none needed, because nothing user-visible ships.
- Blast radius on a parent OpenCode session: none. Nothing in this PR ships in
dist.
Run Summary
| Field | Value |
|---|---|
| Event | pull_request |
| Repository | marcusrbrown/opencode-copilot-delegate |
| Run ID | 44916274319 |
| Cache | hit |
| Session | ses_e016a9f6bffevGoK0fYJgvXS6R |
fro-bot
left a comment
There was a problem hiding this comment.
Verdict: PASS
This is a re-review of b01a9d4, a merge of origin/main into the PR branch. The merge brings in only #589. The PR's own changes (22 files, +946/-109) are unchanged from the version I approved at 78e5a75. I reviewed the diff directly and did not dispatch the ce:review personas. I ran no build, lint, typecheck or test commands.
Blocking issues
None
Non-blocking concerns
None. The earlier note about the heading guard in tests/docs-frontmatter.test.ts still stands as a minor hardening idea, but it is not new.
Missing tests
None. #589 ships its own coverage in tests/host-contract-pins.test.ts (+41 lines), and I did not review it as part of this PR.
Risk assessment (LOW)
- What the merge brought in:
.github/renovate.json5gains anallowedVersions: '<=0.8.4'hold on@opentui/coreand@opentui/solid.tests/host-contract-pins.test.tsgains the matching test. Both come from main, not from this PR. - Doc consistency: the OpenTUI plan note in this PR says "The dev pin is 0.8.4 (Renovate hold in #589)". That matches the merged hold, and
package.jsonpins@opentui/coreand@opentui/solidat0.8.4and@opentui/coreat0.8.4inoverrides. - Regression likelihood: very low. The PR still changes no runtime code. Its only executable changes are the docs-frontmatter test and the fixture shim, and neither ships in
dist. - Security: no secrets, tokens or PII added.
- Changeset: none needed, because nothing user-visible ships.
- Blast radius on a parent OpenCode session: none.
Run Summary
| Field | Value |
|---|---|
| Event | pull_request |
| Repository | marcusrbrown/opencode-copilot-delegate |
| Run ID | 44916667438 |
| Cache | hit |
| Session | ses_e016a9f6bffevGoK0fYJgvXS6R |
This PR runs a
ce:compoundround in full mode over the 2026-11-20/21 work, beyond the dual-host doc that #588 already merged. It has three parallel drafters (L1–L9, every claim checked against code, PRs and git history) and a Related Docs Finder that scores each doc for overlap. All new docs scored Low or Moderate against existing ones, so they are new files. L4 scored High against the re-entrant dialog doc, so that doc is updated in place.output-modewas never set (#555)FRO_BOT_PAT(#555)slashName, V2mode: 'global'(#572, #587)Also in this PR:
tests/docs-frontmatter.test.ts: everydocs/**/*.mdfrontmatter block must parse, and solution docs must carrytitle,date,categoryandproblem_type. A formatter can no longer silently breaksystematic_search.tests/fixtures/bin/copilot: the shim now fails with exit 66 when its fixture is missing, instead of exiting 0 with no output (the A Copilot run that exits 0 with no events and no final message is reported as complete #579 class).Gates:
lintandtypecheckare clean.test:unitis 474/0, including the new frontmatter test.test:tuiis 64/0.run-host.sh v1-currentPASSES with the hardened shim.