@juzser/blacksmith 0.1.0 → 0.1.1

package/factory/orchestrator/dist/db/queries.js

@@ -6,7 +6,7 @@
 // is the normal case; a session filter is for debugging one run).
 import { and, eq, gte, inArray, lte } from 'drizzle-orm';
 import { isOperatorActor } from '../actors.js';
-import { foldAgents, liveAgents as foldLiveAgents, REGISTRY_EVENT_TYPES, } from '../agents-registry.js';
+import { foldAgents, liveAgents as foldLiveAgents, isWorkingAt, REGISTRY_EVENT_TYPES, } from '../agents-registry.js';
 import { compareLogOrder, isLaterEvent, parseEventId, ROOT_EVENT_TYPE } from '../events.js';
 import { waveLayers } from '../graph.js';
 import { judgeFailureKind } from '../providers/types.js';
@@ -514,14 +514,19 @@ function allAgentsForScope(db, scope) {
  * Ties on `lastEventAt` break on `sessionId` so the order is stable under the
  * dashboard's 5s poll rather than shuffling between renders.
  */
-export function runningSessions(db, scope = {}) {
+export function runningSessions(db, scope = {}, opts = {}) {
+    const nowIso = opts.nowIso ?? new Date().toISOString();
     const sessionCond = scopedToSessions(sessions.sessionId, scope);
     const rows = sessionCond
         ? db.select().from(sessions).where(sessionCond).all()
         : db.select().from(sessions).all();
     const liveBySession = new Map();
+    const workingBySession = new Map();
     for (const a of allAgentsForScope(db, scope)) {
         liveBySession.set(a.sessionId, (liveBySession.get(a.sessionId) ?? 0) + 1);
+        if (isWorkingAt(a.dispatchedAt, nowIso)) {
+            workingBySession.set(a.sessionId, (workingBySession.get(a.sessionId) ?? 0) + 1);
+        }
     }
     const projectsBySession = new Map();
     for (const t of allTasksForScope(db, scope)) {
@@ -555,6 +560,7 @@ export function runningSessions(db, scope = {}) {
         lastEventAt: s.lastEventAt,
         eventCount: s.eventCount,
         liveAgentCount: liveBySession.get(s.sessionId) ?? 0,
+        workingAgentCount: workingBySession.get(s.sessionId) ?? 0,
         lastEventType: lastEvent.get(s.sessionId)?.eventType ?? null,
         projects: [...(projectsBySession.get(s.sessionId) ?? [])].sort(),
     }))
@@ -621,8 +627,14 @@ function inFlightEpics(taskRows, closed) {
             .map((t) => t.epicId)),
     ].sort();
 }
