agent-relay-server 0.17.0 → 0.19.0

package/src/config-store.ts

@@ -1,5 +1,7 @@
 import { getDb, ValidationError } from "./db";
+import { cleanEnum, cleanString, cleanStringArray } from "./validation";
 import { resolveProviderSelection, type ProviderEffort } from "agent-relay-sdk/provider-catalog";
+import { errMessage, isRecord, SPAWN_PROVIDERS, VALID_EFFORTS, VALID_WORKSPACE_MODES } from "agent-relay-sdk";
 import type {
   AgentProfile,
   AgentProfileBase,
@@ -24,18 +26,15 @@ const INSIGHTS_NAMESPACE = "insights";
 const INSIGHTS_KEY = "default";
 const WORKSPACE_NAMESPACE = "workspace";
 const WORKSPACE_KEY = "default";
-const VALID_PROVIDERS = ["claude", "codex"] as const;
 const VALID_PROFILE_PROVIDERS = ["any", "claude", "codex"] as const;
 const VALID_PROFILE_BASES = ["host", "minimal", "isolated"] as const;
 const VALID_PROFILE_INSTRUCTION_POLICIES = ["allow", "ignore"] as const;
 const VALID_PROFILE_CATEGORY_MODES = ["host", "profile", "repo", "none"] as const;
 const VALID_PROFILE_ASSET_SOURCES = ["relay", "repo", "inline", "provider"] as const;
 const VALID_PROFILE_FILESYSTEM_SCOPES = ["repo", "workspace", "host"] as const;
-const VALID_EFFORTS = ["low", "medium", "high", "xhigh", "max"] as const;
 const VALID_PERMISSION_MODES = ["open", "guarded", "read-only"] as const;
 const VALID_POLICY_MODES = ["always-on", "on-demand"] as const;
 const VALID_MANAGED_STATUSES = ["stopped", "starting", "running", "stopping", "backoff"] as const;
-const VALID_WORKSPACE_MODES = ["isolated", "shared", "inherit"] as const;
 const BUILT_IN_AGENT_PROFILE_NAMES = new Set(["default-relay", "minimal", "isolated-research"]);
 
 const BUILT_IN_AGENT_PROFILES: AgentProfile[] = [
@@ -156,33 +155,6 @@ function rowToManagedAgentState(row: ManagedAgentStateRow): ManagedAgentState {
   };
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function cleanString(value: unknown, field: string, opts: { required?: boolean; max?: number } = {}): string | undefined {
-  if (value === undefined || value === null) {
-    if (opts.required) throw new ValidationError(`${field} required`);
-    return undefined;
-  }
-  if (typeof value !== "string") throw new ValidationError(`${field} must be a string`);
-  const trimmed = value.trim();
-  if (opts.required && !trimmed) throw new ValidationError(`${field} required`);
-  if (opts.max && trimmed.length > opts.max) throw new ValidationError(`${field} must be ${opts.max} characters or fewer`);
-  return trimmed || undefined;
-}
-
-function cleanStringArray(value: unknown, field: string, opts: { required?: boolean } = {}): string[] {
-  if (value === undefined || value === null) {
-    if (opts.required) throw new ValidationError(`${field} required`);
-    return [];
-  }
-  if (!Array.isArray(value)) throw new ValidationError(`${field} must be an array of strings`);
-  const cleaned = value.map((item) => cleanString(item, `${field} item`, { max: 120 })).filter(Boolean) as string[];
-  if (cleaned.length > 100) throw new ValidationError(`${field} can contain at most 100 values`);
-  return [...new Set(cleaned)];
-}
-
 function cleanStringRecord(value: unknown, field: string): Record<string, string> {
   if (value === undefined || value === null) return {};
   if (!isRecord(value)) throw new ValidationError(`${field} must be an object`);
@@ -213,13 +185,6 @@ function cleanNumber(value: unknown, field: string, opts: { min: number; max: nu
   return value;
 }
 
-function cleanEnum<T extends readonly string[]>(value: unknown, field: string, valid: T): T[number] {
-  if (typeof value !== "string" || !valid.includes(value)) {
-    throw new ValidationError(`${field} must be one of: ${valid.join(", ")}`);
-  }
-  return value as T[number];
-}
-
 function agentProfileDefaults(input: Pick<AgentProfile, "name" | "base"> & Partial<AgentProfile>): AgentProfile {
   const isolated = input.base !== "host";
   return {
@@ -296,7 +261,7 @@ function validateAgentProfile(key: string, value: unknown): AgentProfile {
       : cleanEnum(value.provider, "provider", VALID_PROFILE_PROVIDERS),
     instructions: {
       system: cleanString(instructions.system, "instructions.system", { max: 16_000 }),
-      append: cleanStringArray(instructions.append, "instructions.append"),
+      append: cleanStringArray(instructions.append, "instructions.append", { itemMax: 120, maxItems: 100 }) ?? [],
       repoInstructions: instructions.repoInstructions === undefined
         ? defaults.instructions.repoInstructions
         : cleanEnum(instructions.repoInstructions, "instructions.repoInstructions", VALID_PROFILE_INSTRUCTION_POLICIES),
@@ -343,16 +308,16 @@ function validateSpawnPolicy(key: string, value: unknown): SpawnPolicy {
     enabled: value.enabled === undefined ? true : cleanBoolean(value.enabled, "enabled"),
     orchestratorId: cleanString(value.orchestratorId, "orchestratorId", { required: true, max: 200 })!,
     cwd: cleanString(value.cwd, "cwd", { required: true, max: 1000 })!,
-    provider: cleanEnum(value.provider, "provider", VALID_PROVIDERS) as SpawnProvider,
+    provider: cleanEnum(value.provider, "provider", SPAWN_PROVIDERS) as SpawnProvider,
     workspaceMode: value.workspaceMode === undefined || value.workspaceMode === null ? "inherit" : cleanEnum(value.workspaceMode, "workspaceMode", VALID_WORKSPACE_MODES),
     rig: cleanString(value.rig, "rig", { max: 120 }),
     model: cleanString(value.model, "model", { max: 120 }),
     effort: value.effort === undefined || value.effort === null ? undefined : cleanEnum(value.effort, "effort", VALID_EFFORTS) as ProviderEffort,
     profile: cleanString(value.profile, "profile", { max: 120 }),
-    providerArgs: cleanStringArray(value.providerArgs, "providerArgs"),
+    providerArgs: cleanStringArray(value.providerArgs, "providerArgs", { itemMax: 120, maxItems: 100 }) ?? [],
     prompt: cleanString(value.prompt, "prompt", { max: 16_000 }),
-    tags: cleanStringArray(value.tags, "tags"),
-    capabilities: cleanStringArray(value.capabilities, "capabilities"),
+    tags: cleanStringArray(value.tags, "tags", { itemMax: 120, maxItems: 100 }) ?? [],
+    capabilities: cleanStringArray(value.capabilities, "capabilities", { itemMax: 120, maxItems: 100 }) ?? [],
     label: cleanString(value.label, "label", { max: 120 }),
     mode,
     permissionMode: cleanEnum(value.permissionMode, "permissionMode", VALID_PERMISSION_MODES),
@@ -363,7 +328,7 @@ function validateSpawnPolicy(key: string, value: unknown): SpawnPolicy {
   try {
     resolveProviderSelection({ provider: policy.provider, model: policy.model, effort: policy.effort });
   } catch (error) {
-    throw new ValidationError(error instanceof Error ? error.message : String(error));
+    throw new ValidationError(errMessage(error));
   }
   if (policy.profile && !getAgentProfile(policy.profile)) throw new ValidationError("agent profile not found");
   if (mode === "on-demand") policy.onDemand = cleanOnDemand(value.onDemand);
@@ -411,7 +376,7 @@ function validateStewardConfig(value: unknown): StewardConfig {
   if (!isRecord(value)) throw new ValidationError("steward config value must be an object");
   const config: StewardConfig = {
     enabled: value.enabled === undefined ? false : cleanBoolean(value.enabled, "enabled"),
-    provider: cleanEnum(value.provider, "provider", VALID_PROVIDERS) as SpawnProvider,
+    provider: cleanEnum(value.provider, "provider", SPAWN_PROVIDERS) as SpawnProvider,
     model: cleanString(value.model, "model", { max: 120 }),
     effort: value.effort === undefined || value.effort === null ? undefined : cleanEnum(value.effort, "effort", VALID_EFFORTS) as ProviderEffort,
     permissionMode: (value.permissionMode === undefined || value.permissionMode === null
@@ -426,7 +391,7 @@ function validateStewardConfig(value: unknown): StewardConfig {
   try {
     resolveProviderSelection({ provider: config.provider, model: config.model, effort: config.effort });
   } catch (error) {
-    throw new ValidationError(error instanceof Error ? error.message : String(error));
+    throw new ValidationError(errMessage(error));
   }
   return config;
 }
@@ -484,7 +449,7 @@ const WORKSPACE_CONFIG_DEFAULTS: WorkspaceConfig = {
 
 function validateWorkspaceConfig(value: unknown): WorkspaceConfig {
   if (!isRecord(value)) throw new ValidationError("workspace config value must be an object");
-  const symlinkPaths = cleanStringArray(value.symlinkPaths, "symlinkPaths");
+  const symlinkPaths = cleanStringArray(value.symlinkPaths, "symlinkPaths", { itemMax: 120, maxItems: 100 }) ?? [];
   // Reject absolute paths and parent-traversal up front: symlink sources must stay
   // inside the main checkout. The orchestrator re-checks containment at link time,
   // but failing here gives the operator immediate feedback in the dashboard.
@@ -721,7 +686,7 @@ function listManagedAgentStates(): ManagedAgentState[] {
 
 export function upsertManagedAgentState(input: ManagedAgentStateInput): ManagedAgentState {
   if (!VALID_MANAGED_STATUSES.includes(input.status)) throw new ValidationError("status must be a managed-agent status");
-  if (!VALID_PROVIDERS.includes(input.provider)) throw new ValidationError("provider must be claude or codex");
+  if (!SPAWN_PROVIDERS.includes(input.provider)) throw new ValidationError("provider must be claude or codex");
   const now = input.updatedAt ?? Date.now();
   getDb().query(`
     INSERT INTO managed_agent_state (

package/src/connectors.ts

@@ -3,6 +3,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import type { ConnectorAction, ConnectorActionResult, ConnectorManifest, ConnectorSummary } from "./types";
 import { ValidationError } from "./db";
+import { isRecord } from "agent-relay-sdk";
 
 const CONNECTOR_SCHEMA = "agent-relay.connector.v1";
 const VALID_KINDS = new Set(["channel", "event", "provider", "orchestrator"]);
@@ -34,10 +35,6 @@ function readRecordFile(path: string): Record<string, unknown> | undefined {
   return isRecord(parsed) ? parsed : undefined;
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function validateConnectorId(id: string): void {
   if (!/^[a-z0-9][a-z0-9._-]{0,79}$/.test(id)) {
     throw new ValidationError("connector id must be lowercase alphanumeric plus dot, underscore, or dash");

package/src/contracts.ts

@@ -1,3 +1,5 @@
+import { isRecord, stringValue } from "agent-relay-sdk";
+
 export const CONTRACT_VERSIONS = {
   relayApi: 1,
   orchestratorProtocol: 3,
@@ -95,10 +97,6 @@ function rangeLabel(requirement: ContractRequirement): string {
   return `>=${requirement.min} <${requirement.maxExclusive}`;
 }
 
-function stringValue(value: unknown): string | undefined {
-  return typeof value === "string" && value.trim() ? value.trim() : undefined;
-}
-
 function positiveInteger(value: unknown): number | undefined {
   const parsed = typeof value === "number"
     ? value
@@ -106,7 +104,3 @@ function positiveInteger(value: unknown): number | undefined {
   if (parsed === undefined || !Number.isInteger(parsed) || parsed <= 0) return undefined;
   return parsed;
 }
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/src/daemon.ts

@@ -1,4 +1,5 @@
 import { execFile } from "node:child_process";
+import { shellQuote } from "agent-relay-sdk/shell-utils";
 import { constants, existsSync } from "node:fs";
 import { access, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
@@ -460,10 +461,6 @@ function quoteSystemdArg(value: string): string {
   return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
 }
 
-function shellQuote(value: string): string {
-  return `'${value.replace(/'/g, "'\\''")}'`;
-}
-
 function xmlEscape(value: string): string {
   return value
     .replace(/&/g, "&")

package/src/db.ts

@@ -1,6 +1,8 @@
 import { Database } from "bun:sqlite";
 import { randomUUID } from "node:crypto";
+import { isRecord, stringValue } from "agent-relay-sdk";
 import { ORCHESTRATOR_PROTOCOL_VERSION, VERSION } from "./config.ts";
+import { parseJson } from "./utils";
 import {
   CONTRACT_REQUIREMENTS,
   contractCompatibility,
@@ -1173,13 +1175,6 @@ export function getDb(): Database {
 export class ValidationError extends Error {}
 class ClaimError extends Error {}
 
-function parseJson<T>(raw: string, fallback: T): T {
-  try {
-    return JSON.parse(raw);
-  } catch {
-    return fallback;
-  }
-}
 
 function parseStringArray(raw: string): string[] {
   const parsed = parseJson<unknown>(raw, []);
@@ -1191,10 +1186,6 @@ function normalizeTags(tags: string[] | undefined): string[] {
   return [...new Set((tags ?? []).map((tag) => tag.trim()).filter(Boolean))];
 }
 
-function stringValue(value: unknown): string | undefined {
-  return typeof value === "string" && value.trim() ? value.trim() : undefined;
-}
-
 function inferAgentKind(input: Pick<RegisterAgentInput, "id" | "kind" | "tags" | "capabilities" | "meta">): AgentKind {
   if (input.kind) return input.kind;
   if (input.id === "user") return "user";
@@ -2418,10 +2409,6 @@ function runtimeTokenJtisFromMeta(meta: Record<string, unknown>): string[] {
   return [...jtis];
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-
 // --- Tasks ---
 
 const TASK_SELECT = "SELECT * FROM tasks";
@@ -5092,14 +5079,21 @@ function upsertWorkspaceFromManagedAgent(agent: ManagedAgent): WorkspaceRecord |
     // preserved and metadata is merged, not replaced.
     const existing = getWorkspace(workspace.id);
     const preserveStatus = existing != null && existing.status !== "active";
+    // The branch (and advanced base) change ONLY via the relay's own land-and-continue
+    // recycle (setWorkspaceBranch repoints to `<branch>-N` and bumps base_sha). The
+    // runner keeps re-reporting its spawn-time branch on every heartbeat, and the
+    // recycle returns status to "active" — so without this the next heartbeat clobbers
+    // the repoint back to the original branch, and the next land targets a deleted
+    // branch and strands the work (vent #62 follow-up). Trust the existing row's
+    // branch/base over registration; only a brand-new row takes the runner's values.
     return upsertWorkspace({
       id: workspace.id,
       repoRoot: workspace.repoRoot,
       sourceCwd: workspace.sourceCwd ?? agent.cwd,
       worktreePath: workspace.worktreePath,
-      branch: workspace.branch,
+      branch: existing?.branch ?? workspace.branch,
       baseRef: workspace.baseRef,
-      baseSha: workspace.baseSha,
+      baseSha: existing?.baseSha ?? workspace.baseSha,
       mode: workspace.mode,
       requestedMode: workspace.requestedMode,
       status: preserveStatus ? existing!.status : (workspace.status ?? "active"),
@@ -5241,6 +5235,18 @@ export function updateWorkspaceStatus(id: string, status: WorkspaceStatus, metad
   return getWorkspace(id);
 }
 
+// Repoint a workspace row at a recycled branch after a land-and-continue merge
+// (#206): the worktree switched to a fresh branch cut from the advanced base, so
+// the row must track the new branch (else the next merge command targets a branch
+// that no longer exists) and the new base sha. No-op if the row is gone.
+export function setWorkspaceBranch(id: string, branch: string, baseSha?: string): WorkspaceRecord | null {
+  const existing = getWorkspace(id);
+  if (!existing) return null;
+  db.query(`UPDATE workspaces SET branch = ?, base_sha = coalesce(?, base_sha), updated_at = ? WHERE id = ?`)
+    .run(branch, baseSha ?? null, Date.now(), id);
+  return getWorkspace(id);
+}
+
 // Workspace statuses that count as "live" for stewardship — an agent owning one
 // of these is a candidate steward; the repo is worth coordinating.
 const STEWARD_LIVE_STATUSES = "'active', 'ready', 'conflict', 'review_requested', 'merge_planned'";

package/src/dev.ts

@@ -1,4 +1,5 @@
 import { execFile } from "node:child_process";
+import { shellQuote } from "agent-relay-sdk/shell-utils";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { homedir, hostname as osHostname } from "node:os";
@@ -504,7 +505,3 @@ function quote(value: string): string {
   if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(value)) return value;
   return `"${value.replace(/(["\\$`])/g, "\\$1")}"`;
 }
-
-function shellQuote(value: string): string {
-  return `'${value.replace(/'/g, "'\\''")}'`;
-}

package/src/http-body.ts

@@ -0,0 +1,49 @@
+/** Concatenate body chunks into a single contiguous Uint8Array. */
+export function concatBytes(chunks: Uint8Array[]): Uint8Array {
+  const total = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+  const output = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    output.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return output;
+}
+
+/** Wrap bytes in a single-chunk ReadableStream (e.g. for artifact `storage.store`). */
+export function bytesToStream(bytes: Uint8Array): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(bytes);
+      controller.close();
+    },
+  });
+}
+
+/**
+ * Drain a request body stream into a single Uint8Array, enforcing a byte cap.
+ * Returns a 413 result the moment the running total exceeds `maxBytes` (cancels
+ * the reader). Single home for the read-loop that `parseBody` (routes) and
+ * `parseJsonRpcRequest` (mcp) each open-coded — they differed only in the cap.
+ * Callers handle body-absence and decoding.
+ */
+export async function readBodyBytes(
+  body: ReadableStream<Uint8Array>,
+  maxBytes: number,
+): Promise<{ ok: true; bytes: Uint8Array } | { ok: false; status: 413; error: string }> {
+  const reader = body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (!value) continue;
+    total += value.byteLength;
+    if (total > maxBytes) {
+      await reader.cancel().catch(() => {});
+      return { ok: false, status: 413, error: `request body exceeds ${maxBytes} bytes` };
+    }
+    chunks.push(value);
+  }
+  return { ok: true, bytes: concatBytes(chunks) };
+}

package/src/index.ts

@@ -11,6 +11,7 @@ import { getCompactionWatch } from "./compaction-watch";
 import { getConfig, setConfig } from "./config-store";
 import { startConnectorStatusPoller } from "./connectors";
 import { resolve, sep } from "path";
+import { gzipSync, brotliCompressSync, constants as zlibConstants } from "node:zlib";
 import {
   VERSION,
 } from "./config";
@@ -29,6 +30,7 @@ import {
 } from "./security";
 import { handleCli } from "./cli";
 import { startMaintenanceScheduler } from "./maintenance";
+import { errMessage } from "agent-relay-sdk";
 
 async function main(): Promise<void> {
   const result = await handleCli(process.argv.slice(2));
@@ -264,8 +266,7 @@ export function createFetchHandler(
     }
     const file = Bun.file(resolved);
     if (await file.exists()) {
-      const headers = staticHeaders(requested);
-      return new Response(file, { headers });
+      return await serveStaticFile(req, resolved, requested, file);
     }
 
     return Response.json({ error: "not found" }, { status: 404 });
@@ -275,13 +276,108 @@ export function createFetchHandler(
   };
 }
 
+// In-memory compressed-variant cache, keyed by absolute path. Invalidated when
+// the file's mtime/size changes, so a rebuilt bundle is recompressed on next
+// request. The single-file dashboard bundle (~10 MB unminified) is served
+// uncompressed by Bun.serve otherwise; brotli/gzip cuts it ~6-7x on the wire,
+// which is the dominant cost over high-latency links. Further wins (minify,
+// code-split) tracked in #200 / #201.
+type CompressedVariant = { body: Uint8Array; encoding: "br" | "gzip" };
+const compressedCache = new Map<
+  string,
+  { mtimeMs: number; size: number; br?: Uint8Array; gzip?: Uint8Array }
+>();
+
+const COMPRESSIBLE = /\.(html|js|css|svg|json|webmanifest|map)$/;
+
+function isCompressible(pathname: string): boolean {
+  return pathname === "/" || pathname.endsWith("/") || COMPRESSIBLE.test(pathname);
+}
+
+function negotiateEncoding(req: Request): "br" | "gzip" | null {
+  const accept = req.headers.get("accept-encoding") ?? "";
+  if (/\bbr\b/.test(accept)) return "br";
+  if (/\bgzip\b/.test(accept)) return "gzip";
+  return null;
+}
+
+async function getCompressedVariant(
+  resolved: string,
+  mtimeMs: number,
+  size: number,
+  encoding: "br" | "gzip",
+  raw: () => Promise<Uint8Array>,
+): Promise<CompressedVariant> {
+  let entry = compressedCache.get(resolved);
+  if (!entry || entry.mtimeMs !== mtimeMs || entry.size !== size) {
+    entry = { mtimeMs, size };
+    compressedCache.set(resolved, entry);
+  }
+  const cached = entry[encoding];
+  if (cached) return { body: cached, encoding };
+  const data = await raw();
+  const body =
+    encoding === "br"
+      ? brotliCompressSync(data, {
+          params: {
+            // Quality 5 ~ near-gzip CPU, much better ratio; this runs once per
+            // file version then serves from cache, so cost is amortized away.
+            [zlibConstants.BROTLI_PARAM_QUALITY]: 5,
+            [zlibConstants.BROTLI_PARAM_SIZE_HINT]: data.byteLength,
+          },
+        })
+      : gzipSync(data, { level: 6 });
+  entry[encoding] = body;
+  return { body, encoding };
+}
+
+async function serveStaticFile(
+  req: Request,
+  resolved: string,
+  requested: string,
+  file: ReturnType<typeof Bun.file>,
+): Promise<Response> {
+  const stat = await file.stat();
+  const headers = staticHeaders(requested);
+  // Strong-ish validator from mtime + size; encoding-suffixed so a client never
+  // gets a 304 for a variant it didn't store.
+  const baseTag = `${stat.mtime.getTime().toString(36)}-${stat.size.toString(36)}`;
+
+  const encoding = isCompressible(requested) ? negotiateEncoding(req) : null;
+  const etag = `"${baseTag}${encoding ? `-${encoding}` : ""}"`;
+  headers.set("ETag", etag);
+  if (req.headers.get("if-none-match") === etag) {
+    return new Response(null, { status: 304, headers });
+  }
+
+  if (encoding) {
+    const { body } = await getCompressedVariant(
+      resolved,
+      stat.mtime.getTime(),
+      stat.size,
+      encoding,
+      () => file.bytes(),
+    );
+    headers.set("Content-Encoding", encoding);
+    headers.set("Vary", "Accept-Encoding");
+    headers.set("Content-Length", String(body.byteLength));
+    // Uint8Array is a valid BodyInit at runtime in Bun; the DOM lib types omit it.
+    return new Response(body as unknown as BodyInit, { headers });
+  }
+
+  return new Response(file, { headers });
+}
+
 function staticHeaders(pathname: string): Headers {
   const headers = new Headers();
   const contentType = staticContentType(pathname);
   if (contentType) headers.set("Content-Type", contentType);
-  if (pathname === "/sw.js") {
+  // The shell + PWA control files must always revalidate (ETag makes this a
+  // cheap 304 when unchanged). Hashing isn't available — viteSingleFile inlines
+  // everything into index.html — so no immutable long-cache assets exist.
+  if (pathname === "/sw.js" || pathname === "/manifest.webmanifest") {
     headers.set("Cache-Control", "no-cache");
-  } else if (pathname === "/manifest.webmanifest") {
+  } else if (pathname === "/" || pathname.endsWith("/") || pathname.endsWith(".html")) {
     headers.set("Cache-Control", "no-cache");
   }
   return headers;
@@ -298,7 +394,7 @@ function staticContentType(pathname: string): string | undefined {
 
 if (import.meta.main) {
   main().catch((error) => {
-    console.error(error instanceof Error ? error.message : String(error));
+    console.error(errMessage(error));
     process.exit(1);
   });
 }

package/src/lifecycle-manager.ts

@@ -1,5 +1,5 @@
-import { isAbsolute, relative, resolve } from "node:path";
 import { createCommand } from "./commands-db";
+import { isPathWithinBase } from "./utils";
 import { createActivityEvent, deleteWorkspace, getAgent, getDb, getOrchestrator, listOrchestrators, listWorkspaces, resolveQueuedPolicyMessages } from "./db";
 import {
   getManagedAgentState,
@@ -8,7 +8,9 @@ import {
   upsertManagedAgentState,
 } from "./config-store";
 import { emitRelayEvent } from "./events";
+import { emitCommandEvent } from "./command-events";
 import { buildManagedSpawnParams } from "./managed-policy";
+import { generateSpawnRequestId } from "./spawn-command";
 import type { Command, ManagedAgent, ManagedAgentState, ManagedSessionExitDiagnostics, SpawnPolicy } from "./types";
 
 const DEFAULT_TICK_MS = 10_000;
@@ -208,7 +210,7 @@ export class LifecycleManager {
       this.emitState(state);
       return null;
     }
-    const spawnRequestId = `sp_${crypto.randomUUID()}`;
+    const spawnRequestId = generateSpawnRequestId();
     const state = upsertManagedAgentState({
       policyName: policy.name,
       status: "starting",
@@ -230,7 +232,7 @@ export class LifecycleManager {
         reason,
       },
     });
-    this.emitCommand(command);
+    emitCommandEvent(command, "command.requested");
     return command;
   }
 
@@ -270,7 +272,7 @@ export class LifecycleManager {
         requestedAt: this.now(),
       },
     });
-    this.emitCommand(command);
+    emitCommandEvent(command, "command.requested");
     return command;
   }
 
@@ -278,7 +280,7 @@ export class LifecycleManager {
     const orch = getOrchestrator(policy.orchestratorId);
     if (!orch) return null;
     const state = getManagedAgentState(policy.name);
-    const restartRequestId = `sp_${crypto.randomUUID()}`;
+    const restartRequestId = generateSpawnRequestId();
     const restartSpawn = buildManagedSpawnParams(policy, restartRequestId, { createdBy: "lifecycle-manager", requestedAt: this.now() });
     const restarted = upsertManagedAgentState({
       policyName: policy.name,
@@ -314,7 +316,7 @@ export class LifecycleManager {
         requestedAt: this.now(),
       },
     });
-    this.emitCommand(command);
+    emitCommandEvent(command, "command.requested");
     return command;
   }
 
@@ -406,7 +408,7 @@ export class LifecycleManager {
         requestedAt: this.now(),
       },
     });
-    this.emitCommand(command);
+    emitCommandEvent(command, "command.requested");
     return command;
   }
 
@@ -564,15 +566,6 @@ export class LifecycleManager {
     });
   }
 
-  private emitCommand(command: Command): void {
-    emitRelayEvent({
-      type: "command.requested",
-      source: command.source,
-      subject: command.id,
-      data: { command },
-    });
-  }
-
   // When an agent disappears, its isolated worktrees would otherwise sit
   // `active` on disk forever. Dispatch a workspace.reconcile command to the
   // owning orchestrator, which probes the worktree and either removes it (no
@@ -593,7 +586,7 @@ export class LifecycleManager {
     const orchestrators = listOrchestrators();
     for (const ws of candidates) {
       const orch = orchestrators.find(
-        (candidate) => candidate.status === "online" && pathWithinBaseDir(ws.sourceCwd, candidate.baseDir),
+        (candidate) => candidate.status === "online" && isPathWithinBase(ws.sourceCwd, candidate.baseDir),
       );
       if (!orch) continue;
       const command = createCommand({
@@ -614,17 +607,11 @@ export class LifecycleManager {
           requestedAt: this.now(),
         },
       });
-      this.emitCommand(command);
+      emitCommandEvent(command, "command.requested");
     }
   }
 }
 
-function pathWithinBaseDir(path: string | undefined, baseDir: string | undefined): boolean {
-  if (!path || !baseDir) return false;
-  const rel = relative(resolve(baseDir), resolve(path));
-  return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
-}
-
 let singleton: LifecycleManager | null = null;
 
 export function getLifecycleManager(): LifecycleManager {