Skip to content

fix(crew-log): type the session-tree edge's handle, and fix what that hid - #13007

Merged
bolichen97 merged 1 commit into
mainfrom
fix/crew-log-exc-info-session-tree
Sep 23, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/crew-log-exc-info-session-tree

Conversation

@bolichen97

@bolichen97 bolichen97 commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

main is red. test/test_crew_log_exc_info_sites.py::test_the_exc_info_sites_left_in_crew_log_are_exactly_the_vetted_ones
fails on the integrated tree with nine unvetted exc_info sites, eight in
src/kiro_crew/crew_log/session_tree_projection.py and one in
src/kiro_crew/crew_log/emit.py. #12757 merged them at 04:35 UTC; reproduced on an
unmodified origin/main worktree.

Why it matters

Every open PR inherits it: CI evaluates merge(branch, main), and that test is a
corpus gate every shard runs, so one break reds all eight Linux shards plus Windows
and the Coverage Gate on PRs whose diff is unrelated. It surfaced that way on #12997,
a three-line formatting change. What the red turned out to be hiding matters more.

What changed (motivation → approach → change)

Root cause of the first two symptoms is one annotation. _record_session_tree_edge
in src/kiro_crew/crew_log/emit.py declared its handle log: Any, and both the pin
and mypy read that parameter to decide what the frame holds.

The pin refuses exc_info in a frame that may hold a CrewLog, because a handler
that keeps records (caplog, a MemoryHandler) keeps the traceback, the traceback
keeps the frame, and the handle's write lease then outlives the drop that should have
released it. _record_session_tree_edge holds a live handle and called
logger.debug(..., exc_info=True); Any made the frame look empty.

Fixing that exposed a second defect in the same function: CrewLog.header is a
property and this code called it. The TypeError was swallowed by the handler that
exists so a bookkeeping miss never fails a session open, so created_at stayed 0
and the projection ordered every sibling by 0. Nothing observable failed.

Then the pin's own model turned out to be too narrow. Its docstring said a retained
record keeps "every frame between the except and the raise". Measured, that is not
the boundary: a frame that exits while its frame object is still referenced keeps its
locals, and a retained traceback reaches the whole stack at the except through
tb_frame.f_back. A site in a callee therefore pins a handle its CALLER holds. Two
probes agree -- one driving the real chain, one written independently against plain
CPython -- both showing the handle surviving its drop with exc_info=True and dying
with the traceback rendered to text.

So the nine sites split by call path, not by file:

  • record_opened (only caller is the edge recorder) and _schedule_checkpoint
    (through apply) run under a handle-holding frame. Both render to text and stay
    OUT of VETTED.
  • the other six are reached only from the dashboard seed, the maintenance pool's
    debounced write, or store.remove_unit, none of which holds a handle. They join
    VETTED, each with its call path recorded next to it.
  • the emit.py site renders through the module-level traceback, the idiom _report
    already uses. store.log_exception_text is the package's way to do this, but
    emit.py is the boot-path import gate (see _crew_log), so it may not import the
    store; session_tree_projection.py is only ever imported lazily, so it takes the
    helper at module level. The edge recorder's whole body is now one try, so nothing
    can raise into the writer job.

The annotation is pinned rather than left load-bearing and untested: every log
parameter in emit.py must be recognised by the pin's own handle check. That caught
four pre-existing log: Any parameters (_remember, _seed_attempts,
_note_class_change, _append_body_entry) which were equally invisible to it.

Backwards compatibility

Compatible. Three DEBUG log calls change from a traceback record to the same text
rendered inline, one property is read instead of called (the call only ever raised),
and five parameters gain a type. No signature, no public contract and no stored
format moves.

Tests

In test/test_crew_log_session_tree_projection.py:
test_a_retained_projection_failure_record_does_not_keep_the_handle_alive
(parametrised over the three sites, driving a real failure with a retaining handler
and reading a weakref after the drop), test_the_edge_recorder_swallows_a_projection_failure_as_text,
test_the_edge_recorder_body_is_one_guarded_try, and
test_the_edge_carries_the_header_created_at_not_zero.
In test/test_crew_log_exc_info_sites.py:
test_every_log_parameter_of_the_emitter_is_annotated_as_a_handle.

Negative controls, each run and reverted. Restoring exc_info=True in record_opened
fails with assert CrewLog(kind='session', id='s-retain-record_opened', last_seq=0) is None; same for _schedule_checkpoint and for the edge recorder. Restoring the
in-function import fails with the edge recorder has a statement outside its try/except, which can raise into the writer job: ['ImportFrom', 'Try']. Reverting
log: CrewLog to Any fails with a 'log' parameter in emit.py is not annotated as a CrewLog. Restoring log.header() fails with assert 0 == 1790139981797.

Manual verification

N/A — unit coverage sufficient. The f_back claim was additionally confirmed by a
standalone CPython probe whose control (rendered text) does not pin, so the
observation discriminates rather than merely agreeing.

Related Issues

Unblocks #12997, whose shards surfaced this. No issue was open for it.

Pattern harvest

Rule candidate: review-prompt

Pattern: a parameter typed Any disables every static check that reads annotations to
decide what a frame holds. One Any here hid a lease-pinning exc_info from the pin
written to catch exactly that, and a property called as a method from mypy, in the same
six lines. The narrow rule: a handle, lock or lease passed into a helper must carry its
real type, because the checks guarding those objects are annotation-driven and Any
reads to them as "holds nothing" rather than "unknown". The second, larger lesson is
that a static pin's own model of reachability needs measuring: this one described the
hazard as frame-local for as long as it has existed, and the mechanism is stack-wide.

@bolichen97
bolichen97 requested review from a team and Zedmor September 23, 2026 05:13
@bolichen97

Copy link
Copy Markdown
Contributor Author

Intent: Unbreak main's crew-log exc_info pin, and fix the two defects one
log: Any annotation was hiding from it: a write lease pinned by a traceback record,
and a created_at that silently folded as 0 because a property was called as a method.
Not a goal: widening the pin's own design, revisiting #12757's session-tree
projection beyond those two lines, or changing any other Any annotation in the package.

@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

Verify the six VETTED call-path claims ("no caller holds a handle") were actually traced — nothing enforces them, and the static pin admits it cannot see f_back cases.

Suggestions

  • session_tree_projection.py now imports log_exception_text at module level anyway; rendering the six vetted sites to text too would delete the unenforceable caller-audit premise entirely, at the cost of structured exc_info on DEBUG records — worth weighing as a follow-up, not here.

[DESIGN-REVIEWED] 1dc9380

@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 1dc9380

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

@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

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

The six newly VETTED sites rest on a comment's reachability analysis, not a test — the description concedes the f_back case is not caught statically.

What this change ships

Inventory (7 items) — 7 justified

Intent: make main green again (a corpus-gate test red on every PR shard) and fix the two defects that red was hiding — a FIX; failing test on base is readable from the diff itself.

  1. The corpus-gate test failing on every PR passes again; style(test): format the webhooks API test black left unformatted #12997 unblocks — justified
  2. Session-tree siblings order by real creation time instead of all tying at zero — justified
  3. Three DEBUG failure logs carry the traceback as rendered text, so a record-keeping handler no longer pins a live handle's write lease — justified
  4. Every log parameter in emit.py names the CrewLog type, pinned by a new test; four pre-existing Any siblings fixed (0 remain in the package) — justified
  5. The pin's hazard model widens from frame-local to whole-stack, with six projection sites vetted by recorded call path — justified
  6. The edge recorder's body is one guarded try, pinned, so nothing raises into the writer job — justified
  7. Four new tests drive the real retention chain and the ordering defect — justified

[FIRST-PRINCIPLES-REVIEWED] 1dc9380

… just its own frame

`_record_session_tree_edge` took its `CrewLog` as `log: Any`. That annotation hid
two defects from the checks meant to catch them and left main red, and closing it
exposed that the pin's own model of the hazard was too narrow.

Red now: the pin in test_crew_log_exc_info_sites.py asserts the `exc_info` sites in
`crew_log` are exactly the vetted set, and #12757 added nine.

