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.

Swarm from scratch: GitHub access status, Team account npm, a Mac's teammates' work

bitcoinbuildere3428335e3d7
diff --git a/backend/src/github/app.test.ts b/backend/src/github/app.test.ts
index 51eeb4341..fdf98fb02 100644
--- a/backend/src/github/app.test.ts
+++ b/backend/src/github/app.test.ts
@@ -158,6 +158,10 @@ describe('installation tokens', () => {
const asked = github.calls.filter(c => c.path.startsWith('/users/'))
expect(asked).toEqual([expect.objectContaining({ method: 'GET', path: '/users/harness-fixture%5Bbot%5D', auth: '' })])
// With no app name configured, the app's own answer names it.
+ // With a token, asked with it: unsigned requests from a server's shared address can be refused (PR #1948).
+ const signed = setup()
+ await signed.app.commitIdentity('ghs_issued')
+ expect(signed.github.calls.find(c => c.path.startsWith('/users/'))?.auth).toBe('Bearer ghs_issued')
const unnamed = setup({ slug: null })
expect(await unnamed.app.commitIdentity()).toMatchObject({ name: 'harness-fixture[bot]' })
expect(unnamed.github.calls.map(c => c.path)).toEqual(['/app', '/users/harness-fixture%5Bbot%5D'])
diff --git a/backend/src/github/app.ts b/backend/src/github/app.ts
index 9034f4f93..d922e9000 100644
--- a/backend/src/github/app.ts
+++ b/backend/src/github/app.ts
@@ -97,6 +97,7 @@ export class GitHubApp {
private readonly branches = new Map<string, { value: DefaultBranch; until: number }>()
/** A repository's name now, by the name asked for (lower case): null when it was not renamed. */
private readonly renames = new Map<string, { repository: GitHubRepository | null; until: number }>()
+ private readonly shownNames = new Map<string, { name: string; until: number }>()
/** When each repository's "not installed" was last forgotten on request ([forget]). */
private readonly forgotten = new Map<string, number>()
@@ -116,8 +117,10 @@ export class GitHubApp {
* so a commit made with the app's token shows the app, not the made-up address of the machine account that ran git. A Harness
* Team account has no git identity of its own, so its commits read "Harness Team <harnessteam@<host>.local>", unverified and
* linked to nobody (PR #1934, 2026-10-28). Read once and kept; null while GitHub cannot say, asked again ten minutes later.
+ * [token]: a token to ask with. Asked without one, from a server's shared address, GitHub's limit for unsigned
+ * requests could refuse it, and a Team account's commits stayed the machine's (PR #1948): the token just issued is used.
*/
- async commitIdentity(): Promise<CommitIdentity | null> {
+ async commitIdentity(token?: string): Promise<CommitIdentity | null> {
if (this.identity && (this.identity.value || this.identity.until > this.now())) return this.identity.value
let value: CommitIdentity | null = null
try {
@@ -129,12 +132,12 @@ export class GitHubApp {
}
if (slug) {
const login = `${slug}[bot]`
- // Public: the app's own JWT is not accepted here, and the bot's id is no secret.
- const user = await this.call('GET', `/users/${encodeURIComponent(login)}`, null)
+ // The app's own JWT is not accepted here; any installation token is, and the bot's id is no secret.
+ const user = await this.call('GET', `/users/${encodeURIComponent(login)}`, token ? `Bearer ${token}` : null)
const id = (user.body as { id?: unknown }).id
if (user.status === 200 && typeof id === 'number' && Number.isSafeInteger(id) && id > 0) {
value = { name: login, email: `${id}+${login}@users.noreply.github.com` }
- }
+ } else console.warn(`[github] the app's bot account ${login} was not read: HTTP ${user.status}`)
}
} catch (error) {
if (!(error instanceof GitHubAppError)) throw error
@@ -218,6 +221,21 @@ export class GitHubApp {
return renamed === null ? null : { installation: renamed, repository: current }
}
+ /**
+ * [repository]'s name as GitHub shows it now, for people to read: a project keeps the address it was given, and GitHub
+ * answers an old name by redirect, so a renamed repository was shown by the name it no longer has (autonomous-harness
+ * for autonomous-ai/openharness, 2026-10-28). Its own name when GitHub cannot say. Kept ten minutes either way, so a
+ * status read costs at most one lookup per repository in that time.
+ */
+ async currentFullName(repository: GitHubRepository): Promise<string> {
+ const key = repository.fullName.toLowerCase()
+ const known = this.shownNames.get(key)
+ if (known && known.until > this.now()) return known.name
+ const name = (await this.currentName(repository))?.fullName ?? repository.fullName
+ this.shownNames.set(key, { name, until: this.now() + INSTALLATION_TTL_MS })
+ return name
+ }
+
/** [repository]'s name now when it was renamed, else null: read with a read-only token of its owner's installation of
* the app, which GitHub answers by the repository's id once it moved. The token is revoked at once. */
private async currentName(repository: GitHubRepository): Promise<GitHubRepository | null> {
diff --git a/backend/src/github/projectAccess.test.ts b/backend/src/github/projectAccess.test.ts
index 85e87371e..44f37e8de 100644
--- a/backend/src/github/projectAccess.test.ts
+++ b/backend/src/github/projectAccess.test.ts
@@ -39,6 +39,29 @@ describe('a Swarm project\'s GitHub access', () => {
expect(asked).toBe('acme/app')
})
+ // autonomous-ai/autonomous-harness, renamed autonomous-ai/openharness: GitHub answers the old name by redirect, so the
+ // project showed a name the repository no longer has (2026-10-28).
+ it('shows a renamed repository by its name now, and keeps approvals with the project\'s address', async () => {
+ const { github, app, advance } = setup()
+ github.installed.set('acme/old', 77)
+ github.owners.set('acme', 77)
+ github.renamed.set('acme/old', 'acme/new')
+ let asked = ''
+ const read = () => projectGitHubAccess(app, 'https://github.com/acme/old', { approved: async (repository) => { asked = repository; return true }, canApprove: true })
+ expect(await read()).toEqual({ state: 'covered', repository: 'acme/new' })
+ expect(asked).toBe('acme/old')
+ const lookups = () => github.calls.filter(c => c.path === '/repos/acme/old').length
+ expect(lookups()).toBe(1)
+ // Kept ten minutes, a repository that was not renamed too.
+ await read()
+ expect(lookups()).toBe(1)
+ advance(10 * 60_000 + 1)
+ github.renamed.delete('acme/old')
+ github.installed.set('acme/old', 77)
+ expect(await read()).toEqual({ state: 'covered', repository: 'acme/old' })
+ expect(lookups()).toBe(2)
+ })
+
it('reads GitHub not answering as unknown, never as covered, and says when the app\'s credentials are wrong', async () => {
const { github, app } = setup()
github.control.down = true
diff --git a/backend/src/github/projectAccess.ts b/backend/src/github/projectAccess.ts
index afa48a489..88a6fd588 100644
--- a/backend/src/github/projectAccess.ts
+++ b/backend/src/github/projectAccess.ts
@@ -18,7 +18,7 @@ export type ProjectGitHubAccess =
/** [app]: this server's GitHub App, null when it has none. [approved]: whether someone who can push to the repository
* approved it for this project (github/approvals.ts). [canApprove]: this server has the app's sign-in to approve with.
* [refresh]: a person asked to check again. */
-export async function projectGitHubAccess(app: Pick<GitHubApp, 'resolve' | 'forget' | 'installUrl'> | null, repositoryUrl: string | null,
+export async function projectGitHubAccess(app: Pick<GitHubApp, 'resolve' | 'forget' | 'installUrl' | 'currentFullName'> | null, repositoryUrl: string | null,
approval: { approved: (repository: string) => Promise<boolean>; canApprove: boolean }, refresh = false): Promise<ProjectGitHubAccess> {
if (!app) return { state: 'unavailable' }
if (!repositoryUrl) return { state: 'no-repository' }
@@ -26,11 +26,14 @@ export async function projectGitHubAccess(app: Pick<GitHubApp, 'resolve' | 'forg
if (!repository) return { state: 'not-github', repositoryUrl }
if (refresh) app.forget(repository)
try {
- if (!await app.resolve(repository)) {
+ const resolved = await app.resolve(repository)
+ if (!resolved) {
return { state: 'not-installed', repository: repository.fullName, installUrl: app.installUrl(), canApprove: approval.canApprove }
}
- return await approval.approved(repository.fullName.toLowerCase()) ? { state: 'covered', repository: repository.fullName }
- : { state: 'not-approved', repository: repository.fullName, canApprove: approval.canApprove }
+ // Shown by its name now; approvals stay with the address the project names.
+ const shown = resolved.repository.fullName !== repository.fullName ? resolved.repository.fullName : await app.currentFullName(repository)
+ return await approval.approved(repository.fullName.toLowerCase()) ? { state: 'covered', repository: shown }
+ : { state: 'not-approved', repository: shown, canApprove: approval.canApprove }
} catch (error) {
// Wrong app credentials are the server's to fix and say so; GitHub not answering is never read as covered.
if (error instanceof GitHubAppError && error.code === 'GITHUB_APP_MISCONFIGURED') throw error
diff --git a/backend/src/routes/superTabs.ts b/backend/src/routes/superTabs.ts
index e112beb23..7d835e3af 100644
--- a/backend/src/routes/superTabs.ts
+++ b/backend/src/routes/superTabs.ts
@@ -353,7 +353,7 @@ export async function superTabRoutes(app: FastifyInstance, options: { store?: Su
const issued = await github.issue({ tabId: grant.tabId, agentId: grant.agentId, assignmentId: grant.assignmentId, repository })
// A Harness Team account has no git identity of its own: its commits are the app's, as its pull requests are
// (github/app.ts commitIdentity). A person's machine keeps its owner's, as before.
- const commitAs = isTeamSession(req.user) ? await github.app.commitIdentity() : null
+ const commitAs = isTeamSession(req.user) ? await github.app.commitIdentity(issued.token) : null
return { ...issued, ...attribution(grant), ...(commitAs ? { commitAs } : {}) }
}))
app.post<{ Params: z.infer<typeof tabParams>; Body: z.infer<typeof operation> }>('/api/super-tabs/:tabId/commands',
diff --git a/backend/src/superTabs/machines.ts b/backend/src/superTabs/machines.ts
index 94a10fdc6..305188df5 100644
--- a/backend/src/superTabs/machines.ts
+++ b/backend/src/superTabs/machines.ts
@@ -263,6 +263,19 @@ export function teamPoolOf(state: SuperTabState, pool: ContributedMachine, live?
.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: a Mac whose Harness Team account is in this Swarm runs
+ * that work there (teamMachineFor), so it reads as its account does. Read as itself, every Mac read "has no Harness
+ * Team account yet" next to the very account that took the work, and a Lead took that to mean the Mac could not
+ * (2026-10-28). Any other machine, and a Mac without one, reads as itself.
+ */
+export function machineTeamWork(state: SuperTabState, pool: ContributedMachine, now: number, teamMachines: readonly string[],
+ otherWorkspaceMachines: readonly string[] = []): TeamWorkRefusal | null {
+ const team = !pool.hostMachineId && teamAccountSwarm(state) ? teamPoolOf(state, pool, teamMachines) : undefined
+ const subject = team ?? pool
+ return teamWorkRefusal(subject, now, teamMachines.includes(subject.machineId), teamAccountRequired(state), otherWorkspaceMachines.includes(subject.machineId))
+}
+
/** Where a new agent for [project] runs when a start names [machineId]: the Mac's team account when the project is not
* its contributor's own and the Mac has one in this Swarm, else the machine named. */
export function teamMachineFor(state: SuperTabState, machineId: string, project: SwarmProject, idle = false, live?: readonly string[]): string {
diff --git a/backend/src/superTabs/read/views.ts b/backend/src/superTabs/read/views.ts
index 8d204a066..c1c60e49e 100644
--- a/backend/src/superTabs/read/views.ts
+++ b/backend/src/superTabs/read/views.ts
@@ -4,7 +4,7 @@
* in `derived`, so a part never changes without a new version (Lead's ruling).
*/
import { isLeads, seenMachineIds, visibleState, withSeenRequirement, type Actor, type Agent, type Conversation, type SuperTabState } from '../model.js'
-import { machineSlots, teamAccountRequired, teamAccountSwarm, teamWorkRefusal, type ContributedMachine } from '../machines.js'
+import { machineSlots, machineTeamWork, teamAccountSwarm, type ContributedMachine } from '../machines.js'
import * as store from '../parts/index.js'
import type { Part, SwarmParts } from '../parts/index.js'
import { canReadGroup } from '../projects.js'
@@ -99,8 +99,7 @@ export const progressView = (data: NonNullable<SwarmParts['progress'][number]['d
function derive(state: SuperTabState, visible: SuperTabState, actor: Actor, now: number, extras: ReadExtras): Derived {
const machine = (pool: ContributedMachine) => {
const stored = state.machines!.find(m => m.machineId === pool.machineId)!
- const refusal = teamWorkRefusal(stored, now, extras.teamMachines.includes(pool.machineId), teamAccountRequired(state),
- !!extras.otherWorkspaceMachines?.includes(pool.machineId))
+ const refusal = machineTeamWork(state, stored, now, extras.teamMachines, extras.otherWorkspaceMachines ?? [])
return [pool.machineId, { availableSlots: Math.max(0, pool.maxAgents - machineSlots(state, stored)),
teamWork: refusal ? { allowed: false as const, ...refusal } : { allowed: true as const } }] as const
}
diff --git a/backend/src/superTabs/store.ts b/backend/src/superTabs/store.ts
index 98f7c2f15..94d3a0af2 100644
--- a/backend/src/superTabs/store.ts
+++ b/backend/src/superTabs/store.ts
@@ -1,4 +1,4 @@
-import { contributedEngines, expireRemovals, LASTING_TEAM_REFUSALS, machineContribution, machineObservationSchema, machineSlots, observedPrivacy, recordAgentPresence, removalPreview, startPreparing, swarmGridRow, teamAccountRequired, teamWorkRefusal, type MachineObservation } from './machines.js'
+import { contributedEngines, expireRemovals, LASTING_TEAM_REFUSALS, machineContribution, machineObservationSchema, machineSlots, machineTeamWork, observedPrivacy, recordAgentPresence, removalPreview, startPreparing, swarmGridRow, teamAccountRequired, teamWorkRefusal, type MachineObservation } from './machines.js'
import { createHash } from 'node:crypto'
import type { Prisma, PrismaClient, SuperTabDelivery, SuperTabMessage } from '@prisma/client'
import type { AuthUser } from '../lib/ssoAuth.js'
@@ -746,7 +746,7 @@ export class SuperTabStore {
const stored = state.machines!.find(m => m.machineId === pool.machineId)!
// Whether it takes teammates' projects now, and if not why (machines.ts teamWorkRefusal): what routing leaves it
// out for, and what Desktop can show on the machine.
- const refusal = teamWorkRefusal(stored, now, teamMachines.includes(pool.machineId), teamAccountRequired(state), otherWorkspace.includes(pool.machineId))
+ const refusal = machineTeamWork(state, stored, now, teamMachines, otherWorkspace)
return { ...pool, availableSlots: Math.max(0, pool.maxAgents - machineSlots(state, stored)),
teamWork: refusal ? { allowed: false as const, ...refusal } : { allowed: true as const } }
}) } }
diff --git a/backend/src/superTabs/teamRouting.test.ts b/backend/src/superTabs/teamRouting.test.ts
index b8bbb5224..47489a4cf 100644
--- a/backend/src/superTabs/teamRouting.test.ts
+++ b/backend/src/superTabs/teamRouting.test.ts
@@ -1,6 +1,6 @@
import { afterEach, beforeEach, describe, expect, it } from 'vitest'
import { applyCommand, type Command, type CommandContext } from './commands.js'
-import { admitMachineStart, machineObservationSchema, machineSlots, observedPrivacy, PRIVACY_FRESH_MS, removalPreview, teamAccountRequired, teamAccountSwarm, teamWorkRefusal, type ContributedMachine, type MachinePrivacy } from './machines.js'
+import { admitMachineStart, machineObservationSchema, machineTeamWork, machineSlots, observedPrivacy, PRIVACY_FRESH_MS, removalPreview, teamAccountRequired, teamAccountSwarm, teamWorkRefusal, type ContributedMachine, type MachinePrivacy } from './machines.js'
import { createSuperTab, SuperTabError, visibleState, type Actor, type AgentConfiguration, type AgentStart, type SuperTabState } from './model.js'
import type { RouteDecision } from './routeRecord.js'
@@ -440,6 +440,23 @@ describe('one machine: a Mac and its Harness Team account', () => {
expect(f.state.starts![1]!.request).toMatchObject({ machineId: 'mate-team', cwd: '/team-swarm/lead' })
})
+ // 2026-10-28: every Mac read "has no Harness Team account yet" beside the account that took its teammates' work.
+ it('reads a Mac as its Harness Team account does, since that is where its teammates\' work runs', () => {
+ const f = oneMachine()
+ f.machine('mate-mac').observation = reading('computer')
+ f.machine('mate-team').observation = reading('team', PASSED)
+ expect(machineTeamWork(f.state, f.machine('mate-mac'), NOW, ['mate-team'])).toBeNull()
+ f.machine('mate-team').observation = reading('team', FAILED)
+ expect(machineTeamWork(f.state, f.machine('mate-mac'), NOW, ['mate-team'])?.code).toBe('PRIVACY_CHECK_FAILED')
+ expect(machineTeamWork(f.state, f.machine('mate-mac'), NOW, ['mate-team'], ['mate-team'])?.code).toBe('MACHINE_IN_OTHER_WORKSPACE')
+ // The account itself reads as itself; a Mac whose account is no longer signed in, or outside the Swarms it is tried in,
+ // reads as a Mac without one.
+ expect(machineTeamWork(f.state, f.machine('mate-team'), NOW, ['mate-team'])?.code).toBe('PRIVACY_CHECK_FAILED')
+ expect(machineTeamWork(f.state, f.machine('mate-mac'), NOW, [])?.code).toBe('TEAM_ACCOUNT_REQUIRED')
+ process.env.SWARM_TEAM_ACCOUNT_OWNERS = '[email protected]'
+ try { expect(machineTeamWork(f.state, f.machine('mate-mac'), NOW, ['mate-team'])).toBeNull() } finally { delete process.env.SWARM_TEAM_ACCOUNT_OWNERS }
+ })
+
it('once the team account is removed, its pool left behind takes nothing: the Mac is a Mac without one again', () => {
// Its machine is deleted, so the store no longer lists it among the tab's team machines.
const f = oneMachine(), group = f.group()
diff --git a/cli/src/superTabs/service.ts b/cli/src/superTabs/service.ts
index 60494b8ed..50248582c 100644
--- a/cli/src/superTabs/service.ts
+++ b/cli/src/superTabs/service.ts
@@ -25,6 +25,8 @@ import { ensureTeamTmux, TMUX_MANIFEST_URL, tmuxRunsAt, untarGz, type TeamTmuxDe
import { downloadVerified } from '../lib/selfUpdate.js'
import { managedTmuxPath, tmuxInstallDirectories } from '../lib/tmuxOnPath.js'
import { ensureTeamGh, ghRunsAt, unzipArchive, type TeamGhDeps, type TeamGhOutcome } from '../team/gh.js'
+import { managedNodePath } from '../lib/nodeRuntime.js'
+import { linkTeamNodeTools, type TeamNodeToolsDeps } from '../team/nodeTools.js'
import { env as appEnv } from '../config/env.js'
import { homedir, userInfo } from 'node:os'
import { delimiter, isAbsolute, join } from 'node:path'
@@ -208,6 +210,8 @@ export interface SuperTabServiceOptions {
teamTmux?: () => Promise<TeamTmuxOutcome>
/** What installs the Harness Team account's own gh (team/gh.ts), for a spec. */
teamGh?: () => Promise<TeamGhOutcome>
+ /** What links the Harness Team account's npm and npx (team/nodeTools.ts), for a spec. */
+ teamNodeTools?: () => unknown
/** The owner's subscriptions for the Harness Team account (team/relay.ts), for a spec. */
teamRelay?: () => Pick<TeamRelayPublisher, 'start' | 'stop'>
}
@@ -274,6 +278,7 @@ export function superTabService(core: CoreApi, options: SuperTabServiceOptions =
if (Date.now() - ghCheckedAt >= 30 * 60_000) {
ghCheckedAt = Date.now()
void ensureGh().then(outcome => { if (settled(outcome)) ghCheckedAt = Infinity })
+ ;(options.teamNodeTools ?? (() => linkTeamNodeTools(realTeamNodeToolsDeps())))()
}
}
const disconnect = () => { preparations.clear(); host?.stop(); host = null; held = null; book?.stop(); book = null; bookMachine = null; swarmCards?.want(false); swarmCards = null; cardsMachine = null; tokens.stop(); engines.stop() }
@@ -555,6 +560,16 @@ function realTeamTmuxDeps(): TeamTmuxDeps {
}
}
+/** The team daemon's own Node and bin folder (team/nodeTools.ts). */
+function realTeamNodeToolsDeps(): TeamNodeToolsDeps {
+ return {
+ team: () => { try { return readTeamConfig()?.user === userInfo().username } catch { return false } },
+ node: managedNodePath,
+ binDir: join(homedir(), '.local', 'bin'),
+ log: (line) => console.log(`[team] ${line}`),
+ }
+}
+
/** The team daemon's own, as for its tmux: its account, its PATH and Homebrew's places (team/gh.ts). */
function realTeamGhDeps(): TeamGhDeps {
const binDir = join(homedir(), '.local', 'bin')
diff --git a/cli/src/team/nodeTools.spec.ts b/cli/src/team/nodeTools.spec.ts
new file mode 100644
index 000000000..2d3ea0bfa
--- /dev/null
+++ b/cli/src/team/nodeTools.spec.ts
@@ -0,0 +1,57 @@
+import { execFileSync } from 'node:child_process'
+import { mkdirSync, mkdtempSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { linkTeamNodeTools, type TeamNodeToolsDeps } from './nodeTools.js'
+
+const cleanup: string[] = []
+afterEach(() => { for (const dir of cleanup.splice(0)) rmSync(dir, { recursive: true, force: true }) })
+
+/** A home with Harness's Node laid out as setup copies it: bin/node, and npm and npx as links into lib, as Node ships. */
+function home(tools = true) {
+ const dir = mkdtempSync(join(tmpdir(), 'team-node-'))
+ cleanup.push(dir)
+ const runtime = join(dir, '.harness', 'runtime', 'node-v22')
+ mkdirSync(join(runtime, 'bin'), { recursive: true })
+ mkdirSync(join(runtime, 'lib', 'node_modules', 'npm', 'bin'), { recursive: true })
+ writeFileSync(join(runtime, 'bin', 'node'), '#!/bin/sh\n', { mode: 0o755 })
+ if (tools) {
+ for (const [tool, script] of [['npm', 'npm-cli.js'], ['npx', 'npx-cli.js']] as const) {
+ writeFileSync(join(runtime, 'lib', 'node_modules', 'npm', 'bin', script), `#!/bin/sh\necho ${tool} "$@"\n`, { mode: 0o755 })
+ symlinkSync(`../lib/node_modules/npm/bin/${script}`, join(runtime, 'bin', tool))
+ }
+ }
+ const deps: TeamNodeToolsDeps = { team: () => true, node: () => join(runtime, 'bin', 'node'), binDir: join(dir, '.local', 'bin'), log: vi.fn() }
+ return { dir, runtime, deps }
+}
+
+describe('npm and npx for the Harness Team account', () => {
+ // 2026-10-28: setup linked only node, so a teammate's Builder in the team account had no npm.
+ it('links them from its own Node where they are missing, and they run', () => {
+ const { runtime, deps } = home()
+ expect(linkTeamNodeTools(deps)).toEqual(['npm', 'npx'])
+ expect(readlinkSync(join(deps.binDir, 'npm'))).toBe(join(runtime, 'bin', 'npm'))
+ expect(execFileSync(join(deps.binDir, 'npx'), ['-v'], { encoding: 'utf8' })).toBe('npx -v\n')
+ expect(deps.log).toHaveBeenCalledWith(expect.stringContaining('linked npm and npx'))
+ // Once there, nothing again.
+ expect(linkTeamNodeTools(deps)).toEqual([])
+ })
+
+ it('leaves alone what is already there, an account that is not a team account, and a Node without them', () => {
+ const { deps } = home()
+ mkdirSync(deps.binDir, { recursive: true })
+ symlinkSync('/somewhere/gone', join(deps.binDir, 'npm'))
+ expect(linkTeamNodeTools(deps)).toEqual(['npx'])
+ expect(readlinkSync(join(deps.binDir, 'npm'))).toBe('/somewhere/gone')
+ expect(linkTeamNodeTools({ ...home().deps, team: () => false })).toEqual([])
+ expect(linkTeamNodeTools(home(false).deps)).toEqual([])
+ })
+
+ it('says why, and does not throw, when it cannot link', () => {
+ const { dir, deps } = home()
+ writeFileSync(join(dir, '.local'), 'a file where the folder goes')
+ expect(linkTeamNodeTools(deps)).toEqual([])
+ expect(deps.log).toHaveBeenCalledWith(expect.stringContaining('could not link npm'))
+ })
+})
diff --git a/cli/src/team/nodeTools.ts b/cli/src/team/nodeTools.ts
new file mode 100644
index 000000000..3ba9a93ba
--- /dev/null
+++ b/cli/src/team/nodeTools.ts
@@ -0,0 +1,48 @@
+/**
+ * npm and npx on the Harness Team account's PATH, from its own copy of Harness's Node.
+ *
+ * Setup linked only `node` into the account's `~/.local/bin`, so a teammate's Builder there had no npm: it could not
+ * install a project's packages or run its JavaScript tests, and the Swarm read the account as having no npm (2026-10-28,
+ * the account on this Mac and Mac Auto's). Setup now links them too (script.ts `TEAM_COPY`); an account set up before
+ * runs no setup again, so its daemon adds what is missing as it connects. It never replaces a link or file already there.
+ */
+import { existsSync, lstatSync, mkdirSync, symlinkSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+/** The Node tools linked beside `node`. */
+export const TEAM_NODE_TOOLS = ['npm', 'npx'] as const
+
+export interface TeamNodeToolsDeps {
+ /** Whether this daemon is a Mac's Harness Team account. */
+ team(): boolean
+ /** The account's own Node (`current-node`), whose folder holds npm and npx. */
+ node(): string
+ /** `~/.local/bin` of this account. */
+ binDir: string
+ log(line: string): void
+}
+
+/** Links each of [TEAM_NODE_TOOLS] the account's Node has and its bin folder lacks; what it linked. Never throws. */
+export function linkTeamNodeTools(deps: TeamNodeToolsDeps): string[] {
+ const linked: string[] = []
+ try {
+ if (!deps.team()) return linked
+ const from = dirname(deps.node())
+ for (const tool of TEAM_NODE_TOOLS) {
+ const target = join(deps.binDir, tool)
+ if (!existsSync(join(from, tool)) || present(target)) continue
+ mkdirSync(deps.binDir, { recursive: true })
+ symlinkSync(join(from, tool), target)
+ linked.push(tool)
+ }
+ if (linked.length) deps.log(`team: linked ${linked.join(' and ')} for the Harness Team account from ${from}`)
+ } catch (error) {
+ deps.log(`team: could not link npm for the Harness Team account: ${error instanceof Error ? error.message : String(error)}`)
+ }
+ return linked
+}
+
+/** A link or file at [path], even a link whose target is gone. */
+function present(path: string): boolean {
+ try { lstatSync(path); return true } catch { return false }
+}
diff --git a/cli/src/team/script.spec.ts b/cli/src/team/script.spec.ts
index 07327b27e..e13ebaca9 100644
--- a/cli/src/team/script.spec.ts
+++ b/cli/src/team/script.spec.ts
@@ -198,6 +198,7 @@ describe('the team account\'s copy of the runtime', () => {
mkdirSync(join(stage, 'cli'), { recursive: true })
mkdirSync(home)
writeFileSync(join(stage, 'node', 'bin', 'node'), '#!/bin/sh\necho node "$@"\n', { mode: 0o755 })
+ writeFileSync(join(stage, 'node', 'bin', 'npm'), '#!/bin/sh\n', { mode: 0o755 })
writeFileSync(join(stage, 'cli', 'cli.js'), '// cli')
writeFileSync(join(stage, 'cli', 'package.json'), '{"type":"module"}')
// A second run replaces what the first laid down.
@@ -207,6 +208,9 @@ describe('the team account\'s copy of the runtime', () => {
expect(existsSync(join(runtime, 'node-v1.next'))).toBe(false)
// On the account's PATH, so Codex's `#!/usr/bin/env node` launcher starts in its terminals.
expect(readlinkSync(join(home, '.local', 'bin', 'node'))).toBe(`${runtime}/node-v1/bin/node`)
+ // And npm, for a Builder's packages and tests; npx is linked only where the Node has it.
+ expect(readlinkSync(join(home, '.local', 'bin', 'npm'))).toBe(`${runtime}/node-v1/bin/npm`)
+ expect(existsSync(join(home, '.local', 'bin', 'npx'))).toBe(false)
expect(readFileSync(join(home, '.harness', 'cli', 'cli.js'), 'utf8')).toBe('// cli')
expect(existsSync(join(home, '.harness', 'cli', 'notify.mjs'))).toBe(false)
expect(statSync(join(home, '.harness')).mode & 0o777).toBe(0o700)
diff --git a/cli/src/team/script.ts b/cli/src/team/script.ts
index 5da6d015d..4728a8c94 100644
--- a/cli/src/team/script.ts
+++ b/cli/src/team/script.ts
@@ -167,6 +167,8 @@ export const TEAM_COPY = [
// `codex login` in a terminal on its machine would not start. ~/.local/bin is last on a login shell's PATH: a Node the
// system has wins.
'ln -sfn "$rt/$node_name/bin/node" "$bin/node"',
+ // And its npm and npx, so a teammate's Builder can install a project's packages and run its tests (team/nodeTools.ts).
+ 'for tool in npm npx; do [ ! -e "$rt/$node_name/bin/$tool" ] || ln -sfn "$rt/$node_name/bin/$tool" "$bin/$tool"; done',
'if [ -n "$tmux_name" ]; then',
' put_dir "$stage/tmux" "$rt/$tmux_name"',
` printf '%s\\n' "$rt/$tmux_name/bin/tmux" > "$rt/current-tmux.next" && mv -f "$rt/current-tmux.next" "$rt/current-tmux"`,
diff --git a/desktop/lib/super_tabs/controller.dart b/desktop/lib/super_tabs/controller.dart
index 1d7989e9c..e53bc3ed5 100644
--- a/desktop/lib/super_tabs/controller.dart
+++ b/desktop/lib/super_tabs/controller.dart
@@ -471,6 +471,26 @@ class SuperTabController extends ChangeNotifier {
_changed();
} catch (error) {
appLog.debug('super-tabs', 'project GitHub access not read: $error');
+ // A server without the route (an older backend) shows nothing, as before. Any other failure says it could not
+ // check, and is asked again after 30 seconds, not 5 minutes: a Swarm read in its first seconds came back
+ // empty and Project details showed no GitHub access at all (2026-10-28).
+ final absent =
+ error is SuperTabFailure &&
+ (error.statusCode == 404 || error.code == 'NOT_FOUND');
+ if (absent || _github[projectId] == null) {
+ _github[projectId] = (
+ value: SuperTabProjectGitHub.fromJson({
+ 'state': absent ? 'unavailable' : 'unread',
+ }),
+ at: clock.now(),
+ );
+ }
+ if (!absent) {
+ _githubAsked[projectId] = clock.now().subtract(
+ const Duration(minutes: 5) - const Duration(seconds: 30),
+ );
+ }
+ _changed();
} finally {
_githubReading.remove(projectId);
}
diff --git a/desktop/lib/super_tabs/project_github.dart b/desktop/lib/super_tabs/project_github.dart
index 0261cabb1..35c2eaa05 100644
--- a/desktop/lib/super_tabs/project_github.dart
+++ b/desktop/lib/super_tabs/project_github.dart
@@ -23,8 +23,8 @@ class SuperTabProjectGitHub {
canApprove = row['canApprove'] == true;
/// `covered`, `not-installed`, `not-approved` (installed, but nobody who can push to it approved it for this project:
- /// backend github/approvals.ts), `not-github`, `no-repository`, `unknown` (GitHub did not answer), or `unavailable`
- /// (the server has no GitHub App: nothing is shown).
+ /// backend github/approvals.ts), `not-github`, `no-repository`, `unknown` (GitHub did not answer), `unread` (this
+ /// app could not ask the server), or `unavailable` (the server has no GitHub App: nothing is shown).
final String state;
final String? repository;
final String? installUrl;
@@ -63,6 +63,9 @@ class _ProjectGitHubAccessState extends State<ProjectGitHubAccess>
bool _busy = false;
String? _error;
+ /// GitHub's page is open in the browser: said here until the person is back and it is read again.
+ bool _inBrowser = false;
+
@override
void initState() {
super.initState();
@@ -99,7 +102,12 @@ class _ProjectGitHubAccessState extends State<ProjectGitHubAccess>
Future<void> _check() async {
setState(() => _checking = true);
await widget.controller.readGitHubAccess(widget.projectId, refresh: true);
- if (mounted) setState(() => _checking = false);
+ if (mounted) {
+ setState(() {
+ _checking = false;
+ _inBrowser = false;
+ });
+ }
}
@override
@@ -108,8 +116,27 @@ class _ProjectGitHubAccessState extends State<ProjectGitHubAccess>
listenable: widget.controller,
builder: (context, _) {
final access = widget.controller.githubAccessOf(widget.projectId);
- if (access == null || access.state == 'unavailable') {
- return const SizedBox.shrink();
+ if (access?.state == 'unavailable') return const SizedBox.shrink();
+ // Read as the dialog opens: said, so the section does not appear from nothing a moment later.
+ if (access == null) {
+ return Column(
+ key: ValueKey('super-project-github-${widget.projectId}'),
+ mainAxisSize: MainAxisSize.min,
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ Text('GitHub access', style: DesktopChrome.control(medium: true)),
+ const SizedBox(height: 4),
+ Text(
+ 'Checking…',
+ key: ValueKey(
+ 'super-project-github-text-${widget.projectId}',
+ ),
+ style: DesktopChrome.text().copyWith(
+ color: DesktopChrome.muted,
+ ),
+ ),
+ ],
+ );
}
final repository = access.repository ?? 'its repository';
final text = switch (access.state) {
@@ -126,8 +153,12 @@ class _ProjectGitHubAccessState extends State<ProjectGitHubAccess>
'repositories yet.',
'not-github' => "Teammates' agents can't work on this project: its repository isn't on GitHub.",
'no-repository' => 'This project has no repository address yet. Its owner or Lead sets it.',
+ 'unread' => "Couldn't check GitHub access just now.",
_ => "Couldn't reach GitHub to check $repository.",
};
+ final waiting =
+ _inBrowser &&
+ (access.state == 'not-installed' || access.state == 'not-approved');
final install = access.installUrl;
final approve = access.state == 'not-approved' && access.canApprove;
return Column(
@@ -142,6 +173,17 @@ class _ProjectGitHubAccessState extends State<ProjectGitHubAccess>
key: ValueKey('super-project-github-text-${widget.projectId}'),
style: DesktopChrome.text(),
),
+ if (waiting)
+ Padding(
+ padding: const EdgeInsets.only(top: 4),
+ child: Text(
+ 'Finish on GitHub in your browser. This updates when you come back.',
+ key: const Key('super-project-github-waiting'),
+ style: DesktopChrome.text().copyWith(
+ color: DesktopChrome.muted,
+ ),
+ ),
+ ),
if (_error != null)
Padding(
padding: const EdgeInsets.only(top: 4),
@@ -155,7 +197,8 @@ class _ProjectGitHubAccessState extends State<ProjectGitHubAccess>
),
if (access.state == 'not-installed' ||
access.state == 'not-approved' ||
- access.state == 'unknown')
+ access.state == 'unknown' ||
+ access.state == 'unread')
Padding(
padding: const EdgeInsets.only(top: 8),
child: Wrap(
@@ -219,7 +262,12 @@ class _ProjectGitHubAccessState extends State<ProjectGitHubAccess>
// The plain link still installs; approving is then a step of its own.
}
await launchUrl(Uri.parse(link), mode: LaunchMode.externalApplication);
- if (mounted) setState(() => _busy = false);
+ if (mounted) {
+ setState(() {
+ _busy = false;
+ _inBrowser = true;
+ });
+ }
}
/// Signs the person in to GitHub through the app, which approves the repository if they can push to it.
@@ -237,6 +285,7 @@ class _ProjectGitHubAccessState extends State<ProjectGitHubAccess>
Uri.parse(links.authorizeUrl),
mode: LaunchMode.externalApplication,
);
+ if (mounted) setState(() => _inBrowser = true);
} on SuperTabFailure catch (failure) {
if (mounted) setState(() => _error = failure.message);
} catch (_) {
@@ -264,15 +313,35 @@ class ProjectGitHubLine extends StatefulWidget {
State<ProjectGitHubLine> createState() => _ProjectGitHubLineState();
}
-class _ProjectGitHubLineState extends State<ProjectGitHubLine> {
+class _ProjectGitHubLineState extends State<ProjectGitHubLine>
+ with WidgetsBindingObserver {
@override
void initState() {
super.initState();
+ WidgetsBinding.instance.addObserver(this);
if (widget.controller.snapshot?.hasTeammates == true) {
widget.controller.readGitHubAccess(widget.project.id);
}
}
+ @override
+ void dispose() {
+ WidgetsBinding.instance.removeObserver(this);
+ super.dispose();
+ }
+
+ // Back from GitHub, where the person installed or approved: the line asks again at once. It kept saying
+ // "Teammates can't push here yet" for up to 5 minutes after an approval (2026-10-28).
+ @override
+ void didChangeAppLifecycleState(AppLifecycleState state) {
+ final c = widget.controller;
+ if (state == AppLifecycleState.resumed &&
+ c.snapshot?.hasTeammates == true &&
+ c.githubAccessOf(widget.project.id)?.problem != null) {
+ c.readGitHubAccess(widget.project.id, refresh: true);
+ }
+ }
+
@override
Widget build(BuildContext context) {
final c = widget.controller;
diff --git a/desktop/test/super_tab_project_github_test.dart b/desktop/test/super_tab_project_github_test.dart
index 2666f8f23..78fc516a9 100644
--- a/desktop/test/super_tab_project_github_test.dart
+++ b/desktop/test/super_tab_project_github_test.dart
@@ -1,5 +1,7 @@
// A Swarm project's GitHub access (docs/plans/2026-10-28-swarm-project-github-access.md): whether teammates' agents can
// push to its repository, shown where the project is, with how to let them.
+import 'dart:async';
+
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:flutter_test/flutter_test.dart';
@@ -15,6 +17,9 @@ void main() {
late Map<String, dynamic> answer;
late List<String> launched;
var refuseApprove = false;
+ // A status read held until completed, or failing.
+ Completer<void>? hold;
+ Object? failure;
SuperTabController controllerFor({bool teammates = true}) {
if (teammates) {
@@ -44,6 +49,8 @@ void main() {
}
if (path.contains('/github')) {
asked.add(path);
+ await hold?.future;
+ if (failure != null) throw failure!;
return answer;
}
return server.request(method, path, body: body);
@@ -65,6 +72,8 @@ void main() {
);
launched = [];
refuseApprove = false;
+ hold = null;
+ failure = null;
TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
.setMockMethodCallHandler(
const MethodChannel('plugins.flutter.io/url_launcher'),
@@ -250,4 +259,78 @@ void main() {
expect(find.byKey(const Key('super-project-github-approve')), findsNothing);
c.dispose();
});
+
+ // 2026-10-28, a new Swarm: Project details showed no GitHub access at all while it was read, and after an approval
+ // the sidebar kept saying teammates could not push for 5 minutes.
+ testWidgets('says it is checking while it reads, and that it could not when it fails, asking again soon', (
+ tester,
+ ) async {
+ hold = Completer<void>();
+ final c = controllerFor();
+ await c.refresh();
+ final project = c.snapshot!.projects.first;
+ await tester.pumpWidget(
+ MaterialApp(
+ home: Scaffold(
+ body: ProjectGitHubAccess(controller: c, projectId: project.id),
+ ),
+ ),
+ );
+ await tester.pump();
+ expect(find.text('Checking…'), findsOneWidget);
+ failure = const SuperTabFailure('NETWORK', 'offline');
+ hold!.complete();
+ await tester.pumpAndSettle();
+ expect(find.text("Couldn't check GitHub access just now."), findsOneWidget);
+ expect(find.byKey(const Key('super-project-github-check')), findsOneWidget);
+ // Asked again after 30 seconds, not 5 minutes.
+ final before = asked.length;
+ await c.readGitHubAccess(project.id);
+ expect(asked, hasLength(before));
+ failure = null;
+ await tester.tap(find.byKey(const Key('super-project-github-check')));
+ await tester.pumpAndSettle();
+ expect(find.textContaining('Install Harness on GitHub there'), findsOneWidget);
+ c.dispose();
+ });
+
+ testWidgets('shows nothing on a server without the route', (tester) async {
+ failure = const SuperTabFailure('NOT_FOUND', 'Not found', statusCode: 404);
+ final c = await mount(
+ tester,
+ (c, p) => ProjectGitHubAccess(controller: c, projectId: p.id),
+ );
+ expect(find.text('GitHub access'), findsNothing);
+ expect(find.text('Checking…'), findsNothing);
+ c.dispose();
+ });
+
+ testWidgets('says to finish in the browser, and the sidebar asks again when the person is back', (
+ tester,
+ ) async {
+ answer = {'state': 'not-approved', 'repository': 'acme/app', 'canApprove': true};
+ final c = await mount(
+ tester,
+ (c, p) => Column(
+ children: [
+ ProjectGitHubLine(controller: c, project: p),
+ ProjectGitHubAccess(controller: c, projectId: p.id),
+ ],
+ ),
+ );
+ expect(find.byKey(const Key('super-project-github-waiting')), findsNothing);
+ await tester.tap(find.byKey(const Key('super-project-github-approve')));
+ await tester.pumpAndSettle();
+ expect(find.byKey(const Key('super-project-github-waiting')), findsOneWidget);
+ // Approved in the browser; back in the app, both ask again at once.
+ answer = {'state': 'covered', 'repository': 'acme/app'};
+ tester.binding.handleAppLifecycleStateChanged(AppLifecycleState.inactive);
+ tester.binding.handleAppLifecycleStateChanged(AppLifecycleState.resumed);
+ await tester.pumpAndSettle();
+ expect(asked.last, endsWith('/github?refresh=1'));
+ expect(find.text("Teammates can't push here yet"), findsNothing);
+ expect(find.textContaining('GitHub ✓'), findsOneWidget);
+ expect(find.byKey(const Key('super-project-github-waiting')), findsNothing);
+ c.dispose();
+ });
}