job-forge 2.14.13 → 2.14.14

package/.codex/config.toml

@@ -25,6 +25,5 @@ args = ["-y", "@razroo/gmail-mcp"]
 env = { DISABLE_HTTP = "true" }
 
 [mcp_servers.state-trace]
-command = "uvx"
-args = ["--from", "state-trace[mcp]", "state-trace-mcp"]
+command = "state-trace-mcp"
 env = { STATE_TRACE_STORAGE_PATH = ".state-trace/memory.db", STATE_TRACE_NAMESPACE = "job-forge", STATE_TRACE_CAPACITY_LIMIT = "256" }

package/.cursor/mcp.json

@@ -18,12 +18,7 @@
       }
     },
     "state-trace": {
-      "command": "uvx",
-      "args": [
-        "--from",
-        "state-trace[mcp]",
-        "state-trace-mcp"
-      ],
+      "command": "state-trace-mcp",
       "env": {
         "STATE_TRACE_STORAGE_PATH": ".state-trace/memory.db",
         "STATE_TRACE_NAMESPACE": "job-forge",

package/.cursor/rules/main.mdc

@@ -56,6 +56,9 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D6] Pick the mode from the **Routing** table below AND name it explicitly in your first response (e.g., "running auto-pipeline mode", "this is a `compare` request"). If no row matches the user's intent, ask which mode fits; do not guess.
   why: silent mode picks mis-route work (a "negotiation" question answered in `offer` mode produces the wrong report shape); naming the mode out loud makes the routing decision reviewable and gives downstream dispatches a reliable anchor
 
+- [D7] For standalone `batch` runs, prefer `batch/batch-runner.sh` instead of hand-rolling the loop. It delegates to `@razroo/iso-orchestrator`, persists workflow records in `.jobforge-runs/`, caps bundle fan-out, and mutexes state/report-number writes. Use `JOBFORGE_LEGACY_BATCH_RUNNER=1` only as a fallback.
+  why: the old Bash loop encoded resumability and parallelism manually; the iso-orchestrator path makes the durable control state inspectable and prevents report-number collisions under parallel bundles
+
 ## Procedure
 
 1. Check `cv.md`, `profile.yml`, and `portals.yml`; onboard if any file is missing.

package/.mcp.json

@@ -18,12 +18,7 @@
       }
     },
     "state-trace": {
-      "command": "uvx",
-      "args": [
-        "--from",
-        "state-trace[mcp]",
-        "state-trace-mcp"
-      ],
+      "command": "state-trace-mcp",
       "env": {
         "STATE_TRACE_STORAGE_PATH": ".state-trace/memory.db",
         "STATE_TRACE_NAMESPACE": "job-forge",

package/AGENTS.md

@@ -51,6 +51,9 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D6] Pick the mode from the **Routing** table below AND name it explicitly in your first response (e.g., "running auto-pipeline mode", "this is a `compare` request"). If no row matches the user's intent, ask which mode fits; do not guess.
   why: silent mode picks mis-route work (a "negotiation" question answered in `offer` mode produces the wrong report shape); naming the mode out loud makes the routing decision reviewable and gives downstream dispatches a reliable anchor
 
+- [D7] For standalone `batch` runs, prefer `batch/batch-runner.sh` instead of hand-rolling the loop. It delegates to `@razroo/iso-orchestrator`, persists workflow records in `.jobforge-runs/`, caps bundle fan-out, and mutexes state/report-number writes. Use `JOBFORGE_LEGACY_BATCH_RUNNER=1` only as a fallback.
+  why: the old Bash loop encoded resumability and parallelism manually; the iso-orchestrator path makes the durable control state inspectable and prevents report-number collisions under parallel bundles
+
 ## Procedure
 
 1. Check `cv.md`, `profile.yml`, and `portals.yml`; onboard if any file is missing.

package/CLAUDE.md

@@ -51,6 +51,9 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D6] Pick the mode from the **Routing** table below AND name it explicitly in your first response (e.g., "running auto-pipeline mode", "this is a `compare` request"). If no row matches the user's intent, ask which mode fits; do not guess.
   why: silent mode picks mis-route work (a "negotiation" question answered in `offer` mode produces the wrong report shape); naming the mode out loud makes the routing decision reviewable and gives downstream dispatches a reliable anchor
 
+- [D7] For standalone `batch` runs, prefer `batch/batch-runner.sh` instead of hand-rolling the loop. It delegates to `@razroo/iso-orchestrator`, persists workflow records in `.jobforge-runs/`, caps bundle fan-out, and mutexes state/report-number writes. Use `JOBFORGE_LEGACY_BATCH_RUNNER=1` only as a fallback.
+  why: the old Bash loop encoded resumability and parallelism manually; the iso-orchestrator path makes the durable control state inspectable and prevents report-number collisions under parallel bundles
+
 ## Procedure
 
 1. Check `cv.md`, `profile.yml`, and `portals.yml`; onboard if any file is missing.

package/README.md

@@ -29,7 +29,7 @@ The scaffolded `opencode.json` already has three MCPs wired up — they launch a
 
 - **Geometra** — browser automation + PDF generation
 - **Gmail** — reads replies from recruiters
-- **state-trace** — typed working memory for cross-session context (resumed batches, recent decisions, repeated portal quirks). Spawned via `uvx`; install once with `brew install uv` (or `pipx install uv`) — no other setup.
+- **state-trace** — typed working memory for cross-session context (resumed batches, recent decisions, repeated portal quirks). Install once with `python3 -m pip install "state-trace[mcp]"`; the MCP command is `state-trace-mcp`.
 
 `npm install` also materializes symlinks for every supported agent harness — OpenCode, Cursor, Claude Code, and Codex — so you can run `opencode`, `cursor`, `claude`, or `codex` in the same project and each picks up the shared MCP config and instructions.
 
