Skip to content

fix: keep three stores intact when a rewrite cannot read them - #31998

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
fix/24607-strict-rewrite-reads
Nov 7, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
fix/24607-strict-rewrite-reads

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A store that exists but cannot be read for a moment (EACCES, EIO) is never overwritten with an empty one by the crewmate opt-in card, an app dependency install or uninstall, or a connection mint.

Each of these rewrites reads its file through a reader that answers {} on any OSError, then writes the whole file back. When the read fails for a moment, the write replaces every other entry with nothing, and because the write succeeds nothing reports the loss. These are the 11 sites #24607 lists in mate_tool_access.py, apps/dependency_ledger.py and connections/mint.py.

Why it matters

  • A lost tool-access.json drops every crewmate's opt-in record, so each one is asked the Preview opt-in again.
  • A lost dependency ledger makes every app's dependencies look user-installed. The next install re-seeds it with one owner, so a later uninstall can clean a dependency other apps still use.
  • A lost mint manifest leaves the mint spec files it named unreapable, and agent discovery still selects them.

Not a goal

What changed (motivation → approach → change)

These rewrites now leave an unreadable file exactly as it was. The cause is one shape, a lenient reader feeding a whole-file write, so each of the three readers gets a strict mode: only a missing file reads as empty and any other OSError propagates. Display reads keep the lenient answer.

Store Rewrite When the file cannot be read
~/.kiro/mates/tool-access.json reserve_offer raises, so the card is refused with the existing 503 opt_in_unrecorded
dependency ledger record_install records nothing, logs a warning and returns False, so the install or enable lists that dependency as failed
dependency ledger classify_and_clean_for_uninstall removes no dependency and logs a warning; the uninstall goes on
mint spec manifest _record_mint_spec returns False, which the mint already turns into a failed Connect

The ledger callers keep going instead of failing. resolve_dependencies is documented as non-blocking, so a dependency whose owner was not recorded is reported failed, not installed: the missing owner is shown instead of hidden, and a later install or enable records it. The uninstall's dependency step runs after the onUninstall script, past the point where that handler ever aborts.

The other seven sites (settle, bind_card, release_offer, take_held, record_uninstall, _forget_mint_spec, _sweep_mint_specs) write only after changing an entry the read found, so an empty read writes nothing. The ratchet's _KNOWN records that reason for them instead of "not audited" and drops the four fixed sites. The ledger spec (app-kit-platform.md) and the opt-in card spec (crew-mode.md) say what an unreadable store does.

Backwards compatibility

Compatible: every changed path runs only when a store exists but cannot be read, where main wrote an empty store over it; a missing file still starts empty, and display reads (entry, get_entry, list_by_app, classify_for_uninstall, the mint sweep) still read an unreadable file as empty.

Reader: src/kiro_crew/dashboard/handlers/member_self.py:_raise_opt_in -- crew page -- its except already answers 503 opt_in_unrecorded and raises no card; test_an_unreadable_store_refuses_the_offer_and_keeps_every_record
Reader: src/kiro_crew/connections/mint.py:_write_mint_agent_spec -- chat -- not _record_mint_spec(...) already raises OSError before any spec is written; test_a_manifest_that_cannot_be_read_records_nothing_and_keeps_its_rows
Reader: src/kiro_crew/apps/dependencies.py:resolve_dependencies -- app -- record_install returns False, so the dependency goes to failed and the loop goes on; test_unreadable_ledger_reports_dependency_failed
Reader: src/kiro_crew/apps/routes_uninstall.py:_run_uninstall -- app -- the classification comes back with nothing removable, so no dependency is cleaned and Step 5 runs; test_an_unreadable_ledger_is_left_as_it_was_and_removes_nothing

Tests

  • test_an_unreadable_store_refuses_the_offer_and_keeps_every_record: an EACCES on tool-access.json makes reserve_offer raise and leaves the file byte-identical.
  • test_an_unreadable_ledger_is_left_as_it_was_and_removes_nothing: with the ledger unreadable, an install and an uninstall both return normally, nothing is removable, and the file is byte-identical.
  • test_unreadable_ledger_reports_dependency_failed: with the ledger unreadable, a second app's successful install is reported failed, not installed, and the ledger is byte-identical.
  • test_a_manifest_that_cannot_be_read_records_nothing_and_keeps_its_rows: _record_mint_spec returns False and the manifest keeps its rows.
  • test_lenient_read_rewrite_ratchet.py: four sites leave _KNOWN, seven carry the found-only reason.

