@preventive/triage 1.0.0-alpha.5 → 1.0.0-alpha.51

package/common/github-pr.ts

@@ -0,0 +1,56 @@
+const MAX_PULL_REQUEST_URL = 2048
+
+export interface PullRequestRef { repo: string; number: number }
+export type GithubFixRef = PullRequestRef & { kind: 'pull' | 'issue' }
+export type GithubFixStatus = 'open' | 'draft' | 'closed' | 'merged'
+export type GithubIssueClosedReason = 'completed' | 'not_planned' | 'duplicate' | 'unknown'
+export type GithubFixResult = { url: string } & (
+  { title: string; description: string | null; status: GithubFixStatus; stateReason: GithubIssueClosedReason | null } | { error: 'unavailable' }
+)
+
+// Unknown closure reasons must never imply that an issue was completed.
+export function githubIssueClosedReason(value: unknown): GithubIssueClosedReason {
+  return value === 'completed' || value === 'not_planned' || value === 'duplicate' ? value : 'unknown'
+}
+
+export function isGithubRepoName(value: string): boolean {
+  const [owner, repo, extra] = value.split('/')
+  return extra === undefined && owner !== undefined && repo !== undefined
+    && owner.length <= 39 && /^[a-zA-Z\d](?:-?[a-zA-Z\d])*$/u.test(owner)
+    && repo.length <= 100 && repo !== '.' && repo !== '..' && /^[a-zA-Z\d._-]+$/u.test(repo)
+}
+
+// Only identify the repository and PR number. This never supplies an API URL:
+// the server must match a team repository and use its stored full name.
+function parseGithubNumberedUrl(value: unknown, path: RegExp): PullRequestRef | null {
+  if (typeof value !== 'string' || value.length > MAX_PULL_REQUEST_URL) return null
+  let url: URL
+  try { url = new URL(value) } catch { return null }
+  if (url.href !== value || url.origin !== 'https://github.com' || url.username || url.password) return null
+  const match = path.exec(url.pathname)
+  if (!match) return null
+  const repo = `${match[1]}/${match[2]}`
+  const number = Number(match[3])
+  if (!isGithubRepoName(repo) || !Number.isSafeInteger(number) || number <= 0) return null
+  return { repo, number }
+}
+
+export function parseGithubPrUrl(value: unknown): PullRequestRef | null {
+  return parseGithubNumberedUrl(value, /^\/([^/]+)\/([^/]+)\/pull\/(\d+)(?:\/(?:files|commits|checks))?\/?$/u)
+}
+
+export function parseGithubIssueUrl(value: unknown): PullRequestRef | null {
+  return parseGithubNumberedUrl(value, /^\/([^/]+)\/([^/]+)\/issues\/(\d+)\/?$/u)
+}
+
+export function parseGithubFixUrl(value: unknown): GithubFixRef | null {
+  const pr = parseGithubPrUrl(value)
+  if (pr) return { ...pr, kind: 'pull' }
+  const issue = parseGithubIssueUrl(value)
+  return issue ? { ...issue, kind: 'issue' } : null
+}
+
+// Browser-only deduplication key; never used to construct a server API call.
+export function githubFixKey(ref: GithubFixRef): string {
+  return `${ref.repo.toLowerCase()}#${ref.kind}:${ref.number}`
+}

package/common/gzip.js

@@ -0,0 +1,59 @@
+// Gzip helpers built on the platform CompressionStream /
+// DecompressionStream. Centralised so the half-dozen call sites
+// (storage, triage / workspace export + import, sync-crypto) share
+// one implementation of the Blob → stream → Response plumbing instead
+// of hand-copying it. Bytes in / bytes out is the primitive; the text
+// helpers run the bytes through `common/utf8.js` so the same
+// fatal-on-invalid / BOM-preserving decode rules apply everywhere.
+//
+// `deflate` (raw, no gzip framing) is intentionally NOT covered here —
+// `triage.js` uses it for its own at-rest blob and must stay distinct
+// from the gzip-magic sniffing the bundles / import paths rely on.
+
+import { decodeUtf8, encodeUtf8 } from './utf8.js'
+
+export async function gzipBytes(bytes) {
+  const stream = new Blob([bytes]).stream().pipeThrough(new CompressionStream('gzip'))
+  return new Uint8Array(await new Response(stream).arrayBuffer())
+}
+
+// `maxBytes` (optional) caps the DECOMPRESSED size: gzip expands up to
+// ~1032:1, so a small hostile payload can balloon to GiBs and OOM the
+// process before any content validation runs. Callers decompressing
+// peer-controlled bytes (sync-crypto's inbound changesets) pass a cap;
+// the read then aborts with a RangeError the moment the budget is crossed,
+// instead of materialising the full expansion. Uncapped callers keep
+// the one-shot Response read.
+export async function gunzipBytes(bytes, { maxBytes } = {}) {
+  const stream = new Blob([bytes]).stream().pipeThrough(new DecompressionStream('gzip'))
+  if (maxBytes == null) return new Uint8Array(await new Response(stream).arrayBuffer())
+  const reader = stream.getReader()
+  const chunks = []
+  let total = 0
+  for (;;) {
+    const { value, done } = await reader.read()
+    if (done) break
+    total += value.length
+    if (total > maxBytes) {
+      // Cancel so the DecompressionStream stops inflating the rest.
+      try { await reader.cancel() } catch {}
+      throw new RangeError(`gunzipBytes: decompressed size exceeds ${maxBytes}-byte cap`)
+    }
+    chunks.push(value)
+  }
+  const out = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) {
+    out.set(chunk, offset)
+    offset += chunk.length
+  }
+  return out
+}
+
+export async function gzipText(text) {
+  return await gzipBytes(encodeUtf8(text))
+}
+
+export async function gunzipToText(bytes) {
+  return decodeUtf8(await gunzipBytes(bytes))
+}

