job-application-agent 3.5.0 → 3.6.0

package/job-application-agent/scripts/job-application.mjs

@@ -14,6 +14,18 @@ import { normalizeCommunityJob, normalizeCommunitySource } from './source-commun
 import { TelemetryClient } from './telemetry-client.mjs';
 import { jobIdentity } from './telemetry-schema.mjs';
 import { CloudStateClient, defaultCloudConfigPath, enableCloudUpdateGuard, saveCloudConfig } from './cloud-state-client.mjs';
+import {
+  SESSION_BINDING_ATTENTION_KEYS,
+  createSessionBinding,
+  extractSessionBindingFields,
+  sessionBindingPath,
+  writeSessionBindingFile,
+} from './session-binding.mjs';
+import {
+  detectAiAssistanceDiscouraged,
+  extractNarrativeQuestionsFromText,
+  normalizeAttentionQuestions,
+} from './attention-questions.mjs';
 
 const SOURCES = new Set(['linkedin', 'greenhouse', 'lever', 'ashby', 'workable', 'comeet', 'workday', 'rippling', 'smartrecruiters', 'google-form', 'company', 'email', 'other']);
 const DISCOVERY_SOURCES = new Set(['direct-company', 'linkedin', 'x', 'yc', 'hacker-news', 'job-board', 'email', 'user-supplied', 'web-search', 'other']);
@@ -1302,9 +1314,62 @@ async function attentionList(roundId = null) {
   return { count: items.length, items };
 }
 
