Skip to content

fix(agent-discovery): retry a Windows sharing violation on an agent spec read - #29915

Merged
bolichen97 merged 1 commit into
mainfrom
fix/27905-spec-read-sharing-violation
Nov 4, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/27905-spec-read-sharing-violation

Conversation

@JLargent42

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: On Windows, an agent's configured MCP servers stay listed while the dashboard rewrites kirocrew.json, instead of briefly reading as "no servers configured".

On Windows, a read of ~/.kiro/agents/kirocrew.json that overlaps a replace of that file fails with PermissionError (WinError 32 or 33). _read_agent_spec folded that error into None with a DEBUG line, and _load_agent_config treats None as absent. For that one read the capabilities view drops the agent's MCP servers, and discover_servers_to_sync compares mcp.json against an empty set. The reporter measured 1 to 3 misses per 200 reads with a writer looping. POSIX allows the read, so only Windows is hit.

Why it matters

A configured server that reads as never configured can't be told apart from a real absence. A sync check in that window can offer to sync servers that are already configured. No log line above DEBUG shows the miss.

Not a goal

What changed (motivation → approach → change)

The bug: the spec read opened the file once and treated a Windows lock as "not a spec". Now a locked spec is read again after the replace.

Piece Change
atomic_write.py retry_read_sharing_window The retry loop that read_bytes_with_retry already ran, split out so a caller with its own open can reuse it. Same budget (_REPLACE_MAX_ATTEMPTS, _REPLACE_BACKOFF_SECONDS), Windows only, never sleeps on the event loop. read_bytes_with_retry calls it unchanged.
agent_discovery_parts/spec_reads.py _read_spec_bytes Runs the pinned no-reparse open and the capped read inside that loop. The link, hardlink, fence and size checks run on every attempt.
_read_agent_spec A Windows PermissionError that outlasts the budget logs one WARNING naming the spec with %r, then returns None as before. POSIX keeps the DEBUG line.
agent_discovery.py The facade binds the two new owner imports, as its type-checker test requires.

read_agent_spec_strict reads through _read_spec_bytes as well, so it gets the same retry. A contended read off the loop waits at most about 0.45 s. A caller on the event loop still makes one attempt.

Known overlapping PR: #10107 (fork, folder-scoped agent picker) rewrites much of spec_reads.py and conflicts with main. This change touches about 20 lines there and is independent of it.

Backwards compatibility

Compatible: a spec that is missing, oversized, non-UTF-8, linked, hardlinked, sensitive or UNC still returns None with the same log lines and audit events. Only a Windows sharing violation is retried.

Removes nothing: the change adds a retry and one WARNING. No path, key, function or record is removed.

Tests

test/test_agent_spec_read_sharing_violation.py patches open_fenced_for_read to raise PermissionError with winerror 32 or 33, then open the real file:

  • a lock held for one attempt, or for all but the last, still returns the configured server from _load_agent_config;
  • a lock held past the budget returns None and logs exactly one WARNING naming the spec;
  • on the event loop, and on POSIX, the read makes one attempt and logs no WARNING;
  • an absent spec still returns None with no WARNING;
  • read_agent_spec_strict gets the same retry.

Determinism: 5 repeats green, and green with the 8 node ids in reverse order. 651 targeted tests pass at -n 2 (spec readers, facade, atomic write, retry sites, flake ratchet).

Proof: PROVEN test/test_agent_spec_read_sharing_violation.py::test_spec_locked_mid_replace_still_lists_its_servers[32], test/test_agent_spec_read_sharing_violation.py::test_spec_locked_mid_replace_still_lists_its_servers[33], test/test_agent_spec_read_sharing_violation.py::test_spec_locked_for_most_of_the_budget_is_still_read, test/test_agent_spec_read_sharing_violation.py::test_spec_locked_past_the_budget_warns_and_reads_as_none (head 5aa092c)

Manual verification

N/A: the defect needs a Windows sharing violation, which the seam test simulates. The Backend Tests (Windows) lane runs the same tests on Windows.

Related Issues

Closes #27905

Sibling sweep

Swept: git grep -n "open_fenced_for_read(" -- src/
Sibling: src/kiro_crew/agent_discovery_parts/spec_reads.py:539 -- not affected -- head probe returns False on failure, so the caller keeps raising
Sibling: src/kiro_crew/agent_discovery_parts/dir_revision.py:65 -- not affected -- an unhashable entry makes the memo re-read the spec through the fixed reader
Sibling: src/kiro_crew/artifacts_disk.py:194 -- not affected -- artifact store files, not an agent spec, different writer
Sibling: src/kiro_crew/knowledge/readers.py:215 -- not affected -- asciidoc include under a jail, no product writer replaces it

Pattern harvest

Rule candidate: review-prompt
Pattern: an except OSError that returns a sentinel for "absent" also swallows a Windows PermissionError from a concurrent replace; retry it or report it apart from FileNotFoundError

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

@JLargent42
JLargent42 requested review from a team and KiroCrewCaptain as code owners November 4, 2026 20:13
@JLargent42 JLargent42 self-assigned this Nov 4, 2026
@JLargent42
JLargent42 requested a review from bolichen97 November 4, 2026 20:13
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 4, 2026
@github-actions

github-actions Bot commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

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

The retry is pulled out of the loop read_bytes_with_retry already ran, not written as a second copy. Each item traces to #27905.

What this change ships

Inventory (5 items) — 5 justified

Intent: on Windows, keep an agent's configured MCP servers listed while the dashboard rewrites kirocrew.json, so they no longer briefly read as "no servers configured". This is a FIX.

  1. On Windows, an agent spec read that hits a sharing violation is retried off the event loop and returns the real servers — justified
  2. A spec still locked once the retries run out logs one WARNING naming it, where it used to log a DEBUG line — justified
  3. New public helper atomic_write.retry_read_sharing_window, split out of read_bytes_with_retry, which now calls it; 2 consumers — justified
  4. read_agent_spec_strict gets the same retry through _read_spec_bytes — justified
  5. The facade binds platform_compat and retry_read_sharing_window, as its type-checker test requires — justified

[FIRST-PRINCIPLES-REVIEWED] b6f0e70

Description read

[DESCRIPTION-READ] 971e4a9505cc4e7d4bd6d11e18f28ddfd9f502033543c508fa82934cd7d3c606

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

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks. The fix reuses the existing Windows read-retry loop around the pinned open, so it fixes the cause without changing the None contract, and the Windows CI lane runs it.

Notes

  • On Windows, a real ACL denial on a spec now waits the full retry budget (about 0.45 s) and then logs a WARNING saying "still locked by another process", which is wrong for that case. Reverting is easy, but the text could say "unreadable (locked or denied)" instead.

[DESIGN-REVIEWED] b6f0e70

Description read

[DESCRIPTION-READ] b22afcb94b2b49018c79ea393f1234fa030aebdd61e4b2b2ad104f550edc660a

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

Notes:

  • On Windows, _read_agent_spec logs every PermissionError as "still locked by another process", so an ACL denial (WinError 5) gets the same wording. Checking winerror in (32, 33) would keep that message accurate.

[OPUS-REVIEWED] b6f0e70

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

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

@github-actions

github-actions Bot commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] b6f0e70

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

@JLargent42
JLargent42 force-pushed the fix/27905-spec-read-sharing-violation branch from 5aa092c to b6f0e70 Compare November 4, 2026 20:27
@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 4, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Approving b6f0e70. I read the full diff at this head.

  • retry_read_sharing_window is the existing loop from read_bytes_with_retry, lifted out to take a callable. read_bytes_with_retry now calls it, so its budget, backoff, Windows-only and off-event-loop rules are unchanged.
  • The spec reader retries the whole pinned open and read inside read_once, so the fence check runs again on every attempt instead of reusing a descriptor from before the replace.
  • A fence refusal is not caught by the new branch: _SpecReadRefused subclasses OSError, not PermissionError, so it is not retried and its own except handles it first.
  • Past the budget the per-file contract stays None, now with one WARNING on Windows only. POSIX keeps the single attempt and the DEBUG line.
  • Tests cover WinError 32 and 33, a lock for most of the budget, a lock past it (one warning), the event loop keeping one attempt, POSIX, an absent spec, and the strict reader.

No regex, glob or case-blind matching is added. All 97 checks pass.

@bolichen97
bolichen97 merged commit 3c0cbfd into main Nov 4, 2026
97 checks passed
@bolichen97
bolichen97 deleted the fix/27905-spec-read-sharing-violation branch November 4, 2026 21:11
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 4, 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

2 participants