Skip to content

fix(worktree): refuse to reuse a worktree that is in use - #19013

Merged
iamwhatever merged 2 commits into
kirodotdev:mainfrom
javenciu:fix/worktree-create-refuses-in-use
Oct 11, 2026
Merged

iamwhatever merged 2 commits into
kirodotdev:mainfrom
javenciu:fix/worktree-create-refuses-in-use

Conversation

@javenciu

@javenciu javenciu commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: "Start in new worktree" never opens a second session in a worktree that another session is using.

POST /api/worktree/create reuses an existing worktree when the derived directory is already registered on the requested branch. The rule exists for one case: a retry after the new session failed to open. The check cannot tell that retry from a second request for the same branch. The follow-up card derives the branch from its title (followupBranchFor in website/src/pages/ChatPage.tsx), reads only path from the answer, and opens a new session scoped to it. So when the same follow-up is offered again, or another session in the repository offers one with the same title, the second press opens a second session in the first session's working tree, with its uncommitted edits and new commits.

Why it matters

Two agents then edit one checkout without knowing about each other. One can overwrite or commit the other's half-done work. The endpoint even marks the answer reused: true, but nothing in the client reads that field (git grep -n reused -- website/src/pages/ChatPage.tsx website/src/api/client/files.ts finds only two retry messages and an unrelated comment).

Not a goal

  • A website change. The card already shows the error of a 409 inline. Its copy after a failed session switch says "Switch to it in the sidebar, or press the button again"; pressing again now returns the 409 that says a session is open there, instead of opening a second session.
  • Two presses before the first session exists. The server cannot tell them from a retry without a request id from the client, and the card ignores a press while one is in flight (busyIndex in website/src/components/FollowUpCard.tsx).
  • Files the repository ignores (.gitignore) do not count as changes.
  • The spec builder's _create_worktree (src/kiro_crew/apps/builtins/spec_builder/backend/repository.py) and the task runner's init_workspace (src/kiro_crew/git_coord.py) never reuse a worktree: they refuse an existing path or branch, so they do not have this rule.

What changed (motivation → approach → change)

  • Symptom: a second request for a branch whose worktree another session uses gets 200 with reused: true, and the client opens a second session in that tree.
  • Root cause: _create_worktree_sync in src/kiro_crew/dashboard/handlers/worktree.py treats "the path is registered on this branch" as proof of a retry. A retry's tree is untouched by construction, because the failed session never ran; the check never looks at the tree.
  • Change: a new helper, _worktree_in_use, runs before a reuse. It screens the worktree's own config for a filter driver with the existing _checkout_filter, runs git --no-optional-locks status --porcelain --ignore-submodules=all in the worktree (no index lock is taken, and no recursion into submodules), and counts the branch's commits beyond the base with git rev-list --count <base>..refs/heads/<branch>. Any change, any such commit, or any probe git cannot answer refuses the reuse. An advanced base still reuses an untouched tree, because its old tip is then an ancestor.
  • Change: --ignore-submodules=all on that status. _checkout_filter screens only the superproject's config, so without it the recursive status would run a content filter a submodule declares in its OWN config (.git/modules/<name>/config), which git status executes to compare a modified tracked file — repository-controlled code the superproject screen never saw. A fresh worktree add does not check submodules out, and a session that advanced a submodule POINTER did so in a commit the branch-ahead count still catches, so ignoring submodule working state loses no signal this check needs.
  • Change: api_worktree_create also refuses a reuse when a session is already scoped to the worktree or to a directory inside it. That catches a session that opened and has not changed anything yet. It compares against the realpath'd slot projects the handler already collects for its allow-list.
  • Change: both refusals are a 409 built by a new helper, _in_use_refusal, with code: worktree_in_use and an error that names the reason and says to continue in the session working there.
  • Change: docs/architecture/followup-suggestions-trust-model.md states the rule.
  • Rejected: reading reused in the client. Only the server can see the tree and the sessions, and it would be a website change.
  • Rejected: a fresh path or a suffixed branch on a conflict. The card names its branch, and a retry would then make a new worktree on every press.

Backwards compatibility

Compatible: a retry on an untouched worktree is still reused, pinned by test_our_own_worktree_at_the_destination_is_reused and test_an_untouched_worktree_is_reused_on_retry. A fresh create is unchanged. The 409 body keeps the error key the card reads and adds code. The only caller is the follow-up card: git grep -n "worktree/create" -- src website/src finds the route, the handler docstrings and api.createWorktree.

Removes nothing: a 200 for a worktree in use becomes a 409; no route, key or retry path is removed.

