Skip to content

refactor: fold the crew log agent door's offload, re-check and respond into one helper - #13485

Merged
bolichen97 merged 2 commits into
mainfrom
fix/crew-log-agent-door-helper-12360
Sep 26, 2026
Merged

bolichen97 merged 2 commits into
mainfrom
fix/crew-log-agent-door-helper-12360

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

1. What is the problem?

The crew log agent door has four unit-keyed read routes. Three of them run the same
sequence once the gate has admitted the caller: build the payload off the loop, map a
storage refusal to a response, re-check that the grant still holds, then answer. That
sequence was written out three times in src/kiro_crew/dashboard/handlers/crew_log.py,
and the three copies differed only in the callable they offload, the operation name
they audit under, and the one keyword the re-check takes (listing=True against
unit=unit).

Two of the four steps had no cover at all. CrewLogError did not appear once in
test/test_crew_log_routes.py, so the mapping from a storage refusal to a 400 / 409 /
422 was unguarded at all three routes. And nothing asserted the ORDER of the last two
steps -- only that a withdrawn grant produces a 403, which a route that shaped its
answer first and returned the refusal afterwards would also produce.

The guard that was there scanned the module's source for the re-check's presence inside
each route that suspends. It caught an omitted line, but it could not catch a route that
calls the re-check in an order of its own, because such a route passes the scan.

2. Why this issue matters to the user

Nothing is open today: all three routes do all four steps, in order. What is at risk is
the next route. The re-check exists because the payload read is a suspension point, so a
caller can acquire a channel link while its read is in flight and receive another
session's log content into a published thread. A route added later that suspends and
answers without re-checking reads correctly in review -- the defect is an absent line --
and the same is true of one that re-checks after it has already shaped the answer.

The unguarded refusal mapping has a smaller but live cost: a route that lost it would
answer a malformed unit id or an unparseable log line with a 500 and no code, and the
agent proxying the read has nothing to branch on.

3. How our fix solves it

The three steps after the gate are now one helper, _offload_then_recheck, and the
chain from symptom to cause runs like this.

The symptom is a sequence a future route can get wrong. The cause is that the sequence
lived at the call sites, so getting it right was each route's own responsibility and
"answered without re-checking" was a shape a route could write. The fix removes the
shape: the helper takes the read (bound with functools.partial) and the route's
payload shaping as arguments, and calls the shaping only after the re-check has held. A
route therefore never holds the payload, and the order is not its to get wrong.

Folding the shaping in is a deliberate step past what the issue sketched, which left the
shaping at the call site after a two-value return. A two-value return leaves a route
holding a payload alongside a refusal it must remember to return first -- a mistake the
code today cannot make. The shaping function still belongs to the route; the helper only
calls it.

Each route keeps everything outside those three steps, unchanged: the gate, the env-flag
check, all pre-offload validation (bad_range on the listing and the page,
unknown_projection / the owner-served refusal / slot_projection on the fold), and its
own shaping -- the page's 404 unknown_unit for a unit with no log, the fold's
session_id wrapper key, and the listing's bare pass-through. The three routes behave
verbatim as before.

api_crew_log_resolve is the fourth agent-door route and is untouched. It authorizes and
then answers from memory without suspending, so it has no payload read to re-check
after and no step missing -- worth stating plainly, because the route reads like the one
outlier in the set.

The cookie-gated browser routes (api_session_crew_log and its two siblings) are also
untouched. They stand on a different authorization model -- require_owner_dashboard_request
on the owner's own cookie -- and never call _authorize_crew_log_read, so they are not in
this helper's set.

debug.py is a deliberate deferral, and an earlier draft of this section understated it.
Its _stale_grant_refusal is a different function over a different store, but the shape
and the risk are the same: five debug read handlers run authorize, offload, re-check,
answer, and the only thing holding that order is a string-presence scan asserting the
re-check's name appears in each handler's source -- the weak form this PR replaces, and
debug.py:578 states the same channel-mirror window in its own words. They are not folded
here because the contract differs: that re-check is synchronous, it takes a per-route
reads_past_own policy flag the crew-log version has no equivalent of, and one of the five
offloads at four different points depending on mode, so "the read" is not one callable
there. Tracked as #13526, which carries the five call sites, the presence scan, and the
suggested shape.

4. What tests we did

The acceptance bar for a refactor is that behaviour does not move and that every folded
step is still provably present, so each step was deleted in turn and the file re-run.
One mutation, one intended detector:

mutation reds caught by
drop the offload 48 the route suites broadly
drop the refusal mapping 5 the four mapping cases and the wired-route case, nothing else
drop the re-check 9 seven grant-withdrawn cases, the source scan, the order case
drop the shaping call 5 the page 404, the fold wrapper, the audit, the payload-identity case
shape before re-checking 1 the order case alone

The last row is the one the file could not see before: shaping first and returning the
refusal afterwards turns exactly one test red, and it is new. The counts above are a
measured run of each mutation against this revision, not an estimate -- each entry is
applied to _offload_then_recheck, the one file is re-run with -n0, and the source is
restored and checked back against its digest before the next entry. CI cannot reproduce
them, because CI runs the tests and not the mutations.

New cases, in TestTheOffloadHelperOwnsTheOrder:

  • the refusal mapping, parametrized over invalid_id -> 400, unknown_entry_type ->
    409, another code -> 422, and an empty code -> 422 with crew_log_error;
  • a withdrawn grant returns the refusal and the route's shaping is never called;
  • a held grant hands the shaping the identical payload object;
  • the page route reaches the mapping for its own read, so a route that stopped
    offloading through the helper would not keep that cover.

The source scan is restated as two rules a new route cannot satisfy by accident: the
re-check has exactly one caller, and the gate and that helper are the only two places an
agent-door route may suspend. The second rule is stated as the allowed suspension points
rather than as the storage calls to look for, because suspension has three spellings --
await, async with, async for -- and a rule naming asyncio.to_thread admits a route
that offloads through run_in_executor, awaits a storage coroutine, or gathers one. Both
rules were tested by writing the route they exist to refuse: one that offloads on its own,
one that re-checks by hand, and one that suspends through run_in_executor. All three are
refused, and the last is measured against both forms of the rule -- the call-spelling form
admits it, the suspension-point form names it back. api_crew_log_resolve is the control:
it is in the agent-door set, awaits the gate alone, appears in none of the rules, and is
still admitted.

test/test_crew_log_routes.py: 186 passed (179 before, 7 added), run with -n0.
flake8, isort, mypy on the handler, the black gate, the sync-IO-in-async gate, the
brand gate and the comment-history gate all pass on this diff.

Two Windows backend shards are red on this revision and neither failure is in this diff.
test/test_crew_log_crew_emitter.py::test_a_worker_report_through_the_route_records_the_answer
is #13444, reproduced on unrelated heads (PRs #13494 and #13492 carry the identical
assertion). test/test_diag_procs.py::test_the_gil_hint_can_fire_through_the_read_path is
#13134, a rate assertion that reads the real clock and drifts on a slow runner. This diff
changes two files; both failing files are byte-identical to main, so rebasing cannot
move either one.

5. Any other suggestions on the work

The re-check's caller count is now load-bearing, which the scan states but the helper's
own docstring is the better place for a reader to meet it. If a later route needs the
payload before it can decide the response -- something none of the three needs today --
the honest move is to widen the shaping function's contract rather than to return the
payload to the route, because returning it is what reopens the order.

Closes #12360

@chenmingwei23
chenmingwei23 requested review from a team and patrigao September 24, 2026 19:13
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 24, 2026
@github-actions

github-actions Bot commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

Verify follow-up #13526 exists and carries the debug.py deferral this PR leans on — I could not confirm it from here.

