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
Team agents follow the owner's relay grant after a daemon restart (#3093)
harness-for-autonomous[bot]cf4bfc42673b
diff --git a/cli/src/superTabs/host.ts b/cli/src/superTabs/host.tsindex 65f4d6128..1e87e07c4 100644--- a/cli/src/superTabs/host.ts+++ b/cli/src/superTabs/host.ts@@ -22,7 +22,8 @@ import { prepareContribution, prepareTeamContribution } from './contribution.js'import { homedir, hostname } from 'node:os'import { recordsOtherFolder, scrubClaudeSession, type PurgeTarget, type ScrubTold } from './inCore/teamPurge.js'import { RebindSender, replacementObservations } from './replacements.js'-import { TerminalHost } from './terminal.js'+import { TerminalHost, type TerminalRelay } from './terminal.js'+import { realRelayRecovery } from './relayRecovery.js'import { LimitResume } from './limitResume.js'import { LeadSwitchRequests, type SwitchRow } from './leadSwitchRequest.js'import { BuddyModelRequests, type BuddyModelRow } from './buddyModel.js'@@ -175,6 +176,8 @@ interface HostAgent { tabId: string; agent: { id: string; harnessId: string; macleadsConversationId?: unknown; roleName?: unknown; instructions?: unknown }export interface SuperTabHostOptions {now?: () => number+ /** What restarts a Team agent stranded on an old relay grant (relayRecovery.ts), for a spec. */+ relayRecovery?: TerminalRelaywrite?: (file: string, journal: Journal) => voidlog?: (message: string) => voidobservers?: typeof publishObservers@@ -618,7 +621,9 @@ export class SuperTabHost {this.write = options.write ?? writeJournalthis.log = options.log ?? (message => console.warn(`[super-tabs] ${message}`))// Its pickups follow this host's delivery push lease: the server that pushes deliveries also says when a request waits.- this.terminal = new TerminalHost(core, machineId, { now: this.now, log: this.log, pushes: () => this.now() < this.pushUntil })+ this.terminal = new TerminalHost(core, machineId, { now: this.now, log: this.log, pushes: () => this.now() < this.pushUntil,+ // Only a Team daemon reads a relay grant: on any other the recovery sees no grant and does nothing.+ relay: options.relayRecovery ?? realRelayRecovery(core, machineId, { now: this.now, log: this.log }) })this.limitResume = new LimitResume(core, machineId, { now: this.now, log: this.log,owns: async (tabId, assignmentId, harnessId) => (await this.sources.feed.fresh()).assignments.some(a => a.tabId === tabId && a.assignmentId === assignmentId && a.harnessId === harnessId) })diff --git a/cli/src/superTabs/relayRecovery.spec.ts b/cli/src/superTabs/relayRecovery.spec.tsnew file mode 100644index 000000000..32a4e3c55--- /dev/null+++ b/cli/src/superTabs/relayRecovery.spec.ts@@ -0,0 +1,152 @@+/**+ * A Harness Team agent stranded on a relay grant its owner's daemon no longer answers (task #3106). On daniel-pc, 2026-11-05,+ * the CLI 0.5.43 update restarted the owner's daemon at 11:33, its relay came back at a new address and token, and every+ * Team agent already running failed each model request until someone restarted it. Agents started after 11:33 worked.+ */+import { createServer } from 'node:http'+import type { AddressInfo } from 'node:net'+import { describe, expect, it, onTestFinished, vi } from 'vitest'+import { startSubscriptionRelay } from '../lib/subscriptionRelay.js'+import type { TeamConfig } from '../team/config.js'+import { TEAM_RELAY_GUEST, teamRelayLaunch, type TeamRelayGrant } from '../team/relay.js'+import { RECOVER_AFTER_MS, RELAY_RESTORED, RelayRecovery, relayAnswers, type RelayRecoveryDeps } from './relayRecovery.js'++const OLD: TeamRelayGrant = { url: 'http://127.0.0.1:50001', token: 'old-token-aaaaaaaaaaaaaaaaaaaa' }+const NEW: TeamRelayGrant = { url: 'http://127.0.0.1:50002', token: 'new-token-bbbbbbbbbbbbbbbbbbbb' }++function setup(over: Partial<RelayRecoveryDeps> = {}) {+ let clock = 1_000_000+ let grant: TeamRelayGrant | null = NEW+ const deps = {+ grant: vi.fn(() => grant),+ answers: vi.fn(async (_g: TeamRelayGrant) => true),+ restart: vi.fn(async (_h: string) => ({ ok: true as const })),+ input: vi.fn(async (_h: string, _t: string) => ({ ok: true as const })),+ now: () => clock,+ log: vi.fn(),+ ...over,+ }+ const recovery = new RelayRecovery(deps)+ const failingFor = (ms: number) => ({ failingSince: clock - ms, waiting: false })+ const clear = { failingSince: null, waiting: false }+ return { deps, recovery, failingFor, clear, wait: (ms: number) => { clock += ms }, publish: (next: TeamRelayGrant | null) => { grant = next } }+}++describe('a Team agent whose model keeps failing on its owner\'s relay', () => {+ it('is restarted onto the current grant once its model has failed for a minute, and told to carry on once it is back', async () => {+ const t = setup()+ await t.recovery.seen('h1', 'claude', t.failingFor(RECOVER_AFTER_MS - 1))+ expect(t.deps.restart).not.toHaveBeenCalled()+ await t.recovery.seen('h1', 'claude', t.failingFor(RECOVER_AFTER_MS))+ expect(t.deps.answers).toHaveBeenCalledWith(NEW)+ expect(t.deps.restart).toHaveBeenCalledExactlyOnceWith('h1')+ // The relaunch is still coming up: nothing is typed on the read right after it.+ await t.recovery.seen('h1', 'claude', t.clear)+ expect(t.deps.input).not.toHaveBeenCalled()+ t.wait(15_000)+ await t.recovery.seen('h1', 'claude', t.clear)+ expect(t.deps.input).toHaveBeenCalledExactlyOnceWith('h1', RELAY_RESTORED)+ t.wait(15_000)+ await t.recovery.seen('h1', 'claude', t.clear)+ expect(t.deps.input).toHaveBeenCalledOnce()+ })++ it('is restarted at most once per grant: still failing on the same grant, it is left for its model alert', async () => {+ const t = setup()+ await t.recovery.seen('h1', 'claude', t.failingFor(RECOVER_AFTER_MS))+ for (let i = 0; i < 10; i++) { t.wait(15_000); await t.recovery.seen('h1', 'claude', t.failingFor(RECOVER_AFTER_MS + i * 15_000)) }+ expect(t.deps.restart).toHaveBeenCalledOnce()+ // Never told to carry on while its model still fails.+ expect(t.deps.input).not.toHaveBeenCalled()+ // A grant published since (the owner's daemon restarted again) is worth one more.+ t.publish(OLD)+ await t.recovery.seen('h1', 'claude', t.failingFor(RECOVER_AFTER_MS * 20))+ expect(t.deps.restart).toHaveBeenCalledTimes(2)+ })++ it('is not restarted when the current grant does not answer either: a relaunch would fail the same way', async () => {+ const t = setup({ answers: vi.fn(async () => false) })+ await t.recovery.seen('h1', 'claude', t.failingFor(RECOVER_AFTER_MS))+ expect(t.deps.restart).not.toHaveBeenCalled()+ // Asked again on a later read, once the relay may answer.+ t.wait(15_000)+ vi.mocked(t.deps.answers).mockResolvedValue(true)+ await t.recovery.seen('h1', 'claude', t.failingFor(RECOVER_AFTER_MS + 15_000))+ expect(t.deps.restart).toHaveBeenCalledOnce()+ })++ it('does nothing without a published grant (any daemon but a Team account\'s), or for an engine the relay does not serve', async () => {+ const t = setup()+ t.publish(null)+ await t.recovery.seen('h1', 'claude', t.failingFor(RECOVER_AFTER_MS))+ t.publish(NEW)+ await t.recovery.seen('h2', 'opencode', t.failingFor(RECOVER_AFTER_MS))+ await t.recovery.seen('h3', undefined, t.failingFor(RECOVER_AFTER_MS))+ expect(t.deps.answers).not.toHaveBeenCalled()+ expect(t.deps.restart).not.toHaveBeenCalled()+ })++ it('never types its continue into an open prompt: it waits for the prompt to go', async () => {+ const t = setup()+ await t.recovery.seen('h1', 'codex', t.failingFor(RECOVER_AFTER_MS))+ t.wait(15_000)+ await t.recovery.seen('h1', 'codex', { failingSince: null, waiting: true })+ expect(t.deps.input).not.toHaveBeenCalled()+ t.wait(15_000)+ await t.recovery.seen('h1', 'codex', t.clear)+ expect(t.deps.input).toHaveBeenCalledExactlyOnceWith('h1', RELAY_RESTORED)+ })++ it('tries a failed restart again only with a new grant, and says why it failed without the token', async () => {+ const t = setup({ restart: vi.fn(async () => ({ ok: false as const, error: 'RESTART_FAILED' })) })+ await t.recovery.seen('h1', 'claude', t.failingFor(RECOVER_AFTER_MS))+ t.wait(15_000)+ await t.recovery.seen('h1', 'claude', t.failingFor(RECOVER_AFTER_MS + 15_000))+ expect(t.deps.restart).toHaveBeenCalledOnce()+ expect(t.deps.input).not.toHaveBeenCalled()+ const logged = vi.mocked(t.deps.log).mock.calls.map(c => String(c[0])).join('\n')+ expect(logged).toContain('RESTART_FAILED')+ expect(logged).not.toContain(NEW.token)+ })++ it('forgets agents that are no longer here', async () => {+ const t = setup()+ await t.recovery.seen('h1', 'claude', t.failingFor(RECOVER_AFTER_MS))+ t.recovery.keep(new Set())+ t.wait(15_000)+ await t.recovery.seen('h1', 'claude', t.failingFor(RECOVER_AFTER_MS))+ expect(t.deps.restart).toHaveBeenCalledTimes(2)+ })+})++describe('the owner\'s real relay across a restart that moved it', () => {+ const config = { user: 'harnessteam', owner: 'owner', ownerHome: '/Users/owner' } as TeamConfig+ const owner = { read: async () => ({ provider: 'claude' as const, accessToken: 'owner-fixture', expiresAt: null, accountId: null }), refresh: async () => null }++ it('refuses the stranded grant, answers the current one, and a relaunch reads the current one', async () => {+ const upstream = createServer((req, res) => { res.writeHead(req.url === '/v1/models' ? 200 : 404); res.end('{"data":[]}') })+ await new Promise<void>(resolve => upstream.listen(0, '127.0.0.1', resolve))+ onTestFinished(() => { upstream.closeAllConnections(); upstream.close() })+ const claude = `http://127.0.0.1:${(upstream.address() as AddressInfo).port}`++ // Before the update: the agent launched with this grant.+ const before = await startSubscriptionRelay({ owner, upstream: { claude } })+ const stranded = { url: before.url, token: before.mintToken(TEAM_RELAY_GUEST) }+ expect(await relayAnswers(stranded)).toBe(true)+ await before.close()+ // After it: a new address and a new token (its kept port was not free in time).+ const after = await startSubscriptionRelay({ owner, upstream: { claude } })+ onTestFinished(() => after.close())+ const current = { url: after.url, token: after.mintToken(TEAM_RELAY_GUEST) }+ expect(current.url).not.toBe(stranded.url)+ expect(await relayAnswers(stranded)).toBe(false)+ // The old token at the new address is refused too.+ expect(await relayAnswers({ url: current.url, token: stranded.token })).toBe(false)+ expect(await relayAnswers(current)).toBe(true)++ // The restart relaunches through the same path as a first launch: it reads the grant published now.+ const relaunch = await teamRelayLaunch('claude', { team: () => true, config: () => config, signedIn: async () => false,+ read: () => current, onboarded: () => {}, codexHome: async () => null })+ expect(relaunch).toEqual({ env: { ANTHROPIC_BASE_URL: `${current.url}/claude`, ANTHROPIC_AUTH_TOKEN: current.token }, args: [] })+ })+})diff --git a/cli/src/superTabs/relayRecovery.ts b/cli/src/superTabs/relayRecovery.tsnew file mode 100644index 000000000..05c28cae0--- /dev/null+++ b/cli/src/superTabs/relayRecovery.ts@@ -0,0 +1,165 @@+/**+ * A Harness Team agent stranded on a relay grant its owner's daemon no longer answers is restarted onto the current one+ * (task #3106).+ *+ * A Team agent spends its owner's subscription through the owner's relay, with the address and token it was launched with+ * in its environment (team/relay.ts). The owner's daemon keeps that address across a restart when it can, and otherwise+ * moves to a new port and a new token (team/relay.ts `openRelay`), or mints a new token when the old one reaches its age.+ * Running agents cannot read the new grant: on daniel-pc, 2026-11-05, the CLI 0.5.43 update restarted the owner's daemon+ * at 11:33, and every Team agent already running there failed each model request until someone restarted it by hand,+ * while those started after 11:33 worked. Each loss cost a task and its restart.+ *+ * So the Team daemon's terminal watch (./terminal.ts), which reads each agent's screen anyway, tells this module what it+ * sees. Once an agent's model has failed for a minute, and the relay answers a model call with the grant published now, the+ * agent is restarted in its pane on the same session. Its relaunch reads the owner's relay again, as every launch does+ * (lib/launchOverrides.ts `ownerRelay`). A short continue is typed once it is back, as limit resume does (./limitResume.ts).+ * A grant that does not answer restarts nothing, since a relaunch would fail the same way. Each agent is restarted at most+ * once per grant, so an agent failing for any other reason is left to its model alert as before.+ *+ * ⚠️ The token is never logged: a grant is compared only by a digest, held in memory.+ */+import { createHash } from 'node:crypto'+import { openDaemon } from '../agentClient/daemon.js'+import type { CoreApi } from '../core/api.js'+import { readAuthSession } from '../lib/authSession.js'+import { readTeamConfig } from '../team/config.js'+import { readTeamRelay, type TeamRelayGrant } from '../team/relay.js'++/** How long an agent's model fails before its grant is looked at. Claude Code retries a refused connection for minutes+ * before it gives up a turn, and a busy model's retries mostly clear sooner than this. */+export const RECOVER_AFTER_MS = 60_000+/** When the continue is first tried after a restart: the next screen read, once the relaunched engine is up. */+const CONTINUE_AFTER_MS = 15_000+/** A prompt open at that time is waited out this long between tries. */+const CONTINUE_RETRY_MS = 15_000+/** A restarted agent whose model still fails is not told to carry on: after this long the continue owed to it is dropped. */+const CONTINUE_GIVE_UP_MS = 10 * 60_000+/** How long a probe of the relay may take. */+const PROBE_TIMEOUT_MS = 10_000++/** Said to a restarted agent, whose last turn failed: the task is still its own. */+export const RELAY_RESTORED = 'continue: your connection to the model is back, so carry on with your task from where it stopped'++/** The engines the owner's relay serves (team/relay.ts `teamRelayLaunch`). */+const RELAYED_ENGINES: ReadonlySet<string> = new Set(['claude', 'codex'])++export interface RelayRecoveryDeps {+ /** The grant the owner's daemon publishes for this Team account now; null on any other daemon, or with none published. */+ grant(): TeamRelayGrant | null+ /** Whether the relay answers a model call with [grant]. */+ answers(grant: TeamRelayGrant): Promise<boolean>+ /** Relaunches the agent in its own pane, on the same session (`agent_restart`). */+ restart(harnessId: string): Promise<{ ok: true } | { ok: false; error: string }>+ /** Types [text] and Enter into the agent's terminal. */+ input(harnessId: string, text: string): Promise<{ ok: true } | { ok: false; error: string }>+ now(): number+ log(line: string): void+}++/** One screen read of a running agent: when its model began failing, if it is failing now, and whether a prompt is open. */+export interface RelaySeen { failingSince: number | null; waiting: boolean }++const digestOf = (grant: TeamRelayGrant) => createHash('sha256').update(`${grant.url}\0${grant.token}`).digest('base64url')++/**+ * Whether the relay at [grant] answers a model call with its token: a GET of Claude's model list, which spends nothing.+ * The relay forwards it with the owner's sign-in, so a relay that is gone, a token it refuses and an owner it cannot sign in+ * all read as not answering.+ */+export async function relayAnswers(grant: TeamRelayGrant, fetchImpl: typeof fetch = fetch): Promise<boolean> {+ try {+ const answer = await fetchImpl(`${grant.url.replace(/\/$/, '')}/claude/v1/models`, {+ headers: { authorization: `Bearer ${grant.token}`, 'anthropic-version': '2023-06-01', accept: 'application/json' },+ signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),+ })+ await answer.body?.cancel().catch(() => {})+ return answer.ok+ } catch {+ return false+ }+}++export class RelayRecovery {+ /** Per agent, the digest of the grant it was last restarted for. */+ private readonly restartedFor = new Map<string, string>()+ /** Per restarted agent, the continue owed to it: when to try it next, and when it was restarted. */+ private readonly owed = new Map<string, { at: number; restartedAt: number }>()+ private readonly busy = new Set<string>()++ constructor(private readonly deps: RelayRecoveryDeps) {}++ /** Only these agents are still here: what is kept for the others goes. */+ keep(harnessIds: ReadonlySet<string>): void {+ for (const map of [this.restartedFor, this.owed]) for (const id of map.keys()) if (!harnessIds.has(id)) map.delete(id)+ }++ /** One screen read of a running agent of [engine]. */+ async seen(harnessId: string, engine: string | undefined, read: RelaySeen): Promise<void> {+ if (this.busy.has(harnessId)) return+ this.busy.add(harnessId)+ try { await this.decide(harnessId, engine, read) } finally { this.busy.delete(harnessId) }+ }++ private async decide(harnessId: string, engine: string | undefined, read: RelaySeen): Promise<void> {+ const now = this.deps.now()+ const owed = this.owed.get(harnessId)+ if (owed) {+ if (now < owed.at) return+ if (read.failingSince === null) {+ // Enter on a permission prompt, a question or a menu would answer it.+ if (read.waiting) { owed.at = now + CONTINUE_RETRY_MS; return }+ this.owed.delete(harnessId)+ const typed = await this.deps.input(harnessId, RELAY_RESTORED).catch((error: unknown) => ({ ok: false as const, error: String(error) }))+ if (!typed.ok) this.deps.log(`could not tell ${harnessId} to carry on after its restart: ${typed.error}`)+ return+ }+ // Still failing after its restart: never told to carry on. On the same grant it is left to its model alert below; a+ // grant published since is worth one more restart.+ if (now - owed.restartedAt >= CONTINUE_GIVE_UP_MS) this.owed.delete(harnessId)+ }+ if (read.failingSince === null || now - read.failingSince < RECOVER_AFTER_MS) return+ if (!engine || !RELAYED_ENGINES.has(engine)) return+ const grant = this.deps.grant()+ if (!grant) return+ const digest = digestOf(grant)+ if (this.restartedFor.get(harnessId) === digest) return+ if (!await this.deps.answers(grant).catch(() => false)) return+ this.restartedFor.set(harnessId, digest)+ const restarted = await this.deps.restart(harnessId).catch((error: unknown) => ({ ok: false as const, error: String(error) }))+ if (!restarted.ok) {+ this.deps.log(`could not restart ${harnessId} onto its owner's current relay: ${restarted.error}`)+ return+ }+ this.deps.log(`restarted ${harnessId} onto its owner's current relay: its model had failed for ${Math.round((now - read.failingSince) / 1000)} s`)+ this.owed.set(harnessId, { at: now + CONTINUE_AFTER_MS, restartedAt: now })+ }+}++/** How long a restart may take: the relaunch waits on the engine's command and its pane. */+const RESTART_TIMEOUT_MS = 60_000++/**+ * This machine's: the grant only in the Harness Team account, read as each launch reads it (team/relay.ts+ * `realTeamRelayLaunch`); the restart through this machine's own daemon socket, as the apps ask it (`agent_restart`); the+ * continue through the core's own terminal input.+ */+export function realRelayRecovery(core: CoreApi, machineId: string, options: { now: () => number; log: (line: string) => void }): RelayRecovery {+ return new RelayRecovery({+ grant: () => {+ if (readAuthSession()?.kind !== 'team') return null+ const config = readTeamConfig()+ return config ? readTeamRelay(config) : null+ },+ answers: grant => relayAnswers(grant),+ restart: async harnessId => {+ const local = await openDaemon({ dataDir: core.dataDir, port: core.daemon.port, machineId })+ try {+ const answer = await local.request('agent_restart', { agentId: harnessId }, RESTART_TIMEOUT_MS)+ return typeof answer.error === 'string' ? { ok: false, error: answer.error } : { ok: true }+ } finally { local.close() }+ },+ input: (harnessId, text) => core.superTabs ? core.superTabs.input(harnessId, text, ['Enter']) : Promise.resolve({ ok: false, error: 'no terminal input here' }),+ now: options.now,+ log: line => options.log(`relay recovery: ${line}`),+ })+}diff --git a/cli/src/superTabs/terminal.spec.ts b/cli/src/superTabs/terminal.spec.tsindex 8adead8e1..e668c2baf 100644--- a/cli/src/superTabs/terminal.spec.ts+++ b/cli/src/superTabs/terminal.spec.ts@@ -3,13 +3,15 @@ import { describe, expect, it, vi } from 'vitest'import type { CoreApi, SuperTabScreen } from '../core/api.js'import { fakeCore } from '../testing/fakeCore.js'import { CODEX_MODEL_MIGRATION, CODEX_SIGN_IN, CODEX_TRUST_PROMPT, CODEX_UPDATE_PROMPT } from '../lib/__fixtures__/takeoverScreens.js'+import type { RelaySeen } from './relayRecovery.js'import { capScreen, limitOf, modelFailing, TerminalHost, typedKeys } from './terminal.js'const row = (agentId = 'a1', harnessId = 'h1', over: Record<string, unknown> = {}) => ({ tabId: 'tab', agent: { id: agentId, harnessId, machineId: 'm1' }, ...over })type Sent = { path: string; body: Record<string, any> }function setup(options: { live?: string[]; screen?: (harnessId: string) => SuperTabScreen; requests?: unknown[];- refuse?: (command: Record<string, any>) => { status: number; code: string } | null } = {}) {+ refuse?: (command: Record<string, any>) => { status: number; code: string } | null; engine?: string;+ relay?: { seen: (harnessId: string, engine: string | undefined, read: RelaySeen) => Promise<void>; keep: (ids: ReadonlySet<string>) => void } } = {}) {let clock = 1_000_000const sent: Sent[] = []let pending = options.requests ?? []@@ -23,11 +25,11 @@ function setup(options: { live?: string[]; screen?: (harnessId: string) => Superlet screen = options.screen ?? (() => ({ ok: true as const, text: '> ', hold: null }))const core = fakeCore({account: { backend },- agents: { byAgent: vi.fn((id: string) => (options.live ?? ['h1']).includes(id) ? { agentId: id } as never : undefined) },+ agents: { byAgent: vi.fn((id: string) => (options.live ?? ['h1']).includes(id) ? { agentId: id, engine: options.engine ?? 'claude' } as never : undefined) },superTabs: { attention: vi.fn(), cards: vi.fn(), cardRecap: vi.fn(), shareObservers: vi.fn(),screen: vi.fn(async (harnessId: string) => screen(harnessId)), input: vi.fn(async () => ({ ok: true as const })), inputIfScreen: vi.fn(async () => ({ ok: true as const })) },})- const host = new TerminalHost(core, 'm1', { now: () => clock, log: vi.fn() })+ const host = new TerminalHost(core, 'm1', { now: () => clock, log: vi.fn(), ...(options.relay ? { relay: options.relay } : {}) })return { core, backend, sent, host,now: () => clock,wait: (ms: number) => { clock += ms },@@ -320,6 +322,31 @@ describe('the stuck and usage-limit alerts', () => {})})+describe('a Team agent stranded on its owner\'s relay (task #3106)', () => {+ const failing = (): SuperTabScreen => ({ ok: true, text: '⎿ Unable to connect to API (ECONNREFUSED) · Retrying in 8 seconds… (attempt 4/10)\n❯ ', hold: null })+ const prompt = (): SuperTabScreen => ({ ok: true, text: 'Allow edit? 1. Yes 2. No', hold: 'permission_open' })++ it('tells the relay recovery on every read when the agent\'s model began failing, its engine, and whether a prompt is open', async () => {+ const relay = { seen: vi.fn(async () => {}), keep: vi.fn() }+ const t = setup({ screen: failing, relay, engine: 'codex' })+ const began = t.now()+ await t.host.tick([row()])+ t.wait(60_000); await t.host.tick([row()])+ expect(relay.seen.mock.calls).toEqual([['h1', 'codex', { failingSince: began, waiting: false }], ['h1', 'codex', { failingSince: began, waiting: false }]])+ // Answers came again: not failing now, though the model alert's episode lasts ten more minutes.+ t.showing(prompt); t.wait(15_000); await t.host.tick([row()])+ expect(relay.seen.mock.calls[2]).toEqual(['h1', 'codex', { failingSince: null, waiting: true }])+ expect(relay.keep).toHaveBeenLastCalledWith(new Set(['h1']))+ })++ it('reads nothing for the recovery from a screen it could not read', async () => {+ const relay = { seen: vi.fn(async () => {}), keep: vi.fn() }+ const t = setup({ screen: () => ({ ok: false, error: 'gone' }), relay })+ await t.host.tick([row()])+ expect(relay.seen).not.toHaveBeenCalled()+ })+})+describe('dismissing Codex\'s update screen for a Swarm agent', () => {const update = (): SuperTabScreen => ({ ok: true, text: CODEX_UPDATE_PROMPT, hold: 'update_prompt_open' })const idle = (): SuperTabScreen => ({ ok: true, text: '> ', hold: null })diff --git a/cli/src/superTabs/terminal.ts b/cli/src/superTabs/terminal.tsindex 638030790..2423913a1 100644--- a/cli/src/superTabs/terminal.ts+++ b/cli/src/superTabs/terminal.ts@@ -14,6 +14,7 @@ import { updateDismissKeys } from '../engines/codex/screen.js'import { feedbackDismissKeys } from '../engines/claude/screen.js'import type { MessageHold } from '../engines/facets/screen.js'import { backend } from './host.js'+import type { RelaySeen } from './relayRecovery.js'import { identifier, object } from './wire.js'type Json = Record<string, unknown>@@ -164,6 +165,11 @@ function screenDigest(text: string): string {}type Episode = { since: number; alerted: boolean } | null+/** What the watch tells of each read (./relayRecovery.ts `RelayRecovery`). */+export interface TerminalRelay {+ seen(harnessId: string, engine: string | undefined, read: RelaySeen): Promise<void>+ keep(harnessIds: ReadonlySet<string>): void+}interface Watched { prompt: Episode; limit: Episode; model: Episode; retried?: number; skips?: number }export class TerminalHost {@@ -185,12 +191,15 @@ export class TerminalHost {private readonly log: (message: string) => void/** Whether the server is known to push now (the host's delivery push lease). */private readonly pushes: () => boolean+ /** On a Team daemon, what restarts an agent stranded on an old relay grant (./relayRecovery.ts). */+ private readonly relay: TerminalRelay | nullconstructor(private readonly core: CoreApi, private readonly machineId: string,- options: { now?: () => number; log?: (message: string) => void; pushes?: () => boolean } = {}) {+ options: { now?: () => number; log?: (message: string) => void; pushes?: () => boolean; relay?: TerminalRelay } = {}) {this.now = options.now ?? Date.nowthis.log = options.log ?? (message => console.warn(`[super-tabs] ${message}`))this.pushes = options.pushes ?? (() => false)+ this.relay = options.relay ?? null}/** Each host roster read. Serving and watching run on their own cadence, and the returned promise is only for specs:@@ -294,6 +303,7 @@ export class TerminalHost {this.alertRetries.keepIf(key => agents.has(key.split('-')[2] ?? ''))const harnesses = new Set(own.map(a => a.harnessId))for (const id of this.progress.keys()) if (!harnesses.has(id)) this.progress.delete(id)+ this.relay?.keep(harnesses)for (const agent of own) {const key = `${agent.tabId}:${agent.agentId}`const state = this.watched.get(key) ?? { prompt: null, limit: null, model: null }@@ -314,6 +324,11 @@ export class TerminalHost {// Ten minutes up to the last retry seen, not up to now: the quiet minutes that confirm answers came again are not// failure, so a burst that recovers before ten minutes never alerts (and its task is never lost for it).state.model = await this.episode(agent, 'model', state.model, retrying, now, since => state.retried! - since >= MODEL_WAIT_MS, {})+ // Failing now, on this read: the model alert's episode outlasts the retries by ten minutes, a restart's by as long. Not+ // waited on: a restart takes up to a minute, and the other agents' reads and alerts must not wait behind it.+ void this.relay?.seen(agent.harnessId, this.core.agents.byAgent(agent.harnessId)?.engine,+ { failingSince: modelFailing(read.text) && state.model ? state.model.since : null, waiting: read.hold !== null && WAITING.has(read.hold) })+ .catch(error => this.log(`relay recovery: ${error instanceof Error ? error.message : String(error)}`))}}diff --git a/docs/plans/2026-11-05-team-relay-stranded-plan.md b/docs/plans/2026-11-05-team-relay-stranded-plan.mdnew file mode 100644index 000000000..0563a7866--- /dev/null+++ b/docs/plans/2026-11-05-team-relay-stranded-plan.md@@ -0,0 +1,48 @@+# Team agents follow the owner's relay grant: plan++> Way of working: test-driven, one Engineer, by the project instructions (Engineer role). No Execution Handoff.++**Goal:** a Harness Team agent that was running when its owner's daemon restarted, and holds a relay address or token+that the relay no longer answers, gets the current grant without anyone restarting it by hand (task #3106).++**Architecture:** the Team daemon's terminal watch (`cli/src/superTabs/terminal.ts`) already reads each agent's screen+every 15 s and knows when its model is failing. A new `RelayRecovery` (`cli/src/superTabs/relayRecovery.ts`) is+consulted on each read. Once an agent's model has failed for a minute, it reads the grant published now. If the relay+answers a model call with that grant (a GET of the model list, which spends nothing), the agent is restarted in its+pane with the same session (`agent_restart`). Its relaunch reads the owner's relay again+(`lib/launchOverrides.ts` `ownerRelay`), so it comes back on the current address and token. A short continue is+then typed, as limit resume does. Each agent is restarted at most once per grant. If the grant does not answer,+nothing is restarted: a relaunch would not help.++**Tech stack:** TypeScript, vitest.++**Spec:** task #3106. Evidence: on daniel-pc, Team agents started after the 11:33 update work, and the ones running+through it lost Claude.++## Global constraints++- Swarm code stays out of `cli/src/core`. The token is never logged; a grant is compared only by a digest held in+ memory.+- Team daemon only. On any other daemon `grant()` is null and nothing changes.+- No new credential path. The relay, its tokens and what the Team account reads are as before. The probe uses the+ grant the Team account already reads at every launch.++## Review focus++- That a restart cannot loop: one per agent per grant digest.+- That nothing is restarted when the current grant does not answer (relay down, token refused, owner not signed in).+- That the continue is never typed into an open prompt.++## Tasks++### Task 1: a stranded agent is restarted once onto the current grant++Files: `cli/src/superTabs/relayRecovery.ts`, `cli/src/superTabs/relayRecovery.spec.ts`, `cli/src/superTabs/terminal.ts`,+`cli/src/superTabs/host.ts`.++- [ ] Failing spec: an agent whose model has failed for a minute, with a grant that answers, is restarted once and then+ gets a continue. The same grant never restarts it again. A grant that does not answer restarts nothing. A new grant+ allows one more restart.+- [ ] Failing spec on the real relay (`startSubscriptionRelay`): the old address is refused, the current grant answers+ the probe, and the restarted launch's environment names the current address and token.+- [ ] Implement `RelayRecovery` and wire it into `TerminalHost.watch` and the host's real dependencies.