+async function attentionNotifyHook(event, context = {}) {
+  const notifyUrl = process.env.ATTENTION_NOTIFY_URL?.trim();
+  const notifySecret = process.env.ATTENTION_NOTIFY_SECRET?.trim();
+  if (!notifyUrl || !notifySecret) return { attempted: false, reason: 'notify_unconfigured' };
+
+  let email = '';
+  try { email = String(storedProfileRaw()?.email ?? '').trim().toLowerCase(); } catch { email = ''; }
+  if (!email) {
+    console.error('[attention-notify] profile email missing; skip notify fail-closed');
+    return { attempted: true, ok: false, error: 'profile_email_missing' };
+  }
+
+  const company = String(context.company ?? '').trim() || 'Company';
+  const role = String(context.role ?? '').trim() || 'Role';
+  try {
+    const response = await fetch(notifyUrl, {
+      method: 'POST',
+      headers: {
+        authorization: `Bearer ${notifySecret}`,
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({
+        attentionId: event.id,
+        email,
+        company,
+        role,
+        url: event.url,
+        stage: event.stage,
+        blocker: event.blocker,
+        requiredActions: event.requiredActions,
+        questions: event.questions ?? [],
+        aiAssistanceDiscouraged: Boolean(event.aiAssistanceDiscouraged),
+        postingText: context.postingText ?? '',
+      }),
+    });
+    const body = await response.json().catch(() => ({}));
+    if (!response.ok) {
+      console.error(`[attention-notify] site notify failed (${response.status}): ${body?.error ?? 'unknown'}`);
+      return { attempted: true, ok: false, error: body?.error ?? 'notify_failed', status: response.status };
+    }
+    return { attempted: true, ok: true, magicLinkUrl: body?.magicLinkUrl ?? null, emailId: body?.emailId ?? null };
+  } catch (error) {
+    console.error(`[attention-notify] site notify request failed: ${error instanceof Error ? error.message : 'unknown'}`);
+    return { attempted: true, ok: false, error: 'notify_request_failed' };
+  }
+}
+
 async function attentionAdd(input) {
   const value = object(input, 'attention item');
-  const allowed = new Set(['roundId', 'applicationId', 'url', 'stage', 'blocker', 'requiredActions', 'createdAt']);
+  const allowed = new Set([
+    'roundId', 'applicationId', 'url', 'stage', 'blocker', 'requiredActions', 'createdAt', 'company', 'role',
+    // P1.5 judgment packaging (prompts only — never candidate responses).
+    'questions', 'postingText', 'aiAssistanceDiscouraged',
+    // Local-only session binding hooks — never appended to the cloud attention event.
+    ...SESSION_BINDING_ATTENTION_KEYS,
+  ]);
   for (const key of Object.keys(value)) if (!allowed.has(key)) throw new Error(`Unknown attention property: ${key}.`);
   const stage = string(value.stage, 'attention.stage', 40).toLowerCase();
   const blocker = string(value.blocker, 'attention.blocker', 60).toLowerCase();
@@ -1312,19 +1377,62 @@ async function attentionAdd(input) {
   if (!ATTENTION_BLOCKERS.has(blocker)) throw new Error('attention.blocker is invalid.');
   const requiredActions = stringArray(value.requiredActions, 'attention.requiredActions', true).map((item) => item.toLowerCase());
   if (requiredActions.length > 8 || requiredActions.some((item) => !REQUIRED_ACTIONS.has(item))) throw new Error('attention.requiredActions must contain only documented actions.');
+  const applicationId = string(value.applicationId, 'attention.applicationId', 180);
+  let company = typeof value.company === 'string' ? value.company.trim() : '';
+  let role = typeof value.role === 'string' ? value.role.trim() : '';
+  if (!company || !role) {
+    try {
+      const apps = await jsonLines(join(await ensureStateDir(), 'applications.ndjson'));
+      const match = apps.find((entry) => entry.id === applicationId);
+      if (match) {
+        company = company || String(match.company ?? '').trim();
+        role = role || String(match.role ?? match.title ?? '').trim();
+      }
+    } catch { /* best-effort context for notify only */ }
+  }
+  const postingText = typeof value.postingText === 'string' ? value.postingText.slice(0, 20_000) : '';
+  let questions = normalizeAttentionQuestions(value.questions);
+  if (!questions.length && postingText && requiredActions.includes('provide-judgment')) {
+    questions = extractNarrativeQuestionsFromText(postingText);
+  }
+  const aiAssistanceDiscouraged = value.aiAssistanceDiscouraged === true
+    || detectAiAssistanceDiscouraged(postingText);
+  const localBindingFields = extractSessionBindingFields(value);
   const event = {
     type: 'opened',
     id: `attention-${randomUUID()}`,
     roundId: string(value.roundId, 'attention.roundId', 180),
-    applicationId: string(value.applicationId, 'attention.applicationId', 180),
+    applicationId,
     url: string(value.url, 'attention.url', 2048),
     stage,
     blocker,
     requiredActions: [...new Set(requiredActions)],
+    // Prompts only — never store candidate responses on the attention queue.
+    ...(questions.length ? { questions } : {}),
+    ...(aiAssistanceDiscouraged ? { aiAssistanceDiscouraged: true } : {}),
     createdAt: isoDate(value.createdAt, 'attention.createdAt'),
   };
   await appendPrivateEvent('attention', event);
-  return event;
+
+  let sessionBinding = null;
+  if (localBindingFields) {
+    const binding = createSessionBinding({
+      attentionId: event.id,
+      jobUrl: event.url,
+      applicationId: event.applicationId,
+      roundId: event.roundId,
+      createdAt: event.createdAt,
+      questions: event.questions,
+      aiAssistanceDiscouraged: event.aiAssistanceDiscouraged,
+      ...localBindingFields,
+    });
+    const path = sessionBindingPath(await ensureStateDir(), event.id);
+    sessionBinding = { path, binding: await writeSessionBindingFile(path, binding) };
+  }
+
+  const notify = await attentionNotifyHook(event, { company, role, postingText });
+  const base = sessionBinding ? { ...event, sessionBinding } : event;
+  return notify.attempted ? { ...base, notify } : base;
 }
 
 async function attentionResolve(input) {
@@ -1726,6 +1834,12 @@ async function recordInstallationStart(telemetry, session) {
 
 async function main(args) {
   const [area, action, value] = args;
+  // Outreach is private-only, including errors: never initialize telemetry or
+  // community clients, flush their queues, or run generic reconciliation here.
+  if (area === 'outreach') {
+    const { runOutreach } = await import('./outreach-cli.mjs');
+    return print(await runOutreach(args.slice(1)));
+  }
   const telemetry = new TelemetryClient({ stateDir: stateDir(), readIdentity: () => {
     const profile = storedProfileRaw();
     // Only explicit saved fields; no resume parsing, conversation scraping, or full profile payload.

package/job-application-agent/scripts/novnc-display-guard.mjs

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+/**
+ * Guard: live noVNC / websockify must target the fill x11vnc port (5900),
+ * never TigerVNC (5901). Product failure if the buyer live panel shows a
+ * cold XFCE / jobs listing instead of the paused filled ATS form.
+ *
+ * Usage:
+ *   node scripts/novnc-display-guard.mjs
+ *   node scripts/novnc-display-guard.mjs --unit /etc/systemd/system/novnc.service
+ *   node scripts/novnc-display-guard.mjs --text "websockify ... localhost:5900"
+ *   node scripts/novnc-display-guard.mjs --warn   # warn-only (exit 0 with warning)
+ *
+ * Exit: 0 ok · 1 misconfigured / forbidden target · 2 usage
+ */
+
+import { readFile } from "node:fs/promises";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import {
+  FILL_DISPLAY,
+  FILL_VNC_PORT,
+  FORBIDDEN_DISPLAY,
+  FORBIDDEN_VNC_PORT,
+} from "./session-binding.mjs";
+
+export const NOVNC_GUARD_EXIT = Object.freeze({
+  OK: 0,
+  FAIL: 1,
+  USAGE: 2,
+});
+
+/**
+ * Inspect free-form service / command text for websockify VNC targets.
+ * @param {string} text
+ */
+export function inspectNovncTargetText(text) {
+  const raw = String(text ?? "");
+  const findings = {
+    fillPortMentions: [],
+    forbiddenPortMentions: [],
+    fillDisplayMentions: [],
+    forbiddenDisplayMentions: [],
+    websockifyTargets: [],
+  };
+
+  const portRe = /(?::|localhost\s+)\s*(5900|5901)\b|(?:^|[\s=])(5900|5901)\b/gi;
+  let match;
+  while ((match = portRe.exec(raw)) !== null) {
+    const port = Number(match[1] || match[2]);
+    if (port === FILL_VNC_PORT) findings.fillPortMentions.push(match[0].trim());
+    if (port === FORBIDDEN_VNC_PORT) findings.forbiddenPortMentions.push(match[0].trim());
+  }
+
+  if (/(?:DISPLAY=):?99\b|(?:^|[\s]) :99\b/i.test(raw)) {
+    findings.fillDisplayMentions.push(FILL_DISPLAY);
+  }
+  if (/(?:DISPLAY=):1\b|(?:listen|rfbport).*:1\b/i.test(raw)) {
+    findings.forbiddenDisplayMentions.push(FORBIDDEN_DISPLAY);
+  }
+
+  // Scan host:port pairs on active websockify / proxy lines (skip comment-only).
+  for (const line of raw.split(/\r?\n/)) {
+    const active = line.replace(/#.*$/, "").trim();
+    if (!active || !/websockify|novnc|vnc/i.test(active)) continue;
+    const hostPort = active.match(/(127\.0\.0\.1|localhost|\[::1\])[:\s]+(5900|5901)\b/i);
+    if (hostPort) {
+      findings.websockifyTargets.push({
+        host: hostPort[1],
+        port: Number(hostPort[2]),
+        line: active,
+      });
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Decide pass/fail from inspect findings + optional explicit target.
+ * @param {{
+ *   text?: string,
+ *   targetHost?: string,
+ *   targetPort?: number,
+ *   display?: string,
+ * }} input
+ */
+export function evaluateNovncDisplayGuard(input = {}) {
+  const text = String(input.text ?? "");
+  const findings = text ? inspectNovncTargetText(text) : {
+    fillPortMentions: [],
+    forbiddenPortMentions: [],
+    fillDisplayMentions: [],
+    forbiddenDisplayMentions: [],
+    websockifyTargets: [],
+  };
+
+  const forbiddenTargets = findings.websockifyTargets.filter((t) => t.port === FORBIDDEN_VNC_PORT);
+  const fillTargets = findings.websockifyTargets.filter((t) => t.port === FILL_VNC_PORT);
+
+  const targetPort = input.targetPort != null
+    ? Number(input.targetPort)
+    : (forbiddenTargets[0]?.port ?? fillTargets[0]?.port ?? findings.websockifyTargets[0]?.port);
+  const targetHost = input.targetHost
+    ?? forbiddenTargets[0]?.host
+    ?? fillTargets[0]?.host
+    ?? findings.websockifyTargets[0]?.host
+    ?? null;
+  const display = input.display
+    ?? (findings.fillDisplayMentions[0] || findings.forbiddenDisplayMentions[0] || null);
+
+  /** @type {string[]} */
+  const errors = [];
+  /** @type {string[]} */
+  const warnings = [];
+
+  if (forbiddenTargets.length || (input.targetPort != null && Number(input.targetPort) === FORBIDDEN_VNC_PORT)) {
+    errors.push(
+      `Live noVNC must not target TigerVNC port ${FORBIDDEN_VNC_PORT}. Use fill x11vnc localhost:${FILL_VNC_PORT} (DISPLAY=${FILL_DISPLAY}).`,
+    );
+  }
+  if (findings.forbiddenDisplayMentions.length || display === FORBIDDEN_DISPLAY) {
+    errors.push(
+      `Display ${FORBIDDEN_DISPLAY} is TigerVNC — never the buyer live panel. Fill + live share DISPLAY=${FILL_DISPLAY}.`,
+    );
+  }
+
+  if (targetPort != null && Number.isFinite(targetPort)) {
+    if (targetPort === FORBIDDEN_VNC_PORT) {
+      if (!errors.some((e) => e.includes(String(FORBIDDEN_VNC_PORT)))) {
+        errors.push(`websockify target port ${FORBIDDEN_VNC_PORT} is forbidden.`);
+      }
+    } else if (targetPort !== FILL_VNC_PORT) {
+      errors.push(`websockify target port must be ${FILL_VNC_PORT} (got ${targetPort}).`);
+    }
+  } else if (text && findings.websockifyTargets.length === 0 && findings.fillPortMentions.length === 0) {
+    warnings.push(
+      `No localhost:${FILL_VNC_PORT} websockify target found in unit/text — confirm novnc.service proxies fill x11vnc.`,
+    );
+  }
+
+  // Mentions of 5901 in comments are fine when ExecStart clearly targets 5900.
+  if (findings.forbiddenPortMentions.length && !forbiddenTargets.length && fillTargets.length) {
+    warnings.push(
+      `Text mentions ${FORBIDDEN_VNC_PORT} but websockify target is ${FILL_VNC_PORT} — OK if the mention is a "never use" comment.`,
+    );
+  } else if (findings.forbiddenPortMentions.length && !forbiddenTargets.length && !fillTargets.length && input.targetPort == null) {
+    errors.push(
+      `Live noVNC must not target TigerVNC port ${FORBIDDEN_VNC_PORT}. Use fill x11vnc localhost:${FILL_VNC_PORT} (DISPLAY=${FILL_DISPLAY}).`,
+    );
+  }
+
+  if (targetHost && !/^(127\.0\.0\.1|localhost|\[::1\])$/i.test(targetHost)) {
+    warnings.push(`websockify host is ${targetHost}; prefer localhost/127.0.0.1 for fill x11vnc.`);
+  }
+
+  if (display && display !== FILL_DISPLAY && display !== FORBIDDEN_DISPLAY) {
+    warnings.push(`Unexpected display ${display}; fill contract is ${FILL_DISPLAY}.`);
+  }
+
+  const ok = errors.length === 0;
+  return {
+    ok,
+    hardRule: `live noVNC → localhost:${FILL_VNC_PORT} / DISPLAY=${FILL_DISPLAY} (never ${FORBIDDEN_VNC_PORT} / ${FORBIDDEN_DISPLAY})`,
+    targetHost: targetHost ?? null,
+    targetPort: targetPort ?? null,
+    display: display ?? null,
+    errors,
+    warnings,
+    findings,
+  };
+}
+
+/**
+ * @param {string[]} argv
+ */
+export function parseNovncGuardArgs(argv) {
+  const args = { warnOnly: false, help: false, unitPath: "", text: "" };
+  for (let i = 0; i < argv.length; i += 1) {
+    const flag = argv[i];
+    const next = argv[i + 1];
+    if (flag === "--unit" || flag === "--file") {
+      args.unitPath = String(next ?? "").trim();
+      i += 1;
+    } else if (flag === "--text") {
+      args.text = String(next ?? "");
+      i += 1;
+    } else if (flag === "--target-port") {
+      args.targetPort = Number(next);
+      i += 1;
+    } else if (flag === "--target-host") {
+      args.targetHost = String(next ?? "").trim();
+      i += 1;
+    } else if (flag === "--display") {
+      args.display = String(next ?? "").trim();
+      i += 1;
+    } else if (flag === "--warn" || flag === "--warn-only") {
+      args.warnOnly = true;
+    } else if (flag === "--help" || flag === "-h") {
+      args.help = true;
+    } else if (flag.startsWith("-")) {
+      throw new Error(`Unknown flag: ${flag}`);
+    }
+  }
+  return args;
+}
+
+function printHelp() {
+  console.log(`Usage: node scripts/novnc-display-guard.mjs [options]
+
+Options:
+  --unit <path>         systemd unit (or any file) to scan for websockify targets
+  --text <string>       inspect inline command text
+  --target-port <port>  explicit VNC backend port
+  --target-host <host>  explicit VNC backend host
+  --display <dpy>       explicit DISPLAY (expect ${FILL_DISPLAY})
+  --warn                warn-only: print issues but exit 0 unless --target-port is forbidden
+
+Hard rule: websockify → localhost:${FILL_VNC_PORT} (fill DISPLAY=${FILL_DISPLAY}).
+Never ${FORBIDDEN_VNC_PORT} / TigerVNC ${FORBIDDEN_DISPLAY}.
+`);
+}
+
+async function main(argv = process.argv.slice(2)) {
+  let args;
+  try {
+    args = parseNovncGuardArgs(argv);
+  } catch (error) {
+    console.error(`[novnc-guard] ${error instanceof Error ? error.message : error}`);
+    process.exitCode = NOVNC_GUARD_EXIT.USAGE;
+    return;
+  }
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  let text = args.text || "";
+  if (args.unitPath) {
+    try {
+      text = await readFile(args.unitPath, "utf8");
+    } catch (error) {
+      console.error(`[novnc-guard] cannot read ${args.unitPath}: ${error instanceof Error ? error.message : error}`);
+      process.exitCode = NOVNC_GUARD_EXIT.FAIL;
+      return;
+    }
+  }
+
+  if (!text && args.targetPort == null && !args.display) {
+    // Default: check common agent-box unit path, else print rule + usage hint.
+    const exampleUnit = fileURLToPath(new URL("../references/agent-box/novnc.service.example", import.meta.url));
+    const defaults = [
+      "/etc/systemd/system/novnc.service",
+      "/etc/systemd/system/websockify.service",
+      exampleUnit,
+    ];
+    for (const candidate of defaults) {
+      try {
+        text = await readFile(candidate, "utf8");
+        console.error(`[novnc-guard] scanning ${candidate}`);
+        break;
+      } catch {
+        /* try next */
+      }
+    }
+  }
+
+  if (!text && args.targetPort == null) {
+    printHelp();
+    console.error(`[novnc-guard] provide --unit, --text, or --target-port`);
+    process.exitCode = NOVNC_GUARD_EXIT.USAGE;
+    return;
+  }
+
+  const result = evaluateNovncDisplayGuard({
+    text,
+    targetPort: args.targetPort,
+    targetHost: args.targetHost,
+    display: args.display,
+  });
+
+  console.log(JSON.stringify(result, null, 2));
+
+  if (!result.ok) {
+    for (const err of result.errors) console.error(`[novnc-guard] FAIL: ${err}`);
+    process.exitCode = args.warnOnly ? NOVNC_GUARD_EXIT.OK : NOVNC_GUARD_EXIT.FAIL;
+    return;
+  }
+  for (const warn of result.warnings) console.error(`[novnc-guard] WARN: ${warn}`);
+  console.error(`[novnc-guard] OK — ${result.hardRule}`);
+  process.exitCode = NOVNC_GUARD_EXIT.OK;
+}
+
+const isDirect = import.meta.url === pathToFileURL(process.argv[1] ?? "").href
+  || process.argv[1]?.endsWith("novnc-display-guard.mjs");
+
+if (isDirect) {
+  main().catch((error) => {
+    console.error(`[novnc-guard] ${error instanceof Error ? error.message : error}`);
+    process.exitCode = NOVNC_GUARD_EXIT.FAIL;
+  });
+}

package/job-application-agent/scripts/outreach-cli.mjs

@@ -0,0 +1,95 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { CloudStateClient, defaultCloudConfigPath } from './cloud-state-client.mjs';
+import { migrateLegacyStateDir, resolveStateDir } from './secret-store.mjs';
+import { mutateOutreach, readOutreach, OUTREACH_CAPABILITY } from './outreach-domain.mjs';
+import { privateOutreachWrite, withLocalOutreach, withOutreachLock } from './outreach-store.mjs';
+
+const READS = new Set(['policy-status', 'list', 'show', 'review']);
+const MUTATIONS = new Set(['policy-enable', 'policy-disable', 'assess', 'draft', 'handoff', 'record', 'suppress', 'clear']);
+async function readInput() {
+  let text = ''; for await (const chunk of process.stdin) { text += chunk; if (text.length > 32000) throw new Error('Outreach input too large'); }
+  try { return JSON.parse(text); } catch { throw new Error('Invalid outreach JSON'); }
+}
+async function downgradeGuard() {
+  const agentHome = process.env.JOB_APPLICATION_AGENT_HOME || join(homedir(), '.agents');
+  const path = join(agentHome, 'job-application-agent', 'install.json');
+  let config; try { config = JSON.parse(await readFile(path, 'utf8')); } catch (e) { if (e.code === 'ENOENT') return; throw e; }
+  config.requiredCapabilities = [...new Set([...(config.requiredCapabilities ?? []), OUTREACH_CAPABILITY])].sort();
+  await privateOutreachWrite(path, JSON.stringify(config, null, 2));
+}
+function fromSnapshot(snapshot, action, input) {
+  if (action === 'policy-status') return snapshot.policy;
+  if (action === 'review') return snapshot.review;
+  if (action === 'show') { const item = snapshot.items.find(i => i.id === input.id); if (!item) throw new Error('Opportunity not found'); return item; }
+  return { items: snapshot.items.map(({ content, events, ...item }) => item) };
+}
+
+export async function outreachCache(directory, binding, operation, { generation, snapshot } = {}) {
+  return withOutreachLock(directory, 'outreach-cache.lock', async () => {
+    const path = join(directory, 'outreach-cloud-cache.json');
+    let cache;
+    try { cache = JSON.parse(await readFile(path, 'utf8')); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (cache?.binding !== binding) cache = { binding, generation: 0, revision: -1 };
+    if (operation === 'invalidate') {
+      cache = { binding, generation: cache.generation + 1, revision: cache.revision };
+      await privateOutreachWrite(path, JSON.stringify(cache));
+    } else if (operation === 'write' && cache.generation === generation) {
+      // A lower revision may be a restored backend or a delayed response. Neither
+      // may retain older sensitive content; invalidate all in-flight writers too.
+      cache = snapshot.revision < cache.revision
+        ? { binding, generation: generation + 1, revision: -1 }
+        : { binding, generation, revision: snapshot.revision, cachedAt: new Date().toISOString(), snapshot };
+      await privateOutreachWrite(path, JSON.stringify(cache));
+    }
+    return cache;
+  });
+}
+
+export async function runOutreach(args, { input: suppliedInput, stateDirectory = resolveStateDir(), cloudClient, guard = downgradeGuard, migrate = migrateLegacyStateDir } = {}) {
+  let [action, value, rest, extra] = args;
+  if (action === 'policy') { action = `policy-${value}`; value = rest; rest = extra; }
+  const read = READS.has(action);
+  if ((!read && !MUTATIONS.has(action)) || rest !== undefined || (read ? (action !== 'show' && value !== undefined) || (action === 'show' && !value) : value !== '--stdin')) {
+    throw new Error('Usage: outreach policy status|enable --stdin|disable --stdin; outreach assess|draft|handoff|record|suppress|clear --stdin; outreach list|show <id>|review');
+  }
+  const input = read ? (action === 'show' ? { id: value } : {}) : suppliedInput ?? await readInput();
+  await migrate(stateDirectory);
+  const cloud = cloudClient ?? new CloudStateClient({ stateDir: stateDirectory, configPath: process.env.JOB_APPLICATION_AGENT_CLOUD_CONFIG ?? defaultCloudConfigPath() });
+  const config = await cloud.config(true);
+  let result;
+  if (config) {
+    if (config.version !== 2) throw new Error('Outreach requires cloud-state-v2');
+    const binding = createHash('sha256').update(`${config.url}:${config.token}`).digest('hex');
+    const { generation } = await outreachCache(stateDirectory, binding, read ? 'read' : 'invalidate');
+    try {
+      const status = await cloud.status();
+      if (!status.capabilities?.includes(OUTREACH_CAPABILITY)) throw new Error('Backend upgrade required: outreach-tracking-v1 is missing');
+      if (!read) result = await (await cloud.request('/v2/outreach/command', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ action, input }) })).json();
+      // Failure after a successful mutation must not disguise that committed result.
+      try {
+        const snapshot = await (await cloud.request('/v2/outreach/snapshot')).json();
+        await outreachCache(stateDirectory, binding, 'write', { generation, snapshot });
+        if (read) result = { ...fromSnapshot(snapshot, action, input), stale: false };
+      } catch (error) { if (read) throw error; result = { ...result, cacheRefreshed: false }; }
+    } catch (error) {
+      if (!read || !/^Cloud state unavailable:/.test(error.message)) throw error;
+      const cached = await outreachCache(stateDirectory, binding, 'read');
+      if (!cached.snapshot) throw error;
+      result = { ...fromSnapshot(cached.snapshot, action, input), stale: true, cachedAt: cached.cachedAt, warning: 'Offline cache may contain content cleared on another host; no mutations are allowed.' };
+    }
+  } else {
+    const context = { applications: [], outcomes: [] };
+    if ((action === 'assess' && input.applicationId) || action === 'handoff') {
+      for (const stream of ['applications', 'outcomes']) {
+        try { context[stream] = (await readFile(join(stateDirectory, `${stream}.ndjson`), 'utf8')).split('\n').filter(Boolean).map(row => JSON.parse(row)); }
+        catch (error) { if (error.code !== 'ENOENT') throw error; }
+      }
+    }
+    result = await withLocalOutreach(stateDirectory, state => read ? { result: readOutreach(state, action, input) } : mutateOutreach(state, action, input, { ...context, actor: 'local' }));
+  }
+  if (action === 'policy-enable') await guard();
+  return result;
+}