-/** One project's overview slice, computed by the same logic overview() itself uses (no drift). */
-function projectSummary(db, project, baseScope) {
+/**
+ * One project's overview slice, computed by the same logic overview() itself
+ * uses (no drift). `nowIso` is the caller's single instant, not a fresh
+ * read: overview() hands every per-project summary the same "now" it used
+ * for its own counts, so the project rows and the global card can never
+ * disagree about which agents are working.
+ */
+function projectSummary(db, project, baseScope, nowIso) {
     const scope = { ...baseScope, project };
     const liveRows = allAgentsForScope(db, scope);
     const taskRows = allTasksForScope(db, scope);
@@ -637,6 +649,7 @@ function projectSummary(db, project, baseScope) {
     return {
         project,
         liveAgentCount: liveRows.length,
+        workingAgentCount: liveRows.filter((a) => isWorkingAt(a.dispatchedAt, nowIso)).length,
         epicsInFlight,
         tokensSpent,
         tokensBudget,
@@ -664,7 +677,7 @@ const SNAPSHOT_EVENT_TYPES = REGISTRY_EVENT_TYPES;
  * project, so its agent stayed in the live count and vanished from the
  * historical one, and the StatCard reported an arrival that never happened.
  */
-function liveAgentCountAt(db, scope, cutoffIso) {
+function liveAgentsAt(db, scope, cutoffIso) {
     const conds = [lte(eventsRaw.ts, cutoffIso), inArray(eventsRaw.eventType, SNAPSHOT_EVENT_TYPES)];
     const sessionCond = scopedToSessions(eventsRaw.sessionId, scope);
     if (sessionCond)
@@ -690,9 +703,25 @@ function liveAgentCountAt(db, scope, cutoffIso) {
     }));
     const live = foldLiveAgents(foldAgents(storedEvents));
     if (scope.project === undefined)
-        return live.length;
+        return live;
     const scopedTaskIds = new Set(allTasksForScope(db, scope).map((t) => t.taskId));
-    return live.filter((a) => a.taskId !== null && scopedTaskIds.has(a.taskId)).length;
+    return live.filter((a) => a.taskId !== null && scopedTaskIds.has(a.taskId));
+}
+function liveAgentCountAt(db, scope, cutoffIso) {
+    return liveAgentsAt(db, scope, cutoffIso).length;
+}
+/**
+ * The "working" end of workingAgentCountDelta5m's subtraction: the agents
+ * live as of `cutoffIso` (the very re-fold liveAgentCountAt does, project
+ * scoping included) that were ALSO within DEFAULT_STALE_HOURS of dispatch
+ * *at that cutoff*. Judging the historical rows against today's clock
+ * instead would be D-170 again in a new disguise — the "now" end would
+ * apply a 4h window and the "ago" end a 4h05m one, and an agent that
+ * stalled since the cutoff would read as no change.
+ */
+function workingAgentCountAt(db, scope, cutoffIso) {
+    return liveAgentsAt(db, scope, cutoffIso).filter((a) => isWorkingAt(a.dispatchedAt, cutoffIso))
+        .length;
 }
 /**
  * Total tokens spent (task-result-recorded token_usage) across `epicByTask`'s tasks, as of `cutoffIso`.
@@ -781,7 +810,14 @@ function tokensBudgetedAt(db, scope, cutoffIso, epicByTask) {
     return total;
 }
 export function overview(db, scope = {}, opts = {}) {
+    // One instant for everything this call reports. runningSessions(), the
+    // per-project summaries and the deltas each take the clock as an argument
+    // rather than reading it, so a request that straddles a threshold cannot
+    // count an agent as working in one field and stalled in the next.
+    const now = opts.nowIso ? new Date(opts.nowIso) : new Date();
+    const nowIso = now.toISOString();
     const liveRows = allAgentsForScope(db, scope);
+    const workingRows = liveRows.filter((a) => isWorkingAt(a.dispatchedAt, nowIso));
     const taskRows = allTasksForScope(db, scope);
     const closedEpics = closedEpicsForScope(db, scope);
     const epicsInFlight = inFlightEpics(taskRows, closedEpics);
@@ -835,12 +871,12 @@ export function overview(db, scope = {}, opts = {}) {
         // Milestones carry no session_id and milestoneProgressRows() never
         // filters them by one, so they join the list under a session scope too.
         const declaredRows = db.select({ project: milestones.project }).from(milestones).all();
-        projects = distinctProjects(allTaskRowsUnfiltered, declaredRows).map((p) => projectSummary(db, p, scope));
+        projects = distinctProjects(allTaskRowsUnfiltered, declaredRows).map((p) => projectSummary(db, p, scope, nowIso));
     }
-    const now = opts.nowIso ? new Date(opts.nowIso) : new Date();
     const fiveMinAgo = new Date(now.getTime() - 5 * 60 * 1000).toISOString();
     const oneHourAgo = new Date(now.getTime() - 60 * 60 * 1000).toISOString();
     const liveAgentCountDelta5m = liveRows.length - liveAgentCountAt(db, scope, fiveMinAgo);
+    const workingAgentCountDelta5m = workingRows.length - workingAgentCountAt(db, scope, fiveMinAgo);
     const epicByTask = new Map(taskRows.filter((t) => t.epicId !== null).map((t) => [t.taskId, t.epicId]));
     const totalBudgetNow = [...budgetByEpic.values()].reduce((s, v) => s + v, 0);
     const totalSpentNow = [...spentByEpic.values()].reduce((s, v) => s + v, 0);
@@ -873,7 +909,9 @@ export function overview(db, scope = {}, opts = {}) {
             dispatchedAt: a.dispatchedAt,
         })),
         liveAgentCount: liveRows.length,
-        runningSessions: runningSessions(db, scope),
+        workingAgentCount: workingRows.length,
+        stalledAgentCount: liveRows.length - workingRows.length,
+        runningSessions: runningSessions(db, scope, { nowIso }),
         epicsInFlight,
         closedEpics,
         tokensByEpic,
@@ -881,6 +919,7 @@ export function overview(db, scope = {}, opts = {}) {
         milestoneProgress: milestoneProgressRows(db, scope),
         recentDispatches,
         liveAgentCountDelta5m,
+        workingAgentCountDelta5m,
         budgetUsedPctPointDelta1h,
         ...(projects ? { projects } : {}),
     };
@@ -959,6 +998,12 @@ export const FREE_TIMELINE_EVENT_TYPES = [
     'audit-cut',
     'audit-resolved',
     'audit-closed',
+    // The integration PR run.md step 17 opens, appended by hand through `smith
+    // event append` under `<epic>/integration`. It is the epic's terminal
+    // deliverable -- the one thing the operator is asked to merge -- and the
+    // only event written after `epic-closed`, so without it the timeline of a
+    // closed epic ends at the closing and never shows what the closing was for.
+    'integration-pr-opened',
 ];
 let cachedTaxonomy;
 /**
@@ -1174,7 +1219,8 @@ function worstSeverity(severities) {
  * task_status, tagged with case/origin/worst-open-finding severity plus
  * (Phase 6b) title/agent-role/milestone.
  */
-export function kanban(db, epicId, scope = {}) {
+export function kanban(db, epicId, scope = {}, opts = {}) {
+    const nowIso = opts.nowIso ?? new Date().toISOString();
     const epicCond = epicId !== undefined ? eq(tasks.epicId, epicId) : undefined;
     const sessionCond = scopedToSessions(tasks.sessionId, scope);
     const taskConds = [epicCond, sessionCond].filter((c) => c !== undefined);
@@ -1221,6 +1267,18 @@ export function kanban(db, epicId, scope = {}) {
                 modelTier: d.modelTier,
             });
     }
+    // Who is still on each task, from the agents rows (live only — see
+    // allAgentsForScope). A working row wins over a stalled one on the same
+    // task for the reason flowGraph gives: the chip says who is on the task.
+    const activityByTask = new Map();
+    for (const a of allAgentsForScope(db, scope)) {
+        if (!a.taskId)
+            continue;
+        if (isWorkingAt(a.dispatchedAt, nowIso))
+            activityByTask.set(a.taskId, 'working');
+        else if (!activityByTask.has(a.taskId))
+            activityByTask.set(a.taskId, 'stalled');
+    }
     // epicId -> milestoneId, from roadmap.md's milestones table.
     const milestoneRows = db.select().from(milestones).all();
     const milestoneByEpic = new Map();
@@ -1237,6 +1295,7 @@ export function kanban(db, epicId, scope = {}) {
             title: t.objective,
             agentRole: latestAgentRoleByTask.get(t.taskId)?.agentRole ?? null,
             agentModelTier: latestAgentRoleByTask.get(t.taskId)?.modelTier ?? null,
+            agentActivity: activityByTask.get(t.taskId) ?? null,
             milestoneId: t.epicId ? (milestoneByEpic.get(t.epicId) ?? null) : null,
             tags: {
                 case: t.caseTag,
@@ -1462,7 +1521,8 @@ export function analytics(db, scope = {}) {
  * stack.md: "no separate layout library" — this IS that orchestrator
  * utility, exposed via this query/endpoint per the same doc's instruction).
  */
-export function flowGraph(db, filter = {}) {
+export function flowGraph(db, filter = {}, opts = {}) {
+    const nowIso = opts.nowIso ?? new Date().toISOString();
     let taskRows = allTasksForScope(db, filter);
     if (filter.epicId)
         taskRows = taskRows.filter((t) => t.epicId === filter.epicId);
@@ -1526,9 +1586,17 @@ export function flowGraph(db, filter = {}) {
     const scopedEdges = edgeRows.filter((e) => taskIds.has(e.taskId) && taskIds.has(e.dependsOn));
     const liveRows = allAgentsForScope(db, filter);
     const liveRoleByTask = new Map();
+    // The same last-write-wins walk, over the working rows only. Where a task
+    // carries both a stalled live row and a working one, the working role is
+    // the one to name: the marker says who is on the task, not who was
+    // dispatched to it most recently.
+    const workingRoleByTask = new Map();
     for (const a of liveRows) {
-        if (a.taskId)
-            liveRoleByTask.set(a.taskId, a.agentRole);
+        if (!a.taskId)
+            continue;
+        liveRoleByTask.set(a.taskId, a.agentRole);
+        if (isWorkingAt(a.dispatchedAt, nowIso))
+            workingRoleByTask.set(a.taskId, a.agentRole);
     }
     const waveMap = waveLayers([...taskIds], scopedEdges.map((e) => ({ task: e.taskId, dependsOn: e.dependsOn })));
     const nodes = taskRows.map((t) => ({
@@ -1536,6 +1604,7 @@ export function flowGraph(db, filter = {}) {
         taskStatus: t.taskStatus,
         title: t.objective,
         liveAgentRole: liveRoleByTask.get(t.taskId) ?? null,
+        workingAgentRole: workingRoleByTask.get(t.taskId) ?? null,
         planVersion: t.planVersion,
         wave: waveMap.get(t.taskId) ?? 0,
     }));

package/factory/orchestrator/dist/db/schema.js

@@ -189,6 +189,13 @@ export const findings = sqliteTable('findings', {
     raisedAt: text('raised_at').notNull(),
     updatedAt: text('updated_at').notNull(),
     project: text('project'), // Phase 6b — see eventsRaw's project comment above.
+    // What a spec finding is about (findings.ts SpecRef). The scope is filled
+    // in from findingScope(), so an absent field lands as 'diff' rather than
+    // as a null the reader has to know the default for; the two spec_ref
+    // columns are null on every diff finding because there is no criterion.
+    findingScope: text('finding_scope').notNull().default('diff'),
+    specPlanVersion: integer('spec_plan_version'),
+    criterionRef: text('criterion_ref'),
 }, (t) => [
     index('findings_session_idx').on(t.sessionId),
     index('findings_task_idx').on(t.taskId),

package/factory/orchestrator/dist/events.js

@@ -203,10 +203,20 @@ async function readEventsAtPath(filePath, sessionId) {
         .trimEnd()
         .split('\n')
         .filter((line) => line.length > 0);
-    return lines.map((line, index) => ({
-        event_id: `${sessionId}#${index}`,
-        record: JSON.parse(line),
-    }));
+    return lines.map((line, index) => {
+        let record;
+        try {
+            record = JSON.parse(line);
+        }
+        catch (err) {
+            // A bare SyntaxError says "Unexpected token" and nothing else: not which
+            // log, not which line. The dashboard prints this for every session it
+            // then fails to fold (the global folds read every log), so the message
+            // has to carry the path the operator needs to open.
+            throw new EventError('events.unreadable-session-log', `Line ${index + 1} of ${filePath} is not JSON, so session "${sessionId}" cannot be read: ${errorText(err)}.`, { session_id: sessionId, path: filePath, line: index + 1 });
+        }
+        return { event_id: `${sessionId}#${index}`, record };
+    });
 }
 /**
  * Per-log serialization *inside one process*: concurrent appendEvent calls on
@@ -504,7 +514,31 @@ function validatePayloadDimensions(taxonomy, record) {
 const TYPED_PAYLOAD_SCHEMAS = {
     'finding-raised': 'finding',
 };
+/**
+ * The one field of a `task-result-recorded` payload a reader iterates. The
+ * projector writes `artifacts[]` into rows inside the session's transaction,
+ * so an object here (csb-audit-1#100 carried `{ claude_half, external_half,
+ * repair_brief }`) rolled back the whole session and the dashboard drew
+ * nothing for it. Pinning only this field is deliberate: the full result
+ * schema is not enforced on the event, because real logs carry many
+ * hand-written result payloads that no reader rehydrates -- refusing them
+ * would refuse history for a shape nothing reads.
+ */
+function validateResultArtifactsShape(record) {
+    if (record.event_type !== 'task-result-recorded')
+        return;
+    const payload = record.payload;
+    const artifacts = payload?.artifacts;
+    if (artifacts === undefined || Array.isArray(artifacts))
+        return;
+    throw new EventError('events.invalid-typed-payload', 'Event payload for "task-result-recorded" carries an `artifacts` that is not an array. The projector iterates this list to write artifact rows, so any other shape becomes a crash that rolls back the whole session rather than an error here.', {
+        event_type: record.event_type,
+        schema: 'result',
+        errors: [{ path: '/artifacts', message: `must be an array, got ${typeof artifacts}` }],
+    });
+}
 function validateTypedPayload(schemas, taxonomy, record) {
+    validateResultArtifactsShape(record);
     const schemaName = TYPED_PAYLOAD_SCHEMAS[record.event_type];
     if (schemaName === undefined)
         return;

package/factory/orchestrator/dist/harness.js

@@ -0,0 +1,367 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { SmithError } from './errors.js';
+import { AGENTS_DIR, REPO_ROOT } from './paths.js';
+import { loadGuardrailPolicy } from './policy.js';
+import { loadTaxonomy } from './taxonomy.js';
+/**
+ * The worker harness port: *how* a turn runs, named at last.
+ *
+ * Every worker turn this factory has ever dispatched ran under one harness —
+ * Claude Code's `Agent` tool — and nothing anywhere says so. It is true by
+ * accident of deployment: the orchestrator is itself a Claude Code session, so
+ * the only thing it can spawn is another one. `dispatch_decision` records the
+ * role, the provider, the model tier and the model (P9-23), which is to say it
+ * records *who answered* and with *what weight*, and never *what ran the
+ * turn*. The two are independent axes and the factory has been folding them
+ * into one:
+ *
+ *   - **provider** — taxonomy.yml `provider: [claude, codex, deepseek]` — is
+ *     the vendor whose model produced the words.
+ *   - **harness** — this module — is the program that held the session: gave
+ *     the agent its tools, its working directory, its turn limit.
+ *
+ * `claude-code` + `claude` is the only pair that exists today. `codex-cli` +
+ * `codex` is the pair that makes the distinction load-bearing, and the point
+ * of writing the port before that pair exists is that the second harness
+ * should be a config entry and an invocation shape, not a rewrite of dispatch.
+ *
+ * ## This module renders an invocation. It never runs one.
+ *
+ * Architecture §18 rule 3 — "nothing that observes may dispatch". `smith` is
+ * an observer: it reads logs, folds them, and prints. If `smith harness plan`
+ * spawned the process it describes, the CLI would close its own loop, and
+ * every check that reads a `dispatch_decision` as evidence that a separate
+ * session ran would be reading evidence `smith` produced about itself.
+ *
+ * So `planWorkerTurn()` returns a `WorkerInvocation` — a description, in JSON,
+ * of a process someone else starts. The orchestrator session (or a runner that
+ * is not Claude Code at all) reads it and acts. That separation is the whole
+ * reason this is a port rather than a spawner.
+ *
+ * ## The default policy lives here, in code, on purpose
+ *
+ * There is no `factory/policies/harness.yml`, and this module does not name
+ * one. Two reasons, both checkable:
+ *
+ *   - Writing a policy file is the operator's decision, not a side effect of
+ *     adding a seam. The built-in policy below describes what the factory
+ *     already does; it invents no capability.
+ *   - paths.test.ts holds `factory/policies/` and `paths.ts` to each other in
+ *     both directions — a constant with no file on disk fails the build. A
+ *     path constant for a file we are not shipping would be exactly that.
+ *
+ * An operator who wants a second harness writes a YAML file wherever they like
+ * and names it: `--policy <file>`, the same shape `stack show` already uses.
+ * Absent that flag the built-in policy answers, which is the honest reading of
+ * a factory that has one harness.
+ *
+ * ## A cli harness is outside the trust boundary; a judge gets no worktree
+ *
+ * `providers/types.ts` states the rule for external judge transports: they are
+ * handed nothing but `prompt` — "no worktree paths, credentials beyond its own
+ * key, or anything callable". A `cli` harness is the same kind of thing one
+ * step over: a process this factory starts, on the far side of its own memory,
+ * holding whatever the command line hands it. So the same boundary applies,
+ * and `planWorkerTurn()` refuses to render a `cli` invocation that would put a
+ * worktree path in a judge role's hands (§18 rule 5, "Judges read; they never
+ * gain write access").
+ *
+ * An `in-process` harness is inside the boundary: a reviewer subagent does
+ * read the worktree, under a lease `smith sandbox open` holds for exactly as
+ * long as the verdict takes. The invocation says so — `sandboxRequired` is the
+ * obligation, stated where the caller will see it rather than left to the
+ * playbook to remember.
+ *
+ * Which roles are judges is not a list this file keeps. It is
+ * guardrails.yml's `judge_sandbox.roles` and `role_write_scopes.scopes`, read
+ * through policy.ts, which already refuses a role declared as both. A second
+ * hand-written copy here would be a copy that drifts, and the direction it
+ * would drift in is a judge quietly reclassified as a worker.
+ *
+ * ## Env is an allowlist of names. Values never pass through here.
+ *
+ * A harness that shells out needs credentials, and a rendered invocation is
+ * printed as JSON to a terminal and into logs. So the invocation carries the
+ * *names* a harness may read from the environment and never their values: the
+ * runner applies the allowlist against its own `process.env`. Naming a path
+ * and never a value is the same rule every artifact in this factory writes
+ * under.
+ */
+export class HarnessError extends SmithError {
+}
+/** The policy shape this module parses. Bumped when the YAML shape changes. */
+export const HARNESS_POLICY_VERSION = 1;
+/**
+ * What a rendered invocation is allowed to interpolate. Closed on purpose: a
+ * typo'd `{worktre}` in an args template would otherwise reach the runner as a
+ * literal argument, and a harness would start in the wrong directory rather
+ * than fail to start.
+ */
+const PLACEHOLDERS = ['prompt_file', 'worktree', 'role', 'task'];
+const PLACEHOLDER_RE = /\{([a-z_]+)\}/g;
+/**
+ * Today's factory, written down.
+ *
+ * One harness, serving every role, starting no program — because the Claude
+ * Code `Agent` tool is a call inside the orchestrator's own session, not an
+ * exec. `roles: []` rather than the fifteen taxonomy values: the constraint
+ * that actually binds is whether `.claude/agents/<role>.md` exists, and
+ * `planWorkerTurn()` checks that against the directory rather than against a
+ * list here that would go stale the next time a role is added.
+ */
+export const BUILT_IN_HARNESS_POLICY = Object.freeze({
+    version: HARNESS_POLICY_VERSION,
+    defaultHarness: 'claude-code',
+    harnesses: Object.freeze([
+        Object.freeze({
+            name: 'claude-code',
+            kind: 'in-process',
+            roles: Object.freeze([]),
+            command: null,
+            args: Object.freeze([]),
+            envAllowlist: Object.freeze([]),
+        }),
+    ]),
+    source: 'built-in',
+});
+function invalid(message, details) {
+    return new HarnessError('harness.invalid-policy', message, details);
+}
+function requireStringArray(raw, key) {
+    if (raw === undefined || raw === null)
+        return [];
+    if (!Array.isArray(raw) || raw.some((v) => typeof v !== 'string')) {
+        throw invalid(`harness policy ${key} is not a list of strings.`);
+    }
+    return raw;
+}
+/** Every placeholder an args template names, in order of appearance. */
+function placeholdersIn(text) {
+    return [...text.matchAll(PLACEHOLDER_RE)].map((m) => m[1]);
+}
+export function parseHarnessPolicy(yamlText) {
+    const doc = (parseYaml(yamlText) ?? {});
+    if (typeof doc !== 'object' || doc === null || Array.isArray(doc)) {
+        throw invalid('harness policy is not a mapping.');
+    }
+    const version = doc.version ?? HARNESS_POLICY_VERSION;
+    if (typeof version !== 'number' || !Number.isInteger(version)) {
+        throw invalid('harness policy `version` is not an integer.');
+    }
+    const rawHarnesses = doc.harnesses;
+    if (!Array.isArray(rawHarnesses) || rawHarnesses.length === 0) {
+        throw invalid('harness policy declares no `harnesses`. A file that names none says less than shipping no file at all, which is why the built-in policy is what answers when no --policy is given.');
+    }
+    const harnesses = [];
+    for (const [index, entry] of rawHarnesses.entries()) {
+        const key = `harnesses[${index}]`;
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+            throw invalid(`harness policy ${key} is not a mapping.`);
+        }
+        const item = entry;
+        const name = item.name;
+        if (typeof name !== 'string' || name === '') {
+            throw invalid(`harness policy ${key} is missing \`name\`.`);
+        }
+        if (harnesses.some((h) => h.name === name)) {
+            throw invalid(`harness policy declares "${name}" twice.`, { harness: name });
+        }
+        const kind = item.kind;
+        if (kind !== 'in-process' && kind !== 'cli') {
+            throw invalid(`harness policy ${key} has kind "${String(kind)}"; it is one of in-process, cli.`, { harness: name });
+        }
+        const args = requireStringArray(item.args, `${key}.args`);
+        const command = item.command ?? null;
+        if (kind === 'cli') {
+            if (typeof command !== 'string' || command === '') {
+                throw invalid(`harness policy ${key} is a cli harness with no \`command\`, so nothing would start.`, { harness: name });
+            }
+        }
+        else if (command !== null) {
+            // An in-process harness runs inside the caller's session. A command here
+            // would be a line nothing executes, read by the next person as a
+            // promise the port does not keep.
+            throw invalid(`harness policy ${key} is in-process but names a \`command\`; an in-process harness starts no program.`, { harness: name });
+        }
+        for (const arg of args) {
+            for (const found of placeholdersIn(arg)) {
+                if (!PLACEHOLDERS.includes(found)) {
+                    throw invalid(`harness policy ${key}.args names {${found}}, which no invocation substitutes. Known placeholders: ${PLACEHOLDERS.map((p) => `{${p}}`).join(', ')}.`, { harness: name, placeholder: found });
+                }
+            }
+        }
+        harnesses.push({
+            name,
+            kind,
+            roles: requireStringArray(item.roles, `${key}.roles`),
+            command: kind === 'cli' ? command : null,
+            args,
+            envAllowlist: requireStringArray(item.env, `${key}.env`),
+        });
+    }
+    const declaredDefault = doc.default;
+    const defaultHarness = declaredDefault === undefined || declaredDefault === null
+        ? harnesses[0].name
+        : declaredDefault;
+    if (typeof defaultHarness !== 'string' || defaultHarness === '') {
+        throw invalid('harness policy `default` is not a harness name.');
+    }
+    if (!harnesses.some((h) => h.name === defaultHarness)) {
+        throw invalid(`harness policy names "${defaultHarness}" as the default, and declares no harness by that name.`, { harness: defaultHarness });
+    }
+    return { version, defaultHarness, harnesses, source: 'file' };
+}
+/**
+ * The built-in policy, or the file the caller named.
+ *
+ * No default path: see the header. An absent `filePath` is not a missing file,
+ * it is the statement that this factory runs one harness.
+ */
+export function loadHarnessPolicy(filePath) {
+    if (filePath === undefined)
+        return BUILT_IN_HARNESS_POLICY;
+    if (!existsSync(filePath)) {
+        throw new HarnessError('harness.policy-not-found', `No harness policy at ${filePath}. Omit --policy to use the built-in one.`, { filePath });
+    }
+    return parseHarnessPolicy(readFileSync(filePath, 'utf8'));
+}
+export function roleAccess(role, guardrails = loadGuardrailPolicy()) {
+    if (guardrails.judgeSandbox.roles.includes(role))
+        return 'judge';
+    if (guardrails.roleWriteScopes.some((s) => s.role === role))
+        return 'write-scoped';
+    return 'worker';
+}
+/** Where a role's prompt template lives, and whether it is there. */
+function templateFor(role, agentsDir) {
+    const file = path.join(agentsDir, `${role}.md`);
+    return { file, exists: existsSync(file) };
+}
+function serves(harness, role) {
+    return harness.roles.length === 0 || harness.roles.includes(role);
+}
+function substitute(template, values, harness) {
+    return template.replace(PLACEHOLDER_RE, (_match, token) => {
+        const value = values[token];
+        if (value === undefined || value === null || value === '') {
+            throw new HarnessError('harness.missing-substitution', `Harness "${harness}" interpolates {${token}}, and this request carries no ${token.replace('_', ' ')}.`, { harness, placeholder: token });
+        }
+        return value;
+    });
+}
+/**
+ * Describe the process that would run this turn. Start nothing.
+ *
+ * Every refusal below is a fact the caller could not have checked cheaply:
+ * whether the role exists in the taxonomy, whether a template ships for it,
+ * whether the harness serves it, and whether handing it a worktree would cross
+ * the judge boundary. A runner that skips this call is not faster — it is
+ * making the same four decisions with none of them written down.
+ */
+export function planWorkerTurn(request, options = {}) {
+    const policy = options.policy ?? BUILT_IN_HARNESS_POLICY;
+    const guardrails = options.guardrails ?? loadGuardrailPolicy();
+    const taxonomy = options.taxonomy ?? loadTaxonomy();
+    const agentsDir = options.agentsDir ?? AGENTS_DIR;
+    const { role, taskId } = request;
+    const agentRoles = taxonomy.dimensions.agent ?? [];
+    if (!agentRoles.includes(role)) {
+        throw new HarnessError('harness.unknown-role', `"${role}" is not a taxonomy \`agent\` value, so no dispatch about it could be written even if the turn ran.`, { role });
+    }
+    if (taskId === undefined || taskId === '') {
+        throw new HarnessError('harness.missing-task', 'A worker turn is about a task; the invocation carries its id so the dispatch the caller writes can name the same one.', { role });
+    }
+    if (request.promptFile === undefined || request.promptFile === '') {
+        throw new HarnessError('harness.missing-prompt', 'A worker turn needs a prompt file. This port renders invocations, not prompts — write the prompt first (`smith prompt record`), then plan the turn that carries it.', { role });
+    }
+    const name = request.harness ?? policy.defaultHarness;
+    const harness = policy.harnesses.find((h) => h.name === name);
+    if (harness === undefined) {
+        throw new HarnessError('harness.unknown', `No harness named "${name}". This policy declares: ${policy.harnesses.map((h) => h.name).join(', ')}.`, { harness: name, declared: policy.harnesses.map((h) => h.name) });
+    }
+    if (!serves(harness, role)) {
+        throw new HarnessError('harness.role-not-served', `Harness "${harness.name}" serves ${harness.roles.join(', ')}, and not ${role}.`, { harness: harness.name, role });
+    }
+    const worktree = request.worktree ?? null;
+    const access = roleAccess(role, guardrails);
+    const base = {
+        harness: harness.name,
+        role,
+        taskId,
+        access,
+        promptFile: request.promptFile,
+        worktree,
+        sandboxRequired: access === 'judge' && worktree !== null,
+    };
+    if (harness.kind === 'in-process') {
+        const template = templateFor(role, agentsDir);
+        if (!template.exists) {
+            // D-191's reading, applied to the harness rather than to a grant: a
+            // role with no template reaches no agent. `operator` is the standing
+            // case — taxonomy.yml carries it as a `found_by` for a defect a person
+            // read off the code, and it is never dispatched.
+            throw new HarnessError('harness.no-template', `${role} ships no template at ${path.relative(REPO_ROOT, template.file)}, so an in-process harness has no agent to start.`, { role, template: path.relative(REPO_ROOT, template.file) });
+        }
+        return {
+            ...base,
+            kind: 'in-process',
+            subagentType: role,
+            template: path.relative(REPO_ROOT, template.file),
+        };
+    }
+    if (access === 'judge' && worktree !== null) {
+        // §18 rule 5, one step out from providers/types.ts. An external process
+        // holding a worktree path holds write access to it; no lease this side of
+        // the boundary can take that back.
+        throw new HarnessError('harness.judge-worktree', `Harness "${harness.name}" runs a separate program, and ${role} is a judge role. A judge outside this process gets the prompt and nothing else — a worktree path it holds is write access no sandbox lease can revoke (architecture §18 rule 5).`, { harness: harness.name, role });
+    }
+    const values = {
+        prompt_file: request.promptFile,
+        worktree,
+        role,
+        task: taskId,
+    };
+    return {
+        ...base,
+        kind: 'cli',
+        command: harness.command,
+        args: harness.args.map((arg) => substitute(arg, values, harness.name)),
+        cwd: worktree,
+        envAllowlist: harness.envAllowlist,
+    };
+}
+/**
+ * What `smith harness list` prints: not the policy as written, but the policy
+ * as it resolves. A harness whose `roles` is empty reads as "all" in YAML and
+ * means "every role that ships a template" in practice, and the difference
+ * between those two is the kind of thing an operator finds out at 2am
+ * otherwise.
+ */
+export function summarizeHarnesses(options = {}) {
+    const policy = options.policy ?? BUILT_IN_HARNESS_POLICY;
+    const taxonomy = options.taxonomy ?? loadTaxonomy();
+    const guardrails = options.guardrails ?? loadGuardrailPolicy();
+    const agentsDir = options.agentsDir ?? AGENTS_DIR;
+    const agentRoles = taxonomy.dimensions.agent ?? [];
+    return {
+        source: policy.source,
+        version: policy.version,
+        defaultHarness: policy.defaultHarness,
+        harnesses: policy.harnesses.map((harness) => ({
+            name: harness.name,
+            kind: harness.kind,
+            isDefault: harness.name === policy.defaultHarness,
+            roles: agentRoles.filter((role) => {
+                if (!serves(harness, role))
+                    return false;
+                if (harness.kind === 'in-process')
+                    return templateFor(role, agentsDir).exists;
+                return roleAccess(role, guardrails) !== 'judge';
+            }),
+            command: harness.command,
+            envAllowlist: harness.envAllowlist,
+        })),
+    };
+}