Skip to content

feat(session): pluggable compaction methods - #11377

Open
jingchaodev wants to merge 1 commit into
kirodotdev:mainfrom
jingchaodev:feat/compaction-methods
Open

jingchaodev wants to merge 1 commit into
kirodotdev:mainfrom
jingchaodev:feat/compaction-methods

Conversation

@jingchaodev

@jingchaodev jingchaodev commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: let an operator pick a compaction that spends no model call, changing nothing for a config that never sets it: session.compaction_method defaults to native, today's /compact, and is set in Settings > Chat > Advanced.

At the auto-compact threshold the coordinator has one move: kiro-cli's /compact, a single model call over the whole window. At 99% of a 1M-token window that call took 2m12s, and every turn before it re-sent the whole window. A session that is mostly old tool output pays the same two minutes as one that is all decisions.

Why it matters

The wait lands on the busiest sessions. A long babysit or goal loop crosses the threshold several times a day, and the dashboard shows nothing while the call runs. Kiro Crew already owns a model-free way back to headroom, a session restart plus build_session_replay, but today it is reached only when /compact fails.

Not a goal

What changed (motivation → approach → change)

Motivation: at the threshold the only move is /compact, one model call over the whole window, and the chat shows nothing while it runs.

Approach: a second method, soft, frees the window without a model call. It restarts the session on purpose with the restart every compaction fallback already uses: hold the turn permit, wait for sub-agents that share the process, then _restart_held starts the new session and hands it the queued turns. The new session's first turn replays the transcript tail through build_session_replay, sized by replay_budget_chars (80K chars at a 1M window, 16K at 200K).

Change: one setting picks the method, and each case below either rotates or runs native.

Case What runs
native, the default /compact, as on main
soft on a dashboard tab's own session rotation: restart, then replay the tail
soft on a channel, cron, hook, sub-agent or workflow session native
soft whose estimate would not clear the threshold native
an idle compaction (session.idle_compaction) native: the idle arm never restarts a session

A rotation runs only when its estimate lands below the threshold by the margin /compact must reach. The new session's first context reading checks that estimate, and a rotation that freed too little arms the same failure cooldown as native. A forced Stop during the sub-agent wait ends the rotation as cancelled, and its notice names the rotation. A raise after the new session started reports failed; native never runs on the replaced session. A stored method name the loader does not know, for example a retired shake, loads as native.

The chat says what happened. A rotation posts "Session rotated (soft). The conversation above is still here; the agent remembers only the recent turns, earlier ones are gone from its memory." While it waits for sub-agents, it posts "The session is waiting for its sub-agents to finish before it rotates (soft). Your messages are kept." On a session that can rotate, the mid-turn notice says the chat "will be compacted" instead of "summarized", because a rotation writes no summary, and the replay leaves rotation notices out of the tail and clips an oversized newest row. A session that cannot rotate (a Claude backend, a cron-linked tab) keeps main's replay and wording even with soft set.

The method switch, the rotation and its estimate live in session_compaction.py and the new session_compaction_rotation.py and session_compaction_methods.py; the callback's method is in session_parts/policy.py and session_parts/turn_context.py, which src/kiro_crew/session.py re-exports. The tail budget and the replay switches are in context_assembly/replay.py, context_assembly/budget.py and context.py. dashboard/compaction_seed.py decides which sessions may rotate: a tab's own session key only. The notices are in dashboard/state_parts/session_events.py and dashboard/chat_turn/. The key is in config/sections_session.py, with its PATCH entry in dashboard/handlers/core_config_schema.py and its class in change_card_catalog_kinds.py. The Compaction Method select sits after Auto-Compact Threshold in website/src/pages/settings/ChatPanel.tsx, with its labels in the website/src/i18n/ catalogs. The spec is docs/system-specs/modules/session.md; config-baseline.json, settingsRegistry.gen.ts and the indexes under src/kiro_crew/docs/ are regenerated.

Backwards compatibility

Compatible: session.compaction_method defaults to native, and with it the coordinator dispatches exactly as main does and the replay is byte-identical. The compact callback gains a method keyword; its one registrant in src/ (dashboard/state_parts/session_events.py:_on_compacted) and every test fake accept it. build_session_replay, replay_text and replay_budget_chars gain keyword arguments with defaults.

Removes nothing: no key, record, route or public function goes away, and a config without the key reads native.

Tests

  • test/test_compaction_ladder.py: native reads no rotation seam; soft runs or hands to native; it waits for a shared sub-agent and says it is rotating, not failed; a Stop during that wait settles cancelled, names soft and releases the turn permit once; a raise after the new session started is failed with no native run; queued messages reach the new session; an idle compaction never rotates; a weak rotation cools down and may rotate again.
  • test/test_compaction_seed_writer.py: only a tab's own session key may rotate; a cron job tab, a cron run tab, a workflow tab and a channel session answer no.
  • test/test_replay_rotation.py, test/test_compact_after_turn_notice.py: a Claude session and a cron-linked tab replay and read as native with soft set; rotation notices spend none of the tail; the newest-row clip; the mid-turn notice's method.
  • test/test_session_compaction_methods.py, test/test_compaction_method_config.py, test/metrics/test_business_counters.py, test/test_dashboard_state_ws.py: the estimate arithmetic; the key and its PATCH entry, an unknown name loading as native; the counter for a rotation; the rotation notices, including a Stop's.
  • website/src/test/SettingsChatPanelCoverage.test.tsx, website/src/test/CompactionCard.test.tsx: the select writes the key and shows the pick at once; the card says "compacted" for soft, keeps main's "summarized" otherwise, and draws no raw pause glyph on a waiting notice.

