job-forge 2.14.42 → 2.14.44

package/.cursor/rules/main.mdc

@@ -36,6 +36,9 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [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 plus `headless: true` and `stealth: true` to every `geometra_connect` call and every Geometra auto-connect call that passes `pageUrl` or `url`." 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. Geometra MCP opens visible Chromium unless `headless: true` is explicit, and Geometra MCP >=1.61.3 can launch CloakBrowser stealth Chromium via `stealth: true`; both flags belong with JobForge portal sessions instead of stock visible Playwright Chromium
 
+- [H9] If Geometra MCP disappears, becomes unresponsive, or returns a cascade of `Not connected` after a live form-fill, inspect `.jobforge-mcp/geometra-mcp.jsonl` before guessing. Report the last `launcher_start`, `child_spawn`, `heartbeat`, `signal_received`, `child_stderr`, and `child_exit` events plus the timestamp gap from the last heartbeat. If the last event is an old heartbeat with no `signal_received` / `child_exit`, treat it as likely host SIGKILL or external process death.
+  why: OpenCode or the OS can kill the MCP server without stderr, crash logs, or core dumps. JobForge's MCP launcher writes durable lifecycle events outside MCP stdout, so silent disappearances still leave enough evidence to distinguish host kill, child crash, stderr failure, and wrapper health
+
 ## 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.
@@ -67,7 +70,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]. Use local helpers when they can replace broad file reads, prose math, manual policy checks, or artifact reuse decisions [D8]. Decide inline vs delegated work [D1].
-4. Prepare Geometra dispatches: cleanup [H3], local-helper prefilters when useful [D8], dedupe [H2], location filter [D5], file-backed preflight plan/check [D8], routing [D2], proxy/headless/stealth prompt hygiene [H8].
+4. Prepare Geometra dispatches: cleanup [H3], local-helper prefilters when useful [D8], dedupe [H2], location filter [D5], file-backed preflight plan/check [D8], routing [D2], proxy/headless/stealth prompt hygiene [H8], MCP lifecycle log awareness [H9].
 5. Dispatch at most 2 tasks per round [H1]; wait for final outcomes, not just task ids [H5b], then settle the round with postflight status [D8].
 6. Keep multi-job form-filling out of the orchestrator [H4].
 7. Cross-check subagent facts against authoritative files [H7].

package/AGENTS.md

@@ -31,6 +31,9 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [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 plus `headless: true` and `stealth: true` to every `geometra_connect` call and every Geometra auto-connect call that passes `pageUrl` or `url`." 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. Geometra MCP opens visible Chromium unless `headless: true` is explicit, and Geometra MCP >=1.61.3 can launch CloakBrowser stealth Chromium via `stealth: true`; both flags belong with JobForge portal sessions instead of stock visible Playwright Chromium
 
+- [H9] If Geometra MCP disappears, becomes unresponsive, or returns a cascade of `Not connected` after a live form-fill, inspect `.jobforge-mcp/geometra-mcp.jsonl` before guessing. Report the last `launcher_start`, `child_spawn`, `heartbeat`, `signal_received`, `child_stderr`, and `child_exit` events plus the timestamp gap from the last heartbeat. If the last event is an old heartbeat with no `signal_received` / `child_exit`, treat it as likely host SIGKILL or external process death.
+  why: OpenCode or the OS can kill the MCP server without stderr, crash logs, or core dumps. JobForge's MCP launcher writes durable lifecycle events outside MCP stdout, so silent disappearances still leave enough evidence to distinguish host kill, child crash, stderr failure, and wrapper health
+
 ## 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.
@@ -62,7 +65,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]. Use local helpers when they can replace broad file reads, prose math, manual policy checks, or artifact reuse decisions [D8]. Decide inline vs delegated work [D1].
-4. Prepare Geometra dispatches: cleanup [H3], local-helper prefilters when useful [D8], dedupe [H2], location filter [D5], file-backed preflight plan/check [D8], routing [D2], proxy/headless/stealth prompt hygiene [H8].
+4. Prepare Geometra dispatches: cleanup [H3], local-helper prefilters when useful [D8], dedupe [H2], location filter [D5], file-backed preflight plan/check [D8], routing [D2], proxy/headless/stealth prompt hygiene [H8], MCP lifecycle log awareness [H9].
 5. Dispatch at most 2 tasks per round [H1]; wait for final outcomes, not just task ids [H5b], then settle the round with postflight status [D8].
 6. Keep multi-job form-filling out of the orchestrator [H4].
 7. Cross-check subagent facts against authoritative files [H7].

package/CLAUDE.md

@@ -31,6 +31,9 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [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 plus `headless: true` and `stealth: true` to every `geometra_connect` call and every Geometra auto-connect call that passes `pageUrl` or `url`." 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. Geometra MCP opens visible Chromium unless `headless: true` is explicit, and Geometra MCP >=1.61.3 can launch CloakBrowser stealth Chromium via `stealth: true`; both flags belong with JobForge portal sessions instead of stock visible Playwright Chromium
 
+- [H9] If Geometra MCP disappears, becomes unresponsive, or returns a cascade of `Not connected` after a live form-fill, inspect `.jobforge-mcp/geometra-mcp.jsonl` before guessing. Report the last `launcher_start`, `child_spawn`, `heartbeat`, `signal_received`, `child_stderr`, and `child_exit` events plus the timestamp gap from the last heartbeat. If the last event is an old heartbeat with no `signal_received` / `child_exit`, treat it as likely host SIGKILL or external process death.
+  why: OpenCode or the OS can kill the MCP server without stderr, crash logs, or core dumps. JobForge's MCP launcher writes durable lifecycle events outside MCP stdout, so silent disappearances still leave enough evidence to distinguish host kill, child crash, stderr failure, and wrapper health
+
 ## 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.
@@ -62,7 +65,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]. Use local helpers when they can replace broad file reads, prose math, manual policy checks, or artifact reuse decisions [D8]. Decide inline vs delegated work [D1].
-4. Prepare Geometra dispatches: cleanup [H3], local-helper prefilters when useful [D8], dedupe [H2], location filter [D5], file-backed preflight plan/check [D8], routing [D2], proxy/headless/stealth prompt hygiene [H8].
+4. Prepare Geometra dispatches: cleanup [H3], local-helper prefilters when useful [D8], dedupe [H2], location filter [D5], file-backed preflight plan/check [D8], routing [D2], proxy/headless/stealth prompt hygiene [H8], MCP lifecycle log awareness [H9].
 5. Dispatch at most 2 tasks per round [H1]; wait for final outcomes, not just task ids [H5b], then settle the round with postflight status [D8].
 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',
+    'portal:snapshot': 'job-forge portal:snapshot',
+    'portal:form-schema': 'job-forge portal:form-schema',
+    'portal:explain': 'job-forge portal:explain',
     'trace:list': 'job-forge trace:list',
     'trace:stats': 'job-forge trace:stats',
     'trace:show': 'job-forge trace:show',
@@ -411,6 +414,7 @@ data/timeline-events.jsonl
 .jobforge-prioritize.json
 .jobforge-prioritize-items.json
 .jobforge-lineage.json
