job-forge 2.14.9 → 2.14.10

package/.cursor/rules/main.mdc

@@ -33,6 +33,9 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [H7] Load-bearing facts passed to downstream subagents must originate from a file, not from prior subagent prose. Authoritative sources: `data/pipeline.md`, `data/scan-history.tsv`, `batch/scan-output-*.md`, `reports/{num}-*.md` with `**URL:**` / `**Score:**` headers, `batch/tracker-additions/*.tsv`.
   why: 2026-04-18 scan subagent returned 30 fabricated Greenhouse IDs in prose (plausible-looking, non-existent); orchestrator dispatched 30 downstream subagents that all 404'd. Subagents can hallucinate IDs, scores, and confirmation text — round-trip through a file or don't trust the value
 
+- [H8] Never paste proxy values from `config/profile.yml` into `task` prompts, status text, or summaries. If a proxy is configured, tell the subagent exactly: "Proxy is configured; read `config/profile.yml` and pass its top-level `proxy:` object to every `geometra_connect` call." Do not transcribe `server`, `username`, `password`, or `bypass`, even if you just read them from disk.
+  why: a 2026-04-25 OpenCode trace showed raw proxy credentials copied into an apply subagent prompt; trace logs are local, but prompts must still avoid replicating secrets across subagent sessions
+
 ## Defaults
 
 - [D1] Delegate to a subagent (`task`) only when the work involves repeated tool-heavy steps that bloat the cache prefix: applying to N≥2 jobs, batch scans hitting ≥3 companies, or any "apply to… / process pipeline / batch evaluate" user phrasing. Single-offer evals, dev work, file edits, `tracker` mode, single-URL checks, and one-shot questions stay inline.
@@ -58,7 +61,7 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 1. Check `cv.md`, `profile.yml`, and `portals.yml`; onboard if any file is missing.
 2. Pick and name the mode from **Routing** [D6]. No match → ask; do not guess.
 3. Read the active mode file [D3]; decide inline vs delegated work [D1].
-4. Prepare Geometra dispatches: cleanup [H3], dedupe [H2], location filter [D5], routing [D2].
+4. Prepare Geometra dispatches: cleanup [H3], dedupe [H2], location filter [D5], routing [D2], proxy prompt hygiene [H8].
 5. Dispatch at most 2 tasks per round [H1]; wait for final outcomes, not just task ids [H5b].
 6. Keep multi-job form-filling out of the orchestrator [H4].
 7. Cross-check subagent facts against authoritative files [H7].

package/.opencode/skills/job-forge.md

