@agent-native/core 0.122.3 → 0.123.0

package/src/server/agent-chat/prompt-resources.ts

@@ -418,28 +418,120 @@ function promptResourceBlock(input: {
   return `<resource name="${escapeXmlAttribute(input.name)}" scope="${escapeXmlAttribute(input.scope)}"${pathAttr}>\n${content}\n</resource>`;
 }
 
-function selectPromptSectionsWithinBudget(
-  sections: string[],
+/**
+ * One assembled startup-context block plus the governance tier the context
+ * manifest reports for it (`ContextGovernanceTier`). `required` is the tier
+ * that already meant "not opt-out-able" in the manifest; the budget fitter
+ * honours it as "reserve before anything else competes".
+ */
+export interface PromptSection {
+  content: string;
+  governance: ContextGovernanceTier;
+}
+
+export interface SkippedPromptSection {
+  label: string;
+  chars: number;
+}
+
+export interface PromptSectionBudgetResult {
+  sections: string[];
+  skipped: SkippedPromptSection[];
+  /** Chars by which required sections alone exceeded `maxChars`, else 0. */
+  overflowChars: number;
+}
+
+const PROMPT_SECTION_SEPARATOR = "\n\n";
+const TRIM_NOTE_LABELS_MAX_CHARS = 300;
+const TRIM_NOTE_MAX_CHARS = 700;
+
+function promptSectionLabel(content: string): string {
+  const open = /^<([a-z][a-z0-9-]*)\b([^>]*)>/i.exec(content.trimStart());
+  if (!open) return "unlabelled context section";
+  const attrs = open[2] ?? "";
+  const name = xmlAttribute(attrs, "name") ?? xmlAttribute(attrs, "id");
+  const scope = xmlAttribute(attrs, "scope");
+  if (name) return scope ? `${name} (${scope})` : name;
+  return scope ? `${open[1]} (${scope})` : (open[1] ?? "context section");
+}
+
+function promptBudgetTrimNote(
+  skipped: SkippedPromptSection[],
   maxChars: number,
-): string[] {
-  const omissionNote = `<context-budget-note>Some startup context sections were omitted to keep the first model request responsive. Use \`resources\` with \`action: "list"\` or \`"read"\`, \`docs-search\`, and \`tool-search\` to retrieve relevant depth on demand.</context-budget-note>`;
-  const contentBudget = Math.max(0, maxChars - omissionNote.length - 2);
-  const selected: string[] = [];
-  let used = 0;
-  let omitted = 0;
-
-  for (const section of sections) {
-    const separatorChars = selected.length > 0 ? 2 : 0;
-    if (used + separatorChars + section.length <= contentBudget) {
-      selected.push(section);
-      used += separatorChars + section.length;
+): string {
+  const labels = compactPromptLine(
+    skipped.map((section) => section.label).join(", "),
+    TRIM_NOTE_LABELS_MAX_CHARS,
+  );
+  return `<context-budget-note>Your startup context was trimmed: ${skipped.length} section(s) did not fit the ${maxChars.toLocaleString()}-character first-request budget and were omitted (${labels}). Treat them as unread, not as absent — use \`resources\` with \`action: "list"\` or \`"read"\`, \`docs-search\`, and \`tool-search\` before telling the user something does not exist.</context-budget-note>`;
+}
+
+/**
+ * Fits assembled startup context into `maxChars`, reserving `required`
+ * sections before discretionary ones compete for the remainder, and reporting
+ * every omission so an over-budget request is never silent.
+ *
+ * Required sections are never truncated and never dropped: a half-rendered
+ * list of workspace apps or governance rules reads to the model as a complete
+ * one, which is worse than an explicit note that a section is missing. If they
+ * alone exceed the budget, the budget is exceeded deliberately, every
+ * discretionary section is dropped, and `overflowChars` reports by how much.
+ */
+export function selectPromptSectionsWithinBudget(
+  sections: PromptSection[],
+  maxChars: number,
+): PromptSectionBudgetResult {
+  const required = sections.filter(
+    (section) => section.governance === "required",
+  );
+  const keep = new Set<number>();
+  const skipped: SkippedPromptSection[] = [];
+  let used = required.reduce(
+    (total, section) => total + section.content.length,
+    0,
+  );
+  let count = required.length;
+  const requiredFit =
+    used + count * PROMPT_SECTION_SEPARATOR.length + TRIM_NOTE_MAX_CHARS <=
+    maxChars;
+
+  for (const [index, section] of sections.entries()) {
+    if (section.governance === "required") {
+      keep.add(index);
+      continue;
+    }
+    const projected =
+      used +
+      section.content.length +
+      (count + 1) * PROMPT_SECTION_SEPARATOR.length +
+      TRIM_NOTE_MAX_CHARS;
+    if (requiredFit && projected <= maxChars) {
+      keep.add(index);
+      used += section.content.length;
+      count++;
     } else {
-      omitted++;
+      skipped.push({
+        label: promptSectionLabel(section.content),
+        chars: section.content.length,
+      });
     }
   }
 
-  if (omitted > 0) selected.push(omissionNote);
-  return selected;
+  const selected = sections
+    .filter((_section, index) => keep.has(index))
+    .map((section) => section.content);
+  if (skipped.length > 0) {
+    selected.push(promptBudgetTrimNote(skipped, maxChars));
+  }
+
+  const totalChars =
+    selected.reduce((total, section) => total + section.length, 0) +
+    Math.max(0, selected.length - 1) * PROMPT_SECTION_SEPARATOR.length;
+  return {
+    sections: selected,
+    skipped,
+    overflowChars: requiredFit ? 0 : Math.max(0, totalChars - maxChars),
+  };
 }
 
 function isAutoLoadedInstructionPath(path: string): boolean {
@@ -738,7 +830,19 @@ export async function loadResourcesForPrompt(
 ): Promise<string> {
   await ensurePersonalDefaults(owner);
 
-  const sections: string[] = [];
+  const sections: PromptSection[] = [];
+  const addSection = (
+    content: string | null | undefined,
+    governance: ContextGovernanceTier = "inherited",
+  ): void => {
+    if (content?.trim()) sections.push({ content, governance });
+  };
+  const addSections = (
+    blocks: string[],
+    governance: ContextGovernanceTier = "inherited",
+  ): void => {
+    for (const block of blocks) addSection(block, governance);
+  };
   const promptResourceMaxChars = compact
     ? COMPACT_PROMPT_RESOURCE_MAX_CHARS
     : SHARED_PROMPT_RESOURCE_MAX_CHARS;
@@ -760,7 +864,7 @@ export async function loadResourcesForPrompt(
         readHint:
           'Use docs-search --slug "agents-workspace" to read the full workspace AGENTS.md.',
       });
-      if (block) sections.push(block);
+      addSection(block, "required");
     }
 
     // 2. Template AGENTS.md — always included (critical template instructions).
@@ -774,7 +878,7 @@ export async function loadResourcesForPrompt(
         readHint:
           'Use docs-search --slug "agents-template" to read the full template AGENTS.md.',
       });
-      if (block) sections.push(block);
+      addSection(block);
     }
 
     // In compact mode, skip the full skills block — the agent can use
@@ -783,7 +887,7 @@ export async function loadResourcesForPrompt(
     const runtimeSkills = getRuntimeSkills(bundle);
     if (!compact) {
       const skillsBlock = generateSkillsPromptBlock(bundle);
-      if (skillsBlock) sections.push(skillsBlock);
+      addSection(skillsBlock);
     } else if (runtimeSkills.length > 0) {
       const listedSkills = runtimeSkills.slice(0, PROMPT_SKILL_SUMMARY_LIMIT);
       const lines = listedSkills.map((s) => {
@@ -797,7 +901,7 @@ export async function loadResourcesForPrompt(
           `- ...${runtimeSkills.length - listedSkills.length} more codebase skills. Use \`docs-search --query "<topic>"\` to discover the relevant one.`,
         );
       }
-      sections.push(
+      addSection(
         `<skills-summary>\nCodebase skills bundled from \`.agents/skills/\` (or legacy \`.agent/skills/\`) are available as docs-search pages. Do not use MCP resource reads for these skills.\n\n${lines.join("\n")}\n</skills-summary>`,
       );
     }
@@ -811,14 +915,14 @@ export async function loadResourcesForPrompt(
     "workspace",
     promptResourceMaxChars,
   );
-  if (workspaceAgents) sections.push(workspaceAgents);
-  sections.push(
-    ...(await loadInstructionResourcesForPrompt(
+  addSection(workspaceAgents);
+  addSections(
+    await loadInstructionResourcesForPrompt(
       WORKSPACE_OWNER,
       "workspace-instruction",
       promptResourceMaxChars,
       compact,
-    )),
+    ),
   );
 
   const organizationOwner = sharedResourceOwner(orgId);
@@ -831,16 +935,16 @@ export async function loadResourcesForPrompt(
     organizationOwner === SHARED_OWNER ? "shared" : "app-default",
     promptResourceMaxChars,
   );
-  if (appDefaultAgents) sections.push(appDefaultAgents);
-  sections.push(
-    ...(await loadInstructionResourcesForPrompt(
+  addSection(appDefaultAgents);
+  addSections(
+    await loadInstructionResourcesForPrompt(
       SHARED_OWNER,
       organizationOwner === SHARED_OWNER
         ? "shared-instruction"
         : "app-default-instruction",
       promptResourceMaxChars,
       compact,
-    )),
+    ),
   );
 
   // 5. Active organization resources. These are the durable team rules and
@@ -851,14 +955,14 @@ export async function loadResourcesForPrompt(
       "organization",
       promptResourceMaxChars,
     );
-    if (organizationAgents) sections.push(organizationAgents);
-    sections.push(
-      ...(await loadInstructionResourcesForPrompt(
+    addSection(organizationAgents);
+    addSections(
+      await loadInstructionResourcesForPrompt(
         organizationOwner,
         "organization-instruction",
         promptResourceMaxChars,
         compact,
-      )),
+      ),
     );
   }
 
@@ -870,19 +974,20 @@ export async function loadResourcesForPrompt(
       "personal",
       promptResourceMaxChars,
     );
-    if (personalAgents) sections.push(personalAgents);
-    sections.push(
-      ...(await loadInstructionResourcesForPrompt(
+    addSection(personalAgents, "user");
+    addSections(
+      await loadInstructionResourcesForPrompt(
         owner,
         "personal-instruction",
         promptResourceMaxChars,
         compact,
-      )),
+      ),
+      "user",
     );
   }
 
   const resourceSkillsBlock = await loadResourceSkillsPromptBlock(owner, orgId);
-  if (resourceSkillsBlock) sections.push(resourceSkillsBlock);
+  addSection(resourceSkillsBlock);
 
   let sharedLearnings: Awaited<ReturnType<typeof resourceGetByPath>> = null;
   try {
@@ -906,10 +1011,13 @@ export async function loadResourcesForPrompt(
         content: sharedLearnings.content,
         maxChars: COMPACT_PROMPT_RESOURCE_MAX_CHARS,
       });
-      if (block) sections.push(block);
+      addSection(block);
     }
-    sections.push(
+    // The pointer to on-demand learnings/memory must survive trimming: without
+    // it the agent has no way to learn those scopes exist at all.
+    addSection(
       `<context-note>Organization learnings above and your personal memory (memory/MEMORY.md) are available via the \`resources\` tool. Save durable team facts and routing conventions to shared LEARNINGS.md; keep personal preferences in save-memory.</context-note>`,
+      "required",
     );
   } else {
     // LEARNINGS.md from SQL (template-level instructions are in AGENTS.md
@@ -923,7 +1031,7 @@ export async function loadResourcesForPrompt(
         content: sharedLearnings.content,
         maxChars: SHARED_PROMPT_RESOURCE_MAX_CHARS,
       });
-      if (block) sections.push(block);
+      addSection(block);
     }
 
     // 3. Personal memory index (skip if owner is the shared sentinel).
@@ -941,7 +1049,7 @@ export async function loadResourcesForPrompt(
             content: memoryIndex.content,
             maxChars: SHARED_PROMPT_RESOURCE_MAX_CHARS,
           });
-          if (block) sections.push(block);
+          addSection(block, "user");
         }
       } catch {}
     }
@@ -951,28 +1059,28 @@ export async function loadResourcesForPrompt(
     WORKSPACE_OWNER,
     "workspace",
   );
-  if (workspaceResourceIndex) sections.push(workspaceResourceIndex);
+  addSection(workspaceResourceIndex);
 
   const appDefaultResourceIndex = await loadResourceIndexForPrompt(
     SHARED_OWNER,
     "shared",
   );
-  if (appDefaultResourceIndex) sections.push(appDefaultResourceIndex);
+  addSection(appDefaultResourceIndex);
   if (organizationOwner !== SHARED_OWNER) {
     const organizationResourceIndex = await loadResourceIndexForPrompt(
       organizationOwner,
       "shared",
     );
-    if (organizationResourceIndex) sections.push(organizationResourceIndex);
+    addSection(organizationResourceIndex);
   }
 
-  sections.push(
-    ...(await loadPromptContextProviderBlocks({
+  addSections(
+    await loadPromptContextProviderBlocks({
       owner,
       compact,
       selfAppId,
       orgId,
-    })),
+    }),
   );
 
   try {
@@ -982,8 +1090,12 @@ export async function loadResourcesForPrompt(
         (agent) =>
           `- ${agent.name} (${agent.id}) — ${agent.description || "Connected A2A app"}`,
       );
-      sections.push(
-        `<available-apps>\nWorkspace apps available over A2A/call-agent:\n${lines.join("\n")}\n\nUse \`call-agent\` with the app id when another app owns the work or data. Use tool-search or app-specific actions for details only when needed.\n</available-apps>`,
+      // Nothing else in the prompt or the initial tool surface tells the agent
+      // which peer apps exist, so this block is not droppable: without it the
+      // agent reports cross-app work as impossible instead of delegating.
+      addSection(
+        `<available-apps>\nWorkspace apps available over A2A/call-agent:\n${lines.join("\n")}\n\nUse \`call-agent\` with the app id when another app owns the work or data. Use tool-search or app-specific actions for details only when needed.\n\nThese one-liners are the only cross-app detail in this prompt. Before building a capability another app may already own, before telling the user what is or is not possible across apps, and whenever the user asks which app to use, call \`describe-workspace-apps\` — it reads each peer's live agent card and returns their exact callable actions. Never hand-maintain a list of workspace apps in code or docs; it goes stale silently.\n</available-apps>`,
+        "required",
       );
     }
   } catch {
@@ -991,12 +1103,26 @@ export async function loadResourcesForPrompt(
   }
 
   if (sections.length === 0) return "";
-  const selectedSections = compact
-    ? selectPromptSectionsWithinBudget(
-        sections,
-        COMPACT_PROMPT_RESOURCES_TOTAL_MAX_CHARS,
-      )
-    : sections;
+  let selectedSections = sections.map((section) => section.content);
+  if (compact) {
+    const budget = selectPromptSectionsWithinBudget(
+      sections,
+      COMPACT_PROMPT_RESOURCES_TOTAL_MAX_CHARS,
+    );
+    selectedSections = budget.sections;
+    if (budget.skipped.length > 0) {
+      console.warn(
+        `[agent-native] startup context exceeded the ${COMPACT_PROMPT_RESOURCES_TOTAL_MAX_CHARS.toLocaleString()}-character compact budget for ${selfAppId ?? "app"}; omitted ${budget.skipped.length} discretionary section(s): ${budget.skipped
+          .map((section) => `${section.label} (${section.chars} chars)`)
+          .join(", ")}`,
+      );
+    }
+    if (budget.overflowChars > 0) {
+      console.warn(
+        `[agent-native] required startup context alone exceeds the compact budget by ${budget.overflowChars.toLocaleString()} characters for ${selfAppId ?? "app"}; sending it over budget rather than truncating required context. Shrink workspace-core AGENTS.md or reduce discovered workspace apps.`,
+      );
+    }
+  }
   return (
     "\n\nThe following resources contain template-specific instructions and user context. Use the information in them to help the user.\n\n" +
     selectedSections.join("\n\n")

package/src/server/agent-chat/script-entries.ts

@@ -10,6 +10,7 @@ import type { DatabaseToolsMode } from "../../scripts/db/tool-mode.js";
 import { dbExecToolParameters } from "../../scripts/db/tool-schemas.js";
 import { captureCliOutput } from "../cli-capture.js";
 import {
+  getAmbientUserEmail,
   getRequestOrgId,
   getRequestRunContext,
   getRequestUserEmail,
@@ -480,7 +481,7 @@ export async function createResourceScriptEntries(): Promise<
                 ? store.sharedResourceOwner(getRequestOrgId())
                 : (getRequestRunContext()?.owner ??
                   getRequestUserEmail() ??
-                  process.env.AGENT_USER_EMAIL);
+                  getAmbientUserEmail());
             if (!owner) {
               return "Error: promote requires an authenticated user";
             }
@@ -782,15 +783,27 @@ export async function createAgentLoopSettingsScriptEntries(): Promise<
 export async function createCallAgentScriptEntry(
   selfAppId?: string,
 ): Promise<Record<string, ActionEntry>> {
+  const entries: Record<string, ActionEntry> = {};
+
   try {
     const mod = await import("../../scripts/call-agent.js");
-    return {
-      "call-agent": {
-        tool: mod.tool,
-        run: (args, context) => mod.run(args, context, selfAppId),
-      },
+    entries["call-agent"] = {
+      tool: mod.tool,
+      run: (args, context) => mod.run(args, context, selfAppId),
     };
   } catch {
-    return {};
+    // A missing built-in leaves the rest of the toolset usable.
   }
+
+  try {
+    const mod = await import("../../scripts/describe-workspace-apps.js");
+    entries["describe-workspace-apps"] = {
+      tool: mod.tool,
+      run: (args, context) => mod.run(args, context, selfAppId),
+    };
+  } catch {
+    // A missing built-in leaves the rest of the toolset usable.
+  }
+
+  return entries;
 }

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

@@ -65,6 +65,7 @@ import {
   listAgentEngines,
   registerBuiltinEngines,
 } from "../agent/engine/index.js";
+import { SYSTEM_PROMPT_CACHE_SPLIT } from "../agent/engine/prompt-cache.js";
 import type { EngineMessage } from "../agent/engine/types.js";
 import {
   createProductionAgentHandler,
@@ -1585,12 +1586,14 @@ export function createAgentChatPlugin(
           const runtimeContext = runtimeContextForEvent(context.event);
           const systemPrompt = devActive
             ? devPrompt +
+              SYSTEM_PROMPT_CACHE_SPLIT +
               resources +
               schemaBlock +
               extra +
               modelOverlay +
               runtimeContext
             : basePrompt +
+              SYSTEM_PROMPT_CACHE_SPLIT +
               resources +
               schemaBlock +
               extra +
@@ -1791,6 +1794,10 @@ export function createAgentChatPlugin(
               runSoftTimeoutMs: options?.runSoftTimeoutMs,
             },
             {
+              // Without the hosted default an app that never sets
+              // `runSoftTimeoutMs` resolves to 0 and the wrapper degrades to a
+              // bare `runAgentLoop` — no resume at all on a delegated turn.
+              useHostedDefault: true,
               backgroundFunction:
                 options?.durableBackgroundRuns === true &&
                 isInBackgroundFunctionRuntime(),
@@ -2073,10 +2080,12 @@ export function createAgentChatPlugin(
             // this plugin (A2A above, prod/anonymous/dev handlers below).
             const systemPrompt = devActiveMcp
               ? mcpDevPrompt +
+                SYSTEM_PROMPT_CACHE_SPLIT +
                 resources +
                 schemaBlock +
                 buildRuntimeContextPrompt()
               : basePrompt +
+                SYSTEM_PROMPT_CACHE_SPLIT +
                 resources +
                 schemaBlock +
                 buildRuntimeContextPrompt();
@@ -2126,6 +2135,9 @@ export function createAgentChatPlugin(
                 runSoftTimeoutMs: options?.runSoftTimeoutMs,
               },
               {
+                // Same as the A2A call site: without this a hosted app that
+                // never configured `runSoftTimeoutMs` gets no resume at all.
+                useHostedDefault: true,
                 backgroundFunction:
                   options?.durableBackgroundRuns === true &&
                   isInBackgroundFunctionRuntime(),
@@ -2928,6 +2940,8 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
           // less-stable content would still invalidate the cached prefix for
           // everything that follows it — putting it last means a day
           // rollover invalidates as little of the prefix as possible.
+          // `SYSTEM_PROMPT_CACHE_SPLIT` marks where the cacheable prefix ends,
+          // so everything after it can change without a cache write.
           if (leanPrompt) {
             const leanRunPolicyPrompt = buildLeanRunPolicyPrompt(
               codeEditingSurfaceRestriction,
@@ -2947,6 +2961,7 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
             return setSystemPromptOnContext(
               leanBasePrompt +
                 leanRunPolicyPrompt +
+                SYSTEM_PROMPT_CACHE_SPLIT +
                 extra +
                 modelOverlay +
                 runtimeContext,
@@ -2978,6 +2993,7 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
           });
           return setSystemPromptOnContext(
             basePrompt +
+              SYSTEM_PROMPT_CACHE_SPLIT +
               resources +
               schemaBlock +
               codeEditingSurfaceRestriction +
@@ -5828,7 +5844,18 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                 const {
                   listUnclaimedBackgroundRunRows,
                   shouldRedispatchUnclaimedBackgroundRun,
+                  reapAllStaleRuns,
                 } = await import("../agent/run-store.js");
+                // The unclaimed-background sweep below only matches
+                // dispatch_mode='background' — handoffs a worker never
+                // claimed. Once a worker CLAIMS a row nothing periodic looked
+                // at it again, so a dead producer was only reaped when some
+                // client request path or an unrelated run's cleanup happened
+                // to notice (prod: 24 minutes after the last heartbeat,
+                // against a 45s window). `reapAllStaleRuns` is per-row,
+                // idempotent, re-checks staleness at UPDATE time and honours
+                // the in-flight grace, so it is safe on this cadence.
+                await reapAllStaleRuns().catch(() => {});
                 let rows: { id: string; startedAt: number }[];
                 try {
                   rows = await listUnclaimedBackgroundRunRows();

package/src/server/auth.ts

@@ -83,6 +83,12 @@ import { readBody } from "../server/h3-helpers.js";
 import { putSetting } from "../settings/store.js";
 import { resolveSsrCacheHeaders } from "../shared/cache-control.js";
 import { extractOAuthStateAppId } from "../shared/oauth-state.js";
+import {
+  SIGN_IN_CONTINUATION_PARAM,
+  SIGN_IN_LEGACY_RETURN_PARAM,
+  normalizeAppPath,
+  signInJourney,
+} from "../shared/sign-in-journey.js";
 import {
   AGENT_NATIVE_SOCIAL_IMAGE_ALT,
   AGENT_NATIVE_SOCIAL_IMAGE_HEIGHT,
@@ -535,33 +541,19 @@ export function isDevEnvironment(): boolean {
 }
 
 /**
- * Validate a `?return=` URL for the /_agent-native/sign-in entrypoint.
- *
- * Parses the candidate against a sentinel base origin; any input that
- * resolves to a different origin (network-path references, absolute URLs,
- * `data:` / `javascript:` schemes, backslash-bypass tricks WHATWG normalises
- * to `//`) gets rejected and falls back to "/". Control characters are
- * stripped up front to defend against header-injection. Returns the
- * normalised path the parser produced — never the raw input.
+ * @deprecated Prefer `normalizeAppPath` from `@agent-native/core/shared`,
+ * which returns `null` for a rejected path instead of a `"/"` a caller cannot
+ * distinguish from a genuine request for the home page.
  *
- * Exported for unit tests.
+ * Retained because eight template call sites use it for PROVIDER OAuth
+ * returns (Google Calendar, Slack, Google Docs, …), which is a legitimately
+ * separate concern from the sign-in journey. Deliberately passes NO base path:
+ * provider return targets are not guaranteed to be base-path prefixed, and
+ * tightening that here would silently collapse working provider returns to
+ * "/" on base-path deploys. Base-path containment belongs to `signInJourney`.
  */
 export function safeReturnPath(raw: string | null | undefined): string {
-  if (!raw) return "/";
-  if (/[\x00-\x1f]/.test(raw)) return "/";
-  try {
-    const parsed = new URL(raw, "http://safe-base.invalid");
-    if (parsed.origin !== "http://safe-base.invalid") return "/";
-    // Never return to the sign-in entry point itself. A `return` that resolves
-    // back to `…/_agent-native/sign-in` re-enters the redirect loop — each hop
-    // nests the prior sign-in URL as a fresh `?return=`. Collapse it to "/" so
-    // the post-sign-in 302 lands on the app, not another sign-in page. Matches
-    // with or without an app base-path prefix (`/<app>/_agent-native/sign-in`).
-    if (parsed.pathname.endsWith("/_agent-native/sign-in")) return "/";
-    return parsed.pathname + parsed.search + parsed.hash;
-  } catch {
-    return "/";
-  }
+  return normalizeAppPath(raw) ?? "/";
 }
 
 /**
@@ -1915,14 +1907,21 @@ function createAuthGuardFn(): (
       // reaches this explicit entrypoint after discovering there is no
       // session; only a fresh local development DB can take this redirect.
       if (getMethod(event) === "GET") {
-        const queryStr = queryStart >= 0 ? url.slice(queryStart + 1) : "";
-        const safeReturn = safeReturnPath(
-          new URLSearchParams(queryStr).get("return"),
-        );
-        const autoSession = await maybeAutoCreateDevSession(
-          event,
-          safeReturn === "/" ? getAppBasePath() || "/" : safeReturn,
+        const query = new URLSearchParams(
+          queryStart >= 0 ? url.slice(queryStart + 1) : "",
         );
+        // `?return=` is read as a fallback FOREVER. Generated apps in the wild
+        // hand-write `/_agent-native/sign-in?return=…` and cannot be upgraded;
+        // dropping the fallback would send them all to "/" — a UX quirk no
+        // test would catch. New producers emit `c`; only NEW `?return=`
+        // producers are forbidden, never this consumer.
+        const { resumeHref } = signInJourney({
+          at: url,
+          continuation: query.get(SIGN_IN_CONTINUATION_PARAM),
+          legacyReturn: query.get(SIGN_IN_LEGACY_RETURN_PARAM),
+          basePath: getAppBasePath(),
+        });
+        const autoSession = await maybeAutoCreateDevSession(event, resumeHref);
         if (autoSession) return autoSession;
       }
       return loginHtmlResponse(loginHtml, event);
@@ -2001,7 +2000,14 @@ function createAuthGuardFn(): (
       // dev account, so production SSR remains one cacheable anonymous shell
       // and explicit sign-out still works.
       if (getMethod(event) === "GET") {
-        const autoSession = await maybeAutoCreateDevSession(event, url);
+        // Same source of truth as the sign-in entry above. This used to pass
+        // the raw request URL, which made one decision with two sources — the
+        // shape the sign-in unification exists to delete.
+        const { resumeHref } = signInJourney({
+          at: url,
+          basePath: getAppBasePath(),
+        });
+        const autoSession = await maybeAutoCreateDevSession(event, resumeHref);
         if (autoSession) return autoSession;
       }
       return;