hilos-agent 0.9.0 → 0.9.2

package/src/mcp-loopback.mjs

@@ -0,0 +1,142 @@
+// Turn-scoped loopback transport for a resumed Codex session (0854).
+//
+// Codex's remote MCP auth is normally an environment variable. The daemon
+// deliberately strips HILOS_* secrets from coding children, and handing a
+// persistent workspace token to a model-visible shell would undo that safety.
+// Instead, keep the token in the daemon process and expose a random loopback
+// URL only for the lifetime of one continuation. Codex can use every tool its
+// agent identity is authorized for; it never receives the bearer credential.
+
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+import { DAEMON_CLIENT } from "./mcp.mjs";
+
+const MAX_BODY_BYTES = 2 * 1024 * 1024;
+const FORWARDED_RESPONSE_HEADERS = [
+  "content-type",
+  "mcp-session-id",
+  "mcp-protocol-version",
+  "www-authenticate",
+];
+const FORWARDED_REQUEST_HEADERS = [
+  "content-type",
+  "accept",
+  "mcp-session-id",
+  "mcp-protocol-version",
+  "mcp-method",
+  "mcp-name",
+];
+const MAX_HEADER_LENGTH = 4096;
+
+function readBody(request) {
+  return new Promise((resolve, reject) => {
+    let size = 0;
+    const chunks = [];
+    request.on("data", (chunk) => {
+      size += chunk.length;
+      if (size > MAX_BODY_BYTES) {
+        reject(new Error("request body too large"));
+        request.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    request.on("end", () => resolve(Buffer.concat(chunks)));
+    request.on("error", reject);
+  });
+}
+
+/**
+ * Start an unguessable, loopback-only HTTP proxy to one authenticated hilos MCP
+ * endpoint. The caller must close it in finally after the coding turn.
+ * @param {{
+ *   url?: string,
+ *   token?: string,
+ *   channelId?: string,
+ *   fetchImpl?: typeof fetch,
+ * }} [options]
+ * @returns {Promise<{url: string, close: () => Promise<void>} | null>}
+ */
+export async function startHilosMcpLoopback({ url, token, channelId = "", fetchImpl = fetch } = {}) {
+  if (!url || !token) return null;
+  const nonce = randomBytes(24).toString("hex");
+  const path = `/mcp/${nonce}`;
+  const upstream = new URL(url);
+  // Preserve the room that caused this turn as MCP's effective context. This
+  // does not widen or narrow token access, but it keeps guest-room memory gates
+  // and other context-sensitive server policy active even when the model calls
+  // a workspace-scoped tool without a channelId argument.
+  if (channelId) upstream.searchParams.set("channelId", channelId);
+  const upstreamRequests = new Set();
+
+  const server = createServer(async (request, response) => {
+    if (request.url !== path || !["POST", "GET", "DELETE"].includes(request.method || "")) {
+      response.writeHead(404).end();
+      return;
+    }
+    const controller = new AbortController();
+    upstreamRequests.add(controller);
+    const abortUpstream = () => controller.abort();
+    request.once("aborted", abortUpstream);
+    response.once("close", abortUpstream);
+    try {
+      const body = request.method === "POST" ? await readBody(request) : undefined;
+      const headers = {
+        authorization: `Bearer ${token}`,
+        // This short-lived proxy is part of the persistent daemon's return
+        // path. Marking it on-demand would temporarily relabel a live daemon
+        // and could suppress the offline/wakeup behavior after the turn.
+        "x-hilos-connection-mode": "daemon",
+        ...(DAEMON_CLIENT ? { "x-hilos-client": DAEMON_CLIENT } : {}),
+      };
+      for (const name of FORWARDED_REQUEST_HEADERS) {
+        const value = request.headers[name];
+        if (typeof value === "string" && value.length <= MAX_HEADER_LENGTH) {
+          headers[name] = value;
+        }
+      }
+      const forwarded = await fetchImpl(upstream, {
+        method: request.method,
+        headers,
+        ...(body ? { body } : {}),
+        signal: controller.signal,
+      });
+      for (const name of FORWARDED_RESPONSE_HEADERS) {
+        const value = forwarded.headers.get(name);
+        if (value) response.setHeader(name, value);
+      }
+      response.writeHead(forwarded.status);
+      response.end(Buffer.from(await forwarded.arrayBuffer()));
+    } catch {
+      if (!response.destroyed && !response.writableEnded) {
+        response.writeHead(502, { "content-type": "application/json" });
+        response.end(JSON.stringify({ error: "hilos MCP loopback unavailable" }));
+      }
+    } finally {
+      upstreamRequests.delete(controller);
+      request.removeListener("aborted", abortUpstream);
+      response.removeListener("close", abortUpstream);
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", resolve);
+  });
+  const address = server.address();
+  if (!address || typeof address === "string") {
+    server.close();
+    return null;
+  }
+  let closed = false;
+  return {
+    url: `http://127.0.0.1:${address.port}${path}`,
+    async close() {
+      if (closed) return;
+      closed = true;
+      for (const controller of upstreamRequests) controller.abort();
+      server.closeAllConnections?.();
+      await new Promise((resolve) => server.close(() => resolve()));
+    },
+  };
+}

package/src/mcp.mjs

@@ -3,7 +3,7 @@
 import os from "node:os";
 
 // Best-effort host label so hilos can show "whose machine" this daemon runs on.
-const CLIENT = (() => {
+export const DAEMON_CLIENT = (() => {
   try {
     return `${os.userInfo().username}@${os.hostname()}`;
   } catch {
@@ -20,7 +20,8 @@ export function makeClient({ url, token }) {
       headers: {
         "content-type": "application/json",
         authorization: `Bearer ${token}`,
-        ...(CLIENT ? { "x-hilos-client": CLIENT } : {}),
+        "x-hilos-connection-mode": "daemon",
+        ...(DAEMON_CLIENT ? { "x-hilos-client": DAEMON_CLIENT } : {}),
       },
       body: JSON.stringify({ jsonrpc: "2.0", id: ++id, method, params }),
     });

package/src/model-resolve.mjs

@@ -11,7 +11,13 @@
 // PURE + node-builtins-only; the resolver takes an injected `run` (runCli) so
 // tests drive it with no CLI; a resolution failure NEVER breaks a run ([]).
 //
-// codex stays out: its CLI has no verified model-list command (0504 notes).
+// codex joined in 0783 on the SAME terms: `codex debug models` ("Render the raw
+// model catalog as JSON") is its `--list-models`, so its tier also resolves at
+// run time against the account's own catalog and never against a baked slug.
+// That matters more for codex than for anyone: its slugs are codenames that rev
+// (`gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` in the live catalog) and are
+// plan-gated — a run on a ChatGPT account rejects `gpt-5` outright with "The
+// 'gpt-5' model is not supported when using Codex with a ChatGPT account".
 
 /** Strip ANSI SGR color codes (`--list-models` output is colorized). */
 export function stripAnsi(s) {
@@ -65,30 +71,193 @@ export function resolveCursorModel(tier, ids) {
   return null;
 }
 
+/**
+ * Parse `codex debug models` stdout → the account's LISTED models, ranked by
+ * the catalog's own `priority` (lower first — it is Codex's own ordering of its
+ * lineup). Wire shape captured live against codex-cli 0.144.1:
+ *
+ *   {"models":[{"slug":"gpt-5.6-sol","display_name":"GPT-5.6-Sol",
+ *     "description":"Latest frontier agentic coding model.","priority":1,
+ *     "visibility":"list", …}, …]}
+ *
+ * `visibility:"hide"` entries are internal (the live catalog hides
+ * `codex-auto-review`, Codex's own approval-review model) and are dropped — the
+ * user's preset must never select something the CLI doesn't offer. A drifted
+ * or non-JSON payload → [] and the preset silently falls back to the tool
+ * default, same as the cursor path.
+ *
+ * `supported_in_api` rides along rather than being filtered here, because the
+ * catalog is the RAW lineup — the same bytes whichever way the account is
+ * logged in (verified live) — and whether an api-false model is usable depends
+ * on that login. `gpt-5.3-codex-spark` is the live example: api-false, and
+ * perfectly runnable on a ChatGPT account. A row that doesn't state the field
+ * counts as supported; we never filter on something the catalog didn't say.
+ * @param {string} stdout
+ * @returns {{slug: string, text: string, supportedInApi: boolean}[]}
+ */
+export function parseCodexModels(stdout) {
+  let payload;
+  try {
+    payload = JSON.parse(String(stdout || ""));
+  } catch {
+    return [];
+  }
+  const models = payload && Array.isArray(payload.models) ? payload.models : [];
+  const rows = [];
+  for (const m of models) {
+    if (!m || typeof m !== "object") continue;
+    if (typeof m.slug !== "string" || !m.slug) continue;
+    if (typeof m.visibility === "string" && m.visibility !== "list") continue;
+    const priority = Number.isFinite(m.priority) ? m.priority : Number.MAX_SAFE_INTEGER;
+    const text = `${m.description || ""} ${m.display_name || ""} ${m.slug}`.toLowerCase();
+    rows.push({ slug: m.slug, text, priority, supportedInApi: m.supported_in_api !== false });
+  }
+  rows.sort((a, b) => a.priority - b.priority);
+  return rows.map(({ slug, text, supportedInApi }) => ({ slug, text, supportedInApi }));
+}
+
+/**
+ * Which login `codex login status` is reporting. The CLI's own one-line answer
+ * ("Logged in using ChatGPT" on the live install, 0.4s, printed on STDERR) —
+ * asking it beats parsing `~/.codex/auth.json`, which is private and can move
+ * with CODEX_HOME. Feed it both streams.
+ *
+ * ONLY a positive "api key" reading counts as apikey; everything else,
+ * including an empty/failed/unrecognized answer, is "unknown" and changes
+ * nothing downstream. The ChatGPT wording is live-verified; the API-key wording
+ * is not (I had no API-key install to log into, and would not clobber a real
+ * login to make one), so the matcher is deliberately loose on that side and
+ * fail-safe on every other.
+ * @param {string} stdout
+ * @returns {'apikey'|'chatgpt'|'unknown'}
+ */
+export function codexAuthMode(stdout) {
+  const s = String(stdout || "").toLowerCase();
+  if (/api[\s_-]?key/.test(s)) return "apikey";
+  if (/chatgpt/.test(s)) return "chatgpt";
+  return "unknown";
+}
+
+/**
+ * Drop models this login cannot actually run. Only bites for `apikey`: the
+ * catalog's `supported_in_api:false` rows are exactly the ones an API-key run
+ * rejects, and the "Fastest" tier would otherwise reach for one
+ * (`gpt-5.3-codex-spark` is api-false in the live catalog). chatgpt/unknown
+ * pass through untouched — under ChatGPT auth those models are fine, and an
+ * unreadable auth answer must never silently narrow a user's lineup.
+ * @param {{slug: string, text: string, supportedInApi: boolean}[]} models
+ * @param {'apikey'|'chatgpt'|'unknown'} mode
+ */
+export function filterCodexModels(models, mode) {
+  if (!Array.isArray(models)) return [];
+  if (mode !== "apikey") return models;
+  return models.filter((m) => m && m.supportedInApi !== false);
+}
+
+// Ranked preferences per tier for codex, matched against each model's own
+// description + display name + slug. Codex's catalog SAYS which tier a model
+// is ("Latest frontier agentic coding model." / "Balanced agentic coding model
+// for everyday work." / "Fast and affordable…"), and unlike the slugs those
+// words are stable — reading them beats pattern-matching codenames that rev
+// every release. First pattern with any match wins, then the first model in
+// the catalog's own priority order that matches it.
+const CODEX_TIER_PREFS = {
+  opus: [/frontier/, /complex/],
+  sonnet: [/balanced/, /everyday/, /strong model/],
+  haiku: [/ultra-fast/, /fast and affordable/, /small,|cost-efficient|simpler/, /\b(mini|nano|spark|lite)\b/],
+};
+
+/**
+ * Pick the account's codex slug for a tier, or null when nothing fits.
+ *
+ * The positional fallback is the point of the priority sort: with no wording
+ * match, "Most capable" takes the catalog's own top-ranked model and "Fastest"
+ * takes its last — still only ever a slug the CLI just listed (the 0504 rule),
+ * so the worst case is a slightly-off tier, never a failed run. "Balanced" has
+ * no honest positional answer in a two-model catalog, so it falls back to the
+ * top-ranked one rather than inventing a middle.
+ * @param {'opus'|'sonnet'|'haiku'|string} tier
+ * @param {{slug: string, text: string}[]} models
+ * @returns {string|null}
+ */
+export function resolveCodexModel(tier, models) {
+  const prefs = CODEX_TIER_PREFS[tier];
+  if (!prefs || !Array.isArray(models) || models.length === 0) return null;
+  for (const re of prefs) {
+    const hit = models.find((m) => m && typeof m.text === "string" && re.test(m.text));
+    if (hit) return hit.slug;
+  }
+  if (tier === "haiku") return models[models.length - 1].slug;
+  return models[0].slug;
+}
+
+/**
+ * How each runtime-resolved vendor asks its own CLI what it can run: the list
+ * command, how to read its output, and the fallback binary name.
+ */
+const LIST_MODELS = {
+  cursor: {
+    bin: "cursor-agent",
+    args: ["--list-models"],
+    read: (stdout) => parseCursorModels(stdout),
+    pick: (tier, models) => resolveCursorModel(tier, models),
+  },
+  codex: {
+    bin: "codex",
+    args: ["debug", "models"],
+    read: (stdout) => parseCodexModels(stdout),
+    pick: (tier, models) => resolveCodexModel(tier, models),
+    // codex hands back its RAW lineup, including models a given login can't
+    // run — so it gets a second, cheaper question before the tier is picked.
+    authArgs: ["login", "status"],
+    narrow: (models, authStdout) => filterCodexModels(models, codexAuthMode(authStdout)),
+  },
+};
+
 /**
  * Build a memoized `modelArgsFor(cfg, vendor)` → `["--model", id]` or [].
- * Emits [] (tool default) when: the vendor isn't cursor, no/default tier is
- * configured, the user already pinned `--model` by hand in codingCmd, the
- * list command fails, or nothing matches. Successful lookups are cached per
- * (binary, tier) for the process lifetime; failures are NOT cached so a
- * transient hiccup (offline, auth) retries on the next run.
+ * Emits [] (tool default) when: the vendor resolves no tier at run time
+ * (anything outside LIST_MODELS), no/default tier is configured, the user
+ * already pinned a model by hand in codingCmd, the list command fails, or
+ * nothing matches. Successful lookups are cached per (binary, tier) for the
+ * process lifetime; failures are NOT cached so a transient hiccup (offline,
+ * auth) retries on the next run.
  *
  * @param {{ run: (opts: object) => Promise<{status: number|null, stdout: string}> }} o
  */
 export function createModelArgsResolver({ run } = {}) {
   const cache = new Map();
+  const authCache = new Map(); // binary → the CLI's own login answer, asked once
   return async function modelArgsFor(cfg, vendor) {
     try {
+      const spec = LIST_MODELS[vendor];
       const tier = String(cfg?.codingModel || "").trim();
-      if (vendor !== "cursor" || !tier || tier === "default") return [];
+      if (!spec || !tier || tier === "default") return [];
       const cmd = String(cfg?.codingCmd || "");
-      if (/(^|\s)--model(\s|=)/.test(cmd + " ")) return []; // hand-pinned wins
-      const bin = cmd.trim().split(/\s+/)[0] || "cursor-agent";
+      // Hand-pinned wins — including codex's short spelling (`-m gpt-5.6-sol`),
+      // which is what its own help leads with.
+      if (/(^|\s)(--model|-m)(\s|=)/.test(cmd + " ")) return [];
+      const bin = cmd.trim().split(/\s+/)[0] || spec.bin;
       const key = `${bin} ${tier}`;
       if (cache.has(key)) return cache.get(key);
-      const r = await run({ cmd: bin, args: ["--list-models"], timeoutMs: 30000, heartbeatMs: 0 });
+      const r = await run({ cmd: bin, args: spec.args, timeoutMs: 30000, heartbeatMs: 0 });
       if (!r || r.status !== 0) return [];
-      const id = resolveCursorModel(tier, parseCursorModels(r.stdout));
+      let models = spec.read(r.stdout);
+      if (spec.narrow) {
+        if (!authCache.has(bin)) {
+          const a = await run({ cmd: bin, args: spec.authArgs, timeoutMs: 15000, heartbeatMs: 0 });
+          // BOTH streams: `codex login status` prints its one line on STDERR
+          // (verified live — reading stdout alone returns nothing, which would
+          // silently mean "unknown" forever and quietly disable the narrowing).
+          // A failed/absent answer caches as "" → mode unknown → no narrowing.
+          authCache.set(
+            bin,
+            a && a.status === 0 ? `${String(a.stdout || "")}\n${String(a.stderr || "")}` : "",
+          );
+        }
+        models = spec.narrow(models, authCache.get(bin));
+      }
+      const id = spec.pick(tier, models);
       const args = id ? ["--model", id] : [];
       cache.set(key, args);
       return args;

package/src/permission-gate.mjs

@@ -0,0 +1,269 @@
+// The one block-on-a-human decision loop every vendor adapter shares (0777).
+//
+// opencode proved this flow first (0593 over HTTP/SSE, 0759 over ACP): raise the
+// durable hilos card, poll it under a hard deadline, and answer the agent with
+// the human's decision — with EVERY failure mode (callback error, transport
+// death, timeout, cancellation) resolving to a rejection AND settling the
+// durable card fail-closed, so a card can never be left pending while the tool
+// call proceeds.
+//
+// It lived inline in acp-session.mjs until claude_code and codex needed the
+// identical loop over completely different wires (an MCP permission-prompt tool
+// and codex's elicitation channel). Extracting it is what makes "the same card,
+// the same block, the same timeout" a mechanical fact instead of three
+// hand-copied implementations that can drift apart.
+
+import { mapOpenCodePermissionDecision } from "./opencode-permissions.mjs";
+
+export const DEFAULT_PERMISSION_TIMEOUT_MS = 30 * 60_000;
+export const DEFAULT_PERMISSION_POLL_MS = 1_000;
+
+function abortError(reason = "cancelled") {
+  const error = new Error(String(reason || "cancelled"));
+  error.name = "AbortError";
+  return error;
+}
+
+/**
+ * What the room is told when a gated run turns out to be ungateable (0785).
+ *
+ * A gate that quietly isn't there is worse than no gate, because the room
+ * believes it is. Two CLIs can land here: a codex without `mcp-server`, and a
+ * Claude Code that rejects `--permission-prompt-tool`. Both mean the same thing
+ * to a person watching the thread, so they say the same thing.
+ *
+ * @param {string} [tool] the binary that couldn't ask, when we know it
+ */
+export function ungatedRunNotice(tool) {
+  const name = typeof tool === "string" ? tool.trim() : "";
+  const who = name ? `\`${name}\` on this machine` : "the tool running this";
+  return `This run executes without asking first — ${who} can't raise approval requests. A newer version can.`;
+}
+
+/**
+ * A once-per-RUN latch for that notice.
+ *
+ * The gate is a property of the transport, decided once when the CLI starts —
+ * not of each ask. A run that degrades and then makes forty tool calls owes the
+ * room one line, and a run that retries its CLI (a gated iterate runs it more
+ * than once) still owes exactly one.
+ *
+ * Callers await this BEFORE spawning the ungated child, so the room is warned
+ * while the run can still be stopped rather than told afterwards what it
+ * already did. That is also why the post is bounded: it must go out first, but
+ * a stalled network call must not hold a run hostage — past the deadline we
+ * stop waiting and let the send land whenever it lands. Failure is swallowed
+ * either way; a notice must never take the run down with it.
+ *
+ * @param {{ post: (body: string) => Promise<unknown>, timeoutMs?: number,
+ *   log?: { error?: (m: string) => void } }} o
+ * @returns {(tool?: string) => Promise<boolean>} true only when the post landed
+ */
+export function createUngatedRunNotice({ post, timeoutMs = 10_000, log } = {}) {
+  let posted = false;
+  return async function noticeUngatedRun(tool) {
+    if (posted) return false;
+    posted = true;
+    let timer = null;
+    try {
+      const sent = Promise.resolve(post(ungatedRunNotice(tool)));
+      // Keep the rejection handled even if the deadline wins the race.
+      sent.catch(() => {});
+      const deadline = new Promise((resolve) => {
+        timer = setTimeout(() => resolve("timeout"), Math.max(1, timeoutMs));
+        timer?.unref?.();
+      });
+      const outcome = await Promise.race([sent.then(() => "sent"), deadline]);
+      if (outcome === "timeout") {
+        log?.error?.("ungated-run notice: still sending past its deadline; not holding the run");
+        return false;
+      }
+      return true;
+    } catch (error) {
+      log?.error?.(`ungated-run notice: ${error?.message ?? error}`);
+      return false;
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  };
+}
+
+function raceWithAbort(promise, signal) {
+  if (!signal) return Promise.resolve(promise);
+  if (signal.aborted) return Promise.reject(abortError(signal.reason));
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(abortError(signal.reason));
+    signal.addEventListener("abort", onAbort, { once: true });
+    Promise.resolve(promise).then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error);
+      },
+    );
+  });
+}
+
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
+
+/** How long a fail-closed settlement gets before we stop waiting on it. The
+ *  card is already being rejected on the wire; a hung settlement call must not
+ *  hold the agent's tool call open on top of it. */
+const SETTLEMENT_TIMEOUT_MS = 10_000;
+
+/**
+ * Race a callback against BOTH the abort signal and a wall-clock deadline.
+ *
+ * The deadline check between polls is not enough on its own: these callbacks
+ * are network calls (the daemon's MCP fetch has no timeout of its own), so a
+ * single stalled request could sit past the deadline forever and the ask would
+ * neither resolve nor fail. Bounding each call is what makes the deadline real.
+ */
+function withDeadline(promise, { signal, deadlineAt, now, label }) {
+  const remaining = deadlineAt - now();
+  if (remaining <= 0) return Promise.reject(abortError("timeout"));
+  let timer = null;
+  const timeout = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => reject(abortError("timeout")), remaining);
+    timer?.unref?.();
+  });
+  return Promise.race([raceWithAbort(promise, signal), timeout]).finally(() => {
+    if (timer) clearTimeout(timer);
+    void label;
+  });
+}
+
+/**
+ * Raise one permission card and block until a human decides it.
+ *
+ * Never throws: an unresolvable ask is a rejection, because the alternative —
+ * letting the tool call through — is the one outcome that cannot be undone.
+ *
+ * @param {{
+ *   request: object,
+ *   requestPermission: (request: object, context: object) => Promise<unknown>,
+ *   getPermissionDecision: (handle: unknown, context: object) => Promise<unknown>,
+ *   signal?: AbortSignal,
+ *   timeoutMs?: number,
+ *   deadlineAt?: number,
+ *   pollIntervalMs?: number,
+ *   settlementTimeoutMs?: number,
+ *   sleep?: (ms: number) => Promise<void>,
+ *   now?: () => number,
+ *   log?: { error?: (message: string) => void },
+ *   label?: string,
+ * }} options
+ * @returns {Promise<{ reply: "once"|"always"|"reject", outcome: string, handle: unknown }>}
+ */
+export async function resolveHilosPermissionReply({
+  request,
+  requestPermission,
+  getPermissionDecision,
+  signal,
+  timeoutMs = DEFAULT_PERMISSION_TIMEOUT_MS,
+  deadlineAt,
+  pollIntervalMs = DEFAULT_PERMISSION_POLL_MS,
+  settlementTimeoutMs = SETTLEMENT_TIMEOUT_MS,
+  sleep = defaultSleep,
+  now = () => Date.now(),
+  log,
+  label = "permission",
+}) {
+  if (typeof requestPermission !== "function" || typeof getPermissionDecision !== "function") {
+    throw new Error("permission gate requires requestPermission and getPermissionDecision");
+  }
+  const deadline = deadlineAt ?? now() + Math.max(1, timeoutMs || DEFAULT_PERMISSION_TIMEOUT_MS);
+  let handle = null;
+  let reply = "reject";
+  let outcome = "transport-error";
+  // 0813 — the envelope that actually SETTLED this ask. A workspace rule can
+  // refuse before any human sees the card, and its reason is the one thing a
+  // standing rule can hand the model that a one-off rejection cannot. Only the
+  // seams that carry a message use it; the rest ignore it.
+  let settled = null;
+  try {
+    if (signal?.aborted) throw abortError(signal.reason);
+    handle = await withDeadline(requestPermission(request, { signal, deadlineAt: deadline }), {
+      signal,
+      deadlineAt: deadline,
+      now,
+      label: "request",
+    });
+    let decision = handle;
+    settled = decision;
+    let mapped = mapOpenCodePermissionDecision(decision);
+    while (!mapped) {
+      if (now() >= deadline) throw abortError("timeout");
+      decision = await withDeadline(
+        getPermissionDecision(handle, { request, signal, deadlineAt: deadline }),
+        { signal, deadlineAt: deadline, now, label: "poll" },
+      );
+      settled = decision;
+      mapped = mapOpenCodePermissionDecision(decision);
+      if (mapped) break;
+      const waitMs = Math.min(Math.max(1, pollIntervalMs), Math.max(1, deadline - now()));
+      await raceWithAbort(sleep(waitMs), signal);
+    }
+    reply = mapped;
+    outcome = "decided";
+  } catch (error) {
+    reply = "reject";
+    outcome = error?.message === "timeout" ? "timeout" : signal?.aborted ? "aborted" : "transport-error";
+    log?.error?.(`${label} decision: ${error?.message ?? error}`);
+    // The agent is about to be failed closed. Settle the durable card too, on a
+    // bounded one-shot call with NO run signal — the run's signal is necessarily
+    // aborted on this path and must not strand a card visibly pending.
+    if (handle) {
+      // Best-effort, on its OWN short clock: the run deadline may already be
+      // blown (that is often why we are here), and a settlement call that
+      // stalls must not hold the agent's tool call open behind a rejection it
+      // has already earned.
+      try {
+        await withDeadline(
+          getPermissionDecision(handle, { request, deadlineAt: deadline, failClosed: true }),
+          { deadlineAt: now() + Math.max(1, settlementTimeoutMs), now, label: "settlement" },
+        );
+      } catch (settlementError) {
+        log?.error?.(`${label} settlement: ${settlementError?.message ?? settlementError}`);
+      }
+    }
+  }
+  return {
+    reply,
+    outcome,
+    handle,
+    byPolicy: isPolicyDecision(settled),
+    policyReason: policyReasonFrom(settled),
+  };
+}
+
+/**
+ * Was a workspace RULE what settled this, rather than a person?
+ *
+ * Kept separate from the reason on purpose. The reason is optional — a rule may
+ * carry none — so deriving "policy" from "has a reason" would quietly send a
+ * reasonless rule's refusal back as "a person declined this", which is exactly
+ * the false statement this pair exists to prevent. Provenance is the fact; the
+ * reason is a bonus.
+ */
+export function isPolicyDecision(envelope) {
+  if (!envelope || typeof envelope !== "object") return false;
+  return (envelope.decisionSource ?? envelope.decision_source) === "workspace_policy";
+}
+
+/**
+ * The workspace rule's own words, when a rule is what refused this and it
+ * bothered to say why.
+ *
+ * Deliberately narrow: only a `workspace_policy` decision source yields one, so
+ * a human's rejection can never be dressed up as policy, and a server that
+ * sends nothing yields null rather than a guess.
+ */
+export function policyReasonFrom(envelope) {
+  if (!isPolicyDecision(envelope)) return null;
+  const reason = envelope.policyReason ?? envelope.policy_reason;
+  return typeof reason === "string" && reason.trim() ? reason.trim() : null;
+}