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.

98.0 KB
Raw Blame
import { createHash } from 'node:crypto'
import { githubRepository } from '../github/repository.js'
import { cloneData } from './cloneData.js'
import { autoJoinOn } from './autoJoinDomain.js'
import { lostReasonWithoutMachine } from './lostReason.js'
import type { RouteDecisionEffect } from './routeRecord.js'
import { agentDisplayName, assignAgentDisplayNames } from './agentNames.js'
import { withAvatarView } from './profile.js'
import { swarmUsernames } from './usernames.js'
import { downSince, expireRemovals, startPreparing } from './machines.js'
import { publicReason, readsRawReason } from './startFailure.js'
import { FIRST_INSTRUCTIONS } from './instructions.js'
import { visibleAccess } from './machineAccess.js'
import { projectCard, withExtra } from './statusCard.js'
import { processOf, projectColumns } from './process.js'
import { agentProjectId, agentSetRole, canReadAgent, canReadGroup, canReadProject, groupProject, ledProject, ownerlessProjects, ownsProject, placeRules, projectsOf, sharedWithLeads, skillSetOf, type ProjectVisibility, type SwarmProject } from './projects.js'

export type Role = 'owner' | 'collaborator' | 'viewer'
export interface Person {
  /** Own future task decisions; absent keeps Auto approve. */
  approvalMode?: import('./taskApproval.js').ApprovalMode
  id: string
  email: string
  role: Role
  generation: string
  /** Their own short status (profile.ts); only Swarm members read it. */
  status?: import('./profile.js').PersonStatus
  /** Their time zone's IANA name ("Asia/Ho_Chi_Minh"), as their own app reports it (profile.ts); absent until it has.
   *  Only Swarm members read it, for the local time on a person's card. */
  timeZone?: string
  /** Their own avatar (profile.ts); only Swarm members read it. */
  avatar?: import('./profile.js').Avatar
  /** The name they chose (usernames.ts), or one kept for them; absent, readers work out their default. Only members read it. */
  username?: string
  /** The name they show (personNames.ts), such as "Minh Nguyen"; absent, the Swarm shows their username. Only members read it. */
  name?: string
  /** `domain`: joined by themselves as someone at the owner's email domain (autoJoin.ts), so the people list says so. */
  joinedVia?: 'domain'
}
export interface AgentConfiguration {
  engine: string
  model: string | null
  effort: string | null
  contextWindow: number | null
  engineVersion: string | null
}
/** Why a crew member must leave its machine (crewKeep.ts). */
export type CrewTrouble = 'offline' | 'signed-out' | 'quota' | 'disk' | 'quota-low' | 'unstable'

export interface Agent {
  id: string
  projectId?: string
  machineId: string
  harnessId: string
  machineOwnerId: string
  contributorId: string
  membershipGeneration: string
  hostGrant?: string | null
  name: string
  /** A stable member name; native session and routing names remain in `name`. */
  displayName?: string
  /** The kind an older client started or added it as, kept for older readers. Absent reads as builder (agentRole); the Lead
   *  is derived from leadId. It decides nothing (project instructions, phase 4): roleNameOf names an agent without a role
   *  name by it. */
  role?: AgentRole
  /** The custom role an older client started, added or assigned it in, kept for older readers (projects.ts agentSetRole). */
  roleId?: string | null
  /** The role it was started in, free text from the project's instructions (project instructions, phase 2). The server checks
   *  nothing against them. Absent on agents from before: reads name one by what it is (instructions.ts roleNameOf). */
  roleName?: string
  /** `awaiting`: its task's work ended (finishWorker), shown and read by no command; `keep` and `stop`: asked for
   *  (agent.release, tidy.ts). Kept when its group receives a new brief. */
  workDecision?: 'awaiting' | 'keep' | 'stop'
  /** When its Lead last decided keep: a kept worker is idle from then (tidy.ts). */
  keptAt?: number
  /** When its last idle spell began, once its coordinator was told of it (tidy.ts idleNotices): one notice per spell. */
  idleNoticedAt?: number
  /** Set while its stop is the server's idle stop (tidy.ts, Dee's rules-to-code decision, 2026-11-06),
   *  with the decision it had before: its host withdraws that stop when the session's folder has changes by the time it would
   *  close it (agent.stopRefused). */
  idleStop?: { previous: 'awaiting' | 'keep' | null }
  releaseId?: string
  /** Set while it is one of its project's crew (crew.ts): its host keeps it alive, and no idle path closes or removes it.
   *  `by` is the person's or PM agent's id that marked it. */
  crew?: { role: string; lane?: string; at: number; by: string }
  /** A person's request to move this Product Manager to another engine or account (lead.switch), carried out by its host.
   *  `id` is the operation that asked; `claimedUntil` is set once the host took it (agent.switchClaim). */
  /** The switch request the last rebind settled, until its result arrives: that result is the one line the chat gets, and
   *  it still tells the machine owner who asked. */
  switchLanded?: { id: string; requestedBy: string; candidateAgentId?: string }
  switchRequest?: { id: string; engine: string; profileId: string; targetMachineId?: string; model?: string; effort?: string; requestedBy: string; at: string; claimedUntil?: string }
  /** A Buddy's owner asked its machine to move it onto a model on the Swarm's grid, or back to their subscription (null)
   *  (buddyModel.ts). What they were shown is kept for the line the result writes: the model's name, who serves it and its
   *  window, the smallest any serving machine reported. One at a time; the result or the liveness sweep's lease drops it. */
  modelRequest?: { id: string; gridModel: string | null; gridName?: string; name?: string; servedBy?: string[]; machines?: string[]; contextWindow?: number; requestedBy: string; at: string
    /** Set when the Swarm sent the Buddy home by itself: the model hit a limit, kept failing, or nobody served it. */
    reason?: 'limit' | 'failing' | 'gone'
    /** Only its thread sessions move: a move home left one on a shared model (buddyModel.ts, task #3810). */
    sessionsOnly?: true }
  /** A Buddy thread session that stayed on a shared model when its Buddy went home (task #3810): why it was sent home, and how
   *  many times it stayed. The liveness sweep asks its machine to move it home again, three times at most (buddyModel.ts). */
  homeOwed?: { reason?: 'limit' | 'failing' | 'gone'; tries: number }
  /** When the liveness sweep first found nobody serving the Buddy's `gridModel` (ms): two minutes on, it is sent home. */
  gridModelUnservedSince?: number
  /** The name its owner was shown for the Buddy's `gridModel`, for the lines after nobody serves it any more. */
  gridModelName?: string
  /** The account it runs in on its machine once a switch moved it; absent for the machine's default account. */
  profileId?: string
  /** Captured from the original Swarm launch, never inferred from a later live session with the same id. */
  startedSession?: { creationId: string; sessionId: string; createdAt: string }
  /** The model on the Swarm's grid its start named, which its engine never reports. Kept here because a command does not
   *  load a finished start (parts/load.ts loadActive), and the leaderboard counts every assignment by it (review of #1808). */
  gridModel?: string
  /** Its start named no model, so it runs its engine's own: rated by the policy's `default` row for life (rules.ts
   *  agentTarget). Kept here for the same reason as [gridModel]: a command never sees the finished start (live bug 10-29). */
  launchedDefault?: true
  configuration: AgentConfiguration
  /** The last configuration operation fences delayed observations, including re-contribution. */
  configurationVersion?: string
  /** Fences a repeated Change agent report without rolling back later model observations. */
  replacement?: { previousHarnessId: string; harnessId: string }
  /** When a reading first showed its session gone or its host confirmed a stop; cleared when it is back (machines.ts). */
  downSince?: string
  /** Written by the two-hour down wake-up that lost work replaced (liveness.ts); older states may still carry it, never shown. */
  downNamed?: string
  /** Its last task was lost (liveness.ts): routing leaves it out, even once that task is cancelled or reassigned, until it
   *  finishes a new task, a person assigns it work by hand, or its terminal is replaced (commands.ts). */
  lostTask?: { conversationId: string; assignmentId: string; reason: string; at: number; resumeAt?: string }
  /** A crew member the Swarm put to sleep after an idle hour (crewKeep.ts): its host closes the session and keeps its folder;
   *  work.assign clears it and the host reopens it in place. `folderDropped` once a cleanup rule removed its folder, so a
   *  wake starts it fresh. Set only by the server. */
  asleep?: { since: number; folderDropped?: boolean }
  /** When a reading first showed its session gone, in the last hour, at most five (machines.ts recordAgentPresence): a crew member
   *  that stops three times in an hour is moved, not reopened in place (crewKeep.ts, task #3662). */
  stops?: number[]
  /** A crew member being moved off a failing machine (crewKeep.ts): its start on [machineId] takes over under the same name;
   *  until then nothing is assigned to it and its old host closes the session. Set only by the server. */
  movedTo?: { machineId: string; startId: string; reason: CrewTrouble; at: number }
  /** The agent this crew member took over from on a move, so its history reads as one member. */
  movedFrom?: { agentId: string; machineId: string; reason: CrewTrouble; at: number }
  /** The machine whose start of this member's move failed, and when: not picked again for MOVE_REFUSED_WAIT_MS (crewKeep.ts). */
  crewMoveRefused?: { machineId: string; at: number }
  /** A move needed but no machine could take it: said once in the project chat until the trouble changes. */
  crewStuck?: CrewTrouble
  /** A usage limit seen on its terminal; routing skips the agent until then. Shown as null once passed (terminal.ts). */
  limitedUntil?: string | null
  /** Terminal alert episodes in progress, so each one posts a single row (terminal.ts). */
  alerting?: Array<'prompt' | 'limit' | 'model'>
  /** Set once its session is a Lead or in a private conversation, and kept until the session leaves: nobody but its
   *  machine's person watches it (projects.ts canWatchAgent). */
  confidential?: true
  /** Set by its contributor or its project's Lead (profile.ts); absent shows the pattern Desktop draws from its name. */
  avatar?: import('./profile.js').Avatar
  /** A Buddy (buddies.ts): the person it brainstorms with, at the membership they added it in. Its role stays a builder's
   *  for older readers; this is what makes it a Buddy, and what refuses it every command but its own chat and proposals. */
  buddyOf?: { personId: string; generation: string }
  /** A Buddy that reads every project its person reads (buddies.ts; Dee, 10-31): the main Buddy of a Swarm Buddy chat, or a
   *  plain session there. It has no project and writes nowhere but its own chat. A project session has its project instead. */
  buddyScope?: 'swarm'
  /** A Regular agent (agent.new, task #4116): in no project but its active task's (projects.ts agentProjectId). */
  regular?: true
  /** The one project this Member belongs to (task #4540; spec 2026-11-07-members-and-leads): picked in Cmd-N or when its person
   *  joined. Readers get it in the derived row, never in this part (read/views.ts), and only when they read that project. A
   *  Lead's is the project it leads, derived (agentKind.ts ledProjects). Cleared when the project is deleted. */
  mainProjectId?: string
  /** A Member's own mark (members.ts, task #4697), and a helper's: the Member it helps. Set by the server alone, at its start;
   *  its host reads them in the agent's row to reopen a woken one in its folder (#4698). */
  member?: { projectId: string }
  helperOf?: { agentId: string; harnessId: string }
  /** Its project set up on its computer, as its own host reported (agent.setUp, #4698): the commands it ran, or why it failed.
   *  A Member on a host that reports it takes no task until it is set up (members.ts setUpReady). */
  setUp?: { projectId: string; at: number; steps?: string[]; failed?: string }
  /** The private project a Regular agent first worked in: its one conversation holds that project's content, so it takes tasks
   *  only there from then on (projects.ts regularMayWorkIn; security review 2 of #4116). Set at its assignment, never cleared. */
  privateProjectId?: string
  /** A Buddy that reads one project and writes into it (Dee, 10-31): a project session, or the one Buddy's session in an older
   *  project chat. Its host never widens its reads beyond its folder (cli buddyGuard wide mode), which could hold another
   *  project's clone. */
  buddyNarrow?: true
  /** A Buddy's thread session (buddySessions.ts): it hears and answers only the thread rooted at `thread`, and reads the main
   *  chat only up to `from`, the sequence before the message that started it. The main Buddy has none. */
  buddySession?: BuddySession
  /** Joined on a Harness Team account's machine: kept, so a machine row that went never brings back the rules of an
   *  ordinary machine (projects.ts teamSessionAccess, security re-review of #2089). */
  teamAccount?: true
  /** A crew member woken by new work (crewTimes.ts startWake): when, and the task that woke it, until a machine reading shows
   *  its session running again (`runningAt`, the first reading that did) and the wake's timing row is written (task #3462). Set
   *  only by the server. */
  crewWaking?: { at: number; conversationId: string; runningAt?: number }
}
/** A thread session's thread root and the main chat's last sequence it may read (buddySessions.ts). A project session also
 *  names its project (buddies.ts; Dee, 10-31): it reads that project alone, and is the only Buddy that writes into it. */
