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.

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.ts
index 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; mac
leadsConversationId?: 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?: TerminalRelay
write?: (file: string, journal: Journal) => void
log?: (message: string) => void
observers?: typeof publishObservers
@@ -618,7 +621,9 @@ export class SuperTabHost {
this.write = options.write ?? writeJournal
this.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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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_000
const sent: Sent[] = []
let pending = options.requests ?? []
@@ -23,11 +25,11 @@ function setup(options: { live?: string[]; screen?: (harnessId: string) => Super
let 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.ts
index 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 | null
constructor(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.now
this.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.md
new file mode 100644
index 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.