The 1,467 tests in the 17 changed test files pass 5 runs at 4 workers and two shuffled orders in one process (seeds 11 and 4242).

Manual verification

native took 132 s at 99% of a 1M window (one model call, recorded 2026-09-05). soft spends no model call: the new session starts with at most replay_budget_chars of replayed tail. Still required: a live gateway run with soft through a real threshold crossing.

Screenshots / video

Captured from a gateway of this branch (kiro_crew.testing.harness.spawn_feature_gateway). The notice rows were written by the real compact callback, and the tab was reloaded from disk.

A soft rotation, and the notice while it waits for sub-agents:

Chat notice card under the last assistant reply: Auto-compacted at 82%. Session rotated (soft). The conversation above is still here; the agent remembers only the recent turns, earlier ones are gone from its memory.

Notice card: Auto-compacting at 82%. The session is waiting for its sub-agents to finish before it rotates (soft). Your messages are kept.

Settings > Chat > Advanced, closed and open:

Settings, Chat, Advanced: the Compaction Method select set to Native (Default), summarize in place, with its description

The Compaction Method select open: Native (Default), summarize in place, and Soft, rotate session, keep recent turns

The mid-turn notice with soft and with native, and the rotation notice at 420 px

Mid-turn notice with soft set: Context at 83%, past the 80% auto-compact threshold, the chat will be compacted when this turn ends

Mid-turn notice with native, the default: the chat will be summarized when this turn ends, as on main

The soft rotation notice at 420 px wide, wrapped under the last assistant reply

Related Issues

Refs #8865 (the dashboard looks frozen while auto-compaction runs): soft shortens that wait when an operator picks it, and the default is unchanged, so #8865 stays open.

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

@jingchaodev
jingchaodev requested a review from a team September 16, 2026 20:15
@jingchaodev

Copy link
Copy Markdown
Contributor Author

Intent: Let an operator choose a compaction at the auto-compact threshold that spends no model call: rotate the session and re-seed the successor from the transcript tail, optionally behind an elided digest of the dropped history. The default order stays ["native"], so a config that never sets session.compaction_method_order behaves exactly as before.
Not a goal: Changing the default method; a transcript row for the compaction seed; seed writers for channel surfaces; the handoff and snapshot methods, which are later PRs on the same ladder.

@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running labels Sep 16, 2026
@github-actions

github-actions Bot commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — 🟡 CONCERNS

Design-level review of 01093be3239a610e01b09a5ada2f586e2c2d3853 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

shake saves digests as durable compaction-role transcript rows that only this revision knows to hide, so rolling it back leaves those digests showing as chat bubbles.

Watch

  • Rolling back leaves visible digest rows. shake appends a row with role compaction and meta = {kind: "compaction_seed", …} to the transcript, and it is "on disk before the writer answers". Only the new COMPACTION_SEED_ROLE entries in the two transcript renderer lists keep it from being drawn. As the spec says, "a role no renderer claims falls to the chat page's bubble fallback, which would print the digest after a reload". The base replay already skips the row (it is not in RECALL_ROLES), so a revert or downgrade would not feed the digest back to the agent. But every tab that ever ran shake would then show a raw digest bubble. That migration story is missing.
    Clears when: the Backwards compatibility section states what a revert does to existing compaction rows (accepted as a Breaking: line, or a cleanup or ignore path named).
  • The removal check is capped. The description is cut off inside ## Backwards compatibility, so the reader list could not be fully checked. In this tree, chat_utils still imports the moved run_to_completion. The callback's new required method keyword has one registrant, dashboard/state.py, and the patch updates it. I found no broken reader.
    Clears when: the untruncated section lists dashboard/state.py:_on_compacted and the chat_utils.run_to_completion importers, each with a reason.

[DESIGN-REVIEWED] 01093be

Description read

[DESCRIPTION-READ] cb82f954d45269df79da379c0a3236b47b05c2dff980681b4073acaa44f284ec

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 16, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — 🔴 changes requested (blocking)

Reviewed 01093be3239a610e01b09a5ada2f586e2c2d3853 via the fork AI-review pipeline; updated in place on each push.

1 of 1 blocking finding(s) are security-class and were withheld from adjudication, so the blocking verdict stands.

BLOCKING -- src/kiro_crew/dashboard/compaction_seed.py:108 -- Cron-linked tabs admit rotations that scheduled turns cannot replay
if is_channel_key(key):
With shake configured, a threshold-crossing dashboard follow-up on a persistent cron tab -> _seed_slot admits cron:<id> and _rotate replaces its conversation -> the next scheduled _cron_callback uses build_message’s 20-row recall fallback, which excludes compaction rows, so the successor loses the saved digest and its earlier context.
Anchor: residual/crash-data-loss-corruption
Fix: Reject keys starting with cron: in _seed_slot, including suffixed execution keys, so both rotation methods fall back to native.
[BLOCK-MERGE] 01093be
[GPT-REVIEWED] 01093be

Adjudication (Opus 5.5) — is blocking on each finding proportionate?

F1 (fenced): I'm upholding it. Harm: the model loses saved context without anyone being told. The transcript stays on disk, so this is lost context for the model, not deleted user data. All three conditions are plausible in normal use, so a FLAG isn't justified:

  • Shake has to be switched on. It's opt-in (the default is native, patch line 9).
  • A cron tab gets admitted for rotation. dashboard_slot_key sends cron:<id> keys, including per-run suffixed keys, to the job's open cron-<id> tab (src/kiro_crew/dashboard/chat_utils.py:799-816). The new _seed_slot only refuses channel keys (patch line 1424), so a persistent cron tab with an open tab can be rotated.
  • The next cron fire drops the digest. The cron path never passes a session replay: only chat_runner.py:12160 and slack/handler.py:1802 pass compressed_history. So a fresh successor falls back to the 20-row recall (context.py:2880-2886). That recall goes through _quota_tail, which leaves seeds out (patch lines 740 and 781-808), so the compaction row is skipped and the digest never reaches the model. Nothing restores it.

