@juzser/blacksmith 0.1.0 → 0.2.0

package/factory/orchestrator/dist/harness.js

@@ -0,0 +1,516 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { loadBudgetPolicy } from './budgets.js';
+import { SmithError } from './errors.js';
+import { AGENTS_DIR, HARNESS_POLICY_PATH, REPO_ROOT } from './paths.js';
+import { loadGuardrailPolicy } from './policy.js';
+import { loadTaxonomy } from './taxonomy.js';
+/**
+ * The worker harness port: *how* a turn runs, named at last.
+ *
+ * Every worker turn this factory has ever dispatched ran under one harness —
+ * Claude Code's `Agent` tool — and nothing anywhere says so. It is true by
+ * accident of deployment: the orchestrator is itself a Claude Code session, so
+ * the only thing it can spawn is another one. `dispatch_decision` records the
+ * role, the provider, the model tier and the model (P9-23), which is to say it
+ * records *who answered* and with *what weight*, and never *what ran the
+ * turn*. The two are independent axes and the factory has been folding them
+ * into one:
+ *
+ *   - **provider** — taxonomy.yml `provider: [claude, codex, deepseek]` — is
+ *     the vendor whose model produced the words.
+ *   - **harness** — this module — is the program that held the session: gave
+ *     the agent its tools, its working directory, its turn limit.
+ *
+ * `claude-code` + `claude` was the only pair that existed when this port was
+ * written. `codex-cli` + `codex` and `claude-cli` + `claude` are the pairs
+ * that make the distinction load-bearing, and they are why the second and
+ * third harnesses are config entries and an invocation shape, not a rewrite
+ * of dispatch.
+ *
+ * ## This module renders an invocation. It never runs one.
+ *
+ * Architecture §18 rule 3 — "nothing that observes may dispatch". `smith` is
+ * an observer: it reads logs, folds them, and prints. If `smith harness plan`
+ * spawned the process it describes, the CLI would close its own loop, and
+ * every check that reads a `dispatch_decision` as evidence that a separate
+ * session ran would be reading evidence `smith` produced about itself.
+ *
+ * So `planWorkerTurn()` returns a `WorkerInvocation` — a description, in JSON,
+ * of a process someone else starts. `smith-run` (src/run-cli.ts) is that
+ * someone else for a `cli` invocation: a separate executable that spawns the
+ * program a `WorkerInvocation` describes and prints what happened, and opens
+ * neither the event log nor the database, because starting a program and
+ * observing what a session did are different jobs and this factory keeps
+ * them in different binaries. The orchestrator session still writes the
+ * event that records the turn — `smith-run` running one is not that turn
+ * closing its own loop, any more than `codex` or `claude` running one is.
+ *
+ * ## The shipped policy lives in factory/policies/harness.yml
+ *
+ * It used to live here, in code, as a single frozen `HarnessConfig` this
+ * module exported directly — the honest reading of a factory with exactly
+ * one harness. That stopped being honest the day a second and third harness
+ * needed declaring: a `BUILT_IN_HARNESS_POLICY` object and a shipped YAML
+ * file would have said the same thing twice, in two languages, and the copy
+ * that goes stale is never the one someone is looking at. So the code copy is
+ * gone; `HARNESS_POLICY_PATH` (paths.ts) names the file that answers when
+ * `--policy` is not given, and `source: 'default'` on the result says which
+ * one that was.
+ *
+ * `--policy <file>` still overrides it, the same shape `stack show` uses.
+ * paths.test.ts holds `factory/policies/` and `paths.ts` to each other in
+ * both directions — a constant with no file on disk fails the build, and a
+ * policy file with no constant does too. `harness.yml` and
+ * `HARNESS_POLICY_PATH` had to land together for that reason.
+ *
+ * ## A cli harness is outside the trust boundary; a judge gets no worktree
+ *
+ * `providers/types.ts` states the rule for external judge transports: they are
+ * handed nothing but `prompt` — "no worktree paths, credentials beyond its own
+ * key, or anything callable". A `cli` harness is the same kind of thing one
+ * step over: a process this factory starts, on the far side of its own memory,
+ * holding whatever the command line hands it. So the same boundary applies,
+ * and `planWorkerTurn()` refuses to render a `cli` invocation that would put a
+ * worktree path in a judge role's hands (§18 rule 5, "Judges read; they never
+ * gain write access") — *unless* the harness itself declares `judge_args`:
+ * arguments that put the program into a mode where it cannot write, enforced
+ * by the OS or the tool itself rather than by this factory (codex's
+ * `-s read-only`, claude's `--disallowedTools Write,Edit,...`). That is not a
+ * weaker promise than the in-process path's sandbox lease — it is a
+ * differently-shaped one. An in-process judge runs under guard.sh with a
+ * Bash tool in hand, and the lease is what stops it from writing; a cli judge
+ * with `judge_args` set never has the ability to write at all, which a lease
+ * revocation cannot improve on. Rule 6's fingerprint-before-and-after still
+ * runs either way, because a read-only flag is what the harness promises, not
+ * what this factory has watched happen. An empty `judge_args` means the
+ * harness makes no such promise, and the refusal stands as before.
+ *
+ * `schema_args` is a smaller instance of the same shape: arguments appended
+ * only when the request resolved a schema, so a turn that validates nothing
+ * renders without them and a harness never carries an unconditional
+ * `--output-schema` a schema-less turn cannot fill in.
+ *
+ * An `in-process` harness is inside the boundary: a reviewer subagent does
+ * read the worktree, under a lease `smith sandbox open` holds for exactly as
+ * long as the verdict takes. The invocation says so — `sandboxRequired` is the
+ * obligation, stated where the caller will see it rather than left to the
+ * playbook to remember.
+ *
+ * Which roles are judges is not a list this file keeps. It is
+ * guardrails.yml's `judge_sandbox.roles` and `role_write_scopes.scopes`, read
+ * through policy.ts, which already refuses a role declared as both. A second
+ * hand-written copy here would be a copy that drifts, and the direction it
+ * would drift in is a judge quietly reclassified as a worker.
+ *
+ * ## Env is an allowlist of names. Values never pass through here.
+ *
+ * A harness that shells out needs credentials, and a rendered invocation is
+ * printed as JSON to a terminal and into logs. So the invocation carries the
+ * *names* a harness may read from the environment and never their values: the
+ * runner applies the allowlist against its own `process.env`. Naming a path
+ * and never a value is the same rule every artifact in this factory writes
+ * under.
+ */
+export class HarnessError extends SmithError {
+}
+/** The policy shape this module parses. Bumped when the YAML shape changes. */
+export const HARNESS_POLICY_VERSION = 2;
+const MODEL_TIERS = ['frontier', 'mid', 'small'];
+const OUTPUT_MODES = ['text', 'codex-json', 'claude-json'];
+/**
+ * What a rendered invocation is allowed to interpolate. Closed on purpose: a
+ * typo'd `{worktre}` in an args template would otherwise reach the runner as a
+ * literal argument, and a harness would start in the wrong directory rather
+ * than fail to start.
+ */
+const PLACEHOLDERS = ['prompt_file', 'worktree', 'role', 'task', 'model', 'schema_file'];
+const PLACEHOLDER_RE = /\{([a-z_]+)\}/g;
+/** Per-harness output-size cap when the policy declares none: 2 MiB. */
+export const HARNESS_DEFAULT_MAX_OUTPUT_BYTES = 2 * 1024 * 1024;
+function invalid(message, details) {
+    return new HarnessError('harness.invalid-policy', message, details);
+}
+function requireStringArray(raw, key) {
+    if (raw === undefined || raw === null)
+        return [];
+    if (!Array.isArray(raw) || raw.some((v) => typeof v !== 'string')) {
+        throw invalid(`harness policy ${key} is not a list of strings.`);
+    }
+    return raw;
+}
+/** Every placeholder an args template names, in order of appearance. */
+function placeholdersIn(text) {
+    return [...text.matchAll(PLACEHOLDER_RE)].map((m) => m[1]);
+}
+function checkPlaceholders(args, key, name) {
+    for (const arg of args) {
+        for (const found of placeholdersIn(arg)) {
+            if (!PLACEHOLDERS.includes(found)) {
+                throw invalid(`harness policy ${key} names {${found}}, which no invocation substitutes. Known placeholders: ${PLACEHOLDERS.map((p) => `{${p}}`).join(', ')}.`, { harness: name, placeholder: found });
+            }
+        }
+    }
+}
+function parseOutput(raw, key, name) {
+    if (raw === undefined || raw === null)
+        return 'text';
+    if (typeof raw !== 'string' || !OUTPUT_MODES.includes(raw)) {
+        throw invalid(`harness policy ${key} has output "${String(raw)}"; it is one of ${OUTPUT_MODES.join(', ')}.`, { harness: name });
+    }
+    return raw;
+}
+function parseModels(raw, key, name) {
+    if (raw === undefined || raw === null)
+        return {};
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw invalid(`harness policy ${key} is not a mapping of tier to model id.`, { harness: name });
+    }
+    const models = {};
+    for (const [tier, value] of Object.entries(raw)) {
+        if (!MODEL_TIERS.includes(tier)) {
+            throw invalid(`harness policy ${key} names tier "${tier}"; it is one of ${MODEL_TIERS.join(', ')}.`, { harness: name, tier });
+        }
+        if (typeof value !== 'string' || value === '') {
+            throw invalid(`harness policy ${key}.${tier} is not a model id.`, { harness: name, tier });
+        }
+        models[tier] = value;
+    }
+    return models;
+}
+function parsePositiveIntOrNull(raw, key, name) {
+    if (raw === undefined || raw === null)
+        return null;
+    if (typeof raw !== 'number' || !Number.isFinite(raw) || raw <= 0) {
+        throw invalid(`harness policy ${key} must be a positive number; got ${JSON.stringify(raw)}.`, {
+            harness: name,
+        });
+    }
+    return raw;
+}
+export function parseHarnessPolicy(yamlText) {
+    const doc = (parseYaml(yamlText) ?? {});
+    if (typeof doc !== 'object' || doc === null || Array.isArray(doc)) {
+        throw invalid('harness policy is not a mapping.');
+    }
+    const version = doc.version ?? HARNESS_POLICY_VERSION;
+    if (typeof version !== 'number' || !Number.isInteger(version)) {
+        throw invalid('harness policy `version` is not an integer.');
+    }
+    const rawHarnesses = doc.harnesses;
+    if (!Array.isArray(rawHarnesses) || rawHarnesses.length === 0) {
+        throw invalid('harness policy declares no `harnesses`. A file that names none says less than shipping no file at all, which is why the shipped policy is what answers when no --policy is given.');
+    }
+    const harnesses = [];
+    for (const [index, entry] of rawHarnesses.entries()) {
+        const key = `harnesses[${index}]`;
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+            throw invalid(`harness policy ${key} is not a mapping.`);
+        }
+        const item = entry;
+        const name = item.name;
+        if (typeof name !== 'string' || name === '') {
+            throw invalid(`harness policy ${key} is missing \`name\`.`);
+        }
+        if (harnesses.some((h) => h.name === name)) {
+            throw invalid(`harness policy declares "${name}" twice.`, { harness: name });
+        }
+        const kind = item.kind;
+        if (kind !== 'in-process' && kind !== 'cli') {
+            throw invalid(`harness policy ${key} has kind "${String(kind)}"; it is one of in-process, cli.`, { harness: name });
+        }
+        const args = requireStringArray(item.args, `${key}.args`);
+        const workerArgs = requireStringArray(item.worker_args, `${key}.worker_args`);
+        const judgeArgs = requireStringArray(item.judge_args, `${key}.judge_args`);
+        const schemaArgs = requireStringArray(item.schema_args, `${key}.schema_args`);
+        const command = item.command ?? null;
+        if (kind === 'cli') {
+            if (typeof command !== 'string' || command === '') {
+                throw invalid(`harness policy ${key} is a cli harness with no \`command\`, so nothing would start.`, { harness: name });
+            }
+        }
+        else if (command !== null) {
+            // An in-process harness runs inside the caller's session. A command here
+            // would be a line nothing executes, read by the next person as a
+            // promise the port does not keep.
+            throw invalid(`harness policy ${key} is in-process but names a \`command\`; an in-process harness starts no program.`, { harness: name });
+        }
+        checkPlaceholders(args, `${key}.args`, name);
+        checkPlaceholders(workerArgs, `${key}.worker_args`, name);
+        checkPlaceholders(judgeArgs, `${key}.judge_args`, name);
+        checkPlaceholders(schemaArgs, `${key}.schema_args`, name);
+        harnesses.push({
+            name,
+            kind,
+            roles: requireStringArray(item.roles, `${key}.roles`),
+            command: kind === 'cli' ? command : null,
+            args,
+            workerArgs,
+            judgeArgs,
+            schemaArgs,
+            envAllowlist: requireStringArray(item.env, `${key}.env`),
+            output: parseOutput(item.output, `${key}.output`, name),
+            models: parseModels(item.models, `${key}.models`, name),
+            timeoutMs: parsePositiveIntOrNull(item.timeout_ms, `${key}.timeout_ms`, name),
+            maxOutputBytes: parsePositiveIntOrNull(item.max_output_bytes, `${key}.max_output_bytes`, name),
+        });
+    }
+    const declaredDefault = doc.default;
+    const defaultHarness = declaredDefault === undefined || declaredDefault === null
+        ? harnesses[0].name
+        : declaredDefault;
+    if (typeof defaultHarness !== 'string' || defaultHarness === '') {
+        throw invalid('harness policy `default` is not a harness name.');
+    }
+    if (!harnesses.some((h) => h.name === defaultHarness)) {
+        throw invalid(`harness policy names "${defaultHarness}" as the default, and declares no harness by that name.`, { harness: defaultHarness });
+    }
+    return { version, defaultHarness, harnesses, source: 'file' };
+}
+/**
+ * The shipped policy (factory/policies/harness.yml), or the file the caller
+ * named.
+ *
+ * No caching: every call re-reads and re-parses, the same choice
+ * loadBudgetPolicy makes, so an operator editing `--policy <file>` between
+ * two `smith harness plan` calls in the same process sees the edit.
+ */
+export function loadHarnessPolicy(filePath) {
+    if (filePath === undefined) {
+        return { ...parseHarnessPolicy(readFileSync(HARNESS_POLICY_PATH, 'utf8')), source: 'default' };
+    }
+    if (!existsSync(filePath)) {
+        throw new HarnessError('harness.policy-not-found', `No harness policy at ${filePath}. Omit --policy to use the shipped one.`, { filePath });
+    }
+    return parseHarnessPolicy(readFileSync(filePath, 'utf8'));
+}
+export function roleAccess(role, guardrails = loadGuardrailPolicy()) {
+    if (guardrails.judgeSandbox.roles.includes(role))
+        return 'judge';
+    if (guardrails.roleWriteScopes.some((s) => s.role === role))
+        return 'write-scoped';
+    return 'worker';
+}
+/** Where a role's prompt template lives, and whether it is there. */
+function templateFor(role, agentsDir) {
+    const file = path.join(agentsDir, `${role}.md`);
+    return { file, exists: existsSync(file) };
+}
+function serves(harness, role) {
+    return harness.roles.length === 0 || harness.roles.includes(role);
+}
+const TIER_BY_TEMPLATE_MODEL = Object.freeze({
+    opus: 'frontier',
+    sonnet: 'mid',
+    haiku: 'small',
+});
+function modelLineOf(markdown) {
+    const line = markdown.split('\n').find((l) => l.startsWith('model:'));
+    if (line === undefined)
+        return null;
+    const value = line.slice('model:'.length).trim();
+    return value === '' ? null : value;
+}
+/**
+ * Tier, when the request names none: read off the role template's own
+ * frontmatter `model:` line and fold the model id it names (`opus`, `sonnet`,
+ * `haiku`) through the tier taxonomy.yml's `model_tier` already gives that
+ * vendor's weight class. PR 2 moves role templates to `factory/agents/` with
+ * a `tier:` field of their own, which retires this mapping in favor of
+ * reading it directly — this is the bridge until then, not a second source of
+ * truth meant to outlive it.
+ */
+function tierFromTemplate(templateFile) {
+    if (!existsSync(templateFile))
+        return null;
+    const model = modelLineOf(readFileSync(templateFile, 'utf8'));
+    return model === null ? null : (TIER_BY_TEMPLATE_MODEL[model] ?? null);
+}
+const SCHEMA_DIR = path.join(REPO_ROOT, 'factory', 'specs', 'schema');
+const SCHEMA_SUFFIX = '.schema.json';
+/** `factory/specs/schema/<name>.schema.json`, checked against what actually ships. */
+function resolveSchema(name, harnessName) {
+    if (name === undefined || name === null || name === '')
+        return null;
+    const file = path.join(SCHEMA_DIR, `${name}${SCHEMA_SUFFIX}`);
+    if (!existsSync(file)) {
+        const known = readdirSync(SCHEMA_DIR)
+            .filter((f) => f.endsWith(SCHEMA_SUFFIX))
+            .map((f) => f.slice(0, -SCHEMA_SUFFIX.length))
+            .sort();
+        throw new HarnessError('harness.unknown-schema', `Harness "${harnessName}" was asked to validate against schema "${name}", and factory/specs/schema/ ships no ${name}${SCHEMA_SUFFIX}. It ships: ${known.join(', ')}.`, { harness: harnessName, schema: name, known });
+    }
+    return { name, file };
+}
+function capTokensFor(role, access, budgets) {
+    // Only these three named roles carry a cap in budgets.yml today — every
+    // other role (security-reviewer, merger, tester, uiux, planner, scribe)
+    // has none, and null says so rather than inventing a number nobody set.
+    if (access === 'judge')
+        return budgets.task.judges.capTokens;
+    if (role === 'coder')
+        return budgets.task.coder.capTokens;
+    if (role === 'researcher')
+        return budgets.task.researcher.capTokens;
+    return null;
+}
+function substitute(template, values, harness) {
+    return template.replace(PLACEHOLDER_RE, (_match, token) => {
+        const value = values[token];
+        if (value === undefined || value === null || value === '') {
+            const hint = token === 'schema_file' ? ' — pass --schema <name>' : '';
+            throw new HarnessError('harness.missing-substitution', `Harness "${harness}" interpolates {${token}}, and this request carries no ${token.replace('_', ' ')}${hint}.`, { harness, placeholder: token });
+        }
+        return value;
+    });
+}
+/**
+ * Describe the process that would run this turn. Start nothing.
+ *
+ * Every refusal below is a fact the caller could not have checked cheaply:
+ * whether the role exists in the taxonomy, whether a template ships for it,
+ * whether the harness serves it, and whether handing it a worktree would cross
+ * the judge boundary. A runner that skips this call is not faster — it is
+ * making the same four decisions with none of them written down.
+ */
+export function planWorkerTurn(request, options = {}) {
+    const policy = options.policy ?? loadHarnessPolicy();
+    const guardrails = options.guardrails ?? loadGuardrailPolicy();
+    const taxonomy = options.taxonomy ?? loadTaxonomy();
+    const agentsDir = options.agentsDir ?? AGENTS_DIR;
+    const { role, taskId } = request;
+    const agentRoles = taxonomy.dimensions.agent ?? [];
+    if (!agentRoles.includes(role)) {
+        throw new HarnessError('harness.unknown-role', `"${role}" is not a taxonomy \`agent\` value, so no dispatch about it could be written even if the turn ran.`, { role });
+    }
+    if (taskId === undefined || taskId === '') {
+        throw new HarnessError('harness.missing-task', 'A worker turn is about a task; the invocation carries its id so the dispatch the caller writes can name the same one.', { role });
+    }
+    if (request.tier !== undefined && !MODEL_TIERS.includes(request.tier)) {
+        throw new HarnessError('harness.unknown-tier', `"${request.tier}" is not a model tier. It is one of ${MODEL_TIERS.join(', ')}.`, { tier: request.tier });
+    }
+    if (request.promptFile === undefined || request.promptFile === '') {
+        throw new HarnessError('harness.missing-prompt', 'A worker turn needs a prompt file. This port renders invocations, not prompts — write the prompt first (`smith prompt record`), then plan the turn that carries it.', { role });
+    }
+    const name = request.harness ?? policy.defaultHarness;
+    const harness = policy.harnesses.find((h) => h.name === name);
+    if (harness === undefined) {
+        throw new HarnessError('harness.unknown', `No harness named "${name}". This policy declares: ${policy.harnesses.map((h) => h.name).join(', ')}.`, { harness: name, declared: policy.harnesses.map((h) => h.name) });
+    }
+    if (!serves(harness, role)) {
+        throw new HarnessError('harness.role-not-served', `Harness "${harness.name}" serves ${harness.roles.join(', ')}, and not ${role}.`, { harness: harness.name, role });
+    }
+    // A template is required to start an agent under either kind: an in-process
+    // harness reads it directly, and a cli harness's runner prepends its body
+    // to the prompt on stdin (see WorkerInvocation.template). No template, no
+    // agent to start, regardless of which program would have started it.
+    const template = templateFor(role, agentsDir);
+    if (!template.exists) {
+        // D-191's reading, applied to the harness rather than to a grant: a
+        // role with no template reaches no agent. `operator` is the standing
+        // case — taxonomy.yml carries it as a `found_by` for a defect a person
+        // read off the code, and it is never dispatched.
+        throw new HarnessError('harness.no-template', `${role} ships no template at ${path.relative(REPO_ROOT, template.file)}, so no harness has an agent to start.`, { role, template: path.relative(REPO_ROOT, template.file) });
+    }
+    const templateRelative = path.relative(REPO_ROOT, template.file);
+    const worktree = request.worktree ?? null;
+    const access = roleAccess(role, guardrails);
+    const base = {
+        harness: harness.name,
+        role,
+        taskId,
+        access,
+        promptFile: request.promptFile,
+        worktree,
+        sandboxRequired: access === 'judge' && worktree !== null,
+    };
+    if (harness.kind === 'in-process') {
+        return {
+            ...base,
+            kind: 'in-process',
+            subagentType: role,
+            template: templateRelative,
+        };
+    }
+    if (access === 'judge' && worktree !== null && harness.judgeArgs.length === 0) {
+        // §18 rule 5, one step out from providers/types.ts. An external process
+        // holding a worktree path holds write access to it; no lease this side of
+        // the boundary can take that back — unless the harness's own policy entry
+        // declares judge_args that make the program read-only. See the header.
+        throw new HarnessError('harness.judge-worktree', `Harness "${harness.name}" runs a separate program, and ${role} is a judge role. A judge outside this process gets the prompt and nothing else — a worktree path it holds is write access no sandbox lease can revoke (architecture §18 rule 5). ${harness.name} could still serve ${role} a worktree if its policy entry were to declare judge_args that make the program read-only.`, { harness: harness.name, role });
+    }
+    const tier = request.tier ?? tierFromTemplate(template.file);
+    const model = tier !== null ? (harness.models[tier] ?? null) : null;
+    const schema = resolveSchema(request.schema, harness.name);
+    const values = {
+        prompt_file: request.promptFile,
+        worktree,
+        role,
+        task: taskId,
+        model,
+        schema_file: schema?.file ?? null,
+    };
+    const roleArgs = access === 'judge' ? harness.judgeArgs : harness.workerArgs;
+    const rawArgs = [...harness.args, ...roleArgs, ...(schema !== null ? harness.schemaArgs : [])];
+    const args = rawArgs.map((arg) => substitute(arg, values, harness.name));
+    const budgets = options.budgets ?? loadBudgetPolicy();
+    const budget = {
+        timeout_ms: harness.timeoutMs,
+        max_output_bytes: harness.maxOutputBytes ?? HARNESS_DEFAULT_MAX_OUTPUT_BYTES,
+        cap_tokens: capTokensFor(role, access, budgets),
+    };
+    return {
+        ...base,
+        kind: 'cli',
+        command: harness.command,
+        args,
+        cwd: worktree,
+        envAllowlist: harness.envAllowlist,
+        template: templateRelative,
+        output: harness.output,
+        model,
+        tier,
+        schema: schema?.name ?? null,
+        stdin: 'prompt',
+        budget,
+    };
+}
+/**
+ * What `smith harness list` prints: not the policy as written, but the policy
+ * as it resolves. A harness whose `roles` is empty reads as "all" in YAML and
+ * means "every role that ships a template" in practice, and the difference
+ * between those two is the kind of thing an operator finds out at 2am
+ * otherwise.
+ */
+export function summarizeHarnesses(options = {}) {
+    const policy = options.policy ?? loadHarnessPolicy();
+    const taxonomy = options.taxonomy ?? loadTaxonomy();
+    const guardrails = options.guardrails ?? loadGuardrailPolicy();
+    const agentsDir = options.agentsDir ?? AGENTS_DIR;
+    const agentRoles = taxonomy.dimensions.agent ?? [];
+    return {
+        source: policy.source,
+        version: policy.version,
+        defaultHarness: policy.defaultHarness,
+        harnesses: policy.harnesses.map((harness) => ({
+            name: harness.name,
+            kind: harness.kind,
+            isDefault: harness.name === policy.defaultHarness,
+            roles: agentRoles.filter((role) => {
+                if (!serves(harness, role))
+                    return false;
+                if (!templateFor(role, agentsDir).exists)
+                    return false;
+                if (roleAccess(role, guardrails) === 'judge') {
+                    return harness.kind === 'in-process' || harness.judgeArgs.length > 0;
+                }
+                return true;
+            }),
+            command: harness.command,
+            envAllowlist: harness.envAllowlist,
+            output: harness.output,
+            models: harness.models,
+        })),
+    };
+}

