Skip to content

feat(crew-log): session tree folded from every session log, nested on the System page - #11929

Merged
iamwhatever merged 1 commit into
mainfrom
feat/session-tree-projection
Sep 20, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
feat/session-tree-projection

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Sep 19, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

A session opened by another session through session_create writes who opened it into its own crew log (#11472). Nothing reads that record. The System page's Sessions tab lists every live session as a flat row, so a conductor and the worker it opened look like strangers. Only subagent tasks nest today.

Why it matters

A person reading the Sessions tab wants "what runs under this session" in one glance. Without the edge, one crew's memory, credits and turns are scattered over unrelated rows. The parent field #11472 ships also has no consumer; this is the reader #11484 promised.

What changed (motivation → approach → change)

A created session now sits under its creator in the Sessions tab, to any depth. A created session whose creator is not running stays a top-level row and says who opened it in visible text.

Piece What it does
crew_log/tree.py One pure fold over the first entry of every session log: slot -> creator slot, plus a cycle mark. An orphan stays a root with its citation; a cycle member nests nowhere. Any entry carrying a parent wins; one without never retracts it; the oldest log's word stands. Depth is not carried: the table walks the parent chain itself.
Scanner + cache Reads one bounded head (header + first entry) per log, cached per unit by segment path, inode and the append-only size floor (a file shorter than when it was read is a different file, whatever a recycled inode says); a live session's appends cost no re-read. A first entry caught mid-append (unterminated, unparseable) is not cached and is read again next scan; a terminated unparseable one is damage, cached once. A read that fails outright (OSError after the stat) is no verdict on the bytes: read_head raises it and the scan caches nothing for that unit, so the next scan reads it again or finds it gone. A scan admits at most TREE_UNIT_CAP (4096) units, and the cap cuts every loop, not only what is retained: the live sessions' logs are probed first (the sampler names them by ACP session id; store.unit_dir_for, one stat each, through islice(preferred, cap) so absent ids cost no more than the cap in probes), then store.unit_dirs fills the rest of the cap from the directory's own order, skipping what is already admitted, and stops one candidate past the cap. Nothing past the cap is walked, read, cached or counted; that something lies past it is SessionTree.over_cap, a fact rather than a count. Every retained string is bounded at admission (MAX_ACP_SESSION_ID_LEN, MAX_SHORT_STRING), an oversize or forged head is refused whole, and the refusal is cached. Since the live logs go first, what goes unread is closed sessions' logs, which no row on screen nests on.
/api/sessions/memory (session_memory.py) Each session row carries parent: {slot, key}: the cited creator slot, and the creator's live row key or null when it is not running. The join tries the row key, its bare slot key and the channel-bound alias spend_slot_by_session supplies, so a Slack- or cron-bound creator is found under its linked_session_key row. totals.lineage_over_cap says whether the store held more session logs than the scan admits, beside totals.lineage_cap, on every payload. The sampler hands the tree the live rows' ACP session ids, which runtime_pids in session_allocation.py now carries as sid (bounded where it is retained by MAX_ACP_SESSION_ID_LEN: an oversize or empty id is None, never truncated), so every row on screen has its log read. Typed in website/src/api/client.ts.
Sessions table sessionRows.ts buildTree nests a created session under parent.key the way it nests a task, and a task under whichever session spawned it (walking the parent chain itself, so the wire carries no depth), and marks the row it placed (nested), so the table never reads placement off the row tree, where under Group by a top-level row's parent is a synthetic group row. SessionsTab.tsx scales the indent with depth and draws one guide line per ancestor level under that ancestor's expander (sorting orders each parent's children by the sorted column, so a shallow row can sit below a deeper one; the lines say what a row hangs from), labels an expander that hides sessions as such, marks task rows with a muted "task" before the name (indent alone no longer says the kind once sessions nest too), counts the rows a folded session hides beside its name, unit and memory included ("964.3MB in 4 hidden rows": sessions and tasks, where the footer's "nested" counts sessions only, and their memory summed, since the parent's own figure otherwise reads as the family's total), shows "Created by {creator} (not running, so shown top-level)" as visible text on a created row that could not be nested (under every grouping), on a second full-width line under the name that wraps rather than truncates, since a citation with its tail cut off names nobody, the parenthetical stating the consequence, not only the state; reconciles the footer's "Sessions" count with the rows on screen once any session nests ("5 (3 top-level, 2 nested)", the nested count in the value itself so "Task sessions" beside it is not read as the other half of the sum), and shows a footer stat "Stored session logs 4,096+" while lineage_over_cap is true, as an ordinary stat rather than in the warn colour (it changes nothing on the page), labelled by what it counts on disk since the strip already carries three other "session" counts, with a hint that names the cap it explains ("more than 4,096 exist", interpolated from lineage_cap) and leads with what it means (old session logs are piling up), says every session stays listed and names the one row it can cost (a session restarted since it was opened may show as top-level: its parent lives only in its older, closed log), gives the command that lets old logs expire, prefixed with where it is typed ("in a terminal run: kirocrew config set session.archive_retention_days 30"), and says what it removes (closed sessions' logs and old saved transcripts under Archive older than the days set) and keeps (running sessions, anything newer); the Storage sweep is not named, since it moves transcripts and replay logs to the Trash and never a crew log. The Memory column's "?" says each row is its own runtime's memory, a parent's figure does not include the rows nested under it, and a group's header row under Group by is the one row that totals; the Sessions footer hint says outright that the N task sessions are a separate count, not part of this one, and that a task row is a session run as a task. Footer hints open above the strip, clear of the value they explain. The frames below come from website/scripts/capture-session-tree.mjs, one more of the repository's capture-*.mjs harnesses (built SPA over the stubbed API).

