@north-light/crouter 0.3.161 → 0.3.163

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__/migration.test.js

@@ -7,12 +7,17 @@ import { fileURLToPath } from 'node:url';
 import { DatabaseSync } from 'node:sqlite';
 import { openDb, closeDb, migrate, MIGRATIONS } from '../canvas/db.js';
 import { canvasDbPath, ensureHome } from '../canvas/paths.js';
-import { CANVAS_EXTENSION_NAMES, customExtensionPaths } from '../canvas/extensions.js';
+import { customExtensionPaths } from '../canvas/extensions.js';
 import { updateNode } from '../canvas/canvas.js';
 import { spawn, spawnSync } from 'node:child_process';
 const HERE = dirname(fileURLToPath(import.meta.url));
 const RUNTIME_COLUMNS = ['intent', 'pi_pid', 'window', 'tmux_session'];
 const RACE_FIXTURE = join(HERE, 'fixtures', 'metadata-migration-race.ts');
+const PRE_TOOL_GUIDE_CANVAS_EXTENSION_NAMES = [
+    'canvas-inbox-watcher', 'canvas-stophook', 'canvas-recap',
+    'canvas-goal-capture', 'canvas-passive-context', 'canvas-context-intro',
+    'canvas-doc-substrate', 'canvas-structured-output', 'canvas-bash-valve',
+];
 let home;
 async function waitForPath(path) {
     for (;;) {
@@ -76,7 +81,7 @@ test('a v14 canvas normalizes historical canvas paths while retaining custom lau
         node_id: 'saved', name: 'saved', created: '2026-01-01T00:00:00.000Z', cwd: '/tmp',
         kind: 'developer', mode: 'base', lifecycle: 'terminal', status: 'idle',
         launch: { extensions: [
-                ...CANVAS_EXTENSION_NAMES.map((name) => `/old-generation/pi-extensions/${name}.js`),
+                ...PRE_TOOL_GUIDE_CANVAS_EXTENSION_NAMES.map((name) => `/old-generation/pi-extensions/${name}.js`),
                 '/plugins/canvas-inbox-watcher.js',
             ] },
     }));
@@ -102,7 +107,7 @@ test('a v14 migration is protected against concurrent writeback by normal update
         lifecycle: 'terminal',
         status: 'idle',
         launch: {
-            extensions: [...CANVAS_EXTENSION_NAMES.map((name) => `/old-generation/pi-extensions/${name}.js`), '/plugins/canvas-inbox-watcher.js'],
+            extensions: [...PRE_TOOL_GUIDE_CANVAS_EXTENSION_NAMES.map((name) => `/old-generation/pi-extensions/${name}.js`), '/plugins/canvas-inbox-watcher.js'],
         },
     }));
     ensureHome();

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__/on-read-crouter-home-fence.test.js

@@ -1,12 +1,8 @@
-// The on-read POSITIONAL walk must never treat the crouter home (`~/.crouter`,
-// the user scope root) as a project ancestor. Canvas runtime artifacts live at
-// `~/.crouter/canvas/nodes/<id>/{reports,context}/...`, so a naive ancestor
-// walk from such a read climbs THROUGH `~/.crouter` and would inject whatever
-// lives at `~/.crouter/.crouter/memory/` — e.g. a differently-scoped node whose
-// cwd resolved its private project store there. That leaks one node's private
-// memory into every unrelated node that reads a canvas file. This test pins the
-// fence: reading a canvas artifact must not surface a store nested in the
-// crouter home.
+// Explicit file-context discovery never treats the crouter home
+// (`~/.crouter`, the user scope root) as a project ancestor. Canvas runtime
+// artifacts live below that root, while a nested `~/.crouter/.crouter/memory/`
+// store can belong to a differently scoped node. The user-root fence keeps its
+// explicitly routed docs out of unrelated canvas-file reads.
 //
 // Run: node --import tsx/esm --test src/core/__tests__/on-read-crouter-home-fence.test.ts
 import { test, before, beforeEach, after } from 'node:test';
