@wardby/cli 0.6.0 → 0.7.0

package/dist/core/budget-topup.js

@@ -0,0 +1,156 @@
+import { codingTopUpRoom, MIN_RESERVATION_USD } from "./budget-groups.js";
+import { GROUP_DISPATCH_LOCK_SQL, isSerializationConflict, isTransactionUnavailable } from "./dispatch.js";
+import { logger } from "./logger.js";
+const topUpLog = logger.child({ module: "budget-topup" });
+/** Share of the base one step adds, unless one maximum request hold is more. */
+export const TOP_UP_STEP_SHARE = 0.1;
+/** Headroom: the share of the base, or this many of the run's largest request holds if more. */
+export const TOP_UP_HEADROOM_SHARE = 0.2;
+export const TOP_UP_HEADROOM_HOLDS = 2;
+const roundMicro = (usd) => Math.round(usd / MIN_RESERVATION_USD) * MIN_RESERVATION_USD;
+const floorMicro = (usd) => Math.floor(usd / MIN_RESERVATION_USD + 1e-6) * MIN_RESERVATION_USD;
+/** The run's grant, limit and proxy-session totals, or the outcome when there is nothing to ask for. */
+async function readState(db, runId) {
+    const coding = await db.codingRun.findUnique({
+        where: { runId },
+        select: {
+            budgetReservedUsd: true,
+            budgetBaseUsd: true,
+            budgetLimitUsd: true,
+            run: { select: { status: true } },
+            proxySession: { select: { id: true, status: true, budgetExhaustedAt: true } },
+        },
+    });
+    if (!coding || coding.budgetLimitUsd == null)
+        return { outcome: "closed" };
+    const grantedUsd = Number(coding.budgetReservedUsd);
+    const limitUsd = Number(coding.budgetLimitUsd);
+    const result = { outcome: "closed", grantedUsd };
+    if (grantedUsd + MIN_RESERVATION_USD > limitUsd)
+        return result;
+    if (coding.run.status !== "running" && coding.run.status !== "pending")
+        return result;
+    // Already refused by the proxy: the worker is stopping, a grant now would only be held for nothing.
+    const session = coding.proxySession;
+    if (!session || session.status !== "active" || session.budgetExhaustedAt)
+        return result;
+    const refused = await db.runBudgetEvent.findFirst({
+        where: { runId, kind: "overrun_unavailable" },
+        select: { id: true },
+    });
+    if (refused)
+        return result;
+    // Totals as the proxy ledger counts them (prisma-ledger.ts reserve).
+    const totals = await db.$queryRaw `
+    SELECT
+      COALESCE(SUM(CASE
+        WHEN "status" = 'completed' THEN "actualCostUsd"
+        WHEN "status" = 'uncertain' AND "costEstimated" THEN "actualCostUsd"
+        ELSE 0
+      END), 0) AS "spent",
+      COALESCE(SUM(CASE
+        WHEN "status" = 'reserved' THEN "reservationUsd"
+        WHEN "status" = 'uncertain' AND NOT "costEstimated" THEN "reservationUsd"
+        ELSE 0
+      END), 0) AS "held",
+      COALESCE(MAX(COALESCE("ceilingUsd", "reservationUsd")), 0) AS "maxHold"
+    FROM "CodingProxyRequest" WHERE "sessionId" = ${session.id}
+  `;
+    return {
+        baseUsd: coding.budgetBaseUsd == null ? grantedUsd : Number(coding.budgetBaseUsd),
+        grantedUsd,
+        limitUsd,
+        sessionId: session.id,
+        spentUsd: Number(totals[0]?.spent ?? 0),
+        heldUsd: Number(totals[0]?.held ?? 0),
+        maxHoldUsd: Number(totals[0]?.maxHold ?? 0),
+    };
+}
+/**
+ * How far below its grant a run asks for its next step. Agent loops grow their
+ * context, so the next request usually holds more than any before it, and the
+ * top-up has to land before it is sent.
+ */
+function headroomUsd(state) {
+    return Math.max(TOP_UP_HEADROOM_HOLDS * state.maxHoldUsd, TOP_UP_HEADROOM_SHARE * state.baseUsd);
+}
+/** Close to its grant: within its headroom. */
+function isClose(state) {
+    return state.spentUsd + state.heldUsd >= state.grantedUsd - headroomUsd(state);
+}
+/** Near enough to its grant that the next poll should come soon. */
+function isNear(state) {
+    return state.spentUsd + state.heldUsd >= state.grantedUsd - 2 * headroomUsd(state);
+}
+async function grantOnce(tx, runId, now) {
+    // First statement: serializes with dispatch and every other top-up (see GROUP_DISPATCH_LOCK_SQL).
+    await tx.$executeRawUnsafe(GROUP_DISPATCH_LOCK_SQL);
+    const state = await readState(tx, runId);
+    if ("outcome" in state)
+        return state;
+    if (!isClose(state))
+        return { outcome: "not_needed", grantedUsd: state.grantedUsd, near: isNear(state) };
+    const room = await codingTopUpRoom(tx, runId, now);
+    const step = Math.max(TOP_UP_STEP_SHARE * state.baseUsd, state.maxHoldUsd);
+    const grant = floorMicro(Math.min(step, state.limitUsd - state.grantedUsd, room.roomUsd));
+    if (grant < MIN_RESERVATION_USD) {
+        const details = {
+            source: "top-up",
+            capUsd: room.detail?.capUsd ?? 0,
+            spentUsd: room.detail?.spentUsd ?? 0,
+            heldUsd: room.detail?.heldUsd ?? 0,
+            leftUsd: room.roomUsd,
+            baseBudgetUsd: state.baseUsd,
+            grantedUsd: state.grantedUsd,
+            limitUsd: state.limitUsd,
+            ...(room.groupName ? { groupName: room.groupName } : {}),
+        };
+        await tx.runBudgetEvent.create({
+            data: {
+                runId,
+                kind: "overrun_unavailable",
+                limit: room.limitedBy ?? "run",
+                details: details,
+            },
+        });
+        return { outcome: "unavailable", grantedUsd: state.grantedUsd };
+    }
+    const grantedUsd = Math.min(state.limitUsd, roundMicro(state.grantedUsd + grant));
+    await tx.codingRun.update({ where: { runId }, data: { budgetReservedUsd: grantedUsd } });
+    await tx.codingProxySession.updateMany({
+        where: { id: state.sessionId, status: "active" },
+        data: { budgetUsd: grantedUsd },
+    });
+    return { outcome: "granted", grantedUsd, near: true };
+}
+/**
+ * Grants the run one overrun step when it is close to its grant and its
+ * budget group and run tree have room. Cheap when it is not close: that is
+ * read without the lock. One attempt per call, so a poll never blocks on
+ * retries: a serialization conflict (or a lock not had in time) answers
+ * not_needed and near, and the caller's next poll, soon, asks again.
+ */
+export async function topUpCodingBudget(db, runId, now = new Date()) {
+    const state = await readState(db, runId);
+    if ("outcome" in state)
+        return state;
+    if (!isClose(state))
+        return { outcome: "not_needed", grantedUsd: state.grantedUsd, near: isNear(state) };
+    try {
+        const result = await db.$transaction((tx) => grantOnce(tx, runId, now), {
+            isolationLevel: "Serializable",
+            maxWait: TOP_UP_TX_MAX_WAIT_MS,
+        });
+        if (result.outcome === "granted" || result.outcome === "unavailable") {
+            topUpLog.info({ runId, outcome: result.outcome, grantedUsd: result.grantedUsd }, "coding run overrun top-up");
+        }
+        return result;
+    }
+    catch (err) {
+        if (!isSerializationConflict(err) && !isTransactionUnavailable(err))
+            throw err;
+        return { outcome: "not_needed", grantedUsd: state.grantedUsd, near: true };
+    }
+}
+/** How long one top-up waits to start its transaction: short, so a poll (and its heartbeat) is never held long. */
+export const TOP_UP_TX_MAX_WAIT_MS = 2_000;

