hilos-agent 0.9.0 → 0.9.2

package/src/handler.mjs

@@ -37,16 +37,20 @@ import {
   scrubHilosEnv,
   envForCwd,
 } from "./cli.mjs";
-import { makeStreamParser } from "./agent-events.mjs";
+import { makeStreamParser, createUsageFold } from "./agent-events.mjs";
 import {
   detectVendor,
   codeStreamArgs,
   codeDirArgs,
+  codeImageArgs,
   codeProjectKey,
+  imagesNeedReading,
   attachTarget,
   createProgressEmitter,
   fastChatCmd,
 } from "./progress-emitter.mjs";
+import { createTranscriptTap } from "./transcript.mjs";
+import { imagePromptNote, renderAttachmentLine } from "./attachments.mjs";
 import { resolveFollowupMode, classifyFollowupCue, normalizeSignal } from "./followup.mjs";
 import {
   anchorIterateDecision,
@@ -67,6 +71,17 @@ import { buildMemoryBlock } from "./memory.mjs";
 import { deployFolder, resolveDeployTarget } from "./deploy.mjs";
 import { runOpenCodeHttpSession } from "./opencode-session.mjs";
 import { runAcpSession } from "./acp-session.mjs";
+import {
+  shouldGateClaudePermissions,
+  startClaudePermissionServer,
+} from "./claude-permissions.mjs";
+import {
+  codexMcpTransportUnavailable,
+  codexSandboxFromArgs,
+  runCodexMcpSession,
+  shouldGateCodexPermissions,
+} from "./codex-mcp-session.mjs";
+import { createUngatedRunNotice } from "./permission-gate.mjs";
 
 /**
  * The environment for a coding/chat CLI run. runCli always strips HILOS_* on top
@@ -147,6 +162,49 @@ function compactRunMarker(status, branch) {
   return `Failed:${b}`;
 }
 
+/**
+ * A `--model x` / `-m x` the operator pinned on the coding command (0787).
+ * `modelArgsFor` deliberately returns [] in that case — the hand-pin wins — so
+ * this is where a pinned id is recovered for the receipt.
+ */
+export function pinnedModelId(codingCmd) {
+  const m = /(?:^|\s)(?:--model|-m)(?:\s+|=)("[^"]+"|'[^']+'|\S+)/.exec(String(codingCmd || ""));
+  return m ? m[1].replace(/^["']|["']$/g, "") : "";
+}
+
+/**
+ * The `usage` argument for a report (0787), or `{}` when the CLI told us
+ * nothing — an omitted field is the honest answer, and the card degrades to
+ * "Tokens unavailable" rather than claiming a free run.
+ *
+ * TAKES from the fold. Every report writes its OWN ledger row server-side, so a
+ * run that reports more than once (a proposal card and then a shipped card, a
+ * revision round per loop) must carry only what is new since the last report;
+ * a running total would bill the same tokens twice.
+ *
+ * The model: whatever the stream named wins. Codex names none, so the id
+ * resolved at spawn — or pinned on the command — stands in, and failing both,
+ * the CLI's own name. The ledger has to say what ran.
+ */
+export function reportUsageArgs(fold, { vendor, modelId, runId } = {}) {
+  const totals = fold && typeof fold.take === "function" ? fold.take() : null;
+  if (!totals) return {};
+  const cli = vendor && vendor !== "unknown" ? vendor : null;
+  const model = totals.model || modelId || cli || "";
+  if (!model) return {};
+  const usage = {
+    model,
+    inputTokens: totals.inputTokens,
+    outputTokens: totals.outputTokens,
+    cacheReadTokens: totals.cacheReadTokens,
+    cacheCreationTokens: totals.cacheCreationTokens,
+  };
+  if (cli) usage.vendor = cli;
+  if (typeof totals.costUsd === "number") usage.costUsd = totals.costUsd;
+  if (runId) usage.runId = runId;
+  return { usage };
+}
+
 // Every helper below runs a tool in a directory we choose, so each one hands
 // the child a PWD that matches that directory instead of the daemon's launch
 // dir (0615). git and gh both use the real cwd, so this is hygiene rather than
@@ -162,6 +220,8 @@ function defaultDeps() {
     runCli: (opts) => runCli(opts),
     runOpenCodeHttpSession: (opts) => runOpenCodeHttpSession(opts),
     runAcpSession: (opts) => runAcpSession(opts),
+    runCodexMcpSession: (opts) => runCodexMcpSession(opts),
+    startClaudePermissionServer: (opts) => startClaudePermissionServer(opts),
     // Does a path exist on disk? Injectable so folder mode's "missing folder"
     // guard is unit-testable without touching the real filesystem.
     pathExists: (p) => existsSync(p),
@@ -297,6 +357,145 @@ function openCodePermissionCallbacks({
   };
 }
 
+/**
+ * The post_progress sender both run lanes use, with the 0782 stop check folded
+ * into the beat they already send.
+ *
+ * A person can press Stop on the live card from anywhere — the person who
+ * delegated the work usually is not the one at this laptop. The server records
+ * that on the run's own row and answers the NEXT heartbeat with
+ * `stopRequested: true` (plus `stoppedBy` when it knows the name). So the daemon
+ * learns it on its existing cadence: no poll tool, no second timer, nothing new
+ * to keep alive.
+ *
+ * `onStopRequested` is called at most once per sender and must never throw into
+ * the run — it is the daemon's cue to tear the process group down.
+ *
+ * @param {{ tool: Function, statusId: string, runId?: string|null,
+ *   onStopRequested?: (info: {by: string|null}) => any }} o
+ */
+export function createProgressSender({ tool, statusId, runId = null, onStopRequested }) {
+  let inflight = Promise.resolve();
+  let stopSeen = false;
+  const takeStop = (res) => {
+    if (!res || res.stopRequested !== true) return false;
+    if (stopSeen || !onStopRequested) return true;
+    stopSeen = true;
+    try {
+      onStopRequested({ by: typeof res.stoppedBy === "string" ? res.stoppedBy : null });
+    } catch {
+      /* the stop hand-off must never break the run's teardown */
+    }
+    return true;
+  };
+  return {
+    /** @param {object} p — the emitter's snapshot. */
+    send(p) {
+      try {
+        const r = tool("post_progress", {
+          messageId: statusId,
+          ...(runId ? { runId } : {}),
+          progress: p,
+        });
+        if (r && typeof r.then === "function") {
+          const done = r.then((res) => void takeStop(res), () => {});
+          inflight = Promise.all([inflight, done]).then(
+            () => {},
+            () => {},
+          );
+        }
+      } catch {
+        /* a progress send must never break the run */
+      }
+    },
+    /**
+     * Ask the server outright, and WAIT for the answer.
+     *
+     * The heartbeat above only fires when the CLI says something. A run sitting
+     * inside one silent ten-minute command emits nothing, so nothing would carry
+     * a stop home — the person would press Stop and watch their laptop keep
+     * going. This is the same call, on a timer, and it is also the authoritative
+     * pre-ship check: `state` echoes the card's CURRENT lifecycle so asking
+     * never repaints it (a stopped run's card is frozen server-side anyway).
+     *
+     * @param {"working"|"done"|"error"} [state]
+     * @returns {Promise<boolean>} true when a person has stopped this run.
+     */
+    async poll(state = "working") {
+      try {
+        const res = await tool("post_progress", {
+          messageId: statusId,
+          ...(runId ? { runId } : {}),
+          progress: { state },
+        });
+        return takeStop(res);
+      } catch {
+        // A stop check that can't reach the server is not a stop. The run
+        // continues; the next tick asks again.
+        return false;
+      }
+    },
+    /** Every dispatched write, so a caller can wait them out before settling. */
+    drain() {
+      return inflight;
+    },
+  };
+}
+
+/** How often a run asks whether it has been stopped while its CLI is silent.
+ *  Well under the card's own staleness window, far above a chatty write rate. */
+export const STOP_POLL_MS = 15_000;
+
+/**
+ * Arm the silent-work stop poll for ONE active job. Timers are injectable so
+ * this is unit-tested on a fake clock, and the returned `stop()` must be called
+ * from the same finally that tears the run down — one timer per job, never a
+ * timer that outlives the work it was watching.
+ *
+ * @param {{ poll: () => Promise<boolean>, intervalMs?: number,
+ *   setTimer?: Function, clearTimer?: Function }} o
+ */
+export function createStopPoller({
+  poll,
+  intervalMs = STOP_POLL_MS,
+  setTimer = (fn, ms) => {
+    const id = setInterval(fn, ms);
+    if (id && typeof id.unref === "function") id.unref();
+    return id;
+  },
+  clearTimer = (id) => clearInterval(id),
+} = {}) {
+  let id = null;
+  let asking = false;
+  let done = false;
+  const tick = async () => {
+    // Never stack asks: a slow server must not queue a burst of stop checks.
+    if (asking || done) return;
+    asking = true;
+    try {
+      if (await poll()) {
+        done = true; // the stop is handed over once; teardown owns the rest
+        stop();
+      }
+    } catch {
+      /* a stop check must never break the run */
+    } finally {
+      asking = false;
+    }
+  };
+  function stop() {
+    if (id == null) return;
+    try {
+      clearTimer(id);
+    } catch {
+      /* ignore */
+    }
+    id = null;
+  }
+  id = setTimer(() => void tick(), intervalMs);
+  return { stop, tick };
+}
+
 /** The local HTTP bridge can own only a local OpenCode server. An explicit
  * `--attach` remains on OpenCode's CLI responder, which rejects unanswered asks
  * fail closed; taking over a remote server requires a separate authenticated
@@ -315,22 +514,25 @@ export function shouldUseRuntimePermissionBridge({
   );
 }
 
-/** ACP transport opt-in (0759; slice 1 opencode, slice 2 cursor). Only runs
- * the workspace already gates with runtime permissions qualify, PLUS the
- * operator's explicit acpTransport flag, and only when the vendor's own
- * auto-allow escape hatches are absent — over ACP, hilos must be the one
- * answering asks, so a run configured to never ask has nothing to gate here.
- * Resumed runs stay on the existing paths: their session continuity contract
- * is argv/HTTP-shaped and the ACP path does not carry it yet. */
+/** ACP transport (0759; slice 1 opencode, slice 2 cursor). Only runs the
+ * workspace already gates with runtime permissions qualify, and only when the
+ * vendor's own auto-allow escape hatches are absent — over ACP, hilos must be
+ * the one answering asks, so a run configured to never ask has nothing to gate
+ * here.
+ *
+ * 0778 removed two limits that were never about correctness. `acpTransport`
+ * now defaults ON (config.mjs) for the vendors whose adapter is proven, and a
+ * RESUMED run no longer disqualifies: both live vendors advertise ACP's
+ * `loadSession` capability, so acp-session.mjs resumes the session and keeps
+ * raising cards. Setting `acpTransport: false` still opts a workspace out. */
 export function shouldUseAcpTransport({
   vendor,
   acpTransport,
   runtimePermissions,
   codeArgs,
   codingCmd,
-  resumeSessionId = /** @type {string | null} */ (null),
 }) {
-  if (acpTransport !== true || resumeSessionId != null) return false;
+  if (acpTransport !== true) return false;
   if (runtimePermissions !== true) return false;
   if (vendor === "opencode") {
     return shouldUseRuntimePermissionBridge({
@@ -348,6 +550,174 @@ export function shouldUseAcpTransport({
   return false;
 }
 
+/**
+ * The env a gated claude run gets (0777).
+ *
+ * A permission card can legitimately wait on a person for minutes — a 150s wait
+ * was verified live — so the CLI's own MCP tool timeout must not cut the ask
+ * short before hilos's run deadline does. Everything else about the env is
+ * unchanged (runCli still strips HILOS_* itself).
+ */
+function claudeGateEnv(cfg) {
+  const base = codingChildEnv(cfg) || process.env;
+  const budget = Math.max(60_000, Number(cfg?.runTimeoutMs) || 0) + 60_000;
+  return { ...base, MCP_TOOL_TIMEOUT: String(budget) };
+}
+
+/**
+ * Run claude_code through its permission-prompt seam (0777).
+ *
+ * Deliberately NOT a new transport: the ordinary argv run is untouched — same
+ * runCli, same resume args, same streaming — and the gate is two extra flags
+ * plus a loopback MCP server that lives exactly as long as the run. The prompt
+ * stays the final argument.
+ */
+async function runClaudeGatedCli({
+  deps,
+  cfg,
+  onGateDropped,
+  cmd,
+  codeArgs,
+  prompt,
+  cwd,
+  signal,
+  onData,
+  permissionCallbacks,
+  sessionId = "",
+  resolveSessionId,
+  log = console,
+}) {
+  const server = await deps.startClaudePermissionServer({
+    ...permissionCallbacks,
+    sessionId,
+    // A FRESH run has no session id to hand over: claude reveals its own in the
+    // init frame of its stream, which the progress emitter is already folding.
+    // Pulling from that snapshot means an ask carries the CLI's real session id
+    // without a second parser — and hilos rejects an empty one outright.
+    resolveSessionId,
+    timeoutMs: cfg.runTimeoutMs,
+    signal,
+    log,
+  });
+  try {
+    return await deps.runCli({
+      cmd,
+      args: [...codeArgs, ...server.args, prompt],
+      cwd,
+      timeoutMs: cfg.runTimeoutMs,
+      label: "coding",
+      signal,
+      env: claudeGateEnv(cfg),
+      onData,
+      // 0785 — a CLI that rejects the gate flags is retried without them. This
+      // fires BEFORE that ungated retry is spawned, so the room hears about the
+      // downgrade first rather than after the fact.
+      onPermissionGateDropped: onGateDropped,
+    });
+  } finally {
+    try {
+      await server.close();
+    } catch {
+      /* tearing the gate down must never fail a finished run */
+    }
+  }
+}
+
+/**
+ * Will this codex run take the gated transport (0785)?
+ *
+ * Answerable before the run's argv exists, because the only input that can
+ * change the answer is the operator's OWN command — every flag the daemon
+ * appends later (model, dir, image, resume, stream) is ours and none of them is
+ * the bypass tier. Which matters because the PROMPT is written before the
+ * transport is chosen, and what the prompt may claim about images depends on it.
+ */
+function codexRunIsGated(cfg, caps) {
+  return shouldGateCodexPermissions({
+    vendor: detectVendor(cfg?.codingCmd),
+    runtimePermissions: caps?.runtimePermissions,
+    codeArgs: String(cfg?.codingCmd || "").split(" ").filter(Boolean).slice(1),
+  });
+}
+
+/**
+ * Run codex through its gated transport, with an honest fallback (0785).
+ *
+ * A granted workspace ALWAYS gets `codex mcp-server` — that is what the grant
+ * means, and it is the only codex transport that can ask (`codex exec` has no
+ * approval channel at any flag combination, see codex-mcp-session.mjs). The one
+ * thing the grant can't conjure is the subcommand itself: a codex old enough
+ * not to have it never answers the MCP handshake, and before this the run just
+ * failed. Now it degrades to the plain exec argv — the ungated run every codex
+ * did before 0777, never worse.
+ *
+ * Two rules make that degrade safe. It happens ONLY on positive evidence that
+ * the subcommand is absent (codexMcpTransportUnavailable — every other
+ * pre-handshake failure is returned as the failed run it is, because a wrongly
+ * failed run is recoverable and a wrongly ungated one is not). And the room is
+ * told BEFORE the ungated child is spawned, so the warning arrives while the
+ * run can still be stopped.
+ *
+ * The exec argv is the run's real one (model, images, resume, stream flags),
+ * so the fallback is the same run the ungated lane would have made.
+ */
+async function runCodexGatedSession({
+  deps,
+  cfg,
+  onGateDropped,
+  cmd,
+  codeArgs,
+  prompt,
+  cwd,
+  model,
+  resumeThreadId = null,
+  signal,
+  onData,
+  onEvent,
+  permissionCallbacks,
+}) {
+  const run = await deps.runCodexMcpSession({
+    cmd,
+    cwd,
+    prompt,
+    sandbox: codexSandboxFromArgs(codeArgs),
+    // 0785 — the resolved tier (0783) or a hand-pinned id. The gated transport
+    // took the account default before this, so a preset was silently ignored
+    // exactly where the operator was most likely to have set one.
+    model: model || null,
+    resumeThreadId,
+    timeoutMs: cfg.runTimeoutMs,
+    signal,
+    env: scrubHilosEnv(codingChildEnv(cfg) || process.env),
+    onData,
+    onEvent,
+    ...permissionCallbacks,
+  });
+  if (!codexMcpTransportUnavailable(run)) return run;
+  console.log(
+    "  code → this codex has no `mcp-server`; running WITHOUT the hilos permission gate",
+  );
+  // Warn FIRST — before a single ungated command can run.
+  if (typeof onGateDropped === "function") {
+    try {
+      await onGateDropped();
+    } catch {
+      /* telling the room must never break the run */
+    }
+  }
+  const fallback = await deps.runCli({
+    cmd,
+    args: [...codeArgs, prompt],
+    cwd,
+    timeoutMs: cfg.runTimeoutMs,
+    label: "coding",
+    signal,
+    env: codingChildEnv(cfg),
+    onData,
+  });
+  return { ...fallback, permissionGateDropped: true };
+}
+
 async function awaitDecision({ tool, channelId, reportMessageId, cfg, deps, parentId, signal }) {
   if (!reportMessageId) return { kind: "timeout" };
   const deadline = deps.now() + cfg.decisionTimeoutMs;
@@ -398,7 +768,7 @@ async function linkPrFromUrl({ tool, channelId, url }) {
   await tool("link_pr", { channelId, repoFullName: m[1], prNumber: Number(m[2]) }).catch(() => {});
 }
 
-async function applyDecision({ decision, repoPath, branch, task, requester, cfg, tool, channelId, deps, parentId, existingPrUrl, settleId, runId }) {
+async function applyDecision({ decision, repoPath, branch, task, requester, cfg, tool, channelId, deps, parentId, existingPrUrl, settleId, runId, usageArgs = {} }) {
   const tag = requesterTag(requester);
   const lead = tag ? `${tag} — ` : "";
   // `parentId` here is the run's thread root. Terminal outcomes ask the server
@@ -457,13 +827,21 @@ async function applyDecision({ decision, repoPath, branch, task, requester, cfg,
           : `${lead}pushed \`${branch}\`. Open a PR manually — \`gh\` failed.`,
       prUrl: pr.ok && pr.url ? pr.url : undefined,
       caveats: pr.ok ? [] : [`gh pr create failed: ${(pr.stderr || "").trim().slice(0, 200)}`],
+      // 0787 — what the run cost, when the caller had a receipt to hand over.
+      // Ungated runs land here with the whole run's usage; a gated one already
+      // spent it on the proposal card and passes {}.
+      ...usageArgs,
     };
-    await tool(
+    // 0792 — keep the id of the card this run settled onto, so the caller can
+    // mark it with the run's transcript. `settleId` is that card when the run
+    // streamed onto a live status message; otherwise it is the fresh report.
+    const reportRes = await tool(
       "post_report",
       settleId
         ? { ...reportArgs, messageId: settleId, broadcast: true }
         : { ...reportArgs, parentId, broadcast: true },
     );
+    const reportMsgId = settleId || reportRes?.messageId || null;
     // Work produced a PR → attach it to the channel so its live pill shows up.
     await linkPrFromUrl({ tool, channelId, url: pr.ok ? pr.url : null });
     // Bind the PR to the thread's run (0279/0280) so a follow-up continues it.
@@ -473,10 +851,13 @@ async function applyDecision({ decision, repoPath, branch, task, requester, cfg,
         runId,
         ...(pr.ok && pr.url ? { prUrl: pr.url } : {}),
         status: "awaiting_review",
-        ...(settleId ? { reportMsgId: settleId } : {}),
+        // 0792: record the card even when it was a fresh report rather than a
+        // settle — it is the run's card either way, and the transcript upload
+        // falls back to this exact field when it is not handed an id.
+        ...(reportMsgId ? { reportMsgId } : {}),
       }).catch(() => {});
     }
-    return { status: "pushed", branch, prUrl: pr.ok ? pr.url : null };
+    return { status: "pushed", branch, prUrl: pr.ok ? pr.url : null, reportMsgId };
   }
 
   if (decision.kind === "rejected") {
@@ -516,7 +897,7 @@ async function applyDecision({ decision, repoPath, branch, task, requester, cfg,
  * switched to `main` would otherwise make `gh` try to open main → main. Used
  * only when NOT gated (bias-to-action).
  */
-async function shipSelfDriven({ repoPath, branch, task, requester, cfg, tool, channelId, deps, parentId, settleId, runId }) {
+async function shipSelfDriven({ repoPath, branch, task, requester, cfg, tool, channelId, deps, parentId, settleId, runId, usageArgs = {} }) {
   const tag = requesterTag(requester);
   const lead = tag ? `${tag} — ` : "";
   const currentBranch =
@@ -568,13 +949,17 @@ async function shipSelfDriven({ repoPath, branch, task, requester, cfg, tool, ch
         : prFailure
           ? [`gh pr create failed: ${prFailure}`]
           : [],
+    // 0787 — an autonomous run's receipt rides its one and only report.
+    ...usageArgs,
   };
-  await tool(
+  const reportRes = await tool(
     "post_report",
     settleId
       ? { ...reportArgs, messageId: settleId, broadcast: true }
       : { ...reportArgs, parentId, broadcast: true },
   );
+  // 0792 — the card this run settled onto, for the transcript stamp.
+  const reportMsgId = settleId || reportRes?.messageId || null;
   if (prUrl) await linkPrFromUrl({ tool, channelId, url: prUrl });
   // Bind the PR to the thread's run (0279/0280). Best-effort; only when recorded.
   if (runId) {
@@ -590,7 +975,7 @@ async function shipSelfDriven({ repoPath, branch, task, requester, cfg, tool, ch
                 : prFailure || "GitHub did not return a pull request URL",
           }
         : {}),
-      ...(settleId ? { reportMsgId: settleId } : {}),
+      ...(reportMsgId ? { reportMsgId } : {}),
     }).catch(() => {});
   }
   const status =
@@ -599,6 +984,7 @@ async function shipSelfDriven({ repoPath, branch, task, requester, cfg, tool, ch
     status,
     branch: ship.headBranch,
     prUrl,
+    reportMsgId,
   };
 }
 
@@ -700,16 +1086,21 @@ async function routeIntent({ name, repoFullName, transcript, workspaceMemory, cf
  * agent, edit files now" — led by the router's distilled `brief` (what to build),
  * with the conversation included only as background. Falls back to the raw
  * mention when there's no brief.
- * @param {{ message?: { body?: string } | null, context?: { transcript?: string } | null, brief?: string, repoFullName?: string }} [o]
+ * @param {{ message?: { body?: string } | null, context?: { transcript?: string } | null, brief?: string, repoFullName?: string, images?: {path: string, name: string, type: string}[], imagesReadable?: boolean }} [o]
  */
 export function codeTaskPrompt(o) {
-  const { message, context, brief, repoFullName } = o || {};
+  const { message, context, brief, repoFullName, images, imagesReadable } = o || {};
   const task = (brief && brief.trim()) || String(message?.body || "").trim();
   const transcript = context?.transcript?.trim();
   const where = repoFullName ? ` in the git repository ${repoFullName}` : "";
   let p =
     `You are a coding agent working${where}. Implement the following by EDITING FILES now — ` +
     `make the changes directly, do not just describe them, do not ask questions:\n\n${task}`;
+  // 0779: the screenshots the request was about, already on this machine. Right
+  // under the task, because "fix this spacing" only means something next to the
+  // picture of the spacing.
+  const imageNote = imagePromptNote(images, { readable: imagesReadable });
+  if (imageNote) p += `\n\n${imageNote}`;
   // The daemon owns git: it stages, commits, pushes, and opens the PR after the
   // CLI finishes. An autonomous CLI run with skip-permissions inside a repo whose
   // docs prescribe a commit+PR workflow will otherwise do all of that itself,
@@ -732,16 +1123,19 @@ export function codeTaskPrompt(o) {
  * imperative "edit files now" framing as codeTaskPrompt, but it tells the agent
  * its edits land straight in the folder and bans git/gh (there's nothing for the
  * daemon to commit; the changes ARE the deliverable).
- * @param {{ message?: { body?: string } | null, context?: { transcript?: string } | null, brief?: string, folderPath?: string }} [o]
+ * @param {{ message?: { body?: string } | null, context?: { transcript?: string } | null, brief?: string, folderPath?: string, images?: {path: string, name: string, type: string}[], imagesReadable?: boolean }} [o]
  */
 export function folderTaskPrompt(o) {
-  const { message, context, brief, folderPath } = o || {};
+  const { message, context, brief, folderPath, images, imagesReadable } = o || {};
   const task = (brief && brief.trim()) || String(message?.body || "").trim();
   const where = folderPath ? ` in the local folder ${folderPath}` : "";
   let p =
     `You are a coding agent working directly${where}. Implement the following by EDITING ` +
     `FILES now — make the changes directly in this folder, do not just describe them, do not ` +
     `ask questions:\n\n${task}`;
+  // 0779 — same image handoff as the repo path.
+  const imageNote = imagePromptNote(images, { readable: imagesReadable });
+  if (imageNote) p += `\n\n${imageNote}`;
   p +=
     `\n\nIMPORTANT: your edits apply DIRECTLY to the user's folder — there is no branch, no ` +
     `commit, and no pull request. Do NOT run git; do NOT stage, commit, push, create branches, ` +
@@ -784,7 +1178,17 @@ async function fetchContext({ channelId, tool, parentId }) {
     }));
     rows = messages;
   }
-  return { rows, transcript: rows.map((m) => `${m.author}: ${m.body}`).join("\n").slice(-6000) };
+  // 0779: the rows carry resolved `attachments`, and the body carries the
+  // unresolvable `![name](attachment:<uuid>)` pill token. Flatten the token and
+  // name the file, so the daemon's chat replies and routing decisions stop
+  // being handed a reference no model can follow.
+  return {
+    rows,
+    transcript: rows
+      .map((m) => `${m.author}: ${renderAttachmentLine(m.body, m.attachments)}`)
+      .join("\n")
+      .slice(-6000),
+  };
 }
 
 /**
@@ -1362,9 +1766,26 @@ async function handleFolderDeploy({
  * live), request-changes = re-run in place (bounded), reject = revert the run's
  * own changes (git repos only).
  */
-async function handleFolderTask({ message, channelId, tool, me, caps, cfg, deps, signal, parentId, folderPath, brief, workspaceMemory, context }) {
+async function handleFolderTask({ message, channelId, tool, me, caps, cfg, deps, signal, parentId, folderPath, brief, workspaceMemory, context, onStopRequested }) {
   void me;
   const git = deps.git;
+  // 0779 — screenshots the poll loop already pulled to a temp dir at pickup.
+  // The prompt names them; the argv carries them for a vendor that takes one.
+  const localImages = Array.isArray(message?.images) ? message.images : [];
+  const folderImagePromptArgs = localImages.length
+    ? {
+        images: localImages,
+        imagesReadable: imagesNeedReading(detectVendor(cfg.codingCmd), {
+          gated: codexRunIsGated(cfg, caps),
+        }),
+      }
+    : {};
+  // 0785 — one line per run, whichever CLI turns out to be ungateable.
+  const noticeUngatedRun = createUngatedRunNotice({
+    // Read at post time, not now: the thread root is the ack this run posts.
+    post: (body) => tool("post_message", { channelId, parentId: threadRoot, body }),
+    log: console,
+  });
   const tag = requesterTag(message.author);
   const lead = tag ? `${tag} — ` : "";
 
@@ -1411,6 +1832,33 @@ async function handleFolderTask({ message, channelId, tool, me, caps, cfg, deps,
   // supports it, else the edit-in-place heartbeat, else nothing. Kept across
   // request-changes re-runs on the same status message.
   let progressId = null;
+  // 0787 — what the run cost, folded across every round of the revise loop and
+  // taken at each report so each round's spend is reported exactly once. The
+  // model id the stream names wins; `resolvedModelId` is the spawn-time
+  // fallback for a CLI (codex) whose stream never says.
+  const runUsage = createUsageFold();
+  const cliVendor = detectVendor(cfg.codingCmd);
+  let resolvedModelId = pinnedModelId(cfg.codingCmd);
+  let lastTerminalState = "done";
+  /**
+   * Accounting-only settlement (0787). Plenty of terminal exits produce no
+   * report at all — nothing changed, the CLI never started, a person pressed
+   * Stop — and the tokens those runs spent were being dropped on the floor.
+   * `post_progress` is the terminal call the daemon already makes on every one
+   * of them, it is already run-scoped, and it already carries `runId`, so the
+   * spend rides home on a call that was happening anyway rather than on a new
+   * tool. Only ever the DELTA, so a later report cannot re-report it; a card is
+   * required because there is no other message to hang a terminal update on.
+   */
+  const settleRunUsage = async () => {
+    const args = reportUsageArgs(runUsage, { vendor: cliVendor, modelId: resolvedModelId });
+    if (!args.usage || !progressId) return;
+    await tool("post_progress", {
+      messageId: progressId,
+      progress: { state: lastTerminalState },
+      usage: args.usage,
+    }).catch(() => {});
+  };
   const folderWorking = (elapsedMs, lastLine) => {
     const base = `Working in \`${folderPath}\` — ${fmtElapsed(elapsedMs)} elapsed. I'll report what changed when it's done.`;
     const tail = oneLine(lastLine);
@@ -1425,7 +1873,10 @@ async function handleFolderTask({ message, channelId, tool, me, caps, cfg, deps,
     const streamOn = Boolean(caps.postProgress);
     const streamArgs = streamOn ? codeStreamArgs(vendor) : [];
     let emitter = null;
-    let progressInflight = Promise.resolve();
+    // Every dispatched progress write, so the settle can wait them out (0289).
+    let drainProgress = async () => {};
+    // 0782 — the silent-work stop poll, torn down in the same finally as the run.
+    let stopPoller = null;
     let stopHeartbeat = () => {};
     let lastLine = "";
     // With stream args the CLI's stdout is NDJSON events, not prose — parse it and
@@ -1437,6 +1888,11 @@ async function handleFolderTask({ message, channelId, tool, me, caps, cfg, deps,
     const foldResultEvents = (events) => {
       for (const ev of events || []) {
         if (ev && ev.t === "result" && ev.summary) resultText = ev.summary;
+        // 0787 — read the numbers off the SAME parse the summary comes from.
+        // This parser exists whenever stream args do, which is a superset of the
+        // cases where a progress emitter exists, so folder usage never depends
+        // on the status card having been posted.
+        runUsage.push(ev);
       }
     };
     if (streamOn) {
@@ -1450,21 +1906,21 @@ async function handleFolderTask({ message, channelId, tool, me, caps, cfg, deps,
       }
       const statusId = progressId;
       if (statusId) {
+        // 0782 — a folder run has no runs row, so the stop check is scoped to
+        // the card's thread by the server; it degrades to "no stop" quietly.
+        const sender = createProgressSender({ tool, statusId, onStopRequested });
         emitter = createProgressEmitter({
           parser: makeStreamParser(vendor),
           now: deps.now,
           throttleMs: cfg.progressMs,
-          send: (p) => {
-            try {
-              const r = tool("post_progress", { messageId: statusId, progress: p });
-              if (r && typeof r.then === "function") {
-                const done = r.then(() => {}, () => {});
-                progressInflight = Promise.all([progressInflight, done]).then(() => {}, () => {});
-              }
-            } catch {
-              /* a progress send must never break the run */
-            }
-          },
+          send: sender.send,
+        });
+        drainProgress = () => sender.drain();
+        // The heartbeat only fires when the CLI speaks. This asks anyway, so a
+        // run inside one long silent command is still stoppable.
+        stopPoller = createStopPoller({
+          poll: () => sender.poll("working"),
+          intervalMs: cfg.stopPollMs || STOP_POLL_MS,
         });
       }
     } else if (caps.editMessage && cfg.heartbeatMs > 0) {
@@ -1497,14 +1953,21 @@ async function handleFolderTask({ message, channelId, tool, me, caps, cfg, deps,
     let run;
     // Model preset (0504): same run-time resolution as the repo path.
     const modelArgs = await modelArgsFor(cfg, vendor);
+    // 0787: the id we actually handed the CLI, kept for the usage receipt when
+    // the vendor's own stream never names a model.
+    if (modelArgs[0] === "--model" && modelArgs[1]) resolvedModelId = modelArgs[1];
     // Project pin (0608): opencode reads its project from PWD, so without this
     // a folder run could edit the daemon's launch directory instead of the
     // folder the channel is linked to. [] for every other vendor.
     const dirArgs = codeDirArgs(vendor, folderPath, cfg.codingCmd);
+    // 0779: [] for every vendor without a verified image flag — their argv is
+    // byte-identical to before, and the prompt note still names the files.
+    const imageArgs = codeImageArgs(vendor, localImages);
     const codeArgs = [
       ...parts.slice(1),
       ...modelArgs,
       ...dirArgs,
+      ...imageArgs,
       ...streamArgs,
     ];
     const handleCliData = (c) => {
@@ -1525,6 +1988,23 @@ async function handleFolderTask({ message, channelId, tool, me, caps, cfg, deps,
         }
       }
     };
+    // The structured transports (ACP, codex's MCP server) produce events
+    // directly — there is no NDJSON on stdout for `resultParser` to read, so
+    // this is where THEIR usage joins the fold (0787). A stdout run never
+    // reaches here, and a structured run never reaches resultParser, so the two
+    // sources can't double-count the same tokens.
+    const handleCliEvent = (ev) => {
+      try {
+        emitter?.foldEvent(ev);
+      } catch {
+        /* a progress fold must never break the run */
+      }
+      try {
+        runUsage.push(ev);
+      } catch {
+        /* accounting must never break the run */
+      }
+    };
     try {
       const useAcpTransport = shouldUseAcpTransport({
         vendor,
@@ -1541,6 +2021,26 @@ async function handleFolderTask({ message, channelId, tool, me, caps, cfg, deps,
           codeArgs,
           codingCmd: cfg.codingCmd,
         });
+      // 0777: the two vendors that had no gate at all. Neither is an ACP
+      // adapter — each CLI turned out to have its own native seam (see the
+      // module headers), so both compose with everything already here.
+      const gateCodexPermissions =
+        !useAcpTransport &&
+        !useRuntimePermissionBridge &&
+        shouldGateCodexPermissions({
+          vendor,
+          runtimePermissions: caps.runtimePermissions,
+          codeArgs,
+        });
+      const gateClaudePermissions =
+        !useAcpTransport &&
+        !useRuntimePermissionBridge &&
+        !gateCodexPermissions &&
+        shouldGateClaudePermissions({
+          vendor,
+          runtimePermissions: caps.runtimePermissions,
+          codeArgs,
+        });
       if (useAcpTransport) {
         run = await deps.runAcpSession({
           cmd: parts[0],
@@ -1551,6 +2051,7 @@ async function handleFolderTask({ message, channelId, tool, me, caps, cfg, deps,
           signal,
           env: scrubHilosEnv(codingChildEnv(cfg) || process.env),
           onData: handleCliData,
+          onEvent: handleCliEvent,
           ...openCodePermissionCallbacks({
             tool,
             channelId,
@@ -1574,6 +2075,45 @@ async function handleFolderTask({ message, channelId, tool, me, caps, cfg, deps,
             threadRoot,
           }),
         });
+      } else if (gateCodexPermissions) {
+        run = await runCodexGatedSession({
+          deps,
+          cfg,
+          onGateDropped: () => noticeUngatedRun(parts[0]),
+          cmd: parts[0],
+          codeArgs,
+          cwd: folderPath,
+          prompt: memoryPreamble(workspaceMemory) + promptText,
+          model: resolvedModelId,
+          signal,
+          onData: handleCliData,
+          onEvent: handleCliEvent,
+          permissionCallbacks: openCodePermissionCallbacks({
+            tool,
+            channelId,
+            threadRoot,
+            provider: vendor,
+          }),
+        });
+      } else if (gateClaudePermissions) {
+        run = await runClaudeGatedCli({
+          deps,
+          cfg,
+          onGateDropped: () => noticeUngatedRun(parts[0]),
+          cmd: parts[0],
+          codeArgs,
+          prompt: memoryPreamble(workspaceMemory) + promptText,
+          cwd: folderPath,
+          signal,
+          onData: handleCliData,
+          resolveSessionId: () => emitter?.snapshot()?.sessionId ?? null,
+          permissionCallbacks: openCodePermissionCallbacks({
+            tool,
+            channelId,
+            threadRoot,
+            provider: vendor,
+          }),
+        });
       } else {
         run = await deps.runCli({
           cmd: parts[0],
@@ -1589,10 +2129,21 @@ async function handleFolderTask({ message, channelId, tool, me, caps, cfg, deps,
           onData: handleCliData,
         });
       }
+      // 0785 backstop. The notice normally goes out from `onGateDropped`,
+      // BEFORE the ungated child is spawned — the room has to be warned while
+      // the run can still be stopped, not told afterwards what it already did.
+      // This catches a degrade that reached us without firing that hook; the
+      // latch makes it a no-op in the ordinary case.
+      if (run?.permissionGateDropped) await noticeUngatedRun(parts[0]);
     } finally {
       stopHeartbeat();
+      stopPoller?.stop();
       if (emitter) {
         const errored = Boolean(run && (run.aborted || run.error || run.status !== 0));
+        // Remembered for the accounting-only settlement (0787): an exit with no
+        // report re-sends this same terminal state, so the card is never
+        // repainted into something it wasn't.
+        lastTerminalState = errored ? "error" : "done";
         let reason = "";
         if (errored && run && !run.aborted) {
           const stderrTail = oneLine((run.stderr || "").trim().split("\n").slice(-3).join(" "), 200);
@@ -1607,7 +2158,7 @@ async function handleFolderTask({ message, channelId, tool, me, caps, cfg, deps,
           /* ignore */
         }
         try {
-          await progressInflight;
+          await drainProgress();
         } catch {
           /* a drain failure must never break the run */
         }
@@ -1675,7 +2226,7 @@ async function handleFolderTask({ message, channelId, tool, me, caps, cfg, deps,
   };
 
   // --- Run ---
-  let runResult = await runFolderCli(folderTaskPrompt({ message, context, brief, folderPath }));
+  let runResult = await runFolderCli(folderTaskPrompt({ message, context, brief, folderPath, ...folderImagePromptArgs }));
   if (runResult.aborted) {
     await tool("post_message", {
       channelId,
@@ -1683,6 +2234,7 @@ async function handleFolderTask({ message, channelId, tool, me, caps, cfg, deps,
       broadcast: Boolean(threadRoot),
       body: `Stopped — I left \`${folderPath}\` as it was.`,
     });
+    await settleRunUsage(); // a stopped run still spent tokens (0787)
     return { status: "cancelled" };
   }
 
@@ -1705,6 +2257,7 @@ async function handleFolderTask({ message, channelId, tool, me, caps, cfg, deps,
       body = `The run didn't finish${why}${tail}. ${left} — mention me to retry.`;
     }
     await tool("post_message", { channelId, parentId: threadRoot, broadcast: Boolean(threadRoot), body });
+    await settleRunUsage(); // no report on this exit — settle the spend anyway (0787)
     return { status: "run-failed" };
   }
   if (!runResult.failed && isGit && !hasChanges(changed)) {
@@ -1714,13 +2267,22 @@ async function handleFolderTask({ message, channelId, tool, me, caps, cfg, deps,
       broadcast: Boolean(threadRoot),
       body: `The run finished but nothing changed in \`${folderPath}\`. Mention me to try a different approach.`,
     });
+    await settleRunUsage(); // "nothing changed" is not "nothing spent" (0787)
     return { status: "no-changes" };
   }
 
   // --- Report card + decision loop ---
   const postFolderReport = async (rr, ch) => {
     const report = buildReport(rr, ch);
-    const res = await tool("post_report", { channelId, parentId: threadRoot, broadcast: true, ...report });
+    const res = await tool("post_report", {
+      channelId,
+      parentId: threadRoot,
+      broadcast: true,
+      ...report,
+      // 0787 — a folder run has no runs row, so the receipt rides the card and
+      // the ledger row lands unattached to a run. Still the honest number.
+      ...reportUsageArgs(runUsage, { vendor: cliVendor, modelId: resolvedModelId }),
+    });
     return res?.messageId ?? null;
   };
   let reportMessageId = await postFolderReport(runResult, changed);
@@ -1735,11 +2297,12 @@ async function handleFolderTask({ message, channelId, tool, me, caps, cfg, deps,
       body: `Revising in \`${folderPath}\` with your feedback${decision.note ? `: ${decision.note}` : ""} (round ${round + 1}/${maxRounds}).`,
     });
     runResult = await runFolderCli(
-      folderTaskPrompt({ message, context, brief, folderPath }) +
+      folderTaskPrompt({ message, context, brief, folderPath, ...folderImagePromptArgs }) +
         `\n\nReviewer feedback to address: ${decision.note || "(see the channel)"}`,
     );
     if (runResult.aborted) {
       await tool("post_message", { channelId, parentId: threadRoot, broadcast: Boolean(threadRoot), body: `Stopped — I left \`${folderPath}\` as it was.` });
+      await settleRunUsage();
       return { status: "cancelled" };
     }
     changed = computeChanged();
@@ -1814,6 +2377,7 @@ async function handleFolderTask({ message, channelId, tool, me, caps, cfg, deps,
 
   if (decision.kind === "cancelled") {
     await tool("post_message", { channelId, parentId: threadRoot, broadcast: Boolean(threadRoot), body: `Stopped — the changes so far are still in \`${folderPath}\`.` });
+    await settleRunUsage();
     return { status: "cancelled" };
   }
 
@@ -1837,6 +2401,10 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   const deps = depsOverride ? { ...defaultDeps(), ...depsOverride } : defaultDeps();
   const git = deps.git;
   const signal = opts.signal;
+  // 0782 — the poll loop's hand-off for "a person pressed Stop on the card": it
+  // posts the notice naming them and aborts this job's signal, which is what
+  // tears the coding CLI's process group down (runCli's abort path).
+  const onStopRequested = opts.onStopRequested;
   // When the mention was a thread reply, keep the whole exchange in that thread.
   const parentId = message.parentId ?? null;
 
@@ -2051,6 +2619,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
           brief: routed.task,
           workspaceMemory,
           context,
+          onStopRequested,
         });
       }
       // Not a coding task → post the router's reply if it produced one, else fall
@@ -2409,6 +2978,11 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
         threadRootId: threadRoot,
         taskText: message.body,
         branch,
+        // 0782 — the mention we picked up. The server reads its human author and
+        // records them as the run's requester, which is who (besides workspace
+        // admins) may stop this run from its card. The thread root is NOT that
+        // person: it can be an ack this agent wrote, or someone else's thread.
+        requestedByMessageId: message.id,
         // Map an unrecognized command to null rather than the off-vocabulary
         // "unknown" — provider is documented as
         // claude_code|codex|cursor|opencode|antigravity|hermes|hilos.
@@ -2455,7 +3029,35 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   const streamOn = Boolean(caps.postProgress);
   const vendor = detectVendor(cfg.codingCmd);
   const streamArgs = codeStreamArgs(vendor);
+  // 0792 — the run's own record, when the operator asked for one. Three gates,
+  // all of which have to say yes: the operator's config, the server offering
+  // the tool, and a durable run row to hang the object off. The tap lives at
+  // TASK scope, not per-CLI-invocation, so a resume retry and the gate:true
+  // revision rounds all land in one transcript — the run is the unit, not the
+  // spawn.
+  const transcriptTap =
+    cfg.uploadTranscripts && caps.uploadTranscript && runId ? createTranscriptTap() : null;
+  // 0779 — screenshots the poll loop pulled to a temp dir at pickup. The prompt
+  // names them; the argv carries them for a vendor with a verified image flag.
+  const localImages = Array.isArray(message?.images) ? message.images : [];
+  const codeImagePromptArgs = localImages.length
+    ? {
+        images: localImages,
+        imagesReadable: imagesNeedReading(vendor, { gated: codexRunIsGated(cfg, caps) }),
+      }
+    : {};
+  // 0785 — one line per run, whichever CLI turns out to be ungateable.
+  const noticeUngatedRun = createUngatedRunNotice({
+    // Read at post time: the thread root is the ack this run posts.
+    post: (body) => tool("post_message", { channelId, parentId: threadRoot, body }),
+    log: console,
+  });
   let runSessionId = null; // captured from the stream for 0282 (resume)
+  // 0787 — what the run cost, folded across every runAndStage call (a gated
+  // iterate runs the CLI more than once) and taken at each report.
+  const runUsage = createUsageFold();
+  let resolvedModelId = pinnedModelId(cfg.codingCmd);
+  let lastTerminalState = "done";
   const machine = hostname();
 
   // Session resume (0282): on an ITERATE we can resume the coding agent's SESSION so
@@ -2466,8 +3068,11 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   // (get_active_run) with no local match means the session likely lives on another
   // machine/instance — a bad `--resume` id makes claude error → empty diff → a failed
   // run, so we DON'T resume and degrade to today's branch+feedback (never worse).
-  // claude_code + cursor + opencode have proven resume flags (0282/0573/0608);
-  // codex/unknown → []. The gate itself is pure (resumeDecision in resume.mjs):
+  // claude_code + cursor + opencode + codex have proven resume flags
+  // (0282/0573/0608/0783); unknown → []. Note codex's is a SUBCOMMAND (`exec
+  // resume <id>`), not a flag — it still splices in here, because flags placed
+  // before it are parsed as `exec`'s own (verified live on codex-cli 0.144.1).
+  // The gate itself is pure (resumeDecision in resume.mjs):
   // vendor, machine, project and server agreement all have to line up, and any
   // "no" degrades to the branch+feedback iterate rather than risking a bad id.
   const projectKey = codeProjectKey(vendor, repoPath, cfg.codingCmd);
@@ -2528,6 +3133,25 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       clearInterval(beat);
     };
   };
+  /**
+   * The authoritative check before anything leaves this machine (0782).
+   *
+   * The in-run poll stops when the CLI does, and the git work that follows —
+   * commit, push, `gh pr create` — can take a minute with nothing streaming. A
+   * stop that lands in THAT window would otherwise ship work nobody is waiting
+   * on. So we ask the server one more time, in the shape that changes nothing:
+   * `state` echoes the card's current lifecycle, and a stopped run's card is
+   * frozen server-side regardless. A stop here fires the same hand-off the
+   * heartbeat does (the room hears who stopped it; the job's signal aborts).
+   */
+  const stoppedBeforeShip = async (state = "done") => {
+    // Only the streaming card carries progress metadata. The legacy heartbeat's
+    // message is plain text, and stamping a lifecycle onto it would turn a
+    // status line into a run card — so that path simply has no pre-ship check.
+    if (!streamOn || !progressId) return false;
+    const sender = createProgressSender({ tool, statusId: progressId, runId, onStopRequested });
+    return await sender.poll(state);
+  };
   // Once the run ends, retire the "still working…" progress reply so it doesn't
   // sit there claiming the agent is alive. No-op when no beat ever fired (short
   // run) or without edit_message. Best-effort.
@@ -2537,6 +3161,25 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     }
   };
 
+  /**
+   * Accounting-only settlement (0787) — the repo lane's copy of the folder
+   * lane's. A run that ends with no report (no changes, a CLI that never
+   * started, a person pressing Stop, a self-committing agent under the gate)
+   * still spent tokens, and `post_progress` is the terminal, run-scoped call
+   * the daemon already makes on all of them. Only ever the DELTA, so calling it
+   * on a path that later reports anyway is harmless: the fold is already empty.
+   */
+  const settleRunUsage = async () => {
+    const args = reportUsageArgs(runUsage, { vendor, modelId: resolvedModelId, runId });
+    if (!args.usage || !progressId) return;
+    await tool("post_progress", {
+      messageId: progressId,
+      ...(runId ? { runId } : {}),
+      progress: { state: lastTerminalState },
+      usage: args.usage,
+    }).catch(() => {});
+  };
+
   const parts = cfg.codingCmd.split(" ").filter(Boolean);
   // Run the CLI and stage everything it changed; return the diff stats (no post).
   // Workspace memory (the project's soul) is prepended so the coding agent has
@@ -2556,7 +3199,9 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     // when post_report settles the report, it would re-write metadata WITHOUT the
     // report (it read the pre-settle snapshot) and clobber it. Draining every send
     // here guarantees no progress write is in flight once we settle.
-    let progressInflight = Promise.resolve();
+    let drainProgress = async () => {};
+    // 0782 — the silent-work stop poll, torn down in the same finally as the run.
+    let stopPoller = null;
     if (streamOn) {
       if (!progressId) {
         try {
@@ -2571,27 +3216,35 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
         }
       }
       const statusId = progressId;
-      if (statusId) {
-        emitter = createProgressEmitter({
-          parser: makeStreamParser(vendor),
-          now: deps.now,
-          throttleMs: cfg.progressMs,
-          // The module never imports MCP — the send fn is injected here. It must
-          // never throw into the run (createProgressEmitter also guards).
-          send: (p) => {
-            try {
-              const r = tool("post_progress", { messageId: statusId, progress: p });
-              if (r && typeof r.then === "function") {
-                const done = r.then(() => {}, () => {});
-                progressInflight = Promise.all([progressInflight, done]).then(
-                  () => {},
-                  () => {},
-                );
-              }
-            } catch {
-              /* a progress send must never break the run */
-            }
-          },
+      // The module never imports MCP — the send fn is injected here. It must
+      // never throw into the run (createProgressEmitter also guards). 0782:
+      // the sender also carries the stop signal home on this same beat, bound
+      // to THIS run's id so a stop can't be read off a neighbouring thread.
+      const sender = statusId
+        ? createProgressSender({ tool, statusId, runId, onStopRequested })
+        : null;
+      // The emitter is built whether or not the status card posted (0787). The
+      // stream flags are already on the argv either way, so the CLI is speaking
+      // NDJSON regardless; gating the parser on a card meant one transient
+      // post_message failure silently cost the run its session id (the resume
+      // record's only source on an argv run) and its usage. A card is where
+      // progress is SHOWN, never how the stream is read — this is what the
+      // folder path has always done. With no card the sends are dropped on the
+      // floor rather than skipped, so nothing else in the run changes shape.
+      emitter = createProgressEmitter({
+        parser: makeStreamParser(vendor),
+        now: deps.now,
+        throttleMs: cfg.progressMs,
+        send: sender ? sender.send : () => {},
+      });
+      if (sender) {
+        drainProgress = () => sender.drain();
+        // The heartbeat only fires when the CLI speaks. This asks anyway, so a
+        // run inside one long silent command (a full test suite, a slow install)
+        // is still stoppable from the room.
+        stopPoller = createStopPoller({
+          poll: () => sender.poll("working"),
+          intervalMs: cfg.stopPollMs || STOP_POLL_MS,
         });
       }
     } else {
@@ -2605,10 +3258,15 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     // fallback) suppresses it. buildResumeArgs is [] unless vendor+session make
     // resume safe, so a non-resume run is byte-identical to the pre-0282 ARGV.
     const resumeArgs = resume ? buildResumeArgs(vendor, resumeSessionId) : [];
-    // Model preset (0504): resolved at run time against the CLI's own model
-    // list (cursor only today) — [] when unset/unresolvable, so the tool's
-    // default stands. Inserted before resume/stream flags, after the base.
+    // Model preset (0504, codex in 0783): resolved at run time against the
+    // CLI's own model list — [] when unset/unresolvable, so the tool's default
+    // stands. Inserted before resume/stream flags, after the base — an order
+    // codex depends on, since its resume is a subcommand and the model flag
+    // has to reach `exec`, i.e. sit BEFORE `resume`.
     const modelArgs = await modelArgsFor(cfg, vendor);
+    // 0787: remember the id we actually handed the CLI — the usage receipt for
+    // a vendor whose stream never names a model (codex) has nothing else to say.
+    if (modelArgs[0] === "--model" && modelArgs[1]) resolvedModelId = modelArgs[1];
     // Project pin (0608, opencode only): the CLI resolves its project from PWD,
     // not the spawn cwd, and its sessions are per project — `--dir` makes both
     // deterministic. [] for every other vendor (and for an `--attach`ed run,
@@ -2616,13 +3274,29 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     // The spawned PWD now matches the cwd too (0615); `--dir` stays as the
     // CLI's own explicit contract, and to keep attach runs off our local path.
     const dirArgs = codeDirArgs(vendor, repoPath, cfg.codingCmd);
+    // 0779: BEFORE resumeArgs, for the same reason modelArgs are — codex's
+    // resume is a SUBCOMMAND (`exec resume <id>`) and `--image=` belongs to
+    // `exec`, so it has to sit ahead of it. [] for every vendor without a
+    // verified flag, leaving their argv byte-identical to before.
+    const imageArgs = codeImageArgs(vendor, localImages);
     const codeArgs = streamOn
-      ? [...parts.slice(1), ...modelArgs, ...dirArgs, ...resumeArgs, ...streamArgs]
-      : [...parts.slice(1), ...modelArgs, ...dirArgs, ...resumeArgs];
+      ? [...parts.slice(1), ...modelArgs, ...dirArgs, ...imageArgs, ...resumeArgs, ...streamArgs]
+      : [...parts.slice(1), ...modelArgs, ...dirArgs, ...imageArgs, ...resumeArgs];
     const handleCliData = (c) => {
       // Keep tracking lastLine as a fallback (legacy heartbeat / honesty).
       const lines = String(c).split("\n").map((s) => s.trim()).filter(Boolean);
       if (lines.length) lastLine = lines[lines.length - 1];
+      // 0792 — the raw tail, before the parser reduces it to eight steps. Every
+      // transport routes its child's stdout through this one callback, so the
+      // tap sees an argv run, a permission-bridged run, and an ACP session
+      // alike; a transport that writes nothing to stdout simply leaves it empty.
+      if (transcriptTap) {
+        try {
+          transcriptTap.push(c);
+        } catch {
+          /* keeping a record must never break the run */
+        }
+      }
       if (emitter) {
         try {
           emitter.feed(c);
@@ -2631,6 +3305,24 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
         }
       }
     };
+    // The structured transports (ACP, `codex mcp-server`) put only the
+    // assistant's PROSE on stdout — every tool call travels here instead. The
+    // live card has always read this; the transcript has to as well, or a gated
+    // run uploads a page of narration with no execution anywhere in it.
+    const handleCliEvent = (ev) => {
+      if (transcriptTap) {
+        try {
+          transcriptTap.pushEvent(ev);
+        } catch {
+          /* keeping a record must never break the run */
+        }
+      }
+      try {
+        emitter?.foldEvent(ev);
+      } catch {
+        /* a progress fold must never break the run */
+      }
+    };
     let run;
     try {
       // OpenCode's own non-interactive CLI auto-rejects every permission ask
@@ -2643,7 +3335,6 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
         runtimePermissions: caps.runtimePermissions,
         codeArgs,
         codingCmd: cfg.codingCmd,
-        resumeSessionId: resume ? resumeSessionId : null,
       });
       const useRuntimePermissionBridge =
         !useAcpTransport &&
@@ -2653,16 +3344,41 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
           codeArgs,
           codingCmd: cfg.codingCmd,
         });
+      // 0777, and the reason it composes with resume (0778): claude keeps its
+      // ordinary argv run (resumeArgs included), and codex's gated transport
+      // has its OWN resume — `codex-reply {threadId}` — so a gated iterate
+      // continues the same thread instead of trading continuity for a gate.
+      const gateCodexPermissions =
+        !useAcpTransport &&
+        !useRuntimePermissionBridge &&
+        shouldGateCodexPermissions({
+          vendor,
+          runtimePermissions: caps.runtimePermissions,
+          codeArgs,
+        });
+      const gateClaudePermissions =
+        !useAcpTransport &&
+        !useRuntimePermissionBridge &&
+        !gateCodexPermissions &&
+        shouldGateClaudePermissions({
+          vendor,
+          runtimePermissions: caps.runtimePermissions,
+          codeArgs,
+        });
       if (useAcpTransport) {
         run = await deps.runAcpSession({
           cmd: parts[0],
           vendor,
           cwd: repoPath,
           prompt: memoryPreamble(workspaceMemory) + promptText,
+          // 0778: approvals AND continuity. `resume:false` (the never-worse
+          // retry) drops it exactly like buildResumeArgs does.
+          resumeSessionId: resume ? resumeSessionId : null,
           timeoutMs: cfg.runTimeoutMs,
           signal,
           env: scrubHilosEnv(codingChildEnv(cfg) || process.env),
           onData: handleCliData,
+          onEvent: handleCliEvent,
           ...openCodePermissionCallbacks({
             tool,
             channelId,
@@ -2691,8 +3407,59 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
             runId,
           }),
         });
+      } else if (gateCodexPermissions) {
+        run = await runCodexGatedSession({
+          deps,
+          cfg,
+          onGateDropped: () => noticeUngatedRun(parts[0]),
+          cmd: parts[0],
+          codeArgs,
+          cwd: repoPath,
+          prompt: memoryPreamble(workspaceMemory) + promptText,
+          model: resolvedModelId,
+          // Codex's own resume over this transport. `resume:false` (the
+          // never-worse retry) drops it exactly like buildResumeArgs does.
+          resumeThreadId: resume ? resumeSessionId : null,
+          signal,
+          onData: handleCliData,
+          onEvent: handleCliEvent,
+          permissionCallbacks: openCodePermissionCallbacks({
+            tool,
+            channelId,
+            threadRoot,
+            runId,
+            provider: vendor,
+          }),
+        });
+      } else if (gateClaudePermissions) {
+        run = await runClaudeGatedCli({
+          deps,
+          cfg,
+          onGateDropped: () => noticeUngatedRun(parts[0]),
+          cmd: parts[0],
+          // codeArgs already carries this run's resume flags, so a gated
+          // iterate resumes AND raises cards — the two never traded off.
+          codeArgs,
+          prompt: memoryPreamble(workspaceMemory) + promptText,
+          cwd: repoPath,
+          signal,
+          onData: handleCliData,
+          sessionId: resume ? resumeSessionId ?? "" : "",
+          resolveSessionId: () => emitter?.snapshot()?.sessionId ?? null,
+          permissionCallbacks: openCodePermissionCallbacks({
+            tool,
+            channelId,
+            threadRoot,
+            runId,
+            provider: vendor,
+          }),
+        });
       } else {
-        run = await runCli({
+        // deps.runCli, not the bare import: `defaultDeps` wraps the very same
+        // function, so production is byte-identical, but the ungated repo run
+        // was the ONE coding path that escaped the injectable runner — which is
+        // why nothing above the unit tests could ever drive it (0787).
+        run = await deps.runCli({
           cmd: parts[0],
           args: [...codeArgs, memoryPreamble(workspaceMemory) + promptText],
           cwd: repoPath,
@@ -2703,8 +3470,12 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
           onData: handleCliData,
         });
       }
+      // 0785 — the gate was expected here and the CLI couldn't hold it. Say so
+      // in the room, once per run, rather than only in the daemon's console.
+      if (run?.permissionGateDropped) await noticeUngatedRun(parts[0]);
     } finally {
       stopHeartbeat();
+      stopPoller?.stop();
       if (run?.sessionId) runSessionId = run.sessionId;
       if (emitter) {
         // Terminal state: flip the status card off "working" (state 'done'/'error')
@@ -2713,6 +3484,9 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
         // (0289) — the card cross-fades run → report; for no-changes/failed/gate
         // outcomes this terminal 'done'/'error' is the card's final state.
         const errored = Boolean(run && (run.aborted || run.error || run.status !== 0));
+        // Remembered so an exit with no report re-sends this same state (0787)
+        // rather than repainting the card into something it wasn't.
+        lastTerminalState = errored ? "error" : "done";
         // On error, carry an honest reason onto the card (0294) — the same signal
         // the chat note uses: spawn error message, else exit status, plus a short
         // stderr tail. Sanitized again server-side; an old server just drops it.
@@ -2737,7 +3511,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
         // BEFORE runAndStage returns, so nothing is in flight when the caller
         // settles the report onto this card — no lost-update clobber (0289).
         try {
-          await progressInflight;
+          await drainProgress();
         } catch {
           /* a drain failure must never break the run */
         }
@@ -2747,6 +3521,15 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
         } catch {
           /* ignore */
         }
+        // 0787 — read the run's cost AFTER done() (the terminal usage frame
+        // usually arrives in the parser flush). Folded, not sent yet: the
+        // report call is what carries it home.
+        try {
+          const spend = emitter.usage?.();
+          if (spend) runUsage.push({ t: "usage", ...spend });
+        } catch {
+          /* accounting must never break the run */
+        }
       }
     }
     if (run.aborted || signal?.aborted) {
@@ -2814,8 +3597,9 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
           sessionId: sid,
           machine,
           // The CLI that created the session (a `ses_…` is meaningless to
-          // claude's `--resume`) and the project it belongs to — opencode
-          // scopes sessions per project. The gate above requires both (0608).
+          // claude's `--resume`) and the project it belongs to — opencode and
+          // codex both scope sessions per project. The gate above requires
+          // both (0608, 0783).
           vendor,
           cwd: projectKey,
           updatedAt: new Date().toISOString(),
@@ -2826,6 +3610,32 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     }
   };
 
+  // 0792 — ship the run's record, AFTER its report. Ordering is the whole
+  // point: the transcript is a fact about finished work, and the card it marks
+  // has to exist before it can be marked. Best-effort in every direction — no
+  // tap, no stream, no server tool, or a refused upload all leave the run
+  // exactly as it would have ended without this feature.
+  let transcriptUploaded = false;
+  const uploadTranscript = async (reportMsgId) => {
+    if (!transcriptTap || !runId || transcriptUploaded) return;
+    let text = "";
+    try {
+      text = transcriptTap.text();
+    } catch {
+      return;
+    }
+    // Nothing to say: a transport that never wrote to stdout (an ACP session, a
+    // vendor with no stream) has no transcript, and an empty upload is worse
+    // than none — it would put an empty object behind a Transcript control.
+    if (!text) return;
+    transcriptUploaded = true;
+    await tool("upload_run_transcript", {
+      runId,
+      transcript: text,
+      ...(reportMsgId ? { messageId: reportMsgId } : {}),
+    }).catch(() => {});
+  };
+
   // Post a proposal card (approve-before-push mode) from a staged change.
   const postProposal = async (staged) => {
     const report = buildProposalReport({
@@ -2839,7 +3649,16 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       stat: staged.stat,
       runFailed: staged.runFailed,
     });
-    const res = await tool("post_report", { channelId, parentId: threadRoot, broadcast: true, ...report });
+    const res = await tool("post_report", {
+      channelId,
+      parentId: threadRoot,
+      broadcast: true,
+      ...report,
+      // 0787 — the proposal card is where a gated run's spend lands, because
+      // it is the card the run produced. The later "Shipped" report carries
+      // only what the CLI spent AFTER this one (usually nothing).
+      ...reportUsageArgs(runUsage, { vendor, modelId: resolvedModelId, runId }),
+    });
     return { reportMessageId: res?.messageId ?? null, stat: staged.stat };
   };
 
@@ -2878,6 +3697,9 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       body,
     });
     await updateChannelMarker(compactRunMarker("cancelled", branch));
+    // Every repo-lane cancel funnels through here, so one settle covers them
+    // all: a stopped run still spent tokens (0787).
+    await settleRunUsage();
     return { status: "cancelled", branch };
   };
 
@@ -2906,7 +3728,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
 
   const codePrompt =
     (teamMemoryBlock ? teamMemoryBlock + "\n\n" : "") +
-    codeTaskPrompt({ message, context, brief: routed.task, repoFullName });
+    codeTaskPrompt({ message, context, brief: routed.task, repoFullName, ...codeImagePromptArgs });
   let staged = await runAndStage(codePrompt);
   if (staged.aborted) return await postStopped();
   // Never-worse-than-today (0282): if we RESUMED a session and that run FAILED (a
@@ -2945,11 +3767,13 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       });
       await finalizeProgress(`\`${branch}\` has the agent's own commits — needs review.`);
       await updateChannelMarker(compactRunMarker("changes", branch));
+      await settleRunUsage(); // no report on this exit (0787)
       return { status: "self-committed-gated", branch };
     }
     // When a live status card was streaming, settle the report onto it (0289) —
     // the card cross-fades run → report. Skip finalizeProgress then (it edits the
     // card's body, which the settle overwrites with the report anyway).
+    if (signal?.aborted || (await stoppedBeforeShip())) return await postStopped();
     const selfSettleId = streamOn && progressId ? progressId : null;
     if (!selfSettleId) await finalizeProgress(`Agent shipped \`${branch}\` itself — report below.`);
     const selfResult = await shipSelfDriven({
@@ -2964,8 +3788,10 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       parentId: threadRoot,
       settleId: selfSettleId,
       runId,
+      usageArgs: reportUsageArgs(runUsage, { vendor, modelId: resolvedModelId, runId }),
     });
     await recordSession(selfResult.prUrl);
+    await uploadTranscript(selfResult.reportMsgId);
     await updateChannelMarker(compactRunMarker(selfResult.status, selfResult.branch));
     return selfResult;
   }
@@ -3003,6 +3829,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     await updateChannelMarker(
       compactRunMarker(staged.failed ? "run-failed" : "no-changes", branch),
     );
+    await settleRunUsage(); // "no changes" is not "no spend" (0787)
     return { status: staged.failed ? "run-failed" : "no-changes" };
   }
 
@@ -3011,7 +3838,9 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   // propose-a-diff-and-wait flow for users who want approve-before-push.
   if (!cfg.gate) {
     // A "stop" that lands between the run finishing and the ship must still win.
-    if (signal?.aborted) return await postStopped();
+    // The signal covers a stop we already heard; the server check covers one that
+    // landed while the CLI was silent and nothing was carrying it home.
+    if (signal?.aborted || (await stoppedBeforeShip())) return await postStopped();
     // Seamless single card (0289): when a live status card streamed this run,
     // settle the report onto it in place instead of posting a separate report
     // message. Only the DEFAULT gate:false report settles in place; gate:true's
@@ -3035,6 +3864,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       existingPrUrl: continuingPrUrl,
       settleId,
       runId,
+      usageArgs: reportUsageArgs(runUsage, { vendor, modelId: resolvedModelId, runId }),
     });
     // The settle already flipped the card to the report (body + metadata); editing
     // the body again would clobber the report summary, so only finalize when we
@@ -3043,6 +3873,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     // Re-record with the now-known PR url so the local session record + the run row
     // carry the PR the session belongs to (best-effort; session id unchanged).
     await recordSession(result.prUrl);
+    await uploadTranscript(result.reportMsgId);
     await updateChannelMarker(compactRunMarker(result.status, result.branch));
     return { ...result, stat: staged.stat, sessionId: runSessionId };
   }
@@ -3079,7 +3910,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   }
 
   // A stop during the final wait, too — don't ship a cancelled run.
-  if (signal?.aborted) return await postStopped();
+  if (signal?.aborted || (await stoppedBeforeShip())) return await postStopped();
   const result = await applyDecision({
     decision,
     repoPath,
@@ -3095,9 +3926,15 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     parentId: threadRoot,
     existingPrUrl: continuingPrUrl,
     runId,
+    // Normally {} — a gated run already reported its spend on the proposal card
+    // it is now shipping. Anything the CLI spent after that still comes home.
+    usageArgs: reportUsageArgs(runUsage, { vendor, modelId: resolvedModelId, runId }),
   });
   await finalizeProgress(`Done on \`${branch}\` — see the report below.`);
   await recordSession(result.prUrl);
+  // The gated lane's shipped report is a fresh message; `result.reportMsgId`
+  // names it, and the proposal card is the fallback when it never posted.
+  await uploadTranscript(result.reportMsgId || proposal.reportMessageId);
   await updateChannelMarker(compactRunMarker(result.status, result.branch));
   return { ...result, reportMessageId: proposal.reportMessageId, stat: proposal.stat, rounds: round, sessionId: runSessionId };
   } finally {