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
/**
* Keeps this machine's trust group (trustGroup.ts) in step with every other member, and turns what the
* roster says into the two trust stores that actually gate a connection:
* - machinePeers.json — the key this machine expects when it DIALS a machine member;
* - paired.json (through E2eeManager) — the keys allowed to open a session HERE.
*
* Both halves of the exchange are one sealed RPC, `group_sync`, over the ordinary relay session: the
* dialer sends its roster and itself, the dialed machine merges, answers with its own, and the dialer
* merges that. Whatever changed is then pushed on to the other members, so a link made anywhere
* reaches everyone who is online, and the rest catch up on their next contact.
*
* A machine shared across accounts (gateway/sharedTrust.ts, marked `shared` in both stores) is never part
* of this: rosters are not exchanged with it, it is not seeded from its pin or its trust, and a
* `group_sync` from it is refused. Otherwise sharing one machine would make the colleague's other
* machines trusted here, and this account's trusted by theirs.
*
* Nor is one of the account's team machines (machineKinds.ts): a Harness Team account's daemon, or a computer
* that runs team work only, runs teammates' agents, so a hostile one could otherwise add or drop the keys this
* machine trusts. It stays pinned and trusted, so the person's apps still reach it, but its roster is never
* merged and this one is never sent to it. A machine whose kind the account's machine list cannot say is
* treated the same way.
*/
import type { Frame, LocalClientSink } from '../../backendSocket.js'
import type { RelaySession } from '../remoteRelay.js'
import type { MachineKind } from './machineKinds.js'
import type { MachinePeerStore } from './machinePeers.js'
import type { LinkedPeer } from './manager.js'
import type { PairedClient } from './store.js'
import { parseMember, parseRoster, rosterDigest, type GroupMember, type MergeResult, type Roster, type TrustGroupStore } from './trustGroup.js'
/** The device key log's side of a `group_sync` (deviceLogSyncer.ts): its head rides every exchange, so
* two devices shown different logs find out, and one that is behind is handed what it is missing. */
export interface GroupSyncLogGossip {
/** What this machine sends with its roster. */
gossip: () => Record<string, unknown> | undefined
/** What a peer sent; returns what to answer with (a responder's own head, and entries the peer lacks). */
heard: (peerPub: string, raw: unknown) => Record<string, unknown> | undefined
}
export const GROUP_SYNC = 'group_sync'
/** The stamp a device's description of ITSELF carries: older than anything, so any removal beats it and
* a removed device cannot sync its way back in — only a new link (stamped now) can. */
export const SELF_STAMP = 1
const SYNC_TIMEOUT_MS = 20_000
const PERIODIC_MS = 10 * 60_000
/** A machine synced this recently is not synced again just because a session to it opened. */
const RECONTACT_MS = 5 * 60_000
/** After a round where a member could not be reached (or refused, having not heard of this machine yet),
* try again this soon — then less often. The periodic round takes over after the last. The first is 30 s, the backend's
* retry-after for an offline machine and the relay's longest hold: at 15 s the retry asked an offline machine again
* through the background pools before that was up (socket churn e2e, 2026-10-29). */
const RETRY_MS = [30_000, 60_000, 4 * 60_000]
export interface GroupSyncerDeps {
store: TrustGroupStore
peers: MachinePeerStore
/** This machine, as the group should know it (stamped SELF_STAMP). */
self: () => GroupMember
/** Allow `peer` to open a session here (idempotent). */
trust: (peer: LinkedPeer) => void
/** Stop allowing `pub` here; drops its live sessions. */
untrust: (pub: string) => void
/** paired.json, for seeding the roster from links made before the group existed. */
paired: () => PairedClient[]
/** One sealed request/response with a machine over the relay; null when it could not be reached or
* did not answer (an older machine answers nothing for an unknown type). */
request: (machineId: string, frame: Frame, timeoutMs: number) => Promise<Frame | null>
/** Close every open relay session to a machine the group removed — a lingering one would otherwise
* keep working after its pin is gone, since a pooled session is reused without looking again. */
dropSessions?: (machineId: string) => void
/** Keys a fork put out of trust here until reviewed (deviceLogSyncer.ts): never pinned, trusted or dialed. */
suspended?: () => ReadonlySet<string>
/** Machines worth dialing now; null = unknown, try every member. */
reachable?: () => Set<string> | null
/** Whether `pub` is a machine of another account trusted only because it is shared with this one (or this
* one with it): it never takes part in the group. */
shared?: (pub: string) => boolean
/** What the account's machine list says a machine is (machineKinds.ts): only `computer`, one of the person's own,
* takes part in the group. `team` and unknown (null) never do. `fresh` reads the list again when it is old. */
machineKinds: { kind: (machineId: string) => MachineKind | null; fresh?: () => Promise<void>
/** No team machine ever on this computer (machineKinds.ts): every machine syncs as before team machines. */
teamFree?: () => boolean }
/** Whether the roster here is the account's this machine is signed in to (deviceLogSyncer `current`).
* While not, nothing is swapped: a daemon started after a switch of accounts read the new account's
* log only after its first rounds, and handed the roster of the account it left to the new one's
* machines. */
ready?: () => boolean
now?: () => number
log?: (line: string) => void
}
export class GroupSyncer {
private readonly now: () => number
private readonly lastSynced = new Map<string, number>()
private readonly inFlight = new Map<string, Promise<boolean>>()
private fanOutTimer: ReturnType<typeof setTimeout> | null = null
/** When the pending fan-out runs. */
private fanOutAt = 0
private periodic: ReturnType<typeof setInterval> | null = null
private retryRound = 0
/** Bumped when the account changes: an exchange started before is not merged into the new roster. */
private generation = 0
/** Set once the device key log is wired up; the exchange works without it, as with an older peer. */
devlog: GroupSyncLogGossip | null = null
/** A member the GROUP removed (a tombstone that arrived by `group_sync` — from a device that
* predates the device key log, say): the log must hear of it too, or it would trust the key again. */
onDropped: ((pub: string) => void) | null = null
constructor(private readonly deps: GroupSyncerDeps) {
this.now = deps.now ?? (() => Date.now())
}
/** Seed the roster from links that predate it, re-apply it to the trust stores, and start the
* periodic catch-up. Safe to call once per daemon. */
start(): void {
this.seedFromExistingLinks()
this.applyAll()
this.scheduleFanOut(30_000)
this.periodic = setInterval(() => this.scheduleFanOut(0), PERIODIC_MS)
this.periodic.unref?.()
}
stop(): void {
if (this.periodic) clearInterval(this.periodic)
if (this.fanOutTimer) clearTimeout(this.fanOutTimer)
this.periodic = null
this.fanOutTimer = null
}
roster(): Roster { return this.deps.store.read() }
/** The trust stores were swapped for another account's (accountTrust.ts): who was synced, and what is
* on its way, belong to the one left. */
reset(): void {
this.generation++
this.lastSynced.clear()
this.inFlight.clear()
}
/** A device just linked to or from this machine over the remote password: it joins the group, and the
* rest of the group hears of it. */
linked(peer: LinkedPeer): void {
if (!peer.kind) return // an older joiner that did not say what it is — it stays a plain pairing
const member = parseMember({ ...peer, at: this.now() }, this.now())
if (!member) return
this.deps.store.unblock(member.pub) // linking again is the way back after an unpair
this.apply(this.deps.store.add(member, this.selfPub()))
this.scheduleFanOut(0)
}
/** Remove a member everywhere (`harness group remove`, `harness link unlink`). */
remove(pub: string): boolean {
const known = this.deps.store.read().members.some((m) => m.pub === pub)
const result = this.deps.store.remove(pub, this.selfPub(), this.now())
this.apply(result)
// Not in the roster (a link that predates it): still stop trusting it here.
if (!known) this.forget(pub)
this.scheduleFanOut(0)
return known || result.dropped.length > 0
}
/** A fork put these keys out of trust here: unpin, untrust and stop dialing them — locally only (no
* tombstone, so nothing is removed for anyone else) until `resume`. */
suspend(pubs: readonly string[]): void {
for (const pub of pubs) this.forget(pub)
}
/** The suspension was lifted (a review): pin and trust the roster again. */
resume(): void {
this.applyAll()
}
/** This machine's user unpaired `pub` (`harness unpair`): stop trusting and dialing it HERE, and keep
* it that way — without this the next round would put back what the roster still names. */
unpaired(pub: string): void {
this.deps.store.block(pub)
this.forget(pub)
}
/** Keys the device key log holds (deviceLogSyncer.ts): members of the group like any link, stamped
* when they joined the log, so a device that predates the log hears of them through the group. A key
* the roster holds already, as it is, is trusted here too if it is not: the merge has nothing new to
* say about it, and when it was all that trusted a key, one roster that outran this machine's trust
* (a crash between the two writes, a peer's roster first) kept that device out for good. */
adoptFromLog(members: Array<{ pub: string; kind: GroupMember['kind']; machineId: string; label: string; addedAt: number }>): void {
const now = this.now()
const parsed = members
.map((m) => parseMember({ pub: m.pub, kind: m.kind, label: m.label, at: Math.min(m.addedAt, now), ...(m.machineId ? { machineId: m.machineId } : {}) }, now))
.filter((m): m is GroupMember => m !== null)
if (!parsed.length) return
const before = rosterDigest(this.deps.store.read())
const merged = this.deps.store.merge({ members: parsed, removed: [] }, this.selfPub())
const paired = new Set(this.deps.paired().map((p) => p.identityPub))
const untrusted = merged.roster.members.filter((m) =>
!paired.has(m.pub) && parsed.some((p) => p.pub === m.pub) && !merged.upserted.some((u) => u.pub === m.pub))
const result = { ...merged, upserted: [...merged.upserted, ...untrusted] }
this.apply(result)
if (rosterDigest(result.roster) !== before) this.scheduleFanOut(1_000)
}
/** Whether the group removed `pub` and nothing has put it back. */
tombstoned(pub: string): boolean {
const roster = this.deps.store.read()
return roster.removed.some((t) => t.pub === pub) && !roster.members.some((m) => m.pub === pub)
}
/** Whether `pub` is a member of the group. */
isMember(pub: string): boolean {
return this.deps.store.read().members.some((m) => m.pub === pub)
}
/** Whether this machine's user unpaired `pub` here. */
isBlocked(pub: string): boolean {
return this.deps.store.blocked().has(pub)
}
/** A session to `machineId` just opened: a good moment to compare rosters, unless we just did. */
sessionOpened(machineId: string): void {
const last = this.lastSynced.get(machineId) ?? 0
if (this.now() - last < RECONTACT_MS) return
void this.syncWith(machineId)
}
/** Responder side of `group_sync`, for a sealed request from the session identity `peerPub`. */
handle(peerPub: string, payload: Record<string, unknown>): Record<string, unknown> {
if (this.deps.shared?.(peerPub)) return { error: 'SHARED' }
const refused = this.machinePeerRefusal(peerPub, payload.self)
if (refused) return { error: refused }
if (this.deps.ready?.() === false) {
const none: Roster = { members: [], removed: [] }
return { ...none, digest: rosterDigest(none) }
}
const now = this.now()
const incoming = parseRoster(payload, now)
const self = parseMember(payload.self, now)
// A peer may describe only itself — its `self` must be the key its session proved.
if (self && self.pub === peerPub) incoming.members.push(self)
const before = rosterDigest(this.deps.store.read())
const result = this.deps.store.merge(incoming, this.selfPub())
this.apply(result)
// A member that reached us is one we can reach: put back a pin the relay dropped when this machine
// dialed it before it had heard of us (remoteRelay.ts unlinks a peer that answers e2e_denied).
this.applyAll()
if (rosterDigest(result.roster) !== before) this.scheduleFanOut(1_000)
const devlog = this.devlog?.heard(peerPub, payload.devlog)
return { self: this.deps.self(), ...result.roster, digest: rosterDigest(result.roster), ...(devlog ? { devlog } : {}) }
}
/** Initiator side: exchange rosters with one machine; true when it answered. Never throws. */
syncWith(machineId: string): Promise<boolean> {
const running = this.inFlight.get(machineId)
if (running) return running
const task = this.exchange(machineId).catch(() => false).finally(() => this.inFlight.delete(machineId))
this.inFlight.set(machineId, task)
return task
}
/** Every reachable machine member (and every machine pinned outside the roster), one at a time. */
async syncAll(): Promise<void> {
if (this.deps.ready?.() === false) { this.retryLater(); return }
await this.deps.machineKinds.fresh?.().catch(() => { /* an old list ages out on its own */ })
// Put back any pin the relay dropped. A member can hear of another before that one hears of it,
// and its first dial is then refused — remoteRelay.ts unlinks a peer that answers e2e_denied. The
// roster still says they belong together, so they are re-pinned and tried again on this round.
this.applyAll()
const reachable = this.deps.reachable?.() ?? null
const self = this.deps.self().machineId
const targets = new Set<string>()
const suspended = this.deps.suspended?.() ?? new Set<string>()
for (const m of this.deps.store.read().members) if (m.kind === 'machine' && m.machineId && !suspended.has(m.pub)) targets.add(m.machineId)
for (const p of this.deps.peers.list()) if (!suspended.has(p.pub) && !p.shared) targets.add(p.machineId)
if (self) targets.delete(self)
for (const machineId of this.deps.peers.gone()) targets.delete(machineId)
// A team machine, or one the account's list cannot place, is not dialed: not a member that missed this round.
for (const machineId of targets) if (!this.ordinary(machineId)) targets.delete(machineId)
// All at once: one machine that never answers (offline, or too old to know the frame) must not
// hold up the rest for its whole timeout.
const due = [...targets].filter((machineId) => !reachable || reachable.has(machineId))
const answered = await Promise.all(due.map((machineId) => this.syncWith(machineId)))
const members = new Set(this.deps.store.read().members.map((m) => m.machineId))
const missed = due.some((machineId, i) => !answered[i] && members.has(machineId))
if (!missed) { this.retryRound = 0; return }
this.retryLater()
}
private retryLater(): void {
const delay = RETRY_MS[this.retryRound]
if (delay === undefined) return // the periodic round takes over
this.retryRound++
this.scheduleFanOut(delay, true)
}
private async exchange(machineId: string): Promise<boolean> {
if (!this.deps.peers.get(machineId) || this.deps.ready?.() === false) return false
const generation = this.generation
await this.deps.machineKinds.fresh?.().catch(() => { /* an old list ages out on its own */ })
const pin = this.deps.peers.get(machineId)
// Nothing is sent to a team machine, or to one the account's list cannot place: this roster is not theirs to read.
if (!pin || pin.shared || this.deps.ready?.() === false || generation !== this.generation || !this.ordinary(machineId)) return false
const local = this.deps.store.read()
const devlog = this.devlog?.gossip()
const reply = await this.deps.request(machineId, {
type: GROUP_SYNC,
payload: {
requestId: `gs-${this.now()}-${Math.random().toString(36).slice(2, 8)}`, self: this.deps.self(), ...local, digest: rosterDigest(local),
...(devlog ? { devlog } : {}),
},
}, SYNC_TIMEOUT_MS).catch(() => null)
if (!reply || generation !== this.generation) return false
this.lastSynced.set(machineId, this.now())
const payload = (reply.payload ?? {}) as Record<string, unknown>
if (typeof payload.error === 'string') return false
const now = this.now()
const incoming = parseRoster(payload, now)
const theirSelf = parseMember(payload.self, now)
// The answering machine may describe only itself, as the key this machine dialed and verified.
if (theirSelf && theirSelf.pub === pin.pub && theirSelf.machineId === machineId) incoming.members.push(theirSelf)
if (payload.devlog !== undefined) this.devlog?.heard(pin.pub, payload.devlog)
// Compared with the roster as it is now, not the one sent: a link can land while this was in flight.
const before = rosterDigest(this.deps.store.read())
const result = this.deps.store.merge(incoming, this.selfPub())
this.apply(result)
if (rosterDigest(result.roster) !== before) {
this.deps.log?.(`[group] ${machineId.slice(0, 8)}: +${result.upserted.length} −${result.dropped.length}`)
this.scheduleFanOut(1_000)
}
return true
}
/** `retry`: a follow-up to a round that missed someone. Anything else is news, which starts the
* retry schedule over. */
private scheduleFanOut(delayMs: number, retry = false): void {
if (!retry) this.retryRound = 0
if (this.fanOutTimer) {
// News does not wait behind a retry for a missed member (review of #2104): a link made during a 30 s retry went
// out at the retry, not at once. A retry never moves a fan-out that is already due sooner.
if (retry || Date.now() + delayMs >= this.fanOutAt) return
clearTimeout(this.fanOutTimer)
}
this.fanOutAt = Date.now() + delayMs
this.fanOutTimer = setTimeout(() => {
this.fanOutTimer = null
// What changed reaches every member, not just the recently-contacted ones.
this.lastSynced.clear()
void this.syncAll().catch(() => { /* next round */ })
}, delayMs)
this.fanOutTimer.unref?.()
}
private selfPub(): string { return this.deps.self().pub }
/** Whether the account's machine list says [machineId] is one of the person's own machines. */
private ordinary(machineId: string): boolean {
return this.deps.machineKinds.teamFree?.() === true || this.deps.machineKinds.kind(machineId) === 'computer'
}
/**
* Why a `group_sync` from `peerPub` is refused, or null when it may go on. A machine is known by every machine id
* this one holds for its key (its pin, its roster entry, its pairing) and by the one it gives for itself, and each
* must be one of the person's own: a team machine cannot get in by describing itself as an app, or as another
* machine. A peer no record or word of its own makes a machine (a phone, a desktop app) is not a machine at all.
*/
private machinePeerRefusal(peerPub: string, claimedSelf: unknown): 'TEAM_MACHINE' | 'MACHINE_UNKNOWN' | null {
if (this.deps.machineKinds.teamFree?.() === true) return null
const ids = new Set<string>()
let machine = false
for (const p of this.deps.peers.list()) if (p.pub === peerPub) { ids.add(p.machineId); machine = true }
for (const m of this.deps.store.read().members) {
if (m.pub !== peerPub) continue
if (m.kind === 'machine') machine = true
if (m.machineId) ids.add(m.machineId)
}
for (const p of this.deps.paired()) {
if (p.identityPub !== peerPub) continue
if (p.kind === 'machine') machine = true
if (p.machineId) ids.add(p.machineId)
}
const self = claimedSelf && typeof claimedSelf === 'object' ? claimedSelf as Record<string, unknown> : null
if (self?.pub === peerPub) {
if (self.kind === 'machine') machine = true
if (typeof self.machineId === 'string' && self.machineId) ids.add(self.machineId)
}
if (ids.size === 0) return machine ? 'MACHINE_UNKNOWN' : null
const kinds = [...ids].map((id) => this.deps.machineKinds.kind(id))
if (kinds.includes('team')) return 'TEAM_MACHINE'
return kinds.every((kind) => kind === 'computer') ? null : 'MACHINE_UNKNOWN'
}
/** Links made before the group existed: every pinned machine and every paired peer that said what it is. */
private seedFromExistingLinks(): void {
const seed: GroupMember[] = []
for (const p of this.deps.peers.list()) {
if (p.shared) continue
const m = parseMember({ pub: p.pub, machineId: p.machineId, kind: 'machine', label: p.label, at: p.linkedAt || SELF_STAMP }, this.now())
if (m) seed.push(m)
}
for (const p of this.deps.paired()) {
if (!p.kind || p.shared) continue
const m = parseMember({ pub: p.identityPub, machineId: p.machineId, kind: p.kind, label: p.label, at: p.pairedAt || SELF_STAMP }, this.now())
if (m) seed.push(m)
}
if (seed.length) this.deps.store.merge({ members: seed, removed: [] }, this.selfPub())
}
private applyAll(): void {
const roster = this.deps.store.read()
this.apply({ roster, upserted: roster.members, dropped: [] })
}
private apply(result: MergeResult): void {
const selfMachine = this.deps.self().machineId
const blocked = this.deps.store.blocked()
const suspended = this.deps.suspended?.() ?? new Set<string>()
// A machine the backend said was deleted (remoteRelay.ts) stays in other members' rosters; pinning it again is what made
// the relay dial it for good. It is trusted as before: a deleted machine's identity is spent (gateway/start.ts).
const gone = this.deps.peers.gone()
for (const m of result.upserted) {
if (blocked.has(m.pub) || suspended.has(m.pub)) continue
try {
if (m.kind === 'machine' && m.machineId && m.machineId !== selfMachine && !gone.has(m.machineId)) {
const pin = this.deps.peers.get(m.machineId)
if (!pin || pin.pub !== m.pub) this.deps.peers.pin(m.machineId, m.pub, m.label, m.at)
}
this.deps.trust({ pub: m.pub, machineId: m.machineId, kind: m.kind, label: m.label })
} catch (err) {
this.deps.log?.(`[group] could not apply ${m.pub.slice(0, 8)}: ${err instanceof Error ? err.message : String(err)}`)
}
}
for (const m of result.dropped) {
this.forget(m.pub)
try { this.onDropped?.(m.pub) } catch { /* the removal here stands */ }
}
}
private forget(pub: string): void {
try {
for (const p of this.deps.peers.list()) {
if (p.pub !== pub) continue
this.deps.peers.unlink(p.machineId)
this.deps.dropSessions?.(p.machineId)
}
this.deps.untrust(pub)
} catch (err) {
this.deps.log?.(`[group] could not remove ${pub.slice(0, 8)}: ${err instanceof Error ? err.message : String(err)}`)
}
}
}
/** `GroupSyncerDeps.request` over a background relay session (its own pool — it never takes the
* window's sink): select the machine, send one sealed frame, wait for its `_result`, detach. */
export function relayRequester(
pool: { acquireIsolated: (machineId: string, autonomousEnv: string, selectFrame: Frame, sink: LocalClientSink, onClosed: (code: number, reason: string) => void) => Promise<RelaySession> },
autonomousEnv: () => string,
): GroupSyncerDeps['request'] {
return (machineId, frame, timeoutMs) => new Promise<Frame | null>((resolve) => {
const requestId = (frame.payload as Record<string, unknown> | undefined)?.requestId
let session: RelaySession | null = null
let done = false
const finish = (result: Frame | null): void => {
if (done) return
done = true
clearTimeout(timer)
session?.detach()
resolve(result)
}
const timer = setTimeout(() => finish(null), timeoutMs)
const sink: LocalClientSink = {
sendFrame: (f) => {
const p = (f.payload ?? {}) as Record<string, unknown>
if (f.type === `${frame.type}_result` && p.requestId === requestId) finish(f)
return true
},
sendBinary: () => true,
}
pool.acquireIsolated(machineId, autonomousEnv(), { type: 'machine_select', payload: { machineId } }, sink, () => finish(null))
.then((s) => {
session = s
if (done) { s.detach(); return }
return s.send(frame)
})
.catch(() => finish(null))
})
}