agent-relay-server 0.120.1 → 0.120.3

package/src/sse.ts

@@ -1,4 +1,5 @@
 import { getAgent, getOrchestrator, matchingDeliveryAgents, onWorkspaceChange, sendMessageWithResult, setChannelSubscriberProbe } from "./db";
+import { getOldestOutboxCursor, getOutboxCursor, replayEvents, type BusEvent } from "./bus-outbox";
 import { projectAgentStatusData } from "./agent-card-projection";
 import { emitRelayEvent, subscribeRelayEvents, type RelayEvent } from "./events";
 import { messageMatchesAgent, targetMatchesAgent } from "./agent-ref";
@@ -11,20 +12,27 @@ interface Connection {
   agentId: string | null;
   controller: ReadableStreamDefaultController<Uint8Array>;
   keepalive: Timer;
-  // Pending cross-tick backpressure re-check (#971 refinement). Set when a stream
-  // dips below the queue floor during a synchronous fanout; cleared on the deferred
-  // tick once we know whether it drained (healthy) or stayed stuck (stale → drop).
+  queuedBytes: number;
+  // Pending backpressure re-check. Set when a stream crosses the byte floor; cleared
+  // once it drains or is closed after making no progress during the grace interval.
   drainCheck?: Timer;
+  drainCheckQueuedBytes?: number;
 }
 
 const connections = new Map<string, Connection>();
 const encoder = new TextEncoder();
 const SSE_KEEPALIVE_MS = 15_000;
 const SSE_RETRY_MS = 5_000;
-const SSE_MAX_QUEUED_CHUNKS = 128;
+const SSE_MAX_QUEUED_BYTES = 1024 * 1024;
+const SSE_DRAIN_GRACE_MS = 2_000;
 
 subscribeRelayEvents((event) => fanout(event));
 
+function fanoutAgent(agentId: string, cache: Map<string, AgentCard | null>): AgentCard | null {
+  if (!cache.has(agentId)) cache.set(agentId, getAgent(agentId));
+  return cache.get(agentId) ?? null;
+}
+
 // #797 — let the db layer derive outbound-channel liveness from live SSE subscriptions.
 // A channel agent is "subscribed" iff the channels-host daemon holds an open
 // GET /api/events?for=<channelAgentId> stream (createSSEStream stores `for` as agentId).
@@ -36,28 +44,36 @@ export function hasActiveSubscriber(agentId: string): boolean {
 }
 setChannelSubscriberProbe(hasActiveSubscriber);
 
