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.

Merge batch 11-05 i2205: #3167 #3202 #3201 (#3206)

0xken158255ad7ecea7
diff --git a/backend/integration/superTabGithub.test.ts b/backend/integration/superTabGithub.test.ts
index 52daccdcb..e43fc1386 100644
--- a/backend/integration/superTabGithub.test.ts
+++ b/backend/integration/superTabGithub.test.ts
@@ -14,6 +14,7 @@ import type { Approvals, GitHubSignIn } from '../src/github/approvals.js'
import { errorHandler } from '../src/middlewares/errorHandler.js'
import type { Command } from '../src/superTabs/commands.js'
import { GitHubTokens, MemoryTokenCache } from '../src/github/tokens.js'
+import { OWNER_CHECKS_PER_MINUTE, resetOwnerChecks } from '../src/github/repositoryCreate.js'
import { fakeApp, fakeGitHub, throwawayKey } from '../src/github/fakeGitHub.js'
import { poolRows } from './hostRows.test-support.js'
import { logger } from '../src/utils/logger.js'
@@ -804,3 +805,222 @@ describe('the GitHub revision', () => {
expect(env.approved).toHaveLength(1)
})
})
+
+describe('a new repository from New Project (task #1788)', () => {
+ type Script = Record<string, { status: number; body?: Record<string, unknown> }>
+ const made: Script = {
+ 'GET /user': { status: 200, body: { login: 'olive' } },
+ 'POST /orgs/acme/repos': { status: 201, body: { id: 555, full_name: 'acme/notes', html_url: 'https://github.com/acme/notes' } },
+ }
+ /** The app's sign-in, answering the person's calls from [script]; a code 'bad' is one GitHub refuses, and each code works
+ * once, as GitHub's do. [onCreate] runs while the create call is in flight. */
+ const signInWith = (script: () => Script, onCreate?: () => Promise<void>) => {
+ const used = new Set<string>()
+ return {
+ authorizeUrl: (state: string) => `https://github.test/login/oauth/authorize?state=${state}`,
+ permission: async () => ({ login: 'olive', push: true }),
+ withUserToken: async (code: string, use: (call: (m: string, p: string, b?: unknown) => Promise<{ status: number; body: Record<string, unknown> }>) => Promise<unknown>) => {
+ if (code === 'bad' || used.has(code)) return null
+ used.add(code)
+ return use(async (method, path) => {
+ if (method === 'POST' && onCreate) await onCreate()
+ const answer = script()[`${method} ${path}`] ?? { status: 404, body: { message: 'Not Found' } }
+ return { status: answer.status, body: answer.body ?? {} }
+ })
+ },
+ } as unknown as GitHubSignIn
+ }
+ async function project(env: Env) {
+ const tab = (await env.store.create(owner, randomUUID(), 'Pilot')).id
+ const projectId = String((await env.run(tab, { type: 'project.create', name: 'Notes', visibility: 'public', brief: '' } as Command)).result.projectId)
+ return { tab, projectId }
+ }
+ const ready = (env: Env, grants: Record<string, 'read' | 'write'> = { repository_creation: 'write' }) => {
+ env.github.owners.set('acme', 91)
+ env.github.grants.set(91, grants)
+ }
+ const askCreate = (env: Env, tab: string, projectId: string, payload: Record<string, unknown> = { owner: 'acme', name: 'notes', private: true }, user = owner) =>
+ env.app.inject({ method: 'POST', url: `/api/super-tabs/${tab}/projects/${projectId}/github/repository`, headers: { authorization: `Bearer ${user.sub}` }, payload })
+ const callback = (env: Env, query: string) => env.app.inject({ method: 'GET', url: `/api/github/callback?${query}` })
+ const stateOf = (authorizeUrl: string) => encodeURIComponent(new URL(authorizeUrl).searchParams.get('state')!)
+ const creation = async (env: Env, tab: string, projectId: string) =>
+ (await env.store.readLoad(owner, tab)).state.projects?.find(p => p.id === projectId)?.repositoryCreation
+
+ it('the owner creates a new repository for their new project, approved for it and ready for its PM', async () => {
+ const env = await fresh({ approveAll: false, signIn: signInWith(() => made) })
+ ready(env)
+ env.github.installed.set('acme/notes', 91)
+ const { tab, projectId } = await project(env)
+ const asked = await askCreate(env, tab, projectId)
+ expect(asked.statusCode, asked.body).toBe(200)
+ const { authorizeUrl, at } = asked.json().data as { authorizeUrl: string; at: number }
+ expect(await creation(env, tab, projectId)).toEqual({ owner: 'acme', name: 'notes', private: true, by: owner.sub, at, state: 'waiting' })
+ // Ids, the owner and the name only go to GitHub in the address, never the project's name (privacy review of #1980).
+ expect(decodeURIComponent(authorizeUrl)).not.toContain('Notes')
+ const done = await callback(env, `code=c&state=${stateOf(authorizeUrl)}`)
+ expect(done.statusCode).toBe(200)
+ expect(done.body).toContain('acme/notes is ready')
+ expect(await creation(env, tab, projectId)).toEqual({ owner: 'acme', name: 'notes', private: true, by: owner.sub, at, state: 'created',
+ repositoryUrl: 'https://github.com/acme/notes', reachable: true })
+ expect(env.approved).toEqual([expect.objectContaining({ tabId: tab, projectId, repository: 'acme/notes', scope: 'project', login: 'olive' })])
+ // The same link again changes nothing and creates nothing more.
+ const again = await callback(env, `code=c2&state=${stateOf(authorizeUrl)}`)
+ expect(again.body).toContain('This link has expired')
+ expect(env.approved).toHaveLength(1)
+ })
+
+ it('another member, a bad name or owner, or a project with a repository can\'t start it', async () => {
+ const env = await fresh({ approveAll: false, signIn: signInWith(() => made) })
+ ready(env)
+ const { tab, projectId } = await project(env)
+ await invited(env, tab, host)
+ expect((await askCreate(env, tab, projectId, undefined, host)).json()).toMatchObject({ error: { code: 'PROJECT_OWNER_REQUIRED' } })
+ const named = await askCreate(env, tab, projectId, { owner: 'acme', name: 'a b', private: true })
+ expect(named.statusCode).toBe(400)
+ expect(named.json()).toMatchObject({ error: { code: 'REPOSITORY_NAME', message: 'Use letters, numbers, - _ or . (up to 100).' } })
+ expect((await askCreate(env, tab, projectId, { owner: '-acme', name: 'notes', private: true })).statusCode).toBe(400)
+ const { tab: shared } = await working(env)
+ expect((await askCreate(env, shared, 'lead')).json()).toMatchObject({ error: { code: 'PROJECT_REPOSITORY_SET' } })
+ expect(await creation(env, tab, projectId)).toBeUndefined()
+ })
+
+ it('each organization state is said before sign-in', async () => {
+ const env = await fresh({ approveAll: false, signIn: signInWith(() => made) })
+ const { tab, projectId } = await project(env)
+ const owners = (owner_ = 'acme', user = owner) => env.app.inject({ method: 'GET', url: `/api/super-tabs/${tab}/github/owners/${owner_}`, headers: { authorization: `Bearer ${user.sub}` } })
+ expect((await owners()).json().data).toEqual({ state: 'not-installed', installUrl: 'https://github.com/apps/harness-fixture/installations/new' })
+ const notInstalled = await askCreate(env, tab, projectId)
+ expect(notInstalled.statusCode).toBe(409)
+ expect(notInstalled.json()).toMatchObject({ error: { code: 'GITHUB_APP_NOT_INSTALLED' } })
+ env.github.owners.set('acme', 91)
+ env.github.grants.set(91, { contents: 'write' })
+ env.github.owners.set('beta', 92)
+ env.github.grants.set(92, { repository_creation: 'write' })
+ expect((await owners('beta')).json().data).toEqual({ state: 'ready' })
+ expect((await askCreate(env, tab, projectId, { owner: 'beta', name: 'notes', private: true })).statusCode).toBe(200)
+ expect((await owners('-bad')).statusCode).toBe(400)
+ // Someone outside the Swarm reads nothing.
+ expect((await owners('beta', host)).statusCode).toBeGreaterThanOrEqual(403)
+ const off = await fresh({ approveAll: false, signIn: null })
+ const other = await project(off)
+ const offOwners = await off.app.inject({ method: 'GET', url: `/api/super-tabs/${other.tab}/github/owners/acme`, headers: { authorization: `Bearer ${owner.sub}` } })
+ expect(offOwners.json().data).toEqual({ state: 'not-configured' })
+ expect((await askCreate(off, other.tab, other.projectId)).statusCode).toBe(503)
+ })
+
+ it('an organization that has not accepted the permission is said before sign-in', async () => {
+ const env = await fresh({ approveAll: false, signIn: signInWith(() => made) })
+ ready(env, { contents: 'write' })
+ const { tab, projectId } = await project(env)
+ const owners = await env.app.inject({ method: 'GET', url: `/api/super-tabs/${tab}/github/owners/acme`, headers: { authorization: `Bearer ${owner.sub}` } })
+ expect(owners.json().data).toEqual({ state: 'not-accepted' })
+ expect((await askCreate(env, tab, projectId)).json()).toMatchObject({ error: { code: 'GITHUB_APP_PERMISSIONS' } })
+ })
+
+ it('cancel, a taken name, GitHub\'s refusal and a refused code come back to the app', async () => {
+ let script: Script = made
+ const env = await fresh({ approveAll: false, signIn: signInWith(() => script) })
+ ready(env)
+ const { tab, projectId } = await project(env)
+ const start = async () => (await askCreate(env, tab, projectId)).json().data as { authorizeUrl: string; at: number }
+
+ let asked = await start()
+ const cancelled = await callback(env, `error=access_denied&state=${stateOf(asked.authorizeUrl)}`)
+ expect(cancelled.body).toContain('Nothing was created')
+ expect(await creation(env, tab, projectId)).toMatchObject({ state: 'cancelled', at: asked.at })
+
+ asked = await start()
+ script = { ...made, 'POST /orgs/acme/repos': { status: 422, body: { message: 'Repository creation failed.', errors: [{ message: 'name already exists on this account' }] } } }
+ expect((await callback(env, `code=c3&state=${stateOf(asked.authorizeUrl)}`)).body).toContain('acme/notes already exists')
+ expect(await creation(env, tab, projectId)).toMatchObject({ state: 'taken' })
+
+ asked = await start()
+ script = { ...made, 'POST /orgs/acme/repos': { status: 403, body: { message: 'Members cannot create repositories.' } } }
+ expect((await callback(env, `code=c4&state=${stateOf(asked.authorizeUrl)}`)).body).toContain('Members cannot create repositories.')
+ expect(await creation(env, tab, projectId)).toMatchObject({ state: 'refused', reason: 'Members cannot create repositories.' })
+
+ asked = await start()
+ expect((await callback(env, `code=bad&state=${stateOf(asked.authorizeUrl)}`)).body).toContain('Nothing was created')
+ expect(await creation(env, tab, projectId)).toMatchObject({ state: 'failed' })
+ expect(env.approved).toEqual([])
+ })
+
+ it('an older link changes nothing once a newer ask replaced it, and creates nothing', async () => {
+ let creates = 0
+ const env = await fresh({ approveAll: false, signIn: signInWith(() => { creates++; return made }) })
+ ready(env)
+ const { tab, projectId } = await project(env)
+ const first = (await askCreate(env, tab, projectId)).json().data as { authorizeUrl: string; at: number }
+ await new Promise(resolve => setTimeout(resolve, 5))
+ const second = (await askCreate(env, tab, projectId, { owner: 'acme', name: 'notes2', private: true })).json().data as { authorizeUrl: string; at: number }
+ expect(second.at).toBeGreaterThan(first.at)
+ const late = await callback(env, `code=c&state=${stateOf(first.authorizeUrl)}`)
+ expect(late.body).toContain('This link has expired')
+ expect(creates).toBe(0)
+ expect(await creation(env, tab, projectId)).toMatchObject({ name: 'notes2', state: 'waiting' })
+ })
+
+ it('a replayed callback while the first is still creating changes nothing (security review 2 of #3201)', async () => {
+ let release!: () => void
+ const held = new Promise<void>(resolve => { release = resolve })
+ let entered!: () => void
+ const inside = new Promise<void>(resolve => { entered = resolve })
+ const env = await fresh({ approveAll: false, signIn: signInWith(() => made, async () => { entered(); await held }) })
+ ready(env)
+ env.github.installed.set('acme/notes', 91)
+ const { tab, projectId } = await project(env)
+ const asked = (await askCreate(env, tab, projectId)).json().data as { authorizeUrl: string; at: number }
+ const first = callback(env, `code=c&state=${stateOf(asked.authorizeUrl)}`)
+ await inside
+ expect(await creation(env, tab, projectId)).toMatchObject({ state: 'creating' })
+ const replay = await callback(env, `code=c&state=${stateOf(asked.authorizeUrl)}`)
+ expect(replay.body).toContain('This link has expired')
+ release()
+ expect((await first).body).toContain('acme/notes is ready')
+ expect(await creation(env, tab, projectId)).toMatchObject({ state: 'created', repositoryUrl: 'https://github.com/acme/notes' })
+ expect(env.approved).toHaveLength(1)
+ })
+
+ it('allows nothing for a project deleted while GitHub was creating its repository (security review 1 of #3201)', async () => {
+ let deleteNow: () => Promise<void> = async () => {}
+ const env = await fresh({ approveAll: false, signIn: signInWith(() => made, () => deleteNow()) })
+ ready(env)
+ const { tab, projectId } = await project(env)
+ const asked = (await askCreate(env, tab, projectId)).json().data as { authorizeUrl: string }
+ deleteNow = async () => { await env.run(tab, { type: 'project.delete', projectId } as Command) }
+ const done = await callback(env, `code=c&state=${stateOf(asked.authorizeUrl)}`)
+ expect(done.body).toContain('The project was deleted meanwhile')
+ expect(env.approved).toEqual([])
+ })
+
+ it('asks GitHub nothing for someone who may not create, and limits organization checks per person (security reviews of #3201)', async () => {
+ const env = await fresh({ approveAll: false, signIn: signInWith(() => made) })
+ ready(env)
+ const { tab, projectId } = await project(env)
+ await invited(env, tab, host)
+ const lookups = () => env.github.calls.filter(c => c.path.startsWith('/orgs/')).length
+ expect((await askCreate(env, tab, projectId, undefined, host)).statusCode).toBe(403)
+ expect(lookups()).toBe(0)
+ resetOwnerChecks()
+ onTestFinished(() => { resetOwnerChecks() })
+ const owners = (name: string) => env.app.inject({ method: 'GET', url: `/api/super-tabs/${tab}/github/owners/${name}`, headers: { authorization: `Bearer ${owner.sub}` } })
+ for (let i = 0; i < OWNER_CHECKS_PER_MINUTE; i++) expect((await owners(`org${i}`)).statusCode).toBe(200)
+ const before = lookups()
+ const limited = await owners('one-more')
+ expect(limited.statusCode).toBe(429)
+ expect(limited.json().error.code).toBe('RATE_LIMITED')
+ expect((await askCreate(env, tab, projectId, { owner: 'another', name: 'notes', private: true })).statusCode).toBe(429)
+ expect(lookups()).toBe(before)
+ })
+
+ it('a project deleted while its person was in GitHub is said, and nothing is created', async () => {
+ const env = await fresh({ approveAll: false, signIn: signInWith(() => made) })
+ ready(env)
+ const { tab, projectId } = await project(env)
+ const asked = (await askCreate(env, tab, projectId)).json().data as { authorizeUrl: string }
+ await env.run(tab, { type: 'project.delete', projectId } as Command)
+ const late = await callback(env, `code=c&state=${stateOf(asked.authorizeUrl)}`)
+ expect(late.body).toContain('The project was deleted meanwhile')
+ expect(env.approved).toEqual([])
+ })
+})
diff --git a/backend/integration/superTabNotAvailable.test.ts b/backend/integration/superTabNotAvailable.test.ts
index 7251352d2..e810f75f8 100644
--- a/backend/integration/superTabNotAvailable.test.ts
+++ b/backend/integration/superTabNotAvailable.test.ts
@@ -126,6 +126,8 @@ function calls(tab: string, chat: string, project: string) {
json('POST', 'POST /api/super-tabs/:tabId/attachments/:attachmentId/voice', `${t}/attachments/${MISSING}/voice?lang=en`, {}),
json('GET', 'GET /api/super-tabs/:tabId/projects/:projectId/github', `${t}/projects/${project}/github`),
json('POST', 'POST /api/super-tabs/:tabId/projects/:projectId/github/approve', `${t}/projects/${project}/github/approve`, { scope: 'project' }),
+ json('GET', 'GET /api/super-tabs/:tabId/github/owners/:owner', `${t}/github/owners/acme`),
+ json('POST', 'POST /api/super-tabs/:tabId/projects/:projectId/github/repository', `${t}/projects/${project}/github/repository`, { owner: 'acme', name: 'notes', private: true }),
json('GET', 'GET /api/super-tabs/:tabId/projects/:projectId/roles/:roleId', `${t}/projects/${project}/roles/${MISSING}`),
json('GET', 'GET /api/super-tabs/:tabId/projects/:projectId/ci-load', `${t}/projects/${project}/ci-load`),
// A made-up agent: an outsider is answered as for any Swarm it cannot reach. Asked of the Lead's project, so a member's
@@ -178,7 +180,7 @@ describe('a Swarm the caller cannot reach, on every person route', () => {
const cases = { missing: await answer(missing[i]!, outsider), refused: await answer(call, outsider), revoked: await answer(call, removed) }
// Approving needs the server's GitHub App, which this server has not: it says so to everyone, before any Swarm is read.
// So does a GitHub token, which needs the same app.
- const expected = /\/github\/approve$|\/github-token$/.test(call.route) ? cases.missing : { status: 404, body: NOT_AVAILABLE_BODY }
+ const expected = /\/github\/approve$|\/github\/repository$|\/github-token$/.test(call.route) ? cases.missing : { status: 404, body: NOT_AVAILABLE_BODY }
for (const [name, got] of Object.entries(cases)) expect.soft(got, `${name}: ${call.url}`).toEqual(expected)
}
})
@@ -192,7 +194,7 @@ describe('a Swarm the caller cannot reach, on every person route', () => {
for (const [chat, project] of [['lead', 'lead'], [buddyChat, 'lead'], [f.privateChat, f.privateProject]] as const) {
for (const [i, call] of calls(f.tab, chat, project).entries()) {
const cases = { owner: await answer(call, owner), member: await answer(call, member), outsider: await answer(call, outsider), missing: await answer(missing[i]!, owner) }
- const expected = /\/github\/approve$|\/github-token$/.test(call.route) ? cases.missing : { status: 404, body: NOT_AVAILABLE_BODY }
+ const expected = /\/github\/approve$|\/github\/repository$|\/github-token$/.test(call.route) ? cases.missing : { status: 404, body: NOT_AVAILABLE_BODY }
for (const [name, got] of Object.entries(cases)) expect.soft(got, `${name}: ${call.url}`).toEqual(expected)
}
}
@@ -209,7 +211,8 @@ describe('a Swarm the caller cannot reach, on every person route', () => {
'GET /api/super-tabs/:tabId/conversations/:conversationId/messages', 'POST /api/super-tabs/:tabId/attachments',
'GET /api/super-tabs/:tabId/projects/:projectId/github', 'GET /api/super-tabs/:tabId/leaderboard']))
// Checked before the chat: a terminal opens for one agent (made up here), and approving needs the server's GitHub App.
- const before = ['POST /api/super-tabs/:tabId/native', 'POST /api/super-tabs/:tabId/projects/:projectId/github/approve']
+ const before = ['POST /api/super-tabs/:tabId/native', 'POST /api/super-tabs/:tabId/projects/:projectId/github/approve',
+ 'POST /api/super-tabs/:tabId/projects/:projectId/github/repository']
for (const call of named) {
const got = await answer(call, member), absent = await answer(missing[hidden.indexOf(call)]!, member)
expect(got, call.url).toEqual(absent)
diff --git a/backend/src/github/app.test.ts b/backend/src/github/app.test.ts
index 92281c3f8..dfbb800b8 100644
--- a/backend/src/github/app.test.ts
+++ b/backend/src/github/app.test.ts
@@ -631,3 +631,41 @@ describe('watching a pull request', () => {
expect(await app.watchPullRequest(repo, 12, token)).toBeNull()
})
})
+
+describe('what installation tokens may never carry (task #1788)', () => {
+ it('installation tokens never ask for administration or repository creation', async () => {
+ const app = await import('./app.js')
+ const sets = Object.entries(app).filter(([name]) => name.endsWith('_PERMISSIONS')) as Array<[string, Record<string, string>]>
+ expect(sets.map(([name]) => name)).toEqual(expect.arrayContaining(['TOKEN_PERMISSIONS', 'GRANTED_TOKEN_PERMISSIONS', 'PREPARE_PERMISSIONS']))
+ for (const [, permissions] of sets) {
+ for (const never of app.NEVER_ON_INSTALLATION_TOKENS) expect(Object.keys(permissions)).not.toContain(never)
+ }
+ const { github, app: gh } = setup()
+ github.installed.set('acme/app', 91)
+ for (const never of app.NEVER_ON_INSTALLATION_TOKENS) {
+ await expect(gh.createToken(91, repo, { [never]: 'write', metadata: 'read' })).rejects.toMatchObject({ code: 'GITHUB_APP_PERMISSIONS_FORBIDDEN' })
+ }
+ expect(github.calls.some(c => c.path.endsWith('/access_tokens'))).toBe(false)
+ })
+})
+
+describe('whether an organization lets Harness create repositories (task #1788)', () => {
+ it('says whether an organization lets Harness create repositories', async () => {
+ const { app, github, time } = setup()
+ expect(await app.ownerReadiness('acme')).toEqual({ state: 'not-installed', installUrl: 'https://github.com/apps/harness-fixture/installations/new' })
+ expect(github.calls.map(c => c.path)).toEqual(['/orgs/acme/installation'])
+ github.owners.set('acme', 91)
+ time.advance(60_001)
+ github.grants.set(91, { contents: 'write', metadata: 'read' })
+ expect(await app.ownerReadiness('acme')).toEqual({ state: 'not-accepted' })
+ time.advance(10 * 60_000 + 1)
+ github.grants.set(91, { contents: 'write', metadata: 'read', repository_creation: 'write' })
+ expect(await app.ownerReadiness('acme')).toEqual({ state: 'ready', installation: 91, canAdd: false })
+ time.advance(10 * 60_000 + 1)
+ github.grants.set(91, { repository_creation: 'write', installation_repositories: 'write' })
+ expect(await app.ownerReadiness('Acme')).toEqual({ state: 'ready', installation: 91, canAdd: true })
+ const asked = github.calls.length
+ expect(await app.ownerReadiness('ACME')).toEqual({ state: 'ready', installation: 91, canAdd: true })
+ expect(github.calls).toHaveLength(asked)
+ })
+})
diff --git a/backend/src/github/app.ts b/backend/src/github/app.ts
index 9588588f4..6d90ee117 100644
--- a/backend/src/github/app.ts
+++ b/backend/src/github/app.ts
@@ -22,6 +22,10 @@ export const TOKEN_PERMISSIONS = { contents: 'write', pull_requests: 'write', ch
* in CI with the repository's secrets, and Team-written branches are among the pushers.
*/
export const GRANTED_TOKEN_PERMISSIONS = { workflows: 'write', issues: 'write' } as const
+/** What no installation token may ever ask for (task #1788): a new repository is created with the person's own sign-in
+ * token only (github/repositoryCreate.ts), so a token minted from the app's key can never create, delete or transfer a
+ * repository, nor widen which repositories the installation covers. */
+export const NEVER_ON_INSTALLATION_TOKENS = ['administration', 'repository_creation', 'installation_repositories'] as const
/** What preparing an agent's folder may do before the agent has a task: clone and fetch the repository, nothing more. */
export const PREPARE_PERMISSIONS = { contents: 'read', metadata: 'read' } as const
/** What the Swarm's tidying reads before it archives a finished group: whether its pull requests are merged or closed. */
@@ -49,6 +53,11 @@ export class GitHubAppError extends Error {
}
}
+/** Whether an organization lets Harness create a repository there (task #1788): the app is installed on it and its owner
+ * accepted Repository creation; [canAdd] when it also accepted installation repository access, so a new repository the
+ * installation does not cover yet can be added to it. */
+export type OwnerReadiness = { state: 'ready'; installation: number; canAdd: boolean } | { state: 'not-installed'; installUrl: string | null } | { state: 'not-accepted' }
+
export interface GitHubAppConfig { appId: string; privateKey: KeyObject; slug: string | null }
/** The app's private key as GitHub hands it out (a PEM file), with its line breaks written as `\n`, or base64 of it. The
@@ -150,6 +159,8 @@ export class GitHubApp {
private readonly pushOrigins = new Map<string, { origin: PushOrigin; until: number }>()
/** Each repository's CI reads in the last hour, and its last load read, for [CI_READS_PER_HOUR]. */
private readonly ciReads = new Map<string, { at: number[]; last: { load: CiLoad | null; at: number } | null }>()
+ /** The app's installation on each organization, by its login in lower case, for [ownerReadiness]; null when not installed. */
+ private readonly orgInstallations = new Map<string, { id: number | null; until: number }>()
/** When each repository's "not installed" was last forgotten on request ([forget]). */
private readonly forgotten = new Map<string, number>()
/** The watch's last answer and its ETag, by path ([watchPullRequest]). */
@@ -322,6 +333,28 @@ export class GitHubApp {
return null
}
+ /** Whether [owner], an organization, lets Harness create a repository there (task #1788). Its installation is remembered
+ * ten minutes (a missing one a minute), and what it granted as for agents' tokens ([granted]). A personal account reads
+ * as not installed: v1 creates in organizations only. */
+ async ownerReadiness(owner: string): Promise<OwnerReadiness> {
+ const key = owner.toLowerCase()
+ let known = this.orgInstallations.get(key)
+ if (!known || known.until <= this.now()) {
+ const answer = await this.call('GET', `/orgs/${encodeURIComponent(owner)}/installation`, `Bearer ${this.jwt()}`)
+ if (answer.status === 401) throw this.misconfigured()
+ const id = (answer.body as Record<string, unknown>).id
+ if (answer.status === 200 && typeof id === 'number') known = { id, until: this.now() + INSTALLATION_TTL_MS }
+ else if (answer.status === 404) known = { id: null, until: this.now() + NOT_INSTALLED_TTL_MS }
+ else throw new GitHubAppError('GITHUB_UNAVAILABLE', `GitHub could not look up the app on ${owner}.`, 502)
+ if (this.orgInstallations.size >= 1000) this.orgInstallations.delete(this.orgInstallations.keys().next().value!)
+ this.orgInstallations.set(key, known)
+ }
+ if (known.id === null) return { state: 'not-installed', installUrl: this.installUrl() }
+ const granted = await this.granted(known.id)
+ if (granted?.repository_creation !== 'write') return { state: 'not-accepted' }
+ return { state: 'ready', installation: known.id, canAdd: granted.installation_repositories === 'write' }
+ }
+
/** Forgets that the app was not on [repository] (and its rename), so the next lookup asks GitHub: a person just
* installed it. At most once every REFRESH_MS per repository, so a refresh cannot become a stream of lookups. */
forget(repository: GitHubRepository): void {
@@ -392,6 +425,8 @@ export class GitHubApp {
}
private async mint(installationId: number, repository: GitHubRepository, permissions: TokenPermissions): Promise<{ token: string; expiresAt: string }> {
+ const forbidden = Object.keys(permissions).filter(name => (NEVER_ON_INSTALLATION_TOKENS as readonly string[]).includes(name))
+ if (forbidden.length) throw new GitHubAppError('GITHUB_APP_PERMISSIONS_FORBIDDEN', `An installation token never asks for ${forbidden.join(', ')}.`, 500)
const answer = await this.call('POST', `/app/installations/${installationId}/access_tokens`, `Bearer ${this.jwt()}`,
{ repositories: [repository.name], permissions })
const body = answer.body as Record<string, unknown>
diff --git a/backend/src/github/approvals.test.ts b/backend/src/github/approvals.test.ts
index 0c60f4d27..632d34fa5 100644
--- a/backend/src/github/approvals.test.ts
+++ b/backend/src/github/approvals.test.ts
@@ -63,6 +63,35 @@ describe('the app\'s GitHub sign-in', () => {
expect(await fake(200, {}, false).signIn.permission('c', repo)).toBeNull()
})
+ it('revokes the person\'s token after use, even when the use throws', async () => {
+ const thrown = fake()
+ await expect(thrown.signIn.withUserToken('c', async () => { throw new Error('x') })).rejects.toThrow('x')
+ expect(thrown.calls.at(-1)).toEqual({ url: 'https://api.gh.test/applications/Iv23client/token', method: 'DELETE' })
+ const used = fake()
+ expect(await used.signIn.withUserToken('c', async call => (await call('GET', '/user')).body.login)).toBe('alice')
+ expect(used.calls.map(c => `${c.method} ${c.url}`)).toEqual(['POST https://gh.test/login/oauth/access_token', 'GET https://api.gh.test/user',
+ 'DELETE https://api.gh.test/applications/Iv23client/token'])
+ const refused = fake(200, {}, false)
+ let ran = false
+ expect(await refused.signIn.withUserToken('c', async () => { ran = true })).toBeNull()
+ expect(ran).toBe(false)
+ expect(refused.calls).toHaveLength(1)
+ })
+
+ it('says when the person\'s token could not be revoked, never the token itself', async () => {
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+ const fetch = vi.fn(async (url: string | URL | Request, init?: RequestInit) => {
+ if (String(url).endsWith('/login/oauth/access_token')) return new Response(JSON.stringify({ access_token: 'ghu_secret_fixture' }), { status: 200 })
+ return new Response(null, { status: init?.method === 'DELETE' ? 500 : 200 })
+ }) as unknown as typeof globalThis.fetch
+ const signIn = new GitHubSignIn({ clientId: 'Iv23client', clientSecret: 'secret', fetch, webUrl: 'https://gh.test', apiUrl: 'https://api.gh.test' })
+ await signIn.withUserToken('c', async () => 1)
+ expect(warn).toHaveBeenCalledTimes(1)
+ expect(String(warn.mock.calls[0])).toContain('not revoked')
+ expect(String(warn.mock.calls[0])).not.toContain('ghu_secret_fixture')
+ warn.mockRestore()
+ })
+
it('is on with both its client id and secret, off with neither, and refuses one alone', () => {
expect(githubSignIn({ GITHUB_APP_CLIENT_ID: '', GITHUB_APP_CLIENT_SECRET: '' })).toBeNull()
expect(githubSignIn({ GITHUB_APP_CLIENT_ID: 'Iv23', GITHUB_APP_CLIENT_SECRET: 's' })).toBeInstanceOf(GitHubSignIn)
diff --git a/backend/src/github/approvals.ts b/backend/src/github/approvals.ts
index e5b052330..a52cb3412 100644
--- a/backend/src/github/approvals.ts
+++ b/backend/src/github/approvals.ts
@@ -57,6 +57,10 @@ export function readState(secret: Buffer, state: string, now: number): ApprovalR
export interface GitHubSignInDeps { clientId: string; clientSecret: string; fetch?: typeof fetch; webUrl?: string; apiUrl?: string }
+/** One GitHub API call with the person's user token: its status and its JSON object (empty when it has none). Throws when
+ * GitHub does not answer. */
+export type UserCall = (method: string, path: string, body?: unknown) => Promise<{ status: number; body: Record<string, unknown> }>
+
/** The Harness GitHub App's sign-in (GitHub's web application flow for an app's user access token). */
export class GitHubSignIn {
private readonly fetch: typeof fetch
@@ -75,6 +79,19 @@ export class GitHubSignIn {
/** What GitHub says [code]'s person may do on [repository]: their login, and whether they can push. The person's token
* is revoked before this answers, whatever it found. */
async permission(code: string, repository: GitHubRepository): Promise<{ login: string; push: boolean } | null> {
+ return this.withUserToken(code, async call => {
+ const login = (await call('GET', '/user')).body.login
+ if (typeof login !== 'string') return null
+ // A renamed repository answers by redirect, which fetch follows; one the person cannot see answers 404.
+ const repo = await call('GET', `/repos/${repository.owner}/${repository.name}`)
+ const permissions = (repo.body.permissions ?? {}) as Record<string, unknown>
+ return { login, push: repo.status === 200 && (permissions.push === true || permissions.maintain === true || permissions.admin === true) }
+ }).then(seen => seen ?? null)
+ }
+
+ /** Runs [use] with the person's user token from [code], then revokes the token whatever happened (task #1788: creating a
+ * repository is a few calls with it). Null, with nothing run, when GitHub refuses the code. The token never leaves here. */
+ async withUserToken<T>(code: string, use: (call: UserCall) => Promise<T>): Promise<T | null> {
const exchanged = await this.fetch(`${this.webUrl}/login/oauth/access_token`, {
method: 'POST', signal: AbortSignal.timeout(15_000),
headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
@@ -82,22 +99,25 @@ export class GitHubSignIn {
})
const token = ((await exchanged.json().catch(() => ({}))) as { access_token?: unknown }).access_token
if (!exchanged.ok || typeof token !== 'string' || !token) return null
+ const headers = { Accept: 'application/vnd.github+json', Authorization: `Bearer ${token}`, 'X-GitHub-Api-Version': '2022-11-28', 'User-Agent': 'harness-backend' }
+ const call: UserCall = async (method, path, body) => {
+ const answer = await this.fetch(`${this.apiUrl}${path}`, { method, signal: AbortSignal.timeout(15_000),
+ headers: body === undefined ? headers : { ...headers, 'Content-Type': 'application/json' }, ...(body === undefined ? {} : { body: JSON.stringify(body) }) })
+ const parsed = await answer.json().catch(() => ({})) as unknown
+ return { status: answer.status, body: parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed as Record<string, unknown> : {} }
+ }
try {
- const headers = { Accept: 'application/vnd.github+json', Authorization: `Bearer ${token}`, 'X-GitHub-Api-Version': '2022-11-28', 'User-Agent': 'harness-backend' }
- const user = await this.fetch(`${this.apiUrl}/user`, { headers, signal: AbortSignal.timeout(15_000) })
- const login = ((await user.json().catch(() => ({}))) as { login?: unknown }).login
- if (!user.ok || typeof login !== 'string') return null
- // A renamed repository answers by redirect, which fetch follows; one the person cannot see answers 404.
- const repo = await this.fetch(`${this.apiUrl}/repos/${repository.owner}/${repository.name}`, { headers, signal: AbortSignal.timeout(15_000) })
- const permissions = ((await repo.json().catch(() => ({}))) as { permissions?: Record<string, unknown> }).permissions ?? {}
- return { login, push: repo.ok && (permissions.push === true || permissions.maintain === true || permissions.admin === true) }
+ return await use(call)
} finally {
await this.fetch(`${this.apiUrl}/applications/${encodeURIComponent(this.deps.clientId)}/token`, {
method: 'DELETE', signal: AbortSignal.timeout(15_000),
headers: { Accept: 'application/vnd.github+json', Authorization: `Basic ${Buffer.from(`${this.deps.clientId}:${this.deps.clientSecret}`).toString('base64')}`,
'Content-Type': 'application/json' },
body: JSON.stringify({ access_token: token }),
- }).catch(() => undefined)
+ }).then(answer => answer.status, () => 'no answer').then(status => {
+ // Said, never with the token, so a token left live shows (security review 1 of #3201); it ends on its own at its expiry.
+ if (status !== 204) console.warn(`[github] a sign-in's user token was not revoked (${status === 'no answer' ? status : `HTTP ${status}`})`)
+ })
}
}
}
diff --git a/backend/src/github/repositoryCreate.test.ts b/backend/src/github/repositoryCreate.test.ts
new file mode 100644
index 000000000..6e73b04c2
--- /dev/null
+++ b/backend/src/github/repositoryCreate.test.ts
@@ -0,0 +1,110 @@
+import { createHmac, randomBytes } from 'node:crypto'
+import { describe, expect, it } from 'vitest'
+import { readState, signState, STATE_TTL_MS, type ApprovalRequest, type UserCall } from './approvals.js'
+import { createRepository, createStateSecret, readCreateState, repositoryNameProblem, signCreateState, type CreateRequest } from './repositoryCreate.js'
+import { stateSecret } from './approvals.js'
+import { fakeApp, fakeGitHub, throwawayKey } from './fakeGitHub.js'
+
+const key = throwawayKey()
+const AT = Date.parse('2026-11-05T15:00:00Z')
+const request: CreateRequest = { userId: 'olive', autonomousEnv: 'prod', tabId: 'tab', projectId: 'p1', owner: 'acme', name: 'notes', private: true, at: AT }
+
+/** A GitHub that answers the person's calls from [script], by "METHOD path"; every call is kept. */
+function person(script: Record<string, { status: number; body?: Record<string, unknown> } | (() => never)>) {
+ const calls: Array<{ method: string; path: string; body?: unknown }> = []
+ const call: UserCall = async (method, path, body) => {
+ calls.push({ method, path, ...(body === undefined ? {} : { body }) })
+ const answer = script[`${method} ${path}`] ?? { status: 404, body: { message: 'Not Found' } }
+ if (typeof answer === 'function') answer()
+ const { status, body: b } = answer as { status: number; body?: Record<string, unknown> }
+ return { status, body: b ?? {} }
+ }
+ return { call, calls }
+}
+const me = { 'GET /user': { status: 200, body: { login: 'olive' } } }
+const made = { status: 201, body: { id: 555, full_name: 'acme/notes', html_url: 'https://github.com/acme/notes' } }
+function app(options: { covered?: boolean; canAdd?: boolean } = {}) {
+ const github = fakeGitHub({ publicKey: key.publicKey, appId: '424242' })
+ github.owners.set('acme', 91)
+ github.grants.set(91, { repository_creation: 'write', ...(options.canAdd ? { installation_repositories: 'write' as const } : {}) })
+ if (options.covered) github.installed.set('acme/notes', 91)
+ return { github, app: fakeApp(key.privateKey, github) }
+}
+
+describe('a new repository\'s name', () => {
+ it('names follow GitHub\'s rule', () => {
+ for (const ok of ['notes-app', 'a.b_c', 'A', 'x'.repeat(100)]) expect(repositoryNameProblem(ok)).toBeNull()
+ for (const bad of ['', '.', '..', 'a b', 'a/b', 'é', 'x'.repeat(101)]) expect(repositoryNameProblem(bad)).toBe('Use letters, numbers, - _ or . (up to 100).')
+ })
+})
+
+describe('a create sign-in\'s state', () => {
+ it('a create state is not an approval state, nor the reverse', () => {
+ const secret = randomBytes(32)
+ const created = signCreateState(secret, request, AT)
+ expect(readCreateState(secret, created, AT + STATE_TTL_MS - 1)).toEqual(request)
+ expect(readCreateState(secret, created, AT + STATE_TTL_MS + 1)).toBeNull()
+ expect(readCreateState(randomBytes(32), created, AT)).toBeNull()
+ expect(readState(secret, created, AT)).toBeNull()
+ const approval: ApprovalRequest = { userId: 'olive', autonomousEnv: 'prod', tabId: 'tab', projectId: 'p1', repository: 'acme/notes', scope: 'project' }
+ expect(readCreateState(secret, signState(secret, approval, AT), AT)).toBeNull()
+ const sign = (value: unknown) => { const body = Buffer.from(JSON.stringify(value)).toString('base64url'); return `${body}.${createHmac('sha256', secret).update(body).digest('base64url')}` }
+ expect(readCreateState(secret, sign({ ...request, kind: 'create', name: 'a b', exp: AT + 1000 }), AT)).toBeNull()
+ expect(readCreateState(secret, sign({ ...request, kind: 'create', owner: '-bad', exp: AT + 1000 }), AT)).toBeNull()
+ expect(readCreateState(secret, sign({ ...request, kind: 'create', private: 'yes', exp: AT + 1000 }), AT)).toBeNull()
+ expect(readCreateState(secret, `${created.split('.')[0]}.forged`, AT)).toBeNull()
+ })
+})
+
+describe('the key create states are signed with', () => {
+ it('is its own, apart from approvals\' (security review 2 of #3201), and the same each time', () => {
+ const config = { appId: '1', privateKey: key.privateKey, slug: null }
+ expect(createStateSecret(config)).toEqual(createStateSecret(config))
+ expect(createStateSecret(config)).toHaveLength(32)
+ expect(createStateSecret(config).equals(stateSecret(config))).toBe(false)
+ })
+})
+
+describe('creating the repository with the person\'s token', () => {
+ it('creates it private with a first commit, as the person', async () => {
+ const { call, calls } = person({ ...me, 'POST /orgs/acme/repos': made })
+ expect(await createRepository(call, app({ covered: true }).app, request)).toEqual({ state: 'created', repository: 'acme/notes',
+ repositoryUrl: 'https://github.com/acme/notes', login: 'olive', reachable: true })
+ expect(calls[1]).toEqual({ method: 'POST', path: '/orgs/acme/repos', body: { name: 'notes', private: true, auto_init: true } })
+ const open = person({ ...me, 'POST /orgs/acme/repos': made })
+ await createRepository(open.call, app({ covered: true }).app, { ...request, private: false })
+ expect(open.calls[1]!.body).toEqual({ name: 'notes', private: false, auto_init: true })
+ })
+
+ it('adds it to the installation only where that is granted', async () => {
+ const granted = person({ ...me, 'POST /orgs/acme/repos': made, 'PUT /user/installations/91/repositories/555': { status: 204 } })
+ expect(await createRepository(granted.call, app({ canAdd: true }).app, request)).toMatchObject({ state: 'created', reachable: true })
+ expect(granted.calls.map(c => `${c.method} ${c.path}`)).toContain('PUT /user/installations/91/repositories/555')
+ const refusedAdd = person({ ...me, 'POST /orgs/acme/repos': made, 'PUT /user/installations/91/repositories/555': { status: 403 } })
+ expect(await createRepository(refusedAdd.call, app({ canAdd: true }).app, request)).toMatchObject({ state: 'created', reachable: false })
+ const notGranted = person({ ...me, 'POST /orgs/acme/repos': made })
+ expect(await createRepository(notGranted.call, app().app, request)).toMatchObject({ state: 'created', reachable: false })
+ expect(notGranted.calls.some(c => c.method === 'PUT')).toBe(false)
+ })
+
+ it('a name taken by someone else is taken; the same person\'s create since the request is created', async () => {
+ const exists = { status: 422, body: { message: 'Repository creation failed.', errors: [{ resource: 'Repository', field: 'name', message: 'name already exists on this account' }] } }
+ const theirs = (createdAt: number, admin: boolean) => person({ ...me, 'POST /orgs/acme/repos': exists,
+ 'GET /repos/acme/notes': { status: 200, body: { id: 555, full_name: 'acme/notes', created_at: new Date(createdAt).toISOString(), permissions: { admin } } } })
+ expect(await createRepository(theirs(AT + 5_000, true).call, app({ covered: true }).app, request)).toMatchObject({ state: 'created', repository: 'acme/notes' })
+ expect(await createRepository(theirs(AT - 3_600_000, true).call, app({ covered: true }).app, request)).toEqual({ state: 'taken' })
+ expect(await createRepository(theirs(AT + 5_000, false).call, app({ covered: true }).app, request)).toEqual({ state: 'taken' })
+ expect(await createRepository(person({ ...me, 'POST /orgs/acme/repos': exists }).call, app().app, request)).toEqual({ state: 'taken' })
+ })
+
+ it('GitHub\'s refusal is said in its words', async () => {
+ const said = (status: number, message: string) => person({ ...me, 'POST /orgs/acme/repos': { status, body: { message } } }).call
+ expect(await createRepository(said(403, 'Members of this organization cannot create repositories.'), app().app, request))
+ .toEqual({ state: 'refused', reason: 'Members of this organization cannot create repositories.' })
+ expect(await createRepository(said(404, 'Not Found'), app().app, request)).toEqual({ state: 'refused', reason: 'Not Found' })
+ expect((await createRepository(said(422, 'x'.repeat(400)), app().app, request) as { reason: string }).reason).toHaveLength(300)
+ expect(await createRepository(said(502, 'Bad gateway'), app().app, request)).toEqual({ state: 'failed' })
+ expect(await createRepository(person({ ...me, 'POST /orgs/acme/repos': () => { throw new TypeError('fetch failed') } }).call, app().app, request)).toEqual({ state: 'failed' })
+ expect(await createRepository(person({}).call, app().app, request)).toEqual({ state: 'failed' })
+ })
+})
diff --git a/backend/src/github/repositoryCreate.ts b/backend/src/github/repositoryCreate.ts
new file mode 100644
index 000000000..f425df78c
--- /dev/null
+++ b/backend/src/github/repositoryCreate.ts
@@ -0,0 +1,137 @@
+/**
+ * A new repository for a new project, from New Project's "New repository" (task #1788,
+ * docs/plans/2026-11-05-new-repository-design.md).
+ *
+ * It is created with the person's own user token from the app's sign-in, never with an installation token
+ * ([NEVER_ON_INSTALLATION_TOKENS]): GitHub then decides whether they may create repositories in that organization, and its
+ * record names them. The token is used for at most four calls here and revoked by [GitHubSignIn.withUserToken].
+ */
+import { createHmac, hkdfSync, timingSafeEqual } from 'node:crypto'
+import { STATE_TTL_MS, type UserCall } from './approvals.js'
+import type { GitHubApp, GitHubAppConfig } from './app.js'
+import { createRateLimiter } from '../lib/rateLimit.js'
+import { githubRepository } from './repository.js'
+
+/** GitHub's repository name rule, and an organization login's. */
+const NAME = /^[A-Za-z0-9._-]{1,100}$/
+export const GITHUB_OWNER = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/
+/** How long before the request a repository found under the asked name may have been made and still be this create's own
+ * (clock skew between GitHub and the server). */
+const SKEW_MS = 60_000
+const REASON_MAX = 300
+
+/** How many organizations one person may have checked against GitHub in a minute, by New Project's organization row and
+ * its create (security reviews of #3201): each check is a call signed with the app's own key. */
+export const OWNER_CHECKS_PER_MINUTE = 30
+const ownerChecks = createRateLimiter('github-owner-checks', 60_000, OWNER_CHECKS_PER_MINUTE)
+/** Whether [userId] may have one more organization checked now. */
+export const ownerCheckAllowed = (userId: string, now = Date.now()) => ownerChecks.allows(userId, now)
+/** Test seam: forget this process's counts. */
+export const resetOwnerChecks = () => ownerChecks.reset()
+
+/** The key create states are signed with: the app's own private key, under a label of its own, so a create state and an
+ * approval state (approvals.ts stateSecret) never share a key (security review 2 of #3201). */
+export function createStateSecret(config: GitHubAppConfig): Buffer {
+ const der = config.privateKey.export({ type: 'pkcs8', format: 'der' })
+ return Buffer.from(hkdfSync('sha256', der, 'harness-github-create-state', config.appId, 32))
+}
+
+/** What is wrong with [name] as a new repository's name, in the words New Project shows (F1), or null. */
+export function repositoryNameProblem(name: string): string | null {
+ return NAME.test(name) && name !== '.' && name !== '..' ? null : 'Use letters, numbers, - _ or . (up to 100).'
+}
+
+/** Who asked to create which repository, for which project, and when ([at], ms): signed into the sign-in's state. */
+export interface CreateRequest {
+ userId: string
+ autonomousEnv: string
+ tabId: string
+ projectId: string
+ owner: string
+ name: string
+ private: boolean
+ at: number
+}
+
+export type CreateOutcome =
+ | { state: 'created'; repository: string; repositoryUrl: string; login: string; reachable: boolean }
+ | { state: 'taken' }
+ | { state: 'refused'; reason: string }
+ | { state: 'failed' }
+
+/** A create's state, signed as an approval's is (approvals.ts signState) but marked `kind: 'create'`, so neither reads as
+ * the other. */
+export function signCreateState(secret: Buffer, request: CreateRequest, now: number): string {
+ const body = Buffer.from(JSON.stringify({ kind: 'create', ...request, exp: now + STATE_TTL_MS })).toString('base64url')
+ return `${body}.${createHmac('sha256', secret).update(body).digest('base64url')}`
+}
+
+/** The create a state was signed for, or null when it is not a create's, was not signed here, was changed, or is too old. */
+export function readCreateState(secret: Buffer, state: string, now: number): CreateRequest | null {
+ const [body, signature, extra] = state.split('.')
+ if (!body || !signature || extra !== undefined) return null
+ const expected = createHmac('sha256', secret).update(body).digest()
+ const given = Buffer.from(signature, 'base64url')
+ if (given.length !== expected.length || !timingSafeEqual(given, expected)) return null
+ try {
+ const v = JSON.parse(Buffer.from(body, 'base64url').toString()) as Record<string, unknown>
+ if (v.kind !== 'create' || typeof v.exp !== 'number' || v.exp < now || typeof v.private !== 'boolean' || typeof v.at !== 'number') return null
+ for (const key of ['userId', 'autonomousEnv', 'tabId', 'projectId', 'owner', 'name'] as const) if (typeof v[key] !== 'string' || !v[key]) return null
+ if (!GITHUB_OWNER.test(v.owner as string) || repositoryNameProblem(v.name as string)) return null
+ return { userId: v.userId as string, autonomousEnv: v.autonomousEnv as string, tabId: v.tabId as string, projectId: v.projectId as string,
+ owner: v.owner as string, name: v.name as string, private: v.private, at: v.at }
+ } catch { return null }
+}
+
+const reason = (body: Record<string, unknown>) => {
+ const errors = Array.isArray(body.errors) ? body.errors.map(e => (e as { message?: unknown })?.message).filter((m): m is string => typeof m === 'string') : []
+ const message = typeof body.message === 'string' ? body.message : ''
+ return ([message, ...errors].filter(Boolean).join(': ') || 'GitHub gave no reason.').slice(0, REASON_MAX)
+}
+
+/**
+ * Creates [request]'s repository with the person's token ([call]): private unless they chose otherwise, with a first
+ * commit (a repository with none cannot be cloned into a worktree). A name already taken by a repository this person made
+ * since the request is this create's own, whose answer was lost (F10). Then checks the app's installation covers it, and
+ * adds it where the installation granted that (Option B leaves it ungranted: GitHub gives the app access to what it
+ * creates); otherwise says it is not reachable (F7).
+ */
+export async function createRepository(call: UserCall, app: GitHubApp, request: CreateRequest): Promise<CreateOutcome> {
+ let created: Record<string, unknown>
+ let login: string
+ try {
+ const user = await call('GET', '/user')
+ if (user.status !== 200 || typeof user.body.login !== 'string') return { state: 'failed' }
+ login = user.body.login
+ const answer = await call('POST', `/orgs/${request.owner}/repos`, { name: request.name, private: request.private, auto_init: true })
+ if (answer.status === 201) created = answer.body
+ else if (answer.status === 422 && /already exists/i.test(reason(answer.body))) {
+ const found = await call('GET', `/repos/${request.owner}/${request.name}`)
+ const madeAt = Date.parse(String(found.body.created_at ?? ''))
+ const admin = (found.body.permissions as Record<string, unknown> | undefined)?.admin === true
+ if (found.status !== 200 || !admin || !(madeAt >= request.at - SKEW_MS)) return { state: 'taken' }
+ created = found.body
+ } else if ([401, 403, 404, 422].includes(answer.status)) return { state: 'refused', reason: reason(answer.body) }
+ else return { state: 'failed' }
+ } catch {
+ return { state: 'failed' }
+ }
+ const fullName = typeof created.full_name === 'string' ? created.full_name : `${request.owner}/${request.name}`
+ const repository = githubRepository(`https://github.com/${fullName}`)
+ if (!repository) return { state: 'failed' }
+ const result = { state: 'created' as const, repository: repository.fullName, repositoryUrl: `https://github.com/${repository.fullName}`, login }
+ const covered = await app.installation(repository).catch(() => null)
+ if (covered !== null) return { ...result, reachable: true }
+ try {
+ const readiness = await app.ownerReadiness(request.owner)
+ if (readiness.state !== 'ready' || !readiness.canAdd || typeof created.id !== 'number') return { ...result, reachable: false }
+ const added = await call('PUT', `/user/installations/${readiness.installation}/repositories/${created.id}`)
+ if (added.status === 204 || added.status === 304) {
+ app.forget(repository)
+ return { ...result, reachable: true }
+ }
+ } catch {
+ // The repository is made either way: what could not be checked reads as not reachable (F7), never as a failure.
+ }
+ return { ...result, reachable: false }
+}
diff --git a/backend/src/routes/superTabs.ts b/backend/src/routes/superTabs.ts
index b3c0e4d5b..dccc184c5 100644
--- a/backend/src/routes/superTabs.ts
+++ b/backend/src/routes/superTabs.ts
@@ -29,6 +29,7 @@ import { githubSignIn, PrismaApprovals, readState, signState, stateSecret, type
import type { GitHubRepository } from '../github/repository.js'
import { githubRepository } from '../github/repository.js'
import { attribution } from '../github/attribution.js'
+import { createRepository, createStateSecret, GITHUB_OWNER, ownerCheckAllowed, readCreateState, repositoryNameProblem, signCreateState } from '../github/repositoryCreate.js'
import { githubTokensFromEnv, type GitHubTokens } from '../github/tokens.js'
import { logger } from '../utils/logger.js'
import { SwarmReads } from '../superTabs/read/service.js'
@@ -140,6 +141,9 @@ const projectParams = tabParams.extend({ projectId: id })
// `record=0`: an app reading again because the project's GitHub revision moved, not a person checking; it records nothing.
const refreshQuery = z.object({ refresh: z.literal('1').optional(), record: z.literal('0').optional() })
const approveBody = z.object({ scope: z.enum(['project', 'swarm']) }).strict()
+// New Project's "New repository" (task #1788): an organization the person picked, and the repository's name and privacy.
+const ownerParams = tabParams.extend({ owner: z.string().regex(GITHUB_OWNER) })
+const repositoryBody = z.object({ owner: z.string().regex(GITHUB_OWNER), name: z.string().max(200), private: z.boolean() }).strict()
// What GitHub sends back: a sign-in's code and our state, and after an installation its id and action.
const callbackQuery = z.object({ code: z.string().max(512).optional(), state: z.string().max(4096).optional(), error: z.string().max(128).optional(),
installation_id: z.string().max(32).optional(), setup_action: z.string().max(32).optional() })
@@ -305,6 +309,7 @@ export async function superTabRoutes(app: FastifyInstance, options: { store?: Su
const approvals = options.approvals ?? new PrismaApprovals(prisma)
const signIn = options.signIn !== undefined ? options.signIn : githubSignIn(env)
const approvalSecret = github ? stateSecret(github.app.config) : null
+ const createSecret = github ? createStateSecret(github.app.config) : null
// No token for a repository nobody who can push to it approved for this project: a project names its repository as
// text, and the app is on other people's repositories too.
// Rolled out with the team account (machines.ts `teamAccountRequired`): a Swarm outside it gets tokens as before, so a
@@ -326,6 +331,10 @@ export async function superTabRoutes(app: FastifyInstance, options: { store?: Su
const hosts = options.hosts ?? new HostReads(store, { githubApp: !!github, teamAccountsIdle: !github })
// Members' apps read a project's GitHub access again when its revision moves (projects.ts githubRevision). A move that
// fails is logged and changes no answer: the apps then read again within 5 minutes, as before.
+ /** One organization check against GitHub for [userId], within OWNER_CHECKS_PER_MINUTE (security reviews of #3201). */
+ const limitOwnerChecks = async (userId: string) => {
+ if (!await ownerCheckAllowed(userId)) throw new SuperTabError('RATE_LIMITED', 'Too many organization checks. Try again in a minute.', 429)
+ }
const recorded = (tabId: string, move: () => Promise<unknown>) => move().catch(error => {
logger.warn('[github] access change not recorded', { tabId, error: String(error) })
})
@@ -410,8 +419,89 @@ export async function superTabRoutes(app: FastifyInstance, options: { store?: Su
const install = github.app.installUrl()
return { authorizeUrl: signIn.authorizeUrl(state), installUrl: install ? `${install}?state=${encodeURIComponent(state)}` : null }
}))
+ // Whether an organization lets Harness create a repository there, for New Project's owner row before sign-in (F4, F5):
+ // 'not-configured' when this server can't (F6), so the apps hide the choice. A person of the Swarm only.
+ app.get<{ Params: z.infer<typeof ownerParams> }>('/api/super-tabs/:tabId/github/owners/:owner', { preHandler: validateParams(ownerParams) },
+ (req, reply) => respond(reply, async () => {
+ await store.requireWriter(req.user!, req.params.tabId)
+ if (!github || !signIn || !createSecret) return { state: 'not-configured' }
+ await limitOwnerChecks(req.user!.sub)
+ const readiness = await github.app.ownerReadiness(req.params.owner)
+ return readiness.state === 'not-installed' ? { state: readiness.state, ...(readiness.installUrl ? { installUrl: readiness.installUrl } : {}) } : { state: readiness.state }
+ }))
+ // A new repository for a project its owner just made: checked, recorded as waiting on the project, and the person sent to
+ // GitHub's sign-in, whose callback creates it with their own token (github/repositoryCreate.ts).
+ app.post<{ Params: z.infer<typeof projectParams>; Body: z.infer<typeof repositoryBody> }>('/api/super-tabs/:tabId/projects/:projectId/github/repository',
+ { preHandler: [validateParams(projectParams), validateBody(repositoryBody)] }, (req, reply) => respond(reply, async () => {
+ if (!github || !createSecret) throw new GitHubAppError('GITHUB_APP_NOT_CONFIGURED', 'This Harness server has no GitHub App configured.', 503)
+ if (!signIn) throw new GitHubAppError('GITHUB_APPROVAL_NOT_CONFIGURED', 'This Harness server cannot create repositories yet: its administrator sets GITHUB_APP_CLIENT_ID and GITHUB_APP_CLIENT_SECRET.', 503)
+ const { owner, name } = req.body
+ const problem = repositoryNameProblem(name)
+ if (problem) throw new SuperTabError('REPOSITORY_NAME', problem, 400)
+ // Who may, before any call signed with the app's key (security review 1 of #3201).
+ await store.mayCreateRepository(req.user!, req.params.tabId, req.params.projectId)
+ await limitOwnerChecks(req.user!.sub)
+ const readiness = await github.app.ownerReadiness(owner)
+ if (readiness.state === 'not-installed') {
+ throw new GitHubAppError('GITHUB_APP_NOT_INSTALLED', `Harness isn't on ${owner}'s GitHub yet.`, 409, readiness.installUrl ? { installUrl: readiness.installUrl } : undefined)
+ }
+ if (readiness.state === 'not-accepted') {
+ throw new GitHubAppError('GITHUB_APP_PERMISSIONS', `An owner of ${owner} needs to accept Harness's new permission once: GitHub Settings → GitHub Apps → Harness.`, 409)
+ }
+ const at = Date.now()
+ await store.startRepositoryCreation(req.user!, req.params.tabId, req.params.projectId, { owner, name, private: req.body.private }, at)
+ const state = signCreateState(createSecret, { userId: req.user!.sub, autonomousEnv: req.user!.autonomousEnv, tabId: req.params.tabId,
+ projectId: req.params.projectId, owner, name, private: req.body.private, at }, at)
+ return { authorizeUrl: signIn.authorizeUrl(state), at }
+ }))
app.get<{ Querystring: z.infer<typeof callbackQuery> }>('/api/github/callback', { preHandler: validateQuery(callbackQuery) }, async (req, reply) => {
const page = (title: string, text: string, status = 200) => reply.status(status).type('text/html; charset=utf-8').send(githubPage(title, text))
+ const create = createSecret && github && req.query.state ? readCreateState(createSecret, req.query.state, Date.now()) : null
+ if (create && github) {
+ const githubApp = github.app
+ const expired = () => page('This link has expired', 'Go back to Harness and create the repository again.', 400)
+ const deleted = (made: string | null) => page('The project was deleted meanwhile',
+ made ? `${made} was made on GitHub, but no project uses it. You can go back to Harness.` : 'Nothing was created. You can go back to Harness.', 410)
+ if (!await store.isLive(create.tabId)) return expired()
+ // Claimed before the code is used: a replay, or the same link opened twice, finds nothing to claim (security review 2).
+ const claimed = await store.claimRepositoryAsk(create.tabId, create.projectId, create.userId, create.at)
+ if (claimed === 'gone') return deleted(null)
+ if (!claimed) return expired()
+ const finish = (outcome: Parameters<SuperTabStore['finishRepositoryCreation']>[4]) =>
+ store.finishRepositoryCreation(create.tabId, create.projectId, create.userId, create.at, outcome).catch(error => {
+ logger.warn('[github] repository creation outcome not recorded', { tabId: create.tabId, error: String(error) })
+ return 'error' as const
+ })
+ const full = `${create.owner}/${create.name}`
+ if (req.query.error || !req.query.code || !signIn) {
+ await finish({ state: 'cancelled' })
+ return page('Nothing was created', 'Go back to Harness and choose Try again.')
+ }
+ const outcome = await signIn.withUserToken(req.query.code, call => createRepository(call, githubApp, create)).catch(() => null)
+ if (!outcome || outcome.state === 'failed') {
+ await finish({ state: 'failed' })
+ return page('GitHub didn\'t answer', 'Nothing was created. Go back to Harness and choose Try again.', 502)
+ }
+ if (outcome.state === 'taken') {
+ await finish({ state: 'taken' })
+ return page(`${full} already exists`, 'Go back to Harness and choose another name.', 409)
+ }
+ if (outcome.state === 'refused') {
+ await finish({ state: 'refused', reason: outcome.reason })
+ return page(`GitHub didn't let you create a repository in ${create.owner}`, `${outcome.reason} Go back to Harness to choose another way.`, 403)
+ }
+ // Allowed for the project only once its outcome is recorded on it: a project deleted meanwhile, or an ask replaced,
+ // gets no approval (security review 1 of #3201). Its creator can push, so it is allowed as their sign-in for it would.
+ const written = await finish({ state: 'created', repositoryUrl: outcome.repositoryUrl, reachable: outcome.reachable })
+ if (written === 'gone') return deleted(outcome.repository)
+ if (written !== 'recorded') {
+ return page(`${outcome.repository} is made`, 'Harness could not record it on your project. Go back to Harness and choose Try again: it finds the repository you just made.', 500)
+ }
+ await approvals.approve({ userId: create.userId, autonomousEnv: create.autonomousEnv, tabId: create.tabId, projectId: create.projectId,
+ repository: outcome.repository.toLowerCase(), scope: 'project' }, outcome.login)
+ return page(`${outcome.repository} is ready`, outcome.reachable ? 'Go back to Harness: your project starts in it.'
+ : `Go back to Harness. Teammates' agents can use it once an owner of ${create.owner} adds it to Harness in GitHub: Settings → GitHub Apps → Harness → Configure.`)
+ }
const request = approvalSecret && req.query.state ? readState(approvalSecret, req.query.state, Date.now()) : null
if (!request) return page('This link has expired', 'Go back to Harness and choose Continue in GitHub again.', 400)
// A Swarm deleted since the link was made allows nothing, and says so as an expired link does (superTabs/deletion.ts).
diff --git a/backend/src/superTabs/commands.ts b/backend/src/superTabs/commands.ts
index 8c00085f2..d7a59a569 100644
--- a/backend/src/superTabs/commands.ts
+++ b/backend/src/superTabs/commands.ts
@@ -58,7 +58,7 @@ import { BUDDY_REQUIREMENTS, buddyChatId, buddyReady, chosenBuddyName, isBuddy,
import { BUDDY_OWN_MACHINE_REFUSAL } from './buddyContract.js'
import { askBuddyModel, buddyModelResult, sendBuddyHome, sessionModel } from './buddyModel.js'
import { launchRefusedLine, leadArrived, LEAD_CLAIM_MS, leadEffort, leadJoined, leadOvertaken, leadStartFailed, leadStarting, leadHost, leadWaits, LEAD_CAPABILITY, placeLead } from './leadStart.js'
-import { allowedDrops, approvedDropNotice, droppedLines, MAX_APPROVALS, MAX_DROPPED_LINES, type ApprovalRow, type DroppedLine } from './ruleGuard.js'
+import { allowedDrops, approvedDropNotice, droppedLines, MAX_APPROVALS, MAX_DROPPED_LINES, refuseRepeats, type ApprovalRow, type DroppedLine } from './ruleGuard.js'
import { appendRouting, coordinatorNameOf, routingSummary, FIRST_INSTRUCTIONS, FIRST_SUMMARY, instructionsHash, instructionsTextSchema, legacyRoleName, liveNotes, MAX_NOTES, noteTextSchema, roleNameSchema, summarySchema, type PmNote } from './instructions.js'
import { INSTRUCTIONS_TEMPLATE } from './instructionsTemplate.js'
import { BUILT_IN_HEADING, tidySaved } from './pmSchedule.js'
@@ -1842,6 +1842,8 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,
const onTemplate = !current || project.instructionsHash === instructionsHash(INSTRUCTIONS_TEMPLATE)
const before = context.instructions?.revision === current ? context.instructions.text : onTemplate ? INSTRUCTIONS_TEMPLATE
: fail('INSTRUCTIONS_UNAVAILABLE', 'This project\'s instructions cannot be read now. Try again in a moment.', 503)
+ // A line the save adds that the document already has is refused with the existing line quoted (#3283).
+ refuseRepeats(before, command.text)
// A person's rule, or who gave it, is dropped only by that person or with their own message approving it (#3151).
const { told, rules } = allowedDrops(state, project, before, command.text, sender, command.approvals ?? [], context.approvals ?? [],
context.instructions?.at ?? 0)
@@ -2235,7 +2237,10 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,
// Revision 0 runs on the template (design, Migration); otherwise the stored document of this revision, read by the store.
const stored = !current ? INSTRUCTIONS_TEMPLATE : context.instructions?.revision === current ? context.instructions.text
: fail('INSTRUCTIONS_UNAVAILABLE', 'This project\'s instructions cannot be read now. Try again in a moment.', 503)
- saveInstructions(project, current, appendRouting(stored, command.text), routingSummary(command.text), askedBy)
+ // The line is one more item: one the document already has is refused like a save's, quoting it (#3283, review of #3202).
+ const appended = appendRouting(stored, command.text)
+ refuseRepeats(stored, appended)
+ saveInstructions(project, current, appended, routingSummary(command.text), askedBy)
break
}
case 'rule.remove':
diff --git a/backend/src/superTabs/instructions.test.ts b/backend/src/superTabs/instructions.test.ts
index c7dbd0086..5d829cf6f 100644
--- a/backend/src/superTabs/instructions.test.ts
+++ b/backend/src/superTabs/instructions.test.ts
@@ -521,6 +521,68 @@ describe('an instructions save keeps the rules people gave', () => {
})
})
+// Task #3283 (Leo, 11-05, from lamp): Faye saved a rule the instructions already had, as if new, which hid that it had skipped it.
+describe('an instructions save refuses a rule that is already there', () => {
+ const save = (baseRevision: number, text: string): Command => ({ type: 'instructions.save', projectId: 'lead', baseRevision, text, summary: 'Added a rule' })
+ const rule = 'Every phone app task runs on Tony\'s Mac first, its Engineer and its Tester both (owner, 4 Nov).'
+ const doc = (...rules: string[]) => ['# Project instructions', '', '## Rules', '', ...rules.map(r => `- ${r}`)].join('\n')
+ const base = doc(rule, 'No releases between 18:00 and 09:00 Vietnam time (owner, 2026-11-02).')
+ const stored = { instructions: { revision: 1, text: base, at: 500 } }
+ const refusal = (run: () => unknown) => {
+ try { run() } catch (error) { return error as { code: string; status: number; message: string; details: { repeated: unknown[] } } }
+ throw new Error('the save went through')
+ }
+
+ it('refuses a repeat of a rule, quoting the existing line and saying how to change it', () => {
+ const f = fixture()
+ const again = 'every phone-app task runs on Tony\'s Mac first, its Engineer and its Tester both! (Faye, 11-05)'
+ const refused = refusal(() => f.run(save(1, `${base}\n- ${again}`), owner, stored))
+ expect(refused).toMatchObject({ code: 'INSTRUCTIONS_RULE_REPEATED', status: 409, details: { repeated: [{ added: again, existing: rule }] } })
+ expect(refused.message).toContain(`"${rule}"`)
+ expect(refused.message).toMatch(/change that line/i)
+ expect(f.state.projects![0]).toMatchObject({ instructionsRevision: 1 })
+ })
+
+ it('refuses the same rule word for word', () => {
+ const f = fixture()
+ expect(refusal(() => f.run(save(1, `${base}\n- ${rule}`), owner, stored))).toMatchObject({ code: 'INSTRUCTIONS_RULE_REPEATED' })
+ })
+
+ it('saves a rule changed in substance, and a line reworded in place', () => {
+ const f = fixture()
+ const changed = f.run(save(1, `${base}\n- Every phone app task runs on Tony\'s Mac first, its Engineer but not its Tester (owner, 5 Nov).`), owner, stored)
+ expect(changed.result).toMatchObject({ revision: 2 })
+ const f2 = fixture()
+ expect(f2.run(save(1, base.replace('Every phone app task runs', 'Each phone app task runs')), owner, stored).result).toMatchObject({ revision: 2 })
+ })
+})
+
+// River, 11-05 (review of #3202): saves the server makes itself meet the repeat refusal too. The daily tidy is an
+// instructions.save, checked like any; an older client's rule.set appends one Routing line and must not add a repeat either.
+describe('server-made instruction saves and the repeat refusal', () => {
+ const doc = '# Doc\n\n## Routing\n\n- Reviews run on Opus at high effort for every task.\n- Phone tasks run on Tony\'s Mac first.\n'
+ const stored = { instructions: { revision: 1, text: doc, at: 500 } }
+ const set = (text: string): Command => ({ type: 'rule.set', rule: { kind: 'preferIdle' }, text })
+
+ it('refuses an older client\'s routing line the document already has, quoting it, and saves a new one', () => {
+ const f = fixture()
+ let refused: { code: string; message: string } | undefined
+ try { f.run(set('reviews run on Opus at high effort, for every task!'), owner, stored) } catch (error) { refused = error as typeof refused }
+ expect(refused).toMatchObject({ code: 'INSTRUCTIONS_RULE_REPEATED' })
+ expect(refused!.message).toContain('"Reviews run on Opus at high effort for every task."')
+ expect(f.state.projects![0]).toMatchObject({ instructionsRevision: 1 })
+ expect(f.run(set('Docs tasks run on Haiku first.'), owner, stored).result).toMatchObject({ revision: 2 })
+ })
+
+ it('saves a tidy that merges two copies of a line into one', () => {
+ const f = fixture()
+ const twice = `${doc}- Phone tasks run on Tony's Mac first.\n`
+ const effects = f.run({ type: 'instructions.save', projectId: 'lead', baseRevision: 1, text: doc, summary: 'Tidied', tidy: true } as Command, owner,
+ { instructions: { revision: 1, text: twice, at: 500 } })
+ expect(effects.result).toMatchObject({ revision: 2 })
+ })
+})
+
describe('PM notes', () => {
const note = (text: string, extra: Partial<Extract<Command, { type: 'note.add' }>> = {}): Command =>
({ type: 'note.add', projectId: 'lead', text, askedBy: 'owner', ...extra })
diff --git a/backend/src/superTabs/instructionsDiff.test.ts b/backend/src/superTabs/instructionsDiff.test.ts
index dfb8902e6..1692ec705 100644
--- a/backend/src/superTabs/instructionsDiff.test.ts
+++ b/backend/src/superTabs/instructionsDiff.test.ts
@@ -1,5 +1,5 @@
import { describe, expect, it } from 'vitest'
-import { attributedRules, droppedRules, personKey } from './instructionsDiff.js'
+import { attributedRules, droppedRules, personKey, repeatedRules } from './instructionsDiff.js'
// Task #3151 (Ken, 11-05, from lamp): a PM's tidy from revision 70 to 71 dropped Leo's rule and the "(0xken15, 4 Nov)" of a
// rule it kept, and nothing checked the save.
@@ -105,3 +105,58 @@ describe('droppedRules', () => {
expect(why(doc(tony), doc(tony.replace('0xken15', 'Dee')))).toEqual([[['0xken15'], 'unattributed']])
})
})
+
+// Task #3283 (Leo, 11-05, from lamp): Faye saved a rule the document already had as if it were new, which hid that it had
+// skipped it. A repeat is the same words in the same order, whatever its case, punctuation, list marker or attribution.
+describe('repeatedRules', () => {
+ const rule = 'Every phone app task runs on Tony\'s Mac first, its Engineer and its Tester both (owner, 4 Nov).'
+ const doc = (...lines: string[]) => ['# Project instructions', '', '## Rules', '', ...lines.map(l => `- ${l}`)].join('\n')
+ const before = doc(rule, 'No releases between 18:00 and 09:00 Vietnam time (owner, 2026-11-02).')
+ const repeats = (...added: string[]) => repeatedRules(before, [before, ...added.map(l => `- ${l}`)].join('\n'))
+
+ it('finds a line added word for word, and quotes the existing line', () => {
+ expect(repeats(rule)).toEqual([{ added: rule, existing: rule }])
+ })
+
+ it('finds it through case, punctuation, a new attribution, plurals and filler words', () => {
+ const reworded = 'every phone-app task runs on Tony\'s Mac first: its engineer and its tester both! (Faye, 11-05)'
+ expect(repeats(reworded)).toEqual([{ added: reworded, existing: rule }])
+ expect(repeats('Every phone app tasks run on Tony\'s Mac first, the Engineer and the Tester both.')).toHaveLength(1)
+ })
+
+ it('finds a rewrapped or renumbered copy', () => {
+ const wrapped = before + '\n1. Every phone app task runs on\n Tony\'s Mac first, its Engineer and\n its Tester both.'
+ expect(repeatedRules(before, wrapped)).toHaveLength(1)
+ })
+
+ it('does not find a rule changed in substance', () => {
+ expect(repeats('Every phone app task runs on Tony\'s Mac first, its Engineer but not its Tester.')).toEqual([])
+ expect(repeats('No releases between 18:00 and 10:00 Vietnam time (owner, 2026-11-02).')).toEqual([])
+ expect(repeats('Releases between 18:00 and 09:00 Vietnam time are fine (owner, 2026-11-02).')).toEqual([])
+ expect(repeats('Never run a phone app task on Tony\'s Mac first, its Engineer and its Tester both.')).toEqual([])
+ expect(repeats('Every phone app task runs on Tony\'s Mac first, its Engineer and its Tester both, unless urgent.')).toEqual([])
+ })
+
+ it('does not treat unchanged, moved, reworded-in-place or removed lines as repeats', () => {
+ expect(repeatedRules(before, before)).toEqual([])
+ const [first, second] = before.split('\n').slice(4)
+ expect(repeatedRules(before, [...before.split('\n').slice(0, 4), second, first].join('\n'))).toEqual([])
+ // Rewording a line in place leaves one copy; so does replacing a line with the same words under a new attribution.
+ expect(repeatedRules(before, before.replace('(owner, 4 Nov)', '(owner, 5 Nov)'))).toEqual([])
+ expect(repeatedRules(before, before.replace('Tony\'s Mac first', 'TONY\'S MAC FIRST'))).toEqual([])
+ expect(repeatedRules(before, doc('every phone app task runs on tony\'s mac first, its engineer and its tester both (Faye, 11-05).'))).toEqual([])
+ })
+
+ it('does not hold short lines, headings, or a plain line repeated under another section', () => {
+ const base = '# Project\n\n## Engineer\n\n- Pushes its branch as it goes and opens a draft pull request.\n- Tests pass.\n'
+ expect(repeatedRules(base, base + '- Tests pass.\n\n## Engineer notes\n\n## Engineer\n')).toEqual([])
+ expect(repeatedRules(base, base + '\n## Reviewer\n\n- Pushes its branch as it goes and opens a draft pull request.\n')).toEqual([])
+ expect(repeatedRules(base, base + '- Pushes its branch as it goes and opens a draft pull request.\n')).toHaveLength(1)
+ })
+
+ it('finds an attributed rule repeated in another section', () => {
+ const base = '# Project\n\n## PM\n\n- Decides, never asks the owner to choose (Ken, 2026-11-04).\n'
+ const added = '- Decides, never asks the owner to choose (Faye, 11-05).'
+ expect(repeatedRules(base, `${base}\n## Reviewer\n\n${added}\n`)).toEqual([{ added: added.slice(2), existing: 'Decides, never asks the owner to choose (Ken, 2026-11-04).' }])
+ })
+})
diff --git a/backend/src/superTabs/instructionsDiff.ts b/backend/src/superTabs/instructionsDiff.ts
index dcc1231f6..7325c4f55 100644
--- a/backend/src/superTabs/instructionsDiff.ts
+++ b/backend/src/superTabs/instructionsDiff.ts
@@ -222,3 +222,43 @@ export function keptIn(after: string): (text: string) => boolean {
return kept.some(set => covers(words, set))
}
}
+
+/** A line [after] adds that repeats one it keeps: the added line's words and the existing line's, as the document has them. */
+export interface RepeatedRule { added: string; existing: string }
+/** Fewest content words of a line that can be a repeat: a short line ("Tests pass.") says too little to be the same rule. */
+const MIN_REPEAT_WORDS = 4
+/** Repeats one refusal lists; more are cut. */
+export const MAX_REPEATS = 20
+
+/**
+ * The lines [after] adds, or rewrites, that say what a line it keeps already says (task #3283, Leo 11-05, from lamp: a PM
+ * saved a rule the document had as if it were new, which hid that it had skipped it). Conservative: a repeat has the same
+ * content words in the same order, so case, punctuation, list marker, wrapping, attribution, filler words and plurals make no
+ * difference, and any changed, added or dropped word, negation or number is a change of substance, not a repeat. A line the
+ * old text has word for word is not new; headings and lines under MIN_REPEAT_WORDS words are never repeats; the existing line
+ * is one the save keeps, in the same section, or an attributed rule against another (a rule is one rule wherever it sits).
+ */
+export function repeatedRules(before: string, after: string): RepeatedRule[] {
+ const old = new Map<string, number>()
+ for (const item of items(before)) old.set(item.key, (old.get(item.key) ?? 0) + 1)
+ const kept = new Map<string, { text: string; path: string; attributed: boolean }[]>()
+ const added: { segment: Segment; path: string }[] = []
+ for (const item of items(after)) {
+ if (item.heading) continue
+ const n = old.get(item.key) ?? 0
+ if (n) old.set(item.key, n - 1)
+ for (const segment of segments(item.text)) {
+ if (segment.seq.length < MIN_REPEAT_WORDS) continue
+ if (n) {
+ const key = segment.seq.join(' ')
+ kept.set(key, [...kept.get(key) ?? [], { text: segment.text, path: item.path, attributed: segment.people.length > 0 }])
+ } else added.push({ segment, path: item.path })
+ }
+ }
+ const repeats: RepeatedRule[] = []
+ for (const { segment, path } of added) {
+ const same = kept.get(segment.seq.join(' '))?.find(k => k.path === path || (k.attributed && segment.people.length > 0))
+ if (same) repeats.push({ added: segment.text, existing: same.text })
+ }
+ return repeats
+}
diff --git a/backend/src/superTabs/projects.ts b/backend/src/superTabs/projects.ts
index 99d9b181e..df6bdce64 100644
--- a/backend/src/superTabs/projects.ts
+++ b/backend/src/superTabs/projects.ts
@@ -92,6 +92,24 @@ export interface SwarmProject {
githubSeen?: GitHubSeen
/** What its coordinator is called; reads give "Product Manager" when absent (instructions.ts coordinatorNameOf). */
coordinatorName?: string
+ /** Its owner's last "New repository" from New Project (task #1788): asked, then what GitHub's sign-in made of it. The
+ * app that asked starts the Product Manager in it once `created`; the next ask replaces it. */
+ repositoryCreation?: RepositoryCreation
+}
+
+/** A new repository asked for a project (store.ts startRepositoryCreation, finishRepositoryCreation). [at] (ms) and [by]
+ * name the ask an outcome answers. */
+export interface RepositoryCreation {
+ owner: string
+ name: string
+ private: boolean
+ by: string
+ at: number
+ /** 'creating' once GitHub's callback claimed the ask, so a replay of it changes nothing (security review 2 of #3201). */
+ state: 'waiting' | 'creating' | 'created' | 'taken' | 'refused' | 'failed' | 'cancelled'
+ repositoryUrl?: string
+ reachable?: boolean
+ reason?: string
}
/** The GitHub access states a check records (github/projectAccess.ts): the others are no answer from GitHub. */
@@ -545,6 +563,16 @@ export function mutableProjects(state: SuperTabState): SwarmProject[] {
return state.projects ??= projectsOf(state)
}
+/** The project [actor] may ask a new repository for (task #1788): a person, its owner, while it has no repository address. */
+export function repositoryCreator(state: SuperTabState, actor: Actor, projectId: string): SwarmProject {
+ if (actor.kind !== 'person') fail('HUMAN_REQUIRED', 'A person creates a project\'s repository.', 403)
+ const project = readProject(state, actor, projectId)
+ author(state, actor, true)
+ if (!ownsProject(state, actor.userId, project)) fail('PROJECT_OWNER_REQUIRED', 'Only the project owner can create its repository.', 403)
+ if (project.repository?.repositoryUrl) fail('PROJECT_REPOSITORY_SET', 'This project already shares another repository.', 409)
+ return project
+}
+
export function manageProject(state: SuperTabState, actor: Actor, projectId: string): SwarmProject {
const project = readProject(state, actor, projectId)
author(state, actor, true)
diff --git a/backend/src/superTabs/ruleGuard.ts b/backend/src/superTabs/ruleGuard.ts
index a800e6478..c6b21f585 100644
--- a/backend/src/superTabs/ruleGuard.ts
+++ b/backend/src/superTabs/ruleGuard.ts
@@ -5,7 +5,7 @@
* dropped rule makes the save or wrote a message approving it that the save names. Who a person is comes from the sender or
* the stored message's author, never the caller's word (askedBy). The approver is then told in one private line.
*/
-import { attributedRules, droppedRules, ITEM_CHARS, keptIn, personKey, removedItems, type DroppedRule } from './instructionsDiff.js'
+import { attributedRules, droppedRules, ITEM_CHARS, keptIn, MAX_REPEATS, personKey, removedItems, repeatedRules, type DroppedRule } from './instructionsDiff.js'
import { fail, type Author, type SuperTabState } from './model.js'
import { canReadProject, type SwarmProject } from './projects.js'
import { isSwarmBuddyChat } from './buddies.js'
@@ -82,6 +82,23 @@ export function allowedDrops(state: SuperTabState, project: SwarmProject, before
return { told, rules: dropped }
}
+/**
+ * Refuses a save that adds a line repeating one the document keeps (task #3283, Leo 11-05, from lamp: a PM saved a rule the
+ * instructions already had as if new, which hid that it had skipped it). Each repeat is listed with the existing line quoted;
+ * a change meant is made on that line. Conservative: only the same words (instructionsDiff.ts repeatedRules).
+ */
+export function refuseRepeats(before: string, after: string): void {
+ const repeats = repeatedRules(before, after)
+ if (!repeats.length) return
+ const shown = repeats.slice(0, MAX_REPEATS)
+ fail('INSTRUCTIONS_RULE_REPEATED', [
+ 'Not saved: this adds a line the instructions already have, so it would be read twice. Check that rule before adding it: '
+ + 'it may be one you skipped. If you meant to change it, change that line in place instead of adding another.',
+ ...shown.map(repeat => `- Existing line: "${cut(repeat.existing)}" (added again as "${cut(repeat.added)}")`),
+ ...(repeats.length > shown.length ? [`- And ${repeats.length - shown.length} more.`] : []),
+ ].join('\n'), 409, { repeated: shown })
+}
+
/** Lines one revision's History keeps (River, 11-05): a rewrite of the whole document lists its first 500. */
export const MAX_DROPPED_LINES = 500
/** How the coordinator sorted a line it dropped (pmSchedule.ts, the daily tidy): kept elsewhere with who said it, or a step
diff --git a/backend/src/superTabs/store.ts b/backend/src/superTabs/store.ts
index 328304144..33a32631f 100644
--- a/backend/src/superTabs/store.ts
+++ b/backend/src/superTabs/store.ts
@@ -44,7 +44,7 @@ import { retryTransient } from './retry.js'
import { recordReload } from './retryStats.js'
import { buddyChatId, shownBefore, swarmBuddyChatId, type ChosenBuddyName } from './buddies.js'
import { cleanPullRequestLinks } from './cards.js'
-import { accountOf, wordsOf, buddyInstructionsProject, canReadAgent, canReadGroup, groupRepositoryUrl, canWatchAgent, groupProject, ledProject, onTeamAccount, ownerAccount, ownsProject, admitPerson, projectOf, projectsOf, agentProjectId, readConversation, readProject, skillModeOf, startProject, type ProjectVisibility, sessionKey, GITHUB_SEEN, type GitHubSeen, type SwarmProject } from './projects.js'
+import { accountOf, wordsOf, buddyInstructionsProject, canReadAgent, canReadGroup, groupRepositoryUrl, canWatchAgent, groupProject, ledProject, onTeamAccount, ownerAccount, ownsProject, admitPerson, projectOf, projectsOf, agentProjectId, readConversation, readProject, skillModeOf, startProject, type ProjectVisibility, sessionKey, GITHUB_SEEN, type GitHubSeen, type RepositoryCreation, repositoryCreator, type SwarmProject } from './projects.js'
import { bindSession, makeProjectPrivate } from './sessionScope.js'
import { SESSION_ENDED_KIND, sessionContext, sessionReadsRow, type ContextRow } from './buddySessions.js'
import { DELETED_TEXT, type MessageChangeTarget } from './messageEdits.js'
@@ -3496,6 +3496,73 @@ export class SuperTabStore {
return this.moveGitHub(tabId, project => project.id === projectId && project.githubSeen !== seen, project => { project.githubSeen = seen })
}
+ /** Refuses anyone but a person of [tabId] who may write there (a viewer reads only), for New Project's organization check. */
+ async requireWriter(user: AuthUser, tabId: string): Promise<void> {
+ this.personOnly(user)
+ const { state } = await this.readLoad(user, tabId)
+ author(state, await this.actor(this.db, user, state), true)
+ }
+
+ /** Refuses [user] unless they may ask for a new repository for [projectId] now: a person, its owner, while it has no
+ * repository address. Read only: the routes ask this before any GitHub call (security review 1 of #3201). */
+ async mayCreateRepository(user: AuthUser, tabId: string, projectId: string): Promise<void> {
+ this.personOnly(user)
+ const { state } = await this.readLoad(user, tabId)
+ repositoryCreator(state, await this.actor(this.db, user, state), projectId)
+ }
+
+ /** [user] asks for a new repository for their project (task #1788), checked as [mayCreateRepository] in its write.
+ * Written on the project as `waiting`, replacing any earlier ask, so the apps show it. */
+ async startRepositoryCreation(user: AuthUser, tabId: string, projectId: string, ask: { owner: string; name: string; private: boolean }, at: number): Promise<void> {
+ this.personOnly(user)
+ await transaction(this.db, async tx => {
+ const loaded = await this.load(tx, user, tabId), state = cloneData(loaded.state)
+ const actor = await this.actor(tx, user, state)
+ repositoryCreator(state, actor, projectId)
+ const stored = (state.projects ?? []).find(p => p.id === projectId)!
+ stored.repositoryCreation = { owner: ask.owner, name: ask.name, private: ask.private, by: user.sub, at, state: 'waiting' }
+ stored.githubRevision = (stored.githubRevision ?? 0) + 1
+ await this.save(tx, loaded, state, clock.next(), [{ kind: 'head', key: 'head' }])
+ })
+ }
+
+ /** GitHub's callback claims the waiting ask by [by] at [at] before it uses the sign-in's code: `creating`, in one write, so
+ * a replayed or doubled callback finds nothing to claim and changes nothing (security review 2 of #3201). Null when there
+ * is no such waiting ask, 'gone' when the project or its Swarm is. */
+ async claimRepositoryAsk(tabId: string, projectId: string, by: string, at: number): Promise<RepositoryCreation | null | 'gone'> {
+ return this.repositoryAskWrite(tabId, projectId, by, at, 'waiting', asked => ({ ...asked, state: 'creating' }))
+ }
+
+ /** What GitHub's sign-in made of the ask by [by] at [at]: written only over that same ask while its callback holds it
+ * (`creating`), so a late or repeated callback never overwrites a newer one ('stale'). 'gone' when the project or its
+ * Swarm is: the callback then allows nothing for it. */
+ async finishRepositoryCreation(tabId: string, projectId: string, by: string, at: number,
+ outcome: Pick<RepositoryCreation, 'state' | 'repositoryUrl' | 'reachable' | 'reason'>): Promise<'recorded' | 'stale' | 'gone'> {
+ const written = await this.repositoryAskWrite(tabId, projectId, by, at, 'creating', asked => ({ owner: asked.owner, name: asked.name, private: asked.private,
+ by, at, state: outcome.state, ...(outcome.repositoryUrl ? { repositoryUrl: outcome.repositoryUrl } : {}),
+ ...(outcome.reachable === undefined ? {} : { reachable: outcome.reachable }), ...(outcome.reason ? { reason: outcome.reason } : {}) }))
+ return written === 'gone' ? 'gone' : written ? 'recorded' : 'stale'
+ }
+
+ /** One write of a project's repository ask, only while it is [by]'s ask at [at] in state [from]. */
+ private async repositoryAskWrite(tabId: string, projectId: string, by: string, at: number, from: RepositoryCreation['state'],
+ next: (asked: RepositoryCreation) => RepositoryCreation): Promise<RepositoryCreation | null | 'gone'> {
+ return transaction(this.db, async tx => {
+ const row = await tx.superTab.findUnique({ where: { id: tabId }, select: SWARM_ROW })
+ if (!row || row.deletedAt) return 'gone'
+ const loaded = await loadRow(tx, requireParts(row), {})
+ const state = cloneData(loaded.state)
+ const project = (state.projects ?? []).find(p => p.id === projectId)
+ if (!project) return 'gone'
+ const asked = project.repositoryCreation
+ if (!asked || asked.by !== by || asked.at !== at || asked.state !== from) return null
+ project.repositoryCreation = next(asked)
+ project.githubRevision = (project.githubRevision ?? 0) + 1
+ await this.save(tx, loaded, state, clock.next(), [{ kind: 'head', key: 'head' }])
+ return project.repositoryCreation
+ })
+ }
+
/** One state write moving the GitHub revision of the projects [moves] picks, re-read in its transaction; none picked
* writes nothing. */
private async moveGitHub(tabId: string, moves: (project: SwarmProject) => boolean, also?: (project: SwarmProject) => void): Promise<boolean> {
diff --git a/desktop/lib/super_tabs/route_row.dart b/desktop/lib/super_tabs/route_row.dart
index 7052dfe87..7cb53197e 100644
--- a/desktop/lib/super_tabs/route_row.dart
+++ b/desktop/lib/super_tabs/route_row.dart
@@ -181,9 +181,77 @@ class _SuperTabRouteRowState extends State<SuperTabRouteRow> {
].join(' — '),
),
],
- for (final e in excluded)
- Text('Unavailable: ${e['title']} — ${e['reason']}'),
+ for (final line in _unavailableLines(excluded)) Text(line),
],
);
}
}
+
+/// The CLI's titleOf: "name · engine model effort · machine" (route.ts). The
+/// engine part holds no " · ", so a machine named with one keeps it whole.
+final _titled = RegExp(r'^(.*) · ((?:Claude|Codex) (?:(?! · ).)*) · (.*)$');
+
+/// How route.ts starts a plug-in's refusal: its name, then ": ".
+final _ruled = RegExp(r'^[A-Z][A-Za-z ]{0,40}: ');
+
+/// What a route decision left out, a line each for Details. Task #3292 (Ken,
+/// 2026-11-05): a line per excluded machine × agent × model made an offline
+/// machine 17 lines and the grid limit for security work about 30, a hundred
+/// lines before what the route weighed. So, as the PM's answer does (CLI
+/// routeCommand.ts leftOut): one line per machine with its distinct reasons,
+/// at most [_maxReasons]; a "Name: …" reason seen on several machines (the
+/// grid limit for security work) is said once, naming those machines, since
+/// some read the same but are a machine's fact ("Required tool missing: git."):
+/// a person must still see where. A row of no machine keeps its own line, once.
+/// OFFLINE has no "Name: ", so each offline machine keeps its line. Unlike
+/// leftOut, a machine that also offered candidates keeps its line: Details is
+/// the whole decision, the PM's answer only why a machine was never offered.
+List<String> _unavailableLines(Iterable<Map<String, dynamic>> excluded) {
+ final byMachine = <String, List<String>>{};
+ final others = <String>{};
+ final machinesOf = <String, Set<String>>{};
+ for (final e in excluded) {
+ final title = '${e['title'] ?? ''}', reason = '${e['reason'] ?? ''}';
+ final machine = _titled.firstMatch(title)?.group(3);
+ if (machine == null) {
+ others.add('Unavailable: $title — $reason');
+ continue;
+ }
+ final reasons = byMachine.putIfAbsent(machine, () => []);
+ if (!reasons.contains(reason)) reasons.add(reason);
+ if (_ruled.hasMatch(reason)) {
+ machinesOf.putIfAbsent(reason, () => {}).add(machine);
+ }
+ }
+ final rules = {
+ for (final MapEntry(key: reason, value: machines) in machinesOf.entries)
+ if (machines.length > 1) reason: machines.toList(),
+ };
+ return [
+ for (final MapEntry(key: reason, value: machines) in rules.entries)
+ 'Unavailable on ${_named(machines)} — $reason',
+ for (final MapEntry(key: machine, value: all) in byMachine.entries)
+ if (all.where((r) => !rules.containsKey(r)).toList() case final reasons
+ when reasons.isNotEmpty)
+ 'Unavailable: $machine — ${_upTo(reasons)}',
+ ...others,
+ ];
+}
+
+const _maxReasons = 4, _maxNamed = 3;
+
+/// "A and B", "A, B and C", or past [_maxNamed] "A, B, C and 2 more machines".
+String _named(List<String> machines) {
+ if (machines.length > _maxNamed) {
+ final more = machines.length - _maxNamed;
+ return '${machines.take(_maxNamed).join(', ')} and $more more machine${more == 1 ? '' : 's'}';
+ }
+ return '${machines.take(machines.length - 1).join(', ')} and ${machines.last}';
+}
+
+/// A machine's distinct reasons, the first [_maxReasons] and how many more.
+String _upTo(List<String> reasons) => [
+ ...reasons.take(_maxReasons),
+ if (reasons.length > _maxReasons)
+ '(and ${reasons.length - _maxReasons} more)',
+].join(' ');
diff --git a/desktop/test/super_tab_route_test.dart b/desktop/test/super_tab_route_test.dart
index b02c99024..7306c0bfe 100644
--- a/desktop/test/super_tab_route_test.dart
+++ b/desktop/test/super_tab_route_test.dart
@@ -45,7 +45,11 @@ Map<String, dynamic> routeRow({
/// The decision's record as the backend keeps it. A record from before
/// floors went still carries `floor` and `notes`, which nothing shows; with
/// [revision] null, a record from before it named the instructions revision.
-Map<String, dynamic> decision({String? overrideTo, int? revision = 7}) => {
+Map<String, dynamic> decision({
+ String? overrideTo,
+ int? revision = 7,
+ List<Map<String, dynamic>> excluded = const [],
+}) => {
'id': 'd1',
'conversationId': 'offline',
'record': {
@@ -66,7 +70,7 @@ Map<String, dynamic> decision({String? overrideTo, int? revision = 7}) => {
'title': 'New agent · Codex low · mac',
},
],
- 'excluded': const [],
+ 'excluded': excluded,
'floor': 3,
'notes': true,
'pick': 'c0',
@@ -220,6 +224,130 @@ void main() {
});
}
+ // Task #3292 (Ken, 2026-11-05): Details printed one line per excluded
+ // machine × agent × model, about a hundred lines before what the route
+ // weighed. The record's rows keep the CLI's titleOf title and the reason.
+ const offline = 'Machine is offline or unreachable.';
+ const gridSecurity =
+ 'Grid limits: Security-sensitive work (a security kind or high risk) '
+ 'never runs on a model on the Swarm\'s grid.';
+ List<Map<String, dynamic>> rowsOn(
+ String machine,
+ String reason, {
+ int count = 1,
+ String runs = 'Claude opus high',
+ }) => [
+ for (var i = 0; i < count; i++)
+ {'title': 'New agent · $runs $i · $machine', 'reason': reason},
+ ];
+ Future<void> openDetails(
+ WidgetTester tester,
+ List<Map<String, dynamic>> excluded,
+ ) async {
+ final server = ConversationServer();
+ server.routeDecisions['d1'] = decision(excluded: excluded);
+ await tester.pumpWidget(
+ rowOf(SuperTabMessage.fromJson(routeRow()), controller(server)),
+ );
+ await tester.tap(find.text('Details'));
+ await tester.pumpAndSettle();
+ }
+
+ testWidgets('an offline machine with 17 excluded rows is one line', (
+ tester,
+ ) async {
+ await openDetails(tester, rowsOn('Mac 4', offline, count: 17));
+ final line = find.text('Unavailable: Mac 4 — $offline');
+ expect(line, findsOneWidget);
+ expect(find.textContaining('Unavailable'), findsOneWidget);
+ // The candidates come first.
+ expect(
+ tester.getTopLeft(find.text('Considered')).dy,
+ lessThan(tester.getTopLeft(line).dy),
+ );
+ expect(
+ tester
+ .getTopLeft(
+ find.text('New agent · Codex low · mac — Codex, cheapest'),
+ )
+ .dy,
+ lessThan(tester.getTopLeft(line).dy),
+ );
+ });
+
+ testWidgets('the security grid limit shows once per decision', (
+ tester,
+ ) async {
+ await openDetails(tester, [
+ for (final machine in ['Mac 3', 'MacBook-Pro-8', 'Tony\'s Mac'])
+ ...rowsOn(
+ machine,
+ gridSecurity,
+ count: 10,
+ runs: 'Claude on Kimi K3 (local)',
+ ),
+ ]);
+ expect(find.textContaining('Grid limits'), findsOneWidget);
+ expect(
+ find.text(
+ 'Unavailable on Mac 3, MacBook-Pro-8 and Tony\'s Mac — $gridSecurity',
+ ),
+ findsOneWidget,
+ );
+ // Those machines offered their other candidates: no line of their own.
+ expect(find.textContaining('Unavailable: '), findsNothing);
+ });
+
+ // Review of #3167: "Required tool missing: git." reads like a rule but is a
+ // machine fact; a line said once must still say where.
+ testWidgets('a reason said once names its machines', (tester) async {
+ const git = 'Required tool missing: git.';
+ await openDetails(tester, [
+ ...rowsOn('Mac 3', git, count: 2),
+ ...rowsOn('Gray.local', git),
+ ]);
+ expect(
+ find.text('Unavailable on Mac 3 and Gray.local — $git'),
+ findsOneWidget,
+ );
+ expect(find.textContaining('Unavailable'), findsOneWidget);
+ await tester.pumpWidget(const SizedBox());
+ await openDetails(tester, [
+ for (final machine in ['A', 'B', 'C', 'D', 'E']) ...rowsOn(machine, git),
+ ]);
+ expect(
+ find.text('Unavailable on A, B, C and 2 more machines — $git'),
+ findsOneWidget,
+ );
+ });
+
+ testWidgets('each machine keeps its own line and up to four reasons', (
+ tester,
+ ) async {
+ await openDetails(tester, [
+ ...rowsOn('Mac 4', offline, count: 3),
+ ...rowsOn('Linux box', offline, count: 2),
+ for (final r in ['A.', 'B.', 'C.', 'B.', 'D.', 'E.'])
+ ...rowsOn('Studio · Mac', r),
+ // A rule's reason on one machine only is that machine's.
+ ...rowsOn('Mac 3', gridSecurity, runs: 'Claude on Kimi K3 (local)'),
+ {'title': 'Named model', 'reason': 'No model is called Kimi.'},
+ {'title': 'Named model', 'reason': 'No model is called Kimi.'},
+ {'title': 'Custom row', 'reason': 'Something else.'},
+ ]);
+ for (final line in [
+ 'Unavailable: Mac 4 — $offline',
+ 'Unavailable: Linux box — $offline',
+ 'Unavailable: Studio · Mac — A. B. C. D. (and 1 more)',
+ 'Unavailable: Mac 3 — $gridSecurity',
+ 'Unavailable: Named model — No model is called Kimi.',
+ 'Unavailable: Custom row — Something else.',
+ ]) {
+ expect(find.text(line), findsOneWidget, reason: line);
+ }
+ expect(find.textContaining('Unavailable'), findsNWidgets(6));
+ });
+
testWidgets('shows what a route relied on, never floors', (tester) async {
for (final (revision, line) in [
(7, 'Relied on instructions revision 7'),
diff --git a/docs/plans/2026-11-05-instructions-repeat-refused-plan.md b/docs/plans/2026-11-05-instructions-repeat-refused-plan.md
new file mode 100644
index 000000000..858bf5f00
--- /dev/null
+++ b/docs/plans/2026-11-05-instructions-repeat-refused-plan.md
@@ -0,0 +1,72 @@
+# An instructions save refuses a rule that's already there (task #3283) — plan
+
+> Written by writing-plans and implemented by its Engineer test first (test-driven-development), as the project's
+> instructions describe. No Execution Handoff.
+
+**Goal:** A PM that saves a line repeating one the document already has is told so, with the existing line quoted, instead
+of the repeat being added as if new (lamp, 11-05: Faye was assigned a check against a rule already in its instructions and
+saved the same rule again, which hid that it had skipped it).
+
+**Architecture:** A pure check `repeatedRules(before, after)` in `instructionsDiff.ts` over the items and segments that file
+already parses (case, punctuation, list markers, wrapping, attributions and stop words already normalised into a segment's
+content-word sequence). `ruleGuard.ts` wraps it as `refuseRepeats`, which fails with `INSTRUCTIONS_RULE_REPEATED` (409)
+naming each repeat and the existing line. `commands.ts` `instructions.save` calls it beside `allowedDrops`.
+
+**Tech Stack:** TypeScript, vitest, the backend's command reducer (`applyCommand`).
+
+**Spec:** task #3283 (River, from Leo and Guide2's #3069 proposal).
+
+## Global Constraints
+
+- Conservative: a line is a repeat only when its content-word sequence equals an existing line's, in order. Any changed,
+ added or removed content word, negation or number is a change of substance and saves.
+- Only lines the save adds or rewrites are checked (an item word-for-word in the old text is never new). The existing line
+ must be one the save keeps. Headings and lines under 4 content words are never repeats.
+- A repeat counts within a section, or between two attributed rules anywhere (a rule is one rule, whoever repeats it).
+- Server only. No new stored data, no new settings. Swarm code stays out of `cli/src/core`. Temp files only in `mktemp -d`.
+
+## Design
+
+- growth: none; no stored data.
+- concurrency: N/A; runs inside the save's existing revision check, on the two texts it already holds.
+- read cost: none added; segments of two documents, once per save.
+- scale: a 64 KB document is ~1,000 items; one pass builds a map from sequence to items, linear in the document.
+- compatibility: an older client's save is refused with the same text its PM reads; `rule.set` only appends one new rule and
+ is not checked here.
+- migration + rollback: none; reverting the code removes the check.
+- audience: the server enforces it for every writer, person or agent.
+- identity: N/A. failure: the refusal names every repeat and its existing line, and how to change it if a change was meant.
+- platforms: server only.
+
+## Review Focus
+
+- False positives: a rule changed in substance (negation, number, one content word) or a legitimate same-words line in
+ another section must save.
+- False negatives: the incident's shape (same rule, new attribution/case/punctuation) must be refused.
+
+## Task 1: `repeatedRules` in instructionsDiff.ts
+
+**Files:** `backend/src/superTabs/instructionsDiff.ts`, `backend/src/superTabs/instructionsDiff.test.ts`
+
+**Interfaces:**
+```ts
+export interface RepeatedRule { added: string; existing: string }
+export function repeatedRules(before: string, after: string): RepeatedRule[]
+```
+
+- [ ] Write failing tests: exact repeat, case/punctuation/attribution repeat, rewrapped and renumbered repeat; changed
+ negation or number is not a repeat; an unchanged document and a moved item are not; a line the save removes is not "kept".
+- [ ] Run them, see them fail. Commit the tests.
+- [ ] Implement; run them, see them pass. Commit.
+
+## Task 2: Refuse it on `instructions.save`
+
+**Files:** `backend/src/superTabs/ruleGuard.ts`, `backend/src/superTabs/commands.ts`, `backend/src/superTabs/instructions.test.ts`
+
+**Interfaces:** `refuseRepeats(before: string, after: string): void` fails `INSTRUCTIONS_RULE_REPEATED`, 409, details
+`{ repeated: { added, existing }[] }`.
+
+- [ ] Write failing tests through `applyCommand`: a repeat is refused with the existing line quoted and nothing saved; a
+ changed rule saves; a save of the same rule only reworded in place (not a second copy) saves.
+- [ ] Run, see them fail. Commit the tests.
+- [ ] Implement and wire in `commands.ts`; run, see them pass. Commit.
diff --git a/docs/plans/2026-11-05-new-repository-design.md b/docs/plans/2026-11-05-new-repository-design.md
new file mode 100644
index 000000000..8b8675722
--- /dev/null
+++ b/docs/plans/2026-11-05-new-repository-design.md
@@ -0,0 +1,357 @@
+# New Project can create a new GitHub repository (task #1788) Design
+
+Status: design only, for Ken's security read and Dee's mockup read. No code until both agree.
+
+## Goal
+
+Dee (11-01): "how do I start a new project with a new repo?" Today a person makes the repository on GitHub, then pastes
+its link into New Project. This adds a **New repository** choice to New Project on the phone and on Desktop: a name,
+private by default, made in the Swarm's GitHub organization, and the project starts in it.
+
+Positioning: "Tell the PM what you want, and your crew ships it." A new idea should reach a working crew from Harness
+alone, without a detour through GitHub's website first.
+
+## What exists today (read 2026-11-05 on main 2c5ac721f)
+
+- **Phone**: `mobile/lib/swarm/swarm_new_project_sheet.dart`. The Repository row opens a list of the repositories this
+ Swarm's projects already use, then "Enter a link". Create sends `project.create`, `message.send`, `lead.start
+ {repositoryUrl}`, `project.rename`.
+- **Desktop**: New Project is the New Harness composer (`desktop/lib/widgets/new_harness_form.dart`,
+ `desktop/lib/state/new_harness.dart`, `desktop/lib/super_tabs/launch.dart`). The "Choose repo" menu offers Open
+ Folder, New Folder, Clone Repository (paste a GitHub URL) and recent folders. It sends the same four commands.
+- **Backend**: the Harness GitHub App (`backend/src/github/app.ts`) mints installation tokens with explicit,
+ narrow permission sets (`TOKEN_PERMISSIONS` and the read-only sets). It has no Administration permission. A
+ repository is used for teammates' agents only after someone GitHub says can push to it approves it
+ (`backend/src/github/approvals.ts`). They approve by signing in through the app's own sign-in ("Continue in GitHub").
+ That sign-in's short-lived user token is used once, revoked at once and never stored.
+- Nothing in Harness knows a Swarm's "GitHub organization". The closest fact is the owners of the repositories its
+ projects already use.
+
+## Permission model
+
+### What the app is allowed to do (GitHub side)
+
+GitHub added two narrow repository permissions for apps (October 2026), so creating a repository no longer needs
+**Administration**. Administration would also let a token delete or transfer any repository the app is on.
+
+| Permission | Level | Why | Used with |
+| --- | --- | --- | --- |
+| Repository creation | Read and write | `POST /orgs/{org}/repos` | The person's own user token only |
+| GitHub App installation repository access | Read and write | Add the new repository to the app's installation, only where the installation is on *Only select repositories* | The person's own user token only |
+
+- **Administration is never requested.**
+- An owner of each organization accepts the new permissions once: **Settings → GitHub Apps → Harness → Configure →
+ Accept new permissions**. Until they do, New repository says so for that organization, and everything else works as
+ today. This is the same rollout as Workflows and Issues (docs/swarm-github-app.md, "Workflows and issues").
+
+### Whose token creates it: the person's, not the app's
+
+The repository is created with the **person's own user token from the app's sign-in**, the same "Continue in GitHub"
+step that approves a repository today. It is not created with an installation token. So:
+
+- **GitHub decides who may create.** A user token can do only what both the app and the person may do. If the
+ organization lets only owners create repositories, or the person is not a member, GitHub refuses, and Harness
+ shows that refusal. Harness adds no allow-list of its own that could drift from GitHub's.
+- **The record names a person.** GitHub's audit log shows the person as the creator, "via Harness". The machine
+ owner's login is never used (identity rule). The person becomes the repository's admin, as if they had made it on
+ GitHub.
+- **The token lives seconds.** It makes at most three calls (create, add to installation, read back), then it is
+ revoked (`DELETE /applications/{client_id}/token`), as `GitHubSignIn.permission` does today. It is never stored or
+ logged.
+- **The approval comes with it.** The creator can push, so the new repository is approved for this project in the same
+ step. No second "Continue in GitHub".
+
+### Installation tokens never carry the new permissions
+
+Every installation token Harness mints names its permissions. None of those sets will ever include
+`repository_creation` or `installation_repositories`. A unit test pins this (every exported `*_PERMISSIONS` set, and
+the granted-permission filter, exclude both), so a later change cannot widen agents' tokens by accident.
+
+### Residual risk, for Ken's self-audit
+
+- **A leaked app private key** could mint an installation token that asks for the new permissions, in organizations
+ that accepted them. With them it could create repositories and add any of the organization's repositories to the
+ installation, which widens what a leaked key reaches. Today a leaked key already writes contents on every installed
+ repository. The key stays in the backend's secret store only (unchanged), and the installation-access permission is
+ needed only for *Only select repositories* installs.
+ - **Option A**: request both permissions. A repository GitHub somehow left off a *select repositories* install is
+ added by Harness right after it is made.
+ - **Option B (recommended, now that GitHub documents (2) below)**: request **Repository creation** only. GitHub
+ gives the app access to the repositories it creates, on either kind of install. The leaked-key reach does not grow.
+ If GitHub ever leaves one off, the person sees F7 and an owner adds it by hand.
+ - **The code works either way.** It adds the repository to the installation only where the installation has
+ granted *installation repository access*, read the same way Harness reads Workflows and Issues today. Ken's choice
+ is a setting on the app on GitHub, not a code change.
+
+### What GitHub documents (settled from its docs, 2026-11-05; no spike)
+
+1. **A user token with Repository creation, and without Administration, can create an organization repository.**
+ `POST /orgs/{org}/repos` is listed under the *Repository creation* repository permission, for both user access
+ tokens and installation access tokens
+ ([Permissions required for GitHub Apps](https://docs.github.com/en/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28),
+ "Repository permissions for Repository creation"). A user token succeeds only where the person may also do it
+ ([Choosing permissions for a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app):
+ "The success of an API request with a user access token depends on the user's permissions as well as the app's
+ permissions"), and the person must be a member of the organization
+ ([Create an organization repository](https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#create-an-organization-repository)).
+ The permission was added on 2026-10-13
+ ([GitHub changelog](https://github.blog/changelog/2026-10-13-github-app-improvements-for-least-privilege-and-management/)),
+ and an organization owner still approves it.
+2. **The app gets access to repositories it creates, even on *Only select repositories*.** "Your app is automatically
+ given access to repositories it creates"
+ ([Choosing permissions](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app));
+ "If the app creates any repositories, the app will automatically be granted access to those repositories as well"
+ ([Installing your own GitHub App](https://docs.github.com/en/apps/using-github-apps/installing-your-own-github-app));
+ "When the repository is created, the app or user that created it will be given access to it" (changelog above).
+ The docs don't say outright whether this holds when the app acts through a person's user token. So after creating,
+ Harness checks the installation covers the repository, and adds it or says F7 when it doesn't.
+3. **The person's user token can add a repository to the installation.**
+ `PUT /user/installations/{installation_id}/repositories/{repository_id}` is listed under *GitHub App installation
+ repository access* for user access tokens and installation tokens (permissions page above). "If the caller is a
+ user, they must also be an organization owner or an administrator on the repository in question" (changelog above),
+ and the creator is the new repository's administrator.
+
+**Left to confirm live:** once Ken adds Repository creation to our app and autonomous-ai accepts it, one real New
+repository run on a throwaway name confirms (1) and (2) against GitHub. It is listed in the pull request.
+
+### After the security reviews (2026-11-05)
+
+- **The callback claims the ask before it uses GitHub's code.** One write turns `waiting` into `creating`. A replayed or
+ doubled callback then finds nothing to claim and shows "This link has expired". It never writes over the outcome of
+ the callback that is still running. The outcome is written only over that `creating` ask.
+- **The repository is allowed for the project only once its outcome is recorded on the project.** A project deleted, or
+ an ask replaced, while GitHub was creating gets no approval.
+- **Who may is checked before any call signed with the app's key**, and organization checks are limited to 30 a minute
+ per person, on both routes.
+- **Create states are signed with a key of their own**, derived from the app's key under its own label, apart from
+ approval states.
+- **A revoke GitHub didn't confirm is logged**, never with the token.
+- **Known limit, shared with today's repository approval:** the callback is not tied to the browser that started it.
+ Whoever opens the 10-minute link signs in with their own GitHub. They become the creator, and the approval names them.
+ Here the worst case is a new empty repository in an organization they can create in. Binding the callback to the
+ starting browser should be a separate task on the shared callback.
+
+### Who may use it (Harness side)
+
+- **People only.** The backend refuses an agent (`HUMAN_REQUIRED`), as `project.create` and `lead.start` do. No PM or
+ Engineer creates repositories.
+- **Any member who may create a project in this Swarm** may start the flow. GitHub then decides whether they may create
+ in that organization (above).
+- **The organization is one the Swarm already uses**: the owners of the GitHub repositories its projects use, most
+ recently active first, and only those where the app is installed. The person may type another organization name.
+ GitHub still checks it, and the app must be installed there.
+- **v1 creates in organizations only.** A personal account (`github.com/<you>/...`) keeps today's way: create it on
+ GitHub, paste the link. Nobody asked for it, and an app user token cannot target a personal account the app is not
+ installed on.
+
+### What is created
+
+`POST /orgs/{org}/repos` with `{ name, private: true unless the person switched it off, auto_init: true }`. `auto_init`
+makes the first commit (a README), because a repository with no commit cannot be cloned into a worktree (task #3211
+refuses one). Nothing else is set: no team, no template, no branch rules. The organization's own rulesets apply (the
+"require pull requests on the default branch" step in docs/swarm-github-app.md still matters, and New repository does
+not set it).
+
+## How it flows
+
+```
+ Phone / Desktop Harness backend GitHub
+ ─────────────── ─────────────── ──────
+ Create ──► project.create ─────► project made (no PM yet)
+ ──► POST .../github/repository {owner, name, private}
+ checks: person, project, name rules,
+ app installed on owner, permission
+ accepted ──► signed state (10 min)
+ ◄── authorizeUrl
+ opens browser ──────────────────────────────────────────────────────► sign-in (one tap if
+ already allowed)
+ /api/github/callback ◄──────────────── code + state
+ user token ──► POST /orgs/{owner}/repos ─►
+ ──► add to installation (select installs)
+ ──► revoke token
+ approval recorded; the project's
+ repositoryCreation: created
+ page: "acme/notes is ready. Go back to Harness."
+ back in the app: the Swarm state
+ brings repositoryCreation ◄── {state: created, repositoryUrl}
+ ──► lead.start {repositoryUrl} (as today)
+ ──► project.rename (as today)
+```
+
+The sheet stays open while the browser is out. The outcome comes back in the Swarm state the app already syncs (the
+project's `repositoryCreation`), so nothing polls. **Check again** re-reads the state if the sheet missed it.
+
+## Failure states
+
+Every one is shown in the sheet in plain words. None of them leaves a half-made project silently: the project from
+`project.create` exists, and the sheet's existing "The project is made. Its Product Manager didn't start: …" line
+covers it, with **Try again**.
+
+| # | When | Where it's caught | What the person sees |
+| --- | --- | --- | --- |
+| F1 | Name breaks GitHub's rules (not letters, digits, `-`, `_`, `.`; over 100; `.` or `..`) | In the sheet, as they type | "Use letters, numbers, - _ or . (up to 100)." Create stays off. |
+| F2 | Name already taken in that organization | GitHub's 422 at create | Back in the sheet: "acme/notes already exists. Choose another name, or pick it under Repository to use it." The name field is focused. |
+| F3 | GitHub says the person may not create repositories there (not a member, owners only, private not allowed) | GitHub's 403/422 at create | "GitHub didn't let you create a repository in acme: *GitHub's reason*. Ask an owner of acme, or create it on GitHub and pick Enter a link." |
+| F4 | Harness isn't installed on that organization | Backend, before sign-in | "Harness isn't on acme's GitHub yet." **Install on GitHub** (the install link, as Project details offers today) and **Copy message** for an owner. |
+| F5 | Installed, but the organization hasn't accepted the new permission | Backend, before sign-in (installation's granted permissions, read as for Workflows today) | "An owner of acme needs to accept Harness's new permission once: GitHub Settings → GitHub Apps → Harness." **Copy message**. |
+| F6 | Server has no app sign-in configured (`GITHUB_APP_CLIENT_ID`/`SECRET` unset) | Backend | The New repository choice isn't shown. |
+| F7 | Created, but couldn't be added to a *select repositories* installation (Option B, or GitHub refused) | At create | "acme/notes is made, but Harness can't reach it yet. An owner of acme adds it under Settings → GitHub Apps → Harness → Configure." **Copy message**, **Check again**. The project keeps the address, and the PM starts once it's reachable. |
+| F8 | Person cancels sign-in, or the link is over 10 minutes old | Callback | "Nothing was created." Back in the sheet: **Try again**. |
+| F9 | Network, or GitHub is down | Backend call | "GitHub didn't answer. Nothing was created." **Try again**. |
+| F10 | Create succeeded but Harness lost the answer (timeout, server restart) | Next try | Try again finds the name taken by a repository this person created through Harness in the last 10 minutes. That counts as created, not F2. |
+| F11 | Project deleted while they were in GitHub | Callback, before creating | "The project was deleted meanwhile. Nothing was created." The callback checks the ask is still current before it calls GitHub. A newer ask makes an older link read as expired, and nothing is created. |
+| F12 | Swarm paused, no machine for the PM | Sheet, before anything is created (existing checks) | The existing blocked notes. Nothing is created on GitHub. |
+
+## Mockups
+
+### Phone: Repository subpage gets a "New repository" row
+
+```
+ ‹ Back Repository
+ ┌───────────────────────────────────────────┐
+ │ ⑂ openharness ✓ │
+ │ github.com/autonomous-ai/openharness │
+ │ ⑂ website │
+ │ github.com/autonomous-ai/website │
+ ├───────────────────────────────────────────┤
+ │ + New repository › │ new
+ │ 🔗 Enter a link › │
+ └───────────────────────────────────────────┘
+```
+
+### Phone: New repository subpage
+
+```
+ ‹ Back New repository
+ ┌───────────────────────────────────────────┐
+ │ Owner autonomous-ai › │ the Swarm's org; list if more than one
+ ├───────────────────────────────────────────┤
+ │ Name │
+ │ ┌───────────────────────────────────────┐ │
+ │ │ notes-app │ │
+ │ └───────────────────────────────────────┘ │
+ │ github.com/autonomous-ai/notes-app │
+ ├───────────────────────────────────────────┤
+ │ Private [●━] │ on by default
+ │ Only people with access on GitHub see it │
+ └───────────────────────────────────────────┘
+ GitHub asks you to confirm, then Harness
+ creates it with you as its admin.
+
+ [ Use this name ]
+```
+
+### Phone: the sheet after choosing it
+
+```
+ New project ✕
+ ┌───────────────────────────────────────────┐
+ │ What should this project work on? │
+ │ A notes app with sync… │
+ └───────────────────────────────────────────┘
+ ┌───────────────────────────────────────────┐
+ │ Visibility Private › │
+ │ Repository New · notes-app ✦ › │
+ │ autonomous-ai/notes-app │
+ │ PM runs on Mac Studio › │
+ │ Agent Claude Code · Opus 5.5 › │
+ └───────────────────────────────────────────┘
+ [ Create and continue in GitHub ]
+```
+
+While out in GitHub, and on coming back:
+
+```
+ [ Creating autonomous-ai/notes-app… ] then the usual
+ Check again "Starting the PM…"
+```
+
+A failure replaces the button's note line, for example F2:
+
+```
+ autonomous-ai/notes-app already exists. Choose another
+ name, or pick it under Repository to use it.
+ [ Try again ]
+```
+
+### Desktop: "Choose repo" menu gets a "New Repository" row
+
+```
+ [Agent ▾] [💻 Mac Studio ▾] [📁 Choose repo ▾] ✕
+ ┌──────────────────────────────────────────┐
+ │ 🔍 Search repos │
+ ├──────────────────────────────────────────┤
+ │ 📂 Open Folder │
+ │ Enter a path or browse folders │
+ │ + New Folder │
+ │ Name a new folder │
+ │ ⑂ Clone Repository │
+ │ Paste a GitHub repository URL │
+ │ ✦ New Repository │ new
+ │ Create one on GitHub │
+ ├──────────────────────────────────────────┤
+ │ recent folders… │
+ └──────────────────────────────────────────┘
+```
+
+### Desktop: New Repository prompt (same style as the Clone repository prompt)
+
+```
+ ┌ New repository ─────────────────────────────────────────┐
+ │ Owner [ autonomous-ai ▾ ] Name [ notes-app ] │
+ │ ☑ Private │
+ │ ✦ Create autonomous-ai/notes-app · you confirm in GitHub │
+ └──────────────────────────────────────────────────────────┘
+```
+
+### Desktop: the composer after choosing it
+
+```
+ [Agent ▾] [💻 Mac Studio ▾] [✦ autonomous-ai/notes-app · new ▾] ✕
+ ┌──────────────────────────────────────────────────────────────────┐
+ │ What would you like to work on? │
+ │ A notes app with sync… │
+ │ 📎 [Private ▾] [ Continue in GitHub ] │
+ └──────────────────────────────────────────────────────────────────┘
+ Creates autonomous-ai/notes-app on GitHub, then clones it on Mac Studio
+```
+
+Both apps follow the Harness design language (`docs/naming-system.md`, the existing sheets' rows and prompts). Light
+and dark screenshots of each changed screen come with the pull request.
+
+## Design
+
+- **Growth**: one small `repositoryCreation` object on the project in the Swarm state (owner, name, private, who,
+ when, outcome), replaced by the next attempt and deleted with the project. One `GitHubRepositoryApproval` row per
+ created repository (an existing collection), deleted with its project or Swarm as today. The user token is never
+ stored.
+- **Concurrency**: GitHub's unique name per organization is the lock. Two creates of the same name: one gets 201, the
+ other F2 (or F10 if it is the same person's retry). The outcome is written in one Swarm-state transaction, and only
+ over the waiting request it answers (same person, same time), so a late callback never overwrites a newer attempt.
+ The approval row's existing unique index makes recording it idempotent.
+- **Read cost**: no new read. The outcome arrives with the Swarm state the apps already sync. Checking an organization
+ (F4, F5) is one small read when the person picks it, using the installation lookups the server already caches for 10
+ minutes. Organization choices come from repositories the client already has.
+- **Scale (10x)**: creation is a rare, person-paced action (a few a day). The first metric to warn is GitHub's
+ secondary rate limit on content creation per user. Repository creation is far below it. Each create uses at most
+ four GitHub calls on the person's own quota, plus the installation lookup that is already cached for 10 minutes.
+- **Compatibility**: two new endpoints, one new optional project field and a new menu row. Old apps ignore the field,
+ don't show the row, and keep paste and clone. A new app on an old server gets 404 from the organization check and
+ hides the row. `lead.start` is unchanged.
+- **Migration and rollback**: no data migration. Rollback is the previous backend (endpoint gone, so the apps hide the
+ row). Repositories already created stay on GitHub, as if made there. The GitHub-side permissions can be removed from
+ the app's settings at any time.
+- **Audience**: the server checks that the caller is a person who may read the project and that the state's signature
+ binds person, Swarm, project, owner and name. GitHub enforces who may create in the organization.
+- **Identity**: the person's own GitHub sign-in through the app, never the machine owner's git login and never an
+ installation token.
+- **Failure**: every state in the table above is said in the sheet. A created repository is never deleted by Harness.
+- **Platforms**: phone (iOS, Android) and Desktop (macOS, Windows, Linux). Opening GitHub uses the system browser
+ everywhere. On Windows the browser opens through the existing link launcher, so no console window ever flashes
+ (Windows rule 1).
+
+## Checks this design will need
+
+- Two independent security reviews (sign-in, tokens, access: the two-review rule) and a PM read.
+- A Reviewer for the design PR, then for the code PR.
+- A Tester: phone in the simulator, Desktop on a Mac, against a test organization (not autonomous-ai).
diff --git a/docs/plans/2026-11-05-new-repository-plan.md b/docs/plans/2026-11-05-new-repository-plan.md
new file mode 100644
index 000000000..f8baf8c1c
--- /dev/null
+++ b/docs/plans/2026-11-05-new-repository-plan.md
@@ -0,0 +1,211 @@
+# New Project can create a new GitHub repository (task #1788) Plan
+
+> Worked by the Engineer, test first (superpowers test-driven-development): each task's failing test is committed and
+> seen red before the code that passes it. Tasks 1 to 6 are the backend (this pull request). Tasks 7 and 8 are the
+> phone and Desktop. They share no files with the backend and only the contract in Task 6, so they can run in parallel
+> on machines with Flutter.
+
+**Goal:** New Project offers "New repository": the person names it, it is created private in an organization the
+Swarm uses, through their own GitHub sign-in, and the project's Product Manager starts in it.
+
+**Architecture:** The backend creates the repository in the existing app sign-in callback, with the person's short-lived
+user token, and never with an installation token. The outcome is written on the project in the Swarm state
+(`repositoryCreation`), so the apps learn it from the state they already sync. On `created`, the app sends today's
+`lead.start` with the new address. Installation tokens are pinned so they can never ask for creation permissions.
+
+**Tech Stack:** TypeScript backend (Fastify, Prisma/MongoDB, vitest, mongodb-memory-server integration). Flutter
+phone (`mobile/`) and Desktop (`desktop/`).
+
+**Spec:** `docs/plans/2026-11-05-new-repository-design.md`
+
+## Global Constraints
+
+- Administration is never requested. Installation tokens never carry `repository_creation` or
+ `installation_repositories`.
+- The user token is used for at most four calls and revoked in `finally`. It is never stored or logged.
+- People only: an agent is refused (`HUMAN_REQUIRED`). Only the project's owner starts it, and only while the project has
+ no repository address.
+- Created with `{ name, private, auto_init: true }`. Private by default.
+- Name rule: `^[A-Za-z0-9._-]{1,100}$`, and not `.` or `..`. Owner rule: `^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$`.
+- Organizations only in v1 (`/orgs/{owner}/installation`).
+- Harness never deletes a repository it created.
+- Copy follows the design's failure table (F1 to F12) word for word.
+- Swarm code stays out of `cli/src/core`.
+
+## Review Focus
+
+1. A late or replayed callback (second tab, back button) must not overwrite a newer attempt, or create twice: the outcome
+ is written only over the matching waiting request (same `by` and `at`). Task 5 tests it.
+2. A create state must never pass as an approval state, nor the reverse. Task 4 tests both.
+3. Name taken by a repository the same person just made through Harness (lost answer) reads as created, not F2. One
+ made by anyone else, or long ago, reads as F2. Task 4 tests it.
+4. The token is revoked even when GitHub throws mid-way. Task 3 tests a throwing callback.
+5. Owner names with mixed case (`Autonomous-AI` vs `autonomous-ai`) compare without case. Tasks 2 and 4 test it.
+
+---
+
+### Task 1: Installation tokens can never carry creation permissions
+
+**Files:** Modify `backend/src/github/app.ts` (`mint`). Test `backend/src/github/app.test.ts`.
+
+**Interfaces:** Produces `export const NEVER_ON_INSTALLATION_TOKENS = ['administration', 'repository_creation', 'installation_repositories'] as const`.
+
+- [ ] Test `installation tokens never ask for administration or repository creation`: for every exported `*_PERMISSIONS`
+ constant and `GRANTED_TOKEN_PERMISSIONS`, no key is in `NEVER_ON_INSTALLATION_TOKENS`. And `createToken(id, repo, { repository_creation: 'write' })`
+ rejects with code `GITHUB_APP_PERMISSIONS_FORBIDDEN`, with no call to `/access_tokens` made (fake GitHub `calls`).
+- [ ] Run `npx vitest run src/github/app.test.ts`, which fails on the missing export.
+- [ ] In `mint`, throw `GitHubAppError('GITHUB_APP_PERMISSIONS_FORBIDDEN', …, 500)` before calling GitHub when any asked
+ permission is in the list. Then run it green and commit.
+
+### Task 2: What an organization allows (`ownerReadiness`)
+
+**Files:** Modify `backend/src/github/app.ts`, `backend/src/github/fakeGitHub.ts` (nothing new; it already has `owners`
+and `grants`). Test `backend/src/github/app.test.ts`.
+
+**Interfaces:** Produces `GitHubApp.ownerReadiness(owner: string): Promise<OwnerReadiness>`, where
+`type OwnerReadiness = { state: 'ready'; installation: number; canAdd: boolean } | { state: 'not-installed'; installUrl: string | null } | { state: 'not-accepted' }`.
+
+- [ ] Test `says whether an organization lets Harness create repositories`:
+ - no `/orgs/{owner}/installation` gives `not-installed` with `installUrl` `https://github.com/apps/harness-fixture/installations/new`;
+ - installed, with grants lacking `repository_creation: 'write'`, gives `not-accepted`;
+ - with it gives `ready` and `canAdd: false`;
+ - also with `installation_repositories: 'write'` gives `canAdd: true`;
+ - `Example` and `example` read the same installation, asked once within ten minutes.
+- [ ] Run it red. Then implement with `/orgs/{owner}/installation` only (users are v1 not-installed), the private
+ `granted()` read, and an owner cache of `INSTALLATION_TTL_MS` (`NOT_INSTALLED_TTL_MS` for a missing one). Run it
+ green and commit.
+
+### Task 3: Run a callback's user token, then revoke it (`withUserToken`)
+
+**Files:** Modify `backend/src/github/approvals.ts`. Test `backend/src/github/approvals.test.ts`.
+
+**Interfaces:** Produces `type UserCall = (method: string, path: string, body?: unknown) => Promise<{ status: number; body: Record<string, unknown> }>`,
+and `GitHubSignIn.withUserToken<T>(code: string, use: (call: UserCall) => Promise<T>): Promise<T | null>`. Null when
+GitHub refuses the code. `permission()` is rebuilt on it, with unchanged behaviour.
+
+- [ ] Test `revokes the person's token after use, even when the use throws`: `withUserToken('c', async () => { throw new Error('x') })`
+ rejects with `x`, and the last call is `DELETE /applications/Iv23client/token`. A refused code gives `null`, with
+ no API call. The existing `permission` tests still pass.
+- [ ] Run it red, implement, run `src/github/approvals.test.ts` green, and commit.
+
+### Task 4: Create the repository (`repositoryCreate.ts`)
+
+**Files:** Create `backend/src/github/repositoryCreate.ts`. Test `backend/src/github/repositoryCreate.test.ts`.
+
+**Interfaces:**
+- Consumes `UserCall` (Task 3), `GitHubApp.ownerReadiness` and `GitHubApp.installation` (Task 2), `stateSecret` and `STATE_TTL_MS`.
+- Produces:
+ - `repositoryNameProblem(name: string): string | null` (F1 copy, or null);
+ - `interface CreateRequest { userId; autonomousEnv; tabId; projectId; owner; name; private: boolean; at: number }`;
+ - `signCreateState(secret, request, now): string` and `readCreateState(secret, state, now): CreateRequest | null`
+ (body carries `kind: 'create'`);
+ - `type CreateOutcome = { state: 'created'; repository: string; repositoryUrl: string; login: string; reachable: boolean } | { state: 'taken' } | { state: 'refused'; reason: string } | { state: 'failed' }`;
+ - `createRepository(call: UserCall, app: GitHubApp, request: CreateRequest): Promise<CreateOutcome>`.
+- [ ] Tests, each with a scripted `UserCall` fake:
+ - `names follow GitHub's rule`: `notes-app`, `a.b_c` pass; `''`, `.`, `..`, `a b`, 101 characters fail.
+ - `a create state is not an approval state, nor the reverse`: `readState` of a create state is null, and
+ `readCreateState` of an approval state is null. The same expiry and forgery rules apply as for `readState`.
+ - `creates it private with a first commit, as the person`: POST `/orgs/acme/repos` gets body
+ `{ name: 'notes', private: true, auto_init: true }`. The result is `created`, with `repositoryUrl`
+ `https://github.com/acme/notes`, and `reachable: true` when `app.installation` finds it.
+ - `adds it to the installation only where that is granted`: not covered with `canAdd`: PUT
+ `/user/installations/91/repositories/{id}`, then `reachable: true`. Not covered without `canAdd`: no PUT, and
+ `reachable: false` (F7).
+ - `a name taken by someone else is taken; the same person's create since the request is created`: on 422 "name already
+ exists", GET `/repos/acme/notes` with `permissions.admin` and `created_at` ≥ `request.at` gives `created`. Otherwise
+ `taken`.
+ - `GitHub's refusal is said in its words`: 403 `{ message: 'You need admin access…' }` gives `refused` with that
+ message cut to 300 characters. A 5xx or a throw gives `failed`.
+- [ ] Run them red, implement, run them green, and commit.
+
+### Task 5: The project's `repositoryCreation` in the Swarm state
+
+**Files:** Modify `backend/src/superTabs/projects.ts` (type), `backend/src/superTabs/store.ts`. Test:
+`backend/integration/superTabGithub.test.ts` (the store needs MongoDB).
+
+**Interfaces:** Produces:
+- `interface RepositoryCreation { owner: string; name: string; private: boolean; by: string; at: number; state: 'waiting' | 'created' | 'taken' | 'refused' | 'failed' | 'cancelled'; repositoryUrl?: string; reachable?: boolean; reason?: string }`
+ on `SwarmProject.repositoryCreation?`;
+- `store.startRepositoryCreation(user, tabId, projectId, ask: { owner; name; private }, at: number): Promise<void>`. It
+ refuses an agent (`HUMAN_REQUIRED`), a non-owner (`PROJECT_OWNER_REQUIRED`), and a project with an address
+ (`PROJECT_REPOSITORY_SET`);
+- `store.finishRepositoryCreation(tabId, projectId, by: string, at: number, outcome: Omit<RepositoryCreation, 'owner' | 'name' | 'private' | 'by' | 'at'>): Promise<'recorded' | 'stale' | 'gone'>`.
+ It moves `githubRevision`.
+- [ ] Tests (in the route suite, Task 6): `waiting` then `created` shows on the project. A finish for an older `at`
+ is `stale` and changes nothing. A deleted project is `gone`.
+- [ ] Red, implement, green, commit (with Task 6's suite).
+
+### Task 6: Routes (the contract the apps use)
+
+**Files:** Modify `backend/src/routes/superTabs.ts`. Test `backend/integration/superTabGithub.test.ts`.
+
+**Contract:**
+- `GET /api/super-tabs/:tabId/github/owners/:owner` (a person who reads the Swarm) gives
+ `{ state: 'ready' | 'not-installed' | 'not-accepted' | 'not-configured', installUrl?: string }`. `not-configured`
+ means the server has no app or no sign-in (F6: hide the choice).
+- `POST /api/super-tabs/:tabId/projects/:projectId/github/repository` with body `{ owner, name, private }` gives
+ `{ authorizeUrl, at }`. The errors are `REPOSITORY_NAME` (400, F1 copy), `GITHUB_APP_NOT_INSTALLED` (409, with
+ `installUrl`, F4), `GITHUB_APP_PERMISSIONS` (409, F5), `GITHUB_APP_NOT_CONFIGURED` / `GITHUB_APPROVAL_NOT_CONFIGURED`
+ (503), and the store's refusals.
+- `GET /api/github/callback` reads a create state first. Its pages are:
+ - created: "owner/name is ready. Go back to Harness.";
+ - taken: F2;
+ - refused: F3;
+ - cancelled or expired: F8;
+ - failed: F9;
+ - project gone: F11.
+
+ On created it also approves the repository for the project (`approvals.approve`, scope `project`).
+- [ ] Tests, with the stub sign-in exposing `withUserToken` over the fake GitHub, which gains
+ `POST /orgs/:org/repos`, `GET /repos/:o/:n` for user tokens and `PUT /user/installations/:id/repositories/:rid`:
+ - `the owner creates a new repository for their new project and its PM can start in it`: POST, then callback, then the
+ project's `repositoryCreation` is `created` with the URL, the approval is recorded, and `lead.start` with that URL
+ succeeds;
+ - `another member, an agent, or a project with a repository can't start it`;
+ - `each organization state is said before sign-in` (F4, F5, F6);
+ - `cancel, a taken name and GitHub's refusal come back to the app` (F8, F2, F3 as `repositoryCreation` states);
+ - `a second callback for an older request changes nothing` (Review Focus 1).
+- [ ] Red, implement, run `npx vitest run --config vitest.super-tabs.config.ts integration/superTabGithub.test.ts` green,
+ update `docs/swarm-github-app.md` (permission row, the two endpoints, the callback's create pages), and commit.
+
+### Task 7: Phone (`mobile/`, on a machine with Flutter: Tony's Mac per Routing)
+
+**Files:** `mobile/lib/swarm/swarm_new_project_sheet.dart`, a new `mobile/lib/swarm/swarm_new_repository.dart` (the
+subpage and its state), `mobile/lib/swarm/model.dart` (parse `repositoryCreation`). Tests:
+`mobile/test/swarm/swarm_new_project_test.dart`, `swarm_new_project_shots_test.dart`.
+
+**Consumes:** Task 6's contract. The outcome is on the project row as `repositoryCreation`.
+
+- [ ] Tests first:
+ - the Repository subpage lists "New repository" above "Enter a link" only when the owner check is not
+ `not-configured`, and a 404 hides it;
+ - the subpage's owner list is the distinct GitHub owners of `swarmProjectRepositories`, most recent first, the first
+ chosen;
+ - Private is on by default;
+ - F1 copy shows while typing, and "Use this name" stays off;
+ - F4 and F5 copy shows after the owner check, with Copy message;
+ - Create sends `project.create`, then `message.send`, then the POST, opens `authorizeUrl` in the system browser, and
+ shows "Creating owner/name…" with Check again;
+ - on `repositoryCreation.state == 'created'` with this `at`, it sends `lead.start` with `repositoryUrl`, then
+ `project.rename` to the name;
+ - `taken`, `refused`, `failed` and `cancelled` show F2, F3, F9 and F8 with Try again;
+ - `reachable: false` still starts the PM and shows the F7 line;
+ - light and dark shots of the subpage and the sheet.
+- [ ] Implement to the design's phone mockups, run those test files green, and commit.
+
+### Task 8: Desktop (`desktop/`, on a Mac with Flutter)
+
+**Files:** `desktop/lib/state/new_harness.dart` (a "New Repository" row and its prompt state),
+`desktop/lib/widgets/new_harness_form.dart` (prompt UI and chip), `desktop/lib/super_tabs/launch.dart` (the create
+flow), `desktop/lib/super_tabs/model.dart` (parse `repositoryCreation`). Tests: `desktop/test/new_harness_form_test.dart`,
+`desktop/test/new_agent_rows_and_task_test.dart`.
+
+- [ ] The same tests as Task 7, Desktop-shaped:
+ - the "New Repository" / "Create one on GitHub" row in Choose repo, for a new project only;
+ - the prompt with Owner, Name and Private on;
+ - the chip "owner/name · new";
+ - the button reads "Continue in GitHub";
+ - the note "Creates owner/name on GitHub, then clones it on <machine>";
+ - the same outcome handling, opening the browser through the existing link launcher (no console window on Windows);
+ - light and dark shots.
+- [ ] Implement, run those test files green, and commit.
diff --git a/docs/plans/2026-11-05-route-details-grouping-plan.md b/docs/plans/2026-11-05-route-details-grouping-plan.md
new file mode 100644
index 000000000..da7ef5092
--- /dev/null
+++ b/docs/plans/2026-11-05-route-details-grouping-plan.md
@@ -0,0 +1,75 @@
+# Route Details groups what couldn't start (task #3292) Plan
+
+> Worked by the Engineer, test first (superpowers test-driven-development): each task's failing test is committed and
+> seen red before the code that passes it.
+
+**Goal:** A route decision's Details on Desktop shows the candidates first, then one line per machine for what couldn't
+start there, with its distinct reasons, and a route rule that left out candidates on several machines (the grid limit
+for security work) once for the whole decision, instead of one "Unavailable" line per machine × agent × model.
+
+**Architecture:** Desktop only. The record's excluded rows (`cli/src/superTabs/route.ts` `recordOf`) keep `title` and
+`reason`; the title is the CLI's `titleOf` ("name · engine model effort · machine"), which `route_row.dart` already
+parses for the route's target. A pure function in `route_row.dart`, `_unavailableLines`, groups the rows:
+
+1. A row's machine is the title's last part when the title has the `titleOf` shape; other rows ("Named model",
+ "Local models", "New agents", a model whose host is offline) have none.
+2. A "Name: …" reason (how `route.ts` prefixes a plug-in's refusal) on rows of two or more machines is said once,
+ naming those machines: "Unavailable on Mac 3, Gray.local and Kay.local — Grid limits: …", past three "and N more
+ machines". Some machine facts read the same ("Required tool missing: git."), so the line always says where
+ (review of #3167).
+3. Every other reason goes on its machine's one line, distinct reasons in first-seen order, at most four and then how
+ many more (as the CLI's `leftOut` keeps at most four): "Unavailable: Mac 3 — Machine is offline or unreachable."
+ A machine whose every reason was a rule's has no line of its own.
+4. Rows with no machine stay one line each, once per distinct title and reason.
+
+Unlike `leftOut`, which lists only machines none of whose candidates was offered, Details keeps the line of a machine
+that also offered candidates: Details shows the whole decision, the PM's answer only why a machine was never offered.
+
+No shared helper with the CLI: Dart and TypeScript share no code, and the CLI's `leftOut` needs the `machine` field the
+record does not keep (adding it would change `recordOf` and the backend's strict record schema, outside this task).
+The dialog keeps its layout: the same lines of text under "Considered", fewer of them. There is no expand for the
+excluded rows today, so there is none to keep them behind; the full rows stay in the decision record (the CLI's
+`route-decisions` read).
+
+**Tech Stack:** Flutter/Dart, `flutter_test` widget tests with the existing `ConversationServer` fixture (memory store,
+fake sign-in).
+
+**Spec:** task #3292 brief (Ken, 11-05 17:25 VN).
+
+## Global Constraints
+
+- Owned files only: `desktop/lib/super_tabs/route_row.dart`, `desktop/test/` (and this plan).
+- Keep the Details layout (anh Dee's rule): plain text lines, candidates first.
+- Desktop tests use a memory store and a fake sign-in; nothing signs the Mac out of the real CLI.
+- `make check-ui-style` (or its Desktop equivalent) and the affected Desktop tests before Ready.
+
+## Design
+
+N/A because nothing is stored, synced or exposed anew: Desktop groups, at display time, rows it already reads (at most
+200, `recordOf`). Read cost is one pass over those rows; old records group the same (their titles have the same shape,
+and a title of another shape is shown as it was). Platforms: the same Flutter text on macOS, Windows, Linux and web.
+
+## Review Focus
+
+- A machine name containing " · " (the regex takes the last part as the machine, as `_target` does).
+- A rule reason on one machine stays on that machine's line; the same rule on two machines is lifted once.
+- OFFLINE ("Machine is offline or unreachable.") is the same text on every offline machine: it is no rule (no "Name: "
+ prefix), so two offline machines keep a line each.
+
+## Task 1: Group the excluded rows
+
+**Files:** `desktop/test/super_tab_route_test.dart`, `desktop/lib/super_tabs/route_row.dart`
+
+**Interfaces:** `List<String> _unavailableLines(Iterable<Map<String, dynamic>> excluded)` in `route_row.dart`.
+
+- [ ] Test: an offline machine with 17 excluded rows (17 models, the same OFFLINE reason) shows as one line,
+ "Unavailable: Mac 3 — Machine is offline or unreachable.", and the Considered lines come before it.
+- [ ] Test: the security grid limit on grid candidates of three machines (about 30 rows) shows once per decision, and
+ those machines get no line of their own for it.
+- [ ] Test: two offline machines keep a line each; a machine with five distinct reasons shows four and "1 more";
+ rows with no machine ("Named model") show once each.
+- [ ] Run `flutter test test/super_tab_route_test.dart`: the new tests fail (each row is printed).
+- [ ] Commit the failing tests.
+- [ ] Implement `_unavailableLines` and use it in `_detailsView`.
+- [ ] Run `flutter test test/super_tab_route_test.dart` and the UI style check: green.
+- [ ] Commit, push, post red/green evidence in a PR comment, mark Ready.
diff --git a/docs/swarm-github-app.md b/docs/swarm-github-app.md
index ef295a96c..69457f59f 100644
--- a/docs/swarm-github-app.md
+++ b/docs/swarm-github-app.md
@@ -95,6 +95,45 @@ runs in CI with the repository's secrets, so a branch an agent pushes can run co
with them; the default branch's pull request rule (below) still keeps such a change
from reaching the default branch unreviewed.
+### New repositories from New Project
+
+New Project's **New repository** creates a project's repository in an organization
+(`docs/plans/2026-11-05-new-repository-design.md`). It needs one more repository
+permission on the app: **Repository creation: Read and write**. Never grant
+**Administration**: it also lets a token delete or transfer repositories.
+
+1. On the app's settings page (**Permissions & events**), set **Repository creation**
+ to **Read and write** and click **Save changes**. The server's sign-in settings
+ (`GITHUB_APP_CLIENT_ID` and `GITHUB_APP_CLIENT_SECRET`, step 4) must be set.
+2. An owner of each organization accepts it: **Settings → GitHub Apps → Configure →
+ Accept new permissions**. Until then, New Project says so for that organization.
+
+The repository is created with the person's own sign-in token through the app, never an
+installation token. So GitHub decides whether they may create repositories in that
+organization, and they become the repository's admin. Harness refuses to mint any
+installation token that asks for `administration`, `repository_creation` or
+`installation_repositories` (`NEVER_ON_INSTALLATION_TOKENS` in
+`backend/src/github/app.ts`). GitHub gives the app access to repositories it creates, on
+either kind of install. If an installation also grants **GitHub App installation
+repository access**, Harness adds a new repository that the installation doesn't cover
+yet. Otherwise the person is told that an owner of the organization adds it under
+**Configure**. The new repository is allowed for the project in the same step.
+
+The endpoints:
+
+- `GET /api/super-tabs/:tabId/github/owners/:owner` answers `ready`, `not-installed` (with
+ `installUrl`), `not-accepted` or `not-configured`. Organization checks are limited to 30 a
+ minute per person, on both routes (`RATE_LIMITED`, 429).
+- `POST /api/super-tabs/:tabId/projects/:projectId/github/repository` takes
+ `{ owner, name, private }`. Only the project's owner may call it, while the project has
+ no repository. It answers `{ authorizeUrl, at }`.
+- GitHub sends the person back to `/api/github/callback`. The callback creates the
+ repository and writes the outcome on the project as `repositoryCreation`. While it runs, the state is `creating`, and a
+ replay of the same link changes nothing. The outcome is `created`
+ (with `repositoryUrl` and `reachable`), `taken`, `refused` (with GitHub's `reason`),
+ `failed` or `cancelled`. The apps then start the Product Manager with today's
+ `lead.start`.
+
### 3. Require pull requests on the default branch
A token that can write contents can push straight to any branch that nothing