Skip to content

fix(acp): remove legacy projection metadata from the agents directory - #36125

Merged
bolichen97 merged 2 commits into
mainfrom
fix/35501-legacy-projection-metadata-cleanup
Nov 13, 2026
Merged

bolichen97 merged 2 commits into
mainfrom
fix/35501-legacy-projection-metadata-cleanup

Conversation

@JLargent42

@JLargent42 JLargent42 commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A projection metadata file left in ~/.kiro/agents/ by a pre-v0.10.0 build no longer shows up as a fake subagent in every kiro-cli session.

Builds before v0.10.0 wrote the skill-projection view ledger and ownership sidecars to ~/.kiro/agents/.kirocrew-skill-projection-metadata/. Nothing on main reads, moves or removes them there. kiro-cli 3.1.0 loads every .json under the agents directory as an agent profile, dot-prefixed subdirectories included, so a leftover view-sources.json registers a subagent .kirocrew-skill-projection-metadata/view-sources in every session and logs an invalid-tool-name warning.

Why it matters

Every session on an upgraded install lists a subagent tool built from a metadata file. The model can try to call it, and it costs tool-spec tokens on every turn. The file never goes away on its own.

Not a goal

  • Asking kiro-cli to skip dot-prefixed directories when it loads agents.
  • Removing the legacy .kirocrew-skill-projection.lock or .kirocrew-skill-projection-leases/ (not .json at the agents-directory level, so not loaded as agents).
  • Reading or migrating the legacy ledger's view names back into this home's ledger.

What changed (motivation → approach → change)

Symptom: a fake subagent per session. Root cause: the legacy readers and migration were removed (#20213 / #32139), so a file at the old location stays forever, and kiro-cli 3.1.0 now loads it.

Fix, in src/kiro_crew/acp/skill_projection_parts/alias_reclaim.py: the boot drain (drain_stale_aliases) first calls _remove_legacy_metadata_dir. It walks .kirocrew-skill-projection-metadata/ only when it is a real directory (never a link or junction), bounded by the prune's work limit, and unlinks only regular files whose name and content prove Crew wrote them: view-sources.json holding only kirocrew-skill-view-<24 hex> → string entries, or a kirocrew-skill-view-<24 hex>.json sidecar carrying the managed marker. Each unlink is identity-checked through the existing _unlink_projection_lease_if_unchanged. The directory is removed with os.rmdir once empty; any other file keeps it. Errors are caught so the drain still never raises. Cost: one lstat per boot once the directory is gone.

docs/system-specs/modules/acp-client.md is updated to describe the cleanup. src/kiro_crew/acp/skill_projection.py names the three new definitions in the facade's TYPE_CHECKING manifest. test/link_screen_sites.py declares _remove_legacy_metadata_dir, regenerated with test/gen_link_screen_sites.py. The function refuses every link, like the orphan sweeps declared beside it, so it is not a held site.

Backwards compatibility

Compatible: only files no code path reads are removed; the current layout under <data_home>/skill-projection/ is untouched.

Reader: src/kiro_crew/acp/skill_projection_parts/view_sources.py:_read_view_ledger -- entry: chat -- reads _projection_metadata_dir() under the data home only, never the legacy directory (test_resume_retired_agent_names.py passes)
Reader: src/kiro_crew/acp/skill_projection_parts/view_ownership.py:_managed_metadata_for_alias -- entry: chat -- reads _projection_metadata_dir() only (test_native_skill_projection_rewrites.py passes)

Tests

test/test_skill_projection_legacy_metadata.py, against the real drain_stale_aliases:

  • a legacy ledger plus sidecar are removed along with the directory;
  • a ledger with a non-view key, a non-object ledger, a sidecar without the marker, and a file with a name Crew never writes are each kept (and the Crew sidecar beside them is removed);
  • a linked legacy directory is not followed (staged with make_dir_link, so it runs on Windows as a junction too).

Proof: PROVEN test/test_skill_projection_legacy_metadata.py::test_drain_removes_the_legacy_ledger_sidecars_and_directory, test/test_skill_projection_legacy_metadata.py::test_drain_keeps_a_file_crew_did_not_write[ledger-with-foreign-key], test/test_skill_projection_legacy_metadata.py::test_drain_keeps_a_file_crew_did_not_write[ledger-not-an-object], test/test_skill_projection_legacy_metadata.py::test_drain_keeps_a_file_crew_did_not_write[name-crew-never-wrote] (head f9bb8a3)

Ran locally: the new file plus test_resume_retired_agent_names.py, test_skill_view_relaunch_harness.py, test_native_skill_projection_lease_scan.py, test_skill_view_mode_recovery.py, test_native_skill_projection_rewrites.py (136 passed), and local-gate.py backend related (95 passed).

Manual verification

Reproduced on main: a Linux host upgraded from 0.9 has ~/.kiro/agents/.kirocrew-skill-projection-metadata/view-sources.json (35 entries, every key kirocrew-skill-view-<24 hex>, every value a string), which matches the ownership test above. The new test reproduces the drain leaving it on main (4 failures) and passes with the fix.

Related Issues

Fixes #35501

Sibling sweep

Swept: git grep -n "kirocrew-skill-projection" -- src/
Sibling: src/kiro_crew/acp/skill_projection_parts/alias_reclaim.py -- changed here

Pattern harvest

Not generalizable: a one-off file layout move whose migration was removed before every install had run it.

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.

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

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of f9bb8a33691b8fdf18997bc44e0c297713a2a57e — 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 to check.

What this change ships

Inventory (4 items) — 3 justified

Intent: stop a leftover pre-v0.10.0 metadata file in ~/.kiro/agents/ from appearing as a fake subagent in every kiro-cli session (#35501). This is a FIX.

  1. At gateway boot, the legacy ledger and the view sidecars that Crew provably wrote are deleted from .kirocrew-skill-projection-metadata/; linked directories are not followed — justified
  2. The legacy directory is removed once it is empty, and kept while any file Crew did not write is still in it — justified
  3. A new info log line reports how many legacy files were removed — undeclared, rides along
  4. The acp-client spec now describes the boot cleanup in place of "nothing removes them" — justified

[FIRST-PRINCIPLES-REVIEWED] f9bb8a3

Description read

[DESCRIPTION-READ] 0c2656377d7c85506cf7e0b43b430febe971f73e265be091adc4cafa0b92320e

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

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: the cleanup deletes only files Crew can prove it wrote, at a location no current reader uses. The one build that would still read them was already declared unsupported for this directory.

[DESIGN-REVIEWED] f9bb8a3

Description read

[DESCRIPTION-READ] 01a36302cf426c5b965811bf1b6f4391812c44853bf4a4e9667410ec5f48d608

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] f9bb8a3

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

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

@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] f9bb8a3

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

