Skip to content

perf(startup): fold the session tree in the background, claims fenced until it lands - #34901

Closed
chenmingwei23 wants to merge 5 commits into
mainfrom
fix/34847-session-tree-background-seed
Closed

chenmingwei23 wants to merge 5 commits into
mainfrom
fix/34847-session-tree-background-seed

Conversation

@chenmingwei23

Copy link
Copy Markdown
Contributor

Refs #34847

Stacks on #34866 and #34852 and must merge after them. The branch is based on the #34866 head, so the diff shown here includes their commits until they land; I will rebase onto main once after they merge.

Problem / Motivation

Goal: A restarted gateway restores its tabs without waiting for the crew-log session-tree fold, while creator claims stay refused until the fold lands.

The restore folds the whole crew log synchronously inside the first restored tab that carries created_by, so one tab's read pays the full fold on the boot path (21 s of 31.7 s in a profile of the real prefetch on a home with about 100 tabs). No tab needs that fold to be built; only the creator check needs it.

Why it matters

Every restart of a gateway with many tabs pays the fold before the socket-adjacent restore can finish. Anyone with a large home waits for it on each restart, and the wait grows with the crew log.

Not a goal

What changed (motivation -> approach -> change)

Symptom: the restore blocks on ensure_seeded() in the first prefetch that sees a created_by. Cause: the restore compares each claim with the creation records, and an unfolded tree confirms nothing, so the restore folded first. Change:

  • dashboard/session_tree_boot.py (new): start_background_seed folds the tree off the loop as a tracked task, then confirm_creators upgrades each restored slot whose saved claim the creation records now back. It applies the same test the restore applies, so a claim the records do not back stays refused.
  • dashboard/server.py: start that task right before the restore.
  • slot_builders.py: drop the two blocking _seed_session_tree calls (call sites only) and the facade re-export in chat_persistence.py.
  • chat_turn/crew_log_attribution.py: a first turn that already awaits the fold settles its own slot's claim, so it cannot race the boot sweep and lose the parent edge on its new log.

Fail closed: before the fold lands, an unfolded tree answers "no creator", so a restored claim is UNVERIFIED_CREATOR (non-empty, matches no caller) and session-control reads (creator_of, revive, status) refuse. A failed fold leaves claims refused until the next restart.

Backwards compatibility

Compatible: nothing accepted today is newly refused after the fold; claims are refused for the seconds before it, and a claim the creation records back is accepted again once it lands.

Reader: session_control_parts/session_revive.py:_creation_parent -- session_revive -- unseeded tree answers "" so the ownership check refuses (unchanged), test_a_boot_restore_keeps_only_the_creator_the_spawn_records.
Reader: slot_persistence/metadata_codec.py:_read_created_by -- restore -- stores UNVERIFIED_CREATOR while unfolded, then confirm_creators restores the claim, test_the_boot_seed_runs_in_the_background_and_confirms_after_the_fold.
Reader: chat_turn/crew_log_attribution.py:_crew_log_lineage -- chat turn -- awaits the fold and settles the slot's claim first, test_a_turn_that_waits_for_the_fold_settles_its_own_claim.

Tests

  • test_a_boot_restore_keeps_only_the_creator_the_spawn_records (both restore drivers): the restore leaves the tree unfolded and every claim refused; after the fold, only the backed claim is confirmed.
  • test_the_boot_seed_runs_in_the_background_and_confirms_after_the_fold: the loop is free while the fold is held in flight, the claim is refused, then passes once the fold lands.
  • test_a_turn_that_waits_for_the_fold_settles_its_own_claim.
  • The first test fails on the base (the restore folded inline and confirmed the claim).

Proof: not provable -- other: reverting the production hunks removes the new module the tests import, so the mutated run fails at collection; the restore test was run red against the base separately.

Manual verification

Measured on an isolated gateway bound to a loopback ephemeral port, with a temporary data home holding 100 synthetic tabs (90 with a creator claim) and a crew log of 60,000 session logs; the home and the process were removed afterwards. Method: start the service, open the dashboard with the test-mode flag, wait for the ready line, send one message to the newest tab, and record seconds from process start. 3 runs each, alternating, base = #34866 head vs this head.

service start to socket bound to first message accepted to first turn progress
base 8.2, 8.0, 8.1 s 8.2, 8.0, 8.2 s 17.0, 16.6, 16.7 s
this PR 5.2, 5.1, 5.2 s 5.3, 5.1, 5.3 s 17.2, 16.8, 17.2 s

