Repository navigation
feat(crew): run each crewmate's worker in its own git worktree - #23563
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
First Principles Review (Opus 5.5) — ✅ human override accepted@buluoray overrode this lane for |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the gateway does only the git steps a model can't (make, start in, remove the worktree), and every fallible path leaves the turn on its old project. Notes
[DESIGN-REVIEWED] b5c398b Description read[DESCRIPTION-READ] f628e61897e4a801544d14b3572e19be6d095fd73efd6aa28596e2f95c904b04 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 |
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 findings (all downgraded on adjudication)GPT 6.1 flagged blocking issues on This comment is updated in place on each push. Review detailsBLOCKING -- src/kiro_crew/dashboard/crewmate_worktree_scope.py:95 -- Defer relocated turns until the worktree reset succeeds
Adjudication (Opus 5.5) — is blocking on each finding proportionate?F1: DOWNGRADE. Harm rung LOW–MEDIUM. Three things must all be true at once: a warm worker provider ( False positive or not applicable? A repository writer can comment: |
682cfa7 to
4cea3db
Compare
4cea3db to
963e809
Compare
|
/ai-review override first-principles 963e809: Product decision by the maintainer (buluoray): every crewmate worker runs in its own git worktree by default, so parallel workers never edit the same checkout. |
Human judgment recorded@buluoray marked the first-principles AI finding as false positive, not applicable, or explicitly accepted for
This decision applies only to this commit. A new push requires a new judgment. |
963e809 to
dc4f0ff
Compare
|
/ai-review override first-principles dc4f0ff: Product decision by the maintainer (buluoray): every crewmate worker runs in its own git worktree by default; an unpushed, clean branch with no PR is the only one rebased automatically. |
Human judgment recorded@buluoray recorded a legacy release (class
This decision applies only to this commit. A new push requires a new judgment. |
|
This override used the old command without a class. It was recorded as class |
Human judgment recorded@buluoray recorded a legacy release (class
This decision applies only to this commit. A new push requires a new judgment. |
|
This override used the old command without a class. It was recorded as class |
|
/ai-review override first-principles e13fe6d: Product decision by the maintainer (buluoray): every crewmate worker runs in its own git worktree by default; the gateway never rebases a crewmate branch and only tells the worker, read-only, how far the default branch moved. |
Human judgment recorded@buluoray recorded a legacy release (class
This decision applies only to this commit. A new push requires a new judgment. |
|
This override used the old command without a class. It was recorded as class |
|
/ai-review override first-principles f402ddd: Product decision by the maintainer (buluoray): every crewmate worker runs in its own git worktree by default; the gateway never rebases a crewmate branch and only tells the worker, read-only, how far the default branch moved. |
Human judgment recorded@buluoray recorded a legacy release (class
This decision applies only to this commit. A new push requires a new judgment. |
|
This override used the old command without a class. It was recorded as class |
|
/ai-review override first-principles 5208954: Product decision by the maintainer (buluoray): every crewmate worker runs in its own git worktree by default; the gateway never rebases a crewmate branch and only tells the worker, read-only, how far the default branch moved. |
Human judgment recorded@buluoray recorded a legacy release (class
This decision applies only to this commit. A new push requires a new judgment. |
|
This override used the old command without a class. It was recorded as class |
|
/ai-review override first-principles eada1cc: Product decision by the maintainer (buluoray): every crewmate worker runs in its own git worktree by default; the gateway never rebases a crewmate branch and only tells the worker, read-only, how far the default branch moved. |
Human judgment recorded@buluoray recorded a legacy release (class
This decision applies only to this commit. A new push requires a new judgment. |
|
This override used the old command without a class. It was recorded as class |
|
/ai-review override first-principles fc74e16: Product decision by the maintainer (buluoray): every crewmate worker runs in its own git worktree by default; the gateway never rebases a crewmate branch and only tells the worker, read-only, how far the default branch moved. |
Human judgment recorded@buluoray recorded a legacy release (class
This decision applies only to this commit. A new push requires a new judgment. |
|
This override used the old command without a class. It was recorded as class |
|
/ai-review override first-principles f64edbe product-shape: Product decision by the maintainer (buluoray): every crewmate worker runs in its own git worktree and branch by default. The gateway only makes that worktree, points the worker's turn at it, and removes it with the crewmate; it never rebases, and the worker manages its own branches and rebases from its prompt. |
|
AI-review override not recorded: |
Two crewmates handed one repository shared its checkout: one committed the other's edits, or landed a commit on the branch the other had checked out. The gateway now does only what a model cannot do for itself: 1. Gives each crewmate one worktree per repository, at <workspace>/worktrees/<slug>/<repo>-<hash>, on crew/<slug>/<repo>, cut from the default branch the first time and reused after that. 2. Points a worker turn's slot.project at it, from the paths the turn names or the slot's project, before the provider is claimed. The repository's aws.project_profiles binding still applies there: a cwd in a crewmate worktree is matched as the same path in the checkout, asked of git each time (source_path), so it holds after a restart. 3. Removes those worktrees when the crewmate is deleted, keeping one with uncommitted or ignored files; branches and the repository's own checkout are never touched. Git runs through the follow-up card's sandboxed runner (no hooks, no fsmonitor, checkout filters refused), and the folder is made and unwound through no-follow descriptors. Topic branches, rebasing onto the default branch and checking with merge-tree before a push are the worker's own, asked for in worker.principles.
|
/ai-review override first-principles b5c398b product-shape: Product decision by the maintainer (buluoray): every crewmate worker runs in its own git worktree and branch by default. The gateway only makes that worktree, points the worker's turn at it, and removes it with the crewmate; it never rebases, and the worker manages its own branches and rebases from its prompt. |
|
AI-review override not recorded: |
|
Owner decision (buluoray), recorded for the First Principles review. Every crewmate's worker runs in its own git worktree and branch by default, with no switch to turn it off. This is a deliberate product shape, decided by the maintainer; there is no separate RFC for it. The gateway keeps only what a model cannot do for itself:
It never rebases a crewmate branch. Branch naming beyond the first branch, rebasing onto the default branch and pre-push conflict checks are the worker's job, from its prompt. |
|
/ai-review override first-principles b5c398b owner-decision: Per-crewmate worker worktrees are the maintainer's product decision, recorded at #23563 (comment) ; the gateway only makes the worktree, points the turn at it and removes it with the crewmate. |
Human judgment recorded@buluoray recorded a owner-decision release (class
This decision applies only to this commit. A new push requires a new judgment. |
Problem / Motivation
Goal: Each crewmate's worker works in the crewmate's own git worktree and branch, so two crewmates handed the same repository never edit one checkout or one branch.
With Crewmate 2.0 (#23010) every crewmate hands its work to a worker, but the worker runs wherever its session's project points, usually the repository's shared checkout. Two crewmates working in one repository then edit the same working tree and commit on whatever branch happens to be checked out, so their changes mix and one can move the branch under the other.
Why it matters
Anyone running more than one crewmate on a repository gets tangled commits and lost or overwritten work, and has to keep each crewmate out of the others' way by hand. A worktree per crewmate keeps each one's changes on its own branch, and the user's own checkout stays as they left it.
Not a goal
crew/<slug>/prefix is asked for in the prompt, not refused by the gateway.What changed (motivation → approach → change)
Goal → the gateway does only the three git jobs a model cannot do for itself (make the worktree, start the worker in it, remove it with the crewmate) → every other git step is the worker's own, asked for in its prompt. Git runs through the follow-up card's sandboxed runner (
handlers/worktree._run_git: no hooks, no fsmonitor, checkout filters refused), and the turn reuses the existing project/binding re-capture.kiro_crew/crewmate_worktree.py,ensure). It lives at<crewmate workspace>/worktrees/<crewmate slug>/<repo>-<hash>(one rule, no fallback), oncrew/<slug>/<repo>, cut the first time from the repository's default branch (refs/remotes/origin/HEAD, elserefs/heads/mainormaster, elseHEAD; full ref names, so amaintag is never the base) and reused as it is after that, on whatever branch the worker checked out. Reuse is read fromgit worktree list; there is no index. A folder deleted by hand is pruned and made again on the branch; a folder git does not register is refused. A name the cleaning changed (app+tools,app.lock,app..tools) or one over 40 characters keeps a digest and is a legal ref component. A repository that contains the crewmate's own workspace gets none. The folder is made through no-follow descriptors from the workspace down; aworktree addthat fails or times out removes that folder by descriptor only while its(dev, ino)still matches, then drops the branch it cut.dashboard/crewmate_worktree_scope.py, called fromchat_turn/turn_admission.pyafter the Profile Permissions are seeded and before the provider is claimed). For akirocrew-mate-workerrecord with the crewmate's id, the repository comes from the paths the message names (absolute,~, or drive paths only on Windows; a quoted one read whole; a file not made yet read from its nearest folder), then from the slot's project.slot.projectmoves to the matching subfolder of the worktree (the root when that subfolder is a link out, or holds a control character or bracket). A path in the worktree it already runs in, or in that repository's own checkout, moves nothing. A running session takes the same deferred resetset_projectuses. A git failure, or no sandbox, leaves the turn on its project. The repository'saws.project_profilesbinding still applies in the worktree:crewmate_worktree.source_path, called fromaws_project_profiles.resolve_project_binding, matches a cwd in a crewmate worktree as the same path in the checkout (<workspace>/worktrees/<slug>/app-<hash>/srcas/repos/app/src). It asks git each time and remembers nothing, so it holds after a restart, and applies only when git's work-tree top sits atworktrees/<slug>/, has the namepath_forgives that repository, and is registered by it. Anything else, a repository cloned inside the worktree included, matches as itself; a path with noworktreesfolder runs no git.dashboard/agent_admin/crew_removal.py→remove_for_member). Each folder under<workspace>/worktrees/<slug>that git registers as a worktree is removed withgit worktree remove(never--force). One with uncommitted changes, ignored files or a checkout filter is kept and logged, and so is anything git does not register. Branches stay; the repositories' own checkouts are never touched.crewmate_prompts.json,worker.principles): commit in the worktree and never in the repository's own checkout, name further branches undercrew/<crewmate>/, rebase onto the default branch yourself when you need its changes, and rungit merge-tree --write-tree <base> HEADbefore a push. The conductor's worker line says the worker works in its own worktree under thecrew/prefix.Spec:
docs/system-specs/modules/crew-mode.md("Each crewmate works in a git worktree of its own", and the conductor/worker prompt lines),docs/system-specs/modules/config.md("Crewmate worktrees" under Project AWS profiles).Backwards compatibility
Compatible: a worker turn whose paths are in no git repository runs where it did before, and a git failure leaves the turn on its current project. The gateway never rewrites a worker's branch after cutting it. Conductor chats and non-crewmate sessions are untouched.
aws.project_profilesmatches every path outside a crewmate worktree exactly as before.Removes nothing: the change adds worktrees, prompt lines and a cleanup step on crewmate deletion; the cleanup removes only worktrees git registers under the crewmate's own folder, and keeps any with uncommitted or ignored files.
Tests
test/test_crewmate_worktree.py, job 1: two crewmates (also two sharing a workspace) get separate worktrees and branches; a worktree is reused as the worker left it, a topic branch included, and another crewmate's path maps to your own; a path in no repository, a bare repository and a repository containing the workspace get none; a not-yet-made file maps to its nearest folder; a linked or untracked subfolder gives the root and a bracketed one is not the project;app.lock,app..tools,.hiddenpassgit check-ref-format --branch; names that clean alike and long slugs stay apart; the cut ismainwhile the checkout sits on a feature branch,origin/HEADwhen there is one,HEADwith no default branch, and never amaintag; a folder deleted by hand is rebuilt on its branch with its commit; an unregistered folder, an unlistable worktree table, a checkout filter and an empty repository are refused; a timed-out add leaves no branch or folder, a failed add keeps a branch it did not cut, a failed add with the parent swapped for a link to the crew home removes nothing there, and a linkedworktrees/<slug>gets nothing made through it; quoted paths with spaces, drive paths, the path cap, and paths on different drives.~path into its own worktree or a path in the repository's checkout moves nothing and resets nothing; a brief naming a new file in another repository moves the turn there; a move resets a running session and survives a failed push; a drive path on a POSIX gateway whose cwd is a checkout makes nothing. End to end, a real worker turn throughchat_runner._run_chatclaims its provider with cwd in the crewmate's worktree. AWS profile: a mapped repository's binding applies at the worktree root, in a subfolder and in a not-yet-made folder, and the workspace's own binding never stands in for it; an unmapped repository's worktree gets the caller's env back untouched; a worktree an earlier gateway made (plain git, nothing in this process) is still mapped, and again after it is reused; a nested clone, an unregistered look-alike folder, a copied.git, a worktree outsideworktrees/<slug>/, one moved to a wrong name and one beside the repository all match as themselves; an ordinary path runs no git and no sandbox leaves the path alone;SessionManager.get_or_createin the worktree starts the agent with the repository's profile. Dropping the source mapping, the registration, name or layout check, the no-git filter or the subfolder mapping each turns a test red.remove_for_membernever raises. End to end,api_kirocrew_agent_deleteremoves the clean crewmate's worktree and keeps the dirty one.test/test_agent_refactor_spec_bytes.py(the worker spec's prompt) and theall-metprompt preview golden (the two changed lines only).Proof: not provable -- other: new feature, the new tests exercise code this pull request adds
Manual verification
N/A — unit coverage drives real git in temporary repositories, through the sandboxed runner where the host has a backend and plain git otherwise (the Linux CI runners have none, so the tests no longer skip there; Windows keeps the skip). Run locally both ways, with
TMPDIRoutside the crew data home.Related Issues
Follows #23010.
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.