Skip to content

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

57.8 KB
Raw Blame
import { createHash } from 'node:crypto'
import { activeWork, agent, agentRole, author, conversation, fail, isLeads, leadsRemoved, nextConversationNumber, person, type Actor, type Agent, type AgentStart, type AgentStartRequest, type Conversation, type Person, type SuperTabState } from './model.js'
import type { SwarmRule } from './rules.js'
import { buddyReads, isBuddy, isBuddyChat, isSwarmBuddy, isSwarmBuddyChat } from './buddies.js'
import { agentWrittenNameOf } from './personNames.js'

export type ProjectVisibility = 'public' | 'private'
/** Which built-in skill texts the project's agents get: Default (the team process only) or today's Harness orchestration. */
export type SkillMode = 'default' | 'orchestration'
/** What new clients read: a built-in mode, or the project's own custom role set. */
export type SkillSet = SkillMode | 'custom'
export const SKILL_SET_NAMES: Record<SkillSet, string> = { default: 'Default', orchestration: 'Harness orchestration', custom: 'Custom' }
export type RoleKind = 'lead' | 'builder' | 'reviewer'
/** A role of a project's custom set as the tab state keeps it. Its text lives outside the state (store.ts roleText), so a
 *  roster or tab read never carries up to 20 x 64 KB of skill text; `version` names the text. */
export interface ProjectRole { id: string; name: string; kind: RoleKind; version: string; defaults?: RoleDefaults }
/** What an agent of a role starts on when its start names no model: an engine, and on it a model and effort. */
export interface RoleDefaults { engine: 'claude' | 'codex'; model?: string; effort?: string }
/** The coordinator's first start runs Claude Opus 5.5 at xhigh when its person names no model (Scholes's roadmap, piece 1,
 *  10-30): the project's instructions cannot choose a model before any agent reads them. No other start takes a default now;
 *  routing lives in the instructions (project instructions, phase 4). */
export const BUILT_IN_ROLE_DEFAULTS: Partial<Record<RoleKind, RoleDefaults>> = { lead: { engine: 'claude', model: 'opus', effort: 'xhigh' } }

/** [request] with its role's [defaults] filled in when it names no model, on the defaults' engine alone; a named effort is kept. A
 *  grid model chooses its own. */
export function withRoleDefaults<T extends { engine: string; model?: string; effort?: string; gridModel?: string }>(request: T, defaults: RoleDefaults | undefined): T {
  if (!defaults || request.model || request.gridModel || defaults.engine !== request.engine || !defaults.model) return request
  const effort = request.effort ?? defaults.effort
  return { ...request, model: defaults.model, ...(effort ? { effort } : {}) }
}
export const MAX_ROLES = 20
export const roleVersion = (text: string): string => createHash('sha256').update(text).digest('hex').slice(0, 16)
export interface SwarmProject {
  id: string
  name: string
  /** What the project is, in one line (at most 80 characters), set by its owner or Lead (project.about, task #4540): the Cmd-N
   *  and join project list shows it. Absent shows the repository's name. */
  about?: string
  /** The owner's id; '' for a private project whose owner left with no member left to take it (settleOwners): nobody's. */
  ownerId: string
  /** The owner's membership generation when they became its owner (task #3073): the same account at a later membership
   *  owns nothing, as a member's listing works. Absent on projects from before 2026-11-05 until settleOwners fills it; until
   *  then the owner matches by id, as before. */
  ownerGeneration?: string
  leadConversationId: string
  /** Public means every member of this swarm, never anonymous internet access. */
  visibility: ProjectVisibility
  members: Array<{ id: string; generation: string }>
  updateMinutes: 1 | 5 | 15 | 30
  /** The project's board and work process; absent on older projects, which keep Full (task #3896). */
  process?: import('./process.js').ProjectProcess
  /** Tasks up to this number stay Simple after returning to Full. One watermark covers dormant tasks and repeated
   *  switches without loading or rewriting any task history; absent until the first Simple→Full switch (#3896). */
  simpleThrough?: number
  /** The morning digest (digest.ts): its local time ("08:00") and zone, and the local date and time of the last one sent.
   *  On by default: a project without one gets the default on its coordinator's next poll, unless a person turned it off. */
  digest?: { time: string; timeZone: string; lastOn?: string; lastAt?: number }
  /** A person turned the digest off (project.digest with time null), so the default is not filled in again. */
  digestOff?: true
  /** The last 30-minute slot of the built-in PM schedule in which its coordinator's poll found something to sweep
   *  (pmSchedule.ts), woken or held back, and the message that last carried a wake (its own, an update request or a notice
   *  digest): no new wake while that one is unread. A slot with nothing to sweep is not written. Readers never get it.
   *  `heardAt`: when the last wake asked it to save what people taught it; `tidiedOn` and `tidiedRevision`: the local date
   *  the daily tidy was last asked, and the instructions revision its last save made; `tidyPending`: asked, and no save has
   *  followed yet (pmSchedule.ts tidyRequest; tasks #3022, #3151). */
  schedule?: { lastSlot: number; wakeId?: string; heardAt?: number; tidiedOn?: string; tidiedRevision?: number; tidyPending?: boolean }
  /** The Board way of working (boardRights.ts, task #3819): `boardMode` true once its owner switched it on, absent otherwise;
   *  `canChat` the people its owner granted the right to write in its chat (its owners always have it); `decider` its top
   *  decider, who sets P0 and pauses as its owners do. Every reader of the project reads them. */
  boardMode?: true
  canChat?: string[]
  decider?: string
  /** The what-changed note for PMs (processNotes.ts, task #3581) its PM was last woken for, and the newest it confirmed. */
  processNote?: { told?: string; confirmed?: string }
  /** The oldest message a person sent its PM in the last day that the PM has not answered, and when it was sent, as the worker's
   *  time checks last found it (timeChecks.ts owedAsk); absent when it owes none. Its PM's host restarts a PM that hangs while it
   *  owes one (task #3385). Readers never get it: it may name a message in a person's private chat with the PM. */
  owed?: { messageId: string; since: number }
  /** Its release list (releases.ts, task #3405): merged tasks waiting for a release, each component's last verified release
   *  and its open release step. Written by the server alone; readers never get it. */
  releases?: import('./releases.js').ReleaseLedger
  /** The status card at the top of the project chat (Dee, 2026-10-31): the coordinator's last project.report text, which
   *  replaces the one before and posts nothing. Read exactly by those who read the project chat (model.ts visibleState). */
  status?: ProjectStatus | null
  /** Report watermark per conversation (projectUpdates.ts); kept in its own part (store by parts). */
  progress?: import('./parts/types.js').ProgressData
  repository?: { machineId: string; cwd: string; repositoryUrl: string | null }
  /** Absent on projects from before skill modes, which keep the texts their agents already run. */
  skillMode?: SkillMode
  /** Absent before custom sets. While it is 'custom', skillMode stays 'default' so older clients run the Default text. */
  skillSet?: SkillSet
  /** The project's custom set, kept when the project switches away from it. */
  roles?: ProjectRole[]
  /** Its Product Manager started by the Swarm on one of its machines, or waiting for one (leadStart.ts). */
  lead?: import('./leadStart.js').LeadPlacement
  /** A Personal Swarm project chat with no Lead: its person's messages sent there, delivered to its Lead once it joins
   *  (leadStart.ts leadWaits). Ids and times only, at most MAX_LEAD_WAITING; cleared when a Lead joins. */
  leadWaiting?: Array<{ id: string; at: number }>
  /** The one start of its Lead a Desktop of its person's claimed (lead.claim), from [machineId]; cleared when a Lead joins. */
  leadClaim?: { id: string; machineId: string; at: number }
  /** What its chat was last told of new Reviewers (reviewCapacity.ts), under `any`: none can start, or they soon will not.
   *  Absent once a machine is usable again, so the next shortage is told. Per engine before 2026-10-30, never read since. */
  reviewCapacity?: Partial<Record<'any' | 'claude' | 'codex', 'out' | 'low'>>
  /** Its instructions' revision and short hash (instructions.ts): the text lives outside the state. Absent on a project
   *  from before instructions until the migration writes its document; it runs on the built-in template meanwhile. */
  instructionsRevision?: number
  instructionsHash?: string
  /** The base its instructions were moved onto once (migration/rebase.ts, task #3600): a later save is never rewritten. */
  instructionsBase?: number
  /** Moves on each note the coordinator keeps or a member removes (instructions.ts), so an open panel knows to read them. */
  notesRevision?: number
  /** Moves when its repository's GitHub access may have changed: someone allowed it, GitHub sent someone back after
   *  installing the app, or a check that asked GitHub again found a different answer (store.ts githubChanged, githubSeen).
   *  Members' apps read the access again when it moves rather than keeping it 5 minutes (task #2316, Dee 2026-11-03). */
  githubRevision?: number
  /** What the last check that asked GitHub again found (github/projectAccess.ts), so only a different answer moves it. */
  githubSeen?: GitHubSeen
  /** What its coordinator is called; reads give "Product Manager" when absent (instructions.ts coordinatorNameOf). */
  coordinatorName?: string
  /** Agents answer every person's message in that message's thread, never right below it in the main chat (task #3747, anh
   *  Dee 11-06: "i don't know which one you reply to which"). Absent: as before. Set with `project.answers`. */
  answersInThread?: true
  /** 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 closed tab's project that had messages (commands.ts project.closeTab, task #3929): read-only and out of the sidebar. */
  archived?: true
}

