agent-relay-server 0.121.5 → 0.122.1

package/runner/src/control-server.ts

@@ -0,0 +1,639 @@
+import type { Server, ServerWebSocket } from "bun";
+import type { InteractivePrompt, Message, ReplyObligation } from "agent-relay-sdk";
+import { errMessage, isRecord } from "agent-relay-sdk";
+import type { ProviderPermissionDecisionInput, ProviderStatusEvent, SemanticStatus, TerminalAttachSpec } from "./adapter";
+import { obligationRequiresExplicitReply } from "./reply-obligation-cache";
+import { relayReplyActionText } from "./relay-instructions";
+import { logger, parseLogLevel, LOG_LEVELS } from "./logger";
+import { buildRateLimitProviderState } from "./rate-limit";
+
+// The AskUserQuestion / PermissionRequest hook (runner/plugins/claude/hooks/hooks.json)
+// has a 900s Claude-side timeout. Resolve the server-side wait with a margin UNDER that
+// so the server always returns a deterministic decision before Claude abandons the hook —
+// at exact equality the two timers race with no winner (#693).
+const PERMISSION_WAIT_MS = 880_000;
+// Distinct from a human dismissal ("Dismissed/Denied from Agent Relay dashboard") so the
+// agent can tell "nobody answered in time" (retriable) from "the human said no" (#693).
+const PERMISSION_TIMEOUT_REASON =
+  "No response received within ~15 minutes (timeout, not a dismissal). Re-ask if you still need a decision.";
+
+// A hook that failed in a way it could not handle itself reports here so the
+// failure is never silent (#198 item 5). Phase 1 logs it FATAL to the per-agent
+// log; Phase 2 (#196) will additionally route it through the runner outbox to the
+// server.
+export interface HookFatalReport {
+  hook: string;
+  error: string;
+}
+
+interface MonitorSocketData {
+  kind: "monitor";
+}
+
+type MonitorSocket = ServerWebSocket<MonitorSocketData>;
+
+export interface ControlServer {
+  port: number;
+  url: string;
+  stop(): void;
+  deliverToMonitor(messages: Message[], timeoutMs?: number): Promise<number[]>;
+  resolvePermissionDecision(input: ProviderPermissionDecisionInput): boolean;
+}
+
+interface ControlServerOptions {
+  onStatus(status: ProviderStatusEvent): void;
+  onTerminalAttachSpec?(): Promise<TerminalAttachSpec>;
+  onReplyObligations?(): Promise<ReplyObligation[]>;
+  // Phase 1 live-session lane: a provider Stop hook hands over its transcript
+  // path so the runner can capture the assistant turn and surface it in the
+  // dashboard chat without the agent re-emitting it via /reply.
+  // isPreFlush: true signals a mid-turn call from a PreToolUse hook — flush any
+  // un-mirrored narrative before the interactive form appears in chat (#435).
+  onSessionTurn?(input: { transcriptPath: string; lastAssistantMessage?: unknown; isPreFlush?: boolean }): Promise<void>;
+  onPermissionResolved?(input: ResolvedPermissionPrompt): Promise<void> | void;
+  // A provider UserPromptSubmit hook hands over the prompt the human typed
+  // directly into the session (web terminal / TUI) so the runner can mirror it
+  // into the dashboard chat and start tailing the turn transcript for reasoning.
+  onUserPrompt?(input: { prompt: string; transcriptPath?: string }): Promise<void>;
+  // A provider session-boundary hook (Claude PreCompact / SessionEnd) signals an imminent
+  // context reset or termination so the runner can run end-of-session work (#183 pre-destroy
+  // seam: #184 context-ratio capture) before the invasive operation. `reason` is the raw
+  // provider reason (compact, clear, logout, …); transcriptPath is optional — the runner
+  // falls back to the last path it saw during the session.
+  onSessionBoundary?(input: { reason?: string; transcriptPath?: string }): Promise<void>;
+  // Phase 1 observability (#198): a hook reporting an unhandled failure. The
+  // control server already logs it FATAL; this is the seam for Phase 2 to also
+  // surface it to the server via the runner outbox.
+  onHookFatal?(report: HookFatalReport): void;
+  // Test seam: how long the permission hook waits for a dashboard decision before
+  // resolving as a timeout. Defaults to PERMISSION_WAIT_MS (margin under the 900s hook).
+  permissionWaitMs?: number;
+}
+
+export interface ResolvedPermissionPrompt {
+  provider: "claude";
+  kind: "questions" | "plan" | "command" | "tool";
+  title: string;
+  body: string;
+  promptBody?: string;
+  toolName: string;
+  hookEventName: string;
+  approvalId: string;
+  decision: ProviderPermissionDecisionInput["decision"];
+  decisionLabel: string;
+  questions?: unknown[];
+  answers?: Record<string, string>;
+}
+
+export function startControlServer(options: ControlServerOptions): ControlServer {
+  const monitors = new Set<MonitorSocket>();
+  const pendingDeliveries = new Map<string, { resolve(ids: number[]): void; timer: Timer }>();
+  const pendingPermissionRequests = new Map<string, { resolve(input: ProviderPermissionDecisionInput): void; timer: Timer }>();
+  // approvalIds already resolved, so a duplicate decision (e.g. bus replay after a
+  // reconnect, or both the PreToolUse and PermissionRequest hooks racing one answer)
+  // is an idempotent no-op instead of a silent command failure (#693).
+  const resolvedApprovals = new Set<string>();
+  let server!: Server<MonitorSocketData>;
+
+  server = Bun.serve<MonitorSocketData>({
+    hostname: "127.0.0.1",
+    port: 0,
+    fetch(req, srv) {
+      const url = new URL(req.url);
+      if (url.pathname === "/health") return Response.json({ ok: true });
+      if (url.pathname === "/status" && req.method === "GET") return Response.json({ ok: true });
+      if (url.pathname === "/status" && req.method === "POST") {
+        return handleStatus(req, options);
+      }
+      if (url.pathname === "/terminal/attach-spec" && req.method === "GET") {
+        if (!options.onTerminalAttachSpec) return Response.json({ error: "terminal attach is unavailable" }, { status: 404 });
+        return options.onTerminalAttachSpec()
+          .then((spec) => Response.json(spec))
+          .catch((error) => Response.json({ error: errMessage(error) }, { status: 409 }));
+      }
+      if (url.pathname === "/reply-obligations" && req.method === "GET") {
+        if (!options.onReplyObligations) return Response.json({ pending: false, count: 0 });
+        return options.onReplyObligations()
+          .then((obligations) => Response.json(replyObligationSummary(obligations)))
+          .catch((error) => Response.json({ error: errMessage(error) }, { status: 503 }));
+      }
+      if (url.pathname === "/reply-obligations/claude-stop" && req.method === "GET") {
+        if (!options.onReplyObligations) return Response.json({});
+        return options.onReplyObligations()
+          .then((obligations) => Response.json(replyObligationStopDecision(obligations)))
+          .catch((error) => Response.json({ error: errMessage(error) }, { status: 503 }));
+      }
+      if (url.pathname === "/permissions/request" && req.method === "POST") {
+        return handlePermissionRequest(req, options, pendingPermissionRequests);
+      }
+      if (url.pathname === "/session-turn" && req.method === "POST") {
+        return handleSessionTurn(req, options);
+      }
+      if (url.pathname === "/user-prompt" && req.method === "POST") {
+        return handleUserPrompt(req, options);
+      }
+      if (url.pathname === "/session-boundary" && req.method === "POST") {
+        return handleSessionBoundary(req, options);
+      }
+      if (url.pathname === "/log-level" && req.method === "GET") {
+        return Response.json({ level: logger.getLevel(), levels: LOG_LEVELS });
+      }
+      if (url.pathname === "/log-level" && req.method === "POST") {
+        return handleLogLevel(req);
+      }
+      if (url.pathname === "/hook-fatal" && req.method === "POST") {
+        return handleHookFatal(req, options);
+      }
+      if (url.pathname === "/rate-limit" && req.method === "POST") {
+        return handleRateLimit(req, options);
+      }
+      if (url.pathname === "/monitor") {
+        const upgraded = srv.upgrade(req, { data: { kind: "monitor" } });
+        return upgraded ? undefined : new Response("WebSocket upgrade failed", { status: 400 });
+      }
+      return new Response("not found", { status: 404 });
+    },
+    websocket: {
+      open(ws) {
+        monitors.add(ws);
+      },
+      message(_ws, raw) {
+        const parsed = parseJson(raw);
+        if (parsed?.type === "message.delivered" && Array.isArray(parsed.messageIds)) {
+          const deliveryId = typeof parsed.deliveryId === "string" ? parsed.deliveryId : "";
+          const pending = pendingDeliveries.get(deliveryId);
+          if (pending) {
+            clearTimeout(pending.timer);
+            pendingDeliveries.delete(deliveryId);
+            pending.resolve(parsed.messageIds.filter((id): id is number => Number.isSafeInteger(id)));
+          }
+        }
+      },
+      close(ws) {
+        monitors.delete(ws);
+      },
+    },
+  });
+
+  const port = server.port;
+  if (port === undefined) throw new Error("runner control server did not bind a port");
+
+  return {
+    port,
+    url: `http://127.0.0.1:${port}`,
+    stop() {
+      for (const pending of pendingDeliveries.values()) clearTimeout(pending.timer);
+      pendingDeliveries.clear();
+      for (const pending of pendingPermissionRequests.values()) clearTimeout(pending.timer);
+      pendingPermissionRequests.clear();
+      server.stop(true);
+    },
+    async deliverToMonitor(messages: Message[], timeoutMs = 30_000): Promise<number[]> {
+      if (monitors.size === 0) throw new Error("no Claude monitor connected");
+      const deliveryId = crypto.randomUUID();
+      const payload = JSON.stringify({ type: "message.deliver", deliveryId, messages });
+      return await new Promise<number[]>((resolve, reject) => {
+        const timer = setTimeout(() => {
+          pendingDeliveries.delete(deliveryId);
+          reject(new Error("monitor delivery timed out"));
+        }, timeoutMs);
+        pendingDeliveries.set(deliveryId, { resolve, timer });
+        for (const monitor of monitors) monitor.send(payload);
+      });
+    },
+    resolvePermissionDecision(input: ProviderPermissionDecisionInput): boolean {
+      const pending = pendingPermissionRequests.get(input.approvalId);
+      if (!pending) {
+        // Idempotent: a duplicate decision for an already-resolved approval is a
+        // benign no-op, not a dropped answer that fails the command (#693).
+        return resolvedApprovals.has(input.approvalId);
+      }
+      clearTimeout(pending.timer);
+      pendingPermissionRequests.delete(input.approvalId);
+      resolvedApprovals.add(input.approvalId);
+      if (resolvedApprovals.size > 1024) resolvedApprovals.clear();
+      pending.resolve(input);
+      options.onStatus({
+        status: "busy",
+        reason: "provider-turn",
+        providerState: {
+          state: "active",
+          reason: "permissionResolved",
+          label: "Claude approval resolved",
+          source: "claude",
+          updatedAt: Date.now(),
+        },
+      });
+      return true;
+    },
+  };
+}
+
+function replyObligationSummary(obligations: ReplyObligation[]): Record<string, unknown> {
+  const obligation = obligations[0];
+  if (!obligation) return { pending: false, count: 0 };
+  const subject = obligation.subject ? ` (${obligation.subject})` : "";
+  return {
+    pending: true,
+    count: obligations.length,
+    obligation,
+    reason: `Pending Agent Relay response for message #${obligation.messageId} from ${obligation.from}${subject}. If it still needs an answer, use ${relayReplyActionText(obligation.messageId)}. If multiple delivered messages are part of one current request, answer once to the latest relevant message. If the useful response was already delivered through Relay, do not send a separate status-only confirmation.`,
+  };
+}
+
+function replyObligationStopDecision(obligations: ReplyObligation[]): Record<string, unknown> {
+  // #418 — never block the turn to nag for a `user` obligation: the operator already receives
+  // this turn via the session mirror, so an explicit /reply double-delivers. Only agent↔agent /
+  // spawner obligations (#413) gate the turn here; the mirror's replyTo-linking clears the user
+  // one. (The /reply-obligations summary endpoint is left unfiltered — the obligation IS pending
+  // until the mirror lands, so observability stays accurate.)
+  const enforceable = obligations.filter(obligationRequiresExplicitReply);
+  const summary = replyObligationSummary(enforceable);
+  if (summary.pending !== true) return {};
+  return {
+    decision: "block",
+    reason: summary.reason,
+  };
+}
+
+async function handlePermissionRequest(
+  req: Request,
+  options: ControlServerOptions,
+  pendingPermissionRequests: Map<string, { resolve(input: ProviderPermissionDecisionInput): void; timer: Timer }>,
+): Promise<Response> {
+  const body = await req.json().catch(() => null);
+  if (!isRecord(body)) return Response.json({});
+  // #435: flush any un-mirrored narrative from the transcript before the form
+  // appears in chat — the transcript already has the assistant text block at
+  // PreToolUse time, but the Stop hook (which normally captures it) won't fire
+  // until after the user answers, so the form would otherwise arrive first.
+  const transcriptPath = typeof body.transcript_path === "string" ? body.transcript_path : "";
+  if (transcriptPath && options.onSessionTurn) {
+    await options.onSessionTurn({ transcriptPath, isPreFlush: true }).catch(() => {});
+  }
+  const approvalId = crypto.randomUUID();
+  const view = claudePermissionApprovalView(approvalId, body);
+  options.onStatus({
+    status: "busy",
+    reason: "provider-turn",
+    providerState: {
+      state: "blocked",
+      reason: "permissionRequest",
+      label: view.title,
+      recommendedAction: "Review the permission request in Agent Relay.",
+      source: "claude",
+      pendingApproval: view,
+      updatedAt: Date.now(),
+    },
+  });
+
+  const decision = await new Promise<ProviderPermissionDecisionInput>((resolve) => {
+    const timer = setTimeout(() => {
+      pendingPermissionRequests.delete(approvalId);
+      resolve({ approvalId, decision: "deny", reason: PERMISSION_TIMEOUT_REASON });
+    }, options.permissionWaitMs ?? PERMISSION_WAIT_MS);
+    pendingPermissionRequests.set(approvalId, { resolve, timer });
+  });
+
+  if (decision.reason !== PERMISSION_TIMEOUT_REASON && options.onPermissionResolved) {
+    await Promise.resolve(options.onPermissionResolved(claudeResolvedPermissionPrompt(view, decision, body))).catch(() => {});
+  }
+
+  return Response.json(claudePermissionHookResponse(decision, body));
+}
+
+// Build the normalized InteractivePrompt for a Claude PreToolUse permission/question hook.
+// reasoningSettled is stamped `true` because handlePermissionRequest pre-flushes the
+// transcript narrative (onSessionTurn isPreFlush) BEFORE this view is built and emitted, so
+// the turn's reasoning is already mirrored ahead of the form (#435/#723). No `provider` tag —
+// the server reads the typed contract, not provider identity.
+function claudePermissionApprovalView(id: string, body: Record<string, unknown>): InteractivePrompt {
+  const toolName = typeof body.tool_name === "string" ? body.tool_name : "Tool";
+  const toolInput = isRecord(body.tool_input) ? body.tool_input : {};
+  // AskUserQuestion is not a yes/no gate — it asks the user to pick answers.
+  // Surface the structured questions so the dashboard can render a form and
+  // return the selections via an "answer" decision (handled in the hook
+  // response below as a PreToolUse allow + updatedInput).
+  if (toolName === "AskUserQuestion" && Array.isArray(toolInput.questions) && toolInput.questions.length) {
+    const count = toolInput.questions.length;
+    return {
+      id,
+      kind: "questions",
+      title: count > 1 ? `Claude is asking ${count} questions` : "Claude is asking a question",
+      body: "",
+      questions: toolInput.questions as InteractivePrompt["questions"],
+      choices: [],
+      reasoningSettled: true,
+    };
+  }
+  // ExitPlanMode arrives through the generic PermissionRequest hook (it doesn't
+  // match the AskUserQuestion matcher), which used to render the raw tool_input
+  // JSON with generic Approve/Deny buttons. Surface the plan as markdown with the
+  // real plan-mode choices instead. approve → allow (exit plan mode and proceed);
+  // deny → keep planning.
+  if (toolName === "ExitPlanMode") {
+    const plan = typeof toolInput.plan === "string" && toolInput.plan.trim()
+      ? toolInput.plan
+      : JSON.stringify(toolInput);
+    return {
+      id,
+      kind: "plan",
+      title: "Claude is ready to code",
+      body: plan,
+      choices: [
+        { id: "approve", label: "Approve plan" },
+        { id: "deny", label: "Keep planning" },
+      ],
+      reasoningSettled: true,
+    };
+  }
+  const command = typeof toolInput.command === "string" ? toolInput.command : "";
+  const description = typeof toolInput.description === "string" ? toolInput.description : "";
+  const bodyText = [
+    command || description || JSON.stringify(toolInput),
+    typeof body.cwd === "string" ? `CWD: ${body.cwd}` : "",
+    typeof body.permission_mode === "string" ? `Mode: ${body.permission_mode}` : "",
+  ].filter(Boolean).join("\n");
+  return {
+    id,
+    kind: toolName.toLowerCase() === "bash" ? "command" : "tool",
+    title: `Approve ${toolName}`,
+    body: bodyText,
+    choices: [
+      { id: "approve", label: "Approve" },
+      { id: "approve-session", label: "Approve session" },
+      { id: "deny", label: "Deny" },
+      { id: "abort", label: "Abort" },
+    ],
+    reasoningSettled: true,
+  };
+}
+
+function claudePermissionHookResponse(decision: ProviderPermissionDecisionInput, body: Record<string, unknown>): Record<string, unknown> {
+  // AskUserQuestion comes through a PreToolUse hook. The only way to satisfy it
+  // headlessly is permissionDecision "allow" + updatedInput carrying the answers
+  // (echoing back the original questions). A bare "allow" is not sufficient, so
+  // anything that is not a populated answer is treated as a deny.
+  if (body.hook_event_name === "PreToolUse") {
+    const toolInput = isRecord(body.tool_input) ? body.tool_input : {};
+    if (decision.decision === "answer" && decision.answers && Object.keys(decision.answers).length) {
+      return {
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          permissionDecision: "allow",
+          updatedInput: { ...toolInput, answers: decision.answers },
+        },
+      };
+    }
+    return {
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: decision.reason || "Dismissed from Agent Relay dashboard",
+      },
+    };
+  }
+  const hookEventName = "PermissionRequest";
+  // AskUserQuestion can be gated by the PermissionRequest hook instead of PreToolUse
+  // (e.g. when the PreToolUse hook returned no decision and Claude fell back to the
+  // default permission flow). The answer must still be honored, not turned into a deny
+  // (#693). PermissionRequest supports updatedInput on an allow, same as PreToolUse.
+  if (decision.decision === "answer" && decision.answers && Object.keys(decision.answers).length) {
+    const toolInput = isRecord(body.tool_input) ? body.tool_input : {};
+    return {
+      hookSpecificOutput: {
+        hookEventName,
+        decision: {
+          behavior: "allow",
+          updatedInput: { ...toolInput, answers: decision.answers },
+        },
+      },
+    };
+  }
+  if (decision.decision === "approve" || decision.decision === "approve-session") {
+    const suggestions = Array.isArray(body.permission_suggestions) ? body.permission_suggestions : [];
+    return {
+      hookSpecificOutput: {
+        hookEventName,
+        decision: {
+          behavior: "allow",
+          ...(decision.decision === "approve-session" && suggestions.length ? { updatedPermissions: suggestions } : {}),
+        },
+      },
+    };
+  }
+  return {
+    hookSpecificOutput: {
+      hookEventName,
+      decision: {
+        behavior: "deny",
+        message: decision.reason || "Denied from Agent Relay dashboard",
+        interrupt: decision.decision === "abort",
+      },
+    },
+  };
+}
+
+function claudeResolvedPermissionPrompt(view: InteractivePrompt, decision: ProviderPermissionDecisionInput, body: Record<string, unknown>): ResolvedPermissionPrompt {
+  const toolName = typeof body.tool_name === "string" ? body.tool_name : "Tool";
+  const toolInput = isRecord(body.tool_input) ? body.tool_input : {};
+  const kind = view.kind === "questions" || view.kind === "plan" || view.kind === "command" || view.kind === "tool"
+    ? view.kind
+    : toolName.toLowerCase() === "bash" ? "command" : "tool";
+  const questions = Array.isArray(view.questions)
+    ? view.questions
+    : Array.isArray(toolInput.questions) ? toolInput.questions : undefined;
+  const promptBody = typeof view.body === "string" ? view.body : "";
+  const decisionLabel = claudePermissionDecisionLabel(kind, decision.decision);
+  return {
+    provider: "claude",
+    kind,
+    title: typeof view.title === "string" && view.title ? view.title : `Approve ${toolName}`,
+    body: claudeResolvedPermissionBody({ kind, title: typeof view.title === "string" && view.title ? view.title : `Approve ${toolName}`, toolName, promptBody, decisionLabel, questions, answers: decision.answers }),
+    ...(promptBody ? { promptBody } : {}),
+    toolName,
+    hookEventName: typeof body.hook_event_name === "string" ? body.hook_event_name : "PermissionRequest",
+    approvalId: decision.approvalId,
+    decision: decision.decision,
+    decisionLabel,
+    ...(questions ? { questions } : {}),
+    ...(decision.answers ? { answers: decision.answers } : {}),
+  };
+}
+
+function claudeResolvedPermissionBody(input: { kind: ResolvedPermissionPrompt["kind"]; title: string; toolName: string; promptBody: string; decisionLabel: string; questions?: unknown[]; answers?: Record<string, string> }): string {
+  if (input.kind === "questions") {
+    return [
+      input.title,
+      input.decisionLabel,
+      ...resolvedQuestionRows(input.questions, input.answers, input.decisionLabel).map((row) => `Q: ${row.question}\nA: ${row.answer}`),
+    ].filter(Boolean).join("\n\n");
+  }
+  const subject = input.kind === "plan" ? "Plan prompt resolved" : `${input.toolName} permission resolved`;
+  return [subject, `Decision: ${input.decisionLabel}`, input.promptBody.trim()].filter(Boolean).join("\n\n");
+}
+
+function resolvedQuestionRows(questions: unknown[] | undefined, answers: Record<string, string> | undefined, fallback: string): Array<{ question: string; answer: string }> {
+  const answerMap = answers ?? {};
+  const rows = (questions ?? []).map((question, index) => {
+    const record = question && typeof question === "object" && !Array.isArray(question) ? question as Record<string, unknown> : {};
+    const label = typeof record.question === "string" && record.question.trim()
+      ? record.question.trim()
+      : typeof record.header === "string" && record.header.trim() ? record.header.trim() : `Question ${index + 1}`;
+    const rawAnswer = answerMap[label] ?? answerMap[String(record.question ?? "")] ?? answerMap[String(record.header ?? "")];
+    return { question: label, answer: typeof rawAnswer === "string" && rawAnswer.trim() ? rawAnswer.trim() : fallback };
+  });
+  return rows.length ? rows : Object.entries(answerMap).map(([question, answer]) => ({ question, answer }));
+}
+
+function claudePermissionDecisionLabel(kind: ResolvedPermissionPrompt["kind"], decision: ProviderPermissionDecisionInput["decision"]): string {
+  if (kind === "questions") return decision === "answer" ? "Answered" : "Dismissed";
+  if (kind === "plan") return decision === "approve" || decision === "approve-session" ? "Approved plan" : "Kept planning";
+  if (decision === "approve-session") return "Approved for session";
+  if (decision === "approve") return "Approved";
+  if (decision === "abort") return "Aborted";
+  if (decision === "answer") return "Answered";
+  return "Denied";
+}
+
+async function handleSessionTurn(req: Request, options: ControlServerOptions): Promise<Response> {
+  if (!options.onSessionTurn) return Response.json({ ok: false, reason: "session capture unavailable" });
+  const body = await req.json().catch(() => null);
+  const transcriptPath = isRecord(body) && typeof body.transcriptPath === "string" ? body.transcriptPath : "";
+  const lastAssistantMessage = isRecord(body) ? body.lastAssistantMessage : undefined;
+  // transcriptPath is the primary source, but it can be absent (known CC Stop edge case).
+  // lastAssistantMessage is the fallback for exactly that — accept either; reject only when
+  // both are missing so the turn still reaches the dashboard chat (#264).
+  if (!transcriptPath && lastAssistantMessage === undefined) {
+    return Response.json({ ok: false, reason: "transcriptPath or lastAssistantMessage required" }, { status: 400 });
+  }
+  // Awaited on purpose: the Stop hook posts this synchronously before its
+  // reply-obligation check, so the captured turn must be persisted (and the
+  // obligation cleared) before this response returns.
+  try {
+    await options.onSessionTurn({ transcriptPath, lastAssistantMessage });
+    return Response.json({ ok: true });
+  } catch (error) {
+    return Response.json({ ok: false, reason: errMessage(error) }, { status: 500 });
+  }
+}
+
+async function handleUserPrompt(req: Request, options: ControlServerOptions): Promise<Response> {
+  if (!options.onUserPrompt) return Response.json({ ok: false, reason: "prompt echo unavailable" });
+  const body = await req.json().catch(() => null);
+  const prompt = isRecord(body) && typeof body.prompt === "string" ? body.prompt : "";
+  if (!prompt.trim()) return Response.json({ ok: false, reason: "prompt required" }, { status: 400 });
+  const transcriptPath = isRecord(body) && typeof body.transcriptPath === "string" ? body.transcriptPath : undefined;
+  // Fire-and-forget: the hook must not block Claude's turn on relay round-trips.
+  void Promise.resolve(options.onUserPrompt({ prompt, transcriptPath })).catch(() => {});
+  return Response.json({ ok: true });
+}
+
+async function handleSessionBoundary(req: Request, options: ControlServerOptions): Promise<Response> {
+  if (!options.onSessionBoundary) return Response.json({ ok: false, reason: "session-boundary capture unavailable" });
+  const body = await req.json().catch(() => null);
+  const reason = isRecord(body) && typeof body.reason === "string" ? body.reason : undefined;
+  const transcriptPath = isRecord(body) && typeof body.transcriptPath === "string" ? body.transcriptPath : undefined;
+  // Fire-and-forget: a PreCompact/SessionEnd hook must not block Claude compacting or exiting.
+  void Promise.resolve(options.onSessionBoundary({ reason, transcriptPath })).catch(() => {});
+  return Response.json({ ok: true });
+}
+
+async function handleLogLevel(req: Request): Promise<Response> {
+  const body = await req.json().catch(() => null);
+  const level = parseLogLevel(isRecord(body) && typeof body.level === "string" ? body.level : undefined);
+  if (!level) return Response.json({ error: `level must be one of: ${LOG_LEVELS.join(", ")}` }, { status: 400 });
+  const previous = logger.getLevel();
+  logger.setLevel(level);
+  logger.info("logger", `log level set to ${level} (was ${previous}) via control port`);
+  return Response.json({ ok: true, level, previous });
+}
+
+async function handleHookFatal(req: Request, options: ControlServerOptions): Promise<Response> {
+  const body = await req.json().catch(() => null);
+  const hook = isRecord(body) && typeof body.hook === "string" && body.hook.trim() ? body.hook.trim() : "unknown";
+  const error = isRecord(body) && typeof body.error === "string" ? body.error : "(no detail)";
+  // Never silent: a hook that couldn't handle its own failure lands here as FATAL.
+  logger.fatal(`hook:${hook}`, error);
+  try { options.onHookFatal?.({ hook, error }); } catch { /* reporting must never throw back at the hook */ }
+  return Response.json({ ok: true });
+}
+
+async function handleStatus(req: Request, options: ControlServerOptions): Promise<Response> {
+  const body = await req.json().catch(() => null) as Partial<ProviderStatusEvent> | null;
+  const status = body?.status;
+  if (status !== "idle" && status !== "busy" && status !== "offline" && status !== "error") {
+    return Response.json({ error: "status must be idle, busy, offline, or error" }, { status: 400 });
+  }
+  const reason = body?.reason;
+  if (reason !== undefined && reason !== "provider-turn" && reason !== "subagent" && reason !== "background-script") {
+    return Response.json({ error: "reason must be provider-turn, subagent, or background-script" }, { status: 400 });
+  }
+  const isWorkKind = (item: unknown): item is "provider-turn" | "subagent" | "background-script" =>
+    item === "provider-turn" || item === "subagent" || item === "background-script";
+  const clear = Array.isArray(body?.clear) ? body.clear.filter(isWorkKind) : undefined;
+  // #650: optional pids the runner reconciles against process liveness so a tracked
+  // command/shell killed out-of-band clears the busy marker instead of stranding it.
+  const pidsInput = Array.isArray((body as { pids?: unknown })?.pids) ? (body as { pids: unknown[] }).pids : undefined;
+  const pids = pidsInput
+    ?.map((p) => (typeof p === "number" ? p : Number(p)))
+    .filter((p) => Number.isInteger(p) && p > 0);
+  const timeline = statusTimelineEvent(body);
+  const update: ProviderStatusEvent = {
+    status,
+    ...(typeof body?.providerSessionId === "string" ? { providerSessionId: body.providerSessionId } : {}),
+    ...(reason ? { reason } : {}),
+    ...(clear?.length ? { clear: [...new Set(clear)] } : {}),
+    ...(timeline ? { timeline } : {}),
+    ...(typeof body?.id === "string" ? { id: body.id } : {}),
+    ...(pids?.length ? { pids } : {}),
+    ...(typeof body?.label === "string" ? { label: body.label } : {}),
+    ...(typeof body?.role === "string" ? { role: body.role } : {}),
+    ...(typeof body?.parentId === "string" ? { parentId: body.parentId } : {}),
+    ...(body?.metadata && typeof body.metadata === "object" && !Array.isArray(body.metadata) ? { metadata: body.metadata as Record<string, unknown> } : {}),
+  };
+  options.onStatus(update);
+  return Response.json({ ok: true, ...update });
+}
+
+// #286: the stop-failure hook reports a usage/rate-limit stall here. Build the
+// provider-neutral `blocked` state (reason rate_limit) — the same seam Claude
+// model-unavailable and Codex approvals ride — so the dashboard shows it
+// distinctly (never as idle/available) and the relay's resume sweep can lift it
+// at reset. The agent stays `idle` underneath (the turn truly ended); the runner
+// carries the hold via its rateLimitHold field, not an active-work claim.
+async function handleRateLimit(req: Request, options: ControlServerOptions): Promise<Response> {
+  const body = await req.json().catch(() => null);
+  if (!isRecord(body)) return Response.json({ error: "invalid body" }, { status: 400 });
+  const errorType = typeof body.errorType === "string" && body.errorType ? body.errorType : "rate_limit";
+  // CC's reset_time is unix SECONDS ("if available"); normalize to ms for the relay.
+  const resetTimeSec = typeof body.resetTime === "number" && Number.isFinite(body.resetTime) ? body.resetTime : undefined;
+  const resetAt = resetTimeSec !== undefined ? Math.round(resetTimeSec * 1000) : undefined;
+  const errorMessage = typeof body.errorMessage === "string" && body.errorMessage ? body.errorMessage : undefined;
+  options.onStatus({
+    status: "idle",
+    clear: ["subagent"],
+    providerState: buildRateLimitProviderState({ errorType, resetAt, message: errorMessage, source: "claude" }),
+  });
+  return Response.json({ ok: true, errorType, ...(resetAt ? { resetAt } : {}) });
+}
+
+function statusTimelineEvent(body: Partial<ProviderStatusEvent> | null): ProviderStatusEvent["timeline"] | undefined {
+  const timeline = body?.timeline;
+  if (!timeline || typeof timeline !== "object" || Array.isArray(timeline)) return undefined;
+  if (typeof timeline.status !== "string" || !timeline.status) return undefined;
+  return {
+    status: timeline.status,
+    ...(typeof timeline.id === "string" ? { id: timeline.id } : {}),
+    ...(typeof timeline.timestamp === "number" && Number.isFinite(timeline.timestamp) ? { timestamp: timeline.timestamp } : {}),
+  };
+}
+
+function parseJson(raw: string | Buffer): Record<string, unknown> | null {
+  try {
+    const parsed = JSON.parse(typeof raw === "string" ? raw : raw.toString());
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed as Record<string, unknown> : null;
+  } catch {
+    return null;
+  }
+}