@oisin-ee/pi-tiers 0.0.0-stage → 0.9.0

package/README.md

@@ -1,3 +1,65 @@
-# Temporary Holding Version
+# @oisin-ee/pi-tiers
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Tier virtual models keep each branch on its chosen physical model until a failure requires recovery.
+The selected thinking level passes through to the physical model. Pi clamps unsupported levels.
+A model switch loses prompt caches and thinking signatures.
+
+## Config
+
+Put `tiers.json` in the Pi agent directory (`~/.pi/agent` by default):
+
+```json
+{
+  "sol": ["cliproxy/gpt-5.6", "cliproxy/claude-opus-4-6"],
+  "luna": ["cliproxy/minimax-m3", "cliproxy/gpt-5.6"]
+}
+```
+
+Select `tier/sol` or `tier/luna`. Each target must identify a configured physical model.
+An absent file registers no tiers. Invalid config stops registration. Reload Pi after config changes.
+This package does not load `model-alias.json` or register `alias/*` models.
+
+## Recovery
+
+Gateway failures open a provider-wide circuit. Recovery waits, then retries the same target.
+The delay starts at two seconds and doubles to one minute. Gateway failures never cool individual models or pools.
+
+Quota failures exclude a pool. Model IDs that start with `claude-`, `gpt-`, or `minimax-` use the corresponding shared pool.
+Other models use their provider ID as the pool.
+The snapshot reset time controls the exclusion when the pool is exhausted.
+Without that reset, cooldown starts at five minutes and doubles to one hour.
+
+Pi handles native transient retries first. After native retries end, boundary recovery selects the next target.
+Unknown models and request, authentication, or configuration failures stop without failover. Abort never requests recovery.
+Each user turn permits two recoveries. Native transient retries retain Pi's separate retry budget.
+
+Boundary recovery removes only the failed assistant entry from model context.
+A state-only custom entry records the next route. Recovery never creates user messages or rewrites their text.
+The chosen target, attempted targets, and remaining budget follow the session branch.
+
+## Quota and shared state
+
+Before routing, the extension runs `dogsled quota --json --cached` with a two-second timeout.
+The result stays in memory for one minute. Missing Dogsled or an invalid snapshot disables quota filtering.
+The command never requests a CLIProxy refresh.
+
+A pool is exhausted only when every account has a full window with a future reset.
+For multiple blocked windows, an account becomes available after its last reset.
+The first available account ends the pool exclusion.
+
+The shared store is `~/.pi/agent/state/pi-tiers/state.json`.
+An exclusive `lock/` directory protects each read-modify-write transaction. Its `owner.json` records the process ID and creation time.
+A temporary state file and atomic rename protect readers. Lock acquisition stops after two seconds.
+A dead owner or a lock older than 30 seconds permits takeover through atomic directory rename.
+An ownerless directory also expires after 30 seconds. Retired generations remain for 60 seconds to exclude competing takeovers.
+Invalid state and filesystem failures stop routing rather than discard shared health.
+
+Pi 1.3.0 response events contain no model or request identity.
+HTTP status applies only when an error includes the response's `x-request-id` or `request-id` value.
+Otherwise, the classifier uses error text. Unrelated response status never affects routing.
+
+## Development
+
+```bash
+proto run moon -- run pi-tiers:lint pi-tiers:test
+```

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@oisin-ee/pi-tiers",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.9.0",
+  "description": "Sticky virtual model tiers with quota-aware recovery for pi.",
+  "keywords": [
+    "pi-extension",
+    "pi-package",
+    "tiers"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oisin-ee/oisinpi.git",
+    "directory": "packages/pi-tiers"
+  },
+  "files": [
+    "src/",
+    "!src/**/*.test.ts",
+    "!src/fixture.ts"
+  ],
+  "type": "module",
+  "devDependencies": {
+    "@earendil-works/pi-ai": "catalog:",
+    "@earendil-works/pi-coding-agent": "catalog:"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  }
+}

package/src/branch.ts

@@ -0,0 +1,75 @@
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+import type { State } from "./policy.ts";
+import { VIRTUAL_MODEL_STATE_ENTRY } from "@earendil-works/pi-coding-agent";
+
+const ZERO = 0,
+  RECOVERY = "pi-tiers.recovery",
+  /**
+   * Validates branch data before policy uses it.
+   * @param {unknown} value Stored state.
+   * @returns {boolean} Valid state.
+   */
+  isState = (value: unknown): value is State =>
+    typeof value === "object" &&
+    value !== null &&
+    "chosen" in value &&
+    typeof value.chosen === "string" &&
+    "budget" in value &&
+    typeof value.budget === "number" &&
+    Number.isSafeInteger(value.budget) &&
+    value.budget >= ZERO &&
+    "attempted" in value &&
+    Array.isArray(value.attempted) &&
+    value.attempted.every((item: unknown) => typeof item === "string"),
+  /**
+   * Reads state for one tier, including an unconsumed recovery marker.
+   * A subsequent Pi state entry consumes the marker without editing history.
+   * @param {readonly SessionEntry[]} branch Active branch.
+   * @param {string} tier Virtual model ID.
+   * @returns {State | undefined} Latest branch-owned state.
+   */
+  branchState = (branch: readonly SessionEntry[], tier: string): State | undefined => {
+    for (const entry of branch.toReversed()) {
+      if (
+        entry.type === "custom" &&
+        (entry.customType === VIRTUAL_MODEL_STATE_ENTRY || entry.customType === RECOVERY)
+      ) {
+        const data: unknown = entry.data;
+        if (
+          typeof data === "object" &&
+          data !== null &&
+          "provider" in data &&
+          data.provider === "tier" &&
+          "modelId" in data &&
+          data.modelId === tier &&
+          "state" in data &&
+          isState(data.state)
+        ) {
+          return data.state;
+        }
+      }
+    }
+    return undefined;
+  },
+  /**
+   * Detects a real user entry after the latest route or recovery marker.
+   * Pi can label recovery as user after the failed assistant is omitted.
+   * @param {readonly SessionEntry[]} branch Active branch.
+   * @returns {boolean} Whether a fresh user turn started.
+   */
+  newUserTurn = (branch: readonly SessionEntry[]): boolean => {
+    for (const entry of branch.toReversed()) {
+      if (entry.type === "message" && entry.message.role === "user") {
+        return true;
+      }
+      if (
+        entry.type === "custom" &&
+        (entry.customType === RECOVERY || entry.customType === VIRTUAL_MODEL_STATE_ENTRY)
+      ) {
+        return false;
+      }
+    }
+    return false;
+  };
+
+export { branchState, newUserTurn, RECOVERY };

