@agent-native/core 0.131.6 → 0.131.9

package/corpus/core/src/secrets/crypto.ts

@@ -13,10 +13,13 @@
  * The generic encryption key is derived from
  * `<APP_NAME>_SECRETS_ENCRYPTION_KEY` when set, then
  * `SECRETS_ENCRYPTION_KEY`, then `BETTER_AUTH_SECRET`. Workspace-shared vault
- * rows use a different precedence: `SECRETS_ENCRYPTION_KEY`, then material
- * derived from the workspace-wide `A2A_SECRET`, then the app-local auth/key
- * fallbacks retained for backward-compatible reads. This keeps sibling apps
- * on one key even when each app correctly has a different auth secret.
+ * rows use a different precedence: `WORKSPACE_SECRETS_ENCRYPTION_KEY`, then
+ * the legacy shared `SECRETS_ENCRYPTION_KEY`, then material derived from the
+ * workspace-wide `A2A_SECRET`, then the app-local auth/key fallbacks retained
+ * for backward-compatible reads. A previous workspace key can be supplied
+ * during rotation with `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS`. This keeps
+ * sibling apps on one stable key even when each app correctly has a different
+ * auth secret, and prevents A2A trust rotation from stranding vault data.
  *
  * In production we refuse to start without configured key material — a
  * CWD-derived fallback would be effectively static (e.g. `/var/task` on
@@ -95,6 +98,18 @@ function genericEncryptionKeyMaterial(): string | undefined {
   );
 }
 
