job-forge 2.10.0 → 2.12.0

package/.cursor/rules/main.mdc

@@ -419,6 +419,8 @@ These blocks come from two distinct root causes and require different responses:
 
 **Rule — do NOT loop retrying a class B block.** One retry with `imeFriendly: true` is the correct test for class A. If the same spam message fires after a clean `imeFriendly` refill, stop, mark Failed, move on. Repeated retries waste subagent time and do not change the outcome.
 
+**Class B fix — BYO residential proxy** (added 2026-04-20 via Geometra MCP v1.59.0). When the candidate has configured `proxy:` in `config/profile.yml`, every `geometra_connect` call threads that proxy through to Chromium, which flips the outbound IP from datacenter to residential/mobile and collapses most class-B failures. See the "BYO Residential Proxy" reference section below. Without a configured proxy, class B stays Failed.
+
 **Known-block Ashby tenants (2026-04-19 empirical observations).** These tenants fired class B on every attempted submit from a headless datacenter-IP proxy. Orchestrators planning apply dispatches should assume these tenants will Fail in headless — prioritize other portals, or skip same-tenant siblings after a confirmed class B to avoid burning subagent slots:
 
 - Vellum, Linear, Vanta, River Financial, Higharc, Trace Labs, Solace Health, Unstructured, ClickUp, Zapier, Deepgram, Ramp, WorkOS, Ashby (self-tenant), Perplexity, **Goody**, **Starbridge**, **Graphite**, **Prompt Health**, **Vantage**