package/common/line-diff.d.ts

@@ -0,0 +1,8 @@
+// Type declarations for `common/line-diff.js`, for `.ts` callers.
+
+// Lines `a[a0..a1)` replaced by `b[b0..b1)`.
+export interface ChangeBlock { a0: number; a1: number; b0: number; b1: number }
+
+export function textLines(text: string): string[]
+export function changeBlocks(before: string, after: string, ignoreWhitespace?: boolean): ChangeBlock[]
+export function blocksHold(before: string, after: string, blocks: unknown, ignoreWhitespace?: boolean): boolean

package/common/line-diff.js

@@ -0,0 +1,57 @@
+// The change blocks between two texts' lines, found by @preventive/diff: what
+// the viewer's Compare diffs (ui/view/bundle-compare-code-model.js); and the
+// server's check, apart from @preventive/compare's own, that its diff with
+// renamed names hidden takes the old side to the new (server-managed/rename-diff.ts).
+//
+// Lines are numbered the way the diff numbers them: from zero, a final
+// newline ending the last line rather than starting an empty one.
+import { changeSet } from '@preventive/diff'
+
+export function textLines(text) {
+  if (text === '') return []
+  const lines = text.split('\n')
+  if (lines.at(-1) === '') lines.pop()
+  return lines
+}
+
+// Whether a text's last line ends in a newline. One added or dropped there is
+// a change of that line, as diff has it (the viewer marks it on that line's
+// row), but for diff -b, which ignores it as it does other trailing blanks.
+const endsLine = text => text === '' || text.endsWith('\n')
+
+// A line as diff -b reads it (@preventive/diff's): a run of the C locale's
+// blanks as one space, and those that end it as none.
+const spacing = line => line.replace(/[ \t\n\v\f\r]+$/u, '').replaceAll(/[ \t\n\v\f\r]+/gu, ' ')
+
+// Each `a[a0..a1)` replaced by `b[b0..b1)`. `ignoreWhitespace` is diff -b:
+// lines differing only in how much whitespace they have pair up as unchanged,
+// whitespace added or removed between other characters still a change. Those
+// a unified diff with no context shows (horizon 0), found without printing
+// one and reading it back.
+export function changeBlocks(before, after, ignoreWhitespace = false) {
+  return changeSet(before, after, { horizon: 0, whitespace: ignoreWhitespace ? 'change' : 'none' }).map(({ a0, a1, b0, b1 }) => ({ a0, a1, b0, b1 }))
+}
+
+// Whether `blocks` take `before`'s lines to `after`'s: each in order and apart
+// from the last, within both texts, and every line between them alike on both
+// sides (alike but for how much whitespace they have where `ignoreWhitespace`,
+// as diff -b has them), the last line in a block where a newline was added or
+// dropped after it, so that a diff drawn from them hides no change. A check on
+// what changeBlocks found, or on one found apart from the texts drawn.
+export function blocksHold(before, after, blocks, ignoreWhitespace = false) {
+  if (!Array.isArray(blocks)) return false
+  const a = textLines(before), b = textLines(after)
+  const alike = ignoreWhitespace ? (x, y) => spacing(x) === spacing(y) : (x, y) => x === y
+  let i = 0, j = 0
+  for (const block of [...blocks, { a0: a.length, a1: a.length, b0: b.length, b1: b.length, last: true }]) {
+    const { a0, a1, b0, b1 } = block ?? {}
+    if (![a0, a1, b0, b1].every(Number.isInteger) || a0 < i || b0 < j || a1 < a0 || b1 < b0 || a1 > a.length || b1 > b.length) return false
+    // A block changes a line, and as many lines are alike before it on each side.
+    if ((!block.last && a1 === a0 && b1 === b0) || a0 - i !== b0 - j) return false
+    if (block.last && a0 > i && !ignoreWhitespace && endsLine(before) !== endsLine(after)) return false
+    for (; i < a0; i++, j++) if (!alike(a[i], b[j])) return false
+    i = a1
+    j = b1
+  }
+  return true
+}

