agent-relay-server 0.62.2 → 0.63.0

package/src/maintenance.ts

@@ -1,1099 +1 @@
-import { randomUUID } from "node:crypto";
-import { getArtifactStorage } from "./artifact-storage";
-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 { resolve } from "node:path";
-import {
-  createActivityEvent,
-  clearTeamZeroMembersSince,
-  countLiveTeamMembers,
-  evaluatePoolBindings,
-  expireQueuedMessages,
-  getAgent,
-  getDb,
-  getRepoSteward,
-  getWorkspace,
-  listActiveTeams,
-  listOrchestrators,
-  listWorkspaces,
-  patchWorkspaceMetadata,
-  pruneOfflineAgents,
-  pruneOldMessages,
-  deleteWorkspace,
-  pruneOrphanedSharedWorkspaces,
-  reapStaleAgents,
-  reapStaleOrchestrators,
-  reelectRepoSteward,
-  releaseExpiredClaims,
-  releaseExpiredMergeLeases,
-  releaseOrphanedTasks,
-  runDbMaintenance,
-  setTeamZeroMembersSince,
-  sweepArtifacts,
-  updateWorkspaceStatus,
-} from "./db";
-import type { WorkspaceMergePreview, WorkspaceRecord, WorkspaceStatus } from "./types";
-import { reconcileLandedWorkspace } from "./branch-landed";
-import { preparePrCompletionScan, reconcileLandedPr } from "./workspace-pr-completion";
-import { notifyAgentOffline } from "./agent-lifecycle-events";
-import { reapOrphanedWorktrees } from "./workspace-orphans";
-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";
-import {
-  emitAgentRemoved,
-  emitAgentStatus,
-  emitMessageClaimReleased,
-  emitMessageExpired,
-  emitOrchestratorStatus,
-  emitPoolBindingChanged,
-  emitTaskChanged,
-} from "./sse";
-import { routeNotification, type NotificationType, type NotificationScope } from "./notification-router";
-import { pruneExpiredTokenRecords } from "./token-db";
-import { dissolveTeamById } from "./services/team";
-import { reapTransientAgents, resetTransientTrackerForTests } from "./services/transient-agent-reaper";
-import { resumeRateLimitedAgents, resetRateLimitResumeTrackerForTests } from "./services/rate-limit-resume";
-import { MERGE_PAUSE_MAINTENANCE_JOB } from "./merge-pause-maintenance";
-import type { Command, MaintenanceJob, MaintenanceJobRun } from "./types";
-
-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;
-// #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.
-// Default: every 7th db-maintenance pass (~weekly at the default daily interval).
-const DB_VACUUM_EVERY = Number(process.env.AGENT_RELAY_DB_VACUUM_EVERY) || 7;
-let dbMaintenanceRuns = 0;
-const WORKSPACE_REVIEW_TTL_MS = Number(process.env.AGENT_RELAY_WORKSPACE_REVIEW_TTL_MS) || 3 * DAY_MS;
-const WORKSPACE_GC_INTERVAL_MS = Number(process.env.AGENT_RELAY_WORKSPACE_GC_INTERVAL_MS) || 60 * 60 * 1000;
-// Disk⇄DB orphan reconcile cadence (#244). Runs on start for a boot-time pass,
-// then periodically — orphans accrue slowly (one per crashed/killed session), so
-// a 30-min sweep is plenty without hammering the hosts with probes.
-const WORKSPACE_ORPHAN_REAPER_INTERVAL_MS = Number(process.env.AGENT_RELAY_WORKSPACE_ORPHAN_REAPER_INTERVAL_MS) || 30 * 60 * 1000;
-// Deterministic auto-land (Layer 0): merge clean fast-forwards with no human in
-// the loop. Default on for the seamless workflow; set AGENT_RELAY_WORKSPACE_AUTO_MERGE=0
-// 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;
-// 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
-// agent id, or `broadcast`). Read at call-time so config changes take effect
-// without a restart (issue #157).
-const stewardEscalationMs = () => Number(process.env.AGENT_RELAY_WORKSPACE_STEWARD_ESCALATION_MS) || 60 * 60 * 1000;
-const stewardFallbackTarget = () => (process.env.AGENT_RELAY_WORKSPACE_STEWARD_FALLBACK || "").trim();
-// Statuses that need an owner — a stranded one of these is what escalation rescues.
-// Derived from the shared ready-to-land set (#242) plus `conflict`, so a stranded
-// `ready` worktree (no online steward) escalates to the fallback target instead of
-// rotting silently — same gap that left the original #242 branch parked.
-const STRANDABLE_STATUSES = new Set<WorkspaceStatus>([...READY_TO_LAND_STATUSES, "conflict"]);
-// Live statuses worth scanning. Terminal (cleaned/merged/abandoned) and
-// in-flight (cleanup_requested) states are skipped.
-const CONFLICT_SCAN_STATUSES = new Set<WorkspaceStatus>(["active", "ready", "review_requested", "merge_planned", "conflict"]);
-// In-flight merge statuses that should reconcile to `merged` once the host
-// reports the branch's work has landed in base (squash/cherry-pick, or a merged
-// PR). Excludes active/ready: an agent still working may have landed an early
-// commit while more work is in flight — don't yank its workspace out from under it.
-const LANDED_RECONCILE_STATUSES = new Set<WorkspaceStatus>(["merge_planned", "review_requested", "conflict"]);
-
-// Orphaned-session reaper. A spawned agent's process can outlive its relay
-// presence: the relay agent goes offline/pruned but the orchestrator still
-// reports the session's process running, so it lingers forever (visible under the
-// orchestrator, gone from the Agents panel). Runtime-token self-heal recovers the
-// recoverable ones; this is the backstop that stops the genuinely stuck ones.
-// Conservative by design — a session must be observed continuously orphaned by
-// THIS relay for the grace window before it is reaped, and the tracker is in-memory
-// so a relay restart restarts the clock (giving self-heal first crack every time).
-const ORPHAN_REAPER_INTERVAL_MS = Number(process.env.AGENT_RELAY_ORPHAN_REAPER_INTERVAL_MS) || 5 * 60 * 1000;
-// Read at call-time so changes take effect without a restart (and so tests can tune
-// them). Parsed to allow an explicit 0 (immediate) — `|| default` would reject it.
-const envMsOrDefault = (name: string, fallback: number): number => {
-  const v = Number(process.env[name]);
-  return Number.isFinite(v) && v >= 0 ? v : fallback;
-};
-const orphanGraceMs = () => envMsOrDefault("AGENT_RELAY_ORPHAN_GRACE_MS", 30 * 60 * 1000);
-const orphanReapCooldownMs = () => envMsOrDefault("AGENT_RELAY_ORPHAN_REAP_COOLDOWN_MS", 5 * 60 * 1000);
-const teamReapGraceMs = () => envMsOrDefault("TEAM_REAP_GRACE_MS", 30 * 60 * 1000);
-const teamReapIntervalMs = () => envMsOrDefault("TEAM_REAP_INTERVAL_MS", 5 * 60 * 1000);
-// Set AGENT_RELAY_ORPHAN_REAP=0 to detect + log orphans but never stop them.
-const orphanReapEnabled = () => process.env.AGENT_RELAY_ORPHAN_REAP !== "0";
-// orchestratorId + session identity -> when we first saw it orphaned (and last reaped).
-const orphanTracker = new Map<string, { firstOrphanedAt: number; lastReapAt?: number }>();
-
-export function resetOrphanTrackerForTests(): void { orphanTracker.clear(); resetTransientTrackerForTests(); resetRateLimitResumeTrackerForTests(); }
-
-interface MaintenanceJobDefinition {
-  id: string;
-  title: string;
-  description: string;
-  intervalMs: number;
-  timeoutMs?: number;
-  runOnStart?: boolean;
-  handler: () => Promise<Record<string, unknown>> | Record<string, unknown>;
-}
-
-interface MaintenanceJobRow {
-  id: string;
-  title: string;
-  description: string | null;
-  interval_ms: number;
-  timeout_ms: number;
-  enabled: number;
-  run_on_start: number;
-  last_run_at: number | null;
-  next_run_at: number | null;
-  last_duration_ms: number | null;
-  last_status: string;
-  last_error: string | null;
-  last_result: string | null;
-  consecutive_failures: number;
-  lease_owner: string | null;
-  lease_until: number | null;
-  updated_at: number;
-}
-
-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",
-];
-
-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);
-        // #308 — if a reaped agent was a spawned child, wake its parent: exited (it had become
-        // ready) vs spawn_failed (it never did — crash-loop / onboarding gate). No-op otherwise.
-        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,
-  },
-];
-
-// 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
-// status). Human-set conflicts are never cleared.
-// Stop orphaned spawned sessions: process reported alive by the orchestrator, but
-// the relay agent is offline/pruned and self-heal has had its chance. See the
-// ORPHAN_* notes above. Covers both policy-managed and dashboard/ad-hoc spawns by
-// iterating the orchestrators' reported managedAgents directly.
-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; // can't trust the report or deliver the stop
-    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;
-      // Orphan = orchestrator reports the process running, but no live relay agent.
-      // "stale" is a recent/borderline disconnect — treat as alive and give it time;
-      // it will either recover or progress to "offline" and be caught next pass.
-      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; // let self-heal recover it first
-      if (!reapEnabled) continue; // detect-only mode
-      if (entry.lastReapAt && now - entry.lastReapAt < cooldown) continue; // don't spam shutdowns
-      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);
-    }
-  }
-  // Forget sessions that recovered or are no longer reported, so a future orphaning
-  // of the same session starts a fresh grace window.
-  for (const key of orphanTracker.keys()) if (!seen.has(key)) orphanTracker.delete(key);
-  return { orphaned, reaped, tracked: orphanTracker.size, reapEnabled };
-}
-
-function reapZeroMemberTeams(): Record<string, unknown> {
-  const now = Date.now();
-  const cutoff = now - STALE_TTL_MS;
-  const grace = teamReapGraceMs();
-  const reapedTeamIds: string[] = [];
-  const trackedTeamIds: string[] = [];
-  const clearedTeamIds: string[] = [];
-  let activeTeams = 0;
-  let zeroMemberTeams = 0;
-
-  for (const team of listActiveTeams()) {
-    activeTeams++;
-    const live = countLiveTeamMembers(team.id, cutoff);
-    if (live > 0) {
-      if (team.zeroMembersSince !== undefined) {
-        clearTeamZeroMembersSince(team.id);
-        clearedTeamIds.push(team.id);
-      }
-      continue;
-    }
-
-    zeroMemberTeams++;
-    if (team.zeroMembersSince === undefined) {
-      setTeamZeroMembersSince(team.id, now);
-      trackedTeamIds.push(team.id);
-      continue;
-    }
-    if (now - team.zeroMembersSince < grace) continue;
-
-    const outcomeSummary = `auto-reaped: zero live members for ${grace}ms`;
-    // Leave outcomeStatus null (unknown): an abandoned team is NOT a failed one — its
-    // members went away without an explicit dissolve, which says nothing about success.
-    // Stamping "failed" would skew the #358 outcome analytics. Reason lives in the summary.
-    const dissolved = dissolveTeamById(team.id, { outcomeSummary });
-    createActivityEvent({
-      clientId: `team-reap-${team.id}-${now}`,
-      kind: "state",
-      title: "Team auto-reaped",
-      body: outcomeSummary,
-      meta: team.id,
-      icon: "ti-users-minus",
-      view: "teams",
-      agentId: dissolved.coordinatorId,
-      metadata: {
-        source: "server",
-        maintenanceJobId: "team-reap",
-        teamId: team.id,
-        zeroMembersSince: team.zeroMembersSince,
-        graceMs: grace,
-      },
-    });
-    reapedTeamIds.push(team.id);
-  }
-
-  return { activeTeams, zeroMemberTeams, trackedTeamIds, clearedTeamIds, reapedTeamIds, graceMs: grace };
-}
-
-
-async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
-  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) && CONFLICT_SCAN_STATUSES.has(ws.status),
-  );
-  const flagged: string[] = [], cleared: string[] = [], merged: string[] = [], notifiedStewards: string[] = [], prRecycled: string[] = [];
-  const reviewerArmed: string[] = [], reviewerChangesRequested: string[] = [], relayPrMerged: string[] = [], relayPrWaiting: string[] = [];
-
-  for (const ws of candidates) {
-    const orch = orchestrators.find((candidate) => workspacePathWithinBase(ws.sourceCwd, candidate.baseDir));
-    if (!orch?.apiUrl) continue;
-    // Spend the `gh` PR-state round-trip only on reconcile-eligible rows; active/ready
-    // are excluded from reconcile, so their scan stays git-only (#304).
-    const preview = await fetchHostMergePreview(orch.apiUrl, ws, { checkPr: LANDED_RECONCILE_STATUSES.has(ws.status) });
-    if (!preview || (preview as { available?: false }).available === false) continue;
-    const p = preview as WorkspaceMergePreview;
-    if (p.error || p.missing) continue;
-
-    const meta = ws.metadata as Record<string, unknown>;
-
-    // #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
-    // branch-landed.ts (#304).
-    const landed = p.landed === true || p.prMerged === true;
-    if (landed && LANDED_RECONCILE_STATUSES.has(ws.status)) {
-      // A PR-land merges asynchronously on the remote, outside the relay's land path. For a
-      // LIVE owner that means recycle (land-and-continue, #423); for a gone owner, finalize
-      // terminal `merged` (#304). `reconcileLandedPr` owns that split — see workspace-pr-completion.
-      const outcome = reconcileLandedPr(ws, p);
-      if (outcome.kind === "recycle") { emitCommand(outcome.command); prRecycled.push(ws.id); continue; }
-      if (outcome.kind === "wait") { relayPrWaiting.push(`${ws.id}:${outcome.reason}`); continue; }
-      reconcileLandedWorkspace(ws, p);
-      merged.push(ws.id);
-      continue;
-    }
-
-    const prAction = preparePrCompletionScan(ws, p, orch.agentId);
-    if (prAction.armCommand) { emitCommand(prAction.armCommand); reviewerArmed.push(ws.id); continue; }
-    if (prAction.notifiedOwner) { reviewerChangesRequested.push(ws.id); continue; }
-    if (prAction.refreshCommand) { emitCommand(prAction.refreshCommand); continue; }
-    if (prAction.mergeCommand) { emitCommand(prAction.mergeCommand); relayPrMerged.push(ws.id); continue; }
-    if (prAction.waitReason) relayPrWaiting.push(`${ws.id}:${prAction.waitReason}`);
-    if (prAction.stop) continue;
-
-    // Past here we act on the conflict signal — skip when the host couldn't assess it
-    // (undefined): never flag/clear a conflict on incomplete data.
-    if (p.conflict === undefined) continue;
-
-    if (p.conflict === true && ws.status !== "conflict") {
-      updateWorkspaceStatus(ws.id, "conflict", {
-        autoConflict: true,
-        preConflictStatus: ws.status,
-        conflictAhead: p.ahead,
-        conflictBehind: p.behind,
-        conflictBaseRef: p.baseRef,
-        conflictDetectedAt: Date.now(),
-      });
-      flagged.push(ws.id);
-      createActivityEvent({
-        clientId: "server-workspace-" + ws.id + "-conflict-" + Date.now(),
-        kind: "state",
-        title: "Merge conflict detected",
-        body: `${ws.branch ?? ws.id} can no longer merge cleanly into ${p.baseRef ?? "base"}`,
-        meta: ws.branch ?? ws.id,
-        icon: "ti-alert-triangle",
-        view: "orchestrators",
-        metadata: { source: "server", maintenanceJobId: "workspace-conflict-scan", workspaceId: ws.id, ahead: p.ahead, behind: p.behind },
-      });
-      // Hand the conflict to a steward so it gets resolved instead of rotting
-      // until merge time. Once-per-onset (we only enter this branch on the
-      // active→conflict transition). When managed stewards are enabled, wake the
-      // auto-provisioned per-repo steward agent (#167); otherwise fall back to the
-      // legacy direct ping of the elected steward agent.
-      if (getStewardConfig().enabled) {
-        const woke = wakeRepoSteward(getWorkspace(ws.id) ?? ws, "conflict");
-        if (woke) notifiedStewards.push(woke);
-      } else if (ws.stewardAgentId) {
-        try {
-          // Obligation (ttl null by type default): a conflict handoff must reach the steward.
-          routeNotification({
-            type: "workspace.conflict",
-            scope: { workspaceId: ws.id, repoRoot: ws.repoRoot },
-            recipients: [ws.stewardAgentId],
-            message: {
-              subject: "Workspace merge conflict",
-              body: `Workspace \`${ws.branch ?? ws.id}\` in ${ws.repoRoot} can no longer merge cleanly into ${p.baseRef ?? "base"} (${p.ahead ?? "?"} ahead, ${p.behind ?? "?"} behind). As repo steward, please coordinate resolution.`,
-              payload: { kind: "workspace.conflict", workspaceId: ws.id, repoRoot: ws.repoRoot, branch: ws.branch, baseRef: p.baseRef, ahead: p.ahead, behind: p.behind },
-            },
-          });
-          notifiedStewards.push(ws.stewardAgentId);
-        } catch {
-          // Steward unregistered/stale — the activity event still records it.
-        }
-      }
-    } else if (p.conflict === false && ws.status === "conflict" && meta.autoConflict === true) {
-      const prior = typeof meta.preConflictStatus === "string" && meta.preConflictStatus !== "conflict"
-        ? meta.preConflictStatus as WorkspaceStatus
-        : "active";
-      updateWorkspaceStatus(ws.id, prior, { autoConflict: false, conflictClearedAt: Date.now() });
-      cleared.push(ws.id);
-    }
-  }
-
-  return { scanned: candidates.length, flagged, cleared, merged, prRecycled, notifiedStewards, reviewerArmed, reviewerChangesRequested, relayPrMerged, relayPrWaiting };
-}
-
-// 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.
-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;
-  }
-}
-
-async function workspaceGC(): Promise<Record<string, unknown>> {
-  const now = Date.now();
-  const cutoff = now - WORKSPACE_RETENTION_MS;
-  const reviewCutoff = now - WORKSPACE_REVIEW_TTL_MS;
-
-  // 0. Free any merge leases whose holder never reported back (orchestrator died
-  // mid-merge). The lease TTL is the safety net; this just reclaims them eagerly.
-  const releasedLeaseRepos = releaseExpiredMergeLeases(now);
-
-  // 1. Prune terminal rows past retention
-  const all = listWorkspaces();
-  const terminalIds: string[] = [];
-  for (const ws of all) {
-    if (TERMINAL_WORKSPACE_STATUSES.has(ws.status) && ws.updatedAt < cutoff) {
-      deleteWorkspace(ws.id);
-      terminalIds.push(ws.id);
-    }
-  }
-
-  // 2. Rescue stranded review_requested/conflict worktrees (issue #157). A
-  // worktree is "stranded" when its steward is gone (all repo agents offline).
-  // Re-elect first — an agent may have rejoined — and hand off to the new
-  // steward; if none can be elected past the TTL, escalate to the fallback
-  // target so it never rots in silence. Bookkeeping uses patchWorkspaceMetadata
-  // (no updated_at bump) so the auto-abandon clock below keeps ticking.
-  const escalatedIds: string[] = [];
-  const reassignedIds: string[] = [];
-  const escalationTargets: string[] = [];
-  const escalationMs = stewardEscalationMs();
-  const fallbackTarget = stewardFallbackTarget();
-  for (const ws of all) {
-    if (!STRANDABLE_STATUSES.has(ws.status) || ws.mode !== "isolated" || !ws.worktreePath) continue;
-    reelectRepoSteward(ws.repoRoot);
-    const fresh = getWorkspace(ws.id);
-    if (!fresh || !STRANDABLE_STATUSES.has(fresh.status)) continue;
-    const meta = fresh.metadata as Record<string, unknown>;
-    const steward = fresh.stewardAgentId;
-    const stewardOnline = Boolean(steward && getAgent(steward) && getAgent(steward)!.status !== "offline");
-    const strandedAt = typeof meta.strandedAt === "number" ? meta.strandedAt : undefined;
-
-    if (stewardOnline) {
-      // An online steward owns it. If it was previously stranded and this
-      // steward hasn't been told, hand it off explicitly, then clear markers.
-      if (strandedAt !== undefined && meta.strandedNotifiedSteward !== steward) {
-        const sent = notifyTarget(
-          "workspace.steward_reassigned",
-          { workspaceId: fresh.id, repoRoot: fresh.repoRoot },
-          steward!,
-          "Workspace stewardship reassigned",
-          `You are now steward for ${fresh.repoRoot}. Workspace \`${fresh.branch ?? fresh.id}\` is ${fresh.status} and was stranded without an online steward — please coordinate ${fresh.status === "conflict" ? "conflict resolution" : "review/merge"}.`,
-          { kind: "workspace.steward-reassigned", workspaceId: fresh.id, repoRoot: fresh.repoRoot, branch: fresh.branch, status: fresh.status },
-        );
-        if (sent) reassignedIds.push(fresh.id);
-      }
-      patchWorkspaceMetadata(fresh.id, { strandedAt: undefined, escalatedAt: undefined, strandedNotifiedSteward: steward });
-      continue;
-    }
-
-    // Stranded: no online steward could be elected.
-    if (strandedAt === undefined) { patchWorkspaceMetadata(fresh.id, { strandedAt: now }); continue; }
-    if (now - strandedAt < escalationMs || meta.escalatedAt) continue;
-    const sent = notifyTarget(
-      "workspace.stranded_escalation",
-      { workspaceId: fresh.id, repoRoot: fresh.repoRoot },
-      fallbackTarget,
-      "Stranded workspace needs an owner",
-      `Workspace \`${fresh.branch ?? fresh.id}\` in ${fresh.repoRoot} is ${fresh.status} with no online steward (all repo agents offline) for ${Math.round((now - strandedAt) / (60 * 60 * 1000))}h. Please coordinate ${fresh.status === "conflict" ? "conflict resolution" : "review/merge"} or clean up the worktree.`,
-      { kind: "workspace.stranded-escalation", workspaceId: fresh.id, repoRoot: fresh.repoRoot, branch: fresh.branch, status: fresh.status, strandedAt },
-    );
-    if (sent) escalationTargets.push(sent);
-    patchWorkspaceMetadata(fresh.id, { escalatedAt: now });
-    escalatedIds.push(fresh.id);
-    createActivityEvent({
-      clientId: `workspace-gc-escalate-${fresh.id}-${now}`,
-      kind: "state",
-      title: "Workspace escalated",
-      body: `${fresh.branch ?? fresh.id} in ${fresh.repoRoot} — stranded ${fresh.status} escalated${fallbackTarget ? ` to ${fallbackTarget}` : " (no fallback configured)"}`,
-      meta: fresh.branch ?? fresh.id,
-      icon: "ti-alert-octagon",
-      view: "orchestrators",
-      metadata: { source: "server", maintenanceJobId: "workspace-gc", workspaceId: fresh.id, fallback: fallbackTarget || null },
-    });
-  }
-
-  // 3. Auto-abandon stale review_requested worktrees
-  const abandonedIds: string[] = [];
-  const notifiedStewards: string[] = [];
-  for (const ws of all) {
-    if (ws.status === "review_requested" && ws.updatedAt < reviewCutoff) {
-      updateWorkspaceStatus(ws.id, "abandoned", { autoAbandoned: true, abandonedReason: "review_requested TTL exceeded", abandonedAt: now });
-      abandonedIds.push(ws.id);
-      // Notify the steward if one exists, else the configured fallback so a
-      // stranded abandon isn't silent (issue #157).
-      const target = ws.stewardAgentId ?? fallbackTarget;
-      const sent = notifyTarget(
-        "workspace.auto_abandoned",
-        { workspaceId: ws.id, repoRoot: ws.repoRoot },
-        target,
-        "Workspace auto-abandoned",
-        `Workspace \`${ws.branch ?? ws.id}\` in ${ws.repoRoot} was auto-abandoned after ${Math.round(WORKSPACE_REVIEW_TTL_MS / DAY_MS)}d without steward action. Run workspace cleanup to reclaim the worktree.`,
-        { kind: "workspace.auto-abandoned", workspaceId: ws.id, repoRoot: ws.repoRoot, branch: ws.branch },
-      );
-      if (sent) notifiedStewards.push(sent);
-      createActivityEvent({
-        clientId: `workspace-gc-abandon-${ws.id}-${now}`,
-        kind: "state",
-        title: "Workspace auto-abandoned",
-        body: `${ws.branch ?? ws.id} in ${ws.repoRoot} — review_requested for ${Math.round((now - ws.updatedAt) / DAY_MS)}d`,
-        meta: ws.branch ?? ws.id,
-        icon: "ti-clock-x",
-        view: "orchestrators",
-        metadata: { source: "server", maintenanceJobId: "workspace-gc", workspaceId: ws.id },
-      });
-    }
-  }
-
-  // 3. Trigger git worktree prune on orchestrators that own isolated workspaces
-  const orchestrators = listOrchestrators().filter((orch) => orch.status === "online" && orch.agentId);
-  const reposWithWorkspaces = new Set(
-    all.filter((ws) => ws.mode === "isolated" && Boolean(ws.worktreePath)).map((ws) => ws.repoRoot),
-  );
-  const pruneCommands: string[] = [];
-  for (const repoRoot of reposWithWorkspaces) {
-    const orch = orchestrators.find((candidate) => workspacePathWithinBase(repoRoot, candidate.baseDir));
-    if (!orch?.agentId) continue;
-    const command = createCommand({
-      type: "workspace.prune",
-      source: "system",
-      target: orch.agentId,
-      params: { repoRoot, requestedBy: "workspace-gc", requestedAt: now },
-    });
-    emitCommand(command);
-    pruneCommands.push(command.id);
-  }
-
-  return {
-    prunedTerminal: terminalIds,
-    autoAbandoned: abandonedIds,
-    notifiedStewards,
-    pruneCommands,
-    releasedLeaseRepos,
-    escalated: escalatedIds,
-    reassigned: reassignedIds,
-    escalationTargets,
-  };
-}
-
-let timer: Timer | null = null;
-
-export function startMaintenanceScheduler(): void {
-  ensureMaintenanceJobs();
-  void runDueMaintenanceJobs();
-  if (timer) return;
-  timer = setInterval(() => void runDueMaintenanceJobs(), SCHEDULER_TICK_MS);
-}
-
-export function listMaintenanceJobs(): MaintenanceJob[] {
-  ensureMaintenanceJobs();
-  const rows = getDb().query("SELECT * FROM maintenance_jobs ORDER BY title COLLATE NOCASE ASC").all() as MaintenanceJobRow[];
-  const now = Date.now();
-  return rows.map((row) => rowToJob(row, now));
-}
-
-export async function runMaintenanceJobNow(id: string): Promise<MaintenanceJobRun> {
-  ensureMaintenanceJobs();
-  const definition = definitions.find((job) => job.id === id);
-  if (!definition) throw new Error("maintenance job not found");
-  return runJob(definition, { force: true });
-}
-
-export async function runLegacyMaintenanceReaper(): Promise<Record<string, unknown>> {
-  const runs = await runMaintenanceJobsNow(LEGACY_REAPER_JOB_IDS);
-  const result = aggregateRunResults(runs);
-  auditMaintenanceReaperRun(result);
-  return result;
-}
-
-async function runMaintenanceJobsNow(ids: string[]): Promise<MaintenanceJobRun[]> {
-  const runs: MaintenanceJobRun[] = [];
-  for (const id of ids) runs.push(await runMaintenanceJobNow(id));
-  return runs;
-}
-
-async function runDueMaintenanceJobs(): Promise<void> {
-  ensureMaintenanceJobs();
-  const now = Date.now();
-  const rows = getDb().query(`
-    SELECT id FROM maintenance_jobs
-    WHERE enabled = 1
-      AND next_run_at IS NOT NULL
-      AND next_run_at <= ?
-      AND (lease_until IS NULL OR lease_until <= ?)
-    ORDER BY next_run_at ASC
-  `).all(now, now) as Array<{ id: string }>;
-  for (const row of rows) {
-    const definition = definitions.find((job) => job.id === row.id);
-    if (definition) void runJob(definition).catch((error) => {
-      console.warn(`maintenance job ${definition.id} failed: ${errMessage(error)}`);
-    });
-  }
-}
-
-function ensureMaintenanceJobs(): void {
-  const db = getDb();
-  const now = Date.now();
-  const stmt = db.query(`
-    INSERT INTO maintenance_jobs (id, title, description, interval_ms, timeout_ms, enabled, run_on_start, next_run_at, updated_at)
-    VALUES (?, ?, ?, ?, ?, 1, ?, ?, ?)
-    ON CONFLICT(id) DO UPDATE SET
-      title = excluded.title,
-      description = excluded.description,
-      interval_ms = excluded.interval_ms,
-      timeout_ms = excluded.timeout_ms,
-      run_on_start = excluded.run_on_start,
-      next_run_at = COALESCE(maintenance_jobs.next_run_at, excluded.next_run_at),
-      updated_at = excluded.updated_at
-  `);
-  for (const definition of definitions) {
-    stmt.run(
-      definition.id,
-      definition.title,
-      definition.description,
-      definition.intervalMs,
-      definition.timeoutMs ?? DEFAULT_TIMEOUT_MS,
-      definition.runOnStart ? 1 : 0,
-      definition.runOnStart ? now : now + definition.intervalMs,
-      now,
-    );
-  }
-}
-
-async function runJob(definition: MaintenanceJobDefinition, options: { force?: boolean } = {}): Promise<MaintenanceJobRun> {
-  const db = getDb();
-  const startedAt = Date.now();
-  const owner = `${process.pid}-${randomUUID()}`;
-  const timeoutMs = definition.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  const leaseUntil = startedAt + timeoutMs + 5_000;
-  const claim = db.query(`
-    UPDATE maintenance_jobs
-    SET lease_owner = ?, lease_until = ?, last_status = 'running', updated_at = ?
-    WHERE id = ?
-      AND enabled = 1
-      AND (lease_until IS NULL OR lease_until <= ?)
-      ${options.force ? "" : "AND (next_run_at IS NULL OR next_run_at <= ?)"}
-  `).run(owner, leaseUntil, startedAt, definition.id, startedAt, ...(options.force ? [] : [startedAt]));
-  if (claim.changes === 0) {
-    const state = listMaintenanceJobs().find((job) => job.id === definition.id);
-    return { id: definition.id, status: "skipped", startedAt, finishedAt: Date.now(), durationMs: 0, result: { reason: "not due or already running", state } };
-  }
-
-  try {
-    const result = await withTimeout(Promise.resolve(definition.handler()), timeoutMs);
-    const finishedAt = Date.now();
-    const durationMs = finishedAt - startedAt;
-    db.query(`
-      UPDATE maintenance_jobs
-      SET last_run_at = ?, next_run_at = ?, last_duration_ms = ?, last_status = 'succeeded',
-          last_error = NULL, last_result = ?, consecutive_failures = 0,
-          lease_owner = NULL, lease_until = NULL, updated_at = ?
-      WHERE id = ?
-    `).run(finishedAt, finishedAt + definition.intervalMs, durationMs, JSON.stringify(result), finishedAt, definition.id);
-    return { id: definition.id, status: "succeeded", startedAt, finishedAt, durationMs, result };
-  } catch (error) {
-    const finishedAt = Date.now();
-    const durationMs = finishedAt - startedAt;
-    const message = errMessage(error);
-    db.query(`
-      UPDATE maintenance_jobs
-      SET last_run_at = ?, next_run_at = ?, last_duration_ms = ?, last_status = 'failed',
-          last_error = ?, consecutive_failures = consecutive_failures + 1,
-          lease_owner = NULL, lease_until = NULL, updated_at = ?
-      WHERE id = ?
-    `).run(finishedAt, finishedAt + definition.intervalMs, durationMs, message, finishedAt, definition.id);
-    return { id: definition.id, status: "failed", startedAt, finishedAt, durationMs, error: message };
-  }
-}
-
-async function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
-  let timeout: Timer | undefined;
-  const timeoutPromise = new Promise<never>((_, reject) => {
-    timeout = setTimeout(() => reject(new Error(`maintenance job timed out after ${timeoutMs}ms`)), timeoutMs);
-  });
-  try {
-    return await Promise.race([promise, timeoutPromise]);
-  } finally {
-    if (timeout) clearTimeout(timeout);
-  }
-}
-
-function rowToJob(row: MaintenanceJobRow, now: number): MaintenanceJob {
-  const leaseUntil = row.lease_until ?? undefined;
-  return {
-    id: row.id,
-    title: row.title,
-    description: row.description ?? undefined,
-    intervalMs: row.interval_ms,
-    timeoutMs: row.timeout_ms,
-    enabled: row.enabled === 1,
-    runOnStart: row.run_on_start === 1,
-    lastRunAt: row.last_run_at ?? undefined,
-    nextRunAt: row.next_run_at ?? undefined,
-    lastDurationMs: row.last_duration_ms ?? undefined,
-    lastStatus: leaseUntil && leaseUntil > now ? "running" : row.last_status as MaintenanceJob["lastStatus"],
-    lastError: row.last_error ?? undefined,
-    lastResult: parseJsonObject(row.last_result),
-    consecutiveFailures: row.consecutive_failures,
-    running: Boolean(leaseUntil && leaseUntil > now),
-    leaseUntil,
-    updatedAt: row.updated_at,
-  };
-}
-
-function aggregateRunResults(runs: MaintenanceJobRun[]): Record<string, unknown> {
-  const aggregate: Record<string, unknown> = { ok: true, runs };
-  for (const run of runs) {
-    if (!run.result) continue;
-    for (const [key, value] of Object.entries(run.result)) {
-      if (Array.isArray(value)) {
-        const current = Array.isArray(aggregate[key]) ? aggregate[key] as unknown[] : [];
-        aggregate[key] = [...current, ...value];
-      } else if (typeof value === "number") {
-        aggregate[key] = Number(aggregate[key] ?? 0) + value;
-      } else if (value !== undefined) {
-        aggregate[key] = value;
-      }
-    }
-  }
-  return aggregate;
-}
-
-function auditMaintenanceReaperRun(result: Record<string, unknown>): void {
-  const reapedAgentIds = Array.isArray(result.reapedAgentIds) ? result.reapedAgentIds : [];
-  const reapedOrchestratorIds = Array.isArray(result.reapedOrchestratorIds) ? result.reapedOrchestratorIds : [];
-  const releasedMessageIds = Array.isArray(result.releasedMessageIds) ? result.releasedMessageIds : [];
-  const releasedTaskIds = Array.isArray(result.releasedTaskIds) ? result.releasedTaskIds : [];
-  const releasedOrphanedTaskIds = Array.isArray(result.releasedOrphanedTaskIds) ? result.releasedOrphanedTaskIds : [];
-  const expiredQueuedMessageIds = Array.isArray(result.expiredQueuedMessageIds) ? result.expiredQueuedMessageIds : [];
-  const expiredCommandIds = Array.isArray(result.expiredCommandIds) ? result.expiredCommandIds : [];
-  const expiredArtifactIds = Array.isArray(result.expiredArtifactIds) ? result.expiredArtifactIds : [];
-  try {
-    createActivityEvent({
-      clientId: "server-maintenance-reaper-" + Date.now(),
-      kind: "state",
-      title: "Maintenance reaper run",
-      body: `${reapedAgentIds.length} stale agent(s), ${reapedOrchestratorIds.length} stale orchestrator(s), ${releasedMessageIds.length} message claim(s), ${releasedTaskIds.length} task claim(s), ${releasedOrphanedTaskIds.length} orphaned task(s), ${expiredQueuedMessageIds.length} queued message(s), ${expiredCommandIds.length} command(s), ${expiredArtifactIds.length} artifact(s)`,
-      icon: "ti-broom",
-      view: "activity",
-      metadata: { source: "server", result },
-    });
-  } catch {}
-}
-
-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 },
-  });
-}
-
-function parseJsonObject(raw: string | null): Record<string, unknown> | undefined {
-  if (!raw) return undefined;
-  try {
-    const value = JSON.parse(raw);
-    return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
-  } catch {
-    return undefined;
-  }
-}
+export * from "./maintenance/index";