@juzser/blacksmith 0.1.0

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

@@ -0,0 +1,308 @@
+import { eventTaskId } from './events.js';
+import { epicOfTaskId } from './taskId.js';
+/**
+ * Live agent registry (architecture §7 "active agent count by role/model/
+ * provider"). An agent is live between its `dispatch_decision` event and
+ * whichever terminal event closes it: `task-result-recorded` (a worker's
+ * schema-valid Result landed — Phase 5 addition, see db/projector.ts header
+ * comment) or `error-logged` referencing the same task (an agent ref, per
+ * the task's terminal-event options).
+ *
+ * D-23/P9-12 — the correlation key is `(task_id, agent_role)`, not `task_id`
+ * alone. The old note here claimed "a real dispatcher never runs two agents
+ * on one task_id concurrently"; `/bs run` does exactly that, deliberately,
+ * up to four times per task (coder, grader, reviewer, security-reviewer).
+ * Under the old key each dispatch superseded the previous one, so in wave 3
+ * three agents that finished were recorded as abandoned and the fourth
+ * stayed `live` forever. `agent_id` is still only a label — the role is what
+ * the events already carry, so nothing new has to be threaded through.
+ *
+ * `round` rides along on the record because a judge redispatch is a genuine
+ * second round and the UI should be able to say which one it is looking at.
+ * It is deliberately NOT part of the key: a round-2 dispatch arriving while
+ * round 1 is still open means round 1 was given up on, and keying on the
+ * round would leave it live forever — the same bug, one level down.
+ *
+ * A second `dispatch_decision` for the same `(task_id, agent_role)` whose
+ * prior dispatch is STILL open (no terminal event yet — the escalation ladder
+ * redispatching without the first attempt reporting back) closes the old
+ * entry as `superseded` rather than leaving it orphaned at `live`: one role
+ * does not run twice on one task at once, so an open-on-redispatch entry is
+ * stale bookkeeping, not a genuinely live agent — counting it would corrupt
+ * the Overview live-agent count and detectStale().
+ *
+ * Terminal events name a role where they can: `task-result-recorded` carries
+ * the Result's `agent`, `judge-reported` carries `agent_role`, `judge-verdict`
+ * carries `agent` (D-160). One that names no role is a statement about the
+ * whole task — the queue blocking it, the gate refusing it — and closes every
+ * entry still open under that task, because after a task-level failure nobody
+ * is still running.
+ *
+ * Above all of those sits `epic-closed` (D-187). Every close named so far
+ * needs a task id to speak through, so an agent whose task simply never
+ * reported — and an epic-level dispatch, which has no task id to speak
+ * through at all — stayed `live` past the verdict, past the end of the run,
+ * forever. The epic's own terminal event is the only thing that can say
+ * otherwise, and it closes what is still open under that epic in that session
+ * as `abandoned`: not superseded (nothing replaced them) and not an error
+ * (they were never judged), just outrun by the run they belonged to.
+ */
+export const DISPATCH_EVENT_TYPE = 'dispatch_decision';
+/** Phase 5 addition (deviation, noted in the final report): the terminal counterpart to dispatch_decision. */
+export const TASK_RESULT_EVENT_TYPE = 'task-result-recorded';
+/**
+ * P9-11's judge half. A judge's return is its artifact, not a Result: it has
+ * no `token_usage`, and minting a zeroed one purely to reuse
+ * `task-result-recorded` would put fabricated numbers into the very rows
+ * budget accounting sums. So the registry learns a second terminal event
+ * rather than the event learning to lie.
+ */
+export const JUDGE_REPORT_EVENT_TYPE = 'judge-reported';
+/**
+ * The cross-provider judge's return (D-160). `recordJudgeRun` writes a real
+ * `dispatch_decision` for every external judge, deliberately, so the run shows
+ * up in the same registry and timeline as any other agent (architecture §7) —
+ * but an external judge never writes a Result and never closes a judge turn,
+ * so neither terminal event above could ever speak for it. Its terminal fact
+ * is the `judge-verdict` chained off its own dispatch, and until this was
+ * read, an API call that came back in eight seconds stayed `live` until the
+ * end of the session and turned up in `detectStale` hours later.
+ *
+ * The role is under `agent`, not `agent_role` — the key `recordJudgeRun`
+ * writes (quorum.ts) — which is why this close is spelled out rather than
+ * folded in with judge-reported.
+ */
+export const JUDGE_VERDICT_EVENT_TYPE = 'judge-verdict';
+export const ERROR_EVENT_TYPE = 'error-logged';
+/**
+ * The epic's own terminal fact (D-187). Every close above speaks for a single
+ * task, so an agent whose task never reported — and an epic-level dispatch,
+ * whose `task_id` is absent by design (event.schema.json: "absent for
+ * session-level or epic-level events") and which therefore has no task any
+ * close could name — stayed `live` for good. `epic-closed` is the one event
+ * that says the run those agents belong to is over: whatever was still open
+ * under that epic was abandoned when the verdict landed, not left running.
+ */
+export const EPIC_CLOSED_EVENT_TYPE = 'epic-closed';
+/**
+ * Every event type `foldAgents` acts on — the dispatch that opens an entry and
+ * every terminal that closes one. Exported for callers that slice the event
+ * log before folding it (D-161): a slice narrower than this list feeds the
+ * fold a history in which agents are dispatched and never finish, and the
+ * result is not a smaller answer but a wrong one. Anything that reuses the
+ * fold has to reuse its alphabet too.
+ */
+export const REGISTRY_EVENT_TYPES = [
+    DISPATCH_EVENT_TYPE,
+    TASK_RESULT_EVENT_TYPE,
+    JUDGE_REPORT_EVENT_TYPE,
+    JUDGE_VERDICT_EVENT_TYPE,
+    ERROR_EVENT_TYPE,
+    EPIC_CLOSED_EVENT_TYPE,
+];
+/** Runtime mirror of `AgentStatus` (a type-only union has nothing to iterate
+ * at runtime) — lets ui/test/taxonomy.test.ts assert its status->tone map
+ * covers this list exactly, same drift-guard pattern as roadmap.ts's
+ * MILESTONE_STATUSES. */
+export const AGENT_STATUSES = [
+    'live',
+    'done',
+    'error',
+    'superseded',
+    'abandoned',
+];
+const STATUS_FOR_TERMINAL = {
+    result: 'done',
+    error: 'error',
+    superseded: 'superseded',
+    abandoned: 'abandoned',
+};
+/** The open-entry key — the correlation pair, `(task_id, agent_role)`. */
+function openKey(taskId, role) {
+    return `${taskId}\u0000${role}`;
+}
+function closeEntry(open, eventId, ts, terminalType) {
+    open.terminalEventId = eventId;
+    open.terminalAt = ts;
+    open.terminalType = terminalType;
+    open.status = STATUS_FOR_TERMINAL[terminalType];
+}
+/**
+ * Close what this terminal event actually speaks for: one role when it names
+ * one, every open entry under the task when it does not.
+ */
+function closeOpen(open, taskId, role, eventId, ts, terminalType) {
+    if (role) {
+        const entry = open.get(openKey(taskId, role));
+        if (!entry)
+            return;
+        closeEntry(entry, eventId, ts, terminalType);
+        open.delete(openKey(taskId, role));
+        return;
+    }
+    for (const [key, entry] of open) {
+        if (entry.taskId !== taskId)
+            continue;
+        closeEntry(entry, eventId, ts, terminalType);
+        open.delete(key);
+    }
+}
+/**
+ * Fold a session's full event history into agent registry rows. Pure
+ * function over the event list — used identically by db/projector.ts's
+ * full rebuild and incremental apply paths (no separate incremental state
+ * machine to drift from this one).
+ */
+export function foldAgents(events) {
+    const open = new Map();
+    // Dispatches with no task id have no correlation key, so they cannot live in
+    // `open` — but they are still open, and `epic-closed` still speaks for them.
+    let openEpicLevel = [];
+    const records = [];
+    for (const { event_id, record } of events) {
+        if (record.event_type === DISPATCH_EVENT_TYPE) {
+            const payload = record.payload;
+            if (!payload.agent_role || !payload.provider || !payload.model_tier)
+                continue;
+            // Both levels, because a hand-written dispatch names its task in the
+            // payload and leaves the envelope null (D-245) — and D-244's rule that
+            // `task_id: ""` names no task now holds at either level. Read one level,
+            // or read `''` as an id, and the agent is filed as epic-level while
+            // every task-scoped terminal branch below stays guarded on the task id:
+            // nothing can ever close it. taskId.ts draws the same line for `''`.
+            const taskId = eventTaskId(record);
+            // A still-open dispatch for the same (task, role) is superseded, not
+            // left live forever — see the "second dispatch_decision" note above.
+            // Different roles on one task run side by side and are left alone.
+            if (taskId) {
+                closeOpen(open, taskId, payload.agent_role, event_id, record.ts, 'superseded');
+            }
+            const agent = {
+                id: event_id,
+                sessionId: record.session_id,
+                taskId,
+                // The payload's own claim first; otherwise the task id spells it. A
+                // bare task id (D-130) places nothing, and guessing is what the id
+                // rules exist to prevent, so it stays null.
+                epicId: payload.epic_id ?? (taskId ? epicOfTaskId(taskId) : null),
+                agentId: record.agent_id ?? null,
+                agentRole: payload.agent_role,
+                round: typeof payload.round === 'number' ? payload.round : 1,
+                provider: payload.provider,
+                modelTier: payload.model_tier,
+                dispatchedAt: record.ts,
+                terminalEventId: null,
+                terminalAt: null,
+                terminalType: null,
+                status: 'live',
+            };
+            records.push(agent);
+            if (taskId)
+                open.set(openKey(taskId, payload.agent_role), agent);
+            else
+                openEpicLevel.push(agent);
+            continue;
+        }
+        if (record.event_type === TASK_RESULT_EVENT_TYPE) {
+            // The Result names its author in `agent` (result.schema.json's required
+            // field). A hand-appended one that omits it still closes the task.
+            const payload = record.payload;
+            // Both levels: result.schema.json names the task in the payload, and the
+            // dispatch this closes may have named it only there too (D-245).
+            const taskId = eventTaskId(record);
+            if (taskId) {
+                closeOpen(open, taskId, payload.agent ?? null, event_id, record.ts, 'result');
+            }
+            continue;
+        }
+        if (record.event_type === JUDGE_REPORT_EVENT_TYPE) {
+            const payload = record.payload;
+            const taskId = eventTaskId(record);
+            if (taskId) {
+                closeOpen(open, taskId, payload.agent_role ?? null, event_id, record.ts, 'result');
+            }
+            continue;
+        }
+        if (record.event_type === JUDGE_VERDICT_EVENT_TYPE) {
+            const payload = record.payload;
+            const taskId = eventTaskId(record);
+            if (taskId) {
+                // A run that produced no schema-valid verdict did not do its job, and
+                // `ok: false` is how the log says so. Closing it as a result would let
+                // a provider failing every call read exactly like one answering every
+                // call — the distinction providerAgreement() exists to measure.
+                const terminal = payload.ok === false ? 'error' : 'result';
+                closeOpen(open, taskId, payload.agent ?? null, event_id, record.ts, terminal);
+            }
+            continue;
+        }
+        if (record.event_type === ERROR_EVENT_TYPE) {
+            const payload = record.payload;
+            // `task_ref` is this event's own spelling; eventTaskId covers the two
+            // the rest of the log uses (D-245).
+            const taskId = eventTaskId(record) ?? payload.task_ref;
+            if (taskId) {
+                closeOpen(open, taskId, payload.agent_role ?? null, event_id, record.ts, 'error');
+            }
+            continue;
+        }
+        if (record.event_type === EPIC_CLOSED_EVENT_TYPE) {
+            const payload = record.payload;
+            if (!payload.epic_id)
+                continue;
+            // Scoped to the session that closed the epic: another session's agents
+            // are not this verdict's to speak for. Within it, the epic each entry
+            // was dispatched for is now recorded (D-234), so the task-keyed half
+            // asks that instead of matching the id's prefix by hand.
+            for (const [key, entry] of open) {
+                if (entry.sessionId !== record.session_id)
+                    continue;
+                if (entry.epicId !== payload.epic_id)
+                    continue;
+                closeEntry(entry, event_id, record.ts, 'abandoned');
+                open.delete(key);
+            }
+            // The epic-level half keeps D-187's reasoning for an entry nothing
+            // places -- no task id and no `epic_id` on its dispatch means no other
+            // terminal event can ever name it, so the run's own verdict is the last
+            // thing that can close it. But an entry that DID name an epic is placed,
+            // and one session runs several epics in a row: sweeping the lot closed
+            // the next epic's planner, live and working, on the previous epic's
+            // verdict (D-234).
+            openEpicLevel = openEpicLevel.filter((entry) => {
+                if (entry.sessionId !== record.session_id)
+                    return true;
+                if (entry.epicId !== null && entry.epicId !== payload.epic_id)
+                    return true;
+                closeEntry(entry, event_id, record.ts, 'abandoned');
+                return false;
+            });
+        }
+    }
+    return records;
+}
+/** Default staleness threshold (hours) when the caller doesn't specify one. */
+export const DEFAULT_STALE_HOURS = 4;
+/**
+ * Still-live agents whose dispatch is older than `staleHours` as of `nowIso`
+ * (architecture §4 "live agent registry ... stale detection"). Pure over
+ * the fold's output — `nowIso` is threaded in rather than read from the
+ * clock so this is deterministic and testable.
+ */
+export function detectStale(agents, nowIso, staleHours = DEFAULT_STALE_HOURS) {
+    const now = new Date(nowIso).getTime();
+    const stale = [];
+    for (const agent of agents) {
+        if (agent.status !== 'live')
+            continue;
+        const dispatchedMs = new Date(agent.dispatchedAt).getTime();
+        const liveHours = (now - dispatchedMs) / (1000 * 60 * 60);
+        if (liveHours > staleHours)
+            stale.push({ ...agent, liveHours });
+    }
+    return stale;
+}
+/** Currently live agents (no terminal event yet), the overview page's "live agents" set. */
+export function liveAgents(agents) {
+    return agents.filter((a) => a.status === 'live');
+}

