@syntax-syllogism/aloop 0.5.2 → 0.6.0

package/src/config.mjs

@@ -2,7 +2,14 @@ import { access } from 'node:fs/promises';
 import { constants } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { validateAgent } from './adapters.mjs';
+import { PERMISSIONS, validateAgent } from './adapters.mjs';
+import { normalizeHermeticConfig, resolvePhaseHermetic } from './hermetic.mjs';
+
+// Monotonic counter that makes every config import URL unique. `Date.now()`
+// alone has millisecond granularity, so two loadConfig calls of the same file
+// within one millisecond (routine on fast CI runners) would otherwise reuse the
+// cached module and miss a rewritten config on disk.
+let configImportCounter = 0;
 
 const defaults = {
   baseBranch: 'master',
@@ -13,41 +20,112 @@ const defaults = {
   remote: null,
   adapters: {},
   engines: { default: { name: 'claude' } },
-  phases: ['implement', 'gate', 'review', 'address', 'docs', 'git'],
+  phases: ['implement', 'docs', 'gate', 'review', 'address', 'pr-description', 'publish'],
+  publish: { backend: 'github', draft: true },
   gate: [],
   // Commands run once in a newly created worktree before the first phase.
   // An empty list keeps the generic runner package-manager agnostic.
   setup: [],
+  // Shell used for user-authored setup and gate commands.
+  shell: 'sh',
   maxRounds: 3,
   // Per-command budget. An implement phase on a real work item routinely
   // runs past half an hour; a cap that tight kills healthy runs mid-edit.
   timeoutMs: 60 * 60 * 1000,
+  // Optional run-level ceilings. Unknown usage is retained as unknown by the
+  // metrics layer and is never silently treated as zero by budget checks.
+  budget: {},
   worktrees: true,
   worktreeRoot: null,
   promptDir: '.loop/prompts',
   runsDir: '.loop/runs',
+  // Container execution is opt-in per phase. These are inherited defaults,
+  // not an instruction to run every phase in a container.
+  hermetic: {
+    runtime: 'docker',
+    image: null,
+    network: [],
+    env: [],
+    secrets: [],
+  },
 };
 
 /**
- * Built-in phase definitions.
+ * Built-in phase descriptors.
  *
- * `verdict: true` marks a phase whose agent must emit a machine-readable
- * verdict; `role: 'repair'` marks a phase that exists to answer one. The
- * runner pairs them during normalization, which is what turns a flat list into
- * a loop without the config having to describe control flow.
+ * A verdict owns its repair transition explicitly. The string phase list stays
+ * supported as a shorthand, but adjacency no longer creates a transition.
  */
 const builtinPhases = {
-  implement: { kind: 'agent', prompt: 'implement' },
-  gate: { kind: 'gate' },
-  review: { kind: 'agent', prompt: 'review', verdict: true },
-  address: { kind: 'agent', prompt: 'address', role: 'repair' },
-  docs: { kind: 'agent', prompt: 'docs' },
-  // `requiresCleanTree` makes the runner assert a clean worktree before this
-  // phase runs. The git phase pushes and opens a PR; it must never start over
-  // uncommitted work an earlier phase left behind, and its prompt forbids it
-  // from committing, so a dirty tree there is a pipeline error, not something
-  // for the agent to reconcile.
-  git: { kind: 'agent', prompt: 'git', requiresCleanTree: true },
+  implement: {
+    kind: 'agent',
+    prompt: 'implement',
+    inputs: ['task'],
+    outputs: ['commit'],
+    postconditions: ['clean-tree', 'head-advanced'],
+    permissions: [PERMISSIONS.WRITE_WORKTREE],
+    retry: { maxAttempts: 1 },
+  },
+  gate: {
+    kind: 'gate',
+    inputs: ['worktree'],
+    outputs: ['gate-result'],
+    postconditions: ['gate-passes'],
+    permissions: [PERMISSIONS.READ_ONLY],
+    retry: { maxAttempts: 1 },
+  },
+  review: {
+    kind: 'agent',
+    prompt: 'review',
+    verdict: true,
+    role: 'verdict',
+    inputs: ['commit', 'gate-result'],
+    outputs: ['verdict'],
+    postconditions: ['verdict-recorded'],
+    permissions: [PERMISSIONS.READ_ONLY],
+    retry: { maxAttempts: 1 },
+    repair: ['address', { name: 'gate', recheck: true }],
+  },
+  address: {
+    kind: 'agent',
+    prompt: 'address',
+    role: 'repair',
+    inputs: ['verdict'],
+    outputs: ['commit', 'rebuttal'],
+    postconditions: ['clean-tree', 'head-advanced-or-rebuttal'],
+    permissions: [PERMISSIONS.WRITE_WORKTREE],
+    retry: { maxAttempts: 1 },
+  },
+  docs: {
+    kind: 'agent',
+    prompt: 'docs',
+    optional: true,
+    inputs: ['commit'],
+    outputs: ['commit'],
+    permissions: [PERMISSIONS.WRITE_WORKTREE],
+    retry: { maxAttempts: 1 },
+  },
+  // The description agent may only author the run-dir PR description. The
+  // driver owns all remote mutations in the following publish phase.
+  'pr-description': {
+    kind: 'agent',
+    prompt: 'pr-description',
+    requiresCleanTree: true,
+    inputs: ['commit'],
+    outputs: ['pull-request-description'],
+    postconditions: ['clean-tree', 'head-unchanged', 'pr-description-valid'],
+    permissions: [PERMISSIONS.READ_ONLY],
+    retry: { maxAttempts: 1 },
+  },
+  publish: {
+    kind: 'publish',
+    requiresCleanTree: true,
+    inputs: ['pull-request-description'],
+    outputs: ['pull-request'],
+    postconditions: ['remote-matches', 'pull-request-verified'],
+    permissions: [PERMISSIONS.PUBLISH],
+    retry: { maxAttempts: 1 },
+  },
 };
 
 async function exists(path) {
@@ -63,58 +141,142 @@ function toPhase(entry, index) {
   if (typeof entry === 'string') {
     const builtin = builtinPhases[entry];
     if (!builtin) throw new Error(`Unknown phase "${entry}"; define it as an object to add a custom phase.`);
-    return { name: entry, ...builtin };
+    entry = { name: entry };
   }
   if (!entry?.name) throw new Error(`Phase at position ${index} is missing a name.`);
   const builtin = builtinPhases[entry.name] ?? {};
-  const phase = { ...builtin, ...entry };
-  if (!['agent', 'gate'].includes(phase.kind)) {
-    throw new Error(`Phase "${phase.name}" needs kind "agent" or "gate".`);
+  const phase = { optional: false, ...builtin, ...entry };
+  // Only an explicit boolean true permits skipping a custom phase. This keeps
+  // configuration typos such as `optional: 'false'` required by default.
+  phase.optional = phase.optional === true;
+  if (!['agent', 'gate', 'publish'].includes(phase.kind)) {
+    throw new Error(`Phase "${phase.name}" needs kind "agent", "gate", or "publish".`);
   }
   if (phase.kind === 'agent' && !phase.prompt) phase.prompt = phase.name;
+  for (const field of ['inputs', 'outputs', 'postconditions', 'permissions']) {
+    if (phase[field] === undefined) phase[field] = [];
+    if (!Array.isArray(phase[field]) || phase[field].some((value) => typeof value !== 'string')) {
+      throw new Error(`Phase "${phase.name}" has invalid ${field}; expected an array of strings.`);
+    }
+  }
+  if (phase.permissions.some((permission) => !Object.values(PERMISSIONS).includes(permission))) {
+    throw new Error(`Phase "${phase.name}" has invalid permissions; expected ${Object.values(PERMISSIONS).join(', ')}.`);
+  }
+  if (phase.permissions.length === 0) {
+    phase.permissions = [phase.kind === 'publish' ? PERMISSIONS.PUBLISH : PERMISSIONS.READ_ONLY];
+  }
+  if (phase.retry === undefined) phase.retry = { maxAttempts: 1 };
+  if (!phase.retry || typeof phase.retry !== 'object' || Array.isArray(phase.retry)) {
+    throw new Error(`Phase "${phase.name}" has an invalid retry descriptor.`);
+  }
+  phase.retry = { maxAttempts: 1, ...phase.retry };
+  if (!Number.isInteger(phase.retry.maxAttempts) || phase.retry.maxAttempts < 1) {
+    throw new Error(`Phase "${phase.name}" has an invalid retry.maxAttempts; expected a positive integer.`);
+  }
   return phase;
 }
 
 /**
- * Collapse a flat phase list into the shape the runner executes.
+ * Normalize phase descriptors and their explicit repair transitions.
  *
- * A verdict phase absorbs the repair phases that follow it, plus any gate that
- * immediately preceded it, so `[gate, review, address]` becomes "gate, then
- * review, and while the verdict asks for changes: address, gate, review again".
- * Declaring the loop this way keeps the config readable while leaving the
- * iteration cap in the runner where it belongs.
+ * Legacy lists such as `[gate, review, address]` continue to work because the
+ * built-in review descriptor names `address` and the gate recheck explicitly.
+ * A custom verdict phase must declare its own `repair` list; merely placing a
+ * repair phase after it no longer changes control flow.
  */
 export function normalizePhases(entries, { maxRounds }) {
   const list = entries.map(toPhase);
-  const result = [];
+  const phaseIndexes = new Map();
+  list.forEach((phase, index) => {
+    if (!phaseIndexes.has(phase.name)) phaseIndexes.set(phase.name, index);
+  });
+  const consumedRepairs = new Set();
+
+  function resolveRepair(reference, parentName, index, { allowMissing = false } = {}) {
+    const referenceName = typeof reference === 'string' ? reference : reference?.name;
+    const sourceIndex = referenceName ? phaseIndexes.get(referenceName) : undefined;
+    if (sourceIndex === undefined && allowMissing) return null;
+    const source = sourceIndex === undefined
+      ? (referenceName ? builtinPhases[referenceName] : null)
+      : list[sourceIndex];
+    if (sourceIndex === undefined && !source && typeof reference === 'string') {
+      throw new Error(`Phase "${parentName}" references unknown repair phase "${referenceName}".`);
+    }
+    const descriptor = typeof reference === 'string'
+      ? { name: referenceName, ...source }
+      : { name: referenceName, ...source, ...reference };
+    const repair = toPhase(descriptor, index);
+    if (sourceIndex !== undefined && list[sourceIndex].role === 'repair') consumedRepairs.add(sourceIndex);
+    if (repair.verdict) {
+      throw new Error(`Phase "${parentName}" cannot repair verdict phase "${repair.name}".`);
+    }
+    return repair;
+  }
+
   for (let index = 0; index < list.length; index += 1) {
     const phase = list[index];
-    if (phase.role === 'repair') {
-      throw new Error(`Phase "${phase.name}" is a repair phase and must follow a phase that emits a verdict.`);
+    if (!phase.verdict) continue;
+    const repair = phase.repair ?? [];
+    if (!Array.isArray(repair)) {
+      throw new Error(`Phase "${phase.name}" has an invalid repair transition; expected an array.`);
     }
-    if (!phase.verdict) {
-      result.push(phase);
-      continue;
-    }
-    const repair = [];
-    let next = index + 1;
-    while (next < list.length && list[next].role === 'repair') {
-      repair.push(list[next]);
-      next += 1;
+    phase.maxRounds = phase.maxRounds ?? phase.retry.maxRounds ?? maxRounds;
+    const allowMissing = phase.repair === builtinPhases[phase.name]?.repair;
+    const resolvedRepair = repair
+      .map((reference, repairIndex) => resolveRepair(reference, phase.name, repairIndex, { allowMissing }))
+      .filter(Boolean);
+    const hasRepairTransition = resolvedRepair.some((repairPhase) => !repairPhase.recheck);
+    phase.repair = resolvedRepair.filter((repairPhase) => !repairPhase.recheck || hasRepairTransition);
+  }
+
+  const result = [];
+  for (let index = 0; index < list.length; index += 1) {
+    const phase = list[index];
+    if (phase.role === 'repair' && !consumedRepairs.has(index)) {
+      throw new Error(`Phase "${phase.name}" is a repair phase and must be declared by a phase that emits a verdict.`);
     }
-    const precedingGate = result.at(-1)?.kind === 'gate' ? result.at(-1) : null;
-    result.push({
-      ...phase,
-      maxRounds: phase.maxRounds ?? maxRounds,
-      repair: repair.length
-        ? [...repair, ...(precedingGate ? [{ ...precedingGate, recheck: true }] : [])]
-        : [],
-    });
-    index = next - 1;
+    if (!consumedRepairs.has(index)) result.push(phase);
   }
   return result;
 }
 
+function assertPublishablePhaseOrder(resolvedPhases) {
+  const isPublishingPhase = (phase) => phase.kind === 'publish'
+    || phase.requiresCleanTree === true
+    || phase.outputs.includes('pull-request')
+    || phase.outputs.includes('pull-request-description');
+  let violation;
+
+  for (let publishingIndex = 0; publishingIndex < resolvedPhases.length; publishingIndex += 1) {
+    if (!isPublishingPhase(resolvedPhases[publishingIndex])) continue;
+
+    const verdictIndex = resolvedPhases.findLastIndex((phase, index) => index < publishingIndex
+      && (phase.role === 'verdict' || phase.verdict === true));
+    if (verdictIndex === -1) continue;
+
+    const offenders = resolvedPhases
+      .slice(verdictIndex + 1, publishingIndex)
+      .filter((phase) => phase.outputs.includes('commit'))
+      .map((phase) => phase.name);
+    if (!offenders.length) continue;
+
+    violation = { verdictIndex, publishingIndex, offenders };
+  }
+
+  if (violation) {
+    const { verdictIndex, publishingIndex, offenders } = violation;
+    throw new Error(
+      `Phase order publishes an unreviewed tree: ${offenders.join(', ')} `
+      + `commit${offenders.length > 1 ? 's' : ''} after the `
+      + `"${resolvedPhases[verdictIndex].name}" verdict but before `
+      + `"${resolvedPhases[publishingIndex].name}" publishes. A commit after `
+      + `approval advances HEAD off the approved SHA and stalls publishing. Move `
+      + `${offenders.join(', ')} before the gate/review loop `
+      + `(e.g. ['implement', 'docs', 'gate', 'review', 'address', 'pr-description', 'publish']).`,
+    );
+  }
+}
+
 function normalizeAgent(entry, phaseName, customAdapters) {
   const agent = typeof entry === 'string' ? { name: entry } : entry;
   if (!agent || typeof agent !== 'object' || Array.isArray(agent)) {
@@ -146,14 +308,56 @@ function normalizeEngines(engines, customAdapters) {
   return normalized;
 }
 
-export async function loadConfig(cwd, overrides = {}, configPath) {
+function normalizeBudget(budget) {
+  if (!budget || typeof budget !== 'object' || Array.isArray(budget)) {
+    throw new Error('`budget` must be an object with optional tokens, usd, and wallClockMs limits.');
+  }
+  const normalized = {};
+  for (const field of ['tokens', 'usd', 'wallClockMs']) {
+    const value = budget[field];
+    if (value === undefined) continue;
+    const valid = typeof value === 'number' && Number.isFinite(value) && value >= 0
+      && (field !== 'tokens' || Number.isInteger(value));
+    if (!valid) {
+      const kind = field === 'tokens' ? 'a nonnegative integer' : 'a nonnegative finite number';
+      throw new Error(`\`budget.${field}\` must be ${kind}.`);
+    }
+    normalized[field] = value;
+  }
+  return normalized;
+}
+
+async function importConfigFile(cwd, configPath) {
   const path = configPath ? resolve(configPath) : join(cwd, 'loop.config.mjs');
   if (configPath && !(await exists(path))) {
     throw new Error(`Loop config file does not exist: ${path}`);
   }
-  const configured = (await exists(path))
-    ? ((await import(`${pathToFileURL(path).href}?t=${Date.now()}`)).default ?? {})
+  return (await exists(path))
+    ? ((await import(`${pathToFileURL(path).href}?t=${Date.now()}-${configImportCounter++}`)).default ?? {})
     : {};
+}
+
+/**
+ * Resolve only the configured runs directory, skipping pipeline validation.
+ *
+ * Read-only operations (status/inspect/list/metrics) must inspect saved runs
+ * even when the current pipeline config is unrunnable — for example after a
+ * config change leaves a gate phase without commands, which `loadConfig`
+ * rejects. They need the runs location, not a runnable pipeline, so this reads
+ * `runsDir` from the config file (or the default) without normalizing engines
+ * or phases.
+ */
+export async function loadRunsDir(cwd, configPath) {
+  const configured = await importConfigFile(cwd, configPath);
+  const runsDir = configured.runsDir ?? defaults.runsDir;
+  if (typeof runsDir !== 'string' || !runsDir) {
+    throw new Error('`runsDir` must be a non-empty string.');
+  }
+  return runsDir;
+}
+
+export async function loadConfig(cwd, overrides = {}, configPath) {
+  const configured = await importConfigFile(cwd, configPath);
   const merged = {
     ...defaults,
     ...configured,
@@ -162,11 +366,32 @@ export async function loadConfig(cwd, overrides = {}, configPath) {
     engines: { ...defaults.engines, ...configured.engines, ...overrides.engines },
   };
   merged.engines = normalizeEngines(merged.engines, merged.adapters);
+  merged.budget = normalizeBudget(merged.budget);
+  merged.hermetic = normalizeHermeticConfig(merged.hermetic);
+  if (!merged.publish || typeof merged.publish !== 'object' || Array.isArray(merged.publish)) {
+    throw new Error('`publish` must be an object with backend and draft settings.');
+  }
+  if (merged.publish.backend !== undefined
+    && typeof merged.publish.backend !== 'string'
+    && (typeof merged.publish.backend !== 'object' || merged.publish.backend === null)) {
+    throw new Error('`publish.backend` must be "github" or a backend object.');
+  }
+  if (merged.publish.draft !== undefined && typeof merged.publish.draft !== 'boolean') {
+    throw new Error('`publish.draft` must be a boolean.');
+  }
   if (!Array.isArray(merged.setup) || merged.setup.some((command) => typeof command !== 'string')) {
     throw new Error('`setup` must be an array of command strings.');
   }
+  if (typeof merged.shell !== 'string' || !merged.shell.trim()) {
+    throw new Error('`shell` must be a non-empty string.');
+  }
   merged.resolvedPhases = normalizePhases(merged.phases, { maxRounds: merged.maxRounds });
-  if (merged.resolvedPhases.some((phase) => phase.kind === 'gate' && !(phase.commands ?? merged.gate).length)) {
+  for (const phase of merged.resolvedPhases.flatMap((entry) => [entry, ...(entry.repair ?? [])])) {
+    phase.hermetic = resolvePhaseHermetic(phase.hermetic, merged.hermetic, phase.kind);
+  }
+  assertPublishablePhaseOrder(merged.resolvedPhases);
+  const allResolvedPhases = merged.resolvedPhases.flatMap((phase) => [phase, ...(phase.repair ?? [])]);
+  if (allResolvedPhases.some((phase) => phase.kind === 'gate' && !(phase.commands ?? merged.gate).length)) {
     throw new Error('The pipeline has a gate phase but no gate commands; set `gate: [...]` in loop.config.mjs.');
   }
   return merged;

package/src/git.mjs

@@ -18,6 +18,10 @@ export class GitFacade {
     return this.output(['rev-parse', '--show-toplevel']);
   }
 
+  async commonDir() {
+    return this.output(['rev-parse', '--git-common-dir']);
+  }
+
   async currentBranch() {
     return this.output(['symbolic-ref', '--quiet', '--short', 'HEAD']);
   }
@@ -34,6 +38,24 @@ export class GitFacade {
     return Boolean(await this.status());
   }
 
+  async push(remote, branch, { setUpstream = true, ...options } = {}) {
+    return this.run([
+      'push',
+      ...(setUpstream ? ['--set-upstream'] : []),
+      remote,
+      branch,
+    ], options);
+  }
+
+  async lsRemote(remote, branch, options = {}) {
+    const output = await this.output(['ls-remote', remote, `refs/heads/${branch}`], options);
+    const sha = output.split(/\s+/)[0];
+    if (!/^[0-9a-f]{40}$/i.test(sha)) {
+      throw new Error(`Remote branch ${remote}/${branch} has no resolvable SHA.`);
+    }
+    return sha;
+  }
+
   async localBranchExists(branch) {
     try {
       await this.run(['show-ref', '--verify', '--quiet', `refs/heads/${branch}`]);
@@ -51,6 +73,10 @@ export class GitFacade {
     return (await this.remotes()).includes(remote);
   }
 
+  async remoteUrl(remote) {
+    return this.output(['remote', 'get-url', remote]);
+  }
+
   async defaultRemote() {
     const remotes = await this.remotes();
     if (remotes.includes('origin')) return 'origin';

package/src/hermetic.mjs

@@ -0,0 +1,160 @@
+const DEFAULTS = {
+  runtime: 'docker',
+  image: null,
+  networks: [],
+  env: [],
+  secrets: [],
+};
+
+function normalizeNames(value, field) {
+  const names = value === undefined ? [] : (Array.isArray(value) ? value : [value]);
+  if (names.some((name) => typeof name !== 'string' || !name)) {
+    throw new Error(`Hermetic ${field} must contain non-empty strings.`);
+  }
+  return [...new Set(names)];
+}
+
+function normalizeNetworkNames(value) {
+  const networks = normalizeNames(value, 'network names');
+  if (networks.includes('none') && networks.length > 1) {
+    throw new Error('Hermetic network policy cannot combine "none" with an allowed network.');
+  }
+  return networks;
+}
+
+/** Normalize the run-level defaults without enabling container execution. */
+export function normalizeHermeticConfig(value) {
+  if (value === undefined || value === null || value === false) return { ...DEFAULTS };
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('`hermetic` must be an object.');
+  }
+  const normalized = {
+    ...DEFAULTS,
+    ...value,
+    networks: value.networks ?? value.network ?? DEFAULTS.networks,
+  };
+  if (typeof normalized.runtime !== 'string' || !normalized.runtime) {
+    throw new Error('`hermetic.runtime` must be a non-empty command name.');
+  }
+  if (normalized.image !== null && (typeof normalized.image !== 'string' || !normalized.image)) {
+    throw new Error('`hermetic.image` must be a non-empty image name or null.');
+  }
+  normalized.networks = normalizeNetworkNames(normalized.networks);
+  normalized.env = normalizeNames(normalized.env, 'environment names');
+  normalized.secrets = normalizeNames(normalized.secrets, 'secret names');
+  delete normalized.network;
+  return normalized;
+}
+
+/**
+ * Resolve a phase's opt-in descriptor against run-level defaults.
+ * `undefined` and `false` deliberately mean host execution.
+ */
+export function resolvePhaseHermetic(value, defaults, phaseKind) {
+  if (value === undefined || value === false || value === null) return null;
+  if (value !== true && (typeof value !== 'object' || Array.isArray(value))) {
+    throw new Error('Phase hermetic execution must be true, false, or an object.');
+  }
+  const override = value === true ? {} : value;
+  const resolved = normalizeHermeticConfig({
+    ...defaults,
+    ...override,
+    ...(override.network !== undefined || override.networks !== undefined
+      ? { networks: override.networks ?? override.network }
+      : {}),
+  });
+  if (!resolved.image) {
+    throw new Error('Hermetic phases require `hermetic.image` to be configured.');
+  }
+  if (resolved.secrets.length && phaseKind !== 'publish') {
+    throw new Error('Hermetic secrets may only be declared by the publish phase.');
+  }
+  return resolved;
+}
+
+function mountArg(path, mode) {
+  return `type=bind,src=${path},dst=${path}${mode === 'ro' ? ',readonly' : ''}`;
+}
+
+function uniqueMounts(mounts) {
+  const byPath = new Map();
+  for (const mount of mounts) {
+    const current = byPath.get(mount.path);
+    if (!current || (current.mode === 'ro' && mount.mode === 'rw')) byPath.set(mount.path, mount);
+  }
+  return [...byPath.values()];
+}
+
+/**
+ * Build a runtime invocation around an adapter command. Paths intentionally
+ * stay absolute: each host path is bind-mounted at the same path in the
+ * container, so BYO adapters need no container-specific contract.
+ */
+export function hermeticInvocation({
+  settings,
+  command,
+  args,
+  cwd,
+  mounts = [],
+  env = process.env,
+}) {
+  const runtimeArgs = ['run', '--rm', '--workdir', cwd];
+  const networks = settings.networks.length ? settings.networks : ['none'];
+  for (const network of networks) runtimeArgs.push('--network', network);
+  for (const mount of uniqueMounts(mounts)) runtimeArgs.push('--mount', mountArg(mount.path, mount.mode));
+
+  const environment = { PATH: env.PATH ?? '/usr/bin:/bin' };
+  for (const name of settings.secrets) {
+    if (env[name] === undefined) throw new Error(`Hermetic secret "${name}" is not set in the host environment.`);
+  }
+  for (const name of [...settings.env, ...settings.secrets]) {
+    if (env[name] !== undefined) environment[name] = env[name];
+  }
+  for (const name of Object.keys(environment)) runtimeArgs.push('--env', name);
+
+  runtimeArgs.push(settings.image, command, ...args);
+  return {
+    command: settings.runtime,
+    args: runtimeArgs,
+    env: environment,
+    policy: {
+      runtime: settings.runtime,
+      image: settings.image,
+      networks: [...settings.networks],
+      env: [...settings.env],
+      secrets: [...settings.secrets],
+    },
+  };
+}
+
+export function hermeticEnvironment(settings, source = process.env) {
+  const environment = { PATH: source.PATH ?? '/usr/bin:/bin' };
+  for (const name of settings.secrets) {
+    if (source[name] === undefined) throw new Error(`Hermetic secret "${name}" is not set in the host environment.`);
+  }
+  for (const name of [...settings.env, ...settings.secrets]) {
+    if (source[name] !== undefined) environment[name] = source[name];
+  }
+  return environment;
+}
+
+export function hermeticSnapshot(config) {
+  const phases = config.resolvedPhases
+    .flatMap((phase) => [phase, ...(phase.repair ?? [])])
+    .map((phase) => ({
+      name: phase.name,
+      enabled: Boolean(phase.hermetic),
+      ...(phase.hermetic ? {
+        runtime: phase.hermetic.runtime,
+        image: phase.hermetic.image,
+        networks: [...phase.hermetic.networks],
+        env: [...phase.hermetic.env],
+        secrets: [...phase.hermetic.secrets],
+      } : {}),
+    }));
+  return {
+    runtime: config.hermetic.runtime,
+    image: config.hermetic.image,
+    phases,
+  };
+}

package/src/index.mjs

@@ -1,6 +1,27 @@
 export { runLoop } from './pipeline.mjs';
-export { loadConfig, normalizePhases, builtinPhases, defaults } from './config.mjs';
+export { loadConfig, loadRunsDir, normalizePhases, builtinPhases, defaults } from './config.mjs';
 export { adapterFor, engineForPhase, adapters } from './adapters.mjs';
 export { renderPrompt, loadTemplate, interpolate } from './prompts.mjs';
 export { parseVerdict, readVerdict, formatFindings, APPROVED, CHANGES_REQUESTED } from './verdict.mjs';
 export { RunState, slugFor } from './state.mjs';
+export {
+  computeRunMetrics,
+  computeAggregateMetrics,
+  readRunManifest,
+  readRunManifests,
+} from './metrics.mjs';
+export {
+  resolveRunsDir,
+  getRunStatus,
+  listRunStatuses,
+  getAggregateMetrics,
+  runOperationalCommand,
+  listRuns,
+  getRun,
+  inspectRun,
+  cancelRun,
+  cleanRuns,
+  doctor,
+} from './operations.mjs';
+export { githubBackend } from './publish.mjs';
+export { gitlabBackend, glabTransport, parseGitLabRemoteUrl } from './backends/gitlab.mjs';