Skip to content

fix(dashboard): skip the context snapshot write when its read failed before restore - #18277

Merged
bolichen97 merged 1 commit into
mainfrom
fix/context-snapshot-read-failure-skip-write
Oct 9, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/context-snapshot-read-failure-skip-write

Conversation

@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Problem / Motivation

_persist_context_snapshots merges context_snapshots.json into memory before it writes. In ensure_context_snapshots_loaded, a read that failed with anything other than FileNotFoundError was swallowed to an empty map, and the loaded flag was latched True. The next flush then replaced the file with only the live readings. Every other tab's saved context reading was lost, and nothing retried the read.

The common trigger is a Windows sharing violation (WinError 32) while another handle holds the file. PR #15735 (and its backport #17233) already skips the open_slots.json write for the same kind of seed read failure; this sidecar had no such guard.

Why it matters

After a restart, a reopened tab shows its last context reading from this file. One transient read failure in the boot window erased those readings for every tab the restore had yet to rebuild. After restore it erased the reading of every open tab that had not produced a fresh reading in this process. A read failure on the slot-detail path also latched an empty map for the whole process lifetime, so no reopened tab showed its reading until restart.

Not a goal

  • No change to the prune rule, the restore latch, or the write path.
  • No retry loop inside one flush. The 5 s flush cadence is the retry.
  • No change to open_slots.json handling.

What changed

  • ensure_context_snapshots_loaded returns bool. On an OSError read (content unknown, possibly intact) it returns False and leaves the loaded flag unset, so the next call retries. Content that was read but does not parse (truncated or non-object JSON) is still merged as empty and latched: it holds nothing recoverable, and skipping there would switch persistence off for good on a surface that never runs a restore.
  • _persist_context_snapshots skips its write when the load returns False and keeps the map dirty. This applies before and after restore. Before restore it protects the tabs the restore has yet to rebuild; after restore it protects open tabs whose reading is still only on disk. A legacy owner override that returns None is treated as loaded.
  • DashboardState.ensure_context_snapshots_loaded passes the result through.
  • test/windows_sim.py: new read_text_sharing_violation, the Path.read_text counterpart of read_sharing_violation (patching builtins.open does not reach read_text).
  • Spec: docs/system-specs/modules/learn-cron-dashboard.md, "Context meter survives a reopen", states the read-failure rule.

Why the split between OSError and parse errors instead of skipping on any failure: the snapshot writer is atomic (temp file plus rename), so a parse error means the content is genuinely corrupt and no reader can recover it. A transient OSError means the file may be intact, which is the only case where a write destroys data.

Backwards compatibility

No file format change. Behaviour changes only when the file exists and cannot be read: the write is deferred to the next flush instead of replacing the file. A persistent OSError on read keeps the map dirty and logs at debug level on each flush; the previous behaviour in that case was to overwrite the file, which is what this PR prevents.

Tests

New tests:

  • test/test_open_slots_persistence.py::test_context_snapshot_write_skipped_when_pre_restore_read_fails: a pre-restore flush after a failing read leaves the file byte-identical, the map stays dirty and unlatched, and the next flush writes the union.
  • test/test_context_bar_reopen.py::test_unreadable_snapshot_file_is_not_replaced_after_restore: same after restore; the disk-only reading of an open tab survives.
  • test/test_context_bar_reopen.py::test_slot_detail_retries_a_transiently_unreadable_snapshot_file: a failed first read from the slot-detail handler is retried on the next request.
  • test/test_context_bar_reopen.py::test_corrupt_snapshot_file_is_repaired_not_retried_forever: a truncated file is still repaired by the next write.

Without the fix, the first three fail (file replaced; KeyError: 'context_pct') and the corrupt-file test passes, pinning that its behaviour is unchanged. With the fix all pass.

pytest test/test_context_bar_reopen.py test/test_open_slots_persistence.py test/test_dashboard_chat_handlers_coverage.py test/test_flake_pattern_ratchet.py
287 passed