-export function createSSEStream(agentId: string | null): Response {
+export function createSSEStream(agentId: string | null, lastEventId = 0): Response {
   let connId: string;
 
-  const stream = new ReadableStream<Uint8Array>({
-    start(controller) {
-      connId = crypto.randomUUID();
-      const keepalive = setInterval(() => {
-        const conn = connections.get(connId);
-        if (!conn) return;
-        sendEncoded(conn, encoder.encode(": keepalive\n\n"));
-      }, SSE_KEEPALIVE_MS);
-
-      connections.set(connId, { id: connId, agentId, controller, keepalive });
-
-      controller.enqueue(encoder.encode(
-        `retry: ${SSE_RETRY_MS}\nevent: connected\ndata: ${JSON.stringify({ connectionId: connId })}\n\n`
-      ));
+  const stream = new ReadableStream<Uint8Array>(
+    {
+      start(controller) {
+        connId = crypto.randomUUID();
+        const keepalive = setInterval(() => {
+          const conn = connections.get(connId);
+          if (!conn) return;
+          sendEncoded(conn, encoder.encode(": keepalive\n\n"));
+        }, SSE_KEEPALIVE_MS);
+
+        connections.set(connId, { id: connId, agentId, controller, keepalive, queuedBytes: 0 });
+
+        const replay = replayPlan(lastEventId);
+        controller.enqueue(encoder.encode(
+          `retry: ${SSE_RETRY_MS}\nevent: connected\ndata: ${JSON.stringify({ connectionId: connId, replay })}\n\n`
+        ));
+        replayEventsToConnection(connections.get(connId), replay);
+      },
+      cancel() {
+        removeConnection(connId);
+      },
     },
-    cancel() {
-      removeConnection(connId);
+    {
+      highWaterMark: 0,
+      size: (chunk) => chunk?.byteLength ?? 0,
     },
-  });
+  );
 
   return new Response(stream, {
     headers: {
@@ -85,12 +101,19 @@ function closeConnection(id: string) {
   try { conn?.controller.close(); } catch {}
 }
 
-function sseFrame(event: string, data: unknown): Uint8Array {
-  return encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+function sseFrame(event: string, data: unknown, id?: number): Uint8Array {
+  const idLine = id !== undefined ? `id: ${id}\n` : "";
+  return encoder.encode(`${idLine}event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+}
+
+function bufferedBytes(conn: Connection): number {
+  const desiredSize = conn.controller.desiredSize;
+  if (desiredSize === null) return conn.queuedBytes;
+  return Math.max(0, -desiredSize);
 }
 
 function isBackpressured(conn: Connection): boolean {
-  return conn.controller.desiredSize !== null && conn.controller.desiredSize < -SSE_MAX_QUEUED_CHUNKS;
+  return bufferedBytes(conn) >= SSE_MAX_QUEUED_BYTES;
 }
 
 function sendEncoded(conn: Connection, chunk: Uint8Array) {
@@ -101,59 +124,66 @@ function sendEncoded(conn: Connection, chunk: Uint8Array) {
     removeConnection(conn.id);
     return;
   }
-  // #971 — the queue only drains between event-loop ticks, so within a single
-  // synchronous fanout (a batch loop emitting >SSE_MAX_QUEUED_CHUNKS frames)
-  // desiredSize falls on liveness, not staleness. Closing inline here would kill
-  // healthy, actively-read dashboards mid-burst. Instead defer the verdict: mark
-  // the stream and re-check on a later tick, after the runtime has had a chance to
-  // flush to the socket. Recovered → keep it; still stuck across ticks → drop it.
+  conn.queuedBytes = bufferedBytes(conn);
   if (isBackpressured(conn)) scheduleDrainCheck(conn);
 }
 
 function scheduleDrainCheck(conn: Connection) {
   if (conn.drainCheck) return; // one deferred verdict per stream is enough
+  conn.drainCheckQueuedBytes = bufferedBytes(conn);
   conn.drainCheck = setTimeout(() => {
     conn.drainCheck = undefined;
-    // The connection may already have been removed (cancel/close) between ticks —
+    // The connection may already have been removed (cancel/close) during the grace —
     // closeConnection is idempotent, but bail early so we never touch a stale ref.
     if (connections.get(conn.id) !== conn) return;
-    // Drained across the tick → genuinely healthy-but-slow. Stayed backpressured →
-    // genuinely stalled/stale; drop it (the original #971 protection).
+    const queuedBytes = bufferedBytes(conn);
+    conn.queuedBytes = queuedBytes;
+    if (queuedBytes < SSE_MAX_QUEUED_BYTES) {
+      conn.drainCheckQueuedBytes = undefined;
+      return;
+    }
+    const drained = conn.drainCheckQueuedBytes !== undefined && queuedBytes < conn.drainCheckQueuedBytes;
+    conn.drainCheckQueuedBytes = undefined;
+    if (drained) {
+      scheduleDrainCheck(conn);
+      return;
+    }
     if (isBackpressured(conn)) closeConnection(conn.id);
-  }, 0);
+  }, SSE_DRAIN_GRACE_MS);
 }
 
-function send(conn: Connection, event: string, data: unknown) {
-  sendEncoded(conn, sseFrame(event, data));
+function send(conn: Connection, event: string, data: unknown, id?: number) {
+  sendEncoded(conn, sseFrame(event, data, id));
 }
 
 function fanout(event: RelayEvent): void {
   if (event.type === "message.new") {
-    sendNewMessage(event.data as unknown as Message);
+    sendNewMessage(event.data as unknown as Message, event.seq);
     return;
   }
   if (event.type === "task.updated" || event.type === "task.created" || event.type === "task.claimed" || event.type === "task.status") {
-    sendTaskChanged(event.data as unknown as Task, event.type);
+    sendTaskChanged(event.data as unknown as Task, event.type, event.seq);
     return;
   }
-  const chunk = sseFrame(event.type, event.data);
+  const chunk = sseFrame(event.type, event.data, event.seq);
   for (const conn of connections.values()) {
     sendEncoded(conn, chunk);
   }
 }
 
-function sendNewMessage(msg: Message): void {
+function sendNewMessage(msg: Message, seq?: number): void {
   const scopedBroadcastAgentIds = msg.to === "broadcast"
     ? new Set(matchingDeliveryAgents("broadcast", { from: msg.from, channel: msg.channel }).map((agent) => agent.id))
     : null;
-  const chunk = sseFrame("message.new", msg);
+  const chunk = sseFrame("message.new", msg, seq);
+  const agentCache = new Map<string, AgentCard | null>();
   for (const conn of connections.values()) {
     if (!conn.agentId) {
       sendEncoded(conn, chunk);
       continue;
     }
     if (scopedBroadcastAgentIds && !scopedBroadcastAgentIds.has(conn.agentId)) continue;
-    if (!messageMatchesAgent(msg, conn.agentId, getAgent(conn.agentId))) continue;
+    if (!messageMatchesAgent(msg, conn.agentId, fanoutAgent(conn.agentId, agentCache))) continue;
     sendEncoded(conn, chunk);
   }
 }
@@ -261,14 +291,69 @@ export function emitMessageReactionUpdated(msg: Message) {
   emitRelayEvent({ type: "message.reaction_updated", source: "server", subject: String(msg.id), data: msg as unknown as Record<string, unknown> });
 }
 
-function sendTaskChanged(task: Task, eventType = "task.updated"): void {
-  const chunk = sseFrame(eventType, task);
+function sendTaskChanged(task: Task, eventType = "task.updated", seq?: number): void {
+  const chunk = sseFrame(eventType, task, seq);
+  const agentCache = new Map<string, AgentCard | null>();
   for (const conn of connections.values()) {
-    if (conn.agentId && !targetMatchesAgent(task.target, conn.agentId, getAgent(conn.agentId))) continue;
+    if (conn.agentId && !targetMatchesAgent(task.target, conn.agentId, fanoutAgent(conn.agentId, agentCache))) continue;
     sendEncoded(conn, chunk);
   }
 }
 
+interface ReplayPlan {
+  requested: boolean;
+  since: number;
+  available: boolean;
+  gap: boolean;
+}
+
+function replayPlan(lastEventId: number): ReplayPlan {
+  const since = Number.isSafeInteger(lastEventId) && lastEventId > 0 ? lastEventId : 0;
+  if (since === 0) return { requested: false, since: 0, available: false, gap: false };
+  const oldest = getOldestOutboxCursor();
+  const gap = oldest > 0 && oldest > since + 1;
+  return { requested: true, since, available: !gap, gap };
+}
+
+function replayEventsToConnection(conn: Connection | undefined, plan: ReplayPlan): void {
+  if (!conn || !plan.requested) return;
+  if (plan.gap) {
+    send(conn, "replay.gap", { since: plan.since }, getOutboxCursor());
+    return;
+  }
+  const agentCache = new Map<string, AgentCard | null>();
+  for (const event of replayEvents(plan.since)) {
+    sendReplayEvent(conn, outboxToRelayEvent(event), agentCache);
+  }
+}
+
+function sendReplayEvent(conn: Connection, event: RelayEvent, agentCache: Map<string, AgentCard | null>): void {
+  if (event.type === "message.new" && conn.agentId) {
+    const msg = event.data as unknown as Message;
+    if (!messageMatchesAgent(msg, conn.agentId, fanoutAgent(conn.agentId, agentCache))) return;
+    send(conn, "message.new", msg, event.seq);
+    return;
+  }
+  if (event.type.startsWith("task.") && conn.agentId) {
+    const task = event.data as unknown as Task;
+    if (!targetMatchesAgent(task.target, conn.agentId, fanoutAgent(conn.agentId, agentCache))) return;
+    send(conn, event.type, task, event.seq);
+    return;
+  }
+  send(conn, event.type, event.data, event.seq);
+}
+
+function outboxToRelayEvent(event: BusEvent): RelayEvent {
+  return {
+    seq: event.seq,
+    type: event.eventType,
+    source: event.source,
+    subject: event.subject,
+    data: event.data,
+    timestamp: event.timestamp,
+  };
+}
+
 export function emitTaskChanged(task: Task, eventType = "task.updated") {
   emitRelayEvent({ type: eventType, source: task.source, subject: String(task.id), data: task as unknown as Record<string, unknown> });
 }

package/src/steward.ts

@@ -12,10 +12,11 @@ import type { Orchestrator, SpawnPolicy, StewardConfig } from "./types";
 import { isPathWithinBase } from "./utils";
 
 /** Stable, readable, collision-resistant policy name for a repo's steward. */
-export function repoStewardPolicyName(repoRoot: string): string {
+export function repoStewardPolicyName(repoRoot: string, orchestratorId?: string): string {
   const slug = basename(repoRoot).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "repo";
   const hash = createHash("sha1").update(resolve(repoRoot)).digest("hex").slice(0, 8);
-  return `steward-${slug}-${hash}`;
+  const owner = orchestratorId?.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return owner ? `steward-${slug}-${hash}-${owner}` : `steward-${slug}-${hash}`;
 }
 
 /**
@@ -54,7 +55,7 @@ function desiredStewardPolicy(repoRoot: string, owner: Orchestrator, config: Ste
   const resolved = resolveInternalSpawnTarget("landing-steward", pin);
 
   return {
-    name: repoStewardPolicyName(repoRoot),
+    name: repoStewardPolicyName(repoRoot, owner.id),
     description: `Autonomous repo steward for ${repoRoot} (issue #167).`,
     enabled: true,
     orchestratorId: owner.id,
@@ -118,13 +119,16 @@ function stewardPolicyDiffers(existing: SpawnPolicy, desired: SpawnPolicy): bool
  * owns the repo. Idempotent — refreshes the policy only when config-derived fields
  * change, so it can be called on every sweep without churn.
  */
-export function ensureRepoSteward(repoRoot: string): string | null {
+export function ensureRepoSteward(repoRoot: string, owningOrchestrator?: Orchestrator): string | null {
   const config = getStewardConfig();
   if (!config.enabled) return null;
-  const owner = listOrchestrators().find((orch) => isPathWithinBase(repoRoot, orch.baseDir));
+  const owner = owningOrchestrator ?? listOrchestrators().find((orch) =>
+    orch.status === "online" && isPathWithinBase(repoRoot, orch.baseDir)
+  );
+  if (owner && (owner.status !== "online" || !isPathWithinBase(repoRoot, owner.baseDir))) return null;
   if (!owner) return null;
 
-  const name = repoStewardPolicyName(repoRoot);
+  const name = repoStewardPolicyName(repoRoot, owner.id);
   const desired = desiredStewardPolicy(repoRoot, owner, config);
   const existing = getSpawnPolicy(name);
   if (existing && !stewardPolicyDiffers(existing.value, desired)) return name;

package/src/terminal-authz.ts

@@ -0,0 +1,50 @@
+import { getOrchestrator } from "./db";
+import { getIntegrationAuth, isFullReachRequest, isRequestAuthorizedFor } from "./security";
+
+type TerminalAccessMode = "read" | "write";
+
+interface TerminalOwner {
+  agentId: string;
+  policyName?: string;
+  spawnRequestId?: string;
+}
+
+function hasPresentedCredential(req: Request): boolean {
+  return Boolean(req.headers.get("authorization") || req.headers.get("x-agent-relay-token") || new URL(req.url).searchParams.get("token"));
+}
+
+function terminalOwner(orchestratorId: string, session: string): TerminalOwner | null {
+  const orch = getOrchestrator(orchestratorId);
+  if (!orch) return null;
+  for (const agent of orch.managedAgents ?? []) {
+    const sessions = [agent.terminalSession, agent.tmuxSession, agent.sessionName].filter((value): value is string => typeof value === "string" && value.length > 0);
+    if (!sessions.includes(session)) continue;
+    if (!agent.agentId) return null;
+    return {
+      agentId: agent.agentId,
+      ...(agent.policyName ? { policyName: agent.policyName } : {}),
+      ...(agent.spawnRequestId ? { spawnRequestId: agent.spawnRequestId } : {}),
+    };
+  }
+  return null;
+}
+
+export function isTerminalSessionRequestAuthorized(req: Request, orchestratorId: string, session: string, mode: TerminalAccessMode): boolean {
+  if (!hasPresentedCredential(req)) return true;
+  if (isFullReachRequest(req)) return true;
+  if (getIntegrationAuth(req)) return false;
+  const owner = terminalOwner(orchestratorId, session);
+  if (!owner) return false;
+  const terminalCapability = mode === "read" ? { terminalRead: true } : { terminalWrite: true };
+  return isRequestAuthorizedFor(req, {
+    scope: mode === "read" ? "terminal:read" : "terminal:write",
+    resource: {
+      orchestratorId,
+      agentId: owner.agentId,
+      policyName: owner.policyName,
+      spawnRequestId: owner.spawnRequestId,
+      terminalOwner: true,
+      ...terminalCapability,
+    },
+  });
+}

package/src/token-db.ts

@@ -67,8 +67,8 @@ const BUILT_IN_PROFILES: Array<Omit<TokenProfile, "createdAt" | "updatedAt">> =
     name: "Orchestrator Host",
     description: "Host supervisor access for spawn, command, log, and terminal operations.",
     role: "orchestrator",
-    scope: ["agent:read", "agent:write", "command:read", "command:write", "task:read", "task:write", "logs:read", "terminal:attach", "quota:write", "provisioning:read"],
-    constraints: { logsRead: true, terminalAttach: true },
+    scope: ["agent:read", "agent:write", "command:read", "command:write", "task:read", "task:write", "logs:read", "terminal:attach", "terminal:read", "terminal:write", "quota:write", "provisioning:read"],
+    constraints: { logsRead: true, terminalAttach: true, terminalRead: true, terminalWrite: true },
     ttlSeconds: 30 * 24 * 60 * 60,
     builtIn: true,
     createdBy: "system",
@@ -100,7 +100,7 @@ const BUILT_IN_PROFILES: Array<Omit<TokenProfile, "createdAt" | "updatedAt">> =
     description: "User-launched provider runtime access constrained to its own agent and cwd for long interactive sessions.",
     role: "provider",
     scope: ["agent:read", "agent:write", "message:read", "message:send", "schedule:write", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "teams:read", "blackboard:read", "blackboard:write", "project:read", "project:write", "issue:read", "issue:write", "notifications:read", "notifications:write", "channel:egress", "insights:write", "quota:write"],
-    constraints: { terminalAttach: false, logsRead: false, canDelegate: false },
+    constraints: { terminalAttach: false, terminalRead: false, terminalWrite: false, logsRead: false, canDelegate: false },
     ttlSeconds: 30 * 24 * 60 * 60,
     builtIn: true,
     createdBy: "system",

package/src/validation.ts

@@ -109,7 +109,7 @@ export function cleanTokenConstraints(value: unknown): TokenConstraints | undefi
   if (teamId) constraints.teamId = teamId;
   const tenantId = cleanString(value.tenantId, "constraints.tenantId", { max: 120 });
   if (tenantId) constraints.tenantId = tenantId;
-  for (const key of ["terminalAttach", "logsRead", "canDelegate"] as const) {
+  for (const key of ["terminalAttach", "terminalRead", "terminalWrite", "logsRead", "canDelegate"] as const) {
     if (value[key] !== undefined) {
       if (typeof value[key] !== "boolean") throw new ValidationError(`constraints.${key} must be a boolean`);
       constraints[key] = value[key];

package/src/workspace-actions.ts

@@ -26,8 +26,9 @@ import { isOwnerAlive, requestWorkspaceMerge } from "./workspace-merge";
 // tuple as the HTTP route without a second import hop (one source: workspace-merge, #304).
 export { LAND_STRATEGIES, DEFAULT_MERGE_STRATEGY } from "./workspace-merge";
 import { claimMetadataPatch, workspaceActiveClaim } from "./workspace-claim";
-import { READY_TO_LAND_STATUSES, TERMINAL_WORKSPACE_STATUSES } from "./workspace-phase";
+import { DIRTY_WORKTREE_LAND_SKIP_REASON, READY_TO_LAND_STATUSES, TERMINAL_WORKSPACE_STATUSES, worktreeReapable } from "./workspace-phase";
 import { CLEAR_MERGE_NO_PROGRESS, scheduleRepoMerge } from "./workspace-auto-merge";
+import { fetchHostMergePreview } from "./workspace-probe";
 import type { Command, WorkspaceAutoMergePolicy, WorkspaceMergeStrategy, WorkspaceRecord, WorkspaceStatus } from "./types";
 
 // Single source of truth for the action verb set. The route's `optionalEnum` and
@@ -129,7 +130,28 @@ function recordWorkspaceAudit(a: {
   }
 }
 
-export function applyWorkspaceAction(workspace: WorkspaceRecord, input: ApplyWorkspaceActionInput): WorkspaceActionResult {
+function metadataNumber(metadata: Record<string, unknown>, key: string): number | undefined {
+  const value = metadata[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+async function cleanupWorkSafety(workspace: WorkspaceRecord): Promise<{ ok: true } | { ok: false; error: string }> {
+  const owner = workspaceOwnerOrchestrator(workspace, listOrchestrators(), { requireApiUrl: true });
+  if (!owner?.apiUrl) return { ok: false, error: "owning orchestrator unavailable for cleanup safety probe" };
+  const preview = await fetchHostMergePreview(owner.apiUrl, workspace, { checkPr: false });
+  if (!preview) return { ok: false, error: "cleanup safety probe unavailable" };
+  if ("available" in preview && preview.available === false) return { ok: false, error: "cleanup safety probe unavailable" };
+  const p = preview as Exclude<typeof preview, { available: false }>;
+  if (p.missing) return { ok: true };
+  if (p.error) return { ok: false, error: `cleanup safety probe error: ${p.error}` };
+  if (worktreeReapable({ landed: p.landed, ahead: p.ahead, unmergedAhead: p.unmergedAhead, dirtyCount: p.dirtyCount })) return { ok: true };
+  const dirtyCount = p.dirtyCount ?? 0;
+  if (dirtyCount > 0) return { ok: false, error: `${dirtyCount} uncommitted change(s)` };
+  const ahead = p.unmergedAhead ?? p.ahead ?? 0;
+  return { ok: false, error: `${ahead} unlanded commit(s)` };
+}
+
+export async function applyWorkspaceAction(workspace: WorkspaceRecord, input: ApplyWorkspaceActionInput): Promise<WorkspaceActionResult> {
   const { action } = input;
   const agentId = input.agentId;
   const detail = input.detail;
@@ -228,6 +250,17 @@ export function applyWorkspaceAction(workspace: WorkspaceRecord, input: ApplyWor
   const nextStatus = STATUS_BY_ACTION[action];
   if (!nextStatus) return { ok: false, httpStatus: 400, error: `unsupported action: ${action}` };
 
+  if (READY_TO_LAND_STATUSES.has(nextStatus)) {
+    const dirtyCount = metadataNumber(workspace.metadata, "gitDirtyCount") ?? 0;
+    if (dirtyCount > 0) {
+      return {
+        ok: false,
+        httpStatus: 409,
+        error: `workspace ${workspace.id} cannot be marked ${nextStatus}: ${DIRTY_WORKTREE_LAND_SKIP_REASON} (${dirtyCount} dirty file${dirtyCount === 1 ? "" : "s"}); commit or stash first`,
+      };
+    }
+  }
+
   if (
     action === "cleanup" &&
     input.force !== true &&
@@ -245,7 +278,15 @@ export function applyWorkspaceAction(workspace: WorkspaceRecord, input: ApplyWor
   let command: Command | undefined;
   if (requiresCommand) {
     // Only `cleanup` reaches here — `merge` returned early via the shared helper.
-    const built = buildWorkspaceCleanupCommand(workspace, agentId ?? "dashboard", { force: input.force === true });
+    const safety = await cleanupWorkSafety(workspace);
+    if (!safety.ok && !(input.force === true && Boolean(detail?.trim()))) {
+      return {
+        ok: false,
+        httpStatus: 409,
+        error: `workspace ${workspace.id} cannot be cleaned up safely: ${safety.error}; pass force:true with a detail reason only if intentionally discarding work`,
+      };
+    }
+    const built = buildWorkspaceCleanupCommand(workspace, agentId ?? "dashboard", { force: input.force === true, reason: detail });
     if (!built.ok) return { ok: false, httpStatus: built.status, error: built.error };
     command = built.command;
   }
@@ -287,7 +328,7 @@ export function applyWorkspaceAction(workspace: WorkspaceRecord, input: ApplyWor
 export function buildWorkspaceCleanupCommand(
   workspace: WorkspaceRecord,
   requestedBy: string,
-  opts: { force?: boolean } = {},
+  opts: { force?: boolean; reason?: string } = {},
 ): { ok: true; command: Command } | { ok: false; status: number; error: string } {
   if (
     opts.force !== true &&
@@ -319,6 +360,7 @@ export function buildWorkspaceCleanupCommand(
       requestedBy,
       requestedAt: Date.now(),
       deleteBranch: true,
+      ...(opts.force === true && opts.reason ? { force: true, reason: opts.reason } : {}),
       queued: false,
     },
   });