package/common/linked-workspace-groups.js

@@ -0,0 +1,63 @@
+// Explicit links combine already-resolved workspace App rows. This is a view
+// grouping, not report deduplication: each report's revalidation answer has
+// already been checked in its own row, and links never create report conflicts.
+//
+// `visibleTabs` decides which tabs may BRIDGE two rows; `retainedTabs` (the
+// same projection unless the caller says otherwise) decides which tabs the
+// combined row keeps. They part when a display choice shows a row more of
+// itself without meaning to re-draw the workspace's row boundaries.
+export function mergeLinkedWorkspaceGroups(groups, duplicatesOf, visibleTabs, retainedTabs = visibleTabs) {
+  const parent = groups.map((_, i) => i)
+  const find = (i) => {
+    while (parent[i] !== i) { parent[i] = parent[parent[i]]; i = parent[i] }
+    return i
+  }
+  const tabs = groups.map(visibleTabs)
+  const byId = new Map()
+  for (let i = 0; i < tabs.length; i++) {
+    for (const f of tabs[i]) {
+      if (!f.id) continue
+      if (!byId.has(f.id)) byId.set(f.id, [])
+      byId.get(f.id).push(i)
+    }
+  }
+  for (const [id, rows] of byId) {
+    for (const other of duplicatesOf(id)) {
+      if (other === id) continue
+      for (const a of rows) {
+        for (const b of byId.get(other) ?? []) {
+          const left = find(a), right = find(b)
+          if (left !== right) parent[right] = left
+        }
+      }
+    }
+  }
+  const components = new Map()
+  for (let i = 0; i < groups.length; i++) {
+    const root = find(i)
+    if (!components.has(root)) components.set(root, [])
+    components.get(root).push(i)
+  }
+  if (components.size === groups.length) return groups
+  const key = (f) => f.id ?? String(f._id)
+  const merged = [...components.values()].map((indices) => {
+    if (indices.length === 1) return groups[indices[0]]
+    // Retain the tabs visible in each original row. An imported App finding
+    // or an unjudged source row must not disappear when linked to a pass row.
+    const visible = new Map()
+    for (const i of indices) for (const f of retainedTabs(groups[i])) if (!visible.has(key(f))) visible.set(key(f), f)
+    const members = new Map()
+    for (const i of indices) {
+      for (const f of groups[i]) {
+        if (!members.has(key(f))) members.set(key(f), visible.get(key(f)) ?? f)
+      }
+    }
+    const group = [...members.values()]
+    const first = groups[indices[0]]
+    group.workspaceKey = first.workspaceKey ?? key(first[0])
+    group.linkedTabs = [...visible.values()]
+    return group
+  })
+  Object.defineProperty(merged, 'ruledOutIds', { value: groups.ruledOutIds, configurable: true })
+  return merged
+}

package/common/managed/agent-tasks.ts

