omp-conductor 0.3.13 → 0.3.15

package/src/host.ts

@@ -0,0 +1,90 @@
+/**
+ * Host facts the wizard and status surfaces need without dragging in systemd
+ * or the tracker. Pure so tests pin the thresholds without a real machine.
+ */
+
+import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { DEFAULT_CAPS } 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). */
+export const SMALL_HOST_RAM_BYTES = 16 * 1024 ** 3;
+
+/**
+ * MemTotal from a `/proc/meminfo` body, in bytes. kB × 1024, matching what
+ * Linux reports; undefined when the line is missing or unparsable.
+ */
+export function ramBytesFromMeminfo(text: string): number | undefined {
+  const m = /^MemTotal:\s+(\d+)\s+kB\s*$/m.exec(text);
+  if (m === null) return undefined;
+  const kib = Number(m[1]);
+  if (!Number.isFinite(kib) || kib <= 0) return undefined;
+  return kib * 1024;
+}
+
+/** Darwin `sysctl -n hw.memsize` stdout → bytes. */
+export function ramBytesFromSysctl(raw: string): number | undefined {
+  const n = Number(raw.trim());
+  if (!Number.isFinite(n) || n <= 0) return undefined;
+  return n;
+}
+
+/**
+ * Total installed RAM when the host will say, otherwise undefined. Never
+ * throws: a container without /proc or a locked-down sysctl is "unknown", and
+ * callers fall back to the shipped worker default.
+ */
+export function hostRamBytes(): number | undefined {
+  if (process.platform === "linux") {
+    try {
+      return ramBytesFromMeminfo(readFileSync("/proc/meminfo", "utf8"));
+    } catch {
+      return undefined;
+    }
+  }
+  if (process.platform === "darwin") {
+    const ran = spawnSync("sysctl", ["-n", "hw.memsize"], { encoding: "utf8" });
+    if (ran.status !== 0 || ran.stdout === null) return undefined;
+    return ramBytesFromSysctl(ran.stdout);
+  }
+  return undefined;
+}
+
+/**
+ * Setup default for `maxConcurrentWorkers`. Small hosts get 1; everyone else
+ * keeps {@link DEFAULT_CAPS.maxConcurrentWorkers}. Unknown RAM keeps the
+ * shipped default — guessing low would silently halve throughput on a beefy
+ * box whose /proc we cannot read.
+ */
+export function recommendedMaxWorkers(ramBytes: number | undefined): number {
+  if (ramBytes === undefined) return DEFAULT_CAPS.maxConcurrentWorkers;
+  return ramBytes < SMALL_HOST_RAM_BYTES ? 1 : DEFAULT_CAPS.maxConcurrentWorkers;
+}
+
+/** Compact binary units for status lines (`3.2 GB`, `430 MB`). */
+export function formatRss(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes < 0) return "?";
+  const gb = bytes / 1024 ** 3;
+  if (gb >= 1) return `${gb.toFixed(1)} GB`;
+  const mb = bytes / 1024 ** 2;
+  if (mb >= 1) return `${mb.toFixed(0)} MB`;
+  return `${Math.round(bytes / 1024)} KB`;
+}
+
+/**
+ * `rssBytes` from a `/healthz` JSON body. Old daemons omit the field; garbage
+ * answers undefined rather than NaN so status can hide the line.
+ */
+export function rssBytesFromHealthz(body: string | undefined): number | undefined {
+  if (body === undefined || body.length === 0) return undefined;
+  try {
+    const parsed: unknown = JSON.parse(body);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+    const n = (parsed as { rssBytes?: unknown }).rssBytes;
+    if (typeof n !== "number" || !Number.isFinite(n) || n < 0) return undefined;
+    return n;
+  } catch {
+    return undefined;
+  }
+}

package/src/lifecycle.ts

@@ -313,39 +313,34 @@ export async function stopDaemon(o: { timeoutMs?: number } = {}): Promise<StopRe
     // `livingDaemon` already cleared a stale file; this covers the unparseable
     // one it refused to read. Still ask systemd: a unit can be running with
     // no pidfile (boot race, wiped runtime dir) and stop must still land.
