toolroll 0.9.27 → 0.9.28

package/dist/mate.js

@@ -9,7 +9,8 @@ import { redactSecretAssignments } from "./builder.js";
 import { MATE_CONTRACT } from "./mate-contract.js";
 import { MATE_MAX_PROPOSALS_PER_TURN, MATE_TOOL_SCHEMAS, executeMateTool, isMateTool, mateViewContextFor, projectLabelForMate, redactForMate, toolResultBytes } from "./mate-tools.js";
 import { composeSubscriptionMatePrompt, performSubscriptionMateRequest } from "./subscription-chat.js";
-import { leadContext } from './lead-context.js';
+import { LEAD_REPLY_LIMITS, leadContext } from './lead-context.js';
+import { shortenAsk } from './text-limits.js';
 import { envValue } from "./names.js";
 import { deliverableClaim, deliverableRepair, dropDeliverableClaims, replyCarriesDeliverable } from "./reply-shape.js";
 export const MATE_MESSAGE_MAX_CHARS = 2_000;
@@ -317,6 +318,9 @@ export async function runMateTurn(input) {
     let shownControl = false;
     /** The turn's one repair step for a reply that claims an attachment it does not carry. */
     let repaired = false;
+    /** The turn's one shorten step for a reply over its channel's message limit (LEAD_REPLY_LIMITS); still over, it is split. */
+    let shortened = false;
+    const replyLimit = input.channel === undefined ? null : LEAD_REPLY_LIMITS[input.channel];
     const unbacked = (text) => {
         const claim = deliverableClaim(text);
         if (claim === null || shownControl || replyCarriesDeliverable(text) || store.listMateTurnEvidence(turnId).length > 0)
@@ -447,7 +451,14 @@ export async function runMateTurn(input) {
                 history.push({ role: "operator", text: deliverableRepair(claim) });
                 continue;
             }
-            reply = claim === null ? answer.text : dropDeliverableClaims(answer.text);
+            const candidate = claim === null ? answer.text : dropDeliverableClaims(answer.text);
+            if (replyLimit !== null && candidate.length > replyLimit && !shortened && steps < maxSteps) {
+                shortened = true;
+                history.push({ role: "assistant", text: answer.text, calls: [] });
+                history.push({ role: "operator", text: shortenAsk([{ field: "Your reply", limit: replyLimit, length: candidate.length }]) });
+                continue;
+            }
+            reply = candidate;
             break;
         }
         if (answer.calls.length > MATE_MAX_CALLS_PER_STEP)

package/dist/operate.d.ts

@@ -1,5 +1,6 @@
 import { type IntegrationIo } from "./integrations.js";
 import { type OnboardIo } from "./agent-onboard.js";
+import { type Sizer } from "./task-sizing.js";
 import { type TriggerIo } from "./flow-triggers.js";
 import type { StepIo } from "./flow-steps.js";
 import type { FetchLike } from "./flow-share.js";
@@ -83,6 +84,8 @@ export type OperateOptions = {
         env?: Record<string, string | undefined>;
         openBrowser?: (url: string) => void;
     };
+    /** Injected by tests: the classifier that sizes filed tasks (none by default under test). */
+    filingSizer?: Sizer;
 };
 export type OnboardSeams = Partial<Pick<OnboardIo, "home" | "env" | "cwd" | "interactive" | "confirm" | "findRepo" | "checkConnection" | "pullRequests">>;
 export declare const OPERATE_HELP: string;

package/dist/operate.js