package/factory/orchestrator/dist/args.js

@@ -0,0 +1,84 @@
+/**
+ * argv → flags, positionals, and the flags nobody declared (D-131/D-132).
+ *
+ * This lived in cli.ts until D-131, which is most of why D-131 lived as long as
+ * it did: cli.ts calls `main()` at import time, so nothing here could be
+ * exercised except by building the binary and inferring the parse from a
+ * subcommand's output. `--flag=value` was therefore dropped on the floor by
+ * every command, and for a flag with a default the whole symptom was that the
+ * default won — exit 0, well-formed JSON, the wrong target read.
+ *
+ * usage.ts is the register of what each command accepts; this module is the
+ * only thing that reads a command line against it.
+ */
+/**
+ * Split `--name=value` at the FIRST `=`, so a value may contain one.
+ * Returns null for a token that is not a flag.
+ */
+function splitToken(arg) {
+    if (!arg.startsWith('--') || arg === '--')
+        return null;
+    const body = arg.slice(2);
+    const eq = body.indexOf('=');
+    if (eq < 0)
+        return { key: body, inlineValue: undefined };
+    // `--=x` names no flag; leave it to the unknown-flag path rather than
+    // inventing an empty-named one.
+    return { key: body.slice(0, eq), inlineValue: body.slice(eq + 1) };
+}
+export function parseArgs(argv, spec) {
+    const positional = [];
+    const flags = {};
+    const repeated = {};
+    const ordered = [];
+    const unknown = [];
+    const missingValue = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const token = splitToken(arg);
+        if (token === null) {
+            positional.push(arg);
+            continue;
+        }
+        const { key, inlineValue } = token;
+        const declared = spec === undefined ? undefined : spec.get(key);
+        if (spec !== undefined && declared === undefined && !unknown.includes(key))
+            unknown.push(key);
+        let value;
+        if (inlineValue !== undefined) {
+            value = inlineValue;
+        }
+        else if (declared === false) {
+            // Documented as taking nothing: whatever follows belongs to someone else.
+            value = 'true';
+        }
+        else if (spec !== undefined && declared === undefined) {
+            // An unknown flag is about to be refused. Consuming the token behind it
+            // would turn one clear "no such flag" into that plus a missing positional.
+            value = 'true';
+        }
+        else {
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith('--')) {
+                value = next;
+                i++;
+            }
+            else {
+                // Declared to take a value and handed none. `'true'` is still stored,
+                // so a caller that ignores the report parses exactly as it did before
+                // and cli.ts is the one place that has to refuse. `declared === true`
+                // is load-bearing: `undefined` here means no spec was given, and there
+                // `'true'` is the only answer available.
+                if (declared === true && !missingValue.includes(key))
+                    missingValue.push(key);
+                value = 'true';
+            }
+        }
+        flags[key] = value;
+        const seen = repeated[key] ?? [];
+        seen.push(value);
+        repeated[key] = seen;
+        ordered.push({ key, value });
+    }
+    return { positional, flags, repeated, ordered, unknown, missingValue };
+}

