fix: make a brokered Grok worker actually run, and make its failures diagnosable

README.md

@@ -54,6 +54,22 @@ import { PiHarnessAdapter } from "@noopolis/daimon/pi";
 
 ## Organization-runtime contract
 
+For a strict Codex agent in an already prepared runtime, the public
+`resolveOrganizationCodexSandboxProjection(config, agentId, { acceptanceStorePath })`
+API returns `noopolis.daimon.codex-sandbox-projection.v1`: canonical workspace/home
+paths, the resolved executable, and `sandboxArgs` containing the exact permission
+profile rendered for production. Append only `--` and a mechanical command when
+checking whether that policy can execute in the caller's container.
+
+The resolver opens and verifies caller-owned path identities and executes the
+Codex version probe. It does not import/read authentication, create an agent,
+accept a wake or invoke a model. The acceptance-store path must be the same one
+given to the control host. This API projects command permissions, not the complete
+cognition invocation: Codex's `sandbox` subcommand lacks the strict configuration
+flags accepted by `exec`. A caller must therefore use a fresh empty `HOME` and
+`CODEX_HOME` and a restricted environment for its mechanical probe. Do not infer
+successful tool use or completed agent work from this projection alone.
+
 `@noopolis/daimon/runtime` exports a standard JSON Schema for structural
 validation plus the strict, side-effect-free semantic
 `validateOrganizationRuntimeConfig` / `parseOrganizationRuntimeConfig` API and

docs/engines.md

@@ -81,6 +81,38 @@ the broker owns refresh and stale-credential recovery. The runtime checks broker
 readiness before admitting Grok agents and verifies their sandbox policy before
 turns. The older credential-lease helper is not the production host path.
 
+The broker worker is pinned to Grok CLI 1.0.34 and runs lean: a fixed Daimon
+system prompt, six tools (`run_terminal_command`, `read_file`, `grep`,
+`list_dir`, and the MCP meta-tools `search_tool`/`use_tool`), no bundled
+skills, workflows, plan mode, subagents, memory or web search, and a declared
+model and reasoning effort from a closed list (default `grok-4.6` at `low`).
+The broker proxy refuses any request outside that shape before it spends.
+
+Each broker registration (`service.json` v2) declares its model and effort,
+its usage ledger, and turn limits `{maxRequests, maxTokens, timeoutMs}`. A wake
+may only lower them (`DAIMON_ENGINE_WAKE_TIMEOUT_MS`,
+`DAIMON_ENGINE_WAKE_TOKEN_CEILING`; the `DAIMON_CODEX_WAKE_*` names are
+aliases). The proxy refuses request `maxRequests + 1` and any request after the
+deadline with HTTP 429 before upstream, and stops admitting requests once the
+upstream-reported running total (cached input included) reaches `maxTokens`, so
+a turn overshoots its token ceiling by at most one request. A tripped limit
+kills the worker. The broker seals every terminal turn with its usage, request
+count, declared model and limit reason, and writes one usage row (keyed by
+`turn`) plus per-request rows for completed and failed turns alike; a replayed
+turn is never metered twice. `resolveOrganizationGrokBrokerProjection` exposes
+a slot's full declared shape, and `noopolis.daimon.grok-slot-preflight.v2`
+receipts bind a slot's denied-path canaries to that projection's digest and to
+one recycle (the caller's nonce and the slot's increasing generation).
+
+Evaluators (Paideia judges and the optimizer, organization uid only) borrow the
+same credential through inference grants: `request_inference_grant` over the
+control socket returns a ten-minute token for one declared model and effort,
+which the evaluator's Grok CLI presents to the provider proxy through
+`env_key` in a config rendered by `renderGrokInferenceClientConfig`. Grant
+requests must carry no tools, are metered like a turn, and are written only to
+the broker's separate `inferenceLedgerPath` (`kind: "inference"` rows), never
+to a subject usage ledger or the wake fuse.
+
 AGY uses OS-native secure storage through one private D-Bus and Secret Service
 realm. Enroll it once with:
 

package.json

@@ -66,7 +66,8 @@
     "@earendil-works/pi-coding-agent": "^0.79.10",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@noopolis/mneme": "^0.1.1",
-    "ajv": "^8.17.1"
+    "ajv": "^8.17.1",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/node": "^24.12.4",

scripts/liveGrokBrokerSession.ts

@@ -8,8 +8,11 @@ import { readChild } from "../src/pi/cliChildOutput.ts";
 import { terminateChild, trackCliChild } from "../src/pi/cliProcess.ts";
 import { decodeGrokHeadlessTurn } from "../src/pi/grokHeadlessResult.ts";
 import { readGrokBrokerCredential } from "../src/runtime/grokBrokerCredentialReader.ts";
+import { DEFAULT_GROK_BROKER_TURN_LIMITS } from "../src/runtime/engineBrokerTurnAccounting.ts";
 import { startGrokBrokerProxy } from "../src/runtime/grokBrokerProxy.ts";
-import { renderGrokBrokerWorkerConfig } from "../src/runtime/grokBrokerWorkerConfig.ts";
+import { GrokBrokerTurnMeter } from "../src/runtime/grokBrokerTurnMeter.ts";
+import { DEFAULT_GROK_BROKER_MODEL_POLICY } from "../src/runtime/grokBrokerModelPolicy.ts";
+import { GROK_BROKER_PROVIDER_CAPABILITY_ENV, renderGrokBrokerWorkerArgs, renderGrokBrokerWorkerConfigWith } from "../src/runtime/grokBrokerWorkerConfig.ts";
 
 // Explicit live auth/transport check, not the Linux native worker/isolation E2E.
 // Read the operator credential only in this process; never stage or rotate it.
@@ -37,20 +40,21 @@ try {
       const capability = proxy.capabilities.issue("local-auth-probe", turnId);
       // This local transport probe deliberately does not attest a native worker.
       proxy.registerIsolationGuard(turnId, async () => undefined);
-      const helper = path.join(home, "auth-helper");
-      await writeFile(helper, `#!/bin/sh\nprintf '{"access_token":"${capability}","expires_in":600}\\n'\n`, { mode: 0o700 });
+      // The proxy forwards nothing unmetered; the probe runs under the default v1 limits.
+      proxy.registerTurn(turnId, { policy: DEFAULT_GROK_BROKER_MODEL_POLICY, meter: new GrokBrokerTurnMeter(DEFAULT_GROK_BROKER_TURN_LIMITS) });
       // No MCP tools are needed for this exact-reply authentication probe.
-      await writeFile(path.join(home, "config.toml"), renderGrokBrokerWorkerConfig(helper, proxy.port).split("[mcp_servers.daimon]")[0]);
+      await writeFile(path.join(home, "config.toml"), renderGrokBrokerWorkerConfigWith(DEFAULT_GROK_BROKER_MODEL_POLICY, { proxyPort: proxy.port, mcpUrl: "http://127.0.0.1:43124/mcp" }).split("[mcp_servers.daimon]")[0]);
       const prompt = path.join(home, "prompt.txt");
       await writeFile(prompt, `Reply exactly ${sentinel}. Do not use tools.`);
       stage = `model turn ${round}`;
-      const child = trackCliChild(spawn("grok", [
-        "--sandbox", "strict", "--prompt-file", prompt, "--no-memory", "--no-subagents",
-        "--disable-web-search", "--max-turns", "1", "--permission-mode", "dontAsk",
-        "--model", "daimon-broker-grok", "--output-format", "streaming-messages-json",
-      ], {
+      // The proxy only forwards the lean worker request shape (pinned client
+      // version, exact tool set, declared effort), so the probe uses the same
+      // argv as the native launcher with the built-in strict profile.
+      const args = [...renderGrokBrokerWorkerArgs(prompt, home)].map((value) => value === "daimon-strict" ? "strict" : value);
+      args[args.indexOf("--max-turns") + 1] = "1";
+      const child = trackCliChild(spawn("grok", args, {
         cwd: home, detached: process.platform !== "win32",
-        env: { PATH: process.env.PATH, HOME: home, GROK_HOME: home, LANG: "C", LC_ALL: "C", TZ: "UTC" },
+        env: { PATH: process.env.PATH, HOME: home, GROK_HOME: home, LANG: "C", LC_ALL: "C", TZ: "UTC", [GROK_BROKER_PROVIDER_CAPABILITY_ENV]: capability },
         stdio: ["ignore", "pipe", "pipe"],
       }));
       let output: string;

scripts/scriptSourcePolicy.test.ts

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { mkdir, mkdtemp, readdir, rm, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
@@ -37,3 +37,35 @@ test("script source policy detects a maintained JavaScript regression", async ()
     await rm(root, { force: true, recursive: true });
   }
 });
+
+// Raw control bytes make review tooling classify a source file as binary and skip it.
+// Escape them (`\u0000`) instead; tab, newline and carriage return are the only exceptions.
+const RAW_CONTROL = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/u;
+const textSourcesWithRawControlBytes = async (roots: string[]): Promise<string[]> => {
+  const results: string[] = [];
+  const walk = async (directory: string): Promise<void> => {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const entryPath = path.join(directory, entry.name);
+      if (entry.isDirectory()) { if (entry.name !== "artifacts" && entry.name !== "node_modules") await walk(entryPath); continue; }
+      if (!/\.(?:ts|mts|mjs|js|json|jsonl|md|c|h|inc|toml|sh|yml|yaml)$/u.test(entry.name)) continue;
+      if (RAW_CONTROL.test(await readFile(entryPath, "latin1"))) results.push(entryPath);
+    }
+  };
+  await Promise.all(roots.map(walk));
+  return results.sort();
+};
+
+test("maintained text sources contain no raw control bytes", async () => {
+  assert.deepEqual(await textSourcesWithRawControlBytes(["src", "scripts", "docs"]), []);
+});
+
+test("raw control byte policy detects a regression", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "daimon-control-policy-"));
+  try {
+    await writeFile(path.join(root, "regex.ts"), `export const r = /[${String.fromCharCode(0)}-${String.fromCharCode(0x1f)}]/u;\n`);
+    await writeFile(path.join(root, "clean.ts"), "export const r = /[\\u0000-\\u001f]/u;\n");
+    assert.deepEqual(await textSourcesWithRawControlBytes([root]), [path.join(root, "regex.ts")]);
+  } finally {
+    await rm(root, { force: true, recursive: true });
+  }
+});

