Skip to content

fix(apps): list an app's skills as soon as its links change - #31675

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
fix/adoption-live-skill-catalog
Nov 7, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
fix/adoption-live-skill-catalog

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: An app's skills appear in the skill list as soon as the app is enabled, and disappear as soon as it is disabled or uninstalled.

Enabling an app links its skills under the skills folder, and uninstalling it unlinks them, but GET /api/skills (and the agents' skill catalog) kept serving the list it already held. Measured on origin/main against an isolated gateway with an adopted papyrus: right after POST /api/apps/papyrus/enable the five papyrus skills were missing for 66 s; right after POST /api/apps/papyrus/uninstall they were still listed, pointing at skills/papyrus/... paths that no longer existed. A restart shortly after an enable served the stored snapshot without the app's skills.

Why it matters

Every app that ships skills hits this on every enable, disable, uninstall and reinstall, and the five adopted former built-ins (#26967) all ship skills. For up to a minute an agent can be offered a skill whose files are gone, or miss one the user just turned on, and the skills page disagrees with the app list.

Not a goal

  • Changing the catalog TTL, the stored snapshot, or how a walk is scheduled.
  • A change made by another process (a kirocrew app enable from the CLI): the gateway's loaders are not reachable from there, and it still converges on the TTL as any out-of-band change does.
  • Any app-specific handling: nothing here names an app.

What changed (motivation → approach → change)

Symptom: app skills lag their links by the catalog TTL. Root cause: the app bridge changes the skills root without going through a SkillsLoader, and only a loader's own mutators clear its cached list, its stored snapshot and its disabled-apps memo.

The bridge already rebuilds .app-skill-links.json after every link change. It now compares the rebuilt bytes with the file: when the link set changed (or the file is not a readable regular file), it calls the new src/kiro_crew/skill_live_loaders.py::invalidate_loaders_of, which runs _invalidate_iter_cache() on every open loader of that skills root, exactly as a loader's own create or delete does. Each SkillsLoader registers itself there, weakly, at the end of __init__ in src/kiro_crew/skills.py, and the bridges facade (src/kiro_crew/apps/bridges.py) names the new import for type checkers. An unchanged link set, which is what the boot reconcile produces when it re-links what is already linked, writes nothing and keeps the snapshot, so a gateway boot pays no cold walk for this.

The skills folder is writable from inside the sandbox, so the comparison (_holds_exactly in src/kiro_crew/apps/bridges_skills.py) opens the name without following a link and without blocking, and reads it only when fstat says it is a regular file. A FIFO or link left at that name is atomically replaced, never waited on.

The app-kit-platform and memory-skills-hooks specs, and the TTL comment in skills_discovery.py, name the new immediate path.

Backwards compatibility

Compatible: the links file keeps its JSON format and keys; it is left untouched when its content would not change. It is written as bytes, so on Windows its newlines are \n rather than \r\n; JSON readers accept both.

Removes nothing: no path, key, record or function is removed or tightened.

Tests

test/test_app_skill_links_clear_catalog.py warms a real loader's list, then changes the links and reads again with no clock or sleep:

  • a registered app skill is listed on the very next read, and a deregistered one is gone from it;
  • an unchanged reconcile does not move the loader's generation (no cold walk at boot);
  • only loaders of that skills root are cleared, and a closed loader is skipped;
  • a FIFO with no writer at the links name does not stall a register: the file is replaced and the skill is listed (POSIX only; it fails within the bounded join when the read blocks).

Proof: PROVEN test/test_app_skill_links_clear_catalog.py::TestAppSkillLinksClearTheCatalog::test_a_registered_skill_is_listed_on_the_next_read, test/test_app_skill_links_clear_catalog.py::TestAppSkillLinksClearTheCatalog::test_a_deregistered_skill_is_gone_on_the_next_read, test/test_app_skill_links_clear_catalog.py::TestAppSkillLinksClearTheCatalog::test_a_fifo_at_the_links_name_is_replaced_not_waited_on (head b4184a7f0621)

Determinism: 20/20 at -n0, 10/10 at -n 4 --dist loadgroup --max-worker-restart=2 with test_app_bridges.py and test_skill_catalog_snapshot.py as co-tenants, and a shuffled order (seed 5894, 85 ids with test_app_bridges.py) green. The FIFO test: 20/20 at -n0, 10/10 at -n 4 with test_app_bridges.py, and the file's six tests in a shuffled order (seed 31675) green. test_app_bridges.py, test_skill_catalog_snapshot.py, test_skills_composition_contract.py, test_skills.py, test_skills_bindings.py, test_skill_listing_cost.py, test_frontmatter.py and test_flake_pattern_ratchet.py pass.

Manual verification

Isolated gateway from this branch (loopback, stub ACP backend, throwaway KIROCREW_HOME/HOME/XDG dirs), papyrus adopted at 6ca7bc69:

  • enable, then GET /api/skills in the same second: 5 papyrus skills (main: 0 for 66 s);
  • uninstall, then GET /api/skills in the same second: 0 (main: still 5);
  • trust, registry reinstall, enable, restart, GET /api/skills right after boot: 5.

Related Issues

Part of #26967

Sibling sweep

Swept: git grep -nE "_skills_dir()|skills_dir()" -- src/kiro_crew (writers of the skills root that do not go through a loader)
Sibling: src/kiro_crew/apps/bridges_skills.py -- changed here
Sibling: src/kiro_crew/dashboard/handlers/discover.py:729 -- not affected -- the provider bundle install already calls _invalidate_iter_cache on the dashboard loader
Sibling: src/kiro_crew/dashboard_upkeep.py -- not affected -- writes scripts under an existing skill, never adds or removes a SKILL.md
Swept: git grep -nE "read_text|read_bytes|open(" -- src/kiro_crew/apps/bridges_skills.py src/kiro_crew/skill_live_loaders.py (reads of a sandbox-writable name in this diff)
Sibling: src/kiro_crew/skill_live_loaders.py -- not affected -- opens no file; the bridge's other probes are lstat/stat/realpath, which never open the name

Pattern harvest

Rule candidate: review-prompt
Pattern: a writer that changes a cached tree without going through the cache's owner must invalidate the owner's cache

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

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 6, 2026 19:05
@bolichen97
bolichen97 requested a review from Zedmor November 6, 2026 19:05
@bolichen97
bolichen97 enabled auto-merge (squash) November 6, 2026 19:05
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 6, 2026
@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 59a89922ca43548ba8ef5af3b745c00f3049d983 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 6, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 59a89922ca43548ba8ef5af3b745c00f3049d983 — 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 defect is measured, the fix acts where the cache goes stale (a writer that bypasses the loader), and no existing loader registry exists to reuse.

What this change ships

Inventory (5 items) — 5 justified

Intent: an app's skills should show up in the skill list and the agents' catalog as soon as the app is enabled, and drop out as soon as it is disabled or uninstalled. FIX.

  1. An enabled app's skills are listed on the very next GET /api/skills and catalog read, instead of up to a TTL later — justified
  2. A disabled or uninstalled app's skills disappear at once, along with the stored snapshot a restart would serve — justified
  3. The links file is compared with what is on disk and left untouched when the link set is unchanged, so a boot reconcile triggers no cold walk — justified
  4. A FIFO or link left at the links-file name is replaced instead of blocking the register — justified
  5. The links file is written as bytes, so its newlines on Windows are \n — justified

[FIRST-PRINCIPLES-REVIEWED] 59a8992

Description read

[DESCRIPTION-READ] be59a4ba34f707b08e043dd2dce4b5e93207a08fe332a5ab3611128e3cb24fff

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

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

No design-level concerns. The bridge now clears the cache its own link writes make stale, using the same invalidation the skill loader already runs after its own edits, and skips the clear when the links file would not change.

Notes

  • invalidate_loaders_of reads the loader's private _closed, _dir and _invalidate_iter_cache. A small public SkillsLoader.invalidate_if_root(path) would keep that coupling in one place if this registry gets a second caller.

[DESIGN-REVIEWED] 59a8992

Description read

[DESCRIPTION-READ] 28224caa44612b6043e8286a8b7ca3ca190e0f0614684d8605564aa8865d5c01

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 59a8992

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

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

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 59a8992

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

@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 6, 2026
@bolichen97
bolichen97 force-pushed the fix/adoption-live-skill-catalog branch from e59feed to 75f27c5 Compare November 6, 2026 20:43
@bolichen97

Copy link
Copy Markdown
Contributor Author

Backend Tests shard 2 (Linux + Windows) and the Coverage Gate on e59feed were main's red, not this diff: both failed only test/test_security_gate_liveness.py::test_the_package_stays_within_its_line_budget ("package grew to 34753 lines" against a budget of 34,733). This PR touches nothing under src/kiro_crew/security/; main itself was at 34,753 lines, and #31625 (39717a0) raised the budget to match. Rebased onto origin/main (26c8238); that node id and the PR's related tests pass locally on the new head 75f27c5. The diff is unchanged.

@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 6, 2026
@bolichen97
bolichen97 force-pushed the fix/adoption-live-skill-catalog branch from 75f27c5 to c6ad349 Compare November 6, 2026 21:52
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased onto main at 7c364bc, which carries #31803 (the fix for the main red #31771). On the old head 75f27c5, the only reds were test/test_pull_request_target_allowlist.py::test_only_the_allowed_workflows_use_pull_request_target on shard 7, Linux and Windows, plus the Coverage Gate that depends on it. This PR does not touch that test. New head c6ad349 has the same diff. Locally the related tests pass (175 passed, the allowlist test included), flake8, isort, mypy, black, comment-history, brand and line-cap gates pass, and prove.py still says PROVEN. CI is re-running. The old head got PASS from Design and First Principles and no blocking findings from GPT or Opus, so no dispositions are owed.

@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 6, 2026
@bolichen97
bolichen97 force-pushed the fix/adoption-live-skill-catalog branch from c6ad349 to a3dfa20 Compare November 7, 2026 00:41
@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

self-added: yes
mechanism: the links-file read-back that decides whether to clear the catalog

  • Reading a planted FIFO stalls app lifecycle operations span=c4471b76613e

fixed in a3dfa20: the comparison is _holds_exactly, which opens the name with O_NONBLOCK|O_NOFOLLOW, reads only when fstat says S_ISREG, and reads at most len(expected)+1 bytes; a FIFO, link or unreadable file counts as changed and is atomically replaced as before.
Class swept: the only open of a sandbox-writable name in this diff; the bridge's other probes are lstat/stat/realpath, and skill_live_loaders.py opens no file.
Test: test_a_fifo_at_the_links_name_is_replaced_not_waited_on plants a writer-less FIFO, registers in a thread joined under FALLBACK_TIMEOUT_SECS, and asserts the file is replaced and the skill listed; it fails (blocked) with a plain O_RDONLY open.
The file is written as bytes so the byte comparison holds on Windows too; owning spec app-kit-platform.md 5.2 updated.

@bolichen97

Copy link
Copy Markdown
Contributor Author

CI reds on the old head c6ad349 were not test failures: Backend Ratchets & Boundaries, Backend Tests (3.12, 2), Backend Tests (3.12, 8) and Real Adapter Contract Tests all died in actions/setup-python downloading Python 3.12 (##[error]Unexpected HTTP response: 429, three tries each, before any test ran), and Coverage Gate failed because those shards produced no data. No node id failed, so there is nothing to reproduce or ledger. New head a3dfa20 fixes the GPT finding (disposition above), is rebased on main at f480fa5, and re-runs the whole suite. Locally: the PR's test file and the 14 related app-bridge/skill test files (417 passed), the flake-pattern ratchet, black/isort/flake8/mypy, comment-history, brand, harness-parity, line-cap and docs-lint pass, and prove.py says PROVEN for all three listed tests. Semgrep is not installed on this host; the SAST job runs it.

@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
Enabling, disabling or uninstalling an app links or unlinks its skills
under the skills root, but nothing told the open skills loaders, so
GET /api/skills and the agents' catalog kept serving the pre-change
list for up to the 60 s catalog TTL: an uninstalled app's skills stayed
listed, a just-enabled app's were missing, and a restart soon after
served the stored snapshot without them.

The bridge already rebuilds .app-skill-links.json after every link
change. It now compares the rebuilt body with the file and, when the
link set changed, invalidates every open SkillsLoader of that skills
root (new skill_live_loaders module; each loader tracks itself
weakly). An unchanged set, as the boot reconcile produces, writes
nothing and keeps the snapshot, so a boot pays no cold walk.

Part of #26967
@bolichen97
bolichen97 force-pushed the fix/adoption-live-skill-catalog branch from a3dfa20 to 59a8992 Compare November 7, 2026 01:35
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Nov 7, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running 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 59a8992, no conflict, no open change request.

@KiroCrewCaptain
KiroCrewCaptain merged commit 9e9f5ff into main Nov 7, 2026
97 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the fix/adoption-live-skill-catalog branch November 7, 2026 02:26
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 7, 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