@@ -0,0 +1,292 @@
+// Agents' sessions and their tasks, reconstructed from what each
+// leaves on GitHub (the code viewer's Agents tab, repository-agents.js): a
+// task is a pull request it opened, or a commit it pushed to the default
+// branch without one; a session holds as many as name it, with the branches
+// they are on and the issues they work on. The server reads each artifact's
+// own texts, never others' comments on it (a pull request's body and its
+// head and merge commits' messages, where an agent links its session; a
+// commit's message; a branch's tip commit) for the marks an agent leaves
+// (agentSignals), sending those alone; agentSessions then groups them:
+// those naming one session, a pull request with its branch, a branch with
+// the session its commits name, an issue with the pull requests closing it
+// or a branch named for it. Without a session named, a branch's pull
+// requests are one session, and a commit its own.
+//
+// The agents are Claude and Codex, and those the server knows by their GitHub
+// Apps or accounts (server-managed/app-agents.ts APP_AGENTS): each told by its
+// fingerprint, a line of its texts, by the account its work is authored by
+// (github-agents.ts githubAgent), or by its branches' prefix, the server's to
+// read, and named to the client
+// by its id, name and avatar (AppAgent). Such an agent names no session:
+// a pull request of its is a session alone, with its branch; Claude's or
+// Codex's marks on its work show those as its tools. A pull request labelled
+// for an agent (labelAgents) is that agent's too, where its own texts and
+// branch name none: the mark one who ran it gives work it left unmarked.
+import { githubAgent } from './github-agents.ts'
+
+// 'claude', 'codex', or an app agent's id.
+export type Agent = string
+
+// An agent known by its GitHub App or account, as the server names it to the
+// client: its id, its name, and its avatar, its mark (/api/avatar/<avatar>:
+// `app-<id>` a GitHub App's, `user-<id>` a GitHub account's), where the app
+// draws no mark of its own for it (Copilot's, ui/view/repository-tiles.js).
+export interface AppAgent { id: string; name: string; avatar?: string }
+// How the server tells one, beside the accounts its work is authored by (its
+// id githubAgent's): its fingerprint, a line of an artifact's texts starting
+// with it; its branches' prefix.
+export interface AppAgentMarks { id: string; fingerprint?: string; prefix: string }
+// An artifact's author, as GitHub names its account: its login and id.
+export interface AgentAuthor { login: string; id: number }
+
+// What an artifact's texts say of the agents that made it: the Claude Code
+// sessions and Codex tasks they link, whether they carry Claude's marks,
+// its co-author trailer or its "Generated with" line, and Codex's, its
+// co-author trailer, and the app agents whose fingerprints they carry, or
+// whose branch it is.
+export interface AgentSignals { sessions: string[]; tasks: string[]; claude: boolean; codex: boolean; agents: string[] }
+
+// Each by its author's login, and their account's numeric id (`authorId`)
+// where GitHub names it.
+export interface AgentPull { number: number; title: string; state: 'open' | 'merged' | 'closed'; draft: boolean; author: string | null; authorId?: number | null
+  // Its branch, and the owner of the fork it is in, null where it is in the
+  // repository itself.
+  createdAt: number | null; updatedAt: number | null; head: string | null; fork: string | null; additions: number; deletions: number; commits: number
+  closes: number[]; signals: AgentSignals }
+export interface AgentIssue { number: number; title: string; state: 'open' | 'closed'; author: string | null; authorId?: number | null; createdAt: number | null; updatedAt: number | null }
+export interface AgentBranch { name: string; at: number | null; author: string | null; authorId?: number | null; signals: AgentSignals }
+// A commit to the default branch no pull request merged.
+export interface AgentCommit { oid: string; title: string; at: number | null; author: string | null; authorId?: number | null; additions: number; deletions: number
+  signals: AgentSignals }
+
+export interface AgentSession {
+  id: string
+  agents: Agent[]
+  // Where to open it: a Claude Code session or a Codex task.
+  sessions: string[]
+  tasks: string[]
+  title: string
+  authors: string[]
+  startedAt: number | null
+  updatedAt: number | null
+  state: 'open' | 'merged' | 'closed' | 'branch'
+  // Its tasks: the pull requests it opened, and the commits it pushed to
+  // the default branch, the newest first.
+  pulls: Pick<AgentPull, 'number' | 'title' | 'state' | 'draft'>[]
+  commits: Pick<AgentCommit, 'oid' | 'title'>[]
+  issues: Pick<AgentIssue, 'number' | 'title' | 'state'>[]
+  branches: string[]
+  // The commits its pull requests hold, and their lines and its commits'.
+  commitCount: number
+  additions: number
+  deletions: number
+}
+
+const SESSION = /https:\/\/claude\.ai\/code\/(session_[A-Za-z\d]{6,64})\b/gu
+const CODEX_TASK = /https:\/\/chatgpt\.com\/codex\/tasks\/(task_[a-z]_[A-Za-z\d]{6,64})\b/gu
+// Claude's marks on its commits and pull requests: its co-author trailer,
+// its "Generated with" line, its session trailer.
+const CLAUDE_MARK = /^co-authored-by: claude\b|generated with \[claude code\]|^claude-session:/imu
+// Codex's: its co-author trailer, by its address, as Codex names itself
+// co-author of the commits it makes as whoever ran it; a trailer of a text's
+// trailers (trailerBlock), not a line before them that shows one.
+const CODEX_MARK = /^co-authored-by:[ \t]*[^<\n]*<codex@openai\.com>[ \t]*$/imu
+const MAX_LINKS = 8
+
+// A message's trailers, as git reads them (`git interpret-trailers`): its
+// last paragraph, past its subject's, where each of its lines is a trailer
+// (`Key: value`) or goes on with one (indented), or, where it holds git's
+// own `Signed-off-by:`, a quarter of them are; none where it isn't, as
+// lines a description or example holds, fenced or not, are not.
+const TRAILER_LINE = /^[A-Za-z\d-]+[ \t]*:/u
+export function trailerBlock(text: string): string {
+  const paragraphs = text.replaceAll('\r\n', '\n').trim().split(/\n[ \t]*\n/u)
+  const block = paragraphs.length > 1 ? paragraphs.at(-1)! : ''
+  const lines = block.split('\n')
+  const trailers = lines.filter(line => TRAILER_LINE.test(line)).length
+  const others = lines.filter((line, at) => !TRAILER_LINE.test(line) && !(at > 0 && /^[ \t]/u.test(line))).length
+  return others === 0 || (lines.some(line => /^signed-off-by[ \t]*:/iu.test(line)) && trailers * 3 >= others) ? block : ''
+}
+
+// The agents of those whose ids are `ids` that `labels` name (a pull
+// request's): a label an agent's id, regardless of case, alone or after
+// `agent:` or `agent/` (`Codex`, `agent: claude`).
+const LABEL = /^(?:agent[:/] ?)?([a-z][a-z\d-]*)$/u
+export function labelAgents(labels: unknown[], ids: readonly string[]): Agent[] {
+  return [...new Set(labels.flatMap(label => {
+    const id = typeof label === 'string' ? LABEL.exec(label.trim().toLowerCase())?.[1] : undefined
+    return id !== undefined && ids.includes(id) ? [id] : []
+  }))]
+}
+
+// The sessions and tasks `texts` link, whether they carry Claude's marks and
+// Codex's, and the agents of `apps` whose fingerprints start a line of them
+// (not one a text quotes, as one describing it may), whose account `author`
+// is (githubAgent), or whose prefix the branch `branch` is under;
+// Claude, Codex or the agents of `apps` its `labels` name (labelAgents).
+export function agentSignals(texts: unknown[], apps: readonly AppAgentMarks[] = [], branch: string | null = null,
+  author: AgentAuthor | null = null, labels: unknown[] = []): AgentSignals {
+  const strings = texts.filter((text): text is string => typeof text === 'string')
+  const found = (pattern: RegExp) => [...new Set(strings.flatMap(text => [...text.matchAll(pattern)].map(match => match[1]!)))].slice(0, MAX_LINKS)
+  const lines = strings.flatMap(text => text.split('\n').map(line => line.trimStart()))
+  const authored = author ? githubAgent(author.login, author.id) : null
+  const labelled = labelAgents(labels, ['claude', 'codex', ...apps.map(app => app.id)])
+  return { sessions: found(SESSION), tasks: found(CODEX_TASK), claude: labelled.includes('claude') || strings.some(text => CLAUDE_MARK.test(text)),
+    codex: labelled.includes('codex') || strings.some(text => CODEX_MARK.test(trailerBlock(text))),
+    agents: apps.filter(app => (app.fingerprint && lines.some(line => line.startsWith(app.fingerprint!)))
+      || authored === app.id || branch?.startsWith(app.prefix) || labelled.includes(app.id)).map(app => app.id) }
+}
+
+// The agent a branch's name says made it, and the issue or pull request the
+// Claude GitHub App names its branch for (`claude/issue-12-…`).
+export function agentBranch(name: string | null): { agent: Agent | null; issue: number | null; pull: number | null } {
+  const agent = name?.startsWith('claude/') ? 'claude' : name?.startsWith('codex/') ? 'codex' : null
+  const named = agent === 'claude' ? /^claude\/(issue|pr)-([1-9]\d{0,9})-/u.exec(name!) : null
+  return { agent, issue: named?.[1] === 'issue' ? Number(named[2]) : null, pull: named?.[1] === 'pr' ? Number(named[2]) : null }
+}
+
+// A pull request's branch, as GitHub names one in a fork: `owner:branch`;
+// two forks' of one name, or a fork's and the repository's, are two.
+const headName = (pull: AgentPull) => pull.head && pull.fork ? `${pull.fork}:${pull.head}` : pull.head
+
+const signalAgents = (signals: AgentSignals): Agent[] => [...signals.agents, ...signals.sessions.length > 0 || signals.claude ? ['claude'] : [],
+  ...signals.tasks.length > 0 || signals.codex ? ['codex'] : []]
+const TOOLS = new Set(['claude', 'codex'])
+
+type Artifacts = { pulls?: AgentPull[]; commits?: AgentCommit[]; issues?: AgentIssue[]; branches?: AgentBranch[] }
+type Group = { agents: Set<Agent>; keys: string[] }
+
+// The artifacts joined (`pull:<n>`, `commit:<oid>`, `branch:<name>`,
+// `session:<id>`, `task:<id>`), each set with the agents whose marks are on
+// them: by the sessions and tasks they link and the branches pull requests
+// are from. An app agent's join none by what they link, and a pull request
+// of its its branch alone, where no pull request newer is from it, an app
+// agent's or another's: one a session.
+function artifactGroups({ pulls = [], commits = [], branches = [] }: Artifacts): Group[] {
+  const parent = new Map<string, string>()
+  const find = (key: string): string => {
+    let root = key
+    while (parent.has(root) && parent.get(root) !== root) root = parent.get(root)!
+    parent.set(key, root)
+    return root
+  }
+  const join = (a: string, b: string) => {
+    const [x, y] = [find(a), find(b)]
+    if (x !== y) parent.set(y, x)
+  }
+  const agentsOf = new Map<string, Set<Agent>>()
+  const mark = (key: string, agents: Agent[]) => { for (const agent of agents) agentsOf.set(key, new Set([...agentsOf.get(key) ?? [], agent])) }
+  const linked = (key: string, signals: AgentSignals) => {
+    find(key)
+    if (signals.agents.length === 0) for (const session of signals.sessions) join(key, `session:${session}`)
+    if (signals.agents.length === 0) for (const task of signals.tasks) join(key, `task:${task}`)
+    mark(key, signalAgents(signals))
+  }
+  const branchNames = new Set(branches.map(branch => branch.name))
+  for (const branch of branches) {
+    const key = `branch:${branch.name}`
+    linked(key, branch.signals)
+    const { agent } = agentBranch(branch.name)
+    if (agent) mark(key, [agent])
+  }
+  // The newest pull request read from each branch, by its number, as GitHub
+  // numbers them as they are opened: they are read as they were updated.
+  const newest = new Map<string, number>()
+  for (const pull of pulls) {
+    const head = headName(pull)
+    if (head !== null && pull.number > (newest.get(head) ?? 0)) newest.set(head, pull.number)
+  }
+  for (const pull of pulls) {
+    const key = `pull:${pull.number}`
+    linked(key, pull.signals)
+    const { agent, pull: named } = agentBranch(pull.head)
+    if (agent) mark(key, [agent])
+    // Its branch, an agent's or its own, read or not; a fork's its own.
+    const head = headName(pull)
+    if (pull.signals.agents.length > 0) {
+      if (head !== null && newest.get(head) === pull.number) join(key, `branch:${head}`)
+      continue
+    }
+    if (head && (agent || signalAgents(pull.signals).length > 0 || branchNames.has(head))) join(key, `branch:${head}`)
+    if (named) join(key, `pull:${named}`)
+  }
+  for (const commit of commits) linked(`commit:${commit.oid}`, commit.signals)
+
+  const groups = new Map<string, Group>()
+  for (const key of parent.keys()) {
+    const root = find(key)
+    const group = groups.get(root) ?? { agents: new Set(), keys: [] }
+    group.keys.push(key)
+    for (const agent of agentsOf.get(key) ?? []) group.agents.add(agent)
+    groups.set(root, group)
+  }
+  return [...groups.values()]
+}
+
+const byTime = <T>(time: (item: T) => number | null) => (a: T, b: T) => (time(a) ?? 0) - (time(b) ?? 0)
+
+// The session a group of artifacts is, its tasks and what they touched; null
+// for one no agent left marks on, or holding none read.
+function sessionOf({ agents, keys }: Group, { pulls, commits, issues, branches }: {
+  pulls: Map<number, AgentPull>; commits: Map<string, AgentCommit>; issues: Map<number, AgentIssue>; branches: Map<string, AgentBranch> }): AgentSession | null {
+  if (agents.size === 0) return null
+  const of = (prefix: string) => keys.filter(key => key.startsWith(prefix)).map(key => key.slice(prefix.length))
+  const taskPulls = of('pull:').flatMap(number => pulls.get(Number(number)) ?? []).toSorted(byTime(pull => pull.createdAt))
+  const taskCommits = of('commit:').flatMap(oid => commits.get(oid) ?? []).toSorted(byTime(commit => commit.at))
+  const names = [...new Set([...of('branch:'), ...taskPulls.flatMap(pull => headName(pull) ?? [])])]
+  // The issues its pull requests close, and those its branches are named
+  // for, by a pull request's own name for its branch, a fork's too.
+  const issueNumbers = new Set([...taskPulls.flatMap(pull => pull.closes),
+    ...taskPulls.flatMap(pull => agentBranch(pull.head).issue ?? []), ...of('branch:').flatMap(name => agentBranch(name).issue ?? [])])
+  const taskIssues = [...issueNumbers].flatMap(number => issues.get(number) ?? []).toSorted(byTime(issue => issue.createdAt))
+  const taskBranches = names.flatMap(name => branches.get(name) ?? [])
+  const items = [...taskPulls, ...taskCommits, ...taskIssues, ...taskBranches]
+  if (items.length === 0) return null
+  const [codexTasks, sessions] = [of('task:'), of('session:')]
+  const started = items.flatMap(item => ('createdAt' in item ? item.createdAt : item.at) ?? [])
+  const updated = items.flatMap(item => ('updatedAt' in item ? item.updatedAt : item.at) ?? [])
+  const states = new Set(taskPulls.map(pull => pull.state))
+  // Its first task names it: the earliest of its pull requests and commits.
+  const first = [...taskPulls.map(pull => ({ at: pull.createdAt, title: pull.title })), ...taskCommits.map(commit => ({ at: commit.at, title: commit.title }))]
+    .toSorted(byTime(task => task.at))[0]
+  const landed = [...taskPulls, ...taskCommits]
+  return {
+    id: sessions[0] ?? codexTasks[0] ?? (taskPulls[0] ? `pull-${taskPulls[0].number}` : taskCommits[0]?.oid ?? names[0] ?? ''),
+    // An app agent's first, the one whose session it is, then the tools it
+    // used, Claude's or Codex's.
+    agents: [...[...agents].filter(agent => !TOOLS.has(agent)), ...['claude', 'codex'].filter(agent => agents.has(agent))],
+    sessions, tasks: codexTasks,
+    title: first?.title ?? taskIssues[0]?.title ?? names[0] ?? '',
+    authors: [...new Set(items.flatMap(item => item.author ?? []))],
+    startedAt: started.length > 0 ? Math.min(...started) : null,
+    updatedAt: updated.length > 0 ? Math.max(...updated) : null,
+    state: states.has('open') ? 'open' : states.has('merged') || taskCommits.length > 0 ? 'merged' : states.has('closed') ? 'closed' : 'branch',
+    pulls: taskPulls.map(({ number, title, state, draft }) => ({ number, title, state, draft })).toReversed(),
+    commits: taskCommits.map(({ oid, title }) => ({ oid, title })).toReversed(),
+    issues: taskIssues.map(({ number, title, state }) => ({ number, title, state })),
+    branches: names,
+    commitCount: taskPulls.reduce((sum, pull) => sum + pull.commits, 0) + taskCommits.length,
+    additions: landed.reduce((sum, item) => sum + item.additions, 0),
+    deletions: landed.reduce((sum, item) => sum + item.deletions, 0),
+  }
+}
+
+// The sessions `pulls`, `commits`, `issues` and `branches` make, the most
+// recently updated first: each a set of them, joined by the sessions and
+// tasks they link and the branches pull requests are from, with the issues
+// a pull request closes or a branch is named for.
+// Artifacts no agent left marks on belong to none. Where pull requests
+// updated before `branchesSince` are yet to be read, a session of branches
+// alone older than that waits for them: its pull request may be among them.
+export function agentSessions(artifacts: Artifacts, { branchesSince = null }: { branchesSince?: number | null } = {}): AgentSession[] {
+  const lookups = {
+    pulls: new Map((artifacts.pulls ?? []).map(pull => [pull.number, pull])),
+    commits: new Map((artifacts.commits ?? []).map(commit => [commit.oid, commit])),
+    issues: new Map((artifacts.issues ?? []).map(issue => [issue.number, issue])),
+    branches: new Map((artifacts.branches ?? []).map(branch => [branch.name, branch])),
+  }
+  const waiting = (session: AgentSession) => branchesSince !== null && session.pulls.length === 0 && session.commits.length === 0
+    && (session.updatedAt ?? 0) < branchesSince
+  return artifactGroups(artifacts).flatMap(group => sessionOf(group, lookups) ?? []).filter(session => !waiting(session))
+    .toSorted(byTime(session => session.updatedAt)).toReversed()
+}

