@agent-native/core 0.88.0 → 0.90.1

package/corpus/templates/mail/server/lib/google-auth.ts

@@ -27,6 +27,7 @@ import {
   gmailListLabels,
   gmailWatch,
   gmailStopWatch,
+  googleFetch,
   peopleGetProfile,
 } from "./google-api.js";
 import { resolveGoogleSenderIdentity } from "./sender-identity.js";
@@ -109,6 +110,20 @@ async function getValidAccessToken(
   tokens: GoogleTokens,
   owner?: string,
 ): Promise<string> {
+  if (!tokens.access_token && !tokens.refresh_token) {
+    // The stored record has no usable credentials at all — typically a row
+    // that failed to decrypt after a SECRETS_ENCRYPTION_KEY /
+    // BETTER_AUTH_SECRET rotation (core's parseStoredTokens returns `{}`
+    // instead of throwing). Unlike the missing-refresh-token path below, do
+    // NOT delete the row: a failed decrypt can also mean THIS process holds
+    // the wrong key (e.g. a dev server sharing a prod DB), and deleting
+    // would destroy tokens a correctly configured deployment can still
+    // decrypt. Throw so callers surface a reconnect instead of retrying.
+    throw new Error(
+      `No usable OAuth tokens for ${accountId} — please reconnect.`,
+    );
+  }
+
   // If token is not expired (with 5-minute buffer), return it directly
   if (
     tokens.expiry_date &&
@@ -464,8 +479,18 @@ export async function getAuthStatus(
       .displayName;
     let displayName =
       accountDisplayName ?? getAccountDisplayName(account.accountId);
+    let accessToken: string;
+    try {
+      accessToken = await getValidAccessToken(email, tokens);
+    } catch (err) {
+      console.warn(
+        `[mail] skipping unusable Google OAuth row for ${email}:`,
+        err instanceof Error ? err.message : err,
+      );
+      continue;
+    }
+
     try {
-      const accessToken = await getValidAccessToken(email, tokens);
       const identity = await resolveGoogleSenderIdentity({
         accessToken,
         email,
@@ -583,14 +608,20 @@ function pruneThreadCandidatePages(
   return Object.fromEntries(entries.slice(0, THREAD_CANDIDATE_PAGE_MAX));
 }
 
-async function readThreadCandidatePageStore(
-  ownerEmail: string,
-): Promise<Record<string, ThreadCandidatePageEntry>> {
+async function readThreadCandidatePageStore(ownerEmail: string): Promise<{
+  pages: Record<string, ThreadCandidatePageEntry>;
+  prunedCount: number;
+}> {
   const stored = (await getUserSetting(
     ownerEmail,
     THREAD_CANDIDATE_PAGE_SETTING,
   )) as ThreadCandidatePageStore | null;
-  return pruneThreadCandidatePages(stored?.pages ?? {});
+  const rawPages = stored?.pages ?? {};
+  const pages = pruneThreadCandidatePages(rawPages);
+  return {
+    pages,
+    prunedCount: Object.keys(rawPages).length - Object.keys(pages).length,
+  };
 }
 
 async function writeThreadCandidatePageStore(
@@ -606,10 +637,16 @@ async function getStoredThreadCandidatePage(
   ownerEmail: string,
   key: string,
 ): Promise<ThreadCandidatePageEntry | null> {
-  const pages = await readThreadCandidatePageStore(ownerEmail);
+  const { pages, prunedCount } = await readThreadCandidatePageStore(ownerEmail);
   const page = pages[key];
   if (!page) {
-    await writeThreadCandidatePageStore(ownerEmail, pages);
+    // Cache miss: only pay for the write-back if pruning actually removed
+    // stale entries. A plain miss (e.g. a synthetic token minted on another
+    // process, or a legitimately expired/evicted key) has nothing new to
+    // persist, so skip the SQL write and let this be a pure read.
+    if (prunedCount > 0) {
+      await writeThreadCandidatePageStore(ownerEmail, pages);
+    }
     return null;
   }
   page.updatedAt = Date.now();
@@ -622,7 +659,7 @@ async function deleteStoredThreadCandidatePage(
   ownerEmail: string,
   key: string,
 ): Promise<void> {
-  const pages = await readThreadCandidatePageStore(ownerEmail);
+  const { pages } = await readThreadCandidatePageStore(ownerEmail);
   if (pages[key]) {
     delete pages[key];
     await writeThreadCandidatePageStore(ownerEmail, pages);
@@ -652,7 +689,7 @@ async function storeThreadCandidatePage(
   ids: string[],
   nextPageToken: string | undefined,
 ): Promise<string> {
-  const pages = await readThreadCandidatePageStore(ownerEmail);
+  const { pages } = await readThreadCandidatePageStore(ownerEmail);
   const key = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
   pages[key] = {
     email,
@@ -1704,6 +1741,100 @@ export async function fetchGmailLabelMap(
   return map;
 }
 
+// Gmail's real messages.batchModify endpoint (distinct from the multipart
+// /batch/gmail/v1 endpoint used by gmailBatchGetMessages/Threads) takes up to
+// 1000 message ids and one label add/remove set in a single JSON POST. Used
+// by bulk archive/star/mark-read so selecting many rows costs one Gmail call
+// instead of one per message.
+const GMAIL_BATCH_MODIFY_MAX_IDS = 1000;
+
+async function gmailBatchModify(
+  accessToken: string,
+  ids: string[],
+  addLabelIds?: string[],
+  removeLabelIds?: string[],
+): Promise<void> {
+  if (ids.length === 0) return;
+  for (let i = 0; i < ids.length; i += GMAIL_BATCH_MODIFY_MAX_IDS) {
+    const chunk = ids.slice(i, i + GMAIL_BATCH_MODIFY_MAX_IDS);
+    await googleFetch(
+      "https://gmail.googleapis.com/gmail/v1/users/me/messages/batchModify",
+      accessToken,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ ids: chunk, addLabelIds, removeLabelIds }),
+      },
+    );
+  }
+}
+
+export interface BatchModifyTarget {
+  /** Gmail message id to modify. */
+  id: string;
+  /** Thread id, when known, so callers can invalidate the right thread cache. */
+  threadId?: string;
+  /** Account that owns this message; falls back to ownerEmail's primary account. */
+  accountEmail?: string;
+}
+
+export interface BatchModifyByAccountResult {
+  succeeded: string[];
+  failed: Array<{ id: string; error: string }>;
+}
+
+/**
+ * Apply the same label add/remove to many Gmail messages for one owner,
+ * grouped into one messages.batchModify call per connected account instead
+ * of one modify call per message. Falls back to per-account partial failure
+ * reporting so callers can surface which ids didn't make it (e.g. a token
+ * that failed to refresh for one secondary account).
+ */
+export async function gmailBatchModifyByAccount(
+  ownerEmail: string,
+  targets: BatchModifyTarget[],
+  addLabelIds: string[] | undefined,
+  removeLabelIds: string[] | undefined,
+): Promise<BatchModifyByAccountResult> {
+  const byAccount = new Map<string, BatchModifyTarget[]>();
+  for (const target of targets) {
+    const key = target.accountEmail || ownerEmail;
+    const list = byAccount.get(key);
+    if (list) list.push(target);
+    else byAccount.set(key, [target]);
+  }
+
+  const succeeded: string[] = [];
+  const failed: Array<{ id: string; error: string }> = [];
+
+  for (const [accountEmail, accountTargets] of byAccount) {
+    const client = await getClient(accountEmail);
+    if (!client) {
+      for (const t of accountTargets) {
+        failed.push({
+          id: t.id,
+          error: `Account ${accountEmail} not connected`,
+        });
+      }
+      continue;
+    }
+    try {
+      await gmailBatchModify(
+        client.accessToken,
+        accountTargets.map((t) => t.id),
+        addLabelIds,
+        removeLabelIds,
+      );
+      for (const t of accountTargets) succeeded.push(t.id);
+    } catch (err: any) {
+      const message = err?.message ?? "batchModify failed";
+      for (const t of accountTargets) failed.push({ id: t.id, error: message });
+    }
+  }
+
+  return { succeeded, failed };
+}
+
 /** Extract regular (non-inline) attachments from a Gmail message payload */
 function getAttachments(
   payload: any,

package/corpus/templates/mail/server/lib/jobs.ts

@@ -8,7 +8,7 @@ import {
 import { getUserSetting, putUserSetting } from "@agent-native/core/settings";
 import { markdownPreviewSnippet } from "@shared/markdown.js";
 import type { ComposeAttachment, EmailMessage } from "@shared/types.js";
-import { and, eq, inArray, lte } from "drizzle-orm";
+import { and, eq, inArray, isNull, lte, or } from "drizzle-orm";
 import { nanoid } from "nanoid";
 
 import { db, schema } from "../db/index.js";
@@ -266,15 +266,31 @@ export async function listPendingJobs(
   // couldn't initialize) the query throws — return an empty list instead
   // of bubbling a 500 to the inbox endpoint.
   try {
+    // Scope to this owner at the SQL level (idx_scheduled_jobs_owner_status_run_at
+    // covers this). Legacy rows written before the owner_email backfill only have
+    // account_email set (or neither), so keep matching those the same way the old
+    // in-memory filter did: owner_email match, or owner_email is null and
+    // account_email matches, or both are null (unattributed legacy row).
     const jobs = await db
       .select()
       .from(schema.scheduledJobs)
-      .where(inArray(schema.scheduledJobs.status, ["pending", "processing"]));
+      .where(
+        and(
+          inArray(schema.scheduledJobs.status, ["pending", "processing"]),
+          or(
+            eq(schema.scheduledJobs.ownerEmail, ownerEmail),
+            and(
+              isNull(schema.scheduledJobs.ownerEmail),
+              or(
+                eq(schema.scheduledJobs.accountEmail, ownerEmail),
+                isNull(schema.scheduledJobs.accountEmail),
+              ),
+            ),
+          ),
+        ),
+      );
 
-    return jobs.filter((job: any) => {
-      const jobOwner = job.ownerEmail || job.accountEmail;
-      return !jobOwner || jobOwner === ownerEmail;
-    }) as ScheduledJobRecord[];
+    return jobs as ScheduledJobRecord[];
   } catch (err) {
     console.warn(
       "[mail] listPendingJobs failed (table may not exist yet):",

package/corpus/templates/mail/server/lib/outgoing-email.ts

@@ -181,8 +181,17 @@ export async function resolveComposeAttachments(
   const resolved: ResolvedComposeAttachment[] = [];
   for (const raw of attachments) {
     const att = raw as Partial<ComposeAttachment>;
-    if (!att.filename || typeof att.filename !== "string") continue;
-    if (att.filename.includes("/") || att.filename.includes("..")) continue;
+    // Every other failure branch below throws and is surfaced to the user as
+    // "One or more attachments could not be read" by the send/save callers.
+    // A malformed entry must fail the same way instead of being silently
+    // dropped; otherwise the user believes the file was attached when the
+    // sent email has fewer attachments than they added.
+    if (!att.filename || typeof att.filename !== "string") {
+      throw new Error("Attachment is missing a filename and could not be read");
+    }
+    if (att.filename.includes("/") || att.filename.includes("..")) {
+      throw new Error(`Attachment filename is invalid: ${att.filename}`);
+    }
 
     if (att.source === "gmail" || att.gmailMessageId || att.gmailAttachmentId) {
       if (

package/corpus/templates/mail/server/lib/queued-drafts.ts

@@ -16,6 +16,8 @@ import { getDb, schema } from "../db/index.js";
 
 export type QueuedDraftStatus = "queued" | "in_review" | "sent" | "dismissed";
 
+const SEND_CLAIM_TTL_MS = 15 * 60 * 1000;
+
 export type QueueScope = "review" | "requested" | "all";
 export type QueueStatusFilter = QueuedDraftStatus | "active" | "all";
 
@@ -463,13 +465,152 @@ export async function openQueuedDraftInComposer(
   return { draft: updated, composeId };
 }
 
+export type QueuedDraftClaim =
+  | {
+      claimed: true;
+      ctx: QueueContext;
+      draft: QueuedEmailDraft;
+      claimId: string;
+      priorStatus: QueuedDraftStatus;
+    }
+  | { claimed: false; reason: "sent" | "sending" | "dismissed" };
+
+/**
+ * Atomically claims a queued draft in a private send-claim column while keeping
+ * the public status in one of its durable states ("queued" or "in_review").
+ * That lets only one caller proceed to actually send the underlying email
+ * without writing transient values into the constrained status column. Enforces
+ * the same
+ * owner-or-admin access check as requireQueuedDraft first, then uses a
+ * single conditional UPDATE + RETURNING so two concurrent callers can't both
+ * observe a sendable, unclaimed draft and both dispatch the real send.
+ */
+export async function claimQueuedDraftForSending(
+  id: string,
+): Promise<QueuedDraftClaim> {
+  const { ctx, draft: preClaimDraft } = await requireQueuedDraft(id, {
+    ownerOnly: true,
+  });
+  // Best portable witness of the pre-claim status: UPDATE ... RETURNING
+  // yields POST-update values on both Postgres and SQLite, so it can never
+  // be used to recover the prior status. The WHERE clause below guarantees
+  // this row was "queued" or "in_review" at claim time if the update
+  // affects it, so the pre-read status (when it's one of those two) is
+  // exactly that prior status; otherwise default to "queued".
+  const priorStatus: QueuedDraftStatus =
+    preClaimDraft.status === "queued" || preClaimDraft.status === "in_review"
+      ? preClaimDraft.status
+      : "queued";
+  const claimId = nanoid();
+  const claimedAt = Date.now();
+  const staleClaimBefore = claimedAt - SEND_CLAIM_TTL_MS;
+
+  const claimed = await getDb()
+    .update(schema.queuedEmailDrafts)
+    .set({
+      sendClaimId: claimId,
+      sendClaimedAt: claimedAt,
+      updatedAt: claimedAt,
+    })
+    .where(
+      and(
+        eq(schema.queuedEmailDrafts.id, id),
+        eq(schema.queuedEmailDrafts.orgId, ctx.orgId),
+        or(
+          eq(schema.queuedEmailDrafts.status, "queued"),
+          eq(schema.queuedEmailDrafts.status, "in_review"),
+        ),
+        sql`(${schema.queuedEmailDrafts.sendClaimId} IS NULL OR ${schema.queuedEmailDrafts.sendClaimedAt} < ${staleClaimBefore})`,
+      ),
+    )
+    .returning({ sendClaimId: schema.queuedEmailDrafts.sendClaimId });
+
+  if (claimed.length > 0) {
+    const draft = await getQueuedDraft(id, ctx);
+    if (!draft) throw new Error("Queued draft not found after claim.");
+    return { claimed: true, ctx, draft, claimId, priorStatus };
+  }
+
+  // Lost the race (or nothing to claim) — report the real current status so
+  // callers can distinguish "someone else is sending this right now" from
+  // "this was already sent" instead of silently re-sending or erroring.
+  const [current] = await getDb()
+    .select({
+      status: schema.queuedEmailDrafts.status,
+      sendClaimId: schema.queuedEmailDrafts.sendClaimId,
+    })
+    .from(schema.queuedEmailDrafts)
+    .where(
+      and(
+        eq(schema.queuedEmailDrafts.id, id),
+        eq(schema.queuedEmailDrafts.orgId, ctx.orgId),
+      ),
+    )
+    .limit(1);
+  if (
+    current?.sendClaimId &&
+    (current.status === "queued" || current.status === "in_review")
+  ) {
+    return { claimed: false, reason: "sending" };
+  }
+  if (current?.status === "sent") return { claimed: false, reason: "sent" };
+  return { claimed: false, reason: "dismissed" };
+}
+
+/**
+ * Releases a failed send back to its pre-claim status so the draft is
+ * retryable instead of stuck with an active send claim forever.
+ */
+export async function releaseQueuedDraftClaim(
+  id: string,
+  ctx: QueueContext,
+  claimId: string,
+  priorStatus: QueuedDraftStatus,
+): Promise<void> {
+  await getDb()
+    .update(schema.queuedEmailDrafts)
+    .set({
+      status: priorStatus,
+      sendClaimId: null,
+      sendClaimedAt: null,
+      updatedAt: Date.now(),
+    })
+    .where(
+      and(
+        eq(schema.queuedEmailDrafts.id, id),
+        eq(schema.queuedEmailDrafts.orgId, ctx.orgId),
+        eq(schema.queuedEmailDrafts.sendClaimId, claimId),
+      ),
+    );
+}
+
 export async function markQueuedDraftSent(
   id: string,
+  ctx: QueueContext,
+  claimId: string,
   sentMessageId?: string,
 ): Promise<QueuedEmailDraft> {
-  await requireQueuedDraft(id, { ownerOnly: true });
-  return updateQueuedDraft(id, {
+  const updates: Record<string, unknown> = {
     status: "sent",
-    sentMessageId,
-  });
+    sendClaimId: null,
+    sendClaimedAt: null,
+    sentAt: Date.now(),
+    updatedAt: Date.now(),
+  };
+  if (sentMessageId !== undefined) {
+    updates.sentMessageId = sentMessageId.trim() || null;
+  }
+  await getDb()
+    .update(schema.queuedEmailDrafts)
+    .set(updates)
+    .where(
+      and(
+        eq(schema.queuedEmailDrafts.id, id),
+        eq(schema.queuedEmailDrafts.orgId, ctx.orgId),
+        eq(schema.queuedEmailDrafts.sendClaimId, claimId),
+      ),
+    );
+  const updated = await getQueuedDraft(id, ctx);
+  if (!updated) throw new Error("Queued draft not found after send.");
+  return updated;
 }

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

@@ -159,6 +159,35 @@ const runMailMigrations = runMigrations(
 CREATE INDEX IF NOT EXISTS idx_contact_frequency_owner ON contact_frequency(owner_email);
 CREATE INDEX IF NOT EXISTS idx_automation_rules_owner ON automation_rules(owner_email)`,
     },
+    {
+      version: 15,
+      name: "snippets-table",
+      sql: `CREATE TABLE IF NOT EXISTS snippets (
+    id TEXT PRIMARY KEY,
+    owner_email TEXT NOT NULL,
+    name TEXT NOT NULL,
+    body TEXT NOT NULL,
+    created_at ${intType()} NOT NULL,
+    updated_at ${intType()} NOT NULL
+  );
+CREATE INDEX IF NOT EXISTS idx_snippets_owner_name ON snippets(owner_email, name)`,
+    },
+    {
+      // listPendingJobs (jobs.ts) scopes its WHERE clause to
+      // (status, owner_email) on every inbox/unread list load. The v14 index
+      // only covers (status, run_at), which doesn't serve the owner-scoped
+      // lookup, so add the composite index so that read stays indexed as the
+      // scheduled_jobs table grows across all users.
+      version: 16,
+      name: "scheduled-jobs-owner-status-run-at-idx",
+      sql: `CREATE INDEX IF NOT EXISTS idx_scheduled_jobs_owner_status_run_at ON scheduled_jobs(owner_email, status, run_at)`,
+    },
+    {
+      version: 17,
+      name: "queued-draft-send-claim",
+      sql: `ALTER TABLE queued_email_drafts ADD COLUMN IF NOT EXISTS send_claim_id TEXT;
+ALTER TABLE queued_email_drafts ADD COLUMN IF NOT EXISTS send_claimed_at ${intType()}`,
+    },
   ],
   { table: "mail_migrations" },
 );

package/corpus/templates/plan/.agents/skills/actions/SKILL.md

@@ -161,6 +161,18 @@ to find likely URLs, `web-request` or `provider-api-docs` with clean
 `webFetch()` when you need to grep, aggregate, or compare many pages before
 returning a small result.
 
+For LONG compute, `run-code` supports durable background executions: pass
+`background: true` and the code is enqueued to a `sandbox_executions` row and
+executed out-of-band with a generous budget (default 10 min), surviving the
+hosted agent run's ~40s soft timeout. The call returns
+`{ executionId, status: "queued" }` immediately with polling guidance; check
+progress with `run-code` `{ executionId }` (or the `get-code-execution` tool
+where registered) — results persist after completion. Use background for big
+cross-source joins, multi-page provider sweeps, and heavy analysis scripts;
+keep quick scripts in the default foreground mode. Agents should continue
+other work between polls, and on `failed`/`timed_out` split the computation or
+persist intermediate progress with `workspaceWrite` and re-run.
+
 ### The `http` Option
 
 Controls how the action is exposed as an HTTP endpoint:
@@ -205,6 +217,49 @@ run: async (args) => {
 }
 ```
 
+### Returning Images the Agent Can See (`_agentImages`)
+
+An action's return object may include the well-known optional field
+`_agentImages` to attach vision images (screenshots, chart previews, rendered
+designs) to the tool result. The agent literally sees them — enabling visual
+self-review loops — while the field itself is stripped from the JSON text the
+model reads.
+
+```ts
+run: async ({ dashboardId }) => {
+  const shot = await renderDashboardPng(dashboardId); // Buffer
+  return {
+    dashboardId,
+    panelCount: 6,
+    _agentImages: [
+      // Either a public https URL (preferred — the provider fetches it)…
+      { url: "https://cdn.example.com/previews/dash-1.png", label: "overview" },
+      // …or base64 without a data: prefix (mediaType required; a full
+      // data:image/png;base64,… URL in `data` is also accepted and parsed).
+      { data: shot.toString("base64"), mediaType: "image/png" },
+    ],
+  };
+},
+```
+
+Rules and limits:
+
+- Shape: `Array<{ url?: string; data?: string; mediaType?: string; label?: string }>`.
+  Each entry needs `url` (https only) **or** `data`. Supported media types:
+  `image/jpeg`, `image/png`, `image/gif`, `image/webp`.
+- Caps: max **4 images** per result; max **~2MB of base64** per image.
+  Over-cap or invalid entries never fail the call — they become text notes in
+  the result telling the model what was dropped and why.
+- Persistence: the run ledger stores only the string result plus compact
+  `[image: …]` notes (URLs verbatim; base64 as a byte-count placeholder) —
+  never the payload. Images are re-attached only for the live turn; replayed
+  history is text-only, so prefer stable `url` images the model can re-request.
+- Engine support: native Anthropic and vision-capable AI-SDK providers
+  (anthropic, openai, google, openrouter) receive real image blocks; other
+  paths (Builder gateway, non-vision providers) degrade to the text notes.
+- External MCP tools need no changes — standard MCP `image` content parts are
+  converted automatically under the same caps.
+
 ### Validating Return Values (`outputSchema`)
 
 `schema` validates inputs; `outputSchema` validates what the action **returns**. Pass any Standard Schema-compatible schema (Zod, Valibot, ArkType) and the framework validates the result _after_ `run()` resolves — input validated before `run`, output after.

package/corpus/templates/plan/app/components/editor/PlanDocumentEditor.tsx

@@ -14,6 +14,7 @@ import {
   type DragHandleDropContext,
   type DragHandleOptions,
   type RichMarkdownCollabUser,
+  type UseCollaborativeDocResult,
 } from "@agent-native/core/client";
 // `applyDocSurgically` is re-exported from the editor subpath barrel (the top
 // `@agent-native/core/client` barrel doesn't surface the surgical helpers).
@@ -807,6 +808,7 @@ export function PlanDocumentEditor({
   editable,
   onBlocksChange,
   onVisualQuestionsSubmit,
+  sharedCollabDoc,
 }: {
   content: PlanContent;
   contentUpdatedAt?: string | null;
@@ -816,6 +818,22 @@ export function PlanDocumentEditor({
   onBlocksChange: (blocks: PlanBlock[]) => void | Promise<void>;
   /** Forwarded to question-form and legacy visual-questions blocks. */
   onVisualQuestionsSubmit?: (summary: string) => void;
+  /**
+   * An already-open `plan:<planId>` collab connection (from `usePlanPresence`
+   * in the parent `PlanContentRenderer`), reused instead of opening a second
+   * independent `Y.Doc` + poll loop against the same doc id. `usePlanPresence`
+   * mounts unconditionally alongside this editor for the awareness-only
+   * presence bar, so without sharing, every plan view ran TWO parallel
+   * `useCollaborativeDoc` instances against the same `plan:<planId>` doc —
+   * double `/collab/<docId>/state` fetches, `/collab/<docId>/awareness`
+   * posts, and poll-fallback traffic for one logical document. When omitted
+   * (e.g. the surgical/repro specs that mount this component directly), the
+   * editor falls back to opening its own connection.
+   */
+  sharedCollabDoc?: Pick<
+    UseCollaborativeDocResult,
+    "ydoc" | "awareness" | "isSynced"
+  >;
 }) {
   const t = useT();
   const registryValue = useOptionalBlockRegistry();
@@ -973,12 +991,32 @@ export function PlanDocumentEditor({
   const SINGLE_DOC_COLLAB_ENABLED = true;
   const collabEnabled =
     SINGLE_DOC_COLLAB_ENABLED && editable && !!planId && !!docUser;
-  const docId = collabEnabled ? `plan:${planId}` : null;
-  const { ydoc, awareness } = useCollaborativeDoc({
-    docId,
+  // Prefer the connection `usePlanPresence` already opened on the same
+  // `plan:<planId>` doc for the header presence bar — falling back to owning
+  // our own connection only when the caller doesn't provide one (e.g. the
+  // surgical/repro specs that mount this component in isolation). Opening a
+  // second `useCollaborativeDoc` here as well as in `usePlanPresence` would
+  // double every poll/state/awareness request against the identical doc id.
+  const ownDocId = sharedCollabDoc
+    ? null
+    : collabEnabled
+      ? `plan:${planId}`
+      : null;
+  const ownCollabDoc = useCollaborativeDoc({
+    docId: ownDocId,
     requestSource: TAB_ID,
     user: docUser,
   });
+  // Only borrow the shared connection while collab is actually enabled for
+  // this editor (real editability + a known plan + a signed-in collab user) —
+  // otherwise fall through to `ownCollabDoc`, which is already all-null
+  // because `ownDocId` is null in that case.
+  const {
+    ydoc,
+    awareness,
+    isSynced: collabSyncedRaw,
+  } = collabEnabled && sharedCollabDoc ? sharedCollabDoc : ownCollabDoc;
+  const collabSynced = collabEnabled ? collabSyncedRaw : true;
 
   const getDragTransferData = useMemo<DragHandleOptions["getDragTransferData"]>(
     () =>
@@ -1466,6 +1504,7 @@ export function PlanDocumentEditor({
           extraExtensions={extraExtensions}
           slashItems={slashItems}
           ydoc={ydoc}
+          collabSynced={collabSynced}
           awareness={awareness}
           user={collabUser}
           // Non-collab: PM history off so the app-level undo stack (which alone

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

@@ -5,15 +5,16 @@ import {
   useT,
 } from "@agent-native/core/client";
 import { HeaderActionsProvider } from "@agent-native/toolkit/app-shell";
+import { IconMenu2 } from "@tabler/icons-react";
+import { useState, useEffect } from "react";
+import { useLocation } from "react-router";
+
 import {
   Sheet,
   SheetContent,
   SheetDescription,
   SheetTitle,
-} from "@agent-native/toolkit/ui/sheet";
-import { IconMenu2 } from "@tabler/icons-react";
-import { useState, useEffect } from "react";
-import { useLocation } from "react-router";
+} from "@/components/ui/sheet";
 
 import { Header } from "./Header";
 import { Sidebar } from "./Sidebar";