@@ -73,6 +73,7 @@ JobForge turns opencode into a full job search command center. Instead of manual
 | **Smart LinkedIn Outreach** | Reads evaluation reports to craft targeted messages using top proof points |
 | **Portal Scanner** | 45+ companies pre-configured with fuzzy dedup for reposts |
 | **Batch Processing** | Parallel evaluation with `opencode run` workers, with honest verification flagging |
+| **Durable Batch Orchestration** | `batch-runner.sh` uses `@razroo/iso-orchestrator` for resumable bundle execution, bounded fan-out, mutexed state writes, and workflow records in `.jobforge-runs/`. |
 | **Pipeline Integrity** | Automated merge, dedup, status normalization, health checks |
 | **Cost-Aware Agent Routing** | Three subagents (`@general-free`, `@general-paid`, `@glm-minimal`) with per-task tool surfaces. On OpenCode, JobForge pins all tiers to `opencode-go/deepseek-v4-flash` so application runs avoid overloaded free-model pools. See [Subagent Routing in AGENTS.md](AGENTS.md) for the task-to-agent mapping. |
 | **Trace + Telemetry** | `job-forge trace:*` exposes local OpenCode transcripts, and `job-forge telemetry:*` summarizes runs, child outcomes, provider errors, and pending tracker TSVs. |
@@ -144,6 +145,7 @@ my-search/
 ├── data/                         # applications, pipeline, scan history (personal, gitignored)
 ├── reports/                      # generated evaluation reports (personal, gitignored)
 ├── batch/{batch-input,batch-state}.tsv, tracker-additions/, logs/   # personal
+├── .jobforge-runs/                # durable batch workflow records (generated)
 ├── AGENTS.md                     # personal overrides (opencode + codex)
 ├── CLAUDE.md                     # personal overrides (Claude Code), @-imports CLAUDE.harness.md
 │
@@ -187,6 +189,7 @@ JobForge/
 ├── config/profile.example.yml    # template for consumer's profile.yml
 ├── batch/{batch-prompt.md,batch-runner.sh}   # batch orchestrator
 ├── scripts/
+│   ├── batch-orchestrator.mjs    # iso-orchestrator-backed batch control loop
 │   ├── token-usage-report.mjs    # opencode cost analyzer
 │   └── release/check-source.mjs  # version gate for npm publish
 ├── tracker-lib.mjs / merge-tracker.mjs / dedup-tracker.mjs / verify-pipeline.mjs

package/batch/README.md

@@ -6,13 +6,20 @@ The `batch/` folder holds the **parallel batch runner** for processing 10+ job U
 
 | Path | Role |
 |------|------|
-| `batch-runner.sh` | Orchestrator: parallelism, state, retries, resume |
+| `batch-runner.sh` | Compatibility entrypoint; delegates to the durable Node orchestrator by default |
 | `batch-prompt.md` | Prompt template passed to each worker (keep evaluation and scoring instructions aligned with the canonical model in [`modes/_shared.md`](../modes/_shared.md) so batch scores match single-offer runs) |
 | `README.md` | This file |
 
 ## Local-only files (gitignored when present)
 
-Per [`.gitignore`](../.gitignore): `batch-input.tsv`, `batch-state.tsv`, `logs/*`, and `tracker-additions/*.tsv`. Empty dirs (`logs/`, `tracker-additions/`) use `.gitkeep` so the tree exists in a fresh clone.
+Per [`.gitignore`](../.gitignore): `batch-input.tsv`, `batch-state.tsv`, `logs/*`, `tracker-additions/*.tsv`, and `.jobforge-runs/`. Empty dirs (`logs/`, `tracker-additions/`) use `.gitkeep` so the tree exists in a fresh clone.
+
+The default runner uses `@razroo/iso-orchestrator` through
+`scripts/batch-orchestrator.mjs`. It persists bundle steps and events in
+`.jobforge-runs/`, caps worker fan-out with `workflow.forEach`, and serializes
+state/report-number writes while parallel bundles run. Use
+`JOBFORGE_LEGACY_BATCH_RUNNER=1 ./batch/batch-runner.sh` only to fall back to
+the old shell loop.
 
 ## Input: `batch-input.tsv`
 

package/batch/batch-runner.sh

