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

package/src/client/conversation/worktree/lane-menu.tsx

@@ -0,0 +1,247 @@
+/**
+ * Lane popover: what the conversation's branch directory is, and the three
+ * things a user can do about it.
+ *
+ * This is where the lifecycle lives now that there is no management panel: the
+ * branch is chosen once, when the conversation starts (the composer picker), and
+ * everything that happens *after* the branch exists — re-check, submit a PR,
+ * delete the directory — hangs off the header chip that names that branch. One
+ * control creates, one surface finishes.
+ *
+ * There used to be two teardown actions ("clean up worktree" / "remove
+ * worktree"); users could not tell them apart, so they are one `Delete…` whose
+ * dialog asks the only question that matters (does the local branch go too).
+ *
+ * Two safety rules are enforced here rather than discovered by failing:
+ *   - a running conversation may not tear its own directory down (the directory
+ *     would vanish under the running turn), so the action is disabled with the
+ *     reason shown;
+ *   - deleting the directory this conversation sits on archives the conversation
+ *     (the host does that for every directory session), and the menu says so
+ *     before the click instead of surprising the user afterwards.
+ * @module @dsh-cove/dsh-client-ui-worktree/client/lane-menu
+ */
+
+import { useEffect, useRef, useState } from 'react'
+import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
+import type { LaneView } from '../../../core/worktree/types.ts'
+import { WorktreeApi } from './api.ts'
+import { PrCreateDialog } from './dialogs/PrCreateDialog.tsx'
+import { DeleteWorktreeDialog } from './dialogs/DeleteWorktreeDialog.tsx'
+import { worktreeErrorMessage } from './lifecycle.ts'
+import { WORKTREE_PART_LANE_MENU, WORKTREE_PLUGIN } from './semantic.ts'
+import css from '../conversation.module.css'
+
+/** Which dialog is open, if any. */
+type LaneDialog = 'pr' | 'delete'
+
+/** A base-branch choice set for the PR dialog, read from the repo status. */
+interface PrChoices {
+  branches: string[]
+  baseBranch: string
+}
+
+export interface LaneMenuProps {
+  /** The conversation the chip belongs to (the teardown caller identity). */
+  sessionId: string
+  /** The lane this conversation runs on. */
+  lane: LaneView
+  /** Worktree API surface (the menu owns its dialogs). */
+  api: WorktreeApi
+  /** Whether the conversation is running a turn right now. */
+  running: boolean
+  /**
+   * Whether the lane records this conversation as its own session. Only then do
+   * the teardown actions archive the conversation the user is looking at.
+   */
+  ownLane: boolean
+  onClose: () => void
+  /** The lane changed: the chip re-reads it. */
+  onChanged: () => void
+  t: PropsLocale<'worktree'>['t']
+}
+
+/**
+ * The lane popover.
+ * @param props - see {@link LaneMenuProps}.
+ */
+export function LaneMenu(props: LaneMenuProps): JSX.Element {
+  const { sessionId, lane, api, running, ownLane, onClose, onChanged, t } = props
+  const [busy, setBusy] = useState<'refresh' | 'pr' | 'delete' | null>(null)
+  const [error, setError] = useState<unknown>(null)
+  const [dialog, setDialog] = useState<LaneDialog | null>(null)
+  const [prChoices, setPrChoices] = useState<PrChoices | null>(null)
+  /** Directory facts re-read for the delete dialog; see openDelete. */
+  const [deleteFacts, setDeleteFacts] = useState<{ merged: boolean; dirty: number } | null>(null)
+  const rootRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    // While one of the dialogs is showing, the menu must not dismiss itself on
+    // the next click: the dialog is portaled to the body (so every click in it
+    // is "outside" this popover) and it owns its own dismissal. Without this the
+    // dialog unmounted mid-flight and a PR or teardown the host had already
+    // started vanished from the screen.
+    if (dialog !== null) return undefined
+    const onPointerDown = (event: MouseEvent): void => {
+      if (rootRef.current !== null && !rootRef.current.contains(event.target as Node)) onClose()
+    }
+    const onKeyDown = (event: KeyboardEvent): void => {
+      if (event.key === 'Escape') onClose()
+    }
+    document.addEventListener('mousedown', onPointerDown)
+    document.addEventListener('keydown', onKeyDown)
+    return () => {
+      document.removeEventListener('mousedown', onPointerDown)
+      document.removeEventListener('keydown', onKeyDown)
+    }
+  }, [dialog, onClose])
+
+  /** Probe the lane again, remote included; the chip re-reads the answer. */
+  const refresh = async (): Promise<void> => {
+    if (busy !== null) return
+    setBusy('refresh')
+    setError(null)
+    try {
+      await api.status({ repoPath: lane.repoPath, name: lane.name, force: true })
+      onChanged()
+    } catch (err) {
+      setError(err)
+    } finally {
+      setBusy(null)
+    }
+  }
+
+  /**
+   * The PR dialog needs the repository's candidate branches, which only the
+   * status probe knows. Fetching them here keeps the dialog's contract (a base
+   * dropdown over real branches) instead of opening it with a guessed base.
+   */
+  const openPrDialog = async (): Promise<void> => {
+    if (busy !== null) return
+    setBusy('pr')
+    setError(null)
+    try {
+      const status = await api.status({ repoPath: lane.repoPath })
+      setPrChoices({ branches: status.branches, baseBranch: status.baseBranch })
+      setDialog('pr')
+    } catch (err) {
+      setError(err)
+    } finally {
+      setBusy(null)
+    }
+  }
+
+  /**
+   * The delete dialog owns the branch-checkbox decision; the guard is here.
+   *
+   * The facts are re-read first. `dirty` is a local git call the host makes on
+   * every lane read, and the chip's snapshot can predate work the user has just
+   * left in the directory — which is exactly what decides whether the host will
+   * demand the force choice. Reading that decision from the snapshot hid the
+   * force row the host needs, so the dialog lied about being one click.
+   */
+  const openDelete = async (): Promise<void> => {
+    if (running || busy !== null) return
+    setBusy('delete')
+    setError(null)
+    try {
+      const fresh = await api.lane({ path: lane.path })
+      setDeleteFacts({ merged: fresh?.merged ?? lane.merged, dirty: fresh?.dirty ?? lane.dirty ?? 0 })
+      setDialog('delete')
+    } catch (err) {
+      setError(err)
+    } finally {
+      setBusy(null)
+    }
+  }
+
+  /** The lane is gone (or changed) after a teardown: leave and re-read. */
+  const afterTeardown = (): void => {
+    setDialog(null)
+    setDeleteFacts(null)
+    onChanged()
+    onClose()
+  }
+
+  return (
+    <div
+      ref={rootRef}
+      className={css.laneMenu}
+      role="menu"
+      aria-label={t('menu.aria', { branch: lane.branch ?? lane.name })}
+      data-dsh-plugin={WORKTREE_PLUGIN}
+      data-dsh-part={WORKTREE_PART_LANE_MENU}
+    >
+      <div className={css.laneMenuFacts}>
+        <span className={css.laneMenuPathLabel}>{t('menu.path')}</span>
+        <span className={css.laneMenuPath} title={lane.path}>{lane.path}</span>
+      </div>
+      {/* The PR link is provenance, not an action: it only exists when this
+          plugin created one, and it stays reachable after the merge. */}
+      {lane.prUrl !== null && (
+        <a className={css.laneMenuLink} href={lane.prUrl} target="_blank" rel="noopener noreferrer">
+          {t('worktree.prOpen')}
+        </a>
+      )}
+      {error !== null && <div className={css.laneMenuError} role="alert">{worktreeErrorMessage(error, t)}</div>}
+      <div className={css.laneMenuActions}>
+        <button
+          type="button"
+          role="menuitem"
+          className={css.laneMenuItem}
+          disabled={busy !== null || lane.merged}
+          onClick={() => { void openPrDialog() }}
+        >
+          {t('menu.pr')}
+        </button>
+        <button
+          type="button"
+          role="menuitem"
+          className={css.laneMenuItem}
+          disabled={running || busy !== null}
+          onClick={() => { void openDelete() }}
+        >
+          {t('menu.delete')}
+        </button>
+        <button
+          type="button"
+          role="menuitem"
+          className={css.laneMenuItem}
+          disabled={busy !== null}
+          onClick={() => { void refresh() }}
+        >
+          {t('menu.refresh')}
+        </button>
+      </div>
+      {running && <div className={css.laneMenuHint}>{t('menu.running')}</div>}
+      {ownLane && <div className={css.laneMenuHint}>{t('menu.selfTeardown')}</div>}
+
+      {dialog === 'pr' && prChoices !== null && (
+        <PrCreateDialog
+          repoPath={lane.repoPath}
+          name={lane.name}
+          branches={prChoices.branches}
+          defaultBaseRef={prChoices.baseBranch}
+          api={api}
+          onClose={() => { setDialog(null) }}
+          onCreated={afterTeardown}
+          onSettled={onChanged}
+          t={t}
+        />
+      )}
+      {dialog === 'delete' && deleteFacts !== null && (
+        <DeleteWorktreeDialog
+          repoPath={lane.repoPath}
+          name={lane.name}
+          merged={deleteFacts.merged}
+          dirty={deleteFacts.dirty}
+          api={api}
+          sessionId={ownLane ? sessionId : undefined}
+          onClose={() => { setDialog(null) }}
+          onRemoved={afterTeardown}
+          t={t}
+        />
+      )}
+    </div>
+  )
+}

