[codex] fix(chrome): clarify daemon setup diagnostics

[vincent-peng]

Summary

• Open the side panel daemon Connect hint directly to Options -> Runtime with an allowlisted options-tab target.
• Clear the consumed ?tab=runtime target after the user switches tabs, so reload stays on the user's selected Options tab.
• Clarify Runtime daemon status for local runtime mode, missing nativeMessaging permission, missing native host, installed native host exit, and unreachable daemon/port/reload states.
• Add docs and regression coverage for targeted options tabs and daemon setup status.

Addresses #352.

Behavior proof

Live Chrome diagnostic output from the built extension loaded in a Chromium extension context, with the extension ID redacted:

{
  "browser": "chromium extension context",
  "action": "clicked #daemonHintAction in sidepanel.html",
  "openedUrl": "chrome-extension://<extension-id>/options.html?tab=runtime",
  "runtimeTabSelected": "true",
  "runtimePanelVisible": true,
  "daemonStatus": "Local companion permission missing — enable it in Runtime settings"
}

Built Chrome extension Playwright output now covers the same Connect -> Runtime flow against the packaged chrome-mv3 build:

Running 3 tests using 1 worker
✓ options opens the requested runtime tab from the URL
✓ sidepanel default stays usable with a dismissible daemon hint
✓ sidepanel daemon Connect opens Runtime setup with permission diagnostics
3 passed (8.0s)

The Options URL regression now covers switching away from a requested Runtime deep link, clearing the stale query target, reloading, and staying on the user's selected tab:

RUN  v4.1.9 /private/tmp/summarize-352-review
Test Files  1 passed (1)
Tests  3 passed (3)

Daemon status regression output covers the actionable failure states, including the follow-up installed-host exit case:

RUN  v4.1.9 /private/tmp/summarize-352-review
Test Files  5 passed (5)
Tests  31 passed (31)

The status surface now distinguishes Daemon runtime off, Local companion permission missing, Native host unavailable, Native host exited, and generic daemon unreachable states without auto-enabling Daemon mode.

Validation

• pnpm -s check
• pnpm -C apps/chrome-extension build
• pnpm -s exec vitest run tests/options.tab-controller.test.ts
• env -u NO_COLOR SUMMARIZE_E2E_HTTP_TRANSPORT=1 pnpm -C apps/chrome-extension exec playwright test -c playwright.config.ts --project=chromium tests/options.spec.ts tests/sidepanel.core.spec.ts --grep "requested runtime tab|Connect opens Runtime|permission diagnostics|sidepanel default"

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 10, 2026, 10:17 AM ET / 14:17 UTC.

Summary
The PR routes the Chrome side-panel daemon Connect hint to an allowlisted Runtime options tab, consumes that deep link after user navigation, adds state-specific daemon/native-host diagnostics, and updates docs plus unit and packaged-extension tests.

Reproducibility: yes. Current-main source and the linked report provide a high-confidence path where the side-panel Connect action opens generic Options without directing the user to Runtime diagnostics; the review did not execute that pre-fix flow locally.

Review metrics: 3 noteworthy metrics.

• Patch surface: 17 files, +404/-28. The focused fix spans production navigation and diagnostics, documentation, unit tests, and packaged-extension coverage.
• Exact-head checks: 4 successful checks. The current SHA passes the repository test matrix, Chrome extension E2E, Firefox smoke, and security scanning.
• Diagnostic states: 5 distinct states. The UI now separates runtime-off, permission-missing, host-unavailable, host-exited, and daemon-unreachable outcomes.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #352
Summary: This PR is the direct candidate fix for the linked issue's remaining Connect-flow and diagnostic ambiguity.

Members:

• canonical: Chrome extension stays in browser/local mode although daemon 0.21.3 is running #352 - The issue's latest actionable request is clearer navigation and specific daemon setup diagnostics, matching this PR.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🦞 diamond lobster
Proof: 🦞 diamond lobster
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Next step before merge

• [P2] No repair or product decision is needed; the clean, proven PR awaits ordinary maintainer merge review.

Security
Cleared: The patch introduces no dependency, workflow, secret, permission, or third-party execution changes, and the new internal tab target is fixed-allowlisted.

