Cursor: Apply local changes for cloud agent

docs/DISCOVERY.md

@@ -74,11 +74,25 @@ SearXNG, Fantastic Jobs, Firecrawl Search, and Hirebase posted dates all pass th
 - **Demote** weak/unclear regional hits pre-LLM into the score shortlist; **hard-drop** only high-confidence onsite/hybrid/inaccessible rows with rich body (≥400 chars). No “thinner than usual” stigma for intentional FJ + Firecrawl + SearXNG stacks.
 - Hard WFA accessibility gate post-score.
 
-## Search angles (reasoned vs deterministic)
+## Nested research (where / how / execute)
 
-`discover_jobs` is a thick tool: one agent call runs several internal angles. When the planner LLM can author `searchAngles`, those become hypotheses (ATS-first, work-from-anywhere, visa, skill adjacency). **Angle 0 always searches the tool’s primary intent**; later angles consume the hypotheses. `focus` compiles into query bias (`forceVisaQuery`, ATS `angleIndex` 0, WFA phrasing, semantic broadening) — it is not decorative.
+Discovery is three layers — not a playlist of queries:
 
-When the planner LLM is down (common on unpublished Groq slugs or exhausted OpenRouter), the tool still runs **built-in** ATS-first + WFA + visa (if the profile wants sponsorship) + skill-adjacency angles. Search stays thorough; it does not collapse to a single deterministic query.
+| Layer | Question | Owner |
+|-------|----------|--------|
+| **Outer** | Where should I look? | Chat agent + outcome policy — research *avenues* |
+| **Inner** | How should I look *here*? | One `discover_jobs` call — Search → inspect → reflect → adapt angles |
+| **Provider** | How do I execute reliably? | Dual planners compile intent/focus/pivot → Fantastic / Firecrawl / SearXNG (etc.) — agents never author provider query strings |
+
+**One `discover_jobs` = one avenue.** Optional `searchAngles` are hypotheses for the inner loop only. After each angle, structured `AngleObservation`s feed an LLM adapter (`planNextSearchAngle`); on failure, deterministic pivots remain. When the avenue stops, an `AvenueObservation` (`strategyTrace`, quality, geography/role-fit signals, promising terms) crosses to the outer loop.
+
+**Outer reflection** compares `avenueSummaries` and may start a different avenue (capped by `DISCOVER_OUTER_STRATEGY_RETRIES`, default 2) or present findings. Outcome policy may also nudge `recency="48h"` when listings were found but none scored on a 24h window.
+
+**Hard bounds** (env-overridable): `PERSIST_MAX_PIVOTS`, `PERSIST_MAX_MINUTES`, `PERSIST_TARGET_STRONG`, `PERSIST_DIMINISHING`, `DISCOVER_OUTER_STRATEGY_RETRIES`, `DISCOVER_INNER_PLANNER_TIMEOUT_MS`. Neither loop is unconstrained.
+
+### Legacy note (searchAngles)
+
+Angle 0 still searches the tool’s primary `intent`. `focus` compiles into query bias (`forceVisaQuery`, ATS `angleIndex`, WFA phrasing, semantic broadening). When the planner LLM is down, built-in ATS-first + WFA + visa + skill-adjacency seeds keep the avenue thorough; they are candidates, not a forced playlist.
 
 ## Seen listings (TTL by source)
 

lib/agent-chat/autonomy-policy.selftest.ts

@@ -3,11 +3,14 @@ import assert from "node:assert/strict";
 import {
   BROADEN_RECENCY_USER_LINE,
   broadenRecencyUserLine,
+  discoverOuterStrategyRetries,
   evaluateDiscoverOutcomePolicy,
   humanizeToolError,
   INFRA_FETCH_FAILED_MESSAGE,
   isColloquialResumeMessage,
   PAGE_FETCH_FAILED_MESSAGE,
+  RETRY_STRATEGY_USER_LINE,
+  retryStrategyUserLine,
   shouldTreatAsHardSearchFailure,
 } from "@/lib/agent-chat/autonomy-policy";
 import { shouldRefundDiscoverCredits, shouldRefundTimedOutDiscoverWithoutRun } from "@/lib/digest-admin-errors";
@@ -241,6 +244,56 @@ function testOutcomePolicy(): void {
     }),
     { action: "none" },
   );
+
+  // Avenue exhausted + weak strong yield → outer strategy retry
+  assert.deepEqual(
+    evaluateDiscoverOutcomePolicy({
+      totalDiscovered: 40,
+      totalScored: 2,
+      strongMatchCount: 1,
+      stoppedBecause: "diminishing",
+      internalPivotsExhausted: true,
+      toolCallsUsed: 1,
+      maxToolCalls: 10,
+      autoCycleCount: 0,
+      currentRecency: "48h",
+    }),
+    { action: "retry_strategy" },
+  );
+  assert.ok(RETRY_STRATEGY_USER_LINE.includes("fundamentally different"));
+  assert.ok(retryStrategyUserLine("run-xyz").includes("seedFromRunId=\"run-xyz\""));
+  assert.ok(discoverOuterStrategyRetries() >= 0);
+
+  // Target strong reached → no strategy retry
+  assert.deepEqual(
+    evaluateDiscoverOutcomePolicy({
+      totalDiscovered: 40,
+      totalScored: 6,
+      strongMatchCount: 6,
+      stoppedBecause: "target_strong",
+      toolCallsUsed: 1,
+      maxToolCalls: 10,
+      autoCycleCount: 0,
+      currentRecency: "48h",
+    }),
+    { action: "none" },
+  );
+
+  // Outer retry budget exhausted
+  assert.deepEqual(
+    evaluateDiscoverOutcomePolicy({
+      totalDiscovered: 40,
+      totalScored: 1,
+      strongMatchCount: 0,
+      stoppedBecause: "max_pivots",
+      internalPivotsExhausted: true,
+      toolCallsUsed: 2,
+      maxToolCalls: 10,
+      autoCycleCount: discoverOuterStrategyRetries(),
+      currentRecency: "48h",
+    }),
+    { action: "none" },
+  );
 }
 
 function testRefundDiscoverCredits(): void {

lib/agent-chat/autonomy-policy.ts

@@ -21,6 +21,29 @@ export function broadenRecencyUserLine(seedFromRunId?: string): string {
   );
 }
 
+export const RETRY_STRATEGY_USER_LINE =
+  "[System] Outcome policy: the previous discover_jobs avenue exhausted with weak yield. " +
+  "Compare avenueSummaries / avenueObservation / lastReflection. " +
+  "Call discover_jobs once more with a fundamentally different approach (new avenue intent), not a clone of the last intent. " +
+  "Optional searchAngles are hypotheses for the inner loop only. Prefer seedFromRunId when available. " +
+  "Do not write raw provider queries.";
+
+/** Build the outer-avenue retry nudge, optionally pinning seedFromRunId. */
+export function retryStrategyUserLine(seedFromRunId?: string): string {
+  if (!seedFromRunId?.trim()) return RETRY_STRATEGY_USER_LINE;
+  return (
+    `${RETRY_STRATEGY_USER_LINE} ` +
+    `Pass seedFromRunId=\"${seedFromRunId.trim()}\" so work continues on the existing durable run.`
+  );
+}
+
+/** Max outer avenue switches per turn (env DISCOVER_OUTER_STRATEGY_RETRIES, default 2). */
+export function discoverOuterStrategyRetries(): number {
+  const n = parseInt(String(process.env.DISCOVER_OUTER_STRATEGY_RETRIES ?? "2").trim(), 10);
+  if (!Number.isFinite(n)) return 2;
+  return Math.min(4, Math.max(0, n));
+}
+
 export const INFRA_FETCH_FAILED_MESSAGE =
   "Background search couldn't start. Continuing with results I already have.";
 
