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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
feat(cli): harness route picks the harness a program's words for the person belong to, or new work, and --send types them into an idle one
200d3301614b9e0dd112c9b04f96
diff --git a/cli/src/agentClient/commands.spec.ts b/cli/src/agentClient/commands.spec.tsindex 1d4477e48..f54caf57f 100644--- a/cli/src/agentClient/commands.spec.ts+++ b/cli/src/agentClient/commands.spec.ts@@ -2,7 +2,7 @@ import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'import { tmpdir } from 'node:os'import { join } from 'node:path'import { afterEach, beforeEach, describe, expect, it } from 'vitest'-import { addressOf, agentOrigin, AGENTS_START_AGENTS_OFF, closeCommand, DEPTH_REFUSAL, EXIT, parseDuration, psCommand, refusalNext, replyCommand, showCommand, spawnCheck, spawnCount, spawnRefusal, SPAWN_LIMITS, step, tellCommand, waitCommand, watchCommand, whoamiCommand, type ClientDeps } from './commands.js'+import { addressOf, agentOrigin, AGENTS_START_AGENTS_OFF, closeCommand, DEPTH_REFUSAL, EXIT, parseDuration, psCommand, refusalNext, replyCommand, routeCommand, showCommand, spawnCheck, spawnCount, spawnRefusal, SPAWN_LIMITS, step, tellCommand, waitCommand, watchCommand, whoamiCommand, type ClientDeps } from './commands.js'import { RefusedError, type Rpc } from '../messages/rpc.js'import { AgentClientError, type Daemon, type Where } from './daemon.js'import { Ledger, ledgerPath } from './ledger.js'@@ -2210,3 +2210,114 @@ describe('harness reply to a harness in a pane (a program acting for the person)expect(JSON.parse(shown.out.join('\n'))).toMatchObject({ answer: 'Fixed: name added.' })})})++describe('harness route (a program acting for the person picks the harness)', () => {+ const replied = () => {+ const calls: Array<[string, Record<string, unknown>]> = []+ const record: Rpc = async (target, payload) => { calls.push([target.machineId, payload]); return { id: 'm0000001', state: 'queued' } }+ return { calls, record }+ }+ // The lamp's lamp-tasks, asking about the office computer's harnesses.+ const program = (d: FakeDaemon, office: FakeDaemon, over: Partial<ClientDeps> = {}) => {+ const h = harness(d, { pane: undefined, others: { m2: office }, ...over })+ h.deps.machines = async () => [{ machineId: 'm', label: 'studio', current: true }, { machineId: 'm2', label: 'office', current: false }] as never+ return h+ }+ const decides = (d: FakeDaemon, answer: Record<string, unknown>) => {+ const asked: Array<Record<string, unknown>> = []+ d.extra.route_decide = (payload) => { asked.push(payload); return answer }+ return asked+ }++ beforeEach(() => { setAgentSettingsForTest(dir, { programsReply: true }) })++ it('shows this machine\'s router that machine\'s harnesses in a pane, and types the words into the one it picks', async () => {+ const d = new FakeDaemon(), office = new FakeDaemon('m2')+ office.frames = [frame('week', { engine: 'devin' }), frame('skills', { engine: 'claude' }), frame('fo', { location: 'cloud' } as never), frame('old', { status: 'stopped' })]+ const asked = decides(d, { decided: 'session', id: 'week', via: 'jev', p: 0.9234, trace: '2 sessions · jev: "week" 92%' })+ const r = replied()+ const h = program(d, office, { record: r.record })+ expect(await routeCommand(['--machine', 'office', '--send', '--json', '--', 'how is the week log going?'], h.deps)).toBe(EXIT.ok)+ expect(asked).toEqual([{ text: 'how is the week log going?', projects: [], agents: [], sessions: [+ { id: 'week', name: 'week', asks: ['ask of week'], about: 'week recap' },+ { id: 'skills', name: 'skills', asks: ['ask of skills'], about: 'skills recap' },+ ] }])+ // Decided by THIS machine's router, never the office's.+ expect(office.requests.some((q) => q.type === 'route_decide')).toBe(false)+ expect(r.calls).toEqual([['m2', { action: 'reply_local', machine: 'studio', agentId: 'week', text: 'how is the week log going?' }]])+ expect(JSON.parse(h.out.join('\n'))).toMatchObject({ decided: 'session', id: 'week', name: 'week', machine: 'office', confidence: 0.923,+ reason: '2 sessions · jev: "week" 92%', sent: { state: 'queued' }, next: [{ run: 'harness wait --machine office week' }] })+ })++ it('says new work and sends nothing, so the caller starts it', async () => {+ const d = new FakeDaemon(), office = new FakeDaemon('m2')+ office.frames = [frame('week')]+ decides(d, { decided: 'new', via: 'jev', reason: 'Jev: new work' })+ const r = replied()+ const h = program(d, office, { record: r.record })+ expect(await routeCommand(['--machine', 'office', '--send', '--json', '--', 'write a haiku'], h.deps)).toBe(EXIT.ok)+ expect(JSON.parse(h.out.join('\n'))).toEqual({ decided: 'new', reason: 'Jev: new work' })+ expect(r.calls).toEqual([])+ })++ it('tells the router where this computer\'s last words for that machine went, within ten minutes only', async () => {+ const d = new FakeDaemon(), office = new FakeDaemon('m2')+ office.frames = [frame('week'), frame('skills')]+ const asked = decides(d, { decided: 'session', id: 'week', via: 'jev', p: 0.95, trace: 't' })+ const r = replied()+ const h = program(d, office, { record: r.record })+ expect(await routeCommand(['--machine', 'office', '--send', '--', 'read the week log'], h.deps)).toBe(EXIT.ok)+ expect(asked[0].last).toBeUndefined()+ h.advance(60_000)+ expect(await routeCommand(['--machine', 'office', '--', 'and the other one?'], h.deps)).toBe(EXIT.ok)+ expect(asked[1].last).toEqual({ id: 'week', agoMs: 60_000 })+ // Another computer's words for the office (its line in this ledger cannot be: each computer keeps its own) and+ // words for another machine never steer this one.+ h.ledger.append({ at: NOW + 60_000, by: { machineId: 'm', agentId: 'person' }, told: { machineId: 'm3', agentId: 'skills' }, probe: 'x' })+ expect(await routeCommand(['--machine', 'office', '--', 'and the other one?'], h.deps)).toBe(EXIT.ok)+ expect(asked[2].last).toEqual({ id: 'week', agoMs: 60_000 })+ h.advance(10 * 60_000)+ expect(await routeCommand(['--machine', 'office', '--', 'and the other one?'], h.deps)).toBe(EXIT.ok)+ expect(asked[3].last).toBeUndefined()+ })++ it('never sends to a harness still working: says NOT_IDLE, and to wait, not to start new work', async () => {+ const d = new FakeDaemon(), office = new FakeDaemon('m2')+ office.frames = [frame('week', { activity: { state: 'working' } })]+ decides(d, { decided: 'session', id: 'week', via: 'jev', p: 0.9, trace: 't' })+ const r = replied()+ const h = program(d, office, { record: r.record })+ expect(await routeCommand(['--machine', 'office', '--send', '--json', '--', 'how is it going?'], h.deps)).toBe(EXIT.ok)+ const said = JSON.parse(h.out.join('\n'))+ expect(said).toMatchObject({ decided: 'session', id: 'week', sent: { error: 'NOT_IDLE' }, next: [{ run: 'harness wait --machine office week' }] })+ expect(said.next[0].when).toMatch(/Never start new work/)+ expect(r.calls).toEqual([])+ expect(h.ledger.lastToldBy({ machineId: 'm', agentId: 'person' }, 'm2')).toBeNull()+ })++ it('is refused while the switch is off and for an agent, and asks the router nothing', async () => {+ const d = new FakeDaemon(), office = new FakeDaemon('m2')+ office.frames = [frame('week')]+ const asked = decides(d, { decided: 'session', id: 'week', via: 'jev', p: 0.9, trace: 't' })+ setAgentSettingsForTest(dir, { programsReply: false })+ let h = program(d, office)+ expect(await routeCommand(['--machine', 'office', '--', 'x'], h.deps)).toBe(EXIT.refused)+ expect(h.err.join('\n')).toContain('harness settings programs-reply on')+ setAgentSettingsForTest(dir, { programsReply: true })+ d.frames = [frame('lead', { engine: 'claude' })]+ h = harness(d)+ expect(await routeCommand(['--', 'x'], h.deps)).toBe(EXIT.refused)+ expect(asked).toEqual([])+ })++ it('decides nothing when the router cannot: the caller acts on nothing', async () => {+ const d = new FakeDaemon(), office = new FakeDaemon('m2')+ office.frames = [frame('week')]+ decides(d, { error: 'JEV_UNAVAILABLE', detail: "Harness's server did not answer in time" })+ const r = replied()+ const h = program(d, office, { record: r.record })+ expect(await routeCommand(['--machine', 'office', '--send', '--json', '--', 'x'], h.deps)).toBe(EXIT.failed)+ expect(JSON.parse(h.out.join('\n'))).toMatchObject({ error: 'ROUTER_UNAVAILABLE' })+ expect(r.calls).toEqual([])+ })+})diff --git a/cli/src/agentClient/commands.ts b/cli/src/agentClient/commands.tsindex 5b8be34ba..46991a47d 100644--- a/cli/src/agentClient/commands.ts+++ b/cli/src/agentClient/commands.ts@@ -71,6 +71,17 @@ To a harness in a pane, only when it is idle and the person allows it (harness styped into it once its composer is free. Then wait for it (harness wait <name>) and read its answer (harness show <name>).The person's, or a program's acting for them; an agent does not answer for the person.${ON_MACHINE}`+export const ROUTE_USAGE = `Usage: harness route [--machine <name>] [--send] [--json] -- <words…>++Says which of a machine's harnesses in a pane <words> belong to, as the person's ⌘B does: one of them, or new work.+With --send, words for an idle one are typed into it, as harness reply does; nothing is ever started. For a program+acting for the person, while they allow it (harness settings programs-reply).+--json answers {"decided":"session","id","name","machine","confidence","reason"} or {"decided":"new","reason"},+and with --send "sent": {"state":"queued"} or {"error":"NOT_IDLE"|"NOT_RUNNING",…}. NOT_IDLE: it is still working+on the last words or waits for the person. Wait for it (harness wait <name>) and send them with harness reply, or+say so: never start new work for them, or a follow-up ("how is it going?") becomes a second harness.+Exit status: 0 once decided (sent or not: read "sent"), 5 refused (switch off), 1 nothing decided (ROUTER_UNAVAILABLE).+${ON_MACHINE}`export const TELL_USAGE = `Usage: harness tell [--machine <name>] <name> [--json] -- <work…>Gives more work to a harness you started: typed into it once it is free, or given at its next tool call while it@@ -540,6 +551,21 @@ export function formatRows(rows: Row[], now: number, on = 'this machine'): strinreturn [head, ...lines].join('\n')}+/** What each live one of [rows] is about: the person's last asks and the summaries the daemon keeps (no transcript+ * read), filled in place. `harness ps`'s, and what `harness route` shows the router. */+async function describeRows(daemon: Daemon, rows: Row[]): Promise<void> {+ await Promise.all(rows.filter((r) => r.state !== 'stopped').slice(0, ABOUT_MAX).map(async (row) => {+ const recent = await daemon.request('agent_recent', { agentId: row.id, n: 3 }, 3_000).catch(() => null)+ if (!recent || recent.error) return+ const asks = (Array.isArray(recent.asks) ? recent.asks as unknown[] : []).filter((a): a is string => typeof a === 'string' && !!a.trim()).slice(0, 2)+ const about = (Array.isArray(recent.events) ? recent.events as Array<Record<string, unknown>> : [])+ .map((e) => (typeof e.recap === 'string' && e.recap ? e.recap : typeof e.text === 'string' ? e.text : '').replace(/\s+/g, ' ').trim())+ .filter(Boolean).slice(0, 3).map((t) => clip(t, 140))+ if (asks.length) row.asks = asks.map((a) => clip(asSaid(a).replace(/\s+/g, ' ').trim(), 200))+ if (about.length) row.about = about.join(' / ')+ }))+}+export function psCommand(argv: readonly string[], deps: ClientDeps = {}): Promise<number> {return run(PS_USAGE, deps, wantsJson, argv, async (s) => {const { names, flags, machine } = words(argv, { '--all': 'flag', '--json': 'flag' })@@ -555,17 +581,7 @@ export function psCommand(argv: readonly string[], deps: ClientDeps = {}): Promi: { daemon: o.daemon, machineId: o.where.machineId, machine: o.machine }const frames = line ? await list(line, all) : o.framesconst rows = rowsOf(frames, { machineId: on.machineId, machine: on.machine, caller: o.caller, ledger: o.ledger, now: s.now(), all })- // What each is about: the summaries the daemon keeps (no transcript read), for the live ones.- await Promise.all(rows.filter((r) => r.state !== 'stopped').slice(0, ABOUT_MAX).map(async (row) => {- const recent = await on.daemon.request('agent_recent', { agentId: row.id, n: 3 }, 3_000).catch(() => null)- if (!recent || recent.error) return- const asks = (Array.isArray(recent.asks) ? recent.asks as unknown[] : []).filter((a): a is string => typeof a === 'string' && !!a.trim()).slice(0, 2)- const about = (Array.isArray(recent.events) ? recent.events as Array<Record<string, unknown>> : [])- .map((e) => (typeof e.recap === 'string' && e.recap ? e.recap : typeof e.text === 'string' ? e.text : '').replace(/\s+/g, ' ').trim())- .filter(Boolean).slice(0, 3).map((t) => clip(t, 140))- if (asks.length) row.asks = asks.map((a) => clip(asSaid(a).replace(/\s+/g, ' ').trim(), 200))- if (about.length) row.about = about.join(' / ')- }))+ await describeRows(on.daemon, rows)// Asked for and not started yet: listed by the name it was given, and what it waits for.rows.unshift(...o.asked.filter((a) => !away || a.row.creation.machineId === away.machineId).map((a): Row => ({name: askedName(a), id: a.row.creation.creationId, agent: engineName(a.row.creation.engine),@@ -766,17 +782,7 @@ export function replyCommand(argv: readonly string[], deps: ClientDeps = {}): Pr// A harness in a pane, for a program acting for the person (messages/replyLocal.ts): the machine it runs on// checks the switch and that it is idle again, and queues the words in its mailbox.if (!readAgentSettings(o.where.dataDir).programsReply) throw new AgentClientError('REPLY_OFF', REPLY_OFF_TEXT)- const state = stateOf(t.frame)- if (state === 'stopped' || state === 'offline') throw new AgentClientError('NOT_RUNNING', `${name} is no longer running: it was closed or stopped. Start a new harness with the whole task.`)- if (state !== 'idle') throw new AgentClientError('NOT_IDLE', state === 'working' ? `${name} is working. Wait for it to finish (${step(s.env, 'wait', at)}), then reply.` : `${name} is not idle: it may be waiting for the person (a question or a permission). Only they answer that.`)- let reply: Record<string, unknown>- try { reply = await s.record({ port: o.where.port, dataDir: o.where.dataDir, machineId: t.machineId }, { action: 'reply_local', machine: o.machine, agentId: t.frame.id, text }, 20_000) } catch (error) {- if (error instanceof MessageError) throw new AgentClientError(error.code, error.message)- throw error- }- // As a tell's: `wait` and `show` then hold the answer to the work before until it has taken these words.- try { o.ledger.append({ at: s.now(), by: { machineId: o.where.machineId, agentId: PERSON_AGENT_ID }, told: { machineId: t.machineId, agentId: t.frame.id }, probe: flat(text).slice(0, PROBE_CHARS) }) }- catch { /* `wait` then reads its last answer as it would without the line */ }+ const reply = await replyInPane(s, o, t, text, at)const failed = reply.state === 'failed'const effect = failed ? `${name} did not take it: ${typeof reply.reason === 'string' ? reply.reason : 'its machine refused it'}.` : `${name} has it: typed once its composer is free.`s.out(flags.has('--json') ? JSON.stringify({ ok: !failed, name, id: t.frame.id, message: reply.id ?? null, state: reply.state ?? 'queued', effect, next: failed ? [] : next })@@ -791,6 +797,105 @@ export function replyCommand(argv: readonly string[], deps: ClientDeps = {}): Pr})}+/** How long words sent from here still steer a follow-up that names nothing ("and the other one?") to where they went. */+const ROUTE_LAST_MS = 10 * 60_000++/**+ * Where a program's words for the person go (docs/design/2026-10-09-auto-router.md): the machine's harnesses in a+ * pane, as `ps` reads them, are shown to this machine's router (services/router.ts `route_decide`), which picks one or+ * says new work. With `--send` the words go into the one picked, idle only, as `harness reply` types them; new work is+ * the caller's to start (`harness new`). The same caller policy as `reply` (#1628): the person's switch, never an agent.+ */+export function routeCommand(argv: readonly string[], deps: ClientDeps = {}): Promise<number> {+ return run(ROUTE_USAGE, deps, wantsJson, argv, async (s) => {+ const dash = argv.indexOf('--')+ const { names, flags, machine } = words(dash < 0 ? argv : argv.slice(0, dash), { '--json': 'flag', '--send': 'flag' })+ const text = dash < 0 ? '' : argv.slice(dash + 1).join(' ').trim()+ if (names.length) throw new UsageError('harness route takes no name: it picks one. Give the words after --.')+ if (!text) throw new UsageError('Give the words after --: harness route -- <words>')+ const away = await machineOf(s, s.where(), machine)+ const o = await opened(s)+ let line: Daemon | null = null+ try {+ if (o.caller || o.orphan) throw new AgentClientError('NOT_YOURS', 'Only the person, or a program acting for them, routes words to a harness. To give more work to one you started, use harness tell.')+ if (!readAgentSettings(o.where.dataDir).programsReply) throw new AgentClientError('REPLY_OFF', REPLY_OFF_TEXT)+ const on = away+ ? { daemon: line = await s.open(o.where, away.machineId), machineId: away.machineId, machine: away.label }+ : { daemon: o.daemon, machineId: o.where.machineId, machine: o.machine }+ // Harnesses in a pane only: a cloud one is answered with `harness reply`, through its maker.+ const frames = (line ? await list(line, false) : o.frames).filter((f) => isAgent(f) && f.location !== 'cloud')+ const rows = rowsOf(frames, { machineId: on.machineId, machine: on.machine, caller: o.caller, ledger: o.ledger, now: s.now(), all: false })+ .filter((r) => r.state !== 'stopped')+ await describeRows(on.daemon, rows)+ // Where this computer's last words for that machine went, within ROUTE_LAST_MS. This computer's ledger, so one+ // lamp's follow-up is never steered by another's.+ const told = o.ledger.lastToldBy({ machineId: o.where.machineId, agentId: PERSON_AGENT_ID }, on.machineId)+ const last = told && s.now() - told.at <= ROUTE_LAST_MS && rows.some((r) => r.id === told.told.agentId)+ ? { id: told.told.agentId, agoMs: s.now() - told.at } : undefined+ const sessions = rows.map((r) => ({ id: r.id, name: r.name, asks: r.asks ?? [], ...(r.about ? { about: r.about } : {}) }))+ // Asked of THIS machine's router, as the owner over its own socket: the list is the caller's, so a harness on+ // another computer is routed to as well as one here.+ const verdict = await o.daemon.request('route_decide', { text, sessions, projects: [], agents: [], ...(last ? { last } : {}) }, 15_000)+ if (typeof verdict.error === 'string') {+ throw new AgentClientError('ROUTER_UNAVAILABLE', `Nothing was decided (${verdict.error}${typeof verdict.detail === 'string' ? `: ${verdict.detail}` : ''}). Act on nothing, or ask the person.`)+ }+ const row = verdict.decided === 'session' ? rows.find((r) => r.id === verdict.id) : undefined+ if (!row) {+ const reason = typeof verdict.reason === 'string' ? verdict.reason : 'new work'+ s.out(flags.has('--json') ? JSON.stringify({ decided: 'new', reason }) : `New work: ${reason}. Start it with harness new.`)+ return EXIT.ok+ }+ const decided = { decided: 'session', id: row.id, name: row.name, machine: on.machine,+ confidence: typeof verdict.p === 'number' ? Math.round(verdict.p * 1000) / 1000 : null,+ reason: typeof verdict.trace === 'string' ? verdict.trace : null }+ if (!flags.has('--send')) {+ s.out(flags.has('--json') ? JSON.stringify(decided) : `${row.name} on ${on.machine}${decided.confidence !== null ? ` (${Math.round(decided.confidence * 100)}%)` : ''}`)+ return EXIT.ok+ }+ const frame = frames.find((f) => f.id === row.id)!+ const at = onAway(addressOf({ machineId: '', agentId: row.id, name: row.name, engine: '' }), away)+ let sent: Record<string, unknown>+ try {+ const reply = await replyInPane(s, o, { daemon: on.daemon, frame, machineId: on.machineId, machine: on.machine, yours: false, remote: !!line }, text, at)+ sent = reply.state === 'failed'+ ? { error: 'FAILED', detail: typeof reply.reason === 'string' ? reply.reason : 'its machine refused it' }+ : { state: typeof reply.state === 'string' ? reply.state : 'queued', message: reply.id ?? null }+ } catch (error) {+ if (!(error instanceof AgentClientError) || !['NOT_IDLE', 'NOT_RUNNING'].includes(error.code)) throw error+ sent = { error: error.code, detail: error.message }+ }+ const next: NextStep[] = sent.error === 'NOT_IDLE'+ ? [{ run: step(s.env, 'wait', at), when: 'it is still on the last words: then send these with harness reply. Never start new work for them' }]+ : sent.error ? [] : [{ run: step(s.env, 'wait', at), when: 'for its answer' }]+ s.out(flags.has('--json') ? JSON.stringify({ ...decided, sent, next })+ : [`${row.name} on ${on.machine}: ${sent.error ? `not sent (${sent.detail})` : 'has it: typed once its composer is free.'}`, formatNext(next)].filter(Boolean).join('\n'))+ return EXIT.ok+ } finally { line?.close(); o.daemon.close() }+ })+}++/**+ * [text] typed into [t], a harness in a pane, for the person (messages/replyLocal.ts): only while it is idle. The+ * machine it runs on checks the switch and that it is idle again, and queues the words in its mailbox; its answer is+ * returned. `harness reply`'s and `harness route --send`'s, which check the person's switch first.+ */+async function replyInPane(s: Setup, o: Opened, t: Target, text: string, at: string): Promise<Record<string, unknown>> {+ const name = t.frame.name ?? t.frame.id.slice(0, 8)+ const state = stateOf(t.frame)+ if (state === 'stopped' || state === 'offline') throw new AgentClientError('NOT_RUNNING', `${name} is no longer running: it was closed or stopped. Start a new harness with the whole task.`)+ if (state !== 'idle') throw new AgentClientError('NOT_IDLE', state === 'working' ? `${name} is working. Wait for it to finish (${step(s.env, 'wait', at)}), then reply.` : `${name} is not idle: it may be waiting for the person (a question or a permission). Only they answer that.`)+ let reply: Record<string, unknown>+ try { reply = await s.record({ port: o.where.port, dataDir: o.where.dataDir, machineId: t.machineId }, { action: 'reply_local', machine: o.machine, agentId: t.frame.id, text }, 20_000) } catch (error) {+ if (error instanceof MessageError) throw new AgentClientError(error.code, error.message)+ throw error+ }+ // As a tell's: `wait` and `show` then hold the answer to the work before until it has taken these words, and the+ // next `harness route` from here takes it for where the last words went (`Ledger.lastToldBy`).+ try { o.ledger.append({ at: s.now(), by: { machineId: o.where.machineId, agentId: PERSON_AGENT_ID }, told: { machineId: t.machineId, agentId: t.frame.id }, probe: flat(text).slice(0, PROBE_CHARS) }) }+ catch { /* `wait` then reads its last answer as it would without the line */ }+ return reply+}+// ── tell ───────────────────────────────────────────────────────────────────────────────────────────/**diff --git a/cli/src/agentClient/ledger.ts b/cli/src/agentClient/ledger.tsindex 79ae2d538..972658061 100644--- a/cli/src/agentClient/ledger.ts+++ b/cli/src/agentClient/ledger.ts@@ -190,6 +190,12 @@ export class Ledger {return this.read().told.findLast((row) => same(row.by, by) && same(row.told, m)) ?? null}+ /** The last words [by] gave any harness on [machineId] (`harness reply`, `harness route --send`), or null. This+ * machine's ledger holds only its own callers' lines, so another computer's follow-up never steers this one's. */+ lastToldBy(by: LedgerMember, machineId: string): Told | null {+ return this.read().told.findLast((row) => same(row.by, by) && row.told.machineId === machineId) ?? null+ }+/** 0 for a harness the person started. */depthOf(m: LedgerMember): number {return this.parentOf(m)?.depth ?? 0diff --git a/cli/src/cli.ts b/cli/src/cli.tsindex 8bc2d1bee..b4da69c2f 100644--- a/cli/src/cli.ts+++ b/cli/src/cli.ts@@ -175,7 +175,8 @@ Machine:harness close <name> [--now] save a harness's screen and stop it; an agent closes only what it startedharness tell <name> -- <w> from an agent's pane: more work for a harness it started (agents-tell-agents)harness reply <name> -- <w> say words to a cloud harness (Devin Cloud, Cursor Cloud, Fo): its answer or what next- new, ps, show, wait, watch, tell, reply and close take --machine <name> for another of your+ harness route [--send] -- <w> which harness words belong to, or new work; --send types them into an idle one (programs-reply)+ new, ps, show, wait, watch, tell, reply, route and close take --machine <name> for another of yourmachines: \`harness show --machine office x\`harness mcp the agent verbs as an MCP server on stdin/stdout, for agents that use MCPharness help agents the agent commands, states, exit codes and rules on one screen@@ -2713,7 +2714,7 @@ async function logsExportCommand(json: boolean): Promise<void> {import { orchestratorCommand } from './orchestrator/command.js'import { paneOwner, sendCommand, sendPane } from './messages/command.js'-import { agentOrigin, closeCommand, psCommand, replyCommand, showCommand, tellCommand, waitCommand, watchCommand, whoamiCommand } from './agentClient/commands.js'+import { agentOrigin, closeCommand, psCommand, replyCommand, routeCommand, showCommand, tellCommand, waitCommand, watchCommand, whoamiCommand } from './agentClient/commands.js'import { agentsHelp, helpFor } from './agentClient/help.js'import { openUrlCommand } from './agentClient/openUrl.js'import { harnessRunner, mcpCommand } from './agentClient/mcp.js'@@ -2807,6 +2808,9 @@ switch (cmd) {case 'reply':replyCommand(rest, { machines: usableMachines }).then(code => { process.exitCode = code }).catch(onError)break+ case 'route':+ routeCommand(rest, { machines: usableMachines }).then(code => { process.exitCode = code }).catch(onError)+ breakcase 'tell':unlessBuddy(() => tellCommand(rest, { machines: usableMachines })).then(code => { process.exitCode = code }).catch(onError)breakdiff --git a/cli/src/services/router.spec.ts b/cli/src/services/router.spec.tsindex 07ea92924..700672bbc 100644--- a/cli/src/services/router.spec.ts+++ b/cli/src/services/router.spec.ts@@ -154,7 +154,7 @@ describe('the router', () => {const jev = vi.fn(async () => ({ target: said('s0', 0.8, ['s0', 's1', 'new']) }))const { router: made, lines } = router({ jev })expect(await startRouter(fakeCore(), made).route_decide!({ text: 'refund it', sessions: DESK }, OWNER))- .toEqual({ decided: 'session', id: 'a1', via: 'jev' })+ .toEqual({ decided: 'session', id: 'a1', via: 'jev', p: 0.8, trace: '2 sessions · jev: "billing retries" 0.80, then "Prometheus alerts" 0.10' })expect(lines).toEqual(['session — 2 sessions · jev: "billing retries" 0.80, then "Prometheus alerts" 0.10'])// Jev was asked the task as the client sent it, trimmed.expect(jev).toHaveBeenCalledWith({ message: 'refund it' }, expect.objectContaining({ target: expect.any(Object) }), undefined)diff --git a/cli/src/services/router.ts b/cli/src/services/router.tsindex eaa45bb04..136490829 100644--- a/cli/src/services/router.ts+++ b/cli/src/services/router.ts@@ -98,7 +98,8 @@ export function startRouter(core: CoreApi, router: Router = defaultRouter(core))router.log?.(`${verdict.kind === 'session' ? 'session' : verdict.kind === 'new' ? `new (${verdict.why})` : `nothing decided (${verdict.why})`} — ${verdict.trace}`)if (verdict.kind === 'unavailable') return { error: 'JEV_UNAVAILABLE', detail: verdict.why }return verdict.kind === 'session'- ? { decided: 'session', id: verdict.id, via: 'jev' }+ // `p` and `trace` for a caller that shows or logs why (`harness route`): names and odds only, never the words.+ ? { decided: 'session', id: verdict.id, via: 'jev', p: verdict.p, trace: verdict.trace }: { decided: 'new', via: verdict.via, reason: verdict.why, ...(verdict.project ? { project: verdict.project } : {}), ...(verdict.agent ? { agent: verdict.agent } : {}) }} finally { pending.delete(request) }},diff --git a/docs/cli.md b/docs/cli.mdindex 9ccc7d3c3..9dccf0942 100644--- a/docs/cli.md+++ b/docs/cli.md@@ -128,6 +128,29 @@ in once its composer is free, never over a draft, with `tell`'s limits. Then `haafter a start: `wait` does not return on the answer to the work before. An agent uses `harness tell` instead, for aharness it started.+`harness route [--machine <name>] [--send] [--json] -- <words>` is the person's ⌘B for such a program (a lamp that+heard a request): which of a machine's harnesses in a pane the words belong to, or new work. It reads that machine's+harnesses as `ps` does (name, the person's last asks, what each is about) and asks this machine's router+(`services/router.ts`, Jev; the [design](design/2026-10-09-auto-router.md)), so no device need be paired and+nothing is asked of the backend beyond Jev's own route. `--json` answers `{"decided":"session", "id", "name",+"machine", "confidence", "reason"}` (Jev's odds and its trace: names and odds, never the words) or+`{"decided":"new", "reason"}`; new work is the caller's to start with `harness new`. When the router cannot be asked+it answers `ROUTER_UNAVAILABLE` (exit 1): nothing was decided, and the caller acts on nothing.++- **`--send`** types the words into the harness picked exactly as `harness reply` does: idle only, through its+ machine's mailbox. The answer adds `"sent": {"state": "queued"}`, or `{"error": "NOT_IDLE" | "NOT_RUNNING"}` with+ nothing sent. Exit 0 once decided, sent or not: read `sent`.+- **`NOT_IDLE`** means it is still on the last words, or waits for the person. Wait for it (`harness wait`, the+ answer's `next`) and send them with `harness reply`, or say so. Never start new work for them: a follow-up ("how is+ it going?") would become a second harness.+- **A follow-up that names nothing** ("and the other one?") goes where this computer's last words for that machine+ went within ten minutes: the `Told` line `reply` and `route --send` write in this computer's own ledger+ (`Ledger.lastToldBy`). Each computer keeps its own, so one lamp's follow-up never steers another's.+- **The caller policy is `reply`'s:** the person's `programs-reply` switch for the whole command, deciding included+ (exit 5 while it is off), and never an agent in a pane (`NOT_YOURS`).+- **Cost and time:** one decision is about $0.00017 and 0.4 to 0.7 s on Harness's key (bounded at 8 s), capped per+ account at 30 a minute and 1,000 a day.+`harness watch <name>` follows one harness for a program that acts on it: a line each time it changes, one JSONobject a line with `--json`, until it stops or is gone (exit 4) or `--timeout` passes (exit 124; `0`, the default,follows it as long as it lives). It decides as `wait` does: the maker's state for a cloud harness; the daemon's