package/dist/core/budget-wording.d.ts

@@ -6,17 +6,31 @@
  */
 import type { PrismaClient } from "#prisma";
 export interface BudgetFacts {
-    /** The run's own budget (a coding run's reservation); falls back to the agent's. */
+    /** The run's own budget (a coding run's reservation: its grant); falls back to the agent's. */
     runBudgetUsd?: number | null;
     agentBudgetUsd: number;
+    /** The run's budget before the agent's allowed overrun; absent for runs from before the setting. */
+    baseBudgetUsd?: number | null;
+    /** The most the run could have been topped up to (CodingRun.budgetLimitUsd); absent = its reservation. */
+    limitUsd?: number | null;
     budgetGroupName?: string | null;
     /** The run was refused before it started. */
     refused?: boolean;
 }
+/** A group name is operator-chosen text; keep it to one short, quote-free line. */
+export declare function groupName(name: string | null | undefined): string | null;
+/** The allowed overrun as a whole percent, or null when the run had none (no base, or it rounds to 0%). */
+export declare function overrunPercent(baseUsd: number | null | undefined, limitUsd: number): number | null;
 export declare function budgetSentence(facts: BudgetFacts): string;
+/**
+ * For a run that finished over its base budget: what it spent and by how much
+ * it went over, and whether that stayed inside the allowed overrun. Undefined
+ * when the spend is within the base budget.
+ */
+export declare function overrunSentence(costUsd: number, baseUsd: number, limitUsd: number): string | undefined;
 /**
  * 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 declare function loadBudgetSentence(db: Pick<PrismaClient, "run">, runId: string, status: string): Promise<string>;
+export declare function loadBudgetSentence(db: Pick<PrismaClient, "run" | "runBudgetEvent">, runId: string, status: string): Promise<string>;

package/dist/core/budget-wording.js

@@ -1,10 +1,18 @@
+import { hostBudgetSentence, loadBudgetEvent } from "./budget-events.js";
 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) {
+export function groupName(name) {
     const cleaned = (name ?? "").replace(/["`]/g, "").replace(/\s+/g, " ").trim().slice(0, MAX_GROUP_NAME_CHARS);
     return cleaned || null;
 }
+/** The allowed overrun as a whole percent, or null when the run had none (no base, or it rounds to 0%). */
+export function overrunPercent(baseUsd, limitUsd) {
+    if (baseUsd == null || !(baseUsd > 0) || !(baseUsd < limitUsd))
+        return null;
+    const percent = Math.round((limitUsd / baseUsd - 1) * 100);
+    return percent > 0 ? percent : null;
+}
 export function budgetSentence(facts) {
     const group = groupName(facts.budgetGroupName);
     if (facts.refused) {
@@ -14,6 +22,16 @@ export function budgetSentence(facts) {
             : `Out of budget: ${within}.`;
     }
     const runBudget = facts.runBudgetUsd ?? facts.agentBudgetUsd;
+    const base = facts.baseBudgetUsd;
+    const limit = facts.limitUsd ?? runBudget;
+    const percent = overrunPercent(base, limit);
+    if (base != null && percent !== null && runBudget > base) {
+        // Topped up only partly: what of the overrun its group and run tree had room for.
+        const overrun = runBudget < limit
+            ? `${usd(runBudget - base)} of its ${percent}% allowed overrun`
+            : `its ${percent}% allowed overrun`;
+        return `Out of budget: this run's ${usd(base)} budget and ${overrun} (${usd(runBudget)} in all) were used up.`;
+    }
     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) {
@@ -21,27 +39,47 @@ export function budgetSentence(facts) {
     }
     return `${used}.`;
 }
+/**
+ * For a run that finished over its base budget: what it spent and by how much
+ * it went over, and whether that stayed inside the allowed overrun. Undefined
+ * when the spend is within the base budget.
+ */
+export function overrunSentence(costUsd, baseUsd, limitUsd) {
+    if (!(baseUsd > 0) || !(costUsd > baseUsd))
+        return undefined;
+    const over = costUsd - baseUsd;
+    const percent = Math.round((over / baseUsd) * 100);
+    const within = costUsd <= limitUsd ? ", within its allowed overrun" : "";
+    return `Spent ${usd(costUsd)}, ${usd(over)} (${percent}%) over its ${usd(baseUsd)} budget${within}.`;
+}
 /**
  * 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 loaded = await loadBudgetEvent(db, runId);
+    if (loaded)
+        return hostBudgetSentence(loaded.event);
     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 } },
+                codingRun: { select: { budgetReservedUsd: true, budgetBaseUsd: true, budgetLimitUsd: 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;
+        const base = row.codingRun?.budgetBaseUsd == null ? NaN : Number(row.codingRun.budgetBaseUsd);
+        const limit = row.codingRun?.budgetLimitUsd == null ? NaN : Number(row.codingRun.budgetLimitUsd);
         return budgetSentence({
             runBudgetUsd: Number.isFinite(reserved) ? reserved : null,
+            baseBudgetUsd: Number.isFinite(base) ? base : null,
+            limitUsd: Number.isFinite(limit) ? limit : null,
             agentBudgetUsd,
             budgetGroupName: row.agent.budgetGroup?.name ?? null,
             refused,

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

@@ -5,7 +5,8 @@
  *
  *  1. fails queued runs that waited longer than CODING_QUEUE_TIMEOUT_SEC
  *     (coding_queue_timeout), with a conditional update so concurrent
- *     drains never double-fail a run;
+ *     drains never double-fail a run, then lets the executor clean up after
+ *     each (Executor.cleanupQueueTimeout);
  *  2. starts the oldest queued runs, at most as many as there are free
  *     slots, so order stays FIFO in practice. Starting is fire-and-forget,
  *     like dispatchRun: Executor.start resolves only when the run ends.

package/dist/core/coding-queue.js

@@ -30,6 +30,13 @@ export async function drainCodingQueue(options) {
             timedOut += 1;
             // Only this drain made the row failed (a concurrent drain matched zero rows); bounded, never throws.
             await fileSelfDefectForRun(options.selfDefects, runId);
+            // What a launch the cluster refused left behind (a continuation's in-progress check, its input).
+            try {
+                await executor.cleanupQueueTimeout?.(runId);
+            }
+            catch (err) {
+                queueLog.warn({ err, runId }, "queue-timeout cleanup failed");
+            }
         }
     }
     const active = await db.codingRun.count({

package/dist/core/cron.d.ts

@@ -5,7 +5,11 @@
 export interface DueCheckInput {
     schedule: string;
     timezone: string;
-    /** Start of the most recent window this agent already fired for, or null if never. */
+    /**
+     * Start of the most recent window this agent already fired for, or the
+     * moment its schedule was set (see startsSchedule); null only for a
+     * schedule set before that was recorded.
+     */
     lastScheduledAt: Date | null;
     now: Date;
 }