package/src/client/conversation/worktree/lane-open.ts

@@ -0,0 +1,204 @@
+/**
+ * "Choosing a branch means moving onto its lane": the browser half that turns a
+ * branch choice into (1) the branch's worktree on the host, (2) the conversation
+ * actually running in it, and (3) the binding the header chip, the teardown
+ * guards and the lane's permission preset all key off.
+ *
+ * Why the lane MUST be a registered DSH workspace
+ *   The platform accounts a session to a workspace only while the session's cwd
+ *   equals that workspace's path: `WorkspaceEntity.sessionIds` filters by
+ *   `sessionPath(id) === record.path` and `attachSession` refuses a cwd that
+ *   resolves anywhere else (`dsh-workspace`), and `session.create` takes either
+ *   a workspace id (cwd := the workspace path) or a bare cwd, never both. A blank
+ *   conversation that no workspace accounts for renders its composer inert
+ *   ("choose a workspace to start"), so a lane session created with a bare
+ *   `cwd` is a conversation the user cannot type into. Hence one workspace per
+ *   lane, created with the lane directory as its path; teardown removes it
+ *   again, so the sidebar only carries lanes that are still alive.
+ *
+ * Where the move comes from
+ *   The `conversation.input.dock` seat is rendered with `{ session, input }`
+ *   only (DSH's ConversationContent calls
+ *   `renderSlot('conversation.input.dock', { session, input })`), so no seat prop
+ *   can carry a workspace switch: a prop-based move is dead code that silently
+ *   degrades to "the worktree is ready, pick it in the workspace selector".
+ *   The platform keeps that call on a client service instead — the shell's own
+ *   workspace picker performs `uiWorkspace.openWorkspace(workspaceId,
+ *   migrateDraft)` — so calling the same service is the platform's navigation
+ *   policy rather than a second implementation of it, and it is reachable from a
+ *   plugin. It also reuses an existing blank conversation in that workspace
+ *   instead of piling up a second one.
+ *
+ *   `openWorkspace` reports the conversation it connected through the
+ *   `beforeOpen` callback, which is the only moment that identity exists on this
+ *   side. When the callback never fires (a later navigation superseded this one)
+ *   the session list is polled for the conversation whose cwd is the lane, so the
+ *   lane still gets its binding.
+ *
+ * The draft
+ *   `openWorkspace` moves the *view*, not the composer text: the shell migrates
+ *   draft text and attachments inside its own `beforeOpen`, and that half is not
+ *   plugin-reachable (`ctx.conversation.input.for(actx)` needs a retained
+ *   session scope). A prompt typed before the switch therefore stays in the
+ *   conversation it was typed in — persisted, and not silently dropped in
+ *   transit.
+ * @module @dsh-cove/dsh-client-ui-worktree/client/lane-open
+ */
+
+import type { BindLaneInput, BindLaneResult, CreateLaneInput, CreateLaneResult } from '../../../core/worktree/types.ts'
+
+/** The platform workspace navigation face (the call behind the shell's own workspace picker). */
+export interface LaneOpenNavigation {
+  /**
+   * Connect a workspace and show its conversation.
+   * @param workspaceId - the lane's registered workspace.
+   * @param beforeOpen - receives the conversation being shown, synchronously.
+   */
+  openWorkspace?: (workspaceId: string, beforeOpen?: (sessionId: string) => void) => Promise<void>
+}
+
+/** The session-list slice the fallback lookup reads. */
+export interface LaneOpenSessionList {
+  byId?: Record<string, { cwd?: string } | undefined>
+  ids?: readonly string[]
+}
+
+/** Everything one branch choice needs, injected so tests drive it without a network. */
+export interface LaneOpenDeps {
+  /** `POST /worktree/lane/create` — the worktree behind the branch. */
+  createLane(input: CreateLaneInput): Promise<CreateLaneResult>
+  /** `POST /worktree/lane/bind` — record the conversation and apply the lane preset. */
+  bindLane(input: BindLaneInput): Promise<BindLaneResult>
+  /** Platform navigation; absent on a shell that does not provide the service. */
+  navigation?: LaneOpenNavigation | undefined
+  /** Current session-list snapshot, used only for the superseded-navigation fallback. */
+  listSessions(): LaneOpenSessionList
+  /** Bounded-poll knobs for that fallback (test seam). */
+  timeoutMs?: number
+  pollMs?: number
+  /** Warning sink (test seam). */
+  warn?(message: string, error: unknown): void
+}
+
+/** One branch choice: the conversation asking, the repo, and the branch. */
+export interface LaneOpenInput {
+  /** The conversation that asked; undefined cannot be moved anywhere. */
+  sessionId: string | undefined
+  /** Repository root (any directory inside it resolves on the host). */
+  repoPath: string
+  /** Branch to check out in the lane; created at `base` when it does not exist. */
+  branch: string
+  /** Base commit-ish for a branch that has to be created. */
+  base?: string
+}
+
+/** The outcome of one branch choice, in worktree terms (the picker maps it to its own wire type). */
+export type LaneOpenResult =
+  | {
+    ok: true
+    /** The lane's branch. */
+    branch: string
+    /** True only when this conversation now runs in the lane's directory. */
+    opened: boolean
+  }
+  | {
+    ok: false
+    /** The host's message for the failure. */
+    message: string
+  }
+
+/** How often the fallback looks for the lane's conversation. */
+const LANE_SESSION_POLL_MS = 100
+/** How long the fallback waits for the shell to publish that conversation. */
+const LANE_SESSION_TIMEOUT_MS = 8_000
+
+/**
+ * Create (or attach) the branch's lane, move this conversation onto it, and
+ * record the binding.
+ *
+ * The lane is created first and never rolled back here: the worktree is a real
+ * place the user asked for, so a navigation that does not happen reports
+ * `opened: false` (the picker then says where to find it) instead of discarding
+ * the directory. A binding failure is reported and swallowed for the same
+ * reason — the conversation is in the lane either way, and the composer's own
+ * binder retries the record on its next status read.
+ * @param deps - the host calls, the navigation service and the session list.
+ * @param input - the conversation, repository and branch.
+ * @returns whether the conversation now runs in the lane.
+ */
+export async function openLaneForBranch(deps: LaneOpenDeps, input: LaneOpenInput): Promise<LaneOpenResult> {
+  let lane: CreateLaneResult
+  try {
+    lane = await deps.createLane({
+      repoPath: input.repoPath,
+      branch: input.branch,
+      ...(input.base === undefined ? {} : { base: input.base }),
+    })
+  } catch (error) {
+    return { ok: false, message: error instanceof Error ? error.message : String(error) }
+  }
+
+  const opened = await moveOntoLane(deps, input.sessionId, lane)
+  if (opened === undefined) return { ok: true, branch: lane.branch, opened: false }
+
+  try {
+    await deps.bindLane({ repoPath: input.repoPath, branch: lane.branch, sessionId: opened })
+  } catch (error) {
+    deps.warn?.('[dsh-worktree] lane binding failed:', error)
+  }
+  return { ok: true, branch: lane.branch, opened: true }
+}
+
+/**
+ * Show the conversation that runs in `lane`, when the shell can be asked at all.
+ * @returns the conversation now in the lane, or undefined when nothing moved.
+ */
+async function moveOntoLane(
+  deps: LaneOpenDeps,
+  sessionId: string | undefined,
+  lane: CreateLaneResult,
+): Promise<string | undefined> {
+  // Without a conversation to move, a workspace to connect, or a navigation
+  // service to ask there is nothing to do: the caller reports the lane as ready
+  // and says where to pick it up.
+  if (sessionId === undefined || lane.workspaceId === null) return undefined
+  const navigation = deps.navigation
+  if (navigation?.openWorkspace === undefined) return undefined
+
+  let opened: string | undefined
+  try {
+    await navigation.openWorkspace(lane.workspaceId, (sessionId) => { opened = sessionId })
+  } catch (error) {
+    deps.warn?.('[dsh-worktree] could not open a conversation on the lane:', error)
+    return undefined
+  }
+  if (opened !== undefined) return opened
+  // Superseded before it reported: the workspace may still have been connected,
+  // and the session list is then the only witness of the new conversation.
+  return await waitForLaneSession(deps, lane.path)
+}
+
+/**
+ * The conversation whose cwd is the lane directory, newest first, within the
+ * bounded wait. Used only when the navigation did not name it.
+ * @param deps - session list and the poll knobs.
+ * @param lanePath - the lane directory the conversation must run in.
+ * @returns the session id, or undefined when none appeared in time.
+ */
+export async function waitForLaneSession(deps: LaneOpenDeps, lanePath: string): Promise<string | undefined> {
+  const pollMs = deps.pollMs ?? LANE_SESSION_POLL_MS
+  const timeoutMs = deps.timeoutMs ?? LANE_SESSION_TIMEOUT_MS
+  const deadline = Date.now() + timeoutMs
+  for (;;) {
+    const snapshot = deps.listSessions()
+    const byId = snapshot.byId ?? {}
+    const ids = snapshot.ids ?? Object.keys(byId)
+    // Newest first: the shell's freshly connected draft is the one we want, and
+    // a lane with several conversations must not hand back an old one.
+    for (const id of [...ids].reverse()) {
+      if (byId[id]?.cwd === lanePath) return id
+    }
+    if (Date.now() >= deadline) return undefined
+    await new Promise((resolve) => { setTimeout(resolve, pollMs) })
+  }
+}

