Skip to content

fix(folders): stop agents forking duplicate and empty folders - #15186

Merged
chenmingwei23 merged 2 commits into
mainfrom
fix/agent-folder-dedupe
Sep 30, 2026
Merged

chenmingwei23 merged 2 commits into
mainfrom
fix/agent-folder-dedupe

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: An agent never leaves an empty sidebar folder behind and never makes a second folder with the same name as one that exists.

A user's conductor sat in their Ops folder. It made a second top-level Ops, an empty mockforge-service-builder under it, and a stray top-level "New Session..." tab. The user saw folders "randomly created with nothing inside them".

Why it matters

Every conductor run can litter the sidebar. The person then has to find and delete the junk by hand. A duplicate Ops also splits one goal's work across two folders.

Not a goal

  • Letting an agent create anywhere else in the person's tree, or rename, move or delete the person's folders. Only the folder its own session sits in opens (owner decision, below).
  • Deleting folders that are already empty. Cleanup stays the person's job.
  • A dry run for session_fork. Its folder path works as before.

What changed (motivation → approach → change)

Three code paths made the reported shape.

Symptom Root cause Fix
second top-level Ops A crew member's folder list shows only its own folders (chat_folders.py api_chat_folders). The mkdir -p walk in mcp_dashboard.py did not see the person's Ops, so it made a new one. And a member could not nest under the person's folder at all. A member's list adds the folder its own session is filed in, plus that folder's ancestors. An app or member may create directly under that folder (caller_home_slot). The new subfolder is the agent's.
two parallel creates race Each walk read the tree, then created the missing segment. No check ran under the lock. An agent's same-name test runs inside the locked append. A twin the caller owns is returned (200, reused). Anyone else's twin is refused (folder_name_exists, 409), never duplicated.
empty mockforge-service-builder session_create made its folder path first. A create the gateway then refused left the folders empty. The mkdir -p walk checks every segment's length first. Just before its first create, it posts the session create with dry_run: true. A refusal ends the walk with nothing made.

The owner decided the nesting rule: a conductor in a folder gets its workers under that folder. So the allowance is narrow. The home slot must be the caller's own session: an app's _app must match, and a member's principal must be the one the chat gate stamped from this request's verified key. The slot's folder_id is read under the folder-store lock. Other person folders, a deeper child of the home folder, and rename/move/delete stay refused.

create_session(dry_run=True) runs every gate, the create budget and both slot caps, then returns just before the first write. The budget is read with the new create_rate_limit.has_create_budget, which spends no token. The route refuses a non-boolean dry_run. A refused duplicate writes a denied chat.folder_create SEL line.

The goal-conductor skill now says: if the person already put you in a folder, that folder is your goal folder. The chat_folder_create tool text states the new rule. The spec docs/system-specs/modules/session-control.md describes all of it.

Backwards compatibility

Compatible: the browser keeps its freedom to name two folders alike. Only internal (agent) callers get the name rule, and a same-name folder they own comes back instead of a twin. A path that already exists resolves as before. dry_run is a new optional field. The home-folder rule only allows what was refused before.

Tests

test/test_agent_folder_dedupe.py, 25 cases.

  • A refused create makes no folder. The dry run names the deepest existing folder. An existing path skips it.
  • A conductor in the person's Ops creates Ops/<agent> once and reuses it after. Two parallel creates land one folder.
  • Other person folders (a sibling, a deeper child) are still refused. A person-owned twin under the home folder is refused, not reused.
  • An app naming a session that is not its own gets no home allowance.
  • A member's folder list holds its home chain and nothing else of the person's.
  • The walk takes a reused folder as found, not created. A lost race reuses the winner's folder. An invisible foreign twin is refused, not forked.
  • create_session(dry_run=True) mints nothing, spends no budget, and carries the real refusal, including a spent create budget. The route refuses "false".
  • A too-long later segment creates nothing. A refused duplicate is audited.

Removing the home-folder allowance fails four of these cases. Removing the whole fix fails nine on origin/main.

test/test_mcp_dashboard_folders.py: one case now finds the folder POST by path, since the dry run comes first.

Manual verification

Ran the targeted files: folder tools, cap, ownership, scaffold, steering, member folder gate, pin ownership, session control, fork, error-code contract. 874 pass. black, isort, flake8, mypy and the comment-history gate are clean.

Screenshots / video

N/A — backend and tool behavior only; no UI change.

Related Issues

User report: duplicate Ops folder and empty subfolder made by a conductor.

Pattern harvest

Rule candidate: review-prompt
Pattern: a multi-step tool that creates durable state before its last step can still refuse, leaving that state orphaned.

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