@@ -26,6 +30,20 @@ export interface DueCheckInput {
  * `now` that lands exactly on a boundary.
  */
 export declare function dueWindow(input: DueCheckInput): Date | null;
+export interface ScheduleState {
+    schedule: string | null;
+    timezone: string;
+    scheduleEnabled: boolean;
+}
+/**
+ * Whether a schedule change starts the schedule afresh. Setting, changing
+ * (expression or timezone) or re-enabling a schedule does, so it first fires
+ * at its next window after that, never for one that passed before it existed
+ * or while it was off (see scheduleStartFields). Saving the schedule it
+ * already has does not, keeping its firing history. `before` is null for a
+ * new agent.
+ */
+export declare function startsSchedule(before: ScheduleState | null, after: ScheduleState): boolean;
 export declare function isDue(input: DueCheckInput): boolean;
 /** Throws a descriptive error for an invalid cron expression or timezone. */
 export declare function validateCronExpression(schedule: string, timezone: string): void;

package/dist/core/cron.js

@@ -31,6 +31,23 @@ export function dueWindow(input) {
     }
     return mostRecent;
 }
+/**
+ * Whether a schedule change starts the schedule afresh. Setting, changing
+ * (expression or timezone) or re-enabling a schedule does, so it first fires
+ * at its next window after that, never for one that passed before it existed
+ * or while it was off (see scheduleStartFields). Saving the schedule it
+ * already has does not, keeping its firing history. `before` is null for a
+ * new agent.
+ */
+export function startsSchedule(before, after) {
+    if (!after.schedule || !after.scheduleEnabled)
+        return false;
+    const unchanged = before !== null &&
+        before.scheduleEnabled &&
+        before.schedule === after.schedule &&
+        before.timezone === after.timezone;
+    return !unchanged;
+}
 export function isDue(input) {
     return dueWindow(input) !== null;
 }

