@defrex/autobuild 0.8.0 → 0.10.0

package/packages/core/src/ports/forge/github-transport.ts

@@ -213,8 +213,14 @@ export function createGitHubFetchTransport(opts: {
       // a private repository is otherwise indistinguishable from a bad path,
       // and the operator's fix (export a token, or `gh auth login`) is the
       // point of the message.
+      // `in` rather than relying on the `token === undefined` discriminant:
+      // the plugin-sdk typecheck fixture compiles this chain without
+      // strictNullChecks, where `undefined` is assignable to `string` and
+      // the union stops discriminating (AUT-517).
       const anonymous =
-        credential.token === undefined ? ` (request was unauthenticated: ${credential.reason})` : ''
+        credential.token === undefined && 'reason' in credential
+          ? ` (request was unauthenticated: ${credential.reason})`
+          : ''
       throw new GitHubApiError(
         response.status,
         `${githubErrorMessage(response.status, json, text)}${anonymous}`,
@@ -335,9 +341,14 @@ export async function resolveGitHubToken(
   if (fromEnv !== undefined) return { token: fromEnv }
   const probe = await githubTokenFromGhCli(exec)
   if (probe.token !== undefined) return probe
+  // `in` rather than relying on the `token !== undefined` discriminant: the
+  // plugin-sdk typecheck fixture compiles this chain without
+  // strictNullChecks, where `undefined` is assignable to `string` and the
+  // union stops discriminating (AUT-517). A miss always carries its reason.
+  const missReason = 'reason' in probe ? probe.reason : 'no credential source succeeded'
   return {
     token: undefined,
-    reason: `GITHUB_TOKEN and GH_TOKEN are unset and ${probe.reason}`,
+    reason: `GITHUB_TOKEN and GH_TOKEN are unset and ${missReason}`,
   }
 }
 

package/packages/core/src/ports/forge/github.ts

@@ -470,6 +470,16 @@ function restMergeState(raw: string): MergeStateStatus {
 
 const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms))
 
+/** Bounded UNKNOWN re-query schedule: 7 re-queries, ~30 s of nondecreasing
+ * backoff capped at 6 s steps. Sized after AUT-392 — the prior
+ * two-re-query/2 s budget (`[500, 1500]`) was exhausted by a live occurrence
+ * (build `give-repo-scoped`, PR #352) while GitHub was still computing
+ * mergeability after required checks completed. Single-occurrence evidence,
+ * so this is a deliberate sizing bet, not a measured latency distribution;
+ * the unchanged pendingAutoMerge tick backstop remains behind it for waits a
+ * single tick cannot absorb. */
+export const MERGEABILITY_RETRY_DELAYS_MS = [1000, 2000, 4000, 5000, 6000, 6000, 6000]
+
 /** Hard cap on the janitor poll's per-PR ETag cache. One small entry per PR
  * ever polled in a dispatcher process lifetime makes hitting this in practice
  * implausible; the cap is hygiene, not a load-bearing bound. */
@@ -514,7 +524,8 @@ export class GitHubForge implements Forge {
       env?: Readonly<Record<string, string | undefined>>
       /** Bounded waits between mergeability re-queries when GitHub reports
        * `mergeable_state: 'unknown'` (mergeability still being computed).
-       * Two retries default; tests inject `[0, 0]` so no test sleeps. */
+       * Defaults to `MERGEABILITY_RETRY_DELAYS_MS` (7 re-queries, ~30 s);
+       * tests inject `[0, 0]` or all-zero schedules so no test sleeps. */
       mergeabilityRetryDelaysMs?: number[]
     } = {},
   ) {
@@ -535,7 +546,7 @@ export class GitHubForge implements Forge {
       this.explicitRepository = this.env.AB_REPOSITORY
     }
     this.repoRoot = opts.repoRoot
-    this.mergeabilityRetryDelaysMs = opts.mergeabilityRetryDelaysMs ?? [500, 1500]
+    this.mergeabilityRetryDelaysMs = opts.mergeabilityRetryDelaysMs ?? MERGEABILITY_RETRY_DELAYS_MS
     this.prAttachments = new GitHubPrAttachmentHosting({ transport: this.transport })
   }
 

package/packages/core/src/ports/forge/local-git.ts

@@ -40,9 +40,39 @@ function detail(error: unknown): string {
 export class LocalGitForge implements Forge {
   readonly name = 'local-git'
   private readonly exec: Exec
+  /** The repository the optional checkout-less read seam reads from. The
+   * factory passes the served checkout; without it the capability is absent
+   * and callers retain their checkout/git fallbacks. */
+  private readonly repoRoot?: string
 
-  constructor(opts: { exec?: Exec } = {}) {
+  constructor(opts: { exec?: Exec; repoRoot?: string } = {}) {
     this.exec = opts.exec ?? bunExec
+    this.repoRoot = opts.repoRoot
+  }
+
+  /** Current tip of a local branch in the served repository. Throws when the
+   * branch does not exist — the same not-found contract as remote adapters. */
+  async remoteBranchSha(branch: string): Promise<string> {
+    if (this.repoRoot === undefined) {
+      throw new Error('local-git forge has no repository root for remote branch reads')
+    }
+    const result = await this.command(
+      ['rev-parse', '--verify', `refs/heads/${branch}`],
+      this.repoRoot,
+      true,
+    )
+    if (result.exitCode !== 0) throw new Error(`local-git: unknown remote branch ${branch}`)
+    return result.stdout.trim()
+  }
+
+  /** File bytes from the served repository. Ref omitted → the checkout's HEAD.
+   * Throws when the path does not exist at that ref. */
+  async readFile(path: string, ref?: string): Promise<string> {
+    if (this.repoRoot === undefined) {
+      throw new Error('local-git forge has no repository root for file reads')
+    }
+    const result = await this.command(['show', `${ref ?? 'HEAD'}:${path}`], this.repoRoot)
+    return result.stdout
   }
 
   private async command(args: string[], cwd: string, allowFailure = false) {

package/packages/core/src/ports/runner/claude.ts

@@ -38,7 +38,7 @@ import {
   toolInputPart,
   toolOutputPart,
 } from './stream-parts'
-import { classifyProviderError, configurationFailure } from './provider-error'
+import { classifyProviderError, missingExecutableFailure } from './provider-error'
 import { sessionEnv } from './session-env'
 import type { OneShotCompletion, OneShotCompletionInput, OneShotCompletionResult } from './one-shot'
 import type { RuntimeUsabilityInput, RuntimeUsabilityResult } from './runtime'
@@ -652,7 +652,7 @@ function launchFailure(error: unknown): ClaudeTurn {
   return {
     text: '',
     usage: { inputTokens: 0, outputTokens: 0 },
-    failure: missing ? configurationFailure(message) : classifyProviderError(message),
+    failure: missing ? missingExecutableFailure(message) : classifyProviderError(message),
     cli: {
       stdout: '',
       stderr: errorText(error),

package/packages/core/src/ports/runner/codex.ts

@@ -17,7 +17,11 @@ import {
   type Transcript,
 } from '../types'
 import type { OneShotCompletion, OneShotCompletionInput, OneShotCompletionResult } from './one-shot'
-import { classifyProviderError, configurationFailure, credentialFailure } from './provider-error'
+import {
+  classifyProviderError,
+  credentialFailure,
+  missingExecutableFailure,
+} from './provider-error'
 import {
   abortPart,
   errorPart,
@@ -694,7 +698,7 @@ function launchFailure(error: unknown): CodexTurn {
   return {
     text: '',
     usage: { inputTokens: 0, outputTokens: 0 },
-    failure: missing ? configurationFailure(message) : classifyProviderError(message),
+    failure: missing ? missingExecutableFailure(message) : classifyProviderError(message),
     cli: { stdout: '', stderr: errorText(error), exitCode: -1 },
     events: [],
     malformedLines: [],

package/packages/core/src/ports/runner/fake.ts

@@ -49,12 +49,18 @@ export function failedTurnResult(
   permanent: boolean,
   text = '',
   cause?: AgentFailureCause,
+  missingExecutable?: true,
 ): AgentTurnResult {
   return {
     kind: 'failed',
     text,
     usage: { inputTokens: 0, outputTokens: 0, turns: 1 },
-    failure: { message, permanent, ...(cause !== undefined ? { cause } : {}) },
+    failure: {
+      message,
+      permanent,
+      ...(cause !== undefined ? { cause } : {}),
+      ...(missingExecutable === true ? { missingExecutable } : {}),
+    },
   }
 }
 

package/packages/core/src/ports/runner/pi.ts

@@ -13,7 +13,12 @@ import {
   type Transcript,
 } from '../types'
 import type { OneShotCompletion, OneShotCompletionInput, OneShotCompletionResult } from './one-shot'
-import { classifyProviderError, configurationFailure, credentialFailure } from './provider-error'
+import {
+  classifyProviderError,
+  configurationFailure,
+  credentialFailure,
+  missingExecutableFailure,
+} from './provider-error'
 import { createPiRpcSession, PI_MODEL_ARG, PI_RPC_MODE_ARG } from './pi-rpc'
 import {
   abortPart,
@@ -586,11 +591,8 @@ export class PiAgentRunner implements AgentRunner, OneShotCompletion {
 
 function localPiFailure(error: unknown): AgentTurnFailure {
   const message = errorText(error)
-  if (
-    /executable "pi" was not found|requires Pi .* or newer|could not parse detected Pi version/.test(
-      message,
-    )
-  ) {
+  if (/executable "pi" was not found/.test(message)) return missingExecutableFailure(message)
+  if (/requires Pi .* or newer|could not parse detected Pi version/.test(message)) {
     return configurationFailure(message)
   }
   if (/not ready|authentication|logged in|credentials/i.test(message))

package/packages/core/src/ports/runner/provider-error.ts

@@ -77,9 +77,12 @@ export function classifyProviderError(
 /** Whether another declared target may be tried inside this phase attempt.
  * Legacy plugins have no cause: preserve their old safe split. */
 export function isAlternateEligible(failure: AgentTurnFailure): boolean {
-  return failure.cause === undefined
-    ? !failure.permanent
-    : failure.cause === 'availability' || failure.cause === 'exhaustion'
+  if (failure.cause === undefined) return !failure.permanent
+  return (
+    failure.cause === 'availability' ||
+    failure.cause === 'exhaustion' ||
+    (failure.cause === 'configuration' && failure.missingExecutable === true)
+  )
 }
 
 /** Final-failure retry behavior remains governed by the compatibility bit. */
@@ -92,6 +95,13 @@ export function configurationFailure(message: string): AgentTurnFailure {
   return { message, permanent: true, cause: 'configuration' }
 }
 
+/** The runtime's CLI executable is not installed. Still a permanent
+ * `configuration` failure (never retried), but a later declared target whose
+ * CLI is installed may serve the phase. */
+export function missingExecutableFailure(message: string): AgentTurnFailure {
+  return { message, permanent: true, cause: 'configuration', missingExecutable: true }
+}
+
 /** Explicit credential failures bypass both alternates and phase retries. */
 export function credentialFailure(message: string): AgentTurnFailure {
   return { message, permanent: true, cause: 'credentials' }

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

@@ -79,7 +79,11 @@ export class FakeTicketSource implements TicketSource {
     this.tickets.set(ticket.ref.id, cloneTicket(ticket))
   }
 
-  async listReady(criteria: { labels?: string[]; state?: string }): Promise<TicketListing> {
+  async listReady(criteria: {
+    labels?: string[]
+    state?: string
+    assignee?: string
+  }): Promise<TicketListing> {
     const labels = criteria.labels ?? []
     return {
       tickets: [...this.tickets.values()]

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

@@ -1,6 +1,7 @@
 /**
  * File-based TicketSource (SPEC §3.2, §13): the default tracker. A directory
- * of state directories — `triage/ ready/ doing/ done/` — each holding
+ * of state directories — the lifecycle four `triage/ ready/ doing/ done/`
+ * plus any the repository adds, such as `icebox/` — each holding
  * `<id>.md` files: TOML frontmatter between `+++` fences, then the ticket
  * body, where the spec lives pre-build (§6.3). This adapter is the policy's
  * proof: a source with nowhere to put blobs must be fully workable, because
@@ -19,6 +20,7 @@
  * human edits are explicitly last-write-wins. State renames never cross a
  * filesystem: `<dir>/ready` → `<dir>/doing` is one mount by construction.
  */
+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'
@@ -31,40 +33,64 @@ import type {
   TicketDraft,
   TicketListing,
   TicketSource,
+  TicketStateInfo,
   TicketUpdate,
 } from '../types'
 import { validateTicketUpdate } from './update'
 
+/** Repo-relative fallback when no selected local-state root is supplied. */
+export const DEFAULT_TICKETS_DIR = '.autobuild/tickets'
+
 /**
- * The canonical states, in workflow order. This set is closed: the states are
- * directories, and a tracker whose states are discoverable by `ls` cannot also
- * let config invent new ones.
+ * The directories the dispatcher's roles (create, ready, claim, triage, done)
+ * are played by. Always valid state names, because `ensureLayout` creates them.
  */
-export const TICKET_STATES = ['Triage', 'Ready', 'Doing', 'Done'] as const
-export type TicketState = (typeof TICKET_STATES)[number]
+const LIFECYCLE_DIRS = ['triage', 'ready', 'doing', 'done'] as const
 
-/** Repo-relative fallback when no selected local-state root is supplied. */
-export const DEFAULT_TICKETS_DIR = '.autobuild/tickets'
+/** Dotfile inside a state directory holding its one-line purpose. Dot entries
+ * 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}$/
+
+/** 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]
+}
 
 /**
- * Canonicalize a state name to its directory. Case-insensitive in (a config's
- * `readyState = "ready"` means the `ready/` directory), canonical out — and
- * anything else is a loud error, because a typo'd state must not silently
- * create a fifth directory no `ls` of the four would ever show.
+ * 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.
  */
-export function stateDir(state: string): TicketState {
-  const match = TICKET_STATES.find((s) => s.toLowerCase() === state.toLowerCase())
-  if (match === undefined) {
+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: unknown state "${state}" — this tracker's states are ` +
-        `the directories: ${TICKET_STATES.join(', ')}`,
+      `file ticket source: ambiguous state "${name}" — it matches the directories ${matches.join(', ')}`,
     )
   }
-  return match
-}
-
-function dirName(state: TicketState): string {
-  return state.toLowerCase()
+  throw new Error(
+    `file ticket source: unknown state "${name}" — this tracker's states are ` +
+      `the directories: ${existing.join(', ')}`,
+  )
 }
 
 const frontmatterSchema = z.strictObject({
@@ -138,7 +164,7 @@ function serializeTicketFile(front: Frontmatter, body: string): string {
 /** A ticket file found on disk: its id, its state (= its directory), its path. */
 interface Located {
   id: string
-  state: TicketState
+  state: string
   path: string
 }
 
@@ -147,8 +173,8 @@ export class FileTicketSource implements TicketSource {
 
   private readonly dir: string
   private readonly clock: Clock
-  private readonly createState: TicketState
-  private readonly doneState: TicketState
+  private readonly createState: string
+  private readonly doneState: string
   private readonly selfIgnore: boolean
 
   constructor(opts: {
@@ -174,14 +200,20 @@ export class FileTicketSource implements TicketSource {
   }) {
     this.dir = opts.dir
     this.clock = opts.clock ?? systemClock
-    this.createState = stateDir(opts.createState ?? 'Triage')
-    this.doneState = stateDir(opts.doneState ?? 'Done')
+    const existing = this.statesSync()
+    this.createState = resolveState(opts.createState ?? 'Triage', existing)
+    this.doneState = resolveState(opts.doneState ?? 'Done', existing)
     this.selfIgnore = opts.selfIgnore ?? false
   }
 
-  async listReady(criteria: { labels?: string[]; state?: string }): Promise<TicketListing> {
+  async listReady(criteria: {
+    labels?: string[]
+    state?: string
+    assignee?: string
+  }): Promise<TicketListing> {
     const labels = criteria.labels ?? []
-    const state = criteria.state === undefined ? undefined : stateDir(criteria.state)
+    const state =
+      criteria.state === undefined ? undefined : resolveState(criteria.state, await this.states())
     // Through listAll, not a single readdir: scan completes its layout and
     // duplicate-id checks before any per-record validation is contained. A
     // malformed record can never weaken the invariant preventing a `cp`
@@ -209,8 +241,8 @@ export class FileTicketSource implements TicketSource {
    * the claim record — no `claimedBy` field, which is what makes "claiming
    * visibly removes it from ready/" true.
    *
-   * The guard refuses a ticket already in Doing or in this source's configured
-   * terminal state rather than requiring one in Ready. That inversion is
+   * The guard refuses a ticket already in doing or in this source's configured
+   * terminal state rather than requiring one in ready. That inversion is
    * deliberate: a legal `[tickets] readyState = "Triage"` would otherwise
    * stall forever. Other nonterminal states remain claimable after an explicit
    * handback, while terminal work can never be reopened by claim.
@@ -224,8 +256,8 @@ export class FileTicketSource implements TicketSource {
     // this closes the list→claim window where a human could corrupt a record
     // after it was listed but before the dispatcher claims it.
     await this.loadAt(found)
-    if (found.state === 'Doing' || found.state === this.doneState) return false
-    await rename(found.path, this.pathIn('Doing', id))
+    if (found.state === 'doing' || found.state === this.doneState) return false
+    await rename(found.path, this.pathIn('doing', id))
     return true
   }
 
@@ -250,7 +282,7 @@ export class FileTicketSource implements TicketSource {
   /** A move, never a rewrite — which is why the body survives byte-exactly. */
   async transition(id: string, state: string): Promise<void> {
     await this.ensureLayout()
-    const target = stateDir(state)
+    const target = resolveState(state, await this.states())
     const found = await this.locate(id)
     if (found === null) {
       throw new Error(`file ticket source: transition on unknown ticket "${id}"`)
@@ -270,9 +302,16 @@ export class FileTicketSource implements TicketSource {
    * or adopts the ticket carrying the same idempotency key. */
   async create(draft: TicketDraft, opts: TicketCreateOptions = {}): Promise<Ticket> {
     await this.ensureLayout()
+    // Resolve before anything is read or written: an unknown state touches no file.
+    const targetState =
+      opts.state === undefined ? this.createState : resolveState(opts.state, await this.states())
     const located = await this.scan()
     if (opts.idempotencyKey !== undefined) {
-      const matches: Array<{ found: Located; front: Frontmatter; body: string }> = []
+      const matches: Array<{
+        found: Located
+        front: Frontmatter
+        body: string
+      }> = []
       for (const found of located) {
         const loaded = await this.loadAt(found)
         if (loaded.front.idempotencyKey === opts.idempotencyKey) {
@@ -301,7 +340,6 @@ export class FileTicketSource implements TicketSource {
         : {}),
       ...(opts.idempotencyKey !== undefined ? { idempotencyKey: opts.idempotencyKey } : {}),
     }
-    const targetState = opts.state === undefined ? this.createState : stateDir(opts.state)
     await writeFile(this.pathIn(targetState, front.id), serializeTicketFile(front, draft.body))
     return this.toTicket(front, draft.body, targetState)
   }
@@ -397,22 +435,105 @@ export class FileTicketSource implements TicketSource {
     return states
   }
 
+  /** Every state with its ticket count and purpose. Reads directories only —
+   * never parses a ticket — so a malformed record cannot hide the states. */
+  async listStates(): Promise<TicketStateInfo[]> {
+    const infos: TicketStateInfo[] = []
+    for (const name of await this.states()) infos.push(await this.stateInfo(name))
+    return infos
+  }
+
+  async addState(
+    name: string,
+    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 existing = await this.states()
+    const clash = existing.find((s) => s !== name && s.toLowerCase() === name.toLowerCase())
+    if (clash !== undefined) {
+      throw new Error(
+        `file ticket source: state "${name}" collides with the existing state "${clash}" — ${STATE_NAME_RULE}, ` +
+          'and state names are compared case-insensitively',
+      )
+    }
+    const created = !existing.includes(name)
+    await this.ensureLayout()
+    if (created) await mkdir(join(this.dir, name))
+    if (about !== undefined) await writeFile(join(this.dir, name, ABOUT_FILE), `${about}\n`)
+    return { state: await this.stateInfo(name), created }
+  }
+
+  private async stateInfo(name: string): Promise<TicketStateInfo> {
+    const tickets = (await this.readMarkdown(join(this.dir, name))).length
+    let about: string | undefined
+    try {
+      about = (await readFile(join(this.dir, name, ABOUT_FILE), 'utf8')).trim()
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+    }
+    return { name, tickets, ...(about ? { about } : {}) }
+  }
+
   /**
-   * The four state dirs, plus — for the defaulted backlog only — a
+   * The four lifecycle dirs (never a custom state: `addState` is the
+   * explicit act), plus — for the defaulted backlog only — a
    * self-excluding `.gitignore`. Same move `src/cli/context.ts` makes for
    * `.ab/`: the dir hides itself from git in ANY repo, so the local backlog is
    * never staged, without mutating the repo's own tracked `.gitignore` as an
    * unreviewed side effect. Idempotent; called at the head of every write.
    */
   private async ensureLayout(): Promise<void> {
-    for (const state of TICKET_STATES) {
-      await mkdir(join(this.dir, dirName(state)), { recursive: true })
+    for (const state of LIFECYCLE_DIRS) {
+      await mkdir(join(this.dir, state), { recursive: true })
     }
     if (this.selfIgnore) await writeFile(join(this.dir, '.gitignore'), '*\n')
   }
 
-  private pathIn(state: TicketState, id: string): string {
-    return join(this.dir, dirName(state), `${this.safeId(id)}.md`)
+  /** The state names that exist now. Re-read per operation so a directory
+   * created while a long-running dispatcher is up is seen. */
+  private async states(): Promise<string[]> {
+    try {
+      const entries = await readdir(this.dir, { withFileTypes: true })
+      const directories: string[] = []
+      for (const entry of entries) {
+        if (entry.isDirectory()) directories.push(entry.name)
+        else if (entry.isSymbolicLink()) {
+          const target = await stat(join(this.dir, entry.name)).catch(() => null)
+          if (target?.isDirectory()) directories.push(entry.name)
+        }
+      }
+      return statesIn(directories)
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return statesIn([])
+      throw error
+    }
+  }
+
+  /** Constructor-time twin of `states()`: the only sync IO in this adapter. */
+  private statesSync(): string[] {
+    try {
+      const entries = readdirSync(this.dir, { withFileTypes: true })
+      const directories = entries
+        .filter(
+          (e) =>
+            e.isDirectory() ||
+            (e.isSymbolicLink() &&
+              statSync(join(this.dir, e.name), { throwIfNoEntry: false })?.isDirectory()),
+        )
+        .map((e) => e.name)
+      return statesIn(directories)
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return statesIn([])
+      throw error
+    }
+  }
+
+  private pathIn(state: string, id: string): string {
+    return join(this.dir, state, `${this.safeId(id)}.md`)
   }
 
   private safeId(id: string): string {
@@ -426,7 +547,7 @@ export class FileTicketSource implements TicketSource {
   private async locate(id: string): Promise<Located | null> {
     this.safeId(id)
     const hits: Located[] = []
-    for (const state of TICKET_STATES) {
+    for (const state of await this.states()) {
       const path = this.pathIn(state, id)
       try {
         await stat(path)
@@ -443,14 +564,14 @@ export class FileTicketSource implements TicketSource {
     return hits[0] ?? null
   }
 
-  /** Every ticket file across the four state dirs, sorted, duplicates rejected. */
+  /** Every ticket file across every state dir, sorted, duplicates rejected. */
   private async scan(): Promise<Located[]> {
     await this.assertNoLooseTickets()
     const byId = new Map<string, Located[]>()
-    for (const state of TICKET_STATES) {
-      for (const entry of await this.readMarkdown(join(this.dir, dirName(state)))) {
+    for (const state of await this.states()) {
+      for (const entry of await this.readMarkdown(join(this.dir, state))) {
         const id = entry.slice(0, -'.md'.length)
-        const located = { id, state, path: join(this.dir, dirName(state), entry) }
+        const located = { id, state, path: join(this.dir, state, entry) }
         byId.set(id, [...(byId.get(id) ?? []), located])
       }
     }
@@ -473,7 +594,7 @@ export class FileTicketSource implements TicketSource {
       throw new Error(
         `${join(this.dir, entry)}: ticket file outside a state directory — a ticket's ` +
           `state is the directory it sits in; move it into one of: ` +
-          `${TICKET_STATES.map(dirName).join('/, ')}/`,
+          `${(await this.states()).join('/, ')}/`,
       )
     }
   }
@@ -535,7 +656,7 @@ export class FileTicketSource implements TicketSource {
     return { tickets, diagnostics }
   }
 
-  private toTicket(front: Frontmatter, body: string, state: TicketState): Ticket {
+  private toTicket(front: Frontmatter, body: string, state: string): Ticket {
     return {
       ref: { source: this.name, id: front.id, title: front.title },
       ...(front.idempotencyKey !== undefined ? { creationKey: front.idempotencyKey } : {}),

package/packages/core/src/ports/tickets/{remote-index.ts → hosted-index.ts}

@@ -1,7 +1,8 @@
+// Client half of the hosted ticket source (SPEC §13): the TicketSource a
+// local CLI drives against a hosted deployment. The HTTP server half ships
+// in `@defrex/autobuild-hosted-store-service`.
 export { HostedTicketSource } from './remote'
 export type { HostedTicketFetch, HostedTicketSourceOptions } from './remote'
-export { createTicketServer } from './remote-server'
-export type { TicketServerOptions } from './remote-server'
 export {
   HOSTED_TICKET_OPERATIONS,
   hostedTicketContextSchema,

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

@@ -238,10 +238,42 @@ export class LinearTicketSource implements TicketSource {
     return [...(await this.getTeamInfo('workflow states')).stateIds.keys()]
   }
 
-  async listReady(criteria: { labels?: string[]; state?: string }): Promise<TicketListing> {
+  /** The Linear user a `readyAssignee` value names: `me` is the API key's
+   * owner, anything else is an email. Null when no user matches. */
+  async resolveAssignee(
+    assignee: string,
+  ): Promise<{ id: string; name: string; email: string } | null> {
+    if (assignee === 'me') {
+      const data = await this.gql<{ viewer: { id: string; name: string; email: string } | null }>(
+        'resolveAssignee',
+        'query Viewer { viewer { id name email } }',
+        {},
+      )
+      return data.viewer ?? null
+    }
+    const data = await this.gql<{
+      users: { nodes: { id: string; name: string; email: string }[] }
+    }>(
+      'resolveAssignee',
+      'query UserByEmail($email: String!) { users(filter: { email: { eq: $email } }) { nodes { id name email } } }',
+      { email: assignee },
+    )
+    return data.users.nodes[0] ?? null
+  }
+
+  async listReady(criteria: {
+    labels?: string[]
+    state?: string
+    assignee?: string
+  }): Promise<TicketListing> {
     const filter: Record<string, unknown> = {
       team: { key: { eq: this.teamKey } },
     }
+    if (criteria.assignee !== undefined) {
+      // An unassigned issue matches neither predicate, so it is never ready.
+      filter.assignee =
+        criteria.assignee === 'me' ? { isMe: { eq: true } } : { email: { eq: criteria.assignee } }
+    }
     if (criteria.state !== undefined) {
       filter.state = { name: { eq: criteria.state } }
     }