feat(web): add workspace-aware session flow

2026-07-25 16:04:48 +08:00
parent 755e2a8c51
commit 9eb9c70a8a
170 changed files with 7573 additions and 3006 deletions
--- a/packages/host/apiproxy/README.md
+++ b/packages/host/apiproxy/README.md
@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-host-apiproxy

-The API gateway every client shape shares: the TS contract (`src/api/`, zero Node dependencies, importable from the browser), the fetch carrier pair (`src/fetch/`: `toFetchHandler` on the host side, `AbstractApiClient` plus platform subclasses on the client side), and the host-side implementation (`src/api-proxy.ts`: `createApiProxy` plus the default-exported `ApiProxyService` gateway plugin — config `{provider, model}`, provides `ctx.apiProxy`). Transport-agnostic by design: this package registers no routes; carriers (HTTP today, IPC later) wrap `ctx.apiProxy` themselves. The composition lives in `apps/cli/cordis.yml` (the `api-gateway` row).
+The API gateway every client shape shares: the TS contract (`src/api/`, zero Node dependencies, importable from the browser), the fetch carrier pair (`src/fetch/`: `toFetchHandler` on the host side, `AbstractApiClient` plus platform subclasses on the client side), and the host-side implementation (`src/api-proxy.ts`: `createApiProxy` plus the default-exported `ApiProxyService` gateway plugin — config `{provider, model, workspaceRoot?}`, provides `ctx.apiProxy`). Transport-agnostic by design: this package registers no routes; carriers (HTTP today, IPC later) wrap `ctx.apiProxy` themselves. The shipped core composition lives in [`apps/cli/cordis.yml`](../../../apps/cli/cordis.yml).

 ## Contract layer (`/api`)

@@ -10,6 +10,8 @@ The layering/protocol decisions are recorded in the [GUI layering and RPC protoc

 The mux stream projects the latest log-backed title as a validated `session/title` control frame after each attached-session subscription baseline and immediately after the corresponding live raw title event. This projection does not add titles to `session.list`; cold sessions remain metadata-only there until opening or resuming attaches their logs.

+Workspace and Session lists are separate reconnect baselines. `workspace.create` creates a unique name or adopts an existing directory, `session.create` accepts an optional preallocated Session id, and `host/workspace-changed` plus `host/session-added` carry committed increments in either arrival order. Session drafts are client-only and have no wire method.
+
 ## Carrier layer (`/client` + root)

 `AbstractApiClient` holds every protocol invariant — rpcId minting, envelope wrap/unwrap, zod parsing, SSE frame decoding, unary timeout, microtask-batched envelope observation (`subscribeEnvelopes`) — while platform subclasses supply only the `doFetch` transport aspect. `InProcessApiClient` over `toFetchHandler(api)` is the isomorphic point: the full wire serialization/validation path with no network, used by `dsh -p` headless.
--- a/packages/host/apiproxy/package.json
+++ b/packages/host/apiproxy/package.json
@@ -49,6 +49,7 @@
    "@deepseek-ai/dsh-tools": "workspace:^",
    "@deepseek-ai/dsh-user-approval": "workspace:^",
    "@deepseek-ai/dsh-user-interaction": "workspace:^",
+    "@deepseek-ai/dsh-workspace": "workspace:^",
    "schemastery": "^3.18.0",
    "zod": "^4.4.3"
  },
@@ -57,6 +58,8 @@
    "@deepseek-ai/dsh-invariants": "^0.0.1"
  },
  "devDependencies": {
+    "@deepseek-ai/dsh-storage": "workspace:^",
+    "@deepseek-ai/dsh-storage-domain": "workspace:^",
    "cordis": "^4.0.0-rc.7",
    "@deepseek-ai/dsh-invariants": "workspace:^"
  }
--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -5,16 +5,22 @@

 import { randomUUID } from 'node:crypto'
 import { mkdir, stat } from 'node:fs/promises'
+import { join } from 'node:path'
 import type { Context } from 'cordis'
 import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent'
 import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm'
 import type { JsonValue, Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence'
 import { foldSessionTitle } from '@deepseek-ai/dsh-session-title'
+import type { Workspace, WorkspaceRecord } from '@deepseek-ai/dsh-workspace'
+import {
+  workspaceDomainState, workspaceRecord, WorkspaceId as brandWorkspaceId, WorkspaceNameConflictError,
+} from '@deepseek-ai/dsh-workspace'
 // Type-only: brings the `ctx.tools` Context merge into this program (viewFor reads presenters).
 import type {} from '@deepseek-ai/dsh-tools'
 import type {
  ApiProxy, HistoryEntry, HostFrame, MuxFrame, QuestionResponsePayload, SessionSummary, ToolEventView,
+  WorkspaceId, WorkspaceView,
 } from './api/index.ts'
 import { questionResponsePayloadSchema } from './api/questions.schema.ts'
 import type { ClientResponse, RpcError, RpcReceipt, RpcRequest, RpcResponse } from './api/rpc.ts'
@@ -172,12 +178,14 @@ async function summarizeCold(persistence: SessionPersistence, meta: SessionHeade
  }
 }

-/** Host-level default agent routing: provider/model from the gateway config, cwd from the host process. */
+/** Resolved Host routing and project-directory defaults consumed by the API implementation. */
 export interface ApiProxyDefaults {
  provider: string
  model: string
  /** Default project directory for new sessions whose create request carries no cwd. */
  cwd: string
+  /** Parent directory for name-created workspaces. */
+  workspaceRoot: string
 }

 /** The tool/call payload fields the presenter path reads. */
@@ -273,17 +281,62 @@ function backscanArgs(events: readonly SessionEvent[], callId: string): { name:
 */
 class SessionNotFound extends Error {}

+/** Requested identity already belongs to a session with another project cwd. */
+class SessionCwdConflict extends Error {
+  constructor(
+    readonly sessionId: SessionId,
+    readonly requestedCwd: string,
+    readonly existingCwd: string | undefined,
+  ) {
+    super(
+      `session "${sessionId}" already exists with cwd ${JSON.stringify(existingCwd)}; `
+      + `requested ${JSON.stringify(requestedCwd)}`,
+    )
+  }
+}
+
+/** Host failed before the registry could adopt a name-created directory. */
+class WorkspaceDirectoryCreationError extends Error {}
+
+/** Wire projection of one workspace entity (the workspace.* value row). */
+function workspaceView(workspace: Workspace): WorkspaceView {
+  return {
+    workspaceId: workspace.id,
+    path: workspace.path,
+    title: workspace.title,
+    sessionIds: [...workspace.sessionIds],
+    createdAt: workspace.createdAt,
+    updatedAt: workspace.updatedAt,
+  }
+}
+
+/** Wire projection of the durable record carried by `domain/changed`. */
+function changedWorkspaceView(workspaceId: string, value: unknown): WorkspaceView {
+  const record: WorkspaceRecord = workspaceRecord.parse(value)
+  return {
+    workspaceId: workspaceId as WorkspaceId,
+    path: record.path,
+    title: record.title,
+    sessionIds: [...record.sessionIds],
+    createdAt: record.createdAt,
+    updatedAt: record.updatedAt,
+  }
+}
+
 /**
 * Implement ApiProxy over a composed host context.
- * @param ctx - a context with the host spine mounted (sessions/agents/tools/userInteraction services).
- * @param defaults - host-level default provider/model: injected as
- * agentOptions on create/resume, reported by describe from the same source.
+ * @param ctx - a context with the Host spine and Workspace registry mounted.
+ * @param defaults - host routing and project-directory defaults.
 * @returns the ApiProxy implementation.
 */
 export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiProxy {
  const agentOptions = { provider: defaults.provider, model: defaults.model }
  /** Implicit resume of cold sessions, deduplicating concurrent calls (follows the jsonrpc sessionCreations precedent). */
  const resumes = new Map<SessionId, Promise<Agent>>()
+  /** Client-chosen identity creation/resume, deduplicated across concurrent retries. */
+  const sessionCreations = new Map<SessionId, Promise<Agent>>()
+  /** Serializes path ownership checks with record creation across spellings. */
+  let workspaceCreationChain = Promise.resolve()
  const pendingQuestions = new Map<RpcId, PendingQuestion>()
  const muxQueues = new Set<FrameQueue<RpcRequest<MuxFrame>>>()

@@ -384,6 +437,78 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
    }
  }

