Skip to content

feat: Suggest worktrees made outside HomeShell as workstreams - #7

Merged
planger merged 13 commits into
mainfrom
homeshell-untracked-worktrees
Nov 13, 2026
Merged

planger merged 13 commits into
mainfrom
homeshell-untracked-worktrees

Conversation

@planger

@planger planger commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

What and why

At the moment, HomeShell only notices a worktree made outside HomeShell (with git worktree add
or another tool) when a session happens to run in it, and then shows it as a workstream without a
branch. With this change, the project view lists the linked worktrees of the project's repository
that no workstream works in as untracked worktrees under Separate folders, and Add turns one
into a worktree workstream like one HomeShell created. HomeShell never adds one on its own. A
worktree workstream also goes away when its worktree is removed outside HomeShell.

Second of three stacked PRs, based on #6. Again three commits: daemon, UI and e2e tests.

To try it, run git worktree add ../wt-try -b wt-try in a project's repository. Within the
refresh interval, 1 untracked worktree shows under Separate folders, and Add (or Enter on its
row) makes a workstream of it. git worktree remove ../wt-try removes the workstream again.

Changelog

- Worktrees made outside HomeShell show under Separate folders as untracked worktrees, and Add (or
  Enter on its row) adds one as a workstream.
- A worktree workstream goes away when its worktree is removed outside HomeShell. If an agent is
  still running in it, HomeShell stops nothing: the workstream stays, says its folder is gone,
  and goes once its sessions end, or when you delete it.

Checklist

  • Tests added: unit and e2e, or a regression test for a bug fix (see AGENTS.md)
  • Docs updated per the trigger table in AGENTS.md

@EclipseSourceAI EclipseSourceAI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note

Autonomous AI review. May contain mistakes.

Useful comment? React 👍. Disagree? React 👎 to reject it for follow-up reviews. A reply explaining why helps too.

This agent never approves PRs. A maintainer must sign off.

Only a maintainer can re-request a review from this agent.

Powered by Eclipse Enclave via review-guard-mcp

This PR has the core provider survey git worktree list for each git project on every refresh tick (FolderSurveyor, listingCache, Reconciler.foldersChanged). Linked worktrees that no project or workstream claims show up as untrackedWorktrees on the project, and POST /worktree-workstreams turns one into a worktree workstream without touching the disk (TrackFolder). A core worktree workstream whose worktree git no longer lists, or whose folder was deleted, is retired in the background as a forced Remove that keeps files (Service.retireVanished). The UI puts a fold under Separate folders that you can reach with the arrow keys.

Where to focus

  • Concurrency in the reconcile/store path. Several mechanisms work together here: the firstSeen freshness stamps, HoldClaim, unprojectedRemovals and handOverTakenSuggestions. The docs cover them well. They are where a regression would hide.
  • Two behavior changes, raised inline:
    • Sessions in an untracked worktree are now hidden and never notified. Before this PR they got an adopted workstream.
    • Retiring a workstream force-stops its busy sessions.
  • Keyboard navigation (inline). The fold and the Add buttons break the list's one-tab-stop convention.

Visual check: a Playwright run against a -demo daemon showed this working end to end. The fold appeared within the refresh interval. Add by click and by Enter on the row both created the workstream. git worktree remove made the workstream disappear. There were no console errors. A small cosmetic point: when the name and the branch are the same, the row shows them twice ("wt-try wt-try").

The docs lint passes. I could not run the Go and vitest suites here.

Path string `json:"path"`
SessionCount int `json:"sessionCount"` // Sessions not ended; derived by Recompute
// Sessions are the ones reported in the folder, hidden until it is added.
Sessions []Session `json:"-"`

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sessions on a suggestion never reach a client, and notify only walks project.Workstreams (notify.go), so an agent waiting for input in an external worktree now goes silent, where before this PR its adopted workstream showed and notified it. On upgrade an existing adopted workstream in such a folder is dropped too, so a maintainer should confirm that trading visibility for "never add on its own" is intended. If it is, sessionCount should at least flag a waiting session.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch, thanks! This is handled in #8.

Comment thread daemon/internal/provider/service.go Outdated
}
slog.Info("removing a workstream whose worktree is gone",
"project", ref.ProjectID, "workstream", ref.WorkstreamID, "dir", workstream.WorkingDir)
err = s.removeWorkstream(detached, ref, workstream, RemoveOptions{Force: true, KeepFiles: true})

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Force: true stops busy sessions with no one asking. Case: an agent (or the user) runs git worktree move on a worktree a session is running in. The old path drops out of the listing, the workstream is retired and the session killed, though its folder still exists under the new path (which then shows up as untracked). Retiring only when the workstream has no live sessions, or leaving busy ones to a manual Remove, would avoid that.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch! Changed in b19f551: HomeShell no longer stops sessions when a worktree vanishes. If every session in it has already ended (or failed), the workstream is removed as before. Otherwise it stays listed with its sessions and is marked as folderMissing, so the card says its folder is gone. A later pass removes it once its sessions have ended, and Remove still works earlier, with the usual busy-session guard. As it stays listed, it keeps holding its folder's sessions, so they aren't adopted back.