Why a fold across logs and not one more per-log projection: the edge lives on the child, because the child knows its creator at its first turn and the creator never learns the child's id, so no single log holds the tree. dsh does the same with a parentSession header field on the child and a read-side flattenLineage. The five projections still read only their own log (FR-4); the tree is a different reader and the spec says so.

Why the tree reads parent.slot and not parent.sid: a slot outlives its ACP session, and the live row a child nests under is the slot's. The sid stays in the log as an audit citation for a reader of the logs themselves; the wire does not carry it.

Why a cap that says "over" and not a count: a store past the cap is a store retention is not cleaning, and the page is where someone looks when sessions are the question, so the fact is on every payload and on the page; but counting what lies past the cap would mean walking the whole population on every poll, which is the cost the cap exists to refuse, so the scan stops one candidate past it and the page says "4,096+". Why the live logs go first: the rows on screen are what the tree is folded for, so past the cap it is closed sessions' logs that go unread, not a live row's (while the live rows themselves fit in the cap; the preferred set is bounded too), and no row needs to say its creator is unknown (the per-row flag an earlier revision carried is gone).

Why visible text and not a tooltip: a keyboard or touch reader never sees a native title, and on the top-level row of a creator that is gone that text is the only place the citation can be read. A nested row needs none: its place is the citation.

The scan runs on the executor, only when KIROCREW_CREW_LOG is on (a flag-off launch never imports the storage package); at the cap on a local disk, a cold scan of 4,096 units took 376 ms and a warm one 90-120 ms, against a 5 s poll. docs/system-specs/modules/crew-log-projection.md gains section 6, crew-log-core.md points at the reader, the docs/feature-map system row names the Sessions plane, its files, handler and endpoint. .github/black-baseline.txt drops session_memory.py, test/test_session_memory.py and test/test_session_more_coverage.py, now black-clean. Eleven new strings (created_by, hidden_rows with its plural forms, registered in pluralKeys.json, hidden_rows_memory, task_marker, expand_sessions, collapse_sessions, footer_lineage_over_cap and its hint, memory_hint, footer_sessions_nested and its hint) in every website/src/i18n/locales catalog, the product name through {{productName}}; the /api/sessions/memory row list in learn-cron-dashboard.md names parent, totals.lineage_over_cap and totals.lineage_cap.

Backwards compatibility

Compatible: one new nullable field per session row, one new boolean and one new integer in totals, and a sid on runtime_pids rows (bounded at retention by MAX_ACP_SESSION_ID_LEN, None when oversize or absent), all on existing payloads. No entry type, header or route changes shape. With the crew log off every row reads parent: null, lineage_over_cap is false, and the table is what it was.

