@coreplane/switchboard 1.267.3 → 1.268.0

package/dist/assets/deploy/cloudflare-memory/worker.ts

@@ -4131,6 +4131,9 @@ export class RunHistoryDO extends DurableObject<Env> {
         userId: row.user_id,
         ...(who.userName ? { userName: who.userName } : {}),
         ...(who.parentRunId ? { parentRunId: who.parentRunId } : {}),
+        ...(who.parentInstanceId ? { parentInstanceId: who.parentInstanceId } : {}),
+        ...(who.idempotencyKey ? { idempotencyKey: who.idempotencyKey } : {}),
+        ...(who.costCapUsd !== undefined ? { costCapUsd: who.costCapUsd } : {}),
         threadKey: row.thread_key,
         channelId: row.channel_id,
         ...(row.agent ? { agent: row.agent } : {}),
@@ -4379,12 +4382,23 @@ function parseUsageJson(raw: string | null): RunUsage | undefined {
 }
 
 /** The two identity fields the by-user aggregate needs off a summary, read leniently. */
-function identityOfSummary(raw: string): { userName?: string; parentRunId?: string } {
+function identityOfSummary(raw: string): {
+  userName?: string;
+  parentRunId?: string;
+  parentInstanceId?: string;
+  idempotencyKey?: string;
+  costCapUsd?: number;
+} {
   try {
     const s = JSON.parse(raw) as Record<string, unknown>;
     return {
       ...(typeof s.userName === "string" && s.userName ? { userName: s.userName } : {}),
       ...(typeof s.parentRunId === "string" && s.parentRunId ? { parentRunId: s.parentRunId } : {}),
+      ...(typeof s.parentInstanceId === "string" && s.parentInstanceId ? { parentInstanceId: s.parentInstanceId } : {}),
+      ...(typeof s.idempotencyKey === "string" && s.idempotencyKey ? { idempotencyKey: s.idempotencyKey } : {}),
+      ...(typeof s.costCapUsd === "number" && Number.isFinite(s.costCapUsd) && s.costCapUsd > 0
+        ? { costCapUsd: s.costCapUsd }
+        : {}),
     };
   } catch {
     return {};
@@ -5689,6 +5703,14 @@ function parseClaim(b: Record<string, unknown>): Validated<ClaimRequest> {
     if (typeof meta.idempotencyKey !== "string" || !IDEMPOTENCY_KEY_PATTERN.test(meta.idempotencyKey))
       return invalid("run.meta.idempotencyKey must be <parentInstanceId>:<step>");
   }
+  if (
+    meta.costCapUsd !== undefined &&
+    (meta.parentInstanceId === undefined ||
+      typeof meta.costCapUsd !== "number" ||
+      !Number.isFinite(meta.costCapUsd) ||
+      meta.costCapUsd <= 0)
+  )
+    return invalid("run.meta.costCapUsd must be a positive coordinator cap");
   // The restart tag (record 0064) names the predecessor run whose windows the
   // claim reuses and rides the `child-resumed` event's reason: a run id or
   // absent, never another shape.

package/dist/assets/deploy/cloudflare-resident/imageReconcileState.ts

@@ -0,0 +1,28 @@
+/** One deploy's durable progress for a resident container. A repeated
+ *  reconcile may retry a deferred stop or collect an inactive container's
+ *  report, but must not stop a replacement that is still hydrating. */
+export interface DeployImageReconcileState {
+  build: string;
+  cycleIssued: boolean;
+  cycleStoppedAt?: string;
+  containerBeforeCycle?: string;
+}
+
+export type DeployImageReconcileAction = "start" | "retry-cycle" | "await-report" | "verified";
+
+export function nextDeployImageReconcile(
+  build: string,
+  stored: unknown,
+  reportPending: boolean,
+): DeployImageReconcileAction {
+  if (!stored || typeof stored !== "object") return "start";
+  const state = stored as Record<string, unknown>;
+  if (state.build !== build || typeof state.cycleIssued !== "boolean") return "start";
+  if (!reportPending) return "verified";
+  return state.cycleIssued ? "await-report" : "retry-cycle";
+}
+
+/** A fresh boot after the requested stop can finish hydration and report. */
+export function replacementContainerStarted(before: string | undefined, current: string | undefined): boolean {
+  return before !== undefined && current !== undefined && before !== current;
+}

package/dist/assets/deploy/cloudflare-resident/shared.ts

@@ -30,9 +30,8 @@ export const REFRESH_INTERVAL_S = 600;
  *  ten-minute buckets since the last instance. */
 export const IDLE_REFRESH_INTERVAL_S = 6 * 60 * 60;
 
-/** The thread user pool the image carries (`worker2`..`worker17`): one OS
- *  user per attached thread, and the bound on how many bindings one sweep
- *  step can have to check. */
+/** The image's `worker2`..`worker17` pool: 16 one-use identities per VM
+ *  generation for thread owners and disposable operations. */
 export const THREAD_POOL_SIZE = 16;
 
 /** Exec budgets. Each is a refresh step's own budget too (refresh.ts), so a

package/dist/assets/deploy/cloudflare-resident/worker.ts

@@ -89,6 +89,11 @@ import {
 } from "./legacyCredentials.js";
 import { hasUnexpectedOwnedThreadDir } from "./orphanThreadUsers.js";
 import { KeyedAsyncLock } from "./keyedAsyncLock.js";
+import {
+  nextDeployImageReconcile,
+  replacementContainerStarted,
+  type DeployImageReconcileState,
+} from "./imageReconcileState.js";
 import {
   registeredRunAllowsClaim,
   registeredRunAllowsReattach,
@@ -179,15 +184,17 @@ import { shellQuote } from "../../src/execution/shellQuote.js";
 import { envFromRequest } from "../../src/execution/sandboxEnv.js";
 import { CREDENTIAL_EXPIRY_MARGIN_MS } from "../../src/execution/residentCredentials.js";
 import { destroyWithPersistentFence } from "../../src/execution/residentDestroyGate.js";
-import { ResidentRecreateAdmission } from "../../src/execution/residentRecreateAdmission.js";
+import { ResidentRecreateAdmission, idleForPoolRecycle } from "../../src/execution/residentRecreateAdmission.js";
 import {
   claimPoolBinding,
   mayRunAsPoolUser,
+  ownedPoolUsers,
   parsePoolBindings,
   parseSpentPoolUsers,
   rebuildPoolBindingIndex,
   releasePoolBinding,
   spendPoolUser,
+  unavailablePoolUsers,
 } from "../../src/execution/residentPoolSpends.js";
 import {
   recordFiring,
@@ -591,16 +598,10 @@ const THREADS_DIR = "/workspace/threads";
  *  at the latest (disk is cache). */
 const OPS_DIR = "/workspace/ops";
 
-/** The thread-user pool. worker1 is the engine's build user; each
- *  attach allocates one of these to the thread (persisted in the binding)
- *  and every /exec /read /write for that thread runs privilege-dropped as
- *  that user. The pool is released by the inactivity sweep. */
-/** Pool of OS users for thread worktrees (worker1 is the build user). Sized
- *  for SIMULTANEOUS runs, not for every thread ever seen: a run returns its
- *  user via /detach when it ends, so the pool only fills when 16 runs on one
- *  repo are genuinely concurrent. Memory, not this list, is the real ceiling
- *  — see the instance_type note in wrangler.jsonc. Must match the useradd loop
- *  in the Dockerfile. */
+/** Pool of OS users for thread worktrees and disposable ops. A UID stays with
+ *  its first owner for this VM generation; detach releases the live binding,
+ *  not the UID spend. Exhaustion may recycle a proven-idle VM. Must match the
+ *  useradd loop in the Dockerfile. */
 const THREAD_USERS = Array.from({ length: THREAD_POOL_SIZE }, (_, i) => `worker${i + 2}`);
 
 /** Force-detach: after killing the thread user's processes, how long
@@ -1296,7 +1297,7 @@ interface AttachOk {
   returned?: Returned;
 }
 
-/** What `POST /detach` answers: whether the pool user went back, why not, and
+/** What `POST /detach` answers: whether the live binding was released, why not, and
  *  — on a release — what the tree still held (item 16a), now gone with it. */
 interface DetachAnswer {
   released: boolean;
@@ -1478,6 +1479,7 @@ const DRAIN_KEY = "drain";
  *  verify this resident's container on the new image; the next reconcile that
  *  finds it current reports to the registry and clears it. */
 const IMAGE_REPORT_PENDING_KEY = "imageReportPending";
+const IMAGE_RECONCILE_KEY = "imageReconcile";
 
 type OnboardResult = { ok: true; record: ResidentRecord } | { ok: false; status: number; error: string };
 
@@ -3910,8 +3912,8 @@ export class ResidentDO extends Sandbox<Env> {
     await this.ctx.storage.delete(INFRA_STREAK_KEY);
     await this.setResidentState("warm");
     // Event-triggered reclamation: the prune above already told the
-    // mirror which branches died; finished refs give their worktree and
-    // pool user back now, not at the idle TTL. Housekeeping, never a
+    // mirror which branches died; finished refs release their worktree and
+    // live binding now, not at the idle TTL. Housekeeping, never a
     // lifecycle flip — a failure here is a log line.
     try {
       const gc = await this.reclaimFinishedRefs(resource, facts.defaultRef, cycle.token);
@@ -5250,7 +5252,12 @@ export class ResidentDO extends Sandbox<Env> {
     }
     console.log(`image-stale (${where}): ${stale} — stopping so it restarts on the current image`);
     this.swapIncarnation(); // deliberate incarnation swap
-    await this.stop().catch((err) => console.log(`image-stale: stop failed: ${errMsg(err)}`));
+    try {
+      await this.stop();
+    } catch (err) {
+      console.log(`image-stale: stop failed: ${errMsg(err)}`);
+      if (where === "deploy") return "deferred";
+    }
     // A successful stop proves only that the old process is gone. The pending
     // marker deliberately survives it: the replacement's own hydration reports
     // after reaching `warm`, so `imageReport: current` can never precede a
@@ -5306,9 +5313,66 @@ export class ResidentDO extends Sandbox<Env> {
    *  added afterwards would wait for a report nothing sends (until the drain's
    *  `until`). Held first, every report finds its hold. */
   async reconcileForDeploy(resource: string): Promise<{ result: ImageReconcileResult; verified: boolean }> {
-    await registryStub(this.env).holdDrainFor([resource]);
-    await this.ctx.storage.put(IMAGE_REPORT_PENDING_KEY, { resource });
+    // The deploy's image report and an idle pool recycle both reason about the
+    // same VM. Admit reconciliation as disk work before its first await, so a
+    // recycle sees it as busy; a recycle already holding admission defers this
+    // pass for the deploy's bounded readiness retry.
+    const admitted = await this.withRecreateSafeAdmin(() => this.reconcileForDeployAdmitted(resource));
+    return "error" in admitted ? { result: "deferred", verified: false } : admitted;
+  }
+
+  private async reconcileForDeployAdmitted(
+    resource: string,
+  ): Promise<{ result: ImageReconcileResult; verified: boolean }> {
+    const progress = await this.ctx.storage.get<DeployImageReconcileState>(IMAGE_RECONCILE_KEY);
+    const pending = await this.ctx.storage.get<{ resource: string }>(IMAGE_REPORT_PENDING_KEY);
+    const action = nextDeployImageReconcile(BUILD.commit, progress, pending !== undefined);
+    if (action === "verified") return { result: "current", verified: true };
+    if (action === "start") {
+      await registryStub(this.env).holdDrainFor([resource]);
+      await this.ctx.storage.put(IMAGE_REPORT_PENDING_KEY, { resource });
+      await this.ctx.storage.put(IMAGE_RECONCILE_KEY, { build: BUILD.commit, cycleIssued: false });
+    }
+    if (action === "await-report") {
+      const active = await this.isRuntimeActive().catch(() => null);
+      if (active === false) await this.reportPendingImageCurrent("deploy");
+      else if (active === true) {
+        const [state, facts] = await Promise.all([
+          this.ctx.storage.get<ResidentState>(STATE_KEY),
+          this.ctx.storage.get<RepoFacts>(FACTS_KEY),
+        ]);
+        // A replacement can reuse the disk and leave `warm` unchanged; that
+        // hydrate shortcut does not send a report. A different boot after the
+        // successful stop is proof that a replacement started. Finish its
+        // hydration before reporting; an old warm state alone proves nothing.
+        if (replacementContainerStarted(progress?.containerBeforeCycle, await this.containerIdentity())) {
+          await this.ensureHydrated();
+          await this.reportPendingImageCurrent("deploy");
+        } else if (
+          state === "warm" &&
+          facts?.lastRestore?.at &&
+          Date.parse(facts.lastRestore.at) >= Date.parse(progress?.cycleStoppedAt ?? "")
+        ) {
+          await this.reportPendingImageCurrent("deploy");
+        }
+      }
+      return {
+        result: active === false ? "inactive" : "deferred",
+        verified: (await this.ctx.storage.get(IMAGE_REPORT_PENDING_KEY)) === undefined,
+      };
+    }
+    // Reading the boot ID runs a command and would wake a sleeping resident.
+    // Preserve the inactive path's report-without-start behavior.
+    const activeBeforeCycle = await this.isRuntimeActive().catch(() => null);
+    const containerBeforeCycle = activeBeforeCycle === true ? await this.containerIdentity() : undefined;
     const result = await this.reconcileImage("deploy", true);
+    if (result === "restarted")
+      await this.ctx.storage.put(IMAGE_RECONCILE_KEY, {
+        build: BUILD.commit,
+        cycleIssued: true,
+        cycleStoppedAt: new Date(systemClock()).toISOString(),
+        containerBeforeCycle,
+      } satisfies DeployImageReconcileState);
     if (result === "deferred") return { result, verified: false };
     // Inactivity reports synchronously; a successful stop does not. A
     // concurrent fresh start may also have hydrated while this reconcile
@@ -5615,7 +5679,11 @@ export class ResidentDO extends Sandbox<Env> {
   /** Storage bindings, active ops and inspections all reserve a pool user.
    * Claim inside this method, before its promise resolves: two concurrent
    * callers must not each read the same free UID before either can claim it. */
-  private async findFreePoolUser(excludeThreadKey?: string, excluded = new Set<string>()): Promise<string | undefined> {
+  private async findFreePoolUser(
+    excludeThreadKey?: string,
+    excluded = new Set<string>(),
+    preferred: readonly string[] = [],
+  ): Promise<string | undefined> {
     const all = await this.ctx.storage.list<ThreadBinding>({ prefix: THREAD_KEY_PREFIX });
     const used = new Set(
       [...all.values()].filter((b) => !b.evicted && b.user && b.threadKey !== excludeThreadKey).map((b) => b.user),
@@ -5623,7 +5691,7 @@ export class ResidentDO extends Sandbox<Env> {
     for (const u of this.opUsersInUse.keys()) used.add(u);
     for (const u of this.poolUsersInspecting) used.add(u);
     for (const u of excluded) used.add(u);
-    const user = THREAD_USERS.find((u) => !used.has(u));
+    const user = [...preferred, ...THREAD_USERS].find((u) => !used.has(u));
     if (user) this.poolUsersInspecting.add(user);
     return user;
   }
@@ -5660,19 +5728,82 @@ export class ResidentDO extends Sandbox<Env> {
     throw new Error("pool-user-stage-scan-invalid");
   }
 
+  /** A full one-use pool can serve the next request by destroying its VM,
+   * never by assigning another owner's UID. The admission mark closes every
+   * other entry before the idle read and stays held through the restore. */
+  private async recycleSpentPoolForAdmission(): Promise<true | ThreadErr> {
+    try {
+      const admission = await this.recreateAdmission.run(async (): Promise<true | ThreadErr> => {
+        const spent = parseSpentPoolUsers(await this.ctx.storage.get<unknown>(SPENT_POOL_USERS_KEY), THREAD_USERS);
+        if (!spent) return { error: "pool-generation-unknown: fresh VM required before UID assignment", status: 503 };
+        if (spent.size < THREAD_USERS.length) return true; // another checked recreate already cleared the generation
+        const [status, drain, imagePending, snapshot, registeredRuns, bindings] = await Promise.all([
+          this.getStatus(),
+          this.registry().getDrain(),
+          this.ctx.storage.get(IMAGE_REPORT_PENDING_KEY),
+          this.ctx.storage.get(SNAPSHOT_KEY),
+          this.registeredRunsBeyondOps(),
+          this.ctx.storage.list<ThreadBinding>({ prefix: THREAD_KEY_PREFIX }),
+        ]);
+        if (
+          !snapshot ||
+          !idleForPoolRecycle({
+            state: status.state,
+            draining: liveDrain(drain, systemClock()) !== null,
+            imagePending: imagePending !== undefined,
+            inFlight: this.inFlightCount(),
+            refreshAdmissions: this.refreshAdmissionsInFlight,
+            adminWork: this.adminWorkInFlight,
+            hydrating: this.hydration !== null,
+            registeredRuns,
+            liveBindings: [...bindings.values()].filter((binding) => !binding.evicted).length,
+            inspecting: this.poolUsersInspecting.size,
+          })
+        )
+          return {
+            error: "pool-recycle-required: all UIDs spent and the resident is not idle for checked VM recycle",
+            status: 503,
+          };
+        await this.recreateContainer("pool-recycle: all UIDs spent; no other resident work owns this VM");
+        await this.ensureHydrated();
+        const fresh = parseSpentPoolUsers(await this.ctx.storage.get<unknown>(SPENT_POOL_USERS_KEY), THREAD_USERS);
+        const ready = await this.getStatus();
+        const imageStillPending = (await this.ctx.storage.get(IMAGE_REPORT_PENDING_KEY)) !== undefined;
+        if (!fresh || fresh.size !== 0 || ready.state !== "warm" || imageStillPending)
+          return { error: "pool-recycle-failed: the restored VM is not warm, current and empty", status: 503 };
+        return true;
+      });
+      return admission.busy ? this.recreateRefusal() : admission.value;
+    } catch (err) {
+      console.log(`pool-recycle: checked VM recycle failed (${errMsg(err)})`);
+      return { error: "pool-recycle-failed: the checked VM restore did not complete", status: 503 };
+    }
+  }
+
   private async reserveSafePoolUser(owner: string, excludeThreadKey?: string): Promise<string | ThreadErr> {
-    const spent = parseSpentPoolUsers(await this.ctx.storage.get<unknown>(SPENT_POOL_USERS_KEY), THREAD_USERS);
+    let spent = parseSpentPoolUsers(await this.ctx.storage.get<unknown>(SPENT_POOL_USERS_KEY), THREAD_USERS);
     if (!spent) return { error: "pool-generation-unknown: fresh VM required before UID assignment", status: 503 };
-    const excluded = new Set(spent.keys());
+    let excluded = unavailablePoolUsers(spent, owner);
     let contaminated = false;
+    let recycled = false;
     for (;;) {
-      const user = await this.findFreePoolUser(excludeThreadKey, excluded);
-      if (!user)
+      const user = await this.findFreePoolUser(excludeThreadKey, excluded, ownedPoolUsers(spent, owner));
+      if (!user) {
+        if (!contaminated && excluded.size === THREAD_USERS.length && !recycled) {
+          recycled = true;
+          const result = await this.recycleSpentPoolForAdmission();
+          if (result !== true) return result;
+          spent = parseSpentPoolUsers(await this.ctx.storage.get<unknown>(SPENT_POOL_USERS_KEY), THREAD_USERS);
+          if (!spent) return { error: "pool-generation-unknown: fresh VM required before UID assignment", status: 503 };
+          excluded = unavailablePoolUsers(spent, owner);
+          continue;
+        }
         return contaminated
           ? { error: "pool-user-contaminated: no clean pool user is available", status: 503 }
           : excluded.size === THREAD_USERS.length
             ? { error: "pool-recycle-required: all UIDs spent on this VM; confirm idle and recreate it", status: 503 }
             : { error: "user-pool-exhausted: no safe pool user is available", status: 429 };
+      }
       let safe = false;
       try {
         const clean = !(await this.poolUserHasOldThreadDir(user, [])) && !(await this.poolUserHasOldStageContent(user));
@@ -7803,9 +7934,9 @@ export class ResidentDO extends Sandbox<Env> {
     return "evicted";
   }
 
-  /** POST /detach: a run has ended — give the thread's pool user back now
-   *  instead of holding it until the TTL sweep (the pool is sized for
-   *  simultaneous runs). A run starts from a clean tree (item 17), so the tree
+  /** POST /detach: a run has ended — release its live binding now instead of
+   *  holding it until the TTL sweep. The UID remains spent for this VM
+   *  generation. A run starts from a clean tree (item 17), so the tree
    *  goes whatever it holds: what it held — uncommitted changes, unpushed
    *  commits — is measured once, as the thread user, and named in the answer
    *  (`leftBehind`) so the loss is never silent. The one thing that keeps a
@@ -8787,6 +8918,7 @@ export class ResidentDO extends Sandbox<Env> {
     // The runs whose process lives in the container between operator calls
     // (item 44): what the deploy preflight must see, added to both counts.
     const registeredRuns = await this.registeredRunsBeyondOps();
+    const poolSpends = parseSpentPoolUsers(map.get(SPENT_POOL_USERS_KEY), THREAD_USERS);
     return {
       resource: map.get(RESOURCE_KEY) ?? null,
       state: this.destroying || map.get(DESTROY_UNCONFIRMED_KEY) ? "down" : (map.get(STATE_KEY) ?? "down"),
@@ -8818,7 +8950,10 @@ export class ResidentDO extends Sandbox<Env> {
       // running container the last deploy could not verify.
       imageReport: map.get(IMAGE_REPORT_PENDING_KEY) !== undefined ? "pending" : "current",
       recreateAdmissionHeld: this.recreateAdmission.pending || map.get(RECREATE_ADMISSION_KEY) === true,
-      poolUsersSpent: parseSpentPoolUsers(map.get(SPENT_POOL_USERS_KEY), THREAD_USERS)?.size ?? null,
+      poolUsersSpent: poolSpends?.size ?? null,
+      // Read-scoped owner receipts explain historical occupancy even after
+      // every live binding and disposable op has ended.
+      poolUserSpends: poolSpends ? [...poolSpends].map(([user, owner]) => ({ user, owner })) : null,
       // Item 22: who holds what, as the rows say — the mirror mutex and the
       // cycle/hydration leases, each judged against this incarnation.
       incarnation: this.incarnation,

package/dist/assets/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "switchboard",
-  "version": "1.267.3",
+  "version": "1.268.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "switchboard",
-      "version": "1.267.3",
+      "version": "1.268.0",
       "license": "Apache-2.0",
       "workspaces": [
         "web",
@@ -21023,7 +21023,7 @@
     },
     "packages/switchboard": {
       "name": "@coreplane/switchboard",
-      "version": "1.267.3",
+      "version": "1.268.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@earendil-works/pi-ai": "0.85.1",

package/dist/assets/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchboard",
-  "version": "1.267.3",
+  "version": "1.268.0",
   "private": true,
   "description": "Mention it in Slack and an agent reviews the PR, ships the fix, or answers the question — on the model you choose, with its tools running where you decide.",
   "license": "Apache-2.0",

package/dist/assets/source.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.267.3",
-  "commit": "deb60c5f49012fb663a5797168b9e02d2ba394a7",
-  "builtAt": "2026-09-29T04:50:34.175Z"
+  "version": "1.268.0",
+  "commit": "f1bc76a31780740930006bd492101666268596da-dirty",
+  "builtAt": "2026-09-29T08:06:43.354Z"
 }

package/dist/assets/src/core/budgets.ts

@@ -255,6 +255,10 @@ export const PROVIDER_RETRY_BACKOFFS_MS = [5_000, 15_000, 45_000] as const;
  *  model call itself remains bounded by the run's lease. */
 export const MODEL_STREAM_HEARTBEAT_MS = 15_000;
 
+/** A residents page re-reads the registry while open so a deploy's drain and
+ *  image reports advance even when no run can attach to trigger its feed. */
+export const RESIDENT_LISTING_POLL_MS = 30_000;
+
 /** A hosted ship parent's deadline margin past the pipeline's wall clock
  *  (record 0060): the row's `state.hosting.until` is the hand-off time plus
  *  the instance's `caps.maxMinutes` plus this hour, absorbing the runner's own

package/dist/assets/src/core/coordinator/contract.ts

@@ -307,12 +307,13 @@ export interface ExistingPrPublicationBinding {
   owner: { instanceId: string; unit: string };
 }
 
-/** What a coordinator's spawn stamps on the child's every row: the instance
- *  the child belongs to and the key the spawn carried — and, for the child's
- *  own post-step, the base its pull request targets. */
+/** What a coordinator's spawn stamps on the child's every row: its instance,
+ *  spawn key and admitted cost cap, plus the base for its PR post-step. */
 export interface CoordinatorTag {
   parentInstanceId: string;
   idempotencyKey: string;
+  /** The unit's original dollar limit, fixed at admission; absent means no cost cap. */
+  costCapUsd?: number;
   /** The unit's durable write branch, read from its row at child admission. */
   branch?: string;
   /** Workflow transport for a recovered child. Identity and idempotency remain
@@ -346,15 +347,20 @@ export interface CoordinatorTag {
   publication?: ExistingPrPublicationBinding;
 }
 
-/** The tag as the two flat record fields, or nothing — so a row, a summary
- *  and a record spread the same thing and a run with no coordinator carries no
- *  key. The base never rides here: rows and records keep the shape written
- *  before it existed. */
+/** The tag's identity and optional cap as flat record fields, or nothing — so
+ *  a row, summary and record agree. The base never rides here. */
 export function coordinatorFields(tag: CoordinatorTag | undefined): {
   parentInstanceId?: string;
   idempotencyKey?: string;
+  costCapUsd?: number;
 } {
-  return tag ? { parentInstanceId: tag.parentInstanceId, idempotencyKey: tag.idempotencyKey } : {};
+  return tag
+    ? {
+        parentInstanceId: tag.parentInstanceId,
+        idempotencyKey: tag.idempotencyKey,
+        ...(tag.costCapUsd !== undefined ? { costCapUsd: tag.costCapUsd } : {}),
+      }
+    : {};
 }
 
 /** The parent ship record: what the bot writes at an instance's creation and

package/dist/assets/src/core/costs.ts

@@ -516,6 +516,8 @@ export interface CostReport {
   /** Each biller's daily invoice tie-out (item 4d); absent when no provider block is known
    *  (a report built without the wiring) or run history is off. */
   billers?: BillerTieOut[];
+  /** Ship children across this bot's runs, independent of the Cloudflare group. */
+  shipSpend?: import("./shipSpend.js").ShipSpendReport;
 }
 
 /** What the report carries beyond the priced rows: the account behind the

package/dist/assets/src/core/runEvents.ts

@@ -974,6 +974,7 @@ export type RunEvent =
       type: "coordinator_tag";
       parentInstanceId: string;
       unit?: string;
+      costCapUsd?: number;
       branch?: string;
       transportWorkflowId?: string;
       recovery?: import("./coordinator/contract.js").CoordinatorTag["recovery"];

package/dist/assets/src/core/runLedger/types.ts

@@ -99,6 +99,8 @@ export interface LiveRunMeta {
    *  still sends the parent its event and a retried spawn finds its run. */
   parentInstanceId?: string;
   idempotencyKey?: string;
+  /** The original Ship unit cap carried by the claim, available before its tag event is retained. */
+  costCapUsd?: number;
   /** Where the run's conversation started (item 52), so a reclaimed run's
    *  record still says so: `parent` for a spawned child, `channel` otherwise. */
   seed?: RunSeed;

package/dist/assets/src/core/runRecord.ts

@@ -227,6 +227,8 @@ export interface RunRecord {
    *  item 48), stored at the claim so a retried spawn finds its run. Present
    *  exactly when `parentInstanceId` is — both or neither, never one alone. */
   idempotencyKey?: string;
+  /** The coordinator unit's original cost cap, carried by each child. */
+  costCapUsd?: number;
   /** The plan runner instance this run's hand-off created (record 0051 R2;
    *  item 2): the last `ship_handoff` event, folded at the assembly like the
    *  coordinator tag. Present only on a ship run whose hand-off succeeded;
@@ -1195,6 +1197,14 @@ export function isRunRecord(v: unknown): v is RunRecord {
     (typeof r.idempotencyKey !== "string" || !IDEMPOTENCY_KEY_PATTERN.test(r.idempotencyKey))
   )
     return false;
+  if (
+    r.costCapUsd !== undefined &&
+    (r.parentInstanceId === undefined ||
+      typeof r.costCapUsd !== "number" ||
+      !Number.isFinite(r.costCapUsd) ||
+      r.costCapUsd <= 0)
+  )
+    return false;
   // The instance a ship run's hand-off created (record 0051 R2; item 2).
   if (r.instanceId !== undefined && (typeof r.instanceId !== "string" || !INSTANCE_ID_PATTERN.test(r.instanceId)))
     return false;

package/dist/assets/src/core/runUsage.ts

@@ -1,4 +1,5 @@
 import type { RunEvent } from "./runEvents.js";
+import { unitOfIdempotencyKey } from "./coordinator/contract.js";
 
 // What a run cost in tokens, and who it belongs to — the data behind the cost
 // dimensions of the costs page (docs/reference/specs/costs.md items 10–10a) and
@@ -200,6 +201,9 @@ export interface UsageRun {
   userName?: string;
   /** A child run is billed to whoever started its parent (run-history item 46). */
   parentRunId?: string;
+  parentInstanceId?: string;
+  idempotencyKey?: string;
+  costCapUsd?: number;
   /** The thread the run ran in and the channel it belongs to (platform-namespaced, invariant 4). */
   threadKey: string;
   channelId: string;
@@ -258,6 +262,8 @@ export interface UsageRow {
 
 export interface RunUsageReport {
   rows: UsageRow[];
+  /** Individual Ship children retained for the unit-spend trend; old snapshots omit this. */
+  shipRuns?: ShipRunUsage[];
   /** Runs in range whose usage is not known yet (written before the field; backfill outstanding). */
   pending: number;
   /** The oldest finish the store still holds, so a page can bound its range to the data. */
@@ -265,6 +271,33 @@ export interface RunUsageReport {
   retentionDays: number;
 }
 
+export interface ShipRunUsage {
+  id: string;
+  unitKey: string;
+  finishedAt: number;
+  costCapUsd?: number;
+  /** Missing while an older record is still being backfilled. */
+  usage?: RunUsage;
+}
+
+/** The unit identity comes from the coordinator's durable key, never a thread or branch guess. */
+export function shipRunsOf(runs: readonly UsageRun[]): ShipRunUsage[] {
+  return runs.flatMap((run) => {
+    if (!run.parentInstanceId || !run.idempotencyKey) return [];
+    const unit = unitOfIdempotencyKey(run.idempotencyKey);
+    if (!unit) return [];
+    return [
+      {
+        id: run.id,
+        unitKey: `${run.parentInstanceId}:${unit}`,
+        finishedAt: run.finishedAt,
+        ...(run.costCapUsd !== undefined ? { costCapUsd: run.costCapUsd } : {}),
+        ...(run.usage !== undefined ? { usage: run.usage } : {}),
+      },
+    ];
+  });
+}
+
 export const dayOf = (epochMs: number): string => new Date(epochMs).toISOString().slice(0, 10);
 
 const identityOf = (who: UsageIdentity): UsageIdentity => ({
@@ -334,6 +367,7 @@ export function reportOfUsageRows(rows: RunUsageRows): RunUsageReport {
   const { rows: cells, pending } = aggregateUsage(rows.runs, (id) => rows.parents[id]);
   return {
     rows: cells,
+    shipRuns: shipRunsOf(rows.runs),
     // The store counts what it could not price; the fold sees the same runs without `usage`.
     pending: Math.max(pending, rows.pending),
     ...(rows.earliestFinishedAt !== undefined ? { earliestFinishedAt: rows.earliestFinishedAt } : {}),
@@ -356,6 +390,10 @@ function isUsageRun(v: unknown): v is UsageRun {
     typeof r.channelId === "string" &&
     (r.agent === undefined || typeof r.agent === "string") &&
     (r.parentRunId === undefined || typeof r.parentRunId === "string") &&
+    (r.parentInstanceId === undefined || typeof r.parentInstanceId === "string") &&
+    (r.idempotencyKey === undefined || typeof r.idempotencyKey === "string") &&
+    (r.costCapUsd === undefined ||
+      (typeof r.costCapUsd === "number" && Number.isFinite(r.costCapUsd) && r.costCapUsd > 0)) &&
     typeof r.startedAt === "number" &&
     typeof r.finishedAt === "number" &&
     (r.usage === undefined || isRunUsage(r.usage))
@@ -382,6 +420,7 @@ export function isRunUsageReport(v: unknown): v is RunUsageReport {
   if (typeof v !== "object" || v === null) return false;
   const r = v as Record<string, unknown>;
   if (!Array.isArray(r.rows) || !hasReportTail(r)) return false;
+  if (r.shipRuns !== undefined && (!Array.isArray(r.shipRuns) || !r.shipRuns.every(isShipRunUsage))) return false;
   return r.rows.every(
     (row) =>
       isIdentity(row) &&
@@ -394,3 +433,17 @@ export function isRunUsageReport(v: unknown): v is RunUsageReport {
       isRunUsage((row as UsageRow).usage),
   );
 }
+
+function isShipRunUsage(v: unknown): v is ShipRunUsage {
+  if (typeof v !== "object" || v === null) return false;
+  const r = v as ShipRunUsage;
+  return (
+    typeof r.id === "string" &&
+    typeof r.unitKey === "string" &&
+    typeof r.finishedAt === "number" &&
+    Number.isFinite(r.finishedAt) &&
+    (r.costCapUsd === undefined ||
+      (typeof r.costCapUsd === "number" && Number.isFinite(r.costCapUsd) && r.costCapUsd > 0)) &&
+    (r.usage === undefined || isRunUsage(r.usage))
+  );
+}