dsh-worktree-bar

LIMITATIONS

Known limitations

<a id="known-limitations-and-deferred-work"></a> - **The checkbox opens a Session; it cannot move one** — a Session's working directory is creation-time data in the harness, so "work in a worktree" on the start screen means "create the worktree, then open the Session there". An in-progress conversation cannot be relocated, and this package does not pretend otherwise. - **Worktrees are fresh checkouts of a commit** — `baseRef` defaults to `HEAD`, so uncommitted changes stay in the main checkout. Untracked setup is shared or duplicated only as far as the project's convention declares. - **A `link` is two-way** — connecting a directory means the worktree and the main checkout are the same directory for that path. That is the point for a virtualenv or a local database, and it is why `copy` exists for anything that must not be shared. - **No automatic cleanup** — a created worktree lives until its own menu or checkbox removes it. There is no age-based or exit-time sweep, and no marker in the git metadata. - **Line totals exclude untracked files** — `+N`/`−M` count `git diff HEAD --numstat`; untracked files appear only in the hover's file counts, because counting their lines would mean reading each file on every poll. - **Host changes need a restart** — a replaced package loads its JavaScript once per process, so only the Client half hot-updates through a page load. - **Subagents share the Session directory** — no per-subagent worktree; every child of an isolated Session runs in the same checkout, which is already isolated from the main one. - **Non-git version control is unsupported** — the row is absent outside a git repository. <a id="dev-note"></a> ### Dev Note <details> <summary>Working context for maintainers — click to expand</summary> `npm test` runs the four suites without a test framework or dependency: - `test/git.test.mjs` — the Git layer against a throwaway repository: parsing, real-path identity, layout anchoring from a subdirectory and from inside a worktree, dirty/locked/main removals, and the porcelain output of the main checkout after a creation. - `test/seed.test.mjs` — the project convention against a repository whose shape mirrors a real project: parsing and refusal of bad conventions, link/copy/linkIgnored application, tracked files still coming from git, the setup command, and the guarantee that removal clears the links without touching anything shared. - `test/host.test.mjs` — the route table over a fake Cordis context: admission branches, the fallback fence, request-shape errors, Session directory resolution, and a create → info → remove round trip. - `test/client.test.mjs` — the browser half rendered through `test/react-shim.mjs`, a minimal React and DOM stand-in, asserting the two modes, every menu, and the endpoint sequence each control produces. The shim exists because the deployment ships neither React nor a DOM to plugins and no Host tool can script the page; it is deliberately small (function components, dependency-skipping hooks, no reconciliation) and is not a general React. Three harness facts are worth re-checking before changing behavior here: the Session working directory is creation-time metadata (`@deepseek-ai/dsh-session`), a plugin route's conventional admission is `ctx.connection.admit` (`@deepseek-ai/dsh-client-connection`), and a replaced package's Host code loads only on restart (the HMR row's module roots are empty in this profile). The README pair has no `README.i18n.yaml`: that file is the harness monorepo's translation-pairing record, produced by its own tooling, which this standalone project does not run. </details> **Runtime invariant:** none published. The package owns one route table, which it registers inside `ctx.effect` and which the Loader disposes with the row; it writes no durable state and holds no cross-plugin state.