+function workspaceSharedEncryptionKeyMaterial(): string | undefined {
+  if (typeof process === "undefined") return undefined;
+  return process.env.WORKSPACE_SECRETS_ENCRYPTION_KEY?.trim() || undefined;
+}
+
+function previousWorkspaceSharedEncryptionKeyMaterial(): string | undefined {
+  if (typeof process === "undefined") return undefined;
+  return (
+    process.env.WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS?.trim() || undefined
+  );
+}
+
 /**
  * Vault sharing follows configured A2A trust even on independently deployed
  * sibling apps that are not launched by the workspace wrapper. The wrapper's
@@ -116,14 +131,17 @@ function a2aSharedEncryptionKeyMaterial(): string | undefined {
  * Stable materials that may be used for workspace-shared vault rows, ordered
  * from current preference to legacy compatibility fallbacks.
  *
- * `BETTER_AUTH_SECRET` deliberately comes after the A2A-derived material:
- * sibling apps normally have different auth secrets but share A2A trust.
+ * `BETTER_AUTH_SECRET` deliberately comes after the workspace and A2A-derived
+ * materials: sibling apps normally have different auth secrets but share
+ * workspace trust.
  */
 function sharedEncryptionKeyMaterials(): string[] {
   if (typeof process === "undefined") return [];
   const candidates = [
+    workspaceSharedEncryptionKeyMaterial(),
     process.env.SECRETS_ENCRYPTION_KEY,
     a2aSharedEncryptionKeyMaterial(),
+    previousWorkspaceSharedEncryptionKeyMaterial(),
     process.env.BETTER_AUTH_SECRET,
     appScopedEncryptionKey(),
   ].filter((value): value is string => Boolean(value));
@@ -131,7 +149,14 @@ function sharedEncryptionKeyMaterials(): string[] {
 }
 
 function preferredSharedEncryptionKeyMaterial(): string | undefined {
-  return sharedEncryptionKeyMaterials()[0];
+  if (typeof process === "undefined") return undefined;
+  return (
+    workspaceSharedEncryptionKeyMaterial() ||
+    process.env.SECRETS_ENCRYPTION_KEY ||
+    a2aSharedEncryptionKeyMaterial() ||
+    process.env.BETTER_AUTH_SECRET ||
+    appScopedEncryptionKey()
+  );
 }
 
 function hashSecretEncryptionKey(material: string): Buffer {
@@ -187,20 +212,23 @@ export function getSecretEncryptionKey(): Buffer {
 /**
  * Derive the preferred workspace-shared key used by `app_secrets` rows.
  * Unlike generic column-level encryption, workspace vault data must decrypt
- * in sibling apps. An explicit `SECRETS_ENCRYPTION_KEY` wins; hosted
- * workspaces otherwise derive stable material from their shared `A2A_SECRET`
- * before considering app-local `BETTER_AUTH_SECRET` or app-scoped key
- * fallbacks. Reads try every configured legacy candidate and report when the
- * ciphertext should be refreshed under the preferred key.
+ * in sibling apps. An explicit `WORKSPACE_SECRETS_ENCRYPTION_KEY` wins without
+ * changing the key for app-local OAuth and credential ciphertext. The legacy
+ * shared `SECRETS_ENCRYPTION_KEY` remains supported; hosted workspaces
+ * otherwise derive material from their shared `A2A_SECRET` before considering
+ * app-local `BETTER_AUTH_SECRET` or app-scoped key fallbacks. Reads try every
+ * configured legacy/previous candidate and report when the ciphertext should
+ * be refreshed under the preferred key.
  */
 export function getSharedSecretEncryptionKey(): Buffer {
   return deriveSecretEncryptionKey(
     preferredSharedEncryptionKeyMaterial(),
     "[agent-native/secrets] Refusing to start in production without encryption key material for workspace secrets. " +
-      "Set SECRETS_ENCRYPTION_KEY, ensure a hosted workspace has A2A_SECRET, or set BETTER_AUTH_SECRET / an app-scoped " +
+      "Set WORKSPACE_SECRETS_ENCRYPTION_KEY (preferred), SECRETS_ENCRYPTION_KEY, ensure a hosted workspace has A2A_SECRET, " +
+      "or set BETTER_AUTH_SECRET / an app-scoped " +
       "*_SECRETS_ENCRYPTION_KEY compatibility fallback in the deploy environment.",
-    "[agent-native/secrets] SECRETS_ENCRYPTION_KEY not set — using app-scoped or machine-local fallback for workspace secrets. " +
-      "Set SECRETS_ENCRYPTION_KEY or rely on A2A_SECRET-derived material on hosted workspace deploys so sibling apps share vault rows.",
+    "[agent-native/secrets] Workspace encryption key not set — using app-scoped or machine-local fallback for workspace secrets. " +
+      "Set WORKSPACE_SECRETS_ENCRYPTION_KEY or rely on A2A_SECRET-derived material on hosted workspace deploys so sibling apps share vault rows.",
   );
 }
 
@@ -208,6 +236,7 @@ export function getSharedSecretEncryptionKey(): Buffer {
 export function hasSharedSecretEncryptionKeyMaterial(): boolean {
   if (typeof process === "undefined") return false;
   return Boolean(
+    workspaceSharedEncryptionKeyMaterial() ||
     process.env.SECRETS_ENCRYPTION_KEY ||
     a2aSharedEncryptionKeyMaterial() ||
     process.env.BETTER_AUTH_SECRET,

package/corpus/core/src/secrets/storage.ts

@@ -2,10 +2,12 @@
  * Storage layer for the framework secrets registry.
  *
  * Values are encrypted at rest with AES-256-GCM. The workspace-shared
- * encryption key is derived from `SECRETS_ENCRYPTION_KEY` (preferred) or the
- * workspace-wide `A2A_SECRET`. `BETTER_AUTH_SECRET` and app-scoped keys remain
- * read fallbacks for rows written before sibling apps converged on the shared
- * key. Successful fallback reads race-safely refresh the shared ciphertext.
+ * encryption key prefers `WORKSPACE_SECRETS_ENCRYPTION_KEY`, then the legacy
+ * combined `SECRETS_ENCRYPTION_KEY`, then the workspace-wide `A2A_SECRET`.
+ * A configured previous workspace key, `BETTER_AUTH_SECRET`, and app-scoped
+ * keys remain read fallbacks for rows written before sibling apps converged on
+ * the shared key. Successful fallback reads race-safely refresh the shared
+ * ciphertext.
  *
  * Secret values are NEVER logged and NEVER returned from any route handler.
  */

package/corpus/core/src/server/agent-chat/action-filters-a2a.ts

@@ -360,6 +360,8 @@ export const DELEGATED_AGENT_EXECUTION_CONTRACT = `
 <delegated-agent-contract>
 This request was delegated by another app. You are the specialist owner of the work.
 - Interpret the caller's natural-language objective using your own instructions, skills, data dictionary, credentials, and tools. Choose providers, schemas, queries, and joins here; never ask the caller to invent SQL or source-specific implementation details for you.
+- Finish the objective autonomously in this delegated turn whenever a safe, reasonable default exists. Do not bounce the work back with UI-navigation requests, implementation questions, or intermediate status. Ask for input only when authorization, missing credentials, or a consequential user choice truly blocks progress.
+- When evidence is incomplete, return the best grounded partial answer with explicit coverage gaps instead of refusing or asking the caller to choose your source, filter, dashboard, or workflow.
 - Minimize round trips. Filter, join, aggregate, paginate, stage, and reduce large datasets inside your own tools rather than returning raw records or transcripts.
 - Return a concise caller-ready result with the answer, source and coverage details, relevant counts or IDs, caveats/partial gaps, and exact artifact URLs. Do not return tool transcripts or large raw payloads.
 </delegated-agent-contract>`;

package/corpus/core/src/templates/default/.agents/skills/secrets/SKILL.md

@@ -227,15 +227,20 @@ Core routes plugin mounts these under `/_agent-native/secrets/` automatically:
   prefer `<APP_NAME>_SECRETS_ENCRYPTION_KEY` (for example,
   `ANALYTICS_SECRETS_ENCRYPTION_KEY`), then `SECRETS_ENCRYPTION_KEY`, then
   `BETTER_AUTH_SECRET`.
-- Workspace-shared `app_secrets` prefer `SECRETS_ENCRYPTION_KEY`, then a
-  purpose-derived key from `A2A_SECRET`. Better Auth and app-scoped keys remain
-  legacy read candidates; a successful legacy decrypt is compare-and-swap
-  migrated to the preferred shared key without changing the row timestamp.
-- Set the same stable `SECRETS_ENCRYPTION_KEY` in every app that reads a shared
-  vault. If the vault relies on `A2A_SECRET`, rotating A2A material also rotates
-  its encryption key. Before rotating A2A, add the stable vault key everywhere
-  and read/migrate every existing row while the old A2A material is still
-  available.
+- Workspace-shared `app_secrets` prefer
+  `WORKSPACE_SECRETS_ENCRYPTION_KEY`, then the legacy shared
+  `SECRETS_ENCRYPTION_KEY`, then a purpose-derived key from `A2A_SECRET`.
+  Better Auth and app-scoped keys remain legacy read candidates; a successful
+  legacy decrypt is compare-and-swap migrated to the preferred shared key
+  without changing the row timestamp.
+- Set the same stable `WORKSPACE_SECRETS_ENCRYPTION_KEY` in every app that
+  reads a shared vault. It is intentionally separate from app-local OAuth
+  encryption. If the vault still relies on `A2A_SECRET`, rotating A2A material
+  also rotates its encryption key. Add the stable vault key everywhere and
+  read/migrate existing rows before rotating A2A.
+- To rotate the dedicated workspace key itself, deploy the new value together
+  with `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS=<old value>`, let reads
+  migrate ciphertext, then remove the previous key after the migration window.
 - If no configured key material exists, development uses a machine-local
   fallback and logs a one-time warning. Production fails closed.
 

package/corpus/core/src/templates/headless/.agents/skills/secrets/SKILL.md

@@ -227,15 +227,20 @@ Core routes plugin mounts these under `/_agent-native/secrets/` automatically:
   prefer `<APP_NAME>_SECRETS_ENCRYPTION_KEY` (for example,
   `ANALYTICS_SECRETS_ENCRYPTION_KEY`), then `SECRETS_ENCRYPTION_KEY`, then
   `BETTER_AUTH_SECRET`.
-- Workspace-shared `app_secrets` prefer `SECRETS_ENCRYPTION_KEY`, then a
-  purpose-derived key from `A2A_SECRET`. Better Auth and app-scoped keys remain
-  legacy read candidates; a successful legacy decrypt is compare-and-swap
-  migrated to the preferred shared key without changing the row timestamp.
-- Set the same stable `SECRETS_ENCRYPTION_KEY` in every app that reads a shared
-  vault. If the vault relies on `A2A_SECRET`, rotating A2A material also rotates
-  its encryption key. Before rotating A2A, add the stable vault key everywhere
-  and read/migrate every existing row while the old A2A material is still
-  available.
+- Workspace-shared `app_secrets` prefer
+  `WORKSPACE_SECRETS_ENCRYPTION_KEY`, then the legacy shared
+  `SECRETS_ENCRYPTION_KEY`, then a purpose-derived key from `A2A_SECRET`.
+  Better Auth and app-scoped keys remain legacy read candidates; a successful
+  legacy decrypt is compare-and-swap migrated to the preferred shared key
+  without changing the row timestamp.
+- Set the same stable `WORKSPACE_SECRETS_ENCRYPTION_KEY` in every app that
+  reads a shared vault. It is intentionally separate from app-local OAuth
+  encryption. If the vault still relies on `A2A_SECRET`, rotating A2A material
+  also rotates its encryption key. Add the stable vault key everywhere and
+  read/migrate existing rows before rotating A2A.
+- To rotate the dedicated workspace key itself, deploy the new value together
+  with `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS=<old value>`, let reads
+  migrate ciphertext, then remove the previous key after the migration window.
 - If no configured key material exists, development uses a machine-local
   fallback and logs a one-time warning. Production fails closed.
 

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

@@ -227,15 +227,20 @@ Core routes plugin mounts these under `/_agent-native/secrets/` automatically:
   prefer `<APP_NAME>_SECRETS_ENCRYPTION_KEY` (for example,
   `ANALYTICS_SECRETS_ENCRYPTION_KEY`), then `SECRETS_ENCRYPTION_KEY`, then
   `BETTER_AUTH_SECRET`.
-- Workspace-shared `app_secrets` prefer `SECRETS_ENCRYPTION_KEY`, then a
-  purpose-derived key from `A2A_SECRET`. Better Auth and app-scoped keys remain
-  legacy read candidates; a successful legacy decrypt is compare-and-swap
-  migrated to the preferred shared key without changing the row timestamp.
-- Set the same stable `SECRETS_ENCRYPTION_KEY` in every app that reads a shared
-  vault. If the vault relies on `A2A_SECRET`, rotating A2A material also rotates
-  its encryption key. Before rotating A2A, add the stable vault key everywhere
-  and read/migrate every existing row while the old A2A material is still
-  available.
+- Workspace-shared `app_secrets` prefer
+  `WORKSPACE_SECRETS_ENCRYPTION_KEY`, then the legacy shared
+  `SECRETS_ENCRYPTION_KEY`, then a purpose-derived key from `A2A_SECRET`.
+  Better Auth and app-scoped keys remain legacy read candidates; a successful
+  legacy decrypt is compare-and-swap migrated to the preferred shared key
+  without changing the row timestamp.
+- Set the same stable `WORKSPACE_SECRETS_ENCRYPTION_KEY` in every app that
+  reads a shared vault. It is intentionally separate from app-local OAuth
+  encryption. If the vault still relies on `A2A_SECRET`, rotating A2A material
+  also rotates its encryption key. Add the stable vault key everywhere and
+  read/migrate existing rows before rotating A2A.
+- To rotate the dedicated workspace key itself, deploy the new value together
+  with `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS=<old value>`, let reads
+  migrate ciphertext, then remove the previous key after the migration window.
 - If no configured key material exists, development uses a machine-local
   fallback and logs a one-time warning. Production fails closed.
 

package/corpus/core/src/workspace-files/tool.ts

@@ -86,13 +86,16 @@ export function createWorkspaceFilesTool(): Record<string, ActionEntry> {
                 'MIME type for new files. Default: "text/plain". Use "application/json" for JSON, "text/markdown" for Markdown.',
             },
             offset: {
-              type: "number",
+              type: "integer",
+              minimum: 0,
               description:
-                "Character offset to start reading from (for paging large files). Default: 0.",
+                "Non-negative character offset to start reading from (for paging large files). Default: 0.",
             },
             maxChars: {
-              type: "number",
-              description: `Maximum characters to return when reading. Default: ${DEFAULT_READ_CHARS}. Max: ${MAX_READ_CHARS}.`,
+              type: "integer",
+              minimum: 1,
+              maximum: MAX_READ_CHARS,
+              description: `Positive maximum characters to return when reading. Default: ${DEFAULT_READ_CHARS}. Max: ${MAX_READ_CHARS}.`,
             },
             pattern: {
               type: "string",
@@ -168,16 +171,19 @@ export function createWorkspaceFilesTool(): Record<string, ActionEntry> {
               if (!path) return "Error: path is required for read.";
               const rawOffset = Number(args.offset);
               const offset =
-                Number.isFinite(rawOffset) && rawOffset > 0 ? rawOffset : 0;
+                Number.isFinite(rawOffset) && rawOffset > 0
+                  ? Math.floor(rawOffset)
+                  : 0;
               const rawMax = Number(args.maxChars);
               const maxChars =
                 Number.isFinite(rawMax) && rawMax > 0
-                  ? Math.min(rawMax, MAX_READ_CHARS)
+                  ? Math.min(Math.max(1, Math.floor(rawMax)), MAX_READ_CHARS)
                   : DEFAULT_READ_CHARS;
 
+              // The sentinel character distinguishes an exact page from a truncated one.
               const file = await readWorkspaceFile(scope, path, {
                 offset,
-                maxChars,
+                maxChars: maxChars + 1,
               });
               if (!file) {
                 return JSON.stringify({
@@ -186,19 +192,20 @@ export function createWorkspaceFilesTool(): Record<string, ActionEntry> {
                 });
               }
 
-              const truncated = file.content.length >= maxChars;
+              const truncated = file.content.length > maxChars;
+              const content = file.content.slice(0, maxChars);
               return JSON.stringify({
                 ok: true,
                 path: file.path,
                 contentType: file.contentType,
                 sizeBytes: file.sizeBytes,
                 updatedAt: file.updatedAt,
-                content: file.content,
+                content,
                 ...(truncated
                   ? {
                       truncated: true,
-                      nextOffset: offset + file.content.length,
-                      hint: `File has more content. Call again with offset: ${offset + file.content.length}`,
+                      nextOffset: offset + content.length,
+                      hint: `File has more content. Call again with offset: ${offset + content.length}`,
                     }
                   : {}),
               });

package/corpus/templates/analytics/AGENTS.md

@@ -48,6 +48,7 @@ change the numbers.
   sibling-invocable. Prefer natural-language delegation so this app retains its
   instructions, source selection, and tools. Shaped reads are stable contracts,
   not workarounds for delegation; this app still owns the query.
+- For open-ended delegated requests, choose a safe default and label partial.
 - Data integrity first. Never invent numbers, dimensions, filters, or source
   semantics; only present values you actually retrieved, and state uncertainty.
 - Every analytical answer carries audit context: source(s), time window,

package/corpus/templates/analytics/changelog/2026-07-30-delegated-analytics-questions-now-return-a-useful-current-me.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-30
+---
+
+Delegated analytics questions now return a useful current metric without transport hints derailing the answer

package/corpus/templates/analytics/server/lib/real-data-actions.ts

@@ -7,6 +7,7 @@ const INJECTED_CONTEXT_BLOCKS = [
   "available-skills",
   "available-agents",
   "available-jobs",
+  "a2a-caller-hint",
   "plan-mode-note",
   "non-analytics-retry",
   "response-guard",
@@ -233,6 +234,15 @@ export function stripInjectedAnalyticsGuardContext(text: string): string {
       "",
     );
   }
+  // Compatibility with callers deployed before A2A hints were wrapped in the
+  // structured block above. The legacy transport note includes words such as
+  // "full transcripts" and "create ... dashboard"; allowing those framework
+  // words into intent classification falsely triggered corpus and dashboard
+  // guards for ordinary delegated metric questions.
+  requestText = requestText.replace(
+    /\n*\[Note:\s*this request comes from another app via A2A\.[\s\S]*\]\s*$/i,
+    "",
+  );
   return requestText.trim();
 }
 

package/corpus/templates/clips/actions/generate-workflow.ts

@@ -25,6 +25,7 @@ import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
 import { withFullVideoAiInstructions } from "../shared/clips-ai-prefs.js";
+import { WorkflowKindSchema } from "../shared/workflow.js";
 import { readIncludeFullVideoInAi } from "./lib/clips-ai-prefs.js";
 
 const KIND_PROMPTS = {
@@ -64,7 +65,7 @@ export default defineAction({
     "Ask the agent to generate a structured workflow doc (pr/sop/ticket/email) from this recording's transcript (and the full video when Include full video is enabled). The agent writes the result to clips-workflow-<recordingId> in application_state.",
   schema: z.object({
     recordingId: z.string().describe("Recording ID"),
-    kind: z.enum(["pr", "sop", "ticket", "email"]).describe("Workflow kind"),
+    kind: WorkflowKindSchema.describe("Workflow kind"),
   }),
   run: async (args) => {
     await assertAccess("recording", args.recordingId, "viewer");
@@ -98,7 +99,7 @@ export default defineAction({
 
       const includeFullVideoInAi = await readIncludeFullVideoInAi();
 
-      const existing = await readAppState(stateKey).catch(() => null);
+      const existing = await readAppState(stateKey);
       if (existing?.status === "generating") {
         const requestedAt = Date.parse(String(existing.requestedAt ?? ""));
         const isRecent =
@@ -115,13 +116,14 @@ export default defineAction({
         }
       }
 
+      const requestedAt = new Date().toISOString();
       // Seed the output state with a "generating" placeholder so the UI can show
       // a loading state immediately.
       await writeAppState(stateKey, {
         kind: args.kind,
         status: "generating",
         recordingId: args.recordingId,
-        requestedAt: new Date().toISOString(),
+        requestedAt,
       } as any);
 
       const baseMessage =
@@ -136,7 +138,7 @@ export default defineAction({
         kind: "generate-workflow" as const,
         workflowKind: args.kind,
         recordingId: args.recordingId,
-        requestedAt: new Date().toISOString(),
+        requestedAt,
         recordingTitle: rec.title,
         recordingDescription: rec.description,
         transcriptStatus: transcript?.status ?? "pending",

package/corpus/templates/clips/actions/reconcile-workflow-generation.ts

@@ -0,0 +1,257 @@
+import { defineAction } from "@agent-native/core";
+import {
+  compareAndSetAppState,
+  compareAndSetManyAppState,
+  readAppState,
+} from "@agent-native/core/application-state";
+import { assertAccess } from "@agent-native/core/sharing";
+import { z } from "zod";
+
+import { WorkflowKindSchema } from "../shared/workflow.js";
+
+const WorkflowStateSchema = z
+  .object({
+    kind: WorkflowKindSchema.optional(),
+    status: z.string().optional(),
+    content: z.string().optional(),
+    recordingId: z.string().optional(),
+    requestedAt: z.string().optional(),
+    tabId: z.string().optional(),
+    claimedAt: z.string().optional(),
+  })
+  .passthrough();
+
+const WorkflowRequestSchema = z
+  .object({
+    requestedAt: z.string(),
+    deliveredAt: z.string().optional(),
+    deliveredTabId: z.string().optional(),
+  })
+  .passthrough();
+
+const CLAIM_LEASE_MS = 30_000;
+
+export default defineAction({
+  description:
+    "Track and reconcile the agent run responsible for a generated workflow.",
+  agentTool: false,
+  schema: z.object({
+    operation: z.enum([
+      "track",
+      "release",
+      "mark-delivered",
+      "consume",
+      "stop",
+    ]),
+    recordingId: z.string().min(1),
+    requestedAt: z.string().min(1),
+    tabId: z.string().min(1),
+  }),
+  run: async ({ operation, recordingId, requestedAt, tabId }) => {
+    await assertAccess("recording", recordingId, "viewer");
+
+    const requestKey = `clips-ai-request-${recordingId}`;
+    if (operation === "mark-delivered" || operation === "consume") {
+      const rawRequest = await readAppState(requestKey);
+      if (rawRequest === null) {
+        return operation === "consume"
+          ? { reconciled: false, consumed: true, reason: "missing" as const }
+          : { reconciled: false, delivered: true, reason: "missing" as const };
+      }
+      const parsedRequest = WorkflowRequestSchema.safeParse(rawRequest);
+      if (!parsedRequest.success) {
+        throw new Error(`Invalid workflow request state for ${recordingId}`);
+      }
+      if (parsedRequest.data.requestedAt !== requestedAt) {
+        return operation === "consume"
+          ? {
+              reconciled: false,
+              consumed: true,
+              reason: "newer-request" as const,
+            }
+          : {
+              reconciled: false,
+              delivered: true,
+              reason: "newer-request" as const,
+            };
+      }
+      if (operation === "mark-delivered") {
+        if (parsedRequest.data.deliveredTabId === tabId) {
+          return { reconciled: false, delivered: true };
+        }
+        if (parsedRequest.data.deliveredTabId) {
+          return {
+            reconciled: false,
+            delivered: false,
+            reason: "different-run" as const,
+          };
+        }
+
+        const stateKey = `clips-workflow-${recordingId}`;
+        const rawState = await readAppState(stateKey);
+        if (rawState === null) {
+          return { reconciled: false, delivered: false, reason: "missing" };
+        }
+        const parsedState = WorkflowStateSchema.safeParse(rawState);
+        if (!parsedState.success) {
+          throw new Error(
+            `Invalid generated workflow state for ${recordingId}`,
+          );
+        }
+        if (parsedState.data.status !== "generating") {
+          const consumed = await compareAndSetAppState(
+            requestKey,
+            rawRequest,
+            null,
+          );
+          return consumed
+            ? {
+                reconciled: false,
+                delivered: true,
+                consumed: true,
+                reason: "terminal",
+              }
+            : {
+                reconciled: false,
+                delivered: false,
+                consumed: false,
+                reason: "stale",
+              };
+        }
+        if (
+          parsedState.data.requestedAt !== requestedAt ||
+          parsedState.data.tabId !== tabId
+        ) {
+          return {
+            reconciled: false,
+            delivered: false,
+            reason: "different-run",
+          };
+        }
+
+        const deliveredAt = new Date().toISOString();
+        const delivered = await compareAndSetManyAppState([
+          {
+            key: stateKey,
+            expectedValue: rawState,
+            nextValue: { ...rawState, claimedAt: deliveredAt },
+          },
+          {
+            key: requestKey,
+            expectedValue: rawRequest,
+            nextValue: { ...rawRequest, deliveredAt, deliveredTabId: tabId },
+          },
+        ]);
+        return delivered
+          ? { reconciled: false, delivered: true }
+          : { reconciled: false, delivered: false, reason: "stale" as const };
+      }
+      if (parsedRequest.data.deliveredTabId !== tabId) {
+        return {
+          reconciled: false,
+          consumed: false,
+          reason: "not-delivered" as const,
+        };
+      }
+      const consumed = await compareAndSetAppState(
+        requestKey,
+        rawRequest,
+        null,
+      );
+      return consumed
+        ? { reconciled: false, consumed: true }
+        : { reconciled: false, consumed: false, reason: "stale" as const };
+    }
+
+    const stateKey = `clips-workflow-${recordingId}`;
+    const rawState = await readAppState(stateKey);
+    if (rawState === null) {
+      return { reconciled: false, reason: "missing" as const };
+    }
+
+    const parsedState = WorkflowStateSchema.safeParse(rawState);
+    if (!parsedState.success) {
+      throw new Error(`Invalid generated workflow state for ${recordingId}`);
+    }
+
+    const state = parsedState.data;
+    if (state.status !== "generating") {
+      return { reconciled: false, reason: "terminal" as const };
+    }
+    if (state.requestedAt !== requestedAt) {
+      return { reconciled: false, reason: "newer-request" as const };
+    }
+
+    if (operation === "track") {
+      if (state.tabId === tabId) {
+        return { reconciled: false, tracked: true };
+      }
+      if (state.tabId) {
+        const claimedAt = Date.parse(
+          state.claimedAt ?? state.requestedAt ?? "",
+        );
+        if (
+          !Number.isFinite(claimedAt) ||
+          Date.now() - claimedAt < CLAIM_LEASE_MS
+        ) {
+          return {
+            reconciled: false,
+            tracked: false,
+            reason: "claimed" as const,
+          };
+        }
+      }
+      const rawRequest = await readAppState(requestKey);
+      if (rawRequest === null) {
+        return { reconciled: false, reason: "request-missing" as const };
+      }
+      const parsedRequest = WorkflowRequestSchema.safeParse(rawRequest);
+      if (!parsedRequest.success) {
+        throw new Error(`Invalid workflow request state for ${recordingId}`);
+      }
+      if (parsedRequest.data.requestedAt !== requestedAt) {
+        return { reconciled: false, reason: "newer-request" as const };
+      }
+
+      const tracked = await compareAndSetAppState(stateKey, rawState, {
+        ...rawState,
+        tabId,
+        claimedAt: new Date().toISOString(),
+      });
+      return tracked
+        ? { reconciled: false, tracked: true }
+        : { reconciled: false, tracked: false, reason: "stale" as const };
+    }
+    if (state.tabId !== tabId) {
+      return operation === "release"
+        ? {
+            reconciled: false,
+            released: true,
+            reason: "different-run" as const,
+          }
+        : { reconciled: false, reason: "different-run" as const };
+    }
+    if (operation === "release") {
+      const untrackedState = { ...rawState };
+      delete untrackedState.tabId;
+      delete untrackedState.claimedAt;
+      const released = await compareAndSetAppState(
+        stateKey,
+        rawState,
+        untrackedState,
+      );
+      return released
+        ? { reconciled: false, released: true }
+        : { reconciled: false, released: false, reason: "stale" as const };
+    }
+
+    const reconciled = await compareAndSetAppState(stateKey, rawState, {
+      ...rawState,
+      status: "failed",
+      failedAt: new Date().toISOString(),
+    });
+    return reconciled
+      ? { reconciled: true }
+      : { reconciled: false, reason: "stale" as const };
+  },
+});