Merge branch 'master' into worktree/routed-model-compaction-policy

packages/README.md

@@ -15,6 +15,7 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: the abstract runtime seam for model-written programs + a worker-thread backend | Product — stable surface |
 | [`sandbox/`](sandbox/README.md) | Process-confinement seam; bwrap/Landlock/Seatbelt backends | Product — stable surface |
 | [`fs/`](fs/README.md) | Filesystem capability family: the abstract seam, a local impl, the model-facing file tools, and the bash-backed discovery tools | Product — stable surface |
+| [`lsp/`](lsp/README.md) | LSP capability family: seam, generic stdio provider, and the `lsp` tool | Product — stable surface |
 | [`skill/`](skill/README.md) | Skill capability family: the provider registry, local provider, and model-facing catalog/loader | Product — stable surface |
 | [`compact/`](compact/README.md) | Compaction capability family: the abstract seam + a basic backend (tool deferred) | Product — stable surface |
 | [`context/`](context/README.md) | Model-visible request context, including workspace instructions and time context | Product — stable surface |

packages/core/agent/README.md

@@ -8,7 +8,7 @@ Tracks live agents and carries the initiating Agent through asynchronous driver
 
 ### Public API
 
-The scoped-registration surface: `Agent.ctx` is the agent's scope context (`dsh-scope`, key = the agent) — register tools/sections/variables/listeners through it for that agent alone, all unwound on disposal. `agentEvents(ctx, agent)` is the fused dispatcher for ordinary agent-subject operations (carrier + injected subject in one move); its notification mode invokes every listener and contains both synchronous throws and returned-promise rejections. The registry lifecycle pair reuses one stable routing carrier. `assembleContextFor(agent)` builds the per-agent assembly context (`agent` + `scope` together). `CreateAgentOptions.setup(agentCtx)` and `ResumeAgentOptions.setup(agentCtx)` compose a fresh or resumed agent's scoped world while both objects remain unpublished. Setup is trusted, composition-only same-process code: drive the agent only after creation resolves.
+The scoped-registration surface: `Agent.ctx` is the agent's scope context (`dsh-scope`, key = the agent) — register tools/sections/variables/listeners through it for that agent alone, all unwound on disposal. `agentEvents(ctx, agent)` is the fused dispatcher for ordinary agent-subject operations (carrier + injected subject in one move); its notification mode invokes every listener and contains both synchronous throws and returned-promise rejections. The registry lifecycle pair reuses one stable routing carrier. `assembleContextFor(agent)` builds the per-agent assembly context (`agent` + `scope` together). `installAgentLlmTarget(agentCtx, target)` snapshots a mutable provider/model selection during prompt assembly and applies that pair to both prompt variables and request routing for one step. `CreateAgentOptions.setup(agentCtx)` and `ResumeAgentOptions.setup(agentCtx)` compose a fresh or resumed agent's scoped world while both objects remain unpublished. Setup is trusted, composition-only same-process code: drive the agent only after creation resolves.
 
 - `ctx.agents.register(agent: Agent): () => void` — record an **already-constructed** agent. Disposed with the calling fiber.
 - Advanced ordered lifecycle: `enter(agent, owner): () => void` enforces `agent.id === agent.session.id`, performs the authoritative ID collision check, and inserts without announcing; `owner` explicitly records the live creator-agent relation (or `undefined` for a root), independently of durable session lineage. `announce(agent)` emits `agent/created` exactly once. A detach requested synchronously by a creation listener is deferred until that dispatch unwinds, and every detach checks the captured entry object, so a stale capability cannot delete a later same-ID replacement. The async factory uses this split; ordinary plugins use `register()`.

packages/core/agent/src/index.ts

@@ -15,6 +15,7 @@ import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
 import type { Agent, AgentOptions } from './types.ts'
 
 export * from './types.ts'
+export * from './llm-target.ts'
 export { agentEvents, assembleContextFor } from './dispatch.ts'
 export type { AgentEventDispatch, AgentSubjectEvent } from './dispatch.ts'
 

packages/core/agent/src/llm-target.ts

@@ -0,0 +1,66 @@
+/**
+ * Agent-scoped provider/model target snapshot shared by interactive front doors.
+ * @module @deepseek-ai/dsh-agent/llm-target
+ */
+
+import type { Context } from 'cordis'
+import type { LlmCallConfig } from '@deepseek-ai/dsh-llm'
+
+/** Complete provider/model route selected for one live agent. */
+export interface AgentLlmTarget {
+  /** Registered provider route. */
+  provider: string
+  /** Provider-owned model id. */
+  model: string
+}
+
+/** Mutable selection plus the target captured for the current step. */
+export interface AgentLlmTargetRef {
+  /** Target selected for the next step that enters prompt assembly. */
+  current: AgentLlmTarget | undefined
+  /** Target captured when the current step entered prompt assembly. */
+  assembled: AgentLlmTarget | undefined
+}
+
+/**
+ * Couple one mutable target to agent-scoped prompt assembly and request routing.
+ * Prompt assembly snapshots the selected pair before delegating, then applies
+ * both prompt variables and request config to that snapshot so a concurrent
+ * switch takes effect on a later step instead of splitting the two surfaces.
+ *
+ * @param agentCtx - The target agent's scoped context.
+ * @param target - Mutable selection owned by the calling front door.
+ * @returns Disposer for both scoped waterfall listeners.
+ */
+export function installAgentLlmTarget(agentCtx: Context, target: AgentLlmTargetRef): () => void {
+  const disposeAssembly = agentCtx.on('system-prompt/assemble', async (_assembly, _context, next) => {
+    const selected = target.current
+    const assembled = await next()
+    target.assembled = selected
+    if (selected === undefined) return assembled
+    return {
+      ...assembled,
+      variables: {
+        ...assembled.variables,
+        provider: selected.provider,
+        model: selected.model,
+      },
+    }
+  })
+  const disposeRequest = agentCtx.on(
+    'agent/request',
+    async (_agent, _turn, _step, _config, next): Promise<LlmCallConfig> => {
+      const resolved = await next()
+      const selected = target.assembled
+      return selected === undefined ? resolved : {
+        ...resolved,
+        provider: selected.provider,
+        model: selected.model,
+      }
+    },
+  )
+  return () => {
+    disposeAssembly()
+    disposeRequest()
+  }
+}

packages/core/agent/tests/llm-target.spec.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import {
+  agentEvents,
+  installAgentLlmTarget,
+  type Agent,
+  type AgentLlmTargetRef,
+} from '../src/index.ts'
+import type { LlmCallConfig } from '@deepseek-ai/dsh-llm'
+
+describe('installAgentLlmTarget()', () => {
+  it('snapshots prompt variables and request routing together, then disposes both listeners', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    const target: AgentLlmTargetRef = { current: undefined, assembled: undefined }
+    const dispose = installAgentLlmTarget(ctx, target)
+    const agent = {} as Agent
+    const seed: LlmCallConfig = { provider: 'seed', model: 'seed', temperature: 0.2 }
+
+    expect((await ctx.systemPrompt.assemble()).variables).toEqual({})
+    await expect(agentEvents(ctx, agent).waterfall(
+      'agent/request', 1, 0, seed, () => Promise.resolve(seed),
+    )).resolves.toBe(seed)
+
+    target.current = { provider: 'alpha', model: 'a1' }
+    expect((await ctx.systemPrompt.assemble()).variables).toMatchObject({ provider: 'alpha', model: 'a1' })
+    target.current = { provider: 'beta', model: 'b1' }
+    await expect(agentEvents(ctx, agent).waterfall(
+      'agent/request', 1, 0, seed, () => Promise.resolve(seed),
+    )).resolves.toEqual({ provider: 'alpha', model: 'a1', temperature: 0.2 })
+
+    expect((await ctx.systemPrompt.assemble()).variables).toMatchObject({ provider: 'beta', model: 'b1' })
+    await expect(agentEvents(ctx, agent).waterfall(
+      'agent/request', 1, 1, seed, () => Promise.resolve(seed),
+    )).resolves.toEqual({ provider: 'beta', model: 'b1', temperature: 0.2 })
+
+    dispose()
+    expect((await ctx.systemPrompt.assemble()).variables).toEqual({})
+    await expect(agentEvents(ctx, agent).waterfall(
+      'agent/request', 2, 0, seed, () => Promise.resolve(seed),
+    )).resolves.toBe(seed)
+    await ctx.fiber.dispose()
+  })
+})

packages/core/tools/tests/gen-tool-catalog.spec.ts

@@ -23,7 +23,7 @@ describe('gen-tool-catalog collectToolCatalog', () => {
   it('boots every shipped tool package and harvests its model-facing schemas', async () => {
     const catalog = await collectToolCatalog()
     const names = catalog.flatMap(entry => entry.schemas.map(s => s.name)).sort()
-    expect(names).toEqual(['ask_user_question', 'bash', 'cordis_inspect', 'cordis_mount', 'cordis_unmount', 'create_goal', 'edit', 'get_goal', 'glob', 'grep', 'ralph', 'read', 'run_code', 'skill', 'subagent', 'task_kill', 'task_list', 'task_output', 'todo_write', 'update_goal', 'web_fetch', 'web_search', 'workflow', 'write'])
+    expect(names).toEqual(['ask_user_question', 'bash', 'cordis_inspect', 'cordis_mount', 'cordis_unmount', 'create_goal', 'edit', 'get_goal', 'glob', 'grep', 'lsp', 'ralph', 'read', 'run_code', 'skill', 'subagent', 'task_kill', 'task_list', 'task_output', 'todo_write', 'update_goal', 'web_fetch', 'web_search', 'workflow', 'write'])
     // Every tool carries a JSON-Schema `parameters` object (what the model sees).
     for (const entry of catalog) {
       for (const schema of entry.schemas) {

packages/lsp/README.md

@@ -0,0 +1,13 @@
+# lsp/ - LSP capability family
+
+The language-server capability seam: an abstract LSP interface, a generic stdio provider, and the model-facing `lsp` tool. All **product** packages.
+
+| Package | Role | ctx key |
+|---|---|---|
+| `lsp/` | Abstract LSP seam (provider registry by branded id + extension mapping, per-query selection, vocabulary, `LspError`) | `ctx.lsp` |
+| `lsp-local/` | Generic multi-server local backend (spawn, JSON-RPC, transient-open queries) | (registers providers on `ctx.lsp`) |
+| `tool-lsp/` | Model-facing `lsp` tool (four operations, one-based UTF-16 cursor coordinates) | (registers on `ctx.tools`) |
+
+The interface lives at `lsp/lsp/`. The seam exposes exactly four semantic operations — `goToDefinition`, `findReferences`, `goToImplementation`, `hover` — and no generic JSON-RPC escape hatch, so a provider swap does not change how the model asks for navigation and no protocol payload or unreviewed mutation reaches the model contract. Providers register **capabilities**, not tools; `tool-lsp` is the only owner of the model-facing name, schema, prompt guidance, and presentation.
+
+See the [LSP capability seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) for the design rationale, including why documents open transiently per query, why the local host reads through Node APIs rather than `ctx.fs`, and why extension ownership is exclusive within one runtime.

packages/lsp/lsp-local/README.md

@@ -0,0 +1,55 @@
+# @deepseek-ai/dsh-lsp-local
+
+A **generic local stdio language-server backend** for `ctx.lsp`. One plugin instance accepts a named server table and registers one isolated provider per entry. This is a generic host, not a language-server catalog or installer — deployments configure commands and mappings explicitly; presets belong in `cordis.yml` overlays.
+
+Namespace plugin (`name` / `inject` / `Config` / `apply`, no default export).
+
+## What it does
+
+- Resolves every server-local setting before registration; an invalid mapping or registration conflict rolls back earlier entries, so a failed load leaves no provider routes.
+- Lazily single-flights one server process per `(server id, canonical workspace realpath)`. A crash fails the active query without replay; a later query may replace the process.
+- Uses a compatibility-first **transient-open** sequence per query: canonicalize and read the source with Node APIs, `textDocument/didOpen` (version 1, full text), the requested request, then `textDocument/didClose` in `finally`. A failed or canceled `didOpen` write terminates the instance before the pool can reuse it. Documents close after each call, so the first version needs no `didChange`, content cache, or document LRU.
+- Serializes each source-read/open/query/close lifecycle through one abortable per-workspace queue so queued calls read current source only when their turn starts; distinct workspaces run in parallel.
+- Reads sources through Node filesystem APIs in the subprocess's host namespace — NOT `ctx.fs`, and emits no `fs/observed`: only the LSP result is model-visible, so a query does not satisfy read-before-write policy.
+
+## Configuration
+
+The `servers` record key is the stable provider id reserved on `ctx.lsp`; each value has this shape:
+
+| Server key | Default | Meaning |
+|---|---|---|
+| `command` | (required) | Executable to spawn — absolute, or resolved on the child PATH at load. Launch uses no shell. |
+| `args` | `[]` | Arguments passed to the executable. |
+| `env` | `{}` | Extra env merged on top of the credential-scrubbed ambient env (vars matching `KEY`/`SECRET`/`TOKEN` are not forwarded). |
+| `extensionToLanguage` | (required) | Lowercase leading-dot extension → LSP language id (e.g. `{ '.ts': 'typescript' }`). |
+| `initializationOptions` | `null` | Static `initialize` options forwarded to the server. |
+| `configuration` | `null` | Static answer to every `workspace/configuration` item. |
+| `maxMessageBytes` | `16000000` | Largest single framed message accepted from the server. |
+| `maxStderrBytes` | `1000000` | Largest stderr tail retained for diagnostics. |
+| `maxDocumentBytes` | `4000000` | Largest source file this host will open. |
+| `shutdownTimeoutMs` | `5000` | Graceful `shutdown`/`exit` budget before escalation. |
+| `killGraceMs` | `2000` | Grace for request cancellation and for SIGTERM→SIGKILL escalation. |
+
+`servers` must contain at least one entry, and every id must be non-empty. Timer budgets must be positive integers no greater than Node's `2_147_483_647` ms timer limit. All executables resolve at load after credential scrubbing; a bad later entry prevents every provider from registering. Processes launch lazily on the first matching query.
+
+## Protocol behavior
+
+Initialization advertises `general.positionEncodings: ['utf-16']`, `workspace: { workspaceFolders: true, configuration: true }`, `textDocument.hover.contentFormat: ['markdown', 'plaintext']`, and `linkSupport: true` for definition and implementation, with no dynamic registration. The server's returned capabilities are authoritative: an unsupported operation, or synchronization without transient open/close, fails the query. An omitted server `positionEncoding` defaults to `utf-16`; any other value is a protocol error. The client answers `workspace/configuration` from static config, accepts lifecycle bookkeeping requests, and rejects `workspace/applyEdit` — it never applies edits or runs commands. Navigation maps `Location` directly and `LocationLink` from `targetUri` + `targetSelectionRange`; hover normalization takes valid `MarkupContent.value`, preserves string `MarkedString`s, renders language-tagged values as fenced code, and joins arrays with one blank line. Missing results, malformed ranges or positions, and malformed hover encodings fail as structured `LSP_MALFORMED_RESPONSE` errors.
+
+## Security boundary
+
+The provider trusts its configured server and claims no sandbox confinement. It canonicalizes and reads source through Node APIs, rejecting a source that is missing, non-regular, non-UTF-8, oversized, or whose canonical path resolves outside the canonical workspace (symlink aliases share one instance). Result locations may be external, but an external path cannot become a query source. The first implementation therefore requires trusted host-local deployment; restricted, remote, or virtual workspaces require another provider.
+
+## Model Experience
+
+Indirectly, through `dsh-tool-lsp`, which surfaces this provider's normalized results; this host contributes no prompt or schema itself.
+
+#### KV Cache effect
+
+No direct invalidation; `dsh-tool-lsp` owns request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **Trusted host-local only** — no sandbox confinement, no private cache/temp write contract; supporting untrusted binaries or restricted/remote/virtual workspaces requires a later process/filesystem contract and a different provider ([seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)). Containment resolves `realpath`, then opens the source through one handle with `O_NOFOLLOW | O_NONBLOCK` (final-component symlink guard plus nonblocking rejection of FIFOs) and a bounded read; a concurrent mutator that swaps an *ancestor* directory for a symlink between the resolve and the open is an accepted residual TOCTOU under this trusted-deployment model, not closed with non-portable `openat` segment walks.
+- **Transient-open compatibility floor** — servers whose synchronization omits open/close (or advertise `None`) are unsupported even if closed-document queries would work; the pinned TypeScript e2e establishes one compatibility floor, not a cross-language claim.
+- **Per-server/workspace serialization latency** — parallel agents sharing one server and workspace queue behind one process; long-lived workspace processes consume memory until disposal.

packages/lsp/lsp-local/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@deepseek-ai/dsh-lsp-local",
+  "description": "Generic stdio language-server provider for the DeepSeek Harness LSP capability seam (ctx.lsp) — spawns configured servers, translates JSON-RPC, and serves transient-open goToDefinition/findReferences/goToImplementation/hover queries in the host filesystem namespace",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-brand": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-lsp": "^0.0.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-lsp": "workspace:^",
+    "@deepseek-ai/dsh-timeout": "workspace:^",
+    "cordis": "^4.0.0-rc.7",
+    "typescript": "^6.0.3",
+    "typescript-language-server": "^5.0.0"
+  }
+}

packages/lsp/lsp-local/src/abort.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared cancellation helpers for the local LSP provider's host-I/O, queue, and protocol phases.
+ * @module @deepseek-ai/dsh-lsp-local/abort
+ */
+
+import { timeoutOf } from '@deepseek-ai/dsh-timeout'
+
+/**
+ * Build an abort Error carrying the signal's reason and preserving timeout classification.
+ * @param signal - the aborted signal whose reason to surface.
+ * @returns the timeout reason if present, else the Error reason, else a generic aborted Error.
+ */
+export function abortError(signal: AbortSignal): Error {
+  const timeout = timeoutOf(signal)
+  if (timeout !== undefined) return timeout
+  const reason: unknown = signal.reason
+  if (reason instanceof Error) return reason
+  return new Error('LSP query aborted')
+}
+
+/**
+ * Throw the signal's classified abort error when it has already fired.
+ * @param signal - the optional query cancellation signal.
+ */
+export function throwIfAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) throw abortError(signal)
+}
+
+/**
+ * Await work while allowing a query signal to abandon its wait; the underlying work keeps its own
+ * handlers and continues to its owner-defined quiescence boundary.
+ * @param work - the owned asynchronous work.
+ * @param signal - optional query cancellation.
+ * @returns the work result, or a rejection carrying the classified abort reason.
+ */
+export function abortable<T>(work: Promise<T>, signal?: AbortSignal): Promise<T> {
+  if (signal === undefined) return work
+  if (signal.aborted) return Promise.reject(abortError(signal))
+  const canceled = Promise.withResolvers<never>()
+  const onAbort = (): void => { canceled.reject(abortError(signal)) }
+  signal.addEventListener('abort', onAbort, { once: true })
+  const normalized = work.catch((error: unknown) => {
+    /* v8 ignore next -- owned LSP promises reject with Error; coercion defends the generic helper. */
+    throw error instanceof Error ? error : new Error(String(error))
+  })
+  return Promise.race([normalized, canceled.promise])
+    .finally(() => { signal.removeEventListener('abort', onAbort) })
+}

packages/lsp/lsp-local/src/connection.ts

@@ -0,0 +1,331 @@
+/**
+ * A JSON-RPC endpoint over one spawned language server's stdio. Owns id correlation, outbound
+ * requests/notifications, and inbound server→client requests: it answers `workspace/configuration`
+ * from static config, and rejects `workspace/applyEdit` (this host never applies edits or runs
+ * commands). It caps stderr, surfaces framing/decoder failures as a fatal close, and exposes the
+ * child handle so the instance owns process-signal teardown.
+ * @module @deepseek-ai/dsh-lsp-local/connection
+ */
+
+import type { ChildProcessByStdio } from 'node:child_process'
+import { spawn } from 'node:child_process'
+import type { Readable, Writable } from 'node:stream'
+import { setImmediate as yieldToEventLoop } from 'node:timers/promises'
+import { encodeMessage, MessageDecoder } from './framing.ts'
+
+/** How to launch the server and answer its config requests. */
+export interface ConnectionSpec {
+  /** The resolved absolute executable path (no shell). */
+  readonly command: string
+  /** Arguments passed to the executable. */
+  readonly args: readonly string[]
+  /** The child's working directory (the canonical workspace). */
+  readonly cwd: string
+  /** The child's environment (credential-scrubbed, with overrides applied). */
+  readonly env: Record<string, string>
+  /** Largest single framed message accepted from the server. */
+  readonly maxMessageBytes: number
+  /** Largest stderr tail retained for diagnostics. */
+  readonly maxStderrBytes: number
+  /** Static answer to every `workspace/configuration` item. */
+  readonly configuration: unknown
+}
+
+interface Pending {
+  resolve: (value: unknown) => void
+  reject: (error: Error) => void
+}
+
+/** A live JSON-RPC endpoint bound to one child process. */
+export class LspConnection {
+  private readonly child: ChildProcessByStdio<Writable, Readable, Readable>
+  private readonly decoder: MessageDecoder
+  private readonly pending = new Map<number, Pending>()
+  private nextId = 1
+  private stderr = Buffer.alloc(0)
+  private closeReason: Error | undefined
+  /** Set once the process has fully exited; the instance awaits it during teardown. */
+  readonly closed: Promise<void>
+
+  /**
+   * @param spec - how to launch the server and answer its config requests.
+   * @param onServerRequest - answers a server→client request; rejects to send an error response.
+   */
+  constructor(
+    private readonly spec: ConnectionSpec,
+    private readonly onServerRequest: (method: string, params: unknown) => Promise<unknown>,
+  ) {
+    this.decoder = new MessageDecoder(spec.maxMessageBytes)
+    // `detached` puts the server in its own process group so teardown can signal the WHOLE group
+    // (via `process.kill(-pid)`), reaching helper processes a language server spawns (e.g. tsserver).
+    this.child = spawn(spec.command, [...spec.args], {
+      cwd: spec.cwd,
+      env: spec.env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      detached: true,
+    })
+    this.closed = new Promise<void>((resolve) => {
+      this.child.on('close', () => {
+        const reason = this.closeReason ?? new Error(this.exitMessage())
+        // Record the reason so any request issued AFTER close rejects immediately instead of hanging
+        // (a closed process sends no further responses).
+        this.closeReason = reason
+        this.failAll(reason)
+        resolve()
+      })
+    })
+    this.child.on('error', (error) => { this.fail(error) })
+    // Child stdin can fail while the process itself remains alive (for example, a server closes fd
+    // 0). Treat that as a fatal connection error so pending requests reject immediately instead of
+    // waiting for a process-close event that may never arrive.
+    this.child.stdin.on('error', (error) => { this.fail(error) })
+    this.child.stdout.on('data', (chunk: Buffer) => { this.onStdout(chunk) })
+    this.child.stderr.on('data', (chunk: Buffer) => { this.onStderr(chunk) })
+  }
+
+  /** The child's pid, or `-1` when the spawn produced no pid (so signalling is a no-op). */
+  get pid(): number {
+    /* v8 ignore next -- the `-1` fallback only applies to a spawn that produced no pid; defensive. */
+    return this.child.pid ?? -1
+  }
+
+  /** The retained stderr tail, for diagnostics on a failed server. */
+  get stderrTail(): string {
+    return this.stderr.toString('utf8')
+  }
+
+  /**
+   * Send a request and await its result.
+   * @param method - the JSON-RPC method.
+   * @param params - the request params.
+   * @returns the response result; rejects on an error response, write failure, or close.
+   */
+  request(method: string, params: unknown): Promise<unknown> {
+    const id = this.nextId++
+    const promise = new Promise<unknown>((resolve, reject) => {
+      if (this.closeReason !== undefined) {
+        reject(this.closeReason)
+        return
+      }
+      this.pending.set(id, { resolve, reject })
+      // `write()` records either synchronous or callback-delivered failures on the connection and
+      // rejects every pending request. This handler only consumes the write promise itself.
+      void this.write({ jsonrpc: '2.0', id, method, params }).catch(() => {})
+    })
+    // A caller that stops awaiting (e.g. an aborted query) can leave this promise to reject later
+    // when the process closes; a benign no-op handler keeps that from surfacing as an unhandled
+    // rejection. The returned promise still delivers the rejection to the caller's own await/catch.
+    promise.catch(() => {})
+    return promise
+  }
+
+  /**
+   * Send a notification (no id, no response).
+   * @param method - the JSON-RPC method.
+   * @param params - the notification params.
+   * @returns a promise that settles when the framed notification has been written.
+   */
+  notify(method: string, params: unknown): Promise<void> {
+    return this.write({ jsonrpc: '2.0', method, params })
+  }
+
+  /**
+   * Send a `$/cancelRequest` for an in-flight request id (best-effort; ignores write failure).
+   * @param requestId - the numeric id of the request to cancel.
+   */
+  cancel(requestId: number): void {
+    // The server is already gone or unwritable when this rejects; `write()` has recorded the fatal
+    // connection failure and rejected the pending request, so cancellation remains best-effort.
+    void this.write({ jsonrpc: '2.0', method: '$/cancelRequest', params: { id: requestId } }).catch(() => {})
+  }
+
+  /**
+   * The id the NEXT `request()` will use, so the instance can pre-arm a cancel.
+   * @returns the numeric id the next request will be assigned.
+   */
+  peekNextId(): number {
+    return this.nextId
+  }
+
+  /** Send SIGTERM to the server's process group (idempotent-safe; a dead group ignores it). */
+  terminate(): void {
+    this.signalGroup('SIGTERM')
+  }
+
+  /** Send SIGKILL to the server's process group. */
+  kill(): void {
+    this.signalGroup('SIGKILL')
+  }
+
+  /**
+   * Wait until the owned process group has no members.
+   * @param signal - optional bound for the wait.
+   * @returns `true` when the group exited, or `false` when the signal aborted first.
+   */
+  async waitForProcessGroupExit(signal?: AbortSignal): Promise<boolean> {
+    while (this.processGroupAlive()) {
+      if (signal?.aborted) return false
+      await yieldToEventLoop()
+    }
+    return true
+  }
+
+  /**
+   * Signal the whole process group (negative pid) so helper processes are reached; fall back to the
+   * direct child if the group send fails. Never throws — teardown races process exit.
+   */
+  private signalGroup(sig: NodeJS.Signals): void {
+    const pid = this.child.pid
+    if (pid === undefined) return
+    try {
+      process.kill(-pid, sig)
+    } catch {
+      // The group is gone (already exited) or could not be signalled; try the direct child.
+      try {
+        this.child.kill(sig)
+      } catch {
+        // Already dead; nothing to signal.
+      }
+    }
+  }
+
+  /** Whether the detached process group still has at least one member. */
+  private processGroupAlive(): boolean {
+    const pid = this.child.pid
+    /* v8 ignore next -- only an asynchronous spawn failure omits pid; its close path owns cleanup. */
+    if (pid === undefined) return false
+    try {
+      process.kill(-pid, 0)
+      return true
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code
+      /* v8 ignore next -- POSIX reports an absent group as ESRCH, but child-reaping timing makes
+         whether lifecycle tests observe this branch platform-dependent. */
+      if (code === 'ESRCH') return false
+      /* v8 ignore start -- EPERM and non-POSIX negative-pid failures are platform defenses; CI runs
+         process-group lifecycle tests on POSIX hosts where absence reports ESRCH. */
+      if (code === 'EPERM') return true
+      return this.child.exitCode === null && this.child.signalCode === null
+      /* v8 ignore stop */
+    }
+  }
+
+  private onStdout(chunk: Buffer): void {
+    let messages: unknown[]
+    try {
+      messages = this.decoder.push(chunk)
+    } catch (error) {
+      // A framing/JSON failure corrupts the stream position irrecoverably: fail the instance and
+      // SIGKILL the whole group so helper processes don't outlive the leader.
+      this.fail(asError(error))
+      this.signalGroup('SIGKILL')
+      return
+    }
+    for (const message of messages) this.dispatch(message)
+  }
+
+  private onStderr(chunk: Buffer): void {
+    // Retain the TAIL, not the prefix: a language server's fatal diagnostic usually appears just
+    // before it exits, so the final bounded segment is the useful one.
+    const cap = this.spec.maxStderrBytes
+    if (chunk.length >= cap) {
+      // Copy the bounded suffix so retaining it does not pin an arbitrarily large incoming buffer.
+      this.stderr = Buffer.from(chunk.subarray(chunk.length - cap))
+      return
+    }
+    const retainedBytes = Math.min(this.stderr.length, cap - chunk.length)
+    this.stderr = Buffer.concat([
+      this.stderr.subarray(this.stderr.length - retainedBytes),
+      chunk,
+    ], retainedBytes + chunk.length)
+  }
+
+  private dispatch(message: unknown): void {
+    if (message === null || typeof message !== 'object') return
+    const frame = message as Record<string, unknown>
+    const id = frame.id
+    const method = frame.method
+    if (typeof method === 'string' && (typeof id === 'number' || typeof id === 'string')) {
+      // A response-write failure has already invalidated the connection in `write()`.
+      /* v8 ignore next -- protocol tests exercise response writes; only a simultaneous connection
+         failure makes this consumption handler run. */
+      void this.handleServerRequest(id, method, frame.params).catch(() => {})
+      return
+    }
+    if (typeof method === 'string') {
+      // A server→client notification (e.g. diagnostics, logs): ignored by this MVP host.
+      return
+    }
+    if (typeof id === 'number') this.handleResponse(id, frame)
+  }
+
+  private async handleServerRequest(id: number | string, method: string, params: unknown): Promise<void> {
+    try {
+      const result = await this.onServerRequest(method, params)
+      await this.write({ jsonrpc: '2.0', id, result })
+    } catch (error) {
+      await this.write({ jsonrpc: '2.0', id, error: { code: -32601, message: asError(error).message } })
+    }
+  }
+
+  private handleResponse(id: number, frame: Record<string, unknown>): void {
+    const pending = this.pending.get(id)
+    if (!pending) return
+    this.pending.delete(id)
+    const error = frame.error
+    if (error !== null && typeof error === 'object') {
+      const record = error as Record<string, unknown>
+      pending.reject(new Error(typeof record.message === 'string' ? record.message : 'LSP error response'))
+      return
+    }
+    pending.resolve(frame.result)
+  }
+
+  private write(message: unknown): Promise<void> {
+    if (this.closeReason !== undefined) return Promise.reject(this.closeReason)
+    return new Promise<void>((resolve, reject) => {
+      const done = (error?: Error | null): void => {
+        if (error === undefined || error === null) {
+          resolve()
+          return
+        }
+        this.fail(error)
+        reject(error)
+      }
+      try {
+        this.child.stdin.write(encodeMessage(message), done)
+      /* v8 ignore start -- Node stream write failures are callback-delivered; this guards a
+         nonconforming Writable implementation throwing synchronously. */
+      } catch (error) {
+        const failure = asError(error)
+        this.fail(failure)
+        reject(failure)
+      }
+      /* v8 ignore stop */
+    })
+  }
+
+  /** The exit-close error message, appending the retained stderr tail when the server wrote any. */
+  private exitMessage(): string {
+    const tail = this.stderrTail.trim()
+    return tail === '' ? 'language server exited' : `language server exited; stderr: ${tail}`
+  }
+
+  private fail(error: Error): void {
+    /* v8 ignore next -- the second arm (closeReason already set) needs two fail() calls before close; defensive. */
+    if (this.closeReason === undefined) this.closeReason = error
+    this.failAll(error)
+  }
+
+  private failAll(error: Error): void {
+    const waiting = [...this.pending.values()]
+    this.pending.clear()
+    for (const pending of waiting) pending.reject(error)
+  }
+}
+
+/** Coerce an unknown thrown value to an `Error`. */
+function asError(value: unknown): Error {
+  /* v8 ignore next -- the non-Error branch guards against a non-Error throw, which our paths never produce. */
+  return value instanceof Error ? value : new Error(String(value))
+}

packages/lsp/lsp-local/src/framing.ts

@@ -0,0 +1,102 @@
+/**
+ * LSP base-protocol framing: `Content-Length`-delimited JSON-RPC over a byte stream. The encoder
+ * produces one framed buffer; the decoder buffers incoming bytes and yields complete message bodies,
+ * bounding the header and total message size so a hostile or broken server cannot exhaust memory.
+ * @module @deepseek-ai/dsh-lsp-local/framing
+ */
+
+/** The header/body separator in the LSP base protocol. */
+const HEADER_SEPARATOR = '\r\n\r\n'
+
+/** Cap on the header section so a server that never sends the separator cannot grow the buffer forever. */
+const MAX_HEADER_BYTES = 1 << 16
+
+/**
+ * Encode one JSON-RPC message as a framed LSP buffer (`Content-Length: N\r\n\r\n<utf-8 json>`).
+ * @param message - the JSON-RPC message object to serialize.
+ * @returns the framed bytes ready to write to the server's stdin.
+ */
+export function encodeMessage(message: unknown): Buffer {
+  const body = Buffer.from(JSON.stringify(message), 'utf8')
+  const header = Buffer.from(`Content-Length: ${body.length}\r\n\r\n`, 'ascii')
+  return Buffer.concat([header, body])
+}
+
+/**
+ * A streaming decoder for `Content-Length`-framed JSON-RPC. Feed it stdout chunks; it returns any
+ * whole message bodies that completed. It parses only the `Content-Length` header and ignores other
+ * headers (e.g. `Content-Type`), matching the base protocol.
+ */
+export class MessageDecoder {
+  private buffer: Buffer = Buffer.alloc(0)
+  private readonly maxMessageBytes: number
+
+  /**
+   * @param maxMessageBytes - reject any single framed body larger than this (guards memory).
+   */
+  constructor(maxMessageBytes: number) {
+    this.maxMessageBytes = maxMessageBytes
+  }
+
+  /**
+   * Append a chunk and return every message body that is now complete.
+   * @param chunk - raw bytes from the server's stdout.
+   * @returns the parsed JSON bodies, in arrival order (possibly empty).
+   * @throws Error when a header is malformed or a body exceeds `maxMessageBytes`.
+   */
+  push(chunk: Buffer): unknown[] {
+    this.buffer = this.buffer.length === 0 ? chunk : Buffer.concat([this.buffer, chunk])
+    const messages: unknown[] = []
+    for (;;) {
+      const step = this.next()
+      if (!step.ready) break
+      messages.push(step.message)
+    }
+    return messages
+  }
+
+  /** Parse and consume the next complete message, or report that more bytes are needed. */
+  private next(): { ready: false } | { ready: true; message: unknown } {
+    const separator = this.buffer.indexOf(HEADER_SEPARATOR)
+    if (separator < 0) {
+      if (this.buffer.length > MAX_HEADER_BYTES) {
+        throw new Error(`LSP header exceeded ${MAX_HEADER_BYTES} bytes without a terminator`)
+      }
+      return { ready: false }
+    }
+    if (separator > MAX_HEADER_BYTES) {
+      throw new Error(`LSP header exceeded ${MAX_HEADER_BYTES} bytes`)
+    }
+    const headerText = this.buffer.toString('ascii', 0, separator)
+    const contentLength = parseContentLength(headerText)
+    if (contentLength > this.maxMessageBytes) {
+      throw new Error(`LSP message length ${contentLength} exceeds the ${this.maxMessageBytes}-byte limit`)
+    }
+    const bodyStart = separator + HEADER_SEPARATOR.length
+    const bodyEnd = bodyStart + contentLength
+    if (this.buffer.length < bodyEnd) return { ready: false }
+    const body = this.buffer.toString('utf8', bodyStart, bodyEnd)
+    this.buffer = this.buffer.subarray(bodyEnd)
+    try {
+      return { ready: true, message: JSON.parse(body) }
+    } catch (error) {
+      /* v8 ignore next -- JSON.parse throws a SyntaxError (an Error); the String() fallback is defensive. */
+      throw new Error(`LSP message body was not valid JSON: ${error instanceof Error ? error.message : String(error)}`)
+    }
+  }
+}
+
+/** Read the `Content-Length` header value (case-insensitive), rejecting a missing or non-numeric one. */
+function parseContentLength(headerText: string): number {
+  for (const line of headerText.split('\r\n')) {
+    const colon = line.indexOf(':')
+    if (colon < 0) continue
+    if (line.slice(0, colon).trim().toLowerCase() !== 'content-length') continue
+    const value = Number(line.slice(colon + 1).trim())
+    if (!Number.isInteger(value) || value < 0) {
+      throw new Error(`invalid Content-Length header: ${JSON.stringify(line)}`)
+    }
+    return value
+  }
+  throw new Error(`LSP header block missing Content-Length: ${JSON.stringify(headerText)}`)
+}

packages/lsp/lsp-local/src/host.ts

@@ -0,0 +1,154 @@
+/**
+ * Host-filesystem source access for the local provider, using Node APIs directly in the
+ * subprocess's namespace (never `ctx.fs`): only the LSP result is model-visible, so a query does not
+ * satisfy read-before-write policy and emits no `fs/observed`. Canonicalization derives target
+ * identity from `realpath`, so symlink aliases share a workspace; a source is rejected before server
+ * startup when it is missing, non-regular, non-UTF-8, oversized, or canonically outside the
+ * workspace. External result locations are allowed, but an external path can never become a query
+ * source.
+ * @module @deepseek-ai/dsh-lsp-local/host
+ */
+
+import { constants } from 'node:fs'
+import { open, realpath, stat } from 'node:fs/promises'
+import type { FileHandle } from 'node:fs/promises'
+import { isAbsolute, resolve as resolvePath, sep } from 'node:path'
+import { throwIfAborted } from './abort.ts'
+
+/** A validated source: its canonical absolute path and current UTF-8 text. */
+export interface HostSource {
+  /** The canonical (realpath-resolved) absolute path, inside the canonical workspace. */
+  readonly canonicalPath: string
+  /** The file's current text, read as UTF-8. */
+  readonly text: string
+}
+
+/**
+ * Canonicalize a workspace root: it must exist and be a directory. The returned realpath supplies
+ * process cwd, `rootUri`, the sole `workspaceFolders` entry, and pool identity, so symlinked roots
+ * collapse to one instance.
+ * @param workspaceRoot - the caller's workspace root (absolute).
+ * @param signal - optional cancellation observed around each filesystem operation.
+ * @returns the canonical directory path.
+ * @throws Error when the path is missing or not a directory.
+ */
+export async function canonicalizeWorkspace(workspaceRoot: string, signal?: AbortSignal): Promise<string> {
+  throwIfAborted(signal)
+  let canonical: string
+  try {
+    canonical = await realpath(workspaceRoot)
+  } catch (error) {
+    throw new Error(`workspace root "${workspaceRoot}" cannot be resolved: ${messageOf(error)}`)
+  }
+  throwIfAborted(signal)
+  const info = await stat(canonical)
+  throwIfAborted(signal)
+  if (!info.isDirectory()) {
+    throw new Error(`workspace root "${workspaceRoot}" is not a directory`)
+  }
+  return canonical
+}
+
+/**
+ * Resolve, canonicalize, validate, and read a query source in one pass. A relative `filePath`
+ * resolves against `canonicalWorkspace`; an absolute one is taken directly. The canonical target
+ * must be a regular UTF-8 file no larger than `maxDocumentBytes`, and must lie inside the canonical
+ * workspace.
+ * @param filePath - the model-supplied source path (relative or absolute).
+ * @param canonicalWorkspace - the already-canonicalized workspace root.
+ * @param maxDocumentBytes - the largest source this host will open.
+ * @param signal - optional cancellation observed throughout resolution, validation, and reading.
+ * @returns the canonical path and current UTF-8 text.
+ * @throws Error when the source is missing, non-regular, oversized, non-UTF-8, or out of workspace.
+ */
+export async function readHostSource(
+  filePath: string,
+  canonicalWorkspace: string,
+  maxDocumentBytes: number,
+  signal?: AbortSignal,
+): Promise<HostSource> {
+  throwIfAborted(signal)
+  const requested = isAbsolute(filePath) ? filePath : resolvePath(canonicalWorkspace, filePath)
+  let canonicalPath: string
+  try {
+    canonicalPath = await realpath(requested)
+  } catch (error) {
+    throw new Error(`source "${filePath}" cannot be resolved: ${messageOf(error)}`)
+  }
+  throwIfAborted(signal)
+  if (!isInside(canonicalWorkspace, canonicalPath)) {
+    throw new Error(`source "${filePath}" resolves outside the workspace`)
+  }
+  // Open ONE handle after containment, then stat and read through it: a concurrent replace between
+  // realpath and read cannot swap the target, so the regular-file and size checks bind the bytes we
+  // actually read (no path-based TOCTOU). O_NOFOLLOW rejects the final component being swapped for a
+  // symlink between realpath and open (which would otherwise escape the workspace).
+  // O_NONBLOCK prevents a FIFO with no writer from hanging before fstat can reject it as nonregular.
+  const handle = await open(canonicalPath, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
+  try {
+    throwIfAborted(signal)
+    const info = await handle.stat()
+    throwIfAborted(signal)
+    if (!info.isFile()) {
+      throw new Error(`source "${filePath}" is not a regular file`)
+    }
+    if (info.size > maxDocumentBytes) {
+      throw new Error(`source "${filePath}" is ${info.size} bytes, over the ${maxDocumentBytes}-byte limit`)
+    }
+    // Bound the read to the cap even if the file grew after stat: read one extra byte and reject on
+    // overflow, so a concurrent grow cannot defeat the memory bound.
+    const buffer = await readCapped(handle, maxDocumentBytes, filePath, signal)
+    const text = decodeUtf8Strict(buffer, filePath)
+    throwIfAborted(signal)
+    return { canonicalPath, text }
+  } finally {
+    await handle.close()
+  }
+}
+
+/** Read at most `maxBytes` from the handle, rejecting when the source overflows the cap. */
+async function readCapped(
+  handle: FileHandle,
+  maxBytes: number,
+  filePath: string,
+  signal?: AbortSignal,
+): Promise<Buffer> {
+  const limit = maxBytes + 1
+  const chunk = Buffer.allocUnsafe(limit)
+  let total = 0
+  for (;;) {
+    throwIfAborted(signal)
+    const { bytesRead } = await handle.read(chunk, total, limit - total, total)
+    throwIfAborted(signal)
+    if (bytesRead === 0) break
+    total += bytesRead
+    /* v8 ignore next 3 -- overflow requires the file to grow past the cap between stat and read (a concurrent mutation); defensive. */
+    if (total > maxBytes) {
+      throw new Error(`source "${filePath}" grew past the ${maxBytes}-byte limit while reading`)
+    }
+  }
+  return chunk.subarray(0, total)
+}
+
+/** Whether `child` is the workspace itself or a descendant of it (both already canonical). */
+function isInside(workspace: string, child: string): boolean {
+  if (child === workspace) return true
+  /* v8 ignore next -- a canonical non-root workspace never ends with a separator; the guard covers the filesystem root. */
+  const base = workspace.endsWith(sep) ? workspace : workspace + sep
+  return child.startsWith(base)
+}
+
+/** Decode strictly as UTF-8: a fatal decoder rejects only malformed bytes, keeping a legitimate U+FFFD. */
+function decodeUtf8Strict(buffer: Buffer, filePath: string): string {
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(buffer)
+  } catch {
+    throw new Error(`source "${filePath}" is not valid UTF-8 text`)
+  }
+}
+
+/** Extract a message from an unknown thrown value without leaking `any`. */
+function messageOf(error: unknown): string {
+  /* v8 ignore next -- Node fs rejections are always Error instances; the String() fallback is defensive. */
+  return error instanceof Error ? error.message : String(error)
+}

packages/lsp/lsp-local/src/index.ts

@@ -0,0 +1,336 @@
+/**
+ * Generic stdio language-server backend for `ctx.lsp`. One plugin instance configures a named table
+ * of server commands and registers one isolated provider for each entry. Every provider lazily
+ * single-flights one server process per canonical workspace realpath, serves transient-open queries
+ * through it, and evicts a crashed process so a later query can replace it. Providers read sources
+ * through Node APIs in the host namespace (not `ctx.fs`) and trust their configured servers — no
+ * sandbox confinement.
+ *
+ * Namespace plugin (named exports, no default export). Lifecycle is effect-scoped: disposal
+ * unregisters from `ctx.lsp` and tears down every live server.
+ * @module @deepseek-ai/dsh-lsp-local
+ */
+
+import { accessSync, constants, statSync } from 'node:fs'
+import { delimiter, isAbsolute, join } from 'node:path'
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import { LspError, LspProviderId } from '@deepseek-ai/dsh-lsp'
+import type {
+  LspProvider,
+  LspProviderQuery,
+  LspQueryResult,
+} from '@deepseek-ai/dsh-lsp'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
+import { abortable, abortError } from './abort.ts'
+import { canonicalizeWorkspace, readHostSource } from './host.ts'
+import { LspInstance } from './instance.ts'
+import type { InstanceSpec } from './instance.ts'
+
+export { canonicalizeWorkspace, readHostSource } from './host.ts'
+export { encodeMessage, MessageDecoder } from './framing.ts'
+export {
+  negotiatePositionEncoding,
+  normalizeHover,
+  normalizeLocations,
+  requestMethod,
+  supportsOperation,
+  supportsTransientOpen,
+} from './translate.ts'
+export { LspInstance } from './instance.ts'
+export { LspConnection } from './connection.ts'
+
+/** Cordis plugin name for loader diagnostics. */
+export const name = 'lsp-local'
+
+/** Services required by this plugin. */
+export const inject = ['lsp']
+
+/** Credential-shaped ambient env vars are NOT forwarded to the child by default. */
+const SENSITIVE_ENV_PATTERN = /KEY|SECRET|TOKEN/i
+
+const DEFAULT_MAX_MESSAGE_BYTES = 16_000_000
+const DEFAULT_MAX_STDERR_BYTES = 1_000_000
+const DEFAULT_MAX_DOCUMENT_BYTES = 4_000_000
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 5_000
+const DEFAULT_KILL_GRACE_MS = 2_000
+
+/** One configured local language server and its host bounds. */
+export interface LspLocalServerConfig {
+  /** Executable to spawn (absolute, or resolved on PATH at load). */
+  command: string
+  /** Lowercase leading-dot extension → LSP language id (e.g. `{ '.ts': 'typescript' }`). */
+  extensionToLanguage: Record<string, string>
+  /** Arguments passed to the executable (no shell). Default `[]`. */
+  args?: string[]
+  /** Extra env vars merged on top of the scrubbed ambient env. Default `{}`. */
+  env?: Record<string, string>
+  /** Static `initialize` options forwarded to the server. Default `null`. */
+  initializationOptions?: unknown
+  /** Static answer to every `workspace/configuration` item. Default `null`. */
+  configuration?: unknown
+  /** Largest single framed message accepted from the server (bytes). Default 16000000. */
+  maxMessageBytes?: number
+  /** Largest stderr tail retained for diagnostics (bytes). Default 1000000. */
+  maxStderrBytes?: number
+  /** Largest source file this host will open (bytes). Default 4000000. */
+  maxDocumentBytes?: number
+  /** Graceful `shutdown`/`exit` budget before escalation (ms). Default 5000. */
+  shutdownTimeoutMs?: number
+  /** Request-cancel and SIGTERM→SIGKILL grace (ms). Default 2000. */
+  killGraceMs?: number
+}
+
+/** Plugin configuration: provider id → local language-server configuration. */
+export interface Config {
+  /** Non-empty table of stable provider ids to independent local server configurations. */
+  servers: Record<string, LspLocalServerConfig>
+}
+
+/** One server config after schemastery fills every default. */
+type ResolvedServerConfig = Required<LspLocalServerConfig>
+
+const LspLocalServerConfig: z<LspLocalServerConfig> = z.object({
+  command: z.string().required(),
+  args: z.array(String).default([]),
+  env: z.dict(String).default({}),
+  extensionToLanguage: z.dict(String).required(),
+  initializationOptions: z.any().default(null),
+  configuration: z.any().default(null),
+  maxMessageBytes: z.number().default(DEFAULT_MAX_MESSAGE_BYTES),
+  maxStderrBytes: z.number().default(DEFAULT_MAX_STDERR_BYTES),
+  maxDocumentBytes: z.number().default(DEFAULT_MAX_DOCUMENT_BYTES),
+  shutdownTimeoutMs: z.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_SHUTDOWN_TIMEOUT_MS),
+  killGraceMs: z.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_KILL_GRACE_MS),
+})
+
+export const Config: z<Config> = z.object({
+  servers: z.dict(LspLocalServerConfig).required(),
+})
+
+/**
+ * Register the configured stdio LSP providers. Resolves every executable at load (after credential
+ * scrubbing) before publishing any provider; each process launches lazily on its first matching
+ * query.
+ * @param ctx - the plugin context (must inject `lsp`).
+ * @param config - the resolved plugin configuration (schemastery has filled every default).
+ */
+export function apply(ctx: Context, config: Config): void {
+  const entries = Object.entries(config.servers)
+  if (entries.length === 0) throw new Error('lsp-local: servers must contain at least one server')
+
+  // Resolve every server-local setting before registration so a bad later command or bound cannot
+  // publish an earlier provider. Registry-level mapping conflicts are rolled back below.
+  const providers = entries.map(([providerId, rawConfig]) => {
+    if (providerId.trim() === '') throw new Error('lsp-local: server ids must be non-empty strings')
+    const resolved = rawConfig as ResolvedServerConfig
+    validateServerConfig(providerId, resolved)
+    const childEnv = buildChildEnv(resolved.env)
+    const executable = resolveExecutable(resolved.command, childEnv)
+    return new LocalLspProvider(providerId, resolved, childEnv, executable)
+  })
+
+  ctx.effect(() => {
+    const disposers: Array<() => void> = []
+    try {
+      for (const provider of providers) disposers.push(ctx.lsp.registerProvider(provider))
+    } catch (error) {
+      for (const dispose of disposers.reverse()) dispose()
+      throw error
+    }
+    return async () => {
+      // Remove every route before process teardown so no new query can enter a draining provider.
+      for (const dispose of disposers.reverse()) dispose()
+      await Promise.all(providers.map(provider => provider.disposeAll()))
+    }
+  }, 'lsp-local.registerProviders')
+}
+
+/** Validate one resolved server entry before any provider in the table is registered. */
+function validateServerConfig(providerId: string, resolved: ResolvedServerConfig): void {
+  // Teardown budgets feed `deadline()`, whose `<= 0` is the internal no-timeout sentinel; a
+  // nonpositive value would let a server that ignores shutdown hang disposal forever. Fail at load.
+  assertTimer(providerId, 'shutdownTimeoutMs', resolved.shutdownTimeoutMs)
+  assertTimer(providerId, 'killGraceMs', resolved.killGraceMs)
+  // Byte caps must be positive: a nonpositive stderr cap defeats the retained-tail bound
+  // (`slice(-0)` keeps everything), `maxMessageBytes: 0` makes every response fatal, and a bad
+  // document cap fails later in the read path instead of at load.
+  assertPositiveInteger(providerId, 'maxStderrBytes', resolved.maxStderrBytes)
+  assertPositiveInteger(providerId, 'maxMessageBytes', resolved.maxMessageBytes)
+  assertPositiveInteger(providerId, 'maxDocumentBytes', resolved.maxDocumentBytes)
+}
+
+/** Reject a timer value Node would clamp instead of scheduling as configured. */
+function assertTimer(providerId: string, name: string, value: number): void {
+  if (!Number.isInteger(value) || value < 1 || value > MAX_TIMER_DELAY_MS) {
+    throw new Error(`lsp-local: servers.${providerId}.${name} must be a positive integer no greater than ${MAX_TIMER_DELAY_MS}`)
+  }
+}
+
+/** Reject a nonpositive or non-integer config value at load, so misconfiguration fails loud. */
+function assertPositiveInteger(providerId: string, name: string, value: number): void {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error(`lsp-local: servers.${providerId}.${name} must be a positive integer`)
+  }
+}
+
+/** A pooled generic provider: one server process per canonical workspace, created on demand. */
+class LocalLspProvider implements LspProvider {
+  readonly id: LspProviderId
+  readonly extensionToLanguage: Readonly<Record<string, string>>
+  /** One live instance per canonical workspace realpath. */
+  private readonly instances = new Map<string, LspInstance>()
+  /** One complete source-read→open→query→close serialization tail per canonical workspace. */
+  private readonly queues = new Map<string, Promise<void>>()
+  private disposed = false
+
+  constructor(
+    providerId: string,
+    private readonly config: ResolvedServerConfig,
+    private readonly childEnv: Record<string, string>,
+    private readonly executable: string,
+  ) {
+    this.id = LspProviderId(providerId)
+    this.extensionToLanguage = config.extensionToLanguage
+  }
+
+  /** Read the disposed flag through a method so a `query()` await cannot narrow it to a literal. */
+  private isDisposed(): boolean {
+    return this.disposed
+  }
+
+  /** Reject work that cannot publish or use a provider-owned instance. */
+  private assertActive(signal?: AbortSignal): void {
+    /* v8 ignore next -- the seam unregisters this provider before disposal; direct in-flight calls
+       exercise the post-await check instead. */
+    if (this.isDisposed()) throw new LspError('lsp-local provider is disposed', 'LSP_DISPOSED')
+    if (signal?.aborted) throw abortError(signal)
+  }
+
+  async query(request: LspProviderQuery, signal?: AbortSignal): Promise<LspQueryResult> {
+    // Honor an already-aborted signal before host I/O so a canceled request never starts a server.
+    this.assertActive(signal)
+    const workspace = await canonicalizeWorkspace(request.workspaceRoot, signal)
+    this.assertActive(signal)
+    return this.enqueue(workspace, signal, async () => {
+      this.assertActive(signal)
+      // Read inside the workspace queue but before spawning: a queued query sees current bytes when
+      // its turn starts, while an invalid source still cannot leave an idle process pooled.
+      const source = await readHostSource(request.filePath, workspace, this.config.maxDocumentBytes, signal)
+      // Disposal may have snapshotted the instance map while host I/O was pending. Re-check before a
+      // synchronous get-or-create so every spawned process remains owned by teardown.
+      this.assertActive(signal)
+      let instance = this.instanceFor(workspace)
+      if (instance.dead) {
+        this.evictIfCurrent(workspace, instance)
+        instance = this.instanceFor(workspace)
+      }
+      try {
+        return await instance.query(request, source, signal)
+      } finally {
+        // Drop a crashed slot only when it still owns this instance; a replacement must survive.
+        if (instance.dead) this.evictIfCurrent(workspace, instance)
+      }
+    })
+  }
+
+  /** Serialize one complete query lifecycle for a canonical workspace. */
+  private enqueue<T>(workspace: string, signal: AbortSignal | undefined, run: () => Promise<T>): Promise<T> {
+    const previous = this.queues.get(workspace) ?? Promise.resolve()
+    const result = abortable(previous, signal).then(run)
+    // The tail follows the actual prior work even when this caller aborts its wait. It never rejects,
+    // so later callers serialize without inheriting an earlier query's outcome.
+    const tail = previous.then(() => result).then(() => undefined, () => undefined)
+    this.queues.set(workspace, tail)
+    void tail.then(() => {
+      if (this.queues.get(workspace) === tail) this.queues.delete(workspace)
+    })
+    return result
+  }
+
+  /** Return or synchronously publish the one instance for a canonical workspace. */
+  private instanceFor(workspace: string): LspInstance {
+    this.assertActive()
+    const existing = this.instances.get(workspace)
+    if (existing !== undefined) return existing
+    const created = this.createInstance(workspace)
+    this.instances.set(workspace, created)
+    return created
+  }
+
+  /** Drop the slot iff it still contains this instance. */
+  private evictIfCurrent(workspace: string, instance: LspInstance): void {
+    /* v8 ignore next -- mismatch requires another query to replace the slot before this finally runs. */
+    if (this.instances.get(workspace) === instance) this.instances.delete(workspace)
+  }
+
+  private createInstance(workspace: string): LspInstance {
+    const spec: InstanceSpec = {
+      command: this.executable,
+      args: this.config.args,
+      cwd: workspace,
+      env: this.childEnv,
+      configuration: this.config.configuration,
+      initializationOptions: this.config.initializationOptions,
+      maxMessageBytes: this.config.maxMessageBytes,
+      maxStderrBytes: this.config.maxStderrBytes,
+      shutdownTimeoutMs: this.config.shutdownTimeoutMs,
+      killGraceMs: this.config.killGraceMs,
+    }
+    return new LspInstance(spec)
+  }
+
+  /** Dispose every live instance and block further queries. */
+  async disposeAll(): Promise<void> {
+    this.disposed = true
+    const live = [...this.instances.values()]
+    const draining = [...this.queues.values()]
+    this.instances.clear()
+    await Promise.all([
+      ...live.map(instance => instance.dispose()),
+      ...draining,
+    ])
+    this.queues.clear()
+  }
+}
+
+/** The ambient env minus credential-shaped vars, plus the config's explicit env. */
+function buildChildEnv(extra: Record<string, string>): Record<string, string> {
+  const scrubbed = Object.entries(process.env).filter(
+    ([key, value]) => value !== undefined && !SENSITIVE_ENV_PATTERN.test(key),
+  ) as [string, string][]
+  return { ...Object.fromEntries(scrubbed), ...extra }
+}
+
+/**
+ * Resolve the server executable to an absolute path: an absolute command is verified directly; a
+ * bare command is looked up on the child's PATH. Fails loudly when nothing is executable.
+ */
+function resolveExecutable(command: string, childEnv: Record<string, string>): string {
+  if (isAbsolute(command)) {
+    // Verify an absolute command too, so an unavailable one fails at load, not on the first query.
+    if (!isExecutableFileSync(command)) {
+      throw new Error(`lsp-local: command "${command}" is not an executable file`)
+    }
+    return command
+  }
+  /* v8 ignore next -- buildChildEnv always sets PATH from the ambient env; the further fallbacks are defensive. */
+  const pathValue = childEnv.PATH ?? process.env.PATH ?? ''
+  for (const dir of pathValue.split(delimiter)) {
+    if (dir === '') continue
+    const candidate = join(dir, command)
+    if (isExecutableFileSync(candidate)) return candidate
+  }
+  throw new Error(`lsp-local: command "${command}" was not found on PATH`)
+}
+
+/** Synchronous regular-file and executable check used only at load-time resolution. */
+function isExecutableFileSync(path: string): boolean {
+  try {
+    if (!statSync(path).isFile()) return false
+    accessSync(path, constants.X_OK)
+    return true
+  } catch {
+    return false
+  }
+}

packages/lsp/lsp-local/src/instance.ts

@@ -0,0 +1,334 @@
+/**
+ * One language-server instance: a connection plus the initialize handshake, the serialized abortable
+ * query queue, the transient `didOpen`→request→`didClose` lifecycle, and bounded teardown. One
+ * instance owns one `(provider id, canonical workspace)` process. Queries serialize through a single
+ * queue so a cancellation that fails to stop the server can terminate it without killing unrelated
+ * work; distinct instances run in parallel.
+ * @module @deepseek-ai/dsh-lsp-local/instance
+ */
+
+import { pathToFileURL } from 'node:url'
+import { LspError } from '@deepseek-ai/dsh-lsp'
+import type {
+  LspOperation,
+  LspProviderQuery,
+  LspQueryResult,
+} from '@deepseek-ai/dsh-lsp'
+import { deadline } from '@deepseek-ai/dsh-timeout'
+import { abortable, abortError } from './abort.ts'
+import { LspConnection } from './connection.ts'
+import type { ConnectionSpec } from './connection.ts'
+import type { HostSource } from './host.ts'
+import type { WireInitializeResult, WireServerCapabilities } from './protocol.ts'
+import {
+  negotiatePositionEncoding,
+  normalizeHover,
+  normalizeLocations,
+  requestMethod,
+  supportsOperation,
+  supportsTransientOpen,
+} from './translate.ts'
+
+/** Everything an instance needs beyond the connection spec. */
+export interface InstanceSpec extends ConnectionSpec {
+  /** Static `initialize` options forwarded to the server. */
+  readonly initializationOptions: unknown
+  /** Graceful `shutdown`/`exit` budget before escalation (ms). */
+  readonly shutdownTimeoutMs: number
+  /** SIGTERM→SIGKILL grace after graceful shutdown fails (ms). */
+  readonly killGraceMs: number
+}
+
+/**
+ * A single initialized server process. Not exported as a provider — the provider single-flights and
+ * pools these. `query()` serializes; `dispose()` rejects queued work and tears the process down.
+ */
+export class LspInstance {
+  private readonly connection: LspConnection
+  private capabilities: WireServerCapabilities | undefined
+  /** The serialization tail: each query awaits the prior one, so lifecycles never interleave. */
+  private queue: Promise<unknown> = Promise.resolve()
+  private disposed = false
+  /** The one teardown transaction shared by abort, failure, and explicit disposal. */
+  private teardownPromise: Promise<void> | undefined
+  /** Set once the process closes, so the pool can synchronously skip a dead instance. */
+  private processClosed = false
+  /** Populated once `initialize` succeeds; a failed handshake rejects every query. */
+  private readonly ready: Promise<void>
+
+  /**
+   * @param spec - the launch, initialize, and teardown parameters.
+   */
+  constructor(private readonly spec: InstanceSpec) {
+    this.connection = new LspConnection(spec, (method, params) => this.answerServerRequest(method, params))
+    this.ready = this.initialize()
+    // A handshake rejection must not surface as an unhandled rejection before the first query awaits
+    // it; queries attach the real handler.
+    this.ready.catch(() => {})
+    void this.connection.closed.then(() => { this.processClosed = true })
+  }
+
+  /** Synchronous liveness check: true once the process has closed or the instance was disposed. */
+  get dead(): boolean {
+    return this.processClosed || this.disposed
+  }
+
+  /**
+   * Run one query through the serialized queue.
+   * @param request - the resolved provider query.
+   * @param source - the pre-validated, already-read host source (the provider reads before spawning).
+   * @param signal - optional cancellation for this query's full lifecycle.
+   * @returns the normalized result.
+   */
+  query(request: LspProviderQuery, source: HostSource, signal?: AbortSignal): Promise<LspQueryResult> {
+    // Serialize behind prior work, but observe abort DURING the queue wait too: if an earlier query
+    // hangs (e.g. a signal-less seam caller), a later tool's timeout must still be able to give up
+    // rather than block on the shared tail forever.
+    const run = abortable(this.queue, signal).then(() => this.runQuery(request, source, signal))
+    // Keep the tail alive regardless of this query's outcome so the next caller still serializes. The
+    // tail follows the ACTUAL prior work (this.queue), not the abortable view, so a caller giving up
+    // on the wait does not deserialize the queue.
+    this.queue = this.queue.then(() => run).then(() => undefined, () => undefined)
+    return run
+  }
+
+  private async initialize(): Promise<void> {
+    const initializeResult = await this.connection.request('initialize', {
+      processId: process.pid,
+      rootUri: pathToFileURL(this.spec.cwd).href,
+      workspaceFolders: [{ uri: pathToFileURL(this.spec.cwd).href, name: 'workspace' }],
+      capabilities: CLIENT_CAPABILITIES,
+      initializationOptions: this.spec.initializationOptions,
+    }) as WireInitializeResult
+    const capabilities = initializeResult.capabilities
+    // An omitted encoding defaults to utf-16; any other value is a protocol error we reject here.
+    negotiatePositionEncoding(capabilities.positionEncoding)
+    this.capabilities = capabilities
+    await this.connection.notify('initialized', {})
+  }
+
+  private async runQuery(request: LspProviderQuery, source: HostSource, signal?: AbortSignal): Promise<LspQueryResult> {
+    if (this.disposed) throw new LspError('LSP instance was disposed', 'LSP_DISPOSED')
+    /* v8 ignore next -- the abortable queue wait rejects a pre-aborted signal before runQuery; this is a belt-and-suspenders guard. */
+    if (signal?.aborted) throw abortError(signal)
+    // Observe abort during the handshake wait, and never pool a poisoned instance: if the wait ends
+    // in failure — an abort on a still-pending handshake, OR `initialize` rejecting (utf-8
+    // negotiation, malformed result) without the process exiting — tear the instance down so a
+    // permanently-rejecting/pending `ready` can't make every later query for this workspace fail.
+    try {
+      await abortable(this.ready, signal)
+    } catch (error) {
+      if (!this.dead) {
+        await this.startTeardown()
+      }
+      throw error
+    }
+    const capabilities = this.capabilities
+    /* v8 ignore next -- `ready` resolves only after capabilities are set, else it rejects above; defensive. */
+    if (capabilities === undefined) throw new Error('LSP instance is not initialized')
+    if (!supportsOperation(capabilities, request.operation)) {
+      throw new LspError(`server does not support ${request.operation}`, 'LSP_UNSUPPORTED_OPERATION')
+    }
+    if (!supportsTransientOpen(capabilities.textDocumentSync)) {
+      throw new LspError('server does not support the transient textDocument/didOpen this host requires', 'LSP_UNSUPPORTED_OPERATION')
+    }
+
+    const uri = pathToFileURL(source.canonicalPath).href
+    let opened = false
+    try {
+      /* v8 ignore next -- guards an abort landing between the ready wait and didOpen; not deterministically reproducible. */
+      if (signal?.aborted) throw abortError(signal)
+      try {
+        await abortable(this.connection.notify('textDocument/didOpen', {
+          textDocument: { uri, languageId: request.languageId, version: 1, text: source.text },
+        }), signal)
+      } catch (error) {
+        // A canceled backpressured write or failed stdin leaves the protocol stream unusable before
+        // `opened` can arm the didClose cleanup. Teardown here makes the pool evict the instance.
+        await this.startTeardown()
+        throw error
+      }
+      opened = true
+      const payload = await this.sendRequest(request.operation, uri, request.position, signal)
+      return this.normalize(request.operation, payload)
+    } finally {
+      // A disposed or closed instance (e.g. an aborted request whose server ignored
+      // `$/cancelRequest`) is already tearing down; sending didClose would race that teardown and let
+      // the next queued query's document lifecycle overlap the still-active request.
+      if (opened && !this.dead) {
+        try {
+          await this.connection.notify('textDocument/didClose', { textDocument: { uri } })
+        } catch {
+          // A close-write failure does not replace the settled result/error, but the instance can no
+          // longer be trusted: invalidate it and await bounded process termination.
+          try {
+            await this.startTeardown()
+          } catch {
+            /* v8 ignore next -- teardown owns all expected process races; this only preserves the
+               already-settled query outcome if an unexpected cleanup primitive itself rejects. */
+          }
+        }
+      }
+    }
+  }
+
+  private async sendRequest(
+    operation: LspOperation,
+    uri: string,
+    position: LspProviderQuery['position'],
+    signal?: AbortSignal,
+  ): Promise<unknown> {
+    const params = {
+      textDocument: { uri },
+      position: { line: position.line, character: position.character },
+      // findReferences always includes declarations: the caller gets no flag and impact analysis
+      // never omits the defining site.
+      ...(operation === 'findReferences' ? { context: { includeDeclaration: true } } : {}),
+    }
+    const requestId = this.connection.peekNextId()
+    const send = this.connection.request(requestMethod(operation), params)
+    if (signal === undefined) return send
+    return this.raceAbort(send, requestId, signal)
+  }
+
+  /**
+   * Race a pending request against abort. On abort, send `$/cancelRequest` and give the server a
+   * bounded grace to acknowledge; if it does not settle in time, invalidate and tear down the
+   * instance so the still-active request cannot overlap the next queued query's document lifecycle.
+   */
+  private async raceAbort(send: Promise<unknown>, requestId: number, signal: AbortSignal): Promise<unknown> {
+    try {
+      return await abortable(send, signal)
+    } catch (error) {
+      if (!signal.aborted) throw error
+      this.connection.cancel(requestId)
+      // Wait, bounded, for the server to honor the cancellation. If it does not, the request is still
+      // running: terminate the instance (disposal awaits process close) so nothing outlives the query.
+      const grace = deadline(undefined, this.spec.killGraceMs, 'LSP_CANCEL_GRACE')
+      try {
+        // `settled` is true if the request finished (either outcome) before the grace elapsed.
+        const settled = await Promise.race([
+          send.then(markSettled, markSettled),
+          new Promise<boolean>((resolve) => {
+            /* v8 ignore next -- the cancel-grace deadline signal is freshly armed and not yet aborted here; defensive. */
+            if (grace.signal.aborted) { resolve(false); return }
+            grace.signal.addEventListener('abort', () => { resolve(false) }, { once: true })
+          }),
+        ])
+        if (!settled) await this.startTeardown()
+      } finally {
+        grace[Symbol.dispose]()
+      }
+      throw error
+    }
+  }
+
+  private normalize(operation: LspOperation, payload: unknown): LspQueryResult {
+    if (operation === 'hover') {
+      return { kind: 'hover', hover: normalizeHover(payload) }
+    }
+    // `spec.cwd` is the canonical workspace realpath (the provider canonicalizes before spawning),
+    // and every `file:` location URI is relative to it — so it is the root a caller must relativize
+    // display paths against, not the request's possibly-symlinked workspaceRoot.
+    return { kind: 'locations', locations: normalizeLocations(payload), resolvedWorkspaceRoot: this.spec.cwd }
+  }
+
+  private answerServerRequest(method: string, params: unknown): Promise<unknown> {
+    if (method === 'workspace/configuration') {
+      // Answer every requested item with the one static configuration value.
+      const record = params as { items?: unknown[] } | null
+      /* v8 ignore next -- a configuration request always carries an items array; the empty fallback is defensive. */
+      const items = Array.isArray(record?.items) ? record.items : []
+      return Promise.resolve(items.map(() => this.spec.configuration))
+    }
+    if (LIFECYCLE_NOOP_METHODS.has(method)) {
+      // Accept lifecycle bookkeeping requests with an empty result; we register nothing dynamic.
+      return Promise.resolve(null)
+    }
+    if (method === 'workspace/applyEdit') {
+      // This host never applies edits or runs commands.
+      return Promise.reject(new Error('workspace/applyEdit is not permitted by this host'))
+    }
+    return Promise.reject(new Error(`unsupported server request: ${method}`))
+  }
+
+  /**
+   * Reject queued work, attempt graceful `shutdown`/`exit`, then escalate SIGTERM→SIGKILL, awaiting
+   * process close so nothing outlives disposal.
+   */
+  async dispose(): Promise<void> {
+    await this.startTeardown()
+  }
+
+  /** Publish disposal once and make every caller await the same quiescence boundary. */
+  private startTeardown(): Promise<void> {
+    this.disposed = true
+    this.teardownPromise ??= this.tearDown()
+    return this.teardownPromise
+  }
+
+  private async tearDown(): Promise<void> {
+    const shutdownDeadline = deadline(undefined, this.spec.shutdownTimeoutMs, 'LSP_SHUTDOWN')
+    try {
+      await this.gracefulShutdown(shutdownDeadline.signal)
+    } catch {
+      // Graceful shutdown failed or timed out; process-group cleanup below remains authoritative.
+    } finally {
+      shutdownDeadline[Symbol.dispose]()
+    }
+    await this.forceTerminate()
+  }
+
+  /** Best-effort LSP `shutdown`/`exit`, including process close, bounded by `signal`. */
+  private async gracefulShutdown(signal: AbortSignal): Promise<void> {
+    await abortable(this.connection.request('shutdown', null), signal)
+    await this.connection.notify('exit', null)
+    await abortable(this.connection.closed, signal)
+  }
+
+  /** SIGTERM the group, escalate after `killGraceMs`, then await leader and helper exit. */
+  private async forceTerminate(): Promise<void> {
+    this.connection.terminate()
+    const graceDeadline = deadline(undefined, this.spec.killGraceMs, 'LSP_KILL_GRACE')
+    let groupExited: boolean
+    try {
+      groupExited = await this.connection.waitForProcessGroupExit(graceDeadline.signal)
+    } finally {
+      graceDeadline[Symbol.dispose]()
+    }
+    if (!groupExited) this.connection.kill()
+    await Promise.all([
+      this.connection.closed,
+      this.connection.waitForProcessGroupExit(),
+    ])
+  }
+}
+
+/** Server→client request methods this host acknowledges with an empty result (no dynamic registration). */
+const LIFECYCLE_NOOP_METHODS = new Set([
+  'window/workDoneProgress/create',
+  'client/registerCapability',
+  'client/unregisterCapability',
+])
+
+/** Mark a settled request in the cancel-grace race (either outcome means the request finished). */
+function markSettled(): boolean {
+  return true
+}
+
+/**
+ * The client capabilities advertised at `initialize`: UTF-16 positions, workspace folders and
+ * configuration, markdown/plaintext hover, and link support for definition/implementation. No
+ * dynamic registration; the server's returned capabilities are authoritative.
+ */
+const CLIENT_CAPABILITIES = {
+  general: { positionEncodings: ['utf-16'] },
+  workspace: { workspaceFolders: true, configuration: true },
+  textDocument: {
+    synchronization: { dynamicRegistration: false },
+    hover: { contentFormat: ['markdown', 'plaintext'] },
+    definition: { linkSupport: true },
+    implementation: { linkSupport: true },
+    references: {},
+  },
+} as const

packages/lsp/lsp-local/src/protocol.ts

@@ -0,0 +1,80 @@
+/**
+ * The subset of LSP wire types this generic host reads and writes: initialize capabilities, the four
+ * request results (`Location`, `LocationLink`, `Hover`), and the `textDocumentSync` shapes used to
+ * decide transient-open support. Types only. Fields absent from a real server payload stay optional;
+ * the translation layer normalizes them into the seam's closed unions.
+ * @module @deepseek-ai/dsh-lsp-local/protocol
+ */
+
+/** A zero-based UTF-16 position on the wire (the protocol's `Position`). */
+export interface WirePosition {
+  readonly line: number
+  readonly character: number
+}
+
+/** A wire range (`Range`). */
+export interface WireRange {
+  readonly start: WirePosition
+  readonly end: WirePosition
+}
+
+/** A `Location`: a document URI plus a range. */
+export interface WireLocation {
+  readonly uri: string
+  readonly range: WireRange
+}
+
+/** A `LocationLink`: the target uri plus the selection range to focus. */
+export interface WireLocationLink {
+  readonly targetUri: string
+  readonly targetSelectionRange: WireRange
+  readonly targetRange?: WireRange
+}
+
+/** A `MarkupContent` hover body (`markdown` or `plaintext`). */
+export interface WireMarkupContent {
+  readonly kind: 'markdown' | 'plaintext'
+  readonly value: string
+}
+
+/** A `MarkedString` object form (`{ language, value }`); the string form is a bare `string`. */
+export interface WireMarkedStringObject {
+  readonly language: string
+  readonly value: string
+}
+
+/** One `MarkedString`: a raw string or a language-tagged code block. */
+export type WireMarkedString = string | WireMarkedStringObject
+
+/** A `Hover`: contents in any of the protocol's three encodings, plus an optional range. */
+export interface WireHover {
+  readonly contents: WireMarkupContent | WireMarkedString | readonly WireMarkedString[]
+  readonly range?: WireRange
+}
+
+/** The legacy enum form of `textDocumentSync` (`0` None, `1` Full, `2` Incremental). */
+export type WireTextDocumentSyncKind = 0 | 1 | 2
+
+/** The options form of `textDocumentSync` (`{ openClose, change }`). */
+export interface WireTextDocumentSyncOptions {
+  readonly openClose?: boolean
+  readonly change?: WireTextDocumentSyncKind
+}
+
+/** A `ServerCapabilities.provider` slot: a boolean or an options object (both mean "supported"). */
+export type WireProviderCapability = boolean | Record<string, unknown> | undefined
+
+/** The `ServerCapabilities` fields this host inspects. */
+export interface WireServerCapabilities {
+  readonly positionEncoding?: string
+  readonly textDocumentSync?: WireTextDocumentSyncKind | WireTextDocumentSyncOptions
+  readonly definitionProvider?: WireProviderCapability
+  readonly referencesProvider?: WireProviderCapability
+  readonly implementationProvider?: WireProviderCapability
+  readonly hoverProvider?: WireProviderCapability
+}
+
+/** The `initialize` result envelope. */
+export interface WireInitializeResult {
+  readonly capabilities: WireServerCapabilities
+}

packages/lsp/lsp-local/src/translate.ts

@@ -0,0 +1,235 @@
+/**
+ * Pure protocol translation for the local host: what the server's capabilities allow, and how its
+ * `Location`/`LocationLink`/`Hover` payloads normalize into the seam's closed result unions. No I/O
+ * or process state — every function here is a pure transform, which the fake-stdio tests pin exactly.
+ * @module @deepseek-ai/dsh-lsp-local/translate
+ */
+
+import type {
+  LspHover,
+  LspLocation,
+  LspOperation,
+  LspRange,
+} from '@deepseek-ai/dsh-lsp'
+import { LspError } from '@deepseek-ai/dsh-lsp'
+import { assertNever } from '@deepseek-ai/dsh-llm'
+import type {
+  WireHover,
+  WireLocation,
+  WireLocationLink,
+  WireMarkedString,
+  WireProviderCapability,
+  WireRange,
+  WireServerCapabilities,
+  WireTextDocumentSyncKind,
+} from './protocol.ts'
+
+/**
+ * The `textDocument/*` request method for each seam operation.
+ * @param operation - the seam operation to map.
+ * @returns the LSP request method name.
+ */
+export function requestMethod(operation: LspOperation): string {
+  switch (operation) {
+    case 'goToDefinition': return 'textDocument/definition'
+    case 'findReferences': return 'textDocument/references'
+    case 'goToImplementation': return 'textDocument/implementation'
+    case 'hover': return 'textDocument/hover'
+    /* v8 ignore next -- exhaustive over the closed LspOperation union; unreachable. */
+    default: return assertNever(operation, 'requestMethod')
+  }
+}
+
+/** The `ServerCapabilities` provider field backing each operation. */
+function capabilityValue(capabilities: WireServerCapabilities, operation: LspOperation): WireProviderCapability {
+  switch (operation) {
+    case 'goToDefinition': return capabilities.definitionProvider
+    case 'findReferences': return capabilities.referencesProvider
+    case 'goToImplementation': return capabilities.implementationProvider
+    case 'hover': return capabilities.hoverProvider
+    /* v8 ignore next -- exhaustive over the closed LspOperation union; unreachable. */
+    default: return assertNever(operation, 'capabilityValue')
+  }
+}
+
+/** A provider capability is present when the server sent `true` or an options object (not `false`/absent). */
+function supportsCapability(value: WireProviderCapability): boolean {
+  if (value === undefined) return false
+  if (typeof value === 'boolean') return value
+  return true
+}
+
+/**
+ * Whether the server advertises the requested operation.
+ * @param capabilities - the server's `initialize` capabilities.
+ * @param operation - the seam operation to check.
+ * @returns true when the corresponding provider capability is present.
+ */
+export function supportsOperation(capabilities: WireServerCapabilities, operation: LspOperation): boolean {
+  return supportsCapability(capabilityValue(capabilities, operation))
+}
+
+/**
+ * Whether a `textDocumentSync` value permits the transient `didOpen`/`didClose` this host relies on.
+ * The legacy enum form implies open/close for `Full`/`Incremental`; the options form requires an
+ * explicit `openClose: true`, because the protocol defaults an omitted `openClose` to false.
+ * @param sync - the server's advertised `textDocumentSync` capability.
+ * @returns true when transient open/close is supported.
+ */
+export function supportsTransientOpen(sync: WireServerCapabilities['textDocumentSync']): boolean {
+  if (sync === undefined) return false
+  if (typeof sync === 'number') return isOpenCloseKind(sync)
+  return sync.openClose === true
+}
+
+/** Legacy enum: `Full` (1) or `Incremental` (2) imply open/close support; `None` (0) does not. */
+function isOpenCloseKind(kind: WireTextDocumentSyncKind): boolean {
+  return kind === 1 || kind === 2
+}
+
+/**
+ * Normalize the negotiated position encoding. An omitted encoding defaults to `utf-16`; any value
+ * other than `utf-16` is a protocol error this host does not support.
+ * @param encoding - the server's advertised `positionEncoding`, if any.
+ * @returns the string `'utf-16'`.
+ * @throws Error for any non-`utf-16` encoding.
+ */
+export function negotiatePositionEncoding(encoding: string | undefined): 'utf-16' {
+  if (encoding === undefined || encoding === 'utf-16') return 'utf-16'
+  throw new Error(`server negotiated unsupported position encoding "${encoding}"; this host requires utf-16`)
+}
+
+/** Convert a wire range to the seam's range (structurally identical, but re-shaped as `readonly`). */
+function toRange(range: WireRange): LspRange {
+  return {
+    start: { line: range.start.line, character: range.start.character },
+    end: { line: range.end.line, character: range.end.character },
+  }
+}
+
+/** Whether a record is a `LocationLink` (has `targetUri` + `targetSelectionRange`). */
+function isLocationLink(value: Record<string, unknown>): boolean {
+  return typeof value.targetUri === 'string' && isRange(value.targetSelectionRange)
+}
+
+/** Whether a record is a `Location` (has string `uri` + a range). */
+function isLocation(value: Record<string, unknown>): boolean {
+  return typeof value.uri === 'string' && isRange(value.range)
+}
+
+/** Structural range guard used by both location shapes. */
+function isRange(value: unknown): value is WireRange {
+  if (value === null || typeof value !== 'object') return false
+  const range = value as Record<string, unknown>
+  return isPosition(range.start) && isPosition(range.end)
+}
+
+/** Structural position guard. */
+function isPosition(value: unknown): boolean {
+  if (value === null || typeof value !== 'object') return false
+  const position = value as Record<string, unknown>
+  return isProtocolCoordinate(position.line) && isProtocolCoordinate(position.character)
+}
+
+/** Whether a wire coordinate is a valid nonnegative integer. */
+function isProtocolCoordinate(value: unknown): value is number {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0
+}
+
+/**
+ * Normalize a navigation result (`Location`, `Location[]`, `LocationLink[]`, or `null`) to the seam's
+ * locations. `Location` maps directly; `LocationLink` maps `targetUri` + `targetSelectionRange`.
+ * @param payload - the raw `textDocument/definition|references|implementation` result.
+ * @returns the normalized locations (empty for `null`/`[]`).
+ * @throws Error when an element is neither a `Location` nor a `LocationLink`.
+ */
+export function normalizeLocations(payload: unknown): LspLocation[] {
+  if (payload === null) return []
+  if (payload === undefined) throw malformedResponse('LSP navigation result was missing')
+  const elements = Array.isArray(payload) ? payload : [payload]
+  const locations: LspLocation[] = []
+  for (const element of elements) {
+    if (element === null || typeof element !== 'object') {
+      throw malformedResponse('LSP navigation result contained a non-object entry')
+    }
+    const record = element as Record<string, unknown>
+    if (isLocationLink(record)) {
+      const link = record as unknown as WireLocationLink
+      locations.push({ uri: link.targetUri, range: toRange(link.targetSelectionRange) })
+    } else if (isLocation(record)) {
+      const location = record as unknown as WireLocation
+      locations.push({ uri: location.uri, range: toRange(location.range) })
+    } else {
+      throw malformedResponse('LSP navigation result contained neither a Location nor a LocationLink')
+    }
+  }
+  return locations
+}
+
+/** Render one `MarkedString` (string form verbatim; object form as a language-tagged fenced block). */
+function renderMarkedString(value: WireMarkedString): string {
+  if (typeof value === 'string') return value
+  return `\`\`\`${value.language}\n${value.value}\n\`\`\``
+}
+
+/**
+ * Normalize a `Hover` (or `null`) to the seam's hover. `MarkupContent` uses its `value`; a string
+ * `MarkedString` is verbatim; a language-tagged `MarkedString` becomes a fenced code block; an array
+ * joins its rendered parts with one blank line. The model-facing tool owns the complete result cap.
+ * @param payload - the raw `textDocument/hover` result.
+ * @returns the normalized hover, or `null` when there is no content.
+ * @throws Error when the payload is a non-null, non-object, or structurally invalid hover.
+ */
+export function normalizeHover(payload: unknown): LspHover | null {
+  if (payload === null) return null
+  if (payload === undefined) throw malformedResponse('LSP hover result was missing')
+  if (typeof payload !== 'object') throw malformedResponse('LSP hover result was not an object')
+  const hover = payload as unknown as WireHover
+  const contents = renderHoverContents(hover.contents)
+  if (contents === '') return null
+  const range = hover.range
+  if (range === undefined) return { contents }
+  if (!isRange(range)) throw malformedResponse('LSP hover result contained a malformed range')
+  return { contents, range: toRange(range) }
+}
+
+/** Render the three `Hover.contents` encodings into one string (input is untrusted wire data). */
+function renderHoverContents(contents: unknown): string {
+  if (contents === null || contents === undefined) {
+    throw malformedResponse('LSP hover result had no contents')
+  }
+  if (typeof contents === 'string') return contents
+  if (Array.isArray(contents)) {
+    return contents.map((value) => {
+      if (isMarkedString(value)) return renderMarkedString(value)
+      throw malformedResponse('LSP hover contents contained a malformed MarkedString')
+    }).join('\n\n')
+  }
+  if (typeof contents !== 'object') {
+    throw malformedResponse('LSP hover contents were not MarkupContent, MarkedString, or an array')
+  }
+  const record = contents as Record<string, unknown>
+  if (record.kind === 'markdown' || record.kind === 'plaintext') {
+    if (typeof record.value !== 'string') {
+      throw malformedResponse('LSP hover MarkupContent value was not a string')
+    }
+    return record.value
+  }
+  if (typeof record.language === 'string' && typeof record.value === 'string') {
+    return renderMarkedString({ language: record.language, value: record.value })
+  }
+  throw malformedResponse('LSP hover contents were not MarkupContent, MarkedString, or an array')
+}
+
+/** Whether an untrusted value is either form of `MarkedString`. */
+function isMarkedString(value: unknown): value is WireMarkedString {
+  if (typeof value === 'string') return true
+  if (value === null || typeof value !== 'object') return false
+  const record = value as Record<string, unknown>
+  return typeof record.language === 'string' && typeof record.value === 'string'
+}
+
+/** Create the stable structured error used for malformed server result payloads. */
+function malformedResponse(message: string): LspError {
+  return new LspError(message, 'LSP_MALFORMED_RESPONSE')
+}

packages/lsp/lsp-local/tests/built-lib.e2e.ts

@@ -0,0 +1,73 @@
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { mkdtemp, mkdir, rm, writeFile, realpath } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+
+/**
+ * Keyless built-artifact smoke: plain Node imports `@deepseek-ai/dsh-lsp` and
+ * `@deepseek-ai/dsh-lsp-local` by name through their exports maps, spawns the fixture server, runs
+ * one query (exercising real `Content-Length` framing over `lib/index.js`), and disposes (exercising
+ * subprocess cleanup). Unit tests use `src/`; this pins the downstream `lib/` path. Skips when `lib/`
+ * is absent; CI runs it after the build.
+ */
+
+const pkgDir = fileURLToPath(new URL('..', import.meta.url))
+const seamLib = join(pkgDir, '../lsp/lib/index.js')
+const built = existsSync(join(pkgDir, 'lib/index.js')) && existsSync(seamLib)
+
+const fixtureServer = fileURLToPath(new URL('./fixture-server.ts', import.meta.url))
+
+let root: string
+let ws: string
+
+beforeAll(async () => {
+  root = await realpath(await mkdtemp(join(tmpdir(), 'lsp-built-')))
+  ws = join(root, 'ws')
+  await mkdir(ws)
+  await writeFile(join(ws, 'a.ts'), 'const x = 1\n')
+})
+
+afterAll(async () => {
+  if (root) await rm(root, { recursive: true, force: true })
+})
+
+describe.skipIf(!built)('built lib real load path (plain node)', () => {
+  it('runs a query through lib/index.js and disposes cleanly, framing over the base protocol', async () => {
+    const location = JSON.stringify({ uri: pathToFileURL(join(ws, 'a.ts')).href, range: { start: { line: 0, character: 0 }, end: { line: 0, character: 3 } } })
+    const script = `
+      const { Context } = await import('cordis')
+      const { default: Lsp } = await import('@deepseek-ai/dsh-lsp')
+      const LspLocal = await import('@deepseek-ai/dsh-lsp-local')
+      const ctx = new Context()
+      await ctx.plugin(Lsp)
+      await ctx.plugin(LspLocal, {
+        servers: {
+          fake: {
+            command: ${JSON.stringify(process.execPath)},
+            args: [${JSON.stringify(fixtureServer)}],
+            env: { LSP_FAKE_DEF: ${JSON.stringify(location)} },
+            extensionToLanguage: { '.ts': 'typescript' },
+          },
+        },
+      })
+      const result = await ctx.lsp.query({ operation: 'goToDefinition', filePath: 'a.ts', position: { line: 0, character: 6 }, workspaceRoot: ${JSON.stringify(ws)} })
+      console.log(JSON.stringify(result))
+      await ctx.fiber.dispose()
+    `
+    const child = spawn(process.execPath, ['--input-type=module', '-e', script], { cwd: pkgDir, stdio: ['ignore', 'pipe', 'pipe'] })
+    let stdout = ''
+    let stderr = ''
+    child.stdout.on('data', (chunk: Buffer) => { stdout += chunk.toString('utf8') })
+    child.stderr.on('data', (chunk: Buffer) => { stderr += chunk.toString('utf8') })
+    const exitCode = await new Promise<number | null>(resolve => child.on('close', resolve))
+
+    expect(exitCode, `stderr:\n${stderr}`).toBe(0)
+    const lastLine = stdout.trim().split('\n').at(-1) ?? ''
+    const result = JSON.parse(lastLine) as { kind: string; locations: unknown[] }
+    expect(result.kind).toBe('locations')
+    expect(result.locations).toHaveLength(1)
+  }, 60_000)
+})

packages/lsp/lsp-local/tests/connection.spec.ts

@@ -0,0 +1,240 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { fileURLToPath } from 'node:url'
+import { LspConnection } from '@deepseek-ai/dsh-lsp-local'
+
+const fixtureServer = fileURLToPath(new URL('./fixture-server.ts', import.meta.url))
+
+/** A recorded server→client request the test's handler saw. */
+interface SeenRequest { method: string; params: unknown }
+
+let open: LspConnection[] = []
+
+afterEach(async () => {
+  for (const conn of open) {
+    conn.kill()
+    await conn.closed
+  }
+  open = []
+})
+
+/** Spawn the fixture as a raw connection, with a scripted server-request handler. */
+function connect(
+  env: Record<string, string>,
+  onServerRequest: (method: string, params: unknown) => Promise<unknown> = () => Promise.resolve(null),
+  seen?: SeenRequest[],
+): LspConnection {
+  const conn = new LspConnection({
+    command: process.execPath,
+    args: [fixtureServer],
+    cwd: process.cwd(),
+    env: { ...process.env as Record<string, string>, ...env },
+    maxMessageBytes: 16_000_000,
+    maxStderrBytes: 100_000,
+    configuration: { setting: 42 },
+  }, (method, params) => {
+    seen?.push({ method, params })
+    return onServerRequest(method, params)
+  })
+  open.push(conn)
+  return conn
+}
+
+describe('LspConnection', () => {
+  it('completes an initialize request/response round-trip and exposes a pid', async () => {
+    const conn = connect({})
+    const result = await conn.request('initialize', { capabilities: {} })
+    expect(result).toMatchObject({ capabilities: { hoverProvider: true } })
+    expect(conn.pid).toBeGreaterThan(0)
+  })
+
+  it('rejects a request when the server replies with an error', async () => {
+    const conn = connect({ LSP_FAKE_ERROR: '1' })
+    await conn.request('initialize', { capabilities: {} })
+    await expect(conn.request('textDocument/hover', {})).rejects.toThrow(/server refused the request/)
+  })
+
+  it('answers a server workspace/configuration request from static config', async () => {
+    const seen: SeenRequest[] = []
+    const conn = connect(
+      { LSP_FAKE_ON_OPEN: 'configuration' },
+      (method, params) => {
+        if (method === 'workspace/configuration') {
+          const items = (params as { items: unknown[] }).items
+          return Promise.resolve(items.map(() => ({ setting: 42 })))
+        }
+        return Promise.resolve(null)
+      },
+      seen,
+    )
+    await conn.request('initialize', { capabilities: {} })
+    await conn.notify('textDocument/didOpen', { textDocument: { uri: 'file:///x', languageId: 'ts', version: 1, text: '' } })
+    await waitFor(() => seen.some(s => s.method === 'workspace/configuration'))
+    expect(seen[0]?.method).toBe('workspace/configuration')
+  })
+
+  it('drops a server→client notification without replying', async () => {
+    const conn = connect({ LSP_FAKE_ON_OPEN: 'notification' })
+    await conn.request('initialize', { capabilities: {} })
+    await conn.notify('textDocument/didOpen', { textDocument: { uri: 'file:///x', languageId: 'ts', version: 1, text: '' } })
+    // No throw and the connection stays usable.
+    await expect(conn.request('textDocument/hover', {})).resolves.toBeDefined()
+  })
+
+  it('sends an error response when the server-request handler rejects', async () => {
+    const seen: SeenRequest[] = []
+    const conn = connect(
+      { LSP_FAKE_ON_OPEN: 'applyEdit' },
+      method => method === 'workspace/applyEdit' ? Promise.reject(new Error('not permitted')) : Promise.resolve(null),
+      seen,
+    )
+    await conn.request('initialize', { capabilities: {} })
+    await conn.notify('textDocument/didOpen', { textDocument: { uri: 'file:///x', languageId: 'ts', version: 1, text: '' } })
+    await waitFor(() => seen.some(s => s.method === 'workspace/applyEdit'))
+    // The connection remains healthy after emitting the error response.
+    await expect(conn.request('textDocument/hover', {})).resolves.toBeDefined()
+  })
+
+  it('fails all pending requests and kills the process on a framing error', async () => {
+    const conn = connect({ LSP_FAKE_GARBAGE: '1' })
+    // The garbage byte precedes a valid initialize reply; unframed bytes are tolerated until a
+    // Content-Length header, so initialize still resolves. This exercises the decoder's resilience.
+    await expect(conn.request('initialize', { capabilities: {} })).resolves.toBeDefined()
+  })
+
+  it('rejects a new request issued after the process closes', async () => {
+    const conn = connect({})
+    await conn.request('initialize', { capabilities: {} })
+    conn.terminate()
+    await conn.closed
+    await expect(conn.request('textDocument/hover', {})).rejects.toThrow(/exited|closed/)
+  })
+
+  it('cancel is a no-op-safe write after close', async () => {
+    const conn = connect({})
+    await conn.request('initialize', { capabilities: {} })
+    conn.terminate()
+    await conn.closed
+    expect(() => { conn.cancel(1) }).not.toThrow()
+  })
+
+  it('caps the retained stderr tail', async () => {
+    const conn = connect({})
+    await conn.request('initialize', { capabilities: {} })
+    expect(conn.stderrTail.length).toBeLessThanOrEqual(100_000)
+  })
+})
+
+/** Spawn a raw connection running an inline node script as the "server". */
+function connectScript(script: string, maxStderrBytes = 100_000): LspConnection {
+  const conn = new LspConnection({
+    command: process.execPath,
+    args: ['-e', script],
+    cwd: process.cwd(),
+    env: { ...process.env as Record<string, string> },
+    maxMessageBytes: 16_000_000,
+    maxStderrBytes,
+    configuration: null,
+  }, () => Promise.resolve(null))
+  open.push(conn)
+  return conn
+}
+
+describe('LspConnection edge behavior', () => {
+  it('fails a request when the command cannot be spawned', async () => {
+    const conn = new LspConnection({
+      command: '/definitely/not/a/real/binary/xyz',
+      args: [],
+      cwd: process.cwd(),
+      env: {},
+      maxMessageBytes: 1000,
+      maxStderrBytes: 1000,
+      configuration: null,
+    }, () => Promise.resolve(null))
+    open.push(conn)
+    await expect(conn.request('initialize', {})).rejects.toThrow()
+  })
+
+  it('kills the process and fails pending requests on a framing error', async () => {
+    // Emit an invalid Content-Length header, corrupting the stream irrecoverably.
+    const conn = connectScript('process.stdout.write("Content-Length: abc\\r\\n\\r\\n{}"); setInterval(()=>{}, 1000)')
+    await expect(conn.request('initialize', {})).rejects.toThrow()
+  })
+
+  it('ignores a framed non-object message', async () => {
+    // Send a framed JSON number and a framed null (both non-objects) then a proper response to id 1.
+    const script = 'let b=Buffer.alloc(0);'
+      + 'const fr=(s)=>{const x=Buffer.from(s);return Buffer.concat([Buffer.from(`Content-Length: ${x.length}\\r\\n\\r\\n`),x]);};'
+      + 'process.stdout.write(fr("42"));process.stdout.write(fr("null"));'
+      + 'process.stdin.on("data",c=>{b=Buffer.concat([b,c]);const s=b.indexOf("\\r\\n\\r\\n");if(s<0)return;const len=Number(/(\\d+)/.exec(b.toString("ascii",0,s))[1]);const body=JSON.parse(b.toString("utf8",s+4,s+4+len));process.stdout.write(fr(JSON.stringify({jsonrpc:"2.0",id:body.id,result:{ok:true}})));});'
+    const conn = connectScript(script)
+    await expect(conn.request('initialize', {})).resolves.toEqual({ ok: true })
+  })
+
+  it('drops a response for an unknown id', async () => {
+    // Emit a response for id 999 (never sent), then answer our real request.
+    const script = 'let b=Buffer.alloc(0);'
+      + 'const fr=(s)=>{const x=Buffer.from(s);return Buffer.concat([Buffer.from(`Content-Length: ${x.length}\\r\\n\\r\\n`),x]);};'
+      + 'process.stdout.write(fr(JSON.stringify({jsonrpc:"2.0",id:999,result:{stray:true}})));'
+      + 'process.stdin.on("data",c=>{b=Buffer.concat([b,c]);const s=b.indexOf("\\r\\n\\r\\n");if(s<0)return;const len=Number(/(\\d+)/.exec(b.toString("ascii",0,s))[1]);const body=JSON.parse(b.toString("utf8",s+4,s+4+len));process.stdout.write(fr(JSON.stringify({jsonrpc:"2.0",id:body.id,result:{ok:true}})));});'
+    const conn = connectScript(script)
+    await expect(conn.request('initialize', {})).resolves.toEqual({ ok: true })
+  })
+
+  it('caps the retained stderr tail at maxStderrBytes across chunks', async () => {
+    // Write stderr repeatedly so a later chunk arrives after the cap is already reached.
+    const conn = connectScript('setInterval(()=>process.stderr.write("E".repeat(200)), 5); setInterval(()=>{}, 1000)', 100)
+    await waitFor(() => conn.stderrTail.length >= 100)
+    await new Promise<void>(resolve => setTimeout(resolve, 50))
+    expect(conn.stderrTail.length).toBe(100)
+  })
+
+  it('caps the retained stderr tail by bytes for multibyte UTF-8', async () => {
+    const conn = connectScript('process.stderr.write("😀😀")', 4)
+    await conn.closed
+    expect(conn.stderrTail).toBe('😀')
+    expect(Buffer.byteLength(conn.stderrTail)).toBe(4)
+  })
+
+  it('rejects with a fallback message when the error response has no message string', async () => {
+    const script = 'let b=Buffer.alloc(0);'
+      + 'const fr=(s)=>{const x=Buffer.from(s);return Buffer.concat([Buffer.from(`Content-Length: ${x.length}\\r\\n\\r\\n`),x]);};'
+      + 'process.stdin.on("data",c=>{b=Buffer.concat([b,c]);const s=b.indexOf("\\r\\n\\r\\n");if(s<0)return;const len=Number(/(\\d+)/.exec(b.toString("ascii",0,s))[1]);const body=JSON.parse(b.toString("utf8",s+4,s+4+len));process.stdout.write(fr(JSON.stringify({jsonrpc:"2.0",id:body.id,error:{code:-1}})));});'
+    const conn = connectScript(script)
+    await expect(conn.request('initialize', {})).rejects.toThrow(/LSP error response/)
+  })
+
+  it('rejects a pending request when the process exits mid-flight', async () => {
+    // Never responds, then exits shortly: the pending request must reject on close.
+    const conn = connectScript('setTimeout(()=>process.exit(0), 100)')
+    await expect(conn.request('initialize', {})).rejects.toThrow(/exited|closed/)
+  })
+
+  it('rejects a pending request when child stdin closes but the process stays alive', async () => {
+    const conn = connectScript('require("node:fs").closeSync(0); setInterval(()=>{}, 1000)')
+    await new Promise<void>(resolve => setTimeout(resolve, 100))
+    const timeout = new Promise<never>((_resolve, reject) => {
+      setTimeout(() => { reject(new Error('request timed out')) }, 1000)
+    })
+    await expect(Promise.race([conn.request('initialize', {}), timeout])).rejects.not.toThrow(/timed out/)
+  })
+
+  it('ignores a frame that is neither a valid request nor a numeric-id response', async () => {
+    // A frame with a string id and no method: not dispatchable; the client must ignore it and still
+    // answer our real request.
+    const script = 'let b=Buffer.alloc(0);'
+      + 'const fr=(s)=>{const x=Buffer.from(s);return Buffer.concat([Buffer.from(`Content-Length: ${x.length}\\r\\n\\r\\n`),x]);};'
+      + 'process.stdout.write(fr(JSON.stringify({jsonrpc:"2.0",id:"str-id"})));'
+      + 'process.stdin.on("data",c=>{b=Buffer.concat([b,c]);const s=b.indexOf("\\r\\n\\r\\n");if(s<0)return;const len=Number(/(\\d+)/.exec(b.toString("ascii",0,s))[1]);const body=JSON.parse(b.toString("utf8",s+4,s+4+len));process.stdout.write(fr(JSON.stringify({jsonrpc:"2.0",id:body.id,result:{ok:true}})));});'
+    const conn = connectScript(script)
+    await expect(conn.request('initialize', {})).resolves.toEqual({ ok: true })
+  })
+})
+
+/** Poll a predicate until it holds or a deadline elapses. */
+async function waitFor(predicate: () => boolean, timeoutMs = 3000): Promise<void> {
+  const start = Date.now()
+  while (!predicate()) {
+    if (Date.now() - start > timeoutMs) throw new Error('waitFor timed out')
+    await new Promise<void>(resolve => setTimeout(resolve, 10))
+  }
+}

packages/lsp/lsp-local/tests/fixture-server.ts

@@ -0,0 +1,207 @@
+/**
+ * A scriptable fake LSP server over stdio for lsp-local tests. It speaks the real
+ * `Content-Length`-framed base protocol so it exercises the client's framing, initialize handshake,
+ * transient open/close, request mapping, and teardown — without a real language server.
+ *
+ * Behavior is driven by env vars so one file backs many scenarios:
+ * - LSP_FAKE_ENCODING: advertised positionEncoding (default utf-16; "utf-8" forces a mismatch).
+ * - LSP_FAKE_SYNC: textDocumentSync value as JSON (default 1/Full).
+ * - LSP_FAKE_CAPS: JSON of extra capability flags merged into the defaults.
+ * - LSP_FAKE_DEF / LSP_FAKE_REFS / LSP_FAKE_IMPL / LSP_FAKE_HOVER: JSON result per request.
+ * - LSP_FAKE_HANG: "1" makes textDocument/* requests never respond (for abort/timeout tests).
+ * - LSP_FAKE_CRASH_ON_OPEN: "1" exits the process when a didOpen arrives (crash test).
+ * - LSP_FAKE_EXIT_AFTER_REPLY: "1" exits the process right after answering a textDocument/* request,
+ *   simulating a server that dies while idle so the pool holds a dead instance (eviction test).
+ * - LSP_FAKE_REPLY_DELAY_MS: delays each textDocument/* response by this many milliseconds.
+ * - LSP_FAKE_OPEN_MARKER: appends each didOpen document text as one JSON line to this path.
+ * - LSP_FAKE_INITIALIZED_MARKER: records when the initialized notification is received.
+ * - LSP_FAKE_PAUSE_STDIN_AFTER_INITIALIZED: "1" stops consuming stdin after initialized.
+ * - LSP_FAKE_CLOSE_STDIN_AFTER_INITIALIZED: "1" closes fd 0 after the initialized notification.
+ * - LSP_FAKE_CLOSE_STDIN_AFTER_REPLY: "1" closes fd 0 before sending the first query response.
+ * - LSP_FAKE_EXIT_DELAY_MS / LSP_FAKE_EXIT_MARKER: delay protocol exit and record exit/termination.
+ * - LSP_FAKE_NO_SHUTDOWN: "1" ignores the shutdown request (forces kill escalation).
+ * - LSP_FAKE_ON_OPEN: server→client request to emit when a didOpen arrives, one of
+ *   "configuration" | "applyEdit" | "notification" | "unknown"; the reply is logged to stderr.
+ * - LSP_FAKE_ERROR: "1" answers textDocument/* requests with a JSON-RPC error response.
+ * - LSP_FAKE_GARBAGE: "1" emits an unframed garbage byte before the initialize reply.
+ *
+ * Run: node fixture-server.ts (Node's erasable TypeScript syntax support).
+ */
+
+import { appendFileSync, closeSync } from 'node:fs'
+
+const enc = process.env.LSP_FAKE_ENCODING ?? 'utf-16'
+const sync: unknown = process.env.LSP_FAKE_SYNC !== undefined ? JSON.parse(process.env.LSP_FAKE_SYNC) : 1
+const extraCaps: unknown = process.env.LSP_FAKE_CAPS !== undefined ? JSON.parse(process.env.LSP_FAKE_CAPS) : {}
+const hang = process.env.LSP_FAKE_HANG === '1'
+const crashOnOpen = process.env.LSP_FAKE_CRASH_ON_OPEN === '1'
+const exitAfterReply = process.env.LSP_FAKE_EXIT_AFTER_REPLY === '1'
+const replyDelayMs = Number(process.env.LSP_FAKE_REPLY_DELAY_MS ?? 0)
+const openMarker = process.env.LSP_FAKE_OPEN_MARKER
+const initializedMarker = process.env.LSP_FAKE_INITIALIZED_MARKER
+const pauseStdinAfterInitialized = process.env.LSP_FAKE_PAUSE_STDIN_AFTER_INITIALIZED === '1'
+const closeStdinAfterInitialized = process.env.LSP_FAKE_CLOSE_STDIN_AFTER_INITIALIZED === '1'
+const closeStdinAfterReply = process.env.LSP_FAKE_CLOSE_STDIN_AFTER_REPLY === '1'
+const exitDelayMs = Number(process.env.LSP_FAKE_EXIT_DELAY_MS ?? 0)
+const exitMarker = process.env.LSP_FAKE_EXIT_MARKER
+const noShutdown = process.env.LSP_FAKE_NO_SHUTDOWN === '1'
+const onOpen = process.env.LSP_FAKE_ON_OPEN
+const errorReply = process.env.LSP_FAKE_ERROR === '1'
+const garbage = process.env.LSP_FAKE_GARBAGE === '1'
+
+let serverRequestId = 10_000
+const pendingServerRequests = new Map<number, string>()
+
+process.on('SIGTERM', () => {
+  markExit('TERM')
+  process.exit(0)
+})
+
+function resultFor(method: string): unknown {
+  switch (method) {
+    case 'textDocument/definition': return envJson('LSP_FAKE_DEF', null)
+    case 'textDocument/references': return envJson('LSP_FAKE_REFS', null)
+    case 'textDocument/implementation': return envJson('LSP_FAKE_IMPL', null)
+    case 'textDocument/hover': return envJson('LSP_FAKE_HOVER', null)
+    default: return null
+  }
+}
+
+function envJson(name: string, fallback: unknown): unknown {
+  const raw = process.env[name]
+  return raw === undefined ? fallback : JSON.parse(raw)
+}
+
+let buffer = Buffer.alloc(0)
+process.stdin.on('data', (chunk: Buffer) => {
+  buffer = Buffer.concat([buffer, chunk])
+  for (;;) {
+    const sep = buffer.indexOf('\r\n\r\n')
+    if (sep < 0) break
+    const header = buffer.toString('ascii', 0, sep)
+    const match = /content-length:\s*(\d+)/i.exec(header)
+    if (!match) { buffer = buffer.subarray(sep + 4); continue }
+    const length = Number(match[1])
+    const start = sep + 4
+    if (buffer.length < start + length) break
+    const body = buffer.toString('utf8', start, start + length)
+    buffer = buffer.subarray(start + length)
+    handle(JSON.parse(body) as { id?: number; method?: string; params?: unknown; result?: unknown; error?: unknown })
+  }
+})
+
+function handle(message: { id?: number; method?: string; params?: unknown; result?: unknown; error?: unknown }): void {
+  const { id, method } = message
+  // A frame with an id but no method is the client's REPLY to a server→client request; log it.
+  if (method === undefined && id !== undefined && pendingServerRequests.has(id)) {
+    const kind = pendingServerRequests.get(id)
+    pendingServerRequests.delete(id)
+    process.stderr.write(`REPLY ${kind} ${JSON.stringify({ result: message.result, error: message.error })}\n`)
+    return
+  }
+  if (method === 'initialize') {
+    if (garbage) process.stdout.write('this is not a framed message\r\n')
+    send({
+      id,
+      result: {
+        capabilities: {
+          positionEncoding: enc,
+          textDocumentSync: sync,
+          definitionProvider: true,
+          referencesProvider: true,
+          implementationProvider: true,
+          hoverProvider: true,
+          ...(extraCaps as Record<string, unknown>),
+        },
+      },
+    })
+    return
+  }
+  if (method === 'shutdown') {
+    if (noShutdown) return
+    send({ id, result: null })
+    return
+  }
+  if (method === 'exit') {
+    markExit('EXIT')
+    if (exitDelayMs > 0) {
+      setTimeout(() => {
+        markExit('CLEAN')
+        process.exit(0)
+      }, exitDelayMs)
+      return
+    }
+    markExit('CLEAN')
+    process.exit(0)
+  }
+  if (method === 'textDocument/didOpen') {
+    if (crashOnOpen) process.exit(1)
+    if (openMarker !== undefined) {
+      const params = message.params as { textDocument?: { text?: unknown } } | undefined
+      appendFileSync(openMarker, `${JSON.stringify(params?.textDocument?.text)}\n`)
+    }
+    if (onOpen !== undefined) emitServerRequest(onOpen)
+    return
+  }
+  if (method === 'initialized') {
+    if (initializedMarker !== undefined) appendFileSync(initializedMarker, 'INITIALIZED\n')
+    if (pauseStdinAfterInitialized) process.stdin.pause()
+    if (closeStdinAfterInitialized) closeSync(0)
+    return
+  }
+  if (method === 'textDocument/didClose') return
+  if (method?.startsWith('textDocument/')) {
+    if (hang) return
+    const reply = (): void => {
+      if (closeStdinAfterReply) closeSync(0)
+      if (errorReply) {
+        send({ id, error: { code: -32000, message: 'server refused the request' } })
+      } else {
+        send({ id, result: resultFor(method) })
+      }
+      // Simulate an idle death: answer this request, then exit before the next one arrives so the
+      // pool is left holding a dead instance.
+      if (exitAfterReply) setTimeout(() => process.exit(0), 20)
+    }
+    if (replyDelayMs > 0) setTimeout(reply, replyDelayMs)
+    else reply()
+    return
+  }
+  // Unknown request with an id: answer null so the client never stalls.
+  if (id !== undefined) send({ id, result: null })
+}
+
+/** Append one teardown event when the fixture is configured to expose process ordering. */
+function markExit(event: string): void {
+  if (exitMarker !== undefined) appendFileSync(exitMarker, `${event}\n`)
+}
+
+/** Emit a server→client request and log the client's reply to stderr for the test to assert. */
+function emitServerRequest(kind: string): void {
+  if (kind === 'notification') {
+    send({ method: 'window/logMessage', params: { type: 3, message: 'hello' } })
+    return
+  }
+  const id = serverRequestId++
+  const method = kind === 'configuration'
+    ? 'workspace/configuration'
+    : kind === 'applyEdit'
+      ? 'workspace/applyEdit'
+      : kind === 'lifecycle'
+        ? 'client/registerCapability'
+        : 'window/showMessageRequest'
+  const params = kind === 'configuration' ? { items: [{ section: 'a' }, { section: 'b' }] } : {}
+  pendingServerRequests.set(id, method)
+  send({ id, method, params })
+}
+
+function send(message: Record<string, unknown>): void {
+  const body = Buffer.from(JSON.stringify({ jsonrpc: '2.0', ...message }), 'utf8')
+  process.stdout.write(Buffer.concat([Buffer.from(`Content-Length: ${body.length}\r\n\r\n`, 'ascii'), body]))
+}
+
+// Keep the event loop alive.
+process.stdin.resume()
+if (pauseStdinAfterInitialized || closeStdinAfterInitialized || closeStdinAfterReply) {
+  setInterval(() => {}, 1000)
+}

packages/lsp/lsp-local/tests/framing.spec.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'vitest'
+import { encodeMessage, MessageDecoder } from '@deepseek-ai/dsh-lsp-local'
+
+/** Frame a message the way a server would, for decoder round-trips. */
+function frame(body: string): Buffer {
+  return Buffer.concat([Buffer.from(`Content-Length: ${Buffer.byteLength(body)}\r\n\r\n`, 'ascii'), Buffer.from(body, 'utf8')])
+}
+
+describe('encodeMessage', () => {
+  it('prefixes a Content-Length header with the utf-8 byte length', () => {
+    const buffer = encodeMessage({ jsonrpc: '2.0', method: 'x', params: { s: 'é' } })
+    const text = buffer.toString('utf8')
+    const body = '{"jsonrpc":"2.0","method":"x","params":{"s":"é"}}'
+    expect(text).toBe(`Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`)
+  })
+})
+
+describe('MessageDecoder', () => {
+  it('decodes a single framed message', () => {
+    const decoder = new MessageDecoder(1_000)
+    expect(decoder.push(frame('{"id":1,"result":42}'))).toEqual([{ id: 1, result: 42 }])
+  })
+
+  it('decodes multiple messages arriving in one chunk', () => {
+    const decoder = new MessageDecoder(1_000)
+    const chunk = Buffer.concat([frame('{"a":1}'), frame('{"b":2}')])
+    expect(decoder.push(chunk)).toEqual([{ a: 1 }, { b: 2 }])
+  })
+
+  it('reassembles a message split across chunks', () => {
+    const decoder = new MessageDecoder(1_000)
+    const full = frame('{"hello":"world"}')
+    expect(decoder.push(full.subarray(0, 10))).toEqual([])
+    expect(decoder.push(full.subarray(10))).toEqual([{ hello: 'world' }])
+  })
+
+  it('handles a header split from its body', () => {
+    const decoder = new MessageDecoder(1_000)
+    const body = '{"x":1}'
+    expect(decoder.push(Buffer.from(`Content-Length: ${body.length}\r\n\r\n`, 'ascii'))).toEqual([])
+    expect(decoder.push(Buffer.from(body, 'utf8'))).toEqual([{ x: 1 }])
+  })
+
+  it('reads a case-insensitive header and ignores other headers', () => {
+    const decoder = new MessageDecoder(1_000)
+    const body = '{"ok":true}'
+    const chunk = Buffer.from(`content-length: ${body.length}\r\nContent-Type: x\r\n\r\n${body}`, 'utf8')
+    expect(decoder.push(chunk)).toEqual([{ ok: true }])
+  })
+
+  it('rejects a body over the size limit', () => {
+    const decoder = new MessageDecoder(4)
+    expect(() => decoder.push(frame('{"big":true}'))).toThrow(/exceeds the 4-byte limit/)
+  })
+
+  it('rejects a missing Content-Length header', () => {
+    const decoder = new MessageDecoder(1_000)
+    expect(() => decoder.push(Buffer.from('X: 1\r\n\r\n{}', 'utf8'))).toThrow(/missing Content-Length/)
+  })
+
+  it('rejects a non-numeric Content-Length', () => {
+    const decoder = new MessageDecoder(1_000)
+    expect(() => decoder.push(Buffer.from('Content-Length: abc\r\n\r\n{}', 'utf8'))).toThrow(/invalid Content-Length/)
+  })
+
+  it('rejects a header block that never terminates', () => {
+    const decoder = new MessageDecoder(1_000)
+    const huge = Buffer.alloc((1 << 16) + 1, 0x41)
+    expect(() => decoder.push(huge)).toThrow(/exceeded .* bytes without a terminator/)
+  })
+
+  it('rejects an oversized header block that includes its terminator', () => {
+    const decoder = new MessageDecoder(1_000)
+    const huge = Buffer.from(`Content-Length: 2\r\nX-Fill: ${'a'.repeat(70_000)}\r\n\r\n{}`, 'ascii')
+    expect(() => decoder.push(huge)).toThrow(/header exceeded .* bytes/)
+  })
+
+  it('rejects a non-JSON body', () => {
+    const decoder = new MessageDecoder(1_000)
+    expect(() => decoder.push(frame('not json'))).toThrow(/not valid JSON/)
+  })
+})

packages/lsp/lsp-local/tests/host.spec.ts

@@ -0,0 +1,131 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { mkdtemp, mkdir, rm, symlink, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { realpath } from 'node:fs/promises'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { deadline } from '@deepseek-ai/dsh-timeout'
+import { canonicalizeWorkspace, readHostSource } from '@deepseek-ai/dsh-lsp-local'
+
+const execFileAsync = promisify(execFile)
+
+let root: string
+let ws: string
+
+beforeEach(async () => {
+  root = await realpath(await mkdtemp(join(tmpdir(), 'lsp-host-')))
+  ws = join(root, 'ws')
+  await mkdir(ws)
+})
+
+afterEach(async () => {
+  await rm(root, { recursive: true, force: true })
+})
+
+const BIG = 1_000_000
+
+describe('canonicalizeWorkspace', () => {
+  it('returns the realpath of a directory', async () => {
+    expect(await canonicalizeWorkspace(ws)).toBe(ws)
+  })
+
+  it('resolves a symlinked workspace to its target so aliases share identity', async () => {
+    const link = join(root, 'ws-link')
+    await symlink(ws, link)
+    expect(await canonicalizeWorkspace(link)).toBe(ws)
+  })
+
+  it('rejects a missing workspace', async () => {
+    await expect(canonicalizeWorkspace(join(root, 'nope'))).rejects.toThrow(/cannot be resolved/)
+  })
+
+  it('rejects a non-directory workspace', async () => {
+    const file = join(root, 'file.txt')
+    await writeFile(file, 'x')
+    await expect(canonicalizeWorkspace(file)).rejects.toThrow(/not a directory/)
+  })
+})
+
+describe('readHostSource', () => {
+  it('reads a relative path against the workspace', async () => {
+    await writeFile(join(ws, 'a.ts'), 'const x = 1\n')
+    const source = await readHostSource('a.ts', ws, BIG)
+    expect(source.canonicalPath).toBe(join(ws, 'a.ts'))
+    expect(source.text).toBe('const x = 1\n')
+  })
+
+  it('reads an absolute path inside the workspace', async () => {
+    const abs = join(ws, 'b.ts')
+    await writeFile(abs, 'b')
+    const source = await readHostSource(abs, ws, BIG)
+    expect(source.canonicalPath).toBe(abs)
+  })
+
+  it('accepts a source reached through a symlink that stays inside the workspace', async () => {
+    await mkdir(join(ws, 'real'))
+    await writeFile(join(ws, 'real', 'c.ts'), 'c')
+    await symlink(join(ws, 'real'), join(ws, 'linked'))
+    const source = await readHostSource('linked/c.ts', ws, BIG)
+    expect(source.canonicalPath).toBe(join(ws, 'real', 'c.ts'))
+  })
+
+  it('rejects a source whose canonical path escapes the workspace via symlink', async () => {
+    const outside = join(root, 'outside.ts')
+    await writeFile(outside, 'secret')
+    await symlink(outside, join(ws, 'escape.ts'))
+    await expect(readHostSource('escape.ts', ws, BIG)).rejects.toThrow(/outside the workspace/)
+  })
+
+  it('rejects an absolute source outside the workspace', async () => {
+    const outside = join(root, 'out.ts')
+    await writeFile(outside, 'x')
+    await expect(readHostSource(outside, ws, BIG)).rejects.toThrow(/outside the workspace/)
+  })
+
+  it('rejects a missing source', async () => {
+    await expect(readHostSource('nope.ts', ws, BIG)).rejects.toThrow(/cannot be resolved/)
+  })
+
+  it('rejects a non-regular source (directory)', async () => {
+    await mkdir(join(ws, 'dir'))
+    await expect(readHostSource('dir', ws, BIG)).rejects.toThrow(/not a regular file/)
+  })
+
+  it('rejects a FIFO with no writer without blocking in open', async () => {
+    const fifo = join(ws, 'pipe.ts')
+    await execFileAsync('mkfifo', [fifo])
+    using d = deadline(undefined, 1000, 'FIFO_READ_TIMEOUT')
+    await expect(readHostSource('pipe.ts', ws, BIG, d.signal)).rejects.toThrow(/not a regular file/)
+  })
+
+  it('honors a pre-aborted source read before filesystem work', async () => {
+    const controller = new AbortController()
+    controller.abort(new Error('source read cancelled'))
+    await expect(readHostSource('missing.ts', ws, BIG, controller.signal)).rejects.toThrow(/source read cancelled/)
+  })
+
+  it('treats the workspace root itself as inside, then rejects it as non-regular', async () => {
+    // filePath '.' canonicalizes to the workspace dir: isInside's identity branch is taken, and the
+    // directory then fails the regular-file check.
+    await expect(readHostSource('.', ws, BIG)).rejects.toThrow(/not a regular file/)
+  })
+
+  it('rejects an oversized source', async () => {
+    await writeFile(join(ws, 'big.ts'), 'x'.repeat(100))
+    await expect(readHostSource('big.ts', ws, 10)).rejects.toThrow(/over the 10-byte limit/)
+  })
+
+  it('rejects a non-UTF-8 source', async () => {
+    await writeFile(join(ws, 'bin.ts'), Buffer.from([0xff, 0xfe, 0x00]))
+    await expect(readHostSource('bin.ts', ws, BIG)).rejects.toThrow(/not valid UTF-8/)
+  })
+
+  it('keeps a valid U+FFFD replacement character in otherwise-valid UTF-8', async () => {
+    // The literal replacement char is valid UTF-8; a fatal decoder must accept it (only malformed
+    // byte sequences are rejected).
+    await writeFile(join(ws, 'repl.ts'), 'const s = "<22>"\n')
+    const source = await readHostSource('repl.ts', ws, BIG)
+    expect(source.text).toBe('const s = "<22>"\n')
+  })
+})

packages/lsp/lsp-local/tests/instance.spec.ts

@@ -0,0 +1,338 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { mkdtemp, mkdir, readFile, rm, writeFile, realpath } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { pathToFileURL, fileURLToPath } from 'node:url'
+import { LspInstance, readHostSource } from '@deepseek-ai/dsh-lsp-local'
+import type { InstanceSpec } from '@deepseek-ai/dsh-lsp-local/src/instance.ts'
+import type { LspProviderQuery, LspQueryResult } from '@deepseek-ai/dsh-lsp'
+
+const fixtureServer = fileURLToPath(new URL('./fixture-server.ts', import.meta.url))
+
+let root: string
+let ws: string
+let live: LspInstance[] = []
+
+beforeEach(async () => {
+  root = await realpath(await mkdtemp(join(tmpdir(), 'lsp-inst-')))
+  ws = join(root, 'ws')
+  await mkdir(ws)
+  await writeFile(join(ws, 'a.ts'), 'const x = 1\n')
+})
+
+afterEach(async () => {
+  for (const instance of live) await instance.dispose()
+  live = []
+  await rm(root, { recursive: true, force: true })
+})
+
+function makeInstance(env: Record<string, string> = {}, overrides: Partial<InstanceSpec> = {}): LspInstance {
+  const instance = new LspInstance({
+    command: process.execPath,
+    args: [fixtureServer],
+    cwd: ws,
+    env: { ...process.env as Record<string, string>, ...env },
+    configuration: { setting: 42 },
+    initializationOptions: { init: true },
+    maxMessageBytes: 16_000_000,
+    maxStderrBytes: 100_000,
+    shutdownTimeoutMs: 200,
+    killGraceMs: 200,
+    ...overrides,
+  })
+  live.push(instance)
+  return instance
+}
+
+function query(operation: LspProviderQuery['operation'] = 'goToDefinition'): LspProviderQuery {
+  return { operation, filePath: 'a.ts', position: { line: 0, character: 6 }, workspaceRoot: ws, languageId: 'typescript' }
+}
+
+/** Run a query against an instance, reading the source first the way the provider does. */
+async function run(instance: LspInstance, operation: LspProviderQuery['operation'] = 'goToDefinition', signal?: AbortSignal): Promise<LspQueryResult> {
+  const source = await readHostSource('a.ts', ws, 4_000_000)
+  return instance.query(query(operation), source, signal)
+}
+
+/** Build an instance whose "server" is an inline node script (for teardown-escalation control). */
+function scriptInstance(script: string, overrides: Partial<InstanceSpec> = {}): LspInstance {
+  const instance = new LspInstance({
+    command: process.execPath,
+    args: ['-e', script],
+    cwd: ws,
+    env: { ...process.env as Record<string, string> },
+    configuration: null,
+    initializationOptions: null,
+    maxMessageBytes: 16_000_000,
+    maxStderrBytes: 100_000,
+    shutdownTimeoutMs: 150,
+    killGraceMs: 150,
+    ...overrides,
+  })
+  live.push(instance)
+  return instance
+}
+
+/** An inline server that answers initialize + definition and echoes a location. */
+const RESPONDING_SERVER =
+  'let b=Buffer.alloc(0);'
+  + 'const fr=(o)=>{const x=Buffer.from(JSON.stringify({jsonrpc:"2.0",...o}));return Buffer.concat([Buffer.from(`Content-Length: ${x.length}\\r\\n\\r\\n`),x]);};'
+  + 'process.stdin.on("data",c=>{b=Buffer.concat([b,c]);for(;;){const s=b.indexOf("\\r\\n\\r\\n");if(s<0)break;const len=Number(/(\\d+)/.exec(b.toString("ascii",0,s))[1]);if(b.length<s+4+len)break;const m=JSON.parse(b.toString("utf8",s+4,s+4+len));b=b.subarray(s+4+len);'
+  + 'if(m.method==="initialize")process.stdout.write(fr({id:m.id,result:{capabilities:{positionEncoding:"utf-16",textDocumentSync:1,definitionProvider:true}}}));'
+  + 'else if(m.method==="textDocument/definition")process.stdout.write(fr({id:m.id,result:null}));'
+  + '}});'
+
+const locJson = () => JSON.stringify({ uri: pathToFileURL(join(ws, 'a.ts')).href, range: { start: { line: 0, character: 0 }, end: { line: 0, character: 3 } } })
+
+describe('LspInstance server-request handling', () => {
+  it('answers workspace/configuration with the static config per item', async () => {
+    const instance = makeInstance({ LSP_FAKE_ON_OPEN: 'configuration', LSP_FAKE_DEF: locJson() })
+    // The query drives didOpen, which makes the fake emit workspace/configuration; a healthy answer
+    // keeps the query working.
+    await expect(run(instance, 'goToDefinition')).resolves.toMatchObject({ kind: 'locations' })
+  })
+
+  it('accepts a lifecycle client/registerCapability request', async () => {
+    const instance = makeInstance({ LSP_FAKE_ON_OPEN: 'lifecycle', LSP_FAKE_DEF: 'null' })
+    await expect(run(instance, 'goToDefinition')).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: ws })
+  })
+
+  it('rejects a workspace/applyEdit request but keeps serving', async () => {
+    const instance = makeInstance({ LSP_FAKE_ON_OPEN: 'applyEdit', LSP_FAKE_DEF: 'null' })
+    await expect(run(instance, 'goToDefinition')).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: ws })
+  })
+
+  it('rejects an unknown server request but keeps serving', async () => {
+    const instance = makeInstance({ LSP_FAKE_ON_OPEN: 'unknown', LSP_FAKE_DEF: 'null' })
+    await expect(run(instance, 'goToDefinition')).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: ws })
+  })
+})
+
+describe('LspInstance query and abort', () => {
+  it('sends includeDeclaration for references', async () => {
+    const instance = makeInstance({ LSP_FAKE_REFS: JSON.stringify([JSON.parse(locJson())]) })
+    await expect(run(instance, 'findReferences')).resolves.toMatchObject({ kind: 'locations' })
+  })
+
+  it('rejects a query aborted before it starts', async () => {
+    const instance = makeInstance({ LSP_FAKE_DEF: 'null' })
+    const controller = new AbortController()
+    controller.abort(new Error('pre-abort'))
+    await expect(run(instance, 'goToDefinition', controller.signal)).rejects.toThrow(/pre-abort/)
+  })
+
+  it('cancels an in-flight request on abort and rejects', async () => {
+    const instance = makeInstance({ LSP_FAKE_HANG: '1' })
+    const controller = new AbortController()
+    // Warm the instance first so the abort lands during the hanging request, not during startup.
+    const pending = run(instance, 'goToDefinition', controller.signal)
+    await new Promise<void>(resolve => setTimeout(resolve, 300))
+    controller.abort(new Error('mid-flight'))
+    await expect(pending).rejects.toThrow(/mid-flight/)
+  })
+
+  it('terminates the instance when the server ignores $/cancelRequest past the grace', async () => {
+    // The hang server never honors cancellation, so after the bounded grace the instance must be torn
+    // down (its process closed) rather than left with an active request.
+    const instance = makeInstance({ LSP_FAKE_HANG: '1' }, { killGraceMs: 100 })
+    const controller = new AbortController()
+    const pending = run(instance, 'goToDefinition', controller.signal)
+    await new Promise<void>(resolve => setTimeout(resolve, 300))
+    controller.abort(new Error('mid-flight'))
+    await expect(pending).rejects.toThrow(/mid-flight/)
+    expect(instance.dead).toBe(true)
+  })
+
+  it('resolves the cancel grace when the server honors $/cancelRequest', async () => {
+    // A server that answers $/cancelRequest by settling the pending request lets the grace race
+    // resolve via the request rather than the timeout, so the instance is NOT force-terminated.
+    const script = 'let b=Buffer.alloc(0),reqId=null;'
+      + 'const fr=(o)=>{const x=Buffer.from(JSON.stringify({jsonrpc:"2.0",...o}));return Buffer.concat([Buffer.from(`Content-Length: ${x.length}\\r\\n\\r\\n`),x]);};'
+      + 'process.stdin.on("data",c=>{b=Buffer.concat([b,c]);for(;;){const s=b.indexOf("\\r\\n\\r\\n");if(s<0)break;const len=Number(/(\\d+)/.exec(b.toString("ascii",0,s))[1]);if(b.length<s+4+len)break;const m=JSON.parse(b.toString("utf8",s+4,s+4+len));b=b.subarray(s+4+len);'
+      + 'if(m.method==="initialize")process.stdout.write(fr({id:m.id,result:{capabilities:{positionEncoding:"utf-16",textDocumentSync:1,definitionProvider:true}}}));'
+      + 'else if(m.method==="textDocument/definition")reqId=m.id;'
+      + 'else if(m.method==="$/cancelRequest"&&reqId!==null)process.stdout.write(fr({id:reqId,error:{code:-32800,message:"request cancelled"}}));'
+      + 'else if(m.method==="shutdown")process.stdout.write(fr({id:m.id,result:null}));'
+      + 'else if(m.method==="exit")process.exit(0);'
+      + '}});'
+    const instance = scriptInstance(script, { killGraceMs: 2_000 })
+    const controller = new AbortController()
+    const pending = run(instance, 'goToDefinition', controller.signal)
+    await new Promise<void>(resolve => setTimeout(resolve, 300))
+    controller.abort(new Error('mid-flight'))
+    await expect(pending).rejects.toThrow(/mid-flight/)
+    // The server acknowledged cancellation within grace, so the instance was not force-killed.
+    expect(instance.dead).toBe(false)
+    await instance.dispose()
+  })
+
+  it('observes abort while awaiting a slow initialize handshake', async () => {
+    // A server that answers nothing (not even initialize) leaves `ready` pending; an abort must be
+    // observed during that wait instead of hanging the tool-timeout signal.
+    const instance = scriptInstance('setInterval(()=>{},1000)', { killGraceMs: 100 })
+    const controller = new AbortController()
+    const pending = run(instance, 'goToDefinition', controller.signal)
+    await new Promise<void>(resolve => setTimeout(resolve, 150))
+    controller.abort(new Error('handshake-abort'))
+    await expect(pending).rejects.toThrow(/handshake-abort/)
+    await instance.dispose()
+  })
+
+  it('terminates when abort interrupts a backpressured didOpen write', async () => {
+    // The fixture consumes initialized, then stops reading. A document larger than the stdio pipe
+    // keeps didOpen's write callback pending until cancellation forces bounded process teardown.
+    await writeFile(join(ws, 'a.ts'), 'x'.repeat(2_000_000))
+    const marker = join(root, 'initialized.log')
+    const instance = makeInstance({
+      LSP_FAKE_INITIALIZED_MARKER: marker,
+      LSP_FAKE_PAUSE_STDIN_AFTER_INITIALIZED: '1',
+    }, {
+      shutdownTimeoutMs: 100,
+      killGraceMs: 100,
+    })
+    const controller = new AbortController()
+    const pending = run(instance, 'goToDefinition', controller.signal)
+    await waitForFile(marker)
+    // Let the client enter the large didOpen write after the fixture has paused stdin.
+    await new Promise<void>(resolve => setTimeout(resolve, 100))
+    controller.abort(new Error('didOpen-abort'))
+    await expect(pending).rejects.toThrow(/didOpen-abort/)
+    expect(instance.dead).toBe(true)
+  })
+
+  it('terminates when stdin fails during the didOpen write', async () => {
+    // Closing stdin after initialized makes a large didOpen fail before `opened` can arm didClose;
+    // the instance must still become dead so its provider can replace it.
+    await writeFile(join(ws, 'a.ts'), 'x'.repeat(2_000_000))
+    const instance = makeInstance({ LSP_FAKE_CLOSE_STDIN_AFTER_INITIALIZED: '1' }, {
+      shutdownTimeoutMs: 100,
+      killGraceMs: 100,
+    })
+    await expect(run(instance, 'goToDefinition')).rejects.toThrow()
+    expect(instance.dead).toBe(true)
+  })
+
+  it('rejects when the server lacks the operation capability', async () => {
+    const instance = makeInstance({ LSP_FAKE_CAPS: JSON.stringify({ definitionProvider: false }), LSP_FAKE_DEF: 'null' })
+    await expect(run(instance, 'goToDefinition')).rejects.toThrow(/does not support goToDefinition/)
+  })
+
+  it('propagates a server error response even when a signal is supplied (not an abort)', async () => {
+    // A live signal is passed, but the request fails for a server reason; the catch must rethrow
+    // without treating it as an abort.
+    const instance = makeInstance({ LSP_FAKE_ERROR: '1' })
+    const controller = new AbortController()
+    await expect(run(instance, 'goToDefinition', controller.signal)).rejects.toThrow(/server refused/)
+  })
+
+  it('keeps a settled result but awaits teardown when didClose cannot be written', async () => {
+    const instance = makeInstance({
+      LSP_FAKE_DEF: 'null',
+      LSP_FAKE_CLOSE_STDIN_AFTER_REPLY: '1',
+    }, { shutdownTimeoutMs: 100, killGraceMs: 100 })
+    await expect(run(instance, 'goToDefinition')).resolves.toEqual({
+      kind: 'locations',
+      locations: [],
+      resolvedWorkspaceRoot: ws,
+    })
+    expect(instance.dead).toBe(true)
+  })
+})
+
+describe('LspInstance disposal', () => {
+  it('lets a server finish protocol exit before signal escalation', async () => {
+    const marker = join(root, 'graceful-exit.log')
+    const instance = makeInstance({
+      LSP_FAKE_DEF: 'null',
+      LSP_FAKE_EXIT_DELAY_MS: '75',
+      LSP_FAKE_EXIT_MARKER: marker,
+    }, { shutdownTimeoutMs: 500 })
+    await run(instance, 'goToDefinition')
+    await instance.dispose()
+    expect(await readFile(marker, 'utf8')).toBe('EXIT\nCLEAN\n')
+  })
+
+  it('is idempotent — a second dispose awaits close without error', async () => {
+    const instance = makeInstance({ LSP_FAKE_DEF: 'null' })
+    await run(instance, 'goToDefinition')
+    await instance.dispose()
+    await expect(instance.dispose()).resolves.toBeUndefined()
+  })
+
+  it('rejects a query after disposal', async () => {
+    const instance = makeInstance({ LSP_FAKE_DEF: 'null' })
+    await run(instance, 'goToDefinition')
+    await instance.dispose()
+    await expect(run(instance, 'goToDefinition')).rejects.toThrow(expect.objectContaining({ code: 'LSP_DISPOSED' }))
+  })
+
+  it('reports dead after the process closes', async () => {
+    const instance = makeInstance({ LSP_FAKE_DEF: 'null' })
+    await run(instance, 'goToDefinition')
+    await instance.dispose()
+    expect(instance.dead).toBe(true)
+  })
+
+  it('escalates to SIGKILL when the server ignores shutdown and SIGTERM', async () => {
+    // Server answers initialize, ignores shutdown, and traps SIGTERM so only SIGKILL stops it.
+    const script = RESPONDING_SERVER + 'process.on("SIGTERM",()=>{});'
+    const instance = scriptInstance(script, { shutdownTimeoutMs: 100, killGraceMs: 100 })
+    await run(instance, 'goToDefinition')
+    await expect(instance.dispose()).resolves.toBeUndefined()
+  })
+
+  it('awaits a surviving process-group helper on every concurrent dispose', async () => {
+    const marker = join(root, 'helper.pid')
+    const helper = 'process.on("SIGTERM",()=>{});setInterval(()=>{},1000);'
+    const script = 'const{spawn}=require("node:child_process");const{writeFileSync}=require("node:fs");'
+      + `const helper=spawn(process.execPath,["-e",${JSON.stringify(helper)}],{stdio:"ignore"});`
+      + `writeFileSync(${JSON.stringify(marker)},String(helper.pid));`
+      + RESPONDING_SERVER
+    const instance = scriptInstance(script, { shutdownTimeoutMs: 100, killGraceMs: 100 })
+    await run(instance, 'goToDefinition')
+    const helperPid = Number(await readFile(marker, 'utf8'))
+    try {
+      const first = instance.dispose()
+      await instance.dispose()
+      expect(processAlive(helperPid)).toBe(false)
+      await first
+    } finally {
+      if (processAlive(helperPid)) process.kill(helperPid, 'SIGKILL')
+    }
+  })
+
+  it('carries a non-Error abort reason as a generic aborted error', async () => {
+    const instance = makeInstance({ LSP_FAKE_HANG: '1' })
+    const controller = new AbortController()
+    const pending = run(instance, 'goToDefinition', controller.signal)
+    await new Promise<void>(resolve => setTimeout(resolve, 200))
+    controller.abort('a string reason, not an Error')
+    await expect(pending).rejects.toThrow(/aborted/)
+  })
+})
+
+/** Probe a pid without changing its state. */
+function processAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ESRCH') return false
+    throw error
+  }
+}
+
+/** Wait until a fixture marker exists, bounded so a broken handshake cannot hang the test. */
+async function waitForFile(path: string, timeoutMs = 3000): Promise<void> {
+  const started = Date.now()
+  for (;;) {
+    try {
+      await readFile(path)
+      return
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+    }
+    if (Date.now() - started > timeoutMs) throw new Error('waitForFile timed out')
+    await new Promise<void>(resolve => setTimeout(resolve, 10))
+  }
+}

packages/lsp/lsp-local/tests/lifecycle.spec.ts

@@ -0,0 +1,319 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { realpath } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { pathToFileURL, fileURLToPath } from 'node:url'
+import { Context } from 'cordis'
+import Lsp, { type LspQueryRequest, type LspQueryResult } from '@deepseek-ai/dsh-lsp'
+import { deadline } from '@deepseek-ai/dsh-timeout'
+import * as LspLocal from '@deepseek-ai/dsh-lsp-local'
+import type { LspLocalServerConfig } from '@deepseek-ai/dsh-lsp-local'
+
+const fixtureServer = fileURLToPath(new URL('./fixture-server.ts', import.meta.url))
+
+let root: string
+let ws: string
+
+beforeEach(async () => {
+  root = await realpath(await mkdtemp(join(tmpdir(), 'lsp-local-')))
+  ws = join(root, 'ws')
+  await mkdir(ws)
+  await writeFile(join(ws, 'a.ts'), 'const x = 1\nconst y = x\n')
+})
+
+afterEach(async () => {
+  await rm(root, { recursive: true, force: true })
+})
+
+/** One fake stdio server entry with optional behavior and host-bound overrides. */
+function fakeServer(fakeEnv: Record<string, string> = {}, overrides: Partial<LspLocalServerConfig> = {}): LspLocalServerConfig {
+  return {
+    command: process.execPath,
+    args: [fixtureServer],
+    env: { ...fakeEnv },
+    extensionToLanguage: { '.ts': 'typescript' },
+    ...overrides,
+  }
+}
+
+/** Mount the real seam + lsp-local plugin driving one fake server. */
+async function mount(fakeEnv: Record<string, string> = {}, overrides: Partial<LspLocalServerConfig> = {}): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(Lsp)
+  await ctx.plugin(LspLocal, {
+    servers: { fake: fakeServer(fakeEnv, overrides) },
+  })
+  return ctx
+}
+
+function query(operation: LspQueryRequest['operation'], filePath = 'a.ts'): LspQueryRequest {
+  return { operation, filePath, position: { line: 0, character: 6 }, workspaceRoot: ws }
+}
+
+/** A single Location JSON pointing into the workspace. */
+function locationJson(line: number): unknown {
+  return { uri: pathToFileURL(join(ws, 'a.ts')).href, range: { start: { line, character: 0 }, end: { line, character: 3 } } }
+}
+
+describe('lsp-local end to end over a fake server', () => {
+  it('routes different extensions to independent configured servers', async () => {
+    await writeFile(join(ws, 'a.py'), 'x = 1\n')
+    const ctx = new Context()
+    await ctx.plugin(Lsp)
+    await ctx.plugin(LspLocal, {
+      servers: {
+        typescript: fakeServer({ LSP_FAKE_HOVER: JSON.stringify({ contents: 'ts' }) }),
+        python: fakeServer(
+          { LSP_FAKE_HOVER: JSON.stringify({ contents: 'py' }) },
+          { extensionToLanguage: { '.py': 'python' } },
+        ),
+      },
+    })
+    expect(await ctx.lsp.query(query('hover', 'a.ts'))).toEqual({ kind: 'hover', hover: { contents: 'ts' } })
+    expect(await ctx.lsp.query(query('hover', 'a.py'))).toEqual({ kind: 'hover', hover: { contents: 'py' } })
+    await ctx.fiber.dispose()
+  })
+
+  it('resolves definition to normalized locations', async () => {
+    const ctx = await mount({ LSP_FAKE_DEF: JSON.stringify(locationJson(0)) })
+    const result = await ctx.lsp.query(query('goToDefinition'))
+    expect(result).toEqual<LspQueryResult>({
+      kind: 'locations',
+      locations: [{ uri: pathToFileURL(join(ws, 'a.ts')).href, range: { start: { line: 0, character: 0 }, end: { line: 0, character: 3 } } }],
+      resolvedWorkspaceRoot: ws,
+    })
+    await ctx.fiber.dispose()
+  })
+
+  it('maps a LocationLink for implementation', async () => {
+    const link = { targetUri: pathToFileURL(join(ws, 'a.ts')).href, targetSelectionRange: { start: { line: 1, character: 0 }, end: { line: 1, character: 2 } } }
+    const ctx = await mount({ LSP_FAKE_IMPL: JSON.stringify([link]) })
+    const result = await ctx.lsp.query(query('goToImplementation'))
+    expect(result).toMatchObject({ kind: 'locations', locations: [{ range: { start: { line: 1, character: 0 } } }] })
+    await ctx.fiber.dispose()
+  })
+
+  it('returns references (server includes the declaration)', async () => {
+    const ctx = await mount({ LSP_FAKE_REFS: JSON.stringify([locationJson(0), locationJson(1)]) })
+    const result = await ctx.lsp.query(query('findReferences'))
+    expect(result).toMatchObject({ kind: 'locations' })
+    if (result.kind !== 'locations') throw new Error('expected locations')
+    expect(result.locations).toHaveLength(2)
+    await ctx.fiber.dispose()
+  })
+
+  it('normalizes a hover MarkupContent', async () => {
+    const ctx = await mount({ LSP_FAKE_HOVER: JSON.stringify({ contents: { kind: 'markdown', value: 'docs' } }) })
+    const result = await ctx.lsp.query(query('hover'))
+    expect(result).toEqual({ kind: 'hover', hover: { contents: 'docs' } })
+    await ctx.fiber.dispose()
+  })
+
+  it('returns an empty locations result for a null definition', async () => {
+    const ctx = await mount({ LSP_FAKE_DEF: 'null' })
+    expect(await ctx.lsp.query(query('goToDefinition'))).toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: ws })
+    await ctx.fiber.dispose()
+  })
+
+  it('returns a null hover for a null result', async () => {
+    const ctx = await mount({ LSP_FAKE_HOVER: 'null' })
+    expect(await ctx.lsp.query(query('hover'))).toEqual({ kind: 'hover', hover: null })
+    await ctx.fiber.dispose()
+  })
+
+  it('rejects a non-utf-16 position encoding at initialize', async () => {
+    const ctx = await mount({ LSP_FAKE_ENCODING: 'utf-8', LSP_FAKE_DEF: 'null' })
+    await expect(ctx.lsp.query(query('goToDefinition'))).rejects.toThrow(/unsupported position encoding/)
+    await ctx.fiber.dispose()
+  })
+
+  it('does not pool a poisoned instance when initialize rejects', async () => {
+    // A utf-8 server makes `initialize` reject; the instance must be torn down (not left with a
+    // permanently-rejecting `ready`) so a later query starts a fresh process rather than reusing it.
+    const ctx = await mount({ LSP_FAKE_ENCODING: 'utf-8', LSP_FAKE_DEF: 'null' })
+    await expect(ctx.lsp.query(query('goToDefinition'))).rejects.toThrow(/unsupported position encoding/)
+    // A second query must also fail the same way (fresh instance), and must NOT hang on a poisoned one.
+    await expect(ctx.lsp.query(query('goToDefinition'))).rejects.toThrow(/unsupported position encoding/)
+    await ctx.fiber.dispose()
+  })
+
+  it('rejects a server without transient-open sync (None)', async () => {
+    const ctx = await mount({ LSP_FAKE_SYNC: '0', LSP_FAKE_DEF: 'null' })
+    await expect(ctx.lsp.query(query('goToDefinition'))).rejects.toThrow(/transient textDocument\/didOpen/)
+    await ctx.fiber.dispose()
+  })
+
+  it('accepts openClose options sync', async () => {
+    const ctx = await mount({ LSP_FAKE_SYNC: JSON.stringify({ openClose: true, change: 2 }), LSP_FAKE_DEF: 'null' })
+    expect(await ctx.lsp.query(query('goToDefinition'))).toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: ws })
+    await ctx.fiber.dispose()
+  })
+
+  it('fails a query for an unsupported operation', async () => {
+    const ctx = await mount({ LSP_FAKE_CAPS: JSON.stringify({ hoverProvider: false }), LSP_FAKE_DEF: 'null' })
+    await expect(ctx.lsp.query(query('hover'))).rejects.toThrow(/does not support hover/)
+    await ctx.fiber.dispose()
+  })
+
+  it('rejects a source outside the workspace before startup', async () => {
+    const outside = join(root, 'out.ts')
+    await writeFile(outside, 'x')
+    const ctx = await mount({ LSP_FAKE_DEF: 'null' })
+    await expect(ctx.lsp.query({ ...query('goToDefinition'), filePath: outside })).rejects.toThrow(/outside the workspace/)
+    await ctx.fiber.dispose()
+  })
+
+  it('serializes queries through one instance and runs them in order', async () => {
+    const ctx = await mount({ LSP_FAKE_DEF: JSON.stringify(locationJson(0)) })
+    const results = await Promise.all([
+      ctx.lsp.query(query('goToDefinition')),
+      ctx.lsp.query(query('goToDefinition')),
+      ctx.lsp.query(query('goToDefinition')),
+    ])
+    for (const result of results) expect(result).toMatchObject({ kind: 'locations' })
+    await ctx.fiber.dispose()
+  })
+
+  it('reads a queued query source only when its lifecycle starts', async () => {
+    const marker = join(root, 'opened.jsonl')
+    const ctx = await mount({
+      LSP_FAKE_DEF: 'null',
+      LSP_FAKE_REPLY_DELAY_MS: '300',
+      LSP_FAKE_OPEN_MARKER: marker,
+    })
+    const first = ctx.lsp.query(query('goToDefinition'))
+    await waitFor(async () => (await markerLines(marker)).length === 1)
+    const second = ctx.lsp.query(query('goToDefinition'))
+    await writeFile(join(ws, 'a.ts'), 'const changed = 2\n')
+    await Promise.all([first, second])
+    expect(await markerLines(marker)).toEqual([
+      'const x = 1\nconst y = x\n',
+      'const changed = 2\n',
+    ])
+    await ctx.fiber.dispose()
+  })
+
+  it('aborts an in-flight query when the signal fires', async () => {
+    const ctx = await mount({ LSP_FAKE_HANG: '1' })
+    const controller = new AbortController()
+    const pending = ctx.lsp.query(query('goToDefinition'), controller.signal)
+    controller.abort(new Error('caller cancelled'))
+    await expect(pending).rejects.toThrow(/cancelled/)
+    await ctx.fiber.dispose()
+  })
+
+  it('honors an already-aborted signal before any host I/O or startup', async () => {
+    const ctx = await mount({ LSP_FAKE_DEF: 'null' })
+    const controller = new AbortController()
+    controller.abort(new Error('pre-aborted'))
+    await expect(ctx.lsp.query(query('goToDefinition'), controller.signal)).rejects.toThrow(/pre-aborted/)
+    await ctx.fiber.dispose()
+  })
+
+  it('surfaces the server stderr tail in the exit error', async () => {
+    // A server that writes to stderr then exits without answering: the query rejection carries the
+    // retained stderr tail so the failure is diagnosable.
+    const ctx = await mount({}, {
+      command: process.execPath,
+      args: ['-e', 'process.stderr.write("FATAL: boom\\n"); setTimeout(()=>process.exit(1), 50)'],
+    })
+    await expect(ctx.lsp.query(query('goToDefinition'))).rejects.toThrow(/FATAL: boom/)
+    await ctx.fiber.dispose()
+  })
+
+  it('classifies a timeout deadline as the abort reason', async () => {
+    const ctx = await mount({ LSP_FAKE_HANG: '1' })
+    using d = deadline(undefined, 50, 'TEST_TIMEOUT')
+    await expect(ctx.lsp.query(query('goToDefinition'), d.signal)).rejects.toThrow(/TEST_TIMEOUT/)
+    await ctx.fiber.dispose()
+  })
+
+  it('fails the active query when the server crashes on open, and replaces it next query', async () => {
+    const ctx = await mount({ LSP_FAKE_CRASH_ON_OPEN: '1', LSP_FAKE_DEF: 'null' }, { shutdownTimeoutMs: 100, killGraceMs: 100 })
+    await expect(ctx.lsp.query(query('goToDefinition'))).rejects.toThrow()
+    // A later query starts a fresh process; still crashes, but proves the slot was replaced (no hang).
+    await expect(ctx.lsp.query(query('goToDefinition'))).rejects.toThrow()
+    await ctx.fiber.dispose()
+  })
+
+  it('evicts a pooled server that died while idle and serves the next query from a fresh one', async () => {
+    // The first query succeeds, then the server exits before the second arrives, leaving a dead
+    // instance in the pool. The next query must evict-and-replace it and still succeed, rather than
+    // failing once on the closed connection first.
+    const ctx = await mount({ LSP_FAKE_EXIT_AFTER_REPLY: '1', LSP_FAKE_DEF: JSON.stringify(locationJson(0)) })
+    expect(await ctx.lsp.query(query('goToDefinition'))).toMatchObject({ kind: 'locations' })
+    // Wait past the fixture's post-reply exit so the pooled instance is observably dead.
+    await new Promise(resolve => setTimeout(resolve, 60))
+    expect(await ctx.lsp.query(query('goToDefinition'))).toMatchObject({ kind: 'locations' })
+    await ctx.fiber.dispose()
+  })
+
+  it('does not spawn a server when the signal aborts during source read', async () => {
+    // Abort right after issuing the query: the abort lands while canonicalizeWorkspace/readHostSource
+    // are awaited, so the pre-spawn recheck must reject without ever creating a pooled instance.
+    const ctx = await mount({ LSP_FAKE_DEF: 'null' })
+    const controller = new AbortController()
+    const pending = ctx.lsp.query(query('goToDefinition'), controller.signal)
+    controller.abort(new Error('mid-read cancel'))
+    await expect(pending).rejects.toThrow(/mid-read cancel/)
+    // A subsequent live query still works, proving no half-created instance poisoned the pool.
+    expect(await ctx.lsp.query(query('goToDefinition'))).toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: ws })
+    await ctx.fiber.dispose()
+  })
+
+  it('runs distinct workspaces in parallel instances', async () => {
+    const ws2 = join(root, 'ws2')
+    await mkdir(ws2)
+    await writeFile(join(ws2, 'a.ts'), 'const z = 2\n')
+    const ctx = await mount({ LSP_FAKE_DEF: JSON.stringify(locationJson(0)) })
+    const [r1, r2] = await Promise.all([
+      ctx.lsp.query({ ...query('goToDefinition'), workspaceRoot: ws }),
+      ctx.lsp.query({ ...query('goToDefinition'), workspaceRoot: ws2 }),
+    ])
+    expect(r1).toMatchObject({ kind: 'locations' })
+    expect(r2).toMatchObject({ kind: 'locations' })
+    await ctx.fiber.dispose()
+  })
+
+  it('disposes cleanly, terminating a server that ignores shutdown', async () => {
+    const ctx = await mount({ LSP_FAKE_NO_SHUTDOWN: '1', LSP_FAKE_DEF: 'null' }, { killGraceMs: 100, shutdownTimeoutMs: 100 })
+    await ctx.lsp.query(query('goToDefinition'))
+    await expect(ctx.fiber.dispose()).resolves.toBeUndefined()
+  })
+
+  it('rejects at load when the command is not found', async () => {
+    const ctx = new Context()
+    await ctx.plugin(Lsp)
+    await expect(ctx.plugin(LspLocal, {
+      servers: {
+        missing: {
+          command: 'definitely-not-a-real-lsp-binary-xyz',
+          args: [],
+          extensionToLanguage: { '.ts': 'typescript' },
+        },
+      },
+    })).rejects.toThrow(/was not found on PATH/)
+    await ctx.fiber.dispose()
+  })
+})
+
+/** Read the fixture's JSON-lines didOpen marker, returning no entries before it exists. */
+async function markerLines(path: string): Promise<string[]> {
+  try {
+    const text = await readFile(path, 'utf8')
+    return text.trim().split('\n').filter(Boolean).map(line => JSON.parse(line) as string)
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []
+    throw error
+  }
+}
+
+/** Poll an asynchronous condition until it succeeds or the test-local deadline expires. */
+async function waitFor(condition: () => Promise<boolean>, timeoutMs = 3000): Promise<void> {
+  const started = Date.now()
+  while (!await condition()) {
+    if (Date.now() - started > timeoutMs) throw new Error('waitFor timed out')
+    await new Promise<void>(resolve => setTimeout(resolve, 10))
+  }
+}

packages/lsp/lsp-local/tests/provider.spec.ts

@@ -0,0 +1,185 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { chmod, mkdtemp, mkdir, rm, writeFile, realpath } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Context } from 'cordis'
+import Lsp, { type LspQueryRequest } from '@deepseek-ai/dsh-lsp'
+import * as LspLocal from '@deepseek-ai/dsh-lsp-local'
+import type { Config, LspLocalServerConfig } from '@deepseek-ai/dsh-lsp-local'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
+
+let root: string
+let ws: string
+
+beforeEach(async () => {
+  root = await realpath(await mkdtemp(join(tmpdir(), 'lsp-prov-')))
+  ws = join(root, 'ws')
+  await mkdir(ws)
+  await writeFile(join(ws, 'a.ts'), 'const x = 1\n')
+})
+
+afterEach(async () => {
+  await rm(root, { recursive: true, force: true })
+})
+
+function query(): LspQueryRequest {
+  return { operation: 'goToDefinition', filePath: 'a.ts', position: { line: 0, character: 0 }, workspaceRoot: ws }
+}
+
+/** Wrap one server entry in the plugin's named server table. */
+function config(providerId: string, server: LspLocalServerConfig): Config {
+  return { servers: { [providerId]: server } }
+}
+
+describe('lsp-local provider resolution', () => {
+  it('resolves a bare command on the child PATH and registers the provider', async () => {
+    // A tiny executable script placed on a custom PATH dir: the load-time resolver must find it.
+    const bin = join(root, 'bin')
+    await mkdir(bin)
+    const exe = join(bin, 'fake-lsp')
+    await writeFile(exe, '#!/bin/sh\nexit 0\n')
+    await chmod(exe, 0o755)
+
+    const ctx = new Context()
+    await ctx.plugin(Lsp)
+    await expect(ctx.plugin(LspLocal, config('onpath', {
+      command: 'fake-lsp',
+      args: [],
+      env: { PATH: bin },
+      extensionToLanguage: { '.ts': 'typescript' },
+    }))).resolves.toBeDefined()
+    await ctx.fiber.dispose()
+  })
+
+  it('skips empty PATH segments and fails when the command is absent', async () => {
+    const ctx = new Context()
+    await ctx.plugin(Lsp)
+    await expect(ctx.plugin(LspLocal, config('nope', {
+      command: 'fake-lsp',
+      args: [],
+      env: { PATH: `::${join(root, 'empty')}` },
+      extensionToLanguage: { '.ts': 'typescript' },
+    }))).rejects.toThrow(/was not found on PATH/)
+    await ctx.fiber.dispose()
+  })
+
+  it('rejects a query after the provider is disposed', async () => {
+    // Use a server that never emits results and dispose the plugin, then confirm queries are refused.
+    const ctx = new Context()
+    await ctx.plugin(Lsp)
+    // Grab the provider instance by registering, then dispose the whole plugin fiber.
+    const lsp = ctx.lsp
+    const fiber = await ctx.plugin(LspLocal, config('disp', {
+      command: process.execPath,
+      args: ['-e', 'setInterval(()=>{},1000)'],
+      extensionToLanguage: { '.ts': 'typescript' },
+    }))
+    await fiber.dispose()
+    // After disposal the provider unregistered from the seam, so selection fails as unavailable.
+    await expect(lsp.query(query())).rejects.toThrow(expect.objectContaining({ code: 'LSP_UNAVAILABLE' }))
+    await ctx.fiber.dispose()
+  })
+
+  it('rejects a nonpositive teardown budget at load', async () => {
+    const ctx = new Context()
+    await ctx.plugin(Lsp)
+    await expect(ctx.plugin(LspLocal, config('bad-budget', {
+      command: process.execPath,
+      args: ['-e', ''],
+      extensionToLanguage: { '.ts': 'typescript' },
+      killGraceMs: 0,
+    }))).rejects.toThrow(/servers\.bad-budget\.killGraceMs must be a positive integer/)
+    await ctx.fiber.dispose()
+  })
+
+  it('rejects a nonpositive byte cap at load', async () => {
+    const ctx = new Context()
+    await ctx.plugin(Lsp)
+    await expect(ctx.plugin(LspLocal, config('bad-cap', {
+      command: process.execPath,
+      args: ['-e', ''],
+      extensionToLanguage: { '.ts': 'typescript' },
+      maxDocumentBytes: 0,
+    }))).rejects.toThrow(/servers\.bad-cap\.maxDocumentBytes must be a positive integer/)
+    await ctx.fiber.dispose()
+  })
+
+  it.each(['shutdownTimeoutMs', 'killGraceMs'] as const)('rejects %s above Node timer range at load', async (name) => {
+    const ctx = new Context()
+    await ctx.plugin(Lsp)
+    await expect(ctx.plugin(LspLocal, config('bad-timer', {
+      command: process.execPath,
+      args: ['-e', ''],
+      extensionToLanguage: { '.ts': 'typescript' },
+      [name]: MAX_TIMER_DELAY_MS + 1,
+    }))).rejects.toThrow(new RegExp(`servers\\.bad-timer\\.${name}`))
+    await ctx.fiber.dispose()
+  })
+
+  it('rejects an absolute command that is not executable at load', async () => {
+    const notExe = join(root, 'not-exe.txt')
+    await writeFile(notExe, 'plain text, not executable')
+    const ctx = new Context()
+    await ctx.plugin(Lsp)
+    await expect(ctx.plugin(LspLocal, config('abs-bad', {
+      command: notExe,
+      args: [],
+      extensionToLanguage: { '.ts': 'typescript' },
+    }))).rejects.toThrow(/is not an executable file/)
+    await ctx.fiber.dispose()
+  })
+
+  it('rejects an executable directory as a command at load', async () => {
+    const ctx = new Context()
+    await ctx.plugin(Lsp)
+    await expect(ctx.plugin(LspLocal, config('abs-directory', {
+      command: ws,
+      args: [],
+      extensionToLanguage: { '.ts': 'typescript' },
+    }))).rejects.toThrow(/is not an executable file/)
+    await ctx.fiber.dispose()
+  })
+
+  it('rejects an empty server table at load', async () => {
+    const ctx = new Context()
+    await ctx.plugin(Lsp)
+    await expect(ctx.plugin(LspLocal, { servers: {} })).rejects.toThrow(/servers must contain at least one server/)
+    await ctx.fiber.dispose()
+  })
+
+  it('rejects an empty server id at load', async () => {
+    const ctx = new Context()
+    await ctx.plugin(Lsp)
+    await expect(ctx.plugin(LspLocal, config('', {
+      command: process.execPath,
+      extensionToLanguage: { '.ts': 'typescript' },
+    }))).rejects.toThrow(/server ids must be non-empty strings/)
+    await ctx.fiber.dispose()
+  })
+
+  it('resolves every executable before publishing any provider', async () => {
+    const ctx = new Context()
+    await ctx.plugin(Lsp)
+    await expect(ctx.plugin(LspLocal, {
+      servers: {
+        valid: { command: process.execPath, extensionToLanguage: { '.ts': 'typescript' } },
+        missing: { command: 'definitely-not-a-real-lsp-binary-xyz', extensionToLanguage: { '.py': 'python' } },
+      },
+    })).rejects.toThrow(/was not found on PATH/)
+    await expect(ctx.lsp.query(query())).rejects.toThrow(expect.objectContaining({ code: 'LSP_UNAVAILABLE' }))
+    await ctx.fiber.dispose()
+  })
+
+  it('rolls back earlier registrations when a later server conflicts', async () => {
+    const ctx = new Context()
+    await ctx.plugin(Lsp)
+    await expect(ctx.plugin(LspLocal, {
+      servers: {
+        first: { command: process.execPath, extensionToLanguage: { '.ts': 'typescript' } },
+        second: { command: process.execPath, extensionToLanguage: { '.ts': 'typescript' } },
+      },
+    })).rejects.toThrow(expect.objectContaining({ code: 'LSP_CONFLICT' }))
+    await expect(ctx.lsp.query(query())).rejects.toThrow(expect.objectContaining({ code: 'LSP_UNAVAILABLE' }))
+    await ctx.fiber.dispose()
+  })
+})

packages/lsp/lsp-local/tests/translate.spec.ts

@@ -0,0 +1,173 @@
+import { describe, expect, it } from 'vitest'
+import {
+  negotiatePositionEncoding,
+  normalizeHover,
+  normalizeLocations,
+  requestMethod,
+  supportsOperation,
+  supportsTransientOpen,
+} from '@deepseek-ai/dsh-lsp-local'
+import type { WireServerCapabilities } from '@deepseek-ai/dsh-lsp-local/src/protocol.ts'
+
+const RANGE = { start: { line: 1, character: 2 }, end: { line: 1, character: 5 } }
+
+describe('requestMethod', () => {
+  it('maps each operation to its textDocument request', () => {
+    expect(requestMethod('goToDefinition')).toBe('textDocument/definition')
+    expect(requestMethod('findReferences')).toBe('textDocument/references')
+    expect(requestMethod('goToImplementation')).toBe('textDocument/implementation')
+    expect(requestMethod('hover')).toBe('textDocument/hover')
+  })
+})
+
+describe('supportsOperation', () => {
+  it('reads the provider slot for each operation (boolean and options forms)', () => {
+    const caps: WireServerCapabilities = {
+      definitionProvider: true,
+      referencesProvider: { workDoneProgress: true },
+      implementationProvider: false,
+    }
+    expect(supportsOperation(caps, 'goToDefinition')).toBe(true)
+    expect(supportsOperation(caps, 'findReferences')).toBe(true)
+    expect(supportsOperation(caps, 'goToImplementation')).toBe(false)
+    expect(supportsOperation(caps, 'hover')).toBe(false)
+  })
+})
+
+describe('supportsTransientOpen', () => {
+  it('accepts legacy Full and Incremental enums, rejects None and absent', () => {
+    expect(supportsTransientOpen(1)).toBe(true)
+    expect(supportsTransientOpen(2)).toBe(true)
+    expect(supportsTransientOpen(0)).toBe(false)
+    expect(supportsTransientOpen(undefined)).toBe(false)
+  })
+
+  it('accepts options with openClose:true and rejects openClose:false', () => {
+    expect(supportsTransientOpen({ openClose: true })).toBe(true)
+    expect(supportsTransientOpen({ openClose: false, change: 2 })).toBe(false)
+  })
+
+  it('requires an explicit openClose for the options form (no change-enum fallback)', () => {
+    expect(supportsTransientOpen({ change: 1 })).toBe(false)
+    expect(supportsTransientOpen({ change: 2 })).toBe(false)
+    expect(supportsTransientOpen({})).toBe(false)
+  })
+})
+
+describe('negotiatePositionEncoding', () => {
+  it('defaults an omitted encoding to utf-16', () => {
+    expect(negotiatePositionEncoding(undefined)).toBe('utf-16')
+    expect(negotiatePositionEncoding('utf-16')).toBe('utf-16')
+  })
+
+  it('rejects any other encoding', () => {
+    expect(() => negotiatePositionEncoding('utf-8')).toThrow(/unsupported position encoding/)
+  })
+})
+
+describe('normalizeLocations', () => {
+  it('returns empty only for the protocol no-result value null', () => {
+    expect(normalizeLocations(null)).toEqual([])
+    expect(() => normalizeLocations(undefined)).toThrow(expect.objectContaining({ code: 'LSP_MALFORMED_RESPONSE' }))
+  })
+
+  it('maps a single Location', () => {
+    expect(normalizeLocations({ uri: 'file:///a', range: RANGE })).toEqual([{ uri: 'file:///a', range: RANGE }])
+  })
+
+  it('maps an array of Locations', () => {
+    const result = normalizeLocations([{ uri: 'file:///a', range: RANGE }, { uri: 'file:///b', range: RANGE }])
+    expect(result.map(l => l.uri)).toEqual(['file:///a', 'file:///b'])
+  })
+
+  it('maps a LocationLink from targetUri + targetSelectionRange', () => {
+    const link = { targetUri: 'file:///c', targetSelectionRange: RANGE, targetRange: RANGE }
+    expect(normalizeLocations([link])).toEqual([{ uri: 'file:///c', range: RANGE }])
+  })
+
+  it('rejects a non-object entry', () => {
+    expect(() => normalizeLocations([42])).toThrow(/non-object/)
+  })
+
+  it('rejects an entry that is neither a Location nor a LocationLink', () => {
+    expect(() => normalizeLocations([{ nope: true }])).toThrow(/neither a Location nor a LocationLink/)
+  })
+
+  it('rejects a Location whose range is not an object', () => {
+    expect(() => normalizeLocations([{ uri: 'file:///a', range: 'nope' }])).toThrow(/neither a Location/)
+  })
+
+  it('rejects a Location whose range positions are malformed', () => {
+    expect(() => normalizeLocations([{ uri: 'file:///a', range: { start: null, end: null } }])).toThrow(/neither a Location/)
+  })
+
+  it('rejects negative and fractional position coordinates', () => {
+    expect(() => normalizeLocations([{ uri: 'file:///a', range: { start: { line: -1, character: 0 }, end: RANGE.end } }]))
+      .toThrow(expect.objectContaining({ code: 'LSP_MALFORMED_RESPONSE' }))
+    expect(() => normalizeLocations([{ uri: 'file:///a', range: { start: RANGE.start, end: { line: 1.5, character: 5 } } }]))
+      .toThrow(expect.objectContaining({ code: 'LSP_MALFORMED_RESPONSE' }))
+  })
+})
+
+describe('normalizeHover', () => {
+  it('returns null for null', () => {
+    expect(normalizeHover(null)).toBeNull()
+  })
+
+  it('rejects a missing hover result', () => {
+    expect(() => normalizeHover(undefined)).toThrow(expect.objectContaining({ code: 'LSP_MALFORMED_RESPONSE' }))
+  })
+
+  it('reads MarkupContent value and keeps a range', () => {
+    expect(normalizeHover({ contents: { kind: 'markdown', value: '# H' }, range: RANGE }))
+      .toEqual({ contents: '# H', range: RANGE })
+  })
+
+  it('keeps a bare string MarkedString verbatim', () => {
+    expect(normalizeHover({ contents: 'plain text' })).toEqual({ contents: 'plain text' })
+  })
+
+  it('renders a language-tagged MarkedString object as a fenced code block', () => {
+    expect(normalizeHover({ contents: { language: 'ts', value: 'const x = 1' } }))
+      .toEqual({ contents: '```ts\nconst x = 1\n```' })
+  })
+
+  it('joins a MarkedString array with one blank line', () => {
+    expect(normalizeHover({ contents: ['a', { language: 'ts', value: 'b' }] }))
+      .toEqual({ contents: 'a\n\n```ts\nb\n```' })
+  })
+
+  it('drops an empty-contents hover to null', () => {
+    expect(normalizeHover({ contents: { kind: 'plaintext', value: '' } })).toBeNull()
+  })
+
+  it('rejects a MarkupContent with a non-string value', () => {
+    expect(() => normalizeHover({ contents: { kind: 'markdown', value: 42 } }))
+      .toThrow(expect.objectContaining({ code: 'LSP_MALFORMED_RESPONSE' }))
+  })
+
+  it('rejects a non-object payload', () => {
+    expect(() => normalizeHover(42)).toThrow(/was not an object/)
+  })
+
+  it('rejects malformed contents', () => {
+    expect(() => normalizeHover({ contents: { weird: true } })).toThrow(/were not MarkupContent/)
+    expect(() => normalizeHover({ contents: 42 })).toThrow(/were not MarkupContent/)
+  })
+
+  it('rejects a malformed MarkedString array member', () => {
+    expect(() => normalizeHover({ contents: ['ok', { language: 'ts', value: 42 }] }))
+      .toThrow(expect.objectContaining({ code: 'LSP_MALFORMED_RESPONSE' }))
+    expect(() => normalizeHover({ contents: [null] }))
+      .toThrow(expect.objectContaining({ code: 'LSP_MALFORMED_RESPONSE' }))
+  })
+
+  it('rejects a hover with no contents field', () => {
+    expect(() => normalizeHover({ range: RANGE })).toThrow(/no contents/)
+  })
+
+  it('rejects a malformed range instead of silently dropping it', () => {
+    expect(() => normalizeHover({ contents: 'x', range: { start: { line: 1 } } }))
+      .toThrow(expect.objectContaining({ code: 'LSP_MALFORMED_RESPONSE' }))
+  })
+})

packages/lsp/lsp-local/tests/typescript-server.e2e.ts

@@ -0,0 +1,114 @@
+/**
+ * Keyless real-server e2e: drives the real `typescript-language-server` through the full
+ * `ctx.lsp` → `dsh-lsp-local` stack over the base protocol, exercising all four operations. No API
+ * key needed — the server is a local dev dependency. This establishes one compatibility floor
+ * (TypeScript), not a cross-language claim.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { mkdtemp, mkdir, rm, writeFile, realpath } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Context } from 'cordis'
+import Lsp, { type LspQueryRequest, type LspQueryResult } from '@deepseek-ai/dsh-lsp'
+import * as LspLocal from '@deepseek-ai/dsh-lsp-local'
+
+// The server binary is a dev dependency of this package; resolve its pnpm-hoisted .bin path.
+const serverBin = join(
+  new URL('..', import.meta.url).pathname,
+  'node_modules',
+  '.bin',
+  'typescript-language-server',
+)
+
+let root: string
+let ws: string
+let ctx: Context
+
+beforeAll(async () => {
+  root = await realpath(await mkdtemp(join(tmpdir(), 'lsp-ts-e2e-')))
+  ws = join(root, 'proj')
+  await mkdir(ws)
+  await writeFile(join(ws, 'tsconfig.json'), JSON.stringify({ compilerOptions: { strict: true, module: 'nodenext' } }))
+  // A small program with a definition, a reference, an interface + implementation, and a typed value.
+  await writeFile(join(ws, 'shapes.ts'), [
+    'export interface Shape {',
+    '  area(): number',
+    '}',
+    '',
+    'export class Circle implements Shape {',
+    '  constructor(private r: number) {}',
+    '  area(): number { return Math.PI * this.r * this.r }',
+    '}',
+    '',
+    'export function describe(s: Shape): string {',
+    '  return `area=${s.area()}`',
+    '}',
+    '',
+    'const c = new Circle(2)',
+    'export const text = describe(c)',
+    '',
+  ].join('\n'))
+
+  ctx = new Context()
+  await ctx.plugin(Lsp)
+  await ctx.plugin(LspLocal, {
+    servers: {
+      typescript: {
+        command: serverBin,
+        args: ['--stdio'],
+        extensionToLanguage: { '.ts': 'typescript', '.tsx': 'typescriptreact' },
+      },
+    },
+  })
+}, 60_000)
+
+afterAll(async () => {
+  if (ctx) await ctx.fiber.dispose()
+  if (root) await rm(root, { recursive: true, force: true })
+})
+
+/** One-based helper mirroring the model contract, converted to the seam's zero-based position. */
+function at(operation: LspQueryRequest['operation'], line1: number, char1: number, filePath = 'shapes.ts'): LspQueryRequest {
+  return { operation, filePath, position: { line: line1 - 1, character: char1 - 1 }, workspaceRoot: ws }
+}
+
+function locations(result: LspQueryResult): readonly { uri: string }[] {
+  if (result.kind !== 'locations') throw new Error(`expected locations, got ${result.kind}`)
+  return result.locations
+}
+
+describe('real typescript-language-server', () => {
+  it('resolves the definition of a call site to its declaration', async () => {
+    // `export const text = describe(c)` (line 15): `describe` begins at column 21.
+    const result = await ctx.lsp.query(at('goToDefinition', 15, 22))
+    const locs = locations(result)
+    expect(locs.length).toBeGreaterThanOrEqual(1)
+    expect(locs.some(l => l.uri.endsWith('shapes.ts'))).toBe(true)
+  }, 60_000)
+
+  it('finds references to a symbol including its declaration', async () => {
+    // References to `describe` from its declaration (line 10, col 17).
+    const result = await ctx.lsp.query(at('findReferences', 10, 17))
+    const locs = locations(result)
+    // At least the declaration plus the call site.
+    expect(locs.length).toBeGreaterThanOrEqual(2)
+  }, 60_000)
+
+  it('resolves implementations of an interface', async () => {
+    // Implementations of `Shape` (line 1, col 18) → Circle.
+    const result = await ctx.lsp.query(at('goToImplementation', 1, 18))
+    const locs = locations(result)
+    expect(locs.length).toBeGreaterThanOrEqual(1)
+  }, 60_000)
+
+  it('returns hover information for a typed symbol', async () => {
+    // Hover on `Circle` in `new Circle(2)` (line 14, col 15).
+    const result = await ctx.lsp.query(at('hover', 14, 15))
+    expect(result.kind).toBe('hover')
+    if (result.kind === 'hover') {
+      expect(result.hover).not.toBeNull()
+      expect(result.hover?.contents).toContain('Circle')
+    }
+  }, 60_000)
+})

packages/lsp/lsp-local/tsconfig.json

@@ -0,0 +1,33 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../util/brand"
+    },
+    {
+      "path": "../../util/timeout"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../lsp"
+    }
+  ]
+}

packages/lsp/lsp/README.md

@@ -0,0 +1,42 @@
+# @deepseek-ai/dsh-lsp
+
+The **LSP capability seam**: an abstract `LspService` (`ctx.lsp`) defining WHAT semantic code navigation the harness has — go to definition, find references, find implementations, hover — over language-server providers, without binding the model contract to local subprocesses.
+
+This package is the interface third of the LSP capability:
+
+| Package | Role |
+|---|---|
+| `@deepseek-ai/dsh-lsp` (this) | the interface: the service, provider registry keyed by branded id + extension mapping, per-query selection, request/result vocabulary, the `LspError` taxonomy |
+| `@deepseek-ai/dsh-lsp-local` | a generic local backend that registers configured stdio language-server providers |
+| `@deepseek-ai/dsh-tool-lsp` | the model-facing `lsp` tool over `ctx.lsp` |
+
+The seam exposes exactly four semantic operations — `goToDefinition`, `findReferences`, `goToImplementation`, `hover` — and no generic JSON-RPC escape hatch, so no protocol payload or unreviewed command/mutation reaches a provider through `ctx.lsp`.
+
+## Service API (`ctx.lsp`)
+
+| Member | Semantics |
+|---|---|
+| `registerProvider(provider)` | Register a backend, atomically reserving its branded `id` and every normalized file extension. Any invalid input or conflict publishes nothing and throws `LspError` (`LSP_INVALID_PROVIDER` / `LSP_CONFLICT`). Returns a disposer releasing all reservations. Disposed with the calling fiber. |
+| `query(request, signal?)` | Select the provider by the file's final extension, derive the `languageId` from that provider's mapping, and run one query. No match throws `LspError` `LSP_UNAVAILABLE`. |
+
+Selection is per query and order-independent: a provider owns a set of extensions exclusively, so registration and HMR order never change routing. Extension keys normalize to lowercase, leading-dot form; the `languageId` only synchronizes the transient document, never participates in selection. The first version has no glob, language-id, or explicit route selector.
+
+Providers register **capabilities**, not tools. `dsh-tool-lsp` is the only owner of the model-facing name, description, prompt guidance, schema, and presentation.
+
+## Vocabulary
+
+`LspQueryRequest` (`operation`, `filePath`, `position`, `workspaceRoot`) — every field required, so no field needs implementation defaulting and there is no `resolve()` step. Positions and ranges are zero-based UTF-16, matching the protocol; the tool owns the one-based cursor convention. `findReferences` always includes declarations — providers enforce this internally, so callers get no flag. `LspQueryResult` is a CLOSED discriminated union: `{ kind: 'locations'; locations; resolvedWorkspaceRoot }` for navigation, `{ kind: 'hover'; hover }` for hover (content or `null`) — consumers `switch` to exhaustiveness so a new arm breaks compilation until handled. `resolvedWorkspaceRoot` is the provider's canonical form of the request's `workspaceRoot` and the root its `file:` URIs are relative to; a caller relativizing display paths uses it, not the (possibly symlinked) request root. See `src/types.ts` for the full contracts and `src/index.ts` for the `LspError` codes, including `LSP_DISPOSED` and `LSP_MALFORMED_RESPONSE`.
+
+## Model Experience
+
+Indirectly, through `dsh-tool-lsp`, which owns the model-facing `lsp` schema, prompt, and rendered results while this registry contributes no prompt or schema itself.
+
+#### KV Cache effect
+
+No direct invalidation; `dsh-tool-lsp` owns request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **Exclusive extension ownership within one runtime** — two providers cannot both claim `.ts`, even with different language ids; overlaps fail registration. The intended extension is a deployment-configured selector above registrations, which can relax exclusive reservation without adding provider choice to model input ([seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)).
+- **Four operations only** — symbols and call hierarchy are deferred (they need different schemas); diagnostics need separate freshness/accumulation rules; mutations (rename, code actions, formatting) require separate tools with preview, permission, and write-policy integration.
+- **No observation surface** — availability is observed only by running `query()` and routing the thrown `LspError` codes; there is no provider-change event or capability-status query.

packages/lsp/lsp/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@deepseek-ai/dsh-lsp",
+  "description": "Abstract LSP capability seam (ctx.lsp) for the DeepSeek Harness — language-server provider registry keyed by branded id and extension mapping, order-independent per-query selection, normalized definition/references/implementation/hover requests and results, and the LspError taxonomy",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-brand": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}

packages/lsp/lsp/src/brand.ts

@@ -0,0 +1,21 @@
+/**
+ * dsh-lsp's owned branded id: {@link LspProviderId}, the opaque identity a provider reserves on
+ * `ctx.lsp`. The `Branded<B>` primitive lives in `@deepseek-ai/dsh-brand`; keeping the type and its
+ * factory together here lets `index.ts` re-export both under one name.
+ * @module @deepseek-ai/dsh-lsp/brand
+ */
+
+import type { Branded } from '@deepseek-ai/dsh-brand'
+
+/** Opaque provider identity, reserved atomically with its extension mappings at registration. */
+export type LspProviderId = Branded<'LspProviderId'>
+
+/**
+ * Brand a string as an {@link LspProviderId}. No validation — the registry rejects an empty id at
+ * registration.
+ * @param id - the provider's stable identifier.
+ * @returns the same string, branded.
+ */
+export function LspProviderId(id: string): LspProviderId {
+  return id as LspProviderId
+}

packages/lsp/lsp/src/index.ts

@@ -0,0 +1,158 @@
+/**
+ * The LSP capability seam (`ctx.lsp`): a language-server provider registry and per-query,
+ * order-independent selection over normalized goToDefinition/findReferences/goToImplementation/
+ * hover queries.
+ *
+ * A provider reserves a branded id and an exclusive set of file extensions atomically:
+ * {@link Lsp.registerProvider} validates and conflict-checks everything before mutating, so an
+ * invalid or conflicting registration publishes nothing, and its disposer releases every
+ * reservation together. Selection routes a query by the file's final extension; it never depends on
+ * registration order. The seam exposes exactly the four operations and no JSON-RPC escape hatch.
+ * @module @deepseek-ai/dsh-lsp
+ */
+
+import { Context, Service } from 'cordis'
+import { HarnessError } from '@deepseek-ai/dsh-llm'
+import type { LspProviderId } from './brand.ts'
+import type {
+  LspProvider,
+  LspQueryRequest,
+  LspQueryResult,
+  LspService,
+} from './types.ts'
+
+export { LspProviderId } from './brand.ts'
+export type {
+  LspHover,
+  LspLocation,
+  LspOperation,
+  LspPosition,
+  LspProvider,
+  LspProviderQuery,
+  LspQueryRequest,
+  LspQueryResult,
+  LspRange,
+  LspService,
+} from './types.ts'
+
+declare module 'cordis' {
+  interface Context {
+    lsp: LspService
+  }
+}
+
+/**
+ * Structured LSP failure. Extends {@link HarnessError} with a stable `code`
+ * (`LSP_INVALID_PROVIDER`, `LSP_CONFLICT`, `LSP_UNAVAILABLE`, `LSP_DISPOSED`,
+ * `LSP_UNSUPPORTED_OPERATION`, `LSP_MALFORMED_RESPONSE`, …) that callers route on instead of
+ * parsing `message`.
+ */
+export class LspError extends HarnessError {}
+
+/**
+ * Extract a file's final extension as a normalized, lowercase, leading-dot key (e.g. `Foo.TS` →
+ * `.ts`, `foo.d.ts` → `.ts`). Returns `''` for a name with no extension or a leading-dot dotfile
+ * (`.bashrc`), which no route ever matches. Splits on both `/` and `\` so a caller's path separator
+ * does not change the result.
+ * @param filePath - the source path to inspect.
+ * @returns the normalized extension, or `''` when there is none.
+ */
+export function finalExtension(filePath: string): string {
+  const lastSlash = Math.max(filePath.lastIndexOf('/'), filePath.lastIndexOf('\\'))
+  const base = lastSlash >= 0 ? filePath.slice(lastSlash + 1) : filePath
+  const dot = base.lastIndexOf('.')
+  // dot <= 0 covers both "no dot" (-1) and a leading-dot dotfile (0): neither has an extension.
+  if (dot <= 0) return ''
+  return base.slice(dot).toLowerCase()
+}
+
+/** A well-formed normalized extension: a dot followed by one or more non-dot, non-separator chars. */
+const EXTENSION_PATTERN = /^\.[^./\\]+$/
+
+/** One selection route: the provider to run plus the language id to synchronize the document with. */
+interface Route {
+  readonly provider: LspProvider
+  readonly languageId: string
+}
+
+/**
+ * `ctx.lsp`. Holds the id reservations and the extension→route table; both are populated and cleared
+ * together per provider so a route always has a live provider.
+ */
+export class Lsp extends Service implements LspService {
+  private readonly providerIds = new Set<LspProviderId>()
+  private readonly routes = new Map<string, Route>()
+
+  constructor(ctx: Context) {
+    super(ctx, 'lsp')
+  }
+
+  registerProvider(provider: LspProvider): () => void {
+    // Validate and conflict-check everything BEFORE any mutation: an invalid or conflicting
+    // registration must publish nothing (fail-loud, all-or-nothing).
+    const id = provider.id
+    if (id.trim() === '') {
+      throw new LspError('an LSP provider id must be a non-empty string', 'LSP_INVALID_PROVIDER')
+    }
+    if (this.providerIds.has(id)) {
+      throw new LspError(`an LSP provider with id "${id}" is already registered`, 'LSP_CONFLICT')
+    }
+
+    const entries = Object.entries(provider.extensionToLanguage)
+    if (entries.length === 0) {
+      throw new LspError(`LSP provider "${id}" registers no file extensions`, 'LSP_INVALID_PROVIDER')
+    }
+
+    // Normalize into this provider's route set, catching intra-provider duplicates (e.g. `.TS` and
+    // `.ts`) before checking cross-provider conflicts.
+    const pending = new Map<string, Route>()
+    for (const [rawExt, languageId] of entries) {
+      const ext = normalizeExtension(rawExt)
+      if (!EXTENSION_PATTERN.test(ext)) {
+        throw new LspError(`LSP provider "${id}" maps an invalid extension "${rawExt}"`, 'LSP_INVALID_PROVIDER')
+      }
+      if (languageId.trim() === '') {
+        throw new LspError(`LSP provider "${id}" maps extension "${ext}" to an empty language id`, 'LSP_INVALID_PROVIDER')
+      }
+      if (pending.has(ext)) {
+        throw new LspError(`LSP provider "${id}" maps extension "${ext}" more than once`, 'LSP_INVALID_PROVIDER')
+      }
+      pending.set(ext, { provider, languageId })
+    }
+    for (const ext of pending.keys()) {
+      if (this.routes.has(ext)) {
+        throw new LspError(`extension "${ext}" is already handled by another LSP provider`, 'LSP_CONFLICT')
+      }
+    }
+
+    // All checks passed: reserve id and every extension in one lifecycle controller so disposal
+    // releases them together.
+    const dispose = this.ctx.effect(function* (this: Lsp) {
+      this.providerIds.add(id)
+      for (const [ext, route] of pending) this.routes.set(ext, route)
+      yield () => {
+        this.providerIds.delete(id)
+        for (const ext of pending.keys()) this.routes.delete(ext)
+      }
+    }.bind(this), 'lsp.registerProvider()')
+    // ctx.effect's disposer returns Promise<void>; our disposer API is synchronous
+    // fire-and-forget — discard the (always-resolved) promise.
+    return () => void dispose()
+  }
+
+  async query(request: LspQueryRequest, signal?: AbortSignal): Promise<LspQueryResult> {
+    const route = this.routes.get(finalExtension(request.filePath))
+    if (route === undefined) {
+      throw new LspError(`no LSP provider handles "${request.filePath}"`, 'LSP_UNAVAILABLE')
+    }
+    return route.provider.query({ ...request, languageId: route.languageId }, signal)
+  }
+}
+
+/** Lowercase an extension and ensure it carries a leading dot; `EXTENSION_PATTERN` rejects the rest. */
+function normalizeExtension(ext: string): string {
+  const lower = ext.toLowerCase()
+  return lower.startsWith('.') ? lower : `.${lower}`
+}
+
+export default Lsp

packages/lsp/lsp/src/types.ts

@@ -0,0 +1,130 @@
+/**
+ * LSP seam vocabulary: the normalized request, provider, and result contracts. Types only — the
+ * {@link LspError} taxonomy and the {@link LspProviderId} brand factory are runtime and live in
+ * `index.ts`. Positions and ranges are zero-based UTF-16, matching the protocol; the model-facing
+ * tool owns the one-based cursor convention. The seam exposes no protocol types, process or document
+ * controls, or generic JSON-RPC escape hatch — only the four semantic operations.
+ * @module @deepseek-ai/dsh-lsp/types
+ */
+
+import type { LspProviderId } from './brand.ts'
+
+/**
+ * The four semantic queries the seam and model expose. A closed union: adding an operation is a
+ * compile-enforced change across the seam, providers, and the tool. Symbols and call hierarchy are
+ * deliberately deferred (they need different schemas).
+ */
+export type LspOperation = 'goToDefinition' | 'findReferences' | 'goToImplementation' | 'hover'
+
+/** A zero-based UTF-16 cursor coordinate, matching the LSP wire convention. */
+export interface LspPosition {
+  /** Zero-based line. */
+  readonly line: number
+  /** Zero-based UTF-16 code-unit offset within the line. */
+  readonly character: number
+}
+
+/** A zero-based UTF-16 half-open range `[start, end)`. */
+export interface LspRange {
+  readonly start: LspPosition
+  readonly end: LspPosition
+}
+
+/**
+ * A caller's normalized query. Every field is required: `workspaceRoot` is caller-supplied,
+ * `languageId` comes from the provider registration (not here), and consumers own timeouts and
+ * result limits — so no field needs implementation defaulting and there is no `resolve()` step.
+ */
+export interface LspQueryRequest {
+  /** Which semantic query to run. */
+  readonly operation: LspOperation
+  /** The source file to query (relative to `workspaceRoot` or absolute; the provider canonicalizes). */
+  readonly filePath: string
+  /** The zero-based UTF-16 cursor position to query at. */
+  readonly position: LspPosition
+  /** The workspace root the provider resolves against and indexes; required, never defaulted. */
+  readonly workspaceRoot: string
+}
+
+/**
+ * A request as a provider receives it: the caller's {@link LspQueryRequest} plus the `languageId`
+ * the seam derived from the provider's extension mapping. The language id only synchronizes the
+ * transient document; it does not participate in selection.
+ */
+export interface LspProviderQuery extends LspQueryRequest {
+  /** The LSP language id for `filePath`, from this provider's extension mapping. */
+  readonly languageId: string
+}
+
+/** One resolved location: a document URI and the range within it. */
+export interface LspLocation {
+  /** The target document URI (`file:` or otherwise), verbatim from the server. */
+  readonly uri: string
+  /** The range within the target document. */
+  readonly range: LspRange
+}
+
+/** Normalized hover content, or `null` for no hover at the position. */
+export interface LspHover {
+  /** The normalized hover text (markdown or plaintext, provider-joined). */
+  readonly contents: string
+  /** The range the hover applies to, when the server supplied one. */
+  readonly range?: LspRange
+}
+
+/**
+ * The closed result union. Navigation operations (`goToDefinition`, `findReferences`,
+ * `goToImplementation`) normalize to `locations`; `hover` normalizes to content or `null`.
+ * Consumers `switch` on `kind` to exhaustiveness so a new arm breaks compilation until handled.
+ *
+ * The `locations` variant carries `resolvedWorkspaceRoot`: the provider's canonical form of the
+ * request's `workspaceRoot`, and the root its `file:` location URIs are relative to. A caller that
+ * relativizes display paths MUST use this, not the request's (possibly symlinked) `workspaceRoot`;
+ * otherwise a symlinked workspace misclassifies in-workspace results as external.
+ */
+export type LspQueryResult =
+  | { readonly kind: 'locations'; readonly locations: readonly LspLocation[]; readonly resolvedWorkspaceRoot: string }
+  | { readonly kind: 'hover'; readonly hover: LspHover | null }
+
+/**
+ * A language-server backend registered on `ctx.lsp`. Each provider owns a stable {@link
+ * LspProviderId} and an extension-to-language-id map (lowercase, leading-dot keys).
+ * `findReferences` always includes declarations — the provider enforces this internally; callers
+ * get no flag.
+ */
+export interface LspProvider {
+  /** Stable provider identity, reserved atomically with the extension mappings. */
+  readonly id: LspProviderId
+  /** Lowercase leading-dot extension → LSP language id (e.g. `{ '.ts': 'typescript' }`). */
+  readonly extensionToLanguage: Readonly<Record<string, string>>
+  /**
+   * Run one query. The seam has already selected this provider and derived `languageId`.
+   * @param request - the resolved provider query (caller request + derived language id).
+   * @param signal - optional cancellation; the provider stops its own work when it aborts.
+   * @returns the normalized, closed-union result.
+   */
+  query(request: LspProviderQuery, signal?: AbortSignal): Promise<LspQueryResult>
+}
+
+/**
+ * The LSP capability seam (`ctx.lsp`). Owns provider registration/selection and normalized query
+ * execution; exposes exactly the four operations and no protocol escape hatch.
+ */
+export interface LspService {
+  /**
+   * Register a provider, atomically reserving its id and every normalized extension. Any conflict
+   * or invalid input publishes nothing and throws `LspError`; the returned disposer releases all
+   * reservations. Disposed with the calling fiber.
+   * @param provider - the backend to register.
+   * @returns a synchronous disposer releasing the id and all extension reservations.
+   */
+  registerProvider(provider: LspProvider): () => void
+  /**
+   * Select a provider by the file's extension and run one query. Selection is per-query and
+   * order-independent; no match throws `LspError` `LSP_UNAVAILABLE`.
+   * @param request - the normalized query.
+   * @param signal - optional cancellation forwarded to the selected provider.
+   * @returns the normalized, closed-union result.
+   */
+  query(request: LspQueryRequest, signal?: AbortSignal): Promise<LspQueryResult>
+}

packages/lsp/lsp/tests/lsp.spec.ts

@@ -0,0 +1,187 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import Lsp, {
+  finalExtension,
+  LspError,
+  LspProviderId,
+  type LspProvider,
+  type LspProviderQuery,
+  type LspQueryResult,
+} from '@deepseek-ai/dsh-lsp'
+
+/** A scripted provider that records the queries it receives. */
+function makeProvider(
+  id: string,
+  extensionToLanguage: Record<string, string>,
+  result: LspQueryResult = { kind: 'locations', locations: [], resolvedWorkspaceRoot: '/ws' },
+): LspProvider & { seen: LspProviderQuery[]; seenSignals: (AbortSignal | undefined)[] } {
+  const seen: LspProviderQuery[] = []
+  const seenSignals: (AbortSignal | undefined)[] = []
+  return {
+    id: LspProviderId(id),
+    extensionToLanguage,
+    seen,
+    seenSignals,
+    query(request, signal) {
+      seen.push(request)
+      seenSignals.push(signal)
+      return Promise.resolve(result)
+    },
+  }
+}
+
+/** Mount an Lsp service on a fresh root context. */
+async function mountLsp(): Promise<{ ctx: Context; lsp: Lsp }> {
+  const ctx = new Context()
+  await ctx.plugin(Lsp)
+  return { ctx, lsp: ctx.lsp as Lsp }
+}
+
+const hover: LspQueryResult = { kind: 'hover', hover: { contents: 'x' } }
+
+function query(filePath: string, operation: LspProviderQuery['operation'] = 'goToDefinition'): Parameters<Lsp['query']>[0] {
+  return { operation, filePath, position: { line: 0, character: 0 }, workspaceRoot: '/ws' }
+}
+
+describe('finalExtension', () => {
+  it('lowercases and keeps only the final extension', () => {
+    expect(finalExtension('src/Foo.TS')).toBe('.ts')
+    expect(finalExtension('a/b/foo.d.ts')).toBe('.ts')
+    expect(finalExtension('C:\\proj\\Main.CS')).toBe('.cs')
+  })
+
+  it('returns empty for no extension or a leading-dot dotfile', () => {
+    expect(finalExtension('Makefile')).toBe('')
+    expect(finalExtension('.bashrc')).toBe('')
+    expect(finalExtension('dir.d/file')).toBe('')
+  })
+})
+
+describe('Lsp registration', () => {
+  it('registers a provider and routes a query to it, then releases on dispose', async () => {
+    const { lsp } = await mountLsp()
+    const provider = makeProvider('ts', { '.ts': 'typescript' })
+    const dispose = lsp.registerProvider(provider)
+
+    await expect(lsp.query(query('a.ts'))).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: '/ws' })
+    expect(provider.seen[0]).toMatchObject({ filePath: 'a.ts', languageId: 'typescript' })
+
+    dispose()
+    await expect(lsp.query(query('a.ts'))).rejects.toThrow(expect.objectContaining({ code: 'LSP_UNAVAILABLE' }))
+  })
+
+  it('normalizes extension keys to lowercase leading-dot and derives the language id', async () => {
+    const { lsp } = await mountLsp()
+    const provider = makeProvider('ts', { TS: 'typescript' })
+    lsp.registerProvider(provider)
+    await lsp.query(query('a.ts'))
+    expect(provider.seen[0]?.languageId).toBe('typescript')
+  })
+
+  it('rejects an empty provider id (LSP_INVALID_PROVIDER)', async () => {
+    const { lsp } = await mountLsp()
+    expect(() => lsp.registerProvider(makeProvider('  ', { '.ts': 'typescript' })))
+      .toThrow(expect.objectContaining({ code: 'LSP_INVALID_PROVIDER' }))
+  })
+
+  it('rejects a provider with no extensions (LSP_INVALID_PROVIDER)', async () => {
+    const { lsp } = await mountLsp()
+    expect(() => lsp.registerProvider(makeProvider('ts', {})))
+      .toThrow(expect.objectContaining({ code: 'LSP_INVALID_PROVIDER' }))
+  })
+
+  it('rejects an invalid extension mapping (LSP_INVALID_PROVIDER)', async () => {
+    const { lsp } = await mountLsp()
+    expect(() => lsp.registerProvider(makeProvider('ts', { '.tar.gz': 'archive' })))
+      .toThrow(expect.objectContaining({ code: 'LSP_INVALID_PROVIDER' }))
+  })
+
+  it('rejects an empty language id (LSP_INVALID_PROVIDER)', async () => {
+    const { lsp } = await mountLsp()
+    expect(() => lsp.registerProvider(makeProvider('ts', { '.ts': '  ' })))
+      .toThrow(expect.objectContaining({ code: 'LSP_INVALID_PROVIDER' }))
+  })
+
+  it('rejects an extension mapped twice within one provider (LSP_INVALID_PROVIDER)', async () => {
+    const { lsp } = await mountLsp()
+    expect(() => lsp.registerProvider(makeProvider('ts', { '.ts': 'typescript', TS: 'ts2' })))
+      .toThrow(expect.objectContaining({ code: 'LSP_INVALID_PROVIDER' }))
+  })
+
+  it('rejects a duplicate provider id (LSP_CONFLICT)', async () => {
+    const { lsp } = await mountLsp()
+    lsp.registerProvider(makeProvider('ts', { '.ts': 'typescript' }))
+    expect(() => lsp.registerProvider(makeProvider('ts', { '.tsx': 'typescriptreact' })))
+      .toThrow(expect.objectContaining({ code: 'LSP_CONFLICT' }))
+  })
+
+  it('rejects an extension already owned by another provider (LSP_CONFLICT)', async () => {
+    const { lsp } = await mountLsp()
+    lsp.registerProvider(makeProvider('ts', { '.ts': 'typescript' }))
+    expect(() => lsp.registerProvider(makeProvider('other', { '.ts': 'other-lang' })))
+      .toThrow(expect.objectContaining({ code: 'LSP_CONFLICT' }))
+  })
+
+  it('publishes nothing when a later extension conflicts (atomic reservation)', async () => {
+    const { lsp } = await mountLsp()
+    lsp.registerProvider(makeProvider('ts', { '.ts': 'typescript' }))
+    // This provider's `.py` is free but `.ts` conflicts: the whole registration must roll back.
+    expect(() => lsp.registerProvider(makeProvider('py-ts', { '.py': 'python', '.ts': 'x' })))
+      .toThrow(expect.objectContaining({ code: 'LSP_CONFLICT' }))
+    // `.py` must NOT have been reserved.
+    await expect(lsp.query(query('a.py'))).rejects.toThrow(expect.objectContaining({ code: 'LSP_UNAVAILABLE' }))
+  })
+
+  it('releases every extension and the id together on dispose', async () => {
+    const { lsp } = await mountLsp()
+    const dispose = lsp.registerProvider(makeProvider('multi', { '.ts': 'typescript', '.tsx': 'typescriptreact' }))
+    dispose()
+    await expect(lsp.query(query('a.ts'))).rejects.toThrow(expect.objectContaining({ code: 'LSP_UNAVAILABLE' }))
+    await expect(lsp.query(query('a.tsx'))).rejects.toThrow(expect.objectContaining({ code: 'LSP_UNAVAILABLE' }))
+    // The id is free again after release.
+    expect(() => lsp.registerProvider(makeProvider('multi', { '.ts': 'typescript' }))).not.toThrow()
+  })
+
+  it('selection is order-independent across two providers', async () => {
+    const { lsp } = await mountLsp()
+    const ts = makeProvider('ts', { '.ts': 'typescript' }, hover)
+    const py = makeProvider('py', { '.py': 'python' })
+    lsp.registerProvider(ts)
+    lsp.registerProvider(py)
+    await expect(lsp.query(query('a.py'))).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: '/ws' })
+    await expect(lsp.query(query('a.ts', 'hover'))).resolves.toEqual(hover)
+  })
+
+  it('forwards the abort signal verbatim to the provider', async () => {
+    const { lsp } = await mountLsp()
+    const provider = makeProvider('ts', { '.ts': 'typescript' })
+    lsp.registerProvider(provider)
+    const controller = new AbortController()
+    await lsp.query(query('a.ts'), controller.signal)
+    expect(provider.seenSignals[0]).toBe(controller.signal)
+  })
+
+  it('fails LSP_UNAVAILABLE when no provider handles the extension', async () => {
+    const { lsp } = await mountLsp()
+    lsp.registerProvider(makeProvider('ts', { '.ts': 'typescript' }))
+    await expect(lsp.query(query('a.py'))).rejects.toThrow(expect.objectContaining({ code: 'LSP_UNAVAILABLE' }))
+  })
+
+  it('disposes provider registrations when the contributing fiber is disposed (HMR safety)', async () => {
+    const { ctx, lsp } = await mountLsp()
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      inner.lsp.registerProvider(makeProvider('ts', { '.ts': 'typescript' }))
+    }, { inject: ['lsp'] }))
+    await expect(lsp.query(query('a.ts'))).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: '/ws' })
+    await fiber.dispose()
+    await expect(lsp.query(query('a.ts'))).rejects.toThrow(expect.objectContaining({ code: 'LSP_UNAVAILABLE' }))
+  })
+
+  it('LspError carries its structured code', () => {
+    expect(new LspError('m', 'LSP_UNAVAILABLE').code).toBe('LSP_UNAVAILABLE')
+  })
+
+  it('brands a provider id without altering the string', () => {
+    expect(LspProviderId('ts')).toBe('ts')
+  })
+})

packages/lsp/lsp/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../util/brand"
+    },
+    {
+      "path": "../../llm/llm"
+    }
+  ]
+}

packages/lsp/tool-lsp/README.md

@@ -0,0 +1,88 @@
+# @deepseek-ai/dsh-tool-lsp
+
+The model-facing **`lsp` tool** over `ctx.lsp`: one read-only tool with four operations for precise code navigation. It owns the model schema, prompt guidance, coordinate conversion, result limits and formatting, and ACP presentation; it imports no provider.
+
+Namespace plugin (`name` / `inject` / `Config` / `apply`, no default export). Injects `tools`, `lsp`, and `systemPrompt`.
+
+## The tool
+
+`lsp` accepts `operation` (`goToDefinition` | `findReferences` | `goToImplementation` | `hover`), `file_path`, `line`, and `character`. `line` and `character` are positive, one-based UTF-16 cursor coordinates; the tool converts them to the seam's zero-based positions and converts rendered locations back. `findReferences` includes declarations so impact analysis does not omit the defining site. Provider, language id, workspace root, limits, timeout, initialization, and executable stay outside model input.
+
+The tool requires the workspace root from the session `header.cwd`, with no fallback: absence fails as `LSP_WORKSPACE_REQUIRED` before querying. Locations render as stable, file-grouped `path:line:character` entries relativized against the result's `resolvedWorkspaceRoot` (the provider's canonical root), not the session cwd — so a symlinked cwd still renders in-workspace results as workspace-relative paths; a `file:` URI becomes a workspace-relative path (inside) or absolute path (outside), and any other URI stays verbatim. Empty locations and `null` hover are successful no-result responses; malformed provider payloads remain structured errors.
+
+## Configuration
+
+| Key | Default | Meaning |
+|---|---|---|
+| `maxLocations` | `100` | Largest number of rendered locations before an omission marker. |
+| `maxResultChars` | `16000` | Largest complete rendered result, including truncation metadata. |
+| `timeoutMs` | `60000` | Tool-call timeout budget, enforced by `dsh-timeout-policy`; covers the complete queued open/query/close lifecycle and is not model-configurable. |
+
+## Model Experience
+
+### System prompt
+
+#### What the model sees
+
+One system-prompt section (order 112) positions LSP as a precision aid with the following text:
+
+##### Verbatim guidance
+
+```markdown
+Use search/read for ordinary navigation. Use lsp when textual matches are ambiguous or before a change requires precise definitions, implementations, or references. Positions are one-based line and character (UTF-16) at the cursor; an off-symbol position may return no results. findReferences always includes the declaration.
+```
+
+#### Token effect
+
+Fixed guidance cost on every request while the plugin is active.
+
+#### KV Cache effect
+
+Prefix-stable while the plugin scope and guidance text are unchanged; activation or disposal may invalidate reuse from this section.
+
+### Tool schema
+
+#### What the model sees
+
+The model sees the generated [`lsp` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-lsp).
+
+#### Token effect
+
+Fixed schema cost on every request while enabled; the `timeoutMs` budget is never sent to the model.
+
+#### KV Cache effect
+
+Prefix-stable while the visible tool definition and order are unchanged; registration lifecycle or scoped restrictions may invalidate reuse from the first changed schema token.
+
+### Results
+
+#### What the model sees
+
+File-grouped `path:line:character` location lines or normalized hover text, capped first by `maxLocations` and then by `maxResultChars`; omission and truncation markers are included inside the complete character cap. Empty results use distinct `No results.` / `No hover information.` lines.
+
+#### Token effect
+
+Capped per tool result by `maxResultChars`, with `maxLocations` additionally bounding navigation item count.
+
+#### KV Cache effect
+
+Tool results append after the cached request prefix and do not directly invalidate it.
+
+### ACP presentation
+
+#### What the model sees
+
+Nothing. The client renders a generic search card — `{ card: 'generic', kind: 'search', title, locations: [{ path, line }] }` — whose args-derived title carries the operation and one-based cursor; follow-along focuses the queried line while the title preserves the column.
+
+#### Token effect
+
+Zero direct token effect because rendering is client-side only.
+
+#### KV Cache effect
+
+None; ACP presentation is outside the model request.
+
+## Known Limitations and Deferred Work
+
+- **UTF-16 cursor coordinates** — columns are exact for the protocol but hard for a model to count around non-BMP characters; an off-symbol position may return empty results, so the prompt explains the convention without encouraging broad LSP use ([seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)).
+- **No cross-server completeness promise** — supported servers may return empty or partial results depending on indexing readiness; the tool promises no completeness across languages or servers.

packages/lsp/tool-lsp/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@deepseek-ai/dsh-tool-lsp",
+  "description": "Model-facing lsp tool over the DeepSeek Harness LSP capability seam (ctx.lsp) — one read-only tool with goToDefinition/findReferences/goToImplementation/hover operations, one-based UTF-16 cursor coordinates, bounded location rendering, and hover normalization",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-lsp": "^0.0.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-lsp": "workspace:^",
+    "@deepseek-ai/dsh-lsp-local": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-timeout": "workspace:^",
+    "@deepseek-ai/dsh-timeout-policy": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}

packages/lsp/tool-lsp/src/index.ts

@@ -0,0 +1,145 @@
+/**
+ * Model-facing `lsp` tool over `ctx.lsp`. One read-only tool with four operations
+ * (`goToDefinition`/`findReferences`/`goToImplementation`/`hover`); it converts one-based UTF-16
+ * cursor coordinates to the seam's zero-based positions, requires the session workspace with no
+ * fallback, caps and renders results, and attaches a configurable timeout budget for
+ * `dsh-timeout-policy` to enforce. It runtime-injects only `tools`, `lsp`, and `systemPrompt` and
+ * imports no provider.
+ *
+ * Namespace plugin (named exports, no default export).
+ * @module @deepseek-ai/dsh-tool-lsp
+ */
+
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { assertNever, type ContentBlock } from '@deepseek-ai/dsh-llm'
+import { LspError } from '@deepseek-ai/dsh-lsp'
+import type {} from '@deepseek-ai/dsh-lsp'
+import type {} from '@deepseek-ai/dsh-system-prompt'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
+import {
+  DEFAULT_MAX_LOCATIONS,
+  DEFAULT_MAX_RESULT_CHARS,
+  formatHover,
+  formatLocations,
+  LSP_OPERATIONS,
+  parseLspArgs,
+  presentLspCall,
+} from './render.ts'
+import { sessionCwd } from './session-cwd.ts'
+
+export {
+  DEFAULT_MAX_LOCATIONS,
+  DEFAULT_MAX_RESULT_CHARS,
+  formatHover,
+  formatLocations,
+  LSP_OPERATIONS,
+  parseLspArgs,
+  presentLspCall,
+  renderUri,
+} from './render.ts'
+export { sessionCwd } from './session-cwd.ts'
+
+/** Cordis plugin name for loader diagnostics. */
+export const name = 'tool-lsp'
+
+/** Services required by this plugin. */
+export const inject = ['tools', 'lsp', 'systemPrompt']
+
+/** Default tool-call timeout budget (ms), covering the queued open/query/close lifecycle. */
+export const DEFAULT_LSP_TOOL_TIMEOUT_MS = 60_000
+
+/** The stable system-prompt guidance positioning LSP as a precision aid. */
+export const LSP_PROMPT_TEXT =
+  'Use search/read for ordinary navigation. Use lsp when textual matches are ambiguous or before a change requires precise definitions, implementations, or references. Positions are one-based line and character (UTF-16) at the cursor; an off-symbol position may return no results. findReferences always includes the declaration.'
+
+/** Plugin configuration: result caps and the timeout budget. */
+export interface Config {
+  /** Largest number of rendered locations before an omission marker (default 100). */
+  maxLocations?: number
+  /** Largest complete rendered result in characters, including truncation metadata (default 16000). */
+  maxResultChars?: number
+  /** Tool-call timeout budget in ms (default 60000). */
+  timeoutMs?: number
+}
+
+export const Config: z<Config> = z.object({
+  maxLocations: z.number().default(DEFAULT_MAX_LOCATIONS),
+  maxResultChars: z.number().default(DEFAULT_MAX_RESULT_CHARS),
+  timeoutMs: z.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_LSP_TOOL_TIMEOUT_MS),
+})
+
+type ResolvedConfig = Required<Config>
+
+/**
+ * Register the `lsp` tool and its system-prompt guidance.
+ * @param ctx - the plugin context (must inject `tools`, `lsp`, `systemPrompt`).
+ * @param config - the resolved plugin configuration.
+ */
+export function apply(ctx: Context, config: Config): void {
+  const resolved = config as ResolvedConfig
+  assertPositiveInteger('maxLocations', resolved.maxLocations)
+  assertPositiveInteger('maxResultChars', resolved.maxResultChars)
+  assertTimer('timeoutMs', resolved.timeoutMs)
+
+  ctx.systemPrompt.section({ name: 'tool:lsp', order: 112, text: LSP_PROMPT_TEXT })
+
+  ctx.tools.register(defineTool({
+    name: 'lsp',
+    description:
+      'Query a language server for precise code navigation. operation is one of goToDefinition, findReferences, goToImplementation, hover. line and character are one-based UTF-16 cursor coordinates. findReferences includes the declaration.',
+    parameters: {
+      operation: {
+        type: 'string',
+        required: true,
+        enum: [...LSP_OPERATIONS],
+        description: 'goToDefinition, findReferences, goToImplementation, or hover.',
+      },
+      file_path: { type: 'string', required: true, description: 'The source file to query, relative to the workspace or absolute.' },
+      line: { type: 'number', required: true, description: 'One-based line of the cursor.' },
+      character: { type: 'number', required: true, description: 'One-based UTF-16 column of the cursor.' },
+    },
+    timeoutMs: resolved.timeoutMs,
+    async execute(args, exec): Promise<ContentBlock[]> {
+      const input = parseLspArgs(args)
+      const workspaceRoot = sessionCwd(exec)
+      if (workspaceRoot === undefined) {
+        throw new LspError('the lsp tool requires a session workspace cwd', 'LSP_WORKSPACE_REQUIRED')
+      }
+      const result = await ctx.lsp.query({
+        operation: input.operation,
+        filePath: input.filePath,
+        position: input.position,
+        workspaceRoot,
+      }, exec.signal)
+      switch (result.kind) {
+        case 'locations':
+          // Relativize against the provider's canonical workspace root (which its file: URIs are
+          // relative to), not the session cwd: a symlinked cwd would otherwise misclassify every
+          // in-workspace location as external and render it as an absolute path.
+          return [{ type: 'text', text: formatLocations(result.locations, result.resolvedWorkspaceRoot, resolved.maxLocations, resolved.maxResultChars) }]
+        case 'hover':
+          return [{ type: 'text', text: formatHover(result.hover, resolved.maxResultChars) }]
+        /* v8 ignore next -- exhaustive over the closed LspQueryResult union; unreachable. */
+        default:
+          return assertNever(result, 'tool-lsp result')
+      }
+    },
+    presentCall: presentLspCall,
+  }))
+}
+
+/** Reject a non-positive-integer config value at load, so misconfiguration fails loud. */
+function assertPositiveInteger(name: string, value: number): void {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error(`tool-lsp: ${name} must be a positive integer`)
+  }
+}
+
+/** Reject a timer value Node would clamp instead of scheduling as configured. */
+function assertTimer(name: string, value: number): void {
+  if (!Number.isInteger(value) || value < 1 || value > MAX_TIMER_DELAY_MS) {
+    throw new Error(`tool-lsp: ${name} must be a positive integer no greater than ${MAX_TIMER_DELAY_MS}`)
+  }
+}

packages/lsp/tool-lsp/src/render.ts

@@ -0,0 +1,168 @@
+/**
+ * Pure formatting and coordinate conversion for the `lsp` tool: one-based↔zero-based UTF-16 cursor
+ * conversion, workspace-grouped location rendering with `file:`-URI resolution, complete-result
+ * capping, and ACP presentation. No I/O — a UI may call the presenter on live streaming and on
+ * replay, so it depends only on the tool arguments.
+ * @module @deepseek-ai/dsh-tool-lsp/render
+ */
+
+import { fileURLToPath } from 'node:url'
+import { isAbsolute, relative, sep } from 'node:path'
+import type { GenericCallView } from '@deepseek-ai/dsh-tools'
+import type { LspHover, LspLocation, LspOperation, LspPosition } from '@deepseek-ai/dsh-lsp'
+
+/** The four operations the tool exposes, as a runtime tuple for schema enum + validation. */
+export const LSP_OPERATIONS: readonly LspOperation[] = ['goToDefinition', 'findReferences', 'goToImplementation', 'hover']
+
+/** Default cap on rendered locations before an omission marker is appended. */
+export const DEFAULT_MAX_LOCATIONS = 100
+
+/** Default cap on the complete rendered tool result, including truncation metadata. */
+export const DEFAULT_MAX_RESULT_CHARS = 16_000
+
+/** Validated `lsp` arguments after coordinate checks. */
+export interface LspToolInput {
+  readonly operation: LspOperation
+  readonly filePath: string
+  /** Zero-based UTF-16 position converted from the one-based model coordinates. */
+  readonly position: LspPosition
+}
+
+/** The raw, schema-typed argument shape. */
+export interface LspToolArgs {
+  readonly operation: string
+  readonly file_path: string
+  readonly line: number
+  readonly character: number
+}
+
+/**
+ * Validate and convert model arguments: `operation` must be one of the four; `line`/`character` are
+ * positive one-based integers converted to the seam's zero-based position.
+ * @param args - the schema-validated raw arguments.
+ * @returns the validated input with a zero-based position.
+ * @throws Error when the operation is unknown or a coordinate is not a positive integer.
+ */
+export function parseLspArgs(args: LspToolArgs): LspToolInput {
+  if (!isOperation(args.operation)) {
+    throw new Error(`operation must be one of ${LSP_OPERATIONS.join(', ')}`)
+  }
+  if (args.file_path.trim().length === 0) throw new Error('file_path must be a non-empty string')
+  const line = oneBased(args.line, 'line')
+  const character = oneBased(args.character, 'character')
+  return {
+    operation: args.operation,
+    filePath: args.file_path,
+    // The model counts from 1; the seam (and protocol) count from 0.
+    position: { line: line - 1, character: character - 1 },
+  }
+}
+
+/** Whether a string is one of the four operations. */
+function isOperation(value: string): value is LspOperation {
+  return (LSP_OPERATIONS as readonly string[]).includes(value)
+}
+
+/** Validate a one-based coordinate is a positive integer. */
+function oneBased(value: number, name: string): number {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error(`${name} must be a positive integer (one-based)`)
+  }
+  return value
+}
+
+/**
+ * Render a locations result grouped by file, converting each zero-based location back to a one-based
+ * `path:line:character` entry. A `file:` URI inside the workspace becomes a workspace-relative path;
+ * outside it, an absolute path; a non-`file:` URI is kept verbatim. Applies `maxLocations` and
+ * appends an omission marker when it truncates by count, then applies the complete result cap.
+ * @param locations - the seam's locations (possibly empty).
+ * @param workspaceRoot - the canonical workspace root for relativizing `file:` paths.
+ * @param maxLocations - the cap before truncation.
+ * @param maxResultChars - the complete rendered-text cap, including truncation metadata.
+ * @returns the rendered text; a distinct no-result line when there are none.
+ */
+export function formatLocations(
+  locations: readonly LspLocation[],
+  workspaceRoot: string,
+  maxLocations: number,
+  maxResultChars: number,
+): string {
+  if (locations.length === 0) return boundResult('No results.', maxResultChars, 'locations')
+  const shown = locations.slice(0, maxLocations)
+  const omitted = locations.length - shown.length
+  const grouped = new Map<string, string[]>()
+  for (const location of shown) {
+    const path = renderUri(location.uri, workspaceRoot)
+    const line = location.range.start.line + 1
+    const character = location.range.start.character + 1
+    const entries = grouped.get(path) ?? []
+    entries.push(`${path}:${line}:${character}`)
+    grouped.set(path, entries)
+  }
+  const lines: string[] = []
+  for (const entries of grouped.values()) lines.push(...entries)
+  if (omitted > 0) {
+    lines.push(`… ${omitted} more location${omitted === 1 ? '' : 's'} omitted (limit ${maxLocations}).`)
+  }
+  return boundResult(lines.join('\n'), maxResultChars, 'locations')
+}
+
+/**
+ * Render a hover result, applying `maxResultChars` last and keeping its marker within the cap.
+ * @param hover - the normalized hover, or `null` for no hover.
+ * @param maxResultChars - the complete rendered-text cap, including truncation metadata.
+ * @returns the rendered hover text; a distinct no-result line for `null`.
+ */
+export function formatHover(hover: LspHover | null, maxResultChars: number): string {
+  const text = hover === null ? 'No hover information.' : hover.contents
+  return boundResult(text, maxResultChars, 'hover')
+}
+
+/** Bound a complete rendered result, including the truncation notice itself. */
+function boundResult(text: string, maxChars: number, label: string): string {
+  if (text.length <= maxChars) return text
+  const notice = `\n… ${label} truncated (limit ${maxChars} characters).`
+  if (notice.length >= maxChars) return notice.slice(0, maxChars)
+  return `${text.slice(0, maxChars - notice.length)}${notice}`
+}
+
+/**
+ * Resolve a location URI to a display path. A `file:` URI accepted by Node becomes workspace-relative
+ * (inside) or absolute (outside); any other URI is returned verbatim.
+ * @param uri - the target URI from the seam.
+ * @param workspaceRoot - the canonical workspace root.
+ * @returns the display path or the verbatim URI.
+ */
+export function renderUri(uri: string, workspaceRoot: string): string {
+  if (!uri.startsWith('file:')) return uri
+  let absolute: string
+  try {
+    absolute = fileURLToPath(uri)
+  } catch {
+    // A malformed file: URI is not a path we can resolve; show it verbatim.
+    return uri
+  }
+  const rel = relative(workspaceRoot, absolute)
+  if (rel === '') return '.'
+  // A leading `..` SEGMENT (or an absolute rel) means outside the workspace; guard against a false
+  // positive on an in-workspace path whose first component merely starts with dots (e.g. `..gen/x`).
+  const outside = rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)
+  return outside ? absolute : rel.split(sep).join('/')
+}
+
+/**
+ * ACP presentation for a pending `lsp` call. Uses a generic search card; the title carries the
+ * operation and one-based cursor, and `locations` focuses the queried line (ACP `FileLocation` has
+ * no character, so the title preserves the column).
+ * @param args - the raw tool arguments.
+ * @returns the generic call view.
+ */
+export function presentLspCall(args: LspToolArgs): GenericCallView {
+  return {
+    card: 'generic',
+    kind: 'search',
+    title: `LSP ${args.operation} ${args.file_path}:${args.line}:${args.character}`,
+    locations: [{ path: args.file_path, line: args.line }],
+  }
+}

packages/lsp/tool-lsp/src/session-cwd.ts

@@ -0,0 +1,19 @@
+/**
+ * Derive the workspace root an `lsp` call resolves against: the calling agent's per-session
+ * workspace (`exec.agent.session.header.cwd`), mirroring how the filesystem tools resolve paths.
+ * Unlike those tools, LSP has NO provider fallback — a missing cwd fails the call as
+ * `LSP_WORKSPACE_REQUIRED`, because the local provider must canonicalize a real workspace before it
+ * can start a server.
+ * @module @deepseek-ai/dsh-tool-lsp/session-cwd
+ */
+
+import type { ToolExecution } from '@deepseek-ai/dsh-tools'
+
+/**
+ * The session workspace cwd for this call, or `undefined` when none applies.
+ * @param exec - the tool-execution context; only its optional `agent` is read.
+ * @returns the calling agent's session cwd, or undefined for a non-agent caller.
+ */
+export function sessionCwd(exec: ToolExecution): string | undefined {
+  return exec.agent?.session.header.cwd
+}

packages/lsp/tool-lsp/tests/integration.spec.ts

@@ -0,0 +1,94 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { mkdtemp, mkdir, rm, writeFile, realpath } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { Context } from 'cordis'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import Lsp from '@deepseek-ai/dsh-lsp'
+import * as LspLocal from '@deepseek-ai/dsh-lsp-local'
+import * as TimeoutPolicy from '@deepseek-ai/dsh-timeout-policy'
+import * as ToolLsp from '@deepseek-ai/dsh-tool-lsp'
+
+/**
+ * Focused in-process integration of the model-facing tool, seam, local provider, and timeout policy.
+ * The `lsp-definition` ACP snapshot owns the shipped Loader/app entry path.
+ */
+
+let root: string
+let ws: string
+
+beforeEach(async () => {
+  root = await realpath(await mkdtemp(join(tmpdir(), 'lsp-tool-int-')))
+  ws = join(root, 'ws')
+  await mkdir(ws)
+  await writeFile(join(ws, 'a.ts'), 'const x = 1\n')
+})
+
+afterEach(async () => {
+  await rm(root, { recursive: true, force: true })
+})
+
+/** An inline stdio server that answers initialize + definition; `hang` makes textDocument/* stall. */
+function serverScript(hang: boolean): string {
+  const definition = JSON.stringify({ uri: pathToFileURL(join(ws, 'a.ts')).href, range: { start: { line: 0, character: 0 }, end: { line: 0, character: 3 } } })
+  return 'let b=Buffer.alloc(0);'
+    + `const DEF=${definition};`
+    + 'const fr=(o)=>{const x=Buffer.from(JSON.stringify({jsonrpc:"2.0",...o}));return Buffer.concat([Buffer.from(`Content-Length: ${x.length}\\r\\n\\r\\n`),x]);};'
+    + 'process.stdin.on("data",c=>{b=Buffer.concat([b,c]);for(;;){const s=b.indexOf("\\r\\n\\r\\n");if(s<0)break;const len=Number(/(\\d+)/.exec(b.toString("ascii",0,s))[1]);if(b.length<s+4+len)break;const m=JSON.parse(b.toString("utf8",s+4,s+4+len));b=b.subarray(s+4+len);'
+    + 'if(m.method==="initialize")process.stdout.write(fr({id:m.id,result:{capabilities:{positionEncoding:"utf-16",textDocumentSync:1,definitionProvider:true}}}));'
+    + `else if(m.method==="textDocument/definition"){${hang ? '' : 'process.stdout.write(fr({id:m.id,result:DEF}));'}}`
+    + 'else if(m.method==="shutdown")process.stdout.write(fr({id:m.id,result:null}));'
+    + 'else if(m.method==="exit")process.exit(0);'
+    + '}});'
+}
+
+async function mount(hang: boolean, timeoutMs?: number): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(Lsp)
+  await ctx.plugin(LspLocal, {
+    servers: {
+      inline: {
+        command: process.execPath,
+        args: ['-e', serverScript(hang)],
+        extensionToLanguage: { '.ts': 'typescript' },
+        shutdownTimeoutMs: 200,
+        killGraceMs: 200,
+      },
+    },
+  })
+  await ctx.plugin(TimeoutPolicy)
+  await ctx.plugin(ToolLsp, timeoutMs !== undefined ? { timeoutMs } : {})
+  return ctx
+}
+
+let seq = 0
+function call(ctx: Context, args: unknown) {
+  return ctx.tools.execute({
+    callId: `int-${++seq}` as never,
+    name: 'lsp',
+    arguments: args,
+    agent: { session: { header: { cwd: ws } } } as never,
+  })
+}
+
+describe('tool-lsp integration', () => {
+  it('round-trips a definition query through the real provider and renders a location', async () => {
+    const ctx = await mount(false)
+    const result = await call(ctx, { operation: 'goToDefinition', file_path: 'a.ts', line: 1, character: 7 })
+    expect(result.isError).toBe(false)
+    expect(result.content[0]).toEqual({ type: 'text', text: 'a.ts:1:1' })
+    await ctx.fiber.dispose()
+  }, 30_000)
+
+  it('enforces the TOOL_TIMEOUT budget when the server hangs', async () => {
+    const ctx = await mount(true, 300)
+    const result = await call(ctx, { operation: 'goToDefinition', file_path: 'a.ts', line: 1, character: 7 })
+    expect(result.isError).toBe(true)
+    expect(result.error?.code).toBe('TOOL_TIMEOUT')
+    await ctx.fiber.dispose()
+  }, 30_000)
+})

packages/lsp/tool-lsp/tests/load-path.spec.ts

@@ -0,0 +1,24 @@
+/**
+ * Loader export-shape guard for @deepseek-ai/dsh-tool-lsp. It is a NAMESPACE plugin with `inject`, so a
+ * stray `export default apply` would make the Loader's `unwrapExports` collapse the module to the
+ * bare `apply`, dropping `inject` (postmortem 0001). This verifies the namespace survives
+ * `Loader.prototype.unwrapExports`; the `lsp-definition` ACP snapshot owns full app composition.
+ */
+
+import { describe, expect, it } from 'vitest'
+import Loader from '@cordisjs/plugin-loader'
+import * as toolLsp from '@deepseek-ai/dsh-tool-lsp'
+
+describe('dsh-tool-lsp Loader export-shape guard', () => {
+  it('has no default export and keeps name/inject/Config through unwrapExports', () => {
+    expect('default' in toolLsp).toBe(false)
+
+    const loader = Object.create(Loader.prototype) as Loader
+    const unwrapped = loader.unwrapExports(toolLsp) as Record<string, unknown>
+    expect(unwrapped).toBe(toolLsp)
+    expect(unwrapped.name).toBe('tool-lsp')
+    expect(unwrapped.inject).toEqual(['tools', 'lsp', 'systemPrompt'])
+    expect(typeof unwrapped.apply).toBe('function')
+    expect(unwrapped.Config).toBeDefined()
+  })
+})

packages/lsp/tool-lsp/tests/render.spec.ts

@@ -0,0 +1,142 @@
+import { describe, expect, it } from 'vitest'
+import { pathToFileURL } from 'node:url'
+import { join } from 'node:path'
+import {
+  DEFAULT_MAX_LOCATIONS,
+  DEFAULT_MAX_RESULT_CHARS,
+  formatHover,
+  formatLocations,
+  LSP_OPERATIONS,
+  parseLspArgs,
+  presentLspCall,
+  renderUri,
+} from '@deepseek-ai/dsh-tool-lsp'
+import type { LspLocation } from '@deepseek-ai/dsh-lsp'
+
+const WS = '/home/u/proj'
+
+function loc(uri: string, line: number, character = 0): LspLocation {
+  return { uri, range: { start: { line, character }, end: { line, character: character + 1 } } }
+}
+
+describe('parseLspArgs', () => {
+  it('accepts the four operations and converts one-based to zero-based', () => {
+    for (const operation of LSP_OPERATIONS) {
+      const input = parseLspArgs({ operation, file_path: 'a.ts', line: 3, character: 5 })
+      expect(input.operation).toBe(operation)
+      expect(input.position).toEqual({ line: 2, character: 4 })
+    }
+  })
+
+  it('rejects an unknown operation', () => {
+    expect(() => parseLspArgs({ operation: 'rename', file_path: 'a.ts', line: 1, character: 1 }))
+      .toThrow(/operation must be one of/)
+  })
+
+  it('rejects a blank file_path', () => {
+    expect(() => parseLspArgs({ operation: 'hover', file_path: '   ', line: 1, character: 1 }))
+      .toThrow(/file_path/)
+  })
+
+  it('rejects non-positive or non-integer coordinates', () => {
+    expect(() => parseLspArgs({ operation: 'hover', file_path: 'a.ts', line: 0, character: 1 })).toThrow(/line/)
+    expect(() => parseLspArgs({ operation: 'hover', file_path: 'a.ts', line: 1, character: 0 })).toThrow(/character/)
+    expect(() => parseLspArgs({ operation: 'hover', file_path: 'a.ts', line: 1.5, character: 1 })).toThrow(/line/)
+  })
+})
+
+describe('renderUri', () => {
+  it('relativizes a file: URI inside the workspace with forward slashes', () => {
+    const uri = pathToFileURL(join(WS, 'src', 'a.ts')).href
+    expect(renderUri(uri, WS)).toBe('src/a.ts')
+  })
+
+  it('returns an absolute path for a file: URI outside the workspace', () => {
+    const uri = pathToFileURL('/other/lib/b.ts').href
+    expect(renderUri(uri, WS)).toBe('/other/lib/b.ts')
+  })
+
+  it('renders the workspace root itself as "."', () => {
+    expect(renderUri(pathToFileURL(WS).href, WS)).toBe('.')
+  })
+
+  it('keeps an in-workspace path whose first segment starts with dots relative', () => {
+    // `..generated` is a real in-workspace dir, not a parent escape; only a `..` segment is external.
+    const uri = pathToFileURL(join(WS, '..generated', 'a.ts')).href
+    expect(renderUri(uri, WS)).toBe('..generated/a.ts')
+  })
+
+  it('keeps a non-file URI verbatim', () => {
+    expect(renderUri('untitled:Untitled-1', WS)).toBe('untitled:Untitled-1')
+    expect(renderUri('jdt://contents/Foo.class', WS)).toBe('jdt://contents/Foo.class')
+  })
+
+  it('keeps a malformed file: URI verbatim when it cannot be parsed to a path', () => {
+    // A file: URI with a host that fileURLToPath rejects falls through to the verbatim path.
+    expect(renderUri('file://host/notlocal', WS)).toBe('file://host/notlocal')
+  })
+})
+
+describe('formatLocations', () => {
+  it('renders a no-result line for an empty list', () => {
+    expect(formatLocations([], WS, DEFAULT_MAX_LOCATIONS, DEFAULT_MAX_RESULT_CHARS)).toBe('No results.')
+  })
+
+  it('renders one-based path:line:character grouped by file', () => {
+    const a = pathToFileURL(join(WS, 'a.ts')).href
+    const text = formatLocations([loc(a, 0, 0), loc(a, 4, 2)], WS, DEFAULT_MAX_LOCATIONS, DEFAULT_MAX_RESULT_CHARS)
+    expect(text).toBe('a.ts:1:1\na.ts:5:3')
+  })
+
+  it('caps at maxLocations and marks the omission', () => {
+    const a = pathToFileURL(join(WS, 'a.ts')).href
+    const many = Array.from({ length: 5 }, (_, i) => loc(a, i))
+    const text = formatLocations(many, WS, 2, DEFAULT_MAX_RESULT_CHARS)
+    expect(text).toContain('a.ts:1:1')
+    expect(text).toContain('3 more locations omitted (limit 2).')
+  })
+
+  it('uses the singular omission marker for exactly one extra', () => {
+    const a = pathToFileURL(join(WS, 'a.ts')).href
+    const text = formatLocations([loc(a, 0), loc(a, 1)], WS, 1, DEFAULT_MAX_RESULT_CHARS)
+    expect(text).toContain('1 more location omitted (limit 1).')
+  })
+
+  it('caps the complete location text even when one URI is enormous', () => {
+    const maxResultChars = 80
+    const text = formatLocations([loc(`custom:${'x'.repeat(1_000_000)}`, 0)], WS, 1, maxResultChars)
+    expect(text).toHaveLength(maxResultChars)
+    expect(text).toContain('locations truncated')
+  })
+})
+
+describe('formatHover', () => {
+  it('renders a no-result line for null', () => {
+    expect(formatHover(null, DEFAULT_MAX_RESULT_CHARS)).toBe('No hover information.')
+  })
+
+  it('returns short hover verbatim', () => {
+    expect(formatHover({ contents: '```ts\nx: number\n```' }, DEFAULT_MAX_RESULT_CHARS)).toBe('```ts\nx: number\n```')
+  })
+
+  it('caps the complete hover text including its truncation marker', () => {
+    const text = formatHover({ contents: 'a'.repeat(100) }, 60)
+    expect(text).toHaveLength(60)
+    expect(text).toContain('hover truncated (limit 60 characters).')
+  })
+
+  it('still honors a cap smaller than the truncation marker', () => {
+    expect(formatHover({ contents: 'a'.repeat(100) }, 10)).toHaveLength(10)
+  })
+})
+
+describe('presentLspCall', () => {
+  it('is a generic search card with an operation/cursor title and a line location', () => {
+    expect(presentLspCall({ operation: 'findReferences', file_path: 'a.ts', line: 3, character: 7 })).toEqual({
+      card: 'generic',
+      kind: 'search',
+      title: 'LSP findReferences a.ts:3:7',
+      locations: [{ path: 'a.ts', line: 3 }],
+    })
+  })
+})

packages/lsp/tool-lsp/tests/tool-lsp.spec.ts

@@ -0,0 +1,193 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import Lsp, { LspProviderId, type LspProvider, type LspProviderQuery, type LspQueryResult } from '@deepseek-ai/dsh-lsp'
+import * as ToolLsp from '@deepseek-ai/dsh-tool-lsp'
+import { DEFAULT_LSP_TOOL_TIMEOUT_MS, LSP_PROMPT_TEXT } from '@deepseek-ai/dsh-tool-lsp'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
+
+/** A scripted provider recording queries; `respond` yields the result or throws. */
+function stubProvider(
+  respond: (request: LspProviderQuery) => LspQueryResult,
+  extensionToLanguage: Record<string, string> = { '.ts': 'typescript' },
+): LspProvider & { seen: LspProviderQuery[] } {
+  const seen: LspProviderQuery[] = []
+  return {
+    id: LspProviderId('stub'),
+    extensionToLanguage,
+    seen,
+    query(request) {
+      seen.push(request)
+      return Promise.resolve(respond(request))
+    },
+  }
+}
+
+/** Mount the real tool stack over a real seam plus one stub provider. */
+async function mount(
+  provider?: LspProvider,
+  config: ToolLsp.Config = {},
+): Promise<{ ctx: Context }> {
+  const ctx = new Context()
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(Lsp)
+  if (provider) (ctx.lsp as Lsp).registerProvider(provider)
+  await ctx.plugin(ToolLsp, config)
+  return { ctx }
+}
+
+let seq = 0
+/** `cwd: null` means "no agent" (tests LSP_WORKSPACE_REQUIRED); a string is the session cwd. */
+function call(ctx: Context, args: unknown, cwd: string | null = '/ws') {
+  return ctx.tools.execute({
+    callId: `c-${++seq}` as never,
+    name: 'lsp',
+    arguments: args,
+    ...cwd !== null ? { agent: { session: { header: { cwd } } } as never } : {},
+  })
+}
+
+const okLocations: LspQueryResult = {
+  kind: 'locations',
+  locations: [{ uri: 'file:///ws/a.ts', range: { start: { line: 0, character: 0 }, end: { line: 0, character: 1 } } }],
+  resolvedWorkspaceRoot: '/ws',
+}
+
+describe('tool-lsp registration', () => {
+  it('registers the lsp tool and its prompt section', async () => {
+    const { ctx } = await mount(stubProvider(() => okLocations))
+    expect(ctx.tools.get('lsp')).toBeDefined()
+    const prompt = await ctx.systemPrompt.assemble()
+    const text = prompt.sections.map(s => s.text).join('\n')
+    expect(text).toContain(LSP_PROMPT_TEXT)
+  })
+
+  it('attaches the default timeout budget to the tool definition', async () => {
+    const { ctx } = await mount(stubProvider(() => okLocations))
+    expect(ctx.tools.get('lsp')?.timeoutMs).toBe(DEFAULT_LSP_TOOL_TIMEOUT_MS)
+  })
+
+  it('honors a configured timeout override', async () => {
+    const { ctx } = await mount(stubProvider(() => okLocations), { timeoutMs: 5000 })
+    expect(ctx.tools.get('lsp')?.timeoutMs).toBe(5000)
+  })
+
+  it('exposes exactly the four operations in the schema enum', async () => {
+    const { ctx } = await mount(stubProvider(() => okLocations))
+    const schema = ctx.tools.get('lsp')?.parameters as { properties: { operation: { enum: string[] } } }
+    expect(schema.properties.operation.enum).toEqual(['goToDefinition', 'findReferences', 'goToImplementation', 'hover'])
+  })
+
+  it('has no default export (namespace plugin shape)', () => {
+    expect((ToolLsp as { default?: unknown }).default).toBeUndefined()
+  })
+
+  it('rejects a non-positive config value at load', async () => {
+    await expect(mount(stubProvider(() => okLocations), { maxLocations: 0 })).rejects.toThrow(/maxLocations/)
+  })
+
+  it('rejects a timeout above Node timer range at load', async () => {
+    await expect(mount(stubProvider(() => okLocations), { timeoutMs: MAX_TIMER_DELAY_MS + 1 }))
+      .rejects.toThrow(/timeoutMs/)
+    expect(() => {
+      ToolLsp.apply(new Context(), {
+        maxLocations: 100,
+        maxResultChars: 16_000,
+        timeoutMs: MAX_TIMER_DELAY_MS + 1,
+      })
+    }).toThrow(/timeoutMs/)
+  })
+})
+
+describe('tool-lsp execution', () => {
+  it('converts one-based coordinates and passes the session cwd as workspaceRoot', async () => {
+    const provider = stubProvider(() => okLocations)
+    const { ctx } = await mount(provider)
+    const result = await call(ctx, { operation: 'goToDefinition', file_path: 'a.ts', line: 3, character: 5 }, '/ws')
+    expect(result.isError).toBe(false)
+    expect(provider.seen[0]).toMatchObject({
+      operation: 'goToDefinition',
+      filePath: 'a.ts',
+      position: { line: 2, character: 4 },
+      workspaceRoot: '/ws',
+    })
+  })
+
+  it('renders locations relative to the workspace', async () => {
+    const { ctx } = await mount(stubProvider(() => okLocations))
+    const result = await call(ctx, { operation: 'findReferences', file_path: 'a.ts', line: 1, character: 1 }, '/ws')
+    expect(result.content[0]).toEqual({ type: 'text', text: 'a.ts:1:1' })
+  })
+
+  it('relativizes against the provider resolvedWorkspaceRoot, not the session cwd', async () => {
+    // A symlinked session cwd (`/alias`) resolves to a real path (`/real/ws`) that the provider's
+    // location URIs are under. Relativizing against the alias would misclassify the location as
+    // external and print an absolute path; the tool must use resolvedWorkspaceRoot.
+    const provider = stubProvider(() => ({
+      kind: 'locations',
+      locations: [{ uri: 'file:///real/ws/a.ts', range: { start: { line: 0, character: 0 }, end: { line: 0, character: 1 } } }],
+      resolvedWorkspaceRoot: '/real/ws',
+    }))
+    const { ctx } = await mount(provider)
+    const result = await call(ctx, { operation: 'goToDefinition', file_path: 'a.ts', line: 1, character: 1 }, '/alias')
+    expect(provider.seen[0]).toMatchObject({ workspaceRoot: '/alias' })
+    expect(result.content[0]).toEqual({ type: 'text', text: 'a.ts:1:1' })
+  })
+
+  it('renders hover content', async () => {
+    const { ctx } = await mount(stubProvider(() => ({ kind: 'hover', hover: { contents: 'number' } })))
+    const result = await call(ctx, { operation: 'hover', file_path: 'a.ts', line: 1, character: 1 }, '/ws')
+    expect(result.content[0]).toEqual({ type: 'text', text: 'number' })
+  })
+
+  it('fails LSP_WORKSPACE_REQUIRED without a session cwd', async () => {
+    const { ctx } = await mount(stubProvider(() => okLocations))
+    const result = await call(ctx, { operation: 'goToDefinition', file_path: 'a.ts', line: 1, character: 1 }, null)
+    expect(result.isError).toBe(true)
+    expect(result.error?.code).toBe('LSP_WORKSPACE_REQUIRED')
+  })
+
+  it('surfaces a structured LSP_UNAVAILABLE when no provider handles the file', async () => {
+    const { ctx } = await mount(stubProvider(() => okLocations, { '.py': 'python' }))
+    const result = await call(ctx, { operation: 'goToDefinition', file_path: 'a.ts', line: 1, character: 1 }, '/ws')
+    expect(result.isError).toBe(true)
+    expect(result.error?.code).toBe('LSP_UNAVAILABLE')
+  })
+
+  it('returns a structured INVALID_ARGS on a bad operation', async () => {
+    const { ctx } = await mount(stubProvider(() => okLocations))
+    const result = await call(ctx, { operation: 'rename', file_path: 'a.ts', line: 1, character: 1 }, '/ws')
+    expect(result.isError).toBe(true)
+    expect(result.error?.code).toBe('INVALID_ARGS')
+  })
+
+  it('forwards exec.signal to the seam query', async () => {
+    const seen: (AbortSignal | undefined)[] = []
+    const provider: LspProvider = {
+      id: LspProviderId('sig'),
+      extensionToLanguage: { '.ts': 'typescript' },
+      query(_request, signal) {
+        seen.push(signal)
+        return Promise.resolve(okLocations)
+      },
+    }
+    const { ctx } = await mount(provider)
+    await call(ctx, { operation: 'goToDefinition', file_path: 'a.ts', line: 1, character: 1 }, '/ws')
+    // The timeout policy is not mounted here, so the signal is whatever the registry passes (may be
+    // undefined); the point is the tool threads it through without throwing.
+    expect(seen).toHaveLength(1)
+  })
+
+  it('presentCall renders the pending card from args', async () => {
+    const { ctx } = await mount(stubProvider(() => okLocations))
+    const view = ctx.tools.get('lsp')?.presentCall?.({ operation: 'hover', file_path: 'a.ts', line: 2, character: 3 })
+    expect(view).toEqual({
+      card: 'generic',
+      kind: 'search',
+      title: 'LSP hover a.ts:2:3',
+      locations: [{ path: 'a.ts', line: 2 }],
+    })
+  })
+})

packages/lsp/tool-lsp/tsconfig.json

@@ -0,0 +1,36 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../core/tools"
+    },
+    {
+      "path": "../../core/system-prompt"
+    },
+    {
+      "path": "../../util/timeout"
+    },
+    {
+      "path": "../lsp"
+    }
+  ]
+}

packages/subagent/subagent-acp/README.md

@@ -4,7 +4,9 @@ The ACP provider runs each subagent in a fresh subprocess and drives it as an Ag
 
 ## Start and ownership
 
-`start(request)` performs `spawn` → ACP `initialize` → `newSession` before it fulfills. Fulfillment therefore means a remote session is ready and ownership has transferred to the caller. A spawn, initialization, new-session, or pre-publication cancellation failure rejects only after the subprocess has been reaped.
+`start(request)` resolves the child's working directory, then performs `spawn` → ACP `initialize` → `newSession` before it fulfills. Fulfillment therefore means a remote session is ready and ownership has transferred to the caller. A spawn, initialization, new-session, or pre-publication cancellation failure rejects only after the subprocess has been reaped; a working-directory resolution failure rejects before anything is spawned.
+
+The working directory is the configured `cwd` override when set, else the delegating parent session's cwd — never the server process's own cwd, because one server process serves sessions from many workspaces. The parent-derived value must be an absolute path naming a directory the harness can enter (search permission — what a subprocess cwd needs), and the same resolved path becomes both the subprocess cwd and the ACP `session/new` workspace.
 
 The returned run id is minted in the parent namespace. The child server's session id remains private to ACP wire calls because ACP guarantees it only within that fresh child process; using it as the parent lifecycle id could collide with another remote run or a local agent.
 
@@ -14,7 +16,7 @@ After publication, the provider sends the prompt and collects streamed `agent_me
 
 ## Capabilities and context
 
-ACP advertises no start-time capabilities because this process cannot enforce the remote child's depth, tool filter, persona, or structured-output runtime. It also reports `inheritsParentContext: false`: the remote session starts fresh and ignores `request.parent` beyond the seam's required attribution field.
+ACP advertises no start-time capabilities because this process cannot enforce the remote child's depth, tool filter, persona, or structured-output runtime. It also reports `inheritsParentContext: false`: the remote session starts fresh, and the only parent-derived input is the workspace cwd described above — no conversation context crosses the process boundary.
 
 ## Configuration
 
@@ -23,7 +25,7 @@ ACP advertises no start-time capabilities because this process cannot enforce th
 | `providerName` | `acp` | Registry name on `ctx.subagents`. |
 | `command` | required | Executable spawned for each run. |
 | `args` | `[]` | Command arguments. |
-| `cwd` | process cwd | Child process and ACP session working directory. |
+| `cwd` | parent session cwd | Working-directory override for the child process and its ACP session; must be non-empty, a relative value resolves against the harness launch directory at load, and the result must name a directory the harness can enter. |
 | `permission` | `reject` | Auto-answer permission requests by rejecting or choosing the first allow-shaped option. |
 | `env` | `{}` | Explicit child environment layered over a credential-scrubbed parent environment. |
 | `disposeEofGraceMs` | `6000` | Grace after stdin EOF before SIGTERM. |
@@ -57,7 +59,7 @@ The child environment is built by [`buildChildEnv`](../subagent-subprocess/READM
 
 The package has no default export. Cordis loader unwrapping would otherwise hide the named `inject` metadata; see [postmortem 0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.md).
 
-Keyless tests drive a scripted ACP subprocess over real stdio. The with-key e2e drives the repository's real ACP agent and self-skips without `DEEPSEEK_API_KEY`.
+Keyless tests drive a scripted ACP subprocess over real stdio, including a Loader-composed stdio app proving parent-session cwd inheritance end to end. The with-key e2e drives the repository's real ACP agent and self-skips without `DEEPSEEK_API_KEY`.
 
 ## Model Experience
 
@@ -92,6 +94,7 @@ Append-only; newly visible content follows the reusable request prefix and does
 ## Known Limitations and Deferred Work
 
 - **A fresh process per run** — persistent-process pooling is a future optimization ([the seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)).
+- **Local workspaces only** — the resolved cwd is a local path handed to a child on the same machine; workspace mapping for a remote ACP agent would need its own backend capability and is not designed here.
 - **No optional start-time capabilities** — this provider cannot apply the local harness's `outputSchema`, depth cap, tool filter, or persona inside the remote process, so it advertises none and the service rejects requests that require them.
 - **Only `agent_message_chunk` text is collected** — the child's tool-call activity, thought chunks, and plan updates are not surfaced to the parent.
 - **Permission prompts are auto-answered** (`permission: allow | reject`) — no human is surfaced a child's `session/request_permission` in this cut.

packages/subagent/subagent-acp/src/index.ts

@@ -1,11 +1,14 @@
 /**
  * Out-of-process ACP subagent backend. Each child has its own process, session, model, and
- * tools, so it shares no Cordis context, ignores `request.parent`, and advertises no parent-
- * enforced start capabilities. This plugin uses named exports only; a default would hide its
+ * tools, so it shares no Cordis context and advertises no parent-enforced start capabilities;
+ * the ONE thing it reads off `request.parent` is the session's workspace cwd (see
+ * {@link resolveCwd}). This plugin uses named exports only; a default would hide its
  * loader metadata (see `docs/postmortem/0001-acp-default-export-drops-inject.md`).
  * @module @deepseek-ai/dsh-subagent-acp
  */
 
+import { accessSync, constants, statSync } from 'node:fs'
+import { isAbsolute, resolve } from 'node:path'
 import type { Context } from 'cordis'
 import z from 'schemastery'
 import type { SubagentCapabilities, SubagentProvider, SubagentStartRequest } from '@deepseek-ai/dsh-subagent'
@@ -23,8 +26,11 @@ export interface Config {
   /** Arguments passed to {@link command}. */
   args: string[]
   /**
-   * Working directory for the child process and its ACP session. Defaults to
-   * the parent process's cwd when omitted.
+   * Working directory override for the child process and its ACP session.
+   * Must be non-empty; a relative path resolves against the harness launch
+   * directory at load, and the result must be an existing directory. When
+   * omitted, each child inherits its delegating parent session's cwd — and
+   * starting one from a parent session that has no cwd fails.
    */
   cwd?: string
   /**
@@ -71,6 +77,60 @@ function assertPositiveFinite(name: string, value: number): void {
 /** The shape after schemastery applied the defaults (cwd has none). */
 type ResolvedConfig = Required<Omit<Config, 'cwd'>> & Pick<Config, 'cwd'>
 
+/**
+ * Whether `path` names an existing directory the harness can ENTER. The
+ * search-permission probe matters: `statSync().isDirectory()` is true for a
+ * mode-600 directory, but a subprocess cwd needs `X_OK` or spawn fails EACCES.
+ */
+function isDirectory(path: string): boolean {
+  try {
+    if (!statSync(path).isDirectory()) return false
+    accessSync(path, constants.X_OK)
+    return true
+  } catch {
+    // statSync/accessSync throw only filesystem access errors here
+    // (ENOENT/EACCES/ENOTDIR/…), and every one of them means the path cannot
+    // serve as the child's cwd.
+    return false
+  }
+}
+
+/**
+ * Assert `cwd` can actually host the child: absolute (it doubles as the ACP
+ * session workspace, and a relative path would be re-anchored to the server
+ * process's launch directory) and an existing directory (fail here, before the
+ * process boundary, instead of as an ambiguous spawn ENOENT).
+ * @param label - which source supplied the value, for the diagnostic.
+ * @param cwd - the candidate working directory.
+ * @returns `cwd`, validated.
+ */
+function assertUsableCwd(label: string, cwd: string): string {
+  if (!isAbsolute(cwd)) {
+    throw new Error(`subagent-acp: ${label} must be an absolute path: ${cwd}`)
+  }
+  if (!isDirectory(cwd)) {
+    throw new Error(`subagent-acp: ${label} is not an accessible directory: ${cwd}`)
+  }
+  return cwd
+}
+
+/**
+ * Resolve the child's working directory: the deployment `cwd` override when
+ * configured (already validated at load), else the parent session's workspace
+ * cwd (validated here, its earliest resolvable point). Fails loud when neither
+ * exists — falling back to the harness process cwd would silently bind the
+ * child to the server's launch directory instead of the delegating session's
+ * workspace (one server process serves many sessions, each with its own cwd).
+ */
+function resolveCwd(configured: string | undefined, request: SubagentStartRequest): string {
+  if (configured !== undefined) return configured
+  const parentCwd = request.parent.session.header.cwd
+  if (parentCwd === undefined) {
+    throw new Error('subagent-acp: no working directory for the child — configure `cwd` or delegate from a parent session that has one')
+  }
+  return assertUsableCwd('parent session cwd', parentCwd)
+}
+
 /**
  * The ACP provider. Advertises NO start-time capabilities: an out-of-process
  * child cannot honor `outputSchema`/`maxDepth`/`toolFilter` (the service rejects
@@ -87,7 +147,7 @@ class AcpProvider implements SubagentProvider {
     const spec: AcpRunSpec = {
       command: this.config.command,
       args: this.config.args,
-      cwd: this.config.cwd ?? process.cwd(),
+      cwd: resolveCwd(this.config.cwd, request),
       permission: this.config.permission,
       env: this.config.env,
       disposeEofGraceMs: this.config.disposeEofGraceMs,
@@ -107,5 +167,15 @@ export function apply(ctx: Context, config: Config): void {
   const resolved = config as ResolvedConfig
   assertPositiveFinite('disposeEofGraceMs', resolved.disposeEofGraceMs)
   assertPositiveFinite('disposeGraceMs', resolved.disposeGraceMs)
-  ctx.subagents.registerProvider(new AcpProvider(resolved.providerName, ctx, resolved))
+  // `path.resolve('')` is the process cwd — an empty string would silently
+  // reintroduce the launch-directory fallback this resolution removed.
+  if (resolved.cwd === '') {
+    throw new Error('subagent-acp: config cwd must not be empty — omit the key to inherit the parent session cwd')
+  }
+  // Interpret a relative configured cwd against the harness launch directory
+  // ONCE, at load, and fail a misconfigured directory here — not per start.
+  const validated: ResolvedConfig = resolved.cwd === undefined
+    ? resolved
+    : { ...resolved, cwd: assertUsableCwd('config cwd', resolve(resolved.cwd)) }
+  ctx.subagents.registerProvider(new AcpProvider(validated.providerName, ctx, validated))
 }

packages/subagent/subagent-acp/src/run.ts

@@ -37,7 +37,11 @@ export interface AcpRunSpec {
   command: string
   /** Arguments passed to {@link command}. */
   args: string[]
-  /** Working directory for the child process AND its ACP session `cwd`. */
+  /**
+   * Absolute working directory for the child process AND its ACP session
+   * `cwd`. The provider resolves it before this spec exists: config override,
+   * else the delegating parent session's workspace.
+   */
   cwd: string
   /** How to auto-answer the child's permission prompts. */
   permission: PermissionPolicy

packages/subagent/subagent-acp/tests/loader-composition.e2e.ts

@@ -0,0 +1,73 @@
+import { realpathSync } from 'node:fs'
+import { readFile, readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { type SessionEvent } from '@deepseek-ai/dsh-session'
+import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
+
+/**
+ * Keyless REAL-composition coverage for parent-session cwd inheritance: a
+ * test-only cordis.yml boots the headless app through the Loader with the ACP
+ * backend's `cwd` omitted, a scripted model delegates once, and the scripted
+ * mock ACP child echoes where it actually ran plus the workspace it was
+ * announced — both must be the parent session's cwd. Mock-only composition, so
+ * only this keyless tier applies (the with-key tier lives in subagent-acp.e2e.ts).
+ */
+
+const driver = fileURLToPath(new URL(
+  '../../../../examples/acp-agent/tests/fixtures/subagent/subagent-acp/driver.ts',
+  import.meta.url,
+))
+const configPath = fileURLToPath(new URL(
+  '../../../../examples/acp-agent/tests/fixtures/subagent/subagent-acp/cordis.yml',
+  import.meta.url,
+))
+const mockServer = fileURLToPath(new URL('./mock-acp-server.ts', import.meta.url))
+const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url))
+
+async function jsonlFiles(dir: string): Promise<string[]> {
+  const entries = await readdir(dir, { withFileTypes: true })
+  const paths = await Promise.all(entries.map(async (entry) => {
+    const path = join(dir, entry.name)
+    if (entry.isDirectory()) return jsonlFiles(path)
+    return entry.isFile() && entry.name.endsWith('.jsonl') ? [path] : []
+  }))
+  return paths.flat()
+}
+
+describe('ACP subagent cwd inheritance through a real cordis.yml', () => {
+  it('runs the child in the parent session workspace and announces it as the ACP session cwd', async () => {
+    let events: SessionEvent[] = []
+    let workspace = ''
+    const { stderr } = await runLoaderSmoke({
+      label: 'acp-subagent cwd composition smoke',
+      tempDirPrefix: 'acp-subagent-cwd-e2e-',
+      binScript: driver,
+      libBinScript: driver,
+      configPath,
+      tsconfigPath: repoTsconfig,
+      env: { DSH_TEST_MOCK_ACP_SERVER: mockServer },
+      inspect: async (cwd) => {
+        // The child reports realpaths; canonicalize the temp workspace to match.
+        workspace = realpathSync(cwd)
+        const logs = await jsonlFiles(join(cwd, '.sessions'))
+        expect(logs).toHaveLength(1)
+        const lines = (await readFile(logs[0] as string, 'utf8')).trimEnd().split('\n')
+        events = lines.slice(1).map(line => JSON.parse(line) as SessionEvent)
+      },
+    })
+    expect(stderr).not.toContain('UNHANDLED')
+
+    // The tool result carries the child's two-line echo: its real process.cwd()
+    // and the cwd the backend announced in `session/new` — both the parent
+    // session's workspace, never the harness process's launch directory.
+    const results = events.filter(event => event.type === 'tool/result')
+    expect(results).toHaveLength(1)
+    const resultText = results[0]!.data.content
+      .filter(block => block.type === 'text')
+      .map(block => block.text)
+      .join('')
+    expect(resultText).toBe(`${workspace}\n${workspace}`)
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+})

packages/subagent/subagent-acp/tests/mock-acp-server.ts

@@ -15,6 +15,11 @@
  *                        `dispose()` must still kill the process.
  * - `MOCK_PERMISSION`  — if `1`, the agent calls `session/request_permission`
  *                        before answering, to exercise the client's auto-answer.
+ * - `MOCK_ECHO_CWD`    — if `1`, ignore MOCK_TEXT and stream two lines instead:
+ *                        the agent PROCESS's `process.cwd()` and the `cwd` the
+ *                        client announced in `session/new` — so a test can assert
+ *                        where the child actually ran and what workspace it was
+ *                        told it has.
  * - `MOCK_READY_FILE`  — if set, the path the agent touches once its `prompt`
  *                        handler is in flight (it has streamed its chunk). A test
  *                        polls for this file to cancel on a CONDITION rather than
@@ -63,6 +68,7 @@ import {
 } from '@agentclientprotocol/sdk'
 
 const TEXT = process.env.MOCK_TEXT ?? 'mock child answer'
+const ECHO_CWD = process.env.MOCK_ECHO_CWD === '1'
 const STOP = (process.env.MOCK_STOP ?? 'end_turn') as StopReason
 const HANG = process.env.MOCK_HANG === '1'
 const WANT_PERMISSION = process.env.MOCK_PERMISSION === '1'
@@ -83,6 +89,8 @@ function makeAgent(conn: AgentSideConnection): Agent {
   // Pending cancel resolver for the HANG path: a `session/cancel` resolves the
   // prompt with `cancelled`.
   let resolveCancel: ((reason: StopReason) => void) | undefined
+  // The cwd the client announced in `session/new`, echoed under MOCK_ECHO_CWD.
+  let sessionCwd: string | undefined
 
   return {
     initialize(_params: InitializeRequest): Promise<InitializeResponse> {
@@ -92,7 +100,8 @@ function makeAgent(conn: AgentSideConnection): Agent {
         authMethods: [],
       })
     },
-    async newSession(_params: NewSessionRequest): Promise<NewSessionResponse> {
+    async newSession(params: NewSessionRequest): Promise<NewSessionResponse> {
+      sessionCwd = params.cwd
       // Optionally signal "newSession reached" and block until released, so a
       // test can cancel DURING newSession (the early-cancel race window) on a
       // condition rather than a timeout.
@@ -136,10 +145,14 @@ function makeAgent(conn: AgentSideConnection): Agent {
           update: { sessionUpdate: 'agent_thought_chunk', content: { type: 'text', text: 'thinking…' } },
         })
       }
-      // Stream the canned assistant text as one chunk.
+      // Stream the canned assistant text as one chunk (or, under MOCK_ECHO_CWD,
+      // the observable process cwd + announced session cwd).
       await conn.sessionUpdate({
         sessionId: params.sessionId,
-        update: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: TEXT } },
+        update: {
+          sessionUpdate: 'agent_message_chunk',
+          content: { type: 'text', text: ECHO_CWD ? `${process.cwd()}\n${sessionCwd ?? ''}` : TEXT },
+        },
       })
       // Signal "prompt is in flight" by touching the readiness file, so a test
       // can wait on a CONDITION (file exists) rather than an arbitrary timeout

packages/subagent/subagent-acp/tests/subagent-acp.spec.ts

@@ -1,9 +1,9 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
-import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { chmodSync, existsSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
-import { join } from 'node:path'
+import { join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import SubagentService from '@deepseek-ai/dsh-subagent'
 import { buildChildEnv } from '@deepseek-ai/dsh-subagent-subprocess'
@@ -22,8 +22,8 @@ import { acpStopReason, acpContentText, DEFAULT_DISPOSE_EOF_GRACE_MS, DEFAULT_DI
 
 const mockServer = fileURLToPath(new URL('./mock-acp-server.ts', import.meta.url))
 
-/** A throwaway parent Agent — the ACP backend ignores it, but the seam requires one. */
-const fakeParent = { id: 'parent', session: { header: {} } } as unknown as Agent
+/** A parent Agent stub. The ACP backend reads exactly one thing off it: the session header's cwd (the workspace its child inherits). */
+const fakeParent = { id: 'parent', session: { header: { cwd: process.cwd() } } } as unknown as Agent
 
 function request(text = 'p', signal = new AbortController().signal) {
   return { prompt: [{ type: 'text' as const, text }], parent: fakeParent, signal }
@@ -115,6 +115,184 @@ describe('buildChildEnv', () => {
   })
 })
 
+describe('cwd resolution', () => {
+  it('falls back to the parent session cwd for the child process AND its ACP session', async () => {
+    // realpath: on macOS `tmpdir()` sits behind a symlink (/var → /private/var),
+    // and the child reports its REAL process.cwd() — compare canonical paths.
+    const workdir = realpathSync(mkdtempSync(join(tmpdir(), 'acp-parent-cwd-')))
+    try {
+      const ctx = await setup({ MOCK_ECHO_CWD: '1' })
+      const parent = { id: 'parent', session: { header: { cwd: workdir } } } as unknown as Agent
+      const run = await ctx.subagents.start('acp', { prompt: [{ type: 'text' as const, text: 'p' }], parent, signal: new AbortController().signal })
+      const result = await run.result
+      await run.dispose()
+      // Line 1: where the child process actually ran; line 2: the workspace the
+      // backend announced in `session/new`. Both must be the parent's workspace.
+      expect(text(result.output)).toBe(`${workdir}\n${workdir}`)
+    } finally {
+      rmSync(workdir, { recursive: true, force: true })
+    }
+  })
+
+  it('rejects before spawning when neither config.cwd nor the parent session provides one', async () => {
+    const tmp = mkdtempSync(join(tmpdir(), 'acp-no-cwd-'))
+    const sentinel = join(tmp, 'spawned')
+    try {
+      const ctx = new Context()
+      await ctx.plugin(SubagentService)
+      // A command that would create the sentinel if the child were ever spawned.
+      await ctx.plugin(acp, { providerName: 'acp', command: 'touch', args: [sentinel], permission: 'reject', env: {} })
+      const parent = { id: 'parent', session: { header: {} } } as unknown as Agent
+      await expect(ctx.subagents.start('acp', { prompt: [{ type: 'text' as const, text: 'p' }], parent, signal: new AbortController().signal }))
+        .rejects.toThrow('no working directory')
+      // Resolution failed BEFORE the process boundary — nothing was launched.
+      expect(existsSync(sentinel)).toBe(false)
+    } finally {
+      rmSync(tmp, { recursive: true, force: true })
+    }
+  })
+
+  it('prefers the configured cwd override to the parent session cwd', async () => {
+    const configured = realpathSync(mkdtempSync(join(tmpdir(), 'acp-cfg-cwd-')))
+    const parentDir = realpathSync(mkdtempSync(join(tmpdir(), 'acp-parent-cwd-')))
+    try {
+      const ctx = new Context()
+      await ctx.plugin(SubagentService)
+      await ctx.plugin(acp, {
+        providerName: 'acp',
+        command: process.execPath,
+        args: [mockServer],
+        cwd: configured,
+        permission: 'reject',
+        env: { MOCK_ECHO_CWD: '1' },
+      })
+      const parent = { id: 'parent', session: { header: { cwd: parentDir } } } as unknown as Agent
+      const run = await ctx.subagents.start('acp', { prompt: [{ type: 'text' as const, text: 'p' }], parent, signal: new AbortController().signal })
+      const result = await run.result
+      await run.dispose()
+      expect(text(result.output)).toBe(`${configured}\n${configured}`)
+    } finally {
+      rmSync(configured, { recursive: true, force: true })
+      rmSync(parentDir, { recursive: true, force: true })
+    }
+  })
+
+  it('resolves a relative config cwd against the launch directory at load', async () => {
+    // The child process AND its announced ACP session cwd must both get the
+    // ABSOLUTE form — DSH's own ACP server rejects a relative session cwd, and
+    // deferring resolution to spawn would hide the launch-dir dependency.
+    const relative = 'packages/subagent/subagent-acp'
+    const absolute = resolve(relative)
+    const ctx = new Context()
+    await ctx.plugin(SubagentService)
+    await ctx.plugin(acp, {
+      providerName: 'acp',
+      command: process.execPath,
+      args: [mockServer],
+      cwd: relative,
+      permission: 'reject',
+      env: { MOCK_ECHO_CWD: '1' },
+    })
+    const run = await ctx.subagents.start('acp', request())
+    const result = await run.result
+    await run.dispose()
+    expect(text(result.output)).toBe(`${realpathSync(absolute)}\n${absolute}`)
+  })
+
+  it('rejects an empty config cwd at load', async () => {
+    // `path.resolve('')` is the process cwd, so an empty string would silently
+    // reintroduce the launch-directory fallback this resolution removed.
+    const ctx = new Context()
+    await ctx.plugin(SubagentService)
+    await expect(ctx.plugin(acp, {
+      providerName: 'acp',
+      command: 'true',
+      args: [],
+      cwd: '',
+      permission: 'reject',
+      env: {},
+    })).rejects.toThrow('config cwd must not be empty')
+    await ctx.fiber.dispose()
+  })
+
+  it('rejects a config cwd directory without search permission at load', async () => {
+    // statSync().isDirectory() is true for a mode-600 directory, but a
+    // subprocess cwd needs SEARCH permission — spawn would fail EACCES.
+    const tmp = mkdtempSync(join(tmpdir(), 'acp-noexec-'))
+    chmodSync(tmp, 0o600)
+    try {
+      const ctx = new Context()
+      await ctx.plugin(SubagentService)
+      await expect(ctx.plugin(acp, {
+        providerName: 'acp',
+        command: 'true',
+        args: [],
+        cwd: tmp,
+        permission: 'reject',
+        env: {},
+      })).rejects.toThrow('not an accessible directory')
+      await ctx.fiber.dispose()
+    } finally {
+      chmodSync(tmp, 0o700)
+      rmSync(tmp, { recursive: true, force: true })
+    }
+  })
+
+  it('rejects a config cwd that is not an accessible directory at load', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SubagentService)
+    await expect(ctx.plugin(acp, {
+      providerName: 'acp',
+      command: 'true',
+      args: [],
+      cwd: '/nonexistent/acp-child-workspace',
+      permission: 'reject',
+      env: {},
+    })).rejects.toThrow('not an accessible directory')
+    await ctx.fiber.dispose()
+  })
+
+  it('rejects a parent session cwd that is not absolute', async () => {
+    // SessionHeader documents cwd as absolute; a relative value here is a broken
+    // header, and resolving it against the server process cwd would silently
+    // re-introduce the launch-directory dependency this resolution removes.
+    const ctx = await setup({})
+    const parent = { id: 'parent', session: { header: { cwd: 'relative/workspace' } } } as unknown as Agent
+    await expect(ctx.subagents.start('acp', { prompt: [{ type: 'text' as const, text: 'p' }], parent, signal: new AbortController().signal }))
+      .rejects.toThrow('must be an absolute path')
+  })
+
+  it('rejects a parent session cwd that names a FILE, not a directory', async () => {
+    const tmp = mkdtempSync(join(tmpdir(), 'acp-file-cwd-'))
+    const file = join(tmp, 'a-file')
+    writeFileSync(file, 'x')
+    try {
+      const ctx = await setup({})
+      const parent = { id: 'parent', session: { header: { cwd: file } } } as unknown as Agent
+      await expect(ctx.subagents.start('acp', { prompt: [{ type: 'text' as const, text: 'p' }], parent, signal: new AbortController().signal }))
+        .rejects.toThrow('not an accessible directory')
+    } finally {
+      rmSync(tmp, { recursive: true, force: true })
+    }
+  })
+
+  it('rejects a parent session cwd that is not an accessible directory, before spawning', async () => {
+    const tmp = mkdtempSync(join(tmpdir(), 'acp-bad-parent-cwd-'))
+    const sentinel = join(tmp, 'spawned')
+    try {
+      const ctx = new Context()
+      await ctx.plugin(SubagentService)
+      await ctx.plugin(acp, { providerName: 'acp', command: 'touch', args: [sentinel], permission: 'reject', env: {} })
+      const parent = { id: 'parent', session: { header: { cwd: join(tmp, 'vanished') } } } as unknown as Agent
+      await expect(ctx.subagents.start('acp', { prompt: [{ type: 'text' as const, text: 'p' }], parent, signal: new AbortController().signal }))
+        .rejects.toThrow('not an accessible directory')
+      expect(existsSync(sentinel)).toBe(false)
+    } finally {
+      rmSync(tmp, { recursive: true, force: true })
+    }
+  })
+})
+
 describe('dsh-subagent-acp', () => {
   it('drives child processes with parent-unique run ids and returns streamed output', async () => {
     const ctx = await setup({ MOCK_TEXT: 'hello from acp child', MOCK_STOP: 'end_turn', MOCK_SESSION_ID: 'acp-child-session' })

packages/subagent/subagent/src/types.ts

@@ -56,7 +56,10 @@ export interface SubagentStartRequest {
    * The spawning ("parent") agent — the one whose tool call started this
    * subagent. REQUIRED: in-process backends read `parent.session.header` for
    * the working directory, the `parentSession` lineage to stamp on the child,
-   * and the parent's delegation depth. Out-of-process backends (ACP) ignore it.
+   * and the parent's delegation depth. The out-of-process backend (ACP) reads
+   * exactly one field — the session header's cwd, the child's workspace when
+   * no deployment `cwd` override is configured; nothing else crosses the
+   * process boundary.
    */
   readonly parent: Agent
   /**

packages/ui/acp/src/index.ts

@@ -44,10 +44,15 @@ import {
   type Stream,
   type StopReason,
 } from '@agentclientprotocol/sdk'
-import type { ContentBlock, LlmCallConfig, LlmModelInfo, LlmProviderInfo } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock, LlmModelInfo, LlmProviderInfo } from '@deepseek-ai/dsh-llm'
 import { assertNever, CallId } from '@deepseek-ai/dsh-llm'
 import type {} from '@deepseek-ai/dsh-llm-retry'
-import type { Agent } from '@deepseek-ai/dsh-agent'
+import {
+  installAgentLlmTarget,
+  type Agent,
+  type AgentLlmTarget as LlmTarget,
+  type AgentLlmTargetRef as LlmTargetRef,
+} from '@deepseek-ai/dsh-agent'
 import type {} from '@deepseek-ai/dsh-commands'
 import { SessionId } from '@deepseek-ai/dsh-session'
 // Side-effect type import: resolves `ctx.get('permission')` to the service.
@@ -258,19 +263,6 @@ export const Config: Schema<AcpConfig> = Schema.object({
   model: Schema.string(),
 })
 
-/** Provider/model pair selected for one ACP session. */
-interface LlmTarget {
-  provider: string
-  model: string
-}
-
-/** Mutable target shared by one agent's scoped assembly and request listeners. */
-interface LlmTargetRef {
-  current: LlmTarget | undefined
-  /** Step snapshot captured by prompt assembly so target switches cannot split prompt and request. */
-  assembled: LlmTarget | undefined
-}
-
 /** One resolved ACP model selector plus its opaque value lookup. */
 interface ModelDirectory {
   option: Extract<SessionConfigOption, { type: 'select' }> | undefined
@@ -338,32 +330,7 @@ export function apply(ctx: Context, config: AcpConfig): void {
     const logged = agent.session.requestHeader()?.config
     if (logged !== undefined) target.current = { provider: logged.provider, model: logged.model }
 
-    // Capture once at assembly entry and apply the same pair after downstream
-    // prompt listeners. A selector change during async assembly therefore takes
-    // effect on the following step instead of splitting {{model}} from routing.
-    agentCtx.on('system-prompt/assemble', async (_assembly, _context, next) => {
-      const selected = target.current
-      const assembled = await next()
-      target.assembled = selected
-      if (selected === undefined) return assembled
-      return {
-        ...assembled,
-        variables: {
-          ...assembled.variables,
-          provider: selected.provider,
-          model: selected.model,
-        },
-      }
-    })
-    agentCtx.on('agent/request', async (_agent, _turn, _step, _callConfig, next): Promise<LlmCallConfig> => {
-      const resolved = await next()
-      const selected = target.assembled
-      return selected === undefined ? resolved : {
-        ...resolved,
-        provider: selected.provider,
-        model: selected.model,
-      }
-    })
+    installAgentLlmTarget(agentCtx, target)
   }
 
   /** Opaque ACP value preserving both routing dimensions. */

packages/ui/tui/README.md

@@ -6,13 +6,15 @@ The implemented [TUI feature Agent Note](../../../.agents/notes/implemented/feat
 
 Interactive terminals on macOS, Linux, and Windows are supported. Windows uses pi-tui's native console VT-input handling, and the [Windows support Agent Note](../../../.agents/notes/implemented/feature/2026-07-20-windows-tui-support.md) owns the platform decision and ConPTY process verification.
 
-This package owns interactive terminal presentation and input only. It injects `agents`, [`commands`](../commands/README.md), `tools`, and `userInteraction`, then drives an agent created or resumed by app or developer code. Agent lifecycle, persistence, and the model-facing [`ask_user_question`](../tool-ask-user/README.md) tool remain separate composition entries.
+This package owns interactive terminal presentation and input only. It injects `agents`, [`commands`](../commands/README.md), `llm`, `systemPrompt`, `tokenMeter`, `tools`, and `userInteraction`, then drives an agent created or resumed by app or developer code. Agent lifecycle, persistence, and the model-facing [`ask_user_question`](../tool-ask-user/README.md) tool remain separate composition entries.
 
-The TUI rebuilds resumed history from the active session surface, renders Markdown responses and reasoning, applies each tool's `presentCall` / `presentResult` intent to terminal, diff, or generic cards, keeps the latest `todo/write` plan above the editor, and presents `ctx.userInteraction` questions as keyboard-driven overlays. A durable `llm/retry` event retracts the failed step's live chunks and renders the scheduled retry count, delay, and failure in the transcript; success, exhaustion, and cancellation then settle through ordinary session events. The footer totals each logged model step's usage once, including failed attempts, while treating committed-message usage as a fallback for logs without a usage chunk. Surface replacement events rebuild the transcript so compacted history does not reappear.
+The TUI rebuilds resumed history from the active session surface, renders Markdown responses and reasoning, applies each tool's `presentCall` / `presentResult` intent to terminal, diff, or generic cards, keeps the latest `todo/write` plan above the editor, and presents `ctx.userInteraction` questions in a wide bottom-left keyboard panel with progress, numbered options, and aligned descriptions. A durable `llm/retry` event retracts the failed step's live chunks and renders the scheduled retry count, delay, and failure in the transcript; success, exhaustion, and cancellation then settle through ordinary session events. The footer totals each logged model step's usage once, including failed attempts, while treating committed-message usage as a fallback for logs without a usage chunk. Its idle view shows token-meter context occupancy, tool-card mode, and the current model with reasoning state; while the agent runs, an elapsed working indicator and `esc interrupt` replace that summary. Surface replacement events rebuild the transcript so compacted history does not reappear.
 
 Before model output, session events, tool presenters, questions, configuration, or diagnostics reach pi-tui's ANSI-aware renderers or the terminal title, the TUI renders C0 and C1 controls other than line feeds as visible `\xNN` text. Those sources cannot add terminal control sequences; the TUI and pi-tui retain ownership of terminal rendering and styling.
 
-While the agent is running, ordinary editor submissions call `agent.steer()`; otherwise they call `agent.send()`. A slash at the start of the submitted line enters `ctx.commands` instead: known commands execute directly, unknown commands produce a warning, and neither path reaches the model. The TUI registers `/help`, `/clear`, `/cancel`, `/reasoning`, `/tools`, `/redraw`, and `/exit` as agent-scoped definitions; every other effective command joins autocomplete and `/help` dynamically. Ctrl+C or Escape cancels a running turn. Ctrl+O expands tool cards, Ctrl+R toggles reasoning, Ctrl+L redraws, and Ctrl+D exits while idle.
+While the agent is running, ordinary editor submissions call `agent.steer()`; otherwise they call `agent.send()`. A slash at the start of the submitted line enters `ctx.commands` instead: known commands execute directly, unknown commands produce a warning, and neither path reaches the model. The TUI registers `/help`, `/model`, `/clear`, `/cancel`, `/reasoning`, `/tools`, `/redraw`, and `/exit` as agent-scoped definitions; every other effective command joins autocomplete and `/help` dynamically. Ctrl+C or Escape cancels a running turn. Tool cards collapse long bodies into a configurable head/tail preview; Ctrl+O toggles every card between its preview and full output. Ctrl+R toggles reasoning, Ctrl+L redraws, and Ctrl+D exits while idle.
+
+`/model` opens the advisory `ctx.llm` catalog as a keyboard selector: Up/Down moves, Enter selects, and Escape closes it. `/model <model>` still selects an unambiguous model id directly, while `/model <provider>/<model>` selects an exact target. The configured target or latest logged request header initializes the selector, and an unlisted current model remains visible because catalogs are advisory. Selection is local to this TUI session. Prompt assembly snapshots the target for one step, replaces `{{provider}}` and `{{model}}`, and applies the same pair through `agent/request`; a switch during assembly therefore starts with a later step. The request header durably records targets that reach the model, while an unused selection remains process-local.
 
 ## Config
 
@@ -21,10 +23,13 @@ While the agent is running, ordinary editor submissions call `agent.steer()`; ot
 | `welcome` | `ready.` | Header subtitle |
 | `sessionId` | `main` | Exact shared agent/session identity driven by the terminal |
 | `showReasoning` | `true` | Render reasoning blocks |
-| `maxToolOutputLines` | `12` | Collapsed tool-card output limit |
-| `maxQuestionOptions` | `8` | Visible options in a question overlay |
-| `questionDialogWidth` | `72` | Question-overlay width in columns |
-| `questionDialogMaxHeight` | `20` | Question-overlay maximum rows |
+| `maxToolOutputLines` | `6` | Output lines retained across a collapsed tool card's head/tail preview |
+| `maxQuestionOptions` | `8` | Visible options in a question panel |
+| `maxModelOptions` | `8` | Visible models in the model selector |
+| `questionDialogWidth` | `200` | Question-panel width in columns, clamped to the terminal |
+| `questionDialogMaxHeight` | `20` | Question-panel maximum rows |
+| `modelDialogWidth` | `72` | Model-selector width in columns |
+| `modelDialogMaxHeight` | `20` | Model-selector maximum rows |
 | `showHardwareCursor` | `false` | Show the hardware cursor at pi-tui's IME marker |
 | `color` | `true` | Apply the built-in ANSI palette (see [Color](#color)) |
 | `title` | `DeepSeek Harness` | Terminal window title |
@@ -36,14 +41,14 @@ While the agent is running, ordinary editor submissions call `agent.steer()`; ot
     welcome: 'Coding agent ready.'
     sessionId: main-session-123
     showReasoning: true
-    maxToolOutputLines: 12
+    maxToolOutputLines: 6
 ```
 
 Startup fails before mounting when either process stream is not a TTY. The composing app must mount the TUI before its config-created agent so the front door can observe `agent-loop/config-start-failed`; a matching exact-session failure is written before fullscreen mode starts and exits with status 1 instead of leaving a blank terminal. Disposal aborts running commands, removes the TUI definitions, stops loaders, rejects pending questions, drains terminal input, restores terminal state, unregisters event listeners and the user-interaction provider, and never exits a replacement process during HMR.
 
 ## Color
 
-The palette uses the standard 16-color ANSI foregrounds and SGR attributes, which every terminal remaps to its active color scheme, so it stays readable on light and dark backgrounds alike. Body text keeps the terminal's default foreground rather than a fixed shade. Grouped regions (user prompts, tool cards) use a colored left-gutter bar instead of a filled background block, and the question overlay's active row uses reverse video; both are foreground-only, so they never collide with the terminal background. Set `color: false` to strip all styling.
+The palette uses the standard 16-color ANSI foregrounds and SGR attributes, which every terminal remaps to its active color scheme, so it stays readable on light and dark backgrounds alike. Body text keeps the terminal's default foreground rather than a fixed shade. Grouped regions (user prompts, tool cards) use a colored left-gutter bar instead of a filled background block; the question panel emphasizes its active row with bold accent text, while selectors use reverse video. These treatments are foreground-only, so they never collide with the terminal background. Set `color: false` to strip all styling.
 
 ## Model Experience
 
@@ -61,6 +66,20 @@ Submitted text is retained under the agent loop's normal session-history and com
 
 Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
 
+### Session model selection
+
+#### What the model sees
+
+The `/model` command text and keyboard-selector input are not logged or sent. New steps receive the selected provider/model pair in both prompt variables and request routing.
+
+#### Token effect
+
+The selector adds no messages. A target change may alter interpolated system-prompt text and sends subsequent requests to the selected model.
+
+#### KV Cache effect
+
+Changing provider or model enters that target's cache domain; no cache reuse across distinct targets is assumed.
+
 ### Interactive user-question answers
 
 #### What the model sees

packages/ui/tui/package.json

@@ -28,6 +28,8 @@
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-llm-retry": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
+    "@deepseek-ai/dsh-token-meter": "^0.0.1",
     "@deepseek-ai/dsh-tools": "^0.0.1",
     "@deepseek-ai/dsh-user-interaction": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
@@ -45,6 +47,7 @@
     "@deepseek-ai/dsh-llm-retry": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-token-meter": "workspace:^",
     "@deepseek-ai/dsh-tool-cordis": "workspace:^",
     "@deepseek-ai/dsh-tool-workflow": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",

packages/ui/tui/src/index.ts

@@ -13,12 +13,12 @@ import {
   Editor,
   Input,
   Key,
-  Loader,
   Markdown,
   Spacer,
   Text,
   TUI,
   ProcessTerminal,
+  SelectList,
   matchesKey,
   truncateToWidth,
   visibleWidth,
@@ -33,11 +33,23 @@ import {
 } from '@earendil-works/pi-tui'
 import type { Context } from 'cordis'
 import z from 'schemastery'
-import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent'
+import {
+  installAgentLlmTarget,
+  type Agent,
+  type AgentLlmTarget,
+  type AgentLlmTargetRef,
+  type AgentStatus,
+} from '@deepseek-ai/dsh-agent'
 import type {} from '@deepseek-ai/dsh-agent-loop'
+import type {} from '@deepseek-ai/dsh-token-meter'
 import type {} from '@deepseek-ai/dsh-commands'
 import { errorChain } from '@deepseek-ai/dsh-llm'
-import type { ContentBlock, StreamChunk, TokenUsage } from '@deepseek-ai/dsh-llm'
+import type {
+  ContentBlock,
+  LlmModelInfo,
+  StreamChunk,
+  TokenUsage,
+} from '@deepseek-ai/dsh-llm'
 import type {} from '@deepseek-ai/dsh-llm-retry'
 import { SessionId, type Session, type SessionEvent, type TodoItem } from '@deepseek-ai/dsh-session'
 import type {
@@ -56,20 +68,26 @@ import {
 } from '@deepseek-ai/dsh-user-interaction'
 
 export const name = 'ui-tui'
-export const inject = ['agents', 'commands', 'userInteraction', 'tools']
+export const inject = ['agents', 'commands', 'userInteraction', 'tools', 'llm', 'systemPrompt', 'tokenMeter']
 
 /** Presentation settings for the pi-tui terminal mode. */
 export interface TuiConfig {
   /** Render model reasoning blocks. */
   showReasoning?: boolean
-  /** Maximum tool-output lines shown before the card is collapsed. */
+  /** Maximum tool-card body lines retained in its collapsed head/tail preview. */
   maxToolOutputLines?: number
-  /** Maximum options visible at once in a user-question dialog. */
+  /** Maximum options visible at once in a user-question panel. */
   maxQuestionOptions?: number
-  /** User-question dialog width in terminal columns. */
+  /** Maximum models visible at once in the model selector. */
+  maxModelOptions?: number
+  /** User-question panel width in terminal columns, clamped to the terminal. */
   questionDialogWidth?: number
-  /** User-question dialog maximum height in terminal rows. */
+  /** User-question panel maximum height in terminal rows. */
   questionDialogMaxHeight?: number
+  /** Model-selector width in terminal columns. */
+  modelDialogWidth?: number
+  /** Model-selector maximum height in terminal rows. */
+  modelDialogMaxHeight?: number
   /** Show the terminal's hardware cursor at the pi editor's IME marker. */
   showHardwareCursor?: boolean
   /** Apply the built-in ANSI color palette. */
@@ -79,10 +97,13 @@ export interface TuiConfig {
 }
 
 const showReasoningSchema = z.boolean().default(true)
-const maxToolOutputLinesSchema = z.number().step(1).min(1).default(12)
+const maxToolOutputLinesSchema = z.number().step(1).min(1).default(6)
 const maxQuestionOptionsSchema = z.number().step(1).min(1).default(8)
-const questionDialogWidthSchema = z.number().step(1).min(20).default(72)
+const maxModelOptionsSchema = z.number().step(1).min(1).default(8)
+const questionDialogWidthSchema = z.number().step(1).min(20).default(200)
 const questionDialogMaxHeightSchema = z.number().step(1).min(6).default(20)
+const modelDialogWidthSchema = z.number().step(1).min(20).default(72)
+const modelDialogMaxHeightSchema = z.number().step(1).min(6).default(20)
 const showHardwareCursorSchema = z.boolean().default(false)
 const colorSchema = z.boolean().default(true)
 const titleSchema = z.string().default('DeepSeek Harness')
@@ -92,8 +113,11 @@ export const TuiConfigSchema: z<TuiConfig> = z.object({
   showReasoning: showReasoningSchema,
   maxToolOutputLines: maxToolOutputLinesSchema,
   maxQuestionOptions: maxQuestionOptionsSchema,
+  maxModelOptions: maxModelOptionsSchema,
   questionDialogWidth: questionDialogWidthSchema,
   questionDialogMaxHeight: questionDialogMaxHeightSchema,
+  modelDialogWidth: modelDialogWidthSchema,
+  modelDialogMaxHeight: modelDialogMaxHeightSchema,
   showHardwareCursor: showHardwareCursorSchema,
   color: colorSchema,
   title: titleSchema,
@@ -113,8 +137,11 @@ export const Config: z<Config> = z.object({
   showReasoning: showReasoningSchema,
   maxToolOutputLines: maxToolOutputLinesSchema,
   maxQuestionOptions: maxQuestionOptionsSchema,
+  maxModelOptions: maxModelOptionsSchema,
   questionDialogWidth: questionDialogWidthSchema,
   questionDialogMaxHeight: questionDialogMaxHeightSchema,
+  modelDialogWidth: modelDialogWidthSchema,
+  modelDialogMaxHeight: modelDialogMaxHeightSchema,
   showHardwareCursor: showHardwareCursorSchema,
   color: colorSchema,
   title: titleSchema,
@@ -125,8 +152,11 @@ export interface ResolvedTuiConfig {
   showReasoning: boolean
   maxToolOutputLines: number
   maxQuestionOptions: number
+  maxModelOptions: number
   questionDialogWidth: number
   questionDialogMaxHeight: number
+  modelDialogWidth: number
+  modelDialogMaxHeight: number
   showHardwareCursor: boolean
   color: boolean
   title: string
@@ -138,6 +168,8 @@ export interface TuiRuntime {
   terminal: Terminal
   /** Exit hook used by terminal shutdown or a target-agent startup failure. */
   exit(code: number): void
+  /** Monotonic-enough wall clock for elapsed status rendering. Defaults to `Date.now`. */
+  now?(): number
 }
 
 /**
@@ -149,10 +181,13 @@ export interface TuiRuntime {
 export function resolveTuiConfig(config: TuiConfig | undefined): ResolvedTuiConfig {
   return {
     showReasoning: config?.showReasoning ?? true,
-    maxToolOutputLines: config?.maxToolOutputLines ?? 12,
+    maxToolOutputLines: config?.maxToolOutputLines ?? 6,
     maxQuestionOptions: config?.maxQuestionOptions ?? 8,
-    questionDialogWidth: config?.questionDialogWidth ?? 72,
+    maxModelOptions: config?.maxModelOptions ?? 8,
+    questionDialogWidth: config?.questionDialogWidth ?? 200,
     questionDialogMaxHeight: config?.questionDialogMaxHeight ?? 20,
+    modelDialogWidth: config?.modelDialogWidth ?? 72,
+    modelDialogMaxHeight: config?.modelDialogMaxHeight ?? 20,
     showHardwareCursor: config?.showHardwareCursor ?? false,
     color: config?.color ?? true,
     title: config?.title ?? 'DeepSeek Harness',
@@ -253,6 +288,13 @@ function selectTheme(palette: Palette): SelectListTheme {
   }
 }
 
+function dialogSelectTheme(palette: Palette): SelectListTheme {
+  return {
+    ...selectTheme(palette),
+    selectedText: text => palette.selected(palette.accent(text)),
+  }
+}
+
 function contentText(content: readonly ContentBlock[]): string {
   const parts: string[] = []
   for (const block of content) {
@@ -284,11 +326,52 @@ function textBlocks(content: readonly ContentBlock[], type: 'text' | 'reasoning'
     .join('\n\n')
 }
 
+interface ModelChoice extends AgentLlmTarget {
+  modelName: string
+  description?: string
+}
+
+function targetLabel(target: AgentLlmTarget): string {
+  return `${target.provider}/${target.model}`
+}
+
+function initialTarget(agent: Agent): AgentLlmTarget | undefined {
+  const logged = agent.session.requestHeader()?.config
+  if (logged !== undefined) return { provider: logged.provider, model: logged.model }
+  if (agent.options.provider === undefined || agent.options.model === undefined) return undefined
+  return { provider: agent.options.provider, model: agent.options.model }
+}
+
+async function readModelChoices(
+  ctx: Context,
+  current: AgentLlmTarget | undefined,
+): Promise<ModelChoice[]> {
+  const providers = ctx.llm.listProviders()
+  const groups = await Promise.all(providers.map(async (provider) => {
+    const advertised = await ctx.llm.listModels(provider.id)
+    const models: LlmModelInfo[] = [...advertised]
+    if (
+      current?.provider === provider.id
+      && !models.some(model => model.id === current.model)
+    ) {
+      models.push({ provider: provider.id, id: current.model, name: current.model })
+    }
+    return models.map((model): ModelChoice => ({
+      provider: provider.id,
+      model: model.id,
+      modelName: model.name,
+      ...model.description === undefined ? {} : { description: model.description },
+    }))
+  }))
+  return groups.flat()
+}
+
 class HeaderComponent implements Component {
   constructor(
     private readonly agent: Agent,
     private readonly welcome: string,
     private readonly palette: Palette,
+    private readonly currentModel: () => string | undefined,
   ) {}
 
   invalidate(): void {}
@@ -296,7 +379,7 @@ class HeaderComponent implements Component {
   render(width: number): string[] {
     const usable = Math.max(1, width - 4)
     const title = `${this.palette.bold(this.palette.accent('DEEPSEEK'))} ${this.palette.bold('HARNESS')}`
-    const model = displayText(this.agent.options.model ?? 'model unset')
+    const model = displayText(this.currentModel() ?? 'model unset')
     const detail = `${model}  •  ${displayText(this.agent.session.id)}`
     const top = this.palette.accent(`╭${'─'.repeat(Math.max(0, width - 2))}╮`)
     const bottom = this.palette.accent(`╰${'─'.repeat(Math.max(0, width - 2))}╯`)
@@ -508,9 +591,15 @@ class ToolCardComponent implements Component {
     const glyph = this.result === undefined ? this.palette.warning('◌') : isError ? this.palette.error('✕') : this.palette.success('✓')
     const body = this.renderBody()
     const title = truncateToWidth(`${glyph} ${displayText(this.title())}`, Math.max(1, width - 4), '')
+    const headLines = Math.ceil(this.maxOutputLines / 2)
+    const tailLines = this.maxOutputLines - headLines
     const visibleBody = this.expanded || body.length <= this.maxOutputLines
       ? body
-      : [...body.slice(0, this.maxOutputLines), this.palette.dim(`… ${body.length - this.maxOutputLines} more lines (Ctrl+O to expand)`)]
+      : [
+        ...body.slice(0, headLines),
+        this.palette.dim(`… +${body.length - this.maxOutputLines} lines (Ctrl+O to expand)`),
+        ...body.slice(body.length - tailLines),
+      ]
     const barFn = this.result === undefined
       ? this.palette.warning
       : isError ? this.palette.error : this.palette.success
@@ -647,19 +736,40 @@ class FooterComponent implements Component {
     private readonly toolsExpanded: () => boolean,
     private readonly showReasoning: () => boolean,
     private readonly tokens: () => { input: number; output: number },
+    private readonly currentModel: () => string | undefined,
+    private readonly contextPercent: () => number,
+    private readonly runningSeconds: () => number,
   ) {}
 
   invalidate(): void {}
 
   render(width: number): string[] {
+    if (this.agent.status === 'running') {
+      const interrupt = this.palette.dim('esc interrupt')
+      const activityAvailable = Math.max(0, width - visibleWidth(interrupt) - 1)
+      const activity = truncateToWidth(this.palette.accent(`◒ Working · ${this.runningSeconds()}s`), activityAvailable, '')
+      const gap = ' '.repeat(Math.max(0, width - visibleWidth(activity) - visibleWidth(interrupt)))
+      return [`${activity}${gap}${interrupt}`]
+    }
     const { input, output } = this.tokens()
-    const left = `${formatCwd(this.agent.session.header.cwd)}  ↑${formatTokens(input)} ↓${formatTokens(output)}`
-    const right = `${this.agent.status}  reasoning:${this.showReasoning() ? 'on' : 'off'}  tools:${this.toolsExpanded() ? 'expanded' : 'compact'}`
-    const leftStyled = this.palette.dim(left)
-    const available = Math.max(0, width - visibleWidth(left) - 2)
-    const rightClipped = truncateToWidth(right, available, '')
-    const gap = ' '.repeat(Math.max(1, width - visibleWidth(left) - visibleWidth(rightClipped)))
-    return [truncateToWidth(`${leftStyled}${gap}${this.palette.dim(rightClipped)}`, width, '')]
+    const counters = `↑${formatTokens(input)} ↓${formatTokens(output)}`
+    const model = displayText(this.currentModel() ?? 'model unset')
+    const modelState = `${model}(reasoning:${this.showReasoning() ? 'on' : 'off'})`
+    const context = `${this.contextPercent()}% context`
+    const fullRight = `${context}  tools:${this.toolsExpanded() ? 'expanded' : 'compact'}  ${modelState}`
+    const compactRight = `${context}  ${modelState}`
+    if (visibleWidth(counters) + visibleWidth(compactRight) + 1 > width) {
+      const compact = truncateToWidth(compactRight, width, '')
+      return [`${' '.repeat(Math.max(0, width - visibleWidth(compact)))}${this.palette.dim(compact)}`]
+    }
+    const rightAvailable = width - visibleWidth(counters) - 1
+    const right = visibleWidth(fullRight) <= rightAvailable ? fullRight : compactRight
+    const rightClipped = truncateToWidth(right, rightAvailable, '')
+    const cwdAvailable = Math.max(0, width - visibleWidth(counters) - visibleWidth(rightClipped) - 3)
+    const cwd = truncateToWidth(formatCwd(this.agent.session.header.cwd), cwdAvailable, '')
+    const left = [cwd, counters].filter(Boolean).join('  ')
+    const gap = ' '.repeat(Math.max(0, width - visibleWidth(left) - visibleWidth(rightClipped)))
+    return [`${this.palette.dim(left)}${gap}${this.palette.dim(rightClipped)}`]
   }
 }
 
@@ -668,6 +778,76 @@ interface QuestionSelection {
   custom?: string
 }
 
+function renderDialog(
+  title: string,
+  body: readonly string[],
+  width: number,
+  palette: Palette,
+): string[] {
+  const innerWidth = Math.max(1, width - 4)
+  const topLabel = ` ${displayText(title)} `
+  const top = `╭${topLabel}${'─'.repeat(Math.max(0, width - visibleWidth(topLabel) - 2))}╮`
+  const lines: string[] = [palette.accent(top)]
+  for (const line of body) {
+    const clipped = truncateToWidth(line, innerWidth, '')
+    lines.push(`${palette.accent('│')} ${clipped}${' '.repeat(Math.max(0, innerWidth - visibleWidth(clipped)))} ${palette.accent('│')}`)
+  }
+  lines.push(palette.accent(`╰${'─'.repeat(Math.max(0, width - 2))}╯`))
+  return lines
+}
+
+class ModelDialog implements Component {
+  private readonly list: SelectList
+
+  constructor(
+    choices: readonly ModelChoice[],
+    current: AgentLlmTarget | undefined,
+    maxVisible: number,
+    private readonly palette: Palette,
+    done: (choice: ModelChoice) => void,
+    cancel: () => void,
+  ) {
+    this.list = new SelectList(choices.map(choice => ({
+      value: targetLabel(choice),
+      label: displayText(targetLabel(choice)),
+      description: [
+        displayText(choice.modelName),
+        ...choice.description === undefined ? [] : [displayText(choice.description)],
+        ...current?.provider === choice.provider && current.model === choice.model ? ['current'] : [],
+      ].join(' — '),
+    })), maxVisible, dialogSelectTheme(palette))
+    const currentIndex = current === undefined
+      ? 0
+      : choices.findIndex(choice => choice.provider === current.provider && choice.model === current.model)
+    this.list.setSelectedIndex(currentIndex)
+    this.list.onSelect = (item) => {
+      const selected = choices.find(choice => targetLabel(choice) === item.value)
+      /* v8 ignore next -- SelectList only returns values built from `choices`. */
+      if (selected === undefined) return
+      done(selected)
+    }
+    this.list.onCancel = cancel
+  }
+
+  invalidate(): void {
+    this.list.invalidate()
+  }
+
+  handleInput(data: string): void {
+    this.list.handleInput(data)
+    this.invalidate()
+  }
+
+  render(width: number): string[] {
+    const innerWidth = Math.max(1, width - 4)
+    return renderDialog('Select model', [
+      ...this.list.render(innerWidth),
+      '',
+      this.palette.dim('↑/↓ navigate • Enter select • Esc cancel'),
+    ], width, this.palette)
+  }
+}
+
 class QuestionDialog implements Component, Focusable {
   private selectedIndex = 0
   private selected = new Set<number>()
@@ -679,6 +859,9 @@ class QuestionDialog implements Component, Focusable {
 
   constructor(
     private readonly question: AskUserQuestionItem,
+    private readonly position: number,
+    private readonly total: number,
+    private readonly unanswered: number,
     private readonly maxVisible: number,
     private readonly palette: Palette,
     private readonly done: (selection: QuestionSelection) => void,
@@ -719,11 +902,11 @@ class QuestionDialog implements Component, Focusable {
     } else if (matchesKey(data, Key.enter)) {
       const indices = this.question.multiSelect ? [...this.selected].sort((a, b) => a - b) : [this.selectedIndex]
       if (indices.length === 0) {
-        this.error = 'Select at least one option, or press C for a custom answer.'
+        this.error = 'Select at least one option, or press Tab for a custom answer.'
         return
       }
       this.done({ selected: indices.map(index => options[index]?.label).filter((label): label is string => label !== undefined) })
-    } else if (data.toLowerCase() === 'c') {
+    } else if (matchesKey(data, Key.tab) || data.toLowerCase() === 'c') {
       this.mode = 'custom'
       this.error = ''
     } else if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl('c'))) {
@@ -743,16 +926,13 @@ class QuestionDialog implements Component, Focusable {
   render(width: number): string[] {
     this.input.focused = this.focused
     const innerWidth = Math.max(1, width - 4)
-    const title = displayText(this.question.header ?? 'Question')
-    const topLabel = ` ${title} `
-    const top = `╭${topLabel}${'─'.repeat(Math.max(0, width - visibleWidth(topLabel) - 2))}╮`
-    const lines: string[] = [this.palette.accent(top)]
-    const push = (line: string): void => {
-      const clipped = truncateToWidth(line, innerWidth, '')
-      lines.push(`${this.palette.accent('│')} ${clipped}${' '.repeat(Math.max(0, innerWidth - visibleWidth(clipped)))} ${this.palette.accent('│')}`)
-    }
-    for (const line of wrapTextWithAnsi(this.palette.bold(displayText(this.question.question)), innerWidth)) push(line)
-    push('')
+    const header = `Question ${this.position}/${this.total} (${this.unanswered} unanswered)${this.question.header === undefined ? '' : ` · ${displayText(this.question.header)}`}`
+    const lines = [
+      this.palette.muted(header),
+      ...wrapTextWithAnsi(this.palette.text(displayText(this.question.question)), innerWidth),
+      '',
+    ]
+    const push = (line: string): void => { lines.push(line) }
     if (this.mode === 'custom') {
       for (const line of this.input.render(innerWidth)) push(line)
       push(this.palette.dim(this.options.length > 0 ? 'Enter submit • Esc options' : 'Enter submit • Esc cancel'))
@@ -763,27 +943,45 @@ class QuestionDialog implements Component, Focusable {
         options.length - this.maxVisible,
       ))
       const end = Math.min(options.length, start + this.maxVisible)
+      const optionRows = options.slice(start, end).map((option, offset) => {
+        const index = start + offset
+        const mark = this.question.multiSelect
+          ? this.selected.has(index) ? '[x] ' : '[ ] '
+          : ''
+        return `${index === this.selectedIndex ? '›' : ' '} ${index + 1}. ${mark}${displayText(option.label)}`
+      })
+      const descriptionColumn = Math.min(
+        Math.max(...optionRows.map(row => visibleWidth(row))) + 2,
+        Math.max(1, Math.floor(innerWidth * 0.55)),
+      )
       for (let index = start; index < end; index += 1) {
         // `index < end <= options.length`; the options array is borrowed immutably for this dialog.
         const option = options[index] as NonNullable<AskUserQuestionItem['options']>[number]
-        const cursor = index === this.selectedIndex ? this.palette.accent('›') : ' '
         const mark = this.question.multiSelect
-          ? this.selected.has(index) ? this.palette.success('[x]') : '[ ]'
-          : index === this.selectedIndex ? this.palette.accent('●') : this.palette.dim('○')
-        const description = option.description
-          ? this.palette.muted(` — ${displayText(option.description)}`)
+          ? this.selected.has(index) ? '[x] ' : '[ ] '
           : ''
-        const line = `${cursor} ${mark} ${displayText(option.label)}${description}`
-        push(index === this.selectedIndex ? this.palette.selected(line) : line)
+        const left = `${index === this.selectedIndex ? '›' : ' '} ${index + 1}. ${mark}${displayText(option.label)}`
+        const leftStyled = index === this.selectedIndex
+          ? this.palette.bold(this.palette.accent(left))
+          : left
+        const description = option.description === undefined
+          ? ''
+          : `${' '.repeat(Math.max(1, descriptionColumn - visibleWidth(left)))}${this.palette.muted(displayText(option.description))}`
+        push(`${leftStyled}${description}`)
       }
       if (options.length > this.maxVisible) push(this.palette.dim(`${this.selectedIndex + 1}/${options.length}`))
-      push(this.palette.dim(this.question.multiSelect
-        ? '↑↓ navigate • Space toggle • Enter submit • C custom • Esc cancel'
-        : '↑↓ navigate • Enter select • C custom • Esc cancel'))
+      const hint = this.palette.dim(this.question.multiSelect
+        ? 'Tab custom answer • ↑/↓ navigate • Space toggle • Enter submit • Esc interrupt'
+        : 'Tab custom answer • ↑/↓ navigate • Enter submit • Esc interrupt')
+      for (const line of wrapTextWithAnsi(hint, innerWidth)) push(line)
     }
-    if (this.error) push(this.palette.error(this.error))
-    lines.push(this.palette.accent(`╰${'─'.repeat(Math.max(0, width - 2))}╯`))
-    return lines
+    if (this.error) {
+      for (const line of wrapTextWithAnsi(this.palette.error(this.error), innerWidth)) push(line)
+    }
+    return ['', ...lines, ''].map((line) => {
+      const clipped = truncateToWidth(line, innerWidth, '')
+      return `  ${clipped}${' '.repeat(Math.max(0, innerWidth - visibleWidth(clipped)))}  `
+    })
   }
 }
 
@@ -839,7 +1037,6 @@ export function createTuiChat(
   const ui = new TUI(runtime.terminal, resolved.showHardwareCursor)
   const chat = new Container()
   const todoContainer = new Container()
-  const statusContainer = new Container()
   const editor = new Editor(ui, {
     borderColor: palette.dim,
     selectList: selectTheme(palette),
@@ -848,7 +1045,8 @@ export function createTuiChat(
   let showReasoning = resolved.showReasoning
   let toolsExpanded = false
   let streaming: StreamingAssistantComponent | undefined
-  let statusLoader: Loader | undefined
+  let runningStartedAt: number | undefined
+  let statusTicker: ReturnType<typeof setInterval> | undefined
   let disposed = false
   let shuttingDown: Promise<void> | undefined
   const tokens = sessionTokens(agent.session)
@@ -858,13 +1056,25 @@ export function createTuiChat(
   const questionQueue: PendingQuestion[] = []
   const commandControllers = new Set<AbortController>()
   let activeQuestion: PendingQuestion | undefined
+  let modelOverlay: OverlayHandle | undefined
+  const target: AgentLlmTargetRef = { current: initialTarget(agent), assembled: undefined }
+  let modelCommands = Promise.resolve()
+  const now = (): number => runtime.now?.() ?? Date.now()
 
   const welcome = config.welcome ?? 'ready.'
-  const header = new HeaderComponent(agent, welcome, palette)
-  const footer = new FooterComponent(agent, palette, () => toolsExpanded, () => showReasoning, () => tokens)
+  const header = new HeaderComponent(agent, welcome, palette, () => target.current?.model)
+  const footer = new FooterComponent(
+    agent,
+    palette,
+    () => toolsExpanded,
+    () => showReasoning,
+    () => tokens,
+    () => target.current?.model,
+    () => Math.min(100, Math.round(ctx.tokenMeter.measure(agent.session).totalTokens / ctx.tokenMeter.contextWindow * 100)),
+    () => runningStartedAt === undefined ? 0 : Math.max(0, Math.floor((now() - runningStartedAt) / 1_000)),
+  )
   ui.addChild(header)
   ui.addChild(chat)
-  ui.addChild(statusContainer)
   todoContainer.addChild(todo)
   ui.addChild(todoContainer)
   ui.addChild(editor)
@@ -884,10 +1094,98 @@ export function createTuiChat(
     requestRender()
   }
 
+  const disposeTargetListeners = installAgentLlmTarget(agent.ctx, target)
+
+  const selectModel = (selected: ModelChoice): void => {
+    if (target.current?.provider === selected.provider && target.current.model === selected.model) {
+      appendNotice(`Model is already ${targetLabel(selected)}.`)
+      return
+    }
+    target.current = { provider: selected.provider, model: selected.model }
+    appendNotice(`Model selected: ${targetLabel(selected)}. New steps will use it.`)
+  }
+
+  const showModelSelector = (choices: readonly ModelChoice[]): void => {
+    const current = target.current === undefined ? 'unset' : targetLabel(target.current)
+    if (choices.length === 0) {
+      appendNotice(`Current model: ${current}\nNo models are advertised by registered providers.`, 'warning')
+      return
+    }
+    modelOverlay?.hide()
+    modelOverlay = undefined
+    const close = (): void => {
+      modelOverlay?.hide()
+      modelOverlay = undefined
+      requestRender()
+    }
+    const dialog = new ModelDialog(
+      choices,
+      target.current,
+      resolved.maxModelOptions,
+      palette,
+      (selected) => {
+        close()
+        selectModel(selected)
+      },
+      close,
+    )
+    modelOverlay = ui.showOverlay(dialog, {
+      width: resolved.modelDialogWidth,
+      maxHeight: resolved.modelDialogMaxHeight,
+      anchor: 'center',
+      margin: 1,
+    })
+    requestRender()
+  }
+
+  const handleModelCommand = async (raw: string): Promise<void> => {
+    const choices = await readModelChoices(ctx, target.current)
+    if (disposed) return
+    const argument = raw.trim()
+    if (argument === '') {
+      showModelSelector(choices)
+      return
+    }
+    const parts = argument.split(/\s+/u)
+    if (parts.length > 2) {
+      appendNotice('Usage: /model [provider/]model', 'warning')
+      return
+    }
+
+    let matches: ModelChoice[]
+    if (parts.length === 2) {
+      matches = choices.filter(choice => choice.provider === parts[0] && choice.model === parts[1])
+    } else {
+      const value = argument
+      const qualified = choices.filter(choice => targetLabel(choice) === value)
+      matches = qualified.length > 0 ? qualified : choices.filter(choice => choice.model === value)
+    }
+    if (matches.length === 0) {
+      appendNotice(`Unknown model: ${argument}. Run /model to list available models.`, 'warning')
+      return
+    }
+    if (matches.length > 1) {
+      appendNotice(`Model "${argument}" is advertised by multiple providers; use /model <provider>/<model>.`, 'warning')
+      return
+    }
+    const selected = matches[0]
+    /* v8 ignore next -- a non-empty matches array always has index zero. */
+    if (selected === undefined) return
+    selectModel(selected)
+  }
+
+  const queueModelCommand = (raw: string): void => {
+    modelCommands = modelCommands.then(async () => {
+      await handleModelCommand(raw)
+    }).catch((error: unknown) => {
+      if (!disposed) appendNotice(`Could not read the model catalog: ${errorChain(error)}`, 'error')
+    })
+  }
+
   const clearStatus = (): void => {
-    statusLoader?.stop()
-    statusLoader = undefined
-    statusContainer.clear()
+    if (statusTicker !== undefined) clearInterval(statusTicker)
+    statusTicker = undefined
+    runningStartedAt = undefined
     runtime.terminal.setProgress(false)
   }
 
@@ -895,8 +1193,9 @@ export function createTuiChat(
     clearStatus()
     editor.borderColor = status === 'running' ? text => palette.accent(text) : text => palette.dim(text)
     if (status === 'running') {
-      statusLoader = new Loader(ui, text => palette.accent(text), text => palette.muted(text), 'Working — Enter sends steering, Esc cancels')
-      statusContainer.addChild(statusLoader)
+      runningStartedAt = now()
+      statusTicker = setInterval(requestRender, 1_000)
+      statusTicker.unref()
       runtime.terminal.setProgress(true)
     }
     requestRender()
@@ -1072,6 +1371,9 @@ export function createTuiChat(
       }
       const dialog = new QuestionDialog(
         question,
+        pending.index + 1,
+        pending.request.questions.length,
+        pending.request.questions.length - pending.answers.length,
         resolved.maxQuestionOptions,
         palette,
         (selection) => {
@@ -1090,8 +1392,8 @@ export function createTuiChat(
       pending.overlay = ui.showOverlay(dialog, {
         width: resolved.questionDialogWidth,
         maxHeight: resolved.questionDialogMaxHeight,
-        anchor: 'center',
-        margin: 1,
+        anchor: 'bottom-left',
+        margin: { bottom: 1 },
       })
       requestRender()
     }
@@ -1131,6 +1433,8 @@ export function createTuiChat(
     shuttingDown ??= (async () => {
       disposed = true
       clearStatus()
+      modelOverlay?.hide()
+      modelOverlay = undefined
       for (const controller of commandControllers) controller.abort(new Error('TUI disposed'))
       commandControllers.clear()
       if (activeQuestion !== undefined) {
@@ -1184,7 +1488,7 @@ export function createTuiChat(
     chat.addChild(new Text(palette.bold(palette.accent('Keyboard shortcuts')), 1, 0))
     chat.addChild(new Text([
       'Enter send • Shift/Alt+Enter newline • Up/Down prompt history',
-      'Esc cancel active turn • Ctrl+O expand tool cards • Ctrl+R toggle reasoning',
+      'Esc cancel active turn • Ctrl+O toggle tool cards • Ctrl+R toggle reasoning',
       'Ctrl+C cancel while running; clear input or exit while idle • Ctrl+D exit',
       '',
       ...commandLines,
@@ -1213,6 +1517,15 @@ export function createTuiChat(
       description: 'Show keyboard shortcuts and commands',
       handler: () => { showHelp(); return { kind: 'success' } },
     })
+    commandCtx.commands.register({
+      name: 'model',
+      description: 'Show or switch this session\'s model',
+      input: { hint: '[[provider/]model]' },
+      handler: ({ rawInput }) => {
+        queueModelCommand(rawInput)
+        return { kind: 'success' }
+      },
+    })
     commandCtx.commands.register({
       name: 'clear',
       description: 'Clear the transcript view (session history is unchanged)',
@@ -1288,7 +1601,7 @@ export function createTuiChat(
   }
 
   const removeInputListener = ui.addInputListener((data) => {
-    if (activeQuestion !== undefined) return undefined
+    if (activeQuestion !== undefined || modelOverlay !== undefined) return undefined
     if (matchesKey(data, Key.ctrl('o'))) {
       toggleTools()
       return { consume: true }
@@ -1358,6 +1671,7 @@ export function createTuiChat(
     disposeStatus()
     disposeError()
     disposeAgent()
+    disposeTargetListeners()
   }
 
   rebuildTranscript(true)

packages/ui/tui/tests/harness.ts

@@ -1,9 +1,10 @@
 import { Context } from 'cordis'
 import type { Terminal } from '@earendil-works/pi-tui'
-import AgentRegistry, { type Agent, type AgentStatus } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { type Agent, type AgentOptions, type AgentStatus } from '@deepseek-ai/dsh-agent'
+import type { ContentBlock, LlmModelInfo, LlmProviderInfo } from '@deepseek-ai/dsh-llm'
 import CommandService from '@deepseek-ai/dsh-commands'
-import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionId, type Session } from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 import { createTuiChat, type Config } from '../src/index.ts'
@@ -22,6 +23,15 @@ export interface TuiHarnessOptions {
   configureContext?: (ctx: Context) => Promise<void>
   beforeMount?: (session: Session) => void
   cwd?: string | null
+  agentOptions?: AgentOptions
+  contextWindow?: number
+  contextTokens?: number
+  now?: () => number
+  catalog?: {
+    providers: LlmProviderInfo[]
+    models: LlmModelInfo[]
+    listModels?: (provider: string) => Promise<LlmModelInfo[]>
+  }
 }
 
 export interface TuiHarness<TerminalType extends Terminal, Exit extends (code: number) => void> {
@@ -50,6 +60,28 @@ export async function createTuiTestHarness<TerminalType extends Terminal, Exit e
   await ctx.plugin(AgentRegistry)
   await ctx.plugin(CommandService)
   await ctx.plugin(UserInteractionService)
+  const catalog = options.catalog ?? {
+    providers: [{ id: 'deepseek', name: 'DeepSeek' }],
+    models: [
+      { provider: 'deepseek', id: 'deepseek-v4-flash', name: 'DeepSeek V4 Flash' },
+      { provider: 'deepseek', id: 'deepseek-v4-pro', name: 'DeepSeek V4 Pro' },
+    ],
+  }
+  ctx.provide('llm', {
+    listProviders() {
+      return catalog.providers.map(provider => ({ ...provider }))
+    },
+    listModels(provider: string) {
+      return catalog.listModels?.(provider)
+        ?? Promise.resolve(catalog.models.filter(model => model.provider === provider).map(model => ({ ...model })))
+    },
+  } as never)
+  ctx.provide('tokenMeter', {
+    contextWindow: options.contextWindow ?? 128_000,
+    measure() {
+      return { totalTokens: options.contextTokens ?? 0 }
+    },
+  } as never)
   if (options.configureContext === undefined) {
     const tools = options.tools ?? {}
     ctx.provide('tools', {
@@ -60,6 +92,7 @@ export async function createTuiTestHarness<TerminalType extends Terminal, Exit e
   } else {
     await options.configureContext(ctx)
   }
+  if (ctx.get('systemPrompt') === undefined) await ctx.plugin(SystemPrompt)
   const sessionId = SessionId('main-session')
   const session = ctx.sessions.create(
     sessionId,
@@ -71,7 +104,7 @@ export async function createTuiTestHarness<TerminalType extends Terminal, Exit e
   const cancelled: string[] = []
   const agent: FakeAgent = {
     id: sessionId,
-    options: { model: 'deepseek-v4-flash' },
+    options: options.agentOptions ?? { provider: 'deepseek', model: 'deepseek-v4-flash' },
     session,
     status: options.status ?? 'idle',
     ctx,
@@ -97,7 +130,7 @@ export async function createTuiTestHarness<TerminalType extends Terminal, Exit e
     welcome: 'Coding agent ready.',
     sessionId,
     color: false,
-  }, options.config), { terminal, exit })
+  }, options.config), { terminal, exit, now: options.now ?? (() => 0) })
   return { ctx, session, agent, terminal, exit, controller }
 }
 

packages/ui/tui/tests/plugin-shape.spec.ts

@@ -12,7 +12,15 @@ describe('dsh-tui plugin export shape', () => {
     const unwrapped = loader.unwrapExports(tui) as Record<string, unknown>
     expect(unwrapped).toBe(tui)
     expect(unwrapped.name).toBe('ui-tui')
-    expect(unwrapped.inject).toEqual(['agents', 'commands', 'userInteraction', 'tools'])
+    expect(unwrapped.inject).toEqual([
+      'agents',
+      'commands',
+      'userInteraction',
+      'tools',
+      'llm',
+      'systemPrompt',
+      'tokenMeter',
+    ])
     expect(unwrapped.Config).toBeDefined()
     expect(typeof unwrapped.apply).toBe('function')
   })

packages/ui/tui/tests/snapshots/advanced-cards-collapsed.expected.txt

@@ -33,11 +33,12 @@ buffer
 9| "▌ /workspace/project                                                                                "
   style 0-0 fg=green
   style 2-19 dim
-10| "▌ packages/ui/tui 100%                                                                              "
+10| "▌ … +4 lines (Ctrl+O to expand)                                                                     "
   style 0-0 fg=green
-11| "▌ … 4 more lines (Ctrl+O to expand)                                                                 "
+  style 2-30 dim
+11| "▌ [exit 0]                                                                                          "
   style 0-0 fg=green
-  style 2-34 dim
+  style 2-9 dim
 12| "▌ "
   style 0-0 fg=green
 13| <blank>
@@ -53,12 +54,12 @@ buffer
 17| "▌ - old line                                                                                        "
   style 0-0 fg=green
   style 2-11 fg=red
-18| "▌ - keep                                                                                            "
+18| "▌ … +5 lines (Ctrl+O to expand)                                                                     "
   style 0-0 fg=green
-  style 2-7 fg=red
-19| "▌ … 5 more lines (Ctrl+O to expand)                                                                 "
+  style 2-30 dim
+19| "▌ + expect(screen).toMatchSnapshot()                                                                "
   style 0-0 fg=green
-  style 2-34 dim
+  style 2-35 fg=green
 20| "▌ "
   style 0-0 fg=green
 21| <blank>
@@ -102,6 +103,6 @@ buffer
   style 1-1 inverse
 39| "────────────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-99 dim
-40| "/workspace/project  ↑0 ↓0                                          idle  reasoning:on  tools:compact"
+40| "/workspace/project  ↑0 ↓0                 0% context  tools:compact  deepseek-v4-flash(reasoning:on)"
   style 0-24 dim
-  style 67-99 dim
+  style 42-99 dim

packages/ui/tui/tests/snapshots/advanced-cards-expanded.expected.txt

@@ -122,6 +122,6 @@ buffer
   style 1-1 inverse
 48| "────────────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-99 dim
-49| "/workspace/project  ↑0 ↓0                                         idle  reasoning:on  tools:expanded"
+49| "/workspace/project  ↑0 ↓0                0% context  tools:expanded  deepseek-v4-flash(reasoning:on)"
   style 0-24 dim
-  style 66-99 dim
+  style 41-99 dim

packages/ui/tui/tests/snapshots/code-mode-pending.expected.txt

@@ -46,7 +46,7 @@ buffer
   style 1-1 inverse
 16| "────────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-95 dim
-17| "/workspace/project  ↑0 ↓0                                      idle  reasoning:on  tools:compact"
+17| "/workspace/project  ↑0 ↓0             0% context  tools:compact  deepseek-v4-flash(reasoning:on)"
   style 0-24 dim
-  style 63-95 dim
+  style 38-95 dim
 18-35| <blank>

packages/ui/tui/tests/snapshots/conversation-streaming.expected.txt

@@ -1,5 +1,5 @@
 terminal 96x36 buffer=normal length=36 base=0 viewport=0
-lifecycle started=1 stopped=0 progress=inactive
+lifecycle started=1 stopped=0 progress=active
 title "DSH snapshot"
 cursor hidden column=1 viewportRow=17 bufferRow=17
 viewport
@@ -41,12 +41,12 @@ viewport
 15| " Streaming visible state…                                                                       "
   style 11-23 bold
 16| "────────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-95 dim
+  style 0-95 fg=bright-blue
 17| "                                                                                                "
   style 1-1 inverse
 18| "────────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-95 dim
-19| "/workspace/project  ↑0 ↓0                                      idle  reasoning:on  tools:compact"
-  style 0-24 dim
-  style 63-95 dim
+  style 0-95 fg=bright-blue
+19| "◒ Working · 0s                                                                     esc interrupt"
+  style 0-13 fg=bright-blue
+  style 83-95 dim
 20-35| <blank>

packages/ui/tui/tests/snapshots/cordis-tools-pending.expected.txt

@@ -53,7 +53,7 @@ buffer
   style 1-1 inverse
 19| "────────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-95 dim
-20| "/workspace/project  ↑0 ↓0                                      idle  reasoning:on  tools:compact"
+20| "/workspace/project  ↑0 ↓0             0% context  tools:compact  deepseek-v4-flash(reasoning:on)"
   style 0-24 dim
-  style 63-95 dim
+  style 38-95 dim
 21-35| <blank>

packages/ui/tui/tests/snapshots/disposed-terminal.expected.txt

@@ -1,7 +1,7 @@
 terminal 92x32 buffer=normal length=32 base=0 viewport=0
 lifecycle started=1 stopped=1 progress=inactive
 title "DSH snapshot"
-cursor visible column=0 viewportRow=29 bufferRow=29
+cursor visible column=0 viewportRow=30 bufferRow=30
 buffer
 0| "╭──────────────────────────────────────────────────────────────────────────────────────────╮"
   style 0-91 fg=bright-blue
@@ -25,7 +25,7 @@ buffer
   style 1-18 fg=bright-blue bold
 7| " Enter send • Shift/Alt+Enter newline • Up/Down prompt history                              "
   style 1-61 fg=bright-black
-8| " Esc cancel active turn • Ctrl+O expand tool cards • Ctrl+R toggle reasoning                "
+8| " Esc cancel active turn • Ctrl+O toggle tool cards • Ctrl+R toggle reasoning                "
   style 1-75 fg=bright-black
 9| " Ctrl+C cancel while running; clear input or exit while idle • Ctrl+D exit                  "
   style 1-73 fg=bright-black
@@ -38,28 +38,30 @@ buffer
   style 1-47 fg=bright-black
 14| " /help — Show keyboard shortcuts and commands                                               "
   style 1-44 fg=bright-black
-15| " /reasoning — Toggle reasoning blocks                                                       "
+15| " /model [[provider/]model] — Show or switch this session's model                            "
+  style 1-63 fg=bright-black
+16| " /reasoning — Toggle reasoning blocks                                                       "
   style 1-36 fg=bright-black
-16| " /redraw — Invalidate components and redraw the terminal                                    "
+17| " /redraw — Invalidate components and redraw the terminal                                    "
   style 1-55 fg=bright-black
-17| " /tools — Expand or collapse all tool cards                                                 "
+18| " /tools — Expand or collapse all tool cards                                                 "
   style 1-42 fg=bright-black
-18| <blank>
-19| " provider stream failed after partial output                                                "
+19| <blank>
+20| " provider stream failed after partial output                                                "
   style 1-43 fg=red
-20| <blank>
-21| " The previous process ended during this turn.                                               "
+21| <blank>
+22| " The previous process ended during this turn.                                               "
   style 1-44 fg=yellow
-22| <blank>
-23| " Unknown command: /unknown-advanced-command                                                 "
+23| <blank>
+24| " Unknown command: /unknown-advanced-command                                                 "
   style 1-42 fg=yellow
-24| "────────────────────────────────────────────────────────────────────────────────────────────"
+25| "────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-91 dim
-25| "                                                                                            "
+26| "                                                                                            "
   style 1-1 inverse
-26| "────────────────────────────────────────────────────────────────────────────────────────────"
+27| "────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-91 dim
-27| "/workspace/project  ↑0 ↓0                                  idle  reasoning:on  tools:compact"
+28| "/workspace/project  ↑0 ↓0         0% context  tools:compact  deepseek-v4-flash(reasoning:on)"
   style 0-24 dim
-  style 59-91 dim
-28-31| <blank>
+  style 34-91 dim
+29-31| <blank>

packages/ui/tui/tests/snapshots/dynamic-workflow-pending.expected.txt

@@ -33,8 +33,9 @@ buffer
   style 0-0 fg=yellow
 10| "▌   () => agent('Audit layout', { label: 'layout', phase: 'Inspect' }),                         "
   style 0-0 fg=yellow
-11| "▌   () => agent('Audit lifecycle', { label: 'lifecycle', phase: 'Inspect' }),                   "
+11| "▌ … +1 lines (Ctrl+O to expand)                                                                 "
   style 0-0 fg=yellow
+  style 2-30 dim
 12| "▌ ])                                                                                            "
   style 0-0 fg=yellow
 13| "▌ phase('Verify')                                                                               "
@@ -49,7 +50,7 @@ buffer
   style 1-1 inverse
 18| "────────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-95 dim
-19| "/workspace/project  ↑0 ↓0                                      idle  reasoning:on  tools:compact"
+19| "/workspace/project  ↑0 ↓0             0% context  tools:compact  deepseek-v4-flash(reasoning:on)"
   style 0-24 dim
-  style 63-95 dim
+  style 38-95 dim
 20-35| <blank>

packages/ui/tui/tests/snapshots/errors-and-help.expected.txt

@@ -1,7 +1,7 @@
 terminal 92x32 buffer=normal length=32 base=0 viewport=0
 lifecycle started=1 stopped=0 progress=inactive
 title "DSH snapshot"
-cursor hidden column=1 viewportRow=25 bufferRow=25
+cursor hidden column=1 viewportRow=26 bufferRow=26
 buffer
 0| "╭──────────────────────────────────────────────────────────────────────────────────────────╮"
   style 0-91 fg=bright-blue
@@ -25,7 +25,7 @@ buffer
   style 1-18 fg=bright-blue bold
 7| " Enter send • Shift/Alt+Enter newline • Up/Down prompt history                              "
   style 1-61 fg=bright-black
-8| " Esc cancel active turn • Ctrl+O expand tool cards • Ctrl+R toggle reasoning                "
+8| " Esc cancel active turn • Ctrl+O toggle tool cards • Ctrl+R toggle reasoning                "
   style 1-75 fg=bright-black
 9| " Ctrl+C cancel while running; clear input or exit while idle • Ctrl+D exit                  "
   style 1-73 fg=bright-black
@@ -38,28 +38,30 @@ buffer
   style 1-47 fg=bright-black
 14| " /help — Show keyboard shortcuts and commands                                               "
   style 1-44 fg=bright-black
-15| " /reasoning — Toggle reasoning blocks                                                       "
+15| " /model [[provider/]model] — Show or switch this session's model                            "
+  style 1-63 fg=bright-black
+16| " /reasoning — Toggle reasoning blocks                                                       "
   style 1-36 fg=bright-black
-16| " /redraw — Invalidate components and redraw the terminal                                    "
+17| " /redraw — Invalidate components and redraw the terminal                                    "
   style 1-55 fg=bright-black
-17| " /tools — Expand or collapse all tool cards                                                 "
+18| " /tools — Expand or collapse all tool cards                                                 "
   style 1-42 fg=bright-black
-18| <blank>
-19| " provider stream failed after partial output                                                "
+19| <blank>
+20| " provider stream failed after partial output                                                "
   style 1-43 fg=red
-20| <blank>
-21| " The previous process ended during this turn.                                               "
+21| <blank>
+22| " The previous process ended during this turn.                                               "
   style 1-44 fg=yellow
-22| <blank>
-23| " Unknown command: /unknown-advanced-command                                                 "
+23| <blank>
+24| " Unknown command: /unknown-advanced-command                                                 "
   style 1-42 fg=yellow
-24| "────────────────────────────────────────────────────────────────────────────────────────────"
+25| "────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-91 dim
-25| "                                                                                            "
+26| "                                                                                            "
   style 1-1 inverse
-26| "────────────────────────────────────────────────────────────────────────────────────────────"
+27| "────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-91 dim
-27| "/workspace/project  ↑0 ↓0                                  idle  reasoning:on  tools:compact"
+28| "/workspace/project  ↑0 ↓0         0% context  tools:compact  deepseek-v4-flash(reasoning:on)"
   style 0-24 dim
-  style 59-91 dim
-28-31| <blank>
+  style 34-91 dim
+29-31| <blank>

packages/ui/tui/tests/snapshots/model-selector.expected.txt

@@ -0,0 +1,52 @@
+terminal 92x32 buffer=normal length=32 base=0 viewport=0
+lifecycle started=1 stopped=0 progress=inactive
+title "DSH snapshot"
+cursor hidden column=0 viewportRow=31 bufferRow=31
+buffer
+0| "╭──────────────────────────────────────────────────────────────────────────────────────────╮"
+  style 0-91 fg=bright-blue
+1| "│ DEEPSEEK HARNESS                                                                         │"
+  style 0-0 fg=bright-blue
+  style 2-9 fg=bright-blue bold
+  style 11-17 bold
+  style 91-91 fg=bright-blue
+2| "│ Snapshot agent ready.                                                                    │"
+  style 0-0 fg=bright-blue
+  style 2-22 fg=bright-black
+  style 91-91 fg=bright-blue
+3| "│ deepseek-v4-flash  •  main-session                                                       │"
+  style 0-0 fg=bright-blue
+  style 2-35 dim
+  style 91-91 fg=bright-blue
+4| "╰──────────────────────────────────────────────────────────────────────────────────────────╯"
+  style 0-91 fg=bright-blue
+5| "────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-91 dim
+6| "                                                                                            "
+  style 1-1 inverse
+7| "────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-91 dim
+8| "/workspace/project  ↑0 ↓0         0% context  tools:compact  deepseek-v4-flash(reasoning:on)"
+  style 0-24 dim
+  style 34-91 dim
+9-12| <blank>
+13| "          ╭ Select model ────────────────────────────────────────────────────────╮          "
+  style 10-81 fg=bright-blue
+14| "          │ → deepseek/deepseek-v4-flash      DeepSeek V4 Flash — current        │          "
+  style 10-10 fg=bright-blue
+  style 12-72 fg=bright-blue inverse
+  style 81-81 fg=bright-blue
+15| "          │   deepseek/deepseek-v4-pro        DeepSeek V4 Pro                    │          "
+  style 10-10 fg=bright-blue
+  style 38-60 fg=bright-black
+  style 81-81 fg=bright-blue
+16| "          │                                                                      │          "
+  style 10-10 fg=bright-blue
+  style 81-81 fg=bright-blue
+17| "          │ ↑/↓ navigate • Enter select • Esc cancel                             │          "
+  style 10-10 fg=bright-blue
+  style 12-51 dim
+  style 81-81 fg=bright-blue
+18| "          ╰──────────────────────────────────────────────────────────────────────╯          "
+  style 10-81 fg=bright-blue
+19-31| <blank>

packages/ui/tui/tests/snapshots/model-switching.expected.txt

@@ -0,0 +1,35 @@
+terminal 92x32 buffer=normal length=32 base=0 viewport=0
+lifecycle started=1 stopped=0 progress=inactive
+title "DSH snapshot"
+cursor hidden column=1 viewportRow=8 bufferRow=8
+buffer
+0| "╭──────────────────────────────────────────────────────────────────────────────────────────╮"
+  style 0-91 fg=bright-blue
+1| "│ DEEPSEEK HARNESS                                                                         │"
+  style 0-0 fg=bright-blue
+  style 2-9 fg=bright-blue bold
+  style 11-17 bold
+  style 91-91 fg=bright-blue
+2| "│ Snapshot agent ready.                                                                    │"
+  style 0-0 fg=bright-blue
+  style 2-22 fg=bright-black
+  style 91-91 fg=bright-blue
+3| "│ deepseek-v4-pro  •  main-session                                                         │"
+  style 0-0 fg=bright-blue
+  style 2-33 dim
+  style 91-91 fg=bright-blue
+4| "╰──────────────────────────────────────────────────────────────────────────────────────────╯"
+  style 0-91 fg=bright-blue
+5| <blank>
+6| " Model selected: deepseek/deepseek-v4-pro. New steps will use it.                           "
+  style 1-64 fg=bright-black
+7| "────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-91 dim
+8| "                                                                                            "
+  style 1-1 inverse
+9| "────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-91 dim
+10| "/workspace/project  ↑0 ↓0           0% context  tools:compact  deepseek-v4-pro(reasoning:on)"
+  style 0-24 dim
+  style 36-91 dim
+11-31| <blank>

packages/ui/tui/tests/snapshots/question-dialog-validation.expected.txt

@@ -1,7 +1,7 @@
 terminal 56x20 buffer=normal length=20 base=0 viewport=0
 lifecycle started=1 stopped=0 progress=inactive
 title "DSH snapshot"
-cursor hidden column=56 viewportRow=13 bufferRow=13
+cursor hidden column=56 viewportRow=17 bufferRow=17
 viewport
 0| "╭──────────────────────────────────────────────────────╮"
   style 0-55 fg=bright-blue
@@ -18,52 +18,30 @@ viewport
   style 0-0 fg=bright-blue
   style 2-35 dim
   style 55-55 fg=bright-blue
-4| "╰───╭ Coverage ────────────────────────────────────╮───╯"
+4| "╰──────────────────────────────────────────────────────╯"
   style 0-55 fg=bright-blue
-5| "────│ Which advanced TUI states belong in the      │────"
-  style 0-3 dim
-  style 4-4 fg=bright-blue
-  style 6-50 bold
-  style 51-51 fg=bright-blue bold
-  style 52-55 dim
-6| "    │ required matrix?                             │    "
-  style 1-1 inverse
-  style 4-4 fg=bright-blue
-  style 6-21 bold
-  style 51-51 fg=bright-blue
-7| "────│                                              │────"
-  style 0-3 dim
-  style 4-4 fg=bright-blue
-  style 51-51 fg=bright-blue
-  style 52-55 dim
-8| "/wor│ › [ ] Code Mode — run_code programs and capt │:com"
-  style 0-3 dim
-  style 4-4 fg=bright-blue
-  style 6-6 fg=bright-blue inverse
-  style 7-20 inverse
-  style 21-49 fg=bright-black inverse
-  style 51-51 fg=bright-blue
-  style 52-55 dim
-9| "    │   [ ] Workflows — phases and parallel agents │    "
-  style 4-4 fg=bright-blue
-  style 21-49 fg=bright-black
-  style 51-51 fg=bright-blue
-10| "    │   [ ] Cordis tools — inspect, mount, and unm │    "
-  style 4-4 fg=bright-blue
-  style 24-49 fg=bright-black
-  style 51-51 fg=bright-blue
-11| "    │ 1/4                                          │    "
-  style 4-4 fg=bright-blue
-  style 6-8 dim
-  style 51-51 fg=bright-blue
-12| "    │ ↑↓ navigate • Space toggle • Enter submit •  │    "
-  style 4-4 fg=bright-blue
-  style 6-49 dim
-  style 51-51 fg=bright-blue
-13| "    │ Select at least one option, or press C for a │    "
-  style 4-4 fg=bright-blue
-  style 6-49 fg=red
-  style 51-51 fg=bright-blue
-14| "    ╰──────────────────────────────────────────────╯    "
-  style 4-51 fg=bright-blue
-15-19| <blank>
+5| "                                                        "
+6| "  Question 1/3 (3 unanswered) · Coverage                "
+  style 2-39 fg=bright-black
+7| "  Which advanced TUI states belong in the required      "
+8| "  matrix?                                               "
+9| "                                                        "
+10| "  › 1. [ ] Code Mode     run_code programs and capture  "
+  style 2-19 fg=bright-blue bold
+  style 25-53 fg=bright-black
+11| "    2. [ ] Workflows     phases and parallel agents     "
+  style 25-50 fg=bright-black
+12| "    3. [ ] Cordis tools  inspect, mount, and unmount    "
+  style 25-51 fg=bright-black
+13| "  1/4                                                   "
+  style 2-4 dim
+14| "  Tab custom answer • ↑/↓ navigate • Space toggle •     "
+  style 2-55 dim
+15| "  Enter submit • Esc interrupt                          "
+  style 2-29 dim
+16| "  Select at least one option, or press Tab for a        "
+  style 2-55 fg=red
+17| "  custom answer.                                        "
+  style 2-15 fg=red
+18| "                                                        "
+19| <blank>

packages/ui/tui/tests/snapshots/question-dialog.expected.txt

@@ -20,48 +20,28 @@ viewport
   style 55-55 fg=bright-blue
 4| "╰──────────────────────────────────────────────────────╯"
   style 0-55 fg=bright-blue
-5| "────╭ Coverage ────────────────────────────────────╮────"
-  style 0-3 dim
-  style 4-51 fg=bright-blue
-  style 52-55 dim
-6| "    │ Which advanced TUI states belong in the      │    "
+5| "────────────────────────────────────────────────────────"
+  style 0-55 dim
+6| "                                                        "
   style 1-1 inverse
-  style 4-4 fg=bright-blue
-  style 6-50 bold
-  style 51-51 fg=bright-blue bold
-7| "────│ required matrix?                             │────"
-  style 0-3 dim
-  style 4-4 fg=bright-blue
-  style 6-21 bold
-  style 51-51 fg=bright-blue
-  style 52-55 dim
-8| "/wor│                                              │:com"
-  style 0-3 dim
-  style 4-4 fg=bright-blue
-  style 51-51 fg=bright-blue
-  style 52-55 dim
-9| "    │ › [ ] Code Mode — run_code programs and capt │    "
-  style 4-4 fg=bright-blue
-  style 6-6 fg=bright-blue inverse
-  style 7-20 inverse
-  style 21-49 fg=bright-black inverse
-  style 51-51 fg=bright-blue
-10| "    │   [ ] Workflows — phases and parallel agents │    "
-  style 4-4 fg=bright-blue
-  style 21-49 fg=bright-black
-  style 51-51 fg=bright-blue
-11| "    │   [ ] Cordis tools — inspect, mount, and unm │    "
-  style 4-4 fg=bright-blue
-  style 24-49 fg=bright-black
-  style 51-51 fg=bright-blue
-12| "    │ 1/4                                          │    "
-  style 4-4 fg=bright-blue
-  style 6-8 dim
-  style 51-51 fg=bright-blue
-13| "    │ ↑↓ navigate • Space toggle • Enter submit •  │    "
-  style 4-4 fg=bright-blue
-  style 6-49 dim
-  style 51-51 fg=bright-blue
-14| "    ╰──────────────────────────────────────────────╯    "
-  style 4-51 fg=bright-blue
-15-19| <blank>
+7| "                                                        "
+8| "  Question 1/3 (3 unanswered) · Coverage                "
+  style 2-39 fg=bright-black
+9| "  Which advanced TUI states belong in the required      "
+10| "  matrix?                                               "
+11| "                                                        "
+12| "  › 1. [ ] Code Mode     run_code programs and capture  "
+  style 2-19 fg=bright-blue bold
+  style 25-53 fg=bright-black
+13| "    2. [ ] Workflows     phases and parallel agents     "
+  style 25-50 fg=bright-black
+14| "    3. [ ] Cordis tools  inspect, mount, and unmount    "
+  style 25-51 fg=bright-black
+15| "  1/4                                                   "
+  style 2-4 dim
+16| "  Tab custom answer • ↑/↓ navigate • Space toggle •     "
+  style 2-55 dim
+17| "  Enter submit • Esc interrupt                          "
+  style 2-29 dim
+18| "                                                        "
+19| <blank>

packages/ui/tui/tests/snapshots/retry-cancelled.expected.txt

@@ -42,7 +42,7 @@ buffer
   style 1-1 inverse
 16| "────────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-95 dim
-17| "/workspace/project  ↑0 ↓0                                      idle  reasoning:on  tools:compact"
+17| "/workspace/project  ↑0 ↓0             0% context  tools:compact  deepseek-v4-flash(reasoning:on)"
   style 0-24 dim
-  style 63-95 dim
+  style 38-95 dim
 18-35| <blank>

packages/ui/tui/tests/snapshots/retry-exhausted.expected.txt

@@ -39,7 +39,7 @@ buffer
   style 1-1 inverse
 14| "────────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-95 dim
-15| "/workspace/project  ↑0 ↓0                                      idle  reasoning:on  tools:compact"
+15| "/workspace/project  ↑0 ↓0             0% context  tools:compact  deepseek-v4-flash(reasoning:on)"
   style 0-24 dim
-  style 63-95 dim
+  style 38-95 dim
 16-35| <blank>

packages/ui/tui/tests/snapshots/retry-recovered.expected.txt

@@ -43,7 +43,7 @@ buffer
   style 1-1 inverse
 17| "────────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-95 dim
-18| "/workspace/project  ↑0 ↓0                                      idle  reasoning:on  tools:compact"
+18| "/workspace/project  ↑0 ↓0             0% context  tools:compact  deepseek-v4-flash(reasoning:on)"
   style 0-24 dim
-  style 63-95 dim
+  style 38-95 dim
 19-35| <blank>

packages/ui/tui/tests/snapshots/retry-scheduled.expected.txt

@@ -39,7 +39,7 @@ buffer
   style 1-1 inverse
 14| "────────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-95 dim
-15| "/workspace/project  ↑0 ↓0                                      idle  reasoning:on  tools:compact"
+15| "/workspace/project  ↑0 ↓0             0% context  tools:compact  deepseek-v4-flash(reasoning:on)"
   style 0-24 dim
-  style 63-95 dim
+  style 38-95 dim
 16-35| <blank>

packages/ui/tui/tests/snapshots/surface-after-compaction-narrow.expected.txt

@@ -35,7 +35,6 @@ buffer
   style 1-1 inverse
 12| "────────────────────────────────────────────"
   style 0-43 dim
-13| "/workspace/project  ↑0 ↓0  idle  reasoning:o"
-  style 0-24 dim
-  style 27-43 dim
+13| " 0% context  deepseek-v4-flash(reasoning:on)"
+  style 1-43 dim
 14-17| <blank>

packages/ui/tui/tests/snapshots/surface-after-compaction-wide.expected.txt

@@ -31,7 +31,7 @@ buffer
   style 1-1 inverse
 10| "────────────────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-103 dim
-11| "/workspace/project  ↑0 ↓0                                              idle  reasoning:on  tools:compact"
+11| "/workspace/project  ↑0 ↓0                     0% context  tools:compact  deepseek-v4-flash(reasoning:on)"
   style 0-24 dim
-  style 71-103 dim
+  style 46-103 dim
 12-29| <blank>

packages/ui/tui/tests/snapshots/surface-before-compaction.expected.txt

@@ -45,8 +45,9 @@ buffer
   style 2-19 dim
 15| "▌ packages/ui/tui 100%                                                          "
   style 0-0 fg=green
-16| "▌ 4016 tests passed                                                             "
+16| "▌ … +1 lines (Ctrl+O to expand)                                                 "
   style 0-0 fg=green
+  style 2-30 dim
 17| "▌ 1 test skipped                                                                "
   style 0-0 fg=green
 18| "▌ coverage complete                                                             "
@@ -62,6 +63,6 @@ buffer
   style 1-1 inverse
 23| "────────────────────────────────────────────────────────────────────────────────"
   style 0-79 dim
-24| "/workspace/project  ↑0 ↓0                      idle  reasoning:on  tools:compact"
-  style 0-24 dim
-  style 47-79 dim
+24| "/workspace/pro  ↑0 ↓0 0% context  tools:compact  deepseek-v4-flash(reasoning:on)"
+  style 0-13 dim
+  style 22-79 dim

packages/ui/tui/tests/snapshots/untrusted-controls.expected.txt

@@ -49,36 +49,19 @@ buffer
 19| "▌ Unsafe description \\x1b]2;snapshot-controlled\\x07\\x09\\x7f\\x9b31m                                  "
   style 0-0 fg=green
   style 2-65 fg=bright-black
-20| "▌ /unsafe/\\x1b╭ Unsafe header \\x1b]2;snapshot-controlled\\x07\\x09\\x7f\\x9b31m ─────────╮              "
+20| "▌ /unsafe/\\x1b]2;snapshot-controlled\\x07\\x09\\x7f\\x9b31m                                             "
   style 0-0 fg=green
-  style 2-13 dim
-  style 14-85 fg=bright-blue
-21| "▌ Unsafe outpu│ Unsafe question \\x1b]2;snapshot-controlled\\x07\\x09\\x7f\\x9b31m        │              "
+  style 2-54 dim
+21| "▌ Unsafe output \\x1b]2;snapshot-controlled\\x07\\x09\\x7f\\x9b31m                                       "
   style 0-0 fg=green
-  style 14-14 fg=bright-blue
-  style 16-76 bold
-  style 85-85 fg=bright-blue
-22| "▌ [signal SIG\\│                                                                      │              "
+22| "▌ [signal SIG\\x1b]2;snapshot-controlled\\x07\\x09\\x7f\\x9b31m]                                         "
   style 0-0 fg=green
-  style 2-13 fg=red
-  style 14-14 fg=bright-blue
-  style 85-85 fg=bright-blue
-23| "▌             │ › ● Unsafe option \\x1b]2;snapshot-controlled\\x07\\x09\\x7f\\x9b31m — Un │              "
+  style 2-58 fg=red
+23| "▌ "
   style 0-0 fg=green
-  style 14-14 fg=bright-blue
-  style 16-16 fg=bright-blue inverse
-  style 17-17 inverse
-  style 18-18 fg=bright-blue inverse
-  style 19-78 inverse
-  style 79-83 fg=bright-black inverse
-  style 85-85 fg=bright-blue
-24| "              │ ↑↓ navigate • Enter select • C custom • Esc cancel                   │              "
-  style 14-14 fg=bright-blue
-  style 16-65 dim
-  style 85-85 fg=bright-blue
-25| " Context · uns╰──────────────────────────────────────────────────────────────────────╯              "
-  style 1-13 dim
-  style 14-85 fg=bright-blue
+24| <blank>
+25| " Context · unsafe-\\x1b]2;snapshot-controlled\\x07\\x09\\x7f\\x9b31m                                     "
+  style 1-62 dim
 26| " Unsafe context \\x1b]2;snapshot-controlled\\x07\\x09\\x7f\\x9b31m                                       "
   style 1-60 fg=bright-black
 27| <blank>
@@ -88,19 +71,17 @@ buffer
 30| " Unsafe turn error \\x1b]2;snapshot-controlled\\x07\\x09\\x7f\\x9b31m                                    "
   style 1-63 fg=red
 31| <blank>
-32| " Unsafe live error \\x1b]2;snapshot-controlled\\x07\\x09\\x7f\\x9b31m                                    "
-  style 1-63 fg=red
-33| <blank>
-34| "Plan"
-  style 0-3 fg=bright-blue bold
-35| "  ● Unsafe todo \\x1b]2;snapshot-controlled\\x07\\x09\\x7f\\x9b31m"
-  style 2-2 fg=yellow
-36| "────────────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-99 dim
-37| "                                                                                                    "
-  style 1-1 inverse
-38| "────────────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-99 dim
-39| "/workspace/project  ↑0 ↓0                                          idle  reasoning:on  tools:compact"
+32| "                                                                                                    "
+33| "  Question 1/1 (1 unanswered) · Unsafe header \\x1b]2;snapshot-controlled\\x07\\x09\\x7f\\x9b31m         "
+  style 2-90 fg=bright-black
+34| "  Unsafe question \\x1b]2;snapshot-controlled\\x07\\x09\\x7f\\x9b31m                                     "
+35| "                                                                                                    "
+36| "  › 1. Unsafe option \\x1b]2;snapshot-controlled\\x07\\x09\\x7f\\x9b31m Unsafe detail \\x1b]2;snapshot-c  "
+  style 2-65 fg=bright-blue bold
+  style 67-97 fg=bright-black
+37| "  Tab custom answer • ↑/↓ navigate • Enter submit • Esc interrupt                                   "
+  style 2-64 dim
+38| "                                                                                                    "
+39| "/workspace/project  ↑0 ↓0                 0% context  tools:compact  deepseek-v4-flash(reasoning:on)"
   style 0-24 dim
-  style 67-99 dim
+  style 42-99 dim

packages/ui/tui/tests/tui.snapshot.ts

@@ -40,6 +40,8 @@ const CHECKPOINTS = [
   'surface-before-compaction',
   'surface-after-compaction-narrow',
   'surface-after-compaction-wide',
+  'model-selector',
+  'model-switching',
   'errors-and-help',
   'disposed-terminal',
 ] as const
@@ -201,6 +203,8 @@ describe('TUI terminal-state snapshots', () => {
   it('pins an in-flight reasoning and Markdown stream', async () => {
     const harness = await setupSnapshot()
     await renderAfter(harness, () => {
+      harness.agent.status = 'running'
+      harness.ctx.emit('agent/status', harness.agent, 'running')
       appendUser(harness.session, 'Show the live update.')
       harness.session.append('assistant/chunk', {
         turn: 2,
@@ -463,25 +467,29 @@ describe('TUI terminal-state snapshots', () => {
     const harness = await setupSnapshot({
       config: {
         maxQuestionOptions: 3,
-        questionDialogWidth: 48,
+        questionDialogWidth: 200,
         questionDialogMaxHeight: 16,
       },
     }, { columns: 56, rows: 20 })
     const controller = new AbortController()
     const beforeQuestion = harness.terminal.frames
     const answer = harness.ctx.userInteraction.ask({
-      questions: [{
-        id: 'coverage',
-        header: 'Coverage',
-        question: 'Which advanced TUI states belong in the required matrix?',
-        multiSelect: true,
-        options: [
-          { label: 'Code Mode', description: 'run_code programs and captured output' },
-          { label: 'Workflows', description: 'phases and parallel agents' },
-          { label: 'Cordis tools', description: 'inspect, mount, and unmount' },
-          { label: 'Compaction', description: 'surface replacement and reflow' },
-        ],
-      }],
+      questions: [
+        {
+          id: 'coverage',
+          header: 'Coverage',
+          question: 'Which advanced TUI states belong in the required matrix?',
+          multiSelect: true,
+          options: [
+            { label: 'Code Mode', description: 'run_code programs and captured output' },
+            { label: 'Workflows', description: 'phases and parallel agents' },
+            { label: 'Cordis tools', description: 'inspect, mount, and unmount' },
+            { label: 'Compaction', description: 'surface replacement and reflow' },
+          ],
+        },
+        { id: 'priority', question: 'Which state should be implemented first?' },
+        { id: 'notes', question: 'Any additional constraints?' },
+      ],
       signal: controller.signal,
     })
     const rejected = expect(answer).rejects.toMatchObject({ code: 'ASK_ABORTED' })
@@ -569,6 +577,21 @@ describe('TUI terminal-state snapshots', () => {
     await harness.ctx.fiber.dispose()
     await harness.terminal.dispose()
   })
+
+  it('pins the model selector and selection notice', async () => {
+    const harness = await setupSnapshot({}, { columns: 92, rows: 32 })
+    await renderAfter(harness, () => {
+      harness.terminal.send('/model')
+      harness.terminal.send('\r')
+    })
+    await checkpoint('model-selector', harness.terminal, { includeScrollback: true })
+    await renderAfter(harness, () => {
+      harness.terminal.send('\x1b[B')
+      harness.terminal.send('\r')
+    })
+    await checkpoint('model-switching', harness.terminal, { includeScrollback: true })
+    await disposeSnapshot(harness)
+  })
 })
 
 afterAll(async () => {

packages/ui/tui/tests/tui.spec.ts

@@ -3,7 +3,8 @@ import { join } from 'node:path'
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import type { Terminal } from '@earendil-works/pi-tui'
-import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { agentEvents, assembleContextFor, type Agent } from '@deepseek-ai/dsh-agent'
+import type { LlmCallConfig } from '@deepseek-ai/dsh-llm'
 import CommandService, { type CommandInvocation } from '@deepseek-ai/dsh-commands'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
@@ -112,14 +113,26 @@ async function dispose(setupResult: Awaited<ReturnType<typeof setup>>): Promise<
   await disposeTuiTestHarness(setupResult)
 }
 
+function provideTokenMeter(ctx: Context): void {
+  ctx.provide('tokenMeter', {
+    contextWindow: 128_000,
+    measure() {
+      return { totalTokens: 0 }
+    },
+  } as never)
+}
+
 describe('TUI config', () => {
   it('defaults every direct-call TUI option', () => {
     expect(resolveTuiConfig(undefined)).toEqual({
       showReasoning: true,
-      maxToolOutputLines: 12,
+      maxToolOutputLines: 6,
       maxQuestionOptions: 8,
-      questionDialogWidth: 72,
+      maxModelOptions: 8,
+      questionDialogWidth: 200,
       questionDialogMaxHeight: 20,
+      modelDialogWidth: 72,
+      modelDialogMaxHeight: 20,
       showHardwareCursor: false,
       color: true,
       title: 'DeepSeek Harness',
@@ -128,8 +141,11 @@ describe('TUI config', () => {
       showReasoning: false,
       maxToolOutputLines: 2,
       maxQuestionOptions: 3,
+      maxModelOptions: 4,
       questionDialogWidth: 60,
       questionDialogMaxHeight: 14,
+      modelDialogWidth: 64,
+      modelDialogMaxHeight: 16,
       showHardwareCursor: true,
       color: false,
       title: 'DSH',
@@ -137,8 +153,11 @@ describe('TUI config', () => {
       showReasoning: false,
       maxToolOutputLines: 2,
       maxQuestionOptions: 3,
+      maxModelOptions: 4,
       questionDialogWidth: 60,
       questionDialogMaxHeight: 14,
+      modelDialogWidth: 64,
+      modelDialogMaxHeight: 16,
       showHardwareCursor: true,
       color: false,
       title: 'DSH',
@@ -148,7 +167,11 @@ describe('TUI config', () => {
 
 describe('pi-tui chat lifecycle and transcript', () => {
   it('renders its header, footer, replay, streaming answer, todos, and status', async () => {
+    let now = 0
     const result = await setup({
+      contextWindow: 100,
+      contextTokens: 42,
+      now: () => now,
       beforeMount(session) {
         appendUser(session, 'restored prompt')
         appendAssistant(session, [
@@ -174,9 +197,19 @@ describe('pi-tui chat lifecycle and transcript', () => {
     expect(result.terminal.output).toContain('restored answer')
     expect(result.terminal.output).toContain('write tests')
     expect(result.terminal.output).toContain('↑1.3k ↓42')
+    expect(result.terminal.output).toContain('42% context  tools:compact  deepseek-v4-flash(reasoning:on)')
+    result.terminal.resize(52)
+    await tick()
+    expect(result.terminal.output).toContain('42% context  deepseek-v4-flash(reasoning:on)')
+    result.terminal.resize(65)
+    await tick()
+    expect(result.terminal.output).toContain('↑1.3k ↓42 42% context  deepseek-v4-flash(reasoning:on)')
+    result.terminal.resize(88)
+    await tick()
 
     result.agent.status = 'running'
     result.ctx.emit('agent/status', result.agent, 'running')
+    now = 8_000
     result.session.append('user/message', { content: [{ type: 'text', text: '   ' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
     result.session.append('steering/message', { turn: 2, content: [{ type: 'text', text: 'steering note' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
     result.session.append('steering/message', { turn: 2, content: [{ type: 'text', text: '' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
@@ -254,13 +287,13 @@ describe('pi-tui chat lifecycle and transcript', () => {
     )
     await tick()
 
-    expect(result.terminal.output).toContain('Working')
+    expect(result.terminal.output).toContain('◒ Working · 8s')
+    expect(result.terminal.output).toContain('esc interrupt')
     expect(result.terminal.output).toContain('Steering')
     expect(result.terminal.output).toContain('user context')
     expect(result.terminal.output).toContain('Prompt blocked')
     expect(result.terminal.output).toContain('Turn cancelled')
     expect(result.terminal.output).toContain('final live answer')
-    expect(result.terminal.output).toContain('↑1.8k ↓50')
     expect(result.terminal.progress).toContain(true)
 
     result.session.append('assistant/chunk', {
@@ -277,6 +310,8 @@ describe('pi-tui chat lifecycle and transcript', () => {
     result.agent.status = 'idle'
     result.ctx.emit('agent/status', result.agent, 'idle')
     await tick()
+    expect(result.terminal.output).toContain('↑1.8k ↓50')
+    expect(result.terminal.output).toContain('deepseek-v4-flash(reasoning:off)')
     expect(result.terminal.progress.at(-1)).toBe(false)
     await dispose(result)
     expect(result.terminal.stopped).toBe(1)
@@ -446,6 +481,7 @@ describe('pi-tui chat lifecycle and transcript', () => {
     result.terminal.send('\r')
 
     result.agent.status = 'running'
+    result.ctx.emit('agent/status', result.agent, 'running')
     result.terminal.send('steer it')
     result.terminal.send('\r')
     expect(result.agent.steered).toEqual([[{ type: 'text', text: 'steer it' }]])
@@ -500,6 +536,162 @@ describe('pi-tui chat lifecycle and transcript', () => {
     await dispose(disposedAgent)
   })
 
+  it('opens a keyboard selector and switches the session model without sending slash text to the agent', async () => {
+    const result = await setup({
+      agentOptions: { provider: 'alpha', model: 'a1' },
+      catalog: {
+        providers: [{ id: 'alpha', name: 'Alpha' }, { id: 'beta', name: 'Beta' }],
+        models: [
+          { provider: 'alpha', id: 'a1', name: 'Alpha One', description: 'Fast' },
+          { provider: 'alpha', id: 'shared', name: 'Alpha Shared' },
+          { provider: 'beta', id: 'b1', name: 'Beta One' },
+          { provider: 'beta', id: 'shared', name: 'Beta Shared' },
+        ],
+      },
+    })
+
+    for (const command of ['/model too many model arguments', '/model missing', '/model shared', '/model alpha/a1', '/model alpha a1']) {
+      result.terminal.send(command)
+      result.terminal.send('\r')
+      await tick()
+    }
+    expect(result.terminal.output).toContain('Usage: /model')
+    expect(result.terminal.output).toContain('Unknown model: missing')
+    expect(result.terminal.output).toContain('advertised by multiple providers')
+    expect(result.terminal.output).toContain('already alpha/a1')
+
+    result.agent.status = 'running'
+    result.terminal.send('/model')
+    result.terminal.send('\r')
+    await tick()
+    expect(result.terminal.output).toContain('Select model')
+    expect(result.terminal.output).toContain('alpha/a1')
+    expect(result.terminal.output).toContain('Alpha One — Fast — current')
+    result.terminal.send('\x1b[B')
+    result.terminal.send('\x1b[B')
+    result.terminal.send('\r')
+    await tick()
+    expect(result.terminal.output).toContain('Model selected: beta/b1')
+    expect(result.agent.sent).toEqual([])
+    expect(result.agent.steered).toEqual([])
+
+    result.terminal.send('/model')
+    result.terminal.send('\r')
+    await tick()
+    result.terminal.send('\x1b')
+    await tick()
+    expect(result.agent.cancelled).not.toContain('cancelled from terminal')
+    result.agent.status = 'idle'
+    result.ctx.emit('agent/status', result.agent, 'idle')
+    await tick()
+    expect(result.terminal.output).toContain('tools:compact  b1(reasoning:on)')
+
+    const assembly = await result.ctx.systemPrompt.assemble(assembleContextFor(result.agent))
+    expect(assembly.variables).toMatchObject({ provider: 'beta', model: 'b1' })
+    const seed: LlmCallConfig = { provider: 'alpha', model: 'a1', temperature: 0.2 }
+    const request = await agentEvents(result.ctx, result.agent).waterfall(
+      'agent/request', 1, 0, seed, () => Promise.resolve(seed),
+    )
+    expect(request).toEqual({ provider: 'beta', model: 'b1', temperature: 0.2 })
+    await dispose(result)
+  })
+
+  it('restores the logged model, keeps an unlisted current model visible, and reports catalog failures', async () => {
+    const resumed = await setup({
+      agentOptions: { provider: 'alpha', model: 'configured' },
+      catalog: { providers: [{ id: 'beta', name: 'Beta' }], models: [] },
+      beforeMount(session) {
+        session.append('request/header', {
+          header: { config: { provider: 'beta', model: 'private' } },
+          reason: 'initial',
+        })
+      },
+    })
+    resumed.terminal.send('/model')
+    resumed.terminal.send('\r')
+    await tick()
+    expect(resumed.terminal.output).toContain('Select model')
+    expect(resumed.terminal.output).toContain('beta/private')
+    expect(resumed.terminal.output).toContain('private — current')
+    await dispose(resumed)
+
+    const unset = await setup({
+      agentOptions: {},
+      catalog: {
+        providers: [{ id: 'alpha', name: 'Alpha' }],
+        models: [{ provider: 'alpha', id: 'a1', name: 'Alpha One' }],
+      },
+    })
+    unset.terminal.send('/model')
+    unset.terminal.send('\r')
+    await tick()
+    unset.terminal.send('\r')
+    await tick()
+    expect(unset.terminal.output).toContain('Model selected: alpha/a1')
+    await dispose(unset)
+
+    const empty = await setup({ agentOptions: {}, catalog: { providers: [], models: [] } })
+    empty.terminal.send('/model')
+    empty.terminal.send('\r')
+    await tick()
+    expect(empty.terminal.output).toContain('Current model: unset')
+    expect(empty.terminal.output).toContain('No models are advertised')
+    const assembly = await empty.ctx.systemPrompt.assemble(assembleContextFor(empty.agent))
+    expect(assembly.variables).toEqual({})
+    const seed: LlmCallConfig = { provider: 'fallback', model: 'fallback' }
+    await expect(agentEvents(empty.ctx, empty.agent).waterfall(
+      'agent/request', 1, 0, seed, () => Promise.resolve(seed),
+    )).resolves.toBe(seed)
+    await dispose(empty)
+
+    const failed = await setup({
+      catalog: {
+        providers: [{ id: 'deepseek', name: 'DeepSeek' }],
+        models: [],
+        listModels: () => Promise.reject(new Error('catalog offline')),
+      },
+    })
+    failed.terminal.send('/model')
+    failed.terminal.send('\r')
+    await tick()
+    expect(failed.terminal.output).toContain('Could not read the model catalog: catalog offline')
+    await dispose(failed)
+  })
+
+  it('does not render a model catalog that resolves after TUI disposal', async () => {
+    const deferred = Promise.withResolvers<never[]>()
+    const result = await setup({
+      catalog: {
+        providers: [{ id: 'deepseek', name: 'DeepSeek' }],
+        models: [],
+        listModels: () => deferred.promise,
+      },
+    })
+    result.terminal.send('/model')
+    result.terminal.send('\r')
+    await result.controller.dispose()
+    deferred.resolve([])
+    await tick()
+    expect(result.terminal.output).not.toContain('Available models')
+    await result.ctx.fiber.dispose()
+
+    const rejected = Promise.withResolvers<never[]>()
+    const rejectedResult = await setup({
+      catalog: {
+        providers: [{ id: 'deepseek', name: 'DeepSeek' }],
+        models: [],
+        listModels: () => rejected.promise,
+      },
+    })
+    rejectedResult.terminal.send('/model')
+    rejectedResult.terminal.send('\r')
+    await rejectedResult.controller.dispose()
+    rejected.reject(new Error('late catalog failure'))
+    await tick()
+    expect(rejectedResult.terminal.output).not.toContain('late catalog failure')
+    await rejectedResult.ctx.fiber.dispose()
+  })
+
   it('discovers and executes plugin commands, then removes TUI-local commands on disposal', async () => {
     const result = await setup()
     const handler = vi.fn(({ rawInput }: CommandInvocation) => ({
@@ -701,7 +893,7 @@ describe('tool cards and surface replay', () => {
   }
 
   it('uses terminal, diff, generic, fallback, and collapsed tool presentations', async () => {
-    const result = await setup({ tools, config: { maxToolOutputLines: 1 } })
+    const result = await setup({ tools, config: { maxToolOutputLines: 4 } })
     const calls = [
       ['c1', 'bash', '{"command":"printf hello"}'],
       ['c2', 'signal', '{}'],
@@ -770,7 +962,7 @@ describe('tool cards and surface replay', () => {
     const output = result.terminal.output
     expect(output).toContain('Run command')
     expect(output).toContain('printf hello')
-    expect(output).toContain('more lines')
+    expect(output).toContain('lines (Ctrl+O to expand)')
     expect(output).toContain('SIGTERM')
     expect(output).toContain('Edit files')
     expect(output).toContain('Inspected')
@@ -787,6 +979,11 @@ describe('tool cards and surface replay', () => {
     result.terminal.send('/redraw')
     result.terminal.send('\r')
     await tick()
+    const collapsed = result.terminal.output.slice(result.terminal.output.lastIndexOf('\x1b[2J'))
+    expect(collapsed).toContain('Run command')
+    expect(collapsed).toContain('[exit 0]')
+    expect(collapsed).not.toContain('▌ hello')
+    expect(collapsed).not.toContain('world')
     result.terminal.send('\x0f')
     await tick()
     expect(result.terminal.output).toContain('world')
@@ -840,6 +1037,7 @@ describe('TUI user-interaction dialogs', () => {
     })
     await tick()
     expect(result.terminal.output).toContain('Choose a mode')
+    expect(result.terminal.output).toContain('Question 1/1 (1 unanswered) · Mode')
     expect(result.terminal.output).toContain('1/2')
     result.terminal.send('\x1b[B')
     result.terminal.send('\r')
@@ -859,7 +1057,7 @@ describe('TUI user-interaction dialogs', () => {
       questions: [{ id: 'other', question: 'Choose or type', options: [{ label: 'Default' }] }],
     })
     await tick()
-    result.terminal.send('c')
+    result.terminal.send('\t')
     result.terminal.send('my choice')
     result.terminal.send('\r')
     await expect(custom).resolves.toEqual({ answers: [{ id: 'other', selected: [], custom: 'my choice' }] })
@@ -933,9 +1131,11 @@ describe('TUI user-interaction dialogs', () => {
       ],
     })
     await tick()
+    expect(result.terminal.output).toContain('Question 1/2 (2 unanswered)')
     result.terminal.send('\r')
     await tick()
     expect(result.terminal.output).toContain('Second?')
+    expect(result.terminal.output).toContain('Question 2/2 (1 unanswered)')
     result.terminal.send('done')
     result.terminal.send('\r')
     await expect(batch).resolves.toEqual({ answers: [
@@ -982,6 +1182,7 @@ describe('TUI user-interaction dialogs', () => {
 describe('terminal mounting', () => {
   it('starts immediately when the configured agent already exists', async () => {
     const ctx = new Context()
+    provideTokenMeter(ctx)
     await ctx.plugin(SessionStore)
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(CommandService)
@@ -1001,6 +1202,7 @@ describe('terminal mounting', () => {
 
   it('waits for its configured agent before starting the TUI', async () => {
     const ctx = new Context()
+    provideTokenMeter(ctx)
     await ctx.plugin(SessionStore)
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(CommandService)
@@ -1030,6 +1232,7 @@ describe('terminal mounting', () => {
 
   it('prints a matching live startup failure and exits instead of waiting forever', async () => {
     const ctx = new Context()
+    provideTokenMeter(ctx)
     await ctx.plugin(SessionStore)
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(CommandService)
@@ -1058,6 +1261,7 @@ describe('terminal mounting', () => {
 
   it('renders an uncoercible startup failure without escaping the display boundary', async () => {
     const ctx = new Context()
+    provideTokenMeter(ctx)
     await ctx.plugin(SessionStore)
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(CommandService)
@@ -1079,6 +1283,7 @@ describe('terminal mounting', () => {
 
   it('rolls back providers, listeners, and terminal state when startup fails', async () => {
     const ctx = new Context()
+    provideTokenMeter(ctx)
     await ctx.plugin(SessionStore)
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(CommandService)
@@ -1112,6 +1317,7 @@ describe('terminal mounting', () => {
 
   it('throws when createTuiChat is called without the configured agent', async () => {
     const ctx = new Context()
+    provideTokenMeter(ctx)
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(CommandService)
     await ctx.plugin(UserInteractionService)

packages/ui/tui/tsconfig.json

@@ -26,6 +26,9 @@
     {
       "path": "../../llm/llm"
     },
+    {
+      "path": "../../llm/token-meter"
+    },
     {
       "path": "../../llm/llm-retry"
     },