@@ -26,6 +26,8 @@ import { checkIntegrations, integrationsBrokenLine, integrationsNow, renderInteg
 import { buildHandoff, handoffLines, loginAccount, runOnboard } from "./agent-onboard.js";
 import { backupFiles, backupFolderOf, backupOwner, backupNow, restoreDatabase, startBackups } from "./backup.js";
 import { pushLimitSink } from "./provider-limits.js";
+import { installFilingSizer, ownerSizer, settleSizings } from "./task-sizing.js";
+import { tierLines, tierReport } from "./tier-report.js";
 import { limitsView } from "./limits-ui.js";
 import { startCodexLimits } from "./codex-limits.js";
 import { packageVersion, startMonitoring, targetOf } from "./monitoring.js";
@@ -176,7 +178,7 @@ import { TEMPLATES, templateByName } from "./templates.js";
 import { planTournament, planComparison, contestNoun, jointApprovalDigest, admitContest, crossReadyBarrier, finalizeContestant, recoverContests, maybeAggregate as contestMaybeAggregate, sweepContestCleanup, escalateOverdueContests } from "./contest.js";
 import { isDirectChatProvider, isSubscriptionChatProvider, priceOf, PRICED_MODELS } from "./converse.js";
 import { resolvePhaseAgent, resolveScopeProfile, resolveScopeChain, resolveRouteCandidates, routeOfTask, INSTALLATION_SCOPE } from "./agentconfig.js";
-import { isRiskLevel, legOf, projectRoute, riskConsequence, routeDigestOf, routeWords, RISK_LEVELS, PHASES as ROUTE_PHASES } from "./phase-routing.js";
+import { isRiskLevel, isTaskSize, legOf, projectRoute, riskConsequence, routeDigestOf, routeWords, RISK_LEVELS, TASK_SIZES, PHASES as ROUTE_PHASES } from "./phase-routing.js";
 import { observeProviderReadiness, reportProviderReadinessAuthed } from "./runner.js";
 import { parseDemoUrl, projectDemoUrl, saveProjectDemo } from "./project-demo.js";
 import { effectiveConcurrency, maySlotTake, parseProjectConcurrency, PROJECT_CONCURRENCY_DEFAULT, ProjectPasses, projectConcurrency, saveProjectConcurrency, savedProjectConcurrency } from "./project-concurrency.js";
@@ -423,6 +425,7 @@ Capabilities — what the work needs, recorded and probed, never valued
                                         the repo, asks you questions, and
                                         proposes a scope you approve
   toolroll task route <id> [--risk routine|elevated|high]
+      [--size small|medium|large] [--risky yes|no]
       [--phase plan|build|repair --provider <p> [--model <m>] | --clear-phase <phase>]
       --as <you> --token <t>            which agent plans, builds, and repairs
                                         this task, with the reason for
@@ -500,6 +503,17 @@ Agents — which provider and model each phase runs on
                                         the STRONG agent high-risk, strict,
                                         screenshot-proof, and automerge
                                         routes reach for; never inferred
+  toolroll config set build --tier light --provider <p> --model <m>
+      [--repo <path>] --as <you> --token <t>
+                                        the fast agent small changes build
+                                        on, with no plan
+  toolroll config set <plan|build> [--tier light|strong] --also
+      --provider <p> --model <m> [--repo <path>] --as <you> --token <t>
+                                        another provider's agent on the same
+                                        tier; each task runs the one whose
+                                        plan has more room
+  toolroll config clear <plan|build> [--tier light|strong] --also
+      [--provider <p>] [--repo <path>] --as <you> --token <t>
   toolroll config clear <phase> [--repo <path>] --as <you> --token <t>
 
   toolroll setup show --repo <path>  what a fresh checkout runs first
@@ -632,7 +646,7 @@ export const OPERATE_VALUE_FLAGS = new Set([
     "provider", "plan-model", "plan-provider", "public-url", "editor",
     "command", "timeout-seconds", "setup-digest", "stop-grace", "title", "name", "every", "lines",
     "label", "reviewers", "limit", "role", "key-file", "weekly-usd", "daily-turns", "per-hour", "token-file", "race", "compare", "race-per-usd", "race-total-usd", "race-count", "race-agents", "budget-usd", "build-usd", "sync-max-age", "merge-method",
-    "phase", "risk", "tier", "clear-phase",
+    "phase", "risk", "tier", "clear-phase", "size", "risky",
     "run", "containment", "agent",
     // onboard: the starter flows to switch on.
     "starter",
@@ -664,6 +678,8 @@ export const OPERATE_BOOLEAN_FLAGS = new Set([
     "revoke",
     // task merge: merge without waiting for the full check (Quick or Off results).
     "anyway",
+    // config set/clear: another provider's candidate on the same tier.
+    "also",
 ]);
 export function parseOperateArgs(argv, ownValues = new Set()) {
     const positional = [];
@@ -799,6 +815,9 @@ export async function runOperate(command, argv, write, options = {}) {
     }
     // v105: a Claude turn anywhere in this command says its plan's usage windows; keep the latest.
     const dropLimitSink = pushLimitSink(reading => store.recordProviderLimits(reading, new Date()));
+    // Filed tasks are sized by the owner's own fast classifier (never in tests, the demo, or with NO_TASK_CLASSIFIER).
+    const sizer = options.filingSizer ?? (process.env["VITEST"] !== undefined || envValue(process.env, "NO_TASK_CLASSIFIER") !== undefined || store.isDemo() ? null : ownerSizer());
+    const dropSizer = sizer === null ? () => { } : installFilingSizer(sizer);
     // One `Date` per command is fine for a lookup and wrong for a pass that
     // runs an agent for half an hour: leases granted, extended, and released
     // with the same stale stamp. Injected time stays frozen — a test's clock
@@ -853,6 +872,9 @@ export async function runOperate(command, argv, write, options = {}) {
         return fail(write, json, command, "failed", describe(error), EXIT.failed);
     }
     finally {
+        // A classification still in flight (at most its five-second budget) lands before the database closes.
+        await settleSizings();
+        dropSizer();
         dropLimitSink();
         store.close();
     }
@@ -5787,8 +5809,11 @@ async function configCommand(positional, flags, context) {
             phase: one,
             strong: candidates.ok ? candidates.candidates[one].strong : null,
         }));
+        const alsoRows = [...store.listPhaseTierAlternates(INSTALLATION_SCOPE), ...(scope === INSTALLATION_SCOPE ? [] : store.listPhaseTierAlternates(scope))];
+        // A light planner from before light became build-only is never used: said, with how to clear it.
+        const unusedLight = [INSTALLATION_SCOPE, ...(scope === INSTALLATION_SCOPE ? [] : [scope])].filter(one => store.phaseTierConfig(one, "plan", "light") !== null);
         if (json) {
-            write(envelopeJson({ ok: true, command: "config show", installation, project, resolved, fallback, strong, installationStrong: store.listPhaseTierConfig(INSTALLATION_SCOPE), projectStrong: scope === INSTALLATION_SCOPE ? [] : store.listPhaseTierConfig(scope) }));
+            write(envelopeJson({ ok: true, command: "config show", installation, project, resolved, fallback, strong, installationStrong: store.listPhaseTierConfig(INSTALLATION_SCOPE), projectStrong: scope === INSTALLATION_SCOPE ? [] : store.listPhaseTierConfig(scope), installationAlso: store.listPhaseTierAlternates(INSTALLATION_SCOPE), projectAlso: scope === INSTALLATION_SCOPE ? [] : store.listPhaseTierAlternates(scope) }));
             return EXIT.ok;
         }
         write(`Effective phase agents${scope === INSTALLATION_SCOPE ? "" : ` for ${scope}`}:`);
@@ -5807,6 +5832,22 @@ async function configCommand(positional, flags, context) {
         }
         write("  set one with: toolroll config set <phase> --tier strong --provider <p> --model <m> --as <you> --token <t>");
         write("");
+        write("  light tier (small changes build on this, with no plan):");
+        const light = candidates.ok ? candidates.candidates.build.light ?? null : null;
+        write(`  ${"build".padEnd(8)} ${light === null ? "none configured — small changes keep the default above and say so" : `${light.provider} · ${light.model}  [${light.source}]`}`);
+        for (const one of unusedLight)
+            write(`  ${"plan".padEnd(8)} not used — a small change makes no plan; \`config clear plan --tier light${one === INSTALLATION_SCOPE ? "" : ` --repo ${one}`}\` removes it`);
+        write("  set one with: toolroll config set build --tier light --provider <p> --model <m> --as <you> --token <t>");
+        write("");
+        if (candidates.ok) {
+            const also = ["plan", "build"].flatMap(one => Object.entries(candidates.candidates[one].alternates ?? {}).flatMap(([tier, list]) => (list ?? []).map(spec => `  ${one.padEnd(8)} ${tier.padEnd(8)} also ${spec.provider} · ${spec.model}  [${spec.source}]`)));
+            if (also.length > 0 || alsoRows.length > 0) {
+                write("  other providers on a tier (each task runs the one whose plan has more room):");
+                for (const line of also)
+                    write(line);
+                write("");
+            }
+        }
         write("  repair note: the repair PROVIDER always inherits the build it mends — only its model is configurable.");
         if (fallback.length > 0) {
             write("");
@@ -6046,11 +6087,57 @@ async function configCommand(positional, flags, context) {
     // reaches for when risk, quality, evidence, or publication demand it.
     // Authenticated and audited exactly like the routine row; existing
     // approvals are untouched — a sealed route never re-resolves.
+    // The LIGHT tier (v2): the fast agent a small change builds on.
     const tierGiven = text(flags, "tier");
-    if (tierGiven !== undefined && tierGiven !== "strong") {
-        return fail(write, json, `config ${action}`, "usage", "--tier is `strong` — the routine tier is the plain phase row", EXIT.usage);
+    if (tierGiven !== undefined && tierGiven !== "strong" && tierGiven !== "light") {
+        return fail(write, json, `config ${action}`, "usage", "--tier is `light` or `strong` — the routine tier is the plain phase row", EXIT.usage);
+    }
+    // A light planner would never run (a small change makes no plan): refused rather than kept and ignored.
+    // Clearing one left from before stays possible.
+    if (tierGiven === "light" && phase !== "build" && !(action === "clear" && phase === "plan" && !flag(flags, "also"))) {
+        return fail(write, json, `config ${action}`, "usage", "--tier light is for build only — a small change makes no plan, and repairs resume the builder's session", EXIT.usage);
+    }
+    // Another provider's candidate on the same tier (`--also`): one per provider, and at filing the one whose plan
+    // has more room runs.
+    if (flag(flags, "also")) {
+        if (phase !== "plan" && phase !== "build") {
+            return fail(write, json, `config ${action}`, "usage", "--also is for plan or build — repairs follow the build's provider", EXIT.usage);
+        }
+        const tier = (tierGiven ?? "routine");
+        const alsoProvider = text(flags, "provider");
+        if (alsoProvider !== undefined && !isProviderId(alsoProvider)) {
+            return fail(write, json, `config ${action}`, "usage", `--provider is one of ${PROVIDER_IDS.join(", ")}`, EXIT.usage);
+        }
+        if (action === "clear") {
+            const removed = store.clearPhaseTierAlternates(scope, phase, tier, alsoProvider ?? null);
+            return succeed(write, json, "config clear", { scope, phase, tier, also: true, provider: alsoProvider ?? null, cleared: removed }, () => [
+                removed > 0 ? `Removed ${removed} other-provider ${tier} ${phase} agent${removed === 1 ? "" : "s"} at ${scope}; sealed routes are untouched.` : `No other-provider ${tier} ${phase} agent${alsoProvider === undefined ? "" : ` on ${alsoProvider}`} was configured at ${scope}.`,
+            ]);
+        }
+        const alsoModel = text(flags, "model");
+        if (alsoProvider === undefined || alsoModel === undefined) {
+            return fail(write, json, "config set", "usage", "--also names an exact --provider and --model — approvals bind exact routing", EXIT.usage);
+        }
+        const alsoValid = validateSpec({ provider: alsoProvider, model: alsoModel });
+        if (!alsoValid.ok)
+            return fail(write, json, "config set", "invalid", alsoValid.problem, EXIT.usage);
+        store.setPhaseTierAlternate(scope, phase, tier, alsoProvider, alsoModel, acting.name, clock());
+        const resolvedNow = resolveRouteCandidates(store, scope === INSTALLATION_SCOPE ? null : scope);
+        const own = !resolvedNow.ok ? null : tier === "routine" ? resolvedNow.candidates[phase].routine : tier === "light" ? resolvedNow.candidates[phase].light ?? null : resolvedNow.candidates[phase].strong;
+        return succeed(write, json, "config set", { scope, phase, tier, also: true, provider: alsoProvider, model: alsoModel }, () => [
+            `${tier} ${phase} at ${scope === INSTALLATION_SCOPE ? "the installation" : scope} can also run ${alsoProvider} · ${alsoModel}, set by ${acting.name}.`,
+            own !== null && own.provider === alsoProvider && !own.source.includes("also")
+                ? `  ! the ${tier} ${phase} agent already runs ${alsoProvider} (${own.model}) — this one is not used while it does.`
+                : "  tasks filed from now on run on whichever provider's plan has more room; sealed routes are untouched.",
+        ]);
     }
     if (action === "clear") {
+        if (tierGiven === "light") {
+            const clearedLight = store.clearPhaseTierConfig(scope, phase, "light");
+            return succeed(write, json, "config clear", { scope, phase, tier: "light", cleared: clearedLight }, () => [
+                clearedLight ? `Cleared the light ${phase} agent at ${scope} — small changes keep the default and say so; sealed routes are untouched.` : `No light ${phase} agent was configured at ${scope}.`,
+            ]);
+        }
         if (tierGiven === "strong") {
             const clearedStrong = store.clearPhaseTierConfig(scope, phase, "strong");
             return succeed(write, json, "config clear", { scope, phase, tier: "strong", cleared: clearedStrong }, () => [
@@ -6071,6 +6158,16 @@ async function configCommand(positional, flags, context) {
     if (!valid.ok) {
         return fail(write, json, "config set", "invalid", valid.problem, EXIT.usage);
     }
+    if (tierGiven === "light") {
+        if (modelGiven === null) {
+            return fail(write, json, "config set", "usage", `a light ${phase} agent names an exact --model — approvals bind exact routing`, EXIT.usage);
+        }
+        store.setPhaseTierConfig(scope, phase, "light", providerGiven, modelGiven, acting.name, clock());
+        return succeed(write, json, "config set", { scope, phase, tier: "light", provider: providerGiven, model: modelGiven }, () => [
+            `light ${phase} at ${scope === INSTALLATION_SCOPE ? "the installation" : scope} is ${providerGiven} · ${modelGiven}, set by ${acting.name}.`,
+            "  small changes filed from now on build on it with no plan; sealed routes are untouched.",
+        ]);
+    }
     if (tierGiven === "strong") {
         if (phase === "review" && providerGiven === "gemini") {
             return fail(write, json, "config set", "invalid", "gemini has no isolation posture for the review phase yet — name claude or codex as the strong reviewer", EXIT.usage);
@@ -11348,7 +11445,9 @@ async function routeTaskCommand(positional, flags, context) {
     const providerGiven = text(flags, "provider");
     const modelGiven = text(flags, "model");
     const digestGiven = text(flags, "digest");
-    const editing = riskGiven !== undefined || phaseGiven !== undefined || clearGiven !== undefined;
+    const sizeGiven = text(flags, "size");
+    const riskyGiven = text(flags, "risky");
+    const editing = riskGiven !== undefined || phaseGiven !== undefined || clearGiven !== undefined || sizeGiven !== undefined || riskyGiven !== undefined;
     const show = () => {
         const scope = store.getScope(id);
         const current = store.refFor(BUILT_IN, id);
@@ -11356,7 +11455,7 @@ async function routeTaskCommand(positional, flags, context) {
         const readiness = store.readinessLookupFor(ref.repo, ref.assignedRunner, clock());
         const view = taskRouteView(routed, readiness);
         const projection = routed !== null && routed.kind === "route" ? projectRoute(routed.route, readiness) : null;
-        return succeed(write, json, "task route", { id, risk: current.riskLevel ?? scope?.riskLevel ?? "routine", riskConsequence: riskConsequence(current.riskLevel ?? scope?.riskLevel ?? "routine"), source: routed !== null && routed.kind === "route" ? routed.source : routed?.kind ?? null, route: view, overrides: current.routeOverrides ?? [], digest: scope?.digest ?? null, approval: approvalOf(scope) }, () => routed === null
+        return succeed(write, json, "task route", { id, risk: current.riskLevel ?? scope?.riskLevel ?? "routine", riskConsequence: riskConsequence(current.riskLevel ?? scope?.riskLevel ?? "routine"), size: current.sizing ?? null, source: routed !== null && routed.kind === "route" ? routed.source : routed?.kind ?? null, route: view, overrides: current.routeOverrides ?? [], digest: scope?.digest ?? null, approval: approvalOf(scope) }, () => routed === null
             ? [`${id}: no route can be recommended yet — ${scope === null ? "place the task in a repository and file a scope" : scope.unresolvedReason ?? "the phase configuration cannot resolve"}`]
             : [
                 ...(projection === null
@@ -11393,6 +11492,17 @@ async function routeTaskCommand(positional, flags, context) {
     if (riskGiven !== undefined && !isRiskLevel(riskGiven)) {
         return fail(write, json, "task route", "usage", `--risk is one of ${RISK_LEVELS.join(", ")}`, EXIT.usage);
     }
+    if (sizeGiven !== undefined && !isTaskSize(sizeGiven)) {
+        return fail(write, json, "task route", "usage", `--size is one of ${TASK_SIZES.join(", ")}`, EXIT.usage);
+    }
+    if (riskyGiven !== undefined && riskyGiven !== "yes" && riskyGiven !== "no") {
+        return fail(write, json, "task route", "usage", "--risky is yes or no", EXIT.usage);
+    }
+    // A person's size outranks the classifier's; an unnamed half keeps what the task has.
+    const sizeEdit = sizeGiven === undefined && riskyGiven === undefined ? undefined : {
+        size: sizeGiven ?? ref.sizing?.size ?? "medium",
+        risky: riskyGiven === undefined ? ref.sizing?.risky ?? false : riskyGiven === "yes",
+    };
     if (phaseGiven !== undefined && clearGiven !== undefined) {
         return fail(write, json, "task route", "usage", "say --phase … --provider … --model … OR --clear-phase …, not both", EXIT.usage);
     }
@@ -11420,6 +11530,7 @@ async function routeTaskCommand(positional, flags, context) {
             return authenticated.ok ? { ok: true } : { ok: false, reason: authenticated.reason };
         },
         ...(riskGiven === undefined ? {} : { risk: riskGiven }),
+        ...(sizeEdit === undefined ? {} : { size: sizeEdit }),
         ...(phase === undefined
             ? {}
             : { override: phaseGiven !== undefined ? { phase: phase, provider: providerGiven, model: modelGiven } : { phase: phase, clear: true } }),
@@ -12215,11 +12326,14 @@ function spendCommand(flags, context) {
     // v105: subscription work is $0; what binds it is its plan's windows, as the provider last said.
     const limits = context.store.providerLimits();
     const windows = limitsView(limits, [], { project: repo => basename(repo), teammate: id => String(id) }, context.clock())?.tiles ?? [];
-    return succeed(context.write, context.json, command, { month: month.name, totalMicrousd: total, unpriced, items: items.length, budgets, limits }, () => [
+    // Sized routing: each tier's tasks, time to a result and plan use, and what the tiers saved.
+    const tiers = tierReport(context.store.handle, month.from, month.to, items);
+    return succeed(context.write, context.json, command, { month: month.name, totalMicrousd: total, unpriced, items: items.length, budgets, limits, tiers: { rows: tiers.rows, saved: tiers.saved } }, () => [
         `${month.name}: ${spendUsd(total)} (${items.length} pieces of work${unpriced > 0 ? `, ${unpriced} unpriced` : ""}; subscription work is $0)`,
         ...windows.map(tile => `  ${`${tile.name} ${tile.window}`.padEnd(24)} ${tile.value}% · ${tile.detail}`),
         ...[...byProject.entries()].sort((a, b) => b[1] - a[1]).slice(0, 10).map(([repo, microusd]) => `  ${basename(repo).padEnd(24)} ${spendUsd(microusd)}`),
         ...budgets.map(one => `  budget ${budgetLabel(one, names.get(Number(one.key))).replace(/'s$/, "").padEnd(24)} ${spendUsd(one.spentMicrousd)} of ${spendUsd(one.limitMicrousd)} (${one.percent}%)${one.hardStop ? "" : " alerts only"}`),
+        ...tierLines(tiers, spendUsd),
     ]);
 }
 /** `backup now | list` (sprint 8): back the database up now, or list backups and how the latest ones went. */

package/dist/phase-routing.d.ts

@@ -56,11 +56,16 @@ export declare const MODEL_ID_SHAPE: RegExp;
 /** The same exactness for callers outside this policy (the profile
  * rehydrator): one shape, one definition. */
 export declare function exactModelId(v: unknown): v is string;
-export declare const ROUTE_VERSION = 1;
+/** v2 adds the task's size (small / medium / large, risky or not), the
+ * light tier, and plan headroom. A v1 route — sealed before sizing — still
+ * reads back exactly and keeps its own digest domain. */
+export declare const ROUTE_VERSION = 2;
+export type RouteVersion = 1 | 2;
 /** The durable route ERA a scope row carries once it was filed under this
  * policy: NULL on a row proven to predate v47 (legacy — the sealed profile
  * alone governs), this value on every row filed since. A row with an era
- * and no readable route is corrupt and fails closed. */
+ * and no readable route is corrupt and fails closed. The era marks a ROUTED
+ * row; which route version it holds rides in the snapshot itself. */
 export declare const ROUTE_ERA = 1;
 export declare const PHASES: readonly Phase[];
 /** The review leg remains readable in signed history but is no longer scheduled. */
@@ -68,6 +73,25 @@ export declare const ACTIVE_PHASES: readonly Phase[];
 export type RiskLevel = "routine" | "elevated" | "high";
 export declare const RISK_LEVELS: readonly RiskLevel[];
 export declare function isRiskLevel(value: unknown): value is RiskLevel;
+/** How big a change the task is, sized once at filing (by the classifier,
+ * by the description when it cannot answer, or by a person). */
+export type TaskSize = "small" | "medium" | "large";
+export declare const TASK_SIZES: readonly TaskSize[];
+export type SizeSource = "classifier" | "heuristic" | "person";
+export type TaskSizing = {
+    size: TaskSize;
+    risky: boolean;
+    source: SizeSource;
+    reason: string;
+};
+export declare function isTaskSize(value: unknown): value is TaskSize;
+/** Whether a task makes no plan: a small change that is not risky, at
+ * routine risk. Elevated or high risk always plans, whatever the size. */
+export declare function makesNoPlan(size: TaskSizing | null | undefined, risk: RiskLevel): boolean;
+/** Where a size came from, in words. */
+export declare function sizeSourceWords(source: SizeSource): string;
+/** Strict read of a stored sizing: exact keys, known words, bounded reason. */
+export declare function parseSizing(raw: unknown): TaskSizing | null;
 export declare function riskTitle(risk: RiskLevel): string;
 /**
  * What declaring each risk level DOES, in one plain sentence — derived
@@ -95,7 +119,7 @@ export type ReadinessObservation = {
     observedAt: string;
     runner: string;
 };
-export type CandidateTier = "routine" | "strong";
+export type CandidateTier = "light" | "routine" | "strong";
 /** An exact agent: provider and model id, both required. */
 export type ExactSpec = {
     provider: ProviderId;
@@ -106,10 +130,21 @@ export type RouteCandidate = ExactSpec & {
     source: string;
 };
 export type PhaseCandidates = {
+    /** The operator's named LIGHT (fast) builder (`config set build --tier
+     * light …`), or null/absent when none is configured. A small change
+     * builds on it. Never inferred; the plan phase has none (a small change
+     * makes no plan). */
+    light?: RouteCandidate | null;
     routine: RouteCandidate;
     /** The operator's named strong agent for this phase, or null when none
      * is configured. Never inferred. */
     strong: RouteCandidate | null;
+    /** v2: a tier may hold one more candidate per OTHER provider (`config
+     * set <phase> [--tier …] --also --provider … --model …`) — e.g. a
+     * routine builder on claude and on codex. At filing the one whose
+     * provider has more plan room runs. Each list holds providers other
+     * than its tier's own candidate, at most one each. */
+    alternates?: Partial<Record<CandidateTier, readonly RouteCandidate[]>>;
 };
 /** The repair phase's candidates: with no repair row configured the
  * routine candidate is null and the leg INHERITS the build leg's exact
@@ -138,6 +173,30 @@ export type RouteEvidenceKind = "check" | "screenshot" | "changed-path" | "manua
  * grant at all, a grant whose merges wait for a human (notify), or a live
  * mode that merges by itself (automerge). */
 export type PublicationAuthority = "none" | "notify" | "automerge";
+/** How much of one provider's plan is used, as it last said: the 5-hour
+ * window and the weekly window, in percent; null when unknown. */
+export type ProviderRoom = {
+    provider: ProviderId;
+    fiveHour: number | null;
+    weekly: number | null;
+};
+/** Above these a provider has no headroom: even a candidate one tier
+ * stronger on another provider takes the phase. Below them, a tier's
+ * candidates on different providers still go to the one with more room. */
+export declare const HEADROOM_FIVE_HOUR_LIMIT = 80;
+export declare const HEADROOM_WEEKLY_LIMIT = 90;
+/** The latest plan-window readings as headroom: a window whose reset time
+ * has passed counts as empty; a reading older than its own window is
+ * unknown. Weekly is the plan-wide week (`seven_day`), else the fullest
+ * model-specific week. */
+export declare function headroomFrom(limits: readonly {
+    provider: string;
+    window: string;
+    usedPercent: number;
+    windowMinutes: number | null;
+    resetsAt: string | null;
+    observedAt: string;
+}[], now: Date): ProviderRoom[];
 export type RouteInput = {
     risk: RiskLevel;
     qualityMode: QualityMode;
@@ -153,6 +212,13 @@ export type RouteInput = {
         build?: ExactSpec | null;
         repair?: ExactSpec | null;
     };
+    /** How big the change is (v2): small builds on the light tier with no
+     * plan; large or risky plans and builds on the strong tier. */
+    size?: TaskSizing | null;
+    /** Each provider's plan headroom at filing (v2): when a tier has
+     * candidates on more than one provider, the one with more room runs; a
+     * provider past its limits gives way even to a stronger tier. */
+    headroom?: readonly ProviderRoom[];
 };
 export type RouteLeg = {
     phase: Phase;
@@ -178,7 +244,7 @@ export type RouteLeg = {
     problem: string | null;
 };
 export type PhaseRoute = {
-    version: typeof ROUTE_VERSION;
+    version: RouteVersion;
     risk: RiskLevel;
     qualityMode: QualityMode;
     publication: PublicationAuthority;
@@ -192,6 +258,9 @@ export type PhaseRoute = {
     demands: string[];
     legs: RouteLeg[];
     overrides: RouteOverride[];
+    /** The task's size as it was routed (v2); null on a v1 route or an
+     * unsized task. */
+    size: TaskSizing | null;
 };
 export declare function specWords(spec: {
     provider: string;
@@ -259,9 +328,18 @@ export type RouteProjection = {
     halted: boolean;
     /** Every stated leg problem, phase-prefixed. */
     problems: string[];
+    /** The size the route was made for (v2), or null. */
+    size: TaskSizing | null;
+    /** The plain line an approval card leads with — "Small change: fast
+     * model, no plan" — or null on an unsized route. */
+    sizeWords: string | null;
+    /** Why it was sized so, and by whom, or null. */
+    sizeReason: string | null;
 };
 /** What actually runs: stronger agents only when a leg draws from one. */
 export declare function postureWords(route: Pick<PhaseRoute, "legs">): string;
+/** The size line, plainly: what the size does to this route. */
+export declare function sizeWords(route: Pick<PhaseRoute, "legs" | "size" | "risk">): string | null;
 export declare function readinessWords(state: ReadinessState, reason: string | null): string;
 export declare function chosenWords(leg: Pick<RouteLeg, "chosen" | "tier">): string;
 /**
@@ -270,7 +348,10 @@ export declare function chosenWords(leg: Pick<RouteLeg, "chosen" | "tier">): str
  * plans, builds, and repairs; claude · opus reviews" — with the posture
  * said honestly (stronger agents only when one is actually selected).
  */
-export declare function agentsSummary(route: Pick<PhaseRoute, "legs">): string;
+export declare function agentsSummary(route: Pick<PhaseRoute, "legs"> & {
+    size?: TaskSizing | null;
+    risk?: RiskLevel;
+}): string;
 export declare function legLine(leg: RouteLegProjection): string;
 /** The one projection CLI, task page, and chat all render from. */
 export declare function projectRoute(route: PhaseRoute, readiness: ReadinessLookup): RouteProjection;