export interface BuddySession { thread: string; from: number; projectId?: string }
/** A Buddy chat's live or starting thread session (buddySessions.ts); it leaves when the session ends. `agentId` once it runs;
 *  `waiting`, the person's messages sent while it started, delivered to it when it joins. */
export interface BuddySessionEntry { thread: string; startId: string; agentId?: string; at: number; waiting?: string[] }
export type AgentRole = 'builder' | 'reviewer'
export const agentRole = (agent: Pick<Agent, 'role'>): AgentRole => agent.role ?? 'builder'
export interface AgentStartRequest {
  conversationId: string
  role?: AgentRole
  roleId?: string
  /** The agent's role name (Agent.roleName), kept on it once it starts. */
  roleName?: string
  machineId: string
  engine: string
  model?: string
  effort?: string
  name: string
  cwd: string
  worktree: boolean
  branchRef?: string
  /** Stamped by the server for Team-written code (teamWritten.ts): the agent reads no project settings and its folder gets no trust. */
  projectSettings?: 'off'
  permissionMode?: string
  codexHome?: string
  gridModel?: string
  gridName?: string
  /** The heavy work the task declared it runs on its machine (a heavy build, end-to-end tests): later routes count such a start
   *  on its machine for a few minutes, before the machine's reading shows it (cli superTabs/machineFit.ts, Scholes's goals,
   *  piece 5). Its requirements ask only the least the work runs with, so this says what it is. */
  heavy?: Array<'build' | 'e2e'>
  requirements: { memoryBytes: number; diskBytes: number; maxCpuPercent: number; tools: string[]; devices: string[]; quotaRequired: boolean }
  /** A Buddy's start (buddies.ts): written by buddy.create alone, never taken from an agent.start. */
  buddyOf?: { personId: string; generation: string }
  /** A Swarm-wide Buddy's start (Agent.buddyScope), written by buddy.create or message.send alone. */
  buddyScope?: 'swarm'
  /** A Regular agent's start (agent.new, task #4116): in its person's own chat, in no project's folder. Written by the server alone. */
  regular?: true
  /** The main project its person picked (agent.new, buddy.create; task #4540), kept on the agent when it starts. */
  mainProjectId?: string
  /** A Member's own start (members.ts, task #4697): its host sets the project up once in this folder. Written by the server
   *  alone, with `regular` and `mainProjectId`. */
  member?: { projectId: string }
  /** A helper's start (members.ts): made from its Member's ready setup on the Member's computer, for the task it starts
   *  in. Written by the server alone. */
  helperOf?: { agentId: string; harnessId: string }
  /** The commands its Member recorded setting the project up (agent.setUp), for a helper's host to repeat. */
  setUpSteps?: string[]
  /** A one-project Buddy's start (Agent.buddyNarrow), written by message.send alone. */
  buddyNarrow?: true
  /** The person's messages in an older project chat its start waits on, delivered when it joins (ids only). */
  buddyWaiting?: string[]
  /** The projects a Swarm-wide Buddy's folder holds, one read-only worktree each, made from that project's own checkout on its
   *  machine (spec: Folder). Ids, names and folders only. */
  buddyProjects?: Array<{ id: string; name: string; cwd: string }>
  /** The offered account selected for a destination PM switch. */
  profileId?: string
  /** A crew member's move (crewKeep.ts): the agent its start takes over from once it runs. Written by the server alone. */
  crewMoveOf?: string
  /** A bounded handoff note transferred from the source host, visible only in the destination host's start row. */
  handoffNote?: string
  handoffSourceAgentId?: string
  handoffChangeId?: string
  /** A Buddy thread session's start (buddySessions.ts): written by message.send with newSession alone. Ids only, never text:
   *  starts are listed to the Lead. */
  buddySession?: BuddySession
  /** A project's Product Manager's start (leadStart.ts): written by lead.start alone, never taken from an agent.start. Its
   *  agent becomes the Lead of the project's Lead conversation once it runs. */
  leadFor?: { projectId: string; personId: string; generation: string; switchId?: string }
}
export interface AgentStart {
  poolGeneration?: string
  poolSettled?: boolean
  routeDecisionId?: string
  id: string
  creationId: string
  actorKey: string
  contributorId: string
  membershipGeneration: string
  machineOwnerId: string
  hostGrant: string | null
  request: AgentStartRequest
  harnessId: string | null
  dispatched: boolean
  /** When its host was asked to launch it; a start not running 3 minutes later fails, or 15 minutes later while its machine
   *  reports it preparing (liveness.ts). */
  dispatchedAt?: number
  /** The CLI version its machine's daemon had connected with when it was dispatched (store.ts machineFacts): a failed start
   *  says nothing about that machine once it runs another version (cli routeCommand.ts `stalled`). */
  dispatchedVersion?: string
  /** When it was asked for (absent on starts from before 2026-10-29): a Buddy's fails if its machine never takes it, and a
   *  task's start never launched leaves the task orphaned (liveness.ts). */
  requestedAt?: number
  /** Why its machine holds it without launching it, from the machine's report (cli superTabs/machines.ts), with when it was first
   *  told: gone once the start launches or fails. Read whole by the readers of its raw reason, as what it means by the rest. */
  waiting?: { reason: string; at: number }
  /** On reads only, never stored: its machine's fresh report says it is preparing (machines.ts startPreparing). */
  preparing?: true
  error: string | null
}
/** `needs_human`: the agent needs a person's decision (its result is the question). `blocked`: it cannot go on (its result
 * says why). Both stay active work; the machine running the agent alerts its Harness Pro (cli/src/superTabs/attention.ts).
 * `lost`: its agent died, stalled or hit a limit (liveness.ts); no longer active, so the Lead assigns it again or cancels it. */
export type WorkStatus = 'planned' | 'working' | 'needs_human' | 'blocked' | 'review' | 'done' | 'stopped' | 'cancelled' | 'reconciling' | 'lost'
/** The first line of the system row `work.status` writes for each status an agent sets (commands.ts); catchUp.ts reads it back. */
export const STATUS_LABELS = { working: 'Working', needs_human: 'Needs a human', blocked: 'Stuck', review: 'Ready for review', done: 'Done',
  stopped: 'Stopped' } as const satisfies Partial<Record<WorkStatus, string>>
export interface Check {
  id: string
  description: string
  independent: boolean
  evidence: string | null
  passedBy: string | null
  /** Each checker's latest verdict during this attempt (checkVerdicts.ts); `evidence` and `passedBy` are derived from them.
   *  Absent until the first verdict recorded since verdicts were kept. */
  verdicts?: CheckVerdict[]
}
/** One checker's verdict on a check: its actor key (`agent:ID` or `person:ID`), what it found and when. */
export interface CheckVerdict { by: string; passed: boolean; evidence: string; at: number
  /** The checker's name when it gave the verdict: once it leaves the Swarm, the line that clears its failure still names it
   *  (#2656). Absent on verdicts given before. */
  name?: string
  /** The task's pull request it read and that pull request's head commit then (Dee, #3394): the whole commit id the checker
   *  named; for a person who named none, the one the PR watch last read. It counts only while that is the head, or the head's
   *  patch is the same (checkVerdicts.ts verdictCounts); with no head, only while no head of its pull request is watched. */
  pullRequest?: string
  head?: string
  /** That head's patch id (pullRequestPatch.ts), once the watch has read it. */
  patch?: string
  /** The branch it read the pull request's diff against, as the checker named it (a person's, the one watched): the same head
   *  against another branch is another diff (security review of #3218, round 4), and no base the server infers is known to
   *  be the one read (review round 7). It counts only on this base. */
  base?: string
  /** The pull request's head it stopped counting at, while it does not count: empty while its own pull request's head is not
   *  read yet. */
  stale?: string }
/** A linked pull request's head commit as the PR watch last read it, with its patch id (pullRequestPatch.ts): null when the
 *  patch could not be read, so only that exact head counts (#3394). */
export interface PullRequestHead { head: string; patch: string | null; at: number
  /** The branch it merges into as the watch read it: a new one is read again like a new head, as the patch id names it
   *  (security review of #3218, round 3). Absent on a head recorded before. */
  base?: string
  /** The heads whose verdicts this one carries, newest first, at most CARRIES_KEPT: it is git's own merge of the first and
   *  main, the first of the next, and so on (mergeCarry.ts, task #3553). Absent on any other head. */
  carries?: string[]
  /** Set by the PR watch once GitHub shows the pull request closed (merged or not): a task's checks never count at it while
   *  another linked pull request is open (checkVerdicts.ts checkedPullRequest, task #3953). Cleared when it is open again. */
  closed?: true }
export interface Assignment {
  id: string
  agentId: string
  status: WorkStatus
  configuration: AgentConfiguration
  /** `contributorId`: whose login its agent runs under (Agent.contributorId), so the person's Tasks feed keeps it after the agent
   *  is closed (read/feedIds.ts). Absent on assignments made before 2026-11-07. */
  execution: { machineId: string; harnessId: string; machineOwnerId: string; contributorId?: string }
  result: string | null
  /** Explicit progress fences delayed recording gaps; absent on older backends. */
  recordingProgress?: { at: number; revision: number }
  /** Its agent owns it until then; progress renews it (liveness.ts). Absent on assignments from before leases. */
  leaseUntil?: number
  /** Its agent's last progress the lease saw, for the Lead's wake-up when it is lost. */
  progressAt?: number
  /** When its crew member was told it had been 2 hours without progress (dispatch.ts crewClock): once per quiet spell. */
  nudgedAt?: number
  /** While it needs a human: the person its agent asked (work.status with ask), whom its wait names (liveness.ts). */
  askedOf?: string
  /** While it is blocked or needs a human: why it waits (heldReason.ts). Absent on a hold from before reasons. */
  hold?: import('./heldReason.js').HeldReason
  /** When someone else's verdict found problems in a working hand-off of the older built-in skills, which then stops waiting
   *  for its review (liveness.ts waitingForReview). Its next status clears it. */
  reviewFoundAt?: number
  /** On a linked task (reviewOf): when its own Reviewer's verdict in the build asked for changes. Its quiet time does not count
   *  until the build's next Ready clears it (liveness.ts waitingForRevision). */
  changesRequestedAt?: number
  /** On a linked task: when its agent last wrote to the build's Engineer, as a verdict usually is. It holds the quiet time while
   *  the Engineer isn't waiting on a review, until the build's next Ready clears it (liveness.ts waitingForRevision). */
  toldEngineerAt?: number
  /** A two-review task's hand-overs and reviewers' verdicts, from the automatic reviews (#2382) before project instructions;
   *  never written since (phase 4: the server opens and counts no review), kept on older rows. */
  handoffs?: number
  verdicts?: ReviewVerdict[]
  /** A handed task brought back to its Engineer (handed.ts reopenHanded): when, and why (a No verdict, red CI, a conflict).
   *  Its Engineer's own status, check or post in the task picks it up and clears it; with none in REOPEN_OWNER_MS the task is
   *  lost, so anyone free takes it (liveness.ts). The next status clears it too. */
  reopened?: { at: number; why: string }
  /** Why and when it was lost (status `lost`); after a usage limit whose screen gave a reset time, when its own agent may
   *  take it back (work.resume) unless it was handed on first. */
  lost?: { reason: string; at: number; resumeAt?: string }
}
/** One reviewer's (actorKey) verdict on a two-review task's independent checks, on an older row (Assignment.verdicts). */
export interface ReviewVerdict { by: string; passed: boolean; handoff: number; review?: string }
/** The hand-over an automatic review of a two-review task was opened for, on an older row (Conversation.reviewStamp). */
export interface ReviewStamp { assignmentId: string; handoff: number }
export interface WorkTask {
  goal: string
  changes: string
  constraints: string
  owns: string[]
  requires?: TaskRequirement
  /** `strong`: big, hard or risky work, which the crew's dispatch hands only to a member on a strong model (dispatch.ts, #3576); a task
   *  that wants two reviews counts as strong unless this says `standard`. */
  strength?: 'standard' | 'strong'
  /** What its reviews check first, and how many independent reviews it wants: written into its brief (renderWorkTask), which
   *  whoever opens its review reads. The server opens and counts no review (project instructions, phase 4). */
  review?: ReviewPlan
}
/** A task's review plan (#2382; nightly reflection 10-30: the Lead hand-sent a focus to 20+ reviews that day). `focus` and
 *  `reviews: 2` are said in its brief, so the agent opening its review passes them on (project instructions, phase 4). */
