Skip to content

docs(browser_cli): stop claiming UNSUPPORTED read both bundles - #20897

Merged
chenmingwei23 merged 1 commit into
mainfrom
docs/10699-browser-cli-unsupported-docstrings
Oct 16, 2026
Merged

chenmingwei23 merged 1 commit into
mainfrom
docs/10699-browser-cli-unsupported-docstrings

Conversation

@iamwhatever

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: The UNSUPPORTED seam-verdict docstrings in browser_cli say only what the seam scan guarantees: a bundle was read and its hook is gone.

Three docstrings say an UNSUPPORTED verdict means both bundles were read. The scan stops at the first missing hook, so when registry.js is the bundle missing it, coreBundle.js is never read and the claim is false.

Why it matters

These docstrings tell a reader what an UNSUPPORTED verdict proves. Read as written, it proves both hooks were measured, so a reader can take coreBundle.js as checked when only registry.js was. A later change to the gate or its warning built on that reading would rest on a check that never ran.

Not a goal

  • Changing the scan itself: _seams_support keeps reading bundles in order and stopping at the first missing hook.

What changed (motivation → approach → change)

The claim is wrong because of how _seams_support (browser_cli/install.py) walks its seams: in order, returning at the first needle it does not find. For the lifecycle gate the first seam is registry.js and the second is coreBundle.js (main @ 6d4f2874e8, install.py L1359-L1406):

    for path, needle in seams:                    # install.py:1365
        ...
        if not found:
            return SeamSupport.UNSUPPORTED, ""    # install.py:1378
    return SeamSupport.SUPPORTED, ""
...
    return _seams_support(
        (
            (core_root / "lib" / "tools" / "cli-client" / "registry.js", ...),  # :1401, read first
            (core_root / "lib" / "coreBundle.js", ...),                         # :1404, never reached if :1378 fired on registry.js
        )
    )

Each sentence is reworded to what holds on every branch. Docstrings only; no code changes.

Site Said Says
browser_cli/install.py cli_lifecycle_env_support both bundles were read and a hook is gone a bundle was read and its hook is gone
browser_cli/launch.py _warn_lifecycle_loss both bundles read, a hook genuinely gone a bundle read, its hook genuinely gone
test/test_browser_cli_launch.py test_a_measured_missing_hook_still_names_the_installed_cli Both bundles were read and a hook is gone A bundle was read and its hook is gone

The owning spec, docs/system-specs/modules/browser.md, already says UNSUPPORTED means the serving bundle was read and a needle is gone, so it is unchanged.

Backwards compatibility

Compatible: docstrings only; no code, signature, verdict or log text changes.

Removes nothing: only wording inside three docstrings changes.

Tests

No new test: the change is prose, and no test reads either docstring. In test/test_browser_cli_launch.py only the docstring of test_a_measured_missing_hook_still_names_the_installed_cli changes; its body is untouched.

  • The seven test/test_browser_cli_*.py files: 509 passed at -n 2.
  • Determinism proof for the edited test: 20/20 at -n0; 10/10 at -n 4 --dist loadgroup --max-worker-restart=2 beside test/test_browser_cli_token.py and test/test_browser_cli_snapshots.py; the whole file in a shuffled order, seed 10533, 44 passed.
  • test/test_flake_pattern_ratchet.py: 56 passed.

Manual verification

N/A — prose only; no runtime path changes. git grep -n -i "both bundles" -- src test docs finds no remaining copy of the claim.

Related Issues

Fixes #10699

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners October 15, 2026 16:55
@iamwhatever
iamwhatever requested a review from buluoray October 15, 2026 16:55
@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision b07413ae55f373bbe899d054a24a2797c660136e touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of b07413ae55f373bbe899d054a24a2797c660136e and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] b07413a

False positive or not applicable? A repository writer can comment:
/ai-review override gpt b07413ae55f373bbe899d054a24a2797c660136e: <one-sentence reason>

@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Oct 15, 2026
The UNSUPPORTED docstrings on cli_lifecycle_env_support and
_warn_lifecycle_loss, and the test that stands in for that verdict,
said both bundles were read. _seams_support returns UNSUPPORTED at the
first bundle whose hook is missing, so when registry.js lacks its hook,
coreBundle.js is never read. Each sentence says what holds on every
branch instead: a bundle was read and its hook is gone.

Prose only; no behaviour change.

Fixes #10699
@iamwhatever
iamwhatever force-pushed the docs/10699-browser-cli-unsupported-docstrings branch from 587a2d7 to b07413a Compare October 15, 2026 23:13
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Rebased: onto main 93617e9 (from 6d4f287) to pick up #20902, the fix for main's test_acp_bindings census red (#20893), which was the only test red on 587a2d7; that head's AI lanes failed on the 16:55 UTC API rate-limit outage. No other change; CI re-running.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 15, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of b07413ae55f373bbe899d054a24a2797c660136e — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Nothing to check.

[DESIGN-REVIEWED] b07413a

Description read

[DESCRIPTION-READ] 5834e79849b401fe22c511e4507ed9cde6a483243925b6edec023abeb81178e9

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of b07413ae55f373bbe899d054a24a2797c660136e — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Nothing to check.

What this change ships

Inventory (3 items) — 3 justified

Intent: a FIX. Three docstrings now say what an UNSUPPORTED seam verdict actually proves: one bundle was read and its hook is missing. They no longer claim both bundles were read.

  1. The cli_lifecycle_env_support docstring no longer claims both bundles were read — justified
  2. The _warn_lifecycle_loss docstring no longer claims both bundles were read — justified
  3. The docstring of test_a_measured_missing_hook_still_names_the_installed_cli is reworded the same way — justified

[FIRST-PRINCIPLES-REVIEWED] b07413a

Description read

[DESCRIPTION-READ] 8b04264cfc9294232f9dcbb8a18b82343a6868a2220d8f6f8c9edf86c4b42e10

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed b07413ae55f373bbe899d054a24a2797c660136e — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] b07413a

Verdict parsed from the review's SHA-scoped output markers for commit b07413ae55f373bbe899d054a24a2797c660136e.

False positive or not applicable? A repository writer can comment:
/ai-review override fable b07413ae55f373bbe899d054a24a2797c660136e: <one-sentence reason>

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 16, 2026

@chenmingwei23 chenmingwei23 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving: readiness: passed, all lanes green, no outstanding change requests.

@chenmingwei23
chenmingwei23 merged commit 8b9618e into main Oct 16, 2026
103 checks passed
@chenmingwei23
chenmingwei23 deleted the docs/10699-browser-cli-unsupported-docstrings branch October 16, 2026 01:39
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs(browser_cli): UNSUPPORTED docstrings claim both bundles were read, but the seam scan short-circuits

2 participants