/** 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. */
export const GITHUB_SEEN = ['not-installed', 'not-approved', 'covered'] as const
export type GitHubSeen = typeof GITHUB_SEEN[number]

/** A project's status card: its text, when (ISO time) and by which agent it was written. */
export interface ProjectStatus { text: string; at: string; by: string
  /** The text is the coordinator's own lines, shown after the server's (statusCard.ts, task #3593). Absent on a card saved before:
   *  that text was the whole card, whose lines the server now writes, so it is not shown beside them. */
  own?: true
  /** Set by visibleState on the text it shows readers (the server's lines with the coordinator's own): a view applied again to a
   *  view leaves it as it is. Never stored. */
  shown?: true }
export const PROJECT_STATUS_MAX = 2_000

export const skillModeOf = (project: SwarmProject): SkillMode => project.skillMode ?? 'orchestration'
/** Custom only while the stored mode is still Default: a release from before custom sets switches a project by skillMode
 *  alone during a rolling deploy, and that switch must hold here too. */
export const skillSetOf = (project: SwarmProject): SkillSet =>
  project.skillSet === 'custom' && project.roles && skillModeOf(project) === 'default' ? 'custom' : skillModeOf(project)

/** The Lead is whoever leads the project; every other agent is the kind it was started as. */
export const agentKind = (state: SuperTabState, target: Agent): RoleKind => ledProject(state, target.id) ? 'lead' : agentRole(target)

/** The custom role an agent runs: its own role id while that role is of its kind, else the set's first role of its kind
 *  (agents from before custom sets read as the copied Engineer and Reviewer), else none: its role is gone. */
export function agentSetRole(state: SuperTabState, project: SwarmProject, target: Agent): ProjectRole | null {
  const kind = agentKind(state, target), roles = project.roles ?? []
  return roles.find(r => r.id === target.roleId && r.kind === kind) ?? roles.find(r => r.kind === kind) ?? null
}

/** Existing tabs are one project; their conversation IDs and messages stay intact. */
export function projectsOf(state: SuperTabState): SwarmProject[] {
  return state.projects ?? [{
    id: 'lead', name: state.name, ownerId: state.ownerId, leadConversationId: 'lead',
    visibility: 'public', members: [], updateMinutes: 5,
    ...(state.project ? { repository: state.project } : {}),
  }]
}

export function projectOf(state: SuperTabState, projectId: string): SwarmProject {
  return projectsOf(state).find(p => p.id === projectId) ?? fail('NOT_FOUND', 'This project is unavailable.', 404)
}

export function groupProject(state: SuperTabState, group: Conversation): SwarmProject {
  if (isLeads(group)) leadsRemoved()
  // Never the project 'lead' by default: a person's one Buddy chat belongs to no project (Dee, 10-31).
  if (isSwarmBuddyChat(group)) fail('NOT_FOUND', 'This conversation is unavailable.', 404)
  return projectOf(state, group.projectId ?? 'lead')
}

/** The repository address of the project [group] belongs to (null when it has none or the group has no project); never throws. */
export const groupRepositoryUrl = (state: SuperTabState, group: Conversation): string | null =>
  projectsOf(state).find(p => p.id === (group.projectId ?? 'lead'))?.repository?.repositoryUrl ?? null

/** The project a start works in: a project session's own, none for a Swarm-wide Buddy's (Dee, 10-31), else its conversation's. */
export function startProject(state: SuperTabState, request: Pick<AgentStartRequest, 'conversationId' | 'buddySession'>): SwarmProject | undefined {
  if (request.buddySession?.projectId) return projectOf(state, request.buddySession.projectId)
  const group = conversation(state, request.conversationId)
  return isSwarmBuddyChat(group) ? undefined : groupProject(state, group)
}