package/src/config.ts

@@ -0,0 +1,48 @@
+import { target } from "./policy.ts";
+
+/** Validated tier names and ordered physical targets. */
+type Tiers = ReadonlyMap<string, readonly string[]>;
+
+const ZERO = 0,
+  /**
+   * Validates a tier's ordered model references.
+   * @param {string} name Tier name.
+   * @param {unknown} models External list.
+   * @returns {readonly string[]} Unique physical targets.
+   */
+  parseTargets = (name: string, models: unknown): readonly string[] => {
+    if (
+      name.length === ZERO ||
+      !Array.isArray(models) ||
+      models.length === ZERO ||
+      !models.every((model: unknown): model is string => typeof model === "string")
+    ) {
+      throw new Error(`Invalid tier: ${name}`);
+    }
+    for (const model of models) {
+      target(model);
+    }
+    return [...new Set(models)];
+  },
+  /**
+   * Validates user config before registration.
+   * @param {string | undefined} source User JSON.
+   * @returns {Tiers} Tier definitions.
+   */
+  parseConfig = (source?: string): Tiers => {
+    if (source === undefined) {
+      return new Map();
+    }
+    const value: unknown = JSON.parse(source);
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      throw new Error("tiers.json must contain a tier-to-model map.");
+    }
+    const tiers = new Map<string, readonly string[]>();
+    for (const [name, models] of Object.entries(value)) {
+      tiers.set(name, parseTargets(name, models));
+    }
+    return tiers;
+  };
+
+export { parseConfig };
+export type { Tiers };

package/src/health.ts

@@ -0,0 +1,92 @@
+/** Backoff record shared by all sessions on one host. */
+interface Backoff {
+  readonly failures: number;
+  readonly until: number;
+}
+/** Provider circuits and pool cooldowns have separate namespaces. */
+interface Health {
+  readonly circuits: Readonly<Record<string, Backoff>>;
+  readonly pools: Readonly<Record<string, Backoff>>;
+}
+/** One atomic update to shared health. */
+interface Change {
+  readonly kind: "gateway" | "quota";
+  readonly key: string;
+  readonly now: number;
+  readonly reset: number | undefined;
+}
+
+const ZERO = 0,
+  ONE = 1,
+  TWO = 2,
+  QUOTA_DELAY = 300_000,
+  QUOTA_MAX = 3_600_000,
+  GATEWAY_DELAY = 2000,
+  GATEWAY_MAX = 60_000,
+  /**
+   * Creates an empty health store.
+   * @returns {Health} Healthy endpoints and pools.
+   */
+  emptyHealth = (): Health => ({ circuits: {}, pools: {} }),
+  /**
+   * Computes exponential backoff while preserving distinct failure domains.
+   * @param {Health} health Current store.
+   * @param {Change} change Failure observation.
+   * @returns {Health} Updated store.
+   */
+  updateHealth = (health: Health, change: Change): Health => {
+    const namespace = change.kind === "gateway" ? "circuits" : "pools",
+      previous = health[namespace][change.key],
+      base = change.kind === "gateway" ? GATEWAY_DELAY : QUOTA_DELAY,
+      maximum = change.kind === "gateway" ? GATEWAY_MAX : QUOTA_MAX,
+      failures = (previous?.failures ?? ZERO) + ONE,
+      delay = Math.min(maximum, base * TWO ** (failures - ONE)),
+      record = { failures, until: change.reset ?? change.now + delay };
+    return Object.assign({}, health, {
+      [namespace]: Object.assign({}, health[namespace], { [change.key]: record }),
+    });
+  },
+  /**
+   * Validates persisted backoff records.
+   * @param {unknown} value External map.
+   * @returns {boolean} Whether all records are valid.
+   */
+  isBackoffs = (value: unknown): value is Record<string, Backoff> =>
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.values(value).every(
+      (entry: unknown) =>
+        typeof entry === "object" &&
+        entry !== null &&
+        "failures" in entry &&
+        typeof entry.failures === "number" &&
+        Number.isSafeInteger(entry.failures) &&
+        entry.failures >= ZERO &&
+        "until" in entry &&
+        typeof entry.until === "number" &&
+        Number.isSafeInteger(entry.until) &&
+        entry.until >= ZERO,
+    ),
+  /**
+   * Rejects corrupt stores rather than silently discarding cooldowns.
+   * @param {string} source Persisted JSON.
+   * @returns {Health} Validated health state.
+   */
+  parseHealth = (source: string): Health => {
+    const value: unknown = JSON.parse(source);
+    if (
+      typeof value !== "object" ||
+      value === null ||
+      !("circuits" in value) ||
+      !("pools" in value) ||
+      !isBackoffs(value.circuits) ||
+      !isBackoffs(value.pools)
+    ) {
+      throw new Error("Invalid pi-tiers health state.");
+    }
+    return { circuits: value.circuits, pools: value.pools };
+  };
+
+export { emptyHealth, parseHealth, updateHealth };
+export type { Change, Health };