package/factory/orchestrator/dist/impact.js

@@ -20,6 +20,12 @@
  *   it is a break, and it is provable. A changed signature is weaker: this
  *   module reads text, not types, so it says `possible` and means it.
  *
+ * A `keeps_exports` promise (task-spec.schema.json) is the declaration that
+ * joins the two halves: the pre-run half trusts it and lets a crossing whose
+ * producer promised the exporting file run in the same wave, and the post-run
+ * half verifies it against the diff, where a removed or re-declared export
+ * under a promise is a broken promise and fails the check.
+ *
  * Holes are reported, never fatal. The scanner has blind spots (a `.vue` file,
  * an unterminated literal), and failing a wave for the scanner's limits would
  * teach operators to reach for the override — which costs more than the check
@@ -46,6 +52,17 @@ function ownersOf(files, tasks) {
     }
     return owner;
 }
+/**
+ * Did the crossing's producer promise to keep the exports of the file the
+ * crossing imports from? A promise is a literal path (plan.ts refuses a
+ * pattern), matched the way `ownersOf` matches a claim to a file so the two
+ * agree on what "this file" means.
+ */
+function promisedBy(crossing, tasks) {
+    const producer = tasks.find((task) => task.task_id === crossing.producer);
+    const promises = producer?.keeps_exports ?? [];
+    return promises.some((promise) => claimCoversPath(promise, crossing.exportedBy));
+}
 export function waveImpact(graph, tasks) {
     // Unreadable files are absent from `modules` but still claimable, and a task
     // that claims one has matched a real file — it is the reading that failed.
@@ -101,7 +118,7 @@ export function waveImpact(graph, tasks) {
             }
         }
     }
