agent-relay-server 0.61.1 → 0.62.0

package/src/routes/issue-refs.ts

@@ -0,0 +1,137 @@
+import { deleteIssueRefMapping, getIssueRef, listIssueRefs, patchIssueRefMapping, resolveIssueRefMapping, upsertIssueRefMapping, type ListIssueRefsOptions } from "../services/issue-refs";
+import { cleanEnum, cleanString, optionalEnum } from "../validation";
+import { error, json, parseBody, parseQueryInt, type Handler } from "./_shared";
+import { ISSUE_PROVIDERS, ISSUE_REF_STATUSES, isRecord, type IssueProvider, type IssueRefStatus } from "../types";
+
+function cleanStatus(value: unknown): IssueRefStatus | undefined {
+  return optionalEnum(value, "status", ISSUE_REF_STATUSES) as IssueRefStatus | undefined;
+}
+
+function cleanProvider(value: unknown): IssueProvider {
+  return cleanEnum(value, "provider", ISSUE_PROVIDERS) as IssueProvider;
+}
+
+function cleanTimestamp(value: unknown): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new Error("statusSyncedAt must be a non-negative integer");
+  return value;
+}
+
+function cleanUpsertBody(body: unknown) {
+  if (!isRecord(body)) throw new Error("issue ref body required");
+  return {
+    provider: cleanProvider(body.provider),
+    repo: cleanString(body.repo, "repo", { required: true, max: 500 })!,
+    externalKey: cleanString(body.externalKey, "externalKey", { required: true, max: 240 })!,
+    url: cleanString(body.url, "url", { required: true, max: 2000 })!,
+    title: cleanString(body.title, "title", { max: 500 }),
+    status: cleanStatus(body.status),
+    statusSyncedAt: cleanTimestamp(body.statusSyncedAt),
+  };
+}
+
+function cleanPatchBody(body: unknown) {
+  if (!isRecord(body)) throw new Error("issue ref patch body required");
+  return {
+    url: cleanString(body.url, "url", { max: 2000 }),
+    title: cleanString(body.title, "title", { max: 500 }),
+    status: cleanStatus(body.status),
+    statusSyncedAt: cleanTimestamp(body.statusSyncedAt),
+  };
+}
+
+function cleanResolveBody(body: unknown) {
+  if (!isRecord(body)) throw new Error("issue ref resolve body required");
+  return body;
+}
+
+export const listIssueRefsRoute: Handler = (req) => {
+  try {
+    const url = new URL(req.url);
+    const rawLimit = parseQueryInt(url.searchParams.get("limit"), { min: 1, max: 500, clamp: true });
+    if (Number.isNaN(rawLimit)) return error("limit must be an integer");
+    const opts: ListIssueRefsOptions = {
+      provider: optionalEnum(url.searchParams.get("provider") ?? undefined, "provider", ISSUE_PROVIDERS) as IssueProvider | undefined,
+      repo: cleanString(url.searchParams.get("repo") ?? undefined, "repo", { max: 500 }),
+      status: optionalEnum(url.searchParams.get("status") ?? undefined, "status", ISSUE_REF_STATUSES) as IssueRefStatus | undefined,
+      limit: rawLimit ?? undefined,
+    };
+    return json({ issueRefs: listIssueRefs(opts) });
+  } catch (err) {
+    return error(err instanceof Error ? err.message : "issue refs route failed");
+  }
+};
+
+export const postIssueRefRoute: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    return json({ issueRef: upsertIssueRefMapping(cleanUpsertBody(parsed.body)) });
+  } catch (err) {
+    return error(err instanceof Error ? err.message : "issue refs route failed");
+  }
+};
+
+export const resolveIssueRefRoute: Handler = async (req) => {
+  const url = new URL(req.url);
+  const body = req.method === "POST" ? await parseBody<unknown>(req) : null;
+  if (body && !body.ok) return error(body.error, body.status);
+  try {
+    const value = body ? cleanResolveBody(body.body) : Object.fromEntries(url.searchParams.entries());
+    const ref = cleanString(value.ref, "ref", { max: 1000 });
+    const issueRef = ref
+      ? resolveIssueRefMapping({
+        ref,
+        defaultRepo: cleanString(value.defaultRepo ?? value.repo, "defaultRepo", { max: 500 }),
+        provider: optionalEnum(value.provider, "provider", ISSUE_PROVIDERS, "github") as IssueProvider,
+        title: cleanString(value.title, "title", { max: 500 }),
+        status: cleanStatus(value.status),
+        statusSyncedAt: cleanTimestamp(value.statusSyncedAt),
+      })
+      : resolveIssueRefMapping({
+        provider: cleanProvider(value.provider),
+        repo: cleanString(value.repo, "repo", { required: true, max: 500 })!,
+        externalKey: cleanString(value.externalKey, "externalKey", { required: true, max: 240 })!,
+        url: cleanString(value.url, "url", { max: 2000 }),
+        title: cleanString(value.title, "title", { max: 500 }),
+        status: cleanStatus(value.status),
+        statusSyncedAt: cleanTimestamp(value.statusSyncedAt),
+      });
+    return json({ issueRef });
+  } catch (err) {
+    return error(err instanceof Error ? err.message : "issue refs route failed");
+  }
+};
+
+export const getIssueRefRoute: Handler = (_req, params) => {
+  try {
+    const id = cleanString(params.id, "id", { required: true, max: 120 })!;
+    const issueRef = getIssueRef(id);
+    if (!issueRef) return error("issue ref not found", 404);
+    return json({ issueRef });
+  } catch (err) {
+    return error(err instanceof Error ? err.message : "issue refs route failed");
+  }
+};
+
+export const patchIssueRefRoute: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const issueRef = patchIssueRefMapping(cleanString(params.id, "id", { required: true, max: 120 })!, cleanPatchBody(parsed.body));
+    if (!issueRef) return error("issue ref not found", 404);
+    return json({ issueRef });
+  } catch (err) {
+    return error(err instanceof Error ? err.message : "issue refs route failed");
+  }
+};
+
+export const deleteIssueRefRoute: Handler = (_req, params) => {
+  try {
+    const deleted = deleteIssueRefMapping(cleanString(params.id, "id", { required: true, max: 120 })!);
+    if (!deleted) return error("issue ref not found", 404);
+    return json({ deleted });
+  } catch (err) {
+    return error(err instanceof Error ? err.message : "issue refs route failed");
+  }
+};

package/src/routes/orchestrator.ts

@@ -364,6 +364,26 @@ function orchestratorSelfUpgradeError(orch: ReturnType<typeof getOrchestrator>):
   return undefined;
 }
 
+// One-time, server-authority migration of host-local provider config files into the
+// central provider-config rows (#465). The orchestrator reports its files via the
+// command result; the server seeds the rows (see patchCommand). Capability-gated so
+// pre-#465 orchestrators that lack the handler never get a command they'd reject.
+function dispatchProviderConfigMigration(
+  orch: NonNullable<ReturnType<typeof getOrchestrator>>,
+  requestedBy = "system",
+): ReturnType<typeof createCommand> | null {
+  if (!orch.capabilities?.migrateProviderConfig) return null;
+  const command = createCommand({
+    type: "orchestrator.migrate-provider-config",
+    source: "system",
+    target: orch.agentId,
+    ttlMs: 10 * 60_000,
+    params: { orchestratorId: orch.id, requestedBy },
+  });
+  emitCommand(command);
+  return command;
+}
+
 function reconcileOrchestratorUpgrade(orch: ReturnType<typeof getOrchestrator>): void {
   if (!orch) return;
   const up = orch.upgrade;
@@ -389,6 +409,9 @@ function reconcileOrchestratorUpgrade(orch: ReturnType<typeof getOrchestrator>):
       view: "orchestrators",
       metadata: { orchestratorId: orch.id, version: reported, commandId: up.commandId },
     });