Determinism: the three first-round tests passed 20 runs at -n0, 10 runs at -n 4 --dist loadgroup --max-worker-restart=2 beside test_dependency_ledger.py and test_connections_mint.py, and the three touched files in a shuffled order (seed 9943, 70 tests). test_unreadable_ledger_reports_dependency_failed passed 20 runs at -n0, 10 runs at -n 4 --dist loadgroup --max-worker-restart=2 beside test_dependency_ledger.py and test_dependency_ledger_decode.py, and those three files in a shuffled order (seed 18437, 96 tests). None uses a clock, sleep or port.

Proof: PROVEN test/test_connections_mint_spec_files.py::test_a_manifest_that_cannot_be_read_records_nothing_and_keeps_its_rows, test/test_dependencies.py::TestCapabilitySeamResolution::test_unreadable_ledger_reports_dependency_failed, test/test_dependency_ledger_decode.py::test_an_unreadable_ledger_is_left_as_it_was_and_removes_nothing, test/test_lenient_read_rewrite_ratchet.py::test_no_new_rewrite_starts_from_a_lenient_read, test/test_mate_tool_access.py::test_an_unreadable_store_refuses_the_offer_and_keeps_every_record (head ddcffa2)

Manual verification

N/A — unit coverage sufficient: each test forces the read error on the real store file and compares its bytes before and after.

Screenshots / video

N/A — no frontend file changes and nothing user-visible is drawn differently.

Related Issues

Part of #24607

Sibling sweep

Swept: python -m pytest test/test_lenient_read_rewrite_ratchet.py (its AST scan of src/ lists every lenient read that feeds a write)
Sibling: src/kiro_crew/dashboard/handlers/mcp_config_entries.py -- tracked in #24607
Sibling: src/kiro_crew/apps/dev_mode.py -- tracked in #24607
Sibling: src/kiro_crew/apps/backend_runtime/pidfile.py -- tracked in #24607
Sibling: src/kiro_crew/apps/backend_runtime/stale_reap.py -- tracked in #24607
Sibling: src/kiro_crew/autonudge_selfarm.py -- tracked in #24607
Sibling: src/kiro_crew/apps/builtins/meetings/backend/providers/tasks.py -- tracked in #24607
Sibling: src/kiro_crew/apps/builtins/pptx_maker/backend/routes.py -- tracked in #24607
Sibling: src/kiro_crew/apps/builtins/spec_builder/backend/repository.py -- tracked in #24607
Sibling: src/kiro_crew/builtin_skills/kirocrew-dev/kirocrew-prepare-pr/scripts/push_guard_record.py -- tracked in #24607
Sibling: src/kiro_crew/aws_consent.py -- tracked in #24607
Sibling: src/kiro_crew/irq.py -- not affected -- load_state documents a lost state as one duplicate wake
Sibling: src/kiro_crew/ledger_wake.py -- not affected -- _read_rate documents a lost map as one extra wake

Pattern harvest

Not generalizable: the class already has its rule, the lenient-read ratchet in test/test_lenient_read_rewrite_ratchet.py, and this PR only shrinks its frozen list.

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

Contributed under the project's Apache-2.0 license.

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 7, 2026 02:18
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 7, 2026
@github-actions

github-actions Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of ddcffa2dd1267c51b2fdea3a2806d4fac25e0a4d — 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. Each rewrite now refuses to write when its read fails, which fixes the mechanism behind #24607 for these three modules. The ## Not a goal section defers the sibling modules, and the ratchet still lists them.

Inventory (7 items) — 7 justified

Intent: stop three stores (crewmate opt-in, app dependency ledger, mint manifest) from being wiped when a read fails for a moment. This is a FIX.

  1. When tool-access.json can't be read, the crewmate opt-in card is refused with 503 opt_in_unrecorded instead of erasing every crewmate's record — justified
  2. When the ledger can't be read, an app install or enable lists that dependency as failed instead of installed, and the ledger is left as it was — justified
  3. When the ledger can't be read, an uninstall removes no dependency and carries on — justified
  4. When the mint manifest can't be read, Connect fails instead of dropping the manifest's rows — justified
  5. The three readers gain a strict keyword. It follows the existing convention (agent_state._read, template_mcp_additions._read) and has 4 strict call sites — justified
  6. The ratchet _KNOWN re-tags 7 sites as found-only and drops 4. I read record_uninstall, _forget_mint_spec and _sweep_mint_specs, and each writes only after changing an entry it found — justified
  7. The specs app-kit-platform.md and crew-mode.md now say what an unreadable store does, as the spec rule requires — justified

[FIRST-PRINCIPLES-REVIEWED] ddcffa2

Description read

[DESCRIPTION-READ] ec21ccce48c22790170b28c1236237a60764dc7b808cbde15931699b43162c99

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

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision ddcffa2dd1267c51b2fdea3a2806d4fac25e0a4d 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 7, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks. The change adds a strict read only on the four rewrite paths, and every caller of the changed returns is listed and handled.

Notes

  • An uninstall that runs while the ledger is unreadable leaves the removed app listed in installedBy. Later uninstalls by other apps will treat those dependencies as shared and never clean them. The spec addition in app-kit-platform.md should say this, so nobody reads it as a silent leak later.

[DESIGN-REVIEWED] ddcffa2

Description read

[DESCRIPTION-READ] e23fbf7ff5f4d58e6eaf4642ad389f581dfc823909e819cdef9d42b31d9a80d5

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] ddcffa2

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

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

@github-actions

github-actions Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of ddcffa2dd1267c51b2fdea3a2806d4fac25e0a4d and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] ddcffa2

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

@bolichen97
bolichen97 enabled auto-merge (squash) November 7, 2026 02:44
@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 7, 2026
The crewmate opt-in store, the app dependency ledger and the connection
mint manifest were each rewritten from a reader that answers an empty
document on any OSError, so a transient EACCES or EIO published an empty
file over every other entry.

Each reader gains a strict mode for the base of a rewrite: only a
missing file reads as empty. reserve_offer raises (the card is refused
with 503 opt_in_unrecorded), _record_mint_spec returns False (the mint
fails as before), and the two ledger rewrites leave the file as it was
and log a warning. An install whose ownership was not recorded reports
that dependency as failed, so a later install or enable records it
instead of a later uninstall treating another app as its sole owner.
The remaining sites in these modules write only after changing an entry
the read found, and the ratchet records that reason for them.

Part of #24607
@bolichen97
bolichen97 force-pushed the fix/24607-strict-rewrite-reads branch from e333b65 to ddcffa2 Compare November 7, 2026 04:28
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Skipped ownership registration lets uninstall remove a shared dependency span=c7161665f34f

fixed in ddcffa2: record_install now returns False when the ledger cannot be read (the file is still left as it was), and resolve_dependencies lists that dependency in failed instead of installed.
The missing owner is now reported, not hidden: enable answers partial_failure and a registry install warns, and a later install or enable records the owner.
This is the fix the adjudication scoped (pass the failure up, count the dependency as failed). Rolling back the capability install is not an option, because the other app still owns and uses that dependency.
Pinned by test/test_dependencies.py::TestCapabilitySeamResolution::test_unreadable_ledger_reports_dependency_failed, red without the fix and green with it.

[operator: bolichen97]

@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 7, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/app-kit-platform.md and src/kiro_crew/apps/ (bridges.py, bridges_agents.py, bridges_register.py, bridges_skills.py, manager_install.py, update_status.py) since this head went green (a47c2d4 -> 2552c90); CI re-running.

[operator: bolichen97]

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 7, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved for the on-call. Review lanes pass on ddcffa2, no conflict, no open change request.

@KiroCrewCaptain
KiroCrewCaptain merged commit 7a4830a into main Nov 7, 2026
97 of 101 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the fix/24607-strict-rewrite-reads branch November 7, 2026 10:12
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 7, 2026
buluoray pushed a commit that referenced this pull request Nov 8, 2026
The crewmate opt-in store, the app dependency ledger and the connection
mint manifest were each rewritten from a reader that answers an empty
document on any OSError, so a transient EACCES or EIO published an empty
file over every other entry.

Each reader gains a strict mode for the base of a rewrite: only a
missing file reads as empty. reserve_offer raises (the card is refused
with 503 opt_in_unrecorded), _record_mint_spec returns False (the mint
fails as before), and the two ledger rewrites leave the file as it was
and log a warning. An install whose ownership was not recorded reports
that dependency as failed, so a later install or enable records it
instead of a later uninstall treating another app as its sole owner.
The remaining sites in these modules write only after changing an entry
the read found, and the ratchet records that reason for them.

Part of #24607

(cherry picked from commit 7a4830a)
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