Repository navigation
feat(crew-log): fold a session's crew log into five projections and serve them - #11558
Conversation
Design Review (Fable 5) — 🟡 CONCERNSDesign-level review of Design-Verdict: CONCERNS Every "incremental" read still re-parses the whole log from the start, so per-turn push and per-GET cost grow linearly with session history. Watch
SuggestionsCache the resolved byte offset of each cached bundle's [DESIGN-REVIEWED] 90be3db |
First Principles Review (Fable 5) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS Eight public helpers ship with zero non-test consumers — groundwork for the deferred on-disk checkpoints, kept alive today only by the tests that call them. Not justified as shipped
What this change shipsInventory (10 items) — 9 justifiedIntent: let the session's on-disk crew log finally be read — the session half of RFC PR 2 (folds, paged reads, push). ADDITION, covered by
[FIRST-PRINCIPLES-REVIEWED] 90be3db |
GPT 5.6 Review — ✅ no blocking findings (all downgraded on adjudication)GPT 5.6 flagged blocking issues on This comment is updated in place on each push. Review detailsBLOCKING -- src/kiro_crew/crew_log/projection.py:1188 -- Truncation collapses distinct omitted labels Adjudication (Opus 4.8) — is blocking on each finding proportionate?Confirmed the mechanism: Harm rung: LOW.
False positive or not applicable? A repository writer can comment: |
Opus 4.8 Review — ✅ no blocking findingsReviewed Review detailsI have enough to falsify the sole candidate. Falsification of CANDIDATE 1 — the claim is that The invariant inconsistency is real at the code level:
The only way either map grows without bound is an attacker-planted or corrupted log line carrying many long, distinct No new groundable defect surfaced in No findings. [OPUS-REVIEWED] 90be3db Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
2d6b946 to
eb35b52
Compare
cac1ef0 to
4906a35
Compare
|
Red Windows shards on the previous head main-owned, #11563 -- shard 6, four tests in Neither mine nor #11563 -- shard 8, Mine, and fixed -- shard 3, |
4906a35 to
9bcff68
Compare
9bcff68 to
6bd8ff6
Compare
6bd8ff6 to
4556b5d
Compare
Board classification for
|
| Lane | Failing tests | Owner |
|---|---|---|
| Backend Tests (3.12, 1), Backend Tests (Windows) (1) | test_acp_launch_goldens |
main, #11635 |
| Backend Tests (3.12, 2), Backend Tests (Windows) (2) | test_backend_cards |
main, #11634 |
| Coverage Gate | aggregate of the four above | main, downstream |
Two further main-owned families from earlier heads of this PR are not red here: test_workflows_service::test_finished_run_busy_slot_queues_turn (#10964) and test_xdist_host_budget (#11618). A single TestSyncKillProviderTree failure seen earlier was a flake.
This head
121 tests pass in the two files this PR adds, 318 with test_crew_log_core.py. mypy, black, isort, comment-history and docs-lint clean. Design passed, Opus 4.8 reported no blocking findings, First Principles is advisory.
|
/ai-review override gpt 4556b5d: Pass 1 died on infra (SSE idle timeout, 5 failed reconnects), so pass 2's completed verdict for this SHA was discarded and the gate failed closed on a missing marker. Pass 2 emitted [GPT-REVIEWED] for this SHA with one ADVISORY finding and no [BLOCK-MERGE]. The displayed blocking body is pinned to 6bd8ff6 and both its findings are fixed here. Evidence and advisory disposition: issuecomment-5724449087. |
Human judgment recorded@chenmingwei23 marked the gpt AI finding as false positive, not applicable, or explicitly accepted for
This decision applies only to this commit. A new push requires a new judgment. |
…erve them The crew log is append-only, so every view of it is a fold. This adds the session side panel's five folds (status, usage, timeline, tools, approvals), the two reads that serve them, and the frame that pushes one when the file grows -- the backend folds and cuts pages, the client renders and pages. The incremental form is the primitive and the whole-file form wraps it, so a resumed answer and a from-scratch answer come out of one implementation. A checkpoint is (name, last_seq, state), JSON-serializable, and a replayed entry is refused rather than double-counted. Absent credits and tokens are never read as zero: each total rides beside the count of turns that reported one. An open turn and an unmatched tool call are reported open, never closed with an invented outcome. A page and a fold take opposite postures on an unknown type, deliberately: the fold declares its vocabulary so a required unknown line refuses instead of skewing a total, while the page declares none so one unfamiliar line cannot hide the history in front of it.
…nly within one file A cap on HOW MANY values a fold retains bounds nothing on its own, because each of those values is a string off the wire. Every retained string is cut to TEXT_LIMIT at the point the fold coerces it: an approval's tool and reason, a decision, a per-tool server, a tool or model name, and the status echoes of agent, owner, slot, cwd, model, provider, stop reason and error. A field whose ABSENCE is meaningful keeps it -- a close reason, a stop reason and an error read as null when unset rather than as a reason of no characters. Cutting is safe only for a string that never distinguishes one thing from another. A string used as a KEY is refused instead: one sitting exactly at TEXT_LIMIT cannot be told apart from one that was cut, so keying on it would put two unrelated tools or models in one row reporting each other's totals -- a wrong answer rather than a big value. tools.by_name, usage.by_model and a row's server list give no detail to a label at that length; it goes where a label past the count budget goes, counted in totals that stay exact and reported as omitted detail. An IDENTITY is refused at ID_LIMIT for the same reason, and both sides of a pair coerce it identically so a call and its completion agree on what an identity is. A count of omitted detail counts THINGS, not the events that mention them: a tool name reaches that path from its call and again from its completion, a model once per turn it ran, and a server once per call through it. All three counts share one bookkeeper that dedupes against a capped list, stops at the budget rather than climbing past the number of labels that exist, and exposes names_omitted_saturated / models_omitted_saturated / servers_omitted_saturated to say the figure is a floor rather than a total. A seq is only comparable WITHIN one file, and two places had to learn that. The push skips a projection whose checkpoint has not moved, but fold_session refuses a bundle whose origin does not match the file and rebuilds from the start, so a log removed and recreated can come back at the same terminal seq carrying different values; the push compares the bundle's origin first and treats every projection of a rebuilt bundle as new. And a page reports the tail it OBSERVED: a store handle's last_seq is its own cached figure, authoritative only for its own appends, so a writer growing the file after a reader handle opened was invisible to it and a page could return rows up to `to` while reporting that nothing follows. The push is a per-process singleton, so a restart inside one process rebinds it. Rebinding only the loop left it holding the retired dashboard state, counting the old hub's sockets and sending every frame to a room nobody is in. The rebind repoints the loop and the state and clears the scheduling flags, which belong to the loop going away: a timer armed there never fires and a flush marked in flight there never finishes, so a stale flag silenced the publisher permanently. Installing the push is gated on KIROCREW_CREW_LOG, and gated BEFORE the emitter is imported. start_dashboard calls the installer unconditionally, so asking the emitter whether it is enabled would import it on every disabled launch -- the cost the flag exists to avoid, not a check of it. The variable's name is spelled in the handler and a test pins it against the emitter's own constant so the two cannot drift. A close does not close a turn. A session cut off mid-turn writes session/closed with no turn/completed, and clearing the open turn asserted that the turn finished when nothing recorded it doing so, erasing the one fact a reader wants from that log. Only turn/completed closes a turn, which is the rule the render already stated. A cold fold does not materialize the whole log: the pass is taken FOLD_CHUNK_ENTRIES at a time, and each checkpoint takes only the part of a chunk it has not consumed, so one chunk serves five folds sitting at different seqs. The lazy module accessor is annotated ModuleType, because a module object is not a type and the type checker refuses it. Tests: 121 green across the two files, 318 with the crew-log core suite. Fourteen properties are mutation-verified, each turning a test red: keys made always-keyable, omitted counted per appearance, the id length guard removed, label truncation removed, the server label retained raw, a status string retained raw, the chunk bound raised past the log, page metadata taken from the cached figure, origin dropped from the change check, the state left unbound on rebind, the scheduling flags left set, the boot flag gate removed, the flag name drifted from the emitter's, and the close clearing the turn again. mypy, black, isort, comment-history and docs lint clean on the touched paths.
4556b5d to
90be3db
Compare
…erve them (kirodotdev#11558) * feat(crew-log): fold a session's crew log into five projections and serve them The crew log is append-only, so every view of it is a fold. This adds the session side panel's five folds (status, usage, timeline, tools, approvals), the two reads that serve them, and the frame that pushes one when the file grows -- the backend folds and cuts pages, the client renders and pages. The incremental form is the primitive and the whole-file form wraps it, so a resumed answer and a from-scratch answer come out of one implementation. A checkpoint is (name, last_seq, state), JSON-serializable, and a replayed entry is refused rather than double-counted. Absent credits and tokens are never read as zero: each total rides beside the count of turns that reported one. An open turn and an unmatched tool call are reported open, never closed with an invented outcome. A page and a fold take opposite postures on an unknown type, deliberately: the fold declares its vocabulary so a required unknown line refuses instead of skewing a total, while the page declares none so one unfamiliar line cannot hide the history in front of it. * fix(crew-log): bound every string a fold retains, and compare a seq only within one file A cap on HOW MANY values a fold retains bounds nothing on its own, because each of those values is a string off the wire. Every retained string is cut to TEXT_LIMIT at the point the fold coerces it: an approval's tool and reason, a decision, a per-tool server, a tool or model name, and the status echoes of agent, owner, slot, cwd, model, provider, stop reason and error. A field whose ABSENCE is meaningful keeps it -- a close reason, a stop reason and an error read as null when unset rather than as a reason of no characters. Cutting is safe only for a string that never distinguishes one thing from another. A string used as a KEY is refused instead: one sitting exactly at TEXT_LIMIT cannot be told apart from one that was cut, so keying on it would put two unrelated tools or models in one row reporting each other's totals -- a wrong answer rather than a big value. tools.by_name, usage.by_model and a row's server list give no detail to a label at that length; it goes where a label past the count budget goes, counted in totals that stay exact and reported as omitted detail. An IDENTITY is refused at ID_LIMIT for the same reason, and both sides of a pair coerce it identically so a call and its completion agree on what an identity is. A count of omitted detail counts THINGS, not the events that mention them: a tool name reaches that path from its call and again from its completion, a model once per turn it ran, and a server once per call through it. All three counts share one bookkeeper that dedupes against a capped list, stops at the budget rather than climbing past the number of labels that exist, and exposes names_omitted_saturated / models_omitted_saturated / servers_omitted_saturated to say the figure is a floor rather than a total. A seq is only comparable WITHIN one file, and two places had to learn that. The push skips a projection whose checkpoint has not moved, but fold_session refuses a bundle whose origin does not match the file and rebuilds from the start, so a log removed and recreated can come back at the same terminal seq carrying different values; the push compares the bundle's origin first and treats every projection of a rebuilt bundle as new. And a page reports the tail it OBSERVED: a store handle's last_seq is its own cached figure, authoritative only for its own appends, so a writer growing the file after a reader handle opened was invisible to it and a page could return rows up to `to` while reporting that nothing follows. The push is a per-process singleton, so a restart inside one process rebinds it. Rebinding only the loop left it holding the retired dashboard state, counting the old hub's sockets and sending every frame to a room nobody is in. The rebind repoints the loop and the state and clears the scheduling flags, which belong to the loop going away: a timer armed there never fires and a flush marked in flight there never finishes, so a stale flag silenced the publisher permanently. Installing the push is gated on KIROCREW_CREW_LOG, and gated BEFORE the emitter is imported. start_dashboard calls the installer unconditionally, so asking the emitter whether it is enabled would import it on every disabled launch -- the cost the flag exists to avoid, not a check of it. The variable's name is spelled in the handler and a test pins it against the emitter's own constant so the two cannot drift. A close does not close a turn. A session cut off mid-turn writes session/closed with no turn/completed, and clearing the open turn asserted that the turn finished when nothing recorded it doing so, erasing the one fact a reader wants from that log. Only turn/completed closes a turn, which is the rule the render already stated. A cold fold does not materialize the whole log: the pass is taken FOLD_CHUNK_ENTRIES at a time, and each checkpoint takes only the part of a chunk it has not consumed, so one chunk serves five folds sitting at different seqs. The lazy module accessor is annotated ModuleType, because a module object is not a type and the type checker refuses it. Tests: 121 green across the two files, 318 with the crew-log core suite. Fourteen properties are mutation-verified, each turning a test red: keys made always-keyable, omitted counted per appearance, the id length guard removed, label truncation removed, the server label retained raw, a status string retained raw, the chunk bound raised past the log, page metadata taken from the cached figure, origin dropped from the change check, the state left unbound on rebind, the scheduling flags left set, the boot flag gate removed, the flag name drifted from the emitter's, and the close clearing the turn again. mypy, black, isort, comment-history and docs lint clean on the touched paths.
Problem / Motivation
A session's crew log is on disk and nothing can read it.
#10091(merged as69aeb2803) landed the whole storage layer -- the envelope,seq,ref,iter_from,page,resolve, torn-tail repair -- and the flag-gated sessionemitter that writes it. What does not exist is any way to see what is in the
file: no fold, no route, no push. So a session's own history is written and then
unreadable, and the side panel RFC #10090 describes has nothing behind it.
The gap is not "add an endpoint". A caller that read the raw lines would have to
fold them itself, which means every client needing one number pulls the whole
file, and two clients folding the same bytes can disagree about what they say.
Why it matters
The crew log exists so that a session's state lives in a file rather than in a
context window. That only pays off once something reads it: until a reader can
ask "what did this session spend", "which tool calls are still open", "is this
turn still running", the file is cost with no return, and the flag has no reason
to be turned on.
It also matters that the first reader gets the reading rules right. This is an
append-only record whose whole claim is that two readers of the same bytes agree.
A first consumer that quietly treats an absent measurement as zero, or invents a
completion for a turn that was interrupted, teaches every later consumer to do
the same -- and the file cannot be corrected afterwards.
What changed (motivation -> approach -> change)
Goal: the session half of RFC #10090 section 5 -- the five folds, paged
reads, and the push -- with the reading rules stated where the next consumer will
find them.
Approach. Three decisions carry the design.
is a starting state, one step per entry, and a render.
fold(name, entries)is
advancefrom an empty checkpoint, one line. The alternative -- a batchimplementation beside a resumed one -- is two codepaths free to disagree about
one file, with nothing in the file to say which is right.
(name, last_seq, state)and is JSON-serializable, so theshape a later
projections/<key>.jsonwould carry already exists. State isdeliberately not the rendered value: a fold keeps bookkeeping a reader has no
use for (open tool calls keyed by
call_id, the attempt an open turn is on).fold passes its vocabulary to
iter_from, so a required unknown type refusesrather than letting a total the line may have changed look authoritative. The
page passes none, because paging renders history for a person and refusing the
page would hide the history in front of the one unfamiliar line. That is the
posture
crew-log-core.mdsection 6 already states forpageandresolve,applied to a range read.
What is built.
src/kiro_crew/crew_log/projection.py:status,usage,timeline,tools,approvals, each asfold_<name>(entries) -> dictplus the incrementaladvance(checkpoint, entries);fold_sessionfolds all five from one pass.GET /api/sessions/{id}/crew-log?from=&to=: entries in a seq range, oldestfirst, every
refon the page resolved to{status, entries, first_seq, last_seq}. The verdict and span, never the cited bytes -- those are a page oftheir own unit, which this route already serves. Identical refs resolve once,
and a page resolves at most 25 distinct refs and reports what it left.
GET /api/sessions/{id}/crew-log/projection/{name}: the fold's value and theseqit folded through (FR-5).session_projectionframe ({session_id, name, seq, value}) pushed when alog grows.
crew_log.emit.add_growth_listenerreports a drained BATCH,so a consumer is woken once per turn's burst rather than once per entry; the
listener is registered, not imported, because the emitter is imported by the
dashboard and calling back into it would close a cycle. The publisher hands the
id to the loop from the writer thread, coalesces, then folds all five from one
incremental read and sends a frame only for a projection whose
seqmoved.Four rules the folds hold, each stated in the spec and pinned by a test:
turn/completedomitscredits/tokenson asynthesized close, so every total rides beside the count of turns that reported
one (
turns.credits_reported,turns.tokens_reported).open. Closing them is
open(repair=True), which appends real closers underwrite ownership.
call_idandapproval_idmaybe empty; keying a map by an empty id would let one completion close a
different call's frame.
a window that reports what it dropped,
toolsdetails 100 names while keepingtotals exact, open/pending lists are capped with their own omitted counts.
Two things the reviewer should look at directly:
advancerefuses an entry at or below its checkpointrather than skipping it. Skipping is idempotent and therefore tempting, but it
is wrong for the case that actually happens: a unit removed and recreated
restarts
seq, and a cached checkpoint at 50 would swallow the whole new logsilently. Refusing names the collision, and
fold_sessiondiscards a bundlewhose seq is ahead of the file so the recreated-unit case rebuilds.
handlers/crew_log.pyimports the ledger packageonly inside the calls that need it. The crew log is optional behind
KIROCREW_CREW_LOGand this module is on the dashboard's boot path;test_a_flag_off_launch_does_not_load_the_storage_subsystemcaught the eagerversion, and a test here pins the same invariant for this module.
Scope, per the RFC's PR 2 split: crew-kind folds are out (the crew kind has no
writer), on-disk checkpoints are out (the state shape is ready for them),
subagent lineage is out, and there is no SPA work -- the frame shape is specified
so the client can follow.
#11185(resolver) and#11193(retention) touch thesame package; the only shared file this edits is
crew_log/emit.py, andthe edit there is one listener registry plus one
try/finallyaround the batchwriter's exits.
Naming: the feature is "crew log" in every identifier, route, docstring and doc
line this adds. The
kiro_crew.crew_logpackage keeps its current names, which aseparate rename sweep owns.
Tests
test/test_crew_log_projection.py(61) andtest/test_crew_log_routes.py(32),93 new tests. What they lock in:
scratch at EVERY split point of a log exercising all five folds; a checkpoint
survives a JSON round trip and keeps folding to the same answer;
advanceleaves its input untouched; a replayed entry is refused.
open; two calls with an empty
call_idare never paired; arefusedstatus andan asserted
is_erroreach count, an absentis_errordoes not; the timelinewindow and the tool-name budget bound the value while totals stay exact.
page and REFUSED (409) by the fold, over the same file.
absent-log shape, ref resolution to
okandgone, dedupe, the ref budget,and that a non-owner caller is refused on both reads.
with no growth; the incremental read starts at the first new seq; no fold at
all when nobody is watching; a bounded session cache; one session's fold
refusal does not stop the others;
notifydoes no work on the writer thread.kiro_crew.crew_logmodule.Mutation-verified: 14 mutations, one per load-bearing behaviour (the replay
refusal, the state copy, the credit-turn count, the empty-id rule, both bounds,
both vocabularies, the bundle guard, the ref dedupe and budget, the unchanged-seq
skip, the owner gate, the watcher check). 14/14 killed. The first pass killed 13:
the bundle-guard test was vacuous -- it rebuilt the stale bundle from the same
session's own state, so reusing it produced the right answer anyway. It now
carries a busier session's state under this session's id, which is the shape a
cache actually holds after a unit is recreated.
Local gates, all green:
black,isort,flake8,mypy --follow-imports=silenton the touched paths,
check_black_formatting,check_brand_name,check_changelog_history,check_comment_history,check_feature_map,check_focus_cue,check_harness_parity,check_memory_store_seam,check_lockdown_before_publish,docs_lint,docs-lint.sh. Existing suitesre-run:
test_crew_log_emit.py,test_crew_log_core.py,test_session_ledger_order.py-- 493 passed with the new files.Manual verification
N/A -- backend only, and every path is covered by unit tests including the two
that need a real subprocess (the boot-path import census) and a real file (the
planted unknown type). There is no UI in this PR to exercise, and the push is
verified through the publisher's own seams rather than a live socket.
Related Issues
No linked issue. Implements the session half of RFC #10090 section 5; follows
#10091 (merged as
69aeb2803).Checklist
Other suggestions on the work
Two observations from implementing the spec, neither fixed here:
turn/completedcarries noattempt.crew-log-core.mdsection 5 says(turn, attempt)is the identity a fold groups on, andattemptis declaredon
turn/startedonly. A fold therefore cannot pair a completion with itsstart by field; the pairing has to be positional (a start opens the current
attempt at that ordinal, the next completion for it closes whatever is open).
That is what the file supports, and it is what this fold does, but the spec
sentence promises something the type table does not provide. Adding
attemptto
turn/completedis additive.approval/*usesapproval_id, the spec table saysid. The declarationin
entry_types.pyis the one this folds against. Worth aligning the section 5table with it so the next reader does not fold the wrong key.