@coreplane/switchboard 1.243.0 → 1.245.0

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

@@ -30,11 +30,34 @@
 // arrive in the input rather than from the agent registry.
 
 import type { ShipRoundOutcome } from "../runEvents.js";
+import type { Handoff } from "./handoff.js";
+import { progressOf, renderRenewal, renewalDecision, type PushedHeadFact, type RenewalDecision } from "./renewal.js";
 import type { RunStatus } from "../runRecord.js";
 import { normalizeHead, sameCommit } from "../reviewedHead.js";
-import { formatFinding, type Finding, type FindingDisposition, type ReviewVerdictKind } from "../reviewVerdict.js";
+import {
+  ADDRESS_SEVERITIES,
+  DEFAULT_ADDRESS_SEVERITY,
+  findingsAtOrAbove,
+  formatFinding,
+  isAddressSeverity,
+  type AddressSeverity,
+  type AddressSeveritySource,
+  type Finding,
+  type FindingDisposition,
+  type ReviewVerdictKind,
+} from "../reviewVerdict.js";
 import { parsePlanUnit, planUnitIds } from "./contract.js";
-import { carve, loopPosition, MINUTE_MS, SHIP_WAIT, type Carve, type Loop } from "../budgets.js";
+import {
+  carve,
+  DEFAULT_GRANT,
+  loopPosition,
+  MINUTE_MS,
+  SHIP_WAIT,
+  type Carve,
+  type Grant,
+  type GrantSource,
+  type Loop,
+} from "../budgets.js";
 
 const MIN = MINUTE_MS;
 
@@ -391,7 +414,14 @@ export function presetOf(kind: RoundKind): ChildPreset {
  *  turn: the unit's contract, or the review turn from the pull request and the
  *  prior rounds' records, or the findings message from the review run's verdict. */
 export type Brief =
-  | { kind: "contract"; unit: string; rebase: { branch: string; onto: string } }
+  | {
+      kind: "contract";
+      unit: string;
+      rebase: { branch: string; onto: string };
+      /** A renewal's segment (decision 0046): the child continues the previous
+       *  segment's work from `from`, briefed with that run's write-up and handoff. */
+      continue?: { segment: number; from?: string; previousRunId?: string };
+    }
   | {
       kind: "review";
       unit: string;
@@ -455,6 +485,13 @@ export type ChildFacts =
       /** The dispositions a coding run recorded, as it submitted them: the machine matches them to the round's findings. */
       dispositions?: FindingDisposition[];
       handoff?: boolean;
+      /** The renewal's facts (decision 0046): the heads the run pushed, when
+       *  its lease began, what it cost (null when a model had no price) and
+       *  the handoff's lists — progress is read off these, never asked. */
+      pushed?: PushedHeadFact[];
+      leaseStartedAt?: number;
+      costUsd?: number | null;
+      handoffLists?: Handoff;
     };
 
 /** What heads the unit's branch on GitHub: nothing, an open pull request, or —
@@ -524,7 +561,38 @@ export type UnitEnding =
       /** A changes-requested review posted this round before the stop. */
       postedReview?: boolean;
     }
