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.

app/api/graph/coverage/extract/route.ts

@@ -3,7 +3,8 @@
  * (vision-extraction-coverage.md): run the pipeline over ONE session's
  * uncovered content, whatever its size — the user's answer to an aborted
  * run, a pipeline error, or a session that went dormant under the chunk
- * budget. The pipeline itself batches under EXTRACTION.chunkTokens and
+ * budget. The pipeline itself batches under the graph.extractionChunkTokens setting (extraction-UX redesign,
+ * 2026-09-24) and
  * checkpoints coverage per merged batch, so this is the same run the
  * trigger fires, just user-initiated. 409 while a run is already in
  * flight (the dock is the source of truth for that); failures are logged

app/api/graph/import/route.ts

@@ -14,7 +14,12 @@
  * /api/graph/status, as with session runs.
  */
 import { extraction } from "@/src/server";
-import { ModelsNotConfiguredError, type EmissionStats } from "@/src/core";
+import {
+	ModelsNotConfiguredError,
+	PROVIDER_KEY_MISSING_CODE,
+	ProviderKeyMissingError,
+	type EmissionStats,
+} from "@/src/core";
 
 export const dynamic = "force-dynamic";
 
@@ -23,10 +28,14 @@ interface ImportResult {
 	ok: boolean;
 	stats?: EmissionStats;
 	error?: string;
-	/** The machine discriminator when ok:false is the BYOK refusal (owner,
-	 *  2026-09-22) — the client can open the setup flow off it. */
-	code?: "models_not_configured";
+	/** The machine discriminator when ok:false is a config refusal — the
+	 * BYOK models refusal (owner, 2026-09-22) or the provider-key refusal
+	 * (2026-09-25); the client can open the setup/keys flow off it. */
+	code?: "models_not_configured" | (typeof PROVIDER_KEY_MISSING_CODE);
 	missing?: string[];
+	/** The key-refusal specifics (provider_key_missing only). */
+	provider?: string;
+	slots?: string[];
 }
 
 export async function POST(request: Request) {
@@ -57,6 +66,17 @@ export async function POST(request: Request) {
 					});
 					continue;
 				}
+				if (err instanceof ProviderKeyMissingError) {
+					results.push({
+						filePath: file.name,
+						ok: false,
+						error: err.envelope.error,
+						code: PROVIDER_KEY_MISSING_CODE,
+						provider: err.envelope.provider,
+						slots: err.envelope.slots,
+					});
+					continue;
+				}
 				results.push({ filePath: file.name, ok: false, error: err instanceof Error ? err.message : String(err) });
 			}
 		}