@dsh-cove/dsh-web-all 0.0.0-stage → 0.4.4

package/src/core/worktree/paths.ts

@@ -0,0 +1,123 @@
+/**
+ * Path and naming helpers shared between the host manager and the browser
+ * side (browser side uses these for display only — it never writes to the
+ * filesystem). All paths are POSIX; the host normalizes the separators at
+ * the git boundary.
+ * @module @dsh-cove/dsh-client-ui-worktree/core
+ */
+
+import { isValidBranchName } from './invariant.ts'
+
+/** The directory inside each repo that owns linked worktrees. */
+export const WORKSPACE_DIR = '.dsh/workspaces'
+
+/** The manifest filename inside `WORKSPACE_DIR`. */
+export const MANIFEST_FILENAME = 'manifest.json'
+
+/** The "main" pseudo-worktree name — never a real on-disk worktree. */
+export const MAIN_WORKTREE = '<main>'
+
+/** Compose `<repo>/.dsh/workspaces` for a given repo path. */
+export function worktreeRoot(repoPath: string): string {
+  if (typeof repoPath !== 'string' || repoPath.length === 0) {
+    throw new TypeError('repoPath must be a non-empty string')
+  }
+  const trimmed = stripTrailingSeparator(repoPath)
+  return `${trimmed}/${WORKSPACE_DIR}`
+}
+
+/** Compose `<repo>/.dsh/workspaces/<branch>` for a given repo + branch. */
+export function worktreeDir(repoPath: string, branch: string): string {
+  if (!isValidBranchName(branch)) {
+    throw new Error(`invalid branch name: ${JSON.stringify(branch)}`)
+  }
+  return `${worktreeRoot(repoPath)}/${branch}`
+}
+
+/**
+ * Whether a path is one of this plugin's lane directories
+ * (`<repo>/.dsh/workspaces/<branch>`).
+ *
+ * Used to keep the lane lifecycle's bookkeeping — retiring a lane's workspace
+ * registration once its conversations are archived — away from workspaces the
+ * user registered themselves. Workspace ids are opaque, so the path is the only
+ * thing that identifies a lane in a workspace list.
+ */
+export function isLaneDirectory(path: string): boolean {
+  if (typeof path !== 'string' || path === '') return false
+  return path.replace(/\\/g, '/').includes(`/${WORKSPACE_DIR}/`)
+}
+
+/** Strip a single trailing `/` (defensive only — POSIX paths usually lack it). */
+function stripTrailingSeparator(path: string): string {
+  return path.endsWith('/') && path.length > 1 ? path.slice(0, -1) : path
+}
+
+/** Short sha (first 7 chars) — same display rule as `git rev-parse --short`. */
+export function shortSha(sha: string | null | undefined): string | null {
+  if (typeof sha !== 'string' || sha.length === 0) return null
+  return sha.length > 7 ? sha.slice(0, 7) : sha
+}
+
+/**
+ * Truncate a path for the sidebar row (replace the leading `<repo>/.dsh/`
+ * with a visual marker so the full path is still in the title attr).
+ */
+export function displayPath(absolute: string): string {
+  const marker = `/${WORKSPACE_DIR}/`
+  const idx = absolute.indexOf(marker)
+  if (idx < 0) return absolute
+  return `.dsh/workspaces/${absolute.slice(idx + marker.length)}`
+}
+
+/**
+ * Whether `target` is `root` itself or lies beneath it (POSIX, segment-aware).
+ *
+ * Applied to keep mutations inside the workspaces the host has registered: a
+ * plain string prefix would let `/repo-other` read as "inside `/repo`".
+ */
+export function isInsidePath(root: string, target: string): boolean {
+  const posix = (value: string): string => value.replace(/\\/g, '/')
+  const base = posix(root)
+  const candidate = posix(target)
+  const trimmedBase = base.length > 1 && base.endsWith('/') ? base.slice(0, -1) : base
+  const trimmed = candidate.length > 1 && candidate.endsWith('/') ? candidate.slice(0, -1) : candidate
+  if (trimmedBase === '/' || trimmedBase === '') return trimmed.startsWith('/')
+  return trimmed === trimmedBase || trimmed.startsWith(`${trimmedBase}/`)
+}
+
+/** Compare two paths for equality after normalization (POSIX separators). */
+export function samePath(a: string, b: string): boolean {
+  if (a === b) return true
+  const na = a.replace(/\\/g, '/')
+  const nb = b.replace(/\\/g, '/')
+  if (na === nb) return true
+  const sa = na.endsWith('/') && na.length > 1 ? na.slice(0, -1) : na
+  const sb = nb.endsWith('/') && nb.length > 1 ? nb.slice(0, -1) : nb
+  return sa === sb
+}
+
+/**
+ * Parse a GitHub remote URL into `{ owner, repo }`. Accepts the https
+ * (`https://github.com/owner/repo[.git]`), ssh scp-like
+ * (`git@github.com:owner/repo.git`), and ssh URL (`ssh://git@github.com/owner/repo`)
+ * spellings. Returns null for non-GitHub remotes so the caller can fall
+ * back to the compare-URL path.
+ */
+export function githubOwnerRepo(remoteUrl: string): { owner: string; repo: string } | null {
+  const match = remoteUrl.trim().match(/(?:github\.com[/:])([^/]+)\/([^/.]+?)(?:\.git)?$/)
+  if (match === null) return null
+  const [, owner, repo] = match
+  if (owner === undefined || repo === undefined || owner === '' || repo === '') return null
+  return { owner, repo }
+}
+
+/**
+ * GitHub compare URL for one PR candidate: base...head with the editor
+ * expanded. Returns null when the remote is not a GitHub URL.
+ */
+export function githubCompareUrl(remoteUrl: string, base: string, branch: string): string | null {
+  const parsed = githubOwnerRepo(remoteUrl)
+  if (parsed === null) return null
+  return `https://github.com/${parsed.owner}/${parsed.repo}/compare/${encodeURIComponent(base)}...${encodeURIComponent(branch)}?expand=1`
+}

