the-high-council 0.6.0

package/src/cost-forecast.js

@@ -0,0 +1,70 @@
+// v5 §1 candidate 7: a realistic-case cost estimate before picking a chain,
+// extending the project's existing "price before you run" discipline from
+// `estimateChainRows`'s worst-case (the chain's own declared token
+// assumptions, no history) to what this chain has actually cost on this
+// machine. DERIVED, same convention as spend.js/verdict-stats.js: no
+// ledger, read back from runs/*/report.json, repriced at CURRENT
+// pricing.json rather than trusting a historical run's own possibly-stale
+// `usd` field (a model's price can change between the run and today).
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { runIdToDate } from './spend.js';
+import { costOf } from './cost.js';
+
+const readJson = p => { try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return null; } };
+
+/**
+ * A cost range for `chainName`, built from every historical run of that
+ * exact chain in `runsDir` within the last `days`. The range is the
+ * observed min/max of what those runs actually cost, repriced at today's
+ * pricing.json - a real spread from real runs, not a fabricated tolerance
+ * formula. A single historical run gives a zero-width range (low === high)
+ * rather than inventing variance that was never observed.
+ * Never throws - a missing runs/ dir or no matching history is a note, not
+ * an error.
+ */
+export function forecastCost(chainName, runsDir, { days = 90, now = Date.now() } = {}) {
+  const cutoff = now - days * 24 * 3600 * 1000;
+
+  let ids = [];
+  try {
+    ids = existsSync(runsDir) ? readdirSync(runsDir) : [];
+  } catch {
+    return { chain: chainName, days, runsUsed: 0, low: null, high: null, mean: null, note: 'runs directory could not be read' };
+  }
+
+  const perRunUsd = [];
+  const unpriced = new Set();
+  for (const id of ids) {
+    const when = runIdToDate(id);
+    if (!when || when.getTime() < cutoff) continue;
+    const report = readJson(join(runsDir, id, 'report.json'));
+    if (!report || report.chain !== chainName) continue;
+
+    let total = 0;
+    for (const s of report.stages || []) {
+      if (!s.usage) continue;
+      const c = costOf(s.provider, s.model, s.usage);
+      total += c.usd;
+      if (!c.priced) unpriced.add(`${s.provider}/${s.model}`);
+    }
+    perRunUsd.push(total);
+  }
+
+  if (!perRunUsd.length) {
+    return { chain: chainName, days, runsUsed: 0, low: null, high: null, mean: null, note: 'no historical runs of this chain in the window' };
+  }
+
+  const low = Math.min(...perRunUsd);
+  const high = Math.max(...perRunUsd);
+  const mean = perRunUsd.reduce((a, b) => a + b, 0) / perRunUsd.length;
+
+  // A stage whose provider/model isn't in pricing.json prices as $0 - not
+  // "free", just unpriced. Flagging this rather than letting it silently
+  // understate the range, same discipline summarise() (cost.js) already
+  // applies to a single run's own total.
+  return {
+    chain: chainName, days, runsUsed: perRunUsd.length, low, high, mean,
+    ...(unpriced.size ? { partial: true, unpriced: [...unpriced], note: `${unpriced.size} model(s) in this history have no entry in pricing.json and were counted as $0: ${[...unpriced].join(', ')}` } : {}),
+  };
+}

package/src/cost.js

