@getpipher/armory-fleet 0.9.4 → 0.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpipher/armory-fleet",
-  "version": "0.9.4",
+  "version": "0.10.1",
   "private": false,
   "description": "The armory suite's subagent orchestrator for the pi coding agent — a cross-harness, superpowers-native fleet where every agent is armory-native from birth.",
   "license": "MIT",

package/src/engine/run-registry.ts

@@ -23,6 +23,12 @@ export interface RunRecord {
   forkedFrom?: string;
   /** SPEC-5b-2: cumulative real tokens (input+output+cacheRead+cacheWrite) — live, updated on each message_end. */
   tokenTotal?: number;
+  /** SPEC-6-1: cumulative $ (usage.cost.total) — live, updated on each message_end. */
+  costTotal?: number;
+  /** SPEC-6-1: latest context tokens (calcContextTokens(usage)) — live snapshot. */
+  contextTokens?: number;
+  /** SPEC-6-1: the tier name this run used (for Tiers-view "used by" + per-tier spend). */
+  tier?: string;
   /** SPEC-5b-4: live session handle while status === "running"; cleared by finishRun.
    *  Transient, in-memory only — never written to RunLog (the journal append constructs
    *  a plain object, not RunRecord). */

package/src/engine/spawnSubagent.ts

@@ -9,9 +9,16 @@ import { createTurnBudget, DEFAULT_MAX_TURNS } from "./turn-budget.ts";
 import type { SingleSlotLock } from "./concurrency-lock.ts";
 import type { RunLog } from "../runtime/run-log.ts";
 import { buildToolEvent } from "../runtime/run-log.ts";
+import { resolveAgentModel, type ModelRegistryLike } from "../tiers/resolve.ts";
+import { TierRegistry } from "../tiers/tier-registry.ts";
 
 const PI_DEFAULT_TOOLS = ["read", "bash", "edit", "write"];
 
+/** SPEC-6-1: derive context-token count from a usage object. Prefer totalTokens; fall back to sum. */
+function calcContextTokens(u: { totalTokens?: number; input?: number; output?: number; cacheRead?: number; cacheWrite?: number }): number {
+  return u.totalTokens || ((u.input ?? 0) + (u.output ?? 0) + (u.cacheRead ?? 0) + (u.cacheWrite ?? 0));
+}
+
 /** No-op ports used when a caller omits them (e.g. SPEC-1 unit tests). Production (index.ts) passes real ports. */
 const NOOP_MEMORY_PORT: MemoryHydratePort = { renderScopes: () => "" };
 const NOOP_VISION_PORT: VisionPort = {
@@ -123,6 +130,10 @@ export interface SpawnOptions {
   resumeLink?: string;
   /** SPEC-5b-1: when set, the new run is a fork of this prior runId (written to run:ended + RunRecord.forkedFrom). */
   forkLink?: string;
+  /** SPEC-6-1: tier registry for model-tier resolution. Optional — existing callers without it use agent.model/parent fallback. */
+  tierRegistry?: TierRegistry;
+  /** SPEC-6-1: model catalog for contextFloor filtering. Optional — absent means no catalog filtering. */
+  modelRegistry?: ModelRegistryLike;
 }
 
 export interface SpawnResult {
@@ -134,6 +145,10 @@ export interface SpawnResult {
   model: string;
   durationMs: number;
   tokenTotal: number;
+  /** SPEC-6-1: cumulative $ (usage.cost.total) for this run. */
+  costTotal?: number;
+  /** SPEC-6-1: final context tokens (calcContextTokens of the last usage). */
+  contextTokens?: number;
   error?: string;
 }
 
@@ -173,8 +188,18 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
     // skillsOverride (buildChildLoader reads agent.skills) loads the phase's bundle, not the agent's.
     const childAgent = opts.skillsOverride ? { ...agentDef, skills: opts.skillsOverride } : agentDef;
 
-    // resolve model
-    const model = opts.model ?? agentDef.model ?? `${opts.parentModel.provider}/${opts.parentModel.id}`;
+    // SPEC-6-1: resolve model via tier registry (Q4 precedence + Q5 contextFloor/catalog filter).
+    const resolved = resolveAgentModel(
+      agentDef, opts.model, opts.parentModel,
+      opts.tierRegistry ?? new TierRegistry({ tiers: [], agents: new Map() }),
+      opts.modelRegistry ?? { find: () => undefined },
+    );
+    if ("error" in resolved) {
+      return fail(runId, startedAt, resolved.error, opts.agent);
+    }
+    const model = resolved.model;
+    const tier = resolved.tier;
+    const candidates = resolved.candidates ?? [model];
 
     // child tools pass through UNFILTERED — the single-writer `todo`-exclusion is enforced
     // downstream by the child factory's `excludeTools: ["todo"]` (SPEC-2 §9.1 hardening).
@@ -186,6 +211,7 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
     opts.runRegistry.add({
       runId, agent: agentDef.name, model, task: opts.task, track,
       todoId: null, status: "running", startedAt,
+      tier: tier?.name, costTotal: 0, contextTokens: 0,
     });
     try {
       opts.runLog?.append(runId, { type: "run:meta", runId, agent: agentDef.name, model, task: opts.task, startedAt, track, todoId: null });
@@ -206,19 +232,30 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
       return await finishRun(opts, runId, startedAt, "failed", "", todoId, priorStatus, (e as Error).message, agentDef.name, model);
     }
 
-    // spawn child
-    const { session } = await backend.factory.create({
-      cwd: opts.parentCwd,
-      model,
-      thinkingLevel: childAgent.thinkingLevel,
-      tools,
-      rolePrompt: childAgent.rolePrompt,
-      skills: childAgent.skills ?? [],
-      task: opts.task,
-      agent: childAgent,
-      memoryPort,
-      visionPort,
-    });
+    // SPEC-6-1: fallback retry loop — try candidates[0], on rejection retry candidates[1], etc.
+    let session: ChildSession | undefined;
+    let lastErr: Error | undefined;
+    for (const cand of candidates) {
+      try {
+        const result = await backend.factory.create({
+          cwd: opts.parentCwd,
+          model: cand,
+          thinkingLevel: childAgent.thinkingLevel,
+          tools,
+          rolePrompt: childAgent.rolePrompt,
+          skills: childAgent.skills ?? [],
+          task: opts.task,
+          agent: childAgent,
+          memoryPort,
+          visionPort,
+        });
+        session = result.session;
+        break;
+      } catch (e) { lastErr = e as Error; }
+    }
+    if (!session) {
+      return await finishRun(opts, runId, startedAt, "failed", "", todoId, priorStatus, `backend create failed: ${lastErr?.message ?? "unknown"}`, agentDef.name, model, 0, 0, 0);
+    }
 
     // SPEC-5b-4: retain a narrow live-session handle on the run record so the panel can
     // steer/abort mid-flight. Wrap abort so the local `aborted` flag is set when the panel
@@ -232,6 +269,8 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
     const budget = createTurnBudget(maxTurns);
     let finalText = "";
     let tokenTotal = 0;
+    let costTotal = 0;
+    let contextTokens = 0;
     let turnIdx = -1;
 
     const onSignalAbort = (): void => { aborted = true; void session.abort(); };
@@ -255,11 +294,20 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
         const turnTokens = (u?.input ?? 0) + (u?.output ?? 0) + (u?.cacheRead ?? 0) + (u?.cacheWrite ?? 0);
         if (turnTokens > 0) {
           tokenTotal += turnTokens;
-          opts.runRegistry.update(runId, { tokenTotal });
         }
+        // SPEC-6-1: accumulate cost + context tokens.
+        const cost = u?.cost?.total ?? 0;
+        costTotal += cost;
+        contextTokens = calcContextTokens(u ?? {});
+        opts.runRegistry.update(runId, { costTotal, contextTokens, tokenTotal });
         try {
-          opts.runLog?.append(runId, { type: "message", role: "assistant", text, usage: { total: turnTokens, input: u?.input, output: u?.output, cacheRead: u?.cacheRead, cacheWrite: u?.cacheWrite }, turnIndex: turnIdx });
+          opts.runLog?.append(runId, { type: "message", role: "assistant", text, usage: { total: turnTokens, input: u?.input, output: u?.output, cacheRead: u?.cacheRead, cacheWrite: u?.cacheWrite, cost: u?.cost }, turnIndex: turnIdx });
         } catch { /* best-effort */ }
+        // SPEC-6-1: cap abort — if costTotal exceeds tier.costCap, abort + flag budget_exceeded.
+        if (tier?.costCap && costTotal > tier.costCap) {
+          aborted = true;
+          void session.abort();
+        }
       } else if (e.type === "tool_execution_end") {
         try {
           opts.runLog?.append(runId, buildToolEvent((e as any).toolName, (e as any).args, (e as any).result, (e as any).isError ?? false, turnIdx));
@@ -283,7 +331,7 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
     let error: string | undefined;
     if (aborted) {
       status = "aborted";
-      error = "aborted by user";
+      error = tier?.costCap && costTotal > tier.costCap ? `budget_exceeded (cost $${costTotal.toFixed(4)} > cap $${tier.costCap})` : "aborted by user";
     } else if (budget.count() >= maxTurns) {
       status = "failed";
       error = `hit turn budget (${maxTurns}) mid-task; partial result: ${finalText.slice(0, 200)}`;
@@ -294,7 +342,7 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
       status = "completed";
     }
 
-    return await finishRun(opts, runId, startedAt, status, finalText, todoId, priorStatus, error, agentDef.name, model, tokenTotal);
+    return await finishRun(opts, runId, startedAt, status, finalText, todoId, priorStatus, error, agentDef.name, model, tokenTotal, costTotal, contextTokens);
   } finally {
     opts.lock.release();
   }
@@ -310,18 +358,19 @@ function fail(runId: string, startedAt: number, message: string, agent: string):
 async function finishRun(
   opts: SpawnOptions, runId: string, startedAt: number,
   status: FleetRunStatus, finalText: string, todoId: string | null, priorStatus: string | undefined,
-  error: string | undefined, agentName: string, model: string, tokenTotal = 0,
+  error: string | undefined, agentName: string, model: string, tokenTotal = 0, costTotal = 0, contextTokens = 0,
 ): Promise<SpawnResult> {
   const endedAt = Date.now();
   opts.runRegistry.update(runId, {
     status, endedAt, resultSummary: finalText.slice(0, 120),
     resumedFrom: opts.resumeLink, forkedFrom: opts.forkLink,
     session: undefined,   // SPEC-5b-4: clear the live handle (invariant: session ⟺ running)
+    costTotal, contextTokens,   // SPEC-6-1: final cost/context on the terminal record
   });
   try {
     opts.runLog?.append(runId, {
       type: "run:ended", runId, status, endedAt,
-      resultSummary: finalText.slice(0, 120), tokenTotal,
+      resultSummary: finalText.slice(0, 120), tokenTotal, costTotal, contextTokens,
       resumedFrom: opts.resumeLink, forkedFrom: opts.forkLink,
     });
   } catch { /* best-effort: journal is the index, not the product */ }
@@ -340,6 +389,6 @@ async function finishRun(
   }
   return {
     status, finalText, runId, todoId, agent: agentName, model,
-    durationMs: endedAt - startedAt, tokenTotal, error,
+    durationMs: endedAt - startedAt, tokenTotal, costTotal, contextTokens, error,
   };
 }

package/src/index.ts

@@ -43,6 +43,10 @@ import { Scheduler } from "./scheduling/scheduler.ts";
 import { createFleetResultsTool } from "./tools/fleet-results.ts";
 import { BgRunsStore } from "./panel/bg-runs-store.ts";
 import { FleetWidgetController } from "./panel/fleet-widget.ts";
+import { TierRegistry, mergeTiers } from "./tiers/tier-registry.ts";
+import { BUILTIN_TIERS } from "./tiers/builtin.ts";
+import { TierStore } from "./tiers/tier-store.ts";
+import { splitModel } from "./tiers/resolve.ts";
 
 /** The package builtin agents/ dir, resolved relative to this module. */
 function builtinAgentsDir(): string {
@@ -167,6 +171,12 @@ export default async function (pi: ExtensionAPI): Promise<void> {
   deps.lifecycleDeps.registry = deps.lifecycleRegistry;
   deps.lifecycleDeps.agentRegistry = deps.registry;
 
+  // SPEC-6-1: shared model registry for contextWindow lookups (contextFloor + ctx% widget).
+  const sharedModelRegistry = new ModelRegistry(modelRuntime);
+  deps.modelRegistry = sharedModelRegistry;
+  // Builtin-only placeholder tier registry so spawn works before session_start rebuilds with merged tiers.
+  deps.tierRegistry = new TierRegistry({ tiers: BUILTIN_TIERS, agents: deps.registry });
+
   // ── SPEC-5a: operational runtime (async/bg + scheduling + worktree isolation) ──
   const fleetDir = (cwd: string) => join(cwd, ".pi", "fleet");
   const bgRuns = new BgRunsStore();
@@ -195,7 +205,8 @@ export default async function (pi: ExtensionAPI): Promise<void> {
         agent: o.agent, task: o.task, lifecycleTodoId: o.lifecycleTodoId, model: o.model,
         skillsOverride: o.skills, backendOverride: o.backend,
         registry: deps.registry, todoSync: deps.todoSync, runRegistry: deps.runRegistry, lock: bgLock,
-        backendRegistry: deps.backendRegistry, parentModel: deps.parentModel, parentCwd: opts.worktreePath, runLog: deps.runLog,  // child runs in the worktree
+        backendRegistry: deps.backendRegistry, parentModel: deps.parentModel, parentCwd: opts.worktreePath, runLog: deps.runLog,
+        tierRegistry: deps.tierRegistry, modelRegistry: deps.modelRegistry,  // SPEC-6-1
       }),
     };
     const res = await runLifecycle(task, lifecycleName, { deps: lifecycleFullDeps, mode: opts.mode, worktreePath: opts.worktreePath, baseRef: "HEAD", onCheckpoint: async (p) => p.status === "failed" ? { action: "abort" } : { action: "continue" } });
@@ -277,13 +288,34 @@ export default async function (pi: ExtensionAPI): Promise<void> {
     }
     // SPEC-5b-2: live widget (above editor). Display-only, independent
     // of the /fleet panel. getTheme is a live getter (EditorTheme gotcha). Disposed on session end.
+    const getModelContextWindow = (m: string): number | undefined => {
+      const { provider, id } = splitModel(m, deps.parentModel.provider);
+      return sharedModelRegistry.find(provider, id)?.contextWindow;
+    };
+    deps.getModelContextWindow = getModelContextWindow;
     fleetWidget = new FleetWidgetController({
       runRegistry: deps.runRegistry,
       bgRuns,
       ui: ctx.ui as never,
       getTheme: () => ctx.ui.theme,
+      getModelContextWindow,
     });
     fleetWidget.start();
+
+    // SPEC-6-1: per-session TierStore (cwd-aware project path) + real TierRegistry (builtins + global + project).
+    const tierStore = new TierStore({
+      projectPath: join(dir, "tiers.json"),
+      globalPath: join(process.env.HOME ?? "", ".pi", "agent", "fleet", "tiers.json"),
+    });
+    deps.tierStore = tierStore;
+    const reloadTiers = (): void => {
+      deps.tierRegistry = new TierRegistry({
+        tiers: mergeTiers(BUILTIN_TIERS, tierStore.read("global"), tierStore.read("project")),
+        agents: deps.registry,
+      });
+    };
+    deps.reloadTiers = reloadTiers;
+    reloadTiers();  // build the real merged registry (replaces the builtin-only placeholder)
   });
 
   pi.on("session_shutdown", () => {
@@ -348,6 +380,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
             skillsOverride: o.skills, backendOverride: o.backend,
           registry: deps.registry, todoSync: deps.todoSync, runRegistry: deps.runRegistry, lock: deps.lock,
           backendRegistry: deps.backendRegistry, parentModel: deps.parentModel, parentCwd: deps.parentCwd,
+          tierRegistry: deps.tierRegistry, modelRegistry: deps.modelRegistry,  // SPEC-6-1
         }),
       };
       const res = await runLifecycle(parsed.task, lcName, { deps: lifecycleFullDeps, mode: parsed.auto ? "auto" : "checkpointed", onCheckpoint });

