diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 26a53785..c5919573 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -94,9 +94,10 @@ jobs:
test:
name: unit + e2e (macOS)
runs-on: macos-latest
- # Green runs on shared runners take 20–29 minutes, the e2e step alone 16–22 (2026-10-18), so 30
- # cut off slow but passing runs. 45 leaves room without letting a hung run sit for long.
- timeout-minutes: 45
+ # Green runs on shared runners took 29–45 minutes on 2026-11-12, the e2e step alone 25–37 of
+ # them, and 45 cut off three passing runs in a row (two of them in the merge queue). 70 leaves
+ # room for a slow runner without letting a hung run sit for long.
+ timeout-minutes: 70
steps:
- uses: actions/checkout@v5
@@ -143,6 +144,9 @@ jobs:
- name: Landing page release and responsive tests
run: pnpm --filter @modex/site test:e2e
+ - name: Browser demo workspace tests
+ run: pnpm --filter @modex/web test:e2e
+
- name: Desktop runner memory low point
if: always()
run: apps/ios/ModexCompanion/Scripts/sample-memory.sh --summary "$RUNNER_TEMP/modex-desktop-memory.log"
@@ -164,6 +168,7 @@ jobs:
path: |
apps/desktop/test-results
apps/site/test-results
+ apps/web/test-results
if-no-files-found: ignore
retention-days: 7
diff --git a/AGENTS.md b/AGENTS.md
index b1bfd861..1d094e2c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -53,6 +53,9 @@ itself driving one of them.
- `apps/desktop` — the Electron app (`src/main` process + backends, `src/renderer` React UI,
`e2e/` Playwright). `packages/core` — the offline scripted engine used by demos and tests.
+- `apps/site` — the landing page at modex.codes. `apps/web` — the renderer in a browser at
+ app.modex.codes, on an in-memory demo workspace only: it runs no model, CLI, shell or file
+ operation and makes no request beyond its own origin. Keep it that way.
- `docs/release-signing.md` — how release builds are signed and notarized, and where the
credentials live (never in the tree). `pnpm --filter @modex/desktop dist` stays ad-hoc for
everyday builds.
diff --git a/apps/desktop/e2e/code-review-enablement.spec.ts b/apps/desktop/e2e/code-review-enablement.spec.ts
index 5e1804bc..479cd755 100644
--- a/apps/desktop/e2e/code-review-enablement.spec.ts
+++ b/apps/desktop/e2e/code-review-enablement.spec.ts
@@ -4,8 +4,8 @@ import { tid } from "./support.js";
import { baseWorld, launchWithGh, prRow, type Harness } from "./code-review-support.js";
/**
- * The Code Review setting (#319, #327): hidden by default in a built app until its gates pass, shown from Settings →
- * General or by the old switch's "on". Turning it off hides the surface; it does not touch main's records.
+ * The Code Review setting (#319, #327): shown by default in built apps. Settings → General and the old
+ * switch preserve an explicit choice to hide the surface; turning it off does not touch main's records.
*/
let h: Harness;
test.afterEach(async () => { await h?.close(); });
@@ -16,20 +16,23 @@ async function general() {
return tid(h.page, "code-review-in-rail");
}
-test("Code Review is hidden by default: the rail leaves it out, makes no gh read, and Settings can show it", async () => {
+test("Code Review is visible by default without a switch, stays idle until opened, and survives a reload", async () => {
h = await launchWithGh(baseWorld(), { showCodeReview: false });
const { page } = h;
await expect(tid(page, "open-settings")).toBeVisible();
- await expect(tid(page, "rail-code-review")).toHaveCount(0);
+ await expect(tid(page, "rail-code-review")).toBeVisible();
+ expect(await page.evaluate(() => localStorage.getItem("modex.codeReview"))).toBeNull();
const box = await general();
- await expect(box).not.toBeChecked();
+ await expect(box).toBeChecked();
expect(h.calls().filter((call) => call.includes("search"))).toEqual([]);
- await box.check();
await page.keyboard.press("Escape");
await tid(page, "rail-code-review").click();
await expect(prRow(page, "example-org/lending#73")).toBeVisible();
await page.reload();
await expect(tid(page, "rail-code-review")).toBeVisible();
+ // The app checks its installed CLIs during this test (version checks and Codex's app-server); what must not start is a model turn.
+ expect(h.providerStarts().filter((start) => /^claude .*-p\b/.test(start) || /^codex exec\b/.test(start))).toEqual([]);
+ expect(h.posts()).toEqual([]);
});
test("turning it off is the rollback: the surface leaves at once, survives a relaunch, keeps a draft, and can come back", async () => {
diff --git a/apps/desktop/e2e/code-review-support.ts b/apps/desktop/e2e/code-review-support.ts
index 3d9bb5cd..7495da96 100644
--- a/apps/desktop/e2e/code-review-support.ts
+++ b/apps/desktop/e2e/code-review-support.ts
@@ -77,7 +77,7 @@ export async function launchWithGh(initial: GhWorld, options: { showCodeReview?:
// Row ages and captures read the renderer's clock: pin it to the fixtures' (test/fixtures/code-review.ts NOW).
await page.clock.setFixedTime(new Date("2026-10-18T20:41:00Z"));
await page.reload();
- // Built apps hide Code Review by default (e2e/code-review-enablement.spec.ts); these specs test the workspace itself.
+ // Workspace fixtures keep the legacy opt-in; the enablement spec omits it to exercise the built app's default.
if (options.showCodeReview !== false) await page.evaluate(() => localStorage.setItem("modex.codeReview", "on"));
await page.reload();
// Settings is always in the rail, whether or not Code Review's button is.
diff --git a/apps/desktop/e2e/credit-conservation.spec.ts b/apps/desktop/e2e/credit-conservation.spec.ts
new file mode 100644
index 00000000..da51de0c
--- /dev/null
+++ b/apps/desktop/e2e/credit-conservation.spec.ts
@@ -0,0 +1,36 @@
+import { test, expect } from "@playwright/test";
+import fs from "node:fs";
+import path from "node:path";
+import { appDir, launch, seedHome, tid } from "./support";
+
+test("automatic credit conservation defaults on, thresholds save, and disabling persists", async () => {
+ const { home } = seedHome();
+ const { app, page } = await launch(home);
+ try {
+ const open = async () => {
+ await tid(page, "open-settings").click();
+ await tid(page, "settings-nav").getByRole("button", { name: "Auto routing", exact: true }).click();
+ };
+ await open();
+ const enabled = tid(page, "conserve-credits"), percent = tid(page, "low-quota-percent"), balance = tid(page, "low-credit-balance");
+ await expect(enabled).toBeChecked();
+ await expect(percent).toHaveValue("20");
+ await expect(balance).toHaveValue("10");
+ await percent.fill("25");
+ await balance.fill("5");
+ await page.getByText("Conservation chooses economical models", { exact: false }).scrollIntoViewIfNeeded();
+ await page.screenshot({ path: path.join(appDir, "test-results", "credit-conservation-settings.png") });
+ await tid(page, "settings").getByRole("button", { name: "Save", exact: true }).click();
+ await open();
+ await expect(percent).toHaveValue("25");
+ await expect(balance).toHaveValue("5");
+ await enabled.uncheck();
+ await tid(page, "settings").getByRole("button", { name: "Save", exact: true }).click();
+ await open();
+ await expect(enabled).not.toBeChecked();
+ await expect(percent).toBeDisabled();
+ await expect(balance).toBeDisabled();
+ const saved = JSON.parse(fs.readFileSync(path.join(home, "app", "state.json"), "utf8")).settings.routing;
+ expect([saved.conserve_credits, saved.low_quota_percent, saved.low_credit_balance]).toEqual([false, 25, 5]);
+ } finally { await app.close(); }
+});
diff --git a/apps/desktop/e2e/fixtures/local-model-preservation.mjs b/apps/desktop/e2e/fixtures/local-model-preservation.mjs
new file mode 100644
index 00000000..d519b352
--- /dev/null
+++ b/apps/desktop/e2e/fixtures/local-model-preservation.mjs
@@ -0,0 +1,29 @@
+// Observer-only entry point for disposable, scripted preservation tests. Never packaged.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+if (process.env.MODEX_E2E !== "1" || process.env.MODEX_LM_NATIVE_E2E === "1") throw new Error("Preservation fixture requires scripted E2E mode.");
+const home = fs.realpathSync(process.env.MODEX_HOME ?? "");
+if (!home.startsWith(fs.realpathSync(os.tmpdir()) + path.sep) || !path.basename(home).startsWith("modex-e2e-home-") || JSON.parse(fs.readFileSync(path.join(home, "app/state.json"), "utf8")).settings.default_backend !== "mock") throw new Error("Preservation fixture requires a disposable mock home.");
+import { LocalModelDiscovery } from "../../dist/src/main/engine/local-models/discovery.js";
+globalThis.__lm4DiscoveryResults = [];
+globalThis.__lm4DiscoveryStarts = [];
+const discover = LocalModelDiscovery.prototype.discover;
+LocalModelDiscovery.prototype.discover = async function (ref, requestId) {
+ globalThis.__lm4DiscoveryStarts.push({ connection: { ...ref }, requestId });
+ const result = await discover.call(this, ref, requestId);
+ globalThis.__lm4DiscoveryResults.push({ connection: { ...ref }, requestId, state: result.state });
+ return result;
+};
+
+
+import { LocalExecution } from "../../dist/src/main/engine/local-models/execution.js";
+import { ThreadRunner } from "../../dist/src/main/engine/runner.js";
+globalThis.__lm4Calls = { localStarts: 0, sends: 0, durableSends: 0, retries: 0 };
+const start = LocalExecution.prototype.start;
+LocalExecution.prototype.start = function (...args) { globalThis.__lm4Calls.localStarts++; return start.apply(this, args); };
+for (const [method, key] of [["send", "sends"], ["sendDurably", "durableSends"], ["retry", "retries"]]) {
+ const original = ThreadRunner.prototype[method];
+ ThreadRunner.prototype[method] = function (...args) { globalThis.__lm4Calls[key]++; return original.apply(this, args); };
+}
+await import("./local-model-workflow.mjs");
diff --git a/apps/desktop/e2e/local-model-preservation.spec.ts b/apps/desktop/e2e/local-model-preservation.spec.ts
new file mode 100644
index 00000000..10c47fb8
--- /dev/null
+++ b/apps/desktop/e2e/local-model-preservation.spec.ts
@@ -0,0 +1,121 @@
+// #381 metadata races through production IPC/store/renderer with the existing scripted native fixture.
+// These cases request no coding turns and do not qualify ordinary product admission or real models.
+import { test, expect, _electron as electron, type ElectronApplication } from "@playwright/test";
+import fs from "node:fs";
+import { execFileSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+import path from "node:path";
+import http from "node:http";
+import crypto from "node:crypto";
+import type { AddressInfo } from "node:net";
+import { appDir, seedHome, tid } from "./support.js";
+
+const PNG_B64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
+const sha = (bytes: Buffer) => crypto.createHash("sha256").update(bytes).digest("hex");
+async function runtime(model: string) {
+ let current = model, hold = false, release: (() => void) | undefined;
+ let arrived!: () => void;
+ const barrier = new Promise(resolve => { arrived = resolve; });
+ const hits: Array<{ method?: string; url?: string; auth: boolean }> = [];
+ const server = http.createServer((req, res) => {
+ hits.push({ method: req.method, url: req.url, auth: Boolean(req.headers.authorization) });
+ req.resume(); res.setHeader("content-type", "application/json");
+ const tags = () => res.end(JSON.stringify({ models: [{ name: current, details: { family: "qwen3moe" } }] }));
+ if (req.url === "/api/tags") {
+ if (hold) { hold = false; release = () => { current = "Late/Alpha:Q4_0"; if (!res.destroyed) tags(); }; arrived(); }
+ else tags();
+ } else if (req.url === "/api/ps") res.end(JSON.stringify({ models: [] }));
+ else if (req.url === "/api/show") res.end(JSON.stringify({ capabilities: ["completion", "tools"], model_info: { "qwen3moe.context_length": 65536 } }));
+ else { res.writeHead(404); res.end(); }
+ });
+ await new Promise(resolve => server.listen(0, "127.0.0.1", resolve));
+ return { hits, url: `http://127.0.0.1:${(server.address() as AddressInfo).port}`, hold: () => { hold = true; }, barrier, release: () => release?.(), stop: async () => { release?.(); server.closeAllConnections(); await new Promise(resolve => server.close(() => resolve())); } };
+}
+
+test("delayed metadata preserves two thread drafts, image bytes, target and search focus", async ({}, testInfo) => {
+ const receipt = testInfo.outputPath("local-model-preservation.json");
+ expect(fs.existsSync(receipt)).toBe(false);
+ const out: Record = { startedAt: new Date().toISOString(), gitHeadAtRun: execFileSync("git", ["rev-parse", "HEAD"], { cwd: appDir, encoding: "utf8" }).trim(), scope: "existing temporary-home scripted LocalExecution bootstrap; production IPC/store/renderer; no real model or product admission", state: "started" };
+ const persist = () => fs.writeFileSync(receipt, JSON.stringify(out, null, 2) + "\n"); persist();
+ let app: ElectronApplication | undefined;
+ let alpha: Awaited> | undefined, beta: Awaited> | undefined;
+ try {
+ alpha = await runtime("Fixture/Alpha:Q4_0"); beta = await runtime("Fixture/Beta:Q4_0");
+ const { home } = seedHome();
+ app = await electron.launch({ args: [path.join(appDir, "e2e/fixtures/local-model-preservation.mjs")], cwd: appDir, env: { ...process.env, MODEX_HOME: home, MODEX_E2E: "1", MODEX_E2E_NODE: process.execPath, MODEX_LM_NATIVE_E2E: "", MODEX_LM3_LIVE: "", MODEX_LM3_WIRE: "", MODEX_NO_LOGIN_PATH: "1", TYPESAFE_API_KEY: "", JEV_API_KEY: "" } });
+ out.mainPid = app.process().pid; persist();
+ const page = await app.firstWindow(); await page.waitForLoadState("domcontentloaded");
+ await expect(tid(page, "composer-input")).toBeVisible();
+ out.document = await page.evaluate(() => location.href); expect(out.document).toBe(pathToFileURL(path.join(appDir, "dist/renderer/index.html")).href);
+ for (const [label, url] of [["Alpha lab", alpha.url], ["Beta lab", beta.url]]) await page.evaluate(({ label, url }) => window.modex!.invoke("local-models:command", { op: "create", input: { label, runtime: "ollama", url } }), { label, url });
+ await tid(page, "model-picker").click();
+ await tid(page, "model-local-option").filter({ hasText: "Fixture/Beta:Q4_0" }).click();
+ await tid(page, "model-local-context").getByRole("menuitemradio", { name: /65,536/ }).click();
+ await expect(tid(page, "model-local-badge")).toBeVisible();
+ const local = await page.evaluate(async () => (await window.modex!.invoke("state:get", undefined)).threads.find(t => t.localTarget)!);
+ expect(local.localTarget?.model.id).toBe("Fixture/Beta:Q4_0");
+ out.targetBefore = local.localTarget;
+ const cloud = await page.evaluate(() => window.modex!.invoke("thread:create", { projectId: "p1", backend: "mock", mode: "chat" }));
+ // Direct thread:create returns to its caller; unlike routine creation it does not broadcast a window refresh.
+ await page.reload(); await expect(tid(page, "composer-input")).toBeVisible();
+ out.setup = "Reload after direct IPC thread creation before the race; production source unchanged";
+ const select = async (id: string) => page.locator(`[data-testid="thread-row"][data-thread-id="${id}"] button.thread-main`).click();
+ await select(cloud.id);
+ await tid(page, "composer-input").fill(" cloud draft with image\nkept exactly ");
+ await page.evaluate(b64 => {
+ const dt = new DataTransfer(); dt.items.add(new File([Uint8Array.from(atob(b64), c => c.charCodeAt(0))], "dot.png", { type: "image/png" }));
+ document.querySelector('[data-testid="composer-input"]')!.dispatchEvent(new ClipboardEvent("paste", { clipboardData: dt, bubbles: true, cancelable: true }));
+ }, PNG_B64);
+ await expect(tid(tid(page, "composer-attachments"), "attachment-chip")).toContainText("dot.png");
+ const staging = path.join(home, "attachments", "staging");
+ expect(fs.readdirSync(staging)).toHaveLength(1); const staged = path.join(staging, fs.readdirSync(staging)[0]!);
+ out.imageBefore = sha(fs.readFileSync(staged)); expect(out.imageBefore).toBe(sha(Buffer.from(PNG_B64, "base64")));
+ await tid(page, "open-settings").click(); await page.getByRole("button", { name: "Local models", exact: true }).click();
+ const alphaCard = tid(page, "local-connection").filter({ hasText: "Alpha lab" });
+ await expect(alphaCard).toHaveAttribute("data-state", "ready");
+ alpha.hold();
+ await alphaCard.getByTestId("local-refresh").click();
+ await new Promise((resolve, reject) => {
+ const timer = setTimeout(() => reject(new Error("Alpha refresh did not reach its barrier within 10s")), 10000);
+ alpha!.barrier.then(() => { clearTimeout(timer); resolve(); }, error => { clearTimeout(timer); reject(error); });
+ });
+ await page.keyboard.press("Escape");
+ await select(local.id);
+ await tid(page, "composer-input").fill(" local draft\nkept separately ");
+ await expect(tid(page, "local-inference-host")).toContainText(beta.url);
+ await tid(page, "composer-input").evaluate((el: HTMLTextAreaElement) => el.setSelectionRange(1, 5));
+ await tid(page, "model-picker").click();
+ const search = page.getByRole("searchbox", { name: "Search models" }); await search.fill("late/ALPHA");
+ await search.press("Home"); for (let key = 0; key < 4; key++) await search.press("Shift+ArrowRight");
+ expect(await search.evaluate((el: HTMLInputElement) => ({ start: el.selectionStart, end: el.selectionEnd }))).toEqual({ start: 0, end: 4 });
+ alpha.release();
+ await expect(tid(page, "model-local-title")).toHaveText(["Late/Alpha:Q4_0"]);
+ await expect(search).toHaveValue("late/ALPHA"); await expect(search).toBeFocused();
+ out.searchSelectionAfter = await search.evaluate((el: HTMLInputElement) => ({ start: el.selectionStart, end: el.selectionEnd }));
+ expect(out.searchSelectionAfter).toEqual({ start: 0, end: 4 });
+ const after = await page.evaluate(() => window.modex!.invoke("state:get", undefined));
+ out.targetAfter = after.threads.find(t => t.id === local.id)!.localTarget; expect(out.targetAfter).toEqual(out.targetBefore);
+ expect(after.threads.find(t => t.id === cloud.id)!.localTarget).toBeUndefined();
+ await page.keyboard.press("Escape"); await expect(tid(page, "composer-input")).toHaveValue(" local draft\nkept separately ");
+ out.localDraftAfter = await tid(page, "composer-input").inputValue();
+ await tid(page, "composer-input").focus();
+ out.localSelectionAfter = await tid(page, "composer-input").evaluate((el: HTMLTextAreaElement) => ({ start: el.selectionStart, end: el.selectionEnd }));
+ expect(out.localSelectionAfter).toEqual({ start: 1, end: 5 });
+ await select(cloud.id); await expect(tid(page, "composer-input")).toHaveValue(" cloud draft with image\nkept exactly ");
+ await expect(tid(tid(page, "composer-attachments"), "attachment-chip")).toContainText("dot.png");
+ out.cloudDraftAfter = await tid(page, "composer-input").inputValue();
+ out.callCounts = await app.evaluate(() => (globalThis as any).__lm4Calls);
+ expect(out.callCounts).toEqual({ localStarts: 0, sends: 0, durableSends: 0, retries: 0 });
+ for (const id of [local.id, cloud.id]) expect(await page.evaluate(threadId => window.modex!.invoke("thread:items", { threadId }), id)).toEqual([]);
+ out.imageAfter = sha(fs.readFileSync(staged)); expect(out.imageAfter).toBe(out.imageBefore);
+ for (const r of [alpha, beta]) expect(r.hits.every(h => !h.auth && ((h.method === "GET" && ["/api/tags", "/api/ps"].includes(h.url!)) || (h.method === "POST" && h.url === "/api/show")))).toBe(true);
+ out.state = "passed";
+ } catch (error) { out.state = "failed"; out.failure = String(error); throw error; }
+ finally {
+ alpha?.release();
+ out.hits = { alpha: alpha?.hits ?? [], beta: beta?.hits ?? [] };
+ try { if (app) { await app.close(); out.appClose = "returned"; } else out.appClose = "no returned handle"; }
+ catch (error) { out.state = "close-failed"; out.closeError = String(error); throw error; }
+ finally { await Promise.all([alpha, beta].filter((r): r is Awaited> => Boolean(r)).map(r => r.stop())); out.finishedAt = new Date().toISOString(); persist(); await testInfo.attach("local-model-preservation.json", { path: receipt, contentType: "application/json" }); }
+ }
+});
diff --git a/apps/desktop/e2e/local-model-profile-revision.spec.ts b/apps/desktop/e2e/local-model-profile-revision.spec.ts
new file mode 100644
index 00000000..d3f96b0f
--- /dev/null
+++ b/apps/desktop/e2e/local-model-profile-revision.spec.ts
@@ -0,0 +1,123 @@
+// #381 metadata races through production IPC/store/renderer with the existing scripted native fixture.
+// These cases request no coding turns and do not qualify ordinary product admission or real models.
+import { test, expect, _electron as electron, type ElectronApplication } from "@playwright/test";
+import fs from "node:fs";
+import { execFileSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+import path from "node:path";
+import http from "node:http";
+import type { AddressInfo } from "node:net";
+import { appDir, seedHome, tid } from "./support.js";
+
+async function runtime(initial: string) {
+ let model = initial;
+ let arrival: (() => void) | undefined;
+ let held: http.ServerResponse | undefined;
+ const hits: Array<{ method?: string; url?: string; auth: boolean }> = [];
+ const heldReleases: Array<{ model: string; destroyedBeforeRelease: boolean }> = [];
+ const server = http.createServer((req, res) => {
+ hits.push({ method: req.method, url: req.url, auth: Boolean(req.headers.authorization) }); req.resume();
+ res.setHeader("content-type", "application/json");
+ if (req.url === "/api/tags") {
+ if (arrival) { held = res; const resolve = arrival; arrival = undefined; resolve(); }
+ else res.end(JSON.stringify({ models: [{ name: model, details: { family: "qwen3moe" } }] }));
+ } else if (req.url === "/api/ps") res.end(JSON.stringify({ models: [] }));
+ else if (req.url === "/api/show") res.end(JSON.stringify({ capabilities: ["completion", "tools"], model_info: { "qwen3moe.context_length": 65536 } }));
+ else { res.writeHead(404); res.end(); }
+ });
+ await new Promise((resolve, reject) => { server.once("error", reject); server.listen(0, "127.0.0.1", resolve); });
+ const release = (next = model) => {
+ model = next;
+ if (held) {
+ heldReleases.push({ model: next, destroyedBeforeRelease: held.destroyed });
+ if (!held.destroyed) held.end(JSON.stringify({ models: [{ name: model, details: { family: "qwen3moe" } }] }));
+ held = undefined;
+ }
+ };
+ return { hits, heldReleases, url: `http://127.0.0.1:${(server.address() as AddressInfo).port}`,
+ hold: () => new Promise(resolve => { arrival = resolve; }), release,
+ stop: async () => { release(); server.closeAllConnections(); await new Promise(resolve => server.close(() => resolve())); } };
+}
+async function arrived(barrier: Promise) {
+ await new Promise((resolve, reject) => {
+ const timer = setTimeout(() => reject(new Error("Metadata barrier did not arrive within 10s")), 10000);
+ barrier.then(() => { clearTimeout(timer); resolve(); }, error => { clearTimeout(timer); reject(error); });
+ });
+}
+
+test("profile form survives metadata and endpoint revision never silently rebinds its thread", async ({}, testInfo) => {
+ const receipt = testInfo.outputPath("local-model-profile-revision.json"); expect(fs.existsSync(receipt)).toBe(false);
+ const out: Record = { startedAt: new Date().toISOString(), gitHeadAtRun: execFileSync("git", ["rev-parse", "HEAD"], { cwd: appDir, encoding: "utf8" }).trim(), state: "started", scope: "scripted temporary-home existing workflow bootstrap; no provider inference or product activation" };
+ const persist = () => fs.writeFileSync(receipt, JSON.stringify(out, null, 2) + "\n"); persist();
+ let old: Awaited> | undefined, replacement: Awaited> | undefined;
+ let app: ElectronApplication | undefined;
+ try {
+ old = await runtime("Fixture/Beta:Q4_0"); replacement = await runtime("Replacement/Coder:Q8");
+ const { home } = seedHome();
+ app = await electron.launch({ args: [path.join(appDir, "e2e/fixtures/local-model-preservation.mjs")], cwd: appDir,
+ env: { ...process.env, MODEX_HOME: home, MODEX_E2E: "1", MODEX_E2E_NODE: process.execPath, MODEX_LM_NATIVE_E2E: "", MODEX_LM3_LIVE: "", MODEX_LM3_WIRE: "", MODEX_NO_LOGIN_PATH: "1", TYPESAFE_API_KEY: "", JEV_API_KEY: "" } });
+ out.mainPid = app.process().pid; persist();
+ const page = await app.firstWindow(); await page.waitForLoadState("domcontentloaded"); await expect(tid(page, "composer-input")).toBeVisible();
+ out.document = await page.evaluate(() => location.href); expect(out.document).toBe(pathToFileURL(path.join(appDir, "dist/renderer/index.html")).href);
+ const created = await page.evaluate(url => window.modex!.invoke("local-models:command", { op: "create", input: { label: "Beta lab", runtime: "ollama", url } }), old.url);
+ expect(created.op).toBe("create");
+ await tid(page, "model-picker").click(); await tid(page, "model-local-option").click();
+ await tid(page, "model-local-context").getByRole("menuitemradio", { name: /65,536/ }).click();
+ await expect(tid(page, "model-local-badge")).toBeVisible();
+ const thread = await page.evaluate(async () => (await window.modex!.invoke("state:get", undefined)).threads.find(t => t.localTarget)!);
+ out.targetBefore = thread.localTarget;
+ await tid(page, "composer-input").fill(" pinned draft\nkeep every byte ");
+ await tid(page, "open-settings").click(); await page.getByRole("button", { name: "Local models", exact: true }).click();
+ const card = tid(page, "local-connection"); await expect(card).toHaveAttribute("data-state", "ready");
+ const first = old.hold(); await tid(card, "local-refresh").click(); await arrived(first);
+ await tid(card, "local-edit").click(); const form = tid(card, "local-edit-form");
+ const name = form.getByLabel("Name", { exact: true });
+ await name.fill(" Edited Beta "); await form.getByLabel("Extra model IDs (one per line)").fill("Custom/Exact ID:Q4_0"); await name.focus();
+ // Establish the range directly: macOS Home does not move this input caret.
+ await name.evaluate((el: HTMLInputElement) => el.setSelectionRange(0, 3));
+ out.editSelectionBefore = await name.evaluate((el: HTMLInputElement) => ({ start: el.selectionStart, end: el.selectionEnd }));
+ expect(out.editSelectionBefore).toEqual({ start: 0, end: 3 });
+ old.release("Late/Beta:Q4_0");
+ await expect(tid(card, "local-model")).toContainText("Late/Beta:Q4_0");
+ await expect(name).toHaveValue(" Edited Beta "); await expect(name).toBeFocused();
+ out.editSelectionAfter = await name.evaluate((el: HTMLInputElement) => ({ start: el.selectionStart, end: el.selectionEnd }));
+ expect(out.editSelectionAfter).toEqual({ start: 0, end: 3 });
+ await expect(form.getByLabel("Extra model IDs (one per line)")).toHaveValue("Custom/Exact ID:Q4_0");
+ out.editDraftBeforeSave = await name.inputValue();
+ const beforeSecond = await app.evaluate(() => (globalThis as any).__lm4DiscoveryStarts.length);
+ const second = old.hold(); await tid(card, "local-refresh").click(); await arrived(second);
+ const secondStarts = await app.evaluate(({}, arg) => (globalThis as any).__lm4DiscoveryStarts.slice(arg.after).filter((r: any) => r.connection.id === arg.ref.id && r.connection.revision === arg.ref.revision), { after: beforeSecond, ref: out.targetBefore.model.connection });
+ expect(secondStarts).toHaveLength(1); out.secondHeldRequestId = secondStarts[0].requestId;
+ await form.getByLabel("Address", { exact: true }).fill(replacement.url);
+ await form.getByRole("button", { name: "Save connection", exact: true }).click();
+ await expect(card).toHaveAttribute("data-state", "ready");
+ await expect(tid(card, "local-model")).toContainText(["Replacement/Coder:Q8", "Custom/Exact ID:Q4_0"]);
+ old.release("Stale/MustNotAppear");
+ await expect.poll(() => app!.evaluate(({}, requestId) => (globalThis as any).__lm4DiscoveryResults.some((r: any) => r.requestId === requestId && r.state === "stale"), out.secondHeldRequestId)).toBe(true);
+ out.discoveryResults = await app.evaluate(() => (globalThis as any).__lm4DiscoveryResults);
+ out.staleIdAbsentAtCheckedPoint = !(await card.innerText()).includes("Stale/MustNotAppear");
+ expect(out.staleIdAbsentAtCheckedPoint).toBe(true);
+ const profiles = await page.evaluate(() => window.modex!.invoke("local-models:command", { op: "list" }));
+ if (profiles.op !== "list") throw new Error("Expected profile list");
+ out.currentConnection = profiles.connections[0]; expect(out.currentConnection.revision).toBe(out.targetBefore.model.connection.revision + 1);
+ expect(out.currentConnection.origin).toBe(replacement.url); expect(out.currentConnection.manualModels).toEqual(["Custom/Exact ID:Q4_0"]);
+ const state = await page.evaluate(() => window.modex!.invoke("state:get", undefined));
+ out.targetAfter = state.threads.find(t => t.id === thread.id)!.localTarget; expect(out.targetAfter).toEqual(out.targetBefore);
+ await page.keyboard.press("Escape");
+ await expect(tid(page, "composer-input")).toHaveValue(" pinned draft\nkeep every byte ");
+ out.rawDraftAfter = await tid(page, "composer-input").inputValue();
+ await expect(tid(page, "local-inference-host")).toContainText("an unavailable local server");
+ await expect(tid(page, "local-inference-host")).not.toContainText(replacement.url);
+ out.provenanceText = await tid(page, "local-inference-host").innerText();
+ out.callCounts = await app.evaluate(() => (globalThis as any).__lm4Calls); expect(out.callCounts).toEqual({ localStarts: 0, sends: 0, durableSends: 0, retries: 0 });
+ expect(await page.evaluate(threadId => window.modex!.invoke("thread:items", { threadId }), thread.id)).toEqual([]);
+ for (const r of [old, replacement]) expect(r.hits.every(h => !h.auth && ((h.method === "GET" && ["/api/tags", "/api/ps"].includes(h.url!)) || (h.method === "POST" && h.url === "/api/show")))).toBe(true);
+ out.state = "passed";
+ } catch (error) { out.state = "failed"; out.failure = String(error); throw error; }
+ finally {
+ old?.release(); out.runtime = { old: { hits: old?.hits ?? [], releases: old?.heldReleases ?? [] }, replacement: { hits: replacement?.hits ?? [] } };
+ try { if (app) { await app.close(); out.appClose = "returned"; } else out.appClose = "no returned app handle"; }
+ catch (error) { out.state = "close-failed"; out.closeError = String(error); throw error; }
+ finally { await Promise.all([old, replacement].filter((r): r is Awaited> => Boolean(r)).map(r => r.stop())); out.finishedAt = new Date().toISOString(); persist(); await testInfo.attach("local-model-profile-revision.json", { path: receipt, contentType: "application/json" }); }
+ }
+});
diff --git a/apps/desktop/src/main/engine/backends/account-codex.ts b/apps/desktop/src/main/engine/backends/account-codex.ts
index f14bc566..835b4cfd 100644
--- a/apps/desktop/src/main/engine/backends/account-codex.ts
+++ b/apps/desktop/src/main/engine/backends/account-codex.ts
@@ -88,7 +88,8 @@ export class AccountCodexBackend implements Backend {
const id = opts.account ?? this.identity();
return this.use(id, (backend) => generateTitle(backend, opts, text, signal));
}
- listModels(): Promise { return this.use(this.identity(), (backend) => backend.listModels()); }
+ listModels(account = this.identity()): Promise { return this.use(account, (backend) => backend.listModels()); }
+ quota(account = this.identity()) { return this.use(account, (backend) => backend.quota()); }
async health() {
const id = this.identity(); if (id === "cli") return this.cli.health();
const installed = await installation(this.bin, this.spawnImpl);
diff --git a/apps/desktop/src/main/engine/backends/claude.ts b/apps/desktop/src/main/engine/backends/claude.ts
index 032f0ec9..4f116e0b 100644
--- a/apps/desktop/src/main/engine/backends/claude.ts
+++ b/apps/desktop/src/main/engine/backends/claude.ts
@@ -1,3 +1,4 @@
+import { claudeQuota, type QuotaSnapshot } from "../routing/quota.js";
import { actionDigest } from "../../../shared/human-requests.js";
import { AgentTracker } from "./agents.js";
import type { CliExecutable } from "../cli-path.js";
@@ -67,6 +68,9 @@ export function confinedEnvironment(bin: string, env: NodeJS.ProcessEnv = proces
*/
export class ClaudeBackend implements Backend {
readonly id = "claude" as const;
+ private readonly quotas = new Map();
+
+ async quota(account = "cli"): Promise { return this.quotas.get(account); }
protected get bin(): string { return typeof this.executable === "function" ? this.executable() : this.executable; }
constructor(
@@ -134,7 +138,7 @@ export class ClaudeBackend implements Backend {
if (opts.model) args.push("--model", opts.model);
if (opts.effort) args.push("--effort", opts.effort);
// Fast mode is a settings key in Claude Code; `--settings` accepts inline JSON for this session only.
- if (opts.fast) args.push("--settings", JSON.stringify({ fastMode: true }));
+ if (opts.fast || opts.conserveCredits) args.push("--settings", JSON.stringify({ fastMode: opts.conserveCredits ? false : true }));
if (opts.resume) args.push("--resume", opts.resume);
for (const d of opts.addDirs ?? []) args.push("--add-dir", d);
if (opts.knowledge || opts.pages || opts.images) args.push("--mcp-config", JSON.stringify({ mcpServers: {
@@ -378,6 +382,14 @@ export class ClaudeBackend implements Backend {
} catch {
return;
}
+ if (msg.type === "rate_limit_event") {
+ const next = claudeQuota(msg.rate_limit_info);
+ const account = opts.account ?? "cli";
+ const previous = this.quotas.get(account);
+ const replaced = new Set(next.windows.map(w => w.key));
+ this.quotas.set(account, { ...next, windows: [...(previous?.windows ?? []).filter(w => !replaced.has(w.key)), ...next.windows] });
+ return;
+ }
// A heartbeat (the CLI sends one while a control request runs long) is no sign of the turn going on.
if (msg.type === "keep_alive") return;
// The CLI no longer needs an answer to one of its prompts (Stop, or it settled the prompt itself).
@@ -705,6 +717,8 @@ interface ClaudeMessage {
tasks?: { task_id?: string }[];
session_id?: string;
message?: { id?: string; model?: string; content?: ContentBlock[]; usage?: ClaudeUsage };
+ /** Metadata-only rate_limit_event from the CLI. */
+ rate_limit_info?: unknown;
/** A synthetic assistant reply's API error class ("rate_limit", "billing_error", …). */
error?: unknown;
/** `result`: the turn's token totals. */
diff --git a/apps/desktop/src/main/engine/backends/codex.ts b/apps/desktop/src/main/engine/backends/codex.ts
index ba3d7c02..348cfcbd 100644
--- a/apps/desktop/src/main/engine/backends/codex.ts
+++ b/apps/desktop/src/main/engine/backends/codex.ts
@@ -1,3 +1,4 @@
+import { codexQuota, type QuotaSnapshot } from "../routing/quota.js";
import { requestedPermissions } from "./codex-permissions.js";
import { AgentTracker } from "./agents.js";
import { PAGES_TOOLS } from "../../../shared/pages.js";
@@ -178,6 +179,12 @@ export class CodexBackend implements Backend {
this.send({ id, result });
}
+ async quota(): Promise {
+ if (this.configuration?.local) return undefined;
+ await this.ensure();
+ return codexQuota(await this.request("account/rateLimits/read", {}, 3000));
+ }
+
async listModels(): Promise {
await this.ensure();
const res = await this.request<{ data: CodexModel[] }>("model/list", {});
@@ -703,7 +710,7 @@ export class CodexBackend implements Backend {
model: opts.model || null,
effort: opts.effort ?? null,
// "fast" is the Codex fast-mode service tier; only this turn, the thread's tier is untouched.
- serviceTierForTurn: opts.fast ? "fast" : null,
+ serviceTierForTurn: opts.conserveCredits ? "default" : opts.fast ? "fast" : null,
...(mode ? { collaborationMode: mode } : {}),
});
turnStart(input, collaborationMode)
diff --git a/apps/desktop/src/main/engine/backends/types.ts b/apps/desktop/src/main/engine/backends/types.ts
index e53bd92a..758bdc35 100644
--- a/apps/desktop/src/main/engine/backends/types.ts
+++ b/apps/desktop/src/main/engine/backends/types.ts
@@ -129,6 +129,8 @@ export interface TurnOptions {
effort?: string;
/** Fast mode for this turn (Codex "fast" service tier, Claude fastMode setting). */
fast?: boolean;
+ /** Auto conservation must override a saved fast setting, not inherit it. */
+ conserveCredits?: boolean;
/** Resumable handle from a previous turn on this thread. */
resume?: string;
account?: string;
@@ -209,7 +211,9 @@ export interface Backend {
*/
forceStop?(account?: string): Promise;
/** Current model catalogue for this backend. */
- listModels(): Promise;
+ listModels(account?: string): Promise;
+ /** Metadata-only CLI quota read, scoped to the admitted account. Never starts inference. */
+ quota?(account?: string): Promise;
health?(): Promise;
identity?(): string;
dispose(): Promise;
diff --git a/apps/desktop/src/main/engine/routing/fit.ts b/apps/desktop/src/main/engine/routing/fit.ts
index 68d7a701..cce6d7f7 100644
--- a/apps/desktop/src/main/engine/routing/fit.ts
+++ b/apps/desktop/src/main/engine/routing/fit.ts
@@ -136,7 +136,7 @@ export class Fit {
this.write();
}
- recordOutcome(threadId: string, outcome: "completed" | "failed" | "interrupted", usage?: TurnUsage): void {
+ recordOutcome(threadId: string, outcome: "completed" | "failed" | "interrupted", usage?: TurnUsage, learn = true): void {
const r = this.open(threadId);
if (!r) return;
r.outcome = outcome;
@@ -145,10 +145,10 @@ export class Fit {
if (usage.outputTokens !== undefined) r.outputTokens = usage.outputTokens;
}
const t = (this.state.tasks[r.task] ??= empty());
- if (outcome === "failed") {
+ if (learn && outcome === "failed") {
t.failures += 1;
t.offset = Math.min(MAX_OFFSET, t.offset + FAILURE_STEP);
- } else if (outcome === "completed") t.completions += 1;
+ } else if (learn && outcome === "completed") t.completions += 1;
this.write();
}
diff --git a/apps/desktop/src/main/engine/routing/policy.ts b/apps/desktop/src/main/engine/routing/policy.ts
index aab53698..374b46be 100644
--- a/apps/desktop/src/main/engine/routing/policy.ts
+++ b/apps/desktop/src/main/engine/routing/policy.ts
@@ -1,3 +1,4 @@
+import { quotaState, type QuotaSnapshot } from "./quota.js";
import type { BackendId, EffortLevel, LastTurn, RoutingPolicy } from "../../../shared/types.js";
import type { Candidate, Tier } from "./catalog.js";
import { pick } from "./catalog.js";
@@ -42,6 +43,11 @@ export interface DecisionInput {
/** Learned per-task tier offset (see fit.ts). */
fitOffset: number;
premiumExhausted: boolean;
+ quotas?: Partial>;
+ /** Retry retains the previous attempt's conservation admission even when telemetry is now unknown. */
+ conserveCredits?: boolean;
+ /** An automatic account replacement retains the admitted task capability floor. */
+ minimumTier?: Tier;
/**
* What the thread's prompt cache was built with, and how long ago. The router always passes it;
* a caller that omits it gets a fresh choice every turn.
@@ -59,6 +65,11 @@ export interface Decision {
pinned: boolean;
/** The request must not run because an effort or premium budget limit cannot be guaranteed. */
blocked?: true;
+ minimumTier?: Tier;
+ quotaBlocked?: true;
+ quotaResetAt?: number;
+ /** Requires an explicit standard-speed override in the CLI, even with saved fast settings. */
+ conserving?: true;
/** True when a warm prompt cache kept the thread's model, effort or fast mode. */
held?: true;
/** The cache warmth the hold step saw; absent when no cache information was passed. */
@@ -244,7 +255,7 @@ function hold(input: DecisionInput, free: Decision, current: Candidate | undefin
return { ...kept, warmth: w };
}
-export function decide(input: DecisionInput): Decision {
+function decideWithLimits(input: DecisionInput): Decision {
const { judgments: j, policy, current } = input;
const reasons: string[] = [];
const currentLadder = input.ladders[current.backend] ?? [];
@@ -317,3 +328,97 @@ export function decide(input: DecisionInput): Decision {
// 7. Hold: a warm prompt cache keeps the thread where it is unless the jump is worth a rebuild.
return hold(input, { backend, model: candidate.model, effort, fast, tier: candidate.tier, pinned: false, reasons }, candidateNow, reasons);
}
+
+
+/** Quota is an eligibility constraint; conservation changes discretionary spend, never session ownership. */
+export function decide(input: DecisionInput): Decision { return decideWithQuota(input, Boolean(input.conserveCredits)); }
+
+function decideWithQuota(input: DecisionInput, retainConservation: boolean): Decision {
+ const now = Date.now();
+ const state = (backend: BackendId, model: string) => quotaState(input.quotas?.[backend], input.policy, model, now);
+ const current = currentCandidate(input);
+ const currentUsage = state(input.current.backend, current?.model ?? input.current.model);
+ const planned = decideWithLimits(input);
+ const plannedUsage = state(planned.backend, planned.model);
+ const reasons = [`${input.current.backend}: ${currentUsage.reason}`];
+ if (planned.model !== current?.model && plannedUsage.state === "low") reasons.push(`Initial candidate ${planned.model}: ${plannedUsage.reason}`);
+ const ladders: DecisionInput["ladders"] = {};
+ for (const [backend, candidates] of Object.entries(input.ladders) as [BackendId, Candidate[]][]) {
+ ladders[backend] = candidates.filter(c => {
+ const usage = state(backend, c.model);
+ if (usage.state !== "exhausted") return true;
+ reasons.push(`Excluded ${c.label}: ${usage.reason}`);
+ return false;
+ });
+ }
+ const conserve = input.policy.conserve_credits && (retainConservation || ["low", "exhausted"].includes(currentUsage.state) || plannedUsage.state === "low");
+ let minimumTier = input.minimumTier;
+ const stop = (detail: string, quotaBlocked = false): Decision => ({ ...blocked(input, reasons, detail), minimumTier, ...(quotaBlocked ? { quotaBlocked: true as const, quotaResetAt: currentUsage.resetsAt } : {}), ...(conserve ? { conserving: true as const } : {}) });
+ let effective = { ...input, ladders };
+ if (conserve) {
+ const j = input.judgments;
+ const light = j.complexity < 1.5 && j.needsDeepReasoning < 0.7 && j.blastRadius < 1.5;
+ effective = { ...effective, fitOffset: light ? Math.min(0, input.fitOffset) : input.fitOffset,
+ policy: { ...conservationPolicy(input.policy),
+ posture: light ? "economy" : input.policy.posture } };
+ reasons.push("Conserving low allowance or credits: economical suitable model, at most high effort, paid fast mode off; capability tiers estimate cost, not dollar prices.");
+ }
+ // Compare with the same cache/effort rules before exclusions. Unrelated quota buckets must
+ // never invalidate a legitimate cache hold that already ran below the free-choice tier.
+ const baseline = decideWithLimits({ ...effective, ladders: input.ladders });
+ const free = decideWithLimits({ ...effective, ladders: input.ladders, cache: undefined });
+ const wantedTier = Math.max(input.minimumTier ?? 0, Math.min(baseline.tier, free.tier)) as Tier;
+ minimumTier = wantedTier;
+ const healthy = (b: BackendId) => ladders[b]?.filter(c => c.tier >= wantedTier && state(b, c.model).state === "healthy") ?? [];
+ const quotaDriven = conserve || state(baseline.backend, baseline.model).state === "exhausted" || currentUsage.state === "exhausted";
+ if (quotaDriven && input.policy.allow_backend_switch && !input.current.hasSession) {
+ const allowed = input.policy.allow_backends.filter(b => b === input.current.backend || healthy(b).length > 0);
+ effective.policy = { ...effective.policy, allow_backends: allowed };
+ // Restrict all quota-driven alternatives, including the ordinary capability/unavailable
+ // fallback path, to candidates with fresh healthy readings.
+ for (const b of allowed) if (b !== input.current.backend) effective.ladders = { ...effective.ladders, [b]: healthy(b) };
+ const alternate = allowed.find(b => b !== input.current.backend);
+ if (alternate && (conserve || currentUsage.state === "exhausted")) {
+ reasons.push(`Selected ${alternate} on a fresh conversation: ${state(alternate, healthy(alternate)[0]!.model).reason}`);
+ effective = { ...effective, ladders: { ...effective.ladders, [input.current.backend]: [] }, policy: { ...effective.policy, allow_backends: [alternate] } };
+ }
+ }
+ if (currentUsage.state === "exhausted" && input.source === "jev" && input.judgments.taskConfidence < input.policy.min_confidence) {
+ return stop("The pinned model is exhausted and the judge is unsure; the route was stopped.", true);
+ }
+ const decision = decideWithLimits(effective);
+ const selectedUsage = state(decision.backend, decision.model || current?.model || "");
+ // A different candidate can become low only after exhaustion filtering or backend selection.
+ // One repeat applies conservation to that candidate; it cannot loop because the flag is sticky.
+ if (!conserve && input.policy.conserve_credits && selectedUsage.state === "low") return decideWithQuota(input, true);
+ if (selectedUsage.state === "exhausted") return stop("No permitted model has usable allowance or credits; the route was stopped. Wait for a reset or choose another account.", true);
+ if (!decision.blocked && decision.tier < wantedTier) {
+ return stop("The remaining models do not meet this task's capability target; the route was stopped instead of silently downgrading the work.", Object.values(input.ladders).some(cs => cs?.some(c => state(c.backend, c.model).state === "exhausted")));
+ }
+ if (decision.model !== current?.model || decision.backend !== input.current.backend) reasons.push(`${decision.backend}/${decision.model}: ${selectedUsage.reason}`);
+ return { ...decision, minimumTier: wantedTier, ...(conserve ? { conserving: true as const } : {}), reasons: decision.blocked ? [...reasons, ...decision.reasons] : [decision.reasons[0]!, ...reasons, ...decision.reasons.slice(1)] };
+}
+
+
+function conservationPolicy(policy: RoutingPolicy): RoutingPolicy {
+ const configured = effortIndex(policy.max_effort);
+ return { ...policy, allow_fast: false, ...(configured === undefined ? {} : { max_effort: EFFORTS[Math.min(configured, effortIndex("high")!)]! }) };
+}
+
+/** Revalidate the actual fixed replacement; never turn a provider retry into a weaker or unmetered route. */
+export function admitReplacement(input: DecisionInput, prior: Decision): Decision {
+ const candidate = currentCandidate(input);
+ const usage = quotaState(input.quotas?.[input.current.backend], input.policy, candidate?.model ?? input.current.model);
+ const minimumTier = prior.minimumTier ?? prior.tier;
+ const conserve = input.policy.conserve_credits && (Boolean(prior.conserving) || usage.state === "low" || usage.state === "unknown");
+ const reasons = [`Replacement ${input.current.backend}/${input.current.model}: ${usage.reason}`];
+ const stop = (detail: string): Decision => ({ ...blocked(input, reasons, detail), minimumTier, ...(conserve ? { conserving: true as const } : {}) });
+ if (usage.state === "exhausted") return { ...stop("The replacement is exhausted; Auto stopped before retrying."), quotaBlocked: true, quotaResetAt: usage.resetsAt };
+ if (!candidate) return stop("The replacement model is not in the account's catalogue; Auto stopped before retrying.");
+ if (candidate.tier < minimumTier) return stop("The replacement cannot meet this task's capability target; Auto stopped before retrying.");
+ const effective = conserve ? { ...input, policy: conservationPolicy(input.policy) } : input;
+ const decision = keepCurrent(effective, candidate, reasons);
+ if (conserve) reasons.push("Conserving replacement allowance or credits: supported effort at most high and paid fast mode explicitly off.");
+ return { ...decision, minimumTier, ...(conserve ? { conserving: true as const } : {}),
+ fast: !decision.blocked && !conserve && input.policy.allow_fast && prior.fast && Boolean(candidate.fastTier) };
+}
diff --git a/apps/desktop/src/main/engine/routing/quota.ts b/apps/desktop/src/main/engine/routing/quota.ts
new file mode 100644
index 00000000..4da4d5d9
--- /dev/null
+++ b/apps/desktop/src/main/engine/routing/quota.ts
@@ -0,0 +1,77 @@
+import type { RoutingPolicy } from "../../../shared/types.js";
+
+/** Account-bound metadata only. Provider credit units are not dollars or included allowance. */
+export interface QuotaSnapshot {
+ at: number;
+ windows: { key: string; remainingPercent?: number; resetsAt?: number; model?: string; at?: number; state?: "low" | "exhausted" }[];
+ credits?: { hasCredits?: boolean; unlimited?: boolean; balance?: number };
+ blocked?: boolean;
+ /** Explicit backend statement that included usage is unavailable; missing windows alone cannot prove this. */
+ includedUnavailable?: boolean;
+}
+export interface QuotaState { state: "unknown" | "healthy" | "low" | "exhausted"; reason: string; resetsAt?: number }
+export const QUOTA_MAX_AGE_MS = 5 * 60_000;
+const object = (v: unknown): Record => v && typeof v === "object" && !Array.isArray(v) ? v as Record : {};
+const finite = (v: unknown): v is number => typeof v === "number" && Number.isFinite(v);
+const epoch = (v: unknown): number | undefined => finite(v) && v > 0 && v * 1000 <= 8.64e15 ? v * 1000 : undefined;
+const fresh = (at: number, now: number) => finite(at) && now >= at && now - at <= QUOTA_MAX_AGE_MS;
+
+export function quotaState(snapshot: QuotaSnapshot | undefined, policy: RoutingPolicy, model = "", now = Date.now()): QuotaState {
+ const unknown = { state: "unknown", reason: "Remaining allowance and credits are unknown; no available balance was assumed." } as const;
+ if (!snapshot || !fresh(snapshot.at, now)) return unknown;
+ if (snapshot.blocked) return { state: "exhausted", reason: "The CLI reports a spend-control limit; this account is unavailable." };
+ const windows = snapshot.windows.filter(w => (!w.model || model === w.model || model.startsWith(`claude-${w.model}-`))
+ && fresh(w.at ?? snapshot.at, now) && (w.resetsAt === undefined || (finite(w.resetsAt) && w.resetsAt > now))
+ && (w.state || (finite(w.remainingPercent) && w.remainingPercent >= 0 && w.remainingPercent <= 100)));
+ const worst = [...windows].sort((a, b) => (a.state === "exhausted" ? 0 : a.remainingPercent ?? policy.low_quota_percent) - (b.state === "exhausted" ? 0 : b.remainingPercent ?? policy.low_quota_percent))[0];
+ const c = snapshot.credits;
+ const paid = c?.unlimited === true || (c?.hasCredits === true && c.balance !== 0) || (c?.hasCredits !== false && c?.balance !== undefined && c.balance > 0);
+ if (worst) {
+ const remaining = worst.state === "exhausted" ? 0 : worst.remainingPercent;
+ const reset = worst.resetsAt === undefined ? "" : `; resets ${new Date(worst.resetsAt).toISOString()}`;
+ const detail = remaining === undefined ? "The CLI warns that included allowance is low" : `${Math.round(remaining * 10) / 10}% included allowance remains`;
+ const paidDetail = c?.balance === undefined && !c?.unlimited
+ ? " Paid credits are available; amount is unknown; conserving credits."
+ : " Paid credits remain; conserving credits.";
+ if (remaining === 0) return { state: paid ? "low" : "exhausted", resetsAt: worst.resetsAt,
+ reason: `Included allowance is exhausted${reset}.${paid ? paidDetail : " No usable paid-credit balance is established."}` };
+ return { state: worst.state === "low" || remaining! <= policy.low_quota_percent ? "low" : "healthy", reason: `${detail}${reset}.` };
+ }
+ if (c?.unlimited) return { state: "healthy", reason: "The CLI reports unlimited credits." };
+ if (snapshot.includedUnavailable && (c?.hasCredits === false || c?.balance === 0)) return { state: "exhausted", reason: "The CLI reports included usage unavailable and no paid credits remain." };
+ if (c?.balance !== undefined && finite(c.balance) && c.balance > 0) return { state: c.balance <= policy.low_credit_balance ? "low" : "healthy", reason: `${c.balance} provider credit units remain; included allowance is unknown.` };
+ return unknown;
+}
+
+/** Codex app-server account/rateLimits/read. Never copies credentials or unrecognized payload text. */
+export function codexQuota(value: unknown, at = Date.now()): QuotaSnapshot {
+ const response = object(value), primary = object(response.rateLimits);
+ const windows: QuotaSnapshot["windows"] = [];
+ const buckets = [["account", primary], ...Object.entries(object(response.rateLimitsByLimitId)).map(([key, v]) => [key, object(v)] as const)] as const;
+ for (const [key, bucket] of buckets) {
+ // The single-bucket view is authoritative for general usage. Other buckets need an explicit model scope.
+ const model = typeof bucket.normalModelSlug === "string" ? bucket.normalModelSlug : undefined;
+ if (key !== "account" && !model) continue;
+ for (const kind of ["primary", "secondary"]) {
+ const w = object(bucket[kind]);
+ if (!finite(w.usedPercent) || w.usedPercent < 0 || w.usedPercent > 100) continue;
+ windows.push({ key: `${key}:${kind}`, remainingPercent: 100 - w.usedPercent, resetsAt: epoch(w.resetsAt), ...(model ? { model } : {}) });
+ }
+ }
+ const raw = object(primary.credits);
+ const balance = (typeof raw.balance === "string" && /^\d+(?:\.\d+)?$/.test(raw.balance.trim())) ? Number(raw.balance) : undefined;
+ const credits = Object.keys(raw).length ? { hasCredits: typeof raw.hasCredits === "boolean" ? raw.hasCredits : undefined,
+ unlimited: typeof raw.unlimited === "boolean" ? raw.unlimited : undefined, balance: finite(balance) && balance >= 0 ? balance : undefined } : undefined;
+ return { at, windows, ...(response.ordinaryUsageAllowed === false ? { includedUnavailable: true } : {}), ...(credits ? { credits } : {}), ...(primary.spendControlReached === true ? { blocked: true } : {}) };
+}
+
+/** Claude stream-json rate_limit_event; utilization is a fraction, resetsAt is epoch seconds. */
+export function claudeQuota(value: unknown, at = Date.now()): QuotaSnapshot {
+ const info = object(value);
+ const kind = typeof info.rateLimitType === "string" ? info.rateLimitType : "account";
+ const model = /^(?:seven_day|five_hour)_(opus|sonnet|haiku|fable)$/.exec(kind)?.[1];
+ if (!["account", "five_hour", "seven_day"].includes(kind) && !model) return { at, windows: [] };
+ const remainingPercent = finite(info.utilization) && info.utilization >= 0 && info.utilization <= 1 ? 100 * (1 - info.utilization) : undefined;
+ const state = info.status === "rejected" ? "exhausted" : info.status === "allowed_warning" ? "low" : undefined;
+ return { at, windows: [{ key: kind, at, remainingPercent, resetsAt: epoch(info.resetsAt), ...(model ? { model } : {}), ...(state ? { state } : {}) }] };
+}
diff --git a/apps/desktop/src/main/engine/routing/router.ts b/apps/desktop/src/main/engine/routing/router.ts
index 2ebab199..ab37abf1 100644
--- a/apps/desktop/src/main/engine/routing/router.ts
+++ b/apps/desktop/src/main/engine/routing/router.ts
@@ -1,24 +1,31 @@
+import type { QuotaSnapshot } from "./quota.js";
import path from "node:path";
import type { BackendId, FollowUp, ModelInfo, RoutingPolicy, RoutingStatus, RoutingTest, Thread, ThreadItem } from "../../../shared/types.js";
import type { SecretStore } from "../secrets.js";
-import { ladder, tierOf, type Candidate } from "./catalog.js";
+import { ladder, tierOf, type Candidate, type Tier } from "./catalog.js";
import { Decisions, type DecisionsOptions } from "./decisions.js";
import { Fit } from "./fit.js";
import { JevError } from "./jev.js";
import { judgeHeuristically, judgeWithJev, stateFor, QUESTION_SET_VERSION, type JudgeSource, type Judgments } from "./judge.js";
-import { decide, type Decision } from "./policy.js";
+import { admitReplacement, decide, type Decision } from "./policy.js";
import { fallbackFollowUp, FOLLOW_UP_QUESTION, FOLLOW_UPS, followUpState } from "./followup.js";
import type { TurnUsage } from "../backends/types.js";
+type DecisionInputQuotas = Partial>;
+
/** The Jev options (transport, key, timeout, test seams) build the shared decision service. */
export interface RouterOptions extends Omit {
home: string;
policy: () => RoutingPolicy;
- listModels: (backend: BackendId) => Promise<{ models: ModelInfo[]; error?: string }>;
+ listModels: (backend: BackendId, account?: string) => Promise<{ models: ModelInfo[]; error?: string }>;
+ quota?: (backend: BackendId, account?: string) => Promise;
}
export interface RouteInput {
thread: Thread;
+ accounts?: Partial>;
+ conserveCredits?: boolean;
+ minimumTier?: Tier;
text: string;
items: ThreadItem[];
project: { name: string; branch?: string | null; changedFiles?: number };
@@ -39,12 +46,12 @@ export interface RouteReceipt {
export class Router {
readonly fit: Fit;
readonly decisions: Decisions;
- private readonly ladders = new Map();
+ private readonly ladders = new Map();
private readonly blockedThreads = new Set();
constructor(private readonly o: RouterOptions) {
this.fit = new Fit(path.join(o.home, "app", "routing-fit.json"));
- const { listModels: _listModels, ...decisions } = o;
+ const { listModels: _listModels, quota: _quota, ...decisions } = o;
this.decisions = new Decisions(decisions);
}
@@ -72,14 +79,15 @@ export class Router {
}
/** Model ladders are cached for a minute; the CLIs' lists rarely change mid-session. */
- private async ladderFor(backend: BackendId): Promise {
- const hit = this.ladders.get(backend);
+ private async ladderFor(backend: BackendId, account?: string): Promise {
+ const key = JSON.stringify([backend, account ?? "cli"]);
+ const hit = this.ladders.get(key);
if (hit && Date.now() - hit.at < 60_000) return hit.rungs;
- const r = await this.o.listModels(backend);
+ const r = await this.o.listModels(backend, account);
const rungs = ladder(backend, r.models);
if (r.error) throw new Error(`${backend} model discovery failed: ${r.error}`);
- if (rungs.length) this.ladders.set(backend, { at: Date.now(), rungs });
- else this.ladders.delete(backend);
+ if (rungs.length) this.ladders.set(key, { at: Date.now(), rungs });
+ else this.ladders.delete(key);
return rungs;
}
@@ -102,7 +110,7 @@ export class Router {
};
}
- async route(input: RouteInput, signal?: AbortSignal): Promise {
+ async route(input: RouteInput, signal?: AbortSignal, reuse?: RouteReceipt): Promise {
const started = Date.now();
const policy = this.o.policy();
const { thread } = input;
@@ -113,30 +121,41 @@ export class Router {
let judgments: Judgments;
let source: JudgeSource = "heuristic";
let fallback: string | undefined;
- const jev = await this.decisions.connect("routing", { threadId: thread.id });
- if (jev.transport) {
- try {
- judgments = await judgeWithJev(state, jev.transport, jev.model, signal);
- source = "jev";
- } catch (err) {
- const why = err instanceof JevError ? `${err.message} (${err.code})` : (err as Error).message;
- fallback = `Jev unavailable — ${why}; used the built-in heuristic.`;
+ if (reuse) { judgments = reuse.judgments; source = reuse.source; }
+ else {
+ const jev = await this.decisions.connect("routing", { threadId: thread.id });
+ if (jev.transport) {
+ try {
+ judgments = await judgeWithJev(state, jev.transport, jev.model, signal);
+ source = "jev";
+ } catch (err) {
+ const why = err instanceof JevError ? `${err.message} (${err.code})` : (err as Error).message;
+ fallback = `Jev unavailable — ${why}; used the built-in heuristic.`;
+ judgments = judgeHeuristically(state);
+ }
+ } else if (jev.disabled) {
+ fallback = `${jev.disabled} Used the built-in heuristic.`;
+ judgments = judgeHeuristically(state);
+ } else {
+ fallback = `${(jev.unavailable ?? "No Jev transport available").replace(/[.!;]+$/, "")}; used the built-in heuristic.`;
judgments = judgeHeuristically(state);
}
- } else if (jev.disabled) {
- fallback = `${jev.disabled} Used the built-in heuristic.`;
- judgments = judgeHeuristically(state);
- } else {
- fallback = `${(jev.unavailable ?? "No Jev transport available").replace(/[.!;]+$/, "")}; used the built-in heuristic.`;
- judgments = judgeHeuristically(state);
}
const backends = new Set([thread.backend, ...(policy.allow_backend_switch ? policy.allow_backends : [])]);
const ladders: Partial> = {};
const discoveryErrors: string[] = [];
+ const quotas: DecisionInputQuotas = {};
await Promise.all([...backends].map(async (b) => {
- try { ladders[b] = await this.ladderFor(b); }
- catch (err) { ladders[b] = []; discoveryErrors.push((err as Error).message); }
+ const account = input.accounts?.[b] ?? (b === "codex" ? thread.codexAccount : b === "claude" ? thread.claudeAccount : undefined) ?? undefined;
+ await Promise.all([
+ this.ladderFor(b, account).then(rungs => { ladders[b] = rungs; }).catch(err => {
+ ladders[b] = []; discoveryErrors.push((err as Error).message);
+ }),
+ Promise.resolve().then(() => this.o.quota?.(b, account)).then(snapshot => { quotas[b] = snapshot; }).catch(() => {
+ // Policy reports unknown usage. Raw errors may contain account credentials.
+ }),
+ ]);
}));
const last = thread.lastTurn;
@@ -144,7 +163,7 @@ export class Router {
const idleMs = Number.isFinite(lastAt) ? Math.max(0, Date.now() - lastAt) : undefined;
const premiumExhausted = policy.premium_turns_per_day != null && this.fit.premiumToday() >= policy.premium_turns_per_day;
const decision = decide({
- judgments, source, policy, ladders, premiumExhausted,
+ judgments, source, policy, ladders, premiumExhausted, quotas, conserveCredits: input.conserveCredits, minimumTier: input.minimumTier,
current: { backend: thread.backend, model: thread.model, effort: thread.effort, hasSession: Boolean(thread.sessionHandle) },
fitOffset: this.fit.offsetFor(judgments.task),
cache: { lastTurn: last, idleMs },
@@ -179,6 +198,7 @@ export class Router {
complexity: Math.round(judgments.complexity * 10) / 10,
pinned: decision.pinned,
blocked: decision.blocked,
+ ...(decision.conserving ? { conserving: true as const } : {}),
...(decision.held ? { held: true as const } : {}),
reasons: fallback ? [fallback, ...decision.reasons] : decision.reasons,
durationMs: Date.now() - started,
@@ -187,6 +207,26 @@ export class Router {
return { item, judgments, decision, source, questionSetVersion: QUESTION_SET_VERSION };
}
+ /** Metadata-only admission for a provider-selected model/account retry; Jev is not asked again. */
+ async admitReplacement(thread: Thread, previous: RouteReceipt, account?: string): Promise {
+ const policy = this.o.policy();
+ let rungs: Candidate[] = [], snapshot: QuotaSnapshot | undefined;
+ await Promise.all([
+ this.ladderFor(thread.backend, account).then(value => { rungs = value; }).catch(() => {}),
+ Promise.resolve().then(() => this.o.quota?.(thread.backend, account)).then(value => { snapshot = value; }).catch(() => {}),
+ ]);
+ // The failed provider attempt and its replacement share the original admitted premium turn.
+ const recorded = this.fit.latest(thread.id);
+ const used = this.fit.premiumToday() - Number(Boolean(recorded?.premium && recorded.at.slice(0, 10) === new Date().toISOString().slice(0, 10)));
+ const decision = admitReplacement({ judgments: previous.judgments, source: previous.source, policy,
+ current: { backend: thread.backend, model: thread.model, effort: thread.effort, hasSession: Boolean(thread.sessionHandle) },
+ ladders: { [thread.backend]: rungs }, quotas: { [thread.backend]: snapshot }, fitOffset: 0,
+ premiumExhausted: policy.premium_turns_per_day != null && used >= policy.premium_turns_per_day,
+ }, previous.decision);
+ if (decision.blocked) this.blockedThreads.add(thread.id);
+ return decision;
+ }
+
/** A provider-selected fallback changes what ran, never the user's learned preference. */
noteFallback(thread: Thread, fast: boolean): void {
const tier = tierOf({ id: thread.model, label: thread.model });
@@ -196,8 +236,8 @@ export class Router {
} catch { /* Learning persistence must not prevent a safe provider fallback. */ }
}
- noteOutcome(threadId: string, outcome: "completed" | "failed" | "interrupted", usage?: TurnUsage): void {
- try { this.fit.recordOutcome(threadId, outcome, usage); } catch { /* Learning persistence cannot change a coding turn's outcome. */ }
+ noteOutcome(threadId: string, outcome: "completed" | "failed" | "interrupted", usage?: TurnUsage, learn = true): void {
+ try { this.fit.recordOutcome(threadId, outcome, usage, learn); } catch { /* Learning persistence cannot change a coding turn's outcome. */ }
}
/**
diff --git a/apps/desktop/src/main/engine/runner.ts b/apps/desktop/src/main/engine/runner.ts
index 517face3..f7ee6507 100644
--- a/apps/desktop/src/main/engine/runner.ts
+++ b/apps/desktop/src/main/engine/runner.ts
@@ -14,7 +14,8 @@ import { ClaudeBackend } from "./backends/claude.js";
import { CodexBackend } from "./backends/codex.js";
import { AcpBackend } from "./backends/acp.js";
import { MockBackend } from "./backends/mock.js";
-import { Router } from "./routing/router.js";
+import { Router, type RouteReceipt } from "./routing/router.js";
+import type { Decision } from "./routing/policy.js";
import { answerFor, decide as decideApproval, gateApplies, receiptFor } from "./approvals/gate.js";
import { policyAnswer, policyReceipt } from "./approvals/policy.js";
import type { SecretStore } from "./secrets.js";
@@ -118,7 +119,7 @@ export interface RunnerOptions {
/** Whether a process still exists; tests replace the signal-0 probe. */
isProcessAlive?: (pid: number) => boolean;
/** Modex's Claude account pool: usage-limit cooldowns and rotation (engine/claude-accounts.ts). */
- claudeAccounts?: Pick;
+ claudeAccounts?: Pick;
}
/** The thread's account binding for its current backend: Codex and Claude Code keep separate ones. */
@@ -170,7 +171,7 @@ export class ThreadRunner {
mimo: o.backends?.mimo ?? new AcpBackend("mimo", () => resolveCli("mimo", cliSettings.mimo_bin)),
mock: o.backends?.mock ?? new MockBackend(() => s().mock_script, o.home),
};
- this.router = o.router ?? new Router({ home: o.home, policy: () => s().routing, listModels: (b) => this.listModels(b), secrets: o.secrets });
+ this.router = o.router ?? new Router({ home: o.home, policy: () => s().routing, listModels: (b, account) => this.listModels(b, account), quota: (b, account) => this.background.run(async () => this.backends[b].quota?.(account)), secrets: o.secrets });
// Jev is never asked about a local thread, whichever caller asks (#380).
this.router.decisions.guardThreads(id => localOnly(o.store.thread(id)));
}
@@ -189,11 +190,11 @@ export class ThreadRunner {
&& this.o.store.thread(threadId)?.localTarget?.model.connection.id === connectionId);
}
- async listModels(id: BackendId): Promise<{ models: ModelInfo[]; error?: string }> {
+ async listModels(id: BackendId, account?: string): Promise<{ models: ModelInfo[]; error?: string }> {
if (this.disposing) return { models: [], error: "Modex is shutting down." };
if (this.restartHold) return { models: [], error: "Modex is preparing to restart." };
try {
- return { models: await this.background.run(() => this.backends[id].listModels()) };
+ return { models: await this.background.run(() => this.backends[id].listModels(account)) };
} catch (err) {
return { models: [], error: (err as Error).message };
}
@@ -679,7 +680,7 @@ export class ThreadRunner {
/**
* Runs the thread's last message again, in place: the transcript keeps its one user bubble and the
- * new attempt follows the failure card. Auto routing is not re-asked; the pick already applied.
+ * new attempt follows the failure card. Auto obtains a fresh quota admission before each attempt.
*/
async retry(threadId: string, by = "desktop"): Promise {
this.assertLocalSender(threadId, by);
@@ -748,6 +749,12 @@ export class ThreadRunner {
// auxiliary setup can observe a different active account.
const prospectiveCodexAccount = thread.localTarget === undefined && (thread.backend === "codex" || thread.auto)
? this.backends.codex.identity?.() ?? null : null;
+ const prospectiveClaudeAccount = thread.localTarget === undefined && (thread.backend === "claude" || thread.auto)
+ ? this.backends.claude.identity?.() ?? "cli" : "cli";
+ const routeAccounts = {
+ codex: thread.codexAccount ?? (thread.backend === "codex" && thread.sessionHandle ? "cli" : prospectiveCodexAccount ?? "cli"),
+ claude: thread.claudeAccount ?? (thread.backend === "claude" && thread.sessionHandle ? "cli" : prospectiveClaudeAccount),
+ };
const admittedExecution = executionBinding(thread, prospectiveCodexAccount);
// Staged files move into the thread's folder now, so a Retry (or a restart) still finds them.
let draft: AttachmentDraft | undefined;
@@ -793,7 +800,9 @@ export class ThreadRunner {
const sink = this.sinkFor(threadId, l);
this.setStatus(threadId, "running");
let fast = false;
+ let conserveCredits = false;
let routeId: string | undefined;
+ let routeAdmission: RouteReceipt | undefined;
let routingBlocked: string | undefined;
// A local thread runs only on its exact target: never Auto, never a cloud backend, never a cloud account.
const local = thread.localTarget !== undefined;
@@ -806,12 +815,38 @@ export class ThreadRunner {
if (thread.plan || thread.imageJobId || files.some(file => file.kind === "image")) throw new Error("This local target runs text and tools only. Turn off Plan and remove images.");
} catch (err) { routingBlocked = (err as Error).message; }
}
- if (auto && !retry) {
+ if (auto) {
// Auto: judge the request, then re-read the thread — the pick is applied as a thread update
// so the composer, header, and persisted state all show what this turn runs on.
try {
const project = this.o.store.project(thread.projectId);
- const receipt = await this.router.route({ thread, text, items: l.items.slice(0, -1), project: { name: project?.name ?? "", branch: thread.worktree?.branch ?? null } }, abort.signal);
+ const previousRoute = retry ? [...l.items].reverse().find(i => i.kind === "route") : undefined;
+ const retainConservation = previousRoute?.kind === "route" && previousRoute.conserving === true;
+ let receipt = await this.router.route({ thread, accounts: routeAccounts, conserveCredits: retainConservation, text, items: l.items.slice(0, -1), project: { name: project?.name ?? "", branch: thread.worktree?.branch ?? null } }, abort.signal);
+ const pool = this.o.claudeAccounts;
+ if (receipt.decision.quotaBlocked && thread.backend === "claude" && !thread.sessionHandle && pool?.status().rotate) {
+ const seen = new Set();
+ let limited = routeAccounts.claude;
+ while (receipt.decision.quotaBlocked && !seen.has(limited) && seen.size <= 20 && !abort.signal.aborted) {
+ seen.add(limited);
+ pool.noteLimit(limited, receipt.decision.quotaResetAt);
+ const next = pool.pick(limited);
+ if (seen.has(next)) break;
+ const proposed = { ...thread, claudeAccount: next };
+ const candidate = await this.router.route({ thread: proposed, accounts: { ...routeAccounts, claude: next }, conserveCredits: true,
+ minimumTier: receipt.decision.minimumTier, text, items: l.items.slice(0, -1), project: { name: project?.name ?? "", branch: thread.worktree?.branch ?? null } }, abort.signal, receipt);
+ receipt = candidate;
+ if (!candidate.decision.blocked) {
+ this.o.store.updateThread(threadId, { claudeAccount: next });
+ thread = this.o.store.thread(threadId) ?? proposed;
+ routeAccounts.claude = next;
+ this.addItem(threadId, { id: newId(), kind: "notice", level: "warn", text: "The selected Claude account is exhausted; enabled account rotation selected another account before coding.", at: new Date().toISOString() });
+ break;
+ }
+ limited = next;
+ }
+ }
+ routeAdmission = receipt;
this.addItem(threadId, receipt.item);
routeId = receipt.item.id;
const d = receipt.decision;
@@ -822,6 +857,7 @@ export class ThreadRunner {
if (!d.blocked && d.backend !== thread.backend) this.updateThread(threadId, { backend: d.backend, model: d.model, effort: d.effort }, { fromRouter: true });
else if (!d.blocked && (d.model !== thread.model || d.effort !== thread.effort)) this.updateThread(threadId, { model: d.model, effort: d.effort }, { fromRouter: true });
fast = d.fast;
+ conserveCredits = d.conserving === true;
thread = this.o.store.thread(threadId) ?? thread;
} catch (err) {
if (thread.backend === "mock") {
@@ -880,7 +916,7 @@ export class ThreadRunner {
const account = !local && (thread.backend === "codex" || thread.backend === "claude") && backend.identity
? thread.backend === "codex"
? admittedExecution.backend === "codex" ? admittedExecution.account ?? undefined : prospectiveCodexAccount ?? undefined
- : bound ?? (thread.sessionHandle ? "cli" : backend.identity()) : undefined;
+ : bound ?? (thread.sessionHandle ? "cli" : prospectiveClaudeAccount) : undefined;
if (account && !bound) this.o.store.updateThread(threadId, thread.backend === "codex" ? { codexAccount: account } : { claudeAccount: account });
const accountFor = (ran: Thread) => threadAccount(ran) ?? account;
const freshConversation = !thread.sessionHandle;
@@ -896,7 +932,7 @@ export class ThreadRunner {
const result = await backend.runTurn(
describeAttachments(text, turnFiles),
{
- cwd: ran.cwd, mode: ran.mode, plan: ran.plan, model: ran.model, effort: ran.effort, fast, resume: ran.sessionHandle, account: accountFor(ran),
+ cwd: ran.cwd, mode: ran.mode, plan: ran.plan, model: ran.model, effort: ran.effort, fast, ...(conserveCredits ? { conserveCredits: true } : {}), resume: ran.sessionHandle, account: accountFor(ran),
// Files the CLI reads by path sit outside cwd; --add-dir keeps that from prompting.
addDirs: turnFiles.some((f) => f.kind === "file") ? [path.join(this.attachments.root, threadId)] : [],
...(turnFiles.length ? { attachments: turnFiles } : {}), ...(knowledge ? { knowledge: knowledge.connection } : {}), ...(pages ? { pages: pages.connection } : {}), ...(images ? { images: images.connection } : {}),
@@ -911,25 +947,50 @@ export class ThreadRunner {
throw err;
}
};
- // A model refused for usage credits recently is refused again: start on its fallback instead.
- const skip = local ? undefined : this.recentCreditFallback(thread);
- if (skip) thread = this.fallBack(threadId, thread, skip, routeId, false);
+ let replacementBlocked = false;
+ let replacementFailure: TurnResult = { status: "failed", error: "Auto stopped before an unsafe replacement attempt." };
+ const validateReplacement = async (proposed: Thread): Promise<{ decision?: Decision } | undefined> => {
+ if (!auto || !routeAdmission) return {};
+ const decision = await this.router.admitReplacement(proposed, routeAdmission, accountFor(proposed));
+ if (abort.signal.aborted) { replacementBlocked = true; replacementFailure = { status: "interrupted" }; return undefined; }
+ if (decision.blocked) {
+ replacementBlocked = true;
+ replacementFailure = { status: "failed", error: decision.reasons.at(-1) ?? "Auto rejected the replacement." };
+ if (decision.quotaBlocked && proposed.backend === "claude" && accountFor(proposed)) this.o.claudeAccounts?.noteLimit(accountFor(proposed)!, decision.quotaResetAt);
+ this.addItem(threadId, { id: newId(), kind: "notice", level: "warn", text: `Auto replacement stopped: ${replacementFailure.error}`, at: new Date().toISOString() });
+ if (routeId) this.patchItem(threadId, routeId, { blocked: true, reasons: [...routeAdmission.item.reasons, ...decision.reasons] });
+ return undefined;
+ }
+ fast = decision.fast;
+ conserveCredits = decision.conserving === true;
+ routeAdmission = { ...routeAdmission, decision };
+ return { decision };
+ };
+ // A recent refusal is scoped to this account, and its replacement is admitted before persistence.
+ const skip = local ? undefined : this.recentCreditFallback(thread, accountFor(thread));
+ if (skip) {
+ const checked = await validateReplacement({ ...thread, model: skip });
+ if (checked) thread = this.fallBack(threadId, thread, skip, routeId, false, checked.decision);
+ }
let replyStart = l.items.length;
- let result = await runOn(thread);
+ let result = replacementBlocked ? replacementFailure : await runOn(thread);
// A failed local turn never moves to a cloud model.
- const fallback = !local && result.status === "failed" && !abort.signal.aborted ? this.creditFallback(thread, result.error, l.items.slice(turnStart)) : undefined;
+ const fallback = !local && !replacementBlocked && result.status === "failed" && !abort.signal.aborted ? this.creditFallback(thread, result.error, l.items.slice(turnStart)) : undefined;
if (fallback) {
const from = thread.model;
- this.outOfCredits.set(`${thread.backend}:${from}`, Date.now());
- thread = this.fallBack(threadId, thread, fallback, routeId, true);
- replyStart = l.items.length;
- result = await runOn(thread);
- if (result.status === "failed") result = { ...result, recovery: [`${modelFamilyName(from)} was out of usage credits; retried on ${modelFamilyName(fallback)}.`, ...(result.recovery ?? [])] };
+ this.outOfCredits.set(JSON.stringify([thread.backend, accountFor(thread) ?? "cli", from]), Date.now());
+ const checked = await validateReplacement({ ...thread, model: fallback });
+ if (checked) {
+ thread = this.fallBack(threadId, thread, fallback, routeId, true, checked.decision);
+ replyStart = l.items.length;
+ result = await runOn(thread);
+ if (result.status === "failed") result = { ...result, recovery: [`${modelFamilyName(from)} was out of usage credits; retried on ${modelFamilyName(fallback)}.`, ...(result.recovery ?? [])] };
+ } else result = replacementFailure;
}
// A Claude account that reports a usage limit cools down; with rotation on, a turn that had not started work moves on.
const pool = this.o.claudeAccounts;
const limited = accountFor(thread);
- if (!local && pool && thread.backend === "claude" && limited && result.status === "failed" && !abort.signal.aborted && classifyFailure(result.error ?? "") === "rate_limited") {
+ if (!local && !replacementBlocked && pool && thread.backend === "claude" && limited && result.status === "failed" && !abort.signal.aborted && classifyFailure(result.error ?? "") === "rate_limited") {
const { until } = pool.noteLimit(limited, limitResetAt(result.error ?? ""));
const next = pool.pick(limited);
const name = (id: string) => id === "cli" ? "Claude Code's own login" : `"${pool.account(id)?.label ?? "removed account"}"`;
@@ -938,13 +999,22 @@ export class ThreadRunner {
this.addItem(threadId, { id: newId(), kind: "notice", level: "warn", text: `Claude account ${name(limited)} hit its usage limit; Modex holds it out of rotation until ${new Date(until).toLocaleTimeString([], { hour: "numeric", minute: "2-digit" })}.${movable ? ` Retrying on ${name(next)}.` : next !== limited ? ` New Claude conversations start on ${name(next)}.` : ""}`, at: new Date().toISOString() });
if (movable) {
// A conversation that had no session before this turn starts fresh: the failed attempt's session may live in the old profile.
- this.o.store.updateThread(threadId, { claudeAccount: next, ...(freshConversation ? { sessionHandle: undefined } : {}) });
- thread = this.o.store.thread(threadId) ?? thread;
- replyStart = l.items.length;
- result = await runOn(thread);
- // A second limit still updates selection for the next conversation; never retry a third time.
- if (result.status === "failed" && !abort.signal.aborted && classifyFailure(result.error ?? "") === "rate_limited") pool.noteLimit(next, limitResetAt(result.error ?? ""));
- if (result.status === "failed") result = { ...result, recovery: [`Claude account ${name(limited)} hit its usage limit; retried on ${name(next)}.`, ...(result.recovery ?? [])] };
+ const proposed = { ...thread, claudeAccount: next, ...(freshConversation ? { sessionHandle: undefined } : {}) };
+ const checked = await validateReplacement(proposed);
+ if (checked) {
+ this.o.store.updateThread(threadId, { claudeAccount: next, ...(freshConversation ? { sessionHandle: undefined } : {}), ...(checked.decision ? { effort: checked.decision.effort } : {}) });
+ thread = this.o.store.thread(threadId) ?? proposed;
+ if (auto && checked.decision) {
+ this.router.noteFallback(thread, fast);
+ if (routeId) this.patchItem(threadId, routeId, { effort: checked.decision.effort, fast, conserving: checked.decision.conserving,
+ reasons: [...(routeAdmission?.item.reasons ?? []), ...checked.decision.reasons] });
+ }
+ replyStart = l.items.length;
+ result = await runOn(thread);
+ // A second limit still updates selection for the next conversation; never retry a third time.
+ if (result.status === "failed" && !abort.signal.aborted && classifyFailure(result.error ?? "") === "rate_limited") pool.noteLimit(next, limitResetAt(result.error ?? ""));
+ if (result.status === "failed") result = { ...result, recovery: [`Claude account ${name(limited)} hit its usage limit; retried on ${name(next)}.`, ...(result.recovery ?? [])] };
+ } else result = replacementFailure;
}
}
if (pool && thread.backend === "claude" && result.status === "completed" && accountFor(thread)) pool.clearLimit(accountFor(thread)!);
@@ -954,11 +1024,11 @@ export class ThreadRunner {
if (fast && !ranFast && routeId) this.noteFastOff(threadId, routeId, result.fastMode?.why);
this.noteLastTurn(threadId, thread, ranFast, result);
// Naming is a separate model conversation; a local thread keeps its opening-message title.
- if (!local && result.status === "completed" && shouldName && !abort.signal.aborted) {
+ if (!local && !conserveCredits && result.status === "completed" && shouldName && !abort.signal.aborted) {
const reply = l.items.slice(turnStart).reverse().find((item) => item.kind === "assistant" && item.text.trim());
this.nameThread(threadId, text, fallbackTitle, backend, thread.model, reply?.kind === "assistant" ? reply.text : undefined);
}
- if (auto) this.router.noteOutcome(threadId, result.status, result.usage);
+ if (auto) this.router.noteOutcome(threadId, result.status, result.usage, !replacementBlocked);
this.recordUsage(thread, accountFor(thread), result);
// A failure can precede Stop; its outcome does not establish process exit.
if (result.stop?.outcome === "unconfirmed" && result.stop.pid) (l.unconfirmed ??= new Set()).add(result.stop.pid);
@@ -1305,9 +1375,9 @@ export class ThreadRunner {
}
/** The fallback for a model that was refused for usage credits within CREDIT_SKIP_MS, or undefined. */
- private recentCreditFallback(thread: Thread): string | undefined {
+ private recentCreditFallback(thread: Thread, account = threadAccount(thread) ?? "cli"): string | undefined {
if (localOnly(thread) || !this.o.store.settings.model_fallback) return undefined;
- const key = `${thread.backend}:${thread.model}`;
+ const key = JSON.stringify([thread.backend, account, thread.model]);
const at = this.outOfCredits.get(key);
if (at === undefined) return undefined;
if (Date.now() - at >= CREDIT_SKIP_MS) { this.outOfCredits.delete(key); return undefined; }
@@ -1315,17 +1385,17 @@ export class ThreadRunner {
}
/** Moves the thread to `to` for this turn and onward, and says so in the thread and on Auto's receipt. */
- private fallBack(threadId: string, thread: Thread, to: string, routeId: string | undefined, refusedNow: boolean): Thread {
+ private fallBack(threadId: string, thread: Thread, to: string, routeId: string | undefined, refusedNow: boolean, admission?: Decision): Thread {
const from = modelFamilyName(thread.model), next = modelFamilyName(to);
// fromRouter: Modex made this switch, so Auto must not learn it as the user's preference.
- this.updateThread(threadId, { model: to }, { fromRouter: true });
+ this.updateThread(threadId, { model: to, ...(admission ? { effort: admission.effort } : {}) }, { fromRouter: true });
const why = refusedNow ? `${from} is out of usage credits, so this turn moved to ${next}.` : `${from} ran out of usage credits within the last hour, so this turn runs on ${next}.`;
this.addItem(threadId, { id: newId(), kind: "notice", level: "warn", text: `${why} Add usage credits to use ${from} again, or turn off the fallback in Settings.`, at: new Date().toISOString() });
const route = routeId ? this.slot(threadId).items.find((i) => i.id === routeId) : undefined;
if (route?.kind === "route") {
const actual = this.o.store.thread(threadId) ?? { ...thread, model: to };
- this.router.noteFallback(actual, route.fast);
- this.patchItem(threadId, route.id, { model: to, held: undefined, reasons: [...route.reasons, why] });
+ this.router.noteFallback(actual, admission?.fast ?? route.fast);
+ this.patchItem(threadId, route.id, { model: to, held: undefined, ...(admission ? { effort: admission.effort, fast: admission.fast, conserving: admission.conserving } : {}), reasons: [...route.reasons, why, ...(admission?.reasons ?? [])] });
}
return this.o.store.thread(threadId) ?? { ...thread, model: to };
}
diff --git a/apps/desktop/src/main/engine/store.ts b/apps/desktop/src/main/engine/store.ts
index 91c5c4cc..86ff0421 100644
--- a/apps/desktop/src/main/engine/store.ts
+++ b/apps/desktop/src/main/engine/store.ts
@@ -72,6 +72,9 @@ export function migrateRouting(raw: unknown): RoutingPolicy {
allow_fast: typeof r.allow_fast === "boolean" ? r.allow_fast : d.allow_fast,
min_confidence: num(r.min_confidence, 0, 1, d.min_confidence),
premium_turns_per_day: r.premium_turns_per_day === null ? null : typeof r.premium_turns_per_day === "number" && r.premium_turns_per_day >= 0 ? Math.floor(r.premium_turns_per_day) : d.premium_turns_per_day,
+ conserve_credits: typeof r.conserve_credits === "boolean" ? r.conserve_credits : d.conserve_credits,
+ low_quota_percent: num(r.low_quota_percent, 0, 100, d.low_quota_percent),
+ low_credit_balance: num(r.low_credit_balance, 0, Number.MAX_SAFE_INTEGER, d.low_credit_balance),
jev_model: typeof r.jev_model === "string" && r.jev_model.trim() ? r.jev_model.trim() : d.jev_model,
jev_transport: r.jev_transport === "auto" || r.jev_transport === "cli" || r.jev_transport === "http" ? r.jev_transport : d.jev_transport,
jev_bin: typeof r.jev_bin === "string" && r.jev_bin.trim() ? r.jev_bin.trim() : d.jev_bin,
diff --git a/apps/desktop/src/renderer/components/SettingsDialog.tsx b/apps/desktop/src/renderer/components/SettingsDialog.tsx
index 4e049f85..a972cb56 100644
--- a/apps/desktop/src/renderer/components/SettingsDialog.tsx
+++ b/apps/desktop/src/renderer/components/SettingsDialog.tsx
@@ -561,6 +561,22 @@ export function SettingsDialog({ settings, projects, currentProjectId, onSave, o
setR("premium_turns_per_day", e.target.value === "" ? null : Math.max(0, Math.floor(Number(e.target.value) || 0)))} />
+
+
+
+
+
+
Conservation chooses economical models for light work, limits reasoning effort and turns paid fast mode off. Complex work keeps its capability target; warm conversations keep their context. Unavailable balance readings appear as unknown in each route receipt.
-
↔
+
CHOOSE PER TASK
Claude Code or Codex. Your call.
@@ -255,7 +258,7 @@
Claude Code or Codex. Your call.
-
⑂
+
MAKE ROOM FOR PARALLEL WORK
Separate tasks. Separate checkouts.
@@ -273,7 +276,7 @@
Separate tasks. Separate checkouts.
-
▤
+
KEEP WHAT THE WORK TEACHES YOU
Context that carries forward.
@@ -360,7 +363,7 @@
Make room for your next idea.
class="button button-primary"
data-mac-download
href="__MODEX_DOWNLOAD__"
- >↓ Download for Mac Download for MacA few things worth knowing.
-
+
+
+
Your next task. A clearer place to build.
@@ -507,7 +512,7 @@
class="button button-primary"
data-mac-download
href="__MODEX_DOWNLOAD__"
- >↓ Download for Mac Download for Mac