Skip to content

fix(acp): reclaim run dirs kiro-cli and memory consolidation leave - #16039

Merged
bolichen97 merged 1 commit into
kirodotdev:mainfrom
unstablebrainiac:fix/run-dir-reclaim-gaps
Oct 6, 2026
Merged

bolichen97 merged 1 commit into
kirodotdev:mainfrom
unstablebrainiac:fix/run-dir-reclaim-gaps

Conversation

@unstablebrainiac

@unstablebrainiac unstablebrainiac commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Run folders that subagents, stateless crons and memory consolidation calls leave in the workspace are removed once the run ends.

Each one-run session gets its own folder under the workspace root. Crew removes it at shutdown, and the gateway's sweep catches what a dead gateway left. In practice neither removes them. One host held 2,068 of these folders, each holding only setup files, and gained about 8 an hour.

Two gaps keep them:

  • kiro-cli creates an empty .kiro/agents in the folder it starts in. For a subagent or a stateless cron run, that is the run's own folder. The reclaim accepts only Crew's .kiro/settings files, so this empty folder makes it keep the whole tree.
  • A memory consolidation call runs under memory-consolidation:<store>:<uuid hex>. That key is not one of the one-run shapes, so its folder is never marked and never reclaimed.

Why it matters

The workspace root grows on every host that runs subagents or crons, and nothing shrinks it. Every spawn that derives its folder lists that root again. The doctor's manual remedy names folders holding only .kiro/settings/cli.json, which skips nearly every folder that piles up.

Not a goal

  • Folders where a run turned on code intelligence keep the .kiro/settings/lsp.json kiro-cli writes. The reclaim still unlinks only files Crew writes, so those folders stay.
  • Folders older builds left carry no marker. The sweep still leaves them, and the doctor still names the manual remedy.
  • Long-lived session folders (dashboard, channel, persistent cron) are unchanged.
  • The reclaim on Windows is unchanged. Its walk works by path name and cannot pin .kiro against a junction swapped in after the check, so it still keeps folders holding kiro-cli's .kiro/agents, and memory consolidation folders stay unmarked there. The doctor counts the memory consolidation folders with the unmarked ones. A marked folder kept for its .kiro/agents is in neither of its figures, as on main.

What changed (motivation → approach → change)

Both gaps close inside the existing reclaim rule in src/kiro_crew/session_work_dir.py.

Gap Change
kiro-cli's empty .kiro/agents Residue while it is an empty real folder. It is removed with rmdir before any file is unlinked. A link, a file, or any entry inside it keeps the whole tree. Only the descriptor walk does this, because it removes the folder relative to a .kiro it holds open. The by-name walk used on Windows cannot pin .kiro, so it keeps a tree that holds the folder.
Memory consolidation folders memory-consolidation:<store>:<32 hex> joins the one-run shape table, with the store-name grammar memory_stores validates. Where the walk pins .kiro, the provider marks and reclaims these folders and the sweep sees them. On the by-name walk one gate keeps both the key and the folder name long-lived, so those folders are never marked or swept. The doctor's census counts them on either walk.

The safety rule stays as it was. The reclaim unlinks only Crew's cli.json and its lock, and every folder goes through rmdir. The doctor in doctor_checks/resources.py names the empty .kiro/agents in its remedy and says an unmarked folder can be a kind this platform never marks. docs/system-specs/modules/acp-client.md describes both changes.

Backwards compatibility

Compatible: the reclaim accepts one more empty folder and one more key shape. A folder holding anything a run wrote is still kept, and every folder reclaimed today is still reclaimed.

Tests

  • test/test_session_work_dir.py: where the walk pins .kiro, an empty .kiro/agents is reclaimed, alone or beside Crew's settings; the by-name walk keeps those trees untouched. A spec, a folder or a file named agents keeps the tree as it was. A linked agents is refused. A fresh agents folder makes an old folder young. A file that lands in agents after the check stops the reclaim with cli.json still in place. The sweep reclaims a dead predecessor's memory consolidation folder where the walk pins .kiro and leaves it on the by-name walk. Memory consolidation keys and folder names are one-run shapes only where the walk pins .kiro, and the provider factory follows the same rule. The store part accepts exactly the sampled names memory_store_name_defect accepts, and its pattern is pinned to the one memory_stores validates with. The doctor's census counts every run shape on either walk.
  • test/test_cli_doctor.py: the manual remedy names the empty .kiro/agents, and an unmarked memory consolidation backlog is counted and named on either walk.

Manual verification

  • kiro-cli acp --agent kirocrew-lite, an agent with no MCP servers, started in a folder holding only .kiro/settings/cli.json, had created .kiro/agents there by the time initialize answered. A second folder, passed as the session's cwd, got none.
  • One host's workspace root held 2,068 one-run folders. All 168 cron and subagent folders made since the gateway last restarted were marked and held the empty .kiro/agents. The 178 memory consolidation folders had no marker.

