@juzser/blacksmith 0.1.1 → 0.2.0

package/factory/orchestrator/dist/harness.js

@@ -1,8 +1,9 @@
-import { existsSync, readFileSync } from 'node:fs';
+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, REPO_ROOT } from './paths.js';
+import { AGENTS_DIR, HARNESS_POLICY_PATH, REPO_ROOT } from './paths.js';
 import { loadGuardrailPolicy } from './policy.js';
 import { loadTaxonomy } from './taxonomy.js';
 /**
@@ -22,10 +23,11 @@ import { loadTaxonomy } from './taxonomy.js';
  *   - **harness** — this module — is the program that held the session: gave
  *     the agent its tools, its working directory, its turn limit.
  *
- * `claude-code` + `claude` is the only pair that exists today. `codex-cli` +
- * `codex` is the pair that makes the distinction load-bearing, and the point
- * of writing the port before that pair exists is that the second harness
- * should be a config entry and an invocation shape, not a rewrite of dispatch.
+ * `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.
  *
@@ -36,26 +38,32 @@ import { loadTaxonomy } from './taxonomy.js';
  * 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. The orchestrator session (or a runner that
- * is not Claude Code at all) reads it and acts. That separation is the whole
- * reason this is a port rather than a spawner.
+ * 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 default policy lives here, in code, on purpose
+ * ## The shipped policy lives in factory/policies/harness.yml
  *
- * There is no `factory/policies/harness.yml`, and this module does not name
- * one. Two reasons, both checkable:
+ * 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.
  *
- *   - Writing a policy file is the operator's decision, not a side effect of
- *     adding a seam. The built-in policy below describes what the factory
- *     already does; it invents no capability.
- *   - 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. A
- *     path constant for a file we are not shipping would be exactly that.
- *
- * An operator who wants a second harness writes a YAML file wherever they like
- * and names it: `--policy <file>`, the same shape `stack show` already uses.
- * Absent that flag the built-in policy answers, which is the honest reading of
- * a factory that has one harness.
+ * `--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
  *
@@ -66,7 +74,23 @@ import { loadTaxonomy } from './taxonomy.js';
  * 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").
+ * 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
@@ -92,40 +116,19 @@ import { loadTaxonomy } from './taxonomy.js';
 export class HarnessError extends SmithError {
 }
 /** The policy shape this module parses. Bumped when the YAML shape changes. */
-export const HARNESS_POLICY_VERSION = 1;
+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'];
+const PLACEHOLDERS = ['prompt_file', 'worktree', 'role', 'task', 'model', 'schema_file'];
 const PLACEHOLDER_RE = /\{([a-z_]+)\}/g;
-/**
- * Today's factory, written down.
- *
- * One harness, serving every role, starting no program — because the Claude
- * Code `Agent` tool is a call inside the orchestrator's own session, not an
- * exec. `roles: []` rather than the fifteen taxonomy values: the constraint
- * that actually binds is whether `.claude/agents/<role>.md` exists, and
- * `planWorkerTurn()` checks that against the directory rather than against a
- * list here that would go stale the next time a role is added.
- */
-export const BUILT_IN_HARNESS_POLICY = Object.freeze({
-    version: HARNESS_POLICY_VERSION,
-    defaultHarness: 'claude-code',
-    harnesses: Object.freeze([
-        Object.freeze({
-            name: 'claude-code',
-            kind: 'in-process',
-            roles: Object.freeze([]),
-            command: null,
-            args: Object.freeze([]),
-            envAllowlist: Object.freeze([]),
-        }),
-    ]),
-    source: 'built-in',
-});
+/** 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);
 }
@@ -141,6 +144,51 @@ function requireStringArray(raw, key) {
 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)) {
@@ -152,7 +200,7 @@ export function parseHarnessPolicy(yamlText) {
     }
     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 built-in policy is what answers when no --policy is given.');
+        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()) {
@@ -173,6 +221,9 @@ export function parseHarnessPolicy(yamlText) {
             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 === '') {
@@ -185,20 +236,24 @@ export function parseHarnessPolicy(yamlText) {
             // 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 });
         }
-        for (const arg of args) {
-            for (const found of placeholdersIn(arg)) {
-                if (!PLACEHOLDERS.includes(found)) {
-                    throw invalid(`harness policy ${key}.args names {${found}}, which no invocation substitutes. Known placeholders: ${PLACEHOLDERS.map((p) => `{${p}}`).join(', ')}.`, { harness: name, placeholder: found });
-                }
-            }
-        }
+        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;
@@ -214,16 +269,19 @@ export function parseHarnessPolicy(yamlText) {
     return { version, defaultHarness, harnesses, source: 'file' };
 }
 /**
- * The built-in policy, or the file the caller named.
+ * The shipped policy (factory/policies/harness.yml), or the file the caller
+ * named.
  *
- * No default path: see the header. An absent `filePath` is not a missing file,
- * it is the statement that this factory runs one harness.
+ * 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 BUILT_IN_HARNESS_POLICY;
+    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 built-in one.`, { 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'));
 }
@@ -242,11 +300,67 @@ function templateFor(role, agentsDir) {
 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 === '') {
-            throw new HarnessError('harness.missing-substitution', `Harness "${harness}" interpolates {${token}}, and this request carries no ${token.replace('_', ' ')}.`, { harness, placeholder: token });
+            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;
     });
@@ -261,7 +375,7 @@ function substitute(template, values, harness) {
  * making the same four decisions with none of them written down.
  */
 export function planWorkerTurn(request, options = {}) {
-    const policy = options.policy ?? BUILT_IN_HARNESS_POLICY;
+    const policy = options.policy ?? loadHarnessPolicy();
     const guardrails = options.guardrails ?? loadGuardrailPolicy();
     const taxonomy = options.taxonomy ?? loadTaxonomy();
     const agentsDir = options.agentsDir ?? AGENTS_DIR;
@@ -273,6 +387,9 @@ export function planWorkerTurn(request, options = {}) {
     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 });
     }
