@juzser/blacksmith 0.1.0 → 0.1.1

package/factory/orchestrator/dist/agents-registry.js

@@ -38,14 +38,30 @@ import { epicOfTaskId } from './taskId.js';
  * entry still open under that task, because after a task-level failure nobody
  * is still running.
  *
+ * An epic-level dispatch — a planner, a spec-reviewer, a scribe, sent for
+ * the epic with no task id — closes on a terminal event that also names no
+ * task and does name its role (F2, the cross-provider UI check of
+ * 2026-09-14). Its Result is recorded as a `task-result-recorded` with no
+ * task id and `agent_role` in the payload, and until F2 every terminal branch
+ * was guarded on the task id, so ten such results across the real logs closed
+ * nothing: a planner that returned in four minutes read as live for the rest
+ * of the epic. The event speaks for the latest still-open epic-level entry of
+ * that role in the same session — latest because a result belongs to the
+ * dispatch that caused it, and that is the most recent one — and steps back
+ * when the two name different epics. There is no supersession at this level
+ * (D-244): a second planner dispatch is a second round, not a replacement,
+ * and a terminal event that names no role closes nothing here, because
+ * guessing which agent a session-level error was about is the D-244 mistake
+ * one level up.
+ *
  * Above all of those sits `epic-closed` (D-187). Every close named so far
- * needs a task id to speak through, so an agent whose task simply never
- * reported — and an epic-level dispatch, which has no task id to speak
- * through at all — stayed `live` past the verdict, past the end of the run,
- * forever. The epic's own terminal event is the only thing that can say
- * otherwise, and it closes what is still open under that epic in that session
- * as `abandoned`: not superseded (nothing replaced them) and not an error
- * (they were never judged), just outrun by the run they belonged to.
+ * needs a task id or a role to speak through, so an agent whose task simply
+ * never reported — and an epic-level dispatch whose Result never came —
+ * stayed `live` past the verdict, past the end of the run, forever. The
+ * epic's own terminal event is the only thing that can say otherwise, and it
+ * closes what is still open under that epic in that session as `abandoned`:
+ * not superseded (nothing replaced them) and not an error (they were never
+ * judged), just outrun by the run they belonged to.
  */
 export const DISPATCH_EVENT_TYPE = 'dispatch_decision';
 /** Phase 5 addition (deviation, noted in the final report): the terminal counterpart to dispatch_decision. */
@@ -147,6 +163,26 @@ function closeOpen(open, taskId, role, eventId, ts, terminalType) {
         open.delete(key);
     }
 }
