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,