Result: the boot path is about 3 s shorter. The first turn's progress is unchanged here because the cold fold on this synthetic home is only about 1.5 s and the turn is held by something else (memory preparation, covered by #34866 and #34852). A real home's fold was 21 s in the issue's profile, so a larger gain is expected there, but I did not measure it. A turn with no sandbox backend ends in an error message, which is the "progress" signal used.

Screenshots / video

N/A -- no user-visible UI change.

Related Issues

Refs #34847

Sibling sweep

Swept: git grep -n "_seed_session_tree|ensure_seeded" -- src/
Sibling: src/kiro_crew/dashboard/state_parts/slots_frame.py:364 -- not affected -- already seeds on the maintenance pool, not the boot path
Sibling: src/kiro_crew/dashboard/chat_turn/crew_log_attribution.py:187 -- changed here -- awaits the fold and now settles the claim
Sibling: src/kiro_crew/dashboard/session_memory.py:731 -- not affected -- runs on a page read, not the boot path

Pattern harvest

Not generalizable: a one-off blocking read on the restore path; the fail-closed fallback already existed as UNVERIFIED_CREATOR.

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

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license.

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

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision f3e74cfa678698f139f74b97ad3de8d8e5579b5a touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — 🔴 changes requested (blocking)

GPT 6.1 found at least one blocking issue that must be resolved before merging f3e74cfa678698f139f74b97ad3de8d8e5579b5a. Adjudication upheld 1 of 1 blocking finding(s); those must be resolved before merging.

This comment is updated in place on each push.

BLOCKING -- src/kiro_crew/dashboard/server.py:1618 -- Pending creator verification bypasses quotas and loses approval cascades

start_background_seed(state)
Trigger: After restore and memory preparation finish but before the fold lands, a root parent’s turn does not await seeding because its _created_by is empty. With 50 restored children, /api/session-control/create → create_session → creator_slot_count excludes those children. A dashboard Trust change → apply_approval_mode → plan_descendant_postures also excludes them.
Outcome: Creation admits a 51st child despite the per-creator ceiling. Trust reports success without updating inherited children; later confirm_creator restores ownership but never replays the cascade, leaving those workers asking for approvals.
Anchor: defect
Fix: Await folding and claim confirmation before creator-quota decisions, and defer or replay approval cascades made while verification is pending.

[BLOCK-MERGE] f3e74cf
[GPT-REVIEWED] f3e74cf

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

F1 — UPHOLD. I rated this HIGH. The failure is silent, and the PR introduces it: before this change the restore waited for the fold, so _created_by was already correct by the time anything read it.

  • Conditions: metadata_codec.py:593-595 restores every claim the tree can't confirm yet as UNVERIFIED_CREATOR with _creator_pending_fold. server.py:1618 now starts the fold in the background, so the restore no longer waits for it. During that window, approval_inheritance.py:116-119 builds by_creator from _created_by, so fenced children are missing from the walk. The per-creator quota counts _created_by the same way (slot_registry.py:1325-1341). session_tree_boot.py:23-45 (confirm_creator) restores ownership but never replays a cascade that happened in between.

  • Consequence: The finding describes the raise direction. The lowering direction is the worse one: a parent's Trust lowered during the window leaves its inherited children at the higher, auto-approving posture. The change reports success, and nothing recovers it later.

  • Cost of the real fix: modest. Wait for the existing seed task before the quota check and the posture-cascade path, or re-run plan_descendant_postures from confirm_creators. Both reuse mechanisms that already exist.

    [ADJUDICATION] f3e74cf total=1 uphold=1 downgrade=0
    UPHOLD F1 src/kiro_crew/dashboard/server.py:1618 reason=harm-warrants-remedy
    [GPT-ADJUDICATED] f3e74cf

False positive or not applicable? A repository writer can comment:
/ai-review override gpt f3e74cfa678698f139f74b97ad3de8d8e5579b5a false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of f3e74cfa678698f139f74b97ad3de8d8e5579b5a — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

No design-level concerns: every reader of the unfolded tree fails closed, and the sweep after the restore catches slots published after the fold landed.

Notes

  • _seed_session_tree is now dead code that still calls ensure_seeded on the restore path. A later caller could bring back the 21 s block, so delete it in a follow-up rather than leave it as a trap.
  • A fold that fails keeps every restored claim fenced until the next restart. The fix is one log line at warning instead of debug in seed_and_confirm, so an operator can see why creator-gated controls refuse.