+/**
+ * Close the epic-level entry a task-less terminal event speaks for: the
+ * latest still-open dispatch of `role` in `sessionId` (F2). `epicId` is the
+ * event's own claim about which epic it belongs to; when both sides name one
+ * and they differ, the event is another epic's and closes nothing here. The
+ * list is scanned from the end because the most recent dispatch of a role is
+ * the one whose Result this is.
+ */
+function closeOpenEpicLevel(openEpicLevel, sessionId, role, epicId, eventId, ts, terminalType) {
+    for (let i = openEpicLevel.length - 1; i >= 0; i--) {
+        const entry = openEpicLevel[i];
+        if (!entry || entry.sessionId !== sessionId || entry.agentRole !== role)
+            continue;
+        if (epicId && entry.epicId && entry.epicId !== epicId)
+            continue;
+        closeEntry(entry, eventId, ts, terminalType);
+        openEpicLevel.splice(i, 1);
+        return;
+    }
+}
 /**
  * Fold a session's full event history into agent registry rows. Pure
  * function over the event list — used identically by db/projector.ts's
@@ -156,7 +192,8 @@ function closeOpen(open, taskId, role, eventId, ts, terminalType) {
 export function foldAgents(events) {
     const open = new Map();
     // Dispatches with no task id have no correlation key, so they cannot live in
-    // `open` — but they are still open, and `epic-closed` still speaks for them.
+    // `open` — but they are still open: a task-less terminal naming their role
+    // closes the latest of them (F2), and `epic-closed` sweeps the rest.
     let openEpicLevel = [];
     const records = [];
     for (const { event_id, record } of events) {
@@ -205,13 +242,20 @@ export function foldAgents(events) {
         }
         if (record.event_type === TASK_RESULT_EVENT_TYPE) {
             // The Result names its author in `agent` (result.schema.json's required
-            // field). A hand-appended one that omits it still closes the task.
+            // field). A hand-appended one that omits it still closes the task. An
+            // epic-level one, recorded by hand with no task id, spells the role as
+            // `agent_role` — the dispatch's own key — in every real log so far, so
+            // the fold reads either.
             const payload = record.payload;
             // Both levels: result.schema.json names the task in the payload, and the
             // dispatch this closes may have named it only there too (D-245).
             const taskId = eventTaskId(record);
+            const role = payload.agent ?? payload.agent_role ?? null;
             if (taskId) {
-                closeOpen(open, taskId, payload.agent ?? null, event_id, record.ts, 'result');
+                closeOpen(open, taskId, role, event_id, record.ts, 'result');
+            }
+            else if (role) {
+                closeOpenEpicLevel(openEpicLevel, record.session_id, role, payload.epic_id, event_id, record.ts, 'result');
             }
             continue;
         }
@@ -221,19 +265,25 @@ export function foldAgents(events) {
             if (taskId) {
                 closeOpen(open, taskId, payload.agent_role ?? null, event_id, record.ts, 'result');
             }
+            else if (payload.agent_role) {
+                closeOpenEpicLevel(openEpicLevel, record.session_id, payload.agent_role, payload.epic_id, event_id, record.ts, 'result');
+            }
             continue;
         }
         if (record.event_type === JUDGE_VERDICT_EVENT_TYPE) {
             const payload = record.payload;
             const taskId = eventTaskId(record);
+            // A run that produced no schema-valid verdict did not do its job, and
+            // `ok: false` is how the log says so. Closing it as a result would let
+            // a provider failing every call read exactly like one answering every
+            // call — the distinction providerAgreement() exists to measure.
+            const terminal = payload.ok === false ? 'error' : 'result';
             if (taskId) {
-                // A run that produced no schema-valid verdict did not do its job, and
-                // `ok: false` is how the log says so. Closing it as a result would let
-                // a provider failing every call read exactly like one answering every
-                // call — the distinction providerAgreement() exists to measure.
-                const terminal = payload.ok === false ? 'error' : 'result';
                 closeOpen(open, taskId, payload.agent ?? null, event_id, record.ts, terminal);
             }
+            else if (payload.agent) {
+                closeOpenEpicLevel(openEpicLevel, record.session_id, payload.agent, payload.epic_id, event_id, record.ts, terminal);
+            }
             continue;
         }
         if (record.event_type === ERROR_EVENT_TYPE) {
@@ -244,6 +294,11 @@ export function foldAgents(events) {
             if (taskId) {
                 closeOpen(open, taskId, payload.agent_role ?? null, event_id, record.ts, 'error');
             }
+            else if (payload.agent_role) {
+                // Only with a role: a session-level error names nobody, and every
+                // epic-level agent stays where it was.
+                closeOpenEpicLevel(openEpicLevel, record.session_id, payload.agent_role, payload.epic_id, event_id, record.ts, 'error');
+            }
             continue;
         }
         if (record.event_type === EPIC_CLOSED_EVENT_TYPE) {
@@ -262,10 +317,10 @@ export function foldAgents(events) {
                 closeEntry(entry, event_id, record.ts, 'abandoned');
                 open.delete(key);
             }
-            // The epic-level half keeps D-187's reasoning for an entry nothing
-            // places -- no task id and no `epic_id` on its dispatch means no other
-            // terminal event can ever name it, so the run's own verdict is the last
-            // thing that can close it. But an entry that DID name an epic is placed,
+            // The epic-level half keeps D-187's reasoning for an entry whose Result
+            // never came -- no task id means only a terminal naming its role (F2)
+            // or the run's own verdict can close it, and this is the verdict. But
+            // an entry that DID name an epic is placed,
             // and one session runs several epics in a row: sweeping the lot closed
             // the next epic's planner, live and working, on the previous epic's
             // verdict (D-234).
@@ -306,3 +361,25 @@ export function detectStale(agents, nowIso, staleHours = DEFAULT_STALE_HOURS) {
 export function liveAgents(agents) {
     return agents.filter((a) => a.status === 'live');
 }
+/**
+ * Whether a dispatch at `dispatchedAt` still counts as *working* at `nowIso`:
+ * the dashboard's answer to "is anyone actually on this right now", as
+ * opposed to "has no terminal event closed it yet" (`liveAgents`). Same
+ * arithmetic and the same strict `>` as `detectStale` — working is the
+ * complement of stale over the live set — kept as one predicate so the
+ * queries that count, group and label agents cannot drift from the
+ * threshold the registry warns on.
+ *
+ * Two readings `detectStale`'s loop leaves implicit are pinned here because
+ * the dashboard renders them: a dispatch whose timestamp does not parse is
+ * NOT working (NaN compares false in both directions, which would otherwise
+ * read as "not stale, so working" — an unreadable clock is never evidence
+ * of activity), and a future-dated dispatch IS working (clock skew between
+ * the writer and the reader is not staleness).
+ */
+export function isWorkingAt(dispatchedAt, nowIso, staleHours = DEFAULT_STALE_HOURS) {
+    const liveHours = (new Date(nowIso).getTime() - new Date(dispatchedAt).getTime()) / 3.6e6;
+    if (Number.isNaN(liveHours))
+        return false;
+    return liveHours <= staleHours;
+}

