@north-light/crouter 0.3.161 → 0.3.162

package/dist/core/__tests__/broker-launch-candidates.test.js

@@ -1,4 +1,4 @@
-import { test } from 'node:test';
+import { after, before, test } from 'node:test';
 import assert from 'node:assert/strict';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
@@ -9,6 +9,16 @@ import { buildBrokerSession, isUnknownModel } from '../runtime/broker.js';
 import { resolveProviderCandidates } from '../subscription-state.js';
 const realEngine = { createAgentSessionServices, createAgentSessionFromServices, SessionManager, VERSION };
 const C3_EXT = join(dirname(fileURLToPath(import.meta.url)), 'fixtures', 'c3-custom-provider-ext.ts');
+const previousModelIntent = process.env['CRTR_MODEL_INTENT'];
+before(() => {
+    delete process.env['CRTR_MODEL_INTENT'];
+});
+after(() => {
+    if (previousModelIntent === undefined)
+        delete process.env['CRTR_MODEL_INTENT'];
+    else
+        process.env['CRTR_MODEL_INTENT'] = previousModelIntent;
+});
 const requested = { provider: 'anthropic', id: 'requested' };
 const alternative = { provider: 'openai-codex', id: 'alternative' };
 const DEFAULT_MANAGED_PROVIDERS = new Set(['anthropic', 'openai-codex']);
@@ -92,7 +102,7 @@ test('launch candidate resolver selects a non-managed candidate as automatic fal
         { spec: 'missing/missing', reason: 'not registered' },
     ]);
 });