@@ -6,8 +6,24 @@ set -euo pipefail
 # tracks state in batch-state.tsv for resumability.
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
-BATCH_DIR="$SCRIPT_DIR"
+PROJECT_DIR="${JOB_FORGE_PROJECT:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+
+# Default path: delegate to the durable Node orchestrator. Keep the legacy
+# shell implementation below as an escape hatch while the new runner settles.
+SOURCE="${BASH_SOURCE[0]}"
+while [[ -L "$SOURCE" ]]; do
+  SOURCE_DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+  SOURCE="$(readlink "$SOURCE")"
+  [[ "$SOURCE" != /* ]] && SOURCE="$SOURCE_DIR/$SOURCE"
+done
+HARNESS_BATCH_DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+HARNESS_DIR="$(cd "$HARNESS_BATCH_DIR/.." && pwd)"
+if [[ "${JOBFORGE_LEGACY_BATCH_RUNNER:-}" != "1" && -f "$HARNESS_DIR/scripts/batch-orchestrator.mjs" ]]; then
+  export JOB_FORGE_PROJECT="$PROJECT_DIR"
+  exec node "$HARNESS_DIR/scripts/batch-orchestrator.mjs" "$@"
+fi
+
+BATCH_DIR="$PROJECT_DIR/batch"
 INPUT_FILE="$BATCH_DIR/batch-input.tsv"
 STATE_FILE="$BATCH_DIR/batch-state.tsv"
 PROMPT_FILE="$BATCH_DIR/batch-prompt.md"

package/docs/ARCHITECTURE.md

@@ -131,11 +131,11 @@ For customization (archetypes, weights, tone), start with `_shared.md` and [CUST
 The batch system processes multiple offers in parallel:
 
 ```
-batch-input.tsv    →  batch-runner.sh  →  N × opencode run workers
-(id, url, source, notes) (orchestrator)   (self-contained prompt)
-                           │
-                    batch-state.tsv
-                    (tracks progress)
+batch-input.tsv    ->  batch-runner.sh  ->  N x opencode run workers
+(id, url, source, notes) (iso-orchestrator) (self-contained prompt)
+                           |
+                    batch-state.tsv + .jobforge-runs/
+                    (progress + durable workflow record)
 ```
 
 Each worker is a headless opencode instance (`opencode run`) that receives the full `batch-prompt.md` as context. Workers produce:
@@ -143,9 +143,13 @@ Each worker is a headless opencode instance (`opencode run`) that receives the f
 - PDF
 - Tracker TSV line
 
-The orchestrator manages parallelism, state, retries, and resume.
+The orchestrator manages parallelism, state, retries, and resume. The default
+runner delegates to `scripts/batch-orchestrator.mjs`, which uses
+`@razroo/iso-orchestrator` for bounded bundle fan-out, idempotent bundle steps,
+and mutexed report-number/state writes. Set `JOBFORGE_LEGACY_BATCH_RUNNER=1`
+only if you need the old shell loop.
 
-**Local batch artifacts:** `batch/batch-input.tsv`, `batch/batch-state.tsv`, `batch/logs/`, and `batch/tracker-additions/*.tsv` are created when you run the runner; they are gitignored (with `.gitkeep` in `batch/logs/` and `batch/tracker-additions/`). A fresh clone ships `batch/batch-runner.sh` and `batch/batch-prompt.md` only until you add an input file — see [`batch/README.md`](../batch/README.md) and `batch/batch-runner.sh --help` for the TSV layout and workflow.
+**Local batch artifacts:** `batch/batch-input.tsv`, `batch/batch-state.tsv`, `batch/logs/`, `batch/tracker-additions/*.tsv`, and `.jobforge-runs/` are created when you run the runner; they are gitignored (with `.gitkeep` in `batch/logs/` and `batch/tracker-additions/`). A fresh clone ships `batch/batch-runner.sh` and `batch/batch-prompt.md` only until you add an input file — see [`batch/README.md`](../batch/README.md) and `batch/batch-runner.sh --help` for the TSV layout and workflow.
 
 ## Data Flow
 

package/docs/SETUP.md

@@ -3,7 +3,7 @@
 ## Prerequisites
 
 - [opencode](https://opencode.ai) installed and configured
-- Node.js 18+ (for the CLI, PDF generation, and tracker scripts)
+- Node.js 20.6+ (for the CLI, PDF generation, tracker scripts, and durable batch orchestration)
 - [`uv`](https://docs.astral.sh/uv/) installed (`brew install uv` on macOS, or `pipx install uv`). Used by the state-trace MCP to spawn its Python entry point on demand via `uvx`. Without `uv`, the state-trace MCP fails to start; the rest of JobForge keeps working.
 - (Optional) Go (for the dashboard TUI) — use a toolchain that satisfies the `go` directive in [`dashboard/go.mod`](../dashboard/go.mod)
 

package/iso/instructions.md

@@ -51,6 +51,9 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D6] Pick the mode from the **Routing** table below AND name it explicitly in your first response (e.g., "running auto-pipeline mode", "this is a `compare` request"). If no row matches the user's intent, ask which mode fits; do not guess.
   why: silent mode picks mis-route work (a "negotiation" question answered in `offer` mode produces the wrong report shape); naming the mode out loud makes the routing decision reviewable and gives downstream dispatches a reliable anchor
 
+- [D7] For standalone `batch` runs, prefer `batch/batch-runner.sh` instead of hand-rolling the loop. It delegates to `@razroo/iso-orchestrator`, persists workflow records in `.jobforge-runs/`, caps bundle fan-out, and mutexes state/report-number writes. Use `JOBFORGE_LEGACY_BATCH_RUNNER=1` only as a fallback.
+  why: the old Bash loop encoded resumability and parallelism manually; the iso-orchestrator path makes the durable control state inspectable and prevents report-number collisions under parallel bundles
+
 ## Procedure
 
 1. Check `cv.md`, `profile.yml`, and `portals.yml`; onboard if any file is missing.

package/iso/mcp.json

@@ -12,8 +12,7 @@
       }
     },
     "state-trace": {
-      "command": "uvx",
-      "args": ["--from", "state-trace[mcp]", "state-trace-mcp"],
+      "command": "state-trace-mcp",
       "env": {
         "STATE_TRACE_STORAGE_PATH": ".state-trace/memory.db",
         "STATE_TRACE_NAMESPACE": "job-forge",

package/modes/batch.md

@@ -30,6 +30,7 @@ Each worker is a child `opencode run` with a clean 200K token context. The condu
 ## Read These Files
 
 ```
+.jobforge-runs/                  # Durable iso-orchestrator records (gitignored)
 batch/
   batch-input.tsv               # URLs (from conductor or manual)
   batch-state.tsv               # Progress (auto-generated, gitignored)
@@ -66,12 +67,19 @@ d. Execute via Bash:
 batch/batch-runner.sh [OPTIONS]
 ```
 
+`batch-runner.sh` delegates to `scripts/batch-orchestrator.mjs` by default.
+That Node runner uses `@razroo/iso-orchestrator` to persist workflow records in
+`.jobforge-runs/`, cap bundle fan-out with `workflow.forEach`, and serialize
+report-number/state writes while workers run in parallel. If a regression
+requires the old shell loop, run with `JOBFORGE_LEGACY_BATCH_RUNNER=1`.
+
 Options:
 - `--dry-run` — list pending without executing
 - `--retry-failed` — only retry failed ones
 - `--start-from N` — start from ID N
 - `--parallel N` — N workers in parallel
 - `--max-retries N` — attempts per offer (default: 2)
+- `--workflow-id ID` — durable workflow id (default: `jobforge-batch`)
 
 ## Read batch-state.tsv Format
 
@@ -85,6 +93,7 @@ id	url	status	started_at	completed_at	report_num	score	error	retries
 ## Use Resumability
 
 - If it dies → re-run → reads `batch-state.tsv` → skips completed
+- `.jobforge-runs/` keeps the durable run record, step outcomes, and bundle events
 - Lock file (`batch-runner.pid`) prevents double execution
 - Each worker is independent: failure on offer #47 does not affect the rest
 

package/opencode.json

@@ -36,9 +36,6 @@
     "state-trace": {
       "type": "local",
       "command": [
-        "uvx",
-        "--from",
-        "state-trace[mcp]",
         "state-trace-mcp"
       ],
       "environment": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "job-forge",
-  "version": "2.14.13",
+  "version": "2.14.14",
   "description": "AI-powered job search pipeline built on opencode",
   "type": "module",
   "bin": {
@@ -86,9 +86,10 @@
   },
   "license": "MIT",
   "engines": {
-    "node": ">=18"
+    "node": ">=20.6.0"
   },
   "dependencies": {
+    "@razroo/iso-orchestrator": "^0.1.0",
     "@razroo/iso-trace": "^0.4.0",
     "playwright": "^1.58.1"
   },

package/scripts/batch-orchestrator.mjs

@@ -0,0 +1,886 @@
+#!/usr/bin/env node
+/**
+ * Durable JobForge batch runner powered by @razroo/iso-orchestrator.
+ *
+ * This preserves the public batch-runner.sh interface while moving the
+ * load-bearing control loop into a resumable workflow:
+ *   - one durable workflow record per project
+ *   - idempotent bundle execution keyed by URL + retry count
+ *   - bounded fan-out through workflow.forEach(..., { maxParallel })
+ *   - mutexed state/report-number writes across parallel workers
+ */
+
+import { spawn, spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import {
+  mkdir,
+  readFile,
+  readdir,
+  rm,
+  stat,
+  writeFile,
+} from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { runWorkflow } from '@razroo/iso-orchestrator';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(__dirname, '..');
+const PROJECT_DIR = process.env.JOB_FORGE_PROJECT || process.cwd();
+
+const BATCH_DIR = join(PROJECT_DIR, 'batch');
+const INPUT_FILE = join(BATCH_DIR, 'batch-input.tsv');
+const STATE_FILE = join(BATCH_DIR, 'batch-state.tsv');
+const PROMPT_FILE = join(BATCH_DIR, 'batch-prompt.md');
+const LOGS_DIR = join(BATCH_DIR, 'logs');
+const TRACKER_DIR = join(BATCH_DIR, 'tracker-additions');
+const REPORTS_DIR = join(PROJECT_DIR, 'reports');
+const APPLICATIONS_DIR = join(PROJECT_DIR, 'data', 'applications');
+const TSV_MERGED_DIR = join(TRACKER_DIR, 'merged');
+const LOCK_FILE = join(BATCH_DIR, 'batch-runner.pid');
+const WORKFLOW_DIR = join(PROJECT_DIR, '.jobforge-runs');
+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.
+
+Usage: batch-runner.sh [OPTIONS]
+
+Options:
+  --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
+                       offers sequentially, amortizing the system prompt.
+  --dry-run            Show what would be processed, don't execute
+  --retry-failed       Only retry offers marked as "failed" in state
+  --start-from N       Start from offer ID N
+  --max-retries N      Max retry attempts per offer (default: 2)
+  --workflow-id ID     Durable workflow id (default: ${DEFAULT_WORKFLOW_ID})
+  -h, --help           Show this help
+
+Files:
+  batch-input.tsv      Input offers (id, url, source, notes)
+  batch-state.tsv      Processing state (auto-managed)
+  .jobforge-runs/      Durable iso-orchestrator workflow records
+  batch-prompt.md      Prompt template for workers
+  logs/                Per-bundle logs
+  tracker-additions/   Tracker lines for post-batch merge`);
+}
+
+function parseArgs(argv) {
+  const options = {
+    parallel: 1,
+    dryRun: false,
+    retryFailed: false,
+    startFrom: 0,
+    maxRetries: 2,
+    bundleSize: 5,
+    workflowId: DEFAULT_WORKFLOW_ID,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const next = () => {
+      i += 1;
+      if (i >= argv.length) {
+        throw new Error(`Missing value for ${arg}`);
+      }
+      return argv[i];
+    };
+
+    switch (arg) {
+      case '--parallel':
+        options.parallel = parsePositiveInt(next(), '--parallel');
+        break;
+      case '--bundle-size':
+        options.bundleSize = parsePositiveInt(next(), '--bundle-size');
+        break;
+      case '--dry-run':
+        options.dryRun = true;
+        break;
+      case '--retry-failed':
+        options.retryFailed = true;
+        break;
+      case '--start-from':
+        options.startFrom = parseNonNegativeInt(next(), '--start-from');
+        break;
+      case '--max-retries':
+        options.maxRetries = parsePositiveInt(next(), '--max-retries');
+        break;
+      case '--workflow-id':
+        options.workflowId = sanitizeWorkflowId(next());
+        break;
+      case '-h':
+      case '--help':
+        usage();
+        process.exit(0);
+        break;
+      default:
+        throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+function parsePositiveInt(value, label) {
+  const n = Number.parseInt(value, 10);
+  if (!Number.isInteger(n) || n < 1) {
+    throw new Error(`${label} must be a positive integer`);
+  }
+  return n;
+}
+
+function parseNonNegativeInt(value, label) {
+  const n = Number.parseInt(value, 10);
+  if (!Number.isInteger(n) || n < 0) {
+    throw new Error(`${label} must be a non-negative integer`);
+  }
+  return n;
+}
+
+function sanitizeWorkflowId(value) {
+  const clean = value.trim().replace(/[^a-zA-Z0-9._:-]+/g, '-');
+  if (!clean) throw new Error('--workflow-id cannot be empty');
+  return clean;
+}
+
+function hash(value, length = 12) {
+  return createHash('sha256').update(value).digest('hex').slice(0, length);
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function sanitizeCell(value, fallback = '-') {
+  const text = value === undefined || value === null || value === '' ? fallback : String(value);
+  return text.replace(/[\t\r\n]+/g, ' ').trim() || fallback;
+}
+
+function padReportNum(n) {
+  return String(n).padStart(3, '0');
+}
+
+async function ensureDir(path) {
+  await mkdir(path, { recursive: true });
+}
+
+async function readTextIfExists(path) {
+  if (!existsSync(path)) return '';
+  return readFile(path, 'utf8');
+}
+
+async function checkPrerequisites({ dryRun }) {
+  if (!existsSync(INPUT_FILE)) {
+    throw new Error(`${INPUT_FILE} not found. Add offers first.`);
+  }
+  if (!existsSync(PROMPT_FILE)) {
+    throw new Error(`${PROMPT_FILE} not found.`);
+  }
+  if (!dryRun) {
+    const result = spawnSync('opencode', ['--help'], { stdio: 'ignore' });
+    if (result.error?.code === 'ENOENT') {
+      throw new Error("'opencode' CLI not found in PATH.");
+    }
+  }
+
+  await ensureDir(LOGS_DIR);
+  await ensureDir(TRACKER_DIR);
+  await ensureDir(REPORTS_DIR);
+  await ensureDir(WORKFLOW_DIR);
+}
+
+async function acquirePidLock({ dryRun }) {
+  if (dryRun) return () => {};
+
+  if (existsSync(LOCK_FILE)) {
+    const oldPid = (await readTextIfExists(LOCK_FILE)).trim();
+    if (oldPid) {
+      try {
+        process.kill(Number(oldPid), 0);
+        throw new Error(`Another batch-runner is already running (PID ${oldPid}). If this is stale, remove ${LOCK_FILE}`);
+      } catch (error) {
+        if (error.code !== 'ESRCH') throw error;
+      }
+    }
+    console.log(`WARN: Stale lock file found (PID ${oldPid || 'unknown'} not running). Removing.`);
+    await rm(LOCK_FILE, { force: true });
+  }
+
+  await writeFile(LOCK_FILE, String(process.pid), 'utf8');
+
+  let released = false;
+  return async () => {
+    if (released) return;
+    released = true;
+    await rm(LOCK_FILE, { force: true });
+  };
+}
+
+async function initState() {
+  if (existsSync(STATE_FILE)) return;
+  await ensureDir(dirname(STATE_FILE));
+  await writeFile(STATE_FILE, `${STATE_HEADER}\n`, 'utf8');
+}
+
+async function readState() {
+  await initState();
+  const content = await readFile(STATE_FILE, 'utf8');
+  const rows = new Map();
+
+  for (const line of content.split('\n')) {
+    if (!line.trim()) continue;
+    const parts = line.split('\t');
+    if (parts[0] === 'id') continue;
+    const row = normalizeStateRow({
+      id: parts[0],
+      url: parts[1],
+      status: parts[2],
+      started_at: parts[3],
+      completed_at: parts[4],
+      report_num: parts[5],
+      score: parts[6],
+      error: parts[7],
+      retries: parts[8],
+    });
+    if (row.id) rows.set(row.id, row);
+  }
+
+  return rows;
+}
+
+function normalizeStateRow(row) {
+  return {
+    id: sanitizeCell(row.id, ''),
+    url: sanitizeCell(row.url),
+    status: sanitizeCell(row.status, 'pending'),
+    started_at: sanitizeCell(row.started_at),
+    completed_at: sanitizeCell(row.completed_at),
+    report_num: sanitizeCell(row.report_num),
+    score: sanitizeCell(row.score),
+    error: sanitizeCell(row.error),
+    retries: String(Number.parseInt(row.retries, 10) || 0),
+  };
+}
+
+async function writeState(rows) {
+  const sorted = [...rows.values()].sort((a, b) => {
+    const na = Number.parseInt(a.id, 10);
+    const nb = Number.parseInt(b.id, 10);
+    if (Number.isNaN(na) || Number.isNaN(nb)) return a.id.localeCompare(b.id);
+    return na - nb;
+  });
+
+  const lines = [STATE_HEADER];
+  for (const row of sorted) {
+    lines.push([
+      row.id,
+      row.url,
+      row.status,
+      row.started_at,
+      row.completed_at,
+      row.report_num,
+      row.score,
+      row.error,
+      row.retries,
+    ].map((value) => sanitizeCell(value)).join('\t'));
+  }
+  await writeFile(STATE_FILE, `${lines.join('\n')}\n`, 'utf8');
+}
+
+async function updateStateRow(workflow, nextRow) {
+  return workflow.withMutex('batch-state', async () => {
+    const rows = await readState();
+    const current = rows.get(nextRow.id) || {};
+    const row = normalizeStateRow({ ...current, ...nextRow });
+    rows.set(row.id, row);
+    await writeState(rows);
+    return row;
+  });
+}
+
+async function readInputOffers() {
+  const content = await readFile(INPUT_FILE, 'utf8');
+  const offers = [];
+
+  for (const rawLine of content.split('\n')) {
+    if (!rawLine.trim()) continue;
+    const parts = rawLine.split('\t');
+    if (parts[0] === 'id') continue;
+    const id = sanitizeCell(parts[0], '');
+    const url = sanitizeCell(parts[1], '');
+    if (!id || !url) continue;
+    offers.push({
+      id,
+      url,
+      source: sanitizeCell(parts[2]),
+      notes: sanitizeCell(parts.slice(3).join(' ')),
+    });
+  }
+
+  return offers;
+}
+
+function retriesFor(rows, id) {
+  const n = Number.parseInt(rows.get(id)?.retries, 10);
+  return Number.isInteger(n) && n >= 0 ? n : 0;
+}
+
+function statusFor(rows, id) {
+  return rows.get(id)?.status || 'none';
+}
+
+function selectPendingOffers(offers, rows, options) {
+  const pending = [];
+
+  for (const offer of offers) {
+    const numericId = Number.parseInt(offer.id, 10);
+    if (!Number.isNaN(numericId) && numericId < options.startFrom) continue;
+
+    const status = statusFor(rows, offer.id);
+    const retries = retriesFor(rows, offer.id);
+
+    if (options.retryFailed) {
+      if (status !== 'failed') continue;
+      if (retries >= options.maxRetries) {
+        console.log(`SKIP #${offer.id}: max retries (${options.maxRetries}) reached`);
+        continue;
+      }
+    } else {
+      if (status === 'completed') continue;
+      if (status === 'failed' && retries >= options.maxRetries) {
+        console.log(`SKIP #${offer.id}: failed and max retries reached (use --retry-failed to force)`);
+        continue;
+      }
+    }
+
+    pending.push(offer);
+  }
+
+  return pending;
+}
+
+function partition(items, size) {
+  const bundles = [];
+  for (let i = 0; i < items.length; i += size) {
+    bundles.push(items.slice(i, i + size));
+  }
+  return bundles;
+}
+
+async function maxReportNumberFromFiles(rows) {
+  let max = 0;
+
+  async function scanDir(dir, visitor) {
+    if (!existsSync(dir)) return;
+    for (const file of await readdir(dir)) {
+      const full = join(dir, file);
+      const info = await stat(full);
+      if (info.isFile()) await visitor(file, full);
+    }
+  }
+
+  await scanDir(REPORTS_DIR, async (file) => {
+    const match = file.match(/^(\d+)-.*\.md$/);
+    if (match) max = Math.max(max, Number.parseInt(match[1], 10));
+  });
+
+  await scanDir(APPLICATIONS_DIR, async (file, full) => {
+    if (!file.endsWith('.md')) return;
+    const content = await readFile(full, 'utf8');
+    for (const line of content.split('\n')) {
+      const match = line.match(/^\|\s*(\d+)\s*\|/);
+      if (match) max = Math.max(max, Number.parseInt(match[1], 10));
+    }
+  });
+
+  for (const dir of [TRACKER_DIR, TSV_MERGED_DIR]) {
+    await scanDir(dir, async (file, full) => {
+      if (!file.endsWith('.tsv')) return;
+      const nameMatch = file.match(/^(\d+)-/);
+      if (nameMatch) {
+        max = Math.max(max, Number.parseInt(nameMatch[1], 10));
+        return;
+      }
+      const content = await readFile(full, 'utf8');
+      const firstLine = content.split('\n').find((line) => line.trim());
+      if (!firstLine) return;
+      const n = Number.parseInt(firstLine.split('\t')[0], 10);
+      if (!Number.isNaN(n)) max = Math.max(max, n);
+    });
+  }
+
+  for (const row of rows.values()) {
+    const n = Number.parseInt(row.report_num, 10);
+    if (!Number.isNaN(n)) max = Math.max(max, n);
+  }
+
+  return max;
+}
+
+async function reserveBundle(workflow, bundle, startedAt) {
+  return workflow.withMutex('report-number', async () => {
+    const rows = await readState();
+    let next = await maxReportNumberFromFiles(rows);
+    const specs = [];
+
+    for (const offer of bundle) {
+      const current = rows.get(offer.id);
+      const existingReportNum = current?.status === 'processing' && current?.report_num && current.report_num !== '-'
+        ? current.report_num
+        : null;
+      const reportNum = existingReportNum || padReportNum(++next);
+      const retries = retriesFor(rows, offer.id);
+
+      rows.set(offer.id, normalizeStateRow({
+        id: offer.id,
+        url: offer.url,
+        status: 'processing',
+        started_at: startedAt,
+        completed_at: '-',
+        report_num: reportNum,
+        score: '-',
+        error: '-',
+        retries,
+      }));
+
+      specs.push({
+        id: offer.id,
+        url: offer.url,
+        jd_file: `/tmp/batch-jd-${offer.id}.txt`,
+        report_num: reportNum,
+        date: today(),
+      });
+    }
+
+    await writeState(rows);
+    return specs;
+  });
+}
+
+function bundleStepName(bundle, rows) {
+  const key = bundle
+    .map((offer) => `${offer.id}\0${offer.url}\0${retriesFor(rows, offer.id)}`)
+    .join('\n');
+  const ids = bundle.map((offer) => offer.id).join('_');
+  return `batch-bundle:${ids}:${hash(key)}`;
+}
+
+function bundleTag(bundle) {
+  return `bundle-${bundle.map((offer) => offer.id).join('_')}`;
+}
+
+function buildBundlePrompt(specs) {
+  return `Process these ${specs.length} offers sequentially using the full pipeline in batch-prompt.md
+(Step 1 JD retrieval -> Steps 2-6 evaluate/report/PDF/tracker line). Do each
+offer fully before starting the next. Continue to the next offer even if one
+fails. After each offer, emit ONE single-line JSON on its own line with this
+exact shape (no extra prose, no code fences around it):
+
+{"id":"<id>","status":"completed|failed","report_num":"<num>","company":"...","role":"...","score":<num-or-null>,"pdf":"<path-or-null>","report":"<path-or-null>","error":"<msg-or-null>"}
+
+The orchestrator parses these lines to update state. Anything between status
+JSONs is fine, but do NOT omit or reorder the required keys.
+
+Offers:
+${JSON.stringify(specs)}`;
+}
+
+async function runOpencode(prompt, logFile) {
+  await ensureDir(dirname(logFile));
+
+  return new Promise((resolve) => {
+    const child = spawn('opencode', [
+      'run',
+      '--dangerously-skip-permissions',
+      '--file',
+      PROMPT_FILE,
+      prompt,
+    ], {
+      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');
+      await writeFile(logFile, output, 'utf8');
+      resolve({ exitCode: code ?? 1, output });
+    });
+  });
+}
+
+function parseStatusLines(output) {
+  const seen = new Map();
+  for (const line of output.split('\n')) {
+    const start = line.indexOf('{');
+    const end = line.lastIndexOf('}');
+    if (start === -1 || end === -1 || end <= start) continue;
+    try {
+      const parsed = JSON.parse(line.slice(start, end + 1));
+      if (!parsed || typeof parsed !== 'object') continue;
+      if (!parsed.id || !parsed.status) continue;
+      const id = String(parsed.id);
+      if (!seen.has(id)) seen.set(id, parsed);
+    } catch {
+      // Workers may print non-JSON diagnostics; only exact status JSON matters.
+    }
+  }
+  return seen;
+}
+
+async function processBundle(workflow, bundle) {
+  const startedAt = nowIso();
+  const specs = await reserveBundle(workflow, bundle, startedAt);
+  const tag = bundleTag(bundle);
+  const logFile = join(LOGS_DIR, `${tag}.log`);
+
+  console.log(`--- Processing bundle of ${bundle.length} offer(s): ${bundle.map((offer) => offer.id).join(' ')}`);
+  await workflow.appendEvent({
+    type: 'batch.bundle.started',
+    detail: {
+      ids: bundle.map((offer) => offer.id),
+      log: relativeProjectPath(logFile),
+    },
+  });
+
+  const { exitCode, output } = await runOpencode(buildBundlePrompt(specs), logFile);
+  const completedAt = nowIso();
+  const statuses = parseStatusLines(output);
+  const outcomes = [];
+
+  for (const spec of specs) {
+    const parsed = statuses.get(spec.id);
+    const rows = await readState();
+    const retries = retriesFor(rows, spec.id);
+    const offer = bundle.find((candidate) => candidate.id === spec.id);
+
+    if (parsed) {
+      const status = parsed.status === 'completed' ? 'completed' : 'failed';
+      const nextRetries = status === 'failed' ? retries + 1 : retries;
+      const score = parsed.score === null || parsed.score === undefined ? '-' : parsed.score;
+      const error = parsed.error === null || parsed.error === undefined ? '-' : parsed.error;
+      await updateStateRow(workflow, {
+        id: spec.id,
+        url: offer?.url || spec.url,
+        status,
+        started_at: startedAt,
+        completed_at: completedAt,
+        report_num: sanitizeCell(parsed.report_num, spec.report_num),
+        score: sanitizeCell(score),
+        error: sanitizeCell(error),
+        retries: String(nextRetries),
+      });
+      outcomes.push({
+        id: spec.id,
+        status,
+        score: sanitizeCell(score),
+        report_num: sanitizeCell(parsed.report_num, spec.report_num),
+      });
+      console.log(`    ${status === 'completed' ? 'OK' : 'FAIL'} #${spec.id} (status=${status}, score=${sanitizeCell(score)}, report=${sanitizeCell(parsed.report_num, spec.report_num)})`);
+      continue;
+    }
+
+    const error = exitCode === 0
+      ? 'Worker finished without emitting status JSON for this offer'
+      : `Worker exited ${exitCode} without emitting status JSON for this offer`;
+    await updateStateRow(workflow, {
+      id: spec.id,
+      url: offer?.url || spec.url,
+      status: 'failed',
+      started_at: startedAt,
+      completed_at: completedAt,
+      report_num: spec.report_num,
+      score: '-',
+      error,
+      retries: String(retries + 1),
+    });
+    outcomes.push({
+      id: spec.id,
+      status: 'failed',
+      score: '-',
+      report_num: spec.report_num,
+    });
+    console.log(`    FAIL #${spec.id} (no status emitted; see ${relativeProjectPath(logFile)})`);
+  }
+
+  if (exitCode !== 0) {
+    console.log(`    WARN worker exit code ${exitCode}; see ${relativeProjectPath(logFile)}`);
+  }
+
+  await workflow.appendEvent({
+    type: 'batch.bundle.completed',
+    detail: {
+      ids: bundle.map((offer) => offer.id),
+      exitCode,
+      log: relativeProjectPath(logFile),
+      outcomes,
+    },
+  });
+
+  return {
+    ids: bundle.map((offer) => offer.id),
+    exitCode,
+    log: relativeProjectPath(logFile),
+    outcomes,
+  };
+}
+
+function relativeProjectPath(path) {
+  return path.startsWith(PROJECT_DIR)
+    ? path.slice(PROJECT_DIR.length + 1)
+    : path;
+}
+
+async function runNodeScript(relPath, args = [], { allowFailure = false } = {}) {
+  const scriptPath = join(PKG_ROOT, relPath);
+  const result = spawnSync(process.execPath, [scriptPath, ...args], {
+    cwd: PROJECT_DIR,
+    env: {
+      ...process.env,
+      JOB_FORGE_PROJECT: PROJECT_DIR,
+    },
+    stdio: 'inherit',
+  });
+
+  if (!allowFailure && (result.status ?? 1) !== 0) {
+    throw new Error(`${relPath} exited with status ${result.status ?? 1}`);
+  }
+
+  return result.status ?? 1;
+}
+
+async function mergeTracker() {
+  console.log('\n=== Merging tracker additions ===');
+  await runNodeScript('merge-tracker.mjs');
+  console.log('\n=== Verifying pipeline integrity ===');
+  const verifyStatus = await runNodeScript('verify-pipeline.mjs', [], { allowFailure: true });
+  if (verifyStatus !== 0) {
+    console.log('WARN Verification found issues (see above)');
+  }
+}
+
+async function costReport(sinceMinutes = 180) {
+  console.log(`\n=== Token usage (last ${sinceMinutes} min, warn at $1.00) ===`);
+  await runNodeScript('bin/job-forge.mjs', [
+    'session-report',
+    '--since-minutes',
+    String(sinceMinutes),
+    '--log',
+    '--warn-at',
+    '1.00',
+  ], { allowFailure: true });
+}
+
+async function summaryFromState() {
+  const rows = await readState();
+  let total = 0;
+  let completed = 0;
+  let failed = 0;
+  let pending = 0;
+  let scoreSum = 0;
+  let scoreCount = 0;
+
+  for (const row of rows.values()) {
+    total += 1;
+    if (row.status === 'completed') {
+      completed += 1;
+      const score = Number.parseFloat(row.score);
+      if (!Number.isNaN(score)) {
+        scoreSum += score;
+        scoreCount += 1;
+      }
+    } else if (row.status === 'failed') {
+      failed += 1;
+    } else {
+      pending += 1;
+    }
+  }
+
+  return {
+    total,
+    completed,
+    failed,
+    pending,
+    averageScore: scoreCount > 0 ? Number((scoreSum / scoreCount).toFixed(1)) : null,
+    scoreCount,
+  };
+}
+
+async function printSummary() {
+  console.log('\n=== Batch Summary ===');
+  const summary = await summaryFromState();
+  console.log(`Total: ${summary.total} | Completed: ${summary.completed} | Failed: ${summary.failed} | Pending: ${summary.pending}`);
+  if (summary.averageScore !== null) {
+    console.log(`Average score: ${summary.averageScore}/5 (${summary.scoreCount} scored)`);
+  }
+  return summary;
+}
+
+async function run(options) {
+  await checkPrerequisites(options);
+  const releaseLock = await acquirePidLock(options);
+
+  process.once('SIGINT', async () => {
+    await releaseLock();
+    process.exit(130);
+  });
+  process.once('SIGTERM', async () => {
+    await releaseLock();
+    process.exit(143);
+  });
+
+  try {
+    await initState();
+
+    const offers = await readInputOffers();
+    const totalInput = offers.length;
+    if (totalInput === 0) {
+      console.log(`No offers in ${INPUT_FILE}. Add offers first.`);
+      return;
+    }
+
+    const startedAt = nowIso();
+    const stateRows = await readState();
+    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(`Workflow: ${options.workflowId} (${relativeProjectPath(WORKFLOW_DIR)})`);
+    console.log(`Input: ${totalInput} offers`);
+    console.log('');
+
+    if (pending.length === 0) {
+      console.log('No offers to process.');
+      await printSummary();
+      return;
+    }
+
+    console.log(`Pending: ${pending.length} offers`);
+    console.log('');
+
+    if (options.dryRun) {
+      console.log('=== DRY RUN (no processing) ===');
+      for (const offer of pending) {
+        console.log(`  #${offer.id}: ${offer.url} [${offer.source}] (status: ${statusFor(stateRows, offer.id)})`);
+      }
+      console.log('');
+      console.log(`Would process ${pending.length} offers`);
+      return;
+    }
+
+    const bundles = partition(pending, options.bundleSize);
+    console.log(`Partitioned into ${bundles.length} bundle(s) of up to ${options.bundleSize} offer(s) each`);
+
+    await runWorkflow(
+      {
+        workflowId: options.workflowId,
+        dir: WORKFLOW_DIR,
+        initialState: {
+          kind: 'jobforge-batch',
+          runs: 0,
+          lastRun: null,
+        },
+      },
+      async (workflow) => {
+        await workflow.updateState((state) => ({
+          ...state,
+          runs: Number(state.runs || 0) + 1,
+          lastRun: {
+            startedAt,
+            totalInput,
+            pending: pending.length,
+            bundles: bundles.length,
+            parallel: options.parallel,
+            bundleSize: options.bundleSize,
+          },
+        }));
+
+        const rowsBeforeRun = await readState();
+        const summary = await workflow.forEach(
+          bundles,
+          async (bundle) => {
+            const stepName = bundleStepName(bundle, rowsBeforeRun);
+            return workflow.step(
+              stepName,
+              async () => processBundle(workflow, bundle),
+              {
+                idempotencyKey: stepName,
+              },
+            );
+          },
+          {
+            maxParallel: options.parallel,
+            stopOnError: false,
+          },
+        );
+
+        await workflow.appendEvent({
+          type: 'batch.bundles.finished',
+          detail: {
+            fulfilled: summary.fulfilled,
+            rejected: summary.rejected,
+          },
+        });
+
+        await workflow.step(
+          `merge-and-verify:${hash(startedAt)}`,
+          async () => {
+            await mergeTracker();
+            return { ok: true };
+          },
+        );
+
+        const finalSummary = await printSummary();
+        await workflow.updateState((state) => ({
+          ...state,
+          lastRun: {
+            ...state.lastRun,
+            completedAt: nowIso(),
+            summary: finalSummary,
+          },
+        }));
+
+        if (process.env.JOBFORGE_SKIP_COST_REPORT !== '1') {
+          await costReport(180);
+        }
+
+        return {
+          bundles: bundles.length,
+          summary: finalSummary,
+        };
+      },
+    );
+  } finally {
+    await releaseLock();
+  }
+}
+
+try {
+  const options = parseArgs(process.argv.slice(2));
+  await run(options);
+} catch (error) {
+  console.error(`ERROR: ${error.message}`);
+  process.exit(1);
+}