package/factory/orchestrator/dist/artifacts.js

@@ -1,7 +1,7 @@
 import { existsSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 import { SmithError } from './errors.js';
-import { STATE_ARTIFACTS_DIR } from './paths.js';
+import { STATE_ARTIFACTS_DIR, WORK_ROOT } from './paths.js';
 /**
  * Where a task's artifacts belong: `state/artifacts/<task-id>/`, beside
  * `state/results/<task-id>.json`. One home per task, named by the task, so the
@@ -38,6 +38,33 @@ function realOf(p) {
         return p;
     }
 }
+/**
+ * How the home is spelled from the work root — `state/artifacts/<task-id>` in
+ * production — or null when it does not sit under that root at all, in which
+ * case no relative declaration can be naming it.
+ */
+function spellingFromWorkRoot(home, workRoot) {
+    const rel = path.relative(path.resolve(workRoot), home);
+    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel))
+        return null;
+    return rel;
+}
+/**
+ * The declared path with the home's own spelling stripped off, when it starts
+ * with one: `state/artifacts/<task-id>/round2.txt` becomes `round2.txt`, and
+ * the bare spelling becomes `''`, which is the home itself and reports as
+ * `no-path`. Anything else — an absolute path, a plain filename, another
+ * task's home — is handed back as written.
+ */
+function withinHome(declared, homeSpelling) {
+    if (homeSpelling === null || path.isAbsolute(declared))
+        return declared;
+    const normalized = path.normalize(declared);
+    if (normalized === homeSpelling)
+        return '';
+    const prefix = homeSpelling + path.sep;
+    return normalized.startsWith(prefix) ? normalized.slice(prefix.length) : declared;
+}
 /** True when `child` is `root` itself or lives beneath it. */
 function contains(root, child) {
     if (child === root)
@@ -48,7 +75,11 @@ function contains(root, child) {
 /**
  * Check every path a result declares as evidence. Relative paths resolve
  * against the task's home, so `coverage.txt` means the obvious thing and the
- * short spelling is also the correct one.
+ * short spelling is also the correct one. A path that already begins with the
+ * home's own spelling from the work root — `state/artifacts/<task-id>/x` — is
+ * read as that spelling, not as a subtree of the home: the template says
+ * "under `state/artifacts/<task-id>/`", a coder wrote exactly that, and the
+ * doubled path came back `missing` for a file that existed (FD-5).
  *
  * Two properties, in this order. Inside the home first: a path in the wrong
  * place is wrong whether or not the file happens to be there today, and saying
@@ -79,8 +110,9 @@ export function checkArtifacts(artifacts, opts) {
     const realHome = existsSync(home) ? realOf(home) : home;
     const expectedHome = existsSync(home) ? homeUnder(realOf(root), opts.taskId) : home;
     const homeEscaped = realHome !== expectedHome;
+    const homeSpelling = spellingFromWorkRoot(home, opts.workRoot ?? WORK_ROOT);
     for (const decl of artifacts) {
-        const resolved = path.resolve(home, decl.path);
+        const resolved = path.resolve(home, withinHome(decl.path, homeSpelling));
         if (resolved === home) {
             issues.push({ declared: decl.path, resolved, problem: 'no-path' });
             continue;
@@ -90,7 +122,7 @@ export function checkArtifacts(artifacts, opts) {
             continue;
         }
         if (homeEscaped) {
-            const real = path.resolve(realHome, decl.path);
+            const real = path.resolve(realHome, withinHome(decl.path, homeSpelling));
             issues.push({ declared: decl.path, resolved: real, problem: 'outside-home' });
             continue;
         }

package/factory/orchestrator/dist/budgets.js

@@ -157,11 +157,13 @@ export function loadBudgetPolicy(filePath = BUDGETS_POLICY_PATH) {
  * visible, so plan validation can say "you wrote down a limit nobody can
  * apply" instead of the plan quietly implying otherwise.
  *
- * `max_turns` is null on purpose, and not because the wiring is pending: a turn
- * limit has to live in the dispatch harness, and the Agent tool exposes no
- * turns parameter (agent-interviews.md M-4, answered (c) on 2026-08-05 — the
- * number is carried into the dispatch prompt by the /bs skill, where it is a
- * request to the agent, not a limit on it).
+ * `max_turns` is null on purpose, and not because the wiring is pending: the
+ * turn limit lives in the dispatch harness, which reads the role template's
+ * `maxTurns` (`.claude/agents/<role>.md`) — per role, never per task
+ * (agent-interviews.md M-4, answered (c) on 2026-08-05 and corrected
+ * 2026-09-11 once the cap was measured). A plan cannot raise or lower a
+ * role's ceiling, so a number here would be a second copy the harness never
+ * consults; the /bs dispatch contract restates the template's value instead.
  */
 export const TASK_BUDGET_FIELD_READERS = Object.freeze({
     tokens: 'gate: compared against the result’s token_usage.total_tokens',

package/factory/orchestrator/dist/cli.js

@@ -36,6 +36,7 @@ import { appendEvent, filterEvents, listSessionIds, mergeSessionLogs, readEvents
 import { findingsForDispatch } from './findingContext.js';
 import { AMEND_PENDING_STATUS, AMENDED_STATUS, findingScope, listFindings, mintFindings, OPEN_FINDING_STATUSES, raiseFinding, repairObligation, reverifyFinding, SPEC_FINDING_SCOPE, transition as transitionFinding, } from './findings.js';
 import { recordGoalCheck, resolveEpicGoal } from './goalCheck.js';
+import { loadHarnessPolicy, planWorkerTurn, summarizeHarnesses } from './harness.js';
 import { decideHookPayload } from './hookDecision.js';
 import { checkWorktreeImmutable, fingerprintWorktree, } from './immutability.js';
 import { collectExportDiffs, exportImpact, waveImpact } from './impact.js';
@@ -43,7 +44,7 @@ import { integrationHeadSha, runIntegrationCheck } from './integration.js';
 import { judgePreflight } from './judgePreflight.js';
 import { outstandingJudges, readJudgeTurns, recordJudgeDispatch, recordJudgeReport, } from './judges.js';
 import { addMcpSurface, resolveMcpSurface, runMcpCheck } from './mcp.js';
-import { DOTENV_PATH, LESSONS_MD_PATH, REPO_ROOT, SANDBOX_LEASE_DIR, STATE_DB_PATH, } from './paths.js';
+import { DOTENV_PATH, LESSONS_MD_PATH, lessonsReadPath, REPO_ROOT, SANDBOX_LEASE_DIR, STATE_DB_PATH, } from './paths.js';
 import { diffPlans, livePlanTasks, resolveTaskId, validatePlan, } from './plan.js';
 import { runPlanQuorum } from './planQuorum.js';
 import { detectCurrentBranch, detectRepoRoot, evaluateCommand, loadGuardrailPolicy, } from './policy.js';
@@ -70,6 +71,7 @@ import { COMMANDS, flagSpecFor, helpText, isDocumented, positionalNames, usageFo
 import { applyBatch, pendingBatch } from './waivers.js';
 import { blocksAdmission, checkWaveBudget, } from './waveBudget.js';
 import { computeNextWave, liveWaveTasks } from './waveNext.js';
+import { initWorkRoot } from './workroot.js';
 import { createTaskWorktree, listStale, RESERVED_TASK_ID, removeTaskWorktree, taskBranchName, } from './worktree.js';
 function printJson(value) {
     process.stdout.write(`${JSON.stringify(value)}\n`);
@@ -212,10 +214,15 @@ const DEFAULT_JUDGE_BUDGET = { timeout_ms: 120_000, max_output_bytes: 262_144 };
  * reachable by typo.
  */
 function judgeBudgetFromFlags(flags) {
+    // No default for max_output_tokens: the ceiling is per model, and an unset
+    // field lets the provider's policy entry (crosscheck.yml max_tokens) or the
+    // model's own default apply.
+    const maxOutputTokens = boundedIntFlag(flags, 'max-output-tokens', { min: 1 });
     return {
         timeout_ms: boundedIntFlag(flags, 'timeout-ms', { min: 1 }) ?? DEFAULT_JUDGE_BUDGET.timeout_ms,
         max_output_bytes: boundedIntFlag(flags, 'max-output-bytes', { min: 1 }) ??
             DEFAULT_JUDGE_BUDGET.max_output_bytes,
+        ...(maxOutputTokens === undefined ? {} : { max_output_tokens: maxOutputTokens }),
     };
 }
 /**
@@ -874,7 +881,15 @@ async function main() {
         // Critique-only (planQuorum.ts module header): exit 0 means nothing
         // needs the operator (no trigger fired, or endorsed); exit 1 means the
         // operator must look (critiqued or escalated) before approving the plan.
-        const epicId = requireFlag(flags, 'epic');
+        //
+        // FD-45: the plan may arrive by path. plan.md critiques at step 4 and
+        // files plan-v<n>.json at step 6, so at the moment this verb runs the plan
+        // is a draft with no versioned file to read; `--plan` hands over the
+        // draft itself and `--epic` then defaults to the draft's own epic_id (an
+        // explicit `--epic` must agree -- runPlanQuorum refuses one that does
+        // not). Without `--plan` the verb reads the filed version as before.
+        const draft = flags.plan ? readJsonFile(flags.plan) : undefined;
+        const epicId = draft && flags.epic === undefined ? draft.epic_id : requireFlag(flags, 'epic');
         // Required for this verb, unlike the shared envelope where it defaults to
         // 1: a quorum is a critique of one specific plan version.
         requireFlag(flags, 'plan-version');
@@ -907,8 +922,21 @@ async function main() {
         // that names two different plans is worse than one that fails: reading it
         // back, neither number can be trusted. One read, one number.
         const version = ctx.planVersion;
-        const outcome = await runPlanQuorum({ epicId, version, ...(plannerConfidence !== undefined ? { plannerConfidence } : {}) }, ctx, eventOptsFromFlags(flags));
+        const outcome = await runPlanQuorum({
+            epicId,
+            version,
+            ...(draft ? { plan: draft } : {}),
+            ...(plannerConfidence !== undefined ? { plannerConfidence } : {}),
+            planOpts: planOptsFromFlags(flags),
+        }, ctx, eventOptsFromFlags(flags));
         printJson(outcome);
+        // FD-49: the outcome is a few rationales of several kB each, and the
+        // playbook reads it back more often than a terminal does. Same idiom as
+        // `lessons compile --out`: write it where told, still print it.
+        if (flags.out) {
+            mkdirSync(path.dirname(flags.out), { recursive: true });
+            writeFileSync(flags.out, `${JSON.stringify(outcome, null, 2)}\n`, 'utf8');
+        }
         return outcome.outcome === 'endorsed' ? 0 : 1;
     }
     if (namespace === 'plan' && action === 'ingest') {
@@ -1223,6 +1251,23 @@ async function main() {
         printJson(summary);
         return summary.exitCode;
     }
+    if (namespace === 'init') {
+        // The first command an operator who installed the package runs, and the
+        // only one that exists because installing is not cloning.
+        //
+        // A clone already IS the work root, so this does nothing there and says
+        // so. An install splits in two: the package under node_modules, which the
+        // next `npm i` replaces wholesale, and `.blacksmith/` in the operator's
+        // own repository, which it must not. This creates the second and copies
+        // the files meant to be edited into it — because an answer typed into a
+        // file inside node_modules survives exactly until the first upgrade.
+        const report = initWorkRoot(flags['work-root'] ? { workRoot: flags['work-root'] } : {});
+        printJson(report);
+        // A default that did not ship is a packaging defect, not an operator
+        // error: report it as red rather than leaving them to notice later that
+        // the questionnaire they were told to answer is not there.
+        return report.files.some((file) => file.status === 'missing-default') ? 1 : 0;
+    }
     if (namespace === 'new') {
         // `smith new <project> [--ui]` — action doubles as the positional
         // project name here (splitNamespaceAction), never a subcommand word.
@@ -2055,6 +2100,36 @@ async function main() {
         printJson({ sandboxes: listSandboxes(leaseDir) });
         return 0;
     }
+    // The worker-harness port. `sandbox` above governs what a judge may do once
+    // a turn is running; these two answer the question one step earlier — what
+    // runs the turn at all. Until now the answer was implicit in deployment: the
+    // orchestrator is a Claude Code session, so the only thing it could start
+    // was another one, and no dispatch anywhere recorded that.
+    //
+    // `plan` renders an invocation and returns it. It does not start it —
+    // architecture §18 rule 3: `smith` observes, and an observer that could
+    // dispatch would end up reading its own output back as evidence that a turn
+    // happened. The caller starts the process this prints.
+    //
+    // No `--policy` means the built-in policy, which is the single in-process
+    // harness this factory actually runs. There is no harness.yml to default to,
+    // on purpose: shipping one is the operator's call, not a side effect of
+    // adding the seam.
+    if (namespace === 'harness' && action === 'list') {
+        printJson(summarizeHarnesses({ policy: loadHarnessPolicy(flags.policy) }));
+        return 0;
+    }
+    if (namespace === 'harness' && action === 'plan') {
+        const invocation = planWorkerTurn({
+            harness: flags.harness,
+            role: requireFlag(flags, 'role'),
+            taskId: requireFlag(flags, 'task'),
+            promptFile: requireFlag(flags, 'prompt-file'),
+            worktree: flags.worktree ?? null,
+        }, { policy: loadHarnessPolicy(flags.policy) });
+        printJson(invocation);
+        return 0;
+    }
     if (namespace === 'stack' && (action === 'show' || action === 'check')) {
         // The install interview's answers, read back (`show`) and priced against
         // what factory/scaffold/ can actually build (`check`).
@@ -2192,11 +2267,18 @@ async function main() {
         // blocking the gate on a judge that had just handed in its evidence. One
         // close per role: a judge that splits its findings across two files still
         // owes one turn, and a second report against it would be a duplicate.
+        //
+        // FD-1 (csb-audit-1): `--grader` is the same hand-over for the grader. Its
+        // verdict document is not a findings list, so until `judge report` learned
+        // the shape the grader's turn stayed open with its verdict on the command
+        // line, and the gate blocked on the judge it was about to read.
         const evidenceGiven = evidenceSources(args);
-        if (evidenceGiven.length > 0) {
+        const graderGiven = flags.grader ? [{ foundBy: 'grader', file: flags.grader }] : [];
+        const handedIn = [...evidenceGiven, ...graderGiven];
+        if (handedIn.length > 0) {
             const turns = await readJudgeTurns(taskId, ctx, eventOptsFromFlags(flags));
             const closed = new Set();
-            for (const { foundBy, file } of evidenceGiven) {
+            for (const { foundBy, file } of handedIn) {
                 if (closed.has(foundBy))
                     continue;
                 if (!turns.some((t) => t.role === foundBy && !t.reported))
@@ -2314,7 +2396,7 @@ async function main() {
         // a different number, and the half it drops is the earlier one — the half
         // that holds the first occurrence every repeat is counted against.
         const events = await readLineageEvents(sessionId, eventOptsFromFlags(flags));
-        const lessons = parseLessons(readFileSync(flags.lessons ?? LESSONS_MD_PATH, 'utf8'));
+        const lessons = parseLessons(readFileSync(flags.lessons ?? lessonsReadPath(), 'utf8'));
         const report = checkSameMistakeKpi(events, lessons, { sessionId });
         printJson(report);
         return report.ok ? 0 : 1;
@@ -2780,7 +2862,13 @@ async function main() {
         const { lessonsPage } = await import('./db/queries.js');
         const { compileLessons } = await import('./lessons.js');
         const dbPath = flags.db ?? STATE_DB_PATH;
+        // The operator's copy, not the package's: under an install the shipped one
+        // lives in node_modules, which the next `npm i` replaces wholesale. mkdir
+        // because nothing has necessarily written under factory/ in the work root
+        // before -- `smith init` seeds the two files the operator edits by hand,
+        // and this one is not among them.
         const outPath = flags.out ?? LESSONS_MD_PATH;
+        mkdirSync(path.dirname(outPath), { recursive: true });
         const handle = openDb(dbPath);
         try {
             const scope = flags.session ? { sessionId: flags.session } : {};
@@ -2832,7 +2920,7 @@ async function main() {
         // question is whether an entry has EVER fired, and a session-scoped read
         // answers "not in this half of the epic" while printing `retire`.
         const events = await readLineageEvents(sessionId, eventOptsFromFlags(flags));
-        const lessons = parseLessons(readFileSync(flags.lessons ?? LESSONS_MD_PATH, 'utf8'));
+        const lessons = parseLessons(readFileSync(flags.lessons ?? lessonsReadPath(), 'utf8'));
         const report = auditLessons(events, lessons, { sessionId });
         printJson(report);
         return report.ok ? 0 : 1;
@@ -3022,6 +3110,17 @@ async function main() {
         // Node stack trace on stdout with no error.code, the one shape every other
         // error from this CLI has.
         const port = boundedIntFlag(flags, 'port', { min: 1, max: 65535 }) ?? 4680;
+        // A fixed clock for screenshot harnesses; never for operators. The server
+        // now decides time-dependent facts itself (a live agent is *working* only
+        // within DEFAULT_STALE_HOURS of its dispatch), and ui/e2e pins the browser
+        // clock to one fixture instant — a pinned page over an unpinned server
+        // would draw every fixture agent as stalled. Unset, every request reads
+        // the wall clock (AppOpts.nowIso). Validated here, before the import, for
+        // the same reason --port is: a typo should cost a message, not a build.
+        const nowIso = flags['now-iso'];
+        if (nowIso !== undefined && Number.isNaN(Date.parse(nowIso))) {
+            throw new SmithError('ui.invalid-now', `--now-iso must be an ISO-8601 timestamp Date.parse can read, got "${nowIso}".`, { flag: 'now-iso', value: nowIso });
+        }
         // ui/server is a separate TS project (ui/server/tsconfig.json) built to
         // ui/server/dist/index.js — dynamically imported here (via a computed,
         // non-literal specifier, so tsc never tries to fold it into THIS
@@ -3058,6 +3157,7 @@ async function main() {
             ...(stateDir ? { stateDir } : {}),
             ...(roadmapPath ? { roadmapPath } : {}),
             ...(specsDir ? { specsDir } : {}),
+            ...(nowIso !== undefined ? { nowIso } : {}),
         });
         return 0;
     }

package/factory/orchestrator/dist/crosscheck.js

@@ -151,6 +151,14 @@ function quorumNumber(field, value) {
     }
     return value;
 }
+/** A token count: `quorumNumber` plus "whole and above zero", which is what a provider accepts as max_tokens. */
+function positiveInteger(field, value) {
+    const n = quorumNumber(field, value);
+    if (!Number.isInteger(n) || n < 1) {
+        throw new CrosscheckError('crosscheck.invalid-policy', `crosscheck.yml ${field} must be a positive integer; got ${JSON.stringify(value)}.`, { field, value });
+    }
+    return n;
+}
 function quorumBoolean(field, value) {
     if (typeof value !== 'boolean') {
         throw new CrosscheckError('crosscheck.invalid-policy', `crosscheck.yml ${field} must be true or false; got ${JSON.stringify(value)}. This file is YAML 1.2, where no/off/yes/on are strings, and a non-empty string is truthy. On an external provider's enabled the one other legal value is auto, unquoted and lowercase, which resolves against that provider's precondition on the box reading the file. ${DECIDES_DIFFERENTLY}`, { field, value });
@@ -277,6 +285,9 @@ function parseProvider(name, raw) {
             model: quorumString(`providers.${name}.model`, raw.model),
             apiKeyEnv,
             responseFormatJsonObject: quorumBoolean(`providers.${name}.response_format_json_object`, raw.response_format_json_object ?? true),
+            ...(raw.max_tokens === undefined
+                ? {}
+                : { maxTokens: positiveInteger(`providers.${name}.max_tokens`, raw.max_tokens) }),
         };
     }
     throw new CrosscheckError('crosscheck.invalid-provider', `Provider "${name}" is not kind: native and has no recognized transport (got "${String(raw.transport)}").`, { provider: name, transport: raw.transport });

package/factory/orchestrator/dist/daemon.js

@@ -76,11 +76,25 @@ export function inspectSession(sessionId, events, opts = {}) {
     const schedulerPolicy = opts.schedulerPolicy ?? loadSchedulerPolicy();
     const staleHours = opts.staleHours ?? DEFAULT_STALE_HOURS;
     const findings = [];
+    // A closed epic's bill is final. `checkBudgetAlarm` still prices it, and
+    // `smith budget alarm` still prints it, but "at-risk" or "unverifiable"
+    // there warns about spend that cannot happen, and the daemon would raise
+    // the same line every tick until the log is archived.
+    const closedEpics = new Set();
+    for (const { record } of events) {
+        if (record.event_type !== 'epic-closed')
+            continue;
+        const epicId = record.payload.epic_id;
+        if (typeof epicId === 'string')
+            closedEpics.add(epicId);
+    }
     const budget = checkBudgetAlarm(events, budgetPolicy, { sessionId });
     for (const epic of budget.epics) {
         // `under` is the only status that is an answer rather than a question.
         if (epic.status === 'under')
             continue;
+        if (closedEpics.has(epic.epicId))
+            continue;
         findings.push({
             kind: 'budget',
             severity: epic.status === 'unverifiable' ? 'info' : 'attention',