@@ -0,0 +1,139 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const PRICES = JSON.parse(readFileSync(join(here, 'pricing.json'), 'utf8'));
+
+export function priceOf(provider, model) {
+  return PRICES[`${provider}/${model}`] || null;
+}
+
+export function costOf(provider, model, usage) {
+  const p = priceOf(provider, model);
+  if (!p) return { usd: 0, priced: false };
+  const usd = (usage.input / 1e6) * p.in + (usage.output / 1e6) * p.out;
+  return { usd, priced: true };
+}
+
+export function summarise(stages) {
+  let input = 0, output = 0, usd = 0;
+  const unpriced = new Set();
+  for (const s of stages) {
+    if (!s.usage) continue;
+    input += s.usage.input;
+    output += s.usage.output;
+    const c = costOf(s.provider, s.model, s.usage);
+    usd += c.usd;
+    if (!c.priced) unpriced.add(`${s.provider}/${s.model}`);
+  }
+  return { input, output, total: input + output, usd, unpriced: [...unpriced] };
+}
+
+export function formatUsd(n) {
+  return n >= 1 ? `$${n.toFixed(2)}` : `$${n.toFixed(4)}`;
+}
+
+// ---------------------------------------------------------------------------
+// Per-chain worst-case estimate, from the config's own declared token
+// assumptions. Calls nothing, so it costs nothing. This is the one place that
+// walks a chain's stage shape (questions/criteria/skeleton/proposals/debate/
+// panel rounds/handoff) to price it - `--dry-run` and `council doctor` both
+// call this rather than each re-deriving the shape themselves.
+export function estimateChainRows(config, { fromRun = false } = {}) {
+  const a = config.estimate || { promptTokens: 4000, draftTokens: 6000, critiqueTokens: 1200 };
+  const rows = [];
+  const push = (label, seat, input, output) => {
+    if (!seat) return;
+    const p = seat.provider === 'external' ? { in: 0, out: 0 } : priceOf(seat.provider, seat.model);
+    const usd = p ? (input / 1e6) * p.in + (output / 1e6) * p.out : 0;
+    rows.push({ label, seat: `${seat.provider}/${seat.model}`, input, output, usd, priced: !!p });
+  };
+  if (config.questions && !fromRun) push('questions', config.seats.questions || config.seats.criteria, a.promptTokens, 800);
+  // A chain with hand-written criteria skips that stage entirely.
+  if (!config.criteria?.length) push('criteria', config.seats.criteria, a.promptTokens, 400);
+  let proposalTokens = 0;
+  if (config.proposals && !fromRun) {
+    const parts = config.proposals.parts ?? 3, per = config.proposals.maxTokens ?? 1500;
+    push('skeleton', config.seats.skeleton || config.seats.builder, a.promptTokens + 400, 1200);
+    const samples = config.proposals.samples ?? 1, keep = config.proposals.keep ?? parts;
+    for (const seat of config.seats.proposers || config.seats.critics) {
+      for (let k = 0; k < samples; k++) push(`propose-${seat.lab || seat.provider}${samples > 1 ? `-${k + 1}` : ''}`, seat, a.promptTokens + 1600, parts * per);
+      if (samples > 1) push(`judge-${seat.lab || seat.provider}`, config.seats.judge || seat, a.promptTokens + 1600 + samples * parts * per, 300);
+      proposalTokens += (samples > 1 ? keep : parts) * per;
+    }
+  }
+  if (config.debate && !fromRun) {
+    for (const seat of config.seats.proposers || config.seats.critics) {
+      push(`debate-${seat.lab || seat.provider}`, seat, a.promptTokens + 1600 + proposalTokens, 1500);
+      push(`reply-${seat.lab || seat.provider}`, seat, a.promptTokens + 3000, 800);
+    }
+    proposalTokens += proposalTokens; // the board roughly doubles what the builder reads
+  }
+  if (!fromRun) push('build', config.seats.builder, a.promptTokens + 400 + proposalTokens, a.draftTokens);
+  const unanimous = config.signoff === 'unanimous';
+  for (let r = 1; r <= config.maxRounds; r++) {
+    if (unanimous) {
+      for (const critic of config.seats.critics) {
+        push(`panel-${r}-${critic.lab || critic.provider}`, critic, a.promptTokens + a.draftTokens, a.critiqueTokens);
+      }
+    } else {
+      const critic = config.seats.critics[(r - 1) % config.seats.critics.length];
+      push(`critique-${r}`, critic, a.promptTokens + a.draftTokens, a.critiqueTokens);
+    }
+    if (r < config.maxRounds) push(`revise-${r}`, config.seats.reviser || config.seats.builder, a.promptTokens + a.draftTokens + a.critiqueTokens + proposalTokens, a.draftTokens);
+  }
+  push('final', config.seats.finalist, a.promptTokens + a.draftTokens, a.draftTokens);
+  if (config.handoff) push('handoff', config.seats.handoff || config.seats.builder, a.promptTokens + a.draftTokens, 1200);
+  return rows;
+}
+
+// ---------------------------------------------------------------------------
+// Per-run spend cap.
+//
+// costOf() above is measurement: what a stage cost once it had already been
+// paid for. A cap that only measures is not a cap, so enforcement needs a
+// number BEFORE the call goes out - hence a worst case rather than an actual.
+//
+// Worst case for one stage is: every prompt character billed as input, plus
+// the seat's entire maxTokens budget billed as output. A stage essentially
+// never spends its whole output budget, so this over-estimates on purpose - a
+// cap that occasionally stops a run slightly early is a working cap, and one
+// that lets a run slip past the ceiling is not.
+
+// Characters per token. Real tokenisers vary by model and language; 4 is the
+// usual English rule of thumb and errs low (i.e. estimates MORE tokens) on
+// the code and JSON these prompts are full of.
+const CHARS_PER_TOKEN = 4;
+
+export function estimateTokens(text) {
+  return Math.ceil((text || '').length / CHARS_PER_TOKEN);
+}
+
+/**
+ * The most this stage could cost. Returns 0 for a seat with no price entry -
+ * an unpriced model cannot be accounted for, so it cannot be capped either
+ * (this is why the $0 mock chains run freely under any ceiling).
+ *
+ * `retries` covers the thinking-disabled retry in chain.js invoke(), which
+ * can pay for the same stage twice.
+ */
+export function worstCaseOf(provider, model, { promptChars = 0, maxTokens = 8000, retries = 1 } = {}) {
+  const p = priceOf(provider, model);
+  if (!p) return { usd: 0, priced: false };
+  const input = Math.ceil(promptChars / CHARS_PER_TOKEN);
+  const usd = ((input / 1e6) * p.in + (maxTokens / 1e6) * p.out) * retries;
+  return { usd, priced: true };
+}
+
+/**
+ * Would running this stage risk breaching the ceiling? Pure, so it is
+ * testable without a provider.
+ *
+ * `cap` of null means no ceiling and always returns ok.
+ */
+export function wouldBreach({ spent, cap, projected }) {
+  if (cap === null || cap === undefined) return { breach: false };
+  const after = spent + projected;
+  return { breach: after > cap, after, remaining: Math.max(0, cap - spent) };
+}

