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.

feat: support offline mode by decoupling daemon readiness from backend connectivity and adding CLI execution timeouts

0xken1523603250cd4d
diff --git a/cli/src/authCommand.spec.ts b/cli/src/authCommand.spec.ts
index 20978d170..5dd562fe3 100644
--- a/cli/src/authCommand.spec.ts
+++ b/cli/src/authCommand.spec.ts
@@ -28,14 +28,14 @@ function tempRoot(): string {
return root
}
-function seedSession(root: string): void {
+function seedSession(root: string, opts: { expiresInMs?: number } = {}): void {
const authDir = join(root, 'auth')
mkdirSync(authDir, { recursive: true })
writeFileSync(join(authDir, 'session.json'), JSON.stringify({
version: 1,
accessToken: 'tok_seeded',
refreshToken: 'refresh_seeded',
- expiresAt: Date.now() + 60 * 60_000, // an hour out — accessToken() must not attempt a refresh
+ expiresAt: Date.now() + (opts.expiresInMs ?? 60 * 60_000), // an hour out — accessToken() must not attempt a refresh
autonomousEnv: 'prod',
computerId: 'a'.repeat(32),
machineId: 'm_seeded',
@@ -143,6 +143,17 @@ describe('harness auth status --json', () => {
expiresAt: expect.any(Number),
})
})
+
+ it('reports loggedIn:true and offline:true when the token needs a refresh the service cannot serve', () => {
+ // Near expiry forces a refresh; port 1 refuses it. That is a signed-in computer with no network —
+ // not a signed-out one. It used to read as loggedIn:false and send the desktop app to a login
+ // screen that could not have succeeded without the network either.
+ const root = tempRoot()
+ seedSession(root, { expiresInMs: 30_000 })
+ const result = runSync(root, ['auth', 'status', '--json'], 'http://127.0.0.1:1')
+ expect(result.status).toBe(0)
+ expect(JSON.parse(result.stdout.trim())).toMatchObject({ loggedIn: true, offline: true, machineId: 'm_seeded' })
+ })
})
describe('harness login --json', () => {
diff --git a/cli/src/backendSocket.spec.ts b/cli/src/backendSocket.spec.ts
index e926a5604..e35a02d38 100644
--- a/cli/src/backendSocket.spec.ts
+++ b/cli/src/backendSocket.spec.ts
@@ -1807,6 +1807,35 @@ describe('grid_models_list says whether this machine has a grid CLI', () => {
})
})
+describe('the connect burst with no network', () => {
+ afterEach(() => { wsMock.instances.length = 0 })
+
+ it('a grid_models_list that never answers does not hold agents_list or usage_read behind it', async () => {
+ // Measured 2026-09-18, wifi off, daemon restarted: the desktop asks grid_models_list,
+ // terminal_capabilities and agents_list in one breath on every connect. grid_models_list waited
+ // on a grid reconcile that could not finish, and the ordered per-connection chain held the other
+ // two behind it past the app's 10s timeout — on which the app forced a reconnect and asked all
+ // three again, for as long as the wifi stayed off. The terminal on the same computer read
+ // "offline" the whole time.
+ const socket = new BackendSocket('token')
+ socket.deriveGridName = async () => null
+ socket.gridReadyProbe = () => new Promise<void>(() => {}) // a reconcile that never lands
+ socket.accountUsageReader = () => new Promise(() => {}) // a vendor that never answers
+ const frames: Array<Record<string, unknown>> = []
+ socket.registerLocalClient('local:burst', { sendFrame: (frame) => { frames.push(frame); return true }, sendBinary: () => true })
+
+ socket.handleLocalFrame('local:burst', { type: 'grid_models_list', payload: { requestId: 'grid' } })
+ socket.handleLocalFrame('local:burst', { type: 'usage_read', payload: { requestId: 'usage' } })
+ socket.handleLocalFrame('local:burst', { type: 'agents_list', payload: { requestId: 'agents' } })
+
+ await vi.waitFor(() => expect(frames.some((f) => f.type === 'agents_list_result')).toBe(true))
+ expect(frames.some((f) => f.type === 'grid_models_list_result')).toBe(false)
+ expect(frames.some((f) => f.type === 'usage_read_result')).toBe(false)
+ await socket.unregisterLocalClient('local:burst')
+ await socket.stop()
+ })
+})
+
describe('machine_meta carries the grid name without clobbering it on rename', () => {
afterEach(() => { wsMock.instances.length = 0 })
diff --git a/cli/src/backendSocket.ts b/cli/src/backendSocket.ts
index 6c7b80c7e..b7371ab91 100644
--- a/cli/src/backendSocket.ts
+++ b/cli/src/backendSocket.ts
@@ -551,6 +551,9 @@ export class BackendSocket {
/** Answers `usage_read` — this machine's own agent-account usage (lib/accountUsage.ts). A field
* rather than a direct call so a spec answers it without a real home, Keychain or network. */
accountUsageReader: () => Promise<AccountUsageReading[]> = readAccountUsage
+ /** The grid listing currently out, shared by every `grid_models_list` for the same own grid
+ * that lands meanwhile. */
+ private gridModelsInFlight: { gridName: string | null; grids: ReturnType<typeof listAllGridModels> } | null = null
/** Receives `theme_set` — the desktop's pane colours, to become this machine's tmux
* `window-style` (lib/hostTheme.ts). Wired by cli.ts; null answers with UNSUPPORTED. */
hostThemeSink: ((theme: HostTheme) => void) | null = null
@@ -1785,24 +1788,49 @@ export class BackendSocket {
case 'grid_models_list': {
// Every grid this computer is signed into, in sections, the account's own first. `gridName`
// and `models` keep naming the own grid alone, for an app that predates `grids`.
- const gridName = await this.resolveGridName()
- const grids = await listAllGridModels(gridName)
- reply(type, requestId, {
- gridName,
- models: grids.find((g) => g.own)?.models ?? [],
- grids,
- // Which engines a Local model can be offered to at all. Static per CLI version — it is
- // the set of launch contracts in `gridLaunch.ts` — and answered here, beside the list,
- // so the picker can say "Cursor runs only on its own login" instead of offering a row
- // whose retarget the daemon would refuse. An older app ignores the field; an older
- // daemon omits it, which the app reads as "offer everything", as before.
- localModelEngines: gridCapableEngines(),
- // Whether this MACHINE has a `grid` to run at all — `managed`, `path` or `missing` —
- // as distinct from `gridName`, which is about the account. The Local model dialog was
- // gating on the account alone and starting an agent whose second step is `grid`; this
- // is what lets it, and the picker, say so first. An older app ignores the field.
- gridCli: gridCliPresence(),
- })
+ //
+ // DETACHED from this connection's ordered RPC chain, like `engines_probe`: it waits on a
+ // grid reconcile (up to 6s), then `grid` spawns that each go to the network (up to 30s).
+ // The desktop asks for it in the same breath as `terminal_capabilities` and `agents_list`
+ // on every connect, and awaited here it held both behind it — with no network, past the
+ // app's 10s request timeout, on which the app forces a reconnect and asks all three again.
+ // Measured 2026-09-18, wifi off, daemon restarted: every local RPC timed out for as long
+ // as the backend stayed unreachable; the terminal on the SAME computer sat on "offline"
+ // until the wifi came back. Request ids make the reply safe to land out of order.
+ //
+ // One computation at a time: detached, a second ask that lands while the first is still
+ // out (the app re-asks on every connect, and its own 12s timeout is shorter than the grid
+ // spawns' 30s) would start more `grid` processes for the same answer. Later askers share
+ // the one in flight; the cache in listGridModels covers the settled case.
+ void (async () => {
+ const gridName = await this.resolveGridName()
+ const inFlight = this.gridModelsInFlight
+ const listing = inFlight && inFlight.gridName === gridName
+ ? inFlight.grids
+ : (this.gridModelsInFlight = {
+ gridName,
+ grids: listAllGridModels(gridName).finally(() => {
+ if (this.gridModelsInFlight?.gridName === gridName) this.gridModelsInFlight = null
+ }),
+ }).grids
+ const grids = await listing
+ reply(type, requestId, {
+ gridName,
+ models: grids.find((g) => g.own)?.models ?? [],
+ grids,
+ // Which engines a Local model can be offered to at all. Static per CLI version — it is
+ // the set of launch contracts in `gridLaunch.ts` — and answered here, beside the list,
+ // so the picker can say "Cursor runs only on its own login" instead of offering a row
+ // whose retarget the daemon would refuse. An older app ignores the field; an older
+ // daemon omits it, which the app reads as "offer everything", as before.
+ localModelEngines: gridCapableEngines(),
+ // Whether this MACHINE has a `grid` to run at all — `managed`, `path` or `missing` —
+ // as distinct from `gridName`, which is about the account. The Local model dialog was
+ // gating on the account alone and starting an agent whose second step is `grid`; this
+ // is what lets it, and the picker, say so first. An older app ignores the field.
+ gridCli: gridCliPresence(),
+ })
+ })().catch(() => reply(type, requestId, { error: 'GRID_MODELS_FAILED' }))
return
}
@@ -2402,7 +2430,12 @@ export class BackendSocket {
// not — which may be signed in to a different subscription entirely. The vendor's answer goes
// back as it came: see lib/accountUsage.ts for why the parsing stays on the client.
case 'usage_read': {
- reply(type, requestId, { providers: await this.accountUsageReader() })
+ // Two vendor round trips (up to 8s each, lib/accountUsage.ts) — detached from the ordered
+ // chain for the same reason as `grid_models_list`: it is asked on connect beside the RPCs
+ // the terminal needs, and with no network it held them past the app's timeout.
+ void this.accountUsageReader()
+ .then((providers) => reply(type, requestId, { providers }))
+ .catch(() => reply(type, requestId, { error: 'USAGE_READ_FAILED' }))
return
}
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index c11827538..c6e64be8c 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -158,7 +158,7 @@ import { MachinePeerStore } from './lib/e2ee/machinePeers.js'
import { connectWithPassword } from './lib/e2ee/relayClient.js'
import {
startSelfUpdater, restore as restoreUpdate, confirm as confirmUpdate,
- fetchManifest, downloadVerified, canary, stage, semverGt, shouldAutoUpdate, isLocalDevBuild,
+ fetchManifest, downloadVerified, canary, stage, semverGt, isLocalDevBuild,
type Poller, type UpdateEntry,
} from './lib/selfUpdate.js'
import { managedNodePath } from './lib/nodeRuntime.js'
@@ -284,10 +284,6 @@ const DEVIN_DB = join(env.DEVIN_HOME, 'sessions.db')
// reported by the daemon in words rather than by the app as a timeout.
const PROXY_BACKEND_TIMEOUT_MS = 20_000
-// How long `harness start` waits for the background daemon to report "[backend] connected" before
-// declaring an error. A healthy backend connects in well under this; a timeout ⇒ unreachable.
-const CONNECT_WAIT_MS = 10_000
-
/** Bounds the `POST /api/grid/name` inside the daemon-start grid reconcile, so a stalled control-plane
* connection cannot hold it open. */
const GRID_MINT_TIMEOUT_MS = 10_000
@@ -436,11 +432,14 @@ async function requestJson<T>(
signal?: AbortSignal,
): Promise<T> {
// A GET/DELETE with no body must not carry a content-type — some proxies reject that pairing.
+ // Always bounded: a caller that passes no signal gets the proxy's own bound, so a black-holed
+ // backend (packets dropped, never refused) is an error in 20s and not a process that never exits —
+ // `harness start` used to hang here, and the desktop app, waiting on that start, hung with it.
const res = await fetch(`${backendHttpBase()}${path}`, {
method,
headers: body === undefined ? headers : { 'content-type': 'application/json', ...headers },
...(body === undefined ? {} : { body: JSON.stringify(body) }),
- ...(signal ? { signal } : {}),
+ signal: signal ?? AbortSignal.timeout(PROXY_BACKEND_TIMEOUT_MS),
})
const json = (await res.json().catch(() => ({}))) as { success?: boolean; data?: T; error?: { message?: string } }
if (!res.ok || json.success === false) {
@@ -471,7 +470,7 @@ async function controlPlaneAuth(): Promise<{ session: AuthSession; headers: Reco
}
/** Resolve the canonical machine for the durable computer id without ever using a machine API key. */
-async function resolveComputerMachine(): Promise<AuthSession> {
+async function resolveComputerMachine(signal?: AbortSignal): Promise<AuthSession> {
const current = readAuthSession()
if (!current) throw new Error('Not signed in. Run `harness login`.')
const auth = new AuthSessionManager(backendHttpBase())
@@ -485,7 +484,7 @@ async function resolveComputerMachine(): Promise<AuthSession> {
}, {
authorization: `Bearer ${accessToken}`,
'x-autonomous-env': current.autonomousEnv,
- })
+ }, signal)
const machineId = result.machine?.machineId
if (!machineId) throw new Error('Backend did not return a machine id for this computer')
// Refresh can atomically replace the session while this request is in flight. Always merge the
@@ -512,14 +511,22 @@ async function authStatusCommand(json: boolean): Promise<void> {
}
const auth = new AuthSessionManager(backendHttpBase())
let loggedIn = true
+ let offline = false
try {
await auth.accessToken()
} catch (err) {
- loggedIn = !(err instanceof AuthSessionError)
+ // Only a session the SSO service will never renew (or none at all) is "not signed in". A refresh
+ // that could not be SERVED right now — no network, service down — is a signed-in computer that is
+ // offline, and says so; it used to read as signed out and send the desktop app to a login screen
+ // that could not have succeeded either. Same split proxyBackend makes (401 vs 502).
+ if (err instanceof AuthSessionError && err.code === 'UNAVAILABLE') offline = true
+ else loggedIn = !(err instanceof AuthSessionError)
}
const latest = readAuthSession()
+ const signedIn = loggedIn && latest !== null
const payload = {
- loggedIn: loggedIn && latest !== null,
+ loggedIn: signedIn,
+ ...(signedIn && offline ? { offline: true } : {}),
computerId: latest?.computerId,
machineId: latest?.machineId,
autonomousEnv: latest?.autonomousEnv,
@@ -990,24 +997,17 @@ async function startCommand(foreground: boolean, repair: boolean = false): Promi
console.error('\n ✗ Not signed in. Run: harness login\n')
process.exit(1)
}
- // Update-before-connect: pull the newest bundle so a machine always reconnects on the latest build.
- // Staging swaps ~/.harness/cli/cli.js, and the daemon start spawns below (`node cli.js __run`)
- // executes those fresh bytes. Skipped in the foreground (THIS process becomes the long-lived daemon
- // and self-updates on its own) and on a dev/repo build; never blocks start if the check fails.
- // Run alongside resolveComputerMachine() rather than before it — the two touch disjoint resources
- // (bundle files vs. the auth-session file/a machine-resolve POST), so there is nothing to serialize.
- //
- // Under the spawn lock from the staging onwards: the running daemon's own updater swaps the same
- // cli.js/.prev, and two writers there can leave `.prev` holding the NEW bytes — which is what a
- // later rollback would then "restore". The lock is re-entrant, so `launch` below just joins it.
+ // The session file is the ONLY thing `start` needs. It used to pull the newest bundle and resolve
+ // this computer's machine against the backend before launching — so a computer that could not reach
+ // the backend could not start its daemon at all (a black-holed link hung here forever, and the
+ // desktop app, which spawns this command when the port is silent, hung on "Starting local service…"
+ // with it). Both now belong to the daemon: it updates itself on its own tick (startSelfUpdater) and
+ // it dials, retries and serves the cached machine list until the backend answers. `harness update`
+ // remains for an update on demand.
if (!foreground) {
- // A daemon that is already up is left ALONE — bundle included. Staging is for the daemon this
- // command is about to spawn; a live one updates itself (and hands off under the spawn lock). The
- // desktop app re-runs `harness start` whenever its 400ms probe misreads a busy daemon as down, and
- // staging on each of those swapped cli.js/notify.mjs under the running process and dropped its
- // `.prev` — so the daemon's own updater later wrote `.prev` from the NEW bytes, and a rollback
- // "restored" the very build that had just failed. `spawnDaemon` repeats this check under the
- // lock, for the daemon that comes up while we are waiting our turn.
+ // A daemon that is already up is left ALONE. The desktop app re-runs `harness start` whenever its
+ // 400ms probe misreads a busy daemon as down; `spawnDaemon` repeats this check under the lock, for
+ // the daemon that comes up while we are waiting our turn.
const running = readPid()
if (running && isAlive(running)) {
// Left alone only when it serves THIS sign-in. A daemon on another account — what a forced
@@ -1029,11 +1029,7 @@ async function startCommand(foreground: boolean, repair: boolean = false): Promi
await stopDaemonProcess()
}
await withSpawnLock('start', async () => {
- const [v] = await Promise.all([
- stageLatestBundle((m) => console.log(m)),
- resolveComputerMachine(),
- ])
- if (v) console.log(` ✓ updated to v${v} — connecting on the new build`)
+ await resolveMachineIfUnknown(session)
await launch(foreground, repair)
}, {
onWaiting: (owner) => console.log(` the daemon is ${describeSpawnLockOwner(owner)} — waiting for it to finish…`),
@@ -1045,10 +1041,27 @@ async function startCommand(foreground: boolean, repair: boolean = false): Promi
})
return
}
- await resolveComputerMachine()
+ await resolveMachineIfUnknown(session)
await launch(foreground, repair)
}
+/**
+ * The one backend round trip `start` may still make, and only when the session has no machine id —
+ * a file written by a build that predates login resolving it. Bounded, and never fatal: the daemon
+ * runs on the computer id meanwhile (runForeground `session.machineId ?? session.computerId`; the
+ * adapter dial omits the `&machine=` claim for a non-machine id and the backend pairs by `?computer=`),
+ * and the next login or online start writes the id. A session that already has one costs nothing here.
+ */
+async function resolveMachineIfUnknown(session: AuthSession): Promise<void> {
+ if (session.machineId) return
+ try {
+ await resolveComputerMachine(AbortSignal.timeout(RESOLVE_ON_START_TIMEOUT_MS))
+ } catch (err) {
+ console.log(` (machine id not resolved yet — ${err instanceof Error ? err.message : String(err)}; starting on the computer id, resolved on the next login or online start)`)
+ }
+}
+const RESOLVE_ON_START_TIMEOUT_MS = 10_000
+
/** Download + sha256-verify + canary the manifest's cli.js/notify.mjs, then atomically swap them into
* the installed CLI dir (dropping the .prev backups on success). The freshly-written cli.js is what the
* NEXT spawned daemon (`node cli.js __run`) executes — so staging here = "update, then run the new build".
@@ -1062,24 +1075,6 @@ async function downloadCanaryStage(entry: UpdateEntry, dir: string, log: (m: str
return true
}
-/** Fetch the manifest and, if a strictly-newer build exists, stage it (see downloadCanaryStage). Returns
- * the staged version, or null when nothing was staged — already current, a local, dev/repo or
- * update-disabled build, or ANY fetch/verify/canary failure (all swallowed: an update hiccup must
- * never block `start`). See {@link shouldAutoUpdate} for why a local build is left alone. */
-async function stageLatestBundle(log: (m: string) => void): Promise<string | null> {
- if (SCRIPT_PATH.endsWith('.ts') || env.ADAPTER_UPDATE_DISABLE) return null // dev/repo run never touches the installed bundle
- const dir = resolve(env.ADAPTER_CLI_DIR)
- try {
- const entry = await fetchManifest(env.ADAPTER_UPDATE_URL, env.ADAPTER_UPDATE_KEY)
- if (!entry || !shouldAutoUpdate(entry.version, VERSION)) return null
- log(`▸ newer build available — updating v${VERSION} → v${entry.version}…`)
- return (await downloadCanaryStage(entry, dir, log)) ? entry.version : null
- } catch (e) {
- log(` (update check skipped: ${e instanceof Error ? e.message : String(e)})`)
- return null
- }
-}
-
/** `harness update` — force the self-update NOW instead of waiting for the daemon's
* background poll. Checks the manifest; if a newer build exists it stops any running daemon first (so
* its poller can't race our staging), swaps in the new bytes, then relaunches on them. No-op on a
@@ -5376,18 +5371,20 @@ async function runForeground(session: AuthSession): Promise<void> {
* the one fact that tells a daemon on THIS sign-in from one left over from the previous account (see
* startCommand). Null when the daemon does not say.
*/
-async function runningDaemonStatus(): Promise<{ version: string; sessions: number; machineId: string | null } | null> {
+async function runningDaemonStatus(): Promise<{ version: string; sessions: number; machineId: string | null; connected: boolean } | null> {
try {
const res = await fetch(`http://127.0.0.1:${daemonPort()}/api/status`, {
signal: AbortSignal.timeout(1_500),
})
if (!res.ok) return null
const body: unknown = await res.json()
- const status = body as { version?: unknown; sessions?: unknown; machineId?: unknown } | null
+ const status = body as { version?: unknown; sessions?: unknown; machineId?: unknown; connected?: unknown } | null
const version = typeof status?.version === 'string' && status.version ? status.version : VERSION
const sessions = Array.isArray(status?.sessions) ? status.sessions.length : 0
const machineId = typeof status?.machineId === 'string' && status.machineId ? status.machineId : null
- return { version, sessions, machineId }
+ // Missing on a daemon too old to report it — read as connected, as the desktop app does.
+ const connected = status?.connected !== false
+ return { version, sessions, machineId, connected }
} catch {
return null
}
@@ -5405,7 +5402,7 @@ function printInfoBlock(opts: {
const row = (k: string, v: string): string => ` ${k.padEnd(10)} ${v}`
const rule = ' ' + '─'.repeat(37)
console.log('')
- console.log(' machine · remote machine connected')
+ console.log(' machine · remote machine')
console.log(rule)
console.log(row('status', opts.status))
// Display name mirrored from the backend by the daemon (machine_meta) — only shown when named.
@@ -5524,64 +5521,14 @@ async function spawnDaemon(session: AuthSession, runtimeNode: string | null): Pr
process.exit(1)
}
- const ready = await waitForReady(logOffset, CONNECT_WAIT_MS, launchDeps)
-
- // DEAUTH (401/403): the saved credential is no longer valid — this computer was removed from the machine
- // (or the token is stale). Wipe it, stop the daemon, and signal the caller to ask for a fresh token.
- if (ready.state === 'deauth') {
- try { if (child.pid) process.kill(child.pid, 'SIGTERM') } catch { /* ignore */ }
- removePidFileIf(child.pid)
- clearAuthSession()
- return
- }
-
- // BUSY (409): one machine per machine — this machine is already connected from another computer. The
- // credential is valid, just in use elsewhere, so KEEP the token; stop the daemon and inform (not a
- // failure, not a retry loop). The user stops the other machine first, then runs `harness start` here.
- if (ready.state === 'busy') {
- try { if (child.pid) process.kill(child.pid, 'SIGTERM') } catch { /* ignore */ }
- removePidFileIf(child.pid)
- console.log('\n ℹ This machine is already connected from another computer.')
- console.log(' Only one machine per machine — stop the adapter on that machine first,')
- console.log(' then run `harness start` here again.')
- process.exit(0)
- }
-
- // FATAL misconfig (wrong route → 404, DNS, TLS): retrying is pointless → kill the daemon and say what
- // to fix. (Not 401/403 — those are handled as deauth above.)
- if (ready.state === 'fatal') {
- try { if (child.pid) process.kill(child.pid, 'SIGTERM') } catch { /* ignore */ }
- removePidFileIf(child.pid)
- // A hook-port clash isn't a backend problem — it's a duplicate/leftover adapter. Report it as such.
- if (ready.detail?.startsWith('hook port')) {
- console.error(`\n✗ ${ready.detail}`)
- console.error(` logs ${tildify(LOG_FILE)}`)
- } else {
- console.error(`\n✗ Could not connect to the backend: ${ready.detail}`)
- console.error(` backend ${env.BACKEND_WS_URL}`)
- console.error(` logs ${tildify(LOG_FILE)}`)
- console.error(' If this computer was removed from your machine, run: harness login')
- }
- process.exit(1)
- }
-
- // Not connected YET, but transient (backend deploying / 5xx / slow / not up). The daemon is alive and
- // retries with backoff — it will connect on its own — so leave it running and say so plainly (never a
- // meaningless one-shot "connecting…"). The user runs `harness start` once, not on a babysitting loop.
- if (ready.state === 'unreachable') {
- // Lead with the RUNNING state (+ pid), not the error — the daemon IS started and self-retrying, so
- // seeing a pid / "harness stop" later isn't a surprise. This is not a failure; it reconnects itself.
- console.log(`\n● adapter started · running in the background · pid ${child.pid}`)
- console.log(` Not connected yet — ${ready.detail}. It keeps retrying and connects on its own`)
- console.log(' when the backend is reachable — no need to re-run.')
- console.log(` backend ${env.BACKEND_WS_URL}`)
- console.log(` status harness status · stop harness stop · logs ${tildify(LOG_FILE)}`)
- process.exit(0) // daemon stays alive
- }
-
+ // Bound is started. What the daemon does next — dial the backend, retry on its own backoff, sign
+ // itself out on a 401, step aside on a 409 — is its own business and is logged by it; this command
+ // used to sit here for up to ten seconds watching the log for "[backend] connected", and a computer
+ // with no route to the backend paid all ten before hearing that its daemon was fine. `harness
+ // status` says whether the link is up; the desktop app reads the same fact off `/api/status`.
const daemonStatus = await runningDaemonStatus()
printInfoBlock({
- status: '● connected',
+ status: '● started · connecting to the backend in the background',
pid: child.pid ?? 0,
machineId: session.machineId,
sessions: daemonStatus?.sessions ?? 0,
@@ -6236,7 +6183,15 @@ async function status(): Promise<void> {
const daemonStatus = alive ? await runningDaemonStatus() : null
if (!alive) registry.load()
printInfoBlock({
- status: alive ? '● running' : '○ stopped',
+ // The backend link is the daemon's own business, so `status` is where it is read — `start` no
+ // longer waits to see it, and a daemon with no backend is still serving every local agent.
+ status: !alive
+ ? '○ stopped'
+ : daemonStatus == null
+ ? '● running · not answering yet'
+ : daemonStatus.connected
+ ? '● running · backend connected'
+ : '● running · backend offline — retrying in the background',
pid: pid ?? 0,
machineId: session.machineId,
sessions: daemonStatus?.sessions ?? 0,
diff --git a/cli/src/cliCommand.spec.ts b/cli/src/cliCommand.spec.ts
index 65741d0be..9594e895b 100644
--- a/cli/src/cliCommand.spec.ts
+++ b/cli/src/cliCommand.spec.ts
@@ -204,9 +204,41 @@ describe('start beside a daemon that serves another account', () => {
expect(result.stdout).not.toContain('already running')
await daemon.exited
expect(existsSync(join(root, 'data', 'adapter.pid'))).toBe(false)
- // The restart itself goes on to resolve this session's machine with the backend, which is refused
- // here (port 1) — past the point under test, and the one place a repo run could boot a daemon.
+ // The restart goes on to boot a daemon inline (a repo run) — which fails to bind, because the port
+ // it was handed is this test's own status server. Past the point under test; the backend is never
+ // consulted (start no longer resolves the machine when the session already names one).
expect(result.status).toBe(1)
+ expect(result.stdout + result.stderr).not.toContain('resolve-computer')
+ }, 20_000)
+
+ it('starts without the backend: a session that already names its machine never calls it', async () => {
+ // Offline is the case this exists for. The backend here is port 1 — refused instantly — and the
+ // only thing that stops the boot is the port clash with this test's status server, AFTER the point
+ // where `start` used to abort on the resolve. No "Failed to start adapter: fetch failed".
+ const root = freshRoot()
+ seedSession(root)
+ const port = await daemonStatusServer('m_other')
+
+ const result = await runAsync(root, ['start'], { PORT: String(port) })
+
+ expect(result.stderr).not.toContain('fetch failed')
+ expect(result.stdout + result.stderr).not.toContain('resolve-computer')
+ expect(result.stdout).toContain('dev mode — running in the foreground')
+ }, 20_000)
+
+ it('starts without the backend even when the session has no machine id yet, on the computer id', async () => {
+ const root = freshRoot()
+ mkdirSync(join(root, 'auth'), { recursive: true })
+ writeFileSync(join(root, 'auth', 'session.json'), JSON.stringify({
+ version: 1, accessToken: 'tok', refreshToken: 'refresh', expiresAt: Date.now() + 3_600_000,
+ autonomousEnv: 'prod', computerId: 'a'.repeat(32), updatedAt: Date.now(),
+ }))
+ const port = await daemonStatusServer('m_other')
+
+ const result = await runAsync(root, ['start'], { PORT: String(port) })
+
+ expect(result.stdout).toContain('machine id not resolved yet')
+ expect(result.stdout).toContain('dev mode — running in the foreground')
}, 20_000)
it('leaves one that serves this session alone', async () => {
diff --git a/cli/src/lib/daemonLaunch.spec.ts b/cli/src/lib/daemonLaunch.spec.ts
index b801a2b94..f06a12a61 100644
--- a/cli/src/lib/daemonLaunch.spec.ts
+++ b/cli/src/lib/daemonLaunch.spec.ts
@@ -41,7 +41,8 @@ describe('connectFailure', () => {
expect(connectFailure('Unexpected server response: 409', 1)).toMatchObject({ busy: true })
expect(connectFailure('Unexpected server response: 404', 1)).toMatchObject({ fatal: true, deauth: false })
expect(connectFailure('Unexpected server response: 502', 1)).toMatchObject({ fatal: false })
- expect(connectFailure('getaddrinfo ENOTFOUND x', 1)).toMatchObject({ fatal: true })
+ // Offline is not a misconfiguration: the daemon stays up and serves the loopback until DNS is back.
+ expect(connectFailure('getaddrinfo ENOTFOUND x', 1)).toMatchObject({ fatal: false })
expect(connectFailure('connect ECONNREFUSED', 1)).toMatchObject({ fatal: false })
})
})
diff --git a/cli/src/lib/daemonLaunch.ts b/cli/src/lib/daemonLaunch.ts
index 96ec4731b..1f470abbf 100644
--- a/cli/src/lib/daemonLaunch.ts
+++ b/cli/src/lib/daemonLaunch.ts
@@ -75,7 +75,11 @@ export function connectFailure(tail: string, port: number): ConnectFailure | nul
const deauth = code === 401 || code === 403
return { detail: `backend returned HTTP ${code}`, fatal: deauth || code === 404, deauth }
}
- if (/ENOTFOUND|EAI_AGAIN|getaddrinfo/.test(tail)) return { detail: 'host not found (DNS)', fatal: true }
+ // DNS failing is the ordinary shape of "this computer is offline" (no resolver, captive portal,
+ // airplane mode) — not a misconfiguration. Fatal here used to SIGTERM a daemon that was serving its
+ // agents perfectly well over the loopback, and the desktop app then had nothing to attach to. Left
+ // running, it keeps retrying on its own backoff and connects the moment the network is back.
+ if (/ENOTFOUND|EAI_AGAIN|getaddrinfo/.test(tail)) return { detail: 'host not found (DNS)', fatal: false }
if (/certificate|CERT_|self-signed/i.test(tail)) return { detail: 'TLS certificate error', fatal: true }
if (/ECONNREFUSED/.test(tail)) return { detail: 'connection refused', fatal: false } // backend not up yet → retry
// A 1006 close with no HTTP code — generic "couldn't reach it right now"; transient.
diff --git a/desktop/lib/auth/cli_login.dart b/desktop/lib/auth/cli_login.dart
index 4a3690c94..68176bd27 100644
--- a/desktop/lib/auth/cli_login.dart
+++ b/desktop/lib/auth/cli_login.dart
@@ -7,12 +7,17 @@ import 'sign_in_client.dart';
class CliAuthStatus {
final bool loggedIn;
+
+ /// Signed in, but the CLI could not refresh the token just now (no network, SSO down). Still
+ /// [loggedIn]: the session is on disk and the daemon runs on it; only the backend is out of reach.
+ final bool offline;
final String? computerId;
final String? machineId;
final String? autonomousEnv;
const CliAuthStatus({
required this.loggedIn,
+ this.offline = false,
this.computerId,
this.machineId,
this.autonomousEnv,
@@ -20,6 +25,7 @@ class CliAuthStatus {
factory CliAuthStatus.fromJson(Map<String, dynamic> json) => CliAuthStatus(
loggedIn: json['loggedIn'] == true,
+ offline: json['offline'] == true,
computerId: json['computerId'] as String?,
machineId: json['machineId'] as String?,
autonomousEnv: json['autonomousEnv'] as String?,
diff --git a/desktop/lib/core/harness_cli_runner.dart b/desktop/lib/core/harness_cli_runner.dart
index 0cbc18d69..c6e9d117d 100644
--- a/desktop/lib/core/harness_cli_runner.dart
+++ b/desktop/lib/core/harness_cli_runner.dart
@@ -1,4 +1,5 @@
import 'host_platform.dart';
+
import 'dart:io';
import '../logging/cli_transcript.dart';
@@ -19,6 +20,13 @@ import '../logging/cli_transcript.dart';
class HarnessCliRunner {
final Directory harnessHome;
final Map<String, String> environment;
+
+ /// How long one CLI command may take before the app stops waiting on it. Every command this app
+ /// runs answers in well under a second (`auth status`, `link list`) or a few seconds (`start`
+ /// spawning the daemon and waiting for its port). A `start` that had to reach a black-holed
+ /// backend used to sit here for good — and the app sat on "Starting local service…" with it.
+ final Duration runTimeout;
+ static const defaultRunTimeout = Duration(seconds: 30);
final Future<ProcessResult> Function(
String executable,
List<String> arguments, {
@@ -35,6 +43,7 @@ class HarnessCliRunner {
HarnessCliRunner({
Directory? harnessHome,
Map<String, String>? environment,
+ this.runTimeout = defaultRunTimeout,
Future<ProcessResult> Function(
String executable,
List<String> arguments, {
@@ -116,11 +125,21 @@ class HarnessCliRunner {
final invocation = await resolve(arguments);
return logProcessRun(
_displayLine(arguments),
- () => _runProcess(
- invocation.executable,
- invocation.arguments,
- environment: invocation.environment,
- ),
+ () =>
+ _runProcess(
+ invocation.executable,
+ invocation.arguments,
+ environment: invocation.environment,
+ ).timeout(
+ runTimeout,
+ // The child is not killed — `Process.run` gives no handle to it, and a stuck `start` is the
+ // CLI's own lock's business. What ends here is the app's wait, as an error it can show.
+ onTimeout: () => throw ProcessException(
+ 'harness',
+ arguments,
+ 'did not finish within ${runTimeout.inSeconds}s',
+ ),
+ ),
);
}
diff --git a/desktop/lib/state/app_state.dart b/desktop/lib/state/app_state.dart
index 7e041fa46..b8796c65a 100644
--- a/desktop/lib/state/app_state.dart
+++ b/desktop/lib/state/app_state.dart
@@ -412,6 +412,16 @@ class AppNotifier extends ChangeNotifier {
/// The last [ensureCliDaemonReady] did not reach a ready daemon — the one
/// error the supervisor's ready transition is allowed to retry away.
bool _daemonGateFailed = false;
+
+ /// The daemon's backend link as it last reported it (`/api/status.connected`), fed by the boot
+ /// probe and then by the supervisor's 5s tick. Null until a daemon has answered at all. False is
+ /// not an error: this computer's agents work over the loopback regardless; it is what makes the
+ /// rail say "offline copy" and what keeps a failed machine list from raising the red strip.
+ bool? _backendOnline;
+ bool? get backendOnline => _backendOnline;
+ // The last probe state the boot gate logged, so a daemon that sits in one state for a minute
+ // costs one line, not one per 500ms tick.
+ String? _loggedDaemonState;
// Update checks do not depend on the daemon or SSO. A signed-out user should
// still be able to replace a broken desktop build from the login screen.
Timer? _updateCheckTimer;
@@ -2330,24 +2340,33 @@ class AppNotifier extends ChangeNotifier {
// answers. Waiting for the machine list first would leave the window empty
// for as long as the slowest one takes, and would hand the first-run
// auto-pick a window in which the grid still looks empty.
+ // Every exit below clears the message: a boot superseded by a sign-out/sign-in mid-way (the
+ // `_authWorkCurrent` returns) used to leave "Starting local service…" on a screen nothing would
+ // ever repaint.
await _restorePaneLayout();
- if (!_authWorkCurrent(revision)) return;
+ if (!_authWorkCurrent(revision)) {
+ _bootStatusMessage = null;
+ return;
+ }
await dial.restore();
- if (!_authWorkCurrent(revision)) return;
+ if (!_authWorkCurrent(revision)) {
+ _bootStatusMessage = null;
+ return;
+ }
_ensurePool();
try {
await ensureCliDaemonReady();
} catch (error) {
- if (!_authWorkCurrent(revision)) return;
_bootStatusMessage = null;
+ if (!_authWorkCurrent(revision)) return;
status = AppStatus.authenticated;
_lastError = '$error';
_lastErrorRetryable = true;
notifyListeners();
return;
}
- if (!_authWorkCurrent(revision)) return;
_bootStatusMessage = null;
+ if (!_authWorkCurrent(revision)) return;
// `ensureCliDaemonReady` may have signed the app out instead of succeeding (daemon absent AND
// the saved session gone) — that already routed to the login screen, so don't clobber it.
if (status == AppStatus.unauthenticated) return;
@@ -2414,10 +2433,12 @@ class AppNotifier extends ChangeNotifier {
final discovery = _discovery;
final probe = await discovery.ensureRunning();
if (!_authWorkCurrent(revision)) return;
+ _logDaemonProbe(probe);
switch (probe.state) {
case LocalCliProbeState.ready:
_cliEndpoint = probe.endpoint;
_daemonGateFailed = false;
+ _noteBackendOnline(probe.endpoint!.backendOnline);
case LocalCliProbeState.notReady:
_daemonGateFailed = true;
// Running, not ready — most often a daemon fresh from a self-update still shaking hands
@@ -2426,9 +2447,8 @@ class AppNotifier extends ChangeNotifier {
// retrying by itself; the supervisor below picks the app up the moment it gets there.
_startDaemonSupervision(discovery);
throw StateError(
- 'Harness is running${probe.version == null ? '' : ' (v${probe.version})'} but has not '
- 'connected to the backend yet — ${probe.reason}. It usually finishes on its own; '
- 'retry in a moment.',
+ 'Harness is running${probe.version == null ? '' : ' (v${probe.version})'} but is not '
+ 'ready yet — ${probe.reason}. It usually finishes on its own; retry in a moment.',
);
case LocalCliProbeState.down:
_daemonGateFailed = true;
@@ -2449,6 +2469,40 @@ class AppNotifier extends ChangeNotifier {
_startDaemonSupervision(discovery);
}
+ /// One line per probe STATE the gate lands in, never per tick: this gate was silent, and the one
+ /// machine that sat on "Starting local service…" for good had nothing in any log to say why.
+ void _logDaemonProbe(LocalCliProbe probe) {
+ final line = switch (probe.state) {
+ LocalCliProbeState.ready =>
+ 'ready · backend ${probe.endpoint!.backendOnline ? 'online' : 'OFFLINE'}'
+ '${probe.version == null ? '' : ' · v${probe.version}'}',
+ LocalCliProbeState.notReady =>
+ 'not ready · ${probe.reason}${probe.version == null ? '' : ' · v${probe.version}'}',
+ LocalCliProbeState.down => 'down · ${probe.reason}',
+ };
+ if (line == _loggedDaemonState) return;
+ _loggedDaemonState = line;
+ appLog.info('daemon', line);
+ }
+
+ /// The daemon's backend link changed (or was first seen). Coming BACK is the moment the app has
+ /// been waiting for since it booted offline: the machine list (remote tiles, the real row for this
+ /// computer) and the profile can be fetched now, without a click.
+ ///
+ /// [refetch] is false when the caller IS a machine refresh that just observed the flip through
+ /// its own probe — it is already fetching, and a second run beside it would race the same state.
+ void _noteBackendOnline(bool online, {bool refetch = true}) {
+ if (_backendOnline == online) return;
+ final wasOffline = _backendOnline == false;
+ _backendOnline = online;
+ appLog.info('daemon', 'backend ${online ? 'online' : 'offline'}');
+ if (online && wasOffline && status == AppStatus.authenticated) {
+ if (refetch && !machinesRefreshing) unawaited(retryMachines());
+ if (currentUser == null) unawaited(_loadProfile());
+ }
+ notifyListeners();
+ }
+
/// Supervision starts once the daemon is at least ANSWERING — ready or still connecting. It used to
/// wait for ready, out of fear of a concurrent `harness start` from both places; the supervisor
/// no longer spawns while anything answers on the port, so that race is gone, and starting it on
@@ -2459,6 +2513,7 @@ class AppNotifier extends ChangeNotifier {
stillSignedIn: () async => (await cliLogin.checkStatus()).loggedIn,
onSignedOut: () => _signedOutAtRuntime(_signedOutMessage),
onSnapshot: _updateLocalProjectSnapshot,
+ onBackendOnline: _noteBackendOnline,
onReady: (endpoint) {
// Back (or here for the first time). If the app is sitting on the error strip from a boot
// or reload that found the daemon not ready, this is the moment it was waiting for.
@@ -2999,6 +3054,18 @@ class AppNotifier extends ChangeNotifier {
}
void _reportMachineLoadError(Object error, {bool automatic = false}) {
+ // Offline is not an error to shout about: the daemon said it has no backend, this computer's
+ // machine is standing in from the daemon (see _refreshMachines), and the rail already reads
+ // "offline copy". The strip is for a backend that SHOULD be reachable and is not.
+ if (_backendOnline == false) {
+ machinesAreStale = true;
+ // A strip this raised while the backend still looked reachable comes down with it.
+ if (_lastError != null && _lastError == _machineLoadError) {
+ _lastError = null;
+ }
+ _machineLoadError = null;
+ return;
+ }
final message = 'Could not load machines: ${describeApiError(error)}';
// A recovery must not replace a later agent error or redisplay a dismissed strip.
if (!automatic || (_lastError != null && _lastError == _machineLoadError)) {
@@ -3008,6 +3075,43 @@ class AppNotifier extends ChangeNotifier {
_machineLoadError = message;
}
+ /// The machine THIS computer's daemon serves, built from the daemon's own answer
+ /// (`/api/status.machineId`) when the backend could not list it — no cache yet, backend down. Its
+ /// local WS only selects that exact id (`localWsServer` `machine_select`), so nothing else would
+ /// attach. Added, never replaced: a later real list carries the same id and updates the row in
+ /// place through `machineStates.update` above. No-op when the daemon is not ready, reports no id,
+ /// or a row already exists for it.
+ ///
+ /// [listUnavailable] is true on the failure path: the rows are then a stand-in for a list that
+ /// never came, and the rail says so ("offline copy") while the recovery timer keeps asking. A
+ /// fresh list that simply does not name this computer is not stale — marking it so would keep
+ /// the recovery timer polling a backend that has already answered.
+ void _adoptLocalMachineFromDaemon(
+ LocalCliEndpoint? endpoint,
+ String? localComputerId, {
+ required bool listUnavailable,
+ }) {
+ final machineId = endpoint?.machineId;
+ if (endpoint == null || machineId == null) return;
+ if (machineStates.containsKey(machineId)) return;
+ final machine = Machine(
+ machineId: machineId,
+ computerId: localComputerId ?? endpoint.computerId,
+ authMode: MachineAuthMode.remote,
+ name: Platform.localHostname,
+ status: 'online',
+ );
+ machines = [...machines, machine];
+ machineStates[machineId] = MachineState(machine)
+ ..localOnly = true
+ ..nodeOnline = true;
+ if (listUnavailable) machinesAreStale = true;
+ appLog.info(
+ 'daemon',
+ 'no machine list from the backend — this computer stands in from the daemon',
+ );
+ }
+
/// What the loopback probe means for one machine's transport.
///
/// Written once because two callers need the same answer: the refresh loop, and the failure path that
@@ -3072,6 +3176,19 @@ class AppNotifier extends ChangeNotifier {
await localSettled;
if (_authWorkCurrent(revision)) {
final endpoint = probed;
+ // The probe is the freshest word on the backend link — fresher than the supervisor's last
+ // tick — and it decides whether this failure is an outage to report or just "offline".
+ if (endpoint != null) {
+ _noteBackendOnline(endpoint.backendOnline, refetch: false);
+ }
+ // No list and no row for this computer — a first run offline, or a cache the daemon could
+ // not serve. The daemon knows the machine it serves; stand it up from that so the person
+ // can work locally, exactly as if the backend had listed it.
+ _adoptLocalMachineFromDaemon(
+ endpoint,
+ localComputerId,
+ listUnavailable: true,
+ );
for (final state in machineStates.values) {
_applyLocalTransport(state, endpoint, localComputerId);
_connectMachine(state);
@@ -3086,6 +3203,9 @@ class AppNotifier extends ChangeNotifier {
// sign-out or a dispose may still be published.
if (!_authWorkCurrent(revision)) return;
final localEndpoint = probed;
+ if (localEndpoint != null) {
+ _noteBackendOnline(localEndpoint.backendOnline, refetch: false);
+ }
machines = list
.where((machine) => machine.authMode == MachineAuthMode.remote)
.toList();
@@ -3141,6 +3261,22 @@ class AppNotifier extends ChangeNotifier {
unawaited(_applyNodeStatus(state, reportedOnline));
}
}
+ // A list that arrived but does not name this computer (a stale copy from before this computer
+ // was paired, say) still gets the daemon's own row, on the same rule as the failure path.
+ if (localEndpoint != null &&
+ localEndpoint.machineId != null &&
+ !machineStates.containsKey(localEndpoint.machineId)) {
+ _adoptLocalMachineFromDaemon(
+ localEndpoint,
+ localComputerId,
+ listUnavailable: false,
+ );
+ _applyLocalTransport(
+ machineStates[localEndpoint.machineId]!,
+ localEndpoint,
+ localComputerId,
+ );
+ }
if (localEndpoint != null) _updateLocalProjectSnapshot(localEndpoint);
_autoConnectAndLoadMachines();
_sharingDiscoveryTimer ??= Timer.periodic(const Duration(seconds: 15), (
diff --git a/desktop/lib/ws/local_cli_discovery.dart b/desktop/lib/ws/local_cli_discovery.dart
index 30a0287a6..9b2a2879d 100644
--- a/desktop/lib/ws/local_cli_discovery.dart
+++ b/desktop/lib/ws/local_cli_discovery.dart
@@ -19,6 +19,18 @@ class LocalCliEndpoint {
final int protocolVersion;
final int terminalProtocolVersion;
+ /// The machine this daemon serves, as the daemon itself says (`/api/status.machineId`) — the id
+ /// its local WS answers `machine_select` for. Null from a daemon too old to report one.
+ ///
+ /// This is what lets the app stand up "this computer" with no backend: a machine row built from
+ /// it attaches over the loopback exactly like one the backend listed.
+ final String? machineId;
+
+ /// Whether the daemon currently holds its socket to the backend. NOT part of readiness: a daemon
+ /// with no backend still serves every agent on this computer, and that is most of what the app
+ /// does. False means remote machines and the profile are unavailable for now, nothing more.
+ final bool backendOnline;
+
/// Older daemons report local working folders in status before they support
/// project metadata in agent frames. This snapshot never describes a peer.
final Map<String, AgentProject> agentProjects;
@@ -28,6 +40,8 @@ class LocalCliEndpoint {
required this.wsUri,
required this.protocolVersion,
required this.terminalProtocolVersion,
+ this.machineId,
+ this.backendOnline = true,
this.agentProjects = const {},
});
}
@@ -295,11 +309,16 @@ class LocalCliDiscovery {
void Function()? onSignedOut,
void Function(LocalCliEndpoint endpoint)? onReady,
void Function(LocalCliEndpoint endpoint)? onSnapshot,
+ void Function(bool online)? onBackendOnline,
}) {
var backoff = initialBackoff;
var nextSpawnAllowedAt = DateTime.now();
var quietTicks = 0;
var wasReady = false;
+ // The daemon's backend link as last observed. Reported on every CHANGE, including the first
+ // ready probe, so the app learns "offline" at boot and "back" the moment the daemon reconnects —
+ // this tick is the only poll of `/api/status` there is, and it is the right cadence for it.
+ bool? backendOnline;
// A spawn+grace-window cycle can outlast `checkInterval` — without this, an overlapping tick
// would race a second `harness start` before the first cycle's backoff state even lands (the same
// "port already in use" failure mode a second concurrent spawn hits today).
@@ -317,6 +336,11 @@ class LocalCliDiscovery {
onSnapshot?.call(seen.endpoint!);
if (!wasReady) onReady?.call(seen.endpoint!);
wasReady = true;
+ final online = seen.endpoint!.backendOnline;
+ if (online != backendOnline) {
+ backendOnline = online;
+ onBackendOnline?.call(online);
+ }
return;
}
wasReady = false;
@@ -461,18 +485,14 @@ class LocalCliDiscovery {
version: version,
);
}
- // `discoveryReady` is local-only (tmux/agent-process scanning) and can go true well before the
- // daemon has actually connected to the backend — `/api/machines` and friends proxy straight to
- // it, so treating discovery-ready as "ready" raced the handshake and surfaced as a bogus 30s
- // receive-timeout right after boot. `connected` is the daemon's own backend-socket state
- // (missing field ⇒ older CLI ⇒ accepted, same idiom as above).
- if (body['connected'] == false) {
- return LocalCliProbe.notReady(
- 'not connected to the backend yet',
- pid: pid,
- version: version,
- );
- }
+ // `connected` is the daemon's own backend-socket state. It used to gate readiness — so a
+ // computer that could not reach the backend never got past "Starting local service…", with a
+ // daemon, tmux and every agent sitting right there on the loopback. It is reported instead
+ // (`backendOnline`), and the app decides what it cannot do without it. Missing field ⇒ older
+ // CLI ⇒ online, same idiom as `discoveryReady`. The daemon bounds its own backend proxies
+ // (PROXY_BACKEND_TIMEOUT_MS) and serves its cached machine list meanwhile.
+ final backendOnline = body['connected'] != false;
+ final machineId = body['machineId'];
final advertisedComputerId = _normalizeComputerId(body['computerId']);
final advertised = body['localWs'];
if (advertisedComputerId != localComputerId) {
@@ -512,6 +532,10 @@ class LocalCliDiscovery {
.replace(scheme: base.scheme == 'https' ? 'wss' : 'ws'),
protocolVersion: protocolVersion as int,
terminalProtocolVersion: terminalProtocolVersion as int,
+ machineId: machineId is String && machineId.isNotEmpty
+ ? machineId
+ : null,
+ backendOnline: backendOnline,
agentProjects: _localAgentProjects(
body['sessions'],
identity.environment,
diff --git a/desktop/test/cli_login_test.dart b/desktop/test/cli_login_test.dart
index 638440f84..d23fe99c8 100644
--- a/desktop/test/cli_login_test.dart
+++ b/desktop/test/cli_login_test.dart
@@ -140,6 +140,17 @@ void main() {
expect(status.autonomousEnv, 'prod');
});
+ test('reads the CLI\'s offline flag: signed in, backend out of reach', () {
+ final status = CliAuthStatus.fromJson({
+ 'loggedIn': true,
+ 'offline': true,
+ 'machineId': 'm_123',
+ });
+ expect(status.loggedIn, isTrue);
+ expect(status.offline, isTrue);
+ expect(CliAuthStatus.fromJson({'loggedIn': true}).offline, isFalse);
+ });
+
test('parses a logged-out payload with no other fields', () {
final status = CliAuthStatus.fromJson({'loggedIn': false});
expect(status.loggedIn, isFalse);
diff --git a/desktop/test/daemon_readiness_test.dart b/desktop/test/daemon_readiness_test.dart
index ff5e3348f..0fde6d276 100644
--- a/desktop/test/daemon_readiness_test.dart
+++ b/desktop/test/daemon_readiness_test.dart
@@ -19,6 +19,7 @@ class _ScriptedDiscovery extends LocalCliDiscovery {
int superviseCalls = 0;
void Function(LocalCliEndpoint endpoint)? onReady;
void Function(LocalCliEndpoint endpoint)? onSnapshot;
+ void Function(bool online)? onBackendOnline;
@override
Future<LocalCliProbe> ensureRunning({
@@ -42,10 +43,12 @@ class _ScriptedDiscovery extends LocalCliDiscovery {
void Function()? onSignedOut,
void Function(LocalCliEndpoint endpoint)? onReady,
void Function(LocalCliEndpoint endpoint)? onSnapshot,
+ void Function(bool online)? onBackendOnline,
}) {
superviseCalls++;
this.onReady = onReady;
this.onSnapshot = onSnapshot;
+ this.onBackendOnline = onBackendOnline;
return Timer(const Duration(days: 1), () {});
}
}
@@ -165,10 +168,10 @@ void main() {
expect(notifier.refreshes, 0);
});
- test('a daemon that answers but is still connecting is reported as such, and supervised', () async {
+ test('a daemon that answers but is still scanning is reported as such, and supervised', () async {
final discovery = _ScriptedDiscovery([
const LocalCliProbe.notReady(
- 'not connected to the backend yet',
+ 'still scanning for agents',
version: '9.9.9',
),
]);
@@ -183,7 +186,7 @@ void main() {
'message',
allOf(
contains('Harness is running (v9.9.9)'),
- contains('not connected to the backend yet'),
+ contains('still scanning for agents'),
),
),
),
@@ -216,9 +219,47 @@ void main() {
expect(discovery.superviseCalls, 0);
});
+ test(
+ 'a daemon with no backend is READY: this computer works over the loopback',
+ () async {
+ // The case this whole gate used to fail: a daemon up, tmux up, agents up, and no route to the
+ // backend. It sat on "Starting local service…" for 45s and then on an error strip — and every
+ // retry threw the same error. Offline is a fact the daemon reports, not a reason to wait.
+ final offline = LocalCliEndpoint(
+ computerId: _endpoint.computerId,
+ wsUri: _endpoint.wsUri,
+ protocolVersion: 1,
+ terminalProtocolVersion: 3,
+ machineId: 'm' * 32,
+ backendOnline: false,
+ );
+ // Two answers: offline at boot, online for the retry the reconnect triggers.
+ final discovery = _ScriptedDiscovery([
+ LocalCliProbe.ready(offline),
+ LocalCliProbe.ready(_endpoint),
+ ]);
+ final notifier = _Notifier(discovery)..status = AppStatus.authenticated;
+ addTearDown(notifier.dispose);
+
+ await notifier.ensureCliDaemonReady();
+
+ expect(notifier.backendOnline, isFalse);
+ expect(notifier.lastError, isNull);
+ expect(discovery.superviseCalls, 1);
+ expect(discovery.onBackendOnline, isNotNull);
+
+ // The backend comes back (the supervisor's 5s probe sees `connected:true`): the machines are
+ // fetched again without a click, and the profile too if it was never loaded.
+ discovery.onBackendOnline!(true);
+ await notifier.retryMachines();
+ expect(notifier.backendOnline, isTrue);
+ expect(notifier.refreshes, 1);
+ },
+ );
+
test('the supervisor reporting ready after a not-ready boot retries the machines without a click', () async {
final discovery = _ScriptedDiscovery([
- const LocalCliProbe.notReady('not connected to the backend yet'),
+ const LocalCliProbe.notReady('still scanning for agents'),
LocalCliProbe.ready(_endpoint),
]);
final notifier = _Notifier(discovery)..status = AppStatus.authenticated;
@@ -226,10 +267,7 @@ void main() {
// The boot path: the gate throws, the error strip shows, supervision is on.
await notifier.retryMachines();
- expect(
- notifier.lastError,
- contains('has not connected to the backend yet'),
- );
+ expect(notifier.lastError, contains('still scanning for agents'));
expect(notifier.lastErrorRetryable, isTrue);
expect(notifier.refreshes, 0);
expect(discovery.onReady, isNotNull);
diff --git a/desktop/test/harness_cli_runner_test.dart b/desktop/test/harness_cli_runner_test.dart
index ceff56d16..29e956e0c 100644
--- a/desktop/test/harness_cli_runner_test.dart
+++ b/desktop/test/harness_cli_runner_test.dart
@@ -1,3 +1,4 @@
+import 'dart:async';
import 'dart:io';
import 'package:flutter_test/flutter_test.dart';
@@ -79,6 +80,31 @@ void main() {
expect(invocation.arguments, ['start']);
});
+ test('a command that never finishes is an error within the bound, not a wait without end', () async {
+ // A `harness start` that had to reach a black-holed backend hung here, and the app — waiting on
+ // it to say "Starting local service…" was over — hung with it, for good.
+ final home = Directory('${scratch.path}/home')..createSync();
+ final harnessHome = Directory('${home.path}/.harness')..createSync();
+ final runner = HarnessCliRunner(
+ harnessHome: harnessHome,
+ environment: {'HOME': home.path, 'PATH': '/usr/bin'},
+ runTimeout: const Duration(milliseconds: 50),
+ runProcess: (command, argv, {environment}) =>
+ Completer<ProcessResult>().future,
+ );
+
+ await expectLater(
+ runner.run(['start']),
+ throwsA(
+ isA<ProcessException>().having(
+ (e) => e.message,
+ 'message',
+ contains('did not finish'),
+ ),
+ ),
+ );
+ });
+
test('remote-password status invokes cli.js as direct argv and reads its JSON result', () async {
final home = Directory('${scratch.path}/home')..createSync();
final harnessHome = Directory('${home.path}/.harness')..createSync();
diff --git a/desktop/test/local_cli_discovery_test.dart b/desktop/test/local_cli_discovery_test.dart
index 44ef43b6d..a4c46d862 100644
--- a/desktop/test/local_cli_discovery_test.dart
+++ b/desktop/test/local_cli_discovery_test.dart
@@ -325,15 +325,68 @@ void main() {
});
test(
- 'a daemon still connecting to the backend is NOT READY, and says so',
+ 'a daemon with no backend link is READY, and says the backend is offline',
() async {
+ // Readiness is the loopback's: a daemon that cannot reach the backend still serves every
+ // agent on this computer. `connected:false` used to hold the app on "Starting local
+ // service…" for 45s and then an error strip, with tmux and the agents right there.
+ server = await serveStatus(
+ 0,
+ () => readyStatus(
+ computerId,
+ extra: {'connected': false, 'machineId': 'm' * 32},
+ ),
+ );
+ final probe = await discoveryFor(server!.port, identityFile).probe();
+ expect(probe.state, LocalCliProbeState.ready);
+ expect(probe.endpoint!.backendOnline, isFalse);
+ expect(probe.endpoint!.machineId, 'm' * 32);
+ expect(probe.pid, 4242);
+ expect(probe.version, '9.9.9');
+ },
+ );
+
+ test(
+ 'discover() still hands back the endpoint while the backend is down',
+ () async {
+ // `discover()` is what the machine refresh applies to this computer's row. When it returned
+ // null on `connected:false`, `_applyLocalTransport` read that as "the CLI is offline" and put
+ // the LOCAL terminal into localOffline — a daemon that lost its cloud link took the terminal
+ // on the same desk down with it.
server = await serveStatus(
0,
() => readyStatus(computerId, extra: {'connected': false}),
);
+ final endpoint = await discoveryFor(
+ server!.port,
+ identityFile,
+ ).discover(expectedComputerId: computerId);
+ expect(endpoint, isNotNull);
+ expect(endpoint!.backendOnline, isFalse);
+ },
+ );
+
+ test(
+ 'a daemon that reports no `connected` (older CLI) counts as online',
+ () async {
+ server = await serveStatus(0, () => readyStatus(computerId));
+ final probe = await discoveryFor(server!.port, identityFile).probe();
+ expect(probe.state, LocalCliProbeState.ready);
+ expect(probe.endpoint!.backendOnline, isTrue);
+ expect(probe.endpoint!.machineId, isNull);
+ },
+ );
+
+ test(
+ 'a daemon still scanning for agents is NOT READY, and says so',
+ () async {
+ server = await serveStatus(
+ 0,
+ () => readyStatus(computerId, extra: {'discoveryReady': false}),
+ );
final probe = await discoveryFor(server!.port, identityFile).probe();
expect(probe.state, LocalCliProbeState.notReady);
- expect(probe.reason, 'not connected to the backend yet');
+ expect(probe.reason, 'still scanning for agents');
expect(probe.pid, 4242);
expect(probe.version, '9.9.9');
expect(probe.endpoint, isNull);
@@ -396,10 +449,10 @@ void main() {
const computerId = '0123456789abcdef0123456789abcdef';
final identityFile = File('${scratch.path}/computer-id')
..writeAsStringSync(computerId);
- var connected = false;
+ var scanned = false;
server = await serveStatus(
0,
- () => readyStatus(computerId, extra: {'connected': connected}),
+ () => readyStatus(computerId, extra: {'discoveryReady': scanned}),
);
var spawned = false;
final discovery = discoveryFor(
@@ -409,7 +462,7 @@ void main() {
spawned = true;
},
);
- Future.delayed(const Duration(milliseconds: 700), () => connected = true);
+ Future.delayed(const Duration(milliseconds: 700), () => scanned = true);
final probe = await discovery.ensureRunning(
readyTimeout: const Duration(seconds: 5),
);
@@ -423,7 +476,7 @@ void main() {
..writeAsStringSync(computerId);
server = await serveStatus(
0,
- () => readyStatus(computerId, extra: {'connected': false}),
+ () => readyStatus(computerId, extra: {'discoveryReady': false}),
);
var spawned = false;
final probe = await discoveryFor(
@@ -434,7 +487,7 @@ void main() {
},
).ensureRunning(readyTimeout: const Duration(milliseconds: 600));
expect(probe.state, LocalCliProbeState.notReady);
- expect(probe.reason, 'not connected to the backend yet');
+ expect(probe.reason, 'still scanning for agents');
expect(spawned, isFalse);
});
@@ -566,16 +619,42 @@ void main() {
expect(readies.single.computerId, computerId);
});
+ test(
+ 'startSupervising reports the backend link on every change, not every tick',
+ () async {
+ const computerId = '0123456789abcdef0123456789abcdef';
+ final identityFile = File('${scratch.path}/computer-id')
+ ..writeAsStringSync(computerId);
+ var connected = false;
+ server = await serveStatus(
+ 0,
+ () => readyStatus(computerId, extra: {'connected': connected}),
+ );
+ final seen = <bool>[];
+ final timer = discoveryFor(server!.port, identityFile).startSupervising(
+ checkInterval: const Duration(milliseconds: 20),
+ onBackendOnline: seen.add,
+ );
+ addTearDown(timer.cancel);
+
+ await Future.delayed(const Duration(milliseconds: 120));
+ expect(seen, [false], reason: 'offline at first sight, said once');
+ connected = true;
+ await Future.delayed(const Duration(milliseconds: 120));
+ expect(seen, [false, true], reason: 'the reconnect, said once');
+ },
+ );
+
test(
'startSupervising never spawns over a daemon that answers but is not ready',
() async {
const computerId = '0123456789abcdef0123456789abcdef';
final identityFile = File('${scratch.path}/computer-id')
..writeAsStringSync(computerId);
- // The state a daemon sits in for the length of every self-update's backend handshake.
+ // The state a daemon sits in for the length of its startup scan.
server = await serveStatus(
0,
- () => readyStatus(computerId, extra: {'connected': false}),
+ () => readyStatus(computerId, extra: {'discoveryReady': false}),
);
var spawnCount = 0;
final discovery = discoveryFor(
diff --git a/desktop/test/machine_list_outage_test.dart b/desktop/test/machine_list_outage_test.dart
index 3d146047c..5874dfb08 100644
--- a/desktop/test/machine_list_outage_test.dart
+++ b/desktop/test/machine_list_outage_test.dart
@@ -52,6 +52,10 @@ class _Cli extends CliLogin {
/// A daemon that is up and answering on loopback, whatever the cloud is doing.
class _Discovery extends LocalCliDiscovery {
_Discovery() : super(config: AppConfig.dev);
+
+ /// What the daemon says about its own backend link. The real probe reads `/api/status.connected`.
+ bool backendOnline = true;
+
@override
Future<String?> computerId() async => _computerId;
@override
@@ -61,6 +65,8 @@ class _Discovery extends LocalCliDiscovery {
wsUri: Uri.parse('ws://127.0.0.1:18473/ws'),
protocolVersion: localWsProtocolVersion,
terminalProtocolVersion: 1,
+ machineId: 'local-machine',
+ backendOnline: backendOnline,
);
}
@@ -86,16 +92,17 @@ class _Connection extends WsConn {
}
class _App extends AppNotifier {
- _App(_Api api, _Connection connection)
+ _App(_Api api, _Connection connection, this.discovery)
: super(
config: AppConfig.dev,
authSession: AuthSession(),
cliLogin: _Cli(),
- localCliDiscovery: _Discovery(),
+ localCliDiscovery: discovery,
connectionForTest: (_) => connection,
) {
this.api = api;
}
+ final _Discovery discovery;
@override
Future<void> ensureCliDaemonReady() async {}
}
@@ -120,7 +127,7 @@ void main() {
setUp(() {
disposedEarly = false;
api = _Api();
- app = _App(api, _Connection());
+ app = _App(api, _Connection(), _Discovery());
app.status = AppStatus.authenticated;
// The state a running session is in: this computer's machine, already known to be local.
app.machines = [_localMachine];
@@ -132,9 +139,34 @@ void main() {
if (!disposedEarly) app.dispose();
});
+ test('a failed machine list still applies the loopback endpoint to the local machine', () async {
+ final refresh = app.refreshMachines();
+ await _tick();
+ api.lists.single.completeError(
+ ApiException('Could not reach the Harness backend', status: 502),
+ );
+ await expectLater(refresh, throwsA(isA<ApiException>()));
+ await _tick();
+
+ final local = app.machineStates['local-machine']!;
+ // The probe answered, so this machine can still be reached over loopback — which is exactly what
+ // `_connectMachine` gates the local machine on.
+ expect(local.localEndpoint, isNotNull);
+ expect(local.usesLocalTransport, isTrue);
+ expect(local.transportMode, isNot(MachineTransportMode.cloudE2ee));
+ });
+
test(
- 'a failed machine list still applies the loopback endpoint to the local machine',
+ 'the daemon losing its cloud link leaves the local terminal alone',
() async {
+ // The exact report: "cloud reconnecting…" on the daemon, and the desktop's LOCAL terminal went
+ // offline too. The 15s list refresh failed, and the loopback probe — which used to refuse a
+ // daemon with no backend — handed back nothing, so this computer's row was marked offline.
+ app.discovery.backendOnline = false;
+ final local = app.machineStates['local-machine']!
+ ..connectionStatus = ConnectionStatus.connected
+ ..nodeOnline = true;
+
final refresh = app.refreshMachines();
await _tick();
api.lists.single.completeError(
@@ -143,12 +175,11 @@ void main() {
await expectLater(refresh, throwsA(isA<ApiException>()));
await _tick();
- final local = app.machineStates['local-machine']!;
- // The probe answered, so this machine can still be reached over loopback — which is exactly what
- // `_connectMachine` gates the local machine on.
+ expect(app.backendOnline, isFalse);
expect(local.localEndpoint, isNotNull);
- expect(local.usesLocalTransport, isTrue);
- expect(local.transportMode, isNot(MachineTransportMode.cloudE2ee));
+ expect(local.transportMode, MachineTransportMode.localPlaintext);
+ expect(local.nodeOnline, isTrue, reason: 'the daemon is right here');
+ expect(app.machineListError, isNull);
},
);
@@ -166,34 +197,88 @@ void main() {
expect(app.lastErrorRetryable, isTrue);
});
- test('a successful list still resolves the local endpoint as before', () async {
- final refresh = app.refreshMachines();
- await _tick();
- api.lists.single.complete([_localMachine]);
- await refresh;
- await _tick();
+ test(
+ 'a successful list still resolves the local endpoint as before',
+ () async {
+ final refresh = app.refreshMachines();
+ await _tick();
+ api.lists.single.complete([_localMachine]);
+ await refresh;
+ await _tick();
- final local = app.machineStates['local-machine']!;
- expect(local.localOnly, isTrue);
- expect(local.localEndpoint, isNotNull);
- expect(app.machineListError, isNull);
- });
+ final local = app.machineStates['local-machine']!;
+ expect(local.localOnly, isTrue);
+ expect(local.localEndpoint, isNotNull);
+ expect(app.machineListError, isNull);
+ },
+ );
+
+ test(
+ 'a cached answer is not the end of the job: it keeps recovering',
+ () async {
+ // The daemon answers 200 from its own cache when the backend is unreachable. Treating that as a
+ // clean success would stop the retry and leave the app on stale rows until somebody pressed reload.
+ api.nextIsStale = true;
+ final retry = app.retryMachines();
+ await _tick();
+ api.lists.single.complete([_localMachine]);
+ await retry;
+ await _tick();
+
+ expect(app.machinesAreStale, isTrue);
+ expect(app.machines, isNotEmpty); // usable rows, so no blocking error
+ expect(app.machineListError, isNull);
+ // Still trying: a timer is armed, which is what converges once the backend returns.
+ expect(app.machineRecoveryPending, isTrue);
+
+ app.dispose();
+ disposedEarly = true;
+ },
+ );
+
+ test('offline with nothing cached: this computer stands in from the daemon, quietly', () async {
+ // The first run on a computer that cannot reach the backend — no cache for the daemon to serve,
+ // so the list is a plain 502 — and the state the app knows nothing yet. The daemon knows the one
+ // machine it serves; that is enough to work locally, and it is not an error to shout about.
+ app.machines = [];
+ app.machineStates.clear();
+ app.discovery.backendOnline = false;
- test('a cached answer is not the end of the job: it keeps recovering', () async {
- // The daemon answers 200 from its own cache when the backend is unreachable. Treating that as a
- // clean success would stop the retry and leave the app on stale rows until somebody pressed reload.
- api.nextIsStale = true;
final retry = app.retryMachines();
await _tick();
- api.lists.single.complete([_localMachine]);
+ api.lists.single.completeError(
+ ApiException('Could not reach the Harness backend', status: 502),
+ );
await retry;
await _tick();
- expect(app.machinesAreStale, isTrue);
- expect(app.machines, isNotEmpty); // usable rows, so no blocking error
- expect(app.machineListError, isNull);
- // Still trying: a timer is armed, which is what converges once the backend returns.
- expect(app.machineRecoveryPending, isTrue);
+ expect(app.backendOnline, isFalse);
+ final local = app.machineStates['local-machine'];
+ expect(local, isNotNull, reason: 'built from /api/status.machineId');
+ expect(local!.localOnly, isTrue);
+ expect(local.usesLocalTransport, isTrue);
+ expect(local.transportMode, isNot(MachineTransportMode.cloudE2ee));
+ expect(app.machines.map((m) => m.machineId), ['local-machine']);
+ expect(
+ app.machinesAreStale,
+ isTrue,
+ reason: 'the rail says "offline copy"',
+ );
+ expect(app.machineListError, isNull, reason: 'offline is not an outage');
+ expect(app.lastError, isNull);
+
+ // The backend is back and lists the real row: same id, so it updates in place — one machine,
+ // still local, now with the backend's name.
+ app.discovery.backendOnline = true;
+ final again = app.retryMachines();
+ await _tick();
+ api.lists.last.complete([_localMachine]);
+ await again;
+ await _tick();
+
+ expect(app.machines.map((m) => m.name), ['This computer']);
+ expect(app.machineStates['local-machine']!.localOnly, isTrue);
+ expect(app.machinesAreStale, isFalse);
app.dispose();
disposedEarly = true;