agent-relay-server 0.60.0 → 0.60.1

package/src/db/merge-lease.ts

@@ -12,7 +12,7 @@ import {
   parseRuntimePackage,
   type RuntimeContracts,
 } from "../contracts";
-import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_MERGE_LEASE_MS } from "../config";
+import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_MERGE_LEASE_MS, MAIN_MERGE_PAUSE_TTL_MS } from "../config";
 import { matchAgents } from "../agent-ref";
 import { getDb } from "./connection.ts";
 import type {
@@ -158,3 +158,97 @@ export function releaseMergeLease(opts: { repoRoot?: string; commandId?: string;
   return getDb().query(`DELETE FROM workspace_merge_leases WHERE ${where.join(" AND ")}`).run(...params).changes > 0;
 }
 
+// --- Per-target merge pause lease (issue #448) -----------------------------
+
+export interface MergePauseRecord {
+  id: string;
+  repoRoot: string;
+  baseRef: string;
+  holder: string;
+  reason?: string;
+  createdAt: number;
+  updatedAt: number;
+  expiresAt: number;
+}
+
+export function rowToMergePause(row: any): MergePauseRecord {
+  return {
+    id: row.id,
+    repoRoot: row.repo_root,
+    baseRef: row.base_ref,
+    holder: row.holder,
+    reason: row.reason ?? undefined,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+    expiresAt: row.expires_at,
+  };
+}
+
+export function getMergePause(id: string): MergePauseRecord | null {
+  const row = getDb().query("SELECT * FROM workspace_merge_pauses WHERE id = ?").get(id) as any;
+  return row ? rowToMergePause(row) : null;
+}
+
+export function getActiveMergePause(repoRoot: string, baseRef = "main", now: number = Date.now()): MergePauseRecord | null {
+  const row = getDb().query("SELECT * FROM workspace_merge_pauses WHERE repo_root = ? AND base_ref = ? AND expires_at > ?")
+    .get(repoRoot, baseRef, now) as any;
+  return row ? rowToMergePause(row) : null;
+}
+
+export function listMergePauses(): MergePauseRecord[] {
+  return (getDb().query("SELECT * FROM workspace_merge_pauses ORDER BY updated_at DESC").all() as any[]).map(rowToMergePause);
+}
+
+export function acquireMergePause(input: {
+  repoRoot: string;
+  baseRef?: string;
+  holder: string;
+  reason?: string;
+  ttlMs?: number;
+  now?: number;
+}): { ok: true; pause: MergePauseRecord } | { ok: false; pause: MergePauseRecord } {
+  return getDb().transaction(() => {
+    const now = input.now ?? Date.now();
+    const baseRef = input.baseRef || "main";
+    const existing = getActiveMergePause(input.repoRoot, baseRef, now);
+    if (existing) return { ok: false as const, pause: existing };
+    const id = randomUUID();
+    const expiresAt = now + (input.ttlMs ?? MAIN_MERGE_PAUSE_TTL_MS);
+    getDb().query(`
+      INSERT INTO workspace_merge_pauses (id, repo_root, base_ref, holder, reason, created_at, updated_at, expires_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(repo_root, base_ref) DO UPDATE SET
+        id = excluded.id,
+        holder = excluded.holder,
+        reason = excluded.reason,
+        created_at = excluded.created_at,
+        updated_at = excluded.updated_at,
+        expires_at = excluded.expires_at
+    `).run(id, input.repoRoot, baseRef, input.holder, input.reason ?? null, now, now, expiresAt);
+    return { ok: true as const, pause: getMergePause(id)! };
+  })();
+}
+
+export function renewMergePause(id: string, ttlMs: number = MAIN_MERGE_PAUSE_TTL_MS, now: number = Date.now()): MergePauseRecord | null {
+  const current = getMergePause(id);
+  if (!current || current.expiresAt <= now) return null;
+  getDb().query("UPDATE workspace_merge_pauses SET updated_at = ?, expires_at = ? WHERE id = ?").run(now, now + ttlMs, id);
+  return getMergePause(id);
+}
+
+export function releaseMergePause(opts: { id?: string; repoRoot?: string; baseRef?: string }): boolean {
+  const where: string[] = [];
+  const params: string[] = [];
+  if (opts.id) { where.push("id = ?"); params.push(opts.id); }
+  if (opts.repoRoot) { where.push("repo_root = ?"); params.push(opts.repoRoot); }
+  if (opts.baseRef) { where.push("base_ref = ?"); params.push(opts.baseRef); }
+  if (!where.length) return false;
+  return getDb().query(`DELETE FROM workspace_merge_pauses WHERE ${where.join(" AND ")}`).run(...params).changes > 0;
+}
+
+export function releaseExpiredMergePauses(now: number = Date.now()): string[] {
+  const expired = getDb().query("SELECT id FROM workspace_merge_pauses WHERE expires_at <= ?").all(now) as Array<{ id: string }>;
+  if (!expired.length) return [];
+  getDb().query("DELETE FROM workspace_merge_pauses WHERE expires_at <= ?").run(now);
+  return expired.map((r) => r.id);
+}

package/src/db/migrations.ts

@@ -117,6 +117,21 @@ export function applyMigrations(): void {
   normalizeExistingMessageReactions();
 
   // Migrations
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS workspace_merge_pauses (
+      id TEXT PRIMARY KEY,
+      repo_root TEXT NOT NULL,
+      base_ref TEXT NOT NULL,
+      holder TEXT NOT NULL,
+      reason TEXT,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      expires_at INTEGER NOT NULL,
+      UNIQUE(repo_root, base_ref)
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_workspace_merge_pauses_expires ON workspace_merge_pauses(expires_at)");
+
   const cols = getDb().query("PRAGMA table_info(messages)").all() as any[];
   const colNames = cols.map((c: any) => c.name);
   if (!colNames.includes("thread_id")) {

package/src/maintenance.ts

@@ -13,6 +13,7 @@ import {
   expireQueuedMessages,
   getAgent,
   getDb,
+  getActiveMergePause,
   getRepoSteward,
   getWorkspace,
   listActiveTeams,
@@ -64,6 +65,7 @@ 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;
@@ -197,6 +199,7 @@ const definitions: MaintenanceJobDefinition[] = [
       };
     },
   },
+  MERGE_PAUSE_MAINTENANCE_JOB,
   {
     id: "task-orphan-release",
     title: "Orphaned task release",
@@ -659,9 +662,8 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
   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[] = [];
+  const flagged: string[] = [], cleared: string[] = [], merged: string[] = [], notifiedStewards: string[] = [], prRecycled: string[] = [];
   const reviewerArmed: string[] = [], reviewerChangesRequested: string[] = [], relayPrMerged: string[] = [], relayPrWaiting: string[] = [];
-  const prRecycled: string[] = [];
 
   for (const ws of candidates) {
     const orch = orchestrators.find((candidate) => workspacePathWithinBase(ws.sourceCwd, candidate.baseDir));
@@ -708,6 +710,7 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
     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;
@@ -786,16 +789,13 @@ async function autoMergeCleanFastForwards(): Promise<Record<string, unknown>> {
   );
   const stewardEnabled = getStewardConfig().enabled;
   const merged: string[] = [];
-  const heldByLease: string[] = [];
-  const heldByClaim: string[] = [];
-  const heldAwaitingApproval: string[] = [];
-  const leftForSteward: string[] = [];
-  const wokeStewards: string[] = [];
+  const heldByLease: string[] = [], heldByClaim: string[] = [], heldByPause: string[] = [], heldAwaitingApproval: string[] = [], leftForSteward: string[] = [], wokeStewards: string[] = [];
 
   for (const ws of candidates) {
     if (isAwaitingReviewerApproval(ws)) { heldAwaitingApproval.push(ws.id); continue; }
     // A claimed workspace is being validated by a steward — don't race it (#208).
     if (workspaceActiveClaim(ws)) { heldByClaim.push(ws.id); continue; }
+    if (getActiveMergePause(ws.repoRoot, ws.baseRef ?? "main")) { heldByPause.push(ws.id); continue; }
     const orch = orchestrators.find((candidate) => workspacePathWithinBase(ws.sourceCwd, candidate.baseDir));
     if (!orch?.apiUrl) continue;
     const preview = await fetchHostMergePreview(orch.apiUrl, ws);
@@ -857,7 +857,7 @@ async function autoMergeCleanFastForwards(): Promise<Record<string, unknown>> {
     });
   }
 
-  return { scanned: candidates.length, merged, heldByLease, heldByClaim, heldAwaitingApproval, leftForSteward, wokeStewards };
+  return { scanned: candidates.length, merged, heldByLease, heldByClaim, heldByPause, heldAwaitingApproval, leftForSteward, wokeStewards };
 }
 
 // Route a GC notification, swallowing failures (a stale/missing/misconfigured target must never

package/src/mcp-merge-tools.ts

@@ -0,0 +1,66 @@
+import { ValidationError } from "./db";
+import { McpNotFoundError } from "./mcp-errors";
+import { authContextFromMcp } from "./services/auth-context";
+import { listAutoMergePauses, pauseAutoMerge, renewAutoMergePause, resumeAutoMerge } from "./services/merge-pause";
+import { cleanString } from "./validation";
+
+export const MERGE_TOOLS = [
+  { name: "relay_merge_pauses", description: "List active auto-merge pauses. These are repo/base-level holds that make the workspace auto-merge job yield during release or build critical sections.", requiredScopes: ["command:read"], inputSchema: { type: "object", properties: {}, additionalProperties: false } },
+  {
+    name: "relay_merge_pause",
+    description: "Pause workspace auto-merge for one repo/base pair with a TTL. Existing active pause for the same target is returned as a conflict instead of replacing its holder.",
+    requiredScopes: ["command:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        repoRoot: { type: "string", description: "Repository root whose auto-merge should pause." },
+        baseRef: { type: "string", description: "Base branch/ref to pause (default main)." },
+        ttlMs: { type: "integer", minimum: 1, description: "Pause TTL in milliseconds. Defaults to the server's merge-pause TTL." },
+        reason: { type: "string" },
+        holder: { type: "string", description: "Optional human-readable holder. Defaults to the authenticated caller." },
+      },
+      required: ["repoRoot"],
+      additionalProperties: false,
+    },
+  },
+  { name: "relay_merge_renew", description: "Renew an active auto-merge pause by id, extending its TTL from now.", requiredScopes: ["command:write"], inputSchema: { type: "object", properties: { id: { type: "string" }, ttlMs: { type: "integer", minimum: 1 } }, required: ["id"], additionalProperties: false } },
+  { name: "relay_merge_resume", description: "Release an auto-merge pause by id, or by repoRoot/baseRef.", requiredScopes: ["command:write"], inputSchema: { type: "object", properties: { id: { type: "string" }, repoRoot: { type: "string" }, baseRef: { type: "string", description: "Base branch/ref (default main when repoRoot is used)." } }, additionalProperties: false } },
+] satisfies Array<{ name: string; description: string; requiredScopes: string[]; inputSchema: Record<string, unknown> }>;
+
+type McpAuthLike = Parameters<typeof authContextFromMcp>[0];
+
+export function relayMergeTool(auth: McpAuthLike, name: string, args: Record<string, unknown>): Record<string, unknown> {
+  const ctx = authContextFromMcp(auth);
+  if (name === "relay_merge_pauses") {
+    const pauses = listAutoMergePauses();
+    return { pauses, count: pauses.length };
+  }
+  if (name === "relay_merge_pause") {
+    const result = pauseAutoMerge({
+      repoRoot: cleanString(args.repoRoot, "repoRoot", { required: true, max: 1024 })!,
+      baseRef: cleanString(args.baseRef, "baseRef", { max: 240 }),
+      holder: cleanString(args.holder, "holder", { max: 240 }) ?? ctx.callerAgentId ?? ctx.actor.id,
+      reason: cleanString(args.reason, "reason", { max: 1000 }),
+      ttlMs: optionalPositiveInt(args.ttlMs, "ttlMs"),
+    });
+    return result.ok ? { ok: true, pause: result.pause } : { ok: false, error: "merge target already paused", pause: result.pause };
+  }
+  if (name === "relay_merge_renew") {
+    const pause = renewAutoMergePause(cleanString(args.id, "id", { required: true, max: 120 })!, optionalPositiveInt(args.ttlMs, "ttlMs"));
+    if (!pause) throw new McpNotFoundError("merge pause not found or expired");
+    return { pause };
+  }
+  if (name === "relay_merge_resume") {
+    const id = cleanString(args.id, "id", { max: 120 });
+    const repoRoot = cleanString(args.repoRoot, "repoRoot", { max: 1024 });
+    if (!id && !repoRoot) throw new ValidationError("id or repoRoot required");
+    return { released: resumeAutoMerge({ id, repoRoot, baseRef: cleanString(args.baseRef, "baseRef", { max: 240 }) }) };
+  }
+  throw new ValidationError(`unknown tool: ${name}`);
+}
+
+function optionalPositiveInt(value: unknown, field: string): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) throw new ValidationError(`${field} must be a positive integer`);
+  return value;
+}

package/src/mcp.ts

@@ -50,7 +50,7 @@ import { PLAN_TOOLS, relayPlanTool } from "./mcp-plan-tools";
 import { TEAM_TOOLS, relayTeamTool } from "./mcp-team-tools";
 import { BLACKBOARD_TOOLS, relayBlackboardTool } from "./mcp-blackboard-tools";
 import { PROJECT_TOOLS, relayProjectTool } from "./mcp-project-tools";
-import { NOTIFICATION_SUBSCRIPTION_TOOLS, relayNotificationSubscriptionTool } from "./mcp-notification-subscription-tools";
+import { NOTIFICATION_SUBSCRIPTION_TOOLS, relayNotificationSubscriptionTool } from "./mcp-notification-subscription-tools"; import { MERGE_TOOLS, relayMergeTool } from "./mcp-merge-tools";
 import { PROJECT_INSTRUCTION_POLICY_NAMES, parseProjectInstructions } from "./project-instructions";
 import { AGENT_ACTION_TOOL, relayAgentAction } from "./mcp-agent-action";
 import type { ActivityKind, AgentLifecycle, ArtifactKind, ArtifactSensitivity, AttachmentRef, Command, SendMessageInput, Message, SpawnApprovalMode, SpawnProvider, WorkspaceAutoMergePolicy, WorkspaceMergeStrategy, WorkspaceMode, WorkspaceRecord } from "./types";
@@ -460,7 +460,7 @@ const TOOLS: ToolDefinition[] = [
       additionalProperties: false,
     },
   },