package/src/index.ts

@@ -0,0 +1,70 @@
+import type {
+  AfterProviderResponseEvent,
+  ExtensionAPI,
+  ModelRoute,
+} from "@earendil-works/pi-coding-agent";
+import { Store, readConfig, wait } from "./source.ts";
+import type { Health } from "./health.ts";
+import { Recovery } from "./recovery.ts";
+import type { Request } from "./ports.ts";
+import { Router } from "./router.ts";
+import type { State } from "./policy.ts";
+import { parseConfig } from "./config.ts";
+
+const QUOTA_TIMEOUT = 2000,
+  SUCCESS = 0,
+  /**
+   * Registers user-defined tiers and the final-boundary recovery adapter.
+   * @param {ExtensionAPI} pi Pi extension authority.
+   * @returns {Promise<void>} Registration completion.
+   */
+  extension = async (pi: ExtensionAPI): Promise<void> => {
+    const tiers = parseConfig(await readConfig()),
+      store = new Store(),
+      router = new Router({
+        change: async (change): Promise<void> => store.change(change),
+        now: Date.now,
+        quota: async (): Promise<string> => {
+          try {
+            const result = await pi.exec("dogsled", ["quota", "--json", "--cached"], {
+              timeout: QUOTA_TIMEOUT,
+            });
+            return result.code === SUCCESS ? result.stdout : "";
+          } catch {
+            return "";
+          }
+        },
+        read: async (): Promise<Health> => store.read(),
+        wait,
+      }),
+      recovery = new Recovery(router, tiers);
+    for (const [id, targets] of tiers) {
+      pi.registerVirtualModel<State>({
+        id,
+        name: `Tier: ${id}`,
+        provider: "tier",
+        route: async (request: Request, ctx): Promise<ModelRoute<State>> =>
+          router.route(targets, request, ctx),
+        thinkingLevels: ["off", "minimal", "low", "medium", "high", "xhigh", "max"],
+      });
+    }
+    pi.on(
+      "after_provider_response",
+      (
+        event: Readonly<Omit<AfterProviderResponseEvent, "headers">> & {
+          readonly headers: Readonly<Record<string, string>>;
+        },
+      ) => {
+        router.responses.observe(event.headers, event.status);
+      },
+    );
+    pi.on("agent_before_settle", async (event, ctx) => recovery.settle(event, ctx));
+    pi.on("agent_settled", () => {
+      router.responses.clear();
+    });
+    pi.on("session_start", () => {
+      router.responses.clear();
+    });
+  };
+
+export default extension;

package/src/lock.ts

@@ -0,0 +1,53 @@
+/** A lock generation identifies its owning process and creation time. */
+interface Owner {
+  readonly created_ms: number;
+  readonly pid: number;
+}
+
+const ZERO = 0,
+  STALE_MS = 30_000,
+  RETIRED_MS = 60_000,
+  /**
+   * Validates lock metadata before process checks or path construction.
+   * @param {string} source Owner JSON.
+   * @returns {Owner | undefined} Complete metadata, or an interrupted write.
+   */
+  parseOwner = (source: string): Owner | undefined => {
+    try {
+      const value: unknown = JSON.parse(source);
+      if (
+        typeof value !== "object" ||
+        value === null ||
+        !("pid" in value) ||
+        !("created_ms" in value) ||
+        typeof value.pid !== "number" ||
+        !Number.isSafeInteger(value.pid) ||
+        value.pid <= ZERO ||
+        typeof value.created_ms !== "number" ||
+        !Number.isSafeInteger(value.created_ms) ||
+        value.created_ms < ZERO
+      ) {
+        return undefined;
+      }
+      return { created_ms: value.created_ms, pid: value.pid };
+    } catch {
+      return undefined;
+    }
+  },
+  /**
+   * Names a retired generation without using untrusted path fragments.
+   * @param {Owner} owner Observed generation.
+   * @returns {string} Tombstone directory name.
+   */
+  retiredName = (owner: Owner): string => `retired-${owner.pid}-${owner.created_ms}`,
+  /**
+   * Compares a fresh observation with a previously observed generation.
+   * @param {Owner | undefined} current Fresh metadata.
+   * @param {Owner} expected Original metadata.
+   * @returns {boolean} Whether retirement still applies.
+   */
+  sameOwner = (current: Owner | undefined, expected: Owner): boolean =>
+    current?.pid === expected.pid && current.created_ms === expected.created_ms;
+
+export { parseOwner, RETIRED_MS, retiredName, sameOwner, STALE_MS };
+export type { Owner };

package/src/policy.ts