Lint: flake8, isort and mypy clean on the changed files; scripts/check_black_formatting.py passes (test/windows_sim.py is on the existing black baseline, and the new helper follows that file's current style).

Manual verification

None beyond the tests. The Windows sharing violation is simulated in-process, the same way the existing windows_sim helpers do it.

Related Issues

Follow-up to #15735 and #17233 (backport). Same defect class as #15719. A backport to the 0.8.0 release branch is needed for 0.8.1 and will be a separate PR.

Pattern harvest

Rule candidate: a read that merges an on-disk sidecar before a full-file rewrite must not treat a transient OSError as "empty and loaded"; it returns an "unknown" result and the caller skips the write. Parse errors on an atomically written file may be treated as empty. Applies to every read-merge-rewrite sidecar in dashboard_persistence.py.

…before restore

_persist_context_snapshots merges context_snapshots.json into memory
before it writes. A read that failed with an OSError (a Windows sharing
violation) was swallowed to an empty map and latched as loaded, so the
next flush replaced the file with only the live readings and destroyed
every other tab's saved context reading, with no retry.

ensure_context_snapshots_loaded now returns False on an OSError read and
leaves the loaded flag unset. The flush skips its write and keeps the map
dirty, so the next pass retries against the intact file. This holds
before and after the boot restore: after restore an open tab with no
fresh reading still has its reading only on disk. Content that was read
but does not parse is still merged as empty and latched, so the next
write repairs it instead of switching persistence off for good.

Follow-up to #15735 and #17233, which apply the same rule to the
open_slots.json seed read.
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 8, 2026
@github-actions

github-actions Bot commented Oct 8, 2026

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

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

@github-actions

github-actions Bot commented Oct 8, 2026

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Check that read_text() raising UnicodeDecodeError on a non-UTF-8 file now escapes both except arms. Before, the broad except Exception caught it, so a corrupt file should still be repaired.

[DESIGN-REVIEWED] f11e51e

Description read

[DESCRIPTION-READ] 8944e4f405f0c589bf3cdd8b2b3e60a8728d9f39c72f3285271500a1990d7628

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 Oct 8, 2026

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

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

Check one trade before merge: if the snapshot file can never be read (e.g. a permanent permission error), snapshot writes stop and the only trace is a debug log on every flush.

What this change ships

Inventory (6 items) — 6 justified

Intent: keep every tab's saved context reading when the snapshot file briefly can't be read, e.g. a Windows sharing violation. This is a FIX.

  1. A flush whose snapshot read hit an OSError now skips its write instead of replacing the file. This applies before and after restore — justified
  2. A failed read no longer counts as "loaded", so the next flush or slot-detail request reads the file again — justified
  3. A file that was read but doesn't parse is still treated as empty and repaired by the next write; tests pin that this behaviour is unchanged — justified
  4. ensure_context_snapshots_loaded now returns a bool. It has one consumer, _persist_context_snapshots, and state.py just passes it through — justified
  5. New test helper read_text_sharing_violation in test/windows_sim.py. The existing read_sharing_violation only patches read_bytes, and this code reads with read_text — justified
  6. The spec paragraph "Context meter survives a reopen" now states the read-failure rule — justified

[FIRST-PRINCIPLES-REVIEWED] f11e51e

Description read

[DESCRIPTION-READ] b535685405f59dbdb2fef76c9a3970c83bd3af39a8cb22dc30cda8e1cef8710f

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 Oct 8, 2026

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] f11e51e

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

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

@github-actions

github-actions Bot commented Oct 8, 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 f11e51ee391559c4d62670e80c896f2a381a96da. 1 of 1 blocking finding(s) are security-class and were withheld from adjudication, so the blocking verdict stands.

This comment is updated in place on each push.

BLOCKING -- src/kiro_crew/dashboard/dashboard_persistence.py:344 -- A decoding error terminates periodic autosaves

except OSError:
Invalid UTF-8 in context_snapshots.json plus a dirty context reading -> read_text() raises uncaught UnicodeDecodeError -> _persist_context_snapshots propagates through _flush_dirty_slots into _flush_loop, terminating subsequent periodic transcript and open-tab autosaves.
Anchor: residual/guard-removal
Fix: Catch UnicodeError around read_text() and treat it as corrupt content (text = None), retaining the retry behavior for OSError.

[BLOCK-MERGE] f11e51e
[GPT-REVIEWED] f11e51e

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

F1 (fenced): the harm is silent and lasts until someone fixes the file by hand, and this PR removed the guard that used to catch it.

  • Conditions confirmed. dashboard_persistence.py:341-344 catches only FileNotFoundError and OSError around read_text(), so a UnicodeDecodeError escapes. The old except Exception caught it; this PR removed that. The error escapes _persist_context_snapshots (:400) and _flush_dirty_slots (:186-189) uncaught. In _flush_loop (:90-91) nothing wraps run_in_executor, so the loop ends and periodic transcript and open-tab autosaves stop.

  • Rarity and recovery. The app's own writer can't produce bad bytes: the codec is stdlib json (state.py:301, ensure_ascii, so ASCII only). Only outside corruption reaches this. But there is no recovery: the write that would repair the file (:432) is never reached. So every restart dies again on the first dirty context reading, nothing above debug level reports it, and crash-time transcript loss returns.

  • Fix cost. Trivial: add UnicodeError to the existing parse-failure path.

    [ADJUDICATION] f11e51e total=0 uphold=0 downgrade=0
    [GPT-ADJUDICATED] f11e51e

    [ADJUDICATION-FENCED] f11e51e fenced=1 flagged=0
    UPHOLD-FENCED F1 src/kiro_crew/dashboard/dashboard_persistence.py:344 -- Only outside corruption triggers it, but this PR removed the guard that caught it, the crashed flush never rewrites the file, and so every restart silently loses periodic transcript autosaves until someone repairs the file by hand.
    [GPT-ADJUDICATED-FENCED] f11e51e

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

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 8, 2026
@KiroCrewCaptain
KiroCrewCaptain marked this pull request as ready for review October 9, 2026 00:14
@KiroCrewCaptain
KiroCrewCaptain requested a review from a team as a code owner October 9, 2026 00:14
@bolichen97
bolichen97 merged commit 5cec747 into main Oct 9, 2026
100 of 103 checks passed
@bolichen97
bolichen97 deleted the fix/context-snapshot-read-failure-skip-write branch October 9, 2026 05:44
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Oct 9, 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.

2 participants