The pin's model. Its docstring said a retained record keeps "every frame between the
except and the raise". Measured, that is not the boundary: a frame that exits with
its frame object still referenced keeps its locals, and a retained traceback reaches
the whole stack at the `except` through `tb_frame.f_back`. So a site in a callee pins
a handle the CALLER holds. A probe on the real chain, and a second written
independently against plain CPython, both show the handle surviving its drop with
`exc_info=True` and dying with the traceback rendered to text.

Two of the nine sites are reached that way -- `record_opened` (its only caller is the
edge recorder) and `_schedule_checkpoint` (through `apply`). Both render to text now
and stay OUT of VETTED. The other six are reached only from the dashboard seed, the
maintenance pool, or `store.remove_unit`, none of which holds a handle; those join
VETTED with the call paths recorded.

Defect 1, a pinned write lease: the ninth site was this function's own
`exc_info=True` with a live handle in frame. It renders through the module-level
`traceback`, the idiom `_report` already uses; `store.log_exception_text` is the
package's way but emit.py is the boot-path import gate, so it may not import the
store. The whole body is now one `try`, so nothing can raise into the writer job.

Defect 2, every edge folded created_at 0: `CrewLog.header` is a property. This code
called it, the TypeError was swallowed by the handler that keeps a bookkeeping miss
from failing a session open, and the fold ordered siblings by 0. mypy could not see
it while the parameter was `Any`.

The annotation is now pinned: every `log` parameter in emit.py must be recognised by
the pin's own handle check, which also caught four pre-existing `log: Any` parameters
that were equally invisible to it.
@bolichen97
bolichen97 force-pushed the fix/crew-log-exc-info-session-tree branch from 93d80cc to 1dc9380 Compare September 23, 2026 05:55
@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 Sep 23, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 1dc9380

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable 1dc9380bcc02b4d3e81d41b4d5e080b5e9742cab: <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 Sep 23, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) September 23, 2026 07:13
@bolichen97
bolichen97 merged commit 18f9984 into main Sep 23, 2026
95 of 101 checks passed
@bolichen97
bolichen97 deleted the fix/crew-log-exc-info-session-tree branch September 23, 2026 07:15
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 23, 2026
wknight1 pushed a commit to wknight1/KiroCrew that referenced this pull request Oct 5, 2026
… just its own frame (kirodotdev#13007)

`_record_session_tree_edge` took its `CrewLog` as `log: Any`. That annotation hid
two defects from the checks meant to catch them and left main red, and closing it
exposed that the pin's own model of the hazard was too narrow.

Red now: the pin in test_crew_log_exc_info_sites.py asserts the `exc_info` sites in
`crew_log` are exactly the vetted set, and kirodotdev#12757 added nine.

The pin's model. Its docstring said a retained record keeps "every frame between the
except and the raise". Measured, that is not the boundary: a frame that exits with
its frame object still referenced keeps its locals, and a retained traceback reaches
the whole stack at the `except` through `tb_frame.f_back`. So a site in a callee pins
a handle the CALLER holds. A probe on the real chain, and a second written
independently against plain CPython, both show the handle surviving its drop with
`exc_info=True` and dying with the traceback rendered to text.

Two of the nine sites are reached that way -- `record_opened` (its only caller is the
edge recorder) and `_schedule_checkpoint` (through `apply`). Both render to text now
and stay OUT of VETTED. The other six are reached only from the dashboard seed, the
maintenance pool, or `store.remove_unit`, none of which holds a handle; those join
VETTED with the call paths recorded.

Defect 1, a pinned write lease: the ninth site was this function's own
`exc_info=True` with a live handle in frame. It renders through the module-level
`traceback`, the idiom `_report` already uses; `store.log_exception_text` is the
package's way but emit.py is the boot-path import gate, so it may not import the
store. The whole body is now one `try`, so nothing can raise into the writer job.

Defect 2, every edge folded created_at 0: `CrewLog.header` is a property. This code
called it, the TypeError was swallowed by the handler that keeps a bookkeeping miss
from failing a session open, and the fold ordered siblings by 0. mypy could not see
it while the parameter was `Any`.

The annotation is now pinned: every `log` parameter in emit.py must be recognised by
the pin's own handle check, which also caught four pre-existing `log: Any` parameters
that were equally invisible to it.
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.

2 participants