@iamwhatever
iamwhatever requested a review from a team as a code owner September 29, 2026 23:21
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 29, 2026
@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of d5f1328531974c334e3c490613cde13e6bcd36df — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Verify the dry-run cutover in create_session stays comment-enforced only by choice — a future refusal gate added below it silently re-opens the empty-folder path.

Suggestions

  • The dry-run/real parity contract rests on one comment (session_control.py:2342); a pinning test (e.g. asserting dry_run returns before any state write via an instrumented state) would turn silent drift into a red test.

[DESIGN-REVIEWED] d5f1328

Description read

[DESCRIPTION-READ] 38d4f4714b1995e82df2dfa17465af1a0e93f33a31b2f2179e8b77b19d877e37

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 Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings (all downgraded on adjudication)

GPT 5.6 flagged blocking issues on d5f1328531974c334e3c490613cde13e6bcd36df; Opus 5 adjudication downgraded every one of them to advisory. Adjudication downgraded all 1 blocking finding(s) to advisory: the remedy each one requires is disproportionate to the harm it prevents. Read them as advice, not as merge conditions.

This comment is updated in place on each push.

Review details

BLOCKING -- src/kiro_crew/dashboard/session_control.py:2313 -- Dry-run admission races the folder commit
has_create_budget(SESSION_CREATE, caller_key) if dry_run else allow_create(...)
Two concurrent creates with one slot remaining -> both previews pass -> both commit folders -> one final create returns 429 -> its folder remains empty.
Anchor: persist-before-you-publish
Fix: Reserve rate and slot capacity during preflight, consume it during final creation, and release it if folder creation fails.
[BLOCK-MERGE-DOWNGRADED] d5f1328
[GPT-REVIEWED] d5f1328

Adjudication (Opus 5) — is blocking on each finding proportionate?

LOW — the stranded artifact is one empty sidebar folder row, reported back to the caller in made_note (src/kiro_crew/mcp_dashboard.py:2016, surfaced on the failure path at :2024 and :2087), and the retry consumes it rather than duplicating it, because the walk now reuses the caller's own same-name folder (src/kiro_crew/mcp_dashboard.py:1509-1536).
Conditions confirmed: the preview reads budget without spending it (session_control.py:2313) and returns before any write (session_control.py:2346); the preflight is called once, before the first create only (mcp_dashboard.py:1501); the real create re-runs the same rate/cap gates and can 429 (session_control.py:2318, :2324, :2336) — so it needs two creates in flight landing on the same last budget unit or cap boundary, with the loser's path still carrying uncreated segments. Recovery: no automatic cleanup (the MCP server has no folder delete at all — handlers/_shared.py:1057), but the row is visible and the person deletes it from the dashboard; the PR's own contract already states this residual (mcp_dashboard.py:1975-1982).
Real fix cost: the preflight is an HTTP POST from the MCP server into the gateway, so "reserve at preflight, consume at create, release on failure" means new cross-process reservation state keyed per caller, a TTL/leak reaper (an agent that dies between preflight and create would otherwise permanently hold a slot and rate unit), release wiring on every folder-walk failure path, and a new ordering contract between mcp_dashboard and session_control — a mechanism existing solely for this one path, carried by every future reader of the create gate, to avoid one deletable empty folder.

[ADJUDICATION] d5f1328531974c334e3c490613cde13e6bcd36df total=1 uphold=0 downgrade=1
DOWNGRADE F1 src/kiro_crew/dashboard/session_control.py:2313 reason=disproportionate-remedy
[GPT-ADJUDICATED] d5f1328531974c334e3c490613cde13e6bcd36df

False positive or not applicable? A repository writer can comment:
/ai-review override gpt d5f1328531974c334e3c490613cde13e6bcd36df: <one-sentence reason>

@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — ⏭️ skipped

Revision d5f1328531974c334e3c490613cde13e6bcd36df touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of d5f1328531974c334e3c490613cde13e6bcd36df — 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: PASS

Verify the asserted owner decision behind the home-folder allowance: it loosens the agent/person folder fence, and only the description attests "the owner decided the nesting rule".

What this change ships

Inventory (10 items) — 10 justified

Intent: stop an agent's folder walk leaving duplicate or empty sidebar folders behind — a FIX for a reported user shape, with tests the description says fail nine-deep on base.

  1. A session create that would be refused now makes no folders — the walk previews the create first — justified
  2. An agent hitting its own same-name folder gets that folder back instead of a twin — justified
  3. An agent hitting someone else's same-name folder is refused (409), never duplicated — justified
  4. An agent may now create a subfolder inside the folder its own session is filed in — justified
  5. A crew member's folder list now shows its home folder and its ancestors — justified
  6. New optional dry_run field on the session-create route (one consumer: the MCP preflight) — justified
  7. New read-only budget probe has_create_budget beside allow_create (one consumer: the dry run) — justified
  8. A too-long later path segment now fails before any earlier segment is created — justified
  9. A refused duplicate folder create writes a denied SEL audit line — justified
  10. The goal-conductor skill now keeps a conductor in the folder the person filed it in — justified