+  /** Resolve one requested identity to a live agent, creating or resuming it once. */
+  async function ensureSession(sessionId: SessionId, cwd: string, checkPersistedIdentity: boolean): Promise<Agent> {
+    let creation = sessionCreations.get(sessionId)
+    if (creation === undefined) {
+      creation = (async () => {
+        const live = ctx.agents.get(sessionId)
+        if (live !== undefined) return live
+
+        const persistence = checkPersistedIdentity ? ctx.get('sessionPersistence') : undefined
+        const stored = persistence === undefined
+          ? undefined
+          : (await persistence.list()).find(header => header.id === sessionId)
+        if (stored !== undefined) {
+          if (stored.cwd !== cwd) {
+            throw new SessionCwdConflict(sessionId, cwd, stored.cwd)
+          }
+          return (await ctx.agents.resume({ resumeSessionId: sessionId, agentOptions })).agent
+        }
+
+        try {
+          await mkdir(cwd, { recursive: true })
+        } catch (error: unknown) {
+          throw new Error(`failed to ensure project directory "${cwd}": ${String(error)}`, { cause: error })
+        }
+        return (await ctx.agents.create({ sessionId, agentOptions, meta: { cwd } })).agent
+      })().catch((error: unknown) => {
+        // Another Host entry path may have published the same identity while
+        // this operation crossed an asynchronous persistence/filesystem step.
+        const live = ctx.agents.get(sessionId)
+        if (live !== undefined) return live
+        throw error
+      }).finally(() => {
+        sessionCreations.delete(sessionId)
+      })
+      sessionCreations.set(sessionId, creation)
+    }
+    const agent = await creation
+    if (agent.session.header.cwd !== cwd) {
+      throw new SessionCwdConflict(sessionId, cwd, agent.session.header.cwd)
+    }
+    return agent
+  }
+
+  /** Resolve or create one path while holding the Host's workspace-create chain. */
+  function ensureWorkspace(
+    path: string,
+    title: string | undefined,
+    rejectExistingName = false,
+    createDirectory = false,
+  ): Promise<{ workspace: Workspace; created: boolean }> {
+    const operation = workspaceCreationChain.then(async () => {
+      if (rejectExistingName && title !== undefined
+        && ctx.workspace.list().some(workspace => workspace.title === title)) {
+        throw new WorkspaceNameConflictError(title)
+      }
+      if (createDirectory) {
+        try {
+          await mkdir(path, { recursive: true })
+        } catch (error: unknown) {
+          throw new WorkspaceDirectoryCreationError(
+            `failed to create workspace directory "${path}": ${String(error)}`,
+          )
+        }
+      }
+      const existing = await ctx.workspace.resolveByPath(path)
+      if (existing !== undefined) return { workspace: existing, created: false }
+      return { workspace: await ctx.workspace.create(path, title), created: true }
+    })
+    workspaceCreationChain = operation.then(() => undefined, () => undefined)
+    return operation
+  }
+
  return {
    sessions: {
      // Attached sessions summarize from memory; persisted-but-unattached (cold)
@@ -406,23 +531,51 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
      },

      async create(request) {
-        const sessionId = `session-${randomUUID()}` as SessionId
-        // A session's cwd is its project path. When the creator does not choose
-        // one, the default project is the host-level default (the host process
-        // working directory unless boot overrides it). Ensure the directory
-        // exists so Create-workspace and typed paths land on a real folder.
-        const cwd = request.payload.cwd ?? defaults.cwd
+        const sessionId = request.payload.sessionId ?? `session-${randomUUID()}` as SessionId
+        let workspace: Workspace | undefined
+        if (request.payload.workspaceId !== undefined) {
+          workspace = ctx.workspace.get(brandWorkspaceId(request.payload.workspaceId))
+          if (workspace === undefined) {
+            return err(request, {
+              code: 'workspace-not-found',
+              message: `workspace "${request.payload.workspaceId}" not found`,
+              details: { workspaceId: request.payload.workspaceId },
+            })
+          }
+        }
+        const cwd = workspace?.path ?? request.payload.cwd ?? defaults.cwd
        try {
-          await mkdir(cwd, { recursive: true })
+          await ensureSession(sessionId, cwd, request.payload.sessionId !== undefined)
        } catch (error: unknown) {
+          if (error instanceof SessionCwdConflict) {
+            return err(request, {
+              code: 'session-conflict',
+              message: error.message,
+              details: {
+                sessionId: error.sessionId,
+                requestedCwd: error.requestedCwd,
+                ...error.existingCwd === undefined ? {} : { existingCwd: error.existingCwd },
+              },
+            })
+          }
          return err(request, {
            code: 'internal',
-            message: `failed to ensure project directory "${cwd}": ${String(error)}`,
+            message: `failed to create session "${sessionId}": ${String(error)}`,
            details: {},
          })
        }
-        const handle = await ctx.agents.create({ sessionId, agentOptions, meta: { cwd } })
-        return ok(request, { sessionId: handle.agent.id })
+        if (workspace !== undefined) {
+          try {
+            await workspace.attachSession(sessionId)
+          } catch (error: unknown) {
+            return err(request, {
+              code: 'workspace-attach-failed',
+              message: `session "${sessionId}" was created but could not attach to workspace "${workspace.id}": ${String(error)}`,
+              details: { sessionId, workspaceId: workspace.id },
+            })
+          }
+        }
+        return ok(request, { sessionId })
      },

      async history(request) {
@@ -472,12 +625,71 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
      },
    },