@@ -0,0 +1,85 @@
+/** Failure classes control recovery, not provider retry settings. */
+type Failure = "gateway" | "quota" | "transient" | "request";
+/** Durable router state on one session branch. */
+interface State {
+  readonly attempted: readonly string[];
+  readonly budget: number;
+  readonly chosen: string;
+}
+/** Parsed physical model reference. */
+interface Target {
+  readonly id: string;
+  readonly pool: string;
+  readonly provider: string;
+}
+
+const ZERO = 0,
+  ONE = 1,
+  BAD_GATEWAY = 502,
+  UNAVAILABLE = 503,
+  BAD_REQUEST = 400,
+  UNAUTHORIZED = 401,
+  FORBIDDEN = 403,
+  BUDGET = 2,
+  QUOTA_STATUS = 429,
+  GATEWAY_STATUSES = new Set([BAD_GATEWAY, UNAVAILABLE]),
+  REQUEST_STATUSES = new Set([BAD_REQUEST, UNAUTHORIZED, FORBIDDEN]),
+  /**
+   * Classifies exactly once, with permanent failures taking precedence.
+   * @param {string} message Provider error text.
+   * @param {number | undefined} status Correlated HTTP status.
+   * @returns {Failure} Recovery class.
+   */
+  classify = (message: string, status?: number): Failure => {
+    if (
+      REQUEST_STATUSES.has(status ?? ZERO) ||
+      /unknown model|\b(?:status|code|HTTP)\s*:?\s*(?:400|401|403)\b|unauthorized|forbidden/iu.test(
+        message,
+      )
+    ) {
+      return "request";
+    }
+    if (
+      GATEWAY_STATUSES.has(status ?? ZERO) ||
+      /\b(?:status|code|HTTP)\s*:?\s*(?:502|503)\b|no available server|bad gateway|unable to connect/iu.test(
+        message,
+      )
+    ) {
+      return "gateway";
+    }
+    if (
+      status === QUOTA_STATUS ||
+      /\b(?:status|code|HTTP)\s*:?\s*429\b|usage.limit|rate_limit|insufficient_quota|quota exceeded/iu.test(
+        message,
+      )
+    ) {
+      return "quota";
+    }
+    return /overloaded|timeout|timed out|websocket.*1006|server_busy|retry after/iu.test(message)
+      ? "transient"
+      : "request";
+  },
+  /**
+   * Parses a provider-qualified model and assigns its quota pool.
+   * @param {string} reference Model reference.
+   * @returns {Target} Physical target.
+   */
+  target = (reference: string): Target => {
+    const separator = reference.indexOf("/"),
+      provider = reference.slice(ZERO, separator),
+      id = reference.slice(separator + ONE);
+    if (separator < ONE || id.length === ZERO) {
+      throw new Error(`Invalid tier target: ${reference}`);
+    }
+    const pools = [
+        ["claude-", "claude"],
+        ["gpt-", "codex"],
+        ["minimax-", "minimax"],
+      ],
+      pool =
+        pools.find(([prefix]: readonly string[]) => id.startsWith(prefix ?? ""))?.[ONE] ?? provider;
+    return { id, pool, provider };
+  };
+
+export { BUDGET, classify, target };
+export type { Failure, State, Target };

package/src/ports.ts

@@ -0,0 +1,29 @@
+import type { Change, Health } from "./health.ts";
+import type { ExtensionContext, ModelRouteRequest } from "@earendil-works/pi-coding-agent";
+import type { State } from "./policy.ts";
+
+/** Pi authority used by routing and settlement. */
+interface Context {
+  readonly model: ExtensionContext["model"];
+  readonly modelRegistry: Pick<ExtensionContext["modelRegistry"], "getAvailable">;
+  readonly sessionManager: Pick<ExtensionContext["sessionManager"], "getBranch">;
+  readonly signal?: AbortSignal | undefined;
+}
+/** External effects owned by the host adapter. */
+interface Effects {
+  readonly change: (change: Change) => Promise<void>;
+  readonly now: () => number;
+  readonly quota: () => Promise<string>;
+  readonly read: () => Promise<Health>;
+  readonly wait: (delay: number, signal?: AbortSignal) => Promise<void>;
+}
+/** Read-only Pi routing request. */
+type Request = Readonly<
+  Pick<ModelRouteRequest<State>, "model" | "reason" | "signal" | "state" | "thinkingLevel">
+> & {
+  readonly failed?: {
+    readonly message: { readonly errorMessage?: string; readonly stopReason: string };
+  };
+};
+
+export type { Context, Effects, Request };

package/src/quota.ts

@@ -0,0 +1,81 @@
+/** One validated account window from Dogsled. */
+interface Window {
+  readonly account: string;
+  readonly pool: string;
+  readonly resets_ms: number | null;
+  readonly used_pct: number;
+}
+
+const ZERO = 0,
+  VERSION = 1,
+  FULL = 100,
+  /**
+   * Validates the fields used by quota policy.
+   * @param {unknown} value External window.
+   * @returns {boolean} Whether the window is usable.
+   */
+  isWindow = (value: unknown): value is Window =>
+    typeof value === "object" &&
+    value !== null &&
+    "account" in value &&
+    typeof value.account === "string" &&
+    "pool" in value &&
+    typeof value.pool === "string" &&
+    "used_pct" in value &&
+    typeof value.used_pct === "number" &&
+    Number.isFinite(value.used_pct) &&
+    value.used_pct >= ZERO &&
+    value.used_pct <= FULL &&
+    "resets_ms" in value &&
+    (value.resets_ms === null ||
+      (typeof value.resets_ms === "number" &&
+        Number.isSafeInteger(value.resets_ms) &&
+        value.resets_ms >= ZERO)),
+  /**
+   * Rejects malformed or unsupported snapshots instead of filtering from partial data.
+   * @param {string} source JSON snapshot.
+   * @returns {readonly Window[]} Validated windows, or no filtering.
+   */
+  parseQuota = (source: string): readonly Window[] => {
+    try {
+      const value: unknown = JSON.parse(source);
+      if (
+        typeof value !== "object" ||
+        value === null ||
+        !("version" in value) ||
+        value.version !== VERSION ||
+        !("pools" in value) ||
+        !Array.isArray(value.pools) ||
+        !value.pools.every(isWindow)
+      ) {
+        return [];
+      }
+      return value.pools;
+    } catch {
+      return [];
+    }
+  },
+  /**
+   * Finds when any account in an exhausted pool first becomes available.
+   * @param {readonly Window[]} windows Snapshot windows.
+   * @param {string} pool Pool name.
+   * @param {number} now Current time.
+   * @returns {number | undefined} Pool reset, only when every account is exhausted.
+   */
+  exhaustedUntil = (windows: readonly Window[], pool: string, now: number): number | undefined => {
+    const accounts = new Map<string, number>();
+    for (const window of windows.filter((entry) => entry.pool === pool)) {
+      const reset =
+        window.used_pct >= FULL && window.resets_ms !== null && window.resets_ms > now
+          ? window.resets_ms
+          : ZERO;
+      accounts.set(window.account, Math.max(accounts.get(window.account) ?? ZERO, reset));
+    }
+    const resets = [...accounts.values()];
+    return resets.length > ZERO && resets.every((reset) => reset > now)
+      ? Math.min(...resets)
+      : undefined;
+  };
+
+export { exhaustedUntil, parseQuota };
+export type { Window };

package/src/recovery.ts

@@ -0,0 +1,114 @@
+import type {
+  AgentBeforeSettleEvent,
+  BoundaryResult,
+  SessionEntry,
+} from "@earendil-works/pi-coding-agent";
+import type { Failure, State } from "./policy.ts";
+import { RECOVERY, branchState } from "./branch.ts";
+import type { Context } from "./ports.ts";
+import type { Router } from "./router.ts";
+import type { Tiers } from "./config.ts";
+import { classify } from "./policy.ts";
+
+const ZERO = 0,
+  ONE = 1;
+
+/** Final-boundary recovery runs only after Pi's automatic retry policy ends. */
+class Recovery {
+  readonly #router: Readonly<Pick<Router, "failed" | "next">> & {
+    readonly responses: Readonly<Router["responses"]>;
+  };
+  readonly #tiers: Readonly<Tiers>;
+
+  /**
+   * Connects boundary recovery to routing policy.
+   * @param {Readonly<Router>} router Routing owner.
+   * @param {Readonly<Tiers>} tiers Ordered targets.
+   */
+  public constructor(
+    router: Readonly<Pick<Router, "failed" | "next">> & {
+      readonly responses: Readonly<Router["responses"]>;
+    },
+    tiers: Readonly<Tiers>,
+  ) {
+    this.#router = router;
+    this.#tiers = tiers;
+  }
+
+  /**
+   * Applies a classified failure to the recovery budget and target choice.
+   * @param {Failure} failure Failure class.
+   * @param {State} state Branch state.
+   * @param {readonly string[]} targets Tier targets.
+   * @returns {Promise<State | undefined>} Recovery state, when permitted.
+   */
+  async #next(
+    failure: Failure,
+    state: State,
+    targets: readonly string[],
+  ): Promise<State | undefined> {
+    await this.#router.failed(failure, state.chosen);
+    if (failure === "request" || state.budget === ZERO) {
+      return undefined;
+    }
+    const attempted = failure === "gateway" ? state.attempted : [...state.attempted, state.chosen],
+      next = Object.assign({}, state, { attempted, budget: state.budget - ONE }),
+      chosen = failure === "gateway" ? state.chosen : await this.#router.next(targets, next);
+    return chosen === undefined ? undefined : Object.assign({}, next, { chosen });
+  }
+
+  /**
+   * Omits only the failed assistant and appends a state-only recovery marker.
+   * @param {AgentBeforeSettleEvent} event Final actionable boundary.
+   * @param {Context} ctx Pi authority.
+   * @returns {Promise<BoundaryResult | undefined>} Bounded recovery, or no action.
+   */
+  public async settle(
+    event: AgentBeforeSettleEvent,
+    ctx: Context,
+  ): Promise<BoundaryResult | undefined> {
+    if (
+      event.outcome !== "error" ||
+      ctx.signal?.aborted === true ||
+      ctx.model?.provider !== "tier"
+    ) {
+      return undefined;
+    }
+    const tier = ctx.model.id,
+      state = branchState(ctx.sessionManager.getBranch(), tier),
+      targets = this.#tiers.get(tier),
+      message = event.context.contextMessages.findLast((item) => item.role === "assistant"),
+      entry = event.context.contextEntries.findLast(
+        (item: Readonly<{ sourceEntry: SessionEntry; messages: readonly unknown[] }>) =>
+          item.messages.includes(message),
+      );
+    if (
+      state === undefined ||
+      targets === undefined ||
+      entry === undefined ||
+      message?.role !== "assistant" ||
+      message.stopReason !== "error" ||
+      `${message.provider}/${message.model}` !== state.chosen
+    ) {
+      return undefined;
+    }
+    const text = message.errorMessage ?? "",
+      next = await this.#next(classify(text, this.#router.responses.status(text)), state, targets);
+    if (next === undefined || Boolean(ctx.signal?.aborted)) {
+      return undefined;
+    }
+    return {
+      continue: true,
+      entries: [
+        { replacement: null, targetId: entry.sourceEntry.id, type: "context_edit" },
+        {
+          customType: RECOVERY,
+          data: { modelId: tier, provider: "tier", state: next },
+          type: "custom",
+        },
+      ],
+    };
+  }
+}
+
+export { Recovery };

package/src/responses.ts