@@ -152,6 +152,9 @@ Step 3  — Pre-flight cleanup (once, before the loop)
 Step 4  — Loop in rounds of 2 (Hard Limit #1)
   for round in ceil(len(candidates) / 2):
     pair = candidates[round*2 : round*2 + 2]
+    # If proxy is configured, do not paste proxy values into prompts.
+    # Say: "Proxy is configured; read config/profile.yml and pass its
+    # top-level proxy object to every geometra_connect call."
     # Dispatch 1 or 2 task() calls in ONE message (never 3+)
     task(subagent_type=<tier per AGENTS.md routing>, prompt=<apply prompt for pair[0]>)
     task(subagent_type=<tier>, prompt=<apply prompt for pair[1]>)  # only if pair has 2

package/AGENTS.md

@@ -28,6 +28,9 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [H7] Load-bearing facts passed to downstream subagents must originate from a file, not from prior subagent prose. Authoritative sources: `data/pipeline.md`, `data/scan-history.tsv`, `batch/scan-output-*.md`, `reports/{num}-*.md` with `**URL:**` / `**Score:**` headers, `batch/tracker-additions/*.tsv`.
   why: 2026-04-18 scan subagent returned 30 fabricated Greenhouse IDs in prose (plausible-looking, non-existent); orchestrator dispatched 30 downstream subagents that all 404'd. Subagents can hallucinate IDs, scores, and confirmation text — round-trip through a file or don't trust the value
 
+- [H8] Never paste proxy values from `config/profile.yml` into `task` prompts, status text, or summaries. If a proxy is configured, tell the subagent exactly: "Proxy is configured; read `config/profile.yml` and pass its top-level `proxy:` object to every `geometra_connect` call." Do not transcribe `server`, `username`, `password`, or `bypass`, even if you just read them from disk.
+  why: a 2026-04-25 OpenCode trace showed raw proxy credentials copied into an apply subagent prompt; trace logs are local, but prompts must still avoid replicating secrets across subagent sessions
+
 ## Defaults
 
 - [D1] Delegate to a subagent (`task`) only when the work involves repeated tool-heavy steps that bloat the cache prefix: applying to N≥2 jobs, batch scans hitting ≥3 companies, or any "apply to… / process pipeline / batch evaluate" user phrasing. Single-offer evals, dev work, file edits, `tracker` mode, single-URL checks, and one-shot questions stay inline.
@@ -53,7 +56,7 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 1. Check `cv.md`, `profile.yml`, and `portals.yml`; onboard if any file is missing.
 2. Pick and name the mode from **Routing** [D6]. No match → ask; do not guess.
 3. Read the active mode file [D3]; decide inline vs delegated work [D1].
-4. Prepare Geometra dispatches: cleanup [H3], dedupe [H2], location filter [D5], routing [D2].
+4. Prepare Geometra dispatches: cleanup [H3], dedupe [H2], location filter [D5], routing [D2], proxy prompt hygiene [H8].
 5. Dispatch at most 2 tasks per round [H1]; wait for final outcomes, not just task ids [H5b].
 6. Keep multi-job form-filling out of the orchestrator [H4].
 7. Cross-check subagent facts against authoritative files [H7].

package/CLAUDE.md

@@ -28,6 +28,9 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [H7] Load-bearing facts passed to downstream subagents must originate from a file, not from prior subagent prose. Authoritative sources: `data/pipeline.md`, `data/scan-history.tsv`, `batch/scan-output-*.md`, `reports/{num}-*.md` with `**URL:**` / `**Score:**` headers, `batch/tracker-additions/*.tsv`.
   why: 2026-04-18 scan subagent returned 30 fabricated Greenhouse IDs in prose (plausible-looking, non-existent); orchestrator dispatched 30 downstream subagents that all 404'd. Subagents can hallucinate IDs, scores, and confirmation text — round-trip through a file or don't trust the value
 
+- [H8] Never paste proxy values from `config/profile.yml` into `task` prompts, status text, or summaries. If a proxy is configured, tell the subagent exactly: "Proxy is configured; read `config/profile.yml` and pass its top-level `proxy:` object to every `geometra_connect` call." Do not transcribe `server`, `username`, `password`, or `bypass`, even if you just read them from disk.
+  why: a 2026-04-25 OpenCode trace showed raw proxy credentials copied into an apply subagent prompt; trace logs are local, but prompts must still avoid replicating secrets across subagent sessions
+
 ## Defaults
 
 - [D1] Delegate to a subagent (`task`) only when the work involves repeated tool-heavy steps that bloat the cache prefix: applying to N≥2 jobs, batch scans hitting ≥3 companies, or any "apply to… / process pipeline / batch evaluate" user phrasing. Single-offer evals, dev work, file edits, `tracker` mode, single-URL checks, and one-shot questions stay inline.
@@ -53,7 +56,7 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 1. Check `cv.md`, `profile.yml`, and `portals.yml`; onboard if any file is missing.
 2. Pick and name the mode from **Routing** [D6]. No match → ask; do not guess.
 3. Read the active mode file [D3]; decide inline vs delegated work [D1].
-4. Prepare Geometra dispatches: cleanup [H3], dedupe [H2], location filter [D5], routing [D2].
+4. Prepare Geometra dispatches: cleanup [H3], dedupe [H2], location filter [D5], routing [D2], proxy prompt hygiene [H8].
 5. Dispatch at most 2 tasks per round [H1]; wait for final outcomes, not just task ids [H5b].
 6. Keep multi-job form-filling out of the orchestrator [H4].
 7. Cross-check subagent facts against authoritative files [H7].

package/bin/create-job-forge.mjs

@@ -110,6 +110,9 @@ const consumerPkg = {
     tokens: 'job-forge tokens',
     'tokens:today': 'job-forge tokens --days 1',
     'tokens:log': 'job-forge tokens --days 1 --append',
+    'trace:list': 'job-forge trace:list',
+    'trace:stats': 'job-forge trace:stats',
+    'trace:show': 'job-forge trace:show',
     // One command to pull the latest harness, companion plugin, and any
     // locally-pinned MCP packages. npm update is a no-op on packages not
     // in package.json, so listing @razroo/gmail-mcp + @geometra/mcp is

package/bin/job-forge.mjs

@@ -17,6 +17,7 @@
  *   pdf            Run generate-pdf.mjs
  *   sync-check     Run cv-sync-check.mjs
  *   tokens         Run scripts/token-usage-report.mjs
+ *   trace:*        Inspect local agent transcripts via iso-trace
  *   sync           Re-run the harness symlink sync (bin/sync.mjs)
  *   help, --help   Show this message
  */
@@ -28,6 +29,7 @@ import { existsSync } from 'fs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = resolve(__dirname, '..');
+const PROJECT_DIR = process.env.JOB_FORGE_PROJECT || process.cwd();
 
 const commands = {
   merge:        'merge-tracker.mjs',
@@ -52,6 +54,12 @@ const commands = {
   'render-report-header': 'scripts/render-report-header.mjs',
 };
 
+const traceAliases = {
+  'trace:list': 'list',
+  'trace:stats': 'stats',
+  'trace:show': 'show',
+};
+
 const [, , cmd, ...rest] = process.argv;
 
 function printHelp() {
@@ -68,6 +76,10 @@ Commands:
   pdf            Generate ATS-optimized CV PDF from cv.md
   sync-check     Lint: verify cv.md and profile.yml are filled in
   tokens         Show opencode token usage and cost by session/day
+  trace          Pass through to iso-trace (e.g. job-forge trace sources)
+  trace:list     List recent local agent sessions (defaults: --since 7d --cwd project)
+  trace:stats    Show trace stats (defaults: --since 7d --cwd project)
+  trace:show ID  Show one trace by id or prefix
   sync           Re-create harness symlinks in the current project
 
 Deterministic helpers (prefer these over LLM-derived values):
@@ -90,6 +102,8 @@ Pass --help after a command to see its own flags, e.g.:
   job-forge merge --help
   job-forge tokens --days 1
   job-forge slugify "Anthropic, PBC"
+  job-forge trace:list --since 24h
+  job-forge trace:show ses_...
 
 Project directory resolves to $JOB_FORGE_PROJECT or cwd.`);
 }
@@ -99,6 +113,21 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
   process.exit(0);
 }
 
+if (cmd === 'trace' || traceAliases[cmd]) {
+  const traceArgs = cmd === 'trace'
+    ? (rest.length === 0 ? ['help'] : rest)
+    : [traceAliases[cmd], ...rest];
+
+  const scriptPath = join(PKG_ROOT, 'scripts/trace.mjs');
+  const result = spawnSync(process.execPath, [scriptPath, ...traceArgs], {
+    stdio: 'inherit',
+    cwd: PROJECT_DIR,
+    env: process.env,
+  });
+
+  process.exit(result.status ?? 1);
+}
+
 const rel = commands[cmd];
 if (!rel) {
   console.error(`Unknown command: ${cmd}\n`);

package/docs/ARCHITECTURE.md

@@ -203,6 +203,7 @@ Scripts maintain data consistency. In a consumer project they're invoked via the
 | `generate-pdf.mjs` | `npx job-forge pdf` | Renders HTML to PDF via Geometra MCP (`geometra_generate_pdf`) or standalone Playwright/Chromium (`npx job-forge pdf <input.html> <output.pdf>`) |
 | `cv-sync-check.mjs` | `npx job-forge sync-check` | Setup lint: `cv.md` + `config/profile.yml`, hardcoded-metric scan on `modes/_shared.md` and `batch/batch-prompt.md`, optional `article-digest.md` freshness |
 | `scripts/token-usage-report.mjs` | `npx job-forge tokens` | Per-session opencode token/cost report from the SQLite DB |
+| `scripts/trace.mjs` | `npx job-forge trace:list` / `trace:stats` / `trace:show` | Local transcript observability via `@razroo/iso-trace`; common commands default to OpenCode sessions for the consumer project |
 | `tracker-lib.mjs` | _(library)_ | Shared helpers for reading/writing day-based tracker files — imported by merge/dedup/verify/normalize |
 | `bin/sync.mjs` | `npx job-forge sync` | Creates the harness symlinks in a consumer project (also runs as `postinstall`) |
 | `bin/create-job-forge.mjs` | `npx create-job-forge <dir>` | Scaffolds a new personal project |

package/docs/CUSTOMIZATION.md

@@ -98,13 +98,23 @@ Some forks use a **single** `data/applications.md` instead. That is fine if you
 
 ## Transcript observability (iso-trace)
 
-To inspect real agent sessions locally (tool mix, redundant fetches, Geometra churn) without uploading transcripts, use Razroo's [`@razroo/iso-trace`](https://github.com/razroo/iso/tree/main/packages/iso-trace).
+To inspect real agent sessions locally (tool mix, redundant fetches, Geometra churn) without uploading transcripts, use the `job-forge trace:*` commands. JobForge depends on Razroo's [`@razroo/iso-trace`](https://github.com/razroo/iso/tree/main/packages/iso-trace), so consumer projects do not need to install it separately.
 
-This harness also ships npm scripts (from the package root): `npm run trace:list`, `npm run trace:stats`, and `npm run trace:show -- <id>` — they wrap `iso-trace` with sensible defaults when the CLI is on `PATH`.
+Common commands default to OpenCode sessions for the current project and use a 7-day window:
+
+```bash
+npx job-forge trace:list
+npx job-forge trace:stats
+npx job-forge trace:show <session-id-or-prefix>
+```
+
+Scaffolded projects also include npm aliases: `npm run trace:list`, `npm run trace:stats`, and `npm run trace:show -- <id>`.
+
+For raw iso-trace commands, use `npx job-forge trace sources`, `npx job-forge trace where`, or any other `iso-trace` subcommand after `trace`.
 
 **Where Claude Code writes JSONL:** `~/.claude/projects/<encoded-cwd>/*.jsonl`.
 
-**CLI (install once per machine):** `npx -y @razroo/iso-trace@latest stats --source "$HOME/.claude/projects/<encoded-dir>/<session>.jsonl"`
+**Direct CLI fallback:** `npx -y @razroo/iso-trace@latest stats --source "$HOME/.claude/projects/<encoded-dir>/<session>.jsonl"`
 
 **Performance:** `iso-trace list --cwd /path/to/repo` walks all of `~/.claude/projects` before filtering; on large machines prefer `stats --source <one.jsonl>` or the library's `discoverSessions({ roots: ["<one encoded project dir>"] })` (see the iso-trace README).
 

package/docs/SETUP.md

@@ -130,6 +130,9 @@ From your project root, these commands maintain the tracker and pipeline checks.
 | Generate ATS-optimized CV PDF | `npx job-forge pdf` | `npm run pdf` |
 | Setup lint (cv.md + profile.yml) | `npx job-forge sync-check` | `npm run sync-check` |
 | Token usage report (from opencode SQLite DB) | `npx job-forge tokens` | `npm run tokens` |
+| List recent OpenCode traces for this project | `npx job-forge trace:list` | `npm run trace:list` |
+| Summarize trace tool/file/token usage | `npx job-forge trace:stats` | `npm run trace:stats` |
+| Show one trace by session id/prefix | `npx job-forge trace:show <id>` | `npm run trace:show -- <id>` |
 | Re-create harness symlinks | `npx job-forge sync` | `npm run sync` |
 | Build optional dashboard TUI (Go on `PATH`) | `(cd node_modules/job-forge/dashboard && go build .)` | `npm run build:dashboard` (harness repo only) |
 

package/iso/commands/job-forge.md

@@ -155,6 +155,9 @@ Step 3  — Pre-flight cleanup (once, before the loop)
 Step 4  — Loop in rounds of 2 (Hard Limit #1)
   for round in ceil(len(candidates) / 2):
     pair = candidates[round*2 : round*2 + 2]
+    # If proxy is configured, do not paste proxy values into prompts.
+    # Say: "Proxy is configured; read config/profile.yml and pass its
+    # top-level proxy object to every geometra_connect call."
     # Dispatch 1 or 2 task() calls in ONE message (never 3+)
     task(subagent_type=<tier per AGENTS.md routing>, prompt=<apply prompt for pair[0]>)
     task(subagent_type=<tier>, prompt=<apply prompt for pair[1]>)  # only if pair has 2

package/iso/instructions.md

@@ -28,6 +28,9 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [H7] Load-bearing facts passed to downstream subagents must originate from a file, not from prior subagent prose. Authoritative sources: `data/pipeline.md`, `data/scan-history.tsv`, `batch/scan-output-*.md`, `reports/{num}-*.md` with `**URL:**` / `**Score:**` headers, `batch/tracker-additions/*.tsv`.
   why: 2026-04-18 scan subagent returned 30 fabricated Greenhouse IDs in prose (plausible-looking, non-existent); orchestrator dispatched 30 downstream subagents that all 404'd. Subagents can hallucinate IDs, scores, and confirmation text — round-trip through a file or don't trust the value
 
+- [H8] Never paste proxy values from `config/profile.yml` into `task` prompts, status text, or summaries. If a proxy is configured, tell the subagent exactly: "Proxy is configured; read `config/profile.yml` and pass its top-level `proxy:` object to every `geometra_connect` call." Do not transcribe `server`, `username`, `password`, or `bypass`, even if you just read them from disk.
+  why: a 2026-04-25 OpenCode trace showed raw proxy credentials copied into an apply subagent prompt; trace logs are local, but prompts must still avoid replicating secrets across subagent sessions
+
 ## Defaults
 
 - [D1] Delegate to a subagent (`task`) only when the work involves repeated tool-heavy steps that bloat the cache prefix: applying to N≥2 jobs, batch scans hitting ≥3 companies, or any "apply to… / process pipeline / batch evaluate" user phrasing. Single-offer evals, dev work, file edits, `tracker` mode, single-URL checks, and one-shot questions stay inline.
@@ -53,7 +56,7 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 1. Check `cv.md`, `profile.yml`, and `portals.yml`; onboard if any file is missing.
 2. Pick and name the mode from **Routing** [D6]. No match → ask; do not guess.
 3. Read the active mode file [D3]; decide inline vs delegated work [D1].
-4. Prepare Geometra dispatches: cleanup [H3], dedupe [H2], location filter [D5], routing [D2].
+4. Prepare Geometra dispatches: cleanup [H3], dedupe [H2], location filter [D5], routing [D2], proxy prompt hygiene [H8].
 5. Dispatch at most 2 tasks per round [H1]; wait for final outcomes, not just task ids [H5b].
 6. Keep multi-job form-filling out of the orchestrator [H4].
 7. Cross-check subagent facts against authoritative files [H7].

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "job-forge",
-  "version": "2.14.9",
+  "version": "2.14.10",
   "description": "AI-powered job search pipeline built on opencode",
   "type": "module",
   "bin": {
@@ -18,9 +18,9 @@
     "tokens": "node scripts/token-usage-report.mjs",
     "tokens:today": "node scripts/token-usage-report.mjs --days 1",
     "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",
+    "trace:list": "node bin/job-forge.mjs trace:list",
+    "trace:stats": "node bin/job-forge.mjs trace:stats",
+    "trace:show": "node bin/job-forge.mjs trace:show",
     "plan": "iso plan .",
     "lint:agentmd": "agentmd lint iso/instructions.md",
     "lint:modes": "isolint lint modes/",
@@ -85,6 +85,7 @@
     "node": ">=18"
   },
   "dependencies": {
+    "@razroo/iso-trace": "^0.4.0",
     "playwright": "^1.58.1"
   },
   "devDependencies": {
@@ -93,7 +94,6 @@
     "@razroo/iso-eval": "^0.4.0",
     "@razroo/iso-harness": "^0.6.1",
     "@razroo/iso-route": "^0.5.3",
-    "@razroo/iso-trace": "^0.4.0",
     "@razroo/opencode-model-fallback": "^0.3.1"
   }
 }

package/scripts/trace.mjs

@@ -0,0 +1,469 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'child_process';
+import { existsSync } from 'fs';
+import { createRequire } from 'module';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import {
+  defaultOpenCodeDbPath,
+  findSessionById,
+  openCodeSessionLocator,
+  parseSinceCutoff,
+} from '@razroo/iso-trace';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+const PROJECT_DIR = process.env.JOB_FORGE_PROJECT || process.cwd();
+
+const USAGE = `job-forge trace — local OpenCode transcript observability
+
+Usage:
+  job-forge trace:list [--since 7d] [--cwd <dir>] [--json]
+  job-forge trace:stats [<id-or-prefix>...] [--since 7d] [--cwd <dir>] [--json]
+  job-forge trace:show <id-or-prefix> [--events <kinds>] [--grep <regex>]
+  job-forge trace <iso-trace args...>
+
+Common aliases default to OpenCode sessions for the current JobForge project.
+Use "job-forge trace sources" or "job-forge trace where" for raw iso-trace passthrough.`;
+
+const [cmd = 'help', ...args] = process.argv.slice(2);
+
+function parseFilters(rawArgs) {
+  const opts = { since: '7d', cwd: PROJECT_DIR, json: false };
+  const positional = [];
+
+  for (let i = 0; i < rawArgs.length; i++) {
+    const arg = rawArgs[i];
+    if (arg === '--since') {
+      opts.since = rawArgs[++i];
+    } else if (arg.startsWith('--since=')) {
+      opts.since = arg.slice('--since='.length);
+    } else if (arg === '--cwd') {
+      opts.cwd = rawArgs[++i];
+    } else if (arg.startsWith('--cwd=')) {
+      opts.cwd = arg.slice('--cwd='.length);
+    } else if (arg === '--json') {
+      opts.json = true;
+    } else if (arg === '--help' || arg === '-h') {
+      opts.help = true;
+    } else if (arg.startsWith('--')) {
+      opts.error = `unknown flag "${arg}"`;
+    } else {
+      positional.push(arg);
+    }
+  }
+
+  opts.cwd = resolve(opts.cwd || PROJECT_DIR);
+  return { opts, positional };
+}
+
+function parseShowArgs(rawArgs) {
+  const opts = {};
+  const positional = [];
+
+  for (let i = 0; i < rawArgs.length; i++) {
+    const arg = rawArgs[i];
+    if (arg === '--events') {
+      const raw = rawArgs[++i] || '';
+      opts.events = new Set(raw.split(',').map((s) => s.trim()).filter(Boolean));
+    } else if (arg.startsWith('--events=')) {
+      const raw = arg.slice('--events='.length);
+      opts.events = new Set(raw.split(',').map((s) => s.trim()).filter(Boolean));
+    } else if (arg === '--grep') {
+      opts.grep = compileRegex(rawArgs[++i], 'trace:show');
+    } else if (arg.startsWith('--grep=')) {
+      opts.grep = compileRegex(arg.slice('--grep='.length), 'trace:show');
+    } else if (arg === '--help' || arg === '-h') {
+      opts.help = true;
+    } else if (arg.startsWith('--')) {
+      opts.error = `unknown flag "${arg}"`;
+    } else {
+      positional.push(arg);
+    }
+  }
+
+  return { opts, positional };
+}
+
+function compileRegex(pattern, context) {
+  try {
+    return new RegExp(pattern || '', 'i');
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return new Error(`${context}: invalid --grep regex: ${message}`);
+  }
+}
+
+async function discoverOpenCodeRefs(opts) {
+  const dbPath = defaultOpenCodeDbPath();
+  if (!existsSync(dbPath)) return [];
+
+  const where = [
+    's.time_archived is null',
+    `s.directory = ${sqlString(resolve(opts.cwd || PROJECT_DIR))}`,
+  ];
+  const sinceMs = parseSinceCutoff(opts.since);
+  if (sinceMs !== undefined) {
+    where.push(`s.time_created >= ${Number(sinceMs)}`);
+  }
+
+  const rows = queryOpenCodeDb(dbPath, [
+    'select',
+    '  s.id,',
+    '  s.directory,',
+    '  s.time_created,',
+    '  s.time_updated,',
+    '  (select count(*) from message m where m.session_id = s.id) as turn_count,',
+    '  (',
+    '    (select coalesce(sum(length(data)), 0) from message m where m.session_id = s.id) +',
+    '    (select coalesce(sum(length(data)), 0) from part p where p.session_id = s.id)',
+    '  ) as size_bytes',
+    'from session s',
+    `where ${where.join(' and ')}`,
+    'order by s.time_updated desc',
+  ].join(' '));
+
+  return rows.map((row) => ({
+    id: row.id,
+    source: {
+      harness: 'opencode',
+      format: 'opencode/sqlite-v1',
+      path: openCodeSessionLocator(row.id, dbPath),
+    },
+    cwd: row.directory,
+    startedAt: msToIso(row.time_created),
+    endedAt: msToIso(row.time_updated),
+    turnCount: row.turn_count ?? 0,
+    sizeBytes: row.size_bytes ?? 0,
+  }));
+}
+
+function queryOpenCodeDb(dbPath, sql) {
+  const result = spawnSync('sqlite3', ['-json', dbPath, sql], {
+    encoding: 'utf8',
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  if ((result.status ?? 0) !== 0) {
+    const detail = result.stderr?.trim() || result.stdout?.trim() || `exit ${result.status ?? 1}`;
+    throw new Error(`job-forge trace: sqlite3 query failed: ${detail}`);
+  }
+  return JSON.parse(result.stdout || '[]');
+}
+
+function sqlString(value) {
+  return `'${String(value).replaceAll("'", "''")}'`;
+}
+
+function msToIso(ms) {
+  return new Date(Number(ms)).toISOString();
+}
+
+function sizeLabel(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+
+function shorten(value, max) {
+  const text = String(value ?? '');
+  if (text.length <= max) return text;
+  return `${text.slice(0, max - 1)}...`;
+}
+
+function pad(value, width) {
+  const text = String(value ?? '');
+  return text.length >= width ? text : text + ' '.repeat(width - text.length);
+}
+
+function printSessionTable(refs) {
+  const rows = refs.map((ref) => [
+    ref.id,
+    ref.startedAt.replace('T', ' ').replace(/\.\d+Z$/, 'Z'),
+    shorten(ref.cwd, 42),
+    String(ref.turnCount),
+    sizeLabel(ref.sizeBytes),
+  ]);
+  const header = ['id', 'started', 'cwd', 'turns', 'size'];
+  const widths = header.map((h, i) => Math.max(h.length, ...rows.map((row) => row[i].length)));
+
+  console.log(header.map((h, i) => pad(h, widths[i])).join('  '));
+  console.log(widths.map((w) => '-'.repeat(w)).join('  '));
+  for (const row of rows) {
+    console.log(row.map((cell, i) => pad(cell, widths[i])).join('  '));
+  }
+}
+
+function printStats(result) {
+  console.log(`sessions:  ${result.sessions}`);
+  console.log(`turns:     ${result.turns}`);
+  console.log(`duration:  ${Math.round(result.durationMs / 1000)}s`);
+  console.log(`tokens:    input=${result.tokens.input} output=${result.tokens.output} cache_read=${result.tokens.cacheRead} cache_created=${result.tokens.cacheCreated}`);
+
+  console.log('\ntool calls:');
+  for (const [name, count] of Object.entries(result.toolCalls).sort((a, b) => b[1] - a[1])) {
+    console.log(`  ${pad(name, 28)} ${count}`);
+  }
+
+  console.log('\nfile ops:');
+  for (const [name, count] of Object.entries(result.fileOps).sort((a, b) => b[1] - a[1])) {
+    console.log(`  ${pad(name, 8)} ${count}`);
+  }
+}
+
+function computeOpenCodeStats(refs) {
+  const result = {
+    sessions: refs.length,
+    turns: 0,
+    durationMs: 0,
+    tokens: { input: 0, output: 0, cacheRead: 0, cacheCreated: 0 },
+    toolCalls: {},
+    fileOps: {},
+  };
+
+  for (const ref of refs) {
+    const rows = loadOpenCodeRows(ref.id);
+    result.turns += rows.messages.length;
+    result.durationMs += Math.max(0, Date.parse(ref.endedAt || ref.startedAt) - Date.parse(ref.startedAt));
+
+    for (const row of rows.messages) {
+      const data = parseJson(row.data);
+      const tokens = data.tokens;
+      if (!tokens || typeof tokens !== 'object') continue;
+      result.tokens.input += Number(tokens.input || 0);
+      result.tokens.output += Number(tokens.output || 0);
+      result.tokens.cacheRead += Number(tokens.cache?.read || 0);
+      result.tokens.cacheCreated += Number(tokens.cache?.write || 0);
+    }
+
+    for (const row of rows.parts) {
+      const data = parseJson(row.data);
+      if (data.type !== 'tool') continue;
+      const toolName = data.tool || 'unknown';
+      result.toolCalls[toolName] = (result.toolCalls[toolName] || 0) + 1;
+      const op = fileOpForTool(toolName);
+      if (op) result.fileOps[op] = (result.fileOps[op] || 0) + 1;
+    }
+  }
+
+  return result;
+}
+
+function printOpenCodeSession(ref, opts) {
+  const rows = loadOpenCodeRows(ref.id);
+  console.log(`id:        ${ref.id}`);
+  console.log(`source:    ${ref.source.harness} (${ref.source.format})`);
+  console.log(`path:      ${ref.source.path}`);
+  console.log(`cwd:       ${ref.cwd}`);
+  console.log(`started:   ${ref.startedAt}`);
+  if (ref.endedAt) console.log(`ended:     ${ref.endedAt}`);
+  console.log(`turns:     ${rows.messages.length}`);
+  console.log('');
+
+  const events = openCodeEvents(rows);
+  for (const event of events) {
+    if (opts.events && !opts.events.has(event.kind)) continue;
+    const line = formatOpenCodeEvent(event);
+    if (opts.grep && !opts.grep.test(line)) continue;
+    console.log(line);
+  }
+}
+
+function loadOpenCodeRows(sessionId) {
+  const dbPath = defaultOpenCodeDbPath();
+  const id = sqlString(sessionId);
+  return {
+    messages: queryOpenCodeDb(dbPath, `select id, time_created, data from message where session_id = ${id} order by time_created, id`),
+    parts: queryOpenCodeDb(dbPath, `select id, message_id, time_created, data from part where session_id = ${id} order by time_created, id`),
+  };
+}
+
+function openCodeEvents(rows) {
+  const events = [];
+
+  for (const row of rows.messages) {
+    const data = parseJson(row.data);
+    const at = msToIso(row.time_created);
+    const model = data.modelID && data.providerID ? `${data.providerID}/${data.modelID}` : undefined;
+    const error = data.error?.data?.message || data.error?.message;
+    events.push({
+      kind: error ? 'error' : 'turn',
+      at,
+      text: error
+        ? `${data.role || 'assistant'} ${data.agent || ''} ${model || ''}: ${error}`
+        : `${data.role || 'unknown'} ${data.agent || ''} ${model || ''} finish=${data.finish || 'unknown'}`,
+    });
+    if (data.tokens) {
+      events.push({
+        kind: 'token_usage',
+        at,
+        text: `input=${data.tokens.input || 0} output=${data.tokens.output || 0} cache_read=${data.tokens.cache?.read || 0} cache_created=${data.tokens.cache?.write || 0}${model ? ` model=${model}` : ''}`,
+      });
+    }
+  }
+
+  for (const row of rows.parts) {
+    const data = parseJson(row.data);
+    const at = msToIso(row.time_created);
+    if (data.type === 'text') {
+      events.push({ kind: 'message', at, text: data.text || '' });
+    } else if (data.type === 'reasoning') {
+      events.push({ kind: 'reasoning', at, text: data.text || '' });
+    } else if (data.type === 'tool') {
+      const status = data.state?.status ? ` status=${data.state.status}` : '';
+      const input = data.state?.input ? ` ${JSON.stringify(data.state.input)}` : '';
+      const output = data.state?.output ? ` => ${data.state.output}` : '';
+      events.push({ kind: 'tool_call', at, text: `${data.tool || 'unknown'}${status}${input}${output}` });
+      const op = fileOpForTool(data.tool);
+      if (op) events.push({ kind: 'file_op', at, text: `${op} ${filePathFromTool(data) || ''}`.trim() });
+    } else if (data.__parseError) {
+      events.push({ kind: 'error', at, text: `unparseable part JSON: ${data.__parseError}` });
+    } else {
+      events.push({ kind: data.type || 'part', at, text: JSON.stringify(data) });
+    }
+  }
+
+  return events.sort((a, b) => a.at.localeCompare(b.at));
+}
+
+function formatOpenCodeEvent(event) {
+  return `${event.at} ${event.kind}: ${oneLine(event.text, 360)}`;
+}
+
+function parseJson(raw) {
+  try {
+    return JSON.parse(raw || '{}');
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { __parseError: message, __raw: raw };
+  }
+}
+
+function fileOpForTool(toolName) {
+  if (toolName === 'read') return 'read';
+  if (toolName === 'write') return 'write';
+  if (toolName === 'edit') return 'edit';
+  if (toolName === 'glob') return 'list';
+  if (toolName === 'grep') return 'search';
+  return undefined;
+}
+
+function filePathFromTool(part) {
+  const input = part.state?.input;
+  if (!input || typeof input !== 'object') return undefined;
+  return input.filePath || input.path || input.pattern;
+}
+
+function oneLine(value, max) {
+  return shorten(String(value ?? '').replace(/\s+/g, ' ').trim(), max);
+}
+
+function resolveIsoTraceCli() {
+  const pkgJsonPath = require.resolve('@razroo/iso-trace/package.json');
+  return join(dirname(pkgJsonPath), 'dist/cli.js');
+}
+
+function passthroughIsoTrace(rawArgs) {
+  const cliPath = resolveIsoTraceCli();
+  const result = spawnSync(process.execPath, [cliPath, ...rawArgs], {
+    stdio: 'inherit',
+    cwd: PROJECT_DIR,
+    env: process.env,
+  });
+  return result.status ?? 1;
+}
+
+async function main() {
+  if (cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    console.log(USAGE);
+    return 0;
+  }
+
+  if (cmd === 'list') {
+    const { opts } = parseFilters(args);
+    if (opts.help) {
+      console.log(USAGE);
+      return 0;
+    }
+    if (opts.error) {
+      console.error(`job-forge trace:list: ${opts.error}`);
+      return 2;
+    }
+    const refs = await discoverOpenCodeRefs(opts);
+    if (opts.json) {
+      console.log(JSON.stringify(refs, null, 2));
+      return 0;
+    }
+    if (refs.length === 0) {
+      console.error('job-forge trace:list: no OpenCode sessions found for this project');
+      return 2;
+    }
+    printSessionTable(refs);
+    return 0;
+  }
+
+  if (cmd === 'stats') {
+    const { opts, positional } = parseFilters(args);
+    if (opts.help) {
+      console.log(USAGE);
+      return 0;
+    }
+    if (opts.error) {
+      console.error(`job-forge trace:stats: ${opts.error}`);
+      return 2;
+    }
+    const refs = await discoverOpenCodeRefs(opts);
+    const selected = positional.length === 0
+      ? refs
+      : positional.map((id) => {
+          const ref = findSessionById(refs, id);
+          if (!ref) throw new Error(`job-forge trace:stats: no OpenCode session matches "${id}"`);
+          return ref;
+        });
+    const result = computeOpenCodeStats(selected);
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      printStats(result);
+    }
+    return 0;
+  }
+
+  if (cmd === 'show') {
+    const { opts, positional } = parseShowArgs(args);
+    if (opts.help) {
+      console.log(USAGE);
+      return 0;
+    }
+    if (opts.error) {
+      console.error(`job-forge trace:show: ${opts.error}`);
+      return 2;
+    }
+    if (opts.grep instanceof Error) {
+      console.error(opts.grep.message);
+      return 2;
+    }
+    if (positional.length === 0) {
+      console.error('job-forge trace:show: missing <id-or-prefix>');
+      return 2;
+    }
+    const refs = await discoverOpenCodeRefs({ cwd: PROJECT_DIR, since: undefined });
+    const ref = findSessionById(refs, positional[0]);
+    if (!ref) {
+      console.error(`job-forge trace:show: no OpenCode session matches "${positional[0]}"`);
+      return 2;
+    }
+    printOpenCodeSession(ref, opts);
+    return 0;
+  }
+
+  return passthroughIsoTrace([cmd, ...args]);
+}
+
+main()
+  .then((code) => process.exit(code))
+  .catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    process.exit(1);
+  });