Screenshots / video

N/A: no frontend change.

Related Issues

Related: #16049 records the other one-run session keys whose folders this PR leaves for a follow-up.

no linked issue: this PR closes no issue; the leak was found by counting one host's workspace root.

Pattern harvest

Rule candidate: review-prompt
Pattern: a cleanup's list of what it may remove covers only what the parent writes, and misses what the child process it starts writes into the same folder.

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

@unstablebrainiac
unstablebrainiac requested a review from a team as a code owner October 1, 2026 23:44
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running labels Oct 2, 2026
@github-actions

github-actions Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 91ed141d5d4fd7b2fb5856ad78f9f7956ad4f48f via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Check that memory-consolidation folders on Windows (no marker, no sweep) are acceptable to leave growing until a follow-up closes the by-name walk gap.

[DESIGN-REVIEWED] 91ed141

Description read

[DESCRIPTION-READ] e836e11440b52b7d05852f2e75b3ea86048495f51aca682160ab2ea3bdb66103

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

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed 91ed141d5d4fd7b2fb5856ad78f9f7956ad4f48f via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 91ed141

@github-actions

github-actions Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — 🟡 CONCERNS

Premise-level review of 91ed141d5d4fd7b2fb5856ad78f9f7956ad4f48f via the fork AI-review pipeline — 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/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

_MEMORY_STORE_NAME is a second copy of memory_stores._STORE_NAME_RE's grammar, and only a test keeps the two in step.

Not justified as shipped

  • Item 3 — duplicate of src/kiro_crew/memory_stores.py:87: _MEMORY_STORE_NAME = r"[a-z0-9](?:[a-z0-9-]{0,78}[a-z0-9])?" restates _STORE_NAME_RE (1 existing definition found by grepping a-z0-9-]{0,78}). The diff's own comment says "a test pins the two", so two spellings are kept in step by a test instead of having one source.
    Subtraction: delete the literal and build the component from memory_stores._STORE_NAME_RE.pattern with its ^/\Z anchors removed. Delete the pinning test with it.
    Clears when: the shape table reads the store grammar from memory_stores, or the description names the import cost or cycle that rules this out.

What this change ships

Inventory (6 items) — 5 justified

Intent: one-run work folders that subagents, stateless crons and memory consolidation leave behind are removed when the run ends. This is a FIX.

  1. Reclaim now removes the empty .kiro/agents that kiro-cli creates, on the walk that pins .kiro — justified
  2. On Windows (the by-name walk), a tree holding .kiro/agents is still kept — justified
  3. Memory consolidation keys and folders count as one-run, so they are marked, reclaimed and swept — duplicate of memory_stores._STORE_NAME_RE
  4. Memory consolidation shape is withheld on the by-name walk — justified
  5. Doctor's manual remedy now names the lock file and the empty .kiro/agents — justified
  6. Doctor relabels unmarked folders: "a build that did not mark that kind" — justified

[FIRST-PRINCIPLES-REVIEWED] 91ed141

Description read

[DESCRIPTION-READ] e335580c0063057a4a75679923d8fb6ed729ce6831cfd20bf6db23fa5ee4a932

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.

@unstablebrainiac

This comment has been minimized.

@github-actions

github-actions Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed 91ed141d5d4fd7b2fb5856ad78f9f7956ad4f48f via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 91ed141

@unstablebrainiac
unstablebrainiac force-pushed the fix/run-dir-reclaim-gaps branch from 7e20d34 to 9f9cd07 Compare October 2, 2026 01:04
@unstablebrainiac

This comment has been minimized.

@unstablebrainiac
unstablebrainiac force-pushed the fix/run-dir-reclaim-gaps branch from 9f9cd07 to 676438f Compare October 2, 2026 02:11
@unstablebrainiac

This comment has been minimized.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention 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 readiness: action required A blocking check or review needs attention labels Oct 2, 2026
@unstablebrainiac
unstablebrainiac force-pushed the fix/run-dir-reclaim-gaps branch from 676438f to 57af4e4 Compare October 2, 2026 02:47
@unstablebrainiac

This comment has been minimized.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision labels Oct 2, 2026
@unstablebrainiac
unstablebrainiac force-pushed the fix/run-dir-reclaim-gaps branch from 57af4e4 to 6fc4404 Compare October 2, 2026 03:46
@unstablebrainiac

This comment has been minimized.

@unstablebrainiac

This comment has been minimized.

@unstablebrainiac
unstablebrainiac force-pushed the fix/run-dir-reclaim-gaps branch from 6fc4404 to 747c93d Compare October 2, 2026 06:01
@unstablebrainiac

This comment has been minimized.

@unstablebrainiac

This comment has been minimized.

@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 Oct 2, 2026
@unstablebrainiac
unstablebrainiac force-pushed the fix/run-dir-reclaim-gaps branch from 10b3c6e to 6324dce Compare October 2, 2026 15:24
@unstablebrainiac