@@ -284,6 +401,19 @@ export function planWorkerTurn(request, options = {}) {
     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 = {
@@ -296,40 +426,54 @@ export function planWorkerTurn(request, options = {}) {
         sandboxRequired: access === 'judge' && worktree !== null,
     };
     if (harness.kind === 'in-process') {
-        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 an in-process harness has no agent to start.`, { role, template: path.relative(REPO_ROOT, template.file) });
-        }
         return {
             ...base,
             kind: 'in-process',
             subagentType: role,
-            template: path.relative(REPO_ROOT, template.file),
+            template: templateRelative,
         };
     }
-    if (access === 'judge' && worktree !== null) {
+    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.
-        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: harness.name, role });
+        // 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: harness.args.map((arg) => substitute(arg, values, harness.name)),
+        args,
         cwd: worktree,
         envAllowlist: harness.envAllowlist,
+        template: templateRelative,
+        output: harness.output,
+        model,
+        tier,
+        schema: schema?.name ?? null,
+        stdin: 'prompt',
+        budget,
     };
 }
 /**
@@ -340,7 +484,7 @@ export function planWorkerTurn(request, options = {}) {
  * otherwise.
  */
 export function summarizeHarnesses(options = {}) {
-    const policy = options.policy ?? BUILT_IN_HARNESS_POLICY;
+    const policy = options.policy ?? loadHarnessPolicy();
     const taxonomy = options.taxonomy ?? loadTaxonomy();
     const guardrails = options.guardrails ?? loadGuardrailPolicy();
     const agentsDir = options.agentsDir ?? AGENTS_DIR;
@@ -356,12 +500,17 @@ export function summarizeHarnesses(options = {}) {
             roles: agentRoles.filter((role) => {
                 if (!serves(harness, role))
                     return false;
-                if (harness.kind === 'in-process')
-                    return templateFor(role, agentsDir).exists;
-                return roleAccess(role, guardrails) !== 'judge';
+                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.

package/factory/orchestrator/dist/paths.js

@@ -196,6 +196,8 @@ export const EFFORT_POLICY_PATH = path.join(REPO_ROOT, 'factory', 'policies', 'e
 export const SENSITIVE_PATHS_POLICY_PATH = path.join(REPO_ROOT, 'factory', 'policies', 'sensitive-paths.yml');
 /** The guard hook's rule data — read by `smith policy check`/`smith policy hook` (policy.ts). */
 export const GUARDRAILS_POLICY_PATH = path.join(REPO_ROOT, 'factory', 'policies', 'guardrails.yml');
+/** Which programs may hold a worker turn, and how to start each one (harness.ts). */
+export const HARNESS_POLICY_PATH = path.join(REPO_ROOT, 'factory', 'policies', 'harness.yml');
 /**
  * The S1-S4 ladder and which levels block a merge (severity.ts).
  *