@defrex/autobuild 0.12.0 → 0.13.0

package/packages/core/src/ports/tickets/file.ts

@@ -1,3 +1,5 @@
+import { fileRequestedIds, validateFileTicketId } from './requested-id'
+import { FileTicketAssets } from './file-assets'
 /**
  * File-based TicketSource (SPEC §3.2, §13): the default tracker. A directory
  * of state directories — the lifecycle four `triage/ ready/ doing/ done/`
@@ -17,14 +19,28 @@
  * Concurrency: writes locate and validate immediately before a same-path
  * rewrite or same-filesystem rename; there is no filesystem lock. The
  * dispatcher remains the lifecycle single writer (SPEC §12), and concurrent
- * human edits are explicitly last-write-wins. State renames never cross a
+ * unguarded human edits are explicitly last-write-wins. Revision-checked writes
+ * compare the final read, retaining the same unlocked read/write race window. State renames never cross a
  * filesystem: `<dir>/ready` → `<dir>/doing` is one mount by construction.
  */
+import {
+  STATE_NAME_RULE,
+  validateStateName,
+  validateStatePurpose,
+  orderStates,
+  resolveState,
+} from './states'
 import { readdirSync, statSync } from 'node:fs'
 import { mkdir, readdir, readFile, rename, stat, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
-import { parse as parseToml, stringify as stringifyToml } from 'smol-toml'
-import { z } from 'zod'
+import {
+  parseTicketFile,
+  serializeTicketFile,
+  TicketFileValidationError,
+  type Frontmatter,
+} from './file-codec'
+export { TicketFileValidationError } from './file-codec'
+import { ticketRevision, checkTicketRevision } from './revision'
 import { systemClock, type Clock } from '../../store/types'
 import type {
   DependencyState,
@@ -35,6 +51,7 @@ import type {
   TicketSource,
   TicketStateInfo,
   TicketUpdate,
+  TicketMutation,
 } from '../types'
 import { validateTicketUpdate } from './update'
 
@@ -51,116 +68,22 @@ const LIFECYCLE_DIRS = ['triage', 'ready', 'doing', 'done'] as const
  * and non-`.md` files are never tickets, so it can never be mistaken for one. */
 const ABOUT_FILE = '.about'
 
-const STATE_NAME_RULE =
-  'a state name is one to forty characters of lowercase letters, digits, and hyphens, starting with a letter'
-const STATE_NAME_RE = /^[a-z][a-z0-9-]{0,39}$/
+export { validateStateName } from './states'
 
-/** Throws, stating the rule, unless `name` may be used to create a state. */
-export function validateStateName(name: string): void {
-  if (!STATE_NAME_RE.test(name)) {
-    throw new Error(`file ticket source: invalid state name "${name}" — ${STATE_NAME_RULE}`)
-  }
-}
-
-/** The state names a root listing yields: the lifecycle four, then every other
- * non-dot directory alphabetically. Dot entries and files are never states. */
 function statesIn(directories: string[]): string[] {
-  const lifecycle: string[] = [...LIFECYCLE_DIRS]
-  const extra = directories
-    .filter((name) => !name.startsWith('.') && !lifecycle.includes(name))
-    .sort()
-  return [...lifecycle, ...extra]
-}
-
-/**
- * Resolve a state name to its directory. Case-insensitive in (a config's
- * `readyState = "ready"` means the `ready/` directory), the directory's real
- * name out — and a name matching no directory is a loud error, because a
- * typo'd state must not silently create a directory no `ls` would show.
- */
-function resolveState(name: string, existing: string[]): string {
-  if (existing.includes(name)) return name
-  const matches = existing.filter((s) => s.toLowerCase() === name.toLowerCase())
-  if (matches.length === 1) return matches[0] as string
-  if (matches.length > 1) {
-    throw new Error(
-      `file ticket source: ambiguous state "${name}" — it matches the directories ${matches.join(', ')}`,
-    )
-  }
-  throw new Error(
-    `file ticket source: unknown state "${name}" — this tracker's states are ` +
-      `the directories: ${existing.join(', ')}`,
+  return orderStates(
+    [
+      ...new Set([
+        ...LIFECYCLE_DIRS.filter(
+          (name) => !directories.some((dir) => dir.toLowerCase() === name && dir !== name),
+        ),
+        ...directories.filter((name) => !name.startsWith('.')),
+      ]),
+    ],
+    LIFECYCLE_DIRS,
   )
 }
 
-const frontmatterSchema = z.strictObject({
-  id: z.string().min(1),
-  title: z.string().min(1),
-  labels: z.array(z.string()).default([]),
-  /** Source-local blocker ids (§13). Absent ≡ no dependencies, which keeps
-   * every pre-existing ticket file valid. */
-  blockedBy: z.array(z.string()).optional(),
-  /** Stable external-create adoption key. It travels with the ticket across
-   * state-directory moves, so retries find it in any lifecycle state. */
-  idempotencyKey: z.string().min(1).optional(),
-})
-type Frontmatter = z.infer<typeof frontmatterSchema>
-
-const OPEN_FENCE = '+++\n'
-const CLOSE_FENCE = '\n+++\n'
-
-/** A malformed record that a complete tracker scan may safely exclude. This is
- * deliberately narrower than ordinary Error: filesystem failures, layout
- * violations, duplicate ids, and unexpected exceptions must still abort the
- * listing. */
-export class TicketFileValidationError extends Error {
-  override readonly name = 'TicketFileValidationError'
-}
-
-function parseTicketFile(path: string, raw: string): { front: Frontmatter; body: string } {
-  if (!raw.startsWith(OPEN_FENCE)) {
-    throw new TicketFileValidationError(
-      `${path}: malformed ticket file — missing opening "+++" fence`,
-    )
-  }
-  const close = raw.indexOf(CLOSE_FENCE, OPEN_FENCE.length)
-  if (close === -1) {
-    throw new TicketFileValidationError(
-      `${path}: malformed ticket file — missing closing "+++" fence`,
-    )
-  }
-  let parsed: unknown
-  try {
-    parsed = parseToml(raw.slice(OPEN_FENCE.length, close))
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error)
-    throw new TicketFileValidationError(`${path}: malformed TOML frontmatter — ${message}`)
-  }
-  const result = frontmatterSchema.safeParse(parsed)
-  if (!result.success) {
-    const issues = result.error.issues
-      .map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`)
-      .join('; ')
-    throw new TicketFileValidationError(`${path}: invalid frontmatter — ${issues}`)
-  }
-  return { front: result.data, body: raw.slice(close + CLOSE_FENCE.length) }
-}
-
-function serializeTicketFile(front: Frontmatter, body: string): string {
-  const data: Record<string, unknown> = { id: front.id, title: front.title }
-  if (front.labels.length > 0) data.labels = front.labels
-  // Only when nonempty: a file that never declared blockers must round-trip
-  // byte-identically rather than sprouting `blockedBy = []` on every write.
-  if (front.blockedBy !== undefined && front.blockedBy.length > 0) {
-    data.blockedBy = front.blockedBy
-  }
-  if (front.idempotencyKey !== undefined) {
-    data.idempotencyKey = front.idempotencyKey
-  }
-  // smol-toml stringify ends with a newline; the closing fence follows it.
-  return `${OPEN_FENCE}${stringifyToml(data)}+++\n${body}`
-}
-
 /** A ticket file found on disk: its id, its state (= its directory), its path. */
 interface Located {
   id: string
@@ -170,6 +93,8 @@ interface Located {
 
 export class FileTicketSource implements TicketSource {
   readonly name = 'file'
+  readonly requestedIds = fileRequestedIds
+  readonly assets: FileTicketAssets
 
   private readonly dir: string
   private readonly clock: Clock
@@ -198,6 +123,22 @@ export class FileTicketSource implements TicketSource {
      */
     selfIgnore?: boolean
   }) {
+    this.assets = new FileTicketAssets(opts.dir, async (id) => {
+      const found = await this.locate(id)
+      if (!found)
+        return {
+          exists: false,
+          front: { id, title: id, labels: [] },
+          save: async () => {
+            throw new Error(`file ticket source: asset on unknown ticket "${id}"`)
+          },
+        }
+      const loaded = { found, ...(await this.loadAt(found)) }
+      return {
+        ...loaded,
+        save: (front: Frontmatter) => this.rewriteAt(loaded.found, front, loaded.body),
+      }
+    })
     this.dir = opts.dir
     this.clock = opts.clock ?? systemClock
     const existing = this.statesSync()
@@ -273,7 +214,12 @@ export class FileTicketSource implements TicketSource {
       throw new Error(`file ticket source: comment on unknown ticket "${id}"`)
     }
     const raw = await readFile(found.path, 'utf8')
-    parseTicketFile(found.path, raw) // surface malformed files before appending
+    const parsed = parseTicketFile(found.path, raw)
+    if (parsed.front.comments !== undefined) {
+      parsed.front.comments.push({ body, createdAt: this.clock().toISOString() })
+      await this.rewriteAt(found, parsed.front, parsed.body)
+      return
+    }
     const separator = raw.endsWith('\n') ? '\n' : '\n\n'
     const stamp = this.clock().toISOString()
     await writeFile(found.path, `${raw}${separator}## Comment (${stamp})\n\n${body}\n`)
@@ -301,6 +247,7 @@ export class FileTicketSource implements TicketSource {
   /** Writes `<createState>/file-<n>.md` with the next free n (gaps reused),
    * or adopts the ticket carrying the same idempotency key. */
   async create(draft: TicketDraft, opts: TicketCreateOptions = {}): Promise<Ticket> {
+    if (opts.requestedId !== undefined) validateFileTicketId(opts.requestedId)
     await this.ensureLayout()
     // Resolve before anything is read or written: an unknown state touches no file.
     const targetState =
@@ -332,7 +279,8 @@ export class FileTicketSource implements TicketSource {
     let n = 1
     while (taken.has(`file-${n}`)) n += 1
     const front: Frontmatter = {
-      id: `file-${n}`,
+      id: opts.requestedId ?? `file-${n}`,
+      comments: [],
       title: draft.title,
       labels: [...(draft.labels ?? [])],
       ...(draft.blockedBy !== undefined && draft.blockedBy.length > 0
@@ -340,10 +288,50 @@ export class FileTicketSource implements TicketSource {
         : {}),
       ...(opts.idempotencyKey !== undefined ? { idempotencyKey: opts.idempotencyKey } : {}),
     }
-    await writeFile(this.pathIn(targetState, front.id), serializeTicketFile(front, draft.body))
+    if (taken.has(front.id)) throw new Error(`requested ticket id already occupied: ${front.id}`)
+    await writeFile(this.pathIn(targetState, front.id), serializeTicketFile(front, draft.body), {
+      flag: 'wx',
+    })
     return this.toTicket(front, draft.body, targetState)
   }
 
+  async mutateIfRevision(id: string, expected: string, mutation: TicketMutation): Promise<void> {
+    const patch = mutation.kind === 'update' ? validateTicketUpdate(mutation.patch) : undefined
+    await this.ensureLayout()
+    const target =
+      mutation.kind === 'transition' ? resolveState(mutation.state, await this.states()) : undefined
+    if (mutation.kind === 'blockers') {
+      for (const blocker of new Set(mutation.ids)) {
+        if (mutation.operation === 'block' && blocker === id)
+          throw new Error(`ticket "${id}" cannot block itself`)
+        await this.requireForWrite(blocker, 'blocker')
+      }
+    }
+    // Final locate/read immediately precedes the write. This is best effort,
+    // matching unguarded file writes; it does not introduce filesystem locks.
+    const loaded = await this.requireForWrite(id, 'revision-checked write')
+    checkTicketRevision(this.toTicket(loaded.front, loaded.body, loaded.found.state), expected)
+    if (target !== undefined) {
+      if (loaded.found.state !== target) await rename(loaded.found.path, this.pathIn(target, id))
+      return
+    }
+    const front = { ...loaded.front }
+    let body = loaded.body
+    if (patch) {
+      if (patch.title !== undefined) front.title = patch.title
+      if (patch.labels !== undefined) front.labels = patch.labels
+      if (patch.body !== undefined) body = patch.body
+    } else if (mutation.kind === 'blockers') {
+      const blockers = new Set(front.blockedBy ?? [])
+      for (const blocker of mutation.ids) {
+        if (mutation.operation === 'block') blockers.add(blocker)
+        else blockers.delete(blocker)
+      }
+      front.blockedBy = [...blockers]
+    }
+    await this.rewriteAt(loaded.found, front, body)
+  }
+
   async update(id: string, patch: TicketUpdate): Promise<void> {
     const validated = validateTicketUpdate(patch)
     await this.ensureLayout()
@@ -448,10 +436,7 @@ export class FileTicketSource implements TicketSource {
     opts: { about?: string } = {},
   ): Promise<{ state: TicketStateInfo; created: boolean }> {
     validateStateName(name)
-    const about = opts.about === undefined ? undefined : opts.about.trim()
-    if (about !== undefined && (about === '' || /[\r\n]/.test(about))) {
-      throw new Error('file ticket source: a state purpose must be one nonblank line')
-    }
+    const about = validateStatePurpose(opts.about)
     const existing = await this.states()
     const clash = existing.find((s) => s !== name && s.toLowerCase() === name.toLowerCase())
     if (clash !== undefined) {
@@ -537,10 +522,7 @@ export class FileTicketSource implements TicketSource {
   }
 
   private safeId(id: string): string {
-    if (id.includes('/') || id.includes('\\') || id.includes('..')) {
-      throw new Error(`file ticket source: invalid ticket id "${id}"`)
-    }
-    return id
+    return validateFileTicketId(id)
   }
 
   /** Find the one state dir holding `<id>.md`; null when absent. */
@@ -632,7 +614,9 @@ export class FileTicketSource implements TicketSource {
   /** Rewrite only the located file: editable writes can never move lifecycle
    * state because the existing state-directory path remains authoritative. */
   private async rewriteAt(found: Located, front: Frontmatter, body: string): Promise<void> {
-    await writeFile(found.path, serializeTicketFile(front, body))
+    const temp = `${found.path}.${crypto.randomUUID()}.tmp`
+    await writeFile(temp, serializeTicketFile(front, body))
+    await rename(temp, found.path)
   }
 
   private async listAll(): Promise<TicketListing> {
@@ -658,8 +642,18 @@ export class FileTicketSource implements TicketSource {
 
   private toTicket(front: Frontmatter, body: string, state: string): Ticket {
     return {
+      revision: ticketRevision({
+        title: front.title,
+        body,
+        labels: front.labels,
+        state,
+        blockedBy: front.blockedBy,
+        ...(front.comments !== undefined ? { comments: front.comments } : {}),
+        ...(front.attachments !== undefined ? { attachments: front.attachments } : {}),
+      }),
       ref: { source: this.name, id: front.id, title: front.title },
       ...(front.idempotencyKey !== undefined ? { creationKey: front.idempotencyKey } : {}),
+      ...(front.comments !== undefined ? { comments: structuredClone(front.comments) } : {}),
       title: front.title,
       body,
       state,

package/packages/core/src/ports/tickets/grants.ts

@@ -0,0 +1,47 @@
+import {
+  AUTOBUILD_VERSION,
+  AUTOBUILD_VERSION_HEADER,
+  REMOTE_STORE_PROTOCOL_VERSION,
+  REMOTE_STORE_PROTOCOL_VERSION_HEADER,
+} from '../../store/remote/version'
+import { ticketGrantResponseSchema } from './remote-protocol'
+
+export async function ticketGrantRequest(url: string, token: string, input: unknown) {
+  const response = await fetch(`${url.replace(/\/+$/, '')}/tickets/grants`, {
+    method: 'POST',
+    headers: {
+      authorization: `Bearer ${token}`,
+      'content-type': 'application/json',
+      [AUTOBUILD_VERSION_HEADER]: AUTOBUILD_VERSION,
+      [REMOTE_STORE_PROTOCOL_VERSION_HEADER]: REMOTE_STORE_PROTOCOL_VERSION,
+    },
+    body: JSON.stringify(input),
+    redirect: 'error',
+    signal: AbortSignal.timeout(15000),
+  })
+  // Teardown can race guest/host cleanup; an ended grant is already revoked.
+  if (
+    response.status === 401 &&
+    typeof input === 'object' &&
+    input !== null &&
+    'action' in input &&
+    input.action === 'revoke'
+  )
+    return { ok: true }
+  if (!response.ok)
+    throw new Error(
+      `Ticket grant request failed (${response.status}); refusing project-authority fallback`,
+    )
+  return response.json()
+}
+export async function issueTicketGrant(
+  url: string,
+  token: string,
+  repo: string,
+  execution: string,
+  kind: 'runner' | 'phase',
+) {
+  return ticketGrantResponseSchema.parse(
+    await ticketGrantRequest(url, token, { action: 'issue', repo, execution, kind }),
+  )
+}

package/packages/core/src/ports/tickets/hosted-index.ts

@@ -5,7 +5,24 @@ export { HostedTicketSource } from './remote'
 export type { HostedTicketFetch, HostedTicketSourceOptions } from './remote'
 export {
   HOSTED_TICKET_OPERATIONS,
+  TICKET_COMMENTS_HEADER,
+  TICKET_COMMENTS_CAPABILITY,
   hostedTicketContextSchema,
   hostedTicketRequestSchemas,
+  TICKET_REVISIONS_HEADER,
+  TICKET_REVISIONS_CAPABILITY,
 } from './remote-protocol'
 export type { HostedTicketContext, HostedTicketOperation } from './remote-protocol'
+
+export {
+  TicketRevisionConflict,
+  TicketRevisionUnsupported,
+  mutateTicketIfRevision,
+} from './revision'
+
+export { hostedTicketPolicySchema, type HostedTicketPolicy } from './remote-protocol'
+export { ticketLifecycle } from './lifecycle'
+
+export { orderStates, resolveState, validateStateName, validateStatePurpose } from './states'
+
+export { hostedRequestedIds, MAX_TICKET_NUMBER } from './requested-id'

package/packages/core/src/ports/tickets/identity.ts

@@ -0,0 +1,20 @@
+import type { TicketRef } from '../../ontology'
+import type { TicketSource } from '../types'
+
+/** A per-operation comparison view. Durable references and proposal keys stay exact. */
+export function ticketIdentity(source: TicketSource): (ref: TicketRef) => Promise<string> {
+  const cache = new Map<string, Promise<string>>()
+  return async (ref) => {
+    if (ref.source !== source.name) return `${ref.source}:${ref.id}`
+    let pending = cache.get(ref.id)
+    if (!pending) {
+      pending = source
+        .get(ref.id)
+        .then(
+          (ticket) => `${ref.source}:${ticket?.ref.source === ref.source ? ticket.ref.id : ref.id}`,
+        )
+      cache.set(ref.id, pending)
+    }
+    return pending
+  }
+}

package/packages/core/src/ports/tickets/lifecycle.ts

@@ -0,0 +1,18 @@
+import type { TicketsConfig } from '../../config/schema'
+
+/** Resolve names without changing persisted ticket states or their spelling. */
+export function ticketLifecycle(tickets: TicketsConfig, legacyHosted = false) {
+  const hosted = tickets.source === 'hosted'
+  const old = tickets.source === 'linear' || (hosted && legacyHosted)
+  const triage = tickets.triageState ?? (old ? 'Backlog' : hosted ? 'triage' : 'Triage')
+  return {
+    triage,
+    ready: tickets.readyState,
+    doing:
+      tickets.claimedState ??
+      (tickets.source === 'linear' ? 'In Progress' : old ? 'Doing' : 'doing'),
+    done: tickets.doneState ?? (old ? 'Done' : hosted ? 'done' : 'Done'),
+    create: tickets.createState ?? triage,
+    proposal: tickets.proposalState ?? triage,
+  }
+}

package/packages/core/src/ports/tickets/linear.ts

@@ -1,3 +1,4 @@
+import { ticketRevision } from './revision'
 /**
  * Linear TicketSource (SPEC §3.2, §13): GraphQL over an injectable fetch, so
  * tests run offline against canned exchanges. Queries are deliberately
@@ -109,7 +110,8 @@ interface GqlIssue {
   description: string | null
   url: string
   state: { name: string; type: string } | null
-  labels: { nodes: Array<{ name: string }> }
+  labels: { nodes: Array<{ name: string }>; pageInfo?: PageInfo }
+  comments?: Connection<{ body: string; createdAt: string; user: { name: string } | null }>
   /** Relations where THIS issue is the `relatedIssue` side. A relation
    * `{issue: A, relatedIssue: B, type: "blocks"}` reads "A blocks B", so an
    * issue's blockers are its inverse `blocks` relations, and the blocker is
@@ -237,6 +239,7 @@ function nextCursor(info: PageInfo | undefined, seen: Set<string>): string | nul
   return cursor
 }
 
+const GET_DETAIL_QUERY = `query GetIssue($id: String!) { issue(id: $id) { id identifier title description url state { name type } labels(first: 100) { nodes { name } ${PAGE_INFO} } inverseRelations(first: 100) { nodes { ${READY_RELATIONS} } ${PAGE_INFO} } comments(first: 100, includeArchived: true, orderBy: createdAt) { nodes { body createdAt user { name } } ${PAGE_INFO} } } }`
 const GET_ISSUE_QUERY = `query GetIssue($id: String!) { issue(id: $id) { ${ISSUE_FIELDS} } }`
 const RESOLVE_ISSUE_QUERY = `query ResolveIssue($id: String!) { issue(id: $id) { id } }`
 const ISSUE_STATE_QUERY = `query IssueState($id: String!) { issue(id: $id) { id state { name type } } }`
@@ -343,11 +346,17 @@ export class LinearTicketSource implements TicketSource {
     const seen = new Set<string>()
     let after: string | null = null
     do {
-      const data: { issues: Connection<GqlIssue> } = await this.gql('listReady', LIST_READY_QUERY, {
-        filter,
-        first: READY_PAGE_SIZE,
-        after,
-      })
+      const data: { issues: Connection<GqlIssue> } = await this.gql(
+        'listReady',
+        Object.values(criteria).every((value) => value === undefined)
+          ? LIST_READY_QUERY.replace('after: $after)', 'after: $after, includeArchived: true)')
+          : LIST_READY_QUERY,
+        {
+          filter,
+          first: READY_PAGE_SIZE,
+          after,
+        },
+      )
       await this.completeRelations(data.issues.nodes, true)
       for (const issue of data.issues.nodes) {
         const relations = issue.inverseRelations!.nodes
@@ -369,7 +378,7 @@ export class LinearTicketSource implements TicketSource {
   async get(id: string): Promise<Ticket | null> {
     let data: { issue: GqlIssue | null }
     try {
-      data = await this.gql<{ issue: GqlIssue | null }>('get', GET_ISSUE_QUERY, { id })
+      data = await this.gql<{ issue: GqlIssue | null }>('get', GET_DETAIL_QUERY, { id })
     } catch (error) {
       // Linear's `issue(id:)` field is non-null in the live schema: an unknown
       // identifier arrives as INPUT_ERROR / Entity not found rather than the
@@ -377,7 +386,54 @@ export class LinearTicketSource implements TicketSource {
       if (isEntityNotFound(error)) return null
       throw error
     }
-    return data.issue ? this.toTicket(data.issue) : null
+    if (!data.issue) return null
+    const issue = data.issue
+    // Detail reads exhaust labels and relations independently of dispatch bounds.
+    const labels: Array<{ name: string }> = [...issue.labels.nodes]
+    const labelSeen = new Set<string>()
+    let labelAfter = nextCursor(issue.labels.pageInfo, labelSeen)
+    while (labelAfter !== null) {
+      const page: { issue: { labels: Connection<{ name: string }> } } = await this.gql(
+        'getLabels',
+        `query TicketLabels($id: String!, $after: String) { issue(id: $id) { labels(first: 100, after: $after) { nodes { name } ${PAGE_INFO} } } }`,
+        { id: issue.id ?? id, after: labelAfter },
+      )
+      labels.push(...page.issue.labels.nodes)
+      labelAfter = nextCursor(page.issue.labels.pageInfo, labelSeen)
+    }
+    issue.labels = { nodes: labels }
+    await this.completeRelations([issue], true)
+    const mapComment = (c: { body: string; createdAt: string; user: { name: string } | null }) => ({
+      body: c.body,
+      createdAt: c.createdAt,
+      ...(c.user ? { author: c.user.name } : {}),
+    })
+    const comments: import('../types').TicketComment[] = (issue.comments?.nodes ?? []).map(
+      mapComment,
+    )
+    const seen = new Set<string>()
+    let after = nextCursor(issue.comments?.pageInfo, seen)
+    while (after !== null) {
+      const page: {
+        issue: {
+          comments: Connection<{ body: string; createdAt: string; user: { name: string } | null }>
+        }
+      } = await this.gql(
+        'getComments',
+        `query TicketComments($id: String!, $after: String) { issue(id: $id) { comments(first: 100, after: $after, includeArchived: true, orderBy: createdAt) { nodes { body createdAt user { name } } ${PAGE_INFO} } } }`,
+        { id: issue.id ?? id, after },
+      )
+      comments.push(
+        ...page.issue.comments.nodes.map((c) => ({
+          body: c.body,
+          createdAt: c.createdAt,
+          ...(c.user ? { author: c.user.name } : {}),
+        })),
+      )
+      after = nextCursor(page.issue.comments.pageInfo, seen)
+    }
+    comments.sort((a, b) => Date.parse(a.createdAt) - Date.parse(b.createdAt))
+    return { ...this.toTicket(issue), comments }
   }
 
   /**
@@ -430,6 +486,7 @@ export class LinearTicketSource implements TicketSource {
   }
 
   async create(draft: TicketDraft, opts: TicketCreateOptions = {}): Promise<Ticket> {
+    if (opts.requestedId !== undefined) throw new Error('linear does not support requested ids')
     const reservedId = opts.idempotencyKey
     if (reservedId !== undefined && !linearReservedIssueIdSchema.safeParse(reservedId).success) {
       throw new Error('linear create: idempotency key must be a UUID v4')
@@ -796,7 +853,8 @@ export class LinearTicketSource implements TicketSource {
     // The issue projection predates newly created relations. Preserve native
     // existing blockers and report the requested set now known to be recorded.
     const blockedBy = [...new Set([...blockersOf(issue), ...requested])]
-    return { ...this.toTicket(issue), ...(blockedBy.length > 0 ? { blockedBy } : {}) }
+    const ticket = { ...this.toTicket(issue), ...(blockedBy.length > 0 ? { blockedBy } : {}) }
+    return { ...ticket, revision: ticketRevision(ticket) }
   }
 
   private async adoptCreatedIssue(id: string): Promise<GqlIssue | null> {
@@ -1017,6 +1075,13 @@ export class LinearTicketSource implements TicketSource {
   private toTicket(issue: GqlIssue): Ticket {
     const blockedBy = blockersOf(issue)
     return {
+      revision: ticketRevision({
+        title: issue.title,
+        body: issue.description ?? '',
+        labels: issue.labels.nodes.map((label) => label.name),
+        state: issue.state?.name,
+        blockedBy,
+      }),
       ref: {
         source: this.name,
         id: issue.identifier,