export function agentProjectId(state: SuperTabState, target: Agent): string {
  // A Swarm-wide Buddy has no project (Dee, 10-31): never the project 'lead' by default, so it matches none.
  if (isSwarmBuddy(target)) return NO_PROJECT
  // A Regular agent (task #4116: "the task decides where it works") is its active task's project's while it works, else none.
  if (target.regular) {
    const work = state.conversations.find(c => c.assignment?.agentId === target.id && activeWork(c))
    if (work) return groupProject(state, work).id
    // A Member is its main project's between tasks (task #4697), while its person still reads it: that project's Lead hands it
    // the next task, and it reports its set-up there.
    const main = target.mainProjectId ? projectsOf(state).find(p => p.id === target.mainProjectId) : undefined
    return main && regularMayWorkIn(state, target, main) ? main.id : NO_PROJECT
  }
  return target.projectId ?? state.conversations.find(c => c.agentIds.includes(target.id))?.projectId ?? 'lead'
}
/** The project id of an agent in no project: no project has it, so a comparison with one is false and projectOf refuses it. */
export const NO_PROJECT = ''

/** The project whose Lead (Product Manager) this agent is: the Lead of that project's Lead conversation. */
export function ledProject(state: SuperTabState, agentId: string): SwarmProject | undefined {
  // One scan of the conversations, then one of the projects in their order: a scan of every conversation per project was
  // ledProject's callback, 13.5 M calls in the 2026-11-02 prod profiles (12 profiles), mostly from markConfidential.
  const led = new Set<string>()
  for (const c of state.conversations) if (c.leadId === agentId) led.add(c.id)
  return led.size ? projectsOf(state).find(p => led.has(p.leadConversationId)) : undefined
}

/** Gives each project whose owner is gone a new owner (task #3073, River's ruling 2026-11-05): its owner left or was
 *  removed, or is in the Swarm at a later membership. It passes to the earliest listed member still in the Swarm at the
 *  membership they were listed with, who reads it already (one who can manage it first, else a viewer); else, for a public
 *  project, to the Swarm's owner, who reads it too; else it is nobody's ('' owner): nobody reads it, and the Swarm's owner
 *  sees only that it exists and may delete it (deletableProject). A project from before ownerGeneration whose owner is still
 *  here gets their membership now, which is how the migration fills it. Each project that changed hands, in order. */
export function settleOwners(state: SuperTabState): Array<{ projectId: string; from: string; to: string }> {
  const changed: Array<{ projectId: string; from: string; to: string }> = []
  const people = new Map(state.people.map(p => [p.id, p]))
  for (const project of state.projects ?? []) {
    if (!project.ownerId) continue
    const current = people.get(project.ownerId)
    if (current && project.ownerGeneration === undefined) project.ownerGeneration = current.generation
    if (current && project.ownerGeneration === current.generation) continue
    const listed = project.members.filter(m => m.id !== project.ownerId && people.get(m.id)?.generation === m.generation)
    const next = listed.find(m => people.get(m.id)!.role !== 'viewer') ?? listed[0]
    const swarmOwner = people.get(state.ownerId)
    const to = next ? people.get(next.id)! : project.visibility === 'public' && swarmOwner ? swarmOwner : undefined
    changed.push({ projectId: project.id, from: project.ownerId, to: to?.id ?? '' })
    project.ownerId = to?.id ?? ''
    if (to) project.ownerGeneration = to.generation
    else delete project.ownerGeneration
    if (next) project.members = project.members.filter(m => m !== next)
  }
  return changed
}

/** Adds [member] to the Swarm by any way in (invitation, link, domain or Workspace join): its projects are settled first, so
 *  a project from before ownerGeneration whose owner left is never matched to them again (security reviews of #3082). */
export function admitPerson(state: SuperTabState, member: Person): void {
  settleOwners(state)
  settleBoardRights(state)
  state.people.push(member)
}

/** Takes the people [leaving] out of the Swarm (a removal, a leave, a restore that keeps out those the Workspace lost), and
 *  passes their projects on (settleOwners). */
export function dismissPeople(state: SuperTabState, leaving: ReadonlySet<string>): void {
  state.people = state.people.filter(p => !leaving.has(p.id))
  settleOwners(state)
  settleBoardRights(state)
}

/** Takes everyone no longer in the Swarm out of each project's Can chat and decider seat (task #4216). Both name a person by
 *  id only, and any member reads a public project, so without this a person removed and invited back had them again. Run
 *  before a person is admitted too, which clears a right kept from before this ran on leaving. */
function settleBoardRights(state: SuperTabState): void {
  const people = new Set(state.people.map(p => p.id))
  for (const project of state.projects ?? []) {
    if (project.canChat) {
      const kept = project.canChat.filter(id => people.has(id))
      if (kept.length) project.canChat = kept
      else delete project.canChat
    }
    if (project.decider && !people.has(project.decider)) delete project.decider
  }
}

/** Whose active work other projects' Leads see and are alerted about. A private project's work stays with its own people. */
export const sharedWithLeads = (project: SwarmProject): boolean => project.visibility !== 'private'

export function canReadProject(state: SuperTabState, actor: Actor, project: SwarmProject): boolean {
  if (actor.kind === 'agent') {
    const target = state.agents.find(a => a.id === actor.agentId)
    if (!target || target.machineOwnerId !== actor.machineOwnerId) return false
    // A Swarm-wide Buddy reads every project its person reads now, at the membership it was added in (Dee, 10-31).
    if (isSwarmBuddy(target)) return !!buddyPerson(state, target, project)
    return agentProjectId(state, target) === project.id
  }
  const member = state.people.find(p => p.id === actor.userId)
  return !!member && (project.visibility === 'public' || ownsProject(state, member.id, project) ||
    project.members.some(p => p.id === member.id && p.generation === member.generation))
}

/** Whether [userId] owns [project] now: its owner, in the Swarm at the membership they owned it in (task #3073). A former
 *  owner who left or was removed and came back owns nothing, as a former member reads nothing. A project from before the
 *  generation was stored matches by id until settleOwners fills it. */
export function ownsProject(state: SuperTabState, userId: string, project: SwarmProject): boolean {
  if (!userId || project.ownerId !== userId) return false
  const member = state.people.find(p => p.id === userId)
  return !!member && (project.ownerGeneration === undefined || project.ownerGeneration === member.generation)
}

/** Whom a group's work is for, as its pull requests say (`requestedByLine`): the person who asked for it (`requesterId`) while
 *  they can still read its project, else the project's owner. Until 11-01 it was always the owner, and agents on Tony's Mac
 *  opened Tony's pull requests as Ken's (#2486, #2488, #2491). It names a person only: the GitHub App's token, who gets one
 *  and its commit trailers (store.ts githubAssignment, githubStart) never depend on it. */
