wicked-crew 0.7.1 → 0.7.3

package/dist/campaign/supervision.js

@@ -0,0 +1,515 @@
+// Campaign budget/runtime governance (TH-20 / test-R22): the crew-side supervision layer
+// that makes campaign spend BOUNDED and every abort VISIBLE.
+//
+// Why this exists: core's `CampaignDef` carries exactly one resource knob — `max_concurrency`
+// (DES-CAMPAIGN-001 §2) — and the engine's per-unit wall-clock default is 2 HOURS
+// (wicked-core `execute_wrapped.rs` `unit_timeout()`, override `WICKED_UNIT_TIMEOUT_SECS`).
+// A nightly 20+-node governed campaign with no ceiling is an unbounded spend commitment.
+//
+// KNOB PLACEMENT — the P-9 interim decision, recorded here on purpose:
+//   Budget/timeout/kill knobs live CREW-SIDE (this module), NOT as `CampaignDef` fields in
+//   core. Crew supervision ships without a core release and rides the cancel path that
+//   already exists (`CancelRun` via the adapter). The accepted cost: supervision state does
+//   not survive an ENGINE-ONLY resume — resume a campaign without the crew daemon and
+//   nothing enforces the budget. Moving the knobs into `CampaignDef` (where they would
+//   survive resume) stays open as P-9's core-maintainer call; this module is written so the
+//   policy type can migrate onto the def without changing its semantics.
+//   Doctrine + operator docs: `docs/campaign-budgets.md`.
+//
+// What the supervisor enforces, sweep-driven like `api/stall-watchdog.ts` (same
+// deps-injected/fake-clock idiom) but ENFORCING where the watchdog is detection-only:
+//   1. Per-node timeout — a node RUNNING longer than `nodeTimeoutMs` is cancelled with an
+//      explicit `node-timeout` exclusion. `awaiting-human` never counts against it (a gate
+//      is quiet by design and burns no worker spend).
+//   2. Campaign wall-clock budget — when `elapsed > wallClockBudgetMs`, remaining nodes are
+//      aborted with EXCLUDED-WITH-REASON status: never-launched nodes are excluded at the
+//      scheduler so they can never dispatch; in-flight nodes follow the kill policy
+//      (`kill-running` cancels them, `abandon-running` lets them finish while launching
+//      nothing new). Exclusion is NEVER silent: it lands in supervision state, in the
+//      evidence report, on the /ws fan-out as synthetic frames, and in the warn log.
+//   3. Campaign cost budget (opt-in) — same exhaustion path keyed on recorded USD cost.
+//   4. Nightly cap — `assertWithinNightlyCap` fail-closed preflight on node count, so the
+//      TH-23 nightly recipe cannot launch an uncapped campaign by omission.
+//
+// Cost per node is recorded in evidence: the supervisor stamps wall-clock per node itself
+// (always available) and accepts token/USD figures via `recordNodeCost` when the worker CLI
+// reports them; `buildSupervisionReport`/`writeSupervisionReport` emit the
+// `campaign-supervision.json` evidence artifact whose per-node rows the TH-14 scoreboard
+// cost column diffs — cost regressions become visible exactly like verdict regressions.
+// (Deliberately an ARTIFACT, not new ledger-manifest fields: manifest 2.1 is wicked-ledger's
+// contract and moves through its owner's release train, never ad hoc — ADR 0006.)
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** Campaign-proven pin (the 2026-08 studio E2E campaign ran `WICKED_UNIT_TIMEOUT_SECS=900`). */
+export const DEFAULT_UNIT_TIMEOUT_SECS = 900;
+/** Default per-node timeout: 30 min ≈ 4× the observed 7m41s governed feature run. */
+export const DEFAULT_NODE_TIMEOUT_SECS = 1_800;
+/** Default campaign wall-clock budget: 4 h (a 21-node ladder ≈ 2.7 h serial at observed rate). */
+export const DEFAULT_WALL_CLOCK_BUDGET_SECS = 14_400;
+/** Default nightly node cap (the proven ladder was 21 scenarios; 25 leaves headroom). */
+export const DEFAULT_MAX_NODES = 25;
+export const DEFAULT_KILL_POLICY = 'kill-running';
+/** The env knobs `resolveBudgetPolicy` reads. All crew-side; documented in docs/campaign-budgets.md. */
+export const ENV_BUDGET_SECS = 'WICKED_CAMPAIGN_BUDGET_SECS';
+export const ENV_NODE_TIMEOUT_SECS = 'WICKED_CAMPAIGN_NODE_TIMEOUT_SECS';
+export const ENV_UNIT_TIMEOUT_SECS = 'WICKED_UNIT_TIMEOUT_SECS';
+export const ENV_MAX_NODES = 'WICKED_CAMPAIGN_MAX_NODES';
+export const ENV_MAX_COST_USD = 'WICKED_CAMPAIGN_MAX_COST_USD';
+export const ENV_KILL_POLICY = 'WICKED_CAMPAIGN_KILL_POLICY';
+/** Strict positive-number parse: rejects '', '4h', '-1', '0', NaN — never a silent fallback. */
+function parsePositive(name, raw) {
+    const trimmed = raw.trim();
+    const n = /^\d+(\.\d+)?$/.test(trimmed) ? Number(trimmed) : Number.NaN;
+    if (!Number.isFinite(n) || n <= 0) {
+        throw new Error(`campaign budget policy: ${name}=${JSON.stringify(raw)} is not a positive number — ` +
+            `refusing to guess (a malformed ceiling must never mean "unbounded")`);
+    }
+    return n;
+}
+/**
+ * Resolve the budget policy from an environment (defaults ↦ documented ceilings; malformed
+ * values throw — fail closed, TH-8 posture). Pass `process.env` in the daemon; tests pass
+ * a literal.
+ */
+export function resolveBudgetPolicy(env = process.env) {
+    const budgetSecs = env[ENV_BUDGET_SECS] !== undefined && env[ENV_BUDGET_SECS] !== ''
+        ? parsePositive(ENV_BUDGET_SECS, env[ENV_BUDGET_SECS])
+        : DEFAULT_WALL_CLOCK_BUDGET_SECS;
+    const nodeTimeoutSecs = env[ENV_NODE_TIMEOUT_SECS] !== undefined && env[ENV_NODE_TIMEOUT_SECS] !== ''
+        ? parsePositive(ENV_NODE_TIMEOUT_SECS, env[ENV_NODE_TIMEOUT_SECS])
+        : DEFAULT_NODE_TIMEOUT_SECS;
+    // The ambient WICKED_UNIT_TIMEOUT_SECS is HONORED as the pin (integer seconds — the
+    // engine's own u64 parse would reject a fraction, so we must too).
+    const rawUnit = env[ENV_UNIT_TIMEOUT_SECS];
+    let unitTimeoutSecs = DEFAULT_UNIT_TIMEOUT_SECS;
+    if (rawUnit !== undefined && rawUnit !== '') {
+        unitTimeoutSecs = parsePositive(ENV_UNIT_TIMEOUT_SECS, rawUnit);
+        if (!Number.isInteger(unitTimeoutSecs)) {
+            throw new Error(`campaign budget policy: ${ENV_UNIT_TIMEOUT_SECS}=${JSON.stringify(rawUnit)} must be ` +
+                `an integer number of seconds (the engine parses it as u64 and would silently ` +
+                `ignore this value, falling back to its 2-hour default)`);
+        }
+    }
+    const maxNodes = env[ENV_MAX_NODES] !== undefined && env[ENV_MAX_NODES] !== ''
+        ? parsePositive(ENV_MAX_NODES, env[ENV_MAX_NODES])
+        : DEFAULT_MAX_NODES;
+    if (!Number.isInteger(maxNodes)) {
+        throw new Error(`campaign budget policy: ${ENV_MAX_NODES} must be an integer node count, got ` +
+            JSON.stringify(env[ENV_MAX_NODES]));
+    }
+    const rawKill = env[ENV_KILL_POLICY];
+    let killPolicy = DEFAULT_KILL_POLICY;
+    if (rawKill !== undefined && rawKill !== '') {
+        if (rawKill !== 'kill-running' && rawKill !== 'abandon-running') {
+            throw new Error(`campaign budget policy: ${ENV_KILL_POLICY}=${JSON.stringify(rawKill)} — expected ` +
+                `"kill-running" or "abandon-running"`);
+        }
+        killPolicy = rawKill;
+    }
+    const policy = {
+        wallClockBudgetMs: budgetSecs * 1_000,
+        nodeTimeoutMs: nodeTimeoutSecs * 1_000,
+        unitTimeoutSecs,
+        maxNodes,
+        killPolicy,
+    };
+    const rawCost = env[ENV_MAX_COST_USD];
+    if (rawCost !== undefined && rawCost !== '') {
+        policy.maxCostUsd = parsePositive(ENV_MAX_COST_USD, rawCost);
+    }
+    return policy;
+}
+/**
+ * The TH-8-style environment pins every campaign node MUST launch with. Until the full
+ * TH-8 environment manifest lands, this is the manifest's budget block: the interim
+ * mitigation test-R22 names ("the environment manifest must pin WICKED_UNIT_TIMEOUT_SECS").
+ */
+export function nodeEnvPins(policy) {
+    return { [ENV_UNIT_TIMEOUT_SECS]: String(policy.unitTimeoutSecs) };
+}
+/**
+ * Fail-closed preflight: a node environment must carry the exact `WICKED_UNIT_TIMEOUT_SECS`
+ * pin the policy resolved. Missing ⇒ the engine's 2-hour default applies silently;
+ * mismatched ⇒ the manifest lies about the environment. Both refuse.
+ */
+export function assertNodeEnvPinned(nodeEnv, policy) {
+    const pin = nodeEnv[ENV_UNIT_TIMEOUT_SECS];
+    if (pin === undefined || pin.trim() === '') {
+        throw new Error(`campaign preflight: node environment is missing the ${ENV_UNIT_TIMEOUT_SECS} pin ` +
+            `(expected "${policy.unitTimeoutSecs}"). Unpinned, the engine defaults to 7200 s ` +
+            `per unit — refusing to launch an effectively unbounded node`);
+    }
+    if (pin.trim() !== String(policy.unitTimeoutSecs)) {
+        throw new Error(`campaign preflight: ${ENV_UNIT_TIMEOUT_SECS} pin mismatch — node environment says ` +
+            `${JSON.stringify(pin)}, the budget policy pinned "${policy.unitTimeoutSecs}". ` +
+            `Fail-closed: fix the environment or the policy, never both silently`);
+    }
+}
+/**
+ * Nightly cap, fail-closed (test-R22 interim: "the nightly recipe must cap campaign size
+ * explicitly"). Called with the campaign's node count BEFORE launch; over-cap refuses with
+ * both numbers so the operator sees exactly what to trim or raise.
+ */
+export function assertWithinNightlyCap(nodeCount, policy) {
+    if (!Number.isInteger(nodeCount) || nodeCount < 0) {
+        throw new Error(`campaign preflight: node count must be a non-negative integer, got ${nodeCount}`);
+    }
+    if (nodeCount > policy.maxNodes) {
+        throw new Error(`campaign preflight: ${nodeCount} nodes exceeds the nightly cap of ${policy.maxNodes} ` +
+            `(${ENV_MAX_NODES}). Refusing to launch — split the campaign or raise the cap ` +
+            `explicitly; an uncapped nightly is an unbounded spend commitment`);
+    }
+}
+/** Default sweep cadence: budgets are minutes-scale; 15 s keeps overshoot ≪ any ceiling. */
+export const DEFAULT_SUPERVISION_SWEEP_INTERVAL_MS = 15_000;
+export class CampaignSupervisor {
+    deps;
+    campaigns = new Map();
+    now;
+    log;
+    handle = null;
+    sweeping = false;
+    constructor(deps) {
+        this.deps = deps;
+        this.now = deps.now ?? Date.now;
+        this.log = deps.log ?? (() => undefined);
+    }
+    /**
+     * Begin supervising a campaign under a policy. Call at launch — the wall clock starts
+     * HERE, not at the first sweep. Re-registering an id is a bug (two clocks, one spend).
+     */
+    supervise(campaignId, policy) {
+        if (this.campaigns.has(campaignId)) {
+            throw new Error(`campaign ${campaignId} is already supervised — refusing a second clock`);
+        }
+        this.campaigns.set(campaignId, {
+            policy,
+            startedAt: this.now(),
+            elapsedMs: 0,
+            released: false,
+            nodes: new Map(),
+        });
+    }
+    /**
+     * Stop ENFORCING (campaign reached a terminal status). State stays readable — deliberately
+     * no delete, or a post-terminal report would be irrecoverable. Also reached automatically
+     * when a sweep observes every node terminal.
+     */
+    release(campaignId) {
+        const c = this.campaigns.get(campaignId);
+        if (c !== undefined)
+            c.released = true;
+    }
+    /** Record pipeline-reported cost for a node (tokens/USD — wall-clock is supervisor-owned). */
+    recordNodeCost(campaignId, nodeId, cost) {
+        const c = this.campaigns.get(campaignId);
+        if (c === undefined)
+            return; // unknown campaign: cost with no supervision to attribute it to
+        const node = this.trackNode(c, nodeId);
+        if (cost.usd !== undefined)
+            node.cost.usd = (node.cost.usd ?? 0) + cost.usd;
+        if (cost.inputTokens !== undefined) {
+            node.cost.inputTokens = (node.cost.inputTokens ?? 0) + cost.inputTokens;
+        }
+        if (cost.outputTokens !== undefined) {
+            node.cost.outputTokens = (node.cost.outputTokens ?? 0) + cost.outputTokens;
+        }
+    }
+    /** The supervision state for one campaign, or undefined when it was never supervised. */
+    state(campaignId) {
+        const c = this.campaigns.get(campaignId);
+        if (c === undefined)
+            return undefined;
+        const totalCostUsd = this.totalCostUsd(c);
+        const state = {
+            campaignId,
+            policy: c.policy,
+            startedAt: c.startedAt,
+            elapsedMs: c.elapsedMs,
+            // Explicit copy: the internal `runningSince` bookkeeping never leaves the supervisor.
+            nodes: [...c.nodes.values()].map((n) => {
+                const row = { nodeId: n.nodeId, phase: n.phase, cost: { ...n.cost } };
+                if (n.runId !== undefined)
+                    row.runId = n.runId;
+                if (n.startedAt !== undefined)
+                    row.startedAt = n.startedAt;
+                if (n.exclusion !== undefined)
+                    row.exclusion = { ...n.exclusion };
+                return row;
+            }),
+        };
+        if (totalCostUsd !== undefined)
+            state.totalCostUsd = totalCostUsd;
+        if (c.exhausted !== undefined)
+            state.exhausted = { ...c.exhausted };
+        return state;
+    }
+    /** One enforcement pass over every supervised campaign. Tests drive it directly. */
+    async sweep() {
+        if (this.sweeping)
+            return; // a slow scheduler read must never stack sweeps
+        this.sweeping = true;
+        try {
+            for (const [campaignId, c] of this.campaigns) {
+                try {
+                    await this.sweepCampaign(campaignId, c);
+                }
+                catch (err) {
+                    this.log(`[campaign-supervision] sweep of ${campaignId} failed: ${String(err)}`);
+                }
+            }
+        }
+        finally {
+            this.sweeping = false;
+        }
+    }
+    /** Arm the periodic sweep. Unref'd — the daemon's server lifecycle owns shutdown. */
+    start(intervalMs = DEFAULT_SUPERVISION_SWEEP_INTERVAL_MS) {
+        if (this.handle !== null)
+            return;
+        this.handle = setInterval(() => {
+            this.sweep().catch((err) => {
+                this.log(`[campaign-supervision] sweep failed: ${String(err)}`);
+            });
+        }, intervalMs);
+        this.handle.unref?.();
+    }
+    stop() {
+        if (this.handle !== null)
+            clearInterval(this.handle);
+        this.handle = null;
+    }
+    // -------------------------------------------------------------------------
+    async sweepCampaign(campaignId, c) {
+        if (c.released)
+            return; // over: nothing left to enforce, state stays as it ended
+        const nodes = await this.deps.scheduler.listNodes(campaignId);
+        const now = this.now();
+        c.elapsedMs = now - c.startedAt;
+        // Reconcile observed phases + accumulate per-node RUNNING wall clocks. `cost.wallMs`
+        // counts running intervals only — an awaiting-human interlude neither bills the node
+        // nor counts against its timeout (a gate is quiet by design; sweep granularity bounds
+        // the error at one interval).
+        for (const view of nodes) {
+            const node = this.trackNode(c, view.nodeId);
+            if (view.runId !== undefined)
+                node.runId = view.runId;
+            if (view.phase === 'running') {
+                if (node.runningSince === undefined) {
+                    node.runningSince = now; // (re-)entered running
+                    node.startedAt ??= now;
+                }
+                else {
+                    node.cost.wallMs += now - node.runningSince; // extend the open interval
+                    node.runningSince = now;
+                }
+            }
+            else if (node.runningSince !== undefined) {
+                // Left `running` since the last sweep — close the interval at this observation.
+                node.cost.wallMs += now - node.runningSince;
+                node.runningSince = undefined;
+            }
+            node.phase = view.phase;
+        }
+        // A campaign whose every node is terminal is OVER — a later sweep must never trip its
+        // budget on wall time nobody is spending.
+        if (nodes.length > 0 && nodes.every((n) => n.phase === 'terminal')) {
+            c.released = true;
+            return;
+        }
+        if (c.exhausted !== undefined)
+            return; // exhaustion is enforced exactly once
+        // 1) Per-node timeout (accumulated RUNNING time only; awaiting-human never counts).
+        for (const node of c.nodes.values()) {
+            if (node.phase !== 'running' || node.exclusion !== undefined)
+                continue;
+            if (node.cost.wallMs <= c.policy.nodeTimeoutMs)
+                continue;
+            const reason = `node-timeout: ran ${Math.round(node.cost.wallMs / 1000)}s, per-node timeout is ` +
+                `${Math.round(c.policy.nodeTimeoutMs / 1000)}s (${ENV_NODE_TIMEOUT_SECS})`;
+            await this.excludeOne(campaignId, c, node, 'node-timeout', reason, 'cancelled');
+        }
+        // 2) Campaign-level ceilings — wall-clock first (always armed), then cost (opt-in).
+        if (c.elapsedMs > c.policy.wallClockBudgetMs) {
+            await this.exhaust(campaignId, c, {
+                kind: 'wall-clock',
+                at: new Date(now).toISOString(),
+                spent: c.elapsedMs,
+                budget: c.policy.wallClockBudgetMs,
+                policyApplied: c.policy.killPolicy,
+            });
+            return;
+        }
+        const totalCostUsd = this.totalCostUsd(c);
+        if (c.policy.maxCostUsd !== undefined &&
+            totalCostUsd !== undefined &&
+            totalCostUsd > c.policy.maxCostUsd) {
+            await this.exhaust(campaignId, c, {
+                kind: 'cost',
+                at: new Date(now).toISOString(),
+                spent: totalCostUsd,
+                budget: c.policy.maxCostUsd,
+                policyApplied: c.policy.killPolicy,
+            });
+        }
+    }
+    /**
+     * Abort everything the budget no longer covers. Every touched node gets an
+     * excluded-with-reason record; one campaignBudgetExceeded frame + one
+     * campaignNodeExcluded frame per node ride the /ws fan-out; the warn log names them all.
+     */
+    async exhaust(campaignId, c, exhaustion) {
+        c.exhausted = exhaustion;
+        const kind = exhaustion.kind === 'wall-clock' ? 'campaign-budget' : 'cost-budget';
+        const ceiling = exhaustion.kind === 'wall-clock'
+            ? `wall-clock budget ${Math.round(exhaustion.budget / 1000)}s exceeded ` +
+                `(elapsed ${Math.round(exhaustion.spent / 1000)}s)`
+            : `cost budget $${exhaustion.budget} exceeded (spent $${exhaustion.spent.toFixed(2)})`;
+        const touched = [];
+        for (const node of c.nodes.values()) {
+            if (node.phase === 'terminal' || node.exclusion !== undefined)
+                continue;
+            if (node.phase === 'pending') {
+                await this.excludeOne(campaignId, c, node, kind, `${ceiling}; node never launched`, 'excluded');
+                touched.push(node.nodeId);
+            }
+            else if (c.policy.killPolicy === 'kill-running') {
+                await this.excludeOne(campaignId, c, node, kind, `${ceiling}; in-flight node killed`, 'cancelled');
+                touched.push(node.nodeId);
+            }
+            else {
+                // abandon-running: the node may finish, but it is on record as budget-breached and
+                // nothing new launches after it. Recorded + broadcast — never silent.
+                await this.excludeOne(campaignId, c, node, kind, `${ceiling}; in-flight node abandoned to finish (abandon-running)`, 'abandoned');
+                touched.push(node.nodeId);
+            }
+        }
+        this.deps.broadcast({
+            type: 'campaignBudgetExceeded',
+            campaign: campaignId,
+            kind: exhaustion.kind,
+            budget: exhaustion.budget,
+            spent: exhaustion.spent,
+            policyApplied: exhaustion.policyApplied,
+            nodes: touched,
+        });
+        this.log(`[campaign-supervision] campaign ${campaignId}: ${ceiling} — policy ` +
+            `${exhaustion.policyApplied} applied to ${touched.length} node(s): ` +
+            `${touched.join(', ') || '(none left to touch)'}`);
+    }
+    async excludeOne(campaignId, c, node, kind, reason, applied) {
+        node.exclusion = { kind, reason, at: new Date(this.now()).toISOString(), applied };
+        if (applied === 'cancelled') {
+            await this.deps.scheduler.cancelNode(campaignId, node.nodeId, node.runId, reason);
+        }
+        else if (applied === 'excluded') {
+            await this.deps.scheduler.excludeNode(campaignId, node.nodeId, reason);
+        }
+        this.deps.broadcast({
+            type: 'campaignNodeExcluded',
+            campaign: campaignId,
+            node: node.nodeId,
+            kind,
+            reason,
+            applied,
+        });
+        this.log(`[campaign-supervision] campaign ${campaignId} node ${node.nodeId}: ${applied} — ${reason}`);
+    }
+    trackNode(c, nodeId) {
+        let node = c.nodes.get(nodeId);
+        if (node === undefined) {
+            node = { nodeId, phase: 'pending', cost: { wallMs: 0 } };
+            c.nodes.set(nodeId, node);
+        }
+        return node;
+    }
+    totalCostUsd(c) {
+        let total;
+        for (const node of c.nodes.values()) {
+            if (node.cost.usd !== undefined)
+                total = (total ?? 0) + node.cost.usd;
+        }
+        return total;
+    }
+}
+// ---------------------------------------------------------------------------
+// Evidence: the campaign-supervision report artifact
+// ---------------------------------------------------------------------------
+/** Filename of the supervision evidence artifact inside a campaign's evidence dir. */
+export const SUPERVISION_REPORT_FILENAME = 'campaign-supervision.json';
+/** Build the evidence report from live supervision state. */
+export function buildSupervisionReport(state) {
+    let wallMs = 0;
+    let inputTokens;
+    let outputTokens;
+    for (const n of state.nodes) {
+        wallMs += n.cost.wallMs;
+        if (n.cost.inputTokens !== undefined)
+            inputTokens = (inputTokens ?? 0) + n.cost.inputTokens;
+        if (n.cost.outputTokens !== undefined)
+            outputTokens = (outputTokens ?? 0) + n.cost.outputTokens;
+    }
+    const report = {
+        report: 'campaign-supervision',
+        version: 1,
+        campaign_id: state.campaignId,
+        generated_at: new Date().toISOString(),
+        policy: {
+            wall_clock_budget_secs: Math.round(state.policy.wallClockBudgetMs / 1000),
+            node_timeout_secs: Math.round(state.policy.nodeTimeoutMs / 1000),
+            unit_timeout_pin_secs: state.policy.unitTimeoutSecs,
+            max_nodes: state.policy.maxNodes,
+            ...(state.policy.maxCostUsd !== undefined ? { max_cost_usd: state.policy.maxCostUsd } : {}),
+            kill_policy: state.policy.killPolicy,
+        },
+        started_at: new Date(state.startedAt).toISOString(),
+        elapsed_ms: state.elapsedMs,
+        budget: state.exhausted !== undefined
+            ? {
+                exhausted: true,
+                kind: state.exhausted.kind,
+                at: state.exhausted.at,
+                policy_applied: state.exhausted.policyApplied,
+            }
+            : { exhausted: false },
+        totals: {
+            wall_ms: wallMs,
+            ...(state.totalCostUsd !== undefined ? { cost_usd: state.totalCostUsd } : {}),
+            ...(inputTokens !== undefined ? { input_tokens: inputTokens } : {}),
+            ...(outputTokens !== undefined ? { output_tokens: outputTokens } : {}),
+        },
+        nodes: state.nodes.map((n) => ({
+            node_id: n.nodeId,
+            phase: n.phase,
+            ...(n.runId !== undefined ? { run_id: n.runId } : {}),
+            cost: {
+                wall_ms: n.cost.wallMs,
+                ...(n.cost.usd !== undefined ? { usd: n.cost.usd } : {}),
+                ...(n.cost.inputTokens !== undefined ? { input_tokens: n.cost.inputTokens } : {}),
+                ...(n.cost.outputTokens !== undefined ? { output_tokens: n.cost.outputTokens } : {}),
+            },
+            ...(n.exclusion !== undefined
+                ? {
+                    excluded: {
+                        kind: n.exclusion.kind,
+                        reason: n.exclusion.reason,
+                        at: n.exclusion.at,
+                        applied: n.exclusion.applied,
+                    },
+                }
+                : {}),
+        })),
+    };
+    return report;
+}
+/**
+ * Write the report into a campaign's evidence directory (caller resolves the dir — the
+ * QE pipeline owns evidence placement; crew never writes ledger DOMAIN records, and this
+ * is an artifact file, not a runs/verdicts row). Returns the absolute path written.
+ */
+export async function writeSupervisionReport(evidenceDir, report) {
+    const path = join(evidenceDir, SUPERVISION_REPORT_FILENAME);
+    await writeFile(path, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+    return path;
+}
+//# sourceMappingURL=supervision.js.map

package/dist/campaign/supervision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervision.js","sourceRoot":"","sources":["../../src/campaign/supervision.ts"],"names":[],"mappings":"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"}

package/dist/campaigns/plan.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Scenario → CampaignNode mapping (TH-9; DES-CAMPAIGN-001 §8).
+ *
+ * `POST /campaigns` accepts a batch of SCENARIOS (the qe-campaign vocabulary: garden's
+ * campaign-recon rungs, or any caller's batch of checks) and this module maps them onto the
+ * engine's `CampaignDef` — nodes, `on_success`/`on_terminal` edges, and one composed
+ * single-phase workflow per deterministic scenario. Pure data-in/data-out: no engine handle,
+ * no I/O, so every rule below is unit-testable without spawning a Core.
+ *
+ * ## The two scenario shapes, and where the work actually lives
+ *
+ *  - **`tool` (deterministic)** — the scenario is a spec FILE (garden's runner spec, a script,
+ *    any argv-runnable check) and the node's workflow is one Tool-executor phase running that
+ *    argv verbatim: no council, no LLM, near-zero cost. The engine's Tool path (`run_tool_cmd`)
+ *    spawns the command directly.
+ *  - **`agent` (exploratory / authoring)** — a governed agent run over a problem statement;
+ *    seats are spent only where judgment is the work (test-R9).
+ *
+ * ## The 1022-byte rule (load-bearing, enforced here)
+ *
+ * PTY worker prompts longer than 1022 bytes are SILENTLY DISCARDED by the canonical line
+ * discipline — the worker waits on input that never arrives and the unit burns its full
+ * timeout (the S8 campaign finding; memory: "PTY canonical line limit"). The mapping
+ * therefore refuses, loudly and per-token, anything that smells like a scenario BODY inlined
+ * where a FILE PATH belongs: every Tool argv token and every agent problem statement must be
+ * a single line of at most {@link MAX_INLINE_BYTES} bytes. The fix is always the same and the
+ * error says it: persist the content as a file and pass its path.
+ */
+import type { CampaignDef, LaunchCampaignBody, WorkflowDef } from '../core/types.js';
+/**
+ * Byte ceiling for a single inline string handed to a node (a Tool argv token, an agent
+ * problem). 1022 is the PTY canonical-line limit — the longest line a worker's stdin
+ * accepts before the kernel silently discards it. Tool argv does not itself traverse a PTY,
+ * but the ceiling is enforced uniformly because the failure it guards against is the same
+ * SHAPE either way: scenario bodies belong in files, and a token this long is a body.
+ */
+export declare const MAX_INLINE_BYTES = 1022;
+/** Composed node workflows carry this prefix — the adapter keeps them OUT of the workflow
+ *  catalog (`listWorkflows`) while still persisting them to the overlay dir so a fresh-process
+ *  `resumeCampaign` can re-dispatch pending nodes by workflow id. */
+export declare const CAMPAIGN_WORKFLOW_PREFIX = "campaign-";
+/** The composed workflow id for one deterministic scenario node. */
+export declare function scenarioWorkflowId(campaignId: string, scenarioId: string): string;
+/** A built campaign: the engine def plus the per-node Tool workflows the adapter must arm
+ *  (hot-register + overlay-persist) BEFORE the def launches. */
+export interface BuiltCampaign {
+    def: CampaignDef;
+    workflows: WorkflowDef[];
+}
+/**
+ * Map a `POST /campaigns` body onto the engine's `CampaignDef` + the per-node workflows to arm.
+ *
+ * Throws a plain `Error` (the route answers 400 with the message) on: a malformed campaign or
+ * scenario id, a duplicate scenario id, a scenario with neither/both of `tool`/`agent`, an
+ * empty argv, an inline-rule break ({@link assertInline}), an unknown/self/duplicate dep, or an
+ * `agent.workflow` that is itself a composed campaign workflow. Cycles are LEFT to the engine's
+ * own launch validation — one authority for graph shape, and its reject arrives before anything
+ * persists.
+ *
+ * `defaultClis` is the parsed council roster used for every node that does not carry its own —
+ * Tool nodes never convene it (the phase bypasses the council), agent nodes do.
+ */
+export declare function buildCampaign(body: LaunchCampaignBody, defaultClis: unknown[]): BuiltCampaign;
+//# sourceMappingURL=plan.d.ts.map

package/dist/campaigns/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../src/campaigns/plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EACV,WAAW,EAIX,kBAAkB,EAElB,WAAW,EACZ,MAAM,kBAAkB,CAAC;AAE1B;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,OAAO,CAAC;AASrC;;qEAEqE;AACrE,eAAO,MAAM,wBAAwB,cAAc,CAAC;AAEpD,oEAAoE;AACpE,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAEjF;AAED;gEACgE;AAChE,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,WAAW,CAAC;IACjB,SAAS,EAAE,WAAW,EAAE,CAAC;CAC1B;AAiDD;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,kBAAkB,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,aAAa,CAwD7F"}