package/dist/core/datastores.js

@@ -65,7 +65,7 @@ export function buildSharedDatastoreAccessor(agentId, datastore, db) {
             const datastoreId = await resolveDatastoreId(agentId, boundName, db);
             if (!datastoreId)
                 throw new Error("datastore_not_bound");
-            await datastore.setShared(datastoreId, key, value, opts);
+            await datastore.setShared(datastoreId, key, value, { ...opts, writerAgentId: agentId });
         },
         async delete(boundName, key) {
             const datastoreId = await resolveDatastoreId(agentId, boundName, db);

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

@@ -0,0 +1,14 @@
+import type { PrismaClient } from "#prisma";
+import type { Executor } from "../providers/executor/types.js";
+export interface ResolveDeferredCodingInput {
+    db: PrismaClient;
+    /** The starting process's own executor: the one with the coding configuration. */
+    executor: Executor;
+    runId: string;
+}
+/**
+ * Coding inputs of a run the native gateway dispatched (DeferredExecutor): resolved here, on the
+ * process that starts it, with its own executor — the gateway holds no coding configuration.
+ * Marker: a pending coding run whose CodingRun.workerImage is null. False: the run was refused.
+ */
+export declare function resolveDeferredCodingRun({ db, executor, runId }: ResolveDeferredCodingInput): Promise<boolean>;

package/dist/core/deferred-coding.js

@@ -0,0 +1,62 @@
+import { composeCodingTask } from "../coding/protocol.js";
+import { assertCodingProvider } from "../coding/provider.js";
+import { parseAllowedServiceNames } from "../coding/services/catalog.js";
+import { servicesInstructionNote } from "../coding/services/note.js";
+import { knowledgeSection } from "../knowledge/note.js";
+import { readKnowledgeIndexAt, readServiceDeclarationAt, resolveDispatchServices } from "./dispatch.js";
+/**
+ * Coding inputs of a run the native gateway dispatched (DeferredExecutor): resolved here, on the
+ * process that starts it, with its own executor — the gateway holds no coding configuration.
+ * Marker: a pending coding run whose CodingRun.workerImage is null. False: the run was refused.
+ */
+export async function resolveDeferredCodingRun({ db, executor, runId }) {
+    const run = await db.run.findUnique({
+        where: { id: runId },
+        include: { codingRun: true, agent: { include: { codingProfile: true } } },
+    });
+    const coding = run?.codingRun;
+    // A native run, or a coding run dispatch already resolved: nothing to do.
+    if (!run || !coding || coding.workerImage !== null)
+        return true;
+    const profile = run.agent.codingProfile;
+    if (!profile)
+        throw new Error(`coding_profile_missing: coding agent "${run.agentId}" has no coding profile.`);
+    assertCodingProvider(coding.provider);
+    // The provider is the run's own (fixed at dispatch); the toolchain and image ref are the profile's,
+    // read as they are when the run starts.
+    const selector = {
+        provider: coding.provider,
+        toolchain: profile.toolchain,
+        toolchainVersion: profile.toolchainVersion,
+        workerImageRef: profile.workerImageRef,
+    };
+    // Services before images, in dispatch's order: a run with both a refused declaration and a bad
+    // image ends refused. As at dispatch, only an agent allowed some service reads the declaration,
+    // and any refusal dispatch would have raised refuses the run here instead.
+    let services = [];
+    if (parseAllowedServiceNames(profile.services).length > 0) {
+        const outcome = await readServiceDeclarationAt(executor, coding.repository, coding.baseRef);
+        const resolved = await resolveDispatchServices(db, outcome, profile.services, executor, coding.provider, coding.task, run.agent.systemPrompt);
+        if ("refusal" in resolved) {
+            await db.run.updateMany({
+                where: { id: runId, status: "pending" },
+                data: { status: "refused", error: resolved.refusal, finishedAt: new Date() },
+            });
+            return false;
+        }
+        services = resolved.services;
+    }
+    if (!executor.resolveCodingWorkerImage) {
+        throw new Error("coding_execution_not_configured: this process cannot start coding runs.");
+    }
+    const workerImage = executor.resolveCodingWorkerImage(selector);
+    const toolImage = executor.resolveCodingToolImage?.(selector) ?? null;
+    const knowledge = await readKnowledgeIndexAt(executor, coding.repository, coding.baseRef);
+    const task = composeCodingTask(run.agent.systemPrompt, coding.task, servicesInstructionNote(services), knowledge ? knowledgeSection(knowledge) : undefined);
+    // Conditional on the marker: of two racing starts, only one writes (both composed the same inputs).
+    await db.codingRun.updateMany({
+        where: { runId, workerImage: null },
+        data: { workerImage, toolImage, services, task },
+    });
+    return true;
+}

package/dist/core/delegation-child.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The one lookup both delegation paths (control-plane `delegate_to_*` and the sandbox gateway's
+ * `durableDelegate`) use to find the child a delegation call already created, so a re-executed
+ * delegate step (a resume, or a takeover under a new version) waits on that child again instead
+ * of refusing it as a duplicate.
+ */
+import type { PrismaClient } from "#prisma";
+export type DelegationChildDb = Pick<PrismaClient, "run">;
+/**
+ * The child a delegation call already created, if any: exact key first (Run.parentCallId, the
+ * model's tool-call id), then the single child of that agent with no key. Two or more such
+ * children are ambiguous and adopt none.
+ *
+ * A caller with a call id is a re-run of a recorded step, so an unkeyed child can only be a
+ * legacy row created before parentCallId existed; it is adopted in any status, because it may
+ * have finished while the lead was between deploys and its result is what the step is owed. A
+ * caller without a call id cannot tell a re-run from a new call (its children are unkeyed too),
+ * so it adopts only a drivable child; a finished one leaves the call to the once-per-agent
+ * refusal. `createdAt` is the child row's creation time (Run.startedAt, set when the row is
+ * written and never rewritten), from which the caller measures its wait bound.
+ */
+export declare function findDelegationChild(db: DelegationChildDb, parentRunId: string, childAgentId: string, parentCallId: string | undefined): Promise<{
+    id: string;
+    createdAt: Date;
+} | null>;

package/dist/core/delegation-child.js

@@ -0,0 +1,37 @@
+import { DRIVABLE } from "./run-status.js";
+/**
+ * The child a delegation call already created, if any: exact key first (Run.parentCallId, the
+ * model's tool-call id), then the single child of that agent with no key. Two or more such
+ * children are ambiguous and adopt none.
+ *
+ * A caller with a call id is a re-run of a recorded step, so an unkeyed child can only be a
+ * legacy row created before parentCallId existed; it is adopted in any status, because it may
+ * have finished while the lead was between deploys and its result is what the step is owed. A
+ * caller without a call id cannot tell a re-run from a new call (its children are unkeyed too),
+ * so it adopts only a drivable child; a finished one leaves the call to the once-per-agent
+ * refusal. `createdAt` is the child row's creation time (Run.startedAt, set when the row is
+ * written and never rewritten), from which the caller measures its wait bound.
+ */
+export async function findDelegationChild(db, parentRunId, childAgentId, parentCallId) {
+    const select = { id: true, startedAt: true };
+    const found = (row) => ({ id: row.id, createdAt: row.startedAt });
+    if (parentCallId) {
+        // Same agent too: a call id is the same call only if it names the same sub-agent. A colliding
+        // id from another agent is never adopted: its create then fails on the unique key, which the
+        // delegate tool answers with a tool-result error (delegation_conflict), never a run failure.
+        const keyed = await db.run.findFirst({ where: { parentRunId, parentCallId, agentId: childAgentId }, select });
+        if (keyed)
+            return found(keyed);
+    }
+    const legacy = await db.run.findMany({
+        where: {
+            parentRunId,
+            agentId: childAgentId,
+            parentCallId: null,
+            ...(parentCallId ? {} : { status: { in: [...DRIVABLE] } }),
+        },
+        select,
+        take: 2,
+    });
+    return legacy.length === 1 ? found(legacy[0]) : null;
+}

package/dist/core/dispatch.d.ts

@@ -1,7 +1,11 @@
 import type { Prisma, PrismaClient, Run, RunTrigger, Task } from "#prisma";
 import type { Executor } from "../providers/executor/types.js";
+import { type CodingProvider } from "../coding/provider.js";
+import { type DeclaredService } from "../coding/services/declaration.js";
+import { type ServiceResolution } from "../coding/services/resolve.js";
 import { type AttributionIntent } from "./attribution.js";
 import { type BudgetConstraint } from "./budget-groups.js";
+import { type KnowledgeNoteInput } from "../knowledge/note.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" | "localPullRequest" | "runAttribution" | "$queryRaw" | "$executeRawUnsafe">;
@@ -63,6 +67,12 @@ export interface DispatchRunOptions {
     triggeredById?: string | null;
     /** Sub-agent dispatch (see AgentSubAgent): links this run into a run tree. */
     parentRunId?: string;
+    /**
+     * The parent's delegation call (the model's tool-call id) that dispatches this sub-agent run.
+     * Unique per parent, so a re-executed delegate step finds the child its call created
+     * (findDelegationChild) instead of starting a second one.
+     */
+    parentCallId?: string;
     /**
      * Cost attribution for a run that starts a new attribution (issue event,
      * linked PR, explicit key), resolved before the call (attribution.ts
@@ -148,6 +158,19 @@ export declare function markRunFailedFromExecutorError(db: Pick<DispatchDb, "run
  * `run_tree_exhausted`, then a sentence for people.
  */
 export declare function budgetExhaustedError(constraint: BudgetConstraint): string;
+/**
+ * Serializes grouped coding dispatches (security review I1). Under
+ * Serializable, a row lock taken after the transaction's first read cannot
+ * queue anything: the snapshot is already fixed, so each waiter wakes up
+ * with a stale view and aborts. LOCK TABLE is the one statement that takes
+ * no snapshot, so as the transaction's first statement it makes a waiter's
+ * snapshot start only after the previous holder committed. SHARE ROW
+ * EXCLUSIVE conflicts with itself and with writes to BudgetGroup rows, but not
+ * with the ROW SHARE that foreign-key checks from Agent take, so attaching
+ * agents to groups is not blocked. It serializes grouped coding dispatches
+ * across all groups; each holds it only for one short transaction.
+ */
+export declare const GROUP_DISPATCH_LOCK_SQL = "LOCK TABLE \"BudgetGroup\" IN SHARE ROW EXCLUSIVE MODE";
 /**
  * Attempts for the persist transaction, and the jittered backoff between
  * them, for serialization failures, deadlocks and transactions that could
@@ -189,6 +212,25 @@ export type ContinuationCheck = {
  * run at all" (a user-facing refusal message, not a dispatch).
  */
 export declare function checkContinuation(reader: Pick<DispatchTx, "codingRun">, runId: string, repository: string, dispatchingOwnerId?: string | null): Promise<ContinuationCheck>;
+/** What dispatch learned about a coding run's .wardby/services.yaml before its transaction. */
+export type DeclarationOutcome = {
+    kind: "none";
+} | {
+    kind: "declared";
+    services: DeclaredService[];
+} | {
+    kind: "refused";
+    refusal: string;
+};
+/** The bundle index at a known base ref; also how a deferred coding run reads it when it starts. */
+export declare function readKnowledgeIndexAt(executor: Executor, repository: string, baseRef: string): Promise<KnowledgeNoteInput | undefined>;
+/** The declaration at a known base ref, parsed; also how a deferred coding run reads it when it starts. */
+export declare function readServiceDeclarationAt(executor: Executor, repository: string, baseRef: string): Promise<DeclarationOutcome>;
+/**
+ * Inside the transaction: the run's services, or the refusal that stops it. Takes only the
+ * catalog, so a deferred coding run's start resolves them the same way with a plain client.
+ */
+export declare function resolveDispatchServices(tx: Pick<Prisma.TransactionClient, "codingService">, outcome: DeclarationOutcome, allowed: unknown, executor: Executor, provider: CodingProvider, request: string, instructions: string | null): Promise<ServiceResolution>;
 /**
  * Persists every detached run input in one transaction, then invokes the
  * executor only after commit. A null result means the caller's transactional