@wardby/cli 0.2.1 → 0.4.0

package/dist/core/budget-wording.js

@@ -0,0 +1,55 @@
+const MAX_GROUP_NAME_CHARS = 64;
+const usd = (amount) => `$${amount.toFixed(2)}`;
+/** A group name is operator-chosen text; keep it to one short, quote-free line. */
+function groupName(name) {
+    const cleaned = (name ?? "").replace(/["`]/g, "").replace(/\s+/g, " ").trim().slice(0, MAX_GROUP_NAME_CHARS);
+    return cleaned || null;
+}
+export function budgetSentence(facts) {
+    const group = groupName(facts.budgetGroupName);
+    if (facts.refused) {
+        const within = `this run could not start within its ${usd(facts.runBudgetUsd ?? facts.agentBudgetUsd)} budget`;
+        return group
+            ? `Out of budget: ${within} or what the "${group}" budget group had left of its limit.`
+            : `Out of budget: ${within}.`;
+    }
+    const runBudget = facts.runBudgetUsd ?? facts.agentBudgetUsd;
+    const used = `Out of budget: this run's ${usd(runBudget)} budget was used up`;
+    // A run reserved less than the agent's own budget: its group had only that much left.
+    if (group && runBudget < facts.agentBudgetUsd) {
+        return `${used} (the "${group}" budget group had only that much left of its limit).`;
+    }
+    return `${used}.`;
+}
+/**
+ * The sentence for a finished run, read from the database: a coding run's
+ * reserved budget, otherwise the agent's. Falls back to a sentence without
+ * amounts when they cannot be read. Never throws.
+ */
+export async function loadBudgetSentence(db, runId, status) {
+    const refused = status === "refused";
+    try {
+        const row = await db.run.findUnique({
+            where: { id: runId },
+            select: {
+                agent: { select: { budgetUsd: true, budgetGroup: { select: { name: true } } } },
+                codingRun: { select: { budgetReservedUsd: true } },
+            },
+        });
+        const agentBudgetUsd = Number(row?.agent?.budgetUsd);
+        if (!row?.agent || !Number.isFinite(agentBudgetUsd))
+            throw new Error("budget_facts_unavailable");
+        const reserved = row.codingRun ? Number(row.codingRun.budgetReservedUsd) : NaN;
+        return budgetSentence({
+            runBudgetUsd: Number.isFinite(reserved) ? reserved : null,
+            agentBudgetUsd,
+            budgetGroupName: row.agent.budgetGroup?.name ?? null,
+            refused,
+        });
+    }
+    catch {
+        return refused
+            ? "Out of budget: this run could not start within its budget."
+            : "Out of budget: this run's budget was used up.";
+    }
+}

package/dist/core/coding-queue.d.ts

@@ -16,6 +16,7 @@
  */
 import type { PrismaClient } from "#prisma";
 import type { Executor } from "../providers/executor/types.js";
+import { type SelfDefectSink } from "./self-defects.js";
 export declare const CODING_QUEUE_TIMEOUT_ERROR = "coding_queue_timeout";
 export type CodingQueueDb = Pick<PrismaClient, "run" | "codingRun" | "$transaction">;
 export interface DrainCodingQueueOptions {
@@ -24,6 +25,8 @@ export interface DrainCodingQueueOptions {
     maxConcurrent: number;
     queueTimeoutSec: number;
     now?: () => Date;
+    /** Files a self-defect for each run this drain fails (queue timeout or start failure). Optional. */
+    selfDefects?: SelfDefectSink;
 }
 export interface DrainCodingQueueResult {
     timedOut: number;

package/dist/core/coding-queue.js

@@ -1,5 +1,6 @@
 import { markRunFailedFromExecutorError } from "./dispatch.js";
 import { logger } from "./logger.js";
+import { fileSelfDefectForRun } from "./self-defects.js";
 const queueLog = logger.child({ module: "coding-queue" });
 export const CODING_QUEUE_TIMEOUT_ERROR = "coding_queue_timeout";
 export async function drainCodingQueue(options) {
@@ -25,8 +26,11 @@ export async function drainCodingQueue(options) {
             await tx.codingRun.update({ where: { runId }, data: { failureCategory: CODING_QUEUE_TIMEOUT_ERROR } });
             return true;
         });
-        if (didTimeOut)
+        if (didTimeOut) {
             timedOut += 1;
+            // Only this drain made the row failed (a concurrent drain matched zero rows); bounded, never throws.
+            await fileSelfDefectForRun(options.selfDefects, runId);
+        }
     }
     const active = await db.codingRun.count({
         where: { jobBackend: { not: null }, run: { status: { in: ["pending", "running"] } } },
@@ -48,7 +52,7 @@ export async function drainCodingQueue(options) {
         // drainCodingQueue's own call stack.
         void Promise.resolve()
             .then(() => executor.start(runId))
-            .catch((err) => markRunFailedFromExecutorError(db, runId, err).catch((err2) => queueLog.error({ err: err2, runId }, "failed to persist queued-run start failure")));
+            .catch((err) => markRunFailedFromExecutorError(db, runId, err, options.selfDefects).catch((err2) => queueLog.error({ err: err2, runId }, "failed to persist queued-run start failure")));
     }
     return { timedOut, started: next.map((row) => row.runId) };
 }

package/dist/core/coding-service-status.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Persists launcher-observed coding-run service states (CodingRunServiceStatus, one row per
+ * run x service) for the viewer. Composed into the job launchers by
+ * providers/executor/composition.ts; launchers call it through reportServiceState, which drops
+ * its errors.
+ */
+import type { PrismaClient } from "#prisma";
+import type { ServiceStateReporter } from "../providers/jobs/service-state.js";
+type ServiceStatusDb = Pick<PrismaClient, "codingRunServiceStatus">;
+export declare function prismaServiceStateReporter(db: ServiceStatusDb, now?: () => Date): ServiceStateReporter;
+export {};

package/dist/core/coding-service-status.js

@@ -0,0 +1,17 @@
+export function prismaServiceStateReporter(db, now = () => new Date()) {
+    return async ({ runId, name, state, attempts, reason }) => {
+        const at = now();
+        const data = {
+            state,
+            attempts: attempts ?? null,
+            reason: reason ?? null,
+            readyAt: state === "ready" ? at : null,
+            failedAt: state === "failed" ? at : null,
+        };
+        await db.codingRunServiceStatus.upsert({
+            where: { runId_name: { runId, name } },
+            create: { runId, name, ...data },
+            update: data,
+        });
+    };
+}

package/dist/core/cost-report.d.ts

@@ -0,0 +1,88 @@
+/**
+ * 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 { type PrismaClient } from "#prisma";
+export type CostGroupBy = "issue" | "parent" | "scope" | "agent" | "model" | "run";
+export declare class CostReportInputError extends Error {
+    constructor(message: string);
+}
+export interface CostReportQuery {
+    groupBy: CostGroupBy;
+    from: Date;
+    to: Date;
+    provider?: string;
+    scopeKey?: string;
+    parentKey?: string;
+    issueKey?: string;
+    agentId?: string;
+    limit: number;
+}
+export declare function parseCostReportQuery(raw: unknown, now?: Date): CostReportQuery;
+/** Which runs the caller may count: null = all (stdio operator). */
+export interface CostVisibility {
+    ownedAgentIds: string[];
+    principalId: string;
+}
+export interface TokenKinds {
+    freshInput: number;
+    cachedInput: number;
+    cacheWrite: number;
+    output: number;
+}
+export interface CostRow {
+    key: string;
+    title: string | null;
+    kind: string | null;
+    provider: string | null;
+    runs: number;
+    inProgressRuns: number;
+    costUsd: string;
+    tokens: TokenKinds;
+    byModel: Array<{
+        model: string;
+        costUsd: string;
+        tokens: TokenKinds;
+    }>;
+    bySource: {
+        issue_event: string;
+        linked_pr: string;
+        explicit: string;
+        inherited: string;
+    };
+    firstRunAt: string;
+    lastRunAt: string;
+}
+export interface CostReport {
+    currency: "USD";
+    groupBy: CostGroupBy;
+    from: string;
+    to: string;
+    rows: CostRow[];
+    truncated: boolean;
+    totals: {
+        runs: number;
+        costUsd: string;
+        tokens: TokenKinds;
+    };
+    unattributed: {
+        runs: number;
+        costUsd: string;
+    };
+}
+/**
+ * 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 declare const COST_REPORT_TIMEOUT_MS = 30000;
+/**
+ * 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 declare function costReport(db: Pick<PrismaClient, "$queryRaw" | "$transaction">, q: CostReportQuery, visibility: CostVisibility | null): Promise<CostReport>;

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/datastores.js

@@ -25,9 +25,25 @@ export async function attachDatastore(agentId, datastoreId, db, boundName) {
 export async function detachDatastore(agentId, boundName, db) {
     await db.agentDatastore.deleteMany({ where: { agentId, boundName } });
 }
+/**
+ * Owner rule (resource-sharing grants spec §3.4.1): a binding resolves only
+ * while the datastore's owner is the agent's CURRENT owner, both non-null.
+ * A cross-owner binding (written before that rule, or left behind by
+ * make_owner) and every binding on an owner-less agent resolve like an
+ * unattached boundName, so one owner's store never reaches another owner's
+ * agent (A2/S2-2, R2-1).
+ */
 async function resolveDatastoreId(agentId, boundName, db) {
-    const attachment = await db.agentDatastore.findFirst({ where: { agentId, boundName } });
-    return attachment?.datastoreId;
+    const attachment = await db.agentDatastore.findFirst({
+        where: { agentId, boundName },
+        include: { datastore: { select: { ownerId: true } }, agent: { select: { ownerId: true } } },
+    });
+    if (!attachment)
+        return undefined;
+    const owner = attachment.agent.ownerId;
+    if (owner === null || attachment.datastore.ownerId !== owner)
+        return undefined;
+    return attachment.datastoreId;
 }
 /**
  * Resolves `boundName` to the Datastore attached to this agent under that

package/dist/core/db.d.ts

@@ -32,5 +32,9 @@ export declare function poolSettings(connectionString: string): PoolSettings;
  * The one way wardby builds a Prisma client. `url` defaults to DATABASE_URL
  * as read at call time.
  */
-export declare function createPrismaClient(url?: string | undefined): PrismaClient;
+/** `poolMax` overrides the pool size for a caller that sizes its own pools
+ *  (the coding proxy keeps its ledger and its package registry apart). */
+export declare function createPrismaClient(url?: string | undefined, options?: {
+    poolMax?: number;
+}): PrismaClient;
 export declare const prisma: PrismaClient;

package/dist/core/db.js

@@ -60,9 +60,15 @@ class MissingUrlAdapter extends PrismaPg {
  * The one way wardby builds a Prisma client. `url` defaults to DATABASE_URL
  * as read at call time.
  */
-export function createPrismaClient(url = process.env.DATABASE_URL) {
+/** `poolMax` overrides the pool size for a caller that sizes its own pools
+ *  (the coding proxy keeps its ledger and its package registry apart). */
+export function createPrismaClient(url = process.env.DATABASE_URL, options = {}) {
     const adapter = url
-        ? new PrismaPg({ connectionString: url, ...poolSettings(url) })
+        ? new PrismaPg({
+            connectionString: url,
+            ...poolSettings(url),
+            ...(options.poolMax !== undefined ? { max: options.poolMax } : {}),
+        })
         : new MissingUrlAdapter({ connectionString: "" });
     return new PrismaClient({ adapter });
 }

package/dist/core/dispatch.d.ts

@@ -1,7 +1,10 @@
 import type { Prisma, PrismaClient, Run, RunTrigger, Task } from "#prisma";
 import type { Executor } from "../providers/executor/types.js";
-export type DispatchDb = Pick<PrismaClient, "agent" | "run" | "codingRun" | "task" | "webhook" | "$transaction" | "$queryRaw">;
-type DispatchTx = Pick<Prisma.TransactionClient, "agent" | "run" | "codingRun" | "task" | "webhook" | "$queryRaw">;
+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" | "runIssueStatus" | "codingRun" | "codingService" | "task" | "webhook" | "budgetGroup" | "resourceGrant" | "workItem" | "runAttribution" | "$queryRaw" | "$executeRawUnsafe">;
 type DispatchAgent = Prisma.AgentGetPayload<{
     include: {
         codingProfile: true;
@@ -32,8 +35,30 @@ export interface DispatchRunOptions {
         ttlMs: number;
     };
     beforePersist?: (tx: DispatchTx, agent: DispatchAgent) => Promise<boolean>;
+    /**
+     * Runs inside the persist transaction right after the run row is created,
+     * before the executor is started — for rows that must exist before the run
+     * 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
+     * webhook's creator, a sub-agent's parent triggerer. Omit/null for
+     * scheduled and host-event runs, which only the owner sees.
+     */
+    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
@@ -42,10 +67,10 @@ export interface DispatchRunOptions {
      */
     taskOverride?: string;
     /**
-     * Overrides `agent.budgetUsd` for this run's coding budget reservation —
-     * used by sub-agent dispatch to apply the run-tree's tightened effective
-     * budget (see src/core/budget-groups.ts) instead of the agent's raw
-     * per-run ceiling, the same composability already applied to native runs.
+     * Replaces `agent.budgetUsd` as the requested ceiling for this run's coding
+     * budget reservation. The reservation is still tightened by the agent's
+     * budget group and, with `parentRunId`, the run tree (see
+     * src/core/budget-groups.ts), computed inside the persist transaction.
      * Ignored for native agents, which compute their own effective budget
      * inside executeRun's load step.
      */
@@ -74,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.
  */
@@ -86,7 +115,45 @@ 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
+ * `run_tree_exhausted`, then a sentence for people.
+ */
+export declare function budgetExhaustedError(constraint: BudgetConstraint): string;
+/**
+ * Attempts for the persist transaction, and the jittered backoff between
+ * them, for serialization failures and deadlocks.
+ *
+ * @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