omp-conductor 0.3.25 → 0.4.0

package/src/confinement.ts

@@ -1,44 +1,71 @@
 /**
- * Mechanical worktree confinement for worker sessions.
+ * Mechanical filesystem confinement for the sessions this package starts.
  *
  * The harness has no first-class fs-policy field, but `createAgentSession`
  * accepts inline `extensions` that subscribe to `tool_call` and can return
  * `{ block: true }` before a tool runs (see the harness `protected-paths`
- * example). Workers get that gate for structured file tools; the orchestrator
- * does not — it has to read the state directory and briefs.
+ * example). Two gates ride on that seam, and they are shaped differently
+ * because the two sessions need different things:
+ *
+ *  - {@link worktreeConfinement} — a worker may touch its own checkout and
+ *    nothing else.
+ *  - {@link orchestratorConfinement} — the orchestrator has to read the state
+ *    directory and its briefs, so "jail everything to cwd" does not transfer.
+ *    It gets an allowlist instead, default refusal, with every worker
+ *    checkout, the mirror cache and this package's own install denied
+ *    outright (#127).
  *
  * `bash` is deliberately not confined here: its input is an opaque shell
- * string, and parsing it is a false-sense of security. Closing that gap is a
- * least-privilege uid (deployment), documented beside this module's README
- * section — not a regex over `rm -rf`.
+ * string, and parsing it is a false sense of security. Neither gate contains a
+ * determined session, and no comment or doc here should claim otherwise —
+ * closing that gap is a least-privilege OS principal (#125 for the
+ * orchestrator, a worker uid for the deploy), documented beside this module's
+ * README section, not a regex over `rm -rf`.
+ *
+ * What these gates do buy is a *legible* refusal that holds on hosts where no
+ * uid split will ever be deployed: a structured `edit` into a live worktree
+ * comes back naming the worktree and the roots that are allowed, which the
+ * model can act on in one turn, instead of an `EACCES` it may read as a
+ * transient error and retry.
  */
 