export function workRequesterId(state: SuperTabState, project: SwarmProject, group: Conversation | undefined): string {
  const id = group && (group.projectId ?? 'lead') === project.id ? group.requesterId : undefined
  const member = id ? state.people.find(p => p.id === id) : undefined
  return member?.email && canReadProject(state, { kind: 'person', userId: member.id, email: member.email }, project) ? member.id : project.ownerId
}

/** The line a task's message ends with, telling its Engineer whom the task's pull requests are for. It comes with each
 *  task, from that task's requester, so a reused Engineer never names the one before; the start prompt names nobody
 *  (security review 2 of #2492). Given where the start prompt gave it before: another person's project work, where the
 *  project's owner is not the machine's (cli/src/superTabs/start.ts `githubPromptLine`). A review opens no pull request.
 *  The name is the one the Swarm shows them (personNames.ts writtenNameOf). */
export function requestedByLine(state: SuperTabState, project: SwarmProject, group: Conversation, worker: Agent): string | null {
  if (group.reviewOf || project.ownerId === worker.machineOwnerId) return null
  const requester = state.people.find(p => p.id === workRequesterId(state, project, group))
  // By name, never email: agents pasted the email into pull requests and a machine's privacy hook stopped them (task #2954).
  return requester?.email ? `Start each pull request body with: Requested by ${agentWrittenNameOf(state, requester.id)} through Harness.` : null
}

/** Where Regular agent [worker] finds [project]'s code, for its task's message. It starts in its own empty folder, in no project
 *  (task #4116), and nothing prepares a checkout when it is given a task, so the message says where the code is (task #4218):
 *  the GitHub repository to clone with its own person's git, or the checkout on its own computer. A checkout's folder is
 *  named only on that computer, its person's own. */
export function regularCodeLine(project: SwarmProject, worker: Agent): string {
  const repository = project.repository
  if (repository?.repositoryUrl) return `This project's code is ${repository.repositoryUrl}. Clone it into a folder inside your own folder and work on a branch there, with the git and gh signed in on this computer.`
  if (repository && repository.machineId === worker.machineId) return `This project's code is checked out at ${repository.cwd} on this computer. Make a git worktree of it inside your own folder and work on a branch there.`
  return 'This project has no code this computer can reach: it has no GitHub repository. Ask its PM before changing code.'
}

export function readProject(state: SuperTabState, actor: Actor, projectId: string): SwarmProject {
  author(state, actor)
  const project = projectOf(state, projectId)
  if (!canReadProject(state, actor, project)) fail('NOT_FOUND', 'This project is unavailable.', 404)
  return project
}

export function readConversation(state: SuperTabState, actor: Actor, conversationId: string): Conversation {
  const group = conversation(state, conversationId)
  // Removed for everyone alike (model.ts leadsRemoved): a member of the Swarm reads one plain refusal, nothing of it.
  if (isLeads(group)) {
    author(state, actor)
    leadsRemoved()
  }
  // A person's one Buddy chat has no project: its person and their Buddies read it, and anyone else finds no such chat.
  if (isSwarmBuddyChat(group)) {
    author(state, actor)
    if (!readsSwarmBuddyChat(state, actor, group)) fail('NOT_FOUND', 'This conversation is unavailable.', 404)
    return group
  }
  // A person's chat with a Regular agent of theirs has no project either (agent.new, task #4116): its person and that agent.
  if (isAgentChat(group)) {
    author(state, actor)
    if (!readsAgentChat(state, actor, group)) fail('NOT_FOUND', 'This conversation is unavailable.', 404)
    return group
  }
  // A chat of a project the reader does not read is refused in the same words as one that does not exist: "project
  // unavailable" told another project's chat apart from a made-up id (security review 2 of #2435).
  author(state, actor)
  if (!canReadProject(state, actor, groupProject(state, group)) || !canReadGroup(state, actor, group)) fail('NOT_FOUND', 'This conversation is unavailable.', 404)
  return group
}

/** Whether a project's owner and the Swarm's owner also read its private conversations. The owner decided they do not
 *  (2026-10-26); this is the one place that decides it (design section 4.8). */
export const PRIVATE_VISIBLE_TO_OWNERS = false

/** A Chat with PM from before Buddies replaced it (Ken, 10-29): a private conversation that is no Buddy chat and no Regular agent's
 *  chat (#4248: counted as one, a Regular agent's chat was never listed or delivered). Nobody opens one any more, and nobody reads
 *  one, the PM and its person included; its rows stay in the database. */
export const isClosedPmChat = (group: Pick<Conversation, 'kind' | 'audience'>): boolean => !!group.audience && !isBuddyChat(group) && !isAgentChat(group)

/** Who reads a conversation: nobody the removed Leads conversation (model.ts leadsRemoved); a project conversation's readers; and a Buddy
 *  chat's owner and Buddy (buddies.ts), the PM never. A closed Chat with PM is nobody's. A Buddy reads what its person
 *  reads of its project, no private conversation but its own chat (buddies.ts). */
export function canReadGroup(state: SuperTabState, actor: Actor, group: Conversation): boolean {
  return !isClosedPmChat(group) && readsRecordsIn(state, actor, group)
}

/** Whether [actor] reads what was asked in [group] (decisions.ts): as canReadGroup, and in a closed Chat with PM still its
 *  person, at the generation they were listed with, and the project's Lead, so a decision asked there before stays theirs. */
export function readsRecordsIn(state: SuperTabState, actor: Actor, group: Conversation): boolean {
  if (isLeads(group)) return false
  if (isSwarmBuddyChat(group)) return readsSwarmBuddyChat(state, actor, group)
  if (isAgentChat(group)) return readsAgentChat(state, actor, group)
  const project = groupProject(state, group)
  if (!canReadProject(state, actor, project)) return false
  const buddy = actor.kind === 'agent' ? state.agents.find(a => a.id === actor.agentId && isBuddy(a)) : undefined
  if (buddy) return buddyReads(buddy, group, project.leadConversationId, buddyPerson(state, buddy, project))
  if (!group.audience) return true
  // A Buddy chat has no private channel to the PM: only its owner and its Buddy read it (buddies.ts).
  if (actor.kind === 'agent') return !isBuddyChat(group) && ledProject(state, actor.agentId)?.id === project.id
  const member = state.people.find(p => p.id === actor.userId)
  return !!member && (group.audience.people.some(p => p.id === member.id && p.generation === member.generation)
    || (PRIVATE_VISIBLE_TO_OWNERS && (member.id === project.ownerId || member.id === state.ownerId)))
}

/** A person's chat with a Regular agent of theirs (agent.new, task #4116). */
export const isAgentChat = (group: Pick<Conversation, 'kind'>): boolean => group.kind === 'agent-chat'

