agent-relay-server 0.61.1 → 0.62.0

package/public/sw.js

@@ -1,4 +1,4 @@
-const CACHE_NAME = "agent-relay-dashboard-v3";
+const CACHE_NAME = "agent-relay-dashboard-v4";
 const scopeUrl = new URL(self.registration.scope);
 const scopePath = scopeUrl.pathname.endsWith("/") ? scopeUrl.pathname : `${scopeUrl.pathname}/`;
 const appUrl = (path) => new URL(path, self.registration.scope).toString();
@@ -65,14 +65,25 @@ self.addEventListener("fetch", (event) => {
     return;
   }
 
-  // Stale-while-revalidate for the app shell and SPA navigations: serve the
-  // cached bundle instantly (the ~10 MB unminified shell never blocks the
-  // network on a slow/high-latency link) and refresh it in the background.
-  // SPA route navigations all resolve to index.html, so key them there to avoid
-  // fragmenting the cache by query string / deep-link path.
+  // index.html / SPA navigations: NETWORK-FIRST. The shell embeds the hashed
+  // code-split chunk filenames, which change on every deploy — and the build
+  // deletes the old chunk files. Serving a stale cached shell (the old
+  // stale-while-revalidate behavior) therefore hands the app a chunk map whose
+  // files are already gone → "Failed to fetch dynamically imported module" on
+  // the first navigation after a deploy. Always fetch a fresh shell when online
+  // so its chunk refs match the live /assets; fall back to cache only offline.
+  // Keyed to index.html (not the deep-link path) to keep one shell entry.
   const isNavigation = request.mode === "navigate";
-  if (isNavigation || APP_SHELL.includes(url.href)) {
-    event.respondWith(staleWhileRevalidate(request, isNavigation ? appUrl("index.html") : request));
+  const indexHref = appUrl("index.html");
+  if (isNavigation || url.href === indexHref) {
+    event.respondWith(networkFirst(request, indexHref));
+    return;
+  }
+
+  // Other app-shell entries (manifest, icons) aren't chunk-coupled, so stale is
+  // harmless: serve cached instantly and refresh in the background.
+  if (APP_SHELL.includes(url.href)) {
+    event.respondWith(staleWhileRevalidate(request, request));
     return;
   }
 
@@ -95,6 +106,19 @@ self.addEventListener("fetch", (event) => {
   );
 });
 
+async function networkFirst(request, cacheKey) {
+  const cache = await caches.open(CACHE_NAME);
+  try {
+    const response = await fetch(request);
+    if (response.ok) await cacheNormalized(cache, cacheKey, response);
+    return response;
+  } catch (err) {
+    const cached = await cache.match(cacheKey);
+    if (cached) return cached;
+    throw err;
+  }
+}
+
 async function cacheFirst(request) {
   const cache = await caches.open(CACHE_NAME);
   const cached = await cache.match(request);

package/src/automations.ts

@@ -39,8 +39,7 @@ import type {
   UpdateAutomationInput,
 } from "./types";
 const AUTOMATION_KIND = "scheduled_task";
-const DEFAULT_TIMEZONE = "UTC";
-const DEFAULT_CATCH_UP: AutomationCatchUpPolicy = "skip";
+const DEFAULT_TIMEZONE = "UTC", DEFAULT_CATCH_UP: AutomationCatchUpPolicy = "skip";
 const DEFAULT_CONCURRENCY: AutomationConcurrencyPolicy = "skip";
 const BLOCKING_RUN_STATUSES = new Set<AutomationRunStatus>(["dispatching", "waiting_agent", "running"]);
 const OPEN_RUN_STATUSES = new Set<AutomationRunStatus>(["scheduled", "dispatching", "waiting_agent", "running"]);
@@ -50,7 +49,6 @@ const MIN_RUNTIME_BUDGET_MS = 60_000;
 const MAX_RUNTIME_BUDGET_MS = 24 * 60 * 60 * 1000;
 
 let initializedDb: unknown = null;
-
 export interface AutomationDispatchResult {
   automation: Automation;
   run: AutomationRun;
@@ -65,11 +63,9 @@ export interface AutomationReconcileResult {
   message?: Message;
   command?: Command;
 }
-
 function db() {
   return getDb();
 }
-
 function ensureAutomationTables(): void {
   const current = db();
   if (initializedDb === current) return;
@@ -563,14 +559,31 @@ function createRunTask(
   meta: Record<string, unknown>,
 ): AutomationDispatchResult {
   const template = automation.taskTemplate;
+  // Inject the authoritative dispatch-time run date (#480). A long-lived managed agent's
+  // session-start day awareness goes stale across midnight, so it can't be trusted to derive
+  // "today" — the briefing emitted "Monday Jun 16" when it ran on a Tuesday. The scheduled
+  // instant + timezone are authoritative here; surface them so the task never depends on the
+  // model's recollection. Templates may place it via {{runDate}}/{{runWeekday}}/{{runDateLine}};
+  // otherwise we prepend a Run date line so every scheduled task carries it.
+  const runDate = formatRunDate(run.scheduledFor, automation.timezone);
+  const tokens: Record<string, string> = { runDate: runDate.iso, runWeekday: runDate.weekday, runDateLine: runDate.line };
+  const fill = (text: string) => text.replace(/\{\{\s*(runDate|runWeekday|runDateLine)\s*\}\}/g, (_match, key) => tokens[key] ?? "");
+  const usesRunDateToken = /\{\{\s*(runDate|runWeekday|runDateLine)\s*\}\}/.test(`${template.title}\n${template.body}`);
+  const title = fill(template.title);
+  const body = usesRunDateToken ? fill(template.body) : `Run date: ${runDate.line}.\n\n${template.body}`;
   const result = ingestIntegrationEvent({
     source: "automation",
     type: "scheduled_task",
     severity: template.severity ?? "info",
-    title: template.title,
-    body: template.body,
+    title,
+    body,
     target,
     channel: "automation",
+    // #479 — automation tasks complete via the task-status lifecycle (claim → done), never a
+    // `/reply`. A reply obligation here is unsatisfiable and re-injects the task into every
+    // successor session when a restart-prone managed agent (e.g. the daily telegram briefing)
+    // mints a new agent id, re-firing the scheduled work off-schedule. Dispatch without one.
+    replyExpected: false,
     dedupeKey: template.dedupeKey ? `${template.dedupeKey}:${run.id}` : `automation:${automation.id}:run:${run.id}`,
     externalUrl: template.externalUrl,
     metadata: {
@@ -578,6 +591,9 @@ function createRunTask(
       automationId: automation.id,
       automationRunId: run.id,
       orchestratorId: automation.orchestratorId,
+      runDate: runDate.iso,
+      runWeekday: runDate.weekday,
+      runTimezone: automation.timezone,
       ...meta,
     },
   }, "automation");
@@ -979,6 +995,23 @@ function parseCronField(field: string, min: number, max: number, name: string):
   return values;
 }
 
+// Authoritative localized run date for a dispatched automation task (#480). Formats the
+// scheduled instant in the automation's timezone via the same Intl machinery as cron eval, so
+// scheduled output ("today is …") never depends on a long-lived agent's stale session context.
+function formatRunDate(timestamp: number, timezone: string): { iso: string; weekday: string; line: string } {
+  const dtf = new Intl.DateTimeFormat("en-US", {
+    timeZone: timezone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    weekday: "long",
+  });
+  const parts = Object.fromEntries(dtf.formatToParts(new Date(timestamp)).map((part) => [part.type, part.value]));
+  const iso = `${parts.year}-${parts.month}-${parts.day}`;
+  const weekday = parts.weekday ?? "";
+  return { iso, weekday, line: `${weekday}, ${iso} (${timezone})` };
+}
+
 function localParts(timestamp: number, timezone: string): LocalTimeParts {
   const dtf = new Intl.DateTimeFormat("en-US", {
     timeZone: timezone,

package/src/branch-landed.ts

@@ -1,8 +1,10 @@
+import { errMessage } from "agent-relay-sdk";
 import { emitRelayEvent } from "./events";
 import { getNotificationsConfig } from "./config-store";
 import { routeNotification, INFORMATIONAL_TTL_MS } from "./notification-router";
 import { registerDefaultAudienceRules, resolveAudience, audiencePredicates } from "./notification-rules";
 import { createActivityEvent, getAgent, updateWorkspaceStatus } from "./db";
+import { handleLandedIssueLifecycle } from "./services/issue-lifecycle";
 import type { WorkspaceMergePreview, WorkspaceRecord } from "./types";
 
 // #444 — branch.landed is the first rule-driven type: the on-main "merged" fan-out audience comes
@@ -64,6 +66,9 @@ export function notifyBranchLanded(input: BranchLandedInput): void {
       pushed: input.pushed,
     },
   });
+  void handleLandedIssueLifecycle(input, { log: (message) => console.warn(message) }).catch((error) => {
+    console.warn(`issue lifecycle land hook failed for ${workspace.id}: ${errMessage(error)}`);
+  });
 
   const config = getNotificationsConfig();
   if (!config.enabled || !config.branchLanded) return;

package/src/bus.ts

@@ -14,6 +14,7 @@ import { ShutdownAuthError, ShutdownTargetError, shutdownAgent, shutdownInputFro
 import { applyCommandToRecipe } from "./recipe-runner";
 import { enqueueContinuationInjectionAfterClear } from "./self-resume";
 import { messageMatchesAgent, targetMatchesAgent } from "./agent-ref";
+import { probeWorkspaceOnTurnEnd } from "./workspace-probe";
 import {
   BusProtocolError,
   parseBusFrame,
@@ -174,6 +175,8 @@ function handleFrame(ws: BusWebSocket, frame: ReturnType<typeof validateClientFr
         // merged meta — clears any pending stall watch (stale events ignored).
         noteAgentTimelineEvent(conn.agentId, after?.meta?.timelineEvent);
         emitAgentStatusEvent(conn.agentId);
+        // #237 stop-hook → instant ⚪↔🟡 changes detection on the turn-end edge.
+        probeWorkspaceOnTurnEnd(before, after);
       });
       return;
     case "ack":

package/src/cli/workspace.ts

@@ -5,8 +5,7 @@ import { apiRequest } from "./_shared";
 import { detectAgentId } from "./agent-detect";
 import { describeWorkspacePhase, readyContract, type WorkspacePhaseView } from "../workspace-phase";
 import type { WorkspaceDepsRefreshResult } from "agent-relay-sdk";
-import { AUTO_MERGE_POLICIES, resolveLandStrategy } from "../workspace-merge";
-import { getLandingConfig } from "../config-store";
+import { AUTO_MERGE_POLICIES } from "../workspace-merge";
 import type { WorkspaceAutoMergePolicy } from "../types";
 
 export const WORKSPACE_USAGE = "Usage: agent-relay workspace <status|diagnostics|ready|land|claim|release|list|cleanup-stale|deps> [--id ID] [--strategy ...] [--auto-merge on-green|on-approval|manual] [--reviewer HANDLE] [--purpose TEXT] [--repo PATH] [--wait] [--timeout SECONDS] [--check] [--execute] [--json]";
@@ -204,19 +203,12 @@ export async function handleWorkspaceCommand(args: string[]): Promise<void> {
 
   const from = await detectAgentId();
 
-  // For the `land` action, resolve the effective strategy via the three-level chain
-  // (explicit > instance config > default) so a bare `land` with no --strategy still
-  // picks up the operator's landing.strategy setting. The strategy is passed verbatim
-  // to the server; requestWorkspaceMerge is the single resolution point for the default.
-  let resolvedStrategy: string | undefined = strategy;
-  if (action === "land") {
-    const instanceConfig = getLandingConfig();
-    resolvedStrategy = resolveLandStrategy({
-      explicit: strategy,
-      instanceStrategy: instanceConfig.strategy,
-    });
-  }
-
+  // For the `land` action, pass --strategy through verbatim (undefined when unset).
+  // The server is the SINGLE resolution point: requestWorkspaceMerge resolves the
+  // three-level chain (explicit > instance config > default) server-side. The CLI
+  // must NOT read landing config locally — that needs the server DB, which isn't
+  // initialized in a CLI/steward process and fails with "database not initialized"
+  // (#481). resolveLandStrategy + getLandingConfig stay server-only.
   const actionBody: Record<string, unknown> =
     action === "ready" ? { action: "request-review", agentId: from }
     : action === "claim" ? { action: "claim", agentId: from, purpose }
@@ -224,7 +216,7 @@ export async function handleWorkspaceCommand(args: string[]): Promise<void> {
     : {
         action: "merge",
         agentId: from,
-        ...(resolvedStrategy ? { strategy: resolvedStrategy } : {}),
+        ...(strategy ? { strategy } : {}),
         ...(autoMerge ? { autoMerge } : {}),
         ...(reviewer ? { reviewer } : {}),
       };
@@ -243,6 +235,6 @@ export async function handleWorkspaceCommand(args: string[]): Promise<void> {
   console.log(
     action === "claim" ? `Workspace ${id} claimed${purpose ? ` (${purpose})` : ""} — auto-merge will yield until released or the claim expires.`
     : action === "release" ? `Workspace ${id} claim released.`
-    : `Workspace ${id} merge requested (${resolvedStrategy ?? "auto"}${autoMerge ? `, autoMerge: ${autoMerge}` : ""}${reviewer ? `, reviewer: ${reviewer}` : ""}).`,
+    : `Workspace ${id} merge requested (${strategy ?? "server default"}${autoMerge ? `, autoMerge: ${autoMerge}` : ""}${reviewer ? `, reviewer: ${reviewer}` : ""}).`,
   );
 }

package/src/db/activity.ts

@@ -14,8 +14,9 @@ import {
 } from "../contracts";
 import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_MERGE_LEASE_MS } from "../config";
 import { matchAgents } from "../agent-ref";
-import { getDb } from "./connection.ts";
+import { getDb, ValidationError } from "./connection.ts";
 import { rowToActivityEvent } from "./mappers.ts";
+import { getIssueRef, resolveIssueRefFromString } from "./issue-refs.ts";
 import type {
   AgentCard,
   ActivityEvent,
@@ -77,11 +78,49 @@ import type {
   WorkspaceMetadata,
   WorkspaceRecord,
   WorkspaceStatus,
+  IssueProvider,
+  IssueRef,
 } from "../types";
 
+export const ISSUE_ACTIVITY_ACTIONS = ["read", "edit", "done"] as const;
+export type IssueActivityAction = (typeof ISSUE_ACTIVITY_ACTIONS)[number];
+
+export interface RecordIssueActivityInput {
+  agentId: string;
+  action: IssueActivityAction;
+  issueRefId?: string;
+  issueRef?: string;
+  defaultRepo?: string;
+  provider?: IssueProvider;
+  clientId?: string;
+  title?: string;
+  body?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface IssueActivityAgentSummary {
+  agentId: string;
+  agentName?: string;
+  agentKind?: string;
+  action: IssueActivityAction;
+  count: number;
+  firstAt: number;
+  lastAt: number;
+}
+
+export interface AgentIssueActivitySummary {
+  issueRef: IssueRef;
+  action: IssueActivityAction;
+  count: number;
+  firstAt: number;
+  lastAt: number;
+}
+
 export function listActivityEvents(input: {
   operatorId?: string;
   agentId?: string;
+  issueRefId?: string;
+  issueAction?: IssueActivityAction;
   limit?: number;
   since?: number;
 } = {}): ActivityEvent[] {
@@ -95,6 +134,14 @@ export function listActivityEvents(input: {
     conditions.push("agent_id = ?");
     params.push(input.agentId);
   }
+  if (input.issueRefId) {
+    conditions.push("issue_ref_id = ?");
+    params.push(input.issueRefId);
+  }
+  if (input.issueAction) {
+    conditions.push("issue_action = ?");
+    params.push(input.issueAction);
+  }
   if (input.since !== undefined) {
     conditions.push("created_at >= ?");
     params.push(input.since);
@@ -169,9 +216,9 @@ export function createActivityEvent(input: ActivityEventInput): ActivityEvent {
   const result = getDb().query(`
     INSERT INTO activity_events (
       operator_id, client_id, kind, title, body, meta_text, icon, view, peer_id,
-      message_id, pair_id, task_id, agent_id, metadata, created_at
+      message_id, pair_id, task_id, agent_id, issue_ref_id, issue_action, metadata, created_at
     )
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `).run(
     input.operatorId ?? null,
     input.clientId ?? null,
@@ -186,9 +233,150 @@ export function createActivityEvent(input: ActivityEventInput): ActivityEvent {
     input.pairId ?? null,
     input.taskId ?? null,
     input.agentId ?? null,
+    input.issueRefId ?? null,
+    input.issueAction ?? null,
     JSON.stringify(input.metadata ?? {}),
     now,
   );
   return rowToActivityEvent(getDb().query("SELECT * FROM activity_events WHERE id = ?").get(Number(result.lastInsertRowid)));
 }
 
+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 cleanIssueAction(action: IssueActivityAction): IssueActivityAction {
+  if (!ISSUE_ACTIVITY_ACTIONS.includes(action)) {
+    throw new ValidationError(`action must be one of: ${ISSUE_ACTIVITY_ACTIONS.join(", ")}`);
+  }
+  return action;
+}
+
+function cleanIssueActivityLimit(limit: number | undefined): number {
+  if (limit === undefined) return 200;
+  if (!Number.isSafeInteger(limit) || limit <= 0 || limit > 500) throw new ValidationError("limit must be between 1 and 500");
+  return limit;
+}
+
+function resolveIssueRefForActivity(input: { issueRefId?: string; issueRef?: string; defaultRepo?: string; provider?: IssueProvider }): IssueRef {
+  const issueRefId = optionalText(input.issueRefId, "issueRefId", 120);
+  if (issueRefId) {
+    const issueRef = getIssueRef(issueRefId);
+    if (!issueRef) throw new ValidationError(`issue ref ${issueRefId} not found`);
+    return issueRef;
+  }
+  const ref = optionalText(input.issueRef, "issueRef", 1000);
+  if (!ref) throw new ValidationError("issueRefId or issueRef required");
+  return resolveIssueRefFromString({
+    ref,
+    defaultRepo: optionalText(input.defaultRepo, "defaultRepo", 500),
+    provider: input.provider,
+  });
+}
+
+export function resolveIssueActivityRef(input: { issueRefId?: string; issueRef?: string; defaultRepo?: string; provider?: IssueProvider }): IssueRef {
+  return resolveIssueRefForActivity(input);
+}
+
+export function recordIssueActivity(input: RecordIssueActivityInput): ActivityEvent {
+  const agentId = requiredText(input.agentId, "agentId", 200);
+  const action = cleanIssueAction(input.action);
+  const issueRef = resolveIssueRefForActivity(input);
+  const metadata = {
+    ...(input.metadata ?? {}),
+    issueRefId: issueRef.id,
+    issueAction: action,
+  };
+  return createActivityEvent({
+    clientId: optionalText(input.clientId, "clientId", 240),
+    kind: "issue",
+    title: optionalText(input.title, "title", 200) ?? `Issue ${action}`,
+    body: optionalText(input.body, "body", 1000),
+    agentId,
+    issueRefId: issueRef.id,
+    issueAction: action,
+    metadata,
+  });
+}
+
+export function listIssueActivityAgents(issueRefId: string, opts: { limit?: number } = {}): IssueActivityAgentSummary[] {
+  const id = requiredText(issueRefId, "issueRefId", 120);
+  if (!getIssueRef(id)) throw new ValidationError(`issue ref ${id} not found`);
+  const rows = getDb().query(`
+    SELECT
+      ae.agent_id,
+      a.name AS agent_name,
+      a.kind AS agent_kind,
+      ae.issue_action,
+      count(*) AS count,
+      min(ae.created_at) AS first_at,
+      max(ae.created_at) AS last_at
+    FROM activity_events ae
+    LEFT JOIN agents a ON a.id = ae.agent_id
+    WHERE ae.issue_ref_id = ? AND ae.agent_id IS NOT NULL AND ae.issue_action IS NOT NULL
+    GROUP BY ae.agent_id, ae.issue_action
+    ORDER BY last_at DESC, ae.agent_id ASC, ae.issue_action ASC
+    LIMIT ?
+  `).all(id, cleanIssueActivityLimit(opts.limit)) as Array<{
+    agent_id: string;
+    agent_name: string | null;
+    agent_kind: string | null;
+    issue_action: IssueActivityAction;
+    count: number;
+    first_at: number;
+    last_at: number;
+  }>;
+  return rows.map((row) => ({
+    agentId: row.agent_id,
+    ...(row.agent_name ? { agentName: row.agent_name } : {}),
+    ...(row.agent_kind ? { agentKind: row.agent_kind } : {}),
+    action: cleanIssueAction(row.issue_action),
+    count: row.count,
+    firstAt: row.first_at,
+    lastAt: row.last_at,
+  }));
+}
+
+export function listAgentIssueActivity(agentId: string, opts: { limit?: number } = {}): AgentIssueActivitySummary[] {
+  const id = requiredText(agentId, "agentId", 200);
+  const rows = getDb().query(`
+    SELECT
+      ae.issue_ref_id,
+      ae.issue_action,
+      count(*) AS count,
+      min(ae.created_at) AS first_at,
+      max(ae.created_at) AS last_at
+    FROM activity_events ae
+    WHERE ae.agent_id = ? AND ae.issue_ref_id IS NOT NULL AND ae.issue_action IS NOT NULL
+    GROUP BY ae.issue_ref_id, ae.issue_action
+    ORDER BY last_at DESC, ae.issue_ref_id ASC, ae.issue_action ASC
+    LIMIT ?
+  `).all(id, cleanIssueActivityLimit(opts.limit)) as Array<{
+    issue_ref_id: string;
+    issue_action: IssueActivityAction;
+    count: number;
+    first_at: number;
+    last_at: number;
+  }>;
+  return rows.flatMap((row) => {
+    const issueRef = getIssueRef(row.issue_ref_id);
+    if (!issueRef) return [];
+    return [{
+      issueRef,
+      action: cleanIssueAction(row.issue_action),
+      count: row.count,
+      firstAt: row.first_at,
+      lastAt: row.last_at,
+    }];
+  });
+}

package/src/db/integrations.ts

@@ -166,6 +166,7 @@ export function ingestIntegrationEvent(input: IntegrationEventInput, integration
         subject: `[${task.severity}] ${task.title}`,
         body: taskMessageBody(task),
         claimable: true,
+        replyExpected: input.replyExpected,
         payload: {
           taskId: task.id,
           source: task.source,

package/src/db/issue-associations.ts

@@ -0,0 +1,128 @@
+import { ISSUE_ASSOCIATION_ENTITY_TYPES, type IssueAssociation, type IssueAssociationEntity, type IssueAssociationEntityType, type IssueAssociationIssue } from "../types";
+import { getDb, ValidationError } from "./connection.ts";
+import { getIssueRef } from "./issue-refs.ts";
+
+interface IssueAssociationRow {
+  issue_ref_id: string;
+  entity_type: IssueAssociationEntityType;
+  entity_id: string;
+  created_at: number;
+}
+
+export function planNodeIssueEntityId(planId: string, nodeId: string): string {
+  return `${cleanText(planId, "planId", 120)}:${cleanText(nodeId, "nodeId", 120)}`;
+}
+
+function rowToAssociation(row: IssueAssociationRow): IssueAssociation {
+  return {
+    issueRefId: row.issue_ref_id,
+    entityType: row.entity_type,
+    entityId: row.entity_id,
+    createdAt: row.created_at,
+  };
+}
+
+function cleanEntityType(value: IssueAssociationEntityType): IssueAssociationEntityType {
+  if (!ISSUE_ASSOCIATION_ENTITY_TYPES.includes(value)) {
+    throw new ValidationError(`entityType must be one of: ${ISSUE_ASSOCIATION_ENTITY_TYPES.join(", ")}`);
+  }
+  return value;
+}
+
+function cleanText(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;
+}
+
+export function associateIssue(issueRefId: string, entityType: IssueAssociationEntityType, entityId: string): IssueAssociation {
+  const cleanedIssueRefId = cleanText(issueRefId, "issueRefId", 120);
+  if (!getIssueRef(cleanedIssueRefId)) throw new ValidationError(`issue ref ${cleanedIssueRefId} not found`);
+  const cleanedEntityType = cleanEntityType(entityType);
+  const cleanedEntityId = cleanText(entityId, "entityId", 240);
+  const now = Date.now();
+  getDb().query(`
+    INSERT INTO issue_associations (issue_ref_id, entity_type, entity_id, created_at)
+    VALUES (?, ?, ?, ?)
+    ON CONFLICT(issue_ref_id, entity_type, entity_id) DO NOTHING
+  `).run(cleanedIssueRefId, cleanedEntityType, cleanedEntityId, now);
+  const row = getDb().query(`
+    SELECT issue_ref_id, entity_type, entity_id, created_at
+    FROM issue_associations
+    WHERE issue_ref_id = ? AND entity_type = ? AND entity_id = ?
+  `).get(cleanedIssueRefId, cleanedEntityType, cleanedEntityId) as IssueAssociationRow | undefined;
+  if (!row) throw new ValidationError("issue association could not be created");
+  return rowToAssociation(row);
+}
+
+export function listIssuesForEntity(entityType: IssueAssociationEntityType, entityId: string): IssueAssociationIssue[] {
+  const rows = getDb().query(`
+    SELECT
+      a.issue_ref_id,
+      a.entity_type,
+      a.entity_id,
+      a.created_at,
+      r.id,
+      r.provider,
+      r.repo,
+      r.external_key,
+      r.url,
+      r.title,
+      r.status,
+      r.status_synced_at,
+      r.created_at AS issue_created_at,
+      r.updated_at AS issue_updated_at
+    FROM issue_associations a
+    JOIN issue_refs r ON r.id = a.issue_ref_id
+    WHERE a.entity_type = ? AND a.entity_id = ?
+    ORDER BY a.created_at DESC, a.issue_ref_id DESC
+  `).all(cleanEntityType(entityType), cleanText(entityId, "entityId", 240)) as Array<IssueAssociationRow & {
+    id: string;
+    provider: IssueAssociationIssue["issueRef"]["provider"];
+    repo: string;
+    external_key: string;
+    url: string;
+    title: string | null;
+    status: IssueAssociationIssue["issueRef"]["status"];
+    status_synced_at: number | null;
+    issue_created_at: number;
+    issue_updated_at: number;
+  }>;
+  return rows.map((row) => ({
+    association: rowToAssociation(row),
+    issueRef: {
+      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.issue_created_at,
+      updatedAt: row.issue_updated_at,
+    },
+  }));
+}
+
+export function listEntitiesForIssue(issueRefId: string): IssueAssociationEntity[] {
+  const cleanedIssueRefId = cleanText(issueRefId, "issueRefId", 120);
+  if (!getIssueRef(cleanedIssueRefId)) throw new ValidationError(`issue ref ${cleanedIssueRefId} not found`);
+  const rows = getDb().query(`
+    SELECT issue_ref_id, entity_type, entity_id, created_at
+    FROM issue_associations
+    WHERE issue_ref_id = ?
+    ORDER BY created_at DESC, entity_type ASC, entity_id ASC
+  `).all(cleanedIssueRefId) as IssueAssociationRow[];
+  return rows.map((row) => ({ entityType: row.entity_type, entityId: row.entity_id, createdAt: row.created_at }));
+}
+
+export function removeAssociation(issueRefId: string, entityType: IssueAssociationEntityType, entityId: string): boolean {
+  const result = getDb().query(`
+    DELETE FROM issue_associations
+    WHERE issue_ref_id = ? AND entity_type = ? AND entity_id = ?
+  `).run(cleanText(issueRefId, "issueRefId", 120), cleanEntityType(entityType), cleanText(entityId, "entityId", 240));
+  return result.changes > 0;
+}