@@ -74,38 +97,48 @@ export function shouldTreatAsHardSearchFailure(ctx: SoftFailureContext): boolean
 export type DiscoverOutcomeInput = {
   totalDiscovered: number;
   totalScored: number;
+  /** Strong matches from this avenue (preferred over totalScored for strategy retry). */
+  strongMatchCount?: number;
   timedOut?: boolean;
   backgroundContinued?: boolean;
   stoppedBecause?: string;
+  internalPivotsExhausted?: boolean;
   toolCallsUsed: number;
   maxToolCalls: number;
   autoCycleCount: number;
   /** Recency already used for this discover; 48h is the ceiling — do not broaden again. */
   currentRecency?: string;
+  /** Strong-match bar for considering an avenue successful (default 5). */
+  targetStrong?: number;
 };
 
 export type DiscoverOutcomeAction =
   | { action: "none" }
   | { action: "broaden_recency" }
+  | { action: "retry_strategy" }
   | { action: "await_resume" };
 
 /**
  * Server-side outcome policy after discover_jobs.
  * - discovered>0 / scored=0 on 24h → one 48h recency retry (budget permitting)
- * - already 48h (or unset, which normalizes to default 48h) → none
+ * - already 48h (or unset, which normalizes to default 48h) → none for recency
+ * - avenue exhausted + weak strong yield → capped outer avenue switch (retry_strategy)
  * - timeout + background continued → pause for durable resume (not a hard error)
  */
 export function evaluateDiscoverOutcomePolicy(input: DiscoverOutcomeInput): DiscoverOutcomeAction {
   const {
     totalDiscovered,
     totalScored,
+    strongMatchCount,
     timedOut,
     backgroundContinued,
     stoppedBecause,
+    internalPivotsExhausted,
     toolCallsUsed,
     maxToolCalls,
     autoCycleCount,
     currentRecency,
+    targetStrong = 5,
   } = input;
 
   if (timedOut && backgroundContinued) {
@@ -128,5 +161,26 @@ export function evaluateDiscoverOutcomePolicy(input: DiscoverOutcomeInput): Disc
     return { action: "broaden_recency" };
   }
 
+  const strong =
+    typeof strongMatchCount === "number" && Number.isFinite(strongMatchCount) ?
+      Math.max(0, strongMatchCount)
+    : 0;
+  const avenueExhausted =
+    internalPivotsExhausted === true ||
+    stoppedBecause === "max_pivots" ||
+    stoppedBecause === "diminishing" ||
+    stoppedBecause === "time";
+  const outerCap = discoverOuterStrategyRetries();
+  if (
+    avenueExhausted &&
+    strong < targetStrong &&
+    autoCycleCount < outerCap &&
+    budgetLeft &&
+    !timedOut &&
+    stoppedBecause !== "target_strong"
+  ) {
+    return { action: "retry_strategy" };
+  }
+
   return { action: "none" };
 }

lib/agent-chat/discover-jobs-tool.ts

@@ -93,6 +93,14 @@ import { getEmbedding } from "@/lib/embeddings";
 import { getVectorIndex, isVectorEnabled } from "@/lib/vector-store";
 import crypto from "crypto";
 import type { ReasonedSearchAngle } from "@/lib/search-runs/types";