package/src/core/worktree/pr-create.ts

@@ -0,0 +1,157 @@
+/**
+ * Pull-request creation wire contract and pure argv/input helpers.
+ *
+ * Host execution lives in the worktree service. This module stays runtime-neutral
+ * so both host and client programs compile the same request/result contract.
+ */
+
+export interface PrCreateInput {
+  /** Any path inside the project. `repoPath` remains accepted by the host as a legacy alias. */
+  cwd?: string
+  /** Local branch to publish. `name` remains accepted by the host as a legacy alias. */
+  branch?: string
+  /** Pull-request title. Defaults to the branch for legacy callers. */
+  title?: string
+  /** Pull-request body. Defaults to an empty body for legacy callers. */
+  body?: string
+  /** Target branch. `baseRef` remains accepted by the host as a legacy alias. */
+  base?: string
+  /** GitHub head selector, usually a branch or `owner:branch`. Defaults to `branch`. */
+  head?: string
+  /** Create the pull request as a draft. */
+  draft?: boolean
+  /** Legacy project-root field. */
+  repoPath?: string
+  /** Legacy worktree-name field. */
+  name?: string
+  /** Legacy base-branch field. */
+  baseRef?: string
+}
+
+export interface PrCreateResult {
+  url: string
+  number: number
+  /** Legacy result field retained for the previous browser client. */
+  prUrl: string
+  /** Legacy discriminator: gh creates the pull request through GitHub's API. */
+  method: 'api'
+}
+
+export type PrCreateErrorCode =
+  | 'invalid-input'
+  | 'gh-not-installed'
+  | 'gh-not-authenticated'
+  | 'pr-already-exists'
+  | 'timeout'
+  | 'gh-failed'
+  | 'invalid-gh-response'
+
+export interface NormalizedPrCreateInput {
+  cwd: string
+  branch: string
+  title: string
+  body: string
+  base?: string
+  head: string
+  draft: boolean
+}
+
+export type PrCreateInputValidation =
+  | { ok: true; value: NormalizedPrCreateInput }
+  | { ok: false; message: string }
+
+const MAX_TITLE_LENGTH = 256
+const MAX_BODY_LENGTH = 64 * 1024
+
+/** Git's branch-name restrictions, without invoking a subprocess. */
+export function isSafeBranchName(value: string): boolean {
+  if (value === '' || value.length > 255 || value === '@' || value.startsWith('-')) return false
+  if (/\s|[~^:?*\\\[\x00-\x1f\x7f]/u.test(value)) return false
+  if (value.includes('..') || value.includes('@{') || value.includes('//')) return false
+  if (value.startsWith('/') || value.endsWith('/') || value.startsWith('.') || value.endsWith('.')) return false
+  if (value.endsWith('.lock')) return false
+  return value.split('/').every(part => part !== '' && !part.startsWith('.') && !part.endsWith('.'))
+}
+
+/** GitHub accepts either a branch or `owner:branch` for --head. */
+export function isSafeHead(value: string): boolean {
+  const colon = value.indexOf(':')
+  if (colon === -1) return isSafeBranchName(value)
+  if (colon === 0 || colon !== value.lastIndexOf(':')) return false
+  const owner = value.slice(0, colon)
+  const branch = value.slice(colon + 1)
+  return /^[A-Za-z0-9_.-]+$/u.test(owner) && isSafeBranchName(branch)
+}
+
+/** Normalize current and legacy request fields, rejecting malformed or unsafe values. */
+export function normalizePrCreateInput(input: PrCreateInput): PrCreateInputValidation {
+  const cwdValue = input.cwd ?? input.repoPath
+  const branchValue = input.branch ?? input.name
+  const baseValue = input.base ?? input.baseRef
+
+  if (input.cwd !== undefined && typeof input.cwd !== 'string') return { ok: false, message: 'cwd must be a string' }
+  if (input.repoPath !== undefined && typeof input.repoPath !== 'string') return { ok: false, message: 'repoPath must be a string' }
+  if (typeof cwdValue !== 'string' || cwdValue.trim() === '') return { ok: false, message: 'cwd is required' }
+  if (typeof branchValue !== 'string' || !isSafeBranchName(branchValue.trim())) {
+    return { ok: false, message: 'branch is invalid' }
+  }
+  if (input.branch !== undefined && typeof input.branch !== 'string') return { ok: false, message: 'branch must be a string' }
+  if (input.name !== undefined && typeof input.name !== 'string') return { ok: false, message: 'name must be a string' }
+  if (input.title !== undefined && typeof input.title !== 'string') return { ok: false, message: 'title must be a string' }
+  if (input.body !== undefined && typeof input.body !== 'string') return { ok: false, message: 'body must be a string' }
+  if (input.base !== undefined && typeof input.base !== 'string') return { ok: false, message: 'base must be a string' }
+  if (input.baseRef !== undefined && typeof input.baseRef !== 'string') return { ok: false, message: 'baseRef must be a string' }
+  if (input.head !== undefined && typeof input.head !== 'string') return { ok: false, message: 'head must be a string' }
+  if (input.draft !== undefined && typeof input.draft !== 'boolean') return { ok: false, message: 'draft must be a boolean' }
+
+  const branch = branchValue.trim()
+  const title = input.title?.trim() || branch
+  const body = input.body ?? ''
+  const base = baseValue?.trim()
+  const head = input.head?.trim() || branch
+
+  if (title.length > MAX_TITLE_LENGTH || /[\r\n\x00]/u.test(title)) {
+    return { ok: false, message: `title must be one line and at most ${MAX_TITLE_LENGTH} characters` }
+  }
+  if (body.length > MAX_BODY_LENGTH || body.includes('\0')) {
+    return { ok: false, message: `body must not contain NUL and must be at most ${MAX_BODY_LENGTH} characters` }
+  }
+  if (base !== undefined && (base === '' || !isSafeBranchName(base))) return { ok: false, message: 'base is invalid' }
+  if (!isSafeHead(head)) return { ok: false, message: 'head is invalid' }
+
+  return {
+    ok: true,
+    value: {
+      cwd: cwdValue.trim(),
+      branch,
+      title,
+      body,
+      ...(base === undefined ? {} : { base }),
+      head,
+      draft: input.draft === true,
+    },
+  }
+}
+
+/** Build an argv-only GitHub CLI invocation. Values never pass through a shell. */
+export function ghPrCreateArgv(input: Omit<NormalizedPrCreateInput, 'cwd'>): string[] {
+  const argv = ['pr', 'create', '--title', input.title, '--body', input.body, '--head', input.head]
+  if (input.base !== undefined) argv.push('--base', input.base)
+  if (input.draft) argv.push('--draft')
+  return argv
+}
+
+/** Extract the PR URL and numeric id from `gh pr create` output. */
+export function parseGhPrCreateOutput(stdout: string): { url: string; number: number } | undefined {
+  const match = stdout.match(/https?:\/\/[^\s]+\/pull\/(\d+)(?:\b|\/)?/u)
+  if (match === null) return undefined
+  const number = Number(match[1])
+  if (!Number.isSafeInteger(number) || number <= 0) return undefined
+  try {
+    const url = new URL(match[0].replace(/[),.;]+$/u, ''))
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') return undefined
+    return { url: url.href.replace(/\/$/u, ''), number }
+  } catch {
+    return undefined
+  }
+}