package/common/managed/comments.ts

@@ -0,0 +1,34 @@
+// Managed comments are independent records, shared by reports containing the
+// same finding. Imported and legacy comments may lack attribution or dates.
+export interface ManagedComment {
+  id: string
+  findingId: string
+  body: string
+  authorId: string | null
+  authorLogin: string | null
+  createdAt: number | null
+  updatedAt: number | null
+  version: number
+}
+
+export const MAX_COMMENT_TEXT = 10_000
+
+// Callers also enforce write access to the report containing the finding.
+// Admins can remove comments with no linked user, but cannot claim authorship.
+export function canDeleteComment(comment: Pick<ManagedComment, 'authorId'>, actor: { id: string; role: string } | null | undefined): boolean {
+  return actor != null && (comment.authorId === actor.id || (comment.authorId == null && actor.role === 'admin'))
+}
+
+export function compareManagedComments(a: ManagedComment, b: ManagedComment): number {
+  if (a.createdAt == null && b.createdAt != null) return -1
+  if (a.createdAt != null && b.createdAt == null) return 1
+  const byDate = (a.createdAt ?? 0) - (b.createdAt ?? 0)
+  if (byDate !== 0) return byDate
+  if (a.id === b.id) return 0
+  return a.id < b.id ? -1 : 1
+}
+
+export function parseCommentBody(value: unknown): string | null {
+  if (typeof value !== 'string' || value.length > MAX_COMMENT_TEXT) return null
+  return value.trim() || null
+}