Nothing here requires contradictory timing or input the system can't produce. The fix the finding proposes, refusing cron: keys in _seed_slot, is a one-line change.

[ADJUDICATION] 01093be3239a610e01b09a5ada2f586e2c2d3853 total=0 uphold=0 downgrade=0
[GPT-ADJUDICATED] 01093be3239a610e01b09a5ada2f586e2c2d3853

[ADJUDICATION-FENCED] 01093be3239a610e01b09a5ada2f586e2c2d3853 fenced=1 flagged=0
UPHOLD-FENCED F1 src/kiro_crew/dashboard/compaction_seed.py:108 -- An opt-in shake setting plus a persistent cron tab with a dashboard follow-up is an ordinary combination, and the next scheduled fire's 20-row recall (context.py:2880, _quota_tail without seeds) silently drops the digest, so no extreme-condition argument holds.
[GPT-ADJUDICATED-FENCED] 01093be3239a610e01b09a5ada2f586e2c2d3853

@github-actions

github-actions Bot commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — 🔴 BLOCK

Premise-level review of 01093be3239a610e01b09a5ada2f586e2c2d3853 via the fork AI-review pipeline — 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: BLOCK

The new context_budget.py copies six constants and _effective_window from context_assembly/budget.py, a module that already imports only the standard library.

Not justified as shipped

  • Item 7 — duplicate of src/kiro_crew/context_assembly/budget.py: the module says it exists because "the context facade pulls ~200 further modules". But the base context_assembly/__init__.py says "This package imports nothing", budget.py imports only the standard library, and replay.py imports only budget. The coordinator could already import those owners at module scope.
    Subtraction: delete context_budget.py and test_context_budget_shared.py. Import replay_budget_chars/replay_scale from context_assembly.replay and startup_context_chars from context_assembly.budget.
    Clears when: the copied module is gone, or an import-cost measurement shows context_assembly.budget is heavier than this module.
  • Item 8 — one consumer, generalized: rotation_ladder returns (ceiling,) or (). The PR states "never to a weaker rotation", so the tuple never holds more than one method. chat_runner reads it as _rotation_methods[0] if _rotation_methods else "".
    Subtraction: return str | None, and drop the for method in ladder loop in _run_method_ladder.
    Clears when: the function returns one value, or a second rung that ships is added.
  • Item 9 — undeclared: every compaction, including native, now sends CONTEXT_COMPACTIONS with a new method label.

What this change ships

Inventory (10 items) — 7 justified

Intent: let an operator replace the slow model-call /compact with a compaction that spends no model call. ADDITION.

  1. Compaction Method select in Settings > Chat > Advanced; session.compaction_method, default native — justified
  2. soft: the session restarts at the threshold and its successor replays the transcript tail — justified
  3. shake: writes a hidden digest seed row, then restarts — justified
  4. A rotation that cannot run, or frees too little, hands to native; an ineffective one holds the session on native — justified
  5. Rotation notices in chat, and "will be compacted" mid-turn wording when a rotation is set — justified
  6. With a rotation set, the replay clips an oversized newest row — justified
  7. New context_budget.py copying the budget constants and _effective_window — duplicate of context_assembly/budget.py
  8. rotation_ladder returns a tuple of at most one method — one consumer, generalized
  9. The compaction counter gains a method label on every compaction — undeclared
  10. run_to_completion moved to async_utils — justified

Blockers

  • Second copy of the context-budget constants. context_budget.py redefines CONTEXT_BUDGET_BASE, LESSONS_STARTUP_CAP, PREFS_STARTUP_CAP, REFERENCE_WINDOW_TOKENS, MIN_CONTEXT_BUDGET_BASE, REPLAY_BUDGET_CHARS and effective_window. The patch's own test checks the two copies are equal (7 asserts, patch lines 5574–5581). MIN_CONTEXT_BUDGET_BASE has 0 consumers outside that test (grepped MIN_CONTEXT_BUDGET_BASE in the patch).
    Subtraction: import the existing owners in context_assembly/ directly.
    Clears when: context_budget.py is deleted.

[FIRST-PRINCIPLES-REVIEWED] 01093be

Description read

[DESCRIPTION-READ] f2113a74f4be3aedb9bbc5ad0a235cf4ba79064877dedcdd8480a923469b374e

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 added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 16, 2026
@github-actions

github-actions Bot commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed 01093be3239a610e01b09a5ada2f586e2c2d3853 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings that block the merge; one advisory.

FINDING — src/kiro_crew/session_compaction.py:1132 — with compaction_method="shake" on a dashboard tab past the 500-row conversation quota (_REPLAY_CONVERSATION_MAX_ROWS), _await_cotenants(..., method=method) holds the turn semaphore for up to cotenant_wait_secs (600s) and then cancels the live sub-agents ("stopped when an auto-compaction rotated the session"). Only after that does write_seed reach if getattr(rows, "conversation_quota_cut", True): return SEED_TAIL_ONLY, so the result is OUTCOME_UNAVAILABLE and native runs. A successful native /compact never needed those sub-agents stopped, and this repeats on every threshold crossing for that session → Fix: decide whether the seed can be written (the quota-cut check and the tail split) before calling _await_cotenants. For example, add a precheck to the writer, or have the writer return its verdict before the wait and write afterwards.