-  | { kind: "aborted"; reason: string; round?: RoundRef; reviewRounds: number; finalReply?: string }
+  | {
+      kind: "aborted";
+      reason: string;
+      round?: RoundRef;
+      reviewRounds: number;
+      finalReply?: string;
+      /** A round-0 end without a pull request that was judged for renewal and
+       *  refused: the decision and the card's sentence (decision 0046). */
+      renewal?: { decision: Extract<RenewalDecision, { renew: false }>; line: string };
+    }
+  /** The coding round ended at its lease with the unit unfinished, the row
+   *  showed progress and the grant renewed: this segment is over and the next
+   *  opens in the same thread from `from` under a fresh lease, the coding
+   *  child's write-up as its request (decision 0046, Renewal). */
+  | {
+      kind: "continued";
+      round: RoundRef;
+      /** The coding child whose write-up and handoff the continuation is briefed with. */
+      runId: string;
+      /** The segment the renewal opens (the first segment is 1). */
+      segment: number;
+      from?: string;
+      renewalsLeft: number;
+      /** The session's spend so far, this segment's children included; null when a run's model had no price. */
+      spendUsd: number | null;
+      handoff?: Handoff;
+      /** The coding child's write-up: the checkpoint the continuation is briefed with. */
+      finalReply?: string;
+      line: string;
+      reviewRounds: number;
+      spent: ShipBudgetSpent;
+    }
   | { kind: "no_verdict"; round: RoundRef; reviewRounds: number; finalReply?: string }
   | { kind: "interrupted"; round: RoundRef; runId: string; reviewRounds: number }
   | { kind: "refused"; refusal: string; message?: string; round: RoundRef; reviewRounds: number };
@@ -541,25 +609,28 @@ export type CoordinatorNote =
  *  person can see whether the cap or the child is the problem. */
 export type ShipBudgetSpent = Readonly<Record<"coding" | "review" | "waiting", number>>;
 
