agent-relay-server 0.39.0 → 0.41.0

package/src/mcp.ts

@@ -24,6 +24,7 @@ import {
   listAgents,
   listWorkspaces,
   ownedIsolatedWorkspace,
+  searchContinuationArchives,
   searchAgents,
   type AgentSearchFilter,
   type AgentSearchSort,
@@ -35,6 +36,7 @@ import {
 import { resolveCallerAgentId, type DeliveryReceipt } from "./agent-ref";
 import { ShutdownAuthError, ShutdownTargetError, shutdownAgent } from "./services/shutdown-agent";
 import { emitRelayEvent } from "./events";
+import { compactAndResume } from "./self-resume";
 import {
   getComponentAuth,
   getIntegrationAuth,
@@ -246,6 +248,52 @@ const TOOLS: ToolDefinition[] = [
       additionalProperties: false,
     },
   },
+  {
+    name: "relay_compact_and_resume",
+    description: "Self-resume this same agent in place: Relay stores the continuation envelope, compacts or clears context, then resumes with the relay-built continuation. Use at a clean seam after a context advisory.",
+    requiredScopes: ["command:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        workingState: { type: "string", description: "Current replaceable working state for the next generation." },
+        ruledOut: {
+          type: "array",
+          items: {
+            oneOf: [
+              { type: "string" },
+              {
+                type: "object",
+                properties: {
+                  ruledOut: { type: "string" },
+                  why: { type: "string" },
+                },
+                required: ["ruledOut"],
+                additionalProperties: false,
+              },
+            ],
+          },
+        },
+        mode: { type: "string", enum: ["clear-inject", "native"] },
+        objective: { type: "string", description: "Seed-only objective. Used only on the first call when no spawn prompt seeded the envelope." },
+      },
+      required: ["workingState"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_recall",
+    description: "Recall this same agent's archived pre-compaction transcript segments by keyword/BM25 search. Self-only: caller identity comes from the MCP token; no agentId parameter is accepted.",
+    requiredScopes: ["memory:read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Keyword query over archived compact/clear segments." },
+        limit: { type: "integer", minimum: 1, maximum: 20 },
+      },
+      required: ["query"],
+      additionalProperties: false,
+    },
+  },
   {
     name: "relay_spawn_agent",
     description: "Spawn a long-living provider agent through Relay's orchestrator, optionally handing it its first task via `prompt` in the same call. Defaults to your own host (override with orchestratorId) and returns the resolved agent id once it registers. Gated: requires the command:spawn scope, granted only to agents whose profile sets maxSpawnedAgents>0, up to that live-children quota. Spawned agents cannot themselves spawn (no grandchildren).",
@@ -506,6 +554,8 @@ async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<s
     else if (name === "relay_agent_status") result = relayAgentStatus(args);
     else if (name === "relay_find_agents") result = relayFindAgents(auth, args);
     else if (name === "relay_whoami") result = relayWhoami(auth);
+    else if (name === "relay_compact_and_resume") result = relayCompactAndResume(auth, args);
+    else if (name === "relay_recall") result = relayRecall(auth, args);
     else if (name === "relay_spawn_agent") result = await relaySpawnAgent(auth, args);
     else if (name === "relay_spawn_targets") result = relaySpawnTargets(auth);
     else if (name === "relay_shutdown_agent") result = relayShutdownAgent(auth, args);
@@ -557,6 +607,33 @@ function relayWhoami(auth: McpAuthContext): Record<string, unknown> {
   };
 }
 
+function relayCompactAndResume(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
+  const agentId = callerAgentId(auth);
+  if (!agentId) throw new McpAuthError("relay_compact_and_resume requires a single caller agent identity");
+  return compactAndResume({
+    agentId,
+    workingState: stringField(args.workingState, "workingState", { required: true, maxBytes: MAX_BODY_BYTES }),
+    ruledOut: args.ruledOut,
+    mode: optionalEnum(args.mode, "mode", ["clear-inject", "native"] as const),
+    objective: optionalString(args.objective, "objective", 64_000),
+  }) as unknown as Record<string, unknown>;
+}
+
+function relayRecall(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
+  const agentId = callerAgentId(auth);
+  if (!agentId) throw new McpAuthError("relay_recall requires a single caller agent identity");
+  const matches = searchContinuationArchives({
+    agentId,
+    query: stringField(args.query, "query", { required: true, max: 1000 }),
+    limit: optionalPositiveInt(args.limit, "limit"),
+  });
+  return {
+    query: stringField(args.query, "query", { required: true, max: 1000 }),
+    matches,
+    count: matches.length,
+  };
+}
+
 // MCP transport adapter over the shared send service (epic #342). The service owns from-resolution
 // (token identity via ctx.callerAgentId), reply routing, target resolution + the converged
 // store-ahead policy, authorization, persistence, and emit. This adapter only builds the input,

package/src/routes/commands.ts

@@ -15,6 +15,7 @@ import { ServiceAuthError } from "../services/errors";
 import { notifyBranchLanded } from "../branch-landed";
 import { notifyAgentSpawnFailed } from "../agent-lifecycle-events";
 import { handleReviewerMergeResult } from "../reviewer-pipeline";
+import { enqueueContinuationInjectionAfterClear } from "../self-resume";
 import { type Command, type CommandStatus, type CreateCommandInput, type WorkspaceStatus } from "../types";
 
 const VALID_COMMAND_STATUSES = ["pending", "accepted", "running", "succeeded", "failed", "timed_out", "rejected", "canceled"] as const;
@@ -173,6 +174,7 @@ export const patchCommand: Handler = async (req, params) => {
       // hook so a command that landed in the wrong context gets flagged.
       getCompactionWatch().noteCommandSucceeded(command.type, command.id, command.target);
     }
+    enqueueContinuationInjectionAfterClear(command);
     if (command.type === "workspace.cleanup" && command.status === "succeeded" && isRecord(command.result)) {
       const workspaceId = cleanString(command.result.workspaceId, "result.workspaceId", { max: 160 });
       if (workspaceId) {
@@ -285,6 +287,28 @@ export const patchCommand: Handler = async (req, params) => {
         }
       }
     }
+    if (command.type === "workspace.pr-merge") {
+      const resultWorkspaceId = isRecord(command.result) ? cleanString(command.result.workspaceId, "result.workspaceId", { max: 160 }) : undefined;
+      const workspaceId = resultWorkspaceId ?? command.correlationId;
+      if (workspaceId && command.status === "succeeded" && isRecord(command.result) && command.result.relayMerged === true) {
+        patchWorkspaceMetadata(workspaceId, {
+          relayMerged: true,
+          relayMergeCommandId: command.id,
+          relayMergedAt: Date.now(),
+          relayMergeResult: command.result,
+          relayMergeError: undefined,
+          relayMergeFailedAt: undefined,
+        });
+      } else if (workspaceId && (command.status === "failed" || command.status === "timed_out" || command.status === "rejected" || command.status === "canceled")) {
+        patchWorkspaceMetadata(workspaceId, {
+          relayMerged: false,
+          relayMergeCommandId: undefined,
+          relayMergeError: command.error ?? "PR merge failed",
+          relayMergeFailedAt: Date.now(),
+          relayMergeResult: command.result,
+        });
+      }
+    }
     if (command.type === "workspace.deps-refresh" && command.status === "succeeded" && isRecord(command.result)) {
       // Record the outcome on the row without touching status (#51) — observability
       // for the dashboard; the CLI reads the result straight off the command.

package/src/routes/continuation-archives.ts

@@ -0,0 +1,37 @@
+// Auto-split from routes.ts (#299). Domain: continuation archives.
+import { isRecord } from "agent-relay-sdk";
+import { resolveCallerAgentId } from "../agent-ref";
+import { archiveContinuationSegment, appendContinuationArchiveRefs, getAgent, listAgents, ValidationError } from "../db";
+import { getComponentAuth } from "../security";
+import { cleanEpoch, cleanPositiveId, cleanString } from "../validation";
+import { error, json, parseBody, type Handler } from "./_shared";
+
+export const postContinuationArchiveRoute: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  if (!isRecord(parsed.body)) return error("JSON object body required", 400);
+  try {
+    const agentId = cleanString(parsed.body.agentId, "agentId", { required: true, max: 240 })!;
+    const denied = authorizeArchiveWriter(req, agentId);
+    if (denied) return denied;
+    if (!getAgent(agentId)) return error("agent not found", 404);
+    const archive = archiveContinuationSegment({
+      agentId,
+      segment: cleanString(parsed.body.segment, "segment", { required: true, max: 64_000 })!,
+      generation: cleanPositiveId(parsed.body.generation, "generation"),
+      now: cleanEpoch(parsed.body.occurredAt, "occurredAt"),
+    });
+    const envelope = appendContinuationArchiveRefs(agentId, [archive.ref]);
+    return json({ archive, envelope }, 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+function authorizeArchiveWriter(req: Request, agentId: string): Response | null {
+  const component = getComponentAuth(req);
+  if (!component) return null;
+  const caller = resolveCallerAgentId(component.constraints, listAgents);
+  return caller === agentId ? null : error("forbidden", 403);
+}

package/src/routes/index.ts

@@ -20,6 +20,7 @@ import { getApiDocs, getApiSpec } from "./spec";
 import { getChannelBindings, getChannels, getIntegrations, postChannelActivity, postChannelBinding, postChannelEvent, postIntegrationEvent, putIntegrationRegistryRoute } from "./integrations";
 import { getCommandById, getCommands, patchCommand, postCommand } from "./commands";
 import { getConnectorById, getConnectorConfig, getConnectors, postConnectorAction, postConnectorCall, postConnectorRegister, putConnectorConfig } from "./connectors";
+import { postContinuationArchiveRoute } from "./continuation-archives";
 import { getEvents } from "./sse";
 import { getHostDirectories, postAgent, postAgentSpawn, postRouteAdvice } from "./agents-spawn";
 import { getInsightsConfigRoute, getInsightsObservationsRoute, postInsightsObservationRoute, putInsightsConfigRoute } from "./insights";
@@ -170,6 +171,7 @@ const routes: Route[] = [
   route("PUT", "/api/insights/config", putInsightsConfigRoute),
   route("GET", "/api/insights/observations", getInsightsObservationsRoute),
   route("POST", "/api/insights/observations", postInsightsObservationRoute),
+  route("POST", "/api/continuation-archives", postContinuationArchiveRoute),
   route("GET", "/api/config/:namespace", getConfigNamespace),
   route("GET", "/api/config/:namespace/:key/history", getConfigKeyHistory),
   route("GET", "/api/config/:namespace/:key", getConfigKey),

package/src/security.ts

@@ -207,6 +207,7 @@ export function requiredScopeFor(method: string, pathname: string): string | nul
   // Insights config (the feature toggle) stays admin-only via the default; only the
   // mechanical observation feed is writable by lower-privilege callers.
   if (pathname === "/api/insights/observations") return method === "GET" ? "insights:read" : "insights:write";
+  if (pathname === "/api/continuation-archives") return "insights:write";
   if (pathname.startsWith("/api/system/")) return "system:admin";
   return null;
 }
@@ -281,6 +282,7 @@ export function requiredComponentScopeFor(method: string, pathname: string): str
   // below and every observation was 403-dropped — the whole Insights feed stayed empty.
   // Config (the feature toggle) intentionally keeps falling through to system:admin.
   if (pathname === "/api/insights/observations") return method === "GET" ? "insights:read" : "insights:write";
+  if (pathname === "/api/continuation-archives") return "insights:write";
   if (pathname.startsWith("/api/system/")) return "system:admin";
   return "system:admin";
 }

package/src/self-resume-config.ts

@@ -0,0 +1,44 @@
+import { isRecord } from "agent-relay-sdk";
+import { ValidationError } from "./db/connection.ts";
+import type { SelfResumeConfig } from "./types";
+
+export const DEFAULT_SELF_RESUME_CONFIG: SelfResumeConfig = {
+  defaultMode: "clear-inject",
+  budget: {
+    maxGenerations: 8,
+    maxWallClockMs: 24 * 60 * 60 * 1000,
+    maxTokens: 2_000_000,
+  },
+};
+
+const VALID_SELF_RESUME_MODES = ["clear-inject", "native"] as const;
+
+export function validateSelfResumeConfig(value: unknown): SelfResumeConfig {
+  if (!isRecord(value)) throw new ValidationError("self-resume config value must be an object");
+  const budget = isRecord(value.budget) ? value.budget : {};
+  return {
+    defaultMode: value.defaultMode === undefined || value.defaultMode === null
+      ? DEFAULT_SELF_RESUME_CONFIG.defaultMode
+      : cleanMode(value.defaultMode, "defaultMode"),
+    budget: {
+      maxGenerations: cleanPositiveInt(budget.maxGenerations, "budget.maxGenerations", DEFAULT_SELF_RESUME_CONFIG.budget.maxGenerations),
+      maxWallClockMs: cleanPositiveInt(budget.maxWallClockMs, "budget.maxWallClockMs", DEFAULT_SELF_RESUME_CONFIG.budget.maxWallClockMs),
+      maxTokens: cleanPositiveInt(budget.maxTokens, "budget.maxTokens", DEFAULT_SELF_RESUME_CONFIG.budget.maxTokens),
+    },
+  };
+}
+
+function cleanMode(value: unknown, field: string): SelfResumeConfig["defaultMode"] {
+  if (typeof value !== "string" || !VALID_SELF_RESUME_MODES.includes(value as any)) {
+    throw new ValidationError(`${field} must be one of: ${VALID_SELF_RESUME_MODES.join(", ")}`);
+  }
+  return value as SelfResumeConfig["defaultMode"];
+}
+
+function cleanPositiveInt(value: unknown, field: string, fallback: number): number {
+  if (value === undefined || value === null) return fallback;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+    throw new ValidationError(`${field} must be a positive integer`);
+  }
+  return value;
+}

package/src/self-resume.ts

@@ -0,0 +1,232 @@
+import { isRecord } from "agent-relay-sdk";
+import { createCommand, listCommands } from "./commands-db";
+import { emitCommandEvent } from "./command-events";
+import { getSelfResumeConfig } from "./config-store";
+import {
+  archiveContinuationSegment,
+  ensureContinuationEnvelope,
+  getAgent,
+  getContinuationEnvelope,
+  updateContinuationAfterCompact,
+  ValidationError,
+} from "./db";
+import { emitRelayEvent } from "./events";
+import { notifySystemMessage } from "./notify";
+import type { AgentCard, Command, ContinuationEnvelope, ContinuationLedgerEntry, SelfResumeMode } from "./types";
+
+export interface CompactAndResumeInput {
+  agentId: string;
+  workingState: string;
+  ruledOut?: unknown;
+  mode?: SelfResumeMode;
+  objective?: string;
+}
+
+export interface CompactAndResumeResult {
+  ok: boolean;
+  mode: SelfResumeMode;
+  envelope: ContinuationEnvelope;
+  continuation?: string;
+  command: Command;
+  exhausted?: boolean;
+  reason?: string;
+}
+
+const VALID_RESUME_MODES = ["clear-inject", "native"] as const;
+
+export function compactAndResume(input: CompactAndResumeInput): CompactAndResumeResult {
+  const agent = getAgent(input.agentId);
+  if (!agent) throw new ValidationError("agent not found");
+  const config = getSelfResumeConfig();
+  const mode = input.mode ?? config.defaultMode;
+  if (!VALID_RESUME_MODES.includes(mode)) throw new ValidationError(`mode must be one of: ${VALID_RESUME_MODES.join(", ")}`);
+  assertResumeSupported(agent, mode);
+
+  const now = Date.now();
+  const envelope = ensureContinuationEnvelope({
+    agentId: agent.id,
+    objective: input.objective,
+    config,
+    now,
+  });
+  const exhausted = budgetExhaustion(envelope, now);
+  if (exhausted) {
+    const command = createCleanStop(agent, exhausted);
+    notifySelfResumeBudgetExhausted(agent, envelope, exhausted);
+    return { ok: false, mode, envelope, command, exhausted: true, reason: exhausted };
+  }
+
+  const workingState = input.workingState.trim();
+  if (!workingState) throw new ValidationError("workingState required");
+  const generation = envelope.generation + 1;
+  const ledgerEntries = parseRuledOut(input.ruledOut, generation, now);
+  const archive = archiveContinuationSegment({
+    agentId: agent.id,
+    generation,
+    segment: workingState,
+    now,
+  });
+  const updated = updateContinuationAfterCompact({
+    agentId: agent.id,
+    generation,
+    ledgerEntries,
+    workingState,
+    archiveRefs: [archive.ref],
+    spentTokens: typeof agent.context?.tokensUsed === "number" ? agent.context.tokensUsed : 0,
+    now,
+  });
+  const continuation = renderContinuation(updated);
+  const command = mode === "native"
+    ? createNativeCompact(agent.id, generation, continuation)
+    : createClearThenInject(agent.id, generation, continuation);
+  emitCommandEvent(command, "command.requested");
+  return { ok: true, mode, envelope: updated, continuation, command };
+}
+
+export function enqueueContinuationInjectionAfterClear(command: Command): Command | null {
+  if (command.type !== "agent.clearContext" || command.status !== "succeeded") return null;
+  const resume = isRecord(command.params.selfResume) ? command.params.selfResume : undefined;
+  const continuation = typeof resume?.continuation === "string" ? resume.continuation : undefined;
+  if (!continuation) return null;
+  const generation = typeof resume?.generation === "number" ? resume.generation : undefined;
+  const existing = listCommands({ target: command.target, type: "agent.injectContext", limit: 500 })
+    .find((item) => item.correlationId === command.id);
+  if (existing) return null;
+  const inject = createCommand({
+    type: "agent.injectContext",
+    source: "system",
+    target: command.target,
+    correlationId: command.id,
+    params: {
+      reason: "self-resume-continuation",
+      content: continuation,
+      selfResume: {
+        generation,
+        afterClearCommandId: command.id,
+      },
+    },
+  });
+  emitCommandEvent(inject, "command.requested");
+  return inject;
+}
+
+export function renderContinuation(envelope: ContinuationEnvelope): string {
+  const ledger = envelope.ledger.length
+    ? envelope.ledger.map((entry) => `- gen ${entry.gen} @ ${new Date(entry.at).toISOString()}: ${entry.ruledOut}${entry.why ? `; why: ${entry.why}` : ""}`).join("\n")
+    : "- none";
+  return [
+    `You have been resumed by Agent Relay — generation ${envelope.generation}.`,
+    "",
+    "Objective (verbatim, relay-owned):",
+    envelope.objective,
+    "",
+    "Ruled-out ledger (append-only):",
+    ledger,
+    "",
+    "Working state:",
+    envelope.workingState,
+    "",
+    "Archive refs:",
+    envelope.archiveRefs.length ? envelope.archiveRefs.join("\n") : "- none",
+  ].join("\n");
+}
+
+function assertResumeSupported(agent: AgentCard, mode: SelfResumeMode): void {
+  const context = agent.providerCapabilities?.context;
+  const resume = context?.resume ?? (context?.clear && context?.inject ? "clear-inject" : "none");
+  if (resume === "none") throw new ValidationError("self-resume unsupported, fresh-session handoff only");
+  if (mode === "native" && resume !== "native") throw new ValidationError("native self-resume unsupported for this provider");
+  if (mode === "clear-inject" && !(context?.clear && context?.inject)) {
+    throw new ValidationError("clear-inject self-resume unsupported for this provider");
+  }
+}
+
+function budgetExhaustion(envelope: ContinuationEnvelope, now: number): string | null {
+  if (envelope.generation >= envelope.budget.maxGenerations) return "max generations exhausted";
+  if (Math.max(0, now - envelope.createdAt) >= envelope.budget.maxWallClockMs) return "max wall clock exhausted";
+  if (envelope.budget.spent.tokens >= envelope.budget.maxTokens) return "max token budget exhausted";
+  return null;
+}
+
+function createNativeCompact(agentId: string, generation: number, continuation: string): Command {
+  return createCommand({
+    type: "agent.compact",
+    source: "system",
+    target: agentId,
+    params: {
+      reason: "self-resume",
+      instructions: continuation,
+      selfResume: { generation, mode: "native" },
+    },
+  });
+}
+
+function createClearThenInject(agentId: string, generation: number, continuation: string): Command {
+  return createCommand({
+    type: "agent.clearContext",
+    source: "system",
+    target: agentId,
+    params: {
+      reason: "self-resume",
+      selfResume: { generation, mode: "clear-inject", continuation },
+    },
+  });
+}
+
+function createCleanStop(agent: AgentCard, reason: string): Command {
+  const command = createCommand({
+    type: "agent.shutdown",
+    source: "system",
+    target: agent.id,
+    params: {
+      reason: `self-resume budget exhausted: ${reason}`,
+      graceful: true,
+      timeoutMs: 10_000,
+      preserveRegistration: true,
+      selfResume: { exhausted: true },
+    },
+  });
+  emitCommandEvent(command, "command.requested");
+  return command;
+}
+
+function notifySelfResumeBudgetExhausted(agent: AgentCard, envelope: ContinuationEnvelope, reason: string): void {
+  const payload = {
+    kind: "agent.resume_budget_exhausted",
+    agentId: agent.id,
+    parent: agent.spawnedBy,
+    reason,
+    generation: envelope.generation,
+  };
+  emitRelayEvent({ type: "agent.resume_budget_exhausted", source: "server", subject: agent.id, data: payload });
+  if (!agent.spawnedBy) return;
+  notifySystemMessage(agent.spawnedBy, {
+    subject: "Self-resume budget exhausted",
+    body: `Spawned agent \`${agent.id}\` stopped cleanly: ${reason}.`,
+    payload,
+    replyExpected: false,
+  });
+}
+
+function parseRuledOut(value: unknown, generation: number, now: number): ContinuationLedgerEntry[] {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) throw new ValidationError("ruledOut must be an array");
+  return value.map((item, index) => {
+    if (typeof item === "string") return ledgerEntry(item, "", generation, now);
+    if (!isRecord(item)) throw new ValidationError(`ruledOut[${index}] must be a string or object`);
+    const ruledOut = typeof item.ruledOut === "string" ? item.ruledOut.trim() : "";
+    const why = typeof item.why === "string" ? item.why.trim() : "";
+    if (!ruledOut) throw new ValidationError(`ruledOut[${index}].ruledOut required`);
+    return ledgerEntry(ruledOut, why, generation, now);
+  });
+}
+
+function ledgerEntry(ruledOut: string, why: string, generation: number, now: number): ContinuationLedgerEntry {
+  const cleaned = ruledOut.trim();
+  if (!cleaned) throw new ValidationError("ruledOut entries cannot be blank");
+  return { gen: generation, ruledOut: cleaned, why, at: now };
+}
+
+export function continuationForAgent(agentId: string): ContinuationEnvelope | null {
+  return getContinuationEnvelope(agentId);
+}

package/src/services/send-message.ts

@@ -172,6 +172,10 @@ export function sendMessageService(
     } else {
       emitNewMessage(result.message);
     }
+  } else if (result.updated) {
+    // Session-step upsert (#parity): the row changed in place (same DB id). Re-emit so the
+    // dashboard's id-keyed merge replaces the existing step live — no duplicate row.
+    emitNewMessage(result.message);
   }
   return { message: result.message, created: result.created, receipt };
 }

