@harness-engineering/orchestrator 0.4.1 → 0.4.3

package/dist/index.mjs

@@ -258,11 +258,18 @@ import * as path from "path";
 var InteractionQueue = class {
   dir;
   pushListeners = [];
+  emitter;
   /**
    * @param dir - Directory path for storing interaction JSON files
+   * @param emitter - Optional event bus that receives `interaction.created`
+   *   and `interaction.resolved` events. When omitted, the queue behaves as
+   *   it did pre-Phase-2 (no emission). Phase 2 Task 8 wires the
+   *   orchestrator (itself an EventEmitter) in as the bus so the SSE
+   *   handler (`GET /api/v1/events`) can fan these out to clients.
    */
-  constructor(dir) {
+  constructor(dir, emitter) {
     this.dir = dir;
+    this.emitter = emitter ?? null;
   }
   /**
    * Register a listener that fires after each push.
@@ -290,6 +297,13 @@ var InteractionQueue = class {
     for (const listener of this.pushListeners) {
       listener(interaction);
     }
+    this.emitter?.emit("interaction.created", {
+      id: interaction.id,
+      issueId: interaction.issueId,
+      type: interaction.type,
+      status: interaction.status,
+      createdAt: interaction.createdAt
+    });
   }
   /**
    * List all interactions (regardless of status).
@@ -336,6 +350,13 @@ var InteractionQueue = class {
     const interaction = JSON.parse(raw);
     interaction.status = status;
     await fs.writeFile(filePath, JSON.stringify(interaction, null, 2), "utf-8");
+    if (status === "resolved") {
+      this.emitter?.emit("interaction.resolved", {
+        id,
+        status: "resolved",
+        resolvedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    }
   }
 };
 
@@ -3907,6 +3928,13 @@ function extractUsage(usage) {
     cacheReadTokens: usage.cache_read_input_tokens ?? 0
   };
 }
+function recordCacheUsage(recorder, rawUsage) {
+  if (!recorder || !rawUsage) return;
+  const cacheRead = rawUsage.cache_read_input_tokens ?? 0;
+  const cacheCreation = rawUsage.cache_creation_input_tokens ?? 0;
+  if (cacheRead === 0 && cacheCreation === 0) return;
+  recorder.record("anthropic", cacheRead > 0, cacheCreation, cacheRead);
+}
 function extractToolResultText(blockContent) {
   if (typeof blockContent === "string") return blockContent;
   if (!Array.isArray(blockContent)) return "";
@@ -3988,8 +4016,10 @@ function mapClaudeEvent(rawEvent, sessionId) {
 var ClaudeBackend = class {
   name = "claude";
   command;
-  constructor(command = "claude") {
-    this.command = command;
+  cacheMetrics;
+  constructor(command = "claude", options = {}) {
+    this.command = options.command ?? command;
+    if (options.cacheMetrics) this.cacheMetrics = options.cacheMetrics;
   }
   async startSession(params) {
     const session = {
@@ -4055,6 +4085,9 @@ var ClaudeBackend = class {
                 totalTokens: 0
               }
             };
+            recordCacheUsage(this.cacheMetrics, rawEvent.usage);
+          } else if (rawEvent.type === "assistant" && rawEvent.message?.stop_reason !== null && rawEvent.message?.stop_reason !== void 0) {
+            recordCacheUsage(this.cacheMetrics, rawEvent.message?.usage);
           }
           for (const mapped of mapClaudeEvent(rawEvent, session.sessionId)) {
             yield mapped;
@@ -4923,12 +4956,14 @@ function makeGetModel(model) {
   if (Array.isArray(model) && model.length > 0) return () => model[0] ?? null;
   return () => null;
 }
-function createBackend(def) {
+function createBackend(def, options = {}) {
   switch (def.type) {
     case "mock":
       return new MockBackend();
     case "claude":
-      return new ClaudeBackend(def.command ?? "claude");
+      return new ClaudeBackend(def.command ?? "claude", {
+        ...options.cacheMetrics ? { cacheMetrics: options.cacheMetrics } : {}
+      });
     case "anthropic":
       return new AnthropicBackend({
         model: def.model,
@@ -5366,11 +5401,12 @@ var OrchestratorBackendFactory = class {
     const def = this.router.resolveDefinition(useCase);
     const name = this.router.resolve(useCase);
     let backend;
+    const createOpts = this.opts.cacheMetrics ? { cacheMetrics: this.opts.cacheMetrics } : {};
     if ((def.type === "local" || def.type === "pi") && this.opts.getResolverModelFor) {
       const getModel = this.opts.getResolverModelFor(name);
-      backend = getModel ? this.buildLocalLikeWithResolver(def, getModel) : createBackend(def);
+      backend = getModel ? this.buildLocalLikeWithResolver(def, getModel) : createBackend(def, createOpts);
     } else {
-      backend = createBackend(def);
+      backend = createBackend(def, createOpts);
     }
     if (this.opts.sandboxPolicy === "docker" && this.opts.container) {
       backend = this.wrapInContainer(backend);
@@ -5766,13 +5802,75 @@ function handleInteractionsRoute(req, res, queue) {
   return false;
 }
 
-// src/server/routes/plans.ts
+// src/server/routes/v1/interactions-resolve.ts
 import { z as z4 } from "zod";
+var BodySchema = z4.object({ answer: z4.unknown().optional() });
+var RESOLVE_PATH_RE = /^\/api\/v1\/interactions\/([a-zA-Z0-9_-]+)\/resolve(?:\?.*)?$/;
+function sendJSON(res, status, body) {
+  res.writeHead(status, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(body));
+}
+function handleV1InteractionsResolveRoute(req, res, queue) {
+  if (req.method !== "POST") return false;
+  const match = RESOLVE_PATH_RE.exec(req.url ?? "");
+  if (!match || !match[1]) return false;
+  if (!queue) {
+    sendJSON(res, 503, { error: "Interaction queue not available" });
+    return true;
+  }
+  const id = match[1];
+  void (async () => {
+    let raw;
+    try {
+      raw = await readBody(req);
+    } catch {
+      sendJSON(res, 413, { error: "Body too large" });
+      return;
+    }
+    if (raw.length > 0) {
+      try {
+        const json = JSON.parse(raw);
+        const parsed = BodySchema.safeParse(json);
+        if (!parsed.success) {
+          sendJSON(res, 400, { error: "Invalid body", issues: parsed.error.issues });
+          return;
+        }
+      } catch {
+        sendJSON(res, 400, { error: "Invalid JSON body" });
+        return;
+      }
+    }
+    try {
+      const existing = (await queue.list()).find((i) => i.id === id);
+      if (!existing) {
+        sendJSON(res, 404, { error: `Interaction ${id} not found` });
+        return;
+      }
+      if (existing.status === "resolved") {
+        sendJSON(res, 409, { error: `Interaction ${id} already resolved` });
+        return;
+      }
+      await queue.updateStatus(id, "resolved");
+      sendJSON(res, 200, { resolved: true });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : "Failed to resolve";
+      if (msg.includes("not found")) {
+        sendJSON(res, 404, { error: msg });
+        return;
+      }
+      sendJSON(res, 500, { error: "Internal error resolving interaction" });
+    }
+  })();
+  return true;
+}
+
+// src/server/routes/plans.ts
+import { z as z5 } from "zod";
 import * as fs9 from "fs/promises";
 import * as path9 from "path";
-var PlanWriteSchema = z4.object({
-  filename: z4.string().min(1),
-  content: z4.string().min(1)
+var PlanWriteSchema = z5.object({
+  filename: z5.string().min(1),
+  content: z5.string().min(1)
 });
 function handlePlansRoute(req, res, plansDir) {
   const { method, url } = req;
@@ -5816,7 +5914,7 @@ function handlePlansRoute(req, res, plansDir) {
 import { spawn as spawn4 } from "child_process";
 import { randomUUID as randomUUID4 } from "crypto";
 import * as readline2 from "readline";
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 var SAFE_ENV_PREFIXES = [
   "PATH",
@@ -5851,10 +5949,10 @@ function buildChildEnv() {
   }
   return env;
 }
-var ChatRequestSchema = z5.object({
-  prompt: z5.string().min(1),
-  system: z5.string().optional(),
-  sessionId: z5.string().regex(UUID_RE).optional()
+var ChatRequestSchema = z6.object({
+  prompt: z6.string().min(1),
+  system: z6.string().optional(),
+  sessionId: z6.string().regex(UUID_RE).optional()
 });
 function handleChatProxyRoute(req, res, command = "claude") {
   const { method, url } = req;
@@ -6064,11 +6162,11 @@ function extractChunks(event) {
 
 // src/server/routes/analyze.ts
 import { manualToRawWorkItem, scoreToConcernSignals } from "@harness-engineering/intelligence";
-import { z as z6 } from "zod";
-var AnalyzeRequestSchema = z6.object({
-  title: z6.string().min(1),
-  description: z6.string().optional(),
-  labels: z6.array(z6.string()).optional()
+import { z as z7 } from "zod";
+var AnalyzeRequestSchema = z7.object({
+  title: z7.string().min(1),
+  description: z7.string().optional(),
+  labels: z7.array(z7.string()).optional()
 });
 function emit2(res, event) {
   res.write(`data: ${JSON.stringify(event)}
@@ -6185,21 +6283,21 @@ import {
   ConflictError,
   makeTrackerConflictBody
 } from "@harness-engineering/core";
-import { z as z7 } from "zod";
-var AppendRoadmapRequestSchema = z7.object({
-  title: z7.string().min(1),
-  summary: z7.string().optional(),
-  labels: z7.array(z7.string()).optional(),
-  enrichedSpec: z7.object({
-    intent: z7.string(),
-    unknowns: z7.array(z7.string()),
-    ambiguities: z7.array(z7.string()),
-    riskSignals: z7.array(z7.string()),
-    affectedSystems: z7.array(z7.object({ name: z7.string() }))
+import { z as z8 } from "zod";
+var AppendRoadmapRequestSchema = z8.object({
+  title: z8.string().min(1),
+  summary: z8.string().optional(),
+  labels: z8.array(z8.string()).optional(),
+  enrichedSpec: z8.object({
+    intent: z8.string(),
+    unknowns: z8.array(z8.string()),
+    ambiguities: z8.array(z8.string()),
+    riskSignals: z8.array(z8.string()),
+    affectedSystems: z8.array(z8.object({ name: z8.string() }))
   }).optional(),
-  cmlRecommendedRoute: z7.enum(["local", "human", "simulation-required"]).optional()
+  cmlRecommendedRoute: z8.enum(["local", "human", "simulation-required"]).optional()
 });
-function sendJSON(res, status, body) {
+function sendJSON2(res, status, body) {
   res.writeHead(status, { "Content-Type": "application/json" });
   res.end(JSON.stringify(body));
 }
@@ -6208,7 +6306,7 @@ function handleRoadmapActionsRoute(req, res, roadmapPath) {
   void (async () => {
     try {
       if (!roadmapPath) {
-        sendJSON(res, 503, { error: "Roadmap path not configured" });
+        sendJSON2(res, 503, { error: "Roadmap path not configured" });
         return;
       }
       const projectRoot = path10.dirname(path10.dirname(roadmapPath));
@@ -6216,18 +6314,18 @@ function handleRoadmapActionsRoute(req, res, roadmapPath) {
       if (mode === "file-less") {
         const trackerCfg = loadTrackerClientConfigFromProject(projectRoot);
         if (!trackerCfg.ok) {
-          sendJSON(res, 500, { error: trackerCfg.error.message });
+          sendJSON2(res, 500, { error: trackerCfg.error.message });
           return;
         }
         const clientR = createTrackerClient(trackerCfg.value);
         if (!clientR.ok) {
-          sendJSON(res, 500, { error: clientR.error.message });
+          sendJSON2(res, 500, { error: clientR.error.message });
           return;
         }
         const body2 = await readBody(req);
         const parseResult = AppendRoadmapRequestSchema.safeParse(JSON.parse(body2));
         if (!parseResult.success) {
-          sendJSON(res, 400, {
+          sendJSON2(res, 400, {
             error: parseResult.error.issues[0]?.message ?? "Invalid request body"
           });
           return;
@@ -6240,13 +6338,13 @@ function handleRoadmapActionsRoute(req, res, roadmapPath) {
         const r = await clientR.value.create(newFeature);
         if (!r.ok) {
           if (r.error instanceof ConflictError) {
-            sendJSON(res, 409, makeTrackerConflictBody(r.error));
+            sendJSON2(res, 409, makeTrackerConflictBody(r.error));
             return;
           }
-          sendJSON(res, 502, { error: r.error.message });
+          sendJSON2(res, 502, { error: r.error.message });
           return;
         }
-        sendJSON(res, 201, {
+        sendJSON2(res, 201, {
           ok: true,
           featureName: r.value.name,
           externalId: r.value.externalId
@@ -6256,18 +6354,18 @@ function handleRoadmapActionsRoute(req, res, roadmapPath) {
       const body = await readBody(req);
       const result = AppendRoadmapRequestSchema.safeParse(JSON.parse(body));
       if (!result.success) {
-        sendJSON(res, 400, { error: result.error.issues[0]?.message ?? "Invalid request body" });
+        sendJSON2(res, 400, { error: result.error.issues[0]?.message ?? "Invalid request body" });
         return;
       }
       const parsed = result.data;
       if (parsed.title.includes("\n") || parsed.title.includes("###")) {
-        sendJSON(res, 400, { error: "Title must not contain newlines or markdown headings" });
+        sendJSON2(res, 400, { error: "Title must not contain newlines or markdown headings" });
         return;
       }
       const content = await fs10.readFile(roadmapPath, "utf-8");
       const roadmapResult = parseRoadmap2(content);
       if (!roadmapResult.ok) {
-        sendJSON(res, 500, { error: "Failed to parse roadmap file" });
+        sendJSON2(res, 500, { error: "Failed to parse roadmap file" });
         return;
       }
       const roadmap = roadmapResult.value;
@@ -6297,11 +6395,11 @@ function handleRoadmapActionsRoute(req, res, roadmapPath) {
       const serialized = serializeRoadmap2(roadmap);
       await fs10.writeFile(tmpPath, serialized, "utf-8");
       await fs10.rename(tmpPath, roadmapPath);
-      sendJSON(res, 201, { ok: true, featureName: parsed.title });
+      sendJSON2(res, 201, { ok: true, featureName: parsed.title });
     } catch (err) {
       const msg = err instanceof Error ? err.message : "Failed to append to roadmap";
       if (!res.headersSent) {
-        sendJSON(res, 500, { error: msg });
+        sendJSON2(res, 500, { error: msg });
       }
     }
   })();
@@ -6310,13 +6408,13 @@ function handleRoadmapActionsRoute(req, res, roadmapPath) {
 
 // src/server/routes/dispatch-actions.ts
 import { createHash as createHash3 } from "crypto";
-import { z as z8 } from "zod";
-var DispatchAdHocRequestSchema = z8.object({
-  title: z8.string().min(1),
-  description: z8.string().optional(),
-  labels: z8.array(z8.string()).optional()
+import { z as z9 } from "zod";
+var DispatchAdHocRequestSchema = z9.object({
+  title: z9.string().min(1),
+  description: z9.string().optional(),
+  labels: z9.array(z9.string()).optional()
 });
-function sendJSON2(res, status, body) {
+function sendJSON3(res, status, body) {
   res.writeHead(status, { "Content-Type": "application/json" });
   res.end(JSON.stringify(body));
 }
@@ -6330,13 +6428,13 @@ function handleDispatchActionsRoute(req, res, dispatchFn) {
   void (async () => {
     try {
       if (!dispatchFn) {
-        sendJSON2(res, 503, { error: "Dispatch not available" });
+        sendJSON3(res, 503, { error: "Dispatch not available" });
         return;
       }
       const body = await readBody(req);
       const result = DispatchAdHocRequestSchema.safeParse(JSON.parse(body));
       if (!result.success) {
-        sendJSON2(res, 400, { error: result.error.issues[0]?.message ?? "Invalid request body" });
+        sendJSON3(res, 400, { error: result.error.issues[0]?.message ?? "Invalid request body" });
         return;
       }
       const parsed = result.data;
@@ -6359,11 +6457,11 @@ function handleDispatchActionsRoute(req, res, dispatchFn) {
         externalId: null
       };
       await dispatchFn(issue);
-      sendJSON2(res, 200, { ok: true, issueId: id });
+      sendJSON3(res, 200, { ok: true, issueId: id });
     } catch (err) {
       const msg = err instanceof Error ? err.message : "Dispatch failed";
       if (!res.headersSent) {
-        sendJSON2(res, 500, { error: msg });
+        sendJSON3(res, 500, { error: msg });
       }
     }
   })();
@@ -6411,7 +6509,7 @@ function handleAnalysesRoute(req, res, archive) {
 }
 
 // src/server/routes/maintenance.ts
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 function toMaintenanceHistoryEntry(r) {
   const durationMs = r.startedAt && r.completedAt ? Date.parse(r.completedAt) - Date.parse(r.startedAt) : 0;
   const status = r.status === "failure" ? "failed" : r.status;
@@ -6426,27 +6524,27 @@ function toMaintenanceHistoryEntry(r) {
   if (r.error !== void 0) entry.error = r.error;
   return entry;
 }
-var TriggerRequestSchema = z9.object({
-  taskId: z9.string().min(1)
+var TriggerRequestSchema = z10.object({
+  taskId: z10.string().min(1)
 });
-function sendJSON3(res, status, body) {
+function sendJSON4(res, status, body) {
   res.writeHead(status, { "Content-Type": "application/json" });
   res.end(JSON.stringify(body));
 }
 function handleGetSchedule(res, deps) {
   const status = deps.scheduler.getStatus();
-  sendJSON3(res, 200, status.schedule);
+  sendJSON4(res, 200, status.schedule);
 }
 function handleGetStatus(res, deps) {
   const status = deps.scheduler.getStatus();
-  sendJSON3(res, 200, status);
+  sendJSON4(res, 200, status);
 }
 function handleGetHistory(res, deps, queryString) {
   const params = new URLSearchParams(queryString);
   const limit = Math.min(100, Math.max(1, parseInt(params.get("limit") ?? "20", 10) || 20));
   const offset = Math.max(0, parseInt(params.get("offset") ?? "0", 10) || 0);
   const history = deps.reporter.getHistory(limit, offset).map(toMaintenanceHistoryEntry);
-  sendJSON3(res, 200, history);
+  sendJSON4(res, 200, history);
 }
 function handlePostTrigger(req, res, deps) {
   void (async () => {
@@ -6456,20 +6554,20 @@ function handlePostTrigger(req, res, deps) {
       try {
         json = JSON.parse(body);
       } catch {
-        sendJSON3(res, 400, { error: "Invalid JSON body" });
+        sendJSON4(res, 400, { error: "Invalid JSON body" });
         return;
       }
       const result = TriggerRequestSchema.safeParse(json);
       if (!result.success) {
-        sendJSON3(res, 400, { error: "Missing taskId string" });
+        sendJSON4(res, 400, { error: "Missing taskId string" });
         return;
       }
       await deps.triggerFn(result.data.taskId);
-      sendJSON3(res, 200, { ok: true, taskId: result.data.taskId });
+      sendJSON4(res, 200, { ok: true, taskId: result.data.taskId });
     } catch (err) {
       const msg = err instanceof Error ? err.message : "Trigger failed";
       if (!res.headersSent) {
-        sendJSON3(res, 500, { error: msg });
+        sendJSON4(res, 500, { error: msg });
       }
     }
   })();
@@ -6478,7 +6576,7 @@ function handleMaintenanceRoute(req, res, deps) {
   const { method, url } = req;
   if (!url?.startsWith("/api/maintenance/")) return false;
   if (!deps) {
-    sendJSON3(res, 503, { error: "Maintenance not available" });
+    sendJSON4(res, 503, { error: "Maintenance not available" });
     return true;
   }
   const [pathname, queryString] = url.split("?");
@@ -6499,16 +6597,296 @@ function handleMaintenanceRoute(req, res, deps) {
     handlePostTrigger(req, res, deps);
     return true;
   }
-  sendJSON3(res, 404, { error: "Not found" });
+  sendJSON4(res, 404, { error: "Not found" });
   return true;
 }
 
+// src/server/routes/v1/jobs-maintenance.ts
+import { randomBytes } from "crypto";
+import { z as z11 } from "zod";
+var BodySchema2 = z11.object({
+  taskId: z11.string().min(1).max(200),
+  params: z11.record(z11.unknown()).optional()
+});
+function sendJSON5(res, status, body) {
+  res.writeHead(status, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(body));
+}
+function handleV1JobsMaintenanceRoute(req, res, deps) {
+  if (req.url !== "/api/v1/jobs/maintenance" || req.method !== "POST") return false;
+  if (!deps) {
+    sendJSON5(res, 503, { error: "Maintenance not available" });
+    return true;
+  }
+  void (async () => {
+    let raw;
+    try {
+      raw = await readBody(req);
+    } catch (err) {
+      sendJSON5(res, 413, { error: err instanceof Error ? err.message : "Body too large" });
+      return;
+    }
+    let json;
+    try {
+      json = JSON.parse(raw);
+    } catch {
+      sendJSON5(res, 400, { error: "Invalid JSON body" });
+      return;
+    }
+    const parsed = BodySchema2.safeParse(json);
+    if (!parsed.success) {
+      sendJSON5(res, 400, { error: "Invalid body", issues: parsed.error.issues });
+      return;
+    }
+    const runId = `run_${randomBytes(8).toString("hex")}`;
+    try {
+      await deps.triggerFn(parsed.data.taskId);
+      sendJSON5(res, 200, { ok: true, taskId: parsed.data.taskId, runId });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : "Trigger failed";
+      const lower = msg.toLowerCase();
+      if (lower.includes("unknown task") || lower.includes("not found")) {
+        sendJSON5(res, 404, { error: msg });
+        return;
+      }
+      if (lower.includes("already running")) {
+        sendJSON5(res, 409, { error: msg });
+        return;
+      }
+      sendJSON5(res, 500, { error: "Internal error triggering maintenance task" });
+    }
+  })();
+  return true;
+}
+
+// src/server/routes/v1/events-sse.ts
+import { randomBytes as randomBytes2 } from "crypto";
+var SSE_TOPICS = [
+  "state_change",
+  "agent_event",
+  "interaction.created",
+  "interaction.resolved",
+  "maintenance:started",
+  "maintenance:completed",
+  "maintenance:error",
+  "maintenance:baseref_fallback",
+  "local-model:status",
+  // ── Phase 3 ──
+  "webhook.subscription.created",
+  "webhook.subscription.deleted"
+];
+var HEARTBEAT_MS = 15e3;
+function newEventId() {
+  return `evt_${randomBytes2(8).toString("hex")}`;
+}
+function handleV1EventsSseRoute(req, res, bus) {
+  if (req.method !== "GET" || req.url !== "/api/v1/events") return false;
+  res.setHeader("Content-Type", "text/event-stream");
+  res.setHeader("Cache-Control", "no-cache");
+  res.setHeader("Connection", "keep-alive");
+  res.setHeader("X-Accel-Buffering", "no");
+  res.writeHead(200);
+  res.write(`: harness gateway SSE \u2014 connected at ${(/* @__PURE__ */ new Date()).toISOString()}
+
+`);
+  const listeners = [];
+  for (const topic of SSE_TOPICS) {
+    const fn = (data) => {
+      try {
+        const frame = `event: ${topic}
+data: ${JSON.stringify(data)}
+id: ${newEventId()}
+
+`;
+        res.write(frame);
+      } catch {
+      }
+    };
+    bus.on(topic, fn);
+    listeners.push({ topic, fn });
+  }
+  const heartbeat = setInterval(() => {
+    try {
+      res.write(": heartbeat\n\n");
+    } catch {
+    }
+  }, HEARTBEAT_MS);
+  heartbeat.unref();
+  const cleanup = () => {
+    clearInterval(heartbeat);
+    for (const { topic, fn } of listeners) bus.removeListener(topic, fn);
+  };
+  res.on("close", cleanup);
+  res.on("finish", cleanup);
+  return true;
+}
+
+// src/server/routes/v1/webhooks.ts
+import { z as z12 } from "zod";
+
+// src/server/utils/url-guard.ts
+var PRIVATE_HOSTNAME_RE = /^(localhost|.*\.local)$/i;
+var PRIVATE_IPV4_RE = /^(127\.\d+\.\d+\.\d+|10\.\d+\.\d+\.\d+|172\.(1[6-9]|2\d|3[01])\.\d+\.\d+|192\.168\.\d+\.\d+|169\.254\.\d+\.\d+|0\.0\.0\.0)$/;
+var LOOPBACK_IPV6_RE = /^(::1|::ffff:127\.\d+\.\d+\.\d+|::ffff:0:127\.\d+\.\d+\.\d+)$/i;
+function isPrivateHost(hostname) {
+  return PRIVATE_HOSTNAME_RE.test(hostname) || PRIVATE_IPV4_RE.test(hostname) || LOOPBACK_IPV6_RE.test(hostname);
+}
+
+// src/server/routes/v1/webhooks.ts
+import { WebhookSubscriptionPublicSchema } from "@harness-engineering/types";
+function isAdminAuth(authContext) {
+  if (!authContext) return false;
+  if (authContext.scopes.includes("admin")) return true;
+  if (authContext.id.startsWith("tok_legacy_env")) return true;
+  return false;
+}
+function getAuthContext(req) {
+  return req._authToken;
+}
+var CreateBody = z12.object({
+  url: z12.string().url(),
+  events: z12.array(z12.string().min(1)).min(1)
+});
+var QUEUE_STATS_PATH_RE = /^\/api\/v1\/webhooks\/queue\/stats(?:\?.*)?$/;
+var DELETE_PATH_RE = /^\/api\/v1\/webhooks\/([a-zA-Z0-9_-]+)(?:\?.*)?$/;
+var LIST_OR_CREATE_PATH_RE = /^\/api\/v1\/webhooks(?:\?.*)?$/;
+function sendJSON6(res, status, body) {
+  res.writeHead(status, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(body));
+}
+var unauthDevWarnedThisProcess = false;
+function maybeWarnUnauthDev(tokenId, url) {
+  if (unauthDevWarnedThisProcess) return;
+  const isUnauthDev = tokenId === "tok_legacy_env" || process.env["HARNESS_UNAUTH_DEV_ACTIVE"] === "1";
+  if (!isUnauthDev) return;
+  unauthDevWarnedThisProcess = true;
+  console.warn(
+    `[webhook] subscription created under unauth-dev mode (tokenId=${tokenId}). Webhook target URL: ${url}. Set HARNESS_API_TOKEN or configure tokens.json to silence this warning.`
+  );
+}
+function handleV1WebhooksRoute(req, res, deps) {
+  const url = req.url ?? "";
+  const method = req.method ?? "GET";
+  if (method === "GET" && QUEUE_STATS_PATH_RE.test(url)) {
+    if (!deps.queue) {
+      sendJSON6(res, 503, { error: "Queue not available" });
+      return true;
+    }
+    sendJSON6(res, 200, deps.queue.stats());
+    return true;
+  }
+  if (method === "GET" && LIST_OR_CREATE_PATH_RE.test(url)) {
+    void (async () => {
+      const subs = await deps.store.list();
+      const authContext = getAuthContext(req);
+      const visible = isAdminAuth(authContext) ? subs : subs.filter((s) => s.tokenId === authContext?.id);
+      const publicView = visible.map((s) => WebhookSubscriptionPublicSchema.parse(s));
+      sendJSON6(res, 200, publicView);
+    })();
+    return true;
+  }
+  if (method === "POST" && LIST_OR_CREATE_PATH_RE.test(url)) {
+    void (async () => {
+      let raw;
+      try {
+        raw = await readBody(req);
+      } catch (err) {
+        sendJSON6(res, 413, { error: err instanceof Error ? err.message : "Body too large" });
+        return;
+      }
+      let json;
+      try {
+        json = JSON.parse(raw);
+      } catch {
+        sendJSON6(res, 400, { error: "Invalid JSON body" });
+        return;
+      }
+      const parsed = CreateBody.safeParse(json);
+      if (!parsed.success) {
+        sendJSON6(res, 400, { error: "Invalid body", issues: parsed.error.issues });
+        return;
+      }
+      if (!parsed.data.url.startsWith("https://")) {
+        sendJSON6(res, 422, { error: "URL must use https" });
+        return;
+      }
+      const targetHostname = new URL(parsed.data.url).hostname;
+      if (isPrivateHost(targetHostname)) {
+        sendJSON6(res, 422, { error: "URL must not target private or loopback addresses" });
+        return;
+      }
+      const tokenId = getAuthContext(req)?.id ?? "unknown";
+      const sub = await deps.store.create({
+        tokenId,
+        url: parsed.data.url,
+        events: parsed.data.events
+      });
+      maybeWarnUnauthDev(tokenId, parsed.data.url);
+      deps.bus.emit("webhook.subscription.created", {
+        id: sub.id,
+        tokenId: sub.tokenId,
+        url: sub.url,
+        events: sub.events,
+        createdAt: sub.createdAt
+      });
+      sendJSON6(res, 200, sub);
+    })();
+    return true;
+  }
+  const m = method === "DELETE" ? DELETE_PATH_RE.exec(url) : null;
+  if (m) {
+    const id = m[1] ?? "";
+    void (async () => {
+      const authContext = getAuthContext(req);
+      const subs = await deps.store.list();
+      const sub = subs.find((s) => s.id === id);
+      if (!sub) {
+        sendJSON6(res, 404, { error: "Subscription not found" });
+        return;
+      }
+      if (!isAdminAuth(authContext) && sub.tokenId !== authContext?.id) {
+        sendJSON6(res, 403, { error: "forbidden" });
+        return;
+      }
+      const ok = await deps.store.delete(id);
+      if (!ok) {
+        sendJSON6(res, 404, { error: "Subscription not found" });
+        return;
+      }
+      deps.bus.emit("webhook.subscription.deleted", { id });
+      sendJSON6(res, 200, { deleted: true });
+    })();
+    return true;
+  }
+  return false;
+}
+
+// src/server/routes/v1/telemetry.ts
+var CACHE_STATS_PATH_RE = /^\/api\/v1\/telemetry\/cache\/stats(?:\?.*)?$/;
+function sendJSON7(res, status, body) {
+  res.writeHead(status, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(body));
+}
+function handleV1TelemetryRoute(req, res, deps) {
+  const url = req.url ?? "";
+  const method = req.method ?? "GET";
+  if (method === "GET" && CACHE_STATS_PATH_RE.test(url)) {
+    if (!deps.cacheMetrics) {
+      sendJSON7(res, 503, { error: "Cache metrics recorder not available" });
+      return true;
+    }
+    sendJSON7(res, 200, deps.cacheMetrics.getStats());
+    return true;
+  }
+  return false;
+}
+
 // src/server/routes/sessions.ts
 import * as fs11 from "fs/promises";
 import * as path11 from "path";
-import { z as z10 } from "zod";
-var SessionCreateSchema = z10.object({
-  sessionId: z10.string().min(1)
+import { z as z13 } from "zod";
+var SessionCreateSchema = z13.object({
+  sessionId: z13.string().min(1)
 }).passthrough();
 var UUID_RE2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 function isSafeId(id) {
@@ -6595,7 +6973,7 @@ async function handleUpdate(req, res, url, sessionsDir) {
       return;
     }
     const body = await readBody(req);
-    const updates = z10.record(z10.unknown()).parse(JSON.parse(body));
+    const updates = z13.record(z13.unknown()).parse(JSON.parse(body));
     const sessionFilePath = path11.join(sessionsDir, id, "session.json");
     const current = JSON.parse(await fs11.readFile(sessionFilePath, "utf-8"));
     await fs11.writeFile(sessionFilePath, JSON.stringify({ ...current, ...updates }, null, 2));
@@ -6714,8 +7092,116 @@ function handleStreamsRoute(req, res, recorder) {
   return true;
 }
 
+// src/server/routes/auth.ts
+import { z as z14 } from "zod";
+import {
+  TokenScopeSchema,
+  BridgeKindSchema,
+  AuthTokenPublicSchema
+} from "@harness-engineering/types";
+var CreateBodySchema = z14.object({
+  name: z14.string().min(1).max(100),
+  scopes: z14.array(TokenScopeSchema).min(1),
+  bridgeKind: BridgeKindSchema.optional(),
+  tenantId: z14.string().optional(),
+  expiresAt: z14.string().datetime().optional()
+});
+function sendJSON8(res, status, body) {
+  res.writeHead(status, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(body));
+}
+async function handlePost(req, res, store) {
+  let raw;
+  try {
+    raw = await readBody(req);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : "Failed to read body";
+    sendJSON8(res, 413, { error: msg });
+    return;
+  }
+  let json;
+  try {
+    json = JSON.parse(raw);
+  } catch {
+    sendJSON8(res, 400, { error: "Invalid JSON body" });
+    return;
+  }
+  const parsed = CreateBodySchema.safeParse(json);
+  if (!parsed.success) {
+    sendJSON8(res, 422, { error: "Invalid body", issues: parsed.error.issues });
+    return;
+  }
+  try {
+    const input = {
+      name: parsed.data.name,
+      scopes: parsed.data.scopes
+    };
+    if (parsed.data.bridgeKind !== void 0) input.bridgeKind = parsed.data.bridgeKind;
+    if (parsed.data.tenantId !== void 0) input.tenantId = parsed.data.tenantId;
+    if (parsed.data.expiresAt !== void 0) input.expiresAt = parsed.data.expiresAt;
+    const result = await store.create(input);
+    const publicRecord = AuthTokenPublicSchema.parse(result.record);
+    sendJSON8(res, 200, {
+      ...publicRecord,
+      token: result.token
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : "Failed to create token";
+    if (msg.includes("already exists")) {
+      sendJSON8(res, 409, { error: msg });
+      return;
+    }
+    sendJSON8(res, 500, { error: "Internal error creating token" });
+  }
+}
+async function handleList2(res, store) {
+  try {
+    const list = await store.list();
+    sendJSON8(res, 200, list);
+  } catch {
+    sendJSON8(res, 500, { error: "Internal error listing tokens" });
+  }
+}
+async function handleDelete2(res, store, id) {
+  try {
+    const ok = await store.revoke(id);
+    if (!ok) {
+      sendJSON8(res, 404, { error: "Token not found" });
+      return;
+    }
+    sendJSON8(res, 200, { deleted: true });
+  } catch {
+    sendJSON8(res, 500, { error: "Internal error revoking token" });
+  }
+}
+var DELETE_PATH_RE2 = /^\/api\/v1\/auth\/tokens\/([^/?]+)(?:\?.*)?$/;
+function handleAuthRoute(req, res, store) {
+  const { method, url } = req;
+  if (!url) return false;
+  if (!url.startsWith("/api/v1/auth/")) return false;
+  const [pathname] = url.split("?");
+  if (method === "POST" && pathname === "/api/v1/auth/token") {
+    void handlePost(req, res, store);
+    return true;
+  }
+  if (method === "GET" && pathname === "/api/v1/auth/tokens") {
+    void handleList2(res, store);
+    return true;
+  }
+  if (method === "DELETE") {
+    const match = (pathname ?? "").match(DELETE_PATH_RE2);
+    if (match && match[1]) {
+      const id = decodeURIComponent(match[1]);
+      void handleDelete2(res, store, id);
+      return true;
+    }
+  }
+  sendJSON8(res, 405, { error: "Method not allowed" });
+  return true;
+}
+
 // src/server/routes/local-model.ts
-function sendJSON4(res, status, body) {
+function sendJSON9(res, status, body) {
   res.writeHead(status, { "Content-Type": "application/json" });
   res.end(JSON.stringify(body));
 }
@@ -6723,30 +7209,30 @@ function handleLocalModelRoute(req, res, getStatus) {
   const { method, url } = req;
   if (url !== "/api/v1/local-model/status") return false;
   if (method !== "GET") {
-    sendJSON4(res, 405, { error: "Method not allowed" });
+    sendJSON9(res, 405, { error: "Method not allowed" });
     return true;
   }
   if (!getStatus) {
-    sendJSON4(res, 503, { error: "Local backend not configured" });
+    sendJSON9(res, 503, { error: "Local backend not configured" });
     return true;
   }
   const status = getStatus();
   if (!status) {
-    sendJSON4(res, 503, { error: "Local backend not configured" });
+    sendJSON9(res, 503, { error: "Local backend not configured" });
     return true;
   }
-  sendJSON4(res, 200, status);
+  sendJSON9(res, 200, status);
   return true;
 }
 function handleLocalModelsRoute(req, res, getStatuses) {
   const { method, url } = req;
   if (url !== "/api/v1/local-models/status") return false;
   if (method !== "GET") {
-    sendJSON4(res, 405, { error: "Method not allowed" });
+    sendJSON9(res, 405, { error: "Method not allowed" });
     return true;
   }
   const statuses = getStatuses ? getStatuses() : [];
-  sendJSON4(res, 200, statuses);
+  sendJSON9(res, 200, statuses);
   return true;
 }
 
@@ -6853,10 +7339,271 @@ var PlanWatcher = class {
   }
 };
 
+// src/auth/tokens.ts
+import { randomBytes as randomBytes3, timingSafeEqual } from "crypto";
+import { readFile as readFile8, writeFile as writeFile8, mkdir as mkdir7, rename as rename2 } from "fs/promises";
+import { dirname as dirname4 } from "path";
+import bcrypt from "bcryptjs";
+import {
+  AuthTokenSchema,
+  AuthTokenPublicSchema as AuthTokenPublicSchema2
+} from "@harness-engineering/types";
+var BCRYPT_ROUNDS = 12;
+var LEGACY_ENV_ID = "tok_legacy_env";
+function genId() {
+  return `tok_${randomBytes3(8).toString("hex")}`;
+}
+function genSecret() {
+  return randomBytes3(24).toString("base64url");
+}
+function parseToken(raw) {
+  const dot = raw.indexOf(".");
+  if (dot < 0) return null;
+  return { id: raw.slice(0, dot), secret: raw.slice(dot + 1) };
+}
+var TokenStore = class {
+  constructor(path17) {
+    this.path = path17;
+  }
+  path;
+  cache = null;
+  async load() {
+    if (this.cache) return this.cache;
+    try {
+      const raw = await readFile8(this.path, "utf8");
+      const parsed = JSON.parse(raw);
+      const list = Array.isArray(parsed) ? parsed : [];
+      this.cache = list.map((entry) => {
+        const r = AuthTokenSchema.safeParse(entry);
+        return r.success ? r.data : null;
+      }).filter((x) => x !== null);
+    } catch (err) {
+      if (err.code === "ENOENT") this.cache = [];
+      else throw err;
+    }
+    return this.cache;
+  }
+  async persist(records) {
+    await mkdir7(dirname4(this.path), { recursive: true });
+    const tmp = `${this.path}.tmp-${process.pid}-${Date.now()}-${randomBytes3(4).toString("hex")}`;
+    await writeFile8(tmp, JSON.stringify(records, null, 2), "utf8");
+    await rename2(tmp, this.path);
+    this.cache = records;
+  }
+  async create(input) {
+    const id = genId();
+    const secret = genSecret();
+    const hashedSecret = await bcrypt.hash(secret, BCRYPT_ROUNDS);
+    const record = {
+      id,
+      name: input.name,
+      scopes: input.scopes,
+      ...input.bridgeKind ? { bridgeKind: input.bridgeKind } : {},
+      ...input.tenantId ? { tenantId: input.tenantId } : {},
+      hashedSecret,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      ...input.expiresAt ? { expiresAt: input.expiresAt } : {}
+    };
+    const records = await this.load();
+    if (records.some((r) => r.name === input.name)) {
+      throw new Error(`Token with name "${input.name}" already exists`);
+    }
+    await this.persist([...records, record]);
+    return { id, token: `${id}.${secret}`, record };
+  }
+  async verify(raw) {
+    const parsed = parseToken(raw);
+    if (!parsed) return null;
+    const records = await this.load();
+    const rec = records.find((r) => r.id === parsed.id);
+    if (!rec) return null;
+    if (rec.expiresAt && Date.parse(rec.expiresAt) <= Date.now()) return null;
+    const ok = await bcrypt.compare(parsed.secret, rec.hashedSecret);
+    if (!ok) return null;
+    await this.touchLastUsed(rec.id);
+    return rec;
+  }
+  async touchLastUsed(id) {
+    const records = await this.load();
+    const idx = records.findIndex((r) => r.id === id);
+    if (idx < 0) return;
+    const current = records[idx];
+    if (!current) return;
+    const next = { ...current, lastUsedAt: (/* @__PURE__ */ new Date()).toISOString() };
+    const out = records.slice();
+    out[idx] = next;
+    await this.persist(out);
+  }
+  async list() {
+    const records = await this.load();
+    return records.map((r) => AuthTokenPublicSchema2.parse(r));
+  }
+  async revoke(id) {
+    const records = await this.load();
+    const next = records.filter((r) => r.id !== id);
+    if (next.length === records.length) return false;
+    await this.persist(next);
+    return true;
+  }
+  /**
+   * Synthetic admin record for the legacy HARNESS_API_TOKEN escape hatch.
+   * Returned only when `presented` matches `envValue` byte-for-byte (constant-time).
+   */
+  legacyEnvToken(presented, envValue) {
+    if (!envValue) return null;
+    const a = Buffer.from(presented);
+    const b = Buffer.from(envValue);
+    if (a.length !== b.length) return null;
+    if (!timingSafeEqual(a, b)) return null;
+    return {
+      id: LEGACY_ENV_ID,
+      name: "legacy-env",
+      scopes: ["admin"],
+      hashedSecret: "<env>",
+      createdAt: (/* @__PURE__ */ new Date(0)).toISOString()
+    };
+  }
+};
+
+// src/auth/audit.ts
+import { appendFile, mkdir as mkdir8 } from "fs/promises";
+import { dirname as dirname5 } from "path";
+import { AuthAuditEntrySchema } from "@harness-engineering/types";
+var AuditLogger = class {
+  constructor(path17, opts = {}) {
+    this.path = path17;
+    this.opts = opts;
+  }
+  path;
+  opts;
+  queue = Promise.resolve();
+  dirEnsured = false;
+  async append(input) {
+    const entry = AuthAuditEntrySchema.parse({
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      tokenId: input.tokenId,
+      ...input.tenantId ? { tenantId: input.tenantId } : {},
+      route: input.route,
+      method: input.method,
+      status: input.status
+    });
+    const line = `${JSON.stringify(entry)}
+`;
+    this.queue = this.queue.then(() => this.writeLine(line)).catch(() => void 0);
+  }
+  /** Wait for queued writes to drain. Test-only; not called on the hot path. */
+  async flush() {
+    await this.queue;
+  }
+  async writeLine(line) {
+    try {
+      if (this.opts.createDir !== false && !this.dirEnsured) {
+        await mkdir8(dirname5(this.path), { recursive: true });
+        this.dirEnsured = true;
+      }
+      await appendFile(this.path, line, "utf8");
+    } catch (err) {
+      console.warn(`[audit] write failed: ${err.message}`);
+    }
+  }
+};
+
+// src/server/v1-bridge-routes.ts
+var V1_BRIDGE_ROUTES = [
+  // ── Phase 2 bridge primitives ──
+  {
+    method: "POST",
+    pattern: /^\/api\/v1\/jobs\/maintenance(?:\?.*)?$/,
+    scope: "trigger-job",
+    description: "Trigger a maintenance task ad-hoc."
+  },
+  {
+    method: "POST",
+    pattern: /^\/api\/v1\/interactions\/[^/]+\/resolve(?:\?.*)?$/,
+    scope: "resolve-interaction",
+    description: "Resolve a pending interaction."
+  },
+  {
+    method: "GET",
+    pattern: /^\/api\/v1\/events(?:\?.*)?$/,
+    scope: "read-telemetry",
+    description: "Server-Sent Events stream."
+  },
+  // ── Phase 3 bridge primitives ──
+  {
+    method: "POST",
+    pattern: /^\/api\/v1\/webhooks(?:\?.*)?$/,
+    scope: "subscribe-webhook",
+    description: "Subscribe to outbound webhook fan-out."
+  },
+  {
+    method: "DELETE",
+    pattern: /^\/api\/v1\/webhooks\/[^/]+(?:\?.*)?$/,
+    scope: "subscribe-webhook",
+    description: "Delete a webhook subscription."
+  },
+  {
+    method: "GET",
+    pattern: /^\/api\/v1\/webhooks(?:\?.*)?$/,
+    scope: "subscribe-webhook",
+    description: "List webhook subscriptions."
+  },
+  // ── Phase 4 bridge primitives ──
+  {
+    method: "GET",
+    pattern: /^\/api\/v1\/webhooks\/queue\/stats(?:\?.*)?$/,
+    scope: "subscribe-webhook",
+    description: "Webhook delivery queue depth + DLQ stats."
+  },
+  // ── Phase 5 bridge primitives ──
+  {
+    method: "GET",
+    pattern: /^\/api\/v1\/telemetry\/cache\/stats(?:\?.*)?$/,
+    scope: "read-telemetry",
+    description: "Prompt-cache hit/miss snapshot (rolling window)."
+  }
+];
+function isV1Bridge(method, url) {
+  return V1_BRIDGE_ROUTES.some((r) => r.method === method && r.pattern.test(url));
+}
+function requiredBridgeScope(method, path17) {
+  for (const r of V1_BRIDGE_ROUTES) {
+    if (r.method === method && r.pattern.test(path17)) return r.scope;
+  }
+  return null;
+}
+
+// src/auth/scopes.ts
+function hasScope(held, required) {
+  if (held.includes("admin")) return true;
+  return held.includes(required);
+}
+function requiredScopeForRoute(method, path17) {
+  const bridgeScope = requiredBridgeScope(method, path17);
+  if (bridgeScope) return bridgeScope;
+  if (path17 === "/api/v1/auth/token" && method === "POST") return "admin";
+  if (path17 === "/api/v1/auth/tokens" && method === "GET") return "admin";
+  if (/^\/api\/v1\/auth\/tokens\/[^/]+$/.test(path17) && method === "DELETE") return "admin";
+  if ((path17 === "/api/state" || path17 === "/api/v1/state") && method === "GET") return "read-status";
+  if (path17.startsWith("/api/interactions")) return "resolve-interaction";
+  if (path17.startsWith("/api/plans")) return "read-status";
+  if (path17.startsWith("/api/analyze") || path17.startsWith("/api/analyses")) return "read-status";
+  if (path17.startsWith("/api/roadmap-actions")) return "modify-roadmap";
+  if (path17.startsWith("/api/dispatch-actions")) return "trigger-job";
+  if (path17.startsWith("/api/local-model") || path17.startsWith("/api/local-models"))
+    return "read-status";
+  if (path17.startsWith("/api/maintenance")) return "trigger-job";
+  if (path17.startsWith("/api/streams")) return "read-status";
+  if (path17.startsWith("/api/sessions")) return "read-status";
+  if (path17.startsWith("/api/chat-proxy")) return "trigger-job";
+  return null;
+}
+
 // src/server/http.ts
 var RATE_LIMIT = Number(process.env["HARNESS_RATE_LIMIT"]) || 100;
 var WINDOW_MS = 6e4;
 var rateBuckets = /* @__PURE__ */ new Map();
+var DEPRECATION_DATE = process.env["HARNESS_DEPRECATION_DATE"] ?? "2027-05-14";
 var ratePruneTimer = setInterval(() => {
   const now = Date.now();
   for (const [ip, bucket] of rateBuckets) {
@@ -6905,8 +7652,13 @@ var OrchestratorServer = class {
   maintenanceDeps = null;
   getLocalModelStatus = null;
   getLocalModelStatuses = null;
+  webhooks;
+  cacheMetrics;
   recorder = null;
   planWatcher = null;
+  tokenStore;
+  auditLogger;
+  warnedUnauthDev = false;
   stateChangeListener;
   agentEventListener;
   apiRoutes;
@@ -6914,6 +7666,10 @@ var OrchestratorServer = class {
     this.orchestrator = orchestrator;
     this.port = port;
     this.initDependencies(deps);
+    const tokensPath = process.env["HARNESS_TOKENS_PATH"] ?? path14.resolve(".harness", "tokens.json");
+    const auditPath = process.env["HARNESS_AUDIT_PATH"] ?? path14.resolve(".harness", "audit.log");
+    this.tokenStore = new TokenStore(tokensPath);
+    this.auditLogger = new AuditLogger(auditPath);
     this.httpServer = http.createServer(this.handleRequest.bind(this));
     this.broadcaster = new WebSocketBroadcaster(
       this.httpServer,
@@ -6935,6 +7691,8 @@ var OrchestratorServer = class {
     this.maintenanceDeps = deps?.maintenanceDeps ?? null;
     this.getLocalModelStatus = deps?.getLocalModelStatus ?? null;
     this.getLocalModelStatuses = deps?.getLocalModelStatuses ?? null;
+    this.webhooks = deps?.webhooks;
+    this.cacheMetrics = deps?.cacheMetrics;
   }
   wireEvents() {
     this.stateChangeListener = (snapshot) => {
@@ -7000,10 +7758,8 @@ var OrchestratorServer = class {
     this.recorder = recorder;
   }
   handleRequest(req, res) {
-    if (this.handleStateEndpoint(req, res)) {
-      return;
-    }
-    if (!checkRateLimit(req, res)) {
+    const isState = req.method === "GET" && (req.url === "/api/state" || req.url === "/api/v1/state");
+    if (!isState && !checkRateLimit(req, res)) {
       return;
     }
     if (this.handleApiRoutes(req, res)) {
@@ -7015,31 +7771,48 @@ var OrchestratorServer = class {
     res.writeHead(404, { "Content-Type": "application/json" });
     res.end(JSON.stringify({ error: "Not Found" }));
   }
-  /** Handle GET /api/state and legacy /api/v1/state */
-  handleStateEndpoint(req, res) {
-    const { method, url } = req;
-    if (method === "GET" && (url === "/api/state" || url === "/api/v1/state")) {
-      res.writeHead(200, { "Content-Type": "application/json" });
-      res.end(JSON.stringify(this.orchestrator.getSnapshot()));
-      return true;
-    }
-    return false;
-  }
   /**
-   * Check bearer token auth for mutating API routes.
-   * When HARNESS_API_TOKEN is set, all API requests must include it.
-   * Read-only endpoints (state, static) are exempt.
+   * Phase 1 auth: bearer token lookup against TokenStore + scope check.
+   * Legacy HARNESS_API_TOKEN env var still authenticates as a synthetic
+   * admin record (see TokenStore.legacyEnvToken).
+   *
+   * Returns the resolved AuthToken on success; sends 401/403 + returns null on failure.
    */
-  checkAuth(req, res) {
-    const token = process.env["HARNESS_API_TOKEN"];
-    if (!token) return true;
+  async resolveAuth(req, res) {
     const authHeader = req.headers["authorization"];
-    if (authHeader === `Bearer ${token}`) return true;
-    res.writeHead(401, { "Content-Type": "application/json" });
-    res.end(
-      JSON.stringify({ error: "Unauthorized \u2014 set Authorization: Bearer <HARNESS_API_TOKEN>" })
-    );
-    return false;
+    const legacyEnv = process.env["HARNESS_API_TOKEN"];
+    const listed = await this.tokenStore.list().catch(() => []);
+    if (listed.length === 0 && !legacyEnv) {
+      res.setHeader("X-Harness-Auth-Mode", "unauth-dev");
+      if (!this.warnedUnauthDev) {
+        this.warnedUnauthDev = true;
+        console.warn(
+          "harness orchestrator: running in UNAUTHENTICATED dev mode (tokens.json empty and HARNESS_API_TOKEN not set). All requests resolve as admin. Configure tokens before exposing the API beyond localhost."
+        );
+      }
+      return {
+        id: "tok_unauth_dev",
+        name: "unauth-dev",
+        scopes: ["admin"],
+        hashedSecret: "<none>",
+        createdAt: (/* @__PURE__ */ new Date(0)).toISOString()
+      };
+    }
+    if (!authHeader || !authHeader.startsWith("Bearer ")) {
+      res.writeHead(401, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Unauthorized \u2014 set Authorization: Bearer <token>" }));
+      return null;
+    }
+    const raw = authHeader.slice("Bearer ".length).trim();
+    const legacyMatch = this.tokenStore.legacyEnvToken(raw, legacyEnv);
+    if (legacyMatch) return legacyMatch;
+    const verified = await this.tokenStore.verify(raw);
+    if (!verified) {
+      res.writeHead(401, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Unauthorized \u2014 invalid or expired token" }));
+      return null;
+    }
+    return verified;
   }
   /**
    * Build the ordered API route table. Each entry is invoked in order and
@@ -7051,7 +7824,11 @@ var OrchestratorServer = class {
    */
   buildApiRoutes() {
     return [
+      // Auth admin routes — scope-gated to `admin` by requiredScopeForRoute.
+      // First in the table so the auth surface is unambiguously owned by the orchestrator.
+      (req, res) => handleAuthRoute(req, res, this.tokenStore),
       (req, res) => !!this.interactionQueue && handleInteractionsRoute(req, res, this.interactionQueue),
+      (req, res) => !!this.interactionQueue && handleV1InteractionsResolveRoute(req, res, this.interactionQueue),
       (req, res) => handlePlansRoute(req, res, this.plansDir),
       (req, res) => handleAnalyzeRoute(req, res, this.pipeline),
       (req, res) => handleAnalysesRoute(req, res, this.analysisArchive),
@@ -7061,19 +7838,103 @@ var OrchestratorServer = class {
       // Local-models multi-status route (Spec 2 SC38)
       (req, res) => handleLocalModelsRoute(req, res, this.getLocalModelStatuses),
       (req, res) => handleMaintenanceRoute(req, res, this.maintenanceDeps),
+      (req, res) => handleV1JobsMaintenanceRoute(req, res, this.maintenanceDeps),
       (req, res) => !!this.recorder && handleStreamsRoute(req, res, this.recorder),
       (req, res) => handleSessionsRoute(req, res, this.sessionsDir),
+      // SSE event stream — long-lived; placed near end so cheaper routes
+      // short-circuit first, but before the chat-proxy fallback.
+      (req, res) => handleV1EventsSseRoute(req, res, this.orchestrator),
+      // Phase 3 webhooks — short-circuits to false when webhooks is undefined
+      // (e.g. FakeOrchestrator-based tests pass no webhooks dep).
+      // Phase 4: forward the optional queue handle so the stats endpoint can
+      // serve depth/DLQ counts.
+      (req, res) => !!this.webhooks && handleV1WebhooksRoute(req, res, {
+        store: this.webhooks.store,
+        bus: this.orchestrator,
+        ...this.webhooks.queue ? { queue: this.webhooks.queue } : {}
+      }),
+      // Phase 5 — telemetry/cache/stats. Returns 503 when cacheMetrics is unset
+      // (FakeOrchestrator tests, exporter-disabled configs).
+      (req, res) => handleV1TelemetryRoute(req, res, {
+        ...this.cacheMetrics ? { cacheMetrics: this.cacheMetrics } : {}
+      }),
       // Chat proxy route (spawns Claude Code CLI — no API key required)
       (req, res) => handleChatProxyRoute(req, res, this.claudeCommand)
     ];
   }
-  /** Dispatch to API route handlers. Returns true if a route matched. */
+  /**
+   * Dispatch to API route handlers. Returns true immediately and resolves the
+   * request asynchronously (auth + scope check + dispatch + audit log).
+   *
+   * Static-file fallback for non-/api/* requests requires returning false so
+   * `handleRequest` can hand the request off to the static handler.
+   */
   handleApiRoutes(req, res) {
-    if (!this.checkAuth(req, res)) return true;
+    const url = req.url ?? "";
+    if (!url.startsWith("/api/")) return false;
+    void this.dispatchAuthedRequest(req, res);
+    return true;
+  }
+  async dispatchAuthedRequest(req, res) {
+    const token = await this.resolveAuth(req, res);
+    res.on("finish", () => this.audit(req, res, token));
+    if (!token) return;
+    req._authToken = {
+      id: token.id,
+      scopes: token.scopes
+    };
+    const V1_WRAPPABLE = /* @__PURE__ */ new Set([
+      "interactions",
+      "plans",
+      "analyze",
+      "analyses",
+      "roadmap-actions",
+      "dispatch-actions",
+      "local-model",
+      "local-models",
+      "maintenance",
+      "streams",
+      "sessions",
+      "chat-proxy"
+    ]);
+    const v1Match = /^\/api\/v1\/([^/?]+)(.*)$/.exec(req.url ?? "");
+    const rewrittenSlug = v1Match?.[1];
+    const v1BridgeMatch = isV1Bridge(req.method ?? "GET", req.url ?? "");
+    if (!v1BridgeMatch && rewrittenSlug && V1_WRAPPABLE.has(rewrittenSlug)) {
+      req.url = `/api/${rewrittenSlug}${v1Match?.[2] ?? ""}`;
+    }
+    const isLegacyPrefix = !!req.url && // eslint-disable-next-line @harness-engineering/no-hardcoded-path-separator -- URL path, not filesystem
+    req.url.startsWith("/api/") && // eslint-disable-next-line @harness-engineering/no-hardcoded-path-separator -- URL path, not filesystem
+    !req.url.startsWith("/api/v1/") && !v1Match;
+    if (isLegacyPrefix) {
+      res.setHeader("Deprecation", DEPRECATION_DATE);
+    }
+    const pathname = (req.url ?? "").split("?")[0] ?? "";
+    const required = requiredScopeForRoute(req.method ?? "GET", pathname);
+    if (!required || !hasScope(token.scopes, required)) {
+      res.writeHead(403, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Insufficient scope", required: required ?? "unknown" }));
+      return;
+    }
+    if (req.method === "GET" && (req.url === "/api/state" || req.url === "/api/v1/state")) {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(this.orchestrator.getSnapshot()));
+      return;
+    }
     for (const route of this.apiRoutes) {
-      if (route(req, res)) return true;
+      if (route(req, res)) return;
     }
-    return false;
+    res.writeHead(404, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "Not Found" }));
+  }
+  audit(req, res, token) {
+    void this.auditLogger.append({
+      tokenId: token?.id ?? "anonymous",
+      ...token?.tenantId ? { tenantId: token.tenantId } : {},
+      route: (req.url ?? "").split("?")[0] ?? "",
+      method: req.method ?? "GET",
+      status: res.statusCode || 0
+    });
   }
   get wsClientCount() {
     return this.broadcaster.clientCount;
@@ -7104,6 +7965,630 @@ var OrchestratorServer = class {
   }
 };
 
+// src/gateway/webhooks/store.ts
+import { randomBytes as randomBytes4 } from "crypto";
+import { readFile as readFile9, writeFile as writeFile9, mkdir as mkdir9, rename as rename3, chmod } from "fs/promises";
+import { dirname as dirname6 } from "path";
+import { WebhookSubscriptionSchema } from "@harness-engineering/types";
+
+// src/gateway/webhooks/signer.ts
+import { createHmac, timingSafeEqual as timingSafeEqual2 } from "crypto";
+function sign(secret, body) {
+  const hex = createHmac("sha256", secret).update(body).digest("hex");
+  return `sha256=${hex}`;
+}
+function eventMatches(pattern, type) {
+  if (type.startsWith("telemetry.")) {
+    const pSegs2 = pattern.split(".");
+    if (pSegs2[0] !== "telemetry") return false;
+  }
+  const pSegs = pattern.split(".");
+  const tSegs = type.split(".");
+  if (pSegs.length !== tSegs.length) return false;
+  for (let i = 0; i < pSegs.length; i++) {
+    if (pSegs[i] !== "*" && pSegs[i] !== tSegs[i]) return false;
+  }
+  return true;
+}
+
+// src/gateway/webhooks/store.ts
+function genId2() {
+  return `whk_${randomBytes4(8).toString("hex")}`;
+}
+function genSecret2() {
+  return randomBytes4(32).toString("base64url");
+}
+var WebhookStore = class {
+  constructor(path17) {
+    this.path = path17;
+  }
+  path;
+  cache = null;
+  async load() {
+    if (this.cache) return this.cache;
+    try {
+      const raw = await readFile9(this.path, "utf8");
+      const parsed = JSON.parse(raw);
+      const list = Array.isArray(parsed) ? parsed : [];
+      this.cache = list.map((entry) => {
+        const r = WebhookSubscriptionSchema.safeParse(entry);
+        return r.success ? r.data : null;
+      }).filter((x) => x !== null);
+    } catch (err) {
+      if (err.code === "ENOENT") this.cache = [];
+      else throw err;
+    }
+    return this.cache;
+  }
+  async persist(records) {
+    const tmp = `${this.path}.tmp-${process.pid}-${Date.now()}-${randomBytes4(4).toString("hex")}`;
+    try {
+      await mkdir9(dirname6(this.path), { recursive: true });
+      await writeFile9(tmp, JSON.stringify(records, null, 2), { encoding: "utf8", mode: 384 });
+      await rename3(tmp, this.path);
+      await chmod(this.path, 384);
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+    }
+    this.cache = records;
+  }
+  async create(input) {
+    const id = genId2();
+    const secret = genSecret2();
+    const record = {
+      id,
+      tokenId: input.tokenId,
+      url: input.url,
+      events: input.events,
+      secret,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const records = await this.load();
+    await this.persist([...records, record]);
+    return record;
+  }
+  async list() {
+    return [...await this.load()];
+  }
+  async delete(id) {
+    const records = await this.load();
+    const next = records.filter((r) => r.id !== id);
+    if (next.length === records.length) return false;
+    await this.persist(next);
+    return true;
+  }
+  /** Returns subs whose events list contains a pattern matching `eventType`. */
+  async listForEvent(eventType) {
+    const records = await this.load();
+    return records.filter((r) => r.events.some((p) => eventMatches(p, eventType)));
+  }
+};
+
+// src/gateway/webhooks/delivery.ts
+import { randomBytes as randomBytes5 } from "crypto";
+
+// src/gateway/webhooks/queue.ts
+import Database from "better-sqlite3";
+var RETRY_DELAYS_MS = [1e3, 4e3, 16e3, 64e3, 256e3];
+var MAX_ATTEMPTS = 5;
+var SCHEMA_SQL = `
+  CREATE TABLE IF NOT EXISTS webhook_deliveries (
+    id TEXT PRIMARY KEY,
+    subscriptionId TEXT NOT NULL,
+    eventType TEXT NOT NULL,
+    payload TEXT NOT NULL,
+    attempt INTEGER NOT NULL DEFAULT 0,
+    status TEXT NOT NULL DEFAULT 'pending',
+    nextAttemptAt INTEGER,
+    lastError TEXT,
+    deliveredAt INTEGER
+  ) STRICT;
+  CREATE INDEX IF NOT EXISTS idx_deliverable
+    ON webhook_deliveries(status, nextAttemptAt)
+    WHERE status IN ('pending', 'failed', 'in_flight');
+`;
+var WebhookQueue = class {
+  db;
+  constructor(dbPath) {
+    this.db = new Database(dbPath);
+    this.db.pragma("journal_mode = WAL");
+    this.db.pragma("synchronous = NORMAL");
+    this.db.exec(SCHEMA_SQL);
+    this.recoverInFlight();
+  }
+  insert(row) {
+    this.db.prepare(
+      `INSERT INTO webhook_deliveries
+           (id, subscriptionId, eventType, payload, attempt, status, nextAttemptAt)
+         VALUES (@id, @subscriptionId, @eventType, @payload, 0, 'pending', @nextAttemptAt)`
+    ).run({ ...row, nextAttemptAt: Date.now() });
+  }
+  /**
+   * Atomically lease a batch of deliverable rows: select pending|failed rows
+   * whose nextAttemptAt has elapsed, mark them in_flight in the same
+   * transaction, and return the leased rows. Subsequent calls cannot re-claim
+   * the same rows because they are no longer in pending|failed.
+   *
+   * Without this, two overlapping ticks (tick interval 500ms, HTTP timeout
+   * 5s) would both select the same row and double-fire the webhook.
+   */
+  claim(now, limit = 20) {
+    const selectIds = this.db.prepare(
+      `SELECT id FROM webhook_deliveries
+       WHERE (status = 'pending' OR status = 'failed')
+         AND nextAttemptAt <= ?
+       ORDER BY nextAttemptAt
+       LIMIT ?`
+    );
+    const markInFlight = this.db.prepare(
+      `UPDATE webhook_deliveries SET status = 'in_flight' WHERE id = ?`
+    );
+    const fetchById = this.db.prepare(`SELECT * FROM webhook_deliveries WHERE id = ?`);
+    const txn = this.db.transaction((tNow, tLimit) => {
+      const ids = selectIds.all(tNow, tLimit);
+      const claimed = [];
+      for (const { id } of ids) {
+        markInFlight.run(id);
+        const row = fetchById.get(id);
+        if (row) claimed.push(row);
+      }
+      return claimed;
+    });
+    return txn(now, limit);
+  }
+  /**
+   * Reset any rows stuck in in_flight (e.g. from a crashed or abruptly
+   * stopped worker) back to failed so they can be re-claimed by the next
+   * tick. At-most-once semantics within a single process; at-least-once
+   * across restarts (a row whose HTTP POST completed but whose DB update was
+   * lost will be re-delivered — bridges must be idempotent on delivery-id).
+   */
+  recoverInFlight() {
+    return this.db.prepare(
+      `UPDATE webhook_deliveries
+         SET status = 'failed', nextAttemptAt = ?
+         WHERE status = 'in_flight'`
+    ).run(Date.now()).changes;
+  }
+  markDelivered(id, deliveredAt) {
+    this.db.prepare(
+      `UPDATE webhook_deliveries
+         SET status = 'delivered', deliveredAt = ?, nextAttemptAt = NULL
+         WHERE id = ?`
+    ).run(deliveredAt, id);
+  }
+  markFailed(id, attempt, nextAttemptAt, lastError) {
+    if (attempt >= MAX_ATTEMPTS) {
+      this.db.prepare(
+        `UPDATE webhook_deliveries
+           SET status = 'dead', attempt = ?, lastError = ?, nextAttemptAt = NULL
+           WHERE id = ?`
+      ).run(attempt, lastError, id);
+    } else {
+      this.db.prepare(
+        `UPDATE webhook_deliveries
+           SET status = 'failed', attempt = ?, nextAttemptAt = ?, lastError = ?
+           WHERE id = ?`
+      ).run(attempt, nextAttemptAt, lastError, id);
+    }
+  }
+  retryDead(id) {
+    const result = this.db.prepare(
+      `UPDATE webhook_deliveries
+         SET status = 'pending', attempt = 0, nextAttemptAt = ?, lastError = NULL
+         WHERE id = ? AND status = 'dead'`
+    ).run(Date.now(), id);
+    return result.changes > 0;
+  }
+  list(filter = {}) {
+    const conditions = ["1=1"];
+    const params = [];
+    if (filter.status) {
+      conditions.push("status = ?");
+      params.push(filter.status);
+    }
+    if (filter.subscriptionId) {
+      conditions.push("subscriptionId = ?");
+      params.push(filter.subscriptionId);
+    }
+    const sql = `SELECT * FROM webhook_deliveries WHERE ${conditions.join(" AND ")} ORDER BY nextAttemptAt DESC LIMIT 200`;
+    return this.db.prepare(sql).all(...params);
+  }
+  purge(opts = {}) {
+    const conditions = ["1=1"];
+    const params = [];
+    if (opts.deadOnly) {
+      conditions.push("status = 'dead'");
+    }
+    if (opts.olderThanMs !== void 0) {
+      const cutoff = Date.now() - opts.olderThanMs;
+      conditions.push("(deliveredAt IS NOT NULL AND deliveredAt < ?)");
+      params.push(cutoff);
+    }
+    const sql = `DELETE FROM webhook_deliveries WHERE ${conditions.join(" AND ")}`;
+    return this.db.prepare(sql).run(...params).changes;
+  }
+  /**
+   * Count the rows a purge() call with these same options would delete.
+   * Used by the CLI to show a confirmation preview before destructive deletes.
+   */
+  previewPurge(opts = {}) {
+    const conditions = ["1=1"];
+    const params = [];
+    if (opts.deadOnly) {
+      conditions.push("status = 'dead'");
+    }
+    if (opts.olderThanMs !== void 0) {
+      const cutoff = Date.now() - opts.olderThanMs;
+      conditions.push("(deliveredAt IS NOT NULL AND deliveredAt < ?)");
+      params.push(cutoff);
+    }
+    const sql = `SELECT COUNT(*) as count FROM webhook_deliveries WHERE ${conditions.join(" AND ")}`;
+    const row = this.db.prepare(sql).get(...params);
+    return row.count;
+  }
+  stats() {
+    const rows = this.db.prepare(`SELECT status, COUNT(*) as count FROM webhook_deliveries GROUP BY status`).all();
+    const m = Object.fromEntries(rows.map((r) => [r.status, r.count]));
+    return {
+      pending: m["pending"] ?? 0,
+      inFlight: m["in_flight"] ?? 0,
+      failed: m["failed"] ?? 0,
+      dead: m["dead"] ?? 0,
+      delivered: m["delivered"] ?? 0
+    };
+  }
+  close() {
+    this.db.close();
+  }
+};
+
+// src/gateway/webhooks/delivery.ts
+var WebhookDelivery = class {
+  queue;
+  store;
+  timeoutMs;
+  fetchImpl;
+  tickIntervalMs;
+  maxConcurrentPerSub;
+  drainTimeoutMs;
+  allowPrivateHosts;
+  inFlight = /* @__PURE__ */ new Map();
+  /**
+   * AbortControllers for currently executing HTTP POSTs, keyed by delivery id.
+   * On drain-timeout exhaustion stop() aborts each one so we never write to
+   * the SQLite handle after orchestrator.stop() closes it.
+   */
+  inFlightAborts = /* @__PURE__ */ new Map();
+  tickTimer = null;
+  draining = false;
+  constructor(opts) {
+    this.queue = opts.queue;
+    this.store = opts.store;
+    this.timeoutMs = opts.timeoutMs ?? 5e3;
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+    this.tickIntervalMs = opts.tickIntervalMs ?? 500;
+    this.maxConcurrentPerSub = opts.maxConcurrentPerSub ?? 4;
+    this.drainTimeoutMs = opts.drainTimeoutMs ?? 3e4;
+    this.allowPrivateHosts = opts.allowPrivateHosts ?? false;
+  }
+  enqueue(sub, event) {
+    const payload = JSON.stringify(event);
+    this.queue.insert({
+      id: `dlv_${randomBytes5(8).toString("hex")}`,
+      subscriptionId: sub.id,
+      eventType: event.type,
+      payload
+    });
+  }
+  start() {
+    if (this.tickTimer !== null) return;
+    this.tickTimer = setInterval(() => void this.tick(), this.tickIntervalMs);
+  }
+  async stop() {
+    this.draining = true;
+    if (this.tickTimer !== null) {
+      clearInterval(this.tickTimer);
+      this.tickTimer = null;
+    }
+    const deadline = Date.now() + this.drainTimeoutMs;
+    while (Date.now() < deadline) {
+      const total = [...this.inFlight.values()].reduce((a, b) => a + b, 0);
+      if (total === 0) break;
+      await new Promise((r) => setTimeout(r, 100));
+    }
+    if (this.inFlightAborts.size > 0) {
+      for (const ctrl of this.inFlightAborts.values()) ctrl.abort();
+      await new Promise((r) => setTimeout(r, 100));
+    }
+  }
+  async tick() {
+    if (this.draining) return;
+    const pending = this.queue.claim(Date.now());
+    for (const row of pending) {
+      const inFlight = this.inFlight.get(row.subscriptionId) ?? 0;
+      if (inFlight >= this.maxConcurrentPerSub) continue;
+      this.inFlight.set(row.subscriptionId, inFlight + 1);
+      void this.executeDelivery(row);
+    }
+  }
+  async executeDelivery(row) {
+    const ctrl = new AbortController();
+    this.inFlightAborts.set(row.id, ctrl);
+    try {
+      const subs = await this.store.list();
+      const sub = subs.find((s) => s.id === row.subscriptionId);
+      if (!sub) {
+        this.queue.markFailed(row.id, MAX_ATTEMPTS, Date.now(), "subscription deleted");
+        return;
+      }
+      let hostname;
+      try {
+        hostname = new URL(sub.url).hostname;
+      } catch {
+        this.queue.markFailed(row.id, MAX_ATTEMPTS, Date.now(), "invalid URL");
+        return;
+      }
+      if (!this.allowPrivateHosts && isPrivateHost(hostname)) {
+        this.queue.markFailed(
+          row.id,
+          MAX_ATTEMPTS,
+          Date.now(),
+          "URL resolves to private/loopback host"
+        );
+        return;
+      }
+      const signature = sign(sub.secret, row.payload);
+      const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+      let ok = false;
+      let lastError = "";
+      let aborted = false;
+      try {
+        const res = await this.fetchImpl(sub.url, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "X-Harness-Delivery-Id": row.id,
+            "X-Harness-Event-Type": row.eventType,
+            "X-Harness-Signature": signature,
+            "X-Harness-Timestamp": String(Date.now())
+          },
+          body: row.payload,
+          signal: ctrl.signal
+        });
+        ok = res.ok;
+        if (!ok) lastError = `HTTP ${res.status}`;
+      } catch (err) {
+        aborted = ctrl.signal.aborted;
+        lastError = err instanceof Error ? err.message : String(err);
+      } finally {
+        clearTimeout(timer);
+      }
+      if (aborted && this.draining) {
+        return;
+      }
+      if (ok) {
+        this.queue.markDelivered(row.id, Date.now());
+      } else {
+        const nextAttempt = row.attempt + 1;
+        const delay = RETRY_DELAYS_MS[row.attempt] ?? 256e3;
+        this.queue.markFailed(row.id, nextAttempt, Date.now() + delay, lastError);
+      }
+    } finally {
+      this.inFlightAborts.delete(row.id);
+      const cur = this.inFlight.get(row.subscriptionId) ?? 1;
+      this.inFlight.set(row.subscriptionId, Math.max(0, cur - 1));
+    }
+  }
+};
+
+// src/gateway/webhooks/events.ts
+import { randomBytes as randomBytes6 } from "crypto";
+var WEBHOOK_TOPICS = [
+  "interaction.created",
+  "interaction.resolved",
+  "maintenance:started",
+  "maintenance:completed",
+  "maintenance:error",
+  "webhook.subscription.created",
+  "webhook.subscription.deleted"
+];
+function newEventId2() {
+  return `evt_${randomBytes6(8).toString("hex")}`;
+}
+function wireWebhookFanout({ bus, store, delivery }) {
+  const handlers = [];
+  for (const topic of WEBHOOK_TOPICS) {
+    const eventType = topic.replace(":", ".");
+    const fn = (data) => {
+      void (async () => {
+        const subs = await store.listForEvent(eventType);
+        if (subs.length === 0) return;
+        const event = {
+          id: newEventId2(),
+          type: eventType,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          data
+        };
+        for (const sub of subs) {
+          delivery.enqueue(sub, event);
+        }
+      })();
+    };
+    bus.on(topic, fn);
+    handlers.push({ topic, fn });
+  }
+  return () => {
+    for (const { topic, fn } of handlers) bus.removeListener(topic, fn);
+  };
+}
+
+// src/gateway/telemetry/fanout.ts
+import { randomBytes as randomBytes7 } from "crypto";
+import { SpanKind } from "@harness-engineering/core";
+var TOPICS = {
+  MAINTENANCE_STARTED: "maintenance:started",
+  MAINTENANCE_COMPLETED: "maintenance:completed",
+  MAINTENANCE_ERROR: "maintenance:error",
+  DISPATCH_DECISION: "dispatch:decision",
+  SKILL_INVOCATION: "skill_invocation"
+};
+var TELEMETRY_TYPE = {
+  [TOPICS.MAINTENANCE_STARTED]: "telemetry.maintenance_run",
+  [TOPICS.MAINTENANCE_COMPLETED]: "telemetry.maintenance_run",
+  [TOPICS.MAINTENANCE_ERROR]: "telemetry.maintenance_run",
+  [TOPICS.DISPATCH_DECISION]: "telemetry.dispatch_decision",
+  [TOPICS.SKILL_INVOCATION]: "telemetry.skill_invocation"
+};
+var SPAN_NAME = {
+  [TOPICS.MAINTENANCE_STARTED]: "maintenance_run",
+  [TOPICS.MAINTENANCE_COMPLETED]: "maintenance_run",
+  [TOPICS.MAINTENANCE_ERROR]: "maintenance_run",
+  [TOPICS.DISPATCH_DECISION]: "dispatch_decision",
+  [TOPICS.SKILL_INVOCATION]: "skill_invocation"
+};
+function newEventId3() {
+  return `evt_${randomBytes7(8).toString("hex")}`;
+}
+function newTraceId() {
+  return randomBytes7(16).toString("hex");
+}
+function newSpanId() {
+  return randomBytes7(8).toString("hex");
+}
+function nowNs() {
+  return BigInt(Date.now()) * 1000000n;
+}
+var MAX_ACTIVE_RUNS = 256;
+var ActiveRunRegistry = class {
+  byKey = /* @__PURE__ */ new Map();
+  open(key, ids) {
+    if (this.byKey.has(key)) {
+      this.byKey.set(key, ids);
+      return;
+    }
+    if (this.byKey.size >= MAX_ACTIVE_RUNS) {
+      const oldest = this.byKey.keys().next().value;
+      if (oldest !== void 0) this.byKey.delete(oldest);
+    }
+    this.byKey.set(key, ids);
+  }
+  /**
+   * Look up an active run; tries `correlationId`, then `taskId`. Returns
+   * `undefined` when neither matches — the caller should treat the event as
+   * a root span rather than guessing a parent.
+   */
+  resolve(args) {
+    if (args.correlationId && this.byKey.has(args.correlationId)) {
+      return this.byKey.get(args.correlationId);
+    }
+    if (args.taskId && this.byKey.has(args.taskId)) {
+      return this.byKey.get(args.taskId);
+    }
+    return void 0;
+  }
+  close(key) {
+    this.byKey.delete(key);
+  }
+  /** Number of currently tracked runs. Exposed for tests + diagnostics. */
+  get size() {
+    return this.byKey.size;
+  }
+};
+function buildAttributes(payload, extras = {}) {
+  const attrs = { ...extras };
+  for (const [k, v] of Object.entries(payload)) {
+    if (v === null || v === void 0) continue;
+    if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
+      attrs[k] = v;
+    }
+  }
+  return attrs;
+}
+function wireTelemetryFanout(params) {
+  const { bus, exporter, webhookDelivery, store } = params;
+  const registry = new ActiveRunRegistry();
+  const handlers = [];
+  const enqueueToMatchingSubs = async (event) => {
+    const subs = await store.listForEvent(event.type);
+    if (subs.length === 0) return;
+    const filtered = subs.filter((sub) => sub.events.some((p) => eventMatches(p, event.type)));
+    for (const sub of filtered) {
+      webhookDelivery.enqueue(sub, event);
+    }
+  };
+  const makeHandler = (topic) => (data) => {
+    const payload = data ?? {};
+    const correlationId = typeof payload["correlationId"] === "string" ? payload["correlationId"] : void 0;
+    const taskId = typeof payload["taskId"] === "string" ? payload["taskId"] : void 0;
+    let traceId;
+    let spanId;
+    let parentSpanId;
+    let statusCode;
+    if (topic === TOPICS.MAINTENANCE_STARTED) {
+      traceId = newTraceId();
+      spanId = newSpanId();
+      const key = correlationId ?? taskId ?? `run_${spanId}`;
+      registry.open(key, { traceId, spanId });
+    } else if (topic === TOPICS.MAINTENANCE_COMPLETED || topic === TOPICS.MAINTENANCE_ERROR) {
+      const existing = registry.resolve({
+        ...correlationId !== void 0 ? { correlationId } : {},
+        ...taskId !== void 0 ? { taskId } : {}
+      });
+      if (existing !== void 0) {
+        traceId = existing.traceId;
+        spanId = existing.spanId;
+      } else {
+        traceId = newTraceId();
+        spanId = newSpanId();
+      }
+      statusCode = topic === TOPICS.MAINTENANCE_ERROR ? 2 : 1;
+      const key = correlationId ?? taskId ?? "";
+      if (key) registry.close(key);
+    } else {
+      const parent = registry.resolve({
+        ...correlationId !== void 0 ? { correlationId } : {},
+        ...taskId !== void 0 ? { taskId } : {}
+      });
+      traceId = parent?.traceId ?? newTraceId();
+      spanId = newSpanId();
+      parentSpanId = parent?.spanId;
+    }
+    const startNs = nowNs();
+    const span = {
+      traceId,
+      spanId,
+      ...parentSpanId !== void 0 ? { parentSpanId } : {},
+      name: SPAN_NAME[topic],
+      kind: SpanKind.INTERNAL,
+      startTimeNs: startNs,
+      endTimeNs: startNs,
+      attributes: buildAttributes(payload, { "harness.topic": topic }),
+      ...statusCode !== void 0 ? { statusCode } : {}
+    };
+    exporter.push(span);
+    const gatewayEvent = {
+      id: newEventId3(),
+      type: TELEMETRY_TYPE[topic],
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      data: payload,
+      ...correlationId !== void 0 ? { correlationId } : {}
+    };
+    void enqueueToMatchingSubs(gatewayEvent);
+  };
+  for (const topic of Object.values(TOPICS)) {
+    const fn = makeHandler(topic);
+    bus.on(topic, fn);
+    handlers.push({ topic, fn });
+  }
+  return () => {
+    for (const { topic, fn } of handlers) bus.removeListener(topic, fn);
+  };
+}
+
+// src/orchestrator.ts
+import { CacheMetricsRecorder, OTLPExporter } from "@harness-engineering/core";
+
 // src/logging/logger.ts
 var StructuredLogger = class {
   debug(message, context) {
@@ -7667,17 +9152,17 @@ var SingleProcessLeaderElector = class {
 // src/maintenance/reporter.ts
 import * as fs14 from "fs";
 import * as path15 from "path";
-import { z as z11 } from "zod";
-var RunResultSchema = z11.object({
-  taskId: z11.string(),
-  startedAt: z11.string(),
-  completedAt: z11.string(),
-  status: z11.enum(["success", "failure", "skipped", "no-issues"]),
-  findings: z11.number(),
-  fixed: z11.number(),
-  prUrl: z11.string().nullable(),
-  prUpdated: z11.boolean(),
-  error: z11.string().optional()
+import { z as z15 } from "zod";
+var RunResultSchema = z15.object({
+  taskId: z15.string(),
+  startedAt: z15.string(),
+  completedAt: z15.string(),
+  status: z15.enum(["success", "failure", "skipped", "no-issues"]),
+  findings: z15.number(),
+  fixed: z15.number(),
+  prUrl: z15.string().nullable(),
+  prUpdated: z15.boolean(),
+  error: z15.string().optional()
 });
 var MAX_HISTORY = 500;
 var fallbackLogger = {
@@ -7704,7 +9189,7 @@ var MaintenanceReporter = class {
       await fs14.promises.mkdir(this.persistDir, { recursive: true });
       const filePath = path15.join(this.persistDir, "history.json");
       const data = await fs14.promises.readFile(filePath, "utf-8");
-      const parsed = z11.array(RunResultSchema).safeParse(JSON.parse(data));
+      const parsed = z15.array(RunResultSchema).safeParse(JSON.parse(data));
       if (parsed.success) {
         this.history = parsed.data.slice(0, MAX_HISTORY);
       }
@@ -8121,6 +9606,25 @@ var Orchestrator = class extends EventEmitter {
   prDetector;
   maintenanceScheduler = null;
   maintenanceReporter = null;
+  // Phase 3 webhooks. `webhookStore` is constructed at server-start and held
+  // only as a local; it's passed into `ServerDependencies` and
+  // `wireWebhookFanout` once and never re-read on `this`. The fan-out
+  // teardown handle is kept on the instance so `stop()` can detach listeners.
+  //
+  // Phase 4 delivery durability: the WebhookQueue (SQLite at
+  // `.harness/webhook-queue.sqlite`) and the WebhookDelivery worker are
+  // retained as instance fields so `stop()` can drain in-flight deliveries
+  // (await worker.stop()) and close the SQLite handle (queue.close()).
+  webhookFanoutOff;
+  webhookQueue;
+  webhookDeliveryWorker;
+  // Phase 5: prompt-cache metrics + OTLP trace export. Both are constructed
+  // unconditionally so non-telemetry call sites can reference them safely; the
+  // OTLPExporter is only handed a fanout subscription when config supplies an
+  // endpoint, and `enabled: false` keeps push() a constant-time no-op.
+  cacheMetrics;
+  otlpExporter;
+  telemetryFanoutOff;
   orchestratorIdPromise;
   recorder;
   intelligenceRunner;
@@ -8155,6 +9659,7 @@ var Orchestrator = class extends EventEmitter {
    */
   constructor(config, promptTemplate, overrides) {
     super();
+    this.setMaxListeners(50);
     this.config = config;
     this.promptTemplate = promptTemplate;
     this.state = createEmptyState(config);
@@ -8181,7 +9686,8 @@ var Orchestrator = class extends EventEmitter {
     this.renderer = new PromptRenderer();
     this.overrideBackend = overrides?.backend ?? null;
     this.interactionQueue = new InteractionQueue(
-      path16.join(config.workspace.root, "..", "interactions")
+      path16.join(config.workspace.root, "..", "interactions"),
+      this
     );
     this.analysisArchive = new AnalysisArchive(path16.join(config.workspace.root, "..", "analyses"));
     const backendsMap = this.config.agent.backends ?? {};
@@ -8197,6 +9703,7 @@ var Orchestrator = class extends EventEmitter {
         this.localResolvers.set(name, new LocalModelResolver(resolverOpts));
       }
     }
+    this.cacheMetrics = new CacheMetricsRecorder();
     if (this.config.agent.backends !== void 0 && Object.keys(this.config.agent.backends).length > 0) {
       const sandboxPolicy = this.config.agent.sandboxPolicy === "docker" ? "docker" : "none";
       const firstBackendName = Object.keys(this.config.agent.backends)[0];
@@ -8209,6 +9716,7 @@ var Orchestrator = class extends EventEmitter {
         sandboxPolicy,
         ...this.config.agent.container !== void 0 ? { container: this.config.agent.container } : {},
         ...this.config.agent.secrets !== void 0 ? { secrets: this.config.agent.secrets } : {},
+        cacheMetrics: this.cacheMetrics,
         getResolverModelFor: (name) => {
           const resolver = this.localResolvers.get(name);
           return resolver ? () => resolver.resolveModel() : void 0;
@@ -8255,8 +9763,47 @@ var Orchestrator = class extends EventEmitter {
     this.intelligenceRunner = new IntelligencePipelineRunner(ctx);
     this.completionHandler = new CompletionHandler(ctx, this.postLifecycleComment.bind(this));
     if (config.server?.port) {
+      const webhookStore = new WebhookStore(
+        path16.join(this.projectRoot, ".harness", "webhooks.json")
+      );
+      this.webhookQueue = new WebhookQueue(
+        path16.join(this.projectRoot, ".harness", "webhook-queue.sqlite")
+      );
+      const webhookDelivery = new WebhookDelivery({
+        queue: this.webhookQueue,
+        store: webhookStore
+      });
+      this.webhookDeliveryWorker = webhookDelivery;
+      this.webhookFanoutOff = wireWebhookFanout({
+        bus: this,
+        store: webhookStore,
+        delivery: webhookDelivery
+      });
+      webhookDelivery.start();
+      const otlpCfg = config.telemetry?.export?.otlp;
+      if (otlpCfg) {
+        this.otlpExporter = new OTLPExporter({
+          endpoint: otlpCfg.endpoint,
+          ...otlpCfg.enabled !== void 0 ? { enabled: otlpCfg.enabled } : {},
+          ...otlpCfg.headers !== void 0 ? { headers: otlpCfg.headers } : {},
+          ...otlpCfg.flushIntervalMs !== void 0 ? { flushIntervalMs: otlpCfg.flushIntervalMs } : {},
+          ...otlpCfg.batchSize !== void 0 ? { batchSize: otlpCfg.batchSize } : {}
+        });
+        this.telemetryFanoutOff = wireTelemetryFanout({
+          bus: this,
+          exporter: this.otlpExporter,
+          webhookDelivery,
+          store: webhookStore
+        });
+      }
       this.server = new OrchestratorServer(this, config.server.port, {
         interactionQueue: this.interactionQueue,
+        webhooks: {
+          store: webhookStore,
+          delivery: webhookDelivery,
+          queue: this.webhookQueue
+        },
+        cacheMetrics: this.cacheMetrics,
         plansDir: path16.resolve(config.workspace.root, "..", "docs", "plans"),
         pipeline: this.pipeline,
         analysisArchive: this.analysisArchive,
@@ -9165,6 +10712,9 @@ var Orchestrator = class extends EventEmitter {
     if (this.server) {
       void this.server.start();
     }
+    if (this.otlpExporter) {
+      this.otlpExporter.start();
+    }
     await this.initLocalModelAndPipeline();
     await this.ensureClaimManager();
     const runningIssueIds = new Set(this.state.running.keys());
@@ -9228,6 +10778,26 @@ var Orchestrator = class extends EventEmitter {
       this.maintenanceScheduler.stop();
       this.maintenanceScheduler = null;
     }
+    if (this.webhookFanoutOff) {
+      this.webhookFanoutOff();
+      delete this.webhookFanoutOff;
+    }
+    if (this.telemetryFanoutOff) {
+      this.telemetryFanoutOff();
+      delete this.telemetryFanoutOff;
+    }
+    if (this.otlpExporter) {
+      await this.otlpExporter.stop();
+      delete this.otlpExporter;
+    }
+    if (this.webhookDeliveryWorker) {
+      await this.webhookDeliveryWorker.stop();
+      delete this.webhookDeliveryWorker;
+    }
+    if (this.webhookQueue) {
+      this.webhookQueue.close();
+      delete this.webhookQueue;
+    }
     if (this.server) {
       this.server.stop();
     }
@@ -9648,14 +11218,18 @@ export {
   ClaimManager,
   InteractionQueue,
   LinearGraphQLStub,
+  MAX_ATTEMPTS,
   MockBackend,
   ORCHESTRATOR_IDENTITY_FILE,
   Orchestrator,
   OrchestratorBackendFactory,
   PRDetector,
   PromptRenderer,
+  RETRY_DELAYS_MS,
   RoadmapTrackerAdapter,
   StreamRecorder,
+  TokenStore,
+  WebhookQueue,
   WorkflowLoader,
   WorkspaceHooks,
   WorkspaceManager,