Not a reuse signal: a submodule's own working-tree state. The probe ignores submodules (--ignore-submodules=all), so a reused worktree is judged by its superproject tree and its branch commits, not by edits inside a submodule's nested checkout. A session's real work still shows as a superproject edit or a branch commit.

Tests

Added to test/test_dashboard_worktree_coverage.py (the sync_env fixture gains programmable status, ahead and dest_filter probes):

  • TestCreateWorktreeSync::test_the_retry_inspects_the_tree_without_writing_its_index: the retry still answers reused, and the probes run as --no-optional-locks status --porcelain --ignore-submodules=all in the worktree and rev-list --count <base>..refs/heads/<branch> in the repository.
  • test_a_reused_worktree_with_uncommitted_changes_is_a_409 and test_a_reused_worktree_whose_branch_has_new_commits_is_a_409: refused with worktree_in_use; the worktree and branch are not touched.
  • test_a_reused_worktree_git_cannot_inspect_is_a_409 (5 cases): a filter in the worktree's config, a failed status, an unresolvable base, a failed rev-list, and unparseable output.
  • TestCreateWorktreeSyncRealGit (3 tests): real git on a synthetic repository, with only the OS-sandbox wrapper replaced by a plain git call. An untouched worktree is reused on retry; one with uncommitted edits, and one holding another session's commits, are refused.
  • TestWorktreeInUseIgnoresSubmodules::test_the_reuse_probe_does_not_run_a_submodule_filter: a real superproject with an initialized submodule whose own config declares filter.evil.clean (its driver touches a marker file) and a modified tracked file. The reuse probe's status must not run that filter. With only the OS-sandbox wrapper replaced by a plain git call, _worktree_in_use is driven directly: on the base (b2b49857ae, no --ignore-submodules) the recursive status creates the marker (AssertionError: the reuse probe recursed into the submodule and ran its clean filter), red in 3 of 3 runs; with the fix the marker is never created and the superproject tree reads as reusable, green in 3 of 3 runs.
  • TestEndpointCreateOutcomes::test_a_reused_worktree_open_in_a_session_is_refused (3 cases): a session scoped to the worktree or to a directory inside it gets the 409, audited as an error; with no such session the reuse is returned.

Before the fix (on origin/main 3dc503d, with only this test file copied in: pytest -n 0 test/test_dashboard_worktree_coverage.py -k "inspects_the_tree or uncommitted or new_commits or cannot_inspect or RealGit or open_in_a_session or our_own_worktree"), RC=1 in 3 of 3 serial runs:

E       AssertionError: assert (['--no-optional-locks', 'status', '--porcelain', '--ignore-submodules=all'], '<tmp>/proj-wt-x') in []
E       assert 200 == 409
12 failed, 3 passed, 126 deselected

The three that passed are the controls: the untouched retry, at the unit level and with real git, and the endpoint with no session on the worktree.

After the fix, RC=0: test/test_dashboard_worktree_coverage.py 141 passed in 3 of 3 serial runs; the six test files that name the module 419 passed, 8 skipped. The 8 skips are git-version checks in test/test_git_config_hooks.py (6, git < 2.54) and test/test_governance_updates.py (2); test/test_worktree_create.py runs whole here (91 passed), including test_retry_reuses_our_own_worktree through the real sandboxed spawn. mypy, flake8 and isort are clean, black is clean on worktree.py (the test file is in .github/black-baseline.txt), and scripts/check_black_formatting.py, scripts/check_subprocess_encoding.py (the real-git helper pins encoding="utf-8"), scripts/docs-lint.sh and scripts/check_comment_history.py (with COMMENT_HISTORY_BASE_REF=origin/main) pass.

Manual verification

No UI change. TestCreateWorktreeSyncRealGit drives _create_worktree_sync with real git output on a synthetic repository, including a second session's edits and commits in the worktree.

Related Issues

None found. The reuse rule comes from #461. Open #17169 and #17628 touch other hunks of worktree.py (the non-repo message and _run_git). Open #19012 edits the same reuse branch of _create_worktree_sync: it refuses a worktree whose git worktree add never finished, and reads the worktree list with each entry's lock state instead of only its branch. The two conflict in that one hunk. Whichever lands second keeps both checks: the unfinished-add refusal first, then this change's in-use check (_worktree_in_use, _in_use_refusal) before the reuse is returned.

Pattern harvest

Rule candidate: review-prompt
Pattern: an idempotent retry keyed only on a resource's identity (here a path and a branch name) must also check that the resource is still in the state the failed attempt left it; otherwise it hands one resource to two owners.

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): docs/architecture/followup-suggestions-trust-model.md
  • No secrets, credentials, or internal references in the diff