+.jobforge-mcp/
 .jobforge-runs/
 .jobforge-redacted/
 reports/

package/bin/geometra-mcp-launcher.mjs

@@ -1,12 +1,21 @@
 #!/usr/bin/env node
 
 import { spawn } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-const DEFAULT_FALLBACK_PACKAGE = '@geometra/mcp@1.61.3';
+const DEFAULT_FALLBACK_PACKAGE = '@geometra/mcp@1.62.1';
 const RESOLVE_ONLY_FLAG = '--job-forge-resolve-target';
+const DEFAULT_LOG_RELATIVE_PATH = '.jobforge-mcp/geometra-mcp.jsonl';
+const DEFAULT_HEARTBEAT_MS = 15_000;
+const MAX_STDERR_LOG_CHARS = 4_000;
+const SIGNAL_EXIT_CODES = {
+  SIGHUP: 129,
+  SIGINT: 130,
+  SIGQUIT: 131,
+  SIGTERM: 143,
+};
 
 function normalizeEnv(value) {
   if (typeof value !== 'string') return null;
@@ -26,6 +35,94 @@ function readJsonFile(filePath) {
   return JSON.parse(readFileSync(filePath, 'utf8'));
 }
 
+function boolEnvDisabled(value) {
+  if (typeof value !== 'string') return false;
+  return ['0', 'false', 'no', 'off'].includes(value.trim().toLowerCase());
+}
+
+function positiveIntEnv(value, fallback) {
+  if (typeof value !== 'string' || value.trim() === '') return fallback;
+  const parsed = Number.parseInt(value, 10);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function createLifecycleLogger(projectDir) {
+  if (boolEnvDisabled(process.env.JOB_FORGE_GEOMETRA_MCP_LOG)) {
+    return {
+      enabled: false,
+      logPath: null,
+      write() {},
+    };
+  }
+
+  const configuredPath = normalizeEnv(process.env.JOB_FORGE_GEOMETRA_MCP_LOG_PATH);
+  const logPath = configuredPath ? resolve(configuredPath) : join(projectDir, DEFAULT_LOG_RELATIVE_PATH);
+
+  function write(event, detail = {}) {
+    try {
+      mkdirSync(dirname(logPath), { recursive: true });
+      appendFileSync(logPath, `${JSON.stringify({
+        ts: new Date().toISOString(),
+        event,
+        pid: process.pid,
+        ppid: process.ppid,
+        projectDir,
+        ...detail,
+      })}\n`);
+    } catch {
+      // Logging must never break MCP startup or stdio protocol handling.
+    }
+  }
+
+  return {
+    enabled: true,
+    logPath,
+    write,
+  };
+}
+
+function targetForLog(target) {
+  return {
+    source: target.source,
+    command: target.command,
+    args: target.args,
+    resolvedPath: target.resolvedPath,
+    packageSpec: target.packageSpec,
+  };
+}
+
+function envForLog() {
+  return {
+    node: process.version,
+    platform: process.platform,
+    arch: process.arch,
+    geometraStealth: process.env.GEOMETRA_STEALTH ?? null,
+    geometraBrowser: process.env.GEOMETRA_BROWSER ?? null,
+    explicitMcpPath: Boolean(normalizeEnv(process.env.JOB_FORGE_GEOMETRA_MCP_PATH)),
+    explicitMcpPackage: Boolean(normalizeEnv(process.env.JOB_FORGE_GEOMETRA_MCP_PACKAGE)),
+    explicitLogPath: Boolean(normalizeEnv(process.env.JOB_FORGE_GEOMETRA_MCP_LOG_PATH)),
+  };
+}
+
+function processHealthForLog() {
+  const memory = process.memoryUsage();
+  const resourceUsage = typeof process.resourceUsage === 'function' ? process.resourceUsage() : null;
+  return {
+    uptimeMs: Math.round(process.uptime() * 1000),
+    memory,
+    resourceUsage,
+  };
+}
+
+function stderrChunkForLog(chunk) {
+  const text = Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk);
+  return {
+    text: text.slice(0, MAX_STDERR_LOG_CHARS),
+    bytes: Buffer.byteLength(text),
+    truncated: text.length > MAX_STDERR_LOG_CHARS,
+  };
+}
+
 function readProjectPathFromPackageJson(projectDir) {
   const packagePath = join(projectDir, 'package.json');
   if (!existsSync(packagePath)) return null;
@@ -114,18 +211,109 @@ export async function main(argv = process.argv.slice(2)) {
     return;
   }
 
+  const projectDir = process.env.JOB_FORGE_PROJECT || process.cwd();
+  const logger = createLifecycleLogger(projectDir);
+  const heartbeatMs = boolEnvDisabled(process.env.JOB_FORGE_GEOMETRA_MCP_HEARTBEAT)
+    ? 0
+    : positiveIntEnv(process.env.JOB_FORGE_GEOMETRA_MCP_HEARTBEAT_MS, DEFAULT_HEARTBEAT_MS);
+
+  logger.write('launcher_start', {
+    argv,
+    target: targetForLog(target),
+    env: envForLog(),
+    logPath: logger.logPath,
+    heartbeatMs,
+  });
+
   const child = spawn(target.command, [...target.args, ...argv], {
-    stdio: 'inherit',
+    stdio: ['inherit', 'inherit', 'pipe'],
     env: process.env,
   });
+  let exiting = false;
+  let heartbeat = null;
+
+  logger.write('child_spawn', {
+    childPid: child.pid,
+    target: targetForLog(target),
+  });
+
+  if (child.stderr) {
+    child.stderr.on('data', (chunk) => {
+      process.stderr.write(chunk);
+      logger.write('child_stderr', {
+        childPid: child.pid,
+        ...stderrChunkForLog(chunk),
+      });
+    });
+  }
+
+  if (heartbeatMs > 0) {
+    heartbeat = setInterval(() => {
+      logger.write('heartbeat', {
+        childPid: child.pid,
+        childKilled: child.killed,
+        health: processHealthForLog(),
+      });
+    }, heartbeatMs);
+    heartbeat.unref();
+  }
+
+  const signalNames = ['SIGHUP', 'SIGINT', 'SIGQUIT', 'SIGTERM'];
+  for (const signal of signalNames) {
+    process.once(signal, () => {
+      if (exiting) return;
+      exiting = true;
+      if (heartbeat) clearInterval(heartbeat);
+      logger.write('signal_received', {
+        signal,
+        childPid: child.pid,
+        childKilled: child.killed,
+        health: processHealthForLog(),
+      });
+      if (!child.killed) child.kill(signal);
+      process.exit(SIGNAL_EXIT_CODES[signal] ?? 1);
+    });
+  }
+
+  process.once('uncaughtException', (error) => {
+    logger.write('uncaught_exception', {
+      message: error instanceof Error ? error.message : String(error),
+      stack: error instanceof Error ? error.stack : null,
+      health: processHealthForLog(),
+    });
+    throw error;
+  });
+
+  process.once('unhandledRejection', (reason) => {
+    logger.write('unhandled_rejection', {
+      message: reason instanceof Error ? reason.message : String(reason),
+      stack: reason instanceof Error ? reason.stack : null,
+      health: processHealthForLog(),
+    });
+  });
 
   child.on('error', (error) => {
+    if (heartbeat) clearInterval(heartbeat);
+    logger.write('child_error', {
+      childPid: child.pid,
+      message: error instanceof Error ? error.message : String(error),
+      stack: error instanceof Error ? error.stack : null,
+      health: processHealthForLog(),
+    });
     console.error(error instanceof Error ? error.message : String(error));
     process.exit(1);
   });
 
   child.on('exit', (code, signal) => {
+    if (heartbeat) clearInterval(heartbeat);
+    logger.write('child_exit', {
+      childPid: child.pid,
+      code,
+      signal,
+      health: processHealthForLog(),
+    });
     if (signal) {
+      for (const signalName of signalNames) process.removeAllListeners(signalName);
       process.kill(process.pid, signal);
       return;
     }

package/bin/job-forge.mjs

@@ -17,6 +17,7 @@
  *   pdf            Run generate-pdf.mjs
  *   sync-check     Run cv-sync-check.mjs
  *   mcp:geometra   Launch Geometra MCP via JobForge's local/npm resolver
+ *   portal:*       One-shot direct-Geometra browser snapshots/form schemas
  *   tokens         Run scripts/token-usage-report.mjs
  *   trace:*        Inspect local agent transcripts via iso-trace
  *   telemetry:*    Summarize JobForge pipeline status from traces + tracker files
@@ -91,6 +92,12 @@ const guardAliases = {
   'guard:explain': 'explain',
 };
 
+const portalAliases = {
+  'portal:snapshot': 'snapshot',
+  'portal:form-schema': 'form-schema',
+  'portal:explain': 'explain',
+};
+
 const ledgerAliases = {
   'ledger:status': 'status',
   'ledger:rebuild': 'rebuild',
@@ -247,6 +254,9 @@ Commands:
   pdf            Generate ATS-optimized CV PDF from cv.md
   sync-check     Lint: verify cv.md and profile.yml are filled in
   mcp:geometra   Launch Geometra MCP, preferring local JobForge/Geometra dev wiring
+  portal:snapshot      Render a URL with direct Geometra and print page model/snapshot
+  portal:form-schema   Render a URL with direct Geometra and print form schema
+  portal:explain       Show direct Geometra module/defaults
   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)
@@ -354,6 +364,8 @@ Pass --help after a command to see its own flags, e.g.:
   job-forge telemetry:show ses_...
   job-forge guard:audit
   job-forge guard:explain
+  job-forge portal:snapshot --url https://example.test/jobs/123 --json
+  job-forge portal:form-schema --url https://example.test/apply --json
   job-forge ledger:has --company "Acme" --role "Staff Engineer" --status Applied
   job-forge capabilities:explain general-free
   job-forge capabilities:check general-free --tool browser --mcp geometra --command "npx job-forge merge" --filesystem write
@@ -438,6 +450,21 @@ if (cmd === 'guard' || guardAliases[cmd]) {
   process.exit(result.status ?? 1);
 }
 
+if (cmd === 'portal' || portalAliases[cmd]) {
+  const portalArgs = cmd === 'portal'
+    ? (rest.length === 0 ? ['help'] : rest)
+    : [portalAliases[cmd], ...rest];
+
+  const scriptPath = join(PKG_ROOT, 'scripts/portal.mjs');
+  const result = spawnSync(process.execPath, [scriptPath, ...portalArgs], {
+    stdio: 'inherit',
+    cwd: PROJECT_DIR,
+    env: process.env,
+  });
+
+  process.exit(result.status ?? 1);
+}
+
 if (cmd === 'ledger' || ledgerAliases[cmd]) {
   const ledgerArgs = cmd === 'ledger'
     ? (rest.length === 0 ? ['help'] : rest)

package/docs/ARCHITECTURE.md

@@ -115,7 +115,7 @@ For customization (archetypes, weights, tone), start with `_shared.md` and [CUST
 ## Evaluation Flow (Single Offer)
 
 1. **Input**: User pastes JD text or URL
-2. **Extract**: Geometra MCP/WebFetch extracts JD from URL
+2. **Extract**: `job-forge portal:*`, Geometra MCP, or WebFetch extracts JD/form context from URL
 3. **Classify**: Detect archetype (one row from the archetype table in `modes/_shared.md`)
 4. **Evaluate**: 6 blocks (A-F).
    - A: Role summary.
@@ -251,6 +251,7 @@ Scripts maintain data consistency. In a consumer project they're invoked via the
 | `scripts/trace.mjs` | `npx job-forge trace:list` / `trace:stats` / `trace:show` | Local transcript observability via `@agent-pattern-labs/iso-trace`; common commands default to project-local sessions across supported harnesses |
 | `scripts/telemetry.mjs` | `npx job-forge telemetry:status` / `telemetry:show` | JobForge operational telemetry derived from normalized local traces plus tracker TSV state |
 | `scripts/guard.mjs` | `npx job-forge guard:audit` / `guard:explain` | Deterministic `@agent-pattern-labs/iso-guard` policy audits over local normalized traces (with OpenCode `task` rules still available where relevant) |
+| `scripts/portal.mjs` | `npx job-forge portal:snapshot` / `portal:form-schema` | Deterministic direct-Geometra one-shot browser snapshots and form schemas with JobForge browser defaults enforced in code |
 | `scripts/ledger.mjs` | `npx job-forge ledger:status` / `ledger:has` / `ledger:rebuild` | Deterministic `@agent-pattern-labs/iso-ledger` state over tracker, TSV, and pipeline files |
 | `scripts/capabilities.mjs` | `npx job-forge capabilities:check` / `capabilities:explain` | Deterministic `@agent-pattern-labs/iso-capabilities` role boundary checks for tools, MCPs, commands, filesystem, and network access |
 | `scripts/cache.mjs` | `npx job-forge cache:has` / `cache:get` / `cache:put` | Deterministic `@agent-pattern-labs/iso-cache` JD and artifact reuse keyed by stable job/url inputs |

package/docs/SETUP.md

@@ -216,6 +216,8 @@ Use it to identify which sessions or models are consuming the most tokens. The `
 **PDF generation fails**  
 The scaffolded `opencode.json` already registers Geometra MCP; if it's not running, check `opencode mcp list` and verify the scaffolded config under the `mcp.geometra` key — its `command` MUST be `["npx", "--no-install", "job-forge", "mcp:geometra"]`, `enabled: true`, and its `environment` should include `GEOMETRA_STEALTH=1` (or equivalently `GEOMETRA_BROWSER=stealth`) so proxy-backed portal sessions default to CloakBrowser's patched Chromium. `job-forge mcp:geometra` resolves Geometra in this order: `JOB_FORGE_GEOMETRA_MCP_PATH`, then a consumer-project override from `package.json -> jobForge.geometraMcpPath`, then `opencode.json -> mcp.geometra.environment.JOB_FORGE_GEOMETRA_MCP_PATH`, then a sibling `../geometra/mcp/dist/index.js` checkout for local JobForge development, and finally the pinned npm package. Geometra manages Chromium via its built-in proxy. JobForge still passes `headless: true` and `stealth: true` for portal sessions explicitly; the env block keeps the default aligned for auto-spawned sessions and local debugging. For standalone CLI usage (outside opencode), `generate-pdf.mjs` also works with standalone Playwright/Chromium — install with `npx playwright install chromium`.
 
+`job-forge mcp:geometra` writes MCP launcher diagnostics to `.jobforge-mcp/geometra-mcp.jsonl`. If the server silently vanishes with empty stderr, run `tail -40 .jobforge-mcp/geometra-mcp.jsonl`. A final `signal_received` event means the host sent a catchable signal, a final `child_exit` means Geometra exited, and an old final `heartbeat` with no exit/signal usually means SIGKILL or external process death. Set `JOB_FORGE_GEOMETRA_MCP_LOG_PATH` to move the log, `JOB_FORGE_GEOMETRA_MCP_LOG=0` to disable it, or `JOB_FORGE_GEOMETRA_MCP_HEARTBEAT_MS` to tune the heartbeat interval.
+
 For consumer projects that should always use a local Geometra checkout across Opencode, Codex, Cursor, and Claude, prefer a local `package.json` override instead of editing symlinked MCP configs:
 
 ```json

package/iso/instructions.md

@@ -31,6 +31,9 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [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 plus `headless: true` and `stealth: true` to every `geometra_connect` call and every Geometra auto-connect call that passes `pageUrl` or `url`." 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. Geometra MCP opens visible Chromium unless `headless: true` is explicit, and Geometra MCP >=1.61.3 can launch CloakBrowser stealth Chromium via `stealth: true`; both flags belong with JobForge portal sessions instead of stock visible Playwright Chromium
 
+- [H9] If Geometra MCP disappears, becomes unresponsive, or returns a cascade of `Not connected` after a live form-fill, inspect `.jobforge-mcp/geometra-mcp.jsonl` before guessing. Report the last `launcher_start`, `child_spawn`, `heartbeat`, `signal_received`, `child_stderr`, and `child_exit` events plus the timestamp gap from the last heartbeat. If the last event is an old heartbeat with no `signal_received` / `child_exit`, treat it as likely host SIGKILL or external process death.
+  why: OpenCode or the OS can kill the MCP server without stderr, crash logs, or core dumps. JobForge's MCP launcher writes durable lifecycle events outside MCP stdout, so silent disappearances still leave enough evidence to distinguish host kill, child crash, stderr failure, and wrapper health
+
 ## 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.
@@ -62,7 +65,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]. Use local helpers when they can replace broad file reads, prose math, manual policy checks, or artifact reuse decisions [D8]. Decide inline vs delegated work [D1].
-4. Prepare Geometra dispatches: cleanup [H3], local-helper prefilters when useful [D8], dedupe [H2], location filter [D5], file-backed preflight plan/check [D8], routing [D2], proxy/headless/stealth prompt hygiene [H8].
+4. Prepare Geometra dispatches: cleanup [H3], local-helper prefilters when useful [D8], dedupe [H2], location filter [D5], file-backed preflight plan/check [D8], routing [D2], proxy/headless/stealth prompt hygiene [H8], MCP lifecycle log awareness [H9].
 5. Dispatch at most 2 tasks per round [H1]; wait for final outcomes, not just task ids [H5b], then settle the round with postflight status [D8].
 6. Keep multi-job form-filling out of the orchestrator [H4].
 7. Cross-check subagent facts against authoritative files [H7].

package/modes/apply.md

@@ -4,8 +4,8 @@ Live application assistant. Reads the active application form in Chrome (via Geo
 
 ## Hard limits
 
-- [H1] Submit the form in a single `geometra_run_actions` call that chains upload + fill + pick + submit. Never split upload / fill / submit across multiple tool calls.
-  why: Greenhouse-style forms regenerate internal field IDs after any DOM-mutating action (especially file uploads); multi-call sequences see stale IDs, enter a retry loop, and burn tens of thousands of tokens (4-retry Anthropic FDE trace, ~10K wasted tokens)
+- [H1] Submit the form with one stable `geometra_run_actions` action array that chains upload + fill + pick + submit. Set `softTimeoutMs: 45000`, `output: "final"`, and `includeSteps: false`; if Geometra returns `paused: true` with `resumeFromIndex`, immediately continue with the exact same `actions` array and that `resumeFromIndex`. Never split upload / fill / submit across separate direct tools or rebuilt action arrays.
+  why: Greenhouse-style forms regenerate internal field IDs after any DOM-mutating action (especially file uploads); multi-call sequences see stale IDs, enter a retry loop, and burn tens of thousands of tokens. The soft-timeout continuation keeps the MCP call under host timeout without changing the action array or restarting the application
 
 - [H2] Never auto-retry a failed submit. On recovery failure, report the error to the orchestrator and stop. The orchestrator decides whether to re-dispatch.
   why: duplicate applications are worse than a missed retry — ATS portals often accept a submit whose response was dropped mid-flight, so a retry double-submits. A human must decide.
@@ -64,7 +64,7 @@ Live application assistant. Reads the active application form in Chrome (via Geo
 9. Route high-stakes applications through `@general-paid` [D8].
 10. Extract form questions; classify each Section-G vs new.
 11. Generate answers from Block B + Block F + Section G + JD.
-12. Submit as ONE `run_actions` call [H1] using labels [D6] with `imeFriendly: true` [D4].
+12. Submit via one stable `run_actions` action array [H1] using labels [D6], `imeFriendly: true` [D4], `softTimeoutMs: 45000`, `output: "final"`, and `includeSteps: false`.
 13. On session error, run the 4-step recovery; only one retry [H2].
 14. On provider failure, stop and inspect telemetry before any retry [D9].
 15. On OTP prompt, fetch the code from Gmail via `gmail_get_message`.
@@ -308,13 +308,16 @@ Notes:
 
 When the candidate asks you to actually submit (or when running in auto-pipeline mode at score ≥ 3.0), follow these rules **strictly**. Greenhouse-style forms regenerate internal field IDs after any DOM-mutating action, especially file uploads. That breaks multi-call fill sequences and forces the model into a retry loop that burns tens of thousands of tokens.
 
-### Use one `run_actions` call (Rule A — never split)
+### Use one stable `run_actions` action array (Rule A — never split)
 
-Do the entire submission in a **single** `geometra_run_actions` call that chains all steps. Never split upload / fill / submit across multiple tool calls.
+Do the entire submission with one stable `geometra_run_actions` `actions` array that chains all steps. Never split upload / fill / submit across separate direct tools, and never rebuild the action array between continuations.
 
 ```
 geometra_run_actions({
   sessionId: "...",
+  softTimeoutMs: 45000,
+  output: "final",
+  includeSteps: false,
   actions: [
     { type: "upload_files",  fieldLabel: "Resume/CV", paths: ["/abs/path/cv.pdf"] },
     { type: "fill_fields",   imeFriendly: true,
@@ -326,6 +329,8 @@ geometra_run_actions({
 })
 ```
 
+If the response contains `paused: true`, `pauseReason: "soft-timeout"`, and `resumeFromIndex`, call `geometra_run_actions` again immediately with the same `sessionId`, the exact same `actions` array, `softTimeoutMs: 45000`, `output: "final"`, `includeSteps: false`, and `resumeFromIndex` set to the returned value. This is a continuation, not a retry, and it is the host-safe path for long Samsara/Greenhouse-style embeds. Stop only if the continued call fails, not merely because it paused.
+
 **Always pass `imeFriendly: true` on `fill_fields` for Ashby** (and safe as a default everywhere). Ashby's React form swallows programmatic text input silently — visible value looks correct, `invalidCount` stays >0, and Submit fails with "field required" or "flagged as possible spam." `imeFriendly: true` fires proper composition events that clear React's internal validity state. Confirmed fix: Supabase #793 (2026-04-19). Zero cost on other portals; no reason to leave it off.
 
 ### Use `fieldLabel` over `fieldId` (Rule B)
@@ -356,6 +361,9 @@ Call 3:  geometra_connect({
          })
 Call 4:  geometra_run_actions({
            sessionId: "<new sessionId from Call 3>",
+           softTimeoutMs: 45000,
+           output: "final",
+           includeSteps: false,
            actions: [... the EXACT same actions array you used before ...]
          })
 ```
@@ -365,7 +373,8 @@ Call 4:  geometra_run_actions({
 1. **Always run all 4 calls.** Do not skip Call 1 or Call 2 even if Call 1 shows an empty pool.
 2. **Do not re-fetch the form schema.** Do not call `geometra_form_schema` between Call 3 and Call 4. Your labels haven't changed, so the same `actions` array still works.
 3. **Do not edit the actions array.** Copy it verbatim from your first attempt. Do not re-pick fieldIds. Do not add or remove actions. Same array in, same array out.
-4. **Only ONE retry.** If Call 4 ALSO fails, STOP. Return this exact message to the orchestrator:
+4. **Soft-timeout pause is not failure.** If Call 4 returns `paused: true`, continue with the returned `resumeFromIndex` and the exact same action array. Do not count this as the one retry.
+5. **Only ONE retry.** If Call 4 ALSO fails, STOP. Return this exact message to the orchestrator:
 
    ```
    APPLY FAILED AFTER RECOVERY: <URL>

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({ ..., headless: true, 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.**
+2. **Direct Geometra helper:** Most non-Greenhouse job portals (Lever, Ashby, Workday) are SPAs. Use `npx job-forge portal:snapshot --url "{url}" --json` to render and read the page model/snapshot. This helper enforces `headless: true`, `stealth: true`, and `isolated: true` in code, reads `config/profile.yml` proxy config, and closes Chromium before exit. **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({ ..., headless: true, 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.
+1. **Extract form questions**: Prefer `npx job-forge portal:form-schema --url "{apply_url}" --json` to discover all form fields without leaving a browser open. Use Geometra MCP only when a live multi-step browser session already exists and must be reused. 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({ ..., headless: true, stealth: true })` + geometra_page_model) → WebFetch → WebSearch
+   b. **Extract JD** using Greenhouse API → `npx job-forge portal:snapshot --url "$URL" --json` → Geometra MCP only if an interactive session is needed → 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,9 +34,10 @@ 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({ ..., headless: true, 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.
+2. **Direct Geometra helper:** `npx job-forge portal:snapshot --url "{url}" --json`. Works with non-Greenhouse SPAs (Lever, Ashby, Workday), enforces `headless: true`, `stealth: true`, and `isolated: true` in code, reads `config/profile.yml` proxy config, and closes Chromium before exit.
+3. **Geometra MCP (interactive fallback):** Use only when the one-shot helper is not enough and a live multi-step browser session is required.
+4. **WebFetch (fallback):** For static pages or when Geometra is not available.
+5. **WebSearch (last resort):** Search on secondary portals that index the JD.
 
 **Special cases:**
 - **LinkedIn**: May require login → mark `[!]` and ask the user to paste the text
@@ -68,6 +69,7 @@ Step 1  — Read data/pipeline.md; collect "- [ ]" URLs into `pending = [url_1,
 Step 2  — Pre-flight cleanup (once, before loop):
             geometra_list_sessions()
             geometra_disconnect({ closeBrowser: true })
+            # portal:* helpers are direct-package one-shots and auto-close.
 Step 3  — For round in ceil(N/2):
             pair = pending[round*2 : round*2 + 2]
             # ONE message, 1 or 2 task() calls. Never 3.

package/modes/reference-geometra.md

@@ -159,6 +159,8 @@ Subagents launched via the `task` tool start with a fresh context and cannot aut
 
 **Fix in one sentence:** ALWAYS run `geometra_list_sessions` + `geometra_disconnect` BEFORE `geometra_connect`. Every time. No exceptions except the one explicit exception below.
 
+If Geometra MCP itself disappears or becomes unresponsive, inspect `.jobforge-mcp/geometra-mcp.jsonl` before escalating. `signal_received` means the MCP host or parent process sent a catchable signal, `child_exit` means the Geometra child exited, `child_stderr` preserves stderr that may not show in the agent transcript, and a final stale `heartbeat` with no later event usually means SIGKILL / host reap / OS kill. Report the final event type and timestamp rather than saying only "MCP crashed."
+
 ---
 
 #### Rule 1 — Orchestrator pre-dispatch cleanup (DO THIS EVERY TIME)

package/modes/reference-local-helpers.md

@@ -10,6 +10,7 @@ Prefer a local helper when the workflow needs:
 - Machine-readable artifact validation.
 - Context, capability, or migration policy.
 - Dispatch planning or settlement.
+- One-shot rendered browser snapshots or form schemas.
 - Scoring, timing, priority, or lineage decisions.
 - Safe export checks.
 
@@ -26,6 +27,7 @@ Do not paste whole helper outputs into prompts unless the downstream agent needs
 | Artifact contracts | `templates/contracts.json` | `npx job-forge tracker-line ... --write`; `npx job-forge verify` |
 | Role capability policy | `templates/capabilities.json` | `npx job-forge capabilities:*` |
 | Context bundle policy | `templates/context.json` | `npx job-forge context:*` |
+| Browser snapshots / form schemas | Direct `@geometra/mcp` session module | `npx job-forge portal:*` |
 | JD/artifact reuse | `.jobforge-cache/` | `npx job-forge cache:*` |
 | Artifact lookup | `.jobforge-index.json` from `templates/index.json` | `npx job-forge index:*` |
 | Source-backed facts | `.jobforge-facts.json` from `templates/facts.json` | `npx job-forge facts:*` |
@@ -49,6 +51,7 @@ Do not paste whole helper outputs into prompts unless the downstream agent needs
 - For generated reports or PDFs reused after input changes, run `lineage:check --artifact <file>` if lineage exists; after creating derived artifacts, record them with `lineage:record --artifact <file> --input <source>...`.
 - Before exporting traces, prompts, reports, or fixtures outside the project, run `redact:scan`, `redact:apply`, or `redact:verify`.
 - When diagnosing consumer harness drift, run `migrate:plan` or `migrate:check`; `job-forge sync` applies safe migrations automatically unless `JOB_FORGE_SKIP_MIGRATIONS=1` is set.
+- When you only need a rendered page model, compact snapshot, or form schema from one URL, prefer `portal:snapshot` / `portal:form-schema` over Geometra MCP tool calls. Use MCP for interactive multi-step browser sessions.
 
 ## Enforcement
 

package/modes/reference-portals.md

@@ -100,6 +100,10 @@ Apply these rules when deciding whether the proxy is worth waiting for:
 
 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.
 
+### Direct helper for one-shot reads
+
+Use `npx job-forge portal:snapshot --url "{url}" --json` or `npx job-forge portal:form-schema --url "{url}" --json` when you only need a rendered page model, compact snapshot, or form schema. These commands import Geometra's session module directly instead of going through MCP, enforce `headless: true`, `stealth: true`, and `isolated: true`, pass the `config/profile.yml` proxy block if configured, and close Chromium before exit. Keep MCP for interactive multi-step browser automation where a live `sessionId` must be driven across actions.
+
 ### Troubleshooting
 
 | Symptom | Diagnosis |
@@ -141,4 +145,20 @@ The Geometra MCP partitions its reusable-proxy pool by proxy identity and browse
 
 `job-forge mcp:geometra` resolves Geometra in this order: `JOB_FORGE_GEOMETRA_MCP_PATH`, then `package.json -> jobForge.geometraMcpPath`, then `opencode.json -> mcp.geometra.environment.JOB_FORGE_GEOMETRA_MCP_PATH`, then a sibling local `../geometra/mcp/dist/index.js` checkout for maintainers working across both repos, then the pinned npm fallback.
 
+JobForge's Geometra launcher writes a durable lifecycle log at `.jobforge-mcp/geometra-mcp.jsonl` in the consumer project. The log is JSONL and does not use stdout, so it does not interfere with the MCP stdio protocol. Expected events include `launcher_start`, `child_spawn`, periodic `heartbeat`, `child_stderr`, `signal_received`, `child_error`, and `child_exit`. Override the location with `JOB_FORGE_GEOMETRA_MCP_LOG_PATH`, disable it with `JOB_FORGE_GEOMETRA_MCP_LOG=0`, or tune the heartbeat with `JOB_FORGE_GEOMETRA_MCP_HEARTBEAT_MS`.
+
 To check or modify MCP settings, edit `opencode.json` in the project root.
+
+## Silent MCP Death Diagnostics
+
+If Geometra MCP vanishes with no stderr, no crash log, and subsequent calls return `Not connected`, inspect the lifecycle log before making a claim:
+
+```bash
+tail -40 .jobforge-mcp/geometra-mcp.jsonl
+```
+
+- Last event is `signal_received`: the MCP host or parent process sent a catchable signal such as `SIGTERM`.
+- Last event is `child_exit`: the Geometra child process exited and the log should show its code or signal.
+- Last event is `child_stderr`: preserve the stderr text; it is the best upstream bug report payload.
+- Last event is an old `heartbeat` with no later `signal_received` or `child_exit`: likely host `SIGKILL`, OS kill, or wrapper process death. No process can log after `SIGKILL`, so report the heartbeat timestamp and the missing exit event.
+- No `launcher_start`: OpenCode never started JobForge's Geometra launcher, or it used a different MCP command/config.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "job-forge",
-  "version": "2.14.42",
+  "version": "2.14.44",
   "description": "AI-powered job search pipeline built on opencode",
   "type": "module",
   "bin": {
@@ -18,6 +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",
+    "portal:snapshot": "node bin/job-forge.mjs portal:snapshot",
+    "portal:form-schema": "node bin/job-forge.mjs portal:form-schema",
+    "portal:explain": "node bin/job-forge.mjs portal:explain",
     "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",
@@ -196,6 +199,7 @@
     "@agent-pattern-labs/iso-score": "^0.1.1",
     "@agent-pattern-labs/iso-timeline": "^0.1.1",
     "@agent-pattern-labs/iso-trace": "^0.5.1",
+    "@geometra/mcp": "1.62.1",
     "playwright": "^1.58.1"
   },
   "devDependencies": {

package/scripts/check-helper-integration.mjs

@@ -20,6 +20,7 @@ const groups = [
   helper('trace', '@agent-pattern-labs/iso-trace', ['list', 'stats', 'show']),
   helper('telemetry', '', ['list', 'status', 'show', 'watch']),
   helper('guard', '@agent-pattern-labs/iso-guard', ['audit', 'explain'], { template: 'templates/guards/jobforge-baseline.yaml' }),
+  helper('portal', '@geometra/mcp', ['snapshot', 'form-schema', 'explain'], { migrated: true }),
   helper('ledger', '@agent-pattern-labs/iso-ledger', ['status', 'rebuild', 'verify', 'has', 'query'], { artifacts: ['.jobforge-ledger/'] }),
   helper('capabilities', '@agent-pattern-labs/iso-capabilities', ['list', 'explain', 'check', 'render'], { template: 'templates/capabilities.json', migrated: true }),
   helper('context', '@agent-pattern-labs/iso-context', ['list', 'explain', 'plan', 'check', 'render'], { template: 'templates/context.json', migrated: true }),

package/scripts/check-iso-smoke.mjs

@@ -22,12 +22,14 @@ const checks = [
   ["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 headless stealth", () => every(files.instructions, ["[H8]", "Do not transcribe `server`, `username`, `password`, or `bypass`", "`headless: true`", "`stealth: true`"])],
+  ["H9 points to Geometra MCP lifecycle logs", () => every(files.instructions, ["[H9]", ".jobforge-mcp/geometra-mcp.jsonl", "launcher_start", "heartbeat", "child_exit"])],
   ["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)],
   ["shared prompt points to on-demand references", () => every(files.instructions, ["modes/{mode}.md", "modes/reference-setup.md", "modes/reference-portals.md", "modes/reference-geometra.md"])],
   ["apply mode requires headless stealth Geometra", () => every(files.apply, ["`headless: true`", "`stealth: true`", "`isolated: true`", "every Geometra auto-connect call"])],
+  ["apply mode uses host-safe run_actions continuations", () => every(files.apply, ["softTimeoutMs: 45000", "resumeFromIndex", "pauseReason: \"soft-timeout\"", "This is a continuation, not a retry"])],
   ["apply mode owns high-stakes upgrade", () => every(files.apply, ["[D8]", "@general-paid", "4.0/5", "high-stakes"])],
   ["apply mode blocks provider auto-downgrade", () => every(files.apply, ["[D9]", "do not auto-downgrade", "inspect telemetry before retrying"])],
   ["models policy pins OpenCode to DeepSeek V4 Flash", () => /extends:\s*standard/.test(files.models) && count(files.models, "opencode-go/deepseek-v4-flash") >= 4],

package/scripts/portal.mjs

@@ -0,0 +1,369 @@
+#!/usr/bin/env node
+
+import { createRequire } from 'node:module';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { PROJECT_DIR } from '../tracker-lib.mjs';
+
+const DEFAULT_WIDTH = 1024;
+const DEFAULT_HEIGHT = 768;
+const DEFAULT_SLOW_MO = 350;
+const DEFAULT_MAX_NODES = 120;
+
+const USAGE = `job-forge portal - deterministic direct-Geometra browser helpers
+
+Usage:
+  job-forge portal:snapshot --url <url> [--json] [--forms] [--max-nodes N]
+  job-forge portal:form-schema --url <url> [--json] [--include-options]
+  job-forge portal:explain [--json]
+
+Defaults are enforced in code for every browser launch:
+  isolated: true
+  headless: true
+  stealth: true
+  slowMo: 350
+
+The helper imports Geometra's session module directly. It does not call the
+MCP tool protocol, does not leave a reusable browser pool behind, and closes
+its isolated Chromium before exit. If config/profile.yml contains a top-level
+proxy: block with server/username/password/bypass, it is threaded into the
+browser unless --no-profile-proxy is passed.`;
+
+const [cmd = 'help', ...rawArgs] = process.argv.slice(2);
+const opts = parseArgs(rawArgs);
+
+if (opts.help || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+  console.log(USAGE);
+  process.exit(0);
+}
+
+try {
+  if (cmd === 'snapshot') {
+    await snapshot(opts);
+  } else if (cmd === 'form-schema') {
+    await formSchema(opts);
+  } else if (cmd === 'explain') {
+    await explain(opts);
+  } else {
+    console.error(`unknown portal command "${cmd}"\n`);
+    console.error(USAGE);
+    process.exit(2);
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}
+
+async function snapshot(opts) {
+  if (!opts.url) throw new Error('portal:snapshot requires --url <url>');
+  const geometra = await loadGeometraSessionModule();
+  const proxy = opts.profileProxy ? readProfileProxy(PROJECT_DIR) : null;
+  const session = await connect(geometra, opts, proxy);
+
+  try {
+    const root = buildRoot(geometra, session);
+    const pageModel = geometra.buildPageModel(root, {
+      maxPrimaryActions: opts.maxPrimaryActions,
+      maxSectionsPerKind: opts.maxSectionsPerKind,
+    });
+    const compact = geometra.buildCompactUiIndex(root, {
+      maxNodes: opts.maxNodes,
+      viewportWidth: opts.width,
+      viewportHeight: opts.height,
+    });
+    const result = {
+      url: opts.url,
+      session: connectionSummary(session, proxy),
+      defaults: launchDefaults(opts, proxy),
+      pageModel,
+      compact,
+      ...(opts.forms ? { forms: geometra.buildFormSchemas(root, formOptions(opts)) } : {}),
+    };
+    output(result, opts, () => {
+      console.log(`url: ${opts.url}`);
+      console.log(`session: ${session.id}`);
+      console.log(`defaults: isolated=true headless=true stealth=true slowMo=${opts.slowMo}`);
+      if (proxy) console.log(`proxy: ${redactProxy(proxy)}`);
+      console.log(geometra.summarizePageModel(pageModel, 12));
+      console.log(geometra.summarizeCompactIndex(compact.nodes, 24));
+      if (opts.forms) {
+        console.log(`forms: ${result.forms.length}`);
+      }
+    });
+  } finally {
+    geometra.disconnect({ sessionId: session.id, closeProxy: true });
+  }
+}
+
+async function formSchema(opts) {
+  if (!opts.url) throw new Error('portal:form-schema requires --url <url>');
+  const geometra = await loadGeometraSessionModule();
+  const proxy = opts.profileProxy ? readProfileProxy(PROJECT_DIR) : null;
+  const session = await connect(geometra, opts, proxy);
+
+  try {
+    const root = buildRoot(geometra, session);
+    const forms = geometra.buildFormSchemas(root, formOptions(opts));
+    const result = {
+      url: opts.url,
+      session: connectionSummary(session, proxy),
+      defaults: launchDefaults(opts, proxy),
+      forms,
+    };
+    output(result, opts, () => {
+      console.log(`url: ${opts.url}`);
+      console.log(`session: ${session.id}`);
+      console.log(`defaults: isolated=true headless=true stealth=true slowMo=${opts.slowMo}`);
+      if (proxy) console.log(`proxy: ${redactProxy(proxy)}`);
+      for (const form of forms) {
+        const name = form.name ? ` "${form.name}"` : '';
+        console.log(`${form.formId}${name}: ${form.fieldCount} fields, ${form.requiredCount} required, ${form.invalidCount} invalid`);
+        for (const field of form.fields.slice(0, opts.maxFields)) {
+          const required = field.required ? ' required' : '';
+          const invalid = field.invalid ? ' invalid' : '';
+          const label = field.label || field.name || field.id;
+          console.log(`  - ${field.kind}: ${label}${required}${invalid}`);
+        }
+      }
+    });
+  } finally {
+    geometra.disconnect({ sessionId: session.id, closeProxy: true });
+  }
+}
+
+async function explain(opts) {
+  const moduleTarget = resolveGeometraSessionModule();
+  const proxy = opts.profileProxy ? readProfileProxy(PROJECT_DIR) : null;
+  const result = {
+    projectDir: PROJECT_DIR,
+    module: moduleTarget,
+    defaults: launchDefaults(opts, proxy),
+    profileProxy: proxy ? redactProxy(proxy) : null,
+  };
+  output(result, opts, () => {
+    console.log(`project: ${PROJECT_DIR}`);
+    console.log(`module: ${moduleTarget.source} ${moduleTarget.path}`);
+    console.log(`defaults: isolated=true headless=true stealth=true slowMo=${opts.slowMo}`);
+    console.log(`profile proxy: ${proxy ? redactProxy(proxy) : 'none'}`);
+  });
+}
+
+async function connect(geometra, opts, proxy) {
+  return await geometra.connectThroughProxy({
+    pageUrl: opts.url,
+    isolated: true,
+    headless: true,
+    stealth: true,
+    slowMo: opts.slowMo,
+    width: opts.width,
+    height: opts.height,
+    awaitInitialFrame: true,
+    eagerInitialExtract: true,
+    ...(proxy ? { proxy } : {}),
+  });
+}
+
+function buildRoot(geometra, session) {
+  if (!session.tree || !session.layout) {
+    throw new Error(`Geometra session ${session.id} did not return an accessibility tree`);
+  }
+  return geometra.buildA11yTree(session.tree, session.layout);
+}
+
+async function loadGeometraSessionModule() {
+  const target = resolveGeometraSessionModule();
+  try {
+    return await import(pathToFileURL(target.path).href);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to load Geometra session module from ${target.path}: ${detail}`);
+  }
+}
+
+function resolveGeometraSessionModule() {
+  const explicit = normalizeEnv(process.env.JOB_FORGE_GEOMETRA_SESSION_MODULE);
+  if (explicit) return existingModulePath('env', resolve(explicit));
+
+  const scriptDir = dirname(fileURLToPath(import.meta.url));
+  const siblingPath = resolve(scriptDir, '../../geometra/mcp/dist/session.js');
+  if (existsSync(siblingPath)) return { source: 'sibling-repo', path: siblingPath };
+
+  const require = createRequire(import.meta.url);
+  try {
+    return {
+      source: 'package',
+      path: require.resolve('@geometra/mcp/dist/session.js'),
+    };
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`Could not resolve @geometra/mcp/dist/session.js. Install dependencies with npm install. Resolution error: ${detail}`);
+  }
+}
+
+function existingModulePath(source, path) {
+  if (!existsSync(path)) throw new Error(`${source} Geometra session module not found: ${path}`);
+  return { source, path };
+}
+
+function parseArgs(args) {
+  const opts = {
+    help: false,
+    json: false,
+    forms: false,
+    includeOptions: false,
+    profileProxy: true,
+    width: DEFAULT_WIDTH,
+    height: DEFAULT_HEIGHT,
+    slowMo: DEFAULT_SLOW_MO,
+    maxNodes: DEFAULT_MAX_NODES,
+    maxFields: 80,
+    maxPrimaryActions: 6,
+    maxSectionsPerKind: 8,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--url' || arg === '-u') {
+      opts.url = valueAfter(args, ++i, arg);
+    } else if (arg.startsWith('--url=')) {
+      opts.url = arg.slice('--url='.length);
+    } else if (arg === '--json') {
+      opts.json = true;
+    } else if (arg === '--forms') {
+      opts.forms = true;
+    } else if (arg === '--include-options') {
+      opts.includeOptions = true;
+    } else if (arg === '--no-profile-proxy') {
+      opts.profileProxy = false;
+    } else if (arg === '--width') {
+      opts.width = parsePositiveInt(valueAfter(args, ++i, arg), arg);
+    } else if (arg.startsWith('--width=')) {
+      opts.width = parsePositiveInt(arg.slice('--width='.length), '--width');
+    } else if (arg === '--height') {
+      opts.height = parsePositiveInt(valueAfter(args, ++i, arg), arg);
+    } else if (arg.startsWith('--height=')) {
+      opts.height = parsePositiveInt(arg.slice('--height='.length), '--height');
+    } else if (arg === '--slow-mo') {
+      opts.slowMo = parseNonNegativeInt(valueAfter(args, ++i, arg), arg);
+    } else if (arg.startsWith('--slow-mo=')) {
+      opts.slowMo = parseNonNegativeInt(arg.slice('--slow-mo='.length), '--slow-mo');
+    } else if (arg === '--max-nodes') {
+      opts.maxNodes = parsePositiveInt(valueAfter(args, ++i, arg), arg);
+    } else if (arg.startsWith('--max-nodes=')) {
+      opts.maxNodes = parsePositiveInt(arg.slice('--max-nodes='.length), '--max-nodes');
+    } else if (arg === '--max-fields') {
+      opts.maxFields = parsePositiveInt(valueAfter(args, ++i, arg), arg);
+    } else if (arg.startsWith('--max-fields=')) {
+      opts.maxFields = parsePositiveInt(arg.slice('--max-fields='.length), '--max-fields');
+    } else if (arg === '--help' || arg === '-h') {
+      opts.help = true;
+    } else {
+      throw new Error(`unknown flag "${arg}"`);
+    }
+  }
+
+  return opts;
+}
+
+function formOptions(opts) {
+  return {
+    includeOptions: opts.includeOptions,
+    maxFields: opts.maxFields,
+  };
+}
+
+function readProfileProxy(projectDir) {
+  const profilePath = join(projectDir, 'config', 'profile.yml');
+  if (!existsSync(profilePath)) return null;
+  const proxy = parseTopLevelProxy(readFileSync(profilePath, 'utf8'));
+  return proxy?.server ? proxy : null;
+}
+
+function parseTopLevelProxy(source) {
+  const lines = source.split(/\r?\n/);
+  const start = lines.findIndex((line) => /^proxy:\s*(?:#.*)?$/.test(line));
+  if (start === -1) return null;
+  const proxy = {};
+  for (const line of lines.slice(start + 1)) {
+    if (/^\S/.test(line) && line.trim() !== '') break;
+    const match = line.match(/^\s+([A-Za-z_][A-Za-z0-9_]*):\s*(.*?)\s*$/);
+    if (!match) continue;
+    const key = match[1];
+    if (!['server', 'username', 'password', 'bypass'].includes(key)) continue;
+    const value = parseYamlScalar(match[2]);
+    if (value !== '') proxy[key] = value;
+  }
+  return Object.keys(proxy).length > 0 ? proxy : null;
+}
+
+function parseYamlScalar(raw) {
+  const withoutComment = raw.replace(/\s+#.*$/, '').trim();
+  if ((withoutComment.startsWith('"') && withoutComment.endsWith('"')) ||
+      (withoutComment.startsWith("'") && withoutComment.endsWith("'"))) {
+    return withoutComment.slice(1, -1);
+  }
+  return withoutComment;
+}
+
+function output(result, opts, textPrinter) {
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    textPrinter();
+  }
+}
+
+function launchDefaults(opts, proxy) {
+  return {
+    isolated: true,
+    headless: true,
+    stealth: true,
+    slowMo: opts.slowMo,
+    width: opts.width,
+    height: opts.height,
+    profileProxy: Boolean(proxy),
+  };
+}
+
+function connectionSummary(session, proxy) {
+  return {
+    id: session.id,
+    url: session.url,
+    proxy: Boolean(proxy),
+  };
+}
+
+function redactProxy(proxy) {
+  try {
+    const url = new URL(proxy.server);
+    const auth = proxy.username || proxy.password || url.username || url.password ? ' auth=present' : '';
+    return `${url.protocol}//${url.host}${auth}${proxy.bypass ? ' bypass=present' : ''}`;
+  } catch {
+    return 'configured';
+  }
+}
+
+function normalizeEnv(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function valueAfter(args, index, flag) {
+  const value = args[index];
+  if (!value || value.startsWith('--')) throw new Error(`${flag} requires a value`);
+  return value;
+}
+
+function parsePositiveInt(value, flag) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isInteger(parsed) || parsed <= 0) throw new Error(`${flag} must be a positive integer`);
+  return parsed;
+}
+
+function parseNonNegativeInt(value, flag) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isInteger(parsed) || parsed < 0) throw new Error(`${flag} must be a non-negative integer`);
+  return parsed;
+}

package/templates/migrations.json

@@ -19,6 +19,9 @@
             "context:plan": "job-forge context:plan",
             "context:check": "job-forge context:check",
             "context:render": "job-forge context:render",
+            "portal:snapshot": "job-forge portal:snapshot",
+            "portal:form-schema": "job-forge portal:form-schema",
+            "portal:explain": "job-forge portal:explain",
             "cache:key": "job-forge cache:key",
             "cache:has": "job-forge cache:has",
             "cache:get": "job-forge cache:get",
@@ -109,6 +112,7 @@
             ".jobforge-prioritize.json",
             ".jobforge-prioritize-items.json",
             ".jobforge-lineage.json",
+            ".jobforge-mcp/",
             ".jobforge-redacted/",
             "data/timeline-events.jsonl",
             "batch/preflight-candidates.json",