@moondeck/station 0.0.1 → 1.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@moondeck/station",
-  "version": "0.0.1",
-  "description": "Moondeck Station: runs Moondeck tasks on a machine you control. Placeholder; the first release is coming soon.",
+  "version": "1.0.0",
+  "description": "Moondeck Station: runs Moondeck tasks in containers on a machine you control.",
   "license": "MIT",
   "author": "Moondeck <team@moondeck.io>",
   "homepage": "https://moondeck.io",
@@ -10,17 +10,124 @@
     "url": "git+https://github.com/moondeckio/uai.git",
     "directory": "host-agent"
   },
-  "bin": {
-    "moondeck-station": "./bin/moondeck-station.mjs"
+  "bugs": {
+    "url": "https://github.com/moondeckio/uai/issues"
   },
-  "files": [
-    "bin",
-    "README.md"
+  "keywords": [
+    "ai",
+    "coding-agent",
+    "claude",
+    "codex",
+    "docker",
+    "dev-container",
+    "self-hosted",
+    "orchestrator"
   ],
+  "type": "module",
+  "bin": {
+    "moondeck-station": "bin/uai-host.mjs"
+  },
   "engines": {
-    "node": ">=22"
+    "node": "22.x || >=24 <27"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "files": [
+    "bin",
+    "src",
+    "lib",
+    "db",
+    "scripts/agent",
+    "scripts/install",
+    "runner",
+    "images/standard",
+    "ui",
+    "README.md",
+    "!**/*.test.ts",
+    "!**/*.bats",
+    "!scripts/agent/tests"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./protocol": {
+      "types": "./src/protocol.ts",
+      "default": "./src/protocol.ts"
+    },
+    "./cloud-credentials": {
+      "types": "./src/cloud-credentials.ts",
+      "default": "./src/cloud-credentials.ts"
+    },
+    "./project-env-policy": {
+      "types": "./src/project-env-policy.ts",
+      "default": "./src/project-env-policy.ts"
+    },
+    "./project-env-latest": {
+      "types": "./src/project-env-latest.ts",
+      "default": "./src/project-env-latest.ts"
+    },
+    "./project-env-wording": {
+      "types": "./src/project-env-wording.ts",
+      "default": "./src/project-env-wording.ts"
+    },
+    "./engine-models": {
+      "types": "./src/engine-models.ts",
+      "default": "./src/engine-models.ts"
+    },
+    "./engine-usage": {
+      "types": "./src/engine-usage.ts",
+      "default": "./src/engine-usage.ts"
+    },
+    "./workspace-path-policy": {
+      "types": "./src/workspace-path-policy.ts",
+      "default": "./src/workspace-path-policy.ts"
+    },
+    "./task-secrets": {
+      "types": "./src/task-secrets.ts",
+      "default": "./src/task-secrets.ts"
+    },
+    "./task-env-names": {
+      "types": "./src/task-env-names.ts",
+      "default": "./src/task-env-names.ts"
+    },
+    "./cloud-origins": {
+      "types": "./src/cloud-origins.ts",
+      "default": "./src/cloud-origins.ts"
+    },
+    "./never-proxied-domains": {
+      "types": "./src/never-proxied-domains.ts",
+      "default": "./src/never-proxied-domains.ts"
+    }
+  },
+  "scripts": {
+    "lint": "eslint .",
+    "typecheck": "tsc -p tsconfig.json",
+    "test:unit": "vitest run --config vitest.config.ts",
+    "start": "tsx src/cli.ts run",
+    "moondeck-station": "tsx src/cli.ts"
+  },
+  "dependencies": {
+    "@aws-sdk/client-ssm": "3.899.0",
+    "@sentry/node": "^10.66.0",
+    "better-sqlite3": "12.11.1",
+    "dotenv": "^16.4.5",
+    "drizzle-orm": "^0.36.0",
+    "tsx": "^4.19.2",
+    "ulid": "^2.3.0",
+    "ws": "^8.18.3",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.9.0",
+    "@types/ws": "^8.18.1",
+    "@typescript-eslint/eslint-plugin": "^8.59.4",
+    "@typescript-eslint/parser": "^8.59.4",
+    "esbuild": "0.25.8",
+    "eslint": "^9.14.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4"
   }
 }

package/runner/runner.mjs

@@ -0,0 +1,442 @@
+#!/usr/bin/env node
+/**
+ * uai session runner (ADR-061) — runs INSIDE the task container and owns an
+ * agent CLI process, so the CLI's lifetime is decoupled from the host
+ * process. The host talks to it only through files on the task-workspace
+ * bind mount (no sockets/FIFOs — they don't cross the macOS↔VM boundary):
+ *
+ *   <sessionDir>/inbox.jsonl   host appends; runner tails → CLI stdin
+ *   <sessionDir>/outbox.jsonl  CLI stdout protocol + __uai meta (connections redacted)
+ *   <sessionDir>/heartbeat     rewritten every HEARTBEAT_MS (host checks mtime)
+ *   <sessionDir>/runner.json   pid, protocol, argv, startedAt
+ *
+ * Meta lines are `{"__uai":"spawn"|"exit", ...}`; the host filters them out
+ * before handing lines to the protocol adapters. Host metadata/control lines
+ * in the inbox use the same shape (`input` timestamps and `stop`); the runner
+ * filters those, while every protocol frame goes to the CLI's stdin untouched.
+ *
+ * Plain Node ≥18, dependency-free, ESM. Testable outside docker: point it
+ * at a tmp dir and any line-oriented fake CLI.
+ *
+ * Usage: node runner.mjs <sessionDir> -- <command> [args...]
+ */
+
+import { spawn } from "node:child_process";
+import { appendFileSync, mkdirSync, openSync, readSync, fstatSync, closeSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import process from "node:process";
+
+const PROTOCOL = 1;
+const POLL_MS = 50;
+const HEARTBEAT_MS = 5_000;
+const STDERR_CAP = 8 * 1024;
+const STOP_GRACE_MS = 5_000;
+const customConnection = process.env.UAI_CUSTOM_CONNECTION === "1";
+const connectionKeys = [...new Set([
+  process.env.ANTHROPIC_AUTH_TOKEN,
+  process.env.ANTHROPIC_API_KEY,
+  process.env.UAI_CUSTOM_API_KEY,
+  process.env.AWS_BEARER_TOKEN_BEDROCK,
+].filter((key) => typeof key === "string" && key.length > 0))]
+  .sort((a, b) => b.length - a.length);
+
+function redactConnectionKeys(text) {
+  for (const key of connectionKeys) {
+    text = text.split(key).join("[redacted]".includes(key) ? "" : "[redacted]");
+  }
+  return text;
+}
+
+// Never persist upstream diagnostics from a custom endpoint: these can contain
+// credentials, request bodies or arbitrary provider responses, beyond known keys.
+function connectionReason(value) {
+  const text = typeof value === "string" ? value : JSON.stringify(value) ?? "";
+  if (/401|unauthorized|authentication_failed|unrecognized.?client|expired.?token|token.{0,80}(?:expired|revoked)|invalid.?api.?key/i.test(text)) return "unauthorized";
+  if (/403|forbidden|access.?denied/i.test(text)) return "forbidden";
+  if (/404|model.{0,30}not.found/i.test(text)) return "model-not-found";
+  if (/429|rate.?limit|throttl/i.test(text)) return "rate-limited";
+  if (/expired/i.test(text)) return "expired";
+  if (/408|timeout|timed.out/i.test(text)) return "timeout";
+  return "upstream-error";
+}
+
+function connectionError(value) {
+  const reason = connectionReason(value);
+  // JSON-RPC error responses must retain their error object and numeric code.
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? { ...(typeof value.code === "number" ? { code: value.code } : {}), message: reason }
+    : reason;
+}
+
+// Tool/model payloads can contain fields named error, result or stderrTail.
+// Preserve their meaning; only exact credentials are redacted recursively.
+function redactConnectionValue(value) {
+  if (typeof value === "string") return redactConnectionKeys(value);
+  if (Array.isArray(value)) return value.map(redactConnectionValue);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.entries(value).map(([key, item]) =>
+    [redactConnectionKeys(key), redactConnectionValue(item)]));
+}
+
+// Suppress provider diagnostics only in the CLI's protocol-level failures,
+// never an error object nested in a completed tool item or model output.
+function redactConnectionRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return redactConnectionValue(value);
+  const claudeApiError = value.type === "assistant" && value.is_api_error_message === true;
+  const claudeResultError = value.type === "result" && value.is_error === true;
+  const protocolError = claudeApiError || claudeResultError ||
+    (value.type === "system" && value.subtype === "api_retry") ||
+    value.type === "error" || value.type === "turn.failed" ||
+    (Object.hasOwn(value, "id") && value.error);
+  if (claudeApiError) {
+    value = { ...value, message: { ...value.message,
+      content: [{ type: "text", text: connectionReason(value) }] } };
+  }
+  if (protocolError) {
+    value = { ...value };
+    if (Object.hasOwn(value, "error")) value.error = connectionError(value.error);
+    if (Array.isArray(value.errors)) value.errors = value.errors.map(connectionError);
+    if (claudeResultError && Object.hasOwn(value, "result")) value.result = connectionReason(value.result);
+    if (value.type === "error") {
+      for (const key of ["message", "detail", "body"]) {
+        if (Object.hasOwn(value, key)) value[key] = connectionReason(value[key]);
+      }
+    }
+  }
+  if (value.method === "error" && value.params?.error) {
+    value = { ...value, params: { ...value.params, error: connectionError(value.params.error) } };
+  }
+  if (value.method === "turn/completed" && value.params?.turn?.status === "failed" && value.params.turn.error) {
+    value = { ...value, params: { ...value.params,
+      turn: { ...value.params.turn, error: connectionError(value.params.turn.error) } } };
+  }
+  if (value.__uai === "exit" && Object.hasOwn(value, "stderrTail")) {
+    value = { ...value, stderrTail: value.stderrTail ? connectionReason(value.stderrTail) : "" };
+  }
+  return redactConnectionValue(value);
+}
+
+function safeOutboxLine(line) {
+  if (!customConnection) return line;
+  // Wait for a complete JSON line, decode its strings before redacting, then
+  // serialize again. Replacing raw JSON bytes would miss escaped keys or corrupt
+  // quote/backslash-containing keys. Separate protocol deltas retain their shape;
+  // the host also redacts across assembled message deltas before publication.
+  try {
+    return JSON.stringify(redactConnectionRecord(JSON.parse(line)));
+  } catch {
+    return JSON.stringify({ type: "error", error: connectionReason(line) });
+  }
+}
+
+// SDK/app-server retries must not hide a rejected connection credential.
+// Restrict classification to CLI error records, never generated model text.
+let connectionFailureSeen = false;
+let connectionTransientRetries = 0;
+// Codex's built-in AWS backend has a fixed HTTP retry budget and rejects
+// retry overrides. Do not multiply that budget with another stream cycle.
+const connectionStreamRetryBudget = process.env.AWS_BEARER_TOKEN_BEDROCK &&
+  process.env.CLAUDE_CODE_USE_BEDROCK !== "1" ? 0 : 1;
+function connectionFailureFrame(value) {
+  if (!customConnection) return value;
+  if (value.method === "turn/started" || value.type === "turn.started" ||
+    (value.type === "result" && value.is_error === false)) connectionTransientRetries = 0;
+  const claudeRetry = value.type === "system" && value.subtype === "api_retry";
+  const rpcError = value.error && Object.hasOwn(value, "id");
+  const failed = claudeRetry || rpcError || value.type === "error" || value.type === "turn.failed" ||
+    (value.type === "assistant" && value.is_api_error_message === true) ||
+    (value.type === "result" && value.is_error === true) || value.method === "error" ||
+    (value.method === "turn/completed" && value.params?.turn?.status === "failed");
+  if (!failed) return value;
+  const detail = value.params?.error ?? value.params?.turn?.error ?? value.error ?? value.message ?? value.result ?? "";
+  const text = typeof detail === "string" ? detail : JSON.stringify(detail);
+  const status = value.error_status ?? detail?.status ?? detail?.statusCode ??
+    ([401, 403].includes(detail?.code) ? detail.code : undefined);
+  const auth = status === 401 || status === 403 ||
+    /\b(?:status|code|API Error:)\s*[:=]?\s*(?:401|403)\b|\b401 Unauthorized\b|\b403 Forbidden\b|authentication_failed|unrecognized.?client|access.?denied|expired.?token|invalid.?api.?key|invalid.?bearer.?token|security token.{0,80}(?:expired|invalid)/i.test(text);
+  const retry = claudeRetry || value.params?.willRetry === true ||
+    (value.type === "error" && /^Reconnecting\.\.\./.test(text));
+  if (!auth && (!retry || ++connectionTransientRetries <= connectionStreamRetryBudget)) return value;
+  const reason = auth ? (status === 403 && !/authentication_failed/i.test(text) ? "forbidden" : connectionReason(text)) : connectionReason(value);
+  const safeReason = auth && !["unauthorized", "forbidden", "expired"].includes(reason) ? "unauthorized" : reason;
+  connectionFailureSeen = true;
+  stopCli();
+  if (rpcError) return { jsonrpc: value.jsonrpc, id: value.id, error: { ...(typeof value.error.code === "number" ? { code: value.error.code } : {}), message: safeReason } };
+  if (value.method) return { method: "error", params: { threadId: value.params?.threadId,
+    turnId: value.params?.turnId, willRetry: false, error: { message: safeReason } } };
+  if (["system", "assistant", "result"].includes(value.type)) return {
+    type: "result", subtype: "error_during_execution", is_error: true,
+    result: safeReason, errors: [safeReason],
+  };
+  return { type: "error", message: safeReason };
+}
+
+// Retain only a possible credential prefix across protocol deltas. Every
+// persisted text fragment is safe when concatenated with earlier fragments.
+const deltaTails = new Map();
+let deltaTailBytes = 0;
+// Bound retained bytes, rather than stopping a healthy multi-item turn at
+// an arbitrary item count. Completed items release their state immediately.
+const DELTA_TAIL_MAX_BYTES = 4 * 1024 * 1024;
+function forgetDeltaTail(stream) {
+  const pending = deltaTails.get(stream);
+  if (pending) deltaTailBytes -= pending.bytes;
+  deltaTails.delete(stream);
+}
+function streamingDelta(value) {
+  if (value.type === "stream_event" && value.event?.type === "content_block_delta") {
+    for (const field of ["text", "thinking", "partial_json", "signature"]) {
+      if (typeof value.event.delta?.[field] === "string") {
+        return { stream: `claude:${value.event.index ?? 0}:${field}`, target: value.event.delta, field };
+      }
+    }
+  }
+  if (typeof value.method === "string" && /delta$/i.test(value.method) && typeof value.params?.delta === "string") {
+    return { stream: `codex:${value.method}:${value.params.threadId ?? ""}:${value.params.turnId ?? ""}:${value.params.itemId ?? ""}`,
+      target: value.params, field: "delta" };
+  }
+  return null;
+}
+function safeOutboxLines(line) {
+  if (!customConnection) return [line];
+  let value;
+  try { value = JSON.parse(line); } catch { return [safeOutboxLine(line)]; }
+  if (!value || typeof value !== "object") return [safeOutboxLine(line)];
+  if (connectionFailureSeen && value.__uai !== "exit") return [];
+  value = connectionFailureFrame(value);
+  const delta = streamingDelta(value);
+  if (delta) {
+    const text = redactConnectionKeys((deltaTails.get(delta.stream)?.tail ?? "") + delta.target[delta.field]);
+    let keep = 0;
+    for (const key of connectionKeys) {
+      for (let n = Math.min(key.length - 1, text.length); n > keep; n--) {
+        if (text.endsWith(key.slice(0, n))) { keep = n; break; }
+      }
+    }
+    const tail = keep ? text.slice(-keep) : "";
+    delta.target[delta.field] = keep ? text.slice(0, -keep) : text;
+    forgetDeltaTail(delta.stream);
+    if (tail) {
+      // Only retain the protocol envelope, not a potentially large provider
+      // payload or the already-persisted text.
+      const frame = value.type === "stream_event"
+        ? { type: value.type, event: { type: value.event.type, index: value.event.index,
+            delta: { type: value.event.delta.type, [delta.field]: "" } } }
+        : { method: value.method, params: { threadId: value.params.threadId,
+            turnId: value.params.turnId, itemId: value.params.itemId, delta: "" } };
+      const bytes = Buffer.byteLength(delta.stream) + Buffer.byteLength(tail) + Buffer.byteLength(JSON.stringify(frame));
+      if (deltaTailBytes + bytes > DELTA_TAIL_MAX_BYTES) {
+        stopCli();
+        return [JSON.stringify({ type: "error", error: "upstream-error" })];
+      }
+      deltaTails.set(delta.stream, { tail, frame, bytes });
+      deltaTailBytes += bytes;
+    }
+  }
+  const lines = [];
+  for (const [stream, pending] of deltaTails) {
+    const threadMatches = value.params?.threadId === undefined || pending.frame.params?.threadId === value.params.threadId;
+    const completedTurn = value.params?.turnId ?? value.params?.turn?.id;
+    const turnMatches = completedTurn === undefined || pending.frame.params?.turnId === completedTurn;
+    const terminal = value.__uai === "exit" ||
+      (value.type === "result" && pending.frame.type === "stream_event") ||
+      (value.method === "turn/completed" && pending.frame.params && threadMatches && turnMatches);
+    const claudeEnd = value.type === "stream_event" && value.event?.type === "content_block_stop" &&
+      pending.frame.type === "stream_event" && pending.frame.event.index === value.event.index;
+    const codexEnd = value.method === "item/completed" && pending.frame.params &&
+      typeof (value.params?.item?.id ?? value.params?.itemId) === "string" &&
+      pending.frame.params.itemId === (value.params.item?.id ?? value.params.itemId) &&
+      (value.params.threadId === undefined || pending.frame.params.threadId === value.params.threadId) &&
+      (value.params.turnId === undefined || pending.frame.params.turnId === value.params.turnId);
+    if (!terminal && !claudeEnd && !codexEnd) continue;
+    const d = streamingDelta(pending.frame);
+    d.target[d.field] = pending.tail;
+    lines.push(JSON.stringify(redactConnectionRecord(pending.frame)));
+    forgetDeltaTail(stream);
+  }
+  lines.push(JSON.stringify(redactConnectionRecord(value)));
+  return lines;
+}
+
+// ---- argv ------------------------------------------------------------------
+
+const sep = process.argv.indexOf("--");
+const sessionDir = process.argv[2];
+if (!sessionDir || sep < 0 || sep + 1 >= process.argv.length) {
+  process.stderr.write("usage: runner.mjs <sessionDir> -- <command> [args...]\n");
+  process.exit(2);
+}
+const command = process.argv[sep + 1];
+const args = process.argv.slice(sep + 2);
+
+mkdirSync(sessionDir, { recursive: true });
+const inboxPath = join(sessionDir, "inbox.jsonl");
+const outboxPath = join(sessionDir, "outbox.jsonl");
+const heartbeatPath = join(sessionDir, "heartbeat");
+const runnerJsonPath = join(sessionDir, "runner.json");
+
+// Single append point — appendFileSync with O_APPEND keeps lines atomic for
+// the sizes we write; the runner is the outbox's only writer.
+function outbox(line) {
+  for (const safe of safeOutboxLines(line)) {
+    appendFileSync(outboxPath, safe.endsWith("\n") ? safe : `${safe}\n`);
+  }
+}
+function meta(kind, extra = {}) {
+  outbox(JSON.stringify({ __uai: kind, ts: Date.now(), ...extra }));
+}
+
+// ---- the CLI ---------------------------------------------------------------
+
+// The runner is launched through the container's asdf `node` shim, which
+// exports its resolved version (ASDF_NODEJS_VERSION et al.) into our env.
+// Passing that through would pin the CLI's own asdf shim to the WORKSPACE's
+// node version — "No claude executable found for nodejs X" when the agent
+// CLIs are installed under a different one. So strip the per-tool VERSION
+// PINS only (ASDF_NODEJS_VERSION, ASDF_<TOOL>_VERSION) — NOT the whole ASDF_*
+// namespace: ASDF_DATA_DIR (/opt/asdf-data) and ASDF_DIR (/opt/asdf) tell the
+// shim's `asdf exec` WHERE the tools live. Drop those and asdf falls back to
+// $HOME/.asdf (empty), so EVERY shim aborts with "unknown command: codex.
+// Perhaps you have to reshim?" (exit 1) — the codex/claude resume failure on
+// every host restart, host 0.8.32. `ASDF_VERSION` (asdf's own version) has no
+// middle segment, so the pin regex leaves it — harmless either way.
+const cliEnv = { ...process.env };
+for (const key of Object.keys(cliEnv)) {
+  if (/^ASDF_.+_VERSION$/.test(key)) delete cliEnv[key];
+}
+
+const child = spawn(command, args, { stdio: ["pipe", "pipe", "pipe"], env: cliEnv });
+
+writeFileSync(
+  runnerJsonPath,
+  JSON.stringify({
+    protocol: PROTOCOL,
+    runnerPid: process.pid,
+    cliPid: child.pid ?? null,
+    command,
+    args,
+    startedAt: Date.now(),
+  }),
+);
+meta("spawn", { protocol: PROTOCOL, runnerPid: process.pid, cliPid: child.pid ?? null });
+
+let stderrTail = "";
+child.stderr?.setEncoding("utf8");
+child.stderr?.on("data", (chunk) => {
+  stderrTail = (stderrTail + chunk).slice(-STDERR_CAP);
+});
+
+// CLI stdout → outbox, complete lines only (partial line buffered).
+let stdoutBuf = "";
+child.stdout?.setEncoding("utf8");
+child.stdout?.on("data", (chunk) => {
+  stdoutBuf += chunk;
+  for (;;) {
+    const nl = stdoutBuf.indexOf("\n");
+    if (nl < 0) break;
+    const line = stdoutBuf.slice(0, nl);
+    stdoutBuf = stdoutBuf.slice(nl + 1);
+    if (line.trim().length > 0) outbox(line);
+  }
+});
+
+let exiting = false;
+child.on("exit", (code, signal) => {
+  if (exiting) return;
+  exiting = true;
+  if (stdoutBuf.trim().length > 0) outbox(stdoutBuf); // flush the partial tail
+  meta("exit", { code: connectionFailureSeen ? 1 : code, signal: signal ?? null, stderrTail });
+  process.exit(0);
+});
+child.on("error", (err) => {
+  if (exiting) return;
+  exiting = true;
+  meta("exit", { code: null, signal: null, stderrTail: String(err?.message ?? err) });
+  process.exit(0);
+});
+
+// ---- inbox tail → CLI stdin --------------------------------------------------
+
+let inboxOffset = 0; // fresh session dir per spawn — always start at 0
+let inboxBuf = "";
+
+function stopCli() {
+  if (exiting) return;
+  try {
+    child.kill("SIGTERM");
+  } catch {
+    /* already gone */
+  }
+  setTimeout(() => {
+    try {
+      child.kill("SIGKILL");
+    } catch {
+      /* already gone */
+    }
+  }, STOP_GRACE_MS).unref();
+}
+
+function handleInboxLine(line) {
+  if (line.trim().length === 0) return;
+  if (line.startsWith('{"__uai"')) {
+    try {
+      const ctl = JSON.parse(line);
+      if (ctl.__uai === "stop") stopCli();
+    } catch {
+      /* malformed control — ignore */
+    }
+    return;
+  }
+  try {
+    child.stdin?.write(`${line}\n`);
+  } catch {
+    /* EPIPE after CLI death — the exit meta already tells the host */
+  }
+}
+
+function pollInbox() {
+  let fd;
+  try {
+    fd = openSync(inboxPath, "r");
+  } catch {
+    return; // inbox not created yet
+  }
+  try {
+    const size = fstatSync(fd).size;
+    if (size > inboxOffset) {
+      const len = size - inboxOffset;
+      const buf = Buffer.alloc(len);
+      const read = readSync(fd, buf, 0, len, inboxOffset);
+      inboxOffset += read;
+      inboxBuf += buf.toString("utf8", 0, read);
+      for (;;) {
+        const nl = inboxBuf.indexOf("\n");
+        if (nl < 0) break;
+        const line = inboxBuf.slice(0, nl);
+        inboxBuf = inboxBuf.slice(nl + 1);
+        handleInboxLine(line);
+      }
+    }
+  } finally {
+    closeSync(fd);
+  }
+}
+
+setInterval(pollInbox, POLL_MS);
+
+// ---- heartbeat ---------------------------------------------------------------
+
+function beat() {
+  try {
+    writeFileSync(heartbeatPath, `${process.pid} ${Date.now()}\n`);
+  } catch {
+    /* disk hiccup — next beat retries */
+  }
+}
+beat();
+setInterval(beat, HEARTBEAT_MS);
+
+// The runner dies only with its CLI (or on stop/SIGTERM) — never because a
+// host-side consumer went away. That is the entire point (ADR-061).
+process.on("SIGTERM", stopCli);
+process.on("SIGINT", stopCli);