[OPUS-REVIEWED] 01093be

@jingchaodev
jingchaodev force-pushed the feat/compaction-methods branch from dfa03cd to c5b7fa9 Compare September 16, 2026 22:05
@jingchaodev

Copy link
Copy Markdown
Contributor Author
  • fixed span=4e32029bffcf Configured tail sizes can create an unreplayed history gap

Root cause accepted as stated: two tail budgets (writer keep_tokens*4, replay window-scaled). At a 200K window the writer cut at 80K chars while the replay kept 16K, so rows between the two cuts were in neither the digest nor the tail.
Fix at c5b7fa9: one budget and one walk. context.replay_budget_chars(window) is the replay's own figure; the seed writer cuts at it (SeedWriter(key, method, window_tokens)), _rotate projects from it, and build_session_replay renders through the same walk_tail the writer splits with. session.compaction_keep_recent_tokens is removed rather than threaded: a second number is the defect class.
Pinned by TestNoGapBetweenDigestAndTail at 200K, 1M and the reference: the first replayed row is the row right after through_ts and every newer row is replayed verbatim. Mutation-checked from both sides (writer at fixed 80K fails the 200K case; unscaled replay budget fails the cut-equality test).

@jingchaodev

Copy link
Copy Markdown
Contributor Author
  • fixed span=451b2d4903f8 Function-local imports violate top-level-imports

context.py (both history.transcript_sort_key sites): hoisted to module scope at c5b7fa9. Probed in a clean interpreter: history never loads context and vice versa, so no cycle; the gateway boot already loads both.
dashboard/state.py:4301: kept lazy with the rule's # circular import note. It IS a cycle: compaction_seed imports chat_utils, and chat_utils imports dashboard.state at module scope, so a module-scope import closes state -> compaction_seed -> chat_utils -> state. compaction_seed itself now imports context at module scope (no cycle there).
session_compaction.py: kept lazy, commented as a weight decision, not a cycle. Measured: importing kiro_crew.session_compaction pulls 239 modules; context adds 204 on top, and session_compaction is imported by kiro_crew.session on every CLI/test import that never starts a gateway. Same reason the existing ACP import in _compact_in_place is lazy.

@jingchaodev

Copy link
Copy Markdown
Contributor Author
  • fixed span=512b83460fce Item 4: compaction_keep_recent_tokens promises to size soft's tail but never reaches the replay

Taken as the subtraction proposed: the key is gone at c5b7fa9. Both soft and shake now carry exactly the replay's own window-scaled budget (context.replay_budget_chars(window)), and the projection charges that same figure, so carried equals what the successor receives by construction.
Config test pins the key's absence and that a stray value in a config file is ignored; test_compaction_seed_writer.py pins that the writer reads the replay's budget function and has no arithmetic of its own.

@jingchaodev

Copy link
Copy Markdown
Contributor Author
  • fixed span=b3868a343002 Item 8: replay_line/split_tail re-spell the replay's inline walk

One spelling remains at c5b7fa9: session_compaction_methods.walk_tail is the budgeted newest-first walk; build_session_replay renders through it (with its inject cap and reserved share passed in) and split_tail cuts through it. The +2 separator is one constant (LINE_SEPARATOR_CHARS), the line render is one function (replay_line).
TestSplitTailMatchesReplay now runs at a 200K window and the reference; the inject-share behaviour the replay had is pinned in TestWalkTail and the existing test_history_race.py suite, which passes unchanged.

@jingchaodev

Copy link
Copy Markdown
Contributor Author
  • fixed shake sizes its kept tail with an unscaled budget, reopening the no-gap history gap on sub-1M windows

The sharper statement of the same defect GPT blocked on: at the default keep_tokens a 200K dashboard model already had an 80K writer tail against a 16K replay tail. Fixed at c5b7fa9 by making the writer, the projection and the replay read one window-scaled budget (context.replay_budget_chars) and render through one walk; the pinning test runs the 200K case explicitly.

@jingchaodev

Copy link
Copy Markdown
Contributor Author

Round 1 at c5b7fa9fc (rebased onto current main): the writer, the projection and the successor's replay now share one window-scaled tail budget and one walk, session.compaction_keep_recent_tokens is removed, the history import in context.py is hoisted, and the body reflects the final state. Gates on this head: black/isort/flake8, brand and harness gates, config baseline byte-identical, mypy --platform linux clean, 97 new tests and 1762 across the compaction consumer suites.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 16, 2026
@jingchaodev
jingchaodev force-pushed the feat/compaction-methods branch from c5b7fa9 to bb82582 Compare September 16, 2026 23:00
@jingchaodev

Copy link
Copy Markdown
Contributor Author
  • fixed span=dc2d7de999a7 Timestamp collisions drop undigested replay rows

Accepted: _row_covered used key <= coverage, so a tail row sharing the boundary stamp was dropped from the replay without ever entering the digest (merged streams and legacy second-resolution stamps both reach it).
Fix at bb82582: the digest now names the exact row it covers through. row_fingerprint(row) (delivery id meta.mid/meta.sendId when present, else a hash of role, stamp and content) is recorded as meta.through_row; the replay stops AT that row, and drops only rows STRICTLY older than through_ts. A row that merely shares the boundary stamp is carried. A legacy seed without through_row is exclusive at its stamp (safe side: a duplicate, never a drop).
Pinned: equal-stamp twin carried (replay suite), end-to-end two-rows-one-stamp at the writer's real boundary (writer suite), legacy exclusive case. Mutations red: <= restored, fingerprint match removed.

