[github-actions]

What this is

Not a bug — #6051 is a feature request, so there is no failing behaviour to reproduce. I verified the reported gap, found the capability already exists server-side, and wired it up to the two automatable surfaces. Opened as a draft since it adds public CLI/MCP surface area that deserves a human call on naming.

The gap (verified)

The desktop app can import an existing worktree (openExternalWorktree / importAllWorktrees, apps/desktop/src/lib/trpc/routers/workspaces/procedures/create.ts:912), but neither packages/cli nor the MCP servers exposed anything equivalent — superset workspaces create and workspaces_create only ever materialize a new worktree.

What the issue doesn't mention: the v2 host service already has the whole import path implemented as workspaceCreation.adopt (packages/host-service/src/trpc/router/workspace-creation/procedures/adopt.ts), including the optional explicit worktreePath the desktop import needs, the stale-row hygiene in adoptExistingWorktree, and cross-project path rejection. Its doc comment says the only caller is the v1→v2 migration. So this needed no new host-service logic at all — only client wiring.

What was added

• CLI — superset workspaces import --project <id> --path <worktree-path> --branch <branch> [--name] [--base-branch] (--local | --host <id>), calling workspaceCreation.adopt. --name defaults to the worktree directory name.
• MCP — workspaces_import in packages/mcp-v2, same inputs plus hostId, hitting the same procedure.
• Docs — a <Command> block in the CLI reference and a row in the MCP tool table.

Two deliberate choices, both tested:

1. --path must be absolute. It is interpreted on the target host, which may not be the machine running the CLI, so resolving a relative path against the local cwd would silently point at the wrong directory.
2. Branch mismatch is surfaced, not swallowed. adopt intentionally reads the branch actually checked out at the path and ignores the caller's branch (so a stale name can't make the migration miss a valid worktree). Rather than change that shared behaviour, the CLI compares the result and returns branchMismatch plus a message naming the real branch.

I chose mcp-v2 for the MCP side: it is host-service-backed like the CLI, so it reuses adopt directly. Adding this to v1 packages/mcp would instead require a new desktop renderer command-watcher handler and a new ToolContext mutation — happy to add that too if v1 still needs parity.

Tests

• packages/cli/src/commands/workspaces/import/command.test.ts (6 tests) — started as the reproduction: it failed with Cannot find module './command', which is the reported gap. Now covers forwarding to adopt, name defaulting, --base-branch, relative-path rejection, and branch-mismatch reporting.
• packages/mcp-v2/src/tools/workspaces/import.test.ts (5 tests) — asserts the tool is registered as workspaces_import, targets workspaceCreation.adopt, derives the name, and rejects a relative path without calling the host.

bun test packages/cli/src/commands/workspaces packages/mcp-v2 → 22 pass. Lint exits 0; both packages typecheck.

Unrelated pre-existing failure worth flagging: running the whole packages/cli suite in one process fails agents/create/command.test.ts with Export named 'execFileSync' not found — src/lib/host/spawn.test.ts:40 mocks node:child_process and the mock leaks across files. It fails identically on this branch with my changes stashed, and each file passes in isolation. Left alone as out of scope.

Refs #6051

---

---

Summary by cubic

Adds superset workspaces import and the workspaces_import MCP tool to register an existing git worktree as a workspace, reusing workspaceCreation.adopt. This lets automation hand off pre-created worktrees without creating new ones.

• New Features
  • CLI: superset workspaces import --project <id> --path <abs> --branch <branch> [--name] [--base-branch] (--local | --host <id>).
  • MCP: workspaces_import in packages/mcp-v2, calling workspaceCreation.adopt.
  • Behavior: --path must be absolute (interpreted on the target host); --name defaults to the worktree directory; forwards --base-branch.
  • Safety: import is idempotent; if the checked-out branch differs from --branch, the result sets branchMismatch and returns the real branch.

^{Written for commit 3ce8356. Summary will update on new commits.}

[ghost]

Ready to review this PR? Stage has broken it down into 3 individual chapters for you:

	Title
1	Implement workspace import CLI command
2	Expose workspace import as MCP tool
3	Update CLI and MCP documentation

_{Chapters generated by Stage for commit 3ce8356 on Jul 29, 2026 2:46pm UTC.}

[Kitenite]

Closing: no longer applicable. This adds files under packages/mcp-v2, which no longer exists — it was renamed to packages/mcp in #6079, and #6082 removed the v1 MCP server. The branch is CONFLICTING and ~36 commits behind.

It also builds on workspaceCreation.adopt, which its own docstring documents as migration-only, directing MCP/CLI callers to workspaces.create. Desktop shipped this capability that way in #6097.

#6051 stays open (tracked as SUPER-1691). The smaller fix is a worktreePath + runSetup passthrough on the existing workspaces create command and workspaces_create MCP tool, matching #6097 — not a new command.