omp-conductor 0.4.2 → 0.4.3

package/src/confinement.ts

@@ -1,48 +1,37 @@
 /**
- * Mechanical filesystem confinement for the sessions this package starts.
+ * Mechanical filesystem confinement for the worker sessions this package
+ * starts — and only those.
  *
  * 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). Two gates ride on that seam, and they are shaped differently
- * because the two sessions need different things:
+ * example). {@link worktreeConfinement} rides on that seam: a worker may touch
+ * its own checkout and nothing else.
  *
- *  - {@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).
+ * The orchestrator is deliberately **unconfined** (operator ruling, #143).
+ * An earlier release jailed it to an allowlist, which was never the boundary it
+ * appeared to be: the gate only existed inside sessions this daemon spawns, so
+ * every externally started orchestrator — the supported shape — ran without it
+ * while the brief claimed the refusal was absolute. Rather than widen a jail
+ * nobody can install everywhere, the orchestrator's boundaries are the brief it
+ * is handed and the verb ledger every `conductor_*` call writes, and the
+ * operator reads both. Unconfined means auditable, not licensed.
  *
- * `bash` is deliberately not confined here: its input is an opaque shell
- * 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
+ * `bash` is deliberately not confined here either: its input is an opaque shell
+ * string, and parsing it is a false sense of security. This gate does not
+ * contain a determined session, and no comment or doc here should claim
+ * otherwise — closing that gap is a least-privilege OS principal (a worker uid
+ * under `credentials.isolation: "per-run"`), 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.
+ * What it does buy is a *legible* refusal that holds on hosts where no uid
+ * split will ever be deployed: a structured `edit` outside the assigned
+ * worktree comes back naming the worktree, which the model can act on in one
+ * turn, instead of an `EACCES` it may read as transient and retry.
  */
 
-import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { existsSync, 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"]);
@@ -163,442 +152,3 @@ export function worktreeConfinement(root: string): (pi: ConfinementPi) => void {
   };
 }
 
-// ---------------------------------------------------------------------------
-// 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;
-    });
-  };
-}