@claw-link/gateway-host 0.3.7 → 0.3.9

package/bin/cli.js

@@ -32,6 +32,10 @@ async function main() {
     case 'update-token':
       return require('../scripts/install').retokenCmd();
 
+    case 'set-model':
+    case 'model':
+      return require('../scripts/install').setModelCmd();
+
     case 'agents':
     case 'list':
       return require('../scripts/install').listAgents();
@@ -96,6 +100,7 @@ async function main() {
         '  add-agent   Add an agent by pasting its Host Token (pulls runtime from ClawLink)',
         '  rm-agent    Remove a mapped agent (clhost rm-agent <id>)',
         '  retoken     Re-enter a new Host Token for an existing agent (clhost retoken <id>)',
+        '  set-model   Set the model an agent’s runtime uses (clhost set-model <id> <model>)',
         '  agents      List mapped agents',
         '  status      Show bridge, service state, and mapped agents',
         '  doctor      Diagnose config, runtime binaries, bridge + token/machine binding',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claw-link/gateway-host",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "ClawLink Host Gateway — a secure, outbound-only worker that bridges a local agent CLI (OpenClaw, Hermes, Claude, Codex, Cursor) to your ClawLink agents. No inbound ports; authenticated per-agent by a Host Token.",
   "homepage": "https://claw-link.co",
   "bin": {

package/scripts/install.js

@@ -139,9 +139,9 @@ async function run() {
       onWait: (s) => process.stdout.write(`\r     … still working: ${s.activeJobs} job(s) in flight      `),
     });
     if (live && live.busy) process.stdout.write('\n');
-    console.log(r.restarted
-      ? (r.hadWorker && !r.timedOut ? '  ✓ Finished in-flight work, then refreshed to the latest version.' : '  ✓ Service refreshed to the latest version.')
-      : '  ⚠ Could not refresh the service automatically — run:  clhost restart');
+    if (!r.restarted) console.log('  ⚠ Could not refresh the service automatically — run:  clhost restart');
+    else if (r.confirmed) console.log(`  ✓ Refreshed — now running v${r.version} (pid ${r.pid}).`);
+    else console.log(`  ⚠ Restart triggered but the new worker hasn't come up on v${VERSION} yet — check \`clhost status\` in a few seconds.`);
     reportCli();
     console.log('\n  Commands:  clhost status · clhost agents · clhost add-agent · clhost transport-test\n');
     return;
@@ -190,9 +190,10 @@ async function addAgentCmd() {
   rl.close();
   if (agent) {
     saveAgent(cfg, agent);
-    const { restarted } = await gracefulServiceRestartCLI();
-    console.log(`\n  ✓ Added agent ${agent.agent_id} (${agent.runtime}).` +
-      (restarted ? ' Service restarted.' : ' Run `clhost restart` (or start) to apply.') + '\n');
+    const r = await gracefulServiceRestartCLI();
+    const note = !r.restarted ? ' Run `clhost restart` (or start) to apply.'
+      : r.confirmed ? ' Service restarted.' : ' Restarting — check `clhost status`.';
+    console.log(`\n  ✓ Added agent ${agent.agent_id} (${agent.runtime}).` + note + '\n');
   }
 }
 
@@ -212,8 +213,10 @@ async function removeAgentCmd() {
   cfg.agents = cfg.agents.filter((a) => !(a.agent_id && (a.agent_id === target || a.agent_id.startsWith(target))));
   if (cfg.agents.length === before) { console.log(`  No agent matched '${target}'.`); return; }
   config.save(cfg);
-  const { restarted } = await gracefulServiceRestartCLI();
-  console.log(`  ✓ Removed agent '${target}'.` + (restarted ? ' Service restarted.' : ' Run `clhost restart` to apply.'));
+  const r = await gracefulServiceRestartCLI();
+  const note = !r.restarted ? ' Run `clhost restart` to apply.'
+    : r.confirmed ? ' Service restarted.' : ' Restarting — check `clhost status`.';
+  console.log(`  ✓ Removed agent '${target}'.` + note);
 }
 
 function printAgents(cfg) {
@@ -223,7 +226,7 @@ function printAgents(cfg) {
   for (const a of agents) {
     const id = a.agent_id || '(unresolved)';
     const tok = a.host_token ? `…${String(a.host_token).slice(-4)}` : '—';
-    console.log(`    • ${id}  runtime=${a.runtime || 'pull'}  token=${tok}` + (a.work_dir ? `  work=${a.work_dir}` : ''));
+    console.log(`    • ${id}  runtime=${a.runtime || 'pull'}  token=${tok}` + (a.model ? `  model=${a.model}` : '') + (a.work_dir ? `  work=${a.work_dir}` : ''));
   }
   // Show a concrete, copy-pasteable example (commands also accept any id prefix).
   const example = agents[0].agent_id || '<id>';
@@ -270,12 +273,43 @@ async function retokenCmd() {
     }
     config.save(cfg);
     rl.close(); // release stdin before the (possibly long) graceful drain so Ctrl-C is handled by our cleanup
-    const { restarted } = await gracefulServiceRestartCLI();
-    console.log(`\n  ✓ Updated token for ${agent.agent_id} (…${token.slice(-4)}).` +
-      (restarted ? ' Service restarted.' : ' Run `clhost restart` to apply.') + '\n');
+    const r = await gracefulServiceRestartCLI();
+    const note = !r.restarted ? ' Run `clhost restart` to apply.'
+      : r.confirmed ? ' Service restarted.' : ' Restarting — check `clhost status`.';
+    console.log(`\n  ✓ Updated token for ${agent.agent_id} (…${token.slice(-4)}).` + note + '\n');
   } finally { rl.close(); }
 }
 
+// `set-model <id-or-prefix> <model>` — set (or clear) the model an agent's runtime uses, then
+// restart to apply. Coding runtimes map it to their own flag: claude `--model`, cursor/hermes
+// `--model`, codex `-c model="…"`. Use `default` (or `none`) to clear the override.
+async function setModelCmd() {
+  const cfg = config.load();
+  if (!cfg || !(cfg.agents || []).length) { console.log('No agents configured. Run: clhost add-agent'); return; }
+  const target = (process.argv[3] || '').trim();
+  const modelArg = (process.argv[4] || '').trim();
+  if (!target || !modelArg) {
+    console.log('Usage: clhost set-model <agent-id|prefix> <model>');
+    console.log('  e.g.  clhost set-model 3f208761 sonnet      (claude: sonnet | opus | haiku | full id)');
+    console.log('        clhost set-model my-agent default      (clear → use the runtime default)\n');
+    printAgents(cfg);
+    return;
+  }
+  const agent = cfg.agents.find((a) => a.agent_id && (a.agent_id === target || a.agent_id.startsWith(target)));
+  if (!agent) { console.log(`  No agent matched '${target}'.`); return; }
+
+  const clear = ['default', 'none', '-'].includes(modelArg.toLowerCase());
+  agent.model = clear ? null : modelArg;
+  config.save(cfg);
+  if (!clear && agent.runtime === 'openclaw') {
+    console.log('  ⚠ OpenClaw agents get their model from the OpenClaw gateway, not from here — this override has no effect.');
+  }
+  const r = await gracefulServiceRestartCLI();
+  const note = !r.restarted ? ' Run `clhost restart` to apply.'
+    : r.confirmed ? ' Service restarted.' : ' Restarting — check `clhost status`.';
+  console.log(`  ✓ ${clear ? `Cleared model for ${agent.agent_id} — using the ${agent.runtime} default.` : `Set ${agent.agent_id} model → ${modelArg} (${agent.runtime}).`}` + note);
+}
+
 // `start | stop | restart` — control the installed background service.
 function serviceControl(action) {
   const platform = process.platform;
@@ -297,7 +331,17 @@ function serviceControl(action) {
     if (platform === 'win32') {
       if (action === 'stop')    return execSafe('schtasks /End /TN ClawLinkHost') !== null;
       if (action === 'start')   return execSafe('schtasks /Run /TN ClawLinkHost') !== null;
-      if (action === 'restart') { execSafe('schtasks /End /TN ClawLinkHost'); return execSafe('schtasks /Run /TN ClawLinkHost') !== null; }
+      if (action === 'restart') {
+        execSafe('schtasks /End /TN ClawLinkHost');
+        // /End is async, and the task is MultipleInstancesPolicy=IgnoreNew — so an immediate /Run can be
+        // SILENTLY DROPPED while the old instance is still stopping (the Windows analogue of the macOS
+        // bootout→bootstrap race). Give it a brief, LANGUAGE-NEUTRAL pause to stop before /Run: `ping -n
+        // 4 127.0.0.1` ≈ 3s (parsing schtasks' status would depend on the localized word "Running"; and
+        // `timeout` needs an interactive console). If /Run still doesn't take, restartAndConfirm's
+        // confirm-then-reinstall fallback recovers.
+        execSafe('ping -n 4 127.0.0.1');
+        return execSafe('schtasks /Run /TN ClawLinkHost') !== null;
+      }
     }
   } catch { /* fall through */ }
   return false;
@@ -308,8 +352,10 @@ async function serviceControlCmd(action) {
   // `stop` stays prompt: its SIGTERM already lets the worker finish in-flight work (2nd signal forces).
   if (action === 'restart') {
     const { force, timeoutMs } = parseDrainArgs();
-    const { restarted } = await gracefulServiceRestartCLI({ force, timeoutMs });
-    console.log(restarted ? '  ✓ Service restarted.' : '  ⚠ Could not restart the service (is it installed? run `clhost install`).');
+    const r = await gracefulServiceRestartCLI({ force, timeoutMs });
+    if (!r.restarted) console.log('  ⚠ Could not restart the service (is it installed? run `clhost install`).');
+    else if (r.confirmed) console.log(`  ✓ Service restarted — running v${r.version} (pid ${r.pid}).`);
+    else console.log('  ⚠ Restart triggered but the worker hasn’t reported yet — check `clhost status`.');
     return;
   }
   const ok = serviceControl(action);
@@ -547,47 +593,90 @@ async function drainToIdle({ timeoutMs = 15 * 60 * 1000, force = false, onWait }
   if (force) return { hadWorker: true, drained: false, forced: true };
 
   control.requestDrain();
-  // If the operator Ctrl-C's (or the CLI is killed) mid-wait, clear the flag so the still-running
-  // worker resumes claiming instead of sitting drained forever. Without this, an aborted update/
-  // restart would silently wedge the worker.
+  // NOTE: the Ctrl-C cleanup that clears the drain flag on abort lives in withDrainGuard(), which
+  // wraps this call AND the restart — so there's no window (between drain finishing and the restart)
+  // where an interrupt could leave the worker drained. Don't install a handler here.
+  const startedAt = Date.now();
+  let waited = false;
+  while (Date.now() - startedAt < timeoutMs) {
+    const s = control.liveStatus();
+    if (!s) return { hadWorker: true, drained: true, workerGone: true };  // worker exited → safe
+    // Safe to restart only once the worker has ACKED the drain (won't claim more) AND is idle.
+    if (s.drain && !s.busy) return { hadWorker: true, drained: true, waited };
+    if (s.busy && typeof onWait === 'function') { onWait(s); waited = true; }
+    await sleep(1500);
+  }
+  return { hadWorker: true, drained: false, timedOut: true };
+}
+
+// Run an async drain+restart sequence under a Ctrl-C guard: if the operator interrupts at ANY point
+// (during the drain wait OR the restart), clear the drain flag FIRST so the still-running worker
+// resumes claiming — never left wedged — then exit. Spanning the whole sequence closes the gap that
+// a per-drainToIdle handler would leave open between draining and restarting.
+async function withDrainGuard(fn) {
   const onInt = () => { try { control.clearDrain(); } catch { /* ignore */ } process.exit(130); };
   process.on('SIGINT', onInt);
   process.on('SIGTERM', onInt);
-  try {
-    const startedAt = Date.now();
-    let waited = false;
-    while (Date.now() - startedAt < timeoutMs) {
-      const s = control.liveStatus();
-      if (!s) return { hadWorker: true, drained: true, workerGone: true };  // worker exited → safe
-      // Safe to restart only once the worker has ACKED the drain (won't claim more) AND is idle.
-      if (s.drain && !s.busy) return { hadWorker: true, drained: true, waited };
-      if (s.busy && typeof onWait === 'function') { onWait(s); waited = true; }
-      await sleep(1500);
+  try { return await fn(); }
+  finally { process.off('SIGINT', onInt); process.off('SIGTERM', onInt); }
+}
+
+// After triggering a restart, wait until the NEW worker actually publishes status (a different pid
+// than before and — if given — the expected version), so a caller never reports success while the old
+// process is still winding down or a launchd unload/reload is mid-flight. Best-effort: confirmed=false
+// on timeout. This is what makes `clhost update`'s "runs vX" honest instead of premature.
+async function waitForWorkerUp(prevPid, wantVersion, timeoutMs = 25000) {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    await sleep(1000);
+    const s = control.liveStatus();
+    if (s && s.pid !== prevPid && (!wantVersion || String(s.version) === String(wantVersion))) {
+      return { confirmed: true, version: s.version, pid: s.pid };
     }
-    return { hadWorker: true, drained: false, timedOut: true };
-  } finally {
-    process.off('SIGINT', onInt);
-    process.off('SIGTERM', onInt);
   }
+  const s = control.liveStatus();
+  return { confirmed: false, version: s && s.version, pid: s && s.pid };
+}
+
+// Restart the service and CONFIRM the new worker came up. Prefer an IN-PLACE restart
+// (kickstart -k / systemctl restart / schtasks) — it never unloads the job (no "Service: stopped"
+// window like bootout→bootstrap) and relaunches from the stable app dir. Only if that fails to bring
+// a worker up (service not loaded yet, or a stale Node path in the plist after an nvm/Node upgrade)
+// fall back to a full (re)install, which rewrites the plist. Clears the drain flag unless a fresh
+// worker is confirmed (which clears it on boot) so nothing is ever left drained.
+async function restartAndConfirm({ stageCode = false, wantVersion, onRestart } = {}) {
+  if (stageCode) syncAppDir(); // copy the new code into the stable app dir the service runs from
+  const prevPid = (control.liveStatus() || {}).pid;
+  let notified = false;
+  const notify = () => { if (!notified && typeof onRestart === 'function') { notified = true; onRestart(); } };
+  let restarted = serviceControl('restart');
+  if (restarted) notify();
+  let up = restarted ? await waitForWorkerUp(prevPid, wantVersion) : { confirmed: false };
+  if (!up.confirmed) {
+    const reinstalled = installService(); // rewrites plist/unit (handles a moved Node) + reload
+    if (reinstalled) { restarted = true; notify(); up = await waitForWorkerUp(prevPid, wantVersion); }
+  }
+  if (!up.confirmed) control.clearDrain();
+  return { restarted, ...up };
 }
 
-// Drain the running worker to idle (unless forced), then stage the new code + restart the service.
-// The fresh worker clears the drain flag on boot; if the restart fails we clear it here so the old
-// worker resumes claiming instead of sitting permanently drained.
+// `update` path — drain, then stage new code + restart, confirming the new version is actually live.
 async function gracefulRestart(opts = {}) {
-  const drain = await drainToIdle(opts);
-  const restarted = installService();  // syncAppDir (stage new code) + bootstrap/restart the service
-  if (!restarted) control.clearDrain();
-  return { ...drain, restarted };
+  return withDrainGuard(async () => {
+    const drain = await drainToIdle(opts);
+    const r = await restartAndConfirm({ stageCode: true, wantVersion: VERSION, onRestart: opts.onRestart });
+    return { ...drain, ...r };
+  });
 }
 
-// Config-change restart (add/remove/retoken agent, `clhost restart`): drain in-flight jobs first,
-// then a plain restart. Unlike gracefulRestart it does NOT re-stage code — the version is unchanged.
+// Config-change restart (add/remove/retoken agent, `clhost restart`): drain first, then restart in
+// place (no code re-stage — same version), confirming the worker actually bounced (new pid).
 async function gracefulServiceRestart(opts = {}) {
-  const drain = await drainToIdle(opts);
-  const restarted = serviceControl('restart');
-  if (!restarted) control.clearDrain();
-  return { ...drain, restarted };
+  return withDrainGuard(async () => {
+    const drain = await drainToIdle(opts);
+    const r = await restartAndConfirm({ stageCode: false, onRestart: opts.onRestart });
+    return { ...drain, ...r };
+  });
 }
 
 // Console wrapper around gracefulServiceRestart: prints a one-time "waiting" notice + a live progress
@@ -637,15 +726,20 @@ async function update() {
   if (live && live.busy && !force) process.stdout.write('\n');
 
   if (!r.restarted) { console.log('  ⚠ Could not refresh automatically — run:  clhost restart'); return; }
-  if (r.forced) console.log(`  ✓ Restarted now (--force). Service runs v${VERSION} from ${appDir()}.`);
-  else if (r.timedOut) console.log(`  ⚠ A job was still running after the wait — restarted anyway (it may have been interrupted). Service runs v${VERSION}.`);
-  else if (r.hadWorker) console.log(`  ✓ Finished in-flight work, then refreshed. Service runs v${VERSION} from ${appDir()}.`);
-  else console.log(`  ✓ Service now runs v${VERSION} from ${appDir()}.`);
+  if (r.confirmed) {
+    // The success line now reflects what the new worker ACTUALLY reports (pid + version), not a guess.
+    const drained = r.hadWorker && !r.forced && !r.timedOut;
+    console.log(`  ✓ ${drained ? 'Finished in-flight work, then restarted' : 'Restarted'} — now running v${r.version} (pid ${r.pid}).`);
+    if (r.timedOut) console.log('  ⚠ (A job was still running after the wait — it may have been interrupted.)');
+  } else {
+    console.log(`  ⚠ Restart triggered but the new worker hasn't come up on v${VERSION} yet` +
+      (r.version ? ` (still seeing v${r.version})` : '') + ` — check \`clhost status\` in a few seconds (\`clhost logs\` if it doesn't appear).`);
+  }
   console.log('  (To upgrade the `clhost` CLI you type:  npm i -g @claw-link/gateway-host@latest)\n');
 }
 
 module.exports = {
-  run, installOnly, addAgentCmd, removeAgentCmd, retokenCmd, listAgents, status,
+  run, installOnly, addAgentCmd, removeAgentCmd, retokenCmd, setModelCmd, listAgents, status,
   serviceControl, serviceControlCmd, installService, SERVICE_LABEL,
   versionCmd, doctor, logs, update,
 };

package/src/adapters/claude.js

@@ -10,10 +10,11 @@ module.exports = makeCliAdapter({
   streamJson: true,
   // Prompt via stdin keeps it out of argv/process listings.
   promptViaStdin: true,
-  defaultArgs: (_fullPrompt, resumeId, _stdin, perm = []) => [
+  defaultArgs: (_fullPrompt, resumeId, _stdin, perm = [], model = '') => [
     '-p',
     '--output-format', 'stream-json',
     '--verbose',
+    ...(model ? ['--model', model] : []), // e.g. sonnet | opus | haiku | a full model id
     ...perm,
     ...(resumeId ? ['--resume', resumeId] : []),
   ],

package/src/adapters/cli.js

@@ -8,6 +8,39 @@ const path = require('path');
 const { spawnStreaming, buildArgv } = require('./base');
 const sessionStore = require('../session-store');
 
+// Chat/harness attachments arrive as URLs (the public chat-attachments bucket). A sandboxed CLI
+// can't reach a URL, so we DOWNLOAD each into the agent's workspace and reference the LOCAL path —
+// even a read-only turn keeps its Read tool, so the agent can open the file. Falls back to the URL.
+const MAX_ATTACHMENT_BYTES = Number(process.env.CLAWHOST_MAX_ATTACHMENT_BYTES) || 25 * 1024 * 1024;
+async function localizeAttachments(atts, workDir, logger) {
+  const urls = (Array.isArray(atts) ? atts : [])
+    .map((a) => (typeof a === 'string' ? a : (a && a.url) || ''))
+    .filter(Boolean);
+  if (!urls.length) return '';
+  const relDir = path.join('.clawlink', 'attachments');
+  const absDir = path.join(workDir, relDir);
+  try { fs.mkdirSync(absDir, { recursive: true }); } catch { /* ignore */ }
+  const lines = [];
+  for (const url of urls) {
+    let localRel = null;
+    if (/^https?:\/\//i.test(url)) {
+      try {
+        const res = await fetch(url);
+        if (res.ok) {
+          const buf = Buffer.from(await res.arrayBuffer());
+          if (buf.length <= MAX_ATTACHMENT_BYTES) {
+            const name = ((url.split('/').pop() || 'file').split('?')[0] || 'file').replace(/[^a-zA-Z0-9._-]/g, '_') || 'file';
+            fs.writeFileSync(path.join(absDir, name), buf);
+            localRel = path.join(relDir, name);
+          } else logger.warn(`attachment too large (${buf.length}B): ${url.slice(0, 60)}…`);
+        }
+      } catch (e) { logger.warn(`attachment download failed (${url.slice(0, 60)}…): ${e.message}`); }
+    }
+    lines.push(localRel ? `- ${localRel}` : `- ${url}  (couldn't download — fetch it yourself if you can)`);
+  }
+  return `\n\nThe user attached these file(s). READ them (use your Read tool) before answering:\n${lines.join('\n')}`;
+}
+
 // Generic parser: each non-empty stdout line is answer text.
 function genericLineParser(line) {
   const t = line.replace(/\r$/, '');
@@ -81,7 +114,7 @@ function makeCodexJsonParser(capture) {
 }
 
 /**
- * @param cfg { name, binaries:[], defaultArgs(fullPrompt, resumeId, promptViaStdin, permArgs):[],
+ * @param cfg { name, binaries:[], defaultArgs(fullPrompt, resumeId, promptViaStdin, permArgs, model):[],
  *              streamJson?:bool, makeParser?:(capture)=>parseFn, permissions?:(scope)=>[],
  *              promptViaStdin?:bool, timeoutMs?:number }
  */
@@ -94,23 +127,21 @@ function makeCliAdapter(cfg) {
       const binary = agent.binary || cfg.binaries[0];
       const userPrompt = job.content || '';
       const systemPrompt = job.system_prompt || '';
-      // Text CLIs can't take vision blocks — surface attachment URLs as references so
-      // the model is at least aware of them (override via args_template for file-aware CLIs).
-      const atts = Array.isArray(job.attachments) ? job.attachments : [];
-      const attBlock = atts.length
-        ? '\n\nAttachments:\n' + atts.map((a) => `- ${typeof a === 'string' ? a : (a && a.url) || ''}`).join('\n')
-        : '';
-      const base = systemPrompt ? `${systemPrompt}\n\n---\n\nUser request:\n${userPrompt}` : userPrompt;
-      const fullPrompt = base + attBlock;
       const clSession = job.session_key || job.session_id || null;
       const resumeId = clSession ? sessionStore.get(cfg.name, clSession) : null;
       // 0 = no timeout (default) — don't cut off long generations. Opt in with CLAWHOST_TIMEOUT_MS.
       const timeoutMs = cfg.timeoutMs || Number(process.env.CLAWHOST_TIMEOUT_MS) || 0;
 
-      // Run inside the agent's workspace/scratch dir. Create it if missing so the
-      // spawn never fails with ENOENT (coding workspaces are validated at setup).
+      // Run inside the agent's workspace/scratch dir. Create it FIRST so attachment downloads +
+      // the spawn never fail with ENOENT (coding workspaces are validated at setup).
       try { fs.mkdirSync(agent.work_dir, { recursive: true }); } catch { /* ignore */ }
 
+      // Download any attachments into the workspace and reference their LOCAL paths, so the CLI
+      // (which can't reach a URL) can open them via its Read tool.
+      const attBlock = await localizeAttachments(job.attachments, agent.work_dir, logger);
+      const base = systemPrompt ? `${systemPrompt}\n\n---\n\nUser request:\n${userPrompt}` : userPrompt;
+      const fullPrompt = base + attBlock;
+
       // Scope-based permissions: admin "configure" turns may write workspace files
       // (GUARDRAILS/SOUL/etc.); customer/discovery turns are read-only and cannot
       // edit or run shell. permArgs is handed to defaultArgs so each adapter can place
@@ -123,9 +154,12 @@ function makeCliAdapter(cfg) {
       const permArgs = (!Array.isArray(agent.args_template) && cfg.permissions)
         ? cfg.permissions(writable ? 'configure' : (job.scope || 'customer'))
         : [];
+      // Optional per-agent model override (e.g. `clhost set-model <id> sonnet`). Each adapter
+      // places it with the runtime's correct flag; ignored when an args_template takes over.
+      const model = (!Array.isArray(agent.args_template) && agent.model) ? String(agent.model) : '';
       const argvFor = (rid) => Array.isArray(agent.args_template)
         ? buildArgv(agent.args_template, { prompt: fullPrompt, sessionId: rid || '', systemPrompt })
-        : cfg.defaultArgs(fullPrompt, rid, cfg.promptViaStdin, permArgs);
+        : cfg.defaultArgs(fullPrompt, rid, cfg.promptViaStdin, permArgs, model);
 
       let emittedAny = false;
       const runOnce = async function* (rid) {

package/src/adapters/codex.js

@@ -16,8 +16,11 @@ module.exports = makeCliAdapter({
   binaries: ['codex'],
   promptViaStdin: false,
   makeParser: makeCodexJsonParser,
-  defaultArgs: (fullPrompt, resumeId, _stdin, perm = []) => {
-    const opts = ['--json', '--skip-git-repo-check', ...perm];
+  defaultArgs: (fullPrompt, resumeId, _stdin, perm = [], model = '') => {
+    // Model via `-c model="…"` — the config-override form both `exec` and `exec resume` accept
+    // (like sandbox/approval above), so it must sit in `opts` BEFORE the `--` end-of-options.
+    const modelOpt = model ? ['-c', `model="${model}"`] : [];
+    const opts = ['--json', '--skip-git-repo-check', ...modelOpt, ...perm];
     // `--` ends option parsing so a prompt starting with '-' is positional, never a flag.
     return resumeId
       ? ['exec', 'resume', ...opts, resumeId, '--', fullPrompt]

package/src/adapters/cursor.js

@@ -7,5 +7,6 @@ module.exports = makeCliAdapter({
   name: 'cursor',
   binaries: ['cursor-agent', 'cursor'],
   promptViaStdin: false,
-  defaultArgs: (fullPrompt) => ['-p', fullPrompt],
+  defaultArgs: (fullPrompt, _resumeId, _stdin, _perm = [], model = '') =>
+    [...(model ? ['--model', model] : []), '-p', fullPrompt],
 });

package/src/adapters/hermes.js

@@ -7,8 +7,10 @@ const { makeCliAdapter } = require('./cli');
 module.exports = makeCliAdapter({
   name: 'hermes',
   binaries: ['hermes'],
-  defaultArgs: (fullPrompt, resumeId) => [
-    'chat', '-q', fullPrompt,
+  defaultArgs: (fullPrompt, resumeId, _stdin, _perm = [], model = '') => [
+    'chat',
+    ...(model ? ['--model', model] : []),
+    '-q', fullPrompt,
     ...(resumeId ? ['--resume', resumeId] : []),
   ],
 });

package/src/config.js

@@ -71,6 +71,9 @@ function normalizeAgent(a) {
     host_token: a.host_token,
     runtime: a.runtime || null,
     binary: a.binary || null,
+    // Optional model override for coding runtimes (claude/codex/cursor/hermes). null = the
+    // runtime's own default. Set with `clhost set-model <id> <model>`.
+    model: a.model || null,
     args_template: Array.isArray(a.args_template) ? a.args_template : null,
     local_gateway_url: a.local_gateway_url || null,
     local_gateway_token: a.local_gateway_token || null,

package/src/worker.js

@@ -221,18 +221,14 @@ async function startWorker() {
 
   logger.info(`ClawLink Host Gateway v${VERSION} — ${agents.length} agent(s): ${agents.map((a) => `${(a.agent_id || 'pending').slice(0, 8)}…(${a.runtime || 'resolving'})`).join(', ')}`);
 
-  // H2H data plane: bring up the native QUIC transport once per host (shared by all agents). If no
-  // prebuilt native core exists for this platform, every transfer routes through the central relay.
   const p2p = new P2P(logger);
-  const p2pAddr = await p2p.start();
-  logger.info(p2pAddr
-    ? `H2H transport: native P2P active (${p2pAddr})`
-    : 'H2H transport: central relay (no native core for this platform — install acceleration later)');
 
   // Advertise liveness + in-flight count so `clhost update`/`restart` can wait for this host to go
   // idle before restarting, and pick up the CLI's drain flag (stop claiming, finish current work).
-  // Clear any stale flag first; and only ever honor a flag written AFTER this boot, so a leftover
-  // flag from a crashed update (or a clearDrain that failed) can never wedge a fresh worker.
+  // Do this BEFORE the (possibly slow) P2P init, so a restart is CONFIRMED fast — waitForWorkerUp sees
+  // the new pid/version within ~1s even while iroh is still binding. Clear any stale flag first; and
+  // only ever honor a flag written AFTER this boot, so a leftover flag from a crashed update (or a
+  // clearDrain that failed) can never wedge a fresh worker. (pushStatus never touches p2p.)
   control.clearDrain();      // drop any stale flag left by a previous life FIRST…
   const bootAt = Date.now(); // …then anchor "now": only a drain requested after this point is honored.
   const pushStatus = () => {
@@ -248,6 +244,13 @@ async function startWorker() {
   const statusTimer = setInterval(pushStatus, 2000);
   statusTimer.unref();
 
+  // H2H data plane: bring up the native QUIC transport once per host (shared by all agents). If no
+  // prebuilt native core exists for this platform, every transfer routes through the central relay.
+  const p2pAddr = await p2p.start();
+  logger.info(p2pAddr
+    ? `H2H transport: native P2P active (${p2pAddr})`
+    : 'H2H transport: central relay (no native core for this platform — install acceleration later)');
+
   // Graceful shutdown: stop claiming, let in-flight jobs finish (keeping P2P alive for them), then
   // exit. A second signal forces an immediate exit; SHUTDOWN_DRAIN_MS bounds the wait.
   let stopSignals = 0;

package/templates/claude/CLAUDE.md

@@ -4,9 +4,23 @@ This folder is the working directory for a **ClawLink** customer-facing agent ru
 locally via the ClawLink Host Gateway (`@claw-link/gateway-host`). Claude Code reads
 this `CLAUDE.md` as project context.
 
-Operating rules for this agent:
-- The agent's **persona, applied skills, and per-conversation instructions arrive in
-  the system prompt of every request** — follow them as the source of truth.
+## Read your configured instructions first
+
+Skills, personas, and security settings are written to dedicated files in this directory.
+**Before you respond, read whichever of these exist here — they hold your configured behaviour:**
+
+- `GUARDRAILS.md` — hard security rules. **Never violate these**; they override everything.
+- `BOOTSTRAP.md` — how to start up and behave.
+- `SOUL.md` — your identity / persona.
+- `TOOLS.md` — the tools and skills available to you and how to use them.
+- `MEMORY.md` — remembered context and preferences.
+
+Follow them on every turn. If a file is absent, skip it.
+
+## Operating rules
+
+- The agent's **persona, applied skills, and per-conversation instructions also arrive in
+  the system prompt of every request** — follow them together with the files above.
 - Keep replies helpful, accurate, and on-task for the business you represent.
 - Stay in scope: do not run destructive commands or act outside the customer's request.
 - Never reveal secrets, tokens, config files, or host/system details.

package/templates/codex/AGENTS.md

@@ -4,9 +4,23 @@ This folder is the working directory for a **ClawLink** customer-facing agent ru
 locally via the ClawLink Host Gateway (`@claw-link/gateway-host`). Codex reads
 `AGENTS.md` as project context.
 
-Operating rules for this agent:
-- The agent's **persona, applied skills, and per-conversation instructions arrive in
-  the system prompt of every request** — follow them as the source of truth.
+## Read your configured instructions first
+
+Skills, personas, and security settings are written to dedicated files in this directory.
+**Before you respond, read whichever of these exist here — they hold your configured behaviour:**
+
+- `GUARDRAILS.md` — hard security rules. **Never violate these**; they override everything.
+- `BOOTSTRAP.md` — how to start up and behave.
+- `SOUL.md` — your identity / persona.
+- `TOOLS.md` — the tools and skills available to you and how to use them.
+- `MEMORY.md` — remembered context and preferences.
+
+Follow them on every turn. If a file is absent, skip it.
+
+## Operating rules
+
+- The agent's **persona, applied skills, and per-conversation instructions also arrive in
+  the system prompt of every request** — follow them together with the files above.
 - Keep replies helpful, accurate, and on-task for the business you represent.
 - Stay in scope: do not run destructive commands or act outside the customer's request.
 - Never reveal secrets, tokens, config files, or host/system details.

package/templates/cursor/AGENTS.md

@@ -4,9 +4,23 @@ This folder is the working directory for a **ClawLink** customer-facing agent ru
 locally via the ClawLink Host Gateway (`@claw-link/gateway-host`). The Cursor agent
 reads `AGENTS.md` as project context.
 
-Operating rules for this agent:
-- The agent's **persona, applied skills, and per-conversation instructions arrive in
-  the system prompt of every request** — follow them as the source of truth.
+## Read your configured instructions first
+
+Skills, personas, and security settings are written to dedicated files in this directory.
+**Before you respond, read whichever of these exist here — they hold your configured behaviour:**
+
+- `GUARDRAILS.md` — hard security rules. **Never violate these**; they override everything.
+- `BOOTSTRAP.md` — how to start up and behave.
+- `SOUL.md` — your identity / persona.
+- `TOOLS.md` — the tools and skills available to you and how to use them.
+- `MEMORY.md` — remembered context and preferences.
+
+Follow them on every turn. If a file is absent, skip it.
+
+## Operating rules
+
+- The agent's **persona, applied skills, and per-conversation instructions also arrive in
+  the system prompt of every request** — follow them together with the files above.
 - Keep replies helpful, accurate, and on-task for the business you represent.
 - Stay in scope: do not run destructive commands or act outside the customer's request.
 - Never reveal secrets, tokens, config files, or host/system details.