This comment has been minimized.

@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 Oct 2, 2026
@unstablebrainiac

This comment has been minimized.

@unstablebrainiac
unstablebrainiac force-pushed the fix/run-dir-reclaim-gaps branch from 6324dce to ac549ad Compare October 2, 2026 15:53
@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 Oct 2, 2026
@unstablebrainiac

This comment has been minimized.

@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 Oct 2, 2026
@unstablebrainiac

This comment has been minimized.

@unstablebrainiac

This comment has been minimized.

@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 Oct 2, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

Reviewed for merge triage, not approving from my side: it reclaims run directories that kiro-cli and memory consolidation leave behind, i.e. it deletes files. A deletion path needs a maintainer to confirm the ownership check cannot match a live run or user data. CI is green.

@unstablebrainiac

Copy link
Copy Markdown
Contributor Author

The ownership check is main's and this PR does not change it. The PR widens what can pass it in two places: kiro-cli's empty .kiro/agents folder, and the memory-consolidation_<store>_<call> folder name. What a folder must clear before anything in it is deleted, at ac549ada8:

  • Crew made it for one run. Only a folder derived from a one-run session key is marked (.kirocrew-run-dir, written before the first spawn). An explicit cwd is never marked (loader.py#L5217). The sweep never takes an unmarked folder, whatever its name (session_work_dir.py#L31-L61).
  • Same data home. The marker names the data home and the gateway pid. Neither caller touches a folder marked by another data home (#L440-L467).
  • Not live. The shutdown reclaim covers only the folder its own provider derived, after its client confirmed the process tree dead, and a marker in it must name this home and this process. The sweep takes only a predecessor's folders: a gateway pid that is not this process and has no entry left in this home's pid ledger after the boot reap. It skips every folder a live session in this process names, and any tree whose newest mtime is under an hour old (#L722). Nothing probes the liveness of a pid another process wrote.
  • Residue only. The only files ever unlinked are cli.json and its lock under .kiro/settings, and the marker (#L84-L94). Every directory is removed with rmdir, which fails on anything non-empty, so a folder holding any other file stays. .kiro/agents is removed by rmdir while empty and before any unlink (#L598-L602), so a file that lands in it after the check stops the reclaim with nothing deleted. That step runs only on the descriptor-pinned walk. The by-name walk on Windows keeps any folder holding .kiro/agents, and never marks a memory consolidation folder.

One test drives every gate through a single sweep and asserts each kept folder: live, under an hour old, this process's, another home's, a retained pid, an unreadable marker, a long-lived session's, one holding a user file, and an unmarked one. A liveness probe raises if called (test_session_work_dir.py#L746). The .kiro/agents cases are at #L493 (not empty: kept) and #L520 (an entry arrives mid-reclaim: nothing deleted).

@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 5, 2026
kiro-cli creates an empty .kiro/agents in the folder it starts in, which
for a subagent or a stateless cron run is the run's own work directory.
The reclaim accepted only Crew's .kiro/settings chain, so that folder
made every such directory unreclaimable, at shutdown and in the gateway
sweep. An empty .kiro/agents is now residue: it is checked empty,
removed with rmdir before any residue file is unlinked, and refused
when it is a link or holds anything.

A memory consolidation call runs under a fresh
memory-consolidation:<store>:<uuid hex> key whose derived directory
nothing revisits, but the key was not a one-run shape, so those
directories were never marked or reclaimed. The shape table now carries
that key, so the provider marks and reclaims them and the sweep and the
doctor census see them.
@iamwhatever

Copy link
Copy Markdown
Contributor

Reviewed, not approving (crew-pr-reviewer). It adds reclamation, meaning deletion, of run directories that kiro-cli and memory consolidation leave behind (session_work_dir.py). Our review rules leave data-deleting changes to the owner, who should confirm the selection can never match a live or user-owned directory.

@unstablebrainiac

Copy link
Copy Markdown
Contributor Author

@iamwhatever The selection rules are the same as when I answered this on Oct 4: #16039 (comment). The head has been rebased since (now 91ed141) but the patch is unchanged. A folder is only reclaimed when it carries Crew's one-run marker for this data home, its gateway has exited, nothing in it changed in the last hour, and removal is rmdir-only for directories, so a live run or anything a user put inside it is never matched.

@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.

Reviewed on behalf of the maintainers (sweep 2026-10-06): full diff read, callers verified against current main, readiness passed, required checks green, no blocking review threads. Owner confirmation on the deletion path: a run folder is reclaimed only when it carries Crew's own marker for this data home, its gateway pid has exited, nothing in it changed for >= 1h, and every directory goes through rmdir on the descriptor-pinned walk -- a live run or any user file keeps the whole tree. Windows reclaim is unchanged; only the doctor census widens. Approving and merging.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants