@agent-native/core 0.127.3 → 0.128.1

package/corpus/templates/brain/.agents/skills/sharing/SKILL.md

@@ -34,6 +34,8 @@ Visibility is coarse. Explicit share grants are fine-grained (per user or per or
 - **`editor`** — read + write.
 - **`admin`** — read + write + manage shares. Does NOT replace the single `owner_email` on the resource.
 
+There are three role systems and they never imply one another. A share role answers "what may this person do to **one row**". An org role (`org_members.role`) answers "what may this person do to the **team**". An app role (`defineAppRoles`, see the `authentication` skill) answers "what may this person do inside **one app**". A share `admin` is not an app admin and neither is an org admin.
+
 ### Anonymous public URLs stay separate
 
 Form "publish" slugs, booking-link slugs, any feature that exposes a URL to unauthenticated users — these are a different axis and are NOT controlled by the sharing system. Keep them alongside it.
@@ -137,6 +139,8 @@ export default defineAction({
 
 For delete actions use `"admin"` (or fold in `"owner"` to require the real owner).
 
+`authorize` is a different axis, not an alternative: it gates whether the caller may run the operation at all, while `assertAccess` scopes which row they may touch. A write action restricted to some teammates needs both — `authorize: appAccess.requireAny(...)` on the action, `assertAccess` inside `run`.
+
 ## Create actions must set owner
 
 When inserting a new row, fill `ownerEmail` and `orgId` from the request context:

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

@@ -305,6 +305,38 @@ export default defineAction({
 
 On success the validated value is returned, so coercion/defaults on `outputSchema` apply. Omit `outputSchema` and behavior is byte-for-byte unchanged (no wrapping).
 
+### Authorization (`authorize`)
+
+`authorize` decides whether the caller may run the action at all. It wraps
+`run`, so it holds at **all six dispatch sites** — agent tool, HTTP, frontend
+hook, MCP, A2A, CLI — unlike `needsApproval`, which is honoured only in the
+agent loop. Use `authorize` for "not everyone may do this"; use `needsApproval`
+to ask a human to bless one call a permitted caller is already allowed to make.
+
+```ts
+import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
+
+export default defineAction({
+  description: "Archive a client roster.",
+  schema: z.object({ id: z.string() }),
+  authorize: coachAccess.requireAny("coach-admin"),
+  run: async (args) => {
+    /* ... */
+  },
+});
+```
+
+The wrappers compose as `validate input -> authorize -> run -> validate output
+-> audit`: the gate sits inside input validation, so a guard reading `args` gets
+the parsed, coerced value, and auditing is outermost, so denials are recorded.
+
+A guard that throws denies with its own message; returning `false` denies
+generically; anything else (including `undefined`) allows. A guarded action
+needs a user identity, so an unattended CLI/cron caller with no user email is
+denied. `authorize` gates the operation; `accessFilter` / `assertAccess` still
+scope which rows a permitted caller may touch. See the `authentication` skill
+for `defineAppRoles` and the `sharing` skill for row scoping.
+
 ### Human-in-the-Loop Approval (`needsApproval`)
 
 For high-consequence, outward-facing, hard-to-undo actions (sending an email, charging a card, deleting an account), set `needsApproval` so the agent **cannot** run the action without a human approving the specific call:

package/corpus/templates/calendar/.agents/skills/security/SKILL.md

@@ -159,6 +159,35 @@ whole site. Data scoping lives in actions and API routes; the client gates
 private UI after the shell loads. See the `authentication` skill and
 `guard:ssr-cache-shell` / `ssr-handler.spec.ts`.
 
+**Authorization beyond "is there a session" — `authorize`.** The auth guard only
+proves *someone* is signed in. To restrict an operation to some teammates, set
+`authorize` on the `defineAction`. It wraps `run`, so it applies at every
+dispatch site (agent tool, HTTP, frontend, MCP, A2A, CLI) — unlike
+`needsApproval`, which is honoured only in the agent loop.
+
+```ts
+import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
+
+export default defineAction({
+  description: "Archive a client roster.",
+  schema: z.object({ id: z.string() }),
+  authorize: coachAccess.requireAny("coach-admin"),
+  run: async (args) => {
+    /* ... */
+  },
+});
+```
+
+A guard that throws denies with its own message; returning `false` denies
+generically; anything else (including `undefined`) allows. Guarded actions need
+a user identity — an unattended CLI/cron caller with no user email is denied.
+
+`authorize` is **not** a substitute for `accessFilter` / `assertAccess`. It
+decides whether this caller may perform the operation at all; `accessFilter` /
+`assertAccess` scope which rows a permitted caller may see or touch. A
+restricted write action needs both. See the `authentication` skill for
+`defineAppRoles` and the `actions` skill for the full surface.
+
 ## Human-in-the-Loop Approval for High-Consequence Actions
 
 For a small set of outward-facing, hard-to-undo operations — sending an email, charging a card, deleting an account, posting publicly — auth and access control are necessary but not sufficient: you also do not want the **agent** to perform them autonomously. Set `needsApproval` on the `defineAction` so the agent cannot run the action without a human approving the specific call.
@@ -274,6 +303,8 @@ Run `pnpm action db-check-scoping` to verify. Use `--require-org` for multi-org
 - [ ] New env vars in `.env` only, not committed
 - [ ] New user-data tables have `owner_email` column
 - [ ] Custom routes call `getSession` and reject unauthenticated requests
+- [ ] Actions only some teammates may run set `authorize` (in addition to any
+      `accessFilter` / `assertAccess` row scoping)
 
 ## Related Skills
 

package/corpus/templates/calendar/.agents/skills/sharing/SKILL.md

@@ -34,6 +34,8 @@ Visibility is coarse. Explicit share grants are fine-grained (per user or per or
 - **`editor`** — read + write.
 - **`admin`** — read + write + manage shares. Does NOT replace the single `owner_email` on the resource.
 
+There are three role systems and they never imply one another. A share role answers "what may this person do to **one row**". An org role (`org_members.role`) answers "what may this person do to the **team**". An app role (`defineAppRoles`, see the `authentication` skill) answers "what may this person do inside **one app**". A share `admin` is not an app admin and neither is an org admin.
+
 ### Anonymous public URLs stay separate
 
 Form "publish" slugs, booking-link slugs, any feature that exposes a URL to unauthenticated users — these are a different axis and are NOT controlled by the sharing system. Keep them alongside it.
@@ -137,6 +139,8 @@ export default defineAction({
 
 For delete actions use `"admin"` (or fold in `"owner"` to require the real owner).
 
+`authorize` is a different axis, not an alternative: it gates whether the caller may run the operation at all, while `assertAccess` scopes which row they may touch. A write action restricted to some teammates needs both — `authorize: appAccess.requireAny(...)` on the action, `assertAccess` inside `run`.
+
 ## Create actions must set owner
 
 When inserting a new row, fill `ownerEmail` and `orgId` from the request context:

package/corpus/templates/calendar/_gitignore

@@ -8,8 +8,10 @@ npm-debug.log*
 pnpm-debug.log*
 
 node_modules
+build/
 dist
 dist-ssr
+.output/
 *.local
 
 # Editor directories and files

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

@@ -305,6 +305,38 @@ export default defineAction({
 
 On success the validated value is returned, so coercion/defaults on `outputSchema` apply. Omit `outputSchema` and behavior is byte-for-byte unchanged (no wrapping).
 
+### Authorization (`authorize`)
+
+`authorize` decides whether the caller may run the action at all. It wraps
+`run`, so it holds at **all six dispatch sites** — agent tool, HTTP, frontend
+hook, MCP, A2A, CLI — unlike `needsApproval`, which is honoured only in the
+agent loop. Use `authorize` for "not everyone may do this"; use `needsApproval`
+to ask a human to bless one call a permitted caller is already allowed to make.
+
+```ts
+import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
+
+export default defineAction({
+  description: "Archive a client roster.",
+  schema: z.object({ id: z.string() }),
+  authorize: coachAccess.requireAny("coach-admin"),
+  run: async (args) => {
+    /* ... */
+  },
+});
+```
+
+The wrappers compose as `validate input -> authorize -> run -> validate output
+-> audit`: the gate sits inside input validation, so a guard reading `args` gets
+the parsed, coerced value, and auditing is outermost, so denials are recorded.
+
+A guard that throws denies with its own message; returning `false` denies
+generically; anything else (including `undefined`) allows. A guarded action
+needs a user identity, so an unattended CLI/cron caller with no user email is
+denied. `authorize` gates the operation; `accessFilter` / `assertAccess` still
+scope which rows a permitted caller may touch. See the `authentication` skill
+for `defineAppRoles` and the `sharing` skill for row scoping.
+
 ### Human-in-the-Loop Approval (`needsApproval`)
 
 For high-consequence, outward-facing, hard-to-undo actions (sending an email, charging a card, deleting an account), set `needsApproval` so the agent **cannot** run the action without a human approving the specific call:

package/corpus/templates/chat/.agents/skills/adding-a-feature/SKILL.md

@@ -179,8 +179,15 @@ If the feature stores **user-authored resources** (documents, dashboards, forms,
 
 TL;DR: spread `ownableColumns()` into the resource table, pair it with `createSharesTable(...)`, call `registerShareableResource(...)`, wrap list/read queries with `accessFilter`, guard writes with `assertAccess`, and drop `<ShareButton>` in the resource header. The `share-resource`, `unshare-resource`, `list-resource-shares`, and `set-resource-visibility` actions are auto-mounted framework-wide.
 
+## One more area — who inside the app may do it
+
+If the feature is one **only some teammates should be able to perform inside this app** (an admin-only import, a settings reset), that is a per-app role — not a new organization, and not a share grant. See the `authentication` skill.
+
+TL;DR: declare the vocabulary once with `defineAppRoles({ appId, roles, defaultRole })`, guard the action with `authorize: appAccess.requireAny("...")`, and render the picker with `<TeamPage appRoles={descriptor} />`. `defaultRole` is display only — it never satisfies a guard — and `authorize` gates the operation while `accessFilter` / `assertAccess` still scope the rows.
+
 ## Related Skills
 
+- **authentication** — Per-app member roles (`defineAppRoles`) when only some teammates may use a feature
 - **sharing** — How to make a new resource ownable (private by default, share with users/orgs/public)
 - **context-awareness** — How to expose UI state to the agent (area 4 in detail)
 - **actions** — How to create actions with `defineAction` and the `http` option (area 2 in detail)

package/corpus/templates/chat/.agents/skills/security/SKILL.md

@@ -159,6 +159,35 @@ whole site. Data scoping lives in actions and API routes; the client gates
 private UI after the shell loads. See the `authentication` skill and
 `guard:ssr-cache-shell` / `ssr-handler.spec.ts`.
 
+**Authorization beyond "is there a session" — `authorize`.** The auth guard only
+proves *someone* is signed in. To restrict an operation to some teammates, set
+`authorize` on the `defineAction`. It wraps `run`, so it applies at every
+dispatch site (agent tool, HTTP, frontend, MCP, A2A, CLI) — unlike
+`needsApproval`, which is honoured only in the agent loop.
+
+```ts
+import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
+
+export default defineAction({
+  description: "Archive a client roster.",
+  schema: z.object({ id: z.string() }),
+  authorize: coachAccess.requireAny("coach-admin"),
+  run: async (args) => {
+    /* ... */
+  },
+});
+```
+
+A guard that throws denies with its own message; returning `false` denies
+generically; anything else (including `undefined`) allows. Guarded actions need
+a user identity — an unattended CLI/cron caller with no user email is denied.
+
+`authorize` is **not** a substitute for `accessFilter` / `assertAccess`. It
+decides whether this caller may perform the operation at all; `accessFilter` /
+`assertAccess` scope which rows a permitted caller may see or touch. A
+restricted write action needs both. See the `authentication` skill for
+`defineAppRoles` and the `actions` skill for the full surface.
+
 ## Human-in-the-Loop Approval for High-Consequence Actions
 
 For a small set of outward-facing, hard-to-undo operations — sending an email, charging a card, deleting an account, posting publicly — auth and access control are necessary but not sufficient: you also do not want the **agent** to perform them autonomously. Set `needsApproval` on the `defineAction` so the agent cannot run the action without a human approving the specific call.
@@ -274,6 +303,8 @@ Run `pnpm action db-check-scoping` to verify. Use `--require-org` for multi-org
 - [ ] New env vars in `.env` only, not committed
 - [ ] New user-data tables have `owner_email` column
 - [ ] Custom routes call `getSession` and reject unauthenticated requests
+- [ ] Actions only some teammates may run set `authorize` (in addition to any
+      `accessFilter` / `assertAccess` row scoping)
 
 ## Related Skills
 

package/corpus/templates/chat/.agents/skills/sharing/SKILL.md

@@ -34,6 +34,8 @@ Visibility is coarse. Explicit share grants are fine-grained (per user or per or
 - **`editor`** — read + write.
 - **`admin`** — read + write + manage shares. Does NOT replace the single `owner_email` on the resource.
 
+There are three role systems and they never imply one another. A share role answers "what may this person do to **one row**". An org role (`org_members.role`) answers "what may this person do to the **team**". An app role (`defineAppRoles`, see the `authentication` skill) answers "what may this person do inside **one app**". A share `admin` is not an app admin and neither is an org admin.
+
 ### Anonymous public URLs stay separate
 
 Form "publish" slugs, booking-link slugs, any feature that exposes a URL to unauthenticated users — these are a different axis and are NOT controlled by the sharing system. Keep them alongside it.
@@ -137,6 +139,8 @@ export default defineAction({
 
 For delete actions use `"admin"` (or fold in `"owner"` to require the real owner).
 
+`authorize` is a different axis, not an alternative: it gates whether the caller may run the operation at all, while `assertAccess` scopes which row they may touch. A write action restricted to some teammates needs both — `authorize: appAccess.requireAny(...)` on the action, `assertAccess` inside `run`.
+
 ## Create actions must set owner
 
 When inserting a new row, fill `ownerEmail` and `orgId` from the request context:

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

@@ -305,6 +305,38 @@ export default defineAction({
 
 On success the validated value is returned, so coercion/defaults on `outputSchema` apply. Omit `outputSchema` and behavior is byte-for-byte unchanged (no wrapping).
 
+### Authorization (`authorize`)
+
+`authorize` decides whether the caller may run the action at all. It wraps
+`run`, so it holds at **all six dispatch sites** — agent tool, HTTP, frontend
+hook, MCP, A2A, CLI — unlike `needsApproval`, which is honoured only in the
+agent loop. Use `authorize` for "not everyone may do this"; use `needsApproval`
+to ask a human to bless one call a permitted caller is already allowed to make.
+
+```ts
+import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
+
+export default defineAction({
+  description: "Archive a client roster.",
+  schema: z.object({ id: z.string() }),
+  authorize: coachAccess.requireAny("coach-admin"),
+  run: async (args) => {
+    /* ... */
+  },
+});
+```
+
+The wrappers compose as `validate input -> authorize -> run -> validate output
+-> audit`: the gate sits inside input validation, so a guard reading `args` gets
+the parsed, coerced value, and auditing is outermost, so denials are recorded.
+
+A guard that throws denies with its own message; returning `false` denies
+generically; anything else (including `undefined`) allows. A guarded action
+needs a user identity, so an unattended CLI/cron caller with no user email is
+denied. `authorize` gates the operation; `accessFilter` / `assertAccess` still
+scope which rows a permitted caller may touch. See the `authentication` skill
+for `defineAppRoles` and the `sharing` skill for row scoping.
+
 ### Human-in-the-Loop Approval (`needsApproval`)
 
 For high-consequence, outward-facing, hard-to-undo actions (sending an email, charging a card, deleting an account), set `needsApproval` so the agent **cannot** run the action without a human approving the specific call:

package/corpus/templates/clips/.agents/skills/security/SKILL.md

@@ -159,6 +159,35 @@ whole site. Data scoping lives in actions and API routes; the client gates
 private UI after the shell loads. See the `authentication` skill and
 `guard:ssr-cache-shell` / `ssr-handler.spec.ts`.
 
+**Authorization beyond "is there a session" — `authorize`.** The auth guard only
+proves *someone* is signed in. To restrict an operation to some teammates, set
+`authorize` on the `defineAction`. It wraps `run`, so it applies at every
+dispatch site (agent tool, HTTP, frontend, MCP, A2A, CLI) — unlike
+`needsApproval`, which is honoured only in the agent loop.
+
+```ts
+import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
+
+export default defineAction({
+  description: "Archive a client roster.",
+  schema: z.object({ id: z.string() }),
+  authorize: coachAccess.requireAny("coach-admin"),
+  run: async (args) => {
+    /* ... */
+  },
+});
+```
+
+A guard that throws denies with its own message; returning `false` denies
+generically; anything else (including `undefined`) allows. Guarded actions need
+a user identity — an unattended CLI/cron caller with no user email is denied.
+
+`authorize` is **not** a substitute for `accessFilter` / `assertAccess`. It
+decides whether this caller may perform the operation at all; `accessFilter` /
+`assertAccess` scope which rows a permitted caller may see or touch. A
+restricted write action needs both. See the `authentication` skill for
+`defineAppRoles` and the `actions` skill for the full surface.
+
 ## Human-in-the-Loop Approval for High-Consequence Actions
 
 For a small set of outward-facing, hard-to-undo operations — sending an email, charging a card, deleting an account, posting publicly — auth and access control are necessary but not sufficient: you also do not want the **agent** to perform them autonomously. Set `needsApproval` on the `defineAction` so the agent cannot run the action without a human approving the specific call.
@@ -274,6 +303,8 @@ Run `pnpm action db-check-scoping` to verify. Use `--require-org` for multi-org
 - [ ] New env vars in `.env` only, not committed
 - [ ] New user-data tables have `owner_email` column
 - [ ] Custom routes call `getSession` and reject unauthenticated requests
+- [ ] Actions only some teammates may run set `authorize` (in addition to any
+      `accessFilter` / `assertAccess` row scoping)
 
 ## Related Skills
 

package/corpus/templates/clips/_gitignore

@@ -8,8 +8,10 @@ npm-debug.log*
 pnpm-debug.log*
 
 node_modules
+build/
 dist
 dist-ssr
+.output/
 *.local
 
 # Editor directories and files

package/corpus/templates/clips/actions/request-transcript.ts

@@ -59,6 +59,7 @@ import {
   normalizeTranscriptSegments,
   parseTranscriptSegments,
 } from "../shared/transcript-segments.js";
+import { PENDING_TRANSCRIPT_HEARTBEAT_MS } from "../shared/transcript-status.js";
 import cleanupTranscript from "./cleanup-transcript.js";
 import { loadAgentsMdContext } from "./lib/agents-md-context.js";
 import {
@@ -419,6 +420,54 @@ function isRecentlyPendingTranscript(transcript: {
   );
 }
 
+/**
+ * Run `work` while keeping this recording's pending transcript row marked live.
+ *
+ * `resolveTranscriptPresentation` infers "the worker is gone" from a pending
+ * row nothing has written for STALE_PENDING_TRANSCRIPT_MS, because the row
+ * carries no other liveness signal. Media fetch, ffmpeg extraction and the
+ * provider call legitimately add up past that window on a long recording, so
+ * without this ping the UI publishes a terminal "stopped before it finished"
+ * failure over a run that is still working — and the player's self-heal then
+ * forces a second concurrent transcription of the same clip.
+ *
+ * The update is scoped to `status = 'pending'` so it can never touch a row a
+ * concurrent run has already finished, and the interval is unref'd and cleared
+ * so it cannot hold a serverless invocation open.
+ */
+async function withPendingTranscriptHeartbeat<T>(
+  db: ReturnType<typeof getDb>,
+  recordingId: string,
+  work: () => Promise<T>,
+): Promise<T> {
+  const timer = setInterval(() => {
+    void (async () => {
+      try {
+        await db
+          .update(schema.recordingTranscripts)
+          .set({ updatedAt: new Date().toISOString() })
+          .where(
+            and(
+              eq(schema.recordingTranscripts.recordingId, recordingId),
+              eq(schema.recordingTranscripts.status, "pending"),
+            ),
+          );
+      } catch (err) {
+        console.warn(
+          `[clips] transcript heartbeat failed for ${recordingId}:`,
+          (err as Error)?.message ?? String(err),
+        );
+      }
+    })();
+  }, PENDING_TRANSCRIPT_HEARTBEAT_MS);
+  (timer as { unref?: () => void }).unref?.();
+  try {
+    return await work();
+  } finally {
+    clearInterval(timer);
+  }
+}
+
 async function writeTranscriptCleanupState(
   recordingId: string,
   value: Record<string, unknown>,
@@ -1251,8 +1300,15 @@ const requestTranscriptAction = defineAction({
 
       let audioMedia: AudioOnlyTranscriptionMedia;
       try {
-        audioMedia = await getAudioMedia(rec);
-        await ensureAudioHasSignal(audioMedia);
+        audioMedia = await withPendingTranscriptHeartbeat(
+          db,
+          args.recordingId,
+          async () => {
+            const media = await getAudioMedia(rec);
+            await ensureAudioHasSignal(media);
+            return media;
+          },
+        );
       } catch (err) {
         return failAudioOnlyPreparation({
           db,
@@ -1266,13 +1322,18 @@ const requestTranscriptAction = defineAction({
 
       try {
         const startedAt = Date.now();
-        const builderResult = await transcribeWithBuilderModelFallback({
-          audioBytes: audioMedia.audioBytes,
-          mimeType: audioMedia.mimeType,
-          diarize: false,
-          instructions: SPEECH_ONLY_TRANSCRIPTION_INSTRUCTIONS,
-          timeoutMs: builderTranscriptionTimeoutMs(rec.durationMs),
-        });
+        const builderResult = await withPendingTranscriptHeartbeat(
+          db,
+          args.recordingId,
+          () =>
+            transcribeWithBuilderModelFallback({
+              audioBytes: audioMedia.audioBytes,
+              mimeType: audioMedia.mimeType,
+              diarize: false,
+              instructions: SPEECH_ONLY_TRANSCRIPTION_INSTRUCTIONS,
+              timeoutMs: builderTranscriptionTimeoutMs(rec.durationMs),
+            }),
+        );
 
         const segments = (builderResult.segments ?? [])
           .map((s) => ({
@@ -1449,6 +1510,11 @@ async function upsertTranscriptRow(
     .limit(1);
 
   const retryCount = row.status === "ready" ? 0 : (row.retryCount ?? undefined);
+  // `row.now` is captured once at the top of a run that can last minutes, so it
+  // is a creation timestamp, never a "last written" one. Stamping it as
+  // `updatedAt` would walk the pending heartbeat backwards and re-arm the stale
+  // check over a run that just finished.
+  const updatedAt = new Date().toISOString();
 
   if (existing) {
     await db
@@ -1461,7 +1527,7 @@ async function upsertTranscriptRow(
         ...(row.segmentsJson ? { segmentsJson: row.segmentsJson } : {}),
         ...(row.fullText !== undefined ? { fullText: row.fullText } : {}),
         ...(retryCount !== undefined ? { retryCount } : {}),
-        updatedAt: row.now,
+        updatedAt,
       })
       .where(eq(schema.recordingTranscripts.recordingId, row.recordingId));
   } else {
@@ -1475,7 +1541,7 @@ async function upsertTranscriptRow(
       failureReason: row.failureReason,
       retryCount: retryCount ?? 0,
       createdAt: row.now,
-      updatedAt: row.now,
+      updatedAt,
     });
   }
 }

package/corpus/templates/clips/actions/save-browser-transcript.ts

@@ -153,6 +153,18 @@ export default defineAction({
       };
     }
 
+    // Text plus a failure reason means capture died partway (a Web Speech
+    // session that could not restart, a revoked mic). Keep the partial text,
+    // but never mark it `ready`: that is the terminal state every preserve
+    // guard checks, so a three-line partial would permanently suppress the
+    // Builder fallback that can still transcribe the whole recording.
+    // `failed` rather than `pending`/`streaming` — a fresh pending row makes
+    // finalization's own transcript job skip itself as already-pending, and a
+    // perpetual streaming row reads as normal progress that never resolves.
+    const truncated = Boolean(failureReason);
+    const savedStatus = truncated ? ("failed" as const) : ("ready" as const);
+    const savedFailureReason = truncated ? failureReason : null;
+
     if (current) {
       // Don't overwrite an already-segmented cloud/native transcript with a
       // later lower-confidence native pass — UNLESS the caller owns this
@@ -172,8 +184,8 @@ export default defineAction({
           ownerEmail,
           fullText,
           segmentsJson,
-          status: "ready",
-          failureReason: null,
+          status: savedStatus,
+          failureReason: savedFailureReason,
           updatedAt: now,
         })
         .where(eq(schema.recordingTranscripts.recordingId, args.recordingId));
@@ -184,15 +196,17 @@ export default defineAction({
         language: "en",
         segmentsJson,
         fullText,
-        status: "ready",
-        failureReason: null,
+        status: savedStatus,
+        failureReason: savedFailureReason,
         createdAt: now,
         updatedAt: now,
       });
     }
 
     console.log(
-      `[clips] Native transcript saved for ${args.recordingId} via ${args.source ?? "web-speech"} (${fullText.length} chars)`,
+      truncated
+        ? `[clips] Partial native transcript saved for ${args.recordingId} via ${args.source ?? "web-speech"} (${fullText.length} chars); Builder fallback will retranscribe: ${failureReason}`
+        : `[clips] Native transcript saved for ${args.recordingId} via ${args.source ?? "web-speech"} (${fullText.length} chars)`,
     );
 
     await writeAppState("refresh-signal", { ts: Date.now() });
@@ -212,7 +226,13 @@ export default defineAction({
       rec && isAutoTitleReplaceable(rec.title, rec.titleSource)
     );
     const summaryQueued = Boolean(rec && !rec.description?.trim());
-    if (rec?.status === "ready" && (titleQueued || summaryQueued)) {
+    // A truncated capture dispatches too: the transcript job is what runs the
+    // Builder fallback, and it must not be skipped just because this clip
+    // already has a title and summary.
+    if (
+      rec?.status === "ready" &&
+      (truncated || titleQueued || summaryQueued)
+    ) {
       await dispatchPostFinalizeJob({
         recordingId: args.recordingId,
         kind: "transcript",
@@ -226,9 +246,10 @@ export default defineAction({
 
     return {
       recordingId: args.recordingId,
-      status: "ready" as const,
+      status: savedStatus,
       provider: args.source ?? "web-speech",
       chars: fullText.length,
+      truncated,
       titleQueued,
       summaryQueued,
     };

package/corpus/templates/clips/app/routes/record.tsx

@@ -2054,6 +2054,11 @@ export default function RecordRoute() {
       // (from Web Speech API) with no API key required.
       const browserTranscript = await liveTranscription.stopAndWait();
       const trimmedTranscript = browserTranscript.trim();
+      // Non-null when Web Speech died before we asked it to stop, so whatever
+      // it captured covers only part of the recording. Send it with the text:
+      // a partial transcript must never be stored as the finished one, or the
+      // cloud fallback is suppressed and the user keeps the first few lines.
+      const incompleteReason = liveTranscription.getIncompleteReason();
       if (trimmedTranscript) {
         const transcriptRes = await fetch(
           agentNativePath("/_agent-native/actions/save-browser-transcript"),
@@ -2064,6 +2069,7 @@ export default function RecordRoute() {
               recordingId: pending.id,
               fullText: trimmedTranscript,
               source: "web-speech",
+              failureReason: incompleteReason ?? undefined,
             }),
           },
         ).catch((err) => {
@@ -2086,9 +2092,11 @@ export default function RecordRoute() {
               recordingId: pending.id,
               fullText: "",
               source: "web-speech",
-              failureReason: liveTranscription.supported
-                ? "Browser native transcription returned no speech before recording stopped."
-                : "Browser Web Speech recognition is unavailable in this browser.",
+              failureReason:
+                incompleteReason ??
+                (liveTranscription.supported
+                  ? "Browser native transcription returned no speech before recording stopped."
+                  : "Browser Web Speech recognition is unavailable in this browser."),
             }),
           },
         ).catch((err) => {

package/corpus/templates/clips/changelog/2026-07-28-browser-recordings-no-longer-save-a-truncated-transcript-as-.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-28
+---
+
+Browser recordings no longer save a truncated transcript as complete when speech recognition stops early

package/corpus/templates/clips/changelog/2026-07-28-browser-recordings-no-longer-stop-transcribing-partway-throu.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-28
+---
+
+Browser recordings no longer stop transcribing partway through; a partial live transcript is now flagged instead of saved as the finished one.

package/corpus/templates/clips/changelog/2026-07-28-desktop-full-screen-clips-now-get-an-instant-local-transcrip.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-28
+---
+
+Desktop full-screen clips now get an instant local transcript (and a real title) instead of waiting on cloud transcription

package/corpus/templates/clips/changelog/2026-07-28-long-transcriptions-no-longer-show-a-false-transcription-sto.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-28
+---
+
+Long transcriptions no longer show a false 'transcription stopped' error while they are still running

package/corpus/templates/clips/changelog/2026-07-28-restarting-for-an-update-now-installs-the-newest-release-ins.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-28
+---
+
+Restarting for an update now installs the newest release instead of a stale download that immediately asks you to restart again.

package/corpus/templates/clips/changelog/2026-07-28-the-meeting-recording-pill-now-anchors-to-the-right-edge-of-.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-28
+---
+
+The meeting recording pill now anchors to the right edge of the screen, shows a live waveform that reacts to both you and other speakers, and reads as a proper pill.