export interface ReviewPlan { focus?: string; reviews?: 1 | 2 }

/** How many independent reviews [task] wants: 2 only when its review plan says so. */
export const reviewsWanted = (task: WorkTask | undefined): number => task?.review?.reviews === 2 ? 2 : 1
/** Where a task can be done at all (2026-10-27: a task to check a device plugged into one person's Mac was routed to another
 *  machine by policy order). `machines`: it runs only there, or on a Mac's Harness Team account of one of them. `devices`:
 *  full paths every start for it asks its machine to check (cli superTabs/capacity.ts). Never in the rendered brief, since
 *  a reader may not see the machine. A reader is handed only the machines they see, and how many others (`unseenMachines`). */
/** `access`: what the work needs to reach, by the names machines list it under (machineAccess.ts, task #3047). */
export interface TaskRequirement { machines?: string[]; devices?: string[]; access?: string[]; unseenMachines?: number }

/** The machines a reader sees: listed in their visible state, or running an agent they see. */
export const seenMachineIds = (visible: Pick<SuperTabState, 'machines' | 'agents'>): Set<string> =>
  new Set([...(visible.machines ?? []).map(m => m.machineId), ...visible.agents.map(a => a.machineId)])

/** [group] with its requirement as a reader who sees [seen] may read it. The same group read again gives the same result. */
export function withSeenRequirement<T extends Pick<Conversation, 'task'>>(group: T, seen: ReadonlySet<string>): T {
  const requires = group.task?.requires
  if (!requires?.machines?.some(id => !seen.has(id))) return group
  const machines = requires.machines.filter(id => seen.has(id))
  return { ...group, task: { ...group.task!, requires: { ...requires, machines,
    unseenMachines: (requires.unseenMachines ?? 0) + requires.machines.length - machines.length } } }
}

export const TWO_REVIEWS = 'Two independent reviews, each by a different Reviewer.'
export function renderWorkTask(task: WorkTask): string {
  const review = [...task.review?.focus ? [task.review.focus] : [], ...reviewsWanted(task) === 2 ? [TWO_REVIEWS] : []]
  return `Goal:\n${task.goal}\n\nChanges:\n${task.changes}\n\nConstraints:\n${task.constraints}\n\nOwns:\n${task.owns.map(area => `- ${area}`).join('\n')}`
    + (review.length ? `\n\nReview:\n${review.join('\n')}` : '')
}

export interface Conversation {
  /** Person decision, separate from execution status for old clients. */
  taskApproval?: import('./taskApproval.js').TaskApproval
  id: string
  /** The removed Swarm-wide Leads conversation, still stored in an older Swarm (leadsRemoved), a person's Buddy chat in a
   *  project (buddies.ts), or their one Buddy chat for the whole Swarm, with no project (`swarm-buddy`, buddies.ts
   *  openSwarmBuddyChat; Dee, 10-31): a kind of its own, so an older release parks it unread (parkLaterConversations) instead
   *  of reading it as a project's. Absent on every other conversation. */
  kind?: 'leads' | 'buddy' | 'swarm-buddy' | 'agent-chat'
  projectId?: string
  /** Stable, tab-local workgroup reference. Lead has no number. */
  number?: number
  title: string
  leadId: string | null
  agentIds: string[]
  archived: boolean
  brief: string
  task?: WorkTask
  /** The process when this task was opened; a Simple task stays Simple if the project returns to Full (#3896). */
  process?: import('./process.js').ProjectProcess
  /** A review group names the group whose work it reviews; only a Reviewer is assigned it, and a Reviewer nothing else. */
  reviewOf?: string
  /** A Harness Team agent was assigned to build this task, or GitHub shows the app's bot pushed to its branch: its code runs
   *  only in a Team account (teamWritten.ts, audit H2). */
  teamWritten?: true
  /** What set [teamWritten] (#3304): `assigned` (a Team agent given the task) and `branch` (a bot's push on a branch a start
   *  named) are never cleared; `pushed` names the pull requests GitHub showed a bot's push among, and only a clean read of all
   *  of them clears it. Absent on a mark from before #3304, which a join may have set. */
  teamWrittenBy?: { kind: 'assigned' | 'branch' } | { kind: 'pushed'; pulls: string[] }
  /** A step of the task `reviewOf` names (task steps design, 2026-11-02): its name as the instructions give it, in any
   *  language. Readers show it inside its task, never as a task of its own. Absent on a linked group opened before steps. */
  step?: string
  /** An automatic review's hand-over of a two-review task (#2382); never written since project instructions, phase 4. */
  reviewStamp?: ReviewStamp
  checks: Check[]
  assignment: Assignment | null
  lastMessageSequence: number
  /** The sequence of its newest message in the main stream: a reply only in its thread leaves it (threads.ts). Absent until
   *  this conversation's first message after threads; readers fall back to lastMessageSequence. */
  lastMainSequence?: number
  /** The sequence of its newest main-stream message from a person, not a system row (parts/commit.ts): what makes a task's
   *  sidebar row bold (Huy, 11-03, #2427). Absent until a person's first message after this was added; readers read 0. */
  lastPersonSequence?: number
  /** When a person last wrote to its project's coordinator here: any message in the project chat (threads included), or one
   *  reaching the coordinator in another chat of the project (parts/commit.ts). The built-in wake asks the coordinator to save
   *  what it was taught only after one (pmSchedule.ts; task #3022). Absent until then. */
  heardAt?: number
  /** When a person last talked with each agent here, by agent id (parts/commit.ts): `person`, their last message that reached
   *  it; `answer`, its own post to people after that one. An agent a person is chatting with is never idle (tidy.ts idleSince,
   *  task #3816). Ids and times only, the last hour; hidden from readers. Absent until a person talks with an agent here. */
  talkedAt?: Record<string, { person: number; answer?: number }>
  /** Linked GitHub pull requests, including links older than the latest message page. Absent in older snapshots. */
  pullRequestUrls?: string[]
  /** The pull requests its own code is in, which GitHub's push read covers for its Team-written mark (teamWritten.ts, task
   *  #3554): those its brief, title, assignment's result, checks' evidence and merge record name, never links in posts. [] from
   *  its creation; absent on a conversation from before, which reads what it recorded instead (codePullRequests). */
  codePullRequestUrls?: string[]
  /** Pull requests the PM or the task's Engineer unlinked from it, newest last, at most UNLINKS_KEPT: the task's history of
   *  them, and what keeps a later post's link from linking one again (commands.ts conversation.unlink, task #3953). */
  unlinkedPullRequests?: Array<{ url: string; by: string; reason: string; at: number }>
  /** 'server' on a step the server opened for a handed task (commands.ts openReviewSteps, task #3602): an agent's step of its
   *  kind is then refused as a double. Absent on a step an agent or a person opened, and on older ones. */
  openedBy?: 'server'
  /** When its brief was last set (conversation.create, work.define): a person's rule moved into this task leaves the
   *  instructions only for a pull request GitHub says merged after it (ruleGuard.ts rulePlaces, #3463). No command writes
   *  it otherwise. Absent on a task from before. */
  briefAt?: number
  /** What its Engineer was already told of each linked pull request, newest first (pullRequestEvents.ts): absent until read. */
  pullRequestEvents?: Record<string, string[]>
  /** Each linked pull request's head and patch id as the PR watch last read them (#3394): what check verdicts count against.
   *  Absent until the watch reads one. */
  pullRequestHeads?: Record<string, PullRequestHead>
  /** Each linked pull request's check state as the PR watch last read it, `green`, `red` or `running` (pullRequestEvents.ts
   *  checksStateOf, task #3827): what the board's Done cards say. Written only when it changes; absent until the watch reads one. */
  pullRequestChecks?: Record<string, import('./pullRequestEvents.js').ChecksState>
  /** The people who posted here, newest last, at most four (stuck.ts noteWriter, task #3915): whom a stuck line tags. */
  writers?: string[]
  /** The stuck line this task's people were told, until it is fixed (stuck.ts, task #3915): its reason's key, the line, whom it
   *  tagged and what its fix says. */
  stuck?: { key: string; messageId: string; tagged: string[]; fixed: string }
  /** Its steps and reviews (groups whose reviewOf is this one), newest last, at most 200 (production's most was 14): what a new
   *  pull request head re-derives the checks of, dormant ones included (#3394). Empty from a task's start; absent on a task
   *  from before, whose PR watch looks them up once (pullRequestEvents.ts listedSteps). */
  stepIds?: string[]
  /** Its Linux test step, waiting for a Linux machine the project can test on (osSteps.ts, task #4278): set by a Ready that
   *  found none, gone once the step opens. */
  waitingLinuxStep?: import('./osSteps.js').WaitingStep
  /** Its Windows test step, waiting likewise for a Windows machine (osSteps.ts, task #4410). */
  waitingWindowsStep?: import('./osSteps.js').WaitingStep
  /** Its messages drawn as live cards: its task and each linked pull request (cards.ts). Absent until its first card. */
  cards?: import('./cards.js').GroupCards
  /** The last sequence given to a message here. Each conversation numbers its own messages (store by parts). */
  messageSeq?: number
  /** The sequence of its last message that counts toward its project's reports (projectUpdates.ts). */
  reportSeq?: number
  /** Out of first loads and changes: work done or cancelled and quiet for a day, or archived by hand. A message wakes it. */
  dormant?: boolean
  /** When its last message was written (ISO). */
  lastActivityAt?: string
  /** A private conversation: only these people and the project's Lead read it (projects.ts canReadGroup). */
  audience?: import('./parts/types.js').Audience
  /** The last attempt here that was lost: its agent's status and checks for it are refused, even after reassignment. Where it
   *  ran (machine and engine) stays too, so routing the work again avoids that account even once its agent is gone. */
  lostAttempt?: { id: string; agentId: string; machineId?: string; engine?: string }
  /** Counts reaction changes here (reactions.ts), so readers see a new reaction on an older message. */
  reactionSeq?: number
  /** The tasks its work goes on in, as its cancel's reason names them (commands.ts goesOnIn, task #4462): a duplicate, or
   *  work folded or split into others. It leaves people's Tasks feeds and stays in its project's archived list, which can open them. */
  foldedInto?: string[]
  /** A durable proposal on this card (#3817); retained when its accepted work becomes a task. */
  proposal?: import('./proposalCards.js').ProposalRecord
  /** A Buddy chat's owner messages its Buddy already proposed for (buddies.ts): each asks once. */
  proposals?: string[]
  /** The name a Buddy chat's owner chose for their Buddy (buddies.ts renameBuddy): kept here, which outlives the Buddy, so
   *  one added again takes it. Absent: the default, "<person>'s Buddy". */
  buddyName?: string
  /** A person's main Buddy chat (buddies.ts swarmBuddyChatId) lists their other Buddies' chats, oldest first, so they load
   *  with it, whose id every command can derive (task #3818). At most the Swarm's Buddy cap. Absent: one Buddy. */
  buddyChats?: string[]
  /** This Buddy chat's Buddy is its person's default (task #3818): their lines go to it. One per person; with none marked, the
   *  main chat's. */
  buddyDefault?: true
  /** A Buddy chat's live and starting thread sessions (buddySessions.ts); absent while it has none. */
  buddySessions?: BuddySessionEntry[]
  /** An older project Buddy chat whose person was told their one Buddy cannot start there now (commands.ts buddyDownLine):
   *  told once per outage, so absent again once one can start. */
  buddyDownTold?: true
  /** The person who asked for this work: whoever opened it, or the person its Lead named (leaderboard/record.ts). */
  requesterId?: string
  /** What the leaderboard counts here (leaderboard/record.ts); bookkeeping readers never get whole. */
  ledger?: import('./leaderboard/record.js').GroupLedger
  /** When a verified release carried its last recorded merge to people, and the release tags that did (releases.ts, task #3405):
   *  the board's Shipped. Absent while a release it needs has not gone out, and on work merged before the server recorded it. */
  released?: { at: number; tags: string[] }
  /** While it is on its project's release list (releases.ts): the parts it still waits for, as `desktop` or `cli`; empty until
   *  its pull request's files are read. Absent otherwise, and cleared once it is released or leaves the list (River, 11-05). */
  releasing?: import('./releases.js').ReleaseComponentId[]
  /** Whether its task is moving, waiting on purpose or stuck, as the time checks last found it (liveness.ts recordTaskStates). */
  liveness?: TaskLiveness
  /** Its last step up from a cheaper model: written when a grid attempt's first review fails (commands.ts reviewFailed, goals
   *  piece 4; before project instructions also by the server's step up). Nothing is cancelled: the route reads it to leave the
   *  grid out of the next attempt, route records carry it for the costs report, and the leaderboard reads it. */
  stepUp?: StepUp
  /** The last route, start or assignment on its task by an agent of its project, or its coordinator's post there (commands.ts). */
  leadAction?: { kind: 'assign' | 'route' | 'start' | 'post'; at: number }
  /** Its place in its project's Next up (taskQueue.ts), set by work.queue. Absent: it sorts by its number. */
  queueRank?: number
  /** The day (YYYY-MM-DD) its work should not start before, a promise the PM marks with work.queue. */
  notBefore?: string
  /** Why its not-before date holds it (heldReason.ts), set with the date by work.queue. Absent on a hold from before reasons. */
  hold?: import('./heldReason.js').HeldReason
  /** A pause by someone who steers its project (boardRights.ts, task #3819): who (actorKey), when and why. While set, the task
   *  is not handed out (dispatch.ts) or chased by the PM's sweep (pmSchedule.ts), and shows held (pulse.ts). */
  paused?: { by: string; at: number; reason?: string }
  /** How urgent its task is (taskPriority.ts), set by conversation.create and work.priority. Absent on a step, a chat and a task
   *  from before priorities, which reads as P2. */
  priority?: import('./taskPriority.js').TaskPriority
  /** The lane its PM or a person put it in (dispatch.ts laneOf), set by work.lane, as the lane table writes it. Absent: its
   *  owned paths choose. */
  lane?: string
  /** Its lane as the dispatch hands it out (dispatch.ts laneOf), stored when its paths or lane change (stampLane), so reads
   *  only copy it. Absent on a chat, a step, and a task from before; null when no lane owns its paths. */
  handOutLane?: string | null
  /** The member it waits for, without active work (dispatch.ts): its builder, after another agent's failed check, red CI or a
   *  merge conflict. The next assignment clears it. */
  pin?: { agentId: string; why: 'findings' | 'ci' | 'conflict'; at: number }
  /** What its project's PM owes here (pulse.ts): people's messages that reached it, not answered, reacted to or made a task
   *  yet, at most MAX_OWED. Bookkeeping: readers get it counted in the pulse, never this list. */
  owed?: import('./pulse.js').OwedAsk[]
  /** The PM's answers here (answers.ts): each message it answered, where and by which message, at most MAX_ANSWERED, so a
   *  second `answer` is refused with where the first is. Bookkeeping: never sent to readers. */
  answered?: import('./answers.js').AnsweredAsk[]
  /** Project-chat post limits: at most 50 asks, no text; bookkeeping hidden from readers (chatLimits.ts). */
  chatLimits?: import('./chatLimits.js').ChatLimits
  /** On a project's chat: its project's pulse as last worked out (pulse.ts recordPulse), which every read sends in `derived`. */
  pulse?: import('./pulse.js').Pulse
  /** On a task: its line on its project's status card as the server last wrote it (statusCard.ts noteTaskLines, task #4419).
   *  Readers get the lines in the project's `status` text (visibleState), never as a field. */
  statusLine?: import('./statusCard.js').StatusLine
}
/** A step up: the attempt it opened (2 or 3), the least quality from then on, why, when, and what the failed attempt left for
 *  the next one's brief; the failed start that caused it, if one did. */