@javenciu
javenciu requested review from a team and KiroCrewCaptain as code owners October 11, 2026 02:22
@javenciu
javenciu requested a review from buluoray October 11, 2026 02:22
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 11, 2026
@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

Revision 758e2749dc29992ab4bd0456acd670cab31537e4 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 Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 758e2749dc29992ab4bd0456acd670cab31537e4 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 whether a closed or idle chat slot stays in state._slots. If it does, it still counts as "a session open in it" and the card gets a 409 on every press.

[DESIGN-REVIEWED] 758e274

Description read

[DESCRIPTION-READ] ca14130ea7f469641aac54a2721265e0090b31a8d3ef4631e3051862e7d02ebe

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

Copy link
Copy Markdown
Contributor

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

Premise-level review of 758e2749dc29992ab4bd0456acd670cab31537e4 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

The new code: worktree_in_use key has zero readers: the card reads only error, so the field is surface nobody uses.

Not justified as shipped

  • Item 4 — zero consumers: the description says the 409 "keeps the error key the card reads and adds code". Grepping worktree_in_use across src and website/src finds only the defining site and tests: 0 consumers. Its only precedent, worktree_mkdir_failed (worktree.py:695), also has 0 non-test consumers.
    Subtraction: drop "code": "worktree_in_use" from _in_use_refusal and return just {"error": ...}, 409.
    Clears when: the key is removed, or a client in website/src branches on it.

What this change ships

Inventory (6 items) — 5 justified

Intent: stop "Start in new worktree" from opening a second session in a worktree another session is using. FIX.

  1. Pressing again on a worktree with uncommitted edits or new branch commits now gets a 409 instead of being reused — justified
  2. Pressing again while a session is open in the worktree, or in a directory inside it, now gets a 409 — justified
  3. A worktree git cannot inspect (filter in its config, failed status or rev-list) counts as in use — justified
  4. The 409 body carries a new code: worktree_in_use field — zero consumers: nothing reads it
  5. The reuse probe's status skips submodules, so a submodule's own filter never runs — justified
  6. The trust-model doc states the reuse-only-when-untouched rule — justified

[FIRST-PRINCIPLES-REVIEWED] 758e274

Description read

[DESCRIPTION-READ] c00bf135bb935f5de54b3548fdc453cf82015077ae66c9b19c68cfcb6cefa314

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 758e274

@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

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

Review details

FINDING -- src/kiro_crew/dashboard/handlers/worktree.py:662 -- With status.showUntrackedFiles=no, "--porcelain" hides non-ignored untracked files; an otherwise clean worktree with no open session passes both reuse checks, contradicting the untouched-tree guarantee (recurring-defect-patterns) -> Fix: add --untracked-files=all to this status invocation.
[GPT-REVIEWED] 758e274

@javenciu

Copy link
Copy Markdown
Contributor Author

Thanks, the finding holds. Fixed in a second commit, fe882f5, on top of 01883fc.

  • The @pytest.mark.skipif(shutil.which("git") is None, ...) on TestCreateWorktreeSyncRealGit is removed, together with the import shutil only it used (test/test_dashboard_worktree_coverage.py). The class now always runs. A host without git fails these three tests by name instead of skipping them, and every CI job here has git.
  • No source change, and the description is unchanged: it never described the skip.

Runs on fe882f5:

  • test/test_dashboard_worktree_coverage.py: 140 passed in each of 3 serial runs.
  • Red on main 2ada192, this test file copied in, with the description's -k: 12 failed, 3 passed in each of 3 runs, as the description states.
  • The six test files that name the module: 418 passed, 8 skipped. The skips are the git-version checks in other files that the description already names; this change adds none.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Oct 11, 2026
@javenciu
javenciu force-pushed the fix/worktree-create-refuses-in-use branch from fe882f5 to 55ff463 Compare October 11, 2026 03:38
@javenciu

Copy link
Copy Markdown
Contributor Author

Thanks, the finding holds. I reproduced it before fixing: a scratch superproject with an initialized submodule whose own config set filter.evil.clean (its driver touches a marker file) and a modified tracked file. Running the reuse probe's exact invocation, git -c core.hooksPath=… -c core.fsmonitor=false --no-optional-locks status --porcelain in the superproject, created the marker — the recursive status ran the submodule's clean filter. _checkout_filter (src/kiro_crew/dashboard/handlers/worktree.py:451) reads only the superproject's --local/--worktree config, so a driver in .git/modules/<name>/config is never screened.

