@aria_asi/cli 0.2.30 → 0.2.31

package/dist/runtime/service.mjs

@@ -3,7 +3,7 @@
 import { createServer } from 'node:http';
 import { createRequire } from 'node:module';
 import { createHash, createCipheriv, createDecipheriv, randomBytes, randomUUID, scryptSync } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 
@@ -14,6 +14,11 @@ import {
   extractAnthropicUserMessage,
   extractOpenAIUserMessage,
 } from './provider-proxy.mjs';
+import { recordTokenUsage, brandModel, getUsageSummary, getBillingSummary, getSubscriptionTier } from './metering.mjs';
+import { deployFleet, loadFleet, saveFleet, getFleetStatus, buildAgentSystemPrompt } from './fleet-engine.mjs';
+import { listPlugins, installPlugin, configurePlugin, dispatchHook } from './plugin-engine.mjs';
+import { listWorkflowTemplates, configureWorkflow, getWorkflowStatus, startWorkflow, approveWorkflowStep } from './workflow-engine.mjs';
+import { hqAuthMiddleware, generateApiKey, loginUser, registerUser, revokeSession, listAllTenants } from './auth-middleware.mjs';
 import {
   ARISTOTLE_28_MODULES,
   NOOR_COGNITIVE_SUITE,
@@ -37,8 +42,13 @@ const { runFullChain } = require('./vendor/aria-gate-runtime/index.js');
 const DEFAULT_HOST = process.env.ARIA_RUNTIME_HOST || '127.0.0.1';
 const DEFAULT_PORT = Number(process.env.ARIA_RUNTIME_PORT || 4319);
 const DEFAULT_HARNESS_URL =
+  process.env.ARIA_HARNESS_DAEMON_URL ||
+  process.env.ARIA_HIVE_RUNTIME_URL ||
   process.env.ARIA_HARNESS_BASE_URL ||
   process.env.ARIA_HARNESS_URL ||
+  process.env.ARIA_SOUL_URL ||
+  process.env.ARIAS_SOUL_URL ||
+  process.env.ARIA_SOUL_BASE_URL ||
   'https://harness.ariasos.com';
 const DEFAULT_RUNTIME_URL = process.env.ARIA_RUNTIME_URL || `http://${DEFAULT_HOST}:${DEFAULT_PORT}`;
 const DEFAULT_QDRANT_URL = process.env.ARIA_QDRANT_URL || 'http://127.0.0.1:6333';
@@ -48,16 +58,23 @@ const DEFAULT_FORGE_SERVICE_URL =
   process.env.FORGE_SERVICE_URL ||
   `${DEFAULT_HARNESS_URL.replace(/\/$/, '')}/api/forge/psi`;
 const DEFAULT_HEARTBEAT_GRACE_SECONDS = Number(process.env.ARIA_RUNTIME_HEARTBEAT_GRACE_SECONDS || 900);
+const DEFAULT_OFFLINE_BUNDLE_SOFT_TTL_SECONDS = Number(process.env.ARIA_RUNTIME_OFFLINE_BUNDLE_SOFT_TTL_SECONDS || 86400);
+const DEFAULT_OFFLINE_BUNDLE_HARD_TTL_SECONDS = Number(process.env.ARIA_RUNTIME_OFFLINE_BUNDLE_HARD_TTL_SECONDS || 259200);
 const DEFAULT_JOB_CLAIM_SECONDS = Number(process.env.ARIA_RUNTIME_JOB_CLAIM_SECONDS || 120);
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const STATE_DIR = join(__dirname, 'state');
 const LEASE_PATH = join(STATE_DIR, 'lease.enc');
+const OFFLINE_BUNDLE_PATH = join(STATE_DIR, 'offline-policy-bundle.enc');
 const RUNTIME_META_PATH = join(STATE_DIR, 'runtime-meta.json');
 const AUTONOMY_STATE_PATH = join(STATE_DIR, 'autonomy.json');
 const COGNITION_STATE_PATH = join(STATE_DIR, 'cognition-state.enc');
 const REVOCATION_LOCK_PATH = join(STATE_DIR, 'revoked.json');
 const CONFIG_PATH = join(process.env.HOME || '', '.aria', 'config.json');
 const CODEBASE_AWARENESS_STATE_PATH = join(process.env.HOME || '', '.aria', 'codebase-awareness-state.json');
+const LEGACY_PACKET_CACHE_CANDIDATES = [
+  join(process.env.HOME || '', '.aria', '.aria-harness-last-packet.json'),
+  join(process.env.HOME || '', '.claude', '.aria-harness-last-packet.json'),
+];
 const leaseCache = new Map();
 const TELEMETRY_LIMIT = 250;
 const DECISION_LIMIT = 250;
@@ -88,10 +105,14 @@ const READABLE_LENS_SLOTS = [
 const DOCTRINE_TRIGGER_MAP_CANDIDATES = [
   join(__dirname, 'discipline', 'doctrine_trigger_map.json'),
   join(__dirname, 'doctrine_trigger_map.json'),
+  join(process.env.HOME || '', '.aria', 'runtime', 'discipline', 'doctrine_trigger_map.json'),
+  join(process.env.HOME || '', '.aria', 'runtime', 'doctrine_trigger_map.json'),
   join(process.env.HOME || '', '.claude', 'hooks', 'doctrine_trigger_map.json'),
   join(process.env.HOME || '', '.claude', 'projects', '-home-hamzaibrahim1', 'memory', 'doctrine_trigger_map.json'),
   join(process.env.HOME || '', '.codex', 'doctrine_trigger_map.json'),
+  join(process.env.HOME || '', '.opencode', 'doctrine_trigger_map.json'),
 ];
+const DOCTRINE_TRIGGER_SYNC_INTERVAL_MS = Number(process.env.ARIA_DOCTRINE_TRIGGER_SYNC_INTERVAL_MS || 5000);
 const TOOL_DEPLOY_PATTERNS = [
   /\b(?:\.\/)?scripts\/deploy-/i,
   /\bkubectl\s+apply\b/i,
@@ -115,12 +136,75 @@ const TOOL_DESTRUCTIVE_PATTERNS = [
   /\b(?:DROP|TRUNCATE)\s+(?:TABLE|DATABASE|SCHEMA|INDEX)\b/i,
   /\bkubectl\s+delete\b/i,
 ];
+let doctrineTriggerMapCache = { sourcePath: null, map: { triggers: [] } };
+let doctrineTriggerMapSyncedAt = 0;
 
 function json(res, status, payload) {
   res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
   res.end(JSON.stringify(payload, null, 2));
 }
 
+function buildWebSocketAccept(key) {
+  return createHash('sha1')
+    .update(`${String(key || '').trim()}258EAFA5-E914-47DA-95CA-C5AB0DC85B11`)
+    .digest('base64');
+}
+
+function sendWebSocketCloseFrame(socket, code = 1008, reason = '') {
+  const reasonBuffer = Buffer.from(String(reason || ''), 'utf8');
+  const payload = Buffer.allocUnsafe(2 + reasonBuffer.length);
+  payload.writeUInt16BE(code, 0);
+  reasonBuffer.copy(payload, 2);
+
+  const header =
+    payload.length < 126
+      ? Buffer.from([0x88, payload.length])
+      : Buffer.from([0x88, 126, (payload.length >> 8) & 0xff, payload.length & 0xff]);
+
+  socket.write(Buffer.concat([header, payload]));
+}
+
+function handleWebSocketUpgrade(req, socket) {
+  const url = new URL(req.url || '/', DEFAULT_RUNTIME_URL);
+  if (url.pathname !== '/v1/responses' && url.pathname !== '/responses') {
+    socket.write('HTTP/1.1 404 Not Found\r\nConnection: close\r\n\r\n');
+    socket.destroy();
+    return;
+  }
+
+  const upgrade = String(req.headers.upgrade || '').toLowerCase();
+  const connection = String(req.headers.connection || '').toLowerCase();
+  const websocketKey = req.headers['sec-websocket-key'];
+  if (upgrade !== 'websocket' || !connection.includes('upgrade') || !websocketKey) {
+    socket.write('HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n');
+    socket.destroy();
+    return;
+  }
+
+  const accept = buildWebSocketAccept(websocketKey);
+  socket.write(
+    [
+      'HTTP/1.1 101 Switching Protocols',
+      'Upgrade: websocket',
+      'Connection: Upgrade',
+      `Sec-WebSocket-Accept: ${accept}`,
+      '\r\n',
+    ].join('\r\n'),
+  );
+
+  // Codex can fall back to the HTTPS Responses path after a real websocket
+  // handshake closes. Until Aria owns the full Responses websocket protocol,
+  // keep this seam explicit instead of returning a misleading 404.
+  setTimeout(() => {
+    try {
+      sendWebSocketCloseFrame(socket, 1008, 'aria-runtime-http-fallback');
+    } catch {}
+    try {
+      socket.end();
+    } catch {}
+  }, 25).unref?.();
+}
+
 function isNonTrivialAssistantTurn(text, toolIntents = []) {
   const body = String(text || '').trim();
   if (toolIntents.length > 0) return true;
@@ -198,6 +282,17 @@ function inferToolAction(toolName, args) {
   return 'tool';
 }
 
+function normalizeHarnessPacketPayload(payload) {
+  let current = payload;
+  for (let depth = 0; depth < 3; depth++) {
+    if (!current || typeof current !== 'object' || Array.isArray(current)) break;
+    if (!('packet' in current) || !current.packet || typeof current.packet !== 'object') break;
+    if (!('timestamp' in current) && !('version' in current)) break;
+    current = current.packet;
+  }
+  return current;
+}
+
 function summarizeToolTarget(toolName, args) {
   if (typeof args?.command === 'string' && args.command.trim()) return args.command.trim();
   if (typeof args?.file_path === 'string' && args.file_path.trim()) return args.file_path.trim();
@@ -244,11 +339,49 @@ function extractProviderToolIntents(providerStyle, providerMeta) {
 }
 
 function loadDoctrineTriggerMap() {
+  const now = Date.now();
+  if (now - doctrineTriggerMapSyncedAt < DOCTRINE_TRIGGER_SYNC_INTERVAL_MS) {
+    return doctrineTriggerMapCache.map;
+  }
+
+  const validCandidates = [];
   for (const candidate of DOCTRINE_TRIGGER_MAP_CANDIDATES) {
     const map = readJsonFile(candidate, null);
-    if (map && Array.isArray(map.triggers)) return map;
+    if (!map || !Array.isArray(map.triggers)) continue;
+    try {
+      validCandidates.push({
+        path: candidate,
+        mtimeMs: statSync(candidate).mtimeMs,
+        map,
+      });
+    } catch {}
   }
-  return { triggers: [] };
+
+  if (validCandidates.length === 0) {
+    doctrineTriggerMapCache = { sourcePath: null, map: { triggers: [] } };
+    doctrineTriggerMapSyncedAt = now;
+    return doctrineTriggerMapCache.map;
+  }
+
+  validCandidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  const latest = validCandidates[0];
+  const normalized = JSON.stringify(latest.map, null, 2) + '\n';
+  for (const candidate of DOCTRINE_TRIGGER_MAP_CANDIDATES) {
+    try {
+      const dirPath = dirname(candidate);
+      if (!existsSync(dirPath)) {
+        mkdirSync(dirPath, { recursive: true, mode: 0o755 });
+      }
+      const current = existsSync(candidate) ? readFileSync(candidate, 'utf8') : null;
+      if (current !== normalized) {
+        writeFileSync(candidate, normalized, { mode: 0o644 });
+      }
+    } catch {}
+  }
+
+  doctrineTriggerMapCache = { sourcePath: latest.path, map: latest.map };
+  doctrineTriggerMapSyncedAt = now;
+  return latest.map;
 }
 
 function collectDoctrineTriggerHits(text) {
@@ -341,6 +474,26 @@ function synthesizeOwnerLease(apiKey, reason) {
   };
 }
 
+function buildOfflineBundleFallbackPacket(bundle, error) {
+  const normalized = normalizeHarnessPacketPayload(bundle?.packet);
+  const packet = normalized && typeof normalized === 'object'
+    ? JSON.parse(JSON.stringify(normalized))
+    : null;
+  if (!packet) return null;
+  packet.runtimeOfflineBundle = {
+    phase: error?.softExpired ? 'degraded' : 'fresh',
+    cachedAt: bundle.cachedAt || null,
+    lastUpstreamOkAt: bundle.lastUpstreamOkAt || null,
+    softExpiresAt: error?.softExpiresAt || null,
+    hardExpiresAt: error?.hardExpiresAt || null,
+    ageSeconds: error?.ageSeconds ?? null,
+    doctrineBundleHash: bundle.doctrineBundleHash || null,
+    source: bundle.source || null,
+    lastUpstreamError: bundle.lastUpstreamError || null,
+  };
+  return packet;
+}
+
 function deriveEncryptionKey(secret) {
   return scryptSync(secret, 'aria-mounted-runtime', 32);
 }
@@ -390,10 +543,130 @@ function saveEncryptedLease(lease, secret) {
   writeFileSync(LEASE_PATH, encryptJson(lease, secret), { mode: 0o600 });
 }
 
+function loadEncryptedOfflineBundle(secret) {
+  try {
+    if (!existsSync(OFFLINE_BUNDLE_PATH)) return null;
+    return decryptJson(readFileSync(OFFLINE_BUNDLE_PATH, 'utf8'), secret);
+  } catch {
+    return null;
+  }
+}
+
+function saveEncryptedOfflineBundle(bundle, secret) {
+  mkdirSync(STATE_DIR, { recursive: true, mode: 0o700 });
+  writeFileSync(OFFLINE_BUNDLE_PATH, encryptJson(bundle, secret), { mode: 0o600 });
+}
+
+function computeOfflineBundleStatus(bundle, now = Date.now()) {
+  if (!bundle || typeof bundle !== 'object') {
+    return {
+      present: false,
+      phase: 'missing',
+      usable: false,
+      softExpired: true,
+      hardExpired: true,
+      ageSeconds: null,
+      softTtlSeconds: DEFAULT_OFFLINE_BUNDLE_SOFT_TTL_SECONDS,
+      hardTtlSeconds: DEFAULT_OFFLINE_BUNDLE_HARD_TTL_SECONDS,
+      softExpiresAt: null,
+      hardExpiresAt: null,
+    };
+  }
+
+  const cachedAtMs = Date.parse(bundle.cachedAt || bundle.lastUpdatedAt || bundle.lastUpstreamOkAt || '');
+  const softExpiresAt = Number(bundle.softExpiresAt || 0);
+  const hardExpiresAt = Number(bundle.hardExpiresAt || 0);
+  const ageSeconds = Number.isFinite(cachedAtMs) ? Math.max(0, Math.round((now - cachedAtMs) / 1000)) : null;
+  const softExpired = !softExpiresAt || softExpiresAt <= now;
+  const hardExpired = !hardExpiresAt || hardExpiresAt <= now;
+  const phase = hardExpired ? 'expired' : (softExpired ? 'degraded' : 'fresh');
+  return {
+    present: true,
+    phase,
+    usable: !hardExpired,
+    softExpired,
+    hardExpired,
+    ageSeconds,
+    softTtlSeconds: Number(bundle.softTtlSeconds || DEFAULT_OFFLINE_BUNDLE_SOFT_TTL_SECONDS),
+    hardTtlSeconds: Number(bundle.hardTtlSeconds || DEFAULT_OFFLINE_BUNDLE_HARD_TTL_SECONDS),
+    softExpiresAt: softExpiresAt ? new Date(softExpiresAt).toISOString() : null,
+    hardExpiresAt: hardExpiresAt ? new Date(hardExpiresAt).toISOString() : null,
+    cachedAt: bundle.cachedAt || null,
+    lastUpstreamOkAt: bundle.lastUpstreamOkAt || null,
+    source: bundle.source || null,
+    doctrineBundleHash: bundle.doctrineBundleHash || null,
+    lastUpstreamError: bundle.lastUpstreamError || null,
+  };
+}
+
+function persistOfflineBundle(secret, payload) {
+  const existing = loadEncryptedOfflineBundle(secret);
+  const now = Date.now();
+  const base = existing && typeof existing === 'object' ? existing : {};
+  const cachedAt = typeof base.cachedAt === 'string' && base.cachedAt ? base.cachedAt : new Date(now).toISOString();
+  const softTtlSeconds = Math.max(60, Number(payload.softTtlSeconds || base.softTtlSeconds || DEFAULT_OFFLINE_BUNDLE_SOFT_TTL_SECONDS));
+  const hardTtlSeconds = Math.max(softTtlSeconds, Number(payload.hardTtlSeconds || base.hardTtlSeconds || DEFAULT_OFFLINE_BUNDLE_HARD_TTL_SECONDS));
+  const refreshedAt = new Date(now).toISOString();
+  const bundle = {
+    ...base,
+    ...payload,
+    cachedAt,
+    refreshedAt,
+    lastUpdatedAt: refreshedAt,
+    lastUpstreamOkAt: payload.lastUpstreamOkAt || refreshedAt,
+    softTtlSeconds,
+    hardTtlSeconds,
+    softExpiresAt: now + softTtlSeconds * 1000,
+    hardExpiresAt: now + hardTtlSeconds * 1000,
+  };
+  saveEncryptedOfflineBundle(bundle, secret);
+  return bundle;
+}
+
+function readLegacyPacketCache() {
+  const candidates = [];
+  for (const candidate of LEGACY_PACKET_CACHE_CANDIDATES) {
+    try {
+      if (!existsSync(candidate)) continue;
+      const raw = JSON.parse(readFileSync(candidate, 'utf8'));
+      const packet = normalizeHarnessPacketPayload(raw.packet ?? raw);
+      const harness = typeof packet?.harness === 'string' ? packet.harness : '';
+      if (!harness.trim()) continue;
+      candidates.push({
+        path: candidate,
+        packet,
+        mtimeMs: statSync(candidate).mtimeMs,
+      });
+    } catch {}
+  }
+  candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return candidates[0] || null;
+}
+
+function ensureOfflineBundleSeeded(secret, lease = null) {
+  const existing = loadEncryptedOfflineBundle(secret);
+  const normalizedExisting = normalizeHarnessPacketPayload(existing?.packet);
+  if (normalizedExisting && typeof normalizedExisting.harness === 'string' && normalizedExisting.harness.trim()) {
+    return existing;
+  }
+  const legacy = readLegacyPacketCache();
+  if (!legacy) return existing;
+  return persistOfflineBundle(secret, {
+    ...(existing && typeof existing === 'object' ? existing : {}),
+    keyHash: hashKey(secret),
+    packet: legacy.packet,
+    lease: lease || existing?.lease || loadEncryptedLease(secret),
+    source: `legacy-cache:${legacy.path}`,
+    doctrineBundleHash: lease?.claims?.doctrine_bundle_hash || existing?.doctrineBundleHash || null,
+    lastUpstreamError: existing?.lastUpstreamError || null,
+  });
+}
+
 function defaultCognitionState() {
   return {
     telemetry: [],
     decisions: [],
+    pendingDecisions: [],
     evolutionPrinciples: [],
     aegisPatterns: [],
     heartbeats: [],
@@ -586,6 +859,7 @@ function summarizeCognitionState(state) {
   return {
     telemetryTurns: Array.isArray(state.telemetry) ? state.telemetry.length : 0,
     decisions: Array.isArray(state.decisions) ? state.decisions.length : 0,
+    pendingDecisionUploads: Array.isArray(state.pendingDecisions) ? state.pendingDecisions.length : 0,
     evolutionPrinciples: Array.isArray(state.evolutionPrinciples) ? state.evolutionPrinciples.length : 0,
     aegisPatterns: Array.isArray(state.aegisPatterns) ? state.aegisPatterns.length : 0,
     heartbeats: Array.isArray(state.heartbeats) ? state.heartbeats.length : 0,
@@ -827,6 +1101,15 @@ async function heartbeatUpstream(req, body, client, apiKey) {
       },
     };
     clearRevocationLock();
+    const existingBundle = loadEncryptedOfflineBundle(apiKey);
+    persistOfflineBundle(apiKey, {
+      keyHash: lease.keyHash,
+      lease,
+      packet: existingBundle?.packet || null,
+      source: existingBundle?.source || client.baseUrl || DEFAULT_HARNESS_URL,
+      doctrineBundleHash: lease.claims?.doctrine_bundle_hash || existingBundle?.doctrineBundleHash || null,
+      lastUpstreamError: null,
+    });
   } catch (error) {
     if (!ownerBypassAllowed) {
       throw error;
@@ -883,14 +1166,45 @@ async function ensureLease(req, body, client) {
 
   const keyHash = hashKey(apiKey);
   const cached = leaseCache.get(keyHash) || loadEncryptedLease(apiKey);
+  ensureOfflineBundleSeeded(apiKey, cached);
   if (cached && cached.hardStopAt > Date.now()) {
     leaseCache.set(keyHash, cached);
     if (cached.nextRequiredAt > Date.now()) {
       return cached;
     }
   }
-
-  return heartbeatUpstream(req, body, client, apiKey);
+  try {
+    return await heartbeatUpstream(req, body, client, apiKey);
+  } catch (error) {
+    const bundle = ensureOfflineBundleSeeded(apiKey, cached) || loadEncryptedOfflineBundle(apiKey);
+    const bundleStatus = computeOfflineBundleStatus(bundle);
+    if (bundle?.keyHash === keyHash && bundleStatus.usable) {
+      const fallbackLease = cached || bundle.lease || null;
+      if (fallbackLease) {
+        const lease = {
+          ...fallbackLease,
+          offlineBundle: {
+            phase: bundleStatus.phase,
+            ageSeconds: bundleStatus.ageSeconds,
+            softExpiresAt: bundleStatus.softExpiresAt,
+            hardExpiresAt: bundleStatus.hardExpiresAt,
+            doctrineBundleHash: bundleStatus.doctrineBundleHash,
+            source: bundleStatus.source,
+            lastUpstreamError: error instanceof Error ? error.message : String(error),
+          },
+        };
+        leaseCache.set(keyHash, lease);
+        persistOfflineBundle(apiKey, {
+          ...bundle,
+          lease,
+          lastUpstreamError: error instanceof Error ? error.message : String(error),
+          lastUpstreamOkAt: bundle.lastUpstreamOkAt || bundle.cachedAt || new Date().toISOString(),
+        });
+        return lease;
+      }
+    }
+    throw error;
+  }
 }
 
 function deriveSessionId(req, body, prefix = 'runtime') {
@@ -949,6 +1263,7 @@ async function pushTelemetryUpstream(client, apiKey, payload) {
 }
 
 async function pushDecisionUpstream(client, apiKey, payload) {
+  const normalizedPayload = normalizeDecisionPayload(payload);
   const url = `${client.baseUrl || DEFAULT_HARNESS_URL}/api/decisions/log`;
   const response = await fetch(url, {
     method: 'POST',
@@ -956,7 +1271,7 @@ async function pushDecisionUpstream(client, apiKey, payload) {
       Authorization: `Bearer ${apiKey}`,
       'Content-Type': 'application/json',
     },
-    body: JSON.stringify(payload),
+    body: JSON.stringify(normalizedPayload),
   });
   if (!response.ok) {
     const body = await response.text().catch(() => response.statusText);
@@ -965,6 +1280,88 @@ async function pushDecisionUpstream(client, apiKey, payload) {
   return response.json().catch(() => ({ logged: true }));
 }
 
+function normalizeDecisionPayload(payload) {
+  const sessionId = payload?.session_id || payload?.sessionId || null;
+  const decisionType = payload?.decision_type || payload?.decisionType || 'operational';
+  const category = payload?.category || payload?.decision_category || payload?.decisionCategory || payload?.surface || 'runtime';
+  const decision = payload?.decision || payload?.summary || payload?.outcome || decisionType;
+  const reasoning =
+    payload?.reasoning ||
+    payload?.summary ||
+    (payload?.outcome ? `Outcome: ${payload.outcome}` : 'Runtime decision log');
+  const context =
+    payload?.context ||
+    (sessionId ? `Session ${sessionId}` : 'Runtime decision log');
+  const outcomeRaw = String(payload?.outcome || '').toLowerCase();
+  const outcome =
+    outcomeRaw === 'validated' ? 'success'
+      : outcomeRaw === 'error' ? 'failure'
+      : ['success', 'failure', 'neutral', 'pending'].includes(outcomeRaw) ? outcomeRaw
+      : undefined;
+
+  return {
+    ...payload,
+    session_id: sessionId,
+    decision_type: decisionType,
+    category,
+    context,
+    decision,
+    reasoning,
+    ...(outcome ? { outcome } : {}),
+  };
+}
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function pushDecisionUpstreamWithRetry(client, apiKey, payload, attempts = 3) {
+  let lastError = null;
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    try {
+      return await pushDecisionUpstream(client, apiKey, payload);
+    } catch (error) {
+      lastError = error;
+      if (attempt === attempts - 1) break;
+      await delay(250 * (2 ** attempt));
+    }
+  }
+  throw lastError || new Error('decision upstream failed');
+}
+
+async function flushPendingDecisionUploads(client, apiKey) {
+  const state = loadEncryptedCognitionState(apiKey);
+  const pending = Array.isArray(state.pendingDecisions) ? state.pendingDecisions : [];
+  if (!pending.length) {
+    return { flushed: 0, retained: 0, lastError: null };
+  }
+
+  const remaining = [];
+  let flushed = 0;
+  let lastError = null;
+  for (const entry of pending) {
+    try {
+      await pushDecisionUpstreamWithRetry(client, apiKey, entry.payload);
+      flushed++;
+    } catch (error) {
+      lastError = error instanceof Error ? error.message : String(error);
+      remaining.push({
+        ...entry,
+        attempts: Number(entry.attempts || 0) + 1,
+        lastError,
+        lastTriedAt: new Date().toISOString(),
+      });
+    }
+  }
+
+  mutateCognitionState(apiKey, (current) => ({
+    ...current,
+    pendingDecisions: remaining,
+  }));
+
+  return { flushed, retained: remaining.length, lastError };
+}
+
 function buildMinimalInjection(packet, task, aegisLearnings = null) {
   return {
     harness: packet,
@@ -1022,9 +1419,35 @@ function buildOwnerBypassPacket(message, reason = 'owner-local-bypass') {
 
 async function loadRuntimePacket(req, body, client, packetRequest, message) {
   if (body.packet) return body.packet;
+  const apiKey = resolveApiKey(req, body);
+  ensureOfflineBundleSeeded(apiKey, leaseCache.get(hashKey(apiKey)) || loadEncryptedLease(apiKey));
   try {
-    return await client.getHarnessPacket(packetRequest || {});
+    const wrapped = await client.getHarnessPacket(packetRequest || {});
+    const packet = normalizeHarnessPacketPayload(wrapped?.packet || wrapped);
+    const lease = leaseCache.get(hashKey(apiKey)) || loadEncryptedLease(apiKey);
+    persistOfflineBundle(apiKey, {
+      keyHash: hashKey(apiKey),
+      packet,
+      lease,
+      source: client.baseUrl || DEFAULT_HARNESS_URL,
+      doctrineBundleHash: lease?.claims?.doctrine_bundle_hash || null,
+      lastUpstreamError: null,
+    });
+    return packet;
   } catch (error) {
+    const bundle = ensureOfflineBundleSeeded(apiKey, leaseCache.get(hashKey(apiKey)) || loadEncryptedLease(apiKey)) || loadEncryptedOfflineBundle(apiKey);
+    const bundleStatus = computeOfflineBundleStatus(bundle);
+    if (bundle?.keyHash === hashKey(apiKey) && bundleStatus.usable) {
+      const fallbackPacket = buildOfflineBundleFallbackPacket(bundle, bundleStatus);
+      if (fallbackPacket) {
+        persistOfflineBundle(apiKey, {
+          ...bundle,
+          lastUpstreamError: error instanceof Error ? error.message : String(error),
+          lastUpstreamOkAt: bundle.lastUpstreamOkAt || bundle.cachedAt || new Date().toISOString(),
+        });
+        return fallbackPacket;
+      }
+    }
     if (!isOwnerBypassRequest(req, body)) {
       throw error;
     }
@@ -1266,6 +1689,174 @@ function anthropicResponseEnvelope(text, providerMeta, extra = {}, debug = false
   };
 }
 
+function flattenResponsesTextContent(content) {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) {
+    if (typeof content?.text === 'string') return content.text;
+    if (typeof content?.content === 'string') return content.content;
+    return '';
+  }
+  return content
+    .map((part) => {
+      if (typeof part === 'string') return part;
+      if (typeof part?.text === 'string') return part.text;
+      if (typeof part?.content === 'string') return part.content;
+      if ((part?.type === 'input_text' || part?.type === 'output_text' || part?.type === 'text') && typeof part?.text === 'string') {
+        return part.text;
+      }
+      return '';
+    })
+    .filter(Boolean)
+    .join('\n');
+}
+
+function normalizeResponsesTool(tool) {
+  if (!tool || typeof tool !== 'object') return null;
+  if (tool.type === 'function' && tool.function && typeof tool.function === 'object') {
+    return tool;
+  }
+  if (tool.type === 'function' || typeof tool.name === 'string') {
+    return {
+      type: 'function',
+      function: {
+        name: tool.name || tool.function?.name || 'tool',
+        description: tool.description || tool.function?.description || '',
+        parameters: tool.parameters || tool.function?.parameters || { type: 'object', properties: {} },
+      },
+    };
+  }
+  return tool;
+}
+
+function responsesInputToMessages(input) {
+  if (typeof input === 'string' && input.trim()) {
+    return [{ role: 'user', content: input.trim() }];
+  }
+  if (!Array.isArray(input)) return [];
+
+  const messages = [];
+  for (const item of input) {
+    if (!item || typeof item !== 'object') continue;
+    if (item.type === 'message') {
+      const role = typeof item.role === 'string' ? item.role : 'user';
+      const text = flattenResponsesTextContent(item.content);
+      if (text) messages.push({ role, content: text });
+      continue;
+    }
+    if (item.type === 'input_text' || item.type === 'output_text' || item.type === 'text') {
+      const role = item.role === 'assistant' ? 'assistant' : 'user';
+      const text = flattenResponsesTextContent(item);
+      if (text) messages.push({ role, content: text });
+      continue;
+    }
+    if (item.type === 'function_call_output') {
+      const outputText =
+        typeof item.output === 'string'
+          ? item.output
+          : JSON.stringify(item.output || {});
+      if (outputText) {
+        messages.push({
+          role: 'tool',
+          tool_call_id: item.call_id || item.id || null,
+          content: outputText,
+        });
+      }
+      continue;
+    }
+    if (item.type === 'function_call') {
+      const args =
+        typeof item.arguments === 'string'
+          ? item.arguments
+          : JSON.stringify(item.arguments || item.input || {});
+      messages.push({
+        role: 'assistant',
+        content: `${item.name || 'function_call'} ${args}`.trim(),
+      });
+    }
+  }
+  return messages;
+}
+
+function responsesRequestToOpenAIBody(body = {}) {
+  const messages = responsesInputToMessages(body.input);
+  const instructions = typeof body.instructions === 'string' && body.instructions.trim()
+    ? [{ role: 'system', content: body.instructions.trim() }]
+    : [];
+
+  return {
+    ...body,
+    client: body.client || 'codex',
+    surface: body.surface || 'codex',
+    messages: [...instructions, ...messages],
+    tools: Array.isArray(body.tools) ? body.tools.map(normalizeResponsesTool).filter(Boolean) : undefined,
+    tool_choice: body.tool_choice,
+    max_completion_tokens: body.max_output_tokens || body.max_completion_tokens,
+    metadata: {
+      ...(body.metadata && typeof body.metadata === 'object' ? body.metadata : {}),
+      response_api: true,
+      client: body.client || 'codex',
+      surface: body.surface || 'codex',
+    },
+  };
+}
+
+function openAiCompletionToResponsesEnvelope(body, completion) {
+  const message = completion?.choices?.[0]?.message || {};
+  const text = typeof message.content === 'string' ? message.content : '';
+  const toolCalls = Array.isArray(message.tool_calls) ? message.tool_calls : [];
+  const output = [];
+
+  if (text) {
+    output.push({
+      id: `msg_${randomUUID().replace(/-/g, '')}`,
+      type: 'message',
+      role: 'assistant',
+      status: 'completed',
+      content: [
+        {
+          type: 'output_text',
+          text,
+        },
+      ],
+    });
+  }
+
+  for (const toolCall of toolCalls) {
+    const callId = toolCall?.id || `call_${randomUUID().replace(/-/g, '')}`;
+    const functionInfo = toolCall?.function || {};
+    output.push({
+      id: callId,
+      type: 'function_call',
+      status: 'completed',
+      call_id: callId,
+      name: functionInfo.name || toolCall?.name || 'tool',
+      arguments:
+        typeof functionInfo.arguments === 'string'
+          ? functionInfo.arguments
+          : JSON.stringify(functionInfo.arguments || toolCall?.arguments || {}),
+    });
+  }
+
+  return {
+    id: `resp_${randomUUID().replace(/-/g, '')}`,
+    object: 'response',
+    created_at: new Date().toISOString(),
+    status: 'completed',
+    model: completion?.model || body?.model || 'aria-runtime',
+    output,
+    output_text: text,
+    usage: completion?.usage
+      ? {
+          input_tokens: completion.usage.prompt_tokens || 0,
+          output_tokens: completion.usage.completion_tokens || 0,
+          total_tokens: completion.usage.total_tokens || ((completion.usage.prompt_tokens || 0) + (completion.usage.completion_tokens || 0)),
+        }
+      : undefined,
+    aria: completion?.aria || null,
+    metadata: body?.metadata || null,
+  };
+}
+
 function toReadableSignal(name) {
   const map = {
     fitrah_gate: 'truth boundary',
@@ -1644,6 +2235,10 @@ function computeForgeContractIssues(manifest, forgeResult) {
 }
 
 async function persistTurnArtifacts(req, body, client, apiKey, turn) {
+  persistMizanBundle(apiKey, turn.preBundle, 'runtime/v1-pre');
+  persistMizanBundle(apiKey, turn.midBundle, 'runtime/v1-mid');
+  persistMizanBundle(apiKey, turn.postBundle, 'runtime/v1-post');
+
   const evolutionPrinciples = extractEvolutionPrinciples(turn.packet, [turn.preResult, turn.midResult, turn.postResult]);
   const aegisPatterns = [
     ...extractAegisPatterns(turn.midResult || {}),
@@ -1783,39 +2378,93 @@ async function persistTurnArtifacts(req, body, client, apiKey, turn) {
     await pushTelemetryUpstream(client, apiKey, telemetryPayload);
   } catch {}
 
-  if (findVerifiedState(turn.finalText) || /recommend|should|propose|choose/i.test(turn.finalText)) {
+  const isDecisionTurn =
+    (turn.turnClass?.intensity && turn.turnClass.intensity !== 'light') ||
+    isNonTrivialAssistantTurn(turn.userMessage || '', []) ||
+    isNonTrivialAssistantTurn(turn.finalText || '', []);
+  if (isDecisionTurn) {
+    const surface =
+      body?.surface ||
+      body?.platform ||
+      body?.client ||
+      body?.metadata?.surface ||
+      body?.metadata?.client ||
+      'aria-mounted-runtime';
+    const reasoning = [
+      ...(turn.preResult?.notes || []),
+      ...(turn.midResult?.notes || []),
+      ...(turn.postResult?.notes || []),
+      ...(Array.isArray(turn.validation?.violations) ? turn.validation.violations : []),
+      ...(Array.isArray(turn.layer3?.failures)
+        ? turn.layer3.failures.map((failure) => failure?.detail).filter(Boolean)
+        : []),
+    ]
+      .join(' | ')
+      .slice(0, 4000) || 'Aria runtime cognition turn';
     const decisionPayload = {
       decision_type: body?.metadata?.decision_type || 'runtime-turn',
       category: body?.metadata?.decision_category || 'cognition-control-plane',
-      context: turn.userMessage.slice(0, 2000) || 'mounted runtime turn',
-      decision: turn.finalText.slice(0, 2000),
-      reasoning: [
-        ...(turn.preResult?.notes || []),
-        ...(turn.midResult?.notes || []),
-        ...(turn.postResult?.notes || []),
-      ].join(' | ').slice(0, 4000) || 'Aria runtime cognition turn',
+      context:
+        (turn.userMessage && turn.userMessage.slice(0, 2000)) ||
+        `${surface} runtime turn (${turn.providerMeta.provider || 'provider'})`,
+      decision: turn.success ? 'turn completed' : 'turn blocked by runtime gate',
+      reasoning,
       outcome: 'pending',
-      expected_outcome: {
-        predicate: 'response survives runtime validation and compounds into central telemetry',
+      outcome_details: {
+        expected: body?.metadata?.expected_outcome || null,
+        immediate_actual: {
+          success: turn.success,
+          validation_severity: turn.validation?.severity || null,
+          layer3_pass: turn.layer3?.pass ?? null,
+          doctrine_hits: Array.isArray(turn.layer3?.doctrine?.hits)
+            ? turn.layer3.doctrine.hits.length
+            : 0,
+        },
+        anchors: [
+          turn.preReceipt?.receiptId ? `pre_receipt:${turn.preReceipt.receiptId}` : null,
+          turn.midReceipt?.receiptId ? `mid_receipt:${turn.midReceipt.receiptId}` : null,
+          turn.postReceipt?.receiptId ? `post_receipt:${turn.postReceipt.receiptId}` : null,
+        ].filter(Boolean),
+      },
+      expected_outcome: body?.metadata?.expected_outcome || {
+        predicate: 'turn survives runtime validation and compounds into central telemetry with canonical receipts',
         measurable_type: 'boolean',
         threshold: true,
       },
-      source: 'aria-mounted-runtime',
+      metadata: {
+        session_id: turn.sessionId,
+        surface,
+        provider: turn.providerMeta.provider || null,
+        finish_reason: turn.providerMeta.finishReason || null,
+        pre_receipt_id: turn.preReceipt?.receiptId || null,
+        mid_receipt_id: turn.midReceipt?.receiptId || null,
+        post_receipt_id: turn.postReceipt?.receiptId || null,
+        validation_severity: turn.validation?.severity || null,
+        validation_passed: turn.validation?.passed ?? null,
+        layer3_pass: turn.layer3?.pass ?? null,
+        packet_bypassed: turn.packetBypassed === true,
+      },
+      source: body?.metadata?.decision_source || `${surface}-runtime`,
       model_used: turn.providerMeta.model,
       code_links: body?.metadata?.code_links || null,
     };
+    let decisionResult = null;
+    let decisionError = null;
     try {
-      const decisionResult = await pushDecisionUpstream(client, apiKey, decisionPayload);
-      mutateCognitionState(apiKey, (state) => ({
-        ...state,
-        decisions: appendBounded(state.decisions, {
-          at: new Date().toISOString(),
-          sessionId: turn.sessionId,
-          decision: decisionPayload,
-          result: decisionResult,
-        }, DECISION_LIMIT),
-      }));
-    } catch {}
+      decisionResult = await pushDecisionUpstream(client, apiKey, decisionPayload);
+    } catch (error) {
+      decisionError = error instanceof Error ? error.message : String(error);
+    }
+    mutateCognitionState(apiKey, (state) => ({
+      ...state,
+      decisions: appendBounded(state.decisions, {
+        at: new Date().toISOString(),
+        sessionId: turn.sessionId,
+        decision: decisionPayload,
+        result: decisionResult,
+        error: decisionError,
+      }, DECISION_LIMIT),
+    }));
   }
 
   if (body.ariaGarden !== false && turn.userMessage && turn.finalText) {
@@ -1841,6 +2490,20 @@ async function handleProviderProxy(req, body, client, providerStyle) {
     ? await callProviderForAnthropic(body, turn.ariaSystemPrompt)
     : await callProviderForOpenAI(body, turn.ariaSystemPrompt);
 
+  try {
+    recordTokenUsage({
+      tenantId: body?.metadata?.jti || body?.jti || 'owner-local',
+      agentId: body?.metadata?.agentId || body?.metadata?.roleProfile || null,
+      agentName: body?.metadata?.agentName || null,
+      department: body?.metadata?.department || null,
+      sessionId: turn.sessionId,
+      provider: providerMeta.provider,
+      model: providerMeta.model,
+      usage: providerMeta.usage,
+      requestType: body?.metadata?.requestType || 'chat',
+    });
+  } catch {}
+
   let candidateText = providerMeta.text || '';
   const toolIntents = extractProviderToolIntents(providerStyle, providerMeta);
   const requiresReadableCognition = isNonTrivialAssistantTurn(candidateText, toolIntents);
@@ -1856,7 +2519,7 @@ async function handleProviderProxy(req, body, client, providerStyle) {
     try {
       validation = await client.validateOutput(candidateText, turn.sessionId);
     } catch (error) {
-      if (!turn.packetBypassed) throw error;
+      if (!turn.packetBypassed && !isOwnerBypassRequest(req, body, apiKey)) throw error;
       validation = {
         passed: true,
         severity: 'warn',
@@ -1871,7 +2534,7 @@ async function handleProviderProxy(req, body, client, providerStyle) {
       try {
         validation = await client.validateOutput(candidateText, turn.sessionId);
       } catch (error) {
-        if (!turn.packetBypassed) throw error;
+        if (!turn.packetBypassed && !isOwnerBypassRequest(req, body, apiKey)) throw error;
         validation = {
           passed: true,
           severity: 'warn',
@@ -1911,7 +2574,7 @@ async function handleProviderProxy(req, body, client, providerStyle) {
         toolGateBlockers.push(`${intent.toolName}: ${runtimeCheck.reason || 'runtime action gate blocked this tool request'}`);
       }
     } catch (error) {
-      if (!turn.packetBypassed) throw error;
+      if (!turn.packetBypassed && !isOwnerBypassRequest(req, body, apiKey)) throw error;
       toolGateBlockers.push(`${intent.toolName}: runtime action gate unavailable during owner-local-bypass`);
     }
   }
@@ -2260,6 +2923,8 @@ function packetToSubstrateSet(packet) {
 function runtimeManifest() {
   const runtimeMeta = ensureRuntimeMeta();
   const state = sweepAutonomyState(loadAutonomyState());
+  const ownerToken = readOwnerToken();
+  const offlineBundleStatus = ownerToken ? computeOfflineBundleStatus(loadEncryptedOfflineBundle(ownerToken)) : computeOfflineBundleStatus(null);
   return {
     ok: true,
     runtime: 'aria-mounted-runtime',
@@ -2306,6 +2971,8 @@ function runtimeManifest() {
       'POST /forge/synthesize',
       'POST /codebase/state',
       'POST /v1/chat/completions',
+      'POST /v1/responses',
+      'POST /responses',
       'POST /v1/messages',
     ],
     mount: {
@@ -2323,9 +2990,13 @@ function runtimeManifest() {
       },
       security: {
         encrypted_local_lease: LEASE_PATH,
+        encrypted_offline_bundle: OFFLINE_BUNDLE_PATH,
         encrypted_cognition_state: COGNITION_STATE_PATH,
         revocation_lock: REVOCATION_LOCK_PATH,
         upstream_heartbeat: '/api/license/heartbeat',
+        offline_bundle_soft_ttl_seconds: DEFAULT_OFFLINE_BUNDLE_SOFT_TTL_SECONDS,
+        offline_bundle_hard_ttl_seconds: DEFAULT_OFFLINE_BUNDLE_HARD_TTL_SECONDS,
+        offline_bundle_status: offlineBundleStatus,
       },
       memory: {
         qdrant_url: DEFAULT_QDRANT_URL,
@@ -2354,12 +3025,27 @@ async function runLayer3(req, body, client) {
     substrate: packetToSubstrateSet(packet),
     requireCognitionBlock: body.requireCognitionBlock ?? false,
   });
+  const doctrineHits = collectDoctrineTriggerHits(body.text);
+  const doctrineFailures = doctrineHits.map((hit) => ({
+    severity: String(hit.severity || 'block').toLowerCase() === 'block' ? 'block' : 'warn',
+    kind: 'drift_trigger',
+    detail: `${hit.trigger} (${hit.memory || 'doctrine_trigger_map.json'}): ${hit.message || hit.teaching || 'Doctrine trigger matched.'}`,
+  }));
+  const allFailures = [...result.failures, ...doctrineFailures];
+  const hardFailures = allFailures.filter((failure) => failure.severity === 'block');
 
   return {
-    pass: result.pass,
-    summary: result.summary,
-    failures: result.failures,
+    pass: hardFailures.length === 0,
+    summary:
+      hardFailures.length === 0
+        ? `full_chain: pass (${allFailures.length} warns)`
+        : `full_chain: ${hardFailures.length} hard failures across ${allFailures.length} total`,
+    failures: allFailures,
     packetTimestamp: packet.timestamp || null,
+    doctrine: {
+      sourcePath: doctrineTriggerMapCache.sourcePath,
+      hits: doctrineHits,
+    },
   };
 }
 
@@ -2698,6 +3384,12 @@ async function handleRoute(req, res) {
       return json(res, 200, response);
     }
 
+    if (url.pathname === '/v1/responses' || url.pathname === '/responses') {
+      const responseBody = responsesRequestToOpenAIBody(body);
+      const completion = await handleProviderProxy(req, responseBody, client, 'openai');
+      return json(res, 200, openAiCompletionToResponsesEnvelope(body, completion));
+    }
+
     if (url.pathname === '/v1/messages') {
       const response = await handleProviderProxy(req, body, client, 'anthropic');
       return json(res, 200, response);
@@ -2728,16 +3420,55 @@ async function handleRoute(req, res) {
 
     if (url.pathname === '/decision/log') {
       const apiKey = resolveApiKey(req, body);
-      const result = await pushDecisionUpstream(client, apiKey, body);
-      mutateCognitionState(apiKey, (state) => ({
-        ...state,
-        decisions: appendBounded(state.decisions, {
-          at: new Date().toISOString(),
-          decision: body,
+      const normalizedBody = normalizeDecisionPayload(body);
+      const flush = await flushPendingDecisionUploads(client, apiKey);
+      try {
+        const result = await pushDecisionUpstreamWithRetry(client, apiKey, normalizedBody);
+        mutateCognitionState(apiKey, (state) => ({
+          ...state,
+          decisions: appendBounded(state.decisions, {
+            at: new Date().toISOString(),
+            decision: normalizedBody,
+            result,
+            flushedPending: flush.flushed,
+          }, DECISION_LIMIT),
+        }));
+        return json(res, 200, {
+          ok: true,
           result,
-        }, DECISION_LIMIT),
-      }));
-      return json(res, 200, { ok: true, result });
+          flushedPending: flush.flushed,
+          retainedPending: flush.retained,
+        });
+      } catch (error) {
+        const upstreamError = error instanceof Error ? error.message : String(error);
+        mutateCognitionState(apiKey, (state) => ({
+          ...state,
+          decisions: appendBounded(state.decisions, {
+            at: new Date().toISOString(),
+            decision: normalizedBody,
+            result: {
+              logged: false,
+              queuedUpstream: true,
+              upstreamError,
+            },
+            flushedPending: flush.flushed,
+          }, DECISION_LIMIT),
+          pendingDecisions: appendBounded(state.pendingDecisions, {
+            at: new Date().toISOString(),
+            payload: normalizedBody,
+            attempts: 0,
+            lastError: upstreamError,
+            queuedBy: 'decision/log',
+          }, DECISION_LIMIT),
+        }));
+        return json(res, 200, {
+          ok: true,
+          queuedUpstream: true,
+          upstreamError,
+          flushedPending: flush.flushed,
+          retainedPending: flush.retained + 1,
+        });
+      }
     }
 
     if (url.pathname === '/aegis/patterns') {
@@ -2799,12 +3530,12 @@ async function handleRoute(req, res) {
       }
     }
 
-    if (url.pathname === '/packet') {
+    if (url.pathname === '/packet' || url.pathname === '/api/harness/codex') {
       const packet = await loadRuntimePacket(req, body, client, body.packetRequest || body, body.message || '');
       return json(res, 200, { ok: true, packet });
     }
 
-    if (url.pathname === '/consult') {
+    if (url.pathname === '/consult' || url.pathname === '/api/harness/delegate') {
       const result = await client.consult(body);
       return json(res, 200, { ok: true, ...result });
     }
@@ -2824,7 +3555,7 @@ async function handleRoute(req, res) {
       return json(res, 200, { ok: true, ...result });
     }
 
-    if (url.pathname === '/validate-output') {
+    if (url.pathname === '/validate-output' || url.pathname === '/api/harness/validate') {
       if (typeof body.text !== 'string' || typeof body.sessionId !== 'string') {
         throw new Error('validate-output requires text and sessionId');
       }
@@ -3003,6 +3734,313 @@ async function handleRoute(req, res) {
       return json(res, 200, { ok: true, ...result });
     }
 
+    // ── /hq/* routes: Agentic HQ API ──────────────────────────────
+
+    if (url.pathname.startsWith('/hq/')) {
+      const auth = hqAuthMiddleware(url.pathname, req);
+      if (!auth.authorized) {
+        return json(res, 401, { ok: false, error: auth.error || 'Unauthorized' });
+      }
+      if (auth.tenantId && !body.tenantId) body.tenantId = auth.tenantId;
+      req.hqAuth = auth;
+    }
+
+    // ── /hq/auth/* routes (public, handled before auth gate takes effect) ──
+    if (url.pathname === '/hq/auth/login') {
+      const { username, password } = body;
+      if (!username || !password) return json(res, 400, { ok: false, error: 'username and password required' });
+      const result = loginUser(username, password);
+      if (!result.ok) return json(res, 401, result);
+      return json(res, 200, { ok: true, token: result.session.token, role: result.session.role, tenantId: result.session.tenantId, email: result.session.email });
+    }
+
+    if (url.pathname === '/hq/auth/register') {
+      const { email, password, tenantId } = body;
+      if (!email || !password || !tenantId) return json(res, 400, { ok: false, error: 'email, password, and tenantId required' });
+      const result = registerUser(email, password, tenantId);
+      if (!result.ok) return json(res, 409, result);
+      const loginResult = loginUser(email, password);
+      return json(res, 200, { ok: true, token: loginResult.session.token, role: loginResult.session.role, tenantId: loginResult.session.tenantId, email: loginResult.session.email });
+    }
+
+    if (url.pathname === '/hq/auth/session') {
+      const authHeader = req.headers['authorization'] || '';
+      const token = authHeader.replace(/^Bearer\s+/i, '').trim();
+      if (!token) return json(res, 401, { ok: false, error: 'Token required' });
+      const { validateSession } = await import('./auth-middleware.mjs');
+      const session = validateSession(token);
+      if (!session.valid) return json(res, 401, { ok: false, error: 'Invalid or expired session' });
+      return json(res, 200, { ok: true, role: session.role, tenantId: session.tenantId, email: session.email });
+    }
+
+    if (url.pathname === '/hq/auth/logout') {
+      const authHeader = req.headers['authorization'] || '';
+      const token = authHeader.replace(/^Bearer\s+/i, '').trim();
+      if (token) revokeSession(token);
+      return json(res, 200, { ok: true });
+    }
+
+    // ── /hq/owner/* routes (owner-only) ──
+    if (url.pathname === '/hq/owner/tenants') {
+      const auth = req.hqAuth;
+      if (!auth || auth.role !== 'owner') return json(res, 403, { ok: false, error: 'Owner access required' });
+      const tenants = listAllTenants();
+      const enriched = tenants.map(t => {
+        const fleet = loadFleet(t.tenantId);
+        return { ...t, fleet: fleet ? { deployed: true, activeAgents: fleet.agents?.length || 0, industry: fleet.config?.industry } : { deployed: false } };
+      });
+      return json(res, 200, { ok: true, tenants: enriched });
+    }
+
+    if (url.pathname === '/hq/owner/tenant/dashboard') {
+      const auth = req.hqAuth;
+      if (!auth || auth.role !== 'owner') return json(res, 403, { ok: false, error: 'Owner access required' });
+      const { tenantId: targetTenant } = body;
+      if (!targetTenant) return json(res, 400, { ok: false, error: 'targetTenant required' });
+      const fleet = loadFleet(targetTenant);
+      if (!fleet) return json(res, 404, { ok: false, error: 'No fleet for that tenant' });
+      return json(res, 200, { ok: true, ...getFleetStatus(targetTenant) });
+    }
+
+    if (url.pathname === '/hq/metering/usage') {
+      const { tenantId, from, to } = body;
+      if (!tenantId) return json(res, 400, { ok: false, error: 'tenantId required' });
+      return json(res, 200, { ok: true, ...getUsageSummary(tenantId, { from, to }) });
+    }
+
+    if (url.pathname === '/hq/metering/billing') {
+      const { tenantId, tier } = body;
+      if (!tenantId) return json(res, 400, { ok: false, error: 'tenantId required' });
+      return json(res, 200, { ok: true, ...getBillingSummary(tenantId, tier || 'starter') });
+    }
+
+    if (url.pathname === '/hq/onboarding/chat') {
+      const { tenantId, message, state: clientState } = body;
+      if (!tenantId) return json(res, 400, { ok: false, error: 'tenantId required' });
+      const { createOnboardingSession, loadSession, saveSession, processResponse, getStepPrompt, advanceStep } = await import('./onboarding-engine.mjs');
+      let session = loadSession(tenantId) || createOnboardingSession(tenantId);
+      if (clientState) Object.assign(session.data, clientState);
+      session.history.push({ role: 'user', content: message || '', step: session.step, timestamp: new Date().toISOString() });
+
+      let ariaText = '';
+
+      // Password collection: skip LLM, take user message directly
+      if (session.step === 'credentials' && session.data.email && !session.data.password) {
+        session.data.password = message;
+        session.step = advanceStep(session.step);
+        ariaText = `Great, I have your email as ${session.data.email}. Now please type a password for your dashboard login. Make it at least 8 characters.`;
+      } else {
+        const stepPrompt = getStepPrompt(session.step);
+        try {
+          const providerResult = await callProviderForOpenAI({
+            ...body,
+            messages: [
+              { role: 'system', content: stepPrompt },
+              { role: 'user', content: message || 'Hello' },
+            ],
+          });
+          ariaText = providerResult.text || '';
+        } catch (err) {
+          ariaText = `I'd love to chat more about setting up your AI workforce! Unfortunately, I'm having trouble connecting right now. Could you try again? (Error: ${err.message})`;
+        }
+        session = processResponse(session, ariaText);
+        // After email is extracted, append password prompt
+        if (session.step === 'credentials' && session.data.email && !session.data.password) {
+          ariaText += '\n\nNow please type a password for your dashboard login (at least 8 characters). Your next message will be saved as your password.';
+        }
+      }
+      saveSession(session);
+
+      if (session.step === 'complete' && session.data.confirmed) {
+        const { buildFleetConfig } = await import('./onboarding-engine.mjs');
+        const fleetConfig = buildFleetConfig(session);
+        const enqueueJob = (jobDef) => {
+          const autonomyState = loadAutonomyState();
+          const job = { jobId: randomUUID(), kind: jobDef.kind, surface: 'fleet', sessionId: null, payload: jobDef.payload || {}, metadata: jobDef.metadata || {}, priority: jobDef.priority || 100, status: 'queued', attempts: 0, maxAttempts: 3, createdAt: new Date().toISOString(), updatedAt: new Date().toISOString(), workerId: null, claimedAt: null, claimExpiresAt: null, progress: [], garden: null };
+          autonomyState.jobs.push(job);
+          saveAutonomyState(autonomyState);
+          return job;
+        };
+        const { fleet, workerRegistrations, initialJobs } = deployFleet(tenantId, fleetConfig, enqueueJob);
+        const autonomyState = loadAutonomyState();
+        for (const reg of workerRegistrations) { ensureWorker(autonomyState, reg.workerId, reg); }
+        for (const jobDef of initialJobs) {
+          const job = { jobId: randomUUID(), kind: jobDef.kind, surface: 'fleet', sessionId: null, payload: jobDef.payload || {}, metadata: jobDef.metadata || {}, priority: jobDef.priority || 100, status: 'queued', attempts: 0, maxAttempts: 3, createdAt: new Date().toISOString(), updatedAt: new Date().toISOString(), workerId: null, claimedAt: null, claimExpiresAt: null, progress: [], garden: null };
+          autonomyState.jobs.push(job);
+        }
+        saveAutonomyState(autonomyState);
+        const apiKey = generateApiKey(tenantId);
+        let authToken = null;
+        if (session.data.email && session.data.password) {
+          const regResult = registerUser(session.data.email, session.data.password, tenantId);
+          if (regResult.ok) {
+            const loginResult = loginUser(session.data.email, session.data.password);
+            authToken = loginResult.ok ? loginResult.session.token : null;
+          }
+        }
+        return json(res, 200, { ok: true, step: 'complete', data: session.data, ariaMessage: ariaText, fleet: { deployed: true, agents: fleet.agents.length }, apiKey, authToken });
+      }
+
+      return json(res, 200, { ok: true, step: session.step, data: session.data, ariaMessage: ariaText });
+    }
+
+    if (url.pathname === '/hq/onboarding/status') {
+      const { tenantId } = body;
+      if (!tenantId) return json(res, 400, { ok: false, error: 'tenantId required' });
+      const { loadSession } = await import('./onboarding-engine.mjs');
+      const session = loadSession(tenantId);
+      if (!session) return json(res, 200, { ok: true, step: 'not-started', data: {} });
+      return json(res, 200, { ok: true, step: session.step, data: session.data, updatedAt: session.updatedAt });
+    }
+
+    if (url.pathname === '/hq/fleet/deploy') {
+      const { tenantId, config } = body;
+      if (!tenantId || !config) return json(res, 400, { ok: false, error: 'tenantId and config required' });
+      const enqueueJob = (jobDef) => {
+        const autonomyState = loadAutonomyState();
+        const job = { jobId: randomUUID(), kind: jobDef.kind, surface: jobDef.surface || 'fleet', sessionId: null, payload: jobDef.payload || {}, metadata: jobDef.metadata || {}, priority: jobDef.priority || 100, status: 'queued', attempts: 0, maxAttempts: 3, createdAt: new Date().toISOString(), updatedAt: new Date().toISOString(), workerId: null, claimedAt: null, claimExpiresAt: null, progress: [], garden: null };
+        autonomyState.jobs.push(job);
+        saveAutonomyState(autonomyState);
+        return job;
+      };
+      const { fleet, workerRegistrations, initialJobs } = deployFleet(tenantId, config, enqueueJob);
+      const autonomyState = loadAutonomyState();
+      for (const reg of workerRegistrations) {
+        ensureWorker(autonomyState, reg.workerId, reg);
+      }
+      for (const jobDef of initialJobs) {
+        const job = { jobId: randomUUID(), kind: jobDef.kind, surface: jobDef.surface || 'fleet', sessionId: null, payload: jobDef.payload || {}, metadata: jobDef.metadata || {}, priority: jobDef.priority || 100, status: 'queued', attempts: 0, maxAttempts: 3, createdAt: new Date().toISOString(), updatedAt: new Date().toISOString(), workerId: null, claimedAt: null, claimExpiresAt: null, progress: [], garden: null };
+        autonomyState.jobs.push(job);
+      }
+      saveAutonomyState(autonomyState);
+      return json(res, 200, { ok: true, fleet, workersRegistered: workerRegistrations.length, jobsEnqueued: initialJobs.length });
+    }
+
+    if (url.pathname === '/hq/fleet/status') {
+      const { tenantId } = body;
+      if (!tenantId) return json(res, 400, { ok: false, error: 'tenantId required' });
+      return json(res, 200, getFleetStatus(tenantId));
+    }
+
+    if (url.pathname === '/hq/fleet/agent/chat') {
+      const { tenantId, agentId, message: agentMsg } = body;
+      if (!tenantId || !agentId || !agentMsg) return json(res, 400, { ok: false, error: 'tenantId, agentId, and message required' });
+      const fleet = loadFleet(tenantId);
+      if (!fleet) return json(res, 404, { ok: false, error: 'No fleet deployed' });
+      const agent = (fleet.agents || []).find(a => a.id === agentId || a.templateId === agentId);
+      if (!agent) return json(res, 404, { ok: false, error: `Agent ${agentId} not found` });
+      const systemPrompt = buildAgentSystemPrompt(agent, fleet.config);
+      let reply = '';
+      try {
+        const providerResult = await callProviderForOpenAI({
+          ...body,
+          messages: [
+            { role: 'system', content: systemPrompt },
+            { role: 'user', content: agentMsg },
+          ],
+          metadata: { ...body.metadata, agentId: agent.id, agentName: agent.name, department: agent.department, requestType: 'fleet-chat' },
+        });
+        reply = providerResult.text || '';
+      } catch (err) {
+        reply = `I'm having trouble connecting right now. Please try again. (Error: ${err.message})`;
+      }
+      try {
+        if (providerResult.usage) {
+          recordTokenUsage({
+            tenantId: body.tenantId || 'owner-local',
+            agentId: agent.id,
+            agentName: agent.name,
+            department: agent.department,
+            sessionId: null,
+            provider: 'deepseek',
+            model: body.model || 'deepseek-v4-flash',
+            usage: providerResult.usage,
+            requestType: 'fleet-chat',
+          });
+        }
+      } catch {}
+      agent.lastActivity = new Date().toISOString();
+      agent.stats.messagesSent = (agent.stats.messagesSent || 0) + 1;
+      saveFleet(fleet);
+      return json(res, 200, { ok: true, agentId, agentName: agent.name, department: agent.department, reply, status: agent.status });
+    }
+
+    if (url.pathname === '/hq/fleet/agent/action') {
+      const { tenantId, agentId, action, payload: actionPayload } = body;
+      if (!tenantId || !agentId || !action) return json(res, 400, { ok: false, error: 'tenantId, agentId, and action required' });
+      const fleet = loadFleet(tenantId);
+      if (!fleet) return json(res, 404, { ok: false, error: 'No fleet deployed' });
+      const agent = (fleet.agents || []).find(a => a.id === agentId || a.templateId === agentId);
+      if (!agent) return json(res, 404, { ok: false, error: `Agent ${agentId} not found` });
+      const autonomyState = loadAutonomyState();
+      const job = { jobId: randomUUID(), kind: `fleet:${agent.id}:${action}`, surface: 'fleet', sessionId: null, payload: actionPayload || {}, metadata: { tenantId, agentId: agent.id, agentName: agent.name, department: agent.department, action, requestType: 'fleet-action' }, priority: 100, status: 'queued', attempts: 0, maxAttempts: 3, createdAt: new Date().toISOString(), updatedAt: new Date().toISOString(), workerId: null, claimedAt: null, claimExpiresAt: null, progress: [], garden: null };
+      autonomyState.jobs.push(job);
+      saveAutonomyState(autonomyState);
+      agent.lastActivity = new Date().toISOString();
+      saveFleet(fleet);
+      return json(res, 200, { ok: true, agentId, action, jobId: job.jobId, result: 'enqueued' });
+    }
+
+    if (url.pathname === '/hq/plugins/list') {
+      const { tenantId } = body;
+      return json(res, 200, { ok: true, plugins: listPlugins(tenantId || 'owner-local') });
+    }
+
+    if (url.pathname === '/hq/plugins/install') {
+      const { tenantId, pluginId, config: pluginConfig } = body;
+      if (!tenantId || !pluginId) return json(res, 400, { ok: false, error: 'tenantId and pluginId required' });
+      const result = installPlugin(tenantId, pluginId, pluginConfig);
+      if (!result.ok) return json(res, 400, result);
+      return json(res, 200, result);
+    }
+
+    if (url.pathname === '/hq/plugins/configure') {
+      const { tenantId, pluginId, config: pluginConfig } = body;
+      if (!tenantId || !pluginId) return json(res, 400, { ok: false, error: 'tenantId and pluginId required' });
+      const result = configurePlugin(tenantId, pluginId, pluginConfig);
+      if (!result.ok) return json(res, result.error.startsWith('No plugins') ? 404 : 400, result);
+      return json(res, 200, result);
+    }
+
+    if (url.pathname === '/hq/workflows/list') {
+      return json(res, 200, { ok: true, workflows: listWorkflowTemplates() });
+    }
+
+    if (url.pathname === '/hq/workflows/configure') {
+      const { tenantId, workflowId, config: workflowConfig } = body;
+      if (!tenantId || !workflowId) return json(res, 400, { ok: false, error: 'tenantId and workflowId required' });
+      const result = configureWorkflow(tenantId, workflowId, workflowConfig);
+      if (!result.ok) return json(res, 400, result);
+      return json(res, 200, result);
+    }
+
+    if (url.pathname === '/hq/workflows/start') {
+      const { tenantId, workflowId, payload } = body;
+      if (!tenantId || !workflowId) return json(res, 400, { ok: false, error: 'tenantId and workflowId required' });
+      const result = startWorkflow(tenantId, workflowId, payload);
+      if (!result.ok) return json(res, 400, result);
+      return json(res, 200, result);
+    }
+
+    if (url.pathname === '/hq/workflows/approve') {
+      const { tenantId, instanceId, approved } = body;
+      if (!tenantId || !instanceId) return json(res, 400, { ok: false, error: 'tenantId and instanceId required' });
+      const result = approveWorkflowStep(tenantId, instanceId, approved !== false);
+      if (!result.ok) return json(res, 400, result);
+      return json(res, 200, result);
+    }
+
+    if (url.pathname === '/hq/workflows/status') {
+      const { tenantId } = body;
+      if (!tenantId) return json(res, 400, { ok: false, error: 'tenantId required' });
+      return json(res, 200, { ok: true, ...getWorkflowStatus(tenantId) });
+    }
+
+    if (url.pathname === '/hq/subscription/tier') {
+      const { tier } = body;
+      return json(res, 200, { ok: true, tier: getSubscriptionTier(tier) });
+    }
+
     return json(res, 404, { ok: false, error: `No route for POST ${url.pathname}` });
   } catch (error) {
     return json(res, 500, {
@@ -3028,6 +4066,15 @@ export async function startRuntimeServer(options = {}) {
       });
     });
   });
+  server.on('upgrade', (req, socket) => {
+    try {
+      handleWebSocketUpgrade(req, socket);
+    } catch {
+      try {
+        socket.destroy();
+      } catch {}
+    }
+  });
 
   await new Promise((resolve, reject) => {
     server.once('error', reject);