hilos-agent 0.5.1 → 0.7.0

package/README.md

@@ -1,6 +1,6 @@
 # hilos-agent
 
-Run **your own** coding agent — Claude Code, Codex, Cursor, Hermes, or any command — as
+Run **your own** coding agent — Claude Code, Codex, Cursor, opencode, Hermes, or any command — as
 an autonomous teammate inside a [hilos](https://hilos.sh) channel.
 
 It connects to hilos over MCP, watches for `@mentions` of your agent in a
@@ -42,7 +42,8 @@ Running from elsewhere, or want to map several repos explicitly? Use a config:
   "url": "https://hilos.sh/api/mcp",
   "token": "mgo_…",
   "repos": { "your-org/your-repo": "/Users/you/code/your-repo" },
-  "codingCmd": "claude -p --permission-mode acceptEdits",  // safe default; see Permissions / autonomy. or "codex exec", "cursor-agent -p --output-format text", "agy -p", any command
+  "codingCmd": "claude -p --permission-mode acceptEdits",  // safe default; see Permissions / autonomy. or "codex exec", "cursor-agent -p --output-format text --trust", "opencode run", "agy -p", any command
+  "codingModel": "",  // model preset tier ("opus" | "sonnet" | "haiku") resolved at run time against the CLI's own model list (Cursor only today); "" = the tool's default
   "chatCmd": "",  // FAST command for chat replies + the plan-ack. Empty = derived from codingCmd's tool (codex daemons chat with codex, etc.); set to override
   "defaultBranch": "main",
   "gate": false,               // default: open a PR directly. true = approve-before-push
@@ -186,6 +187,14 @@ explains what each permission level means.
 `codingCmd` decides how much the coding agent can do on its own. Three levels,
 safest first:
 
+- **`opencode run` (runtime-gated).** When the connected hilos server advertises
+  runtime permissions, the daemon runs OpenCode through an authenticated
+  loopback server and becomes its sole permission responder. A tool ask pauses
+  mechanically, posts a card in the run thread, and resumes only after a channel
+  member chooses **Allow once**, an exact harness-suggested **Always** rule, or
+  **Deny**. Missing transport, expiry, and cancellation all reject the tool
+  call. `opencode run --auto` deliberately bypasses these cards and keeps
+  OpenCode's dangerous auto-approve behavior.
 - **`--permission-mode acceptEdits` (default).** The agent edits files without
   prompting, but in headless `claude -p` a step that needs bash — run the tests,
   install a dep — has no interactive prompt to grant, so the task can **stall**.
@@ -207,7 +216,10 @@ safest first:
 
 The default stays `acceptEdits`. Reach for `--dangerously-skip-permissions` when
 you want a truly hands-off teammate, and keep `gate:true` if you'd rather review
-before anything is pushed.
+before anything is pushed. OpenCode is the first harness with the runtime-card
+bridge; Claude Code, Codex, Cursor, and other adapters still follow their own
+CLI permission modes until their native approval hooks join the same
+vendor-neutral hilos substrate.
 
 ## Hooks — stream a raw Claude Code session
 

package/bin/hilos-agent.mjs

@@ -16,10 +16,18 @@
 // codingCmd in hilos-agent.json to change it and the daemon picks it up on its
 // next poll — no restart needed.
 
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
 import { resolveConfig, decodeJoin, writeStarterConfig, GLOBAL_CONFIG } from "../src/config.mjs";
 import { run } from "../src/run.mjs";
 import { hookMain, hooksMain } from "../src/hook.mjs";
 
+function packageVersion() {
+  const pkgPath = fileURLToPath(new URL("../package.json", import.meta.url));
+  return JSON.parse(readFileSync(pkgPath, "utf8")).version;
+}
+
 function parseArgs(argv) {
   const flags = {};
   const positional = [];
@@ -31,12 +39,14 @@ function parseArgs(argv) {
     else if (a === "--url") flags.url = argv[++i];
     else if (a === "--token") flags.token = argv[++i];
     else if (a === "--coding-cmd") flags.codingCmd = argv[++i];
+    else if (a === "--coding-model") flags.codingModel = argv[++i];
     else if (a === "--chat-cmd") flags.chatCmd = argv[++i];
     else if (a === "--once") flags.once = true;
     else if (a === "--backfill") flags.backfill = true;
     else if (a === "--no-gate") flags.gate = false;
     else if (a === "--global") flags.global = true;
     else if (a === "-h" || a === "--help") flags.help = true;
+    else if (a === "-v" || a === "--version") flags.version = true;
     else positional.push(a);
   }
   return { cmd: positional[0] || "run", flags, positional };
@@ -56,20 +66,29 @@ Options:
   --channel <id>     watch only one channel (per-channel override)
   --config <path>    use a specific config file
   --coding-cmd <cmd> the coding agent to run — claude -p, codex exec,
-                     cursor-agent -p, agy -p, hermes, or any command that
-                     takes a prompt as its last arg (default: "claude -p")
+                     cursor-agent -p --trust, opencode run, agy -p, hermes,
+                     or any command
+                     that takes a prompt as its last arg (default: "claude -p")
+  --coding-model <tier>  model preset tier (opus | sonnet | haiku) resolved at
+                     run time against the CLI's own model list — never a baked
+                     id (Cursor only today; default: the tool's own model)
   --chat-cmd <cmd>   fast command for chat replies + the plan-ack (default:
                      derived from the coding command, so a Codex or Cursor
                      daemon chats with its own tool)
   --once             one poll then exit (cron-friendly)
   --backfill         also act on mentions that predate startup
   --no-gate          propose only; don't wait for approval / push
+  -v, --version      print the installed version
   -h, --help         this help
 
 Docs: https://hilos.sh  ·  https://www.npmjs.com/package/hilos-agent`;
 
 async function main() {
   const { cmd, flags, positional } = parseArgs(process.argv.slice(2));
+  if (flags.version || cmd === "version") {
+    console.log(packageVersion());
+    return;
+  }
   if (flags.help || cmd === "help") {
     console.log(HELP);
     return;
@@ -98,6 +117,7 @@ async function main() {
     // non-Claude connect command doesn't write the Claude default over it.
     const starter = { ...(joinPayload || {}) };
     if (flags.codingCmd) starter.codingCmd = flags.codingCmd;
+    if (flags.codingModel) starter.codingModel = flags.codingModel;
     const path = writeStarterConfig(joinPayload ? GLOBAL_CONFIG : flags.config, starter);
     console.log(`Wrote ${path}.`);
     console.log(joinPayload ? "Token + endpoint set from your link." : "Fill in token + repos, then run `hilos-agent`.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hilos-agent",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Run your own coding agent (Claude Code / Codex / Cursor) as an autonomous teammate in a hilos channel. Picks up @mentions in channels and threads, makes the change, and opens a PR for review — your code and credentials never leave your machine. (Approve-before-push is available via gate:true.)",
   "type": "module",
   "bin": {

package/src/agent-events.mjs

@@ -1,9 +1,11 @@
 // Normalized vendor stream parser (0272). The KEYSTONE of the "Agents feel
 // alive" epic: coding CLIs each narrate their work in a different, unstable
 // wire format (Claude Code emits `--output-format stream-json` NDJSON, Codex
-// emits `--json` item events, Cursor emits unstructured text). This module turns
-// any of them into ONE small, typed `AgentEvent` stream the UI can render as a
-// live "what the agent is doing right now" card.
+// emits `--json` item events, Cursor emits its own `--output-format
+// stream-json` NDJSON — 0573, opencode emits `--format json` part events —
+// 0608). This module turns any of them into ONE small,
+// typed `AgentEvent` stream the UI can render as a live "what the agent is
+// doing right now" card.
 //
 // Design rules that make this safe to point at an untrusted, evolving CLI:
 //   - PURE + dependency-free (node builtins only) so it stands alone and is
@@ -207,12 +209,184 @@ function parseCodexLine(line) {
   }
 }
 
+/**
+ * Parse ONE Cursor `--output-format stream-json` NDJSON line → AgentEvent[].
+ * Shapes captured LIVE against cursor-agent 2026.07.23 (ticket 0572's audit):
+ * a `system`/`init` envelope with `session_id` (the `--resume` id — 0573),
+ * `assistant` turns whose message.content carries text blocks (tool calls
+ * arrive as separate events, unlike Claude's inline tool_use), `tool_call`
+ * started/completed envelopes keyed by kind (`editToolCall`/`readToolCall`/
+ * `shellToolCall`, each with an `args` object), and a terminal `result` with
+ * `is_error` + the full text in `result`. `thinking` deltas, the `user` echo,
+ * and `tool_call` completions are deliberately not steps.
+ */
+function parseCursorLine(line) {
+  const obj = tryParse(line);
+  if (!obj) return [];
+  if (obj.type === "system" && typeof obj.session_id === "string") {
+    return [{ t: "session", sessionId: sanitizeText(obj.session_id) }];
+  }
+  if (obj.type === "result") {
+    const ok = obj.is_error !== true && obj.subtype !== "error";
+    const summary = typeof obj.result === "string" ? sanitizeText(obj.result) : undefined;
+    return [summary ? { t: "result", ok, summary } : { t: "result", ok }];
+  }
+  // Only `started` — the `completed` twin repeats the same call and would
+  // double every step.
+  if (obj.type === "tool_call" && obj.subtype === "started") {
+    const ev = cursorToolEvent(obj.tool_call);
+    return ev ? [ev] : [];
+  }
+  if (obj.type === "assistant" && obj.message && Array.isArray(obj.message.content)) {
+    const out = [];
+    for (const block of obj.message.content) {
+      if (block && block.type === "text" && typeof block.text === "string") {
+        const text = sanitizeText(block.text.replace(/\s+/g, " ").trim());
+        if (text) out.push({ t: "note", text });
+      }
+    }
+    return out;
+  }
+  return [];
+}
+
+/** One Cursor tool_call envelope → an AgentEvent, or null. The envelope holds a
+ *  single `<kind>ToolCall` key; grep/ls/etc. carry less "alive" signal and are
+ *  skipped, mirroring toolKind()'s v1 restraint — an unknown kind never crashes. */
+function cursorToolEvent(toolCall) {
+  if (!toolCall || typeof toolCall !== "object") return null;
+  for (const [key, val] of Object.entries(toolCall)) {
+    if (!key.endsWith("ToolCall") || !val || typeof val !== "object") continue;
+    const args = val.args && typeof val.args === "object" ? val.args : {};
+    if (key === "shellToolCall" || key === "terminalToolCall") {
+      const cmd = typeof args.command === "string" ? args.command.replace(/\s+/g, " ").trim() : "";
+      return { t: "run", cmd: sanitizeText(cmd) };
+    }
+    if (key === "editToolCall" || key === "writeToolCall") {
+      return { t: "edit", path: typeof args.path === "string" ? sanitizeText(args.path) : "" };
+    }
+    if (key === "readToolCall") {
+      return { t: "read", path: typeof args.path === "string" ? sanitizeText(args.path) : "" };
+    }
+    return null;
+  }
+  return null;
+}
+
+/** One opencode `tool_use` part → an AgentEvent, or null. Tool names are
+ *  lowercase (`read`/`write`/`edit`/`patch`/`bash`); the arguments live under
+ *  `state.input` (`filePath` for file tools, `command` for bash). Anything else
+ *  (glob/grep/webfetch/task) carries less "alive" signal and is skipped, mirroring
+ *  toolKind()'s v1 restraint — an unknown tool never crashes the parser. */
+function opencodeToolEvent(part) {
+  if (!part || typeof part !== "object") return null;
+  const tool = typeof part.tool === "string" ? part.tool.toLowerCase() : "";
+  const state = part.state && typeof part.state === "object" ? part.state : {};
+  const input = state.input && typeof state.input === "object" ? state.input : {};
+  if (tool === "bash") {
+    const raw = input.command;
+    const cmd = typeof raw === "string" ? raw.replace(/\s+/g, " ").trim() : "";
+    return { t: "run", cmd: sanitizeText(cmd) };
+  }
+  if (tool === "write" || tool === "edit" || tool === "patch" || tool === "multiedit") {
+    const raw = input.filePath ?? input.file_path ?? input.path;
+    return { t: "edit", path: typeof raw === "string" ? sanitizeText(raw) : "" };
+  }
+  if (tool === "read") {
+    const raw = input.filePath ?? input.file_path ?? input.path;
+    return { t: "read", path: typeof raw === "string" ? sanitizeText(raw) : "" };
+  }
+  return null;
+}
+
+/**
+ * A stateful line parser for opencode `run --format json` NDJSON (0608).
+ *
+ * Shapes captured LIVE against opencode 1.18.5: EVERY event carries a top-level
+ * `sessionID` (`ses_…`) — including the very first `step_start` and the terminal
+ * `error` — which is exactly the id `--session` resumes. `text` events carry a
+ * WHOLE text part (`part.text`), not a delta, so a part is emitted once and a
+ * repeat of the same `part.id` with identical text is dropped (a growing part
+ * re-emits, so the room still sees the latest wording). `tool_use` events carry
+ * the tool + its input; they're deduped by `callID` so a state update can't
+ * double a step. `step_finish` closes an assistant turn (`part.reason`): `stop`
+ * ends the run, so it becomes the `result` carrying the last text as the summary
+ * (opencode has no separate result event, and the folder-run report reads that
+ * summary). `error` (`{ error: { name, data: { message } } }`) → a failed result.
+ *
+ * Stateful (last text, seen part/call ids) — hence a factory, not a bare fn.
+ */
+function makeOpencodeLineParser() {
+  const seenText = new Map(); // part.id → last emitted text
+  const seenCalls = new Set(); // tool callID
+  let sessionSeen = false;
+  let lastText = "";
+  return function parseOpencodeLine(line) {
+    const obj = tryParse(line);
+    if (!obj) return [];
+    const out = [];
+    // The session id rides on every event; emit it once, off whichever lands first.
+    if (!sessionSeen && typeof obj.sessionID === "string" && obj.sessionID) {
+      sessionSeen = true;
+      out.push({ t: "session", sessionId: sanitizeText(obj.sessionID) });
+    }
+    const part = obj.part && typeof obj.part === "object" ? obj.part : {};
+    switch (obj.type) {
+      case "text": {
+        const text = typeof part.text === "string" ? sanitizeText(part.text.replace(/\s+/g, " ").trim()) : "";
+        if (!text) break;
+        const id = typeof part.id === "string" ? part.id : "";
+        if (id && seenText.get(id) === text) break; // same part, same text → not news
+        if (id) {
+          seenText.set(id, text);
+          if (seenText.size > 200) seenText.delete(seenText.keys().next().value); // bound
+        }
+        lastText = text;
+        out.push({ t: "note", text });
+        break;
+      }
+      case "tool_use": {
+        const callId = typeof part.callID === "string" ? part.callID : "";
+        if (callId && seenCalls.has(callId)) break; // status updates repeat the call
+        if (callId) {
+          seenCalls.add(callId);
+          if (seenCalls.size > 500) seenCalls.delete(seenCalls.values().next().value); // bound
+        }
+        const ev = opencodeToolEvent(part);
+        if (ev) out.push(ev);
+        break;
+      }
+      case "step_finish": {
+        // Only the turn that stops ends the RUN; `tool-calls` means another
+        // assistant turn follows.
+        if (part.reason === "stop") {
+          out.push(lastText ? { t: "result", ok: true, summary: lastText } : { t: "result", ok: true });
+        }
+        break;
+      }
+      case "error": {
+        const err = obj.error && typeof obj.error === "object" ? obj.error : {};
+        const data = err.data && typeof err.data === "object" ? err.data : {};
+        const raw = typeof data.message === "string" ? data.message : typeof err.name === "string" ? err.name : "";
+        const summary = sanitizeText(raw);
+        out.push(summary ? { t: "result", ok: false, summary } : { t: "result", ok: false });
+        break;
+      }
+      default:
+        break;
+    }
+    return out;
+  };
+}
+
 /** claude / claude_code / claude-code all mean the Claude parser. */
 function normalizeVendor(vendor) {
   const v = String(vendor || "").toLowerCase();
   if (v === "claude" || v === "claude_code" || v === "claude-code") return "claude";
   if (v === "codex") return "codex";
-  return "cursor"; // cursor + ANY unknown vendor → lastLine fallback
+  if (v === "cursor") return "cursor"; // structured stream-json since 0573
+  if (v === "opencode") return "opencode"; // structured `--format json` since 0608
+  return "text"; // ANY unknown vendor → lastLine text-tail fallback
 }
 
 // --- Streaming parsers -----------------------------------------------------
@@ -249,12 +423,13 @@ function makeLineBufferedParser(parseLine) {
 }
 
 /**
- * Fallback for Cursor and any vendor with no structured stream. There's nothing
- * to parse, so we only remember the last non-empty line seen — matching exactly
- * what the daemon does today (handler.mjs onData) so we NEVER regress below it —
- * and emit at most one sparse note on flush.
+ * Fallback for any vendor with no structured stream (cursor graduated to a
+ * real parser in 0573). There's nothing to parse, so we only remember the last
+ * non-empty line seen — matching exactly what the daemon does today
+ * (handler.mjs onData) so we NEVER regress below it — and emit at most one
+ * sparse note on flush.
  */
-function makeCursorParser() {
+function makeTextTailParser() {
   let lastLine = "";
   return {
     /** @returns {AgentEvent[]} */
@@ -278,14 +453,18 @@ function makeCursorParser() {
 
 /**
  * Build a stateful stream parser for `vendor`.
- * @param {'claude'|'claude_code'|'codex'|'cursor'|string} vendor
+ * @param {'claude'|'claude_code'|'codex'|'cursor'|'opencode'|string} vendor
  * @returns {{ push: (chunk: string) => AgentEvent[], flush: () => AgentEvent[] }}
  */
 export function makeStreamParser(vendor) {
   const v = normalizeVendor(vendor);
   if (v === "claude") return makeLineBufferedParser(parseClaudeLine);
   if (v === "codex") return makeLineBufferedParser(parseCodexLine);
-  return makeCursorParser();
+  if (v === "cursor") return makeLineBufferedParser(parseCursorLine);
+  // opencode's line parser carries per-stream state (dedupe + last text), so
+  // each parser instance gets its own.
+  if (v === "opencode") return makeLineBufferedParser(makeOpencodeLineParser());
+  return makeTextTailParser();
 }
 
 // --- Human step labels (what the LiveRunCard shows) ------------------------

package/src/cli.mjs

@@ -89,6 +89,33 @@ export function minimalEnv(base = process.env, extraAllow = []) {
   return out;
 }
 
+// ── PWD must match the directory we actually run in (0615) ───────────────────
+// A child spawned with `cwd` still inherits the PARENT's `PWD`, which names
+// wherever the daemon was launched. Most tools call getcwd() and never notice,
+// but some resolve their working project from the environment instead: live-
+// verified on opencode 1.18.5, which read, edited, and shelled in the daemon's
+// launch directory while hilos staged the diff in the repo clone ("no changes
+// produced"). An env that contradicts the real cwd is simply wrong, so every
+// spawn that sets `cwd` also sets `PWD` to it — and drops the inherited
+// `OLDPWD`, which is both meaningless to the child and a leak of where the
+// daemon lives. No cwd means the child inherits ours, so PWD is left alone.
+
+/**
+ * `base` with `PWD` pinned to `cwd` (and any inherited `OLDPWD` removed).
+ * Returns a copy; `base` is never mutated. A missing/blank `cwd` is a no-op.
+ * @param {Record<string, string | undefined>} base
+ * @param {string} [cwd]
+ * @returns {Record<string, string>}
+ */
+export function envForCwd(base, cwd) {
+  const out = { ...(base || {}) };
+  if (typeof cwd === "string" && cwd.trim()) {
+    out.PWD = cwd;
+    delete out.OLDPWD;
+  }
+  return out;
+}
+
 /** Human-readable elapsed time: "45s", "2m 3s". */
 export function fmtElapsed(ms) {
   const total = Math.max(0, Math.round(ms / 1000));
@@ -145,8 +172,9 @@ const MAX_CAPTURE_BYTES = 50 * 1024 * 1024;
  * @property {(chunk: string) => void} [onData] - called with each stdout chunk as
  *   it arrives (lets a caller track the latest output line for a heartbeat)
  * @property {Record<string, string>} [env] - base environment for the child. Any
- *   hilos-owned var (HILOS_*) is stripped from it regardless. Omit to inherit the
- *   daemon's environment minus HILOS_* (the safe default).
+ *   hilos-owned var (HILOS_*) is stripped from it regardless, and `PWD` is pinned
+ *   to `cwd` when one is set (0615). Omit to inherit the daemon's environment
+ *   minus HILOS_* (the safe default).
  */
 
 /**
@@ -159,7 +187,7 @@ const MAX_CAPTURE_BYTES = 50 * 1024 * 1024;
  *
  * @param {RunCliOptions} opts
  */
-export function runCli(opts) {
+function runCliOnce(opts) {
   const {
     cmd,
     args = [],
@@ -188,12 +216,13 @@ export function runCli(opts) {
       // `codex exec` appends piped stdin to its prompt and blocks until EOF, so
       // an open pipe hangs it until the run timeout ("Reading additional input
       // from stdin…"). Nothing we spawn is ever fed via stdin.
-      // Always strip hilos's own token from the child's env (see scrubHilosEnv).
+      // Always strip hilos's own token from the child's env (see scrubHilosEnv),
+      // and keep PWD honest about the directory we run in (see envForCwd).
       child = spawn(cmd, args, {
         cwd,
         detached: true,
         stdio: ["ignore", "pipe", "pipe"],
-        env: scrubHilosEnv(env || process.env),
+        env: envForCwd(scrubHilosEnv(env || process.env), cwd),
       });
     } catch (error) {
       resolve({ status: null, stdout: "", stderr: "", error });
@@ -289,3 +318,27 @@ export function runCli(opts) {
     child.on("close", (code) => finish(code, null));
   });
 }
+
+// Compat retry (0572): Cursor CLIs older than Jan 2026 predate the workspace-
+// trust gate and reject the `--trust` flag we now bake into cursor commands
+// (`error: unknown option '--trust'`). Those CLIs don't NEED the flag (no gate
+// existed), so on that exact failure runCli retries ONCE with it stripped. The
+// failed attempt writes only the commander error to stderr — stdout stays
+// empty — so progress streaming (onData) never sees the false start. Lives
+// inside runCli (not a wrapper) so every call site, present and future, gets it.
+const UNKNOWN_TRUST_RE = /unknown option '--trust'/;
+
+/** @param {RunCliOptions} opts */
+export async function runCli(opts) {
+  const first = await runCliOnce(opts);
+  const args = Array.isArray(opts?.args) ? opts.args : [];
+  if (
+    first.status !== 0 &&
+    !first.aborted &&
+    args.includes("--trust") &&
+    UNKNOWN_TRUST_RE.test(first.stderr || "")
+  ) {
+    return runCliOnce({ ...opts, args: args.filter((a) => a !== "--trust") });
+  }
+  return first;
+}

package/src/config.mjs

@@ -66,6 +66,11 @@ const DEFAULTS = {
   // mode with codingEnvAllow: ["MY_VAR", …].
   codingEnv: "inherit",
   codingEnvAllow: [],
+  // Model preset TIER for the coding run ("" / "default" = the tool's own
+  // default). "opus" | "sonnet" | "haiku" resolve at RUN time against the
+  // CLI's own model list — never a baked id that could 404 on another account
+  // (0504; cursor only today, see model-resolve.mjs).
+  codingModel: "",
   // Chat replies + the code-task plan-ack use a FAST one-shot command so a casual
   // reply (or "I see it, here's my plan") comes back in seconds, not minutes.
   // Bounded by chatTimeoutMs with a template fallback so it can never dead-air.
@@ -112,6 +117,7 @@ export function resolveConfig({ flags = {}, join: joinPayload } = {}) {
     token: process.env.HILOS_TOKEN,
     channelId: process.env.HILOS_CHANNEL,
     codingCmd: process.env.CODING_CMD,
+    codingModel: process.env.HILOS_CODING_MODEL,
     chatCmd: process.env.HILOS_CHAT_CMD,
     heartbeatMs: process.env.HILOS_HEARTBEAT_MS ? Number(process.env.HILOS_HEARTBEAT_MS) : undefined,
     progressMs: process.env.HILOS_PROGRESS_MS ? Number(process.env.HILOS_PROGRESS_MS) : undefined,
@@ -135,8 +141,12 @@ export function resolveConfig({ flags = {}, join: joinPayload } = {}) {
   // Local-folder map, merged like `repos` (an object, not a scalar overlay).
   merged.folders = { ...DEFAULTS.folders, ...(file.folders || {}) };
   merged.deploy = { ...DEFAULTS.deploy, ...(file.deploy || {}) };
-  // Remember where the file lives so reloadConfig can re-read it live.
+  // Remember where the file lives so reloadConfig can re-read it live, and
+  // what it said AT LAUNCH so reload only applies fields the user actually
+  // edited afterwards (0576) — a pre-existing file value must not claw back
+  // an explicit launch flag (--coding-cmd / --coding-model) on the first poll.
   merged.configPath = findConfigPath(flags.config) || null;
+  merged.fileSnapshot = file;
   return merged;
 }
 
@@ -145,6 +155,7 @@ export function resolveConfig({ flags = {}, join: joinPayload } = {}) {
 // edited file can NEVER drop the daemon's connection.
 const LIVE_FIELDS = [
   "codingCmd",
+  "codingModel",
   "chatCmd",
   "codingEnv",
   "codingEnvAllow",
@@ -182,8 +193,17 @@ export function reloadConfig(prev) {
   const path = prev.configPath;
   const file = (path && readJson(path)) || {};
   const next = { ...prev };
-  for (const k of LIVE_FIELDS) if (file[k] !== undefined) next[k] = file[k];
+  // Apply only fields that CHANGED since the launch snapshot (or the last
+  // reload): an EDIT to hilos-agent.json wins live, as documented, but a value
+  // that merely pre-existed at launch can't override the flags the user just
+  // pasted (`--coding-cmd`/`--coding-model` on a machine with an older config
+  // silently flipped back on the first poll — 0576 review finding).
+  const snap = prev.fileSnapshot || {};
+  const changed = (k) => JSON.stringify(file[k]) !== JSON.stringify(snap[k]);
+  for (const k of LIVE_FIELDS) if (file[k] !== undefined && changed(k)) next[k] = file[k];
+  next.fileSnapshot = file;
   if (process.env.CODING_CMD) next.codingCmd = process.env.CODING_CMD;
+  if (process.env.HILOS_CODING_MODEL) next.codingModel = process.env.HILOS_CODING_MODEL;
   if (process.env.HILOS_CHAT_CMD) next.chatCmd = process.env.HILOS_CHAT_CMD;
   if (process.env.HILOS_HEARTBEAT_MS) next.heartbeatMs = Number(process.env.HILOS_HEARTBEAT_MS);
   if (process.env.HILOS_PROGRESS_MS) next.progressMs = Number(process.env.HILOS_PROGRESS_MS);
@@ -208,6 +228,7 @@ export function writeStarterConfig(path, partial = {}) {
     channelId: partial.channelId || "",
     repos: partial.repos || { "owner/name": "/absolute/path/to/checkout" },
     codingCmd: partial.codingCmd || DEFAULTS.codingCmd,
+    ...(partial.codingModel ? { codingModel: partial.codingModel } : {}),
     defaultBranch: DEFAULTS.defaultBranch,
     // false = open a PR directly (bias to action); true = approve-before-push.
     gate: false,