@jingchaodev

Copy link
Copy Markdown
Contributor Author
  • fixed span=4e32029bffcf Oversized inject rows corrupt the replay boundary

Accepted: split_tail walked with walk_tail's defaults (no inject clip, no inject reserve) while the replay clipped and reserved, so a huge newest inject could eat the writer's budget and digest conversation the replay carries verbatim.
Fix at bb82582: context.replay_walk_options(window) returns the exact walk_tail kwargs the replay uses (budget, the inject-clipping renderer, the inject reserve); build_session_replay walks with them and build_seed splits with the same **options. walk_tail also reports the tail's start as the OLDEST kept row, so a skipped inject inside the tail cannot shift the boundary.
Pinned: a 100K-char newest inject leaves recent conversation in the tail and every tail row replays verbatim; a source pin asserts split_tail(rows, **options). Mutations red: writer split with the bare budget; tail start computed as a count.

@jingchaodev

Copy link
Copy Markdown
Contributor Author
  • rebutted span=1ebd9b37e14c function-local from kiro_crew.context import in session_compaction.py

Not a cycle, a measured weight decision, and the rule's own exemption class (deferring work that must not run at import). Probed in a clean interpreter: import kiro_crew.cli loads kiro_crew.session (and therefore this module) but NOT kiro_crew.context; context adds ~204 modules on top of the 239 this module already pulls. A module-scope import would charge every kirocrew <cmd> invocation for a compaction only a running gateway performs, the same reason _compact_in_place defers its ACP import.
The two sites now say so in a comment naming the measured cost (bb82582), matching the repo precedent recorded in docs/system-specs/modules/auto-improvement.md D-76 (boot-path weight is a legitimate reason to keep an import lazy).

@jingchaodev

Copy link
Copy Markdown
Contributor Author
  • fixed span=cdd6beff00b4 "dashboard renders it as a collapsed marker" contradicts the absence of a renderer

Docstring on SEED_ROLE now says the transcript draws no row for it because no renderer claims the role, with the collapsed marker named as follow-up work (bb82582), matching the spec and the PR body.

@jingchaodev

Copy link
Copy Markdown
Contributor Author
  • fixed span=159e67c3578f help text does not state the native backstop

The key's help text now says native always runs last even when unlisted, that shake steps aside on surfaces without a writer, and what ['shake', 'soft'] means (bb82582; config-baseline.json regenerated with it).

@jingchaodev

Copy link
Copy Markdown
Contributor Author
  • needs-a-decision span=3c5d9ebae4a9 Item 1: one consumer, generalized (list vs scalar)

The list shape exists for exactly one order, ['shake', 'soft']: digest where a surface can write one (the dashboard today), tail-only elsewhere (channels register no writer, so shake steps aside and soft runs). A scalar compaction_method: shake cannot express that; it would mean shake where possible and native (the minutes-long model call) elsewhere, which is the wait the operator opted out of. The help text now documents that order (bb82582).
Maintainer question: keep the list (one real two-step order, documented) or shrink to a scalar and accept native as the only fallback on channel surfaces? I recommend the list; the follow-up PRs on this ladder (handoff, snapshot) add a second and third rotation method, which makes the order shape load-bearing rather than speculative.

@jingchaodev

Copy link
Copy Markdown
Contributor Author

Round 2 at bb8258281 (rebased onto current main): the digest names the exact row it covers through (through_row, a fingerprint) and the replay stops at that row rather than at an equal timestamp; the seed writer splits with the replay's exact walk options (replay_walk_options: budget, inject clipping, inject reserve); the key's help text states the native backstop; the SEED_ROLE docstring describes the row as hidden. Gates on this head: black/isort/flake8, brand and harness gates, config baseline regenerated, mypy --platform linux clean, 105 new tests and 1770 across the compaction consumer suites, six mutations red then restored.

Bundle Size Gate on the previous head: the all chunk is 7.0 KB over its 11620 KB budget. This PR changes no file under website/ (the gate ran because the diff also touches scripts/), and that budget entry is unchanged on main, so the overrun is main's own frontend growth (today's Zoom-connector and docx-renderer commits), not this PR's. Left for a maintainer to refresh in website/scripts/check-bundle-size.mjs; not bumped here to keep a backend PR out of the frontend budget file.

@jingchaodev
jingchaodev force-pushed the feat/compaction-methods branch from bb82582 to 2f7e3d2 Compare September 16, 2026 23:39
@jingchaodev

Copy link
Copy Markdown
Contributor Author

GPT, round 19 (judged head b0f4177b3): cancellation leaves a durable seed for a rotation that never occurred (compaction_seed.py:165)

  • span=4e32029bffcf -- fixed at 01093be32.

Right: a cancel between the seed save and the recycle left a saved seed with no rotation behind it.
The seed write, the restart and the verdict bookkeeping now run as one transaction under async_utils.run_to_completion (moved verbatim from chat_utils, which keeps the name). A cancel is deferred to the end of the transaction and then re-raised, never dropped, and close_all gathers the task before it tears the sessions down.
The seed save itself is a guarded save_slot_off_loop (best_effort=False, both identity pins), so a tab close waits for it before it gives the name away.
Pin: test_cancellation_finishes_seed_save_and_rotation_before_releasing cancels the compaction while the seed save is held open: the save finishes, the old session is recycled, the verdict is armed, and only then does CancelledError surface.

@jingchaodev

Copy link
Copy Markdown
Contributor Author

Opus, round 19 (judged head b0f4177b3): soft asks no surface question (session_compaction.py:851)

  • span=a54056c0dbbc -- fixed at 01093be32.