package/src/core/worktree/protocol.ts

@@ -0,0 +1,7 @@
+/**
+ * worktree 跨半区 wire 契约（host 与 client 双 program 编译）。
+ * 纯常量：/worktree 与 /workspace-model 前缀。
+ */
+
+export const WORKTREE_API_PREFIX = '/worktree'
+export const WORKSPACE_MODEL_PREFIX = '/workspace-model'

package/src/core/worktree/types.ts

@@ -0,0 +1,317 @@
+/**
+ * Domain types shared between the host half and the browser half. Anything
+ * that crosses the HTTP boundary lands here first so the JSON contract is
+ * one source of truth.
+ *
+ * The plugin deliberately mirrors the official `ctx.workspaces` /
+ * `ctx.sessions` client-service shapes where it can — the browser side
+ * mirrors the official `@deepseek-ai/dsh-workspace` / `@deepseek-ai/dsh-session` faces
+ * (type-only) and aligns its derivation to the same `sessionIds` account
+ * the official WorkspaceBrowser uses, so a single source of truth
+ * governs session grouping and workspace display across both surfaces.
+ * @module @dsh-cove/dsh-client-ui-worktree/core
+ */
+
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { WorkspaceId } from '@deepseek-ai/dsh-workspace/types'
+import type { WorktreeErrorCode } from './invariant.ts'
+
+// Re-export the branded id types so host modules can import them from
+// `core/types.ts` alongside the rest of the domain model.
+export type { SessionId } from '@deepseek-ai/dsh-session/types'
+export type { WorkspaceId } from '@deepseek-ai/dsh-workspace/types'
+
+/** One linked worktree entry as the browser renders it under a project row. */
+export interface WorktreeView {
+  /** Stable name (= worktree dir name under `.dsh/workspaces/`). */
+  name: string
+  /** Absolute filesystem path. */
+  path: string
+  /** The checked-out branch (or null when detached). */
+  branch: string | null
+  /** HEAD sha (short) when known. */
+  head: string | null
+  /** True when the worktree directory exists on disk. */
+  exists: boolean
+  /** DSH workspace id when registered; null when the path is not a workspace. */
+  workspaceId: WorkspaceId | null
+  /** Session bound to this lane (session-bound lanes only); null otherwise.
+   *  This binding — not `workspaceId` — is what makes a lane a lane. */
+  sessionId: SessionId | null
+}
+
+/** One git project (repo) in the host worktree index. */
+export interface WorktreeProject {
+  /** Canonical absolute path of the repository. */
+  repoPath: string
+  /** Absolute path of the main worktree (== repoPath on a normal repo). */
+  mainPath: string
+  /** DSH workspace id for the main worktree path, when registered. */
+  mainWorkspaceId: WorkspaceId | null
+  /** The repository's basename (e.g. `dsh-cove`). */
+  name: string
+  /** The main worktree's HEAD branch (or null when detached / unknown). */
+  mainBranch: string | null
+  /** Number of uncommitted files in the main working tree (>=0); null when not probed. */
+  dirty: number | null
+  /** Linked worktrees under `<repo>/.dsh/workspaces/`. The main worktree is NOT in this list. */
+  worktrees: WorktreeView[]
+}
+
+/**
+ * Host response: the per-repo worktree index for the management panel.
+ * Sessions are never carried through the HTTP layer.
+ */
+export interface WorktreeIndex {
+  /** Every registered workspace path that resolves to a git repository. */
+  projects: WorktreeProject[]
+}
+
+/** Result shape for worktree mutations returned over HTTP. */
+export interface MutationResult<T = void> {
+  ok: true
+  value: T
+}
+
+/** Domain error shape returned over HTTP (status >= 400). */
+export interface WorktreeErrorView {
+  ok: false
+  code: WorktreeErrorCode
+  message: string
+}
+
+/** Discriminated union for HTTP responses. */
+export type WorktreeResponse<T = void> = MutationResult<T> | WorktreeErrorView
+
+/** Parameters for `POST /worktree/create`. */
+export interface CreateWorktreeInput {
+  /** Repository root (must be a registered workspace). */
+  repoPath: string
+  /** Branch name (also used as the worktree dir name under `.dsh/workspaces/`).
+   *  The branch is cut at `base` and checked out in the worktree. */
+  branch: string
+  /** Optional base commit-ish the new branch starts at; defaults to HEAD. */
+  base?: string
+}
+
+/** Parameters for `POST /worktree/lane/create` — the worktree behind a branch. */
+export interface CreateLaneInput {
+  /** Repository root (any directory inside it resolves). */
+  repoPath: string
+  /** Branch the lane checks out. An existing local branch is ATTACHED (its own
+   *  worktree is created); otherwise the branch is cut at `base`. */
+  branch: string
+  /** Base commit-ish for a branch that has to be created; defaults to HEAD. */
+  base?: string
+}
+
+/**
+ * A prepared lane: the branch's worktree, ready to host the conversation that
+ * asked for it.
+ *
+ * The lane directory is registered as a DSH workspace, and that is a platform
+ * requirement rather than a design taste: the registry accounts a session to a
+ * workspace only while the session's cwd equals that workspace's path (its
+ * `sessionIds` filters by the session's path, and `attachSession` refuses any
+ * other cwd), `session.create` takes a workspace id XOR a bare cwd, and a blank
+ * conversation that no workspace accounts for renders its composer inert
+ * ("choose a workspace to start"). A lane session created with a bare cwd is
+ * therefore a conversation the user cannot type into.
+ *
+ * Ownership still sits with the conversation: the lane is recorded against the
+ * session that asked for it (`/worktree/lane/bind`), that binding is what the
+ * teardown guards read, and the header chip — not the workspace row — is where
+ * its lifecycle lives. Teardown unregisters the workspace with the directory, so
+ * the sidebar only carries lanes that are still alive.
+ */
+export interface LaneHandle {
+  /** Lane name == branch name. */
+  name: string
+  /** Checked-out branch. */
+  branch: string
+  /** Absolute worktree path — the directory a lane session runs in. */
+  path: string
+  /** Short HEAD of the lane. */
+  head: string | null
+  /** False when an existing worktree was reused instead of created. */
+  created: boolean
+  /** The lane's registered workspace, which is how a blank draft is moved onto
+   *  it; null when the registry refused (the lane still exists on disk, but no
+   *  conversation can be started in it). */
+  workspaceId: WorkspaceId | null
+}
+
+/** Result of `POST /worktree/lane/create`. */
+export type CreateLaneResult = LaneHandle
+
+/** Parameters for `POST /worktree/lane/bind` — attach a created session to its lane. */
+export interface BindLaneInput {
+  /** Repository root owning the lane. */
+  repoPath: string
+  /** Branch the lane cuts (its manifest name). */
+  branch: string
+  /** Session the platform created on the lane workspace. */
+  sessionId: string
+}
+
+/** Result of `POST /worktree/lane/bind`. */
+export interface BindLaneResult {
+  /** The lane after binding (null when it cannot be resolved). */
+  lane: LaneView | null
+  /** Whether the lane's required permission preset is now applied. */
+  permissionPresetApplied: boolean
+}
+
+/** Parameters for `POST /worktree/lane` — resolve the lane a path/session belongs to. */
+export interface LaneLookupInput {
+  /** Absolute path inside the lane (usually the session cwd). */
+  path?: string
+  /** Session id; the host resolves its cwd when `path` is absent. */
+  sessionId?: string
+}
+
+/**
+ * One lane as the conversation header chip and the panel render it.
+ * `name`/`branch` identify the lane; the status fields mirror
+ * `WorktreeStatusView` so a single host probe serves both surfaces.
+ */
+export interface LaneView {
+  /** Lane name == branch name. */
+  name: string
+  /** Checked-out branch (null when detached). */
+  branch: string | null
+  /** Absolute lane path. */
+  path: string
+  /** Repository root owning the lane. */
+  repoPath: string
+  /** True when the lane directory exists on disk. */
+  exists: boolean
+  /** DSH workspace id when registered. */
+  workspaceId: WorkspaceId | null
+  /** Session recorded as bound to this lane, when one was created through us. */
+  sessionId: SessionId | null
+  /** Whether the required lane preset applied; null for older/non-session lanes. */
+  permissionPresetApplied: boolean | null
+  /** Uncommitted file count (null when the directory is gone). */
+  dirty: number | null
+  /** Remote-tracking ref for the branch exists after fetch. */
+  pushed: boolean
+  /** Branch gone from the remote after having been pushed (merged signal). */
+  remoteBranchGone: boolean
+  /** Branch is merged into its base. */
+  merged: boolean
+  /** Recorded PR url, when one was created through this plugin. */
+  prUrl: string | null
+  /** Recorded GitHub PR number. */
+  prNumber: number | null
+}
+
+/** Parameters for `POST /worktree/remove`. */
+export interface RemoveWorktreeInput {
+  /** Repository root. */
+  repoPath: string
+  /** Worktree directory name under `.dsh/workspaces/`. */
+  name: string
+  /** Pass --force to git so uncommitted changes are dropped. */
+  force?: boolean
+  /**
+   * The conversation asking for the teardown, when it is the lane's own
+   * conversation. A live session blocks removal so a running conversation never
+   * loses its directory; that interlock must not make a lane the conversation
+   * itself sits on unremovable, so the lane's own recorded session may excuse
+   * itself (and is archived by the teardown like any other). Any other id —
+   * including one the lane does not record — excuses nothing.
+   */
+  sessionId?: string
+}
+
+/** Parameters for `POST /worktree/init`. */
+export interface InitWorktreeInput {
+  /** Repository root. */
+  repoPath: string
+  /** Create the first branch on HEAD (default: `main`). */
+  initialBranch?: string
+}
+
+/** Parameters for `POST /worktree/pr-create`. */
+export interface PrCreateInput {
+  /** Repository root (must be a registered workspace). */
+  repoPath: string
+  /** Worktree name == branch name. */
+  name: string
+  /** PR target base branch; defaults to the repo's resolved base (manifest
+   *  `baseBranch`, else the remote default branch, else `main`). */
+  baseRef?: string
+  /** Optional PR title; defaults to the branch name. */
+  title?: string
+}
+
+/** Result of `POST /worktree/pr-create`. */
+export interface PrCreateResult {
+  /** The PR page URL (compare URL when created via 'url', html_url when 'api'). */
+  prUrl: string
+  /** How the PR was created: compare URL opened in the browser, or the
+   *  GitHub REST API (requires the `pr.tokenEnv` credential). */
+  method: 'url' | 'api'
+}
+
+/** Parameters for `POST /worktree/status`. */
+export interface StatusInput {
+  /** Repository root. */
+  repoPath: string
+  /** Status for one named worktree only; omit for every linked worktree. */
+  name?: string
+  /**
+   * Probe the remote again instead of answering from the host cache. The
+   * explicit "refresh status" action sets it; opening the panel does not,
+   * because a status probe runs `git fetch` and `ls-remote` per lane.
+   */
+  force?: boolean
+}
+
+/** Per-worktree PR/merge status as the panel renders it. */
+export interface WorktreeStatusView {
+  /** Worktree name (== branch name). */
+  name: string
+  /** Absolute worktree path. */
+  path: string
+  /** Checked-out branch (null when detached). */
+  branch: string | null
+  /** True when the remote-tracking ref for the branch exists after fetch. */
+  pushed: boolean
+  /** True when the branch was pushed before but the remote branch is now gone. */
+  remoteBranchGone: boolean
+  /** True when the branch is merged into the base (branch gone on remote, or
+   *  the branch tip is an ancestor of the base tip). */
+  merged: boolean
+  /** The recorded PR url, when one was created through this plugin. */
+  prUrl: string | null
+}
+
+/** Host response: per-repo PR/merge status index. */
+export interface WorktreeStatusIndex {
+  /** Base branch every status was resolved against. */
+  baseBranch: string
+  worktrees: WorktreeStatusView[]
+  /**
+   * Candidate branches for dialogs: local branch short names, then remote
+   * `origin/*` names with the `origin/` prefix stripped, deduplicated in
+   * that order. Serves base-ref / base-commit dropdowns without another
+   * round trip (the panel probes one status per repo on open).
+   */
+  branches: string[]
+}
+
+/** Parameters for `POST /worktree/cleanup`. */
+export interface CleanupWorktreeInput {
+  /** Repository root. */
+  repoPath: string
+  /** Worktree directory name under `.dsh/workspaces/`. */
+  name: string
+  /** Force cleanup even when the branch is not merged (abandons the branch
+   *  and drops uncommitted changes). */
+  force?: boolean
+  /** The conversation asking for the teardown, when it is the lane's own
+   *  conversation; see {@link RemoveWorktreeInput.sessionId}. */
+  sessionId?: string
+}