[DESIGN-REVIEWED] b1ca796

@github-actions

github-actions Bot commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of b1ca796d80575193b17a023bda2e7dadd03a8895 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] b1ca796

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

@github-actions

github-actions Bot commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of b1ca796d80575193b17a023bda2e7dadd03a8895 — 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

Confirm #13526 exists and names debug.py's five deferred sibling sites (808, 1024, 1103, 1160, 1199) — the only unfixed half of the root cause.

What this change ships

Inventory (6 items) — 6 justified

Intent: make "answered under a stale grant" a shape a future crew-log route cannot write, by folding the shared post-gate sequence into one helper and pinning the order — a FIX (guard-gap), no behavior change.

  1. Three routes' offload / refusal-map / re-check / answer sequence now lives in one helper — justified
  2. Source-scan guard restated: re-check has one caller; door routes suspend only at gate and helper — justified
  3. Storage-refusal → 400/409/422 mapping gains test cover it never had — justified
  4. Re-check-before-shaping order gains its first test — justified
  5. Page route's wiring through the helper pinned — justified
  6. Resolve route asserted as the no-suspend control — justified

Counts run: _offload_then_recheck — 3 consumers; _stale_grant_refusal siblings in debug.py — 5, declared and deferred to #13526.

[FIRST-PRINCIPLES-REVIEWED] b1ca796

@github-actions

github-actions Bot commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] b1ca796

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

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

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition of the two advisory findings on b0440679789f5b7b5fabeb79a1c61306fbe92edf,
plus the two reds that are not in this diff. New head 3a1ed5fe08a3016283724a05e55333de8854b96a.

Design Review: the suspension check only detected to_thread -- fixed

The finding is real and it was load-bearing, because the whole claim of this PR is that a
door route cannot answer under a withdrawn grant. A rule that looks for
asyncio.to_thread states the wrong thing: suspension has three spellings in Python
(await, async with, async for), so a route offloading through run_in_executor,
awaiting a storage coroutine, or gathering one satisfied the pin while still holding a
suspension point the re-check never sees.

The pin now states the allowed suspension points instead of the calls to look for: the
gate and _offload_then_recheck are the only two an agent-door route may hold, and
anything else that suspends is named back in the failure message. async with and
async for in a door body are refused outright.

Measured rather than argued. A run_in_executor suspension was added to
api_crew_log_resolve and both forms of the rule were evaluated against it:

OLD to_thread-only predicate flags it: False   <- admitted
NEW suspension-point predicate flags it: ['loop.run_in_executor']   <- refused

and the test itself then fails with
api_crew_log_resolve suspends at ['loop.run_in_executor'], outside the gate and the helper.
Mutation reverted; api_crew_log_resolve stays the control, since it awaits the gate
alone and so is admitted by every rule while appearing in none.

First Principles: the mutation counts were author-asserted -- re-measured, and two were wrong

Fair challenge, and it found something. Each mutation was re-applied to
_offload_then_recheck against this revision, the one file re-run with -n0, and the
source restored and checked back against its digest before the next entry:

mutation reds asserted before reds measured
drop the offload 44 48
drop the refusal mapping 2 5
drop the re-check 9 9
drop the shaping call 5 5
shape before re-checking 1 1

The refusal-mapping row was the real error: it is the four parametrized mapping cases
plus test_a_route_reaches_the_mapping_for_its_own_read, not two cases. The offload row
was undercounted the same way. Both rows are corrected in the PR body, which now also
says the counts are a measured run and that CI cannot reproduce them, because CI runs the
tests and not the mutations.

The two rows that matter for the acceptance bar are unchanged and still discriminate
exactly as claimed: dropping the re-check reddens 9, and shaping before the re-check
reddens exactly 1 -- test_the_shaping_never_runs_when_the_grant_was_withdrawn, alone.

Two Windows shards are red and neither failure is in this diff