/** Whether [actor] reads agent chat [group]: its person at the membership it was opened in, and an agent in it that runs on that
 *  person's own account. Nobody else: not the Swarm's owner, a project's owner or PM, or another agent, as a Swarm Buddy chat. */
function readsAgentChat(state: SuperTabState, actor: Actor, group: Conversation): boolean {
  const owner = group.audience?.people[0]
  if (!owner || !state.people.some(p => p.id === owner.id && p.generation === owner.generation)) return false
  if (actor.kind === 'person') return actor.userId === owner.id
  const target = state.agents.find(a => a.id === actor.agentId)
  return !!target && target.machineOwnerId === actor.machineOwnerId && group.agentIds.includes(target.id)
    && target.contributorId === owner.id && target.machineOwnerId === owner.id
}

/** Whether [actor] reads Swarm Buddy chat [group] (Dee, 10-31): its person at the membership it was opened in, and a Buddy in it
 *  of that person and membership. Nobody else: not the Swarm's owner, a project's PM or another agent. */
function readsSwarmBuddyChat(state: SuperTabState, actor: Actor, group: Conversation): boolean {
  const owner = group.audience?.people[0]
  if (!owner || !state.people.some(p => p.id === owner.id && p.generation === owner.generation)) return false
  if (actor.kind === 'person') return actor.userId === owner.id
  const target = state.agents.find(a => a.id === actor.agentId)
  return !!target && target.machineOwnerId === actor.machineOwnerId && group.agentIds.includes(target.id) && isBuddy(target)
    && target.buddyOf!.personId === owner.id && target.buddyOf!.generation === owner.generation
}

/** A Buddy's person, while they read [project] at the membership they added it in: a person who left, rejoined or lost a
 *  private project's membership takes their Buddy's reads with them, the instructions' included (review of phase 2). */
export function buddyPerson(state: SuperTabState, buddy: Agent, project: SwarmProject): Person | undefined {
  const person = state.people.find(p => p.id === buddy.buddyOf!.personId && p.generation === buddy.buddyOf!.generation)
  return person && canReadProject(state, { kind: 'person', userId: person.id, email: person.email }, project) ? person : undefined
}

/** The project whose instructions [buddy] reads for its person (task #3024): any project its person reads now, at the
 *  membership they added it in, a Buddy of one project's included, so it can check a project's rules for them as they would
 *  (Leo, 11-05: his Buddy could not read lamp's). This read alone: its other reads stay with its project. Refused in the words
 *  of a project that does not exist. */
export function buddyInstructionsProject(state: SuperTabState, actor: Actor, buddy: Agent, projectId: string): SwarmProject {
  author(state, actor)
  const project = projectOf(state, projectId)
  if (actor.kind !== 'agent' || actor.agentId !== buddy.id || buddy.machineOwnerId !== actor.machineOwnerId || !isBuddy(buddy)
    || !buddyPerson(state, buddy, project)) fail('NOT_FOUND', 'This project is unavailable.', 404)
  return project
}

/** A private conversation's audience: each person a member who reads its project, captured at their generation. */
export function audienceOf(state: SuperTabState, project: SwarmProject, personIds: string[]): NonNullable<Conversation['audience']> {
  return { people: [...new Set(personIds)].map(id => {
    const member = state.people.find(p => p.id === id) ?? fail('INVALID_AUDIENCE', 'List people in this Swarm.', 400)
    if (!canReadProject(state, { kind: 'person', userId: member.id, email: member.email }, project)) {
      fail('INVALID_AUDIENCE', `${member.email} cannot read this project.`, 400)
    }
    return { id: member.id, generation: member.generation }
  }) }
}

export function canReadAgent(state: SuperTabState, actor: Actor, target: Agent): boolean {
  // A Swarm-wide Buddy belongs to no project and writes only in its person's chat: its person reads it, and so does it.
  if (isSwarmBuddy(target)) return actor.kind === 'person' ? actor.userId === target.buddyOf!.personId : actor.agentId === target.id
  // An idle Regular agent (task #4116): its person, itself, and the PM of a project its person reads, which may give it a task.
  if (target.regular && agentProjectId(state, target) === NO_PROJECT) {
    if (actor.kind === 'person') return actor.userId === target.contributorId
    if (actor.agentId === target.id) return true
    const led = ledProject(state, actor.agentId)
    return !!led && regularMayWorkIn(state, target, led)
  }
  return canReadProject(state, actor, projectOf(state, agentProjectId(state, target)))
}

/** A session that reads people's private messages: its project's Lead (the Product Manager each person chats with privately),
 *  or any agent in a private conversation, so a replaced Lead's earlier screen stays closed too. */
export const confidentialSession = (state: SuperTabState, target: Agent, sets: ConfidentialSets = confidentialSets(state)): boolean =>
  sets.leaders.has(target.id) || sets.privateMembers.has(target.id)

/** confidentialSets' answer. A caller that asks about many agents or readers of one state builds it once and passes it down
 *  (task #4504: the host roster rebuilt it for each person on each agent, agents x people passes over the conversations). */
export interface ConfidentialSets { leaders: ReadonlySet<string>; privateMembers: ReadonlySet<string> }

/** Who confidentialSession holds confidential, for every agent at once: the Leads of a project's Lead conversation, and every
 *  member of a private conversation (one with an audience). One pass over the conversations: asking per agent scanned them
 *  per project and agent on every command (markConfidential), 13.5 M of ledProject's callbacks and 1.6 M of the private
 *  member check's in the 2026-11-02 prod profiles. Built per call, never kept on the state, since a command changes it. */
export function confidentialSets(state: SuperTabState): ConfidentialSets {
  const leadChats = new Set(projectsOf(state).map(p => p.leadConversationId))
  const leaders = new Set<string>(), privateMembers = new Set<string>()
  for (const c of state.conversations) {
    if (c.leadId !== null && leadChats.has(c.id)) leaders.add(c.leadId)
    if (c.audience) for (const id of c.agentIds) privateMembers.add(id)
  }
  return { leaders, privateMembers }
}

/** Whether an agent's session is confidential: marked, or a Lead or private member now, here or (`elsewhere`) in another Swarm. */
export const isConfidential = (state: SuperTabState, target: Agent, elsewhere = false, sets?: ConfidentialSets): boolean =>
  !!target.confidential || elsewhere || confidentialSession(state, target, sets)

/** A native session's identity across Swarms: its machine and harness. */
export const sessionKey = (machineId: string, harnessId: string) => `${machineId}\n${harnessId}`
/** The other Swarms' registrations a command is checked against (confidential.ts otherRegistrations), by sessionKey. */
export interface OtherRegistrations { registered: Set<string>; confidential: Set<string> }