src/contracts/grokWorkerContract.ts

@@ -0,0 +1,95 @@
+/**
+ * Fixed operating contract every broker-launched Grok worker receives through
+ * `--system-prompt-override`.
+ *
+ * The override replaces Grok's ~12k-token coding-agent system prompt and stops
+ * cwd `AGENTS.md` injection; the agent's identity and instructions still arrive
+ * in the prompt file. It is compiled into the native launcher byte-for-byte
+ * (`DBL_GROK_SYSTEM_PROMPT`), pinned by sha256 in the runtime contract
+ * manifest, and must stay ASCII without quotes or backslashes so the C literal
+ * needs no escaping.
+ *
+ * Daimon's per-wake tools reach Grok as deferred MCP tools named
+ * `daimon__<tool>` (server `[mcp_servers.daimon]`). Naming them lets `use_tool`
+ * run directly and saves one `search_tool` round trip per tool (P0: 3 → 2
+ * requests).
+ */
+
+/**
+ * The atoms of that route, and its single definition.
+ *
+ * Both texts a Grok worker receives are rendered from them: the pinned system
+ * prompt below, and the caller's identity envelope
+ * ({@link grokMountedToolNamingRule}, used by `src/runtime/engineDispatcher.ts`).
+ * They were worded independently once, and the envelope told the model to call
+ * the tools by their bare names - which Grok 1.0.34 refuses outright, before
+ * any HTTP: `'moltnet_read' is not a valid MCP tool name. Tool names must be
+ * qualified as \`server__tool\`` (local rig, real CLI, real rendered config).
+ * There is exactly one valid spelling, so two independently worded naming rules
+ * are one rule too many; this is the single definition both render from.
+ */
+export const DAIMON_GROK_MCP_SERVER = "daimon" as const;
+/** Grok's own name for an MCP tool of that server: exactly what `tool_name` must carry. */
+export const DAIMON_GROK_TOOL_PREFIX = `${DAIMON_GROK_MCP_SERVER}__` as const;
+export const grokDaimonToolName = (tool: string): string => `${DAIMON_GROK_TOOL_PREFIX}${tool}`;
+/** Grok's two MCP meta-tools, and the argument that names a tool for the first. */
+export const GROK_MCP_INVOKE_TOOL = "use_tool" as const;
+export const GROK_MCP_SEARCH_TOOL = "search_tool" as const;
+export const GROK_MCP_TOOL_NAME_ARGUMENT = "tool_name" as const;
+/** Illustrative Daimon tools for the system prompt, which cannot know a wake's real mount. */
+const DAIMON_GROK_EXAMPLE_TOOLS = Object.freeze(["moltnet_read", "moltnet_send", "memory_search", "memory_register"] as const);
+
+export const DAIMON_GROK_SYSTEM_PROMPT = [
+  "You are a headless Daimon agent; no human is present.",
+  "Your identity, instructions and wake event are in the user prompt.",
+  `Daimon tools are MCP tools on server ${DAIMON_GROK_MCP_SERVER}: call a known one directly with ${GROK_MCP_INVOKE_TOOL} (${GROK_MCP_TOOL_NAME_ARGUMENT} ${DAIMON_GROK_EXAMPLE_TOOLS.map(grokDaimonToolName).join(", ")}, or another ${DAIMON_GROK_TOOL_PREFIX} name you were given); use ${GROK_MCP_SEARCH_TOOL} only for a name you do not know.`,
+  "If a tool result says output was saved to a file, read that path with read_file.",
+  "If a tool fails, do not retry it in a loop: stop and report the failure.",
+  "Your final answer is a private note to the runtime: one line, or empty."
+].join(" ");
+
+/**
+ * The same route, stated once for the caller's identity envelope, where a
+ * wake's real mounted tools are known.
+ *
+ * It contributes exactly what the pinned prompt cannot know - the wake's real
+ * mounted names - and the one rule that makes them callable. It asserts rather
+ * than corrects: one bare catalogue, one prefix rule, one example, and the
+ * prefixed form named as the *only* valid form, because that is the CLI's own
+ * verdict on a bare name rather than a preference.
+ *
+ * What it deliberately leaves out is as load bearing. It never claims the
+ * agent's own instructions spell a tool wrongly, never offers a shell or CLI
+ * route, never repeats the catalogue in prefixed form - and never restates the
+ * `search_tool` rule. A Grok worker already reads two authoritative sentences
+ * about `search_tool`: the pinned prompt's ("only for a name you do not know")
+ * and Grok's own injected notice, which says the model MUST call it before any
+ * MCP tool. Observed on the rig: that contradiction is not enforced, and
+ * `use_tool` works with no prior `search_tool`. A third wording would only add
+ * a voice, so this sentence stays out of that argument entirely.
+ */
+export const grokMountedToolNamingRule = (mountedToolNames: readonly string[]): string => {
+  const example = grokDaimonToolName(mountedToolNames[0] ?? DAIMON_GROK_EXAMPLE_TOOLS[0]);
+  return `Your mounted tools are exactly: ${mountedToolNames.join(", ")}. `
+    + `On this engine each is an MCP tool on server ${DAIMON_GROK_MCP_SERVER}, and its only valid tool name is `
+    + `${DAIMON_GROK_TOOL_PREFIX}<name>: invoke it with ${GROK_MCP_INVOKE_TOOL}, ${GROK_MCP_TOOL_NAME_ARGUMENT} = ${example}. `
+    + "A bare name is not a valid MCP tool name and reaches nothing.";
+};
+
+/** Closed declared-model vocabulary; defaults are `grok-4.6` at `low`. */
+export const GROK_BROKER_MODELS = Object.freeze(["grok-4.6", "grok-4.5", "grok-build"] as const);
+export const GROK_BROKER_REASONING_EFFORTS = Object.freeze(["low", "medium", "high"] as const);
+
+/** `--tools` input ids. These are NOT the model-visible names (see below). */
+export const GROK_WORKER_TOOL_IDS = Object.freeze(["run_terminal_cmd", "read_file", "grep", "list_dir", "search_tool", "use_tool"] as const);
+
+/**
+ * The exact tool names a lean worker request body must carry.
+ *
+ * Grok 1.0.34 fails open on an unmappable `--tools` entry and ships all 19
+ * tools, so the proxy compares every upstream body against this set.
+ */
+export const GROK_WORKER_VISIBLE_TOOLS = Object.freeze(["grep", "list_dir", "read_file", "run_terminal_command", "search_tool", "use_tool"] as const);
+
+/** `--max-turns` backstop compiled into the launcher; per-wake ceilings belong to the broker. */
+export const GROK_WORKER_MAX_TURNS = 48 as const;

