agent-relay-server 0.62.3 → 0.63.0

package/src/issue-tracker/github.ts

@@ -2,7 +2,7 @@ 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";
+const GITHUB_CREDENTIAL_REQUIREMENT = "GitHub issue tracker adapter requires gh authenticated with a token that has issues:write scope";
 
 type GitHubApiMethod = "GET" | "PATCH" | "POST";
 
@@ -12,7 +12,7 @@ export interface GitHubApiRequest {
   body?: Record<string, unknown>;
 }
 
-export type GitHubApi = (request: GitHubApiRequest) => Promise<unknown>;
+type GitHubApi = (request: GitHubApiRequest) => Promise<unknown>;
 
 interface GitHubIssuePayload {
   state?: unknown;
@@ -92,7 +92,7 @@ function uniqueLabels(labels: string[]): string[] {
   return [...new Set(labels.map((label) => label.trim()).filter(Boolean))];
 }
 
-export class GitHubIssueTrackerAdapter implements IssueTrackerAdapter {
+class GitHubIssueTrackerAdapter implements IssueTrackerAdapter {
   constructor(private readonly api: GitHubApi = ghApi) {}
 
   resolveLink(ref: IssueRef): string {

package/src/maintenance/constants.ts

@@ -0,0 +1,35 @@
+import { DAY_MS, REAP_INTERVAL_MS } from "../config";
+import { READY_TO_LAND_STATUSES, TERMINAL_WORKSPACE_STATUSES } from "../workspace-phase";
+import type { WorkspaceStatus } from "../types";
+
+export { DAY_MS, REAP_INTERVAL_MS, TERMINAL_WORKSPACE_STATUSES };
+
+export const DEFAULT_TIMEOUT_MS = 30_000;
+export const SCHEDULER_TICK_MS = 10_000;
+export const OUTBOX_RETENTION_MS = Number(process.env.AGENT_RELAY_OUTBOX_RETENTION_MS) || 60 * 60 * 1000;
+export const TOKEN_RECORD_RETENTION_SECONDS = Number(process.env.AGENT_RELAY_TOKEN_RECORD_RETENTION_SECONDS) || 7 * 24 * 60 * 60;
+export const CONFLICT_SCAN_INTERVAL_MS = Number(process.env.AGENT_RELAY_CONFLICT_SCAN_INTERVAL_MS) || 10 * 60 * 1000;
+export const WORKSPACE_RETENTION_MS = Number(process.env.AGENT_RELAY_WORKSPACE_RETENTION_MS) || DAY_MS;
+export const DB_MAINTENANCE_INTERVAL_MS = Number(process.env.AGENT_RELAY_DB_MAINTENANCE_INTERVAL_MS) || DAY_MS;
+export const DB_VACUUM_EVERY = Number(process.env.AGENT_RELAY_DB_VACUUM_EVERY) || 7;
+export const WORKSPACE_REVIEW_TTL_MS = Number(process.env.AGENT_RELAY_WORKSPACE_REVIEW_TTL_MS) || 3 * DAY_MS;
+export const WORKSPACE_GC_INTERVAL_MS = Number(process.env.AGENT_RELAY_WORKSPACE_GC_INTERVAL_MS) || 60 * 60 * 1000;
+export const WORKSPACE_ORPHAN_REAPER_INTERVAL_MS = Number(process.env.AGENT_RELAY_WORKSPACE_ORPHAN_REAPER_INTERVAL_MS) || 30 * 60 * 1000;
+export const WORKSPACE_AUTO_MERGE_INTERVAL_MS = Number(process.env.AGENT_RELAY_WORKSPACE_AUTO_MERGE_INTERVAL_MS) || CONFLICT_SCAN_INTERVAL_MS;
+export const ORPHAN_REAPER_INTERVAL_MS = Number(process.env.AGENT_RELAY_ORPHAN_REAPER_INTERVAL_MS) || 5 * 60 * 1000;
+
+export const stewardEscalationMs = () => Number(process.env.AGENT_RELAY_WORKSPACE_STEWARD_ESCALATION_MS) || 60 * 60 * 1000;
+export const stewardFallbackTarget = () => (process.env.AGENT_RELAY_WORKSPACE_STEWARD_FALLBACK || "").trim();
+export const STRANDABLE_STATUSES = new Set<WorkspaceStatus>([...READY_TO_LAND_STATUSES, "conflict"]);
+export const CONFLICT_SCAN_STATUSES = new Set<WorkspaceStatus>(["active", "ready", "review_requested", "merge_planned", "conflict"]);
+export const LANDED_RECONCILE_STATUSES = new Set<WorkspaceStatus>(["merge_planned", "review_requested", "conflict"]);
+
+export const envMsOrDefault = (name: string, fallback: number): number => {
+  const v = Number(process.env[name]);
+  return Number.isFinite(v) && v >= 0 ? v : fallback;
+};
+export const orphanGraceMs = () => envMsOrDefault("AGENT_RELAY_ORPHAN_GRACE_MS", 30 * 60 * 1000);
+export const orphanReapCooldownMs = () => envMsOrDefault("AGENT_RELAY_ORPHAN_REAP_COOLDOWN_MS", 5 * 60 * 1000);
+export const teamReapGraceMs = () => envMsOrDefault("TEAM_REAP_GRACE_MS", 30 * 60 * 1000);
+export const teamReapIntervalMs = () => envMsOrDefault("TEAM_REAP_INTERVAL_MS", 5 * 60 * 1000);
+export const orphanReapEnabled = () => process.env.AGENT_RELAY_ORPHAN_REAP !== "0";

package/src/maintenance/events.ts

@@ -0,0 +1,32 @@
+import { emitRelayEvent } from "../events";
+import { routeNotification, type NotificationScope, type NotificationType } from "../notification-router";
+import type { Command } from "../types";
+
+export function emitCommand(command: Command): void {
+  const suffix = command.status === "timed_out" ? "timed_out" : command.status;
+  emitRelayEvent({
+    type: `command.${suffix}`,
+    source: command.source,
+    subject: command.id,
+    data: { command },
+  });
+}
+
+// Route a maintenance notification, swallowing failures (a stale/missing/misconfigured
+// target must never break the sweep). Returns the target on success, null otherwise.
+export function notifyTarget(
+  type: NotificationType,
+  scope: NotificationScope,
+  target: string,
+  subject: string,
+  body: string,
+  payload: Record<string, unknown>,
+): string | null {
+  if (!target) return null;
+  try {
+    routeNotification({ type, scope, recipients: [target], message: { subject, body, payload } });
+    return target;
+  } catch {
+    return null;
+  }
+}

package/src/maintenance/index.ts

@@ -0,0 +1,7 @@
+export {
+  listMaintenanceJobs,
+  resetOrphanTrackerForTests,
+  runLegacyMaintenanceReaper,
+  runMaintenanceJobNow,
+  startMaintenanceScheduler,
+} from "./scheduler";

package/src/maintenance/jobs.ts

@@ -0,0 +1,340 @@
+import { getArtifactStorage } from "../artifact-storage";
+import { expireStaleBusAgents } from "../bus";
+import { pruneOutbox } from "../bus-outbox";
+import { expireCommands } from "../commands-db";
+import { OFFLINE_PRUNE_MS, REAP_INTERVAL_MS, STALE_TTL_MS } from "../config";
+import {
+  createActivityEvent,
+  evaluatePoolBindings,
+  expireQueuedMessages,
+  pruneOrphanedSharedWorkspaces,
+  pruneOfflineAgents,
+  pruneOldMessages,
+  reapStaleAgents,
+  reapStaleOrchestrators,
+  releaseExpiredClaims,
+  releaseOrphanedTasks,
+  runDbMaintenance,
+  sweepArtifacts,
+} from "../db";
+import { notifyAgentOffline } from "../agent-lifecycle-events";
+import { autoMergeCleanFastForwards } from "../workspace-auto-merge";
+import { reapOrphanedWorktrees } from "../workspace-orphans";
+import { getLifecycleManager } from "../lifecycle-manager";
+import { applyCommandToRecipe } from "../recipe-runner";
+import {
+  emitAgentRemoved,
+  emitAgentStatus,
+  emitMessageClaimReleased,
+  emitMessageExpired,
+  emitOrchestratorStatus,
+  emitPoolBindingChanged,
+  emitTaskChanged,
+} from "../sse";
+import { pruneExpiredTokenRecords } from "../token-db";
+import { reapTransientAgents } from "../services/transient-agent-reaper";
+import { resumeRateLimitedAgents } from "../services/rate-limit-resume";
+import { MERGE_PAUSE_MAINTENANCE_JOB } from "../merge-pause-maintenance";
+import {
+  DB_MAINTENANCE_INTERVAL_MS,
+  DB_VACUUM_EVERY,
+  DAY_MS,
+  ORPHAN_REAPER_INTERVAL_MS,
+  OUTBOX_RETENTION_MS,
+  TOKEN_RECORD_RETENTION_SECONDS,
+  WORKSPACE_AUTO_MERGE_INTERVAL_MS,
+  WORKSPACE_GC_INTERVAL_MS,
+  WORKSPACE_ORPHAN_REAPER_INTERVAL_MS,
+  CONFLICT_SCAN_INTERVAL_MS,
+  teamReapIntervalMs,
+} from "./constants";
+import { emitCommand } from "./events";
+import { reapOrphanedSessions } from "./orphaned-sessions";
+import { reapZeroMemberTeams } from "./teams";
+import { scanWorkspaceConflicts, workspaceGC } from "./workspaces";
+import type { MaintenanceJobDefinition } from "./types";
+
+let dbMaintenanceRuns = 0;
+
+export const LEGACY_REAPER_JOB_IDS = [
+  "claim-cleanup",
+  "task-orphan-release",
+  "queued-message-expiration",
+  "command-expiration",
+  "artifact-sweep",
+  "stale-agent-reaper",
+  "orchestrator-reaper",
+  "offline-agent-prune",
+  "pool-binding-reconcile",
+];
+
+export const definitions: MaintenanceJobDefinition[] = [
+  {
+    id: "claim-cleanup",
+    title: "Claim cleanup",
+    description: "Release expired message and task claims.",
+    intervalMs: REAP_INTERVAL_MS,
+    runOnStart: true,
+    handler() {
+      const released = releaseExpiredClaims();
+      for (const id of released.messageIds) emitMessageClaimReleased(id);
+      for (const task of released.tasks) emitTaskChanged(task, "task.updated");
+      return {
+        releasedMessageIds: released.messageIds,
+        releasedTaskIds: released.tasks.map((task) => task.id),
+      };
+    },
+  },
+  MERGE_PAUSE_MAINTENANCE_JOB,
+  {
+    id: "task-orphan-release",
+    title: "Orphaned task release",
+    description: "Release active tasks owned by agents that are no longer online.",
+    intervalMs: REAP_INTERVAL_MS,
+    runOnStart: true,
+    handler() {
+      const tasks = releaseOrphanedTasks();
+      for (const task of tasks) emitTaskChanged(task, "task.updated");
+      return { releasedOrphanedTaskIds: tasks.map((task) => task.id) };
+    },
+  },
+  {
+    id: "queued-message-expiration",
+    title: "Queued message expiration",
+    description: "Expire queued messages that exceeded their max age.",
+    intervalMs: REAP_INTERVAL_MS,
+    runOnStart: true,
+    handler() {
+      const messages = expireQueuedMessages();
+      for (const message of messages) emitMessageExpired(message);
+      return { expiredQueuedMessageIds: messages.map((message) => message.id) };
+    },
+  },
+  {
+    id: "command-expiration",
+    title: "Command expiration",
+    description: "Timeout active commands past their lease.",
+    intervalMs: REAP_INTERVAL_MS,
+    runOnStart: true,
+    handler() {
+      const commands = expireCommands();
+      for (const command of commands) {
+        applyCommandToRecipe(command);
+        emitCommand(command);
+      }
+      return { expiredCommandIds: commands.map((command) => command.id) };
+    },
+  },
+  {
+    id: "bus-agent-expiration",
+    title: "Bus agent expiration",
+    description: "Expire stale live bus attachments and release associated orphan work.",
+    intervalMs: REAP_INTERVAL_MS,
+    runOnStart: true,
+    handler() {
+      const expired = expireStaleBusAgents();
+      for (const task of expired.orphanedTasks) emitTaskChanged(task, "task.updated");
+      return {
+        expiredBusAgentIds: expired.agentIds,
+        releasedOrphanedTaskIds: expired.orphanedTasks.map((task) => task.id),
+      };
+    },
+  },
+  {
+    id: "stale-agent-reaper",
+    title: "Stale agent reaper",
+    description: "Mark agents offline when heartbeats are too old.",
+    intervalMs: REAP_INTERVAL_MS,
+    runOnStart: true,
+    handler() {
+      const reapedAgentIds = reapStaleAgents(STALE_TTL_MS);
+      for (const id of reapedAgentIds) {
+        emitAgentStatus(id);
+        getLifecycleManager().onAgentDisappeared(id);
+        notifyAgentOffline(id, "heartbeat lost");
+        createActivityEvent({
+          clientId: "server-agent-" + id + "-heartbeat-lost-" + Date.now(),
+          kind: "state",
+          title: "Heartbeat lost",
+          body: "Agent marked offline",
+          meta: id,
+          icon: "ti-heart-off",
+          view: "chat",
+          agentId: id,
+          metadata: { source: "server", maintenanceJobId: "stale-agent-reaper" },
+        });
+      }
+      return { reapedAgentIds };
+    },
+  },
+  {
+    id: "offline-agent-prune",
+    title: "Offline agent prune",
+    description: "Delete long-offline provider agents and release their claims.",
+    intervalMs: REAP_INTERVAL_MS,
+    runOnStart: false,
+    handler() {
+      const prunedAgentIds = pruneOfflineAgents(OFFLINE_PRUNE_MS);
+      for (const id of prunedAgentIds) emitAgentRemoved(id);
+      return { prunedAgentIds };
+    },
+  },
+  {
+    id: "orphaned-session-reaper",
+    title: "Orphaned session reaper",
+    description: "Stop spawned sessions whose relay agent is offline/gone but whose process the orchestrator still reports running, after a grace period for self-heal.",
+    intervalMs: ORPHAN_REAPER_INTERVAL_MS,
+    runOnStart: false,
+    handler: reapOrphanedSessions,
+  },
+  { id: "transient-agent-reaper", title: "Transient agent reaper", description: "Cleanly shut down transient spawned agents once they are idle and any isolated branch work has landed.", intervalMs: REAP_INTERVAL_MS, runOnStart: false, handler: reapTransientAgents },
+  { id: "rate-limit-resume", title: "Rate-limit resume", description: "Auto-resume agents held on a provider usage/rate-limit stall once their reset window has passed (#286).", intervalMs: REAP_INTERVAL_MS, runOnStart: false, handler: resumeRateLimitedAgents },
+  {
+    id: "team-reap",
+    title: "Team lifecycle close-out",
+    description: "Dissolve active teams that have had zero live members for the configured grace window.",
+    intervalMs: teamReapIntervalMs(),
+    runOnStart: false,
+    handler: reapZeroMemberTeams,
+  },
+  {
+    id: "orchestrator-reaper",
+    title: "Orchestrator reaper",
+    description: "Mark stale orchestrator registrations offline.",
+    intervalMs: REAP_INTERVAL_MS,
+    runOnStart: true,
+    handler() {
+      const reapedOrchestratorIds = reapStaleOrchestrators();
+      for (const id of reapedOrchestratorIds) emitOrchestratorStatus(id);
+      return { reapedOrchestratorIds };
+    },
+  },
+  {
+    id: "pool-binding-reconcile",
+    title: "Pool binding reconcile",
+    description: "Reassign pool channel bindings when current assignees are unavailable.",
+    intervalMs: REAP_INTERVAL_MS,
+    runOnStart: true,
+    handler() {
+      const changes = evaluatePoolBindings();
+      for (const change of changes) emitPoolBindingChanged(change.bindingId, change.channelId, change.previousAgentId, change.newAgentId);
+      return { poolBindingChanges: changes };
+    },
+  },
+  {
+    id: "old-message-prune",
+    title: "Old message prune",
+    description: "Delete messages outside the configured retention window.",
+    intervalMs: DAY_MS,
+    runOnStart: false,
+    handler() {
+      const retentionDays = Number(process.env.RETENTION_DAYS) || 30;
+      return { prunedMessages: pruneOldMessages(retentionDays * DAY_MS) };
+    },
+  },
+  {
+    id: "db-maintenance",
+    title: "Database maintenance",
+    description: "Refresh planner stats (ANALYZE + optimize), truncate the WAL, and periodically VACUUM to reclaim space.",
+    intervalMs: DB_MAINTENANCE_INTERVAL_MS,
+    runOnStart: false,
+    timeoutMs: 5 * 60 * 1000,
+    handler() {
+      dbMaintenanceRuns += 1;
+      const vacuum = DB_VACUUM_EVERY > 0 && dbMaintenanceRuns % DB_VACUUM_EVERY === 0;
+      return runDbMaintenance({ vacuum });
+    },
+  },
+  {
+    id: "bus-outbox-prune",
+    title: "Bus outbox prune",
+    description: "Prune retained bus outbox events after replay retention.",
+    intervalMs: 5 * 60 * 1000,
+    runOnStart: false,
+    handler() {
+      return { prunedOutboxEvents: pruneOutbox(OUTBOX_RETENTION_MS) };
+    },
+  },
+  {
+    id: "artifact-sweep",
+    title: "Artifact sweep",
+    description: "Delete expired or unlinked artifacts and their local blobs.",
+    intervalMs: 60 * 60 * 1000,
+    runOnStart: false,
+    timeoutMs: 2 * 60 * 1000,
+    async handler() {
+      const swept = sweepArtifacts();
+      const failedBlobDeletes: string[] = [];
+      for (const blob of swept.blobs) {
+        try {
+          await getArtifactStorage().delete(blob.storageUri);
+        } catch {
+          failedBlobDeletes.push(blob.digest);
+        }
+      }
+      return {
+        expiredArtifactIds: swept.artifactIds,
+        sweptBlobDigests: swept.blobs.map((blob) => blob.digest),
+        failedBlobDeletes,
+      };
+    },
+  },
+  {
+    id: "token-record-prune",
+    title: "Token record prune",
+    description: "Delete expired or revoked token records after retention.",
+    intervalMs: 60 * 60 * 1000,
+    runOnStart: false,
+    handler() {
+      const prunedTokenJtis = pruneExpiredTokenRecords({ retentionSeconds: TOKEN_RECORD_RETENTION_SECONDS });
+      return { prunedTokenJtis };
+    },
+  },
+  {
+    id: "workspace-orphan-sweep",
+    title: "Workspace orphan sweep",
+    description: "Delete shared-mode workspace occupancy rows whose owner agent is offline or gone.",
+    intervalMs: REAP_INTERVAL_MS,
+    runOnStart: true,
+    handler() {
+      const prunedSharedWorkspaceIds = pruneOrphanedSharedWorkspaces();
+      return { prunedSharedWorkspaceIds };
+    },
+  },
+  {
+    id: "workspace-conflict-scan",
+    title: "Workspace conflict scan",
+    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: true,
+    timeoutMs: 60 * 1000,
+    handler: scanWorkspaceConflicts,
+  },
+  {
+    id: "workspace-auto-merge",
+    title: "Workspace auto-merge",
+    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: true,
+    timeoutMs: 60 * 1000,
+    handler: autoMergeCleanFastForwards,
+  },
+  {
+    id: "workspace-gc",
+    title: "Workspace GC",
+    description: "Prune terminal workspace rows past retention, auto-abandon stale review_requested worktrees, and trigger git worktree prune on orchestrators.",
+    intervalMs: WORKSPACE_GC_INTERVAL_MS,
+    runOnStart: false,
+    timeoutMs: 60 * 1000,
+    handler: workspaceGC,
+  },
+  {
+    id: "workspace-orphan-reaper",
+    title: "Workspace orphan reaper",
+    description: "Reconcile disk<->DB: reap orphaned worktrees whose work has landed (or is empty), flag orphans holding un-landed work as needs-attention instead of deleting, and report rows whose worktree vanished. git worktree prune can't do this - it no-ops while the directory still exists.",
+    intervalMs: WORKSPACE_ORPHAN_REAPER_INTERVAL_MS,
+    runOnStart: true,
+    timeoutMs: 2 * 60 * 1000,
+    handler: reapOrphanedWorktrees,
+  },
+];

package/src/maintenance/orphaned-sessions.ts

@@ -0,0 +1,86 @@
+import { createCommand } from "../commands-db";
+import { createActivityEvent, getAgent, listOrchestrators } from "../db";
+import { emitRelayEvent } from "../events";
+import { orphanGraceMs, orphanReapCooldownMs, orphanReapEnabled } from "./constants";
+
+const orphanTracker = new Map<string, { firstOrphanedAt: number; lastReapAt?: number }>();
+
+export function resetOrphanSessionTrackerForTests(): void {
+  orphanTracker.clear();
+}
+
+// Stop orphaned spawned sessions: process reported alive by the orchestrator, but
+// the relay agent is offline/pruned and self-heal has had its chance.
+export function reapOrphanedSessions(): Record<string, unknown> {
+  const now = Date.now();
+  const grace = orphanGraceMs();
+  const cooldown = orphanReapCooldownMs();
+  const reapEnabled = orphanReapEnabled();
+  const seen = new Set<string>();
+  const reaped: string[] = [];
+  let orphaned = 0;
+
+  for (const orch of listOrchestrators()) {
+    if (orch.status !== "online") continue;
+    for (const agent of orch.managedAgents) {
+      const sessionId = agent.spawnRequestId || agent.tmuxSession || agent.sessionName || agent.agentId;
+      if (!sessionId) continue;
+      const key = `${orch.id}:${sessionId}`;
+      const relayAgent = agent.agentId ? getAgent(agent.agentId) : null;
+      const isOrphan = !relayAgent || relayAgent.status === "offline";
+      if (!isOrphan) { orphanTracker.delete(key); continue; }
+      seen.add(key);
+      orphaned++;
+      const entry = orphanTracker.get(key) ?? { firstOrphanedAt: now };
+      orphanTracker.set(key, entry);
+      if (now - entry.firstOrphanedAt < grace) continue;
+      if (!reapEnabled) continue;
+      if (entry.lastReapAt && now - entry.lastReapAt < cooldown) continue;
+      entry.lastReapAt = now;
+      const command = createCommand({
+        type: "agent.shutdown",
+        source: "system",
+        target: orch.agentId,
+        correlationId: agent.spawnRequestId,
+        params: {
+          action: "shutdown",
+          agentId: agent.agentId,
+          spawnRequestId: agent.spawnRequestId,
+          sessionName: agent.sessionName,
+          tmuxSession: agent.tmuxSession,
+          policyName: agent.policyName,
+          graceful: false,
+          timeoutMs: 10_000,
+          reason: "orphaned-session-reaper",
+          requestedBy: "orphaned-session-reaper",
+          requestedAt: now,
+          orchestratorId: orch.id,
+        },
+      });
+      emitRelayEvent({ type: "command.requested", source: "system", subject: command.id, data: { command } });
+      createActivityEvent({
+        clientId: `orphaned-session-reaper-${key}-${now}`,
+        kind: "state",
+        title: "Orphaned session reaped",
+        body: `${agent.label ?? agent.agentId ?? sessionId}: process still running on ${orch.id}, but its relay agent has been offline > ${Math.round(grace / 60000)}m and did not self-heal - stopping it`,
+        meta: agent.label ?? agent.agentId ?? sessionId,
+        icon: "ti-ghost",
+        view: "orchestrators",
+        agentId: agent.agentId || undefined,
+        metadata: {
+          source: "server",
+          maintenanceJobId: "orphaned-session-reaper",
+          orchestratorId: orch.id,
+          agentId: agent.agentId,
+          spawnRequestId: agent.spawnRequestId,
+          tmuxSession: agent.tmuxSession,
+          commandId: command.id,
+          orphanAgeMs: now - entry.firstOrphanedAt,
+        },
+      });
+      reaped.push(key);
+    }
+  }
+  for (const key of orphanTracker.keys()) if (!seen.has(key)) orphanTracker.delete(key);
+  return { orphaned, reaped, tracked: orphanTracker.size, reapEnabled };
+}