@JLargent42
JLargent42 force-pushed the fix/35501-legacy-projection-metadata-cleanup branch from 5a7df8d to 9e6a272 Compare November 12, 2026 22:45
@JLargent42

Copy link
Copy Markdown
Contributor Author

GPT 6.1 review of 5a7df8dc25f001942d360e42c5c509242125d33e — disposition

  • BLOCKING test/test_skill_projection_legacy_metadata.py:79 (Windows skip on the linked-directory test): fixed in 9e6a27276906f8f6b4372d206c21ca5e3bccfceb. The test now stages the link with kiro_crew.testing.links.make_dir_link (an unprivileged junction on Windows) and the skipif is gone, so the is_link_or_junction refusal is exercised on every platform. Class sweep: this is the only skip in the new test file.

The branch was also rebased onto main 0feaa8be90 to pick up #36124, which fixes the GitFork import whose absence on main failed Build Wheel, Build Desktop and E2E on the previous head.

@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 13, 2026
@JLargent42
JLargent42 force-pushed the fix/35501-legacy-projection-metadata-cleanup branch from 9e6a272 to e84be79 Compare November 13, 2026 02:15
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 13, 2026
Builds before v0.10.0 wrote the skill-projection view ledger and
ownership sidecars to ~/.kiro/agents/.kirocrew-skill-projection-metadata/.
Nothing reads them there, and kiro-cli 3.1.0 loads every .json under the
agents directory as an agent, so a leftover ledger becomes a fake subagent
in every session.

The boot drain now removes the regular files there whose name and content
prove Crew wrote them, and the directory once it is empty. Any other file
stays, and a linked directory is never walked.

Fixes #35501
…ards

Stage the linked-directory test with make_dir_link, which makes an
unprivileged junction on Windows, instead of skipping it there.

Declare _remove_legacy_metadata_dir in the link-screen baseline
(regenerated with test/gen_link_screen_sites.py): it refuses every link,
like the orphan sweeps beside it. Name the three new alias_reclaim
definitions in the skill_projection facade's TYPE_CHECKING manifest.
@JLargent42
JLargent42 force-pushed the fix/35501-legacy-projection-metadata-cleanup branch from e84be79 to f9bb8a3 Compare November 13, 2026 04:06
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 13, 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.

Approve at f9bb8a3. I read the whole product diff: alias_reclaim.py, the facade re-exports in skill_projection.py, and the spec paragraph.

kiro-cli 3.1.0 loads every .json under the agents directory as an agent, dot-prefixed subdirectories included. So the ledger and sidecars a pre-v0.10.0 build left in .kirocrew-skill-projection-metadata/ showed up as subagents. The boot drain now removes them through _remove_legacy_metadata_dir, and it only deletes what Crew provably wrote:

  • it walks only a real directory, never a link or junction, bounded by _PROJECTION_PRUNE_WORK_LIMIT;
  • it unlinks only regular files whose name and content pass _is_legacy_metadata_file: a ledger that maps view names to strings and nothing else, or a view-named sidecar carrying the managed marker;
  • each unlink goes through the existing identity-checked _unlink_projection_lease_if_unchanged;
  • it removes the directory only once it is empty, so any other file keeps it;
  • an OSError is logged at debug and the drain goes on.

No regex is added. The name check reuses main's existing _LEGACY_ALIAS_NAME_RE unchanged. There is no refusal, and nothing is live red (the cancelled runs are superseded by newer passes).

@bolichen97
bolichen97 merged commit 6e0d01b into main Nov 13, 2026
211 of 229 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Legacy skill-projection metadata left in ~/.kiro/agents is loaded by kiro-cli 3.1.0 as an agent, adding a fake subagent to every session

2 participants