omp-conductor 0.18.0 → 0.18.2

package/src/host.ts

@@ -3,9 +3,11 @@
  * or the tracker. Pure so tests pin the thresholds without a real machine.
  */
 
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { spawnSync } from "node:child_process";
-import { DEFAULT_CAPS } from "./types.ts";
+import { availableParallelism } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { DEFAULT_CAPS, type HostConstraints } from "./types.ts";
 
 /** 16 GiB — below this, two in-process omp sessions plus the orchestrator are
  *  a measured swap risk on a shared VPS (issue #51: 3–4GB peaks on 7.6GB). */
@@ -78,6 +80,86 @@ export function workerOvercommit(total: number, ram?: number | undefined): strin
     : undefined;
 }
 
+/**
+ * CPU cores this process can actually use — affinity- and quota-aware, which
+ * is the load a worker would really get on a shared host. `undefined` mirrors
+ * {@link hostRamBytes}: the renderer simply omits the count.
+ */
+export function hostCoreCount(): number | undefined {
+  try {
+    return availableParallelism();
+  } catch {
+    return undefined;
+  }
+}
+
+/** What {@link hostFacts} reads off the host; injectable for render tests. */
+export interface HostFacts {
+  cores?: number;
+  ramBytes?: number;
+}
+
+/**
+ * The host's numbers through the module's own readers — the same
+ * {@link hostRamBytes} the capacity decision and the wizard use, plus the
+ * core count — so the rendered brief, the worker-count recommendation and
+ * the status surfaces can never disagree about the box they run on. This is
+ * the default the brief renderer reaches for; tests inject facts instead.
+ */
+export function hostFacts(): HostFacts {
+  return { cores: hostCoreCount(), ramBytes: hostRamBytes() };
+}
+
+/**
+ * The usable-size phrase the brief folds into the host line (`4 cores,
+ * 3.2 GB`); empty when the host will not say either number.
+ */
+function hostSizePhrase(facts: HostFacts): string {
+  const parts: string[] = [];
+  if (facts.cores !== undefined) parts.push(`${facts.cores} cores`);
+  if (facts.ramBytes !== undefined) parts.push(formatRss(facts.ramBytes));
+  return parts.join(", ");
+}
+
+/**
+ * The worker-brief host-constraints paragraph (#721): the typed replacement
+ * for host facts hand-written into an untracked agent context file. Cores and
+ * RAM come from {@link hostFacts} (the module's own readers) and are folded
+ * into the operator's description; the PATH and per-repo convention lines are
+ * typed config. It never names a guarded command — the shared-host notice,
+ * derived from `SHARED_HOST_SCRIPTS`, stays the only list of refused suites.
+ *
+ * Empty when nothing renders — no section, and the brief is byte-for-byte
+ * today's for a fleet that never fills the config field. `facts` is a
+ * parameter so tests pin the rendering deterministically; the dispatch default
+ * is {@link hostFacts}. The return has no trailing newline and leads with one
+ * when non-empty, so the template can render it on the line below the
+ * shared-host notice without gluing the two paragraphs.
+ */
+export function hostConstraintsNotice(
+  host: HostConstraints | undefined,
+  repoSlug: string,
+  facts: HostFacts = hostFacts(),
+): string {
+  if (host === undefined) return "";
+
+  const lines: string[] = [];
+  const description = host.description?.trim();
+  if (description !== undefined && description !== "") {
+    const size = hostSizePhrase(facts);
+    lines.push(`**Host:** ${description}${size === "" ? "" : ` (${size})`}`);
+  }
+  const path = host.path?.trim();
+  if (path !== undefined && path !== "") {
+    lines.push(`**PATH:** non-interactive invocations (scripts and \`ssh host '<cmd>'\`) must export PATH="${path}".`);
+  }
+  const convention = host.conventions?.[repoSlug]?.trim();
+  if (convention !== undefined && convention !== "") {
+    lines.push(`**Convention (${repoSlug}):** ${convention}`);
+  }
+  return lines.length === 0 ? "" : `\n${lines.join("\n\n")}`;
+}
+
 /** Compact binary units for status lines (`3.2 GB`, `430 MB`). */
 export function formatRss(bytes: number): string {
   if (!Number.isFinite(bytes) || bytes < 0) return "?";
@@ -104,3 +186,161 @@ export function rssBytesFromHealthz(body: string | undefined): number | undefine
     return undefined;
   }
 }