Review details

Best possible solution:

Merge the proven exact head through normal maintainer review, then close the linked issue when the extension change ships and ensure the matching Chrome Web Store package follows repository release policy.

Do we have a high-confidence way to reproduce the issue?

Yes. Current-main source and the linked report provide a high-confidence path where the side-panel Connect action opens generic Options without directing the user to Runtime diagnostics; the review did not execute that pre-fix flow locally.

Is this the best way to solve the issue?

Yes. The patch reuses the existing Runtime setup surface, constrains deep links to known tabs, preserves stored runtime choices, and retains fallback Options opening behavior.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 206a6f844764.

Label changes

Label justifications:

• P2: The PR fixes a bounded Chrome extension setup and recovery problem with limited blast radius and no core outage.
• rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): Redacted live Chromium output and packaged-extension Playwright output directly demonstrate the after-fix Connect-to-Runtime flow and diagnostic text.
• proof: sufficient: Contributor real behavior proof is sufficient. Redacted live Chromium output and packaged-extension Playwright output directly demonstrate the after-fix Connect-to-Runtime flow and diagnostic text.

Evidence reviewed

What I checked:

• Exact-head implementation: The reviewed head validates requested Options tabs through a fixed allowlist, forwards the optional target through the panel contract, and retains generic Options fallbacks when targeted window or tab creation fails. (apps/chrome-extension/src/entrypoints/background/panel-utils.ts:100, 530e84b0ad8b)
• Navigation compatibility: The requested Runtime tab takes precedence only for initial navigation; after the user switches tabs, the URL target is removed and reload follows the persisted selected tab. (apps/chrome-extension/src/entrypoints/options/tab-controller.ts:4, 530e84b0ad8b)
• Diagnostic behavior: Existing policy and optional-permission checks remain ahead of transport probing, while transport failures distinguish missing host, exited host, and generic daemon reachability states without changing runtime selection. (apps/chrome-extension/src/entrypoints/options/daemon-status.ts:16, 530e84b0ad8b)
• Related issue evidence: The reporter said the connection eventually recovered after reload and restart cycles, but the UI never identified which prerequisite was stale; that remaining ambiguity directly matches this PR's diagnostic scope.
• Exact-head checks and proof: GitHub reports the reviewed SHA as cleanly mergeable with successful repository tests, Chrome extension E2E, Firefox smoke, and GitGuardian checks; the PR body also includes redacted live Chromium output showing the after-fix flow. (530e84b0ad8b)
• Feature provenance: Current-main blame and symbol history attribute the existing options tab controller, daemon status checker, and options-window helper to the 0.21.3 release commit by Peter Steinberger. (apps/chrome-extension/src/entrypoints/options/daemon-status.ts:1, 288bec056698)

Likely related people:

• Peter Steinberger: Current-main blame and symbol history tie the existing Chrome options navigation and daemon diagnostic surfaces to the 0.21.3 release commit. (role: feature owner; confidence: high; commits: 288bec056698; files: apps/chrome-extension/src/entrypoints/options/daemon-status.ts, apps/chrome-extension/src/entrypoints/options/tab-controller.ts, apps/chrome-extension/src/entrypoints/background/panel-utils.ts)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Review history (7 earlier review cycles)

• reviewed 2026-07-10T13:13:50.661Z sha 088c42a :: needs real behavior proof before merge. :: [P2] Preserve the installed-host exit diagnostic
• reviewed 2026-07-10T13:30:56.401Z sha 95fad6b :: needs real behavior proof before merge. :: none
• reviewed 2026-07-10T13:38:12.942Z sha 95fad6b :: needs real behavior proof before merge. :: none
• reviewed 2026-07-10T13:46:18.590Z sha 7f7235a :: needs changes before merge. :: [P2] Consume the requested tab after initial navigation
• reviewed 2026-07-10T13:51:38.088Z sha 7f7235a :: needs changes before merge. :: [P2] Consume the requested tab after initial navigation
• reviewed 2026-07-10T14:03:40.252Z sha 530e84b :: needs maintainer review before merge. :: none
• reviewed 2026-07-10T14:09:01.879Z sha 530e84b :: needs maintainer review before merge. :: none