-  ...TEAM_TOOLS,
+  ...MERGE_TOOLS, ...TEAM_TOOLS,
   ...PLAN_TOOLS,
   ...BLACKBOARD_TOOLS,
   ...PROJECT_TOOLS,
@@ -577,7 +577,7 @@ async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<s
     else if (name === "relay_workspace_claim") result = relayWorkspaceMutation(auth, "claim", args);
     else if (name === "relay_workspace_release") result = relayWorkspaceMutation(auth, "release-claim", args);
     else if (name === "relay_workspace_land") result = relayWorkspaceMutation(auth, "merge", args);
-    else if (name.startsWith("relay_team_")) result = await relayTeamTool(auth, name, args);
+    else if (name.startsWith("relay_merge_")) result = relayMergeTool(auth, name, args); else if (name.startsWith("relay_team_")) result = await relayTeamTool(auth, name, args);
     else if (name.startsWith("relay_plan_")) result = relayPlanTool(auth, name, args);
     else if (name.startsWith("relay_blackboard_")) result = relayBlackboardTool(auth, name, args);
     else if (name.startsWith("relay_project_")) result = relayProjectTool(auth, name, args);
@@ -1043,7 +1043,6 @@ function relayWorkspaceMutation(auth: McpAuthContext, action: WorkspaceAction, a
   return payload;
 }
 
