The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
Merge batch 11-05 i2205: #3167 #3202 #3201 (#3206)
0xken158255ad7ecea7
diff --git a/backend/integration/superTabGithub.test.ts b/backend/integration/superTabGithub.test.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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): ApprovalRexport 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_tokenif (!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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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, typeimport 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?: Suconst 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?: Suconst 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?: Suconst 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()) : nullif (!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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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, beforereturn { 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 stepdiff --git a/backend/src/superTabs/store.ts b/backend/src/superTabs/store.tsindex 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.dartindex 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.dartindex 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdindex 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 cowith them; the default branch's pull request rule (below) still keeps such a changefrom 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 branchA token that can write contents can push straight to any branch that nothing