Right: only the dashboard replay re-seeds a rotated session, so a soft recycle of a cron, hook, sub-agent or non-dashboard channel session came back with no turns.
Both rotations now ask the seed writer's supports(key) before the projection. With no writer, or a key the writer holds no transcript for (a channel-born key, a key with no tab), the rotation is unavailable and the walk hands to native.
Slack keeps native too: its own fresh-session bootstrap is a model call, which soft promises not to spend. The help says "soft and shake run in dashboard tabs only".
Pins: test_soft_without_a_seed_writer_hands_straight_to_native and test_soft_on_a_surface_the_writer_does_not_support_hands_straight_to_native.

@jingchaodev

Copy link
Copy Markdown
Contributor Author

Design, round 19 (judged head b0f4177b3)

  • span=547b88e9c36f -- fixed at 01093be32.

Taken: an insufficient shake now hands to native, the same as an unavailable one. rotation_ladder(m) is the configured rotation alone, so no weaker rotation ever runs in place of a stronger one, and the history shake was chosen to keep is never dropped undigested.
Pin: test_an_insufficient_shake_hands_straight_to_native (the walk logs shake then native, and the digest is never written).

@jingchaodev

Copy link
Copy Markdown
Contributor Author

First Principles, round 19 (judged head b0f4177b3)

  • span=f637057139b3 -- fixed at 01093be32.

The wrapper is gone. build_seed is the one function: it returns the seed with the flag the writer reads ((seed, split_dropped)), the writer is its one caller in src/, and the tests call it directly.

@jingchaodev

Copy link
Copy Markdown
Contributor Author

First Principles, round 19 (judged head b0f4177b3)

  • span=f1e90cdaef1c -- fixed at 01093be32.

The title prop is deleted: website/src/components/settings.tsx is byte-identical to main. The option labels are now short enough that the closed select shows them whole (see the Settings screenshots), so the prop has nothing left to do.

@jingchaodev

Copy link
Copy Markdown
Contributor Author

First Principles, round 19 (judged head b0f4177b3)

  • span=c078a5a8ce3c -- fixed at 01093be32.

The rider is gone. main has since fixed the stale route itself, so after the rebase the regenerated settings registry adds only chat.compaction-method and touches no other entry.

@jingchaodev

Copy link
Copy Markdown
Contributor Author

UX, round 19 (judged head b0f4177b3)

  • span=e5e87e88f467 -- needs-a-decision (maintainers).

Agreed that no first-time reader has seen "Soft", "Shake" or "Session rotated (soft)". A fork contributor cannot push this branch to the repository for the blind read, so the decision stays with a maintainer: push it for that read, or accept the labels as shipped. Same question as rounds 17 and 18.

@jingchaodev

Copy link
Copy Markdown
Contributor Author

UX, round 19 (judged head b0f4177b3)

  • span=0267061e663a -- fixed at 01093be32.

The labels are short now, so the closed trigger shows them whole: "Native (Default) — summarize in place", "Soft — rotate session, keep recent turns", "Shake — rotate session, digest earlier turns". The description says that Soft and Shake call no model. Both Settings screenshots in the body are recaptured on this head.

@jingchaodev

Copy link
Copy Markdown
Contributor Author

UX, round 19 (judged head b0f4177b3)

  • span=5d69c48eeda1 -- fixed at 01093be32.

One term now: the Soft and Shake labels say "rotate session", the same verb as the notice's "Session rotated (soft)", so a user can map the notice to the setting by the word, not only by "(soft)".

@jingchaodev

Copy link
Copy Markdown
Contributor Author

UX, round 19 (judged head b0f4177b3)

  • span=154263142bcb -- fixed at 01093be32.

The description is rewritten and ends with a period: "What runs at the Auto-Compact Threshold. Soft and Shake call no model and run in dashboard chats only; anywhere they cannot run, Native runs." The hand-off chain is gone with it, because a rotation now hands only to Native.

@jingchaodev

Copy link
Copy Markdown
Contributor Author