export interface StepUp { attempt: number; floor: number; reason: string; at: number; carry: string; startId?: string
  /** A route record carries it already (commands.ts route.record): later routes of the task do not, so it counts once. */
  recorded?: true }
/** Absent while its task is working (its agent reported in the last 30 minutes; its last progress is its assignment's
 *  `progressAt`) or there is none. `waiting`: on a person (`personId`), a review, its stated
 *  blocker, the new revision of the build it reviews, or its agent's start. `quiet`: its agent has reported nothing for 30 minutes
 *  (`silent`), or it has been in review for 30 minutes with no linked task open (`review`). `orphaned`: nobody holds it — its
 *  agent was removed or lost it, or its start failed or never launched. `since`: when that began, as first recorded. */
export interface TaskLiveness {
  state: 'waiting' | 'quiet' | 'orphaned'
  why: 'person' | 'review' | 'blocked' | 'revision' | 'queued' | 'starting' | 'silent' | 'removed' | 'lost' | 'start-failed' | 'unstarted'
  since: number
  personId?: string
}

/** [url] as the project's own pull request, in the project's spelling of owner and repository (GitHub names are not case
 *  sensitive); null when it belongs to any other repository, whatever its name, since an owner is never guessed. Without a
 *  known GitHub repository nothing can be judged. */
export function projectPullRequestUrl(url: string, repositoryUrl: string | null | undefined): string | null {
  const own = githubRepository(repositoryUrl)
  if (!own) return url
  const match = url.match(/^https:\/\/github\.com\/([A-Za-z0-9_-]+)\/([A-Za-z0-9_.-]+)\/pull\/([1-9][0-9]*)$/)
  if (!match) return null
  return match[1]!.toLowerCase() === own.owner.toLowerCase() && match[2]!.toLowerCase() === own.name.toLowerCase()
    ? `https://github.com/${own.fullName}/pull/${match[3]}` : null
}

/** The GitHub pull request links in [text], each once, in order. With the project's [repositoryUrl], each is that repository's
 *  (in the project's spelling) and a link into any other repository is left out, so one pull request is one link. */
export const pullRequestLinks = (text: string, repositoryUrl?: string | null): string[] => [...new Set([...text.matchAll(/https:\/\/github\.com\/[A-Za-z0-9_-]+\/[A-Za-z0-9_.-]+\/pull\/([1-9][0-9]*)\b/g)]
  .filter(match => Number(match[1]) <= Number.MAX_SAFE_INTEGER).flatMap(match => projectPullRequestUrl(match[0], repositoryUrl) ?? []))]

/** The pull requests [group]'s own code is in (codePullRequestUrls). A conversation from before the list reads every link it
 *  recorded, posts' included: an access rule loses no protection it had (task #3554). */
export const codePullRequests = (group: Pick<Conversation, 'codePullRequestUrls' | 'pullRequestUrls'>): string[] =>
  group.codePullRequestUrls ?? group.pullRequestUrls ?? []

/** Adds the pull request links of [texts], its own code's sources, to [group]'s code list, and corrects the ones it holds. A
 *  conversation from before the list gets none: it keeps reading what it recorded (codePullRequests). */
export function appendCodePullRequestUrls(group: Conversation, texts: Iterable<string | null | undefined>, repositoryUrl?: string | null): void {
  if (group.codePullRequestUrls === undefined) return
  const urls = new Set(group.codePullRequestUrls.flatMap(url => projectPullRequestUrl(url, repositoryUrl) ?? []))
  for (const text of texts) if (text) for (const url of pullRequestLinks(text, repositoryUrl)) if (!unlinked(group, url)) urls.add(url)
  group.codePullRequestUrls = [...urls]
}

/** The most unlinked pull requests a task remembers. */
export const UNLINKS_KEPT = 50
/** Whether [url] was unlinked from [group]: no later text links it again. */
const unlinked = (group: Pick<Conversation, 'unlinkedPullRequests'>, url: string): boolean => !!group.unlinkedPullRequests?.some(entry => entry.url === url)

/** Adds the pull request links of [texts] to [group] and corrects the ones it holds, by the project's [repositoryUrl]. */
export function appendPullRequestUrls(group: Conversation, texts: Iterable<string | null | undefined>, repositoryUrl?: string | null): void {
  const urls = new Set((group.pullRequestUrls ?? []).flatMap(url => projectPullRequestUrl(url, repositoryUrl) ?? []))
  for (const text of texts) if (text) for (const url of pullRequestLinks(text, repositoryUrl)) if (!unlinked(group, url)) urls.add(url)
  group.pullRequestUrls = [...urls]
}
export interface Invitation {
  id: string
  email: string
  role: 'collaborator' | 'viewer'
  conversationId: string
  expiresAt: number
  /** Who sent it: the Workspace check at acceptance reads their role then (store.ts invite.accept). Absent on invitations
   *  from before it was recorded. */
  invitedBy?: string
}
/** An agent a machine's report removed as closed: as it was, and where it was (closedAgents.ts). */
export interface RemovedSession {
  machineId: string
  harnessId: string
  agent: Agent
  groupIds: string[]
  leadOf: string[]
  removedAt: number
}

