@agent-native/core 0.119.4 → 0.119.6

package/corpus/core/src/templates/workspace-core/.agents/skills/integration-webhooks/SKILL.md

@@ -16,10 +16,10 @@ metadata:
 
 Integration webhooks (Slack, Telegram, WhatsApp, email, Google Docs, etc.) must
 **enqueue work to SQL and return 200 immediately**, then process the work in a
-**separate fresh function execution** kicked off by a self-fired HTTP POST. A
-recurring retry job sweeps anything that gets stuck. This pattern works on every
-serverless host (Netlify, Vercel, Cloudflare Workers, Fly, Render, Node) without
-relying on platform-specific background-execution features.
+**separate fresh function execution** kicked off by a self-fired HTTP POST. SQL
+is always the source of truth. Long-lived hosts use an in-process retry loop as
+a best-effort safety net; serverless deployments must use an external durable
+sweep when recovery cannot depend on a process staying alive.
 
 Do not run agent loops inside the webhook handler itself. Do not rely on
 fire-and-forget `Promise`s after `return`ing from a serverless handler — they get
@@ -38,8 +38,9 @@ Past attempts that don't work cross-host:
   freeze the execution context the moment the response goes out. The promise
   is silently killed, the user gets no reply, and there's no error in the
   logs.
-- **Netlify Background Functions** — Netlify-only, requires a `-background`
-  filename suffix, breaks on every other host.
+- **A platform background function as the queue** — host-specific execution is
+  useful as a delivery mechanism, but it cannot replace the SQL row or atomic
+  claim shared by every host.
 - **Cloudflare `event.waitUntil()`** — CF Workers only, not portable.
 - **Vercel Fluid / `after()`** — Vercel-only, gated behind specific runtimes.
 - **A long-lived in-process queue** — fine on a single Node box, but on
@@ -62,8 +63,9 @@ and a recurring job is the safety net.
                             2. INSERT INTO integration_pending_tasks
                                  (status='pending', payload=...)
                                                                   │
-                            3. fetch(POST /integrations/_process-task)
-                                 — fire-and-forget, NO await on body
+                            3. dispatch POST /integrations/process-task
+                                 — portable self-fire by default
+                                 — acknowledged background handoff when enabled
                                                                   │
                             4. return 200 to platform ◄───────────┘
 
@@ -79,7 +81,7 @@ and a recurring job is the safety net.
 
 
                           ┌──────────────────────────────────────────────┐
-                          │  Recurring job (every 60s) — safety net      │
+                          │  Recovery sweep (every 60s) — safety net    │
                           │  Re-fires processor for tasks stuck in       │
                           │  'pending' or 'processing' beyond timeout.   │
                           │  Caps retries at 3 then marks 'failed'.      │
@@ -98,6 +100,7 @@ loop.
 | `packages/core/src/integrations/webhook-handler.ts`                     | Verifies signature, parses, enqueues task, fires processor             |
 | `packages/core/src/integrations/pending-tasks-store.ts`                 | SQL queue: `insertPendingTask`, `claimPendingTask`, `markTaskCompleted`, `markTaskFailed` |
 | `packages/core/src/integrations/pending-tasks-retry-job.ts`             | Recurring retry sweep (`startPendingTasksRetryJob`, `retryStuckPendingTasks`) |
+| `packages/core/src/integrations/integration-durable-dispatch.ts`        | Default-off acknowledged dispatch, scoped rollout, and outcome recording |
 | `packages/core/src/integrations/types.ts`                               | `PlatformAdapter`, `IncomingMessage`, `OutgoingMessage`                |
 | `packages/core/src/integrations/adapters/{slack,telegram,whatsapp,email,google-docs}.ts` | One adapter per platform                                               |
 
@@ -108,7 +111,8 @@ All under `/_agent-native/integrations/`:
 | Method | Path                       | Purpose                                                       |
 | ------ | -------------------------- | ------------------------------------------------------------- |
 | POST   | `/:platform/webhook`       | Platform pings this. Verifies, enqueues, returns 200 quickly. |
-| POST   | `/_process-task`           | Self-webhook target. Claims a task and runs the agent loop.   |
+| POST   | `/process-task`            | Processor target. Claims a task and runs the agent loop.      |
+| POST   | `/retry-stuck-tasks`       | Signed, bounded recovery sweep for durable schedulers.        |
 | GET    | `/status`                  | All integrations status (settings UI).                        |
 | GET    | `/:platform/status`        | One platform's status.                                        |
 | POST   | `/:platform/enable`        | Enable an integration.                                        |