package/src/workspace-pr-completion.ts

@@ -0,0 +1,121 @@
+import { isRecord } from "agent-relay-sdk";
+import { createCommand, getCommand } from "./commands-db";
+import { patchWorkspaceMetadata } from "./db";
+import { handleReviewerPipelineScan, isAwaitingReviewerApproval } from "./reviewer-pipeline";
+import type { Command, WorkspaceAutoMergePolicy, WorkspaceMergePreview, WorkspaceRecord } from "./types";
+
+const ACTIVE_COMMAND_STATUSES = new Set(["pending", "accepted", "running"]);
+const PASSING_CONCLUSIONS = new Set(["SUCCESS", "NEUTRAL", "SKIPPED"]);
+const PASSING_STATES = new Set(["SUCCESS"]);
+const READY_MERGE_STATES = new Set(["CLEAN", "HAS_HOOKS"]);
+
+function relayPrMergeAlreadyHandled(workspace: WorkspaceRecord): boolean {
+  const commandId = text(workspace.metadata.relayMergeCommandId);
+  if (commandId) {
+    const command = getCommand(commandId);
+    if (command && ACTIVE_COMMAND_STATUSES.has(command.status)) return true;
+    if (command?.status === "succeeded" && command.result?.relayMerged === true) return true;
+  }
+  return workspace.metadata.relayMerged === true && !commandId;
+}
+
+function nativeAutoMergeArmed(workspace: WorkspaceRecord): boolean {
+  if (isRecord(workspace.metadata.mergeResult) && workspace.metadata.mergeResult.autoMergeArmed === true) return true;
+  const commandId = text(workspace.metadata.autoMergeArmCommandId);
+  if (!commandId) return false;
+  const command = getCommand(commandId);
+  return command?.status === "succeeded" && command.result?.autoMergeArmed === true;
+}
+
+function prAutoMergePolicy(workspace: WorkspaceRecord, preview: WorkspaceMergePreview): WorkspaceAutoMergePolicy {
+  const commandId = text(workspace.metadata.mergeCommandId);
+  if (commandId) {
+    const command = getCommand(commandId);
+    const autoMerge = text(command?.params.autoMerge);
+    if (autoMerge === "on-green" || autoMerge === "on-approval" || autoMerge === "manual") return autoMerge;
+  }
+  if (workspace.metadata.awaitingApproval === true || (isRecord(workspace.metadata.mergeResult) && workspace.metadata.mergeResult.awaitingApproval === true)) return "on-approval";
+  return "on-green";
+}
+
+function prReadyForRelayMerge(workspace: WorkspaceRecord, preview: WorkspaceMergePreview): { ok: true; policy: WorkspaceAutoMergePolicy } | { ok: false; reason: string; policy?: WorkspaceAutoMergePolicy } {
+  if (preview.strategy !== "pr") return { ok: false, reason: "not-pr-strategy" };
+  if (preview.prMerged === true || preview.prState === "merged") return { ok: false, reason: "already-merged" };
+  if (!preview.prNumber && !preview.prUrl) return { ok: false, reason: "missing-pr" };
+  if (nativeAutoMergeArmed(workspace)) return { ok: false, reason: "native-auto-merge-armed" };
+  if (relayPrMergeAlreadyHandled(workspace)) return { ok: false, reason: "relay-merge-already-dispatched" };
+
+  const policy = prAutoMergePolicy(workspace, preview);
+  if (policy === "manual") return { ok: false, reason: "manual", policy };
+  if (policy === "on-approval" && preview.reviewDecision !== "APPROVED") return { ok: false, reason: "approval-required", policy };
+  if (!prMergeable(preview)) return { ok: false, reason: "not-mergeable", policy };
+  if (!statusChecksGreen(preview.statusCheckRollup)) return { ok: false, reason: "checks-not-green", policy };
+  return { ok: true, policy };
+}
+
+export function preparePrCompletionScan(workspace: WorkspaceRecord, preview: WorkspaceMergePreview, orchestratorAgentId: string): {
+  armCommand?: Command;
+  notifiedOwner?: string;
+  mergeCommand?: Command;
+  waitReason?: string;
+  stop?: boolean;
+} {
+  if (isAwaitingReviewerApproval(workspace)) {
+    const action = handleReviewerPipelineScan(workspace, preview, orchestratorAgentId);
+    if (action.armCommand) return { armCommand: action.armCommand, stop: true };
+    if (action.notifiedOwner) return { notifiedOwner: action.notifiedOwner, stop: true };
+  }
+  const relayPr = prReadyForRelayMerge(workspace, preview);
+  if (relayPr.ok) return { mergeCommand: dispatchRelayPrMergeCommand(workspace, preview, orchestratorAgentId, relayPr.policy), stop: true };
+  return {
+    waitReason: preview.strategy === "pr" && relayPr.reason !== "not-pr-strategy" ? relayPr.reason : undefined,
+    stop: isAwaitingReviewerApproval(workspace),
+  };
+}
+
+function dispatchRelayPrMergeCommand(workspace: WorkspaceRecord, preview: WorkspaceMergePreview, orchestratorAgentId: string, policy: WorkspaceAutoMergePolicy): Command {
+  const now = Date.now();
+  const prNumber = preview.prNumber ?? (typeof workspace.metadata.prNumber === "number" ? workspace.metadata.prNumber : undefined);
+  const prUrl = preview.prUrl ?? text(workspace.metadata.prUrl);
+  const command = createCommand({
+    type: "workspace.pr-merge",
+    source: "system",
+    target: orchestratorAgentId,
+    correlationId: workspace.id,
+    params: {
+      action: "pr-merge", workspaceId: workspace.id, repoRoot: workspace.repoRoot, worktreePath: workspace.worktreePath,
+      branch: workspace.branch, baseRef: workspace.baseRef, prNumber, prUrl, policy,
+      requestedBy: "relay-pr-completion", requestedAt: now,
+    },
+  });
+  patchWorkspaceMetadata(workspace.id, {
+    relayMerged: true, relayMergeCommandId: command.id, relayMergeDispatchedAt: now, relayMergePolicy: policy,
+    relayMergeError: undefined, relayMergeFailedAt: undefined,
+  });
+  return command;
+}
+
+function statusChecksGreen(rollup: unknown): boolean {
+  if (!Array.isArray(rollup) || rollup.length === 0) return false;
+  return rollup.every(statusNodeGreen);
+}
+
+function prMergeable(preview: WorkspaceMergePreview): boolean {
+  const mergeable = text(preview.mergeable)?.toUpperCase();
+  if (mergeable !== "MERGEABLE") return false;
+  const state = text(preview.mergeStateStatus)?.toUpperCase();
+  return state ? READY_MERGE_STATES.has(state) : true;
+}
+
+function statusNodeGreen(node: unknown): boolean {
+  if (!isRecord(node)) return false;
+  const conclusion = text(node.conclusion)?.toUpperCase();
+  if (conclusion) return PASSING_CONCLUSIONS.has(conclusion);
+  const state = text(node.state)?.toUpperCase();
+  if (state) return PASSING_STATES.has(state);
+  return false;
+}
+
+function text(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}