export interface SuperTabState {
  version: 1
  id: string
  name: string
  project?: { machineId: string; cwd: string; repositoryUrl: string | null }
  projects?: SwarmProject[]
  /** The removed Leads conversation of an older Swarm, still stored (leadsRemoved); no read sends it. */
  leadsConversationId?: string
  /** Pairs of tasks ("a:b", sorted ids) whose Leads were told their owned code overlaps, so each pair is told once. */
  overlapAlerts?: string[]
  /** Read-only, for a Lead's own reads (visibleState): the active work of the other projects it may know about. */
  otherProjectsWork?: OtherProjectWork[]
  /** Read-only, for a project agent's reads (visibleState): the account every project's PM runs on, for the route's notes. */
  pmAccounts?: PmAccount[]
  /** Read-only, for the Swarm owner's reads (visibleState): the projects nobody owns, by name and size (projects.ts). */
  ownerlessProjects?: Array<{ id: string; name: string; conversations: number }>
  ownerId: string
  /** The Workspace it belongs to (workspaceStore.ts); absent on a Swarm from before Workspaces until the migration gives it one. */
  workspaceId?: string
  /** Who in the Workspace may find and join it by themselves: `workspace` lets members and up join; absent reads as invite-only. */
  workspaceVisibility?: 'invite-only' | 'workspace'
  environment: string
  /** Fields this tab overrides from its owner's account routing policy (routingPolicy.ts). */
  routingPolicy?: import('./routingPolicy.js').RoutingOverride
  /** The owner's routing rules (rules.ts); absent until the first is set. */
  rules?: import('./rules.js').SwarmRule[]
  /** Owner-only sharing configuration; visibleState always removes it. */
  sharing?: import('./sharing.js').SwarmSharing
  /** People who left or were removed, whom auto-join never adds again (autoJoin.ts); visibleState always removes it. */
  autoJoinDeclined?: string[]
  /** Only in what a reader gets (visibleState), never stored: people at the owner's domain join by themselves, so the leave
   *  dialog says someone who leaves is not added back. */
  autoJoin?: true
  paused: boolean
  /** Its owner deleted it (deletion.ts): nobody reads or writes it, its row lists no member, and its owner may restore it until
   *  `purgeAt` (ISO times). Absent on a live Swarm. */
  deletion?: { at: string; by: string; purgeAt: string }
  /** Idle workers stop and finished groups archive by themselves (tidy.ts); false once the owner turns it off. */
  tidy?: false
  /** The most Buddies a person may have in this Swarm (buddies.ts BUDDY_CAP), set by its owner (task #3818). */
  buddyCap?: number
  /** Buddies (buddies.ts) are on in every Swarm; readers are always told so (visibleState), as apps from before 10-29 hide
   *  Buddies and show Chat with PM without it. A stored value from the old switch is ignored. */
  buddies?: true
  people: Person[]
  agents: Agent[]
  conversations: Conversation[]
  /** Deleting a project never makes its old # references name new work. */
  retiredConversationNumber?: number
  invitations: Invitation[]
  starts?: AgentStart[]
  machines?: import('./machines.js').ContributedMachine[]
  /** Slot claims survive person withdrawal; only host proof for this generation releases them. */
  harnessReservations?: Array<{ machineId: string; harnessId: string; generation: string; renewed: boolean }>
  /** Native stop receipts survive late replaceable machine observations. */
  releasedHarnesses?: Array<{ machineId: string; harnessId: string }>
  /** Sessions of removed agents their host closes, listed to that host until it says they closed (agent.sessionClosed). */
  /** `heldFor`: a confidential session in a Harness Team account, whose project the account keeps serving alone until its
   *  host confirms the close, which it does once its saved session there is deleted (machines.ts productManagerOn); `since`
   *  when it was removed, and `noticed` once the Swarm said it lasts (liveness.ts). */
  /** `buddyOnly`: a Buddy's session on a Buddy-only machine, kept from every reader as its machine is (read/changes.ts). */
  /** What a report's removal of a closed agent must restore if its session reopens (closedAgents.ts): only its machine's host hears
   *  of it (read/hostRows.ts), and no reader gets it, as it names private chats. */
  removedSessions?: RemovedSession[]
  closingSessions?: Array<{ agentId: string; machineId: string; harnessId: string; machineOwnerId: string; heldFor?: string; since?: number; noticed?: true
    buddyOnly?: true }>
  /** Removed machines whose host still has to clean up (machines.ts expireRemovals), listed only to that host. */
  machineCleanups?: import('./machines.js').MachineCleanup[]
  /** The machines their person took out of this Swarm, so a sync that adds machines by itself leaves them out; a reader gets only
   *  the ids of their own (visibleState). */
  removedMachines?: Array<{ machineId: string; contributorId: string }>
  /** Conversations of a kind a later release added, set aside unchanged by a release that does not know it (parkLaterConversations). */
  parkedConversations?: Conversation[]
  /** The Local models add-on (docs/plans/2026-10-23-swarm-local-models.md): off until the owner turns it on, and only
   * then does anything call grid. The grid is kept when it is turned off, so turning it on again is instant. */
  localModels?: SwarmLocalModels
  /** The highest workgroup number ever given (store by parts); numbers are never given twice. */
  groupCounter?: number
  /** The tab revision when this Swarm was split into parts; every later message sequence is above it. */
  sequenceBase?: number
}
export interface SwarmLocalModels {
  /** The Swarm's own grid, minted on first turn-on and never renamed. */
  grid: string
  enabled: boolean
  /** What the owner's host last reported: the grid created and its members in step, or why not. */
  ready?: boolean
  error?: string
}
/** An account a project's PM runs on (Ken, 11-05): its machine (a Mac's Harness Team account names that Mac too, whose
 *  subscription it spends) and engine. A project the reader may not read is "another project", its PM unnamed. */
export interface PmAccount { machineId: string; hostMachineId?: string; engine: string; project: string; pm: string }

/** Every project's PM account (PmAccount): a PM could drain the account another project's PM ran on, and the route, reading
 *  as an agent of one project, saw no other project's PM (review of #3134). */
export function pmAccounts(state: SuperTabState, actor: Actor): PmAccount[] {
  return projectsOf(state).flatMap(project => {
    const leadId = state.conversations.find(c => c.id === project.leadConversationId)?.leadId
    const pm = leadId ? state.agents.find(a => a.id === leadId) : undefined
    const engine = pm?.configuration?.engine
    if (!pm || !engine) return []
    const host = state.machines?.find(m => m.machineId === pm.machineId)?.hostMachineId
    // A public project is named to every project agent, as otherProjectsWork names it (sharedWithLeads).
    const readable = canReadProject(state, actor, project) || sharedWithLeads(project)
    return [{ machineId: pm.machineId, ...(host ? { hostMachineId: host } : {}), engine,
      project: readable ? project.name : 'another project', pm: readable ? pm.displayName ?? pm.name : 'its PM' }]
  })
}

export interface OtherProjectWork {
  conversationId: string
  projectName: string
  title: string
  owns: string[]
  status: WorkStatus
  agentName: string
  /** The first pull request link in the assignment's result, when its agent reported one. */
  pr: string | null
}
export type Actor =
  | { kind: 'person'; userId: string; email: string }
  | { kind: 'agent'; agentId: string; machineOwnerId: string }
export interface Author { kind: 'person' | 'agent'; id: string; name: string; displayName?: string; membershipGeneration: string }
export interface MessageDraft {
  id: string
  conversationId: string
  author: Author
  text: string
  replyTo: string | null
  /** Explicit answer in main chat, without a thread. */
  answers?: string
  recipients: string[]
  /** Buddies this row is news for (buddyNews.ts): a delivery each, never listed among its recipients. */
  buddyRecipients?: string[]
  /** Structured row kind for clients; `native` is written by native.ts, `route`/`route-override` by commands. */
  source?: Record<string, unknown>
  attachments?: import('./attachments.js').Attachment[]
  /** People a Lead tagged (mentions.ts). */
  mentions?: string[]
  /** Its tags wait until the group has had no worker and no Lead action for a while (mentions.ts NO_WORKER_GRACE_MS). */
  holdMentions?: true
  /** Written by message.send: a post, not a notice the server writes under an agent's name. Never stored; an agent's post to its
   *  project's coordinator waits for its digest (noticeDigest.ts gatheredMessage). */
  post?: true
  /** The root of the thread this reply is in; absent on a top-level message, which is its own thread (writeMessages). */
  thread?: string
  /** A thread reply also shown in the conversation's main stream. */
  alsoInChat?: true
  /** A reply in a Buddy thread session's thread (buddySessions.ts): the main Buddy never reads it. */
  buddySession?: true
  /** The project a row of a person's one Buddy chat belongs to (buddySessions.ts lostProjectRow), on the row itself so hiding it
   *  has no limit (security review 2 of #2435). */
  buddyProject?: string
}
/** A notice for one agent alone (a skill update): delivered to it like any message, never shown to people or other agents. */
export const AGENT_ONLY = { kind: 'agent-only' }
/** Who reads each kind of notice the Swarm writes into a chat: every kind the code writes has its line (notices.test.ts).
 *  `people`: everyone in the chat, its record of what happened or of what someone must act on. `recipients`: written for the
 *  Lead or an agent, so only the ones it reaches read it, like an agent-only notice, under its own kind so they receive it as
 *  before; a notice that reaches none is for people, the only ones left who can act (review of #2177). `agent`: only its
 *  recipients, always. Ken, 2026-10-29: shown under the Lead's name in the project chat, the Lead's wakes read as requests to
 *  act; people read a task's state on its status line. By kind, so the ones already stored are hidden as well. A kind people
 *  read can still be one row's recipients' alone (forRecipients): a cancel told to its worker, a routing line in the project
 *  chat. A kind no code here knows, stored by a newer server, reads as `people`. */