+
+// ------------------------------------------------------- worker host state (#894) --
+
+/**
+ * The dedicated worker account earlier boundary slices created on this host.
+ *
+ * Worker sessions no longer launch under it (#894 restored the fleet-account
+ * runtime v0.18.0 used): the constants below survive only so `setup host` can
+ * keep staging and recognising the units it once installed until #895 retires
+ * that host lifecycle end to end. Nothing on the session-launch path reads
+ * them.
+ */
+export const WORKER_ACCOUNT = "omp-worker";
+
+/** The worker account's system home: its harness config, caches and state. */
+export const WORKER_HOME_DIR = "/var/lib/omp-worker";
+
+/**
+ * The harness package omp-conductor loads a session from. Held here, beside
+ * the identity that has to reach it, so `omp.ts` (which imports it) and the
+ * binding checks below can never name two different packages.
+ */
+export const OMP_HARNESS_PACKAGE = "@oh-my-pi/pi-coding-agent";
+
+/** Native addon package the harness imports at runtime. */
+export const OMP_NATIVES_PACKAGE = "@oh-my-pi/pi-natives";
+
+/**
+ * Where `setup host` binds the operator's install so a worker session can
+ * resolve it (#828).
+ *
+ * Bun's node_modules resolution needs **read** permission — not merely search
+ * — on the directory that holds a `node_modules`: it enumerates the directory
+ * to decide whether the child is there. The fleet account's home is granted to
+ * the worker search-only by design (#798), so a bare `@oh-my-pi/pi-coding-agent`
+ * import from `<fleet home>/node_modules/omp-conductor` did not find the
+ * operator's install at all and fell through to Bun's auto-install, which
+ * downloaded a *different* harness version into the worker's own cache whose
+ * native addon then failed to load — every dispatch on the host stopped before
+ * session start.
+ *
+ * The fix is a read-only bind of the operator's `node_modules` at a path whose
+ * every ancestor is world-readable. Worker children are launched from it, so
+ * the entry module, the peer import and every transitive import resolve inside
+ * one tree the worker can enumerate — and, because a bind shares inodes with
+ * its source, it is the operator's exact build rather than a copy that can
+ * drift.
+ *
+ * Deliberately **not** under {@link WORKER_HOME_DIR}: the worker owns its home
+ * between setups, and a symlink planted where a root-run mount point goes would
+ * redirect that mount to an arbitrary target (#816).
+ */
+export const WORKER_HARNESS_DIR = "/var/lib/omp-worker-harness";
+
+/** The bound `node_modules` itself. The leaf name is load-bearing: it is what
+ *  Node/Bun resolution looks for walking up from the entry module. */
+export const WORKER_HARNESS_NODE_MODULES = join(WORKER_HARNESS_DIR, "node_modules");
+
+/**
+ * The install root a module path sits in — its nearest ancestor named
+ * `node_modules` — or `undefined` when it has none, which is this package
+ * running from a source checkout rather than an install.
+ */
+export function packageNodeModulesRoot(modulePath: string): string | undefined {
+  const parts = resolve(modulePath)
+    .split("/")
+    .filter((part) => part !== "");
+  const idx = parts.lastIndexOf("node_modules");
+  return idx < 0 ? undefined : `/${parts.slice(0, idx + 1).join("/")}`;
+}
+
+/**
+ * `path` as a worker session sees it through the harness binding, or
+ * `undefined` when it is not inside `packageRoot` — a test seam pointing at a
+ * file elsewhere, or a source checkout with no install root at all.
+ *
+ * Production uses {@link WORKER_HARNESS_NODE_MODULES}; an explicit binding
+ * root lets the Linux regression build the same inode-sharing tree under its
+ * private temporary directory instead of touching the live host mount.
+ */
+export function workerHarnessPath(
+  path: string,
+  packageRoot: string | undefined,
+  bindingRoot: string = WORKER_HARNESS_NODE_MODULES,
+): string | undefined {
+  if (packageRoot === undefined) return undefined;
+  const absolute = resolve(path);
+  const prefix = `${packageRoot}/`;
+  if (!absolute.startsWith(prefix)) return undefined;
+  return join(bindingRoot, absolute.slice(prefix.length));
+}
+
+/** One path's filesystem identity. Identity rather than bytes, because that is
+ *  exactly what distinguishes a live bind of the operator's install (same
+ *  device and inode) from an empty mount point or a copy that has drifted. */
+function pathIdentity(path: string): string | undefined {
+  try {
+    const st = statSync(path);
+    return `${st.dev}:${st.ino}`;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Read-only facts {@link harnessBindingProblem} decides on; injected by tests. */
+export interface HarnessBindingDeps {
+  /** This module's own directory — the install root is derived from it. */
+  moduleDir?: string;
+  /** `dev:ino` of one path, or `undefined` when it cannot be stat'ed. */
+  identity?: (path: string) => string | undefined;
+  /** Alternate binding root for the isolated Linux currentness regression. */
+  bindingRoot?: string;
+}
+
+/**
+ * Why a worker session could not load the operator's harness through the
+ * binding, or `undefined` when it can.
+ *
+ * Both halves of the launch are checked, by filesystem identity: this package's
+ * own directory (the child's entry module comes from it) and the harness
+ * package directory (its peer import resolves to it). A mount point that is
+ * empty, stale, or bound to some other tree fails on the identity comparison
+ * rather than being taken on faith — which is the whole point, since the
+ * symptom this replaces was a *successful* import of the wrong build.
+ */
+export function harnessBindingProblem(deps: HarnessBindingDeps = {}): string | undefined {
+  const moduleDir = deps.moduleDir ?? import.meta.dir;
+  const identity = deps.identity ?? pathIdentity;
+  const bindingRoot = deps.bindingRoot ?? WORKER_HARNESS_NODE_MODULES;
+  const packageRoot = packageNodeModulesRoot(moduleDir);
+  if (packageRoot === undefined) {
+    return (
+      `omp-conductor is running from ${moduleDir}, which is not inside a node_modules install root — ` +
+      "a worker session resolves its harness through a read-only bind of that root, so worker dispatch " +
+      "needs the installed package (install omp-conductor with its harness peer, then re-run `omp-conductor setup host`)"
+    );
+  }
+  for (const dir of [moduleDir, join(packageRoot, OMP_HARNESS_PACKAGE)]) {
+    const source = identity(dir);
+    if (source === undefined) {
+      return (
+        `${dir} is missing or unreadable — ${OMP_HARNESS_PACKAGE} must be installed alongside omp-conductor ` +
+        "for a worker session to load the same harness build the operator runs"
+      );
+    }
+    // Non-null by construction: `dir` is inside `packageRoot`.
+    const bound = workerHarnessPath(dir, packageRoot, bindingRoot) ?? dir;
+    if (identity(bound) !== source) {
+      return (
+        `${bound} does not resolve to ${dir} — the worker harness binding of ${packageRoot} at ` +
+        `${bindingRoot} is missing or stale, so a worker session would resolve a different ` +
+        "harness build (or none). Run `omp-conductor setup host` to establish it"
+      );
+    }
+  }
+  return undefined;
+}
+

package/src/lifecycle.ts

@@ -53,7 +53,7 @@ const READY_TIMEOUT_MS = 15_000;
 const READY_POLL_MS = 250;
 
 /** `/healthz` is a local, in-memory answer; a slow one means something is wrong. */
-const HEALTH_TIMEOUT_MS = 1_500;
+export const HEALTH_TIMEOUT_MS = 1_500;
 
 /** Default grace period between `SIGTERM` and `SIGKILL`. */
 const STOP_TIMEOUT_MS = 10_000;
@@ -963,6 +963,127 @@ export function systemdMainPid(unit = SYSTEMD_UNIT): number | undefined {
   return ownership.kind === "active" ? ownership.pid : undefined;
 }
 
+/**
+ * The run-control endpoint the `worker` verbs may address.
+ *
+ * `record` is the pidfile's own answer: the record port is authoritative
+ * because the daemon itself wrote it, and the record's `project` (when set)
+ * rides along so callers keep refusing a record pinned to another project
+ * exactly as before. `unit` is the systemd answer for a missing or stale
+ * record: the unit is active, its MainPID is alive, and `/healthz` on the
+ * probe port proved a conductor daemon serving `expectedProject` — the port
+ * was located, not assumed. `unserved` is that same live unit when no port
+ * proved itself: the daemon is running but its control address cannot be
+ * located, so callers must refuse rather than guess. `unknown` is the
+ * manager-failure answer: the unit's ownership could not be read (bus,
+ * permission, timeout), so neither running nor stopped is provable and the
+ * callers must refuse — collapsing that into `none` is how a control verb
+ * lies "daemon is not running" while the unit is up. `none` is the confirmed
+ * negative: no record, and no unit with a live MainPID.
+ */
+export type DaemonControlTarget =
+  | { kind: "record"; pid: number; port: number; project?: string }
+  | { kind: "unit"; pid: number; port: number }
+  | { kind: "unserved"; pid: number; port: number }
+  | { kind: "unknown"; reason: string }
+  | { kind: "none" };
+
+/**
+ * The port a unit-run daemon is probed on when the pidfile is absent: the
+ * generated unit always pins `--port` 8787 (`DEFAULT_PORT`), so that is the
+ * default candidate. The port is verified by `/healthz` before it is used —
+ * a listener is never trusted for being on the default port alone (#811).
+ *
+ * A test process redirects the probe with `OMP_CONDUCTOR_TEST_DAEMON_PORT`,
+ * the same seam discipline as `OMP_CONDUCTOR_TEST_SYSTEMCTL_STATE`: a CLI
+ * test cannot bind the real 8787 (the host's actual daemon may answer, the
+ * #399 failure mode), so its fake unit daemon serves on an ephemeral port
+ * that the state names.
+ */
+function controlProbePort(): number {
+  if (process.env["NODE_ENV"] === "test") {
+    const override = process.env["OMP_CONDUCTOR_TEST_DAEMON_PORT"];
+    if (override !== undefined && override.trim() !== "") {
+      const port = Number.parseInt(override.trim(), 10);
+      if (Number.isInteger(port) && port > 0 && port <= 65535) return port;
+    }
+  }
+  return DEFAULT_PORT;
+}
+
+/**
+ * Resolve the running daemon's pid + port for the run-control verbs, or prove
+ * the daemon is not running. The pidfile is authoritative while the process
+ * it names is alive; when it is missing or stale, the systemd unit is the
+ * liveness witness — the same consultation `status` performs (#716): an
+ * active unit whose MainPID is alive proves the daemon runs even though no
+ * record pins its port. The port is never assumed: `/healthz` on the probe
+ * port must prove a conductor daemon answering for `expectedProject` before
+ * that address is offered as something to operate (#811).
+ *
+ * Never throws — the caller decides whether `unserved` (a live unit with no
+ * proved endpoint) or `none` (nothing running) is the answer to give.
+ */
+export async function daemonControlTarget(
+  expectedProject?: string,
+): Promise<DaemonControlTarget> {
+  const record = livingDaemon();
+  if (record !== undefined) {
+    return {
+      kind: "record",
+      pid: record.pid,
+      port: record.port,
+      ...(record.project === undefined ? {} : { project: record.project }),
+    };
+  }
+  const ownership = probeUnit();
+  // A manager query the manager could not answer is not "no unit": collapsing
+  // it into `none` is exactly how a control verb reports a live unit-owned
+  // daemon stopped. The caller must refuse on the honest indeterminacy.
+  if (ownership.kind === "unknown") return { kind: "unknown", reason: ownership.reason };
+  if (ownership.kind !== "active" || !isAlive(ownership.pid)) return { kind: "none" };
+  const port = controlProbePort();
+  const health = await healthCheck(port);
+  if (!health.ok || !healthServesProject(health.body, expectedProject)) {
+    return { kind: "unserved", pid: ownership.pid, port };
+  }
+  return { kind: "unit", pid: ownership.pid, port };
+}
+
+/**
+ * The reachable { pid, port } a run-control verb may operate, or the refusal
+ * that names why it cannot. The refusal language is one shared place so
+ * `worker` and `extend` cannot drift apart on the same endpoint questions:
+ * `none` is the plain "not running"; a record pinned to another project is
+ * the same refusal the verbs always gave; an unprovable live unit and an
+ * unknown manager state both fail closed instead of contacting anything or
+ * claiming the daemon stopped.
+ */
+export async function requireDaemonControl(
+  expectedProject: string,
+): Promise<{ pid: number; port: number }> {
+  const target = await daemonControlTarget(expectedProject);
+  if (target.kind === "none") throw new Error("daemon is not running");
+  if (target.kind === "unknown") {
+    throw new Error(
+      `cannot determine whether ${SYSTEMD_UNIT} is running (${target.reason}) — ` +
+        `refusing to send run control while liveness is unknown; ` +
+        `retry when systemctl answers, or check \`systemctl status ${SYSTEMD_UNIT}\``,
+    );
+  }
+  if (target.kind === "record" && target.project !== undefined && target.project !== expectedProject) {
+    throw new Error(
+      `daemon serves project "${target.project}", not requested project "${expectedProject}"`,
+    );
+  }
+  if (target.kind === "unserved") {
+    throw new Error(
+      `daemon is running (${SYSTEMD_UNIT} pid ${target.pid}) but not serving /healthz for project "${expectedProject}" on port ${target.port} — no run-control endpoint could be located, so nothing was changed`,
+    );
+  }
+  return { pid: target.pid, port: target.port };
+}
+
 // ---------------------------------------------------------------------------
 // internals
 // ---------------------------------------------------------------------------

package/src/omp-settings.ts

@@ -36,6 +36,25 @@ import type { ProjectConfig } from "./types.ts";
 /** The overlay filename inside a run's session directory. */
 export const OMP_SETTINGS_FILE = "omp-settings.yml";
 
+/**
+ * The OMP model-role names one settings map declares — the keys of its
+ * `modelRoles` stanza (#875). This is the one grammar every surface that
+ * names an adjudicator role reads: omp's own `modelRoles` config, whether it
+ * sits in the daemon account's global settings, a project's overlay, or both.
+ * Anything that is not a flat string-map names no roles at all — an overlay
+ * whose `modelRoles` is, say, a YAML list is omp's to reject, and offering
+ * garbage role names here would only train the setup dialog on values OMP
+ * would refuse. `null` and any other non-object input — including an empty
+ * or comments-only settings file whose YAML parses to `null` — is zero
+ * roles, never a fault.
+ */
+export function modelRolesIn(settings: unknown): readonly string[] {
+  if (settings === null || typeof settings !== "object" || Array.isArray(settings)) return [];
+  const roles = (settings as Record<string, unknown>)["modelRoles"];
+  if (roles === null || typeof roles !== "object" || Array.isArray(roles)) return [];
+  return Object.keys(roles as Record<string, unknown>);
+}
+
 /**
  * The effective overlay map for a project: the opaque `ompSettings` map plus
  * the retry keys (`retry.modelFallback`, `retry.fallbackChains.default`)