Key-presence refusal at every gate: a pinned model is not enough

Owner-diagnosed: the turn gate checked only model coordinates, so a
pinned slot whose provider key was deleted passed the gate and died
mid-stream masked to 'An error occurred.' The key is now gated where
the model is — by what would RUN (env-first keyValue truth, so an
env-shadowed key passes).

- core/settings.ts: the provider_key_missing envelope family (code,
  provider, slots, human line naming the provider from AUTH_PROVIDER_KEYS
  labels) + ProviderKeyMissingError + isProviderKeyRefusal matcher.
- chat-handler turn gate: refuses 503 before beginTurn when the resolved
  conversation's provider key is gone (slots: [strong]).
- Job runner: same check via an injected dep (agent layer cannot read
  the key store) — a keyless engine refuses the spawn through the
  existing failure-shape convention, no phantom run.
- Extraction pipeline: refuseIfStagesUnready refuses BEFORE any batch
  (first offender: extractor before auditor); the trigger skips info-
  level, /api/graph/import surfaces the 503 envelope per file.
- Tests: 8 new pins (turn gate both ways, runner refusal, pipeline
  first-offender + pass-through, envelope factory, matcher); the three
  turn-driving suites seed OPENROUTER_API_KEY like any real setup.
- Doc fix: stale EXTRACTION.chunkTokens comment in the manual-extract
  route (left over from eed4b4e).

Known residual (pre-existing, flagged for master): the manual extract
route logs BOTH config refusals as console.error (fire-and-forget path);
the coverage ledger keeps everything uncovered either way.

tests/byok-refusal.test.ts

@@ -2,7 +2,13 @@ import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 import { parseModelsRefusal } from "../components/chat.tsx";
 import { prefillFromSlots, prefillLevelFromPin, setupStage } from "../components/setup-dialog.tsx";
