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.

fix: a refresh that fails ambiguously must still name `harness login`

Kelvin4ca317855f68
diff --git a/cli/src/lib/authSession.spec.ts b/cli/src/lib/authSession.spec.ts
index ddca64364..9f8e47b70 100644
--- a/cli/src/lib/authSession.spec.ts
+++ b/cli/src/lib/authSession.spec.ts
@@ -61,6 +61,51 @@ describe('AuthSessionManager', () => {
expect(fetchMock).not.toHaveBeenCalled()
})
+ it('names `harness login` when the refresh service answers 503, because that is what a dead token looks like here', async () => {
+ // Measured 2026-09-06 against the live backend: an unusable refresh token comes back as
+ // `503 {"error":{"code":"AUTH_SERVICE_UNAVAILABLE"}}`, NOT 401 and not REFRESH_TOKEN_INVALID.
+ // So this answer is indistinguishable from a real outage, and the message has to carry both
+ // readings — saying only the upstream's "Authentication service unavailable" sends somebody
+ // with a dead sign-in away to wait for a service that is fine.
+ writeAuthSession(baseSession())
+ // A fresh Response per call: a body can only be read once, so one shared Response would make
+ // every call after the first see an empty body and prove nothing about the message.
+ vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockImplementation(async () => new Response(JSON.stringify({
+ success: false,
+ error: { code: 'AUTH_SERVICE_UNAVAILABLE', message: 'Authentication service unavailable' },
+ }), { status: 503 })))
+ const manager = new AuthSessionManager('https://api.example.test')
+
+ const err = await manager.accessToken().catch((e: unknown) => e) as InstanceType<typeof AuthSessionError>
+ expect(err).toMatchObject({ name: AuthSessionError.name, code: 'UNAVAILABLE' })
+ expect(err.message).toMatch(/harness login/) // the way out, which the upstream never names
+ expect(err.message).toMatch(/Authentication service unavailable/) // the upstream's own words, kept
+ })
+
+ it('keeps the session when the refresh service is merely unavailable', async () => {
+ // The other half of the same ambiguity, and the reason this must NOT be reclassified as
+ // INVALID_REFRESH: that branch deletes the session, and deleting it on a transient blip
+ // destroys a refresh token nothing can bring back. Ambiguous means keep, and say so.
+ writeAuthSession(baseSession())
+ vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockResolvedValue(new Response(JSON.stringify({
+ success: false,
+ error: { code: 'AUTH_SERVICE_UNAVAILABLE', message: 'Authentication service unavailable' },
+ }), { status: 503 })))
+ const manager = new AuthSessionManager('https://api.example.test')
+
+ await expect(manager.accessToken()).rejects.toMatchObject({ code: 'UNAVAILABLE' })
+ expect(readAuthSession()).toMatchObject({ refreshToken: 'refresh-1' })
+ })
+
+ it('still says `harness login` when the service gives no message of its own', async () => {
+ writeAuthSession(baseSession())
+ vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockRejectedValue(new Error('socket hang up')))
+ const manager = new AuthSessionManager('https://api.example.test')
+
+ await expect(manager.accessToken()).rejects.toThrow(/harness login/)
+ expect(readAuthSession()).toMatchObject({ refreshToken: 'refresh-1' })
+ })
+
it('clears an invalid refresh session instead of retrying it forever', async () => {
writeAuthSession(baseSession())
vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockResolvedValue(new Response(JSON.stringify({
diff --git a/cli/src/lib/authSession.ts b/cli/src/lib/authSession.ts
index e6228702d..e2b1edcbd 100644
--- a/cli/src/lib/authSession.ts
+++ b/cli/src/lib/authSession.ts
@@ -113,6 +113,29 @@ async function withLock<T>(action: () => Promise<T>): Promise<T> {
type RefreshResult = { token: string; refreshToken?: string; expiresIn?: number }
+/**
+ * The sentence an `UNAVAILABLE` refresh failure carries — and why it names `harness login` even
+ * though it is classified as a service problem.
+ *
+ * Measured 2026-09-06 against the live backend: an unusable refresh token comes back as
+ * `503 {"error":{"code":"AUTH_SERVICE_UNAVAILABLE"}}` — **not** 401 and **not**
+ * `REFRESH_TOKEN_INVALID`, so it never reaches the branch below whose whole job is to say the
+ * sign-in is dead. Passing the upstream's own words through verbatim then tells somebody whose
+ * sign-in has lapsed to wait for a service that is perfectly healthy, and that wait never ends.
+ *
+ * ⚠️ **It cannot simply be reclassified as `INVALID_REFRESH`.** The identical answer is what a
+ * genuine outage gives, and that branch DELETES the session — destroying a refresh token nothing
+ * can bring back, on a blip. Ambiguous means keep the credential and say both things. So the
+ * classification stays `UNAVAILABLE`, nothing is deleted, and only the wording changes: the
+ * upstream's reading first because it is the likelier one, the actionable one last because it is
+ * the one that ends the loop.
+ */
+function unavailableMessage(said?: string): string {
+ return `Could not renew this computer's sign-in${said ? ` (${said})` : ''}. `
+ + 'That is usually the SSO service having a moment, but it is also what a lapsed sign-in looks '
+ + 'like here — if it keeps happening, run `harness login` to sign in again.'
+}
+
async function refreshRequest(baseUrl: string, current: AuthSession): Promise<RefreshResult> {
if (!current.refreshToken) throw new AuthSessionError('No SSO refresh token. Run `harness login`.', 'MISSING')
let response: Response
@@ -123,7 +146,7 @@ async function refreshRequest(baseUrl: string, current: AuthSession): Promise<Re
body: JSON.stringify({ refreshToken: current.refreshToken, autonomousEnv: current.autonomousEnv }),
})
} catch {
- throw new AuthSessionError('SSO refresh service is unavailable.', 'UNAVAILABLE')
+ throw new AuthSessionError(unavailableMessage(), 'UNAVAILABLE')
}
const body = await response.json().catch(() => ({})) as {
success?: boolean; data?: { token?: unknown; refreshToken?: unknown; expiresIn?: unknown }; error?: { code?: unknown; message?: unknown }
@@ -132,7 +155,10 @@ async function refreshRequest(baseUrl: string, current: AuthSession): Promise<Re
throw new AuthSessionError('SSO refresh token is invalid. Run `harness login`.', 'INVALID_REFRESH')
}
if (!response.ok || body.success === false || typeof body.data?.token !== 'string' || !body.data.token) {
- throw new AuthSessionError(typeof body.error?.message === 'string' ? body.error.message : 'SSO refresh service is unavailable.', 'UNAVAILABLE')
+ throw new AuthSessionError(
+ unavailableMessage(typeof body.error?.message === 'string' && body.error.message ? body.error.message : undefined),
+ 'UNAVAILABLE',
+ )
}
return {
token: body.data.token,