halo-agent 2.2.0 → 2.2.2

package/detectFormErrors.js

@@ -286,4 +286,226 @@ async function detectFormErrorsInRoot(page) {
   });
 }
 
-module.exports = { detectFormErrors };
+/**
+ * Proactive required-field emptiness check.
+ *
+ * detectFormErrors is REACTIVE — it only reports a problem if the ATS has
+ * already rendered an error (aria-invalid, "is required" text, error class).
+ * On Ashby, a required combobox the agent failed to fill stays empty WITHOUT
+ * the form rendering a visible error until/unless submit is attempted — and
+ * sometimes not even then in the DOM snapshot we capture. So a reactive check
+ * sees a clean page and the agent auto-submits an incomplete form (the Plaid
+ * failure).
+ *
+ * This is the ground-truth, ATS-agnostic guard: walk every field the form
+ * marks REQUIRED (asterisked label, `required` attr, aria-required="true")
+ * and return the ones that are empty — using the same isEmptyField logic
+ * detectFormErrors uses, so react-select / Ashby comboboxes are judged by
+ * their rendered value chip, not the hidden input's .value.
+ *
+ * The orchestrator calls this BEFORE submitting: if any required field is
+ * empty, never auto-submit — route to REVIEWING with the list.
+ *
+ * Output: { hasEmptyRequired: boolean, emptyFields: [{label, selector?}] }
+ */
+async function detectRequiredEmpties(page, opts = {}) {
+  const roots = [page, ...page.frames().filter((f) => {
+    const u = f.url();
+    return f !== page.mainFrame() && u && DFE_EMBED_HOSTS.test(u) && !/google\.com|gstatic\.com|recaptcha/i.test(u);
+  })];
+  let merged = { hasEmptyRequired: false, emptyFields: [] };
+  for (const root of roots) {
+    const r = await detectRequiredEmptiesInRoot(root).catch(() => null);
+    if (r) {
+      merged.hasEmptyRequired = merged.hasEmptyRequired || r.hasEmptyRequired;
+      merged.emptyFields.push(...(r.emptyFields || []));
+    }
+  }
+  // Exclude labels the planner deliberately skipped (conditional-not-applicable,
+  // honeypots, optional). The planner has dependency context the DOM walk lacks,
+  // so a field it intentionally left blank is NOT an unfilled required field.
+  const excluded = new Set((opts.excludeLabels || []).map((l) => String(l || '').toLowerCase().trim()).filter(Boolean));
+  // Dedup by label, drop excluded.
+  const seen = new Set();
+  merged.emptyFields = merged.emptyFields.filter((f) => {
+    const k = (f.label || '').toLowerCase().trim();
+    if (!k || seen.has(k)) return false;
+    seen.add(k);
+    // If smartFill confirmed a resume upload, a file/resume field reading
+    // "empty" is a false positive: Ashby (and similar) keep the native
+    // <input type=file> at files.length===0 after upload because they stash
+    // the file in their own state and show a filename chip elsewhere. Don't
+    // block on it.
+    if (opts.resumeUploaded && f.isFile) return false;
+    // Match excluded loosely — DOM label vs planner label can differ by
+    // trailing punctuation/truncation.
+    for (const ex of excluded) {
+      if (k === ex || k.startsWith(ex) || ex.startsWith(k) || k.includes(ex) || ex.includes(k)) return false;
+    }
+    return true;
+  });
+  merged.hasEmptyRequired = merged.emptyFields.length > 0;
+  return merged;
+}
+
+async function detectRequiredEmptiesInRoot(page) {
+  return await page.evaluate(() => {
+    function visibleText(el) {
+      if (!el) return '';
+      const rect = el.getBoundingClientRect();
+      if (rect.width === 0 && rect.height === 0) return '';
+      const t = (el.innerText || el.textContent || '').trim();
+      return t ? t.replace(/\s+/g, ' ').slice(0, 300) : '';
+    }
+    function nearestLabel(el) {
+      if (el.id) {
+        const lbl = document.querySelector(`label[for="${el.id}"]`);
+        if (lbl) return visibleText(lbl).replace(/\*$/, '').trim();
+      }
+      if (el.labels && el.labels[0]) return visibleText(el.labels[0]).replace(/\*$/, '').trim();
+      const al = el.getAttribute('aria-labelledby');
+      if (al) {
+        const t = al.split(/\s+/).map((id) => document.getElementById(id)).filter(Boolean).map(visibleText).join(' ').trim();
+        if (t) return t;
+      }
+      let p = el.parentElement; let hops = 0;
+      while (p && hops < 6) {
+        const lbl = p.querySelector('label, legend, h3, h4');
+        if (lbl && !lbl.contains(el)) {
+          const t = visibleText(lbl).replace(/\*$/, '').trim();
+          if (t && t.length < 200) return t;
+        }
+        p = p.parentElement; hops += 1;
+      }
+      return el.getAttribute('aria-label') || el.placeholder || el.name || el.id || '(unknown)';
+    }
+    // Same emptiness logic as detectFormErrors (kept in sync deliberately).
+    function isEmptyField(el) {
+      const tag = el.tagName.toLowerCase();
+      const type = (el.type || '').toLowerCase();
+      if (type === 'checkbox' || type === 'radio') return !el.checked;
+      if (tag === 'select') {
+        if (!el.value) return true;
+        const selOpt = el.options[el.selectedIndex];
+        if (selOpt && !selOpt.value) return true;
+        return false;
+      }
+      if (type === 'file') return !el.files || el.files.length === 0;
+      if (el.isContentEditable) return !(el.innerText || '').trim();
+      if (el.getAttribute('role') === 'combobox' || tag === 'select') {
+        let wrap = el.closest('[class*="select__control"]');
+        if (!wrap) { let p = el; for (let i = 0; i < 8 && p; i++, p = p.parentElement) { if (/select__control|select-control/i.test(p.className || '')) { wrap = p; break; } } }
+        if (!wrap) wrap = el.closest('[class*="select"], [class*="combobox"], [class*="Select"]') || el.parentElement;
+        if (wrap) {
+          const valueEl = wrap.querySelector('[class*="single-value"], [class*="multi-value"], [class*="multiValue"], [class*="singleValue"], [class*="chip"], [class*="tag"]');
+          if (valueEl && (valueEl.innerText || valueEl.textContent || '').trim()) return false;
+          const wrapText = (wrap.innerText || '').trim();
+          const placeholderEl = wrap.querySelector('[class*="placeholder"]');
+          const placeholderText = placeholderEl ? (placeholderEl.innerText || '').trim() : '';
+          if (wrapText && wrapText !== placeholderText && !/^select\b|^choose\b|^start typing|^\.\.\./i.test(wrapText)) return false;
+        }
+        const v = (el.value || el.innerText || '').trim();
+        return !v;
+      }
+      return !(el.value || '').trim();
+    }
+
+    // A radiogroup / checkbox-set counts as "filled" if ANY member is checked.
+    // We track required groups by name so we don't flag every individual radio.
+    function isRequired(el) {
+      // Programmatic markers are authoritative and field-specific.
+      if (el.required) return true;
+      if (el.getAttribute('aria-required') === 'true') return true;
+
+      // Asterisk/"required" in label text is the common ATS convention, BUT
+      // it must come from THIS field's OWN label — not a sibling's. The Plaid
+      // false-positive ("If yes, please provide further explanation below")
+      // was a conditional field flagged because a climb-5-ancestors walk
+      // scooped up a neighbouring required field's asterisk. Only trust the
+      // directly-associated label:
+      //   1. <label for=id>
+      //   2. el.labels[0]
+      //   3. the SINGLE closest wrapping label/legend that contains ONLY this
+      //      control (not a shared group container with multiple inputs).
+      const labelTextOf = (lblEl) => (lblEl && (lblEl.innerText || lblEl.textContent || '')).trim();
+      const marks = (txt) => /\*\s*$/.test(txt) || /\(\s*required\s*\)/i.test(txt) || /\brequired\b\s*\*?$/i.test(txt);
+
+      if (el.id) {
+        const lbl = document.querySelector(`label[for="${el.id}"]`);
+        if (lbl) return marks(labelTextOf(lbl));
+      }
+      if (el.labels && el.labels[0]) return marks(labelTextOf(el.labels[0]));
+
+      // Closest wrapping label/legend, but ONLY if that container holds a
+      // single control (so we don't inherit a group asterisk meant for a
+      // different required field in the same fieldset).
+      let p = el.parentElement; let hops = 0;
+      while (p && hops < 4) {
+        const labelEl = p.querySelector(':scope > label, :scope > legend, :scope > [class*="label"]');
+        if (labelEl) {
+          const controlsInScope = p.querySelectorAll('input:not([type=hidden]), textarea, select, [role="combobox"], [contenteditable="true"]').length;
+          if (controlsInScope <= 1) return marks(labelTextOf(labelEl));
+          // Shared container with multiple controls — the asterisk isn't
+          // necessarily ours. Stop; treat as not-required unless a
+          // programmatic marker said otherwise (handled above).
+          return false;
+        }
+        p = p.parentElement; hops += 1;
+      }
+      return false;
+    }
+
+    const fields = Array.from(document.querySelectorAll(
+      'input:not([type=hidden]):not([type=submit]):not([type=button]), textarea, select, [role="combobox"], [contenteditable="true"]'
+    ));
+    const emptyFields = [];
+    const seen = new Set();
+    const radioGroupsChecked = new Map(); // name -> bool any-checked
+    const radioGroupRequired = new Map(); // name -> required
+
+    // First pass: tally radio/checkbox groups by name.
+    for (const el of fields) {
+      const type = (el.type || '').toLowerCase();
+      if ((type === 'radio' || type === 'checkbox') && el.name) {
+        if (el.checked) radioGroupsChecked.set(el.name, true);
+        else if (!radioGroupsChecked.has(el.name)) radioGroupsChecked.set(el.name, false);
+        if (isRequired(el)) radioGroupRequired.set(el.name, true);
+      }
+    }
+
+    for (const el of fields) {
+      const type = (el.type || '').toLowerCase();
+      // Skip non-rendered fields entirely (display:none templates etc).
+      const rect = el.getBoundingClientRect();
+      const inDom = rect.width > 0 || rect.height > 0 || el.offsetParent !== null;
+      if (!inDom && type !== 'file') continue; // file inputs are often 0x0 by design
+
+      // Radio/checkbox handled at group level.
+      if ((type === 'radio' || type === 'checkbox') && el.name) {
+        if (!radioGroupRequired.get(el.name)) continue;
+        if (radioGroupsChecked.get(el.name)) continue; // satisfied
+        const key = 'group:' + el.name;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        if (!radioGroupsChecked.get(el.name)) {
+          emptyFields.push({ label: nearestLabel(el).slice(0, 200), selector: `[name="${el.name}"]` });
+        }
+        continue;
+      }
+
+      if (!isRequired(el)) continue;
+      if (!isEmptyField(el)) continue;
+      const label = nearestLabel(el).slice(0, 200);
+      const key = label.toLowerCase();
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const isFile = type === 'file'
+        || /resume|cv\b|cover.?letter|attach|upload/i.test(label);
+      emptyFields.push({ label, isFile, selector: el.id ? `#${el.id}` : (el.name ? `[name="${el.name}"]` : null) });
+    }
+
+    return { hasEmptyRequired: emptyFields.length > 0, emptyFields };
+  });
+}
+
+module.exports = { detectFormErrors, detectRequiredEmpties };