package/factory/orchestrator/dist/artifacts.js

@@ -0,0 +1,111 @@
+import { existsSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { SmithError } from './errors.js';
+import { STATE_ARTIFACTS_DIR } from './paths.js';
+/**
+ * Where a task's artifacts belong: `state/artifacts/<task-id>/`, beside
+ * `state/results/<task-id>.json`. One home per task, named by the task, so the
+ * evidence for a verdict is findable from the verdict without a search.
+ *
+ * `taskId` arrives from a worker-written result file, so it is not trusted to
+ * be a plain name: a `..` segment would compute a home outside the artifacts
+ * dir, and every later check would then be reporting about somewhere else.
+ */
+export function artifactHome(taskId, artifactsDir = STATE_ARTIFACTS_DIR) {
+    return homeUnder(path.resolve(artifactsDir), taskId);
+}
+function homeUnder(root, taskId) {
+    if (typeof taskId !== 'string' || taskId.trim() === '') {
+        throw new SmithError('artifacts.missing-task-id', `Cannot locate an artifact home without a task id (got ${JSON.stringify(taskId)}). A blank id resolves to ${root}, which holds every task's home — the check would then pass on any path at all.`, { task_id: taskId ?? null, artifacts_dir: root });
+    }
+    const home = path.resolve(root, taskId);
+    if (!contains(root, home)) {
+        throw new SmithError('artifacts.unsafe-task-id', `Task id '${taskId}' resolves outside the artifacts directory (${home}). A task id names a directory under ${root}; it cannot climb out of it.`, { task_id: taskId, artifacts_dir: root, resolved: home });
+    }
+    return home;
+}
+/**
+ * `realpathSync`, falling back to the lexical path. A path can exist and still
+ * fail to resolve — a permission wall on a parent is enough — and the answer
+ * to "did this leave the home" is then the lexical one rather than a throw out
+ * of a check that is supposed to return an issue list.
+ */
+function realOf(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+/** True when `child` is `root` itself or lives beneath it. */
+function contains(root, child) {
+    if (child === root)
+        return true;
+    const rel = path.relative(root, child);
+    return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+/**
+ * Check every path a result declares as evidence. Relative paths resolve
+ * against the task's home, so `coverage.txt` means the obvious thing and the
+ * short spelling is also the correct one.
+ *
+ * Two properties, in this order. Inside the home first: a path in the wrong
+ * place is wrong whether or not the file happens to be there today, and saying
+ * `missing` about a `/tmp` file that exists would be false. Then existence:
+ * an artifact that cannot be opened when the verdict is written is not
+ * evidence.
+ *
+ * Inside is asked twice, of two different things. `path.resolve` answers it
+ * about the string, which is what refuses `../elsewhere/coverage.txt`.
+ * `realpathSync` answers it about the file, which is what refuses the same
+ * file reached through a symlink named `evidence/` — and refuses a home that
+ * is itself a link into a worktree, where every relative path under it spells
+ * correctly and none of it survives the branch (D-193).
+ *
+ * Directories pass. An html coverage report and a Playwright trace are real
+ * artifacts and neither is a file. What this does not check is whether the
+ * bytes support the claim — that is a reviewer's job, not a stat call's.
+ */
+export function checkArtifacts(artifacts, opts) {
+    const root = path.resolve(opts.artifactsDir ?? STATE_ARTIFACTS_DIR);
+    const home = homeUnder(root, opts.taskId);
+    const issues = [];
+    // Where the home really is, and where it is supposed to be. They differ when
+    // the home is itself a link — into a worktree, say — and then every relative
+    // path under it spells correctly while none of it outlives the branch. A
+    // home that was never created cannot mislead anyone: nothing resolves
+    // through it, so every declaration under it comes back `missing` below.
+    const realHome = existsSync(home) ? realOf(home) : home;
+    const expectedHome = existsSync(home) ? homeUnder(realOf(root), opts.taskId) : home;
+    const homeEscaped = realHome !== expectedHome;
+    for (const decl of artifacts) {
+        const resolved = path.resolve(home, decl.path);
+        if (resolved === home) {
+            issues.push({ declared: decl.path, resolved, problem: 'no-path' });
+            continue;
+        }
+        if (!contains(home, resolved)) {
+            issues.push({ declared: decl.path, resolved, problem: 'outside-home' });
+            continue;
+        }
+        if (homeEscaped) {
+            const real = path.resolve(realHome, decl.path);
+            issues.push({ declared: decl.path, resolved: real, problem: 'outside-home' });
+            continue;
+        }
+        if (!existsSync(resolved)) {
+            issues.push({ declared: decl.path, resolved, problem: 'missing' });
+            continue;
+        }
+        // Asked of the file now, not of the string: `evidence/coverage.txt` is
+        // inside the home lexically and outside it in every sense that matters
+        // when `evidence` is a link. Report where it went, since an issue naming
+        // a correct-looking path is one the operator cannot act on.
+        const real = realOf(resolved);
+        if (!contains(realHome, real)) {
+            issues.push({ declared: decl.path, resolved: real, problem: 'outside-home' });
+        }
+    }
+    return { home, checked: artifacts.length, issues, ok: issues.length === 0 };
+}

package/factory/orchestrator/dist/attribution.js

@@ -0,0 +1,160 @@
+import { decideFindingAttribution, resolveFindingOwner, } from './claims.js';
+import { foldTasks } from './db/projector.js';
+import { appendEvent, readLineageEvents } from './events.js';
+import { computeFingerprint, reattributeFinding, } from './findings.js';
+import { emitFollowUpTask, followUpTaskId } from './taskEvents.js';
+import { requireEpicOfTaskId } from './taskId.js';
+/**
+ * Every epic this module derives becomes a durable artifact — the `epic_id`
+ * on a routed finding, and the `<epic>/followup-<fp>` id of a task that gets
+ * dispatched. So an id with no epic is refused here rather than answered with
+ * itself: `epicOf("task-1")` used to return "task-1", minting the follow-up
+ * `task-1/followup-ab12` under an epic that does not exist (D-49/P9-10).
+ */
+const epicOf = requireEpicOfTaskId;
+/** Every claim the ownership map records for a task id. */
+function claimsOf(taskId, ownership) {
+    return ownership.filter((t) => t.task_id === taskId).flatMap((t) => t.claims);
+}
+/**
+ * The claims a follow-up inherits (D-48/P9-31).
+ *
+ * A follow-up minted with only the file the finding named is a task that
+ * cannot fix the bug: the fix lands in the implementation AND its test, and
+ * the second edit is out of claim. So the follow-up inherits from whoever
+ * resolved its ownership — the owner's whole claim set when one task owns the
+ * file, the union of the candidates' sets when several could, and the named
+ * file alone only when nobody claims it and there is nothing to inherit.
+ *
+ * The candidate records carry only the single matching claim, so the full set
+ * is looked up by id in the ownership map. Sorted and de-duplicated: the
+ * claim set is a set, and a task spec that differs run to run is not one.
+ */
+function followUpClaims(owner, filePath, ownership) {
+    const inherited = owner.owner === 'resolved'
+        ? claimsOf(owner.taskId, ownership)
+        : owner.owner === 'ambiguous'
+            ? owner.candidates.flatMap((c) => claimsOf(c.taskId, ownership))
+            : [];
+    return inherited.length === 0 ? [filePath] : [...new Set(inherited)].sort();
+}
+/**
+ * Whether any finding's owner needs looking up in the log at all. Only one
+ * that resolves to a DIFFERENT task does — the common case is a judge speaking
+ * about the very task at the gate, and that case should not pay for a fold of
+ * the whole session.
+ */
+function needsTaskStatuses(items, ownership, defaultTaskId) {
+    return items.some((item) => {
+        const owner = resolveFindingOwner(item.filePath, ownership);
+        return owner.owner === 'resolved' && owner.taskId !== defaultTaskId;
+    });
+}
+/**
+ * Decide where each finding goes, writing nothing. Every id is derived (the
+ * follow-up's from the fingerprint), so a caller can compute the whole routing
+ * and then discard it if the finding turns out to be waived or refuted — and
+ * mint no task for a bug nobody is going to fix.
+ */
+export async function routeFindings(items, options, ctx, opts = {}) {
+    const { defaultTaskId, ownership } = options;
+    // Asked once, up front, so an epic that cannot be derived fails before any
+    // routing exists rather than on whichever finding happens to need it.
+    const defaultEpicId = options.epicId ?? epicOf(defaultTaskId);
+    const gated = (item) => ({
+        input: item,
+        attribution: 'gated',
+        taskId: defaultTaskId,
+        epicId: defaultEpicId,
+        fromTaskId: defaultTaskId,
+        reason: '',
+        claims: [],
+    });
+    if (ownership === undefined || ownership.length === 0)
+        return items.map(gated);
+    // Current status of every task the log knows about, folded once. A task the
+    // log has never heard of is simply absent, and reads as open: a task in the
+    // plan but not yet in the log is `todo`, not merged.
+    //
+    // The lineage's log (D-119), because "absent reads as open" is the reading
+    // that goes wrong across a session boundary: a task the parent session
+    // merged is absent from the child's, so a finding against it would be
+    // reassigned to a task that is already done rather than gated.
+    const statuses = needsTaskStatuses(items, ownership, defaultTaskId)
+        ? new Map(foldTasks(await readLineageEvents(ctx.sessionId, opts)).map((t) => [
+            t.taskId,
+            t.taskStatus,
+        ]))
+        : undefined;
+    return items.map((item) => {
+        const owner = resolveFindingOwner(item.filePath, ownership);
+        const decided = decideFindingAttribution(owner, defaultTaskId, (id) => statuses?.get(id));
+        if (decided.attribution === 'gated')
+            return gated(item);
+        if (decided.attribution === 'reassigned') {
+            return {
+                input: reattributeFinding(item, decided.taskId),
+                attribution: 'reassigned',
+                taskId: decided.taskId,
+                epicId: epicOf(decided.taskId),
+                fromTaskId: defaultTaskId,
+                reason: `${decided.taskId} claims ${decided.claim}; ${defaultTaskId} does not own this file.`,
+                claims: [],
+            };
+        }
+        const epicId = owner.owner === 'resolved' ? epicOf(owner.taskId) : defaultEpicId;
+        const taskId = followUpTaskId(epicId, computeFingerprint({
+            filePath: item.filePath,
+            category: item.finding.finding_category,
+            summary: item.finding.summary,
+        }));
+        return {
+            input: reattributeFinding(item, taskId),
+            attribution: 'follow-up',
+            taskId,
+            epicId,
+            fromTaskId: defaultTaskId,
+            reason: decided.reason,
+            claims: followUpClaims(owner, item.filePath, ownership),
+        };
+    });
+}
+/**
+ * Write the two facts a re-attributed finding produces: the follow-up task it
+ * needs (only when nobody open could take it), and the move itself. The
+ * `finding-reattributed` event is what makes a clean gate outcome readable —
+ * without it the log shows a finding under a task that was never gated, and no
+ * trace of how it got there.
+ *
+ * Call this only once the finding has survived intake. A waived or refuted
+ * finding minting a `todo` follow-up would block the epic verdict on a bug the
+ * team already settled.
+ */
+export async function recordReattribution(routed, finding, ctx, opts = {}) {
+    if (routed.attribution === 'gated')
+        return;
+    if (routed.attribution === 'follow-up') {
+        await emitFollowUpTask({
+            epicId: routed.epicId,
+            taskId: routed.taskId,
+            objective: `Fix: ${finding.summary}`,
+            claims: routed.claims,
+        }, ctx, opts);
+    }
+    await appendEvent({
+        session_id: ctx.sessionId,
+        actor: ctx.actor ?? 'system',
+        event_type: 'finding-reattributed',
+        task_id: routed.taskId,
+        plan_version: ctx.planVersion,
+        causal_parent: ctx.causalParent,
+        payload: {
+            from_task_id: routed.fromTaskId,
+            to_task_id: routed.taskId,
+            attribution: routed.attribution,
+            file_path: routed.input.filePath,
+            finding_id: finding.finding_id,
+            reason: routed.reason,
+        },
+    }, opts);
+}