@juzser/blacksmith 0.2.0 → 0.4.0

package/factory/orchestrator/dist/agentsSync.js

@@ -0,0 +1,178 @@
+/**
+ * `smith agents sync` — set each agent template's `maxTurns:` from the box's
+ * env, or put it back to the committed value.
+ *
+ * A turn cap is per role, never per task: Claude Code reads it from the
+ * template's frontmatter when it spawns the agent, so the only lever is the
+ * template file itself. This rewrites that one line and nothing else. The
+ * edit is local and left uncommitted on purpose — a raised cap on one box is
+ * that box's business, and `--reset` restores what git HEAD says.
+ *
+ * SMITH_MAXTURNS_<ROLE> names the role upper-cased with `-` as `_`
+ * (spec-reviewer → SMITH_MAXTURNS_SPEC_REVIEWER).
+ */
+import { readdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { SmithError } from './errors.js';
+import { GitCommandError, runGit, runGitRaw } from './git.js';
+import { AGENTS_DIR } from './paths.js';
+export class AgentsSyncError extends SmithError {
+}
+export const MAXTURNS_ENV_PREFIX = 'SMITH_MAXTURNS_';
+export function maxTurnsEnvName(role) {
+    return `${MAXTURNS_ENV_PREFIX}${role.toUpperCase().replaceAll('-', '_')}`;
+}
+const MAX_TURNS_LINE = /^maxTurns:[ \t]*(\S*)[ \t]*$/m;
+function listRoles(agentsDir) {
+    return readdirSync(agentsDir)
+        .filter((name) => name.endsWith('.md'))
+        .map((name) => name.slice(0, -'.md'.length))
+        .sort();
+}
+/** The frontmatter block's bounds: the text between the leading `---` lines. */
+function frontmatterBounds(text) {
+    const open = text.match(/^---\r?\n/);
+    if (!open)
+        return null;
+    const start = open[0].length;
+    const close = /^---[ \t]*$/m.exec(text.slice(start));
+    if (!close)
+        return null;
+    return { start, end: start + close.index };
+}
+function findMaxTurns(text, file) {
+    const bounds = frontmatterBounds(text);
+    const block = bounds ? text.slice(bounds.start, bounds.end) : '';
+    const match = bounds ? MAX_TURNS_LINE.exec(block) : null;
+    const raw = match?.[1] ?? '';
+    if (!bounds || !match || !/^[0-9]+$/.test(raw)) {
+        throw new AgentsSyncError('agents.no-max-turns', `${file} has no frontmatter "maxTurns: <integer>" line to rewrite.`, { file });
+    }
+    const valueStart = bounds.start + match.index + match[0].indexOf(raw, 'maxTurns:'.length);
+    return { value: Number(raw), from: valueStart, to: valueStart + raw.length };
+}
+function withMaxTurns(text, site, value) {
+    return `${text.slice(0, site.from)}${value}${text.slice(site.to)}`;
+}
+/**
+ * The template's current `maxTurns:`, read fresh from disk — never cached,
+ * because `smith agents sync` may have rewritten the file since the caller
+ * last looked. Unlike `findMaxTurns`, this never throws: a role with no
+ * template, or a template with no `maxTurns:` line, is "cannot verify" for a
+ * caller like dispatchLint.ts, not a hard failure.
+ */
+export function readTemplateMaxTurns(agentsDir, role) {
+    const file = path.join(agentsDir, `${role}.md`);
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        return findMaxTurns(text, file).value;
+    }
+    catch {
+        return undefined;
+    }
+}
+function positiveInt(name, raw) {
+    const value = /^[0-9]+$/.test(raw) ? Number(raw) : Number.NaN;
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new AgentsSyncError('agents.invalid-env', `${name} must be a positive integer (digits only); got ${JSON.stringify(raw)}.`, { variable: name });
+    }
+    return value;
+}
+function apply(edits, dryRun) {
+    if (!dryRun) {
+        for (const edit of edits)
+            if (edit.change.changed)
+                writeFileSync(edit.file, edit.next);
+    }
+    return edits.map((edit) => edit.change);
+}
+/**
+ * Rewrite `maxTurns:` for every role whose SMITH_MAXTURNS_<ROLE> is set
+ * (non-empty). Every name and value is checked, and every target file read,
+ * before anything is written: one bad entry refuses the whole sync.
+ */
+export function syncAgentMaxTurns(options = {}) {
+    const agentsDir = options.agentsDir ?? AGENTS_DIR;
+    const env = options.env ?? process.env;
+    const dryRun = options.dryRun ?? false;
+    const roles = listRoles(agentsDir);
+    const byEnv = new Map(roles.map((role) => [maxTurnsEnvName(role), role]));
+    const requested = [];
+    for (const name of Object.keys(env).sort()) {
+        if (!name.startsWith(MAXTURNS_ENV_PREFIX))
+            continue;
+        const raw = env[name];
+        if (raw === undefined || raw === '')
+            continue;
+        const role = byEnv.get(name);
+        if (role === undefined) {
+            throw new AgentsSyncError('agents.unknown-role', `${name} names no agent template; valid roles: ${roles.join(', ')}.`, { variable: name, roles });
+        }
+        requested.push({ role, env: name, to: positiveInt(name, raw) });
+    }
+    requested.sort((a, b) => a.role.localeCompare(b.role));
+    const edits = requested.map(({ role, env: name, to }) => {
+        const file = path.join(agentsDir, `${role}.md`);
+        const text = readFileSync(file, 'utf8');
+        const site = findMaxTurns(text, file);
+        return {
+            change: { role, env: name, from: site.value, to, changed: site.value !== to },
+            file,
+            next: withMaxTurns(text, site, to),
+        };
+    });
+    return { mode: 'sync', dryRun, agentsDir, roles, changes: apply(edits, dryRun) };
+}
+/**
+ * Put every template's `maxTurns:` back to the value committed at git HEAD,
+ * touching only that line — any other local edit to the file stays. Refuses
+ * when the templates are not in a git checkout, rather than guess a default.
+ */
+export function resetAgentMaxTurns(options = {}) {
+    const agentsDir = options.agentsDir ?? AGENTS_DIR;
+    const dryRun = options.dryRun ?? false;
+    const roles = listRoles(agentsDir);
+    let topLevel;
+    try {
+        topLevel = runGit(agentsDir, ['rev-parse', '--show-toplevel']);
+    }
+    catch (err) {
+        if (!(err instanceof GitCommandError))
+            throw err;
+        throw new AgentsSyncError('agents.reset-unavailable', `--reset needs git HEAD, but ${agentsDir} is not inside a git checkout.`, { agentsDir });
+    }
+    const edits = roles.map((role) => {
+        const file = path.join(agentsDir, `${role}.md`);
+        const rel = path.relative(topLevel, realpathSync(file)).split(path.sep).join('/');
+        let committed;
+        try {
+            committed = runGitRaw(topLevel, ['show', `HEAD:${rel}`]);
+        }
+        catch (err) {
+            if (!(err instanceof GitCommandError))
+                throw err;
+            throw new AgentsSyncError('agents.reset-unavailable', `--reset needs ${rel} at git HEAD, and it is not there.`, { file: rel });
+        }
+        const to = findMaxTurns(committed, `HEAD:${rel}`).value;
+        const text = readFileSync(file, 'utf8');
+        const site = findMaxTurns(text, file);
+        return {
+            change: {
+                role,
+                env: maxTurnsEnvName(role),
+                from: site.value,
+                to,
+                changed: site.value !== to,
+            },
+            file,
+            next: withMaxTurns(text, site, to),
+        };
+    });
+    return { mode: 'reset', dryRun, agentsDir, roles, changes: apply(edits, dryRun) };
+}

