Repository navigation
fix: name the cause when pod_up cannot see a scratch worktree - #33254
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the change only rewrites an error that was already being returned, and touches no sandbox scope or contract. Notes
[DESIGN-REVIEWED] 8a57fc7 Description read[DESCRIPTION-READ] 0677055d28901ebc0a0a53263fd43dbd73c6fbca75d767e67fbfca26de09631e 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 |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks. The fix stops at the error message on purpose, because Notes
What this change shipsInventory (8 items) — 6 justifiedIntent: an agent that cannot start a pod on a worktree in scratch learns the cause and how to fix it. This is a FIX.
[FIRST-PRINCIPLES-REVIEWED] 8a57fc7 Description read[DESCRIPTION-READ] 7e97188efde10f08df086988287dda0fea0b56eb9e08d7ca24ce9c39abee9e71 That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
1b5ced8 to
589a66e
Compare
589a66e to
4b29f37
Compare
4b29f37 to
c169e3d
Compare
c169e3d to
26c7e8b
Compare
Dev Fleet runs its git in the agent sandbox, which masks the whole scratch root so one session cannot read another's scratch. A worktree an agent created under $KIROCREW_SCRATCH therefore reads as prunable to that git, discovery drops it, and pod_up, pod_status, pod_restart and pod_down answered a bare "worktree not found" for a worktree that exists. The name lookup now checks, when nothing else matches, for a prunable worktree of that name under the scratch root, and answers with its path and copy-ready commands that recreate it under <repo>/.worktrees/: git worktree remove (which refuses uncommitted work), then git worktree add on the same branch or commit. git worktree move is not offered: in a sandboxed shell scratch is its own mount and the rename fails with EXDEV. The system prompt's scratch rule, the pod_up tool description, and the pod-e2e and kirocrew-worktree-dev skills say a pod worktree goes in <repo>/.worktrees/<name>. The sandbox mask is unchanged.
26c7e8b to
8a57fc7
Compare
bolichen97
left a comment
There was a problem hiding this comment.
Approving. When pod_up cannot find a worktree, _find_worktree now checks whether the name matches a prunable worktree recorded under the scratch root. If so, it names that cause instead of a bare "worktree not found". The lookup runs on the executor and only after the normal lookup has failed. Discovery itself is unchanged: _usable_worktrees keeps the same filter.
The suggested recovery is careful:
test -dcomes first, so a shell that cannot see the path stops beforeworktree removedrops someone else's record.- A detached tree gets a branch first, so a new commit is not orphaned.
- Remove-then-add is used instead of
git worktree move, which fails across the sandbox mount. - Every path and branch goes through
shlex.quote.
The sandbox mask is not touched, and the prompt, skill and tool docs now say to put pod worktrees under <repo>/.worktrees/. The tests cover the scratch match, a normal miss, a detached tree and a dirty-tree refusal. No regex, nothing gets stricter, and all checks are green.
|
Correction to my review above: it wrongly said the tests cover a dirty-tree refusal; they cover the scratch match, the branch case, a real miss and a visible tree, and the approval stands. |
Kiro Crew's built-in Dev Fleet moved on after this tree was cut from main at 6d07df11. An adopted host runs this tree, so each of those changes is carried here first, up to main at 46f62dea: - pod_down waits for the pod's whole stop, and the tool waits 120s (kirodotdev/KiroCrew#33272) - pod_up names a worktree hidden in a session's scratch, and its description says where to create one (kirodotdev/KiroCrew#33254) - the how-to sentence is one message per language (kirodotdev/KiroCrew#33327), rendered by i18nNodes, the bundle's stand-in for the dashboard's <Trans components> - Create worktree from latest stable, with Refresh, in a labelled More actions menu (kirodotdev/KiroCrew#33391), on the page's own MenuBtn - pod_up's test-double env override (kirodotdev/KiroCrew#35199) - provision checks the build input (kirodotdev/KiroCrew#22686), a clean closed worktree can prune (kirodotdev/KiroCrew#31124), the secret comes from the spawn environment (kirodotdev/KiroCrew#34762), every bad-body 400 carries a code (kirodotdev/KiroCrew#32503), and the demo skill's Windows tool lookup (kirodotdev/KiroCrew#33556, #33779) app.json now carries the wheel copy's agentTools block byte for byte, which an adopted record needs for its tools to stay listed (kirodotdev/KiroCrew#33141). The suite runs against Kiro Crew main at 46f62dea, the fixtures match that wheel copy, and PORTING.md records each port. Co-authored-by: Bolin Chen <bolichen@amazon.com>
Problem / Motivation
Goal: When an agent asks Dev Fleet for a pod on a worktree it cannot see because the worktree is in a session's scratch directory, the refusal names that cause and tells the agent where to create the worktree instead.
Agents create worktrees under
$KIROCREW_SCRATCH, as the system prompt tells them to.pod_upon such a worktree answersworktree not found: <name>although the worktree exists, so other Bots cannot start pods and get no hint why.Why it matters
Every agent that follows the prompt's worktree advice and then wants a pod hits this, and the message sends them looking for a typo. The only way out today is to know that a pod worktree must live outside scratch.
Not a goal
What changed (motivation → approach → change)
Symptom:
pod_up wt-stopansweredworktree not found: wt-stopfor a worktree under~/.kiro/crew/scratch/runtime-8bd91637/.Cause: Dev Fleet runs
git worktree list --porcelainthrough the agent sandbox (runtime._run_cmd→sandboxed_spawn_argv). The sandbox masks the whole scratch root (sandbox_leaves), so that git reports any worktree in scratch asprunable gitdir file points to non-existent location, andrepository._discover_worktreesdrops prunable entries. Run through the same sandbox entry point, a worktree in this session's scratch came back prunable and one under<repo>/.worktrees/did not.Change:
repository._find_worktreedev_fleet/scratch_worktrees.pyrepository.pyis already long)mcp_tools/apps.pypod_updescription says to create the worktree under<repo>/.worktrees/<name>config/prompt.md<clone>/.worktrees/<name>pod-e2eskillkirocrew-worktree-devskill$KIROCREW_SCRATCHdocs/system-specs/modules/dev-fleet.mdThe message, for a worktree under scratch on a branch (paths are shell-quoted). A detached one first gets a branch named after it,
git -C <path> switch -c <name> && ..., then is re-added on that branch, so a commit made after the refusal is not orphaned whenworktree removedeletes the tree's HEAD:Why remove-then-add and not
git worktree move: in an agent's sandboxed shell the scratch dir is its own bind mount, so the move's rename fails withInvalid cross-device link.git worktree removewithout--forcerefuses a tree with uncommitted or untracked work, so the command cannot drop work silently; ignored files such as.venvdo not block it.pod_status,pod_restartandpod_downuse the same lookup, so they say the same. A name that is truly missing still answersworktree not found.Why not let
pod_upaccept the calling session's own scratch: the check here is only a lookup.kirocrew pod upitself also runs in the sandbox and reads the checkout, so every pod command would need a window into the caller's scratch, and the pod would break when that session's scratch is reclaimed.builder-security checked: no listener, bind, auth or sandbox scope changes. The scratch check runs in the gateway process and only reads paths git already reported.
Backwards compatibility
Compatible: only the error text of a lookup that already failed changes, and only when the missing name is a worktree under the scratch root.
Removes nothing: no route, field, tool or behaviour is taken away.
Tests
Proof: not provable -- other: prove.py reverts every production hunk at once, including the new module the test imports, so the mutated run fails only at collection; reverting repository.py alone turns test_a_worktree_hidden_by_the_scratch_mask_names_its_cause red
test/test_dev_fleet_scratch_worktree.py:switch -c <name>+worktree remove+worktree add <name>commands, and never the stale head;switch -c, and the message never offersworktree move;shlex.quote, as the code does, so the tests hold on Windows paths;worktree not found;repository.pyreverted tomain, both scratch tests fail and the other two pass.-n0.test_builtin_skill_*,test_prompt_*,test_context.py,test_agent_parts.py,test_agent_fork_templates.py,test_dev_fleet_pod_*,test_dev_fleet_app_guards.py,test_dev_fleet_app_prune.py,test_pod_e2e_harness_paths.py,test_live_checkout.py,test_hook_matcher_modes.py): 704 passed, 1 skipped. The earlier revision also passed all 38test/test_dev_fleet_*files (1,412 passed).scripts/docs-lint.shpass.Manual verification
mainthrough the live gateway: a worktree under this session's$KIROCREW_SCRATCH→pod_up→worktree not found: scr-podrepro.prunable gitdir file points to non-existent location, and<repo>/.worktrees/pod-33124did not.<repo>/.worktrees/pod-33124→pod_up(up on 7902) →pod_status(up health=200) →pod_down(stopped, home reclaimed) →pod_status(down health=0).sandboxed_spawn_argv, standard mode, own scratch as a private window):git worktree move <scratch>/x <repo>/.worktrees/xfailed withInvalid cross-device link;git worktree removerefused a tree with an edited file, removed a clean one that held an ignored.venv, andgit worktree add <repo>/.worktrees/x <branch>then succeeded. The probe worktrees and branches were removed afterwards.main. The test drives_find_worktreewith the porcelain entries git returns.Screenshots / video
N/A - no frontend change.
Related Issues
Closes #33252
Not in this PR: the
pod_downstop timeout is fixed separately in #33272 (issue #33270).Sibling sweep
Swept: git grep -n '_discover_worktrees()|_find_worktree(' -- src/kiro_crew/apps/builtins/dev_fleet
Sibling: src/kiro_crew/apps/builtins/dev_fleet/worktree_ops_pods.py -- not affected -- pod_up, pod_restart, pod_status and pod_down all resolve through _find_worktree, so the fix there reaches them
Sibling: src/kiro_crew/apps/builtins/dev_fleet/repository.py -- not affected -- _valid_worktree_names and the fleet list only list worktrees; a scratch worktree there is the same ghost row git already reports as prunable
Pattern harvest
Not generalizable: the cause is one specific mask (scratch) hiding one specific kind of path (a worktree) from one sandboxed reader; the fix names that pair.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.