package/src/core/worktree/workspace-model.ts

@@ -0,0 +1,61 @@
+/**
+ * Workspace-scoped model presets: domain types shared between the host
+ * half and the browser half. Everything crossing the HTTP boundary lands
+ * here first so the JSON contract is one source of truth.
+ *
+ * The granularity is **workspace**: a preset is keyed by the canonical
+ * workspace directory path (the same value the DSH session header records
+ * as `cwd` at session creation). Each workspace — a plain directory or a
+ * worktree — carries one `{ provider, model, reasoningEffort? }` selection
+ * that overrides the session's otherwise-resolved model from its very first
+ * request.
+ * @module @dsh-cove/dsh-client-ui-worktree/core/workspace-model
+ */
+
+/** One workspace's model preset. `reasoningEffort` is adapter-owned and
+ *  optional — absent means the selected model's provider default applies. */
+export interface WorkspaceModelPreset {
+  /** Registered provider route id. */
+  provider: string
+  /** Provider-owned model id. */
+  model: string
+  /** Adapter-owned reasoning effort id, or provider default when absent. */
+  reasoningEffort?: string
+}
+
+/** The stored document: a map from canonical workspace path to preset. */
+export type WorkspacePresetMap = Record<string, WorkspaceModelPreset>
+
+/** The effective display form a preset may take. */
+export interface EffectiveWorkspaceModel {
+  /** Whether the workspace has an explicit preset. */
+  preset?: WorkspaceModelPreset
+}
+
+/** A read of one workspace's effective model selection. */
+export interface WorkspaceModelView {
+  /** Canonical workspace path the preset is keyed by. */
+  path: string
+  /** Explicit preset when registered; undefined when none. */
+  preset?: WorkspaceModelPreset
+}
+
+/** Mutation input: set/clear a preset for one canonical workspace path. */
+export interface SetWorkspaceModelInput {
+  /** Canonical workspace path (the preset key). */
+  path: string
+  /** The preset to store. */
+  preset: WorkspaceModelPreset
+}
+
+/** Domain error shape returned over HTTP (status >= 400). */
+export interface WorkspaceModelErrorView {
+  ok: false
+  code: 'bad-request' | 'forbidden'
+  message: string
+}
+
+/** Discriminated union for HTTP responses. */
+export type WorkspaceModelResponse<T = void> =
+  | { ok: true; value: T }
+  | WorkspaceModelErrorView