gsd-pi 2.75.0 → 2.76.0-dev.4c866b677

package/src/resources/extensions/gsd/auto-start.ts

@@ -60,7 +60,7 @@ import { initRoutingHistory } from "./routing-history.js";
 import { restoreHookState, resetHookState } from "./post-unit-hooks.js";
 import { resetProactiveHealing, setLevelChangeCallback } from "./doctor-proactive.js";
 import { snapshotSkills } from "./skill-discovery.js";
-import { isDbAvailable, getMilestone, openDatabase } from "./gsd-db.js";
+import { isDbAvailable, getMilestone, openDatabase, getDbStatus } from "./gsd-db.js";
 import { hideFooter } from "./auto-dashboard.js";
 import {
   debugLog,
@@ -273,8 +273,8 @@ export async function bootstrapAutoSession(
   //
   // Precedence:
   // 1) Explicit session override via /gsd model (this session)
-  // 2) GSD model preferences from PREFERENCES.md (validated against live auth)
-  // 3) Current session model from settings/session restore (if provider ready)
+  // 2) Current session model from settings/session restore (if provider ready)
+  // 3) GSD model preferences from PREFERENCES.md (validated against live auth)
   //
   // This preserves #3517 defaults while honoring explicit runtime model
   // selection for subsequent /gsd runs in the same session.
@@ -314,11 +314,14 @@ export async function bootstrapAutoSession(
   }
   const sessionModelReady =
     ctx.model && ctx.modelRegistry.isProviderRequestReady(ctx.model.provider);
+  const currentSessionModel = (sessionModelReady && ctx.model)
+    ? { provider: ctx.model.provider, id: ctx.model.id }
+    : null;
+  const startThinkingSnapshot = pi.getThinkingLevel();
   const startModelSnapshot = manualSessionOverride
+    ?? currentSessionModel
     ?? validatedPreferredModel
-    ?? (sessionModelReady && ctx.model
-      ? { provider: ctx.model.provider, id: ctx.model.id }
-      : null);
+    ?? null;
 
   try {
     // Validate GSD_PROJECT_ID early so the user gets immediate feedback
@@ -464,11 +467,12 @@ export async function bootstrapAutoSession(
     // Detect survivor milestone branches in both pre-planning and complete phases.
     // In phase=complete, the milestone artifacts exist but finalization (merge,
     // worktree cleanup) was never run — the survivor branch must be merged.
+    // Applies to both worktree and branch isolation modes.
     let hasSurvivorBranch = false;
     if (
       state.activeMilestone &&
       (state.phase === "pre-planning" || state.phase === "complete") &&
-      shouldUseWorktreeIsolation() &&
+      getIsolationMode() !== "none" &&
       !detectWorktreeName(base) &&
       !base.includes(`${pathSep}.gsd${pathSep}worktrees${pathSep}`)
     ) {
@@ -663,8 +667,9 @@ export async function bootstrapAutoSession(
     s.pendingQuickTasks = [];
     s.currentUnit = null;
     s.currentMilestoneId = state.activeMilestone?.id ?? null;
-    s.originalModelId = ctx.model?.id ?? null;
-    s.originalModelProvider = ctx.model?.provider ?? null;
+    s.originalModelId = startModelSnapshot?.id ?? ctx.model?.id ?? null;
+    s.originalModelProvider = startModelSnapshot?.provider ?? ctx.model?.provider ?? null;
+    s.originalThinkingLevel = startThinkingSnapshot ?? null;
 
     // Register SIGTERM handler
     registerSigtermHandler(base);
@@ -711,7 +716,7 @@ export async function bootstrapAutoSession(
 
     if (
       s.currentMilestoneId &&
-      shouldUseWorktreeIsolation() &&
+      getIsolationMode() !== "none" &&
       !detectWorktreeName(base) &&
       !isUnderGsdWorktrees(base)
     ) {
@@ -757,9 +762,22 @@ export async function bootstrapAutoSession(
     // call returns "db_unavailable", triggering artifact-retry which
     // re-dispatches the same task — producing an infinite loop (#2419).
     if (existsSync(gsdDbPath) && !isDbAvailable()) {
+      const dbStatus = getDbStatus();
+      const phaseHint = dbStatus.lastPhase === "open"
+        ? "The database file could not be opened"
+        : dbStatus.lastPhase === "initSchema"
+          ? "The database schema could not be initialized"
+          : dbStatus.lastPhase === "vacuum-recovery"
+            ? "Corruption recovery (VACUUM) failed"
+            : dbStatus.attempted
+              ? "The database could not be opened (phase unknown)"
+              : "The database provider could not be loaded";
+      const errorDetail = dbStatus.lastError ? ` (${dbStatus.lastError.message})` : "";
+      const providerHint = dbStatus.provider
+        ? ` Provider: ${dbStatus.provider}.`
+        : " No SQLite provider available — check Node >= 22 or install better-sqlite3.";
       ctx.ui.notify(
-        "SQLite database exists but failed to open. Auto-mode cannot proceed without a working database provider. " +
-          "Check for corrupt gsd.db or missing native SQLite bindings.",
+        `SQLite database exists but failed to open: ${gsdDbPath}. ${phaseHint}${errorDetail}.${providerHint}`,
         "error",
       );
       return releaseLockAndReturn();
@@ -778,6 +796,7 @@ export async function bootstrapAutoSession(
         id: startModelSnapshot.id,
       };
     }
+    s.autoModeStartThinkingLevel = startThinkingSnapshot ?? null;
     s.manualSessionModelOverride = manualSessionOverride ?? null;
 
     // Apply worker model override from parallel orchestrator (#worker-model).
@@ -837,10 +856,11 @@ export async function bootstrapAutoSession(
     const bannerPrefs = loadEffectiveGSDPreferences()?.preferences;
     const effectiveProvider = s.autoModeStartModel?.provider ?? ctx.model?.provider;
     const effectivelyEnabled = routingConfig.enabled
-      && !(effectiveProvider && isFlatRateProvider(
-        effectiveProvider,
-        buildFlatRateContext(effectiveProvider, ctx, bannerPrefs),
-      ));
+      && (routingConfig.allow_flat_rate_providers
+        || !(effectiveProvider && isFlatRateProvider(
+          effectiveProvider,
+          buildFlatRateContext(effectiveProvider, ctx, bannerPrefs),
+        )));
 
     // The actual ceiling may come from tier_models.heavy, not the start model.
     const effectiveCeiling = (routingConfig.enabled && routingConfig.tier_models?.heavy)

package/src/resources/extensions/gsd/auto-verification.ts

@@ -5,9 +5,9 @@
  * dependency audits, handles auto-fix retry logic, and writes
  * verification evidence JSON.
  *
- * Extracted from handleAgentEnd() in auto.ts. Returns a sentinel
- * value instead of calling return/pauseAuto directly — the caller
- * checks the result and handles control flow.
+ * Extracted from the pre-loop agent_end handler in auto.ts. Returns a
+ * sentinel value instead of calling return/pauseAuto directly — the
+ * caller checks the result and handles control flow.
  */
 
 import type { ExtensionContext, ExtensionAPI } from "@gsd/pi-coding-agent";
@@ -526,6 +526,39 @@ export async function runPostUnitVerification(
       result.passed = false;
     }
 
+    // Emit Layer 2 verify_result event with the final, post-exec verdict so hooks
+    // see the authoritative pass/fail and the complete set of failures.
+    try {
+      const { emitVerifyResult } = await import("./hook-emitter.js");
+      const checkFailures = result.checks
+        .filter((c) => c.exitCode !== 0)
+        .map((c) => ({
+          kind: "gate" as const,
+          message: `${c.command} exited ${c.exitCode}${c.stderr ? `: ${c.stderr.slice(0, 200)}` : ""}`,
+        }));
+      const runtimeFailures = (result.runtimeErrors ?? [])
+        .filter((e) => e.blocking)
+        .map((e) => ({
+          kind: "other" as const,
+          message: `[${e.source}] ${e.message.slice(0, 200)}`,
+        }));
+      const postExecFailures = (postExecChecks ?? [])
+        .filter((c) => !c.passed)
+        .map((c) => ({
+          kind: "other" as const,
+          message: `[${c.category}] ${c.target}: ${c.message}`,
+        }));
+      await emitVerifyResult({
+        passed: result.passed,
+        failures: [...checkFailures, ...runtimeFailures, ...postExecFailures],
+        unitType: s.currentUnit.type,
+        unitId: s.currentUnit.id,
+        cwd: s.basePath,
+      });
+    } catch (hookErr) {
+      logWarning("engine", `verify_result hook emission failed: ${(hookErr as Error).message}`);
+    }
+
     // ── Auto-fix retry logic ──
     if (result.passed) {
       s.verificationRetryCount.delete(s.currentUnit.id);

package/src/resources/extensions/gsd/auto-worktree.ts

@@ -60,6 +60,7 @@ import {
   nativeAddPaths,
   nativeRmForce,
   nativeBranchDelete,
+  nativeBranchForceReset,
   nativeBranchExists,
   nativeDiffNumstat,
   nativeUpdateRef,
@@ -237,6 +238,14 @@ function clearProjectRootStateFiles(basePath: string, milestoneId: string): void
   }
 }
 
+function isProjectGsdSymlink(basePath: string): boolean {
+  try {
+    return lstatSyncFn(join(basePath, ".gsd")).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
 // ─── Build Artifact Auto-Resolve ─────────────────────────────────────────────
 
 /** Patterns for machine-generated build artifacts that can be safely
@@ -921,10 +930,74 @@ export function runWorktreePostCreateHook(
 
 // ─── Auto-Worktree Branch Naming ───────────────────────────────────────────
 
+/** Returns the git branch name for a milestone worktree (`milestone/<MID>`). */
 export function autoWorktreeBranch(milestoneId: string): string {
   return `milestone/${milestoneId}`;
 }
 
+// ─── Branch-mode Entry ─────────────────────────────────────────────────────
+
+/**
+ * Enter branch isolation mode for a milestone.
+ *
+ * Creates `milestone/<MID>` from the integration branch (if it doesn't
+ * exist yet) and checks out to it.  No worktree directory is created — the
+ * project root is the working copy; only HEAD changes.
+ *
+ * Uses the same 3-tier integration-branch fallback as createAutoWorktree:
+ *   1. META.json recorded integration branch
+ *   2. git.main_branch preference
+ *   3. nativeDetectMainBranch (origin/HEAD auto-detection)
+ */
+export function enterBranchModeForMilestone(
+  basePath: string,
+  milestoneId: string,
+): void {
+  const branch = autoWorktreeBranch(milestoneId);
+  const branchExists = nativeBranchExists(basePath, branch);
+
+  if (!branchExists) {
+    // Create the milestone branch from the integration branch start-point.
+    const integrationBranch =
+      readIntegrationBranch(basePath, milestoneId) ?? undefined;
+    const gitPrefs = loadEffectiveGSDPreferences()?.preferences?.git;
+    // Validate main_branch preference exists in the repo before using it —
+    // a stale preference (e.g. "master" when repo uses "main") would cause
+    // nativeBranchForceReset to fail with a bad start-point reference.
+    const validatedPrefBranch =
+      gitPrefs?.main_branch &&
+      typeof gitPrefs.main_branch === "string" &&
+      gitPrefs.main_branch.length > 0 &&
+      nativeBranchExists(basePath, gitPrefs.main_branch)
+        ? gitPrefs.main_branch
+        : undefined;
+    const startPoint =
+      integrationBranch ??
+      validatedPrefBranch ??
+      nativeDetectMainBranch(basePath);
+
+    // nativeBranchForceReset creates (or resets) branch at startPoint,
+    // then checkout switches HEAD to it.
+    nativeBranchForceReset(basePath, branch, startPoint);
+    debugLog("auto-worktree", {
+      action: "enterBranchMode",
+      milestoneId,
+      branch,
+      startPoint,
+      created: true,
+    });
+  } else {
+    debugLog("auto-worktree", {
+      action: "enterBranchMode",
+      milestoneId,
+      branch,
+      reused: true,
+    });
+  }
+
+  nativeCheckoutBranch(basePath, branch);
+}
+
 // ─── Public API ────────────────────────────────────────────────────────────
 
 /**
@@ -1610,12 +1683,19 @@ export function mergeMilestoneToMain(
       // CONTEXT files into the stash. If stash pop later fails, those files
       // are permanently trapped in the stash entry and lost on the next
       // stash push or drop.
+      //
+      // When `.gsd` itself is a symlink, Git rejects pathspecs below it
+      // ("beyond a symbolic link"). In that layout, exclude the whole symlink
+      // and keep stashing real project files that could block the merge.
+      const stashPathspecs = isProjectGsdSymlink(originalBasePath_)
+        ? [".", ":(exclude).gsd"]
+        : [":(exclude).gsd/milestones"];
       execFileSync(
         "git",
         [
           "stash", "push", "--include-untracked",
           "-m", `gsd: pre-merge stash for ${milestoneId}`,
-          "--", ":(exclude).gsd/milestones",
+          "--", ...stashPathspecs,
         ],
         { cwd: originalBasePath_, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" },
       );

package/src/resources/extensions/gsd/auto.ts

@@ -146,6 +146,7 @@ import { getPriorSliceCompletionBlocker } from "./dispatch-guard.js";
 import {
   createAutoWorktree,
   enterAutoWorktree,
+  enterBranchModeForMilestone,
   teardownAutoWorktree,
   isInAutoWorktree,
   getAutoWorktreePath,
@@ -160,6 +161,7 @@ import {
   escapeStaleWorktree,
 } from "./auto-worktree.js";
 import { pruneQueueOrder } from "./queue-order.js";
+import { startCommandPolling as _startCommandPolling, isRemoteConfigured } from "../remote-questions/manager.js";
 
 import { debugLog, isDebugEnabled, writeDebugSummary } from "./debug-logger.js";
 import {
@@ -168,6 +170,7 @@ import {
 } from "./auto-recovery.js";
 import { resolveDispatch, DISPATCH_RULES } from "./auto-dispatch.js";
 import { getErrorMessage } from "./error-utils.js";
+import { recoverFailedMigration } from "./migrate-external.js";
 import { initRegistry, convertDispatchRules } from "./rule-registry.js";
 import { emitJournalEvent as _emitJournalEvent, type JournalEntry } from "./journal.js";
 import {
@@ -201,7 +204,7 @@ import {
 } from "./auto-post-unit.js";
 import { bootstrapAutoSession, openProjectDbIfPresent, type BootstrapDeps } from "./auto-start.js";
 import { initHealthWidget } from "./health-widget.js";
-import { autoLoop, resolveAgentEnd, resolveAgentEndCancelled, _resetPendingResolve, isSessionSwitchInFlight, type LoopDeps, type ErrorContext } from "./auto-loop.js";
+import { runLegacyAutoLoop, runUokKernelLoop, resolveAgentEnd, resolveAgentEndCancelled, _resetPendingResolve, isSessionSwitchInFlight, type LoopDeps, type ErrorContext } from "./auto-loop.js";
 import { runAutoLoopWithUok } from "./uok/kernel.js";
 import { resolveUokFlags } from "./uok/flags.js";
 // Slice-level parallelism (#2340)
@@ -326,6 +329,7 @@ export function startAutoDetached(
   });
 }
 
+/** Returns true if the project is configured for `isolation:worktree` mode. */
 export function shouldUseWorktreeIsolation(): boolean {
   const prefs = loadEffectiveGSDPreferences()?.preferences?.git;
   if (prefs?.isolation === "worktree") return true;
@@ -390,6 +394,27 @@ function deregisterSigtermHandler(): void {
   s.sigtermHandler = null;
 }
 
+/**
+ * Wrapper: start background command polling for the configured remote channel
+ * (currently Telegram only). Stores the cleanup function on the session so
+ * every exit path can stop the interval via stopCommandPolling().
+ * No-op when no remote channel is configured.
+ */
+function startAutoCommandPolling(basePath: string): void {
+  if (!isRemoteConfigured()) return;
+  // Clear any existing interval before starting a new one (e.g. resume path).
+  stopAutoCommandPolling();
+  s.commandPollingCleanup = _startCommandPolling(basePath);
+}
+
+/** Wrapper: stop background command polling and clear the stored cleanup. */
+function stopAutoCommandPolling(): void {
+  if (s.commandPollingCleanup) {
+    s.commandPollingCleanup();
+    s.commandPollingCleanup = null;
+  }
+}
+
 export { type AutoDashboardData } from "./auto-dashboard.js";
 
 export function getAutoDashboardData(): AutoDashboardData {
@@ -466,6 +491,15 @@ export function getAutoModeStartModel(): {
   return s.autoModeStartModel;
 }
 
+/**
+ * Update the dashboard-facing dispatched model label.
+ * Used when runtime recovery switches models mid-unit (e.g. provider fallback)
+ * so the AUTO box reflects the active model immediately.
+ */
+export function setCurrentDispatchedModelId(model: { provider: string; id: string } | null): void {
+  s.currentDispatchedModelId = model ? `${model.provider}/${model.id}` : null;
+}
+
 // Tool tracking — delegates to auto-tool-tracking.ts
 export function markToolStart(toolCallId: string, toolName?: string): void {
   _markToolStart(toolCallId, s.active, toolName);
@@ -648,6 +682,7 @@ function handleLostSessionLock(
   s.paused = false;
   deactivateGSD();
   clearUnitTimeout();
+  stopAutoCommandPolling();
   restoreProjectRootEnv();
   restoreMilestoneLockEnv();
   deregisterSigtermHandler();
@@ -687,6 +722,7 @@ function cleanupAfterLoopExit(ctx: ExtensionContext): void {
   s.active = false;
   deactivateGSD();
   clearUnitTimeout();
+  stopAutoCommandPolling();
   restoreProjectRootEnv();
   restoreMilestoneLockEnv();
 
@@ -735,6 +771,7 @@ export async function stopAuto(
     // ── Step 1: Timers and locks ──
     try {
       clearUnitTimeout();
+      stopAutoCommandPolling();
       if (lockBase()) clearLock(lockBase());
       if (lockBase()) releaseSessionLock(lockBase());
     } catch (e) {
@@ -932,7 +969,7 @@ export async function stopAuto(
       logWarning("engine", `file unlink failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
     }
 
-    // ── Step 13: Restore original model (before reset clears IDs) ──
+    // ── Step 13: Restore original model + thinking (before reset clears IDs) ──
     try {
       if (pi && ctx && s.originalModelId && s.originalModelProvider) {
         const original = ctx.modelRegistry.find(
@@ -941,6 +978,9 @@ export async function stopAuto(
         );
         if (original) await pi.setModel(original);
       }
+      if (pi && s.originalThinkingLevel) {
+        pi.setThinkingLevel(s.originalThinkingLevel);
+      }
     } catch (e) {
       debugLog("stop-cleanup-model", { error: e instanceof Error ? e.message : String(e) });
     }
@@ -1000,6 +1040,7 @@ export async function pauseAuto(
 ): Promise<void> {
   if (!s.active) return;
   clearUnitTimeout();
+  stopAutoCommandPolling();
 
   // Flush queued follow-up messages (#3512).
   // Late async notifications (async_job_result, gsd-auto-wrapup) can trigger
@@ -1103,6 +1144,7 @@ function buildResolverDeps(): WorktreeResolverDeps {
     teardownAutoWorktree,
     createAutoWorktree,
     enterAutoWorktree,
+    enterBranchModeForMilestone,
     getAutoWorktreePath,
     autoCommitCurrentBranch,
     getCurrentBranch,
@@ -1253,6 +1295,11 @@ function buildLoopDeps(): LoopDeps {
   } as unknown as LoopDeps;
 }
 
+/**
+ * Start auto-mode. Handles both fresh-start and resume paths, sets up session
+ * state, enters the milestone worktree or branch, and dispatches the first unit.
+ * No-ops if auto-mode is already active.
+ */
 export async function startAuto(
   ctx: ExtensionCommandContext,
   pi: ExtensionAPI,
@@ -1281,6 +1328,13 @@ export async function startAuto(
   // Escape stale worktree cwd from a previous milestone (#608).
   base = escapeStaleWorktree(base);
 
+  // Heal .gsd.migrating before any branching — covers both fresh-start and
+  // resume paths (#4416). The matching call in auto-start.ts covers the
+  // bootstrap-only path; this call ensures the resume path is also protected.
+  if (recoverFailedMigration(base)) {
+    ctx.ui.notify("Recovered unfinished migration (.gsd.migrating → .gsd).", "info");
+  }
+
   const freshStartAssessment = interruptedAssessment
     ?? await assessInterruptedSession(base);
 
@@ -1438,10 +1492,10 @@ export async function startAuto(
       ctx.ui.notify(summary, level as "info" | "warning" | "error");
     });
 
-    // ── Auto-worktree: re-enter worktree on resume ──
+    // ── Auto-worktree / branch-mode: re-enter on resume ──
     if (
       s.currentMilestoneId &&
-      shouldUseWorktreeIsolation() &&
+      getIsolationMode() !== "none" &&
       s.originalBasePath &&
       !isInAutoWorktree(s.basePath) &&
       !detectWorktreeName(s.basePath) &&
@@ -1533,12 +1587,14 @@ export async function startAuto(
     logCmuxEvent(loadEffectiveGSDPreferences()?.preferences, s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", "progress");
 
     captureProjectRootEnv(s.originalBasePath || s.basePath);
+    startAutoCommandPolling(s.basePath);
     await runAutoLoopWithUok({
       ctx,
       pi,
       s,
       deps: buildLoopDeps(),
-      runLegacyLoop: autoLoop,
+      runKernelLoop: runUokKernelLoop,
+      runLegacyLoop: runLegacyAutoLoop,
     });
     cleanupAfterLoopExit(ctx);
     return;
@@ -1573,40 +1629,20 @@ export async function startAuto(
   }
   logCmuxEvent(loadEffectiveGSDPreferences()?.preferences, requestedStepMode ? "Step-mode started." : "Auto-mode started.", "progress");
 
+  startAutoCommandPolling(s.basePath);
+
   // Dispatch the first unit
   await runAutoLoopWithUok({
     ctx,
     pi,
     s,
     deps: buildLoopDeps(),
-    runLegacyLoop: autoLoop,
+    runKernelLoop: runUokKernelLoop,
+    runLegacyLoop: runLegacyAutoLoop,
   });
   cleanupAfterLoopExit(ctx);
 }
 
-// ─── Agent End Handler ────────────────────────────────────────────────────────
-
-/**
- * Deprecated thin wrapper — kept as export for backward compatibility.
- * The actual agent_end processing now happens via resolveAgentEnd() in auto-loop.ts,
- * which is called directly from index.ts. The autoLoop() while loop handles all
- * post-unit processing (verification, hooks, dispatch) that this function used to do.
- *
- * If called by straggler code, it simply resolves the pending promise so the loop
- * can continue.
- */
-export async function handleAgentEnd(
-  ctx: ExtensionContext,
-  pi: ExtensionAPI,
-): Promise<void> {
-  if (!s.active || !s.cmdCtx) {
-    // Even when inactive, resolve any pending promise so the loop is unblocked.
-    resolveAgentEndCancelled();
-    return;
-  }
-  clearUnitTimeout();
-  resolveAgentEnd({ messages: [] });
-}
 // describeNextUnit is imported from auto-dashboard.ts and re-exported
 export { describeNextUnit } from "./auto-dashboard.js";
 

package/src/resources/extensions/gsd/blocked-models.ts

@@ -0,0 +1,98 @@
+// GSD — Persistent per-project blocklist of provider/model pairs that the
+// provider has rejected at request time for account entitlement reasons.
+//
+// Lives at `.gsd/runtime/blocked-models.json` so the block survives /gsd auto
+// restarts.  Auto-mode model selection skips blocked entries; agent-end
+// recovery adds entries when a runtime rejection is classified as
+// `unsupported-model`.  See issue #4513.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { gsdRoot } from "./paths.js";
+import { withFileLockSync } from "./file-lock.js";
+
+export interface BlockedModelEntry {
+  provider: string;
+  id: string;
+  reason: string;
+  blockedAt: number;
+}
+
+interface BlockedModelsFile {
+  version: 1;
+  blocked: BlockedModelEntry[];
+}
+
+function blockedModelsPath(basePath: string): string {
+  return join(gsdRoot(basePath), "runtime", "blocked-models.json");
+}
+
+function modelKey(provider: string, id: string): string {
+  return `${provider.toLowerCase()}/${id.toLowerCase()}`;
+}
+
+function readFileSafe(path: string): BlockedModelsFile {
+  if (!existsSync(path)) return { version: 1, blocked: [] };
+  try {
+    const raw = readFileSync(path, "utf-8");
+    const parsed = JSON.parse(raw) as Partial<BlockedModelsFile>;
+    if (!parsed || !Array.isArray(parsed.blocked)) {
+      return { version: 1, blocked: [] };
+    }
+    const blocked = parsed.blocked.filter(
+      (e): e is BlockedModelEntry =>
+        !!e && typeof e.provider === "string" && typeof e.id === "string",
+    );
+    return { version: 1, blocked };
+  } catch {
+    // Corrupted JSON: treat as empty so a bad file never blocks dispatch.
+    return { version: 1, blocked: [] };
+  }
+}
+
+export function loadBlockedModels(basePath: string): BlockedModelEntry[] {
+  return readFileSafe(blockedModelsPath(basePath)).blocked;
+}
+
+export function isModelBlocked(
+  basePath: string,
+  provider: string | undefined,
+  id: string | undefined,
+): boolean {
+  if (!provider || !id) return false;
+  const target = modelKey(provider, id);
+  return loadBlockedModels(basePath).some(
+    (e) => modelKey(e.provider, e.id) === target,
+  );
+}
+
+export function blockModel(
+  basePath: string,
+  provider: string,
+  id: string,
+  reason: string,
+): void {
+  const path = blockedModelsPath(basePath);
+  mkdirSync(dirname(path), { recursive: true });
+  // Ensure the file exists before we try to lock it — proper-lockfile requires
+  // the target path to exist (file-lock.ts falls through to an unlocked call
+  // otherwise).
+  if (!existsSync(path)) {
+    writeFileSync(path, JSON.stringify({ version: 1, blocked: [] }, null, 2) + "\n", "utf-8");
+  }
+  withFileLockSync(path, () => {
+    const current = readFileSafe(path);
+    const target = modelKey(provider, id);
+    if (current.blocked.some((e) => modelKey(e.provider, e.id) === target)) {
+      return;
+    }
+    const next: BlockedModelsFile = {
+      version: 1,
+      blocked: [
+        ...current.blocked,
+        { provider, id, reason, blockedAt: Date.now() },
+      ],
+    };
+    writeFileSync(path, JSON.stringify(next, null, 2) + "\n", "utf-8");
+  });
+}