-    const orderedCrossings = [...crossings.values()]
+    const orderCrossings = (found) => found
         .map((c) => ({
         producer: c.producer,
         consumer: c.consumer,
@@ -115,6 +132,11 @@ export function waveImpact(graph, tasks) {
         a.consumer.localeCompare(b.consumer) ||
         a.exportedBy.localeCompare(b.exportedBy) ||
         a.importedBy.localeCompare(b.importedBy));
+    // A promise moves the crossing from the blocking set to the promised one;
+    // it does not erase it, because the post-run verifier and the operator both
+    // want to see which crossings the wave is running on trust.
+    const orderedCrossings = orderCrossings([...crossings.values()].filter((c) => !promisedBy(c, tasks)));
+    const orderedPromised = orderCrossings([...crossings.values()].filter((c) => promisedBy(c, tasks)));
     const orderedExposure = [...exposure.values()]
         .map((e) => ({
         producer: e.producer,
@@ -136,14 +158,15 @@ export function waveImpact(graph, tasks) {
         status,
         ok: status !== 'coupled',
         crossings: orderedCrossings,
+        promised: orderedPromised,
         exposure: orderedExposure,
         claimsWithoutFiles,
         unanalyzed,
         unresolved,
-        detail: describeWave(status, orderedCrossings, orderedExposure, unanalyzed.length + unresolved.length),
+        detail: describeWave(status, orderedCrossings, orderedPromised.length, orderedExposure, unanalyzed.length + unresolved.length),
     };
 }
-function describeWave(status, crossings, exposure, holes) {
+function describeWave(status, crossings, promised, exposure, holes) {
     const parts = [];
     if (status === 'coupled') {
         const pairs = new Set(crossings.map((c) => `${c.producer}/${c.consumer}`));
@@ -155,6 +178,9 @@ function describeWave(status, crossings, exposure, holes) {
     else {
         parts.push('No task in this wave imports a symbol another task in this wave exports.');
     }
+    if (promised > 0) {
+        parts.push(`${promised} crossing(s) run on a keeps_exports promise, verified post-run.`);
+    }
     if (exposure.length > 0) {
         parts.push(`${exposure.length} file(s) outside the wave import from claimed files.`);
     }
@@ -187,14 +213,52 @@ export function diffExports(before, after, file) {
 function consumes(names, symbol) {
     return names.includes('*') || names.includes(symbol);
 }
+/**
+ * A promise against the diff of the file it names. A file the diff does not
+ * hold was not touched, so its exports are as they were: kept.
+ */
+function verdictOn(file, diffs) {
+    const diff = diffs.find((entry) => entry.file === file);
+    if (diff === undefined) {
+        return { file, status: 'kept', removed: [], signatureChanged: [], added: [] };
+    }
+    const lists = {
+        removed: [...diff.removed],
+        signatureChanged: [...diff.signatureChanged],
+        added: [...diff.added],
+    };
+    if (diff.unverifiable)
+        return { file, status: 'unverified', ...lists };
+    if (diff.removed.length > 0)
+        return { file, status: 'broken', reason: 'removed', ...lists };
+    if (diff.signatureChanged.length > 0) {
+        return { file, status: 'broken', reason: 'signature-changed', ...lists };
+    }
+    return { file, status: 'kept', ...lists };
+}
+function describePromise(verdict) {
+    const changes = [];
+    if (verdict.removed.length > 0)
+        changes.push(`removed [${verdict.removed.join(', ')}]`);
+    if (verdict.signatureChanged.length > 0) {
+        changes.push(`changed the declaration of [${verdict.signatureChanged.join(', ')}]`);
+    }
+    return `Promise broken: ${verdict.file} ${changes.join(' and ')}.`;
+}
 /**
  * Whose files broke. `claims` is the acting task's own claim list: an importer
  * the task already owns is not a break, because the same task is free to fix
  * it in the same diff — and usually has.
+ *
+ * `keepsExports` is the task's own `keeps_exports` promise, the one the wave
+ * gate ran a crossing on. It is held against the diff regardless of who
+ * imports the file: the importer the promise covered belongs to another task,
+ * whose file this diff cannot see, so "inside the claims" excuses nothing here.
  */
-export function exportImpact(graph, diffs, claims) {
+export function exportImpact(graph, diffs, claims, keepsExports = []) {
     const breaks = [];
     const unverifiable = [];
+    const promises = keepsExports.map((file) => verdictOn(file, diffs));
     for (const diff of diffs) {
         if (diff.unverifiable) {
             unverifiable.push(diff.file);
@@ -243,7 +307,14 @@ export function exportImpact(graph, diffs, claims) {
     }
     if (unverifiable.length > 0)
         parts.push(`Unreadable, so unchecked: ${unverifiable.join(', ')}.`);
-    return { ok: proven === 0, breaks, detail: parts.join(' ') };
+    const broken = promises.filter((verdict) => verdict.status === 'broken');
+    for (const verdict of broken)
+        parts.push(describePromise(verdict));
+    const unverified = promises.filter((verdict) => verdict.status === 'unverified');
+    if (unverified.length > 0) {
+        parts.push(`Promise unverified: ${unverified.map((verdict) => verdict.file).join(', ')}.`);
+    }
+    return { ok: proven === 0 && broken.length === 0, breaks, promises, detail: parts.join(' ') };
 }
 /**
  * The collector half (P9-3): read both sides of each changed file out of git.