@juzser/blacksmith 0.3.0 → 0.4.0

package/factory/orchestrator/dist/daemon.js

@@ -22,8 +22,9 @@ import { loadCrosscheckPolicy } from './crosscheck.js';
 import { apply, foldTasks, rebuild } from './db/projector.js';
 import { summariseEpicWidth, UNMEASURED_HINT } from './epicWidth.js';
 import { SmithError } from './errors.js';
-import { listSessionIds, mergeSessionLogs, parseEventId, readEvents, } from './events.js';
+import { listSessionIds, mergeSessionLogs, parseEventId } from './events.js';
 import { ageFindings, memoryOf } from './findingAge.js';
+import { LogCache } from './logCache.js';
 import { STATE_DAEMON_DIR, STATE_DB_PATH, STATE_EVENTS_DIR } from './paths.js';
 import { unwatchedProjects } from './projects.js';
 import { FACTORY_PROJECT } from './roadmap.js';
@@ -63,6 +64,20 @@ function admitFor(proposals, events, lens) {
 function staleSubject(agent) {
     return agent.taskId ?? agent.epicId ?? agent.agentId ?? agent.id;
 }
+/**
+ * The session an event id names, for a finding that has nothing better to key
+ * on than the id of the event that raised it. `null` on anything that is not
+ * a well-formed event id, rather than throwing — a proposal's origin is a
+ * nicety, not a fact `inspectSession` should die over.
+ */
+function originSessionId(eventId) {
+    try {
+        return parseEventId(eventId).sessionId;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Everything one session's lineage says about itself: spend against the epic
  * cap, dispatches nobody can be billed for, agents that never came back, and
@@ -119,10 +134,24 @@ export function inspectSession(sessionId, events, opts = {}) {
         });
     }
     for (const agent of detectStale(foldAgents(events), now.toISOString(), staleHours)) {
+        // Same rule as the budget check above, and the same reason: a closed
+        // epic's dispatch cannot still be live, so flagging it would raise the
+        // same line every tick until the log is archived. `foldAgents`'s own
+        // epic-closed handling only closes an entry against the session that
+        // closed it (D-234) — a dispatch and the epic's close can sit in
+        // different sessions of one lineage, which is exactly the shape this
+        // tick's merged log hands here, so the same-session fold alone would
+        // miss it.
+        if (agent.epicId !== null && closedEpics.has(agent.epicId))
+            continue;
         findings.push({
             kind: 'stale-agent',
             severity: 'attention',
-            sessionId,
+            // The dispatch's own session, not the tree's primary leaf: a fork
+            // asks inspectSession once for the whole tree, and the agent that
+            // never came back belongs to whichever session actually dispatched
+            // it.
+            sessionId: agent.sessionId,
             subject: staleSubject(agent),
             detail: `${agent.agentRole} (${agent.provider}/${agent.modelTier}) has been live for ` +
                 `${agent.liveHours.toFixed(1)}h with no result, error or supersession — past the ` +
@@ -142,7 +171,10 @@ export function inspectSession(sessionId, events, opts = {}) {
         findings.push({
             kind: 'spec-change',
             severity: proposal.blocking ? 'attention' : 'info',
-            sessionId,
+            // `proposalId` is the `spec-change-proposed` event's own id, so this is
+            // the session that actually raised the proposal — not the tree's
+            // primary leaf, which a fork may have picked for an unrelated sibling.
+            sessionId: originSessionId(proposal.proposalId) ?? sessionId,
             subject: proposal.taskId,
             detail: `${proposal.proposedBy} proposes amending ${proposal.criterionRef}: ${proposal.assumption} ` +
                 `(${proposal.severity}, ${proposal.blocking ? 'blocking' : 'non-blocking'}, ` +
@@ -150,15 +182,29 @@ export function inspectSession(sessionId, events, opts = {}) {
                 `${proposal.proposalId}\` or \`smith plan reject ${proposal.proposalId}\`.`,
         });
     }
-    const proposals = computeProposals({ events, now, policy: schedulerPolicy });
+    const proposals = computeProposals({
+        events,
+        now,
+        policy: schedulerPolicy,
+        ...(opts.resolveProjectForTaskRef === undefined
+            ? {}
+            : { resolveProjectForTaskRef: opts.resolveProjectForTaskRef }),
+        ...(opts.selfFallbackForTaskRef === undefined
+            ? {}
+            : { selfFallbackForTaskRef: opts.selfFallbackForTaskRef }),
+    });
     const admissions = admitFor(proposals, events, opts.admission);
+    // `TaskFoldRow.sessionId` is stamped once, the first time `touch()` builds
+    // the row, and never overwritten by a later touch — the task's origin
+    // session, not whichever one most recently merged or dispatched against it.
+    const taskSession = new Map(foldTasks(events).map((row) => [row.taskId, row.sessionId]));
     for (const [index, proposal] of proposals.entries()) {
         const admission = admissions[index];
         if (proposal.kind === 'recheck') {
             findings.push({
                 kind: 'recheck',
                 severity: 'info',
-                sessionId,
+                sessionId: taskSession.get(proposal.taskId) ?? sessionId,
                 subject: proposal.taskId,
                 detail: `Recheck due (${proposal.reasons.join(', ')}): ${proposal.mergeCount} later overlapping ` +
                     `merge(s), ${proposal.daysElapsed} day(s) elapsed, confidence ${proposal.confidence}.`,
@@ -172,13 +218,20 @@ export function inspectSession(sessionId, events, opts = {}) {
             // the discharge command below clears. Reported here and not in
             // inspectFactory because `issue-reported` lands in the error's own
             // session, so this lineage is the one that can answer it.
-            const project = proposal.project === FACTORY_PROJECT ? '' : ` (${proposal.project})`;
+            const project = proposal.project === null
+                ? ' (unresolved project)'
+                : proposal.project === FACTORY_PROJECT
+                    ? ''
+                    : ` (${proposal.project})`;
+            const projectPhrase = proposal.project === null ? 'an unresolved project' : `project ${proposal.project}`;
             findings.push({
                 kind: 'unreported-error',
                 severity: 'info',
-                sessionId,
+                // `report.session_id` — the session the error actually lives in, and
+                // the same one the detail text below already sends the operator to.
+                sessionId: proposal.sessionId,
                 subject: `error ${proposal.fingerprint}${project}`,
-                detail: `Error ${proposal.fingerprint} in project ${proposal.project} ` +
+                detail: `Error ${proposal.fingerprint} in ${projectPhrase} ` +
                     `(${proposal.errorClass}, task ${proposal.taskRef}, ${proposal.occurrences} occurrence(s)) ` +
                     'has no issue-reported event. Report it with ' +
                     `\`smith issues report --session ${proposal.sessionId}\`; ` +
@@ -208,6 +261,12 @@ export function inspectFactory(events, opts = {}) {
         policy,
         ...(opts.projectDirs === undefined ? {} : { projectDirs: opts.projectDirs }),
         ...(opts.readOutdated === undefined ? {} : { readOutdated: opts.readOutdated }),
+        ...(opts.resolveProjectForTaskRef === undefined
+            ? {}
+            : { resolveProjectForTaskRef: opts.resolveProjectForTaskRef }),
+        ...(opts.selfFallbackForTaskRef === undefined
+            ? {}
+            : { selfFallbackForTaskRef: opts.selfFallbackForTaskRef }),
     });
     const admissions = admitFor(proposals, events, opts.admission);
     for (const [index, proposal] of proposals.entries()) {
@@ -343,21 +402,29 @@ function errorMessage(err) {
 /**
  * One pass over the state directory.
  *
- * Two rules hold it together. It reads every log ONCE and folds lineages in
- * memory, so a five-session lineage reports one budget alarm rather than five
- * (D-119's argument, read from the other end). And no single unreadable log or
- * failed projection ends the tick: both become findings, because a watchdog
- * that dies on the first corrupt line is a watchdog that is silent exactly
- * when something is wrong.
+ * Two rules hold it together. It reads every log ONCE and folds each lineage
+ * TREE in memory — not once per leaf — so a five-session chain reports one
+ * budget alarm rather than five (D-119's argument, read from the other end),
+ * and a base session that forked into several wave children reports it once
+ * rather than once per sibling. And no single unreadable log or failed
+ * projection ends the tick: both become findings, because a watchdog that
+ * dies on the first corrupt line is a watchdog that is silent exactly when
+ * something is wrong.
  */
 export async function runTick(opts = {}) {
     const now = opts.now ?? new Date();
     const stateDir = opts.stateDir ?? STATE_EVENTS_DIR;
     const findings = [];
+    // No shared cache passed in: a fresh one is cold for every session, so this
+    // reads identically to the old `readEvents`-per-session loop — one full
+    // read per log, this call only.
+    const cache = opts.logCache ?? new LogCache();
     const logs = new Map();
+    const liveSessionIds = new Set();
     for (const sessionId of listSessionIds(stateDir)) {
+        liveSessionIds.add(sessionId);
         try {
-            logs.set(sessionId, await readEvents(sessionId, { stateDir }));
+            logs.set(sessionId, await cache.read(sessionId, { stateDir }));
         }
         catch (err) {
             findings.push({
@@ -369,6 +436,13 @@ export async function runTick(opts = {}) {
             });
         }
     }
+    // Sessions that disappear from `listSessionIds` are evicted here, on the
+    // next tick, so the cache's memory is bounded by live logs, not by
+    // history. Driven by the LISTED set, not the read-succeeded set: a session
+    // that is listed but unreadable this tick keeps its entry. On a fresh,
+    // unshared cache (`opts.logCache` undefined) this is a no-op -- nothing
+    // was cached to evict.
+    cache.retainOnly(liveSessionIds);
     const parentOf = new Map();
     for (const [sessionId, events] of logs) {
         const root = events.find((e) => e.record.event_type === ROOT_EVENT_TYPE);
@@ -390,17 +464,59 @@ export async function runTick(opts = {}) {
             ancestors.add(parent);
     }
     const leaves = [...logs.keys()].filter((id) => !ancestors.has(id)).sort();
-    const lineageOf = (leaf) => {
-        const chain = [];
+    // parentOf inverted: a session's immediate children among the sessions this
+    // tick loaded. Lets a shared ancestor's descendants be walked forward once,
+    // instead of re-walked backward once per leaf below it.
+    const childrenOf = new Map();
+    for (const [childId, parent] of parentOf) {
+        if (parent === null || !logs.has(parent))
+            continue;
+        const siblings = childrenOf.get(parent) ?? [];
+        siblings.push(childId);
+        childrenOf.set(parent, siblings);
+    }
+    // The furthest ancestor of `id` that this tick still holds a log for — the
+    // root of the tree `id` belongs to, and the same root for every session in
+    // that tree regardless of which leaf asks.
+    const rootOf = (id) => {
+        let current = id;
         const seen = new Set();
-        let current = leaf;
-        while (current !== null && logs.has(current) && !seen.has(current)) {
+        while (true) {
+            const parent = parentOf.get(current) ?? null;
+            if (parent === null || !logs.has(parent) || seen.has(current))
+                return current;
             seen.add(current);
-            chain.unshift(current);
-            current = parentOf.get(current) ?? null;
+            current = parent;
         }
-        return chain.map((sessionId) => ({ sessionId, events: logs.get(sessionId) ?? [] }));
     };
+    // Every session reachable from `root` by walking children — the whole tree
+    // a lineage forks into, not just the one leaf that happened to ask for it.
+    // Guarded like rootOf: a cycle in causal parents must cost a tick nothing,
+    // not grow this list until the process dies.
+    const treeSessions = (root) => {
+        const all = [root];
+        const seen = new Set(all);
+        for (let i = 0; i < all.length; i += 1) {
+            for (const child of childrenOf.get(all[i]) ?? []) {
+                if (seen.has(child))
+                    continue;
+                seen.add(child);
+                all.push(child);
+            }
+        }
+        return all;
+    };
+    // Leaves grouped by the tree they fork from. A base session with several
+    // wave children is one tree with several leaves — inspected once, not once
+    // per sibling, so the shared ancestor's findings are not re-emitted once
+    // per fork (the D-119 argument, which a single chain never forks to break).
+    const leavesByRoot = new Map();
+    for (const leaf of leaves) {
+        const root = rootOf(leaf);
+        const group = leavesByRoot.get(root) ?? [];
+        group.push(leaf);
+        leavesByRoot.set(root, group);
+    }
     // A tick reports the admission line by default, where `inspectSession` and
     // `inspectFactory` stay silent unless asked. The asymmetry is deliberate: a
     // caller who reaches for one function is answering their own question and
@@ -422,6 +538,12 @@ export async function runTick(opts = {}) {
         ...(opts.projectDirs === undefined ? {} : { projectDirs: opts.projectDirs }),
         ...(opts.readOutdated === undefined ? {} : { readOutdated: opts.readOutdated }),
         ...(opts.readProjects === undefined ? {} : { readProjects: opts.readProjects }),
+        ...(opts.resolveProjectForTaskRef === undefined
+            ? {}
+            : { resolveProjectForTaskRef: opts.resolveProjectForTaskRef }),
+        ...(opts.selfFallbackForTaskRef === undefined
+            ? {}
+            : { selfFallbackForTaskRef: opts.selfFallbackForTaskRef }),
     };
     const projectDb = opts.projectDb ?? true;
     const dbPath = opts.dbPath ?? STATE_DB_PATH;
@@ -437,16 +559,55 @@ export async function runTick(opts = {}) {
         detail: `The read-model refresh failed: ${errorMessage(err)}. The event log is unaffected — ` +
             'it is the UI and `smith status` that are now stale.',
     });
-    for (const leaf of leaves) {
-        findings.push(...inspectSession(leaf, mergeSessionLogs(lineageOf(leaf)), inspectOpts));
-        if (!projectDb)
-            continue;
-        try {
-            await apply(dbPath, leaf, dbOpts);
-            projected += 1;
+    for (const [root, group] of leavesByRoot) {
+        // Sorted, so a forked tree attributes its shared findings to the same
+        // leaf on every tick, rather than whichever one Map iteration hands back
+        // first — the same determinism `leaves` itself already sorts for.
+        const primary = [...group].sort()[0];
+        const merged = mergeSessionLogs(treeSessions(root).map((sessionId) => ({ sessionId, events: logs.get(sessionId) ?? [] })));
+        findings.push(...inspectSession(primary, merged, inspectOpts));
+    }
+    // The signature a leaf's projection was last applied against: every
+    // session in its own upward chain, keyed by the fingerprint the cache read
+    // it at. Two ticks that see the same fingerprints for the same chain saw
+    // no change anywhere that leaf's own projection or lineage-scoped folds
+    // depend on, so re-applying would write the same rows a second time.
+    // `opts.logCache === undefined` opts a caller all the way out: with no
+    // cache to remember a signature against, every leaf is applied every tick,
+    // unchanged from before this cache existed.
+    const leafSignature = (leaf) => {
+        const chain = [];
+        const seen = new Set();
+        let current = leaf;
+        while (current !== null && !seen.has(current)) {
+            seen.add(current);
+            chain.push(current);
+            const parent = parentOf.get(current) ?? null;
+            current = parent !== null && logs.has(parent) ? parent : null;
         }
-        catch (err) {
-            findings.push(projectionFailed(leaf, err));
+        return chain
+            .map((id) => {
+            const fp = cache.fingerprintOf(id);
+            return fp === undefined ? `${id}:?` : `${id}:${fp.dev}.${fp.ino}.${fp.size}.${fp.mtimeMs}`;
+        })
+            .join('|');
+    };
+    const applyFn = opts.applyFn ?? apply;
+    if (projectDb) {
+        for (const leaf of leaves) {
+            const signature = opts.logCache === undefined ? undefined : leafSignature(leaf);
+            if (signature !== undefined && opts.logCache?.getAppliedSignature(leaf) === signature) {
+                continue;
+            }
+            try {
+                await applyFn(dbPath, leaf, dbOpts);
+                projected += 1;
+                if (signature !== undefined)
+                    opts.logCache?.setAppliedSignature(leaf, signature);
+            }
+            catch (err) {
+                findings.push(projectionFailed(leaf, err));
+            }
         }
     }
     // The read-model is not made of sessions alone. `milestones` is a full
@@ -683,6 +844,10 @@ export async function runDaemon(opts) {
     const tick = opts.tick ?? runTick;
     const sleep = opts.sleep ?? defaultSleep;
     const shouldContinue = opts.shouldContinue ?? (() => true);
+    // One cache for the whole run: this is the loop finding 50acc356 is about
+    // — the process that survives long enough for "every tick re-reads every
+    // byte ever written" to matter.
+    const logCache = opts.logCache ?? new LogCache();
     acquireLock(opts.dir, { pid, startedAt, intervalSeconds }, opts.isAlive === undefined ? {} : { isAlive: opts.isAlive });
     const tickOptions = {
         ...(opts.now === undefined ? {} : { now: opts.now }),
@@ -695,6 +860,8 @@ export async function runDaemon(opts) {
         ...(opts.projectDb === undefined ? {} : { projectDb: opts.projectDb }),
         ...(opts.dbPath === undefined ? {} : { dbPath: opts.dbPath }),
         ...(opts.dbOpts === undefined ? {} : { dbOpts: opts.dbOpts }),
+        ...(opts.applyFn === undefined ? {} : { applyFn: opts.applyFn }),
+        logCache,
     };
     // Read from disk rather than held in a variable, so a daemon restarted by
     // cron or by the operator picks up where the last process stopped. A tick

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

@@ -396,23 +396,46 @@ function waveTaskIds(record) {
     const taskId = eventTaskId(record);
     return taskId ? [taskId] : [];
 }
+/**
+ * The tasks one error-logged event names: the envelope/payload `task_id`
+ * (D-245) when the producer set one, else `payload.task_ref` split on `,`
+ * and each part trimmed. A comma joins several real ids into one string
+ * when a producer logged a single check's failure against more than one
+ * task at once — events.ts's append-time guard now refuses to write that
+ * shape, but a log written before the guard existed still carries it, and
+ * foldTasks() replays every log ever written. Splitting here, not only in
+ * assertedTaskIds()'s pre-pass, is what keeps the two agreeing on what the
+ * event names (see that function's own comment) — a fix that touched one
+ * and not the other used to mint a card whose id was the literal
+ * "epic-1/task-1,epic-1/task-2" string.
+ */
+function errorTaskRefIds(record) {
+    const envelopeId = eventTaskId(record);
+    if (envelopeId)
+        return [envelopeId];
+    const ref = record.payload.task_ref;
+    if (!ref)
+        return [];
+    return ref
+        .split(',')
+        .map((id) => id.trim())
+        .filter(Boolean);
+}
 /**
  * The task ids one event asserts something about, spelled the way foldTasks()'s
  * switch reads them: the envelope or payload `task_id` (D-245) for the
  * single-task events, `payload.task_ids` for a wave's admission or merge, and
- * `error-logged`'s own `payload.task_ref`. Kept beside the switch on purpose —
- * the two must agree on what names a task, or the walk touches an id the
- * pre-pass never saw.
+ * `error-logged`'s own `payload.task_ref` (or its comma-joined list — see
+ * errorTaskRefIds()). Kept beside the switch on purpose — the two must agree
+ * on what names a task, or the walk touches an id the pre-pass never saw.
  */
 function assertedTaskIds(record) {
     switch (record.event_type) {
         case 'wave-admitted':
         case 'wave-merged':
             return waveTaskIds(record);
-        case 'error-logged': {
-            const id = eventTaskId(record) ?? record.payload.task_ref;
-            return id ? [id] : [];
-        }
+        case 'error-logged':
+            return errorTaskRefIds(record);
         case 'task-added':
         case 'gate-outcome':
         case 'task-superseded': {
@@ -606,26 +629,27 @@ export function foldTasks(events, opts = {}) {
             }
             case 'error-logged': {
                 const p = record.payload;
-                // `task_ref` is this event's own spelling; eventTaskId covers the two
-                // the rest of the log uses (D-245).
-                const taskId = eventTask ?? p.task_ref;
-                if (!taskId)
-                    break;
-                const row = touch(taskId, record.ts, record.session_id);
-                row.project = record.project ?? row.project;
-                if (TERMINAL_TASK_STATUSES.has(row.taskStatus))
-                    break;
-                // Severity decides whether the task moves; the error class decides
-                // where. taxonomy.yml: S3 is "real but waivable; batched to operator
-                // at epic end", S4 is "logged, never asked" — a budget note or a
-                // tool hiccup at that level is on the record but the task carries on,
-                // and showing it as blocked is what the board did for 43 of the 55
-                // errors logged so far. A record with no severity is treated as
-                // major: the write path requires the field, so its absence means a
-                // log this reader does not own.
-                if (NOTE_ONLY_SEVERITIES.has(p.severity ?? ''))
-                    break;
-                row.taskStatus = p.error?.startsWith('coordination.') ? 'escalated' : 'blocked';
+                // errorTaskRefIds() is this event's own spelling (D-245's envelope
+                // reader, or a comma-joined `task_ref` split into its real ids) —
+                // shared with assertedTaskIds()'s pre-pass so the two agree.
+                const taskIds = errorTaskRefIds(record);
+                for (const taskId of taskIds) {
+                    const row = touch(taskId, record.ts, record.session_id);
+                    row.project = record.project ?? row.project;
+                    if (TERMINAL_TASK_STATUSES.has(row.taskStatus))
+                        continue;
+                    // Severity decides whether the task moves; the error class decides
+                    // where. taxonomy.yml: S3 is "real but waivable; batched to operator
+                    // at epic end", S4 is "logged, never asked" — a budget note or a
+                    // tool hiccup at that level is on the record but the task carries on,
+                    // and showing it as blocked is what the board did for 43 of the 55
+                    // errors logged so far. A record with no severity is treated as
+                    // major: the write path requires the field, so its absence means a
+                    // log this reader does not own.
+                    if (NOTE_ONLY_SEVERITIES.has(p.severity ?? ''))
+                        continue;
+                    row.taskStatus = p.error?.startsWith('coordination.') ? 'escalated' : 'blocked';
+                }
                 break;
             }
             default:

package/factory/orchestrator/dist/dispatchLint.js

@@ -0,0 +1,132 @@
+/**
+ * `smith dispatch lint` — check a dispatch prompt against two things a
+ * dispatcher can get wrong without any signal until the agent runs:
+ *
+ *   - the turn budget stated in the prompt vs the role template's
+ *     `maxTurns:`, read fresh off disk (dispatch.md "Carry into the
+ *     prompt" — a prompt that promises more than the template is a fiction
+ *     the agent plans against and gets cut in the middle of).
+ *   - a judge prompt's declared-artifact line vs what the ledger recorded
+ *     for its `judge dispatch` (dispatch.md "Declare each judge's
+ *     artifact" — a judge prompt missing that line is undetectable until
+ *     the report never lands).
+ *
+ * Both parsers and both comparisons live here so the two checks stay one
+ * source of truth for "what does a compliant dispatch prompt say", rather
+ * than every dispatcher re-deriving it.
+ */
+import path from 'node:path';
+import { readTemplateMaxTurns } from './agentsSync.js';
+import { readJudgeTurns } from './judges.js';
+import { AGENTS_DIR } from './paths.js';
+/**
+ * The epic criterion's six judge roles (task 5 and task 6 objectives both
+ * name this exact set: spec-reviewer, reviewer, verifier, grader,
+ * security-reviewer, auditor) -- the roles whose dispatch declares an
+ * artifact and whose SubagentStop is guarded by judge-stop.sh. Kept as its
+ * own list rather than read out of judges.ts: `foldJudgeTurns` folds any
+ * role with a `declared_artifact` on its dispatch into a turn, but this
+ * module is stricter on purpose — only these six get an artifact check, so
+ * a coder's dispatch (never carries one) reads `not-applicable` rather than
+ * a false `undeclared`.
+ *
+ * Not the same six as dispatch.md's "Fingerprint the worktree around every
+ * judge" list, which swaps `auditor` for `uiux`: that section is about
+ * which judges run inside a task's worktree (auditor runs over a whole
+ * project at HEAD, never per-task, so a worktree fingerprint does not apply
+ * to it; uiux does run per-task). This list is about which roles owe a
+ * declared artifact and a blocked Stop, and `auditor` is one of them.
+ */
+export const JUDGE_ROLES = [
+    'reviewer',
+    'verifier',
+    'grader',
+    'spec-reviewer',
+    'security-reviewer',
+    'auditor',
+];
+const JUDGE_ROLE_SET = new Set(JUDGE_ROLES);
+const TURN_BUDGET_LINE = /Turn budget:[ \t]*(\S*)/g;
+/**
+ * `Turn budget: <n>` in a dispatch prompt — mid-sentence or on its own
+ * line, since a dispatch's leading line names the role and the budget in
+ * one breath ("Role: coder. Turn budget: 40 ..."). Null for no occurrence,
+ * more than one (two numbers is no number), or a value that is not a bare
+ * non-negative integer — every one of those is "cannot state a turn count",
+ * not "states zero".
+ */
+export function parseStatedTurns(prompt) {
+    const matches = [...prompt.matchAll(TURN_BUDGET_LINE)];
+    if (matches.length !== 1)
+        return null;
+    const raw = matches[0]?.[1] ?? '';
+    return /^[0-9]+$/.test(raw) ? Number(raw) : null;
+}
+const DECLARED_ARTIFACT_LINE = /^Declared artifact:[ \t]*(\S+)[ \t]*$/m;
+/** `Declared artifact: <path>` in a dispatch prompt, or null when the line is not there. */
+export function parseDeclaredArtifactLine(prompt) {
+    const match = DECLARED_ARTIFACT_LINE.exec(prompt);
+    return match?.[1] ?? null;
+}
+/** The line a dispatch is expected to carry verbatim, given the ledger's declared path. */
+export function formatDeclaredArtifactLine(artifactPath) {
+    return `Declared artifact: ${artifactPath}`;
+}
+function checkTurns(prompt, role, agentsDir) {
+    const stated = parseStatedTurns(prompt);
+    const template = readTemplateMaxTurns(agentsDir, role) ?? null;
+    if (template === null)
+        return { status: 'unverifiable', stated, template: null };
+    if (stated === null)
+        return { status: 'missing', stated: null, template };
+    if (stated === template)
+        return { status: 'ok', stated, template };
+    return { status: stated < template ? 'under' : 'over', stated, template };
+}
+async function checkArtifact(prompt, role, taskId, sessionId, eventOpts) {
+    if (!JUDGE_ROLE_SET.has(role)) {
+        return { status: 'not-applicable', expected_line: null, declared_line: null };
+    }
+    const declaredLine = parseDeclaredArtifactLine(prompt);
+    const turns = await readJudgeTurns(taskId, { sessionId }, eventOpts);
+    const turn = turns.find((t) => t.role === role);
+    if (turn === undefined) {
+        return { status: 'undeclared', expected_line: null, declared_line: declaredLine };
+    }
+    const expectedLine = formatDeclaredArtifactLine(turn.declaredArtifact);
+    if (declaredLine === null) {
+        return { status: 'missing', expected_line: expectedLine, declared_line: null };
+    }
+    if (declaredLine === turn.declaredArtifact) {
+        return { status: 'ok', expected_line: expectedLine, declared_line: declaredLine };
+    }
+    if (!path.isAbsolute(declaredLine)) {
+        return { status: 'relative', expected_line: expectedLine, declared_line: declaredLine };
+    }
+    return { status: 'mismatch', expected_line: expectedLine, declared_line: declaredLine };
+}
+// Fail closed: every status but "ok" exits non-zero, including "under" (a
+// prompt that understates the template's budget still disagrees with it) and
+// "unverifiable" (an unreadable template is not a pass, exactly like `dispatch
+// check`, `tester check`, `delegation check`, and `escalation check` already
+// treat "cannot tell" as a failure, never a maybe).
+const TURNS_FAIL = new Set(['under', 'over', 'missing', 'unverifiable']);
+const ARTIFACT_FAIL = new Set([
+    'missing',
+    'relative',
+    'mismatch',
+    'undeclared',
+]);
+/**
+ * Lint one dispatch prompt. Never throws on a bad prompt — a bad prompt is
+ * exactly the finding this reports — only on a missing task/session (the
+ * caller's own mistake, same as every other verb that reads the ledger).
+ */
+export async function lintDispatchPrompt(input) {
+    const agentsDir = input.agentsDir ?? AGENTS_DIR;
+    const eventOpts = input.eventOpts ?? {};
+    const turns = checkTurns(input.prompt, input.role, agentsDir);
+    const artifact = await checkArtifact(input.prompt, input.role, input.taskId, input.sessionId, eventOpts);
+    const exitCode = TURNS_FAIL.has(turns.status) || ARTIFACT_FAIL.has(artifact.status) ? 1 : 0;
+    return { turns, artifact, exitCode };
+}