@agent-native/core 0.97.0 → 0.98.0

package/corpus/templates/plan/actions/update-local-plan-folder.ts

@@ -15,6 +15,8 @@ import {
 import { normalizePlanContent } from "../server/plan-content.js";
 import { referencedBlockIdsForPlanComments } from "../server/plan-mdx.js";
 import {
+  agentPlanContentPatchesSchema,
+  agentPlanContentSchema,
   applyPlanContentPatches,
   planContentPatchesSchema,
   planContentSchema,
@@ -22,41 +24,52 @@ import {
 } from "../shared/plan-content.js";
 import type { PlanKind } from "../shared/types.js";
 
+const CONTENT_DESCRIPTION =
+  "Full structured content replacement. Prefer contentPatches for targeted edits.";
+const CONTENT_PATCHES_DESCRIPTION =
+  "Targeted structured content edits addressed by stable block/prototype/canvas ids.";
+
+// Named so `agentInputSchema` below can `.extend()` it with compact
+// `content`/`contentPatches` fields instead of duplicating every other key.
+const updateLocalPlanFolderSchema = z.object({
+  slug: z
+    .string()
+    .min(1)
+    .regex(/^[A-Za-z0-9._-]+$/)
+    .describe("Folder name under PLAN_LOCAL_DIR, for example checkout-review."),
+  path: z
+    .string()
+    .optional()
+    .describe(
+      "Optional repo-relative folder path, for example plans/checkout-review.",
+    ),
+  title: z.string().optional().describe("Plan title."),
+  brief: z
+    .string()
+    .optional()
+    .describe("One-line plan summary shown under the title."),
+  kind: localPlanKindSchema.optional(),
+  content: planContentSchema.optional().describe(CONTENT_DESCRIPTION),
+  contentPatches: planContentPatchesSchema
+    .optional()
+    .default([])
+    .describe(CONTENT_PATCHES_DESCRIPTION),
+  note: z.string().optional().describe("Short audit note for callers."),
+});
+
 export default defineAction({
   description:
     "Update a DB-free local Agent-Native Plan MDX folder from PLAN_LOCAL_DIR or an optional repo-relative path. Applies the same structured contentPatches used by update-visual-plan, writes plan.mdx/canvas.mdx/prototype.mdx back to the same local folder, and never writes to the database.",
-  schema: z.object({
-    slug: z
-      .string()
-      .min(1)
-      .regex(/^[A-Za-z0-9._-]+$/)
-      .describe(
-        "Folder name under PLAN_LOCAL_DIR, for example checkout-review.",
-      ),
-    path: z
-      .string()
-      .optional()
-      .describe(
-        "Optional repo-relative folder path, for example plans/checkout-review.",
-      ),
-    title: z.string().optional().describe("Plan title."),
-    brief: z
-      .string()
-      .optional()
-      .describe("One-line plan summary shown under the title."),
-    kind: localPlanKindSchema.optional(),
-    content: planContentSchema
-      .optional()
-      .describe(
-        "Full structured content replacement. Prefer contentPatches for targeted edits.",
-      ),
-    contentPatches: planContentPatchesSchema
+  schema: updateLocalPlanFolderSchema,
+  // ADVERTISED-ONLY: same shape, but `content`/`contentPatches` swap the deep
+  // per-block-type union for a compact `type`-enum stand-in. Runtime
+  // validation always runs the full schema above — see the `actions` skill.
+  agentInputSchema: updateLocalPlanFolderSchema.extend({
+    content: agentPlanContentSchema.optional().describe(CONTENT_DESCRIPTION),
+    contentPatches: agentPlanContentPatchesSchema
       .optional()
       .default([])
-      .describe(
-        "Targeted structured content edits addressed by stable block/prototype/canvas ids.",
-      ),
-    note: z.string().optional().describe("Short audit note for callers."),
+      .describe(CONTENT_PATCHES_DESCRIPTION),
   }),
   requiresAuth: false,
   publicAgent: {

package/corpus/templates/plan/actions/update-visual-plan.ts

@@ -49,6 +49,8 @@ import {
   sectionInputSchema,
 } from "../server/plans.js";
 import {
+  agentPlanContentPatchesSchema,
+  agentPlanContentSchema,
   applyPlanContentPatches,
   planContentPatchesSchema,
   planContentSchema,
@@ -403,67 +405,81 @@ function contentPatchDetails(input: {
   });
 }
 
+const CONTENT_DESCRIPTION =
+  "Full structured content replacement. Prefer contentPatches for targeted edits; use this only for broad restructuring.";
+const CONTENT_PATCHES_DESCRIPTION =
+  "Targeted structured content edits addressed by stable id. For live plans this is the preferred edit path; patch-visual-plan-source is only for exported MDX folders. Supported ops: set-metadata for title/brief, set-prototype / remove-prototype / update-prototype-screen / patch-prototype-html for live prototype surfaces; update-block / replace-block, update-rich-text, patch-wireframe-html, patch-diagram-html, update-wireframe-node, replace-wireframe-screen, update-canvas-frame, update-canvas-annotation / append-canvas-annotation, append-block / remove-block, update-custom-html.";
+
+// Named so `agentInputSchema` below can `.extend()` it with compact
+// `content`/`contentPatches` fields instead of duplicating every other key.
+const updateVisualPlanSchema = z.object({
+  planId: z.string().describe("Plan ID"),
+  title: z.string().optional().describe("Plan title."),
+  brief: z
+    .string()
+    .optional()
+    .describe("One-line plan summary shown under the title."),
+  status: planStatusSchema
+    .optional()
+    .describe(
+      'Plan status. Setting "approved" also records approvedAt timestamp.',
+    ),
+  currentFocus: z
+    .string()
+    .optional()
+    .describe("Current agent focus label shown in the review surface."),
+  html: z
+    .string()
+    .optional()
+    .describe(
+      "Legacy: a standalone HTML document. Setting this NULLS structured content — blocks, contentPatches, inline editing, and MDX round-trip all stop working for this plan. Only for preserving a pre-existing HTML artifact; never author new plans this way.",
+    ),
+  content: planContentSchema.optional().describe(CONTENT_DESCRIPTION),
+  contentPatches: planContentPatchesSchema
+    .optional()
+    .default([])
+    .describe(CONTENT_PATCHES_DESCRIPTION),
+  markdown: z
+    .string()
+    .optional()
+    .describe("Legacy markdown source. Prefer content blocks."),
+  sections: z
+    .array(sectionInputSchema)
+    .optional()
+    .default([])
+    .describe("Legacy section array. Prefer content blocks."),
+  comments: z
+    .array(commentInputSchema)
+    .optional()
+    .default([])
+    .describe(
+      "Legacy comment array. Prefer reply-to-plan-comment / resolve-plan-comment for new comments.",
+    ),
+  consumedCommentIds: z
+    .array(z.string())
+    .optional()
+    .default([])
+    .describe("Prefer consume-plan-feedback for marking feedback consumed."),
+  note: z
+    .string()
+    .optional()
+    .describe("Short label saved as the version-history snapshot label."),
+});
+
 export default defineAction({
   description:
     "Update an Agent-Native Plan's structured content blocks, prototype screens, sections, comments, or status. Prefer contentPatches for targeted edits. Use full content only for broad restructuring. Works on plans and recaps alike when you have editor access; with viewer access (common on PR recaps published by CI) only comment-only calls succeed — to change a recap you cannot edit, publish a replacement with create-visual-recap instead of retrying this call.",
-  schema: z.object({
-    planId: z.string().describe("Plan ID"),
-    title: z.string().optional().describe("Plan title."),
-    brief: z
-      .string()
-      .optional()
-      .describe("One-line plan summary shown under the title."),
-    status: planStatusSchema
-      .optional()
-      .describe(
-        'Plan status. Setting "approved" also records approvedAt timestamp.',
-      ),
-    currentFocus: z
-      .string()
-      .optional()
-      .describe("Current agent focus label shown in the review surface."),
-    html: z
-      .string()
-      .optional()
-      .describe(
-        "Legacy: a standalone HTML document. Setting this NULLS structured content — blocks, contentPatches, inline editing, and MDX round-trip all stop working for this plan. Only for preserving a pre-existing HTML artifact; never author new plans this way.",
-      ),
-    content: planContentSchema
-      .optional()
-      .describe(
-        "Full structured content replacement. Prefer contentPatches for targeted edits; use this only for broad restructuring.",
-      ),
-    contentPatches: planContentPatchesSchema
+  schema: updateVisualPlanSchema,
+  // ADVERTISED-ONLY: same top-level shape, but `content`/`contentPatches`
+  // swap the deep per-block-type union for a compact `type`-enum stand-in.
+  // Runtime validation always runs the full schema above — see the `actions`
+  // skill.
+  agentInputSchema: updateVisualPlanSchema.extend({
+    content: agentPlanContentSchema.optional().describe(CONTENT_DESCRIPTION),
+    contentPatches: agentPlanContentPatchesSchema
       .optional()
       .default([])
-      .describe(
-        "Targeted structured content edits addressed by stable id. For live plans this is the preferred edit path; patch-visual-plan-source is only for exported MDX folders. Supported ops: set-metadata for title/brief, set-prototype / remove-prototype / update-prototype-screen / patch-prototype-html for live prototype surfaces; update-block / replace-block, update-rich-text, patch-wireframe-html, patch-diagram-html, update-wireframe-node, replace-wireframe-screen, update-canvas-frame, update-canvas-annotation / append-canvas-annotation, append-block / remove-block, update-custom-html.",
-      ),
-    markdown: z
-      .string()
-      .optional()
-      .describe("Legacy markdown source. Prefer content blocks."),
-    sections: z
-      .array(sectionInputSchema)
-      .optional()
-      .default([])
-      .describe("Legacy section array. Prefer content blocks."),
-    comments: z
-      .array(commentInputSchema)
-      .optional()
-      .default([])
-      .describe(
-        "Legacy comment array. Prefer reply-to-plan-comment / resolve-plan-comment for new comments.",
-      ),
-    consumedCommentIds: z
-      .array(z.string())
-      .optional()
-      .default([])
-      .describe("Prefer consume-plan-feedback for marking feedback consumed."),
-    note: z
-      .string()
-      .optional()
-      .describe("Short label saved as the version-history snapshot label."),
+      .describe(CONTENT_PATCHES_DESCRIPTION),
   }),
   publicAgent: {
     expose: true,
@@ -774,13 +790,14 @@ export default defineAction({
       });
     }
 
-    // The local better-sqlite3 driver rejects async transaction callbacks
-    // ("Transaction function cannot return a promise"), so the multi-statement
-    // write runs sequentially rather than inside `db.transaction`. The leading
-    // optimistic-lock UPDATE still guards concurrent writes; the libsql (prod)
-    // driver executes these awaits identically. (A driver-aware atomic helper is
-    // the proper long-term fix.)
-    await (async (tx: typeof db) => {
+    // Async transactions are safe on every driver here: better-sqlite3's
+    // normally-sync-only transaction() is patched to support async callbacks
+    // in packages/core/src/db/create-get-db.ts (patchBetterSqliteTransactions,
+    // wired into createGetDb for local sqlite urls), matching libsql/Postgres.
+    // See restore-plan-version.ts for the same pattern. The leading
+    // optimistic-lock UPDATE still guards concurrent writes; a thrown error
+    // (e.g. the zero-rows-affected conflict below) rolls back the whole block.
+    await db.transaction(async (tx) => {
       // guard:allow-unscoped -- gated above by editor access, or by public
       // viewer access plus new-open-human-comment / canvas-review-markup validation.
       //
@@ -959,7 +976,7 @@ export default defineAction({
         createdBy: onlyReviewerCommentWork ? "human" : "agent",
         createdAt: now,
       });
-    })(db);
+    });
 
     // Make an agent content edit visible on the plan-presence doc: light the AI
     // avatar in the header PresenceBar and glow the patched block(s) for ~6s.

package/corpus/templates/plan/app/components/layout/Sidebar.tsx

@@ -26,6 +26,7 @@ import {
   IconMessageCircle,
   IconPin,
   IconPlus,
+  IconRefresh,
   IconSettings,
 } from "@tabler/icons-react";
 import {
@@ -494,6 +495,22 @@ function PlansSidebarSection({ collapsed }: { collapsed: boolean }) {
             <Skeleton key={item} className="h-8 rounded-md bg-sidebar-accent" />
           ))}
         </div>
+      ) : plansQuery.isError ? (
+        <div className="grid gap-2 rounded-md border border-sidebar-border/70 p-2">
+          <p className="text-xs leading-5 text-sidebar-foreground/65">
+            {t("plansPage.loadError.didNotLoadTitle")}
+          </p>
+          <Button
+            type="button"
+            variant="outline"
+            size="sm"
+            className="h-7 justify-center text-xs"
+            onClick={() => void plansQuery.refetch()}
+          >
+            <IconRefresh className="size-3.5" />
+            {t("plansPage.loadError.retry")}
+          </Button>
+        </div>
       ) : plans.length === 0 ? (
         <p className="px-2 py-1.5 text-xs leading-5 text-sidebar-foreground/55">
           {t("sidebar.noPlans")}

package/corpus/templates/plan/app/components/ui/tabs.tsx

@@ -27,7 +27,7 @@ const TabsTrigger = React.forwardRef<
   <TabsPrimitive.Trigger
     ref={ref}
     className={cn(
-      "inline-flex items-center justify-center whitespace-nowrap rounded-sm border border-transparent px-3 py-1.5 text-sm font-medium ring-offset-background transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 data-[state=active]:bg-background data-[state=active]:text-foreground",
+      "inline-flex items-center justify-center whitespace-nowrap rounded-sm border border-transparent px-3 py-1.5 text-sm font-medium ring-offset-background transition-[color,background-color,box-shadow] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 data-[state=active]:bg-background data-[state=active]:text-foreground",
       className,
     )}
     {...props}

package/corpus/templates/plan/app/i18n/ar-SA.ts

@@ -434,6 +434,16 @@ const messages = {
       title: "لم يتم العثور على الخطة المحلية",
       message: 'تعذرت قراءة مجلد الخطة المحلية "{{slug}}".',
     },
+    localPlanConnection: {
+      promptTitle: "الاتصال بهذه الخطة المحلية",
+      promptMessage:
+        "تظل هذه الخطة على جهازك. يحتاج Plan إلى إذن المتصفح لقراءتها من الجسر المحلي.",
+      deniedTitle: "تم حظر الوصول إلى الشبكة المحلية",
+      deniedMessage:
+        "افتح إعدادات الموقع في متصفحك لـ Plan، واسمح بالوصول إلى الشبكة المحلية، ثم تحقق مرة أخرى.",
+      connect: "الاتصال بالخطة المحلية",
+      checkAgain: "التحقق مرة أخرى",
+    },
     overview: {
       title: "يخطط",
       documentCount_other: "{{count}} المستندات",

package/corpus/templates/plan/app/i18n/de-DE.ts

@@ -448,6 +448,16 @@ const messages = {
       title: "Lokaler Plan nicht gefunden",
       message: "Der lokale Planordner „{{slug}}“ konnte nicht gelesen werden.",
     },
+    localPlanConnection: {
+      promptTitle: "Mit diesem lokalen Plan verbinden",
+      promptMessage:
+        "Dieser Plan bleibt auf deinem Computer. Plan benötigt die Berechtigung des Browsers, um ihn über die lokale Verbindung zu lesen.",
+      deniedTitle: "Der Zugriff auf das lokale Netzwerk ist blockiert",
+      deniedMessage:
+        "Öffne die Website-Einstellungen deines Browsers für Plan, erlaube den Zugriff auf das lokale Netzwerk und prüfe es dann erneut.",
+      connect: "Mit lokalem Plan verbinden",
+      checkAgain: "Erneut prüfen",
+    },
     overview: {
       title: "planen",
       documentCount_other: "{{count}} Dokumente",

package/corpus/templates/plan/app/i18n/en-US.ts

@@ -433,6 +433,16 @@ const messages = {
       title: "Local plan not found",
       message: 'The local plan folder "{{slug}}" could not be read.',
     },
+    localPlanConnection: {
+      promptTitle: "Connect to this local plan",
+      promptMessage:
+        "This plan stays on your computer. Plan needs browser permission to read it from the local bridge.",
+      deniedTitle: "Local network access is blocked",
+      deniedMessage:
+        "Open your browser's site settings for Plan, allow local network access, then check again.",
+      connect: "Connect to local plan",
+      checkAgain: "Check again",
+    },
     overview: {
       title: "Plans",
       documentCount_one: "{{count}} document",

package/corpus/templates/plan/app/i18n/es-ES.ts

@@ -500,6 +500,16 @@ const messages = {
       message: 'No se pudo leer la carpeta del plan local "{{slug}}".',
       title: "Plan local no encontrado",
     },
+    localPlanConnection: {
+      promptTitle: "Conectarse a este plan local",
+      promptMessage:
+        "Este plan permanece en tu ordenador. Plan necesita permiso del navegador para leerlo desde el puente local.",
+      deniedTitle: "El acceso a la red local está bloqueado",
+      deniedMessage:
+        "Abre la configuración del sitio de Plan en el navegador, permite el acceso a la red local y vuelve a comprobarlo.",
+      connect: "Conectarse al plan local",
+      checkAgain: "Comprobar de nuevo",
+    },
     loggedOut: {
       copied: "copiado",
       copy: "Copiar",

package/corpus/templates/plan/app/i18n/fr-FR.ts

@@ -502,6 +502,16 @@ const messages = {
       message: 'Le dossier du plan local "{{slug}}" n\'a pas pu être lu.',
       title: "Plan local introuvable",
     },
+    localPlanConnection: {
+      promptTitle: "Se connecter à ce plan local",
+      promptMessage:
+        "Ce plan reste sur votre ordinateur. Plan a besoin de l’autorisation du navigateur pour le lire depuis le pont local.",
+      deniedTitle: "L’accès au réseau local est bloqué",
+      deniedMessage:
+        "Ouvrez les paramètres du site de Plan dans votre navigateur, autorisez l’accès au réseau local, puis vérifiez à nouveau.",
+      connect: "Se connecter au plan local",
+      checkAgain: "Vérifier à nouveau",
+    },
     loggedOut: {
       copied: "Copié",
       copy: "Copie",

package/corpus/templates/plan/app/i18n/hi-IN.ts

@@ -431,6 +431,16 @@ const messages = {
       title: "स्थानीय योजना नहीं मिली",
       message: 'स्थानीय योजना फ़ोल्डर "{{slug}}" पढ़ा नहीं जा सका।',
     },
+    localPlanConnection: {
+      promptTitle: "इस स्थानीय योजना से कनेक्ट करें",
+      promptMessage:
+        "यह योजना आपके कंप्यूटर पर ही रहती है। इसे स्थानीय ब्रिज से पढ़ने के लिए Plan को ब्राउज़र की अनुमति चाहिए।",
+      deniedTitle: "स्थानीय नेटवर्क की पहुँच अवरुद्ध है",
+      deniedMessage:
+        "अपने ब्राउज़र में Plan की साइट सेटिंग खोलें, स्थानीय नेटवर्क की पहुँच की अनुमति दें और फिर दोबारा जाँचें।",
+      connect: "स्थानीय योजना से कनेक्ट करें",
+      checkAgain: "फिर से जाँचें",
+    },
     overview: {
       title: "योजना",
       documentCount_other: "{{count}} दस्तावेज़",

package/corpus/templates/plan/app/i18n/ja-JP.ts

@@ -443,6 +443,16 @@ const messages = {
       title: "ローカルプランが見つかりません",
       message: "ローカル プラン フォルダー「{{slug}}」を読み取れませんでした。",
     },
+    localPlanConnection: {
+      promptTitle: "このローカルプランに接続",
+      promptMessage:
+        "このプランはコンピューター上に保存されています。ローカルブリッジから読み取るには、Plan にブラウザーの許可が必要です。",
+      deniedTitle: "ローカルネットワークへのアクセスがブロックされています",
+      deniedMessage:
+        "ブラウザーで Plan のサイト設定を開き、ローカルネットワークへのアクセスを許可してから、もう一度確認してください。",
+      connect: "ローカルプランに接続",
+      checkAgain: "もう一度確認",
+    },
     overview: {
       title: "计划",
       documentCount_other: "{{count}} 个文档",

package/corpus/templates/plan/app/i18n/ko-KR.ts

@@ -432,6 +432,16 @@ const messages = {
       title: "지역 계획을 찾을 수 없습니다.",
       message: '로컬 계획 폴더 "{{slug}}"을(를) 읽을 수 없습니다.',
     },
+    localPlanConnection: {
+      promptTitle: "이 로컬 계획에 연결",
+      promptMessage:
+        "이 계획은 컴퓨터에 그대로 보관됩니다. 로컬 브리지에서 읽으려면 Plan에 브라우저 권한이 필요합니다.",
+      deniedTitle: "로컬 네트워크 접근이 차단되었습니다",
+      deniedMessage:
+        "브라우저에서 Plan의 사이트 설정을 열고 로컬 네트워크 접근을 허용한 다음 다시 확인하세요.",
+      connect: "로컬 계획에 연결",
+      checkAgain: "다시 확인",
+    },
     overview: {
       title: "计划",
       documentCount_other: "{{count}} 个文档",

package/corpus/templates/plan/app/i18n/pt-BR.ts

@@ -445,6 +445,16 @@ const messages = {
       title: "Plano local não encontrado",
       message: 'A pasta do plano local "{{slug}}" não pôde ser lida.',
     },
+    localPlanConnection: {
+      promptTitle: "Conectar a este plano local",
+      promptMessage:
+        "Este plano permanece no seu computador. O Plan precisa da permissão do navegador para lê-lo pela ponte local.",
+      deniedTitle: "O acesso à rede local está bloqueado",
+      deniedMessage:
+        "Abra as configurações do site do Plan no navegador, permita o acesso à rede local e verifique novamente.",
+      connect: "Conectar ao plano local",
+      checkAgain: "Verificar novamente",
+    },
     overview: {
       title: "plano",
       documentCount_other: "{{count}} documentos",

package/corpus/templates/plan/app/i18n/zh-CN.ts

@@ -468,6 +468,16 @@ const messages = {
       message: "无法读取本地计划文件夹“{{slug}}”。",
       title: "未找到本地计划",
     },
+    localPlanConnection: {
+      promptTitle: "连接到此本地计划",
+      promptMessage:
+        "此计划保留在你的电脑上。Plan 需要浏览器权限才能通过本地桥接读取它。",
+      deniedTitle: "本地网络访问已被阻止",
+      deniedMessage:
+        "打开浏览器中 Plan 的网站设置，允许访问本地网络，然后再次检查。",
+      connect: "连接到本地计划",
+      checkAgain: "再次检查",
+    },
     loggedOut: {
       copied: "已复制",
       copy: "复制",

package/corpus/templates/plan/app/i18n/zh-TW.ts

@@ -468,6 +468,16 @@ const messages = {
       message: "無法讀取本機計畫資料夾“{{slug}}”。",
       title: "未找到本機計畫",
     },
+    localPlanConnection: {
+      promptTitle: "連線至此本機計畫",
+      promptMessage:
+        "此計畫會保留在你的電腦上。Plan 需要瀏覽器權限，才能透過本機橋接讀取它。",
+      deniedTitle: "本機網路存取已遭封鎖",
+      deniedMessage:
+        "開啟瀏覽器中 Plan 的網站設定，允許存取本機網路，然後再次檢查。",
+      connect: "連線至本機計畫",
+      checkAgain: "再次檢查",
+    },
     loggedOut: {
       copied: "已複製",
       copy: "複製",

package/corpus/templates/plan/app/lib/plan-local-bridge.ts

@@ -46,6 +46,53 @@ type LocalPlanBridgeCommentUpdate = {
   deletedCommentIds?: string[];
 };
 
+export type LocalNetworkAccessPermissionState =
+  | "checking"
+  | "prompt"
+  | "granted"
+  | "denied"
+  | "unsupported";
+
+export class LocalPlanBridgePermissionError extends Error {
+  readonly permissionState: "prompt" | "denied";
+
+  constructor(permissionState: "prompt" | "denied") {
+    super(
+      permissionState === "denied"
+        ? "Local network access is blocked for this site. Open your browser's site settings for Plan, allow local network access, then retry."
+        : "Plan needs permission to connect to the local plan on this computer. Allow local network access in your browser, then retry.",
+    );
+    this.name = "LocalPlanBridgePermissionError";
+    this.permissionState = permissionState;
+  }
+}
+
+export async function localNetworkAccessPermissionState(): Promise<
+  Exclude<LocalNetworkAccessPermissionState, "checking">
+> {
+  if (typeof navigator === "undefined" || !navigator.permissions?.query) {
+    return "unsupported";
+  }
+  try {
+    // Chrome 145 split this permission into local-network and
+    // loopback-network, but keeps the Chrome 142 alias working for queries.
+    const status = await navigator.permissions.query({
+      name: "local-network-access",
+    } as unknown as PermissionDescriptor);
+    if (
+      status.state === "granted" ||
+      status.state === "denied" ||
+      status.state === "prompt"
+    ) {
+      return status.state;
+    }
+  } catch {
+    // Browsers without Local Network Access expose Permissions but reject the
+    // Chrome-specific permission name. Fall through to the legacy fetch path.
+  }
+  return "unsupported";
+}
+
 function assertLocalBridgeUrl(value: string): string {
   let url: URL;
   try {
@@ -92,6 +139,7 @@ export function shouldRetryLocalPlanBridgeBundle(
   failureCount: number,
   error: unknown,
 ) {
+  if (error instanceof LocalPlanBridgePermissionError) return false;
   const message = error instanceof Error ? error.message : String(error ?? "");
   if (
     message.includes("Local plan bridge URL") ||
@@ -107,6 +155,28 @@ export function localPlanBridgeRetryDelay(attemptIndex: number) {
   return Math.min(500 * 2 ** attemptIndex, 2_500);
 }
 
+export function shouldShowLocalPlanLoadError(input: {
+  localPlanMode: boolean;
+  hasBundle: boolean;
+  hasBridgeUrl: boolean;
+  bridgeFetchEnabled: boolean;
+  error: unknown;
+  loading: boolean;
+  fetching: boolean;
+  permissionState: LocalNetworkAccessPermissionState;
+}): boolean {
+  if (!input.localPlanMode || input.hasBundle) return false;
+  if (input.hasBridgeUrl && !input.bridgeFetchEnabled) return false;
+  if (
+    input.error instanceof LocalPlanBridgePermissionError &&
+    (input.permissionState === "granted" ||
+      input.permissionState === "unsupported")
+  ) {
+    return false;
+  }
+  return Boolean(input.error) || (!input.loading && !input.fetching);
+}
+
 /**
  * Decide whether the hosted-plan render should surface the retryable load
  * error card instead of the initial skeleton.
@@ -342,7 +412,16 @@ export async function fetchLocalPlanBridgeBundle(
   fallbackSlug: string,
 ): Promise<LocalPlanBundle> {
   const safeUrl = assertLocalBridgeUrl(bridgeUrl);
-  const response = await fetch(safeUrl, { cache: "no-store" });
+  let response: Response;
+  try {
+    response = await fetch(safeUrl, { cache: "no-store" });
+  } catch (error) {
+    const permissionState = await localNetworkAccessPermissionState();
+    if (permissionState === "prompt" || permissionState === "denied") {
+      throw new LocalPlanBridgePermissionError(permissionState);
+    }
+    throw error;
+  }
   const payload = (await response
     .json()
     .catch(() => null)) as LocalPlanBridgePayload | null;