package/src/errors.js

@@ -0,0 +1,82 @@
+// v5 §1 candidate 4: a small, stable catalog of the codes this project's
+// hard-fail paths actually hit, each with a one-line cause, a one-line
+// fix naming a real file, and a doc pointer - documented in
+// TROUBLESHOOTING.md, which every code here must also appear in (checked
+// by test/errors.test.js).
+//
+// Tone, fixed by Muad from a concrete preview (2026-09-13): name what's
+// wrong in plain words, explain what the missing concept IS in one line
+// (not just that it's absent), blank line, then the concrete fix with a
+// real path, then a doc pointer. No jargon the reader hasn't met yet. No
+// apology, no personality, no exclamation marks - warm is not chatty.
+// `formatCouncilError` enforces this shape mechanically so no call site
+// can drift from it by writing its own message.
+
+export const ERROR_CATALOG = {
+  'COUNCIL-E001': {
+    kind: 'degradable',
+    title: 'Missing API key',
+    render: ctx => ({
+      what: `The "${ctx.provider}" API key isn't set, so chain "${ctx.chain}" can't call that lab.`,
+      concept: `An API key is what proves to ${ctx.provider} that a request is yours to pay for - without it, every call to that lab fails before it starts.`,
+      fix: `Set ${ctx.envVar} in your .env file.`,
+      doc: 'README.md#setup',
+    }),
+  },
+  'COUNCIL-E002': {
+    kind: 'degradable',
+    title: 'Unpriced model',
+    render: ctx => ({
+      what: `"${ctx.provider}/${ctx.model}" has no listed price, so its cost can't be shown or added to your spend total.`,
+      concept: `A price is the per-token rate this program uses to add up what a run will cost before you pay for it.`,
+      fix: `Add an entry for "${ctx.provider}/${ctx.model}" to src/pricing.json.`,
+      doc: 'README.md#the-spend-cap',
+    }),
+  },
+  'COUNCIL-E003': {
+    kind: 'fatal',
+    title: 'Malformed chain file',
+    render: ctx => ({
+      what: `The chain file "${ctx.path}" isn't valid JSON, so it can't be read at all.`,
+      concept: `A chain file is the plain JSON config that says which models fill which seat - a syntax error anywhere in it stops the whole file from parsing.`,
+      fix: `Check ${ctx.path} for a missing comma, bracket, or quote.`,
+      doc: 'README.md#chains',
+    }),
+  },
+  'COUNCIL-E004': {
+    kind: 'degradable',
+    title: 'Unreadable stage reply',
+    render: ctx => ({
+      what: `The reply from "${ctx.lab}" for stage "${ctx.label}" couldn't be read as the JSON this stage expects.`,
+      concept: `A stage reply is one lab's structured answer for one step of the chain - an unreadable one is treated as an abstention, not a failure, so the run continues without it.`,
+      fix: `Read the saved reply at ${ctx.file || 'runs/<id>/<label>.md'} to see what that lab actually returned.`,
+      doc: 'TROUBLESHOOTING.md#council-e004',
+    }),
+  },
+};
+
+/**
+ * The full, tone-shaped message for `code`, filled with `ctx`. Throws if
+ * `code` isn't in the catalog - a call site using an unknown code is a
+ * bug in this codebase, not a user-facing condition.
+ */
+export function formatCouncilError(code, ctx = {}) {
+  const entry = ERROR_CATALOG[code];
+  if (!entry) throw new Error(`formatCouncilError: unknown code "${code}"`);
+  const { what, concept, fix, doc } = entry.render(ctx);
+  return `${code} [${entry.kind}] ${entry.title}\n${what} ${concept}\n\n${fix}\nSee: ${doc}`;
+}
+
+/**
+ * An Error carrying a catalog `code` and its `kind` (degradable|fatal), so
+ * a top-level catch can print the tone-shaped message and choose an exit
+ * code without re-deriving either.
+ */
+export class CouncilError extends Error {
+  constructor(code, ctx = {}) {
+    super(formatCouncilError(code, ctx));
+    this.code = code;
+    this.kind = ERROR_CATALOG[code]?.kind;
+    this.ctx = ctx;
+  }
+}