-import { existsSync, realpathSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { ORCHESTRATOR_BRIEF_NAME, POLICY_BRIEF_NAME } from "./brief-upgrade.ts";
+import {
+  configPath,
+  defaultMirrorRoot,
+  defaultWorkspaceRoot,
+  loadConfig,
+  stateDir,
+} from "./config.ts";
+import { TICK_CONFIG_FILE, TICK_OWNER_FILE, TICK_STATUS_FILE } from "./orchestrator-tick.ts";
+import { briefPathForProject, policyPathForProject } from "./setup.ts";
 
 /** Tools whose structured `path` (or path-like) field we can gate. */
 const GATED = new Set(["write", "edit", "read", "grep", "glob"]);
 
+/** Real path of a confinement root, or the lexical one when it does not exist. */
+function realRoot(root: string): string {
+  try {
+    return realpathSync(resolve(root));
+  } catch {
+    return resolve(root);
+  }
+}
+
 /**
- * Resolve `candidate` as a worker would, then ask whether it stays under
- * `root`. Symlink-aware: existing path components are realpath'd so a link
- * planted inside the worktree cannot escape by string-prefix tricks.
+ * Resolve `candidate` against an already-realpath'd `base`, following symlinks
+ * through every component that exists.
  *
  * A path that does not exist yet (a new write) realpaths the deepest existing
  * ancestor and appends the rest — the same TOCTOU posture as the harness's
  * own workspace confinement helper.
  */
-export function isInsideWorktree(root: string, candidate: string): boolean {
-  if (candidate.length === 0 || candidate.includes("\0")) return false;
-
-  let rootReal: string;
-  try {
-    rootReal = realpathSync(resolve(root));
-  } catch {
-    rootReal = resolve(root);
-  }
-
-  const abs = resolve(rootReal, candidate);
+function realResolve(base: string, candidate: string): string {
+  const abs = resolve(base, candidate);
 
   const missing: string[] = [];
   let probe = abs;
@@ -49,20 +76,34 @@ export function isInsideWorktree(root: string, candidate: string): boolean {
     probe = parent;
   }
 
-  let base: string;
+  let head: string;
   try {
-    base = realpathSync(probe);
+    head = realpathSync(probe);
   } catch {
-    base = probe;
+    head = probe;
   }
-  const resolved = missing.length === 0 ? base : join(base, ...missing);
+  return missing.length === 0 ? head : join(head, ...missing);
+}
 
+/** Whether an already-resolved path stays under an already-resolved root. */
+function contains(rootReal: string, resolved: string): boolean {
   const rel = relative(rootReal, resolved);
   // Inside ⇒ "" or a relative path that does not climb out. Absolute `rel` is
   // a Windows drive mismatch; anything starting with `..` has left the root.
   return rel === "" || (!isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${sep}`));
 }
 
+/**
+ * Resolve `candidate` as a worker would, then ask whether it stays under
+ * `root`. Symlink-aware: existing path components are realpath'd so a link
+ * planted inside the worktree cannot escape by string-prefix tricks.
+ */
+export function isInsideWorktree(root: string, candidate: string): boolean {
+  if (candidate.length === 0 || candidate.includes("\0")) return false;
+  const rootReal = realRoot(root);
+  return contains(rootReal, realResolve(rootReal, candidate));
+}
+
 /** Pull the path-like field a gated tool carries, if any. */
 export function pathFromToolInput(toolName: string, input: Record<string, unknown>): string | undefined {
   if (!GATED.has(toolName)) return undefined;
@@ -121,3 +162,443 @@ export function worktreeConfinement(root: string): (pi: ConfinementPi) => void {
     pi.on("tool_call", (event) => confineToolCall(rootAbs, event.toolName, event.input));
   };
 }
+
+// ---------------------------------------------------------------------------
+// orchestrator confinement (#127)
+// ---------------------------------------------------------------------------
+
+/**
+ * The installed package's own root — `src/`'s parent, so the briefs under
+ * `src/briefs/`, the skills and `package.json` are all inside it. Read from
+ * `import.meta.dir` for the same reason the integrity tripwire does
+ * (`daemon.ts`): it is a self-portrait of the code executing right now, not
+ * whichever checkout happens to be on disk.
+ */
+const PACKAGE_ROOT = dirname(import.meta.dir);
+
+/**
+ * `<scheme>://` prefixes the harness resolves itself. Reading `issue://`,
+ * `skill://` and `memory://` is a large part of what the orchestrator is
+ * *for*, and none of them names a file, so the gate has no opinion on them.
+ * `file://` is the exception — it does name a file, so it is converted back to
+ * a path and judged as one.
+ */
+const URI_SCHEME = /^([A-Za-z][A-Za-z0-9+.-]*):\/\//;
+
+/**
+ * The filesystem path a tool argument denotes, or `undefined` when it denotes
+ * something the filesystem gate cannot and should not judge.
+ */
+function filesystemPath(raw: string): string | undefined {
+  const scheme = URI_SCHEME.exec(raw);
+  if (scheme === null) return raw;
+  if (scheme[1]?.toLowerCase() !== "file") return undefined;
+  try {
+    return fileURLToPath(raw);
+  } catch {
+    // A malformed `file://` URL names nothing resolvable. Hand back the raw
+    // string so it fails the allowlist rather than slipping through as "not a
+    // path at all" — this gate never guesses in the permissive direction.
+    return raw;
+  }
+}
+
+/**
+ * Roots the orchestrator is refused whatever the allowlist says. Declared as
+ * data so the refusal text, the README and the tests read from one list
+ * instead of three copies that drift (same pattern as `REPORT_SCOPES`).
+ *
+ * `config` is the odd one: it is a single file, and it is *readable* through
+ * the pinhole below. Denying it here is what stops the session writing it, and
+ * that matters because the config is where its own jail, its release grants
+ * and its merge authority are declared. A session that can edit the file that
+ * bounds it is not bounded.
+ */
+export const DENIED_ROOT_KINDS = ["worker-checkouts", "mirror", "package-source", "config"] as const;
+
+export type DeniedRootKind = (typeof DENIED_ROOT_KINDS)[number];
+
+/**
+ * Why each root is denied, phrased for the session that just hit it — the
+ * refusal has to be actionable in one turn, so it says what to do instead.
+ */
+export const DENIED_ROOT_REASON: Record<DeniedRootKind, string> = {
+  "worker-checkouts":
+    "a live worker may be mid-run in it, and its uncommitted work has provenance you cannot see — read the run's PR instead",
+  mirror: "the bare mirror cache is git plumbing shared by every run, not somewhere to read code from",
+  "package-source": "nobody patches the running conductor, and that includes you",
+  config:
+    "it declares your own jail, grants and authority — it is an operator decision, changed by re-running setup, never by the session it governs. Read it freely; ask your operator to change it",
+};
+
+export interface DeniedRoot {
+  kind: DeniedRootKind;
+  root: string;
+}
+
+/**
+ * What an orchestrator session may touch. **Default is refusal**: a path that
+ * matches nothing here is blocked. A deny-list would only stop what somebody
+ * thought to name, and would leave the structured tools pointed at the whole
+ * filesystem.
+ */
+export interface OrchestratorJail {
+  /** Directory roots readable in full. */
+  readRoots: string[];
+  /** Directory roots writable in full — a subset of {@link readRoots}. */
+  writeRoots: string[];
+  /**
+   * Exact files readable even though they sit inside a denied root. Derived
+   * from config only, never operator-extensible: the briefs live *in*
+   * `workspaceRoot`, and denying that root wholesale would otherwise blind the
+   * session to its own standing orders.
+   */
+  readFiles: string[];
+  /**
+   * Exact files writable on the same terms — a subset of {@link readFiles}.
+   * `POLICY.md` is here because the Learning loop's whole job is amending it
+   * after an operator says yes.
+   */
+  writeFiles: string[];
+  /** Refused outright. Outranks every root and every operator addition. */
+  denied: DeniedRoot[];
+}
+
+/** One project's contribution to the jail. */
+export interface OrchestratorJailProject {
+  workspaceRoot: string;
+  mirrorRoot: string;
+  briefPath: string;
+  policyPath: string;
+  /**
+   * Read-only pinholes inside `workspaceRoot` that are not product code and
+   * not a run's work: the heartbeat's own config, status and owner files. A
+   * fleet points its heartbeat at the workspace that holds the briefs, so
+   * these sit beside them inside the denied root — and denial outranks
+   * `orchestratorReadPaths`, which would leave a session unable to read why
+   * its own tick did not fire with no way for an operator to grant it.
+   */
+  fleetFiles?: readonly string[];
+  /** `orchestratorReadPaths`, already validated absolute by `config.ts`. */
+  readPaths?: readonly string[];
+}
+
+/**
+ * Build the jail from already-resolved inputs. Pure, so the precedence rules
+ * are testable without a config file or a live state directory.
+ */
+export function orchestratorJail(input: {
+  stateDir: string;
+  configPath: string;
+  packageRoot: string;
+  projects: readonly OrchestratorJailProject[];
+}): OrchestratorJail {
+  const state = resolve(input.stateDir);
+  const config = resolve(input.configPath);
+  const readRoots = [state];
+  // Readable through the pinhole, unwritable through the denial below.
+  const readFiles: string[] = [config];
+  const writeFiles: string[] = [];
+  const denied: DeniedRoot[] = [
+    { kind: "package-source", root: resolve(input.packageRoot) },
+    { kind: "config", root: config },
+  ];
+
+  for (const p of input.projects) {
+    denied.push({ kind: "worker-checkouts", root: resolve(p.workspaceRoot) });
+    denied.push({ kind: "mirror", root: resolve(p.mirrorRoot) });
+    readFiles.push(resolve(p.briefPath), resolve(p.policyPath));
+    for (const file of p.fleetFiles ?? []) readFiles.push(resolve(file));
+    writeFiles.push(resolve(p.policyPath));
+    // Operator additions are read roots and only read roots: they are checked
+    // *after* the denied list, so `orchestratorReadPaths: ["<workspaceRoot>"]`
+    // buys nothing. That case is the one this issue exists for.
+    for (const extra of p.readPaths ?? []) readRoots.push(resolve(extra));
+  }
+
+  return {
+    readRoots: [...new Set(readRoots)],
+    writeRoots: [state],
+    readFiles: [...new Set(readFiles)],
+    writeFiles: [...new Set(writeFiles)],
+    denied,
+  };
+}
+
+/**
+ * The live jail, computed from the config on disk rather than from hardcoded
+ * paths (#127). An operator who moves `$OMP_CONDUCTOR_HOME` moves the state
+ * directory with it, and a jail pinned to `~/.omp/conductor` would then be
+ * guarding an empty directory while the real one sat open.
+ *
+ * Every configured project contributes its denied roots, not just one the
+ * caller might have named: a single orchestrator serves the whole fleet, so a
+ * second project's checkouts are exactly as off-limits as the first's.
+ *
+ * A config too broken to load still produces a jail, and it is the fail-closed
+ * one: the state directory plus the *default* workspace and mirror roots
+ * denied. The session keeps its own scratch and loses everything else, rather
+ * than running unconfined because one key was malformed.
+ */
+export function orchestratorJailFromConfig(): OrchestratorJail {
+  const heartbeatFiles = (workspaceRoot: string): string[] =>
+    [TICK_CONFIG_FILE, TICK_STATUS_FILE, TICK_OWNER_FILE].map((name) => join(workspaceRoot, name));
+
+  let projects: OrchestratorJailProject[] = [];
+  try {
+    projects = loadConfig().projects.map((p) => ({
+      workspaceRoot: p.workspaceRoot,
+      mirrorRoot: p.mirrorRoot,
+      briefPath: briefPathForProject(p),
+      policyPath: policyPathForProject(p),
+      fleetFiles: heartbeatFiles(p.workspaceRoot),
+      ...(p.orchestratorReadPaths === undefined ? {} : { readPaths: p.orchestratorReadPaths }),
+    }));
+  } catch {
+    // Unreadable config: fall through to the defaults below.
+  }
+  if (projects.length === 0) {
+    const workspaceRoot = defaultWorkspaceRoot();
+    projects = [
+      {
+        workspaceRoot,
+        mirrorRoot: defaultMirrorRoot(),
+        briefPath: join(workspaceRoot, ORCHESTRATOR_BRIEF_NAME),
+        policyPath: join(workspaceRoot, POLICY_BRIEF_NAME),
+        fleetFiles: heartbeatFiles(workspaceRoot),
+      },
+    ];
+  }
+  return orchestratorJail({
+    stateDir: stateDir(),
+    configPath: configPath(),
+    packageRoot: PACKAGE_ROOT,
+    projects,
+  });
+}
+
+/** Why one orchestrator tool call was refused, for the audit and the count. */
+export type OrchestratorRefusalKind = DeniedRootKind | "outside-allowlist" | "read-only";
+
+export interface OrchestratorRefusal {
+  tool: string;
+  /** The path exactly as the tool asked for it, so the audit reads like the transcript. */
+  path: string;
+  kind: OrchestratorRefusalKind;
+}
+
+/** A refusal and the block the harness gets, kept together so counting the one
+ *  never means re-deriving the other. */
+export interface OrchestratorRefusalResult {
+  decision: ConfineDecision;
+  refusal: OrchestratorRefusal;
+}
+
+/**
+ * Exact-file match against an already-resolved candidate. Resolved the same
+ * way the candidate was, so a `POLICY.md` that does not exist yet and a state
+ * directory reached through a symlink both still compare equal.
+ */
+function samePath(file: string, resolved: string): boolean {
+  const abs = resolve(file);
+  return realResolve(realRoot(dirname(abs)), basename(abs)) === resolved;
+}
+
+/**
+ * The denied thing to name in the refusal. For worker checkouts that is the
+ * individual worktree — `<workspaceRoot>/349`, the directory a human would
+ * recognise — not the parent the config happens to call `workspaceRoot`.
+ */
+function deniedTarget(kind: DeniedRootKind, rootReal: string, resolved: string): string {
+  if (kind !== "worker-checkouts") return rootReal;
+  const first = relative(rootReal, resolved).split(sep)[0];
+  if (first === undefined || first.length === 0) return rootReal;
+  const checkout = join(rootReal, first);
+  // A *file* directly inside `workspaceRoot` — the composed brief, say — is
+  // not a checkout, and naming it as one would send the reader looking for a
+  // run that does not exist.
+  try {
+    return statSync(checkout).isDirectory() ? checkout : rootReal;
+  } catch {
+    return rootReal;
+  }
+}
+
+function listing(roots: string[], files: string[]): string {
+  const rootPart = roots.length === 0 ? "nothing" : roots.join(", ");
+  return files.length === 0 ? rootPart : `${rootPart}, plus the files ${files.join(", ")}`;
+}
+
+/**
+ * Decide whether one orchestrator tool_call may run. Undefined means "no
+ * opinion" (allow). Pure, so every precedence rule below is pinned by a test
+ * without a harness session.
+ *
+ * Precedence, in this order and for a reason:
+ *  1. the derived exact-file pinholes — the briefs live inside a denied root;
+ *  2. the denied roots — so a mis-specified `orchestratorReadPaths` cannot
+ *     re-open the two roots this gate exists for;
+ *  3. the allowlist, write roots for `write`/`edit` and read roots otherwise;
+ *  4. refusal.
+ */
+export function confineOrchestratorToolCall(
+  jail: OrchestratorJail,
+  cwd: string,
+  toolName: string,
+  input: Record<string, unknown>,
+): OrchestratorRefusalResult | undefined {
+  const raw = pathFromToolInput(toolName, input);
+  if (raw === undefined) return undefined;
+  const candidate = filesystemPath(raw);
+  if (candidate === undefined) return undefined;
+
+  const mutating = toolName === "write" || toolName === "edit";
+  if (candidate.includes("\0")) {
+    return {
+      decision: {
+        block: true,
+        reason: `Blocked: ${toolName} path "${raw}" contains a NUL byte and names no file.`,
+      },
+      refusal: { tool: toolName, path: raw, kind: "outside-allowlist" },
+    };
+  }
+
+  const resolved = realResolve(realRoot(cwd), candidate);
+
+  for (const file of mutating ? jail.writeFiles : jail.readFiles) {
+    if (samePath(file, resolved)) return undefined;
+  }
+
+  for (const { kind, root } of jail.denied) {
+    const rootReal = realRoot(root);
+    if (!contains(rootReal, resolved)) continue;
+    return {
+      decision: {
+        block: true,
+        reason:
+          `Blocked: ${toolName} path "${raw}" resolves into ${deniedTarget(kind, rootReal, resolved)}, ` +
+          `which the orchestrator may never touch — ${DENIED_ROOT_REASON[kind]}. ` +
+          `The denial covers all of ${rootReal} and outranks orchestratorReadPaths.`,
+      },
+      refusal: { tool: toolName, path: raw, kind },
+    };
+  }
+
+  for (const root of mutating ? jail.writeRoots : jail.readRoots) {
+    if (contains(realRoot(root), resolved)) return undefined;
+  }
+
+  const readable = jail.readRoots.some((root) => contains(realRoot(root), resolved));
+  if (mutating && readable) {
+    return {
+      decision: {
+        block: true,
+        reason:
+          `Blocked: ${toolName} path "${raw}" is readable but not writable by the orchestrator. ` +
+          `Writable: ${listing(jail.writeRoots, jail.writeFiles)}. ` +
+          "You re-brief workers and amend POLICY.md; editing anything else is a worker's job.",
+      },
+      refusal: { tool: toolName, path: raw, kind: "read-only" },
+    };
+  }
+
+  return {
+    decision: {
+      block: true,
+      reason:
+        `Blocked: ${toolName} path "${raw}" is outside the orchestrator's allowlist, and the default is refusal. ` +
+        `Readable: ${listing(jail.readRoots, jail.readFiles)}. ` +
+        'Add a root to "orchestratorReadPaths" in the project config if this session genuinely needs it.',
+    },
+    refusal: { tool: toolName, path: raw, kind: "outside-allowlist" },
+  };
+}
+
+/**
+ * Append-only audit of refusals, beside the release-policy one and for the
+ * same reason: a gate nobody can count is a gate nobody notices. An
+ * orchestrator that is refused thirty times an hour is misbriefed, and that
+ * shows up in `omp-conductor status` rather than only in a transcript.
+ */
+export const CONFINEMENT_AUDIT_FILE = "orchestrator-confinement-refusals.jsonl";
+
+export interface ConfinementRefusalRecord extends OrchestratorRefusal {
+  at: string;
+}
+
+export function recordConfinementRefusal(
+  refusal: OrchestratorRefusal,
+  root = stateDir(),
+  now = new Date(),
+): void {
+  mkdirSync(root, { recursive: true });
+  const record: ConfinementRefusalRecord = { ...refusal, at: now.toISOString() };
+  appendFileSync(join(root, CONFINEMENT_AUDIT_FILE), `${JSON.stringify(record)}\n`, { mode: 0o600 });
+}
+
+export interface ConfinementRefusalSummary {
+  count: number;
+  latest: ConfinementRefusalRecord;
+}
+
+/** Today's refusals, for the status surface. Undefined when there were none. */
+export function confinementRefusalsToday(
+  root = stateDir(),
+  now = new Date(),
+): ConfinementRefusalSummary | undefined {
+  let text: string;
+  try {
+    text = readFileSync(join(root, CONFINEMENT_AUDIT_FILE), "utf8");
+  } catch {
+    return undefined;
+  }
+  const day = now.toISOString().slice(0, 10);
+  let count = 0;
+  let latest: ConfinementRefusalRecord | undefined;
+  for (const line of text.split("\n")) {
+    if (line.length === 0) continue;
+    try {
+      const value = JSON.parse(line) as Partial<ConfinementRefusalRecord>;
+      if (
+        typeof value.at === "string" &&
+        value.at.startsWith(day) &&
+        typeof value.tool === "string" &&
+        typeof value.path === "string" &&
+        typeof value.kind === "string"
+      ) {
+        count += 1;
+        latest = value as ConfinementRefusalRecord;
+      }
+    } catch {
+      // One torn line must not hide the valid records written after it.
+    }
+  }
+  return latest === undefined ? undefined : { count, latest };
+}
+
+/**
+ * Inline extension factory for an orchestrator session. Refusals are counted
+ * through `onRefusal`, which defaults to the durable audit above — a refusal
+ * the operator never learns about is indistinguishable from a session that
+ * behaved.
+ */
+export function orchestratorConfinement(
+  jail: OrchestratorJail,
+  cwd: string,
+  onRefusal: (refusal: OrchestratorRefusal) => void = recordConfinementRefusal,
+): (pi: ConfinementPi) => void {
+  const cwdAbs = resolve(cwd);
+  return (pi) => {
+    pi.on("tool_call", (event) => {
+      const refused = confineOrchestratorToolCall(jail, cwdAbs, event.toolName, event.input);
+      if (refused === undefined) return undefined;
+      try {
+        onRefusal(refused.refusal);
+      } catch {
+        // Audit is evidence, not the gate. A full disk must not turn a deny
+        // into an allow.
+      }
+      return refused.decision;
+    });
+  };
+}