Skip to content

refactor: fold the five debug read routes onto one re-check helper - #31608

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
fix/13526-debug-read-helper
Nov 7, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
fix/13526-debug-read-helper

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Every debug read route builds its answer through one helper that re-checks the caller's grant before the route shapes or returns anything, and a test pins that shape instead of looking for a function name.

The five debug read routes in handlers/debug.py each wrote out the same four steps: authorize, build the payload off the loop, re-check that the grant still holds, answer. The only guard on that order was a test that checked each route's source for the string _stale_grant_refusal. That scan passes a route that re-checks after it has already shaped its answer, and a route that suspends some other way (run_in_executor, an awaited coroutine, async with, async for).

Why it matters

No hole is open today: all five routes do all four steps in order. The risk is the next route. The re-check exists because a caller can acquire a channel mirror while the read runs, and a route that answers without re-checking would publish host-wide state into that mirror. A name scan cannot catch that mistake.

Not a goal

  • Changing what any debug route answers: status codes, bodies, redaction and the reads_past_own decision stay as they are.
  • Merging this helper with the crew log one: that re-check is async and has no reads_past_own.
  • Moving each route's exception-to-status mapping into the helper.
  • Redacting refusals, which answers without redact today.

What changed (motivation → approach → change)

Before After
Who runs read → re-check → answer each of the five routes, by hand _offload_then_recheck, the only caller of _stale_grant_refusal
What a route hands over (nothing) its bound read, its own respond shaping, and reads_past_own (refusals computes it, the rest take the default)
api_debug_threads four to_thread calls across three mode branches _threads_read binds the requested mode into one read
The guard a string-presence scan two route-shape rules, the same ones the crew log door uses (#13485)

The helper calls respond only after the re-check holds, so a withdrawn grant reaches the caller as the 403 and the route's shaping never sees the payload. Each route keeps its gate, its early exits (400, 422, 501) and its own except arms. The three diag-backed routes share _redacted_json, which is the same redact(json.dumps(..., default=str)) they each ran. gateway keeps its own shaping without default=str, as on main.

The new test parses the module and checks two things. First, _stale_grant_refusal has exactly one caller, _offload_then_recheck. Second, every function that calls _authorize_debug_read suspends only at the gate and the helper. An await of anything else is named back in the failure, and so are async with, async for and async comprehensions. A control asserts the five routes are the ones that go through the helper.

Backwards compatibility

Compatible: every route answers the same status and body for every request it answered before; the only difference is which error a failure in the shaping step reports. In threads and snapshots the route's except arms now surround the helper call, so a ValueError/OSError raised while serialising an already re-checked payload (a circular reference, say) is answered with that route's 400/503 instead of an unhandled 500. Neither carries the payload.

Removes nothing: the presence-scan test is replaced by a stricter one, and the only symbols added are private (_offload_then_recheck, _redacted_json, _threads_read).

Tests

  • test_a_debug_route_can_only_answer_through_the_recheck replaces test_every_offload_is_followed_by_a_stale_grant_recheck. It fails on main, where five routes call the re-check. Checked by hand against three mutations: shaping before the re-check, a run_in_executor await in a route, and an async comprehension in a route. Each one fails it by name.
  • test_the_shaping_never_runs_when_the_grant_was_withdrawn drives the helper with a channel-linked caller and asserts a 403 with respond never called.
  • The existing route tests stay green unchanged, including the 400/404 mappings that now pass through the helper (test_a_dump_that_vanished_between_two_reads_is_a_404, test_a_malformed_window_value_is_the_callers_error_not_a_crash) and the self-narrowed refusals read (test_a_channel_linked_session_still_reads_its_own_refusals).
  • Determinism: both new tests passed 20 times at -n0, and 10 times at -n 4 --dist loadgroup --max-worker-restart=2 beside test_crew_log_routes_facade.py and test_crew_log_routes_dispatch_fence.py. All 92 tests in test/test_mcp_debug.py passed in a shuffled order (seed 21657).

Proof: PROVEN test/test_mcp_debug.py::TestTheRouteAuthorizationShape::test_a_debug_route_can_only_answer_through_the_recheck (head 6d8c700)

Manual verification

N/A — unit coverage sufficient: the five routes are driven through their real handlers by the existing route tests, and the change has no UI.

Screenshots / video

N/A — backend-only change; no frontend path touched.

Related Issues

Closes #13526

Sibling sweep

Swept: git grep -n "_stale_grant_refusal" -- src/
Sibling: src/kiro_crew/dashboard/handlers/crew_log.py -- not affected -- the crew log door was folded onto its own helper by #13485
Sibling: src/kiro_crew/dashboard/handlers/crew_log_scope.py -- not affected -- defines the async crew log re-check; its only route caller is that helper

Pattern harvest

Not generalizable: the two route-shape rules are tied to the gate and helper each door owns, and both doors now pin their own.

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

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 6, 2026 17:52
@bolichen97
bolichen97 requested a review from Zedmor November 6, 2026 17:52
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 6, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) November 6, 2026 18:13
@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

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

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of c6b8da81578fc75f4d3bfd9184f77e993bf3524a — 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 does not.

