Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

harnessd: the viewers can run in their own process (#775)

Dee48e30638dcaf
diff --git a/cli/e2e/viewersProcess.e2e.ts b/cli/e2e/viewersProcess.e2e.ts
new file mode 100644
index 000000000..cf188a06c
--- /dev/null
+++ b/cli/e2e/viewersProcess.e2e.ts
@@ -0,0 +1,209 @@
+/**
+ * The DSH viewers in their own process, for a real harness agent on the real daemon: harnessd's master
+ * runs viewers beside the core (`HARNESSD_SERVICES=viewers`, here with search too), the harness's viewer
+ * server is the viewers process's own, and its URL reaches the window through the core, which keeps each
+ * agent's last word for the frames it builds (core/viewersLink.ts). Whatever happens to the viewers costs
+ * the viewers alone: hung or killed, the core keeps answering frames with what it last knew, agents keep
+ * working, and the master starts them again, which stops the viewer server the dead process left behind
+ * and starts a new one whose URL replaces the old. A core that restarts leaves the viewers to their
+ * process: the viewer keeps its URL, and the new core answers with it.
+ */
+import { execFileSync } from 'node:child_process'
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it, onTestFailed } from 'vitest'
+import { LocalClient, type Frame } from './harness/client.js'
+import { IsolatedDaemon, until } from './harness/daemon.js'
+
+const HARNESS = 'e2e/sketch'
+const viewerScript = (d: IsolatedDaemon) => join(d.env.DSH_DIR!, 'e2e', 'sketch', 'viewer.mjs')
+
+/** A harness with a viewer of its own, installed in the daemon's harness folder: a small web server on
+ * the port the daemon hands it, which says which process it is. */
+function installHarness(d: IsolatedDaemon): void {
+ const dir = join(d.env.DSH_DIR!, 'e2e', 'sketch')
+ mkdirSync(dir, { recursive: true })
+ writeFileSync(viewerScript(d), [
+ "import { createServer } from 'node:http'",
+ "createServer((_, res) => res.end(`sketch viewer ${process.pid}`)).listen(Number(process.env.HARNESS_VIEWER_PORT), '127.0.0.1')",
+ ].join('\n') + '\n')
+ writeFileSync(join(dir, 'harness.json'), JSON.stringify({
+ spec: 1, id: HARNESS, name: 'Sketch', engine: 'claude',
+ // By its whole path, so a viewer server this test started is told apart from any other process.
+ viewer: { command: `'${process.execPath}' '${viewerScript(d)}'`, url: 'http://127.0.0.1:${port}/' },
+ }))
+ writeFileSync(join(d.env.DSH_DIR!, 'installed.json'), JSON.stringify([
+ { id: HARNESS, dir, source: dir, ref: null, commit: null, linked: false, installedAt: Date.now() },
+ ]))
+}
+
+const processTable = (): Array<{ pid: number; command: string }> =>
+ execFileSync('ps', ['-A', '-o', 'pid=,command=']).toString().trim().split('\n')
+ .map((line) => line.trim().match(/^(\d+)\s+(.*)$/)).filter((match): match is RegExpMatchArray => !!match)
+ .map(([, pid, command]) => ({ pid: Number(pid), command }))
+/** The viewer servers this daemon's harness started that are still running (and their shells). */
+const viewerServers = (d: IsolatedDaemon): number[] =>
+ processTable().filter(({ command }) => command.includes(viewerScript(d))).map(({ pid }) => pid)
+/** A process's parents, nearest first. */
+function ancestors(pid: number): number[] {
+ const found: number[] = []
+ for (let at = pid; found.length < 8;) {
+ const parent = Number(execFileSync('ps', ['-o', 'ppid=', '-p', String(at)]).toString().trim())
+ if (!parent || parent <= 1) break
+ found.push(parent)
+ at = parent
+ }
+ return found
+}
+
+/** The viewers process the master runs now: the last one it said it started. Read from its log, never
+ * from the process table, where another daemon's viewers could be. */
+const viewersPid = (d: IsolatedDaemon): number | null => {
+ const started = [...d.log().matchAll(/\[harnessd\] service viewers started \(pid (\d+)\)/g)]
+ return started.length ? Number(started[started.length - 1][1]) : null
+}
+const restarts = (d: IsolatedDaemon) => [...d.log().matchAll(/\[harnessd\] service viewers started .* restart \d+/g)].length
+const ready = (d: IsolatedDaemon) => [...d.log().matchAll(/\[cli\] ready/g)].length
+
+const row = async (client: LocalClient, agentId: string) =>
+ ((await client.request<{ agents: Array<Record<string, any>> }>('agents_list', { includeStopped: true }, 30_000)).agents)
+ .find((agent) => agent.id === agentId)
+async function create(d: IsolatedDaemon, client: LocalClient, folder: string, extra: Record<string, unknown> = {}, engine = 'claude'): Promise<Record<string, any>> {
+ const cwd = join(d.projectsDir, folder)
+ mkdirSync(cwd, { recursive: true })
+ const created = await client.request('agent_create', { engine, cwd, bypassPermission: true, ...extra }, 90_000)
+ expect(created.error, `${folder}: ${JSON.stringify(created)}`).toBeUndefined()
+ return until(`${folder} to bind its conversation`, async () => {
+ const agent = await row(client, created.agent.id)
+ return agent?.sessionId && agent.status === 'active' ? agent : null
+ }, 60_000, 500)
+}
+async function turn(client: LocalClient, agentId: string, content: string): Promise<void> {
+ const ended = client.next((frame: Frame) => frame.type === 'turn_ended' && frame.agentId === agentId, 45_000, `turn_ended (${content})`)
+ client.send('message', { agentId, content })
+ await ended
+}
+/** The viewer URL the core answers the agent's frame with, once it has one other than `previous`. */
+const viewerUrl = (client: LocalClient, agentId: string, previous: string | null = null): Promise<string> =>
+ until(`a viewer URL for ${agentId}${previous ? ` other than ${previous}` : ''}`, async () => {
+ const url = (await row(client, agentId))?.viewerUrl
+ return typeof url === 'string' && url !== previous ? url : null
+ }, 60_000, 250)
+/** What the viewer at `url` answers, or null when nothing serves it. */
+const serves = async (url: string): Promise<string | null> => {
+ const response = await fetch(url, { signal: AbortSignal.timeout(2_000) }).catch(() => null)
+ return response?.ok ? response.text() : null
+}
+
+describe('the DSH viewers in their own process', () => {
+ let daemon: IsolatedDaemon | undefined
+ /** Every daemon a test started, closed by the test or not: none may leave a viewer server behind. */
+ const started: IsolatedDaemon[] = []
+ afterEach(async () => {
+ await daemon?.close()
+ daemon = undefined
+ // A viewer server runs in a process group of its own, and a failed test may have left one.
+ for (const pid of started.splice(0).flatMap(viewerServers)) {
+ try { process.kill(-pid, 'SIGKILL') } catch { /* not a group leader, or gone */ }
+ try { process.kill(pid, 'SIGKILL') } catch { /* gone */ }
+ }
+ })
+ const fresh = async (services: string) => {
+ const d = await IsolatedDaemon.create({ env: {
+ HARNESSD_SERVICES: services,
+ HARNESSD_SERVICE_INITIAL_BACKOFF_MS: '200',
+ HARNESSD_SERVICE_MAX_BACKOFF_MS: '1000',
+ } })
+ daemon = d
+ started.push(d)
+ installHarness(d)
+ onTestFailed(() => { console.log(`---- daemon log\n${d.log().split('\n').slice(-150).join('\n')}`) })
+ await d.start()
+ return d
+ }
+
+ it('by default the viewers stay in the core\'s process, as before', async () => {
+ const d = await fresh('')
+ const client = await LocalClient.connect(d)
+ const sketch = await create(d, client, 'sketch-default', { dsh: HARNESS })
+ const answer = await serves(await viewerUrl(client, sketch.id))
+ expect(answer).toMatch(/^sketch viewer \d+$/)
+ expect(ancestors(Number(answer!.split(' ').pop()))).toContain(d.corePid())
+ expect(viewersPid(d)).toBeNull()
+ client.close()
+ })
+
+ it('a harness agent\'s viewer is the viewers process\'s, its URL reaches the window through the core, and search runs beside it', async () => {
+ const d = await fresh('search,viewers')
+ const client = await LocalClient.connect(d)
+ await until('the viewers to connect to the core', () => d.log().includes('[services] viewers connected') || null, 30_000, 200)
+ await until('search to connect to the core', () => d.log().includes('[services] search connected') || null, 30_000, 200)
+ const sketch = await create(d, client, 'sketch-one', { dsh: HARNESS })
+ const url = await viewerUrl(client, sketch.id)
+ expect(url).toMatch(/^http:\/\/127\.0\.0\.1:\d+\/$/)
+ expect(await row(client, sketch.id)).toMatchObject({ dsh: HARNESS, dshName: 'Sketch', viewerName: 'Sketch Viewer' })
+ // Pushed to the window on the agent's frame, not only there when it asks.
+ await client.waitFor((frame) => frame.type === 'agent_synced' && frame.payload?.agent?.id === sketch.id && frame.payload.agent.viewerUrl === url,
+ 30_000, 'the agent\'s frame with its viewer URL')
+ // A real server, and the viewers process's: the core is not among its parents.
+ const answer = await serves(url)
+ expect(answer).toMatch(/^sketch viewer \d+$/)
+ const parents = ancestors(Number(answer!.split(' ').pop()))
+ expect(parents).toContain(viewersPid(d))
+ expect(parents).not.toContain(d.corePid())
+ await turn(client, sketch.id, 'about the axolotl in the sketch')
+ await until('search to find the harness agent\'s conversation', async () =>
+ JSON.stringify(await client.request('session_search', { query: 'axolotl' }, 30_000)).includes(sketch.sessionId) || null, 60_000, 1_000)
+ expect(d.coresStarted()).toBe(1)
+ client.close()
+ // Stopped with the daemon, it stops its viewer servers before it goes.
+ await d.close()
+ daemon = undefined
+ await until('no viewer server to be left running', () => viewerServers(d).length === 0 || null, 10_000, 200)
+ })
+
+ it('hung, then killed, the viewers cost only themselves: frames build from what the core last knew, agents work, and the master brings them back with a new viewer', async () => {
+ const d = await fresh('viewers')
+ const client = await LocalClient.connect(d)
+ const sketch = await create(d, client, 'sketch-killed', { dsh: HARNESS })
+ const plain = await create(d, client, 'plain-codex', {}, 'codex')
+ const before = await viewerUrl(client, sketch.id)
+ const first = viewersPid(d)!
+ // Hung: it hears nothing and says nothing. The core answers the agent's frame with what it last knew.
+ process.kill(first, 'SIGSTOP')
+ expect((await row(client, sketch.id))?.viewerUrl).toBe(before)
+ await turn(client, plain.id, 'while the viewers were hung')
+ // Killed: the master starts it again, and the new process stops the viewer server the old one left.
+ process.kill(first, 'SIGKILL')
+ await until('the master to restart the viewers', () => restarts(d) >= 1 || null, 30_000, 200)
+ expect(viewersPid(d)).not.toBe(first)
+ const after = await viewerUrl(client, sketch.id, before)
+ await until('the viewer left behind to be stopped', async () => (await serves(before)) === null || null, 30_000, 250)
+ expect(await serves(after)).toMatch(/^sketch viewer \d+$/)
+ await client.waitFor((frame) => frame.type === 'agent_synced' && frame.payload?.agent?.id === sketch.id && frame.payload.agent.viewerUrl === after,
+ 30_000, 'the agent\'s frame with its new viewer URL')
+ await turn(client, sketch.id, 'the harness agent never noticed')
+ expect(d.coresStarted()).toBe(1)
+ client.close()
+ })
+
+ it('a core that restarts leaves the viewers running: the new core answers with the same viewer', async () => {
+ const d = await fresh('viewers')
+ let client = await LocalClient.connect(d)
+ const sketch = await create(d, client, 'sketch-core', { dsh: HARNESS })
+ const url = await viewerUrl(client, sketch.id)
+ const viewers = viewersPid(d)
+ const core = d.corePid()!
+ const wired = ready(d)
+ process.kill(core, 'SIGKILL')
+ await until('a new core to finish starting', () => ready(d) > wired || null, 60_000, 200)
+ client.close()
+ client = await LocalClient.connect(d)
+ await until('the new core to answer with the same viewer', async () => (await row(client, sketch.id))?.viewerUrl === url || null, 60_000, 250)
+ expect(viewersPid(d)).toBe(viewers)
+ expect(restarts(d)).toBe(0)
+ expect(await serves(url)).toMatch(/^sketch viewer \d+$/)
+ await turn(client, sketch.id, 'after the core came back')
+ client.close()
+ })
+})
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index 640273706..23b6d08e6 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -164,8 +164,10 @@ import { databaseHistory } from './core/transcripts/databaseHistory.js'
import { createCoreApi, emptyPorts, MODELS_FALLBACKS, SEARCH_FALLBACKS, TEAMS_FALLBACKS, VIEWERS_FALLBACKS, WORKSPACES_FALLBACKS, type TeamsPort } from './core/api.js'
import { createServiceHost, testFaults } from './core/serviceHost.js'
import { createServiceLinks } from './core/serviceLinks.js'
+import { createViewersLink } from './core/viewersLink.js'
import { KNOWN_SERVICES, serviceSpecs } from './harnessd/services.js'
import { runSearchService } from './services/searchProcess.js'
+import { runViewersService } from './services/viewersProcess.js'
import { SEARCH_REQUESTS, startSearch } from './services/search.js'
import { STORE_REQUESTS, startStore } from './services/store.js'
import { startViewers } from './services/viewers.js'
@@ -1811,8 +1813,7 @@ async function runForeground(session: AuthSession | null): Promise<void> {
// Each service starts and is called through the host, so one that fails is logged and left off and
// the core carries on without it (core/serviceHost.ts).
const serviceHost = createServiceHost(ports, { faults: testFaults(process.env.HARNESSD_TEST_FAULTS) })
- // The DSH companions: each harness agent's viewer and verdict watch (services/viewers.ts).
- serviceHost.start('viewers', startViewers, coreApi, VIEWERS_FALLBACKS)
+ // The DSH companions: each harness agent's viewer and verdict watch (services/viewers.ts), started below.
dshFrameContextRef = (s) => ports.viewers?.frameContext(s) ?? null
const attachDsh = (s: RegisteredSession): void => ports.viewers?.attach(s)
const detachDsh = (agentId: string): void => ports.viewers?.detach(agentId)
@@ -2188,11 +2189,13 @@ async function runForeground(session: AuthSession | null): Promise<void> {
const outOfProcess = new Set(serviceToken ? serviceSpecs(process.env, KNOWN_SERVICES).map((spec) => spec.name) : [])
// The requests each service that can run in its own process answers (its own module declares them).
const requestsOf: Record<string, readonly string[]> = { search: SEARCH_REQUESTS }
+ // What the core keeps of the viewers in their own process, for the frames it builds (core/viewersLink.ts).
+ const viewersLink = createViewersLink(coreApi, (frame, opts) => serviceLinks.notify('viewers', frame, opts))
const serviceLinks = createServiceLinks({
token: serviceToken,
owned: Object.fromEntries([...outOfProcess].map((name) => [name, requestsOf[name] ?? []])),
- // Every agent, live then stopped, with the name the apps show for it: what search indexes.
- answer: (_service, query) => query === 'agents'
+ // Search asks for every agent, live then stopped, with the name the apps show for it: what it indexes.
+ answer: (service, query, payload) => service === 'viewers' ? viewersLink.answer(query, payload) : query === 'agents'
? { agents: coreApi.agents.all().map((session) => ({ ...session, displayName: coreApi.agents.displayName(session) })) }
: { error: 'UNKNOWN_QUERY' },
})
@@ -2214,6 +2217,9 @@ async function runForeground(session: AuthSession | null): Promise<void> {
}
// What the core calls search through: guarded, so it answers its fallbacks once search is switched off.
const sessionSearch = ports.search
+ // The DSH viewers: in this process, or in its own (services/viewersProcess.ts), told of each agent.
+ if (outOfProcess.has('viewers')) ports.viewers = viewersLink.port
+ else serviceHost.start('viewers', startViewers, coreApi, VIEWERS_FALLBACKS)
// The harnesses installed here, and installing, updating and removing one (services/store.ts).
serviceHost.serve('store', startStore, coreApi, STORE_REQUESTS)
@@ -5573,12 +5579,13 @@ switch (cmd) {
break
case '__service': { // internal: a service harnessd's master runs in its own process (services/process.ts)
const socketPath = localSocketPath(env.ADAPTER_DATA_DIR, env.PORT)
- if (rest[0] !== 'search' || !socketPath) {
+ const runService = rest[0] === 'search' ? runSearchService : rest[0] === 'viewers' ? runViewersService : null
+ if (!runService || !socketPath) {
console.error(`[service] ${rest[0] ?? '(none)'}: ${socketPath ? 'no such service in this build' : 'the core has no local socket to reach'}`)
process.exit(2)
}
process.title = `harnessd ${rest[0]}`
- runSearchService({ dataDir: env.ADAPTER_DATA_DIR, socketPath, machineId: computerId(), token: process.env.HARNESSD_SERVICE_TOKEN ?? '' })
+ runService({ dataDir: env.ADAPTER_DATA_DIR, socketPath, machineId: computerId(), token: process.env.HARNESSD_SERVICE_TOKEN ?? '' })
break
}
case '__run': // internal: the detached daemon child reads the durable SSO session — or runs without one
diff --git a/cli/src/core/AGENTS.md b/cli/src/core/AGENTS.md
index 38affafe9..a3002b431 100644
--- a/cli/src/core/AGENTS.md
+++ b/cli/src/core/AGENTS.md
@@ -30,4 +30,5 @@ questions. Everything else is a service ([../services/AGENTS.md](../services/AGE
- `engines/`: the engines' hooks.
- `input.ts`, `questions.ts`: messages into a pane; an agent's question and its answer.
- `api.ts`: the contract with services. `serviceHost.ts`: services in this process.
- `serviceLinks.ts`: services in their own processes.
+ `serviceLinks.ts`: services in their own processes. `viewersLink.ts`: what the core keeps of the
+ viewers when they run in theirs.
diff --git a/cli/src/core/viewersLink.spec.ts b/cli/src/core/viewersLink.spec.ts
new file mode 100644
index 000000000..7662d1201
--- /dev/null
+++ b/cli/src/core/viewersLink.spec.ts
@@ -0,0 +1,149 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { RegisteredSession } from '../lib/registry.js'
+import { fakeCore } from '../testing/fakeCore.js'
+import { createViewersLink } from './viewersLink.js'
+
+const agent = (over: Partial<RegisteredSession> = {}) =>
+ ({ agentId: 'a1', sessionId: 's1', engine: 'claude', dsh: 'acme/blender', cwd: '/work/scene', ...over }) as RegisteredSession
+
+const context = (over: Record<string, unknown> = {}) =>
+ ({ id: 'acme/blender', name: 'Blender', viewerUrl: null, viewerName: 'Blender Viewer', verdict: null, ...over })
+
+function setup(live: RegisteredSession | null = agent(), terminalAvailable = true) {
+ const core = fakeCore({
+ agents: {
+ byAgent: vi.fn(() => live ?? undefined),
+ terminalAvailable: vi.fn(() => terminalAvailable),
+ live: vi.fn(() => [agent(), agent({ agentId: 'plain', dsh: undefined }), agent({ agentId: 'a2', dsh: 'acme/kicad' })]),
+ },
+ })
+ const notify = vi.fn(() => true)
+ const link = createViewersLink(core, notify)
+ return { core, notify, link, port: link.port }
+}
+
+describe('the viewers in their own process, as the core keeps them', () => {
+ it('tells the process of each agent with a harness it attaches, and of no other', () => {
+ const { notify, port } = setup()
+ port.attach(agent())
+ port.attach(agent({ agentId: 'plain', dsh: undefined }))
+ // Not held while the process is down: it asks for every agent each time it connects.
+ expect(notify.mock.calls).toEqual([[{ type: 'service_event', payload: { kind: 'attach', session: agent() } }]])
+ })
+
+ it('answers a frame with the fallbacks until the process has said anything of the agent', () => {
+ const { port } = setup()
+ port.attach(agent())
+ expect(port.frameContext(agent())).toBeNull()
+ expect(port.forwardingUrl('a1')).toBeNull()
+ })
+
+ it('keeps what the process says of an attached agent, follows its viewer and sends its frame again', () => {
+ const { core, link, port } = setup()
+ port.attach(agent())
+ const said = context({ viewerUrl: 'http://127.0.0.1:7001/' })
+ expect(link.answer('context', { agentId: 'a1', context: said, forwardingUrl: 'http://127.0.0.1:7001/', requestId: 'q1', query: 'context' })).toEqual({ kept: true })
+ expect(port.frameContext(agent())).toEqual(said)
+ expect(port.forwardingUrl('a1')).toBe('http://127.0.0.1:7001/')
+ expect(core.clients.viewerChanged).toHaveBeenCalledWith('a1')
+ expect(core.agents.sync).toHaveBeenCalledWith(agent())
+ // An agent without a harness has nothing to say on its frame, whatever was kept under its id.
+ expect(port.frameContext(agent({ dsh: undefined }))).toBeNull()
+ })
+
+ it('a change that moves no viewer sends the frame without disturbing the viewer panes; no change does nothing', () => {
+ const { core, link, port } = setup()
+ port.attach(agent())
+ link.answer('context', { agentId: 'a1', context: context(), forwardingUrl: null })
+ // Its first word moved nothing a viewer pane follows: no viewer yet.
+ expect(core.clients.viewerChanged).not.toHaveBeenCalled()
+ expect(core.agents.sync).toHaveBeenCalledTimes(1)
+ const verdict = { ready: true, summary: 'ok', errors: 0, warnings: 0, artifact: null, phases: [], updatedAt: null }
+ link.answer('context', { agentId: 'a1', context: context({ verdict }), forwardingUrl: null })
+ expect(port.frameContext(agent())).toMatchObject({ verdict })
+ expect(core.clients.viewerChanged).not.toHaveBeenCalled()
+ expect(core.agents.sync).toHaveBeenCalledTimes(2)
+ expect(link.answer('context', { agentId: 'a1', context: context({ verdict }), forwardingUrl: null })).toEqual({ kept: true })
+ expect(core.agents.sync).toHaveBeenCalledTimes(2)
+ })
+
+ it('follows a viewer URL that moves even when nothing forwards to it', () => {
+ const { core, link, port } = setup()
+ port.attach(agent())
+ link.answer('context', { agentId: 'a1', context: context({ viewerUrl: 'http://elsewhere.test/' }), forwardingUrl: null })
+ expect(core.clients.viewerChanged).toHaveBeenCalledWith('a1')
+ })
+
+ it('waits for the terminal before sending a frame, which would otherwise read as "agent gone"', () => {
+ const detached = setup(agent(), false)
+ detached.port.attach(agent())
+ detached.link.answer('context', { agentId: 'a1', context: context({ viewerUrl: 'http://127.0.0.1:7001/' }), forwardingUrl: 'http://127.0.0.1:7001/' })
+ expect(detached.port.frameContext(agent())).toMatchObject({ viewerUrl: 'http://127.0.0.1:7001/' })
+ expect(detached.core.agents.sync).not.toHaveBeenCalled()
+ const gone = setup(null)
+ gone.port.attach(agent())
+ gone.link.answer('context', { agentId: 'a1', context: context(), forwardingUrl: null })
+ expect(gone.core.agents.sync).not.toHaveBeenCalled()
+ })
+
+ it('keeps nothing of an agent it never attached, or detached since: a word said before the detach is older than it', () => {
+ const { core, link, port } = setup()
+ expect(link.answer('context', { agentId: 'a1', context: context(), forwardingUrl: null })).toEqual({ kept: false })
+ port.attach(agent())
+ port.detach('a1')
+ expect(link.answer('context', { agentId: 'a1', context: context({ viewerUrl: 'http://127.0.0.1:7001/' }), forwardingUrl: 'http://127.0.0.1:7001/' })).toEqual({ kept: false })
+ expect(port.frameContext(agent())).toBeNull()
+ expect(port.forwardingUrl('a1')).toBeNull()
+ expect(core.agents.sync).not.toHaveBeenCalled()
+ // Nor of one it cannot name.
+ expect(link.answer('context', { agentId: 7, context: context() })).toEqual({ kept: false })
+ })
+
+ it('reads what does not look like a context or a URL as none', () => {
+ const { link, port } = setup()
+ port.attach(agent())
+ link.answer('context', { agentId: 'a1', context: 'not a context', forwardingUrl: 9 })
+ expect(port.frameContext(agent())).toBeNull()
+ expect(port.forwardingUrl('a1')).toBeNull()
+ })
+
+ it('a detach forgets the agent, lets the viewer panes go of a viewer it had, and is held until the process hears it', () => {
+ const { core, notify, link, port } = setup()
+ port.attach(agent())
+ link.answer('context', { agentId: 'a1', context: context({ viewerUrl: 'http://127.0.0.1:7001/' }), forwardingUrl: 'http://127.0.0.1:7001/' })
+ vi.mocked(core.clients.viewerChanged).mockClear()
+ port.detach('a1')
+ expect(core.clients.viewerChanged).toHaveBeenCalledWith('a1')
+ expect(notify).toHaveBeenLastCalledWith({ type: 'service_event', payload: { kind: 'detach', agentId: 'a1' } }, { untilDelivered: true })
+ expect(port.frameContext(agent())).toBeNull()
+ // One with no viewer, or never heard of, has no viewer pane to let go of.
+ vi.mocked(core.clients.viewerChanged).mockClear()
+ port.attach(agent({ agentId: 'a2' }))
+ link.answer('context', { agentId: 'a2', context: null, forwardingUrl: null })
+ port.detach('a2')
+ port.detach('never')
+ expect(core.clients.viewerChanged).not.toHaveBeenCalled()
+ })
+
+ it('answers from what it last knew while the process cannot hear anything', () => {
+ const { link, notify, port } = setup()
+ port.attach(agent())
+ link.answer('context', { agentId: 'a1', context: context({ viewerUrl: 'http://127.0.0.1:7001/' }), forwardingUrl: 'http://127.0.0.1:7001/' })
+ notify.mockReturnValue(false)
+ port.attach(agent())
+ expect(port.frameContext(agent())).toMatchObject({ viewerUrl: 'http://127.0.0.1:7001/' })
+ expect(port.forwardingUrl('a1')).toBe('http://127.0.0.1:7001/')
+ })
+
+ it('names the agents with a harness when the process asks, and refuses a question it does not know', () => {
+ const { link } = setup()
+ expect(link.answer('agents', {})).toEqual({ agents: [agent(), agent({ agentId: 'a2', dsh: 'acme/kicad' })] })
+ expect(link.answer('session_search', {})).toEqual({ error: 'UNKNOWN_QUERY' })
+ })
+
+ it('stops nothing in the core: the viewers are the process\'s', async () => {
+ const { notify, port } = setup()
+ await expect(port.stop()).resolves.toBeUndefined()
+ expect(notify).not.toHaveBeenCalled()
+ })
+})
diff --git a/cli/src/core/viewersLink.ts b/cli/src/core/viewersLink.ts
new file mode 100644
index 000000000..6d9b9650b
--- /dev/null
+++ b/cli/src/core/viewersLink.ts
@@ -0,0 +1,97 @@
+/**
+ * The DSH viewers in their own process, as the core sees them (`HARNESSD_SERVICES=viewers`; the
+ * process's side is services/viewersProcess.ts).
+ *
+ * The core asks the viewers two things while it builds an agent's frame: what its DSH context is (its
+ * harness's name, its viewer URL, its verdict) and where the windows' viewer pane forwards to. A frame
+ * cannot wait on another process, so the viewers tell the core each agent's answers whenever they change
+ * (a `service_query` of kind `context`), the core keeps the last of them here, and the port answers from
+ * that: while the process is down, with what it last knew, or the fallbacks for an agent it never heard
+ * of. Each change then does in the core what the viewers did in their process: the windows' viewer panes
+ * follow a viewer that moved (`clients.viewerChanged`), and the frame of an agent whose terminal is
+ * attached goes out again.
+ *
+ * Attach and detach go to the process as notifications (`service_event`). A detach it missed would leave
+ * a viewer running, so it is held until the process hears it. An attach it missed is caught up instead:
+ * the process asks for every agent with a harness (`agents`) each time it connects, which a restarted
+ * process needs anyway, since it starts holding nothing. Holding attaches as well would only pile up the
+ * core's repeats (one per agent on every discovery pass) while the process is down.
+ *
+ * The core keeps what it hears only for the agents it has attached and not since detached: what the
+ * process says of an agent before it hears the agent's detach must not bring the forgotten agent's
+ * viewer back. The process says everything again on each attach, which is how the core's first word on
+ * an agent arrives after a core restart, when the process connects before the core has attached anyone.
+ */
+import type { AgentDshContext } from '../lib/agentFrame.js'
+import type { CoreApi, ViewersPort } from './api.js'
+import type { ServiceFrame } from './serviceLinks.js'
+
+/** Tell the viewers' process something (core/serviceLinks.ts `notify`, for `viewers`). */
+export type NotifyViewers = (frame: ServiceFrame, opts?: { untilDelivered?: boolean }) => boolean
+
+/** What the viewers last said of one agent. */
+interface Known {
+ context: AgentDshContext | null
+ forwardingUrl: string | null
+}
+
+/** The two URLs a change in which the windows' viewer panes must follow. */
+const urls = (known: Known | undefined): string => JSON.stringify([known?.context?.viewerUrl ?? null, known?.forwardingUrl ?? null])
+
+export function createViewersLink(core: Pick<CoreApi, 'agents' | 'clients'>, notify: NotifyViewers) {
+ const attached = new Set<string>()
+ const known = new Map<string, Known>()
+
+ const port: ViewersPort = {
+ attach: (session) => {
+ if (!session.dsh) return
+ attached.add(session.agentId)
+ notify({ type: 'service_event', payload: { kind: 'attach', session } })
+ },
+ detach: (agentId) => {
+ attached.delete(agentId)
+ const had = known.get(agentId)
+ known.delete(agentId)
+ // The windows' viewer panes let go of its viewer at once, as when it stopped in this process.
+ if (urls(had) !== urls(undefined)) core.clients.viewerChanged(agentId)
+ notify({ type: 'service_event', payload: { kind: 'detach', agentId } }, { untilDelivered: true })
+ },
+ frameContext: (session) => (session.dsh ? known.get(session.agentId)?.context ?? null : null),
+ forwardingUrl: (agentId) => known.get(agentId)?.forwardingUrl ?? null,
+ // The viewers are the process's: a core restarting or stopping leaves them running for the next core,
+ // and the master stops the process itself when the daemon stops.
+ stop: async () => {},
+ }
+
+ /** The process says what one agent's frame says of its harness now. */
+ const heard = (payload: Record<string, unknown>): Record<string, unknown> => {
+ const agentId = typeof payload.agentId === 'string' ? payload.agentId : ''
+ if (!attached.has(agentId)) return { kept: false }
+ const next: Known = {
+ context: payload.context && typeof payload.context === 'object' ? payload.context as AgentDshContext : null,
+ forwardingUrl: typeof payload.forwardingUrl === 'string' ? payload.forwardingUrl : null,
+ }
+ const before = known.get(agentId)
+ if (JSON.stringify(before) === JSON.stringify(next)) return { kept: true }
+ known.set(agentId, next)
+ if (urls(before) !== urls(next)) core.clients.viewerChanged(agentId)
+ // Only once the agent's terminal is attached: a frame with none reads to the desktop as "agent gone"
+ // (services/viewers.ts, `syncCompanion`). The attach's own sync carries what arrived first.
+ const session = core.agents.byAgent(agentId)
+ if (session && core.agents.terminalAvailable(agentId)) core.agents.sync(session)
+ return { kept: true }
+ }
+
+ return {
+ port,
+ /** The core's answers to the viewers' questions (core/serviceLinks.ts `answer`, for `viewers`). */
+ answer(query: string, payload: Record<string, unknown>): Record<string, unknown> {
+ // Every agent the core has with a harness, dormant ones too: the ones it attaches at start.
+ if (query === 'agents') return { agents: core.agents.live().filter((session) => session.dsh) }
+ if (query === 'context') return heard(payload)
+ return { error: 'UNKNOWN_QUERY' }
+ },
+ }
+}
+
+export type ViewersLink = ReturnType<typeof createViewersLink>
diff --git a/cli/src/harnessd/services.ts b/cli/src/harnessd/services.ts
index e57710319..de15a3b4a 100644
--- a/cli/src/harnessd/services.ts
+++ b/cli/src/harnessd/services.ts
@@ -288,11 +288,14 @@ export class ServiceSupervisor {
/**
* The services this build can run in their own processes, with their memory budgets. Which of them do
- * is `HARNESSD_SERVICES` (`search`): off until named, while each one beds in, and the core runs a
+ * is `HARNESSD_SERVICES` (`search,viewers`): off until named, while each one beds in, and the core runs a
* service that is not out here in its own process, as before.
*/
export const KNOWN_SERVICES: Readonly<Record<string, Omit<ServiceSpec, 'name'>>> = {
search: { heapLimitMiB: 1_024, rssLimitMiB: 2_048 },
+ // Its file watches on every harness's workspace; the viewer servers it starts are processes of their
+ // own, outside this budget.
+ viewers: { heapLimitMiB: 512, rssLimitMiB: 1_024 },
}
/** Service timings from the environment (for tests and support); anything unset or invalid keeps its default. */
diff --git a/cli/src/services/AGENTS.md b/cli/src/services/AGENTS.md
index 5a5d31167..92e51ed29 100644
--- a/cli/src/services/AGENTS.md
+++ b/cli/src/services/AGENTS.md
@@ -39,7 +39,7 @@ let several people build features at once without touching the core or each othe
## Running in its own process
A service that can crash natively, hang or leak should run in its own process, where it costs only
-itself. Search does: `HARNESSD_SERVICES=search`.
+itself. Search and the viewers do: `HARNESSD_SERVICES=search,viewers` (either alone, too).
- `src/harnessd/services.ts` runs it (`KNOWN_SERVICES`, with its memory budget). The core routes the
requests it declared (its `<NAME>_REQUESTS`) to its process, and the same handlers answer them there.
@@ -49,6 +49,12 @@ itself. Search does: `HARNESSD_SERVICES=search`.
`SERVICE_UNAVAILABLE` while it is down, and holds what the service must not miss.
- `src/services/searchProcess.ts` is the example to copy. `e2e/serviceProcesses.e2e.ts` is the proof
to copy: killed, hung (SIGSTOP), leaking, crashing on every start.
+- A port the core calls in line (while it builds a frame, say) cannot wait on another process. The
+ viewers show how (`src/services/viewersProcess.ts`, `src/core/viewersLink.ts`): the process tells
+ the core its answers whenever they change (a `service_query` kind the core answers), the core keeps
+ the last ones and its port answers from them, or from the fallbacks before it has heard any. The
+ process asks the core for everything it should hold each time it connects, which a restarted
+ process needs anyway. `e2e/viewersProcess.e2e.ts` proves it with a real harness agent's viewer.
## Do not
diff --git a/cli/src/services/viewersProcess.spec.ts b/cli/src/services/viewersProcess.spec.ts
new file mode 100644
index 000000000..2cc3c413e
--- /dev/null
+++ b/cli/src/services/viewersProcess.spec.ts
@@ -0,0 +1,251 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { CoreApi, CorePorts, ViewersPort } from '../core/api.js'
+import type { AgentDshContext } from '../lib/agentFrame.js'
+import type { RegisteredSession } from '../lib/registry.js'
+import { runServiceProcess, type CoreConnection, type ServiceProcessOptions } from './process.js'
+import { runViewersService, viewersCoreApi } from './viewersProcess.js'
+
+// The real default reaches a real socket and this process's own channel: never in a test.
+vi.mock('./process.js', () => ({ runServiceProcess: vi.fn(() => ({ stop: vi.fn() })) }))
+
+const agent = (agentId = 'a1', over: Partial<RegisteredSession> = {}) =>
+ ({ agentId, sessionId: `s-${agentId}`, engine: 'claude', dsh: 'acme/blender', cwd: `/work/${agentId}`, ...over }) as RegisteredSession
+
+/** Viewers that start nothing: what each agent's frame says is whatever the test sets. */
+function fakeViewers() {
+ const contexts = new Map<string, AgentDshContext>()
+ const urls = new Map<string, string>()
+ const port = {
+ attach: vi.fn(),
+ detach: vi.fn(),
+ frameContext: vi.fn((session: RegisteredSession) => contexts.get(session.agentId) ?? null),
+ forwardingUrl: vi.fn((agentId: string) => urls.get(agentId) ?? null),
+ stop: vi.fn(async () => {}),
+ } satisfies ViewersPort
+ return { port, contexts, urls }
+}
+
+/** A connection to the core that records what it is told and answers `agents` with `listed`. */
+function connection(listed: unknown = { agents: [] }) {
+ const query = vi.fn(async (name: string, _payload?: Record<string, unknown>) => (name === 'agents' ? listed : { kept: true }) as Record<string, unknown>)
+ const told = () => query.mock.calls.filter(([name]) => name === 'context').map(([, payload]) => payload)
+ return { core: { query } satisfies CoreConnection, query, told }
+}
+
+const flush = () => new Promise((done) => setTimeout(done, 0))
+
+describe('the viewers in their own process', () => {
+ afterEach(() => vi.clearAllMocks())
+
+ const setup = (over: Partial<Parameters<typeof runViewersService>[0]> = {}) => {
+ const viewers = fakeViewers()
+ let api: CoreApi | null = null
+ let options: ServiceProcessOptions | null = null
+ let onSigterm: (() => void) | null = null
+ const service = { stop: vi.fn() }
+ const exits: number[] = []
+ const handle = runViewersService({
+ dataDir: '/data', socketPath: '/data/daemon-1.sock', machineId: 'm', token: 't',
+ run: (given) => { options = given; return service },
+ start: (core: CoreApi, ports: CorePorts) => { api = core; ports.viewers = viewers.port },
+ onSignal: (signal, handler) => { if (signal === 'SIGTERM') onSigterm = handler },
+ exit: (code) => exits.push(code),
+ ...over,
+ })
+ return { viewers, api: api!, options: options!, service, handle, exits, sigterm: () => onSigterm!() }
+ }
+
+ it('reaches the core as `viewers`, through the socket and token it was given, and answers the apps nothing', () => {
+ const { options } = setup()
+ expect(options).toMatchObject({ name: 'viewers', socketPath: '/data/daemon-1.sock', machineId: 'm', token: 't' })
+ expect(options.requests).toEqual({})
+ })
+
+ it('attaches what the core attaches, tells the core what the agent\'s frame says, and detaches what it detaches', async () => {
+ const { viewers, api, options } = setup()
+ const core = connection()
+ options.onConnected!(core.core)
+ await flush()
+ viewers.contexts.set('a1', { id: 'acme/blender', name: 'Blender', viewerUrl: null, viewerName: 'Blender Viewer', verdict: null })
+ options.onEvent!({ kind: 'attach', session: agent() })
+ expect(viewers.port.attach).toHaveBeenCalledWith(agent())
+ expect(api.agents.byAgent('a1')).toEqual(agent())
+ expect(core.told()).toEqual([{ agentId: 'a1', context: viewers.contexts.get('a1'), forwardingUrl: null }])
+ options.onEvent!({ kind: 'detach', agentId: 'a1' })
+ expect(viewers.port.detach).toHaveBeenCalledWith('a1')
+ expect(api.agents.byAgent('a1')).toBeUndefined()
+ // What a stopping viewer says after its detach is not the core's to hear.
+ api.clients.viewerChanged('a1')
+ expect(core.told()).toHaveLength(1)
+ })
+
+ it('tells the core each change once, where the service would move the viewer panes or push a frame', async () => {
+ const { viewers, api, options } = setup()
+ const core = connection()
+ options.onConnected!(core.core)
+ options.onEvent!({ kind: 'attach', session: agent() })
+ // A viewer came up: its URL, and where the windows' pane forwards.
+ viewers.contexts.set('a1', { id: 'acme/blender', name: 'Blender', viewerUrl: 'http://127.0.0.1:7001/', verdict: null })
+ viewers.urls.set('a1', 'http://127.0.0.1:7001/')
+ api.clients.viewerChanged('a1')
+ api.agents.sync(agent())
+ expect(core.told()).toEqual([
+ { agentId: 'a1', context: null, forwardingUrl: null },
+ { agentId: 'a1', context: viewers.contexts.get('a1'), forwardingUrl: 'http://127.0.0.1:7001/' },
+ ])
+ // A verdict: the frame changes, and the core hears it.
+ viewers.contexts.set('a1', { ...viewers.contexts.get('a1')!, verdict: { ready: true, summary: null, errors: 0, warnings: 0, artifact: null, phases: [], updatedAt: null } })
+ api.agents.sync(agent())
+ expect(core.told()).toHaveLength(3)
+ // Said again on every attach, changed or not: a core that restarted keeps nothing until it attaches.
+ options.onEvent!({ kind: 'attach', session: agent() })
+ expect(core.told()).toHaveLength(4)
+ })
+
+ it('says nothing before it is connected, then everything the core lists once it has caught up', async () => {
+ const { viewers, options } = setup()
+ viewers.contexts.set('a1', { id: 'acme/blender', name: 'Blender', viewerUrl: null, verdict: null })
+ options.onEvent!({ kind: 'attach', session: agent() })
+ expect(viewers.port.attach).toHaveBeenCalledOnce()
+ const core = connection({ agents: [agent()] })
+ options.onConnected!(core.core)
+ expect(core.told()).toEqual([])
+ await flush()
+ expect(core.told()).toEqual([{ agentId: 'a1', context: viewers.contexts.get('a1'), forwardingUrl: null }])
+ })
+
+ it('catches up with the core\'s agents on every connection: attaches what is missing, detaches what is gone', async () => {
+ const { viewers, api, options } = setup()
+ options.onEvent!({ kind: 'attach', session: agent('gone') })
+ options.onEvent!({ kind: 'attach', session: agent('kept') })
+ const core = connection({ agents: [agent('kept'), agent('new'), { not: 'an agent' }, null] })
+ options.onConnected!(core.core)
+ await flush()
+ expect(viewers.port.attach).toHaveBeenCalledWith(agent('new'))
+ expect(viewers.port.detach).toHaveBeenCalledWith('gone')
+ expect(viewers.port.detach).toHaveBeenCalledTimes(1)
+ expect(api.agents.all().map((session) => session.agentId).sort()).toEqual(['kept', 'new'])
+ expect(api.agents.live()).toHaveLength(2)
+ })
+
+ it('leaves an agent heard of since it asked: news newer than the core\'s answer', async () => {
+ const { viewers, api, options } = setup()
+ options.onEvent!({ kind: 'attach', session: agent('a1') })
+ let answer: (value: Record<string, unknown>) => void = () => {}
+ const query = vi.fn((name: string) => (name === 'agents' ? new Promise<Record<string, unknown>>((done) => { answer = done }) : Promise.resolve({ kept: true })))
+ options.onConnected!({ query })
+ // While the question is out: a new agent attached, an old one detached.
+ options.onEvent!({ kind: 'attach', session: agent('a4') })
+ options.onEvent!({ kind: 'detach', agentId: 'a1' })
+ answer({ agents: [agent('a1')] })
+ await flush()
+ expect(api.agents.all().map((session) => session.agentId)).toEqual(['a4'])
+ // Attached once, before the question: the answer naming it did not bring it back.
+ expect(viewers.port.attach.mock.calls.filter(([session]) => session.agentId === 'a1')).toHaveLength(1)
+ })
+
+ it('ignores an older connection\'s answer, an answer that names no agents, and a core that cannot answer', async () => {
+ const { viewers, options } = setup()
+ let answer: (value: Record<string, unknown>) => void = () => {}
+ const older = vi.fn((name: string) => (name === 'agents' ? new Promise<Record<string, unknown>>((done) => { answer = done }) : Promise.resolve({})))
+ options.onConnected!({ query: older })
+ options.onConnected!(connection({ error: 'UNKNOWN_QUERY' }).core)
+ answer({ agents: [agent('late')] })
+ await flush()
+ options.onConnected!({ query: vi.fn(async () => { throw new Error('the core went away') }) })
+ await flush()
+ expect(viewers.port.attach).not.toHaveBeenCalled()
+ })
+
+ it('a word lost with its connection is said again on the next one', async () => {
+ const { viewers, options } = setup()
+ const lost = vi.fn(async (name: string) => {
+ if (name === 'context') throw new Error('the core went away')
+ return { agents: [agent()] }
+ })
+ viewers.contexts.set('a1', { id: 'acme/blender', name: 'Blender', viewerUrl: 'http://127.0.0.1:7001/', verdict: null })
+ options.onConnected!({ query: lost })
+ options.onEvent!({ kind: 'attach', session: agent() })
+ await flush()
+ const core = connection({ agents: [agent()] })
+ options.onConnected!(core.core)
+ await flush()
+ expect(core.told()).toEqual([{ agentId: 'a1', context: viewers.contexts.get('a1'), forwardingUrl: null }])
+ })
+
+ it('ignores what it is told that it does not act on', () => {
+ const { viewers, options } = setup()
+ options.onEvent!({ kind: 'touch', sessionId: 's1' })
+ options.onEvent!({ kind: 'attach' })
+ options.onEvent!({ kind: 'attach', session: { dsh: 'acme/blender' } })
+ options.onEvent!({ kind: 'detach', agentId: 7 })
+ expect(viewers.port.attach).not.toHaveBeenCalled()
+ expect(viewers.port.detach).not.toHaveBeenCalled()
+ })
+
+ it('stops its viewer servers before it goes, however it ends, and only once', async () => {
+ const { viewers, service, handle, exits, options, sigterm } = setup()
+ sigterm()
+ options.exit!(1)
+ handle.stop()
+ await flush()
+ expect(service.stop).toHaveBeenCalledOnce()
+ expect(viewers.port.stop).toHaveBeenCalledOnce()
+ expect(exits).toEqual([0, 1])
+ })
+
+ it('goes all the same when its viewers fail to stop', async () => {
+ const viewers = fakeViewers()
+ viewers.port.stop.mockRejectedValue(new Error('a watch would not close'))
+ const { exits, sigterm } = setup({ start: (_core, ports) => { ports.viewers = viewers.port } })
+ sigterm()
+ await flush()
+ expect(exits).toEqual([0])
+ })
+
+ it('does not run without viewers: the master starts it again, or parks it', () => {
+ expect(() => setup({ start: () => {} })).toThrow('the viewers did not start')
+ })
+
+ it('runs on a core API of the agents the core attached, answering what the viewers never ask as nothing', async () => {
+ const sessions = new Map([['a1', agent()]])
+ const tell = vi.fn()
+ const api = viewersCoreApi('/data', sessions, tell)
+ expect(api.dataDir).toBe('/data')
+ expect(api.agents.all()).toEqual([agent()])
+ expect(api.agents.live()).toEqual([agent()])
+ expect(api.agents.byAgent('a1')).toEqual(agent())
+ expect(api.agents.displayName(agent())).toBe('')
+ expect(api.agents.advertised()).toEqual([])
+ // The core judges the terminal when it hears: here every change is worth telling.
+ expect(api.agents.terminalAvailable('a1')).toBe(true)
+ api.agents.sync(agent())
+ api.clients.viewerChanged('a1')
+ expect(tell.mock.calls).toEqual([['a1'], ['a1']])
+ expect(api.transcripts.databaseHistory(agent())).toBeUndefined()
+ expect(api.external.sessions.list()).toEqual([])
+ await expect(api.external.sessions.scan()).resolves.toEqual([])
+ expect(api.external.open.known().size).toBe(0)
+ await expect(api.external.open.fresh()).resolves.toEqual(new Map())
+ await expect(api.account.mintGridName()).resolves.toBeNull()
+ await expect(api.account.accessToken()).rejects.toThrow('the viewers hold no credential')
+ api.clients.gridNamed('grid')
+ api.clients.dshInstallStatus({ phase: 'clone' })
+ })
+
+ it('runs as a real service process by default: its viewers, its signal, its exit', async () => {
+ const once = vi.spyOn(process, 'once').mockImplementation(() => process)
+ const exit = vi.spyOn(process, 'exit').mockImplementation((() => undefined) as never)
+ try {
+ runViewersService({ dataDir: '/data', socketPath: '/data/daemon-1.sock', machineId: 'm', token: 't' })
+ expect(runServiceProcess).toHaveBeenCalledWith(expect.objectContaining({ name: 'viewers', socketPath: '/data/daemon-1.sock' }))
+ const [signal, handler] = once.mock.calls.at(-1)!
+ expect(signal).toBe('SIGTERM')
+ ;(handler as () => void)()
+ await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(0))
+ } finally {
+ once.mockRestore()
+ exit.mockRestore()
+ }
+ })
+})
diff --git a/cli/src/services/viewersProcess.ts b/cli/src/services/viewersProcess.ts
new file mode 100644
index 000000000..499379ea0
--- /dev/null
+++ b/cli/src/services/viewersProcess.ts
@@ -0,0 +1,165 @@
+/**
+ * The DSH viewers in their own process (`harness __service viewers`, with `HARNESSD_SERVICES=viewers`).
+ *
+ * The same viewer servers and verdict watches as in the core's process (services/viewers.ts), on a core
+ * API built here. The agents are the ones the core attaches: it says each attach and detach
+ * (`service_event`), and each time this process connects it asks the core for every agent with a harness
+ * (`service_query agents`) and catches up, so a process started after a crash, or reconnected after the
+ * core restarted, holds exactly the viewers the core's agents should have.
+ *
+ * What the core used to read from the service while it builds a frame (an agent's DSH context, where the
+ * windows' viewer pane forwards) is told to the core whenever it changes (`service_query context`), and
+ * the core keeps it (core/viewersLink.ts). Where the service would push a frame or move the windows'
+ * viewer panes in the core's process, it tells the core here, and the core does both as before.
+ *
+ * The viewer servers, the watches on every harness's workspace and their restarts are this process's
+ * alone: a crash or a leak costs the viewers, and the master starts them again. A new process stops the
+ * viewer servers a crashed one left running before it starts its own (dsh/viewerLedger.ts). A core restart
+ * no longer restarts every viewer: they stay up here, and the new core hears their URLs at once.
+ */
+import type { CoreApi } from '../core/api.js'
+import { emptyPorts } from '../core/api.js'
+import type { RegisteredSession } from '../lib/registry.js'
+import { runServiceProcess, type CoreConnection, type ServiceProcess } from './process.js'
+import { startViewers } from './viewers.js'
+
+export interface ViewersServiceOptions {
+ dataDir: string
+ socketPath: string
+ machineId: string
+ token: string
+ /** Swapped in tests for one that does not touch the real socket or process. */
+ run?: typeof runServiceProcess
+ /** Swapped in tests for viewers that start no server and watch no file. */
+ start?: typeof startViewers
+ /** How the master's stop (SIGTERM) reaches this process; this process's own signal when absent. */
+ onSignal?: (signal: NodeJS.Signals, handler: () => void) => void
+ exit?: (code: number) => void
+}
+
+/** Whether what the core sent is an agent this process can attach. */
+const isSession = (value: unknown): value is RegisteredSession =>
+ !!value && typeof value === 'object' && typeof (value as { agentId?: unknown }).agentId === 'string'
+
+/**
+ * The core API the viewers run on in their own process: the agents the core attached, and `tell` for
+ * what the service would do to the core's windows. Whether an agent's terminal is attached is the core's
+ * to judge when it hears; what the viewers never ask (search, sign-in) answers as nothing.
+ */
+export function viewersCoreApi(dataDir: string, sessions: ReadonlyMap<string, RegisteredSession>, tell: (agentId: string) => void): CoreApi {
+ const attached = (): RegisteredSession[] => [...sessions.values()]
+ return {
+ dataDir,
+ agents: {
+ all: attached,
+ live: attached,
+ displayName: () => '',
+ byAgent: (agentId) => sessions.get(agentId),
+ advertised: () => [],
+ terminalAvailable: () => true,
+ sync: (session) => tell(session.agentId),
+ },
+ transcripts: { databaseHistory: () => undefined },
+ external: {
+ sessions: { list: () => [], scan: async () => [] },
+ open: { known: () => new Map(), fresh: async () => new Map() },
+ },
+ account: { mintGridName: async () => null, accessToken: () => Promise.reject(new Error('the viewers hold no credential')) },
+ clients: { viewerChanged: tell, gridNamed: () => {}, dshInstallStatus: () => {} },
+ }
+}
+
+export function runViewersService(options: ViewersServiceOptions): ServiceProcess {
+ /** The agents the core attached, by agent id: what this process holds viewers for. */
+ const sessions = new Map<string, RegisteredSession>()
+ /** What the current connection was last told of each agent, so a change is said once. */
+ const told = new Map<string, string>()
+ /** The agents attached or detached since the core was last asked for all of them: newer than its answer. */
+ const heard = new Set<string>()
+ let core: CoreConnection | null = null
+ const ports = emptyPorts()
+
+ const tell = (agentId: string): void => {
+ const session = sessions.get(agentId)
+ // A detached agent is the core's to forget: nothing said after its detach may bring it back.
+ if (!core || !session) return
+ const state = { agentId, context: viewers.frameContext(session), forwardingUrl: viewers.forwardingUrl(agentId) }
+ const said = JSON.stringify(state)
+ if (told.get(agentId) === said) return
+ told.set(agentId, said)
+ // Lost only with the connection; the next connection is told everything again.
+ void core.query('context', state).catch(() => {})
+ }
+
+ ;(options.start ?? startViewers)(viewersCoreApi(options.dataDir, sessions, tell), ports)
+ if (!ports.viewers) throw new Error('the viewers did not start')
+ const viewers = ports.viewers
+
+ const attach = (session: RegisteredSession): void => {
+ sessions.set(session.agentId, session)
+ viewers.attach(session)
+ // Said again on every attach: a core that restarted has heard nothing yet, and keeps what it hears
+ // only of an agent it has attached (core/viewersLink.ts).
+ told.delete(session.agentId)
+ tell(session.agentId)
+ }
+ const detach = (agentId: string): void => {
+ sessions.delete(agentId)
+ told.delete(agentId)
+ viewers.detach(agentId)
+ }
+ /** Every agent the core has with a harness, as it answered: attach what is missing here, detach what it
+ * no longer has, but leave an agent heard of since the question, whose news is newer than the answer. */
+ const catchUp = (agents: unknown): void => {
+ if (!Array.isArray(agents)) return
+ const listed = new Map(agents.filter(isSession).map((session) => [session.agentId, session]))
+ for (const [agentId, session] of listed) if (!heard.has(agentId)) attach(session)
+ for (const agentId of [...sessions.keys()]) if (!listed.has(agentId) && !heard.has(agentId)) detach(agentId)
+ }
+
+ const exit = options.exit ?? ((code: number) => process.exit(code))
+ let stopping: Promise<void> | null = null
+ const stop = (): Promise<void> => {
+ stopping ??= Promise.resolve().then(() => {
+ service.stop()
+ return viewers.stop()
+ })
+ return stopping
+ }
+ // However this process ends (the master's SIGTERM, the master going, a test fault), its viewer servers
+ // are stopped first: they run in process groups of their own and would otherwise outlive it, holding
+ // their ports, until the next viewers process reaped them.
+ const leave = (code: number): void => {
+ void stop().catch(() => {}).then(() => exit(code))
+ }
+
+ const run = options.run ?? runServiceProcess
+ const service = run({
+ name: 'viewers',
+ socketPath: options.socketPath,
+ machineId: options.machineId,
+ token: options.token,
+ // The apps ask the viewers nothing: only the core does, through the context it keeps.
+ requests: {},
+ exit: leave,
+ onEvent: (payload) => {
+ if (payload.kind === 'attach' && isSession(payload.session)) {
+ heard.add(payload.session.agentId)
+ attach(payload.session)
+ } else if (payload.kind === 'detach' && typeof payload.agentId === 'string') {
+ heard.add(payload.agentId)
+ detach(payload.agentId)
+ }
+ },
+ onConnected: (connection) => {
+ core = connection
+ told.clear()
+ heard.clear()
+ // The catch-up attaches every agent the core lists, and each attach tells the core that agent's
+ // context: a new core hears everything, and one that only dropped the connection what changed.
+ void connection.query('agents').then((answer) => { if (core === connection) catchUp(answer.agents) }, () => {})
+ },
+ })
+ ;(options.onSignal ?? ((signal, handler) => { process.once(signal, handler) }))('SIGTERM', () => leave(0))
+ return { stop: () => { void stop() } }
+}
diff --git a/docs/design/2026-10-03-harnessd.md b/docs/design/2026-10-03-harnessd.md
index d280d639c..faebe7f83 100644
--- a/docs/design/2026-10-03-harnessd.md
+++ b/docs/design/2026-10-03-harnessd.md
@@ -469,6 +469,15 @@ Done so far:
`cli/src/services/searchProcess.ts` runs the same index on a core API built in its own process.
`e2e/serviceProcesses.e2e.ts` proves on the real daemon that search killed, hung (stopped), leaking
or crashing on every start costs search alone: the core never restarts and agents keep working.
+- **The viewers in their own process** (`HARNESSD_SERVICES=viewers`, alone or beside search). The core
+ asks the viewers two things in line while it builds a frame: an agent's DSH context and where its
+ viewer pane forwards. So the process tells the core each agent's answers whenever they change, and
+ the core keeps the last ones (`cli/src/core/viewersLink.ts`). While the process is down, frames carry
+ what the core last knew. Attach and detach are notifications; a detach is held until the process
+ hears it, and the process asks for every agent with a harness each time it connects. The viewer
+ servers are the process's own: a crash costs only them (the new process stops the ones the old one
+ left running, then starts its own), and a core restart no longer restarts them.
+ `cli/e2e/viewersProcess.e2e.ts` proves it on the real daemon with a real harness agent's viewer.
- **Services answer their own requests** (core/serviceHost.ts `route`). A service declares the frame
types it answers (`<NAME>_REQUESTS`) and returns their handlers from its start. The socket hands
such a request to it before its own switch, with who asked (`Asker`: local, owner), and never