type="button"
className={foldStyles.foldButton}
aria-expanded={expanded}
data-nav-id="untracked-worktrees"

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The fold and every Add button stay in the Tab order, so the list now has several tab stops. Focusing the fold or a row also resets the list's stop (placeTabStop knows no untracked-worktrees id), so after arrowing down there and tabbing away, Tab from above comes back to the first card, not where the user left off. The session list's fold and row controls use controlTabIndexFor to keep one tab stop (session-list.tsx, list-navigation.ts). The fold and its rows should follow that.

@planger
planger force-pushed the homeshell-untracked-worktrees branch from ece4c65 to 9fe34ce Compare November 12, 2026 15:40
planger added a commit that referenced this pull request Nov 12, 2026
The fold and every Add button were tab stops of their own, and focusing
the fold or a row put the list's stop back on the first card. The fold
and its rows now take part in the roving tab stop (useListTabStop's
trailing items), and an Add takes Tab only from its row, as a card's
controls do.

Review: #7 (comment)
planger added a commit that referenced this pull request Nov 12, 2026
A row showed both the name and the branch, so a worktree named after
its branch read "wt-try wt-try". The branch now shows only when it
differs from the name; a detached one still says so.

Review: #7 (review)
planger added a commit that referenced this pull request Nov 12, 2026
The copy-path button of each row was still a tab stop of its own. It
now takes Tab only from the row holding the list's stop, as the row's
Add does and as a card's copy button does.

Review: #7 (comment)
planger added a commit that referenced this pull request Nov 12, 2026
The fold and every Add button were tab stops of their own, and focusing
the fold or a row put the list's stop back on the first card. The fold
and its rows now take part in the roving tab stop (useListTabStop's
trailing items), and an Add takes Tab only from its row, as a card's
controls do.

Review: #7 (comment)
planger added a commit that referenced this pull request Nov 12, 2026
A row showed both the name and the branch, so a worktree named after
its branch read "wt-try wt-try". The branch now shows only when it
differs from the name; a detached one still says so.

Review: #7 (review)
@planger
planger force-pushed the homeshell-untracked-worktrees branch from 53880ce to 7725092 Compare November 12, 2026 17:05
planger added a commit that referenced this pull request Nov 12, 2026
The copy-path button of each row was still a tab stop of its own. It
now takes Tab only from the row holding the list's stop, as the row's
Add does and as a card's copy button does.

Review: #7 (comment)
planger added a commit that referenced this pull request Nov 12, 2026
A worktree workstream whose folder vanished was retired at once, its
sessions force-stopped, so a `git worktree move` under a working agent
killed it. Now one with a session not yet terminal stays listed, marked
folderMissing, its sessions shown; a later pass retires it once they are
all terminal, and the user can Remove it sooner, with the busy guard.
Kept listed, it still holds its folder's sessions, so none is adopted
back. The card says its folder is gone, and Delete offers no files to
keep, as there are none.

Review: #7 (comment)

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

Verified everything locally: untracked worktrees (incl. detached and ones added while running), Add by click and Enter, persistence across a restart, removal outside HomeShell, and the "folder is gone" path with a running session all work as described. LGTM , thanks!

planger added a commit that referenced this pull request Nov 13, 2026
The fold and every Add button were tab stops of their own, and focusing
the fold or a row put the list's stop back on the first card. The fold
and its rows now take part in the roving tab stop (useListTabStop's
trailing items), and an Add takes Tab only from its row, as a card's
controls do.

Review: #7 (comment)
@planger
planger force-pushed the homeshell-untracked-worktrees branch from b19f551 to a6322cf Compare November 13, 2026 08:59
planger added a commit that referenced this pull request Nov 13, 2026
A row showed both the name and the branch, so a worktree named after
its branch read "wt-try wt-try". The branch now shows only when it
differs from the name; a detached one still says so.

Review: #7 (review)
planger added a commit that referenced this pull request Nov 13, 2026
The copy-path button of each row was still a tab stop of its own. It
now takes Tab only from the row holding the list's stop, as the row's
Add does and as a card's copy button does.

Review: #7 (comment)
planger added a commit that referenced this pull request Nov 13, 2026
A worktree workstream whose folder vanished was retired at once, its
sessions force-stopped, so a `git worktree move` under a working agent
killed it. Now one with a session not yet terminal stays listed, marked
folderMissing, its sessions shown; a later pass retires it once they are
all terminal, and the user can Remove it sooner, with the busy guard.
Kept listed, it still holds its folder's sessions, so none is adopted
back. The card says its folder is gone, and Delete offers no files to
keep, as there are none.

Review: #7 (comment)
planger added a commit that referenced this pull request Nov 13, 2026
The fold and every Add button were tab stops of their own, and focusing
the fold or a row put the list's stop back on the first card. The fold
and its rows now take part in the roving tab stop (useListTabStop's
trailing items), and an Add takes Tab only from its row, as a card's
controls do.

