@bivy/bivy 0.0.0 → 0.1.0-staging.2

package/dist/pairing-crypto.js

@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+import { generateKeyPairSync, createPublicKey, createPrivateKey, diffieHellman, hkdfSync, createHmac, randomBytes, timingSafeEqual, } from "node:crypto";
+import { seal, open } from "./e2e.js";
+import { HKDF_INFO, ROOM_KEY_BYTES, WRAP_KEY_BYTES, PAIR_SECRET_BYTES } from "./wire-format.js";
+/**
+ * Pairing crypto for the X25519 device-linking handshake (replaces shipping the
+ * room key inside the QR fragment).
+ *
+ * Design
+ * ------
+ * The node keeps a long-term X25519 identity keypair and a symmetric ROOM KEY
+ * used for bulk frame encryption (so the relay still broadcasts one ciphertext
+ * to all devices, exactly as before). Pairing establishes, per device, a stable
+ * "wrap key" via ECDH(node_priv, device_pub); the node delivers the current room
+ * key encrypted under that wrap key. The relay can route the wrapped key but
+ * cannot derive the wrap key (it holds neither private key).
+ *
+ * Authenticating the device's public key
+ * --------------------------------------
+ * The node's public key reaches the phone OUT OF BAND via the QR (a trusted
+ * screen), so the phone cannot be fooled about node identity. The phone's public
+ * key reaches the node OVER the relay, so a malicious relay could try to
+ * substitute its own. We bind the first exchange with a high-entropy
+ * `pairSecret` carried only in the QR (never over the relay): the phone proves
+ * knowledge of it with HMAC(pairSecret, device_pub). The relay never saw the QR,
+ * so it cannot forge the proof — at worst it can cause pairing to fail, never to
+ * leak the room key. After the first exchange the node stores the authentic
+ * device public key and can re-wrap future room keys (on revoke/rotate) without
+ * re-scanning.
+ *
+ * Wire encoding is base64url for all key material so it survives JSON/QR/URLs.
+ */
+const PAIR_INFO = Buffer.from(HKDF_INFO.pair);
+const ROTATE_INFO = Buffer.from(HKDF_INFO.rotate);
+const MODEL_AUTH_VAULT_INFO = Buffer.from(HKDF_INFO.modelAuthVault);
+const GITHUB_APP_VAULT_INFO = Buffer.from(HKDF_INFO.githubAppVault);
+const EMPTY_SALT = Buffer.alloc(0);
+/** Generate a fresh X25519 keypair (node identity or device ephemeral). */
+export function generatePairingKeypair() {
+    const { publicKey, privateKey } = generateKeyPairSync("x25519");
+    return {
+        publicKeyB64: rawPublicKey(publicKey).toString("base64url"),
+        privateKeyB64: privateKey.export({ type: "pkcs8", format: "der" }).toString("base64url"),
+    };
+}
+/** Raw 32-byte X25519 public key (the form WebCrypto exports/imports as "raw"). */
+function rawPublicKey(key) {
+    // JWK `x` is the base64url raw public key for OKP/X25519.
+    const jwk = key.export({ format: "jwk" });
+    if (!jwk.x)
+        throw new Error("could not export X25519 public key");
+    return Buffer.from(jwk.x, "base64url");
+}
+function publicKeyFromRaw(rawB64) {
+    return createPublicKey({
+        key: { kty: "OKP", crv: "X25519", x: rawB64 },
+        format: "jwk",
+    });
+}
+function privateKeyFromB64(privB64) {
+    return createPrivateKey({ key: Buffer.from(privB64, "base64url"), type: "pkcs8", format: "der" });
+}
+/**
+ * Derive the per-device wrap key. Identical on both ends because ECDH is
+ * symmetric: ECDH(node_priv, device_pub) === ECDH(device_priv, node_pub).
+ */
+export function deriveWrapKey(ourPrivateKeyB64, theirPublicKeyB64, purpose) {
+    const shared = diffieHellman({
+        privateKey: privateKeyFromB64(ourPrivateKeyB64),
+        publicKey: publicKeyFromRaw(theirPublicKeyB64),
+    });
+    const info = purpose === "pair" ? PAIR_INFO
+        : purpose === "rotate" ? ROTATE_INFO
+            : purpose === "github-app-vault" ? GITHUB_APP_VAULT_INFO
+                : MODEL_AUTH_VAULT_INFO;
+    return Buffer.from(hkdfSync("sha256", shared, EMPTY_SALT, info, WRAP_KEY_BYTES));
+}
+/** A fresh 32-byte symmetric room key. */
+export function generateRoomKey() {
+    return randomBytes(ROOM_KEY_BYTES);
+}
+/** A high-entropy single-use pairing secret carried only in the QR. */
+export function generatePairSecret() {
+    return randomBytes(PAIR_SECRET_BYTES).toString("base64url");
+}
+/** HMAC-SHA256(pairSecret, device_pub) — the phone's proof it holds the QR secret. */
+export function pairingProof(pairSecretB64, devicePublicKeyB64) {
+    return createHmac("sha256", Buffer.from(pairSecretB64, "base64url"))
+        .update(Buffer.from(devicePublicKeyB64, "base64url"))
+        .digest("base64url");
+}
+export function verifyPairingProof(pairSecretB64, devicePublicKeyB64, proofB64) {
+    const expected = pairingProof(pairSecretB64, devicePublicKeyB64);
+    const a = Buffer.from(expected, "base64url");
+    const b = Buffer.from(proofB64, "base64url");
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+/** Wrap (encrypt) the room key under a per-device wrap key for delivery. */
+export function wrapRoomKey(wrapKey, roomKey) {
+    return seal(wrapKey, roomKey.toString("base64"));
+}
+export function unwrapRoomKey(wrapKey, wrapped) {
+    return Buffer.from(open(wrapKey, wrapped), "base64");
+}

package/dist/policy/conditions.js

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// Typed runtime-failure conditions + a classifier.
+//
+// This is the load-bearing seam of policy-driven run orchestration: rules match
+// STABLE condition codes, never raw provider error strings. A raw failure (an
+// opaque `429`, a `credit balance is too low`, a socket hang-up) is classified
+// here exactly once into a `RuntimeCondition` plus whatever recovery metadata we
+// could recover (a `retryAfterMs`, a `resetsAt`), and every downstream rule,
+// evidence event, and effector speaks only that vocabulary. Add a new provider
+// quirk here and the whole policy layer understands it — no rule edits, no
+// regexes scattered through runtimes and the queue poller.
+import { isAnthropicAuthError } from "../runtime/anthropic-preflight.js";
+function rawText(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === "string")
+        return error;
+    try {
+        return JSON.stringify(error) ?? String(error);
+    }
+    catch {
+        return String(error);
+    }
+}
+/** Parse a "wait N" hint from a raw error into milliseconds, if present. */
+export function parseRetryAfterMs(raw) {
+    // `retry-after: 30` / `retry_after=30` (seconds, HTTP-style).
+    const header = /retry[\s_-]?after["'\s:=]+(\d{1,5})/i.exec(raw);
+    if (header?.[1])
+        return Number(header[1]) * 1000;
+    // "try again in 12 seconds" / "retry in 5 minutes".
+    const phrase = /(?:try again|retry)\s+in\s+(\d{1,5})\s*(ms|s|sec|second|m|min|minute|h|hour)/i.exec(raw);
+    if (phrase?.[1]) {
+        const n = Number(phrase[1]);
+        const unit = phrase[2].toLowerCase();
+        if (unit === "ms")
+            return n;
+        if (unit.startsWith("h"))
+            return n * 3_600_000;
+        if (unit.startsWith("m") && unit !== "ms")
+            return n * 60_000;
+        return n * 1000;
+    }
+    return undefined;
+}
+/** Parse an ISO reset timestamp (e.g. `resets_at: 2026-07-27T18:00:00Z`). */
+export function parseResetsAt(raw) {
+    const iso = /(20\d\d-\d\d-\d\dT[\d:.]+(?:Z|[+-]\d\d:?\d\d))/.exec(raw);
+    return iso?.[1];
+}
+// Ordered classifiers: the FIRST match wins, so more-specific/actionable
+// conditions are tested before broader ones (auth 401 before generic HTTP
+// noise; explicit billing/quota before a bare rate-limit; context-window before
+// a generic "too long").
+const CLASSIFIERS = [
+    { condition: "auth_failed", test: (r) => isAnthropicAuthError(r) },
+    {
+        condition: "credits_exhausted",
+        test: (r) => /\b402\b|payment required|insufficient\s+(?:credit|quota|balance|funds)|credit balance (?:is )?too low|quota (?:exceeded|exhausted)|billing|(?:usage|session) limit (?:reached|hit)|(?:you(?:'ve| have)\s+)?hit your limit|out of credits|plan (?:limit|allowance)/i.test(r),
+    },
+    {
+        condition: "rate_limited",
+        test: (r) => /\b429\b|\b529\b|rate[\s_-]?limit|too many requests|overloaded/i.test(r),
+    },
+    {
+        condition: "context_overflow",
+        test: (r) => /context[\s_-]?(?:length|window|limit)|maximum context|prompt is too long|too many tokens|exceeds?\b[^.]*\btokens?\b/i.test(r),
+    },
+    {
+        condition: "node_offline",
+        test: (r) => /ECONNREFUSED|EHOSTUNREACH|ENETUNREACH|no route to host|node (?:is )?offline|host unreachable/i.test(r),
+    },
+    {
+        condition: "transport_error",
+        test: (r) => /ETIMEDOUT|ECONNRESET|EPIPE|EAI_AGAIN|ENOTFOUND|socket hang ?up|network (?:error|timeout)|fetch failed|timed? ?out|temporarily unavailable|\b50[234]\b/i.test(r),
+    },
+    {
+        condition: "task_failed",
+        test: (r) => /tests? failed|checks? failed|no progress|made no changes|nothing to commit|assertion/i.test(r),
+    },
+];
+/**
+ * Classify a raw runtime failure into a stable `RuntimeCondition` plus any
+ * recovery metadata. Unmatched failures are `"unknown"` — deliberately left for
+ * a human rather than blindly retried.
+ */
+export function classifyFailure(error) {
+    const raw = rawText(error).slice(0, 2000);
+    const condition = CLASSIFIERS.find((c) => c.test(raw))?.condition ?? "unknown";
+    const out = { condition, raw };
+    // Recovery hints are only meaningful for the wait-and-retry conditions.
+    if (condition === "rate_limited" || condition === "credits_exhausted") {
+        const retryAfterMs = parseRetryAfterMs(raw);
+        if (retryAfterMs !== undefined)
+            out.retryAfterMs = retryAfterMs;
+        const resetsAt = parseResetsAt(raw);
+        if (resetsAt !== undefined)
+            out.resetsAt = resetsAt;
+    }
+    return out;
+}

package/dist/policy/policy-engine.js

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+import { guardToolCall } from "../guard.js";
+import { riskCategoryForTool } from "./risk.js";
+/** Runtime-agnostic policy decision layer. Strong runtimes call this before tools.
+ *  Persistent "remembered decisions" were removed — the engine now only applies
+ *  the mode-based guard floor; governance beyond that is left to the agents. */
+export class PolicyEngine {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    decideToolCall(workspace, toolName, input) {
+        const risk = riskCategoryForTool(toolName);
+        if (this.options.unrestricted)
+            return { decision: "allow", risk };
+        const base = guardToolCall(workspace, toolName, input, this.options.mode, this.options.isRiskyIntegration ?? (() => false));
+        return { ...base, risk };
+    }
+}

package/dist/policy/risk.js

@@ -0,0 +1,18 @@
+export function riskCategoryForTool(toolName) {
+    const tool = toolName.toLowerCase();
+    if (["write", "edit", "multi_edit", "patch"].includes(tool))
+        return "filesystem";
+    if (["bash", "shell", "terminal"].includes(tool))
+        return "shell";
+    if (tool.includes("git") || tool.includes("github"))
+        return "git.write";
+    if (tool.includes("secret") || tool.includes("credential") || tool.includes("token"))
+        return "secret.read";
+    if (tool.includes("stripe") || tool.includes("payment"))
+        return "payment";
+    if (tool.includes("deploy") || tool.includes("release"))
+        return "deploy";
+    if (tool.includes("http") || tool.includes("fetch") || tool.includes("curl"))
+        return "network.write";
+    return "unknown";
+}

package/dist/policy/ruleset.js

@@ -0,0 +1,113 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// The ruleset schema + validator + the pure matcher.
+//
+// A ruleset is user-authored policy: which failures are recoverable, how to
+// recover (retry / reroute through a fallback chain / park for a human), and the
+// bounds (max attempts, backoff). It is validated once with typebox into a
+// versioned in-memory shape — we never execute arbitrary YAML expressions — and
+// the same ruleset serves both the interactive session and the work queue,
+// gated by `appliesTo`. The MATCHER here is pure: `(ruleset, condition,
+// context) → Rule | undefined`. How the chosen rule is carried out lives in the
+// context-specific effectors (see run-policy.ts for the queue effector).
+import { Type } from "typebox";
+import { Check, Errors } from "typebox/value";
+// ── Schema (typebox) ────────────────────────────────────────────────────────
+// Declared with typebox so a ruleset loaded from disk/YAML is validated before
+// it can steer a live run. Kept intentionally small for v1: the reroute slice.
+// The literals are spelled out (not mapped) so typebox infers the union type.
+const ConditionSchema = Type.Union([
+    Type.Literal("rate_limited"),
+    Type.Literal("credits_exhausted"),
+    Type.Literal("context_overflow"),
+    Type.Literal("auth_failed"),
+    Type.Literal("node_offline"),
+    Type.Literal("transport_error"),
+    Type.Literal("task_failed"),
+    Type.Literal("unknown"),
+]);
+const RoutingCandidateSchema = Type.Object({
+    runtimeId: Type.Optional(Type.String()),
+    model: Type.Optional(Type.String()),
+    /** Provider/account id to route through — matched against configured creds. */
+    account: Type.Optional(Type.String()),
+    /** Human-readable label for evidence, if none is derivable. */
+    label: Type.Optional(Type.String()),
+}, { additionalProperties: false });
+const BackoffSchema = Type.Object({
+    baseMs: Type.Integer({ minimum: 0 }),
+    factor: Type.Number({ minimum: 1 }),
+    capMs: Type.Integer({ minimum: 0 }),
+    jitter: Type.Number({ minimum: 0, maximum: 1 }),
+}, { additionalProperties: false });
+const RuleSchema = Type.Object({
+    when: Type.Array(ConditionSchema, { minItems: 1 }),
+    action: Type.Union([Type.Literal("retry"), Type.Literal("reroute"), Type.Literal("park")]),
+    /** Ordered fallback candidates for `reroute`; first with valid creds wins. */
+    chain: Type.Optional(Type.Array(RoutingCandidateSchema)),
+    /** What to do when retries/chain are exhausted. Defaults to `park`. */
+    onExhausted: Type.Optional(Type.Union([Type.Literal("park"), Type.Literal("give_up")])),
+    maxAttempts: Type.Integer({ minimum: 1, maximum: 100 }),
+    backoff: Type.Optional(BackoffSchema),
+}, { additionalProperties: false });
+export const RulesetSchema = Type.Object({
+    /** Schema version — lets stored rulesets migrate without silent misreads. */
+    version: Type.Literal(1),
+    name: Type.String({ minLength: 1 }),
+    appliesTo: Type.Array(Type.Union([Type.Literal("session"), Type.Literal("queue")]), { minItems: 1 }),
+    rules: Type.Array(RuleSchema),
+}, { additionalProperties: false });
+/** Backoff used when a retry/reroute rule doesn't specify one. Mirrors the
+ *  reconnect layer's defaults (see src/session/reconnect.ts BackoffOptions). */
+export const DEFAULT_BACKOFF = { baseMs: 2000, factor: 2, capMs: 60_000, jitter: 0.3 };
+/**
+ * The built-in default ruleset — deliberately SAFE, not clever.
+ *
+ * Infra hiccups (transient transport, provider rate-limits) retry with backoff;
+ * quota/auth/context failures are PARKED for a human (we can't presume a valid
+ * fallback model or account for an arbitrary node); genuine task failures and
+ * anything unclassified fall through to the caller's existing failure path.
+ * Reroute + fallback chains are fully supported (see run-policy.ts) but opt-in:
+ * author a rule with a `chain` to enable cross-account/model/provider fallback.
+ */
+export const DEFAULT_RULESET = {
+    version: 1,
+    name: "default",
+    appliesTo: ["queue", "session"],
+    rules: [
+        { when: ["transport_error", "node_offline"], action: "retry", maxAttempts: 3, backoff: DEFAULT_BACKOFF },
+        {
+            when: ["rate_limited"],
+            action: "retry",
+            maxAttempts: 4,
+            backoff: { baseMs: 5000, factor: 2, capMs: 120_000, jitter: 0.3 },
+        },
+        { when: ["credits_exhausted"], action: "park", maxAttempts: 1 },
+        { when: ["context_overflow"], action: "park", maxAttempts: 1 },
+        { when: ["auth_failed"], action: "park", maxAttempts: 1 },
+    ],
+};
+/**
+ * Validate an untrusted value (e.g. parsed from a user's YAML/JSON) against the
+ * ruleset schema. Returns the typed ruleset on success, or a bounded list of
+ * human-readable errors — never throws.
+ */
+export function validateRuleset(value) {
+    if (Check(RulesetSchema, value))
+        return { ok: true, ruleset: value, errors: [] };
+    const errors = [...Errors(RulesetSchema, value)]
+        .slice(0, 20)
+        .map((e) => `${e.path || "/"}: ${e.message}`);
+    return { ok: false, errors: errors.length ? errors : ["ruleset did not match the expected shape"] };
+}
+/**
+ * The pure matcher: the first rule that applies to `context` and lists
+ * `condition` in its `when`. Undefined means "no policy for this failure" — the
+ * caller keeps its existing behavior (e.g. fail the run).
+ */
+export function findRule(ruleset, condition, context) {
+    if (!ruleset.appliesTo.includes(context))
+        return undefined;
+    return ruleset.rules.find((rule) => rule.when.includes(condition));
+}

package/dist/policy/run-policy.js

@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// Run policy: the pure decision layer the queue effector drives.
+//
+// Given a failed attempt (its current routing, the raw error, the attempt count,
+// and how many reroutes have already been applied), it classifies the failure,
+// finds the matching rule, and returns ONE decision: retry (with a backoff
+// delay), reroute (to the next credentialed candidate in the rule's chain), park
+// (hand to a human), or give_up (no policy — keep the caller's existing
+// behavior). It touches no I/O and no clock beyond an injectable `random`, so
+// it's fully deterministic and unit-testable. The poller (src/control-plane-
+// tasks.ts) is the effector that carries the decision out on the live run.
+import { classifyFailure } from "./conditions.js";
+import { DEFAULT_BACKOFF, DEFAULT_RULESET, findRule, } from "./ruleset.js";
+/** `min(cap, base·factor^n)` spread by ±jitter/2 — the reconnect-layer formula. */
+export function computeBackoffMs(cfg, n, random) {
+    const raw = Math.min(cfg.capMs, cfg.baseMs * Math.pow(cfg.factor, n));
+    const spread = raw * cfg.jitter * (random() - 0.5);
+    return Math.max(0, Math.round(raw + spread));
+}
+function candidateRef(c) {
+    return (c.label ||
+        [c.runtimeId, c.model, c.account && `@${c.account}`].filter(Boolean).join(" / ") ||
+        "fallback route");
+}
+/** Build a run policy bound to a ruleset. Stateless: all per-run state (attempt,
+ *  rerouteCount) is passed in, so one instance safely serves every run. */
+export function createRunPolicy(deps = {}) {
+    const ruleset = deps.ruleset ?? DEFAULT_RULESET;
+    const context = deps.context ?? "queue";
+    const hasCredential = deps.hasCredential ?? (() => true);
+    const random = deps.random ?? Math.random;
+    const now = deps.now ?? Date.now;
+    return {
+        decide(ctx) {
+            const classified = classifyFailure(ctx.error);
+            const { condition } = classified;
+            const rule = findRule(ruleset, condition, context);
+            if (!rule)
+                return { action: "give_up", condition };
+            const exhausted = ctx.attempt >= rule.maxAttempts;
+            const nextAttempt = ctx.attempt + 1;
+            const backoff = rule.backoff ?? DEFAULT_BACKOFF;
+            // A provider-supplied reset is the most precise recovery time. This is
+            // especially important for session/usage limits: retrying with ordinary
+            // backoff before the window resets only burns attempts. A relative
+            // Retry-After is the next-best hint; otherwise use authored backoff.
+            const resetAtMs = classified.resetsAt === undefined ? undefined : Date.parse(classified.resetsAt);
+            const resetDelayMs = resetAtMs !== undefined && Number.isFinite(resetAtMs)
+                ? Math.max(0, resetAtMs - now())
+                : undefined;
+            const delayMs = resetDelayMs ?? classified.retryAfterMs ?? computeBackoffMs(backoff, ctx.attempt - 1, random);
+            const onExhausted = () => rule.onExhausted === "give_up"
+                ? { action: "give_up", condition }
+                : {
+                    action: "park",
+                    condition,
+                    summary: `${condition}: no recovery left after ${ctx.attempt} attempt(s) — needs attention.`,
+                };
+            if (rule.action === "park") {
+                return { action: "park", condition, summary: `${condition}: parked for a human — no automatic recovery.` };
+            }
+            if (rule.action === "retry") {
+                if (exhausted)
+                    return onExhausted();
+                const wait = Math.round(delayMs / 1000);
+                const timing = resetDelayMs !== undefined && classified.resetsAt
+                    ? ` when the limit resets at ${classified.resetsAt}`
+                    : wait ? ` in ~${wait}s` : "";
+                return {
+                    action: "retry",
+                    delayMs,
+                    condition,
+                    summary: `${condition}: transient — retrying (attempt ${nextAttempt}/${rule.maxAttempts})${timing}.`,
+                };
+            }
+            // action === "reroute": walk the chain from the current cursor, skipping
+            // any candidate we can prove lacks credentials on this node, or that is a
+            // no-op (a pure model change equal to the model we're already on).
+            const chain = rule.chain ?? [];
+            const isNoop = (c) => c.model !== undefined && c.model === ctx.routing.model && c.runtimeId === undefined && c.account === undefined;
+            let cursor = ctx.rerouteCount;
+            while (cursor < chain.length && (!hasCredential(chain[cursor]) || isNoop(chain[cursor])))
+                cursor += 1;
+            if (exhausted || cursor >= chain.length)
+                return onExhausted();
+            const candidate = chain[cursor];
+            const routing = {};
+            if (candidate.runtimeId !== undefined)
+                routing.runtimeId = candidate.runtimeId;
+            if (candidate.model !== undefined)
+                routing.model = candidate.model;
+            if (candidate.account !== undefined)
+                routing.account = candidate.account;
+            const ref = candidateRef(candidate);
+            return {
+                action: "reroute",
+                delayMs,
+                condition,
+                routing,
+                ref,
+                rerouteCount: cursor + 1,
+                summary: `${condition}: rerouting to ${ref} (attempt ${nextAttempt}).`,
+            };
+        },
+    };
+}

package/dist/policy/session-reroute.js

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// Session effector — in-session model reroute.
+//
+// The queue effector (src/control-plane-tasks.ts) reruns a failed item under the
+// run policy. This is the interactive-session counterpart, scoped to the ONE
+// action a live session can take fully in-place: swapping the model. When a turn
+// ends in a recoverable error (credits exhausted, rate-limited) and the session
+// ruleset says `reroute` down a model chain, this swaps the model via the
+// runtime's `setModel` and re-sends the same prompt — so the session continues on
+// a cheaper/other model instead of surfacing an error.
+//
+// It deliberately does NOT handle agent (runtime) or node reroutes: those are
+// forks / standby promotions (new session identity, possibly reduced fidelity),
+// not in-place swaps — a separate, heavier effector (see docs/rulesets.md). A
+// chain candidate that changes anything other than the model is skipped here and
+// the error is left to surface.
+//
+// The decision is SYNCHRONOUS (`planReroute`) so the caller can atomically decide
+// whether to suppress the turn's error toast before kicking off the async swap +
+// retry (`applyReroute`). Reroute happens only at the turn boundary, so there is
+// no partial-work hazard.
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export class SessionRerouteController {
+    deps;
+    attempt = 1;
+    rerouteCount = 0;
+    applying = false;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Reset the reroute budget at the start of each new user-initiated turn. */
+    beginTurn() {
+        this.attempt = 1;
+        this.rerouteCount = 0;
+    }
+    /**
+     * Synchronously decide whether this turn error should become an in-place model
+     * reroute. Returns a plan (the caller should suppress the error toast and call
+     * `applyReroute`) or null (let the error surface as usual). Pure w.r.t. the
+     * controller's counters — those advance only when the plan is applied.
+     */
+    planReroute(rawError, currentModel) {
+        if (this.applying)
+            return null;
+        const decision = this.deps.policy.decide({
+            routing: { model: currentModel },
+            error: rawError,
+            attempt: this.attempt,
+            rerouteCount: this.rerouteCount,
+        });
+        if (decision.action !== "reroute")
+            return null;
+        const model = decision.routing.model;
+        // Only a MODEL change is applicable in-session; a chain candidate that swaps
+        // agent/account/node (or is a no-op) is left to surface / a future effector.
+        if (!model || model === currentModel)
+            return null;
+        return {
+            model,
+            condition: decision.condition,
+            summary: decision.summary,
+            delayMs: decision.delayMs,
+            rerouteCount: decision.rerouteCount,
+        };
+    }
+    /** Apply a plan: swap the model and re-drive the turn. Best-effort; on a failed
+     *  swap it reports via `onFailed` rather than throwing. */
+    async applyReroute(plan, target) {
+        if (this.applying)
+            return;
+        this.applying = true;
+        try {
+            this.deps.onEvent?.({ kind: "fallback", summary: plan.summary });
+            this.deps.onNotice?.({
+                level: "info",
+                message: `Switching to ${plan.model} after ${plan.condition.replace(/_/g, " ")}, then retrying…`,
+            });
+            if (plan.delayMs > 0)
+                await (this.deps.sleep ?? defaultSleep)(plan.delayMs);
+            await target.setModel("", plan.model);
+            this.deps.onModelChanged?.();
+            this.attempt += 1;
+            this.rerouteCount = plan.rerouteCount;
+            await target.reprompt();
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.deps.onFailed?.(`Couldn't reroute to ${plan.model}: ${message}`);
+        }
+        finally {
+            this.applying = false;
+        }
+    }
+}

package/dist/pty-runner.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+"""Run a command under a pseudo-terminal while relaying stdio over pipes."""
+
+import os
+import pty
+import select
+import signal
+import subprocess
+import sys
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        print("usage: pty-runner.py command [args...]", file=sys.stderr)
+        return 2
+
+    master_fd, slave_fd = pty.openpty()
+    env = os.environ.copy()
+    env.setdefault("TERM", "xterm-256color")
+
+    proc = subprocess.Popen(
+        sys.argv[1:],
+        stdin=slave_fd,
+        stdout=slave_fd,
+        stderr=slave_fd,
+        env=env,
+        close_fds=True,
+        start_new_session=True,
+    )
+    os.close(slave_fd)
+
+    def forward_signal(signum, _frame):
+        try:
+            os.killpg(proc.pid, signum)
+        except ProcessLookupError:
+            pass
+
+    signal.signal(signal.SIGINT, forward_signal)
+    signal.signal(signal.SIGTERM, forward_signal)
+
+    stdin_fd = sys.stdin.fileno()
+    stdout_fd = sys.stdout.fileno()
+    stdin_open = True
+
+    while True:
+        read_fds = [master_fd]
+        if stdin_open:
+            read_fds.append(stdin_fd)
+
+        readable, _, _ = select.select(read_fds, [], [], 0.1)
+
+        if master_fd in readable:
+            try:
+                data = os.read(master_fd, 8192)
+            except OSError:
+                data = b""
+            if not data:
+                break
+            os.write(stdout_fd, data)
+
+        if stdin_open and stdin_fd in readable:
+            data = os.read(stdin_fd, 8192)
+            if not data:
+                stdin_open = False
+            else:
+                try:
+                    os.write(master_fd, data)
+                except OSError:
+                    break
+
+        if proc.poll() is not None:
+            # Drain any final PTY output.
+            while True:
+                readable, _, _ = select.select([master_fd], [], [], 0)
+                if not readable:
+                    break
+                try:
+                    data = os.read(master_fd, 8192)
+                except OSError:
+                    break
+                if not data:
+                    break
+                os.write(stdout_fd, data)
+            break
+
+    try:
+        os.close(master_fd)
+    except OSError:
+        pass
+
+    return proc.wait()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())