@@ -0,0 +1,44 @@
+const ZERO = 0,
+  ONE = 1,
+  LIMIT = 128;
+
+/** Correlates HTTP status only when the error identifies the same response. */
+class Responses {
+  readonly #statuses = new Map<string, number>();
+
+  /**
+   * Records bounded response metadata, never headers or credentials.
+   * @param {Readonly<Record<string, string>>} headers Response headers.
+   * @param {number} status HTTP status.
+   */
+  public observe(headers: Readonly<Record<string, string>>, status: number): void {
+    const id = headers["x-request-id"] ?? headers["request-id"];
+    if (this.#statuses.size >= LIMIT) {
+      this.#statuses.clear();
+    }
+    if (id !== undefined && id.length > ZERO) {
+      this.#statuses.set(id, status);
+    }
+  }
+
+  /**
+   * Uses status only when a provider error explicitly includes its request ID.
+   * @param {string} message Error text.
+   * @returns {number | undefined} Correlated status.
+   */
+  public status(message: string): number | undefined {
+    const tokens: readonly string[] = message.match(/[a-z0-9_-]+/giu) ?? [],
+      matches = [...this.#statuses].filter(([id]: readonly [string, number]) =>
+        tokens.includes(id),
+      ),
+      [match] = matches;
+    return matches.length === ONE ? match?.[ONE] : undefined;
+  }
+
+  /** Removes metadata after settlement or session navigation. */
+  public clear(): void {
+    this.#statuses.clear();
+  }
+}
+
+export { Responses };

package/src/router.ts

@@ -0,0 +1,176 @@
+import { BUDGET, classify, target } from "./policy.ts";
+import type { Context, Effects, Request } from "./ports.ts";
+import type { Failure, State } from "./policy.ts";
+import { branchState, newUserTurn } from "./branch.ts";
+import { exhaustedUntil, parseQuota } from "./quota.ts";
+import type { Health } from "./health.ts";
+import type { ModelRoute } from "@earendil-works/pi-coding-agent";
+import { Responses } from "./responses.ts";
+import type { Window } from "./quota.ts";
+
+const ZERO = 0,
+  ONE = 1,
+  CACHE_MS = 60_000;
+
+/** Sticky routing with host-wide quota and gateway health. */
+class Router {
+  readonly #effects: Effects;
+  public readonly responses = new Responses();
+  #quota: readonly Window[] = [];
+  #quotaUntil = ZERO;
+
+  /**
+   * Connects policy to host effects.
+   * @param {Effects} effects External authority.
+   */
+  public constructor(effects: Effects) {
+    this.#effects = effects;
+  }
+
+  /**
+   * Refreshes only the local cached quota snapshot, at most once per minute.
+   * @returns {Promise<void>} Completion.
+   */
+  async #refresh(): Promise<void> {
+    if (this.#effects.now() >= this.#quotaUntil) {
+      this.#quota = parseQuota(await this.#effects.quota());
+      this.#quotaUntil = this.#effects.now() + CACHE_MS;
+    }
+  }
+
+  /**
+   * Checks both explicit cooldowns and account windows.
+   * @param {string} reference Model reference.
+   * @param {Health} health Shared snapshot.
+   * @returns {boolean} Availability.
+   */
+  #available(reference: string, health: Health): boolean {
+    const { pool } = target(reference),
+      now = this.#effects.now();
+    return (
+      (health.pools[pool]?.until ?? ZERO) <= now &&
+      exhaustedUntil(this.#quota, pool, now) === undefined
+    );
+  }
+
+  /**
+   * Chooses the first unattempted available target without changing state.
+   * @param {readonly string[]} targets Ordered tier.
+   * @param {State} state Branch state.
+   * @returns {Promise<string | undefined>} Next target.
+   */
+  public async next(targets: readonly string[], state: State): Promise<string | undefined> {
+    await this.#refresh();
+    const health = await this.#effects.read();
+    return targets.find(
+      (candidate) => !state.attempted.includes(candidate) && this.#available(candidate, health),
+    );
+  }
+
+  /**
+   * Records only gateway circuits or quota cooldowns.
+   * @param {Failure} failure Classified failure.
+   * @param {string} reference Failed physical model.
+   * @returns {Promise<void>} Completion.
+   */
+  public async failed(failure: Failure, reference: string): Promise<void> {
+    if (failure === "gateway" || failure === "quota") {
+      await this.#refresh();
+      const parsed = target(reference),
+        now = this.#effects.now();
+      await this.#effects.change({
+        key: failure === "gateway" ? parsed.provider : parsed.pool,
+        kind: failure,
+        now,
+        reset: failure === "quota" ? exhaustedUntil(this.#quota, parsed.pool, now) : undefined,
+      });
+    }
+  }
+
+  /**
+   * Keeps native transient retries on their current physical model.
+   * @param {Request} request Pi request.
+   * @param {State} state Current branch state.
+   * @returns {Promise<State>} State after a native retry failure.
+   */
+  async #retry(request: Request, state: State): Promise<State> {
+    const { failed } = request;
+    if (failed === undefined) {
+      return state;
+    }
+    const message = failed.message.errorMessage ?? "",
+      failure = classify(message, this.responses.status(message));
+    if (failed.message.stopReason === "aborted" || failure === "request") {
+      throw new Error(message || "Tier request stopped.");
+    }
+    await this.failed(failure, state.chosen);
+    if (failure === "quota" && state.budget === ZERO) {
+      throw new Error("Tier recovery budget exhausted.");
+    }
+    return failure === "quota"
+      ? Object.assign({}, state, {
+          attempted: [...state.attempted, state.chosen],
+          budget: state.budget - ONE,
+        })
+      : state;
+  }
+
+  /**
+   * Dispatches with the selected thinking level after checking shared health.
+   * @param {Request} request Pi request.
+   * @param {Context} ctx Pi authority.
+   * @param {State} state Chosen state.
+   * @returns {Promise<ModelRoute<State>>} Physical route.
+   */
+  async #dispatch(request: Request, ctx: Context, state: State): Promise<ModelRoute<State>> {
+    const parsed = target(state.chosen),
+      model = ctx.modelRegistry
+        .getAvailable()
+        .find((candidate) => candidate.provider === parsed.provider && candidate.id === parsed.id);
+    if (model === undefined) {
+      throw new Error(`Unknown model: ${state.chosen}`);
+    }
+    const health = await this.#effects.read(),
+      until = health.circuits[parsed.provider]?.until ?? ZERO;
+    await this.#effects.wait(until - this.#effects.now(), request.signal);
+    request.signal?.throwIfAborted();
+    return { model, state, thinkingLevel: request.thinkingLevel };
+  }
+
+  /**
+   * Routes a tier without fabricating conversation messages.
+   * @param {readonly string[]} targets Ordered physical models.
+   * @param {Request} request Pi request.
+   * @param {Context} ctx Pi authority.
+   * @returns {Promise<ModelRoute<State>>} Physical dispatch.
+   */
+  public async route(
+    targets: readonly string[],
+    request: Request,
+    ctx: Context,
+  ): Promise<ModelRoute<State>> {
+    request.signal?.throwIfAborted();
+    await this.#refresh();
+    const previous =
+        request.reason === "direct"
+          ? undefined
+          : (branchState(ctx.sessionManager.getBranch(), request.model.id) ?? request.state),
+      initial = previous ?? { attempted: [], budget: BUDGET, chosen: targets[ZERO] ?? "" },
+      current =
+        request.reason === "user" && newUserTurn(ctx.sessionManager.getBranch())
+          ? Object.assign({}, initial, { attempted: [], budget: BUDGET })
+          : initial,
+      state = await this.#retry(request, current),
+      health = await this.#effects.read(),
+      chosen =
+        !state.attempted.includes(state.chosen) && this.#available(state.chosen, health)
+          ? state.chosen
+          : await this.next(targets, state);
+    if (chosen === undefined) {
+      throw new Error("No available target in tier.");
+    }
+    return this.#dispatch(request, ctx, Object.assign({}, state, { chosen }));
+  }
+}
+
+export { Router };