package/src/http-server.js

@@ -0,0 +1,349 @@
+#!/usr/bin/env node
+// relay as a network service: trigger-service (sower-industries.de's order pipeline) calling a
+// deployed relay instance over HTTPS, since Fly.io machines don't share a filesystem the way a
+// local sibling-checkout does. Blocking request/response, not detached-and-polled like
+// src/mcp/server.js's tools - this mirrors trigger-service's own existing jobs/start-run.js and
+// jobs/resume-harness.js exactly (a real chain run/resume already blocks the buyer's own HTTP
+// request today; this doesn't change that shape, only moves where the child process runs).
+//
+// 2026-09-09: built under an explicit author override of the 2026-09-08 scope-gate KILL-DESCOPE
+// verdict on relay productionization (sower-industries/Docs/working-agreements-scars.md carries
+// the original verdict; sower-industries/PLAN.md's Parking lot section names the four defects this
+// build addresses: wrong dependency facts (fixed below - see requiredEnvForChain(), derived from
+// a chain's own seats table rather than guessed), no crash-recovery/idempotency (the idempotency
+// store below - disk-persisted at idemDir, its own volume in production, same as runs/), no budget
+// guard on the endpoint (dailyUsage() below, a backstop behind trigger-service's own
+// MAX_USD_PER_DAY check - this is defense in depth, not the primary guard), and a missed reuse of
+// relay's own MCP server (src/mcp/server.js's run-state functions - runSummary/waiting/safeRun -
+// are the same disk-as-source-of-truth model this file uses; not literally shared code, since the
+// MCP server's detached-and-polled execution model and this file's blocking one are genuinely
+// different shapes, but the same conventions: a run's true state always comes from its runs/<id>/
+// folder on disk, never from in-memory state that a restart would lose).
+import express from 'express';
+import crypto from 'node:crypto';
+import { spawn as nodeSpawn } from 'node:child_process';
+import {
+  existsSync, readFileSync, readdirSync, writeFileSync, mkdirSync, mkdtempSync, copyFileSync,
+} from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { tmpdir } from 'node:os';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const root = resolve(here, '..');
+
+// The only chain trigger-service actually starts (jobs/start-run.js's own DEFAULT_CHAIN,
+// 'plan-auto') - read directly from that chain's own seats table rather than assumed, so this list
+// can't drift from the chain config the way the original scope-gated spec's provider list did.
+// Every other chain this repo can run is out of scope for this endpoint on purpose - trigger-
+// service's own RELAY_CHAIN env var (start-run.js) could in principle name a different chain, in
+// which case its provider keys would also need to be Fly secrets here; this constant is a
+// documented default, not a hard runtime restriction.
+export function requiredEnvForChain(chainName, chainsDir = join(root, 'chains')) {
+  const configPath = join(chainsDir, `${chainName}.json`);
+  if (!existsSync(configPath)) return [];
+  const config = JSON.parse(readFileSync(configPath, 'utf8'));
+  const providers = new Set();
+  const seats = config.seats || {};
+  for (const [key, seat] of Object.entries(seats)) {
+    if (key === 'critics') {
+      for (const critic of seat) providers.add(critic.provider);
+    } else if (seat?.provider) {
+      providers.add(seat.provider);
+    }
+  }
+  const KEY_BY_PROVIDER = {
+    anthropic: 'ANTHROPIC_API_KEY', openai: 'OPENAI_API_KEY', google: 'GOOGLE_API_KEY',
+    xai: 'XAI_API_KEY', mistral: 'MISTRAL_API_KEY', deepseek: 'DEEPSEEK_API_KEY',
+    groq: 'GROQ_API_KEY', cohere: 'COHERE_API_KEY', openrouter: 'OPENROUTER_API_KEY',
+    together: 'TOGETHER_API_KEY', zai: 'ZAI_API_KEY',
+  };
+  return [...providers].map((p) => KEY_BY_PROVIDER[p]).filter(Boolean).sort();
+}
+
+const readJson = (p) => { try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return null; } };
+const safeRunId = (id) => /^[0-9TZ-]+$/.test(id) && existsSync(join(root, 'runs', id));
+
+// Run ids are relay's own timestamp format (src/cli.js: `new Date().toISOString().replace(...)`),
+// e.g. `2026-09-08T10-44-43-969Z` - reversible back to a real Date without needing a second,
+// separately-maintained timestamp store.
+function runIdToDate(runId) {
+  const iso = runId.replace(/T(\d{2})-(\d{2})-(\d{2})-(\d{3})Z$/, 'T$1:$2:$3.$4Z');
+  const d = new Date(iso);
+  return Number.isNaN(d.getTime()) ? null : d;
+}
+
+/**
+ * Defense-in-depth spend guard at this endpoint's own layer - trigger-service's own
+ * spend.js/budgetOk() (checked before it ever calls this service) is the primary guard; this one
+ * exists because Docs/working-agreements-scars.md's recorded scope-gate verdict named "no budget
+ * guard on the newly-exposed endpoint" as a real defect, and an endpoint reachable by anything
+ * holding the bearer token should not trust a caller's own pre-check as its only protection.
+ * Source of truth is runs/ on disk (each run's own report.json.totals.usd), same
+ * disk-not-memory convention as the rest of this file - nothing here is lost on a restart.
+ */
+export function dailyUsage(runsDir, now = Date.now()) {
+  const cutoff = now - 24 * 3600 * 1000;
+  let usd = 0;
+  let count = 0;
+  for (const id of existsSync(runsDir) ? readdirSync(runsDir) : []) {
+    const d = runIdToDate(id);
+    if (!d || d.getTime() < cutoff) continue;
+    count += 1;
+    usd += readJson(join(runsDir, id, 'report.json'))?.totals?.usd ?? 0;
+  }
+  return { usd, count };
+}
+
+function runChildForeground({ spawnFn, args, cwd }) {
+  return new Promise((resolvePromise) => {
+    let child;
+    try {
+      child = spawnFn('node', args, { cwd });
+    } catch (err) {
+      resolvePromise({ code: null, stderr: String(err?.message ?? err) });
+      return;
+    }
+    let stderr = '';
+    child.stderr?.on('data', (d) => { stderr += d.toString(); });
+    child.on('error', (err) => resolvePromise({ code: null, stderr: stderr + String(err?.message ?? err) }));
+    child.on('close', (code) => resolvePromise({ code, stderr }));
+  });
+}
+
+// Filtered to relay's own run-id shape (src/cli.js: an ISO-8601 timestamp with `:`/`.` swapped for
+// `-`, e.g. `2026-09-08T10-44-43-969Z`) - the same pattern src/mcp/server.js's own safeRun() already
+// checks. Without this filter, any other new entry appearing under runsDir in the same before/after
+// window (this file's own idempotency store, if it ever shared this directory; a future unrelated
+// tool writing here) could be mistaken for the run this request just started.
+const RUN_ID_PATTERN = /^[0-9TZ-]+$/;
+function findNewRunDir(runsDir, before) {
+  if (!existsSync(runsDir)) return null;
+  return readdirSync(runsDir).find((d) => !before.has(d) && RUN_ID_PATTERN.test(d)) ?? null;
+}
+
+// Idempotency store: one JSON file per idempotency key (trigger-service passes its own order id).
+// {status:'pending'} while a spawn is in progress; {status:'done', statusCode, body} once resolved,
+// replayed verbatim to a retried request instead of spawning a second run for the same order.
+// Atomic create via the 'wx' flag - a second concurrent request for the same key gets EEXIST and is
+// told to poll, never silently spawns a duplicate.
+//
+// 2026-09-09: moved off relayRoot's own ephemeral local disk onto its own persistent path
+// (idemDir, independent of runsDir - see createRelayHttpServer's own comment on why it isn't
+// nested under runs/ itself) once the author asked for the "lost on restart" tradeoff closed -
+// same disk-as-source-of-truth durability runs/ already gets from its own Fly volume.
+function idempotencyPath(idemDir, key) {
+  return join(idemDir, `${key.replace(/[^a-zA-Z0-9_-]/g, '_')}.json`);
+}
+
+function claimIdempotencyKey(idemDir, key) {
+  mkdirSync(idemDir, { recursive: true });
+  const path = idempotencyPath(idemDir, key);
+  if (existsSync(path)) {
+    const existing = readJson(path);
+    return { claimed: false, existing };
+  }
+  try {
+    writeFileSync(path, JSON.stringify({ status: 'pending', startedAt: new Date().toISOString() }), { flag: 'wx' });
+    return { claimed: true, path };
+  } catch (err) {
+    if (err.code === 'EEXIST') return { claimed: false, existing: readJson(path) };
+    throw err;
+  }
+}
+
+function resolveIdempotencyKey(path, statusCode, body) {
+  writeFileSync(path, JSON.stringify({ status: 'done', statusCode, body, finishedAt: new Date().toISOString() }));
+}
+
+/**
+ * createRelayHttpServer({ root, token, spawnFn, maxUsdPerDay, maxRunsPerDay, idemDir }) - factory
+ * shape matching trigger-service's own createXRouter()/createXRouter() dependency-injection
+ * convention (webhooks/stripe.js, jobs/checkpoint.js) so this is testable against a stub spawnFn,
+ * no real child process, no real API keys, same pattern as that repo's own 40-test suite.
+ *
+ * `idemDir` defaults to `<relayRoot>/.idempotency` (local disk, matching every prior default) but
+ * is independently overridable - production points it at its own persistent volume, deliberately
+ * NOT nested under `runsDir` (`runs/.idempotency/` would durability-wise be simpler - one mount
+ * instead of two - but every directory under runs/ is treated as a run by src/mcp/server.js's and
+ * src/ui/server.js's own `list_runs`/UI listings, neither of which this file's own idempotency
+ * bookkeeping should ever show up in).
+ */
+export function createRelayHttpServer({
+  relayRoot = root,
+  token = process.env.RELAY_SERVICE_TOKEN,
+  spawnFn = nodeSpawn,
+  maxUsdPerDay = Number(process.env.MAX_USD_PER_DAY || 20),
+  maxRunsPerDay = Number(process.env.MAX_RUNS_PER_DAY || 5),
+  idemDir = process.env.RELAY_IDEMPOTENCY_DIR || join(relayRoot, '.idempotency'),
+} = {}) {
+  const runsDir = join(relayRoot, 'runs');
+  const cliPath = join(relayRoot, 'src', 'cli.js');
+  const resumingNow = new Set();
+
+  const app = express();
+  app.use(express.json({ limit: '256kb' }));
+
+  app.get('/health', (req, res) => {
+    res.json({ status: 'ok', spendLast24h: dailyUsage(runsDir) });
+  });
+
+  app.use((req, res, next) => {
+    const header = req.headers.authorization || '';
+    const provided = header.startsWith('Bearer ') ? header.slice(7) : '';
+    const expected = token || '';
+    const providedBuf = Buffer.from(provided);
+    const expectedBuf = Buffer.from(expected);
+    const ok = expected.length > 0
+      && providedBuf.length === expectedBuf.length
+      && crypto.timingSafeEqual(providedBuf, expectedBuf);
+    if (!ok) {
+      res.status(401).json({ error: 'unauthorized' });
+      return;
+    }
+    next();
+  });
+
+  app.post('/runs', async (req, res) => {
+    const { chain, taskContent, idempotencyKey } = req.body ?? {};
+    if (typeof chain !== 'string' || typeof taskContent !== 'string' || typeof idempotencyKey !== 'string' || !chain || !taskContent || !idempotencyKey) {
+      res.status(400).json({ error: 'malformed_request' });
+      return;
+    }
+
+    const usage = dailyUsage(runsDir);
+    if (usage.usd >= maxUsdPerDay || usage.count >= maxRunsPerDay) {
+      res.status(503).json({ error: 'budget_exceeded', reason: usage.usd >= maxUsdPerDay ? 'usd_cap' : 'run_cap', usage });
+      return;
+    }
+
+    const claim = claimIdempotencyKey(idemDir, idempotencyKey);
+    if (!claim.claimed) {
+      if (claim.existing?.status === 'done') {
+        res.status(claim.existing.statusCode).json(claim.existing.body);
+        return;
+      }
+      res.status(409).json({ error: 'in_progress' });
+      return;
+    }
+
+    const taskDir = mkdtempSync(join(tmpdir(), 'relay-service-task-'));
+    const taskPath = join(taskDir, `${idempotencyKey}.md`);
+    writeFileSync(taskPath, taskContent);
+
+    const before = new Set(existsSync(runsDir) ? readdirSync(runsDir) : []);
+    const { code, stderr } = await runChildForeground({
+      spawnFn, args: [cliPath, '--chain', chain, '--task', taskPath], cwd: relayRoot,
+    });
+
+    let statusCode;
+    let body;
+
+    if (code === 3) {
+      const runId = findNewRunDir(runsDir, before);
+      const needsPath = runId ? join(runsDir, runId, 'NEEDS-answers.md') : null;
+      if (!runId || !existsSync(needsPath)) {
+        statusCode = 500;
+        body = { outcome: 'error', reason: 'run_start_failed', runId };
+      } else {
+        const questionsRaw = readFileSync(join(runsDir, runId, 'questions.md'), 'utf8');
+        const parsed = JSON.parse(questionsRaw.slice(questionsRaw.indexOf('{'), questionsRaw.lastIndexOf('}') + 1));
+        const questions = (Array.isArray(parsed?.questions) ? parsed.questions : []).map((q) => q.question).filter(Boolean);
+        statusCode = 200;
+        body = { outcome: 'paused', runId, questions };
+      }
+    } else if (code === 0) {
+      const runId = findNewRunDir(runsDir, before);
+      statusCode = 200;
+      body = { outcome: 'completed', runId };
+    } else {
+      statusCode = 500;
+      body = { outcome: 'error', reason: 'nonzero_exit', exitCode: code, stderrTail: stderr.slice(-500) };
+    }
+
+    resolveIdempotencyKey(claim.path, statusCode, body);
+    res.status(statusCode).json(body);
+  });
+
+  app.post('/runs/:id/resume', async (req, res) => {
+    const { id } = req.params;
+    const { answersText } = req.body ?? {};
+    if (!safeRunId(id)) {
+      res.status(404).json({ error: 'no_such_run' });
+      return;
+    }
+    if (typeof answersText !== 'string' || !answersText) {
+      res.status(400).json({ error: 'malformed_request' });
+      return;
+    }
+    if (resumingNow.has(id)) {
+      res.status(409).json({ error: 'resume_in_progress' });
+      return;
+    }
+    resumingNow.add(id);
+
+    try {
+      const runDir = join(runsDir, id);
+      writeFileSync(join(runDir, 'answers.md'), answersText);
+
+      const { code, stderr } = await runChildForeground({
+        spawnFn, args: [cliPath, '--resume', join('runs', id)], cwd: relayRoot,
+      });
+
+      if (code !== 0) {
+        res.status(500).json({ success: false, error: 'nonzero_exit', exitCode: code, stderrTail: stderr.slice(-500) });
+        return;
+      }
+
+      // Relay never writes a file literally named PLAN.md - it writes deliverable.md. Same
+      // copy-if-missing step trigger-service's own resume-harness.js already does today; moved
+      // here since this is now where the run folder actually lives.
+      const deliverablePath = join(runDir, 'deliverable.md');
+      const planPath = join(runDir, 'PLAN.md');
+      if (existsSync(deliverablePath) && !existsSync(planPath)) {
+        copyFileSync(deliverablePath, planPath);
+      }
+
+      const missing = ['PLAN.md', 'BOARD.md', 'HANDOFF.md'].filter((f) => !existsSync(join(runDir, f)));
+      if (missing.length > 0) {
+        res.status(500).json({ success: false, error: 'missing_output_files', missing });
+        return;
+      }
+      res.status(200).json({ success: true });
+    } finally {
+      resumingNow.delete(id);
+    }
+  });
+
+  app.get('/runs/:id/attachments', (req, res) => {
+    const { id } = req.params;
+    if (!safeRunId(id)) {
+      res.status(404).json({ error: 'no_such_run' });
+      return;
+    }
+    const runDir = join(runsDir, id);
+    const files = ['PLAN.md', 'BOARD.md', 'HANDOFF.md']
+      .filter((f) => existsSync(join(runDir, f)))
+      .map((f) => ({ filename: f, content: readFileSync(join(runDir, f), 'utf8') }));
+    res.status(200).json({ files });
+  });
+
+  app.use((req, res) => {
+    res.status(404).json({ error: 'not_found' });
+  });
+
+  return app;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const PORT = Number(process.env.PORT || 8090);
+  if (!process.env.RELAY_SERVICE_TOKEN) {
+    console.error('RELAY_SERVICE_TOKEN not set - refusing to start (this endpoint holds live LLM provider keys).');
+    process.exit(1);
+  }
+  const app = createRelayHttpServer({});
+  app.listen(PORT, () => {
+    console.log(`relay http-server listening on :${PORT}`);
+    console.log(`required env for plan-auto: ${requiredEnvForChain('plan-auto').join(', ')}`);
+  });
+}