This diff changes two files. Both failing test files are byte-identical to main, and the
branch's own diff against its merge base is those same two files, so there is no overlap
and rebasing cannot move either red.

Both issues are open and labelled claimed, so neither is patched from here.

@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 Sep 24, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Answering the standing Design advisory on 3a1ed5fe08a3016283724a05e55333de8854b96a
("confirm the two red Windows shards match #13444/#13134 on an unrelated head"). Both
confirmed, measured this cycle by reading other open PRs' failing shard annotations.

#13444 -- PR #13502, an unrelated head, carries the byte-identical assertion:

test/test_crew_log_crew_emitter.py::test_a_worker_report_through_the_route_records_the_answer
  AssertionError: assert {'from': 3, ...} == {'from': 1, ...}

That is now three unrelated heads (#13494, #13492, #13502), which matches the issue's own
title: it fails on every PR.

#13134 -- the test red on this head has changed since the last report, and it is a
different sibling in the same file: test_an_unchanged_process_still_gets_its_rate,
assert 46.04051565377478 == 50.0 +/- 1. That is exactly the shape #13134 generalizes to,
a percentage derived from the real clock compared against a fixed value with a +/-1
tolerance, and #13134 already records that shape on three unrelated heads (#13149 on
Linux, #13106 and #13237 on Windows), so it is not Windows-only either.

One related observation, stated separately because it is not the same assertion: PR #13512
is currently red on test/test_diag_procs.py::test_a_read_refused_as_too_soon_does_not_restart_the_window
with AssertionError: 0.8s apart is under the floor. Same file and the same underlying
cause -- a timing assumption that real runner time invalidates -- but a floor check rather
than a +/-1 rate tolerance, so I am not counting it as an instance of #13134's assertion.

Nothing here is in this diff. The branch's own change against its merge base is two files,
and both failing test files are byte-identical to main.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition of the First Principles CONCERNS on 3a1ed5fe08a3016283724a05e55333de8854b96a
(Item 1, debug.py's five sibling sites). The finding is correct and I checked every claim in
it against the source before acting:

  • _stale_grant_refusal is defined at debug.py:569 and called at 808, 1024, 1103, 1160,
    1199
    -- the five line numbers the review gave, exactly.
  • each is preceded by its own offload: 807, 1020, 1079/1081/1090/1093, 1159, 1185.
  • debug.py:578 does state the same risk in its own words, the channel mirror acquired
    inside the read's window.
  • the guard really is a presence scan: test/test_mcp_debug.py asserts
    "_stale_grant_refusal" in src for each of the five handlers, which is the form this PR's
    description calls insufficient -- it cannot see a route that re-checks after it has shaped
    its answer, nor one that suspends by a different spelling.

So the PR body's earlier wording -- that debug.py "shares only a name and guards a
different store" -- was understated. The store does differ; the shape and the risk do not.
That sentence is rewritten.

Taken as accepted-and-deferred, on the clearing condition the review itself named. Filed as
#13526, which carries the five call sites, the offload line for each, the presence scan,
the reason it is a separate change (that re-check is synchronous, it takes a per-route
reads_past_own policy flag, and api_debug_threads offloads at four points depending on
mode, so one bound callable does not describe its read), and the suggested shape. The PR
body now records the deferral and links it.

Not folded into this diff, which stays at two files. Folding five sites whose helper needs a
different contract is its own change, which is what the review concluded too.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Rebased onto main 958e43fcc9e1, new head a8e862dae6de0e2d3e8ac350be5fe5be059feb83.

Why: #13444 was closed and its fix is in this base, so the Backend Tests (3.12, 2)
red disclosed earlier should clear here. Verified at the file level rather than from the
issue state: on main test/test_crew_log_crew_emitter.py went 20970 -> 22841 bytes, 25 ->
27 tests, and its monkeypatch sites now use restoring forms.

The rebase is content-neutral. Same two files
(src/kiro_crew/dashboard/handlers/crew_log.py, test/test_crew_log_routes.py), both
blobs byte-identical to the previous head, new merge base equal to main's head, and
test/test_crew_log_routes.py still 186 passed with -n0.

A different base-owned red appeared with the new base, and it is not in this diff:

Backend Tests (Windows) (1)
src/kiro_crew/apps/builtins/code_review_sage/tests/test_learning.py::TestCandidateLockSpansProcesses::test_concurrent_processes_both_land
  AssertionError: 1 != 0 : replace(tmp, target)
  child: PermissionError [WinError 5] ...\learnings\common\tmp*.tmp -> ...\learnings\common\learned-patterns.md

Filed as #13576 with the mechanism. Short version: store.atomic_write_locked takes
its not _CAN_PIN_DIR branch on Windows (marked # pragma: no cover), the
learned-patterns.md namespace-init write sits outside the _candidate_lock that
serialises candidate.md, and six concurrent children each replace that one destination
-- which POSIX rename tolerates and Windows os.replace refuses. It arrived with
ddceef5897 (#13298): the test file is byte-identical across the two bases while
store.py and atomic_write.py changed, and it reproduces on PRs #13553 and #13545.

test/test_diag_procs.py's timing class (#13134) is still open and may still red a
Windows shard; that disposition is unchanged. Still no [BLOCK-MERGE] on any head, and the
debug.py deferral stands at #13526.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition of the two advisories on a8e862dae6de0e2d3e8ac350be5fe5be059feb83.

First Principles: "verify the deferral is real" -- verified

Fair check, since the unfixed siblings rest on that pointer. #13526 is open and read back
just now: it carries all five debug.py call sites (808, 1024, 1103, 1160, 1199), names
all five handlers (api_debug_gateway, api_debug_refusals, api_debug_threads,
api_debug_processes, api_debug_snapshots), and quotes the presence scan
(assert "_stale_grant_refusal" in src) that is the reason it is a separate change. Not a
title-only pointer.

Design: allowed_awaits fails closed on attribute-form awaits -- correct, and deliberate

The reading is right. allowed_awaits holds two BARE names, and the comparison is against
whatever the await resolves to:

  • ast.Name call -> the bare id, so only the gate and the helper match;
  • any other call form -> ast.unparse(awaited.func), e.g. loop.run_in_executor, which is
    never in a set of bare names, so it is always flagged;
  • an await of a non-call -> name stays "", also never in the set, flagged as the
    unparsed expression.

So every suspension except those two bare-name calls is refused. That is the intended
direction: the rule exists to name new suspension points, not to enumerate allowed
spellings, and the dotted branch is there to REPORT the offender legibly, not to admit it.

The failure mode the review is pointing at is real though: a future editor could read the
ast.unparse branch as "dotted names are compared too" and add a dotted entry to
allowed_awaits, quietly converting a fail-closed rule into an allowance.

Deferring the one-line note rather than pushing for it, on this reasoning: it is a
comment-only change to a rule that already behaves correctly, and a push re-rolls four
non-deterministic review lanes that are all currently clean on this head (Design PASS,
First Principles PASS, GPT 5.6 no blocking findings). Trading a settled board for a comment
is the wrong way round. If a push happens on this PR for any other reason, the note goes in
with it. Recording the property here so the knowledge survives either way: allowed_awaits
is a set of bare names by design; a dotted entry added to it would not widen the rule so
much as break its contract, because the dotted string only ever comes from the reporting
branch.

Board

Backend Tests (3.12, 2) is GREEN on this head, which is what the rebase was for -- #13444's
fix is in this base. The one red left, Backend Tests (Windows) (1), is #13576 and is not in
this diff.

@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 Sep 24, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Final state on a8e862dae6de0e2d3e8ac350be5fe5be059feb83. Board settled; nothing left that I
can move.

Checks: 91 lanes, 79 success, 11 skipped, 1 failure. Nothing queued, nothing in
progress, zero superseded-cancelled attempts (both dedupe views agree: newest-per-name and
newest-per-(name, external_id)).

Reviews: all four clean on this head -- Design PASS, First Principles PASS, GPT 5.6 no
blocking findings, Opus 5 no blocking findings. No [BLOCK-MERGE] from any bot on any head.

PR Readiness: failure, one blocking item, and its lane verdict names it precisely:

passed=[Fast Gate Build Code Review CodeQL Internal Content Scan Opus 5 Review
        GPT 5.6 Review Design Review UX Review First Principles Review Security Scope Review]
pending=[]  failed=[CI (failure)]

Eleven lanes passed, nothing pending, and the one failure is CI -- which is red solely
because of the single shard below. mergeable is MERGEABLE.

The only red is not in this diff: Backend Tests (Windows) (1) on
code_review_sage/tests/test_learning.py::TestCandidateLockSpansProcesses, a Windows
os.replace race on learned-patterns.md. Filed as #13576 with the mechanism; it arrived
with ddceef5897 (#13298) in this base and reproduces on PRs #13553 and #13545. This diff
is two crew-log files and touches none of it.

What the rebase bought: Backend Tests (3.12, 2) is green here. It was red before the
rebase as #13444, whose fix is in this base.

Remaining blocker is a human approval -- reviewDecision: REVIEW_REQUIRED, patrigao
requested. Merging is not mine to do.

One incidental observation from driving this, recorded here rather than as a fourth issue in
a family that already has three (#13252, #13363, #13456): the readiness status sat on a
stale pending that claimed CI and Build were still queued long after both finished. A
re-run then failed at its own publish step -- Failed to publish the readiness status ... The POST is not retried -- after its reads hit a transient API error. Because the POST failed,
the [read-failed] token that pr-readiness-sweep.yml keys on was never published either,
so the sweep had nothing to match and the wrong status would have stood indefinitely. A
second re-run published the verdict above. Not filed separately: seen once, cleared on
retry, and the same symptom from other causes is already tracked.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Correction to my earlier comment on this red. Two things in it were wrong.

#13576 was a duplicate and is closed. The live tracking is #13528 ("concurrent
learning stagers flake in atomic_write_locked, whose Windows path takes no lock"), open
and claimed, with the fix in PR #13551 ("fix(sage): serialize the data-layout
self-heal across processes"), currently open and not merged. Point at those, not at #13576.

My dedup missed #13528 even though it was in the issue list I fetched: every term I searched
came from my own framing -- the test node id, the file path, the error string -- while
#13528's title names the function on the failing path (atomic_write_locked) and
paraphrases the symptom. None of my terms matched it.

My mechanism attribution named the wrong frame. I said the unlocked write was namespace
initialisation, via learning.py:185 / create_namespace. It is not: create_namespace
writes below namespaces/<name>/. The racing write is the data-layout self-heal in
store.ensure_layout, which seeds common/learned-patterns.md before any candidate lock is
taken, so six fresh-root processes each see it missing and each enter the Windows replace
path.

What I had right stays right: the destination (learned-patterns.md), the Windows-versus-POSIX
asymmetry (POSIX rename over an open file succeeds, Windows os.replace raises WinError 5),
and that it is base-owned and reproduces on unrelated heads. What I had wrong was which
caller does the unlocked write.

PR #13551's own diff states the underlying point better than I did: it adds a cross-process
layout_lock built on platform_compat.file_lock, and amends atomic_write_locked's
docstring to say callers ALSO own mutual exclusion -- the locked in that function's name
refers to its temp file, not to exclusion between processes.

Effect on this PR: none of the state changes. Backend Tests (Windows) (1) is still the
only red, still not in this diff, and still base-owned; the difference is only which issue
tracks it. Once PR #13551 merges, a rebase onto that main should clear it and leave the board
green apart from the missing approval.

…d into one helper

Three of the four unit-keyed reads on the agent's door run the same sequence
after the gate admits the caller: build the payload off the loop, map a storage
refusal, re-check that the grant still holds, answer. The three middle segments
were identical apart from the callable they offload, the operation they audit
under and the one keyword the re-check takes, so the sequence is now one helper,
``_offload_then_recheck``, and each route hands it the read and its own payload
shaping.

The shaping is passed in rather than done after the call, so a route never holds
a payload before the re-check has passed and cannot answer out of order. The
route keeps everything outside those three steps: the gate, the env flag, all
pre-offload validation, and the shaping function itself.

Behaviour is unchanged at all three routes. ``api_crew_log_resolve`` keeps its
own shape: it answers from memory rather than suspending, so it owes no
re-check.

The source-scan guard is restated against the choke point -- the re-check has
exactly one caller, and no agent-door route suspends by itself -- which also
refuses a route that re-checks by hand in an order of its own. New cases pin the
storage-refusal mapping, which had no cover, and pin that a withdrawn grant
stops the route's shaping from running at all.

Closes #12360
@chenmingwei23
chenmingwei23 force-pushed the fix/crew-log-agent-door-helper-12360 branch from a8e862d to dd6cf3f Compare September 25, 2026 05:59
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 25, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/crew-log-agent-door-helper-12360 branch from dd6cf3f to 4bce0e0 Compare September 25, 2026 06:16
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 25, 2026
…spelling

The source scan asserted that no agent-door route reaches storage by
`asyncio.to_thread`. Suspension has three spellings -- `await`, `async with`,
`async for` -- so a route that offloads through `run_in_executor`, awaits a
storage coroutine, or gathers one satisfies that assertion while still being
able to answer under a grant taken before the read.

State the rule from the other side: the gate and `_offload_then_recheck` are
the only two suspension points a door route may hold, and anything else that
suspends is named back in the failure. A route that genuinely needs a third
has to add it here, which is where somebody decides whether it owes a
re-check.

`api_crew_log_resolve` stays the control: it awaits the gate alone, so it is
admitted by every rule in the pin while appearing in none of them.
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition of the two advisory PASS verdicts on 4bce0e01947726bb0f0eceae8228ffdf53b2c47e, and the head that supersedes it.

Both reviewers: "confirm the two red Windows shards are red on base, not introduced by this diff"

That ask is now answered by the board rather than by argument: there are no red Windows shards. All eight Backend Tests (Windows) lanes pass on this head.

The reason is a rebase, not a change to this diff. The two shards were owned by two base defects:

So the shards were base-owned, and the evidence is that they cleared without this diff changing.

Design Suggestion: door detection escaped by an attribute-form gate call -- FIXED

This one was a real hole and I have closed it rather than deferred it.

The fail-closed treatment I gave suspensions covered only the await side. Door detection was still bare-name only, and that is the permissive direction: a route spelling its gate as self._authorize_crew_log_read(...) was not recognised as a door at all, so none of the suspension rules ever reached it. The pin claimed to be comprehensive while admitting exactly one spelling of escape.

The call collector now matches an attribute tail as well as a bare name, so both spellings name the same gate.

Measured, not argued. Against a synthetic route whose gate call is attribute-form and which then suspends on its own via loop.run_in_executor:

  • old collector: sees ['json_response']; recognises it as a door: False
  • new collector: sees ['_authorize_crew_log_read', 'json_response', 'run_in_executor']; recognises it as a door: True
  • control, a bare-name door: recognised by both, so the widening is additive and did not move the goalposts

Once the route is recognised, the existing suspension rule names its loop.run_in_executor back, which is the behaviour already pinned.

Same widening also strengthens the single-re-check-caller assertion, since an attribute-form call to the re-check would now be counted too.

What this costs

test/test_crew_log_routes.py only; src/kiro_crew/dashboard/handlers/crew_log.py is byte-identical (blob c0b98ddef1). 186 passed with -n0 on this base. Comment-history gate (selftest first), black, flake8, isort, brand and sync-IO-in-async gates all pass. Two commits, since PR Hygiene requires one or two.

Note on the seven reds that appeared and cleared on this head

Design, GPT 5.6, Opus 5, First Principles, UX, Resolve desktop matrix and Publish readiness signal all failed inside a twenty-second window at 06:16Z, every log carrying API rate limit exceeded for installation. None was a code failure and each annotation prescribed a re-run. I waited for the installation quota to recover -- measured by other PRs' review lanes completing successfully with multi-minute durations rather than by attempt count -- then re-ran them once each. All returned green and PR Readiness published success at 06:58Z.

@chenmingwei23
chenmingwei23 force-pushed the fix/crew-log-agent-door-helper-12360 branch from 4bce0e0 to b1ca796 Compare September 25, 2026 07:04
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running labels Sep 25, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Final state on b1ca796d80575193b17a023bda2e7dadd03a8895, and one red row a reviewer should not have to decode.

The required gate passed

PR Readiness is present and success as of 07:41:05Z -- "Eligible automated validation passed for this revision". Combined commit status is success. mergeable is true.

Board: total_count 91 equal to 91 rows returned, and newest-per-name and newest-per-(name, external_id) agree: 79 success, 11 skipped, 1 failure, zero cancelled, zero queued, zero in progress.

Every substantive lane is green, including all four reviewers on this exact head (Design PASS, First Principles PASS, GPT 5.6 and Opus 5 no blocking findings), Security Scope Review, PR Hygiene, CodeQL, and all eight Backend Tests (Windows) shards. No [BLOCK-MERGE] marker in any bot comment.

The one red row is a stale publisher attempt, not a check result

Publish readiness signal shows failure from 07:34:23Z. That row is mine and it is superseded:

Readiness had published a truthful pending at 07:10Z while CI, Build and CodeQL were still running. The board then went green at 07:26:38Z, but nothing re-triggered the publisher, so the status sat 16 minutes behind a green board with zero unfinished runs on the head. I re-ran the readiness workflow to re-evaluate it. That attempt died on API rate limit exceeded for installation (403 at 07:34:29 and 07:34:30), published nothing, and left this lane red.

The self-heal sweep then did the job properly: its 07:34:27Z run republished the status as success at 07:41:05Z. So the verdict this lane exists to produce is present and passing; only the failed attempt's row remains, and no later run of that workflow exists on this head to supersede it.

Why I am not re-running it again

Re-running would likely turn the row green, but the downside has reversed since my first attempt. Then, the status was pending, so a failed re-run could not make anything worse. Now the status is success, and this publisher overwrites the status with a [read-failed] pending when its own board read is rate-limited. A re-run today can therefore destroy a passing required gate to tidy a cosmetic row, on an installation whose quota has been flapping all morning (multi-minute successes at 07:37Z, ~80-second quota failures at 07:31Z and 07:34Z).

That trade is not worth taking, so the row stays red and is explained here instead.

Scope unchanged

Two commits, two files: src/kiro_crew/dashboard/handlers/crew_log.py and test/test_crew_log_routes.py. Nothing in this diff touches the readiness workflow, Windows paths, or anything the red row concerns.

@bolichen97 bolichen97 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.

Reviewed the full diff. Required gate PR Readiness is green on the current head, all CI shards pass, no blocking reviews. Approving.

@bolichen97
bolichen97 enabled auto-merge (squash) September 26, 2026 01:11
@bolichen97
bolichen97 merged commit be067a3 into main Sep 26, 2026
94 of 95 checks passed
@bolichen97
bolichen97 deleted the fix/crew-log-agent-door-helper-12360 branch September 26, 2026 01:11
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 26, 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.

crew-log agent door: fold authorize/offload/re-check/respond into one helper

2 participants