-
 function payloadWithAttachments(
   payload: Record<string, unknown> | undefined,
   attachments: AttachmentRef[] | undefined,

package/src/merge-pause-maintenance.ts

@@ -0,0 +1,13 @@
+import { REAP_INTERVAL_MS } from "./config";
+import { releaseExpiredMergePauses } from "./db";
+
+export const MERGE_PAUSE_MAINTENANCE_JOB = {
+  id: "merge-pause-expiration",
+  title: "Merge pause expiration",
+  description: "Release expired repo/base auto-merge pauses.",
+  intervalMs: REAP_INTERVAL_MS,
+  runOnStart: true,
+  handler() {
+    return { releasedMergePauseIds: releaseExpiredMergePauses() };
+  },
+};

package/src/routes/agent-sessions.ts

@@ -1,6 +1,6 @@
 // Auto-split from routes.ts (#299). Domain: agent-sessions.
 import { RELAY_TOKEN_HEADER, isRecord } from "agent-relay-sdk";
-import { VALID_AGENT_ACTIONS, agentControlActionIcon, auditEvent, authAuditMetadata, authorizeRoute, dashboardAttribution, emitCommand, error, json, metaString, parseBody, spawnRequestId, type AgentControlAction, type Handler } from "./_shared";
+import { VALID_AGENT_ACTIONS, agentControlActionIcon, auditEvent, authAuditMetadata, authorizeRoute, cleanAttachmentRefs, dashboardAttribution, emitCommand, error, json, metaString, parseBody, spawnRequestId, type AgentControlAction, type Handler } from "./_shared";
 import { ValidationError, getAgent, getAgentTimeline, getOrchestrator, markReady, mergeAgentMeta, sendMessage } from "../db";
 import { buildManagedSpawnParams } from "../managed-policy";
 import { buildSpawnCommand, generateSpawnRequestId, resolveSpawnModelParams } from "../spawn-command";
@@ -306,6 +306,7 @@ export const postAgentPrompt: Handler = async (req, params) => {
   try {
     if (!isRecord(parsed.body)) return error("body required");
     const body = cleanString(parsed.body.body, "body", { required: true, max: 100_000 })!;
+    const attachments = cleanAttachmentRefs(parsed.body.attachments ?? parsed.body.artifacts, "attachments");
     const agent = getAgent(params.id!);
     if (!agent) return error("agent not found", 404);
     if (agent.status === "offline") return error("agent is offline", 422);
@@ -319,12 +320,13 @@ export const postAgentPrompt: Handler = async (req, params) => {
       to: agent.id,
       kind: "session",
       body,
+      ...(attachments ? { payload: { attachments } } : {}),
     });
     const command = createCommand({
       type: "prompt.inject",
       source: "dashboard",
       target: agent.id,
-      params: { body, messageId: message.id },
+      params: { body, messageId: message.id, ...(attachments ? { attachments } : {}) },
     });
     emitCommand(command);
     emitNewMessage(message);

package/src/routes/commands.ts

@@ -315,6 +315,26 @@ export const patchCommand: Handler = async (req, params) => {
         });
       }
     }