-    const unitPid = systemdMainPid();
-    if (unitPid !== undefined && (await stopViaSystemd(undefined))) {
-      const deadline = Date.now() + (o.timeoutMs ?? STOP_TIMEOUT_MS);
-      while (isAlive(unitPid) && Date.now() < deadline) await sleep(100);
-      if (isAlive(unitPid)) {
-        throw new Error(
-          `daemon pid ${unitPid} still alive after systemctl stop ${SYSTEMD_UNIT} — ` +
-            `check \`systemctl status ${SYSTEMD_UNIT}\``,
-        );
-      }
+    const decision = decideSystemdStop(undefined);
+    if (decision.kind === "unknown") {
+      throw new Error(ownershipUnknown("stop", decision.reason));
+    }
+    if (decision.kind === "stop") {
+      await runSystemdStop(decision.mainPid, o.timeoutMs);
       clearRecord();
-      return { kind: "stopped", pid: unitPid, via: "systemctl" };
+      return { kind: "stopped", pid: decision.mainPid, via: "systemctl" };
     }
     clearRecord();
     return { kind: "not-running" };
   }
 
-  if (await stopViaSystemd(rec.pid)) {
-    // Wait out the unit: systemctl stop is synchronous for Type=simple, but
-    // a slow drain still holds the old pid briefly and the next start would
-    // refuse against it.
-    const deadline = Date.now() + (o.timeoutMs ?? STOP_TIMEOUT_MS);
-    while (isAlive(rec.pid) && Date.now() < deadline) await sleep(100);
-    if (isAlive(rec.pid)) {
-      throw new Error(
-        `daemon pid ${rec.pid} still alive after systemctl stop ${SYSTEMD_UNIT} — ` +
-          `check \`systemctl status ${SYSTEMD_UNIT}\``,
-      );
-    }
+  const decision = decideSystemdStop(rec.pid);
+  if (decision.kind === "unknown") {
+    // Pidfile stays: we could not prove the unit does *not* own this pid, and
+    // signalling it under that uncertainty is the bounce under Restart=on-failure.
+    throw new Error(ownershipUnknown("stop", decision.reason));
+  }
+  if (decision.kind === "stop") {
+    await runSystemdStop(rec.pid, o.timeoutMs);
     clearRecord();
     return { kind: "stopped", pid: rec.pid, via: "systemctl" };
   }
 
+  // decision.kind === "not-ours": confirmed no unit, inactive unit, no systemd
+  // binary, or a unit whose MainPID is somebody else. Only a *confirmed*
+  // negative is safe to signal.
   const gone = await terminate(rec.pid, o.timeoutMs ?? STOP_TIMEOUT_MS);
   if (!gone) {
     // The record stays: something is still holding that pid, and forgetting
@@ -360,11 +355,11 @@ export async function stopDaemon(o: { timeoutMs?: number } = {}): Promise<StopRe
  * Restarts the daemon.
  *
  * Same ownership rule as {@link stopDaemon}: when the unit owns the live pid,
- * `systemctl restart` keeps systemd in charge of the replacement process so
- * the new MainPID is still the unit's. Falling back to stop+start for a
- * hand-started daemon would leave the unit dead and the new process
- * unsupervised — fine for a laptop, wrong for the host that installed a unit
- * specifically so a crash comes back.
+ * `systemctl restart` is the *only* path — a failed manager call is terminal,
+ * never a fallthrough to raw signals. An *unanswered* ownership query is also
+ * terminal: "dbus blipped" is not "no unit". Falling back to stop+start is
+ * reserved for a confirmed hand-started daemon (no systemd, inactive unit, or
+ * a unit whose MainPID is someone else).
  *
  * Returns the record of the process that is now answering `/healthz`.
  */
@@ -372,34 +367,38 @@ export async function restartDaemon(
   o: { port?: number; project?: string; timeoutMs?: number } = {},
 ): Promise<{ previous: DaemonRecord | undefined; record: DaemonRecord; via: "systemctl" | "cli" }> {
   const previous = livingDaemon();
-  const unitPid = systemdMainPid();
+  const ownership = probeUnit();
+  if (ownership.kind === "unknown") {
+    throw new Error(ownershipUnknown("restart", ownership.reason));
+  }
+
   const unitOwns =
-    unitPid !== undefined && (previous === undefined || previous.pid === unitPid);
+    ownership.kind === "active" && (previous === undefined || previous.pid === ownership.pid);
 
   if (unitOwns) {
+    // Ownership is proven. A refused/timed-out restart must not fall through
+    // to stopDaemon's signal path — that is the exact bounce this module exists
+    // to prevent (SIGTERM → exit 143 → Restart=on-failure → new MainPID).
     const ran = systemctl(["restart", SYSTEMD_UNIT]);
-    if (ran.ok) {
-      // systemctl restart returns once the new MainPID is up; the pidfile is
-      // written by the daemon itself on boot, so wait for that rather than
-      // inventing a record from the unit alone.
-      const deadline = Date.now() + READY_TIMEOUT_MS;
-      for (;;) {
-        const rec = livingDaemon();
-        if (rec !== undefined) {
-          const health = await healthCheck(rec.port);
-          if (health.ok) return { previous, record: rec, via: "systemctl" };
-        }
-        if (Date.now() >= deadline) break;
-        await sleep(READY_POLL_MS);
+    if (!ran.ok) {
+      throw new Error(systemctlFailure("restart", ran));
+    }
+    // systemctl restart returns once the new MainPID is up; the pidfile is
+    // written by the daemon itself on boot, so wait for that rather than
+    // inventing a record from the unit alone.
+    const deadline = Date.now() + READY_TIMEOUT_MS;
+    for (;;) {
+      const rec = livingDaemon();
+      if (rec !== undefined) {
+        const health = await healthCheck(rec.port);
+        if (health.ok) return { previous, record: rec, via: "systemctl" };
       }
-      throw new Error(
-        `systemctl restart ${SYSTEMD_UNIT} returned, but the daemon never answered /healthz`,
-      );
+      if (Date.now() >= deadline) break;
+      await sleep(READY_POLL_MS);
     }
-    // Unit exists and owns the pid but systemctl refused (permissions, dbus
-    // down). Fall through to the signal path rather than stranding the
-    // operator with "restart failed" and a still-running daemon they cannot
-    // reach through the unit.
+    throw new Error(
+      `systemctl restart ${SYSTEMD_UNIT} returned, but the daemon never answered /healthz`,
+    );
   }
 
   await stopDaemon({ timeoutMs: o.timeoutMs });
@@ -408,32 +407,70 @@ export async function restartDaemon(
 }
 
 /**
- * The MainPID of {@link SYSTEMD_UNIT}, or `undefined` when systemd is absent,
- * the unit is unknown, or it is not running. Never throws: a missing binary
- * or a dbus blip is "no unit", and stop falls back to SIGTERM.
+ * What we know about {@link SYSTEMD_UNIT}.
+ *
+ * - `active` — unit has a live MainPID (> 1). Includes transitional manager
+ *   states (`activating`, `deactivating`, `reloading`, `reactivating`) — the
+ *   pid is still systemd-owned, so a raw SIGTERM would bounce under
+ *   `Restart=on-failure`.
+ * - `inactive` — confirmed not running (MainPID absent/0), unit absent, *or*
+ *   no `systemctl` binary on this host. Safe to treat as "not supervised here".
+ * - `unknown` — the manager exists (or we cannot tell it does not) but the
+ *   query failed: dbus blip, permission, timeout. Must not be collapsed into
+ *   `inactive` — that is how a unit-owned daemon gets a raw SIGTERM.
  */
-export function systemdMainPid(unit = SYSTEMD_UNIT): number | undefined {
+export type UnitOwnership =
+  | { kind: "active"; pid: number }
+  | { kind: "inactive" }
+  | { kind: "unknown"; reason: string };
+
+/**
+ * Probe {@link SYSTEMD_UNIT} ownership. Never throws — the caller decides
+ * whether `unknown` is fatal (stop/restart: yes).
+ */
+export function probeUnit(unit = SYSTEMD_UNIT): UnitOwnership {
   const ran = systemctl(["show", unit, "--property=MainPID", "--property=ActiveState", "--value"]);
-  if (!ran.ok) return undefined;
+  if (!ran.ok) {
+    // No binary at all → this host has no systemd manager, so nothing here can
+    // be unit-owned. Any other failure (dbus, auth, timeout) is unknown.
+    if (ran.missing) return { kind: "inactive" };
+    const detail = (ran.stderr.trim() || ran.stdout.trim() || "systemctl show failed").split("\n")[0]!;
+    return { kind: "unknown", reason: detail };
+  }
   // `systemctl show --value` prints one property per line, MainPID then
   // ActiveState, in the order requested. Tolerate either order and blank
   // lines so a future systemctl rearrange does not silently disable the path.
+  // Unknown units still exit 0 with `0` / `inactive`, which is the confirmed
+  // negative we want — not an error.
+  //
+  // Ownership is the MainPID, not ActiveState. A successful probe that names a
+  // live pid (> 1) means systemd still owns that process — including during
+  // `activating` / `deactivating` / `reloading`. Filtering on ActiveState here
+  // used to label those transitional states "inactive" and hand the pid to a
+  // raw SIGTERM, which is exactly the Restart=on-failure bounce.
   const lines = ran.stdout
     .split("\n")
     .map((l) => l.trim())
     .filter((l) => l.length > 0);
   let pid: number | undefined;
-  let active: string | undefined;
   for (const line of lines) {
     if (/^\d+$/.test(line)) {
       const n = Number(line);
       if (Number.isInteger(n) && n > 1) pid = n;
-    } else {
-      active = line;
     }
   }
-  if (active !== undefined && active !== "active" && active !== "reactivating") return undefined;
-  return pid;
+  if (pid === undefined) return { kind: "inactive" };
+  return { kind: "active", pid };
+}
+
+/**
+ * The MainPID of an *active* {@link SYSTEMD_UNIT}, or `undefined` when the
+ * unit is confirmed inactive/absent or when ownership could not be determined.
+ * Prefer {@link probeUnit} when the caller must distinguish those two.
+ */
+export function systemdMainPid(unit = SYSTEMD_UNIT): number | undefined {
+  const ownership = probeUnit(unit);
+  return ownership.kind === "active" ? ownership.pid : undefined;
 }
 
 // ---------------------------------------------------------------------------
@@ -441,40 +478,108 @@ export function systemdMainPid(unit = SYSTEMD_UNIT): number | undefined {
 // ---------------------------------------------------------------------------
 
 /**
- * Ask systemd to stop the unit, but only when it actually owns `pid`.
+ * Whether systemd should stop this daemon.
+ *
+ * - `stop` — unit is active and owns `pid` (or there is no pidfile and the
+ *   unit is the only candidate). Caller MUST go through systemctl; a failed
+ *   manager call is terminal.
+ * - `not-ours` — confirmed inactive/absent unit, no systemd binary, or a unit
+ *   whose MainPID is someone else. Caller may SIGTERM its own pidfile process.
+ * - `unknown` — ownership query failed. Caller MUST NOT signal.
+ */
+type SystemdStopDecision =
+  | { kind: "stop"; mainPid: number }
+  | { kind: "not-ours" }
+  | { kind: "unknown"; reason: string };
+
+function decideSystemdStop(pid: number | undefined): SystemdStopDecision {
+  const ownership = probeUnit();
+  if (ownership.kind === "unknown") return { kind: "unknown", reason: ownership.reason };
+  if (ownership.kind === "inactive") return { kind: "not-ours" };
+  if (pid !== undefined && ownership.pid !== pid) return { kind: "not-ours" };
+  return { kind: "stop", mainPid: ownership.pid };
+}
+
+/**
+ * `systemctl stop` for a pid we have already proven the unit owns.
  *
- * `pid === undefined` means "no pidfile" — still stop the unit if it is
- * active, because that is the only process that could be the daemon. A unit
- * whose MainPID is some other process is left alone: stopping it would take
- * down a neighbour, and the signal path handles *our* pid.
+ * Throws on manager refusal/timeout — never returns "false" for the caller to
+ * reinterpret as "try SIGTERM instead". That reinterpretation is how stop
+ * bounced under `Restart=on-failure`.
  */
-async function stopViaSystemd(pid: number | undefined): Promise<boolean> {
-  const main = systemdMainPid();
-  if (main === undefined) return false;
-  if (pid !== undefined && main !== pid) return false;
+async function runSystemdStop(pid: number, timeoutMs?: number): Promise<void> {
   const ran = systemctl(["stop", SYSTEMD_UNIT]);
-  return ran.ok;
+  if (!ran.ok) {
+    // Record stays: the unit still owns the process, and clearing it would let
+    // the next `start` believe the port is free while systemd still holds it.
+    throw new Error(systemctlFailure("stop", ran));
+  }
+  // systemctl stop is synchronous for Type=simple, but a slow drain still
+  // holds the old pid briefly and the next start would refuse against it.
+  const deadline = Date.now() + (timeoutMs ?? STOP_TIMEOUT_MS);
+  while (isAlive(pid) && Date.now() < deadline) await sleep(100);
+  if (isAlive(pid)) {
+    throw new Error(
+      `daemon pid ${pid} still alive after systemctl stop ${SYSTEMD_UNIT} — ` +
+        `check \`systemctl status ${SYSTEMD_UNIT}\``,
+    );
+  }
+}
+
+function systemctlFailure(verb: "stop" | "restart", ran: SystemctlResult): string {
+  const detail = (ran.stderr.trim() || ran.stdout.trim() || "no output").split("\n")[0] ?? "no output";
+  return (
+    `systemctl ${verb} ${SYSTEMD_UNIT} failed: ${detail} — ` +
+    `refusing to signal a unit-owned daemon (that is how Restart=on-failure turns stop into a bounce); ` +
+    `fix the unit or run \`systemctl ${verb} ${SYSTEMD_UNIT}\` yourself`
+  );
+}
+
+function ownershipUnknown(verb: "stop" | "restart", reason: string): string {
+  return (
+    `cannot determine whether ${SYSTEMD_UNIT} owns the daemon (${reason}) — ` +
+    `refusing to ${verb} via signal while ownership is unknown ` +
+    `(a raw SIGTERM under Restart=on-failure is a bounce); ` +
+    `retry when systemctl answers, or run \`systemctl ${verb} ${SYSTEMD_UNIT}\` yourself`
+  );
 }
 
 /**
- * Run one `systemctl` invocation. Captures output and never throws: absence
- * of the binary, a missing unit, or a permission error are all "not ok", and
- * the caller decides whether to fall back.
+ * Run one `systemctl` invocation. Captures output and never throws: the caller
+ * classifies the result. `missing: true` means the binary is not on PATH — that
+ * is a confirmed "no systemd on this host", not a transient query failure.
  *
  * The default shells out. Tests replace it with {@link setSystemctlForTest}
  * so the ownership decision is exercised without a real systemd.
  */
-export type SystemctlFn = (args: string[]) => { ok: boolean; stdout: string; stderr: string };
+export type SystemctlResult = {
+  ok: boolean;
+  stdout: string;
+  stderr: string;
+  /** Binary not found (ENOENT). Distinct from a failed invocation of a present binary. */
+  missing?: boolean;
+};
 
-function defaultSystemctl(args: string[]): { ok: boolean; stdout: string; stderr: string } {
+export type SystemctlFn = (args: string[]) => SystemctlResult;
+
+function defaultSystemctl(args: string[]): SystemctlResult {
   try {
     const res = spawnSync("systemctl", args, {
       encoding: "utf8",
-      // A hung dbus is not worth blocking stop on; the signal path is right there.
+      // Bound the wait: a hung dbus becomes `unknown` ownership, not a hang.
+      // Callers must NOT treat that timeout as "no unit".
       timeout: 15_000,
       env: process.env,
     });
-    if (res.error) return { ok: false, stdout: "", stderr: res.error.message };
+    if (res.error) {
+      const err = res.error as NodeJS.ErrnoException;
+      return {
+        ok: false,
+        stdout: "",
+        stderr: err.message,
+        ...(err.code === "ENOENT" ? { missing: true } : {}),
+      };
+    }
     return {
       ok: res.status === 0,
       stdout: res.stdout ?? "",

package/src/omp.ts

@@ -13,6 +13,8 @@
  * site on purpose: a non-literal specifier stops `tsc` from trying to resolve
  * the module, which is the whole reason this shim exists.
  */
+import { worktreeConfinement } from "./confinement.ts";
+
 const OMP_PACKAGE = "@oh-my-pi/pi-coding-agent";
 
 /**
@@ -114,6 +116,12 @@ export async function createSession(opts: {
   sessionDir?: string;
   model?: string;
   resume?: boolean;
+  /**
+   * Install the worktree `tool_call` gate so structured file tools cannot
+   * leave `cwd`. Workers pass true; the orchestrator leaves this off — it has
+   * to read the state directory and briefs.
+   */
+  confineToCwd?: boolean;
 }): Promise<AgentSessionLike> {
   let loaded: unknown;
   try {
@@ -167,6 +175,10 @@ export async function createSession(opts: {
     // agentDir (~/.omp/agent/mcp.json) — without this, workers grep-only and
     // burn the turns cap on discovery (#29).
     enableMCP: true,
+    // Mechanical worktree gate (#24): structured write/edit/read/grep/glob
+    // whose path resolves outside cwd are blocked before execution. Inline
+    // extension — the harness has no separate fs-policy field.
+    ...(opts.confineToCwd ? { extensions: [worktreeConfinement(opts.cwd)] } : {}),
   });
   const raw = asRawSession(created);
   // Surfaced rather than swallowed: this is how a quiet downgrade to a weaker

package/src/orchestrator-tick.ts

@@ -334,7 +334,7 @@ export function resolveTickScope(): {
  * live `POLICY.md`.
  *
  * Runs on **every** successful send — including ticks that use a custom
- * `message` — so protocol updates land after `npm install` without waiting for
+ * `message` — so protocol updates land after a package upgrade without waiting for
  * the default prompt path. Failures (no config, no `POLICY.md`, unreadable
  * overlay) are silent: the tick still goes out.
  */