export const NOTICE_READERS = {
  // Only its agent: a skill update (cli host.ts), a decision answered (decisions.ts).
  'agent-only': 'agent',
  // The Lead's wakes and requests, and the worker's "moved" line (liveness.ts, tidy.ts, projectUpdates.ts, digest.ts); two
  // projects changing the same code, to both their Leads in the Leads chat (commands.ts).
  'work-stalled': 'recipients', 'work-lost': 'recipients', 'work-resumed': 'recipients', 'idle-stop': 'recipients',
  // A crew member's 2 hours without progress on its task, to that member (dispatch.ts crewClock, liveness.ts).
  'crew-nudge': 'recipients',
  // An agent with no open task for 15 minutes, and a grid attempt's failed first review, told to the coordinator (tidy.ts
  // idleNotices, commands.ts work.check; project instructions, phase 4). `idle-stop` rows are from before.
  idle: 'recipients', 'review-failed': 'recipients',
  'update-request': 'recipients', 'digest-request': 'recipients', overlap: 'recipients',
  // The coordinator's wake for its built-in schedule (pmSchedule.ts).
  'schedule-request': 'recipients',
  // The daily tidy, the coordinator's alone like its wake (pmSchedule.ts tidyRequest).
  'tidy-request': 'recipients',
  // Two agents that may be talking in a loop, told to the coordinator (commands.ts pairLoop, project instructions phase 1).
  'pair-loop': 'recipients',
  // A crew member's finished wake or move, timed for the daily scorecard (crewTimes.ts, task #3462): read by nobody.
  'crew-timing': 'agent',
  // The server's routine notices to the coordinator, gathered into one message (noticeDigest.ts).
  'notice-digest': 'recipients',
  // An agent's tag, ask or line to a person, routed to the PM instead (crewNeeds.ts): the PM's alone. Never gathered.
  'crew-need': 'recipients',
  // A person's decision wakes the task's PM; people read the decision in Tasks.
  'task-approval': 'recipients',
  // Each its own case in commands.ts, decided by the row (forRecipients): statuses, briefs, merges, starts, removals.
  system: 'people',
  // A save of the project's instructions was posted in the project chat until #3132 (Dee and Ken, 11-05): the rows stored
  // before are read by nobody (#3165), and a project chat ending in one is served as read (read/servedTops.ts). A change is
  // read in the Instructions history.
  instructions: 'agent',
  // A member removed one of the coordinator's notes: told to the coordinator alone (instructions.ts).
  'note-removed': 'recipients',
  'project-report': 'people', route: 'people', 'route-override': 'people', 'buddy-proposal': 'people', 'buddy-proposal-sent': 'people', 'buddy-session-ended': 'people',
  // Proposal history, and the private Buddy notices stored before task #4558, are visible to the people who can read their card/chat.
  'proposal-card': 'people', 'proposal-answer': 'people', 'proposal-notice': 'people', 'proposal-merged': 'people', 'proposal-overdue': 'people',
  'decision-delegated': 'people', 'machine-removed': 'people', ship: 'people',
  // An agent's question to a person in a switched project, in their default Buddy chat (decisions.ts askedThroughBuddy, #3826).
  'decision-asked': 'people',
  // A Buddy's question settled in its owner's Decisions, in their Buddy chat (decisions.ts settleBuddyDecision).
  'decision-answered': 'people',
  // A decision its person must agree to reached its time unanswered, told to the PM alone (decisions.ts mustAgreePassed).
  'decision-must-agree': 'recipients',
  // A computer signed in as another account now, told to its old owner in their Buddy chat (commands.ts machine.moved, #3122).
  'computer-moved': 'people',
  // "<machine> left the Swarm: ..." in every project chat, no longer written (anh Dee, 11-04, #2742): the rows stored before are
  // read by nobody (they have no recipients), and a project chat ending in one is served as read (read/servedTops.ts).
  'machine-left': 'agent',
  // A task's one line in its project chat, edited as it moves (taskLine.ts): people read a task's state there.
  'task-line': 'people',
  // A project PM's private line in a person's one Buddy chat, no longer written (task #4558: only the person and their own agent
  // post there): its person reads the rows stored before.
  'pm-line': 'people',
  // A decider's override of a person's rule, told to them by their own Buddy in their Buddy chats (commands.ts instructions.save).
  'rule-approved': 'people',
  // Their one Buddy cannot start in a person's older project chat, told to them there once per outage (commands.ts buddyDownLine).
  'buddy-cannot-start': 'people',
  'auto-archive': 'people', native: 'people',
  // A release step the Swarm opened for the Integrator, and its verified release's line (releases.ts, task #3405).
  release: 'people',
  // The nightly routing reflection, for the project's people; never a Buddy's (buddies.ts routingRow).
  'routing-reflection': 'people',
  // No new agent can start, or soon none will, told to the coordinator; with none in the chat, people read it, tagging who can
  // fix it (reviewCapacity.ts; final review). Older rows, written for no one, still read as people's. Older rows of kinds no
  // longer written (the automatic review's `auto-review`, a routing rule's `rule`) read as people's, as any kind not listed does.
  'review-capacity': 'recipients',
  // #2177's rulings: a failed start and a terminal's alert or typed input stay the people's to see.
  // A PM switch nobody answered, in its project chat (tidy.ts staleSwitches).
  switch: 'people',
  // The machine owner's one line when another person moves a PM onto one of their non-default accounts (commands.ts agent.switchResult).
  'pm-switch-notice': 'people',
  // The machine owner's line, once a week, when someone else's work starts on their machine (othersWork.ts).
  'others-work-notice': 'people',
  'start-timeout': 'people', 'terminal-alert': 'people', 'terminal-input': 'people',
} as const satisfies Record<string, 'people' | 'recipients' | 'agent'>
const readersOf = (kind: unknown): 'people' | 'recipients' | 'agent' =>
  typeof kind === 'string' && Object.hasOwn(NOTICE_READERS, kind) ? NOTICE_READERS[kind as keyof typeof NOTICE_READERS] : 'people'
/** Marks a notice of a kind people also read (a cancel to its worker), or a copy for no one of a notice its recipient hears
 *  elsewhere, as its recipients' alone. */
export const forRecipients = (source: Record<string, unknown>) => ({ ...source, recipientsOnly: true as const })
/** Whether only the message's recipients read it: never people, nor other agents. */
export const agentOnly = (source: unknown, recipients: readonly string[]): boolean => {
  const notice = source as { kind?: unknown; recipientsOnly?: unknown } | null | undefined
  const readers = readersOf(notice?.kind)
  return readers === 'agent' || notice?.recipientsOnly === true || (readers === 'recipients' && recipients.length > 0)
}
/** What a Buddy reads of an agent and of a task: no machine or terminal ids (review 1 of #2115: no machines means none). */
/** A lost task's reason without the machine it ran on (lostReason.ts). */
/** Whether [target]'s machine is kept from [actor]: one Buddy-only (machines.ts buddyOnly), which only the Buddy's person and
 *  the Buddy itself read where it runs (security review 1 of #2234). */
export const machineHiddenFrom = (state: SuperTabState, actor: Actor, target: Agent): boolean =>
  !!target.buddyOf && !!state.machines?.some(m => m.buddyOnly && m.machineId === target.machineId)
  && !(actor.kind === 'person' ? actor.userId === target.buddyOf?.personId : actor.agentId === target.id)

export const agentWithoutMachine = <T extends Pick<Agent, 'machineId' | 'harnessId' | 'replacement' | 'lostTask'>>(target: T): T => {
  const { replacement: _replacement, ...rest } = target
  return { ...rest, machineId: '', harnessId: '',
    ...(target.lostTask ? { lostTask: { ...target.lostTask, reason: lostReasonWithoutMachine(target.lostTask.reason) } } : {}) } as T
}
/** An agent as a Buddy [buddyId] reads it: no machine, and for any agent but itself not whose machine, membership or Team
 *  account runs it, which says whose Mac runs the PM (security reviews of #2258). Its membership's generation matches a
 *  person's, so it goes too (delta review 1 of #2258), and so does its host grant, which under an older share policy names
 *  its contributor's email (lib/machineSharePolicy.ts; final check of #2258). */
export const agentForBuddy = <T extends Pick<Agent, 'id' | 'machineId' | 'harnessId' | 'machineOwnerId' | 'contributorId' | 'membershipGeneration' | 'hostGrant' | 'teamAccount'
  | 'replacement' | 'lostTask' | 'modelRequest'>>(target: T, buddyId: string): T => {
  // A pending model switch names the machines serving the model (buddyModel.ts); its host reads it from its own rows, never here
  // (security review 1 of #2787).
  const { modelRequest: _switching, ...unswitched } = target
  const bare = agentWithoutMachine(unswitched as T)
  if (target.id === buddyId) return bare
  const { teamAccount: _team, ...rest } = bare
  return { ...rest, machineOwnerId: '', contributorId: '', membershipGeneration: '', hostGrant: null } as T
}
/** A group as a Buddy reads it: its task names no machine, terminal or machine owner. */
/** A conversation as a Buddy reads it: no machine (below), and no list of its chat's sessions, which names other threads, other
 *  projects' among them, and starts still pending (security review 2 of #2435). */
export const groupForBuddy = <T extends Pick<Conversation, 'assignment' | 'lostAttempt' | 'buddySessions'>>(group: T): T => {
  const { buddySessions: _sessions, ...rest } = groupWithoutMachines(group)
  return rest as T
}
export const groupWithoutMachines = <T extends Pick<Conversation, 'assignment' | 'lostAttempt'>>(group: T): T => {
  const assignment = group.assignment && { ...group.assignment,
    ...(group.assignment.execution ? { execution: { ...group.assignment.execution, machineId: '', harnessId: '', machineOwnerId: '',
      ...group.assignment.execution.contributorId !== undefined ? { contributorId: '' } : {} } } : {}),
    ...(group.assignment.lost ? { lost: { ...group.assignment.lost, reason: lostReasonWithoutMachine(group.assignment.lost.reason) } } : {}) }
  return { ...group, ...(assignment ? { assignment } : {}),
    ...(group.lostAttempt ? { lostAttempt: { id: group.lostAttempt.id, agentId: group.lostAttempt.agentId } } : {}) }
}
export interface CommandEffects {
  state: SuperTabState
  messages: MessageDraft[]
  cancelledAgents: string[]
  previousAttempts: Array<{ conversationId: string; brief: string; checks: Check[]; assignment: Assignment }>
  routeDecisions: RouteDecisionEffect[]
  result: Record<string, unknown>
  /** `message.edit`'s new text, credentials removed (commands.ts WORDS): what the store writes into the row. */
  messageEdit?: { messageId: string; text: string }
  /** An agent's reaction settles that agent's own deliveries of the message it reacted to, as an answer does (reactions.ts; the store closes the rows). */
  settles?: { messageId: string; agentId: string }
  /** A terminal request or its answer, written outside the tab state by the store (terminal.ts). */
  terminal?: import('./terminal.js').TerminalEffect
  /** A Buddy's proposal closed by hand, written into the open proposals by the store (proposals.ts closeProposal). */
  closedProposal?: { messageId: string; conversationId: string; reason: string }
  /** Decisions asked, and a decision answered, written outside the tab state by the store (decisions.ts). */
  decisions?: import('./decisions.js').DecisionDraft[]
  decisionAnswer?: import('./decisions.js').DecisionAnswer
  /** A must-agree decision past its time, kept waiting for its person (decisions.ts keepWaiting). */
  decisionKeptWaiting?: string
  /** Decisions whose question was answered elsewhere, closed by the store (decisions.ts closeDecisions; task #4547). */
  closedDecisions?: string[]
  /** Deliveries of messages already stored: a Buddy thread session's first messages, sent while it started (buddySessions.ts). */
  /** `lead`: a project's Lead hearing its person's messages sent while the chat had none (leadStart.ts leadArrived). */
  lateDeliveries?: Array<{ messageId: string; conversationId: string; agentId: string; author: { kind: 'person'; id: string; generation: string }; lead?: true }>
  /** An attempt the command closed for its gone builder (commands.ts conversation.merged, task #3510): the store closes its
   *  attempt row as a builder's own done does. */
  closedAssignment?: { assignmentId: string; outcome: 'done' }
  /** A project's new instructions revision, written outside the tab state by the store (instructions.ts). */
  instructions?: import('./instructions.js').InstructionsWrite
  /** A project's new rules revision, written outside the tab state by the store (policyStore.ts). */
  projectRules?: import('./policy.js').RulesWrite
  /** A coordinator's note kept or a note removed, written outside the tab state by the store (instructions.ts). */
  notes?: import('./instructions.js').NotesWrite
  /** Reactions the Swarm adds as a task's agent on the message that asked for it (taskLine.ts), written by the store as that
   *  agent's own `message.react`. */
  reactions?: Array<{ conversationId: string; messageId: string; agentId: string; emoji: import('./reactions.js').Reaction }>
}
/** `details` go to the caller with the code: what it needs to act on the refusal (a stale save's current text). */
export class SuperTabError extends Error {
  /** `unreachable`: the caller cannot reach this Swarm at all (not, or no longer, a member). The person routes answer it as
   *  they answer a Swarm that does not exist (routes/superTabs.ts NOT_AVAILABLE), so the answer never says which. */
  constructor(readonly code: string, message: string, readonly status = 409, readonly unreachable = false, readonly details?: Record<string, unknown>) {
    super(message)
    this.name = 'SuperTabError'
  }
}
export function fail(code: string, message: string, status = 409, details?: Record<string, unknown>): never { throw new SuperTabError(code, message, status, false, details) }
export const stableId = (...parts: string[]): string => createHash('sha256').update(JSON.stringify(parts)).digest('hex').slice(0, 24)
export const actorKey = (actor: Actor): string => actor.kind === 'person' ? `person:${actor.userId}` : `agent:${actor.agentId}`
/** The task is open: assigned, and its attempt not ended. A handed task (below) is open too: archive, steps, deletion and the
 *  GitHub token hold all read this. Whether its agent is busy is occupiesAgent. */
export const activeWork = (group: Conversation): boolean => !!group.assignment &&
  !['done', 'stopped', 'cancelled', 'lost'].includes(group.assignment.status)
/** A task its Engineer handed over (task #3399, handed.ts): its pull request is ready for review, the status its Engineer sets
 *  when it marks it ready. The task stays open and its Engineer keeps its push access, but the work waits on others, so the
 *  Engineer is free for new work. A step's own Ready is its verdict, not a hand-over. */
