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.

Merge batch 11-05 i2345: #3172 (#3197)

0xken15918ddc675afc
diff --git a/cli/src/lib/launchOverrides.spec.ts b/cli/src/lib/launchOverrides.spec.ts
index 935ef9484..c4d23cb2c 100644
--- a/cli/src/lib/launchOverrides.spec.ts
+++ b/cli/src/lib/launchOverrides.spec.ts
@@ -17,6 +17,8 @@ import { prepareSwarmSkill } from './swarmSkills.js'
import { swarmEngineArgs } from './swarmEngineArgs.js'
import { swarmGitHubLaunch } from './swarmGitHub.js'
import { writeMachineMcp } from './machineMcp.js'
+import { NO_CLAUDE_RELAY, NO_CODEX_RELAY, teamRelayLaunch, type TeamRelayGrant } from '../team/relay.js'
+import type { TeamConfig } from '../team/config.js'
const GRID: GridLaunchOverride = {
networkId: 'grid-abc',
@@ -242,6 +244,35 @@ describe('buildLaunchOverrides — a relaunch comes back where the agent was', (
expect(ownerRelay).not.toHaveBeenCalled()
})
+ // Task #3301: a CLI release restarts the owner's daemon, which publishes a new grant a little later, and the Team daemon,
+ // which restores its agents meanwhile. A Claude restored in that gap started with no credentials and sat signed out.
+ it('in the Harness Team account, holds a Claude or Codex relaunch across the owner\'s daemon restart and launches it on the new grant', async () => {
+ const config = { user: 'harnessteam', owner: 'owner', ownerHome: '/Users/owner' } as TeamConfig
+ const before: TeamRelayGrant = { url: 'http://127.0.0.1:41001', token: 'b'.repeat(43) }
+ const after: TeamRelayGrant = { url: 'http://127.0.0.1:41002', token: 'c'.repeat(43) }
+ let published: TeamRelayGrant | null = before
+ const ownerRelay = (engine: Parameters<typeof teamRelayLaunch>[0], home?: string) => teamRelayLaunch(engine, {
+ team: () => true, config: () => config, signedIn: async () => false, read: () => published, onboarded: () => {}, codexHome: async () => {},
+ }, home)
+ const relaunch = () => buildLaunchOverrides(deps({ ownerRelay }).d, 'claude', {}, 'agent-1')
+ // Mid-session, on the grant it was launched with.
+ expect(await relaunch()).toMatchObject({ ok: true, overrides: { env: { ANTHROPIC_BASE_URL: `${before.url}/claude`, ANTHROPIC_AUTH_TOKEN: before.token } } })
+ // The owner's daemon restarts: its grant is gone until it publishes again. The Team daemon's restore is held, with why.
+ published = null
+ expect(await relaunch()).toEqual({ ok: false, error: 'OWNER_RELAY_UNAVAILABLE', unavailable: 'native', detail: NO_CLAUDE_RELAY })
+ // Published again on a new port and token: the held pass (core/agents/heldLaunches.ts) launches it on that one.
+ published = after
+ const resumed = await relaunch()
+ expect(resumed).toMatchObject({ ok: true, overrides: { env: { ANTHROPIC_BASE_URL: `${after.url}/claude`, ANTHROPIC_AUTH_TOKEN: after.token } } })
+ expect(JSON.stringify(resumed)).not.toContain(before.token)
+ // A Team Codex in the daemon's own home (a Builder's) is held the same way, and comes back on the relay's provider.
+ published = null
+ const codex = () => buildLaunchOverrides(deps({ ownerRelay }).d, 'codex', {}, 'agent-2')
+ expect(await codex()).toEqual({ ok: false, error: 'OWNER_RELAY_UNAVAILABLE', unavailable: 'native', detail: NO_CODEX_RELAY })
+ published = after
+ expect(await codex()).toMatchObject({ ok: true, overrides: { env: { HARNESS_RELAY_TOKEN: after.token }, extraArgs: expect.arrayContaining(['model_provider="harness_owner"']) } })
+ })
+
it('builds OpenCode overrides without optional code and uses the requested engine facts', async () => {
vi.mocked(loadEngine).mockImplementation(() => new Promise(() => {}))
expect(await buildLaunchOverrides(deps().d, 'opencode', {}, 'agent-1')).toMatchObject({ ok: true })
diff --git a/cli/src/superTabs/relayRecovery.ts b/cli/src/superTabs/relayRecovery.ts
index 05c28cae0..303efe98f 100644
--- a/cli/src/superTabs/relayRecovery.ts
+++ b/cli/src/superTabs/relayRecovery.ts
@@ -16,6 +16,10 @@
* 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.
*
+ * A signed-out screen counts as a failing model too (./terminal.ts `signedOut`: Claude Code's "Not logged in · Please run
+ * /login" or "API Error: 401", task #3301): a Team agent launched while its owner's grant could not be read, or holding a
+ * token the relay no longer takes, is relaunched the same way once a grant reads and answers.
+ *
* ⚠️ The token is never logged: a grant is compared only by a digest, held in memory.
*/
import { createHash } from 'node:crypto'
diff --git a/cli/src/superTabs/terminal.spec.ts b/cli/src/superTabs/terminal.spec.ts
index e668c2baf..a833a619a 100644
--- a/cli/src/superTabs/terminal.spec.ts
+++ b/cli/src/superTabs/terminal.spec.ts
@@ -3,8 +3,8 @@ 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'
+import { RECOVER_AFTER_MS, RELAY_RESTORED, RelayRecovery, type RelaySeen } from './relayRecovery.js'
+import { capScreen, limitOf, modelFailing, signedOut, 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> }
@@ -347,6 +347,67 @@ describe('a Team agent stranded on its owner\'s relay (task #3106)', () => {
})
})
+// Task #3301: a CLI release restarted the owner's daemon and its relay, and Team Claude agents launched in the gap, or still
+// holding a token the relay no longer took, showed Claude Code's signed-out notice and sat there until a person came (Quince,
+// 2026-11-05: "Not logged in · Please run /login"). The watch knew only a relay that does not answer at all.
+describe('a Team agent signed out of its owner\'s relay (task #3301)', () => {
+ const GRANT = { url: 'http://127.0.0.1:41002', token: 'c'.repeat(43) }
+ const NOT_LOGGED_IN = '⏺ I will run the tests.\n\n ⎿ Not logged in · Please run /login\n\n❯ \n ? for shortcuts'
+ const UNAUTHORIZED = '⏺ Reading the brief.\n ⎿ API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"Invalid bearer token"}} · Please run /login\n❯ '
+ const BACK = '⏺ Carrying on with the task.\n❯ '
+
+ function recovering(screen: string, over: { grant?: () => typeof GRANT | null } = {}) {
+ let text = screen
+ const restart = vi.fn(async (_h: string) => { text = BACK; return { ok: true as const } })
+ let t!: ReturnType<typeof setup>
+ const recovery = new RelayRecovery({ grant: over.grant ?? (() => GRANT), answers: async () => true, restart,
+ input: (h, typed) => t.core.superTabs!.input(h, typed, ['Enter']), now: () => t.now(), log: vi.fn() })
+ t = setup({ screen: () => ({ ok: true, text, hold: null }), relay: recovery })
+ return { t, restart }
+ }
+ // The relay recovery is not awaited by the watch (a restart takes up to a minute): let it settle.
+ const settle = () => new Promise(resolve => setTimeout(resolve, 0))
+
+ for (const [name, screen] of [['Not logged in', NOT_LOGGED_IN], ['API Error: 401', UNAUTHORIZED]] as const) {
+ it(`relaunches an agent showing "${name}" onto the current grant, then tells it to carry on`, async () => {
+ // The Team daemon restarted mid-session too: a new watch and recovery, which never restarted this agent.
+ const { t, restart } = recovering(screen)
+ await t.host.tick([row()]); await settle()
+ expect(restart).not.toHaveBeenCalled()
+ t.wait(RECOVER_AFTER_MS); await t.host.tick([row()]); await settle()
+ expect(restart).toHaveBeenCalledExactlyOnceWith('h1')
+ t.wait(15_000); await t.host.tick([row()]); await settle()
+ expect(t.core.superTabs!.input).toHaveBeenCalledExactlyOnceWith('h1', RELAY_RESTORED, ['Enter'])
+ })
+ }
+
+ it('relaunches nothing while no grant reads: the held relaunch waits for it (team/relay.ts NO_CLAUDE_RELAY)', async () => {
+ const { t, restart } = recovering(NOT_LOGGED_IN, { grant: () => null })
+ await t.host.tick([row()]); t.wait(RECOVER_AFTER_MS); await t.host.tick([row()]); await settle()
+ expect(restart).not.toHaveBeenCalled()
+ })
+
+ it('knows Claude Code\'s and Codex\'s own signed-out notices near the prompt', () => {
+ for (const line of [' ⎿ Not logged in · Please run /login', '⎿ API Error: 401 {"type":"error","error":{"type":"authentication_error"}} · Please run /login',
+ ' ⎿ Invalid API key · Please run /login', ' ⎿ OAuth token has expired · Please run /login', '■ unexpected status 401 Unauthorized: Missing bearer authentication']) {
+ expect(signedOut(`⏺ work\n\n${line}\n❯ `), line).toBe(true)
+ }
+ expect(modelFailing(NOT_LOGGED_IN)).toBe(false)
+ })
+
+ it('never reads the agent\'s own words, a tool\'s output or an old notice far up the screen as signed out', () => {
+ // An agent working on this very bug writes and prints these lines: restarting it would cost its turn.
+ expect(signedOut('⏺ Quince showed "Not logged in · Please run /login" after the update.\n❯ ')).toBe(false)
+ expect(signedOut(' The brief says API Error: 401 is not recovered.\n❯ ')).toBe(false)
+ expect(signedOut('⏺ Bash(echo "Not logged in · Please run /login")\n ⎿ Not logged in · Please run /login\n❯ ')).toBe(false)
+ expect(signedOut(` ⎿ Not logged in · Please run /login\n${'line\n'.repeat(30)}❯ `)).toBe(false)
+ // A reply that starts with the phrase is still the agent's own words, Claude Code's "⏺" or Codex's "•" (security review 2).
+ expect(signedOut('⏺ Not logged in users are sent to /login, so the relay never sees them.\n❯ ')).toBe(false)
+ expect(signedOut('⏺ API Error: 401 comes from the relay when its token is stale.\n❯ ')).toBe(false)
+ expect(signedOut('• Invalid API key is what Codex prints for a stale relay token.\n› ')).toBe(false)
+ })
+})
+
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 2423913a1..1366a75c8 100644
--- a/cli/src/superTabs/terminal.ts
+++ b/cli/src/superTabs/terminal.ts
@@ -95,6 +95,25 @@ export function modelFailing(text: string): boolean {
return text.split('\n').slice(-LIMIT_NEAR_LINES).some(line => MODEL_LINE.test(line))
}
+/** An engine whose model refuses its sign-in: Claude Code's "Not logged in · Please run /login", "API Error: 401 {…
+ * authentication_error …} · Please run /login", "Invalid API key · Please run /login" and "OAuth token has expired", and
+ * Codex's "■ unexpected status 401 Unauthorized". A CLI release restarts the owner's daemon and its relay: a Team agent
+ * launched in that gap, or holding a token the relay no longer takes, showed one and sat there (task #3301, Quince,
+ * 2026-11-05). Only a line that starts with the notice, bare or under the engines' own marks (Claude Code's "⎿", Codex's
+ * "■"), where the engine draws its own ([ownNotice]), and near the prompt: an agent writing or printing these words, its
+ * reply under "⏺" or "•" included, is not signed out (security review 2 of #3172). */
+const SIGNED_OUT_LINE = /^\s*(?:⎿\s+|■\s+)?(?:api error:\s*401\b|not logged in\b|invalid api key\b|oauth token has (?:expired|been revoked)|unexpected status 401\b)/i
+
+/** Whether the screen shows its engine signed out of its model: no answer will come until it is launched signed in. */
+export function signedOut(text: string): boolean {
+ const lines = text.split('\n')
+ const from = Math.max(0, lines.length - LIMIT_NEAR_LINES)
+ return lines.slice(from).some((line, i) => SIGNED_OUT_LINE.test(line) && ownNotice(lines, from + i))
+}
+
+/** A model the agent gets no answer from: retrying one that does not answer, or signed out of it. */
+const unanswered = (text: string) => modelFailing(text) || signedOut(text)
+
/** Claude Code's tool call, whose output it draws under it: "⏺ Bash(…)", "⏺ Read(…)", "⏺ mcp__github__get_pr(…)". */
const TOOL_CALL = /^⏺\s+[\w.-]+\(/
@@ -314,12 +333,13 @@ export class TerminalHost {
state.skips = await this.skipUpdate(agent, read, state.skips ?? 0)
const now = this.now()
const digest = screenDigest(read.text), seen = this.progress.get(agent.harnessId)
+ const failing = unanswered(read.text)
// A model being retried is not the agent's work moving, whatever else the screen shows meanwhile.
- if (!seen || (seen.digest !== digest && !modelFailing(read.text))) this.progress.set(agent.harnessId, { digest, at: now })
+ if (!seen || (seen.digest !== digest && !failing)) this.progress.set(agent.harnessId, { digest, at: now })
state.prompt = await this.episode(agent, 'prompt', state.prompt, read.hold !== null && WAITING.has(read.hold), now, since => now - since >= PROMPT_WAIT_MS, {})
const limit = limitOf(read.text, now)
state.limit = await this.episode(agent, 'limit', state.limit, limit !== null, now, () => true, limit ?? {})
- if (modelFailing(read.text)) state.retried = now
+ if (failing) state.retried = now
const retrying = state.retried !== undefined && now - state.retried < MODEL_CLEAR_MS
// 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).
@@ -327,7 +347,7 @@ export class TerminalHost {
// 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) })
+ { failingSince: failing && 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/cli/src/team/relay.spec.ts b/cli/src/team/relay.spec.ts
index 56330ecfd..493a120a2 100644
--- a/cli/src/team/relay.spec.ts
+++ b/cli/src/team/relay.spec.ts
@@ -9,7 +9,7 @@ import { engineAccount } from '../lib/engineAccount.js'
import type { TeamConfig } from './config.js'
import {
publishTeamRelay, publishWindowsTeamRelay, readRememberedGrant, readTeamRelay, writeRememberedGrant, readWindowsTeamRelay, setfaclGrant, TEAM_RELAY_GUEST, teamRelayDir, teamRelayFile,
- teamRelayLaunch, teamRelayPublished, NO_PM_RELAY, type OwnerRelayLaunch, TeamRelayPublisher, prepareCodexHome, installedCodexVersion,
+ teamRelayLaunch, teamRelayPublished, NO_PM_RELAY, NO_CLAUDE_RELAY, NO_CODEX_RELAY, type OwnerRelayLaunch, TeamRelayPublisher, prepareCodexHome, installedCodexVersion,
CODEX_CLIENT_VERSION_FALLBACK, settleCodexModel, offeredCodexModels, codexModelNotOffered,
type TeamRelayGrant, type TeamRelayLaunchDeps, type TeamRelayPublisherDeps, type TeamRelayReadDeps, type WindowsRelayFs,
} from './relay.js'
@@ -455,7 +455,6 @@ describe('a launch in the team account', () => {
// Signed in in that home, or not a Team daemon, or no home of its own: nothing to refuse.
expect(await teamRelayLaunch('codex', launchDeps({ read: () => null, signedIn: async () => true }), home)).toBeNull()
expect(await teamRelayLaunch('codex', launchDeps({ read: () => null, team: () => false }), home)).toBeNull()
- expect(await teamRelayLaunch('codex', launchDeps({ read: () => null }))).toBeNull()
})
it('readies a Product Manager\'s own Codex home with the owner\'s models, and leaves the daemon\'s alone', async () => {
@@ -473,7 +472,35 @@ describe('a launch in the team account', () => {
expect(await teamRelayLaunch('claude', launchDeps({ team: () => false }))).toBeNull()
expect(await teamRelayLaunch('claude', launchDeps({ config: () => null }))).toBeNull()
expect(await teamRelayLaunch('claude', launchDeps({ signedIn: async () => true }))).toBeNull()
- expect(await teamRelayLaunch('claude', launchDeps({ read: () => null }))).toBeNull()
+ expect(await teamRelayLaunch('claude', launchDeps({ signedIn: async () => true, read: () => null }))).toBeNull()
+ })
+
+ // Task #3301: each CLI release restarts the owner's daemon and its relay, and a Team Claude launched before the grant read
+ // again started with no credentials ("Not logged in · Please run /login", Quince, 2026-11-05). It is refused with why, as
+ // a Codex Product Manager's home is: a relaunch is held until the grant reads (lib/launchOverrides.ts), a new agent is
+ // refused (core/agents/create.ts), never started signed out.
+ it('refuses a Claude that neither the owner\'s relay nor a sign-in of its own can sign in', async () => {
+ expect(await teamRelayLaunch('claude', launchDeps({ read: () => null }))).toEqual({ refused: NO_CLAUDE_RELAY })
+ // A sign-in that cannot be read is no sign-in: with no grant either, nothing would sign it in.
+ expect(await teamRelayLaunch('claude', launchDeps({ read: () => null, signedIn: async () => { throw new Error('keychain') } }))).toEqual({ refused: NO_CLAUDE_RELAY })
+ expect(NO_CLAUDE_RELAY).toBe('Waiting for the owner\'s subscription relay on this machine: Claude Code cannot sign in here without it.')
+ // Its first-run screens are recorded only for a launch on the relay.
+ const deps = launchDeps({ read: () => null })
+ await teamRelayLaunch('claude', deps)
+ expect(deps.onboarded).not.toHaveBeenCalled()
+ })
+
+ // Task #3301, the same bug for a Team Codex in the daemon's own home (a Builder's): it started signed out too.
+ it('refuses a Codex in the team account\'s own home that neither the owner\'s relay nor its own sign-in can sign in', async () => {
+ const deps = launchDeps({ read: () => null })
+ expect(await teamRelayLaunch('codex', deps)).toEqual({ refused: NO_CODEX_RELAY })
+ expect(deps.codexHome).not.toHaveBeenCalled()
+ expect(await teamRelayLaunch('codex', launchDeps({ read: () => null, signedIn: async () => { throw new Error('keychain') } }))).toEqual({ refused: NO_CODEX_RELAY })
+ expect(NO_CODEX_RELAY).toBe('Waiting for the owner\'s subscription relay on this machine: Codex cannot sign in here without it.')
+ // Signed in itself, not a Team daemon, or no team config: launched as before.
+ expect(await teamRelayLaunch('codex', launchDeps({ read: () => null, signedIn: async () => true }))).toBeNull()
+ expect(await teamRelayLaunch('codex', launchDeps({ read: () => null, team: () => false }))).toBeNull()
+ expect(await teamRelayLaunch('codex', launchDeps({ config: () => null }))).toBeNull()
})
})
diff --git a/cli/src/team/relay.ts b/cli/src/team/relay.ts
index 45d70d3ce..3eb421be8 100644
--- a/cli/src/team/relay.ts
+++ b/cli/src/team/relay.ts
@@ -394,6 +394,12 @@ export interface OwnerRelayLaunch { env: Record<string, string>; args: string[]
* one. The launch refuses or holds with it, never starting signed out (security re-checks of #2089). */
export interface OwnerRelayRefusal { refused: string }
export const NO_PM_RELAY = 'The owner\'s subscription relay is not available on this machine, so a Codex Product Manager cannot sign in here.'
+/** Why a Team-account Claude that has not signed in itself is not launched while the owner's grant cannot be read: a CLI
+ * release restarts the owner's daemon and its relay, and a Claude launched in that gap started with no credentials and
+ * sat on "Not logged in · Please run /login" (task #3301). A relaunch is held with it and launches once the grant reads. */
+export const NO_CLAUDE_RELAY = 'Waiting for the owner\'s subscription relay on this machine: Claude Code cannot sign in here without it.'
+/** The same for a Team-account Codex in the account's own home (a Builder's), which started signed out the same way. */
+export const NO_CODEX_RELAY = 'Waiting for the owner\'s subscription relay on this machine: Codex cannot sign in here without it.'
export interface TeamRelayLaunchDeps {
/** Whether this daemon runs team work only. */
@@ -418,8 +424,10 @@ export async function teamRelayLaunch(engine: AgentEngine, deps: TeamRelayLaunch
if (!deps.team()) return null
const home = engine === 'codex' ? codexHome : undefined
// A Codex home of its own holds no sign-in but what it was given: with no relay it is refused, not launched signed out.
- const none = home === undefined ? null : { refused: NO_PM_RELAY }
+ // Neither is a Claude or a Codex the team account has not signed in itself, once its owner's relay is configured (task #3301).
+ const none = { refused: home !== undefined ? NO_PM_RELAY : engine === 'claude' ? NO_CLAUDE_RELAY : NO_CODEX_RELAY }
const config = deps.config()
+ // No team config is no relay to wait for: only a Codex home of its own is refused then.
if (!config) return home !== undefined && !await deps.signedIn(engine, home).catch(() => false) ? none : null
if (await (home === undefined ? deps.signedIn(engine) : deps.signedIn(engine, home)).catch(() => false)) return null
const grant = deps.read(config)
diff --git a/docs/plans/2026-11-05-team-claude-never-signed-out-plan.md b/docs/plans/2026-11-05-team-claude-never-signed-out-plan.md
new file mode 100644
index 000000000..9ba9ed76f
--- /dev/null
+++ b/docs/plans/2026-11-05-team-claude-never-signed-out-plan.md
@@ -0,0 +1,77 @@
+# A release never leaves Team-account Claude agents signed out: plan
+
+> Way of working: test-driven, one Engineer, by the project instructions (Engineer role). No Execution Handoff.
+
+**Goal:** a CLI release restarts every owner's daemon and the relay its Team account spends. A Team-account Claude
+launched while the owner's grant cannot be read waits for it and starts on it, never signed out; and a Team agent
+already showing Claude's signed-out or 401 screen is relaunched onto the current grant (task #3301).
+
+**Architecture:**
+- `teamRelayLaunch` (`cli/src/team/relay.ts`) answers a Claude launch in a Team daemon that has its team config, is not
+ signed in itself and reads no grant with a refusal (`NO_CLAUDE_RELAY`), as it already does for a Codex Product
+ Manager's own home. Both callers honour a refusal already: a relaunch (restore after a daemon restart, restart,
+ resume) is held with `OWNER_RELAY_UNAVAILABLE` / `unavailable: 'native'` (`cli/src/lib/launchOverrides.ts`), and the
+ held pass (`core/agents/heldLaunches.ts`) tries it again every 2–30 s, so it launches on the grant once it reads. A
+ new agent (`core/agents/create.ts`) is refused with the same code instead of starting signed out, and the Swarm start
+ moves on.
+- The terminal watch (`cli/src/superTabs/terminal.ts`) recognizes Claude Code's own signed-out notices near the prompt
+ (`Not logged in · Please run /login`, `API Error: 401 …`, `authentication_error`, `Invalid API key`, `OAuth token has
+ expired`) as a model that does not answer, only where Claude draws its notice (at the margin or as its own `⎿` row),
+ never in text the agent printed. That feeds the model alert and `RelayRecovery` (`cli/src/superTabs/relayRecovery.ts`)
+ as a 5xx does: after a minute, with a current grant that answers, the agent is restarted once per grant onto it.
+
+**Tech stack:** TypeScript, vitest.
+
+**Spec:** task #3301; Guide2's diagnosis in task #3069 (main 8704f62c4). Builders on Mac 3, MacBook-Pro-8, Tony's,
+Ken's MacbookPro and Gray's Team accounts stopped after 0.5.50–0.5.54; Quince showed `Not logged in · Please run /login`.
+
+## Global constraints
+
+- CLI only. Swarm code stays out of `cli/src/core`: no core file changes; both core callers already honour a refusal.
+- No new credential path: the grant is read as every launch reads it; the token is never logged.
+- Team daemon only. A Team account that signed Claude in itself, a non-Team daemon, and a Team daemon with no team
+ config launch as before.
+- No test signs the Mac out of the real CLI: all deps are fakes.
+
+## Review focus
+
+- That no Team-account Claude can be launched without a relay grant or its own sign-in (create, restore, restart).
+- That a held relaunch launches on the grant once it reads (daemon restart mid-session).
+- That signed-out detection cannot fire on an agent's own prose or a tool's output (no restart of a working agent).
+- That recovery still restarts at most once per agent per grant.
+
+## Tasks
+
+### Task 1: a Team Claude with no readable grant is held, then launches when it reads
+
+Files: `cli/src/team/relay.ts`, `cli/src/team/relay.spec.ts`, `cli/src/lib/launchOverrides.spec.ts`.
+
+Interfaces: `export const NO_CLAUDE_RELAY: string`; `teamRelayLaunch('claude', …)` returns `{ refused: NO_CLAUDE_RELAY }`
+when team, config present, not signed in, and `read(config)` is null.
+
+- [ ] Failing test (relay.spec): Claude in a Team daemon, not signed in, no grant → `{ refused: NO_CLAUDE_RELAY }`;
+ signed in, not Team, or no config → null as before.
+- [ ] Failing test (launchOverrides.spec): a daemon restart mid-session. The real `teamRelayLaunch` with a grant that
+ is gone while the owner's daemon restarts: the relaunch is held (`OWNER_RELAY_UNAVAILABLE`, `native`); once the
+ new grant reads, the next relaunch carries the new address and token.
+- [ ] Watch both fail; implement the refusal; watch them pass. Run `relay.spec`, `launchOverrides.spec`,
+ `core/agents/create.spec`.
+
+### Task 2: a 'Not logged in' or 401 screen is recovered by relaunch
+
+Files: `cli/src/superTabs/terminal.ts`, `cli/src/superTabs/terminal.spec.ts`, `cli/src/superTabs/relayRecovery.ts`
+(doc), `cli/src/superTabs/relayRecovery.spec.ts`.
+
+Interfaces: `export function signedOut(text: string): boolean`; `modelFailing` unchanged; the watch treats
+`modelFailing || signedOut` as a model that does not answer.
+
+- [ ] Failing tests (terminal.spec): `signedOut` knows Claude's notices and not the agent's own words or a tool's
+ output; the watch reports `failingSince` to the relay recovery for a signed-out screen.
+- [ ] Failing test (relayRecovery.spec): an agent launched signed out after a daemon restart (no grant it was
+ restarted for), showing `Not logged in`, is restarted once onto the grant that now reads, and told to carry on.
+- [ ] Watch them fail; implement; watch them pass. Run `terminal.spec`, `relayRecovery.spec`.
+
+### Task 3: evidence
+
+- [ ] Red/green evidence (tests on main's code vs the branch) in a PR comment; CLI coverage gate for the touched area
+ (`npm run test:orchestrator` if it covers superTabs), recorded in the PR.