-/** The severity ship must address before an approve stands (agent-ship item
- *  9's gate): an approve carrying a finding at or above this level continues
- *  into the findings step exactly as a request_changes does. Ordered most to
- *  least severe. */
-export const ADDRESS_SEVERITIES = ["blocking", "major", "minor", "nit"] as const;
-export type AddressSeverity = (typeof ADDRESS_SEVERITIES)[number];
-/** Where the level in force came from, most specific wins: a `severity:` directive on the request (`run`), the user's or the channel's config scope, the org's `ship.addressSeverity` (or its default). */
-export type AddressSeveritySource = "org" | "channel" | "user" | "run";
-export const DEFAULT_ADDRESS_SEVERITY: AddressSeverity = "minor";
-export const isAddressSeverity = (v: unknown): v is AddressSeverity =>
-  (ADDRESS_SEVERITIES as readonly unknown[]).includes(v);
-
-const severityRank = (s: AddressSeverity): number => ADDRESS_SEVERITIES.indexOf(s);
-/** The findings the gate acts on at `level`: at or above it. Every parsed
- *  finding carries one of the ladder's four levels — the verdict parser
- *  (`parseVerdictInput`) drops an entry with any other severity, `fyi` or none,
- *  with a note — so nothing outside the ladder ever reaches the gate. */
-export function findingsAtOrAbove(findings: readonly Finding[], level: AddressSeverity): Finding[] {
-  return findings.filter((f) => severityRank(f.severity) <= severityRank(level));
+// The severity to address (agent-ship item 9's gate) is the verdict parser's
+// ladder (src/core/reviewVerdict.ts): the same level the parser holds a
+// submitted approve to, so a posted approve can carry a gated finding only
+// when it was parsed at a different level — the check below is defense in
+// depth behind the parser's. Re-exported here for the runner's callers.
+export {
+  ADDRESS_SEVERITIES,
+  DEFAULT_ADDRESS_SEVERITY,
+  findingsAtOrAbove,
+  isAddressSeverity,
+  type AddressSeverity,
+  type AddressSeveritySource,
+};
+
+export interface UnitSession {
+  segment: number;
+  renewalsSpent: number;
+  spendUsd: number | null;
+  continueFrom?: string;
+  /** The previous segment's coding run: its write-up and handoff brief the continuation. */
+  previousRunId?: string;
+  previousHandoff?: Handoff;
 }
 
 export interface UnitPipelineInput {
@@ -578,6 +649,18 @@ export interface UnitPipelineInput {
   addressSeverity?: AddressSeverity;
   /** Which layer set the level in force; named in the round header and the ending. */
   addressSeveritySource?: AddressSeveritySource;
+  /** The grant the request carried (decision 0046, the renewable lease):
+   *  renewals and a cost cap, and which layer granted it — named in the report;
+   *  absent reads as zero renewals and no cap, the org's. Nothing here spends
+   *  it yet: the renewal decision is the segment's end, not this unit's. */
+  grant?: Grant;
+  grantSource?: GrantSource;
+  /** The segment this pipeline runs (decision 0046, Renewal): absent for the
+   *  first; a renewal's carries its number, the renewals spent before it, the
+   *  session's spend so far, the sha it continues from and the previous
+   *  segment's handoff. Every step name of a later segment is prefixed with
+   *  it, so the Workflow's durable steps never collide across segments. */
+  session?: UnitSession;
   /** The instance's mark (agent-ship item 16): a generated one-unit plan — a
    *  `plan` with an id and no `path` — whose unit runs in the requesting
    *  thread and is re-issued with the request's own text, never a plan path. */
@@ -606,6 +689,10 @@ type Phase =
       runId: string;
       childHead?: string;
       finalReply?: string;
+      /** The renewal's facts off the child's record (decision 0046): its pushed heads, its lease's start, its handoff. */
+      childPushed?: PushedHeadFact[];
+      childLeaseStartedAt?: number;
+      childHandoff?: Handoff;
       /** The coding child died (`failed` or `interrupted`) after it may have
        *  pushed: the pr-check recovers a pushed branch by opening its pull
        *  request; with nothing pushed the unit ends with the child's own reason. */
@@ -639,6 +726,9 @@ export interface UnitPipelineState {
   readonly lastCodingRunId?: string;
   /** How the budget went so far, accrued as each answer moves the clock. */
   readonly spentMs: ShipBudgetSpent;
+  /** The session's dollars so far: the input's from earlier segments plus each
+   *  child's cost as its record is read; null once any run's cost is unknown. */
+  readonly spendUsd: number | null;
   readonly ending?: UnitEnding;
 }
 
@@ -674,6 +764,7 @@ export function openUnitPipeline(input: UnitPipelineInput, at: number): UnitPipe
     phase: { at: "pre-check" },
     reviewRounds: 0,
     spentMs: { coding: 0, review: 0, waiting: 0 },
+    spendUsd: input.session?.spendUsd ?? 0,
     findingsByRound: {},
     dispositionsByRound: {},
     reviewRunByRound: {},
@@ -713,12 +804,33 @@ function roundCarve(s: UnitPipelineState, round: RoundRef): Carve {
   return carve(remainingMs(s), { kind, index: loopPosition(loopOf(s), kind, round.index) }, loopOf(s));
 }
 
-const roundStep = (s: UnitPipelineState, round: RoundRef) => `${s.input.unit.id}/${round.index}/${round.kind}`;
+/** The prefix every step of this pipeline is named under: the unit id, and for
+ *  a renewal's segment the segment too (`U10/s2/…`), so the Workflow's durable
+ *  step cache never hands segment two the answers of segment one. */
+export const stepPrefixOf = (unit: string, session: UnitSession | undefined): string =>
+  session !== undefined && session.segment > 1 ? `${unit}/s${session.segment}` : unit;
+const stepPrefix = (s: UnitPipelineState) => stepPrefixOf(s.input.unit.id, s.input.session);
+const roundStep = (s: UnitPipelineState, round: RoundRef) => `${stepPrefix(s)}/${round.index}/${round.kind}`;
 
 function briefFor(s: UnitPipelineState, round: RoundRef): Brief {
   const unit = s.input.unit.id;
-  if (round.kind === "coding")
-    return { kind: "contract", unit, rebase: { branch: s.input.unit.branch, onto: s.input.base } };
+  if (round.kind === "coding") {
+    const session = s.input.session;
+    return {
+      kind: "contract",
+      unit,
+      rebase: { branch: s.input.unit.branch, onto: s.input.base },
+      ...(session !== undefined && session.segment > 1
+        ? {
+            continue: {
+              segment: session.segment,
+              ...(session.continueFrom !== undefined ? { from: session.continueFrom } : {}),
+              ...(session.previousRunId !== undefined ? { previousRunId: session.previousRunId } : {}),
+            },
+          }
+        : {}),
+    };
+  }
   const pr = s.pr!.number;
   if (round.kind === "findings") return { kind: "findings", unit, pr, reviewRunId: s.reviewRunByRound[round.index]! };
   const priorReview = s.reviewRunByRound[round.index - 1];
@@ -754,7 +866,7 @@ export function matchDispositions(
 /** The step the machine is at. Pure over the state: asked before every step
  *  and again after a replay, it names the same step for the same state. */
 export function nextAction(s: UnitPipelineState): CoordinatorAction {
-  const unit = s.input.unit.id;
+  const unit = stepPrefix(s);
   const p = s.phase;
   switch (p.at) {
     case "pre-check":
@@ -815,6 +927,14 @@ interface Transition {
 
 const ENDED: Phase = { at: "ended" };
 
+/** The session's dollars after one more child: unknown (null) once any run's
+ *  cost is — a total that left a run out would understate the spend a cap
+ *  judges — and a record without the field counts as unknown too. */
+function addSpend(sum: number | null, cost: number | null | undefined): number | null {
+  if (sum === null || cost === null || cost === undefined) return null;
+  return sum + cost;
+}
+
 function end(s: UnitPipelineState, ending: UnitEnding, notes: CoordinatorNote[] = []): Transition {
   return { state: { ...s, phase: ENDED, ending }, notes: [...notes, { type: "ended", ending }] };
 }
@@ -885,6 +1005,7 @@ function settleCoding(
   // round's findings enter the state (agent-ship item 6).
   let next: UnitPipelineState = {
     ...s,
+    spendUsd: addSpend(s.spendUsd, facts.costUsd),
     ...(facts.pr !== undefined ? { pr: { number: facts.pr.number, url: facts.pr.url } } : {}),
     ...(round.kind === "findings" && facts.dispositions !== undefined
       ? {
@@ -922,6 +1043,9 @@ function settleCoding(
       runId,
       ...(facts.headSha !== undefined ? { childHead: facts.headSha } : {}),
       ...(facts.finalReply !== undefined ? { finalReply: facts.finalReply } : {}),
+      ...(facts.pushed !== undefined ? { childPushed: facts.pushed } : {}),
+      ...(facts.leaseStartedAt !== undefined ? { childLeaseStartedAt: facts.leaseStartedAt } : {}),
+      ...(facts.handoffLists !== undefined ? { childHandoff: facts.handoffLists } : {}),
     },
   };
   return { state: next, notes: [] };
@@ -961,6 +1085,7 @@ function settleReview(
   const verdict = facts.verdict;
   const next: UnitPipelineState = {
     ...s,
+    spendUsd: addSpend(s.spendUsd, facts.costUsd),
     findingsByRound: { ...s.findingsByRound, [round.index]: verdict.findings },
     ...(facts.reviewHead !== undefined ? { lastReviewHead: facts.reviewHead } : {}),
     ...(verdict.summary !== undefined ? { lastVerdictSummary: verdict.summary } : {}),
@@ -1122,15 +1247,72 @@ function settlePrCheck(s: UnitPipelineState, phase: Extract<Phase, { at: "pr-che
         [roundNote(round, "aborted")],
       );
     }
-    const reason =
-      round.index === 0
-        ? `⚠️ Ship ended at round 0: the coding round ended without opening a pull request (a clarifying question, a budget write-up, an unproven push or a description-less push ends the pipeline here). No review round ran.`
-        : `⚠️ Round ${round.index}'s findings step left no open pull request heading \`${s.input.unit.branch}\` — the pull request was closed out from under the pipeline and none was reopened, so there is nothing to re-review.`;
+    // Round 0 ended without a pull request: the segment is over with the unit
+    // unfinished, and the grant decides whether the next opens (decision
+    // 0046, Renewal). Progress is read off the child's record — a head pushed
+    // to the unit's branch since the segment started, or a handoff that moved —
+    // never off its words; the decision then asks the grant's count, the cap
+    // and the fit, in that order, and a refusal names the clause. A plain
+    // abort keeps its old shape when nothing was pushed under a grant of zero:
+    // a clarifying question is not a stop to explain.
+    if (round.index === 0) {
+      const grant = s.input.grant ?? DEFAULT_GRANT;
+      const session = s.input.session;
+      const progress = progressOf({
+        branch: s.input.unit.branch,
+        pushed: phase.childPushed ?? [],
+        ...(session?.continueFrom !== undefined ? { startHead: session.continueFrom } : {}),
+        ...(phase.childLeaseStartedAt !== undefined ? { leaseStartedAt: phase.childLeaseStartedAt } : {}),
+        ...(session?.previousHandoff !== undefined && phase.childHandoff !== undefined
+          ? { handoff: { previous: session.previousHandoff, current: phase.childHandoff } }
+          : {}),
+      });
+      const decision = renewalDecision({
+        grant,
+        renewalsSpent: session?.renewalsSpent ?? 0,
+        spendUsd: s.spendUsd,
+        progress,
+        pipeline: s.input.caps,
+      });
+      const line = renderRenewal(decision, grant);
+      if (decision.renew)
+        return end(
+          s,
+          {
+            kind: "continued",
+            round,
+            runId: phase.runId,
+            segment: decision.segment,
+            ...(decision.from !== undefined ? { from: decision.from } : {}),
+            renewalsLeft: decision.renewalsLeft,
+            spendUsd: s.spendUsd,
+            ...(phase.childHandoff !== undefined ? { handoff: phase.childHandoff } : {}),
+            ...(phase.finalReply !== undefined ? { finalReply: phase.finalReply } : {}),
+            line,
+            reviewRounds: s.reviewRounds,
+            spent: s.spentMs,
+          },
+          [roundNote(round, "continued")],
+        );
+      const judged = grant.renewals > 0 || progress.progressed;
+      return end(
+        s,
+        {
+          kind: "aborted",
+          reason: `⚠️ Ship ended at round 0: the coding round ended without opening a pull request (a clarifying question, a budget write-up, an unproven push or a description-less push ends the pipeline here). No review round ran.`,
+          round,
+          reviewRounds: s.reviewRounds,
+          ...(phase.finalReply !== undefined ? { finalReply: phase.finalReply } : {}),
+          ...(judged ? { renewal: { decision, line } } : {}),
+        },
+        [roundNote(round, "aborted")],
+      );
+    }
     return end(
       s,
       {
         kind: "aborted",
-        reason,
+        reason: `⚠️ Round ${round.index}'s findings step left no open pull request heading \`${s.input.unit.branch}\` — the pull request was closed out from under the pipeline and none was reopened, so there is nothing to re-review.`,
         round,
         reviewRounds: s.reviewRounds,
         ...(phase.finalReply !== undefined ? { finalReply: phase.finalReply } : {}),
@@ -1475,6 +1657,12 @@ export function renderUnitReport(s: UnitPipelineState, facts?: MergeReadyFacts):
   // stated decision, never a silent one.
   const level = s.input.addressSeverity ?? DEFAULT_ADDRESS_SEVERITY;
   const levelLine = `Severity addressed: ${level} and above (set by ${s.input.addressSeveritySource ?? "org"}).`;
+  // The grant as the instance carries it (decision 0046): spent of granted,
+  // the cap when one is set, and who granted it — zero of zero until a scope
+  // or a directive says otherwise, and nothing spends it before the renewal
+  // decision exists.
+  const grant = s.input.grant ?? DEFAULT_GRANT;
+  const grantLine = `Renewals: 0 of ${grant.renewals} spent${grant.costCapUsd !== undefined ? `, cost cap $${grant.costCapUsd}` : ""} (granted by ${s.input.grantSource ?? "org"}).`;
   const lastFindings = s.findingsByRound[e.reviewRounds] ?? [];
   const skipped = lastFindings.filter((f) => !findingsAtOrAbove([f], level).length);
   const skippedLine =
@@ -1490,6 +1678,7 @@ export function renderUnitReport(s: UnitPipelineState, facts?: MergeReadyFacts):
         `✅ Merged after ${rounds}: ${e.pr.url} (squash \`${e.sha.slice(0, 7)}\`) — merged by the plan runner under \`plan:merge\`: the review approved at this head and the guards were green.`,
         verdictLine,
         levelLine,
+        grantLine,
         ...(skippedLine ? [skippedLine] : []),
         declinedLine,
       ].join("\n");
@@ -1498,6 +1687,7 @@ export function renderUnitReport(s: UnitPipelineState, facts?: MergeReadyFacts):
         `✅ Merge-ready after ${rounds}: ${e.pr.url}`,
         verdictLine,
         levelLine,
+        grantLine,
         ...(skippedLine ? [skippedLine] : []),
         declinedLine,
         // What the driver read at the approved head when it composed this
@@ -1543,7 +1733,19 @@ export function renderUnitReport(s: UnitPipelineState, facts?: MergeReadyFacts):
         reissue,
       ]);
     case "aborted":
-      return join([e.finalReply, e.reason, `⚠️ Ship aborted after ${rounds}.`, reissue]);
+      return join([
+        e.finalReply,
+        e.reason,
+        e.renewal !== undefined ? `🔁 Not renewed: ${e.renewal.line}.` : undefined,
+        `⚠️ Ship aborted after ${rounds}.`,
+        reissue,
+      ]);
+    case "continued":
+      return join([
+        e.finalReply,
+        `🔁 Segment ${e.segment - 1} ended at its lease with the unit unfinished — ${e.line}. Segment ${e.segment} opens in this thread${e.from !== undefined ? ` from \`${e.from.slice(0, 7)}\`` : ""} under a fresh ${s.input.caps.maxMinutes}-minute lease, with this segment's write-up as its request; ${e.renewalsLeft} renewal${e.renewalsLeft === 1 ? "" : "s"} remain${e.spendUsd !== null ? `, $${e.spendUsd.toFixed(2)} spent so far` : ""}.`,
+        budgetSplitLine(e.spent, s.input.caps.maxMinutes),
+      ]);
     case "no_verdict":
       return join([
         `⚠️ Review round ${e.round.index} ended without a submitted verdict (budget, refusal, or stop) — ship never converts that into a request for changes, so no findings step ran.`,

package/dist/assets/src/core/ship/renewal.ts

@@ -0,0 +1,155 @@
+// The renewal decision (decision 0046, Renewal: the grant decides, the lease
+// continues). A lease is sized by the infrastructure; the problem is bounded by
+// the grant. When a segment ends with its unit unfinished, the runner reads
+// progress off the row — never off a model's word — and renews only when three
+// things hold: the row shows progress, the grant has a renewal left and the
+// spend is under its cap, and the pipeline's ask still passes the fit.
+// Otherwise it stops and names the clause that failed; a person's reply spends
+// a renewal by hand. Pure and node-free: the unit machine (a Worker) and the
+// bot's routes compute the same decision from the same facts.
+
+import { fit, type Grant, type Pipeline } from "../budgets.js";
+import type { Handoff } from "./handoff.js";
+
+/** A head the run pushed, as the record carries it (run-history item 2). */
+export interface PushedHeadFact {
+  ref: string;
+  sha: string;
+  at?: number;
+}
+
+export interface ProgressInput {
+  /** The unit's branch: a push to any other ref is not the unit's progress. */
+  branch: string;
+  /** The heads the segment's coding run pushed (`RunRecord.pushed`). */
+  pushed: readonly PushedHeadFact[];
+  /** The head the segment started from — the previous segment's recorded sha.
+   *  Absent on a fresh branch, where any push is progress. */
+  startHead?: string;
+  /** When the segment's lease began; a push stamped before it is not this segment's. */
+  leaseStartedAt?: number;
+  /** The previous segment's handoff and this one's, when both exist. */
+  handoff?: { previous: Handoff; current: Handoff };
+}
+
+export type Progress =
+  | { progressed: true; by: "push"; sha: string }
+  | { progressed: true; by: "handoff" }
+  | { progressed: false; why: string };
+
+/** Two shas name one commit when the shorter is a prefix of the longer. */
+const sameSha = (a: string, b: string): boolean => {
+  const x = a.toLowerCase();
+  const y = b.toLowerCase();
+  return x.length <= y.length ? y.startsWith(x) : x.startsWith(y);
+};
+
+/** Progress is a fact the row records after unit eight and the runner reads
+ *  without a model: the last head pushed to the unit's branch that differs from
+ *  the head the segment started at and is not older than the lease; failing
+ *  that, a handoff whose follow-ups shrank or whose deviations grew. */
+export function progressOf(input: ProgressInput): Progress {
+  const last = [...input.pushed].reverse().find((h) => h.ref === input.branch);
+  if (last !== undefined) {
+    const newerThanLease =
+      input.leaseStartedAt === undefined || last.at === undefined || last.at >= input.leaseStartedAt;
+    const moved = input.startHead === undefined || !sameSha(last.sha, input.startHead);
+    if (newerThanLease && moved) return { progressed: true, by: "push", sha: last.sha };
+  }
+  const pushWhy = `no head newer than the lease's start was pushed to \`${input.branch}\``;
+  if (input.handoff === undefined) return { progressed: false, why: pushWhy };
+  const { previous, current } = input.handoff;
+  if (current.followUps.length < previous.followUps.length || current.deviations.length > previous.deviations.length)
+    return { progressed: true, by: "handoff" };
+  return { progressed: false, why: `${pushWhy} and the handoff is unchanged` };
+}
+
+export interface RenewalInput {
+  grant: Grant;
+  /** Renewals already spent under this request: the segments beyond the first. */
+  renewalsSpent: number;
+  /** Dollars spent under this request so far; null when a run's model had no
+   *  price, since a total that left a model's tokens out would understate it. */
+  spendUsd: number | null;
+  progress: Progress;
+  /** The pipeline the next segment would run: its fit is re-asserted before every segment. */
+  pipeline: Pipeline;
+}
+
+export type RenewalWhy = "no_progress" | "grant_exhausted" | "cost_cap" | "unfit";
+
+export type RenewalDecision =
+  | { renew: true; segment: number; from?: string; renewalsLeft: number }
+  | { renew: false; why: RenewalWhy; detail: string; renewalsLeft: number };
+
+const usd = (n: number): string => `$${n.toFixed(2)}`;
+
+/** The decision, in the order the record states the clauses: progress, the
+ *  grant's count, the cap, the fit. `segment` is the one the renewal opens
+ *  (the first segment is 1); `from` the sha it continues from when a push made
+ *  the progress. */
+export function renewalDecision(input: RenewalInput): RenewalDecision {
+  const renewalsLeft = Math.max(0, input.grant.renewals - input.renewalsSpent);
+  if (!input.progress.progressed) return { renew: false, why: "no_progress", detail: input.progress.why, renewalsLeft };
+  if (renewalsLeft === 0) {
+    const detail =
+      input.grant.renewals === 0
+        ? "the grant holds no renewals"
+        : `the grant's ${input.grant.renewals} renewal${input.grant.renewals === 1 ? "" : "s"} are spent`;
+    return { renew: false, why: "grant_exhausted", detail, renewalsLeft };
+  }
+  const cap = input.grant.costCapUsd;
+  if (cap !== undefined) {
+    if (input.spendUsd === null)
+      return {
+        renew: false,
+        why: "cost_cap",
+        detail: `spend is unknown (a model had no price) under the grant's cap of $${cap}`,
+        renewalsLeft,
+      };
+    if (input.spendUsd >= cap)
+      return {
+        renew: false,
+        why: "cost_cap",
+        detail: `spend ${usd(input.spendUsd)} reached the grant's cap of $${cap}`,
+        renewalsLeft,
+      };
+  }
+  const held = fit(input.pipeline);
+  if (!held.ok)
+    return {
+      renew: false,
+      why: "unfit",
+      detail: `a ${held.have}-minute segment cannot hold the ship loop (${input.pipeline.maxRounds} review rounds need ${held.need} min)`,
+      renewalsLeft,
+    };
+  return {
+    renew: true,
+    segment: input.renewalsSpent + 2,
+    ...(input.progress.by === "push" ? { from: input.progress.sha } : {}),
+    renewalsLeft: renewalsLeft - 1,
+  };
+}
+
+/** The card's words (the record's trace, steps 4 and 9): a renewal names its
+ *  number of the grant's and the sha it continues from; a stop names the
+ *  clause and, when renewals remain, the reply that spends one by hand. */
+export function renderRenewal(decision: RenewalDecision, grant: Grant): string {
+  if (decision.renew)
+    return `renewal ${decision.segment - 1} of ${grant.renewals}, continues ${decision.from !== undefined ? decision.from.slice(0, 7) : "the branch's head"}`;
+  const holds =
+    decision.renewalsLeft > 0
+      ? `grant holds ${decision.renewalsLeft} renewal${decision.renewalsLeft === 1 ? "" : "s"}`
+      : "the grant holds no renewals";
+  switch (decision.why) {
+    case "no_progress":
+      return decision.renewalsLeft > 0
+        ? `no progress in the last lease; ${holds}; reply continue to spend one`
+        : `no progress in the last lease; ${holds}`;
+    case "cost_cap":
+      return decision.renewalsLeft > 0 ? `${decision.detail}; ${holds} unspent` : decision.detail;
+    case "grant_exhausted":
+    case "unfit":
+      return decision.detail;
+  }
+}

package/dist/assets/src/core/trace/attrs.ts

@@ -34,6 +34,14 @@ export interface AttrDomain {
   /** The `<provider>/<model>` that took the turn — a ship run's children answer
    *  on different models, and the run page badges the switch per step. */
   model: string;
+  /** The tools a proxied call offered the model (model-proxy.md item 6): how
+   *  many, their names sorted and comma-joined, and the request's `tool_choice`
+   *  by its word — `auto` when tools came and nothing was said, `none` when no
+   *  tools came or the request said so, `any` for OpenAI's `required`, `tool`
+   *  for a named tool. */
+  tools: number;
+  toolNames: string;
+  toolChoice: "auto" | "none" | "any" | "tool";
   stopReason: "end_turn" | "tool_use" | "max_tokens" | "stop_sequence" | "other";
   inputTokens: number;
   outputTokens: number;
@@ -159,6 +167,9 @@ const ATTR_TYPE: Record<SpanAttrKey, "string" | "number" | "boolean"> = {
   backend: "string",
   command: "string",
   model: "string",
+  tools: "number",
+  toolNames: "string",
+  toolChoice: "string",
   stopReason: "string",
   inputTokens: "number",
   outputTokens: "number",

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

@@ -70,9 +70,10 @@ export interface TraceOptions {
   span?: Span;
   /** Which door the call came through when it was not the surface's own
    *  grammar: `route` for a command the request router bound from prose
-   *  (record 0036). Copied onto the registry's audit line, never read by a
-   *  handler. Absent for a typed command. */
-  source?: "route";
+   *  (record 0036), `confirm` for a stored input run at a confirmation's
+   *  click (record 0044). Copied onto the registry's audit line, never read
+   *  by a handler. Absent for a typed command. */
+  source?: "route" | "confirm";
 }
 
 export interface Span {