agent-relay-server 0.61.2 → 0.62.0

package/src/db/issue-lifecycle.ts

@@ -0,0 +1,187 @@
+import { getDb, ValidationError } from "./connection.ts";
+
+export const ISSUE_LIFECYCLE_ACTIONS = ["close", "reopen"] as const;
+export const ISSUE_LIFECYCLE_STATUSES = ["succeeded", "failed"] as const;
+export type IssueLifecycleAction = (typeof ISSUE_LIFECYCLE_ACTIONS)[number];
+export type IssueLifecycleStatus = (typeof ISSUE_LIFECYCLE_STATUSES)[number];
+
+export interface IssueLifecycleActionRecord {
+  id: number;
+  issueRefId: string;
+  action: IssueLifecycleAction;
+  landKey: string;
+  workspaceId?: string;
+  branch?: string;
+  baseRef?: string;
+  commitSha?: string;
+  commitSubject?: string;
+  agentId?: string;
+  source?: string;
+  comment?: string;
+  status: IssueLifecycleStatus;
+  error?: string;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface UpsertIssueLifecycleActionInput {
+  issueRefId: string;
+  action: IssueLifecycleAction;
+  landKey: string;
+  workspaceId?: string;
+  branch?: string;
+  baseRef?: string;
+  commitSha?: string;
+  commitSubject?: string;
+  agentId?: string;
+  source?: string;
+  comment?: string;
+  status: IssueLifecycleStatus;
+  error?: string;
+}
+
+interface IssueLifecycleActionRow {
+  id: number;
+  issue_ref_id: string;
+  action: IssueLifecycleAction;
+  land_key: string;
+  workspace_id: string | null;
+  branch: string | null;
+  base_ref: string | null;
+  commit_sha: string | null;
+  commit_subject: string | null;
+  agent_id: string | null;
+  source: string | null;
+  comment: string | null;
+  status: IssueLifecycleStatus;
+  error: string | null;
+  created_at: number;
+  updated_at: number;
+}
+
+function cleanText(value: string | undefined, field: string, max: number): string | undefined {
+  if (value === undefined) return undefined;
+  const cleaned = value.trim();
+  if (!cleaned) return undefined;
+  if (cleaned.length > max) throw new ValidationError(`${field} must be ${max} characters or fewer`);
+  return cleaned;
+}
+
+function cleanRequiredText(value: string, field: string, max: number): string {
+  const cleaned = cleanText(value, field, max);
+  if (!cleaned) throw new ValidationError(`${field} required`);
+  return cleaned;
+}
+
+function cleanAction(value: IssueLifecycleAction): IssueLifecycleAction {
+  if (!ISSUE_LIFECYCLE_ACTIONS.includes(value)) throw new ValidationError(`action must be one of: ${ISSUE_LIFECYCLE_ACTIONS.join(", ")}`);
+  return value;
+}
+
+function cleanStatus(value: IssueLifecycleStatus): IssueLifecycleStatus {
+  if (!ISSUE_LIFECYCLE_STATUSES.includes(value)) throw new ValidationError(`status must be one of: ${ISSUE_LIFECYCLE_STATUSES.join(", ")}`);
+  return value;
+}
+
+function rowToIssueLifecycleAction(row: IssueLifecycleActionRow): IssueLifecycleActionRecord {
+  return {
+    id: row.id,
+    issueRefId: row.issue_ref_id,
+    action: row.action,
+    landKey: row.land_key,
+    ...(row.workspace_id ? { workspaceId: row.workspace_id } : {}),
+    ...(row.branch ? { branch: row.branch } : {}),
+    ...(row.base_ref ? { baseRef: row.base_ref } : {}),
+    ...(row.commit_sha ? { commitSha: row.commit_sha } : {}),
+    ...(row.commit_subject ? { commitSubject: row.commit_subject } : {}),
+    ...(row.agent_id ? { agentId: row.agent_id } : {}),
+    ...(row.source ? { source: row.source } : {}),
+    ...(row.comment ? { comment: row.comment } : {}),
+    status: row.status,
+    ...(row.error ? { error: row.error } : {}),
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+export function getSuccessfulIssueLifecycleAction(issueRefId: string, action: IssueLifecycleAction, landKey: string): IssueLifecycleActionRecord | null {
+  const row = getDb().query(`
+    SELECT * FROM issue_lifecycle_actions
+    WHERE issue_ref_id = ? AND action = ? AND land_key = ? AND status = 'succeeded'
+  `).get(
+    cleanRequiredText(issueRefId, "issueRefId", 120),
+    cleanAction(action),
+    cleanRequiredText(landKey, "landKey", 240),
+  ) as IssueLifecycleActionRow | undefined;
+  return row ? rowToIssueLifecycleAction(row) : null;
+}
+
+export function listSuccessfulCloseActionsForCommit(input: { commitSha?: string; commitSubject?: string }): IssueLifecycleActionRecord[] {
+  const commitSha = cleanText(input.commitSha, "commitSha", 64);
+  const commitSubject = cleanText(input.commitSubject, "commitSubject", 500);
+  if (!commitSha && !commitSubject) return [];
+  const conditions: string[] = ["action = 'close'", "status = 'succeeded'"];
+  const params: string[] = [];
+  if (commitSha) {
+    conditions.push("commit_sha = ?");
+    params.push(commitSha);
+  }
+  if (commitSubject) {
+    conditions.push("commit_subject = ?");
+    params.push(commitSubject);
+  }
+  const rows = getDb().query(`
+    SELECT * FROM issue_lifecycle_actions
+    WHERE ${conditions.join(" AND ")}
+    ORDER BY updated_at DESC, id DESC
+  `).all(...params) as IssueLifecycleActionRow[];
+  return rows.map(rowToIssueLifecycleAction);
+}
+
+export function upsertIssueLifecycleAction(input: UpsertIssueLifecycleActionInput): IssueLifecycleActionRecord {
+  const now = Date.now();
+  const issueRefId = cleanRequiredText(input.issueRefId, "issueRefId", 120);
+  const action = cleanAction(input.action);
+  const landKey = cleanRequiredText(input.landKey, "landKey", 240);
+  getDb().query(`
+    INSERT INTO issue_lifecycle_actions (
+      issue_ref_id, action, land_key, workspace_id, branch, base_ref, commit_sha, commit_subject,
+      agent_id, source, comment, status, error, created_at, updated_at
+    )
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(issue_ref_id, action, land_key) DO UPDATE SET
+      workspace_id = excluded.workspace_id,
+      branch = excluded.branch,
+      base_ref = excluded.base_ref,
+      commit_sha = excluded.commit_sha,
+      commit_subject = excluded.commit_subject,
+      agent_id = excluded.agent_id,
+      source = excluded.source,
+      comment = excluded.comment,
+      status = excluded.status,
+      error = excluded.error,
+      updated_at = excluded.updated_at
+  `).run(
+    issueRefId,
+    action,
+    landKey,
+    cleanText(input.workspaceId, "workspaceId", 160) ?? null,
+    cleanText(input.branch, "branch", 240) ?? null,
+    cleanText(input.baseRef, "baseRef", 120) ?? null,
+    cleanText(input.commitSha, "commitSha", 64) ?? null,
+    cleanText(input.commitSubject, "commitSubject", 500) ?? null,
+    cleanText(input.agentId, "agentId", 200) ?? null,
+    cleanText(input.source, "source", 120) ?? null,
+    cleanText(input.comment, "comment", 2000) ?? null,
+    cleanStatus(input.status),
+    cleanText(input.error, "error", 2000) ?? null,
+    now,
+    now,
+  );
+  const row = getDb().query(`
+    SELECT * FROM issue_lifecycle_actions
+    WHERE issue_ref_id = ? AND action = ? AND land_key = ?
+  `).get(issueRefId, action, landKey) as IssueLifecycleActionRow | undefined;
+  if (!row) throw new ValidationError("issue lifecycle action could not be recorded");
+  return rowToIssueLifecycleAction(row);
+}

package/src/db/issue-refs.ts

@@ -0,0 +1,254 @@
+import { randomUUID } from "node:crypto";
+import { getDb, ValidationError } from "./connection.ts";
+import { ISSUE_PROVIDERS, ISSUE_REF_STATUSES, type IssueProvider, type IssueRef, type IssueRefStatus } from "../types";
+
+interface IssueRefRow {
+  id: string;
+  provider: IssueProvider;
+  repo: string;
+  external_key: string;
+  url: string;
+  title: string | null;
+  status: IssueRefStatus;
+  status_synced_at: number | null;
+  created_at: number;
+  updated_at: number;
+}
+
+export interface UpsertIssueRefInput {
+  provider: IssueProvider;
+  repo: string;
+  externalKey: string;
+  url: string;
+  title?: string;
+  status?: IssueRefStatus;
+  statusSyncedAt?: number;
+}
+
+export interface ResolveIssueRefByExternalKeyInput {
+  provider: IssueProvider;
+  repo: string;
+  externalKey: string;
+  url?: string;
+  title?: string;
+  status?: IssueRefStatus;
+  statusSyncedAt?: number;
+}
+
+export interface ResolveIssueRefFromStringInput {
+  ref: string;
+  defaultRepo?: string;
+  provider?: IssueProvider;
+  title?: string;
+  status?: IssueRefStatus;
+  statusSyncedAt?: number;
+}
+
+export interface ListIssueRefsOptions {
+  provider?: IssueProvider;
+  repo?: string;
+  status?: IssueRefStatus;
+  limit?: number;
+}
+
+export interface UpdateIssueRefInput {
+  url?: string;
+  title?: string;
+  status?: IssueRefStatus;
+  statusSyncedAt?: number;
+}
+
+export function issueRefId(): string {
+  return `issue_${randomUUID()}`;
+}
+
+function rowToIssueRef(row: IssueRefRow): IssueRef {
+  return {
+    id: row.id,
+    provider: row.provider,
+    repo: row.repo,
+    externalKey: row.external_key,
+    url: row.url,
+    ...(row.title ? { title: row.title } : {}),
+    status: row.status,
+    ...(row.status_synced_at !== null ? { statusSyncedAt: row.status_synced_at } : {}),
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function cleanProvider(value: IssueProvider): IssueProvider {
+  if (!ISSUE_PROVIDERS.includes(value)) {
+    throw new ValidationError(`provider must be one of: ${ISSUE_PROVIDERS.join(", ")}`);
+  }
+  return value;
+}
+
+function cleanStatus(value: IssueRefStatus | undefined): IssueRefStatus {
+  if (value === undefined) return "unknown";
+  if (!ISSUE_REF_STATUSES.includes(value)) {
+    throw new ValidationError(`status must be one of: ${ISSUE_REF_STATUSES.join(", ")}`);
+  }
+  return value;
+}
+
+function requiredText(value: string | undefined, field: string, max: number): string {
+  if (typeof value !== "string") throw new ValidationError(`${field} required`);
+  const cleaned = value.trim();
+  if (!cleaned) throw new ValidationError(`${field} required`);
+  if (cleaned.length > max) throw new ValidationError(`${field} must be ${max} characters or fewer`);
+  return cleaned;
+}
+
+function optionalText(value: string | undefined, field: string, max: number): string | undefined {
+  if (value === undefined) return undefined;
+  const cleaned = requiredText(value, field, max);
+  return cleaned || undefined;
+}
+
+function cleanSyncedAt(value: number | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  if (!Number.isSafeInteger(value) || value < 0) throw new ValidationError("statusSyncedAt must be a non-negative integer");
+  return value;
+}
+
+function githubIssueUrl(repo: string, externalKey: string): string {
+  return `https://github.com/${repo}/issues/${externalKey}`;
+}
+
+function resolveUrl(provider: IssueProvider, repo: string, externalKey: string, url: string | undefined): string {
+  const cleaned = optionalText(url, "url", 2000);
+  if (cleaned) return cleaned;
+  if (provider === "github") return githubIssueUrl(repo, externalKey);
+  throw new ValidationError("url required for non-github issue refs");
+}
+
+export function getIssueRef(id: string): IssueRef | null {
+  const row = getDb().query("SELECT * FROM issue_refs WHERE id = ?").get(id) as IssueRefRow | undefined;
+  return row ? rowToIssueRef(row) : null;
+}
+
+export function getIssueRefByExternalKey(provider: IssueProvider, repo: string, externalKey: string): IssueRef | null {
+  const row = getDb().query("SELECT * FROM issue_refs WHERE provider = ? AND repo = ? AND external_key = ?")
+    .get(cleanProvider(provider), requiredText(repo, "repo", 500), requiredText(externalKey, "externalKey", 240)) as IssueRefRow | undefined;
+  return row ? rowToIssueRef(row) : null;
+}
+
+export function upsertIssueRef(input: UpsertIssueRefInput): IssueRef {
+  const provider = cleanProvider(input.provider);
+  const repo = requiredText(input.repo, "repo", 500);
+  const externalKey = requiredText(input.externalKey, "externalKey", 240);
+  const url = resolveUrl(provider, repo, externalKey, input.url);
+  const existing = getIssueRefByExternalKey(provider, repo, externalKey);
+  const title = optionalText(input.title, "title", 500);
+  const status = input.status === undefined && existing ? existing.status : cleanStatus(input.status);
+  const statusSyncedAt = cleanSyncedAt(input.statusSyncedAt);
+  const now = Date.now();
+  if (existing) {
+    getDb().query(`
+      UPDATE issue_refs
+      SET url = ?, title = ?, status = ?, status_synced_at = ?, updated_at = ?
+      WHERE id = ?
+    `).run(url, title ?? existing.title ?? null, status, statusSyncedAt ?? existing.statusSyncedAt ?? null, now, existing.id);
+    return getIssueRef(existing.id)!;
+  }
+  const id = issueRefId();
+  getDb().query(`
+    INSERT INTO issue_refs (id, provider, repo, external_key, url, title, status, status_synced_at, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(id, provider, repo, externalKey, url, title ?? null, status, statusSyncedAt ?? null, now, now);
+  return getIssueRef(id)!;
+}
+
+export function resolveIssueRefByExternalKey(input: ResolveIssueRefByExternalKeyInput): IssueRef {
+  const provider = cleanProvider(input.provider);
+  const repo = requiredText(input.repo, "repo", 500);
+  const externalKey = requiredText(input.externalKey, "externalKey", 240);
+  const existing = getIssueRefByExternalKey(provider, repo, externalKey);
+  if (existing && input.url === undefined && input.title === undefined && input.status === undefined && input.statusSyncedAt === undefined) {
+    return existing;
+  }
+  return upsertIssueRef({
+    provider,
+    repo,
+    externalKey,
+    url: input.url ?? existing?.url ?? resolveUrl(provider, repo, externalKey, undefined),
+    title: input.title ?? existing?.title,
+    status: input.status ?? existing?.status,
+    statusSyncedAt: input.statusSyncedAt ?? existing?.statusSyncedAt,
+  });
+}
+
+export function resolveIssueRefFromString(input: ResolveIssueRefFromStringInput): IssueRef {
+  const ref = requiredText(input.ref, "ref", 1000);
+  if (ref.startsWith("issue_")) {
+    const existing = getIssueRef(ref);
+    if (!existing) throw new ValidationError(`issue ref ${ref} not found`);
+    return existing;
+  }
+  const provider = cleanProvider(input.provider ?? "github");
+  if (provider !== "github") throw new ValidationError("string issue refs are only supported for github in this foundation resolver");
+  const urlMatch = ref.match(/^https:\/\/github\.com\/([^/]+)\/([^/]+)\/issues\/([0-9]+)(?:[/?#].*)?$/);
+  const ownerRepoMatch = ref.match(/^([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)#([0-9]+)$/);
+  const bareMatch = ref.match(/^#([0-9]+)$/);
+  const repo = urlMatch ? `${urlMatch[1]}/${urlMatch[2]}` : ownerRepoMatch ? ownerRepoMatch[1] : bareMatch ? input.defaultRepo : undefined;
+  const externalKey = urlMatch ? urlMatch[3] : ownerRepoMatch ? ownerRepoMatch[2] : bareMatch ? bareMatch[1] : undefined;
+  if (!repo || !externalKey) throw new ValidationError("ref must be issue_<id>, #number, owner/repo#number, or a GitHub issue URL");
+  return resolveIssueRefByExternalKey({
+    provider,
+    repo: requiredText(repo, "repo", 500),
+    externalKey,
+    url: githubIssueUrl(repo, externalKey),
+    title: input.title,
+    status: input.status,
+    statusSyncedAt: input.statusSyncedAt,
+  });
+}
+
+export function listIssueRefs(opts: ListIssueRefsOptions = {}): IssueRef[] {
+  const conditions: string[] = [];
+  const params: Array<string | number> = [];
+  if (opts.provider) {
+    conditions.push("provider = ?");
+    params.push(cleanProvider(opts.provider));
+  }
+  if (opts.repo) {
+    conditions.push("repo = ?");
+    params.push(requiredText(opts.repo, "repo", 500));
+  }
+  if (opts.status) {
+    conditions.push("status = ?");
+    params.push(cleanStatus(opts.status));
+  }
+  const limit = opts.limit ?? 100;
+  if (!Number.isSafeInteger(limit) || limit <= 0 || limit > 500) throw new ValidationError("limit must be between 1 and 500");
+  params.push(limit);
+  const where = conditions.length ? `WHERE ${conditions.join(" AND ")}` : "";
+  const rows = getDb().query(`
+    SELECT * FROM issue_refs
+    ${where}
+    ORDER BY updated_at DESC, created_at DESC, id DESC
+    LIMIT ?
+  `).all(...params) as IssueRefRow[];
+  return rows.map(rowToIssueRef);
+}
+
+export function updateIssueRef(id: string, input: UpdateIssueRefInput): IssueRef | null {
+  const existing = getIssueRef(requiredText(id, "id", 120));
+  if (!existing) return null;
+  const url = optionalText(input.url, "url", 2000) ?? existing.url;
+  const title = input.title === undefined ? existing.title : optionalText(input.title, "title", 500);
+  const status = input.status === undefined ? existing.status : cleanStatus(input.status);
+  const statusSyncedAt = input.statusSyncedAt === undefined ? existing.statusSyncedAt : cleanSyncedAt(input.statusSyncedAt);
+  getDb().query(`
+    UPDATE issue_refs
+    SET url = ?, title = ?, status = ?, status_synced_at = ?, updated_at = ?
+    WHERE id = ?
+  `).run(url, title ?? null, status, statusSyncedAt ?? null, Date.now(), existing.id);
+  return getIssueRef(existing.id);
+}
+
+export function deleteIssueRef(id: string): boolean {
+  const result = getDb().query("DELETE FROM issue_refs WHERE id = ?").run(requiredText(id, "id", 120));
+  return result.changes > 0;
+}

package/src/db/mappers.ts

@@ -377,6 +377,8 @@ export function rowToActivityEvent(row: any): ActivityEvent {
     pairId: row.pair_id ?? undefined,
     taskId: row.task_id ?? undefined,
     agentId: row.agent_id ?? undefined,
+    issueRefId: row.issue_ref_id ?? undefined,
+    issueAction: row.issue_action ?? undefined,
     metadata: parseJson(row.metadata, {}),
     createdAt: row.created_at,
   };

package/src/db/migrations.ts

@@ -117,6 +117,53 @@ export function applyMigrations(): void {
   normalizeExistingMessageReactions();
 
   // Migrations
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS issue_refs (
+      id TEXT PRIMARY KEY,
+      provider TEXT NOT NULL,
+      repo TEXT NOT NULL,
+      external_key TEXT NOT NULL,
+      url TEXT NOT NULL,
+      title TEXT,
+      status TEXT NOT NULL DEFAULT 'unknown',
+      status_synced_at INTEGER,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      UNIQUE(provider, repo, external_key)
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_issue_refs_external ON issue_refs(provider, repo, external_key)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_issue_refs_updated ON issue_refs(updated_at DESC)");
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS issue_associations (
+      issue_ref_id TEXT NOT NULL REFERENCES issue_refs(id) ON DELETE CASCADE,
+      entity_type TEXT NOT NULL CHECK (entity_type IN ('team', 'plan-node', 'epic')),
+      entity_id TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      PRIMARY KEY (issue_ref_id, entity_type, entity_id)
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_issue_associations_entity ON issue_associations(entity_type, entity_id, created_at DESC)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_issue_associations_issue ON issue_associations(issue_ref_id, created_at DESC)");
+  getDb().run(`CREATE TABLE IF NOT EXISTS issue_lifecycle_actions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT, issue_ref_id TEXT NOT NULL REFERENCES issue_refs(id) ON DELETE CASCADE,
+    action TEXT NOT NULL CHECK (action IN ('close', 'reopen')), land_key TEXT NOT NULL, workspace_id TEXT, branch TEXT, base_ref TEXT, commit_sha TEXT, commit_subject TEXT,
+    agent_id TEXT, source TEXT, comment TEXT, status TEXT NOT NULL CHECK (status IN ('succeeded', 'failed')),
+    error TEXT, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL, UNIQUE(issue_ref_id, action, land_key))`);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_issue_lifecycle_commit ON issue_lifecycle_actions(commit_sha, action, status)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_issue_lifecycle_subject ON issue_lifecycle_actions(commit_subject, action, status)");
+
+  const activityCols = getDb().query("PRAGMA table_info(activity_events)").all() as any[];
+  const activityColNames = activityCols.map((c: any) => c.name);
+  if (!activityColNames.includes("issue_ref_id")) {
+    getDb().run("ALTER TABLE activity_events ADD COLUMN issue_ref_id TEXT");
+  }
+  if (!activityColNames.includes("issue_action")) {
+    getDb().run("ALTER TABLE activity_events ADD COLUMN issue_action TEXT");
+  }
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_activity_issue ON activity_events(issue_ref_id, created_at)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_activity_agent_issue ON activity_events(agent_id, issue_ref_id, created_at)");
+
   getDb().run(`
     CREATE TABLE IF NOT EXISTS workspace_merge_pauses (
       id TEXT PRIMARY KEY,

package/src/db/schema.ts

@@ -671,13 +671,13 @@ export function initDb(path: string = "agent-relay.db"): Database {
       message_id INTEGER,
       pair_id TEXT,
       task_id INTEGER,
-      agent_id TEXT,
+      agent_id TEXT, issue_ref_id TEXT, issue_action TEXT,
       metadata TEXT NOT NULL DEFAULT '{}',
       created_at INTEGER NOT NULL
     );
     CREATE INDEX IF NOT EXISTS idx_activity_operator ON activity_events(operator_id, created_at);
     CREATE INDEX IF NOT EXISTS idx_activity_created ON activity_events(created_at);
-    CREATE INDEX IF NOT EXISTS idx_activity_agent ON activity_events(agent_id, created_at);
+    CREATE INDEX IF NOT EXISTS idx_activity_agent ON activity_events(agent_id, created_at); CREATE INDEX IF NOT EXISTS idx_activity_issue ON activity_events(issue_ref_id, created_at); CREATE INDEX IF NOT EXISTS idx_activity_agent_issue ON activity_events(agent_id, issue_ref_id, created_at);
 
     CREATE TABLE IF NOT EXISTS channels (
       id TEXT PRIMARY KEY,

package/src/issue-tracker/adapter.ts

@@ -0,0 +1,24 @@
+import type { IssueRef, IssueRefStatus } from "../types";
+
+export interface IssueTrackerStatus {
+  status: IssueRefStatus;
+  title: string;
+}
+
+export interface IssueTrackerCloseOptions {
+  comment?: string;
+  labels?: string[];
+}
+
+export interface IssueTrackerReopenOptions {
+  comment?: string;
+}
+
+export interface IssueTrackerAdapter {
+  resolveLink(ref: IssueRef): string;
+  getStatus(ref: IssueRef): Promise<IssueTrackerStatus>;
+  close(ref: IssueRef, options?: IssueTrackerCloseOptions): Promise<void>;
+  reopen(ref: IssueRef, options?: IssueTrackerReopenOptions): Promise<void>;
+  comment(ref: IssueRef, body: string): Promise<void>;
+  applyLabels(ref: IssueRef, labels: string[]): Promise<void>;
+}

package/src/issue-tracker/github.ts

@@ -0,0 +1,136 @@
+import type { IssueRef, IssueRefStatus } from "../types";
+import type { IssueTrackerAdapter, IssueTrackerCloseOptions, IssueTrackerReopenOptions, IssueTrackerStatus } from "./adapter";
+
+export const GITHUB_FIXED_LABEL = "fixed";
+export const GITHUB_CREDENTIAL_REQUIREMENT = "GitHub issue tracker adapter requires gh authenticated with a token that has issues:write scope";
+
+type GitHubApiMethod = "GET" | "PATCH" | "POST";
+
+export interface GitHubApiRequest {
+  method: GitHubApiMethod;
+  path: string;
+  body?: Record<string, unknown>;
+}
+
+export type GitHubApi = (request: GitHubApiRequest) => Promise<unknown>;
+
+interface GitHubIssuePayload {
+  state?: unknown;
+  title?: unknown;
+  html_url?: unknown;
+}
+
+function textFromBytes(value: unknown): string {
+  if (!value) return "";
+  if (typeof value === "string") return value;
+  if (value instanceof Uint8Array) return Buffer.from(value).toString("utf8");
+  return String(value);
+}
+
+async function ghApi(request: GitHubApiRequest): Promise<unknown> {
+  // Deploy gate for #474: the host running lifecycle automation must provide gh
+  // auth backed by a GitHub token with `issues:write` scope.
+  const args = ["gh", "api", "--method", request.method, request.path, "--header", "Accept: application/vnd.github+json"];
+  appendBodyArgs(args, request.body);
+  const proc = Bun.spawnSync(args, {
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+    env: process.env,
+  });
+  const stdout = textFromBytes(proc.stdout).trim();
+  if (proc.exitCode !== 0) {
+    const stderr = textFromBytes(proc.stderr).trim();
+    throw new Error(`${GITHUB_CREDENTIAL_REQUIREMENT}; gh api failed: ${stderr || stdout || `exit ${proc.exitCode}`}`);
+  }
+  if (!stdout) return {};
+  try {
+    return JSON.parse(stdout);
+  } catch {
+    return {};
+  }
+}
+
+function appendBodyArgs(args: string[], body: Record<string, unknown> | undefined): void {
+  if (!body) return;
+  for (const [key, value] of Object.entries(body)) {
+    if (value === undefined || value === null) continue;
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (item === undefined || item === null) continue;
+        args.push("--raw-field", `${key}[]=${String(item)}`);
+      }
+      continue;
+    }
+    args.push(typeof value === "string" ? "--raw-field" : "--field", `${key}=${String(value)}`);
+  }
+}
+
+function githubIssuePath(ref: IssueRef): string {
+  assertGitHubIssueRef(ref);
+  return `/repos/${ref.repo}/issues/${ref.externalKey}`;
+}
+
+function assertGitHubIssueRef(ref: IssueRef): void {
+  if (ref.provider !== "github") throw new Error(`GitHub adapter cannot handle ${ref.provider} issue refs`);
+  if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(ref.repo)) throw new Error("GitHub issue ref repo must be owner/repo");
+  if (!/^[0-9]+$/.test(ref.externalKey)) throw new Error("GitHub issue ref externalKey must be an issue number");
+}
+
+function statusFromState(state: unknown): IssueRefStatus {
+  if (state === "open" || state === "closed") return state;
+  return "unknown";
+}
+
+function titleFromIssue(value: unknown): string {
+  const titleValue = value && typeof value === "object" ? (value as GitHubIssuePayload).title : undefined;
+  const title = typeof titleValue === "string" ? titleValue.trim() : "";
+  return title || "Untitled issue";
+}
+
+function uniqueLabels(labels: string[]): string[] {
+  return [...new Set(labels.map((label) => label.trim()).filter(Boolean))];
+}
+
+export class GitHubIssueTrackerAdapter implements IssueTrackerAdapter {
+  constructor(private readonly api: GitHubApi = ghApi) {}
+
+  resolveLink(ref: IssueRef): string {
+    assertGitHubIssueRef(ref);
+    return ref.url || `https://github.com/${ref.repo}/issues/${ref.externalKey}`;
+  }
+
+  async getStatus(ref: IssueRef): Promise<IssueTrackerStatus> {
+    const issue = await this.api({ method: "GET", path: githubIssuePath(ref) }) as GitHubIssuePayload;
+    return { status: statusFromState(issue.state), title: titleFromIssue(issue) };
+  }
+
+  async close(ref: IssueRef, options: IssueTrackerCloseOptions = {}): Promise<void> {
+    await this.api({ method: "PATCH", path: githubIssuePath(ref), body: { state: "closed" } });
+    await this.applyLabels(ref, [GITHUB_FIXED_LABEL, ...(options.labels ?? [])]);
+    if (options.comment) await this.comment(ref, options.comment);
+  }
+
+  async reopen(ref: IssueRef, options: IssueTrackerReopenOptions = {}): Promise<void> {
+    await this.api({ method: "PATCH", path: githubIssuePath(ref), body: { state: "open" } });
+    if (options.comment) await this.comment(ref, options.comment);
+  }
+
+  async comment(ref: IssueRef, body: string): Promise<void> {
+    const trimmed = body.trim();
+    if (!trimmed) throw new Error("GitHub issue comment body required");
+    await this.api({ method: "POST", path: `${githubIssuePath(ref)}/comments`, body: { body: trimmed } });
+  }
+
+  async applyLabels(ref: IssueRef, labels: string[]): Promise<void> {
+    const cleaned = uniqueLabels(labels);
+    if (cleaned.length === 0) return;
+    await this.api({ method: "POST", path: `${githubIssuePath(ref)}/labels`, body: { labels: cleaned } });
+  }
+}
+
+export function createGitHubIssueTrackerAdapter(api?: GitHubApi): IssueTrackerAdapter {
+  return new GitHubIssueTrackerAdapter(api);
+}
+
+export const githubIssueTrackerAdapter = createGitHubIssueTrackerAdapter();