-test('broker launch falls back to a non-managed provider when no managed provider is authenticated', async () => {
+test('broker launch keeps an unregistered concrete model pinned even when a non-managed provider is available', async () => {
     const cwd = mkdtempSync(join(tmpdir(), 'crtr-launch-candidate-'));
     try {
         const engine = {
@@ -111,7 +121,7 @@ test('broker launch falls back to a non-managed provider when no managed provide
         };
         const { session } = await buildBrokerSession(engine, { cwd, extensionPaths: [C3_EXT], model: 'missing/missing' });
         try {
-            assert.equal(`${session.model?.provider}/${session.model?.id}`, 'c3prov/c3model');
+            assert.equal(`${session.model?.provider}/${session.model?.id}`, 'unknown/unknown');
         }
         finally {
             session.dispose();

package/dist/core/__tests__/broker-sdk-wiring.test.js

@@ -18,7 +18,7 @@
 //
 // These run offline (no network/auth): registration + system-prompt assembly +
 // dialog routing are all local. No tmux, no broker process — direct unit drives.
-import { test } from 'node:test';
+import { after, before, test } from 'node:test';
 import assert from 'node:assert/strict';
 import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
@@ -27,7 +27,6 @@ import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createAgentSessionServices, createAgentSessionFromServices, SessionManager, VERSION, } from '../runtime/broker-sdk.js';
 import { buildBrokerSession, makeBrokerUiContext, isLeadingEngineCommand, chooseGuidanceDeliveryMode, promptWithNextTurnGuidance, isHiddenJsonlBranchEntry, stripHiddenEntriesFromJsonlExport, engineLeadingCommandTokens, } from '../runtime/broker.js';
-import { readManagedProviderRotationPolicy } from '../runtime/managed-provider-cooling.js';
 import { CANVAS_EXTENSIONS } from '../runtime/launch.js';
 import { buildRefInventory } from '../memory/inline-ref-inventory.js';
 import { buildGuidance } from '../memory/inline-ref-guidance.js';
@@ -45,6 +44,32 @@ const realEngine = {
 const HERE = dirname(fileURLToPath(import.meta.url));
 const C3_EXT = join(HERE, 'fixtures', 'c3-custom-provider-ext.ts');
 const C5_EXT = join(HERE, 'fixtures', 'c5-command-boundary-ext.ts');
+const priorModelIntent = process.env['CRTR_MODEL_INTENT'];
+const priorNodeCwd = process.env['CRTR_NODE_CWD'];
+const priorProfileId = process.env['CRTR_PROFILE_ID'];
+before(() => {
+    // buildBrokerSession normally receives its environment through buildBrokerEnv,
+    // which strips the launcher's CRTR_* values before applying the target recipe.
+    // These direct SDK tests bypass that boundary, so clear the ambient node's
+    // routing scope and intent to exercise only each fixture's explicit config.
+    delete process.env['CRTR_MODEL_INTENT'];
+    delete process.env['CRTR_NODE_CWD'];
+    delete process.env['CRTR_PROFILE_ID'];
+});
+after(() => {
+    if (priorModelIntent === undefined)
+        delete process.env['CRTR_MODEL_INTENT'];
+    else
+        process.env['CRTR_MODEL_INTENT'] = priorModelIntent;
+    if (priorNodeCwd === undefined)
+        delete process.env['CRTR_NODE_CWD'];
+    else
+        process.env['CRTR_NODE_CWD'] = priorNodeCwd;
+    if (priorProfileId === undefined)
+        delete process.env['CRTR_PROFILE_ID'];
+    else
+        process.env['CRTR_PROFILE_ID'] = priorProfileId;
+});
 function brokerExts() {
     return [...CANVAS_EXTENSIONS, C3_EXT];
 }
@@ -138,7 +163,7 @@ function runIsolatedManagedLaunch(pool) {
     const script = `
     const { createAgentSessionServices, createAgentSessionFromServices, SessionManager, VERSION } = await import(${JSON.stringify(new URL('../runtime/broker-sdk.ts', import.meta.url).href)});
     const { buildBrokerSession } = await import(${JSON.stringify(new URL('../runtime/broker.ts', import.meta.url).href)});
-    const { writeSubscriptionPool, readRotationConfig } = await import(${JSON.stringify(new URL('../subscription-state.ts', import.meta.url).href)});
+    const { writeSubscriptionPool } = await import(${JSON.stringify(new URL('../subscription-state.ts', import.meta.url).href)});
     await writeSubscriptionPool('anthropic', ${JSON.stringify(pool)});
     const realEngine = { createAgentSessionServices, createAgentSessionFromServices, SessionManager, VERSION };
     const engine = {
@@ -160,7 +185,7 @@ function runIsolatedManagedLaunch(pool) {
       },
     };
     const { session } = await buildBrokerSession(engine, { cwd: ${JSON.stringify(cwd)}, extensionPaths: [${JSON.stringify(C3_EXT)}], model: 'anthropic/cooling-model' });
-    console.log(JSON.stringify({ provider: session.model?.provider, id: session.model?.id, preferred: readRotationConfig().preferredModel }));
+    console.log(JSON.stringify({ provider: session.model?.provider, id: session.model?.id }));
     session.dispose();
   `;
     try {
@@ -177,8 +202,23 @@ function runIsolatedManagedLaunch(pool) {
         rmSync(cwd, { recursive: true, force: true });
     }
 }
-test('C3f — broker launch falls back to a non-managed provider when no managed provider is authenticated', async () => {
+test('C3f — a logical request can reach a non-managed raw-registry fallback when no managed provider is authenticated', async () => {
     const cwd = mkdtempSync(join(tmpdir(), 'crtr-c3c-'));
+    const priorIntent = process.env['CRTR_MODEL_INTENT'];
+    const priorNodeCwd = process.env['CRTR_NODE_CWD'];
+    process.env['CRTR_MODEL_INTENT'] = 'custom/strong';
+    process.env['CRTR_NODE_CWD'] = cwd;
+    mkdirSync(join(cwd, '.crouter'), { recursive: true });
+    writeFileSync(join(cwd, '.crouter', 'config.json'), `${JSON.stringify({
+        modelRoutes: {
+            c3: {
+                family: 'custom',
+                credentialSource: 'user',
+                providerId: 'c3prov',
+                models: { strong: 'c3prov/c3model' },
+            },
+        },
+    })}\n`);
     try {
         const deterministicEngine = {
             ...realEngine,
@@ -209,6 +249,14 @@ test('C3f — broker launch falls back to a non-managed provider when no managed
         }
     }
     finally {
+        if (priorIntent === undefined)
+            delete process.env['CRTR_MODEL_INTENT'];
+        else
+            process.env['CRTR_MODEL_INTENT'] = priorIntent;
+        if (priorNodeCwd === undefined)
+            delete process.env['CRTR_NODE_CWD'];
+        else
+            process.env['CRTR_NODE_CWD'] = priorNodeCwd;
         rmSync(cwd, { recursive: true, force: true });
     }
 });
@@ -218,7 +266,6 @@ test('C3g — an explicit managed subscription pool authenticates a registered r
     ]);
     assert.equal(selected.provider, 'anthropic');
     assert.equal(selected.id, 'cooling-model');
-    assert.equal(selected.preferred, undefined);
 });
 test('C3h — a cooling managed launch target boots model-less rather than falling back to a non-managed provider', () => {
     // The managed anthropic target is registered + pool-authenticated but COOLING
@@ -233,7 +280,6 @@ test('C3h — a cooling managed launch target boots model-less rather than falli
     ]);
     assert.equal(selected.provider, 'unknown');
     assert.equal(selected.id, 'unknown');
-    assert.equal(selected.preferred, undefined);
 });
 // (C4 — project guidance now comes from the document substrate: crouter keeps
 // `noContextFiles: true` in buildBrokerSession, and buildContextIntro's
@@ -271,24 +317,6 @@ test('C2 — zero-writable UI context resolves dialogs to deny/cancel immediatel
     assert.equal(await ctx.input('name'), undefined, 'C2: input() cancels (undefined)');
     assert.equal(await ctx.editor('edit'), undefined, 'C2: editor() cancels (undefined)');
 });
-test('broker UI exposes the live provider pin policy to package extensions', () => {
-    let pinned = false;
-    const ctx = makeBrokerUiContext({
-        writable: () => [],
-        forward: () => { },
-        pending: new Map(),
-        broadcast: () => { },
-        providerRotationPolicy: () => pinned
-            ? { allowCrossProviderFallback: false, reason: 'provider-pinned' }
-            : { allowCrossProviderFallback: true },
-    });
-    assert.deepEqual(readManagedProviderRotationPolicy(ctx), { allowCrossProviderFallback: true });
-    pinned = true;
-    assert.deepEqual(readManagedProviderRotationPolicy(ctx), {
-        allowCrossProviderFallback: false,
-        reason: 'provider-pinned',
-    }, 'the same running UI context observes a live set_model pin change');
-});
 // ===========================================================================
 // M2 (review mq5wkqep / T4) — REPLACES the Wave-0 M-1 cancel-on-detach. A dialog
 // forwarded to a writable viewer that then DETACHES must NOT be cancelled: it

package/dist/core/__tests__/full/broker-provider-retry.test.js

@@ -5,14 +5,13 @@
 // exercises runBroker's live retry handler rather than its helpers in isolation.
 import { test, before, after, afterEach } from 'node:test';
 import assert from 'node:assert/strict';
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { createHeadlessHarness } from '../helpers/harness.js';
 import { createAttachKit } from '../helpers/broker-clients.js';
 import { defaultModelLaddersConfig } from '../../../types.js';
 import { readFault } from '../../runtime/fault.js';
 import { normalizeModel } from '../../runtime/launch.js';
-import { setModelLive } from '../../runtime/model-swap.js';
 const MODEL_LADDERS = defaultModelLaddersConfig();
 function resolvedModel(spec) {
     const normalized = normalizeModel(spec, MODEL_LADDERS);
@@ -21,9 +20,8 @@ function resolvedModel(spec) {
     assert.notEqual(slash, -1, `${spec} must normalize to a qualified provider/model spec`);
     const provider = modelSpec.slice(0, slash);
     const id = modelSpec.slice(slash + 1);
-    return { spec: normalized, model: { provider, id }, pin: { providerId: provider, modelId: id } };
+    return { spec: normalized, model: { provider, id } };
 }
-const ANTHROPIC_STRONG = resolvedModel('anthropic/strong');
 const OPENAI_STRONG = resolvedModel('openai/strong');
 let h;
 const kit = createAttachKit(() => h);
@@ -39,20 +37,6 @@ function seedPool(provider, cooling) {
             rateLimitedUntil: cooling ? Date.now() + 60_000 : 0, lastAttemptAt: 0, lastRateLimitedAt: 0,
         }]));
 }
-function rotationPath() {
-    return join(h.agentHome, '.pi', 'agent', 'provider-rotation.json');
-}
-function clearRotation() {
-    rmSync(rotationPath(), { force: true });
-}
-function preferred() {
-    try {
-        return JSON.parse(readFileSync(rotationPath(), 'utf8')).preferredModel;
-    }
-    catch {
-        return undefined;
-    }
-}
 function model(id) {
     return JSON.parse(readFileSync(join(h.home, 'nodes', id, 'fake-pi.model.json'), 'utf8'));
 }
@@ -76,28 +60,6 @@ function agentStartCount(id) {
         return 0;
     }
 }
-async function autoRetry(id, expected) {
-    h.fakeCmd(id, { cmd: 'auto_retry', errorMessage: 'rate limit exceeded' });
-    await h.waitFor(() => {
-        try {
-            return assert.deepEqual(model(id), expected) === undefined ? true : false;
-        }
-        catch {
-            return false;
-        }
-    }, { label: `auto-retry switch for ${id}` });
-}
-// The auto-retry receipt file's timestamp, so re-firing auto_retry a second/
-// third time in one test doesn't false-positive on a STALE receipt that
-// already existed from an earlier fire in the same test.
-function autoRetryAt(id) {
-    try {
-        return JSON.parse(readFileSync(join(h.home, 'nodes', id, 'fake-pi.auto-retry.json'), 'utf8')).at;
-    }
-    catch {
-        return 0;
-    }
-}
 before(async () => {
     h = await createHeadlessHarness({ sessionPrefix: 'crtr-provider-retry' });
 });
@@ -108,61 +70,12 @@ after(async () => {
 afterEach(() => {
     kit.closeAll();
 });
-test('broker auto-retry preserves the launch requested pin, clears it on restoration, and never persists the temporary fallback', { timeout: 30_000 }, async () => {
-    const parent = h.spawnRoot('provider retry parent');
-    seedPool('anthropic', true);
-    seedPool('openai-codex', false);
-    clearRotation();
-    const child = await h.spawnHeadlessChild(parent, 'launch fallback then retry', { model: ANTHROPIC_STRONG.spec });
-    assert.deepEqual(model(child), OPENAI_STRONG.model, 'a cooling requested managed launch starts its viable equivalent');
-    assert.deepEqual(preferred(), ANTHROPIC_STRONG.pin, 'launch retains the requested managed model as its restoration pin');
-    const before = h.node(child);
-    seedPool('anthropic', false);
-    await autoRetry(child, ANTHROPIC_STRONG.model);
-    await h.waitFor(() => preferred() === undefined, { label: 'launch preferred pin cleared after restoration' });
-    assert.deepEqual(preferred(), undefined, 'reaching the launch-requested provider fulfils and clears its temporary pin');
-    const after = h.node(child);
-    assert.equal(after.model_override, before.model_override, 'turn-time fallback never overwrites the durable model override');
-    assert.equal(after.launch?.model, before.launch?.model, 'turn-time fallback never overwrites the durable launch recipe');
-});
-test('broker auto-retry records its current managed model only when no restoration pin exists', { timeout: 30_000 }, async () => {
-    const parent = h.spawnRoot('normal retry parent');
-    seedPool('anthropic', false);
-    seedPool('openai-codex', false);
-    clearRotation();
-    // Establish the exact qualified OpenAI ladder cell, then explicitly release
-    // its structural pin so this test reaches the retry resolver by construction.
-    const child = await h.spawnHeadlessChild(parent, 'normal retry', { model: OPENAI_STRONG.spec });
-    await setModelLive(child, OPENAI_STRONG.spec, false);
-    clearRotation();
-    const before = h.node(child);
-    assert.deepEqual(model(child), OPENAI_STRONG.model);
-    await autoRetry(child, ANTHROPIC_STRONG.model);
-    await h.waitFor(() => {
-        try {
-            assert.deepEqual(preferred(), OPENAI_STRONG.pin);
-            return true;
-        }
-        catch {
-            return false;
-        }
-    }, { label: 'normal retry preferred model recorded' });
-    assert.deepEqual(preferred(), OPENAI_STRONG.pin, 'a normal automatic switch records its failed managed model for later restoration');
-    const after = h.node(child);
-    assert.equal(after.model_override, before.model_override);
-    assert.equal(after.launch?.model, before.launch?.model);
-});
 test('a managed-cooling terminal authors a rate-limit auto fault whose deadline drives exactly one broker re-drive', { timeout: 30_000 }, async () => {
     const parent = h.spawnRoot('cooling terminal parent');
     // The terminal fault path is pool-independent — the stophook classifies purely
     // off the errorMessage text + the cooling diagnostic, so pool state is inert.
-    // A qualified openai-codex id now pins structurally, but that has no effect
-    // here either way: this test never triggers retry/not-found policy (only the
-    // stophook fault path + launch-time pinnedToFirst, which is a no-op because
-    // the pool isn't cooling at spawn).
     seedPool('anthropic', false);
     seedPool('openai-codex', false);
-    clearRotation();
     const child = await h.spawnHeadlessChild(parent, 'cooling terminal', { model: OPENAI_STRONG.spec });
     await h.waitFor(() => agentStartCount(child) >= 1, { label: 'initial cooling fixture turn started' });
     const baselineStarts = agentStartCount(child);
@@ -332,47 +245,18 @@ test('raw overflow settling without compaction terminates instead of hanging', {
     await h.tick();
     assert.equal(h.status(child), 'dead', 'settled raw overflow cannot leave the child hanging');
 });
-test("a live set_model decision updates the running broker's pin policy immediately, in both directions, without a revive", { timeout: 30_000 }, async () => {
-    const parent = h.spawnRoot('live pin policy parent');
-    seedPool('anthropic', false);
-    seedPool('openai-codex', false);
-    clearRotation();
-    // Establish the desired qualified Anthropic ladder cell while explicitly
-    // keeping its live retry policy unpinned, independent of ambient defaults.
-    const child = await h.spawnHeadlessChild(parent, 'live pin policy', { model: ANTHROPIC_STRONG.spec });
-    await setModelLive(child, ANTHROPIC_STRONG.spec, false);
-    clearRotation();
-    assert.deepEqual(model(child), ANTHROPIC_STRONG.model, 'explicit setup selects the current Anthropic strong model');
-    // false → true, LIVE: an explicit raw qualified re-pick pins the SAME
-    // resolved model — no model value changes, only the live pin decision. The
-    // running broker's retry-fallback policy (broker.ts's cfg.modelProviderPinned
-    // read) enforces it on the VERY NEXT retry, with no revive in between: the
-    // auto_retry below is suppressed rather than allowed to rotate the model.
-    await setModelLive(child, ANTHROPIC_STRONG.spec, true);
-    assert.deepEqual(model(child), ANTHROPIC_STRONG.model, 'the explicit re-pick keeps the same resolved model');
-    const priorAt1 = autoRetryAt(child);
-    h.fakeCmd(child, { cmd: 'auto_retry', errorMessage: 'rate limit exceeded' });
-    await h.waitFor(() => autoRetryAt(child) > priorAt1, { label: 'pinned auto-retry processed' });
-    // Settle past the fallback's own async continuation window.
-    await new Promise((resolve) => setTimeout(resolve, 500));
-    assert.deepEqual(model(child), ANTHROPIC_STRONG.model, 'a live pin suppresses turn-time provider rotation immediately, without revive');
-    assert.deepEqual(preferred(), undefined, 'a suppressed retry records no restoration pin');
-    // true → false, LIVE: an explicit re-pick of the same qualified model with
-    // pinned=false releases the pin. The next retry must now be free to rotate.
-    await setModelLive(child, ANTHROPIC_STRONG.spec, false);
-    await autoRetry(child, OPENAI_STRONG.model);
-    assert.deepEqual(preferred(), ANTHROPIC_STRONG.pin, 'the released pin lets the next retry rotate and record a restoration pin');
-});
-test('a picker-originated set_model frame with no pinned field derives the pin from the real registry provider namespace; an internal no-raw-token path preserves it', { timeout: 30_000 }, async () => {
+test('an explicit picker choice pins and clears prior logical routing; an internal no-raw-token path preserves that decision', { timeout: 30_000 }, async () => {
     const parent = h.spawnRoot('picker frame parent');
     seedPool('anthropic', false);
     seedPool('openai-codex', false);
-    const child = await h.spawnHeadlessChild(parent, 'picker frame child', { model: 'strong' }); // unpinned boot
+    const child = await h.spawnHeadlessChild(parent, 'picker frame child', { model: 'openai/strong' }); // logical route boot
     const ctrl = await kit.attach(child, 'controller', 'picker-test');
     ctrl.send({ type: 'set_model', model: OPENAI_STRONG.spec }); // exactly what buildModelPicker sends — no `pinned`
     await ctrl.waitFrame((f) => f.type === 'ack' && f.for === 'set_model', 'picker set_model acked');
     let after = h.node(child);
     assert.equal(after.launch?.modelProviderPinned, true, 'the omitted-pinned frame derives pinned from the real openai-codex registry namespace');
+    assert.equal(after.launch?.modelIntent, undefined, 'the explicit concrete choice clears the logical launch intent');
+    assert.equal(after.launch?.env.CRTR_MODEL_INTENT, undefined, 'a revive cannot restore the stale logical route intent');
     // `cycle_ladder` — an internal no-raw-token path (no `model`/`pinned` on the
     // frame at all) — reuses the SAME resolve+setModel machinery `set_model` does
     // (real `nextLadderModel`/`resolveModelQuery`, the fake engine's real

package/dist/core/__tests__/model-pin-durability.test.js

@@ -2,8 +2,8 @@
 //
 // `modelProviderPinned` is durable node state with ONE derivation rule: it is
 // decided exactly once, at an explicit user model change, from that change's
-// RAW pre-normalize token — a qualified `<provider>/<model-id>` or
-// `<provider>/<tier>` token pins; a bare tier (`ultra`) or bare family alias
+// RAW pre-normalize token — a concrete `<provider>/<model-id>` token pins;
+// logical `<family>/<tier>` refs, bare tiers (`ultra`), and family aliases
 // (`opus`/`sonnet`/`haiku`) unpins. Every other rebuild or persist (a
 // polymorph/lifecycle change with no new `--model`, a dormant model write whose
 // spec happens to normalize to a concrete cell, cycle_model/cycle_ladder,
@@ -77,11 +77,11 @@ test('fixture: a bare tier is unpinned; its normalized concrete cell reads as pi
     assert.equal(isProviderPinnedModelToken('ultra'), false, 'a bare tier is unpinned');
     assert.equal(isProviderPinnedModelToken(ULTRA_CELL), true, 'a qualified concrete cell reads as pinned');
 });
-test('a qualified provider/id or provider/tier token pins structurally, across real registry provider namespaces', () => {
+test('only concrete provider/id tokens pin; logical family/tier refs remain preferences', () => {
     assert.equal(isProviderPinnedModelToken('anthropic/claude-fable-5:high'), true, 'a concrete anthropic id pins');
     assert.equal(isProviderPinnedModelToken('openai-codex/gpt-5.6-sol:max'), true, 'the real openai-codex registry namespace pins, not just the family alias `openai`');
     assert.equal(isProviderPinnedModelToken('amazon-bedrock/some-model-id'), true, 'any qualified provider/id pins — no undocumented exception for a provider outside the three built-in families');
-    assert.equal(isProviderPinnedModelToken('openai/ultra'), true, 'a qualified provider/tier pins too');
+    assert.equal(isProviderPinnedModelToken('openai/ultra'), false, 'a qualified family/tier ref is logical and unpinned');
     assert.equal(isProviderPinnedModelToken('ultra'), false, 'a bare tier has no `/` and stays unpinned');
     assert.equal(isProviderPinnedModelToken('opus'), false, 'a bare family alias has no `/` and stays unpinned');
 });
@@ -114,11 +114,13 @@ test('a deliberately tier-run node is not wrongly re-pinned when a rebuild or pe
     // the concrete spec ULTRA_CELL normalizes to.
     createNode(node('tier-node', {
         model_override: ULTRA_CELL,
-        launch: { extensions: [], env: {}, model: ULTRA_CELL, modelProviderPinned: true },
+        launch: { extensions: [], env: { CRTR_MODEL_INTENT: 'openai/ultra' }, model: ULTRA_CELL, modelIntent: { family: 'openai', strength: 'ultra' }, modelProviderPinned: true },
     }));
     persistDormantModel('tier-node', ULTRA_CELL, false);
     const after = getNode('tier-node');
     assert.equal(after?.launch?.model, ULTRA_CELL, 'the concrete spec is persisted as the launch model');
     assert.equal(after?.model_override, ULTRA_CELL, 'the concrete spec is persisted as the override');
+    assert.equal(after?.launch?.modelIntent, undefined, 'an explicit concrete choice clears the prior logical route intent');
+    assert.equal(after?.launch?.env.CRTR_MODEL_INTENT, undefined, 'the revived broker does not inherit the prior logical route intent');
     assert.equal(after?.launch?.modelProviderPinned, false, 'an explicit bare-tier decision clears a prior pin — the raw-token decision wins over the concrete spec shape');
 });

package/dist/core/__tests__/model-routes.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/model-routes.test.js

@@ -0,0 +1,41 @@
+import { after, before, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { expandModelCandidates } from '../model-routes.js';
+const previousHome = process.env.HOME;
+let home = '';
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-model-routes-'));
+    process.env.HOME = home;
+    mkdirSync(join(home, '.crouter'), { recursive: true });
+    writeFileSync(join(home, '.crouter', 'config.json'), JSON.stringify({
+        modelRoutes: {
+            'anthropic-user': { family: 'anthropic', credentialSource: 'user', providerId: 'anthropic', models: { strong: 'anthropic/a-strong', medium: 'anthropic/a-medium', light: 'anthropic/a-light' } },
+            'openai-user': { family: 'openai', credentialSource: 'user', providerId: 'openai-codex', models: { strong: 'openai-codex/o-strong', medium: 'openai-codex/o-medium', light: 'openai-codex/o-light' } },
+            'anthropic-funded': { family: 'anthropic', credentialSource: 'northlight', providerId: 'funded-anthropic', models: { strong: 'funded-anthropic/a-strong', medium: 'funded-anthropic/a-medium', light: 'funded-anthropic/a-light' } },
+            'openai-funded': { family: 'openai', credentialSource: 'northlight', providerId: 'funded-openai', models: { strong: 'funded-openai/o-strong', medium: 'funded-openai/o-medium', light: 'funded-openai/o-light' } },
+        },
+        modelRouting: { credentialSourceOrder: ['user', 'northlight'], familyOrder: ['anthropic', 'openai'], strengthFallback: ['medium', 'light'] },
+    }));
+});
+after(() => {
+    if (previousHome === undefined)
+        delete process.env.HOME;
+    else
+        process.env.HOME = previousHome;
+    rmSync(home, { recursive: true, force: true });
+});
+test('declared routes expand credential source, strength, then family preference', () => {
+    const candidates = expandModelCandidates({ kind: 'logical', family: 'openai', strength: 'strong', spec: 'openai-codex/o-strong' }, home, null);
+    assert.deepEqual(candidates.map((candidate) => `${candidate.credentialSource}/${candidate.family}/${candidate.strength}`), [
+        'user/openai/strong', 'user/anthropic/strong', 'user/openai/medium', 'user/anthropic/medium', 'user/openai/light', 'user/anthropic/light',
+        'northlight/openai/strong', 'northlight/anthropic/strong', 'northlight/openai/medium', 'northlight/anthropic/medium', 'northlight/openai/light', 'northlight/anthropic/light',
+    ]);
+    assert.deepEqual(candidates.map((candidate) => candidate.rank), [...Array(12).keys()]);
+});
+test('concrete routes retain provider/model first and only move to same-model credential sources', () => {
+    const candidates = expandModelCandidates({ kind: 'concrete', spec: 'anthropic/a-strong' }, home, null);
+    assert.deepEqual(candidates.map((candidate) => `${candidate.providerId}/${candidate.modelId}`), ['anthropic/a-strong', 'funded-anthropic/a-strong']);
+});

package/dist/core/__tests__/review-model-floor.test.js

@@ -68,7 +68,7 @@ test('review still permits equal-or-stronger explicit models', () => {
     assert.equal(spec('review', 'strong'), expected('strong'));
     assert.equal(spec('review', 'ultra'), expected('ultra'));
 });
-test('explicit provider-qualified overrides preserve their provider pin through launch construction', () => {
+test('concrete overrides stay pinned while logical provider/strength overrides remain unpinned', () => {
     const qualified = buildLaunchSpec('developer', 'base', {
         lifecycle: 'terminal', hasManager: true, cwd: home, profileId: null, model: 'anthropic/ultra',
     }).launch;
@@ -78,7 +78,7 @@ test('explicit provider-qualified overrides preserve their provider pin through
     const bare = buildLaunchSpec('developer', 'base', {
         lifecycle: 'terminal', hasManager: true, cwd: home, profileId: null, model: 'ultra',
     }).launch;
-    assert.equal(qualified.modelProviderPinned, true);
+    assert.equal(qualified.modelProviderPinned, false);
     assert.equal(exact.modelProviderPinned, true);
     assert.equal(bare.modelProviderPinned, false);
 });

package/dist/core/auth-file.d.ts

@@ -20,8 +20,9 @@ export declare function readAuthCredentials(authPath?: string): Promise<AuthFile
 export declare function readAuthCredential(providerId: string, authPath?: string): Promise<Credential | undefined>;
 /** Persist one provider's credential under the auth.json lock, leaving every other entry intact. */
 export declare function setAuthCredential(providerId: string, credential: Credential, authPath?: string): Promise<void>;
-/** Remove one provider's credential (logout) under the auth.json lock. */
-export declare function deleteAuthCredential(providerId: string, authPath?: string): Promise<void>;
+/** Remove one provider's credential (logout) under the auth.json lock. Returns
+ * whether a record was removed from the exact snapshot this write replaced. */
+export declare function deleteAuthCredential(providerId: string, authPath?: string): Promise<boolean>;
 /**
  * The `CredentialStore` crouter hands to `ModelRuntime`. Backed directly by auth.json rather
  * than by an in-memory cache, so `modify` is a real cross-process read-modify-write: pi's

package/dist/core/auth-file.js

@@ -126,12 +126,14 @@ export async function setAuthCredential(providerId, credential, authPath = defau
         return { result: undefined, next: serialize(data) };
     });
 }
-/** Remove one provider's credential (logout) under the auth.json lock. */
+/** Remove one provider's credential (logout) under the auth.json lock. Returns
+ * whether a record was removed from the exact snapshot this write replaced. */
 export async function deleteAuthCredential(providerId, authPath = defaultAuthPath()) {
-    await new LockedJsonFile(authPath).withLockAsync(async (current) => {
+    return new LockedJsonFile(authPath).withLockAsync(async (current) => {
         const data = parse(current);
+        const removed = Object.hasOwn(data, providerId);
         delete data[providerId];
-        return { result: undefined, next: serialize(data) };
+        return { result: removed, next: serialize(data) };
     });
 }
 /**

package/dist/core/canvas/types.d.ts

@@ -25,7 +25,12 @@ export type EdgeType = 'subscribes_to' | 'spawned_by';
 export interface LaunchSpec {
     /** Model id/pattern passed to pi `--model`. */
     model?: string;
-    /** True only for a caller's explicit `provider/tier` or `provider/id` override. */
+    /** Original logical family/strength preference, retained after normalization. */
+    modelIntent?: {
+        family: string;
+        strength: import('../../types.js').ModelStrength;
+    };
+    /** True only for a caller's explicit concrete `provider/id` override. */
     modelProviderPinned?: boolean;
     /** True for an exact-consult launch: `model` is the verbatim captured
      *  `provider/id:thinking` spec, bypassing the review floor/normalize and

package/dist/core/config.d.ts

@@ -1,4 +1,4 @@
-import type { Scope, ScopeConfig, ScopeState, KindConfig, ModelLaddersConfig, ModelProvider, ModelStrength } from '../types.js';
+import type { Scope, ScopeConfig, ScopeState, KindConfig, ModelLaddersConfig, ModelProvider, ModelStrength, ModelRouteConfig, ModelRoutingConfig } from '../types.js';
 export declare function configPath(scope: Scope): string | null;
 export declare function statePath(scope: Scope): string | null;
 export declare function readConfig(scope: Scope): ScopeConfig;
@@ -33,6 +33,8 @@ export declare function readRawScopeConfig(scope: Scope): Partial<ScopeConfig> |
 export interface MergedLaunchConfig {
     kinds: Record<string, KindConfig>;
     modelLadders: ModelLaddersConfig;
+    modelRoutes?: Record<string, ModelRouteConfig>;
+    modelRouting?: ModelRoutingConfig;
     /** The merged `spawnEnv.allow` set (project stack > profile > user >
      *  builtin, additive) — read by `buildOperationalEnvBase`
      *  (`core/runtime/spawn-env.ts`) as source C of the broker spawn-env