/** A confidential session is registered in one Swarm only (Lead ruling, final review Critical 1), so its mark lives exactly as
 *  long as that registration: a command may not register again (add, start, rebind) a session confidential elsewhere, nor make
 *  a session registered elsewhere a Lead or a private conversation's member. Registrations from before the rule stay. */
export function requireSingleRegistration(before: SuperTabState, after: SuperTabState, elsewhere: OtherRegistrations): void {
  const prior = new Map(before.agents.map(a => [a.id, a]))
  const then = confidentialSets(before), now = confidentialSets(after)
  for (const target of after.agents) {
    const was = prior.get(target.id), key = sessionKey(target.machineId, target.harnessId)
    if ((!was || was.harnessId !== target.harnessId) && elsewhere.confidential.has(key)) {
      fail('SESSION_CONFIDENTIAL', 'This terminal reads private chats in another Swarm. Start a new agent here.')
    }
    const lead = now.leaders.has(target.id) && !(was && then.leaders.has(target.id))
    const member = now.privateMembers.has(target.id) && !(was && then.privateMembers.has(target.id))
    if ((lead || member) && elsewhere.registered.has(key)) {
      fail('SESSION_CONFIDENTIAL', 'This terminal also works in another Swarm, so it cannot lead or read private chats. Start a new agent for this.')
    }
  }
}

/** A session becomes confidential the moment it is a Lead or in a private conversation, and stays so until it leaves the
 *  Swarm (its session closes), even once that membership ends (Lead ruling, final review Critical 1). */
export function markConfidential(state: SuperTabState): void {
  // Every command runs this for every agent: one pass for all of them, not one per agent (confidentialSets).
  const { leaders, privateMembers } = confidentialSets(state)
  for (const target of state.agents) if (!target.confidential && (leaders.has(target.id) || privateMembers.has(target.id))) target.confidential = true
}

/** Whether a session's terminal is closed to watching in this Swarm. A confidential session's screen and scrollback hold
 *  people's private chats, so only the person whose machine runs it watches it, owners included. The project's current Lead is
 *  the exception, view only (Ken, 2026-10-28): every reader of its project watches it, the private chats it is in included.
 *  It stays marked, so a former Lead, another Swarm and an ordinary share still find it closed. `elsewhere`: the session is
 *  confidential in another Swarm (confidential.ts), whose chats are not this Swarm's to read. */
export const watchClosed = (state: SuperTabState, target: Agent, elsewhere = false, sets?: ConfidentialSets): boolean =>
  elsewhere || (isConfidential(state, target, false, sets) && !ledProject(state, target.id))

/** Who may watch an agent's terminal: observe it or hold a share of it. Reading or typing in it on request is closed by
 *  `isConfidential` alone (terminal.ts mayDrive). Any other agent: every reader of its project, as before. */
export function canWatchAgent(state: SuperTabState, actor: Actor, target: Agent, elsewhere = false, sets?: ConfidentialSets): boolean {
  if (!canReadAgent(state, actor, target)) return false
  const team = teamSessionAccess(state, actor, target, elsewhere, sets)
  if (team) return team !== 'none'
  return !watchClosed(state, target, elsewhere, sets) || ownSession(actor, target)
}

/** Whether [pool] is a Harness Team account: a Mac's (it names its Mac) or a machine used only for agents (its reading came
 *  from a team session). */
export const teamAccountPool = (pool: import('./machines.js').ContributedMachine | null | undefined): boolean =>
  !!pool && (!!pool.hostMachineId || pool.observation?.sessionKind === 'team')

/** Whether [target] runs in a Harness Team account: read from its machine, whichever way it joined (security review 1 of
 *  #2089), and kept from when it joined one, so a machine row that went never brings back the old rules (its re-review). */
export const onTeamAccount = (state: SuperTabState, target: Agent): boolean =>
  !!target.teamAccount || teamAccountPool(state.machines?.find(m => m.machineId === target.machineId))

/** Which account [agent] acts as (audit M3, task #2021): its machine owner's own on any of their machines, or, [onTeam], that
 *  one machine's Harness Team account. */
export const accountOf = (agent: Pick<Agent, 'machineId' | 'machineOwnerId'>, onTeam: boolean): string =>
  onTeam ? `team:${agent.machineOwnerId}:${agent.machineId}` : `own:${agent.machineOwnerId}`

/** Notices the server writes in its own words under an agent's name (security reviews of #2570): they quote no agent, task
 *  titles and names aside. */
const SERVER_WORDS: ReadonlySet<unknown> = new Set(['work-stalled', 'work-resumed', 'idle', 'review-capacity', 'overlap', 'pm-switch-notice', 'others-work-notice'])
/** Whose words a row carries, for the mark of another account's (audit M3): its author's (a post, a status row, a brief, a
 *  route's reason); a lost task's notice, its worker's last result; none, a notice in the server's own words. A review's
 *  failed findings name no reviewer: they count as unknown, which is marked. */
export function wordsOf(source: unknown): 'author' | 'none' | 'unknown' | { agentId: string } {
  const row = source as { kind?: unknown; agentId?: unknown } | null | undefined
  if (SERVER_WORDS.has(row?.kind)) return 'none'
  if (row?.kind === 'review-failed') return 'unknown'
  if (row?.kind === 'work-lost') return typeof row.agentId === 'string' ? { agentId: row.agentId } : 'unknown'
  // A Buddy's proposal, posted as its owner: its Buddy wrote the goal and scope and picked the words (security review 2 of #3024).
  if (row?.kind === 'buddy-proposal') {
    const buddyId = (row as { buddyId?: unknown }).buddyId
    return typeof buddyId === 'string' ? { agentId: buddyId } : 'unknown'
  }
  return 'author'
}

/**
 * A confidential session in a Harness Team account (#895 R2): every teammate's work there runs as one macOS user whose
 * folders hold other projects' clones, so typing in it is a shell that reads them. Nobody drives it through the Swarm. Its
 * project's owner may watch it; its machine's owner neither watches nor drives it, as a member or as its machine's person.
 * Other members watch it as they watch any confidential session (watchClosed). Null for every other session, and for
 * agents, which keep their own rules (mayDrive).
 */
export function teamSessionAccess(state: SuperTabState, actor: Actor, target: Agent, elsewhere = false, sets?: ConfidentialSets): 'watch' | 'none' | 'member' | null {
  if (!onTeamAccount(state, target) || actor.kind !== 'person' || !isConfidential(state, target, elsewhere, sets)) return null
  if (ownsProject(state, actor.userId, projectOf(state, agentProjectId(state, target)))) return 'watch'
  if (actor.userId === target.machineOwnerId) return 'none'
  return watchClosed(state, target, elsewhere, sets) ? 'none' : 'member'
}

