@juzser/blacksmith 0.4.0 → 0.5.0

package/factory/orchestrator/dist/cli.js

@@ -15,7 +15,8 @@
 // nothing at runtime. `test/cliBoot.test.ts` reads the built graph and fails if
 // the database layer creeps back into it.
 import { execFileSync, spawn } from 'node:child_process';
-import { mkdirSync, openSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, openSync, readFileSync, realpathSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { resetAgentMaxTurns, syncAgentMaxTurns } from './agentsSync.js';
@@ -24,20 +25,25 @@ import { closeAudit, consolidateAudit, cutAudit, decideAudit, openAudit, recordA
 import { checkBudgetAlarm } from './budgetAlarm.js';
 import { budgetEnvOverrides, loadBudgetPolicy } from './budgets.js';
 import { collectCommittedChanges, loadWorktreePolicy, postRunCheck, readClaimList, validateWave, writeRootCheck, } from './claims.js';
+import { warnIfLegacyName } from './cliName.js';
 import { collectCoverageEvidence } from './coverage.js';
 import { loadCrosscheckPolicy } from './crosscheck.js';
 import { independentFinderRequest, reconcile, runIndependentFinder, } from './crossFinding.js';
+import { formatDeclaredArtifactLine } from './declaredArtifactLine.js';
 import { checkDelegationGrants, checkDelegationLog, loadDelegationPolicy } from './delegation.js';
 import { checkDispatchAsymmetry } from './dispatchAudit.js';
 import { lintDispatchPrompt } from './dispatchLint.js';
 import { loadDotEnv } from './dotenv.js';
 import { loadEffortPolicy, resolveEffort } from './effort.js';
+import { budgetPolicyForPlan, epicBudgetPolicies } from './epicBudget.js';
 import { ISSUE_CANDIDATE_EVENT_TYPES } from './errorIssues.js';
 import { SmithError } from './errors.js';
 import { checkEscalationLadder } from './escalation.js';
 import { appendEvent, filterEvents, followEvents, listSessionIds, mergeSessionLogs, readEvents, readLineageEvents, requireSession, sessionTree, startSession, tailEvents, } from './events.js';
+import { listPendingFeedback, recordFeedback, resolveFeedback, } from './feedback.js';
 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 { runGit } from './git.js';
 import { recordGoalCheck, resolveEpicGoal } from './goalCheck.js';
 import { loadHarnessPolicy, planWorkerTurn, summarizeHarnesses, } from './harness.js';
 import { decideHookPayload } from './hookDecision.js';
@@ -46,13 +52,15 @@ import { collectExportDiffs, exportImpact, waveImpact } from './impact.js';
 import { integrationHeadSha, runIntegrationCheck } from './integration.js';
 import { previewOutcomes, reportErrors } from './issueReporter.js';
 import { judgePreflight } from './judgePreflight.js';
-import { outstandingJudges, readJudgeTurns, recordJudgeDispatch, recordJudgeReport, } from './judges.js';
+import { isJudgeKind, JudgeError, outstandingJudges, readJudgeArtifact, readJudgeTurns, recordJudgeDispatch, recordJudgeReport, uiuxDeviationsToEvidence, } from './judges.js';
 import { addMcpSurface, resolveMcpSurface, runMcpCheck } from './mcp.js';
-import { DOTENV_PATH, LESSONS_MD_PATH, lessonsReadPath, REPO_ROOT, SANDBOX_LEASE_DIR, STATE_DB_PATH, } from './paths.js';
-import { bareTaskId, diffPlans, livePlanTasks, planProjectResolverForTaskRef, planSelfFallbackForTaskRef, resolveTaskId, validatePlan, } from './plan.js';
+import { DOTENV_PATH, LESSONS_MD_PATH, lessonsReadPath, REPO_ROOT, SANDBOX_LEASE_DIR, STATE_DB_PATH, WORK_ROOT, } from './paths.js';
+import { diffPlans, impliedSpecsDir, isUiAffecting, latestPlanVersion, livePlanTasks, liveSpec, loadPlan, planProjectResolverForTaskRef, planSelfFallbackForTaskRef, resolveTaskId, validatePlan, } from './plan.js';
 import { runPlanQuorum } from './planQuorum.js';
 import { detectCurrentBranch, detectRepoRoot, evaluateCommand, loadGuardrailPolicy, } from './policy.js';
 import { factoryProjects } from './projects.js';
+import { captureContext, capturePrompt } from './promptCapture.js';
+import { importTranscript } from './promptImport.js';
 import { recordUserPrompt } from './prompts.js';
 import { checkBrief, wrapIngested } from './provenance.js';
 import { runJudge } from './providers/index.js';
@@ -65,20 +73,22 @@ import { activeSandboxFor, closeSandbox, listSandboxes, openSandbox, } from './s
 import { registerProjectInRoadmap, scaffoldProject } from './scaffold.js';
 import { loadSensitivePathsPolicy, securityTriggers, } from './security.js';
 import { parseLessons } from './severity.js';
-import { amendPlan, recordSpecReview, taskSuccessors } from './spec.js';
+import { amendPlan, recordSpecReview, successorChainPath, taskSuccessors } from './spec.js';
 import { approveSpecChange, listSpecChanges, proposeSpecChange, rejectSpecChange, } from './specChange.js';
 import { checkStack, loadStackAnswers } from './stack.js';
 import { buildSymbolGraph, collectSources } from './symbols.js';
-import { emitEdgesRecorded, emitTasksAdded, emitWaveAdmitted, readAddedTasks, } from './taskEvents.js';
+import { emitEdgesRecorded, emitTasksAdded, emitWaveAdmitted, planIngestGaps, readAddedTasks, unadmissibleTasks, } from './taskEvents.js';
+import { epicOfTaskId } from './taskId.js';
+import { CLOSED_TO_FURTHER_WORK } from './taskStatus.js';
 import { loadTaxonomy } from './taxonomy.js';
 import { checkTesterIsolation } from './testerAudit.js';
 import { assertSelectableTestCmd } from './testSelect.js';
 import { COMMANDS, flagSpecFor, helpText, isDocumented, positionalNames, usageFor, usageLine, usageText, } from './usage.js';
-import { applyBatch, pendingBatch } from './waivers.js';
+import { applyBatch, approveTaskWaiver, 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';
+import { createTaskWorktree, epicBranchPrefix, integrationBranchName, listStale, RESERVED_TASK_ID, removeTaskWorktree, taskBranchExists, taskBranchName, } from './worktree.js';
 function printJson(value) {
     process.stdout.write(`${JSON.stringify(value)}\n`);
 }
@@ -96,6 +106,38 @@ function readJsonFile(filePath) {
  * at the point the file is read, rather than let a gate run act on either.
  */
 const MAX_CHECK_TIMEOUT_MS = 2_147_483_647;
+/**
+ * `--findings <file>`'s intake, both places it's read (`findings raise`,
+ * `gate run`). The file is a pre-minted `RaiseFindingInput[]` (`{finding,
+ * filePath}`) — a replay, a fixture, a cross-check re-run — not the
+ * `FindingEvidence[]` (`{file_path, finding_category, ...}`, snake_case) a
+ * judge artifact actually holds, the shape `--evidence` expects. Reading it
+ * unvalidated used to crash deep inside routing: `normalizeRepoPath` reads
+ * `filePath` straight off the item, so a judge artifact's `undefined`
+ * `filePath` threw a raw TypeError (#285) instead of naming what was wrong.
+ */
+function readFindingsInputFile(filePath) {
+    const items = readJsonFile(filePath);
+    if (!Array.isArray(items)) {
+        throw new SmithError('cli.invalid-flag', `--findings ${filePath} must be a JSON array of {finding, filePath} items, got ${typeof items}.`, { flag: 'findings', file: filePath });
+    }
+    items.forEach((item, index) => {
+        const record = (item && typeof item === 'object' ? item : {});
+        const looksLikeEvidence = typeof record.file_path === 'string' &&
+            typeof record.finding_category === 'string' &&
+            record.finding === undefined;
+        if (looksLikeEvidence) {
+            throw new SmithError('cli.invalid-flag', `--findings ${filePath} item ${index} looks like a judge artifact (FindingEvidence: file_path/finding_category), not a raised finding ({finding, filePath}). Use --evidence <file> --found-by <role> instead.`, { flag: 'findings', file: filePath, index });
+        }
+        if (typeof record.filePath !== 'string') {
+            throw new SmithError('cli.invalid-flag', `--findings ${filePath} item ${index} is missing a string "filePath".`, { flag: 'findings', file: filePath, index, field: 'filePath' });
+        }
+        if (record.finding === null || typeof record.finding !== 'object') {
+            throw new SmithError('cli.invalid-flag', `--findings ${filePath} item ${index} is missing a "finding" object.`, { flag: 'findings', file: filePath, index, field: 'finding' });
+        }
+    });
+    return items;
+}
 function readChecksFile(filePath) {
     const checks = readJsonFile(filePath);
     for (const check of checks) {
@@ -166,6 +208,9 @@ function declaredWaveBudgets(plan, taskIds, policy) {
 function admissionBudget(check, rationale) {
     return {
         status: check.status,
+        // Threaded from the policy the cap came from, never re-resolved here: a
+        // second resolution is a second answer that can drift from the cap's.
+        tier: check.tier,
         cap_tokens: check.capTokens,
         projected_tokens: check.projectedTokens,
         wave_tokens: check.waveTokens,
@@ -181,23 +226,41 @@ function requireFlag(flags, name) {
     return value;
 }
 /**
- * requireFlag for a flag that must parse as a number, so `--input-tokens abc`
- * is named here rather than travelling as NaN into a token_usage the schema
- * then rejects for the wrong reason.
+ * Resolves the project directory an OPTIONAL --project reads its
+ * `.blacksmith/crosscheck.yml` overlay from, for the verbs where --project
+ * is not required outright (unlike `epic verdict`/`epic close`, D-42/P9-26).
+ * --project wins when given; otherwise, when a --worktree is present, its
+ * main checkout is derived, because a task worktree is a git-worktree
+ * SIBLING of the project rather than a child (`.wt/<project>/<task>`, per
+ * `taskWorktreeDir()`), so `path.dirname()` cannot recover it -- only git
+ * knows the common dir a worktree branches off of.
+ *
+ * Returns undefined when neither flag is present or the worktree is not a
+ * git checkout yet, which is deliberate: `loadCrosscheckPolicy()` already
+ * treats an absent projectDir as "no overlay", so callers that spread this
+ * in conditionally keep the env+shipped-policy behaviour unchanged rather
+ * than regressing every call site that has no project to give.
  */
-function requireIntFlag(flags, name) {
-    const raw = requireFlag(flags, name);
-    const value = Number(raw);
-    if (!Number.isInteger(value)) {
-        throw new SmithError('cli.non-numeric-flag', `--${name} must be an integer, got "${raw}".`, {
-            flag: name,
-            value: raw,
-        });
+function projectDirFromFlags(flags, worktreeFlagName = 'worktree') {
+    if (flags.project)
+        return flags.project;
+    const worktreeDir = flags[worktreeFlagName];
+    if (!worktreeDir)
+        return undefined;
+    try {
+        const gitCommonDir = runGit(worktreeDir, ['rev-parse', '--git-common-dir']);
+        return path.dirname(path.resolve(worktreeDir, gitCommonDir));
+    }
+    catch {
+        return undefined;
     }
-    return value;
 }
 /**
- * requireIntFlag's optional twin, for a count that also has to be in range.
+ * A flag that must parse as a whole number in range, but may also be absent
+ * entirely — the both-or-neither shape `--input-tokens`/`--output-tokens`
+ * need (#220): a dispatcher with no API onto a subagent's token spend omits
+ * both rather than travelling a typo'd or invented number as NaN into a
+ * token_usage the schema then rejects for the wrong reason.
  *
  * D-210. `event tail --n` read its count with a bare Number.parseInt and
  * checked nothing, which fails in both directions at once: `--n abc` is NaN,
@@ -435,6 +498,70 @@ async function issueInputs(flags) {
 function planOptsFromFlags(flags) {
     return flags['specs-dir'] ? { specsDir: flags['specs-dir'] } : {};
 }
+/** `realpathSync`, falling back to the resolved lexical path when it fails. */
+function realOrResolved(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+/**
+ * `plan amend`'s own specs-dir default (#219) -- deliberately not
+ * `planOptsFromFlags`, whose silent fallback to `SPECS_ACTIVE_DIR` is a
+ * documented contract several other commands rely on for a READ (see its
+ * own doc comment, and `issueInputs`'s). Amend is a WRITE: the version it
+ * cuts is filed at `<specsDir>/<epicId>/plan-vN.json`, so silently
+ * defaulting to this checkout's own specs tree when `--plan` already lives
+ * somewhere else does not merely read the wrong file, it plants the new
+ * version in the wrong one -- beside no other version of the plan it just
+ * amended.
+ *
+ * Derived from `--plan`'s own directory instead (`impliedSpecsDir`), when
+ * that path already sits in the shape a plan file lives in. An explicit
+ * `--specs-dir` still wins outright when it agrees with that; when it does
+ * not, the two flags are answering a question this command cannot silently
+ * referee, so it refuses rather than guessing which one the caller meant.
+ */
+function amendSpecsDirOpts(planPath, plan, flags) {
+    const explicit = flags['specs-dir'];
+    const implied = impliedSpecsDir(planPath, plan.epic_id);
+    if (explicit === undefined)
+        return implied === null ? {} : { specsDir: implied };
+    // Compared on disk, not lexically: the same tree reached through a
+    // symlink (macOS /tmp -> /private/tmp) is agreement, not a mismatch.
+    if (implied !== null && realOrResolved(explicit) !== realOrResolved(implied)) {
+        throw new SmithError('cli.specs-dir-mismatch', `--specs-dir "${explicit}" disagrees with the directory --plan "${planPath}" already lives in: that plan's own layout says its specs dir is "${implied}". Drop --specs-dir to amend in place, point it at "${implied}", or move --plan under the tree --specs-dir names.`, { plan: planPath, epicId: plan.epic_id, specsDir: explicit, impliedSpecsDir: implied });
+    }
+    return { specsDir: explicit };
+}
+/**
+ * The tier `epic verdict`/`epic close` actually run at, resolved the same way
+ * `effort show` resolves it (security floor included) so the two commands
+ * can never disagree about what tier an epic is on. Read-only, best-effort on
+ * the plan the way `resolvePlanRoster` (epic.ts) is: a plan that fails to
+ * load is "unreadable", not a crash, and `resolveEffort` already treats an
+ * absent plan as "floor not evaluated" rather than "floor clean" (see
+ * `EffortResolution.securityFloorEvaluated`).
+ */
+function resolveEpicEffort(epicId, flags) {
+    const planOpts = planOptsFromFlags(flags);
+    const version = latestPlanVersion(epicId, planOpts);
+    let plan = null;
+    if (version !== null) {
+        try {
+            plan = loadPlan(epicId, version, planOpts);
+        }
+        catch {
+            plan = null;
+        }
+    }
+    const policy = loadEffortPolicy(flags.policy);
+    const securityPolicy = loadCrosscheckPolicy(flags.crosscheck).planQuorum;
+    const resolution = resolveEffort(policy, securityPolicy, plan ? { plan } : {});
+    return { tier: resolution.effective, closingSpecReview: resolution.profile.closingSpecReview };
+}
 /**
  * The one reader for every flag usage.ts documents as `<iso>` (D-209).
  *
@@ -491,10 +618,10 @@ function isoDateFlag(flags, name) {
  * `event append` writes.
  *
  * `--roadmap-path` belongs here too: both verbs rebuild the whole milestones
- * table from a roadmap file, and unset it falls back to black-smith's own
+ * table from a roadmap file, and unset it falls back to blacksmith's own
  * factory/specs/roadmap.md. Dropping the flag therefore did not mean "keep the
  * existing milestones" — it meant "replace this db's milestones with
- * black-smith's", which is a silent data swap for any db but this repo's.
+ * blacksmith's", which is a silent data swap for any db but this repo's.
  *
  * `--specs-dir` travels for the same reason and is the same flag `plan`
  * already takes: the projector reads an epic's plan file to answer what
@@ -662,6 +789,25 @@ function mintFromEvidence(args, taskId, scope = {}) {
         ...scope,
     }));
 }
+/**
+ * Mint a uiux visual pass's deviations under the `uiux` judge. `--uiux-visual`
+ * hands over the whole Result document (bs-uiux.md's output contract), not a
+ * findings-evidence array, so this reads `structured_output.deviations` the
+ * same way `readJudgeArtifact`'s uiux branch does (judges.ts) before handing
+ * the mapped evidence to the same `mintFindings` every other judge goes
+ * through.
+ */
+function mintFromUiuxVisual(filePath, taskId) {
+    // Reuse `readJudgeArtifact`'s uiux visual-branch validation (judges.ts)
+    // rather than re-checking the shape here: a document missing
+    // `structured_output.deviations`, or one where it is not an array, must
+    // raise `judges.artifact-invalid-evidence` instead of silently minting
+    // nothing and letting the gate pass on a wrong-shaped document (S2).
+    readJudgeArtifact(filePath, 'uiux', taskId, 'visual');
+    const document = readJsonFile(filePath);
+    const deviations = document.structured_output?.deviations ?? [];
+    return mintFindings(uiuxDeviationsToEvidence(deviations), { taskId, foundBy: 'uiux' });
+}
 /**
  * The gated task's declared caps, read off the same `--plan` the gate already
  * takes for ownership (D-41/P9-24) — no new flag, because a budget the gate can
@@ -686,9 +832,33 @@ function budgetFromFlags(flags, taskId) {
             return undefined;
         throw err;
     }
-    const budget = plan.tasks.find((t) => t.task_id === resolved)?.budget;
+    const budget = liveSpec(plan, resolved)?.budget;
     return typeof budget === 'object' && budget !== null ? budget : undefined;
 }
+/**
+ * The task's `ui_affecting` flag off `--plan` (U2 D3/D6), for the gate's uiux
+ * stage: `undefined` means no `--plan` was given at all, so the stage cannot
+ * resolve the flag either way and records "unverifiable" rather than guess
+ * (D6). A `--plan` that does not name the task, same as `budgetFromFlags`,
+ * is read as `undefined` too — a follow-up task no plan version has been cut
+ * for yet is not grounds to force the uiux stage one way or the other.
+ */
+function uiAffectingFromFlags(flags, taskId) {
+    if (!flags.plan)
+        return undefined;
+    const plan = readJsonFile(flags.plan);
+    let resolved;
+    try {
+        resolved = resolveTaskId(plan, taskId);
+    }
+    catch (err) {
+        if (err instanceof SmithError && err.code === 'plan.unknown-task')
+            return undefined;
+        throw err;
+    }
+    const spec = liveSpec(plan, resolved);
+    return spec ? isUiAffecting(spec) : undefined;
+}
 /**
  * The claim globs one dispatch is scoped to, read off the plan (P9-2). Only
  * claim-path-scoped lessons use them, so a role that declares no such scope
@@ -700,7 +870,21 @@ function claimsForDispatch(flags) {
     if (!flags.plan)
         return [];
     const taskId = requireFlag(flags, 'task');
-    const owner = ownershipFromPlan(readJsonFile(flags.plan)).find((t) => t.task_id === taskId);
+    const plan = readJsonFile(flags.plan);
+    let resolved;
+    try {
+        resolved = resolveTaskId(plan, taskId);
+    }
+    catch (err) {
+        if (err instanceof SmithError && err.code === 'plan.unknown-task') {
+            throw new SmithError('cli.task-not-in-plan', `No task ${taskId} in ${flags.plan}.`, {
+                taskId,
+                plan: flags.plan,
+            });
+        }
+        throw err;
+    }
+    const owner = ownershipFromPlan(plan).find((t) => t.task_id === resolved);
     if (!owner) {
         throw new SmithError('cli.task-not-in-plan', `No task ${taskId} in ${flags.plan}.`, {
             taskId,
@@ -724,7 +908,21 @@ function caseForDispatch(flags) {
     if (!flags.plan)
         return '';
     const taskId = requireFlag(flags, 'task');
-    const task = readJsonFile(flags.plan).tasks.find((t) => t.task_id === taskId);
+    const plan = readJsonFile(flags.plan);
+    let resolved;
+    try {
+        resolved = resolveTaskId(plan, taskId);
+    }
+    catch (err) {
+        if (err instanceof SmithError && err.code === 'plan.unknown-task') {
+            throw new SmithError('cli.task-not-in-plan', `No task ${taskId} in ${flags.plan}.`, {
+                taskId,
+                plan: flags.plan,
+            });
+        }
+        throw err;
+    }
+    const task = liveSpec(plan, resolved);
     if (!task) {
         throw new SmithError('cli.task-not-in-plan', `No task ${taskId} in ${flags.plan}.`, {
             taskId,
@@ -782,6 +980,47 @@ function splitNamespaceAction(argv) {
     }
     return { namespace, action: undefined, rest: restAll };
 }
+/**
+ * #250. `wave check --session` admits against the log, so before it admits
+ * it asks the log three things, in order: was this plan version ingested,
+ * does every id have a task row, and is every row still live. Each refusal is
+ * thrown before anything is written, so a refused wave leaves no
+ * `wave-admitted` behind. "Live" excludes only CLOSED_TO_FURTHER_WORK: a
+ * `failed` or `escalated` task is held by an operator and is re-admitted by
+ * the escalation ladder, so it passes.
+ *
+ * The no-row refusal is a defensive invariant, not a path the CLI reaches
+ * today: past an ingest every plan id has a row, and an id neither the plan
+ * nor the log knows is refused earlier, by the id resolution.
+ *
+ * Order matters for the answer the operator reads: an un-ingested plan makes
+ * every row question moot (the rows are missing or stale because the ingest
+ * is), so it is asked first and names the one command that fixes it.
+ */
+async function refuseUnadmissibleTasks(plan, taskIds, flags) {
+    const sessionId = flags.session;
+    const eventOpts = eventOptsFromFlags(flags);
+    const gaps = await planIngestGaps(plan, { sessionId }, eventOpts);
+    if (gaps.length > 0) {
+        const pending = [...new Set(gaps.map((g) => g.taskId))];
+        throw new SmithError('cli.plan-not-ingested', `Plan "${plan.epic_id}" v${plan.version} has not been ingested into session "${sessionId}" (${pending.length} task(s) pending): run \`bs plan ingest\` on it first, then re-check.`, { epic: plan.epic_id, version: plan.version, session: sessionId, pending });
+    }
+    // Imported here for the reason nextWaveInputFrom gives: the db layer stays
+    // out of the graph every `smith` invocation loads.
+    const { foldTasks, taskIdCanonicalizer } = await import('./db/projector.js');
+    const events = await readLineageEvents(sessionId, eventOpts);
+    const statusOf = new Map();
+    for (const row of foldTasks(events))
+        statusOf.set(row.taskId, row.taskStatus);
+    const canonical = taskIdCanonicalizer(events);
+    const { missing, terminal } = unadmissibleTasks(taskIds.map(canonical), statusOf);
+    if (missing.length > 0) {
+        throw new SmithError('plan.unknown-task', `Session "${sessionId}" has no task row for ${missing.map((id) => `"${id}"`).join(', ')}: a wave is admitted against the log, and the log does not know ${missing.length === 1 ? 'this task' : 'these tasks'}.`, { session: sessionId, missing });
+    }
+    if (terminal.length > 0) {
+        throw new SmithError('cli.task-not-live', `Refusing to admit ${terminal.map((t) => `"${t.taskId}" (${t.taskStatus})`).join(', ')}: the work is over in session "${sessionId}". Drop ${terminal.length === 1 ? 'it' : 'them'} from the wave.`, { session: sessionId, tasks: terminal });
+    }
+}
 /**
  * Everything a wave computation reads about a plan: the plan itself with the
  * log's follow-ups merged in, the worktree policy, the import crossings
@@ -869,6 +1108,10 @@ async function nextWaveInputFrom(planFile, flags) {
     };
 }
 async function main() {
+    // bs-rename, operator decision 3: a no-op unless argv[1]'s basename is the
+    // deprecated `smith`, in which case it writes one line to stderr, never
+    // stdout -- stdout is parsed as JSON by playbooks.
+    warnIfLegacyName(process.argv[1], 'smith', 'bs');
     // Refuse an unsupported runtime before anything opens the database. The
     // native binding crashes lazily — `new Database()`, not import — so a check
     // here still runs, and a subcommand that happens to avoid SQLite must not
@@ -878,7 +1121,7 @@ async function main() {
     if (!runtime.supported) {
         // Prose on stderr so a human sees it even when stdout is piped into a
         // JSON parser; the structured form still goes to stdout for callers.
-        process.stderr.write(`smith: unsupported runtime\n${runtime.reason ?? ''}\n`);
+        process.stderr.write(`bs: unsupported runtime\n${runtime.reason ?? ''}\n`);
         printJson({ error: { code: 'unsupported-runtime', message: runtime.reason } });
         return 1;
     }
@@ -1023,7 +1266,25 @@ async function main() {
         // requirePositionals is what makes it true, and it runs first.
         const [planFile] = requirePositionals(positional, usageFor('plan validate'));
         const plan = readJsonFile(planFile);
-        const result = validatePlan(plan);
+        // Grandfathering (plan.ui-flag-missing, U2 S1 R2) needs the version this
+        // one amends. It is readable here only when the file sits where
+        // `impliedSpecsDir` expects a plan to sit (`<specsDir>/<epicId>/plan-vN.json`)
+        // and the previous version is actually on disk beside it; a validate run
+        // against a bare fixture or a file moved elsewhere gets no previous and
+        // validates without the exemption, same as before this change.
+        let previous;
+        if (plan.version > 1) {
+            const specsDir = impliedSpecsDir(planFile, plan.epic_id);
+            if (specsDir !== null) {
+                try {
+                    previous = loadPlan(plan.epic_id, plan.version - 1, { specsDir });
+                }
+                catch {
+                    // No readable previous version alongside this file.
+                }
+            }
+        }
+        const result = validatePlan(plan, previous ? { previous } : {});
         printJson(result);
         return result.valid ? 0 : 1;
     }
@@ -1085,6 +1346,13 @@ async function main() {
             ...(draft ? { plan: draft } : {}),
             ...(plannerConfidence !== undefined ? { plannerConfidence } : {}),
             planOpts: planOptsFromFlags(flags),
+            // Same reasoning as `epic verdict`/`epic close` (D-42/P9-26): an
+            // optional --project hands the quorum a project's
+            // .blacksmith/crosscheck.yml overlay (OpenRouter substitution/extra
+            // judges) rather than only the shipped policy. No worktree
+            // derivation here -- a plan critique has no task worktree to derive
+            // one from -- so an absent --project reads exactly as before.
+            crosscheck: { policy: loadCrosscheckPolicy(undefined, { projectDir: flags.project }) },
         }, ctx, eventOptsFromFlags(flags));
         printJson(outcome);
         // FD-49: the outcome is a few rationales of several kB each, and the
@@ -1107,7 +1375,12 @@ async function main() {
         const plan = readJsonFile(planFile);
         const ctx = eventContextFromFlags(flags);
         const opts = eventOptsFromFlags(flags);
-        const written = await emitTasksAdded(plan, ctx, opts);
+        // --project: an epic already integrating on `smith/<epic>/integration`
+        // (legacy continuity, worktree.ts's epicBranchPrefix) must have this
+        // v(n+1) ingest declare the same prefix `worktree create` will actually
+        // cut, not the plain `bs` default. Absent for a brand-new epic, which has
+        // no such branch to ask git about yet.
+        const written = await emitTasksAdded(plan, ctx, opts, flags.project);
         // D-254: the arrows, after the nodes. The plan declares a DAG and the
         // scheduler has always read it off the file, but nothing wrote it to the
         // log -- so the db's `edges` table was empty and every operator-facing
@@ -1124,6 +1397,11 @@ async function main() {
         // claims-and-edges only, so the input carries no crossings.
         const { computePlanParallelism } = await import('./waveSchedule.js');
         const parallelism = computePlanParallelism(plan, loadWorktreePolicy());
+        // The last event this call appended -- the edges, after the nodes, since
+        // emitEdgesRecorded runs after emitTasksAdded. A re-ingest that wrote
+        // neither (everything already on the log) appends nothing, so there is
+        // no id to print.
+        const lastEvent = edges.length > 0 ? edges[edges.length - 1] : written[written.length - 1];
         printJson({
             epic: plan.epic_id,
             version: plan.version,
@@ -1132,6 +1410,7 @@ async function main() {
             skipped: plan.tasks.length - added,
             edges: edges.length,
             parallelism,
+            ...(lastEvent ? { event_id: lastEvent.event_id } : {}),
         });
         return 0;
     }
@@ -1139,7 +1418,8 @@ async function main() {
     // to cut a version that cites no spec finding, so "the plan changed" is
     // always answerable with "which finding said it was wrong".
     if (namespace === 'plan' && action === 'amend') {
-        const plan = readJsonFile(requireFlag(flags, 'plan'));
+        const planPath = requireFlag(flags, 'plan');
+        const plan = readJsonFile(planPath);
         // Comma-split, not repeated: a finding id has no commas, and an amendment
         // routinely cites several at once.
         const findingIds = requireFlag(flags, 'findings')
@@ -1159,7 +1439,7 @@ async function main() {
             rationale: requireFlag(flags, 'rationale'),
             sites,
             ...(changes ? { changes } : {}),
-        }, eventContextFromFlags(flags), { ...eventOptsFromFlags(flags), ...planOptsFromFlags(flags) });
+        }, eventContextFromFlags(flags), { ...eventOptsFromFlags(flags), ...amendSpecsDirOpts(planPath, plan, flags) });
         // No no-op warning here any more. A pure carry-forward used to be legal
         // and merely suspicious — the shape a forgotten --changes takes — so the
         // CLI printed a warning and cut the version anyway. Since D-127 an
@@ -1180,6 +1460,11 @@ async function main() {
             // no task behind it is a deliberate call or a forgotten one.
             sitesUnclaimed: result.sitesUnclaimed,
             diff: result.diff,
+            // #221: an open finding this amendment's own objective text names but
+            // --findings does not cite -- surfaced the same way sitesUnclaimed is,
+            // a fact for the operator to read off the result rather than a guard.
+            warnings: result.warnings,
+            event_id: result.event_id,
         });
         return 0;
     }
@@ -1229,13 +1514,17 @@ async function main() {
     // sites. Approval supplies them from what the worker already recorded.
     if (namespace === 'plan' && action === 'approve') {
         const [proposalId] = requirePositionals(positional, usageFor('plan approve'));
-        const plan = readJsonFile(requireFlag(flags, 'plan'));
+        const planPath = requireFlag(flags, 'plan');
+        const plan = readJsonFile(planPath);
+        // #287: approval runs `plan amend` underneath, so it is the same write
+        // `amendSpecsDirOpts` was written for (#219), not the read
+        // `planOptsFromFlags` silently defaults for everyone else.
         const result = await approveSpecChange({
             proposalId,
             plan,
             decidedBy: requireFlag(flags, 'decided-by'),
             ...(flags.rationale ? { rationale: flags.rationale } : {}),
-        }, eventContextFromFlags(flags), { ...eventOptsFromFlags(flags), ...planOptsFromFlags(flags) });
+        }, eventContextFromFlags(flags), { ...eventOptsFromFlags(flags), ...amendSpecsDirOpts(planPath, plan, flags) });
         printJson({
             proposalId,
             epic: result.plan.epic_id,
@@ -1245,6 +1534,7 @@ async function main() {
             sites: result.proposal.sites,
             sitesUnclaimed: result.sitesUnclaimed,
             diff: result.diff,
+            event_id: result.event_id,
         });
         return 0;
     }
@@ -1274,7 +1564,7 @@ async function main() {
         // at. resolveTaskId turns that silence into a named error.
         const typedIds = positional.slice(1);
         if (typedIds.length === 0) {
-            throw new SmithError('cli.empty-wave', 'Usage: smith wave check <plan.json> <task-id>... — a wave with no tasks is not a wave.', { plan: plan.epic_id });
+            throw new SmithError('cli.empty-wave', 'Usage: bs wave check <plan.json> <task-id>... — a wave with no tasks is not a wave.', { plan: plan.epic_id });
         }
         // D-48/P9-31: a follow-up task exists only in the log, so the log is the
         // second register an id may be found in — and the place its claims come
@@ -1284,6 +1574,8 @@ async function main() {
             ? await readAddedTasks({ sessionId: flags.session }, eventOptsFromFlags(flags))
             : [];
         const taskIds = typedIds.map((typed) => resolveTaskId(plan, typed, logged.map((t) => t.taskId)));
+        if (flags.session)
+            await refuseUnadmissibleTasks(plan, taskIds, flags);
         // Neither register is narrowed on the way in. `?? []` used to stand here
         // and on the line above, and it fires on a missing claims field but not on
         // a claims field holding the wrong thing: a plan writing `"claims":
@@ -1351,7 +1643,9 @@ async function main() {
                 // the sum of every session that worked on it.
                 await readLineageEvents(flags.session, eventOptsFromFlags(flags))
             : [];
-        const budgetPolicy = loadBudgetPolicy(flags['budget-policy']);
+        // Sized for the tier this epic runs at: the plan's own `effort` after
+        // effort.yml's security floor, else effort.yml's default_tier.
+        const budgetPolicy = budgetPolicyForPlan(plan, { policyFile: flags['budget-policy'] });
         const budget = checkWaveBudget(budgetEvents, budgetPolicy, declaredWaveBudgets(plan, taskIds, budgetPolicy), { sessionId: flags.session ?? '', epicId: plan.epic_id });
         const overridden = rationale !== '' && blocksAdmission(budget.status);
         const blocked = blocksAdmission(budget.status) && !overridden;
@@ -1365,7 +1659,7 @@ async function main() {
         }
         // Names only, and only when some differ from budgets.yml: which caps came
         // from the box's env rather than the file.
-        const envOverrides = budgetEnvOverrides(loadBudgetPolicy(flags['budget-policy'], {}));
+        const envOverrides = budgetEnvOverrides(loadBudgetPolicy(flags['budget-policy'], {}, budgetPolicy.tier));
         printJson({
             ...result,
             symbolImpact,
@@ -1563,7 +1857,8 @@ async function main() {
     // the whole safety property: an operator can read what the policy would
     // have let run, and argue with it, before any of it moves. So this appends
     // no event, writes no worktree and starts no agent -- exactly the daemon's
-    // invariant, held by the command a person types too.
+    // invariant, held by the command a person types too. No event_id in the
+    // printed JSON either, for the same reason: there is never one to name.
     if (namespace === 'scheduler' && action === 'admit') {
         const { computeProposals, loadSchedulerPolicy } = await import('./scheduler.js');
         const { admitProposals } = await import('./autonomy.js');
@@ -1650,11 +1945,12 @@ async function main() {
             // plan on disk naming no project is this checkout's own epic, so it
             // reads as FACTORY_PROJECT rather than staying an unresolved null the
             // daemon would report as an unlabeled finding and the on/off switch
-            // for 'black-smith' would never get asked about. Split into strict
+            // for 'blacksmith' would never get asked about. Split into strict
             // (resolveProjectForTaskRef) and self-only (selfFallbackForTaskRef)
             // tiers so a session's own stamp can ride between them (S2-c).
             resolveProjectForTaskRef: planProjectResolverForTaskRef(planOptsFromFlags(flags)),
             selfFallbackForTaskRef: planSelfFallbackForTaskRef(FACTORY_PROJECT, planOptsFromFlags(flags)),
+            planOpts: planOptsFromFlags(flags),
             ...(flags.db ? { dbPath: flags.db } : {}),
             ...(flags['no-db'] === 'true' ? { projectDb: false } : {}),
         };
@@ -1710,7 +2006,7 @@ async function main() {
             // Let acquireLock own the liveness question — one implementation of
             // "is that pid still there" rather than a second opinion here.
             throw new DaemonError('daemon.already-running', `A daemon (pid ${held.pid}, started ${held.startedAt}) already holds ${dir}. ` +
-                'Run `smith daemon stop` first, or `smith daemon status` to see what it last found.', { pid: held.pid, dir });
+                'Run `bs daemon stop` first, or `bs daemon status` to see what it last found.', { pid: held.pid, dir });
         }
         mkdirSync(dir, { recursive: true });
         // `ignore` would discard the one account of why a detached daemon died.
@@ -1801,11 +2097,32 @@ async function main() {
             const events = await readLineageEvents(sessionId, eventOptsFromFlags(flags));
             const successors = taskSuccessors(events, epic);
             const from = flags.from;
-            const expected = bareTaskId(epic, taskId);
-            const actual = successors.get(from) ?? successors.get(`${epic}/${from}`);
-            if (actual === undefined || bareTaskId(epic, actual) !== expected) {
+            // Walks the successor chain hop by hop (spec.ts's
+            // `successorChainPath`) rather than asking about the direct successor
+            // alone: a plan amended twice before the intermediate successor is
+            // ever cut still names `taskId` as `from`'s transitive successor, and
+            // the log is the register this guard is answerable to.
+            const chain = successorChainPath(epic, from, taskId, successors);
+            if (chain === undefined) {
                 throw new SmithError('worktree.not-a-successor', `${epic}/${taskId} is not logged as the successor of ${epic}/${from}; run \`plan propose\`/\`plan approve\` with a supersede pairing them first.`, { epic, taskId, from });
             }
+            // The log naming a chain is not enough: `createTaskWorktree` branches
+            // `taskId` directly off `from`'s own branch, so if some hop strictly
+            // between them was already cut as its own branch, skipping straight
+            // there would silently drop that hop's commits. `chain` is `from`'s
+            // own hops through `taskId` inclusive (spec.ts's `successorChainPath`
+            // doc comment); drop the last one (`taskId` itself, which never has a
+            // branch yet) and refuse on the intermediate hop closest to `taskId`
+            // if any of them do.
+            const intermediates = chain.slice(0, -1);
+            let cutIntermediate;
+            for (const hop of intermediates) {
+                if (taskBranchExists(projectDir, epic, hop))
+                    cutIntermediate = hop;
+            }
+            if (cutIntermediate !== undefined) {
+                throw new SmithError('worktree.chain-intermediate-cut', `${epic}/${taskId} cannot be cut --from ${epic}/${from}: ${epic}/${cutIntermediate} sits between them and already has its own branch (${taskBranchName(epic, cutIntermediate, epicBranchPrefix(projectDir, epic))}), so its commits would be silently dropped; rerun with --from ${cutIntermediate} instead.`, { epic, taskId, from, intermediate: cutIntermediate });
+            }
             printJson(createTaskWorktree(projectDir, epic, taskId, { from }));
             return 0;
         }
@@ -1885,6 +2202,110 @@ async function main() {
         printJson({ event_id: stored.event_id, record: stored.record });
         return 0;
     }
+    // The hook-driven sibling of `prompt record`: reads one UserPromptSubmit
+    // payload on stdin and files it where promptCapture.ts decides. The plugin
+    // reaches the same function through the lean `bs-prompt-hook` bin; this verb
+    // is the surface the CLI tests drive. It never fails a prompt, so every
+    // outcome is exit 0.
+    if (namespace === 'prompt' && action === 'capture') {
+        try {
+            const line = await capturePrompt(readFileSync(0, 'utf8'), captureContext(process.cwd(), process.env));
+            if (line !== null)
+                console.log(line);
+        }
+        catch {
+            // A capture that fails loses one record; the prompt itself goes through.
+        }
+        return 0;
+    }
+    // Backfill: replays a Claude Code transcript into the home prompt log the
+    // hook would have written (promptImport.ts). Unlike `capture` it is an
+    // explicit act, so a refusal is exit 1. --dry-run prints each event first.
+    if (namespace === 'prompt' && action === 'import') {
+        const { events, summary } = await importTranscript(requireFlag(flags, 'transcript'), captureContext(process.cwd(), process.env), { dryRun: flags['dry-run'] === 'true' });
+        if (flags['dry-run'] === 'true')
+            for (const event of events)
+                console.log(JSON.stringify(event));
+        console.log(JSON.stringify(summary));
+        return 0;
+    }
+    // The operator's mid-run comment on a task, from the dashboard or from
+    // GitHub, and its two readers/writers below (feedback.ts). This PR is the
+    // store and the CLI only; the dashboard form and the playbook that acts on
+    // `smith feedback pending`'s suggestion are later work.
+    if (namespace === 'feedback' && action === 'record') {
+        const taskId = requireFlag(flags, 'task');
+        const bodyFile = flags['body-file'];
+        const body = bodyFile !== undefined ? readFileSync(bodyFile, 'utf8') : flags.body;
+        if (body === undefined) {
+            throw new SmithError('cli.missing-flag', 'Missing --body or --body-file: operator feedback needs a body.', { flag: 'body' });
+        }
+        if (flags.kind !== undefined && flags.kind !== 'must-fix' && flags.kind !== 'nice-to-have') {
+            throw new SmithError('cli.invalid-flag', `--kind must be "must-fix" or "nice-to-have", got "${flags.kind}".`, { flag: 'kind', value: flags.kind });
+        }
+        if (flags.source !== undefined &&
+            flags.source !== 'dashboard' &&
+            flags.source !== 'github' &&
+            flags.source !== 'cli') {
+            throw new SmithError('cli.invalid-flag', `--source must be "dashboard", "github" or "cli", got "${flags.source}".`, { flag: 'source', value: flags.source });
+        }
+        const result = await recordFeedback({
+            taskId,
+            body,
+            kind: flags.kind,
+            source: flags.source,
+            externalId: flags['external-id'],
+            author: flags.author,
+        }, eventContextFromFlags(flags), eventOptsFromFlags(flags));
+        printJson({
+            event_id: result.event.event_id,
+            feedback_id: result.feedbackId,
+            deduped: result.deduped,
+        });
+        return 0;
+    }
+    if (namespace === 'feedback' && action === 'pending') {
+        const sessionId = requireFlag(flags, 'session');
+        const eventOpts = eventOptsFromFlags(flags);
+        requireSession(sessionId, eventOpts);
+        const taskId = flags.task;
+        const epic = flags.epic;
+        const pending = await listPendingFeedback(sessionId, { taskId }, eventOpts);
+        const scoped = epic === undefined ? pending : pending.filter((row) => epicOfTaskId(row.taskId) === epic);
+        // Kept out of the boot graph like every other db/projector.js call site
+        // (P9-2, test/cliBoot.test.ts): the module pulls in drizzle-orm, and
+        // `smith --help` should not pay for a database it never opens.
+        const { foldTasks } = await import('./db/projector.js');
+        const statuses = new Map(foldTasks(await readLineageEvents(sessionId, eventOpts)).map((t) => [t.taskId, t.taskStatus]));
+        const withAction = scoped.map((row) => ({
+            ...row,
+            // A task not yet closed to further work gets its comment bounced back
+            // to the coder still on it; one that already merged (or was superseded
+            // or waived) gets a follow-up task instead (taskStatus.ts's
+            // CLOSED_TO_FURTHER_WORK, the same question claims.ts's
+            // decideFindingAttribution answers for a finding).
+            suggestedAction: CLOSED_TO_FURTHER_WORK.has(statuses.get(row.taskId) ?? '')
+                ? 'follow-up'
+                : 'bounce',
+        }));
+        printJson({ sessionId, pending: withAction, count: withAction.length });
+        return 0;
+    }
+    if (namespace === 'feedback' && action === 'resolve') {
+        const feedbackId = requireFlag(flags, 'feedback');
+        const resolution = requireFlag(flags, 'resolution');
+        if (resolution !== 'bounced' && resolution !== 'follow-up' && resolution !== 'dismissed') {
+            throw new SmithError('cli.invalid-flag', `--resolution must be "bounced", "follow-up" or "dismissed", got "${resolution}".`, { flag: 'resolution', value: resolution });
+        }
+        const stored = await resolveFeedback({
+            feedbackId,
+            resolution: resolution,
+            note: flags.note,
+            followUpTaskId: flags['follow-up-task'],
+        }, eventContextFromFlags(flags), eventOptsFromFlags(flags));
+        printJson({ event_id: stored.event_id, record: stored.record });
+        return 0;
+    }
     if (namespace === 'research' && action === 'check') {
         const result = checkBrief(readJsonFile(requireFlag(flags, 'brief')));
         printJson(result);
@@ -1909,20 +2330,23 @@ async function main() {
         if (selectTestCmd !== undefined)
             assertSelectableTestCmd(selectTestCmd);
         const tasks = readJsonFile(tasksFile);
-        // D-46/P9-29: the queue is the only component that knows a branch landed,
-        // and it used to say so to stdout and nowhere else — which is why the
-        // projector's `completed` column was unreachable by machine. `--session`
-        // is what turns the run into a fact; without it the queue still runs, and
-        // still tells nobody.
-        const events = flags.session
-            ? { ctx: eventContextFromFlags(flags), ...eventOptsFromFlags(flags) }
-            : undefined;
+        // D-46/P9-29/#269: the queue is the only component that knows a branch
+        // landed, and it used to say so to stdout and nowhere else — which is why
+        // the projector's `completed` column was unreachable by machine, and why
+        // a wave that followed the playbook literally still left `wave-merged`
+        // unwritten. `--session` is what turns the run into a fact, so a run
+        // with no session to write it into is refused before any git write
+        // below, rather than left to merge and tell nobody.
+        if (!flags.session) {
+            throw new SmithError('cli.queue-run-needs-session', 'queue run merges task branches into the integration branch, so every merge must be logged: pass --session <id> --causal-parent <event-id> --plan <plan.json> (add --plan-version if the plan is not version 1).', { epic });
+        }
+        const events = { ctx: eventContextFromFlags(flags), ...eventOptsFromFlags(flags) };
         // `--tasks` is hand-written, so its ids are whatever was typed. Minting
         // them from the plan before any git runs is the whole point of P9-29: a
         // bare id here would put `wave-merged` in the log under a spelling the
         // plan never used, which is how the dogfood epic folded one task instead
         // of six. Refuse the run whole rather than merge some and mislabel them.
-        if (events && !flags.plan) {
+        if (!flags.plan) {
             throw new SmithError('cli.missing-flag', 'queue run --session also needs --plan <plan.json>: a merge may only be logged under the task id the plan declares.', { epic });
         }
         // --batch (roadmap merge-lanes) groups tasks with groupForBatch before
@@ -1930,12 +2354,10 @@ async function main() {
         // does not carry: the plan's `edges`, so a task never stacks with
         // something it depends_on, and — for a tasks-file entry that omits its
         // own `claims` — the plan's claim list, so a hand-typed batch run is not
-        // blind to a disjointness `wave admit` already knows. Same shape as the
-        // `--session` guard just above, and for the same reason: refuse the run
-        // whole rather than group some tasks correctly and others by guesswork.
-        if (flags.batch === 'true' && !flags.plan) {
-            throw new SmithError('cli.missing-flag', 'queue run --batch also needs --plan <plan.json>: grouping reads its dependency edges and claim lists from there.', { epic });
-        }
+        // blind to a disjointness `wave admit` already knows. `--plan` is
+        // unconditionally required above since #269, so a batch run with none is
+        // already refused there.
+        //
         // `attemptCandidate` runs the epic's test command directly against the
         // whole batch candidate — there is no per-task file set to narrow it to,
         // so a `--select-test-cmd` template would either render nonsensically or
@@ -2073,7 +2495,10 @@ async function main() {
         // the merge — and adopt any task with it, which is the forgery the whole
         // verb exists to prevent. Deriving it from the plan-resolved id means the
         // branch and the id it is logged under cannot disagree.
-        { taskId, branch: taskBranchName(plan.epic_id, taskId) }, {
+        {
+            taskId,
+            branch: taskBranchName(plan.epic_id, taskId, epicBranchPrefix(projectDir, plan.epic_id)),
+        }, {
             projectDir,
             epic: plan.epic_id,
             mergeCommit,
@@ -2091,6 +2516,7 @@ async function main() {
             ...eventOptsFromFlags(flags),
             ...(flags.actor === undefined ? {} : { actor: flags.actor }),
             ...(flags.continues === undefined ? {} : { continues: flags.continues }),
+            ...(flags.prompt === undefined ? {} : { promptId: flags.prompt }),
         }));
         return 0;
     }
@@ -2154,7 +2580,7 @@ async function main() {
             process.stderr.write(`warning: this session-start is ${result.event_id}, not ${result.record.session_id}#0 — ` +
                 `session "${result.record.session_id}" was already open. The record is written and ` +
                 'durable, but a log has one root and readers take the first, so nothing will read this ' +
-                'one. Use `smith session start`, which refuses instead of receipting, and chain off the ' +
+                'one. Use `bs session start`, which refuses instead of receipting, and chain off the ' +
                 'event that is already there.\n');
         }
         printJson({ ...result, on_timeline: onTimeline });
@@ -2394,7 +2820,7 @@ async function main() {
             // Same refusal as `wave check`, for the same reason: validating the
             // empty set answers "admissible" about a wave nobody described.
             if (positional.length === 0) {
-                throw new SmithError('cli.empty-wave', 'Usage: smith claims impact --plan <plan.json> <task-id>... — a wave with no tasks is not a wave.', { plan: plan.epic_id });
+                throw new SmithError('cli.empty-wave', 'Usage: bs claims impact --plan <plan.json> <task-id>... — a wave with no tasks is not a wave.', { plan: plan.epic_id });
             }
             const recordsById = new Map(plan.tasks.map((task) => [task.task_id, task]));
             // Claims and keeps_exports are read through the one door validateWave
@@ -2562,7 +2988,7 @@ async function main() {
             worktree: flags.worktree ?? null,
             ...(tier !== undefined ? { tier } : {}),
             ...(flags.schema !== undefined ? { schema: flags.schema } : {}),
-        }, { policy: loadHarnessPolicy(flags.policy) });
+        }, { policy: loadHarnessPolicy(flags.policy), planOpts: planOptsFromFlags(flags) });
         printJson(invocation);
         return 0;
     }
@@ -2648,6 +3074,14 @@ async function main() {
         const { runGate } = await import('./gate.js');
         const [taskId] = requirePositionals(positional, usageFor('gate run'));
         const worktreeDir = requireFlag(flags, 'worktree');
+        // --project overrides; otherwise derived from --worktree, whose main
+        // checkout IS the project (a task worktree is a git-worktree sibling,
+        // `.wt/<project>/<task>`, not a child -- see projectDirFromFlags). Either
+        // way this reaches the gate's own crosscheck load below, so a project's
+        // .blacksmith/crosscheck.yml overlay (OpenRouter substitution/extra
+        // judges) governs the quorum a gate run can trigger, not just the
+        // shipped policy.
+        const projectDir = projectDirFromFlags(flags);
         const checks = readChecksFile(requireFlag(flags, 'checks'));
         // The result file has the same two intake shapes as findings below, and for
         // the same reason. With `--agent`, `--result` is the worker's half —
@@ -2656,6 +3090,13 @@ async function main() {
         // meter, so a token count it writes is invented (D-18/P9-17). Without
         // `--agent` the file is taken as a complete document, which is what a
         // replay or a fixture hands over.
+        //
+        // `--input-tokens`/`--output-tokens` are optional, both-or-neither (#220):
+        // a harness that ran the subprocess itself has real numbers, but a
+        // dispatcher with no API onto a subagent's token spend — one running
+        // inside Claude Code, say — has neither, and stampResultEnvelope turns
+        // that absence into an honest `{measured: false}` rather than have the
+        // caller invent a count to satisfy a mandatory flag.
         const resultFile = readJsonFile(requireFlag(flags, 'result'));
         const result = flags.agent
             ? stampResultEnvelope(resultFile, {
@@ -2663,8 +3104,8 @@ async function main() {
                 agent: flags.agent,
                 provider: requireFlag(flags, 'provider'),
                 modelTier: requireFlag(flags, 'model-tier'),
-                inputTokens: requireIntFlag(flags, 'input-tokens'),
-                outputTokens: requireIntFlag(flags, 'output-tokens'),
+                inputTokens: boundedIntFlag(flags, 'input-tokens', { min: 0 }),
+                outputTokens: boundedIntFlag(flags, 'output-tokens', { min: 0 }),
             })
             : resultFile;
         // Two intake shapes. `--evidence` is what judges actually produce
@@ -2673,8 +3114,9 @@ async function main() {
         // judge at this gate (D-32/P9-13). `--findings` stays for already-minted
         // records (replays, fixtures, cross-check re-runs).
         const findingsInput = [
-            ...(flags.findings ? readJsonFile(flags.findings) : []),
+            ...(flags.findings ? readFindingsInputFile(flags.findings) : []),
             ...mintFromEvidence(args, taskId),
+            ...(flags['uiux-visual'] ? mintFromUiuxVisual(flags['uiux-visual'], taskId) : []),
         ];
         const lessons = flags.lessons ? parseLessons(readFileSync(flags.lessons, 'utf8')) : [];
         const ctx = eventContextFromFlags(flags);
@@ -2709,18 +3151,24 @@ async function main() {
         // 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);
-        const graderGiven = flags.grader ? [{ foundBy: 'grader', file: flags.grader }] : [];
-        const handedIn = [...evidenceGiven, ...graderGiven];
+        const graderGiven = flags.grader
+            ? [{ foundBy: 'grader', file: flags.grader }]
+            : [];
+        const uiuxVisualGiven = flags['uiux-visual']
+            ? [{ foundBy: 'uiux', file: flags['uiux-visual'], kind: 'visual' }]
+            : [];
+        const handedIn = [...evidenceGiven, ...graderGiven, ...uiuxVisualGiven];
         if (handedIn.length > 0) {
             const turns = await readJudgeTurns(taskId, ctx, eventOptsFromFlags(flags));
             const closed = new Set();
-            for (const { foundBy, file } of handedIn) {
-                if (closed.has(foundBy))
+            for (const { foundBy, file, kind } of handedIn) {
+                const closeKey = kind ? `${foundBy}:${kind}` : foundBy;
+                if (closed.has(closeKey))
                     continue;
-                if (!turns.some((t) => t.role === foundBy && !t.reported))
+                if (!turns.some((t) => t.role === foundBy && t.kind === (kind ?? null) && !t.reported))
                     continue;
-                closed.add(foundBy);
-                await recordJudgeReport({ taskId, role: foundBy, artifactPath: file }, ctx, eventOptsFromFlags(flags));
+                closed.add(closeKey);
+                await recordJudgeReport({ taskId, role: foundBy, artifactPath: file, ...(kind ? { kind } : {}) }, ctx, eventOptsFromFlags(flags));
             }
         }
         // P9-11: the genuinely clean case, said out loud. A judge that found
@@ -2733,7 +3181,7 @@ async function main() {
             // role called "true" would close nothing (no such dispatch exists) and
             // say so nowhere, so a bare --no-findings is a usage error instead.
             if (role === 'true') {
-                throw new SmithError('cli.no-findings-needs-role', '--no-findings names the judge role it attests for, e.g. --no-findings security-reviewer.', { usage: 'smith gate run <task-id> --no-findings <role>' });
+                throw new SmithError('cli.no-findings-needs-role', '--no-findings names the judge role it attests for, e.g. --no-findings security-reviewer.', { usage: 'bs gate run <task-id> --no-findings <role>' });
             }
             await recordJudgeReport({ taskId, role, noFindings: true }, ctx, eventOptsFromFlags(flags));
         }
@@ -2762,10 +3210,75 @@ async function main() {
             ...(graderVerdict !== undefined ? { graderVerdict } : {}),
             ...(budget ? { budget } : {}),
             ...(flags['artifacts-dir'] ? { artifactsDir: flags['artifacts-dir'] } : {}),
+            uiAffecting: uiAffectingFromFlags(flags, taskId),
+            crosscheck: { policy: loadCrosscheckPolicy(undefined, { projectDir }) },
+        }, ctx, eventOptsFromFlags(flags));
+        printJson(outcome);
+        return outcome.outcome === 'blocked' ? 1 : 0;
+    }
+    // The tester's screenshots reach the dashboard the moment the tester
+    // finishes, not only at the next `gate run`. wave.md's tester has no
+    // worktree to certify and no tests to run, so it was never handed to
+    // `gate run` at all — and its declared artifacts never reached the
+    // projector (`${event_id}#${index}` rows in db/projector.ts). This is the
+    // schema-check/task-result-recorded/artifact-check third of `gate run`
+    // exposed on its own, over the same `recordTaskResult` (gate.ts) rather
+    // than a second copy of either check, and it never emits `gate-outcome`:
+    // epic.ts's ungated-task check (D-138) treats that event as proof a full
+    // gate ran, and a lean Result projection is not one.
+    if (namespace === 'results' && action === 'record') {
+        const { recordTaskResult } = await import('./gate.js');
+        const taskId = requireFlag(flags, 'task');
+        // The same two intake shapes as `gate run`'s `--result`, for the same
+        // reason (D-18/P9-17): with `--agent` the file is the worker's half and
+        // the dispatcher stamps token_usage, so a tester's own count never reaches
+        // the budget reads.
+        const resultFile = readJsonFile(requireFlag(flags, 'result'));
+        const result = flags.agent
+            ? stampResultEnvelope(resultFile, {
+                taskId,
+                agent: flags.agent,
+                provider: requireFlag(flags, 'provider'),
+                modelTier: requireFlag(flags, 'model-tier'),
+                inputTokens: boundedIntFlag(flags, 'input-tokens', { min: 0 }),
+                outputTokens: boundedIntFlag(flags, 'output-tokens', { min: 0 }),
+            })
+            : resultFile;
+        const ctx = eventContextFromFlags(flags);
+        const outcome = await recordTaskResult({
+            taskId,
+            result,
+            ...(flags['artifacts-dir'] ? { artifactsDir: flags['artifacts-dir'] } : {}),
+            ...(flags.worktree ? { worktreeDir: flags.worktree } : {}),
         }, ctx, eventOptsFromFlags(flags));
         printJson(outcome);
         return outcome.outcome === 'blocked' ? 1 : 0;
     }
+    // U2 S3/D4: the preflight for the gate's uiux stage, over the same
+    // checkUiux the stage itself calls — so a dispatcher can ask "is this task's
+    // screenshot set fresh and reviewed yet" without staging a whole gate run,
+    // and the two can never disagree about the same fixture.
+    if (namespace === 'uiux' && action === 'check') {
+        const { checkUiux } = await import('./uiuxGate.js');
+        const taskId = requireFlag(flags, 'task');
+        const plan = readJsonFile(requireFlag(flags, 'plan'));
+        const resolved = resolveTaskId(plan, taskId);
+        const spec = liveSpec(plan, resolved);
+        const ctx = eventContextFromFlags(flags);
+        const opts = eventOptsFromFlags(flags);
+        if (!spec || !isUiAffecting(spec)) {
+            printJson({ outcome: 'pass' });
+            return 0;
+        }
+        const head = flags.worktree ? runGit(flags.worktree, ['rev-parse', 'HEAD']) : undefined;
+        const result = await checkUiux({
+            taskId: resolved,
+            ...(head !== undefined ? { head } : {}),
+            ...(flags['artifacts-dir'] ? { artifactsDir: flags['artifacts-dir'] } : {}),
+        }, ctx, opts);
+        printJson(result);
+        return result.outcome === 'blocked' ? 1 : 0;
+    }
     // D-40/P9-25: the gate's coverage evidence, without staging a gate run.
     // This is the verb the D-40 investigation wanted and did not have — it took
     // a coverage re-run on the pre-task-4 integration branch to establish what
@@ -2812,11 +3325,21 @@ async function main() {
         // session reports half an epic's cost as the whole of it, and reports it
         // under an alarm threshold it may already have crossed.
         const events = await readLineageEvents(sessionId, eventOptsFromFlags(flags));
+        // Each epic is judged against budgets.yml sized for its own effort tier
+        // (its latest plan's `effort`); the report's top-level cap is the default
+        // tier's, and each epic line carries the cap it was judged against.
+        const policyForEpic = epicBudgetPolicies({
+            policyFile: flags.policy,
+            planOpts: planOptsFromFlags(flags),
+        });
         const report = checkBudgetAlarm(events, loadBudgetPolicy(flags.policy), {
             sessionId,
             ...(flags.epic ? { epicId: flags.epic } : {}),
+            policyForEpic,
         });
-        const envOverrides = budgetEnvOverrides(loadBudgetPolicy(flags.policy, {}));
+        const envOverrides = [
+            ...new Set([undefined, ...report.epics.filter((e) => e.epicId !== '*').map((e) => e.epicId)].flatMap((epicId) => budgetEnvOverrides(loadBudgetPolicy(flags.policy, {}, epicId === undefined ? undefined : policyForEpic(epicId).tier)))),
+        ];
         printJson(envOverrides.length > 0 ? { ...report, budgetEnvOverrides: envOverrides } : report);
         return report.ok ? 0 : 1;
     }
@@ -2869,12 +3392,26 @@ async function main() {
         const outcome = await runEpicVerdict({
             epicId,
             integrationHeadSha: integrationHeadSha(projectDir, epicId),
+            integrationBranch: integrationBranchName(epicId, epicBranchPrefix(projectDir, epicId)),
             mcp: mcpSurfaceFor(epicId, projectDir, flags),
             goal: epicGoalFor(epicId, flags),
             // D-126: the live plan is a voter. Without this the roster is the
             // event-log fold alone, and a task an amendment added but nobody
             // dispatched is invisible rather than unfinished.
             planOpts: planOptsFromFlags(flags),
+            // run.md step 13: tier `small` may waive an absent closing spec
+            // review, but only `summarizeEpic` can tell an epic's tier apart
+            // from a hole nobody filled -- resolved the same way `effort show`
+            // resolves it, security floor included.
+            effort: resolveEpicEffort(epicId, flags),
+            // --project is already required above; hand it to the crosscheck
+            // load too, so a project's .blacksmith/crosscheck.yml overlay
+            // (OpenRouter substitution/extra judges) is what the verdict's
+            // quorum actually reads, not just what preflight reports. No
+            // --policy override for this command (unlike judge preflight):
+            // the shipped/default path plus the project overlay is the only
+            // combination epic verdict has ever read.
+            crosscheck: { policy: loadCrosscheckPolicy(undefined, { projectDir }) },
         }, ctx, eventOptsFromFlags(flags));
         printJson(outcome);
         return outcome.outcome === 'hold' ? 1 : 0;
@@ -2891,9 +3428,17 @@ async function main() {
         const record = await closeEpic({
             epicId,
             integrationHeadSha: integrationHeadSha(projectDir, epicId),
+            integrationBranch: integrationBranchName(epicId, epicBranchPrefix(projectDir, epicId)),
             mcp: mcpSurfaceFor(epicId, projectDir, flags),
             goal: epicGoalFor(epicId, flags),
             planOpts: planOptsFromFlags(flags),
+            // See `epic verdict` above: same tier resolution, so a close can
+            // never waive a review its own verdict would have blocked on.
+            effort: resolveEpicEffort(epicId, flags),
+            // Same reasoning as `epic verdict` above: the project overlay must
+            // reach the close's own crosscheck load too, not just the verdict
+            // it is closing over.
+            crosscheck: { policy: loadCrosscheckPolicy(undefined, { projectDir }) },
             ...(flags['override-rationale'] !== undefined
                 ? { overrideRationale: flags['override-rationale'] }
                 : {}),
@@ -2912,13 +3457,26 @@ async function main() {
         const plan = readJsonFile(requireFlag(flags, 'plan'));
         // Evidence, not identity (interview N-2): the reviewer reports what it
         // read; the plan version and the head it was read at come from here.
+        //
+        // Exactly one of --evidence or --no-findings (issue #249). A missing
+        // --evidence used to read as "found nothing", so a reviewer that never
+        // wrote its file closed the review clean. Same rule as `judge report`:
+        // an empty review is the file saying so, or the operator attesting it.
+        const noFindings = flags['no-findings'] === 'true';
+        if (noFindings && flags.evidence) {
+            throw new SmithError('cli.incompatible-flags', 'epic spec-review takes --evidence <file> or --no-findings, not both: the review either handed over its findings file or the operator attests it found nothing.', { epicId });
+        }
+        if (!noFindings && !flags.evidence) {
+            throw new SmithError('cli.missing-flag', "epic spec-review needs --evidence <file> (the reviewer's findings list, `[]` when it found nothing) or --no-findings (the operator attests an empty review). A missing file is not an empty review.", { epicId, flag: 'evidence' });
+        }
         const evidence = flags.evidence ? readJsonFile(flags.evidence) : [];
         // No branch, no review. The whole point of this dispatch is that it reads
         // the code that now exists; recording one against a head that could not be
         // read would produce a review nothing can be shown to cover.
         const headSha = integrationHeadSha(projectDir, epicId);
         if (headSha === null) {
-            throw new SmithError('cli.no-integration-branch', `Could not read the head of smith/${epicId}/integration in ${projectDir}. The closing spec review reads the assembled branch, so there is nothing to review yet.`, { epicId, projectDir });
+            const branch = integrationBranchName(epicId, epicBranchPrefix(projectDir, epicId));
+            throw new SmithError('cli.no-integration-branch', `Could not read the head of ${branch} in ${projectDir}. The closing spec review reads the assembled branch, so there is nothing to review yet.`, { epicId, projectDir });
         }
         const record = await recordSpecReview({
             epicId,
@@ -2929,6 +3487,7 @@ async function main() {
                 ? { reviewedByProvider: flags['reviewed-by-provider'] }
                 : {}),
             evidence,
+            ...(noFindings ? { noFindings: true } : {}),
         }, eventContextFromFlags(flags), eventOptsFromFlags(flags));
         printJson(record);
         // Exit 0 even when it found something: the review ran, and a spec finding
@@ -3046,7 +3605,7 @@ async function main() {
         // are indistinguishable to everything downstream.
         const mintTaskId = specDispatch && plan ? `${plan.epic_id}/${RESERVED_TASK_ID}` : defaultTaskId;
         const findingsInput = [
-            ...(flags.findings ? readJsonFile(flags.findings) : []),
+            ...(flags.findings ? readFindingsInputFile(flags.findings) : []),
             // The mint id, not the default one: a spec finding belongs to the epic
             // (D-33), and the dispatch's scope rides along with it so every finding
             // in the batch is spec-scoped by construction.
@@ -3084,7 +3643,9 @@ async function main() {
             // can hold the fix, because the fix is a plan amendment.
             const isSpec = !result.suppressed && findingScope(result.finding) === SPEC_FINDING_SCOPE;
             if (!result.suppressed && !isSpec) {
-                await recordReattribution(routing, result.finding, ctx, opts);
+                // The plan, when given, says which project a follow-up belongs to --
+                // the same fallback the plan-driven task writers take (planScoped).
+                await recordReattribution(routing, result.finding, plan?.project ? { ...ctx, project: plan.project } : ctx, opts);
             }
             raised.push({
                 findingId: result.suppressed ? null : result.finding.finding_id,
@@ -3093,6 +3654,8 @@ async function main() {
                 attribution: isSpec ? SPEC_FINDING_SCOPE : routing.attribution,
                 suppressed: result.suppressed,
                 reason: routing.reason,
+                // A suppressed finding appended nothing, so it carries no event_id.
+                event_id: result.suppressed ? undefined : result.event_id,
             });
         }
         printJson(raised);
@@ -3132,11 +3695,11 @@ async function main() {
         // Refusing here, on the status alone, keeps argument order as the reading
         // order and lets the error name the verb that CAN take the edge.
         const AMENDMENT_ROUTES = {
-            [AMEND_PENDING_STATUS]: '`smith plan amend` puts every finding it cites into "amend-pending", with the task ids the new plan version added or superseded as the obligation',
-            [AMENDED_STATUS]: '`smith epic close` computes which of those tasks actually landed and discharges the finding with that evidence',
+            [AMEND_PENDING_STATUS]: '`bs plan amend` puts every finding it cites into "amend-pending", with the task ids the new plan version added or superseded as the obligation',
+            [AMENDED_STATUS]: '`bs epic close` computes which of those tasks actually landed and discharges the finding with that evidence',
         };
         if (newStatus in AMENDMENT_ROUTES) {
-            throw new SmithError('cli.amendment-edge-unreachable', `"${newStatus}" is not reachable through "smith findings transition": the amendment path is entered and closed by the commands that can compute its evidence, never by hand. ${AMENDMENT_ROUTES[newStatus]}.`, { status: newStatus, findingId });
+            throw new SmithError('cli.amendment-edge-unreachable', `"${newStatus}" is not reachable through "bs findings transition": the amendment path is entered and closed by the commands that can compute its evidence, never by hand. ${AMENDMENT_ROUTES[newStatus]}.`, { status: newStatus, findingId });
         }
         const ctx = eventContextFromFlags(flags);
         const finding = await transitionFinding(findingId, newStatus, ctx, eventOptsFromFlags(flags));
@@ -3145,20 +3708,25 @@ async function main() {
     }
     // The dispatch-time half of P9-15, shaped exactly like `lessons
     // for-dispatch`: the caller composing a task prompt asks for the block and
-    // splices it. `--plan` is required rather than optional here — without it
-    // the claims list is empty, every finding fails the join, and the command
-    // would answer "nothing is open in your files" when it never looked.
+    // splices it. `--plan` and `--task` come as a pair: a `--task` without
+    // `--plan` would have an empty claims list, every finding would fail the
+    // join, and the command would answer "nothing is open in your files" when it
+    // never looked. Neither is the epic-level shape (#248) — a role with no task
+    // of its own (dispatch.md) gets every open finding in the epic instead.
     if (namespace === 'findings' && action === 'for-dispatch') {
-        const usage = 'smith findings for-dispatch --session ... --plan plan.json --task task-id [--state-dir dir]';
-        requireFlag(flags, 'plan');
-        const taskId = requireFlag(flags, 'task');
+        const usage = usageLine(usageFor('findings for-dispatch'));
+        if (flags.task !== undefined)
+            requireFlag(flags, 'plan');
         const sessionId = requireFlag(flags, 'session');
         const eventOpts = eventOptsFromFlags(flags);
         requireSession(sessionId, eventOpts);
         if (positional.length > 0) {
             throw new SmithError('cli.usage', `Unexpected argument. Usage: ${usage}`, { positional });
         }
-        printJson(await findingsForDispatch({ sessionId, taskId, claims: claimsForDispatch(flags) }, eventOpts));
+        // claimsForDispatch refuses a `--plan` with no `--task`, so half a
+        // per-task call never falls through to the epic-wide answer.
+        const claims = claimsForDispatch(flags);
+        printJson(await findingsForDispatch({ sessionId, ...(flags.task === undefined ? {} : { taskId: flags.task }), claims }, eventOpts));
         return 0;
     }
     // Re-dating a finding's evidence (P9-15). Deliberately its own verb and not
@@ -3170,8 +3738,8 @@ async function main() {
         const ctx = eventContextFromFlags(flags);
         const eventOpts = eventOptsFromFlags(flags);
         requireSession(ctx.sessionId, eventOpts);
-        await reverifyFinding(findingId, flags.note ?? '', ctx, eventOpts);
-        printJson({ findingId, note: flags.note ?? '' });
+        const reverified = await reverifyFinding(findingId, flags.note ?? '', ctx, eventOpts);
+        printJson({ findingId, note: flags.note ?? '', event_id: reverified.event_id });
         return 0;
     }
     // D-21 Part 4. Corrects a malformed amends_task_ids entry on a finding
@@ -3211,18 +3779,34 @@ async function main() {
         printJson(pending);
         return 0;
     }
+    if (namespace === 'waivers' && action === 'approve-task') {
+        const [taskId] = requirePositionals(positional, usageFor('waivers approve-task'));
+        const note = requireFlag(flags, 'note');
+        const event = await approveTaskWaiver(taskId, note, eventContextFromFlags(flags), eventOptsFromFlags(flags));
+        printJson(event);
+        return 0;
+    }
     if (namespace === 'waivers' && action === 'apply') {
         const [decisionsFile] = requirePositionals(positional, usageFor('waivers apply'));
         const decisions = readJsonFile(decisionsFile);
         const ctx = eventContextFromFlags(flags);
-        const results = await applyBatch(decisions, ctx, eventOptsFromFlags(flags));
-        printJson(results);
+        const result = await applyBatch(decisions, ctx, eventOptsFromFlags(flags));
+        // #221: a denial's output names the finding ids a later `plan amend
+        // --findings` has to carry, or a denied finding stays open forever with
+        // no discharge path left. See .claude/skills/bs/waivers.md.
+        printJson(result);
         return 0;
     }
     if (namespace === 'lessons' && action === 'candidates') {
         const { openDb } = await import('./db/projector.js');
         const { lessonsPage } = await import('./db/queries.js');
         const dbPath = flags.db ?? STATE_DB_PATH;
+        // A named session must exist, same as `db rebuild`/`db apply` (P9-28):
+        // without this, a typoed --session silently reads as "no rows for this
+        // session" instead of "no such session", and --state-dir (accepted here
+        // for exactly this) had no effect at all.
+        if (flags.session)
+            requireSession(flags.session, eventOptsFromFlags(flags));
         const handle = openDb(dbPath);
         try {
             const scope = flags.session ? { sessionId: flags.session } : {};
@@ -3297,7 +3881,7 @@ async function main() {
     if (namespace === 'lessons' && action === 'compile') {
         const { openDb } = await import('./db/projector.js');
         const { lessonsPage } = await import('./db/queries.js');
-        const { compileLessons } = await import('./lessons.js');
+        const { compileLessons, lessonsToPreserve } = 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
@@ -3310,7 +3894,14 @@ async function main() {
         try {
             const scope = flags.session ? { sessionId: flags.session } : {};
             const approved = lessonsPage(handle.db, scope).approved;
-            const markdown = compileLessons(approved.map((l) => ({
+            // The store only ever tracks its OWN rows: an entry already in outPath
+            // with no store row (hand-authored, or raised before the store existed)
+            // is invisible to `approved` above, so compileLessons has to be handed
+            // the file's own prior content or it has no way to tell "the store
+            // doesn't track this" apart from "this was deleted" — see its own
+            // docstring.
+            const existingMarkdown = existsSync(outPath) ? readFileSync(outPath, 'utf8') : undefined;
+            const compileInputs = approved.map((l) => ({
                 lessonId: l.lessonId,
                 lessonScope: l.lessonScope,
                 statement: l.statement,
@@ -3318,9 +3909,14 @@ async function main() {
                 claimPath: l.claimPath,
                 agentRole: l.agentRole,
                 caseType: l.caseType,
-            })));
+            }));
+            const markdown = compileLessons(compileInputs, existingMarkdown);
             writeFileSync(outPath, markdown, 'utf8');
-            printJson({ outPath, lessonsCompiled: approved.length });
+            // lessonsPreserved: pre-existing entries with no store row that this
+            // compile kept verbatim rather than regenerated — the count an operator
+            // needs to notice a hand-authored entry silently stopped surviving.
+            const lessonsPreserved = lessonsToPreserve(compileInputs, existingMarkdown).length;
+            printJson({ outPath, lessonsCompiled: approved.length, lessonsPreserved });
             return 0;
         }
         finally {
@@ -3400,8 +3996,14 @@ async function main() {
             model: requireFlag(flags, 'model'),
             ...(flags.provider ? { provider: flags.provider } : {}),
             ...(flags['model-tier'] ? { modelTier: flags['model-tier'] } : {}),
+            // uiux only: which of its two turns this dispatch opens; recordJudgeDispatch
+            // rejects it for any other role.
+            ...(flags.kind ? { kind: flags.kind } : {}),
         }, eventContextFromFlags(flags), eventOptsFromFlags(flags));
-        printJson(stored);
+        printJson({
+            ...stored,
+            expected_line: formatDeclaredArtifactLine(requireFlag(flags, 'artifact')),
+        });
         return 0;
     }
     if (namespace === 'judge' && action === 'report') {
@@ -3419,16 +4021,27 @@ async function main() {
             // Here the role is already named by --role, so the valueless spelling
             // is the right one and 'true' means what it says.
             ...(flags['no-findings'] === 'true' ? { noFindings: true } : {}),
+            // uiux only: which of its two open turns this closes; required when both are open.
+            ...(flags.kind ? { kind: flags.kind } : {}),
         }, eventContextFromFlags(flags), eventOptsFromFlags(flags));
         printJson(report);
         return 0;
     }
     if (namespace === 'judge' && action === 'outstanding') {
         const sessionId = requireFlag(flags, 'session');
+        const taskId = requireFlag(flags, 'task');
         const eventOpts = eventOptsFromFlags(flags);
         requireSession(sessionId, eventOpts);
-        const open = outstandingJudges(await readJudgeTurns(requireFlag(flags, 'task'), { sessionId }, eventOpts));
-        printJson(open);
+        // A typo such as `--kind visaul` must not read as "nothing outstanding":
+        // filtering on an unrecognised kind would silently match zero turns and
+        // exit 0 while a real one is still open (S2). Validate against the same
+        // closed list `assertKindAllowed` checks before filtering.
+        if (flags.kind !== undefined && !isJudgeKind(flags.kind)) {
+            throw new JudgeError('judges.invalid-kind', `"--kind" must be "spec" or "visual"; got ${JSON.stringify(flags.kind)}.`, { kind: flags.kind });
+        }
+        const allOpen = outstandingJudges(await readJudgeTurns(taskId, { sessionId }, eventOpts));
+        const open = flags.kind ? allOpen.filter((turn) => turn.kind === flags.kind) : allOpen;
+        printJson({ taskId, sessionId, outstanding: open, count: open.length });
         return open.length > 0 ? 1 : 0;
     }
     if (namespace === 'judge' && action === 'escalations') {
@@ -3453,7 +4066,7 @@ async function main() {
         // Deliberately ahead of `judge run` in this file for the same reason it is
         // ahead of it in the runbook: an operator reaching for a calibration call
         // to find out why a provider keeps failing usually needed this instead.
-        const report = judgePreflight(flags.policy);
+        const report = judgePreflight(flags.policy, { projectDir: flags.project });
         printJson(report);
         return report.problems.length > 0 ? 1 : 0;
     }
@@ -3473,7 +4086,15 @@ async function main() {
         // the split between them is the operator mandate made operable: `request`
         // shows exactly what would leave the machine WITHOUT sending it, `run`
         // sends it, and `reconcile` needs no provider at all.
-        const policy = loadCrosscheckPolicy(flags.policy);
+        //
+        // --project (or a --worktree to derive one from) reaches this load too,
+        // same as `gate run`/`plan quorum`/`epic verdict`. Only `run` can ever
+        // observe it: `independent_finder` -- the fragment `request`/`reconcile`
+        // read -- is a repo-policy knob a project overlay is structurally
+        // forbidden to touch (loadProjectProviderOverlay only ever merges
+        // `providers`), and `run` is the one call that hands runIndependentFinder
+        // the full policy, `providers` included.
+        const policy = loadCrosscheckPolicy(flags.policy, { projectDir: projectDirFromFlags(flags) });
         if (action === 'request') {
             // Read-only and network-free by construction: it builds the JudgeRequest
             // and prints it. Every refusal independentFinderRequest() can raise —
@@ -3580,7 +4201,7 @@ async function main() {
         // missing feature but a silent data swap: the read path re-projects each
         // session on the first request (app.ts's createRefresher), and apply()
         // rebuilds the whole milestones table from a roadmap file while it is
-        // there. Unset, that file falls back to black-smith's own
+        // there. Unset, that file falls back to blacksmith's own
         // factory/specs/roadmap.md — so serving another project's db showed this
         // repo's roadmap from the first page load onward.
         const roadmapPath = flags['roadmap-path'];
@@ -3588,13 +4209,30 @@ async function main() {
         // request, and the plan files it consults to place an unstamped epic
         // (D-246) must be the served db's, not this repo's.
         const specsDir = flags['specs-dir'];
+        // Where Claude Code keeps its live-session registry and transcripts, for
+        // /api/cli-sessions: --claude-config-dir, then $CLAUDE_CONFIG_DIR, then
+        // ~/.claude. Only this verb resolves a default; the server never does.
+        const claudeFlag = flags['claude-config-dir'];
+        const claudeEnv = process.env.CLAUDE_CONFIG_DIR;
+        const claude = claudeFlag
+            ? { dir: path.resolve(claudeFlag), source: 'flag' }
+            : claudeEnv
+                ? { dir: path.resolve(claudeEnv), source: 'env' }
+                : { dir: path.join(homedir(), '.claude'), source: 'default' };
+        // Repeatable: extra state homes (`<dir>/state/events`) the dashboard reads
+        // besides the live sessions' own. Read-only; see ui/server/src/stores.ts.
+        const stores = (repeated.store ?? []).map((dir) => path.resolve(dir));
         mod.serve({
             port,
             dbPath,
+            ...(stores.length > 0 ? { stores } : {}),
             ...(stateDir ? { stateDir } : {}),
             ...(roadmapPath ? { roadmapPath } : {}),
             ...(specsDir ? { specsDir } : {}),
             ...(nowIso !== undefined ? { nowIso } : {}),
+            claudeConfigDir: claude.dir,
+            claudeConfigSource: claude.source,
+            knownRoots: [...new Set([REPO_ROOT, WORK_ROOT])],
         });
         return 0;
     }
@@ -3699,11 +4337,63 @@ async function main() {
     });
     return 1;
 }
+// `smith <verb> | head -c1` (or any reader that goes away before draining
+// stdout) closes the pipe out from under a write that has already committed
+// whatever the verb was reporting -- a `dispatch_decision` appended, an event
+// tailed, a report already computed. Node's default for an unheard stdout
+// `error` is to throw, which crashes the process AFTER that commit with an
+// uncaught `write EPIPE` stack; a caller that treats the resulting non-zero
+// exit as "did not happen" and retries then double-appends. `event tail
+// --follow` and `daemon run` already each register their own `process.stdout
+// .on('error', requestStop)` to stop their loop quietly (cli.ts's two other
+// stdout error listeners), but every one-shot verb -- everything that calls
+// `printJson` exactly once -- had no listener at all, so it was still one
+// early reader away from this crash. Registered here, at the top of the
+// file's only entry point, so it is in place before ANY write, including the
+// per-verb ones' own first `printJson` call.
+//
+// Multiple listeners on the same stream's `error` event all fire -- this one
+// does not replace `event tail --follow`'s or `daemon run`'s, it just also
+// catches everything they do not: whichever fires first, an EPIPE is still
+// quiet.
+//
+// A real write failure (ENOSPC, say) is not innocuous like EPIPE, but this
+// handler is registered before `event tail --follow`'s and `daemon run`'s
+// own `process.stdout.on('error', requestStop)` listeners (this file's other
+// two), at the top of the file's only entry point -- so if it rethrows
+// unconditionally, its throw fires first and those listeners never run at
+// all. For `daemon run` specifically, that throw becomes an uncaught
+// exception outside `runDaemon`'s own try/finally (daemon.ts's loop), which
+// skips the finally and strands the lock under a pid that is already gone --
+// exactly what the comment at this file's `daemon run` handler says the
+// listener there exists to prevent. `listenerCount` counts this listener
+// too, so `> 1` means one of those loop-owning listeners is also registered:
+// defer to it and let its own stop-the-loop handling run instead of
+// rethrowing here. Only when this is the sole listener -- a one-shot verb,
+// nothing else to stop -- does a real write failure still throw and crash,
+// same as before.
+let mainExitCode = null;
+process.stdout.on('error', (err) => {
+    if (err.code === 'EPIPE') {
+        // The command's own resolved status when we already have one (a verb
+        // that computed its exit code before this write, the common case); 0 --
+        // "wrote everything there was, the reader just stopped listening" --
+        // when main() has not resolved yet, since an early EPIPE is the reader
+        // saying "enough", not this process failing to do its job.
+        process.exitCode = mainExitCode ?? 0;
+        return;
+    }
+    if (process.stdout.listenerCount('error') > 1)
+        return;
+    throw err;
+});
 main()
     .then((code) => {
+    mainExitCode = code;
     process.exitCode = code;
 })
     .catch((err) => {
+    mainExitCode = 1;
     // A SmithError is a designed answer: its code names the failure and its
     // details name the record, so a stack would only add noise. Anything else
     // is a bug, and D-135 is what that costs — `{"message":"Cannot read