@agent-native/core 0.97.0 → 0.98.1

package/corpus/templates/plan/actions/create-ui-plan.ts

@@ -34,7 +34,10 @@ import {
   sectionInputSchema,
   writeEvent,
 } from "../server/plans.js";
-import { planContentSchema } from "../shared/plan-content.js";
+import {
+  agentPlanContentSchema,
+  planContentSchema,
+} from "../shared/plan-content.js";
 
 const uiPlanStateSchema = z.object({
   name: z.string().min(1).describe("State or screen name"),
@@ -52,64 +55,76 @@ const uiPlanComponentSchema = z.object({
     .describe("Intent, constraints, and details for this UI part"),
 });
 
+const CONTENT_DESCRIPTION =
+  'Structured editable UI plan content. Prefer this for app-owned top canvas wireframes (HTML mockups: set the wireframe\'s data.html to a semantic HTML fragment of the screen and pick a surface — the renderer owns the theme, footprint/aspect, hand-drawn font, and sketch overlay; use --wf-* CSS tokens for any custom color, never hex). Call get-plan-blocks first for visual frame guidance before choosing frame: "show" or frame: "hide". Do not use legacy kit-tree screen arrays or nested FrameScreen/Card/Row/Btn-style children for new canvas artboards. Use sketch diagrams, rich text, code blocks (grouped in a vertical tabs block for a file map), annotated code for key files, validation checklists, and bounded custom HTML fragments. Diagram data.html/data.css should use renderer-owned .diagram-* primitives plus --wf-* tokens, not custom fonts or hard-coded hex/rgb/hsl colors, so light/dark and sketchy Excalifont/rough.js modes remain correct. The canvas should carry Claude-style flex/grid wireframe artboards and designer annotations; the document should add implementation substance instead of duplicating the same wireframes. The renderer owns all visual styling; emit lean content, not pixels.';
+
+// Named (and un-refined) so `agentInputSchema` below can `.extend()` it with
+// a compact `content` field instead of duplicating every other key. The
+// `.refine()` (brief/goal requirement) only applies to the real runtime
+// `schema` further down.
+const createUiPlanSchema = z.object({
+  title: z.string().optional().describe("Short UI plan title"),
+  brief: z
+    .string()
+    .optional()
+    .describe(
+      "One short sentence summarizing the UI plan, shown as the lede under the title. Keep it to a single tight line; the document carries the detail.",
+    ),
+  goal: z.string().optional().describe("Alias for brief."),
+  source: planSourceSchema.optional().default("manual"),
+  repoPath: z.string().optional().describe("Repository path for the run"),
+  currentFocus: z.string().optional().describe("Current UI plan focus"),
+  status: planStatusSchema.optional().default("review"),
+  content: planContentSchema.optional().describe(CONTENT_DESCRIPTION),
+  markdown: z
+    .string()
+    .optional()
+    .describe("Markdown/text fallback or source UI plan"),
+  states: z
+    .array(uiPlanStateSchema)
+    .optional()
+    .default([])
+    .describe(
+      "Screens or states to show primarily on the optional top pan/zoom canvas, such as Default, Empty, Loading, Error, Mobile, or Agent handoff. For component/widget work, prefer focused component variants and one real product-context frame over fake desktop/mobile journeys. Omit when visual states would not help.",
+    ),
+  components: z
+    .array(uiPlanComponentSchema)
+    .optional()
+    .default([])
+    .describe(
+      "Focused UI parts and constraints for canvas annotations and the implementation document. Do not use these to create redundant wireframe tabs when the top canvas already shows the UI.",
+    ),
+  implementationNotes: z
+    .string()
+    .optional()
+    .describe("Concise notes for the implementation map section"),
+  sections: z
+    .array(sectionInputSchema)
+    .optional()
+    .default([])
+    .describe("Optional additional plan sections"),
+  comments: z
+    .array(commentInputSchema)
+    .optional()
+    .default([])
+    .describe("Initial annotations or review prompts"),
+});
+
 export default defineAction({
   description:
     "Create a UI-first plan whose centerpiece is wireframed screens/states on a canvas. For a document-first plan use create-visual-plan; for a recap of an existing diff use create-visual-recap; for a running interactive prototype use create-prototype-plan; for a full-fidelity branded design use create-plan-design. Publish via this tool; never deliver the plan as inline chat text.",
-  schema: z
-    .object({
-      title: z.string().optional().describe("Short UI plan title"),
-      brief: z
-        .string()
-        .optional()
-        .describe(
-          "One short sentence summarizing the UI plan, shown as the lede under the title. Keep it to a single tight line; the document carries the detail.",
-        ),
-      goal: z.string().optional().describe("Alias for brief."),
-      source: planSourceSchema.optional().default("manual"),
-      repoPath: z.string().optional().describe("Repository path for the run"),
-      currentFocus: z.string().optional().describe("Current UI plan focus"),
-      status: planStatusSchema.optional().default("review"),
-      content: planContentSchema
-        .optional()
-        .describe(
-          'Structured editable UI plan content. Prefer this for app-owned top canvas wireframes (HTML mockups: set the wireframe\'s data.html to a semantic HTML fragment of the screen and pick a surface — the renderer owns the theme, footprint/aspect, hand-drawn font, and sketch overlay; use --wf-* CSS tokens for any custom color, never hex). Call get-plan-blocks first for visual frame guidance before choosing frame: "show" or frame: "hide". Do not use legacy kit-tree screen arrays or nested FrameScreen/Card/Row/Btn-style children for new canvas artboards. Use sketch diagrams, rich text, code blocks (grouped in a vertical tabs block for a file map), annotated code for key files, validation checklists, and bounded custom HTML fragments. Diagram data.html/data.css should use renderer-owned .diagram-* primitives plus --wf-* tokens, not custom fonts or hard-coded hex/rgb/hsl colors, so light/dark and sketchy Excalifont/rough.js modes remain correct. The canvas should carry Claude-style flex/grid wireframe artboards and designer annotations; the document should add implementation substance instead of duplicating the same wireframes. The renderer owns all visual styling; emit lean content, not pixels.',
-        ),
-      markdown: z
-        .string()
-        .optional()
-        .describe("Markdown/text fallback or source UI plan"),
-      states: z
-        .array(uiPlanStateSchema)
-        .optional()
-        .default([])
-        .describe(
-          "Screens or states to show primarily on the optional top pan/zoom canvas, such as Default, Empty, Loading, Error, Mobile, or Agent handoff. For component/widget work, prefer focused component variants and one real product-context frame over fake desktop/mobile journeys. Omit when visual states would not help.",
-        ),
-      components: z
-        .array(uiPlanComponentSchema)
-        .optional()
-        .default([])
-        .describe(
-          "Focused UI parts and constraints for canvas annotations and the implementation document. Do not use these to create redundant wireframe tabs when the top canvas already shows the UI.",
-        ),
-      implementationNotes: z
-        .string()
-        .optional()
-        .describe("Concise notes for the implementation map section"),
-      sections: z
-        .array(sectionInputSchema)
-        .optional()
-        .default([])
-        .describe("Optional additional plan sections"),
-      comments: z
-        .array(commentInputSchema)
-        .optional()
-        .default([])
-        .describe("Initial annotations or review prompts"),
-    })
-    .refine((args) => Boolean(args.brief || args.goal), {
+  schema: createUiPlanSchema.refine(
+    (args) => Boolean(args.brief || args.goal),
+    {
       message: "Either brief or goal is required.",
-    }),
+    },
+  ),
+  // ADVERTISED-ONLY: same top-level shape, but `content` swaps 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: createUiPlanSchema.extend({
+    content: agentPlanContentSchema.optional().describe(CONTENT_DESCRIPTION),
+  }),
   publicAgent: {
     expose: true,
     readOnly: false,

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

@@ -36,7 +36,10 @@ import {
   sectionInputSchema,
   writeEvent,
 } from "../server/plans.js";
-import { planContentSchema } from "../shared/plan-content.js";
+import {
+  agentPlanContentSchema,
+  planContentSchema,
+} from "../shared/plan-content.js";
 
 function inferImportedPlanTitle(planText: string): string {
   const firstHeading = planText
@@ -51,59 +54,70 @@ function inferImportedPlanTitle(planText: string): string {
   return firstLine ? firstLine.slice(0, 90) : "Imported visual plan";
 }
 
+const CONTENT_DESCRIPTION =
+  "Structured editable plan content. Prefer this for rich text, inline diagrams, annotated code, question-form open questions, and optional canvas/prototype UI surfaces. Call the get-plan-blocks tool FIRST for the authoritative block catalog, visual frame guidance, authoring rules, and style tokens — do not author from memory. Key rules: canvas frames use wireframe data.html/html semantic HTML, not legacy kit-tree screen arrays; use diagram blocks with .diagram-* primitives and --wf-* tokens (no hex/rgb/hsl, no custom fonts); for file maps use annotated-code blocks in a vertical tabs block; put unresolved decisions in a bottom question-form block.";
+
+// Named (and un-refined) so `agentInputSchema` below can `.extend()` it with
+// a compact `content` field instead of duplicating every other key. The
+// `.refine()` (brief/goal/planText requirement) is applied only to the real
+// runtime `schema` further down — refine predicates aren't serializable JSON
+// Schema anyway, so the advertised copy never needs it.
+const createVisualPlanSchema = z.object({
+  title: z.string().optional().describe("Short plan title"),
+  brief: z
+    .string()
+    .optional()
+    .describe(
+      "One short sentence summarizing the plan, shown as the lede under the title. Keep it to a single tight line — the document body carries the detail, not this summary.",
+    ),
+  goal: z.string().optional().describe("Alias for brief."),
+  planText: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      "Existing Codex, Claude Code, Markdown, or pasted plan text to preserve and turn into a visual review plan.",
+    ),
+  source: planSourceSchema.optional(),
+  repoPath: z.string().optional().describe("Repository path for the run"),
+  currentFocus: z.string().optional().describe("Current plan focus"),
+  status: planStatusSchema.optional().default("review"),
+  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),
+  markdown: z
+    .string()
+    .optional()
+    .describe("Markdown/text fallback or source plan"),
+  sections: z
+    .array(sectionInputSchema)
+    .optional()
+    .default([])
+    .describe("Readable plan sections and visual blocks"),
+  comments: z
+    .array(commentInputSchema)
+    .optional()
+    .default([])
+    .describe("Initial annotations or review prompts"),
+});
+
 export default defineAction({
   description:
     "Create a document-first structured plan for any coding task. Call this EXACTLY ONCE per plan — produce the final plan in a single call. Do NOT create a draft and then a second 'clean' version; if you need to revise after creating, call update-visual-plan with the existing planId instead of creating another plan (each create renders its own embed, so a second create leaves a duplicate). For a plan whose centerpiece is wireframed screens/states on a canvas use create-ui-plan; for a recap of an existing diff use create-visual-recap; for a running interactive prototype use create-prototype-plan; for a full-fidelity branded design use create-plan-design. Also accepts imported Codex, Claude Code, Markdown, or pasted plan text via planText. Publish via this tool; never deliver the plan as inline chat text.",
-  schema: z
-    .object({
-      title: z.string().optional().describe("Short plan title"),
-      brief: z
-        .string()
-        .optional()
-        .describe(
-          "One short sentence summarizing the plan, shown as the lede under the title. Keep it to a single tight line — the document body carries the detail, not this summary.",
-        ),
-      goal: z.string().optional().describe("Alias for brief."),
-      planText: z
-        .string()
-        .min(1)
-        .optional()
-        .describe(
-          "Existing Codex, Claude Code, Markdown, or pasted plan text to preserve and turn into a visual review plan.",
-        ),
-      source: planSourceSchema.optional(),
-      repoPath: z.string().optional().describe("Repository path for the run"),
-      currentFocus: z.string().optional().describe("Current plan focus"),
-      status: planStatusSchema.optional().default("review"),
-      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(
-          "Structured editable plan content. Prefer this for rich text, inline diagrams, annotated code, question-form open questions, and optional canvas/prototype UI surfaces. Call the get-plan-blocks tool FIRST for the authoritative block catalog, visual frame guidance, authoring rules, and style tokens — do not author from memory. Key rules: canvas frames use wireframe data.html/html semantic HTML, not legacy kit-tree screen arrays; use diagram blocks with .diagram-* primitives and --wf-* tokens (no hex/rgb/hsl, no custom fonts); for file maps use annotated-code blocks in a vertical tabs block; put unresolved decisions in a bottom question-form block.",
-        ),
-      markdown: z
-        .string()
-        .optional()
-        .describe("Markdown/text fallback or source plan"),
-      sections: z
-        .array(sectionInputSchema)
-        .optional()
-        .default([])
-        .describe("Readable plan sections and visual blocks"),
-      comments: z
-        .array(commentInputSchema)
-        .optional()
-        .default([])
-        .describe("Initial annotations or review prompts"),
-    })
-    .refine((args) => Boolean(args.brief || args.goal || args.planText), {
-      message: "Either brief, goal, or planText is required.",
-    }),
+  schema: createVisualPlanSchema.refine(
+    (args) => Boolean(args.brief || args.goal || args.planText),
+    { message: "Either brief, goal, or planText is required." },
+  ),
+  // ADVERTISED-ONLY: same top-level shape, but `content` swaps 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: createVisualPlanSchema.extend({
+    content: agentPlanContentSchema.optional().describe(CONTENT_DESCRIPTION),
+  }),
   publicAgent: {
     expose: true,
     readOnly: false,

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/hooks/use-navigation-state.ts

@@ -55,7 +55,10 @@ export function useNavigationState() {
     }).catch(() => {});
   }, [location.pathname, location.search]);
 
-  // Listen for navigate commands from agent
+  // Listen for one-shot navigate commands from the agent. useDbSync
+  // invalidates this exact key when the shared SSE/poll transport receives an
+  // app-state:navigate event, so this stays idle between real commands instead
+  // of charging the host for a request every two seconds.
   const { data: navCommand } = useQuery({
     queryKey: ["navigate-command"],
     queryFn: async () => {
@@ -70,7 +73,7 @@ export function useNavigationState() {
       }
       return null;
     },
-    refetchInterval: 2_000,
+    retry: false,
     structuralSharing: false,
   });
 

package/corpus/templates/plan/app/hooks/use-plans.ts

@@ -17,7 +17,6 @@ import type {
   PlanVersionListResponse,
 } from "@shared/types";
 import { useQueryClient, type UseQueryOptions } from "@tanstack/react-query";
-import type { RefObject } from "react";
 import { toast } from "sonner";
 
 import type { PlanMdxFolder } from "@/lib/desktop-plan-files";
@@ -337,23 +336,17 @@ export function localPlanBundleQueryKey(slug: string, path?: string | null) {
   ] as const;
 }
 
-export function usePlan(
-  id?: string,
-  pausePollRef?: RefObject<boolean> | { current: boolean },
-) {
+export function usePlan(id?: string) {
   return useActionQuery<PlanBundle & { html?: string }>(
     "get-visual-plan",
     planBundleQueryParams(id ?? ""),
     {
       enabled: !!id,
-      // Pause the 3-second poll while a comment mutation is in-flight so
-      // an optimistic comment inserted into the cache isn't evicted before
-      // the server write commits (Issue 4a).
-      refetchInterval: (query: { state: { status: string } }) => {
-        if (query.state.status === "error") return false;
-        if (pausePollRef?.current) return false;
-        return 3_000;
-      },
+      // Mutating actions and collaboration writes already arrive through the
+      // shared useDbSync SSE/poll transport, which invalidates active action
+      // reads. Keep the last bundle visible during that targeted refresh and
+      // avoid repeatedly downloading the full plan while nothing changed.
+      placeholderData: (previous) => previous,
     },
   );
 }