Repository navigation
fix(crew-log): type the session-tree edge's handle, and fix what that hid - #13007
Conversation
|
Intent: Unbreak |
Design Review (Fable 5) — ✅ PASSDesign-level review of 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 Suggestions
[DESIGN-REVIEWED] 1dc9380 |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
First Principles Review (Fable 5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS The six newly VETTED sites rest on a comment's reachability analysis, not a test — the description concedes the What this change shipsInventory (7 items) — 7 justifiedIntent: 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.
[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.
93d80cc to
1dc9380
Compare
Opus 5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
… 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.
Problem / Motivation
mainis red.test/test_crew_log_exc_info_sites.py::test_the_exc_info_sites_left_in_crew_log_are_exactly_the_vetted_onesfails on the integrated tree with nine unvetted
exc_infosites, eight insrc/kiro_crew/crew_log/session_tree_projection.pyand one insrc/kiro_crew/crew_log/emit.py. #12757 merged them at 04:35 UTC; reproduced on anunmodified
origin/mainworktree.Why it matters
Every open PR inherits it: CI evaluates
merge(branch, main), and that test is acorpus 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_edgein
src/kiro_crew/crew_log/emit.pydeclared its handlelog: Any, and both the pinand mypy read that parameter to decide what the frame holds.
The pin refuses
exc_infoin a frame that may hold aCrewLog, because a handlerthat keeps records (
caplog, aMemoryHandler) keeps the traceback, the tracebackkeeps the frame, and the handle's write lease then outlives the drop that should have
released it.
_record_session_tree_edgeholds a live handle and calledlogger.debug(..., exc_info=True);Anymade the frame look empty.Fixing that exposed a second defect in the same function:
CrewLog.headeris aproperty and this code called it. The
TypeErrorwas swallowed by the handler thatexists so a bookkeeping miss never fails a session open, so
created_atstayed0and 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
exceptand the raise". Measured, that is notthe 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
exceptthroughtb_frame.f_back. A site in a callee therefore pins a handle its CALLER holds. Twoprobes agree -- one driving the real chain, one written independently against plain
CPython -- both showing the handle surviving its drop with
exc_info=Trueand dyingwith 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 stayOUT of
VETTED.debounced write, or
store.remove_unit, none of which holds a handle. They joinVETTED, each with its call path recorded next to it.traceback, the idiom_reportalready uses.
store.log_exception_textis the package's way to do this, butemit.py is the boot-path import gate (see
_crew_log), so it may not import thestore;
session_tree_projection.pyis only ever imported lazily, so it takes thehelper at module level. The edge recorder's whole body is now one
try, so nothingcan raise into the writer job.
The annotation is pinned rather than left load-bearing and untested: every
logparameter in emit.py must be recognised by the pin's own handle check. That caught
four pre-existing
log: Anyparameters (_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, andtest_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=Trueinrecord_openedfails with
assert CrewLog(kind='session', id='s-retain-record_opened', last_seq=0) is None; same for_schedule_checkpointand for the edge recorder. Restoring thein-function import fails with
the edge recorder has a statement outside its try/except, which can raise into the writer job: ['ImportFrom', 'Try']. Revertinglog: CrewLogtoAnyfails witha 'log' parameter in emit.py is not annotated as a CrewLog. Restoringlog.header()fails withassert 0 == 1790139981797.Manual verification
N/A — unit coverage sufficient. The
f_backclaim was additionally confirmed by astandalone 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
Anydisables every static check that reads annotations todecide what a frame holds. One
Anyhere hid a lease-pinningexc_infofrom the pinwritten 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
Anyreads 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.