@holoscript/holoscript-agent 2.0.0 → 2.0.2

package/dist/index.js

@@ -1,14 +1,19 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { homedir as homedir3 } from "os";
+import { homedir as homedir3, hostname as hostname2 } from "os";
 import { join as join4 } from "path";
+import { createHash as createHash4, createDecipheriv, randomBytes as randomBytes2 } from "crypto";
+import { Wallet as Wallet2 } from "ethers";
 import {
   createAnthropicProvider,
   createOpenAIProvider,
   createGeminiProvider,
   createMockProvider,
-  createLocalLLMProvider
+  createLocalLLMProvider,
+  createXAIProvider,
+  createOpenRouterProvider,
+  resolveSovereignProviderAsync
 } from "@holoscript/llm-provider";
 
 // src/identity.ts
@@ -16,6 +21,8 @@ var VALID_PROVIDERS = /* @__PURE__ */ new Set([
   "anthropic",
   "openai",
   "gemini",
+  "xai",
+  "openrouter",
   "mock",
   "bitnet",
   "local-llm"
@@ -36,7 +43,9 @@ function loadIdentity(env = process.env) {
   const budgetRaw = env.HOLOSCRIPT_AGENT_BUDGET_USD_DAY ?? "5";
   const budget = Number(budgetRaw);
   if (!Number.isFinite(budget) || budget < 0) {
-    throw new Error(`HOLOSCRIPT_AGENT_BUDGET_USD_DAY must be >= 0 (0 = unlimited), got ${budgetRaw}`);
+    throw new Error(
+      `HOLOSCRIPT_AGENT_BUDGET_USD_DAY must be >= 0 (0 = unlimited), got ${budgetRaw}`
+    );
   }
   return {
     handle,
@@ -74,16 +83,52 @@ function identityForLog(id) {
 // src/brain.ts
 import { readFile } from "fs/promises";
 async function loadBrain(brainPath, scopeTier = "warm") {
-  const systemPrompt = await readFile(brainPath, "utf8");
-  const { domain, capabilityTags } = extractIdentity(systemPrompt);
-  return { brainPath, systemPrompt, capabilityTags, domain, scopeTier };
+  const raw = await readFile(brainPath, "utf8");
+  const { domain, capabilityTags, requires, prefers, avoids } = extractIdentity(raw);
+  const systemPrompt = extractSystemPromptPreamble(raw);
+  return {
+    brainPath,
+    systemPrompt,
+    capabilityTags,
+    domain,
+    scopeTier,
+    requires,
+    prefers,
+    avoids,
+    reflect: extractReflect(raw)
+  };
+}
+function extractReflect(brain) {
+  const block = sliceNamedBlock(brain, "reflect");
+  if (block === void 0) return void 0;
+  const criteria = scalarField(block, "criteria") ?? scalarField(block, "scorer") ?? scalarField(block, "of") ?? "correctness, completeness, and valid HoloScript syntax";
+  const escRaw = scalarField(block, "escalate_on_fail") ?? scalarField(block, "escalateOnFail") ?? scalarField(block, "escalate");
+  return { criteria, escalateOnFail: (escRaw ?? "").split(",")[0].trim().toLowerCase() === "true" };
+}
+function extractSystemPromptPreamble(src) {
+  const lines = src.split("\n");
+  const BLOCK_START = /^(#version|#target|#mode|identity\s*\{|state\s*\{|computed\s*\{|traits\s*\[|capabilities\s*\{|directives\s*\{|behavior\s)/;
+  let cutLine = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (BLOCK_START.test(lines[i].trim())) {
+      cutLine = i;
+      break;
+    }
+  }
+  if (cutLine <= 0) return src;
+  return lines.slice(0, cutLine).join("\n").trimEnd();
 }
 function extractIdentity(brain) {
   const identityBlock = sliceNamedBlock(brain, "identity");
-  if (!identityBlock) return { domain: "unknown", capabilityTags: [] };
+  if (!identityBlock) {
+    return { domain: "unknown", capabilityTags: [], requires: [], prefers: [], avoids: [] };
+  }
   const domain = scalarField(identityBlock, "domain") ?? "unknown";
   const capabilityTags = listField(identityBlock, "capability_tags") ?? [];
-  return { domain, capabilityTags };
+  const requires = listField(identityBlock, "requires") ?? [];
+  const prefers = listField(identityBlock, "prefers") ?? [];
+  const avoids = listField(identityBlock, "avoids") ?? [];
+  return { domain, capabilityTags, requires, prefers, avoids };
 }
 function sliceNamedBlock(src, name) {
   const re = new RegExp(`\\b${name}\\s*:?\\s*\\{`, "g");
@@ -138,8 +183,10 @@ function listField(block, key) {
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
 import { dirname } from "path";
 var ANTHROPIC_PRICING_USD_PER_MTOK = {
-  "claude-opus-4-7": { input: 15, output: 75 },
-  "claude-opus-4-6": { input: 15, output: 75 },
+  "claude-opus-4-8": { input: 10, output: 50 },
+  // 3× cheaper than 4.7 on total cost; A-020 2026-06-08
+  "claude-opus-4-7": { input: 5, output: 25 },
+  "claude-opus-4-6": { input: 5, output: 25 },
   "claude-sonnet-4-6": { input: 3, output: 15 },
   "claude-haiku-4-5-20251001": { input: 1, output: 5 },
   "claude-haiku-4-5": { input: 1, output: 5 }
@@ -156,8 +203,30 @@ function defaultAnthropicPricer(model, usage) {
 function defaultLocalLlmPricer(_model, _usage) {
   return 0;
 }
+var XAI_PRICING_USD_PER_MTOK = {};
+function defaultXAIPricer(model, usage) {
+  const price = XAI_PRICING_USD_PER_MTOK[model];
+  if (!price) {
+    throw new Error(
+      `No xAI pricing configured for model "${model}" \u2014 populate XAI_PRICING_USD_PER_MTOK (see /research task_1778109552044_qed8 in docs/LLM_CAPABILITIES.md) or pass a custom pricer`
+    );
+  }
+  return (usage.promptTokens * price.input + usage.completionTokens * price.output) / 1e6;
+}
+var OPENROUTER_PRICING_USD_PER_MTOK = {};
+function defaultOpenRouterPricer(model, usage) {
+  const price = OPENROUTER_PRICING_USD_PER_MTOK[model];
+  if (!price) {
+    throw new Error(
+      `No OpenRouter pricing configured for model "${model}" \u2014 populate OPENROUTER_PRICING_USD_PER_MTOK or pass a custom pricer`
+    );
+  }
+  return (usage.promptTokens * price.input + usage.completionTokens * price.output) / 1e6;
+}
 function defaultPricerForProvider(provider) {
   if (provider === "local-llm" || provider === "mock") return defaultLocalLlmPricer;
+  if (provider === "xai") return defaultXAIPricer;
+  if (provider === "openrouter") return defaultOpenRouterPricer;
   return defaultAnthropicPricer;
 }
 var CostGuard = class {
@@ -219,6 +288,181 @@ function todayUtc() {
   return (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
 }
 
+// src/capability-router.ts
+import {
+  ANTHROPIC_CAPABILITIES,
+  OPENAI_CAPABILITIES,
+  GEMINI_CAPABILITIES,
+  XAI_CAPABILITIES,
+  OPENROUTER_CAPABILITIES,
+  LOCAL_LLM_CAPABILITIES,
+  BITNET_CAPABILITIES,
+  MOCK_CAPABILITIES
+} from "@holoscript/llm-provider";
+var NoEligibleProviderError = class extends Error {
+  constructor(requires, avoids, considered, excludedByAvoids) {
+    super(
+      `No provider satisfies brain requires=[${requires.join(", ")}] avoids=[${avoids.join(", ")}]. Considered: [${considered.join(", ")}]. Excluded by avoids: [${excludedByAvoids.join(", ")}].`
+    );
+    this.requires = requires;
+    this.avoids = avoids;
+    this.considered = considered;
+    this.excludedByAvoids = excludedByAvoids;
+    this.name = "NoEligibleProviderError";
+  }
+};
+function satisfies(capabilities, key) {
+  const value = capabilities[key];
+  if (typeof value === "boolean") return value;
+  if (typeof value === "number") return value > 0;
+  return false;
+}
+function countMatches(capabilities, keys) {
+  let count = 0;
+  for (const key of keys) {
+    if (satisfies(capabilities, key)) count++;
+  }
+  return count;
+}
+function unsatisfiedKeys(capabilities, keys) {
+  return keys.filter((key) => !satisfies(capabilities, key));
+}
+function pickProvider(opts) {
+  const { brain, envOverride, candidates } = opts;
+  const tieBreaker = opts.tieBreakerOrder ?? candidates.map((c) => c.name);
+  if (candidates.length === 0) {
+    throw new Error("pickProvider: no candidates supplied");
+  }
+  const excludedByAvoids = [];
+  const notAvoided = [];
+  for (const candidate of candidates) {
+    const matchesAvoid = brain.avoids.some((a) => satisfies(candidate.capabilities, a));
+    if (matchesAvoid) {
+      excludedByAvoids.push(candidate.name);
+    } else {
+      notAvoided.push(candidate);
+    }
+  }
+  if (brain.requires.length === 0) {
+    if (envOverride !== void 0) {
+      const envCandidate = candidates.find((c) => c.name === envOverride);
+      const matchedPrefers = envCandidate ? brain.prefers.filter((p) => satisfies(envCandidate.capabilities, p)) : [];
+      return {
+        picked: envOverride,
+        reason: "env-override-no-requirements",
+        unsatisfiedRequires: [],
+        matchedPrefers,
+        excludedByAvoids,
+        alternatives: candidates.filter((c) => c.name !== envOverride).map((c) => c.name)
+      };
+    }
+    const ordered = orderCandidates(notAvoided, tieBreaker);
+    if (ordered.length === 0) {
+      return {
+        picked: candidates[0].name,
+        reason: "open-routing-default",
+        unsatisfiedRequires: [],
+        matchedPrefers: brain.prefers.filter((p) => satisfies(candidates[0].capabilities, p)),
+        excludedByAvoids,
+        alternatives: candidates.slice(1).map((c) => c.name)
+      };
+    }
+    return {
+      picked: ordered[0].name,
+      reason: "open-routing-default",
+      unsatisfiedRequires: [],
+      matchedPrefers: brain.prefers.filter((p) => satisfies(ordered[0].capabilities, p)),
+      excludedByAvoids,
+      alternatives: ordered.slice(1).map((c) => c.name)
+    };
+  }
+  const eligible = notAvoided.filter(
+    (c) => unsatisfiedKeys(c.capabilities, brain.requires).length === 0
+  );
+  if (eligible.length === 0) {
+    if (envOverride !== void 0) {
+      const envCandidate = candidates.find((c) => c.name === envOverride);
+      const unsatisfied = envCandidate ? unsatisfiedKeys(envCandidate.capabilities, brain.requires) : brain.requires.slice();
+      const matchedPrefers = envCandidate ? brain.prefers.filter((p) => satisfies(envCandidate.capabilities, p)) : [];
+      return {
+        picked: envOverride,
+        reason: "env-override-mismatch",
+        unsatisfiedRequires: unsatisfied,
+        matchedPrefers,
+        excludedByAvoids,
+        alternatives: []
+      };
+    }
+    throw new NoEligibleProviderError(
+      brain.requires,
+      brain.avoids,
+      candidates.map((c) => c.name),
+      excludedByAvoids
+    );
+  }
+  const ranked = [...eligible].sort((a, b) => {
+    const aMatches = countMatches(a.capabilities, brain.prefers);
+    const bMatches = countMatches(b.capabilities, brain.prefers);
+    if (aMatches !== bMatches) return bMatches - aMatches;
+    const aIdx = tieBreaker.indexOf(a.name);
+    const bIdx = tieBreaker.indexOf(b.name);
+    const aRank = aIdx === -1 ? Number.MAX_SAFE_INTEGER : aIdx;
+    const bRank = bIdx === -1 ? Number.MAX_SAFE_INTEGER : bIdx;
+    return aRank - bRank;
+  });
+  if (envOverride !== void 0) {
+    const envEligible = ranked.find((c) => c.name === envOverride);
+    if (envEligible) {
+      return {
+        picked: envOverride,
+        reason: "env-override-satisfies",
+        unsatisfiedRequires: [],
+        matchedPrefers: brain.prefers.filter((p) => satisfies(envEligible.capabilities, p)),
+        excludedByAvoids,
+        alternatives: ranked.filter((c) => c.name !== envOverride).map((c) => c.name)
+      };
+    }
+    const envCandidate = candidates.find((c) => c.name === envOverride);
+    const unsatisfied = envCandidate ? unsatisfiedKeys(envCandidate.capabilities, brain.requires) : brain.requires.slice();
+    return {
+      picked: envOverride,
+      reason: "env-override-mismatch",
+      unsatisfiedRequires: unsatisfied,
+      matchedPrefers: envCandidate ? brain.prefers.filter((p) => satisfies(envCandidate.capabilities, p)) : [],
+      excludedByAvoids,
+      alternatives: ranked.map((c) => c.name)
+    };
+  }
+  const top = ranked[0];
+  return {
+    picked: top.name,
+    reason: "capability-best-fit",
+    unsatisfiedRequires: [],
+    matchedPrefers: brain.prefers.filter((p) => satisfies(top.capabilities, p)),
+    excludedByAvoids,
+    alternatives: ranked.slice(1).map((c) => c.name)
+  };
+}
+var BUILT_IN_CANDIDATES = [
+  { name: "anthropic", capabilities: ANTHROPIC_CAPABILITIES },
+  { name: "openai", capabilities: OPENAI_CAPABILITIES },
+  { name: "gemini", capabilities: GEMINI_CAPABILITIES },
+  { name: "xai", capabilities: XAI_CAPABILITIES },
+  { name: "openrouter", capabilities: OPENROUTER_CAPABILITIES },
+  { name: "local-llm", capabilities: LOCAL_LLM_CAPABILITIES },
+  { name: "bitnet", capabilities: BITNET_CAPABILITIES },
+  { name: "mock", capabilities: MOCK_CAPABILITIES }
+];
+function orderCandidates(candidates, tieBreaker) {
+  return [...candidates].sort((a, b) => {
+    const aIdx = tieBreaker.indexOf(a.name);
+    const bIdx = tieBreaker.indexOf(b.name);
+    const aRank = aIdx === -1 ? Number.MAX_SAFE_INTEGER : aIdx;
+    const bRank = bIdx === -1 ? Number.MAX_SAFE_INTEGER : bIdx;
+    return aRank - bRank;
+  });
+}
+
 // src/holomesh-client.ts
 var HolomeshClient = class {
   constructor(opts) {
@@ -226,9 +470,14 @@ var HolomeshClient = class {
     this.bearer = opts.bearer;
     this.teamId = opts.teamId;
     this.fetchImpl = opts.fetchImpl ?? fetch;
+    this.signer = opts.signer;
+  }
+  /** Wrap body in a signed envelope when a signer is available (strict-mode endpoints). */
+  async signBody(body) {
+    return this.signer ? await this.signer(body) : body;
   }
   async heartbeat(payload) {
-    await this.req("POST", `/team/${this.teamId}/presence`, payload);
+    await this.req("POST", `/team/${this.teamId}/presence`, await this.signBody(payload));
   }
   async getOpenTasks() {
     const data = await this.req(
@@ -238,28 +487,33 @@ var HolomeshClient = class {
     return data.tasks ?? data.open ?? [];
   }
   async claim(taskId) {
-    return this.req("PATCH", `/team/${this.teamId}/board/${taskId}`, { action: "claim" });
+    return this.req("PATCH", `/team/${this.teamId}/board/${taskId}`, await this.signBody({ action: "claim" }));
   }
   async joinTeam() {
     return this.req(
       "POST",
       `/team/${this.teamId}/join`,
-      {}
+      await this.signBody({})
     );
   }
   async sendMessageOnTask(taskId, body) {
-    await this.req("POST", `/team/${this.teamId}/message`, {
+    await this.req("POST", `/team/${this.teamId}/message`, await this.signBody({
       to: "team",
       subject: `task:${taskId}`,
       content: body
-    });
+    }));
   }
   async markDone(taskId, summary, commitHash) {
-    await this.req("PATCH", `/team/${this.teamId}/board/${taskId}`, {
+    await this.req("PATCH", `/team/${this.teamId}/board/${taskId}`, await this.signBody({
       action: "done",
       summary,
-      commitHash
-    });
+      // verification_evidence required by server before task can be closed.
+      verification_evidence: summary,
+      // Exclude commitHash when undefined — JSON.stringify drops undefined but
+      // canonicalizeSigning preserves it as the literal string "undefined",
+      // causing a signature-mismatch vs what the server sees after JSON.parse.
+      ...commitHash !== void 0 ? { commitHash } : {}
+    }));
   }
   // POST CAEL audit records for this agent. Server validator at
   // packages/mcp-server/src/holomesh/routes/core-routes.ts:472-533 requires
@@ -282,6 +536,40 @@ var HolomeshClient = class {
       wallet: raw.wallet
     };
   }
+  // ── Team Message Surface (E4 delegated-authority protocol) ───────────────────
+  /** Read recent team messages. */
+  async getTeamMessages(limit = 20) {
+    const data = await this.req(
+      "GET",
+      `/team/${this.teamId}/messages?limit=${limit}`
+    );
+    return data.messages ?? [];
+  }
+  /** Post a message to the team feed. */
+  async sendTeamMessage(content, messageType = "text") {
+    await this.req("POST", `/team/${this.teamId}/message`, await this.signBody({ content, type: messageType }));
+  }
+  // ── Owner-op API wrappers (E4) ─────────────────────────────────────────────
+  /** Switch team mode. Requires owner or founder role. */
+  async setTeamMode(mode, reason) {
+    return this.req("POST", `/team/${this.teamId}/mode`, await this.signBody({ mode, reason }));
+  }
+  /** Update room preferences. Requires config:write permission. */
+  async patchRoomPrefs(prefs) {
+    return this.req("PATCH", `/team/${this.teamId}/room`, await this.signBody(prefs));
+  }
+  /** Update a board task. */
+  async updateTask(taskId, updates) {
+    return this.req("PATCH", `/team/${this.teamId}/board/${taskId}`, await this.signBody({ action: "update", ...updates }));
+  }
+  /** Delete a board task. */
+  async deleteTask(taskId) {
+    return this.req("PATCH", `/team/${this.teamId}/board/${taskId}`, await this.signBody({ action: "delete" }));
+  }
+  /** Delegate a board task to another agent. */
+  async delegateTask(taskId, toAgentId) {
+    return this.req("PATCH", `/team/${this.teamId}/board/${taskId}`, await this.signBody({ action: "delegate", toAgentId }));
+  }
   async req(method, path, body) {
     const url = `${this.apiBase}${path}`;
     const res = await this.fetchImpl(url, {
@@ -349,7 +637,18 @@ function brainClassOf(brain) {
   return "unknown";
 }
 function buildCaelRecord(input) {
-  const { identity, brain, task, messages, finalText, usage, costUsd, spentUsd, prevChain, runtimeVersion } = input;
+  const {
+    identity,
+    brain,
+    task,
+    messages,
+    finalText,
+    usage,
+    costUsd,
+    spentUsd,
+    prevChain,
+    runtimeVersion
+  } = input;
   const l0 = sha(brain.systemPrompt);
   const l1 = sha(`${task.id}|${task.title}|${task.description ?? ""}`);
   const l2 = sha(JSON.stringify(messages));
@@ -365,15 +664,16 @@ function buildCaelRecord(input) {
     prev_hash: prevChain,
     fnv1a_chain,
     version_vector_fingerprint: `agent@${runtimeVersion}|brain@${brainClassOf(brain)}|provider@${identity.llmProvider}|model@${identity.llmModel}`,
-    brain_class: brainClassOf(brain)
+    brain_class: brainClassOf(brain),
+    trust_epoch: "post-w107"
   };
 }
 
 // src/tools.ts
 import { readFile as readFile2, writeFile, readdir, mkdir, stat } from "fs/promises";
-import { resolve, dirname as dirname2 } from "path";
+import { resolve, dirname as dirname2, delimiter, isAbsolute, sep } from "path";
 import { spawn } from "child_process";
-var ALLOWED_READ_ROOTS = [
+var FLEET_READ_ROOTS = [
   "/root/msc-paper-22",
   // Paper 22 mechanization inputs (scp'd by deploy)
   "/root/holoscript-mesh",
@@ -381,15 +681,24 @@ var ALLOWED_READ_ROOTS = [
   "/root/agent-output"
   // Read back what we wrote
 ];
-var ALLOWED_WRITE_ROOTS = [
+var FLEET_WRITE_ROOTS = [
   "/root/agent-output"
   // Single write sink — keeps deliverables in one place
 ];
-var BASH_WHITELIST = [
-  "lake build",
-  "lake env",
-  "lake clean",
-  "lean ",
+function parseRootsEnv(raw, fallback) {
+  if (!raw) return fallback;
+  const roots = raw.split(delimiter).map((r) => r.trim()).filter((r) => r.length > 0 && isAbsolute(r));
+  return roots.length > 0 ? roots : fallback;
+}
+var ALLOWED_READ_ROOTS = parseRootsEnv(
+  process.env.HOLOSCRIPT_AGENT_READ_ROOTS,
+  FLEET_READ_ROOTS
+);
+var ALLOWED_WRITE_ROOTS = parseRootsEnv(
+  process.env.HOLOSCRIPT_AGENT_WRITE_ROOTS,
+  FLEET_WRITE_ROOTS
+);
+var BASH_READ_ONLY_PREFIXES = [
   "ls ",
   "ls\n",
   "ls$",
@@ -404,16 +713,36 @@ var BASH_WHITELIST = [
   "git log",
   "git diff",
   "git show",
+  "pwd",
+  "echo ",
+  "lake env"
+];
+var BASH_PRODUCTIVE_PREFIXES = [
+  "lake build",
+  "lake clean",
+  "lean ",
   "pnpm --filter",
   "pnpm vitest",
   "vitest run",
-  "pwd",
-  "echo "
+  // Robotics / edge-node (Jetson) productive commands — without these, every
+  // ros2/colcon/tegrastats task fails the W.107 artifact gate and is abandoned
+  // as no-artifact. (jetson-orin-01 lane.)
+  "ros2 launch",
+  "ros2 topic pub",
+  "ros2 service call",
+  "colcon build",
+  "tegrastats"
 ];
+var BASH_WHITELIST = [...BASH_READ_ONLY_PREFIXES, ...BASH_PRODUCTIVE_PREFIXES];
+function isProductiveBashCommand(cmd) {
+  const trimmed = String(cmd ?? "").trim();
+  if (!trimmed) return false;
+  return BASH_PRODUCTIVE_PREFIXES.some((prefix) => trimmed.startsWith(prefix.trim()));
+}
 var MESH_TOOLS = [
   {
     name: "read_file",
-    description: "Read a file from the agent sandbox. Allowed roots: /root/msc-paper-22, /root/holoscript-mesh, /root/agent-output. Returns the file content as text. Use this to inspect inputs scp'd to the instance (e.g. MSC/Invariants.lean).",
+    description: `Read a file from the agent sandbox. Allowed roots: ${ALLOWED_READ_ROOTS.join(", ")}. Returns the file content as text. Use this to inspect task inputs and the read-only repo view.`,
     input_schema: {
       type: "object",
       properties: {
@@ -435,11 +764,11 @@ var MESH_TOOLS = [
   },
   {
     name: "write_file",
-    description: "Write a file to /root/agent-output/. This is the deliverable sink \u2014 anything you want to emit as task output (a Lean proof, a markdown report, a JSON dataset) goes here. Creates parent directories. Will refuse paths outside the write root.",
+    description: `Write a file to the deliverable sink (write roots: ${ALLOWED_WRITE_ROOTS.join(", ")}). Anything you want to emit as task output (a Lean proof, a markdown report, a JSON dataset, a .holo scene) goes here. Creates parent directories. Will refuse paths outside the write root(s).`,
     input_schema: {
       type: "object",
       properties: {
-        path: { type: "string", description: "Absolute path under /root/agent-output/" },
+        path: { type: "string", description: `Absolute path under a write root: ${ALLOWED_WRITE_ROOTS.join(", ")}` },
         content: { type: "string", description: "File content to write (UTF-8)" }
       },
       required: ["path", "content"]
@@ -447,7 +776,7 @@ var MESH_TOOLS = [
   },
   {
     name: "bash",
-    description: "Run a shell command. Whitelisted prefixes only: lake build, lean, ls, cat, grep, find, wc, head, tail, git status/log/diff/show, pnpm --filter, vitest run, pwd, echo. Hard 60s wall timeout, 1MB stdout cap. Use for lake build / lean kernel-checks, git inspection, repo greps. Refuses rm, curl, ssh, sudo, eval.",
+    description: "Run a shell command. Whitelisted prefixes only: lake build, lean, ls, cat, grep, find, wc, head, tail, git status/log/diff/show, pnpm --filter, vitest run, pwd, echo, ros2 launch/topic/service, colcon build, tegrastats. Hard 60s wall timeout, 1MB stdout cap. Use for builds, tests, hardware probes. Refuses rm, curl, ssh, sudo, eval.",
     input_schema: {
       type: "object",
       properties: {
@@ -456,22 +785,52 @@ var MESH_TOOLS = [
       },
       required: ["cmd"]
     }
+  },
+  {
+    name: "emit_hardware_receipt",
+    description: "Emit a portable hardware receipt (PortableHardwareReceiptMetadata v1) capturing device identity, runtime, and measured performance. Writes a JSON receipt to the agent output dir. Use after running tegrastats or colcon build to record hardware evidence for the CAEL audit chain. Accepts either pre-parsed measurements or raw tegrastats output (the tool parses it automatically).",
+    input_schema: {
+      type: "object",
+      properties: {
+        device_kind: {
+          type: "string",
+          description: 'Device identifier, e.g. "jetson-orin-nano-super", "raspberry-pi-5"'
+        },
+        accelerator: {
+          description: 'Accelerator string, e.g. "NVIDIA CUDA 8.7", or null for CPU-only'
+        },
+        runtime_name: { type: "string", description: 'Inference runtime, e.g. "Ollama", "llama.cpp"' },
+        runtime_version: { type: "string", description: 'Runtime version, e.g. "0.30.8"' },
+        host_os: { type: "string", description: 'OS + firmware, e.g. "JetPack 6.2.1 / Ubuntu 22.04"' },
+        composition_id: { type: "string", description: 'Brain composition reference, e.g. "jetson-orin-brain"' },
+        measurements: {
+          type: "array",
+          description: "Pre-parsed measurements. Each item: {metric: string, value: number, unit: string}",
+          items: { type: "object" }
+        },
+        tegrastats_output: {
+          type: "string",
+          description: "Raw tegrastats output line(s) \u2014 tool auto-parses GPU%, RAM, temp, power"
+        }
+      },
+      required: ["device_kind", "runtime_name", "runtime_version", "host_os"]
+    }
   }
 ];
 function isUnderRoot(absPath, root) {
   const resolved = resolve(absPath);
   const rootResolved = resolve(root);
-  return resolved === rootResolved || resolved.startsWith(rootResolved + "/");
+  return resolved === rootResolved || resolved.startsWith(rootResolved + sep);
 }
 function checkReadAllowed(path) {
-  if (!path.startsWith("/")) return `path must be absolute, got "${path}"`;
+  if (!isAbsolute(path)) return `path must be absolute, got "${path}"`;
   for (const root of ALLOWED_READ_ROOTS) {
     if (isUnderRoot(path, root)) return null;
   }
   return `read denied \u2014 path "${path}" not under allowed roots: ${ALLOWED_READ_ROOTS.join(", ")}`;
 }
 function checkWriteAllowed(path) {
-  if (!path.startsWith("/")) return `path must be absolute, got "${path}"`;
+  if (!isAbsolute(path)) return `path must be absolute, got "${path}"`;
   for (const root of ALLOWED_WRITE_ROOTS) {
     if (isUnderRoot(path, root)) return null;
   }
@@ -526,12 +885,113 @@ async function runTool(use) {
       return result.code === 0 ? okResult(use.id, result.stdout) : errResult(use.id, `exit=${result.code}
 ${result.stderr || result.stdout}`);
     }
+    if (use.name === "emit_hardware_receipt") {
+      const deviceKind = String(use.input.device_kind ?? "unknown-device");
+      const accelerator = use.input.accelerator === null || use.input.accelerator === "null" ? null : String(use.input.accelerator ?? "").trim() || null;
+      const runtimeName = String(use.input.runtime_name ?? "Ollama");
+      const runtimeVersion = String(use.input.runtime_version ?? "unknown");
+      const hostOs = String(use.input.host_os ?? "unknown");
+      const compositionId = String(use.input.composition_id ?? "unknown");
+      let measurements = [];
+      if (Array.isArray(use.input.measurements)) {
+        for (const m of use.input.measurements) {
+          const metric = String(m.metric ?? "");
+          const value = Number(m.value ?? 0);
+          const unit = String(m.unit ?? "");
+          if (metric && Number.isFinite(value)) {
+            measurements.push({ metric, value, unit, method: "measured" });
+          }
+        }
+      }
+      if (typeof use.input.tegrastats_output === "string" && use.input.tegrastats_output.length > 0) {
+        measurements = [...measurements, ...parseTegrastats(use.input.tegrastats_output)];
+      }
+      if (measurements.length === 0) {
+        measurements.push({ metric: "agent-tick", value: 1, unit: "count", method: "presence" });
+      }
+      const capturedAt = (/* @__PURE__ */ new Date()).toISOString();
+      const receipt = {
+        schemaVersion: "holoscript.hardware-receipt-metadata.v1",
+        target: {
+          id: `${deviceKind}-${Date.now()}`,
+          kind: deviceKind,
+          architecture: /jetson|orin|nano|agx|xavier/i.test(deviceKind) ? "arm64" : "unknown",
+          artifactKind: "measurement-trace"
+        },
+        device: {
+          vendor: /jetson|orin|nvidia/i.test(deviceKind) ? "nvidia" : "unknown",
+          model: deviceKind,
+          accelerator
+        },
+        runtime: { name: runtimeName, version: runtimeVersion, hostOS: hostOs },
+        compilerVersion: "holoscript-agent-1.0.0",
+        constraints: [],
+        measuredResults: measurements,
+        replayInputs: [
+          { kind: "composition-ref", uri: `compositions/${compositionId}`, sha256: "unknown" }
+        ],
+        provenance: {
+          capturedAt,
+          sourceCompositionHash: compositionId
+        },
+        owner: {
+          agent: process.env.HOLOSCRIPT_AGENT_HANDLE ?? "unknown",
+          ...process.env.HOLOMESH_TEAM_ID ? { team: process.env.HOLOMESH_TEAM_ID } : {}
+        }
+      };
+      const ts = capturedAt.replace(/[:.]/g, "-");
+      const outPath = resolve(ALLOWED_WRITE_ROOTS[0], `hardware-receipt-${ts}.json`);
+      const denied = checkWriteAllowed(outPath);
+      if (denied) return errResult(use.id, `Cannot write receipt: ${denied}`);
+      await mkdir(dirname2(outPath), { recursive: true });
+      await writeFile(outPath, JSON.stringify(receipt, null, 2), "utf8");
+      return okResult(
+        use.id,
+        `Hardware receipt written to ${outPath} \u2014 ${measurements.length} measurements, accelerator=${accelerator ?? "none"}`
+      );
+    }
     return errResult(use.id, `unknown tool: ${use.name}`);
   } catch (err) {
     return errResult(use.id, err instanceof Error ? err.message : String(err));
   }
 }
+function parseTegrastats(raw) {
+  const results = [];
+  const m = (pattern, metric, unit, transform) => {
+    const match = raw.match(pattern);
+    if (match?.[1]) {
+      const value = transform ? transform(match[1]) : Number(match[1]);
+      if (Number.isFinite(value)) results.push({ metric, value, unit, method: "tegrastats" });
+    }
+  };
+  const ram = raw.match(/RAM\s+(\d+)\/(\d+)MB/);
+  if (ram) {
+    const used = Number(ram[1]);
+    const total = Number(ram[2]);
+    results.push({ metric: "ram-used", value: used, unit: "MB", method: "tegrastats" });
+    results.push({ metric: "ram-total", value: total, unit: "MB", method: "tegrastats" });
+    if (total > 0)
+      results.push({ metric: "ram-pct", value: Math.round(used / total * 100), unit: "%", method: "tegrastats" });
+  }
+  m(/GR3D_FREQ\s+(\d+)%/, "gpu-util", "%");
+  m(/EMC_FREQ\s+(\d+)%/, "emc-freq-pct", "%");
+  m(/tj@([\d.]+)C/, "temp-tj", "C", parseFloat);
+  m(/cpu@([\d.]+)C/, "temp-cpu", "C", parseFloat);
+  m(/gpu@([\d.]+)C/, "temp-gpu", "C", parseFloat);
+  m(/VDD_SOC\s+(\d+)mW/, "power-soc", "mW");
+  m(/VDD_CPU_CV\s+(\d+)mW/, "power-cpu-cv", "mW");
+  m(/VDD_IN\s+(\d+)mW/, "power-total", "mW");
+  m(/CPU\s+\[(\d+)%/, "cpu-util-core0", "%");
+  return results;
+}
 function runBash(cmd, cwd) {
+  if (process.env.VITEST === "true" || process.env.NODE_ENV === "test") {
+    return Promise.resolve({
+      code: 0,
+      stdout: `[mock-bash under vitest] cmd="${cmd}" cwd="${cwd}"`,
+      stderr: ""
+    });
+  }
   return new Promise((resolveProm) => {
     const child = spawn("bash", ["-c", cmd], { cwd, env: process.env });
     let stdout = "";
@@ -600,6 +1060,35 @@ var AgentRunner = class {
     const { identity, brain, mesh, costGuard, provider, logger } = this.opts;
     const log = logger ?? (() => void 0);
     await this.heartbeatWithAutoRejoin();
+    if (this.opts.messageHandler) {
+      try {
+        const receipts = await this.opts.messageHandler.processMessages();
+        if (receipts.length > 0) {
+          log({
+            ev: "messages-processed",
+            count: receipts.length,
+            statuses: receipts.map((r) => r.status)
+          });
+          if (brain.capabilityTags.length === 0 || brain.capabilityTags.every((t) => t.startsWith("delegated"))) {
+            return {
+              action: "messages-processed",
+              spentUsd: costGuard.getState().spentUsd,
+              remainingUsd: costGuard.getRemainingUsd(),
+              receipts: receipts.map((r) => ({
+                status: r.status,
+                action: r.action,
+                reason: r.reason
+              }))
+            };
+          }
+        }
+      } catch (err) {
+        log({
+          ev: "message-handler-error",
+          message: err instanceof Error ? err.message : String(err)
+        });
+      }
+    }
     if (costGuard.isOverBudget()) {
       const state = costGuard.getState();
       log({ ev: "over-budget", spentUsd: state.spentUsd, budget: identity.budgetUsdPerDay });
@@ -633,6 +1122,8 @@ var AgentRunner = class {
     const MAX_TOOL_ITERS = 30;
     let lastResponse;
     const toolsCalled = /* @__PURE__ */ new Set();
+    let productiveCallCount = 0;
+    let lastCommitHash;
     while (true) {
       iters++;
       if (iters > MAX_TOOL_ITERS) {
@@ -640,12 +1131,16 @@ var AgentRunner = class {
         finalText = finalText || `[tool-loop hit ${MAX_TOOL_ITERS}-iter cap before final text]`;
         break;
       }
+      const activeTools = brain.requires.includes("local-llm") ? MESH_TOOLS.filter((t) => t.name === "write_file") : MESH_TOOLS;
       const resp = await provider.complete(
         {
           messages,
-          maxTokens: 4096,
+          // 8192 for local thinking models (qwen3:4b uses ~3800 tokens on thinking
+          // before the tool-call JSON; 4096 cuts off mid-generation). Frontier
+          // models ignore this ceiling and stop naturally earlier.
+          maxTokens: 8192,
           temperature: 0.4,
-          tools: MESH_TOOLS
+          tools: activeTools
         },
         identity.llmModel
       );
@@ -656,13 +1151,39 @@ var AgentRunner = class {
         totalTokens: aggUsage.totalTokens + resp.usage.totalTokens
       };
       if (resp.finishReason === "tool_use" && resp.toolUses && resp.toolUses.length > 0) {
-        log({ ev: "tool-call", taskId: target.id, iter: iters, tools: resp.toolUses.map((t) => t.name) });
-        for (const u of resp.toolUses) toolsCalled.add(u.name);
+        log({
+          ev: "tool-call",
+          taskId: target.id,
+          iter: iters,
+          tools: resp.toolUses.map((t) => t.name)
+        });
+        for (const u of resp.toolUses) {
+          toolsCalled.add(u.name);
+          if (u.name === "write_file") {
+            const content = String(u.input?.content ?? "");
+            if (content.length > 0) productiveCallCount++;
+          } else if (u.name === "bash") {
+            const cmd = String(u.input?.cmd ?? "");
+            if (isProductiveBashCommand(cmd)) productiveCallCount++;
+          } else if (u.name === "emit_hardware_receipt") {
+            productiveCallCount++;
+          }
+        }
         messages.push({
           role: "assistant",
           content: resp.assistantBlocks ?? []
         });
         const toolResults = await Promise.all(resp.toolUses.map((u) => runTool(u)));
+        for (let ti = 0; ti < resp.toolUses.length; ti++) {
+          const tu = resp.toolUses[ti];
+          if (tu.name === "bash") {
+            const tr = toolResults[ti];
+            if (tr && !tr.is_error) {
+              const shaMatch = tr.content.match(/\b([0-9a-f]{7,40})\b/);
+              if (shaMatch) lastCommitHash = shaMatch[1];
+            }
+          }
+        }
         messages.push({
           role: "user",
           content: toolResults
@@ -673,24 +1194,75 @@ var AgentRunner = class {
       break;
     }
     const durationMs = Date.now() - start;
-    const SIDE_EFFECTING_TOOLS = /* @__PURE__ */ new Set(["write_file", "bash"]);
-    const sideEffectingCalled = [...toolsCalled].some((t) => SIDE_EFFECTING_TOOLS.has(t));
-    if (!sideEffectingCalled) {
+    if (productiveCallCount === 0) {
       log({
         ev: "no-artifact",
         taskId: target.id,
         tool_iters: iters,
         toolsCalled: [...toolsCalled],
-        message: "task execution called no side-effecting tool (write_file/bash) \u2014 refusing to mark executed. Likely a pure-text or read-only-inspection response. Task remains open for a grounded attempt."
+        productiveCallCount,
+        message: "task execution did not produce a real artifact \u2014 refusing to mark executed. Required: write_file with non-empty content OR bash with a productive prefix (lake build / pnpm --filter / vitest run / lean / pnpm vitest). Pure-text, read-only inspection, and trivial-bash-bypass (`echo`, `cat`, etc.) do not satisfy the gate."
       });
       return {
         action: "no-artifact",
         taskId: target.id,
         spentUsd: costGuard.getState().spentUsd,
         remainingUsd: costGuard.getRemainingUsd(),
-        message: `no side-effecting tool called (toolsCalled=[${[...toolsCalled].join(",")}], iters=${iters})`
+        message: `no productive tool call observed (toolsCalled=[${[...toolsCalled].join(",")}], productiveCallCount=${productiveCallCount}, iters=${iters})`
       };
     }
+    let reflectVerdict;
+    if (brain.reflect) {
+      try {
+        const reflectResp = await provider.complete(
+          {
+            messages: [
+              {
+                role: "system",
+                content: "You are a strict reviewer. Evaluate the work against the criteria; do not rewrite it."
+              },
+              {
+                role: "user",
+                content: `Reflect on the artifact produced for this task. Evaluate it for: ${brain.reflect.criteria}.
+
+--- artifact / final response ---
+${finalText.slice(0, 4e3)}
+--- end ---
+
+Give a one-line reason, then end with exactly "VERDICT: PASS" or "VERDICT: FAIL".`
+              }
+            ],
+            maxTokens: 512,
+            temperature: 0.1
+          },
+          identity.llmModel
+        );
+        aggUsage = {
+          promptTokens: aggUsage.promptTokens + reflectResp.usage.promptTokens,
+          completionTokens: aggUsage.completionTokens + reflectResp.usage.completionTokens,
+          totalTokens: aggUsage.totalTokens + reflectResp.usage.totalTokens
+        };
+        const verdictMatch = /VERDICT:\s*(PASS|FAIL)/i.exec(reflectResp.content);
+        const pass = verdictMatch ? verdictMatch[1].toUpperCase() === "PASS" : true;
+        reflectVerdict = {
+          pass,
+          reason: reflectResp.content.replace(/VERDICT:\s*(PASS|FAIL)/i, "").trim().slice(0, 300)
+        };
+        log({
+          ev: "reflect",
+          taskId: target.id,
+          pass,
+          escalateOnFail: brain.reflect.escalateOnFail,
+          reason: reflectVerdict.reason.slice(0, 120)
+        });
+      } catch (err) {
+        log({
+          ev: "reflect-error",
+          taskId: target.id,
+          message: err instanceof Error ? err.message : String(err)
+        });
+      }
+    }
     const cost = costGuard.recordUsage(identity.llmModel, aggUsage);
     log({
       ev: "executed",
@@ -700,7 +1272,11 @@ var AgentRunner = class {
       tokens: aggUsage.totalTokens,
       tool_iters: iters
     });
-    const response = { ...lastResponse ?? { content: finalText, usage: aggUsage }, content: finalText, usage: aggUsage };
+    const response = {
+      ...lastResponse ?? { content: finalText, usage: aggUsage },
+      content: finalText,
+      usage: aggUsage
+    };
     const execResult = {
       taskId: target.id,
       responseText: response.content,
@@ -734,10 +1310,32 @@ var AgentRunner = class {
       });
       const posted = await mesh.postAuditRecords(identity.handle, [caelRecord]);
       this.prevCaelChain = caelRecord.fnv1a_chain;
-      log({ ev: "cael-posted", taskId: target.id, appended: posted.appended, rejected: posted.rejected });
+      log({
+        ev: "cael-posted",
+        taskId: target.id,
+        appended: posted.appended,
+        rejected: posted.rejected
+      });
     } catch (err) {
       log({ ev: "cael-post-error", message: err instanceof Error ? err.message : String(err) });
     }
+    if (reflectVerdict && !reflectVerdict.pass && brain.reflect?.escalateOnFail) {
+      try {
+        await mesh.sendMessageOnTask(
+          target.id,
+          `[${identity.handle}] reflect gate FAILED \u2014 escalating to the fleet instead of marking done. Reason: ${reflectVerdict.reason}`
+        );
+      } catch {
+      }
+      log({ ev: "reflect-escalate", taskId: target.id, reason: reflectVerdict.reason.slice(0, 120) });
+      return {
+        action: "reflect-escalate",
+        taskId: target.id,
+        spentUsd: costGuard.getState().spentUsd,
+        remainingUsd: costGuard.getRemainingUsd(),
+        message: `reflect self-evaluation failed; escalated to fleet (reason: ${reflectVerdict.reason.slice(0, 120)})`
+      };
+    }
     if (this.opts.onTaskExecuted) {
       await this.opts.onTaskExecuted(execResult, target);
     } else {
@@ -748,6 +1346,16 @@ var AgentRunner = class {
 ${response.content}`
       );
     }
+    try {
+      await mesh.markDone(target.id, finalText.slice(0, 500), lastCommitHash);
+      log({ ev: "mark-done", taskId: target.id, commitHash: lastCommitHash });
+    } catch (err) {
+      log({
+        ev: "mark-done-error",
+        taskId: target.id,
+        message: err instanceof Error ? err.message : String(err)
+      });
+    }
     return {
       action: "executed",
       taskId: target.id,
@@ -840,7 +1448,7 @@ function buildTaskPrompt(task) {
     "Description:",
     task.description ?? "(no description)",
     "",
-    "Produce the deliverable described in the task. Apply your brain composition rules \u2014 anti-patterns, decision loop, and scope tier all bind. Return the response as plain text suitable for posting to /room as a message on this task."
+    "Produce the deliverable: call write_file (or bash with a build command) to create all required output files FIRST. Apply your brain composition rules \u2014 anti-patterns, decision loop, and scope tier all bind. After calling the tool(s), return a short plain-text summary of what you did for posting to /room."
   ].join("\n");
 }
 function sleep(ms) {
@@ -877,7 +1485,9 @@ function makeCommitHook(opts) {
     const relPath = relativeTo(cwd, filePath);
     const addRes = spawn2("git", ["add", relPath], { cwd, encoding: "utf8" });
     if (addRes.status !== 0) {
-      throw new Error(`git add failed: ${addRes.stderr || addRes.stdout || `exit ${addRes.status}`}`);
+      throw new Error(
+        `git add failed: ${addRes.stderr || addRes.stdout || `exit ${addRes.status}`}`
+      );
     }
     const message = renderCommitMessage({ scope, task, identity, result });
     const commitArgs = ["commit", "-m", message];
@@ -886,7 +1496,9 @@ function makeCommitHook(opts) {
     }
     const commitRes = spawn2("git", commitArgs, { cwd, encoding: "utf8" });
     if (commitRes.status !== 0) {
-      throw new Error(`git commit failed: ${commitRes.stderr || commitRes.stdout || `exit ${commitRes.status}`}`);
+      throw new Error(
+        `git commit failed: ${commitRes.stderr || commitRes.stdout || `exit ${commitRes.status}`}`
+      );
     }
     const hashRes = spawn2("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf8" });
     const commitHash = hashRes.status === 0 ? hashRes.stdout.trim() : void 0;
@@ -1109,7 +1721,10 @@ USR:${user}`).digest("hex").slice(0, 16);
 }
 function withTimeout(p, ms, label) {
   return new Promise((resolve4, reject) => {
-    const timer = setTimeout(() => reject(new Error(`ablation cell "${label}" timed out after ${ms}ms`)), ms);
+    const timer = setTimeout(
+      () => reject(new Error(`ablation cell "${label}" timed out after ${ms}ms`)),
+      ms
+    );
     p.then(
       (v) => {
         clearTimeout(timer);
@@ -1295,13 +1910,29 @@ var Supervisor = class {
     return { ...managed.status };
   }
   async bootAgent(spec) {
-    const identity = this.identityFromSpec(spec);
     const brain = await loadBrain(spec.brainPath, spec.scopeTier ?? "warm");
-    const provider = await this.opts.providerFactory(spec, identity);
+    const decision = pickProvider({
+      brain,
+      envOverride: spec.provider,
+      candidates: BUILT_IN_CANDIDATES
+    });
+    const effectiveSpec = decision.picked === spec.provider ? spec : { ...spec, provider: decision.picked };
+    const identity = this.identityFromSpec(effectiveSpec);
+    if (decision.reason === "env-override-mismatch" && this.opts.logger) {
+      this.opts.logger({
+        ts: (/* @__PURE__ */ new Date()).toISOString(),
+        ev: "capability-router-mismatch",
+        handle: spec.handle,
+        envOverride: spec.provider,
+        unsatisfiedRequires: decision.unsatisfiedRequires,
+        excludedByAvoids: decision.excludedByAvoids
+      });
+    }
+    const provider = await this.opts.providerFactory(effectiveSpec, identity);
     const stateDir = this.opts.stateDir ?? join2(homedir(), ".holoscript-agent", "cost-state");
-    const isFree = spec.provider === "mock" || spec.provider === "local-llm" || spec.provider === "bitnet";
+    const isFree = effectiveSpec.provider === "mock" || effectiveSpec.provider === "local-llm" || effectiveSpec.provider === "bitnet";
     const costGuard = new CostGuard({
-      statePath: join2(stateDir, `${spec.handle}.json`),
+      statePath: join2(stateDir, `${effectiveSpec.handle}.json`),
       dailyBudgetUsd: identity.budgetUsdPerDay,
       pricer: isFree ? () => 0 : void 0
     });
@@ -1311,7 +1942,7 @@ var Supervisor = class {
       teamId: identity.teamId,
       fetchImpl: this.opts.fetchImpl
     });
-    const onTaskExecuted = spec.enableCommitHook ? this.buildCommitHook(spec, identity, mesh) : void 0;
+    const onTaskExecuted = effectiveSpec.enableCommitHook ? this.buildCommitHook(effectiveSpec, identity, mesh) : void 0;
     const runner = new AgentRunner({
       identity,
       brain,
@@ -1320,16 +1951,16 @@ var Supervisor = class {
       mesh,
       onTaskExecuted,
       auditLog: this.auditLog,
-      logger: (ev) => this.log({ agent: spec.handle, ...ev })
+      logger: (ev) => this.log({ agent: effectiveSpec.handle, ...ev })
     });
     const status = {
-      handle: spec.handle,
+      handle: effectiveSpec.handle,
       state: "starting",
       spentUsd: 0,
       remainingUsd: identity.budgetUsdPerDay,
       restarts: 0
     };
-    return { spec, identity, brain, runner, costGuard, status };
+    return { spec: effectiveSpec, identity, brain, runner, costGuard, status };
   }
   buildCommitHook(spec, identity, mesh) {
     const writer = makeCommitHook({
@@ -1351,7 +1982,9 @@ var Supervisor = class {
     }
     const wallet = process.env[spec.walletEnvKey];
     if (!wallet || !/^0x[0-9a-fA-F]{40}$/.test(wallet)) {
-      throw new Error(`Missing or malformed wallet env var "${spec.walletEnvKey}" for agent "${spec.handle}"`);
+      throw new Error(
+        `Missing or malformed wallet env var "${spec.walletEnvKey}" for agent "${spec.handle}"`
+      );
     }
     return {
       handle: spec.handle,
@@ -1427,6 +2060,8 @@ var VALID_PROVIDERS2 = /* @__PURE__ */ new Set([
   "anthropic",
   "openai",
   "gemini",
+  "xai",
+  "openrouter",
   "mock",
   "bitnet",
   "local-llm"
@@ -1440,16 +2075,21 @@ function parseSupervisorConfig(raw) {
   const data = JSON.parse(raw);
   if (!isObject(data)) throw new Error("Supervisor config must be a JSON object");
   if (!Array.isArray(data.agents)) throw new Error("Supervisor config.agents must be an array");
-  if (data.agents.length === 0) throw new Error("Supervisor config.agents must have at least one entry");
+  if (data.agents.length === 0)
+    throw new Error("Supervisor config.agents must have at least one entry");
   const seenHandles = /* @__PURE__ */ new Set();
-  const agents = data.agents.map((entry, idx) => validateAgent(entry, idx, seenHandles));
+  const agents = data.agents.map(
+    (entry, idx) => validateAgent(entry, idx, seenHandles)
+  );
   const globalBudgetUsdPerDay = optionalNumber(data, "globalBudgetUsdPerDay");
   const defaultTickIntervalMs = optionalNumber(data, "defaultTickIntervalMs");
   if (globalBudgetUsdPerDay != null && globalBudgetUsdPerDay <= 0) {
     throw new Error(`globalBudgetUsdPerDay must be positive, got ${globalBudgetUsdPerDay}`);
   }
   if (defaultTickIntervalMs != null && defaultTickIntervalMs < 5e3) {
-    throw new Error(`defaultTickIntervalMs must be >= 5000ms (mesh-friendly), got ${defaultTickIntervalMs}`);
+    throw new Error(
+      `defaultTickIntervalMs must be >= 5000ms (mesh-friendly), got ${defaultTickIntervalMs}`
+    );
   }
   return { agents, globalBudgetUsdPerDay, defaultTickIntervalMs };
 }
@@ -1472,8 +2112,10 @@ function validateAgent(entry, idx, seen) {
     throw new Error(`agents[${idx}].scopeTier "${scopeTier}" must be cold | warm | hot`);
   }
   const budgetUsdPerDay = optionalNumber(entry, "budgetUsdPerDay");
-  if (budgetUsdPerDay != null && budgetUsdPerDay <= 0) {
-    throw new Error(`agents[${idx}].budgetUsdPerDay must be positive, got ${budgetUsdPerDay}`);
+  if (budgetUsdPerDay != null && budgetUsdPerDay < 0) {
+    throw new Error(
+      `agents[${idx}].budgetUsdPerDay must be >= 0 (0 = unlimited), got ${budgetUsdPerDay}`
+    );
   }
   const tickIntervalMs = optionalNumber(entry, "tickIntervalMs");
   if (tickIntervalMs != null && tickIntervalMs < 5e3) {
@@ -1542,9 +2184,14 @@ async function provisionAgent(req, opts = { execute: false }) {
     throw new Error(`handle "${req.handle}" must match ${HANDLE_PATTERN2}`);
   }
   if (!req.founderBearer || req.founderBearer.trim().length === 0) {
-    throw new Error("founderBearer is required (HOLOMESH_API_KEY of an agent that can call /register)");
+    throw new Error(
+      "founderBearer is required (HOLOMESH_API_KEY of an agent that can call /register)"
+    );
   }
-  const meshApiBase = (req.meshApiBase ?? "https://mcp.holoscript.net/api/holomesh").replace(/\/$/, "");
+  const meshApiBase = (req.meshApiBase ?? "https://mcp.holoscript.net/api/holomesh").replace(
+    /\/$/,
+    ""
+  );
   const seatsRoot = req.seatsRoot ?? defaultSeatsRoot();
   const surface = req.handle;
   const seatId = makeSeatId(surface);
@@ -1559,10 +2206,7 @@ async function provisionAgent(req, opts = { execute: false }) {
       seatId,
       seatDir,
       willGenerateWallet: !existsSync3(walletPath),
-      willCallEndpoints: [
-        `POST ${meshApiBase}/register/challenge`,
-        `POST ${meshApiBase}/register`
-      ]
+      willCallEndpoints: [`POST ${meshApiBase}/register/challenge`, `POST ${meshApiBase}/register`]
     };
   }
   if (existsSync3(walletPath) && !opts.force) {
@@ -1605,30 +2249,40 @@ async function provisionAgent(req, opts = { execute: false }) {
   if (!challenge.nonce) {
     throw new Error(`/register/challenge returned no nonce: ${JSON.stringify(challenge)}`);
   }
-  const signature = await wallet.signTypedData(EIP712_DOMAIN, EIP712_TYPES, { nonce: challenge.nonce });
-  const registration = await postJson(
-    fetchImpl,
-    `${meshApiBase}/register`,
-    req.founderBearer,
-    {
-      name: req.handle,
-      wallet_address: wallet.address,
-      nonce: challenge.nonce,
-      signature
-    }
-  );
+  const signature = await wallet.signTypedData(EIP712_DOMAIN, EIP712_TYPES, {
+    nonce: challenge.nonce
+  });
+  const registration = await postJson(fetchImpl, `${meshApiBase}/register`, req.founderBearer, {
+    name: req.handle,
+    wallet_address: wallet.address,
+    nonce: challenge.nonce,
+    signature
+  });
   writeFileSync3(
     regPath,
-    JSON.stringify({ status: 201, response: registration, registered_at: (/* @__PURE__ */ new Date()).toISOString(), flow: "x402" }, null, 2),
+    JSON.stringify(
+      {
+        status: 201,
+        response: registration,
+        registered_at: (/* @__PURE__ */ new Date()).toISOString(),
+        flow: "x402"
+      },
+      null,
+      2
+    ),
     "utf8"
   );
   const agentId = registration.agent?.id;
   const bearer = registration.agent?.api_key;
   if (!agentId || !bearer) {
-    throw new Error(`/register did not return agent.id + agent.api_key: ${JSON.stringify(registration).slice(0, 400)}`);
+    throw new Error(
+      `/register did not return agent.id + agent.api_key: ${JSON.stringify(registration).slice(0, 400)}`
+    );
   }
   if (registration.wallet?.private_key) {
-    console.warn("[provision] WARN \u2014 server returned private_key despite x402 flow; ignoring (using local key).");
+    console.warn(
+      "[provision] WARN \u2014 server returned private_key despite x402 flow; ignoring (using local key)."
+    );
   }
   let joinedTeam;
   if (req.autoJoinTeamId) {
@@ -1688,7 +2342,12 @@ function encryptPrivateKey(privKey, masterKey) {
   const iv = randomBytes(12);
   const cipher = createCipheriv("aes-256-gcm", masterKey, iv);
   const ct = Buffer.concat([cipher.update(privKey, "utf8"), cipher.final()]);
-  return { iv: iv.toString("base64"), ct: ct.toString("base64"), tag: cipher.getAuthTag().toString("base64"), alg: "aes-256-gcm" };
+  return {
+    iv: iv.toString("base64"),
+    ct: ct.toString("base64"),
+    tag: cipher.getAuthTag().toString("base64"),
+    alg: "aes-256-gcm"
+  };
 }
 async function postJson(fetchImpl, url, bearer, body) {
   const res = await fetchImpl(url, {
@@ -1763,16 +2422,34 @@ async function main() {
 async function cmdRun(opts) {
   const identity = loadIdentity();
   const brain = await loadBrain(identity.brainPath, scopeTierFromEnv());
-  const provider = await buildProvider(identity);
+  const decision = pickProvider({
+    brain,
+    envOverride: identity.llmProvider,
+    candidates: BUILT_IN_CANDIDATES
+  });
+  const effectiveIdentity = decision.picked === identity.llmProvider ? identity : { ...identity, llmProvider: decision.picked };
+  if (decision.reason === "env-override-mismatch") {
+    console.log(
+      JSON.stringify({
+        ts: (/* @__PURE__ */ new Date()).toISOString(),
+        ev: "capability-router-mismatch",
+        envOverride: identity.llmProvider,
+        unsatisfiedRequires: decision.unsatisfiedRequires,
+        excludedByAvoids: decision.excludedByAvoids
+      })
+    );
+  }
+  const provider = await buildProvider(effectiveIdentity);
   const costGuard = new CostGuard({
     statePath: stateFilePath(identity),
     dailyBudgetUsd: identity.budgetUsdPerDay,
-    pricer: defaultPricerForProvider(identity.llmProvider)
+    pricer: defaultPricerForProvider(effectiveIdentity.llmProvider)
   });
   const mesh = new HolomeshClient({
     apiBase: identity.meshApiBase,
     bearer: identity.x402Bearer,
-    teamId: identity.teamId
+    teamId: identity.teamId,
+    signer: buildRequestSigner(identity.handle)
   });
   const commitHook = buildCommitHook(identity, mesh);
   const auditLog = buildAuditLog();
@@ -1786,7 +2463,14 @@ async function cmdRun(opts) {
     onTaskExecuted: commitHook,
     auditLog
   });
-  console.log(JSON.stringify({ ts: (/* @__PURE__ */ new Date()).toISOString(), ev: "boot", identity: identityForLog(identity), brain: { domain: brain.domain, tags: brain.capabilityTags, tier: brain.scopeTier } }));
+  console.log(
+    JSON.stringify({
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      ev: "boot",
+      identity: identityForLog(identity),
+      brain: { domain: brain.domain, tags: brain.capabilityTags, tier: brain.scopeTier }
+    })
+  );
   if (opts.once) {
     const result = await runner.tick();
     console.log(JSON.stringify({ ts: (/* @__PURE__ */ new Date()).toISOString(), ev: "tick-result", ...result }));
@@ -1811,15 +2495,26 @@ function supervisorProviderFactory() {
         return createOpenAIProvider({ defaultModel: spec.model });
       case "gemini":
         return createGeminiProvider({ defaultModel: spec.model });
+      case "xai":
+        return createXAIProvider({ defaultModel: spec.model });
+      case "openrouter":
+        return createOpenRouterProvider({ defaultModel: spec.model });
       case "local-llm":
         return createLocalLLMProvider({
           baseURL: process.env.HOLOSCRIPT_AGENT_LOCAL_LLM_BASE_URL,
-          model: spec.model
+          model: spec.model,
+          timeoutMs: process.env.HOLOSCRIPT_AGENT_LOCAL_LLM_TIMEOUT_MS ? Number(process.env.HOLOSCRIPT_AGENT_LOCAL_LLM_TIMEOUT_MS) : 3e5
         });
+      case "sovereign":
+        return resolveSovereignProviderAsync(spec.model ? { model: spec.model } : {}).then(
+          (r) => r.provider
+        );
       case "mock":
         return createMockProvider();
       default:
-        throw new Error(`Provider "${spec.provider}" not yet wired in supervisor \u2014 Phase 2.5 deliverable.`);
+        throw new Error(
+          `Provider "${spec.provider}" not yet wired in supervisor \u2014 add a case here.`
+        );
     }
   };
 }
@@ -1846,11 +2541,15 @@ async function cmdSupervise(rest) {
   process.on("SIGINT", onSig);
   process.on("SIGTERM", onSig);
   await sup.start();
-  console.log(JSON.stringify({ ts: (/* @__PURE__ */ new Date()).toISOString(), ev: "supervise-running", config: cfgPath }));
+  console.log(
+    JSON.stringify({ ts: (/* @__PURE__ */ new Date()).toISOString(), ev: "supervise-running", config: cfgPath })
+  );
   const reportEvery = Number(process.env.HOLOSCRIPT_AGENT_STATUS_REPORT_MS ?? "300000");
   if (reportEvery > 0) {
     setInterval(() => {
-      console.log(JSON.stringify({ ts: (/* @__PURE__ */ new Date()).toISOString(), ev: "supervisor-status", ...sup.status() }));
+      console.log(
+        JSON.stringify({ ts: (/* @__PURE__ */ new Date()).toISOString(), ev: "supervisor-status", ...sup.status() })
+      );
     }, reportEvery);
   }
 }
@@ -1872,7 +2571,9 @@ async function cmdAudit(rest) {
     const events = log.query(filter);
     for (const e of events) console.log(JSON.stringify(e));
   } else {
-    throw new Error("Usage: holoscript-agent audit [rollup|query|tail] [--agent=<h>] [--provider=<p>] [--task=<id>] [--kind=<k>] [--limit=<n>] [--log=<path>]");
+    throw new Error(
+      "Usage: holoscript-agent audit [rollup|query|tail] [--agent=<h>] [--provider=<p>] [--task=<id>] [--kind=<k>] [--limit=<n>] [--log=<path>]"
+    );
   }
 }
 async function cmdProvision(rest) {
@@ -1884,7 +2585,9 @@ async function cmdProvision(rest) {
   const force = rest.includes("--force");
   const founderBearer = process.env.HOLOMESH_API_KEY;
   if (!founderBearer) {
-    throw new Error("HOLOMESH_API_KEY env var required for provisioning (founder-tier bearer for /register endpoints)");
+    throw new Error(
+      "HOLOMESH_API_KEY env var required for provisioning (founder-tier bearer for /register endpoints)"
+    );
   }
   const result = await provisionAgent(
     {
@@ -1896,7 +2599,9 @@ async function cmdProvision(rest) {
     },
     { execute, force }
   );
-  console.log(JSON.stringify({ ts: (/* @__PURE__ */ new Date()).toISOString(), ev: "provision-result", ...result }, null, 2));
+  console.log(
+    JSON.stringify({ ts: (/* @__PURE__ */ new Date()).toISOString(), ev: "provision-result", ...result }, null, 2)
+  );
   if (result.status === "executed" || result.status === "reused") {
     console.log("\n# Add these lines to your .env to use this seat:");
     for (const line of result.envVarLines) console.log(line);
@@ -1908,19 +2613,27 @@ async function cmdStatus(rest) {
     throw new Error("Usage: holoscript-agent status --config=<path-to-agents.json>");
   }
   const config = loadSupervisorConfig(cfgPath);
-  console.log(JSON.stringify({
-    config: cfgPath,
-    agentCount: config.agents.length,
-    enabled: config.agents.filter((a) => a.enabled !== false).map((a) => a.handle),
-    disabled: config.agents.filter((a) => a.enabled === false).map((a) => a.handle),
-    globalBudgetUsdPerDay: config.globalBudgetUsdPerDay ?? null,
-    defaultTickIntervalMs: config.defaultTickIntervalMs ?? null
-  }, null, 2));
+  console.log(
+    JSON.stringify(
+      {
+        config: cfgPath,
+        agentCount: config.agents.length,
+        enabled: config.agents.filter((a) => a.enabled !== false).map((a) => a.handle),
+        disabled: config.agents.filter((a) => a.enabled === false).map((a) => a.handle),
+        globalBudgetUsdPerDay: config.globalBudgetUsdPerDay ?? null,
+        defaultTickIntervalMs: config.defaultTickIntervalMs ?? null
+      },
+      null,
+      2
+    )
+  );
 }
 async function cmdAblate(rest) {
   const specPath = rest.find((a) => a.startsWith("--spec="))?.split("=")[1];
   if (!specPath) {
-    throw new Error("Usage: holoscript-agent ablate --spec=<path-to-ablation.json> [--out-md=<path>] [--out-json=<path>]");
+    throw new Error(
+      "Usage: holoscript-agent ablate --spec=<path-to-ablation.json> [--out-md=<path>] [--out-json=<path>]"
+    );
   }
   const outMd = rest.find((a) => a.startsWith("--out-md="))?.split("=")[1];
   const outJson = rest.find((a) => a.startsWith("--out-json="))?.split("=")[1];
@@ -1949,7 +2662,12 @@ async function cmdAblate(rest) {
     },
     pricer: p.pricePerCallUsd != null ? () => p.pricePerCallUsd : p.pricePerMtokInput != null && p.pricePerMtokOutput != null ? (u) => (u.promptTokens * p.pricePerMtokInput + u.completionTokens * p.pricePerMtokOutput) / 1e6 : void 0
   }));
-  const startMsg = JSON.stringify({ ts: (/* @__PURE__ */ new Date()).toISOString(), ev: "ablation-start", task: spec.task.taskId, cells: providers.length });
+  const startMsg = JSON.stringify({
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    ev: "ablation-start",
+    task: spec.task.taskId,
+    cells: providers.length
+  });
   console.log(startMsg);
   const matrix = await runAblation({
     task: spec.task,
@@ -1967,17 +2685,19 @@ async function cmdAblate(rest) {
   if (!outMd && !outJson) {
     console.log(renderAblationMarkdown(matrix));
   }
-  console.log(JSON.stringify({
-    ts: (/* @__PURE__ */ new Date()).toISOString(),
-    ev: "ablation-done",
-    task: matrix.taskId,
-    cells: matrix.cells.length,
-    errors: matrix.cells.filter((c) => c.errorMessage).length,
-    totalCostUsd: matrix.totalCostUsd,
-    promptHash: matrix.promptHash,
-    outMd: outMd ?? null,
-    outJson: outJson ?? null
-  }));
+  console.log(
+    JSON.stringify({
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      ev: "ablation-done",
+      task: matrix.taskId,
+      cells: matrix.cells.length,
+      errors: matrix.cells.filter((c) => c.errorMessage).length,
+      totalCostUsd: matrix.totalCostUsd,
+      promptHash: matrix.promptHash,
+      outMd: outMd ?? null,
+      outJson: outJson ?? null
+    })
+  );
 }
 async function cmdWhoami() {
   const identity = loadIdentity();
@@ -1998,17 +2718,24 @@ async function buildProvider(identity) {
       return createOpenAIProvider({ defaultModel: identity.llmModel });
     case "gemini":
       return createGeminiProvider({ defaultModel: identity.llmModel });
+    case "xai":
+      return createXAIProvider({ defaultModel: identity.llmModel });
+    case "openrouter":
+      return createOpenRouterProvider({ defaultModel: identity.llmModel });
     case "mock":
       return createMockProvider();
     case "local-llm":
       return createLocalLLMProvider({
         baseURL: process.env.HOLOSCRIPT_AGENT_LOCAL_LLM_BASE_URL,
-        model: identity.llmModel
+        model: process.env.HOLOSCRIPT_AGENT_LOCAL_LLM_MODEL ?? identity.llmModel,
+        // Edge devices (Jetson ~15 tok/s) need more than the 120s default.
+        // HOLOSCRIPT_AGENT_LOCAL_LLM_TIMEOUT_MS overrides; default 300s.
+        timeoutMs: process.env.HOLOSCRIPT_AGENT_LOCAL_LLM_TIMEOUT_MS ? Number(process.env.HOLOSCRIPT_AGENT_LOCAL_LLM_TIMEOUT_MS) : 3e5
       });
+    case "sovereign":
+      return (await resolveSovereignProviderAsync(identity.llmModel ? { model: identity.llmModel } : {})).provider;
     default:
-      throw new Error(
-        `Provider "${p}" not yet wired in CLI \u2014 Phase 2 deliverable. Use anthropic | openai | gemini | local-llm | mock for now.`
-      );
+      throw new Error(`Provider "${p}" not yet wired in CLI \u2014 add a case in buildProvider.`);
   }
 }
 function buildCommitHook(identity, mesh) {
@@ -2029,6 +2756,41 @@ function buildCommitHook(identity, mesh) {
     }
   };
 }
+function canonicalizeSigning(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value))
+    return `[${value.map(canonicalizeSigning).join(",")}]`;
+  const obj = value;
+  return `{${Object.keys(obj).sort().map((k) => `${JSON.stringify(k)}:${canonicalizeSigning(obj[k])}`).join(",")}}`;
+}
+function buildRequestSigner(handle) {
+  const seatsRoot = process.env.HOLOSCRIPT_AGENT_SEATS_ROOT ?? join4(homedir3(), ".holoscript-agent", "seats");
+  const fp = createHash4("sha256").update(hostname2() + homedir3()).digest("hex").slice(0, 8);
+  const seatId = `holoscript-${handle}-${fp}-x402`;
+  const walletPath = join4(seatsRoot, seatId, "wallet.enc");
+  const masterKeyPath = join4(seatsRoot, ".master-key");
+  if (!existsSync4(walletPath) || !existsSync4(masterKeyPath)) return void 0;
+  try {
+    const blob = JSON.parse(readFileSync5(walletPath, "utf8"));
+    const masterKey = readFileSync5(masterKeyPath);
+    const iv = Buffer.from(blob.encrypted_privkey.iv, "base64");
+    const ct = Buffer.from(blob.encrypted_privkey.ct, "base64");
+    const tag = Buffer.from(blob.encrypted_privkey.tag, "base64");
+    const decipher = createDecipheriv(blob.encrypted_privkey.alg ?? "aes-256-gcm", masterKey, iv);
+    decipher.setAuthTag(tag);
+    const privateKey = Buffer.concat([decipher.update(ct), decipher.final()]).toString("utf8");
+    const wallet = new Wallet2(privateKey);
+    return async (body) => {
+      const nonce = randomBytes2(16).toString("hex");
+      const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+      const payload = canonicalizeSigning({ body, nonce, timestamp });
+      const signature = await wallet.signMessage(payload);
+      return { body, signature, signer_address: blob.address, nonce, timestamp };
+    };
+  } catch {
+    return void 0;
+  }
+}
 function scopeTierFromEnv() {
   const t = (process.env.HOLOSCRIPT_AGENT_SCOPE_TIER ?? "warm").toLowerCase();
   if (t === "cold" || t === "warm" || t === "hot") return t;
@@ -2072,8 +2834,8 @@ USAGE
 
 REQUIRED ENV
   HOLOSCRIPT_AGENT_HANDLE            agent handle (e.g. "security-auditor")
-  HOLOSCRIPT_AGENT_PROVIDER          anthropic | openai | gemini | local-llm | mock
-  HOLOSCRIPT_AGENT_MODEL             model id (e.g. "claude-opus-4-7")
+  HOLOSCRIPT_AGENT_PROVIDER          anthropic | openai | gemini | xai | openrouter | local-llm | sovereign | mock
+  HOLOSCRIPT_AGENT_MODEL             model id (e.g. "claude-opus-4-8")
   HOLOSCRIPT_AGENT_BRAIN             path to .hsplus brain composition
   HOLOSCRIPT_AGENT_WALLET            0x\u2026 wallet address
   HOLOSCRIPT_AGENT_X402_BEARER       per-surface mesh bearer (W.087 vertex B)
@@ -2092,10 +2854,18 @@ OPTIONAL ENV
   HOLOSCRIPT_AGENT_WORKING_DIR       git repo to commit into (default process.cwd())
   HOLOSCRIPT_AGENT_COMMIT_SCOPE      commit subject scope (default "agent(<handle>)")
   HOLOSCRIPT_AGENT_LOCAL_LLM_BASE_URL  local-llm provider base URL (default http://localhost:8080)
+  HOLOSCRIPT_AGENT_LOCAL_LLM_MODEL     local-llm model id (e.g. "qwen3:4b-instruct"); overrides HOLOSCRIPT_AGENT_MODEL for the local provider
+  HOLOSCRIPT_AGENT_LOCAL_LLM_TIMEOUT_MS  local-llm request timeout in ms (default 300000 \u2014 edge devices like Jetson need >120s)
 `);
 }
 main().catch((err) => {
-  console.error(JSON.stringify({ ts: (/* @__PURE__ */ new Date()).toISOString(), ev: "fatal", message: err instanceof Error ? err.message : String(err) }));
+  console.error(
+    JSON.stringify({
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      ev: "fatal",
+      message: err instanceof Error ? err.message : String(err)
+    })
+  );
   process.exit(1);
 });
 //# sourceMappingURL=index.js.map