export const handed = (group: Conversation): boolean => !group.reviewOf && group.assignment?.status === 'review'
/** Work in its agent's hands, which makes the agent busy: open and not handed over. Every "is this agent busy" check reads it. */
export const occupiesAgent = (group: Conversation): boolean => activeWork(group) && !handed(group)

/** What awaitingWorkers reads of the conversations, from one pass over them: the agents leading any conversation, those with
 *  active work, and each agent's assigned groups (not lost) in conversation order. Scanning every conversation per agent and
 *  project was 2.6 M calls in the 2026-11-02 prod profiles (12 profiles), on every read. Built per call or per caller's loop
 *  over projects, never kept on the state, since a command changes it. */
export interface WorkerIndex { leaders: ReadonlySet<string>; working: ReadonlySet<string>; groupsByAgent: ReadonlyMap<string, Conversation[]> }
export function workerIndex(state: SuperTabState): WorkerIndex {
  const leaders = new Set<string>(), working = new Set<string>(), groupsByAgent = new Map<string, Conversation[]>()
  for (const c of state.conversations) {
    if (c.leadId !== null) leaders.add(c.leadId)
    if (!c.assignment) continue
    // Busy with work in its hands; a task it handed over leaves it free (task #3399).
    if (occupiesAgent(c)) working.add(c.assignment.agentId)
    // A lost task's agent did not finish it, even once the task is cancelled: it may be gone.
    if (c.assignment.lost) continue
    const groups = groupsByAgent.get(c.assignment.agentId)
    if (groups) groups.push(c)
    else groupsByAgent.set(c.assignment.agentId, [c])
  }
  return { leaders, working, groupsByAgent }
}

/** Old states derive the finished-work mark from their closed assignments; new states persist it on the worker. */
export function awaitingWorkers(state: SuperTabState, projectId: string, index = workerIndex(state)): Agent[] {
  return state.agents.filter(a => {
    if (index.leaders.has(a.id) || index.working.has(a.id)) return false
    const groups = index.groupsByAgent.get(a.id) ?? []
    return (a.projectId ?? groups.map(c => groupProject(state, c).id)[0] ?? 'lead') === projectId &&
      (a.workDecision === 'awaiting' || (!a.workDecision && groups.some(c => !occupiesAgent(c))))
  })
}
/** A task's work ended: its worker is marked `awaiting`, whatever its kind. People see the mark; no command reads it, so
 *  nothing waits for a keep or stop (project instructions, phase 4, decision 17). A coordinator, and a worker already
 *  stopping, keep what they have. */
export function finishWorker(state: SuperTabState, workerId: string): void {
  const target = state.agents.find(a => a.id === workerId)
  if (!target || state.conversations.some(c => c.leadId === target.id) || target.workDecision === 'stop') return
  // A handed task that ends while its Engineer works on its next one leaves that Engineer busy (task #3399).
  if (state.conversations.some(c => occupiesAgent(c) && c.assignment!.agentId === target.id)) return
  target.workDecision = 'awaiting'
}

export function person(state: SuperTabState, id: string): Person {
  const found = state.people.find(p => p.id === id)
  if (!found) throw new SuperTabError('FORBIDDEN', 'You no longer have access to this Super Tab.', 403, true)
  return found
}
export function agent(state: SuperTabState, id: string): Agent {
  const found = state.agents.find(a => a.id === id) ?? fail('AGENT_UNAVAILABLE', 'This agent is no longer in the Super Tab.')
  if (person(state, found.contributorId).generation !== found.membershipGeneration) {
    fail('AGENT_UNAVAILABLE', 'This agent must be shared again before it can participate.')
  }
  return found
}
export function conversation(state: SuperTabState, id: string): Conversation {
  return state.conversations.find(c => c.id === id) ?? fail('NOT_FOUND', 'This conversation is unavailable.', 404)
}

export const isLeads = (group: Conversation): boolean => group.kind === 'leads'

const KNOWN_KINDS: Record<NonNullable<Conversation['kind']>, true> = { leads: true, buddy: true, 'swarm-buddy': true, 'agent-chat': true }
/** Conversation kinds this release knows; one of another kind is kept aside unchanged (parkLaterConversations, parts/shape.ts). */
export const knownKind = (group: Pick<Conversation, 'kind'>): boolean => group.kind == null || Object.hasOwn(KNOWN_KINDS, group.kind)
/** During a rolling deploy the previous release reads what the next one wrote. A conversation kind it does not know
 *  belongs to no project it can check, so it waits here unchanged, and the release that knows it puts it back. */
export function parkLaterConversations(state: SuperTabState): void {
  const all = [...state.conversations, ...state.parkedConversations ?? []]
  const known = knownKind
  state.conversations = all.filter(known)
  const parked = all.filter(c => !known(c))
  if (parked.length) state.parkedConversations = parked
  else delete state.parkedConversations
}

/** Work a Lead of another project should know about: assigned and moving, not finished, stuck or archived. */
export const crossProjectActive = (group: Conversation): boolean => !group.archived && !isLeads(group) && !group.audience
  && ['working', 'review', 'needs_human'].includes(group.assignment?.status ?? '')

/** The active work of the other projects a project's Lead may know about (shared with the read API, design 7.2). */
export function otherProjectsWork(state: SuperTabState, own: SwarmProject): OtherProjectWork[] {
  return state.conversations.filter(crossProjectActive).flatMap(group => {
    const project = groupProject(state, group), assignment = group.assignment!
    if (project.id === own.id || !sharedWithLeads(project)) return []
    const worker = state.agents.find(a => a.id === assignment.agentId)
    return [{ conversationId: group.id, projectName: project.name, title: group.title, owns: group.task?.owns ?? [], status: assignment.status,
      agentName: worker ? worker.displayName ?? worker.name : '', pr: assignment.result?.match(/https:\/\/github\.com\/[^\s/]+\/[^\s/]+\/pull\/\d+/)?.[0] ?? null }]
  })
}

/** The Swarm-wide Leads conversation ("Product Managers" in the apps) is removed (Dee, 2026-10-31): only agents posted
 *  there and people did not know what it was for. A new Swarm gets none. An older Swarm keeps its stored record and
 *  history untouched (no data is deleted), but no read sends it, no command or post reaches it (LEADS_REMOVED) and no
 *  delivery from it is handed out. */
export const LEADS_REMOVED = "The Product Managers chat was removed. Post in your project's chat instead."
export function leadsRemoved(): never { fail('LEADS_CONVERSATION_REMOVED', LEADS_REMOVED, 410) }

/** Legacy groups keep their append order, including archived groups. Persisted
 * numbers are never reassigned; the store serializes concurrent additions. */
export function numberConversations(state: SuperTabState): void {
  let next = nextConversationNumber(state)
  const projects = projectsOf(state), leads = new Set(projects.map(p => p.leadConversationId))
  for (const group of state.conversations) {
    if (!leads.has(group.id) && !isLeads(group) && group.number == null) {
      // An unnumbered dormant task predates a Simple→Full switch. Giving it a number now must not make it new work.
      if (!group.kind && !group.audience && !group.reviewOf && projects.some(p => p.id === (group.projectId ?? 'lead') && p.simpleThrough !== undefined)) group.process = 'simple'
      state.groupCounter = group.number = next++
    }
  }
}
/** The store by parts keeps the highest number ever given (`groupCounter`): a dormant group is not loaded, and its
 *  number must not be given again. */
export function nextConversationNumber(state: SuperTabState): number {
  return Math.max(state.groupCounter ?? 0, state.retiredConversationNumber ?? 0, 0,
    ...[...state.conversations, ...state.parkedConversations ?? []].map(c => c.number ?? 0)) + 1
}
export function author(state: SuperTabState, actor: Actor, write = false): Author {
  if (actor.kind === 'person') {
    const member = person(state, actor.userId)
    if (write && member.role === 'viewer') fail('READ_ONLY', 'You have read-only access to this Super Tab.', 403)
    return { kind: 'person', id: member.id, name: member.email, membershipGeneration: member.generation }
  }
  const member = agent(state, actor.agentId)
  if (member.machineOwnerId !== actor.machineOwnerId) fail('FORBIDDEN', 'Only the execution host can speak as this agent.', 403)
  if (write && person(state, member.contributorId).role === 'viewer') fail('READ_ONLY', 'This contribution is read-only.', 403)
  return { kind: 'agent', id: member.id, name: member.name, displayName: agentDisplayName(state.agents, member.id), membershipGeneration: member.membershipGeneration }
}

/** The Swarm's grid name: `swarm-` and 12 hex of sha256(tab id). Derived so it is reproducible when supported; the
 * stored value is authoritative and never renamed. */
export function swarmGridName(tabId: string): string {
  return `swarm-${createHash('sha256').update(tabId).digest('hex').slice(0, 12)}`
}

export function createSuperTab(id: string, name: string, owner: { id: string; email: string }, environment: string, visibility?: ProjectVisibility): SuperTabState {
  const state: SuperTabState = {
    version: 1, id, name, ownerId: owner.id, environment, paused: false,
    people: [{ ...owner, email: owner.email.trim().toLowerCase(), role: 'owner', generation: id }],
    agents: [], invitations: [],
    conversations: [{ id: 'lead', title: 'Lead', leadId: null, agentIds: [], archived: false, brief: '', checks: [], assignment: null, lastMessageSequence: 0 }],
  }
  // A new Swarm's first project starts in Default; only a project from before skill modes reads as Harness orchestration.
  // It starts on a copy of the built-in instructions, which the store writes beside it (store.ts create).
  state.projects = [{ ...projectsOf(state)[0]!, ...(visibility ? { visibility } : {}), skillMode: 'default', ...FIRST_INSTRUCTIONS }]
  // Its models are on from the start (owner, 2026-10-24): the owner's computer makes the Swarm's grid in the background
  // (CLI `superTabs/swarmGrids.ts`) and reports how it went. Fire and forget: a grid that could not be made leaves the
  // Swarm as it is, and the owner's first share or run in Your models sets the models up then.
  state.localModels = { grid: swarmGridName(id), enabled: true }
  return state
}

/** Pending invitations are management data, not part of the shared conversation. */
/** What every read appends to a Mac's Harness Team account entry's name (task #3060). */
export const TEAM_ENTRY_LABEL = ' · Team account'
/** A Team account entry's name as people read it: its Mac's, then TEAM_ENTRY_LABEL, once. */
export const teamEntryName = (name: string): string => name.endsWith(TEAM_ENTRY_LABEL) ? name : `${name}${TEAM_ENTRY_LABEL}`