-import { isModelsRefusal, modelsNotConfigured } from "../src/core/settings.ts";
+import {
+	isModelsRefusal,
+	isProviderKeyRefusal,
+	modelsNotConfigured,
+	providerKeyMissing,
+	PROVIDER_KEY_MISSING_CODE,
+} from "../src/core/settings.ts";
 import type { ModelCatalogEntry, ModelSlotName } from "../src/core/index.ts";
 
 /**
@@ -42,6 +48,35 @@ describe("isModelsRefusal — the job-record matcher", () => {
 	});
 });
 
+describe("providerKeyMissing — the envelope factory (provider-key interlude, 2026-09-25)", () => {
+	it("names the provider from the curated label and carries the exact machine code", () => {
+		const envelope = providerKeyMissing("openrouter", ["strong"]);
+		assert.deepEqual(envelope, {
+			error: "No OpenRouter key is set — add one in Settings → Keys",
+			code: PROVIDER_KEY_MISSING_CODE,
+			provider: "openrouter",
+			slots: ["strong"],
+		});
+		assert.equal(envelope.code, "provider_key_missing");
+	});
+
+	it("an unknown provider falls back to its raw id as the label", () => {
+		const envelope = providerKeyMissing("weird", ["cheap"]);
+		assert.equal(envelope.error, "No weird key is set — add one in Settings → Keys");
+	});
+});
+
+describe("isProviderKeyRefusal — the job-record matcher (provider-key interlude)", () => {
+	it("matches the envelope wording regardless of provider label, not real failures", () => {
+		assert.equal(isProviderKeyRefusal(providerKeyMissing("together", ["cheap"]).error), true);
+		assert.equal(isProviderKeyRefusal(providerKeyMissing("openai", ["strong"]).error), true);
+		assert.equal(isProviderKeyRefusal(""), false);
+		assert.equal(isProviderKeyRefusal(undefined), false);
+		assert.equal(isProviderKeyRefusal("FAILED: headless crashed"), false);
+		assert.equal(isProviderKeyRefusal(modelsNotConfigured(["strong"]).error), false, "the models refusal is a different failure");
+	});
+});
+
 describe("prefillFromSlots — the SetupDialog prefill (BYOK wave)", () => {
 	const entry = (id: string, provider: string): ModelCatalogEntry => ({
 		id,

tests/chat-flow.test.ts

@@ -36,6 +36,11 @@ import type { TeachingAgent } from "../src/agent/teacher-agent.ts";
 import type { UIMessage } from "ai";
 import { PATHS } from "../config.ts";
 
+// The key-presence turn gate (provider-key interlude, 2026-09-25): scripted
+// turns pin openrouter per chat — the gate reads env-first truth, so the
+// key must be present in the test process like any real setup.
+process.env.OPENROUTER_API_KEY ??= "test-key-presence-gate";
+
 const QUIZ_INPUT = {
 	question: "Which planet is closest to the sun?",
 	options: [
@@ -612,3 +617,56 @@ describe("the BYOK turn gate (no factory floor — owner, 2026-09-22)", () => {
 		await drain(res);
 	});
 });
+
+// ─── the key-presence turn gate (provider-key interlude, owner, 2026-09-25) ─
+
+describe("the key-presence turn gate (provider-key interlude, 2026-09-25)", () => {
+	// The gate's truth is env-first (keyValue): in tests process.env is the
+	// WHOLE truth (the throwaway data dir has no auth.json), so each test
+	// pins its provider's env var explicitly and restores it after.
+	it("a pinned provider whose key is gone refuses with 503 provider_key_missing — nothing lingers", async () => {
+		const chat = chatStore.createChat("Test: keyless provider");
+		createdChats.push(chat.id);
+		const saved = process.env.TOGETHER_API_KEY;
+		delete process.env.TOGETHER_API_KEY;
+		try {
+			// The chat's own model override pins the provider — the same
+			// chain the strong slot rides. The gate fires BEFORE the engine
+			// build, so the fake model id never hits the catalog.
+			chatStore.saveSettings(chat.id, { model: { provider: "together", id: "no-such-model" } });
+			const firstUser = { id: "u1", role: "user", parts: [{ type: "text", text: "teach me something" }] };
+			const res = await handleChatRequest(post(chat.id, [firstUser]), agentFactory(scriptedTeacher(defaultLesson).engine));
+
+			assert.equal(res.status, 503, "the key-presence gate refuses before beginTurn");
+			const body = (await res.json()) as { error: string; code: string; provider: string; slots: string[] };
+			assert.equal(body.code, "provider_key_missing");
+			assert.equal(body.provider, "together", "the envelope names whose key is gone");
+			assert.deepEqual(body.slots, ["strong"], "the conversation tier is the affected slot");
+			assert.equal(body.error, "No Together key is set — add one in Settings → Keys", "the human line names the provider");
+			assert.equal(isTurnRunning(chat.id), false, "the refusal never registers a live turn");
+			assert.equal(chatStore.getChat(chat.id)!.messages.length, 0, "no write-ahead persist before the gate");
+		} finally {
+			if (saved !== undefined) process.env.TOGETHER_API_KEY = saved;
+		}
+	});
+
+	it("an env-present key passes the gate (gate by what would run)", async () => {
+		const chat = chatStore.createChat("Test: env-keyed provider");
+		createdChats.push(chat.id);
+		const saved = process.env.OPENAI_API_KEY;
+		process.env.OPENAI_API_KEY = "test-key-presence-gate";
+		try {
+			// A REAL catalog model: the engine build AFTER the gate must
+			// resolve — the injected agent replaces the loop, not the build.
+			chatStore.saveSettings(chat.id, { model: { provider: "openai", id: "gpt-4" } });
+			const firstUser = { id: "u1", role: "user", parts: [{ type: "text", text: "teach me something" }] };
+			const res = await handleChatRequest(post(chat.id, [firstUser]), agentFactory(scriptedTeacher(defaultLesson).engine));
+
+			assert.equal(res.status, 200, "the env-shadowed key counts as present — the turn runs");
+			await drain(res);
+		} finally {
+			if (saved !== undefined) process.env.OPENAI_API_KEY = saved;
+			else delete process.env.OPENAI_API_KEY;
+		}
+	});
+});

tests/demos.test.tsx

@@ -1,3 +1,4 @@
+
 /**
  * Demo + visual artifact tests (W6) — deterministic, zero network, no real
  * Chrome:
@@ -83,6 +84,13 @@ function testRunner() {
 }
 import { artifactRenderers } from "../components/artifacts/index.ts";
 
+// The key-presence turn gate (provider-key interlude, 2026-09-25): scripted
+// turns pin openrouter per chat — the gate reads env-first truth, so the
+// key must be present in the test process like any real setup.
+process.env.OPENROUTER_API_KEY ??= "test-key-presence-gate";
+
+
+
 const JOBS_DIR = path.join(PATHS.data, "jobs");
 const createdChats: string[] = [];
 const createdJobs: string[] = [];

tests/extraction.test.ts

@@ -39,7 +39,7 @@ import type {
 } from "../src/core/contracts.ts";
 import type { GraphStore } from "../src/core/ports.ts";
 import { abortExtraction, createExtractionPipeline, extractionStatuses, transcriptView } from "../src/agent/subagents/extraction.ts";
-import { ModelsNotConfiguredError } from "../src/core/settings.ts";
+import { ModelsNotConfiguredError, ProviderKeyMissingError, providerKeyMissing, type ModelSlotName } from "../src/core/settings.ts";
 import { batchTag, coverageOf, coverageSlots } from "../src/core/coverage.ts";
 import { chatStore } from "../src/store/chats.ts";
 import { PATHS } from "../config.ts";
@@ -394,6 +394,54 @@ describe("the extraction pipeline (extractor → auditor → merger)", () => {
 		assert.equal(ledgers.readCoverage().length, 0);
 	});
 
+	it("key-presence refusal: a stage engine whose provider key is gone throws before any batch (provider-key interlude, 2026-09-25)", async () => {
+		const { chatId } = fixtureChat();
+		const ledgers = memoryLedgers();
+		const extractor = fauxEngine([]);
+		const auditor = fauxEngine([]);
+		const seen: Array<[string, ModelSlotName]> = [];
+		const pipeline = createExtractionPipeline({
+			chatStore,
+			graphStore: ledgers,
+			extractor,
+			auditor,
+			providerKeyMissing: (provider, tier) => {
+				seen.push([provider, tier]);
+				return providerKeyMissing(provider, [tier]);
+			},
+		});
+		await assert.rejects(pipeline.runExtraction(chatId), (err: unknown) => {
+			assert.ok(err instanceof ProviderKeyMissingError);
+			assert.equal(err.envelope.code, "provider_key_missing");
+			assert.equal(err.envelope.provider, extractor.model.provider, "the provider of the keyless engine");
+			assert.deepEqual(err.envelope.slots, ["cheap"], "extractor + auditor are the cheap tier");
+			return true;
+		});
+		// FIRST offender surfaces (extractor before auditor) — and nothing
+		// ran: the refusal lands before any batch, no coverage writes.
+		assert.deepEqual(seen, [[extractor.model.provider, "cheap"]]);
+		assert.equal(ledgers.readCoverage().length, 0);
+	});
+
+	it("key-presence pass-through: null from the check lets a stage through — the NEXT keyless stage surfaces (first-offender discipline)", async () => {
+		const { chatId } = fixtureChat();
+		const ledgers = memoryLedgers();
+		let calls = 0;
+		const pipeline = createExtractionPipeline({
+			chatStore,
+			graphStore: ledgers,
+			extractor: fauxEngine([]),
+			auditor: fauxEngine([]),
+			providerKeyMissing: (provider, tier) => (calls++ === 0 ? null : providerKeyMissing(provider, [tier])),
+		});
+		await assert.rejects(pipeline.runExtraction(chatId), (err: unknown) => {
+			assert.ok(err instanceof ProviderKeyMissingError, "the auditor's refusal surfaces after the extractor passed");
+			return true;
+		});
+		assert.equal(calls, 2, "both stages were checked, in order");
+		assert.equal(ledgers.readCoverage().length, 0);
+	});
+
 	it("the LLM cluster-namer is DEAD (wave 7): a merge mints no naming runs — labels are session names now", async () => {
 		const { chatId } = fixtureChat();
 		const ledgers = memoryLedgers();

tests/jobs.test.ts

@@ -58,6 +58,7 @@ import { persistTurn, withMessageIds } from "../src/server/turn-service.ts";
 import { chatStore } from "../src/store/chats.ts";
 import { jobStore } from "../src/store/jobs.ts";
 import { createJobRunner, pdfModelOverride, researchModelOverride } from "../src/agent/subagents/runner.ts";
+import { providerKeyMissing, type ModelSlotName } from "../src/core/settings.ts";
 import type { PiEngine } from "../src/agent/models.ts";
 import type { SearchProvider } from "../src/core/search.ts";
 import { PATHS } from "../config.ts";
@@ -65,6 +66,11 @@ import { PATHS } from "../config.ts";
 const JOBS_DIR = path.join(PATHS.data, "jobs");
 
 const createdChats: string[] = [];
+
+// The key-presence turn gate (provider-key interlude, 2026-09-25): scripted
+// turns pin openrouter per chat — the gate reads env-first truth, so the
+// key must be present in the test process like any real setup.
+process.env.OPENROUTER_API_KEY ??= "test-key-presence-gate";
 const createdJobs: string[] = [];
 
 function trackChat(id: string) {
@@ -1391,3 +1397,56 @@ describe("BYOK job refusal (no factory floor)", () => {
 		assert.equal(result.sources.length, 0, "the failure result matches the research convention");
 	});
 });
+
+// ─── provider-key: the key-presence job refusal (owner, 2026-09-25) ─────────
+
+describe("provider-key job refusal (key-presence interlude)", () => {
+	it("an engine whose provider key is gone refuses the spawn — envelope wording, no phantom run", async () => {
+		const chat = chatStore.createChat("Test: keyless spawn");
+		trackChat(chat.id);
+		chatStore.saveMessages(chat.id, [
+			{ id: "u1", role: "user", parts: [{ type: "text", text: "hi" }] },
+			{
+				id: "a1",
+				role: "assistant",
+				parts: [{ type: "tool-research", toolCallId: "call-km1", state: "output-available", input: RESEARCH_INPUT, output: "Dispatched." }],
+			},
+		] as never);
+
+		const job = jobStore.createJob({ kind: "research", chatId: chat.id, toolCallId: "call-km1" });
+		trackJob(job.id);
+
+		const delivery = fakeDeliver();
+		// The chain RESOLVES (an engine exists) — the KEY is what's missing.
+		// The injected check is the server seam's stand-in: it sees the
+		// engine's provider + the kind's slot tier, exactly as wired.
+		const engine = fauxEngine([]);
+		const seen: Array<[string, ModelSlotName]> = [];
+		const runner = createJobRunner({
+			chatStore,
+			jobStore,
+			deliver: delivery.deliver,
+			engineFor: () => engine,
+			providerKeyMissing: (provider, tier) => {
+				seen.push([provider, tier]);
+				return providerKeyMissing(provider, [tier]);
+			},
+		});
+		await runner.runJob(job.id);
+
+		// The refusal lands through the SAME convention as every failed job:
+		// honest record, kind failure shape steered, terminal flip after.
+		const done = jobStore.getJob(job.id)!;
+		assert.equal(done.status, "error", "the job lands error, never a phantom run");
+		assert.equal(done.error, providerKeyMissing(engine.model.provider, ["cheap"]).error, "the envelope's error line verbatim");
+		assert.deepEqual(seen, [[engine.model.provider, "cheap"]], "the check saw the engine's provider + the researcher's tier");
+		assert.equal(delivery.steers.length, 1, "the refusal STEERED — the teacher is not stranded");
+		const text = delivery.steers[0]!.parts[0];
+		assert.ok(
+			text.type === "text" && text.text.includes(`Research failed: No ${engine.model.provider} key is set`),
+			"the steer carries the kind's failure shape",
+		);
+		const result = done.result as ResearchResult;
+		assert.equal(result.sources.length, 0, "the failure result matches the research convention");
+	});
+});