@agent-native/core 0.85.7 → 0.86.0

package/corpus/templates/mail/.agents/skills/real-time-sync/SKILL.md

@@ -58,6 +58,21 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
 
 - Don't create manual polling loops — `useDbSync()` handles SSE plus fallback polling
 - Don't create your own fetch-based polling alongside `useDbSync` — use the `onEvent` callback for custom handling
+- Don't open your own `EventSource` to `/_agent-native/events`. A tab must hold exactly ONE SSE connection no matter how many features listen — extra streams eat the browser's per-origin connection budget and can starve ordinary data fetches (worst on HTTP/1.1 dev servers). Subscribe to the shared transport instead:
+
+  ```ts
+  import { subscribeSyncEvents } from "@agent-native/core/client";
+
+  const unsubscribe = subscribeSyncEvents({
+    onEvents: (events) => {
+      // filter by event.source and handle push-style updates
+    },
+    // Optional: relax your own fallback cadence while push is healthy.
+    onSseStateChange: (connected) => {},
+  });
+  ```
+
+  `useDbSync` and every `subscribeSyncEvents` subscriber share one `EventSource` and one fallback poll loop per tab — this is how collaborative documents receive doc updates and cursor/awareness events.
 
 ## Which sources to depend on
 

package/corpus/templates/mail/.agents/skills/storing-data/SKILL.md

@@ -25,6 +25,14 @@ Agent-native apps use Drizzle ORM over the configured SQL backend. Local develop
 
 For app code, use Drizzle's schema/query DSL by default. Raw SQL is an escape hatch for additive migrations, health checks, or one-off maintenance, not the normal way to build features.
 
+### Naming migrations
+
+When you add an entry to a `runMigrations([...])` list (`@agent-native/core/db`), always give it a unique `name:` slug (e.g. `name: "analytics-alert-rules-table"`) alongside its `version`. Never renumber or reuse version numbers on existing entries.
+
+Why: version numbers alone are not a safe identity. Two branches that each independently extend the same migration list can ship different DDL under the same version numbers — whichever branch deploys first "claims" those version numbers in the bookkeeping table, and the other branch's DDL is silently treated as already applied even though it never ran. This exact collision took down analytics: parallel branches both extended their migration list through v75-v83 with different DDL, so `analytics_alert_rules`, `analytics_alert_incidents`, and `session_recordings.network_error_count` never made it to production despite the bookkeeping table showing every version as applied. A `name:` slug is tracked independently of version numbers, so it applies exactly once per database regardless of what any other branch already recorded.
+
+Existing unnamed migrations don't need to be renamed retroactively (the two gating strategies coexist), but any new entry should always carry a name.
+
 ### Core SQL Stores (auto-created, available in all templates)
 
 | Store               | Purpose                                              | Access                                     |

package/corpus/templates/mail/package.json

@@ -62,8 +62,8 @@
     "@radix-ui/react-toggle": "^1.1.9",
     "@radix-ui/react-toggle-group": "^1.1.10",
     "@radix-ui/react-tooltip": "^1.2.7",
-    "@react-router/dev": "^8.0.1",
-    "@react-router/fs-routes": "^8.0.1",
+    "@react-router/dev": "^8.1.0",
+    "@react-router/fs-routes": "^8.1.0",
     "@swc/core": "^1.13.3",
     "@tailwindcss/typography": "^0.5.16",
     "@tailwindcss/vite": "catalog:",
@@ -95,7 +95,7 @@
     "react-dom": "catalog:",
     "react-hook-form": "^7.71.2",
     "react-resizable-panels": "^4.10.0",
-    "react-router": "^8.0.1",
+    "react-router": "^8.1.0",
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.5.0",
     "tailwindcss": "catalog:",

package/corpus/templates/mail/server/lib/contact-frequency.ts