[DESIGN-REVIEWED] f3e74cf

Description read

[DESCRIPTION-READ] d80aed49c714183217b4df55a5475dc7a1745eb91fde122f992275bc9b51e355

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 Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of f3e74cfa678698f139f74b97ad3de8d8e5579b5a — 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 does not.

First-Principles-Verdict: PASS

Nothing blocks. The PR removes a measured wait from the boot path, claims stay fenced until the fold lands, and the one leftover is dead code.

Notes

  • Item 6 — zero consumers: "Changing _seed_session_tree; it is left untouched and is now unused." git grep _seed_session_tree -- src test finds 1 hit, the definition at slot_persistence/restore_inputs.py:318, with no callers. Subtraction: delete _seed_session_tree instead of keeping an unused second fold entry point.
  • Item 2 — not a full duplicate: state_parts/slots_frame.py:_request_lineage_seed already folds the tree in the background on the maintenance pool, but it has no completion hook, so seed_and_confirm is a different capability. Subtraction: none that is smaller.

What this change ships

Inventory (7 items) — 6 justified

Intent: a restarted gateway restores its tabs without waiting for the crew-log fold, and creator claims stay refused until the fold lands. This is a FIX (perf).

  1. Restoring tabs no longer waits for the session-tree fold — justified
  2. The fold now runs as a tracked background task at boot, then confirms the backed claims — justified
  3. Restored creator claims are refused for the seconds before the fold lands — justified
  4. A second confirm sweep runs after the restore, for slots published after the first sweep — justified
  5. A first turn that awaits the fold confirms its own slot's claim — justified
  6. _seed_session_tree is kept with no callers — zero consumers, dead code left behind
  7. A new per-slot flag records "waiting on the fold" so a History reopen stays fenced — justified

[FIRST-PRINCIPLES-REVIEWED] f3e74cf

Description read

[DESCRIPTION-READ] 54a5abf120f45bdc5e72edaa90a5ac3abfb197b2703b2752461c338b05bed3ec

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] f3e74cf

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable f3e74cfa678698f139f74b97ad3de8d8e5579b5a false-positive: <reason, 20 to 500 characters>

@chenmingwei23
chenmingwei23 force-pushed the fix/34847-session-tree-background-seed branch from 2c82911 to 2d0801c Compare November 10, 2026 23:54
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Fixed in 2d0801c. The boot fold now upgrades only a slot the restore itself marked as waiting on the fold (_creator_pending_fold, set in _read_created_by), so a History reopen that is fenced with the same sentinel stays fenced; a test covers it. A confirm pass also runs once after the restore returns, for a slot published after the sweep. The flake-ratchet red is fixed by polling the event instead of parking a pool wait in the test.

@chenmingwei23
chenmingwei23 force-pushed the fix/34847-session-tree-background-seed branch from 2d0801c to e29f329 Compare November 11, 2026 00:08
@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 Nov 11, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/34847-session-tree-background-seed branch from e29f329 to d64be1f Compare November 11, 2026 01:32
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

GPT 6.1 finding at test/test_crew_log_session_tree_spawned.py:338 fixed in d64be1f: both waits in the background-seed test are now bounded with asyncio.wait_for (the start handshake and the seed task), and the release event is set in a finally so a failure before the handshake cannot leave the fold thread parked.

@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 Nov 11, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/34847-session-tree-background-seed branch from d64be1f to 8e78b58 Compare November 11, 2026 02:32
@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 Nov 11, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/34847-session-tree-background-seed branch from 8e78b58 to f3e74cf Compare November 11, 2026 03:14
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Backend Tests (3.12, 7) red on 8e78b58 was ours: test_state_parts_facade's slot-default inventory did not list the new _creator_pending_fold slot field. Fixed in f3e74cf by adding its default (False) to the inventory.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Closing this unmerged by maintainer decision. Moving the session-tree seed to the background opened a window where creator-based checks (creator quota, approval cascade, a lowered Trust setting) pass unchecked for children whose creator is not yet confirmed, and the measured gain did not move first-turn time (only the socket bind came earlier). The seed's own cost is being made delta-only by the watermark replay for #34846 (#34882), which removes the reason to move it off the boot path. The branch is kept for reference. Refs #34847

@github-actions github-actions Bot removed the readiness: checking Automated validation is still running label Nov 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant