@agent-native/core 0.76.0 → 0.76.1

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,46 @@
 # @agent-native/core
 
+## 0.76.1
+
+### Patch Changes
+
+- 50f32ff: Make durable-background agent-chat worker failures diagnosable from the client
+  and harden recovery when the background worker never starts.
+
+  A durable-background run is dispatched into a Netlify `-background` function,
+  which acks asynchronously with a 202. If that worker then dies silently (its
+  logs are not readable from the build tooling), the run would just time out with
+  no clue why, and because dispatch already returned 202 the existing fast-fail
+  inline fallback never engaged — so the run errored opaquely.
+
+  Diagnostics (readable WITHOUT bg-fn logs). The `_process-run` worker pipeline
+  now records the last reached stage onto the run row (`agent_runs.diag_stage`, a
+  compact JSON `{stage,detail?,at}`) via the new best-effort `recordRunDiagnostic`:
+  route entered, HMAC auth pass/fail (recorded onto the run BEFORE the 401/503 is
+  returned, including whether `A2A_SECRET` is present in the bg-fn isolate),
+  worker entered (with the resolved `runsInBackgroundFunction` value), claim
+  win/lose, worker loop started, and any thrown error. `/runs/active?threadId=`
+  (and `listRunsForThread`) now surface `dispatchMode` and `diagStage`, so the
+  next prod run's death cause is readable straight from the client.
+
+  Recovery (covers "202 acked but worker never started"). A background-dispatched
+  run that is still unclaimed (`dispatch_mode = 'background'`, never flipped to
+  `background-processing`) past a tight 25s grace is reaped early and recoverably
+  with the new `background_worker_never_started` error code (the wide 90s window
+  only exists to protect a CLAIMED, cold-starting worker — an unclaimed run has no
+  worker to protect). The `/runs/active` read path attempts this recovery before
+  the generic stale reaper, so a silent worker death surfaces as a recoverable
+  error the client can re-drive instead of hanging for 90s.
+
+  Also fixes a latent gate: `/_agent-native/agent-chat/_process-run` now bypasses
+  the session-auth guard (mirroring the agent-teams processor). The self-dispatch
+  carries only an HMAC Bearer token and no session cookie, so without the bypass
+  the worker was 401'd before it could authenticate and claim the run.
+
+- 50f32ff: Tighten bundled visual plan wireframe guidance so agents use literal spacing,
+  pad root containers, and choose feature-cloud layouts for abundance-style
+  marketing sections.
+
 ## 0.76.0
 
 ### Minor Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.76.0",
+  "version": "0.76.1",
   "type": "module",
   "engines": {
     "node": ">=22"

package/corpus/core/src/agent/durable-background.ts

@@ -285,8 +285,37 @@ export type ProcessRunPreparation =
       status: number;
       /** Error payload. */
       error: string;
+      /**
+       * The run id parsed from the body, when present. Carried even on failure
+       * so the route can RECORD the auth/validation failure ONTO the run
+       * (diag_stage) before returning the error status — otherwise a 401/503 in
+       * the unreadable Netlify background function would leave the run to time
+       * out with no clue why. Null when no run id could be parsed.
+       */
+      runId: string | null;
     };
 
+/**
+ * Parse the run id from a `_process-run` request body without authenticating.
+ * Mirrors the precedence in `prepareProcessRunRequest` (marker.runId, then
+ * top-level taskId). Returns null when neither is a usable string. Used so the
+ * route can attach a diagnostic to the run even on an auth/validation failure.
+ */
+export function extractProcessRunId(body: unknown): string | null {
+  if (!body || typeof body !== "object") return null;
+  const record = body as Record<string, unknown>;
+  const marker = record[AGENT_CHAT_BACKGROUND_RUN_FIELD] as
+    | { runId?: unknown }
+    | undefined;
+  if (marker && typeof marker.runId === "string" && marker.runId) {
+    return marker.runId;
+  }
+  if (typeof record.taskId === "string" && record.taskId) {
+    return record.taskId;
+  }
+  return null;
+}
+
 /**
  * Pure, transport-agnostic core of the `_process-run` route: validate the body,
  * authenticate the HMAC self-dispatch, and produce the body the re-entered
@@ -308,7 +337,12 @@ export function prepareProcessRunRequest(
   authHeader: string | undefined,
 ): ProcessRunPreparation {
   if (!body || typeof body !== "object") {
-    return { ok: false, status: 400, error: "Invalid request body" };
+    return {
+      ok: false,
+      status: 400,
+      error: "Invalid request body",
+      runId: null,
+    };
   }
   const record = body as Record<string, unknown>;
   const marker = record[AGENT_CHAT_BACKGROUND_RUN_FIELD] as
@@ -321,7 +355,7 @@ export function prepareProcessRunRequest(
         ? (record.taskId as string)
         : "";
   if (!runId) {
-    return { ok: false, status: 400, error: "runId required" };
+    return { ok: false, status: 400, error: "runId required", runId: null };
   }
 
   if (hasConfiguredA2ASecret()) {
@@ -331,6 +365,7 @@ export function prepareProcessRunRequest(
         ok: false,
         status: 401,
         error: "Invalid or expired processor token",
+        runId,
       };
     }
   } else if (isA2AProductionRuntime()) {
@@ -339,6 +374,7 @@ export function prepareProcessRunRequest(
       status: 503,
       error:
         "Agent chat background processor not configured — set A2A_SECRET on this deployment.",
+      runId,
     };
   }
 

package/corpus/core/src/agent/production-agent.ts

@@ -109,6 +109,8 @@ import {
   updateRunHeartbeat,
   updateRunStatusIfRunning,
   claimBackgroundRun,
+  recordRunDiagnostic,
+  RUN_DIAG_STAGE,
 } from "./run-store.js";
 import {
   classifyToolCallJournal,
@@ -4599,6 +4601,30 @@ export function createProductionAgentHandler(
       isBackgroundWorker || baseHandleRunComplete
         ? async (run: ActiveRun) => {
             try {
+              // DIAGNOSTIC: a background worker that completed in an errored
+              // state threw inside the loop. Record it (with the last error
+              // event's message when available) so the failure cause is
+              // readable from the client. Skipped for clean completions and for
+              // recoverable soft-timeout boundaries (those chain a continuation
+              // below, they did not "throw").
+              if (
+                isBackgroundWorker &&
+                run.status === "errored" &&
+                !endsAtInternalContinuationBoundary(run)
+              ) {
+                const errEvent = [...run.events]
+                  .reverse()
+                  .find((e) => e.event.type === "error")?.event as
+                  | { error?: string; errorCode?: string }
+                  | undefined;
+                await recordRunDiagnostic(
+                  run.runId,
+                  RUN_DIAG_STAGE.workerThrew,
+                  errEvent?.errorCode || errEvent?.error
+                    ? `${errEvent.errorCode ?? ""} ${errEvent.error ?? ""}`.trim()
+                    : "run ended in errored state",
+                ).catch(() => {});
+              }
               // Persist the (partial) assistant turn to thread_data FIRST — the
               // server-driven continuation below rebuilds from it, so it must be
               // committed before we re-fire.
@@ -4689,6 +4715,17 @@ export function createProductionAgentHandler(
     // on entry so a slow cold-start doesn't leave the row looking stale to the
     // reaper before startRun's 1.5s heartbeat timer takes over.
     if (isBackgroundWorker) {
+      // DIAGNOSTIC: the re-entered handler recognized itself as the background
+      // worker. Record the runtime regime too — `isInBackgroundFunctionRuntime()`
+      // reads a globalThis marker set by the bg-fn entry, which may NOT be set in
+      // this isolate; recording the ACTUAL resolved value reveals whether the
+      // worker is on the 13-min `-background` budget or the 40s clamp. This is
+      // the proof the worker reached its own code (vs. dying at auth before it).
+      await recordRunDiagnostic(
+        runId,
+        RUN_DIAG_STAGE.workerEntered,
+        `runsInBackgroundFunction=${runsInBackgroundFunction} continuationCount=${backgroundContinuationCount}`,
+      ).catch(() => {});
       // A chained continuation chunk's runId was minted by the prior chunk and
       // never inserted, so insert its background row now (idempotently — a
       // duplicate Netlify delivery that already inserted it just PK-collides and
@@ -4703,8 +4740,16 @@ export function createProductionAgentHandler(
       if (!won) {
         // Already claimed by an earlier delivery — return a benign ack so
         // Netlify doesn't retry a successful handoff.
+        await recordRunDiagnostic(runId, RUN_DIAG_STAGE.workerClaimLost).catch(
+          () => {},
+        );
         return { ok: true, skipped: "already-claimed" };
       }
+      // DIAGNOSTIC: this worker won the claim and now OWNS the run. If a run
+      // ever stalls at this stage it means the loop below failed to start.
+      await recordRunDiagnostic(runId, RUN_DIAG_STAGE.workerClaimed).catch(
+        () => {},
+      );
       await updateRunHeartbeat(runId).catch(() => {});
     }
 
@@ -4719,6 +4764,15 @@ export function createProductionAgentHandler(
 
         send({ type: "activity", label: "Starting agent" });
 
+        // DIAGNOSTIC: the agent loop body actually started running. For a
+        // background worker, a run that is claimed but never reaches this stage
+        // died between claiming and loop start. Best-effort, background only.
+        if (isBackgroundWorker) {
+          await recordRunDiagnostic(runId, RUN_DIAG_STAGE.workerStarted).catch(
+            () => {},
+          );
+        }
+
         // Notify listeners that a run has started (used by agent teams)
         if (options.onRunStart) {
           await options.onRunStart(send, threadId ?? runId);

package/corpus/core/src/agent/run-manager.ts

@@ -15,6 +15,7 @@ import {
   updateRunHeartbeat,
   bumpRunProgress,
   reapIfStale,
+  reapUnclaimedBackgroundRun,
   ensureTerminalRunEvent,
   setRunError,
   STALE_RUN_ERROR_EVENT,
@@ -1022,6 +1023,14 @@ export async function getActiveRunForThreadAsync(threadId: string): Promise<{
   status: string;
   heartbeatAt: number;
   lastProgressAt: number | null;
+  /** How the run was dispatched (NULL/foreground, background, background-processing). */
+  dispatchMode?: string | null;
+  /**
+   * Last reached `_process-run` worker stage as a JSON string
+   * `{stage,detail?,at}`. Surfaced so a silent background-worker death is
+   * diagnosable from the client WITHOUT the unreadable bg-fn logs.
+   */
+  diagStage?: string | null;
 } | null> {
   // Check memory first — return both running AND recently-completed runs
   // that still have events in memory. This allows sub-agent tabs to replay
@@ -1055,6 +1064,20 @@ export async function getActiveRunForThreadAsync(threadId: string): Promise<{
     const sqlRun = await getRunByThread(threadId, { includeTerminal: true });
     if (!sqlRun) return null;
     if (sqlRun.status === "running") {
+      // FALLBACK HARDENING: a background-dispatched run that is still UNCLAIMED
+      // (dispatch_mode === 'background', never flipped to 'background-processing')
+      // past the tight grace means the bg-fn worker never started — a silent
+      // async-worker death that the 202-ack inline fallback can't catch. Reap it
+      // early and recoverably (background_worker_never_started) so the run no
+      // longer hangs for the full 90s window and the client's recoverable-error
+      // path can re-drive the turn. Only fires when there is provably no live
+      // worker; a claimed/heartbeating run is left alone by the conditional SQL.
+      if (sqlRun.dispatchMode === "background") {
+        const recovered = await reapUnclaimedBackgroundRun(sqlRun.id).catch(
+          () => false,
+        );
+        if (recovered) return null;
+      }
       // If the producer is dead (no recent heartbeat), reap before the
       // client can see a stale "running" status and enter a reconnect
       // loop it can never exit.
@@ -1067,6 +1090,8 @@ export async function getActiveRunForThreadAsync(threadId: string): Promise<{
         status: sqlRun.status,
         heartbeatAt: sqlRun.heartbeatAt ?? sqlRun.startedAt,
         lastProgressAt: sqlRun.lastProgressAt,
+        dispatchMode: sqlRun.dispatchMode,
+        diagStage: sqlRun.diagStage,
       };
     }
     if (sqlRun.status === "completed" || sqlRun.status === "errored") {
@@ -1092,6 +1117,8 @@ export async function getActiveRunForThreadAsync(threadId: string): Promise<{
         status: sqlRun.status,
         heartbeatAt: sqlRun.heartbeatAt ?? sqlRun.startedAt,
         lastProgressAt: sqlRun.lastProgressAt,
+        dispatchMode: sqlRun.dispatchMode,
+        diagStage: sqlRun.diagStage,
       };
     }
   } catch {

package/corpus/core/src/agent/run-store.ts

@@ -44,6 +44,40 @@ export const STALE_RUN_ERROR_EVENT = {
     "The run heartbeat stopped while the run was still marked running. Partial output and tool calls were preserved when available.",
 } as const;
 
+/**
+ * Terminal error for a background-dispatched run whose worker NEVER claimed it
+ * (the foreground fired the self-dispatch, Netlify acked it async with a 202,
+ * but the `_process-run` worker never ran far enough to flip
+ * `dispatch_mode background → background-processing`). Distinct errorCode so the
+ * client (and prod triage) can tell "the worker died silently" apart from "a
+ * claimed worker's heartbeat went stale". Recoverable so the client surfaces a
+ * retry affordance and re-drives the turn. See `reapUnclaimedBackgroundRun`.
+ */
+export const UNCLAIMED_BACKGROUND_RUN_ERROR_EVENT = {
+  type: "error",
+  error:
+    "The agent run was handed off to a background worker that never started. It was recovered so you can try again.",
+  errorCode: "background_worker_never_started",
+  recoverable: true,
+  details:
+    "A background-dispatched run was acknowledged (HTTP 202) but its worker never claimed the run, so no progress was produced. The run was reaped early (it had no live worker to protect) so the turn can be retried.",
+} as const;
+
+/**
+ * Grace period before a never-claimed background run (dispatch_mode still
+ * 'background', no worker claim) is treated as a dead handoff and reaped.
+ *
+ * This is intentionally MUCH tighter than `BACKGROUND_RUN_STALE_MS` (90s). The
+ * wide 90s window exists ONLY to protect a CLAIMED worker whose heartbeat lags
+ * during a slow cold start. A run that is still `dispatch_mode = 'background'`
+ * has, by definition, NO worker — nothing to protect — so once a Netlify
+ * background function has had a reasonable cold-start window to claim it and
+ * hasn't, the handoff is dead and should surface promptly instead of leaving
+ * the user staring at a spinner for 90s. 25s comfortably exceeds a normal
+ * Netlify Lambda cold start while still failing fast on a silent worker death.
+ */
+export const UNCLAIMED_BACKGROUND_RUN_GRACE_MS = 25_000;
+
 async function ensureRunTables(): Promise<void> {
   if (!_initPromise) {
     _initPromise = (async () => {
@@ -61,7 +95,8 @@ async function ensureRunTables(): Promise<void> {
           turn_id TEXT,
           error_code TEXT,
           error_detail TEXT,
-          dispatch_mode TEXT
+          dispatch_mode TEXT,
+          diag_stage TEXT
         )
       `);
       // Backfill heartbeat_at on older deployments.
@@ -118,11 +153,16 @@ async function ensureRunTables(): Promise<void> {
       // normal synchronous path, "background" for a run dispatched into a
       // Netlify background function. The reaper/claim widen the stale window
       // for background rows so a slow cold-start isn't falsely reaped.
+      // diag_stage records the last reached pipeline stage (+ any error) for a
+      // background-dispatched run so a silent worker death is DIAGNOSABLE from
+      // the client (/runs/active surfaces it) without reading the unreadable
+      // Netlify background-function logs. See recordRunDiagnostic.
       for (const col of [
         "turn_id",
         "error_code",
         "error_detail",
         "dispatch_mode",
+        "diag_stage",
       ] as const) {
         try {
           if (isPostgres()) {
@@ -416,6 +456,72 @@ export async function setRunError(
   }
 }
 
+/**
+ * Diagnostic stage names recorded onto a background run as it moves through the
+ * `_process-run` worker pipeline. Each value is the LAST stage successfully
+ * reached, so a stuck run's `diag_stage` reveals exactly where it died. Ordered
+ * roughly by execution; the literal strings are the client-readable contract.
+ */
+export const RUN_DIAG_STAGE = {
+  /** The `_process-run` route handler was entered (the request reached Nitro). */
+  routeEntered: "route_entered",
+  /** HMAC auth + body validation in prepareProcessRunRequest FAILED. */
+  authFailed: "auth_failed",
+  /** HMAC auth + body validation PASSED; about to invoke the worker handler. */
+  authPassed: "auth_passed",
+  /** The re-entered agent-chat handler recognized itself as the bg worker. */
+  workerEntered: "worker_entered",
+  /** The worker won the atomic claim (it owns the run). */
+  workerClaimed: "worker_claimed",
+  /** The worker LOST the claim (a duplicate delivery already owns the run). */
+  workerClaimLost: "worker_claim_lost",
+  /** The agent loop started (startRun fired). */
+  workerStarted: "worker_started",
+  /** The worker threw before/while running the loop (message carried in detail). */
+  workerThrew: "worker_threw",
+  /** The route handler caught an error from the worker invocation. */
+  routeThrew: "route_threw",
+} as const;
+
+export type RunDiagStage = (typeof RUN_DIAG_STAGE)[keyof typeof RUN_DIAG_STAGE];
+
+/**
+ * Record the last reached pipeline stage (+ optional short detail) for a run.
+ *
+ * PURPOSE: a Netlify background function's logs are not readable from the build
+ * tooling, so when its worker dies silently the run just times out with no clue
+ * WHY. This writes the failure stage straight onto the `agent_runs` row, which
+ * `/runs/active` and `listRunsForThread` surface to the client — so the next
+ * prod run's death cause is readable WITHOUT bg-fn logs. Cheap, additive, and
+ * best-effort: it must never throw or perturb the run (it is called on the auth
+ * path BEFORE a 401 is returned, and around the worker body).
+ *
+ * The stored value is a compact JSON `{ stage, detail?, at }` capped to 2 KB so
+ * a long stack can't bloat the row.
+ */
+export async function recordRunDiagnostic(
+  runId: string,
+  stage: RunDiagStage,
+  detail?: string,
+): Promise<void> {
+  if (!runId) return;
+  try {
+    await ensureRunTables();
+    const client = getDbExec();
+    const payload = JSON.stringify({
+      stage,
+      ...(detail ? { detail: detail.slice(0, 1500) } : {}),
+      at: Date.now(),
+    }).slice(0, 2000);
+    await client.execute({
+      sql: `UPDATE agent_runs SET diag_stage = ? WHERE id = ?`,
+      args: [payload, runId],
+    });
+  } catch {
+    // Diagnostics are best-effort; never let them break the run or the route.
+  }
+}
+
 /** Update the run's liveness heartbeat. Called periodically by run-manager. */
 export async function updateRunHeartbeat(runId: string): Promise<void> {
   await ensureRunTables();
@@ -490,6 +596,68 @@ export async function reapIfStale(
   return reaped;
 }
 
+/**
+ * FALLBACK HARDENING for the "dispatched with 202 but the worker never started"
+ * case. A background-dispatched run sits in `dispatch_mode = 'background'` until
+ * the worker wins `claimBackgroundRun` (which flips it to
+ * `background-processing`). If the worker silently dies (e.g. the bg-fn 401s
+ * before it can claim), the row stays `background`, never heartbeats again, and
+ * — because dispatch returned 202 — the foreground already returned the SSE
+ * stream, so the existing fast-fail inline fallback never engaged. The run would
+ * otherwise hang for the full 90s background window and then error opaquely.
+ *
+ * This reaps such a run EARLY and DISTINCTLY: a row that is still unclaimed
+ * (`dispatch_mode = 'background'`) past the tight `UNCLAIMED_BACKGROUND_RUN_GRACE_MS`
+ * grace is a dead handoff — there is no live worker to protect with the wide
+ * window — so we flip it to `errored` with the recoverable
+ * `background_worker_never_started` code. The client's existing recoverable-error
+ * path then lets the user (or auto-recovery) re-drive the turn. Idempotent and
+ * conditional: only an unclaimed, still-running, grace-exceeded row matches, so a
+ * claimed worker, a fresh dispatch, or a terminal row is never touched.
+ *
+ * Returns true when this call reaped the run.
+ */
+export async function reapUnclaimedBackgroundRun(
+  runId: string,
+): Promise<boolean> {
+  await ensureRunTables();
+  const client = getDbExec();
+  const completedAt = Date.now();
+  const cutoff = completedAt - UNCLAIMED_BACKGROUND_RUN_GRACE_MS;
+  const { rowsAffected } = await client.execute({
+    sql: `UPDATE agent_runs
+          SET status = 'errored',
+              completed_at = ?,
+              error_code = ?,
+              error_detail = ?
+          WHERE id = ?
+            AND status = 'running'
+            AND dispatch_mode = 'background'
+            AND COALESCE(heartbeat_at, started_at) < ?`,
+    args: [
+      completedAt,
+      UNCLAIMED_BACKGROUND_RUN_ERROR_EVENT.errorCode,
+      UNCLAIMED_BACKGROUND_RUN_ERROR_EVENT.details,
+      runId,
+      cutoff,
+    ],
+  });
+  const reaped = (rowsAffected ?? 0) > 0;
+  if (reaped) {
+    await recordRunDiagnostic(
+      runId,
+      RUN_DIAG_STAGE.workerThrew,
+      "unclaimed background dispatch reaped (worker never claimed the run)",
+    );
+    await safeAppendTerminalRunEvent(
+      runId,
+      UNCLAIMED_BACKGROUND_RUN_ERROR_EVENT,
+      "reap-unclaimed-background",
+    );
+  }
+  return reaped;
+}
+
 export async function updateRunStatus(
   runId: string,
   status: "completed" | "errored" | "aborted",
@@ -644,12 +812,14 @@ export async function getRunByThread(
   heartbeatAt: number | null;
   completedAt: number | null;
   lastProgressAt: number | null;
+  dispatchMode: string | null;
+  diagStage: string | null;
 } | null> {
   await ensureRunTables();
   const client = getDbExec();
   const sql = options?.includeTerminal
-    ? `SELECT id, thread_id, turn_id, status, started_at, heartbeat_at, completed_at, last_progress_at FROM agent_runs WHERE thread_id = ? ORDER BY started_at DESC LIMIT 1`
-    : `SELECT id, thread_id, turn_id, status, started_at, heartbeat_at, completed_at, last_progress_at FROM agent_runs WHERE thread_id = ? AND status = 'running' ORDER BY started_at DESC LIMIT 1`;
+    ? `SELECT id, thread_id, turn_id, status, started_at, heartbeat_at, completed_at, last_progress_at, dispatch_mode, diag_stage FROM agent_runs WHERE thread_id = ? ORDER BY started_at DESC LIMIT 1`
+    : `SELECT id, thread_id, turn_id, status, started_at, heartbeat_at, completed_at, last_progress_at, dispatch_mode, diag_stage FROM agent_runs WHERE thread_id = ? AND status = 'running' ORDER BY started_at DESC LIMIT 1`;
   const { rows } = await client.execute({ sql, args: [threadId] });
   if (rows.length === 0) return null;
   const r = rows[0] as {
@@ -661,6 +831,8 @@ export async function getRunByThread(
     heartbeat_at: number | string | null;
     completed_at: number | string | null;
     last_progress_at: number | string | null;
+    dispatch_mode?: string | null;
+    diag_stage?: string | null;
   };
   return {
     id: r.id,
@@ -672,6 +844,8 @@ export async function getRunByThread(
     completedAt: r.completed_at == null ? null : Number(r.completed_at),
     lastProgressAt:
       r.last_progress_at == null ? null : Number(r.last_progress_at),
+    dispatchMode: r.dispatch_mode ?? null,
+    diagStage: r.diag_stage ?? null,
   };
 }
 
@@ -686,6 +860,9 @@ export interface AgentRunSummary {
   lastProgressAt: number | null;
   errorCode: string | null;
   abortReason: string | null;
+  dispatchMode: string | null;
+  /** Last reached `_process-run` worker stage (JSON `{stage,detail?,at}`). */
+  diagStage: string | null;
 }
 
 export async function listRunsForThread(
@@ -696,7 +873,7 @@ export async function listRunsForThread(
   const limit = Math.min(Math.max(options.limit ?? 10, 1), 50);
   const client = getDbExec();
   const { rows } = await client.execute({
-    sql: `SELECT id, thread_id, turn_id, status, started_at, heartbeat_at, completed_at, last_progress_at, error_code, abort_reason
+    sql: `SELECT id, thread_id, turn_id, status, started_at, heartbeat_at, completed_at, last_progress_at, error_code, abort_reason, dispatch_mode, diag_stage
           FROM agent_runs
           WHERE thread_id = ?
           ORDER BY started_at DESC
@@ -715,6 +892,8 @@ export async function listRunsForThread(
       last_progress_at?: number | string | null;
       error_code?: string | null;
       abort_reason?: string | null;
+      dispatch_mode?: string | null;
+      diag_stage?: string | null;
     };
     return {
       id: row.id,
@@ -728,6 +907,8 @@ export async function listRunsForThread(
         row.last_progress_at == null ? null : Number(row.last_progress_at),
       errorCode: row.error_code ?? null,
       abortReason: row.abort_reason ?? null,
+      dispatchMode: row.dispatch_mode ?? null,
+      diagStage: row.diag_stage ?? null,
     };
   });
 }

package/corpus/core/src/server/agent-chat-plugin.ts

@@ -152,6 +152,7 @@ import {
 } from "../a2a/auth-policy.js";
 import {
   AGENT_CHAT_PROCESS_RUN_PATH,
+  extractProcessRunId,
   prepareProcessRunRequest,
 } from "../agent/durable-background.js";
 import {
@@ -7174,6 +7175,14 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
               status: run.status,
               heartbeatAt: run.heartbeatAt,
               lastProgressAt: run.lastProgressAt,
+              // Durable-background diagnostics: how the run was dispatched and
+              // the last reached `_process-run` worker stage (JSON
+              // `{stage,detail?,at}`). Surfaced here so a silent background
+              // worker death is diagnosable from the client WITHOUT the
+              // unreadable Netlify background-function logs — read
+              // `/runs/active?threadId=...` and inspect `diagStage`.
+              dispatchMode: run.dispatchMode ?? null,
+              diagStage: run.diagStage ?? null,
               // Server clock so the client computes "stuck" elapsed time
               // server-relative, immune to client clock skew.
               serverNow: Date.now(),
@@ -7791,6 +7800,19 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
             setResponseStatus(event, 405);
             return { error: "Method not allowed" };
           }
+          // DIAGNOSTIC: load the run-store diagnostic recorder. Each stage we
+          // reach is written onto the run row (diag_stage) so a silent failure
+          // INSIDE the Netlify background function — whose logs we cannot read —
+          // is still diagnosable from the client via /runs/active. Best-effort:
+          // the import + every record call is wrapped so diagnostics can never
+          // break the worker path.
+          const diag = await import("../agent/run-store.js")
+            .then((m) => ({
+              record: m.recordRunDiagnostic,
+              stages: m.RUN_DIAG_STAGE,
+            }))
+            .catch(() => null);
+
           // Consume the body ONCE (h3 v2's web Request stream is single-use).
           let processBody: any;
           try {
@@ -7800,6 +7822,18 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
             return { error: "Invalid request body" };
           }
 
+          // Record "the route handler was entered" against the run BEFORE auth
+          // runs. This is the proof the bg-fn invocation actually reached Nitro
+          // (vs. dying at the function entry / never being invoked). The runId
+          // is parsed without authenticating so we can attach it even on a
+          // subsequent auth failure.
+          const diagRunId = extractProcessRunId(processBody);
+          if (diag && diagRunId) {
+            await diag
+              .record(diagRunId, diag.stages.routeEntered)
+              .catch(() => {});
+          }
+
           // Validate + HMAC-authenticate the self-dispatch and prepare the
           // background-worker body. Pure decision (unit-tested in
           // durable-background.spec.ts); the route only wires it to h3.
@@ -7808,10 +7842,36 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
             getHeader(event, "authorization"),
           );
           if (!prepared.ok) {
+            // DIAGNOSTIC: record the auth/validation failure ONTO the run
+            // before returning the error status. Without this, a 401 (e.g.
+            // A2A_SECRET missing/mismatched in the bg-fn env, or the path not
+            // bypassing session auth) inside the unreadable bg function would
+            // leave the run to time out with NO clue. The detail carries the
+            // status + whether A2A_SECRET is even present in this isolate.
+            if (diag && prepared.runId) {
+              const a2aPresent = Boolean(
+                process.env.A2A_SECRET && process.env.A2A_SECRET.length > 0,
+              );
+              await diag
+                .record(
+                  prepared.runId,
+                  diag.stages.authFailed,
+                  `status=${prepared.status} error=${prepared.error} a2aSecretPresent=${a2aPresent}`,
+                )
+                .catch(() => {});
+            }
             setResponseStatus(event, prepared.status);
             return { error: prepared.error };
           }
 
+          // DIAGNOSTIC: auth + body validation passed. Reaching here proves the
+          // request was authenticated and we are about to invoke the worker.
+          if (diag) {
+            await diag
+              .record(prepared.runId, diag.stages.authPassed)
+              .catch(() => {});
+          }
+
           // Stash the verified+augmented body for the handler — the body stream
           // is already consumed, so the handler reads this instead.
           (event as any).context = (event as any).context ?? {};
@@ -7821,6 +7881,17 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
             return await invokeAgentChatHandler(event);
           } catch (err: any) {
             console.error("[agent-chat] _process-run failed:", err);
+            // DIAGNOSTIC: the worker invocation threw at the route boundary —
+            // record the message so the failure cause is readable client-side.
+            if (diag) {
+              await diag
+                .record(
+                  prepared.runId,
+                  diag.stages.routeThrew,
+                  err instanceof Error ? err.message : String(err),
+                )
+                .catch(() => {});
+            }
             setResponseStatus(event, 500);
             return { error: "process-run failed" };
           }