@@ -8,35 +8,62 @@ function makeId(owner: string, contact: string): string {
 
 /**
  * Increment contact frequency after sending an email.
- * Upserts a row for each recipient.
+ * Upserts a row for each recipient in a single batched statement.
  */
 export async function incrementSendFrequency(
   ownerEmail: string,
   recipients: { email: string; name?: string }[],
 ): Promise<void> {
+  if (recipients.length === 0) return;
+
   const now = Date.now();
+
+  // De-dupe by conflict key (id), summing send counts for repeated emails.
+  // A single multi-row insert can't target the same conflict key twice —
+  // Postgres raises "ON CONFLICT DO UPDATE command cannot affect row a
+  // second time" — so recipients appearing more than once in one call must
+  // be merged before the insert.
+  const byId = new Map<
+    string,
+    { id: string; contactEmail: string; contactName: string; sendCount: number }
+  >();
   for (const r of recipients) {
     const id = makeId(ownerEmail, r.email);
-    await db
-      .insert(schema.contactFrequency)
-      .values({
+    const existing = byId.get(id);
+    if (existing) {
+      existing.sendCount += 1;
+      if (r.name) existing.contactName = r.name;
+    } else {
+      byId.set(id, {
         id,
-        ownerEmail: ownerEmail.toLowerCase(),
         contactEmail: r.email.toLowerCase(),
         contactName: r.name || "",
         sendCount: 1,
-        receiveCount: 0,
-        lastContactedAt: now,
-      })
-      .onConflictDoUpdate({
-        target: schema.contactFrequency.id,
-        set: {
-          sendCount: sql`${schema.contactFrequency.sendCount} + 1`,
-          contactName: r.name || sql`${schema.contactFrequency.contactName}`,
-          lastContactedAt: now,
-        },
       });
+    }
   }
+
+  const values = Array.from(byId.values()).map((r) => ({
+    id: r.id,
+    ownerEmail: ownerEmail.toLowerCase(),
+    contactEmail: r.contactEmail,
+    contactName: r.contactName,
+    sendCount: r.sendCount,
+    receiveCount: 0,
+    lastContactedAt: now,
+  }));
+
+  await db
+    .insert(schema.contactFrequency)
+    .values(values)
+    .onConflictDoUpdate({
+      target: schema.contactFrequency.id,
+      set: {
+        sendCount: sql`${schema.contactFrequency.sendCount} + excluded.send_count`,
+        contactName: sql`case when excluded.contact_name != '' then excluded.contact_name else ${schema.contactFrequency.contactName} end`,
+        lastContactedAt: sql`excluded.last_contacted_at`,
+      },
+    });
 }
 
 /**

package/corpus/templates/mail/server/plugins/db.ts

@@ -1,6 +1,35 @@
-import { runMigrations, intType } from "@agent-native/core/db";
+import {
+  ensureAdditiveColumns,
+  getDbExec,
+  runMigrations,
+  intType,
+} from "@agent-native/core/db";
 
-export default runMigrations(
+import * as schema from "../db/schema.js";
+
+/**
+ * Every Drizzle table exported from schema.ts. Filters out type-only and
+ * helper exports the same way db.spec.ts's `isDrizzleTable` regression guard
+ * does: a real table carries a Symbol-keyed drizzle metadata bag, plain
+ * exports don't.
+ */
+function isDrizzleTable(value: unknown): value is object {
+  return (
+    !!value &&
+    typeof value === "object" &&
+    Object.getOwnPropertySymbols(value).some((s) =>
+      s.toString().includes("drizzle"),
+    )
+  );
+}
+
+const schemaTables = Object.values(schema).filter(isDrizzleTable);
+
+// Convention: every new migration below MUST set a unique `name:` slug (see
+// packages/core/src/db/migrations.ts for the full rationale). Version numbers
+// alone are not a safe identity across parallel branches that each extend
+// this list independently.
+const runMailMigrations = runMigrations(
   [
     {
       version: 1,
@@ -133,3 +162,35 @@ CREATE INDEX IF NOT EXISTS idx_automation_rules_owner ON automation_rules(owner_
   ],
   { table: "mail_migrations" },
 );
+
+/**
+ * The migration list above is the authoritative source for tables, indexes,
+ * and data transforms. `ensureAdditiveColumns` runs after it as a
+ * belt-and-braces safety net for the failure mode where a column is added to
+ * schema.ts without a matching hand-written ALTER migration, which silently
+ * 500s every query touching a pre-existing production table. It only ever
+ * adds missing columns — never drops, renames, or retypes anything — and any
+ * failure here is logged and swallowed so it can never fail boot.
+ */
+export default async (nitroApp: any): Promise<void> => {
+  await runMailMigrations(nitroApp);
+  try {
+    const summary = await ensureAdditiveColumns({
+      db: getDbExec(),
+      tables: schemaTables,
+    });
+    if (summary.errors.length > 0) {
+      console.warn(
+        "[db] ensureAdditiveColumns completed with errors:",
+        summary.errors,
+      );
+    }
+  } catch (err) {
+    // Never fail boot over the safety net itself — the authoritative
+    // migrations above already ran.
+    console.warn(
+      "[db] ensureAdditiveColumns failed (non-fatal):",
+      err instanceof Error ? err.message : err,
+    );
+  }
+};

package/corpus/templates/plan/.agents/skills/real-time-sync/SKILL.md

@@ -58,6 +58,21 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
 
 - Don't create manual polling loops — `useDbSync()` handles SSE plus fallback polling
 - Don't create your own fetch-based polling alongside `useDbSync` — use the `onEvent` callback for custom handling
+- Don't open your own `EventSource` to `/_agent-native/events`. A tab must hold exactly ONE SSE connection no matter how many features listen — extra streams eat the browser's per-origin connection budget and can starve ordinary data fetches (worst on HTTP/1.1 dev servers). Subscribe to the shared transport instead:
+
+  ```ts
+  import { subscribeSyncEvents } from "@agent-native/core/client";
+
+  const unsubscribe = subscribeSyncEvents({
+    onEvents: (events) => {
+      // filter by event.source and handle push-style updates
+    },
+    // Optional: relax your own fallback cadence while push is healthy.
+    onSseStateChange: (connected) => {},
+  });
+  ```
+
+  `useDbSync` and every `subscribeSyncEvents` subscriber share one `EventSource` and one fallback poll loop per tab — this is how collaborative documents receive doc updates and cursor/awareness events.
 
 ## Which sources to depend on
 

package/corpus/templates/plan/.agents/skills/visual-plan/SKILL.md

@@ -433,9 +433,10 @@ not hit an OAuth wall:
 npx @agent-native/core@latest skills add visual-plans
 ```
 
-After that, `/visual-plan` and `/visual-recap` are the two installed slash
-commands. If you only need one command, use `skills add visual-plan` or
-`skills add visual-recap` instead. The other planning modes
+After that, `/visual-plan`, `/visual-recap`, and `/visualize-repo` are the
+installed slash commands. If you only need one command, use
+`skills add visual-plan`, `skills add visual-recap`, or
+`skills add visualize-repo` instead. The other planning modes
 (`create-ui-plan`, `create-prototype-plan`, `create-plan-design`,
 `create-visual-questions`) are MCP tools reachable from `/visual-plan`, not
 separate slash commands. Pass `--no-connect` to register the connector without
@@ -455,6 +456,11 @@ For fully offline, no-account use, run the Plans app locally and sync plans to
 your repo as MDX. This local mode is a separate advanced path, not the default
 hosted flow.
 
+For repo-wide visual docs, run
+`npx @agent-native/core@latest visualize-repo --open` to create/update
+`agent-native.json`, seed `.agent-native/visual-docs/repo-overview`, and open
+the local bridge.
+
 If a Plans tool returns `needs auth`, `Unauthorized`, or `Session terminated`, do
 not keep retrying it — stop and give the user the per-client reconnect step from
 `references/connection.md`, then continue once the connector is available.

package/corpus/templates/plan/.agents/skills/visualize-repo/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: visualize-repo
+description: >-
+  Open or create a repo-native visual documentation workspace backed by local
+  Plan MDX files. Use when the user asks to visualize a repository, create
+  durable visual docs for APIs/components/models/flows, launch a visual repo
+  viewer, review repo docs like a visual IDE, or collect Plan comments that
+  should become coding-agent changes.
+metadata:
+  visibility: exported
+---
+
+# Visualize Repo
+
+`/visualize-repo` opens a local, source-controlled visual documentation layer
+for a repository. It is for durable repo understanding, not a one-off plan:
+components can have wireframes, APIs can have specs, models can have schema
+views, and reviewers can comment on those docs before sending work to a coding
+agent.
+
+## Default Command
+
+Run the Agent-Native CLI from the repo root:
+
+```bash
+npx @agent-native/core@latest visualize-repo --open
+```
+
+Useful variants:
+
+```bash
+npx @agent-native/core@latest visualize-repo init
+npx @agent-native/core@latest visualize-repo --target actions --target server/db/schema.ts
+npx @agent-native/core@latest visualize-repo check
+npx @agent-native/core@latest visualize-repo verify
+npx @agent-native/core@latest visualize-repo --no-open
+```
+
+The command writes or updates `agent-native.json` with an
+`apps.visualize-repo` local-files section, creates a starter MDX folder at
+`.agent-native/visual-docs/repo-overview`, then serves it through the Plan
+local bridge. The hosted Plan UI can render the review surface, but the plan
+source stays in local files and bridge comments stay in `comments.json`.
+
+## When There Is No Manifest
+
+If `agent-native.json` does not exist, let the CLI bootstrap one. It scans for
+high-value starting points such as `actions/`, `app/components/`,
+`app/pages/`, `server/db/schema.ts`, `src/`, `packages/`, `templates/`,
+`docs/`, and `content/`. Keep the first run targeted. Prefer 5-20 visualized
+nodes over a generated wall of repo prose.
+
+Use explicit targets when the user already knows the important surface:
+
+```bash
+npx @agent-native/core@latest visualize-repo \
+  --target actions/webhooks.ts \
+  --target server/db/schema.ts \
+  --target app/components/PromptComposer.tsx
+```
+
+## Agent Workflow
+
+1. Inspect `agent-native.json` and the generated `plan.mdx`.
+2. Read the source anchors listed for each target before changing the visual
+   docs.
+3. Add only the visual blocks that earn their keep: `api-endpoint` for stable
+   APIs, `data-model` for durable schema, `wireframe` for user-facing
+   components/flows, `diagram` for architecture, and `annotated-code` for
+   load-bearing implementation.
+4. Run `npx @agent-native/core@latest visualize-repo check` after editing MDX.
+5. Use `verify` before handoff when renderer correctness matters.
+
+When acting on comments, treat local `comments.json` as the feedback inbox.
+Agent-targeted comments should become code changes plus matching MDX updates so
+the visual docs and executable code stay in sync.
+
+## Privacy Boundary
+
+`visualize-repo check` is local/offline lint. `visualize-repo --open` starts a
+localhost bridge and opens the Plan UI against local files; it does not publish
+the plan to hosted storage and performs no hosted Plan database writes.
+`visualize-repo verify` may send the MDX folder to the Plan app's public
+validation action so the real renderer schema can check it. For no hosted
+content egress, pass `--app-url` pointing at a local Plan app or skip
+`verify` and rely on `check`.
+
+Do not call hosted Plan write tools for this workflow unless the user explicitly
+asks to publish or share the docs. Avoid `create-visual-plan`,
+`update-visual-plan`, `import-visual-plan-source`, `patch-visual-plan-source`,
+and `get-plan-feedback` for local repo docs; edit the MDX files directly and
+use the local bridge.

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

@@ -7,6 +7,7 @@ import {
 } from "../server/plan-mdx.js";
 import {
   buildPlanHtml,
+  loadFullPlanEvents,
   loadPlanBundle,
   planDeepLink,
   planPath,
@@ -29,6 +30,10 @@ export default defineAction({
   },
   run: async (args) => {
     const bundle = await loadPlanBundle(args.planId);
+    // The bundle caps events at the most recent 50 for the hot polled path;
+    // an export is a rare, explicit "durable receipt" so it carries the full
+    // activity history. loadPlanBundle already resolved access above.
+    bundle.events = await loadFullPlanEvents(args.planId);
     const path = planPath(bundle.plan.id, bundle.plan.kind);
     const mdx = await exportPlanContentToMdxFolder({
       content: bundle.plan.content,

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

@@ -7,10 +7,12 @@ import {
   readLocalPlanComments,
   readPlanLocalFolder,
 } from "../server/lib/local-plan-files.js";
+import {
+  localPlanKindSchema,
+  resolveLocalPlanKind,
+} from "../server/lib/local-plan-kind.js";
 import type { PlanKind } from "../shared/types.js";
 
-const localPlanKindSchema = z.enum(["plan", "recap"]);
-
 export default defineAction({
   description:
     "Read a DB-free local Agent-Native Plan MDX folder from PLAN_LOCAL_DIR or an optional repo-relative path for privacy-focused local-files preview. This never reads schema.plans and never writes to the database.",
@@ -71,23 +73,3 @@ export default defineAction({
     view: "plan",
   }),
 });
-
-function resolveLocalPlanKind(
-  explicit: "plan" | "recap" | undefined,
-  mdx: { "plan.mdx": string; ".plan-state.json"?: string },
-): "plan" | "recap" {
-  if (explicit) return explicit;
-  const frontmatterMatch = mdx["plan.mdx"].match(
-    /^---[\s\S]*?^kind:\s*["']?(plan|recap)["']?\s*$/m,
-  );
-  if (frontmatterMatch) return frontmatterMatch[1] as "plan" | "recap";
-  try {
-    const state = mdx[".plan-state.json"]
-      ? (JSON.parse(mdx[".plan-state.json"]) as { kind?: unknown })
-      : null;
-    if (state?.kind === "plan" || state?.kind === "recap") return state.kind;
-  } catch {
-    // Optional state file.
-  }
-  return "plan";
-}

package/corpus/templates/plan/actions/get-plan-version.ts

@@ -1,19 +1,17 @@
 import { defineAction } from "@agent-native/core";
-import {
-  ForbiddenError,
-  currentAccess,
-  resolveAccess,
-} from "@agent-native/core/sharing";
 import { and, eq } from "drizzle-orm";
 import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
-import { resolvePlanAccessContext } from "../server/lib/local-identity.js";
 import {
   parsePlanVersionSnapshot,
   summarizePlanVersion,
 } from "../server/lib/plan-versions.js";
-import { buildPlanHtml, summarizePlan } from "../server/plans.js";
+import {
+  assertPlanEditor,
+  buildPlanHtml,
+  summarizePlan,
+} from "../server/plans.js";
 import type { Plan, PlanBundle } from "../shared/types.js";
 
 export default defineAction({
@@ -33,15 +31,7 @@ export default defineAction({
     description: "Read one saved version of a visual plan.",
   },
   run: async ({ planId, versionId }) => {
-    const access = await resolveAccess(
-      "plan",
-      planId,
-      resolvePlanAccessContext(currentAccess()),
-    );
-    if (!access) throw new ForbiddenError(`Plan ${planId} not found`);
-    if ((access.resource as typeof schema.plans.$inferSelect).deletedAt) {
-      throw new ForbiddenError(`Plan ${planId} not found`);
-    }
+    const access = await assertPlanEditor(planId);
 
     const ownerEmail = access.resource.ownerEmail as string;
     const [version] = await getDb()

package/corpus/templates/plan/actions/list-plan-versions.ts

@@ -1,15 +1,10 @@
 import { defineAction } from "@agent-native/core";
-import {
-  ForbiddenError,
-  currentAccess,
-  resolveAccess,
-} from "@agent-native/core/sharing";
-import { and, desc, eq } from "drizzle-orm";
+import { and, desc, eq, inArray } from "drizzle-orm";
 import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
-import { resolvePlanAccessContext } from "../server/lib/local-identity.js";
-import { summarizePlanVersion } from "../server/lib/plan-versions.js";
+import { summarizePlanVersionRow } from "../server/lib/plan-versions.js";
+import { assertPlanEditor } from "../server/plans.js";
 
 export default defineAction({
   description:
@@ -28,19 +23,31 @@ export default defineAction({
     description: "List saved version history for a visual plan.",
   },
   run: async ({ planId, limit }) => {
-    const access = await resolveAccess(
-      "plan",
-      planId,
-      resolvePlanAccessContext(currentAccess()),
-    );
-    if (!access) throw new ForbiddenError(`Plan ${planId} not found`);
-    if ((access.resource as typeof schema.plans.$inferSelect).deletedAt) {
-      throw new ForbiddenError(`Plan ${planId} not found`);
-    }
+    const access = await assertPlanEditor(planId);
 
     const ownerEmail = access.resource.ownerEmail as string;
-    const versions = await getDb()
-      .select()
+    const db = getDb();
+    // Project only the small columns + denormalized summary columns instead of
+    // `.select()`-ing every row's full `snapshot_json` (the entire plan +
+    // sections blob) just to JSON.parse it for a list view. Rows written
+    // before the summary columns existed have `blockCount === null`; for
+    // those (and only those) we fetch + parse `snapshot_json` below.
+    const versions = await db
+      .select({
+        id: schema.planVersions.id,
+        planId: schema.planVersions.planId,
+        title: schema.planVersions.title,
+        changeLabel: schema.planVersions.changeLabel,
+        createdBy: schema.planVersions.createdBy,
+        createdAt: schema.planVersions.createdAt,
+        status: schema.planVersions.status,
+        source: schema.planVersions.source,
+        blockCount: schema.planVersions.blockCount,
+        sectionCount: schema.planVersions.sectionCount,
+        hasCanvas: schema.planVersions.hasCanvas,
+        hasPrototype: schema.planVersions.hasPrototype,
+        previewText: schema.planVersions.previewText,
+      })
       .from(schema.planVersions)
       .where(
         and(
@@ -51,10 +58,31 @@ export default defineAction({
       .orderBy(desc(schema.planVersions.createdAt))
       .limit(limit);
 
+    const legacyIds = versions
+      .filter((version) => version.blockCount == null)
+      .map((version) => version.id);
+    const legacySnapshots = legacyIds.length
+      ? await db
+          .select({
+            id: schema.planVersions.id,
+            snapshotJson: schema.planVersions.snapshotJson,
+          })
+          .from(schema.planVersions)
+          .where(inArray(schema.planVersions.id, legacyIds))
+      : [];
+    const legacySnapshotById = new Map(
+      legacySnapshots.map((row) => [row.id, row.snapshotJson]),
+    );
+
     return {
       planId,
       count: versions.length,
-      versions: versions.map(summarizePlanVersion),
+      versions: versions.map((version) =>
+        summarizePlanVersionRow({
+          ...version,
+          snapshotJson: legacySnapshotById.get(version.id) ?? null,
+        }),
+      ),
     };
   },
 });

package/corpus/templates/plan/actions/patch-visual-plan-source.ts

@@ -1,4 +1,5 @@
 import { defineAction } from "@agent-native/core";
+import { agentTouchDocument } from "@agent-native/core/collab";
 import { and, eq } from "drizzle-orm";
 import { z } from "zod";
 
@@ -43,7 +44,11 @@ export default defineAction({
     description:
       "Apply granular MDX source patches and persist the normalized visual plan.",
   },
-  run: async (args) => {
+  run: async (args, ctx) => {
+    // Only agent invocations (in-app tool loop / A2A → "tool"; external MCP →
+    // "mcp") light the AI presence flag.
+    const isAgentCaller =
+      ctx?.caller === "tool" || ctx?.caller === "mcp" || ctx?.caller === "a2a";
     await assertPlanEditor(args.planId);
     const bundle = await loadPlanBundle(args.planId);
     const versionAtLoad = bundle.plan.updatedAt;
@@ -107,6 +112,41 @@ export default defineAction({
       createdBy: "agent",
     });
 
+    // Surface AI presence + a lingering highlight on the patched block(s) via the
+    // plan-presence doc. Best-effort — never fail the save on presence.
+    if (isAgentCaller) {
+      try {
+        const patchIds = new Set<string>();
+        for (const patch of args.patches) {
+          if (patch.op === "replace-markdown-block")
+            patchIds.add(patch.blockId);
+          else if (patch.op === "update-component-prop") {
+            patchIds.add(patch.componentId);
+          } else if (patch.op === "update-wireframe-node") {
+            patchIds.add(patch.nodeId);
+          }
+        }
+        if (patchIds.size === 0) {
+          for (const block of nextContent.blocks) patchIds.add(block.id);
+        }
+        const blockIds = Array.from(patchIds).slice(0, 12);
+        agentTouchDocument(`plan:${args.planId}`, {
+          edit: {
+            descriptor: { kind: "paths", paths: blockIds },
+            label: `Patched ${args.patches.length} source block${
+              args.patches.length === 1 ? "" : "s"
+            }`,
+          },
+          metadata: { blockIds },
+        });
+      } catch (error) {
+        console.error(
+          "[patch-visual-plan-source] agent presence publish failed",
+          error,
+        );
+      }
+    }
+
     const updated = await loadPlanBundle(args.planId);
     const local = isLocalPlanRuntime()
       ? await writePlanLocalFiles({

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

@@ -6,13 +6,15 @@ import {
   isLocalPlanRuntime,
 } from "../server/lib/local-identity.js";
 import { promotePlanLocalFolder } from "../server/lib/local-plan-files.js";
+import {
+  localPlanKindSchema,
+  resolveLocalPlanKind,
+} from "../server/lib/local-plan-kind.js";
 import { exportPlanContentToMdxFolder } from "../server/plan-mdx.js";
 import { buildPlanHtml, nowIso } from "../server/plans.js";
 import type { PlanContent } from "../shared/plan-content.js";
 import type { PlanBundle, PlanKind } from "../shared/types.js";
 
-const localPlanKindSchema = z.enum(["plan", "recap"]);
-
 export default defineAction({
   description:
     "Copy a DB-free local Agent-Native Plan MDX folder into a repo-relative folder, using apps.plan.roots[0].path from agent-native.json when no targetPath is provided and falling back to plans/<slug>.",
@@ -137,26 +139,6 @@ export default defineAction({
   }),
 });
 
-function resolveLocalPlanKind(
-  explicit: "plan" | "recap" | undefined,
-  mdx: { "plan.mdx": string; ".plan-state.json"?: string },
-): "plan" | "recap" {
-  if (explicit) return explicit;
-  const frontmatterMatch = mdx["plan.mdx"].match(
-    /^---[\s\S]*?^kind:\s*["']?(plan|recap)["']?\s*$/m,
-  );
-  if (frontmatterMatch) return frontmatterMatch[1] as "plan" | "recap";
-  try {
-    const state = mdx[".plan-state.json"]
-      ? (JSON.parse(mdx[".plan-state.json"]) as { kind?: unknown })
-      : null;
-    if (state?.kind === "plan" || state?.kind === "recap") return state.kind;
-  } catch {
-    // Optional state file.
-  }
-  return "plan";
-}
-
 function countLocalPlanBlocks(blocks: PlanContent["blocks"]) {
   const counts: Record<string, number> = {};
   const visitBlocks = (items: PlanContent["blocks"]) => {