Tests

  • test/test_crew_log_tree.py (36): fold rules (orphan and self-cite to root, a cycle marked; the parent chain along a chain; any-with-parent and no retraction across a restart; oldest log wins; input order does not matter); scanner (an unchanged log costs no read, a replaced inode is re-read, a shorter file under the same name and inode is re-read, a torn first entry is not cached and is read once it lands, a read that fails is not cached and the next scan reads the log, a removed unit leaves the cache, a directory carrying another unit's id is refused and the refusal is cached, a damaged first entry is refused once, a retention-truncated log yields the slot with no parent, a header-only log is read again once its entry lands, a retained string past its bound refuses the whole record while an oversize parent.sid changes nothing because it is not read); the cap (units past it are neither read nor cached and the overflow is reported as a fact; a unit that falls past the cap is evicted so the cache never exceeds it; live units named by the caller are admitted first so past the cap only closed logs go unread, and the preferred set is itself bounded by the cap; the invariant measured: ten times the cap in absent ids costs exactly the cap in probes, a store three times the cap is examined for cap + 1 candidates, the cache never exceeds the cap); the store helpers (read_head raises on a file it cannot open; unit_dir_for answers for a directory, not for an absent one or a linked entry; unit_dirs stops one candidate past its limit, neither lists nor counts an excluded name, and at a zero limit still says whether anything exists); parent_payload never nests a cycle or a row under itself.
  • test/test_session_memory.py (+6): a child row names its live creator; a channel-bound creator is found through its slot alias; an absent creator leaves key: null; a store past the cap sets totals.lineage_over_cap beside lineage_cap while both live rows still fold (the closed session's log is what goes unread); no crew-log root gives null everywhere; flag off builds no scanner and reports false with cap 0.
  • test/test_session_more_coverage.py (+1): a runtime_pids row carries the backend session id only within MAX_ACP_SESSION_ID_LEN; an oversize, empty or absent one is None.
  • website/src/test/sessionRows.test.ts (+7): nesting under a creator, tasks under the nested child, arbitrary depth, an orphan stays top-level with its citation, an unknown key is ignored, cycle members become roots while a hanger-on keeps its edge, a plain session has parent: null; the placed row carries nested: true, its creator and a root do not.
  • website/src/test/SessionsTab.test.tsx (+9): the orphan row shows "Created by {slot} (not running, so shown top-level)" as text and no name cell carries a "Created by" title; the orphan keeps that text under Group by, where its parent row is a group row; a nested row does not repeat its creator; a session nobody created says nothing; a folded session says "M MB in N hidden rows" beside its name as visible text; a row carries one guide line per ancestor level and a top-level row none; the session-logs stat appears only while lineage_over_cap is true, reads "4,096+", is not warn-coloured, and carries its hint; the Memory header's hint says a parent's figure does not include its nested rows; the Sessions value says how many are top-level only once one nests, with its hint.

Manual verification

Real path on this host: session_create from one session opened lineage-probe; its log's session/opened carries parent {slot: chat-1531-1789617025, sid: 7eefead2-...}, and the sid's own log header says slot: chat-1531-1789617025. The frames below are the built SPA over the shared stub (website/scripts/capture-session-tree.mjs), payload shaped as the fold produces it: a conductor, the worker it opened, that worker's own worker and task, a created session whose conductor is gone, a Slack session; a third frame per theme feeds a payload whose store is past the scan's cap, since the footer stat is hidden otherwise, and a fourth opens that stat's hint. The pod could not boot on this host (its kiro-cli child fails on systemd-run), so the frames are from the harness, not a pod.

Screenshots / video

Sessions tab, dark: conductor > worker > worker > task nested one indent step per level, task rows carrying a muted TASK marker before their name, with one guide line per ancestor level under that ancestor's expander; the orphaned worker is top-level and says Created by its creator slot (not running, so shown top-level) on its own full-width line; the Memory header carries a hint that a parent's figure does not include its nested rows; footer reads Sessions 5 (3 top-level, 2 nested) with its hint
Sessions tab, dark: the same tree under Group by Channel: a dashboard group holding the conductor with its nested workers and task, and the orphaned worker with its Created by citation; a slack group holding the Slack session; nesting and the citation survive a grouping, whose group row is a top-level row's parent in the row tree

Sessions tab, dark: the conductor folded via its Collapse sessions expander; "964.3MB in 4 hidden rows" beside its name says what is folded (two workers, two tasks) and what they hold, the orphan and Slack rows stay

Sessions tab, dark: a payload whose store holds more session logs than the scan admits; every row still folds, and the footer shows Stored session logs 4,096+ as an ordinary stat with a hint beside it

Sessions tab, dark: the stored-session-logs hint open above the footer strip, naming the 4,096+ it explains: more than 4,096 exist, every session stays listed, a session restarted since it was opened may show as top-level, the kirocrew config set command with where to type it, and what it removes (closed sessions' logs and old saved transcripts under Archive older than the days set) and keeps (running sessions, anything newer)
Sessions tab, dark: the Memory column header's hint open: each row shows its own runtime's memory, a session's figure does not include the rows nested under it, and under Group by a group's header row totals its members
Sessions tab, dark: the Sessions footer stat's hint open beside 5 (3 top-level, 2 nested): the 2 task sessions are a separate count, not part of this one; a nested session sits under the session that opened it; a task row is a session run as a task

Light theme

Sessions tab, light: the same expanded tree with its guide lines
Sessions tab, light: the same tree under Group by Channel

Sessions tab, light: the same folded conductor with its hidden-row count

Sessions tab, light: the same over-cap payload

Sessions tab, light: the same hint open above the strip
Sessions tab, light: the same Memory header hint open
Sessions tab, light: the same Sessions footer hint open

Related Issues

Two issues opened from earlier review rounds of this PR are fixed here: the admission order past the cap (live sessions' logs are read first) and the per-poll walk of the whole store (the listing stops one candidate past the cap).

Closes #11484
Closes #11937
Closes #11956

Follow-up to #11472.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|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 review from a team and pepmach September 19, 2026 01:39
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 19, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Intent: Give the parent {slot, sid?} that #11472 writes on a created session's session/opened its reader: fold every session log's first entry into one slot-keyed session tree, carry the creator on each /api/sessions/memory row, and nest a created session under its running creator in the System page Sessions table the way a task nests today. Resolves #11484.
Not a goal: subagent (spawn_run) lineage, fork lineage, a crew-log viewer page to link the citation to, on-disk checkpoints for the tree, or any change to what the emitter writes.

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

github-actions Bot commented Sep 19, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

Verify the spend_slot_by_session alias join against a real Slack/cron-bound creator — manual verification ran on the stub harness, not a live pod.

[DESIGN-REVIEWED] aa60e5a

@github-actions

github-actions Bot commented Sep 19, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — 🟡 CONCERNS

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

UX-Verdict: CONCERNS

The new Sessions footer hint fails its one job: after reading it, the blind reader still could not say which rows count toward which number.

Watch

  • footer_sessions_nested_hint ("A task row is a session run as a task… a separate count") confused the reader it exists for: "the wording still confuses me (a task 'is a session' but is counted separately)" and, in the could-not-tell list, "After reading the help bubbles I still couldn't confidently say which rows count toward which number." Anyone with nested sessions sees this footer on every visit, so the confusion is persistent though not task-blocking. Smallest fix: anchor the hint to what's visible — e.g. "Counts the session rows above (nested ones included). Rows marked TASK are counted separately, under 'Task sessions'."

Suggestions

  • footer_sessions_nested_hint: drop "A task row is a session run as a task" — defining a task as a session while excluding it from the session count is the exact sentence that broke comprehension; name the visible TASK marker instead.

[UX-REVIEWED] aa60e5a

@github-actions

github-actions Bot commented Sep 19, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

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

Verify the measured scan cost (376 ms cold / 90–120 ms warm at 4,096 units) — it is the number that licenses folding every crew log on each 5-second poll.

What this change ships

Inventory (10 items) — 9 justified

Intent: show which session opened which by nesting created sessions under their creators on the Sessions tab — the reader for the parent field #11472 shipped and #11484 promised. ADDITION.

  1. A created session nests under its creator in the Sessions tab, to any depth — justified
  2. A created row whose creator is not running says "Created by {creator}" in visible text — justified
  3. A folded row shows "M MB in N hidden rows" beside its name — justified
  4. Task rows gain a "task" marker; expanders hiding sessions say so — justified
  5. Footer Sessions count reconciles top-level vs nested once any session nests — justified
  6. New footer stat "Stored session logs 4,096+" with a retention remedy, only when the store exceeds the scan cap — justified
  7. Memory column "?" hint says a parent's figure is not a family sum — justified
  8. Wire surface: parent {slot, key} per row, lineage_over_cap/lineage_cap on totals, sid on runtime rows — justified
  9. New cross-log reader crew_log/tree.py (pure fold + capped, cached scanner) and four store helpers — justified
  10. Dev capture harness (one of 547 sibling capture-*.mjs) plus black-baseline removal reformatting three touched files — rides along, harm-free

Provenance is derived, not inherited: the base crew-log-core.md already specified "a fold that builds the session tree keys it by slot and reads one session/opened per crew log," and #11472/#11484 record the field and its promised reader. Consumers counted: parent → sessionRows.ts buildTree + SessionsTab.tsx; lineage_over_cap/lineage_cap → the footer stat (grep over website/src, 2 non-test consumers); sid → _lineage in session_memory.py. The scanner's cap, cache and size-floor each carry a measured or OS-level cause stated in the spec section shipped with them.

[FIRST-PRINCIPLES-REVIEWED] aa60e5a

@github-actions

github-actions Bot commented Sep 19, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] aa60e5a

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

@github-actions

github-actions Bot commented Sep 19, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

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

Review details

I have thoroughly reviewed the diff. The discovery pass produced no candidates, and my own Step 2 examination of the core logic — fold_tree and its cycle colouring, the SessionTree scanner's cap/eviction/size-based cache validation, read_head's torn/damaged/missing-line disambiguation, opened_record's bounds-refusal, parent_payload, the backend slot-spelling join, and the frontend nestsUnder forest guarantee, getLeafRows flattening semantics, and per-row getIsGrouped()-gated rendering — surfaced no reachable, groundable defect at the required bar. Imports (fmtMb, InfoTip), the placement="top" prop, and the title-attribute contract the tests rely on all check out.

No findings.

[OPUS-REVIEWED] aa60e5a

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

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

@chenmingwei23
chenmingwei23 force-pushed the feat/session-tree-projection branch from cb33c96 to 2677a28 Compare September 19, 2026 02:56
@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 19, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition: fixed

  • span=fed34b1a9589 -- the creator citation lived only in a native title

Outcome: fixed in 2677a28.
No name cell carries a "Created by" title any more. A created row that could not be nested under its creator (creator not running, or a cycle) shows "Created by {creator}" as visible text beside its name; the name is what ellipsizes first, the citation keeps up to 60% of the cell, so the orphan row in the attached frame reads "Created by chat-1399-1789600101" in full. A row that IS nested under its creator has its place as the citation and the creator's expander names the relation ("Collapse sessions under {name}"), so it does not repeat the name above it.
Pinned by website/src/test/SessionsTab.test.tsx: the orphan row shows the text, the nested row does not, and no cell carries a "Created by" title.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition: rebutted

  • span=aa0294420cf4 -- the fold chevron was read as "a guess"

Outcome: rebutted; evidence added.
The chevron is the table's existing expander, the same control that folds a session's tasks today, unchanged in shape or place. What this PR changes is its label: an expander that hides sessions says so ("Expand sessions under {name}" / "Collapse sessions under {name}") instead of borrowing the tasks wording. The collapsed frame the evidence gap asked for is now in the body: the conductor folded, its two workers and their task hidden, the orphan and the Slack row where they were.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition: fixed

  • span=04d95dffa1a5 -- created_by_with_log handed the user a raw UUID and "log" vocabulary

Outcome: fixed in 2677a28.
The string is gone from every catalog, and so are the fields that fed it: the wire carries parent {slot, key} only. The citation names the creator by its display name when it has a live row, else by the slot key the log cited, which is the name the table already gives an untitled session. Nothing on this page can open a crew log by sid, so nothing here says "log".

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition: fixed

  • span=cac905d17fc2 -- item 6, the log sub-field had zero consumers

Outcome: fixed in 2677a28 by subtraction.
parent.log is deleted from the payload and log_present from the fold. parent.sid went with it: its only consumer was the tooltip string the UX lane had this round remove, and the tree is keyed by slot (a slot outlives its ACP session; the live row a child nests under is the slot's). The wire is now parent {slot, key}, both consumed by sessionRows.ts. The sid stays in the entry as an audit citation for a reader of the logs themselves; crew-log-projection.md section 6 says so and says nothing reads it today.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition: fixed

  • span=540888ca6bf4 -- item 9, read_opened_record and TreeNode.sids had zero consumers

Outcome: fixed in 2677a28 by subtraction.
Both are deleted. The scanner inlines the read it always did, and the fold keeps the set of slots that have a log as a local, which is all it needed the per-slot sid list for.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition: fixed

  • span=d70a245e31b2 -- session-head cache had no population bound

Outcome: fixed in 2677a28.
One named cap, TREE_UNIT_CAP = 4096, applied at admission: a scan admits the first that many unit directories in the store's name order and neither reads nor caches the rest, so the head cache holds one entry per admitted unit and no more whatever the store holds; a unit that falls past the cap because the population grew in front of it is evicted like a removed one. Every retained string was already bounded at admission (MAX_ACP_SESSION_ID_LEN, MAX_SHORT_STRING; oversize refuses the unit). The overflow is counted in SessionTree.omitted and said once per snapshot on the wire as totals.lineage_omitted, which the Sessions footer shows whenever it is not zero, so a session whose log went unread (shown with no creator) is not mistaken for one nobody created.
Tests: test_crew_log_tree.py (units past the cap are neither read nor cached and are counted; a unit that falls past the cap is evicted so the cache never exceeds it), test_session_memory.py (the count reaches totals), SessionsTab.test.tsx (the footer stat appears only when it is not zero).

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition: fixed

  • span=d69e3403b7fa -- session lineage was omitted from the feature map

Outcome: fixed in 2677a28 (adjudication downgraded this to advisory; the row edit is cheap and true, so it is done).
The system row in docs/feature-map/README.md now names the Sessions plane's nesting, its page files (SessionsTab.tsx, sessionRows.ts), the handler and sampler that own the payload (handlers/sessions.py, session_memory.py, lineage from crew_log/tree.py) and GET /api/sessions/memory. scripts/check_feature_map.py passes against the base.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

CI note on cb33c96: the two macOS reds are main-owned and untouched by this diff.

Neither file is in this PR. The Comment History Gate red (a "no longer" in a docstring) and the Fast Gate / Coverage Gate cascade it caused are fixed in 2677a28.

@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 19, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/session-tree-projection branch from 2677a28 to 999bdcd Compare September 19, 2026 03:17
@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 19, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition: fixed

  • span=758e5ffe56f3 -- the scan cap was applied after an unbounded listing

Outcome: fixed in 999bdcd.
store.unit_dirs(kind, limit=...) now bounds the enumeration while it runs: entries stream through heapq.nsmallest as an unsized generator, so the heap holds at most limit paths and the store never materializes or sorts the whole population; the entries past the heap are counted and returned beside the kept list. tree.py passes TREE_UNIT_CAP as that limit and takes the count as omitted, so the one named constant bounds the listing, the reads and the cache alike. A root with a million unit directories costs a million stat calls and a 4096-element heap.
Tests: test_unit_dirs_keeps_the_first_names_only_and_counts_the_rest pins that the heap receives an object with no len (a list handed to nsmallest would take its sort-everything shortcut) and that the kept names are the first in order with the rest counted; the two cap tests from round 0 still pass on the new path.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition: fixed

  • span=c3b0cae4175d -- learn-cron-dashboard.md described parent as {slot, sid, key, log}

Outcome: fixed in 999bdcd. The row list now reads {slot, key}, the shape parent_payload emits and client.ts and crew-log-projection.md section 6 declare.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Backend Tests (Windows) (6) on 077d796 went red on test/test_member_memory_publication.py::test_cancelled_dashboard_request_drains_worker_before_deciding_retirement[provision-opt_in] ("request did not reach the worker"), a file this PR does not touch; the test passes locally on this head. A timing flake on the Windows shard, like the decisions-gate one two heads ago; the new head re-runs it.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition: fixed

  • span=d4a7deef048c -- tree.py:271: "which no row on screen nests on" contradicts the spec's restarted-session exception

Outcome: fixed in 0a09bda, and since this span is at its third round (2, 8, 16: each time a tree.py docstring restating section 6 of the spec and drifting from it), the fix is to the class of comment rather than the sentence: the SessionTree class docstring is now the one place in the module that states what the cap leaves unread and the single case in which a live row nests on it (a slot restarted since it was opened, whose parent lives only in its older, closed log, folds as a root while the store is over the cap); records() points at that docstring instead of restating it, and the two sampler comments in session_memory.py carry the exception and point at the same place. No behaviour changes.
Tests: none needed (comments); tree + sampler tests still 75 green.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition: fixed

  • span=62544988ac5a -- "Created by X (not running)" states a state, not its consequence; the reader cannot tell whether the row is a problem

Outcome: fixed in 0a09bda with the item's shape: "Created by {{name}} (not running, so shown top-level)", in all 13 catalogs; the spec's sentence on the citation and the body follow. The frames are re-shot with the new text.
Tests: SessionsTab.test.tsx asserts the new visible text on the orphan row (two places).

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition: rebutted

  • span=70f2dae33b5c -- front-load the removes/keeps sentence ahead of the command and cut the stored-logs hint to about three sentences

Outcome: rebutted for this round, on the lane's own previous verdict: on 077d796 (09aa1aa01e56) the UX lane asked for two sentences of prose, then the command with where it is typed, "keeping the what-it-removes detail last", and the hint now has exactly that shape (two prose sentences, the command, the removes/keeps sentence). Reordering it again on the next head would be the fifth reshaping of this hint by opposing asks (rounds 9, 10, 12, 13, 15), so the choice between the two orders goes to the human reviewer rather than into another push; the text is one string in 13 catalogs either way.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition: rebutted

  • span=e578263b67ac -- item 10, rides along: the black reformat of session_memory.py and two test files, and their baseline removal

Outcome: rebutted as under its four earlier spans (23caa02cd0fd, 49b2f6b162dc, 631aa564f59b, 30e29096e5b3): every one of the three files is edited by this PR, scripts/check_black_formatting.py fails the build until a touched file that became black-clean is pruned from .github/black-baseline.txt, and the body's "What changed" names the three files and the pruning. The item itself calls it formatting only.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Retrospective addendum (round 16). A second span reached three rounds: d4a7deef048c, the GPT lane's tree.py docstring finding (rounds 2, 8, 16), each time a docstring restating the spec's admission semantics and drifting from it. Mechanism: prose in tree.py that restates section 6. Verdict: smaller replacement, made in the head this comment precedes: one statement in the SessionTree class docstring, pointers from records() and from the two sampler comments, no restatement elsewhere. Round-10 verdicts on every other mechanism stand (all KEEP); nothing subtracted. With this head every whole-design lane is PASS for the first time; UX's two suggestions are dispositioned above (one taken, one left to the human reviewer), and Design's "verify the real gateway once" cannot be done on this host (the pod's kiro-cli child fails on systemd-run; documented in the body), so it is left for a reviewer with a booting pod.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition: fixed

  • span=11211e5fc8a5 -- indent no longer marks a task: sessions and tasks interleave in one tree with no visible kind cue

Outcome: fixed in a7bd77b with the item's smallest fix: task rows carry a muted, small-caps "task" marker before their name (key task_marker in all 13 catalogs), so an indented row says its kind in the table itself rather than only on hover (a session's name underlines, a task's does not) or in the expander's aria-label. The spec's Sessions-table passage records the reason. Frames re-shot.
Tests: SessionsTab.test.tsx asserts the marker on task rows and its absence on a session row.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition: rebutted

  • span=981d1c3fa13a -- the stored-logs hint renders as about twelve lines in a 300 px bubble; split it into two paragraphs or trim

Outcome: rebutted. InfoTip renders its text as one paragraph (whitespace-normal, and the same string is the button's title), shared by 84 hints, so a second paragraph is not available to this string without changing the component for all of them (said under 3d198cd26150 on 6c75ce8). Trimming it again would undo what the lane asked for on the two previous heads (09aa1aa01e56: where the command is typed and the removes/keeps sentence last; 3d198cd26150: what the command removes and keeps), which the Design lane's honesty finding (66b8c3cea15... on b3f8d83) also requires. The hint's length is the price of those three verdicts; which of them to drop is a call for the human reviewer, offered in the final report.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

CI on 0a09bda: two Windows reds, neither from this diff. Backend Tests (Windows) (6): test/test_member_memory_publication.py::test_cancelled_dashboard_request_drains_worker_before_deciding_retirement ("request did not reach the worker"), the same timing flake as on 077d796, now red on 2 of the last 3 heads; the test passes locally and this PR does not touch that area, so it looks like a repository flake worth a look outside this PR. Build Windows Installer (x64): "Installed gateway became ready in 14.75 seconds" and then exit code 1 with no message from the ceiling step; the job was green on the two previous heads with identical packaging, and this head changed only comments, catalogs, the capture harness and one test string. The new head re-runs both.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition: fixed

  • span=fc270711ff60 -- SessionsTab.tsx:610: the task marker uses text-[9.5px], below the 10px typography floor

Outcome: fixed in 9bc98ac: text-[10px].

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition: fixed

  • span=b6e6dfc947fb -- "4 hidden rows, 964.3MB" beside the parent's own Memory cell does not say whose megabytes those are

Outcome: fixed in 9bc98ac with the item's wording: the badge reads "964.3MB in 4 hidden rows", the relation in the words, in all 13 catalogs (hidden_rows_memory); the spec's sentence on the badge says why. Frames re-shot.
Tests: SessionsTab.test.tsx asserts "576.0MB in 2 hidden rows" on the folded Debugging session.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition: rebutted

  • span=62dff47b677c -- the stored-logs hint is about 90 words with an inline command; front-load two sentences and let the removes/keeps detail trail, or point at the Archive page

Outcome: rebutted for this head; the same reshaping was asked on 29df34d (f9b312d346bf), 43e3e2f (70f2dae33b5c) and 0a09bda (981d1c3fa13a), each time in the opposite direction from the lane's own previous verdict (3d198cd26150 asked for the removes/keeps sentence; 09aa1aa01e56 asked for it last, after the command, which is the current order). The Archive page is a read-only list of transcripts and cannot show what retention would touch in the crew-log store. The text is one string in 13 catalogs; which shape to keep is left to the human reviewer, with the history in these comments.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition: rebutted

  • span=3b0fc3da9891 -- lead the Sessions hint with the definition and put the task-count disclaimer second

Outcome: rebutted: the current order is the one the lane asked for twice, on 2565090 (dbd35510660f: "Tasks sentence first") and on 077d796 (b48ffda0fbbd: say outright that the task sessions are a separate count). The reader who "could not have told them apart without the bubble" is the reader that sentence exists for, which is why it stays first.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition: rebutted

  • span=067163e90702 -- item 10, rides along: black-baseline removals and format-only hunks in three touched files

Outcome: rebutted as under its five earlier spans (23caa02cd0fd, 49b2f6b162dc, 631aa564f59b, 30e29096e5b3, e578263b67ac): the three files are edited by this PR, scripts/check_black_formatting.py fails the build until a touched file that became black-clean is pruned from .github/black-baseline.txt, and the body's "What changed" names the files and the pruning; the item itself says the change is mandated by the gate.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/session.md, src/kiro_crew/dashboard/chat_runner.py, src/kiro_crew/dashboard/chat_utils.py (#12007) and test/test_work_ledger.py (#12008), neighbours of files this PR touches; one commit, targeted tests green on the rebased tree (312, including test_work_ledger.py); CI re-running. On a7bd77b the on-demand macOS suite went red on two tests this PR does not touch (test_theme_install.py::TestCopyInstalledTheme::test_dest_case_variant_ancestor_rejected_on_case_insensitive_fs and test_platform_log_append.py::test_concurrent_short_writers_serialize), which reads as the runner gaps #11943 tracks rather than this diff. This push also carries the round-18 dispositions above.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition: fixed

  • span=eda4e7fb57ed -- the Memory hint says figures never roll up, but a Group by header row shows a sum

Outcome: fixed in 5c3b0a1 by the item's first fix: the hint gains "Under Group by, a group's header row totals its members." in all 13 catalogs, so the one row kind that does sum (TanStack's sum aggregation on the grouped column, the base table's behaviour) is named beside the rule for every other row. The spec's Sessions-table passage says the same. Frames re-shot.
Tests: SessionsTab.test.tsx asserts the new sentence on the Memory header's hint.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition: fixed

  • span=ffab6d1675ef -- task identity stays fuzzy: column "Session / Task", footer "Task sessions", rows tagged "task"

Outcome: fixed in 5c3b0a1 with the item's smallest fix: the Sessions footer hint ends with "A task row is a session run as a task.", in all 13 catalogs.
Tests: SessionsTab.test.tsx asserts the sentence on the Sessions stat's hint.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition: rebutted

  • span=78b09a62726e -- front-load the stored-logs hint's action and cut the keep/remove tail to one sentence

Outcome: rebutted for this head, as for the same ask on 29df34d (f9b312d346bf), 43e3e2f (70f2dae33b5c), 0a09bda (981d1c3fa13a) and a7bd77b (62dff47b677c): the lane's own earlier verdicts fixed the present order (removes/keeps after the command, 09aa1aa01e56) and content (what the command removes and keeps, 3d198cd26150), and the Design lane's honesty finding (66b8c3cea15... on b3f8d83) fixed the restart sentence. The shape is one string in 13 catalogs; the human reviewer chooses between the two orders, with this history.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition: rebutted

  • span=d80e45605dd4 -- rescan every Nth sample: the warm scan re-stats every admitted unit on each 5 s poll while lineage changes on lifecycle timescales

Outcome: rebutted for this PR on the measured cost, not on the idea. At the cap (4,096 units, local disk) the warm scan is 90-120 ms every 5 s on the executor, about 2% of one core while the Sessions tab is open and nothing while it is not; below the cap it is proportionally less, and a store that large is the retention-off case the footer stat exists to surface. Sampling every Nth poll would add a staleness window (a fresh created session nesting late) and a second knob for a cost that is not yet a cost; the spec records the measurement so a real store that contradicts it has a number to compare against, and the amortised scan is the first thing to add then (the option is written down on #11956, which this PR closes).

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition: rebutted

  • span=f2c6f6cee28a -- item 10, undeclared: black-baseline removals and reformat-only hunks in two test files

Outcome: rebutted as under its six earlier spans (23caa02cd0fd, 49b2f6b162dc, 631aa564f59b, 30e29096e5b3, e578263b67ac, 067163e90702): both files are edited by this PR, scripts/check_black_formatting.py fails the build until a touched file that became black-clean is pruned from .github/black-baseline.txt, and the body's "What changed" names the files and the pruning, inside the first 8000 bytes.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

CI on 9bc98ac: Backend Tests (3.12, 6) shows "The operation was canceled" at 12:57:17 after ten minutes of green progress dots (no failing test, no pytest timeout; the job's own limit is 60 min), and Coverage Gate failed downstream of it; nothing in this PR cancels runs on its own head, so this reads as the runner being withdrawn. The new head re-runs it.

buluoray
buluoray previously approved these changes Sep 20, 2026

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

Approving at head 5c3b0a1d. No blocking findings. The conflict needs a rebase, but it does not need a re-implementation — that distinction is the main thing I want on the record here.

The conflict is MECHANICAL and docs-only

git merge-tree --write-tree origin/main pr11929 gives exactly one content conflict. All code auto-merges — including src/kiro_crew/session_allocation.py — as do all 13 locale JSONs and the other three spec docs.

The one conflict is in docs/system-specs/modules/learn-cron-dashboard.md, where both sides edited the same giant one-line paragraph (**Sessions**: GET /api/sessions ...) around line 2349: main inserted a clause into the /api/sessions/usage sub-description, this PR inserted the parent field into /api/sessions/memory and added lineage_over_cap / lineage_cap to totals. Two independent sentence insertions into unrelated sub-clauses. Resolution is keep-both, about two minutes by hand, zero code risk.

So the CONFLICTING/DIRTY state and the 86-vs-87+ check count are fully explained by a stale docs paragraph, not by code divergence. I checked this specifically because a conflicted PR on this repo cannot have a merge ref built, which means its green checks can be pre-conflict evidence — worth distrusting by default. Here the code side is genuinely unaffected: no symbol, model or code path this PR builds on was rewritten by main.

The fold is bounded, and it does not re-read on every page load

TREE_UNIT_CAP = 4096 cuts every loop: records() uses islice(preferred, cap) for named live units and unit_dirs(..., limit=cap-len(named)) stops one candidate past the limit (if len(kept) >= max(0, limit): return kept, True). A store of a million units costs cap+1 stats rather than a walk. The SessionTree head cache is owned by the sampler for the gateway's life and validated by (segment, st_dev, st_ino, size-floor), so an untouched log costs one stat; the scan itself runs in _blocking_sample, off the event loop. Overflow is reported as a fact via over_cap → lineage_over_cap / lineage_cap, so nothing pays to count the population it declined to read.

Malformed input degrades to the pre-PR state

opened_record() returns None — a refusal — for an unreadable or non-session header, an id that does not fold back to its own directory, or any retained string past MAX_ACP_SESSION_ID_LEN / MAX_SHORT_STRING. read_head() separates torn-mid-append (unterminated and unparseable → transient, re-read) from interior damage (terminated and unparseable → final, cached once, so a planted bad line costs one read rather than one per scan). And SessionTree.snapshot() wraps fold_tree in a bare except that logs and returns {}, so a store fault degrades to "no creator known" — exactly the state before this PR. A bad log affects its own row and nothing else.

Cycle handling is fail-closed, which is the interesting case for a tree folded from untrusted-ish files: fold_tree follows an edge only when the parent has a log of its own (parent_slot in has_log), _cycle_members colours the edge graph and marks every node on a cycle so the consumer nests none of them while a hanger-on keeps its edge, and parent_payload nulls the nesting key on node.cycle or a self-citation. A forged or damaged cyclic citation cannot produce infinite nesting.

Mutations for the two load-bearing tests

test_a_cycle_marks_every_member_and_a_hanger_on_keeps_its_edge reds if you delete on_cycle |= _cycle_members(edge) in fold_tree (or make _cycle_members return set()): the A↔B cycle folds with cycle=False and assert nodes["A"].cycle is True fails. Nicely isolated — the self-cite case survives on the separate if parent_slot == slot branch, so this mutation tests only the multi-node detector.

test_units_past_the_cap_are_neither_read_nor_cached_and_the_overflow_is_reported reds if store.unit_dirs's overflow return becomes return kept, False (over_cap stays False), and reds differently if the early return is removed entirely (all three units get read, so len(reads) == 2 fails). It asserts the real read count and head-cache membership, not a call.

Both assert effects rather than call existence.

Verified clean

No new route or auth surface — this extends the existing owner-gated /api/sessions/memory payload and adds no endpoint. The whole reader sits behind KIROCREW_CREW_LOG, imported lazily in _lineage and returning ({}, False, 0) when off, and the session log lives under the OS-fenced crew-log root rather than the tool-gate-only transcript root — which is the correct side of this repo's forgeability line. session_allocation.py:_bounded_session_id carries an oversize or empty backend id as None rather than truncating, since a truncated id would name a different unit. i18n is key-symmetric across all 13 locales (the 11–14 line differences are CLDR plural categories: ja/ko/zh-CN other-only, en one/other, ru one/few/many/other) with en-XA regenerated. No literal colors in the added lines of SessionsTab.tsx or sessionRows.ts.

Not verified: the Python and Vitest suites were not executed — this was a read-only review, so the findings come from source at 5c3b0a1d plus git merge-tree, not from a test run.

One practical note: this approval will be voided by the rebase under require_last_push_approval, so re-request review after resolving that one paragraph and I will re-approve without re-reading the code, since the merge preview shows nothing else moves.

Not merging; that is the maintainer's call.

… the System page

A session opened through session_create records its creator on its own
session/opened entry (#11472). This adds the reader. crew_log/tree.py folds
the first entry of every session log into slot -> parent edges: an orphan
and a cycle degrade to root, any opened entry carrying a parent wins and
one without never retracts it, the oldest log's word stands. A cached
scanner reads one bounded head per log and re-reads only a replaced or
removed segment. /api/sessions/memory carries `parent` per session row
(slot, sid, the creator's live key, whether the sid resolves to a log),
and the System page Sessions table nests a created session under its
running creator the way it nests a task, to any depth.

Closes #11484
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Rebased onto main c0be415708 (61 commits since e20f2581bb, including #11909, #12021, #12022, #11970, #12116); head is now aa60e5a730, still one commit.

One conflict, in docs/system-specs/modules/learn-cron-dashboard.md (the GET /api/sessions/memory paragraph): main added the usage_text_scrape_enabled settings clause; this branch adds parent and totals.lineage_over_cap / lineage_cap. Both kept. A word-level diff of the two sides showed those as the only three divergences. Every other file is byte-identical to the previous head (same 32 files, +2823/-166).

Verified locally on the rebased head: 887 backend tests across 13 files (tree, sampler, session memory, crew-log store, retention, projection, the crew-log MCP server, routes, session cleanup); black on the touched files with the baseline prunes intact; isort, flake8, mypy; comment-history, agent-SDK boundary, sync-io, loop-locks, feature-map and docs-lint gates; all 12 added i18n keys present in the 13 catalogs plus en-XA; i18n:check clean. The frontend vitest suite was not run locally for this push (host load); CI runs 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

3 participants