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
import { accessRefusal, taskAccess } from './machineAccess.js'
import { createHash } from 'node:crypto'
import { z } from 'zod'
import { engineUnusable, machineSuspensionReason } from './engineHealth.js'
import { MAX_HARNESSES, tokensByModelSchema } from './costs/tokens.js'
import { activeWork, occupiesAgent, fail, person, stableId, type Actor, type Agent, type AgentStart, type AgentStartRequest, type MessageDraft, type SuperTabState } from './model.js'
import { WORKSPACE_LABEL } from './workspaces.js'
import { startFinished } from './parts/write.js'
import { agentProjectId, isAgentChat, canReadAgent, canReadProject, groupProject, ledProject, ownsProject, projectOf, projectsOf, teamAccountPool, type SwarmProject } from './projects.js'
import { isSwarmBuddyChat } from './buddies.js'
export { teamAccountPool } from './projects.js'
import { conversation } from './model.js'
/** An explicit grant for this tab and project. It never creates a MachineShare. */
export interface ContributedMachine {
machineId: string
name: string
contributorId: string
membershipGeneration: string
generation: string
cwd: string
scope?: 'swarm'
engines: string[]
/** The count its owner allows when [agents] is `atMost` (and for an older row, see agentLimit). Kept as a number every
* client reads; with As memory allows it is only what the owner last saw, never a limit. */
maxAgents: number
/** Its Agents setting (Dee, 11-04: "remove the limit"): `memory`, as many as free memory allows, checked at each start;
* `atMost`, its owner's own [maxAgents]. Absent on a row saved by an older client: agentLimit reads it. */
agents?: 'memory' | 'atMost'
paused: boolean
/** `sessionKind` is how the reporting machine is signed in, stamped from its session by the store, never taken from
* the report: `team` for a Mac's team account (lib/teamSession.ts), `computer` for any other. Absent on older readings.
* `privacy` is kept only from a team session's reading (observedPrivacy). */
observation?: Omit<MachineObservation, 'privacy'> & { receivedAt: number; sessionKind?: 'team' | 'computer'; privacy?: StoredPrivacy }
/** A Mac's Harness Team account: the machine of the Mac it lives on, stamped by the store from its account row
* (`Machine.hostMachineId`), never taken from the command. Such a pool is that Mac under the scenes ("One machine",
* docs/plans/2026-10-24-swarm-team-account.md): it shows the Mac's name, joins where the Mac was added, follows the
* Mac's pause, slots and removal, and runs teammates' projects started on the Mac (teamStartRequest). */
hostMachineId?: string
/** Set by machine.remove: an online machine stays listed, paused, while its host deletes the Swarm's folders there, until
* the host says it cleaned up (machine.cleaned) or REMOVAL_FALLBACK_MS passes. An offline one leaves the list at once and
* its cleanup waits for its host (expireRemovals). No chat hears how it ended (#2742). */
removal?: { id: string; state: 'cleaning'; requestedAt: string }
/** Added by Desktop as its person joined the Swarm. Swarm v3 has no Team accounts, so it no longer keeps teammates' projects
* off it: its person's own agents take any project they read (teamWorkCheck; #4248, finding 8 of #4212). Kept, and kept
* when the contribution is saved again, only because Desktop's launch.dart still reads it; gone with the machine. */
teamAccountOnly?: true
/** Its owner's choice whether teammates' work may also run in their own account here (commands.ts machine.ownAccountWork,
* Scholes 11-04): who chose (the owner, whose word it is) and when. `allowed` lets a teammate's start run on this entry,
* as its owner, instead of moving to its Harness Team account (ownAccountWork); only the owner's own session turns it on.
* `askedIn`: the owner's message a Lead passed on to turn it off. Kept when the contribution is saved again;
* gone with the machine, so a Mac removed and added again starts Team-account-only. Never on a Team account's own entry. */
ownAccountChoice?: { allowed: boolean; by: string; at: string; askedIn?: { conversationId: string; messageId: string } }
/** One of its person's own machines that is not in the Swarm, recorded only so its host starts and watches their Buddies
* there (Dee, 10-29: "I don't want to add my machine to the swarm"). It takes no other start, is no route or Product
* Manager candidate, serves no local models, and no reader sees it (model.ts visibleState). It goes with its last Buddy
* (commands.ts dropIdleBuddyMachines), or becomes an ordinary machine when its person adds it with Add machine. */
buddyOnly?: true
/** Who had this computer's entry before the account signed in on it now (commands.ts machine.moved, #3122), and until when:
* Machines says "Was kelvin until 5 Nov". Only the last one; gone with the entry. */
previousOwner?: { personId: string; until: string }
/** Agent-time Swarm agents here spent on other people's tasks, by leaderboard week, kept by its readings (leaderboard/lent.ts). */
lent?: import('./leaderboard/lent.js').LentWeek[]
/** The same by day, for the board's rolling periods. Only the leaderboard read gets it (model.ts visibleState). */
lentDays?: import('./leaderboard/lent.js').LentDay[]
/** The leaderboard week (Monday 00:00 UTC) its owner was last told someone else's work started here (othersWork.ts): once
* a week. On a Mac, for its Harness Team account too. Kept when the contribution is saved again. */
othersToldWeek?: number
/** The projects whose agents may run here, set by its owner (commands.ts machine.projects, Tony 11-03); absent: every
* project, as before. A Mac's Harness Team account keeps none of its own: it follows its Mac's (machineProjectRefusal). */
projects?: string[]
/** What it can reach, by macOS account (machine.access, machineAccess.ts, task #3047): its own account's and its Harness
* Team account's, both on the Mac's own entry; never on a Team account's. Kept when the contribution is saved again;
* gone with the machine. At most MAX_ACCESS. */
access?: import('./machineAccess.js').AccessEntry[]
/** Per engine, its failed starts here in a row, until one runs or they suspend it (engineHealth.ts). */
engineFailures?: Record<string, number>
/** Bounded repeat level (0–6) and cause of the current failure streak. Kept across expiry, removed by success/resume
* or with the machine. A launch failure anywhere in the streak prevents sign-in-only recovery. */
engineBackoff?: Record<string, { level: number; cause: 'engine' | 'sign-in' }>
/** `fine` keeps the old reader's contract. Records before 11-05 lack duration/cause and retain their six-hour policy. */
engineSuspensions?: Record<string, { at: number; fine: boolean; durationMs?: number; cause?: 'engine' | 'sign-in' }>
/** Pickup timeouts across all engines. One bounded counter/level/cooldown per machine, removed by any successful start
* or with its contribution. Expiry removes the cooldown only, preserving backoff (0–6) until recovery is proven. */
machineFailures?: number
machineBackoff?: number
machineSuspension?: { at: number; durationMs: number }
}
/** A removed machine whose host never acknowledged in time: its records are gone, its host still cleans up on its next poll.
* [requestedAt]: when its removal was asked for; none on one recorded before 2026-10-28. */
export interface MachineCleanup { machineId: string; removalId: string; machineOwnerId: string; requestedAt?: string
/** Left by a Buddy-only machine (ContributedMachine.buddyOnly): like the record, no reader but its person learns of it, nor of
* the part's removal once its host confirms (read/changes.ts; security review 1 of #2234). */
buddyOnly?: true }
/** Was a day, until a host that kept reporting but never confirmed held Diego's Mac 'Cleaning up' for it (2026-10-28). */
export const REMOVAL_FALLBACK_MS = 30 * 60_000
/** A cleanup that has waited REMOVAL_FALLBACK_MS since its removal, or one too old to say when: it no longer holds its
* owner's add (commands.ts machine.contribute). Diego's Mac, 2026-10-28: its cleanup never finished, and adding it back
* said 'still cleaning up' for good. */
export const cleanupOverdue = (cleanup: MachineCleanup, now: number): boolean =>
!cleanup.requestedAt || now - Date.parse(cleanup.requestedAt) >= REMOVAL_FALLBACK_MS
/** Older contributions may name engines that Swarm no longer starts. Their fresh
* observation lists the supported engines that are actually installed. */
/** The default account's id for an engine on a machine: the CLI and Desktop compute the same 16 hex (sha256 of `machine:engine:default`). */
export const defaultProfileId = (machineId: string, engine: string): string =>
createHash('sha256').update(`${machineId}:${engine}:default`).digest('hex').slice(0, 16)
/** A profile id as the agent stores it: the default account (literal or hashed) is absent. */
export const storedProfileId = (machineId: string, engine: string, profileId: string | undefined): string | undefined =>
profileId === undefined || profileId === 'default' || profileId === defaultProfileId(machineId, engine) ? undefined : profileId
export function contributedEngines(pool: ContributedMachine, observation: MachineObservation | undefined = pool.observation): string[] {
const supported = (engine: string) => engine === 'claude' || engine === 'codex'
return pool.engines.some(engine => !supported(engine))
? (observation?.quotas ?? []).map(quota => quota.engine).filter(supported)
: pool.engines.filter(supported)
}
const measure = z.number().finite().nonnegative().nullable()
const percent = z.number().min(0).max(100).nullable()
const resource = z.object({
cpuPercent: percent, memoryTotalBytes: measure, memoryUsedBytes: measure,
diskFreeBytes: measure, diskTotalBytes: measure,
projectDiskFreeBytes: measure, projectDiskTotalBytes: measure.optional(),
deviceType: z.string().max(120).nullable(), chip: z.string().max(120).nullable(), os: z.string().max(120).nullable(),
gpuPercent: percent,
}).strict()
const quota = z.object({ engine: z.string().regex(/^[a-z][a-z0-9_-]{0,79}$/), known: z.boolean(),
windows: z.array(z.object({ name: z.string().max(80), usedPercent: z.number().min(0).max(100),
resetsAt: z.union([z.string().max(80), z.number().finite(), z.null()]) }).strict()).max(10),
}).strict()
/** Milliseconds since the epoch, on the reporting Mac's clock. */
const checkedAt = z.number().finite().nonnegative()
/**
* What a Harness Team daemon says about its privacy check with each reading (cli/src/team/privacy.ts, docs/plans/
* 2026-10-24-swarm-team-account.md Task 2): `account`, it runs in a Mac's Harness Team account and the check passed, or
* failed with the first failing item (`unchecked` when it could not run); `dedicated`, the whole machine is for agents
* (`harness team on`). The owner's own daemon sends none. `item` is a short slug, so a newer CLI's item still reads.
*/
export const machinePrivacySchema = z.union([
z.object({ mode: z.literal('account'), passed: z.literal(true), checkedAt }).strict(),
z.object({ mode: z.literal('account'), passed: z.literal(false), item: z.string().regex(/^[a-z][a-z0-9-]{0,39}$/), detail: z.string().max(1000), checkedAt }).strict(),
z.object({ mode: z.literal('dedicated') }).strict(),
])
export type MachinePrivacy = z.infer<typeof machinePrivacySchema>
/** As a pool keeps it: `seenAt` is when this server first received that check's result, on the server's clock. */
export type StoredPrivacy = MachinePrivacy & { seenAt: number }
/** What the machine is ready for (cli/src/superTabs/machines.ts readiness), for the route to leave out one that cannot do
* the work: per engine whether it is installed and signed in, and per folder in its Swarm workspace (one per project)
* the repository it checks out (an address without credentials), whether it is a git checkout, and whether this
* machine's own login can push to it. Absent from hosts before it; null and absent entries are unknown. */
const readiness = z.object({
engines: z.array(z.object({ engine: z.string().regex(/^[a-z][a-z0-9_-]{0,79}$/), installed: z.boolean().nullable(), signedIn: z.boolean().nullable() }).strict()).max(8).optional(),
checkouts: z.array(z.object({ folder: z.string().min(1).max(160).regex(/^[^/\\]+$/).refine(f => f !== '.' && f !== '..'),
repository: z.string().max(300).nullable(), git: z.boolean(), push: z.boolean().nullable() }).strict()).max(64).optional(),
}).strict()
export const machineObservationSchema = z.object({ generation: z.string().max(160), resources: resource,
tools: z.record(z.string().max(80), z.boolean()).refine(v => Object.keys(v).length <= 20),
toolProbeErrors: z.record(z.string().max(80), z.string().max(200)).refine(v => Object.keys(v).length <= 20).optional(),
quotas: z.array(quota).max(32),
/** Per engine whose allowance is unknown, why, in plain words naming no account, token or plan (cli superTabs/capacity.ts
* quotaUnknownReason): what the route says of it. Absent from hosts before it. */
quotaReasons: z.record(z.string().regex(/^[a-z][a-z0-9_-]{0,79}$/), z.string().min(1).max(300)).refine(v => Object.keys(v).length <= 8).optional(),
runningHarnessIds: z.array(z.string().max(160)).max(1000),
stoppedHarnessIds: z.array(z.string().max(160)).max(1000),
/** Running Buddy sessions positively idle in this reading; absent is unknown, never idle (#3824). */
idleBuddyHarnessIds: z.array(z.string().max(160)).max(1000).optional(),
/** Of the stopped ones, those this machine's idle cleanup closed (cli superTabs/cleanupCloses.ts): only such a session is
* refused new work (closedAgents.ts sessionClosed), never one stopped by Change agent or a restart (review of #2953).
* Absent from hosts before it. */
closedHarnessIds: z.array(z.string().max(160)).max(1000).optional(),
stoppedReservations: z.array(z.object({ harnessId: z.string().min(1).max(160), generation: z.string().min(1).max(160) }).strict()).max(1000).optional(),
/** When each running agent's screen or transcript last changed (epoch ms); its lease renews on recent progress
* (liveness.ts). Absent from hosts before it, whose agents renew by running alone. */
harnessProgress: z.record(z.string().max(160), z.number().int().nonnegative()).refine(v => Object.keys(v).length <= 1000).optional(),
/** Each running Swarm agent's token counts by model, as its session totals (costs/tokens.ts). An attempt's tokens are the
* difference between its start and its end (routeDecisions.ts). Absent from hosts before it, whose attempts record none. */
harnessTokens: z.record(z.string().max(160), tokensByModelSchema).refine(v => Object.keys(v).length <= MAX_HARNESSES).optional(),
/** Whether each running Swarm session's folder has uncommitted changes (git status), for those its host could read.
* Only a session reported clean is ever stopped for being idle (tidy.ts). Absent from hosts before it. */
harnessUncommitted: z.record(z.string().max(160), z.boolean()).refine(v => Object.keys(v).length <= 1000).optional(),
/** The Local models add-on (docs/plans/2026-10-23-swarm-local-models.md); absent from hosts before it. On the Swarm's
* grid: what this machine serves there (`local` an engine of its own, `api` a saved API it shares), usable by agents on
* any machine. On any other grid: a model its owner may use there (`shared`, shared with them), usable only by agents
* on this machine, since only its sign-in reaches that grid. */
localModels: z.array(z.object({ grid: z.string().min(1).max(160), model: z.string().min(1).max(200),
name: z.string().max(200).optional(), contextWindow: z.number().int().positive().nullable().optional(),
kind: z.enum(['local', 'api', 'shared']).optional(),
/** Started or shared on this machine, not yet listed by the grid: shown as starting, never offered to a Builder. */
starting: z.boolean().optional() }).strict()).max(64).optional(),
/** Models this machine serves on the Swarm's grid that Builders are not offered, too small or too slow to drive a coding
* agent (cli/src/lib/codingModel.ts), with why: so the route can tell a Lead asked for one why it is not offered. */
refusedModels: z.array(z.object({ grid: z.string().min(1).max(160), model: z.string().min(1).max(200),
name: z.string().max(200).optional(), why: z.string().min(1).max(300) }).strict()).max(16).optional(),
/** A Harness Team daemon's privacy check; absent from the owner's own daemon and from hosts before it. The store keeps
* it only when a team session reported it (observedPrivacy). */
privacy: machinePrivacySchema.optional(),
readiness: readiness.optional(),
/** The starts this machine launched and is still preparing (fetching the project, checking its worktree out, starting
* the engine), as of this report. Such a start waits past the 3 minutes while reports keep naming it (liveness.ts);
* the store keeps only this machine's own launched starts. Absent from hosts before it, whose starts get 3 minutes. */
preparingStartIds: z.array(z.string().min(1).max(160)).max(100).optional(),
/** The starts on this machine whose host reports the server refused, each with the refusal (cli superTabs/machines.ts): each
* fails at once (liveness.ts failRefusedStarts), where it waited out the 3 minutes with its reason in the machine's log alone
* (task #2441). The store keeps only this machine's own starts that neither run nor failed; no reader reads them. Absent from
* hosts before it. */
refusedStarts: z.array(z.object({ startId: z.string().min(1).max(160), reason: z.string().min(1).max(300) }).strict()).max(100).optional(),
/** What this host can launch beyond workers: `leadStart`, a project's Product Manager (leadStart.ts). Absent from hosts
* before it, which are never given one. */
capabilities: z.array(z.string().regex(/^[a-zA-Z]{1,40}$/)).max(16).optional(),
/** The accounts a Product Manager could move to, per engine (cli superTabs/profiles): `id` is a stable 16-hex handle,
* `label` a name its owner chose (never an email, so no '@'), `leftPercent` the allowance left. Absent from hosts before it. */
profiles: z.array(z.object({ engine: z.enum(['claude', 'codex']), id: z.string().regex(/^[0-9a-f]{16}$/),
label: z.string().min(1).max(40).refine(l => !l.includes('@')), leftPercent: z.number().int().min(0).max(100).nullable(),
resetsAt: z.string().datetime().nullable() }).strict()).max(16).optional(),
}).strict()
export type MachineObservation = z.infer<typeof machineObservationSchema>
/** A machine reports every 15 seconds (cli/src/superTabs/machines.ts); three missed beats is offline. */
export const MACHINE_FRESH_MS = 45_000
/** A machine's reading as its pool keeps it. */
export type StoredReading = NonNullable<ContributedMachine['observation']>
/** A start this machine may say it is preparing: one it launched that neither runs nor failed (liveness.ts). */
export const preparableStart = (start: AgentStart, machineId: string): boolean =>
start.request.machineId === machineId && !!start.dispatched && !start.harnessId && !start.error
/** A start this machine may say the server refused: one of its own that neither runs nor failed, launched or not. */
export const refusableStart = (start: AgentStart, machineId: string): boolean =>
start.request.machineId === machineId && !start.harnessId && !start.error
/**
* What a report stores of [observation] on [pool]: progress and tokens of running sessions only (leases and attempts read
* them), the preparing starts [preparable] allows, the refused starts [refusable] allows, the contributed engines' quotas, privacy only from a team session
* (observedPrivacy), and how the machine is signed in, from the session and never from the report (lib/teamSession.ts).
* A full report and a reading-only one (DB 2.5) store the same.
*/
export function storedObservation(pool: ContributedMachine, observation: MachineObservation,
opts: { team: boolean; now: number; preparable: (startId: string) => boolean; refusable?: (startId: string) => boolean }): StoredReading {
const { privacy: reported, harnessProgress, harnessTokens, preparingStartIds, refusedStarts, profiles, idleBuddyHarnessIds, ...reading } = observation
const running = (id: string) => observation.runningHarnessIds.includes(id)
const progress = harnessProgress && Object.fromEntries(Object.entries(harnessProgress).filter(([id]) => running(id)))
const tokens = harnessTokens && Object.fromEntries(Object.entries(harnessTokens).filter(([id]) => running(id)))
const preparing = preparingStartIds?.filter(opts.preparable)
// None unless the caller can tell which starts this machine may name (refusableStart).
const refused = refusedStarts?.filter(r => opts.refusable?.(r.startId) ?? false)
const privacy = observedPrivacy(pool.observation?.privacy, reported, opts.team, opts.now)
const engines = contributedEngines(pool, observation)
return { ...reading, quotas: observation.quotas.filter(q => engines.includes(q.engine)), receivedAt: opts.now,
...(idleBuddyHarnessIds ? { idleBuddyHarnessIds: [...new Set(idleBuddyHarnessIds.filter(running))] } : {}),
...(profiles ? { profiles: profiles.filter(p => engines.includes(p.engine)) } : {}),
sessionKind: opts.team ? 'team' : 'computer', ...(privacy ? { privacy } : {}), ...(progress ? { harnessProgress: progress } : {}),
...(tokens ? { harnessTokens: tokens } : {}), ...(preparing ? { preparingStartIds: preparing } : {}),
...(refused?.length ? { refusedStarts: refused } : {}) }
}
const sameSet = (a: readonly string[] = [], b: readonly string[] = []) => {
const left = new Set(a), right = new Set(b)
return left.size === right.size && [...left].every(id => right.has(id))
}
/**
* Whether [next] changes nothing a report decides from, against [previous] (DB 2.5 spec, section 1 condition 2): the same
* running and stopped sessions, no stop proof, no refused start, the same preparing starts. Progress renews leases (liveness.ts
* reportRenewedAt), so it also keeps its shape, and no session's progress goes back: a lease then ends no sooner than the
* last full report saw.
*/
export function readingOnly(previous: StoredReading | undefined, next: StoredReading): boolean {
// How the machine is signed in decides who may host it (store.ts teamByRecord reads the stored one): a reading from the
// other kind of session runs in full, so the full report's refusal is never skipped (review of #2378).
// A refused start fails in the full report, which reads the Swarm's starts (store.ts fullReading).
if (!previous || next.stoppedReservations?.length || next.refusedStarts?.length || previous.sessionKind !== next.sessionKind) return false
if (!sameSet(previous.runningHarnessIds, next.runningHarnessIds) || !sameSet(previous.stoppedHarnessIds, next.stoppedHarnessIds)
|| !sameSet(previous.closedHarnessIds ?? [], next.closedHarnessIds ?? [])
|| !sameSet(previous.preparingStartIds, next.preparingStartIds)
|| !sameSet(previous.idleBuddyHarnessIds, next.idleBuddyHarnessIds)) return false
if (!previous.harnessProgress || !next.harnessProgress) return !previous.harnessProgress && !next.harnessProgress
const before = previous.harnessProgress, after = next.harnessProgress
return sameSet(Object.keys(before), Object.keys(after)) && Object.entries(before).every(([id, at]) => after[id]! >= at)
}
/** Whether [start] is preparing now: launched, neither running nor failed, and named by a fresh report of its own machine.
* Read from that report, never written into the start, so a report a minute per start writes nothing more. */
export function startPreparing(state: SuperTabState, start: AgentStart, now: number): boolean {
if (!start.dispatched || start.harnessId || start.error || start.dispatchedAt === undefined) return false
const report = state.machines?.find(m => m.machineId === start.request.machineId)?.observation
return !!report?.preparingStartIds?.includes(start.id) && now - report.receivedAt <= MACHINE_FRESH_MS
}
// ── Teammates' work runs only on Team machines (docs/plans/2026-10-24-swarm-team-account.md, Task 3) ──────────────
// A start or an assignment for a project whose owner is not the person whose grant runs the machine is a teammate's
// work. It would run as that machine's owner, with their files, logins and subscriptions, so it is admitted only on a
// Team machine — the Mac's Harness Team account, or a machine used only for agents — that shows its privacy now.
// Everything else refuses it and says why; a person's own projects on their own machines are unchanged.
// Swarm v3 (task #4120) runs a person's own agent on their own computer instead: this holds only on a Team account (#4218).
/** How long a passed privacy check counts, from when this server first received it. The team account checks again
* every 5 minutes (cli/src/team/privacy.ts PRIVACY_RECHECK_MS) and reports within a 15-second beat, so a healthy
* machine's check is never older than about 5 minutes here. 15 minutes allows two missed rechecks (a slow check, a
* daemon restart) before routing stops, and bounds to 15 minutes how long a home folder opened again but no longer
* checked can still be trusted. A failing check counts at once, whatever its age. */
export const PRIVACY_FRESH_MS = 15 * 60_000
/**
* The privacy a reading leaves on the pool: only a team session's, since an ordinary computer's says nothing about a
* team account. The same check sent again keeps the date it first arrived, so a check that stops running goes stale on
* the server's clock, whatever the reporting Mac's clock says.
*/
export function observedPrivacy(previous: StoredPrivacy | undefined, reported: MachinePrivacy | undefined, team: boolean, now: number): StoredPrivacy | undefined {
if (!team || !reported) return undefined
const same = previous && previous.mode === reported.mode && (reported.mode === 'dedicated'
|| (previous.mode === 'account' && previous.passed === reported.passed && previous.checkedAt === reported.checkedAt))
return { ...reported, seenAt: same ? previous.seenAt : now }
}
export type TeamWorkCode = 'TEAM_WRITTEN_WORK' | 'MACHINE_OFFLINE' | 'TEAM_ACCOUNT_REQUIRED' | 'PRIVACY_UNCHECKED' | 'PRIVACY_CHECK_FAILED' | 'PRIVACY_CHECK_STALE'
| 'MACHINE_IN_OTHER_WORKSPACE' | 'NOT_SWARM_MACHINE' | 'MACHINE_PROJECTS' | 'ACCESS_MISSING' | 'TEAM_ACCOUNTS_REMOVED' | 'NOT_YOUR_COMPUTER' | 'READ_ONLY' | 'STEP_OS'
export interface TeamWorkRefusal { code: TeamWorkCode; reason: string }
/** Refusals that hold until a person acts on the machine; a stale check or an offline machine may pass again by itself. */
export const LASTING_TEAM_REFUSALS: readonly string[] = ['TEAM_ACCOUNT_REQUIRED', 'PRIVACY_UNCHECKED', 'PRIVACY_CHECK_FAILED', 'MACHINE_IN_OTHER_WORKSPACE']
/** What each item of the privacy check (cli/src/team/privacy.ts) could reach when it failed. */
const PRIVACY_ITEMS: Record<string, string> = {
sentinel: 'it could read the privacy sentinel in its owner\'s home folder', 'home-listing': 'it could list its owner\'s home folder',
gitconfig: 'it could read its owner\'s ~/.gitconfig', ssh: 'it could list its owner\'s ~/.ssh', projects: 'it could list its owner\'s project folders',
keychain: 'it could list its owner\'s login Keychain folder', chrome: 'it could list its owner\'s Chrome profile', safari: 'it could list its owner\'s Safari folder',
// A Linux team account checks Firefox in place of Safari; a Windows one, Edge and the Credential Manager folders.
firefox: 'it could list its owner\'s Firefox profile', edge: 'it could list its owner\'s Edge profile',
credentials: 'it could list its owner\'s Windows Credential Manager folder',
'standard-user': 'the team account is an administrator', unchecked: 'the check did not run',
}
const ONLY_OWN = 'so it runs only its owner\'s projects'
/**
* Whether a teammate's work needs a Harness Team account on every machine of a Swarm (`SWARM_TEAM_ACCOUNT_REQUIRED=1`).
* Without it, a machine without one takes a teammate's work as it did before team accounts, while a machine with one
* already follows the rule. Read on every call, so a test can set it.
*
* Every Swarm alike (2026-11-02). It was held to the Swarms of the owners `SWARM_TEAM_ACCOUNT_OWNERS` listed while the
* feature was tried on production (2026-10-27 to 11-02); that variable is no longer read.
*/
export function teamAccountRequired(): boolean {
return process.env.SWARM_TEAM_ACCOUNT_REQUIRED === '1'
}
/** Why this contributed machine may not run a teammate's project now, or null when it may. `teamRow`: its account row
* says it is signed in as a team account (`Machine.sessionKind`), read by the store. A machine that is not a Team account
* runs its own person's agents, whatever they work on (teamWorkCheck), so it reads no rule: it read "has no Harness Team
* account yet" where the rule was required or it was added at join, and the route left those agents out (task #4218). */
/** `otherWorkspace`: the machine is contributed to a Swarm of another Workspace too (store.ts otherWorkspaceMachines). Its Team account
* runs every teammate's work as one macOS user, so it serves one Workspace's teammates at a time (swarm-workspaces design). */
export function teamWorkRefusal(pool: ContributedMachine, now: number, teamRow = false, otherWorkspace = false): TeamWorkRefusal | null {
const reading = pool.observation, name = pool.name
// A Mac's Harness Team account whose machine is no longer a Team machine was removed (`harness team remove` deletes it).
// Its last reading stays fresh for a minute, and in that minute it read as taking teammates' work and a Lead's route
// named it (local Team account run, 2026-10-28).
if (pool.hostMachineId && !teamRow) return { code: 'TEAM_ACCOUNT_REQUIRED', reason: `The Harness Team account on ${name} was removed, ${ONLY_OWN}.` }
// Its owner let teammates' work run in their own account here: their explicit choice wins over the Swarm-wide rule, for
// this machine only (River, 11-04).
if (ownAccountWork(pool)) return null
if (!teamRow && reading?.sessionKind !== 'team') return null
if (otherWorkspace) return { code: 'MACHINE_IN_OTHER_WORKSPACE', reason: `The Harness Team account on ${name} also serves another ${WORKSPACE_LABEL}'s Swarms, ${ONLY_OWN} here.` }
if (!reading || now - reading.receivedAt > MACHINE_FRESH_MS) {
// A Mac's team account goes by its Mac's name ("One machine"), and the Mac itself may well be online.
return { code: 'MACHINE_OFFLINE', reason: pool.hostMachineId
? `The Harness Team account on ${name} is offline, so it cannot show that it is private.`
: `${name} is offline, so it cannot show that its Harness Team account is private.` }
}
if (!teamRow && reading.sessionKind !== 'team') return { code: 'TEAM_ACCOUNT_REQUIRED', reason: `${name} has no Harness Team account yet, ${ONLY_OWN}.` }
const privacy = reading.privacy
if (!privacy) return { code: 'PRIVACY_UNCHECKED', reason: `${name} has not reported a privacy check from its Harness Team account, ${ONLY_OWN}.` }
if (privacy.mode === 'dedicated') return null
if (!privacy.passed) {
const what = PRIVACY_ITEMS[privacy.item]
return { code: 'PRIVACY_CHECK_FAILED', reason: `The Harness Team account on ${name} is not private (${privacy.item}${what ? `: ${what}` : ''}), ${ONLY_OWN}.` }
}
if (now - privacy.seenAt > PRIVACY_FRESH_MS) {
const minutes = Math.floor((now - privacy.seenAt) / 60_000)
return { code: 'PRIVACY_CHECK_STALE', reason: `The privacy check on ${name} last passed ${minutes} minutes ago, ${ONLY_OWN} until it passes again.` }
}
return null
}
/**
* Whether work for [project] may run on [machineId] under [contributorId]'s grant there: the pool's contributor for a start, the
* agent's contributor for an agent already in the Swarm. Swarm v3 has no Team accounts (task #4120, the PM's ruling there): an
* agent a person brought works on any task of a project that person can read, in their own account, so the work runs as its own
* person and never as a machine owner it does not belong to.
*/
export function teamWorkCheck(state: SuperTabState, machineId: string, contributorId: string, project: SwarmProject): TeamWorkRefusal | null {
// Its owner kept it for other projects (machine.projects): whoever's project and grant it is.
const kept = machineProjectRefusal(state, machineId, project)
if (kept) return kept
const pool = state.machines?.find(m => m.machineId === machineId)
// A Buddy-only machine is its person's alone: an agent they added there takes their own projects' work and no other's
// (security re-check 1 of #2234). New starts there are refused in admitMachineStart.
if (pool?.buddyOnly) return ownsProject(state, pool.contributorId, project) ? null : { code: 'NOT_SWARM_MACHINE', reason: NOT_SWARM_MACHINE }
// A Team account's agent already in the Swarm keeps working in what it holds until it is stopped after the release; it gets no
// new work and no new agent starts there, which their own gates refuse (admitMachineStart, work.assign, the route, the picks).
if (pool && pool.contributorId !== contributorId) return { code: 'NOT_YOUR_COMPUTER', reason: NOT_YOUR_COMPUTER }
const person = state.people.find(p => p.id === contributorId)
// Reading is not working: a viewer's agent takes no work (security review 1 of #3446).
if (person?.role === 'viewer') return { code: 'READ_ONLY', reason: 'This agent\'s person is a viewer here, so their agents take no work.' }
if (ownsProject(state, contributorId, project) || (person && canReadProject(state, { kind: 'person', userId: person.id, email: person.email }, project))) return null
return { code: 'NOT_YOUR_COMPUTER', reason: `${pool?.name ?? 'This machine'}'s person cannot read this project, so its agents take none of its work.` }
}
/** Why a Team account's entry takes no new agent and no new work (task #4120). */
export const TEAM_ACCOUNTS_GONE: TeamWorkRefusal = { code: 'TEAM_ACCOUNTS_REMOVED',
reason: 'Harness Team accounts are gone: an agent runs on its own person\'s computer, in their own account.' }
/** Why a new agent does not start on another person's computer (task #4120): it would run as that computer's person. */
export const NOT_YOUR_COMPUTER = 'A new agent starts only on its own person\'s computer, in their own account, never on another person\'s.'
/**
* Why [machineId] takes no work of [project]: its owner kept it for other projects (commands.ts machine.projects, Tony
* 11-03), or null. A Mac's Harness Team account follows its Mac's list. The sentence names only projects every member may
* read and counts the rest, since it reaches the readers of [project] (a route's exclusions, a refused start).
*/
export function machineProjectRefusal(state: SuperTabState, machineId: string, project: SwarmProject): TeamWorkRefusal | null {
const pool = state.machines?.find(m => m.machineId === machineId)
const mac = pool?.hostMachineId ? state.machines?.find(m => m.machineId === pool.hostMachineId && m.contributorId === pool.contributorId) ?? pool : pool
const listed = mac?.projects
if (!mac || !listed || listed.includes(project.id)) return null
const kept = projectsOf(state).filter(p => listed.includes(p.id))
if (!kept.length) return { code: 'MACHINE_PROJECTS', reason: `${mac.name} runs no project now: its owner can choose its projects again.` }
const named = kept.filter(p => p.visibility === 'public').map(p => p.name), others = kept.length - named.length
const parts = [...named, ...(others ? [`${others} other project${others > 1 ? 's' : ''}`] : [])]
const list = parts.length > 1 ? `${parts.slice(0, -1).join(', ')} and ${parts.at(-1)}` : parts[0]
return { code: 'MACHINE_PROJECTS', reason: `${mac.name} runs only ${list}.` }
}
// ── One machine: a Mac and its Harness Team account ─────────────────────────────────────────────────────────────────
// The team account is how a Mac runs teammates' work without its owner's files, not a machine of its own to anyone: a
// Lead names the Mac, and the work for another person's project lands in the Mac's team account.
/** Every pool of a Harness Team account on the Mac [pool] is, under the same grant: one, or more once the account was
* removed and set up again (a new account and machine, the old one's pool still listed). They go with the Mac. */
export function teamPoolsOf(state: SuperTabState, pool: ContributedMachine): ContributedMachine[] {
if (pool.hostMachineId) return []
return state.machines?.filter(m => m.hostMachineId === pool.machineId && m.contributorId === pool.contributorId) ?? []
}
/** The name a machine's owner gave it in Machines (its account row, routes/machines.ts rename), which every Swarm list shows
* (Dee, #2308): seeded from its computer's hostname, so a machine never renamed keeps that. Null when the row has none. */
export function accountMachineName(row: { name: string | null } | null | undefined): string | null {
return row?.name?.trim() || null
}
/** Whether [pool] shows another name than [name], its owner's (accountMachineName). A Team account's pool goes by its Mac's
* name, never its own account's "<Mac> · Team": it follows its Mac (followAccountName). */
export function renamedBy(pool: ContributedMachine, name: string | null): name is string {
return !!name && !pool.hostMachineId && pool.name !== name
}
/** Renames [pool], and its Mac's Team account pools, to [name] when its owner renamed it (renamedBy); whether it did. Its
* host's readings call it, so a rename shows in every Swarm the machine is in by its next heartbeat. */
export function followAccountName(state: SuperTabState, pool: ContributedMachine, name: string | null): boolean {
if (!renamedBy(pool, name)) return false
for (const each of [pool, ...teamPoolsOf(state, pool)]) each.name = name
return true
}
/** The one of them that runs teammates' work on the Mac: not being removed, and the last to report. Undefined when none. */
export function teamPoolOf(state: SuperTabState, pool: ContributedMachine, live?: readonly string[]): ContributedMachine | undefined {
// [live]: the account rows still signed in as team accounts (store.ts teamMachines). One removed since (`harness team
// remove` deletes its machine) leaves its pool behind, and the Mac goes back to what a Mac without one does.
return teamPoolsOf(state, pool).filter(m => !m.removal && (!live || live.includes(m.machineId)))
.reduce<ContributedMachine | undefined>((best, m) => !best || (m.observation?.receivedAt ?? -1) >= (best.observation?.receivedAt ?? -1) ? m : best, undefined)
}
/**
* Whether [pool] takes teammates' work, as a Swarm's reads say it. Every machine reads as itself: a teammate's agent on a Mac
* runs in its own person's account there, never in the Mac's Harness Team account (task #4120), so that account's privacy check
* no longer speaks for the Mac (task #4218).
*/
export function machineTeamWork(pool: ContributedMachine, now: number, teamMachines: readonly string[],
otherWorkspaceMachines: readonly string[] = []): TeamWorkRefusal | null {
return teamWorkRefusal(pool, now, teamMachines.includes(pool.machineId), otherWorkspaceMachines.includes(pool.machineId))
}
/** The projects with work on [machineId]: its agents' and its pending starts'. */
export function projectsOnMachine(state: SuperTabState, machineId: string): Set<string> {
const pending = (state.starts ?? []).filter(s => s.request.machineId === machineId && !s.harnessId && !s.error)
.map(s => s.request.leadFor?.projectId ?? groupProject(state, conversation(state, s.request.conversationId)).id)
return new Set([...state.agents.filter(a => a.machineId === machineId).map(a => agentProjectId(state, a)), ...pending])
}
/** The project whose Product Manager runs, or is starting, on [machineId]; null when none does. In a Harness Team account it
* serves only that project: every agent there is one macOS user, which reads the others' files, the Product Manager's
* saved sessions with people's private chats among them (#895). */
export function productManagerOn(state: SuperTabState, machineId: string): string | null {
const led = state.agents.find(a => a.machineId === machineId && ledProject(state, a.id))
if (led) return ledProject(state, led.id)!.id
// One removed whose host has not yet confirmed its data there is deleted (commands.ts removeAgent).
const closing = state.closingSessions?.find(c => c.machineId === machineId && c.heldFor)
if (closing) return closing.heldFor!
return state.starts?.find(s => s.request.machineId === machineId && s.request.leadFor && !s.harnessId && !s.error)?.request.leadFor!.projectId ?? null
}
/** Whether [pool]'s owner lets teammates' work run in their own account there (machine.ownAccountWork): a Mac's own entry
* only, never its Team account's. */
export const ownAccountWork = (pool: Pick<ContributedMachine, 'ownAccountChoice' | 'hostMachineId' | 'buddyOnly' | 'contributorId'> | undefined): boolean =>
!!pool && pool.ownAccountChoice?.allowed === true && pool.ownAccountChoice.by === pool.contributorId && !pool.hostMachineId && !pool.buddyOnly
/** What the route and an agent's row say of a machine whose owner lets teammates' work run in their own account there, so
* whoever routes a teammate's task to it does so knowingly (River, 11-04). */
export const ownAccountNote = (pool: Pick<ContributedMachine, 'name'>, ownerName: string | undefined): string =>
`${pool.name} runs teammates' work in ${ownerName ?? 'its owner'}'s own account.`
/** The folder a start for [project] uses on [pool]: what admitMachineStart accepts there. */
export function projectFolder(pool: ContributedMachine, project: SwarmProject): string {
return pool.scope === 'swarm'
? project.repository?.machineId === pool.machineId ? project.repository.cwd : `${pool.cwd.replace(/\/+$/, '')}/${project.id}`
: pool.cwd
}
/** [request] as [pool] can carry it out for [project]: a project whose folder is recorded without a repository address has
* nothing to clone or branch from on any machine but the one that folder is on, so elsewhere it starts in the project's own
* empty folder without a worktree (task #3211); its host makes that folder (cli superTabs/projectFolder.ts). A project with
* no folder recorded yet is left alone: its first start records one. Any other start is unchanged. */
export function noRepositoryStart(pool: ContributedMachine | undefined, project: SwarmProject | undefined, request: AgentStartRequest): AgentStartRequest {
const repository = project?.repository
if (!pool || pool.scope !== 'swarm' || !repository || repository.repositoryUrl || repository.machineId === pool.machineId) return request
if (!request.worktree && !request.branchRef) return request
const { branchRef: _branchRef, ...rest } = request
return { ...rest, worktree: false }
}
/** What a host reports (`capabilities`) when it runs a Swarm-wide Buddy in its folder of project worktrees (Dee, 10-31). */
export const SWARM_BUDDY_CAPABILITY = 'swarmBuddy'
/** At most this many projects' worktrees in a Swarm-wide Buddy's folder (spec: Staying within one context). */
export const MAX_BUDDY_PROJECTS = 50
/** A Swarm-wide Buddy's own folder on [pool] (spec: Folder): its host makes it, with one read-only worktree per project in it. It
* is no project's checkout, so nothing of one project is ever another's. */
export function buddyHomeFolder(pool: ContributedMachine, owner: { id: string }): string {
return `${pool.cwd.replace(/\/+$/, '')}/.buddy-${owner.id}`
}
/** The projects [owner] reads, as a Swarm-wide Buddy's folder on [pool] holds them: each project's own folder there, the oldest
* first, at most MAX_BUDDY_PROJECTS. Ids, names and folders only (starts are listed to the PM). */
export function buddyProjectsOn(state: SuperTabState, pool: ContributedMachine, owner: { id: string; email: string }): Array<{ id: string; name: string; cwd: string }> {
const readable = projectsOf(state).filter(p => canReadProject(state, { kind: 'person', userId: owner.id, email: owner.email }, p))
// A machine shared for one project only has that project's folder alone (projectFolder answers its folder for any project):
// never list another project at it (security review 1 of #2435).
.filter(p => pool.scope === 'swarm' || p.id === 'lead')
.map(p => ({ id: p.id, name: p.name, cwd: projectFolder(pool, p) }))
// Only projects with a folder of their own: two that answer the same folder would show one project's code as the other's.
const counts = new Map<string, number>()
for (const p of readable) counts.set(p.cwd, (counts.get(p.cwd) ?? 0) + 1)
return readable.filter(p => counts.get(p.cwd) === 1).slice(0, MAX_BUDDY_PROJECTS)
}
/** Refuses with the refusal's code and sentence: 403, or 409 like any start on an offline machine. */
export function failTeamWork(refusal: TeamWorkRefusal, after = ''): never {
fail(refusal.code, `${refusal.reason}${after}`, refusal.code === 'MACHINE_OFFLINE' ? 409 : 403)
}
export function requireTeamWork(...args: Parameters<typeof teamWorkCheck>): void {
const refusal = teamWorkCheck(...args)
if (refusal) failTeamWork(refusal)
}
/** Since when an agent has been down: the stored time a reading first showed its session gone or the host confirmed its
* stop, or its machine's last reading once that is stale. Nothing is written while a machine is silent, so that case is
* read from the reading itself. Undefined while it is up. */
export function downSince(state: SuperTabState, target: Agent, now: number): string | undefined {
const observation = state.machines?.find(m => m.machineId === target.machineId)?.observation
const offline = observation && now - observation.receivedAt > MACHINE_FRESH_MS ? new Date(observation.receivedAt).toISOString() : undefined
return [target.downSince, offline].filter(Boolean).sort()[0]
}
/** Before a new reading replaces the last one: a session it lists as running is back; any other agent on the machine
* keeps the earliest time it was down, including the time its machine went silent. */
export function recordAgentPresence(state: SuperTabState, machineId: string, running: string[], now: number): void {
for (const target of state.agents.filter(a => a.machineId === machineId)) {
if (running.includes(target.harnessId)) {
delete target.downSince
delete target.downNamed
} else {
// A stop is counted once, when a reading first shows the session gone; the last hour's, at most five (task #3662).
if (!target.downSince) target.stops = [...(target.stops ?? []).filter(at => now - at < 3_600_000), now].slice(-5)
target.downSince = downSince(state, target, now) ?? new Date(now).toISOString()
}
}
}
/** Why a start other than its own person's Buddy is refused on a Buddy-only machine: worded as for any machine outside the
* Swarm, so the refusal says nothing about whose it is or what runs there. */
/** A host that can tell a Buddy's window from another agent's on Windows (CLI callerPane.ts `windowsRunningPane`). An older one
* cannot: a Buddy there refused every agent's Swarm command on that computer (security review of #2093). */
export const WINDOWS_BUDDY_CAPABILITY = 'windowsBuddy'
export const BUDDY_WINDOWS_REFUSAL = 'Update Harness on this Windows machine to run a Buddy on it, or pick another of your machines.'
export const refusesWindowsBuddy = (pool: ContributedMachine): boolean => pool.observation?.resources.os === 'Windows'
&& !pool.observation.capabilities?.includes(WINDOWS_BUDDY_CAPABILITY)
export const NOT_SWARM_MACHINE = 'This machine is not one of the Swarm\'s machines.'
/** The most machines one person adds to one Swarm (#2637, Ken, 2026-11-04). The Swarm-wide 32 dated from one 16 MB
* document; each machine is its own part now. Team accounts' entries count apart, so a Mac's Team account never uses up
* its owner's 20, and still have a bound. Review again when one Swarm passes 100 entries (plan 2026-11-04). */
export const MACHINES_PER_PERSON = 20
export const MACHINE_LIMIT_MESSAGE = `You have ${MACHINES_PER_PERSON} machines in this Swarm, the most one person can add. Remove one before adding another.`
/** How many more machines [contributorId] may add to [state], or with [team] Team accounts' entries. Buddy-only records count
* as the person's machines. The command's check and the host's join rows both read this, so they never disagree. */
export const machineRoom = (state: SuperTabState, contributorId: string, { team = false } = {}): number =>
Math.max(0, MACHINES_PER_PERSON - (state.machines ?? []).filter(m => m.contributorId === contributorId && !!m.hostMachineId === team).length)
export const machineLimitReached = (state: SuperTabState, contributorId: string, options: { team?: boolean } = {}): boolean =>
machineRoom(state, contributorId, options) === 0
/** A Buddy-only machine with no Buddy left on it, running or starting, leaves: its host deletes the Swarm's folders there as
* for a removed machine, and no chat hears of it, since none ever saw it (Lead, 10-29). Run after every command (commands.ts)
* and every liveness sweep (liveness.ts), so each way a Buddy goes (removed, failed or timed out, its person or project
* gone) ends it, as expireRemovals does for removals. Written as a machine part change, guarded by its version. */
export function dropIdleBuddyMachines(state: SuperTabState, now: number): void {
for (const pool of state.machines?.filter(m => m.buddyOnly) ?? []) {
if (state.agents.some(a => a.machineId === pool.machineId)
|| state.starts?.some(s => s.request.machineId === pool.machineId && !s.harnessId && !s.error)) continue
state.machines = state.machines!.filter(m => m !== pool)
;(state.machineCleanups ??= []).push({ machineId: pool.machineId, removalId: stableId('buddy-machine', pool.machineId, pool.generation),
machineOwnerId: pool.contributorId, requestedAt: new Date(now).toISOString(), buddyOnly: true })
state.harnessReservations = state.harnessReservations?.filter(r => r.machineId !== pool.machineId)
state.releasedHarnesses = state.releasedHarnesses?.filter(r => r.machineId !== pool.machineId)
state.removedSessions = state.removedSessions?.filter(r => r.machineId !== pool.machineId)
}
}
/** The Swarm's own machines: every contribution but a Buddy-only one (ContributedMachine.buddyOnly). */
export const swarmMachines = (state: Pick<SuperTabState, 'machines'>): ContributedMachine[] => (state.machines ?? []).filter(m => !m.buddyOnly)
export function machineContribution(state: SuperTabState, machineId: string) {
const pool = state.machines?.find(m => m.machineId === machineId)
if (!pool) return null
const contributor = person(state, pool.contributorId)
// Its person left and came back while their host still removes what the Swarm had there (task #4252): that ends by itself.
if (contributor.role !== 'viewer' && contributor.generation !== pool.membershipGeneration && pool.removal) {
fail('MACHINE_CLEANING', `${pool.name ?? 'This machine'} is still cleaning up after its person left the Swarm. Try again once that finishes, in a minute or two.`)
}
if (contributor.role === 'viewer' || contributor.generation !== pool.membershipGeneration) {
fail('CONTRIBUTION_REVOKED', 'This machine contribution was withdrawn.', 403)
}
return pool
}
/** A machine is its owner's to remove: whoever contributed it, or, for a machine with only shared agents, whoever
* contributed all of them. Not the Swarm owner (spec 2026-10-23-remove-machine.md, decision 1). */
export function ownedMachine(state: SuperTabState, actor: Actor, machineId: string) {
const pool = state.machines?.find(m => m.machineId === machineId)
// Not listed to anyone: it goes with its last Buddy (commands.ts dropIdleBuddyMachines), never by a removal that tells chats.
if (pool?.buddyOnly) fail('NOT_FOUND', 'This machine is not in the Swarm.', 404)
const members = state.agents.filter(a => a.machineId === machineId)
if (!pool && !members.length) fail('NOT_FOUND', 'This machine is not in the Swarm.', 404)
const ownerId = pool?.contributorId ?? (members.every(a => a.contributorId === members[0]!.contributorId) ? members[0]!.contributorId : null)
if (actor.kind !== 'person' || actor.userId !== ownerId) fail('FORBIDDEN', 'Only the machine\'s owner can remove it.', 403)
return { pool, members }
}
/** What removing the machine would do, for its owner's confirmation. */
export function removalPreview(state: SuperTabState, actor: Actor, machineId: string) {
const owned = ownedMachine(state, actor, machineId)
// A Mac leaves with its Harness Team account and the agents there (commands.ts machine.remove).
const teams = owned.pool ? teamPoolsOf(state, owned.pool).filter(m => !m.removal).map(m => m.machineId) : []
const members = [...owned.members, ...state.agents.filter(a => teams.includes(a.machineId))]
const led = members.map(a => ledProject(state, a.id)).find(Boolean)
const visibleAgents = members.filter(a => canReadAgent(state, actor, a))
const soleSourceProjects = projectsOf(state).filter(p => p.repository?.machineId === machineId && !p.repository.repositoryUrl)
const visibleSoleSourceProjects = soleSourceProjects.filter(p => canReadProject(state, actor, p))
return {
blockedBy: led ? canReadProject(state, actor, led)
? { projectId: led.id, projectName: led.name } : { reason: "A Product Manager of a project you can't see runs on this machine." } : null,
agents: visibleAgents.map(a => {
// The task in its hands first, then one it handed over (#3399).
const task = state.conversations.find(c => occupiesAgent(c) && c.assignment!.agentId === a.id)
?? state.conversations.find(c => activeWork(c) && c.assignment!.agentId === a.id)
return { id: a.id, name: a.displayName ?? a.name, projectName: projectsOf(state).find(p => p.id === agentProjectId(state, a))?.name ?? '',
...(task ? { task: task.title } : {}) }
}),
hiddenAgentCount: members.length - visibleAgents.length,
// Their code is only on this machine: agents elsewhere start in an empty folder until someone shares a repository (#3211).
soleSourceProjects: visibleSoleSourceProjects.map(p => ({ id: p.id, name: p.name })),
hiddenSoleSourceProjectCount: soleSourceProjects.length - visibleSoleSourceProjects.length,
}
}
/** No reading yet, or one older than three missed beats: the machine Desktop shows as offline, and the one a start
* is refused on. Nothing is written while a machine is silent, so this is read from the last reading itself. */
export function machineOffline(pool: ContributedMachine, now: number): boolean {
return !pool.observation || now - pool.observation.receivedAt > MACHINE_FRESH_MS
}
/** A removal its host cannot acknowledge (offline) or has not acknowledged in REMOVAL_FALLBACK_MS: the machine's records go, and the
* cleanup waits for its host on its next connection. No chat is told: the Machines list shows which machines are in the Swarm
* (anh Dee, 11-04, #2742). */
export function expireRemoval(state: SuperTabState, pool: ContributedMachine): void {
(state.machineCleanups ??= []).push({ machineId: pool.machineId, removalId: pool.removal!.id, machineOwnerId: pool.contributorId,
requestedAt: pool.removal!.requestedAt })
state.machines = state.machines!.filter(m => m !== pool)
}
/** Ends the removals that are due. A read applies them without writing. */
export function expireRemovals(state: SuperTabState, now: number): void {
for (const pool of state.machines?.filter(m => m.removal
&& (machineOffline(m, now) || now - Date.parse(m.removal.requestedAt) >= REMOVAL_FALLBACK_MS)) ?? []) expireRemoval(state, pool)
}
/** Pending intents reserve slots too. Only an explicit host stop frees a launched slot. A Mac and its Harness Team account
* share the Mac's slots (One machine, teamStartRequest): each counts what runs on both. */
export function machineSlots(state: SuperTabState, pool: ContributedMachine) {
return slotCounter(state)(pool)
}
/**
* The slots each pool of `state` holds, for every pool a read lists: the Swarm's reservations, released harnesses, agents
* and starts are grouped by machine once, where each pool used to filter the whole lists again (prod 10-31: 543 released
* harnesses on 17 machines, ~27 k callbacks per change read, a quarter of its CPU). Counts the state as it is when called;
* a command that changes the state asks again (machineSlots).
*/
export function slotCounter(state: SuperTabState): (pool: ContributedMachine) => number {
const group = <T>(items: readonly T[] | undefined, machineOf: (item: T) => string) => {
const by = new Map<string, T[]>()
for (const item of items ?? []) {
const list = by.get(machineOf(item))
if (list) list.push(item)
else by.set(machineOf(item), [item])
}
return by
}
const reservationsBy = group(state.harnessReservations, r => r.machineId)
const releasedBy = group(state.releasedHarnesses, r => r.machineId)
const agentsBy = group(state.agents, a => a.machineId)
const startsBy = group(state.starts, s => s.request.machineId)
const counted = new Map<ContributedMachine, number>()
const poolSlots = (pool: ContributedMachine) => {
const known = counted.get(pool)
if (known !== undefined) return known
const reservations = reservationsBy.get(pool.machineId) ?? []
const live = new Set(reservations.map(r => r.harnessId))
const released = (releasedBy.get(pool.machineId) ?? []).filter(r => !live.has(r.harnessId)).map(r => r.harnessId)
const observed = pool.observation?.stoppedHarnessIds ?? []
const stopped = new Set([...observed.filter(id => {
const reservation = reservations.find(r => r.harnessId === id)
// Older hosts can prove a first launch stopped, but cannot distinguish a resumed runtime from its predecessor.
return !reservation || !reservation.renewed || pool.observation?.stoppedReservations?.some(r => r.harnessId === id && r.generation === reservation.generation)
}), ...released])
const running = new Set((pool.observation?.runningHarnessIds ?? []).filter(id => !stopped.has(id)))
for (const a of agentsBy.get(pool.machineId) ?? []) if (!stopped.has(a.harnessId)) running.add(a.harnessId)
for (const r of reservations) if (!stopped.has(r.harnessId)) running.add(r.harnessId)
let pending = 0
for (const start of startsBy.get(pool.machineId) ?? []) {
if (start.error) continue
// A finished start's harness counts through its agent or its host's report. Reads keep finished starts until they expire,
// and counted every harness ever started there (Mac Studio, 10-29: 13 running, 121 counted, no free agents shown).
if (start.harnessId) { if (!startFinished(start) && !stopped.has(start.harnessId)) running.add(start.harnessId) }
else pending++
}
counted.set(pool, running.size + pending)
return running.size + pending
}
return pool => {
const mac = pool.hostMachineId ? state.machines?.find(m => m.machineId === pool.hostMachineId && m.contributorId === pool.contributorId) : pool
const team = mac && teamPoolOf(state, mac)
return [...new Set([pool, mac, team])].reduce((sum, each) => sum + (each ? poolSlots(each) : 0), 0)
}
}
/** Machines of the Swarm serving models on its grid now, by model: only fresh readings count. */
/** What a Swarm's owner's computer keeps on grid for it (docs/plans/2026-10-23-swarm-local-models.md): the grid, and as its
* members the people who may act in the Swarm. A viewer is not one, and the owner is the grid's admin already. */
export function swarmGridRow(tabId: string, state: SuperTabState) {
const local = state.localModels
if (!local) return null
return { tabId, grid: local.grid, enabled: local.enabled, ready: local.ready ?? null,
members: state.people.filter(p => p.role !== 'viewer' && p.id !== state.ownerId).map(p => p.email) }
}
/** The grid a contributed machine reports served models on: only while the add-on is on, so the host asks grid nothing otherwise. */
export const hostLocalGrid = (state: SuperTabState) => state.localModels?.enabled ? { localGrid: state.localModels.grid } : {}
export function servedLocalModels(state: SuperTabState, now: number) {
const grid = state.localModels?.enabled ? state.localModels.grid : null
if (!grid) return []
return swarmMachines(state).flatMap(m => !m.observation || now - m.observation.receivedAt > MACHINE_FRESH_MS ? []
: (m.observation.localModels ?? []).filter(l => l.grid === grid && !l.starting).map(l => ({ ...l, machineId: m.machineId })))
}
/** Whether a start names a model it may run on now: one the Swarm's grid serves, from any machine; or one on another grid
* that the start's own machine reads it can use (shared with its owner, owner 2026-10-23). Grid models carry no
* subscription model or effort. */
export function localModelAllowed(state: SuperTabState, request: AgentStartRequest, now: number): boolean {
const grid = state.localModels?.enabled ? state.localModels.grid : null
if (!grid || !request.gridModel || !request.gridName || request.model || request.effort) return false
if (request.gridName === grid) return servedLocalModels(state, now).some(l => l.model === request.gridModel)
const pool = (state.machines ?? []).find(m => m.machineId === request.machineId)
return !!pool?.observation && now - pool.observation.receivedAt <= MACHINE_FRESH_MS
&& (pool.observation.localModels ?? []).some(l => l.grid === request.gridName && l.model === request.gridModel && !l.starting)
}
/** `teamMachines`: the tab's machines whose account row is signed in as a team account, read by the store. A start is
* admitted again when its host launches it, so a Team machine whose check failed or went stale since never launches it. */
/** [forProject]: the project it is for when that is not yet its conversation's, as New Project's Product Manager before the
* project exists (leadStart.ts leadChoices). */
export function admitMachineStart(state: SuperTabState, request: AgentStartRequest, now: number, start?: AgentStart, teamMachines: readonly string[] = [],
otherWorkspaceMachines: readonly string[] = [], forProject?: SwarmProject,
/** A read that admits many machines against one state counts their slots once (leadStart.ts leadChoices). */
slots: (pool: ContributedMachine) => number = pool => machineSlots(state, pool)) {
const pool = machineContribution(state, request.machineId)
if (!pool) return null
// No new agent in a Harness Team account, whoever asks (task #4120): its agents keep what they hold until they are stopped.
if (teamAccountPool(pool)) failTeamWork(TEAM_ACCOUNTS_GONE)
if (pool.buddyOnly && request.buddyOf?.personId !== pool.contributorId) fail('NOT_SWARM_MACHINE', NOT_SWARM_MACHINE, 403)
// At its add and again at its launch: a Buddy-only machine is first read after its Buddy was asked for.
if (request.buddyOf && refusesWindowsBuddy(pool)) fail('BUDDY_WINDOWS', BUDDY_WINDOWS_REFUSAL, 403)
if (pool.removal) fail('MACHINE_REMOVED', 'This machine is being removed from the Swarm.')
if (start && start.poolGeneration !== pool.generation) fail('CONTRIBUTION_REVOKED', 'This machine contribution changed. Reconcile the original start.', 403)
if (pool.paused) fail('MACHINE_PAUSED', 'New work is paused on this machine.')
// A person's one Buddy chat has no project (Dee, 10-31): its project session works in the one it names, and its main Buddy
// and plain sessions in none, in their own folder (buddyHomeFolder).
const group = forProject ? undefined : conversation(state, request.conversationId)
// A Regular agent's own chat has none either (agent.new, task #4116): it starts in its person's home folder. A Member's start
// names its project (members.ts, task #4697), and starts in that project's folder as any project agent does (#4698).
const project = forProject ?? (request.member ? projectOf(state, request.member.projectId) : isAgentChat(group!) ? undefined : !isSwarmBuddyChat(group!) ? groupProject(state, group!)
: request.buddySession?.projectId ? projectOf(state, request.buddySession.projectId) : undefined)
if (project && !pool.scope && project.id !== 'lead') fail('PROJECT_CONTRIBUTION', 'Ask its owner to add this machine to the swarm again to support other projects.')
// Kept by its owner for other projects: a Product Manager too. A Buddy is its owner's own (commands.ts buddy.create).
const kept = project && !request.buddyOf ? machineProjectRefusal(state, pool.machineId, project) : null
if (kept) failTeamWork(kept)
const held = teamAccountPool(pool) ? productManagerOn(state, pool.machineId) : null
if (held && held !== project?.id) {
fail('TEAM_ACCOUNT_HELD', `The Harness Team account on ${pool.name} runs another project's Product Manager, so it takes only that project's work for now.`, 403)
}
// Before the request's own fields: a machine that takes none of this project's work says so first. A Buddy is its owner's
// own agent on their own machine (commands.ts buddy.create), as a Lead is: teammates' work rules do not apply to it. Nor to
// a Product Manager outside a Team account: any machine of the Swarm takes it (leadStart.ts, Ken 10-29).
// What the task needs to reach, checked here for every start whatever the route sent (an older CLI drops needs.access):
// a Buddy and a Product Manager need none (design section 3).
const needed = !request.buddyOf && !request.leadFor && !request.regular ? taskAccess(group) : []
if (!request.buddyOf && !request.leadFor && !request.regular) requireTeamWork(state, pool.machineId, pool.contributorId, project!)
const missing = project ? accessRefusal(state, pool.machineId, project, needed) : null
if (missing) failTeamWork(missing)
const cwd = project ? projectFolder(pool, project) : buddyHomeFolder(pool, { id: request.buddyOf?.personId ?? pool.contributorId })
// Every refused field is named, with what the machine does accept. Values the caller sent are not echoed: an account
// setting can be a path or a name of the caller's own.
const refused: string[] = []
if (request.cwd !== cwd) refused.push(`cwd (this project uses ${cwd} on it)`)
const engines = contributedEngines(pool)
if (!engines.includes(request.engine)) refused.push(`engine (it contributes ${engines.join(', ') || 'no engines'})`)
// A model served on the Swarm's own grid is the one exception to "default account settings": the owner turned the
// add-on on, and some machine of the Swarm serves it now.
const local = localModelAllowed(state, request, now)
const settings = (['codexHome', 'gridModel', 'gridName'] as const).filter(key => request[key] && !(local && key !== 'codexHome'))
if (settings.length) refused.push(`${settings.join(', ')} (it runs with its own default account settings, so leave ${settings.length > 1 ? 'them' : 'it'} out)`)
// Swarm v3 (task #4215): an agent starts with its owner's own permission settings, so a start names no mode. Last, in the
// words a CLI from before full mode answers by sending the start again without it (cli superTabs/start.ts before #4215).
if (request.permissionMode !== undefined) refused.push('permissionMode (it runs with its own default account settings, so leave it out)')
if (refused.length) {
fail('OUTSIDE_CONTRIBUTION', `${pool.name} accepts only its contributed project folder, engines and default account settings. Refused: ${refused.join('; ')}.`, 403)
}
// A Buddy-only machine is recorded with its Buddy's start, before its host ever read the Swarm: the start waits for it.
if (machineOffline(pool, now) && !(pool.buddyOnly && !pool.observation)) fail('MACHINE_OFFLINE', 'Wait for a fresh reading from the contributed machine.')
if (!start) admitByRoom(state, pool, slots(pool), request.requirements.memoryBytes, request.buddyOf ? 'a Buddy' : 'an agent')
const machineReason = !start ? machineSuspensionReason(pool, now) : null
if (machineReason) fail('MACHINE_UNAVAILABLE', machineReason)
// A new start only: a grid model runs without the engine's subscription, and one already asked for is settled by its host.
const unusable = !start && !local ? engineUnusable(pool, request.engine, now) : null
if (unusable) fail('ENGINE_UNAVAILABLE', unusable)
return pool
}
/** What one agent needs to start, as the CLI asks (capacity.ts START_REQUIREMENTS.memoryBytes). */
export const AGENT_MEMORY_BYTES = 2 * 1024 ** 3
/** The most agents any machine runs, as machine.contribute's own bound: a ceiling on growth, never a setting. */
export const MACHINE_AGENTS_CEILING = 1024
/** What joining suggested before 11-04 (CLI prepareContribution, Desktop superTabSuggestedAgentSlots): one agent per 4 GiB,
* 1 to 16. Joining stored it as a limit; Mac 3 refused Milo's engineer at 16 (Dee, 11-04). */
export const joinSuggestion = (memoryTotalBytes: number): number =>
Math.max(1, Math.min(16, Math.floor(memoryTotalBytes / (2 * AGENT_MEMORY_BYTES))))
/** The count its owner holds a machine to, or null when it takes agents as memory allows. A Buddy-only machine counts its
* own Buddies (commands.ts). An older row says neither (a compatibility rule: review it once Desktop and the CLI send
* `agents`, and remove it when no stored row lacks it): a stored number that is the old join suggestion (16, or the one its
* measured memory gave) was never the owner's own limit; any other number is. Desktop's old As memory allows stored the
* machine's maximum (one per 2 GiB), which free memory reaches first anyway. */
export function agentLimit(pool: Pick<ContributedMachine, 'maxAgents' | 'agents' | 'buddyOnly' | 'observation'>): number | null {
if (pool.buddyOnly || pool.agents === 'atMost') return pool.maxAgents
if (pool.agents === 'memory') return null
if (pool.maxAgents === 16) return null
const total = pool.observation?.resources?.memoryTotalBytes
// Under 4 GiB the suggestion was its floor of 1, not a figure from memory.
if (typeof total === 'number' && total >= 2 * AGENT_MEMORY_BYTES && pool.maxAgents === joinSuggestion(total)) return null
return pool.maxAgents
}
/** Its measured free memory, from its last reading; null with none. */
export function freeMemoryBytes(pool: Pick<ContributedMachine, 'observation'>): number | null {
const r = pool.observation?.resources
return r && typeof r.memoryTotalBytes === 'number' && typeof r.memoryUsedBytes === 'number' ? Math.max(0, r.memoryTotalBytes - r.memoryUsedBytes) : null
}
/** A Mac and its Harness Team account: one machine, one memory (slotCounter counts their slots together too). */
function memoryPair(state: SuperTabState, pool: ContributedMachine): ContributedMachine[] {
const mac = pool.hostMachineId ? state.machines?.find(m => m.machineId === pool.hostMachineId && m.contributorId === pool.contributorId) : pool
return [...new Set([pool, mac, mac && teamPoolOf(state, mac)])].filter((m): m is ContributedMachine => !!m)
}
/** What a new start can use on [pool] as memory allows: the least free memory its Mac and Team account last read, less what
* starts admitted there and not yet launched will take, which no reading shows yet (review of #3001: three 2 GiB starts
* were all admitted on 5 GiB free). Null with no reading. */
export function startableMemoryBytes(state: SuperTabState, pool: ContributedMachine): number | null {
const pair = memoryPair(state, pool)
const readings = pair.map(freeMemoryBytes).filter((free): free is number => free !== null)
if (!readings.length) return null
const machines = new Set(pair.map(m => m.machineId))
let held = 0
for (const start of state.starts ?? []) {
if (start.error || start.harnessId || !machines.has(start.request.machineId)) continue
held += start.request.requirements?.memoryBytes || AGENT_MEMORY_BYTES
}
return Math.max(0, Math.min(...readings) - held)
}
/** How many more agents it takes now, for the route and Desktop: its owner's count less what runs, or, as memory allows,
* one per AGENT_MEMORY_BYTES of startable memory (none with no reading). Its host checks free memory and disk again at
* each launch. */
export function availableSlots(state: SuperTabState, pool: ContributedMachine, used: number): number {
const limit = agentLimit(pool)
const ceiling = Math.max(0, (limit ?? MACHINE_AGENTS_CEILING) - used)
if (limit !== null) return ceiling
const free = startableMemoryBytes(state, pool)
return free === null ? 0 : Math.min(ceiling, Math.floor(free / AGENT_MEMORY_BYTES))
}
const gib = (bytes: number) => `${Math.round(bytes / 1024 ** 3 * 100) / 100} GB`
/** A new start's room on [pool], said in words its owner can act on: its own count, or its free memory. */
export function admitByRoom(state: SuperTabState, pool: ContributedMachine, used: number, memoryBytes: number, who = 'an agent') {
const limit = agentLimit(pool)
if (limit !== null) {
if (used >= limit) fail('MACHINE_FULL', `${pool.name} is set to run at most ${limit} agent${limit === 1 ? '' : 's'} and runs ${used}. Its owner can change that in its settings, or try again when one finishes.`)
return
}
if (used >= MACHINE_AGENTS_CEILING) fail('MACHINE_FULL', `${pool.name} already runs ${used} agents, the most any machine runs.`)
const free = startableMemoryBytes(state, pool)
if (free !== null && free < memoryBytes) {
fail('MACHINE_FULL', `${pool.name} is out of free memory: ${gib(free)} free, and ${who} needs ${gib(memoryBytes)}. Try again when an agent there finishes, or pick another machine.`,
409, { reason: 'memory' })
}
}