src/contracts/organizationRuntimeContract.ts

@@ -1,3 +1,5 @@
+import { GROK_BROKER_MODELS, GROK_BROKER_REASONING_EFFORTS } from "./grokWorkerContract.js";
+
 /** The data-only organization-runtime constants shared by product code and artifacts. */
 export const ORGANIZATION_RUNTIME_VERSION = "noopolis.daimon.organization-runtime.v1" as const;
 export const ORGANIZATION_RUNTIME_V2_VERSION = "noopolis.daimon.organization-runtime.v2" as const;
@@ -74,7 +76,11 @@ export const ORGANIZATION_RUNTIME_CONFIG_SCHEMA = {
           codexSandbox: { type: "object", additionalProperties: false, required: ["mode", "networkAccess", "webSearch"], properties: {
             mode: { const: "workspace-write" }, networkAccess: { const: false }, webSearch: { const: "disabled" }
           } }
-        } },
+        }, allOf: [
+          // grok: a declared model is the closed broker pair, both or neither; never a Codex sandbox.
+          { if: { properties: { kind: { const: "grok" } } }, then: { properties: { model: { enum: GROK_BROKER_MODELS }, reasoningEffort: { enum: GROK_BROKER_REASONING_EFFORTS }, codexSandbox: false }, dependentRequired: { model: ["reasoningEffort"], reasoningEffort: ["model"] } } },
+          { if: { properties: { kind: { const: "agy" } } }, then: { properties: { model: false, reasoningEffort: false, codexSandbox: false } } }
+        ] },
         ...PRODUCTION_TOOL_PROPERTIES
       }
     } }