@wardby/cli 0.3.0 → 0.4.1

package/dist/core/cost-report.js

@@ -0,0 +1,248 @@
+/**
+ * Cost by issue / parent / scope / agent / model / run over a time window
+ * (docs/private/2026-10-01-issue-cost-attribution-design.md §7). Rows count
+ * attributed runs only; unattributed spend is reported separately so the gap
+ * is visible. Money is summed as NUMERIC in SQL and returned as strings; tokens
+ * are always by priced kind, never one total.
+ */
+import { Prisma } from "#prisma";
+const GROUP_BYS = ["issue", "parent", "scope", "agent", "model", "run"];
+const DEFAULT_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
+const DEFAULT_LIMIT = 25;
+const MAX_LIMIT = 200;
+export class CostReportInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CostReportInputError";
+    }
+}
+function optionalString(args, name) {
+    const v = args[name];
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== "string" || v.length === 0 || v.length > 256) {
+        throw new CostReportInputError(`${name} must be a non-empty string.`);
+    }
+    return v;
+}
+function optionalDate(args, name) {
+    const v = args[name];
+    if (v === undefined)
+        return undefined;
+    const d = typeof v === "string" ? new Date(v) : new Date(NaN);
+    if (Number.isNaN(d.getTime()))
+        throw new CostReportInputError(`${name} must be an ISO date.`);
+    return d;
+}
+export function parseCostReportQuery(raw, now = new Date()) {
+    const args = raw && typeof raw === "object" ? raw : {};
+    const groupBy = (args.groupBy ?? "issue");
+    if (!GROUP_BYS.includes(groupBy)) {
+        throw new CostReportInputError(`groupBy must be one of: ${GROUP_BYS.join(", ")}.`);
+    }
+    const to = optionalDate(args, "to") ?? now;
+    const from = optionalDate(args, "from") ?? new Date(to.getTime() - DEFAULT_WINDOW_MS);
+    if (from.getTime() >= to.getTime())
+        throw new CostReportInputError("from must be before to.");
+    let limit = DEFAULT_LIMIT;
+    if (args.limit !== undefined) {
+        if (typeof args.limit !== "number" || !Number.isInteger(args.limit) || args.limit < 1) {
+            throw new CostReportInputError("limit must be a positive integer.");
+        }
+        limit = Math.min(args.limit, MAX_LIMIT);
+    }
+    const q = { groupBy, from, to, limit };
+    for (const name of ["provider", "scopeKey", "parentKey", "issueKey", "agentId"]) {
+        const v = optionalString(args, name);
+        if (v !== undefined)
+            q[name] = v;
+    }
+    return q;
+}
+const NO_PARENT = "(no parent)";
+/** NUMERIC text → canonical decimal string without trailing zeros ("3.100000" → "3.1", null → "0"). */
+function usd(v) {
+    if (v == null)
+        return "0";
+    return v.includes(".") ? v.replace(/0+$/, "").replace(/\.$/, "") : v;
+}
+const kinds = (r) => ({
+    freshInput: Number(r?.fresh ?? 0),
+    cachedInput: Number(r?.cached ?? 0),
+    cacheWrite: Number(r?.write ?? 0),
+    output: Number(r?.out ?? 0),
+});
+/** The run filter every query shares: window, visibility, and the agent filter. Only `r` must be in scope. */
+function runFilter(q, vis) {
+    const parts = [Prisma.sql `r."startedAt" >= ${q.from} AND r."startedAt" < ${q.to}`];
+    if (vis) {
+        parts.push(vis.ownedAgentIds.length > 0
+            ? Prisma.sql `(r."agentId" IN (${Prisma.join(vis.ownedAgentIds)}) OR r."triggeredById" = ${vis.principalId})`
+            : Prisma.sql `r."triggeredById" = ${vis.principalId}`);
+    }
+    if (q.agentId)
+        parts.push(Prisma.sql `r."agentId" = ${q.agentId}`);
+    return Prisma.join(parts, " AND ");
+}
+/** The work-item filters; `a` (RunAttribution) and `w` (WorkItem) must be joined. */
+function attributionFilter(q) {
+    const parts = [Prisma.sql `TRUE`];
+    if (q.provider)
+        parts.push(Prisma.sql `w."provider" = ${q.provider}`);
+    if (q.scopeKey)
+        parts.push(Prisma.sql `w."scopeKey" = ${q.scopeKey}`);
+    if (q.parentKey)
+        parts.push(Prisma.sql `a."parentKeyAtRun" = ${q.parentKey}`);
+    if (q.issueKey)
+        parts.push(Prisma.sql `w."key" = ${q.issueKey}`);
+    return Prisma.join(parts, " AND ");
+}
+/** The group key for each groupBy, over Run r / RunAttribution a / WorkItem w (and RunModelUsage u for "model"). */
+const GROUP_KEY = {
+    issue: Prisma.sql `w."key"`,
+    parent: Prisma.sql `COALESCE(a."parentKeyAtRun", '(no parent)')`,
+    scope: Prisma.sql `w."scopeKey"`,
+    agent: Prisma.sql `r."agentId"`,
+    model: Prisma.sql `u."model"`,
+    run: Prisma.sql `r."id"`,
+};
+const ATTRIBUTED = Prisma.sql `"Run" r JOIN "RunAttribution" a ON a."runId" = r."id" JOIN "WorkItem" w ON w."id" = a."workItemId"`;
+const USAGE_ATTRIBUTED = Prisma.sql `"RunModelUsage" u JOIN ${ATTRIBUTED} ON r."id" = u."runId"`;
+/**
+ * How long one report may take. Prisma's interactive-transaction default (5 s)
+ * is too short for a wide window over a large Run table; the same limit is set
+ * as the transaction's statement_timeout so Postgres stops the work too, not
+ * only the client.
+ */
+export const COST_REPORT_TIMEOUT_MS = 30_000;
+/**
+ * Every query runs in one read-only REPEATABLE READ transaction, so the rows,
+ * the totals and the unattributed figure all come from the same snapshot even
+ * while runs are finishing.
+ */
+export async function costReport(db, q, visibility) {
+    return db.$transaction(async (tx) => {
+        await tx.$executeRaw `SET TRANSACTION READ ONLY`;
+        // SET takes no bind parameters; the value is a constant.
+        await tx.$executeRawUnsafe(`SET LOCAL statement_timeout = '${COST_REPORT_TIMEOUT_MS}ms'`);
+        return reportIn(tx, q, visibility);
+    }, { isolationLevel: "RepeatableRead", timeout: COST_REPORT_TIMEOUT_MS });
+}
+async function reportIn(db, q, visibility) {
+    const where = Prisma.sql `${runFilter(q, visibility)} AND ${attributionFilter(q)}`;
+    const key = GROUP_KEY[q.groupBy];
+    // "model" groups usage rows, so its money comes from RunModelUsage; every other grouping sums Run.costUsd once per run.
+    const byModel = q.groupBy === "model";
+    const money = byModel ? Prisma.sql `u."costUsd"` : Prisma.sql `r."costUsd"`;
+    const source = byModel ? USAGE_ATTRIBUTED : ATTRIBUTED;
+    const groups = await db.$queryRaw `
+    SELECT ${key} AS key,
+           MIN(w."provider") AS provider,
+           MIN(w."parentKind") AS parent_kind,
+           COUNT(DISTINCT r."id") AS runs,
+           COUNT(DISTINCT r."id") FILTER (WHERE r."status" IN ('pending', 'running')) AS in_progress,
+           SUM(${money})::text AS usd,
+           SUM(${money}) FILTER (WHERE a."source" = 'issue_event')::text AS src_issue_event,
+           SUM(${money}) FILTER (WHERE a."source" = 'linked_pr')::text AS src_linked_pr,
+           SUM(${money}) FILTER (WHERE a."source" = 'explicit')::text AS src_explicit,
+           SUM(${money}) FILTER (WHERE a."source" = 'inherited')::text AS src_inherited,
+           MIN(r."startedAt") AS first_at,
+           MAX(r."startedAt") AS last_at
+    FROM ${source}
+    WHERE ${where}
+    GROUP BY ${key}
+    ORDER BY SUM(${money}) DESC NULLS LAST, ${key}
+    LIMIT ${q.limit + 1}`;
+    const truncated = groups.length > q.limit;
+    const page = groups.slice(0, q.limit);
+    // Per-group, per-model tokens and money for just this page's groups.
+    const usage = page.length
+        ? await db.$queryRaw `
+        SELECT ${key} AS key, u."model" AS model, SUM(u."costUsd")::text AS usd,
+               SUM(u."freshInputTokens") AS fresh, SUM(u."cachedInputTokens") AS cached,
+               SUM(u."cacheWriteTokens") AS write, SUM(u."outputTokens") AS out
+        FROM ${USAGE_ATTRIBUTED}
+        WHERE ${where} AND ${key} IN (${Prisma.join(page.map((g) => g.key))})
+        GROUP BY ${key}, u."model"
+        ORDER BY SUM(u."costUsd") DESC, u."model"`
+        : [];
+    const titles = await groupTitles(db, q.groupBy, page);
+    const rows = page.map((g) => {
+        const models = usage
+            .filter((u) => u.key === g.key)
+            .map((m) => ({ model: m.model, costUsd: usd(m.usd), tokens: kinds(m) }));
+        const tokens = models.reduce((t, m) => ({
+            freshInput: t.freshInput + m.tokens.freshInput,
+            cachedInput: t.cachedInput + m.tokens.cachedInput,
+            cacheWrite: t.cacheWrite + m.tokens.cacheWrite,
+            output: t.output + m.tokens.output,
+        }), { freshInput: 0, cachedInput: 0, cacheWrite: 0, output: 0 });
+        return {
+            key: g.key,
+            ...titles(g),
+            provider: g.provider,
+            runs: Number(g.runs),
+            inProgressRuns: Number(g.in_progress),
+            costUsd: usd(g.usd),
+            tokens,
+            byModel: models,
+            bySource: {
+                issue_event: usd(g.src_issue_event),
+                linked_pr: usd(g.src_linked_pr),
+                explicit: usd(g.src_explicit),
+                inherited: usd(g.src_inherited),
+            },
+            firstRunAt: g.first_at.toISOString(),
+            lastRunAt: g.last_at.toISOString(),
+        };
+    });
+    const [totals] = await db.$queryRaw `
+    SELECT COUNT(*) AS runs, SUM(r."costUsd")::text AS usd FROM ${ATTRIBUTED} WHERE ${where}`;
+    const [totalTokens] = await db.$queryRaw `
+    SELECT SUM(u."freshInputTokens") AS fresh, SUM(u."cachedInputTokens") AS cached,
+           SUM(u."cacheWriteTokens") AS write, SUM(u."outputTokens") AS out
+    FROM ${USAGE_ATTRIBUTED} WHERE ${where}`;
+    const [unattributed] = await db.$queryRaw `
+    SELECT COUNT(*) AS runs, SUM(r."costUsd")::text AS usd
+    FROM "Run" r
+    WHERE ${runFilter(q, visibility)}
+      AND NOT EXISTS (SELECT 1 FROM "RunAttribution" ra WHERE ra."runId" = r."id")`;
+    return {
+        currency: "USD",
+        groupBy: q.groupBy,
+        from: q.from.toISOString(),
+        to: q.to.toISOString(),
+        rows,
+        truncated,
+        totals: { runs: Number(totals?.runs ?? 0), costUsd: usd(totals?.usd), tokens: kinds(totalTokens) },
+        unattributed: { runs: Number(unattributed?.runs ?? 0), costUsd: usd(unattributed?.usd) },
+    };
+}
+/** Titles and kinds per group: current WorkItem names for issue/parent, agent names for agent; none otherwise. */
+async function groupTitles(db, groupBy, page) {
+    const none = () => ({ title: null, kind: null });
+    if (page.length === 0)
+        return none;
+    if (groupBy === "issue" || groupBy === "parent") {
+        const keys = page.map((g) => g.key).filter((k) => k !== NO_PARENT);
+        if (keys.length === 0)
+            return none;
+        const items = await db.$queryRaw `
+      SELECT "provider", "key", "title", "type" FROM "WorkItem" WHERE "key" IN (${Prisma.join(keys)})`;
+        const byKey = new Map(items.map((i) => [`${i.provider}\u0000${i.key}`, i]));
+        return (g) => {
+            if (groupBy === "parent" && g.key === NO_PARENT)
+                return { title: null, kind: null };
+            const i = byKey.get(`${g.provider}\u0000${g.key}`);
+            // A parent's kind lives on its children (WorkItem.parentKind), selected in the group query.
+            return { title: i?.title ?? null, kind: groupBy === "parent" ? g.parent_kind : (i?.type ?? null) };
+        };
+    }
+    if (groupBy === "agent") {
+        const agents = await db.$queryRaw `
+      SELECT "id", "name" FROM "Agent" WHERE "id" IN (${Prisma.join(page.map((g) => g.key))})`;
+        const byId = new Map(agents.map((a) => [a.id, a.name]));
+        return (g) => ({ title: byId.get(g.key) ?? null, kind: "agent" });
+    }
+    return none;
+}