/** Who could watch an agent's terminal before a commit and cannot after it (canWatchAgent, by the session the observer relay
 *  watches: machine, harness and machine owner): a person left, the agent left, its project stopped being shared with them,
 *  or the session turned confidential, by whatever command. Each such agent, with the people who lost it. Its observer
 *  sockets then check again (store.ts accessChanged), and those people's terminals on it are revoked (native.ts). */
export function watchersLost(before: SuperTabState, after: SuperTabState): Array<{ agentId: string; personIds: string[] }> {
  const session = (a: Agent) => `${a.machineId}\n${a.harnessId}\n${a.machineOwnerId}`
  const now = new Map(after.agents.map(a => [session(a), a]))
  // canWatchAgent per person, with the confidential sets built once per state, not once per person per agent (task #4504).
  const sets = new Map<SuperTabState, ConfidentialSets>([[before, confidentialSets(before)], [after, confidentialSets(after)]])
  const watchers = (state: SuperTabState, target: Agent) => state.people.map(p => ({ kind: 'person' as const, userId: p.id, email: p.email }))
    .filter(actor => canWatchAgent(state, actor, target, false, sets.get(state)))
  return before.agents.flatMap(target => {
    const was = watchers(before, target)
    if (!was.length) return []
    const still = now.get(session(target))
    const is = new Set(still ? watchers(after, still).map(actor => actor.userId) : [])
    const lost = was.filter(actor => !is.has(actor.userId)).map(actor => actor.userId)
    return lost.length ? [{ agentId: target.id, personIds: lost }] : []
  })
}

/** Everything that decides who reads a conversation and who watches a terminal (canReadGroup, canWatchAgent and the
 *  terminals native.ts revokes): when two states give the same text, no access changed between them. Messages, statuses and
 *  checks, most commands, change none of it. The Swarm's owner counts only once PRIVATE_VISIBLE_TO_OWNERS is true; it is
 *  kept so that turning it on cannot skip a revocation. */
export const accessInputs = (state: SuperTabState): string => JSON.stringify([state.ownerId,
  state.people.map(p => [p.id, p.generation, p.role]),
  projectsOf(state).map(p => [p.id, p.visibility, p.ownerId, p.members, p.leadConversationId]),
  state.agents.map(a => [a.id, a.machineId, a.harnessId, a.machineOwnerId, a.projectId, a.confidential]),
  state.conversations.map(c => [c.id, c.kind, c.projectId, c.leadId, c.archived, c.agentIds, c.audience])])

/** Whether [actor] is an agent working in [projectId], as its host speaks for it: any of the project's agents but a Buddy, which
 *  only talks with its owner. Which of them does what is the project's instructions' to say (project instructions, phase 4). */
export function projectAgent(state: SuperTabState, actor: Actor, projectId: string): actor is Extract<Actor, { kind: 'agent' }> {
  if (actor.kind !== 'agent') return false
  const self = state.agents.find(a => a.id === actor.agentId)
  return !!self && !isBuddy(self) && self.machineOwnerId === actor.machineOwnerId && agentProjectId(state, self) === projectId
}

/** The only actors a confidential session admits: the person whose machine runs it, or the session itself. */
export const ownSession = (actor: Actor, target: Agent): boolean =>
  actor.kind === 'person' ? actor.userId === target.machineOwnerId : actor.agentId === target.id

export function readAgent(state: SuperTabState, actor: Actor, agentId: string): Agent {
  const target = agent(state, agentId)
  if (!canReadAgent(state, actor, target)) fail('AGENT_UNAVAILABLE', 'This agent is unavailable.', 404)
  return target
}

/** A terminal contains its session's entire history. Joining another project's
 * chat must never expose that history to a different audience. */
/** Whether Regular agent [target] may take a task in [project]: its person reads it (it works only where they could read it
 *  themselves), and, once it has worked in a private project, it is that one: its one conversation holds that project's
 *  content, which no other project's members may hear from it (security review 2 of #4116). Public work moves on freely. */
export function regularMayWorkIn(state: SuperTabState, target: Agent, project: SwarmProject): boolean {
  const member = state.people.find(p => p.id === target.contributorId)
  return !!member && canReadProject(state, { kind: 'person', userId: member.id, email: member.email }, project)
    && (!target.privateProjectId || target.privateProjectId === project.id)
}

/** [admitsIdleRegular]: an assignment, the one way an idle Regular agent comes into a project (task #4116), which records its
 *  private mark (commands.ts assignTo), or taking an agent out, which admits nobody. A chat join admits none: added while idle,
 *  it would hear a private project with nothing recorded, or sit in several projects at once (security review 2 of #4116). */
export function sameProject(state: SuperTabState, group: Conversation, target: Agent, admitsIdleRegular = false): void {
  const project = groupProject(state, group)
  // An idle Regular agent takes its task's project, if it may work there; a busy one stays in its task's.
  if (target.regular && agentProjectId(state, target) === NO_PROJECT) {
    if (!admitsIdleRegular) fail('REGULAR_TASK_ONLY', 'A Regular agent joins a project through a task there: give it one.', 403)
    if (regularMayWorkIn(state, target, project)) return
  }
  if (agentProjectId(state, target) !== project.id) {
    fail('PROJECT_SESSION', 'Start a separate agent for another project. This terminal belongs to its original project.')
  }
}

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)
  if (actor.kind !== 'person' || !ownsProject(state, actor.userId, project)) {
    fail('PROJECT_OWNER_REQUIRED', 'Only the project owner can manage this project.', 403)
  }
  mutableProjects(state)
  return projectOf(state, projectId)
}

/** The project [actor] may delete: one they manage, or, for the Swarm's owner, one that is nobody's (settleOwners), which they
 *  may delete but never read (task #3073). */
export function deletableProject(state: SuperTabState, actor: Actor, projectId: string): SwarmProject {
  author(state, actor)
  const project = projectsOf(state).find(p => p.id === projectId)
  if (!project || !isOwnerless(project) || actor.kind !== 'person' || actor.userId !== state.ownerId) return manageProject(state, actor, projectId)
  author(state, actor, true)
  mutableProjects(state)
  return projectOf(state, projectId)
}

/** The account of [project]'s owner, which the GitHub token and a start's preparation name the work for: nobody for a project
 *  nobody owns, never looked up by its empty id, which is no ObjectId (the lookup would throw). */
export async function ownerAccount(users: { findUnique(args: { where: { id: string }; select: { name: true; email: true } }): Promise<{ name: string | null; email: string } | null> },
  project: SwarmProject): Promise<{ name: string | null; email: string } | null> {
  return project.ownerId ? users.findUnique({ where: { id: project.ownerId }, select: { name: true, email: true } }) : null
}

/** A project nobody owns: its owner left with no member left to take it (settleOwners). */
export const isOwnerless = (project: SwarmProject): boolean => !project.ownerId

