workspace-server

Workspace Server

The Workspace Server (`apps/workspace-server/`) is a Node daemon that runs on a remote machine and exposes workspace runtimes (git, files, deps, ACP, …) to Emdash clients over the `@emdash/wire` protocol. Clients connect over an SSH-forwarded Unix socket; the daemon is independently lived and can be running when clients upgrade, downgrade, or are absent entirely.

The desktop client and managed installation flow live in `apps/emdash-desktop/src/core/services/hosts/node/workspace-server/`. For an SSH host, the runtime broker looks up a `HostService` through `Hosts` (`core/services/hosts/node/hosts.ts`) and asks its `runtime` service for a client. `Hosts` owns identity replacement, aggregate state/events, and lease rebinding. Each remote identity has one `HostService` (`node/host-service.ts`), composing `connection`, `runtime`, and `server`. Server operations are bound to that Host, with their own provisioning caches and operation queue. Retired identities cannot publish into replacement state. Local workers remain owned by desktop runtime bootstrap. `host.server` implements the `HostWorkspaceServer` interface directly through `RemoteHostWorkspaceServer` (`node/remote-host-workspace-server.ts`). Its public methods take no connection ID; its owner supplies the identity once. It owns the observable daemon state, one operation queue, and one latest-version cache. Disposing its owner clears its observed state and cancels active and queued operations. The Host service coordinates the per-Host `HostConnectionSupervisor` (ADR 0008), bounded SSH adapters, and workspace-server provisioning. `ManagedHostConnection` owns leases, the runtime pin, and serialized persisted intent. Its composed supervisor owns execution, health-check scheduling, and retry policy. Its internal `HostRuntimeConnection` owns the stable Wire client, bounded channel opening and initialization, candidate installation/cleanup, and physical-generation-bound health requests. It reports disconnections and RPC timeouts to the supervisor without scheduling recovery. Provisioning uses a one-shot `WorkspaceServerDialer`; neither it nor the SSH manager schedules connection recovery. The broker only resolves clients. Ordinary outages preserve logical identity; machine identity edits dispose it.

The public `HostConnection` port exposes read-only availability, `lease(owner)`, `pin()`, and `disconnect()`. Pin and Disconnect return typed Results about intent registration/persistence; they do not wait for connection establishment. Internal readiness and wake operations are separate. Projects own a child-scope connection lease while automatic access is eligible, and dispose that scope when access becomes ineligible. Observing state registers no intent; there is no demand-mode API. `Hosts.lease(connectionId, owner)` follows identity replacement while its owner remains alive; `host.connection.lease(owner)` belongs to that particular Host identity. Passive project observation registers no lease. SSH-only access remains independent of runtime pinning; restoring persisted SSH permission does not create a pin. Availability is a kernel-derived projection, with a stable per-Host source that follows identity replacement. Readiness waits require existing explicit runtime intent or scope-owned automatic demand; they never acquire implicit demand. `host.runtime.waitUntilReady()` only observes; explicit Connect/Retry registers a pin before waiting, capturing the same Host identity across both steps. Wake hints go through `Hosts`, not runtime access. Health deadlines do not slide when serving those waits. Explicit server operations capture the supervisor's operation scope before queueing, so Disconnect or identity replacement cancels both queued and active work. Failed/timed-out operations expose manual recovery; successful Stop remains paused until an explicit runtime action.

`node/availability.ts` routes local/remote availability and exposes the shared Wire live model. It owns no retry loop. `node/worker-host-availability.ts` owns readiness for adapter-managed workers; production uses it only for desktop-local workers. A remote Host cannot fall back to that local preparation path. The Host probe and provisioner each own a single Host's cached result and current operation; cancelled work is fenced before continuing to another daemon action.

Managed Linux installations use `~/.emdash/workspace-server/` with immutable version directories, an atomic `current` symlink, staging and install-lock paths, and an explicitly selected socket under `run/`. When the daemon is absent or the user explicitly requests an update, the desktop downloads the channel pointer for its protocol major, then downloads and executes that version's immutable `apps/workspace-server/install.sh` on the remote with the selected version pinned. Canary desktops fall back to the stable pointer when no canary pointer exists. The script detects Linux architecture and glibc support, pulls the matching artifact, verifies its SHA-256 sidecar, and extracts it before `current` changes. Compatible same-major daemons remain installed until a future explicit update. The desktop offers that update only when the channel pointer names a strictly newer SemVer artifact version; equal and older pointer versions leave the running daemon alone. `EMDASH_WORKSPACE_SERVER_ARTIFACTS_URL` overrides the install-script and artifact base URL for development; the Docker remote dev setup publishes Linux builds to local minio and uses `http://minio:9000/emdash-releases/workspace-server` so remote installation exercises the same curl-based object-store path as production. Provisioning verifies that every successful install selected the exact version named by the resolved channel pointer.

The contract lives in `packages/core/src/workspace-server/`, shared by the server and every client so TypeScript clients stay in sync at build time. Non-TypeScript clients (e.g. a future mobile app) use the negotiat