job-forge 2.14.36 → 2.14.38

package/modes/apply.md

@@ -42,8 +42,8 @@ Live application assistant. Reads the active application form in Chrome (via Geo
 - [D6] Use `fieldLabel` over `fieldId` everywhere it works.
   why: labels are stable across DOM refreshes; IDs are regenerated
 
-- [D7] If the orchestrator says a proxy is configured, read the top-level `proxy:` block from `config/profile.yml` and pass that object into every `geometra_connect` call — including Call 3 of the recovery sequence. If the task prompt includes a legacy inline `proxy` object, pass it through, but do not echo credentials in status text. 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 modes/reference-portals.md.
+- [D7] If the orchestrator says a proxy is configured, read the top-level `proxy:` block from `config/profile.yml` and pass that object plus `stealth: true` into every `geometra_connect` call — including Call 3 of the recovery sequence. If the task prompt includes a legacy inline `proxy` object, pass it through and still set `stealth: true`, but do not echo credentials in status text. If absent, run with `stealth: true` and no proxy; never invent a proxy URL.
+  why: class-B Ashby / Cloudflare-fronted portals need a residential outbound IP plus a stealth Chromium fingerprint. Geometra MCP v1.59.0 added proxy plumbing, and v1.61.3 added CloakBrowser stealth Chromium via `stealth: true`; the orchestrator owns the config pipe. See "BYO Residential Proxy" in modes/reference-portals.md.
 
 - [D8] Upgrade application routing to `@general-paid` when the offer score is ≥ 4.0/5, the user flags "top-tier", "dream job", or "high-stakes", or the candidate is late-stage/post-screen.
   why: high-stakes applications need the quality-sensitive prompt and medium reasoning budget even though OpenCode now routes both application tiers through DeepSeek V4 Flash by default
@@ -53,7 +53,7 @@ Live application assistant. Reads the active application form in Chrome (via Geo
 
 ## Procedure
 
-1. `geometra_connect` + `geometra_page_model`; thread `proxy` if present [D7]; no WebFetch [D5].
+1. `geometra_connect` with `stealth: true` + `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.
@@ -350,6 +350,7 @@ Call 3:  geometra_connect({
            isolated: true,
            headless: true,
            slowMo: 350,
+           stealth: true,
            proxy: <pass through from task prompt if present; omit otherwise>
          })
 Call 4:  geometra_run_actions({

package/modes/auto-pipeline.md

@@ -9,7 +9,7 @@ Fetch the JD content once. If the input is a **URL** (not pasted JD text), fetch
 **Pick exactly one method, in this priority order:**
 
 1. **Greenhouse JSON API (first try, if the URL is Greenhouse-backed):** If the pipeline.md entry carries `| gh={slug}/{id}` OR the URL host matches `*.greenhouse.io` / a known Greenhouse customer front-end (`*.pinterestcareers.com`, `okta.com/company/careers/opportunity/*`, `samsara.com/company/careers/roles/*`, `zoominfo.com/careers?gh_jid=*`, `collibra.com/.../?gh_jid=*`, `careers.toasttab.com/jobs?gh_jid=*`, `careers.airbnb.com/positions/*?gh_jid=*`, `coinbase.com/careers/positions/*?gh_jid=*`, `instacart.careers/job/?gh_jid=*`), extract `slug` and `id` and WebFetch `https://boards-api.greenhouse.io/v1/boards/{slug}/jobs/{id}`. 200 + JSON with `content` is the authoritative JD. 404 = genuinely closed (mark CLOSED and stop). **OpenCode WebFetch compatibility:** do not pass `format: "json"`; omit `format` or use `format: "text"` and parse the returned JSON text. **If 200, STOP — do not fall back to Geometra or WebFetch of the front-end.** The API is faster, cheaper (no Geometra session), and never returns a bot-shell.
-2. **Geometra MCP:** Most non-Greenhouse job portals (Lever, Ashby, Workday) are SPAs. Use `geometra_connect` + `geometra_page_model` to render and read the JD. **If this returns non-empty JD text, STOP — do not WebFetch the same URL.**
+2. **Geometra MCP:** Most non-Greenhouse job portals (Lever, Ashby, Workday) are SPAs. Use `geometra_connect({ ..., stealth: true })` + `geometra_page_model` to render and read the JD. **If this returns non-empty JD text, STOP — do not WebFetch the same URL.**
 3. **WebFetch (only if Geometra is unavailable OR returned only a shell with no JD text):** For static pages (ZipRecruiter, WeLoveProduct, company career pages).
 4. **WebSearch (only if methods 1–3 all failed):** Search for the role title + company on secondary portals that index the JD in static HTML.
 
@@ -38,7 +38,7 @@ Execute the full `pdf` pipeline (read `modes/pdf.md`).
 
 Generate draft answers for the application form when the final score is >= 3.5. If the final score is >= 3.5 (per Canonical Scoring Model thresholds in `_shared.md`), generate draft answers for the application form:
 
-1. **Extract form questions**: Use Geometra MCP (`geometra_connect` + `geometra_form_schema`) to discover all form fields. **Reuse the same `sessionId` from Step 0** when the apply URL is the same rendered page; only connect again if the prior session ended or the URL changed. If questions cannot be extracted, use the generic questions.
+1. **Extract form questions**: Use Geometra MCP (`geometra_connect({ ..., stealth: true })` + `geometra_form_schema`) to discover all form fields. **Reuse the same `sessionId` from Step 0** when the apply URL is the same rendered page; only connect again if the prior session ended or the URL changed. If questions cannot be extracted, use the generic questions.
 2. **Generate answers** following the tone guidelines (see below).
 3. **Save in the report** as a `## G) Draft Application Answers` section.
 

package/modes/pipeline.md

@@ -7,7 +7,7 @@ Processes accumulated job offer URLs from `data/pipeline.md`. The user adds URLs
 1. **Read** `data/pipeline.md` → find `- [ ]` items in the "Pending" section
 2. **For each pending URL**:
    a. Calculate the next sequential `REPORT_NUM` by running `npx job-forge next-num` (scans `reports/`, day file `#` columns, and `batch/tracker-additions/` — do NOT derive from `reports/` alone)
-   b. **Extract JD** using Geometra MCP (geometra_connect + geometra_page_model) → WebFetch → WebSearch
+   b. **Extract JD** using Geometra MCP (`geometra_connect({ ..., stealth: true })` + geometra_page_model) → WebFetch → WebSearch
    c. If the URL is not accessible → mark as `- [!]` with a note and continue
    d. **Run full auto-pipeline**: A-F Evaluation → Report .md → PDF (if score >= 3.0, per `_shared.md` thresholds) → Draft answers (if score >= 3.5) → Tracker
    e. **Move from "Pending" to "Processed"**: `- [x] #NNN | URL | Company | Role | Score/5 | PDF ✅/❌`
@@ -34,7 +34,7 @@ Processes accumulated job offer URLs from `data/pipeline.md`. The user adds URLs
 ## Detect JD From URL
 
 1. **Greenhouse JSON API (FIRST, when the entry has `| gh={slug}/{id}` OR the host looks Greenhouse-backed):** WebFetch `https://boards-api.greenhouse.io/v1/boards/{slug}/jobs/{id}`. 200 + JSON with `content` = LIVE, use it as the JD; 404 = genuinely CLOSED (mark `- [!]` and continue). **OpenCode WebFetch compatibility:** do not pass `format: "json"`; omit `format` or use `format: "text"` and parse the returned JSON text. Bot-hostile customer fronts (`pinterestcareers.com`, `okta.com`, `samsara.com`, `zoominfo.com`, `collibra.com`, `careers.toasttab.com`, `careers.airbnb.com`, `coinbase.com`, `instacart.careers`, `careers.toasttab.com`) MUST be verified via this API first — WebFetch/Geometra of those domains returns a shell or 403 and causes false CLOSED marks.
-2. **Geometra MCP:** `geometra_connect` + `geometra_page_model`. Works with non-Greenhouse SPAs (Lever, Ashby, Workday), uses fewer tokens than raw DOM snapshots.
+2. **Geometra MCP:** `geometra_connect({ ..., stealth: true })` + `geometra_page_model`. Works with non-Greenhouse SPAs (Lever, Ashby, Workday), uses fewer tokens than raw DOM snapshots.
 3. **WebFetch (fallback):** For static pages or when Geometra is not available.
 4. **WebSearch (last resort):** Search on secondary portals that index the JD.
 

package/modes/reference-geometra.md

@@ -50,7 +50,7 @@ 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.
+**Class B fix — BYO residential proxy + stealth Chromium.** 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. JobForge also passes `stealth: true` so Geometra MCP >=1.61.3 launches CloakBrowser's patched Chromium instead of stock Playwright Chromium. See the "BYO Residential Proxy" reference section below. Without a configured proxy, stealth still helps browser fingerprinting, but the outbound IP remains datacenter.
 
 **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:
 
@@ -138,12 +138,12 @@ When running multiple application forms in parallel, each `geometra_connect` MUS
 
 **Correct parallel pattern:**
 ```javascript
-geometra_connect({ pageUrl: "https://...", isolated: true, headless: true, slowMo: 350 })
+geometra_connect({ pageUrl: "https://...", isolated: true, headless: true, slowMo: 350, stealth: true })
 ```
 
 **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.
+**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. Keep `stealth: true` either way so JobForge uses Geometra's CloakBrowser Chromium path for portal sessions.
 
 ### Session Reuse — When Subagents Cannot Reach Existing Sessions
 
@@ -185,7 +185,7 @@ Every subagent that uses Geometra must run these THREE tool calls as its FIRST t
 ```
 Step 1:  geometra_list_sessions()
 Step 2:  geometra_disconnect({ closeBrowser: true })
-Step 3:  geometra_connect({ pageUrl: "<the URL the orchestrator gave you>", isolated: true, headless: true, slowMo: 350 })
+Step 3:  geometra_connect({ pageUrl: "<the URL the orchestrator gave you>", isolated: true, headless: true, slowMo: 350, stealth: true })
 ```
 
 **If the orchestrator says proxy is configured,** read the top-level
@@ -193,7 +193,7 @@ Step 3:  geometra_connect({ pageUrl: "<the URL the orchestrator gave you>", isol
 
 ```
 Step 3:  geometra_connect({
-           pageUrl: "<URL>", isolated: true, headless: true, slowMo: 350,
+           pageUrl: "<URL>", isolated: true, headless: true, slowMo: 350, stealth: true,
            proxy: { server: "...", username: "...", password: "...", bypass: "..." }
          })
 ```

package/modes/reference-portals.md

@@ -49,13 +49,13 @@ When a form says "enter the code we sent to your email", you MUST retrieve the c
 
 ---
 
-## BYO Residential Proxy — opt-in outbound-IP override
+## BYO Residential Proxy + Stealth Chromium
 
 **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.
+**Fix:** route the spawned Chromium through a residential or mobile proxy the candidate already pays for, and launch Geometra's CloakBrowser stealth Chromium with `stealth: true`. Geometra MCP v1.59.0 added a `proxy: { server, username?, password?, bypass? }` parameter on `geometra_connect` and `geometra_prepare_browser`; v1.61.3 added `stealth: true` for CloakBrowser. The outbound IP becomes residential/mobile, the browser fingerprint moves off stock Playwright Chromium, and the class-B checks have fewer signals to trip.
 
-**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.
+**Proxy is opt-in, stealth is default.** 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 still passes `stealth: true`, but the outbound IP remains the machine or hosting environment running Chromium.
 
 ### Where the proxy config lives
 
@@ -76,15 +76,15 @@ See `config/profile.example.yml` for the commented-out template.
 **Orchestrator responsibilities:**
 
 1. On session start, read `config/profile.yml` once. If a `proxy:` block is present, remember that a proxy is configured, but do not paste username/password values into task prompts or user-visible status.
-2. When dispatching any subagent whose work involves a `geometra_connect` call, tell it to read `config/profile.yml` and pass the top-level `proxy:` block to every `geometra_connect` call. Example dispatch prompt line: "Proxy is configured; read `config/profile.yml` and pass its top-level `proxy:` object to every `geometra_connect` call."
-3. When the orchestrator itself opens a Chromium session (single-application interactive flow), include the same `proxy` object from `config/profile.yml` in its own `geometra_connect` call.
+2. When dispatching any subagent whose work involves a `geometra_connect` call, tell it to read `config/profile.yml` and pass the top-level `proxy:` block plus `stealth: true` to every `geometra_connect` call. Example dispatch prompt line: "Proxy is configured; read `config/profile.yml` and pass its top-level `proxy:` object plus `stealth: true` to every `geometra_connect` call."
+3. When the orchestrator itself opens a Chromium session (single-application interactive flow), include the same `proxy` object from `config/profile.yml` and `stealth: true` 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 says proxy is configured, read `config/profile.yml` and pass the top-level `proxy:` object through to `geometra_connect` and any `geometra_prepare_browser` calls unchanged.
-2. If the task prompt includes a legacy inline `proxy` object, pass it through unchanged, but never print the credentials back in status text.
-3. If the task prompt does NOT mention a proxy and `config/profile.yml` has no `proxy:` block, run without one.
+1. If the task prompt says proxy is configured, read `config/profile.yml` and pass the top-level `proxy:` object plus `stealth: true` through to `geometra_connect` and any `geometra_prepare_browser` calls unchanged.
+2. If the task prompt includes a legacy inline `proxy` object, pass it through unchanged and still set `stealth: true`, but never print the credentials back in status text.
+3. If the task prompt does NOT mention a proxy and `config/profile.yml` has no `proxy:` block, run with `stealth: true` and no proxy.
 4. Never second-guess the proxy field — if it comes from `profile.yml`, it's authoritative.
 
 ### When proxy use is load-bearing
@@ -98,7 +98,7 @@ Apply these rules when deciding whether the proxy is worth waiting for:
 
 ### 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.
+The Geometra MCP partitions its reusable-proxy pool by proxy identity and browser flavor — proxy partitioning landed in `@geometra/mcp@1.59.0`, and stealth partitioning is available in `@geometra/mcp@1.61.3`. A direct session and a proxied session NEVER share a Chromium instance, and stock and stealth sessions do not pool together. 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
 
@@ -128,7 +128,7 @@ The Geometra MCP partitions its reusable-proxy pool by `(server, username, bypas
     "geometra": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "@geometra/mcp"]
+      "args": ["-y", "@geometra/mcp@1.61.3"]
     },
     "gmail": {
       "type": "stdio",

package/modes/scan.md

@@ -25,7 +25,7 @@ Read `portals.yml` which contains:
 
 ### Use Level 1 — Direct Geometra (PRIMARY)
 
-**For each company in `tracked_companies`:** Connect to its `careers_url` with Geometra MCP (`geometra_connect` + `geometra_page_model` / `geometra_list_items`), read ALL visible job listings, and extract the title + URL of each one. Direct Geometra is the most reliable method because:
+**For each company in `tracked_companies`:** Connect to its `careers_url` with Geometra MCP (`geometra_connect({ ..., stealth: true })` + `geometra_page_model` / `geometra_list_items`), read ALL visible job listings, and extract the title + URL of each one. Direct Geometra is the most reliable method because:
 
 - It sees the page in real time (not cached Google results).
 - It works with SPAs (Ashby, Lever, Workday).
@@ -138,7 +138,7 @@ The levels are additive — all are executed, results are merged and deduplicate
 
 4. **Level 1 — Geometra scan** (sequential, or ≤2 parallel via `task` subagents per Hard Limit #1 in `AGENTS.md`):
    For each company in `tracked_companies` with `enabled: true` and `careers_url` defined:
-   a. `geometra_connect` to the `careers_url`
+   a. `geometra_connect` to the `careers_url` with `stealth: true`
    b. `geometra_page_model` or `geometra_list_items` to read all job listings
    c. If the page has filters/departments, navigate the relevant sections
    d. For each job listing extract: `{title, url, company}`
@@ -317,7 +317,7 @@ Each company in `tracked_companies` MUST have a `careers_url` — the direct URL
 **If `careers_url` doesn't exist** for a company:
 1. Try the pattern for its known platform
 2. If that fails, do a quick WebSearch: `"{company}" careers jobs`
-3. Navigate with Geometra (`geometra_connect`) to confirm it works
+3. Navigate with Geometra (`geometra_connect` with `stealth: true`) to confirm it works
 4. **Save the found URL in portals.yml** for future scans
 
 **If `careers_url` returns 404 or redirect:**

package/opencode.json

@@ -18,7 +18,7 @@
       "command": [
         "npx",
         "-y",
-        "@geometra/mcp"
+        "@geometra/mcp@1.61.3"
       ],
       "environment": {}
     },
@@ -46,7 +46,8 @@
     }
   },
   "instructions": [
-    "templates/states.yml"
+    "templates/states.yml",
+    ".opencode/instructions.md"
   ],
   "small_model": "opencode-go/deepseek-v4-flash"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "job-forge",
-  "version": "2.14.36",
+  "version": "2.14.38",
   "description": "AI-powered job search pipeline built on opencode",
   "type": "module",
   "bin": {
@@ -173,6 +173,9 @@
   "engines": {
     "node": ">=20.6.0"
   },
+  "overrides": {
+    "fast-uri": "3.1.2"
+  },
   "dependencies": {
     "@razroo/iso-cache": "^0.1.0",
     "@razroo/iso-canon": "^0.1.0",
@@ -185,21 +188,21 @@
     "@razroo/iso-ledger": "^0.1.0",
     "@razroo/iso-lineage": "^0.1.0",
     "@razroo/iso-migrate": "^0.1.0",
-    "@razroo/iso-orchestrator": "^0.1.0",
+    "@razroo/iso-orchestrator": "^0.2.0",
     "@razroo/iso-postflight": "^0.1.0",
     "@razroo/iso-preflight": "^0.1.0",
     "@razroo/iso-prioritize": "^0.1.0",
     "@razroo/iso-redact": "^0.1.0",
     "@razroo/iso-score": "^0.1.0",
     "@razroo/iso-timeline": "^0.1.0",
-    "@razroo/iso-trace": "^0.4.0",
+    "@razroo/iso-trace": "^0.5.0",
     "playwright": "^1.58.1"
   },
   "devDependencies": {
     "@razroo/agentmd": "^0.3.0",
-    "@razroo/iso": "^0.2.5",
+    "@razroo/iso": "^0.3.1",
     "@razroo/iso-eval": "^0.4.0",
-    "@razroo/iso-harness": "^0.6.1",
+    "@razroo/iso-harness": "^0.8.0",
     "@razroo/iso-route": "^0.5.3"
   }
 }

package/scripts/batch-orchestrator.mjs

@@ -8,6 +8,7 @@
  *   - idempotent bundle execution keyed by URL + retry count
  *   - bounded fan-out through workflow.forEach(..., { maxParallel })
  *   - mutexed state/report-number writes across parallel workers
+ *   - renewable leases + heartbeats for worker liveness inspection
  */
 
 import { spawn, spawnSync } from 'node:child_process';
@@ -46,12 +47,13 @@ const DEFAULT_WORKFLOW_ID = 'jobforge-batch';
 const STATE_HEADER = 'id\turl\tstatus\tstarted_at\tcompleted_at\treport_num\tscore\terror\tretries';
 
 function usage() {
-  console.log(`job-forge batch runner - process job offers in batch via opencode run workers
-Uses your default opencode model.
+  console.log(`job-forge batch runner - process job offers in batch via AI CLI workers
+Uses the selected runner's default project configuration.
 
 Usage: batch-runner.sh [OPTIONS]
 
 Options:
+  --runner NAME        Worker CLI: opencode or codex (default: ${process.env.JOBFORGE_BATCH_RUNNER || 'opencode'})
   --parallel N         Number of parallel workers (default: 1)
   --bundle-size N      Offers per worker invocation (default: 5, use 1 for
                        legacy per-offer mode). Each worker processes N
@@ -74,6 +76,7 @@ Files:
 
 function parseArgs(argv) {
   const options = {
+    runner: parseRunner(process.env.JOBFORGE_BATCH_RUNNER || 'opencode'),
     parallel: 1,
     dryRun: false,
     retryFailed: false,
@@ -94,6 +97,9 @@ function parseArgs(argv) {
     };
 
     switch (arg) {
+      case '--runner':
+        options.runner = parseRunner(next());
+        break;
       case '--parallel':
         options.parallel = parsePositiveInt(next(), '--parallel');
         break;
@@ -128,6 +134,12 @@ function parseArgs(argv) {
   return options;
 }
 
+function parseRunner(value) {
+  const runner = String(value || '').trim().toLowerCase();
+  if (runner === 'opencode' || runner === 'codex') return runner;
+  throw new Error(`--runner must be one of: opencode, codex`);
+}
+
 function parsePositiveInt(value, label) {
   const n = Number.parseInt(value, 10);
   if (!Number.isInteger(n) || n < 1) {
@@ -180,7 +192,7 @@ async function readTextIfExists(path) {
   return readFile(path, 'utf8');
 }
 
-async function checkPrerequisites({ dryRun }) {
+async function checkPrerequisites({ dryRun, runner }) {
   if (!existsSync(INPUT_FILE)) {
     throw new Error(`${INPUT_FILE} not found. Add offers first.`);
   }
@@ -188,9 +200,10 @@ async function checkPrerequisites({ dryRun }) {
     throw new Error(`${PROMPT_FILE} not found.`);
   }
   if (!dryRun) {
-    const result = spawnSync('opencode', ['--help'], { stdio: 'ignore' });
+    const command = workerCommandName(runner);
+    const result = spawnSync(command, ['--help'], { stdio: 'ignore' });
     if (result.error?.code === 'ENOENT') {
-      throw new Error("'opencode' CLI not found in PATH.");
+      throw new Error(`'${command}' CLI not found in PATH.`);
     }
   }
 
@@ -531,6 +544,70 @@ async function runOpencode(prompt, logFile) {
   });
 }
 
+let batchTemplateCache;
+
+async function batchTemplateText() {
+  if (batchTemplateCache === undefined) {
+    batchTemplateCache = await readFile(PROMPT_FILE, 'utf8');
+  }
+  return batchTemplateCache;
+}
+
+function workerCommandName(runner) {
+  return runner === 'codex' ? 'codex' : 'opencode';
+}
+
+async function runCodex(prompt, logFile) {
+  await ensureDir(dirname(logFile));
+  const finalMessageFile = `${logFile}.last-message.txt`;
+  const combinedPrompt = `${(await batchTemplateText()).trim()}\n\n${prompt}`;
+
+  return new Promise((resolveRun) => {
+    const child = spawn('codex', [
+      'exec',
+      '--dangerously-bypass-approvals-and-sandbox',
+      '-C',
+      PROJECT_DIR,
+      '--output-last-message',
+      finalMessageFile,
+      combinedPrompt,
+    ], {
+      cwd: PROJECT_DIR,
+      env: {
+        ...process.env,
+        JOB_FORGE_PROJECT: PROJECT_DIR,
+      },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    const chunks = [];
+    child.stdout.on('data', (chunk) => chunks.push(chunk));
+    child.stderr.on('data', (chunk) => chunks.push(chunk));
+
+    child.on('error', async (error) => {
+      chunks.push(Buffer.from(`\n${error.stack || error.message}\n`));
+    });
+
+    child.on('close', async (code) => {
+      const output = Buffer.concat(chunks).toString('utf8');
+      const finalMessage = await readTextIfExists(finalMessageFile);
+      const logOutput = finalMessage
+        ? `${output}\n\n--- FINAL MESSAGE ---\n${finalMessage}`
+        : output;
+      await writeFile(logFile, logOutput, 'utf8');
+      resolveRun({
+        exitCode: code ?? 1,
+        output: finalMessage || output,
+      });
+    });
+  });
+}
+
+async function runWorker(runner, prompt, logFile) {
+  if (runner === 'codex') return runCodex(prompt, logFile);
+  return runOpencode(prompt, logFile);
+}
+
 function parseStatusLines(output) {
   const seen = new Map();
   for (const line of output.split('\n')) {
@@ -550,7 +627,57 @@ function parseStatusLines(output) {
   return seen;
 }
 
-async function processBundle(workflow, bundle) {
+async function withWorkerLiveness(workflow, { runner, tag, ids, logFile }, run) {
+  const leaseKey = `worker:${tag}`;
+  const holder = `${runner}:${process.pid}:${tag}`;
+  const detail = {
+    runner,
+    ids,
+    log: relativeProjectPath(logFile),
+  };
+
+  await workflow.touchLease(leaseKey, {
+    holder,
+    ttlMs: 120_000,
+    detail: {
+      ...detail,
+      phase: 'starting',
+    },
+  });
+  await workflow.heartbeat(leaseKey, {
+    ...detail,
+    phase: 'starting',
+  });
+
+  const timer = setInterval(() => {
+    workflow.touchLease(leaseKey, {
+      holder,
+      ttlMs: 120_000,
+      detail: {
+        ...detail,
+        phase: 'running',
+      },
+    }).catch(() => {});
+    workflow.heartbeat(leaseKey, {
+      ...detail,
+      phase: 'running',
+    }).catch(() => {});
+  }, 30_000);
+  timer.unref?.();
+
+  try {
+    return await run();
+  } finally {
+    clearInterval(timer);
+    await workflow.heartbeat(leaseKey, {
+      ...detail,
+      phase: 'finished',
+    }).catch(() => {});
+    await workflow.releaseLease(leaseKey, holder).catch(() => {});
+  }
+}
+
+async function processBundle(workflow, bundle, options) {
   const startedAt = nowIso();
   const specs = await reserveBundle(workflow, bundle, startedAt);
   const tag = bundleTag(bundle);
@@ -561,11 +688,17 @@ async function processBundle(workflow, bundle) {
     type: 'batch.bundle.started',
     detail: {
       ids: bundle.map((offer) => offer.id),
+      runner: options.runner,
       log: relativeProjectPath(logFile),
     },
   });
 
-  const { exitCode, output } = await runOpencode(buildBundlePrompt(specs), logFile);
+  const { exitCode, output } = await withWorkerLiveness(workflow, {
+    runner: options.runner,
+    tag,
+    ids: bundle.map((offer) => offer.id),
+    logFile,
+  }, () => runWorker(options.runner, buildBundlePrompt(specs), logFile));
   const completedAt = nowIso();
   const statuses = parseStatusLines(output);
   const outcomes = [];
@@ -598,6 +731,13 @@ async function processBundle(workflow, bundle) {
         score: sanitizeCell(score),
         report_num: sanitizeCell(parsed.report_num, spec.report_num),
       });
+      await workflow.heartbeat(`worker:${tag}`, {
+        runner: options.runner,
+        ids: bundle.map((candidate) => candidate.id),
+        offerId: spec.id,
+        phase: 'settling',
+        status,
+      }).catch(() => {});
       console.log(`    ${status === 'completed' ? 'OK' : 'FAIL'} #${spec.id} (status=${status}, score=${sanitizeCell(score)}, report=${sanitizeCell(parsed.report_num, spec.report_num)})`);
       continue;
     }
@@ -622,6 +762,13 @@ async function processBundle(workflow, bundle) {
       score: '-',
       report_num: spec.report_num,
     });
+    await workflow.heartbeat(`worker:${tag}`, {
+      runner: options.runner,
+      ids: bundle.map((candidate) => candidate.id),
+      offerId: spec.id,
+      phase: 'settling',
+      status: 'failed',
+    }).catch(() => {});
     console.log(`    FAIL #${spec.id} (no status emitted; see ${relativeProjectPath(logFile)})`);
   }
 
@@ -633,6 +780,7 @@ async function processBundle(workflow, bundle) {
     type: 'batch.bundle.completed',
     detail: {
       ids: bundle.map((offer) => offer.id),
+      runner: options.runner,
       exitCode,
       log: relativeProjectPath(logFile),
       outcomes,
@@ -766,7 +914,7 @@ async function run(options) {
     const pending = selectPendingOffers(offers, stateRows, options);
 
     console.log('=== job-forge batch runner ===');
-    console.log(`Parallel: ${options.parallel} | Bundle size: ${options.bundleSize} | Max retries: ${options.maxRetries}`);
+    console.log(`Runner: ${options.runner} | Parallel: ${options.parallel} | Bundle size: ${options.bundleSize} | Max retries: ${options.maxRetries}`);
     console.log(`Workflow: ${options.workflowId} (${relativeProjectPath(WORKFLOW_DIR)})`);
     console.log(`Input: ${totalInput} offers`);
     console.log('');
@@ -812,6 +960,7 @@ async function run(options) {
             totalInput,
             pending: pending.length,
             bundles: bundles.length,
+            runner: options.runner,
             parallel: options.parallel,
             bundleSize: options.bundleSize,
           },
@@ -824,7 +973,7 @@ async function run(options) {
             const stepName = bundleStepName(bundle, rowsBeforeRun);
             return workflow.step(
               stepName,
-              async () => processBundle(workflow, bundle),
+              async () => processBundle(workflow, bundle, options),
               {
                 idempotencyKey: stepName,
               },

package/scripts/check-iso-smoke.mjs

@@ -5,6 +5,7 @@ import { resolve } from "node:path";
 const root = resolve(process.argv[2] ?? ".");
 const files = {
   instructions: readFileSync(resolve(root, "iso/instructions.md"), "utf8"),
+  instructionsOpencode: readFileSync(resolve(root, "iso/instructions.opencode.md"), "utf8"),
   helpers: readFileSync(resolve(root, "modes/reference-local-helpers.md"), "utf8"),
   apply: readFileSync(resolve(root, "modes/apply.md"), "utf8"),
   models: readFileSync(resolve(root, "models.yaml"), "utf8"),
@@ -20,6 +21,8 @@ const checks = [
   ["H5 blocks same-company concurrent retry", () => every(files.instructions, ["Re-dispatch the same company only AFTER", "previous subagent returns"])],
   ["H6 requires merge and verify", () => every(files.instructions, ["batch/tracker-additions/*.tsv", "npx job-forge merge", "npx job-forge verify"])],
   ["H7 distrusts subagent prose", () => every(files.instructions, ["must originate from a file", "not from prior subagent prose"])],
+  ["H8 keeps proxy secret and requires stealth", () => every(files.instructions, ["[H8]", "Do not transcribe `server`, `username`, `password`, or `bypass`", "`stealth: true`"])],
+  ["OpenCode addendum exists for task semantics", () => every(files.instructionsOpencode, ["OpenCode", "`task`", "launch acknowledgement", "Do not use `task` to poll status"])],
   ["root points to consolidated helper reference", () => every(files.instructions, ["[D8]", "modes/reference-local-helpers.md", "deterministic local helpers"])],
   ["helper reference covers score/timeline/prioritize/lineage", () => every(files.helpers, ["templates/score.json", "npx job-forge score:*", "templates/timeline.json", "npx job-forge timeline:*", "templates/prioritize.json", "npx job-forge prioritize:*", ".jobforge-lineage.json", "npx job-forge lineage:*"])],
   ["root helper defaults are consolidated", () => !/\[D(?:9|1\d|2[0-9])\]/.test(files.instructions)],