Counts run: dry_run route field → 1 consumer (mcp_dashboard._preflight_create); has_create_budget → 1 (create_session); caller_home_slot → 2; _resolve_folder_for_new_session → 2 call sites, so session_fork is the 1 unfixed sibling of the orphaned-state cause — declared and deferred in ## Not a goal, so accepted. docs/decisions/ has no dry-run/preview entry; the GET-over-dry_run pin in sessions.py:3589 covers destructive verbs only, and the route's strict boolean check addresses that pin's stated hazard. Residual note for the merger: the Goal's "never leaves an empty folder" is delivered minus the preflight-to-create window, admitted in _resolve_folder_for_new_session's docstring but not in the description.

[FIRST-PRINCIPLES-REVIEWED] d5f1328

Description read

[DESCRIPTION-READ] 4cc62328870c2650dcf4741da6b3919519ff9601807919d6ea6113a368ec145b

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.

zejiangg added 2 commits September 30, 2026 00:00
… ones

A crew member's folder view hid the person's folders, so its mkdir -p walk forked a same-name twin; parallel walks raced on the same segment; and session_create built its folder path before a create that could still be refused. The folder endpoint now refuses an agent a same-name sibling under its lock, the walk re-reads on that refusal, and session_create dry-runs the create before making any folder.
A conductor the person filed in a folder now puts its workers in a subfolder of it. An app or member may create directly under its own session's folder; the new folder is the agent's, a same-name folder it owns is reused, and the rest of the person's tree stays closed. The session_create preview now runs inside the walk before its first create, checks every segment length and the create budget, and a refused duplicate is audited.
@iamwhatever
iamwhatever force-pushed the fix/agent-folder-dedupe branch from 0dca49d to d5f1328 Compare September 30, 2026 00:01
@github-actions

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

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

Review details

No blocking findings.

FINDING — src/kiro_crew/mcp_dashboard.py:2067 — the preflight refusal returns an already-prefixed f"Error: could not create a session: …", but every other walk error is a bare reason and _resolve_folder_for_new_session wraps it again (redact(f"Error: {fld_err}{made_note}")), so a refused session_create shows the agent Error: Error: could not create a session: … → Fix: drop the Error: prefix from _preflight_create's return and let the single wrapping site add it (line 2087 keeps its prefix — it is returned unwrapped).

FINDING — src/kiro_crew/dashboard/chat_folders.py:459 — api_chat_folders' docstring still states the member contract as "sees only the folders it OWNS" while the new filter also admits str(f.get("id") or "") in home_chain, so the file that defines the member visibility boundary now documents a narrower rule than it enforces → Fix: restate the docstring as owned folders plus the caller's home-folder ancestor chain; the same widening also leaves docs/architecture/mcp.md:1725's "An app may create at the top level or inside a folder it owns" sentence stale against the new parent_id != _slot_home_folder_id(home_slot) allowance.

FINDING — src/kiro_crew/mcp_dashboard.py:2618 — chat_folder_create does its own _post and never reads the new reused flag, so a 200 reuse arm response (existing self-owned sibling, no error key) is rendered as Created folder \…`and the agent records a create that did not happen — the walk at line 1557 handles the same response correctly → Fix: branch ond.get("reused")` and report that the existing folder was reused.

FINDING — src/kiro_crew/dashboard/chat_folders.py:1544 — the reuse early return web.json_response(folder, status=200) sits above the route's sel().log_api_access(..., outcome="allowed", ...), so the one success path that hands an agent a folder id after an ownership test leaves no SEL record, while both the 201 create and the new 409 duplicate denial are audited → Fix: emit the audit line with a distinct source (e.g. reused) before that return.

[OPUS-REVIEWED] d5f1328

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable d5f1328531974c334e3c490613cde13e6bcd36df: <one-sentence reason>

@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 Sep 30, 2026

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

Bulk approve: readiness passed, board green, no outstanding changes requested.

@chenmingwei23
chenmingwei23 merged commit a8d594d into main Sep 30, 2026
99 of 105 checks passed
@chenmingwei23
chenmingwei23 deleted the fix/agent-folder-dedupe branch September 30, 2026 03:45
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 30, 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