agent-relay-server 0.61.1 → 0.62.0

package/src/issue-tracker/index.ts

@@ -0,0 +1,13 @@
+export type {
+  IssueTrackerAdapter,
+  IssueTrackerCloseOptions,
+  IssueTrackerReopenOptions,
+  IssueTrackerStatus,
+} from "./adapter";
+export {
+  createIssueTrackerRegistry,
+  issueTrackerRegistry,
+  resolveIssueTrackerAdapter,
+  type IssueTrackerAdapterMap,
+  type IssueTrackerRegistry,
+} from "./registry";

package/src/issue-tracker/registry.ts

@@ -0,0 +1,26 @@
+import type { IssueProvider, IssueRef } from "../types";
+import type { IssueTrackerAdapter } from "./adapter";
+import { githubIssueTrackerAdapter } from "./github";
+
+export type IssueTrackerAdapterMap = Partial<Record<IssueProvider, IssueTrackerAdapter>>;
+
+export interface IssueTrackerRegistry {
+  get(ref: IssueRef): IssueTrackerAdapter;
+}
+
+export function createIssueTrackerRegistry(adapters: IssueTrackerAdapterMap = {}): IssueTrackerRegistry {
+  const resolved: IssueTrackerAdapterMap = { github: githubIssueTrackerAdapter, ...adapters };
+  return {
+    get(ref: IssueRef): IssueTrackerAdapter {
+      const adapter = resolved[ref.provider];
+      if (!adapter) throw new Error(`No issue tracker adapter registered for provider ${ref.provider}`);
+      return adapter;
+    },
+  };
+}
+
+export const issueTrackerRegistry = createIssueTrackerRegistry();
+
+export function resolveIssueTrackerAdapter(ref: IssueRef): IssueTrackerAdapter {
+  return issueTrackerRegistry.get(ref);
+}

package/src/maintenance.ts

@@ -4,7 +4,7 @@ import { expireStaleBusAgents } from "./bus";
 import { pruneOutbox } from "./bus-outbox";
 import { createCommand, expireCommands } from "./commands-db";
 import { DAY_MS, OFFLINE_PRUNE_MS, REAP_INTERVAL_MS, STALE_TTL_MS } from "./config";