Round 19: b0f4177b3 -> 01093be32, rebased onto main at 64ece1a1b (it merges cleanly with today's tip), one commit.

This answers the 2026-09-30 triage (issuecomment-5909842366) and the 2026-10-05 rebase request (issuecomment-5998839384). The four decisions are made, so needs-author-decision can come off.

Question Decision
GPT F1: a quota-cut transcript shake hands to native. A read the 500-row quota cut writes no seed.
Opus: which surfaces may run soft Dashboard tabs only. Both rotations ask the seed writer's supports(key); every other key runs native.
GPT F2: a cancel after the seed save The seed write, the restart and the verdict bookkeeping are one run_to_completion transaction.
Rebase: honour the sub-agent restart hold Yes. A rotation restarts the session the way every compaction restart on main does: _await_cotenants, then _restart_held, which also hands queued turns to the successor.
  • The rebase: main's context.py split (refactor: compose context assembly from focused owners #15998) moved the replay code, so the seed admission now lives in the replay owner (context_assembly/replay.py). The rotation also takes main's Stop guards (fix(compaction): honor a Stop during the uncompactable recycle #18926): it records itself as the turn owner, a Stop during the sub-agent wait or the seed write settles cancelled with no restart, and the permit is released only when this task still owns it. That release clears turn_owner, as fix(session): decline a Stop only once the compaction holds the session #18935 requires of every holder.
  • main's mid-turn notice (fix(chat): say when a turn crosses the compaction threshold #19775): it says the chat "will be summarized when this turn ends", and a rotation writes no summary. With soft or shake configured, the notice row records the method and the card says "will be compacted". With native the row and its words are main's.
  • Found before this push, all fixed: a second shake could drop the first digest; a rotation's own notice spent the successor's tail budget; the seed save was not a write a tab close waits for; the hold could record inputs the projection never read; a reset during the seed write could arm a verdict on the wrong session; a rotation waiting for sub-agents said a compaction had failed; a config whose session section cannot be read failed a turn in _run_chat that main runs. Each has a pinning test that fails with its guard removed.
  • Default unchanged: with native, dispatch is main's and a transcript with no seed row replays as on main (TestWithoutASeedNothingChanges; a local verifier also compared 600 random native transcripts against main's replay and found no difference).
  • Still with maintainers: the UX blind read (e5e87e88f467) needs the branch pushed in-repo. The diff is 65 files, +6,031/-173, all behind the opt-in key.
  • Local review of this head: no Critical, High or Medium. One Low is left as is: the notice names the method the turn read when it started, so changing the method during a turn can show "summarized" while a rotation runs. Only the words are wrong; the compaction runs the configured method.
  • Gates on this head: the static gates (black, isort, flake8, comment-history, brand, harness parity, feature-map, docs-lint, flake-pattern ratchet), mypy --platform linux clean on 2,344 files, gen:ui --check, tsc, i18n:check, eslint on the PR's 11 frontend files, 399 vitest tests in 22 related test files plus 944 i18n tests, and 5,192 backend tests across the compaction, context and chat-runner suites. The 241 tests this PR adds or changes pass 20 runs in one process, 10 at 4 workers and one shuffled order (seed 22387).

@bolichen97

Copy link
Copy Markdown
Contributor

Thanks for this PR. It now conflicts with main. Could you rebase onto the latest main and resolve the conflicts? We will review it again once it is rebased and CI is green.

@jingchaodev

Copy link
Copy Markdown
Contributor Author

resolution: removed -- context_budget.py and its parity test are deleted, so the owners in context_assembly hold the only copies

  • span=3cb3a763d7c2

fixed in 8f7dd9c8460d: src/kiro_crew/context_budget.py and test/test_context_budget_shared.py are deleted. The coordinator imports replay_budget_chars from context_assembly/replay.py and startup_context_chars() from context_assembly/budget.py; no budget figure has a second copy.
Items 8 and 9 went with it: rotation_ladder is gone (the coordinator reads the one configured method), and the compaction counter carries no new method label, so a default config's series is main's.

@jingchaodev

Copy link
Copy Markdown
Contributor Author

resolution: narrowed -- only a dashboard tab's own session key may rotate, and shake with its digest rows is removed

  • span=4e32029bffcf

fixed in 8f7dd9c8460d: _seed_slot in dashboard/compaction_seed.py answers a key only when slot_ownership.own_session_key(slot) == key. cron:<id>, cron:<id>:<run>, workflow, hook and sub-agent keys keep native even while a tab shows them; channel keys are refused before any lookup.
shake and its seed rows are removed, so no rotation writes a digest that a cron fire's recall could skip. Pinned by test/test_compaction_seed_writer.py::TestSupports::test_a_tab_linked_to_an_external_session_is_unsupported (cron job tab, cron run tab, workflow tab).

@jingchaodev

jingchaodev commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor Author

Round 20: 01093be32 -> 8f7dd9c8460d, rebased onto main at d80dd051f437, one commit.

@bolichen97 thanks, it is rebased and the conflicts are resolved. The fork CI runs need a maintainer to approve them.

This round narrows the PR: shake is removed, and soft is the one rotation. The code and tests went from +6031/-173 to about +3000/-105, plus seven committed screenshots.

Lane on 01093be32 Answer
First Principles BLOCK (context_budget.py copies the budget constants) deleted; disposition
GPT 6.1 BLOCK (cron-linked tabs admit rotations) only a tab's own session key rotates; disposition
UX BLOCK (no screenshot of the waiting notice) temp-screenshots/compaction-methods/rotation-waiting-subagents.png, shown in the description
Design concern (a revert leaves digest rows drawn as bubbles) gone with shake: this PR writes no new row kind

A local review of the new head found five more defects, all fixed with tests:

  • With soft set, a session that can never rotate (a Claude backend, a cron-linked tab) now keeps main's replay and mid-turn wording.
  • A rotation that frees too little gets main's failure cooldown. The hold that kept the key on native until a setting changed is removed, because the first reading includes the new session's first turn.
  • A forced Stop during the sub-agent wait names the rotation in its notice.
  • A raise after the new session started reports failed instead of running native on the replaced session.
  • The waiting notices no longer draw a raw "⏸" beside the card icon. This also fixes main's own waiting notice.

The question left for a maintainer is the one from rounds 17 to 19: no first-time reader has seen "Soft" or "Session rotated (soft)", and a fork contributor cannot push the branch for that blind read. Please either push it for the read or accept the labels. With that, the author decisions are made, so needs-author-decision can come off.

@jingchaodev

Copy link
Copy Markdown
Contributor Author

Rebased onto main at b3bf88b8814a to clear the merge conflict. Still one commit: 9dbaf773be03.

How each conflict was resolved:

One more fix from main's new style tests: the French compaction_method_desc now has U+202F before its semicolon, as frStyle.test.ts requires.

Heads-up: tsc -p tsconfig.app.json fails on main itself at website/src/pages/chat/AssistantMessage.tsx:683. GitFork is used there but not imported. This PR does not touch that file.

The fork CI runs for this head need a maintainer's approval again.

@KiroCrewCaptain

KiroCrewCaptain commented Nov 12, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider thinks the change is probably fine but estimates a 20% chance that this change introduces a defect, above the 12% limit for approving on its own.

Adds the opt-in setting session.compaction_method, which defaults to native. With the default, behaviour matches main: try_rotation returns None immediately (and always for idle compactions), so the native dispatch that follows is main's, plus one INFO log line. The replay output is identical too, because the new skip and clip switches only turn on when the turn's _rotation_method is set. The new required method keyword on the compact callback is supplied at both coordinator call sites, the only registrant in src (the dashboard callback) defaults it to native, and the exact-argument test fakes were updated. soft reuses the existing restart path (_restart_held). It holds the turn permit, waits for sub-agents and re-checks that the session wasn't replaced. Its finally block releases the permit only if no Stop took it and clears state.rotating. A Stop settles as cancelled, and a raise after the successor started reports failed without running native. It sets pending_verdict, so a weak rotation arms the cooldown. Only a tab's own session key may rotate, checked with own_session_key: channel, cron, workflow and linked sessions are refused, which addresses the e

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit 432bf5ba67 · 3132 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@jingchaodev

Copy link
Copy Markdown
Contributor Author

Rebased onto main at db8101f545ca to clear the merge conflict. Still one commit: 328200142119.

How the conflict was resolved:

  • src/kiro_crew/docs/ui-index.generated.json: took main's copy, then ran npm run gen:ui.

@jingchaodev

Copy link
Copy Markdown
Contributor Author

Rebased onto main at 176820cd7a51 to clear the merge conflict. Still one commit: bd962cdc2be5.

How the conflict was resolved:

  • src/kiro_crew/docs/ui-index.generated.json: took main's copy, then ran npm run gen:ui.

@jingchaodev

Copy link
Copy Markdown
Contributor Author

Rebased onto main at 16e11a18703b to clear the merge conflict. Still one commit: 613ea348503b.

How the conflict was resolved:

  • src/kiro_crew/docs/ui-index.generated.json: took main's copy, then ran npm run gen:ui.

@jingchaodev

Copy link
Copy Markdown
Contributor Author

Rebased onto main at 02e103f1443b to clear the merge conflict. Still one commit: de5fc4bf3a75.

How the conflict was resolved:

  • src/kiro_crew/docs/ui-index.generated.json: took main's copy, then ran npm run gen:ui.

@jingchaodev

Copy link
Copy Markdown
Contributor Author

Rebased onto main at 0f3e09c97f75 to clear the merge conflict. Still one commit: d49ebf9796d2.

How the conflict was resolved:

  • src/kiro_crew/docs/ui-index.generated.json: took main's copy, then ran npm run gen:ui.

@jingchaodev

Copy link
Copy Markdown
Contributor Author

Rebased onto main at 5cf7704fee26 to clear the merge conflict. Still one commit: c239facab7e5.

How the conflict was resolved:

  • src/kiro_crew/docs/ui-index.generated.json: took main's copy, then ran npm run gen:ui.

@jingchaodev

Copy link
Copy Markdown
Contributor Author

Rebased onto main at b81cf5a3acc0 to clear the merge conflict. Still one commit: 03f21f6c96ff.

How the conflict was resolved:

  • src/kiro_crew/docs/ui-index.generated.json: took main's copy, then ran npm run gen:ui.

@jingchaodev

Copy link
Copy Markdown
Contributor Author

Rebased onto main at fdf7cbc2ec83 to clear the merge conflict. Still one commit: 68a48494ea2d.

How each conflict was resolved:

@jingchaodev

Copy link
Copy Markdown
Contributor Author

Rebased onto main at 6f4a30b93ff2 to clear the merge conflict. Still one commit: 432bf5ba67d0.

How the conflict was resolved:

  • src/kiro_crew/docs/ui-index.generated.json: took main's copy, then ran npm run gen:ui.

@jingchaodev

Copy link
Copy Markdown
Contributor Author

Rebased onto main at e1d7ff2428d3 to clear the merge conflict. Still one commit: 6fd54f675538.

How the conflict was resolved:

At the auto-compact threshold the coordinator has one move: kiro-cli's
/compact, a single model call over the whole window that took 2m12s at
99% of a 1M-token window. session.compaction_method chooses what runs
there: native (the default, that same /compact, so nothing changes for
a config that never sets it) or soft. Settings > Chat > Advanced carries
a Compaction Method select beside the Auto-Compact Threshold, and the
config PATCH allowlist accepts the key as an enum. An unknown stored
name loads as native.

soft is a rotation and makes no model call. The coordinator restarts
the session the way every compaction restart does: it holds the turn
permit, waits for sub-agents that share the process, then _restart_held
starts the successor, hands it the turns queued behind the hold and
recycles the old session. The successor's first turn replays the
transcript tail through build_session_replay, under the
replay_budget_chars figure that context_assembly.replay owns.

A rotation runs only when the dashboard seed writer supports the key
and its projection clears the threshold by the margin /compact must
reach. Otherwise native runs. An ineffective rotation holds the key on
native until the method, window or threshold its projection read
changes. The rotation notices say the transcript on screen is intact
and the agent's memory of earlier turns is gone. The replay leaves those
notices out, so they spend none of the tail. With soft configured, the
mid-turn notice says the chat "will be compacted" instead of
"summarized", and the replay clips an oversized newest row.
@jingchaodev

Copy link
Copy Markdown
Contributor Author

Rebased onto main at 102146851ca1 to clear the merge conflict. Still one commit: 44bfb624a0a2.

How the conflict was resolved:

Two rules that reached main after the last rebase also apply to this PR:

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor) needs-author-decision PR blocked on author input readiness: action required A blocking check or review needs attention

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants