Repository navigation
fix(skills): coordinate live and pending auto-skill slug claims - #12970
Conversation
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Verify the shard-7 red really is main's #13005 before merging — Coverage Gate fails closed behind it and this PR cannot clear it itself. [DESIGN-REVIEWED] 7a2cc4b |
First Principles Review (Fable 5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS The two declared uncoordinated writers (crystallize's raw-file staging, dashboard The three defects are provenanced by tests that fail on base; the cross-process premise for the lock is real (gateway, What this change shipsInventory (9 items) — 9 justifiedIntent: stop the auto-skill pipeline silently losing generated candidates when the live tree and pending queue claim the same slug independently — a FIX.
[FIRST-PRINCIPLES-REVIEWED] 7a2cc4b |
Opus 5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 5.6 Review — ✅ no blocking findings (all downgraded on adjudication)GPT 5.6 flagged blocking issues on This comment is updated in place on each push. Review detailsBLOCKING -- src/kiro_crew/history_consolidation.py:1819 -- Marker retraction never schedules the promised retry Adjudication (Opus 5) — is blocking on each finding proportionate?F1 — I opened Conditions confirmed: the slug-claim lock refusal sets Recovery path (not none): any subsequent message re-triggers Harm rung — LOW. The lost item is a single speculative auto-skill candidate, an explicitly best-effort, human-review-gated proposal ( [ADJUDICATION] 7a2cc4b total=1 uphold=0 downgrade=1 False positive or not applicable? A repository writer can comment: |
GPT 5.6 Review —
|
GPT 5.6 Review —
|
50133b8 to
987c6d3
Compare
987c6d3 to
2e91f85
Compare
2e91f85 to
45d72db
Compare
GPT 5.6 Review —
|
GPT 5.6 Review —
|
|
Evidence on the current fenced finding, for whoever decides its disposition. This is not an override, just the code reading behind it. The finding at The detection marker does not prevent a retry. Skill detection never consumed the consolidation offset. The window is the tail of the whole session ( That last point also prices the prescribed fix. "Prevent offset advancement" would hold back the offset that history, semantic and lesson extraction share, which reintroduces the duplicate-entry problem the decoupling exists to avoid. On the residual itself. Reaching the drop needs two processes contending on one skills home AND the holder exceeding the 5 second ceiling over a critical section that is directory On the anchor. The Separately, |
|
Round disposition for head This head is the branch rebased onto current The fenced finding F1 is closed in code. The prior disposition argued its premise; this one does not, because the mechanism the finding names now has a fix in the tree. Which half of the prescribed fix I implemented
The marker half is implemented. The offset half is deliberately not, on the adjudication's own pricing of it: the finding's "prevent offset advancement" half "would hold back the shared consolidation offset that history/semantic/lesson extraction advance -- re-consolidating the same tail into duplicate entries, which is exactly why skill detection was decoupled from that offset." Implementing it would trade this residual for duplicate history, semantic and lesson entries. What is in the tree is the remedy the adjudication itself described: "a retryable-outcome contract threaded from The mechanism was real, and the code's own documentation is the evidence
Nothing delivered that promise. This is narrower than the finding's "permanently drops": one further appended message still re-runs detection, as the prior disposition showed. But the recovery the code documents genuinely did not exist, and that is worth closing rather than arguing. The fix
It is an out-parameter rather than a raise or a new return type, for two reasons this tree forces. Claim-lock sites, enumeratedThree call sites take the lock. Two are reachable from PinsTwo tests, both failing before the fix and passing after.
The history pin's pre-fix failure is the assertion it was written for, not an incidental error: The skills pin errors before the fix because it must construct the new class: Scoped local run:
Backend Tests shard 7 and Coverage Gate belonged to the base
That test is a static AST walk over It was a main-red incident, filed as #13005 sixteen minutes before that CI run and closed as completed by #13007. RebaseThe previous head did not merge with current One test-side fix was needed beyond the merge. The new pin's double did not accept #13760's Verified on the rebased tree: the scoped suite plus the shard-7 test give A second instance of the same invariant, deliberately left for a follow-up#13760's guard yields It is not closed here, and not because it was missed. |
45d72db to
7e104db
Compare
The live tree and the pending queue are two halves of one auto-skill slug space, but each side claimed a name while consulting only its own half, and the sibling walk trusted a derived name it never re-validated. Three ways a candidate went missing: A publisher could take a queued candidate's promotion destination. create_auto_skill claimed auto/<slug> checking only the live directory, so an auto-publish proposing a slug that staging had already queued as a sibling took that name. approve_pending_skill then refused the candidate with live_exists for as long as the live directory stood, and TTL pruning deleted it unreviewed. Exhausted sibling allocation reported success. With every suffix -2..-50 taken, stage_skill_candidate returned the natural auto/<slug> name without persisting anything. The caller read the truthy return as staged, logged it and wrote a staged audit event, and consolidation advanced its message offset, so the candidate was lost behind a success record. A suffixed name could fall outside the canonical slug pattern. Appending -N to a long slug can exceed the pattern's length, and list_pending_skills skips a non-canonical directory while prune_pending walks that same list, so such a claim was invisible to the queue, the dashboard and pruning alike. _auto_slug_available is the one availability test both claim paths consult: it checks the pending queue, the live tree, and the slug pattern before any allocation. create_auto_skill declines a slug that is awaiting review, since a publish slug is re-derivable while a queued candidate is immutable, human-gated work. The reservation is scoped to the claim under test. A pending UPDATE candidate is queued under a name derived from its target and is promoted to the live target named in its metadata, so its own queue slug is never a live destination; reserving by name alone would hold auto/<target-slug>-update against an unrelated skill that slugifies to that name and drop it, because consolidation advances its offset whatever one candidate's outcome. So _auto_slug_available takes the claim kind (live, pending-new, pending-update) and the live test reads the queued candidate's kind. That test fails closed: metadata that is missing, unreadable, or silent about kind keeps the slug reserved. The two claim paths allocate in different directories, so an atomic mkdir makes each half safe on its own but cannot make the cross-namespace pair safe. Both paths test and claim inside one advisory lock at the skills root, and the live claim uses mkdir(exist_ok=False) so a platform that cannot lock still refuses a directory another writer owns. Staging holds that lock until .meta.json is committed, because kind is the field a live publish reads: a publish seeing the claimed directory before that file lands fails closed and refuses a name an UPDATE candidate never reserves. Every acquire failure proceeds unlocked instead of raising, because both callers contract to return None so the caller audits a rejection, and an escaping error would convert a recorded refusal into the silent loss this coordination exists to stop. A stalled claim lock also reopens skill detection, not just its log. The lock refuses rather than proceeding unlocked, and both its docstring and the timeout constant's comment promise that the next consolidation pass retries; nothing delivered that promise. Skill detection records a (rotation_generation, message_count) marker BEFORE staging runs and skips a pass whose pair is unchanged, so a candidate refused by the lock was not re-judged until a further message changed the count or a gateway restart cleared the marker. The two refusals were also indistinguishable at the caller: a bare None covers an invalid slug, an oversized procedure and an exhausted sibling walk, which are properties of the candidate and final, as well as an unacquired lock, which is a property of the moment. ClaimRefusal carries that one bit. A claim path sets retryable only for the lock, and the detection pass retracts its own marker when it sees one, so the next pass re-judges the same unchanged session and reaches the claim with the lock free. It is a mutable out-parameter rather than a raise or a new return type on purpose: the lock helper documents that it never raises because an escaping error would abort a consolidation pass mid-way, and every caller that does not care keeps reading str | None. The shared consolidation offset is left advanced deliberately. History, semantic and lesson extraction all consume it, so rewinding it to re-attempt one skill candidate would re-summarize an already-consolidated tail into duplicate entries, which is why skill detection was decoupled from that offset to begin with. The marker is the only state the retry rewinds. Fixes #10252
7e104db to
7a2cc4b
Compare
bolichen97
left a comment
There was a problem hiding this comment.
Reviewed on behalf of the maintainers (sweep 2026-09-27): readiness passed, required checks green on 7a2cc4b, no blocking review threads, security posture unchanged. Approving and merging.
Problem / Motivation (1. What is the problem?)
Goal: Give the live and pending auto-skill namespaces one shared availability
test under one shared lock, so no claim on either side can strand or silently
drop a generated skill candidate.
Auto-skill slugs live in two places, the live tree at
auto/<slug>and thepending queue at
auto/.pending/<slug>, but each side claimed a name whileconsulting only its own half, and the sibling walk trusted a name it derived
without re-validating it. Three ways a generated skill candidate went missing:
A publisher could take a queued candidate's promotion destination.
create_auto_skillclaimedauto/<slug>after checking only the livedirectory. Staging's sibling allocation queues
.pending/<slug>-2when thenatural slug is under review; a later auto-publish (approval off, prose-only)
proposing the literal slug
<slug>-2then claimedauto/<slug>-2live.approve_pending_skillrefuses a candidate whose live name is occupied(
live_exists), so the queued candidate became unapprovable for as long asthat directory stood, and TTL pruning deleted it unreviewed.
Exhausted sibling allocation reported success. With every suffix
-2..-50taken,
stage_skill_candidatelogged a warning and returned the naturalauto/<slug>name without persisting anything. The caller reads a truthyreturn as staged: it logged the candidate and wrote a
stagedaudit event, andconsolidation advanced its message offset regardless of per-candidate outcome.
The candidate was lost behind a success record.
A suffixed name could fall outside the canonical slug pattern. The pattern
_AUTO_NAME_PATTERNallows at most 64 characters, so appending-2to a63-character slug produces a 65-character name.
list_pending_skillsskips apending directory whose name is not canonical, and
prune_pendingwalks thatsame list, so such a claim is invisible to the queue, to the dashboard, and to
pruning alike. It can never be reviewed and is never cleaned up.
Why it matters (2. Why this issue matters to the user)
Every one of these paths destroys generated work silently, and the queue is the
only place a user ever sees it. Consolidation advances its message offset per
run, so a dropped candidate is not retried from the same sessions. The skill the
model extracted is simply gone. In the first and third paths the user is never
told anything at all; in the second the audit trail positively asserts the
candidate was staged, so the record disagrees with the disk and a user looking
for the skill has no way to find out why it is absent.
Not a goal
publish loses and returns
None, which its caller already audits as arejection. Giving it a sibling live name
auto/<slug>-Nchanges whatpublishing means and would put a name in the live tree that no queue entry
points at. That belongs in its own issue.
auto/outside this coordination. Thecrystallizebuiltin stages with raw file tools, andcreate_skillaccepts anauto/-prefixed name from the dashboard handlers. Both are recorded in theowning spec as known gaps, and each needs a different change from this diff.
success; 50 distinct candidates slugifying alike is an upstream dedupe problem,
so the useful follow-up is surfacing the rejection rather than raising the
number.
_is_pending_slug_safeenforce_AUTO_NAME_PATTERN. It guardstraversal only, so the approve and dismiss handlers still accept a
non-canonical slug the queue will not list. Nothing reaches that state through
the staging path after this change.
What changed (3. How our fix solves it)
The root cause is that two namespaces forming one slug space were claimed
independently. The fix gives them one shared availability test,
_auto_slug_available, which both claim paths consult before allocating, andone shared lock,
_auto_slug_claim_lock, which they hold across the test andthe claim it authorizes.
create_auto_skilldeclines a slug held by a queued NEW candidate, so apublish cannot take that candidate's destination. One side of the collision
has to lose, and the publish is the cheaper loss: it returns
None, which thecaller already audits as a rejection, whereas the queued candidate is
immutable human-gated work that would disappear with no record at all.
Consolidation advances its message offset whatever one candidate's outcome, so
neither side is retried from the same sessions. The choice is which loss
leaves a trail, and this PR does not claim the refused publish is re-derived.
stage_skill_candidatetests every name on its walk, so the queue onlyaccepts a claim it can serve: a new candidate never lands on a slug whose live
counterpart is occupied, and a suffixed name that breaks the pattern is never
claimed.
Noneinstead of a name. That is what makes the callertake its rejection branch, so a candidate that was not written is not
recorded as staged.
mkdir(exist_ok=False), not the availability test, onboth sides. The test picks a name; the
mkdirwins or loses, and a directoryappearing in the window moves a staging walk to the next name and makes a live
publish refuse rather than overwrite the other writer's content.
The two halves are not symmetric, so
_auto_slug_availabletakes the claimunder test rather than reserving by name alone:
liveneedsauto/<slug>absent and no pending NEW candidate under thatslug.
pending-newneeds the pending directory absent andauto/<slug>unoccupied, since a queued candidate whose live name is taken is
unapprovable.
pending-updateneeds only the pending directory absent. An update is queuedunder a name derived from its target (
<target-slug>-update) andapprove_pending_updatepromotes it over the livetargetnamed in itsmetadata, never consulting
auto/<candidate-slug>. So a pending updatereserves nothing in the live tree, and treating it as a reservation would hold
auto/<target-slug>-updateagainst an unrelated skill that slugifies to thatname and drop it, since consolidation advances its offset whatever one
candidate's outcome.
The kind is read from the candidate's metadata and the test fails closed:
metadata that is missing, unreadable, or silent about
kindkeeps the slugreserved, so a candidate that may still be promoted to
auto/<slug>cannot bestranded by an unreadable file.
The lock is what closes the cross-namespace window an atomic
mkdircannot:the two paths allocate in different directories, so each
mkdiris safe on itsown while two processes sharing one skills home could each pass the other half's
test and then create their own directory. Staging holds it until
.meta.jsoniscommitted, because
kindis the field a live publish reads: a publish seeingthe claimed directory before that file lands fails closed and refuses a name an
update candidate never reserves.
An unacquired lock is a REFUSAL, not a licence to claim uncoordinated.
_auto_slug_claim_lockyields whether it acquired, and all three claim pathsreturn
Nonewhen it did not, because proceeding unlocked would reopen exactlythe window the lock exists to close. The acquire itself is
platform_compat.file_lock, which owns the platform matrix, the bounded wait andthe single-shot refusal for an on-loop caller; it is entered explicitly so the
acquire is the only failure that means unlocked, since one
except OSErroraroundthe whole block would read a failed write as a failed acquire. The ceiling is
overridden down to seconds because a claim's critical section is one directory
test plus a small write, so a holder that has not released by then is stuck. The
two acquire failures both refuse: the lock file cannot be opened, which is a home
that would fail the skill write too, or the lock is not won inside the ceiling. It
never raises, because
Noneis what the callers audit as a rejection while anexception would abort the consolidation pass, and the next pass reaches the same
code with the lock free. The lock file is a dot-prefixed plain file at the skills
root, which discovery skips, placed outside
auto/so taking it does not createthe auto namespace as a side effect of a refused claim.
restore_auto_skillis the third claimant on the live half and now obeys thesame rule. It moves an archived skill onto
auto/<slug>, which strands a queuedcandidate exactly as a publish would, and it previously checked only whether its
own destination existed. The invariant is now stated in the owning spec so a
future allocator reads it: the three auto-skill allocators test availability with
_auto_slug_availablewhile holding_auto_slug_claim_lock.Two writers reach
auto/without that coordination and are documented in thespec as known gaps rather than covered cases, because closing either one is a
different change from this diff:
crystallizebuiltin skill stagesauto/.pending/<slug>with raw filetools, so it can write a pending directory after a live claim already stands.
Closing it means giving crystallize a host path that calls
stage_skill_candidate; no such path exists today, since the only in-treecaller is consolidation. Adding an agent-facing surface is outside this fix.
create_skillaccepts anauto/-prefixed name from the dashboard prompt anddiscover handlers, since
READONLY_SKILL_KEY_PREFIXESis only("kiro-user/", "kiro-workspace/"). Closing it means refusing or routing thosenames at those two call sites.
Tests (4. What tests we did)
Fourteen new cases in
test/test_skill_pending.py, each pinning one leg of theroot cause:
test_publish_cannot_occupy_a_queued_candidates_destinationwalks thereported sequence end to end: stage, sibling-queue a distinct candidate at
-2, have a publisher propose that literal slug, and assert it is refused, nolive directory appears, and the queued candidate still approves successfully.
test_staging_skips_a_sibling_whose_live_name_is_taken: the queue does nothand out an unapprovable name; the candidate lands on
-3and approves.test_exhausted_pending_slugs_report_failure_not_success: all 50 names taken,staging returns
None, and nothing is written under any claim.test_overlong_sibling_slug_is_refused_not_orphaned: a 63-character slugwhose
-2sibling exceeds the pattern; exactly one pending directory remainsand it is listable.
test_update_candidate_may_share_its_live_targets_slug: the update path isnot diverted by its live target.
test_pending_update_does_not_reserve_a_live_name: a queued update attopic-updatedoes not block a distinct skill publishing toauto/topic-update, and the update still points at its own target.test_pending_candidate_of_unknown_kind_still_reserves_its_slug: absent,malformed,
new, and non-object metadata each keep the slug reserved.test_both_claim_paths_hold_the_shared_slug_lock: both paths run theiravailability test at lock depth 1, and the lock file exists afterwards.
test_live_claim_refuses_a_directory_that_appears_under_it: a directorycreated in the window makes the live publish refuse, and the other writer's
bytes survive. The
Path.mkdirpatch is scoped withpytest.MonkeyPatch.context()so nothing the fixtures installed is touched.test_claim_without_the_lock_is_refused_not_attempted: with the acquireforced to fail, staging and publishing both return
Noneand write nothing.test_claim_lock_that_cannot_be_opened_refuses_without_raising: an unopenablelock file takes the same refusal path rather than raising.
test_pending_metadata_is_committed_under_the_claim_lock: at lock release theclaimed directory and its
.meta.jsonare both on disk, so no publish can reada claim whose
kindhas not landed.test_restore_cannot_occupy_a_queued_candidates_destination: a restore isrefused while a candidate of that slug is queued, the archive keeps its copy,
and the candidate still approves.
test_claim_is_the_mkdir_not_the_availability_testforces the race by makingthe availability test approve an occupied name, and asserts the walk moves on
while the candidate under review keeps its bytes.
test_approve_refuses_when_live_existsbuilds its live skill directly on disk.Publishing through
create_auto_skillover a queued slug is the behaviour thischange refuses; the guard it covers, approval's own
live_existsrefusal, stillapplies to a live skill arriving by any other route, so the assertion is
unchanged.
Run locally with explicit
-n0:test/test_skill_pending.py43 passed,test/test_skill_versioning.py39 passed (the update path),test/test_skill_pending_api.py+test_skill_pending_notify.py+test_skill_update_flow.py116 passed,test/test_skill_lifecycle.py13 passed(the restore path), and the skill selections in
test/test_history.py23 passed.Gates: comment-history, black ratchet, sync-io-in-async, feature-map and
changelog-history all pass on the diff scope; flake8, isort and mypy are clean on
both changed Python files.
5. Any other suggestions on the work
The deliberate scope limits are listed under
## Not a goalabove; the onecrystallizedetail worth repeating is that a direct write could still reach thenon-canonical-slug state
_is_pending_slug_safedoes not refuse.One review note needs no change. First Principles reported two ACP
clientInfohunks as an undeclared rider and suspected a stale diff base, which is correct:
git diff origin/main...HEADis exactly the two files above, with zeroclientInfooracpmatches. The hunks are main's own merged change appearingin a two-dot diff against a moved base.
Pattern harvest
Rule candidate: review-prompt
Pattern: one name space with two independent allocators, where each tests only
its own half before claiming. The defect class has two faces, and this fix hit
both. First, a claim keyed by a name rather than by the destination approval
actually writes to: a pending update is stored under
<target-slug>-updatebutpromoted to
auto/<target-slug>, so reserving its storage name holds a livename nothing will ever occupy. Second, an atomic create per namespace read as if
it made the cross-namespace pair atomic, which it cannot.
The review question to add: for every allocation, which path does approval
write to, does every other writer of that exact name run the same test, and do
the test and the claim sit inside one lock. Ask it wherever a store has a
staging area and a live area, which in this repository also covers pending
artifacts and staged monitors, not only skills.
Fixes #10252