The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
Merge origin/main into feat/grid-scale-phase-a
Kelvin30a7248c6f80
diff --cc cli/src/backendSocket.gridReads.spec.tsindex ef559098e,000000000..ce6f5a0e7mode 100644,000000..100644--- a/cli/src/backendSocket.gridReads.spec.ts+++ b/cli/src/backendSocket.gridReads.spec.ts@@@ -1,155 -1,0 +1,160 @@@+/**+ * The daemon's grid RPCs as a desktop drives them — `grid_models_list`, the Model Manager's+ * `grid_fleet_models_list` and `agent_retarget` — against a fake relay that records every request it+ * receives, and a fake `grid` first on PATH (grid-reads-without-waking issue 02).+ *+ * The relay is the spy: nothing here recomputes what the daemon sends, it reads what arrived.+ */+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'+import { createServer, type IncomingHttpHeaders, type Server } from 'node:http'+import { tmpdir } from 'node:os'+import { join } from 'node:path'+import { BackendSocket } from './backendSocket.js'+import { env } from './config/env.js'+import { fakeGridAnswers, installFakeGrid, type FakeGrid, type FakeGridPlan } from './lib/__fixtures__/fakeGrid.js'+import { clearGridMcpUrlCache } from './lib/gridMcpUrl.js'+import { resetGridModels, type GridModelsService } from './lib/gridModels.js'++const OWN = 'mine', OWN_ID = 'net-own'+const OVERVIEW = '/relay/v1/grid/overview'++let server: Server, base: string, seen: Array<{ path: string; headers: IncomingHttpHeaders }>+let overview: { status: number; body: unknown }+let root: string, gridHome: string, previousData: string, grid: FakeGrid, service: GridModelsService, clock: number+let socket: BackendSocket, frames: Array<{ type: string; payload: Record<string, unknown> }>++function plan(status: string | null = 'running'): FakeGridPlan {+ return {+ ls: { stdout: JSON.stringify([{ grid: OWN, id: OWN_ID, type: 'permissioned-public' }]) },+ [`info ${OWN}`]: { stdout: JSON.stringify({ grid: OWN, status, grid_url: `${base}/g/${OWN_ID}` }) },+ }+}++async function ask(type: string, payload: Record<string, unknown> = {}): Promise<Record<string, unknown>> {+ const requestId = `${type}-${frames.length}`+ socket.handleLocalFrame('local:grid-reads', { type, payload: { ...payload, requestId } })+ await vi.waitFor(() => expect(frames.some((f) => f.payload.requestId === requestId)).toBe(true), { timeout: 10_000 })+ return frames.find((f) => f.payload.requestId === requestId)!.payload+}++function expectNoCredential(): void {+ for (const request of seen) {+ expect(request.headers.authorization).toBeUndefined()+ expect(request.headers['x-api-key']).toBeUndefined()+ }+}++beforeEach(async () => {+ seen = []+ overview = { status: 200, body: { nodes: [{ name: 'mac', engine: 'llama.cpp', models: ['small-q4'], online: true }], models: [{ id: 'Small-Q4' }] } }+ server = createServer((req, res) => {+ seen.push({ path: req.url ?? '', headers: req.headers })+ const found = req.url === `/g/${OWN_ID}${OVERVIEW}` ? overview : { status: 404, body: {} }+ res.writeHead(found.status, { 'content-type': 'application/json' })+ res.end(JSON.stringify(found.body))+ })+ await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve))+ base = `http://127.0.0.1:${(server.address() as { port: number }).port}`+ root = mkdtempSync(join(tmpdir(), 'grid-reads-rpc-'))+ gridHome = join(root, 'grid-home')+ mkdirSync(gridHome, { recursive: true })+ vi.stubEnv('GRID_HOME', gridHome)+ previousData = env.ADAPTER_DATA_DIR+ env.ADAPTER_DATA_DIR = join(root, 'data')+ clock = Date.parse('2026-09-24T10:00:00Z')+ // Before the socket, which subscribes to the service it finds for its `grid_models_changed` push.+ service = resetGridModels({ now: () => clock, dataDir: () => join(root, 'data'), gridHome: () => gridHome, email: () => null })+ grid = installFakeGrid(plan())+ socket = new BackendSocket('token')+ socket.setHarnessGridName(OWN)+ frames = []+ socket.registerLocalClient('local:grid-reads', { sendFrame: (frame) => { frames.push(frame as typeof frames[number]); return true }, sendBinary: () => true })+})++afterEach(async () => {+ await service.settled()+ await socket.unregisterLocalClient('local:grid-reads')+ await socket.stop()+ grid.dispose()+ clearGridMcpUrlCache()+ env.ADAPTER_DATA_DIR = previousData+ vi.unstubAllEnvs()+ server.closeAllConnections()+ await new Promise<void>((resolve) => server.close(() => resolve()))+ rmSync(root, { recursive: true, force: true })+})++describe('grid_models_list', () => {+ it('answers in the old shape with the three new fields, and reads the grid with no credential', async () => {+ const reply = await ask('grid_models_list')++ expect(reply).toMatchObject({ gridName: OWN, models: [{ id: 'Small-Q4', node: 'mac' }] })+ expect(reply.grids).toEqual([{+ name: OWN, type: 'permissioned-public', own: true, models: [{ id: 'Small-Q4', node: 'mac' }],+ state: 'awake', seenAt: new Date(clock).toISOString(), lastKnownAge: 0,+ }])+ expect(seen.map((r) => r.path)).toEqual([`/g/${OWN_ID}${OVERVIEW}`])+ expectNoCredential()+ })++ it('pushes grid_models_changed when a read it did not wait for changes the list', async () => {+ await ask('grid_models_list')+ clock += 20_000+ overview = { status: 200, body: { nodes: [{ name: 'mac', engine: 'llama.cpp', models: ['small-q4', 'big-q8'] }], models: [] } }++ const reply = await ask('grid_models_list')+ // Answered at once from the picture; the read it started lands behind it and is pushed.+ expect((reply.models as unknown[]).length).toBe(1)+ await vi.waitFor(() => expect(frames.some((f) => f.type === 'grid_models_changed')).toBe(true), { timeout: 5_000 })++ const pushed = frames.find((f) => f.type === 'grid_models_changed')!.payload+ expect(pushed).not.toHaveProperty('requestId')+ expect(pushed).toMatchObject({ gridName: OWN, models: [{ id: 'Small-Q4', node: 'mac' }, { id: 'big-q8', node: 'mac' }], supportsModelLaunch: true })+ // Two overview reads, and one of provider discovery: `big-q8` had no spelling from any other source.+ expect(seen.map((r) => r.path)).toEqual([`/g/${OWN_ID}${OVERVIEW}`, `/g/${OWN_ID}${OVERVIEW}`, `/g/${OWN_ID}/nodes/discover`])+ expectNoCredential()+ })+})++describe('grid_fleet_models_list (the Model Manager) on a sleeping own grid', () => {+ it('is not an inventory error, keeps Start and Pause enabled, and reports a parked engine running', async () => {+ grid.replan(plan('asleep'))+ overview = { status: 503, body: { detail: 'resting', code: 'grid_asleep' } }+ const records = join(gridHome, 'run', 'engines', OWN_ID)+ mkdirSync(records, { recursive: true })+ writeFileSync(join(records, 'remote.json'), JSON.stringify({+ node_id: 'node-1', meta_name: 'mac', pid: process.pid, engines: [{ endpoint_url: null, models: ['Small-Q4.gguf'] }], advertise_as: [],+ }))++ const reply = await ask('grid_fleet_models_list', { refresh: true })++ expect(reply.error).not.toBe('Running models could not be checked. Try again.')+ expect(reply.models).toEqual([expect.objectContaining({ id: 'local:Small-Q4.gguf', state: 'running', gridAsleep: true, canStop: true })])+ expect(seen.map((r) => r.path)).toEqual([`/g/${OWN_ID}${OVERVIEW}`])+ expectNoCredential()+ // The owner status is asked once and remembered, not asked on every tick.+ await ask('grid_fleet_models_list', { refresh: true })+ await ask('grid_fleet_models_list', { refresh: true })+ expect(grid.calls().filter((argv) => argv.includes('info'))).toHaveLength(1)+ expect(grid.calls().some((argv) => argv.includes('engines'))).toBe(false)+ })+})++describe('agent_retarget', () => {- it('moves an agent onto a grid model without reading the grid at all', async () => {++ it('reads nothing on its own: the one request is the model lookup of the move a person made', async () => {+ const answers = fakeGridAnswers()- grid.replan(answers.plan)++ // The relay the grid's `info --env` names is this test's, so nothing here can reach a real host.++ const relay = `${base}/g/${OWN_ID}/relay/v1`++ grid.replan({ ...answers.plan, info: { stdout: `export OPENAI_BASE_URL="${relay}"\nexport OPENAI_API_KEY="${answers.token}"\n` } })+ socket.onRetargetAgent = vi.fn(async () => ({ ok: true as const }))++ const reply = await ask('agent_retarget', { agentId: 'agent-1', gridModel: 'GLM-4.7-Flash', gridName: answers.gridName })++ expect(reply).toMatchObject({ retargeted: true })- expect(seen).toEqual([])++ // Moving an agent onto a model is a person's act, which may wake the grid (and is meant to: the++ // pane is about to use it). What must not happen is any read on the app's own schedule.++ expect(seen.map((r) => r.path)).toEqual([`/g/${OWN_ID}/relay/v1/models`])++ expect(seen.some((r) => r.path.endsWith('/grid/overview') || r.path.endsWith('/nodes/discover'))).toBe(false)+ })+})diff --cc cli/src/backendSocket.tsindex ca6b3288a,b8c32b1ee..ecd505207--- a/cli/src/backendSocket.ts+++ b/cli/src/backendSocket.ts@@@ -365,42 -365,15 +365,46 @@@ async function enrichSubagentStats(even}}+/** What `grid_models_list` answers and `grid_models_changed` pushes — one shape, so a window parses both+ * with one reader. `gridName` and `models` keep naming the own grid alone, for an app that predates+ * `grids`; each section's `state`, `seenAt` and `lastKnownAge` are additive. */+function gridModelsPayload(gridName: string | null, grids: GridSection[]): Record<string, unknown> {+ return {+ 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(),+ supportsModelLaunch: true,+ // 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(),+ }+}+export class BackendSocket {private readonly gridFleet = new GridFleetRpc()+ // The Model Manager reads the grid it runs on through the same credential-less reader as every picker+ // (never `grid engines`, which carries the grid credential and so wakes a sleeping grid on every tick),+ // and a start or stop it finishes makes every list read again — pushed to the window when it changes.private readonly localModels = new LocalModels({stateDir: join(env.ADAPTER_DATA_DIR, 'local-models'),+ machineName: () => this.machineDisplayName,+ inventory: gridInventory,+ onChanged: () => { forgetGridModels(); void this.pushGridModels() },})+ /** This machine's name as Harness shows it (Machines), from the backend's `machine_meta`. Null+ * until the first one arrives. */+ private machineDisplayName: string | null = null+ /** A read the window did not ask for changed what a picker would show: tell the window+ * (`grid_models_changed`), so its one picture stays current without polling. */+ private readonly stopGridModelsPush = onGridModelsChanged(() => { void this.pushGridModels() })private readonly apiConnections = new ApiConnections(env.ADAPTER_DATA_DIR)private ws: WebSocket | null = nullprivate connecting = falsediff --cc cli/src/lib/gridModels.tsindex c280d289f,8449a852a..3e4b52bab--- a/cli/src/lib/gridModels.ts+++ b/cli/src/lib/gridModels.ts@@@ -1,40 -1,24 +1,41 @@@/**- * What the account's private harness grid can answer right now.+ * What the grids this computer is signed into can answer — read WITHOUT waking any of them.*- * One `grid models --json <grid>` away, so this module is a shape and a filter rather than a- * protocol. It exists because two things have to be decided in one place: which rows are offered to- * a person, and what an agent is told to ask for.+ * Every picker, the Models panel and the macOS Models menu ask here, and until issue 02 of+ * grid-reads-without-waking each ask was a `grid models` spawn plus a SIGNED-IN read of the relay's+ * model list. On the platform a signed-in read of a sleeping grid wakes it, so an open app kept every+ * grid of the account awake all day — and the read that woke one usually came back empty. Now:+ *+ * - each grid is read through `gridReader.ts`, with no credential: an awake grid answers as before, a+ * sleeping one says so at once (with the platform's record of what it served) and is not started;+ * - what was read is kept as a PICTURE per grid (`gridPicture.ts`, persisted), so an answer is given at+ * once and a sleeping grid shows its last known models instead of vanishing;+ * - the account's OWN grid, whose status the owner can read, is read at most once per asleep episode.+ *+ * The credentialed model-list read is gone from every automatic path. What still wakes a grid is a+ * person's act, and it does not go through here.*/+import { createHash, randomUUID } from 'node:crypto'+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'+import { dirname, join } from 'node:path'+import { env as config } from '../config/env.js'+import { gridCredentialsPath } from './gridCredentials.js'+import { signedInGridEmail } from './gridDerive.js'import { gridExec, gridJson } from './gridExec.js'+ import { contextWindowHint } from './gridLaunch.js'import { resolveGridMcpUrl } from './gridMcpUrl.js'--/** A row of `grid models --json`. `node` names the machine serving it — on a private grid, one of- * the user's own. */-interface GridModelRow {- model?: unknown- engine?: unknown- node?: unknown-}+import {+ emptyPicture, mergeAwake, idKey, parsePicture, provenStopped, sectionView, servedKey, unspelled, withAsleep,+ withSpellings, withUnknown, type GridPicture, type LocalRecord, type PictureState, type SectionView, type ServedHere,+} from './gridPicture.js'+import {+ OWNER_ASLEEP_STATUS, readBase, readDiscoveryIds, readGridInfo, readOverview, readViaCli, type GridInfo, type GridRead,+ type ReadNode,+} from './gridReader.js'+import { readRunRecords } from './localModels.js'export interface GridModel {- /** The id an engine is pointed at, verbatim from the grid. */+ /** The id an engine is pointed at, in the exact case the grid serves it. */id: string/** Which machine answers it, or empty when the grid does not say. Display only. */node: string@@@ -48,409 -92,98 +49,443 @@@ export interface GridSectiontype: string/** True for the account's private grid — the picker labels that one "Local". */own: boolean+ /** Its models: live while it is awake, the last known ones while it is not — never blanked. */models: GridModel[]+ /** Additive (an older app ignores these three): what the last read said, when the grid was last seen+ * awake, and how old the list above is. */+ state?: PictureState+ seenAt?: string | null+ lastKnownAge?: number | null}-/**- * Every grid this computer is signed into, each with its live models, own grid first.- *- * The picker used to ask only the private grid ("models my machines serve"). A person in a- * shared grid (a team's, a company's) has models there they can switch an agent to just the- * same, and had to leave the app to find out. So all of them, in sections, the private one first- * and marked so the app can call it Local. Listed concurrently: each grid costs a `grid models`- * spawn and a relay round trip, and three of them one after another was the whole of what a- * person waited through. A grid that fails to answer is an empty section, not a missing one.- */-export async function listAllGridModels(ownGridName: string | null): Promise<GridSection[]> {- const { value: rows } = await gridJson<Array<{ grid?: unknown; type?: unknown }>>(['--remote', 'ls'])- if (!Array.isArray(rows)) {- return ownGridName ? [{ name: ownGridName, type: 'permissioned-public', own: true, models: await listGridModels(ownGridName) }] : []- }- const grids = rows- .filter((row): row is { grid: string; type?: unknown } => typeof row.grid === 'string' && row.grid.trim().length > 0)- .map((row) => ({ name: row.grid.trim(), type: typeof row.type === 'string' ? row.type : '' }))- const sections = await Promise.all(grids.map(async (grid) => ({- name: grid.name,- type: grid.type,- own: grid.name === ownGridName,- models: await listGridModels(grid.name),- })))- sections.sort((a, b) => Number(b.own) - Number(a.own))- return sections+/** What the Model Manager is told about the grid it runs on (`localModels.ts`'s `GridInventory`). */+export interface GridInventoryAnswer {+ state: PictureState+ nodes: Record<string, unknown>[]++ /** The owner status as last read (memoised, never asked per tick); null when it could not be read. */++ status: string | null+}++/** How long one read's answer stands before the next is made: the list is live while a grid is awake,+ * and a sleeping grid changes only when something wakes it. A failure is retried sooner than sleep. */+const AWAKE_MEMO_MS = 15_000+const ASLEEP_MEMO_MS = 120_000+const FAILED_MEMO_MS = 30_000++/** `grid info` is a control-plane call: a member's grid address barely moves; the OWNER's status is the+ * thing that says a grid fell asleep or woke, so it is asked more often, and less often while asleep. */+const ADDRESS_MEMO_MS = 10 * 60_000+const OWN_STATUS_AWAKE_MEMO_MS = 15_000+const OWN_STATUS_ASLEEP_MEMO_MS = 60_000++/** Several changes landing together (three grids refreshed at once) are one push, not three. */+const CHANGE_COALESCE_MS = 250++/** How long an ask waits for the FIRST read of a grid this daemon has never seen before answering with+ * what it has. Kept well inside the app's 12s `grid_models_list` timeout, which the grid-name wait+ * (`GRID_ATTACH_WAIT_MS`, 6s) shares: a read slower than this lands behind the answer and is pushed. */+const FIRST_READ_WAIT_MS = 4_000++interface GridRow { name: string; type: string; id: string }++/** The key a grid is tracked under when `grid ls` gave it no network id — its name, marked as such, so+ * it can never collide with an id and never names a run-record directory. */+const NAME_ONLY_PREFIX = 'name:'+const nameOnlyRow = (name: string, type = ''): GridRow => ({ name, type, id: `${NAME_ONLY_PREFIX}${name}` })++/** Everything this daemon holds about one grid, keyed by its network id. */+interface Tracked {+ id: string+ /** The name `grid` knows it by — what goes into `grid info <name>` and the fallback's argv. */+ name: string+ /** The account's own grid. A property of the GRID, learnt from whoever last knew (the model list,+ * the Model Manager), so an asker that does not know — a launch check — never changes how it is read. */+ own: boolean+ picture: GridPicture+ loaded: boolean+ /** Whether a picture existed before this process read anything (on disk, or read since). */+ known: boolean+ /** The picture as last written, so a read that changed nothing writes nothing. */+ saved: string+ readAt: number | null+ readTtl: number+ info: { at: number; value: GridInfo | null } | null+ /** The own grid's one read of its current asleep episode has been made. */+ episodeRead: boolean+ /** What this daemon has watched a live run record serve here since the last awake read. */+ seen: Set<string>+ /** Ids discovery has already been asked to spell, so an id no provider spells is asked about once. */+ spelled: Set<string>+ /** The last awake overview's own node objects, for the Model Manager. Not persisted. */+ rawNodes: Record<string, unknown>[]+ pending: Promise<void> | null+}++export interface GridModelsDeps {+ now: () => number+ /** Where pictures are kept (`<data dir>/grid-pictures`). */+ dataDir: () => string+ /** `~/.grid`, whose `run/engines/<grid id>/` holds this computer's run records. */+ gridHome: () => string+ /** The signed-in account — a node published under it is the account's own. */+ email: () => string | null+ /** [FIRST_READ_WAIT_MS], injectable so a test need not wait it out. */+ firstReadWaitMs: number+}++const defaultDeps: GridModelsDeps = {+ now: () => Date.now(),+ dataDir: () => config.ADAPTER_DATA_DIR,+ gridHome: () => dirname(gridCredentialsPath()),+ email: () => signedInGridEmail(),+ firstReadWaitMs: FIRST_READ_WAIT_MS,}/**- * The last answer for a grid, for a few seconds.- *- * The picker asks on every open, and the answer costs two subprocess spawns and two network round- * trips — measured at ~1.4s, which is a person watching a header do nothing after a click. Reopening- * a menu twice in a row should not pay that twice.+ * The pictures, the reads that keep them current, and the answers built from them.*- * Short on purpose. The list is genuinely live — an engine can join or leave between two opens — so- * this is only the window in which a click is free, not a cache in the sense of holding state. Longer- * would start offering models nobody is serving, which is the failure the no-caching rule existed to- * avoid.+ * Nothing here runs on a timer: a grid is read only when something asks about it and its last answer+ * has aged past its memo. So an app nobody looks at costs nothing, and an app somebody looks at costs a+ * credential-less read every 15s at most per grid — and never a wake.*/-const TTL_MS = 15_000-const memo = new Map<string, { at: number; models: GridModel[] }>()+export class GridModelsService {+ private readonly deps: GridModelsDeps+ private readonly tracked = new Map<string, Tracked>()+ private readonly listeners = new Set<() => void>()+ private rows: GridRow[] | null = null+ private changeTimer: NodeJS.Timeout | null = null++ constructor(deps: Partial<GridModelsDeps> = {}) {+ this.deps = { ...defaultDeps, ...deps }+ }++ /** Called (coalesced) whenever a read changed what a picker would be told. */+ onChange(listener: () => void): () => void {+ this.listeners.add(listener)+ return () => { this.listeners.delete(listener) }+ }++ /** Resolves once every read already started has landed — for a test, and for a caller that must see+ * the answer a read it triggered produced. */+ async settled(): Promise<void> {+ await Promise.all([...this.tracked.values()].map((tracked) => tracked.pending?.catch(() => {})))+ }++ /** Every read is due again — for a caller that has just changed what a grid serves, or which grid is+ * whose. The pictures stay: they are what is shown until the next read lands. */+ forget(): void {+ for (const tracked of this.tracked.values()) {+ tracked.readAt = null+ tracked.info = null+ }+ this.rows = null+ }++ /**+ * Every grid this computer is signed into, own grid first, each with its models.+ *+ * Answered from the pictures at once. A grid whose answer has aged is read again in the background —+ * one read per grid at a time — and a change is announced through [onChange]. Only a grid this daemon+ * has never seen is waited for, and only for [FIRST_READ_WAIT_MS]: an answer made of nothing is worse+ * than a short wait, and a timed-out ask is worse than both.+ */+ async sections(ownGridName: string | null, opts: { refresh?: boolean } = {}): Promise<GridSection[]> {+ const rows = await this.gridRows(ownGridName)+ const sections = await Promise.all(rows.map(async (row) => {+ const tracked = await this.track(row, row.name === ownGridName)+ if (opts.refresh !== false && this.due(tracked)) {+ const refreshing = this.refresh(tracked)+ if (!tracked.known) await this.within(refreshing, this.deps.firstReadWaitMs)+ else void refreshing.catch(() => {})+ }+ return { name: row.name, type: row.type, own: tracked.own, ...await this.view(tracked) }+ }))+ sections.sort((a, b) => Number(b.own) - Number(a.own))+ return sections+ }++ /** One grid's models, read now if its answer has aged — for a launch that must not start on a model+ * nobody serves. Still never a waking read: a sleeping grid answers with what it last served. */+ async models(gridName: string): Promise<GridModel[]> {+ const tracked = await this.track(await this.rowFor(gridName))+ if (this.due(tracked)) await this.refresh(tracked)+ return (await this.view(tracked)).models+ }++ /** What the Model Manager needs to tell a running model from a stopped one, on the account's own grid. */+ async inventory(gridName: string, force: boolean): Promise<GridInventoryAnswer> {+ const tracked = await this.track(await this.rowFor(gridName), true)+ if (force) tracked.readAt = null+ if (this.due(tracked)) await this.refresh(tracked)- return { state: tracked.picture.state, nodes: tracked.picture.state === 'awake' ? tracked.rawNodes : [] }++ return {++ state: tracked.picture.state,++ nodes: tracked.picture.state === 'awake' ? tracked.rawNodes : [],++ status: tracked.info?.value?.status ?? null,++ }+ }-function cached(gridName: string): GridModel[] | null {- const hit = memo.get(gridName)- return hit && Date.now() - hit.at < TTL_MS ? hit.models : null+ private async rowFor(gridName: string): Promise<GridRow> {+ return (await this.gridRows(null)).find((row) => row.name === gridName) ?? nameOnlyRow(gridName)+ }++ /** `grid ls --json` — a LOCAL registry read, no network. The last good answer stands in for a failed+ * one; with none, the own grid alone, as before this module knew about shared grids. */+ private async gridRows(ownGridName: string | null): Promise<GridRow[]> {+ const { value } = await gridJson<Array<{ grid?: unknown; type?: unknown; id?: unknown }>>(['--remote', 'ls'])+ if (Array.isArray(value)) {+ this.rows = value+ // A name goes into a `grid` argv (`info <grid>`, the fallback's `models <grid>`): one that reads+ // as a flag, or carries a control character, is not one this daemon will pass along.+ .filter((row) => typeof row?.grid === 'string' && /^[^-\x00-\x1f\x7f][^\x00-\x1f\x7f]*$/.test(row.grid.trim()))+ .map((row) => {+ const name = (row.grid as string).trim()+ const type = typeof row.type === 'string' ? row.type : ''+ return typeof row.id === 'string' && row.id.trim() ? { name, type, id: row.id.trim() } : nameOnlyRow(name, type)+ })+ }+ if (this.rows) return this.rows+ return ownGridName ? [nameOnlyRow(ownGridName, 'permissioned-public')] : []+ }++ /** The grid behind `row`, loaded from disk the first time. `own`, when the caller knows it, is recorded. */+ private async track(row: GridRow, own?: boolean): Promise<Tracked> {+ let tracked = this.tracked.get(row.id)+ if (!tracked) {+ tracked = {+ id: row.id, name: row.name, own: false, picture: emptyPicture(), loaded: false, known: false, saved: '',+ readAt: null, readTtl: 0, info: null, episodeRead: false, seen: new Set(), spelled: new Set(), rawNodes: [],+ pending: null,+ }+ this.tracked.set(row.id, tracked)+ }+ tracked.name = row.name+ if (own !== undefined) tracked.own = own+ if (!tracked.loaded) {+ tracked.loaded = true+ await this.load(tracked)+ }+ return tracked+ }++ /** `work`, or nothing more than `ms` of it — what it produces meanwhile lands on its own. */+ private async within(work: Promise<void>, ms: number): Promise<void> {+ let timer: NodeJS.Timeout | undefined+ await Promise.race([work.catch(() => {}), new Promise<void>((resolve) => { timer = setTimeout(resolve, ms) })])+ clearTimeout(timer)+ }++ private due(tracked: Tracked): boolean {+ const now = this.deps.now()+ if (tracked.readAt === null || now - tracked.readAt >= tracked.readTtl) return true+ // The owner's status is what says the own grid fell asleep or woke; it is checked on its own clock.+ return tracked.own && (tracked.info === null || now - tracked.info.at >= this.statusTtl(tracked))+ }++ private statusTtl(tracked: Tracked): number {+ if (!tracked.own) return ADDRESS_MEMO_MS+ return tracked.info?.value?.status === OWNER_ASLEEP_STATUS ? OWN_STATUS_ASLEEP_MEMO_MS : OWN_STATUS_AWAKE_MEMO_MS+ }++ /** One refresh per grid at a time; every asker shares it. */+ private refresh(tracked: Tracked): Promise<void> {+ tracked.pending ??= this.read(tracked).finally(() => { tracked.pending = null })+ return tracked.pending+ }++ private async read(tracked: Tracked): Promise<void> {+ const before = JSON.stringify(await this.signature(tracked))+ const info = await this.info(tracked)+ const asleepByStatus = tracked.own && info?.status === OWNER_ASLEEP_STATUS+ // The own grid, while its status says asleep, is read exactly once per asleep episode — to fetch the+ // platform's record of what it served — and then left alone until the status changes.+ if (asleepByStatus && tracked.episodeRead) {+ await this.apply(tracked, { kind: 'asleep', lastKnown: null }, null)+ } else {+ tracked.episodeRead = asleepByStatus+ const base = readBase(info?.gridUrl ?? null)+ let read: GridRead = base ? await readOverview(base) : { kind: 'unreachable' }+ // Only when nothing answered at all — never to second-guess an answer the grid gave.+ if (read.kind === 'unreachable') read = await readViaCli(tracked.name)+ await this.apply(tracked, read, base)+ }+ await this.save(tracked)+ tracked.known = true+ if (JSON.stringify(await this.signature(tracked)) !== before) this.changed()+ }++ private async info(tracked: Tracked): Promise<GridInfo | null> {+ const now = this.deps.now()+ if (tracked.info && now - tracked.info.at < this.statusTtl(tracked)) return tracked.info.value+ // A failed ask keeps the last answer (the address is still the address), and is not re-asked at once.+ const value = await readGridInfo(tracked.name) ?? tracked.info?.value ?? null+ tracked.info = { at: now, value }+ if (value?.status !== OWNER_ASLEEP_STATUS) tracked.episodeRead = false+ return value+ }++ private async apply(tracked: Tracked, read: GridRead, base: string | null): Promise<void> {+ const now = this.deps.now()+ tracked.readAt = now+ if (read.kind === 'asleep') {+ tracked.picture = withAsleep(tracked.picture, read.lastKnown, now)+ tracked.readTtl = ASLEEP_MEMO_MS+ return+ }+ if (read.kind !== 'awake') {+ tracked.picture = withUnknown(tracked.picture)+ tracked.readTtl = FAILED_MEMO_MS+ return+ }+ const here = await this.servedHere(tracked)+ const email = this.deps.email()?.trim().toLowerCase() ?? ''+ const isMine = (node: ReadNode): boolean => !!email && node.providerEmail?.trim().toLowerCase() === email+ const previous = tracked.picture+ let picture = mergeAwake(previous, read.nodes, now, isMine, (name, key) => provenStopped(previous, here, name, key))+ picture = { ...picture, caseMap: withSpellings(picture.caseMap, [...read.curatedIds, ...here.records.flatMap((r) => r.ids)]) }+ const unknownIds = unspelled(picture, read.nodes).filter((key) => !tracked.spelled.has(key))+ if (unknownIds.length && base) {+ unknownIds.forEach((key) => tracked.spelled.add(key))+ picture = { ...picture, caseMap: withSpellings(picture.caseMap, await readDiscoveryIds(base)) }+ }+ tracked.picture = picture+ tracked.rawNodes = read.rawNodes+ tracked.readTtl = AWAKE_MEMO_MS+ // What this computer serves is re-learnt from what is live now: the grid has just said what it serves.+ tracked.seen = new Set(liveKeys(here.records))+ }++ /**+ * This computer's own records for the grid, and what they have been seen serving. Deliberately updates+ * `seen` on EVERY look, answers included: "seen served since the last awake read" is only true if each+ * look that found a live record counted.+ */+ private async servedHere(tracked: Tracked): Promise<ServedHere> {+ const records: LocalRecord[] = tracked.id.startsWith(NAME_ONLY_PREFIX) ? [] : await readRunRecords(this.deps.gridHome(), tracked.id)+ for (const key of liveKeys(records)) tracked.seen.add(key)+ return { records, seen: tracked.seen, own: tracked.own }+ }++ private async view(tracked: Tracked): Promise<Omit<SectionView, 'models'> & { models: GridModel[] }> {+ return sectionView(tracked.picture, await this.servedHere(tracked), this.deps.now())+ }++ /** What a push is about: the rows and the state — not the ages, which move every second. */+ private async signature(tracked: Tracked): Promise<unknown> {+ const view = await this.view(tracked)+ return { models: view.models, state: view.state }+ }++ private changed(): void {+ if (this.changeTimer) return+ this.changeTimer = setTimeout(() => {+ this.changeTimer = null+ for (const listener of this.listeners) {+ try { listener() } catch { /* a listener's failure is its own */ }+ }+ }, CHANGE_COALESCE_MS)+ this.changeTimer.unref?.()+ }++ private file(tracked: Tracked): string {+ const name = createHash('sha256').update(tracked.id).digest('hex').slice(0, 24)+ return join(this.deps.dataDir(), 'grid-pictures', `${name}.json`)+ }++ private async load(tracked: Tracked): Promise<void> {+ try {+ const raw = JSON.parse(await readFile(this.file(tracked), 'utf8')) as { networkId?: unknown; picture?: unknown }+ const picture = raw.networkId === tracked.id ? parsePicture(raw.picture) : null+ if (!picture) return+ tracked.picture = picture+ tracked.known = true+ tracked.saved = JSON.stringify(picture)+ } catch { /* never read on this computer, or not a file this module wrote */ }+ }++ /** Owner-only, replaced atomically — a crash mid-write leaves the previous picture, never half of one. */+ private async save(tracked: Tracked): Promise<void> {+ const text = JSON.stringify(tracked.picture)+ if (text === tracked.saved) return+ try {+ const file = this.file(tracked)+ await mkdir(dirname(file), { recursive: true, mode: 0o700 })+ const temp = `${file}.${randomUUID()}.tmp`+ await writeFile(temp, JSON.stringify({ networkId: tracked.id, picture: tracked.picture }), { mode: 0o600 })+ await rename(temp, file)+ tracked.saved = text+ } catch { /* the picture is still in memory; the next read tries again */ }+ }}-function remember(gridName: string, models: GridModel[]): void {- memo.set(gridName, { at: Date.now(), models })+function liveKeys(records: readonly LocalRecord[]): string[] {+ return records+ .filter((record) => record.pid !== null && record.alive)+ .flatMap((record) => record.ids.map((id) => servedKey(record.name, idKey(id))))}-/** Drop the memo — for a caller that has just changed what the grid serves. */+/** The daemon's one service. Module-level like the memo it replaces, so every caller shares one picture. */+let service = new GridModelsService()++/** Live models on `gridName`, router excluded, as the picture has them after a read if one was due. */+export async function listGridModels(gridName: string | null): Promise<GridModel[]> {+ if (!gridName?.trim()) return []+ return service.models(gridName.trim())+}++/** Every grid this computer is signed into, each with its models, own grid first. */+export function listAllGridModels(ownGridName: string | null, opts: { refresh?: boolean } = {}): Promise<GridSection[]> {+ return service.sections(ownGridName, opts)+}++/** The Model Manager's inventory of the own grid (`LocalModels`' injected `inventory`). */+export function gridInventory(gridName: string, force: boolean): Promise<GridInventoryAnswer> {+ return service.inventory(gridName, force)+}++/** Make every read due again — for a caller that has just changed what a grid serves. */export function forgetGridModels(): void {- memo.clear()+ service.forget()}-/** Model ids exactly as the grid's relay serves them — the names an engine must send. Empty when the- * relay cannot be asked, which the caller treats as "fall back", never as "no models". */-async function relayModelIds(gridName: string): Promise<string[]> {- const info = await gridExec(['--remote', 'info', gridName, '--env'])- if (info.code !== 'OK') return []- const env = readEnvExports(info.stdout)- if (!env.baseUrl || !env.apiKey) return []- return (await relayModels(env.baseUrl, env.apiKey)).map((m) => m.id)+/** Be told (coalesced) when a background read changed what a picker would be told. */+export function onGridModelsChanged(listener: () => void): () => void {+ return service.onChange(listener)+}++/** For tests: a fresh service, optionally with its clock and places injected. */+export function resetGridModels(deps: Partial<GridModelsDeps> = {}): GridModelsService {+ service = new GridModelsService(deps)+ return service}+ /** A row of the relay's `/models`: the id it routes, and the context window it reports for it. */+ interface RelayModel { id: string; contextWindow?: number }+-/** The relay's own catalogue. Empty when it cannot be asked — callers read that as "fall back". */++/**++ * The relay's own catalogue. Empty when it cannot be asked — callers read that as "fall back".++ *++ * ⚠️ A SIGNED-IN read, so on a sleeping grid it WAKES it. Asked only by [resolveGridTarget], i.e. when++ * a person moves an agent onto a model or starts one there — an act that needs the grid anyway. Never++ * from the model list or any other read made on the app's own schedule (grid-reads-without-waking).++ */+ async function relayModels(baseUrl: string, apiKey: string): Promise<RelayModel[]> {+ try {+ const response = await fetch(`${baseUrl.replace(/\/$/, '')}/models`, {+ headers: { authorization: `Bearer ${apiKey}` },+ signal: AbortSignal.timeout(10_000),+ })+ if (!response.ok) return []+ const body = await response.json() as { data?: Array<{ id?: unknown; context_window?: unknown }> }+ return (body.data ?? []).flatMap((m) => {+ if (typeof m.id !== 'string' || !m.id) return []+ const contextWindow = contextWindowHint(m.context_window)+ return [{ id: m.id, ...(contextWindow ? { contextWindow } : {}) }]+ })+ } catch {+ return []+ }+ }+/** `grid info --env` prints shell exports; these are the two that matter. */const ENV_LINE = /^export\s+(OPENAI_BASE_URL|OPENAI_API_KEY)=(.*)$/gmdiff --cc cli/src/lib/localModels.integration.spec.tsindex 0840f1c68,ac6487224..9d2b88805--- a/cli/src/lib/localModels.integration.spec.ts+++ b/cli/src/lib/localModels.integration.spec.ts@@@ -58,11 -58,7 +59,11 @@@ else if (args.includes('info') && args.else if (args.includes('info')) console.log("export OPENAI_BASE_URL='${base}/v1'\\nexport OPENAI_API_KEY='inference-fixture'");else process.exitCode = 2;`, { mode: 0o700 })- const options = { stateDir, processEnv: { GRID_HOME: gridHome, HARNESS_GRID_BIN: executable, PATH: root } }+ // The grid's own answer, as the credential-less reader would give it: the engine is listed while its+ // run record exists (the fake's `join` writes it, `leave` removes it).+ const record = join(gridHome, 'run', 'engines', 'fixture-grid', 'remote.json')- const inventory = async () => ({ state: 'awake' as const, nodes: existsSync(record) ? [{ node_id: 'fixture-node', online: true, models: ['tiny'] }] : [] })++ const inventory = async () => ({ state: 'awake' as const, status: 'running', nodes: existsSync(record) ? [{ node_id: 'fixture-node', online: true, models: ['tiny'] }] : [] })+ const options = { stateDir, processEnv: { GRID_HOME: gridHome, HARNESS_GRID_BIN: executable, PATH: root }, inventory }service = new LocalModels(options)expect((await service.list('home')).models[0]).toMatchObject({ state: 'available', canStart: true })expect(replies).toBe(0)diff --cc cli/src/lib/localModels.spec.tsindex f4fc39091,495f39a78..82536de11--- a/cli/src/lib/localModels.spec.ts+++ b/cli/src/lib/localModels.spec.ts@@@ -4,8 -4,7 +4,8 @@@ import { join } from 'node:pathimport { tmpdir } from 'node:os'import { createHash } from 'node:crypto'import { rmSync, writeFileSync } from 'node:fs'-import { compatibleModels, contextLadder, LocalModels } from './localModels.js'+import { spawnSync } from 'node:child_process'- import { compatibleModels, LocalModels, readRunRecords, type GridInventory } from './localModels.js'++import { compatibleModels, contextLadder, LocalModels, readRunRecords, type GridInventory } from './localModels.js'import { GridFleetRpc, type GridFleetResult } from './gridFleetRpc.js'import { encryptDownFrame, encryptRpcResult } from './e2ee/applicationFrames.js'@@@ -19,11 -18,16 +19,20 @@@ let calls: string[][], serving: booleanlet request: Mock<(url: string | URL, init?: RequestInit) => Promise<Response>>let run: Mock<(args: string[], output?: (s: string) => void) => Promise<GridFleetResult>>let downloadFails: boolean, catalogFails: boolean- // What the grid says it serves. Production reads it without a credential (`gridModels.gridInventory`);- // here it is the scenario the fake `grid` below answers for `engines`, so each test keeps its meaning,- // and `gridState` is what the grid's own answer said about it.- let gridState: GridInventory['state']+ /** What `grid info` says of the grid. Down (`stopped`/`asleep`) refuses `engines` and `join`, as+ * the real grid does, until `grid start` brings it back. */+ let gridState: 'running' | 'stopped' | 'asleep'+ /** What `grid ctx FILE` reads from a file's header (null: the command fails), and the window the+ * serving engine reports once started (undefined: Grid does not say). */+ let trainedWindow: number | null, servedWindow: number | undefined+ /** The relay's own test request — as opposed to the probe sent straight to the engine on this+ * machine (`127.0.0.1`), which a start now makes first. */+ const RELAY_CHAT = 'inference.example.test/v1/chat/completions'+ const refused = (message: string) => ({ ok: false, code: 1, stdout: '', stderr: message, error: 'Grid command failed.' })++/** The grid's own answer when a test pins it (null: derived from [gridState], as production derives it). */++let answered: GridInventory['state'] | null++/** What `gridModels.gridInventory` would hand the Model Manager — read without a credential. */+let inventory: Mock<(grid: string, force: boolean) => Promise<GridInventory>>beforeEach(async () => {root = await mkdtemp(join(tmpdir(), 'local-models-'))home = join(root, 'grid'); stateDir = join(root, 'receipts'); records = join(home, 'run', 'engines', 'grid-home')@@@ -61,13 -72,7 +77,20 @@@}return response({ choices: [{ message: { content: 'ok' } }] })})- gridState = 'awake'- inventory = vi.fn(async (grid: string) => {- service = new LocalModels({ stateDir, processEnv: { GRID_HOME: home }, run, request: request as typeof fetch })++ // The inventory as production reads it (`gridModels.gridInventory`), over this fake's grid: the owner++ // status is `gridState`; a sleeping grid answers asleep, a stopped one answers nothing readable (the++ // proxy's grid_stopped), and a running one lists what the fake's `engines` lists.++ answered = null++ inventory = vi.fn(async (grid: string): Promise<GridInventory> => {++ const status = gridState++ if (answered) return { state: answered, nodes: [], status }++ if (status === 'asleep') return { state: 'asleep', nodes: [], status }++ if (status !== 'running') return { state: 'unknown', nodes: [], status }+ const answer = await run(['--remote', 'engines', grid, '--json'])- if (!answer.ok) throw new Error('unreadable')- return { state: gridState, nodes: gridState === 'awake' ? JSON.parse(answer.stdout) : [] }++ if (!answer.ok) return { state: 'unknown', nodes: [], status }++ try { return { state: 'awake', nodes: JSON.parse(answer.stdout), status } } catch { return { state: 'unknown', nodes: [], status } }+ })+ service = new LocalModels({ stateDir, processEnv: { GRID_HOME: home }, run, request: request as typeof fetch, inventory })})afterEach(async () => { await service.settled(); vi.useRealTimers(); vi.restoreAllMocks(); vi.unstubAllEnvs(); vi.unstubAllGlobals(); await rm(root, { recursive: true, force: true }) })@@@ -187,10 -192,10 +210,10 @@@ describe('local model discovery and lifit('keeps existing local engines visible when the catalog cannot be reached', async () => {await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()catalogFails = true- const fresh = new LocalModels({ stateDir, processEnv: { GRID_HOME: home }, run, request: request as typeof fetch })+ const fresh = new LocalModels({ stateDir, processEnv: { GRID_HOME: home }, run, request: request as typeof fetch , inventory })const snapshot = await fresh.list('home')expect(snapshot.models[0]).toMatchObject({ state: 'running', canStop: true })- expect(snapshot.error).toContain('unavailable')+ expect(snapshot.notice).toContain('unavailable')expect(JSON.stringify(snapshot)).not.toContain('private raw')})@@@ -701,94 -772,178 +790,275 @@@})})+/** A pid that existed a moment ago and no longer does. */+function deadPid(): number {+ return Number(spawnSync(process.execPath, ['-e', 'process.stdout.write(String(process.pid))'], { encoding: 'utf8' }).stdout)+}++describe('the Model Manager while its grid sleeps (grid-reads-without-waking issue 02)', () => {+ const parkedRecord = (pid: unknown) => JSON.stringify({ node_id: 'local-node', meta_name: 'This computer', pid,+ engines: [{ endpoint_url: null, models: ['Small-Q4.gguf'] }], advertise_as: [] })++ it('is not an inventory error: Start and Pause stay enabled, and a parked engine reads running', async () => {+ gridState = 'asleep'+ const next = card('org/Next-GGUF'); next.versions[0].pull_spec = 'org/Next-GGUF:Next.gguf'+ catalogCards = [card(), next]+ await writeFile(join(home, 'models', 'Small-Q4.gguf'), Buffer.alloc(64))+ await writeFile(join(records, 'remote.json'), parkedRecord(process.pid))++ const snapshot = await service.list('home')+- expect(snapshot.error).not.toBe('Running models could not be checked. Try again.')++ expect(snapshot.notice).not.toBe('Running models could not be checked. Try again.')+ expect(snapshot.models[0]).toMatchObject({ id: 'org/Small-GGUF', state: 'running', gridAsleep: true, canStop: true })+ expect(snapshot.models[1]).toMatchObject({ id: 'org/Next-GGUF', canStart: true })+ expect(inventory).toHaveBeenCalledWith('home', false)+ })++ it('reads a parked engine running on a row the catalog does not know, too', async () => {+ gridState = 'asleep'; catalogCards = []+ await writeFile(join(records, 'remote.json'), parkedRecord(process.pid))+ expect((await service.list('home')).models).toEqual([expect.objectContaining({ id: 'local:Small-Q4.gguf', state: 'running', gridAsleep: true, canStop: true })])+ })++ it.each([['a process that is gone', () => deadPid()], ['a join mid-spawn (pid 0)', () => 0], ['no pid at all', () => 'x']])(+ 'does not call %s parked', async (_name, pid) => {+ gridState = 'asleep'; catalogCards = []+ await writeFile(join(records, 'remote.json'), parkedRecord(pid()))+ const [row] = (await service.list('home')).models+ expect(row).toMatchObject({ id: 'local:Small-Q4.gguf', state: 'available', canStop: true })+ expect(row).not.toHaveProperty('gridAsleep')+ })++ it('an engine the awake grid lists is running with no asleep flag', async () => {+ serving = true+ await writeFile(join(home, 'models', 'Small-Q4.gguf'), Buffer.alloc(64))+ await writeFile(join(records, 'remote.json'), parkedRecord(process.pid))+ await writeFile(join(records, 'remote.heartbeat'), '')+ const [row] = (await service.list('home')).models+ expect(row).toMatchObject({ state: 'running' })+ expect(row).not.toHaveProperty('gridAsleep')+ })++ it('a grid that answered nothing readable is still an inventory error', async () => {- gridState = 'unknown'- expect((await service.list('home')).error).toBe('Running models could not be checked. Try again.')++ answered = 'unknown'++ expect((await service.list('home')).notice).toBe('Running models could not be checked. Try again.')++ })++++ it('and so is one whose owner status could not be read either — nothing says it is down', async () => {++ inventory.mockResolvedValueOnce({ state: 'unknown', nodes: [], status: null })++ expect((await service.list('home')).notice).toBe('Running models could not be checked. Try again.')+ })++ it.each([['failed', { ...ok(), ok: false, code: 1 }], ['answered with something that is not JSON', { ...ok(), stdout: 'not json' }]])(+ 'so is a grid list that %s', async (_how, answer) => {+ const original = run.getMockImplementation()!+ run.mockImplementation(async (args, output) => args.includes('ls') ? answer : original(args, output))- expect((await service.list('home')).error).toBe('Running models could not be checked. Try again.')++ expect((await service.list('home')).notice).toBe('Running models could not be checked. Try again.')+ })++ it('tells its owner when a start or stop has finished, so the lists are read again', async () => {+ const onChanged = vi.fn()+ service = new LocalModels({ stateDir, processEnv: { GRID_HOME: home }, run, request: request as typeof fetch, inventory, onChanged })+ await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()+ expect(onChanged).toHaveBeenCalledOnce()+ })+})++describe('readRunRecords — what servedHere knows about this computer', () => {+ it('reads the name, the advertised ids (else the models under the display rule) and whether the pid lives', async () => {+ await writeFile(join(records, 'a.json'), JSON.stringify({ meta_name: 'mac', pid: process.pid, advertise_as: ['Team/Model', 7, ''], models: ['ignored.gguf'] }))+ await writeFile(join(records, 'b.json'), JSON.stringify({ meta_name: 'mac', pid: deadPid(), models: ['Qwen3-8B-Q4_K_M.GGUF', 'plain'] }))+ await writeFile(join(records, 'c.json'), JSON.stringify({ pid: 0, models: 'not a list' }))+ await writeFile(join(records, 'd.json'), '{ not json')+ await writeFile(join(records, 'e.heartbeat'), '')++ const found = (await readRunRecords(home, 'grid-home')).sort((x, y) => x.ids.join().localeCompare(y.ids.join()))++ expect(found).toEqual([+ { name: '', ids: [], pid: null, alive: false },+ { name: 'mac', ids: ['Qwen3-8B-Q4_K_M', 'plain'], pid: expect.any(Number), alive: false },+ { name: 'mac', ids: ['Team/Model'], pid: process.pid, alive: true },+ ])+ })++ it.each(['', '../grid-home', 'missing'])('answers nothing for grid id %j', async (gridId) => {+ await writeFile(join(records, 'a.json'), JSON.stringify({ meta_name: 'mac', pid: process.pid, advertise_as: ['X'] }))+ expect(await readRunRecords(home, gridId)).toEqual([])+ })+})+++ describe('a context a coding agent can work in', () => {+ // ⚠️ REGRESSION. Every model was offered and started at 16K or less — a model that loads, passes+ // its one-word check, and then cannot hold a coding agent's first prompt. Codex, Claude Code and+ // OpenCode all need 64K at the least; the most this machine can give is what a start now asks for.++ it.each([+ [32768, false], [65535, false], [65536, true], [262144, true],+ ])("a catalog fit of %i on this machine is offered: %s", async (ctx, offered) => {+ catalogCards[0].fit.ctx = ctx+ expect((await service.list('home')).models.length).toBe(offered ? 1 : 0)+ })++ it('pins the whole fit, capped at the most the model was trained for', async () => {+ Object.assign(catalogCards[0].fit, { ctx: 262144, max_ctx: 196608 })+ await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()+ const joined = calls.find(args => args.includes('join'))!+ expect(joined[joined.indexOf('--ctx-size') + 1]).toBe('196608')+ })++ it('shrinks to what fits at start when memory has since tightened, but never under 64K', async () => {+ catalogCards[0].fit.ctx = 262144+ await service.list('home')+ catalogCards[0].fit.ctx = 98304+ await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()+ const joined = calls.find(args => args.includes('join'))!+ expect(joined[joined.indexOf('--ctx-size') + 1]).toBe('98304')+ })++ it('refuses to start at all when the fit at start is under 64K', async () => {+ await service.list('home')+ catalogCards[0].fit.ctx = 32768+ await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()+ expect(calls.some(args => args.includes('join'))).toBe(false)+ expect((await service.list('home')).models[0].operation).toMatchObject({ phase: 'failed', error: expect.stringContaining('make room') })+ })++ it('hides a model on disk whose file can never hold 64K, and keeps one it cannot read', async () => {+ catalogCards = []; serving = true+ await writeFile(join(home, 'models', 'Small-Q4.gguf'), Buffer.alloc(64))+ await writeFile(join(records, 'remote.json'), JSON.stringify({ node_id: 'local-node', engines: [{ models: ['Small-Q4.gguf'] }] }))+ await writeFile(join(records, 'remote.heartbeat'), '')+ const id = (await service.list('home')).models[0].id+ await service.act('home', id, 'stop'); await service.settled()+ // Unreadable header: unknown is not "too small".+ expect((await service.list('home', true)).models.map(m => m.id)).toEqual([id])+ trainedWindow = 32768- const fresh = new LocalModels({ stateDir, processEnv: { GRID_HOME: home }, run, request: request as typeof fetch })++ const fresh = new LocalModels({ stateDir, processEnv: { GRID_HOME: home }, run, request: request as typeof fetch, inventory })+ expect((await fresh.list('home')).models).toEqual([])+ })++ it.each([+ [131072, 'done'], [undefined, 'done'], [32768, 'failed'],+ ] as const)('after a start that served %s tokens, the start is %s', async (window, phase) => {+ servedWindow = window+ await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()+ const operation = (await service.list('home', true)).models[0].operation+ expect(operation?.phase).toBe(phase)+ if (phase === 'failed') {+ // Served too small: taken back down rather than left answering prompts it cannot hold.+ expect(calls.find(args => args.includes('leave'))).toEqual(['--remote', 'leave', 'home', '--engine', 'Small-Q4.gguf'])+ expect(operation?.error).toBe('Small could only get a 32K context here. Coding agents need at least 64K. Close some apps, or choose a smaller model.')+ } else {+ expect(calls.some(args => args.includes('leave'))).toBe(false)+ }+ })+ })++ describe('stepping down to the context that actually runs', () => {+ // ⚠️ REGRESSION, measured on a 64 GB M1 Max. Left to the engine, a 35B model took its whole+ // trained 256K, loaded, and then failed its very first request — "Insufficient Memory+ // (kIOGPUCommandBufferCallbackErrorOutOfMemory)", then "Compute error." for every request after.+ // The relay check waited three minutes and said only "did not answer". The same file ran at 128K.++ const joinedAt = () => calls.filter(args => args.includes('join')).map(args => Number(args[args.indexOf('--ctx-size') + 1]))+ /** The engine on this machine runs out of memory at any context above [limit]. */+ const gpuHolds = (limit: number) => {+ const original = request.getMockImplementation()!+ request.mockImplementation(async (url, init) => {+ if (String(url).includes('127.0.0.1') && String(url).endsWith('/chat/completions') && joinedAt().at(-1)! > limit) {+ return new Response(JSON.stringify({ error: { code: 500, message: 'Compute error.', type: 'server_error' } }), { status: 500 })+ }+ return original(url, init)+ })+ }++ it('halves to the 64K floor and no further', () => {+ expect(contextLadder(262144)).toEqual([262144, 131072, 65536])+ expect(contextLadder(196608)).toEqual([196608, 98304, 65536])+ expect(contextLadder(100000)).toEqual([100000, 65536])+ expect(contextLadder(65536)).toEqual([65536])+ expect(contextLadder(50000)).toEqual([])+ })++ it('takes a size the GPU cannot run back down, and settles on the next that does', async () => {+ catalogCards[0].fit.ctx = 262144+ gpuHolds(131072)+ await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()+ expect(joinedAt()).toEqual([262144, 131072])+ // Down between the two, and Grid's registration restored before the second join.+ const between = calls.slice(calls.findIndex(a => a.includes('join')) + 1, calls.findLastIndex(a => a.includes('join')))+ expect(between).toContainEqual(['--remote', 'leave', 'home', '--engine', 'Small-Q4.gguf'])+ expect(between).toContainEqual(['--remote', 'sync'])+ expect((await service.list('home', true)).models[0]).toMatchObject({ state: 'running', operation: { phase: 'done' } })+ })++ it('says it is memory, in words, when not even 64K runs — without waiting on the relay', async () => {+ catalogCards[0].fit.ctx = 262144+ gpuHolds(0)+ await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()+ expect(joinedAt()).toEqual([262144, 131072, 65536])+ expect(request.mock.calls.some(([url]) => String(url).includes(RELAY_CHAT))).toBe(false)+ expect((await service.list('home', true)).models[0].operation).toMatchObject({ phase: 'failed',+ error: 'This computer does not have the memory to run Small with a 64K context. Close some apps, or choose a smaller model.' })+ })++ it('steps down from a size whose join fails, since a failed allocation at load looks like that', async () => {+ catalogCards[0].fit.ctx = 262144+ const original = run.getMockImplementation()!+ run.mockImplementation(async (args, output) => args.includes('join') && args.includes('262144') ? refused('engine exited') : original(args, output))+ await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()+ const joins = run.mock.calls.map(([args]) => args).filter(args => args.includes('join'))+ expect(joins.map(a => a[a.indexOf('--ctx-size') + 1])).toEqual(['262144', '131072'])+ expect((await service.list('home', true)).models[0].operation?.phase).toBe('done')+ })++ it.each([+ ['nothing is listening on this machine', () => { throw new Error('ECONNREFUSED') }],+ ['the engine fails for another reason', () => new Response('{"error":{"message":"template error"}}', { status: 500 })],+ // Not a load in progress (503), so not waited on for ten minutes.+ ['its health check answers something unexpected', () => new Response('teapot', { status: 418 })],+ ])('leaves the judgement to the relay check when %s', async (_case, answer) => {+ const original = request.getMockImplementation()!+ request.mockImplementation(async (url, init) => String(url).includes('127.0.0.1') ? answer() : original(url, init))+ await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()+ expect(joinedAt()).toEqual([131072])+ expect(request.mock.calls.some(([url]) => String(url).includes(RELAY_CHAT))).toBe(true)+ expect((await service.list('home', true)).models[0].operation?.phase).toBe('done')+ })++ it('starts a file on disk at the most its header says it holds', async () => {+ catalogCards = []; serving = true+ await writeFile(join(home, 'models', 'Small-Q4.gguf'), Buffer.alloc(64))+ await writeFile(join(records, 'remote.json'), JSON.stringify({ node_id: 'local-node', engines: [{ models: ['Small-Q4.gguf'] }] }))+ await writeFile(join(records, 'remote.heartbeat'), '')+ const id = (await service.list('home')).models[0].id+ await service.act('home', id, 'stop'); await service.settled()+ trainedWindow = 262144- const fresh = new LocalModels({ stateDir, processEnv: { GRID_HOME: home }, run, request: request as typeof fetch })++ const fresh = new LocalModels({ stateDir, processEnv: { GRID_HOME: home }, run, request: request as typeof fetch, inventory })+ await fresh.act('home', id, 'start'); await fresh.settled()+ expect(joinedAt()).toEqual([262144])+ })+ })++ describe("a model is labelled with the machine's name as Harness shows it", () => {+ // ⚠️ REGRESSION. Started from the Models modal, a model joined with no `--name`, so Grid labelled+ // it with the host name: `mac.lan` under "On your machines" while Machines called it `M2`.+ const joined = () => calls.find(args => args.includes('join'))!++ it('joins under the Harness name', async () => {- const named = new LocalModels({ stateDir, processEnv: { GRID_HOME: home }, run, request: request as typeof fetch, machineName: () => ' M2 ' })++ const named = new LocalModels({ stateDir, processEnv: { GRID_HOME: home }, run, request: request as typeof fetch, machineName: () => ' M2 ', inventory })+ await named.act('home', 'org/Small-GGUF', 'start'); await named.settled()+ expect(joined().slice(joined().indexOf('--name'), joined().indexOf('--name') + 2)).toEqual(['--name', 'M2'])+ })++ it.each([+ ['is not known yet', () => null],+ ['would read as a flag', () => '--all'],+ ['carries a control character', () => 'M2\nevil'],+ ])('leaves --name off when the name %s, rather than pass it', async (_case, machineName) => {- const named = new LocalModels({ stateDir, processEnv: { GRID_HOME: home }, run, request: request as typeof fetch, machineName })++ const named = new LocalModels({ stateDir, processEnv: { GRID_HOME: home }, run, request: request as typeof fetch, machineName, inventory })+ await named.act('home', 'org/Small-GGUF', 'start'); await named.settled()+ expect(joined()).not.toContain('--name')+ expect((await named.list('home', true)).models[0].operation?.phase).toBe('done')+ })+ })diff --cc cli/src/lib/localModels.tsindex ad56d5ebb,c1f633db9..78f6ffab2--- a/cli/src/lib/localModels.ts+++ b/cli/src/lib/localModels.ts@@@ -39,25 -77,23 +81,35 @@@ export interface LocalModelsSnapshotobservedAt: string; busy: boolean}interface Candidate {- id: string; name: string; pull: string; file: string; files: string[]; size: number; quant: string; context: number+ id: string; name: string; pull: string; file: string; files: string[]; size: number; quant: string+ /** The window to pin at start: the catalog's fit for this machine, which is the largest it can+ * hold. Absent for a model found on disk, which the catalog never sized — the engine then measures+ * free memory at load and takes the largest window that fits (`grid join` without `--ctx-size`). */+ context?: numberaliases?: string[]}-interface Owned { file: string; selector: string; aliases: string[]; nodeId: string; name: string; live: boolean; siblings: number }+/** `live`: its heartbeat sidecar is fresh (the grid is hearing from it). `pidAlive`: the process its run+ * record names exists — the only liveness that holds while the grid sleeps and the sidecar goes stale. */- interface Owned { file: string; selector: string; aliases: string[]; nodeId: string; name: string; live: boolean; pidAlive: boolean; context: number; siblings: number }++interface Owned { file: string; selector: string; aliases: string[]; nodeId: string; name: string; live: boolean; pidAlive: boolean; siblings: number }interface Receipt { spec: 1; grid: string; operation?: ModelOperation }+/** What the grid says is running on it, read WITHOUT waking it (`gridModels.gridInventory`): the- * overview's node objects while it is awake, nothing while it sleeps. */- export interface GridInventory { state: PictureState; nodes: Record<string, unknown>[] }++ * overview's node objects while it is awake, nothing while it sleeps — and its owner status (`running`,++ * `stopped`, `asleep`; null for a member or when it could not be read), remembered rather than asked on++ * every tick. */++export interface GridInventory { state: PictureState; nodes: Record<string, unknown>[]; status: string | null }interface Options {stateDir: string; processEnv?: NodeJS.ProcessEnv+ /** This machine's name as Harness shows it. Grid labels an engine with its `--name`, and without+ * one it takes the host name — so a model started here read `mac.lan` under "On your machines"+ * while Machines called the same computer `M2`. */+ machineName?: () => string | null | undefinedrun?: (args: string[], output?: (chunk: string) => void, timeout?: number) => Promise<GridFleetResult>request?: typeof fetch+ /** Injected, never a `grid engines` call: that read carries the grid credential, and a signed-in read+ * of a sleeping grid WAKES it — once a tick, for as long as the panel is open. */+ inventory: (grid: string, force: boolean) => Promise<GridInventory>+ /** Told when a start or stop has finished, so the model lists are read again. */+ onChanged?: () => void}/** One concrete, machine-fitted version per model. Non-chat and unprobed offline@@@ -213,8 -255,7 +271,8 @@@ export class LocalModelsconst advertised = Array.isArray(record.advertise_as) && specs.length === 1? record.advertise_as.filter((v: unknown) => typeof v === 'string' && v.length > 0) : []const aliases: string[] = advertised.length ? advertised : [file]- result.push({ file: basename(file), selector: file, aliases, nodeId: str(record.node_id), name: str(record.meta_name), live, siblings: specs.length + (record.media ? 1 : 0) })+ const pid = recordPid(record)- result.push({ file: basename(file), selector: file, aliases, nodeId: str(record.node_id), name: str(record.meta_name), live, pidAlive: pid !== null && processExists(pid), context: Math.min(16384, num(record.ctx_size) || 8192), siblings: specs.length + (record.media ? 1 : 0) })++ result.push({ file: basename(file), selector: file, aliases, nodeId: str(record.node_id), name: str(record.meta_name), live, pidAlive: pid !== null && processExists(pid), siblings: specs.length + (record.media ? 1 : 0) })this.blockers.set(grid, `Stop ${cleanName(aliases[0])} first to start another local model.`)}}@@@ -299,15 -405,9 +422,16 @@@}private async readList(grid: string, force: boolean): Promise<LocalModelsSnapshot> {await Promise.all([this.loadCatalog(force), this.readReceipt(grid)])- let owned: Owned[] = [], nodes: Record<string, any>[] = [], inventoryError: string | undefined+ let owned: Owned[] = [], nodes: Record<string, any>[] = [], inventoryError: string | undefined, asleep = falsetry {- [owned, nodes] = await Promise.all([this.owned(grid), this.servingNodes(grid)])+ let inventory: GridInventory+ [owned, inventory] = await Promise.all([this.owned(grid), this.options.inventory(grid, force)])- // Asleep is not an inventory error: the grid is resting, what runs here is still known here, and- // Start and Pause stay enabled. Only a read that failed some other way is.- if (inventory.state === 'unknown') throw new Error('unanswered')- asleep = inventory.state !== 'awake'- nodes = rows(inventory.nodes)++ // A grid that is down — its owner status says stopped or asleep (DOWN) — runs nothing: an answer,++ // not a gap, so Start stays enabled (and brings it back up). Asleep says so even to a member, in++ // the grid's own answer. Only a read that failed some other way is "could not be checked".++ if (inventory.state === 'unknown' && !DOWN.has(inventory.status ?? '')) throw new Error('unanswered')++ asleep = inventory.state === 'asleep' || inventory.status === 'asleep'++ nodes = inventory.state === 'awake' ? rows(inventory.nodes) : []} catch { inventoryError = 'Running models could not be checked. Try again.' }const operation = this.active?.grid === grid ? this.active.operation : this.receipt?.grid === grid ? this.receipt.operation : undefinedconst choices = [...this.candidates, ...(await this.known(grid, owned)).filter(k => !this.candidates.some(c => c.file === k.file))]@@@ -345,23 -441,42 +469,28 @@@tokensPerSecond: single && running ? num(node?.throughput_tok_s) : undefined,requests: running ? num(perModel?.requests) : undefined,windowSeconds: running ? num(answered.window_seconds) : undefined,- operation: operation?.modelId === candidate.id ? operation : undefined }+ operation: operation?.modelId === candidate.id ? operation : undefined,+ ...(!node && parked(instance) ? { gridAsleep: true } : {}) }})for (const instance of owned.filter(o => !choices.some(c => c.file === o.file))) {+ const serving = !!servingNode(instance)models.push({ id: `local:${instance.file}`, name: cleanName(instance.aliases[0]),- state: servingNode(instance) ? 'running' : 'available', canStart: false, canStop: !inventoryError,- operation: operation?.modelId === `local:${instance.file}` ? operation : undefined })+ state: serving || parked(instance) ? 'running' : 'available', canStart: false, canStop: !inventoryError,+ operation: operation?.modelId === `local:${instance.file}` ? operation : undefined,+ ...(!serving && parked(instance) ? { gridAsleep: true } : {}) })}const value: LocalModelsSnapshot = { models, memoryBytes: num(obj(this.device.memory).total_gb) === undefined ? undefined : this.device.memory.total_gb * GiB,- hardware: str(obj(this.device.machine).model || obj(this.device.cpu).brand), error: inventoryError || this.catalogError,+ hardware: str(obj(this.device.machine).model || obj(this.device.cpu).brand), notice: inventoryError || this.catalogError,observedAt: new Date().toISOString(), busy: !!this.active }this.cached = { grid, at: Date.now(), value }return value}+ /** What `grid info` says of [grid]: `running`, `stopped`, `asleep`. */+ private async gridStatus(grid: string): Promise<string> {+ return str(obj(await this.json(['--remote', 'info', grid, '--json'])).status)+ }+- /** The nodes serving [grid] — none at all when the grid is down.- *- * ⚠️ A stopped or asleep grid REFUSES `engines` ("isn't up; run `grid start` first") rather than- * answering an empty list, and reading that refusal as "unknown" disabled every Start in the- * list: the one state in which a person most needs to start a model was the one in which none- * could be. Stopping the last model from this list leaves the grid up, so it was only reached by- * a grid taken down by hand or gone to sleep — but then there was no way back from here. A grid- * that is down runs nothing, which is an answer, not a gap. Any other refusal still is one. */- private async servingNodes(grid: string): Promise<Record<string, any>[]> {- const result = await this.run(['--remote', 'engines', grid, '--json'])- if (result.ok) {- try { return rows(JSON.parse(result.stdout)) } catch { throw new Error('Running models could not be checked. Try again.') }- }- if (DOWN.has(await this.gridStatus(grid))) return []- throw new Error('Running models could not be checked. Try again.')- }-/** A repeated click or lost RPC acknowledgement joins the same operation.* A different model waits: starts/stops must not race on the machine's budget. */async act(grid: string | null, modelId: unknown, action: 'start' | 'stop'): Promise<{ operation?: ModelOperation; error?: string }> {diff --cc desktop/lib/screens/swarm_screen.dartindex 5b1f57307,e70ba7a0e..f4dab3069--- a/desktop/lib/screens/swarm_screen.dart+++ b/desktop/lib/screens/swarm_screen.dart@@@ -267,13 -266,20 +266,24 @@@ class _SwarmScreenState extends State<Sapp.agentUnread.addListener(_unreadChanged);// Coming back to the window puts the tab in front of the person again, and// nothing in the app necessarily changes when that happens — so it is told.+ //+ // The daemon is told too, on the way out as well as the way back: it decides+ // from `app_panes` whether a finished turn is already on screen, and that+ // roster does not change when the window slips behind a browser. Without+ // the second half the dial went quiet the first time this window lost focus+ // and stayed quiet until a pane happened to change._lifecycle = AppLifecycleListener(- onResume: app.seeWatchedAgents,+ onResume: () {+ app.seeWatchedAgents();+ app.announceWindowForeground();+ },+ onHide: app.announceWindowForeground,+ onInactive: app.announceWindowForeground,+ // Whether the app is in front of anyone decides whether the model surfaces refresh at all+ // (`AppNotifier.foreground`): a minimised or background window asks no daemon anything.+ onStateChange: app.appLifecycleChanged,);+ app.appLifecycleChanged(WidgetsBinding.instance.lifecycleState);app.addListener(_syncToolbarNotices);_toolbarNotices.addListener(_toolbarNoticesChanged);_onboarding.addListener(_onboardingChanged);diff --cc desktop/lib/widgets/grid_model_picker.dartindex 2f3b6f008,a5f7f9f0d..a94449d9a--- a/desktop/lib/widgets/grid_model_picker.dart+++ b/desktop/lib/widgets/grid_model_picker.dart@@@ -94,21 -94,18 +94,27 @@@ class GridModelPicker extends StatefulWclass _GridModelPickerState extends State<GridModelPicker> {bool _loading = false;- ModelsMenuController? _usage;++ /// The window's shared subscription readings — the same controller the Models panel draws,+ /// so this row and that menu cannot disagree. Owned by the app, never disposed here.+ late final ModelsMenuController _usage = widget.notifier.modelsMenu;GridModels? _last;+ /// Set when the control was built while the app was in the background: the warm-up it skipped is+ /// owed, and paid once when the app comes back to the foreground.+ bool _prefetchOwed = false;+@overridevoid initState() {super.initState();+ // The app's one picture of the grids, when some other surface has already read it — or the+ // daemon has pushed it — is a warm answer for this control's first click.+ _last = widget.notifier.gridPictures[widget.machineId];+ widget.notifier.gridPictures.addListener(_pictureChanged);+ widget.notifier.foreground.addListener(_foregroundChanged);+ // A reading that lands while the menu is open redraws its Subscription row, rather than+ // leaving "Checking usage…" there until the next open.+ _usage.addListener(_redrawOpenMenu);// Warm the answer as soon as the control exists, so a click lands on a memo rather than on two// subprocess spawns and two network round trips — measured at ~1.4s, which is a person watching// a header do nothing. Fire-and-forget: nothing here waits on it, and a failure just means the@@@ -141,14 -117,9 +147,10 @@@// Not under `flutter test`: a refresh reads the Keychain and asks the vendors, the same reads the// usage rail keeps out of tests (kUnderTest) — here every test that drew a pane header left that// work's timers pending after the tree was gone. Opening the menu still refreshes.- if (!kUnderTest) unawaited(_usage!.refresh().catchError((_) {}));+ if (!kUnderTest) unawaited(_usage.refresh().catchError((_) {}));- final answer = await widget.notifier.gridModels(widget.machineId);- if (mounted) _last = answer;+ _prefetchOwed = false;+ final picture = await widget.notifier.readGridPicture(widget.machineId);+ if (mounted) _last = picture;}/// Closes the menu this control has open, if any. Set while one is showing.@@@ -301,8 -260,8 +296,8 @@@// read to draw a list it already has is a menu that feels broken whenever that source is slow.// This open uses whatever is cached; the refresh lands for the next one. `refresh()` is itself// capped at once a minute, so opening the menu repeatedly costs nothing.- unawaited(_usage!.refresh().catchError((_) {}));+ unawaited(_usage.refresh().catchError((_) {}));- answer = await widget.notifier.gridModels(widget.machineId);+ answer = await widget.notifier.readGridPicture(widget.machineId);} finally {if (mounted) setState(() => _loading = false);}diff --cc desktop/test/grid_picture_test.dartindex f16ddbdc1,000000000..807b39c98mode 100644,000000..100644--- a/desktop/test/grid_picture_test.dart+++ b/desktop/test/grid_picture_test.dart@@@ -1,508 -1,0 +1,340 @@@- // The app-level picture of what the account's grids serve, and the three surfaces that refresh it- // (the Model Manager, the macOS Models menu, the pane picker) keeping quiet while the app is in the- // background. grid-reads-without-waking issue 02, desktop half.++// The app-level picture of what the account's grids serve, and the surfaces that refresh it (the Model++// Manager, the pane picker) keeping quiet while the app is in the background. (The macOS Models menu++// this also covered was removed on main in #303 — Models opens from the View menu now.)++// grid-reads-without-waking issue 02, desktop half.+import 'dart:async';++import 'package:flutter/material.dart';- import 'package:flutter/services.dart';+import 'package:flutter_test/flutter_test.dart';+import 'package:harness/core/models.dart';+import 'package:harness/models/model_manager_controller.dart';- import 'package:harness/screens/swarm_screen.dart';+import 'package:harness/state/app_state.dart';- import 'package:harness/state/swarm_catalog.dart';- import 'package:harness/usage/models_menu_controller.dart';- import 'package:harness/usage/usage_controller.dart';+import 'package:harness/widgets/grid_model_picker.dart';+import 'package:harness/ws/ws_conn.dart';++import 'support/model_manager.dart';+import 'swarm_state_test.dart' show MemoryStore, createApp;++/// A daemon that answers `grid_models_list` from [reply] and counts every time it is asked.+class _Daemon extends WsConn {+ _Daemon(this.reply)+ : super(+ wsBaseUrl: 'ws://fixture.invalid',+ autonomousEnv: 'test',+ machineId: 'm',+ accessTokenProvider: (_, _) async => '',+ onAuthFailure: (_) {},+ onEvent: (_) {},+ onStatus: (_) {},+ );++ Map<String, dynamic> reply;+ int asked = 0;++ /// When set, the next `grid_models_list` waits on it — so a test can land a push while a read is+ /// still out.+ Completer<void>? hold;++ @override+ Future<Map<String, dynamic>> request(+ String type, {+ Map<String, dynamic> payload = const {},+ Duration timeout = const Duration(seconds: 20),+ }) async {+ if (type != 'grid_models_list') return {};+ asked++;+ final held = hold;+ if (held != null) {+ hold = null;+ final answer = reply;+ await held.future;+ return answer;+ }+ return reply;+ }+}++Map<String, dynamic> _reply({+ String state = 'awake',+ String node = 'macbook',+ List<String> ids = const ['Qwen3.5-4B'],+ bool withNewFields = true,+}) => {+ 'gridName': 'home',+ 'models': [+ for (final id in ids) {'id': id, 'node': node},+ ],+ 'grids': [+ {+ 'name': 'home',+ 'type': 'permissioned-public',+ 'own': true,+ 'models': [+ for (final id in ids) {'id': id, 'node': node},+ ],+ if (withNewFields) ...{+ 'state': state,+ 'seenAt': '2026-09-24T08:00:00.000Z',+ 'lastKnownAge': 42,+ },+ },+ ],+ 'supportsModelLaunch': true,+};++void main() {+ TestWidgetsFlutterBinding.ensureInitialized();++ group('GridModels.fromReply', () {+ test('reads the three optional fields a newer daemon adds', () {+ final answer = GridModels.fromReply(_reply(state: 'asleep'));+ final section = answer.sections.single;+ expect(section.state, GridSectionState.asleep);+ expect(section.seenAt, DateTime.utc(2026, 9, 24, 8));+ expect(section.lastKnownAge, 42);+ // The sleeping section keeps its last known models — never blanked.+ expect(section.models.single.id, 'Qwen3.5-4B');+ });++ test('an older daemon that sends none of them reads exactly as before', () {+ final answer = GridModels.fromReply(_reply(withNewFields: false));+ final section = answer.sections.single;+ expect(section.state, isNull);+ expect(section.seenAt, isNull);+ expect(section.lastKnownAge, isNull);+ expect(section.name, 'home');+ expect(section.own, isTrue);+ expect(section.models.single.node, 'macbook');+ expect(section.models.single.grid, 'home');+ expect(answer.models.single.id, 'Qwen3.5-4B');+ expect(answer.reachable, isTrue);+ expect(answer.supportsModelLaunch, isTrue);+ });++ test('a state it does not know, a negative age and a bad time are no claim at all', () {+ final raw = _reply();+ final grid = (raw['grids'] as List).single as Map<String, dynamic>;+ grid['state'] = 'hibernating';+ grid['lastKnownAge'] = -5;+ grid['seenAt'] = 'yesterday';+ final section = GridModels.fromReply(raw).sections.single;+ expect(section.state, isNull);+ expect(section.lastKnownAge, isNull);+ expect(section.seenAt, isNull);+ });+ });++ group('the app-level picture', () {+ late _Daemon daemon;+ late AppNotifier app;+ setUp(() {+ daemon = _Daemon(_reply());+ app = createApp(connectionForTest: (_) => daemon);+ });+ tearDown(() => app.dispose());++ test('a grid_models_changed push replaces it with no request', () async {+ expect(app.gridPictures['m'], isNull);+ await app.handleEventForTest('m', {+ 'type': 'grid_models_changed',+ 'payload': _reply(state: 'asleep', node: 'studio'),+ });+ final picture = app.gridPictures['m']!;+ expect(picture.sections.single.state, GridSectionState.asleep);+ expect(picture.sections.single.models.single.node, 'studio');+ expect(daemon.asked, 0);+ });++ test(+ 'every read feeds it, and reads that overlap are one request',+ () async {+ final first = app.refreshGridModels('m');+ final second = app.refreshGridModels('m');+ expect(identical(await first, await second), isTrue);+ expect(daemon.asked, 1);+ expect(+ app.gridPictures['m']!.sections.single.state,+ GridSectionState.awake,+ );+ },+ );++ test(+ 'a read that was out when a push landed does not overwrite the push',+ () async {+ final hold = daemon.hold = Completer<void>();+ final read = app.refreshGridModels('m');+ await app.handleEventForTest('m', {+ 'type': 'grid_models_changed',+ 'payload': _reply(state: 'asleep'),+ });+ hold.complete();+ await read;+ expect(+ app.gridPictures['m']!.sections.single.state,+ GridSectionState.asleep,+ );+ },+ );++ test(+ 'a read that could not reach the machine keeps the last good picture for every surface',+ () async {+ await app.refreshGridModels('m');+ daemon.reply = {'error': 'GRID_MODELS_FAILED'};++ // The caller that must know (the creation check) still hears that the machine did not answer…+ expect((await app.refreshGridModels('m')).reachable, isFalse);+ // …while the picture every other surface shows stays the last list it had.+ final picture = await app.readGridPicture('m');+ expect(picture.reachable, isTrue);+ expect(picture.sections.single.models.single.id, 'Qwen3.5-4B');+ expect(app.gridPictures['m']!.reachable, isTrue);+ },+ );++ test('the foreground flag follows the lifecycle, unknown counting as foreground', () {+ expect(app.inForeground, isTrue);+ app.appLifecycleChanged(AppLifecycleState.inactive);+ expect(app.inForeground, isFalse);+ app.appLifecycleChanged(AppLifecycleState.hidden);+ expect(app.inForeground, isFalse);+ app.appLifecycleChanged(AppLifecycleState.resumed);+ expect(app.inForeground, isTrue);+ app.appLifecycleChanged(null);+ expect(app.inForeground, isTrue);+ });+ });++ group('the Model Manager timer', () {+ late ModelManagerTestApp app;+ setUp(() => app = ModelManagerTestApp(ModelManagerConnection()));+ tearDown(() => app.dispose());++ // Each test owns its controller and disposes it before the test ends: its 4 s timer is a fake+ // timer inside `testWidgets`, and one left running fails the test.+ ModelManagerController manager() =>+ ModelManagerController(app, storage: MemoryStore())+ // The visible panel is the tick that reads every 4 s whatever the clock says — the idle+ // 60 s read compares `DateTime.now()`, which fake time does not move.+ ..setPanelVisible(true);++ testWidgets(+ 'a background app runs none of it, and one refresh runs on return',+ (tester) async {+ final controller = manager();+ app.appLifecycleChanged(AppLifecycleState.hidden);+ controller.start();+ await tester.pump();+ for (var i = 0; i < 30; i++) {+ await tester.pump(const Duration(seconds: 4));+ }+ expect(app.localReads, 0);+ expect(app.gridReads, 0);++ app.appLifecycleChanged(AppLifecycleState.resumed);+ await tester.pump();+ expect(app.localReads, 1);+ expect(app.gridReads, 1);+ controller.dispose();+ await tester.pump(const Duration(seconds: 10));+ },+ );++ testWidgets('in the foreground it reads as it always did', (tester) async {+ final controller = manager();+ controller.start();+ await tester.pump();+ final first = app.localReads;+ expect(first, 1);+ await tester.pump(const Duration(seconds: 4));+ expect(app.localReads, 2);+ controller.dispose();+ await tester.pump(const Duration(seconds: 10));+ });++ testWidgets('a push reaches the manager with no read of its own', (+ tester,+ ) async {+ final controller = manager();+ controller.start();+ await tester.pump();+ final reads = app.gridReads;+ await app.handleEventForTest('m', {+ 'type': 'grid_models_changed',+ 'payload': _reply(ids: ['Pushed-Model']),+ });+ expect(controller.sections.single.models.single.id, 'Pushed-Model');+ expect(app.gridReads, reads);+ controller.dispose();+ await tester.pump(const Duration(seconds: 10));+ });+ });++ group('the pane picker prefetch', () {+ late _Daemon daemon;+ late AppNotifier app;+ setUp(() {+ daemon = _Daemon(_reply());+ app = createApp(connectionForTest: (_) => daemon);+ });+ tearDown(() => app.dispose());++ Future<void> mount(WidgetTester tester) => tester.pumpWidget(+ MaterialApp(+ home: Scaffold(+ body: Center(+ child: GridModelPicker(+ notifier: app,+ machineId: 'm',+ engineLabel: 'claude',+ ),+ ),+ ),+ ),+ );++ testWidgets('does not run in the background, and runs once on return', (+ tester,+ ) async {+ app.appLifecycleChanged(AppLifecycleState.inactive);+ await mount(tester);+ await tester.pump();+ expect(daemon.asked, 0);+ app.appLifecycleChanged(AppLifecycleState.resumed);+ await tester.pump();+ expect(daemon.asked, 1);+ app.appLifecycleChanged(AppLifecycleState.inactive);+ app.appLifecycleChanged(AppLifecycleState.resumed);+ await tester.pump();+ // A picker that is already warm owes nothing on a second return.+ expect(daemon.asked, 1);+ });++ testWidgets('in the foreground it warms as it always did', (tester) async {+ await mount(tester);+ await tester.pump();+ expect(daemon.asked, 1);+ });++ testWidgets('a push lands in the open menu with no request', (+ tester,+ ) async {+ tester.view.physicalSize = const Size(1200, 900);+ tester.view.devicePixelRatio = 1;+ addTearDown(tester.view.reset);+ await mount(tester);+ await tester.tap(find.byType(GridModelPicker));+ await tester.pumpAndSettle();+ expect(find.text('Qwen3.5-4B'), findsOneWidget);+ final asked = daemon.asked;+ await app.handleEventForTest('m', {+ 'type': 'grid_models_changed',+ 'payload': _reply(ids: ['Pushed-Model']),+ });+ await tester.pumpAndSettle();+ expect(find.text('Pushed-Model'), findsOneWidget);+ expect(daemon.asked, asked);+ });+ });-- group('the macOS Models menu', () {- const channel = MethodChannel('harness/swarm_tabs');- late _Daemon daemon;- late AppNotifier app;- late List<MethodCall> messages;- late ModelsMenuController menu;- late UsageController usage;- late SwarmProjectStore projects;-- setUp(() {- daemon = _Daemon(_reply());- app = createApp(connectionForTest: (_) => daemon);- usage = UsageController(sources: const [], autoStart: false);- menu = ModelsMenuController(usage: usage);- projects = SwarmProjectStore();- });- tearDown(() {- menu.dispose();- usage.dispose();- app.dispose();- projects.dispose();- });-- Future<void> mount(WidgetTester tester) async {- final messenger = tester.binding.defaultBinaryMessenger;- messages = <MethodCall>[];- messenger.setMockMethodCallHandler(channel, (call) async {- messages.add(call);- return true;- });- addTearDown(() => messenger.setMockMethodCallHandler(channel, null));- await tester.pumpWidget(- MaterialApp(- home: SwarmScreen(- notifier: app,- nativeTabs: true,- projectStore: projects,- modelsMenu: menu,- ),- ),- );- await tester.pump();- }-- Future<void> native(WidgetTester tester, String method) async {- final reply = Completer<void>();- tester.binding.defaultBinaryMessenger.handlePlatformMessage(- channel.name,- const StandardMethodCodec().encodeMethodCall(MethodCall(method)),- (_) => reply.complete(),- );- await reply.future;- await tester.pump();- }-- List<Map<Object?, Object?>> lastSections() =>- ((messages.lastWhere((c) => c.method == 'modelsState').arguments- as Map)['sections']- as List)- .cast<Map<Object?, Object?>>();-- testWidgets(- 'does not refresh in the background, and refreshes once on return',- (tester) async {- tester.binding.handleAppLifecycleStateChanged(- AppLifecycleState.inactive,- );- addTearDown(- () => tester.binding.handleAppLifecycleStateChanged(- AppLifecycleState.resumed,- ),- );- await mount(tester);- // Every app change asks the menu to refresh; in the background none of them may.- for (var i = 0; i < 5; i++) {- app.notifyListeners();- await tester.pump(const Duration(seconds: 15));- }- expect(daemon.asked, 0);- tester.binding.handleAppLifecycleStateChanged(- AppLifecycleState.resumed,- );- await tester.pump();- expect(daemon.asked, 1);- await tester.pumpWidget(const SizedBox());- },- );-- testWidgets('refreshes when it opens, inside the ten-second throttle', (- tester,- ) async {- await mount(tester);- final before = daemon.asked;- expect(before, 1);- await native(tester, 'modelsOpened');- expect(daemon.asked, before + 1);- await tester.pumpWidget(const SizedBox());- });-- testWidgets('opening it refreshes even when the window reads as inactive', (- tester,- ) async {- await mount(tester);- final before = daemon.asked;- tester.binding.handleAppLifecycleStateChanged(AppLifecycleState.inactive);- addTearDown(- () => tester.binding.handleAppLifecycleStateChanged(- AppLifecycleState.resumed,- ),- );- await tester.pump();- await native(tester, 'modelsOpened');- expect(daemon.asked, before + 1);- await tester.pumpWidget(const SizedBox());- });-- testWidgets('updates when only a node changed', (tester) async {- await mount(tester);- expect(lastSections().single['models'], [- {'id': 'Qwen3.5-4B', 'node': 'macbook'},- ]);- daemon.reply = _reply(node: 'studio');- await native(tester, 'modelsOpened');- expect(lastSections().single['models'], [- {'id': 'Qwen3.5-4B', 'node': 'studio'},- ]);- await tester.pumpWidget(const SizedBox());- });-- testWidgets('updates when only the state changed', (tester) async {- await mount(tester);- expect(lastSections().single['state'], 'awake');- daemon.reply = _reply(state: 'asleep');- await native(tester, 'modelsOpened');- expect(lastSections().single['state'], 'asleep');- await tester.pumpWidget(const SizedBox());- });-- testWidgets('a push updates it with no request', (tester) async {- await mount(tester);- final asked = daemon.asked;- await app.handleEventForTest('m', {- 'type': 'grid_models_changed',- 'payload': _reply(ids: ['Pushed-Model']),- });- await tester.pump();- expect((lastSections().single['models'] as List).single, {- 'id': 'Pushed-Model',- 'node': 'macbook',- });- expect(daemon.asked, asked);- await tester.pumpWidget(const SizedBox());- });-- testWidgets('an older daemon sends no state, and the menu says none', (- tester,- ) async {- daemon.reply = _reply(withNewFields: false);- await mount(tester);- expect(lastSections().single.containsKey('state'), isFalse);- await tester.pumpWidget(const SizedBox());- });- });+}