package/factory/orchestrator/dist/audit.js

@@ -32,11 +32,15 @@
 import { randomBytes } from 'node:crypto';
 import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
 import path from 'node:path';
+import { resolveFindingOwner } from './claims.js';
 import { SmithError } from './errors.js';
 import { appendEvent } from './events.js';
 import { computeFingerprint, normalizeFilePath } from './findings.js';
 import { runGit } from './git.js';
 import { checkWorktreeImmutable, fingerprintWorktree, } from './immutability.js';
+import { isFactoryCheckout, SPECS_ACTIVE_DIR } from './paths.js';
+import { latestPlanVersion, loadPlan, planClaimedTasks, } from './plan.js';
+import { defaultKindFor, FACTORY_PROJECT } from './roadmap.js';
 import { loadTaxonomy } from './taxonomy.js';
 export class AuditError extends SmithError {
 }
@@ -251,11 +255,31 @@ export function foldAuditStore(lines, opts = {}) {
  * The fingerprints an axis may not raise again. This is the whole of the
  * dedupe half of §3.1 — `audit record` drops what this names and appends the
  * rest.
+ *
+ * Each suppressing finding contributes two fingerprints, not one. Its
+ * stored `finding.fingerprint` is whatever `computeFingerprint` produced
+ * *when the line was written* — widening that normalizer (issue #178) does
+ * not rewrite `findings.jsonl`, so a decline recorded before a normalizer
+ * fix keeps its old hash forever. The raised line still carries its own
+ * `file_path`/`axis`/`summary`, so recomputing the fingerprint with today's
+ * normalizer costs nothing and lets a pre-existing decline suppress a
+ * re-raise that only differs in what the new normalizer now strips — no
+ * store rewrite, no migration. When the stored hash and the recomputed one
+ * already agree (the common case), the second `add` is a no-op.
  */
 export function suppressedFingerprints(lines, opts = {}) {
-    return new Set(foldAuditStore(lines, opts)
-        .filter((finding) => finding.suppressesReraise)
-        .map((finding) => finding.fingerprint));
+    const set = new Set();
+    for (const finding of foldAuditStore(lines, opts)) {
+        if (!finding.suppressesReraise)
+            continue;
+        set.add(finding.fingerprint);
+        set.add(computeFingerprint({
+            filePath: finding.file_path,
+            category: finding.axis,
+            summary: finding.summary,
+        }));
+    }
+    return set;
 }
 function clusterOf(filePath, findings) {
     const members = findings.filter((finding) => finding.status !== 'merged');
@@ -398,6 +422,39 @@ function mintAuditId(now) {
     const day = now.toISOString().slice(0, 10).replaceAll('-', '');
     return `${day}-${randomBytes(4).toString('hex')}`;
 }
+/**
+ * The name an audit calls `project` by, everywhere one is needed: the
+ * event's `project` field, the cut milestone's `- project:` line and goal
+ * sentence, and the cut spec's Project line.
+ *
+ * `path.basename(project)` names every OTHER project correctly, but this
+ * clone's own directory is not always named FACTORY_PROJECT
+ * (`black-smith`) -- roadmap.ts's own note documents the real `black-smith`/
+ * `blacksmith` siblings this factory was built beside -- so a self-audit that
+ * used the basename wrote a name `collectProjects()` (projects.ts) had never
+ * seen, sent it looking for a checkout under this clone's own parent, and it
+ * found this very clone: registered a second time as a foreign, non-self ref
+ * that `--no-self` could not filter. Comparing against REPO_ROOT, resolved
+ * the same way `unwatchedProjects` (projects.ts) already does, is what tells
+ * "this clone, filed under its own directory name" from "a project that is
+ * genuinely named that".
+ */
+export function auditedProjectName(project) {
+    return isFactoryCheckout(project) ? FACTORY_PROJECT : path.basename(project);
+}
+/**
+ * The `- kind:` a cut milestone declares alongside auditedProjectName's
+ * `- project:` line. roadmap.ts's own parser fixes the two together
+ * (`roadmap.factory-kind-fixed`): a milestone naming FACTORY_PROJECT must be
+ * kind "factory", never "product". A cut that named a self-audit
+ * FACTORY_PROJECT but still wrote a hard-coded "product" kind would stamp a
+ * milestone that fails to parse the moment `loadRoadmap()` reads it back, so
+ * this feeds auditedProjectName's own answer through roadmap.ts's
+ * defaultKindFor rather than re-deriving it separately.
+ */
+export function auditedProjectKind(project) {
+    return defaultKindFor(auditedProjectName(project));
+}
 /**
  * The audit's events are ordinary events on the operator's session, stamped
  * with the project's name so the multi-project timeline can tell whose audit
@@ -412,7 +469,7 @@ function emit(eventType, project, ctx, opts, payload) {
         event_type: eventType,
         plan_version: ctx.planVersion,
         causal_parent: ctx.causalParent,
-        project: path.basename(project),
+        project: auditedProjectName(project),
         payload,
     }, opts);
 }
@@ -635,7 +692,7 @@ function cite(finding) {
 function renderMilestone(input, project, findings) {
     const audits = auditIdsOf(findings);
     const goal = [
-        `Cut from audit ${audits.join(', ')} of \`${path.basename(project)}\` (${findings.length} accepted finding${findings.length === 1 ? '' : 's'}: ${severityCounts(findings)}).`,
+        `Cut from audit ${audits.join(', ')} of \`${auditedProjectName(project)}\` (${findings.length} accepted finding${findings.length === 1 ? '' : 's'}: ${severityCounts(findings)}).`,
         'Each finding below is one acceptance criterion; the plan decides the tasks.',
         ...findings.map((finding) => `${cite(finding)}.`),
     ].join(' ');
@@ -644,8 +701,8 @@ function renderMilestone(input, project, findings) {
         `- id: ${input.epicId}`,
         '- status: planned',
         `- epics: [${input.epicId}]`,
-        `- project: ${path.basename(project)}`,
-        '- kind: product',
+        `- project: ${auditedProjectName(project)}`,
+        `- kind: ${auditedProjectKind(project)}`,
         `- goal: ${goal}`,
         '',
     ].join('\n');
@@ -673,9 +730,9 @@ function renderSpec(input, project, findings) {
         `# Epic spec — \`${input.epicId}\``,
         '',
         `- **Epic id** — \`${input.epicId}\``,
-        `- **Project** — \`${path.basename(project)}\` at \`${project}\`, and every worktree is placed beside that clone (\`AGENTS.md\` "Worktrees").`,
+        `- **Project** — \`${auditedProjectName(project)}\` at \`${project}\`, and every worktree is placed beside that clone (\`AGENTS.md\` "Worktrees").`,
         `- **Roadmap milestone** — \`${input.epicId}\` in \`factory/specs/roadmap.md\`.`,
-        `- **Provenance** — cut by \`smith audit cut\` from audit ${audits.join(', ')} (${findings.length} accepted finding${findings.length === 1 ? '' : 's'}: ${severityCounts(findings)}). Each finding carries this epic id in \`.blacksmith/findings.jsonl\`; \`smith audit resolve\` marks them fixed when the epic closes.`,
+        `- **Provenance** — cut by \`smith audit cut\` from audit ${audits.join(', ')} (${findings.length} accepted finding${findings.length === 1 ? '' : 's'}: ${severityCounts(findings)}). Each finding carries this epic id in \`.blacksmith/findings.jsonl\`; \`smith audit resolve\` marks fixed only the ones a task in this plan still claims, and leaves the rest \`deferred\`.`,
         '',
         '## What this epic is',
         '',
@@ -734,24 +791,83 @@ export async function cutAudit(projectDir, input, ctx, opts = {}) {
     };
 }
 /**
- * `audit resolve <project-dir> --epic <epic-id>`. Appends a `fixed` line for
- * every finding the epic carried. Called from `/bs run`'s epic-close step, so
- * it is repeatable; an epic no finding carries is refused, because the likely
- * cause is a typo and a silent no-op would leave every finding open.
+ * The epic's newest plan, however `resolveOpts` asks for it found. Refuses
+ * rather than guesses: `resolveAudit` must never treat "I could not find a
+ * plan" as "nothing is claimed", because that reading marks every carried
+ * finding fixed.
+ */
+function resolveEpicPlan(epicId, resolveOpts) {
+    if (resolveOpts.plan !== undefined)
+        return resolveOpts.plan;
+    const planOpts = resolveOpts.planOpts ?? {};
+    const version = latestPlanVersion(epicId, planOpts);
+    if (version === null) {
+        const searchedDir = path.join(planOpts.specsDir ?? SPECS_ACTIVE_DIR, epicId);
+        throw new AuditError('audit.no-plan', `no plan found for epic ${epicId}: \`audit resolve\` only marks a finding fixed when some plan task claims its file, so a missing plan cannot be treated as an empty one. Searched ${searchedDir}. If this epic's plans live elsewhere, pass --specs-dir <dir> naming the directory they live in, or --plan <plan.json> to point at one directly.`, { epic: epicId });
+    }
+    return loadPlan(epicId, version, planOpts);
+}
+/**
+ * `--except` entries against the epic's carried fingerprints, full or a
+ * unique prefix — the same latitude other audit verbs give a fingerprint
+ * argument. A value that matches nothing is refused as a likely typo (same
+ * spirit as `audit.unknown-epic`); one whose prefix matches more than one
+ * carried fingerprint is refused rather than guessed.
+ */
+function matchExceptFingerprints(except, carried, epicId) {
+    const known = carried.map((finding) => finding.fingerprint);
+    const matched = new Set();
+    for (const value of except) {
+        if (known.includes(value)) {
+            matched.add(value);
+            continue;
+        }
+        const candidates = known.filter((fingerprint) => fingerprint.startsWith(value));
+        if (candidates.length === 1) {
+            matched.add(candidates[0]);
+            continue;
+        }
+        if (candidates.length > 1) {
+            throw new AuditError('audit.ambiguous-except', `--except ${value} matches ${candidates.length} findings epic ${epicId} carries: ${candidates.join(', ')}`, { epic: epicId, value, candidates });
+        }
+        throw new AuditError('audit.unknown-finding', `--except ${value} matches no finding epic ${epicId} carries`, { epic: epicId, value });
+    }
+    return matched;
+}
+/**
+ * `audit resolve <project-dir> --epic <epic-id>`. Appends a `fixed` line only
+ * for a carried finding some task in the epic's newest plan still claims
+ * (`resolveFindingOwner`, D-41/P9-24) — an operator who scoped the plan
+ * narrower than the audit deferred the rest on purpose, and marking them
+ * fixed anyway would erase that choice. Unclaimed findings stay exactly as
+ * they were and come back in `deferred`; `--except` forces specific
+ * fingerprints there even when a task claims them. Called from `/bs run`'s
+ * epic-close step, so it is repeatable; an epic no finding carries is
+ * refused, because the likely cause is a typo and a silent no-op would leave
+ * every finding open. A plan that cannot be found is refused too
+ * (`audit.no-plan`): being unsure must never mark anything fixed.
  */
-export async function resolveAudit(projectDir, epicId, ctx, opts = {}) {
+export async function resolveAudit(projectDir, epicId, ctx, opts = {}, resolveOpts = {}) {
     const project = path.resolve(projectDir);
     const carried = foldAuditStore(readAuditStore(project)).filter((finding) => finding.epic === epicId);
     if (carried.length === 0) {
         throw new AuditError('audit.unknown-epic', `no finding in ${auditStorePath(project)} carries epic ${epicId}: was it cut with \`smith audit cut\`?`, { epic: epicId });
     }
     const open = carried.filter((finding) => finding.status !== 'fixed');
+    const plan = resolveEpicPlan(epicId, resolveOpts);
+    const claimedTasks = planClaimedTasks(plan);
+    const except = matchExceptFingerprints(resolveOpts.except ?? [], carried, epicId);
+    const toFix = open.filter((finding) => !except.has(finding.fingerprint) &&
+        resolveFindingOwner(finding.file_path, claimedTasks).owner !== 'unclaimed');
+    const toFixFingerprints = new Set(toFix.map((finding) => finding.fingerprint));
+    const deferred = open.filter((finding) => !toFixFingerprints.has(finding.fingerprint));
     const stored = await emit('audit-resolved', project, ctx, opts, {
         epic: epicId,
-        fixed: open.map((finding) => finding.fingerprint),
+        fixed: toFix.map((finding) => finding.fingerprint),
+        deferred: deferred.map((finding) => finding.fingerprint),
     });
     const ts = new Date().toISOString();
-    appendAuditLines(project, open.map((finding) => ({
+    appendAuditLines(project, toFix.map((finding) => ({
         fingerprint: finding.fingerprint,
         status: 'fixed',
         ts,
@@ -761,10 +877,11 @@ export async function resolveAudit(projectDir, epicId, ctx, opts = {}) {
     })));
     return {
         epic: epicId,
-        fixed: open.map((finding) => finding.fingerprint),
+        fixed: toFix.map((finding) => finding.fingerprint),
         already: carried
             .filter((finding) => finding.status === 'fixed')
             .map((finding) => finding.fingerprint),
+        deferred: deferred.map((finding) => finding.fingerprint),
         event_id: stored.event_id,
     };
 }

package/factory/orchestrator/dist/autonomy.js

@@ -60,6 +60,8 @@ function subjectOf(proposal) {
         }
         case 'growth-review-due':
             return `product-growth review, ${proposal.cadenceDays}-day cadence`;
+        case 'error-report':
+            return `issue report for error ${proposal.fingerprint} (${proposal.errorClass}, task ${proposal.taskRef})`;
     }
 }
 /** The text the security keywords are matched against, named by field so a hit can say where. */
@@ -76,6 +78,17 @@ function securityFields(proposal, ctx) {
             return proposal.packages.map((p) => ({ field: 'package', value: p.name }));
         case 'growth-review-due':
             return [];
+        case 'error-report':
+            // Refused ahead of the keyword match (see classify() below); listed so
+            // the switch stays exhaustive. proposal.project is only ever null when
+            // errorIssues.ts's fail-closed fold could not resolve one, which this
+            // branch never actually returns for -- see classify()'s early
+            // 'tracker-write-never-auto' refusal for every 'error-report' kind.
+            return [
+                { field: 'task ref', value: proposal.taskRef },
+                { field: 'error class', value: proposal.errorClass },
+                { field: 'project', value: proposal.project ?? '(unresolved)' },
+            ];
     }
 }
 function classify(proposal, policy, ctx) {
@@ -95,6 +108,18 @@ function classify(proposal, policy, ctx) {
             reason: 'A product-growth review proposes SCOPE, and scope is the operator\'s (architecture §12: "product-growth proposals always wait for an operator tick"). Listing the kind in auto_dispatch_kinds changes nothing.',
         };
     }
+    // Same place, same reason shape: reporting an error writes to an external
+    // issue tracker under an authenticated `gh` token whose scope includes
+    // `repo`, and scheduler.yml's autonomy block already holds that anything
+    // touching auth or secrets always waits for a person. Ahead of the
+    // whitelist so that listing the kind changes nothing.
+    if (proposal.kind === 'error-report') {
+        return {
+            decision: 'operator',
+            code: 'tracker-write-never-auto',
+            reason: 'Reporting an error writes to an external issue tracker under an authenticated gh token whose scope includes repo. scheduler.yml\'s autonomy block holds that anything touching auth or secrets always waits for a person, so listing "error-report" in auto_dispatch_kinds changes nothing.',
+        };
+    }
     if (!policy.autoDispatchKinds.includes(proposal.kind)) {
         return {
             decision: 'operator',

package/factory/orchestrator/dist/budgets.js

@@ -144,8 +144,97 @@ export function parseBudgetPolicy(yamlText) {
         escalationLadder: parseEscalationLadder(doc.escalation_ladder?.rungs),
     };
 }
-export function loadBudgetPolicy(filePath = BUDGETS_POLICY_PATH) {
-    return parseBudgetPolicy(readFileSync(filePath, 'utf8'));
+const INT_OVERRIDES = [
+    ['SMITH_EPIC_CAP_TOKENS', 'epicCap'],
+    ['SMITH_EPIC_MAX_IN_FLIGHT_TASKS', 'maxInFlight'],
+    ['SMITH_TASK_CODER_CAP_TOKENS', 'coderCap'],
+    ['SMITH_TASK_CODER_CAP_DIFF_LINES', 'coderDiff'],
+    ['SMITH_TASK_RESEARCHER_CAP_TOKENS', 'researcherCap'],
+    ['SMITH_TASK_JUDGES_CAP_TOKENS', 'judgesCap'],
+];
+const RATIO_OVERRIDE = 'SMITH_EPIC_ALARM_RATIO';
+export const BUDGET_ENV_VARS = Object.freeze([
+    'SMITH_EPIC_CAP_TOKENS',
+    RATIO_OVERRIDE,
+    ...INT_OVERRIDES.slice(1).map(([name]) => name),
+]);
+function envValue(env, name) {
+    const value = env[name];
+    return value === undefined || value === '' ? null : value;
+}
+/**
+ * Strict on purpose, and stricter than the YAML: a `.env` line is typed by
+ * hand, and `4M`, `4e6` or `4_000_000` read as something else by every parser
+ * that accepts them. Digits only, no sign, no exponent, greater than zero.
+ * The error names the variable and the value it was given, and nothing else.
+ */
+function envPositiveInt(name, raw) {
+    const value = /^[0-9]+$/.test(raw) ? Number(raw) : Number.NaN;
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new BudgetError('budgets.invalid-env', `${name} must be a positive integer (digits only); got ${JSON.stringify(raw)}.`, { variable: name });
+    }
+    return value;
+}
+function envRatio(name, raw) {
+    const value = /^(?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+)$/.test(raw) ? Number(raw) : Number.NaN;
+    if (!Number.isFinite(value) || value <= 0 || value > 1) {
+        throw new BudgetError('budgets.invalid-env', `${name} must be a decimal in (0, 1]; got ${JSON.stringify(raw)}.`, { variable: name });
+    }
+    return value;
+}
+/**
+ * `policy` with every set budget env name applied on top. Pure: it reads only
+ * `env` and returns a new policy. Every name is validated before any is
+ * applied, so a bad value refuses the whole overlay rather than half of it.
+ */
+export function applyBudgetEnv(policy, env) {
+    const ints = new Map();
+    for (const [name, field] of INT_OVERRIDES) {
+        const raw = envValue(env, name);
+        if (raw !== null)
+            ints.set(field, envPositiveInt(name, raw));
+    }
+    const rawRatio = envValue(env, RATIO_OVERRIDE);
+    const ratio = rawRatio === null ? null : envRatio(RATIO_OVERRIDE, rawRatio);
+    return {
+        ...policy,
+        epic: {
+            capTokens: ints.get('epicCap') ?? policy.epic.capTokens,
+            alarmRatio: ratio ?? policy.epic.alarmRatio,
+            maxInFlightTasks: ints.get('maxInFlight') ?? policy.epic.maxInFlightTasks,
+        },
+        task: {
+            coder: {
+                capTokens: ints.get('coderCap') ?? policy.task.coder.capTokens,
+                capDiffLines: ints.get('coderDiff') ?? policy.task.coder.capDiffLines,
+            },
+            researcher: { capTokens: ints.get('researcherCap') ?? policy.task.researcher.capTokens },
+            judges: { capTokens: ints.get('judgesCap') ?? policy.task.judges.capTokens },
+        },
+    };
+}
+/**
+ * The budget env names whose value actually changed a number of `base` (the
+ * policy as budgets.yml has it) — names only, never values — so a report that
+ * prints an effective cap can say it did not come from budgets.yml. A name
+ * set to the value budgets.yml already holds overrode nothing and is left
+ * out: `.env.example` ships every knob at its default, so a copied `.env`
+ * sets all of them.
+ */
+export function budgetEnvOverrides(base, env = process.env) {
+    return BUDGET_ENV_VARS.filter((name) => {
+        if (envValue(env, name) === null)
+            return false;
+        const alone = applyBudgetEnv(base, { [name]: env[name] });
+        return JSON.stringify(alone) !== JSON.stringify(base);
+    });
+}
+/**
+ * budgets.yml, with the box's env overrides on top. Every consumer reads the
+ * policy through here, so an override reaches all of them or none.
+ */
+export function loadBudgetPolicy(filePath = BUDGETS_POLICY_PATH, env = process.env) {
+    return applyBudgetEnv(parseBudgetPolicy(readFileSync(filePath, 'utf8')), env);
 }
 /**
  * For each field a task budget may declare, the mechanism that reads it — or

package/factory/orchestrator/dist/claims.js

@@ -4,6 +4,7 @@ import { parse as parseYaml } from 'yaml';
 import { SmithError } from './errors.js';
 import { runGit, runGitRaw } from './git.js';
 import { WORKTREE_POLICY_PATH } from './paths.js';
+import { HELD_OPEN_BY_AN_OPERATOR, TERMINAL_TASK_STATUSES } from './taskStatus.js';
 export class ClaimsError extends SmithError {
 }
 function splitPathSegments(p) {
@@ -472,11 +473,14 @@ export function resolveFindingOwner(filePath, tasks) {
  * landed (`completed`), the team already accepted the gap (`waived`), or a
  * later plan version replaced the task outright (`superseded`).
  *
- * `failed` and `escalated` are deliberately NOT here: those tasks are still
- * open work an operator is holding, and a finding about their files belongs
- * on them rather than on a new task competing for the same claims.
+ * That is every terminal status except the ones an operator is still holding:
+ * a finding about a `failed` or `escalated` task's files belongs on that task
+ * rather than on a new one competing for the same claims. The exception is
+ * declared in taskStatus.ts as HELD_OPEN_BY_AN_OPERATOR and subtracted here,
+ * so the three strings this used to name by hand come from the roster the
+ * dimension already keeps rather than from a fourth copy of it.
  */
-const CLOSED_TO_FURTHER_WORK = new Set(['completed', 'waived', 'superseded']);
+const CLOSED_TO_FURTHER_WORK = new Set([...TERMINAL_TASK_STATUSES].filter((status) => !HELD_OPEN_BY_AN_OPERATOR.has(status)));
 /**
  * Where a finding should land, given who owns its file (D-41/P9-24).
  *