dsh-codex-style-worktree

LIMITATIONS

Known limitations

- **DSH versions**: `0.2.0-rc.2` / `0.2.1-rc.2`; depends on the base bundle's `sessionProjections`, `settings` and `configEditor` — missing ones degrade gracefully: no projections → sidebar marker / progress card unavailable; no settings → read-only config; - **Node.js >= 22.19.0** (the client uses React 18+ `useSyncExternalStore`); - **Creation happens only on the first step of a Session's first turn** and only for top-level Sessions whose recorded creation source is `startup`; resume / clear / compaction / subagents / taskboard sessions / matching presets / disable marker / `enabled: false` / existing record / placement=local never create one. A blank Session that is opened and never used creates nothing, so a placement choice made in it is read at send time and cannot lag one Session behind; - **No new Workspace**: sessions stay in their original workspace; only the cwd changes; - **No naming, no branch** (detached by default); `mode: branch` is opt-in; the plugin never merges, pushes or deletes user branches; - **Non-Git workspaces**: the selector is hidden and nothing is created; - **Read-only sandbox / workspace-write boundary / no commit / limit**: structured errors that never block the session; - concurrent creation in one repository is serialized by `createKeyedMutex`; any exception inside the `agent/pre-step` listener is swallowed and warned about, so the plugin can never prevent a session from starting or block the first message; - projection events enter the session log (~4 per new session), the cost of zero polling; an ephemeral channel could replace them later (out of scope for this release); - **known limitation**: cleaning a non-live session's checkout from the settings page leaves its sidebar marker until that session's next consistency repair (reopening the session or its first step; see 2.4); - **seat choice (by design, not a limitation)**: the placement pill registers in the official `conversation.hero.options` list seat, **not** the single-value `conversation.hero.workspace` seat owned by the shipped WorkspacePicker (that seat is `kind: "single"` with `replaceRisk: "shadows-shipped-ui"`), so the shipped workspace switcher is **never shadowed**; the sidebar marker uses the official ambient-marker seat `sidebar.session.row.leading`, not the hover-only row action strip; - the sidebar marker is only a marker: not clickable, no hover card, no navigation; - the "don't use a worktree" rollback feature is **explicitly out of scope**; the progress card's "Cancel" only hides the card. - **The cost of force-cleaning**: overriding `worktree-in-use` makes the **other** live session lose its current working directory (its cwd points at a deleted checkout) and throws away any uncommitted changes in it; cleaning your own session's checkout is not refused, its cwd is moved back to the original workspace. - **Restored checkouts are not managed by the plugin**: they are not written to sidecar records and are not bound to a session, so remove them manually with `git worktree remove`; snapshots only hold the pre-delete committed HEAD. - **Snapshots only contain committed content**: the ref points at the pre-delete `HEAD`, so uncommitted changes are not in it; a restored checkout is not bound to the original session either. - **Archive cleanup is a lazy sweep**: `cleanupOnArchive` is not immediate; it only runs at the moments listed in 6.3, and skips checkouts still used by a live session. Out of scope: cloud / Codex Web integration / multiple placements; automatic merge, PRs, environment installation; remembering placement per session (instead of per workspace); switching an existing session into a worktree mid-conversation.