package/src/source.ts

@@ -0,0 +1,258 @@
+import type { Change, Health } from "./health.ts";
+import { RETIRED_MS, STALE_MS, parseOwner, retiredName, sameOwner } from "./lock.ts";
+import { emptyHealth, parseHealth, updateHealth } from "./health.ts";
+import { mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import type { Owner } from "./lock.ts";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import path from "node:path";
+import process from "node:process";
+import { setTimeout } from "node:timers/promises";
+
+const ZERO = 0,
+  LOCK_WAIT = 25,
+  IO_TIMEOUT = 2000,
+  /**
+   * Recognizes a specific filesystem error without suppressing other failures.
+   * @param {unknown} error Failure.
+   * @param {string} code Expected code.
+   * @returns {boolean} Match.
+   */
+  hasCode = (error: unknown, code: string): boolean =>
+    error instanceof Error && "code" in error && error.code === code,
+  /**
+   * Reads optional JSON source.
+   * @param {string} file Path.
+   * @returns {Promise<string | undefined>} Source, absent only for missing files.
+   */
+  readOptional = async (file: string): Promise<string | undefined> => {
+    try {
+      return await readFile(file, "utf8");
+    } catch (error) {
+      if (hasCode(error, "ENOENT")) {
+        return undefined;
+      }
+      throw error;
+    }
+  },
+  /**
+   * Sleeps without retaining an abort listener after completion.
+   * @param {number} delay Milliseconds.
+   * @param {AbortSignal | undefined} signal Cancellation.
+   * @returns {Promise<void>} Completion.
+   */
+  wait = async (delay: number, signal?: AbortSignal): Promise<void> => {
+    await setTimeout(Math.max(ZERO, delay), undefined, { signal });
+  },
+  /**
+   * Probes process existence without treating permission failures as death.
+   * @param {number} pid Recorded process.
+   * @returns {boolean} Whether the process is gone.
+   */
+  dead = (pid: number): boolean => {
+    try {
+      process.kill(pid, ZERO);
+      return false;
+    } catch (error) {
+      return hasCode(error, "ESRCH");
+    }
+  },
+  /**
+   * Reads a complete generation, ignoring missing metadata during creation.
+   * @param {string} directory Lock directory.
+   * @returns {Promise<Owner | undefined>} Owner.
+   */
+  ownerAt = async (directory: string): Promise<Owner | undefined> => {
+    const source = await readOptional(path.join(directory, "owner.json"));
+    return source === undefined ? undefined : parseOwner(source);
+  },
+  /**
+   * Gives an abandoned empty directory stable metadata and a nonempty tombstone.
+   * @param {string} directory Lock directory.
+   * @returns {Promise<void>} Completion.
+   */
+  identifyAbandoned = async (directory: string): Promise<void> => {
+    try {
+      const details = await stat(directory);
+      if (Date.now() - details.mtimeMs > STALE_MS) {
+        await writeFile(
+          path.join(directory, "owner.json"),
+          JSON.stringify({ created_ms: Math.floor(details.mtimeMs), pid: process.pid }),
+          { flag: "wx" },
+        );
+      }
+    } catch (error) {
+      if (!hasCode(error, "ENOENT") && !hasCode(error, "EEXIST")) {
+        throw error;
+      }
+    }
+  },
+  /**
+   * Finds a stale generation, including interrupted directory creation.
+   * @param {string} directory Lock directory.
+   * @returns {Promise<Owner | undefined>} Stale owner.
+   */
+  staleOwner = async (directory: string): Promise<Owner | undefined> => {
+    const owner = await ownerAt(directory);
+    if (owner === undefined) {
+      await identifyAbandoned(directory);
+      return undefined;
+    }
+    return Date.now() - owner.created_ms > STALE_MS || dead(owner.pid) ? owner : undefined;
+  },
+  /**
+   * Retires only a stale, unchanged generation to its unique nonempty directory.
+   * @param {string} directory Lock directory.
+   * @returns {Promise<boolean>} Whether this waiter won retirement.
+   */
+  retire = async (directory: string): Promise<boolean> => {
+    const owner = await staleOwner(directory);
+    if (owner === undefined || !sameOwner(await ownerAt(directory), owner)) {
+      return false;
+    }
+    try {
+      await rename(directory, path.join(path.dirname(directory), retiredName(owner)));
+      return true;
+    } catch (error) {
+      if (hasCode(error, "ENOENT") || hasCode(error, "ENOTEMPTY") || hasCode(error, "EEXIST")) {
+        return false;
+      }
+      throw error;
+    }
+  },
+  /**
+   * Removes only retired directories outside the contention retention window.
+   * @param {string} directory State directory.
+   * @returns {Promise<void>} Completion.
+   */
+  cleanRetired = async (directory: string): Promise<void> => {
+    const entries = await readdir(directory, { withFileTypes: true });
+    await Promise.all(
+      entries
+        .filter(
+          (entry: Readonly<{ name: string; isDirectory: () => boolean }>) =>
+            entry.isDirectory() && /^retired-\d+-\d+$/u.test(entry.name),
+        )
+        .map(async (entry: Readonly<{ name: string }>) => {
+          const retired = path.join(directory, entry.name);
+          try {
+            const details = await stat(retired);
+            if (Date.now() - details.ctimeMs > RETIRED_MS) {
+              await rm(retired, { force: true, recursive: true });
+            }
+          } catch (error) {
+            if (!hasCode(error, "ENOENT")) {
+              throw error;
+            }
+          }
+        }),
+    );
+  },
+  /**
+   * Publishes complete owner metadata after exclusive directory creation.
+   * @param {string} directory Acquired directory.
+   * @returns {Promise<Owner>} Published generation.
+   */
+  publishOwner = async (directory: string): Promise<Owner> => {
+    const owner = { created_ms: Date.now(), pid: process.pid };
+    await writeFile(path.join(directory, "owner.tmp"), JSON.stringify(owner), { flag: "wx" });
+    await rename(path.join(directory, "owner.tmp"), path.join(directory, "owner.json"));
+    await cleanRetired(path.dirname(directory));
+    return owner;
+  },
+  /**
+   * Acquires a recoverable directory lock with a bounded wait.
+   * @param {string} directory Lock directory.
+   * @param {number} deadline Deadline.
+   * @returns {Promise<Owner>} Acquired generation.
+   */
+  acquire = async (directory: string, deadline: number): Promise<Owner> => {
+    try {
+      await mkdir(directory);
+    } catch (error) {
+      if (!hasCode(error, "EEXIST") || Date.now() >= deadline) {
+        throw error;
+      }
+      await retire(directory);
+      await wait(LOCK_WAIT);
+      return acquire(directory, deadline);
+    }
+    return publishOwner(directory);
+  },
+  /**
+   * Releases only the generation this transaction acquired.
+   * @param {string} directory Lock directory.
+   * @param {Owner} owner Acquired generation.
+   * @returns {Promise<void>} Completion.
+   */
+  release = async (directory: string, owner: Owner): Promise<void> => {
+    if (sameOwner(await ownerAt(directory), owner)) {
+      await rm(directory, { recursive: true });
+    }
+  };
+
+/** Atomic host-local circuit and cooldown persistence. */
+class Store {
+  readonly #directory: string;
+  readonly #file: string;
+
+  /**
+   * Selects the agent state directory.
+   * @param {string} directory State root.
+   */
+  public constructor(directory = path.join(getAgentDir(), "state", "pi-tiers")) {
+    this.#directory = directory;
+    this.#file = path.join(directory, "state.json");
+  }
+
+  /**
+   * Reads an atomic state snapshot.
+   * @returns {Promise<Health>} Current shared health.
+   */
+  public async read(): Promise<Health> {
+    const source = await readOptional(this.#file);
+    return source === undefined ? emptyHealth() : parseHealth(source);
+  }
+
+  /**
+   * Writes and syncs a temporary snapshot before atomic replacement.
+   * @param {Health} health New state.
+   * @returns {Promise<void>} Durable replacement.
+   */
+  async #write(health: Health): Promise<void> {
+    const temporary = path.join(this.#directory, `${crypto.randomUUID()}.tmp`),
+      file = await open(temporary, "wx");
+    try {
+      await file.writeFile(JSON.stringify(health));
+      await file.sync();
+      await rename(temporary, this.#file);
+    } finally {
+      await file.close();
+      await rm(temporary, { force: true });
+    }
+  }
+
+  /**
+   * Holds the lock across the entire read-modify-rename transaction.
+   * @param {Change} change Failure to record.
+   * @returns {Promise<void>} Durable completion.
+   */
+  public async change(change: Change): Promise<void> {
+    await mkdir(this.#directory, { recursive: true });
+    const lockPath = path.join(this.#directory, "lock"),
+      lock = await acquire(lockPath, Date.now() + IO_TIMEOUT);
+    try {
+      await this.#write(updateHealth(await this.read(), change));
+    } finally {
+      await release(lockPath, lock);
+    }
+  }
+}
+
+/**
+ * Reads the user-owned tier map.
+ * @returns {Promise<string | undefined>} Config source.
+ */
+const readConfig = async (): Promise<string | undefined> =>
+  readOptional(path.join(getAgentDir(), "tiers.json"));
+
+export { acquire, readConfig, release, retire, Store, wait };