/** What the Swarm's owner reads of each project nobody owns (task #3073): that it exists, its name and its size (its chats in
 *  this read), never what is in it. Anyone else reads nothing of them. */
export function ownerlessProjects(state: SuperTabState, actor: Actor): Array<{ id: string; name: string; conversations: number }> | undefined {
  if (actor.kind !== 'person' || actor.userId !== state.ownerId) return undefined
  const ownerless = projectsOf(state).filter(isOwnerless)
  return ownerless.length ? ownerless.map(p => ({ id: p.id, name: p.name,
    conversations: state.conversations.filter(c => c.projectId === p.id).length })) : undefined
}

/** How long a start may stay pending before a project delete treats it as stuck: well past the 15 minutes the sweep gives a
 *  dispatched start to prepare (liveness.ts START_PREPARE_MS). */
export const STUCK_START_MS = 60 * 60_000

/** Removes coordination only; the command removes the project's agents first.
 * Pending starts must be reconciled first; terminal-history privacy bindings remain permanent. [orphaned] names the
 * contributed starts still settling whose agent was already removed before this delete: only their machine settles one,
 * and it closed that agent's session when it was removed, so none of them ever settles (2026-11-04: 17 such starts on four
 * Macs, from agents stopped while a project was cleaned up, kept its owner from deleting it). */
export function deleteProject(state: SuperTabState, actor: Actor, projectId: string, orphaned: ReadonlySet<string> = new Set(), now?: number): void {
  const project = deletableProject(state, actor, projectId)
  // A project nobody owns is deleted by the Swarm's owner, who reads nothing of it: no refusal names what is in it, and its
  // work, which nobody can resolve, goes with it.
  const ownerless = isOwnerless(project)
  // A person's one Buddy chat belongs to no project and stays; that project's sessions in it go with their agents.
  const groups = state.conversations.filter(c => !isLeads(c) && !isSwarmBuddyChat(c) && groupProject(state, c).id === project.id)
  const groupIds = new Set(groups.map(c => c.id))
  // A queued start in an archived conversation can never be dispatched (commands.ts open() refuses it), so it no longer
  // blocks the delete; it goes with the project's other starts below. On 2026-11-03 one queued two days earlier kept an
  // owner from deleting a cleaned-up project, and no command could settle it.
  const archived = new Set(groups.filter(c => c.archived).map(c => c.id))
  // A start still pending an hour after it was last asked for is stuck, not starting: the sweep fails a dispatched one
  // within 15 minutes (liveness.ts), so nothing is mid-start there. It goes with the project. On 2026-11-04 the owner was
  // still refused after both fixes above, by starts no read showed them.
  const stuck = (s: AgentStart) => now !== undefined && now - (s.dispatchedAt ?? s.requestedAt ?? 0) > STUCK_START_MS
  const pending = (state.starts ?? []).filter(s => groupIds.has(s.request.conversationId) && !s.error && !stuck(s) &&
    !(!s.dispatched && !s.harnessId && archived.has(s.request.conversationId)) &&
    (!s.harnessId || s.poolGeneration && !s.poolSettled && !orphaned.has(s.id)))
  // Each refusal names what holds it, so its owner can act on it: the ones before named nothing, and no read showed them.
  const titled = (id: string) => groups.find(c => c.id === id)?.title || 'the project chat'
  if (pending.length && ownerless) fail('STARTS_PENDING', 'Agents of this project are still starting. Delete it once they have started or failed, within the hour.')
  if (pending.length) {
    fail('STARTS_PENDING', `Resolve this project’s pending agent starts before deleting it: ${pending.slice(0, 3)
      .map(s => `${s.request.name} in “${titled(s.request.conversationId)}”`).join(', ')}${pending.length > 3 ? ` and ${pending.length - 3} more` : ''}.`)
  }
  const active = ownerless ? [] : groups.filter(activeWork)
  if (active.length) {
    fail('WORK_ACTIVE', `Resolve this project’s active work before deleting it: ${active.slice(0, 3).map(c => `“${titled(c.id)}”`).join(', ')}${
      active.length > 3 ? ` and ${active.length - 3} more` : ''}.`)
  }
  state.retiredConversationNumber = nextConversationNumber(state) - 1
  state.projects = state.projects!.filter(p => p.id !== project.id)
  state.rules = state.rules?.filter(r => r.projectId !== project.id)
  if (!state.rules?.length) delete state.rules
  state.conversations = state.conversations.filter(c => !groupIds.has(c.id))
  state.starts = state.starts?.filter(s => !groupIds.has(s.request.conversationId))
  // A pending invitation is to the Swarm, not to this project: it lands somewhere that is left instead.
  const landing = inviteLanding(state)
  state.invitations = state.invitations.flatMap(i => !groupIds.has(i.conversationId) ? [i] : landing ? [{ ...i, conversationId: landing }] : [])
  if (project.id === 'lead') {
    delete state.project
    state.machines = state.machines?.filter(m => m.scope === 'swarm')
  }
}

/** Rules were the Swarm's until 2026-10-23, when one project's rules refused every other project's Lead. A rule from then
 * belongs to the project whose chat it was asked in, else to the project of a remaining Lead chat (inviteLanding). */
export function placeRules(state: SuperTabState): void {
  for (const rule of state.rules ?? []) {
    if (rule.projectId) continue
    const asked = rule.askedIn && state.conversations.find(c => c.id === rule.askedIn!.conversationId)
    const landing = state.conversations.find(c => c.id === inviteLanding(state))
    rule.projectId = asked ? groupProject(state, asked).id : landing ? groupProject(state, landing).id : 'lead'
  }
}

export function projectRules(state: SuperTabState, projectId: string): SwarmRule[] {
  return (state.rules ?? []).filter(r => r.projectId === projectId)
}

/** Where an invited person lands: the asked-for group while it exists, else a remaining project's Lead
 * conversation, public first. Desktop asks for the original 'lead' group, which is gone once its project is
 * deleted; on 2026-10-22 that refused every invitation with "This conversation is unavailable". */
export function inviteLanding(state: SuperTabState, preferred?: string): string | null {
  if (preferred && state.conversations.some(c => c.id === preferred)) return preferred
  const projects = projectsOf(state).filter(p => state.conversations.some(c => c.id === p.leadConversationId))
  return (projects.find(p => p.visibility === 'public') ?? projects[0])?.leadConversationId ?? null
}

/** Capture current swarm membership so leaving and rejoining does not restore
 * an old private-project invitation. */
export function projectMembers(state: SuperTabState, ids: string[]) {
  return [...new Set(ids)].map(id => {
    const member = person(state, id)
    return { id, generation: member.generation }
  })
}