Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

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.ts
index 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.ts
index 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 './answe
import { 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 = operationId
return 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?.agentId
const 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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 const
diff --git a/backend/src/superTabs/stepOpen.ts b/backend/src/superTabs/stepOpen.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.md
new file mode 100644
index 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`.