@@ -129,6 +133,10 @@ CREATE TABLE IF NOT EXISTS integration_pending_tasks (
   org_id             TEXT,
   status             TEXT    NOT NULL,   -- pending | processing | completed | failed
   attempts           INTEGER NOT NULL DEFAULT 0,
+  dispatch_attempts  INTEGER NOT NULL DEFAULT 0,
+  last_dispatch_at   INTEGER,
+  last_dispatch_outcome TEXT,
+  dispatch_scope     TEXT,             -- persisted channel scope for recovery
   error_message      TEXT,
   created_at         INTEGER NOT NULL,
   updated_at         INTEGER NOT NULL,
@@ -136,6 +144,8 @@ CREATE TABLE IF NOT EXISTS integration_pending_tasks (
 );
 CREATE INDEX IF NOT EXISTS idx_pending_tasks_status_created
   ON integration_pending_tasks(status, created_at);
+CREATE INDEX IF NOT EXISTS idx_pending_tasks_dispatch_scope
+  ON integration_pending_tasks(platform, dispatch_scope);
 ```
 
 The store layer creates this lazily on first use via `ensureTable()` and uses
@@ -143,10 +153,38 @@ The store layer creates this lazily on first use via `ensureTable()` and uses
 
 `claimPendingTask` is the critical concurrency primitive: it atomically flips
 `pending` → `processing` and increments `attempts`, returning `null` if another
-worker beat us to it. Both the initial fire-and-forget call and the retry job
+worker beat us to it. Both the initial dispatch and every recovery sweep
 funnel through the same processor endpoint, and `claimPendingTask` is what
 prevents the same task from being processed twice.
 
+### Netlify durable recovery
+
+The portable self-dispatch remains the default. To emit and use Netlify's
+acknowledged background worker plus a one-minute scheduled recovery function,
+set `AGENT_INTEGRATION_DURABLE_DISPATCH=true` at build and runtime. A production
+rollout can be narrowed with the comma-separated
+`AGENT_INTEGRATION_DURABLE_DISPATCH_SCOPES` allowlist. Supported values are
+`<platform>:*`, `<platform>:<external-thread-id>`, and, for adapters that expose
+one, `<platform>:<channel-id>` (for example `slack:C123`).
+Channel-scoped handoffs persist that scope separately from the provider thread
+identity so a later bounded recovery sweep applies the same allowlist decision.
+
+Workspace deploys emit this pair only for the Dispatch control-plane app, which
+owns workspace messaging integrations. Standalone templates emit their own
+pair when the same flag is enabled.
+
+The background handoff waits only for Netlify's enqueue acknowledgement, not
+for the agent loop. A failed or non-2xx acknowledgement falls back to the
+portable processor. The scheduled function calls the HMAC-authenticated,
+bounded `/retry-stuck-tasks` route; its atomic compare-and-set update prevents
+overlapping sweeps from dispatching the same stale row twice.
+Rows acknowledged by the 15-minute background worker use a 16-minute stale
+cutoff, while portable synchronous dispatches retain the shorter serverless
+cutoff. Apply that lease predicate before `LIMIT` so healthy long runs cannot
+hide recoverable work. The background processor writes its lease marker in the
+same atomic update that claims the row; best-effort dispatch telemetry is not
+trusted for replay safety.
+
 ## Adding a New Platform Adapter
 
 1. **Implement `PlatformAdapter`** in `packages/core/src/integrations/adapters/<platform>.ts`:
@@ -245,9 +283,10 @@ so a normal long-running reply is safe.
 
 ## Cross-Platform Considerations
 
-- **No platform-specific background APIs.** No `waitUntil`, no
-  `-background.ts` filenames, no Vercel `after()`. The pattern works
-  identically on every host because it only uses `fetch()` and SQL.
+- **Portable correctness, optional host acceleration.** Every host uses SQL,
+  HMAC-authenticated processor routes, and atomic claims. A host-specific
+  background function or scheduler may provide a more reliable wake-up, but
+  disabling it must preserve the portable path.
 - **No assumed runtime.** The processor endpoint is a normal H3 handler under
   `/_agent-native/`. It runs wherever the rest of the framework runs.
 - **No persistent in-memory state.** The dedup map in the webhook handler is
@@ -262,11 +301,12 @@ so a normal long-running reply is safe.
 
 ## Why Fire-and-Forget on Serverless Is Unreliable
 
-Even though the webhook handler does `fetch(processorUrl, ...)` without
-awaiting the response body, that initial dispatch is **not** guaranteed to
-complete before the function freezes. In practice it usually does — the TCP
-connect + write happens quickly — but the recurring retry job is the safety
-net for the cases where:
+The portable webhook path gives the outbound processor request a short head
+start but does not wait for the response body, so that initial dispatch is
+**not** guaranteed to complete before the function freezes. On a long-lived
+host, the in-process retry loop is a best-effort safety net. On Netlify with
+durable dispatch enabled, the initial handoff is acknowledged and the external
+scheduled function supplies the recovery wake-up for cases where:
 
 - The serverless platform froze the handler before the outbound `fetch`
   flushed its bytes.
@@ -278,8 +318,9 @@ Tasks stuck in `pending` for >90s or `processing` for >5min get re-fired up to
 3 times. After 3 attempts they're marked `failed` permanently so we stop
 spamming the processor.
 
-**Never assume the initial fire-and-forget succeeded.** Always rely on the
-queue + retry job for at-least-once delivery.
+**Never assume the initial dispatch succeeded.** Rely on the SQL queue, atomic
+claim, and a recovery mechanism whose lifetime is independent of the original
+request. An in-process timer alone is not that mechanism on serverless.
 
 ## Debugging Checklist
 
@@ -292,7 +333,7 @@ queue + retry job for at-least-once delivery.
 4. **Status?** `pending` means the processor never picked it up — check that
    `_process-task` is reachable from the box itself (the self-fetch must work
    over the public URL). `processing` for over 5 minutes means the processor
-   died mid-run — the retry job will pick it up.
+   died mid-run — a live recovery sweep will pick it up.
 5. **Failed?** Check `error_message` and `attempts`. After 3 attempts the row
    is parked at `failed` and won't be retried.
 6. **Reply not delivered?** The processor likely succeeded but

package/corpus/templates/dispatch/changelog/2026-07-21-recover-stalled-slack-agent-work.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-21
+---
+
+Slack agent requests recover automatically when the first background handoff is interrupted.

package/corpus/templates/slides/actions/patch-deck.ts

@@ -26,6 +26,7 @@ import { z } from "zod";
 import { normalizeSlidePadding } from "../app/lib/normalize-slide-padding.js";
 import { getDb, schema } from "../server/db/index.js";
 import { notifyClients } from "../server/handlers/decks.js";
+import { ASPECT_RATIO_VALUES } from "../shared/aspect-ratios.js";
 
 // ---------------------------------------------------------------------------
 // Per-deck write lock — same pattern as add-slide.ts so all client and agent
@@ -122,7 +123,7 @@ const PatchDeckFieldsOp = z.object({
       tweaks: z
         .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
         .optional(),
-      aspectRatio: z.string().optional(),
+      aspectRatio: z.enum(ASPECT_RATIO_VALUES).optional(),
       shareToken: z.string().optional(),
       visibility: z.enum(["private", "org", "public"]).optional(),
     })

package/corpus/templates/slides/changelog/2026-07-23-opening-or-refining-a-deck-no-longer-crashes-with-a-blank-er.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-23
+---
+
+Opening or refining a deck no longer crashes with a blank error screen when the deck has an unrecognized aspect ratio

package/corpus/templates/slides/shared/aspect-ratios.ts

@@ -30,5 +30,8 @@ export const ASPECT_RATIO_VALUES = ["16:9", "1:1", "9:16", "4:5"] as const;
 export const DEFAULT_ASPECT_RATIO: AspectRatio = "16:9";
 
 export function getAspectRatioDims(ratio: AspectRatio | undefined | null) {
-  return ASPECT_RATIOS[ratio ?? DEFAULT_ASPECT_RATIO];
+  if (ratio && Object.prototype.hasOwnProperty.call(ASPECT_RATIOS, ratio)) {
+    return ASPECT_RATIOS[ratio];
+  }
+  return ASPECT_RATIOS[DEFAULT_ASPECT_RATIO];
 }

package/corpus/templates/tasks/.oxfmtrc.json

@@ -0,0 +1,8 @@
+{
+  "tabWidth": 2,
+  "useTabs": false,
+  "printWidth": 80,
+  "trailingComma": "all",
+  "proseWrap": "preserve",
+  "sortImports": true
+}

package/corpus/templates/tasks/AGENTS.md

@@ -7,6 +7,11 @@ inventory existing public kits and installed package seams. Use
 `customizing-agent-native` for the configure → compose → eject → propose seam
 ladder.
 
+## Authoritative References
+
+- [Feature docs](./docs/features/README.md) define product behavior and feature status.
+- [Action definitions](./actions/) contain the canonical tool descriptions, input schemas, and implementations.
+
 ## Core Rules
 
 - Never hardcode API keys, tokens, webhook URLs, signing secrets, private Builder/internal data, customer data, or credential-looking literals. Use secrets/OAuth/runtime configuration and obvious placeholders in examples.
@@ -16,34 +21,38 @@ ladder.
 - Keep the action surface small: task CRUD actions plus `reorder-tasks`, `view-screen`, and `navigate`.
 - Do not use `db-query` for normal task operations.
 - Call `view-screen` first when the user's visible task context matters (especially on `/tasks`).
+- Tasks are private to each user. Preserve `ownerEmail` scoping unless intentionally implementing sharing.
+- The task detail panel exposes `tasks.task-detail.bottom` as an `ExtensionSlot` with `slotContext` containing `taskId`, `title`, `done`, and `fieldValues`.
 
 ## Actions
 
-| Action                       | Method | Purpose                                                                                      |
-| ---------------------------- | ------ | -------------------------------------------------------------------------------------------- |
-| `list-tasks`                 | GET    | List current user's tasks; `includeDone` and `includeFields` default to false                |
-| `create-task`                | POST   | Create a task with `title`                                                                   |
-| `update-task`                | POST   | Patch `title`, `done`, and/or `fieldValues` by `taskId`                                      |
-| `delete-task`                | POST   | Delete a task by `taskId` (confirm with user first)                                          |
-| `bulk-update-tasks`          | POST   | Patch `title` and/or `done` on multiple tasks by id                                          |
-| `bulk-delete-tasks`          | POST   | Delete multiple tasks by id (confirm with user first)                                        |
-| `reorder-tasks`              | POST   | Reorder visible tasks by id list top-to-bottom                                               |
-| `list-inbox-items`           | GET    | List current user's inbox items                                                              |
-| `create-inbox-item`          | POST   | Create a not-ready inbox item with `title` (default chat capture)                            |
-| `update-inbox-item`          | POST   | Patch inbox item `title` by `inboxItemId`                                                    |
-| `delete-inbox-item`          | POST   | Delete an inbox item (confirm with user first)                                               |
-| `mark-inbox-item-ready`      | POST   | Promote inbox item to an incomplete task                                                     |
-| `reorder-inbox-items`        | POST   | Reorder inbox items by id list top-to-bottom                                                 |
-| `list-custom-fields`         | GET    | List custom field definitions                                                                |
-| `create-custom-field`        | POST   | Create a custom field definition with `title`, `type`, and optional `config`                 |
-| `update-custom-field`        | POST   | Patch a field definition `title` and/or type-compatible `config`; type is immutable          |
-| `delete-custom-field`        | POST   | Delete a field definition and its values on every task (confirm with user first)             |
-| `reorder-custom-fields`      | POST   | Reorder custom field definitions by id list top-to-bottom                                    |
-| `list-visible-task-fields`   | GET    | List custom field ids shown on task cards for the current user                               |
-| `update-visible-task-fields` | POST   | Replace which custom fields appear on task cards (max 3)                                     |
-| `view-screen`                | —      | Read navigation, UI bulk selection, visible tasks, and inbox snapshot                        |
-| `navigate`                   | —      | Move UI to a view: `tasks`, `inbox`, `fields`, `extensions`, `team` (`home`/`ask` → `tasks`) |
-| `render-task-list-inline`    | —      | Render an interactive task-list widget inline in chat without leaving the current view       |
+| Action                        | Method | Purpose                                                                                      |
+| ----------------------------- | ------ | -------------------------------------------------------------------------------------------- |
+| `list-tasks`                  | GET    | List current user's tasks; `includeDone` and `includeFields` default to false                |
+| `create-task`                 | POST   | Create a task with `title`                                                                   |
+| `update-task`                 | POST   | Patch `title`, `done`, and/or `fieldValues` by `taskId`                                      |
+| `delete-task`                 | POST   | Delete a task by `taskId` (confirm with user first)                                          |
+| `bulk-update-tasks`           | POST   | Patch `title` and/or `done` on multiple tasks by id                                          |
+| `bulk-delete-tasks`           | POST   | Delete multiple tasks by id (confirm with user first)                                        |
+| `reorder-tasks`               | POST   | Reorder visible tasks by id list top-to-bottom                                               |
+| `list-inbox-items`            | GET    | List current user's inbox items                                                              |
+| `create-inbox-item`           | POST   | Create a not-ready inbox item with `title` (default chat capture)                            |
+| `update-inbox-item`           | POST   | Patch inbox item `title` by `inboxItemId`                                                    |
+| `delete-inbox-item`           | POST   | Delete an inbox item (confirm with user first)                                               |
+| `bulk-delete-inbox-items`     | POST   | Delete multiple inbox items by id (confirm with user first)                                  |
+| `mark-inbox-item-ready`       | POST   | Promote inbox item to an incomplete task                                                     |
+| `bulk-mark-inbox-items-ready` | POST   | Promote multiple inbox items to incomplete tasks by id                                       |
+| `reorder-inbox-items`         | POST   | Reorder inbox items by id list top-to-bottom                                                 |
+| `list-custom-fields`          | GET    | List custom field definitions                                                                |
+| `create-custom-field`         | POST   | Create a custom field definition with `title`, `type`, and optional `config`                 |
+| `update-custom-field`         | POST   | Patch a field definition `title` and/or type-compatible `config`; type is immutable          |
+| `delete-custom-field`         | POST   | Delete a field definition and its values on every task (confirm with user first)             |
+| `reorder-custom-fields`       | POST   | Reorder custom field definitions by id list top-to-bottom                                    |
+| `list-visible-task-fields`    | GET    | List custom field ids shown on task cards for the current user                               |
+| `update-visible-task-fields`  | POST   | Replace which custom fields appear on task cards (max 3)                                     |
+| `view-screen`                 | —      | Read navigation, UI bulk selection, visible tasks, and inbox snapshot                        |
+| `navigate`                    | —      | Move UI to a view: `tasks`, `inbox`, `fields`, `extensions`, `team` (`home`/`ask` → `tasks`) |
+| `render-task-list-inline`     | —      | Render an interactive task-list widget inline in chat without leaving the current view       |
 
 ## Store Functions And Transactions
 
@@ -80,22 +89,6 @@ export type DbHandle = Pick<
 
 ## Commit Message Conventions
 
-- Never include `Made-with: Cursor` in commit messages. Remove it if it appears
-  in a generated message.
-- Use one of these prefixes:
-  - `feature: ...` or `feature(PROJECT): ...`
-  - `fix: ...` or `fix(PROJECT): ...`
-  - `refactor: ...` or `refactor(PROJECT): ...`
-  - `technical: ...` or `technical(PROJECT): ...`
-  - `chore: ...` or `chore(PROJECT): ...`
-- `PROJECT` is optional. If provided, it must be one of `generator` or `web`.
-- Before creating any commit, always:
-  - ask for confirmation,
-  - show the proposed commit message first,
-  - commit only after explicit user approval.
-
-## Commit Message Conventions
-
 - Never include `Made-with: Cursor` in commit messages. Remove it if it appears
   in a generated message.
 - Use one of these prefixes:

package/corpus/templates/tasks/README.md

@@ -4,13 +4,20 @@ Task-list-first agent-native app. Default home is `/tasks`; chat handles capture
 
 ## TODO
 
-- [ ] **i18n** — Add `app/i18n/` catalogs (`en-US` + locale mirrors) and migrate UI copy from raw literals to `useT()`. Remove tasks strings from `scripts/i18n-raw-literal-baseline.txt` once migrated.
-- [ ] **Delete dialog wiring** — `TaskList` and `InboxList` duplicate single/bulk delete dialog state (`pendingDeleteId`, `bulkDeleteOpen`, confirm handlers, toast on bulk success). Extract a shared hook or composer helper (e.g. `useDeleteDialogs`) that owns pending id, open state, and confirm wiring while composers pass entity labels and delete mutations.
-- [ ] Extract shared action schema helpers (e.g. `taskId` field, title patch) once the action surface grows beyond MVP.
-- [ ] Add route-level `ErrorBoundary` and `Suspense` around task list loading (align with other agent-native templates).
+- [ ] **Runtime action discovery filtering** — Update `@agent-native/core` development action discovery to exclude colocated `*.test.*`, `*.spec.*`, and helper-only modules so they are never exposed as agent tools or HTTP action routes.
+- [ ] **Optional event-triggered automations** — If Tasks needs workflows such as “when a task is completed, notify another system,” register stable domain events in `server/plugins/agent-chat.ts` and emit owner-scoped payloads from the successful write paths. Add event discovery, payload-validation, transition, and failure-isolation tests before exposing the events as a public automation contract.
 - [ ] **`view-screen` agent snapshot** — Revisit `AGENT_TASKS_LIST_CAP` in `actions/view-screen.ts`: it caps the agent tool payload (token budget), not the UI list. Confirm whether `list` / `selectedItem` / `inListSnapshot` correctly represent what the user sees, tune or document the cap, and align with UI limits if needed. Also review Zod parsing of `navigation` / app-state selection keys for strictness vs backward compatibility.
-- [ ] **Selection context** — Revisit prop drilling through `TaskList` → header/bar/rows once the composer stabilizes; a narrow context for `{ state, actions }` would trim wiring but must not blur the `dnd/` ↔ `selection/` boundary.
 - [ ] **`TaskList` optimistic state** — Refactor manual `allTasks` buffer in `app/components/tasks/TaskList.tsx` to TanStack Query `onMutate` once exit animations and reorder rollback can share one cache strategy.
 - [ ] **Exit-animation list reconcile** — Move exit-animation reconcile / `exitingIdsRef` out of `app/components/tasks/TaskList.tsx` into a neutral list helper (e.g. `use-ordered-tasks-with-exit-animation.ts`). That logic keeps completed rows visible during CSS exit when Show all is off; it is not DnD. `TaskList` should pass an ordered list into generic `SortableList`.
-- Shared `ListRowPreview` (`app/components/shared/dnd/ListRowPreview.tsx`) still duplicates row chrome; render the live row in the overlay when `SortableList` can mount previews safely (see TODO in that file).
 - [ ] **`move-tasks` / relative reorder (try on a separate branch)** — Today DnD persistence is FE-heavy: `SortableList` runs `reorderMovingItems` (`app/components/dnd/reorder-moving-items.ts`) to compute the **full visible id list**, then `TaskList` calls `reorder-tasks` with every id top-to-bottom. The BE already persists order via `server/tasks/store.ts` `reorderTasks` — no separate `bulkReorder` needed, but the **drop → order** translation is brittle (multi-select before/after/top/bottom edge cases). **Proposal:** add a relative move action, e.g. `move-tasks` with `{ taskIds, beforeId? | afterId?, includeDone? }` (or extend `reorder-tasks` with a relative mode). BE applies the block move, validates visible list / ownership, rewrites `sortOrder`, returns updated tasks. Keep **absolute** full-list `taskIds[]` as an escape hatch for agent/import flows. **FE after refactor:** dnd-kit still handles overlay/collision/optimistic UI, but on drop only derives `{ selected ids, anchor id, before | after }` from `over` + drag direction — delete most of `computeBlockInsertIndex`. **Prefer `beforeId`/`afterId` over `toIndex`** — matches user/agent language (“put these after task Z”) and avoids index ambiguity with `includeDone` / hidden rows. **Touch:** new `actions/move-tasks.ts`, `server/tasks/store.ts`, `use-tasks.ts`, `TaskList.tsx` / `InboxList.tsx`, agent prompt in `server/plugins/agent-chat.ts`, unit tests on store + thin FE mapping tests; keep `reorder-tasks` until callers migrate.
+- [ ] **List pagination + virtualization (when volume warrants)** — `listStoredItems` is unbounded and rows render unvirtualized. Fine at personal-list volumes; if lists grow, adopt mail's pattern (`useInfiniteQuery` with page size 25 + `@tanstack/react-virtual` in `EmailList.tsx`). Parked by the 2026-07-17 sibling-parity review as a latent scaling concern, not an active bug.
+
+## Optional improvements
+
+Reviewed against sibling templates (starter, mail, content, calendar, plan): none of these has an established cross-template convention to adopt, so they are optional polish rather than alignment work.
+
+- [ ] **Delete dialog wiring** — `TaskList` and `InboxList` duplicate single/bulk delete dialog state (`pendingDeleteId`, `bulkDeleteOpen`, confirm handlers, toast on bulk success); a shared `useDeleteDialogs` hook could own that wiring. Siblings: no template has a shared delete-confirm hook — each inlines shadcn `AlertDialog` per call site (calendar's `DeleteEventDialog` is feature-specific). tasks' shared `DeleteItemDialog`/`BulkDeleteDialog` components already lead here; this would be a net-new pattern, not adoption.
+- [ ] **Shared action schema helpers** — Extract shared helpers (e.g. `taskId` field, title patch) if duplication grows. Siblings: no template has generic schema helpers — every action inlines `z.object({...})` in `defineAction`; the only shared primitives are feature-specific (clips' `booleanParam`, tasks' own `boolean-query-param`). Wait for a concrete third duplication before abstracting.
+- [ ] **Custom `ErrorBoundary` copy** — tasks already exports the root-level `ErrorBoundary` (re-export from `@agent-native/core/client`), which is full boundary parity: no template has per-route boundaries, and `Suspense` only wraps `lazy()` components — data loads through react-query, not loaders. The only optional delta: mail and content (2 of 4) replace the re-export with custom copy plus `ErrorReportActions` (send feedback / open issue).
+- [ ] **Task attachments** — no `@agent-native/core/file-upload` usage anywhere, though `.gitignore` already carries the standard `data/uploads/` entry. mail/content/plan use the framework file-upload module. A product decision, not an alignment gap.
+- [ ] **Selection context** — Revisit prop drilling through `TaskList` → header/bar/rows; a narrow `{ state, actions }` context would trim wiring but must not blur the `dnd/` ↔ `selection/` boundary. Siblings: no template uses a React context for list multi-select — the universal pattern is a `useState<Set<string>>` hook plus prop drilling (mail's `EmailList` passes `selectedIds` down as props), and tasks' `use-list-selection.ts` is already the most generalized version of it.

package/corpus/templates/tasks/actions/bulk-delete-inbox-items.ts

@@ -4,16 +4,18 @@ import { z } from "zod";
 import { deleteInboxItems, requireUserEmail } from "../server/inbox/store.js";
 import { BULK_ID_LIMIT } from "../shared/bulk-limits.js";
 
+export const bulkDeleteInboxItemsSchema = z.object({
+  inboxItemIds: z
+    .array(z.string())
+    .min(1)
+    .max(BULK_ID_LIMIT)
+    .describe("Inbox item ids to delete"),
+});
+
 export default defineAction({
   description:
-    "Delete multiple inbox items permanently. Ask the user to confirm before calling.",
-  schema: z.object({
-    inboxItemIds: z
-      .array(z.string())
-      .min(1)
-      .max(BULK_ID_LIMIT)
-      .describe("Inbox item ids to delete"),
-  }),
+    "Delete multiple inbox items permanently. Use delete-inbox-item for one item. Ask the user to confirm before calling.",
+  schema: bulkDeleteInboxItemsSchema,
   run: async (args, ctx) => {
     const ownerEmail = requireUserEmail(ctx?.userEmail);
     return deleteInboxItems({

package/corpus/templates/tasks/actions/bulk-delete-tasks.ts

@@ -4,16 +4,18 @@ import { z } from "zod";
 import { deleteTasks, requireUserEmail } from "../server/tasks/store.js";
 import { BULK_ID_LIMIT } from "../shared/bulk-limits.js";
 
+export const bulkDeleteTasksSchema = z.object({
+  taskIds: z
+    .array(z.string())
+    .min(1)
+    .max(BULK_ID_LIMIT)
+    .describe("Task ids to delete"),
+});
+
 export default defineAction({
   description:
-    "Delete multiple tasks permanently. Ask the user to confirm before calling.",
-  schema: z.object({
-    taskIds: z
-      .array(z.string())
-      .min(1)
-      .max(BULK_ID_LIMIT)
-      .describe("Task ids to delete"),
-  }),
+    "Delete multiple tasks permanently. Use delete-task for one task. Ask the user to confirm before calling.",
+  schema: bulkDeleteTasksSchema,
   run: async (args, ctx) => {
     const ownerEmail = requireUserEmail(ctx?.userEmail);
     return deleteTasks({ ownerEmail, ids: args.taskIds });

package/corpus/templates/tasks/actions/bulk-mark-inbox-items-ready.ts

@@ -9,7 +9,7 @@ import { BULK_ID_LIMIT } from "../shared/bulk-limits.js";
 
 export default defineAction({
   description:
-    "Promote multiple inbox items to incomplete tasks in one atomic batch.",
+    "Promote multiple inbox items to incomplete tasks in one atomic batch, preserving their ids. Use mark-inbox-item-ready for one item.",
   schema: z.object({
     inboxItemIds: z
       .array(z.string())

package/corpus/templates/tasks/actions/bulk-update-tasks.ts

@@ -5,18 +5,20 @@ import { UserInputError } from "../server/errors.js";
 import { requireUserEmail, updateTasks } from "../server/tasks/store.js";
 import { BULK_ID_LIMIT } from "../shared/bulk-limits.js";
 
+export const bulkUpdateTasksSchema = z.object({
+  taskIds: z
+    .array(z.string())
+    .min(1)
+    .max(BULK_ID_LIMIT)
+    .describe("Task ids to update"),
+  title: z.string().min(1).optional().describe("New title for every task"),
+  done: z.boolean().optional().describe("Completion state for every task"),
+});
+
 export default defineAction({
   description:
-    "Update multiple tasks with the same title and/or completion patch.",
-  schema: z.object({
-    taskIds: z
-      .array(z.string())
-      .min(1)
-      .max(BULK_ID_LIMIT)
-      .describe("Task ids to update"),
-    title: z.string().min(1).optional().describe("New title for every task"),
-    done: z.boolean().optional().describe("Completion state for every task"),
-  }),
+    "Apply the same title and/or completion state to multiple tasks. Use update-task for one task or custom field values.",
+  schema: bulkUpdateTasksSchema,
   run: async (args, ctx) => {
     const ownerEmail = requireUserEmail(ctx?.userEmail);
     if (args.title === undefined && args.done === undefined) {

package/corpus/templates/tasks/actions/create-inbox-item.ts

@@ -5,11 +5,14 @@ import { z } from "zod";
 import { createInboxItem, requireUserEmail } from "../server/inbox/store.js";
 import type { InboxItem } from "../server/inbox/store.js";
 
+export const createInboxItemSchema = z.object({
+  title: z.string().min(1).describe("Inbox item title"),
+});
+
 export default defineAction({
-  description: "Create a not-ready inbox item with a title.",
-  schema: z.object({
-    title: z.string().min(1).describe("Inbox item title"),
-  }),
+  description:
+    "Create a not-ready inbox item for later triage. Use create-task when the user explicitly wants it added directly to the task list.",
+  schema: createInboxItemSchema,
   run: async (args, ctx) => {
     const ownerEmail = requireUserEmail(ctx?.userEmail);
     const item = await createInboxItem({ ownerEmail, title: args.title });

package/corpus/templates/tasks/actions/create-task.ts

@@ -9,7 +9,8 @@ import {
 } from "../server/tasks/store.js";
 
 export default defineAction({
-  description: "Create a new task with a title.",
+  description:
+    "Create an incomplete task directly on the task list. Use create-inbox-item for a quick capture to triage later.",
   schema: z.object({
     title: z.string().min(1).describe("Task title"),
   }),

package/corpus/templates/tasks/actions/delete-inbox-item.ts

@@ -3,12 +3,14 @@ import { z } from "zod";
 
 import { deleteInboxItem, requireUserEmail } from "../server/inbox/store.js";
 
+export const deleteInboxItemSchema = z.object({
+  inboxItemId: z.string().describe("Inbox item id"),
+});
+
 export default defineAction({
   description:
-    "Delete an inbox item permanently. Ask the user to confirm before calling.",
-  schema: z.object({
-    inboxItemId: z.string().describe("Inbox item id"),
-  }),
+    "Delete one inbox item permanently. Use bulk-delete-inbox-items for multiple items. Ask the user to confirm before calling.",
+  schema: deleteInboxItemSchema,
   run: async (args, ctx) => {
     const ownerEmail = requireUserEmail(ctx?.userEmail);
     await deleteInboxItem({ ownerEmail, id: args.inboxItemId });

package/corpus/templates/tasks/actions/delete-task.ts

@@ -5,7 +5,7 @@ import { deleteTask, requireUserEmail } from "../server/tasks/store.js";
 
 export default defineAction({
   description:
-    "Delete a task permanently. Ask the user to confirm before calling.",
+    "Delete one task permanently. Use bulk-delete-tasks for multiple tasks. Ask the user to confirm before calling.",
   schema: z.object({
     taskId: z.string().describe("Task id"),
   }),

package/corpus/templates/tasks/actions/list-inbox-items.ts

@@ -3,9 +3,11 @@ import { z } from "zod";
 
 import { listInboxItems, requireUserEmail } from "../server/inbox/store.js";
 
+export const listInboxItemsSchema = z.object({});
+
 export default defineAction({
-  description: "List inbox items for the current user (not-ready capture).",
-  schema: z.object({}),
+  description: "List not-ready inbox items awaiting triage.",
+  schema: listInboxItemsSchema,
   http: { method: "GET" },
   readOnly: true,
   run: async (_args, ctx) => {

package/corpus/templates/tasks/actions/list-visible-task-fields.ts

@@ -4,10 +4,12 @@ import { z } from "zod";
 import { requireUserEmail } from "../server/custom-fields/store.js";
 import { getTaskCardFieldIds } from "../server/user-config/store.js";
 
+export const listVisibleTaskFieldsSchema = z.object({});
+
 export default defineAction({
   description:
     "List custom field ids currently shown on task cards for the current user.",
-  schema: z.object({}),
+  schema: listVisibleTaskFieldsSchema,
   http: { method: "GET" },
   readOnly: true,
   run: async (_args, ctx) => {

package/corpus/templates/tasks/actions/mark-inbox-item-ready.ts

@@ -5,12 +5,14 @@ import { z } from "zod";
 import { markInboxItemReady, requireUserEmail } from "../server/inbox/store.js";
 import type { Task } from "../server/tasks/store.js";
 
+export const markInboxItemReadySchema = z.object({
+  inboxItemId: z.string().describe("Inbox item id"),
+});
+
 export default defineAction({
   description:
-    "Mark an inbox item ready: promotes the inbox item to an incomplete task (same id).",
-  schema: z.object({
-    inboxItemId: z.string().describe("Inbox item id"),
-  }),
+    "Promote one inbox item to an incomplete task, preserving its id. Use bulk-mark-inbox-items-ready for multiple items.",
+  schema: markInboxItemReadySchema,
   run: async (args, ctx) => {
     const ownerEmail = requireUserEmail(ctx?.userEmail);
     return markInboxItemReady({ ownerEmail, id: args.inboxItemId });

package/corpus/templates/tasks/actions/navigate.ts

@@ -21,22 +21,24 @@ import { optionalBooleanQueryParam } from "./lib/boolean-query-param.js";
 
 const viewSchema = z.enum(NAV_VIEW_INPUTS);
 
+export const navigateSchema = z.object({
+  view: viewSchema.describe(
+    "View name to navigate to; home and ask are aliases for tasks",
+  ),
+  taskId: z.string().optional().describe("Selected task id on /tasks"),
+  fieldId: z
+    .string()
+    .optional()
+    .describe("Selected custom field id on /fields"),
+  includeDone: optionalBooleanQueryParam().describe(
+    "When true, show completed tasks on /tasks",
+  ),
+});
+
 export default defineAction({
   description:
-    "Navigate the UI to a specific view. Writes a navigate command to application state which the UI reads and auto-deletes.",
-  schema: z.object({
-    view: viewSchema.describe(
-      "View name to navigate to; home and ask are aliases for tasks",
-    ),
-    taskId: z.string().optional().describe("Selected task id on /tasks"),
-    fieldId: z
-      .string()
-      .optional()
-      .describe("Selected custom field id on /fields"),
-    includeDone: optionalBooleanQueryParam().describe(
-      "When true, show completed tasks on /tasks",
-    ),
-  }),
+    "Navigate the Tasks UI to a view, optionally selecting a task or custom field.",
+  schema: navigateSchema,
   http: false,
   run: async (args) => {
     const view = resolveNavView(args.view);