+    if (command.type === "workspace.pr-refresh") {
+      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.prRefreshed === true) {
+        patchWorkspaceMetadata(workspaceId, {
+          prRefreshCommandId: command.id,
+          prRefreshedAt: Date.now(),
+          prRefreshResult: command.result,
+          prRefreshError: undefined,
+          prRefreshFailedAt: undefined,
+        });
+      } else if (workspaceId && (command.status === "failed" || command.status === "timed_out" || command.status === "rejected" || command.status === "canceled")) {
+        patchWorkspaceMetadata(workspaceId, {
+          prRefreshCommandId: command.id,
+          prRefreshError: command.error ?? "PR branch refresh failed",
+          prRefreshFailedAt: Date.now(),
+          prRefreshResult: 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/index.ts

@@ -35,6 +35,7 @@ import { getTaskById, getTaskEvents, getTasks, patchTaskStatus, postClaimTask, p
 import { getMyTeamRoute, getTeamOutcomesRoute, getTeamsRoute, postMyTeamDissolveRoute, putMyTeamBriefRoute } from "./teams";
 import { postTeamDissolveByIdRoute } from "./teams";
 import { deleteTeamTemplateRoute, getTeamTemplateRoute, getTeamTemplatesRoute, postTeamTemplateRoute, putTeamTemplateRoute } from "./team-templates";
+import { getMergePauseById, getMergePauses, postMergePause, postMergePauseRenew, postMergePauseResume } from "./merges";
 import { postMcp } from "../mcp";
 import { postOrchestratorBootstrap, postOrchestratorBootstrapExchange } from "./orchestrator-bootstrap";
 
@@ -139,6 +140,12 @@ const routes: Route[] = [
   route("POST", "/api/workspaces/:id/actions", postWorkspaceAction),
   route("DELETE", "/api/workspaces/:id", deleteWorkspaceById),
 
+  route("GET", "/api/merges/pauses", getMergePauses),
+  route("POST", "/api/merges/pause", postMergePause),
+  route("POST", "/api/merges/resume", postMergePauseResume),
+  route("POST", "/api/merges/renew", postMergePauseRenew),
+  route("GET", "/api/merges/pauses/:id", getMergePauseById),
+
   route("POST", "/api/system/broadcast", postSystemBroadcast),
   route("GET", "/api/teams", getTeamsRoute),
   route("GET", "/api/teams/outcomes", getTeamOutcomesRoute),

package/src/routes/merges.ts

@@ -0,0 +1,95 @@
+// Auto-merge coordination routes. Generic pause/resume primitive for callers
+// that need Relay's auto-merge sweep to defer a target briefly (#448).
+import { isRecord } from "agent-relay-sdk";
+import { ValidationError } from "../db";
+import { getAutoMergePause, listAutoMergePauses, pauseAutoMerge, renewAutoMergePause, resumeAutoMerge } from "../services/merge-pause";
+import { cleanString } from "../validation";
+import { authAuditMetadata, authorizeRoute, error, json, parseBody, type Handler } from "./_shared";
+
+function cleanTtlMs(value: unknown): number | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+    throw new ValidationError("ttlMs must be a positive integer");
+  }
+  return value;
+}
+
+function actorFromRequest(req: Request): string {
+  const audit = authAuditMetadata(req);
+  const auth = isRecord(audit.auth) ? audit.auth : undefined;
+  return typeof auth?.sub === "string" ? auth.sub
+    : typeof auth?.name === "string" ? auth.name
+    : "root";
+}
+
+export const getMergePauses: Handler = (req) => {
+  const denied = authorizeRoute(req, { scope: "command:read" });
+  if (denied) return denied;
+  return json({ pauses: listAutoMergePauses() });
+};
+
+export const postMergePause: Handler = async (req) => {
+  const denied = authorizeRoute(req, { scope: "command:write" });
+  if (denied) return denied;
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) return error("body required");
+    const repoRoot = cleanString(parsed.body.repoRoot, "repoRoot", { required: true, max: 1000 })!;
+    const baseRef = cleanString(parsed.body.baseRef, "baseRef", { max: 240 }) ?? "main";
+    const holder = cleanString(parsed.body.holder, "holder", { max: 240 }) ?? actorFromRequest(req);
+    const reason = cleanString(parsed.body.reason, "reason", { max: 500 });
+    const ttlMs = cleanTtlMs(parsed.body.ttlMs);
+    const result = pauseAutoMerge({ repoRoot, baseRef, holder, reason, ttlMs });
+    if (!result.ok) {
+      return json({ error: "merge target already paused", pause: result.pause }, 409);
+    }
+    return json({ pause: result.pause }, 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const postMergePauseRenew: Handler = async (req) => {
+  const denied = authorizeRoute(req, { scope: "command:write" });
+  if (denied) return denied;
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) return error("body required");
+    const id = cleanString(parsed.body.id, "id", { required: true, max: 120 })!;
+    const ttlMs = cleanTtlMs(parsed.body.ttlMs);
+    const pause = renewAutoMergePause(id, ttlMs);
+    return pause ? json({ pause }) : error("merge pause not found or expired", 404);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const postMergePauseResume: Handler = async (req) => {
+  const denied = authorizeRoute(req, { scope: "command:write" });
+  if (denied) return denied;
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) return error("body required");
+    const id = cleanString(parsed.body.id, "id", { max: 120 });
+    const repoRoot = cleanString(parsed.body.repoRoot, "repoRoot", { max: 1000 });
+    const baseRef = cleanString(parsed.body.baseRef, "baseRef", { max: 240 });
+    if (!id && !repoRoot) return error("id or repoRoot required", 400);
+    const released = resumeAutoMerge(id ? { id } : { repoRoot: repoRoot!, baseRef: baseRef ?? "main" });
+    return json({ released });
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const getMergePauseById: Handler = (req, params) => {
+  const denied = authorizeRoute(req, { scope: "command:read" });
+  if (denied) return denied;
+  const pause = getAutoMergePause(params.id!);
+  return pause ? json(pause) : error("merge pause not found", 404);
+};

package/src/security.ts

@@ -195,6 +195,7 @@ export function requiredScopeFor(method: string, pathname: string): string | nul
   if (pathname.startsWith("/api/inbox")) return method === "GET" ? "message:read" : "message:send";
   if (pathname.startsWith("/api/messages")) return method === "GET" ? "message:read" : "message:send";
   if (pathname.startsWith("/api/commands")) return method === "GET" ? "command:read" : "command:write";
+  if (pathname.startsWith("/api/merges")) return method === "GET" ? "command:read" : "command:write";
   if (pathname.startsWith("/api/workspaces")) return method === "GET" ? "agent:read" : "agent:write";
   if (pathname.startsWith("/api/agent-profiles")) return method === "GET" ? "agent:read" : "agent:write";
   if (pathname.startsWith("/api/recipes")) return method === "GET" ? "recipes:read" : "recipes:write";
@@ -254,6 +255,7 @@ export function requiredComponentScopeFor(method: string, pathname: string): str
     if (method === "GET") return "command:read";
     return "command:write";
   }
+  if (pathname.startsWith("/api/merges")) return method === "GET" ? "command:read" : "command:write";
   if (pathname.startsWith("/api/workspaces")) return method === "GET" ? "agent:read" : "agent:write";
   if (pathname.startsWith("/api/tokens") || pathname.startsWith("/api/token-profiles")) return method === "GET" ? "token:read" : "token:write";
   if (pathname.startsWith("/api/maintenance")) return "system:admin";

package/src/services/merge-pause.ts

@@ -0,0 +1,37 @@
+import {
+  acquireMergePause as acquireMergePauseRow,
+  getMergePause,
+  listMergePauses,
+  releaseMergePause as releaseMergePauseRow,
+  renewMergePause as renewMergePauseRow,
+  type MergePauseRecord,
+} from "../db";
+
+export type { MergePauseRecord };
+
+export function listAutoMergePauses(): MergePauseRecord[] {
+  return listMergePauses();
+}
+
+export function getAutoMergePause(id: string): MergePauseRecord | null {
+  return getMergePause(id);
+}
+
+export function pauseAutoMerge(input: {
+  repoRoot: string;
+  baseRef?: string;
+  holder: string;
+  reason?: string;
+  ttlMs?: number;
+  now?: number;
+}): { ok: true; pause: MergePauseRecord } | { ok: false; pause: MergePauseRecord } {
+  return acquireMergePauseRow(input);
+}
+
+export function renewAutoMergePause(id: string, ttlMs?: number): MergePauseRecord | null {
+  return renewMergePauseRow(id, ttlMs);
+}
+
+export function resumeAutoMerge(input: { id?: string; repoRoot?: string; baseRef?: string }): boolean {
+  return releaseMergePauseRow(input);
+}

package/src/services/spawn-agent.ts

@@ -208,19 +208,21 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   // resolves it. Absent (graceful) when the cwd is inside no registered root.
   const callerProject = resolveProjectForCwd(resolvedCwd);
 
-  // #409 — instruction projection (default OFF). Only when the caller opts in AND the
-  // spawn cwd resolves to a project do we compose a knowledge preamble and PREPEND it to
-  // systemPromptAppend. Absent flag / no project / empty block ⇒ systemPromptAppend is
-  // left exactly as the caller passed it, so the spawn command stays byte-identical.
-  let systemPromptAppend = input.systemPromptAppend;
+  // #409 + #463 — one composition home for the prompt material handed to providers.
+  // Precedence is: project preamble, profile system, profile append entries, then
+  // transient caller/fork context. Spawns without profile/project material stay
+  // byte-identical to the caller-provided systemPromptAppend.
+  const appendBlocks: string[] = [];
   if (input.projectInstructions && callerProject) {
     const block = composeProjectInstructions(callerProject, {
       ...(input.projectInstructions.policy ? { policy: input.projectInstructions.policy } : {}),
     });
-    if (block) {
-      systemPromptAppend = systemPromptAppend ? `${block}\n\n${systemPromptAppend}` : block;
-    }
+    if (block.trim()) appendBlocks.push(block);
   }
+  if (agentProfile?.instructions.system?.trim()) appendBlocks.push(agentProfile.instructions.system);
+  appendBlocks.push(...(agentProfile?.instructions.append.filter((entry) => entry.trim()) ?? []));
+  if (input.systemPromptAppend?.trim()) appendBlocks.push(input.systemPromptAppend);
+  const systemPromptAppend = appendBlocks.length ? appendBlocks.join("\n\n") : input.systemPromptAppend;
 
   // Child runner token. `agentInitiated` (set whenever an agent is the caller) forces a
   // non-spawn-capable child (no grandchildren); `spawnedBy` stamps authoritative lineage the