package/src/client/conversation/worktree/lane-workspace-sweeper.ts

@@ -0,0 +1,136 @@
+/**
+ * Retire the sidebar row of a lane whose conversations are all archived.
+ *
+ * Why a lane ever has a workspace row
+ *   The platform accounts a session to a workspace only while the session's cwd
+ *   equals that workspace's path (`WorkspaceEntity.sessionIds` filters by the
+ *   session's path, and `attachSession` refuses any other cwd), and a blank
+ *   conversation that no workspace accounts for renders an inert composer
+ *   ("choose a workspace to start"). So the lane's directory must BE a workspace
+ *   while a conversation runs in it — that part is a platform requirement, not a
+ *   taste, and no plugin can avoid the row.
+ *
+ * What this owns
+ *   The row's LIFETIME. Once every conversation the lane accounts for is
+ *   archived, the registration is dead weight: the directory, the branch and the
+ *   manifest binding stay, so picking that branch again re-registers the
+ *   directory in one call. The host half retires the same way from archive
+ *   events; this half runs where the archive set is visible to the browser, so it
+ *   also cleans up rows an earlier build left behind — including on an
+ *   installation whose host bundle predates that change.
+ *
+ * Safety rules
+ *   - only paths that are this plugin's lane directories (`<repo>/.dsh/workspaces/<branch>`);
+ *   - only workspaces that account for at least one conversation (a lane created
+ *     moments ago has none yet, and must not be retired from under its setup);
+ *   - only when every accounted conversation is archived. A lane with a live
+ *     conversation keeps its workspace, or that conversation loses the workspace
+ *     it runs in.
+ * @module @dsh-cove/dsh-client-ui-worktree/client/lane-workspace-sweeper
+ */
+
+import { isLaneDirectory } from '../../../core/worktree/paths.ts'
+
+/** The workspace-list slice the sweep reads (mirrors the client workspace snapshot). */
+export interface LaneSweepSnapshot {
+  /** `ready` once the host list has arrived; earlier phases carry no items. */
+  phase?: string
+  items?: readonly {
+    workspaceId?: string
+    path?: string
+    sessionIds?: readonly string[]
+  }[]
+  /** Complete registry-global archive set. */
+  archivedSessionIds?: readonly string[]
+}
+
+/** The client workspace face the sweep needs. */
+export interface LaneSweeperWorkspaces {
+  list?: {
+    getSnapshot?: () => LaneSweepSnapshot
+    subscribe?: (listener: () => void) => () => void
+  }
+  delete?: (workspaceId: string) => Promise<void>
+}
+
+/** Everything the sweep needs, injected so tests drive it without a browser. */
+export interface LaneSweeperFaces {
+  /** `ctx.workspaces` — the archived set and the delete command. */
+  workspaces?: LaneSweeperWorkspaces | undefined
+  /** Warning sink (test seam). */
+  warn?(message: string, error: unknown): void
+}
+
+/**
+ * The lane workspaces whose conversations are all archived, in snapshot order.
+ * @param snapshot - the client workspace snapshot.
+ * @returns workspace ids to retire.
+ */
+export function laneWorkspacesToRetire(snapshot: LaneSweepSnapshot | undefined): string[] {
+  if (snapshot === undefined || snapshot.phase !== 'ready') return []
+  const archived = new Set(snapshot.archivedSessionIds ?? [])
+  const retiring: string[] = []
+  for (const workspace of snapshot.items ?? []) {
+    const id = workspace.workspaceId
+    const path = workspace.path
+    const sessionIds = workspace.sessionIds ?? []
+    if (id === undefined || path === undefined) continue
+    if (!isLaneDirectory(path)) continue
+    // A lane created moments ago accounts for no conversation yet: its workspace
+    // is being set up and must survive the sweep.
+    if (sessionIds.length === 0) continue
+    // A live conversation needs the workspace it runs in.
+    if (!sessionIds.every((sessionId) => archived.has(sessionId))) continue
+    retiring.push(id)
+  }
+  return retiring
+}
+
+/**
+ * Sweep once: delete the registration of every lane whose conversations are all
+ * archived. A failure is reported and does not stop the rest.
+ * @param faces - the workspace face and the warning sink.
+ * @returns the workspace ids that were retired.
+ */
+export async function sweepLaneWorkspaces(faces: LaneSweeperFaces): Promise<string[]> {
+  const list = faces.workspaces?.list
+  const remove = faces.workspaces?.delete
+  if (list?.getSnapshot === undefined || remove === undefined) return []
+  const candidates = laneWorkspacesToRetire(list.getSnapshot())
+  const retired: string[] = []
+  for (const workspaceId of candidates) {
+    try {
+      await remove.call(faces.workspaces, workspaceId)
+      retired.push(workspaceId)
+    } catch (error) {
+      faces.warn?.('[dsh-worktree] could not retire a lane workspace:', error)
+    }
+  }
+  return retired
+}
+
+/**
+ * Sweep on mount and on every workspace-list change (an archive, a new lane, a
+ * deletion). Sweeps never overlap: a change arriving mid-sweep queues one more
+ * pass, so the pass always sees the list the changes produced.
+ * @param faces - the workspace face and the warning sink.
+ * @returns the disposer (unsubscribes).
+ */
+export function mountLaneWorkspaceSweeper(faces: LaneSweeperFaces): () => void {
+  const list = faces.workspaces?.list
+  if (list?.getSnapshot === undefined || list.subscribe === undefined) return () => {}
+  let running = false
+  let queued = false
+  const run = (): void => {
+    if (running) { queued = true; return }
+    running = true
+    void sweepLaneWorkspaces(faces).catch((error: unknown) => {
+      faces.warn?.('[dsh-worktree] lane workspace sweep failed:', error)
+    }).finally(() => {
+      running = false
+      if (queued) { queued = false; run() }
+    })
+  }
+  run()
+  return list.subscribe(run)
+}