+import {
+  buildAngleObservation,
+  buildAvenueObservation,
+  type AngleObservation,
+  type AngleObservationSource,
+  type AvenueObservation,
+} from "@/lib/agent-chat/discovery-observations";
+import { planNextSearchAngle } from "@/lib/agent-chat/plan-next-search-angle";
 
 /** Max listings sent to Groq/OpenRouter scoring per discover angle (ranked, lane-quota'd). */
 function discoverMaxLlmScoreListings(): number {
@@ -281,6 +289,10 @@ export interface DiscoverJobsSuccessResult {
   /** True when persistence loop finished without early strong target; model may show possible matches. */
   internalPivotsExhausted?: boolean;
   lastReflection?: AngleReflection;
+  /** Ordered inner-loop observations for this avenue (outer reflection input). */
+  strategyTrace?: AngleObservation[];
+  /** Rolled-up avenue summary for outer strategy. */
+  avenueObservation?: AvenueObservation;
   /** Durable search run id when Redis checkpoints are enabled. */
   searchRunId?: string;
   /** True when remaining work was handed to a background worker. */
@@ -2092,6 +2104,12 @@ export async function runDiscoverJobsTool(opts: {
   let prevStrongTotal = 0;
   let companyPivotIndex = 0;
   const companyTargets = companyNamesForPivot(profile, sources);
+  const strategyTrace: AngleObservation[] = [];
+  const priorAngleSummaries: Array<{ intent: string; focus?: ReasonedSearchAngle["focus"] }> = [];
+  let currentAngleSource: AngleObservationSource = "seed";
+  let currentAngleRationale: string | undefined = reasonedAngles[0]?.rationale;
+  let currentAngleFocus: ReasonedSearchAngle["focus"] | undefined = reasonedAngles[0]?.focus;
+  const avenueApproach = intentTrim;
 
   // Resume from durable checkpoint: seed prior scored matches and angle count.
   if (resumeSeed) {
@@ -2346,6 +2364,24 @@ export async function runDiscoverJobsTool(opts: {
     });
     lastReflection = reflection;
 
+    const angleObservation = buildAngleObservation({
+      angleIndex: anglesRun - 1,
+      intent: nextIntent,
+      focus: currentAngleFocus,
+      rationale: currentAngleRationale,
+      reflection,
+      gatedScored: meta.gatedScored,
+      scoredBeforeGate: meta.scoredBeforeGate,
+      newUniqueDiscovered: meta.newUniqueDiscovered,
+      totalDiscoveredThisAngle: result.totalDiscovered,
+      source: currentAngleSource,
+    });
+    strategyTrace.push(angleObservation);
+    priorAngleSummaries.push({
+      intent: nextIntent,
+      ...(currentAngleFocus ? { focus: currentAngleFocus } : {}),
+    });
+
     const listingsThisAngle = result.strongMatches.length + result.possibleMatches.length;
     const newStrongThisAngle = Math.max(0, strongN - prevStrongTotal);
 
@@ -2422,10 +2458,33 @@ export async function runDiscoverJobsTool(opts: {
       break;
     }
 
-    const reasonedNext = reasonedAngles[anglesRun];
-    if (reasonedNext) {
-      // angles[0] already contributed focus on the primary pass; later slots are full hypotheses.
-      nextIntent = enrichIntentForFocus(reasonedNext.intent.trim(), reasonedNext.focus);
+    // Inner adapt: LLM reflects on observations; candidates are hints only (not a playlist).
+    const unusedCandidates = reasonedAngles.slice(anglesRun);
+    const planned = await planNextSearchAngle({
+      avenueApproach,
+      profile,
+      latest: angleObservation,
+      priorAngles: priorAngleSummaries,
+      candidates: unusedCandidates,
+      strongMatchCount: strongN,
+      targetStrong: PERSISTENCE_TARGET_STRONG,
+    });
+
+    if (planned.action === "stop") {
+      progress(
+        planned.rationale?.trim() ?
+          planned.rationale.trim()
+        : strongN > 0 ?
+          "This search avenue looks solid enough. Wrapping up…"
+        : "This search avenue looks exhausted. Wrapping up…",
+      );
+      stoppedBecause = "completed";
+      prevStrongTotal = strongN;
+      break;
+    }
+
+    if (planned.action === "adapt") {
+      nextIntent = enrichIntentForFocus(planned.intent.trim(), planned.focus);
       nextOpts = applyReasonedFocus(
         {
           progressMode: "continuation",
@@ -2433,20 +2492,24 @@ export async function runDiscoverJobsTool(opts: {
           pivot: "default",
           angleIndex: anglesRun,
         },
-        reasonedNext.focus,
+        planned.focus,
       );
-      const rationale = reasonedNext.rationale?.trim();
+      currentAngleSource = "llm";
+      currentAngleFocus = planned.focus;
+      currentAngleRationale = planned.rationale;
+      const rationale = planned.rationale?.trim();
       progress(
         rationale ?
-          `Trying a different search hypothesis: ${rationale}`
-        : `Trying a distinct ${(reasonedNext.focus ?? "profile-aware").replace(/_/g, " ")} angle…`,
+          `Adapting this avenue: ${rationale}`
+        : `Adapting this avenue with a refined ${(planned.focus ?? "profile-aware").replace(/_/g, " ")} angle…`,
       );
       lastStrategy =
-        reasonedNext.focus === "skill_adjacency" ? "semantic_broadening" : null;
+        planned.focus === "skill_adjacency" ? "semantic_broadening" : null;
       prevStrongTotal = strongN;
       continue;
     }
 
+    // Deterministic floor when the inner planner fails open.
     if (anglesRun === PERSISTENCE_MAX_PIVOTS) {
       nextIntent = semanticSkillsRemoteIntent(profile);
       nextOpts = {
@@ -2456,6 +2519,10 @@ export async function runDiscoverJobsTool(opts: {
         angleIndex: anglesRun,
       };
       lastStrategy = "exhausted";
+      currentAngleSource = "deterministic";
+      currentAngleFocus = "skill_adjacency";
+      currentAngleRationale = "Deterministic semantic broadening after planner fallback.";
+      prevStrongTotal = strongN;
       continue;
     }
 
@@ -2496,20 +2563,28 @@ export async function runDiscoverJobsTool(opts: {
     if (hirebasePivot === "broaden_role") {
       nextIntent = buildBroadenRoleIntent(profile, intentTrim);
       nextOpts.continuationWidening = true;
+      currentAngleFocus = undefined;
     } else if (hirebasePivot === "extend_timeframe") {
       nextIntent = intentTrim;
       nextOpts.continuationWidening = true;
+      currentAngleFocus = undefined;
     } else if (hirebasePivot === "semantic_broadening") {
       nextIntent = semanticSkillsRemoteIntent(profile);
+      currentAngleFocus = "skill_adjacency";
     } else if (hirebasePivot === "company_specific") {
       nextIntent = intentTrim;
       const companies = companyTargets;
       nextOpts.companyName = companies[companyPivotIndex % companies.length];
       companyPivotIndex++;
+      currentAngleFocus = undefined;
     } else {
       nextIntent = semanticSkillsRemoteIntent(profile);
       nextOpts.pivot = "semantic_broadening";
+      currentAngleFocus = "skill_adjacency";
     }
+    currentAngleSource = "deterministic";
+    currentAngleRationale = `Deterministic pivot: ${pivot.replace(/_/g, " ")}.`;
+    progress(`Trying a different angle (${pivot.replace(/_/g, " ")})…`);
 
     prevStrongTotal = strongN;
   }
@@ -2543,6 +2618,17 @@ export async function runDiscoverJobsTool(opts: {
     stoppedBecause === "max_pivots" ||
     stoppedBecause === "time";
 
+  const avenueObservation = buildAvenueObservation({
+    approach: avenueApproach,
+    anglesRun,
+    stoppedBecause,
+    strongMatches: allStrong,
+    possibleMatches: allPossible,
+    totalDiscovered: urlsDiscoveredThisSession.size,
+    strategyTrace,
+    targetStrong: PERSISTENCE_TARGET_STRONG,
+  });
+
   if (durable) {
     try {
       const run = await durable.get(durable.runId);
@@ -2609,6 +2695,8 @@ export async function runDiscoverJobsTool(opts: {
     stoppedBecause,
     internalPivotsExhausted,
     lastReflection,
+    strategyTrace,
+    avenueObservation,
     searchRunId: durable?.runId,
     [LAB_DEBUG_PAYLOAD_KEY]: {
       backend: [

lib/agent-chat/discovery-observations.selftest.ts

@@ -0,0 +1,134 @@
+import assert from "node:assert/strict";
+
+import {
+  avenueObservationForLlm,
+  buildAngleObservation,
+  buildAvenueObservation,
+  extractPromisingTerminology,
+  worthContinuingHintFromCounts,
+} from "@/lib/agent-chat/discovery-observations";
+import type { ScoreResult } from "@/lib/types";
+
+function dim(score: number): ScoreResult["role_fit"] {
+  return { score, notes: "" };
+}
+
+function scored(
+  title: string,
+  verdict: "Strong Match" | "Possible" | "Skip",
+  remote: number,
+  role: number,
+  flags: string[] = [],
+) {
+  return {
+    title,
+    company: "Acme Labs",
+    scoresSnapshot: {
+      role_fit: dim(role),
+      global_remote: dim(remote),
+      culture_async: dim(5),
+      contractor_friendly: dim(5),
+      skill_gaps: [],
+      red_flags: flags,
+      green_flags: [],
+      verdict: "Skip" as const,
+      verdict_reason: "t",
+    },
+    verdict,
+  };
+}
+
+function testPromisingTerminology(): void {
+  const terms = extractPromisingTerminology([
+    scored("Senior React Engineer", "Strong Match", 8, 8),
+    scored("React TypeScript Frontend", "Possible", 7, 7),
+    scored("Junior Java", "Skip", 3, 3),
+  ]);
+  assert.ok(terms.includes("react"));
+  assert.ok(terms.includes("typescript") || terms.includes("frontend") || terms.includes("acme"));
+  assert.ok(!terms.includes("junior"));
+}
+
+function testAngleObservationShape(): void {
+  const rows = [
+    scored("Senior React", "Strong Match", 8, 8),
+    scored("US Only Role", "Skip", 2, 6, ["US-only role"]),
+  ];
+  const obs = buildAngleObservation({
+    angleIndex: 0,
+    intent: "senior React remote",
+    focus: "work_from_anywhere",
+    rationale: "WFA first",
+    reflection: {
+      dominantFailureReason: "low_remote_score",
+      suggestedPivot: "semantic_broadening",
+    },
+    gatedScored: rows,
+    newUniqueDiscovered: 2,
+    totalDiscoveredThisAngle: 5,
+    source: "seed",
+  });
+  assert.equal(obs.resultQuality.strong, 1);
+  assert.equal(obs.geographySignals.dominantRemoteFailure, true);
+  assert.ok((obs.geographySignals.usOnlyFlagCount ?? 0) >= 1);
+  assert.equal(obs.novelty.newUniqueDiscovered, 2);
+  assert.ok(obs.novelty.duplicateOrSeenRate !== undefined);
+  assert.ok(obs.promisingTerminology.length >= 1);
+  assert.equal(obs.source, "seed");
+}
+
+function testAvenueObservationAndHint(): void {
+  assert.equal(
+    worthContinuingHintFromCounts({ strong: 5, possible: 0, totalDiscovered: 20 }),
+    "solid",
+  );
+  assert.equal(
+    worthContinuingHintFromCounts({ strong: 1, possible: 0, totalDiscovered: 10 }),
+    "thin_but_promising",
+  );
+  assert.equal(
+    worthContinuingHintFromCounts({ strong: 0, possible: 0, totalDiscovered: 0 }),
+    "empty",
+  );
+  assert.equal(
+    worthContinuingHintFromCounts({ strong: 0, possible: 1, totalDiscovered: 30 }),
+    "weak",
+  );
+
+  const avenue = buildAvenueObservation({
+    approach: "senior React remote",
+    anglesRun: 2,
+    stoppedBecause: "diminishing",
+    strongMatches: [scored("Senior React", "Strong Match", 8, 8)],
+    possibleMatches: [scored("Frontend TS", "Possible", 7, 7)],
+    totalDiscovered: 12,
+    strategyTrace: [
+      buildAngleObservation({
+        angleIndex: 0,
+        intent: "senior React remote",
+        reflection: {
+          dominantFailureReason: "low_remote_score",
+          suggestedPivot: "semantic_broadening",
+        },
+        gatedScored: [],
+        newUniqueDiscovered: 3,
+        totalDiscoveredThisAngle: 5,
+        source: "seed",
+      }),
+    ],
+  });
+  assert.equal(avenue.worthContinuingHint, "thin_but_promising");
+  assert.ok(avenue.dominantFailures.includes("low_remote_score"));
+  const llm = avenueObservationForLlm(avenue);
+  assert.equal(llm.approach, "senior React remote");
+  assert.ok(Array.isArray(llm.strategyTrace));
+}
+
+function main(): void {
+  testPromisingTerminology();
+  testAngleObservationShape();
+  testAvenueObservationAndHint();
+  console.log("discovery-observations.selftest: ok");
+}
+
+main();

lib/agent-chat/discovery-observations.ts

@@ -0,0 +1,329 @@
+/**
+ * Structured observations crossing the inner→outer discovery boundary.
+ * Outer strategy reasons over these; it does not receive raw listing dumps.
+ */
+
+import type { ReasonedSearchAngle } from "@/lib/search-runs/types";
+import type { ScoreResult } from "@/lib/types";
+
+export type AngleObservationSource = "llm" | "deterministic" | "seed";
+
+export type DominantFailureReason =
+  | "low_role_fit"
+  | "low_remote_score"
+  | "blocked_fetches"
+  | "no_results"
+  | "high_volume_low_yield"
+  | null;
+
+export type SuggestedPivot =
+  | "broaden_role"
+  | "extend_timeframe"
+  | "semantic_broadening"
+  | "company_specific"
+  | "exhausted";
+
+/** Minimal scored row shape — avoids importing discover-jobs-tool (circular). */
+export type ObservationScoredListing = {
+  title: string;
+  company?: string;
+  scoresSnapshot: ScoreResult;
+  verdict: "Strong Match" | "Possible" | "Skip";
+};
+
+export type AngleResultQuality = {
+  strong: number;
+  possible: number;
+  skip: number;
+  meanRoleFit?: number;
+  meanGlobalRemote?: number;
+};
+
+export type AngleNovelty = {
+  newUniqueDiscovered: number;
+  /** 0–1 share of discovered URLs already seen this session (when totals known). */
+  duplicateOrSeenRate?: number;
+};
+
+export type AngleObservation = {
+  angleIndex: number;
+  intent: string;
+  focus?: ReasonedSearchAngle["focus"];
+  rationale?: string;
+  resultQuality: AngleResultQuality;
+  /** Share of scored rows with role_fit below 5 (0–1). */
+  roleFitBelowShare?: number;
+  geographySignals: {
+    dominantRemoteFailure: boolean;
+    lowRemoteShare?: number;
+    usOnlyFlagCount?: number;
+  };
+  novelty: AngleNovelty;
+  failurePatterns: {
+    dominantFailureReason: DominantFailureReason;
+    suggestedPivot: SuggestedPivot;
+  };
+  promisingTerminology: string[];
+  source: AngleObservationSource;
+};
+
+export type AvenueTopListing = {
+  title: string;
+  company?: string;
+  verdict: "Strong Match" | "Possible";
+};
+
+export type AvenueObservation = {
+  approach: string;
+  anglesRun: number;
+  stoppedBecause?: string;
+  strongMatchCount: number;
+  possibleMatchCount: number;
+  totalDiscovered: number;
+  dominantFailures: Array<NonNullable<DominantFailureReason>>;
+  strategyTrace: AngleObservation[];
+  topListings: AvenueTopListing[];
+  /** Coarse hint for outer reflection: some signal but thin vs empty vs solid. */
+  worthContinuingHint: "solid" | "thin_but_promising" | "weak" | "empty";
+};
+
+const STOP_WORDS = new Set([
+  "the",
+  "and",
+  "for",
+  "with",
+  "senior",
+  "junior",
+  "remote",
+  "role",
+  "roles",
+  "engineer",
+  "engineering",
+  "software",
+  "developer",
+  "job",
+  "jobs",
+]);
+
+function meanScore(
+  rows: ObservationScoredListing[],
+  key: "role_fit" | "global_remote",
+): number | undefined {
+  if (rows.length === 0) return undefined;
+  let sum = 0;
+  let n = 0;
+  for (const r of rows) {
+    const v = Number(r.scoresSnapshot[key]?.score);
+    if (Number.isFinite(v)) {
+      sum += v;
+      n++;
+    }
+  }
+  return n > 0 ? Math.round((sum / n) * 10) / 10 : undefined;
+}
+
+/** Recurring title/company tokens from Strong/Possible — heuristic, not LLM. */
+export function extractPromisingTerminology(
+  rows: ObservationScoredListing[],
+  cap = 8,
+): string[] {
+  const counts = new Map<string, number>();
+  for (const r of rows) {
+    if (r.verdict !== "Strong Match" && r.verdict !== "Possible") continue;
+    const blob = `${r.title ?? ""} ${r.company ?? ""}`;
+    for (const raw of blob.split(/[\s,/|·•\-–—]+/)) {
+      const t = raw.toLowerCase().replace(/[^a-z0-9+#.]/g, "");
+      if (t.length < 3 || STOP_WORDS.has(t)) continue;
+      counts.set(t, (counts.get(t) ?? 0) + 1);
+    }
+  }
+  return [...counts.entries()]
+    .filter(([, c]) => c >= 1)
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .slice(0, cap)
+    .map(([t]) => t);
+}
+
+function countUsOnlyFlags(rows: ObservationScoredListing[]): number {
+  let n = 0;
+  for (const r of rows) {
+    const flags = [
+      ...(r.scoresSnapshot.red_flags ?? []),
+      ...(r.scoresSnapshot.green_flags ?? []),
+    ];
+    if (flags.some((f) => /\b(us[- ]?only|united states only|usa only|must be in (the )?us)\b/i.test(f))) {
+      n++;
+    }
+  }
+  return n;
+}
+
+export function buildAngleObservation(opts: {
+  angleIndex: number;
+  intent: string;
+  focus?: ReasonedSearchAngle["focus"];
+  rationale?: string;
+  reflection: {
+    dominantFailureReason: DominantFailureReason;
+    suggestedPivot: SuggestedPivot;
+  };
+  gatedScored: ObservationScoredListing[];
+  scoredBeforeGate?: ObservationScoredListing[];
+  newUniqueDiscovered: number;
+  totalDiscoveredThisAngle: number;
+  urlsAlreadySeenBeforeAngle?: number;
+  source: AngleObservationSource;
+}): AngleObservation {
+  const {
+    angleIndex,
+    intent,
+    focus,
+    rationale,
+    reflection,
+    gatedScored,
+    scoredBeforeGate,
+    newUniqueDiscovered,
+    totalDiscoveredThisAngle,
+    source,
+  } = opts;
+  const pool = gatedScored.length > 0 ? gatedScored : (scoredBeforeGate ?? []);
+  const strong = gatedScored.filter((r) => r.verdict === "Strong Match").length;
+  const possible = gatedScored.filter((r) => r.verdict === "Possible").length;
+  const skip = gatedScored.filter((r) => r.verdict === "Skip").length;
+  const lowRole = pool.filter((r) => Number(r.scoresSnapshot.role_fit?.score ?? 0) < 5).length;
+  const lowRemote = pool.filter((r) => Number(r.scoresSnapshot.global_remote?.score ?? 0) < 5).length;
+  const duplicateOrSeenRate =
+    totalDiscoveredThisAngle > 0 ?
+      Math.min(
+        1,
+        Math.max(0, (totalDiscoveredThisAngle - newUniqueDiscovered) / totalDiscoveredThisAngle),
+      )
+    : undefined;
+
+  return {
+    angleIndex,
+    intent: intent.trim().slice(0, 200),
+    ...(focus ? { focus } : {}),
+    ...(rationale?.trim() ? { rationale: rationale.trim().slice(0, 240) } : {}),
+    resultQuality: {
+      strong,
+      possible,
+      skip,
+      ...(meanScore(pool, "role_fit") !== undefined ?
+        { meanRoleFit: meanScore(pool, "role_fit") }
+      : {}),
+      ...(meanScore(pool, "global_remote") !== undefined ?
+        { meanGlobalRemote: meanScore(pool, "global_remote") }
+      : {}),
+    },
+    ...(pool.length > 0 ? { roleFitBelowShare: Math.round((lowRole / pool.length) * 100) / 100 } : {}),
+    geographySignals: {
+      dominantRemoteFailure: reflection.dominantFailureReason === "low_remote_score",
+      ...(pool.length > 0 ?
+        { lowRemoteShare: Math.round((lowRemote / pool.length) * 100) / 100 }
+      : {}),
+      usOnlyFlagCount: countUsOnlyFlags(pool),
+    },
+    novelty: {
+      newUniqueDiscovered,
+      ...(duplicateOrSeenRate !== undefined ? { duplicateOrSeenRate } : {}),
+    },
+    failurePatterns: {
+      dominantFailureReason: reflection.dominantFailureReason,
+      suggestedPivot: reflection.suggestedPivot,
+    },
+    promisingTerminology: extractPromisingTerminology(
+      gatedScored.filter((r) => r.verdict === "Strong Match" || r.verdict === "Possible"),
+    ),
+    source,
+  };
+}
+
+export function worthContinuingHintFromCounts(opts: {
+  strong: number;
+  possible: number;
+  totalDiscovered: number;
+  targetStrong?: number;
+}): AvenueObservation["worthContinuingHint"] {
+  const target = opts.targetStrong ?? 5;
+  if (opts.strong >= target) return "solid";
+  if (opts.strong > 0 || opts.possible >= 3) return "thin_but_promising";
+  if (opts.totalDiscovered === 0 && opts.strong === 0 && opts.possible === 0) return "empty";
+  return "weak";
+}
+
+export function buildAvenueObservation(opts: {
+  approach: string;
+  anglesRun: number;
+  stoppedBecause?: string;
+  strongMatches: ObservationScoredListing[];
+  possibleMatches: ObservationScoredListing[];
+  totalDiscovered: number;
+  strategyTrace: AngleObservation[];
+  targetStrong?: number;
+}): AvenueObservation {
+  const strong = opts.strongMatches.length;
+  const possible = opts.possibleMatches.length;
+  const dominantFailures = opts.strategyTrace
+    .map((a) => a.failurePatterns.dominantFailureReason)
+    .filter((x): x is NonNullable<DominantFailureReason> => Boolean(x));
+  const uniqFailures = [...new Set(dominantFailures)];
+  const topListings: AvenueTopListing[] = [
+    ...opts.strongMatches.slice(0, 4).map((r) => ({
+      title: r.title,
+      ...(r.company ? { company: r.company } : {}),
+      verdict: "Strong Match" as const,
+    })),
+    ...opts.possibleMatches.slice(0, 3).map((r) => ({
+      title: r.title,
+      ...(r.company ? { company: r.company } : {}),
+      verdict: "Possible" as const,
+    })),
+  ].slice(0, 6);
+
+  return {
+    approach: opts.approach.trim().slice(0, 240),
+    anglesRun: opts.anglesRun,
+    ...(opts.stoppedBecause ? { stoppedBecause: opts.stoppedBecause } : {}),
+    strongMatchCount: strong,
+    possibleMatchCount: possible,
+    totalDiscovered: opts.totalDiscovered,
+    dominantFailures: uniqFailures,
+    strategyTrace: opts.strategyTrace,
+    topListings,
+    worthContinuingHint: worthContinuingHintFromCounts({
+      strong,
+      possible,
+      totalDiscovered: opts.totalDiscovered,
+      targetStrong: opts.targetStrong,
+    }),
+  };
+}
+
+/** Compact shape for the chat LLM (outer reflection). */
+export function avenueObservationForLlm(obs: AvenueObservation): Record<string, unknown> {
+  return {
+    approach: obs.approach,
+    anglesRun: obs.anglesRun,
+    stoppedBecause: obs.stoppedBecause,
+    strongMatchCount: obs.strongMatchCount,
+    possibleMatchCount: obs.possibleMatchCount,
+    totalDiscovered: obs.totalDiscovered,
+    dominantFailures: obs.dominantFailures,
+    worthContinuingHint: obs.worthContinuingHint,
+    topListings: obs.topListings,
+    strategyTrace: obs.strategyTrace.map((a) => ({
+      angleIndex: a.angleIndex,
+      intent: a.intent,
+      focus: a.focus,
+      rationale: a.rationale,
+      resultQuality: a.resultQuality,
+      roleFitBelowShare: a.roleFitBelowShare,
+      geographySignals: a.geographySignals,
+      novelty: a.novelty,
+      failurePatterns: a.failurePatterns,
+      promisingTerminology: a.promisingTerminology,
+      source: a.source,
+    })),
+  };
+}

lib/agent-chat/plan-next-search-angle.selftest.ts

@@ -0,0 +1,50 @@
+import assert from "node:assert/strict";
+
+import { parsePlanNextSearchAngleJson } from "@/lib/agent-chat/plan-next-search-angle";
+
+function testParseAdapt(): void {
+  const r = parsePlanNextSearchAngleJson({
+    action: "adapt",
+    intent: "senior frontend React remote EMEA",
+    focus: "work_from_anywhere",
+    rationale: "Prior hits were US-only; bias EMEA",
+  });
+  assert.equal(r?.action, "adapt");
+  if (r?.action === "adapt") {
+    assert.equal(r.intent, "senior frontend React remote EMEA");
+    assert.equal(r.focus, "work_from_anywhere");
+    assert.equal(r.source, "llm");
+  }
+}
+
+function testParseStop(): void {
+  const r = parsePlanNextSearchAngleJson({
+    action: "stop",
+    rationale: "Quality is good enough for this avenue",
+  });
+  assert.equal(r?.action, "stop");
+}
+
+function testParseRejectsPlaylistBlindnessInputs(): void {
+  assert.equal(parsePlanNextSearchAngleJson({ action: "adapt", intent: "" }), null);
+  assert.equal(parsePlanNextSearchAngleJson({ action: "adapt", intent: "ab" }), null);
+  assert.equal(parsePlanNextSearchAngleJson(null), null);
+  const badFocus = parsePlanNextSearchAngleJson({
+    action: "adapt",
+    intent: "senior React remote",
+    focus: "site:greenhouse.io",
+  });
+  assert.equal(badFocus?.action, "adapt");
+  if (badFocus?.action === "adapt") {
+    assert.equal(badFocus.focus, undefined);
+  }
+}
+
+function main(): void {
+  testParseAdapt();
+  testParseStop();
+  testParseRejectsPlaylistBlindnessInputs();
+  console.log("plan-next-search-angle.selftest: ok");
+}
+
+main();

lib/agent-chat/plan-next-search-angle.ts

@@ -0,0 +1,172 @@
+/**
+ * Inner-loop adapter: given angle observations, propose the next search angle
+ * (or stop). LLM-first with deterministic fail-open. Never authors provider query strings.
+ */
+
+import { chatCompletionWithTools } from "@/lib/agent-chat/groq-tools-client";
+import type { AngleObservation } from "@/lib/agent-chat/discovery-observations";
+import type { ReasonedSearchAngle } from "@/lib/search-runs/types";
+import type { UserProfile } from "@/lib/user-profile";
+
+const FOCUS_SET = new Set<ReasonedSearchAngle["focus"]>([
+  "ats_first",
+  "work_from_anywhere",
+  "visa_sponsorship",
+  "skill_adjacency",
+]);
+
+const INNER_PLANNER_TIMEOUT_MS = (() => {
+  const n = parseInt(String(process.env.DISCOVER_INNER_PLANNER_TIMEOUT_MS ?? "8000").trim(), 10);
+  return Number.isFinite(n) ? Math.min(20_000, Math.max(2_000, n)) : 8_000;
+})();
+
+export type PlanNextSearchAngleResult =
+  | { action: "stop"; rationale?: string }
+  | {
+      action: "adapt";
+      intent: string;
+      focus?: ReasonedSearchAngle["focus"];
+      rationale?: string;
+      source: "llm";
+    }
+  | { action: "fallback_deterministic" };
+
+function profileGist(profile: UserProfile): string {
+  const pref = profile.jobPreferences;
+  const titles =
+    Array.isArray(pref?.searchTitleVariants) ?
+      pref!.searchTitleVariants.filter((x): x is string => typeof x === "string").slice(0, 4)
+    : [];
+  const stack =
+    Array.isArray(pref?.preferredTechStack) ?
+      pref!.preferredTechStack.filter((x): x is string => typeof x === "string").slice(0, 6)
+    : [];
+  const seniority =
+    Array.isArray(pref?.seniorityLevels) ?
+      pref!.seniorityLevels.filter((x): x is string => typeof x === "string").slice(0, 3)
+    : [];
+  return [
+    profile.headline?.trim(),
+    titles.length ? `titles:${titles.join(", ")}` : "",
+    seniority.length ? `seniority:${seniority.join(", ")}` : "",
+    stack.length ? `stack:${stack.join(", ")}` : "",
+    pref?.workPreference ? `work:${pref.workPreference}` : "",
+  ]
+    .filter(Boolean)
+    .join(" · ")
+    .slice(0, 400);
+}
+
+function extractJsonObject(text: string): unknown {
+  const trimmed = text.trim();
+  const fence = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const raw = fence?.[1]?.trim() ?? trimmed;
+  const start = raw.indexOf("{");
+  const end = raw.lastIndexOf("}");
+  if (start < 0 || end <= start) throw new Error("no_json_object");
+  return JSON.parse(raw.slice(start, end + 1));
+}
+
+/** Parse / validate LLM JSON for the next inner angle. Exported for tests. */
+export function parsePlanNextSearchAngleJson(raw: unknown): PlanNextSearchAngleResult | null {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+  const o = raw as Record<string, unknown>;
+  const action = typeof o.action === "string" ? o.action.trim().toLowerCase() : "";
+  if (action === "stop") {
+    return {
+      action: "stop",
+      ...(typeof o.rationale === "string" && o.rationale.trim() ?
+        { rationale: o.rationale.trim().slice(0, 240) }
+      : {}),
+    };
+  }
+  if (action !== "adapt" && action !== "continue" && action !== "next") return null;
+  const intent = typeof o.intent === "string" ? o.intent.trim() : "";
+  if (!intent || intent.length < 3) return null;
+  const focusRaw = typeof o.focus === "string" ? o.focus.trim() : "";
+  const focus =
+    FOCUS_SET.has(focusRaw as ReasonedSearchAngle["focus"]) ?
+      (focusRaw as ReasonedSearchAngle["focus"])
+    : undefined;
+  const rationale =
+    typeof o.rationale === "string" && o.rationale.trim() ?
+      o.rationale.trim().slice(0, 240)
+    : undefined;
+  return {
+    action: "adapt",
+    intent: intent.slice(0, 200),
+    ...(focus ? { focus } : {}),
+    ...(rationale ? { rationale } : {}),
+    source: "llm",
+  };
+}
+
+/**
+ * Ask the model how to adapt within the current avenue.
+ * Returns fallback_deterministic on timeout, API failure, or invalid JSON.
+ */
+export async function planNextSearchAngle(opts: {
+  avenueApproach: string;
+  profile: UserProfile;
+  latest: AngleObservation;
+  priorAngles: Array<{ intent: string; focus?: ReasonedSearchAngle["focus"] }>;
+  candidates?: ReasonedSearchAngle[];
+  strongMatchCount: number;
+  targetStrong: number;
+}): Promise<PlanNextSearchAngleResult> {
+  const system = [
+    "You adapt job-search angles inside ONE research avenue (local improvement, not a new strategy).",
+    "Providers compile your intent into safe queries — never invent site: operators or raw API params.",
+    "Return ONLY JSON with one of:",
+    '{"action":"adapt","intent":"...","focus":"ats_first|work_from_anywhere|visa_sponsorship|skill_adjacency","rationale":"..."}',
+    '{"action":"stop","rationale":"..."}',
+    "Stop when quality is good enough for this avenue, or further tweaks would not help.",
+    "Adapt when geography, seniority, stack, or volume failed — change the hypothesis meaningfully.",
+    "Optional candidates are hints only; rewrite or discard them.",
+  ].join(" ");
+
+  const user = JSON.stringify(
+    {
+      avenueApproach: opts.avenueApproach,
+      profileGist: profileGist(opts.profile),
+      strongMatchCount: opts.strongMatchCount,
+      targetStrong: opts.targetStrong,
+      latestObservation: opts.latest,
+      priorAnglesThisAvenue: opts.priorAngles,
+      candidateHypotheses: (opts.candidates ?? []).slice(0, 4),
+    },
+    null,
+    0,
+  );
+
+  const run = async (): Promise<PlanNextSearchAngleResult> => {
+    const msg = await chatCompletionWithTools(
+      [
+        { role: "system", content: system },
+        { role: "user", content: user },
+      ],
+      [],
+      { toolChoice: "none" },
+    );
+    const content = typeof msg.content === "string" ? msg.content : "";
+    if (!content.trim()) return { action: "fallback_deterministic" };
+    try {
+      const parsed = parsePlanNextSearchAngleJson(extractJsonObject(content));
+      return parsed ?? { action: "fallback_deterministic" };
+    } catch {
+      return { action: "fallback_deterministic" };
+    }
+  };
+
+  try {
+    const timed = await Promise.race([
+      run(),
+      new Promise<PlanNextSearchAngleResult>((resolve) =>
+        setTimeout(() => resolve({ action: "fallback_deterministic" }), INNER_PLANNER_TIMEOUT_MS),
+      ),
+    ]);
+    return timed;
+  } catch {
+    return { action: "fallback_deterministic" };
+  }
+}

lib/agent-chat/run-conversation.ts

@@ -91,8 +91,10 @@ import {
   evaluateDiscoverOutcomePolicy,
   humanizeToolError,
   isColloquialResumeMessage,
+  retryStrategyUserLine,
   shouldTreatAsHardSearchFailure,
 } from "@/lib/agent-chat/autonomy-policy";
+import { avenueObservationForLlm, type AvenueObservation } from "@/lib/agent-chat/discovery-observations";
 
 const MAX_TOOL_CALLS = 10;
 const MAX_HISTORY = 24;
@@ -176,9 +178,13 @@ const GROUNDING_SYSTEM_RULES = [
   "## Tool grounding (critical)",
   "You are a tool-calling agent. Job listings in your responses must come exclusively from tool results.",
   "Never invent job titles, companies, or URLs. If a tool returns nothing, say so.",
-  "discover_jobs already ran internal pivots — one call per intent per turn unless outcome policy asks for recency=\"48h\".",
+  "Nested research: OUTER = where to look (avenue); INNER = how to look within that avenue (discover_jobs adapts angles from results).",
+  "One discover_jobs call = one avenue. searchAngles are optional hypotheses for the inner loop — not a fixed playlist.",
+  "After an avenue returns, compare avenueSummaries / avenueObservation. If the approach is weak, call discover_jobs again with a fundamentally different avenue (prefer seedFromRunId). Do not clone the same intent.",
+  "If Strong matches already meet the bar, present them — do not churn avenues.",
+  "Outcome policy may nudge recency=\"48h\" or a different avenue; follow those system lines when present.",
   "For ordinary \"find roles for me\" / profile searches, call discover_jobs first. Do not start with run_batch_search unless the user asked for a deeper background/batch search or discover already returned empty/timeout.",
-  "When inference is available, include 2–4 distinct searchAngles in discover_jobs: ATS-first plus profile-relevant work-from-anywhere, visa, or adjacent-skill hypotheses. Do not write raw site: queries.",
+  "Do not write raw site: queries or provider payloads — planners compile safe queries.",
   "After a timeout, show partials and offer a background search; do not retry discovery in the same turn.",
   "If a search tool errors, say search is temporarily unavailable and stop. Do not retry discover_jobs or call run_batch_search in that turn.",
   "If discover_jobs succeeds with zero listings (no error), say nothing was found in the last 48 hours honestly and you may offer batch search — do not say search is unavailable.",
@@ -429,6 +435,7 @@ function discoverJobsPayloadForLlm(
   payload: unknown,
   jobs?: AgentJobCard[],
   prefs?: UserProfile["jobPreferences"],
+  priorAvenueSummaries?: AvenueObservation[],
 ): Record<string, unknown> | undefined {
   if (typeof payload !== "object" || payload === null || Array.isArray(payload)) return undefined;
   const p = payload as Record<string, unknown>;
@@ -441,10 +448,38 @@ function discoverJobsPayloadForLlm(
       {
         dominantFailureReason: (lr as Record<string, unknown>).dominantFailureReason,
         suggestedPivot: (lr as Record<string, unknown>).suggestedPivot,
+        strongMatchCount: (lr as Record<string, unknown>).strongMatchCount,
+        possibleMatchCount: (lr as Record<string, unknown>).possibleMatchCount,
+        lowScoreCount: (lr as Record<string, unknown>).lowScoreCount,
       }
     : undefined;
   const sectionCounts =
     jobs?.length ? countJobsByOpportunitySection(jobs, prefs) : undefined;
+
+  let avenueObservation: Record<string, unknown> | undefined;
+  if (p.avenueObservation && typeof p.avenueObservation === "object" && !Array.isArray(p.avenueObservation)) {
+    try {
+      avenueObservation = avenueObservationForLlm(p.avenueObservation as AvenueObservation);
+    } catch {
+      avenueObservation = undefined;
+    }
+  }
+
+  const avenueSummaries = [
+    ...(priorAvenueSummaries ?? []).map((a) => avenueObservationForLlm(a)),
+    ...(avenueObservation ? [avenueObservation] : []),
+  ];
+
+  const topFromJobs =
+    (jobs ?? [])
+      .filter((j) => j.verdict === "Strong Match" || j.verdict === "Possible")
+      .slice(0, 6)
+      .map((j) => ({
+        title: j.title,
+        ...(j.company ? { company: j.company } : {}),
+        verdict: j.verdict,
+      }));
+
   return {
     totalDiscovered: p.totalDiscovered,
     totalScored: p.totalScored,
@@ -464,6 +499,11 @@ function discoverJobsPayloadForLlm(
     stoppedBecause: p.stoppedBecause,
     internalPivotsExhausted: p.internalPivotsExhausted,
     lastReflection: reflectionSummary,
+    ...(avenueObservation ? { avenueObservation } : {}),
+    ...(avenueSummaries.length ? { avenueSummaries } : {}),
+    ...(Array.isArray(p.strategyTrace) ? { strategyTrace: p.strategyTrace } : {}),
+    ...(topFromJobs.length ? { topListings: topFromJobs } : {}),
+    searchRunId: p.searchRunId,
   };
 }
 
@@ -476,6 +516,8 @@ function buildLlmToolContent(opts: {
   jobPreferences?: UserProfile["jobPreferences"];
   /** Soft failure: prior signal in the turn; model should continue, not stop. */
   softFailure?: boolean;
+  /** Prior avenues this turn (outer reflection). */
+  priorAvenueSummaries?: AvenueObservation[];
 }): string {
   const {
     fn,
@@ -485,13 +527,14 @@ function buildLlmToolContent(opts: {
     thrownReason,
     jobPreferences,
     softFailure,
+    priorAvenueSummaries,
   } = opts;
   const jobs = result.jobs ?? [];
   const jobCount = jobs.length;
   const hasPayload = typeof result.payload !== "undefined";
   const payloadForLlm =
     fn === "discover_jobs" && hasPayload ?
-      discoverJobsPayloadForLlm(result.payload, jobs, jobPreferences)
+      discoverJobsPayloadForLlm(result.payload, jobs, jobPreferences, priorAvenueSummaries)
     : result.payload;
 
   let grounding: string;
@@ -615,7 +658,8 @@ async function resolveAgentLabAdmin(userId: string): Promise<boolean> {
 const MISSION_REMINDER =
   "[MISSION REMINDER: Specialist job search — work-from-anywhere, visa-sponsored, and eligible restricted remote. " +
   "Quote only listings from tool results. " +
-  "discover_jobs already ran internal pivots: do not call it again this turn for the same intent unless a system nudge asks for recency=\"48h\". " +
+  "Nested research: each discover_jobs is one avenue (inner adapt already ran). " +
+  "If that avenue is weak, you may start a different avenue with a new intent — not a clone — especially when outcome policy asks. " +
   "On timeout: present partials and offer run_batch_search (do not auto-call it). " +
   "On tool error: say search is unavailable and stop. " +
   "On discover_jobs success with zero listings: say nothing matched recently; you may offer batch or 48h — do not say search is unavailable. " +
@@ -704,9 +748,10 @@ function buildSystemPrompt(opts: {
     "",
     "EXECUTION RULES (non-negotiable):",
     "1. In execution steps, act immediately with a tool call. Do not narrate what you are about to search.",
-    "2. discover_jobs is the primary search tool. One call per intent per turn (it already runs internal pivots). For a normal profile search, call discover_jobs first — do not plan run_batch_search as step 1 unless the user explicitly asked for a deep/background/batch search.",
-    "2a. Use your reasoning to provide 2–4 distinct searchAngles with the call. Ground them in the profile and make one ATS-first; the tool safely compiles them and falls back deterministically if omitted.",
-    "3. After discover_jobs: if strongMatchCount > 0, present results grouped by opportunity path when sectionCounts shows multiple paths and quote matches verbatim with URLs. If 0 and internalPivotsExhausted, or if timedOut, show any partials and offer (do not automatically call) run_batch_search. If the tool returns an error, state that search is temporarily unavailable and stop: do not retry discover_jobs or call run_batch_search in that turn. If the tool succeeds with zero listings (no error), say nothing matched in the last 48 hours and you may offer batch — do not claim search is unavailable.",
+    "2. discover_jobs is the primary search tool. One call = one research avenue (inner loop adapts angles from results). For a normal profile search, call discover_jobs first — do not plan run_batch_search as step 1 unless the user explicitly asked for a deep/background/batch search.",
+    "2a. Decide a broad avenue (where to look). Optionally pass 2–4 searchAngles as hypotheses for the inner loop — not a fixed playlist. Ground them in the profile; make one ATS-first when relevant. Do not write raw site: queries.",
+    "2b. After an avenue returns: if Strong matches meet the bar, present them. If the avenue is weak/exhausted, you may call discover_jobs again with a fundamentally different avenue (prefer seedFromRunId). Compare avenueSummaries. Outcome policy may nudge a strategy switch or recency=\"48h\".",
+    "3. After discover_jobs: if strongMatchCount > 0, present results grouped by opportunity path when sectionCounts shows multiple paths and quote matches verbatim with URLs. If 0 and internalPivotsExhausted, or if timedOut, show any partials and offer (do not automatically call) run_batch_search — unless outcome policy asks for another avenue or 48h. If the tool returns an error, state that search is temporarily unavailable and stop: do not retry discover_jobs or call run_batch_search in that turn. If the tool succeeds with zero listings (no error), say nothing matched in the last 48 hours and you may offer batch — do not claim search is unavailable.",
     "4. Do not call score_job on discover_jobs results (already scored). Do not call research_company on those results unless the user named a company.",
     "5. remember: call when user rejects a company or states a preference. update_profile: call when user corrects role/stack.",
     "6. get_shortlist: call when user asks for saved jobs. research_company: only when the user named a company — never as a follow-up after discover_jobs.",
@@ -1084,6 +1129,8 @@ export async function runAgentConversation(opts: {
   let finalResultSummary: string | undefined;
   let budgetExhausted = false;
   let autoCycleCount = 0;
+  /** AvenueObservations accumulated this turn for outer reflection. */
+  const turnAvenueSummaries: AvenueObservation[] = [];
   let resumeAttached = false;
   const verboseLogging = isLabInferenceLoggingEnabled();
 
@@ -1648,12 +1695,15 @@ export async function runAgentConversation(opts: {
           } catch {
             /* default */
           }
+          const strongFromPayload = Array.isArray(p?.strongMatches) ? p.strongMatches.length : 0;
           const policy = evaluateDiscoverOutcomePolicy({
             totalDiscovered,
             totalScored,
+            strongMatchCount: strongFromPayload,
             timedOut: p?.timedOut === true,
             backgroundContinued: p?.backgroundContinued === true,
             stoppedBecause: typeof p?.stoppedBecause === "string" ? p.stoppedBecause : undefined,
+            internalPivotsExhausted: p?.internalPivotsExhausted === true,
             toolCallsUsed,
             maxToolCalls: MAX_TOOL_CALLS,
             autoCycleCount,
@@ -1665,6 +1715,12 @@ export async function runAgentConversation(opts: {
               type: "progress",
               text: "No scored matches yet. Widening to the last 48 hours and retrying discovery…",
             });
+          } else if (policy.action === "retry_strategy") {
+            pendingAutoCycleNudge = retryStrategyUserLine(observedSearchRunId);
+            emit({
+              type: "progress",
+              text: "This search avenue looks thin. Trying a different approach…",
+            });
           } else if (policy.action === "await_resume") {
             preferAwaitResumeStop = true;
           }
@@ -2063,8 +2119,22 @@ export async function runAgentConversation(opts: {
           thrownReason: value.thrownReason,
           jobPreferences: profile.jobPreferences,
           softFailure,
+          priorAvenueSummaries:
+            value.fn === "discover_jobs" ? [...turnAvenueSummaries] : undefined,
         }),
       });
+
+      if (
+        value.fn === "discover_jobs" &&
+        !value.result.error &&
+        !value.toolThrewOrTimedOut
+      ) {
+        const av = (value.result.payload as { avenueObservation?: AvenueObservation } | undefined)
+          ?.avenueObservation;
+        if (av && typeof av === "object" && typeof av.approach === "string") {
+          turnAvenueSummaries.push(av);
+        }
+      }
     }
 
     return skippedForBudget;

lib/agent-chat/tools-schema.ts

@@ -45,18 +45,19 @@ export const AGENT_TOOL_DEFINITIONS: Array<{
       name: "discover_jobs",
       description: [
         "Primary discovery engine for finding work-from-anywhere, visa-sponsored, and eligible restricted-remote tech roles.",
-        "Discovers AND scores job listings in one operation via consolidated remote-job discovery (curated ATS inventory + open-web ATS search), with internal angle pivots and profile vector pre-filter.",
+        "Discovers AND scores job listings in one operation via consolidated remote-job discovery (curated ATS inventory + open-web ATS search), with an inner loop that adapts angles from result quality, plus profile vector pre-filter.",
         "Returns only listings that pass the user's accessibility preferences and lane-specific scoring gates. Do not call score_job after this tool. Do not call research_company unless the user named a company.",
         "",
         "Inputs:",
-        "- intent: Natural language query (e.g. 'senior frontend roles'). Do not say 'remote' (it is strictly enforced automatically).",
+        "- intent: Natural language query for this research avenue (e.g. 'senior frontend roles'). Do not say 'remote' (it is strictly enforced automatically).",
         "- sources: Optional array of site hosts, company names, or ATS URLs to prioritize.",
-        "- searchAngles: When inference is available, provide 2–4 genuinely distinct profile-aware search angles. Include ATS-first plus work-from-anywhere, visa, or adjacent-skill angles as relevant. These are strategy inputs, not raw search operators.",
+        "- searchAngles: Optional hypotheses for the INNER loop (how to look within this avenue). Not a fixed playlist — the tool adapts from results. Include ATS-first / WFA / visa / adjacent-skill when relevant.",
         "- recency: '48h' (default) or '24h' (fast). Do not request a week or month.",
         "",
         "Notes:",
         "- Always try this first before run_batch_search.",
-        "- Internal pivots already ran — do not call discover_jobs again for the same intent this turn unless outcome policy asks for a different angle.",
+        "- One call = one OUTER avenue. After it returns, compare avenueObservation / avenueSummaries; you may call discover_jobs again with a fundamentally different approach when the avenue is weak (prefer seedFromRunId). Do not clone the same intent.",
+        "- If Strong matches already meet the bar, present them instead of churning avenues.",
         "- If it returns nothing or times out, present what you have and offer (do not auto-call) run_batch_search.",
         "- Listings are scored from full pages when needed and classified by opportunity path.",
         "- Optional seedFromRunId reuses discovered/scored URLs from a prior durable search run (cheaper resume).",
@@ -104,7 +105,7 @@ export const AGENT_TOOL_DEFINITIONS: Array<{
               required: ["intent", "focus"],
             },
             description:
-              "Best-effort human-reasoned strategy. If omitted, deterministic reflection still completes the search.",
+              "Optional inner-loop hypotheses for this avenue (not a fixed playlist). If omitted, deterministic + reflective adaptation still completes the search.",
           },
           recency: {
             type: "string",

package.json

@@ -20,7 +20,7 @@
     "test:agent-persist": "tsx --tsconfig tsconfig.json lib/agent-run-persist.selftest.ts",
     "test:session-context": "tsx --tsconfig tsconfig.json lib/agent-chat/session-context.selftest.ts && tsx --tsconfig tsconfig.json lib/normalize-job-url.selftest.ts && tsx --tsconfig tsconfig.json lib/agent-chat/session-listings-store.selftest.ts && tsx --tsconfig tsconfig.json lib/agent-chat/session-transcript-store.selftest.ts",
     "test:subscription": "tsx --tsconfig tsconfig.json lib/subscription.selftest.ts",
-    "test:autonomy-policy": "tsx --tsconfig tsconfig.json lib/agent-chat/autonomy-policy.selftest.ts && tsx --tsconfig tsconfig.json lib/agent-chat/parse-embedded-tool-calls.selftest.ts && tsx --tsconfig tsconfig.json lib/agent-chat/deterministic-discover-fallback.selftest.ts && tsx --tsconfig tsconfig.json lib/agent-chat/suggested-intents.selftest.ts && tsx --tsconfig tsconfig.json lib/agent-chat/turn-failure-recovery.selftest.ts",
+    "test:autonomy-policy": "tsx --tsconfig tsconfig.json lib/agent-chat/autonomy-policy.selftest.ts && tsx --tsconfig tsconfig.json lib/agent-chat/parse-embedded-tool-calls.selftest.ts && tsx --tsconfig tsconfig.json lib/agent-chat/deterministic-discover-fallback.selftest.ts && tsx --tsconfig tsconfig.json lib/agent-chat/suggested-intents.selftest.ts && tsx --tsconfig tsconfig.json lib/agent-chat/turn-failure-recovery.selftest.ts && tsx --tsconfig tsconfig.json lib/agent-chat/discovery-observations.selftest.ts && tsx --tsconfig tsconfig.json lib/agent-chat/plan-next-search-angle.selftest.ts",
     "test:discover-jobs": "tsx --tsconfig tsconfig.json lib/agent-chat/discover-jobs-tool.selftest.ts",
     "test:discovery": "tsx --tsconfig tsconfig.json lib/discovery/discovery.selftest.ts && tsx --tsconfig tsconfig.json lib/discovery/jsearch.selftest.ts && tsx --tsconfig tsconfig.json lib/discover-pre-llm-gate.selftest.ts && tsx --tsconfig tsconfig.json lib/seen-listings.selftest.ts && tsx --tsconfig tsconfig.json lib/discover-jobs-lab-debug.selftest.ts",
     "bench:discovery": "tsx --tsconfig tsconfig.json lib/discovery/benchmark.ts",