-import { isAbsolute, relative, resolve } from "node:path";
+import { resolve } from "node:path";
 import {
   createActivityEvent,
   clearTeamZeroMembersSince,
@@ -13,7 +13,6 @@ import {
   expireQueuedMessages,
   getAgent,
   getDb,
-  getActiveMergePause,
   getRepoSteward,
   getWorkspace,
   listActiveTeams,
@@ -23,7 +22,6 @@ import {
   pruneOfflineAgents,
   pruneOldMessages,
   deleteWorkspace,
-  emitWorkspaceChange,
   pruneOrphanedSharedWorkspaces,
   reapStaleAgents,
   reapStaleOrchestrators,
@@ -37,17 +35,15 @@ import {
   updateWorkspaceStatus,
 } from "./db";
 import type { WorkspaceMergePreview, WorkspaceRecord, WorkspaceStatus } from "./types";
-import { requestWorkspaceMerge } from "./workspace-merge";
 import { reconcileLandedWorkspace } from "./branch-landed";
-import { isAwaitingReviewerApproval } from "./reviewer-pipeline";
 import { preparePrCompletionScan, reconcileLandedPr } from "./workspace-pr-completion";
 import { notifyAgentOffline } from "./agent-lifecycle-events";
-import { workspaceActiveClaim } from "./workspace-claim";
 import { reapOrphanedWorktrees } from "./workspace-orphans";
-import { deriveBranchState, DIRTY_WORKTREE_LAND_SKIP_REASON, READY_TO_LAND_STATUSES, TERMINAL_WORKSPACE_STATUSES } from "./workspace-phase";
-import { errMessage, RELAY_TOKEN_HEADER } from "agent-relay-sdk";
-import { getStewardConfig, getLandingConfig } from "./config-store";
-import { ensureRepoSteward } from "./steward";
+import { deriveBranchState, READY_TO_LAND_STATUSES, TERMINAL_WORKSPACE_STATUSES } from "./workspace-phase";
+import { applyBranchFreshness, fetchHostMergePreview, workspacePathWithinBase } from "./workspace-probe";
+import { autoMergeCleanFastForwards, wakeRepoSteward } from "./workspace-auto-merge";
+import { errMessage } from "agent-relay-sdk";
+import { getStewardConfig } from "./config-store";
 import { emitRelayEvent } from "./events";
 import { getLifecycleManager } from "./lifecycle-manager";
 import { applyCommandToRecipe } from "./recipe-runner";
@@ -72,7 +68,12 @@ const DEFAULT_TIMEOUT_MS = 30_000;
 const SCHEDULER_TICK_MS = 10_000;
 const OUTBOX_RETENTION_MS = Number(process.env.AGENT_RELAY_OUTBOX_RETENTION_MS) || 60 * 60 * 1000;
 const TOKEN_RECORD_RETENTION_SECONDS = Number(process.env.AGENT_RELAY_TOKEN_RECORD_RETENTION_SECONDS) || 7 * 24 * 60 * 60;
-const CONFLICT_SCAN_INTERVAL_MS = Number(process.env.AGENT_RELAY_CONFLICT_SCAN_INTERVAL_MS) || 2 * 60 * 1000;
+// #237: demoted from the 2-min PRIMARY merge-back driver to a slow self-healing
+// backstop now that the work is event-driven (stop-hook freshness + on-ready/on-settle
+// land). ~10 min + runOnStart on both the conflict scan and the auto-merge job: they
+// almost never have work because events did it in seconds; they exist to catch dropped
+// events, relay restarts, and direct human commits with no agent turn.
+const CONFLICT_SCAN_INTERVAL_MS = Number(process.env.AGENT_RELAY_CONFLICT_SCAN_INTERVAL_MS) || 10 * 60 * 1000;
 const WORKSPACE_RETENTION_MS = Number(process.env.AGENT_RELAY_WORKSPACE_RETENTION_MS) || DAY_MS;
 const DB_MAINTENANCE_INTERVAL_MS = Number(process.env.AGENT_RELAY_DB_MAINTENANCE_INTERVAL_MS) || DAY_MS;
 // VACUUM rewrites the whole file (auto_vacuum is off), so run it sparingly.
@@ -90,9 +91,6 @@ const WORKSPACE_ORPHAN_REAPER_INTERVAL_MS = Number(process.env.AGENT_RELAY_WORKS
 // to require a manual or steward merge per repo. Read at call-time so operators can
 // toggle it without a restart.
 const WORKSPACE_AUTO_MERGE_INTERVAL_MS = Number(process.env.AGENT_RELAY_WORKSPACE_AUTO_MERGE_INTERVAL_MS) || CONFLICT_SCAN_INTERVAL_MS;
-// Don't re-wake the managed steward for the same workspace more than once per
-// this window — a persistent conflict/behind row would otherwise re-ping every sweep.
-const STEWARD_WAKE_COOLDOWN_MS = Number(process.env.AGENT_RELAY_STEWARD_WAKE_COOLDOWN_MS) || 10 * 60 * 1000;
 // How long a stranded review_requested/conflict worktree (no online steward) may
 // sit before escalating to the configured fallback target, and the durable
 // escalation target itself (`policy:<name>`, `label:<name>`, `cap:<name>`, an
@@ -420,18 +418,18 @@ const definitions: MaintenanceJobDefinition[] = [
   {
     id: "workspace-conflict-scan",
     title: "Workspace conflict scan",
-    description: "Probe active worktrees for divergence and auto-flag conflicts before merge time.",
+    description: "Self-healing backstop (#237): probe worktrees for divergence/freshness and auto-flag conflicts. The turn-end stop-hook drives the common case; this catches dropped events, restarts, and direct human commits.",
     intervalMs: CONFLICT_SCAN_INTERVAL_MS,
-    runOnStart: false,
+    runOnStart: true,
     timeoutMs: 60 * 1000,
     handler: scanWorkspaceConflicts,
   },
   {
     id: "workspace-auto-merge",
     title: "Workspace auto-merge",
-    description: "Auto-merge any non-conflicting ready/review_requested worktree into base under the per-repo lease (rebasing when the base moved on); only real or unknown conflicts are left for the steward.",
+    description: "Self-healing backstop (#237): land any non-conflicting ready/review_requested worktree under the per-repo lease (rebasing when base moved on); only real/unknown conflicts go to the steward. The on-ready/on-settle event chain drives the common case; runOnStart reclaims rows stranded across a relay restart.",
     intervalMs: WORKSPACE_AUTO_MERGE_INTERVAL_MS,
-    runOnStart: false,
+    runOnStart: true,
     timeoutMs: 60 * 1000,
     handler: autoMergeCleanFastForwards,
   },
@@ -455,31 +453,6 @@ const definitions: MaintenanceJobDefinition[] = [
   },
 ];
 
-function workspacePathWithinBase(path: string | undefined, baseDir: string | undefined): boolean {
-  if (!path || !baseDir) return false;
-  const rel = relative(resolve(baseDir), resolve(path));
-  return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
-}
-
-async function fetchHostMergePreview(apiUrl: string, workspace: WorkspaceRecord, opts: { checkPr?: boolean } = {}): Promise<WorkspaceMergePreview | { available: false } | null> {
-  // `checkPr` costs a `gh` round-trip, so the caller opts in only where PR-merge ground
-  // truth is actionable (reconcile/land candidates), not for every badge-probe (#304).
-  const checkPr = opts.checkPr !== false;
-  const query = new URLSearchParams({ path: workspace.worktreePath, ...(checkPr ? { checkPr: "1" } : {}) });
-  if (workspace.baseRef) query.set("baseRef", workspace.baseRef);
-  if (workspace.baseSha) query.set("baseSha", workspace.baseSha);
-  const headers: Record<string, string> = {};
-  const token = process.env.AGENT_RELAY_TOKEN;
-  if (token) headers[RELAY_TOKEN_HEADER] = token;
-  try {
-    const res = await fetch(`${apiUrl}/api/workspace/merge-preview?${query.toString()}`, { headers, signal: AbortSignal.timeout(8_000) });
-    if (!res.ok) return null;
-    return await res.json() as WorkspaceMergePreview;
-  } catch {
-    return null;
-  }
-}
-
 // Iterate active worktrees and ask the owning host whether each can still merge
 // cleanly. Auto-flag `conflict` when a clean merge is no longer possible, and
 // auto-clear conflicts we set ourselves once they resolve (restoring the prior
@@ -624,36 +597,6 @@ function reapZeroMemberTeams(): Record<string, unknown> {
   return { activeTeams, zeroMemberTeams, trackedTeamIds, clearedTeamIds, reapedTeamIds, graceMs: grace };
 }
 
-// Wake the managed per-repo steward (issue #167) for a workspace it should handle:
-// auto-provision the policy from global steward config, then queue a `policy:` wake
-// message (which also spawns the on-demand agent now via onMessageForPolicy). Honors a
-// per-workspace cooldown so a persistent conflict/behind row isn't re-pinged every sweep.
-// Returns the steward policy name on a fresh wake, or null (disabled / no owner / cooled down).
-function wakeRepoSteward(ws: WorkspaceRecord, reason: string): string | null {
-  const meta = ws.metadata as Record<string, unknown>;
-  const lastWoke = typeof meta.stewardWokenAt === "number" ? meta.stewardWokenAt : 0;
-  if (lastWoke && Date.now() - lastWoke < STEWARD_WAKE_COOLDOWN_MS) return null;
-  const policyName = ensureRepoSteward(ws.repoRoot);
-  if (!policyName) return null;
-  try {
-    // Obligation (ttl null by type default): a steward task must survive until claimed/handled.
-    routeNotification({
-      type: "workspace.steward_task",
-      scope: { workspaceId: ws.id, repoRoot: ws.repoRoot },
-      recipients: [`policy:${policyName}`],
-      message: {
-        subject: `Steward: ${ws.status} workspace needs attention`,
-        body: `Workspace \`${ws.branch ?? ws.id}\` (id ${ws.id}) in ${ws.repoRoot} is ${ws.status} and could not auto-land (${reason}). Claim it first so auto-merge yields: \`agent-relay workspace claim --id ${ws.id} --purpose steward\`. Inspect: \`agent-relay steward inspect ${ws.id}\`. Then cd into ${ws.worktreePath}, rebase onto ${ws.baseRef ?? "base"}, resolve, run checks, and land: \`agent-relay workspace land --id ${ws.id} --strategy rebase-ff\` — or \`agent-relay workspace release --id ${ws.id}\` and escalate if you can't.`,
-        payload: { kind: "workspace.steward-task", workspaceId: ws.id, repoRoot: ws.repoRoot, worktreePath: ws.worktreePath, branch: ws.branch, baseRef: ws.baseRef, status: ws.status, reason },
-      },
-    });
-    getLifecycleManager().onMessageForPolicy(policyName);
-    patchWorkspaceMetadata(ws.id, { stewardWokenAt: Date.now(), stewardPolicy: policyName });
-    return policyName;
-  } catch {
-    return null;
-  }
-}
 
 async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
   const orchestrators = listOrchestrators().filter((orch) => orch.status === "online" && orch.apiUrl);
@@ -677,19 +620,12 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
 
     const meta = ws.metadata as Record<string, unknown>;
 
-    // #236: stash the latest ahead/dirty counts so deriveBranchState can tell idle
-    // (⚪) from changes (🟡) for an active worktree — the relay isn't in the git
-    // path, so this scan is its only window onto the tree. Only write (and refresh
-    // the owner's badge) when the derived state actually flips, to avoid SSE churn
-    // every 2 min on unchanged workspaces. Status-changing branches below own their
-    // own badge refresh via updateWorkspaceStatus.
-    const nextAhead = p.ahead ?? 0;
-    const nextDirty = p.dirtyCount ?? 0;
-    if (meta.gitAhead !== nextAhead || meta.gitDirtyCount !== nextDirty) {
-      const before = deriveBranchState(ws);
-      const patched = patchWorkspaceMetadata(ws.id, { gitAhead: nextAhead, gitDirtyCount: nextDirty, gitProbedAt: Date.now() });
-      if (patched && deriveBranchState(patched) !== before) emitWorkspaceChange(patched);
-    }
+    // #236: stash the host's latest ahead/dirty counts so deriveBranchState can tell
+    // idle (⚪) from changes (🟡). This periodic pass is the self-healing backstop now
+    // that the turn-end stop-hook (`probeWorkspaceState`) flips the badge instantly
+    // (#237); both share `applyBranchFreshness` so the rule can't drift. Status-changing
+    // branches below own their own badge refresh via updateWorkspaceStatus.
+    applyBranchFreshness(ws, p);
 
     // Landing wins over conflict checks. A merged PR can look like a no-op or conflict
     // locally, so reconcile before the conflict-undefined skip and keep finalization in
@@ -777,89 +713,6 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
   return { scanned: candidates.length, flagged, cleared, merged, prRecycled, notifiedStewards, reviewerArmed, reviewerChangesRequested, relayPrMerged, relayPrWaiting };
 }
 
-// Deterministic auto-land (Layer 0, #167/#207/#242): land conflict-free ready
-// work under the shared lease, rebasing when base moved; leave uncertainty to stewards.
-async function autoMergeCleanFastForwards(): Promise<Record<string, unknown>> {
-  if (process.env.AGENT_RELAY_WORKSPACE_AUTO_MERGE === "0") return { skipped: "disabled" };
-  const orchestrators = listOrchestrators().filter((orch) => orch.status === "online" && orch.apiUrl);
-  if (!orchestrators.length) return { scanned: 0, skipped: "no online orchestrators" };
-
-  const candidates = listWorkspaces().filter(
-    (ws) => ws.mode === "isolated" && Boolean(ws.worktreePath) && READY_TO_LAND_STATUSES.has(ws.status),
-  );
-  const stewardEnabled = getStewardConfig().enabled;
-  const merged: string[] = [];
-  const heldByLease: string[] = [], heldByClaim: string[] = [], heldByPause: string[] = [], heldAwaitingApproval: string[] = [], leftForSteward: string[] = [], wokeStewards: string[] = [];
-
-  for (const ws of candidates) {
-    if (isAwaitingReviewerApproval(ws)) { heldAwaitingApproval.push(ws.id); continue; }
-    // A claimed workspace is being validated by a steward — don't race it (#208).
-    if (workspaceActiveClaim(ws)) { heldByClaim.push(ws.id); continue; }
-    if (getActiveMergePause(ws.repoRoot, ws.baseRef ?? "main")) { heldByPause.push(ws.id); continue; }
-    const orch = orchestrators.find((candidate) => workspacePathWithinBase(ws.sourceCwd, candidate.baseDir));
-    if (!orch?.apiUrl) continue;
-    const preview = await fetchHostMergePreview(orch.apiUrl, ws);
-    if (!preview || (preview as { available?: false }).available === false) continue;
-    const p = preview as WorkspaceMergePreview;
-    if (p.error || p.missing) continue;
-    if (p.reason === DIRTY_WORKTREE_LAND_SKIP_REASON) {
-      patchWorkspaceMetadata(ws.id, { lastLandSkipReason: p.reason, lastLandSkipAt: Date.now() });
-    } else if (ws.metadata.lastLandSkipReason === DIRTY_WORKTREE_LAND_SKIP_REASON) {
-      patchWorkspaceMetadata(ws.id, { lastLandSkipReason: undefined, lastLandSkipAt: undefined });
-    }
-
-    const ahead = p.unmergedAhead ?? p.ahead ?? 0;
-    const behind = p.behind ?? 0;
-    // Land anything that won't conflict — including a base that moved on (behind>0)
-    // but rebases cleanly. The merge-tree prediction already accounts for the moved
-    // base, and mergeRebaseFf rebases then aborts-to-conflict on a real replay
-    // conflict, so a too-optimistic prediction degrades safely to review_requested.
-    // Only a predicted conflict (true) or unknown state (undefined) goes to the steward.
-    // A no-op (#230) — nothing to land (ahead=0, clean) — is also landable: the host
-    // resolves it to a terminal `merged` status, draining the queue instead of waking
-    // the steward every sweep for a workspace with no work.
-    const canLand = p.noop === true || (p.conflict === false && ahead > 0);
-    if (!canLand) {
-      leftForSteward.push(ws.id);
-      if (stewardEnabled) {
-        const woke = wakeRepoSteward(ws, p.conflict === true ? "conflict" : "merge state unknown");
-        if (woke) wokeStewards.push(woke);
-      }
-      continue;
-    }
-
-    // Honor the operator's instance landing.strategy (#419-followup): when PR mode is on
-    // (`landing.strategy = "pr"`), autonomous worker lands must open a PR too — not silently
-    // direct-merge. Passing an explicit "rebase-ff" here SHADOWS the instance config inside
-    // requestWorkspaceMerge (explicit wins over instanceStrategy), which is the bug that made
-    // PR mode never engage for spawned workers. For "pr" we OMIT the explicit strategy so
-    // requestWorkspaceMerge resolves it from the config and defaults autoMerge to "on-green";
-    // the default "direct" keeps the historical deterministic rebase-ff (no behavior change).
-    const result = requestWorkspaceMerge(ws, getLandingConfig().strategy === "pr" ? { requestedBy: "auto-merge" } : { strategy: "rebase-ff", requestedBy: "auto-merge" });
-    if (!result.ok) {
-      // 409 = another merge holds this repo's lease this tick; retry next sweep.
-      heldByLease.push(ws.id);
-      continue;
-    }
-    emitCommand(result.command);
-    merged.push(ws.id);
-    createActivityEvent({
-      clientId: `workspace-auto-merge-${ws.id}-${Date.now()}`,
-      kind: "state",
-      title: p.noop ? "Workspace auto-resolving (no work to merge)" : behind > 0 ? "Workspace auto-merging (rebase)" : "Workspace auto-merging (clean fast-forward)",
-      body: p.noop
-        ? `${ws.branch ?? ws.id} → ${p.baseRef ?? "base"} (nothing to land — resolving to merged)`
-        : `${ws.branch ?? ws.id} → ${p.baseRef ?? "base"} (${ahead} ahead${behind > 0 ? `, ${behind} behind — rebasing` : ", clean"})`,
-      meta: ws.branch ?? ws.id,
-      icon: "ti-git-merge",
-      view: "orchestrators",
-      metadata: { source: "server", maintenanceJobId: "workspace-auto-merge", workspaceId: ws.id, commandId: result.command.id, ahead },
-    });
-  }
-
-  return { scanned: candidates.length, merged, heldByLease, heldByClaim, heldByPause, heldAwaitingApproval, leftForSteward, wokeStewards };
-}
-
 // Route a GC notification, swallowing failures (a stale/missing/misconfigured target must never
 // break the GC sweep). Returns the target on success, null otherwise. These are all obligation-style
 // workspace handoffs (null TTL by type default) — they must survive until the recipient acts.

package/src/mcp-issue-activity-tools.ts

@@ -0,0 +1,114 @@
+import { McpNotFoundError } from "./mcp-errors";
+import { ValidationError } from "./db";
+import { getIssueRef } from "./services/issue-refs";
+import {
+  ISSUE_ACTIVITY_ACTIONS,
+  listAgentIssueActivity,
+  listIssueActivityAgents,
+  recordAndEmitIssueActivity,
+  type IssueActivityAction,
+} from "./services/issue-activity";
+import { cleanEnum, cleanMeta, cleanString, optionalEnum } from "./validation";
+import { ISSUE_PROVIDERS, type IssueProvider } from "./types";
+
+export const ISSUE_ACTIVITY_TOOLS = [
+  {
+    name: "relay_issue_activity_record",
+    description: "Record that an agent read, edited, or completed work for an IssueRef. Accepts issueRefId or a raw issueRef string such as #473 or owner/repo#473.",
+    requiredScopes: ["issue:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        agentId: { type: "string" },
+        action: { type: "string", enum: ISSUE_ACTIVITY_ACTIONS },
+        issueRefId: { type: "string" },
+        issueRef: { type: "string" },
+        ref: { type: "string" },
+        defaultRepo: { type: "string" },
+        repo: { type: "string" },
+        provider: { type: "string", enum: ISSUE_PROVIDERS },
+        clientId: { type: "string" },
+        title: { type: "string" },
+        body: { type: "string" },
+        metadata: { type: "object" },
+      },
+      required: ["agentId", "action"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_issue_activity_by_issue",
+    description: "List agents and actions recorded for one internal IssueRef id.",
+    requiredScopes: ["issue:read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        issueRefId: { type: "string" },
+        limit: { type: "integer", minimum: 1, maximum: 500 },
+      },
+      required: ["issueRefId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_issue_activity_by_agent",
+    description: "List IssueRefs and actions touched by one agent.",
+    requiredScopes: ["issue:read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        agentId: { type: "string" },
+        limit: { type: "integer", minimum: 1, maximum: 500 },
+      },
+      required: ["agentId"],
+      additionalProperties: false,
+    },
+  },
+] satisfies Array<{ name: string; description: string; requiredScopes: string[]; inputSchema: Record<string, unknown> }>;
+
+type IssueActivityToolAuth = { kind: string; actor: string; scopes?: string[] };
+
+function providerArg(value: unknown): IssueProvider | undefined {
+  return optionalEnum(value, "provider", ISSUE_PROVIDERS) as IssueProvider | undefined;
+}
+
+function actionArg(value: unknown): IssueActivityAction {
+  return cleanEnum(value, "action", ISSUE_ACTIVITY_ACTIONS) as IssueActivityAction;
+}
+
+function limitArg(value: unknown): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0 || value > 500) {
+    throw new ValidationError("limit must be between 1 and 500");
+  }
+  return value;
+}
+
+export function relayIssueActivityTool(_auth: IssueActivityToolAuth, name: string, args: Record<string, unknown>): Record<string, unknown> {
+  if (name === "relay_issue_activity_record") {
+    const event = recordAndEmitIssueActivity({
+      agentId: cleanString(args.agentId, "agentId", { required: true, max: 200 })!,
+      action: actionArg(args.action),
+      issueRefId: cleanString(args.issueRefId, "issueRefId", { max: 120 }),
+      issueRef: cleanString(args.issueRef ?? args.ref, "issueRef", { max: 1000 }),
+      defaultRepo: cleanString(args.defaultRepo ?? args.repo, "defaultRepo", { max: 500 }),
+      provider: providerArg(args.provider),
+      clientId: cleanString(args.clientId, "clientId", { max: 240 }),
+      title: cleanString(args.title, "title", { max: 200 }),
+      body: cleanString(args.body, "body", { max: 1000 }),
+      metadata: cleanMeta(args.metadata),
+    });
+    return { event };
+  }
+  if (name === "relay_issue_activity_by_issue") {
+    const issueRefId = cleanString(args.issueRefId, "issueRefId", { required: true, max: 120 })!;
+    const issueRef = getIssueRef(issueRefId);
+    if (!issueRef) throw new McpNotFoundError("issue ref not found");
+    return { issueRef, agents: listIssueActivityAgents(issueRef.id, { limit: limitArg(args.limit) }) };
+  }
+  if (name === "relay_issue_activity_by_agent") {
+    const agentId = cleanString(args.agentId, "agentId", { required: true, max: 200 })!;
+    return { agentId, issues: listAgentIssueActivity(agentId, { limit: limitArg(args.limit) }) };
+  }
+  throw new ValidationError(`unknown tool: ${name}`);
+}

package/src/mcp-issue-association-tools.ts

@@ -0,0 +1,130 @@
+import { associateIssueRef, listIssueEntities, listIssueRefsForEntity, removeIssueAssociation, resolveAssociationIssueRef } from "./services/issue-associations";
+import { cleanEnum, cleanString, optionalEnum } from "./validation";
+import { ISSUE_ASSOCIATION_ENTITY_TYPES, ISSUE_PROVIDERS, isRecord, type IssueAssociationEntityType, type IssueProvider } from "./types";
+import { ValidationError } from "./db";
+
+export const ISSUE_ASSOCIATION_TOOLS = [
+  {
+    name: "relay_issue_association_associate",
+    description: "Associate a canonical IssueRef with a team, plan-node, or epic. Accepts issueRefId or raw issue coordinates and stores only the internal IssueRef id.",
+    requiredScopes: ["issue:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        issueRefId: { type: "string" },
+        ref: { type: "string" },
+        defaultRepo: { type: "string" },
+        provider: { type: "string", enum: ISSUE_PROVIDERS },
+        repo: { type: "string" },
+        externalKey: { type: "string" },
+        url: { type: "string" },
+        title: { type: "string" },
+        entityType: { type: "string", enum: ISSUE_ASSOCIATION_ENTITY_TYPES },
+        entityId: { type: "string" },
+      },
+      required: ["entityType", "entityId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_issue_association_list_issues_for_entity",
+    description: "List IssueRefs associated with a team, plan-node, or epic.",
+    requiredScopes: ["issue:read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        entityType: { type: "string", enum: ISSUE_ASSOCIATION_ENTITY_TYPES },
+        entityId: { type: "string" },
+      },
+      required: ["entityType", "entityId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_issue_association_list_entities_for_issue",
+    description: "List teams, plan nodes, and epics associated with an IssueRef. Accepts issueRefId or raw issue coordinates.",
+    requiredScopes: ["issue:read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        issueRefId: { type: "string" },
+        ref: { type: "string" },
+        defaultRepo: { type: "string" },
+        provider: { type: "string", enum: ISSUE_PROVIDERS },
+        repo: { type: "string" },
+        externalKey: { type: "string" },
+        url: { type: "string" },
+        title: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_issue_association_remove",
+    description: "Remove one issue/entity association. Accepts issueRefId or raw issue coordinates.",
+    requiredScopes: ["issue:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        issueRefId: { type: "string" },
+        ref: { type: "string" },
+        defaultRepo: { type: "string" },
+        provider: { type: "string", enum: ISSUE_PROVIDERS },
+        repo: { type: "string" },
+        externalKey: { type: "string" },
+        url: { type: "string" },
+        title: { type: "string" },
+        entityType: { type: "string", enum: ISSUE_ASSOCIATION_ENTITY_TYPES },
+        entityId: { type: "string" },
+      },
+      required: ["entityType", "entityId"],
+      additionalProperties: false,
+    },
+  },
+] satisfies Array<{ name: string; description: string; requiredScopes: string[]; inputSchema: Record<string, unknown> }>;
+
+type IssueAssociationToolAuth = { kind: string; actor: string; scopes?: string[] };
+
+function entityTypeArg(value: unknown): IssueAssociationEntityType {
+  return cleanEnum(value, "entityType", ISSUE_ASSOCIATION_ENTITY_TYPES) as IssueAssociationEntityType;
+}
+
+function issueInput(args: Record<string, unknown>) {
+  return {
+    issueRefId: cleanString(args.issueRefId, "issueRefId", { max: 120 }),
+    ref: cleanString(args.ref, "ref", { max: 1000 }),
+    defaultRepo: cleanString(args.defaultRepo, "defaultRepo", { max: 500 }),
+    provider: optionalEnum(args.provider, "provider", ISSUE_PROVIDERS) as IssueProvider | undefined,
+    repo: cleanString(args.repo, "repo", { max: 500 }),
+    externalKey: cleanString(args.externalKey, "externalKey", { max: 240 }),
+    url: cleanString(args.url, "url", { max: 2000 }),
+    title: cleanString(args.title, "title", { max: 500 }),
+  };
+}
+
+function associationInput(args: Record<string, unknown>) {
+  return {
+    ...issueInput(args),
+    entityType: entityTypeArg(args.entityType),
+    entityId: cleanString(args.entityId, "entityId", { required: true, max: 240 })!,
+  };
+}
+
+export function relayIssueAssociationTool(_auth: IssueAssociationToolAuth, name: string, args: Record<string, unknown>): Record<string, unknown> {
+  if (!isRecord(args)) throw new ValidationError("arguments must be an object");
+  if (name === "relay_issue_association_associate") return associateIssueRef(associationInput(args)) as unknown as Record<string, unknown>;
+  if (name === "relay_issue_association_list_issues_for_entity") {
+    return {
+      issues: listIssueRefsForEntity(
+        entityTypeArg(args.entityType),
+        cleanString(args.entityId, "entityId", { required: true, max: 240 })!,
+      ),
+    };
+  }
+  if (name === "relay_issue_association_list_entities_for_issue") {
+    const issueRef = resolveAssociationIssueRef(issueInput(args));
+    return { issueRef, entities: listIssueEntities(issueRef.id) };
+  }
+  if (name === "relay_issue_association_remove") return removeIssueAssociation(associationInput(args));
+  throw new ValidationError(`unknown tool: ${name}`);
+}

package/src/mcp-issue-lifecycle-tools.ts

@@ -0,0 +1,55 @@
+import { reopenIssueLifecycle } from "./services/issue-lifecycle";
+import { cleanEnum, cleanString, optionalEnum } from "./validation";
+import { ISSUE_ASSOCIATION_ENTITY_TYPES, ISSUE_PROVIDERS, isRecord, type IssueAssociationEntityType, type IssueProvider } from "./types";
+import { ValidationError } from "./db";
+
+export const ISSUE_LIFECYCLE_TOOLS = [
+  {
+    name: "relay_issue_lifecycle_reopen",
+    description: "Reopen a canonical IssueRef through its tracker adapter, update cached status to open, and optionally re-associate it with a team, plan-node, or epic.",
+    requiredScopes: ["issue:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        issueRefId: { type: "string" },
+        ref: { type: "string" },
+        defaultRepo: { type: "string" },
+        provider: { type: "string", enum: ISSUE_PROVIDERS },
+        repo: { type: "string" },
+        externalKey: { type: "string" },
+        url: { type: "string" },
+        title: { type: "string" },
+        comment: { type: "string" },
+        agentId: { type: "string" },
+        entityType: { type: "string", enum: ISSUE_ASSOCIATION_ENTITY_TYPES },
+        entityId: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+  },
+] satisfies Array<{ name: string; description: string; requiredScopes: string[]; inputSchema: Record<string, unknown> }>;
+
+type IssueLifecycleToolAuth = { kind: string; actor: string; scopes?: string[] };
+
+function reopenInput(args: Record<string, unknown>) {
+  return {
+    issueRefId: cleanString(args.issueRefId, "issueRefId", { max: 120 }),
+    ref: cleanString(args.ref, "ref", { max: 1000 }),
+    defaultRepo: cleanString(args.defaultRepo ?? args.repo, "defaultRepo", { max: 500 }),
+    provider: optionalEnum(args.provider, "provider", ISSUE_PROVIDERS) as IssueProvider | undefined,
+    repo: cleanString(args.repo, "repo", { max: 500 }),
+    externalKey: cleanString(args.externalKey, "externalKey", { max: 240 }),
+    url: cleanString(args.url, "url", { max: 2000 }),
+    title: cleanString(args.title, "title", { max: 500 }),
+    comment: cleanString(args.comment, "comment", { max: 2000 }),
+    agentId: cleanString(args.agentId, "agentId", { max: 200 }),
+    entityType: args.entityType === undefined ? undefined : cleanEnum(args.entityType, "entityType", ISSUE_ASSOCIATION_ENTITY_TYPES) as IssueAssociationEntityType,
+    entityId: cleanString(args.entityId, "entityId", { max: 240 }),
+  };
+}
+
+export async function relayIssueLifecycleTool(_auth: IssueLifecycleToolAuth, name: string, args: Record<string, unknown>): Promise<Record<string, unknown>> {
+  if (!isRecord(args)) throw new ValidationError("arguments must be an object");
+  if (name === "relay_issue_lifecycle_reopen") return await reopenIssueLifecycle(reopenInput(args)) as unknown as Record<string, unknown>;
+  throw new ValidationError(`unknown tool: ${name}`);
+}