export function visibleState(state: SuperTabState, actor: Actor, now = Date.now()): SuperTabState {
  author(state, actor)
  // The copy leaves out what no reader gets and no step below reads: the owner-only sharing, the hosts' slot claims, released
  // and closing sessions (only that machine's host roster lists them: read/hostRows.ts; a removed private agent's session is
  // not every member's), and overlap alerts. Nor a dormant conversation: it is read on demand, never in a whole-Swarm read
  // (spec, Archive); a command may still load one.
  const { sharing: _sharing, autoJoinDeclined: _declined, harnessReservations: _reservations, releasedHarnesses: _released, overlapAlerts: _alerts, closingSessions: _closing,
    removedSessions: _removed, ...kept } = state
  const visible = cloneData({ ...kept, conversations: state.conversations.filter(c => !c.dormant) })
  // Prepared PM handoffs are private host-to-host launch data. Machine hosts receive their own start through read/hostRows.ts;
  // ordinary people and agent syncs must never receive the note or its correlation fields.
  for (const start of visible.starts ?? []) {
    delete start.request.handoffNote
    delete start.request.handoffSourceAgentId
    delete start.request.handoffChangeId
  }
  if (autoJoinOn(state)) visible.autoJoin = true
  // A Buddy-only machine is no machine of the Swarm to anyone, its own person included (machines.ts buddyOnly): their Buddy
  // shows as a Buddy, and their machine stays theirs. Machines, status and the leaderboard's lent hours all read this.
  if (visible.machines) visible.machines = visible.machines.filter(m => !m.buddyOnly)
  // A machine taken out says who owned it: a reader gets the ids of their own, which is all their sync asks.
  const ownRemoved = actor.kind === 'person' ? (visible.removedMachines ?? []).filter(r => r.contributorId === actor.userId).map(r => r.machineId) : []
  if (ownRemoved.length) (visible as { removedMachines?: unknown }).removedMachines = ownRemoved
  else delete visible.removedMachines
  // What a machine can reach: its notes and checks only to those section 4 of the design names (machineAccess.ts).
  for (const pool of visible.machines ?? []) {
    const access = visibleAccess(state, pool, actor)
    if (access) pool.access = access
  }
  // Rows by day and project that only the leaderboard read uses, and it takes them from the Swarm itself.
  for (const pool of visible.machines ?? []) delete pool.lentDays
  // Where teammates' work ran was a Team-account choice; Swarm v3 runs every agent as its own person (#4120, #4289). It stays
  // stored for teamWorkRefusal until the Team entries go (#4290), and no reader gets it.
  for (const pool of visible.machines ?? []) delete pool.ownAccountChoice
  // A Mac's Harness Team account is stored under its Mac's name (machines.ts followAccountName), and read so it named two
  // entries alike: a lamp start picked the Team account's thinking it was the Mac (task #3060). Every read tells them apart;
  // the stored name, which renames and the server's own sentences read, stays the Mac's.
  for (const pool of visible.machines ?? []) if (pool.hostMachineId) pool.name = teamEntryName(pool.name)
  // A machine kept for some projects names to each reader only those they may read (machines.ts projects): a private
  // project's id is not another member's to see.
  for (const pool of visible.machines ?? []) {
    if (pool.projects) pool.projects = pool.projects.filter(id => projectsOf(state).some(p => p.id === id && canReadProject(state, actor, p)))
  }
  // Nor its id, which a Buddy's row carries (machineHiddenFrom).
  visible.agents = visible.agents.map(a => machineHiddenFrom(state, actor, a) ? agentWithoutMachine(a) : a)
  // The removed Leads conversation reaches nobody (leadsRemoved), its id included.
  visible.conversations = visible.conversations.filter(c => !isLeads(c))
  delete visible.leadsConversationId
  assignAgentDisplayNames(visible.agents)
  const led = actor.kind === 'agent' ? ledProject(visible, actor.agentId) : undefined
  if (led) visible.otherProjectsWork = otherProjectsWork(visible, led)
  const ownerless = ownerlessProjects(state, actor)
  if (ownerless) visible.ownerlessProjects = ownerless
  for (const target of visible.agents) {
    const since = downSince(state, target, now)
    if (since) target.downSince = since
    delete target.downNamed
    if (target.limitedUntil && Date.parse(target.limitedUntil) <= now) target.limitedUntil = null
  }
  visible.buddies = true
  // A failing privacy check's detail is its contributor's: an error from the check can name paths on their Mac. Everyone
  // else reads which item failed (machines.ts teamWorkRefusal).
  for (const pool of visible.machines ?? []) {
    // Engine idle proof is for server lifecycle decisions alone, never a member's activity feed (#3824).
    if (pool.observation) delete pool.observation.idleBuddyHarnessIds
    const privacy = pool.observation?.privacy
    if (privacy && 'detail' in privacy && !(actor.kind === 'person' && actor.userId === pool.contributorId)) delete (privacy as { detail?: string }).detail
  }
  // A machine's accounts (labels, percent left) are for those who may switch a PM running there: its owner, and the owners of
  // projects whose PM runs on it. Agents and everyone else read the machine without them.
  for (const pool of visible.machines ?? []) {
    if (!pool.observation?.profiles) continue
    const there = state.agents.filter(a => a.machineId === pool.machineId)
    const owners = new Set(there.length ? there.map(a => a.machineOwnerId) : [pool.contributorId])
    const mayMove = actor.kind === 'person' && (owners.has(actor.userId) ||
      there.some(a => projectsOf(state).some(p => ownsProject(state, actor.userId, p) && state.conversations.some(c => c.id === p.leadConversationId && c.leadId === a.id))))
    if (!mayMove) delete pool.observation.profiles
  }
  expireRemovals(visible, now)
  // A read never hands out the cleanup records it just applied (read/hostRows.ts delivers them to the machine's host).
  delete visible.machineCleanups
  delete visible.parkedConversations
  for (const group of visible.conversations) { delete group.chatLimits; delete group.talkedAt }
  numberConversations(visible)
  delete visible.retiredConversationNumber
  delete visible.groupCounter
  delete visible.sequenceBase
  placeRules(visible)
  if (visible.rules) visible.rules = visible.rules.filter(r => projectsOf(state).some(p => p.id === r.projectId && canReadProject(state, actor, p)))
  if (visible.projects) {
    visible.projects = visible.projects.filter(p => canReadProject(state, actor, p))
    visible.conversations = visible.conversations.filter(c => canReadGroup(state, actor, c))
    // The status card is read exactly by those who read the project chat (projects.ts SwarmProject.status); without the chat
    // loaded, by nobody.
    visible.projects = visible.projects.map(({ owed: _owed, ...p }) => {
      // What the PM owes is its host's alone (timeChecks.ts owedAsk): it may name a message in someone's private chat.
      const chat = state.conversations.find(c => c.id === p.leadConversationId)
      if (chat && canReadGroup(state, actor, chat)) {
        // The server's lines, built from the tasks' own (statusCard.ts), then the coordinator's own; the stored status text is only
        // the latter.
        if (p.status?.shown) return p
        const card = projectCard(state, p, now)
        if (!card.text) return p
        const lastChange = card.changedAt ?? Date.now()
        return { ...p, status: { text: withExtra(card.text, p.status?.own ? p.status.text : null), at: new Date(lastChange).toISOString(), by: p.status?.by ?? chat.leadId ?? '', shown: true } }
      }
      if (p.status === undefined) return p
      const { status: _status, ...rest } = p
      return rest
    })
    visible.agents = visible.agents.filter(a => canReadAgent(state, actor, a))
    visible.starts = visible.starts?.filter(s => visible.conversations.some(c => c.id === s.request.conversationId))
    if (!visible.projects.some(p => p.id === 'lead')) {
      delete visible.project
      visible.machines = visible.machines?.filter(m => m.scope === 'swarm')
    }
    const harnesses = new Set([...visible.agents.map(a => a.harnessId), ...(visible.starts ?? []).flatMap(s => s.harnessId ? [s.harnessId] : [])])
    for (const pool of visible.machines ?? []) {
      if (!pool.observation) continue
      pool.observation.runningHarnessIds = pool.observation.runningHarnessIds.filter(id => harnesses.has(id))
      pool.observation.stoppedHarnessIds = pool.observation.stoppedHarnessIds.filter(id => harnesses.has(id))
      if (pool.observation.closedHarnessIds) pool.observation.closedHarnessIds = pool.observation.closedHarnessIds.filter(id => harnesses.has(id))
      if (pool.observation.harnessProgress) pool.observation.harnessProgress = Object.fromEntries(Object.entries(pool.observation.harnessProgress).filter(([id]) => harnesses.has(id)))
      // Each attempt's tokens are read through the cost summary (costs/read.ts), never from the machine's raw counts.
      delete pool.observation.harnessTokens
      // What the server refused this machine's host is for the sweep alone (liveness.ts failRefusedStarts), never a reader.
      delete pool.observation.refusedStarts
      if (pool.observation.stoppedReservations) pool.observation.stoppedReservations = pool.observation.stoppedReservations.filter(r => harnesses.has(r.harnessId))
      if (pool.observation.preparingStartIds) pool.observation.preparingStartIds = pool.observation.preparingStartIds.filter(id => visible.starts?.some(s => s.id === id))
    }
    for (const start of visible.starts ?? []) if (startPreparing(state, start, now)) start.preparing = true
    visible.invitations = visible.invitations.filter(i => visible.conversations.some(c => c.id === i.conversationId))
  }
  // One index for every project: the loop sets only workDecision, which the index does not hold.
  const workers = workerIndex(visible)
  for (const project of projectsOf(visible)) for (const target of awaitingWorkers(visible, project.id, workers)) target.workDecision = 'awaiting'
  for (const project of visible.projects ?? []) {
    project.skillSet = skillSetOf(project)
    Object.assign(project, { process: processOf(project), columns: projectColumns(project) })
  }
  // An uploaded avatar's stored key stays on the server; readers get a link with each parts read (avatarLinks.ts).
  // Each person as the Swarm names them (usernames.ts), their default included.
  const names = swarmUsernames(state)
  visible.people = visible.people.map(p => ({ ...withAvatarView(p), username: names.get(p.id) })) as Person[]
  visible.agents = visible.agents.map(withAvatarView) as Agent[]
  // On Custom every agent shows the role it runs, null when its kind has none; elsewhere a role id means nothing yet.
  for (const target of visible.agents) {
    const home = projectsOf(state).find(p => p.id === agentProjectId(state, target))
    if (home && skillSetOf(home) === 'custom') target.roleId = agentSetRole(state, home, target)?.id ?? null
    else delete target.roleId
  }
  if (actor.kind !== 'person' || actor.userId !== state.ownerId) visible.invitations = []
  for (const start of visible.starts ?? []) {
    const raw = readsRawReason(actor, start, state.conversations.find(c => c.id === start.request.conversationId))
    if (start.error && !raw) start.error = publicReason(start.error)
    if (start.waiting && !raw) start.waiting = { ...start.waiting, reason: publicReason(start.waiting.reason) }
  }
  // A Buddy brainstorms; where agents run and how work is routed are none of its business (buddies.ts). A start names the
  // machine and the folder on it, so it reads none, though it reads their workgroups.
  if (actor.kind === 'agent' && state.agents.some(a => a.id === actor.agentId && a.buddyOf)) {
    visible.machines = []
    visible.starts = []
    visible.agents = visible.agents.map(a => agentForBuddy(a, actor.agentId))
    visible.conversations = visible.conversations.map(groupForBuddy)
    // A project's repository names the machine and folder it was made from; the address is all a Buddy needs (security
    // review 2 of #2115).
    for (const project of visible.projects ?? []) if (project.repository) project.repository = { repositoryUrl: project.repository.repositoryUrl } as typeof project.repository
    // Where its Product Manager runs names the machine and its start: a Buddy reads how it stands, and why it failed, which
    // names no machine (leadStart.ts leadStartFailed; Diego, 10-30).
    for (const project of visible.projects ?? []) {
      const lead = project.lead
      if (lead) project.lead = { status: lead.status, ...(lead.reason !== undefined ? { reason: lead.reason } : {}) } as typeof lead
      // Which of its person's machines starts the Lead of a Personal project (leadStart.ts) is a machine too.
      delete project.leadClaim
    }
    if (visible.project) visible.project = { repositoryUrl: visible.project.repositoryUrl } as typeof visible.project
    delete visible.rules
    delete visible.routingPolicy
  }
  const seen = seenMachineIds(visible)
  visible.conversations = visible.conversations.map(c => withSeenRequirement(c, seen))
  // A project agent's route notes the accounts PMs run on, on machines it may see: after the Buddy's machines are gone.
  if (actor.kind === 'agent' && visible.machines?.length) {
    const machines = new Set(visible.machines.map(m => m.machineId))
    visible.pmAccounts = pmAccounts(state, actor).filter(a => machines.has(a.machineId) || (a.hostMachineId !== undefined && machines.has(a.hostMachineId)))
  }
  return visible
}