package/dist/core/dispatch.d.ts

@@ -1,8 +1,10 @@
 import type { Prisma, PrismaClient, Run, RunTrigger, Task } from "#prisma";
 import type { Executor } from "../providers/executor/types.js";
+import { type AttributionIntent } from "./attribution.js";
 import { type BudgetConstraint } from "./budget-groups.js";
+import { type SelfDefectSink } from "./self-defects.js";
 export type DispatchDb = Pick<PrismaClient, "agent" | "run" | "runHostCheck" | "codingRun" | "task" | "webhook" | "budgetGroup" | "$transaction" | "$queryRaw">;
-export type DispatchTx = Pick<Prisma.TransactionClient, "agent" | "run" | "runHostCheck" | "runHostStatus" | "codingRun" | "codingService" | "task" | "webhook" | "budgetGroup" | "resourceGrant" | "$queryRaw" | "$executeRawUnsafe">;
+export type DispatchTx = Pick<Prisma.TransactionClient, "agent" | "run" | "runHostCheck" | "runHostStatus" | "runIssueStatus" | "codingRun" | "codingService" | "task" | "webhook" | "budgetGroup" | "resourceGrant" | "workItem" | "runAttribution" | "$queryRaw" | "$executeRawUnsafe">;
 type DispatchAgent = Prisma.AgentGetPayload<{
     include: {
         codingProfile: true;
@@ -39,6 +41,8 @@ export interface DispatchRunOptions {
      * can observe them (e.g. RunHostCheck, see core/host-events.ts).
      */
     afterPersist?: (tx: DispatchTx, run: Run) => Promise<void>;
+    /** Files a self-defect when the executor fails to start the run and this marks it failed. Optional. */
+    selfDefects?: SelfDefectSink;
     /**
      * Who the run is visible to besides the agent owner (Run.triggeredById,
      * resource-sharing grants spec §3.5): the trigger_agent caller, a
@@ -48,6 +52,13 @@ export interface DispatchRunOptions {
     triggeredById?: string | null;
     /** Sub-agent dispatch (see AgentSubAgent): links this run into a run tree. */
     parentRunId?: string;
+    /**
+     * Cost attribution for a run that starts a new attribution (issue event,
+     * linked PR, explicit key), resolved before the call (attribution.ts
+     * resolveWorkItem). Ignored when the parent run or the continued coding run
+     * is attributed: inheritance wins.
+     */
+    attribution?: AttributionIntent;
     grantedParentMemoryKeys?: string[];
     /**
      * Per-run task text for a NATIVE agent (appended to its systemPrompt at
@@ -88,6 +99,10 @@ export interface DispatchRunResult {
  *   (Prisma 7) -- Prisma 6's engine put 40001 at meta.code, still accepted;
  * - at COMMIT (e.g. SSI write skew): an unwrapped DriverAdapterError, no
  *   code or meta, with the SQLSTATE at cause.originalCode.
+ * Also a unique violation (P2002) on WorkItem: concurrent first dispatches
+ * attributed to one new issue each insert its WorkItem, and Postgres reports
+ * the loser as 23505 rather than 40001. The retry finds the committed row.
+ * Unique violations on other models are real errors and are not retried.
  *
  * @internal Exported only for the real-PostgreSQL tests.
  */
@@ -100,7 +115,7 @@ export declare function isSerializationConflict(err: unknown): boolean;
  * the conditional `updateMany` makes the second call match zero rows rather
  * than overwrite whatever landed in between.
  */
-export declare function markRunFailedFromExecutorError(db: Pick<DispatchDb, "run">, runId: string, err: unknown): Promise<void>;
+export declare function markRunFailedFromExecutorError(db: Pick<DispatchDb, "run">, runId: string, err: unknown, selfDefects?: SelfDefectSink): Promise<void>;
 /**
  * The `Run.error` of a coding run refused at dispatch because a budget
  * constraint has nothing left: `budget_group_exhausted:<period>` or
@@ -114,6 +129,31 @@ export declare function budgetExhaustedError(constraint: BudgetConstraint): stri
  * @internal Exported only for the real-PostgreSQL tests.
  */
 export declare const PERSIST_ATTEMPTS = 8;
+export type ContinuationRefusal = "unknown_run" | "other_repository" | "no_pull_request";
+/** A continuation refused because of the run it names. Its message is fixed text, safe to show the model. */
+export declare class ContinuationRefusedError extends Error {
+    readonly reason: ContinuationRefusal;
+    constructor(reason: ContinuationRefusal);
+}
+export type ContinuationCheck = {
+    ok: true;
+    root: {
+        runId: string;
+        baseRef: string;
+        headRef: string;
+        pullRequestNumber: number;
+    };
+} | {
+    ok: false;
+    reason: ContinuationRefusal;
+};
+/**
+ * Whether this deployment can continue coding run `runId` in `repository`: the
+ * run (or its root) is in this database, in that repository, and opened a pull
+ * request. A run id read from a pull request can name a run that another
+ * deployment sharing the same App made, so check before relying on one.
+ */
+export declare function checkContinuation(reader: Pick<DispatchTx, "codingRun">, runId: string, repository: string): Promise<ContinuationCheck>;
 /**
  * Persists every detached run input in one transaction, then invokes the
  * executor only after commit. A null result means the caller's transactional

package/dist/core/dispatch.js

@@ -1,12 +1,18 @@
 import { CODING_PROTOCOL_VERSION, CodingTaskInputSchema, normalizeGitHubRepository, normalizeGitRef, publicCodingRunResult, composeCodingTask, } from "../coding/protocol.js";
-import { assertCodingProviderModel } from "../coding/provider.js";
+import { assertCodingProvider, assertCodingProviderModel } from "../coding/provider.js";
+import { ModelUnavailableError, entryOf } from "../providers/llm/catalog-types.js";
 import { parseAllowedServiceNames, workerServices } from "../coding/services/catalog.js";
 import { MAX_SERVICE_DECLARATION_BYTES, ServiceDeclarationError, parseServiceDeclaration, } from "../coding/services/declaration.js";
 import { servicesInstructionNote } from "../coding/services/note.js";
 import { resolveRunServices } from "../coding/services/resolve.js";
 import { DECLARATION_UNAVAILABLE_SENTENCE, LAUNCHER_UNSUPPORTED_SENTENCE, invalidDeclarationSentence, serviceRefusal, } from "../coding/services/wording.js";
+import { attributeRun } from "./attribution.js";
 import { effectiveBudgetForRun, MIN_RESERVATION_USD } from "./budget-groups.js";
+import { DEFAULT_KNOWLEDGE_BUNDLE_PATH } from "../knowledge/concept.js";
+import { KNOWLEDGE_INDEX_READ_MAX_BYTES, knowledgeSection } from "../knowledge/note.js";
 import { logger } from "./logger.js";
+import { CodingModelProviderMismatchError, resolveCodingEntry } from "./run-pricing.js";
+import { fileSelfDefectForRun } from "./self-defects.js";
 const dispatchLog = logger.child({ module: "dispatch" });
 /** SQLSTATEs worth retrying the persist transaction for: serialization failure, deadlock. */
 const RETRYABLE_SQLSTATES = new Set(["40001", "40P01"]);
@@ -21,6 +27,10 @@ const RETRYABLE_SQLSTATES = new Set(["40001", "40P01"]);
  *   (Prisma 7) -- Prisma 6's engine put 40001 at meta.code, still accepted;
  * - at COMMIT (e.g. SSI write skew): an unwrapped DriverAdapterError, no
  *   code or meta, with the SQLSTATE at cause.originalCode.
+ * Also a unique violation (P2002) on WorkItem: concurrent first dispatches
+ * attributed to one new issue each insert its WorkItem, and Postgres reports
+ * the loser as 23505 rather than 40001. The retry finds the committed row.
+ * Unique violations on other models are real errors and are not retried.
  *
  * @internal Exported only for the real-PostgreSQL tests.
  */
@@ -30,6 +40,8 @@ export function isSerializationConflict(err) {
     const candidate = err;
     if (candidate.code === "P2034")
         return true;
+    if (candidate.code === "P2002")
+        return candidate.meta?.modelName === "WorkItem";
     if (candidate.code === "P2010") {
         const sqlState = candidate.meta?.driverAdapterError?.cause?.originalCode;
         return (typeof sqlState === "string" && RETRYABLE_SQLSTATES.has(sqlState)) || candidate.meta?.code === "40001";
@@ -48,8 +60,8 @@ export function isSerializationConflict(err) {
  * the conditional `updateMany` makes the second call match zero rows rather
  * than overwrite whatever landed in between.
  */
-export async function markRunFailedFromExecutorError(db, runId, err) {
-    await db.run.updateMany({
+export async function markRunFailedFromExecutorError(db, runId, err, selfDefects) {
+    const updated = await db.run.updateMany({
         where: { id: runId, status: { in: ["pending", "running"] } },
         data: {
             status: "failed",
@@ -57,6 +69,9 @@ export async function markRunFailedFromExecutorError(db, runId, err) {
             finishedAt: new Date(),
         },
     });
+    // Only the call that made the row failed files (the duplicate call matches zero rows); bounded, never throws.
+    if (updated.count > 0)
+        await fileSelfDefectForRun(selfDefects, runId);
 }
 /**
  * The `Run.error` of a coding run refused at dispatch because a budget
@@ -111,32 +126,67 @@ function retryDelayMs(attempt) {
     const ceiling = Math.min(RETRY_MAX_MS, RETRY_BASE_MS * 2 ** attempt);
     return Math.floor(ceiling / 2 + Math.random() * (ceiling / 2));
 }
+const CONTINUATION_REFUSALS = {
+    unknown_run: "Cannot continue an unknown coding run.",
+    other_repository: "Cannot continue a coding run from a different repository.",
+    no_pull_request: "Cannot continue a coding run that never opened a pull request.",
+};
+/** A continuation refused because of the run it names. Its message is fixed text, safe to show the model. */
+export class ContinuationRefusedError extends Error {
+    reason;
+    constructor(reason) {
+        super(CONTINUATION_REFUSALS[reason]);
+        this.reason = reason;
+        this.name = "ContinuationRefusedError";
+    }
+}
 /**
- * Resolves a coding run's branch: an override, else a continuation root's
- * (verified to be in the same repository and to have opened a pull request),
- * else the profile's base.
+ * Whether this deployment can continue coding run `runId` in `repository`: the
+ * run (or its root) is in this database, in that repository, and opened a pull
+ * request. A run id read from a pull request can name a run that another
+ * deployment sharing the same App made, so check before relying on one.
  */
-async function resolveCodingBranch(reader, options, profile) {
-    if (options.continuesCodingRunId === undefined)
-        return { baseRef: options.codingBaseRef ?? profile.baseRef };
-    if (options.codingBaseRef !== undefined) {
-        throw new Error("continuesCodingRunId cannot be combined with codingBaseRef.");
-    }
-    const candidate = await reader.codingRun.findUnique({ where: { runId: options.continuesCodingRunId } });
+export async function checkContinuation(reader, runId, repository) {
+    const candidate = await reader.codingRun.findUnique({ where: { runId } });
     if (!candidate)
-        throw new Error("Cannot continue an unknown coding run.");
+        return { ok: false, reason: "unknown_run" };
     const root = candidate.rootCodingRunId
         ? await reader.codingRun.findUnique({ where: { runId: candidate.rootCodingRunId } })
         : candidate;
     if (!root)
-        throw new Error("Cannot continue an unknown coding run.");
-    if (normalizeGitHubRepository(root.repository) !== normalizeGitHubRepository(profile.repository)) {
-        throw new Error("Cannot continue a coding run from a different repository.");
+        return { ok: false, reason: "unknown_run" };
+    if (normalizeGitHubRepository(root.repository) !== normalizeGitHubRepository(repository)) {
+        return { ok: false, reason: "other_repository" };
     }
     const rootResult = publicCodingRunResult(root.result);
-    if (rootResult?.outcome !== "pull_request_opened" && rootResult?.outcome !== "pull_request_updated") {
-        throw new Error("Cannot continue a coding run that never opened a pull request.");
+    if ((rootResult?.outcome !== "pull_request_opened" && rootResult?.outcome !== "pull_request_updated") ||
+        rootResult.pullRequestNumber === undefined) {
+        return { ok: false, reason: "no_pull_request" };
     }
+    return {
+        ok: true,
+        root: {
+            runId: root.runId,
+            baseRef: root.baseRef,
+            headRef: root.headRef,
+            pullRequestNumber: rootResult.pullRequestNumber,
+        },
+    };
+}
+/**
+ * Resolves a coding run's branch: an override, else a continuation root's
+ * (see checkContinuation), else the profile's base.
+ */
+async function resolveCodingBranch(reader, options, profile) {
+    if (options.continuesCodingRunId === undefined)
+        return { baseRef: options.codingBaseRef ?? profile.baseRef };
+    if (options.codingBaseRef !== undefined) {
+        throw new Error("continuesCodingRunId cannot be combined with codingBaseRef.");
+    }
+    const check = await checkContinuation(reader, options.continuesCodingRunId, profile.repository);
+    if (!check.ok)
+        throw new ContinuationRefusedError(check.reason);
+    const { root } = check;
     return {
         baseRef: root.baseRef,
         headRef: root.headRef,
@@ -150,6 +200,35 @@ const UNREADABLE_DECLARATION = {
     github_file_not_a_file: "it is not a file",
     github_file_not_utf8: "it is not UTF-8 text",
 };
+/**
+ * The knowledge note's input (docs/knowledge.md): the repository's bundle
+ * index at the run's base, read before the transaction like the services
+ * declaration. Any failure means no note, never a failed dispatch.
+ */
+async function readKnowledgeIndex(options, profile, resolvedBranch) {
+    const executor = options.executor;
+    if (!executor.readCodingRepositoryFile)
+        return undefined;
+    try {
+        // Resolved here, inside the try: a branch problem is the transaction's to report, not the note's.
+        const branch = resolvedBranch ?? (await resolveCodingBranch(options.db, options, profile));
+        const indexText = await executor.readCodingRepositoryFile({
+            repository: profile.repository,
+            baseRef: normalizeGitRef(branch.baseRef),
+            path: `${DEFAULT_KNOWLEDGE_BUNDLE_PATH}/index.md`,
+            maxBytes: KNOWLEDGE_INDEX_READ_MAX_BYTES,
+        });
+        return indexText ? { bundlePath: DEFAULT_KNOWLEDGE_BUNDLE_PATH, indexText } : undefined;
+    }
+    catch (err) {
+        if (err instanceof Error && err.message in UNREADABLE_DECLARATION) {
+            dispatchLog.info({ repository: profile.repository, reason: err.message }, "knowledge index unreadable; dispatching without it");
+            return undefined;
+        }
+        dispatchLog.warn({ err, repository: profile.repository }, "knowledge index read failed; dispatching without it");
+        return undefined;
+    }
+}
 /**
  * Coding-run services (docs/coding-services.md): resolves the run's branch and
  * reads the repository's declaration from its base, then parses it. A network
@@ -245,6 +324,10 @@ export async function dispatchRun(options) {
         parseAllowedServiceNames(preview.codingProfile.services).length > 0
         ? await readServiceDeclaration(options, preview.codingProfile)
         : undefined;
+    // The knowledge note's input: the repository's bundle index at the run's base (a network call).
+    const knowledgeIndex = preview?.kind === "coding" && preview.codingProfile && options.executor.readCodingRepositoryFile
+        ? await readKnowledgeIndex(options, preview.codingProfile, declarationRead?.branch)
+        : undefined;
     const persistOnce = () => options.db.$transaction(async (tx) => {
         if (lockGroups)
             await tx.$executeRawUnsafe(GROUP_DISPATCH_LOCK_SQL);
@@ -271,13 +354,30 @@ export async function dispatchRun(options) {
         // reservation. A native run computes its effective budget in
         // executeRun's load step instead.
         let codingBudget;
+        let codingEntry;
+        let modelFailure;
         let services = [];
         let servicesRefusal;
         if (agent.kind === "coding") {
             if (!agent.codingProfile)
                 throw new Error(`Coding agent "${agent.id}" has no coding profile.`);
-            assertCodingProviderModel(agent.codingProfile.provider, agent.model);
-            if (declarationRead) {
+            // An unknown coding provider is a broken profile, not a catalog state: still thrown.
+            assertCodingProvider(agent.codingProfile.provider);
+            // Recorded on the run row below: the run is billed at this entry for its whole life.
+            // A model the catalog cannot run (missing, disabled, or another provider's) fails
+            // the run here instead of throwing: the run row commits with the reason, so the
+            // caller's own writes stand (a scheduler's lastScheduledAt, a mention's status
+            // row) and the owner sees why in list_runs, rather than a rolled-back
+            // transaction that a scheduler would retry on every tick.
+            try {
+                codingEntry = resolveCodingEntry(agent.codingProfile.provider, agent.model);
+            }
+            catch (err) {
+                if (!(err instanceof ModelUnavailableError || err instanceof CodingModelProviderMismatchError))
+                    throw err;
+                modelFailure = err.message;
+            }
+            if (!modelFailure && declarationRead) {
                 if (declarationRead.repository !== agent.codingProfile.repository ||
                     declarationRead.profileBaseRef !== agent.codingProfile.baseRef) {
                     // The declaration was read for a profile that changed before this transaction.
@@ -291,7 +391,7 @@ export async function dispatchRun(options) {
                 else
                     services = resolved.services;
             }
-            if (!servicesRefusal)
+            if (!modelFailure && !servicesRefusal)
                 codingBudget = await reserveCodingBudget(tx, agent, now, options);
         }
         const refusal = servicesRefusal ?? codingBudget?.refusal;
@@ -304,13 +404,29 @@ export async function dispatchRun(options) {
                 grantedParentMemoryKeys: options.grantedParentMemoryKeys ?? [],
                 taskOverride: options.taskOverride,
                 triggeredById: options.triggeredById ?? null,
+                // Failed before it starts, like a native run whose model the
+                // runner's load step finds unavailable: zero spend, never started.
+                ...(modelFailure ? { status: "failed", error: modelFailure, finishedAt: now } : {}),
                 // Refused before it starts, the same terminal status (and zero
                 // spend) as a native run whose budget is gone at turn 1.
                 ...(refusal ? { status: "refused", error: refusal, finishedAt: now } : {}),
+                ...(codingEntry
+                    ? {
+                        pricingVersion: codingEntry.priceVersion,
+                        // entryOf returns plain JSON data (fresh array, no Dates); the interface's readonly
+                        // efforts array is all that keeps it from matching Prisma's Json input type.
+                        pricingSnapshot: entryOf(codingEntry),
+                    }
+                    : {}),
             },
         });
         if (options.afterPersist)
             await options.afterPersist(tx, run);
+        const attributed = await attributeRun(tx, run.id, {
+            parentRunId: options.parentRunId,
+            continuesCodingRunId: options.continuesCodingRunId,
+            intent: options.attribution,
+        }, now);
         if (agent.kind === "coding" && agent.codingProfile && codingBudget && !refusal) {
             // Checked above too; repeated so the provider type narrows here.
             assertCodingProviderModel(agent.codingProfile.provider, agent.model);
@@ -319,7 +435,7 @@ export async function dispatchRun(options) {
                 throw new Error(`Coding agent "${agent.id}" requires a task.`);
             // The worker sees only the task text, so the agent's own instructions, and the
             // services note, ride in it.
-            const task = composeCodingTask(agent.systemPrompt, request, servicesInstructionNote(services));
+            const task = composeCodingTask(agent.systemPrompt, request, servicesInstructionNote(services), knowledgeIndex ? knowledgeSection(knowledgeIndex) : undefined);
             const budgetUsd = codingBudget.budgetUsd;
             // Resolved once: before the transaction when the declaration was read from it.
             const branch = declarationRead?.branch ?? (await resolveCodingBranch(tx, options, agent.codingProfile));
@@ -351,6 +467,8 @@ export async function dispatchRun(options) {
             await tx.codingRun.create({
                 data: {
                     runId: run.id,
+                    issueProvider: attributed?.provider ?? null,
+                    issueKey: attributed?.key ?? null,
                     task: input.task,
                     repository: input.repository,
                     baseRef: input.baseRef,
@@ -407,8 +525,8 @@ export async function dispatchRun(options) {
     }
     if (!persisted)
         return null;
-    if (persisted.run.status === "refused") {
-        dispatchLog.warn({ runId: persisted.run.id, agentId: options.agentId, reason: persisted.run.error }, "coding run refused at dispatch");
+    if (persisted.run.status === "refused" || persisted.run.status === "failed") {
+        dispatchLog.warn({ runId: persisted.run.id, agentId: options.agentId, reason: persisted.run.error }, `coding run ${persisted.run.status} at dispatch`);
         return persisted;
     }
     const runStart = async () => {
@@ -416,7 +534,7 @@ export async function dispatchRun(options) {
             await options.executor.start(persisted.run.id);
         }
         catch (err) {
-            await markRunFailedFromExecutorError(options.db, persisted.run.id, err).catch((err2) => dispatchLog.error({ err: err2, runId: persisted.run.id }, "failed to persist executor start failure"));
+            await markRunFailedFromExecutorError(options.db, persisted.run.id, err, options.selfDefects).catch((err2) => dispatchLog.error({ err: err2, runId: persisted.run.id }, "failed to persist executor start failure"));
         }
     };
     if (options.awaitExecution) {