package/src/client/conversation/worktree/lifecycle.ts

@@ -0,0 +1,75 @@
+/**
+ * Worktree lifecycle stage derivation (pure, shared with tests): given the
+ * disk truth and the latest status probe, classify a linked worktree into
+ * one of the four panel stages that drive its primary action.
+ *
+ * Also the single place that turns a client/host failure into localized copy:
+ * the panel and the dialogs must never print the host's English `message`
+ * verbatim in a Chinese UI, and a fence refusal must not read like a git bug.
+ * @module @dsh-cove/dsh-client-ui-worktree/client/lifecycle
+ */
+
+import type { Translate } from '@deepseek-ai/dsh-client-ui-slots'
+import type { WorktreeStatusView, WorktreeView } from '../../../core/worktree/types.ts'
+import type { WorktreeErrorCode } from '../../../core/worktree/invariant.ts'
+import { WorktreeApiError } from './api.ts'
+import type { WorktreeKey } from './locales.ts'
+
+/** Lifecycle stage of one linked worktree — drives the row's primary action. */
+export type WorktreeStage = 'missing' | 'developing' | 'in-review' | 'merged'
+
+export function stageOfWorktree(
+  worktree: Pick<WorktreeView, 'exists' | 'branch'>,
+  status: WorktreeStatusView | undefined,
+): WorktreeStage {
+  if (!worktree.exists) return 'missing'
+  if (status?.merged === true) return 'merged'
+  // A pushed branch with a recorded PR url is under review; anything else
+  // is still developing (submit-PR is the next step).
+  if (status?.prUrl != null && status.prUrl !== '') return 'in-review'
+  return 'developing'
+}
+
+/** The localized key for one domain error code. */
+function codeKeyOf(code: WorktreeErrorCode | undefined): WorktreeKey {
+  switch (code) {
+    case 'worktree-exists': return 'error.worktreeExists'
+    case 'worktree-not-found': return 'error.worktreeNotFound'
+    case 'not-a-repository': return 'error.notARepository'
+    case 'workspace-unknown': return 'error.workspaceUnknown'
+    case 'invalid-branch': return 'error.invalidBranch'
+    case 'worktree-busy': return 'error.worktreeBusy'
+    case 'not-merged': return 'error.notMerged'
+    case 'session-create-failed':
+    case 'session-unknown': return 'error.laneSession'
+    case 'lane-mismatch': return 'error.laneMismatch'
+    default: return 'error.gitFailed'
+  }
+}
+
+/**
+ * The localized key explaining one failure, or null when the error carries no
+ * known shape (the caller then shows its own message).
+ */
+export function worktreeErrorKeyOf(error: unknown): WorktreeKey | null {
+  if (error instanceof WorktreeApiError) {
+    if (error.kind === 'permission') return 'error.permissionDenied'
+    if (error.kind === 'malformed' || error.kind === 'transport') return 'error.unreachable'
+    return codeKeyOf(error.code)
+  }
+  return null
+}
+
+/**
+ * Render one failure as user-facing copy.
+ * @param error - any thrown value from the worktree API.
+ * @param t - the `worktree` namespace translator.
+ * @returns localized text, with the raw detail attached for the git/unreachable cases.
+ */
+export function worktreeErrorMessage(error: unknown, t: Translate<WorktreeKey>): string {
+  const detail = error instanceof Error ? error.message : String(error)
+  const key = worktreeErrorKeyOf(error)
+  if (key === null) return detail
+  if (key === 'error.gitFailed' || key === 'error.unreachable') return t(key, { error: detail })
+  return t(key)
+}