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
Linux test steps open only where the project can test on Linux (#4278) (#3484)
0xken15db2c0f00f474
diff --git a/backend/integration/superTabReviewSteps.test.ts b/backend/integration/superTabReviewSteps.test.tsindex 9efac54f8..8d8569ef3 100644--- a/backend/integration/superTabReviewSteps.test.ts+++ b/backend/integration/superTabReviewSteps.test.ts@@ -32,6 +32,8 @@ beforeAll(async () => {for (const user of [owner, host]) await db.user.create({ data: { id: user.sub, externalId: `fixture-${user.sub}`, email: user.email, autonomousEnv: user.autonomousEnv } })await db.machine.create({ data: { machineId: 'review-host', userId: host.sub, apiKey: 'fixture-review-host', managerId: 'fixture', autonomousEnv: 'prod', authMode: 'remote' } })await db.machineShare.create({ data: { machineId: 'review-host', ownerId: host.sub, autonomousEnv: 'prod', emails: [owner.email] } })+ await db.machine.create({ data: { machineId: 'linux-host', userId: host.sub, apiKey: 'fixture-linux-host', managerId: 'fixture', autonomousEnv: 'prod', authMode: 'remote' } })+ await db.machineShare.create({ data: { machineId: 'linux-host', ownerId: host.sub, autonomousEnv: 'prod', emails: [owner.email] } })})afterAll(async () => {await db?.$disconnect()@@ -47,11 +49,14 @@ async function swarm(hooks: SuperTabStoreHooks) {await execute({ type: 'invite.accept', inviteId: invitation.result.inviteId as string }, host)await execute({ type: 'machine.contribute', machineId: 'review-host', name: 'Review Mac', cwd: '/repo', engines: ['claude'], maxAgents: 8 }, host)// It reports as a live machine does, so its own agents can take steps (reviewSeats.ts canStart): they are its person's own (task #4120).- const generation = (await poolRows(store, host, 'review-host')).find(p => p.tabId === tab)!.machine.generation- await store.observeMachine(host, tab, 'review-host', { generation, resources: { cpuPercent: 10, memoryTotalBytes: 32e9, memoryUsedBytes: 4e9,- diskFreeBytes: 120e9, diskTotalBytes: 500e9, projectDiskFreeBytes: 120e9, deviceType: 'Laptop', chip: 'Fixture', os: 'macOS', gpuPercent: null },- quotas: [{ engine: 'claude', known: true, windows: [{ name: 'weekly', usedPercent: 10, resetsAt: null }] }], tools: {}, runningHarnessIds: [], stoppedHarnessIds: [],- readiness: { engines: [{ engine: 'claude', installed: true, signedIn: true }] } } as never)+ const observe = async (machineId: string, os: string) => {+ const generation = (await poolRows(store, host, machineId)).find(p => p.tabId === tab)!.machine.generation+ await store.observeMachine(host, tab, machineId, { generation, resources: { cpuPercent: 10, memoryTotalBytes: 32e9, memoryUsedBytes: 4e9,+ diskFreeBytes: 120e9, diskTotalBytes: 500e9, projectDiskFreeBytes: 120e9, deviceType: 'Laptop', chip: 'Fixture', os, gpuPercent: null },+ quotas: [{ engine: 'claude', known: true, windows: [{ name: 'weekly', usedPercent: 10, resetsAt: null }] }], tools: {}, runningHarnessIds: [], stoppedHarnessIds: [],+ readiness: { engines: [{ engine: 'claude', installed: true, signedIn: true }] } } as never)+ }+ await observe('review-host', 'macOS')const add = async (conversationId: string, name: string, lead = false, roleName?: string) => String((await execute({ type: 'agent.add',conversationId, machineId: 'review-host', harnessId: randomUUID(), name, configuration: opus, lead, ...roleName ? { roleName } : {} } as Command, host)).result.agentId)const lead = await add('lead', 'PM', true)@@ -59,7 +64,7 @@ async function swarm(hooks: SuperTabStoreHooks) {const dev = await add(task, 'Dev', false, 'Engineer')const reviewers = [await add(task, 'Rev A', false, 'Reviewer'), await add(task, 'Rev B', false, 'Reviewer')]const assignment = String((await execute({ type: 'work.assign', conversationId: task, agentId: dev })).result.assignmentId)- return { store, tab, execute, lead, task, dev, reviewers, assignment }+ return { store, tab, execute, observe, lead, task, dev, reviewers, assignment }}const stepsIn = async (tab: string, task: string) => (await db.swarmGroup.findMany({ where: { tabId: tab } }))@@ -115,6 +120,31 @@ describe('a Ready through the store', () => {expect(await stepsIn(tab, task)).toEqual([])})+ // Task #4278: with no Linux machine the project can reach, a CLI change's Linux test waits and the task says why; once the+ // PM's person's Linux computer reports, the time checks open it.+ it('opens a CLI change\'s Linux test only once a Linux machine is there', async () => {+ const head = 'c'.repeat(40)+ const { store, tab, execute, observe, task, dev, assignment } = await swarm({ pullRequestFiles: async (_repository, urls) => ({ urls, head,+ files: ['cli/src/superTabs/host.ts'] }) })+ await execute({ type: 'work.status', conversationId: task, assignmentId: assignment, status: 'review', result: `Ready: ${REPO}/pull/7` }, host, dev)+ expect((await stepsIn(tab, task)).map(step => step.step).sort()).toEqual(['Review', 'Test on a Mac'])+ const said = await db.superTabMessage.findMany({ where: { tabId: tab, conversationId: task } })+ expect(said.filter(row => row.text === 'No Linux machine: CI\'s Linux runs stand in.')).toHaveLength(1)+ await store.runTimeChecks(tab)+ expect((await stepsIn(tab, task)).map(step => step.step).sort()).toEqual(['Review', 'Test on a Mac'])+ await execute({ type: 'machine.contribute', machineId: 'linux-host', name: 'Linux box', cwd: '/repo', engines: ['claude'], maxAgents: 8 }, host)+ await observe('linux-host', 'Linux')+ await store.runTimeChecks(tab)+ const steps = await stepsIn(tab, task)+ expect(steps.map(step => step.step).sort()).toEqual(['Review', 'Test on a Linux machine', 'Test on a Mac'])+ const linux = (await db.swarmGroup.findMany({ where: { tabId: tab } })).map(row => row.data as { id: string; step?: string; brief?: string })+ .find(group => group.step === 'Test on a Linux machine')!+ expect(linux.brief).toContain(head)+ const listed = ((await db.swarmGroup.findFirstOrThrow({ where: { tabId: tab, key: task } })).data as { stepIds?: string[]; waitingLinuxStep?: unknown })+ expect(listed.stepIds).toContain(linux.id)+ expect(listed.waitingLinuxStep).toBeUndefined()+ })+it('opens the strictest steps when the read throws, and the Ready still goes through', async () => {const pullRequestFiles = vi.fn(async () => { throw new Error('GitHub down') })const { tab, execute, task, dev, assignment } = await swarm({ pullRequestFiles })diff --git a/backend/src/superTabs/commands.ts b/backend/src/superTabs/commands.tsindex 81934ab0e..ca1d0b53b 100644--- a/backend/src/superTabs/commands.ts+++ b/backend/src/superTabs/commands.ts@@ -24,10 +24,12 @@ import {type Actor, type AgentConfiguration, type AgentStart, type AgentStartRequest, type BuddySessionEntry, type WorkTask, type Agent, type Author, type Check, type CommandEffects, type Conversation, type SuperTabState,} from './model.js'import { jobKindOf } from './evidence/jobKind.js'-import { endSteps, stepEndedRows, isStep, stepName, stepsOf, taskOwner } from './steps.js'+import { endSteps, listStep, stepEndedRows, isStep, stepName, stepsOf, taskOwner } from './steps.js'import { closeMerged } from './mergedTasks.js'import { noteWriter } from './stuck.js'-import { reviewPlan, stepBrief, stepCheck, refreshStepBrief, type PlannedStep, type StepKind } from './reviewTable.js'+import { reviewPlan, refreshStepBrief, type PlannedStep, type StepKind } from './reviewTable.js'+import { openReviewStep, type StepPull } from './stepOpen.js'+import { LINUX_WAIT_LINE, testsOnLinux, waitForLinux } from './linuxSteps.js'import { builtBy, reviewerCandidates, STRENGTH_RULE } from './reviewerPick.js'import { checkedPullRequest, deriveCheck, recordCheckVerdict } from './checkVerdicts.js'import { routeRecordSchema, routeTitle, startedAs, type KeptCandidate, type RouteDecision, type RouteFinal, type RouteOverride } from './routeRecord.js'@@ -93,14 +95,6 @@ import { inThread, leadsGroup, recordAnswered, requireUnanswered } from './answeimport { laneNamed, pinBuilder, spokenList, stampLane } from './dispatch.js'const id = z.string().min(1).max(160).regex(/^[A-Za-z0-9_-]+$/)-/** The most steps a task lists (Conversation.stepIds): production's most was 14 (2026-11-05). */-const STEPS_LISTED = 200-/** [task] lists its new step [id], so a new head of its pull request re-derives the step's checks even once it is dormant- * (#3394), however the step opened (conversation.create, or a Ready's review steps). A task from before lists none until its- * PR watch looks its dormant steps up (review of #3218, round 3): listing only this one would hide those. */-function listStep(task: Conversation, id: string): void {- if (task.stepIds) task.stepIds = [...task.stepIds, id].slice(-STEPS_LISTED)-}/** A route override's reason when its agent gave none, on a decision whose chosen candidate was not a pick (a person's choice, or an older record). */const NO_REASON = 'No reason given.'/** What a pick-less route's only candidate is chosen for, when its start gives no reason (task #2901). */@@ -1951,24 +1945,11 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,const name = stepName(step)return /security/i.test(name) ? 'security' : /test/i.test(name) ? 'test' : /review|read/i.test(name) ? 'review' : null}- /** A new step [planned] of [task], opened as conversation.create opens one with `reviewOf` and `step`. */- const openStep = (task: Conversation, planned: PlannedStep, read: NonNullable<CommandContext['pullRequestFiles']>) => {- const project = groupProject(state, task)- const leadId = conversation(state, project.leadConversationId).leadId- const id = stableId(operationId, 'review-step', planned.name)- const number = nextConversationNumber(state)- state.groupCounter = number- const pulls = read.heads ?? read.urls.map((url, i) => ({ url, head: i === 0 ? read.head : null }))- const brief = stepBrief(planned, { number: task.number ?? number, title: task.title, pulls })- state.conversations.push({ id, ...(state.projects ? { projectId: project.id } : {}), number, title: planned.name, leadId,- agentIds: leadId ? [leadId] : [], archived: false, brief, reviewOf: task.id,- // A step keeps its task's mark, as conversation.create's does (teamWritten.ts stepMark).- ...stepMark(state, task), step: planned.name, openedBy: 'server',- assignment: null, lastMessageSequence: 0, codePullRequestUrls: [], checks: storedChecks([{ description: stepCheck(planned), independent: true }], id) })- const step = state.conversations.at(-1)!- listStep(task, id)- message(id, brief, [], null, SYSTEM_ROW, undefined, undefined, undefined, stableId(id, 'brief'))- bindTaskCard(step, effects.messages.at(-1)!)+ /** A new step [planned] of [task] (stepOpen.ts), its brief written as the sender. */+ const openStep = (task: Conversation, planned: PlannedStep, pulls: readonly StepPull[]) => {+ const { step, brief } = openReviewStep(state, task, planned, pulls, stableId(operationId, 'review-step', planned.name), sender)+ effects.messages.push(brief)+ result.messageId = operationIdreturn step}/**@@ -1981,19 +1962,28 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,const openReviewSteps = (task: Conversation, read: NonNullable<CommandContext['pullRequestFiles']>) => {const existing = stepsOf(state, task.id).filter(step => !step.archived)const taken = new Set<string>(), unassigned: Array<{ name: string; kind: StepKind }> = []+ const pulls = read.heads ?? read.urls.map((url, i) => ({ url, head: i === 0 ? read.head : null }))for (const planned of reviewPlan(read.files, context.projectRules?.rules)) {const free = (step: Conversation) => !taken.has(step.id)let step = existing.find(s => free(s) && stepName(s) === planned.name) ?? existing.find(s => free(s) && stepKind(s) === planned.kind)if (step) {taken.add(step.id)- step.brief = refreshStepBrief(step.brief ?? '', planned, { number: task.number!, title: task.title,- pulls: read.heads ?? read.urls.map((url, i) => ({ url, head: i === 0 ? read.head : null })) })+ step.brief = refreshStepBrief(step.brief ?? '', planned, { number: task.number!, title: task.title, pulls })+ }+ // A new Linux step opens only where the project can test on Linux (linuxSteps.ts, task #4278): else it waits, and the+ // task says once that CI's Linux runs stand in. A step the PM closed is not open, so a later head never brings it back.+ if (!step && planned.os === 'linux') {+ if (!testsOnLinux(state, groupProject(state, task), context.now)) {+ if (waitForLinux(task, planned, pulls)) message(task.id, LINUX_WAIT_LINE, [], null, SYSTEM_ROW, undefined, undefined, undefined, stableId(operationId, 'linux-wait'))+ continue+ }+ delete task.waitingLinuxStep}if (step && activeWork(step)) continue// A step whose every check passed at this very head keeps its verdict: a repeated Ready (a CI rerun) asks nothing again.if (step && read.head && step.checks.length && step.checks.every(check => check.passedBy&& (check.verdicts ?? []).some(verdict => verdict.passed && (verdict as { head?: string }).head === read.head))) continue- step ??= openStep(task, planned, read)+ step ??= openStep(task, planned, pulls)const previous = step.assignment?.agentIdconst ranked = reviewerCandidates(state, task, planned.kind, read.head, context.now, planned.os)const ordered = [...ranked.filter(a => a.id === previous), ...ranked.filter(a => a.id !== previous)]diff --git a/backend/src/superTabs/linuxSteps.test.ts b/backend/src/superTabs/linuxSteps.test.tsnew file mode 100644index 000000000..01185d6e9--- /dev/null+++ b/backend/src/superTabs/linuxSteps.test.ts@@ -0,0 +1,150 @@+import { describe, expect, it } from 'vitest'+import { applyCommand, type Command, type CommandContext } from './commands.js'+import { createSuperTab, type Actor, type AgentConfiguration } from './model.js'+import { stepsOf } from './steps.js'+import { openWaitingSteps } from './linuxSteps.js'++// Task #4278: since v3 (#4120) a Tester starts only on its own person's computer, and no own-account Linux machine could take+// harness's Linux test steps, yet every new head opened one and the PM closed it by hand (#4204, #4215, #4216, #4217, #4252,+// #4259 on 11-07).+const owner: Extract<Actor, { kind: 'person' }> = { kind: 'person', userId: 'owner', email: '[email protected]' }+const opus: AgentConfiguration = { engine: 'claude', model: 'opus', effort: 'high', contextWindow: 200000, engineVersion: 'fixture' }+const PR = 'https://github.com/acme/app/pull/7'+const LINE = 'No Linux machine: CI\'s Linux runs stand in.'+const NOW = 1_000_000++/** A machine as its reading lists it: online, signed in, with quota. */+const machine = (machineId: string, os: string, contributorId = 'owner', extra: Record<string, unknown> = {}) => ({ machineId, name: machineId, contributorId,+ membershipGeneration: 'g', generation: 'g1', cwd: '/swarm', scope: 'swarm', engines: ['claude'], maxAgents: 4, paused: false,+ observation: { generation: 'g1', receivedAt: NOW - 1000, sessionKind: 'computer', resources: { os }, tools: {}, runningHarnessIds: [], stoppedHarnessIds: [],+ readiness: { engines: [{ engine: 'claude', installed: true, signedIn: true }] },+ quotas: [{ engine: 'claude', known: true, windows: [{ name: 'weekly', usedPercent: 10, resetsAt: null }] }] }, ...extra })++/** The PM's person is `owner`: its PM, Engineer and Mac Tester run on owner's Mac. */+function fixture() {+ let state = createSuperTab('tab', 'Pilot', { id: 'owner', email: owner.email }, 'prod')+ let sequence = 0+ const rows: Array<{ conversationId: string; text: string; recipients: string[] }> = []+ const run = (command: Command, actor: Actor = owner, context: Partial<CommandContext> = {}) => {+ const effects = applyCommand(state, actor, command, { now: NOW, operationId: `op-${++sequence}`, ...context })+ state = effects.state+ rows.push(...effects.messages)+ return effects+ }+ const as = (agentId: string): Actor => ({ kind: 'agent', agentId, machineOwnerId: 'host-owner' })+ const add = (harnessId: string, group: string, machineId: string, roleName?: string, lead = false) => run({ type: 'agent.add', conversationId: group, machineId,+ harnessId, name: harnessId, configuration: opus, lead, ...roleName ? { roleName } : {} } as Command, owner,+ { contribution: { machineOwnerId: 'host-owner', contributorId: 'owner' } }).result.agentId as string+ const lead = add('pm', 'lead', 'mac1', undefined, true)+ const task = run({ type: 'conversation.create', title: 'Fix the host', brief: 'The host restarts cleanly.', checks: [{ description: 'Restarts', independent: true }],+ priority: 'P2', requesterId: 'owner' }, as(lead)).result.conversationId as string+ const dev = add('dev', task, 'mac1', 'Engineer')+ run({ type: 'work.assign', conversationId: task, agentId: dev }, as(lead))+ add('rev', task, 'mac1', 'Reviewer')+ add('mac-tst', task, 'mac1', 'Tester')+ const group = (id: string) => state.conversations.find(c => c.id === id)!+ const ready = (head: string) => run({ type: 'work.status', conversationId: task, assignmentId: group(task).assignment!.id, status: 'review',+ result: `Ready: ${PR}` } as Command, as(dev), { pullRequestFiles: { urls: [PR], head, files: ['cli/src/superTabs/host.ts'] } })+ const steps = () => stepsOf(state, task).filter(step => !step.archived).map(step => step.step)+ const lines = () => rows.filter(row => row.conversationId === task && row.text === LINE)+ const machines = (...list: unknown[]) => { state.machines = [machine('mac1', 'macOS'), ...list] as never }+ return { run, as, add, lead, task, dev, group, ready, steps, lines, machines, get state() { return state } }+}++describe('a Ready opens a Linux test step only where the project can test on Linux', () => {+ it('with only a Mac, opens the Mac test and no Linux one, and the task says why once', () => {+ const f = fixture()+ f.machines()+ f.ready('a'.repeat(40))+ expect(f.steps()).toEqual(['Review', 'Test on a Mac'])+ expect(f.lines()).toHaveLength(1)+ // A second head opens no Linux step and says it no second time.+ f.ready('b'.repeat(40))+ expect(f.steps()).toEqual(['Review', 'Test on a Mac'])+ expect(f.lines()).toHaveLength(1)+ })++ it('counts no Linux machine that no Tester of the project can reach', () => {+ const cases = {+ 'another person\'s, with no agent of the project': machine('linux1', 'Linux', 'dan'),+ 'a Team account\'s': machine('linux1', 'Linux', 'owner', { hostMachineId: 'mac1' }),+ 'offline': machine('linux1', 'Linux', 'owner', { observation: { ...machine('linux1', 'Linux').observation, receivedAt: NOW - 10 * 60_000 } }),+ 'paused': machine('linux1', 'Linux', 'owner', { paused: true }),+ 'kept for other projects': machine('linux1', 'Linux', 'owner', { projects: ['other'] }),+ }+ for (const [why, linux] of Object.entries(cases)) {+ const f = fixture()+ f.machines(linux)+ f.ready('a'.repeat(40))+ expect(f.steps(), why).toEqual(['Review', 'Test on a Mac'])+ expect(f.lines(), why).toHaveLength(1)+ }+ })++ it('opens it on the PM\'s person\'s own Linux computer, where the PM may start a Tester', () => {+ const f = fixture()+ f.machines(machine('linux1', 'Linux'))+ f.ready('a'.repeat(40))+ expect(f.steps()).toEqual(['Review', 'Test on a Mac', 'Test on a Linux machine'])+ expect(f.lines()).toHaveLength(0)+ })++ it('opens it on another person\'s Linux machine where their own agent of this project runs', () => {+ const f = fixture()+ const theirs = f.add('dan-tst', f.task, 'linux1', 'Tester')+ const agent = f.state.agents.find(a => a.id === theirs)!+ agent.contributorId = 'dan'+ f.machines(machine('linux1', 'Linux', 'dan'))+ f.ready('a'.repeat(40))+ expect(f.steps()).toEqual(['Review', 'Test on a Mac', 'Test on a Linux machine'])+ expect(f.lines()).toHaveLength(0)+ })++ it('never reopens at a later head a Linux step the PM closed while no Linux machine was there', () => {+ const f = fixture()+ f.machines(machine('linux1', 'Linux'))+ f.ready('a'.repeat(40))+ const linux = stepsOf(f.state, f.task).find(step => step.step === 'Test on a Linux machine')!+ // The machine leaves; nobody can take the step, and the PM closes it.+ f.machines()+ f.run({ type: 'conversation.archive', conversationId: linux.id, archived: true } as Command, f.as(f.lead))+ f.ready('b'.repeat(40))+ expect(f.steps()).toEqual(['Review', 'Test on a Mac'])+ expect(f.lines()).toHaveLength(1)+ })+})++describe('a waiting Linux step opens once a Linux machine is there', () => {+ it('opens nothing while none is, then opens it at the recorded head and tells the PM, once', () => {+ const f = fixture()+ f.machines()+ const head = 'a'.repeat(40)+ f.ready(head)+ const state = f.state+ expect(openWaitingSteps(state, NOW)).toEqual([])+ expect(f.steps()).toEqual(['Review', 'Test on a Mac'])+ // The PM's person's Linux computer reports.+ state.machines = [machine('mac1', 'macOS'), machine('linux1', 'Linux')] as never+ const rows = openWaitingSteps(state, NOW)+ const linux = stepsOf(state, f.task).filter(step => step.step === 'Test on a Linux machine')+ expect(linux).toHaveLength(1)+ expect(linux[0]!.brief).toContain(head)+ expect(rows.find(row => row.conversationId === linux[0]!.id)!.text).toBe(linux[0]!.brief)+ expect(rows.find(row => row.conversationId === f.task)!.recipients).toEqual([f.lead])+ expect(state.conversations.find(c => c.id === f.task)!.waitingLinuxStep).toBeUndefined()+ // A second pass opens nothing more.+ expect(openWaitingSteps(state, NOW)).toEqual([])+ expect(stepsOf(state, f.task).filter(step => step.step === 'Test on a Linux machine')).toHaveLength(1)+ })++ it('keeps waiting on a task that is no longer open', () => {+ const f = fixture()+ f.machines()+ f.ready('a'.repeat(40))+ const state = f.state+ state.conversations.find(c => c.id === f.task)!.assignment!.status = 'done'+ state.machines = [machine('mac1', 'macOS'), machine('linux1', 'Linux')] as never+ expect(openWaitingSteps(state, NOW)).toEqual([])+ expect(stepsOf(state, f.task).some(step => step.step === 'Test on a Linux machine')).toBe(false)+ })+})diff --git a/backend/src/superTabs/linuxSteps.ts b/backend/src/superTabs/linuxSteps.tsnew file mode 100644index 000000000..6fa78f9ed--- /dev/null+++ b/backend/src/superTabs/linuxSteps.ts@@ -0,0 +1,69 @@+/**+ * A Linux test step waits for a Linux machine (task #4278). Since v3 (#4120) a Tester starts only on its own person's+ * computer and a Team account takes no work, so harness's Linux steps had nobody who could take them, yet every new head+ * opened one and the PM closed it by hand (#4204, #4215, #4216, #4217, #4252, #4259 on 11-07). A Ready now opens one only+ * where the project can test on Linux; otherwise CI's Linux unit checks stand in, the task says so once, and the time checks+ * open the step once such a machine is there. Mac and Windows steps open as before (the task's constraint).+ */+import { agentDisplayName } from './agentNames.js'+import { isBuddy } from './buddies.js'+import { machineOffline, machineProjectRefusal, swarmMachines } from './machines.js'+import { activeWork, stableId, type Author, type Conversation, type MessageDraft, type SuperTabState } from './model.js'+import { agentProjectId, groupProject, onTeamAccount, teamAccountPool, type SwarmProject } from './projects.js'+import { reportsOs, type PlannedStep } from './reviewTable.js'+import { openReviewStep, type StepPull } from './stepOpen.js'+import { stepName, stepsOf } from './steps.js'++/** What the task says while its Linux step waits. */+export const LINUX_WAIT_LINE = 'No Linux machine: CI\'s Linux runs stand in.'++/** A task's Linux test step that waits for a Linux machine, with the pull requests its brief names (no history: the brief+ * says it is unknown). One per task, replaced at each Ready, gone once the step opens. */+export interface WaitingStep { step: PlannedStep; pulls: StepPull[] }++const coordinatorOf = (state: SuperTabState, project: SwarmProject) =>+ state.agents.find(a => a.id === state.conversations.find(c => c.id === project.leadConversationId)?.leadId)++/**+ * Whether [project] can test on Linux at [now]: an own-account machine reports Linux, online, not paused or being removed,+ * open to the project, and a Tester can get there: it is the PM's own person's computer, where the PM may start one, or an+ * own-account agent of the project runs there as that machine's person.+ */+export function testsOnLinux(state: SuperTabState, project: SwarmProject, now: number): boolean {+ const pm = coordinatorOf(state, project)+ return swarmMachines(state).some(pool => reportsOs(pool.observation?.resources?.os, 'linux') && !machineOffline(pool, now) && !pool.paused+ && !pool.removal && !teamAccountPool(pool) && !machineProjectRefusal(state, pool.machineId, project)+ && (pool.contributorId === pm?.contributorId || state.agents.some(a => a.machineId === pool.machineId && a.contributorId === pool.contributorId+ && !isBuddy(a) && a.workDecision !== 'stop' && !onTeamAccount(state, a) && agentProjectId(state, a) === project.id)))+}++/** Records [step] of [task] as waiting for a Linux machine, briefed on [pulls]; true when it was not waiting yet, so the+ * task is told once. */+export function waitForLinux(task: Conversation, step: PlannedStep, pulls: readonly StepPull[]): boolean {+ const first = !task.waitingLinuxStep+ task.waitingLinuxStep = { step, pulls: pulls.map(({ url, head, base }) => ({ url, head, ...base ? { base } : {} })) }+ return first+}++/**+ * The time checks' pass (store.ts runTimeChecks): each open task's waiting Linux step opens once its project can test on+ * Linux, and the PM hears it in the task, to give it a Tester there. Written as the PM; a project with none keeps waiting.+ */+export function openWaitingSteps(state: SuperTabState, now: number): MessageDraft[] {+ const waiting = state.conversations.filter(task => task.waitingLinuxStep && !task.archived && activeWork(task))+ const can = new Map<string, boolean>()+ const linux = (project: SwarmProject) => can.get(project.id) ?? can.set(project.id, testsOnLinux(state, project, now)).get(project.id)!+ return waiting.flatMap(task => {+ const project = groupProject(state, task), pm = coordinatorOf(state, project)+ if (!pm || !linux(project)) return []+ const { step, pulls } = task.waitingLinuxStep!+ delete task.waitingLinuxStep+ // One its PM opened by hand meanwhile is that step.+ if (stepsOf(state, task.id).some(s => !s.archived && stepName(s) === step.name)) return []+ const author: Author = { kind: 'agent', id: pm.id, name: pm.name, displayName: agentDisplayName(state.agents, pm.id), membershipGeneration: pm.membershipGeneration }+ const id = stableId(task.id, 'linux-step', ...pulls.map(pull => pull.head ?? ''))+ const { brief } = openReviewStep(state, task, step, pulls, id, author)+ return [brief, { id: stableId(id, 'told'), conversationId: task.id, author, replyTo: null, recipients: [pm.id], source: { kind: 'system' },+ text: `${step.name} of #${task.number} is open: a Linux machine is here now. Give it a Tester there.` }]+ })+}diff --git a/backend/src/superTabs/model.ts b/backend/src/superTabs/model.tsindex b1974ac7a..e0bb0e454 100644--- a/backend/src/superTabs/model.ts+++ b/backend/src/superTabs/model.ts@@ -475,6 +475,9 @@ export interface Conversation {* pull request head re-derives the checks of, dormant ones included (#3394). Empty from a task's start; absent on a task* from before, whose PR watch looks them up once (pullRequestEvents.ts listedSteps). */stepIds?: string[]+ /** Its Linux test step, waiting for a Linux machine the project can test on (linuxSteps.ts, task #4278): set by a Ready that+ * found none, gone once the step opens. */+ waitingLinuxStep?: import('./linuxSteps.js').WaitingStep/** Its messages drawn as live cards: its task and each linked pull request (cards.ts). Absent until its first card. */cards?: import('./cards.js').GroupCards/** The last sequence given to a message here. Each conversation numbers its own messages (store by parts). */diff --git a/backend/src/superTabs/parts/light.test.ts b/backend/src/superTabs/parts/light.test.tsindex bc5db71be..ade5d0313 100644--- a/backend/src/superTabs/parts/light.test.ts+++ b/backend/src/superTabs/parts/light.test.ts@@ -96,6 +96,7 @@ const conversation: Required<Conversation> = {teamWrittenBy: { kind: 'assigned' },title: 't',unlinkedPullRequests: [],+ waitingLinuxStep: { step: { name: 'Test on a Linux machine', kind: 'test', areas: [], where: ['The CLI on a Linux machine'], os: 'linux' }, pulls: [] },writers: [],}diff --git a/backend/src/superTabs/parts/light.ts b/backend/src/superTabs/parts/light.tsindex 42e140f53..bf2db34dc 100644--- a/backend/src/superTabs/parts/light.ts+++ b/backend/src/superTabs/parts/light.ts@@ -116,6 +116,7 @@ export const GROUP_FIELDS = {'teamWritten','teamWrittenBy','unlinkedPullRequests',+ 'waitingLinuxStep','writers',],} as constdiff --git a/backend/src/superTabs/stepOpen.ts b/backend/src/superTabs/stepOpen.tsnew file mode 100644index 000000000..a47491639--- /dev/null+++ b/backend/src/superTabs/stepOpen.ts@@ -0,0 +1,34 @@+/**+ * Opening a planned review step (task #3401), as conversation.create opens one with `reviewOf` and `step`: a Ready opens its+ * steps here, and so do the time checks for a Linux step that waited for a Linux machine (linuxSteps.ts, task #4278).+ */+import { bindTaskCard } from './cards.js'+import { nextConversationNumber, stableId, type Author, type Conversation, type MessageDraft, type SuperTabState } from './model.js'+import { groupProject } from './projects.js'+import { stepBrief, stepCheck, type PlannedStep } from './reviewTable.js'+import { listStep } from './steps.js'+import { stepMark } from './teamWritten.js'++/** A pull request a step's brief names, at the head and base its files were read at. */+export interface StepPull { url: string; head: string | null; base?: string | null; history?: import('./prHistory.js').HistoryReport }++/** Opens step [planned] of [task] as [id], briefed on [pulls]: the step, and its brief written as [author], which is its card. */+export function openReviewStep(state: SuperTabState, task: Conversation, planned: PlannedStep, pulls: readonly StepPull[], id: string,+ author: Author): { step: Conversation; brief: MessageDraft } {+ const project = groupProject(state, task)+ const leadId = state.conversations.find(c => c.id === project.leadConversationId)?.leadId ?? null+ const number = nextConversationNumber(state)+ state.groupCounter = number+ const text = stepBrief(planned, { number: task.number ?? number, title: task.title, pulls })+ state.conversations.push({ id, ...(state.projects ? { projectId: project.id } : {}), number, title: planned.name, leadId,+ agentIds: leadId ? [leadId] : [], archived: false, brief: text, reviewOf: task.id,+ // A step keeps its task's mark, as conversation.create's does (teamWritten.ts stepMark).+ ...stepMark(state, task), step: planned.name, openedBy: 'server',+ assignment: null, lastMessageSequence: 0, codePullRequestUrls: [],+ checks: [{ description: stepCheck(planned), independent: true, id: stableId(id, '0'), evidence: null, passedBy: null }] })+ const step = state.conversations.at(-1)!+ listStep(task, id)+ const brief: MessageDraft = { id: stableId(id, 'brief'), conversationId: id, author, text, replyTo: null, recipients: [], source: { kind: 'system' } }+ bindTaskCard(step, brief)+ return { step, brief }+}diff --git a/backend/src/superTabs/steps.ts b/backend/src/superTabs/steps.tsindex 24dd6854e..aa0961808 100644--- a/backend/src/superTabs/steps.ts+++ b/backend/src/superTabs/steps.ts@@ -19,6 +19,15 @@ export const stepName = (group: Pick<Conversation, 'step' | 'title'>): string =>export const taskEnded = (state: SuperTabState, step: Pick<Conversation, 'reviewOf'>): boolean =>['done', 'cancelled'].includes(state.conversations.find(c => c.id === step.reviewOf)?.assignment?.status ?? '')+/** The most steps a task lists (Conversation.stepIds): production's most was 14 (2026-11-05). */+const STEPS_LISTED = 200+/** [task] lists its new step [id], so a new head of its pull request re-derives the step's checks even once it is dormant+ * (#3394), however the step opened (conversation.create, or a Ready's review steps). A task from before lists none until its+ * PR watch looks its dormant steps up (review of #3218, round 3): listing only this one would hide those. */+export function listStep(task: Conversation, id: string): void {+ if (task.stepIds) task.stepIds = [...task.stepIds, id].slice(-STEPS_LISTED)+}+/** The steps of task [taskId], in creation order. */export const stepsOf = (state: SuperTabState, taskId: string): Conversation[] =>state.conversations.filter(c => c.reviewOf === taskId)diff --git a/backend/src/superTabs/store.ts b/backend/src/superTabs/store.tsindex 7d327e8f8..26e895a83 100644--- a/backend/src/superTabs/store.ts+++ b/backend/src/superTabs/store.ts@@ -81,6 +81,7 @@ import { RefusalMemory } from './dispatchRefusals.js'import { tasksHoldingMoves } from './ruleGuard.js'import { candidatesFor, dispatchRules, DISPATCH_RULES, dispatchPlan, freeCrew, laneCapacity, openTasks, pinBuilder, pullRequestPin, roundOf, type DispatchLookup, type DispatchRules, type Skip } from './dispatch.js'import { buddySleepCandidates, sleepBuddies } from './buddySleep.js'+import { openWaitingSteps } from './linuxSteps.js'import { failRefusedStarts, judgedMachines, loseTasks, nextLossAt, recordTaskState, sweepForLead, sweepLiveness, SWEEP_EVERY_MS, unpurgedNotice } from './liveness.js'import { endedReply, taskLineChats } from './taskLine.js'import { owedAsk } from './timeChecks.js'@@ -5595,7 +5596,8 @@ export class SuperTabStore {if (chats.length) loaded = await this.ensure(tx, loaded, { groupIds: [...loaded.state.conversations.map(c => c.id), ...chats] })const state = cloneData(loaded.state), now = this.now()const rulesFor = await this.projectDispatch(tx, state)- const written = [...sweepForLead(state, now, rulesFor), ...advanceProposalCards(state, now)]+ // A Linux test step that waited for a Linux machine opens once one is there (linuxSteps.ts, task #4278).+ const written = [...sweepForLead(state, now, rulesFor), ...advanceProposalCards(state, now), ...openWaitingSteps(state, now)]for (const [id, bodies] of migration) written.push(...migrateLegacyProposals(state, projectsOf(state).find(p => p.id === id)!, bodies, now))// What waits for each agent: an agent with a delivery open is not idle. Only loaded groups' active work keeps an agent// from being idle (project instructions, phase 4).diff --git a/docs/plans/2026-11-07-linux-test-steps-plan.md b/docs/plans/2026-11-07-linux-test-steps-plan.mdnew file mode 100644index 000000000..64690b8a8--- /dev/null+++ b/docs/plans/2026-11-07-linux-test-steps-plan.md@@ -0,0 +1,95 @@+# Linux test steps open only where the project can test on Linux (task #4278)++> Written by the Engineer, following writing-plans; implemented test first by the same Engineer, task by task.++**Goal:** A Ready opens a "Test on a Linux machine" step only when the project has a reachable own-account Linux machine.+Otherwise the task says "No Linux machine: CI's Linux runs stand in.", the step waits on the task, and it opens by itself+once such a machine is there. A later head never reopens a Linux step the PM closed while no Linux machine existed.++**Architecture:** `reviewTable.ts reviewPlan` keeps planning the step. `commands.ts openReviewSteps` asks the new+`linuxSteps.ts` whether the project can test on Linux before it opens a new Linux step; when it cannot, the planned step+and its pull requests are recorded on the task (`Conversation.osWaiting`) and one line is written in the task. The 30-second+time checks (`store.ts runTimeChecks`) call `linuxSteps.ts openWaitingSteps`, which opens each waiting step whose machine+is now there and tells the PM in the task. Opening a step moves out of the `commands.ts` closure into `stepOpen.ts`, so the+Ready and the time checks open steps the same way.++**Tech Stack:** TypeScript backend, vitest unit tests, MongoDB integration tests through `SuperTabStore`.++**Spec:** the task brief (River, 2026-11-07): "When review steps open, open an OS test step only if the project has a+reachable own-account machine of that OS. Otherwise don't open it: mark the card 'No Linux machine: CI's Linux runs stand+in', and open the step automatically once such a machine joins. Never reopen a step the PM closed for this reason at a later+head of the same task. Real-store tests." Constraints: backend only; Mac and Windows rules stay as they are.++## What counts as a Linux machine for a project++Since v3 (#4120) a new agent starts only on its own person's computer, and a Team account takes no work. Live on 11-07 the+only Linux entry, daniel-pc, has no agent of this project and is not the PM's person's computer, so no Tester can ever run+there. A machine counts when all hold:++- it reports Linux, is online (a reading within `MACHINE_FRESH_MS`), not paused, not being removed, not Buddy-only, not a+ Team account;+- its owner allows this project there (`machineProjectRefusal`);+- a Tester can get there: it is the project PM's own person's computer (the PM may start one), or an own-account agent of+ this project already runs there as that machine's person.++Mac and Windows steps open as before (constraint).++## Design++- growth: `osWaiting` holds at most one entry per OS on a task (only Linux today), each the planned step and its pull+ requests (at most the task's linked pull requests, no history). It is removed when the step opens and goes with the+ task's row.+- concurrency: the task's group row, as every Ready and time-check write already locks it; a racing second run opens the+ same step id (stable from task and step name) and finds the entry gone.+- read cost: the time checks read only what they already load; the gate reads machines and agents in memory. Nothing new+ is read from the database.+- scale: at 10x, machines (about 60 rows now) and agents are scanned only for tasks that have a waiting entry, once per+ project per pass. The time-check duration warns first.+- compatibility: a new optional field; older clients ignore it. The line in the task is an ordinary system row every+ client draws.+- migration and rollback: none. Rolling back leaves `osWaiting` unread; steps open at each Ready as before.+- audience: the line goes to the task's own chat; the server writes it.+- identity: no start is made; the PM is told and assigns as it does today.+- failure: a step that opens tells the PM in the task; a step that stays waiting is said in the task once.+- platforms: backend only (Linux in CI); no client change.++## Global Constraints++- Backend only, under `backend/src/superTabs/` and its tests.+- Mac and Windows test steps open exactly as before.+- No new database read; the time checks use what they load.++## Review Focus++- The machine rule above: does it match who can really take a Linux test after v3?+- A step the PM archived is never reopened at a later head while no Linux machine is there.+- `stepOpen.ts` opens steps exactly as the old closure did (ids, number, brief, card, step list).++## Tasks++### Task 1: A Ready opens no Linux step without a Linux machine, and the task says why++**Files:** `backend/src/superTabs/linuxSteps.ts` (new), `linuxSteps.test.ts` (new), `commands.ts`, `model.ts`+(`Conversation.osWaiting`), `stepOpen.ts` (new), `steps.ts` (`listStep` moves here).++**Interfaces:** `testsOnLinux(state, project, now): boolean`; `LINUX_WAIT_LINE`; `Conversation.osWaiting?: WaitingStep[]`.++- [ ] Failing unit tests: a Ready on a `cli/` change with only a Mac opens Review and Test on a Mac, no Linux step, and+ writes "No Linux machine: CI's Linux runs stand in." once in the task; a second head writes it no second time; a+ Linux machine of another person with no project agent, a Team account's, an offline or paused one each count as none;+ the PM's own Linux computer, or one with an own-account project agent, opens the step as before.+- [ ] Failing unit test: a Linux step the PM archived while no Linux machine is there is not reopened at a later head.+- [ ] Code: the gate in `openReviewSteps`, the waiting record, the line; `openStep` moved to `stepOpen.ts`.++### Task 2: A waiting Linux step opens once a Linux machine is there++**Files:** `linuxSteps.ts`, `linuxSteps.test.ts`, `store.ts` (`runTimeChecks`),+`backend/integration/superTabReviewSteps.test.ts`.++**Interfaces:** `openWaitingSteps(state, now): MessageDraft[]`.++- [ ] Failing unit test: with the step waiting, a pass with no Linux machine opens nothing; once one reports, it opens the+ step with its brief at the recorded head, clears the entry and tells the PM in the task; a second pass opens nothing.+- [ ] Failing real-store test: a Ready through `SuperTabStore` with only a Mac stores no Linux step and the line; after a+ Linux machine of the PM's person reports, `runTimeChecks` opens it in the database.+- [ ] Code: `openWaitingSteps`, called from `runTimeChecks`.