package/src/panel/fleet-panel.ts

@@ -26,8 +26,11 @@ import type { TodoSyncPort } from "../todo-sync/port.ts";
 import type { LifecycleDef, LifecycleRunRecord, CheckpointDecision, PhaseRecord } from "../lifecycle/lifecycle-types.ts";
 import type { LifecycleRunDeps, CheckpointFn } from "../lifecycle/run-lifecycle.ts";
 import { runLifecycle } from "../lifecycle/run-lifecycle.ts";
+import type { TierRegistry } from "../tiers/tier-registry.ts";
+import type { TierStore } from "../tiers/tier-store.ts";
+import { buildTiersItems, setTierCostCap, setTierModels, setTierContextFloor, addTier, deleteTier } from "./tiers-items.ts";
 
-type View = "fleet" | "lifecycle" | "runs" | "agents" | "backends" | "scheduled";
+type View = "fleet" | "lifecycle" | "runs" | "agents" | "backends" | "scheduled" | "tiers";
 
 export interface FleetPanelDeps {
   registry: Map<string, AgentDef>;
@@ -47,6 +50,14 @@ export interface FleetPanelDeps {
   bgRuns?: BgRunsStore;
   /** SPEC-5b-1: durable per-run conversation log. Optional — Runs tab degrades to empty when absent. */
   runLog?: RunLog;
+  /** SPEC-6-1: tier registry for the Tiers view. Optional — panel degrades to empty list when absent. */
+  tierRegistry?: TierRegistry;
+  /** SPEC-6-1: tier store for inline edits. Optional — Tiers view action keys are no-ops when absent. */
+  tierStore?: TierStore;
+  /** SPEC-6-1: callback to rebuild the tier registry after a write. */
+  reloadTiers?: () => void;
+  /** SPEC-6-1: model contextWindow resolver for Runs-tab ctx% (Surface C). Optional — ctx% hidden when absent. */
+  getModelContextWindow?: (model: string) => number | undefined;
 }
 
 export interface FleetPanelOpts {
@@ -94,6 +105,10 @@ export class FleetPanel extends Container {
   // SPEC-5b-4: Steer inline input state (mid-run redirect; mirrors resumeMode/resumeInput).
   private steerInput: Input | null = null;
   private steerMode = false;
+  // SPEC-6-1: Tiers view inline-edit state (mirrors steerInput/steerMode).
+  private tiersInput: Input | null = null;
+  private tiersEditPhase: "models" | "costCap" | "contextFloor" | "add" | null = null;
+  private tiersScope: "project" | "global" = "project";
   // SPEC-5b-3: full-message overlay (second level over the 5b-1 timeline) + stored SelectList refs
   // so handleInput can forward keys to the active overlay (Container/TUI routes input only to the
   // focused component = this panel; children receive keys only if we forward them).
@@ -133,11 +148,13 @@ export class FleetPanel extends Container {
         : this.view === "lifecycle"
           ? [...this.deps.lifecycleRuns.values()].map((l: LifecycleRunRecord) => ({ value: l.runId, label: lifecycleRow(l) }))
           : this.view === "runs"
-            ? buildRunsIndex(this.deps.runLog?.dir ?? "").map((r: RunMeta) => ({ value: r.runId, label: runsRow(r) }))
+            ? buildRunsIndex(this.deps.runLog?.dir ?? "").map((r: RunMeta) => ({ value: r.runId, label: runsRow(r, this.deps.getModelContextWindow) }))
             : this.view === "agents"
               ? [...this.deps.registry.values()].map((a: AgentDef) => ({ value: a.name, label: agentsRow(a) }))
             : this.view === "scheduled"
               ? (this.deps.scheduler?.list() ?? []).map((s: Schedule) => ({ value: s.id, label: scheduleRow(s) }))
+            : this.view === "tiers"
+              ? (this.deps.tierRegistry ? buildTiersItems({ tierRegistry: this.deps.tierRegistry, runRegistry: this.deps.runRegistry }) : [])
               : this.deps.backendRegistry.list().map((b: Backend) => ({ value: b.id, label: backendsRow(b) }));
     const fresh = new SelectList(items, 12, {
       selectedPrefix: (s: string) => this.theme.fg("accent", s),
@@ -176,7 +193,7 @@ export class FleetPanel extends Container {
     this.children.length = 0;
     this.children.push(...keep);
     const accent = (s: string): string => this.theme.fg("accent", s);
-    const tabs = (["fleet", "lifecycle", "runs", "agents", "backends", "scheduled"] as View[])
+    const tabs = (["fleet", "lifecycle", "runs", "agents", "backends", "scheduled", "tiers"] as View[])
       .map((v) => (v === this.view ? this.theme.fg("accent", this.theme.bold(`[${v}]`)) : this.theme.fg("dim", v)))
       .join("  ");
     this.addChild(new Text(accent(this.theme.bold("  FLEET")) + "  " + tabs, 0, 0));
@@ -297,6 +314,17 @@ export class FleetPanel extends Container {
       this.addChild(new Text(this.theme.fg("accent", "  steer> "), 0, 0));
       this.addChild(this.steerInput);
       this.addChild(new Text(this.theme.fg("dim", "  enter submit • esc cancel"), 0, 0));
+    } else if (this.tiersEditPhase && this.tiersInput) {
+      // SPEC-6-1: Tiers tab — inline edit input.
+      const sel = this.list.getSelectedItem();
+      const name = sel?.value ?? "";
+      const prompt = this.tiersEditPhase === "add" ? "  new tier name> "
+        : this.tiersEditPhase === "models" ? `  models for ${name}> `
+        : this.tiersEditPhase === "costCap" ? `  costCap for ${name}> `
+        : `  contextFloor for ${name}> `;
+      this.addChild(new Text(this.theme.fg("accent", prompt), 0, 0));
+      this.addChild(this.tiersInput);
+      this.addChild(new Text(this.theme.fg("dim", "  enter submit • esc cancel"), 0, 0));
     } else if (this.resumeMode && this.resumeInput) {
       // SPEC-5b-1: Runs tab — resume follow-up input.
       this.addChild(new Text(this.theme.fg("accent", "  follow-up> "), 0, 0));
@@ -344,7 +372,9 @@ export class FleetPanel extends Container {
                   : this.view === "agents"
                   ? "  r:Run  e:Edit  i:Info  d:Reload  tab:Backends  q:Quit"
                   : this.view === "scheduled"
-                    ? "  a:Add  p:Pause/resume  d:Delete  i:Info  tab:Fleet  q:Quit"
+                    ? "  a:Add  p:Pause/resume  d:Delete  i:Info  tab:Tiers  q:Quit"
+                  : this.view === "tiers"
+                    ? "  m:Models  c:costCap  f:contextFloor  a:Add  d:Delete  g:scope  tab:Fleet  q:Quit"
                     : "  r:Refresh  i:Info  tab:Fleet  q:Quit";
     this.addChild(new Text(this.theme.fg("dim", hint), 0, 0));
     this.addChild(new Spacer(1));
@@ -416,7 +446,7 @@ export class FleetPanel extends Container {
       : this.view === "lifecycle" ? "runs"
       : this.view === "runs" ? "agents"
       : this.view === "agents" ? "backends"
-      : this.view === "backends" ? "scheduled" : "fleet";
+      : this.view === "backends" ? "scheduled" : this.view === "scheduled" ? "tiers" : "fleet";
     this.selectedBackend = null;
     this.selectedLifecycle = null;
     this.selectedSchedule = null;
@@ -428,6 +458,8 @@ export class FleetPanel extends Container {
     this.messageBodyList = null;
     this.steerMode = false;       // SPEC-5b-4: drop any in-flight steer input on tab switch
     this.steerInput = null;
+    this.tiersEditPhase = null;   // SPEC-6-1: drop any in-flight tiers edit on tab switch
+    this.tiersInput = null;
     this.list = this.buildList();
     this.renderShell();
   }
@@ -469,6 +501,12 @@ export class FleetPanel extends Container {
       this.invalidate();
       return;
     }
+    if (this.tiersEditPhase && this.tiersInput) {
+      if (matchesKey(data, "escape")) { this.cancelTiersEdit(); return; }
+      this.tiersInput.handleInput(data);
+      this.invalidate();
+      return;
+    }
     if (this.resumeMode && this.resumeInput) {
       if (matchesKey(data, "escape")) { this.cancelResume(); return; }
       this.resumeInput.handleInput(data);
@@ -576,6 +614,20 @@ export class FleetPanel extends Container {
         return;
       }
     }
+    // SPEC-6-1: Tiers view — m:Models c:costCap f:contextFloor a:Add d:Delete g:scope
+    if (this.view === "tiers" && this.deps.tierStore && this.deps.tierRegistry) {
+      if (matchesKey(data, "m")) { this.startTiersEdit("models"); return; }
+      if (matchesKey(data, "c")) { this.startTiersEdit("costCap"); return; }
+      if (matchesKey(data, "f")) { this.startTiersEdit("contextFloor"); return; }
+      if (matchesKey(data, "a")) { this.startTiersEdit("add"); return; }
+      if (matchesKey(data, "d")) { this.executeTiersDelete(); return; }
+      if (matchesKey(data, "g")) {
+        this.tiersScope = this.tiersScope === "project" ? "global" : "project";
+        this.onNotify(`tiers scope: ${this.tiersScope}`, "info");
+        this.renderShell();
+        return;
+      }
+    }
     // SPEC-4: pending checkpoint keys (c/v/a)
     if (this.pendingCheckpoint && !this.lcRevising) {
       if (matchesKey(data, "c")) { this.pendingCheckpoint.resolve({ action: "continue" }); this.pendingCheckpoint = null; this.renderShell(); return; }
@@ -739,6 +791,78 @@ export class FleetPanel extends Container {
     })();
   }
 
+  // ────────────────────────────── SPEC-6-1: Tiers view inline edit ──────────────────────────────
+
+  private startTiersEdit(phase: "models" | "costCap" | "contextFloor" | "add"): void {
+    if (phase !== "add") {
+      const sel = this.list.getSelectedItem();
+      if (!sel) { this.onNotify("select a tier first", "warning"); return; }
+    }
+    this.tiersInput = new Input();
+    this.tiersInput.onSubmit = (value: string) => { void this.executeTiersEdit(value, phase); };
+    this.tiersInput.onEscape = () => this.cancelTiersEdit();
+    this.tiersEditPhase = phase;
+    this.renderShell();
+  }
+
+  private cancelTiersEdit(): void {
+    this.tiersEditPhase = null;
+    this.tiersInput = null;
+    this.renderShell();
+  }
+
+  private async executeTiersEdit(value: string, phase: "models" | "costCap" | "contextFloor" | "add"): Promise<void> {
+    const store = this.deps.tierStore!;
+    const scope = this.tiersScope;
+    const sel = this.list.getSelectedItem();
+    const name = sel?.value ?? "";
+    if (phase === "add" && !value.trim()) { this.onNotify("tier name required", "error"); return; }
+    this.tiersEditPhase = null;
+    this.tiersInput = null;
+    this.renderShell();
+    let tiers = store.read(scope);
+    try {
+      if (phase === "add") {
+        tiers = addTier(tiers, value.trim(), ["<placeholder-model>"]);
+      } else if (phase === "models") {
+        tiers = setTierModels(tiers, name, value.split(/[,\s]+/).filter(Boolean));
+      } else if (phase === "costCap") {
+        const n = Number(value);
+        if (value.trim() !== "" && Number.isNaN(n)) { this.onNotify("costCap must be a number", "error"); return; }
+        tiers = setTierCostCap(tiers, name, value.trim() === "" ? undefined : n);
+      } else {
+        const n = Number(value);
+        if (value.trim() !== "" && Number.isNaN(n)) { this.onNotify("contextFloor must be a number", "error"); return; }
+        tiers = setTierContextFloor(tiers, name, value.trim() === "" ? undefined : n);
+      }
+      store.write(scope, tiers);
+      this.deps.reloadTiers?.();
+      this.list = this.buildList();
+      this.renderShell();
+      if (phase === "add") this.onNotify(`tier '${value.trim()}' added; press m to edit models`, "info");
+    } catch (e) {
+      this.onNotify(e instanceof Error ? e.message : String(e), "error");
+      return;
+    }
+  }
+
+  private executeTiersDelete(): void {
+    const sel = this.list.getSelectedItem();
+    if (!sel) { this.onNotify("select a tier first", "warning"); return; }
+    const store = this.deps.tierStore!;
+    const scope = this.tiersScope;
+    const tiers = deleteTier(store.read(scope), sel.value);
+    try {
+      store.write(scope, tiers);
+      this.deps.reloadTiers?.();
+      this.list = this.buildList();
+      this.renderShell();
+      this.onNotify(`tier '${sel.value}' deleted`, "info");
+    } catch (e) {
+      this.onNotify(e instanceof Error ? e.message : String(e), "error");
+    }
+  }
+
   private async executeResume(prior: RunMeta, followUp: string): Promise<void> {
     this.resumeMode = false;
     this.resumeInput = null;

package/src/panel/fleet-widget.ts

@@ -39,6 +39,8 @@ export interface FleetWidgetDeps {
   now?: () => number;
   setInterval?: (fn: () => void, ms: number) => unknown;
   clearInterval?: (id: unknown) => void;
+  /** SPEC-6-1: resolve a model's context window for the ctx% widget segment. Optional — absent → no ctx%. */
+  getModelContextWindow?: (model: string) => number | undefined;
 }
 
 export class FleetWidgetController {
@@ -64,7 +66,11 @@ export class FleetWidgetController {
   }
 
   private activeRuns() {
-    const fg = this.deps.runRegistry.list().map(toWidgetRun);
+    const fg = this.deps.runRegistry.list().map((r) => {
+      const w = toWidgetRun(r);
+      w.maxContext = this.deps.getModelContextWindow?.(r.model);
+      return w;
+    });
     const bg = this.deps.bgRuns ? [...this.deps.bgRuns.values()].map(toWidgetRunFromBg) : [];
     return [...fg, ...bg];
   }

package/src/panel/rows.ts

@@ -11,6 +11,14 @@ export function fmtDuration(ms: number): string {
   return `${m}m${s % 60}s`;
 }
 
+/** Compact token count: <1K as-is, >=1K with K suffix (1 decimal under 10K, 0 decimals above).
+ *  142 → "142"; 1300 → "1.3K"; 265055 → "265K"; 2027001 → "2027K". */
+export function fmtTokens(n: number): string {
+  if (n < 1000) return `${n}`;
+  const k = n / 1000;
+  return `${k.toFixed(k < 10 ? 1 : 0)}K`;
+}
+
 const STATUS_GLYPH: Record<FleetRunStatus, string> = {
   running: "▶",
   completed: "✓",

package/src/panel/runs-rows.ts

@@ -1,26 +1,29 @@
 // src/panel/runs-rows.ts
 // SPEC-5b-1 — pure renderers for the Runs tab + per-turn timeline. Reuses the glyph
 // language (▶ ✓ ✗) so the Runs tab is visually consistent with Fleet/Lifecycle.
-import { fmtDuration } from "./rows.ts";
+import { fmtDuration, fmtTokens } from "./rows.ts";
 import type { RunMeta, MessageEvent, ToolEvent } from "../runtime/run-log.ts";
 
 const STATUS_GLYPH: Record<RunMeta["status"], string> = {
   running: "▶", completed: "✓", failed: "✗", aborted: "✗",
 };
 
-export function runsRow(r: RunMeta): string {
+export function runsRow(r: RunMeta, getModelContextWindow?: (model: string) => number | undefined): string {
   const dur = r.endedAt ? fmtDuration(r.endedAt - r.startedAt) : "—";
-  const tok = r.tokenTotal > 0 ? `  ${r.tokenTotal} tok` : "";
+  const tok = r.tokenTotal > 0 ? `  ${fmtTokens(r.tokenTotal)} tok` : "";
+  const maxCtx = getModelContextWindow?.(r.model);
+  const ctx = (r.contextTokens != null && maxCtx != null && maxCtx > 0) ? `  ${Math.round(r.contextTokens / maxCtx * 100)}%` : "";
+  const cost = r.costTotal ? `  $${r.costTotal.toFixed(4)}` : "";
   const summary = r.resultSummary ? `  "${r.resultSummary}"` : "";
   const prov = r.resumedFrom ? `  ← resumed:${r.resumedFrom}` : r.forkedFrom ? `  ← forked:${r.forkedFrom}` : "";
-  return `${STATUS_GLYPH[r.status]} ${r.runId}  ${r.agent}  ${r.status}  ${dur}${tok}${summary}${prov}`;
+  return `${STATUS_GLYPH[r.status]} ${r.runId}  ${r.agent}  ${r.status}  ${dur}${tok}${ctx}${cost}${summary}${prov}`;
 }
 
 export function runTimelineRow(e: MessageEvent | ToolEvent): string {
   const turn = Math.max(0, e.turnIndex);
   if (e.type === "message") {
     const text = e.text.length > 80 ? e.text.slice(0, 79) + "…" : e.text;
-    const tok = e.usage?.total != null ? `  ${e.usage.total} tok` : "";
+    const tok = e.usage?.total != null ? `  ${fmtTokens(e.usage.total)} tok` : "";
     return `[a] "${text}"${tok}  ·t${turn}`;
   }
   const glyph = e.isError ? "✗" : "✓";

package/src/panel/tiers-items.ts

@@ -0,0 +1,63 @@
+import type { Tier } from "../tiers/tier-registry.ts";
+import type { TierRegistry } from "../tiers/tier-registry.ts";
+import type { RunRegistry } from "../engine/run-registry.ts";
+import { renderTierRow } from "./tiers-rows.ts";
+import type { SelectItem } from "@earendil-works/pi-tui";
+
+export interface TiersItemSources {
+  tierRegistry: TierRegistry;
+  runRegistry: RunRegistry;
+}
+
+/** Build the /fleet Tiers view list items. One per tier, labeled via `renderTierRow`. */
+export function buildTiersItems(src: TiersItemSources): SelectItem[] {
+  const runs = src.runRegistry.list();
+  return src.tierRegistry.list().map((tier) => {
+    const tierRuns = runs.filter((r) => r.tier === tier.name);
+    const spend = tierRuns.reduce((sum, r) => sum + (r.costTotal ?? 0), 0);
+    const runCount = tierRuns.length;
+    const usedBy = src.tierRegistry.usedBy(tier.name);
+    return { value: tier.name, label: renderTierRow(tier, spend, usedBy, runCount) };
+  });
+}
+
+/** Set the costCap on a tier. `undefined` removes the field. Throws if tier not found. */
+export function setTierCostCap(tiers: Tier[], name: string, cap: number | undefined): Tier[] {
+  const idx = tiers.findIndex((t) => t.name === name);
+  if (idx < 0) throw new Error(`tier '${name}' not found`);
+  const updated = { ...tiers[idx]! };
+  if (cap != null) updated.costCap = cap;
+  else delete updated.costCap;
+  return [...tiers.slice(0, idx), updated, ...tiers.slice(idx + 1)];
+}
+
+/** Replace the models array on a tier. Empty array → throws. Throws if tier not found. */
+export function setTierModels(tiers: Tier[], name: string, models: string[]): Tier[] {
+  if (models.length === 0) throw new Error(`tier '${name}': models must be non-empty`);
+  const idx = tiers.findIndex((t) => t.name === name);
+  if (idx < 0) throw new Error(`tier '${name}' not found`);
+  const updated = { ...tiers[idx]!, models };
+  return [...tiers.slice(0, idx), updated, ...tiers.slice(idx + 1)];
+}
+
+/** Set/unset the contextFloor on a tier. Throws if tier not found. */
+export function setTierContextFloor(tiers: Tier[], name: string, floor: number | undefined): Tier[] {
+  const idx = tiers.findIndex((t) => t.name === name);
+  if (idx < 0) throw new Error(`tier '${name}' not found`);
+  const updated = { ...tiers[idx]! };
+  if (floor != null) updated.contextFloor = floor;
+  else delete updated.contextFloor;
+  return [...tiers.slice(0, idx), updated, ...tiers.slice(idx + 1)];
+}
+
+/** Add a new tier. Throws on duplicate name or empty models. */
+export function addTier(tiers: Tier[], name: string, models: string[]): Tier[] {
+  if (models.length === 0) throw new Error(`tier '${name}': models must be non-empty`);
+  if (tiers.some((t) => t.name === name)) throw new Error(`tier '${name}' already exists`);
+  return [...tiers, { name, models }];
+}
+
+/** Remove a tier by name. No-op if absent (no throw). */
+export function deleteTier(tiers: Tier[], name: string): Tier[] {
+  return tiers.filter((t) => t.name !== name);
+}

package/src/panel/tiers-rows.ts

@@ -0,0 +1,16 @@
+import type { Tier } from "../tiers/tier-registry.ts";
+
+function fmtFloor(n: number | undefined): string {
+  if (n == null) return "—";
+  if (n >= 1000) return `${Math.round(n / 1000)}k`;
+  return String(n);
+}
+
+/** One row per tier for the /fleet Tiers view. Pure (unit-tested). */
+export function renderTierRow(tier: Tier, spend: number, usedBy: string[], runCount: number): string {
+  const cap = tier.costCap != null ? `$${tier.costCap}` : "—";
+  const floor = fmtFloor(tier.contextFloor);
+  const spendStr = spend > 0 ? `$${spend.toFixed(4)}` : "$0.00";
+  const used = usedBy.length ? `used by: ${usedBy.join(", ")}` : "used by: —";
+  return `${tier.name}  ${tier.models.join("→")}  ${cap}  ${floor}  ${spendStr}  ${runCount} runs  ${used}`;
+}

package/src/panel/widget-rows.ts

@@ -7,7 +7,7 @@
 // mirror of this same renderer (same `widgetLine`, cap 8 vs 5), and the PRD §5 "navigable agent
 // list below editor" intent was never achievable via pi widgets (editor keeps keyboard focus).
 // `/fleet` is the navigable action surface; this one above-editor widget is the glance surface.
-import { fmtDuration } from "./rows.ts";
+import { fmtDuration, fmtTokens } from "./rows.ts";
 import type { RunRecord } from "../engine/run-registry.ts";
 import type { BgRunStatus } from "./rows.ts";
 
@@ -24,6 +24,14 @@ export interface WidgetRun {
   phaseTotal?: number;
   kind: "fg" | "bg";
   backend?: string;
+  /** SPEC-6-1: task excerpt for the primary label (fg runs). */
+  task?: string;
+  /** SPEC-6-1: latest context-token snapshot (for ctx% segment). */
+  contextTokens?: number;
+  /** SPEC-6-1: max context window for the resolved model (set by controller — Task 7). */
+  maxContext?: number;
+  /** SPEC-6-1: cumulative $ (for the $ segment). */
+  costTotal?: number;
 }
 
 export function toWidgetRun(r: RunRecord): WidgetRun {
@@ -31,6 +39,7 @@ export function toWidgetRun(r: RunRecord): WidgetRun {
     runId: r.runId, agent: r.agent, status: r.status,
     startedAt: r.startedAt, endedAt: r.endedAt, tokenTotal: r.tokenTotal,
     kind: "fg",
+    task: r.task, costTotal: r.costTotal, contextTokens: r.contextTokens,
   };
 }
 
@@ -57,14 +66,26 @@ const STATUS_GLYPH: Record<WidgetRun["status"], string> = {
   running: "▶", queued: "⏳", paused: "⏸", completed: "✓", failed: "✗", aborted: "✗",
 };
 
-/** One compact line per active run. */
+/** One compact line per active run.
+ *  fg: `▶ "task excerpt"  · agent  5s  265K tok  42%  $0.01` (runId hidden; agent hidden when general-purpose).
+ *  bg: `▶ ●plan 2/4  pi` (phase as primary label; no runId, no task excerpt). */
 function widgetLine(r: WidgetRun, now: number): string {
   const glyph = STATUS_GLYPH[r.status];
   const dur = typeof r.startedAt === "number" ? `  ${fmtDuration(now - r.startedAt)}` : "";
-  const tok = r.tokenTotal ? `  ${r.tokenTotal} tok` : "";
-  const phase = r.phase ? `  ●${r.phase} ${r.phaseIndex ?? 0}/${r.phaseTotal ?? 0}` : "";
-  const be = r.backend ? `  ${r.backend}` : "";
-  return `${glyph} ${r.runId}  ${r.agent}${dur}${tok}${phase}${be}`;
+  const tok = r.tokenTotal ? `  ${fmtTokens(r.tokenTotal)} tok` : "";
+  const ctx = (r.contextTokens != null && r.maxContext != null && r.maxContext > 0) ? `  ${Math.round(r.contextTokens / r.maxContext * 100)}%` : "";
+  const cost = r.costTotal ? `  $${r.costTotal.toFixed(4)}` : "";
+
+  if (r.kind === "bg") {
+    const phase = r.phase ? `●${r.phase} ${r.phaseIndex ?? 0}/${r.phaseTotal ?? 0}` : r.runId;
+    const be = r.backend ? `  ${r.backend}` : "";
+    return `${glyph} ${phase}${tok}${be}`;
+  }
+
+  // fg: task excerpt as primary label (fallback to runId if no task)
+  const label = r.task ? `"${r.task.slice(0, 40)}"` : r.runId;
+  const agentSeg = r.agent && r.agent !== "general-purpose" ? `  · ${r.agent}` : "";
+  return `${glyph} ${label}${agentSeg}${dur}${tok}${ctx}${cost}`;
 }
 
 /** Above-editor widget: one line per active run, cap 5, overflow → "+N more in /fleet". */

package/src/registry/frontmatter.ts

@@ -22,6 +22,8 @@ export interface AgentDef {
   sessionKey: string;
   source: AgentSource;
   filePath: string;
+  /** SPEC-6-1: cost-aware model tier (overrides agent.model when set). */
+  tier?: string;
 }
 
 export class FrontmatterError extends Error {
@@ -67,6 +69,7 @@ export function parseAgentFile(content: string, filePath: string, source: AgentS
     name,
     description,
     model: typeof raw.model === "string" ? raw.model : undefined,
+    tier: typeof raw.tier === "string" ? raw.tier : undefined,
     thinkingLevel: typeof raw.thinkingLevel === "string" ? (raw.thinkingLevel as ThinkingLevel) : undefined,
     tools: strList(raw.tools),
     skills: strList(raw.skills),

package/src/runtime/run-log.ts

@@ -14,7 +14,7 @@ export interface RunMetaEvent {
 }
 export interface MessageEvent {
   type: "message"; role: string; text: string;
-  usage?: { total?: number; input?: number; output?: number; cacheRead?: number; cacheWrite?: number };
+  usage?: { total?: number; input?: number; output?: number; cacheRead?: number; cacheWrite?: number; cost?: { total?: number } };
   turnIndex: number;
 }
 export interface ToolEvent {
@@ -23,6 +23,10 @@ export interface ToolEvent {
 export interface RunEndedEvent {
   type: "run:ended"; runId: string; status: FleetRunStatus; endedAt: number;
   resultSummary?: string; tokenTotal: number; resumedFrom?: string; forkedFrom?: string;
+  /** SPEC-6-1: cumulative $ at run end. */
+  costTotal?: number;
+  /** SPEC-6-1: latest context-token snapshot at run end. */
+  contextTokens?: number;
 }
 export type RunLogEvent = RunMetaEvent | MessageEvent | ToolEvent | RunEndedEvent;
 
@@ -33,6 +37,10 @@ export interface RunMeta {
   backendSessionId?: string; sessionKey?: string;
   status: FleetRunStatus; endedAt?: number; resultSummary?: string; tokenTotal: number;
   resumedFrom?: string; forkedFrom?: string;
+  /** SPEC-6-1: cumulative $ at run end. */
+  costTotal?: number;
+  /** SPEC-6-1: latest context-token snapshot at run end. */
+  contextTokens?: number;
 }
 
 const ARGS_LIMIT = 200;
@@ -103,6 +111,7 @@ export class RunLog {
         meta.status = ended.status; meta.endedAt = ended.endedAt;
         meta.resultSummary = ended.resultSummary; meta.tokenTotal = ended.tokenTotal;
         meta.resumedFrom = ended.resumedFrom; meta.forkedFrom = ended.forkedFrom;
+        meta.costTotal = ended.costTotal; meta.contextTokens = ended.contextTokens;
       }
       out.push(meta);
     }

package/src/tiers/builtin.ts

@@ -0,0 +1,8 @@
+import type { Tier } from "./tier-registry.ts";
+
+/** Shipped default tiers (Q10). Overridable via global/project tiers.json. */
+export const BUILTIN_TIERS: Tier[] = [
+  { name: "economy",  models: ["Ollama/minimax-m3:cloud"] },
+  { name: "standard", models: ["Ollama/glm-5.2:cloud", "Ollama/minimax-m3:cloud"] },
+  { name: "frontier", models: ["anthropic/claude-sonnet-4", "Ollama/glm-5.2:cloud"], costCap: 5, contextFloor: 200000 },
+];

package/src/tiers/resolve.ts

@@ -0,0 +1,50 @@
+import type { AgentDef } from "../registry/frontmatter.ts";
+import type { Tier, TierRegistry } from "./tier-registry.ts";
+
+/** Narrow port over pi's ModelRegistry — only the lookup 6-1 needs. */
+export interface ModelRegistryLike {
+  find(provider: string, modelId: string): { contextWindow: number } | undefined;
+}
+
+export interface ResolvedModel {
+  model: string;
+  tier?: Tier;
+  /** Pre-filtered eligible candidates (primary first); spawnSubagent retries these on create() rejection. */
+  candidates?: string[];
+}
+
+export interface ResolveError { error: string; model?: undefined; }
+
+/** Split "provider/modelId" on the first "/". Bare id → { parentProvider, id }. */
+export function splitModel(model: string, parentProvider = ""): { provider: string; id: string } {
+  const i = model.indexOf("/");
+  if (i < 0) return { provider: parentProvider, id: model };
+  return { provider: model.slice(0, i), id: model.slice(i + 1) };
+}
+
+/** Q4 precedence: optsModel > agent.tier > agent.model > parent. Q5: contextFloor + catalog filter. */
+export function resolveAgentModel(
+  agent: AgentDef, optsModel: string | undefined,
+  parentModel: { provider: string; id: string },
+  tiers: TierRegistry, modelRegistry: ModelRegistryLike,
+): ResolvedModel | ResolveError {
+  if (optsModel) return { model: optsModel };
+  if (agent.tier) {
+    const tier = tiers.get(agent.tier);
+    if (!tier) return { error: `tier '${agent.tier}' not found; available: ${tiers.list().map((t) => t.name).join(", ")}` };
+    const candidates: string[] = [];
+    for (const m of tier.models) {
+      const { provider, id } = splitModel(m, parentModel.provider);
+      const model = modelRegistry.find(provider, id);
+      if (!model) continue;                                              // not in catalog → skip
+      if (tier.contextFloor && (model.contextWindow ?? 0) < tier.contextFloor) continue;  // below floor → skip
+      candidates.push(m);
+    }
+    if (candidates.length === 0) {
+      return { error: `tier '${tier.name}': no eligible model (all missing or below contextFloor ${tier.contextFloor ?? "—"})` };
+    }
+    return { model: candidates[0]!, tier, candidates };
+  }
+  if (agent.model) return { model: agent.model };
+  return { model: `${parentModel.provider}/${parentModel.id}` };
+}

package/src/tiers/tier-registry.ts

@@ -0,0 +1,66 @@
+export interface Tier {
+  name: string;
+  models: string[];          // ordered fallback chain, primary first
+  costCap?: number;          // $ per-run; abort when run.costTotal exceeds
+  contextFloor?: number;     // min contextWindow; skip models below it at spawn
+}
+
+export class TierFileError extends Error {
+  override name = "TierFileError" as const;
+}
+
+/** Parse a raw JSON string into validated Tier[]. Empty/blank → []. */
+export function parseTiersFile(raw: string): Tier[] {
+  const trimmed = raw.trim();
+  if (!trimmed) return [];
+  let parsed: unknown;
+  try { parsed = JSON.parse(trimmed); } catch { throw new TierFileError("malformed tiers file (invalid JSON)"); }
+  if (!Array.isArray(parsed)) throw new TierFileError("tiers file must be a JSON array of tier objects");
+  const seen = new Set<string>();
+  return parsed.map((t) => {
+    const obj = t as Record<string, unknown>;
+    const name = obj.name;
+    const models = obj.models;
+    if (typeof name !== "string" || !name.trim()) throw new TierFileError("tier missing name");
+    if (!Array.isArray(models)) throw new TierFileError("tier missing models");
+    if (models.length === 0) throw new TierFileError(`tier '${name}' has empty models`);
+    if (seen.has(name)) throw new TierFileError(`duplicate tier name '${name}'`);
+    seen.add(name);
+    return {
+      name, models: models.map(String),
+      ...(typeof obj.costCap === "number" ? { costCap: obj.costCap } : {}),
+      ...(typeof obj.contextFloor === "number" ? { contextFloor: obj.contextFloor } : {}),
+    };
+  });
+}
+
+/** Merge tiers by name: builtins < global < project (later scopes win by name). */
+export function mergeTiers(builtin: Tier[], globalTiers: Tier[], project: Tier[]): Tier[] {
+  const map = new Map<string, Tier>();
+  for (const t of builtin) map.set(t.name, t);
+  for (const t of globalTiers) map.set(t.name, t);
+  for (const t of project) map.set(t.name, t);
+  return [...map.values()];
+}
+
+export interface TierRegistryOpts {
+  tiers: Tier[];
+  /** Agent defs keyed by agent name — only the `tier` field is read, for `usedBy`. */
+  agents: Map<string, { tier?: string }>;
+}
+
+export class TierRegistry {
+  private readonly byName = new Map<string, Tier>();
+  private readonly agents: Map<string, { tier?: string }>;
+  constructor(opts: TierRegistryOpts) {
+    for (const t of opts.tiers) this.byName.set(t.name, t);
+    this.agents = opts.agents;
+  }
+  get(name: string): Tier | undefined { return this.byName.get(name); }
+  list(): Tier[] { return [...this.byName.values()]; }
+  usedBy(name: string): string[] {
+    const out: string[] = [];
+    for (const [agentName, def] of this.agents) if (def.tier === name) out.push(agentName);
+    return out.sort();
+  }
+}

package/src/tiers/tier-store.ts

@@ -0,0 +1,22 @@
+import { readFileSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { parseTiersFile, type Tier } from "./tier-registry.ts";
+
+export interface TierStoreOpts { projectPath: string; globalPath: string; }
+
+export class TierStore {
+  constructor(private readonly opts: TierStoreOpts) {}
+  read(scope: "project" | "global"): Tier[] {
+    const path = scope === "project" ? this.opts.projectPath : this.opts.globalPath;
+    try { return parseTiersFile(readFileSync(path, "utf8")); } catch { return []; }
+  }
+  write(scope: "project" | "global", tiers: Tier[]): void {
+    const json = JSON.stringify(tiers, null, 2);
+    parseTiersFile(json);  // throws on invalid — no file change
+    const path = scope === "project" ? this.opts.projectPath : this.opts.globalPath;
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, json, "utf8");
+    renameSync(tmp, path);  // atomic
+  }
+}

package/src/tools/subagent.ts

@@ -48,6 +48,16 @@ export interface SubagentToolDeps {
   bgRuns?: import("../panel/bg-runs-store.ts").BgRunsStore;
   /** SPEC-5b-1: durable per-run conversation log. Optional — Runs tab + journaling disabled when absent. */
   runLog?: import("../runtime/run-log.ts").RunLog;
+  /** SPEC-6-1: tier registry for cost-aware model routing. Optional. */
+  tierRegistry?: import("../tiers/tier-registry.ts").TierRegistry;
+  /** SPEC-6-1: model registry for contextWindow lookups (contextFloor + ctx%). Optional. */
+  modelRegistry?: import("../tiers/resolve.ts").ModelRegistryLike;
+  /** SPEC-6-1: tier store for the /fleet Tiers view writes. Optional. */
+  tierStore?: import("../tiers/tier-store.ts").TierStore;
+  /** SPEC-6-1: rebuild the tier registry after a panel write. */
+  reloadTiers?: () => void;
+  /** SPEC-6-1: model contextWindow resolver for Runs-tab ctx% (Surface C). Optional — ctx% hidden when absent. */
+  getModelContextWindow?: (model: string) => number | undefined;
 }
 
 /** Build the pi.registerTool definition. Thin wrapper over spawnSubagent. */
@@ -89,6 +99,7 @@ export function createSubagentTool(deps: SubagentToolDeps) {
             registry: deps.registry, todoSync: deps.todoSync, runRegistry: deps.runRegistry, lock: deps.lock,
             backendRegistry: deps.backendRegistry, parentModel: deps.parentModel, parentCwd: deps.parentCwd, runLog: deps.runLog, signal,
             maxTurns: params.maxTurns,
+            tierRegistry: deps.tierRegistry, modelRegistry: deps.modelRegistry,
           }),
         };
         const res = await runLifecycle(params.task, params.lifecycle, {
@@ -120,6 +131,7 @@ export function createSubagentTool(deps: SubagentToolDeps) {
         runLog: deps.runLog,
         signal,
         maxTurns: params.maxTurns,
+        tierRegistry: deps.tierRegistry, modelRegistry: deps.modelRegistry,
       });
       const isError = res.status === "failed" || res.status === "aborted";
       return {