+    workspace: {
+      list(request) {
+        return Promise.resolve(ok(request, { items: ctx.workspace.list().map(workspaceView) }))
+      },
+
+      // Exactly one of path/name arrives (schema refine). Existing-folder
+      // adoption reuses its canonical path; create-by-name rejects a name
+      // already present in the registry.
+      async create(request) {
+        const { payload } = request
+        let path: string
+        if (payload.name !== undefined) {
+          const name = payload.name.trim()
+          if (name === '' || name === '.' || name === '..' || /[/\\]/.test(name)) {
+            return err(request, {
+              code: 'workspace-invalid-path',
+              message: `workspace name must be one non-empty path segment, got "${payload.name}"`,
+              details: { path: payload.name },
+            })
+          }
+          path = join(defaults.workspaceRoot, name)
+        } else {
+          path = payload.path as string
+        }
+        try {
+          const name = payload.name?.trim()
+          const { workspace, created } = await ensureWorkspace(
+            path,
+            name,
+            name !== undefined,
+            name !== undefined,
+          )
+          return ok(request, { workspace: workspaceView(workspace), created })
+        } catch (error: unknown) {
+          if (error instanceof WorkspaceNameConflictError) {
+            return err(request, {
+              code: 'workspace-name-conflict',
+              message: error.message,
+              details: { name: error.workspaceName },
+            })
+          }
+          if (error instanceof WorkspaceDirectoryCreationError) {
+            return err(request, { code: 'internal', message: error.message, details: {} })
+          }
+          // The registry rejects a path that does not resolve to an existing
+          // directory (realpath ENOENT / not-a-directory) — the business
+          // error of the typed-path flow, surfaced as a validation failure.
+          return err(request, {
+            code: 'workspace-invalid-path',
+            message: `cannot create a workspace at "${path}": ${error instanceof Error ? error.message : String(error)}`,
+            details: { path },
+          })
+        }
+      },
+
+    },
+
    host: {
      describe(request) {
        // TODO(step2): version should read apps/cli's package.json; placeholder for now.
        return Promise.resolve(ok(request, {
          version: '0.0.1',
-          cwd: process.cwd(),
+          // Same source as session.create's fallback: the UI's default project
+          // must match where an unspecified-cwd session actually lands.
+          cwd: defaults.cwd,
          provider: defaults.provider,
          model: defaults.model,
          attachedSessions: ctx.agents.list().length,
@@ -542,12 +754,17 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro

      host(_request, signal) {
        const queue = new FrameQueue<RpcRequest<HostFrame>>()
+        const committedWorkspaceIds = new Set(
+          ctx.workspace.list().map(workspace => String(workspace.id)),
+        )
        const disposers = [
          ctx.on('session/created', (session: Session) => {
            queue.push(frame({
              type: 'host/session-added',
              sessionId: session.id,
              ...session.header.parentSession === undefined ? {} : { parentSessionId: session.header.parentSession },
+              // cwd rides the frame so the client list needs no refresh to group the new session.
+              ...session.header.cwd === undefined ? {} : { cwd: session.header.cwd },
            }))
          }),
          ctx.on('session/disposed', (session: Session) => {
@@ -560,6 +777,29 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
          ctx.on('agent/error', (agent: Agent, _turn: number, _step: number, error: Error) => {
            queue.push(frame({ type: 'host/agent-error', sessionId: agent.id, message: String(error) }))
          }),
+          ctx.on('domain/changed', (change) => {
+            if (change.domain !== 'workspace' || change.operation !== 'put') return
+            if (change.table === '') {
+              const state = workspaceDomainState.parse(change.value)
+              for (const workspaceId of state.workspaceIds) {
+                if (committedWorkspaceIds.has(workspaceId)) continue
+                const workspace = ctx.workspace.get(workspaceId)
+                if (workspace === undefined) {
+                  throw new Error(`committed workspace registry references missing workspace "${workspaceId}"`)
+                }
+                committedWorkspaceIds.add(workspaceId)
+                queue.push(frame({ type: 'host/workspace-changed', workspace: workspaceView(workspace) }))
+              }
+              return
+            }
+            if (change.table !== 'workspaces' || !committedWorkspaceIds.has(change.key)) return
+            // Existing-entity table writes are complete attach/touch commits.
+            // A new entity's first put waits for the global registry write above.
+            queue.push(frame({
+              type: 'host/workspace-changed',
+              workspace: changedWorkspaceView(change.key, change.value),
+            }))
+          }),
        ]
        return queue.iterate(signal, () => { for (const dispose of disposers) dispose() })
      },
--- a/packages/host/apiproxy/src/api/events.schema.ts
+++ b/packages/host/apiproxy/src/api/events.schema.ts
@@ -11,6 +11,7 @@ import type { Wire } from './rpc.schema.ts'
 import { rpcErrorSchema, rpcIdSchema } from './rpc.schema.ts'
 import { approvalRequestIdSchema } from './approvals.schema.ts'
 import { sessionEventSchema, sessionIdSchema, toolEventViewSchema } from './sessions.schema.ts'
+import { workspaceViewSchema } from './workspace.schema.ts'

 /** Question shape validated strictly against core dsh-user-interaction. */
 export const askUserQuestionItemSchema = z.object({
@@ -39,9 +40,10 @@ export const muxFrameSchema = z.discriminatedUnion('type', [

 /** HostFrame union (payload slot of a host-stream ServerRequest). */
 export const hostFrameSchema = z.discriminatedUnion('type', [
-  z.object({ type: z.literal('host/session-added'), sessionId: sessionIdSchema, parentSessionId: sessionIdSchema.optional() }),
+  z.object({ type: z.literal('host/session-added'), sessionId: sessionIdSchema, parentSessionId: sessionIdSchema.optional(), cwd: z.string().optional() }),
  z.object({ type: z.literal('host/session-removed'), sessionId: sessionIdSchema }),
  z.object({ type: z.literal('host/session-status'), sessionId: sessionIdSchema, running: z.boolean() }),
  z.object({ type: z.literal('host/agent-error'), sessionId: sessionIdSchema, message: z.string() }),
+  z.object({ type: z.literal('host/workspace-changed'), workspace: workspaceViewSchema }),
  z.object({ type: z.literal('stream/error'), error: rpcErrorSchema }),
 ]) as unknown as z.ZodType<HostFrame>
--- a/packages/host/apiproxy/src/api/events.ts
+++ b/packages/host/apiproxy/src/api/events.ts
@@ -12,6 +12,7 @@ import type { CallId } from '@deepseek-ai/dsh-llm/brand'
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types'
 import type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-tools/presentation'
 import type { RpcError, RpcId, RpcRequest } from './rpc.ts'
+import type { WorkspaceView } from './workspace.ts'

 // Client-side consumers take the render-intent vocabulary from the contract;
 // dsh-tools remains its owner.
@@ -62,10 +63,18 @@ export type MuxFrame =
  | { type: 'question/resolved'; sessionId: SessionId; questionRpcId: RpcId; outcome: 'answered' | 'cancelled' }
  | { type: 'stream/error'; error: RpcError }

-/** Host stream frames. session-added carries the lineage anchor; agent-error is the only outlet for live failures with no turn position. */
+/**
+ * Host stream frames. session-added carries the lineage anchor and the
+ * project cwd (the list-summary fields a client cannot wait for a refresh to
+ * learn); agent-error is the only outlet for live failures with no turn
+ * position; workspace-changed pushes the full new snapshot after every
+ * durable workspace mutation (create/attach/order change — the client
+ * upserts, while `workspace.list` provides the reconnect baseline).
+ */
 export type HostFrame =
-  | { type: 'host/session-added'; sessionId: SessionId; parentSessionId?: SessionId }
+  | { type: 'host/session-added'; sessionId: SessionId; parentSessionId?: SessionId; cwd?: string }
  | { type: 'host/session-removed'; sessionId: SessionId }
  | { type: 'host/session-status'; sessionId: SessionId; running: boolean }
  | { type: 'host/agent-error'; sessionId: SessionId; message: string }
+  | { type: 'host/workspace-changed'; workspace: WorkspaceView }
  | { type: 'stream/error'; error: RpcError }
--- a/packages/host/apiproxy/src/api/index.ts
+++ b/packages/host/apiproxy/src/api/index.ts
@@ -6,6 +6,7 @@

 import type { SessionsApi } from './sessions.ts'
 import type { HostApi } from './host.ts'
+import type { WorkspaceApi } from './workspace.ts'
 import type { EventsApi } from './events.ts'
 import type { ClientResponse, RpcReceipt } from './rpc.ts'

@@ -13,6 +14,7 @@ import type { ClientResponse, RpcReceipt } from './rpc.ts'
 export interface ApiProxy {
  sessions: SessionsApi
  host: HostApi
+  workspace: WorkspaceApi
  events: EventsApi
  /** Response entry for server-requests (client-response, echoing their rpcId); not a domain method (four-quadrant model). */
  respond(message: ClientResponse): Promise<RpcReceipt>
@@ -21,6 +23,7 @@ export interface ApiProxy {
 // ---- Domain interfaces and payload entities ----
 export type { HistoryEntry, SessionsApi, SessionSummary } from './sessions.ts'
 export type { HostApi } from './host.ts'
+export type { WorkspaceApi, WorkspaceId, WorkspaceView } from './workspace.ts'
 export type { EventsApi, MuxFrame, HostFrame, ToolCallView, ToolEventView, ToolResultView } from './events.ts'
 export type { ApprovalResponsePayload } from './approvals.ts'
 export type { QuestionResponsePayload } from './questions.ts'
--- a/packages/host/apiproxy/src/api/rpc-map.ts
+++ b/packages/host/apiproxy/src/api/rpc-map.ts
@@ -6,6 +6,7 @@

 import type { SessionsApi } from './sessions.ts'
 import type { HostApi } from './host.ts'
+import type { WorkspaceApi } from './workspace.ts'
 import type { RpcResponse } from './rpc.ts'

 /** Method name → method signature. Signatures are the single source of truth; payload/value types are always derived from here. */
@@ -16,6 +17,8 @@ export interface RpcMethodMap {
  'session.prompt': SessionsApi['prompt']
  'session.cancel': SessionsApi['cancel']
  'host.describe': HostApi['describe']
+  'workspace.list': WorkspaceApi['list']
+  'workspace.create': WorkspaceApi['create']
 }

 /** Business request payload of method K (reaches through the RpcRequest narrow form to payload). */
--- a/packages/host/apiproxy/src/api/rpc.schema.ts
+++ b/packages/host/apiproxy/src/api/rpc.schema.ts
@@ -35,6 +35,11 @@ export const rpcErrorSchema: z.ZodType<RpcError> = z.discriminatedUnion('code',
  z.object({ code: z.literal('bad-request'), message: z.string(), details: z.object({ issues: z.array(z.custom<ZodIssue>()) }) }),
  z.object({ code: z.literal('cancelled'), message: z.string(), details: z.object({}) }),
  z.object({ code: z.literal('session-not-found'), message: z.string(), details: z.object({ sessionId: z.string() }) }),
+  z.object({ code: z.literal('session-conflict'), message: z.string(), details: z.object({ sessionId: z.string(), requestedCwd: z.string(), existingCwd: z.string().optional() }) }),
+  z.object({ code: z.literal('workspace-attach-failed'), message: z.string(), details: z.object({ sessionId: z.string(), workspaceId: z.string() }) }),
+  z.object({ code: z.literal('workspace-not-found'), message: z.string(), details: z.object({ workspaceId: z.string() }) }),
+  z.object({ code: z.literal('workspace-invalid-path'), message: z.string(), details: z.object({ path: z.string() }) }),
+  z.object({ code: z.literal('workspace-name-conflict'), message: z.string(), details: z.object({ name: z.string() }) }),
  z.object({ code: z.literal('agent-busy'), message: z.string(), details: z.object({ reason: z.string() }) }),
  z.object({ code: z.literal('internal'), message: z.string(), details: z.object({}) }),
 ]) as unknown as z.ZodType<RpcError>
--- a/packages/host/apiproxy/src/api/rpc.ts
+++ b/packages/host/apiproxy/src/api/rpc.ts
@@ -32,6 +32,11 @@ export interface RpcErrorDetailsMap {
  'bad-request': { issues: ZodIssue[] }
  'cancelled': {}
  'session-not-found': { sessionId: SessionId }
+  'session-conflict': { sessionId: SessionId; requestedCwd: string; existingCwd?: string }
+  'workspace-attach-failed': { sessionId: SessionId; workspaceId: string }
+  'workspace-not-found': { workspaceId: string }
+  'workspace-invalid-path': { path: string }
+  'workspace-name-conflict': { name: string }
  'agent-busy': { reason: string }
  'internal': {}
 }
--- a/packages/host/apiproxy/src/api/sessions.schema.ts
+++ b/packages/host/apiproxy/src/api/sessions.schema.ts
@@ -11,10 +11,19 @@ import type { RequestPayload, ResponseValue } from './rpc-map.ts'
 import type { Wire } from './rpc.schema.ts'
 import type { HistoryEntry, SessionSummary } from './sessions.ts'
 import type { ToolEventView } from './events.ts'
+import type { WorkspaceId } from './workspace.ts'

 /** SessionId: one brand cast after shape validation (the only cast point in this domain). */
 export const sessionIdSchema = z.string().min(1) as unknown as z.ZodType<SessionId>

+/**
+ * WorkspaceId: the workspace domain's one brand cast. Hosted here rather
+ * than in workspace.schema because session.create references it while
+ * workspace.schema references sessionIdSchema — schema modules must stay a
+ * DAG (both casts used at module top level; a cycle is a load-time TDZ).
+ */
+export const workspaceIdSchema = z.string().min(1) as unknown as z.ZodType<WorkspaceId>
+
 /** SessionEvent passthrough: strict envelope, wide data (the client fold handles unknown types via its documented default). */
 export const sessionEventSchema = z.object({
  type: z.string(),
@@ -44,10 +53,15 @@ export const sessionListValueSchema = z.object({
  items: z.array(sessionSummarySchema),
 }) satisfies z.ZodType<Wire<ResponseValue<'session.list'>>>

-/** session.create request payload. */
+/** session.create request payload (at most one of workspaceId / cwd). */
 export const sessionCreateRequestSchema = z.object({
+  workspaceId: workspaceIdSchema.optional(),
  cwd: z.string().optional(),
-}) satisfies z.ZodType<Wire<RequestPayload<'session.create'>>>
+  sessionId: sessionIdSchema.optional(),
+}).refine(
+  payload => payload.workspaceId === undefined || payload.cwd === undefined,
+  { message: 'session.create accepts workspaceId or cwd, not both' },
+) satisfies z.ZodType<Wire<RequestPayload<'session.create'>>>

 /** session.create response value. */
 export const sessionCreateValueSchema = z.object({
--- a/packages/host/apiproxy/src/api/sessions.ts
+++ b/packages/host/apiproxy/src/api/sessions.ts
@@ -8,6 +8,7 @@ import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types'
 import type { RpcId, RpcRequest, RpcResponse } from './rpc.ts'
 import type { ToolEventView } from './events.ts'
+import type { WorkspaceId } from './workspace.ts'

 declare module '@deepseek-ai/dsh-llm' {
  interface MessageSourceMap {
@@ -49,8 +50,16 @@ export interface SessionsApi {
  /** Lists persisted sessions (updatedAt descending). v1 returns everything; cursor is a reserved seat, unimplemented. */
  list(request: RpcRequest<{ cursor?: string }>): Promise<RpcResponse<{ items: SessionSummary[] }>>

-  /** Creates a new session (and its agent, idle and standing by). */
-  create(request: RpcRequest<{ cwd?: string }>): Promise<RpcResponse<{ sessionId: SessionId }>>
+  /**
+   * Creates a real session and its idle agent. At most one of `workspaceId` /
+   * `cwd` is accepted; an omitted project uses the Host cwd. A caller may
+   * preallocate `sessionId`: retries with the same id and cwd return the same
+   * session, while a different cwd fails with `session-conflict`.
+   * Workspace creation attaches the session after publication; an attach
+   * failure returns `workspace-attach-failed` with the published session id.
+   */
+  create(request: RpcRequest<{ workspaceId?: WorkspaceId; cwd?: string; sessionId?: SessionId }>):
+  Promise<RpcResponse<{ sessionId: SessionId }>>

  /**
   * Reads a window of history events; page boundaries align to message boundaries: one page =
--- a/packages/host/apiproxy/src/api/workspace.schema.ts
+++ b/packages/host/apiproxy/src/api/workspace.schema.ts
@@ -0,0 +1,46 @@
+/**
+ * workspace domain zod schemas (names derived from map keys). The
+ * WorkspaceId brand cast lives in sessions.schema (see the note there) and
+ * is re-exported here as the domain-local name.
+ */
+
+import { z } from 'zod'
+import type { RequestPayload, ResponseValue } from './rpc-map.ts'
+import type { Wire } from './rpc.schema.ts'
+import type { WorkspaceView } from './workspace.ts'
+import { sessionIdSchema, workspaceIdSchema } from './sessions.schema.ts'
+
+export { workspaceIdSchema } from './sessions.schema.ts'
+
+/** WorkspaceView row of every workspace.* response. */
+export const workspaceViewSchema = z.object({
+  workspaceId: workspaceIdSchema,
+  path: z.string(),
+  title: z.string(),
+  sessionIds: z.array(sessionIdSchema),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+}) satisfies z.ZodType<Wire<WorkspaceView>>
+
+/** workspace.list request payload (empty object literal). */
+export const workspaceListRequestSchema = z.object({}) satisfies z.ZodType<Wire<RequestPayload<'workspace.list'>>>
+
+/** workspace.list response value. */
+export const workspaceListValueSchema = z.object({
+  items: z.array(workspaceViewSchema),
+}) satisfies z.ZodType<Wire<ResponseValue<'workspace.list'>>>
+
+/** workspace.create request payload: exactly one of path/name (the contract's create spellings). */
+export const workspaceCreateRequestSchema = z.object({
+  path: z.string().optional(),
+  name: z.string().optional(),
+}).refine(
+  payload => (payload.path === undefined) !== (payload.name === undefined),
+  { message: 'workspace.create requires exactly one of path / name' },
+) satisfies z.ZodType<Wire<RequestPayload<'workspace.create'>>>
+
+/** workspace.create response value. */
+export const workspaceCreateValueSchema = z.object({
+  workspace: workspaceViewSchema,
+  created: z.boolean(),
+}) satisfies z.ZodType<Wire<ResponseValue<'workspace.create'>>>
--- a/packages/host/apiproxy/src/api/workspace.ts
+++ b/packages/host/apiproxy/src/api/workspace.ts
@@ -0,0 +1,55 @@
+/**
+ * workspace domain contract. Wire projection of the host-side workspace
+ * entity (@deepseek-ai/dsh-workspace): a stable id over a directory path,
+ * a display title, and the ordered session account. Method signatures are the
+ * source of truth, same as the sessions domain.
+ */
+
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { Branded } from '@deepseek-ai/dsh-brand'
+import type { RpcRequest, RpcResponse } from './rpc.ts'
+
+/**
+ * Wire-side workspace id brand. Deliberately re-declared here rather than
+ * imported from dsh-workspace: api/ must stay browser-importable with zero
+ * host-package dependencies, and the brand string matches, so both sides
+ * agree structurally.
+ */
+export type WorkspaceId = Branded<'WorkspaceId'>
+
+/** One workspace row: the record projection every workspace.* value carries. */
+export interface WorkspaceView {
+  workspaceId: WorkspaceId
+  /** Canonical directory path (host-side realpath canon). */
+  path: string
+  /** Unique display title (defaults to the path basename at create). */
+  title: string
+  /** Sessions accounted under this workspace, newest-first for display. */
+  sessionIds: SessionId[]
+  /** ISO-8601 creation instant. */
+  createdAt: string
+  /** ISO-8601 last-mutation instant. */
+  updatedAt: string
+}
+
+/** Workspace-domain unary methods (the map keys workspace.* of RpcMethodMap). */
+export interface WorkspaceApi {
+  /** Lists all workspaces in the registry's durable display order. */
+  list(request: RpcRequest<{}>): Promise<RpcResponse<{ items: WorkspaceView[] }>>
+
+  /**
+   * Creates (or idempotently resolves) a workspace. Exactly one of `path` /
+   * `name` (schema-enforced): `path` registers an EXISTING directory (no
+   * mkdir — a missing or non-directory path fails with `workspace-invalid-path`);
+   * `name` is a single path segment the host mkdirs under its default project
+   * root before registering. Either spelling resolving to a directory already
+   * owned by a workspace returns that workspace (`created: false`) for the
+   * existing-folder spelling. Create-by-name rejects an existing title with
+   * `workspace-name-conflict`; a new path whose basename duplicates another
+   * Workspace title is rejected by the registry with the same code.
+   * A new name-created workspace uses `name` as both directory name and title;
+   * a path-created workspace uses the registry's basename title default.
+   */
+  create(request: RpcRequest<{ path?: string; name?: string }>):
+  Promise<RpcResponse<{ workspace: WorkspaceView; created: boolean }>>
+}
--- a/packages/host/apiproxy/src/fetch/client.ts
+++ b/packages/host/apiproxy/src/fetch/client.ts
@@ -21,6 +21,10 @@ import {
  sessionListValueSchema,
  sessionPromptValueSchema,
 } from '../api/sessions.schema.ts'
+import {
+  workspaceCreateValueSchema,
+  workspaceListValueSchema,
+} from '../api/workspace.schema.ts'

 /**
 * Client consumption face of the contract (shape a): same domain tree as ApiProxy, but unary
@@ -48,6 +52,10 @@ export interface IApiClient {
  host: {
    describe(payload: RequestPayload<'host.describe'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'host.describe'>>>
  }
+  workspace: {
+    list(payload: RequestPayload<'workspace.list'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'workspace.list'>>>
+    create(payload: RequestPayload<'workspace.create'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'workspace.create'>>>
+  }
  events: {
    mux(payload: Parameters<ApiProxy['events']['mux']>[0]['payload'], signal: AbortSignal, onOpen?: () => void): AsyncIterable<RpcRequest<MuxFrame>>
    host(payload: Parameters<ApiProxy['events']['host']>[0]['payload'], signal: AbortSignal, onOpen?: () => void): AsyncIterable<RpcRequest<HostFrame>>
@@ -67,6 +75,8 @@ const UNARY_VALUE_SCHEMAS: { [K in keyof RpcMethodMap]: z.ZodType<Wire<ResponseV
  'session.prompt': sessionPromptValueSchema,
  'session.cancel': sessionCancelValueSchema,
  'host.describe': hostDescribeValueSchema,
+  'workspace.list': workspaceListValueSchema,
+  'workspace.create': workspaceCreateValueSchema,
 }

 /** Default unary timeout (rpc-compare 2026-07-19: a hung host must not leave callers pending forever). */
@@ -253,6 +263,11 @@ export abstract class AbstractApiClient implements IApiClient {
    describe: (payload, signal) => this.callUnary('host.describe', payload, signal),
  }

+  readonly workspace: IApiClient['workspace'] = {
+    list: (payload, signal) => this.callUnary('workspace.list', payload, signal),
+    create: (payload, signal) => this.callUnary('workspace.create', payload, signal),
+  }
+
  readonly events: IApiClient['events'] = {
    mux: (payload, signal, onOpen) => this.openMux(payload, signal, onOpen),
    host: (payload, signal, onOpen) => this.openHost(payload, signal, onOpen),
--- a/packages/host/apiproxy/src/fetch/handler.ts
+++ b/packages/host/apiproxy/src/fetch/handler.ts
@@ -22,6 +22,10 @@ import {
  sessionPromptRequestSchema,
 } from '../api/sessions.schema.ts'
 import { hostDescribeRequestSchema } from '../api/host.schema.ts'
+import {
+  workspaceCreateRequestSchema,
+  workspaceListRequestSchema,
+} from '../api/workspace.schema.ts'

 /**
 * Unary dispatch table, keyed by (and compiler-locked to) RpcMethodMap: a map row without a
@@ -44,6 +48,8 @@ const UNARY_ROUTES: UnaryRoutes = {
  'session.prompt': { schema: sessionPromptRequestSchema, invoke: (api, r) => api.sessions.prompt(r) },
  'session.cancel': { schema: sessionCancelRequestSchema, invoke: (api, r) => api.sessions.cancel(r) },
  'host.describe': { schema: hostDescribeRequestSchema, invoke: (api, r) => api.host.describe(r) },
+  'workspace.list': { schema: workspaceListRequestSchema, invoke: (api, r) => api.workspace.list(r) },
+  'workspace.create': { schema: workspaceCreateRequestSchema, invoke: (api, r) => api.workspace.create(r) },
 }

 /** Route lookup that narrows an arbitrary path segment to a map key (single cast point for the string→key refinement). */
--- a/packages/host/apiproxy/src/index.ts
+++ b/packages/host/apiproxy/src/index.ts
@@ -8,6 +8,7 @@
 * routes — carriers (HTTP today, IPC later) wrap `ctx.apiProxy` themselves.
 */

+import { resolve } from 'node:path'
 import { Context, Service } from 'cordis'
 import z from 'schemastery'
 import type { ApiProxy } from './api/index.ts'
@@ -28,37 +29,47 @@ declare module 'cordis' {
  }
 }

-/** Gateway plugin config: the host-level default agent routing. */
+/** Gateway plugin config: host-level agent routing and Workspace creation root. */
 export interface Config {
  /** Default provider route for created/resumed agents. */
  provider: string
  /** Default model id. */
  model: string
+  /** Parent directory for name-created Workspaces; defaults to the Host cwd. */
+  workspaceRoot?: string
 }

 /**
 * The API gateway service: implements the ApiProxy contract over the composed
- * host context and provides it as `ctx.apiProxy`. The default project
- * directory for new sessions is the host process working directory (not a
- * config field this round).
+ * host context and provides it as `ctx.apiProxy`. The Host cwd is the default
+ * project directory and the fallback parent for name-created Workspaces.
 */
 export class ApiProxyService extends Service implements ApiProxy {
-  static inject = ['agents', 'sessions', 'tools', 'userInteraction']
+  static inject = ['agents', 'sessions', 'tools', 'userInteraction', 'workspace']

  static Config: z<Config> = z.object({
    provider: z.string().required(),
    model: z.string().required(),
+    workspaceRoot: z.string(),
  })

  readonly sessions: ApiProxy['sessions']
+  readonly workspace: ApiProxy['workspace']
  readonly host: ApiProxy['host']
  readonly events: ApiProxy['events']
  readonly respond: ApiProxy['respond']

  constructor(ctx: Context, config: Config) {
    super(ctx, 'apiProxy')
-    const api = createApiProxy(ctx, { provider: config.provider, model: config.model, cwd: process.cwd() })
+    const cwd = process.cwd()
+    const api = createApiProxy(ctx, {
+      provider: config.provider,
+      model: config.model,
+      cwd,
+      workspaceRoot: resolve(config.workspaceRoot ?? cwd),
+    })
    this.sessions = api.sessions
+    this.workspace = api.workspace
    this.host = api.host
    this.events = api.events
    // createApiProxy returns closures (no `this` capture); bind only satisfies
--- a/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
@@ -55,7 +55,7 @@ describe('sessions.list cold merge', () => {
        return undefined
      },
    })
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
+    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })

    const response = await api.sessions.list(request({}))
    expect(response.result.ok).toBe(true)
@@ -79,7 +79,7 @@ describe('degenerate composition (no persistence, no factory)', () => {
    await ctx.plugin(SessionStore)
    await ctx.plugin(AgentRegistry)
    await ctx.plugin(UserInteractionService)
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
+    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })

    const listed = await api.sessions.list(request({}))
    expect(listed.result.ok).toBe(true)
--- a/packages/host/apiproxy/tests/api-proxy-view.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-view.spec.ts
@@ -76,7 +76,7 @@ async function collect(iterable: AsyncIterable<RpcRequest<MuxFrame>>, count: num
 describe('mux live view computation', () => {
  it('attaches the three standard card views, omits view without a presenter, soft-falls on throw', async () => {
    const { ctx } = await harness()
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
+    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
    const abort = new AbortController()
    const stream = api.events.mux({ rpcId: RpcId('t-mux'), payload: {} }, abort.signal)
    const collected = collect(stream, 9, abort)
@@ -122,7 +122,7 @@ describe('mux live view computation', () => {

  it('serves history entries with call/result views, backscan pairing, and soft-falls', async () => {
    const { ctx } = await harness()
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
+    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
    const session = ctx.sessions.create()
    // history resolves the agent first; a live structural stub is enough (only
    // .session is read on this path).
@@ -156,7 +156,7 @@ describe('mux live view computation', () => {

  it('drops a disposed session from the live open-call table (result after dispose gets no view)', async () => {
    const { ctx } = await harness()
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
+    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
    const abort = new AbortController()
    const stream = api.events.mux({ rpcId: RpcId('t-mux3'), payload: {} }, abort.signal)

@@ -177,7 +177,7 @@ describe('mux live view computation', () => {

  it('pairs a result after turn/end via the in-memory backscan fallback', async () => {
    const { ctx } = await harness()
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
+    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
    const abort = new AbortController()
    const stream = api.events.mux({ rpcId: RpcId('t-mux2'), payload: {} }, abort.signal)
    const collected = collect(stream, 4, abort)
--- a/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts
@@ -0,0 +1,246 @@
+import { existsSync, mkdirSync, mkdtempSync, realpathSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import AgentRegistry, { AgentMessageId } from '@deepseek-ai/dsh-agent'
+import type { Agent, AgentFactory } from '@deepseek-ai/dsh-agent'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import type { Session } from '@deepseek-ai/dsh-session'
+import Storage from '@deepseek-ai/dsh-storage'
+import { DomainFacility } from '@deepseek-ai/dsh-storage-domain'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
+import WorkspaceRegistry from '@deepseek-ai/dsh-workspace'
+import type { HostFrame, WorkspaceId } from '@deepseek-ai/dsh-host-apiproxy/api'
+import type { RpcRequest, RpcResponse } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import { createApiProxy } from '@deepseek-ai/dsh-host-apiproxy'
+import { MemoryStorageBackend } from '../../../storage/storage-domain/tests/helpers/memory-backend.ts'
+
+let nextRpc = 1
+
+function request<P>(payload: P): RpcRequest<P> {
+  return { rpcId: RpcId(`workspace-${String(nextRpc++)}`), payload }
+}
+
+function expectOk<T>(response: RpcResponse<T>): T {
+  expect(response.result.ok).toBe(true)
+  if (!response.result.ok) throw new Error('unreachable')
+  return response.result.value
+}
+
+async function nextHostFrame(
+  stream: AsyncIterator<RpcRequest<HostFrame>>,
+): Promise<RpcRequest<HostFrame>> {
+  const next = await stream.next()
+  if (next.done === true) throw new Error('Host stream ended before the expected increment')
+  return next.value
+}
+
+function stubAgent(session: Session): Agent {
+  return {
+    id: session.id,
+    options: {},
+    session,
+    status: 'idle',
+    ctx: new Context(),
+    followup: () => AgentMessageId('stub'),
+    queue: () => AgentMessageId('stub'),
+    steer: () => AgentMessageId('stub'),
+    inject: () => AgentMessageId('stub'),
+    send: () => AgentMessageId('stub'),
+    cancel() {},
+    whenIdle: () => Promise.resolve(),
+  }
+}
+
+/** Compose the API over real Session, Agent, Storage, Domain, and Workspace services. */
+async function harness(
+  workspaceRoot = realpathSync(mkdtempSync(join(tmpdir(), 'dsh-apiproxy-workspace-'))),
+) {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(UserInteractionService)
+  await ctx.plugin(Storage)
+  ctx.storage.backend.register('memory', new MemoryStorageBackend())
+  const storageDomain = new DomainFacility(ctx, { backend: 'memory', routes: {} })
+  ctx.storage.mount('domain', storageDomain)
+  ctx.provide('storageDomain', storageDomain)
+  ctx.provide('sessionPersistence', { list: () => Promise.resolve([]) } as never)
+  await ctx.plugin(WorkspaceRegistry)
+
+  const factory: AgentFactory = {
+    async createAgent(_ownerCtx, options) {
+      const session = ctx.sessions.create(
+        options.sessionId,
+        options.meta === undefined ? {} : { meta: options.meta },
+      )
+      const agent = stubAgent(session)
+      const unregister = ctx.agents.register(agent)
+      return {
+        agent,
+        dispose: () => {
+          unregister()
+          return Promise.resolve()
+        },
+      }
+    },
+    async resume() {
+      throw new Error('test harness has no persisted sessions')
+    },
+  }
+  ctx.agents.setFactory(factory)
+  const api = createApiProxy(ctx, {
+    provider: 'test',
+    model: 'test-model',
+    cwd: workspaceRoot,
+    workspaceRoot,
+  })
+  return { api, ctx, storageDomain, workspaceRoot }
+}
+
+describe('workspace.create', () => {
+  it('serializes concurrent names and rejects the duplicate', async () => {
+    const { api, workspaceRoot } = await harness()
+    const responses = await Promise.all([
+      api.workspace.create(request({ name: 'alpha' })),
+      api.workspace.create(request({ name: 'alpha' })),
+    ])
+    const created = responses.find(response => response.result.ok)
+    const duplicate = responses.find(response => !response.result.ok)
+
+    expect(created).toBeDefined()
+    expect(expectOk(created!)).toMatchObject({
+      created: true,
+      workspace: { path: join(workspaceRoot, 'alpha'), title: 'alpha' },
+    })
+    expect(duplicate?.result).toMatchObject({
+      ok: false,
+      error: { code: 'workspace-name-conflict', details: { name: 'alpha' } },
+    })
+    expect(existsSync(join(workspaceRoot, 'alpha'))).toBe(true)
+  })
+
+  it('adopts only existing directories and rejects unsafe names', async () => {
+    const { api, workspaceRoot } = await harness()
+    const existing = join(workspaceRoot, 'existing')
+    mkdirSync(existing)
+    const first = expectOk(await api.workspace.create(request({ path: existing })))
+    const repeated = expectOk(await api.workspace.create(request({ path: existing })))
+    expect(first).toMatchObject({ created: true, workspace: { path: existing, title: 'existing' } })
+    expect(repeated).toMatchObject({ created: false, workspace: { workspaceId: first.workspace.workspaceId } })
+
+    const missing = join(workspaceRoot, 'missing')
+    const missingResult = await api.workspace.create(request({ path: missing }))
+    expect(missingResult.result).toMatchObject({ ok: false, error: { code: 'workspace-invalid-path' } })
+    expect(existsSync(missing)).toBe(false)
+
+    for (const name of ['', '.', '..', 'a/b', 'a\\b']) {
+      const invalid = await api.workspace.create(request({ name }))
+      expect(invalid.result).toMatchObject({ ok: false, error: { code: 'workspace-invalid-path' } })
+    }
+  })
+})
+
+describe('session creation and Workspace membership', () => {
+  it('attaches a preallocated idempotent session while cwd-only sessions stay ungrouped', async () => {
+    const { api, ctx } = await harness()
+    const workspace = expectOk(await api.workspace.create(request({ name: 'project' }))).workspace
+    const sessionId = SessionId('session-workspace-preallocated')
+
+    expectOk(await api.sessions.create(request({ workspaceId: workspace.workspaceId, sessionId })))
+    expectOk(await api.sessions.create(request({ workspaceId: workspace.workspaceId, sessionId })))
+    expect(expectOk(await api.workspace.list(request({}))).items[0]?.sessionIds).toEqual([sessionId])
+    expect(ctx.agents.list().filter(agent => agent.id === sessionId)).toHaveLength(1)
+
+    const ungrouped = SessionId('session-cwd-only')
+    expectOk(await api.sessions.create(request({ cwd: workspace.path, sessionId: ungrouped })))
+    expect(expectOk(await api.workspace.list(request({}))).items[0]?.sessionIds).toEqual([sessionId])
+    expect(expectOk(await api.sessions.list(request({}))).items.map(item => item.sessionId)).toContain(ungrouped)
+
+    const conflict = await api.sessions.create(request({ cwd: join(workspace.path, 'other'), sessionId }))
+    expect(conflict.result).toMatchObject({
+      ok: false,
+      error: { code: 'session-conflict', details: { sessionId, existingCwd: workspace.path } },
+    })
+    const missing = await api.sessions.create(request({
+      workspaceId: 'missing-workspace' as WorkspaceId,
+      sessionId: SessionId('session-missing-workspace'),
+    }))
+    expect(missing.result).toMatchObject({ ok: false, error: { code: 'workspace-not-found' } })
+  })
+
+  it('retains a published session when attachment fails and repairs it on retry', async () => {
+    const { api, ctx } = await harness()
+    const created = expectOk(await api.workspace.create(request({ name: 'project' }))).workspace
+    const workspace = ctx.workspace.list()[0]
+    if (workspace === undefined) throw new Error('workspace missing from registry')
+    vi.spyOn(workspace, 'attachSession').mockRejectedValueOnce(new Error('simulated write failure'))
+    const sessionId = SessionId('session-attach-retry')
+
+    const failed = await api.sessions.create(request({ workspaceId: created.workspaceId, sessionId }))
+    expect(failed.result).toMatchObject({
+      ok: false,
+      error: { code: 'workspace-attach-failed', details: { sessionId, workspaceId: created.workspaceId } },
+    })
+    expect(ctx.agents.get(sessionId)).toBeDefined()
+
+    expectOk(await api.sessions.create(request({ workspaceId: created.workspaceId, sessionId })))
+    expect(expectOk(await api.workspace.list(request({}))).items[0]?.sessionIds).toEqual([sessionId])
+  })
+})
+
+describe('Host Workspace increments', () => {
+  it('streams committed Workspace and Session increments after empty baselines', async () => {
+    const { api } = await harness()
+    expect(expectOk(await api.workspace.list(request({}))).items).toEqual([])
+    expect(expectOk(await api.sessions.list(request({}))).items).toEqual([])
+
+    const abort = new AbortController()
+    const stream: AsyncIterator<RpcRequest<HostFrame>> =
+      api.events.host(request({}), abort.signal)[Symbol.asyncIterator]()
+    const workspaceIncrement = nextHostFrame(stream)
+    const workspace = expectOk(await api.workspace.create(request({ name: 'project' }))).workspace
+    expect(await workspaceIncrement).toMatchObject({
+      payload: { type: 'host/workspace-changed', workspace: { workspaceId: workspace.workspaceId } },
+    })
+
+    const sessionId = SessionId('session-streamed-workspace')
+    const pending = nextHostFrame(stream)
+    expectOk(await api.sessions.create(request({ workspaceId: workspace.workspaceId, sessionId })))
+    const increments: HostFrame[] = []
+    increments.push((await pending).payload)
+    while (increments.length < 2) {
+      const next = await stream.next()
+      if (next.done === true) throw new Error('Host stream ended before both increments')
+      increments.push(next.value.payload)
+    }
+    expect(increments.find(increment => increment.type === 'host/session-added')).toMatchObject({
+      type: 'host/session-added', sessionId, cwd: workspace.path,
+    })
+    const workspaceChanged = increments.find(
+      (increment): increment is Extract<HostFrame, { type: 'host/workspace-changed' }> =>
+        increment.type === 'host/workspace-changed',
+    )
+    expect(workspaceChanged?.workspace.sessionIds).toEqual([sessionId])
+    abort.abort()
+  })
+
+  it('does not publish a Workspace whose registry-order commit fails', async () => {
+    const { api, storageDomain } = await harness()
+    const domain = storageDomain.get('workspace')
+    if (domain === undefined) throw new Error('workspace domain is not open')
+    vi.spyOn(domain.global, 'set').mockRejectedValueOnce(new Error('simulated registry order failure'))
+    const abort = new AbortController()
+    const stream: AsyncIterator<RpcRequest<HostFrame>> =
+      api.events.host(request({}), abort.signal)[Symbol.asyncIterator]()
+    const next = stream.next()
+
+    const failed = await api.workspace.create(request({ name: 'ghost' }))
+    expect(failed.result.ok).toBe(false)
+    expect(expectOk(await api.workspace.list(request({}))).items).toEqual([])
+    abort.abort()
+    expect(await next).toMatchObject({ done: true })
+  })
+})
--- a/packages/host/apiproxy/tests/client-handler.spec.ts
+++ b/packages/host/apiproxy/tests/client-handler.spec.ts
@@ -34,6 +34,10 @@ function scriptedApi(overrides: {
      ...overrides.sessions,
    },
    host: { describe: r => ok(r, { version: '0-test', cwd: '/t', attachedSessions: 0 }), ...overrides.host },
+    workspace: {
+      list: r => ok(r, { items: [] }),
+      create: r => ok(r, { workspace: { workspaceId: 'w1' as never, path: '/t', title: 't', sessionIds: [], createdAt: '0', updatedAt: '0' }, created: true }),
+    },
    events: { mux: () => empty<MuxFrame>(), host: () => empty<HostFrame>(), ...overrides.events },
    respond: overrides.respond ?? (() => Promise.resolve({ accepted: false as const, reason: 'not-pending' as const })),
  }
@@ -190,6 +194,23 @@ describe('unary round trip', () => {
  })
 })

+describe('workspace domain round trip', () => {
+  it('routes both workspace methods through their handler rows and value schemas', async () => {
+    const c = client(scriptedApi())
+    const list = await c.workspace.list({})
+    expect(list.result).toEqual({ ok: true, value: { items: [] } })
+    const created = await c.workspace.create({ path: '/t' })
+    expect(created.result.ok).toBe(true)
+    if (created.result.ok) expect(created.result.value.created).toBe(true)
+  })
+
+  it('rejects a create payload violating the exactly-one refine at the handler', async () => {
+    const response = await client(scriptedApi()).workspace.create({})
+    expect(response.result.ok).toBe(false)
+    if (!response.result.ok) expect(response.result.error.code).toBe('bad-request')
+  })
+})
+
 describe('SSE stream path', () => {
  it('yields frames in order and skips the comment preamble', async () => {
    const frames: MuxFrame[] = [
--- a/packages/host/apiproxy/tests/fetch-carrier.spec.ts
+++ b/packages/host/apiproxy/tests/fetch-carrier.spec.ts
@@ -42,6 +42,17 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
        return { rpcId: request.rpcId, result: { ok: true, value: { version: 'v', cwd: '/w', attachedSessions: 0 } } }
      },
    },
+    workspace: {
+      async list(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { items: [] } } }
+      },
+      async create(request) {
+        return {
+          rpcId: request.rpcId,
+          result: { ok: true, value: { workspace: { workspaceId: 'w1' as never, path: '/w', title: 'w', sessionIds: [], createdAt: 't', updatedAt: 't' }, created: true } },
+        }
+      },
+    },
    events: {
      mux: (_request, signal) => stream(muxFrames, signal),
      host: (_request, signal) => stream(hostFrames, signal),
--- a/packages/host/apiproxy/tests/rpc-schemas.spec.ts
+++ b/packages/host/apiproxy/tests/rpc-schemas.spec.ts
@@ -12,6 +12,10 @@ import {
  sessionPromptValueSchema, sessionSummarySchema,
 } from '../src/api/sessions.schema.ts'
 import { hostDescribeRequestSchema, hostDescribeValueSchema } from '../src/api/host.schema.ts'
+import {
+  workspaceCreateRequestSchema, workspaceCreateValueSchema, workspaceIdSchema, workspaceListRequestSchema,
+  workspaceListValueSchema, workspaceViewSchema,
+} from '../src/api/workspace.schema.ts'
 import { hostFrameSchema, muxFrameSchema, askUserQuestionItemSchema } from '../src/api/events.schema.ts'
 import { approvalRequestIdSchema, approvalResponsePayloadSchema } from '../src/api/approvals.schema.ts'
 import { askUserQuestionAnswerSchema, questionResponsePayloadSchema } from '../src/api/questions.schema.ts'
@@ -31,6 +35,11 @@ describe('rpcErrorSchema', () => {
    expect(rpcErrorSchema.parse({ code: 'bad-request', message: 'm', details: { issues: [] } }).code).toBe('bad-request')
    expect(rpcErrorSchema.parse({ code: 'cancelled', message: 'm', details: {} }).code).toBe('cancelled')
    expect(rpcErrorSchema.parse({ code: 'session-not-found', message: 'm', details: { sessionId: 's' } }).code).toBe('session-not-found')
+    expect(rpcErrorSchema.parse({ code: 'session-conflict', message: 'm', details: { sessionId: 's', requestedCwd: '/a', existingCwd: '/b' } }).code).toBe('session-conflict')
+    expect(rpcErrorSchema.parse({ code: 'workspace-attach-failed', message: 'm', details: { sessionId: 's', workspaceId: 'w' } }).code).toBe('workspace-attach-failed')
+    expect(rpcErrorSchema.parse({ code: 'workspace-not-found', message: 'm', details: { workspaceId: 'w' } }).code).toBe('workspace-not-found')
+    expect(rpcErrorSchema.parse({ code: 'workspace-invalid-path', message: 'm', details: { path: '/x' } }).code).toBe('workspace-invalid-path')
+    expect(rpcErrorSchema.parse({ code: 'workspace-name-conflict', message: 'm', details: { name: 'x' } }).code).toBe('workspace-name-conflict')
    expect(rpcErrorSchema.parse({ code: 'agent-busy', message: 'm', details: { reason: 'r' } }).code).toBe('agent-busy')
    expect(rpcErrorSchema.parse({ code: 'internal', message: 'm', details: {} }).code).toBe('internal')
  })
@@ -96,6 +105,9 @@ describe('sessions domain schemas', () => {
    expect(sessionListRequestSchema.parse({ cursor: 'c' }).cursor).toBe('c')
    expect(sessionListValueSchema.parse({ items: [] }).items).toEqual([])
    expect(sessionCreateRequestSchema.parse({ cwd: '/w' }).cwd).toBe('/w')
+    // The refine's both-sides branch: workspaceId alone passes, workspaceId+cwd rejects.
+    expect(sessionCreateRequestSchema.parse({ workspaceId: 'w1', sessionId: 's1' }).sessionId).toBe('s1')
+    expect(() => sessionCreateRequestSchema.parse({ workspaceId: 'w1', cwd: '/w' })).toThrow(/not both/)
    expect(sessionCreateValueSchema.parse({ sessionId: 's1' }).sessionId).toBe('s1')
    expect(sessionHistoryRequestSchema.parse({ sessionId: 's1', beforeSeq: 3, maxMessages: 5 }).beforeSeq).toBe(3)
    expect(() => sessionHistoryRequestSchema.parse({ sessionId: 's1', maxMessages: 0 })).toThrow()
@@ -119,6 +131,31 @@ describe('host domain schemas', () => {
  })
 })

+describe('workspace domain schemas', () => {
+  const view = {
+    workspaceId: 'w1', path: '/p', title: 'p', sessionIds: ['s1'],
+    createdAt: '2026-07-25T00:00:00.000Z', updatedAt: '2026-07-25T00:00:00.000Z',
+  }
+
+  it('validates ids, the view row, and list request/value', () => {
+    expect(workspaceIdSchema.parse('w1')).toBe('w1')
+    expect(() => workspaceIdSchema.parse('')).toThrow()
+    expect(workspaceViewSchema.parse(view).sessionIds).toEqual(['s1'])
+    expect(() => workspaceViewSchema.parse({ ...view, sessionIds: 's1' })).toThrow()
+    expect(workspaceListRequestSchema.parse({})).toEqual({})
+    expect(workspaceListValueSchema.parse({ items: [view] }).items).toHaveLength(1)
+  })
+
+  it('create requires exactly one of path/name (both refine arms)', () => {
+    expect(workspaceCreateRequestSchema.parse({ path: '/p' }).path).toBe('/p')
+    expect(workspaceCreateRequestSchema.parse({ name: 'n' }).name).toBe('n')
+    expect(() => workspaceCreateRequestSchema.parse({})).toThrow(/exactly one/)
+    expect(() => workspaceCreateRequestSchema.parse({ path: '/p', name: 'n' })).toThrow(/exactly one/)
+    expect(workspaceCreateValueSchema.parse({ workspace: view, created: false }).created).toBe(false)
+  })
+
+})
+
 describe('events frame schemas', () => {
  it('accepts every mux frame branch', () => {
    const frames = [
--- a/packages/host/apiproxy/tsconfig.json
+++ b/packages/host/apiproxy/tsconfig.json
@@ -41,6 +41,9 @@
    {
      "path": "../../ui/user-interaction"
    },
+    {
+      "path": "../../workspace/workspace"
+    },
    {
      "path": "../../support/invariants"
    }