Fix: _worktree_in_use's status probe now passes --ignore-submodules=all (src/kiro_crew/dashboard/handlers/worktree.py:662), so git never recurses into a submodule and never runs its filter.

I chose "do not recurse" over "screen each submodule's filters" because the in-use check holds without recursion. It asks whether the SUPERPROJECT worktree is as worktree add left it: a clean superproject tree and a branch with no commit beyond its base. A fresh worktree add does not check submodules out, so an untouched retry tree has no submodule working state at all. A session that advanced a submodule POINTER did so in a commit, which the branch-ahead count (git rev-list --count <base>..refs/heads/<branch>) still catches. Screening every initialized submodule recursively would be more code and would still have to read each submodule's config safely; ignoring submodule working state is smaller and loses no signal this check needs.

Red: test/test_dashboard_worktree_coverage.py::TestWorktreeInUseIgnoresSubmodules::test_the_reuse_probe_does_not_run_a_submodule_filter drives the real _worktree_in_use against that superproject, with only the OS-sandbox wrapper replaced by a plain git call, and asserts the marker file is never created. On the base it fails in 3 of 3 runs (AssertionError: the reuse probe recursed into the submodule and ran its clean filter); with the fix it passes in 3 of 3, and the superproject tree reads as reusable. The six worktree test files pass (419 passed, 8 skipped), including the probe's command-pinning test, updated to the new argv.

Scope: this addresses the blocking submodule-filter execution. The separate non-blocking note about status.showUntrackedFiles=no is not changed here; the reuse probe's untracked-file behaviour can be tightened in a follow-up.

@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 11, 2026
"Start in new worktree" reused the existing worktree for any request
whose branch already had one at the derived path. The rule exists for
a retry whose session never opened, but it also matched a second
request for the same branch, so the card offered again put a second
session into a tree another session was working in, uncommitted edits
and new commits included.

_create_worktree_sync now reuses the tree only while it is exactly as
"worktree add" left it: a new helper, _worktree_in_use, checks that
"git status --porcelain" is empty and that the branch has no commit
beyond the base, and refuses when either probe cannot answer. The
endpoint also refuses when a session is already scoped to the tree or
to a directory inside it. Both answers are a 409 with code
worktree_in_use, built by _in_use_refusal, which the card shows
inline. The follow-up trust-model doc states the rule.
The in-use probe's `git status` recursed into submodules, so a content
filter a submodule declares in its own config (.git/modules/<name>/config)
ran to compare a modified tracked file. `_checkout_filter` screens only the
superproject's config. The probe now passes --ignore-submodules=all: the
in-use check asks whether the superproject tree and branch are as
`worktree add` left them, and a fresh add checks no submodule out.

The real-git reuse checks also run without a skip: a newly added skipif
loosened the test file's ratchet, and every CI host has git. A new test
drives the real probe against a superproject whose submodule declares a
filter, and asserts its marker file is never written.
@javenciu
javenciu force-pushed the fix/worktree-create-refuses-in-use branch from 55ff463 to 758e274 Compare October 11, 2026 07:59
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention 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 11, 2026

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

This PR fixes "Start in new worktree" so it no longer hands one worktree to two sessions. Before, POST /api/worktree/create reused any registered worktree on the same branch. Now it reuses one only when the tree is as worktree add left it, and it answers 409 worktree_in_use when the tree has uncommitted changes, when its branch has commits beyond the base, or when a slot is already scoped to the tree or a directory inside it. That is the root cause, because the old check treated "path is registered on this branch" as proof of a retry. I read the full production diff in dashboard/handlers/worktree.py and tried to break it. Every probe that git cannot answer fails closed. The filter screen runs before status, and --ignore-submodules=all stops a submodule's own clean filter from running; the real-git test reproduces that filter running on base. The branch is validated by is_valid_followup_branch before it reaches rev-list. The base ref comes from the same _resolve_base_ref the create path cuts from. The slot-prefix check adds os.sep, so proj-wt-x2 does not match proj-wt-x. Base is main, all checks are green, and there are no change requests. Two notes, neither blocking: the First Principles CONCERNS about the zero-reader code key still has no disposition, and a repo with status.showUntrackedFiles=no would hide a closed session's untracked files from the probe (adding --untracked-files=normal is a one-line follow-up). — crew-pr-reviewer (deep re-check)

@iamwhatever
iamwhatever merged commit fd19f6e into kirodotdev:main Oct 11, 2026
104 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 11, 2026
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.

2 participants