+    // Upgrade settled — the orchestrator is now running new-enough code to handle
+    // the provider-config migration, so seed the central rows from its local files (#465).
+    dispatchProviderConfigMigration(orch);
     emitOrchestratorStatus(orch.id);
   } else if (up.status === "pending" && Date.now() - up.requestedAt > ORCH_UPGRADE_DEADLINE_MS) {
     const errMsg = `upgrade timed out; orchestrator still reports ${reported ?? "unknown"} (wanted ${up.desiredVersion})`;
@@ -416,9 +439,27 @@ export const postOrchestratorAction: Handler = async (req, params) => {
     if (!orch) return error("orchestrator not found", 404);
 
     if (!isRecord(parsed.body)) return error("body required");
-    const action = optionalEnum(parsed.body.action, "action", ["restart", "shutdown", "upgrade"] as const);
+    const action = optionalEnum(parsed.body.action, "action", ["restart", "shutdown", "upgrade", "migrate-provider-config"] as const);
     if (!action) return error("action required");
 
+    if (action === "migrate-provider-config") {
+      const denied = authorizeRoute(req, { scope: "command:write", resource: { orchestratorId: orch.id } });
+      if (denied) return denied;
+      const command = dispatchProviderConfigMigration(orch, "dashboard");
+      if (!command) return error(`orchestrator ${orch.id} does not support provider-config migration; upgrade it first`, 409);
+      auditEvent({
+        clientId: `server-orchestrator-migrate-provider-config-${orch.id}-${command.id}`,
+        kind: "state",
+        title: "Provider config migration requested",
+        body: orch.id,
+        meta: orch.id,
+        icon: "ti-arrow-up-circle",
+        view: "orchestrators",
+        metadata: { orchestratorId: orch.id, commandId: command.id, ...authAuditMetadata(req), ...dashboardAttribution(req, parsed.body.surface) },
+      });
+      return json({ ok: true, action, command }, 202);
+    }
+
     if (action === "upgrade") {
       const denied = authorizeRoute(req, { scope: "command:write", resource: { orchestratorId: orch.id } });
       if (denied) return denied;

package/src/security.ts

@@ -188,6 +188,10 @@ export function requiredScopeFor(method: string, pathname: string): string | nul
   if (pathname.startsWith("/api/pairs")) return method === "GET" ? "pairs:read" : "pairs:write";
   if (pathname.startsWith("/api/teams")) return method === "GET" ? "teams:read" : "teams:write";
   if (pathname.startsWith("/api/blackboard")) return method === "GET" ? "blackboard:read" : "blackboard:write";
+  if (pathname.startsWith("/api/issue-associations")) return method === "GET" ? "issue:read" : "issue:write";
+  if (pathname.startsWith("/api/issue-activity")) return method === "GET" ? "issue:read" : "issue:write";
+  if (pathname.startsWith("/api/issue-lifecycle")) return method === "GET" ? "issue:read" : "issue:write";
+  if (pathname.startsWith("/api/issue-refs")) return method === "GET" ? "issue:read" : "issue:write";
   if (pathname.startsWith("/api/projects")) return method === "GET" ? "project:read" : "project:write";
   // Insights config (the feature toggle) stays admin-only via the default; only the
   // mechanical observation feed is writable by lower-privilege callers.
@@ -269,6 +273,10 @@ export function requiredComponentScopeFor(method: string, pathname: string): str
   if (pathname.startsWith("/api/plans")) return method === "GET" ? "plans:read" : "plans:write";
   if (pathname.startsWith("/api/teams")) return method === "GET" ? "teams:read" : "teams:write";
   if (pathname.startsWith("/api/blackboard")) return method === "GET" ? "blackboard:read" : "blackboard:write";
+  if (pathname.startsWith("/api/issue-associations")) return method === "GET" ? "issue:read" : "issue:write";
+  if (pathname.startsWith("/api/issue-activity")) return method === "GET" ? "issue:read" : "issue:write";
+  if (pathname.startsWith("/api/issue-lifecycle")) return method === "GET" ? "issue:read" : "issue:write";
+  if (pathname.startsWith("/api/issue-refs")) return method === "GET" ? "issue:read" : "issue:write";
   // Fail-closed default returns system:admin, so this case is load-bearing: without it
   // every /api/projects call from a scoped component token would 403-blackhole (#405).
   if (pathname.startsWith("/api/projects")) return method === "GET" ? "project:read" : "project:write";

package/src/services/issue-activity.ts

@@ -0,0 +1,30 @@
+import {
+  ISSUE_ACTIVITY_ACTIONS,
+  listAgentIssueActivity,
+  listIssueActivityAgents,
+  recordIssueActivity,
+  resolveIssueActivityRef,
+  type IssueActivityAction,
+  type RecordIssueActivityInput,
+} from "../db/activity";
+import { emitActivityEvent } from "../sse";
+import type { IssueProvider } from "../types";
+
+export {
+  ISSUE_ACTIVITY_ACTIONS,
+  listAgentIssueActivity,
+  listIssueActivityAgents,
+  recordIssueActivity,
+  type IssueActivityAction,
+  type RecordIssueActivityInput,
+};
+
+export function recordAndEmitIssueActivity(input: RecordIssueActivityInput) {
+  const event = recordIssueActivity(input);
+  emitActivityEvent(event);
+  return event;
+}
+
+export function resolveIssueActivityMapping(input: { issueRefId?: string; issueRef?: string; defaultRepo?: string; provider?: IssueProvider }) {
+  return resolveIssueActivityRef(input);
+}

package/src/services/issue-associations.ts

@@ -0,0 +1,72 @@
+import {
+  associateIssue,
+  listEntitiesForIssue,
+  listIssuesForEntity,
+  removeAssociation,
+} from "../db/issue-associations";
+import { getIssueRef, resolveIssueRefByExternalKey, resolveIssueRefFromString } from "../db/issue-refs";
+import type { IssueAssociationEntityType, IssueAssociationIssue, IssueProvider } from "../types";
+import { ValidationError } from "../db/connection";
+
+export interface ResolveAssociationIssueInput {
+  issueRefId?: string;
+  ref?: string;
+  defaultRepo?: string;
+  provider?: IssueProvider;
+  repo?: string;
+  externalKey?: string;
+  url?: string;
+  title?: string;
+}
+
+export interface AssociateIssueInput extends ResolveAssociationIssueInput {
+  entityType: IssueAssociationEntityType;
+  entityId: string;
+}
+
+export function resolveAssociationIssueRef(input: ResolveAssociationIssueInput) {
+  if (input.issueRefId) {
+    const issueRef = getIssueRef(input.issueRefId);
+    if (!issueRef) throw new ValidationError(`issue ref ${input.issueRefId} not found`);
+    return issueRef;
+  }
+  if (input.ref) {
+    return resolveIssueRefFromString({
+      ref: input.ref,
+      defaultRepo: input.defaultRepo ?? input.repo,
+      provider: input.provider,
+      title: input.title,
+    });
+  }
+  if (input.provider && input.repo && input.externalKey) {
+    return resolveIssueRefByExternalKey({
+      provider: input.provider,
+      repo: input.repo,
+      externalKey: input.externalKey,
+      url: input.url,
+      title: input.title,
+    });
+  }
+  throw new ValidationError("issueRefId, ref, or provider/repo/externalKey required");
+}
+
+export function associateIssueRef(input: AssociateIssueInput) {
+  const issueRef = resolveAssociationIssueRef(input);
+  return {
+    association: associateIssue(issueRef.id, input.entityType, input.entityId),
+    issueRef,
+  };
+}
+
+export function listIssueRefsForEntity(entityType: IssueAssociationEntityType, entityId: string): IssueAssociationIssue[] {
+  return listIssuesForEntity(entityType, entityId);
+}
+
+export function listIssueEntities(issueRefId: string) {
+  return listEntitiesForIssue(issueRefId);
+}
+
+export function removeIssueAssociation(input: AssociateIssueInput): { deleted: boolean } {
+  const issueRef = resolveAssociationIssueRef(input);
+  return { deleted: removeAssociation(issueRef.id, input.entityType, input.entityId) };
+}

package/src/services/issue-lifecycle.ts

@@ -0,0 +1,308 @@
+import { errMessage } from "agent-relay-sdk";
+import { getAgent, listPlansWithBoundOwner } from "../db";
+import { listIssuesForEntity, planNodeIssueEntityId } from "../db/issue-associations";
+import {
+  getSuccessfulIssueLifecycleAction,
+  listSuccessfulCloseActionsForCommit,
+  upsertIssueLifecycleAction,
+} from "../db/issue-lifecycle";
+import { getIssueRef, resolveIssueRefByExternalKey, resolveIssueRefFromString, updateIssueRef } from "../db/issue-refs";
+import { associateIssue } from "../db/issue-associations";
+import { resolveIssueTrackerAdapter } from "../issue-tracker";
+import type { IssueTrackerAdapter } from "../issue-tracker";
+import { recordAndEmitIssueActivity } from "./issue-activity";
+import type { IssueAssociationEntityType, IssueProvider, IssueRef, WorkspaceRecord } from "../types";
+
+type LifecycleWorkspace = Pick<WorkspaceRecord, "id" | "repoRoot" | "branch" | "baseRef" | "ownerAgentId">;
+type AdapterResolver = (ref: IssueRef) => IssueTrackerAdapter;
+type LogFn = (message: string) => void;
+
+export interface LandedIssueLifecycleInput {
+  workspace: LifecycleWorkspace;
+  mergedSha?: string;
+  subject?: string;
+  source?: string;
+}
+
+export interface ReopenIssueLifecycleInput {
+  issueRefId?: string;
+  ref?: string;
+  defaultRepo?: string;
+  provider?: IssueProvider;
+  repo?: string;
+  externalKey?: string;
+  url?: string;
+  title?: string;
+  comment?: string;
+  agentId?: string;
+  entityType?: IssueAssociationEntityType;
+  entityId?: string;
+}
+
+export interface IssueLifecycleOptions {
+  adapterResolver?: AdapterResolver;
+  log?: LogFn;
+}
+
+export type CloseIssueLifecycleResult =
+  | { issueRef: IssueRef; action: "closed"; source: "association" | "commit"; landKey: string }
+  | { issueRef: IssueRef; action: "skipped"; reason: "already-closed" | "already-processed"; landKey: string }
+  | { issueRef: IssueRef; action: "failed"; error: string; landKey: string };
+
+export type ReopenIssueLifecycleResult =
+  | { issueRef: IssueRef; action: "reopened"; landKey: string }
+  | { issueRef: IssueRef; action: "skipped"; reason: "already-open"; landKey: string }
+  | { issueRef: IssueRef; action: "failed"; error: string; landKey: string };
+
+let adapterResolverForTests: AdapterResolver | undefined;
+
+export function __setIssueLifecycleAdapterResolverForTests(resolver: AdapterResolver | undefined): void {
+  adapterResolverForTests = resolver;
+}
+
+function adapterFor(ref: IssueRef, opts: IssueLifecycleOptions): IssueTrackerAdapter {
+  return (opts.adapterResolver ?? adapterResolverForTests ?? resolveIssueTrackerAdapter)(ref);
+}
+
+function logFailure(opts: IssueLifecycleOptions, message: string): void {
+  if (opts.log) opts.log(message);
+  else console.warn(message);
+}
+
+function defaultIssueRepo(): string | undefined {
+  return process.env.AGENT_RELAY_DEFAULT_ISSUE_REPO || process.env.GITHUB_REPOSITORY || undefined;
+}
+
+function cleanText(value: string | undefined): string | undefined {
+  const cleaned = value?.trim();
+  return cleaned || undefined;
+}
+
+function landKey(input: LandedIssueLifecycleInput): string {
+  const base = input.workspace.baseRef ?? "main";
+  const sha = cleanText(input.mergedSha);
+  if (sha) return `land:${base}:${sha}`;
+  return `land:${base}:${input.workspace.id}:${input.workspace.branch ?? "unknown"}:${input.subject ?? ""}`.slice(0, 240);
+}
+
+function manualReopenKey(issueRef: IssueRef): string {
+  return `manual-reopen:${issueRef.id}:${Date.now()}`;
+}
+
+function issueRefMap(refs: IssueRef[]): IssueRef[] {
+  const out = new Map<string, IssueRef>();
+  for (const ref of refs) out.set(ref.id, ref);
+  return [...out.values()];
+}
+
+function associatedIssueRefs(workspace: LifecycleWorkspace): IssueRef[] {
+  const refs: IssueRef[] = [];
+  const owner = workspace.ownerAgentId ? getAgent(workspace.ownerAgentId) : null;
+  if (owner?.teamId) {
+    refs.push(...listIssuesForEntity("team", owner.teamId).map((item) => item.issueRef));
+  }
+  if (workspace.ownerAgentId) {
+    for (const plan of listPlansWithBoundOwner(workspace.ownerAgentId)) {
+      for (const node of plan.nodes) {
+        if (node.ownerRef?.agentId !== workspace.ownerAgentId) continue;
+        refs.push(...listIssuesForEntity("plan-node", planNodeIssueEntityId(plan.id, node.id)).map((item) => item.issueRef));
+      }
+    }
+  }
+  return issueRefMap(refs);
+}
+
+const CLOSING_KEYWORD_RE = /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+([^\n\r]+)/gi;
+const ISSUE_REF_AT_START_RE = /^(https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/issues\/[0-9]+(?:[/?#][^\s,)]*)?|[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+#[0-9]+|#[0-9]+)/;
+const REF_SEPARATOR_RE = /^(?:\s*,\s*|\s+(?:and|&)\s+)/i;
+
+export function parseClosingIssueRefs(text: string | undefined, fallbackDefaultRepo = defaultIssueRepo()): IssueRef[] {
+  if (!text) return [];
+  const refs: IssueRef[] = [];
+  for (const match of text.matchAll(CLOSING_KEYWORD_RE)) {
+    let rest = match[1] ?? "";
+    while (rest.trim()) {
+      rest = rest.trimStart();
+      const refMatch = rest.match(ISSUE_REF_AT_START_RE);
+      if (!refMatch) break;
+      try {
+        refs.push(resolveIssueRefFromString({ ref: refMatch[1]!, defaultRepo: fallbackDefaultRepo }));
+      } catch {
+        // Invalid or bare-without-default refs are ignored; the land itself must never fail here.
+      }
+      rest = rest.slice(refMatch[0].length);
+      const separator = rest.match(REF_SEPARATOR_RE);
+      if (!separator) break;
+      rest = rest.slice(separator[0].length);
+    }
+  }
+  return issueRefMap(refs);
+}
+
+export function resolveIssueRefsForLand(input: LandedIssueLifecycleInput): { source: "association" | "commit"; refs: IssueRef[] } {
+  const associated = associatedIssueRefs(input.workspace);
+  if (associated.length > 0) return { source: "association", refs: associated };
+  return { source: "commit", refs: parseClosingIssueRefs(input.subject) };
+}
+
+function closeAuditComment(input: LandedIssueLifecycleInput): string {
+  const commit = input.mergedSha ? input.mergedSha.slice(0, 12) : input.workspace.branch ?? input.workspace.id;
+  return `Closed by \`${commit}\` on merge to \`main\` - reopen if release surfaces more work.`;
+}
+
+async function closeIssueRefForLand(
+  issueRef: IssueRef,
+  source: "association" | "commit",
+  input: LandedIssueLifecycleInput,
+  opts: IssueLifecycleOptions,
+): Promise<CloseIssueLifecycleResult> {
+  const key = landKey(input);
+  if (getSuccessfulIssueLifecycleAction(issueRef.id, "close", key)) return { issueRef, action: "skipped", reason: "already-processed", landKey: key };
+  const latest = getIssueRef(issueRef.id) ?? issueRef;
+  if (latest.status === "closed") return { issueRef: latest, action: "skipped", reason: "already-closed", landKey: key };
+
+  const comment = closeAuditComment(input);
+  try {
+    await adapterFor(latest, opts).close(latest, { comment, labels: ["fixed"] });
+    const closed = updateIssueRef(latest.id, { status: "closed", statusSyncedAt: Date.now() }) ?? latest;
+    upsertIssueLifecycleAction({
+      issueRefId: latest.id,
+      action: "close",
+      landKey: key,
+      workspaceId: input.workspace.id,
+      branch: input.workspace.branch,
+      baseRef: input.workspace.baseRef ?? "main",
+      commitSha: input.mergedSha,
+      commitSubject: input.subject,
+      agentId: input.workspace.ownerAgentId,
+      source,
+      comment,
+      status: "succeeded",
+    });
+    if (input.workspace.ownerAgentId) {
+      recordAndEmitIssueActivity({
+        agentId: input.workspace.ownerAgentId,
+        action: "done",
+        issueRefId: latest.id,
+        clientId: `issue-close:${latest.id}:${key}`,
+        title: "Issue closed on land",
+        body: comment,
+        metadata: { workspaceId: input.workspace.id, branch: input.workspace.branch, commitSha: input.mergedSha, source },
+      });
+    }
+    return { issueRef: closed, action: "closed", source, landKey: key };
+  } catch (error) {
+    const message = errMessage(error);
+    upsertIssueLifecycleAction({
+      issueRefId: latest.id,
+      action: "close",
+      landKey: key,
+      workspaceId: input.workspace.id,
+      branch: input.workspace.branch,
+      baseRef: input.workspace.baseRef ?? "main",
+      commitSha: input.mergedSha,
+      commitSubject: input.subject,
+      agentId: input.workspace.ownerAgentId,
+      source,
+      comment,
+      status: "failed",
+      error: message,
+    });
+    logFailure(opts, `issue lifecycle close failed for ${latest.id} on ${key}: ${message}`);
+    return { issueRef: latest, action: "failed", error: message, landKey: key };
+  }
+}
+
+function revertedCommitLookup(subject: string | undefined): { commitSha?: string; commitSubject?: string } {
+  const text = cleanText(subject);
+  if (!text) return {};
+  const sha = text.match(/\bThis reverts commit ([0-9a-f]{7,64})\b/i)?.[1];
+  if (sha) return { commitSha: sha };
+  const revertedSubject = text.match(/^Revert "(.+)"$/)?.[1];
+  return revertedSubject ? { commitSubject: revertedSubject } : {};
+}
+
+async function reopenIssuesForRevert(input: LandedIssueLifecycleInput, opts: IssueLifecycleOptions): Promise<ReopenIssueLifecycleResult[]> {
+  const lookup = revertedCommitLookup(input.subject);
+  const closedActions = listSuccessfulCloseActionsForCommit(lookup);
+  const results: ReopenIssueLifecycleResult[] = [];
+  for (const action of closedActions) {
+    results.push(await reopenIssueLifecycle({
+      issueRefId: action.issueRefId,
+      comment: `Reopened by revert \`${input.mergedSha?.slice(0, 12) ?? input.workspace.branch ?? input.workspace.id}\` on merge to \`main\`.`,
+      agentId: input.workspace.ownerAgentId,
+    }, opts));
+  }
+  return results;
+}
+
+export async function handleLandedIssueLifecycle(input: LandedIssueLifecycleInput, opts: IssueLifecycleOptions = {}): Promise<{
+  source: "association" | "commit";
+  closed: CloseIssueLifecycleResult[];
+  reopened: ReopenIssueLifecycleResult[];
+  skipped: string[];
+}> {
+  if ((input.workspace.baseRef ?? "main") !== "main") return { source: "commit", closed: [], reopened: [], skipped: ["non-default-branch"] };
+  const resolved = resolveIssueRefsForLand(input);
+  const closed: CloseIssueLifecycleResult[] = [];
+  for (const ref of resolved.refs) {
+    closed.push(await closeIssueRefForLand(ref, resolved.source, input, opts));
+  }
+  const reopened = await reopenIssuesForRevert(input, opts);
+  return { source: resolved.source, closed, reopened, skipped: [] };
+}
+
+function resolveReopenRef(input: ReopenIssueLifecycleInput): IssueRef {
+  if (input.issueRefId) {
+    const issueRef = getIssueRef(input.issueRefId);
+    if (!issueRef) throw new Error(`issue ref ${input.issueRefId} not found`);
+    return issueRef;
+  }
+  if (input.ref) return resolveIssueRefFromString({ ref: input.ref, defaultRepo: input.defaultRepo ?? input.repo, provider: input.provider, title: input.title });
+  if (input.provider && input.repo && input.externalKey) {
+    return resolveIssueRefByExternalKey({
+      provider: input.provider,
+      repo: input.repo,
+      externalKey: input.externalKey,
+      url: input.url,
+      title: input.title,
+    });
+  }
+  throw new Error("issueRefId, ref, or provider/repo/externalKey required");
+}
+
+export async function reopenIssueLifecycle(input: ReopenIssueLifecycleInput, opts: IssueLifecycleOptions = {}): Promise<ReopenIssueLifecycleResult> {
+  const issueRef = resolveReopenRef(input);
+  const key = manualReopenKey(issueRef);
+  if (issueRef.status === "open") return { issueRef, action: "skipped", reason: "already-open", landKey: key };
+  const comment = input.comment ?? "Reopened by Agent Relay issue lifecycle.";
+  try {
+    await adapterFor(issueRef, opts).reopen(issueRef, { comment });
+    const opened = updateIssueRef(issueRef.id, { status: "open", statusSyncedAt: Date.now() }) ?? issueRef;
+    upsertIssueLifecycleAction({
+      issueRefId: issueRef.id,
+      action: "reopen",
+      landKey: key,
+      agentId: input.agentId,
+      comment,
+      status: "succeeded",
+      source: "explicit",
+    });
+    if (input.entityType && input.entityId) associateIssue(issueRef.id, input.entityType, input.entityId);
+    return { issueRef: opened, action: "reopened", landKey: key };
+  } catch (error) {
+    const message = errMessage(error);
+    upsertIssueLifecycleAction({
+      issueRefId: issueRef.id,
+      action: "reopen",
+      landKey: key,
+      agentId: input.agentId,
+      comment,
+      status: "failed",
+      error: message,
+      source: "explicit",
+    });
+    logFailure(opts, `issue lifecycle reopen failed for ${issueRef.id}: ${message}`);
+    return { issueRef, action: "failed", error: message, landKey: key };
+  }
+}

package/src/services/issue-refs.ts

@@ -0,0 +1,32 @@
+import {
+  deleteIssueRef,
+  getIssueRef,
+  listIssueRefs,
+  resolveIssueRefByExternalKey,
+  resolveIssueRefFromString,
+  updateIssueRef,
+  upsertIssueRef,
+  type ListIssueRefsOptions,
+  type ResolveIssueRefByExternalKeyInput,
+  type ResolveIssueRefFromStringInput,
+  type UpdateIssueRefInput,
+  type UpsertIssueRefInput,
+} from "../db/issue-refs";
+
+export { getIssueRef, listIssueRefs, type ListIssueRefsOptions };
+
+export function upsertIssueRefMapping(input: UpsertIssueRefInput) {
+  return upsertIssueRef(input);
+}
+
+export function resolveIssueRefMapping(input: ResolveIssueRefByExternalKeyInput | ResolveIssueRefFromStringInput) {
+  return "ref" in input ? resolveIssueRefFromString(input) : resolveIssueRefByExternalKey(input);
+}
+
+export function patchIssueRefMapping(id: string, input: UpdateIssueRefInput) {
+  return updateIssueRef(id, input);
+}
+
+export function deleteIssueRefMapping(id: string) {
+  return deleteIssueRef(id);
+}