package/common/managed/finding-detail.d.ts

@@ -0,0 +1,3 @@
+export const FINDING_DETAIL_FIELDS: readonly string[]
+export function liteReportData(data: unknown, options?: { fold?: boolean }): unknown
+export function liteWorkspace<T extends { filename: string; data: unknown }>(reports: readonly T[], links: readonly (readonly string[])[]): { reports: T[]; folded: boolean }

package/common/managed/finding-detail.js

@@ -0,0 +1,66 @@
+import { findingTitle, reportEntries, revalidateKindOf } from '@preventive/report'
+import { managedTeamRevalidationConflicted } from './team-app.js'
+
+// A finding's detail: what its popup, the views besides the board and an
+// export read, and the board does not. Its narrative and evidence, the hash
+// its Code button finds a bundle by, the export it names, the facts its card
+// and an export tell (write-md-finding.js PLAIN_FIELDS, CODE_FIELDS, but for
+// `priority`, which the board sorts and filters by), and the run meta its
+// card's run line and a report's header read (its `model` and `type`, which
+// the board's filters read, stay). A team's
+// reports are first sent without it (server-managed/team-reports.ts), the
+// board drawn from them, and their findings filled in from the whole reports
+// (ui/view/managed-details.js).
+export const FINDING_DETAIL_FIELDS = Object.freeze([
+  'description', 'evidence', 'impact', 'reproduction', 'recommendation', 'confidenceReason', 'revalidateVerdict', 'revalidateRecommendation',
+  'fileHash', 'exportName', 'methodName',
+  'commitHash', 'auditedCommit', 'detectedAt', 'committedAt', 'dateCreated', 'status', 'branch', 'pocStatus', 'parent', 'slug', 'reportPath',
+  'category', 'discoveredIn', 'effort', 'exportsMode',
+])
+const DETAIL = new Set(FINDING_DETAIL_FIELDS)
+// As much of a name as a heading takes (@preventive/report write-md-finding.js
+// HEADING_MAX), about a board card's three lines.
+const NAME_CHARS = 120
+
+// A finding without its detail. One without a title of its own is named by its
+// description's first line (findingTitle), which it keeps as its description,
+// as much of it as a card shows.
+function liteFinding(finding) {
+  if (!finding || typeof finding !== 'object' || Array.isArray(finding)) return finding
+  const lite = Object.fromEntries(Object.entries(finding).filter(([key]) => !DETAIL.has(key)))
+  const titled = typeof finding.title === 'string' && finding.title.trim() !== ''
+  const title = titled ? '' : findingTitle(finding)
+  if (title) lite.description = title.length > NAME_CHARS ? `${title.slice(0, NAME_CHARS - 1)}…` : title
+  return lite
+}
+
+const isPass = finding => revalidateKindOf(finding) === 'revalidation'
+
+// A report's data, its findings without their detail. A workspace opening in
+// App mode shows of an entry holding the revalidation pass's row that row
+// alone (ui/view/group.js foldedTabs): with `fold`, such an entry is sent as
+// the pass's rows, the rows beneath them left for the whole reports
+// (ui/view/managed-details.js).
+export function liteReportData(data, { fold = false } = {}) {
+  const key = Array.isArray(data?.findings) ? 'findings' : Array.isArray(data?.groups) ? 'groups' : null
+  if (!key) return data
+  const entries = data[key].map(entry => {
+    if (!Array.isArray(entry)) return liteFinding(entry)
+    const shown = fold && entry.length > 1 && entry.some(isPass) ? entry.filter(isPass) : entry
+    return shown.map(liteFinding)
+  })
+  return { ...data, [key]: entries }
+}
+
+const rows = data => (reportEntries(data) ?? []).flat().length
+
+// A team's reports as its board is first sent them (server-managed/team-reports.ts),
+// each `liteReportData`, folded where nothing in the workspace contradicts the
+// revalidation pass, which opens a view of it in App mode
+// (ui/view/render.js configureReportRevalidation); `folded` where that left
+// rows out.
+export function liteWorkspace(reports, links) {
+  const fold = !managedTeamRevalidationConflicted(Object.assign(reports.map(({ filename, data }) => ({ filename, data })), { links }))
+  const lite = reports.map(report => ({ ...report, data: liteReportData(report.data, { fold }) }))
+  return { reports: lite, folded: fold && lite.some((report, index) => rows(report.data) < rows(reports[index].data)) }
+}