@@ -54,7 +50,8 @@ test('a store nested in the crouter home does not leak into a canvas-artifact re
     mkdirSync(leakedStore, { recursive: true });
     writeFileSync(join(leakedStore, 'private-thing.md'), '---\nkind: knowledge\n' +
         "when-and-why-to-read: When X, read this because Y.\n" +
-        'file-read-visibility: content\n---\n' +
+        'file-read-visibility: content\n' +
+        'applies-to: "**/*.md"\n---\n' +
         'PRIVATE ASSISTANT MEMORY MUST NOT LEAK\n');
     // A canvas runtime artifact under the crouter home — the shape of every node
     // report/context file the harness auto-reads.

package/dist/core/__tests__/on-read-dedup-resume.test.js

@@ -1,17 +1,6 @@
-// Bug-regression: on-read doc injection "fires a second time per session".
-//
-// The on-read substrate hook dedups so a doc surfaces at most once per
-// conversation. That dedup set USED to live only in the pi process heap (cleared
-// on session_start). But a node's logical session — the .jsonl transcript —
-// spans MULTIPLE pi processes: a dormancy → revive(resume) cycle exits the old
-// process and launches a fresh `pi --session` that REUSES the same transcript.
-// The fresh process started with an empty set, so any doc already injected
-// before dormancy got injected AGAIN on the next read.
-//
-// The fix persists the set to nodes/<id>/injected-docs.json: a resume rehydrates
-// it (dedup holds), and only the FRESH-transcript launch paths clear it. These
-// tests lock in both halves: the store round-trip, and the dedup surviving a
-// simulated revive(resume) while re-surfacing after a fresh launch.
+// On-read context surfaces at most once per conversation. The dedup set lives
+// at nodes/<id>/injected-docs.json so a process resumed onto the same transcript
+// rehydrates it, while a fresh transcript clears it.
 //
 // Run: node --import tsx/esm --test src/core/__tests__/on-read-dedup-resume.test.ts
 import { test, before, beforeEach, after } from 'node:test';
@@ -64,7 +53,7 @@ test('injected-store round-trips and clears', () => {
     assert.ok(!existsSync(injectedDocsPath(node)), 'clear removes the file');
     assert.deepEqual([...loadInjectedDocs(node)], [], 'load after clear is empty');
 });
-test('user-global memory docs do not fire positionally for every file under home', () => {
+test('project and user memory docs without applies-to do not fire on file reads', () => {
     const fakeHome = mkdtempSync(join(tmpdir(), 'crtr-onread-user-home-'));
     process.env['HOME'] = fakeHome;
     resetScopeCache();
@@ -72,33 +61,32 @@ test('user-global memory docs do not fire positionally for every file under home
     const userMemDir = join(fakeHome, '.crouter', 'memory');
     mkdirSync(userMemDir, { recursive: true });
     writeFileSync(join(userMemDir, 'noisy-global.md'), '---\nkind: preference\n' +
-        'when-and-why-to-read: When reading any file, this preference should be read because this fixture must not fire positionally\n' +
+        'when-and-why-to-read: When reading any file, this preference should be read because this fixture must not fire without an explicit route\n' +
         'file-read-visibility: content\n---\n' +
         'NOISY USER BODY\n');
     const projectMemDir = join(fakeHome, 'work', '.crouter', 'memory');
     mkdirSync(projectMemDir, { recursive: true });
     writeFileSync(join(projectMemDir, 'local.md'), '---\nkind: knowledge\n' +
-        'when-and-why-to-read: When reading project files, this reference should be read because local project memories remain positional\n' +
+        'when-and-why-to-read: When reading project files, this reference should be read because this fixture proves explicit file routing\n' +
         'file-read-visibility: content\n---\n' +
         'LOCAL PROJECT BODY\n');
     const readFile = join(fakeHome, 'work', 'ideas.md');
     writeFileSync(readFile, 'turn off xml closer\n');
     const rendered = renderOnReadDocs(node, readFile, new Set());
-    assert.ok(!rendered.includes('NOISY USER BODY'), 'user-global doc is not positional');
-    assert.ok(rendered.includes('LOCAL PROJECT BODY'), 'project doc still fires positionally');
-    assert.ok(rendered.includes('<memory kind="knowledge" name="local"'), 'memory docs render as memory tags');
-    assert.ok(!rendered.includes('triggered-by='), 'read target is not repeated on child items');
-    assert.ok(!rendered.includes('<auto-loaded-context file='), 'read target is not repeated on the wrapper');
+    assert.ok(!rendered.includes('NOISY USER BODY'), 'user-global doc has no explicit file route');
+    assert.ok(!rendered.includes('LOCAL PROJECT BODY'), 'project doc also has no implicit file route');
+    assert.equal(rendered, '', 'no file context renders without an explicit trigger');
     rmSync(fakeHome, { recursive: true, force: true });
 });
 test('on-read doc surfaces once, stays deduped across a revive(resume), re-surfaces after a fresh launch', () => {
     const node = spawnNode({ kind: 'general', cwd: work, parent: null }).node_id;
-    // A positional substrate doc in a `.crouter/memory/` ancestor of the read file.
+    // A file-routed substrate doc in a `.crouter/memory/` ancestor.
     const memDir = join(work, '.crouter', 'memory');
     mkdirSync(memDir, { recursive: true });
     writeFileSync(join(memDir, 'onread-fixture.md'), '---\nkind: knowledge\n' +
         'when-and-why-to-read: When reading work files, this reference should be read because it is the on-read regression fixture\n' +
-        'file-read-visibility: content\n---\n' +
+        'file-read-visibility: content\n' +
+        'applies-to: "src/**"\n---\n' +
         `${FIXTURE_BODY}\n`);
     const readFile = join(work, 'src', 'file.ts');
     mkdirSync(join(work, 'src'), { recursive: true });
@@ -113,7 +101,7 @@ test('on-read doc surfaces once, stays deduped across a revive(resume), re-surfa
     // --- dormancy → revive(resume): NEW process rehydrates the set from disk ---
     const seenAfterRevive = loadInjectedDocs(node);
     assert.deepEqual(seenAfterRevive, seen, 'revive(resume) rehydrates the persisted dedup set');
-    assert.ok(!renderOnReadDocs(node, readFile, seenAfterRevive).includes(FIXTURE_BODY), 'resumed process does NOT re-inject the doc (the bug)');
+    assert.ok(!renderOnReadDocs(node, readFile, seenAfterRevive).includes(FIXTURE_BODY), 'resumed process does not re-inject the doc');
     // --- fresh launch (revive resume=false, e.g. a refresh-yield) clears the set ---
     clearInjectedDocs(node);
     const seenFresh = loadInjectedDocs(node);

package/dist/core/__tests__/on-read-identity.test.js

@@ -1,13 +1,7 @@
-// The on-read POSITIONAL loader resolves a doc's identity with the SAME
+// The explicit file-context loader resolves a doc's identity with the same
 // explicit-name-then-path-fallback rule the boot resolver uses (schema.ts's
 // resolveDocName), never deriving `name` from the physical path alone.
 //
-// A migrated AGENTS.md doc (`crtr sys sync project-guidance`'s CLAUDE.md/AGENTS.md conversion)
-// is written at `file-read-visibility: content` with an explicit frontmatter
-// `name` (the project label, e.g. `crouter`) so sibling project roots do not
-// collapse onto the shared `AGENTS` leaf. `loadPositionalDoc` must inject the
-// doc under that explicit name, not the path-derived `AGENTS`.
-//
 // Run: node --import tsx/esm --test src/core/__tests__/on-read-identity.test.ts
 import { test, before, beforeEach, after } from 'node:test';
 import assert from 'node:assert/strict';
@@ -47,22 +41,21 @@ after(() => {
     else
         process.env['HOME'] = prevHomeEnv;
 });
-test('a migrated AGENTS doc injects on-read under its explicit frontmatter name, not the path-derived one', () => {
+test('an explicitly routed doc injects on-read under its frontmatter name, not the path-derived one', () => {
     const node = spawnNode({ kind: 'general', cwd: work, parent: null }).node_id;
-    // Shape of a `crtr sys sync project-guidance` CLAUDE.md/AGENTS.md migration: physical filename
-    // stays AGENTS.md, but frontmatter carries the project's explicit identity.
     const memDir = join(work, '.crouter', 'memory');
     mkdirSync(memDir, { recursive: true });
-    writeFileSync(join(memDir, 'AGENTS.md'), '---\nkind: knowledge\n' +
+    writeFileSync(join(memDir, 'physical-guide.md'), '---\nkind: knowledge\n' +
         'name: acme-project\n' +
-        'when-and-why-to-read: When working in acme-project, this knowledge should be read because it is the project\'s operating guide.\n' +
-        'file-read-visibility: content\n---\n' +
+        'when-and-why-to-read: When reading acme source, this knowledge should be read because it carries the project-specific implementation constraints.\n' +
+        'file-read-visibility: content\n' +
+        'applies-to: "src/**"\n---\n' +
         'ACME PROJECT OPERATING GUIDE\n');
     const readFile = join(work, 'src', 'file.ts');
     mkdirSync(join(work, 'src'), { recursive: true });
     writeFileSync(readFile, 'export const x = 1;\n');
     const rendered = renderOnReadDocs(node, readFile, new Set());
-    assert.ok(rendered.includes('ACME PROJECT OPERATING GUIDE'), 'the migrated doc fires positionally');
+    assert.ok(rendered.includes('ACME PROJECT OPERATING GUIDE'), 'the matching explicit route fires');
     assert.ok(rendered.includes('<memory kind="knowledge" name="acme-project"'), `expected explicit frontmatter name "acme-project" in the injected envelope, got: ${rendered}`);
-    assert.ok(!rendered.includes('name="AGENTS"'), 'must not fall back to the path-derived name when frontmatter sets one');
+    assert.ok(!rendered.includes('name="physical-guide"'), 'must not fall back to the path-derived name when frontmatter sets one');
 });