package/orchestrator.js

@@ -13,7 +13,7 @@ const path = require('path');
 const fs = require('fs');
 const { fillFields: legacyFillFields, uploadFile, findNextButton, findSubmitButton, waitForStableDOM, snapshotFieldLabels } = require('./filler');
 const { smartFillPage } = require('./smartFill');
-const { detectFormErrors } = require('./detectFormErrors');
+const { detectFormErrors, detectRequiredEmpties } = require('./detectFormErrors');
 
 // Switchable filler — smart by default, can be killed via config.useSmartFill=false.
 // smartFill.js internally falls back to legacyFillFields if /smartfill/plan-fill
@@ -47,6 +47,7 @@ async function fillFields(page, aep, opts) {
     askUserReasons: result.askUserReasons || [],
     plannedActions: result.planned || 0,
     fellBackToLegacy: !!result.fallback,
+    resumeUploaded: !!result.resumeUploaded,
   };
 }
 const { detectCaptcha, solveCaptcha, injectCaptchaToken } = require('./captcha');
@@ -217,8 +218,14 @@ async function runJob(queueItem, chromeConn, config, reportStatus) {
       }
     }
 
-    // Upload resume if we have a temp file
-    if (tempResumeFile) {
+    // Upload resume ONLY if smartFill didn't already place it. This blanket
+    // fallback predates smartFill's per-field upload_file action; running it
+    // unconditionally dumped the resume into the FIRST file input it found —
+    // which on Greenhouse (resume + cover-letter inputs) put the resume into
+    // the cover-letter slot too. smartFill now reports resumeUploaded, so we
+    // only fall back when the planner genuinely missed the resume field.
+    if (tempResumeFile && !fillResult.resumeUploaded) {
+      console.log('[orchestrator] smartFill did not upload a resume — running fallback uploader.');
       const uploaded = await uploadFile(page, 'input[type="file"], [data-testid*="resume"], button:has-text("Upload")', tempResumeFile);
       if (uploaded) fillResult.filled = (fillResult.filled || 0) + 1;
     }
@@ -432,23 +439,65 @@ async function runJob(queueItem, chromeConn, config, reportStatus) {
 
     console.log(`[orchestrator] Reached review/submit page. Waiting for confirmation...`);
 
+    // ─────────────────────────────────────────────────────────────────────
+    // HONESTY GUARD (the Plaid/Ashby fix). Before we even consider
+    // auto-submitting, check — proactively, not waiting for the ATS to
+    // render an error — whether any REQUIRED field is still empty. The
+    // Plaid run auto-submitted with Location + dates blank because:
+    //   (a) the comboboxes never filled (element-not-visible, now fixed), and
+    //   (b) detectFormErrors is reactive — a clean-looking DOM let
+    //       auto-submit "trust the click."
+    // If required fields are empty, auto-submit is OFF for this job no matter
+    // what the config/agent_config says: we route to REVIEWING so the human
+    // sees exactly which fields are blank. Never silently submit incomplete.
+    // ─────────────────────────────────────────────────────────────────────
+    const skippedLabels = (ctx.skippedFields || []).map((s) => s.label);
+    const requiredCheck = await detectRequiredEmpties(page, { excludeLabels: skippedLabels, resumeUploaded: !!fillResult.resumeUploaded }).catch(() => ({ hasEmptyRequired: false, emptyFields: [] }));
+    let forceReview = false;
+    if (requiredCheck.hasEmptyRequired) {
+      const list = requiredCheck.emptyFields.map((f) => f.label).slice(0, 8).join(', ');
+      console.warn(`[orchestrator] ${requiredCheck.emptyFields.length} required field(s) still EMPTY: ${list}`);
+      console.warn(`[orchestrator] Overriding auto-submit → REVIEWING. Will not submit an incomplete form.`);
+      forceReview = true;
+    }
+
     // Take a screenshot of the review page
     const reviewScreenshot = await page.screenshot({ type: 'jpeg', quality: 70 });
     const reviewKey = await uploadScreenshot(config, reviewScreenshot, `review_${queueId}.jpg`);
 
-    await reportStatus('REVIEWING', {
-      review_screenshot_r2_key: reviewKey || null,
-      step: 'REVIEWING',
-      step_detail: `${cumulativeFilled} fields filled · awaiting your confirm`,
-    });
-
-    // Wait for user to confirm submission from dashboard
-    // OR auto-submit if config.autoSubmit is true
-    if (config.autoSubmit || aep.agent_config?.auto_submit) {
-      const timeout = (aep.agent_config?.review_timeout_seconds || 30) * 1000;
-      await page.waitForTimeout(timeout);
-    } else {
+    if (forceReview) {
+      const list = requiredCheck.emptyFields.map((f) => f.label).slice(0, 8).join(', ');
+      // Report REVIEWING (not NEEDS_ATTENTION): the agent is going to WAIT on
+      // the submit-confirmed flag, and POST /apply-queue/submit/:id only
+      // accepts rows in REVIEWING state. Using NEEDS_ATTENTION here meant the
+      // dashboard's "Resolved" click 400'd and the agent waited forever. The
+      // reason text still tells the user exactly which fields to fill; the
+      // "Submit" button then wakes the agent once they've filled them in Chrome.
+      await reportStatus('REVIEWING', {
+        review_screenshot_r2_key: reviewKey || null,
+        step: 'REVIEWING',
+        step_detail: `${requiredCheck.emptyFields.length} required field(s) need you: ${list}. Fill them in Chrome, then click Submit.`.slice(0, 200),
+        needs_attention_reason: `${requiredCheck.emptyFields.length} required field(s) could not be auto-filled: ${list}. Fill them in your Chrome window, then click Submit.`,
+        fields_filled: cumulativeFilled,
+      });
+      // Wait for the human to fill + confirm. They resolve the blanks in
+      // Chrome, then click Submit on the dashboard.
       await waitForSubmitConfirmation(config, queueId);
+    } else {
+      await reportStatus('REVIEWING', {
+        review_screenshot_r2_key: reviewKey || null,
+        step: 'REVIEWING',
+        step_detail: `${cumulativeFilled} fields filled · awaiting your confirm`,
+      });
+
+      // Wait for user to confirm submission from dashboard
+      // OR auto-submit if config.autoSubmit is true AND the form is complete.
+      if (config.autoSubmit || aep.agent_config?.auto_submit) {
+        const timeout = (aep.agent_config?.review_timeout_seconds || 30) * 1000;
+        await page.waitForTimeout(timeout);
+      } else {
+        await waitForSubmitConfirmation(config, queueId);
+      }
     }
 
     // STEP 6: SUBMITTING
@@ -601,10 +650,32 @@ async function runJob(queueItem, chromeConn, config, reportStatus) {
     let finalState = 'DONE';
     if (verdict.submitted === null) {
       const autoSubmit = config.autoSubmit || aep.agent_config?.auto_submit;
-      if (autoSubmit) {
-        // Auto-submit ON + verifier unavailable: trust the click; the
-        // screenshot becomes the audit trail.
-        console.log(`[orchestrator] Verifier unavailable (source: ${verdict.source}); auto-submit ON — trusting click, screenshot is the receipt.`);
+
+      // Even with auto-submit ON, don't "trust the click" blindly. Two cheap
+      // local signals tell us the submit probably did NOT go through:
+      //   1. The URL never changed to a confirmation pattern (still on the
+      //      form). A successful ATS submit almost always redirects.
+      //   2. Required fields are STILL empty after the click — proof the form
+      //      bounced us (this is the Plaid case: blank Location/dates, no
+      //      redirect, verifier down → it had said "trusting click").
+      // If either holds, we refuse the silent DONE and route to REVIEWING.
+      const stillOnForm = !/thank|confirm|success|applied|submitted/i.test(verdictUrl);
+      const postSkipped = (ctx.skippedFields || []).map((s) => s.label);
+      const postCheck = await detectRequiredEmpties(page, { excludeLabels: postSkipped, resumeUploaded: !!fillResult.resumeUploaded }).catch(() => ({ hasEmptyRequired: false, emptyFields: [] }));
+
+      if (postCheck.hasEmptyRequired) {
+        const list = postCheck.emptyFields.map((f) => f.label).slice(0, 8).join(', ');
+        console.warn(`[orchestrator] After submit, required field(s) STILL empty: ${list}. Not a real submit — REVIEWING.`);
+        finalState = 'REVIEWING';
+      } else if (autoSubmit && !stillOnForm) {
+        // Form complete + URL redirected away + verifier just unavailable:
+        // this is the defensible "trust the click" case. Screenshot is the receipt.
+        console.log(`[orchestrator] Verifier unavailable (source: ${verdict.source}); form complete + redirected — trusting click, screenshot is the receipt.`);
+      } else if (autoSubmit && stillOnForm) {
+        // Auto-submit ON but no redirect and no obvious empties: ambiguous.
+        // Don't claim DONE on a page that still looks like the form.
+        console.warn(`[orchestrator] Auto-submit ON but still on form URL and verifier unavailable — REVIEWING rather than a blind DONE.`);
+        finalState = 'REVIEWING';
       } else {
         // No auto-submit → REVIEWING so the user eyeballs first.
         console.warn(`[orchestrator] Could not verify submission (source: ${verdict.source}). REVIEWING — please eyeball the screenshot + click Submit.`);
@@ -1267,7 +1338,7 @@ async function runExtensionFill({
     fillResult.filled += precision.filled || 0;
   }
 
-  if (tempResumeFile) {
+  if (tempResumeFile && !fillResult.resumeUploaded) {
     const uploaded = await uploadFile(page, 'input[type="file"], [data-testid*="resume"], button:has-text("Upload")', tempResumeFile);
     if (uploaded) fillResult.filled = (fillResult.filled || 0) + 1;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "halo-agent",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "HALO local apply agent — auto-fills job applications using your real Chrome session",
   "main": "index.js",
   "bin": {

package/smartFill.js

@@ -58,7 +58,50 @@ async function executePlanItem(page, item, fieldByMmid, ctx) {
     visible = await locator.isVisible({ timeout: 800 }).catch(() => false);
   }
   if (!visible) {
-    return { ok: false, reason: `element not visible (mmid=${item.mmid}${field.frameUrl ? ', in-frame' : ''})` };
+    // The scanned element being invisible doesn't always mean "give up." Many
+    // ATSes (Ashby, react-select) render the REAL combobox <input> at 0x0 and
+    // expose only a clickable WRAPPER (".select__control", a styled div, the
+    // value-display button). scanAccessibility tags the inner input, so the
+    // executor would FAIL "element not visible" and the required field stays
+    // empty — exactly the Ashby Location/School/date failure. Recover by
+    // re-pointing the locator at the nearest visible interactive ancestor and
+    // letting the dropdown handlers below open it.
+    const looksLikeDropdown = field.role === 'combobox' || field.role === 'listbox'
+      || /select|combobox|dropdown|month|year|listbox/i.test(String(field.selectorHint || ''))
+      || (Array.isArray(field.options) && field.options.length > 0);
+    const isOpenable = looksLikeDropdown
+      || item.action === 'click_option' || item.action === 'select_option';
+    if (isOpenable) {
+      const wrapperSel = await locator.evaluate((el) => {
+        // Climb to the closest ancestor that's actually rendered (non-zero box)
+        // and looks interactive (select-control class, role, or just a sized
+        // container holding this input). Tag it so Playwright can target it.
+        const sized = (n) => { const r = n.getBoundingClientRect?.(); return r && (r.width > 0 || r.height > 0); };
+        let p = el;
+        for (let i = 0; i < 8 && p; i++, p = p.parentElement) {
+          const cls = String(p.className || '');
+          const looksControl = /select__control|select-control|control|combobox|dropdown|trigger|css-/i.test(cls)
+            || p.getAttribute?.('role') === 'combobox'
+            || p.getAttribute?.('aria-haspopup');
+          if (sized(p) && (looksControl || p !== el)) {
+            const cid = 'halo-wrap-' + Math.random().toString(36).slice(2, 8);
+            p.setAttribute('data-halo-wrap', cid);
+            return cid;
+          }
+        }
+        return null;
+      }).catch(() => null);
+      if (wrapperSel) {
+        const wrap = root.locator(`[data-halo-wrap="${wrapperSel}"]`).first();
+        if (await wrap.isVisible({ timeout: 600 }).catch(() => false)) {
+          locator = wrap;
+          visible = true;
+        }
+      }
+    }
+    if (!visible) {
+      return { ok: false, reason: `element not visible (mmid=${item.mmid}${field.frameUrl ? ', in-frame' : ''})` };
+    }
   }
 
   switch (item.action) {
@@ -738,6 +781,7 @@ async function smartFillPage(page, aep, options) {
   const fieldByMmid = new Map(fields.map((f) => [String(f.mmid), f]));
   const planByMmid = new Map(plan.map((p) => [String(p.mmid), p]));
   let filled = 0, skipped = 0, failed = 0;
+  let resumeUploaded = false; // so the orchestrator can skip its blanket fallback
   const askUserReasons = [];
 
   for (const f of fields) {
@@ -764,9 +808,24 @@ async function smartFillPage(page, aep, options) {
       if (item.action === 'skip') {
         console.log(`[smartFill] skip "${labelShort}" — ${result.reason}`);
         skipped += 1;
+        // Record the planner's deliberate skips so the orchestrator's
+        // required-empty guard can EXCLUDE them. The planner has full
+        // context (it saw "If yes…" conditional dependencies); the guard is
+        // a blind DOM walk. A field the planner intentionally left blank
+        // (conditional-not-applicable, honeypot, optional) must not be
+        // mistaken for an unfilled required field.
+        if (ctx && Array.isArray(ctx.skippedFields) && f.label) {
+          ctx.skippedFields.push({ label: f.label, reason: (item.reasoning || result.reason || '').slice(0, 160) });
+        }
       } else {
         console.log(`[smartFill] ${item.action} "${labelShort}" — ${result.reason}${item.reasoning ? ` (why: ${item.reasoning.slice(0, 80)})` : ''}`);
         filled += 1;
+        // Note a successful resume upload so the orchestrator doesn't run its
+        // legacy blanket "upload resume to the first file input" fallback,
+        // which was dumping the resume into the COVER-LETTER slot too.
+        if (item.action === 'upload_file' && String(item.value).toLowerCase().trim() !== 'cover_letter') {
+          resumeUploaded = true;
+        }
         // Track in ctx for cross-page dedup
         if (ctx && ctx.answeredFields) {
           ctx.answeredFields.set(f.label || f.selectorHint, {
@@ -784,7 +843,7 @@ async function smartFillPage(page, aep, options) {
     }
   }
 
-  return { filled, skipped, failed, askUserReasons, planned: plan.length, fallback: false };
+  return { filled, skipped, failed, askUserReasons, planned: plan.length, fallback: false, resumeUploaded };
 }
 
 module.exports = { smartFillPage };