Skip to content

feat(crew-log): serve the Context panel from the usage fold - #15367

Merged
chenmingwei23 merged 2 commits into
mainfrom
feat/usage-fold-context-turns
Oct 2, 2026
Merged

chenmingwei23 merged 2 commits into
mainfrom
feat/usage-fold-context-turns

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Open the Context tab and get the same answer without reading two weeks of every session's turn records.

no linked issue: this came from a work item (CREW-18723), not a filed bug, and nothing
open covers it -- the nearest, #13232 and #4749, are about the SIZE of the context this
panel measures, which this PR does not change. The three numbers cited below (#14975,
#15078, #15183) are neighbouring PRs named for merge-order reasons, so none of them
should close when this merges.

To draw one session's context chart, the dashboard opened every token-usage
shard file in a 14-day window, parsed every line in each, and threw away all
but the lines belonging to that one session. The work scales with how busy the
whole installation has been, not with the session being looked at. On a machine
that runs many sessions, most of what it reads is other sessions' turns.

The same numbers were already being recorded a second time. Every turn writes a
context/composed entry to the crew log carrying the identical block sizes, and
the usage fold already folds it -- but only into a running per-source total. It
kept no per-turn rows, so the panel could not be answered from it.

Why it matters

Every open of the Context tab pays for the whole installation's turn volume. It
gets slower as the machine is used more, and it is slowest exactly when someone
is debugging a busy session.

It also stored the injection breakdown twice, and only one copy was ever read: the
token row's ctx_blocks and phase existed for this one reader and nothing else.

Not a goal

  • Scope of the panel change (amended, owner-role, 2026-09-30 -- see the amendment
    comment on this PR).
    The earlier line "No change to what the panel shows or how it
    looks. No frontend file is touched." is WITHDRAWN. The panel keeps its layout and its
    set of sections. Two visible things change on purpose, both consequences of the fold
    being the source: (1) each turn row is labelled with its true ordinal from the log
    rather than a window-local index, so a session's "Turn 3" may read "Turn 43" after
    upgrade; (2) the "earlier turns not shown" line derives from those ordinals and
    therefore covers turns the fold's newest-200 window dropped as well as turns outside
    the day filter. ContextBreakdownPanel.tsx is in scope for exactly those two changes
    and the screenshot evidence shows them. capture-session-breakdown.mjs was named in
    the amendment as in scope too; in the end it needed no change and is not in this diff.
  • No new block labels. Which spans of a prompt get measured is unchanged.
  • No new provider reading. Nothing here starts asking a model how full its window is.
  • The token row keeps every billing field. Only the two fields nothing read are removed.

What changed (motivation → approach → change)

The reader was scanning for a fact the crew log already had. The usage fold in
src/kiro_crew/crew_log/projection.py now keeps the per-turn rows, context_trace in
src/kiro_crew/dashboard/handlers/usage.py is one fold read, and
src/kiro_crew/crew_log/emit.py with src/kiro_crew/crew_log/entry_types.py record the
two facts the panel needs and the writer already had.

Part Before After
Reading one session's trace open every shard in 14 days, parse every line one memoised fold read
Per-turn rows not kept by the fold context.turns, newest 200, oldest dropped first
How full the window got read off each token row turn/completed carries the reading and its window as one pair
Which population a turn is on the token row only recorded on context/composed
ctx_blocks / phase on the token row written every turn gone; nothing read them

A row stores label -> chars, not the entry's own {kind, chars, tokens} list.
Per-source tokens are the writer's own split of chars and context.by_source already
sums them. The fold is read per session key, so its state lands in the slot-fold cache,
ceiling 995,342 bytes. At every limit's maximum the shipped shape is 808,912 and the list
shape 3,319,357: it does not merely cost more, it does not fit.

context/composed records session_start or per_turn. The chart pulls the
session-start injection out before scaling the bars: it is many times the size of every
other composition and would flatten them all. Only the composer knows which it built, so
it is recorded, not guessed -- the available guess, a session's first composition, is
wrong for the rebuild a mid-session replay triggers.

turn/completed carries the provider's occupancy reading with the window it was taken
against, and the fold stamps both onto that turn's rows.
The Session Breakdown tree
divides one by the other, so both halves are load-bearing: token counts cannot be the
numerator (billing, summed over every model call, so a tool-using turn exceeds the window
it would divide by) and the denominator must come from the same turn, because a model
switch moves the window. It sits on the ROW because the reader is bounded to days and a
session-wide maximum cannot be narrowed afterwards. Rows are REPLACED, not edited: the
fold shares row dicts with snapshots already handed to readers.

Each row carries its own ordinal, assigned before truncation, so a reader shows the
turn's true number and needs no dropped-turn count on the wire. A turn's ordinal is keyed
by its crew-log unit and turn number, and the unit moves only on the session/opened
that starts a unit (resumed false). A retry, a rewind, a regenerate and a re-attachment
after a gateway restart all stay inside one unit, so each reads back the turn's ordinal;
only a new unit (a new session, or a compaction) starts a new key space.

History, and the crew-log switch. A session predating this fold reads with an
unstated phase and no occupancy until its next turn closes; that heals. One recorded
with the crew log OFF reads empty and stays empty while it is off -- this panel now
depends on that switch, which api_context_trace states. No shard fallback: this release
stops writing ctx_blocks and the scan was bounded to days, so a fallback would serve
at most that many days and nothing after.

The occupancy pair sits in both stores, unlike ctx_blocks: it has four live readers
(context_occupancy, slot_turn_usage, cost_breakdown, the Telemetry drilldown).

Only the usage fold's state_version moves (per-fold versions landed in #14975), so
this retires that fold's savepoints and leaves the other five standing. #15078 adds a
different fold and edits the same _FOLD_STATE_PINS block, so whichever merges second
takes a trivial rebase there; the folds do not overlap. #15183 edits
ContextBreakdownPanel.tsx but not the ContextTrace interface, so the contract test
below holds in either merge order.

test/test_usage.py leaves .github/black-baseline.txt: formatting made it
black-clean, and the ratchet requires a graduated entry be pruned. 926 remain listed.

Backwards compatibility

Compatible: the payload gains a per-row ordinal and keeps every field the panel
declares. ContextBreakdownPanel.tsx reads that ordinal; its tests and
SessionBreakdownTree.test.tsx move with it.

turn/completed gains context as an OPTIONAL object, written only when the provider
reported occupancy. The two synthesized closers (the in-process failed one and
crash-repair) cannot know it and continue to omit it, which is why it is optional
rather than required; a turn with no reading folds as unmeasured.

context/composed gains phase as an OPTIONAL field, and the writer omits the key
entirely when it has no phase to state -- which is the shape every entry already on
disk has. test_a_composition_written_without_a_phase_still_folds pins that: it
asserts the written entry carries no phase key, then that the entry folds, the turn
reads as an unstated phase, and every other field is unaffected. Declaring the field
required or making the writer always stamp it both fail that test. Without it, one
upgrade would empty the panel for every session recorded before the field existed.

Breaking for one internal caller: _build_token_record and persist_token_record
no longer accept ctx_blocks or phase, and the row no longer carries them.
Writer sweep on origin/main @ ee817d5e6685f895933f7d366145bd0bca4f7c57: one
caller passed them (chat_runner.py, updated here); a repo-wide grep finds no
reader of either stored field outside the tests that pinned the write. Rows
already on disk keep both fields and stay valid JSON -- no reader looks at them.

Tests

test/metrics/test_context_trace.py is rewritten to write a real crew log, so
writer, fold and reader are exercised together instead of three fixtures agreeing
with each other.

  • Parity: the whole payload against the shape the scan produced, written out
    as a literal. The old code path is not kept alive to compare against -- two
    implementations agreeing says nothing about either being right.
  • The ordinal key: open, turn 1, a re-attach opener after the process died, then a
    regenerate of turn 1 -- the regenerate reads ordinal 1 and the next new turn is 2.
    Keying by the per-attachment counter instead gives 1, 2, 3.
  • The occupancy pair: the peak is the provider's reading and not the billed input
    (the fixtures bill far more than they occupy, so a peak taken from billing shows);
    the window comes from the turn that produced the peak, proved with a session whose
    fullest turn ran on a small window and whose later, emptier turn moved to a large
    one; a reading whose window the provider did not state reports no window rather
    than borrowing another turn's.
  • The runner wiring: the turn closer passes the names read_context_tokens was
    unpacked into, read from the source. Nothing else here reaches that dict literal, so
    a hardcoded 0 would otherwise leave every test green and the panel empty.
  • The contract the frontend declares: the expected field set is extracted from
    ContextBreakdownPanel.tsx's own interface text, so a field the panel declares
    and the reader stops sending fails here. Each assertion carries a control proving
    the extraction found a real interface.
  • Both bounds: the day window still excludes an older turn; the fold drops the
    oldest row first and reports how many.
  • The memory budget, at the cap: a full window with every limit at its maximum
    measures under the slot-fold cache-member ceiling, and the rejected row shape
    measures over it. The first test also compares its own window against one built
    with a single shared value, because sharing understates the measurement downward
    -- a ceiling check alone would still pass and the guard would go quiet.
  • phase is additive: a composition written without the key still folds and reads
    as unstated, which is what keeps every crew log already on disk readable.
  • Rows the writer would never produce: an undated row, a non-positive block, a
    later zero window, a fold value that is not a context view. Each is a guard that
    answers a damaged log, reached by planting the folded value.

Mutation passes drove the test set rather than the reverse. Survivors that became
tests: a later zero window taken as current, a row's recorded total replaced by the sum
of its blocks, a kept non-positive block, a kept undated row, and the runner passing a
hardcoded 0 for the occupancy reading. One survivor became a code change instead --
a first-seen branch whose window assignment a later peak almost always overwrote, so
the pair is now set in exactly one place and the untestable branch is gone. The budget
test likewise compares its window against a shared-value build, because sharing
understates the measurement downward and a ceiling check alone stayed green.

Manual verification

The fold and the reader were driven end to end over a real crew log outside
pytest: two turns composed with both phases, the payload read back, and every
field checked against what the writer recorded -- the same path the parity test
now pins.

Screenshots / video

The Context panel now reads its per-turn window from the usage fold, and review
surfaced two turn-history bugs the panel had to consume: the backend window drops
its oldest per-turn rows once a session passes 200 turns (session-start rows
are now preserved as the chart's anchor), and the "earlier turns not shown" count
has to be true for turns dropped by the fold as well as those the chart clips from
its own front. Each row now carries the ordinal it was assigned before any trim,
so the count comes off the first shown row's own number rather than a summed
whole-session total, which is what made the earlier arithmetic wrong on any window
narrower than the fold's. Below, the panel is driven with a session-start row plus
34 per-turn rows whose ordinals begin at 41: the chart shows the newest 30, keeps
the session-start injection listed above it, and the chip reads 44 earlier turns
not shown
.

Context panel: session-start row preserved above the chart, "44 earlier turns not shown" reflecting 40 backend-dropped + 4 chart-clipped turns

Committed under temp-screenshots/ rather than attached because the available
gh (2.62) predates --attach (2.99); the same-repo UX lane reads committed
media under that path the same way it reads a description attachment.

Related Issues

N/A -- no tracked issue; this PR carries the context.

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

@chenmingwei23
chenmingwei23 requested a review from a team as a code owner September 30, 2026 08:48
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Intent: Make one session's Context panel answerable from a projection the crew log already feeds, so opening it costs one memoised fold read instead of parsing 14 days of every session's turn records.
Not a goal: Changing what the panel shows or how it looks (no frontend file changes); adding block labels or changing which spans of a prompt get measured; making anything new ask a provider how full its window is.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 30, 2026
@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

Verify the one-time cold refold every slot's usage fold takes after upgrade (state_version +9 retires all savepoints) stays acceptable on long-lived, many-unit installations.

Suggestions

  • The refused-turn change moves context/composed past the gates instead of letting the fold mark refused turns' rows (turn/refused is now folded anyway); if refusal forensics ever need the would-be composition back, that fold-side flag is the shape to reach for, not re-ordering the writes again.

[DESIGN-REVIEWED] 96edd70

Description read

[DESCRIPTION-READ] d01f03647d39c6c33a42c627d3ad68a7857b0d766dc779da4b6180990b25e471

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 Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — 🟡 CONCERNS

Premise-level review of 96edd70bedc61da957d53e9831e67641491dbe63 — 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: CONCERNS

The backward-clock unit-ordering fix covers only the usage fold; the timeline fold's identical front-trimmed window still rides the header clock.

Not justified as shipped

  • Item 9 — symptom-level: _usage_units_in_succession names the root cause itself — "a clock that steps backward between two units of one slot … sorts the genuinely-newer unit BEFORE its predecessor" and the front-trim "evicts the newest unit's rows" — then patches it for usage alone. Grepping _slot_units_for_fold's fallthrough against folds that front-trim a window counts 1 unfixed sibling: timeline (TIMELINE_LIMIT trim, projection.py:2084-2088, plus its dropped counter) folds per slot through the header-clock order the panel fold's own comment already calls unsafe. The general fix is larger (timeline's savepoints would need retiring), so deferral is acceptable — but the change nowhere says the sibling is left.
    Clears when: the succession order covers the timeline fold's window, or a linked issue records timeline's exposure as deferred.

What this change ships

Inventory (10 items) — 9 justified

Intent: make the Context tab answer from the crew log's usage fold instead of re-scanning every installation shard — a FIX (performance defect, cause-level: the duplicate ctx_blocks write is deleted with it).

  1. Context tab served by one memoised fold read instead of a 14-day all-shard scan — justified
  2. Turn rows labelled with their true session ordinal ("Turn 3" may read "Turn 43") — justified
  3. "Earlier turns not shown" now counts fold-dropped and day-filtered turns, derived from ordinals — justified
  4. Usage fold keeps newest-200 per-turn rows, session-start rows preserved, occupancy stamped per row — justified
  5. turn/completed optionally records the provider occupancy pair; context/composed optionally records phase — justified
  6. Token row stops carrying ctx_blocks/phase — justified (grepped: zero remaining readers)
  7. A refused dispatch no longer records a composition (request facts emitted past the gates) — justified
  8. Crew-log unclassified remainder keeps its label; only an empty label becomes other — justified (reversed pin ships verifiable evidence: block_unclassified translated in every locale, no block_other key)
  9. Usage fold's units ordered by durable succession chain, not header clock — symptom-level: point patch; 1 counted sibling (timeline) shares the front-trimmed window on the header fallthrough
  10. Sessions recorded with the crew log off read empty; no shard fallback for pre-upgrade rows — justified (declared deliberate deletion; crew log is on by default)

[FIRST-PRINCIPLES-REVIEWED] 96edd70

Description read

[DESCRIPTION-READ] c5f493f5fdb83153528ad2af0e3494cea5f0b14da56e2fb48857c13f6f43fd49

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 Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 96edd70

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

@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 30, 2026
@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

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

Review details

No findings that block the merge.

FINDING — website/src/pages/ContextBreakdownPanel.tsx:615 — starts.map renders one row per COMPOSITION while regular is deduped by displayN (for (const t of all) if (!t.isStart) byTurn.set(t.displayN, t)), so a provider-switch replay turn that failed to land and was regenerated — both attempts compose at PHASE_SESSION_START under the same _crew_log_turn_no, so _count_turn_ordinal hands both rows one ordinal — draws two identical "Turn N · session start" rows, each separately selectable on its differing t.n and each showing a different breakdown for the same turn number → Fix: build starts through the same per-ordinal map (for (const t of all) if (t.isStart) startByTurn.set(t.displayN, t)) and take startsBeforeFirstShown from that map.

FINDING — docs/system-specs/modules/metrics.md:1055 — the spec says the occupancy pair comes from the turn "that reported the largest occupancy" while handlers/usage.py crowns the largest ratio (used * peak_window >= peak_used * row_used_window), so a 150k/1M turn loses to a 120k/200k one and the spec contradicts context_trace's own docstring added in the same commit, on the one field a reader cannot check against the payload → Fix: restate the sentence as the largest used / used_window ratio.

[OPUS-REVIEWED] 96edd70

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

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

@chenmingwei23
chenmingwei23 force-pushed the feat/usage-fold-context-turns branch from 82b2186 to 4c907f1 Compare September 30, 2026 10:30
@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 30, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/usage-fold-context-turns branch from 4c907f1 to c49a032 Compare September 30, 2026 11:31
@chenmingwei23

chenmingwei23 commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor Author
  • fixed span=edc024cbb4a9 F1 shallow copy mutates an earlier projection snapshot

Fixed in c49a0329345f446e9dac15866f9552e015b3dc3d. Confirmed against the module's own
contract. The stamp now REPLACES the element (rows[index] = {**rows[index], ...})
instead of writing into a dict _usage_copy shares with a snapshot already handed to a
reader; that stays O(window) because the list is rebuilt per apply anyway.
The adjudication's second half was the more useful one: the witness was blind because
_turn_items emitted no context block. That builder now carries the provider pair, so
test_a_fold_never_reaches_into_the_state_it_was_handed[usage] fails BY NAME when the
stamp is reverted to an in-place write. Verified by mutation, not by inspection.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

span=e8fb475c29c4 [WATCH] in-place row edit against _usage_copy's shared rows -- fixed in c49a0329345f446e9dac15866f9552e015b3dc3d.

Same root cause as the GPT blocking finding, fixed once. The stamp replaces the
element rather than mutating it, exactly as the Clears-when line specifies, and
_turn_items now emits a context block so the purity test covers the path. That
second half was the load-bearing one: without it the copier's miss produced the right
value while editing a caller's state, and nothing raised.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

span=131784e56e85 [SUGGESTION] "self-heal" overstates the crew-log-off case -- fixed in c49a0329345f446e9dac15866f9552e015b3dc3d.

Correct, and it was my sentence conflating two different cases. The body now separates
them: a session predating the fold heals as turns arrive, while one recorded with the
crew log OFF reads empty and stays empty while it is off. api_context_trace's
docstring carried the opposite promise ("the usage rows this reads are always written")
and now names the switch as the one thing this surface is not independent of.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

span=eb1e4f0bd577 item 3, occupancy pair duplicated across both stores -- rebutted, and the wording that invited it is fixed in c49a0329345f446e9dac15866f9552e015b3dc3d.

The two stores serve two consumer sets, so this is not the duplication the description
argues against. The token row's context_used/context_window have four live readers:
context_occupancy (usage.py:480), TURN_USAGE_FIELDS -> slot_turn_usage
(usage.py:585, the app-facing usage API), cost_breakdown's context bands
(usage.py:1015), and the Telemetry turns drilldown, which renders the ratio
(TelemetryPanel.tsx:842). ctx_blocks/phase had ZERO readers, which is why those
two were deleted and these are not.
The finding is right that my own sentence read as covering both. It said "two copies of
one number" without naming which; it now names ctx_blocks/phase and states
explicitly that the occupancy pair is in both stores and why that differs.

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

Copy link
Copy Markdown
Contributor Author

span=b7ae743a80d8 item 7, fields with no counted consumer -- needs-a-decision. The count is correct; what it implies is the question.

Verified, not disputed. turns_omitted: 0 hits in website/src, and the panel's own
"earlier hidden" count understates the hidden turns by exactly it. Row step,
tokens, tokens_estimated, sources_omitted: none read by context_trace.
The two halves differ, though. turns_omitted on the PAYLOAD I can simply delete --
the ContextTrace interface never declared it, the fold still reports it, and its
tests can read the fold directly. I have not done it in this push because the lanes
were just answered and re-rolling several clean verdicts for a field nobody reads is a
poor trade; it batches with the next round.
The row fields are a different question, and it is architectural rather than a defect:
applied strictly, "a counted consumer or deletion" trims the projection to exactly what
ONE panel reads today, which makes the fold a private backing store for that surface
instead of a projection other readers (crew log panel, MCP tools) can use.
sources_omitted in particular is the honesty counter for the per-row source cap --
without it a capped row silently reports a smaller prompt.
Maintainer ruling requested on the row fields: trim to the current reader, or keep the
projection self-describing and accept fields ahead of their consumers.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • fixed span=edc024cbb4a9 F2 refused turns bypass the former completion guard

Fixed in c49a0329345f446e9dac15866f9552e015b3dc3d. Legitimate, and this repository
already held the answer: on_turn_started is emitted after every dispatch gate on the
stated grounds that it "asserts that the turn RAN". context/composed asserts the same
thing -- what the gateway PUT IN FRONT OF THE MODEL -- so both request facts moved down
beside it, rather than adding a pending buffer to the fold. request/configured stays
immediately ahead of the composition because the fold reads its window to stamp rows.
This also removes a pre-existing inflation of the cumulative context.by_source, which
counted refused compositions before this change made them visible.
A source-ordering test now fails if the composition moves back above any dispatch gate,
using on_turn_started as its control; verified by mutation.

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

Copy link
Copy Markdown
Contributor Author

Branch ownership -- please do not push to feat/usage-fold-context-turns

This PR is being driven by a live babysit loop (worker W-G, conductor session
chat-1875-1790253512) which rebases, squashes and lease-pushes this branch each round.

A second agent pushed e029c7d0994fb941edff231d8e6c1c80f2c18d8d on top of
c49a0329345f446e9dac15866f9552e015b3dc3d at 11:37 UTC. No harm done -- it built on the
existing commit rather than replacing it, and it caught a real bug the first round missed
(turn numbers restart per unit, so the occupancy stamp could reach into a previous unit).
That work is kept, credited, and extended below.

Two things went wrong that ownership would have prevented:

  1. Duplicated effort. Both pushes fix the same two GPT findings by different means. The
    branch briefly carried two remedies for each.
  2. A new defect. Scoping the refusal retraction by turn number alone lets a refusal in a
    later unit delete a completed turn's rows from an earlier one -- a real, already
    stamped reading, with nothing able to recover it. Reproduced, and fixed here.

If you are an automated triage fleet: this PR is not unowned. It is red only while its
round is in flight, and a red review lane on a PR with an active loop is not an
abandoned head. Please check for a live session naming the PR number before writing.

@chenmingwei23
chenmingwei23 force-pushed the feat/usage-fold-context-turns branch 2 times, most recently from adbe1e6 to d5d948f Compare September 30, 2026 12:36
@chenmingwei23
chenmingwei23 requested a review from a team September 30, 2026 12:36
@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — 🟡 CONCERNS

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

UX-Verdict: CONCERNS

Sessions recorded with the crew log off now get a permanently empty panel whose copy — "…recorded for this session yet." — promises data that will never come.

Watch

  • Dead panel with misleading copy for KIROCREW_CREW_LOG=0 installs: the trace moved from always-written token shards to the crew log (api_context_trace: "a session run with KIROCREW_CREW_LOG switched off has nothing for this route to return"), so a feature these users had silently stops, and the UI's only explanation is "No context breakdown recorded for this session yet." — "yet" implies it will arrive, every open, forever. Low frequency (explicit opt-out) × persistent × misleading. Fix: have the payload carry a recording-off flag when emit.enabled() is false and render a distinct empty state naming the switch.
  • Pre-upgrade sessions flatten their chart: old context/composed entries carry no phase, so isStart is false and the session-start injection (≈39,000 chars vs ≈2,700 per turn in the supplied screenshot's own scale) draws in-chart, pinning the y-axis — while start_note still claims "The session-start turn is shown above the chart so later turns stay readable." Transition-window only and acknowledged in the PR text; a human should accept the degraded chart (and the note that misstates it) knowingly.

[UX-REVIEWED] 96edd70

Description read

[DESCRIPTION-READ] e7a1fae3bbd5cc34d620623a74176b5d5a0a1f0a40fef9092f0850a18fe6c83a

That sha256 names everything this verdict read: the PR description, plus the 4 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.

@chenmingwei23
chenmingwei23 force-pushed the feat/usage-fold-context-turns branch from d5d948f to f4bc098 Compare September 30, 2026 13:03
@chenmingwei23
chenmingwei23 force-pushed the feat/usage-fold-context-turns branch from d11fd25 to cd4bc40 Compare October 1, 2026 05:09
@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 Oct 1, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/usage-fold-context-turns branch from cd4bc40 to a5c5bcf Compare October 1, 2026 05:27
@github-actions github-actions Bot removed the readiness: checking Automated validation is still running label Oct 1, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Owned by conductor session chat-1875 (worker W-G3). Head 6d972cf748 = the 07:56Z rebase onto d8fa6a527e plus two additions folded into the top commit (author kept):

  • regenerated the fold catalogue (FOLDS.md / folds.json): now that fix(crew-log): regenerate the fold catalogue for the subagents fold #15744 made main's catalogue current, this branch's usage fold also consumes request/configured, session/opened and turn/refused, so test_fold_catalogue would go red on the 07:56Z head;
  • deleted the orphaned half-sentence at usage.py:797 that the Opus lane flagged.

Tree verified locally: mypy clean (2007 files), flake8/isort clean on touched paths, 1145 scoped tests pass, gateway boot e2e turn passes. Please do not push or rebase this branch while this round runs.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Owned by conductor session chat-1875 (worker W-G3). Head 86cab0196d = 9ff2c27c5f plus the fix for GPT's ordinal-memo finding (projection.py:287), folded into the top commit with its author kept:

  • the (unit, turn) memo is now one append-only string context_turn_keys (a key's position gives its ordinal), bounded at 10,000 keys = the slot's live message cap, the range chat_rewind can reach; usage fold state version +8;
  • new tests: a rewind to turn 10 after 1,000 turns keeps ordinal 10; the bound is pinned to _MAX_SLOT_MESSAGES; the cell-budget test now measures a full window plus a full memo (928,954 < 995,342).

Local gates: mypy clean (2007 files), flake8/isort/black clean, 1017 scoped tests pass, gateway boot e2e turn passes. Please do not push or rebase this branch while this round runs.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Owned by conductor session chat-1875 (worker W-G3). Head e72a1d3f63 = 86cab0196d plus the fix for GPT's delta finding; please do not push while this round runs.

GPT F1 (ContextBreakdownPanel.tsx:565), fixed: previous now comes from the item before the selected turn in the deduplicated sequence (session-start rows plus the kept attempt per turn), so a retried turn is compared with the turn before it, never with its own hidden attempt. Regression: draws a retried turn once, from its newest attempt now asserts +315 vs previous (turn 9 vs turn 8); it fails on the old line.

Opus on 86cab0196d failed closed on the app installation rate limit (no verdict), not a finding.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Rebased onto main 9d98cba. New head: 985ab39 (still 2 commits, authors kept).

One conflict, in test/test_crew_log_checkpoint.py, inside the _FOLD_STATE_PINS table. It hit both commits.

Checks on the rebased tree, all exit 0:

  • mypy (repo venv) on the 6 touched src files: no issues.
  • pytest: test_crew_log_checkpoint, test_crew_log_projection, test_crew_log_emit, test_usage, metrics/test_context_trace: 689 passed.
  • vitest: ContextBreakdownPanel, SessionBreakdownTree: 49 passed.
  • tsc -p tsconfig.app.json, eslint on the panel: clean.
  • scripts/fold_catalogue.py --write: already current; --check: passed.
  • flake8, isort, comment-history gate: clean.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Rebase only onto main 55d6539, to pick up the widthFamilyGc test fix from #16028. No code, title or description change. Locally: widthFamilyGc.test.ts and the two touched frontend test files pass (70 tests), and the six touched backend test files pass (904 tests).

Opening one session's Context panel scanned up to 14 days of every session's
token records to find the rows belonging to that one slot. This serves the same
panel from a projection the crew log already maintains, so the read is one
memoised fold instead of a directory walk whose cost grows with every other
session on the box.

The `usage` fold gains a bounded per-turn window. Each row carries the turn's
composition as `label -> chars`, deliberately not the entry's own
`[{kind, chars, tokens}]` list: measured at the cap (200 rows x 64 sources with
labels at `TEXT_LIMIT`) the list shape is 3,319,357 B against 808,912 B for the
mapping, and the slot-fold cache's per-member ceiling is 995,342 B, so the list
shape does not fit. Per-turn per-source tokens also have no reader and are not an
independent measurement -- the writer derives each one from that source's chars at
a fixed ratio. `CONTEXT_TURNS_LIMIT` is 200, the same posture as `TIMELINE_LIMIT`
and defined beside it.

Occupancy rides on the ROW, as `used` with the `used_window` it was measured
against, rather than as one session-wide pair. The reader is bounded to a day
window and a session-wide maximum cannot be narrowed to it afterwards: on a long
session the fullest turn is usually older than every row in the span. The reading
comes from the provider on `turn/completed` rather than from `tokens.input`,
because billing sums every model call a turn made, so a tool-using turn bills
past the window it would be divided by.

Two guards scope that stamp, and neither covers the other's case. The `_closed`
seal tells two FINISHED runs of one ordinal apart, since each closer marks its own
tail run. A unit counter off `session/opened` tells apart a run that was never
closed at all: a unit cut off mid-turn leaves its rows unsealed, and the next
unit's same-ordinal turn would stamp an unmeasured turn with its own reading.
Removing the seal reddens the two attempt tests; removing the unit term or
freezing the counter reddens the cross-unit test.

Each row also carries its own `ordinal`, assigned before any truncation, so a
reader shows the turn's true number directly. No dropped-turn count rides on the
payload: a whole-session total applied to an array index cannot answer for a
narrower window, because the index counts only the rows still present AND inside
the window. That is what the count got wrong, so the count is gone rather than
rescoped, and the ordinal gap is the record of what was trimmed.

A row carries only what its one reader asks for. `tokens`, `tokens_estimated`,
`sources_omitted` and `step` are not on it: `context_trace` shapes rows to the
`ContextTrace` interface, which declares none of them, and a row's token count is
the writer's own fixed-ratio split of the same `chars` rather than an independent
measurement. The session-wide counts they would have duplicated -- `tokens`,
`estimated_turns`, `by_source` -- are accumulated separately and unaffected.

`context_trace()` now reads `read_slot_projection(slot, "usage")` and shapes to
the existing `ContextTrace` TypeScript interface. A contract test reads
`ContextBreakdownPanel.tsx` so the shape cannot drift from its only consumer. The
old scan is deleted rather than kept alongside for comparison. There is no
read-through fallback to the token shards: this release stops writing
`ctx_blocks`, and the scan was bounded to `days`, so a fallback would serve at
most that many days and then nothing -- a read path with a provable expiry date is
worse than none.

`context/composed` gains an optional `phase`, which the panel reads to split the
one-off session-start injection out before the chart scales. It is stated by the
composer, never derived here: the guess available to a fold, the first row of a
unit, is wrong for the rebuild a mid-session replay triggers. Existing rows
without it still fold, with a test.

`context/composed` and `request/configured` are emitted after every dispatch
gate, beside `on_turn_started`, so a refused turn leaves no phantom row. Only the
`usage` fold's `state_version` moves. #15078 is the trivial-rebase neighbour on
`_FOLD_STATE_PINS`.

One 200-row window with realistic 40-source rows measures 808,912 B at the cap.

Co-authored-by: kirocrew-agent <agent@kirocrew.local>
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Rebase only onto main fa37aa5, to pick up the autonudge F811 lint fix from #16032 (and the widthFamilyGc fix from #16028). No code, title or description change; both commits kept. Locally: flake8 on autonudge.py is clean and widthFamilyGc.test.ts passes (21 tests).

…, and count composition-less turns

Reads the ``ordinal`` the fold assigns onto each context row so the Context
panel shows a turn's true number and an exact "earlier turns not shown" count,
independent of how many rows the window dropped or the day view excluded.

Ranks the occupancy peak by the highest ``used / used_window`` ratio (the
fullest turn) rather than the largest absolute ``used``, so a model switch that
moves the window no longer crowns a proportionally-emptier turn; a reading with
no stated window is not a valid peak candidate.

Derives the ordinal from the durable turn history rather than a
composition-only counter: a turn that ran but composed nothing (a refusal, or a
turn reusing the prompt already in context) still consumes an ordinal, so the
number a later row carries reflects every turn before it. The turn-composed
signal is keyed on the closing turn's (unit, turn) identity, held as a
JSON-native list so it survives a checkpoint round-trip. Bumps the usage fold
state_version and re-records its savepoint pin.
@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • fixed span=edc024cbb4a9

Real and fixed as one invariant: a turn's ordinal key is stable across retry, rewind,
regenerate and re-attach within one crew-log unit, and only a real new unit (a new
session or a compaction, each its own crew log) starts a new key space.
The key's unit is now context_key_unit, which moves only on the session/opened
that starts a unit (resumed not true). context_unit still moves on every opener
and keeps its one other job, scoping occupancy stamps and the row unit field, where
splitting at a re-attachment is the safe direction.
Every place that writes or reads the ordinal key, one pass:

  • writes: _count_turn_ordinal appends (unit, turn) to context_turn_keys and
    advances context_turns_seq (the only writer of both);
  • callers, all now passing context_key_unit: the turn/completed closer, the
    turn/refused branch, and the context/composed row's ordinal;
  • reads: _count_turn_ordinal alone reads context_turn_keys; _usage_copy shares
    the string unchanged; the rendered row ordinal is read by the usage handler and
    ContextBreakdownPanel.tsx, which never see the key.
    The usage fold's state_version moved and its _FOLD_STATE_PINS entry was
    re-recorded, so savepoints keyed by the old counter refold cold.
    Test: open, turn 1, a re-attach opener after the process died, a regenerate of turn 1,
    then turn 2 -> ordinals 1, 1, 2 and two turns counted. Keyed by the per-attachment
    counter it gives 1, 2, 3. The retry, rewind and memo-bound tests still pass.
    Fixed in 96edd70, on main fa37aa5.

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

LGTM. I checked this at head 96edd70.

context_trace now does one memoised read of the slot's usage projection (dashboard/handlers/usage.py:777) instead of scanning every token shard for ctx_blocks. context_trace was the only reader of ctx_blocks on main, so nothing is dropped without a replacement. The peak is ranked by ratio (usage.py:883, used * peak_window >= peak_used * row_used_window). Composition-less and refused turns each take one ordinal through _count_turn_ordinal (crew_log/projection.py:1780, :1789), and the occupancy reach-back stops at the unit boundary and the seal. The composition is emitted only after every dispatch-gate refusal returns, so a refused turn writes nothing. Retained fields are bounded (200 rows, 64 sources per row, keyed labels, 10,000-key memo), and state_version is bumped so old savepoints refold cold. App callers still get the SEL-audited 404.

Mutations, each restored from a backup:

  • comparing the peak on absolute used reddens test_peak_is_the_fullest_ratio_not_the_largest_used_across_a_switch
  • dropping the composition-less ordinal advance reddens 3 tests, including test_a_retried_composition_less_turn_takes_ONE_ordinal
  • dropping the unit check on the reach-back reddens test_usage_an_interrupted_units_open_row_is_not_stamped_by_the_next_unit

Crew-log, context-trace and usage suites: 905 passed, 0 failed. Frontend vitest was not run here; I read the TSX.

The first-principles and UX CONCERNS are advisory. The timeline clock-ordering fix is a sibling fold outside this diff, and the empty-panel copy for installs with the crew log disabled, plus flatter charts for pre-upgrade sessions, are low-frequency UX follow-ups.

Merge order with #15781 (non-blocking, but whichever lands second must handle it): the two conflict in crew_log/projection.py, and the interaction is semantic as well as textual. #15781 charges slot-fold cache cells per row via _SLOT_FOLD_ROW_BYTES, and a fold missing from that table is charged one 64 KiB row. Here usage becomes a slot-read fold holding up to ~800 KB, and its size justification cites the radar ceiling #15781 removes. The rebase should give usage a count_rows and a measured row cost, keep this PR's state_version bump, and keep the usage branch in _slot_units_for_fold, which #15781's version does not have.

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