First-Principles-Verdict: PASS

This is a refactor; nothing about what users see changes. The only behaviour change, a serialisation error now answered with 400 or 503 instead of 500, is declared and exposes no payload.

What this change ships

Inventory (6 items) — 5 justified

Intent: make it impossible for a future debug read route to answer before it re-checks the caller's grant (#13526). This is a FIX, made by restructuring the code.

  1. All five debug read routes (gateway, refusals, threads, processes, snapshots) now build their answer through one private helper that re-checks the grant first — justified
  2. The threads route turns its three modes into one prepared read instead of four separate background calls — justified
  3. The three diag routes share one redact-and-return-JSON function, the same code each one ran before — justified
  4. In threads and snapshots, a ValueError or OSError while serialising an already re-checked payload now gets the route's 400 or 503 instead of a 500 — rides along
  5. The test that only checked each route's source for the re-check's name is replaced by a test that parses the module and checks where routes call the re-check and where they pause — justified
  6. A new test shows the route's shaping never runs when the grant was withdrawn — justified

[FIRST-PRINCIPLES-REVIEWED] c6b8da8

Description read

[DESCRIPTION-READ] 8430aeb7316b5ba0f554fd4403aacb45f16008c8f64b62da5b6bcea68d5474e3

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

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of c6b8da81578fc75f4d3bfd9184f77e993bf3524a — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

No design-level concerns. This is a behaviour-preserving refactor of private helpers, and the old name-scan test is replaced by a stricter shape test.

[DESIGN-REVIEWED] c6b8da8

Description read

[DESCRIPTION-READ] 7572222c6fa426e05ff0b46af675cd85277210ac2646dcb25ded9bef08c625bb

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

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] c6b8da8

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable c6b8da81578fc75f4d3bfd9184f77e993bf3524a false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] c6b8da8

False positive or not applicable? A repository writer can comment:
/ai-review override gpt c6b8da81578fc75f4d3bfd9184f77e993bf3524a false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 6, 2026
The five debug read routes each wrote out the same four steps --
authorize, build the payload off the loop, re-check the grant, answer --
and the only thing holding that order was a test that looked for the
re-check's name in each route's source. That scan passes a route that
re-checks after shaping its answer, and one that suspends by another
spelling.

The three steps after the gate now live in _offload_then_recheck: the
route hands over its bound read, its own response shaping and its
reads_past_own decision, and the shaping runs only once the re-check
holds. api_debug_threads' four mode-dependent offloads become one bound
read. Each route keeps its gate, its early exits and its own
exception-to-status arms. Behaviour is unchanged at all five routes.

The presence scan is replaced by the two route-shape rules the crew-log
door uses: the re-check has exactly one caller, and the gate and the
helper are the only places a debug route may suspend. A second test pins
that a withdrawn grant stops the route's shaping from running at all.

Closes #13526
@bolichen97
bolichen97 force-pushed the fix/13526-debug-read-helper branch from 6d8c700 to c6b8da8 Compare November 6, 2026 23:17
@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 Nov 6, 2026
@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 Nov 7, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Approved for the on-call. Review lanes pass on c6b8da8, no conflict, no open change request.

@KiroCrewCaptain
KiroCrewCaptain merged commit c52c1eb into main Nov 7, 2026
152 of 154 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the fix/13526-debug-read-helper branch November 7, 2026 00:44
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 7, 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.

debug read routes: fold authorize/offload/re-check/respond into one helper (5 sites behind a presence scan)

2 participants