@@ -510,6 +512,8 @@ geometra_connect({ pageUrl: "https://...", isolated: true, headless: true, slowM
 
 **Wrong:** running `geometra_connect` without `isolated: true` when submitting multiple forms concurrently. The forms may share state and produce incorrect submissions.
 
+**With a configured proxy,** add `proxy: { server, username?, password?, bypass? }` to the same call — see "BYO Residential Proxy" below. The reusable-proxy pool is partitioned by proxy identity, so mixing direct and proxied sessions across parallel rounds is safe.
+
 ### Session Reuse — When Subagents Cannot Reach Existing Sessions
 
 Subagents launched via the `task` tool start with a fresh context and cannot automatically attach to Chromium sessions spawned by a previous orchestrator session. If you dispatch a subagent to fill a form in session `s16`, but `s16` was created by a previous opencode session, the subagent's MCP calls will silently fail (returning empty results) because the subagent's MCP server has no knowledge of `s16`.
@@ -553,6 +557,17 @@ Step 2:  geometra_disconnect({ closeBrowser: true })
 Step 3:  geometra_connect({ pageUrl: "<the URL the orchestrator gave you>", isolated: true, headless: true, slowMo: 350 })
 ```
 
+**If the orchestrator passed a `proxy` object in the task prompt** (sourced from `config/profile.yml`), add it to Step 3:
+
+```
+Step 3:  geometra_connect({
+           pageUrl: "<URL>", isolated: true, headless: true, slowMo: 350,
+           proxy: { server: "...", username: "...", password: "...", bypass: "..." }
+         })
+```
+
+Pass the proxy object through unchanged. Do NOT paraphrase or drop fields — `username`/`password`/`bypass` are optional, so only include what the orchestrator gave you. See the "BYO Residential Proxy" reference section for the why.
+
 **DO NOT** skip Step 1 or Step 2. **DO NOT** think about whether it's needed. **DO NOT** look at `geometra_list_sessions` output and reason about it — just always call `geometra_disconnect({ closeBrowser: true })` next. The disconnect is a no-op if the pool is empty, and a poison-cure if it isn't.
 
 **Single exception:** if the orchestrator's task prompt says literally "attach to sessionId X" or "use existing session X", skip Steps 1-3 and call `geometra_page_model({ sessionId: "X" })` directly.
@@ -574,7 +589,64 @@ When the orchestrator dispatches an `apply` (form-fill + submit), pick the subag
 
 ---
 
-## Stack and Conventions
+## BYO Residential Proxy — opt-in outbound-IP override
+
+**Problem:** on 2026-04-19 cycle 4, 5/5 untested Ashby tenants and 100% of Dropbox-class Cloudflare-fronted portals fingerprint-blocked headless Chromium from datacenter IPs. `imeFriendly: true` fixes class A (React validation lag) but has zero effect on class B (environment fingerprint). There is no in-session software-only fix for class B: the server decided the session is a bot before the form response was rendered.
+
+**Fix:** route the spawned Chromium through a residential or mobile proxy the candidate already pays for. Geometra MCP v1.59.0 added a `proxy: { server, username?, password?, bypass? }` parameter on `geometra_connect` and `geometra_prepare_browser` that forwards straight to Playwright's `chromium.launch({ proxy })`. The outbound IP becomes residential/mobile, and the fingerprint check that fired class B no longer trips.
+
+**Opt-in, BYO.** JobForge does NOT bundle or resell proxy bandwidth — the candidate brings their own provider (Bright Data, Oxylabs, SOAX, Smartproxy, mobile hotspot, self-hosted SOCKS). Without a configured proxy, JobForge behavior is unchanged from v2.11.0 and earlier.
+
+### Where the proxy config lives
+
+`config/profile.yml` → top-level `proxy:` block:
+
+```yaml
+proxy:
+  server: "http://residential.example.com:8080"   # http://, https://, or socks5://
+  username: "your-proxy-username"                  # optional
+  password: "your-proxy-password"                  # optional
+  bypass: "*.internal,localhost"                   # optional
+```
+
+See `config/profile.example.yml` for the commented-out template.
+
+### How the orchestrator threads it through
+
+**Orchestrator responsibilities:**
+
+1. On session start, read `config/profile.yml` once. If a `proxy:` block is present, capture it as the `PROXY_CONFIG` for the session.
+2. When dispatching any subagent whose work involves a `geometra_connect` call, include `PROXY_CONFIG` verbatim in the task prompt. Example dispatch prompt line: "Pass `proxy: { server: ..., username: ..., password: ..., bypass: ... }` to every `geometra_connect` call you make."
+3. When the orchestrator itself opens a Chromium session (single-application interactive flow), include the same `proxy` object in its own `geometra_connect` call.
+4. If `proxy:` is absent from `profile.yml`, skip the param entirely. Do NOT invent a proxy URL or leave a stale placeholder.
+
+**Subagent responsibilities:**
+
+1. If the task prompt includes a `proxy` object, pass it through to `geometra_connect` and any `geometra_prepare_browser` calls unchanged.
+2. If the task prompt does NOT include a proxy object, run without one.
+3. Never second-guess the proxy field — if the orchestrator sourced it from `profile.yml`, it's authoritative.
+
+### When proxy use is load-bearing
+
+Apply these rules when deciding whether the proxy is worth waiting for:
+
+- **Required** for known-block Ashby tenants (see the class-B list in the Ashby section above), for `happydance.website` / Cloudflare-fronted ATSes, and for any Lever tenant that previously failed in the class-B pattern.
+- **Recommended** for any Ashby tenant NOT on the class-A-compatible list (base rate prior: ~80-90% block headless).
+- **Optional** for Greenhouse, Workday, Lever-clean tenants — these accept datacenter IPs today; using the proxy adds ~100ms per frame but no material downside.
+- **Not useful** for Typeform (Geometra-unsupported), Avature native-select lag (not a fingerprint issue), JazzHR+reCAPTCHA (reCAPTCHA scores unrelated to IP), Breezy (tenant-configured per-IP throttle — proxy may help or may hit a fresh throttle).
+
+### Pool partitioning — why mixed runs are safe
+
+The Geometra MCP partitions its reusable-proxy pool by `(server, username, bypass)` — see `@geometra/mcp@1.59.0` release notes. A direct session and a proxied session NEVER share a Chromium instance, and two sessions with different proxy configs don't pool either. Practical consequence: flipping `proxy:` on or off in `profile.yml` mid-session is safe — the next `geometra_connect` just opens a fresh Chromium in its own pool partition.
+
+### Troubleshooting
+
+| Symptom | Diagnosis |
+|---|---|
+| `Error: Failed to connect to proxy` immediately after `geometra_connect` | Proxy URL is wrong / unreachable. Verify the `server:` field hits the right host:port. |
+| `407 Proxy Authentication Required` | `username` or `password` is wrong or missing. Many residential providers require both. |
+| Class-B submit failure persists even with proxy set | (a) proxy is a datacenter proxy, not residential; (b) same tenant IP-banned your specific proxy's IP pool; (c) tenant uses TLS fingerprint / canvas fingerprint, not IP — switch to a fresh Chromium (isolated: true) and retry once, else mark Failed. |
+| Every `geometra_connect` is 3-5s slower than before | Expected — residential proxies add latency. Trade-off for higher submit-success rate. Do NOT revert unless the acceptance-rate lift is < 5%. |
 
 - Node.js (mjs modules), Geometra MCP (PDF + scraping + form filling), Gmail MCP (email), YAML (config), HTML/CSS (template), Markdown (data)
 

package/AGENTS.md

@@ -414,6 +414,8 @@ These blocks come from two distinct root causes and require different responses:
 
 **Rule — do NOT loop retrying a class B block.** One retry with `imeFriendly: true` is the correct test for class A. If the same spam message fires after a clean `imeFriendly` refill, stop, mark Failed, move on. Repeated retries waste subagent time and do not change the outcome.
 
+**Class B fix — BYO residential proxy** (added 2026-04-20 via Geometra MCP v1.59.0). When the candidate has configured `proxy:` in `config/profile.yml`, every `geometra_connect` call threads that proxy through to Chromium, which flips the outbound IP from datacenter to residential/mobile and collapses most class-B failures. See the "BYO Residential Proxy" reference section below. Without a configured proxy, class B stays Failed.
+
 **Known-block Ashby tenants (2026-04-19 empirical observations).** These tenants fired class B on every attempted submit from a headless datacenter-IP proxy. Orchestrators planning apply dispatches should assume these tenants will Fail in headless — prioritize other portals, or skip same-tenant siblings after a confirmed class B to avoid burning subagent slots:
 
 - Vellum, Linear, Vanta, River Financial, Higharc, Trace Labs, Solace Health, Unstructured, ClickUp, Zapier, Deepgram, Ramp, WorkOS, Ashby (self-tenant), Perplexity, **Goody**, **Starbridge**, **Graphite**, **Prompt Health**, **Vantage**
@@ -505,6 +507,8 @@ geometra_connect({ pageUrl: "https://...", isolated: true, headless: true, slowM
 
 **Wrong:** running `geometra_connect` without `isolated: true` when submitting multiple forms concurrently. The forms may share state and produce incorrect submissions.
 
+**With a configured proxy,** add `proxy: { server, username?, password?, bypass? }` to the same call — see "BYO Residential Proxy" below. The reusable-proxy pool is partitioned by proxy identity, so mixing direct and proxied sessions across parallel rounds is safe.
+
 ### Session Reuse — When Subagents Cannot Reach Existing Sessions
 
 Subagents launched via the `task` tool start with a fresh context and cannot automatically attach to Chromium sessions spawned by a previous orchestrator session. If you dispatch a subagent to fill a form in session `s16`, but `s16` was created by a previous opencode session, the subagent's MCP calls will silently fail (returning empty results) because the subagent's MCP server has no knowledge of `s16`.
@@ -548,6 +552,17 @@ Step 2:  geometra_disconnect({ closeBrowser: true })
 Step 3:  geometra_connect({ pageUrl: "<the URL the orchestrator gave you>", isolated: true, headless: true, slowMo: 350 })
 ```
 
+**If the orchestrator passed a `proxy` object in the task prompt** (sourced from `config/profile.yml`), add it to Step 3:
+
+```
+Step 3:  geometra_connect({
+           pageUrl: "<URL>", isolated: true, headless: true, slowMo: 350,
+           proxy: { server: "...", username: "...", password: "...", bypass: "..." }
+         })
+```
+
+Pass the proxy object through unchanged. Do NOT paraphrase or drop fields — `username`/`password`/`bypass` are optional, so only include what the orchestrator gave you. See the "BYO Residential Proxy" reference section for the why.
+
 **DO NOT** skip Step 1 or Step 2. **DO NOT** think about whether it's needed. **DO NOT** look at `geometra_list_sessions` output and reason about it — just always call `geometra_disconnect({ closeBrowser: true })` next. The disconnect is a no-op if the pool is empty, and a poison-cure if it isn't.
 
 **Single exception:** if the orchestrator's task prompt says literally "attach to sessionId X" or "use existing session X", skip Steps 1-3 and call `geometra_page_model({ sessionId: "X" })` directly.
@@ -569,7 +584,64 @@ When the orchestrator dispatches an `apply` (form-fill + submit), pick the subag
 
 ---
 
-## Stack and Conventions
+## BYO Residential Proxy — opt-in outbound-IP override
+
+**Problem:** on 2026-04-19 cycle 4, 5/5 untested Ashby tenants and 100% of Dropbox-class Cloudflare-fronted portals fingerprint-blocked headless Chromium from datacenter IPs. `imeFriendly: true` fixes class A (React validation lag) but has zero effect on class B (environment fingerprint). There is no in-session software-only fix for class B: the server decided the session is a bot before the form response was rendered.
+
+**Fix:** route the spawned Chromium through a residential or mobile proxy the candidate already pays for. Geometra MCP v1.59.0 added a `proxy: { server, username?, password?, bypass? }` parameter on `geometra_connect` and `geometra_prepare_browser` that forwards straight to Playwright's `chromium.launch({ proxy })`. The outbound IP becomes residential/mobile, and the fingerprint check that fired class B no longer trips.
+
+**Opt-in, BYO.** JobForge does NOT bundle or resell proxy bandwidth — the candidate brings their own provider (Bright Data, Oxylabs, SOAX, Smartproxy, mobile hotspot, self-hosted SOCKS). Without a configured proxy, JobForge behavior is unchanged from v2.11.0 and earlier.
+
+### Where the proxy config lives
+
+`config/profile.yml` → top-level `proxy:` block:
+
+```yaml
+proxy:
+  server: "http://residential.example.com:8080"   # http://, https://, or socks5://
+  username: "your-proxy-username"                  # optional
+  password: "your-proxy-password"                  # optional
+  bypass: "*.internal,localhost"                   # optional
+```
+
+See `config/profile.example.yml` for the commented-out template.
+
+### How the orchestrator threads it through
+
+**Orchestrator responsibilities:**
+
+1. On session start, read `config/profile.yml` once. If a `proxy:` block is present, capture it as the `PROXY_CONFIG` for the session.
+2. When dispatching any subagent whose work involves a `geometra_connect` call, include `PROXY_CONFIG` verbatim in the task prompt. Example dispatch prompt line: "Pass `proxy: { server: ..., username: ..., password: ..., bypass: ... }` to every `geometra_connect` call you make."
+3. When the orchestrator itself opens a Chromium session (single-application interactive flow), include the same `proxy` object in its own `geometra_connect` call.
+4. If `proxy:` is absent from `profile.yml`, skip the param entirely. Do NOT invent a proxy URL or leave a stale placeholder.
+
+**Subagent responsibilities:**
+
+1. If the task prompt includes a `proxy` object, pass it through to `geometra_connect` and any `geometra_prepare_browser` calls unchanged.
+2. If the task prompt does NOT include a proxy object, run without one.
+3. Never second-guess the proxy field — if the orchestrator sourced it from `profile.yml`, it's authoritative.
+
+### When proxy use is load-bearing
+
+Apply these rules when deciding whether the proxy is worth waiting for:
+
+- **Required** for known-block Ashby tenants (see the class-B list in the Ashby section above), for `happydance.website` / Cloudflare-fronted ATSes, and for any Lever tenant that previously failed in the class-B pattern.
+- **Recommended** for any Ashby tenant NOT on the class-A-compatible list (base rate prior: ~80-90% block headless).
+- **Optional** for Greenhouse, Workday, Lever-clean tenants — these accept datacenter IPs today; using the proxy adds ~100ms per frame but no material downside.
+- **Not useful** for Typeform (Geometra-unsupported), Avature native-select lag (not a fingerprint issue), JazzHR+reCAPTCHA (reCAPTCHA scores unrelated to IP), Breezy (tenant-configured per-IP throttle — proxy may help or may hit a fresh throttle).
+
+### Pool partitioning — why mixed runs are safe
+
+The Geometra MCP partitions its reusable-proxy pool by `(server, username, bypass)` — see `@geometra/mcp@1.59.0` release notes. A direct session and a proxied session NEVER share a Chromium instance, and two sessions with different proxy configs don't pool either. Practical consequence: flipping `proxy:` on or off in `profile.yml` mid-session is safe — the next `geometra_connect` just opens a fresh Chromium in its own pool partition.
+
+### Troubleshooting
+
+| Symptom | Diagnosis |
+|---|---|
+| `Error: Failed to connect to proxy` immediately after `geometra_connect` | Proxy URL is wrong / unreachable. Verify the `server:` field hits the right host:port. |
+| `407 Proxy Authentication Required` | `username` or `password` is wrong or missing. Many residential providers require both. |
+| Class-B submit failure persists even with proxy set | (a) proxy is a datacenter proxy, not residential; (b) same tenant IP-banned your specific proxy's IP pool; (c) tenant uses TLS fingerprint / canvas fingerprint, not IP — switch to a fresh Chromium (isolated: true) and retry once, else mark Failed. |
+| Every `geometra_connect` is 3-5s slower than before | Expected — residential proxies add latency. Trade-off for higher submit-success rate. Do NOT revert unless the acceptance-rate lift is < 5%. |
 
 - Node.js (mjs modules), Geometra MCP (PDF + scraping + form filling), Gmail MCP (email), YAML (config), HTML/CSS (template), Markdown (data)
 

package/CLAUDE.md

@@ -414,6 +414,8 @@ These blocks come from two distinct root causes and require different responses:
 
 **Rule — do NOT loop retrying a class B block.** One retry with `imeFriendly: true` is the correct test for class A. If the same spam message fires after a clean `imeFriendly` refill, stop, mark Failed, move on. Repeated retries waste subagent time and do not change the outcome.
 
+**Class B fix — BYO residential proxy** (added 2026-04-20 via Geometra MCP v1.59.0). When the candidate has configured `proxy:` in `config/profile.yml`, every `geometra_connect` call threads that proxy through to Chromium, which flips the outbound IP from datacenter to residential/mobile and collapses most class-B failures. See the "BYO Residential Proxy" reference section below. Without a configured proxy, class B stays Failed.
+
 **Known-block Ashby tenants (2026-04-19 empirical observations).** These tenants fired class B on every attempted submit from a headless datacenter-IP proxy. Orchestrators planning apply dispatches should assume these tenants will Fail in headless — prioritize other portals, or skip same-tenant siblings after a confirmed class B to avoid burning subagent slots:
 
 - Vellum, Linear, Vanta, River Financial, Higharc, Trace Labs, Solace Health, Unstructured, ClickUp, Zapier, Deepgram, Ramp, WorkOS, Ashby (self-tenant), Perplexity, **Goody**, **Starbridge**, **Graphite**, **Prompt Health**, **Vantage**
@@ -505,6 +507,8 @@ geometra_connect({ pageUrl: "https://...", isolated: true, headless: true, slowM
 
 **Wrong:** running `geometra_connect` without `isolated: true` when submitting multiple forms concurrently. The forms may share state and produce incorrect submissions.
 
+**With a configured proxy,** add `proxy: { server, username?, password?, bypass? }` to the same call — see "BYO Residential Proxy" below. The reusable-proxy pool is partitioned by proxy identity, so mixing direct and proxied sessions across parallel rounds is safe.
+
 ### Session Reuse — When Subagents Cannot Reach Existing Sessions
 
 Subagents launched via the `task` tool start with a fresh context and cannot automatically attach to Chromium sessions spawned by a previous orchestrator session. If you dispatch a subagent to fill a form in session `s16`, but `s16` was created by a previous opencode session, the subagent's MCP calls will silently fail (returning empty results) because the subagent's MCP server has no knowledge of `s16`.
@@ -548,6 +552,17 @@ Step 2:  geometra_disconnect({ closeBrowser: true })
 Step 3:  geometra_connect({ pageUrl: "<the URL the orchestrator gave you>", isolated: true, headless: true, slowMo: 350 })
 ```
 
+**If the orchestrator passed a `proxy` object in the task prompt** (sourced from `config/profile.yml`), add it to Step 3:
+
+```
+Step 3:  geometra_connect({
+           pageUrl: "<URL>", isolated: true, headless: true, slowMo: 350,
+           proxy: { server: "...", username: "...", password: "...", bypass: "..." }
+         })
+```
+
+Pass the proxy object through unchanged. Do NOT paraphrase or drop fields — `username`/`password`/`bypass` are optional, so only include what the orchestrator gave you. See the "BYO Residential Proxy" reference section for the why.
+
 **DO NOT** skip Step 1 or Step 2. **DO NOT** think about whether it's needed. **DO NOT** look at `geometra_list_sessions` output and reason about it — just always call `geometra_disconnect({ closeBrowser: true })` next. The disconnect is a no-op if the pool is empty, and a poison-cure if it isn't.
 
 **Single exception:** if the orchestrator's task prompt says literally "attach to sessionId X" or "use existing session X", skip Steps 1-3 and call `geometra_page_model({ sessionId: "X" })` directly.
@@ -569,7 +584,64 @@ When the orchestrator dispatches an `apply` (form-fill + submit), pick the subag
 
 ---
 
-## Stack and Conventions
+## BYO Residential Proxy — opt-in outbound-IP override
+
+**Problem:** on 2026-04-19 cycle 4, 5/5 untested Ashby tenants and 100% of Dropbox-class Cloudflare-fronted portals fingerprint-blocked headless Chromium from datacenter IPs. `imeFriendly: true` fixes class A (React validation lag) but has zero effect on class B (environment fingerprint). There is no in-session software-only fix for class B: the server decided the session is a bot before the form response was rendered.
+
+**Fix:** route the spawned Chromium through a residential or mobile proxy the candidate already pays for. Geometra MCP v1.59.0 added a `proxy: { server, username?, password?, bypass? }` parameter on `geometra_connect` and `geometra_prepare_browser` that forwards straight to Playwright's `chromium.launch({ proxy })`. The outbound IP becomes residential/mobile, and the fingerprint check that fired class B no longer trips.
+
+**Opt-in, BYO.** JobForge does NOT bundle or resell proxy bandwidth — the candidate brings their own provider (Bright Data, Oxylabs, SOAX, Smartproxy, mobile hotspot, self-hosted SOCKS). Without a configured proxy, JobForge behavior is unchanged from v2.11.0 and earlier.
+
+### Where the proxy config lives
+
+`config/profile.yml` → top-level `proxy:` block:
+
+```yaml
+proxy:
+  server: "http://residential.example.com:8080"   # http://, https://, or socks5://
+  username: "your-proxy-username"                  # optional
+  password: "your-proxy-password"                  # optional
+  bypass: "*.internal,localhost"                   # optional
+```
+
+See `config/profile.example.yml` for the commented-out template.
+
+### How the orchestrator threads it through
+
+**Orchestrator responsibilities:**
+
+1. On session start, read `config/profile.yml` once. If a `proxy:` block is present, capture it as the `PROXY_CONFIG` for the session.
+2. When dispatching any subagent whose work involves a `geometra_connect` call, include `PROXY_CONFIG` verbatim in the task prompt. Example dispatch prompt line: "Pass `proxy: { server: ..., username: ..., password: ..., bypass: ... }` to every `geometra_connect` call you make."
+3. When the orchestrator itself opens a Chromium session (single-application interactive flow), include the same `proxy` object in its own `geometra_connect` call.
+4. If `proxy:` is absent from `profile.yml`, skip the param entirely. Do NOT invent a proxy URL or leave a stale placeholder.
+
+**Subagent responsibilities:**
+
+1. If the task prompt includes a `proxy` object, pass it through to `geometra_connect` and any `geometra_prepare_browser` calls unchanged.
+2. If the task prompt does NOT include a proxy object, run without one.
+3. Never second-guess the proxy field — if the orchestrator sourced it from `profile.yml`, it's authoritative.
+
+### When proxy use is load-bearing
+
+Apply these rules when deciding whether the proxy is worth waiting for:
+
+- **Required** for known-block Ashby tenants (see the class-B list in the Ashby section above), for `happydance.website` / Cloudflare-fronted ATSes, and for any Lever tenant that previously failed in the class-B pattern.
+- **Recommended** for any Ashby tenant NOT on the class-A-compatible list (base rate prior: ~80-90% block headless).
+- **Optional** for Greenhouse, Workday, Lever-clean tenants — these accept datacenter IPs today; using the proxy adds ~100ms per frame but no material downside.
+- **Not useful** for Typeform (Geometra-unsupported), Avature native-select lag (not a fingerprint issue), JazzHR+reCAPTCHA (reCAPTCHA scores unrelated to IP), Breezy (tenant-configured per-IP throttle — proxy may help or may hit a fresh throttle).
+
+### Pool partitioning — why mixed runs are safe
+
+The Geometra MCP partitions its reusable-proxy pool by `(server, username, bypass)` — see `@geometra/mcp@1.59.0` release notes. A direct session and a proxied session NEVER share a Chromium instance, and two sessions with different proxy configs don't pool either. Practical consequence: flipping `proxy:` on or off in `profile.yml` mid-session is safe — the next `geometra_connect` just opens a fresh Chromium in its own pool partition.
+
+### Troubleshooting
+
+| Symptom | Diagnosis |
+|---|---|
+| `Error: Failed to connect to proxy` immediately after `geometra_connect` | Proxy URL is wrong / unreachable. Verify the `server:` field hits the right host:port. |
+| `407 Proxy Authentication Required` | `username` or `password` is wrong or missing. Many residential providers require both. |
+| Class-B submit failure persists even with proxy set | (a) proxy is a datacenter proxy, not residential; (b) same tenant IP-banned your specific proxy's IP pool; (c) tenant uses TLS fingerprint / canvas fingerprint, not IP — switch to a fresh Chromium (isolated: true) and retry once, else mark Failed. |
+| Every `geometra_connect` is 3-5s slower than before | Expected — residential proxies add latency. Trade-off for higher submit-success rate. Do NOT revert unless the acceptance-rate lift is < 5%. |
 
 - Node.js (mjs modules), Geometra MCP (PDF + scraping + form filling), Gmail MCP (email), YAML (config), HTML/CSS (template), Markdown (data)
 

package/config/profile.example.yml

@@ -86,3 +86,23 @@ location_constraints:
     - US
   requires_visa_sponsorship: false     # true → roles in non-authorized countries are blocked unless
                                        # the JD explicitly mentions visa sponsorship
+
+# Optional outbound proxy for the Chromium that Geometra MCP spawns.
+# Uncomment and fill in to route ALL browser traffic through a residential /
+# mobile / SOCKS proxy you already pay for. Bypasses the datacenter-IP
+# fingerprinting that drives ~80-90% of Ashby / Lever / Cloudflare-fronted
+# "flagged as possible spam" submit failures in headless mode.
+#
+# BYO — JobForge does NOT bundle or resell proxy bandwidth. Pick a residential
+# or mobile provider (Bright Data, Oxylabs, SOAX, Smartproxy, etc.), or a
+# mobile hotspot, or your own SOCKS relay. Required: Geometra MCP >= 1.59.0.
+#
+# When present, the apply / scan / auto-pipeline modes thread this into every
+# `geometra_connect` call as `proxy: {...}`. Pool is partitioned by proxy
+# identity so direct and proxied sessions never share a Chromium.
+#
+# proxy:
+#   server: "http://residential.example.com:8080"   # http://, https://, or socks5://
+#   username: "your-proxy-username"                  # optional; omit if no auth
+#   password: "your-proxy-password"                  # optional; omit if no auth
+#   bypass: "*.internal,localhost"                   # optional comma-separated host patterns

package/iso/instructions.md

@@ -414,6 +414,8 @@ These blocks come from two distinct root causes and require different responses:
 
 **Rule — do NOT loop retrying a class B block.** One retry with `imeFriendly: true` is the correct test for class A. If the same spam message fires after a clean `imeFriendly` refill, stop, mark Failed, move on. Repeated retries waste subagent time and do not change the outcome.
 
+**Class B fix — BYO residential proxy** (added 2026-04-20 via Geometra MCP v1.59.0). When the candidate has configured `proxy:` in `config/profile.yml`, every `geometra_connect` call threads that proxy through to Chromium, which flips the outbound IP from datacenter to residential/mobile and collapses most class-B failures. See the "BYO Residential Proxy" reference section below. Without a configured proxy, class B stays Failed.
+
 **Known-block Ashby tenants (2026-04-19 empirical observations).** These tenants fired class B on every attempted submit from a headless datacenter-IP proxy. Orchestrators planning apply dispatches should assume these tenants will Fail in headless — prioritize other portals, or skip same-tenant siblings after a confirmed class B to avoid burning subagent slots:
 
 - Vellum, Linear, Vanta, River Financial, Higharc, Trace Labs, Solace Health, Unstructured, ClickUp, Zapier, Deepgram, Ramp, WorkOS, Ashby (self-tenant), Perplexity, **Goody**, **Starbridge**, **Graphite**, **Prompt Health**, **Vantage**
@@ -505,6 +507,8 @@ geometra_connect({ pageUrl: "https://...", isolated: true, headless: true, slowM
 
 **Wrong:** running `geometra_connect` without `isolated: true` when submitting multiple forms concurrently. The forms may share state and produce incorrect submissions.
 
+**With a configured proxy,** add `proxy: { server, username?, password?, bypass? }` to the same call — see "BYO Residential Proxy" below. The reusable-proxy pool is partitioned by proxy identity, so mixing direct and proxied sessions across parallel rounds is safe.
+
 ### Session Reuse — When Subagents Cannot Reach Existing Sessions
 
 Subagents launched via the `task` tool start with a fresh context and cannot automatically attach to Chromium sessions spawned by a previous orchestrator session. If you dispatch a subagent to fill a form in session `s16`, but `s16` was created by a previous opencode session, the subagent's MCP calls will silently fail (returning empty results) because the subagent's MCP server has no knowledge of `s16`.
@@ -548,6 +552,17 @@ Step 2:  geometra_disconnect({ closeBrowser: true })
 Step 3:  geometra_connect({ pageUrl: "<the URL the orchestrator gave you>", isolated: true, headless: true, slowMo: 350 })
 ```
 
+**If the orchestrator passed a `proxy` object in the task prompt** (sourced from `config/profile.yml`), add it to Step 3:
+
+```
+Step 3:  geometra_connect({
+           pageUrl: "<URL>", isolated: true, headless: true, slowMo: 350,
+           proxy: { server: "...", username: "...", password: "...", bypass: "..." }
+         })
+```
+
+Pass the proxy object through unchanged. Do NOT paraphrase or drop fields — `username`/`password`/`bypass` are optional, so only include what the orchestrator gave you. See the "BYO Residential Proxy" reference section for the why.
+
 **DO NOT** skip Step 1 or Step 2. **DO NOT** think about whether it's needed. **DO NOT** look at `geometra_list_sessions` output and reason about it — just always call `geometra_disconnect({ closeBrowser: true })` next. The disconnect is a no-op if the pool is empty, and a poison-cure if it isn't.
 
 **Single exception:** if the orchestrator's task prompt says literally "attach to sessionId X" or "use existing session X", skip Steps 1-3 and call `geometra_page_model({ sessionId: "X" })` directly.
@@ -569,7 +584,64 @@ When the orchestrator dispatches an `apply` (form-fill + submit), pick the subag
 
 ---
 
-## Stack and Conventions
+## BYO Residential Proxy — opt-in outbound-IP override
+
+**Problem:** on 2026-04-19 cycle 4, 5/5 untested Ashby tenants and 100% of Dropbox-class Cloudflare-fronted portals fingerprint-blocked headless Chromium from datacenter IPs. `imeFriendly: true` fixes class A (React validation lag) but has zero effect on class B (environment fingerprint). There is no in-session software-only fix for class B: the server decided the session is a bot before the form response was rendered.
+
+**Fix:** route the spawned Chromium through a residential or mobile proxy the candidate already pays for. Geometra MCP v1.59.0 added a `proxy: { server, username?, password?, bypass? }` parameter on `geometra_connect` and `geometra_prepare_browser` that forwards straight to Playwright's `chromium.launch({ proxy })`. The outbound IP becomes residential/mobile, and the fingerprint check that fired class B no longer trips.
+
+**Opt-in, BYO.** JobForge does NOT bundle or resell proxy bandwidth — the candidate brings their own provider (Bright Data, Oxylabs, SOAX, Smartproxy, mobile hotspot, self-hosted SOCKS). Without a configured proxy, JobForge behavior is unchanged from v2.11.0 and earlier.
+
+### Where the proxy config lives
+
+`config/profile.yml` → top-level `proxy:` block:
+
+```yaml
+proxy:
+  server: "http://residential.example.com:8080"   # http://, https://, or socks5://
+  username: "your-proxy-username"                  # optional
+  password: "your-proxy-password"                  # optional
+  bypass: "*.internal,localhost"                   # optional
+```
+
+See `config/profile.example.yml` for the commented-out template.
+
+### How the orchestrator threads it through
+
+**Orchestrator responsibilities:**
+
+1. On session start, read `config/profile.yml` once. If a `proxy:` block is present, capture it as the `PROXY_CONFIG` for the session.
+2. When dispatching any subagent whose work involves a `geometra_connect` call, include `PROXY_CONFIG` verbatim in the task prompt. Example dispatch prompt line: "Pass `proxy: { server: ..., username: ..., password: ..., bypass: ... }` to every `geometra_connect` call you make."
+3. When the orchestrator itself opens a Chromium session (single-application interactive flow), include the same `proxy` object in its own `geometra_connect` call.
+4. If `proxy:` is absent from `profile.yml`, skip the param entirely. Do NOT invent a proxy URL or leave a stale placeholder.
+
+**Subagent responsibilities:**
+
+1. If the task prompt includes a `proxy` object, pass it through to `geometra_connect` and any `geometra_prepare_browser` calls unchanged.
+2. If the task prompt does NOT include a proxy object, run without one.
+3. Never second-guess the proxy field — if the orchestrator sourced it from `profile.yml`, it's authoritative.
+
+### When proxy use is load-bearing
+
+Apply these rules when deciding whether the proxy is worth waiting for:
+
+- **Required** for known-block Ashby tenants (see the class-B list in the Ashby section above), for `happydance.website` / Cloudflare-fronted ATSes, and for any Lever tenant that previously failed in the class-B pattern.
+- **Recommended** for any Ashby tenant NOT on the class-A-compatible list (base rate prior: ~80-90% block headless).
+- **Optional** for Greenhouse, Workday, Lever-clean tenants — these accept datacenter IPs today; using the proxy adds ~100ms per frame but no material downside.
+- **Not useful** for Typeform (Geometra-unsupported), Avature native-select lag (not a fingerprint issue), JazzHR+reCAPTCHA (reCAPTCHA scores unrelated to IP), Breezy (tenant-configured per-IP throttle — proxy may help or may hit a fresh throttle).
+
+### Pool partitioning — why mixed runs are safe
+
+The Geometra MCP partitions its reusable-proxy pool by `(server, username, bypass)` — see `@geometra/mcp@1.59.0` release notes. A direct session and a proxied session NEVER share a Chromium instance, and two sessions with different proxy configs don't pool either. Practical consequence: flipping `proxy:` on or off in `profile.yml` mid-session is safe — the next `geometra_connect` just opens a fresh Chromium in its own pool partition.
+
+### Troubleshooting
+
+| Symptom | Diagnosis |
+|---|---|
+| `Error: Failed to connect to proxy` immediately after `geometra_connect` | Proxy URL is wrong / unreachable. Verify the `server:` field hits the right host:port. |
+| `407 Proxy Authentication Required` | `username` or `password` is wrong or missing. Many residential providers require both. |
+| Class-B submit failure persists even with proxy set | (a) proxy is a datacenter proxy, not residential; (b) same tenant IP-banned your specific proxy's IP pool; (c) tenant uses TLS fingerprint / canvas fingerprint, not IP — switch to a fresh Chromium (isolated: true) and retry once, else mark Failed. |
+| Every `geometra_connect` is 3-5s slower than before | Expected — residential proxies add latency. Trade-off for higher submit-success rate. Do NOT revert unless the acceptance-rate lift is < 5%. |
 
 - Node.js (mjs modules), Geometra MCP (PDF + scraping + form filling), Gmail MCP (email), YAML (config), HTML/CSS (template), Markdown (data)
 

package/modes/apply.md

@@ -1,6 +1,102 @@
-# Mode: apply — Live Application Assistant
+# Agent: mode-apply
 
-Interactive mode for when the candidate is filling out an application form in Chrome. Reads what's on screen, loads prior context from the offer evaluation, and generates personalized answers for each form question.
+Live application assistant. Reads the active application form in Chrome (via Geometra MCP), loads prior context from the offer evaluation, generates personalized answers, and submits the form in one atomic transaction. When the user is applying to more than one job, this mode is invoked by the orchestrator as a dispatched subagent — never driven from an interactive session directly.
+
+## Hard limits
+
+- [H1] Submit the form in a single `geometra_run_actions` call that chains upload + fill + pick + submit. Never split upload / fill / submit across multiple tool calls.
+  why: Greenhouse-style forms regenerate internal field IDs after any DOM-mutating action (especially file uploads); multi-call sequences see stale IDs, enter a retry loop, and burn tens of thousands of tokens (4-retry Anthropic FDE trace, ~10K wasted tokens)
+
+- [H2] Never auto-retry a failed submit. On recovery failure, report the error to the orchestrator and stop. The orchestrator decides whether to re-dispatch.
+  why: duplicate applications are worse than a missed retry — ATS portals often accept a submit whose response was dropped mid-flight, so a retry double-submits. A human must decide.
+
+- [H3] Outcomes MUST be written as TSV to `batch/tracker-additions/{num}-{slug}.tsv` — never append APPLIED / FAILED / SKIP to `data/pipeline.md`.
+  why: `pipeline.md` is the URL inbox (`[ ]` → `[x]`); TSVs are the bridge to day files via `npx job-forge merge` (see root `[H6]` in iso/instructions.md)
+
+- [H4] Before dispatching the first subagent in a multi-job run, the orchestrator MUST call `geometra_list_sessions` then `geometra_disconnect({closeBrowser: true})`. Every dispatch-round, no exceptions.
+  why: prior aborted subagents leave Chromium sessions stuck in the pool; next `geometra_connect` fails with "Not connected" (see root `[H3]`)
+
+- [H5] Max 2 parallel `task` dispatches per round. For N jobs, run `ceil(N/2)` sequential rounds of 2. Never emit 3+ dispatches in a single message.
+  why: free-tier rate limits + subagent post-cleanup cost; racing more than 2 reliably loses at least one result (see root `[H1]`)
+
+## Defaults
+
+- [D1] Prefer the structured `location_constraints` block in `config/profile.yml` over the prose `location.*` / `compensation.location_flexibility` fields. Fall back to prose only when `location_constraints` is absent.
+  why: structured is O(1) field lookup; prose requires LLM interpretation per dispatch. 2026-04-18 empirical: prose path reached the right call but burned interpretation cycles on every candidate.
+
+- [D2] When Geometra MCP is unavailable, ask the candidate to share a screenshot, paste form questions as text, or provide company + role for lookup.
+  why: Geometra is the expected primary path; gracefully degrade without refusing to help.
+
+- [D3] On a detected role change (role on screen ≠ evaluated role in the report), warn the candidate and ask whether to adapt answers or re-evaluate. Do not silently proceed.
+  why: adapting answers to the wrong role produces mis-targeted cover letters and the candidate won't catch it until the recruiter does
+
+- [D4] Always pass `imeFriendly: true` on `fill_fields` — safe default everywhere, load-bearing for Ashby.
+  why: Ashby's React form swallows programmatic text input silently; `imeFriendly: true` fires composition events that clear React's internal validity state. Zero cost on other portals. Confirmed fix: Supabase #793 (2026-04-19).
+
+- [D5] Fetch `geometra_form_schema` at most once per application, right after the initial `geometra_connect`. Operate on labels thereafter.
+  why: schema re-fetches return hundreds of nested field IDs and pollute context; labels don't change mid-flow, so the second fetch is just paying for the same payload twice
+
+- [D6] Use `fieldLabel` over `fieldId` everywhere it works.
+  why: labels are stable across DOM refreshes; IDs are regenerated
+
+- [D7] If the orchestrator's task prompt includes a `proxy` object (sourced from `config/profile.yml`), pass it verbatim into every `geometra_connect` call — including Call 3 of the recovery sequence. If absent, run without one; never invent a proxy URL.
+  why: class-B Ashby / Cloudflare-fronted portals need a residential outbound IP; the fix is wired in Geometra MCP v1.59.0 but the orchestrator owns the config pipe. See "BYO Residential Proxy" in iso/instructions.md.
+
+## Procedure
+
+1. `geometra_connect` + `geometra_page_model`; thread `proxy` if present [D7]; no WebFetch [D5].
+2. If Geometra is unavailable, ask for screenshot or pasted text [D2].
+3. Extract company + role; Grep `reports/` for a matching evaluation.
+4. Load full report + Section G if present.
+5. Compare role on screen vs evaluated role [D3].
+6. If different, pause for the candidate's decision [D3].
+7. Before dispatch, run Geometra cleanup [H4] and location filter [D1].
+8. Extract form questions; classify each Section-G vs new.
+9. Generate answers from Block B + Block F + Section G + JD.
+10. Submit as ONE `run_actions` call [H1] using labels [D6] with `imeFriendly: true` [D4].
+11. On session error, run the 4-step recovery; only one retry [H2].
+12. On OTP prompt, fetch the code from Gmail via `gmail_get_message`.
+13. Submit the OTP with `geometra_fill_otp` and click Submit.
+14. Write outcome as `batch/tracker-additions/*.tsv` [H3].
+15. Cap parallelism at 2 per round [H5]; one in-flight per company.
+
+## Routing
+
+| If the role on screen... | Action |
+|---|---|
+| Matches the evaluated report exactly | Proceed with Section G answers |
+| Is a closely related variant (same archetype) | Warn, offer to adapt [D3] |
+| Is materially different (different archetype) | Warn, offer to re-evaluate [D3] |
+| Has no evaluation report | Offer to run auto-pipeline first |
+| Location conflicts with profile.yml constraints | Mark `Discarded`, do not dispatch [D1] |
+| otherwise | Ask the candidate what they want |
+
+## Output format
+
+The apply subagent returns a short structured message to the orchestrator (not prose to the user):
+
+```
+APPLIED <url> — report #NNN, score X.X/5, tenant <ats>
+  tracker TSV: batch/tracker-additions/<num>-<slug>.tsv
+  notes: <one-line observation>
+```
+
+Or, on failure:
+
+```
+APPLY FAILED AFTER RECOVERY: <url>
+  Error 1: <first error>
+  Error 2: <post-recovery error>
+  Recommend: re-dispatch on @general-paid
+```
+
+---
+
+# Reference
+
+Sections below are the detailed runbooks, decision tables, and portal-specific empirical notes for the rules above. The contract is the `## Hard limits` / `## Defaults` / `## Procedure` / `## Routing` block above; this material is what the subagent consults during execution.
+
+## Apply the session-length rule — REQUIRED
 
 ## Apply the session-length rule — REQUIRED
 
@@ -224,7 +320,8 @@ Call 3:  geometra_connect({
            pageUrl: "<the same URL as before>",
            isolated: true,
            headless: true,
-           slowMo: 350
+           slowMo: 350,
+           proxy: <pass through from task prompt if present; omit otherwise>
          })
 Call 4:  geometra_run_actions({
            sessionId: "<new sessionId from Call 3>",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "job-forge",
-  "version": "2.10.0",
+  "version": "2.12.0",
   "description": "AI-powered job search pipeline built on opencode",
   "type": "module",
   "bin": {
@@ -20,9 +20,14 @@
     "tokens:log": "node scripts/token-usage-report.mjs --days 1 --append",
     "trace:list": "iso-trace list --since 7d --cwd .",
     "trace:stats": "iso-trace stats --since 7d --cwd .",
+    "trace:show": "iso-trace show",
+    "plan": "iso plan .",
     "lint:agentmd": "agentmd lint iso/instructions.md",
+    "lint:modes": "isolint lint modes/",
     "test:agentmd": "agentmd test iso/instructions.md --fixtures fixtures/instructions.yml --via claude-code --model claude-haiku-4-5 --concurrency 2",
     "test:agentmd:baseline": "agentmd test iso/instructions.md --fixtures fixtures/instructions.yml --via claude-code --model claude-haiku-4-5 --concurrency 2 --trials 3 --format json --out fixtures/baseline.json",
+    "test:agentmd:apply": "agentmd test modes/apply.md --fixtures fixtures/modes/apply.yml --via claude-code --model claude-haiku-4-5 --concurrency 2 --trials 3",
+    "lint:agentmd:modes": "agentmd lint modes/apply.md",
     "build:config": "iso build .",
     "prepack": "iso build .",
     "release:check-source": "node ./scripts/release/check-source.mjs",