Review: #7 (comment)
planger added a commit that referenced this pull request Nov 13, 2026
A row showed both the name and the branch, so a worktree named after
its branch read "wt-try wt-try". The branch now shows only when it
differs from the name; a detached one still says so.

Review: #7 (review)
@planger
planger force-pushed the homeshell-untracked-worktrees branch from 8ff9300 to 18098ac Compare November 13, 2026 09:57
planger added a commit that referenced this pull request Nov 13, 2026
The copy-path button of each row was still a tab stop of its own. It
now takes Tab only from the row holding the list's stop, as the row's
Add does and as a card's copy button does.

Review: #7 (comment)
planger added a commit that referenced this pull request Nov 13, 2026
A worktree workstream whose folder vanished was retired at once, its
sessions force-stopped, so a `git worktree move` under a working agent
killed it. Now one with a session not yet terminal stays listed, marked
folderMissing, its sessions shown; a later pass retires it once they are
all terminal, and the user can Remove it sooner, with the busy guard.
Kept listed, it still holds its folder's sessions, so none is adopted
back. The card says its folder is gone, and Delete offers no files to
keep, as there are none.

Review: #7 (comment)
Base automatically changed from homeshell-in-place-default to main November 13, 2026 11:48
The core provider surveys the linked worktrees of a project's repository.
Those no workstream works in are carried on the project as
untrackedWorktrees, with the number of sessions running there, instead of
having their sessions adopted into a workstream without a branch.
POST /worktree-workstreams adds one as a worktree workstream, which then
behaves like one HomeShell created. HomeShell never adds one on its own.

A worktree workstream whose worktree was removed outside HomeShell is
retired like a Remove. Projections and removals in flight do not bring
back or drop a workstream changed meanwhile.
A fold under Separate folders lists the untracked worktrees, each with its
branch, folder and sessions, and Add makes a workstream of one. The fold
and its rows are items of the workstream list: the arrow keys reach them,
Right opens the fold, Left closes it or goes back to it, and Enter on a row
adds it. Focus on one leaves nothing selected, so that no Alt letter acts
on a card or session the user has moved away from.
The form mounts once the providers load and focuses its name in an effect,
so the name box can be found before it has focus. CI hit that gap.
The fold and every Add button were tab stops of their own, and focusing
the fold or a row put the list's stop back on the first card. The fold
and its rows now take part in the roving tab stop (useListTabStop's
trailing items), and an Add takes Tab only from its row, as a card's
controls do.

Review: #7 (comment)
A row showed both the name and the branch, so a worktree named after
its branch read "wt-try wt-try". The branch now shows only when it
differs from the name; a detached one still says so.

Review: #7 (review)
A click on the fold now focuses it, as Chromium does on its own, so the
list's stop leaves a row the fold hides rather than the fold standing
in for it while the list still names the row. The tab stop's card and
its position travel together, and the tests say what they mean.
The copy-path button of each row was still a tab stop of its own. It
now takes Tab only from the row holding the list's stop, as the row's
Add does and as a card's copy button does.

Review: #7 (comment)
A failed session has not ended (SessionState.Ended), so the count on an
untracked worktree includes it, as the session list shows it among the
live ones.
A worktree workstream whose folder vanished was retired at once, its
sessions force-stopped, so a `git worktree move` under a working agent
killed it. Now one with a session not yet terminal stays listed, marked
folderMissing, its sessions shown; a later pass retires it once they are
all terminal, and the user can Remove it sooner, with the busy guard.
Kept listed, it still holds its folder's sessions, so none is adopted
back. The card says its folder is gone, and Delete offers no files to
keep, as there are none.

Review: #7 (comment)
…worktree keeps its name

The projection hands its read to ReplaceProjection, so a rename, a
removal or a workstream added in a suggested folder while the pass runs
outlives it; a session the projection hides on a suggestion counts as
listed, so the store does not add it to a workstream as well. A worktree
added from a suggestion keeps its name when its branch moves, as only
the core's in-place names follow the branch (GivenName).
…nd an Add claims its folder everywhere

- A workstream changed while a pass ran is taken from the store whole,
  but keeps the pass's FolderMissing: only a pass finds it, so the
  store's copy is never newer.
- The read handed to ReplaceProjection covers a removal made during the
  pass, so the store's own record of removals since the last projection
  (unprojectedRemovals) goes. A pass hands an empty project's read as
  empty, not nil, which would mean no read at all.
- Adding an untracked worktree changes no git listing, so it now has
  every project surveyed again: a project sharing the repository stops
  suggesting the folder.
- ARCHITECTURE.md: "Changes during a pass win" is the one home for what
  a pass keeps of suggestions too.
…ases listed

stampEndedAtLocked and keepChangesSinceRead index sessions with the one
sessionsByID, over a session walk. The tests reuse hasSession, and
resurvey's comment names an untracked worktree added among its cases.
@planger
planger force-pushed the homeshell-untracked-worktrees branch from 18098ac to aa76c26 Compare November 13, 2026 11:49
@planger
planger merged commit d97ba1e into main Nov 13, 2026
6 checks passed
@planger
planger deleted the homeshell-untracked-worktrees branch November 13, 2026 12:12
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.

3 participants